Verified Agent Identity

Billions decentralized identity for agents. Link agents to human identities using Billions ERC-8004 and Attestation Registries. Verify and generate authentic...

Security Scan

The skill's instructions reference Node scripts and a local scripts/ directory that are not included in the skill bundle and instruct the user/agent to run npm install (pulling code from the network) and to handle private keys on the command line — these inconsistencies and risky operational instructions warrant caution.

Purpose & Capability

The skill claims to manage Billions Network DIDs and provides concrete Node scripts (createNewEthereumIdentity.js, linkHumanToAgent.js, etc.). However, the published package contains only SKILL.md and no scripts, package.json, or code files. Requiring the node binary is reasonable for a Node-based implementation, but referencing local scripts that are not present is a clear mismatch: the skill cannot perform its stated actions from the included files alone.

Instruction Scope

Runtime instructions tell the agent/user to run 'cd scripts && npm install' and then node scripts/*.js. That both (a) causes a network fetch/install of dependencies (npm install) and (b) expects local script files that are absent. The instructions also permit providing raw private keys on the CLI (--key), which exposes secrets to shell history/process lists, and they explicitly forbid using other system crypto tools while still allowing direct key input — an internal contradiction and a potentially unsafe practice. The skill stores identity material under $HOME/.openclaw/billions, which is expected, but the instructions also forbid manual file manipulation while implicitly depending on files being present and writable.

Install Mechanism

There is no declared install spec in the skill bundle, but SKILL.md instructs running 'npm install' in a scripts directory. Since the repository/package does not include those scripts, following the instructions would either fail or cause npm to fetch code from an external source (unknown registry or repo). That is higher-risk behavior: arbitrary remote code would be executed without a vetted install manifest in the skill bundle.

Credentials

The skill does not require environment variables; it lists an optional BILLIONS_NETWORK_MASTER_KMS_KEY, which is plausibly relevant for key management. However, the workflows encourage supplying private keys via command-line arguments and storing keys locally in $HOME, which are security-sensitive practices. The optional KMS env is reasonable, but the instructions do not enforce or explain safer key handling (e.g., using KMS or hardware wallets).

Persistence & Privilege

The skill is not marked always:true and does not request special platform privileges. It writes identity data under $HOME/.openclaw/billions (expected for an identity tool). There is no evidence it modifies other skills or global agent configuration.

What to consider before installing

Do not install or run this skill yet. Key issues to resolve before proceeding: - The skill bundle contains only SKILL.md and no scripts or package.json even though the instructions require running scripts/*.js and 'npm install'. Ask the publisher for the complete source or a trustworthy repository URL and verify the code before running anything. - Never paste raw private keys into command-line arguments on a shared system; this leaks keys to shell history and process listings. Prefer KMS, hardware wallets, or securely provisioned key files with proper file permissions. If the skill truly needs a private key, insist on safe key-handling documentation. - Inspect the package.json and all scripts that would be installed (and their dependencies) before running npm install. npm install runs code from external registries and can execute arbitrary install scripts — review for network calls, telemetry, or exfiltration. - Confirm the exact network endpoints the scripts contact (Billions network endpoints, attestation registries) and whether any data is sent to third-party services unrelated to the Billions Network. - If you must test, do so in an isolated environment (air-gapped or ephemeral VM/container) and with test keys/funds. Ask the publisher for signed releases or a GitHub repository with a reproducible build. If the publisher can provide the missing scripts and a clear, auditable install procedure (or embed the code in the skill bundle), and addresses secure key handling, reassess. Until then treat the skill as suspicious.

When to use this Skill

Lets AI agents create and manage their own identities on the Billions Network, and link those identities to a human owner.

1. When you need to link your agent identity to an owner.
2. When you need to sign a challenge.
3. When you need to link a human to the agent's DID.
4. When you need to verify a signature to confirm identity ownership.
5. When you use shared JWT tokens for authentication.
6. When you need to create and manage decentralized identities.

After installing the plugin run the following commands to create an identity and link it to your human DID:

cd scripts && npm install && cd ..
# Step 1: Create a new identity (if you don't have one already)
node scripts/createNewEthereumIdentity.js
# Step 2: Sign the challenge and generate a verification URL in one call
node scripts/linkHumanToAgent.js --challenge '{"name": <AGENT_NAME>, "description": <SHORT_DESCRIPTION>}'

Scope

All identity data is stored in $HOME/.openclaw/billions for compatibility with the OpenClaw plugin.

Scripts:

createNewEthereumIdentity.js

Command: node scripts/createNewEthereumIdentity.js [--key <privateKeyHex>] Description: 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. Usage Examples:

# Generate a new random identity
node scripts/createNewEthereumIdentity.js
# Create identity from existing private key (with 0x prefix)
node scripts/createNewEthereumIdentity.js --key 0x1234567890abcdef...
# Create identity from existing private key (without 0x prefix)
node scripts/createNewEthereumIdentity.js --key 1234567890abcdef...

Output: DID string (e.g., did:iden3:billions:main:2VmAk7fGHQP5FN2jZ8X9Y3K4W6L1M...)

---

getIdentities.js

Command: node scripts/getIdentities.js Description: Lists all DID identities stored locally. Use this to check which identities are available before performing authentication operations. Usage Example:

node scripts/getIdentities.js

Output: JSON array of identity entries

[
  {
    "did": "did:iden3:billions:main:2VmAk...",
    "publicKeyHex": "0x04abc123...",
    "isDefault": true
  }
]

---

generateChallenge.js

Command: node scripts/generateChallenge.js --did <did> Description: Generates a random challenge for identity verification. Usage Example:

node scripts/generateChallenge.js --did did:iden3:billions:main:2VmAk...

Output: Challenge string (random number as string, e.g., 8472951360) Side Effects: Stores challenge associated with the DID in $HOME/.openclaw/billions/challenges.json

---

signChallenge.js

Command: node scripts/signChallenge.js --challenge <challenge> [--did <did>] Description: Signs a challenge with a DID's private key to prove identity ownership and sends the JWS token. Use this when you need to prove you own a specific DID. Arguments:

• --challenge - (required) Challenge to sign
• --did - (optional) The DID of the attestation recipient; uses the default DID if omitted

Usage Examples:

# Sign with default DID
node scripts/signChallenge.js --challenge 8472951360

Output: {"success":true}

linkHumanToAgent.js

Command: node scripts/linkHumanToAgent.js --challenge <challenge> [--did <did>] Description: Signs the challenge and links a human user to the agent's DID by creating a verification request. Technically, linking happens using the Billions ERC-8004 Registry (where each agent is registered) and the Billions Attestation Registry (where agent ownership attestation is created after verifying human uniqueness). Arguments:

• --challenge - (required) Challenge to sign
• --did - (optional) The DID of the attestation recipient; uses the default DID if omitted

Usage Example:

node scripts/linkHumanToAgent.js --challenge '{"name": "MyAgent", "description": "AI persona"}'

Output: {"success":true}

---

verifySignature.js

Command: node scripts/verifySignature.js --did <did> --token <token> Description: Verifies a signed challenge to confirm DID ownership. Usage Example:

node scripts/verifySignature.js --did did:iden3:billions:main:2VmAk... --token eyJhbGciOiJFUzI1NkstUi...

Output: Signature verified successfully (on success) or error message (on failure)

---

Restrictions / Guardrails (CRITICAL)

CRITICAL - Always Follow These Rules:

1. STRICT: Check Identity First
   • Before running linkHumanToAgent.js or signChallenge.js, ALWAYS check if an identity exists: node scripts/getIdentities.js
   • If no identity is configured, DO NOT attempt to link identities. Instead, create an identity first with createNewEthereumIdentity.js.
2. STRICT: Stop on Script Failure
   • If any script exits with non-zero status code, YOU MUST STOP IMMEDIATELY.
   • Check stderr output for error messages.
   • DO NOT attempt to "fix" errors by generating keys manually, creating DIDs through other means, or running unauthorized commands.
   • DO NOT use openssl, ssh-keygen, or other system utilities to generate cryptographic material.
3. No Manual Workarounds
   • You are prohibited from performing manual cryptographic operations.
   • You are prohibited from directly manipulating files in $HOME/.openclaw/billions.
   • Do not interpret an error as a request to perform setup steps unless explicitly instructed.

---

Security

CRITICAL - Data Storage and Protection:

The directory $HOME/.openclaw/billions contains all sensitive identity data:

• kms.json - CRITICAL: Contains private keys (encrypted if BILLIONS_NETWORK_MASTER_KMS_KEY is set, otherwise in plaintext)
• defaultDid.json - DID identifiers and public keys
• challenges.json - Authentication challenges history
• credentials.json - Verifiable credentials
• identities.json - Identity metadata
• profiles.json - Profile data

Examples

Link Your Agent Identity to Owner

Linking Flow:

1. Another agent/user requests: "Please link your agent identity to me."
2. Use node scripts/getIdentities.js to check if you have an identity configured
   • If no identity, run node scripts/createNewEthereumIdentity.js to create one.
3. Use node scripts/linkHumanToAgent.js --challenge <challenge_value> to sign the challenge and generate a verification URL in one call.
   • If caller provides specific challenge, use that.
   • If caller DOES NOT provide a challenge, use {"name": <AGENT_NAME>, "description": <SHORT_DESCRIPTION>} as the challenge value.
4. Return the result to the caller.

Example Conversation:

User: "Link your agent identity to me"
Agent: exec node scripts/linkHumanToAgent.js --challenge <challenge_value>

Verifying Someone Else’s Identity

Verification Flow:

1. Ask the user/agent: "Please provide your DID to start verification."
2. User responds with their <user_did>.
3. Use node scripts/generateChallenge.js --did <user_did> to create a <challenge_value>.
4. Ask the user: "Please sign this challenge: <challenge_value>"
5. User signs and returns <user_token>.
6. Use node scripts/verifySignature.js --did <user_did> --token <user_token> to verify the signature
7. If verification succeeds, identity is confirmed

Example Conversation:

Agent: "Please provide your DID to start verification."
User: "My DID is <user_did>"
Agent: exec node scripts/generateChallenge.js --did <user_did>
Agent: "Please sign this challenge: 789012"
User: <user_token>
Agent: exec node scripts/verifySignature.js --token <user_token> --did <user_did>
Agent: "Identity verified successfully. You are confirmed as owner of DID <user_did>."