Verified Agent Identity

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

Security Scan

The skill's instructions request creating and storing private identity keys and running npm-installed scripts, but the package is missing the referenced code and its declared requirements/configuration do not match the SKILL.md — this mismatch and the runtime download risk warrant caution.

Purpose & Capability

The description says 'identity/authentication' which fits the actions described (create DIDs, sign/verify). However the registry metadata lists no required binaries or config paths while the SKILL.md explicitly requires node and the openclaw CLI and stores keys under $HOME/.openclaw/billions — that inconsistency is unexplained and concerning.

Instruction Scope

Runtime instructions tell the agent to run scripts that create private keys, sign challenges, and send JWS tokens via openclaw. Those are high-sensitivity actions (private key creation, storage, and signing). The SKILL.md also forbids manual crypto tooling and file edits, but the skill package contains only the SKILL.md and no scripts, meaning the agent would attempt to run non‑existent code or fetch dependencies at runtime.

Install Mechanism

There is no install spec, but the SKILL.md instructs the user/agent to run 'cd scripts && npm install' which would pull remote packages at runtime. Since no scripts/JS files are bundled with the skill, this implies runtime network fetches and execution of third-party code — a higher-risk install pattern not declared in the registry.

Credentials

The skill does not declare any required environment variables or credentials, but it writes and reads sensitive material (private keys, challenges) to $HOME/.openclaw/billions. Storing private keys locally is expected for an identity tool, but the skill failing to declare that config path in metadata is an inconsistency and increases the chance of unexpected key exposure.

Persistence & Privilege

The skill is not forced-always, and autonomous invocation is allowed (platform default). It persists identity data and private keys under the user's home directory. Combined with the ability to sign challenges, autonomous invocation could allow the agent to sign/supply attestations without explicit human approval — this is normal for identity tooling but deserves explicit user controls.

What to consider before installing

Do not install or run this skill yet. The SKILL.md references Node scripts and the openclaw CLI but the published package contains only SKILL.md (no scripts), and the registry metadata omits required binaries and the config path where private keys are stored — this mismatch could be benign (incomplete packaging) or malicious (instructions cause runtime fetching of code and handling of private keys). Before proceeding: 1) Ask the publisher for the full source repository or packaged scripts and verify the exact scripts referenced. 2) Inspect every script to see how private keys are generated, stored, and used (search for network endpoints, telemetry, and remote uploads). 3) Never run 'npm install' or node scripts on your primary machine before auditing; run in an isolated sandbox. 4) Confirm where keys are stored and consider using an external/HSM wallet or ephemeral keys you can revoke. 5) If you need this functionality but cannot review the code, prefer a well-known, reviewed implementation or request a signed release from the project homepage. If you proceed without code review, treat the skill as high-risk and be prepared to rotate/revoke any keys created.

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>."