Leanjutsu

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 code and instructions broadly match an agent identity-linking tool, but there are packaging inconsistencies and several security-relevant behaviors (plaintext key storage by default, JWS/attestation sent to remote endpoints, CLI private-key arguments) that warrant caution before installing.

Purpose & Capability

Functionality in the scripts (create identity, sign/verify challenges, produce a wallet pairing URL) matches the declared identity/linking purpose. However the registry metadata and embedded _meta.json/README values differ (skill listed as 'Leanjutsu' vs SKILL.md name 'verified-agent-identity' and differing owner/slug entries), which is an inconsistency that should be explained by the publisher.

Instruction Scope

Runtime instructions are focused on DID creation, signing, linking and verification. They read and write identity material under $HOME/.openclaw/billions and make network calls to resolver.privado.id, rpc-mainnet.billions.network and several billions.network domains. The code also POSTs the authorization request to a URL shortener (identity-dashboard.billions.network) and constructs a callback URL that embeds the signed JWS as a query parameter — this sends potentially sensitive attestation/JWS material to a remote service, which is expected for this protocol but is a concentration-of-risk and should be accepted explicitly by the user.

Install Mechanism

There is no automated install spec in the registry (install is manual via 'cd scripts && npm install'), but the package and package-lock pull from public npm registries and use well-known identity libraries. This is expected for a Node-based identity toolkit; still, running 'npm install' will fetch dependencies from npm (moderate risk) and the skill includes many code files that will be executed locally.

Credentials

The skill does not require credentials to be set by default, but it stores private keys in $HOME/.openclaw/billions/kms.json. By default keys are stored as plaintext 'plain' provider unless the user sets the optional environment variable BILLIONS_NETWORK_MASTER_KMS_KEY to enable AES-256-GCM per-entry encryption. Storing private keys unencrypted by default and allowing private keys to be passed on the CLI (--key) (which can be leaked via shell history) are significant sensitive-data risks that must be understood before use.

Persistence & Privilege

The skill persists identity and key material to $HOME/.openclaw/billions (its own directory) and does not request always:true or system-wide config changes. The skill may be invoked autonomously by the agent (default platform behavior); given it can access and sign with stored keys, autonomous invocation increases potential impact and should be considered when granting the skill to an agent.

What to consider before installing

This package appears to implement the identity-linking functionality it claims, but review these before installing: - Provenance: confirm the publisher and package identity (the SKILL.md name, README, and _meta.json/registry owner/slug differ). Only proceed if you trust the source and homepage (billions.network). - Key storage: by default private keys will be written to $HOME/.openclaw/billions/kms.json and may be stored unencrypted. If you will store real/private keys, set BILLIONS_NETWORK_MASTER_KMS_KEY to a strong secret (and understand how to manage it), or avoid using real keys on this machine. - CLI key exposure: avoid passing private keys via --key on shells with history; prefer importing keys via secure means or using the KMS encryption feature. - Remote endpoints: the skill sends signed JWS/attestation material to a URL-shortener and to an attestation-relay endpoint (domains under billions.network and resolver.privado.id). Review and accept the privacy implications (these endpoints will see the attestation or the shortener request_uri). If you require on-prem or audited endpoints, adapt the code before use. - Dependency install: the scripts require running 'npm install' which will fetch many packages from npm; audit or pin versions if you need stricter supply-chain guarantees. If you are not comfortable with the above (especially plaintext key storage or sending attestations to remote services), do not install or run the scripts on a machine with valuable keys. If you decide to proceed, set BILLIONS_NETWORK_MASTER_KMS_KEY, review the code yourself (or ask for a vendor attestation), and run in an isolated 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 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>."