Verified Agent Identity

Billions/Iden3 authentication and identity management tools for agents. Link, proof, sign, and verify.

Security Scan

The skill's code and instructions are consistent with its stated purpose (creating, signing, and verifying DIDs on the Billions/iden3 network), but it has a few practical risks and a metadata inconsistency you should understand before installing.

Purpose & Capability

The name/description match the included scripts: identity creation, signing, linking, and verification using iden3/Billions. The code implements expected features (KMS, DID storage, JWS signing, RPC/resolver calls). One metadata inconsistency: registry metadata lists no required binaries, but SKILL.md and the code require 'node' and the 'openclaw' CLI (used to send direct messages).

Instruction Scope

Runtime instructions tell you to run `npm install` and several node scripts that read/write files under $HOME/.openclaw/billions, call network endpoints (RPC, DID resolver, attestation relay), and invoke the 'openclaw message send' binary to forward tokens/URLs. Those actions are coherent with identity management, but the skill will: (1) persist private keys locally (unencrypted JSON), (2) create outbound network requests (RPC, resolver, relay), and (3) embed signed tokens in URLs that are sent to recipients. The SKILL.md guardrails explicitly forbid manual key manipulation and running arbitrary crypto tools, which is slightly odd given keys are persisted unencrypted — keep that in mind.

Install Mechanism

No formal install spec is provided, but SKILL.md instructs running `cd scripts && npm install`. That pulls dependencies from the npm registry (package.json/package-lock reference standard packages). This is expected for a Node-based skill but introduces the normal npm supply-chain risks (third-party packages). There are no downloads from untrusted URLs or scripts that extract arbitrary archives.

Credentials

The skill declares no required environment variables, which is appropriate. However it stores sensitive material (private keys) unencrypted in files under $HOME/.openclaw/billions (kms.json). While this is functionally necessary for the skill, it is a sensitive privilege: anyone with filesystem access to that path can read private keys. Also the SKILL.md metadata requires the 'openclaw' CLI; if that CLI has its own credentials or agent tokens accessible via the environment or config, the skill will call it (though the code attempts argument sanitization).

Persistence & Privilege

The skill does not request 'always: true' or other elevated agent-wide privileges. It writes only to a self-contained directory ($HOME/.openclaw/billions) and does not modify other skills' configurations. It can be invoked autonomously (default), which is normal — combine that with the local key store sensitivity when granting autonomy.

Assessment

This skill appears to implement what it claims, but take these precautions before installing: - Verify you trust the Billions/iden3 endpoints used (rpc-mainnet.billions.network, attestation-relay.billions.network, resolver.privado.id). The skill will contact them. - Be aware private keys are saved unencrypted to $HOME/.openclaw/billions/kms.json by default. Restrict filesystem permissions to that directory and review its contents after use. - The scripts call the 'openclaw' CLI to send messages. Confirm that the local openclaw binary is trusted and that sending verification URLs/tokens to recipients is acceptable in your environment. - Running `npm install` will fetch packages from npm (normal for Node). If you have strict supply-chain requirements, review package-lock.json or install in an isolated environment first. - Note the small metadata mismatch: the registry entry omitted required binaries while SKILL.md requires node and openclaw. Confirm your runtime meets those requirements before enabling. If you need stronger guarantees (encrypted key storage, different storage path, or removal of autonomous invocation), request an updated skill that supports those changes or run the scripts manually in a locked environment.

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 sign a challenge.
3. When you need link a human to the agent's DID.
4. When you need to verify a signature to confirm identity ownership.
5. When 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 --to <SENDER> --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 --to <sender> --challenge <challenge> [--did <did>] Description: Signs a challenge with a DID's private key to prove identity ownership and sends the JWS token as a direct message to the specified sender. Use this when you need to prove you own a specific DID. Arguments:

• --to - (required) The message sender identifier, passed as --target to openclaw message send
• --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 and send to sender
node scripts/signChallenge.js --to <sender> --challenge 8472951360

Output: {"success":true}

linkHumanToAgent.js

Command: node scripts/linkHumanToAgent.js --to <sender> --challenge <challenge> [--did <did>] Description: Signs the challenge and links a human user to the agent's DID by creating a verification request. Response will be sent as a direct message to the specified sender. Arguments:

• --to - (required) The message sender identifier, passed as --target to openclaw message send
• --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 --to <sender> --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 unencrypted private keys
• 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 --to <sender> --challenge <challenge_value> to sign the challenge and generate a verification URL in one call.
   • The --to value is the message sender (the caller's identifier).
   • 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 --to <sender> --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>."