DryptoBillions

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

Security Scan

The skill's code and instructions match its stated identity-management purpose, but it persistently stores unencrypted private keys in the user's home directory and relies on network callbacks and many npm dependencies — risks that warrant caution before installing.

Purpose & Capability

Name/description (DIDs, sign/verify, link) align with the included scripts: identity creation, signing, pairing links, and verification. The openclaw CLI and node are required as declared in SKILL.md metadata. However, the implementation persists private keys in plaintext under $HOME/.openclaw/billions/kms.json which is functionally related to the purpose but increases risk and should be explicitly highlighted to users.

Instruction Scope

Runtime instructions are narrowly scoped to running the provided node scripts and sending messages via openclaw. The scripts read/write files in $HOME/.openclaw/billions, call the openclaw CLI to send messages, and perform network calls to Billions network endpoints and a DID resolver. They do not attempt to read unrelated system state or require unrelated credentials, but they do generate and store long-lived cryptographic material and include callbacks that will expose signed tokens to external endpoints (attestation-relay.billions.network and wallet.billions.network).

Install Mechanism

There is no built-in install spec — SKILL.md instructs running npm install in scripts/, which will pull public npm packages (package-lock included). This is a moderate supply-chain surface: dependencies include multiple iden3/PolygonID libraries and some git+https entries. No arbitrary binary downloads from unknown hosts are present, but npm install will bring many transitive packages (AGPL-licensed components are present).

Credentials

No environment variables are requested, which is appropriate. But the skill stores sensitive private keys unencrypted in $HOME/.openclaw/billions/kms.json (KeysFileStorage), accessible to anyone with filesystem access to the account. It also writes other identity state to $HOME/.openclaw/billions. Persisting raw private keys locally is disproportionate from a security standpoint unless the user understands and accepts this tradeoff.

Persistence & Privilege

The skill persists long-lived credential material and identity state to $HOME/.openclaw/billions outside the agent workspace. It does not request elevated platform privileges or set always:true, but the creation of plaintext private-key files is a persistent privilege that increases the blast radius if an account is compromised.

Scan Findings in Context

[child_process.execFileSync] expected: The code invokes execFileSync('openclaw', ...) to send direct messages. This is expected for a skill that must call the openclaw CLI; the implementation includes input sanitization and an allowlist for the target, reducing command-injection risk.

[plaintext_key_storage] expected: The KeysFileStorage implementation writes private keys in JSON to kms.json under $HOME/.openclaw/billions. Storing keys on disk in plaintext is functionally consistent with an on-disk KMS but is a sensitive design choice users must be aware of.

[external_network_endpoints] expected: Scripts contact RPC and relay endpoints (rpc-mainnet.billions.network, attestation-relay.billions.network) and a DID resolver (resolver.privado.id). These network calls are expected for identity verification flows but cause signed tokens/JWS to be passed to external services (via callback query parameters), which has privacy/security implications.

What to consider before installing

This skill appears to do what it says (create DIDs, sign/verify, create pairing URLs) but there are some important security considerations: - Private keys are stored unencrypted on disk at $HOME/.openclaw/billions/kms.json. Anyone with access to your user account or backup of that path can impersonate the agent. Prefer a secure, encrypted KMS or ensure the directory permissions and host security are appropriate before installing. - Installing requires running npm install in the scripts/ folder. That will pull many dependencies (including AGPL components and some git-sourced packages). Consider auditing package-lock.json, running npm audit, and verifying the provenance of packages. - The skill sends signed tokens and pairing callbacks to third-party endpoints (attestation-relay.billions.network, wallet.billions.network, and resolver.privado.id). Confirm that you trust these services and understand what data will be transmitted (signed attestation tokens can contain identity metadata). - The scripts call the openclaw CLI (execFileSync). Ensure the openclaw binary on your PATH is the authentic CLI you expect; otherwise the skill could interact with a malicious binary. - If you need the functionality but want less risk, ask the maintainer for an option to encrypt keys at rest, or to use an external secure KMS. If you cannot confirm the source/trustworthiness of the code and endpoints, treat this skill as untrusted. If you want, I can extract the exact files that write keys and the lines where network callbacks are constructed so you or a reviewer can inspect them more quickly.

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