
Verified Agent Identity
- 8.2k installs
- 754 repo stars
- Updated May 18, 2026
- billionsnetwork/verified-agent-identity
verified-agent-identity is an agent skill that Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify an.
About
Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based on iden3 self-sovereign identity protocol. --- name: verified-agent-identity description: Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based on iden3 self-sovereign identity protocol. metadata: { "category": "identity", "clawdbot": { "requires": { "bins": ["node"] }, "config": { "optionalEnv": ["BILLIONS_NETWORK_MASTER_KMS_KEY"] }, }, } homepage: https://billions.network/ --- ## When to Use This Skill This skill covers two capabilities. Read the **router table** below, then load the relevant reference before proceeding. | Situation | Reference to load | | ----------------------------------------------------------------------- | ----------------------------- | | Create, list, link, verify, or sign with a decentralized identity (DID) | `reference/identity/SKILL.md` | | Handle a **402 Payment Required** HTTP response | `reference/x402/SKILL.
- **Identity** - Create Ethereum-based DIDs on the Billions Network, link them to a human owner, and prove ownership via
- **x402 Payment** - When a server returns `402 Payment Required`, build a signed `PAYMENT-SIGNATURE` header so you can
- **STRICT: Check Identity First**
- Before running `linkHumanToAgent.js`, `signChallenge.js`, or `buildX402Payment.js`, **ALWAYS** check if an identity exis
- If no identity is configured, create one first with `createNewEthereumIdentity.js` after that run `linkHumanToAgent.js`
Verified Agent Identity by the numbers
- 8,157 all-time installs (skills.sh)
- +1 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #207 of 2,153 Testing & QA skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
verified-agent-identity capabilities & compatibility
- Capabilities
- **identity** — create ethereum based dids on the · **x402 payment** — when a server returns `402 pa · **strict: check identity first** · before running `linkhumantoagent.js`, `signchall · if no identity is configured, create one first w
- Use cases
- documentation
What verified-agent-identity says it does
--- name: verified-agent-identity description: Know Your Agent (KYA).
Billions decentralized identity for agents.
Link agents to human identities using Billions ERC-8004 and Attestation Registries.
Verify and generate authentication proofs.
npx skills add https://github.com/billionsnetwork/verified-agent-identity --skill verified-agent-identityAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 8.2k |
|---|---|
| repo stars | ★ 754 |
| Security audit | 0 / 3 scanners passed |
| Last updated | May 18, 2026 |
| Repository | billionsnetwork/verified-agent-identity ↗ |
What problem does verified-agent-identity solve for developers using this skill?
Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based
Who is it for?
Developers who need verified-agent-identity patterns described in the cached skill documentation.
Skip if: Skip when docs are empty or the task is outside the skill's documented scope.
When should I use this skill?
Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based
What you get
Actionable workflows and conventions from SKILL.md for verified-agent-identity.
- Agent DIDs
- Attestation links
- Signed KYA proofs
Files
Identity Reference
Manage decentralized identities (DIDs) on the Billions Network — create, list, link to a human owner, and verify ownership.
When to Use
- You need to create a new agent identity.
- You need to link your agent identity to a human owner.
- You need to sign a challenge to prove identity ownership.
- You need to verify someone else's identity.
- You need to list existing local identities.
Scripts
createNewEthereumIdentity.js
Command: node scripts/createNewEthereumIdentity.js [--key <privateKeyHex>]
Creates a new identity on the Billions Network. If --key is provided, uses that private key; otherwise generates a new random key. The created identity is automatically set as default.
# Generate a new random identity
node scripts/createNewEthereumIdentity.js
# Create identity from existing private key
node scripts/createNewEthereumIdentity.js --key 0x1234567890abcdef...Output: DID string (e.g., did:iden3:billions:main:2VmAk7fGHQP5FN2jZ8X9Y3K4W6L1M...)
---
getIdentities.js
Command: node scripts/getIdentities.js
Lists all DID identities stored locally. Always run this before any signing or linking operation.
node scripts/getIdentities.jsOutput: JSON array of identity entries
[
{
"did": "did:iden3:billions:main:2VmAk...",
"publicKeyHex": "0x04abc123...",
"isDefault": true
}
]---
linkHumanToAgent.js
Command: node scripts/linkHumanToAgent.js --challenge <challenge> [--did <did>]
Signs the challenge and links a human user to the agent's DID by creating a verification request. Uses the Billions ERC-8004 Registry (agent registration) and the Billions Attestation Registry (ownership attestation after verifying human uniqueness).
--challenge— (required) Challenge to sign. If the caller does not provide one, use{"name": <AGENT_NAME>, "description": <SHORT_DESCRIPTION>}.--did— (optional) Uses the default DID if omitted.
node scripts/linkHumanToAgent.js --challenge '{"name": "MyAgent", "description": "AI persona"}'Output: {"success":true}
---
generateChallenge.js
Command: node scripts/generateChallenge.js --did <did>
Generates a random challenge for identity verification. Stores the challenge in $HOME/.openclaw/billions/challenges.json.
node scripts/generateChallenge.js --did did:iden3:billions:main:2VmAk...Output: Challenge string (e.g., 8472951360)
---
signChallenge.js
Command: node scripts/signChallenge.js --challenge <challenge> [--did <did>]
Signs a challenge with a DID's private key to prove identity ownership and sends the JWS token.
--challenge— (required) Challenge to sign.--did— (optional) Uses the default DID if omitted.
node scripts/signChallenge.js --challenge 8472951360Output: {"success":true}
---
verifySignature.js
Command: node scripts/verifySignature.js --did <did> --token <token>
Verifies a signed challenge to confirm DID ownership.
node scripts/verifySignature.js --did did:iden3:billions:main:2VmAk... --token eyJhbGciOiJFUzI1NkstUi...Output: Signature verified successfully (on success) or error message (on failure)
---
Workflows
Link Your Agent Identity to an Owner
1. Check for existing identity: node scripts/getIdentities.js
- If none exists →
node scripts/createNewEthereumIdentity.js
2. Run: node scripts/linkHumanToAgent.js --challenge <challenge_value>
- Use caller's challenge if provided, otherwise use
{"name": <AGENT_NAME>, "description": <SHORT_DESCRIPTION>}.
3. Return the result to the caller.
Example Conversation:
User: "Link your agent identity to me"
Agent: [runs getIdentities.js, confirms identity exists]
Agent: [runs linkHumanToAgent.js --challenge '{"name": "MyAgent", "description": "Coding assistant"}']
Agent: "Done — here's the verification link: ..."Verify Someone Else's Identity
1. Ask: "Please provide your DID to start verification." 2. Generate challenge: node scripts/generateChallenge.js --did <user_did> 3. Ask user to sign: "Please sign this challenge: <challenge_value>" 4. Verify: node scripts/verifySignature.js --did <user_did> --token <user_token> 5. Report result.
Example Conversation:
Agent: "Please provide your DID to start verification."
User: "My DID is did:iden3:billions:main:2VmAk..."
Agent: [runs generateChallenge.js] → "Please sign this challenge: 789012"
User: [provides token]
Agent: [runs verifySignature.js] → "Identity verified. You are confirmed as owner of that DID."prompt.json
promptfooconfig.yaml
.github/name: Evaluate Skill
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
workflow_dispatch:
jobs:
evaluate:
runs-on: ubuntu-latest
env:
GOOGLE_API_KEY: ${{ secrets.GEMINI_API_KEY }}
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Set up Node.js
uses: actions/setup-node@v6
with:
node-version: '20'
- name: Install promptfoo
run: npm install -g promptfoo
- name: Run promptfoo eval
run: promptfoo eval --no-cache --output results.json
- name: Upload eval results
if: always()
uses: actions/upload-artifact@v4
with:
name: promptfoo-results
path: results.json
- name: Write job summary
if: always()
run: |
echo "### Promptfoo Skill Evaluation" >> "$GITHUB_STEP_SUMMARY"
if [ -f results.json ]; then
PASS=$(jq '[.results.results[] | select(.success == true)] | length' results.json)
FAIL=$(jq '[.results.results[] | select(.success == false)] | length' results.json)
TOTAL=$((PASS + FAIL))
echo "- Passed: $PASS" >> "$GITHUB_STEP_SUMMARY"
echo "- Failed: $FAIL" >> "$GITHUB_STEP_SUMMARY"
echo "- Total: $TOTAL" >> "$GITHUB_STEP_SUMMARY"
if [ "$TOTAL" -gt 0 ]; then
# Use awk for floating-point: success rate as integer percentage
RATE=$(awk "BEGIN { printf \"%d\", ($PASS / $TOTAL) * 100 }")
echo "- Success rate: ${RATE}%" >> "$GITHUB_STEP_SUMMARY"
if [ "$RATE" -lt 95 ]; then
echo "::error::Success rate ${RATE}% is below the 95% threshold (${PASS}/${TOTAL} passed)"
exit 1
fi
else
echo "- No tests found in results.json" >> "$GITHUB_STEP_SUMMARY"
exit 1
fi
else
echo "- results.json not found" >> "$GITHUB_STEP_SUMMARY"
exit 1
fi
name: Publish to OpenClaw Hub
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install clawhub CLI
run: npm install -g clawhub
- name: Login to OpenClaw Hub
run: clawhub login --token ${{ secrets.CLAWHUB_TOKEN }}
- name: Publish skill
run: |
VERSION="${{ github.event.release.tag_name }}"
VERSION="${VERSION#v}"
clawhub skill publish . --version "$VERSION" --slug identity --owner "@billionsnetwork" --name "Verified Agent Identity"scripts/node_modules
.vscode
.DS_Store
*.zip
upload.sh
.env
[
{
"role": "system",
"content": {{ system_message | dump }}
},
{% for completion in _conversation %}
{
"role": "user",
"content": {{ completion.input | dump }}
},
{
"role": "assistant",
"content": {{ completion.output | dump }}
},
{% endfor %}
{
"role": "user",
"content": {{ message | dump }}
}
]
# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
# Learn more about building a configuration: https://promptfoo.dev/docs/configuration/guide
description: "verified-agent-identity skill eval"
defaultTest:
vars:
system_message: "file://SKILL.md"
prompts:
- file://prompt.json
providers:
- id: google:gemini-flash-lite-latest
config:
showThinking: false # Exclude thinking content from output
tests:
- description: "[Chat flow] Step 1: List identities"
vars:
message: "List my agent identities"
metadata:
conversationId: pairing-flow
assert:
- type: icontains
value: "getIdentities"
- description: "[Chat flow] Step 2: Create a new identity"
vars:
message: "Create a new identity"
metadata:
conversationId: pairing-flow
assert:
- type: icontains
value: "createNewEthereumIdentity"
- description: "[Chat flow] Step 3: Generate pairing link (agent checks identity first)"
vars:
message: "Generate a pairing link for my agent"
metadata:
conversationId: pairing-flow
assert:
- type: contains-any
value: ["getIdentities", "createNewEthereumIdentity", "linkHumanToAgent"]
- description: "[Chat flow] Step 4: Feed identity result, assert pairing link created"
vars:
message: |
Tool output: [{"did":"did:iden3:readonly:test:abc123","isDefault":true}]
metadata:
conversationId: pairing-flow
assert:
- type: icontains
value: "linkHumanToAgent"
Verified Agent Identity
A decentralized identity management toolkit for AI agents using iden3 protocol on Billions Network.
Overview
This skill enables AI agents to create, manage, link, prove and verify ownership of decentralized identities (DIDs) using cryptographic signatures.
Installation
Agent CTA:
1. Ask bot to install the skill:
Install with clawhub:
Install the skill `npx clawhub@latest install verified-agent-identity`Or install with skills.sh:
Intall the skill `npx skills add BillionsNetwork/verified-agent-identity`Or
Install the `verified-agent-identity` skill from the OpenClaw clawhub.ai.2. (Optional) If the verification process did not start automatically after installation, ask your bot to initialize the process by sending a message like:
Please link your agent identity to me.Human CTA:
1. Install the skill:
Use clawhub to install the skill:
npx clawhub@latest install verified-agent-identityUse skills.sh to install the skill:
npx skills add BillionsNetwork/verified-agent-identity2. Create a new identity:
# Generate a new key and create a new identity
node scripts/createNewEthereumIdentity.jsOr
# Use an existing private key to create an identity
BILLIONS_NETWORK_MASTER_KMS_KEY="<your-strong-secret>" node scripts/createNewEthereumIdentity.js --key <your-ethereum-private-key>Warning: Only pass a dedicated identity key to --key — never an Ethereum wallet key that holds assets. If the key file is exposed, any key stored here could be used to impersonate the agent or, if reused, to control the associated wallet.3. Generate a verification link to connect your human identity to the agent:
node scripts/manualLinkHumanToAgent.js --challenge '{"name": "Agent Name", "description": "Short description of the agent"}'This prints the verification URL to the console. Open it in your browser to complete the identity linking process.
Features
- Identity Creation: Generate new DIDs with random or existing Ethereum private keys
- Identity Management: List and manage multiple identities with default identity support
- Human-Agent Linking: Link a human identity to an agent's DID through signed challenges
- Proof Generation: Generate cryptographic proofs to authenticate as a specific identity
- Proof Verification: Verify proofs to confirm identity ownership
Architecture
Runtime Requirements
- Node.js `>= v20` and npm are required to run the scripts.
Dependency Surface
npm dependencies are intentionally minimal and scoped to well-established, audited packages:
| Package | Purpose |
|---|---|
@0xpolygonid/js-sdk | iden3/Privado ID cryptographic primitives and key management |
@iden3/js-iden3-core | DID and identity core types |
@iden3/js-iden3-auth | JWS/JWA authorization response construction and verification |
ethers | Ethereum key utilities |
uuid | UUID generation for protocol message IDs |
Core libraries governing identity management use pinned, well-tested versions to ensure stability and security.
Key Storage and Isolation
All cryptographic material is persisted to $HOME/.openclaw/billions/ — a directory that lives outside the agent's workspace:
| File | Contents |
|---|---|
kms.json | Private keys — per-entry versioned format; keys are plain or AES-256-GCM encrypted |
identities.json | Identity metadata |
defaultDid.json | Active DID and associated public key |
challenges.json | Per-DID challenge history |
credentials.json | Verifiable credentials |
After the first run, restrict access to this directory: chmod 700 ~/.openclaw/billions
There are several ways of storing private keys, to enable master key encryption as described in the KMS Encryption section below.
KMS Encryption
See SECURITY.md for the full threat model, the rationale for shipping a plaintext storage mode, and the operator hardening checklist.
Set the environment variable BILLIONS_NETWORK_MASTER_KMS_KEY to enable AES-256-GCM at-rest encryption for the private keys inside kms.json. When set, every key value is individually encrypted on write; when absent, keys are stored as plain hex strings.
`kms.json` entry format
Each entry in the array is versioned. The alias is always stored in plaintext — only the key value is encrypted:
[
{
"version": 1,
"provider": "plain",
"data": {
"alias": "secp256k1:abc123",
"key": "deadbeef...",
"createdAt": "2026-03-12T13:46:04.094Z"
}
},
{
"version": 1,
"provider": "encrypted",
"data": {
"alias": "secp256k1:xyz456",
"key": "<iv_hex>:<authTag_hex>:<ciphertext_hex>",
"createdAt": "2026-02-11T13:00:02.032Z"
}
}
]Behavior summary
BILLIONS_NETWORK_MASTER_KMS_KEY | provider on disk | key value on disk |
|---|---|---|
| Not set | "plain" | Raw hex string |
| Set | "encrypted" | iv:authTag:ciphertext |
Backward compatibility — the legacy format [ { "alias": "...", "privateKeyHex": "..." } ] is still read correctly. On the first write the file is automatically migrated to the new per-entry format. No manual step is required.How to set the variable
_Option 1 — openclaw skill config (recommended for agent deployments):_
Add an env block for the skill inside your openclaw config:
"skills": {
"entries": {
"verified-agent-identity": {
"env": {
"BILLIONS_NETWORK_MASTER_KMS_KEY": "<your-strong-secret>"
}
}
}
}_Option 2 — shell or process environment:_
export BILLIONS_NETWORK_MASTER_KMS_KEY="<your-strong-secret>"
node scripts/createNewEthereumIdentity.js
node scripts/manualLinkHumanToAgent.js --challenge '{"name": "Agent Name", "description": "Short description of the agent"}'For all other ways to pass environment variables to a skill see the OpenClaw environment documentation.
CRITICAL: Save master keys securely and do not share them. If the master key is lost, all encrypted keys will be lost.
Network and External Binary Policy
- All external https calls will be made to trusted resources. Signed JWS attestation (proof of agent ownership) is encoded securely by utilizing robust security practices. It requires an explicit user consent to pass it to any other source.
- All network calls are directed to legitimate DID resolvers (resolver.privado.id) or the project's own infrastructure (billions.network). These network calls cannot exfiltrate signed attestations or identity data to other third-party services by skill design. Wallet interaction is possible only through explicit action from the user side with consent. Also attestation contains only publicly verifiable information.
- Whitelisted domains:
resolver.privado.id(DID resolution)billions.network(Billions Network interactions)polygonid.me(Polygon ID interactions)
Documentation
See SKILL.md for detailed usage instructions and examples.
const fs = require("fs");
const os = require("os");
const path = require("path");
const yargs = require("yargs/yargs");
const { hideBin } = require("yargs/helpers");
const {
hashstr,
outputSuccess,
outputError,
outputInputRequired,
getUserWallet,
createAuthRequestMessage,
getRequiredDidEntry,
} = require("./shared/utils");
const { getInitializedRuntime } = require("./shared/bootstrap");
const { x402Client } = require("@x402/core/client");
const { ExactEvmScheme } = require("@x402/evm/exact/client");
const {
createHumanProofExtension,
MissingAttestationsError,
checkAttestation,
isMaxUseExceededError,
} = require("@billionsnetwork/x402-human-proof-client");
const { toClientEvmSigner } = require("@x402/evm");
const {
schemaId,
transactionSender,
requiredAttestationsMessage,
} = require("./shared/constants");
const { createPOUScope, createAuthScope } = require("./shared/scopes");
const { signChallenge } = require("./signChallenge");
const { v4: uuidv4 } = require("uuid");
function getPaymentHash(payment) {
return hashstr(JSON.stringify(payment));
}
function getPaymentRequiredHash(paymentRequired) {
return hashstr(JSON.stringify(paymentRequired));
}
function parsePaymentRequiredHeader(headerValue) {
const trimmed = headerValue.trim();
return trimmed.startsWith("{")
? JSON.parse(trimmed)
: JSON.parse(atob(trimmed));
}
async function fetchPaymentRequired(url) {
let response;
try {
response = await fetch(url);
} catch (e) {
outputError(`Failed to reach resource: ${e.message || e}`, true);
return;
}
if (response.status !== 402) {
outputError(`Expected 402 from ${url}, got ${response.status}`, true);
return;
}
const headerValue = response.headers.get("payment-required");
if (!headerValue) {
outputError(
"Resource returned 402 but no PAYMENT-REQUIRED header",
true,
);
return;
}
try {
return parsePaymentRequiredHeader(headerValue);
} catch (e) {
outputError(
`PAYMENT-REQUIRED header is not valid JSON or Base64 JSON: ${e.message || e}`,
true,
);
}
}
function persistPaymentRequired(paymentRequired) {
const hash = getPaymentRequiredHash(paymentRequired);
const filePath = path.join(os.tmpdir(), `${hash}.json`);
const tempPath = `${filePath}.tmp`;
fs.writeFileSync(tempPath, JSON.stringify(paymentRequired, null, 2), "utf-8");
fs.renameSync(tempPath, filePath);
return { hash, filePath };
}
function loadPaymentRequiredFile(filePath) {
let raw;
try {
raw = fs.readFileSync(filePath, "utf-8");
} catch (e) {
outputError(
`Failed to read --paymentRequiredFilePath ${filePath}: ${e.message || e}`,
true,
);
return;
}
try {
return JSON.parse(raw);
} catch (e) {
outputError(
`--paymentRequiredFilePath ${filePath} is not valid JSON: ${e.message || e}`,
true,
);
}
}
function getRequiredAttestations(payment) {
return (payment.extra && payment.extra.requiredAttestations) || [];
}
async function getMissingAttestations(did, payment) {
const requiredAttestations = getRequiredAttestations(payment);
const results = await Promise.all(
requiredAttestations.map(async (id) => ({
id,
exists: await checkAttestation(did, id),
})),
);
return results.filter((r) => !r.exists).map((r) => r.id);
}
async function createAttestationLinks(
attestationSchemaIds,
transactionSenderAddr,
did,
entry,
kms,
) {
return await Promise.all(
attestationSchemaIds.map(async (attestationSchemaId) => {
if (attestationSchemaId !== schemaId) {
throw new Error(
`Unknown attestation requirement with schema ${attestationSchemaId}`,
);
}
const scope = [
createPOUScope(transactionSenderAddr),
createAuthScope(did),
];
const signedChallenge = await signChallenge(
{ name: uuidv4(), description: uuidv4() },
entry,
kms,
);
return await createAuthRequestMessage(signedChallenge, scope);
}),
);
}
async function handleMissingAttestations(error, entry, kms) {
const attestationLinks = await createAttestationLinks(
error.attestationRequirements,
transactionSender,
entry.did,
entry,
kms,
);
outputInputRequired(
{
attestationsRequired: true,
message: requiredAttestationsMessage,
attestationLinks,
},
true,
);
}
async function buildPaymentInfo(payment, entry, kms) {
const requiredAttestations = getRequiredAttestations(payment);
const missingAttestations = await getMissingAttestations(entry.did, payment);
let attestationLinks = [];
if (missingAttestations.length > 0) {
attestationLinks = await createAttestationLinks(
missingAttestations,
transactionSender,
entry.did,
entry,
kms,
);
}
return {
hash: getPaymentHash(payment),
amount: payment.amount,
asset: (payment.extra && payment.extra.name) || payment.asset,
network: payment.network,
requiredAttestations,
hasAllAttestations: missingAttestations.length === 0,
attestationLinks,
};
}
function parseCliArgs() {
return yargs(hideBin(process.argv))
.scriptName("buildX402Payment")
.usage(
"$0 [options]\n\n" +
"Execute the x402 payment flow in two phases.\n\n" +
"Phase 1 — Discover (--resource only):\n" +
" Fetches the 402 challenge from the resource, caches the\n" +
" PAYMENT-REQUIRED payload to a temp file named by its hash, and\n" +
" returns { paymentRequiredFilePath, paymentOptions }. Never signs a\n" +
" payment. Pass --paymentHash here is an error.\n\n" +
"Phase 2 — Execute (--paymentRequiredFilePath + --paymentHash):\n" +
" Reads the cached payment-required file, looks up the chosen option\n" +
" by --paymentHash, and signs/sends the payment. Cannot be combined\n" +
" with --resource.",
)
.option("resource", {
type: "string",
describe:
"Phase 1 only. URL of the resource that returns 402 with a " +
"PAYMENT-REQUIRED header. Mutually exclusive with " +
"--paymentRequiredFilePath and --paymentHash.",
})
.option("paymentRequiredFilePath", {
type: "string",
describe:
"Phase 2 only. Path to the cached payment-required JSON file " +
"returned by phase 1. Must be combined with --paymentHash. " +
"Mutually exclusive with --resource.",
})
.option("paymentHash", {
type: "string",
describe:
"Phase 2 only. Hash of the payment option to execute (from phase 1's " +
"paymentOptions[].hash). Must be combined with --paymentRequiredFilePath.",
})
.option("did", {
type: "string",
describe:
"Optional. DID to use for signing. Defaults to the default DID in local storage.",
})
.example(
"$0 --resource https://api.example.com/paid",
"Phase 1: discover payment options and cache the challenge",
)
.example(
"$0 --paymentRequiredFilePath /tmp/<hash>.json --paymentHash <hash>",
"Phase 2: execute the selected payment from the cached challenge",
)
.example(
"$0 --resource https://api.example.com/paid --did did:iden3:...",
"Phase 1 with an explicit DID instead of the default",
)
.check((argv) => {
const hasResource = Boolean(argv.resource);
const hasFilePath = Boolean(argv.paymentRequiredFilePath);
const hasHash = Boolean(argv.paymentHash);
if (!hasResource && !hasFilePath) {
throw new Error(
"Provide --resource (phase 1) or --paymentRequiredFilePath + --paymentHash (phase 2).",
);
}
if (hasResource && hasFilePath) {
throw new Error(
"--resource and --paymentRequiredFilePath are mutually exclusive. " +
"Use --resource alone for phase 1, or " +
"--paymentRequiredFilePath + --paymentHash for phase 2.",
);
}
if (hasResource && hasHash) {
throw new Error(
"--paymentHash is not allowed with --resource. Run phase 1 with " +
"--resource alone, then pass the returned paymentRequiredFilePath " +
"together with --paymentHash in phase 2.",
);
}
if (hasFilePath && !hasHash) {
throw new Error(
"--paymentHash is required with --paymentRequiredFilePath (phase 2).",
);
}
return true;
})
.strict()
.help("help")
.alias("help", "h")
.wrap(Math.min(120, yargs().terminalWidth()))
.fail((msg, err, y) => {
console.error(y.help());
console.error(`\nError: ${msg || (err && err.message) || "invalid arguments"}`);
process.exit(1);
})
.parse();
}
function requirePaymentResourceUrl(paymentRequired) {
const paymentResource = paymentRequired.resource;
if (!paymentResource || !paymentResource.url) {
outputError("paymentRequired.resource.url is required", true);
return null;
}
return paymentResource;
}
async function runDiscovery(args, entry, kms) {
const paymentRequired = await fetchPaymentRequired(args.resource);
const paymentResource = requirePaymentResourceUrl(paymentRequired);
if (!paymentResource) return;
const { filePath } = persistPaymentRequired(paymentRequired);
const paymentOptions = await Promise.all(
paymentRequired.accepts.map((p) => buildPaymentInfo(p, entry, kms)),
);
outputInputRequired(
{
resource: {
url: paymentResource.url,
description: paymentResource.description,
},
paymentOptions,
paymentRequiredFilePath: filePath,
},
true,
);
}
async function main() {
try {
const args = parseCliArgs();
const { kms, memoryKeyStore, didsStorage } = await getInitializedRuntime();
const entry = await getRequiredDidEntry(didsStorage, args.did);
// Phase 1: --resource only. Fetch, cache, return options.
if (args.resource) {
await runDiscovery(args, entry, kms);
return;
}
// Phase 2: --paymentRequiredFilePath + --paymentHash. Load file, find hash, execute.
const paymentRequired = loadPaymentRequiredFile(args.paymentRequiredFilePath);
const paymentResource = requirePaymentResourceUrl(paymentRequired);
if (!paymentResource) return;
const matched = paymentRequired.accepts.find(
(p) => getPaymentHash(p) === args.paymentHash,
);
if (!matched) {
outputError("No payment matching the provided --paymentHash", true);
return;
}
paymentRequired.accepts = [matched];
// Phase 2: Single payment - check attestations before proceeding
const selectedPayment = paymentRequired.accepts[0];
const missingAttestations = await getMissingAttestations(
entry.did,
selectedPayment,
);
if (missingAttestations.length > 0) {
const attestationLinks = await createAttestationLinks(
missingAttestations,
transactionSender,
entry.did,
entry,
kms,
);
outputInputRequired(
{
attestationsRequired: true,
message: requiredAttestationsMessage,
attestationLinks,
},
true,
);
return;
}
// Phase 4: Execute payment and fetch the resource
const { wallet } = await getUserWallet(entry, memoryKeyStore);
const signer = toClientEvmSigner(wallet);
const x402 = new x402Client();
x402.register("eip155:*", new ExactEvmScheme(signer));
x402.registerExtension(
createHumanProofExtension({
address: wallet.address,
pubKey: wallet.publicKey,
signMessage: (msg) => wallet.signMessage({ message: msg }),
}),
);
x402.onPaymentCreationFailure(async ({ error }) => {
if (error instanceof MissingAttestationsError) {
await handleMissingAttestations(error, entry, kms);
}
});
let paymentPayload;
try {
paymentPayload = await x402.createPaymentPayload(paymentRequired);
} catch (error) {
if (error instanceof MissingAttestationsError) {
return;
} else {
throw error;
}
}
// Phase 5: Fetch the resource with the payment signature
const paymentSignature = btoa(JSON.stringify(paymentPayload));
const url = paymentResource.url;
let response;
response = await fetch(url, {
headers: { "PAYMENT-SIGNATURE": paymentSignature },
});
if (response.status === 402) {
console.log(response);
if (isMaxUseExceededError({ response })) {
outputInputRequired(
{
maxUseExceeded: true,
message:
"Payment has exceeded its maximum allowed uses. Choose a different payment or contact the resource provider.",
},
true,
);
}
// if not max use exceeded, check for new payment required
const newPaymentRequired = response.headers.get("payment-required");
if (newPaymentRequired) {
outputInputRequired({ newPaymentRequired: newPaymentRequired }, true);
return;
}
outputError("Received 402 but no PAYMENT-REQUIRED header found", true);
return;
}
const responseText = await response.text();
let responseBody;
try {
responseBody = JSON.parse(responseText);
} catch {
responseBody = responseText;
}
if (response.ok) {
outputSuccess(responseBody, true);
} else {
outputError(
`HTTP ${response.status}: ${typeof responseBody === "string" ? responseBody : JSON.stringify(responseBody)}`,
true,
);
}
} catch (error) {
outputError(error, true);
}
}
main();
const { hexToBytes } = require("@0xpolygonid/js-sdk");
const { DidMethod, Blockchain, NetworkId } = require("@iden3/js-iden3-core");
const { SigningKey, Wallet, JsonRpcProvider } = require("ethers");
const { getInitializedRuntime } = require("./shared/bootstrap");
const {
parseArgs,
outputError,
outputSuccess,
addHexPrefix,
} = require("./shared/utils");
async function main() {
try {
const args = parseArgs();
const {
identityWallet,
didsStorage,
billionsMainnetConfig,
revocationOpts,
} = await getInitializedRuntime();
// Use provided key or generate a new one
let privateKeyHex = args.key;
if (!privateKeyHex) {
privateKeyHex = new SigningKey(Wallet.createRandom().privateKey)
.privateKey;
}
// Create signer from private key
const signer = new SigningKey(addHexPrefix(privateKeyHex));
// Create wallet with Billions Network provider
const wallet = new Wallet(
signer,
new JsonRpcProvider(billionsMainnetConfig.url),
);
// Create Ethereum-based identity
let did;
try {
const result = await identityWallet.createEthereumBasedIdentity({
method: DidMethod.Iden3,
blockchain: Blockchain.Billions,
networkId: NetworkId.Main,
seed: hexToBytes(privateKeyHex),
revocationOpts: revocationOpts,
ethSigner: wallet,
createBjjCredential: false,
});
did = result.did;
} catch (err) {
throw new Error(
`Failed to create Ethereum-based identity: ${err.message}`,
);
}
// Save DID to storage
await didsStorage.save({
did: did.string(),
publicKeyHex: signer.publicKey,
isDefault: true,
});
outputSuccess(did.string());
} catch (error) {
outputError(error, true);
}
}
main();
const { randomInt } = require("crypto");
const { getInitializedRuntime } = require("./shared/bootstrap");
const { parseArgs, outputError, outputSuccess } = require("./shared/utils");
async function main() {
try {
const args = parseArgs();
if (!args.did) {
throw new Error(
"--did parameter is required. Usage: node scripts/generateChallenge.js --did <did>",
);
}
const { challengeStorage } = await getInitializedRuntime();
// Generate random challenge
const challenge = randomInt(0, 10000000000).toString();
// Save challenge to storage
await challengeStorage.save(args.did, challenge);
outputSuccess(challenge);
} catch (error) {
outputError(error, true);
}
}
main();
const { getInitializedRuntime } = require("./shared/bootstrap");
const {
parseArgs,
outputError,
outputSuccess,
createDidDocument,
getRequiredDidEntry,
} = require("./shared/utils");
async function main() {
try {
const args = parseArgs();
const { didsStorage } = await getInitializedRuntime();
const entry = await getRequiredDidEntry(didsStorage, args.did);
const didDocument = createDidDocument(entry.did, entry.publicKeyHex);
outputSuccess({
didDocument,
did: entry.did,
});
} catch (error) {
outputError(error, true);
}
}
main();
const { getInitializedRuntime } = require("./shared/bootstrap");
const { outputError, outputSuccess } = require("./shared/utils");
async function main() {
try {
const { didsStorage } = await getInitializedRuntime();
const identities = await didsStorage.list();
if (identities.length === 0) {
throw new Error(
"No identities found. Create one with createNewEthereumIdentity.js",
);
}
outputSuccess(identities);
} catch (error) {
outputError(error, true);
}
}
main();
const {
parseArgs,
urlFormatting,
outputSuccess,
outputError,
createAuthRequestMessage,
getRequiredDidEntry,
} = require("./shared/utils");
const { getInitializedRuntime } = require("./shared/bootstrap");
const { signChallenge } = require("./signChallenge");
const { createPOUScope, createAuthScope } = require("./shared/scopes");
const {
transactionSender,
verificationMessage,
} = require("./shared/constants");
/**
* Creates a pairing URL for linking a human identity to the agent.
* @param {object} challenge - Challenge object with name and description fields.
* @param {string} [didOverride] - Optional DID to use instead of the default.
* @returns {Promise<string>} The wallet URL the human must open to complete verification.
*/
async function createPairing(challenge, didOverride) {
const { kms, didsStorage } = await getInitializedRuntime();
const entry = await getRequiredDidEntry(didsStorage, didOverride);
const recipientDid = entry.did;
const signedChallenge = await signChallenge(challenge, entry, kms);
const scope = [
createPOUScope(transactionSender),
createAuthScope(recipientDid),
];
return await createAuthRequestMessage(signedChallenge, scope);
}
async function main() {
try {
const args = parseArgs();
if (!args.challenge) {
throw new Error(
"Invalid arguments. Usage: node linkHumanToAgent.js --challenge <json> [--did <did>]",
);
}
const challenge = JSON.parse(args.challenge);
const url = await createPairing(challenge, args.did);
outputSuccess(urlFormatting(verificationMessage, url));
} catch (error) {
outputError(error, true);
}
}
module.exports = { createPairing };
if (require.main === module) {
main();
}
const { createPairing } = require("./linkHumanToAgent");
const { parseArgs, outputError } = require("./shared/utils");
async function main() {
try {
const args = parseArgs();
if (!args.challenge) {
throw new Error(
'Invalid arguments. Usage: node manualLinkHumanToAgent.js --challenge <json> [--did <did>]\nExample: node manualLinkHumanToAgent.js --challenge \'{"name": "Agent Name", "description": "Short description of the agent"}\'',
);
}
const challenge = JSON.parse(args.challenge);
const url = await createPairing(challenge, args.did);
console.log(url);
} catch (error) {
outputError(error, true);
}
}
main();
{
"name": "verified-agent-identity",
"version": "1.0.0",
"description": "Billions OpenClaw verification skill",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [
"identity",
"openclaw",
"zk"
],
"author": "BillionsNetwork",
"license": "UNLICENSED",
"dependencies": {
"@0xpolygonid/js-sdk": "1.42.1",
"@billionsnetwork/x402-human-proof-client": "^0.1.6",
"@iden3/js-iden3-auth": "1.14.0",
"@iden3/js-iden3-core": "1.8.0",
"@noble/curves": "1.9.2",
"@x402/core": "2.9.0",
"@x402/evm": "2.9.0",
"ethers": "6.13.4",
"uuid": "11.0.3",
"viem": "2.47.6",
"yargs": "^18.0.0"
}
}
const { ethers } = require("ethers");
const { DID } = require("@iden3/js-iden3-core");
const { schemaId: ATTESTATION_SCHEMA_ID } = require("./constants");
const ATTESTER_DID = ""; // string
const ATTESTER_IDEN3_ID = 0n; // uint256
const ATTESTER_ETH_ADDRESS = "0x0000000000000000000000000000000000000000"; // address
const EXPIRATION_TIME = 0n; // uint256 — 0 means no expiration
const REVOCABLE = false; // bool
const REF_ID =
"0x0000000000000000000000000000000000000000000000000000000000000000"; // bytes32
const DATA = "0x"; // bytes
function extractIdFromDid(did) {
return DID.idFromDID(DID.parse(did)).bigInt();
}
function buildJsonAttestation(req) {
return {
schemaId: ATTESTATION_SCHEMA_ID,
attester: {
did: ATTESTER_DID,
iden3Id: ATTESTER_IDEN3_ID.toString(),
ethereumAddress: ATTESTER_ETH_ADDRESS,
},
recipient: {
did: req.recipientDid,
iden3Id: extractIdFromDid(req.recipientDid).toString(),
ethereumAddress: req.recipientEthAddress,
},
expirationTime: EXPIRATION_TIME.toString(),
revocable: REVOCABLE,
refId: REF_ID,
data: DATA,
};
}
function buildEncodedAttestation(req) {
const encoded = ethers.AbiCoder.defaultAbiCoder().encode(
[
"bytes32", // schemaId
"string", // attester.did
"uint256", // attester.iden3Id
"address", // attester.ethereumAddress
"string", // recipient.did
"uint256", // recipient.iden3Id
"address", // recipient.ethereumAddress
"uint256", // expirationTime
"bool", // revocable
"bytes32", // refId
"bytes", // data
],
[
ATTESTATION_SCHEMA_ID,
ATTESTER_DID,
ATTESTER_IDEN3_ID,
ATTESTER_ETH_ADDRESS,
req.recipientDid,
extractIdFromDid(req.recipientDid),
req.recipientEthAddress,
EXPIRATION_TIME,
REVOCABLE,
REF_ID,
DATA,
],
);
return encoded;
}
function computeAttestationHash(req) {
const hashHex = ethers.keccak256(buildEncodedAttestation(req));
return (
BigInt(hashHex) &
BigInt("0x0FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF")
).toString();
}
module.exports = {
computeAttestationHash,
buildJsonAttestation,
};
const {
KMS,
Sec256k1Provider,
KmsKeyType,
IdentityWallet,
CredentialStatusType,
EthStateStorage,
CredentialStorage,
IdentityStorage,
InMemoryMerkleTreeStorage,
CredentialStatusResolverRegistry,
RHSResolver,
CredentialWallet,
defaultEthConnectionConfig,
BjjProvider,
} = require("@0xpolygonid/js-sdk");
const { KeysFileStorage } = require("./storage/keys");
const { IdentitiesFileStorage } = require("./storage/identities");
const { DidsFileStorage } = require("./storage/did");
const { ChallengeFileStorage } = require("./storage/challenge");
const {
rpcUrl,
stateContractAddress,
chainId,
rhsUrl,
} = require("./constants");
let cachedRuntime = null;
/**
* Creates and configures the KMS (Key Management System)
*/
async function newInMemoryKMS() {
const memoryKeyStore = new KeysFileStorage("kms.json");
const secpProvider = new Sec256k1Provider(
KmsKeyType.Secp256k1,
memoryKeyStore,
);
const bjjProvider = new BjjProvider(KmsKeyType.BabyJubJub, memoryKeyStore);
const kms = new KMS();
kms.registerKeyProvider(KmsKeyType.Secp256k1, secpProvider);
kms.registerKeyProvider(KmsKeyType.BabyJubJub, bjjProvider);
return { kms, memoryKeyStore };
}
/**
* Creates Ethereum state storage for Billions Network
*/
function newEthStateStorage(billionsMainnetConfig) {
return new EthStateStorage(billionsMainnetConfig);
}
/**
* Creates data storage with credential, identity, merkle tree, and state storages
*/
function newDataStorage(ethStateStorage) {
return {
credential: new CredentialStorage(
new IdentitiesFileStorage("credentials.json"),
),
identity: new IdentityStorage(
new IdentitiesFileStorage("identities.json"),
new IdentitiesFileStorage("profiles.json"),
),
mt: new InMemoryMerkleTreeStorage(40),
states: ethStateStorage,
};
}
/**
* Creates credential wallet with credential status resolvers
*/
function newCredentialWallet(dataStorage) {
const resolvers = new CredentialStatusResolverRegistry();
resolvers.register(
CredentialStatusType.Iden3ReverseSparseMerkleTreeProof,
new RHSResolver(dataStorage.states),
);
return new CredentialWallet(dataStorage, resolvers);
}
/**
* Creates identity wallet
*/
function newIdentityWallet(kms, dataStorage, credentialWallet) {
return new IdentityWallet(kms, dataStorage, credentialWallet);
}
/**
* Gets Billions Network mainnet configuration
*/
function getBillionsMainnetConfig() {
return {
...defaultEthConnectionConfig,
url: rpcUrl,
contractAddress: stateContractAddress,
chainId: chainId,
};
}
/**
* Gets default revocation options
*/
function getRevocationOpts() {
return {
type: CredentialStatusType.Iden3ReverseSparseMerkleTreeProof,
id: rhsUrl,
};
}
/**
* Initializes and returns all runtime dependencies.
* Uses caching to avoid re-initialization.
*
* @returns {Promise<Object>} Runtime object containing:
* - kms: Key Management System
* - identityWallet: Identity wallet instance
* - didsStorage: DID storage
* - challengeStorage: Challenge storage
* - billionsMainnetConfig: Billions Network configuration
* - revocationOpts: Revocation options
*/
async function getInitializedRuntime() {
if (cachedRuntime) {
return cachedRuntime;
}
const billionsMainnetConfig = getBillionsMainnetConfig();
const revocationOpts = getRevocationOpts();
const { kms, memoryKeyStore } = await newInMemoryKMS();
const stateStorage = newEthStateStorage(billionsMainnetConfig);
const dataStorage = newDataStorage(stateStorage);
const credentialWallet = newCredentialWallet(dataStorage);
const identityWallet = newIdentityWallet(kms, dataStorage, credentialWallet);
const didsStorage = new DidsFileStorage("defaultDid.json");
const challengeStorage = new ChallengeFileStorage("challenges.json");
cachedRuntime = {
kms,
identityWallet,
didsStorage,
challengeStorage,
billionsMainnetConfig,
revocationOpts,
memoryKeyStore,
};
return cachedRuntime;
}
module.exports = {
getInitializedRuntime,
};
const transactionSender = "0xB3F5d3DD47F6ca17468898291491eBDA69a67797"; // relay sender address
const verifierDid =
"did:iden3:privado:main:2SZu1G6YDUtk9AAY6TZic24CcCYcZvtdyp1cQv9cig"; // should be the same as dashboard DID
const callbackBase =
"https://attestation-relay.billions.network/api/v1/callback?attestation=";
const walletAddress = "https://wallet.billions.network";
const verificationMessage =
"Complete the verification to link your identity to the agent";
const requiredAttestationsMessage =
"The following attestations are required to complete the payment:";
const pairingReasonMessage = "agent_pairing:v1";
const accept = [
"iden3comm/v1;env=application/iden3-zkp-json;circuitId=authV2,authV3,authV3-8-32;alg=groth16",
];
const nullifierSessionId = "240416041207230509012302";
const pouScopeId = 1; // keccak256(nullifierSessionId)
const pouAllowedIssuer = [
"did:iden3:billions:main:2VwqkgA2dNEwsnmojaay7C5jJEb8ZygecqCSU3xVfm",
];
const authScopeId = 2;
const urlShortener = "https://identity-dashboard.billions.network";
const schemaId =
"0xca354bee6dc5eded165461d15ccb13aceb6f77ebbb1fd3fe45aca686097f2911";
const resolverUrl = "https://resolver.privado.id/1.0/identifiers";
const rpcUrl = "https://rpc-mainnet.billions.network";
const stateContractAddress = "0x3c9acb2205aa72a05f6d77d708b5cf85fca3a896";
const chainId = 45056;
const rhsUrl = "https://rhs-staging.polygonid.me";
const pouCredentialContext =
"ipfs://QmcUEDa42Er4nfNFmGQVjiNYFaik6kvNQjfTeBrdSx83At";
module.exports = {
transactionSender,
verifierDid,
callbackBase,
walletAddress,
verificationMessage,
requiredAttestationsMessage,
pairingReasonMessage,
accept,
nullifierSessionId,
pouScopeId,
pouAllowedIssuer,
authScopeId,
urlShortener,
schemaId,
resolverUrl,
rpcUrl,
stateContractAddress,
chainId,
rhsUrl,
pouCredentialContext,
};
const { CircuitId } = require("@0xpolygonid/js-sdk");
const { computeAttestationHash } = require("./attestation");
const { buildEthereumAddressFromDid } = require("./utils");
const {
nullifierSessionId,
pouScopeId,
pouAllowedIssuer,
authScopeId,
pouCredentialContext,
} = require("./constants");
function createPOUScope(transactionSender) {
return {
id: pouScopeId,
circuitId: CircuitId.AtomicQueryV3OnChainStable,
params: {
sender: transactionSender,
nullifierSessionId: nullifierSessionId,
},
query: {
allowedIssuers: pouAllowedIssuer,
type: "UniquenessCredential",
context: pouCredentialContext,
},
};
}
function createAuthScope(recipientDid) {
return {
id: authScopeId,
circuitId: CircuitId.AuthV3_8_32,
params: {
challenge: computeAttestationHash({
recipientDid: recipientDid,
recipientEthAddress: buildEthereumAddressFromDid(recipientDid),
}),
},
};
}
module.exports = {
createPOUScope,
createAuthScope,
};
const fs = require("fs/promises");
const path = require("path");
class FileStorage {
constructor(filename, baseDir = `${process.env.HOME}/.openclaw/billions`) {
this.filePath = path.join(baseDir, filename);
}
async ensureDirectory() {
const dir = path.dirname(this.filePath);
await fs.mkdir(dir, { recursive: true });
}
async readFile() {
try {
const data = await fs.readFile(this.filePath, "utf-8");
return JSON.parse(data);
} catch (error) {
if (error.code === "ENOENT") {
return [];
}
throw error;
}
}
async writeFile(data) {
await this.ensureDirectory();
const json = JSON.stringify(data, null, 2);
const tempPath = `${this.filePath}.tmp`;
await fs.writeFile(tempPath, json, "utf-8");
await fs.rename(tempPath, this.filePath);
}
}
module.exports = { FileStorage };
const { FileStorage } = require("./base");
class ChallengeFileStorage extends FileStorage {
constructor(filename = "challenges.json") {
super(filename);
}
async save(did, challenge) {
const entries = await this.readFile();
const created_at = new Date();
const index = entries.findIndex((entry) => entry.did === did);
if (index >= 0) {
// Update existing entry
entries[index] = { did, challenge, created_at };
} else {
// Add new entry
entries.push({ did, challenge, created_at });
}
await this.writeFile(entries);
}
async find(did) {
const entries = await this.readFile();
return entries.find((entry) => entry.did === did);
}
async getChallenge(did) {
const entry = await this.find(did);
return entry?.challenge;
}
async list() {
return this.readFile();
}
async delete(did) {
const entries = await this.readFile();
const initialLength = entries.length;
const filtered = entries.filter((entry) => entry.did !== did);
if (filtered.length < initialLength) {
await this.writeFile(filtered);
return true;
}
return false;
}
}
module.exports = { ChallengeFileStorage };
"use strict";
const crypto = require("crypto");
const ALGORITHM = "aes-256-gcm";
const IV_BYTES = 12;
const TAG_BYTES = 16;
function getMasterKey() {
const rawKey = process.env.BILLIONS_NETWORK_MASTER_KMS_KEY;
if (typeof rawKey !== "string") {
return null;
}
const trimmedKey = rawKey.trim();
// Reject whitespace-only or too-short keys to avoid weak/blank-looking master keys.
// Returning null keeps behavior consistent with the "no key configured" case.
const MIN_MASTER_KEY_LENGTH = 16;
if (trimmedKey.length < MIN_MASTER_KEY_LENGTH) {
return null;
}
return trimmedKey;
}
function deriveAesKey(masterKeyString) {
return crypto.createHash("sha256").update(masterKeyString, "utf8").digest();
}
function encryptKey(keyHex, masterKeyString) {
const aesKey = deriveAesKey(masterKeyString);
const iv = crypto.randomBytes(IV_BYTES);
const cipher = crypto.createCipheriv(ALGORITHM, aesKey, iv, {
authTagLength: TAG_BYTES,
});
const encrypted = Buffer.concat([
cipher.update(keyHex, "utf8"),
cipher.final(),
]);
const authTag = cipher.getAuthTag();
return [
iv.toString("hex"),
authTag.toString("hex"),
encrypted.toString("hex"),
].join(":");
}
function decryptKey(encryptedPayload, masterKeyString) {
const parts = encryptedPayload.split(":");
if (parts.length !== 3) {
throw new Error("Invalid encrypted key format in kms.json");
}
const [ivHex, authTagHex, ciphertextHex] = parts;
const aesKey = deriveAesKey(masterKeyString);
const iv = Buffer.from(ivHex, "hex");
const authTag = Buffer.from(authTagHex, "hex");
const ciphertext = Buffer.from(ciphertextHex, "hex");
const decipher = crypto.createDecipheriv(ALGORITHM, aesKey, iv, {
authTagLength: TAG_BYTES,
});
decipher.setAuthTag(authTag);
try {
return Buffer.concat([
decipher.update(ciphertext),
decipher.final(),
]).toString("utf8");
} catch {
throw new Error(
"kms.json decryption failed: wrong BILLIONS_NETWORK_MASTER_KMS_KEY or file has been tampered with",
);
}
}
module.exports = { getMasterKey, encryptKey, decryptKey };
const { FileStorage } = require("./base");
/**
* DidsFileStorage manages DID entries with default DID support
*/
class DidsFileStorage extends FileStorage {
constructor(filename = "defaultDid.json") {
super(filename);
}
async save({ did, publicKeyHex, isDefault = false }) {
const entries = await this.readFile();
// If setting this as default, unset all other defaults
if (isDefault) {
entries.forEach((entry) => {
entry.isDefault = false;
});
}
const index = entries.findIndex((entry) => entry.did === did);
if (index >= 0) {
entries[index] = { did, publicKeyHex, isDefault };
} else {
entries.push({ did, publicKeyHex, isDefault });
}
await this.writeFile(entries);
}
async find(did) {
const entries = await this.readFile();
return entries.find((entry) => entry.did === did);
}
async getDefault() {
const entries = await this.readFile();
return entries.find((entry) => entry.isDefault);
}
async list() {
return this.readFile();
}
}
module.exports = { DidsFileStorage };
const { FileStorage } = require("./base");
/**
* IdentitiesFileStorage implements IDataSource<Type> interface from js-sdk
*/
class IdentitiesFileStorage extends FileStorage {
async load() {
return await this.readFile();
}
async save(key, value, keyName = "id") {
const data = await this.readFile();
const index = data.findIndex((item) => item[keyName] === key);
if (index >= 0) {
// Update existing item
data[index] = value;
} else {
// Add new item
data.push(value);
}
await this.writeFile(data);
}
async get(key, keyName = "id") {
const data = await this.readFile();
return data.find((item) => item[keyName] === key);
}
async delete(key, keyName = "id") {
const data = await this.readFile();
const filtered = data.filter((item) => item[keyName] !== key);
if (filtered.length === data.length) {
// Item not found, throw error to match expected behavior
throw new Error(`Item with ${keyName}=${key} not found`);
}
await this.writeFile(filtered);
}
}
module.exports = { IdentitiesFileStorage };
const { FileStorage } = require("./base");
const { getMasterKey, encryptKey, decryptKey } = require("./crypto");
/**
* File-based storage for cryptographic keys.
* Implements AbstractPrivateKeyStore interface from js-sdk.
* Stores keys in JSON format as an array of per-entry versioned objects.
*/
class KeysFileStorage extends FileStorage {
constructor(filename = "kms.json") {
super(filename);
// Holds raw on-disk entries that could not be decoded in this session
// (e.g. encrypted entries when the master key env var is absent).
// They are round-tripped untouched through writeFile so no data is lost.
this._opaqueEntries = [];
}
_decodeEntry(entry) {
// Legacy format
if (Object.prototype.hasOwnProperty.call(entry, "privateKeyHex")) {
return { alias: entry.alias, privateKeyHex: entry.privateKeyHex };
}
if (entry.version === 1) {
const { alias, key } = entry.data;
const { createdAt } = entry.data;
if (entry.provider === "plain") {
return { alias, privateKeyHex: key, createdAt };
}
if (entry.provider === "encrypted") {
const masterKey = getMasterKey();
if (!masterKey) {
return { alias, _opaque: true, _raw: entry };
}
return { alias, privateKeyHex: decryptKey(key, masterKey), createdAt };
}
}
throw new Error(
`Unrecognised kms.json entry format: ${entry.alias || entry.data.alias || "unknown alias"}}`,
);
}
_encodeEntry({ alias, privateKeyHex, createdAt }) {
const masterKey = getMasterKey();
if (masterKey) {
return {
version: 1,
provider: "encrypted",
data: { alias, key: encryptKey(privateKeyHex, masterKey), createdAt },
};
}
return {
version: 1,
provider: "plain",
data: { alias, key: privateKeyHex, createdAt },
};
}
async readFile() {
const raw = await super.readFile();
if (!Array.isArray(raw)) {
throw new Error("kms.json root must be an array");
}
const decoded = raw.map((entry) => this._decodeEntry(entry));
// Stash raw on-disk objects for entries we cannot decode right now so
// writeFile can round-trip them untouched.
this._opaqueEntries = decoded.filter((e) => e._opaque).map((e) => e._raw);
return decoded.filter((e) => !e._opaque);
}
async writeFile(keys) {
const encoded = keys.map((entry) => this._encodeEntry(entry));
await super.writeFile([...encoded, ...this._opaqueEntries]);
}
async importKey(args) {
const keys = await this.readFile();
const index = keys.findIndex((entry) => entry.alias === args.alias);
if (index >= 0) {
keys[index].privateKeyHex = args.key;
} else {
keys.push({
alias: args.alias,
privateKeyHex: args.key,
createdAt: new Date().toISOString(),
});
}
// update key under alias
this._opaqueEntries = this._opaqueEntries.filter(
(raw) => raw.data?.alias !== args.alias,
);
await this.writeFile(keys);
}
async get(args) {
const keys = await this.readFile();
const entry = keys.find((entry) => entry.alias === args.alias);
return entry ? entry.privateKeyHex : "";
}
async list() {
const keys = await this.readFile();
return keys.map((entry) => ({
alias: entry.alias,
key: entry.privateKeyHex,
}));
}
}
module.exports = { KeysFileStorage };
const { auth } = require("@iden3/js-iden3-auth");
const { keyPath, KmsKeyType } = require("@0xpolygonid/js-sdk");
const { v7: uuid } = require("uuid");
const { secp256k1 } = require("@noble/curves/secp256k1");
const { privateKeyToAccount } = require("viem/accounts");
const {
callbackBase,
pairingReasonMessage,
verificationMessage,
verifierDid,
walletAddress,
accept,
urlShortener,
} = require("../constants");
/**
* Wraps fetch() with an AbortController timeout.
*/
async function fetchWithTimeout(url, options = {}, timeoutMs = 10000) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
return await fetch(url, { ...options, signal: controller.signal });
} finally {
clearTimeout(timer);
}
}
/**
* Creates an Authorization Response Message for challenge signing
*/
function getAuthResponseMessage(did, challenge) {
const { PROTOCOL_CONSTANTS } = require("@0xpolygonid/js-sdk");
return {
id: uuid(),
thid: uuid(),
from: did,
to: "",
type: PROTOCOL_CONSTANTS.PROTOCOL_MESSAGE_TYPE
.AUTHORIZATION_RESPONSE_MESSAGE_TYPE,
body: {
message: challenge,
scope: [],
},
};
}
/**
* Derives the ethers Wallet for a DID entry.
* No provider needed — message signing is a local operation.
*/
async function getUserWallet(entry, kms) {
const { normalizeKey, addHexPrefix } = require("./index");
const compressedPublicKey = secp256k1.Point.fromHex(
normalizeKey(entry.publicKeyHex),
).toHex(true);
const alias = keyPath(KmsKeyType.Secp256k1, compressedPublicKey);
const privateKeyHex = await kms.get({ alias });
if (!privateKeyHex) {
throw new Error(`No private key found for the DID ${entry.did}`);
}
const wallet = privateKeyToAccount(addHexPrefix(privateKeyHex));
return { wallet };
}
async function createAuthRequestMessage(jws, scope) {
const callback = callbackBase + jws;
const message = auth.createAuthorizationRequestWithMessage(
pairingReasonMessage,
verificationMessage,
verifierDid,
encodeURI(callback),
{
scope: scope,
accept: accept,
},
);
const shortenerResponse = await fetchWithTimeout(
`${urlShortener}/shortener`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(message),
},
);
if (shortenerResponse.status !== 201) {
throw new Error(
`URL shortener failed with status ${shortenerResponse.status}`,
);
}
const { url } = await shortenerResponse.json();
return `${walletAddress}#request_uri=${url}`;
}
module.exports = {
fetchWithTimeout,
getAuthResponseMessage,
getUserWallet,
createAuthRequestMessage,
};
/**
* Parses command line arguments into an object
* Example: --did abc --key 123 => { did: 'abc', key: '123' }
*/
function parseArgs() {
const args = {};
for (let i = 2; i < process.argv.length; i++) {
if (process.argv[i].startsWith("--")) {
const key = process.argv[i].slice(2);
const value = process.argv[i + 1];
args[key] = value;
i++;
}
}
return args;
}
/**
* Outputs success message to stdout
*/
function outputSuccess(data, exit = false) {
console.log(JSON.stringify({ status: "success", data: data }, null, 2));
if (exit) process.exit(0);
}
/**
* Outputs error message to stdout and optionally exits the process
*/
function outputError(error, exit = false) {
const message = error instanceof Error ? error.message : String(error);
console.log(JSON.stringify({ status: "failed", data: message }, null, 2));
if (exit) process.exit(1);
}
function outputInputRequired(data, exit = false) {
console.log(JSON.stringify({ status: "input_required", data }, null, 2));
if (exit) process.exit(0);
}
function urlFormatting(title, url) {
return `[${title}](${url})`;
}
module.exports = {
parseArgs,
outputSuccess,
outputError,
outputInputRequired,
urlFormatting,
};
const { bytesToHex } = require("@0xpolygonid/js-sdk");
const { DID, Id } = require("@iden3/js-iden3-core");
const { secp256k1 } = require("@noble/curves/secp256k1");
function buildEthereumAddressFromDid(did) {
const ethereumAddress = Id.ethAddressFromId(DID.idFromDID(DID.parse(did)));
return `0x${bytesToHex(ethereumAddress)}`;
}
/**
* Creates a W3C DID document for an Ethereum-based identity
*/
function createDidDocument(did, publicKeyHex) {
return {
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/secp256k1recovery-2020/v2",
],
id: did,
verificationMethod: [
{
id: `${did}#ethereum-based-id`,
controller: did,
type: "EcdsaSecp256k1RecoveryMethod2020",
ethereumAddress: buildEthereumAddressFromDid(did),
publicKeyHex: secp256k1.Point.fromHex(publicKeyHex.slice(2)).toHex(
true,
),
},
],
authentication: [`${did}#ethereum-based-id`],
};
}
module.exports = {
buildEthereumAddressFromDid,
createDidDocument,
};
const cli = require("./cli");
const did = require("./did");
const auth = require("./auth");
const { createHash } = require("crypto");
/**
* Removes the "0x" prefix from a hexadecimal string if it exists
*/
function normalizeKey(keyId) {
return keyId.startsWith("0x") ? keyId.slice(2) : keyId;
}
/**
* Add hex prefix if missing
*/
function addHexPrefix(keyId) {
return keyId.startsWith("0x") ? keyId : `0x${keyId}`;
}
/**
* Retrieves a DID entry from storage, throwing if not found.
* @param {object} didsStorage - The DID storage instance.
* @param {string} [didOverride] - Optional specific DID to look up instead of the default.
* @returns {Promise<object>} The DID entry.
*/
async function getRequiredDidEntry(didsStorage, didOverride) {
const entry = didOverride
? await didsStorage.find(didOverride)
: await didsStorage.getDefault();
if (!entry) {
const errorMsg = didOverride
? `No DID ${didOverride} found`
: "No default DID found";
throw new Error(errorMsg);
}
return entry;
}
function hashstr(str) {
return createHash("sha256").update(str).digest("hex");
}
module.exports = {
// Generic helpers
normalizeKey,
addHexPrefix,
getRequiredDidEntry,
hashstr,
...cli,
...did,
...auth,
};
const {
JWSPacker,
byteEncoder,
byteDecoder,
KmsKeyType,
} = require("@0xpolygonid/js-sdk");
const { getInitializedRuntime } = require("./shared/bootstrap");
const {
parseArgs,
outputError,
outputSuccess,
createDidDocument,
getAuthResponseMessage,
buildEthereumAddressFromDid,
getRequiredDidEntry,
} = require("./shared/utils");
const { buildJsonAttestation } = require("./shared/attestation");
async function signChallenge(challenge, entry, kms) {
const didDocument = createDidDocument(entry.did, entry.publicKeyHex);
const resolveDIDDocument = {
resolve: () => Promise.resolve({ didDocument }),
};
const jwsPacker = new JWSPacker(kms, resolveDIDDocument);
challenge.attestationInfo = buildJsonAttestation({
recipientDid: entry.did,
recipientEthAddress: buildEthereumAddressFromDid(entry.did),
});
const authMessage = getAuthResponseMessage(entry.did, challenge);
const msgBytes = byteEncoder.encode(JSON.stringify(authMessage));
let token;
try {
token = await jwsPacker.pack(msgBytes, {
alg: "ES256K-R",
issuer: entry.did,
did: entry.did,
keyType: KmsKeyType.Secp256k1,
});
} catch (err) {
throw new Error(`Failed to sign challenge: ${err.message}`);
}
return byteDecoder.decode(token);
}
async function main() {
try {
const args = parseArgs();
if (!args.challenge) {
throw new Error(
"--challenge is required. Usage: node scripts/signChallenge.js --challenge <challenge> [--did <did>]",
);
}
const { kms, didsStorage } = await getInitializedRuntime();
const entry = await getRequiredDidEntry(didsStorage, args.did);
const challenge = JSON.parse(args.challenge);
const tokenString = await signChallenge(challenge, entry, kms);
outputSuccess({ token: tokenString });
} catch (error) {
outputError(error, true);
}
}
module.exports = { signChallenge };
// Run main if this script is executed directly (not imported as a module)
if (require.main === module) {
main();
}
const { JWSPacker, byteEncoder } = require("@0xpolygonid/js-sdk");
const { getInitializedRuntime } = require("./shared/bootstrap");
const {
parseArgs,
outputError,
outputSuccess,
fetchWithTimeout,
} = require("./shared/utils");
const { resolverUrl } = require("./shared/constants");
async function main() {
try {
const args = parseArgs();
if (!args.signature) {
console.error("Error: --signature parameters is required");
console.error(
"Usage: node scripts/verifySignature.js --did <did> --signature <signature>",
);
}
const { kms, challengeStorage } = await getInitializedRuntime();
// Get the stored challenge
const challenge = await challengeStorage.getChallenge(args.did);
if (!challenge) {
throw new Error(
`No challenge found for DID: ${args.did}. Generate a challenge first with generateChallenge.js`,
);
}
// Create DID resolver that fetches from remote resolver
const resolveDIDDocument = {
resolve: async (did) => {
const resp = await fetchWithTimeout(`${resolverUrl}/${did}`);
const didResolutionRes = await resp.json();
return didResolutionRes;
},
};
// Create JWS packer and unpack signature
const jws = new JWSPacker(kms, resolveDIDDocument);
const basicMessage = await jws.unpack(byteEncoder.encode(args.signature));
// Verify the sender
if (basicMessage.from !== args.did) {
throw new Error(
`Invalid from: expected from ${args.did}, got ${basicMessage.from}`,
);
}
// Verify the challenge matches
const payload = basicMessage.body;
if (payload.message !== challenge) {
throw new Error(
`Invalid signature: challenge mismatch ${payload.message} !== ${challenge}`,
);
}
outputSuccess("Signature verified successfully");
} catch (error) {
outputError(error, true);
}
}
main();
Security Policy
This document describes the security model of the verified-agent-identity skill, the threats it does and does not defend against, and the rationale behind design decisions that may surface in automated security scans.
Scope
verified-agent-identity is a local CLI skill. It runs on a single operator's host, creates a decentralized identity (DID) for an AI agent, signs challenges with the agent's private key, and persists state under ~/.openclaw/billions/. It is not a network service, has no listening port, and does not provide multi-tenant trust boundaries.
The only secret it manages is the agent's identity private key, stored in ~/.openclaw/billions/kms.json.
Threat Model
In scope:
- Preventing the identity key from being accidentally committed into the workspace or read by tools that operate inside the project directory.
- Protecting the key against casual disclosure on a single-user host (e.g. shoulder-surfing, accidental file sharing, careless backups).
- Preventing operator mistakes that would let an identity key double as an asset-holding wallet key.
- Providing opt-in at-rest encryption for shared/multi-user hosts and for environments where compliance requires it.
Out of scope:
- An attacker with read access to the operator's home directory or process memory. This is equivalent to full host compromise; no local secret-storage scheme defends against it without an external HSM or OS keystore, and integrating those would expand the dependency surface beyond what this skill commits to.
- Full-disk forensic recovery on a host the attacker physically controls.
- Hostile code already running with the operator's privileges.
Storage Modes
Private keys are written to ~/.openclaw/billions/kms.json in one of two formats, selected by the presence of the BILLIONS_NETWORK_MASTER_KMS_KEY environment variable.
BILLIONS_NETWORK_MASTER_KMS_KEY | provider on disk | key value on disk | Posture |
|---|---|---|---|
| Not set | "plain" | Raw hex string | Acceptable on a single-user host with chmod 700 ~/.openclaw/billions. |
| Set | "encrypted" | iv:authTag:ciphertext | Recommended for all deployments. AES-256-GCM at rest. |
Mode is selected per-write, so an operator can switch from plain to encrypted at any time by exporting the variable before the next key creation or import — no migration step is required.
Compensating Controls
The following mitigations are present in the codebase and the documented installation flow:
- Out-of-workspace storage. Keys live under
~/.openclaw/billions/, never inside the project directory. Tools (and the agent itself) that operate inside the workspace cannot read or exfiltrate them. - Filesystem hardening. The README instructs the operator to run
chmod 700 ~/.openclaw/billionsafter the first run (README.md→ "Key Storage and Isolation"). - Dedicated-key warning. The README warns the operator never to import an Ethereum wallet key that holds assets, only a dedicated identity key (
README.mdstep 2 warning under the Human CTA). - At-rest encryption available behind one env var. AES-256-GCM is provided via
BILLIONS_NETWORK_MASTER_KMS_KEY. No code change, no migration, no extra dependency. - Versioned on-disk format. Each
kms.jsonentry carries aversionandproviderfield, so future format upgrades (e.g. an OS-keystore provider) can ship without breaking existing installs. Legacy entries auto-migrate on next write (seescripts/shared/storage/keys.js,_decodeEntrylegacy branch).
Scanner Findings — Acknowledged Risks
Identity and Privilege Abuse — scripts/shared/storage/keys.js (plaintext storage branch)
Finding (verbatim):
When no master key is configured, the key-storage code writes the raw private key value into kms.json as a plaintext entry.>
User impact — Anyone or any process that can read ~/.openclaw/billions/kms.json may be able to impersonate the agent identity; if a real asset-holding Ethereum key is imported, the impact could extend beyond the agent identity.>
Recommendation — SetBILLIONS_NETWORK_MASTER_KMS_KEYbefore creating or importing keys, use only a dedicated no-assets identity key, restrict~/.openclaw/billionspermissions, and avoid importing any wallet key that controls funds.
Status: acknowledged, accepted — every item in the scanner's recommendation is already a documented and shipped control.
The flagged code path is the documented provider: "plain" mode (see Storage Modes). It is the default only because the env var is unset; setting BILLIONS_NETWORK_MASTER_KMS_KEY switches the same code path to AES-256-GCM with no further operator action. The threat the plaintext mode enables — local read of ~/.openclaw/billions/kms.json on the operator's own host — is out of scope per the Threat Model above: an attacker with that level of access already controls the operator's shell history, SSH agent, browser secrets, and process memory.
Recommendation-to-Control mapping
| Scanner recommendation | Control in this repository | Reference |
|---|---|---|
Set BILLIONS_NETWORK_MASTER_KMS_KEY before creating or importing keys | A > Note block immediately precedes every key-creation command in the README, instructing the operator to set the variable. The KMS Encryption section documents the on-disk format change and the AES-256-GCM scheme. | README.md → "KMS Encryption" |
| Use only a dedicated, no-assets identity key | An explicit > Warning block under the key-creation step tells the operator never to pass an asset-holding wallet key to --key. | README.md step 2 of "Human CTA" |
Restrict ~/.openclaw/billions permissions | The "Key Storage and Isolation" section instructs chmod 700 ~/.openclaw/billions after the first run. The directory itself sits outside the agent workspace, so workspace-scoped tools cannot read it. | README.md → "Key Storage and Isolation" |
| Avoid importing any wallet key that controls funds | Same > Warning block as above; reinforced in the Operator Checklist below. | README.md step 2 warning + this document |
Why the plaintext mode is retained
1. Zero-config local development and CI smoke tests — no master secret to fetch or commit. 2. Backward compatibility — existing kms.json files written by earlier versions of the skill remain readable; legacy entries auto-migrate on the next write (scripts/shared/storage/keys.js → _decodeEntry legacy branch). 3. Single code path — the same write path becomes encrypted at rest the moment BILLIONS_NETWORK_MASTER_KMS_KEY is set. There is no separate "secure mode" the operator has to migrate to, so the plaintext default cannot drift away from the encrypted path over time.
The Operator Checklist is the recommended deployment posture and exactly matches the scanner's recommendation.
Operator Checklist
1. Set the master key first.
export BILLIONS_NETWORK_MASTER_KMS_KEY="<a strong secret>"Do this before the first node scripts/createNewEthereumIdentity.js. Keys created without it are written as provider: "plain". 2. Use a dedicated identity key. Never reuse an Ethereum private key that holds assets. If the kms.json file is exposed, every key inside it should be revocable / disposable. 3. Restrict the storage directory.
chmod 700 ~/.openclaw/billions4. Back up the master key out of band. If BILLIONS_NETWORK_MASTER_KMS_KEY is lost, every entry written under provider: "encrypted" is unrecoverable.
Reporting a Vulnerability
Please report suspected vulnerabilities privately to the Billions Network security contact rather than filing a public issue. Open an issue marked security requesting a private disclosure channel if you do not already have one.
Related skills
FAQ
What does verified-agent-identity do?
Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based on iden3 self-sovere
When should I use verified-agent-identity?
Know Your Agent (KYA). Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentication proofs. Based on iden3 self-sovere
Is verified-agent-identity safe to install?
Review the Security Audits panel on this page before installing in production.