create-agent 0.0.8 → 0.0.11

package/.claude/settings.local.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(git checkout:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(node -e:*)",
+      "Bash(npm test)",
+      "Bash(git pull:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh issue list:*)",
+      "WebFetch(domain:nostrcg.github.io)",
+      "Bash(node bin/create-agent.js:*)",
+      "WebSearch",
+      "Bash(gh issue view:*)",
+      "Bash(gh api:*)",
+      "WebFetch(domain:ai-sdk.dev)",
+      "WebFetch(domain:github.com)",
+      "Bash(git fetch:*)",
+      "Bash(gh repo fork:*)",
+      "Bash(node /home/melvin/agi/create-agent/bin/create-agent.js:*)"
+    ]
+  }
+}

package/README.md

@@ -1,113 +1,201 @@
-# create-agent 🤖
+# create-agent
 
-A command-line tool to generate Agent keypairs with various encodings.
+[![npm version](https://img.shields.io/npm/v/create-agent.svg)](https://www.npmjs.com/package/create-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933.svg)](https://nodejs.org/)
 
-## Installation 📦
+> **Your AI agent has no identity.** It can't prove who it is. It can't sign anything. It can't be trusted.
+>
+> Fix that in one command.
 
 ```bash
-npm install -g create-agent
+npx create-agent
 ```
 
-Or simply run:
+Instantly generates a cryptographic identity with a [W3C DID document](https://www.w3.org/TR/did-core/) — the emerging standard for autonomous agent identity.
+
+---
+
+## Why create-agent?
+
+AI agents and autonomous systems need verifiable identities. Traditional auth (API keys, OAuth) wasn't designed for machine-to-machine trust. **create-agent** provides:
+
+- **Cryptographic Identity** — Schnorr keypairs on secp256k1
+- **W3C Standards** — DID documents for interoperability
+- **Decentralized** — No central authority, works with Nostr relays
+- **Zero Config** — One command, instant identity
+
+---
+
+## Installation
 
 ```bash
-npm create agent
+# Run directly (no install)
+npx create-agent
+
+# Or install globally
+npm install -g create-agent
+
+# Or as a dependency
+npm install create-agent
 ```
 
-## Usage 🚀
+---
 
-Simply run:
+## CLI Output
 
-```bash
-create-agent
+The tool outputs a spec-compliant DID document to `stdout`:
+
+```json
+{
+  "@context": [
+    "https://w3id.org/did",
+    "https://w3id.org/nostr/context"
+  ],
+  "id": "did:nostr:dd82687ee5a352c6d6de337bce53f150ca1567f3861475c74e7da62695931d23",
+  "type": "DIDNostr",
+  "verificationMethod": [
+    {
+      "id": "did:nostr:dd82687ee5a352c6d6de337bce53f150ca1567f3861475c74e7da62695931d23#key1",
+      "type": "Multikey",
+      "controller": "did:nostr:dd82687ee5a352c6d6de337bce53f150ca1567f3861475c74e7da62695931d23",
+      "publicKeyMultibase": "fe70102dd82687ee5a352c6d6de337bce53f150ca1567f3861475c74e7da62695931d23"
+    }
+  ],
+  "authentication": ["#key1"],
+  "assertionMethod": ["#key1"],
+  "service": []
+}
 ```
 
-The tool will generate a new Agent keypair and display it in various formats.
+Key information is displayed on `stderr` for security (private keys in red).
 
-## Output Fields 🔑
+---
 
-The tool generates a JSON object containing:
+## Programmatic API
 
-### Private Key Formats
+```javascript
+import { generateAgent } from 'create-agent'
 
-#### `privkey`
+const agent = generateAgent()
 
-- 32-byte private key in hexadecimal format
-- The private key of the Agent
-- Used to sign Nostr events
-- Example:
-  ```
-  "7f7168866801e2003bfc6507f881783e23587d35ece7b1f1981891b9c9c26c55"
-  ```
-- ⚠️ **Keep this secret!**
+// Nostr keys
+console.log(agent.pubkey)   // hex public key
+console.log(agent.npub)     // bech32 public key
+console.log(agent.privkey)  // hex private key (keep secret)
+console.log(agent.nsec)     // bech32 private key (keep secret)
 
-#### `nsec`
+// W3C DID Document
+console.log(agent.did.id)   // did:nostr:<pubkey>
+console.log(agent.did)      // full DID document
+```
 
-- Bech32-encoded private key (starts with `nsec`)
-- Human-friendly format
-- Example:
-  ```
-  "nsec1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq3vk8rx"
-  ```
-- ⚠️ **Keep this secret!**
+---
 
-### Public Key Formats
+## CLI Examples
 
-#### `pubkey`
+```bash
+# Save DID document to file
+create-agent > agent-identity.json
 
-- 32-byte public key in hexadecimal format
-- Derived from private key using Schnorr signatures
-- Your identity in the Nostr network
-- Example:
-  ```
-  "06444f34c6c5f973d74b3c78214fd0bf694f0cf459651b2ffe651fa08ba00bf4"
-  ```
+# Extract DID identifier
+create-agent | jq -r '.id'
 
-#### `npub`
+# Extract public key
+create-agent | jq -r '.verificationMethod[0].publicKeyMultibase'
 
-- Bech32-encoded public key (starts with `npub`)
-- Human-friendly format for sharing
-- Example:
-  ```
-  "npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m"
-  ```
+# Suppress stderr, get only JSON
+create-agent 2>/dev/null
+```
 
-## Example Output 📝
+---
+
+## Output Reference
+
+### Keys
+
+| Field | Format | Description |
+|-------|--------|-------------|
+| `pubkey` | 64 hex chars | Public key (shareable) |
+| `npub` | bech32 | Human-readable public key |
+| `privkey` | 64 hex chars | Private key — **keep secret** |
+| `nsec` | bech32 | Human-readable private key — **keep secret** |
+
+### DID Document
+
+| Field | Value |
+|-------|-------|
+| `@context` | W3C DID v1 + Nostr context |
+| `id` | `did:nostr:<pubkey>` |
+| `type` | `DIDNostr` |
+| `verificationMethod` | Multikey with secp256k1 |
+| `authentication` | `#key1` reference |
+| `assertionMethod` | `#key1` reference |
+
+### Multibase Encoding
+
+The `publicKeyMultibase` follows multicodec standards:
 
-```json
-{
-  "privkey": "7f7168866801e2003bfc6507f881783e23587d35ece7b1f1981891b9c9c26c55",
-  "pubkey": "06444f34c6c5f973d74b3c78214fd0bf694f0cf459651b2ffe651fa08ba00bf4",
-  "nsec": "nsec1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq3vk8rx",
-  "npub": "npub1sg6plzptd64u62a878hep2kev88swjh3tw00gjsfl8f237lmu63q0uf63m"
-}
 ```
+fe70102<pubkey>
+│└───┘└┘└─────┘
+│  │   │   └── 32-byte x-coordinate
+│  │   └────── 02 compressed key prefix
+│  └────────── e701 secp256k1-pub varint
+└───────────── f base16-lower prefix
+```
+
+---
+
+## Use Cases
+
+| Application | Description |
+|-------------|-------------|
+| **AI Agents** | Verifiable identity for autonomous systems |
+| **Nostr Bots** | Generate keypairs for automated accounts |
+| **Testing** | Create ephemeral identities for integration tests |
+| **Credentials** | Subject identifiers for Verifiable Credentials |
+
+---
+
+## Security
 
-## Security Notice 🔒
+Private keys (`privkey`, `nsec`) are cryptographic secrets. Exposure allows:
 
-**Never share your private key!** Anyone with access to your private key (`privkey` or `nsec`) can:
+- Signing messages as the identity
+- Accessing encrypted communications
+- Full impersonation
 
-- ✍️ Post messages as you
-- 👤 Update your profile
-- 👥 Follow/unfollow other users
-- 📨 Send encrypted messages in your name
+The CLI outputs private keys to `stderr` only, allowing safe piping of the DID document.
+
+---
 
-## About Nostr 📡
+## Specification
+
+This implementation follows the [did:nostr Method Specification](https://nostrcg.github.io/did-nostr/) maintained by the [W3C Nostr Community Group](https://www.w3.org/community/nostr/).
+
+---
 
-Nostr (Notes and Other Stuff Transmitted by Relays) is a decentralized social networking protocol. Each user is identified by a public key, and all actions are signed using their corresponding private key.
+## Related
 
-## Development 🛠️
+- [did:nostr Specification](https://nostrcg.github.io/did-nostr/)
+- [DID:nostr Explorer](https://nostrapps.github.io/did-explorer/)
+- [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
+- [W3C DID Core](https://www.w3.org/TR/did-core/)
+
+---
+
+## Development
 
 ```bash
 git clone https://github.com/melvincarvalho/create-agent.git
 cd create-agent
 npm install
+npm test
 ```
 
-## License 📄
-
-MIT
-
 ---
 
-Made with ❤️ for the [Agentic Alliance](https://agenticalliance.com/) community
+## License
+
+MIT — [Agentic Alliance](https://agenticalliance.com/)

package/bin/create-agent.js

@@ -1,48 +1,9 @@
 #!/usr/bin/env node
 
-// =============================================================================
-// NOSTR KEY GENERATION
-// =============================================================================
-import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
-import { nip19 } from 'nostr-tools';
-
-// Generate cryptographically secure private key (32 bytes)
-const privkey = generateSecretKey();
-const privkeyHex = Array.from(privkey)
-  .map(b => b.toString(16).padStart(2, '0'))
-  .join('');
-
-// Derive public key using Schnorr signatures (32 bytes, hex encoded)
-const pubkey = getPublicKey(privkey);
+import { generateAgent } from '../index.js'
 
-// Encode keys in Nostr formats
-const nsec = nip19.nsecEncode(privkey);
-const npub = nip19.npubEncode(pubkey);
-
-// =============================================================================
-// DID DOCUMENT CREATION
-// =============================================================================
-const didDocument = {
-  "@context": [
-    "https://www.w3.org/ns/did/v1",
-    "https://w3id.org/nostr/context"
-  ],
-  "id": `did:nostr:${pubkey}`,
-  "verificationMethod": [
-    {
-      "id": `did:nostr:${pubkey}#key1`,
-      "controller": `did:nostr:${pubkey}`,
-      "type": "SchnorrVerification2025"
-    }
-  ],
-  "authentication": [
-    "#key1"
-  ],
-  "assertionMethod": [
-    "#key1"
-  ],
-  "service": []  // Empty services array
-};
+// Generate agent identity
+const { privkey, pubkey, nsec, npub, did } = generateAgent()
 
 // =============================================================================
 // CONSOLE OUTPUT
@@ -59,7 +20,7 @@ process.stderr.write('\n\x1b[32m📋 Your Nostr Identity:\x1b[0m\n');
 process.stderr.write('\x1b[32m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m\n');
 process.stderr.write(`\x1b[0mPublic Key (hex) : \x1b[33m${pubkey}\x1b[0m\n`);
 process.stderr.write(`\x1b[0mNostr Public Key : \x1b[33m${npub}\x1b[0m\n`);
-process.stderr.write(`\x1b[0mPrivate Key (hex): \x1b[31m${privkeyHex}\x1b[0m\n`);
+process.stderr.write(`\x1b[0mPrivate Key (hex): \x1b[31m${privkey}\x1b[0m\n`);
 process.stderr.write(`\x1b[0mNostr Secret Key : \x1b[31m${nsec}\x1b[0m\n`);
 process.stderr.write('\n');
 process.stderr.write('\x1b[36m🔍 Usage:\x1b[0m\n');
@@ -72,5 +33,5 @@ process.stderr.write('\n');
 // Then output the DID document to stdout with a clear header in the output
 process.stderr.write('\x1b[36m📄 DID Nostr Document:\x1b[0m\n');
 process.stderr.write('\x1b[36m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m\n');
-console.log(JSON.stringify(didDocument, null, 2));
+console.log(JSON.stringify(did, null, 2));
 process.stderr.write('\x1b[36m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m\n');

package/index.js

@@ -0,0 +1,47 @@
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure'
+import { nip19 } from 'nostr-tools'
+
+/**
+ * Generate a new Nostr agent identity
+ * @returns {{ privkey: string, pubkey: string, nsec: string, npub: string, did: object }}
+ */
+export function generateAgent() {
+  // Generate cryptographically secure private key (32 bytes)
+  const sk = generateSecretKey()
+  const privkey = Array.from(sk)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('')
+
+  // Derive public key using Schnorr signatures
+  const pubkey = getPublicKey(sk)
+
+  // Encode keys in Nostr formats
+  const nsec = nip19.nsecEncode(sk)
+  const npub = nip19.npubEncode(pubkey)
+
+  // Create publicKeyMultibase: f (base16-lower) + e701 (secp256k1-pub varint) + 02 (even parity) + pubkey
+  const publicKeyMultibase = `fe70102${pubkey}`
+
+  // Create DID document per https://nostrcg.github.io/did-nostr/
+  const did = {
+    "@context": [
+      "https://w3id.org/did",
+      "https://w3id.org/nostr/context"
+    ],
+    "id": `did:nostr:${pubkey}`,
+    "type": "DIDNostr",
+    "verificationMethod": [
+      {
+        "id": `did:nostr:${pubkey}#key1`,
+        "type": "Multikey",
+        "controller": `did:nostr:${pubkey}`,
+        "publicKeyMultibase": publicKeyMultibase
+      }
+    ],
+    "authentication": ["#key1"],
+    "assertionMethod": ["#key1"],
+    "service": []
+  }
+
+  return { privkey, pubkey, nsec, npub, did }
+}

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "create-agent",
   "type": "module",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "description": "create an agent",
-  "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   },
   "bin": {
     "create-agent": "bin/create-agent.js"

package/test/index.test.js

@@ -0,0 +1,66 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert'
+import { generateAgent } from '../index.js'
+
+describe('generateAgent', () => {
+  test('returns all expected properties', () => {
+    const agent = generateAgent()
+    
+    assert.ok(agent.privkey, 'should have privkey')
+    assert.ok(agent.pubkey, 'should have pubkey')
+    assert.ok(agent.nsec, 'should have nsec')
+    assert.ok(agent.npub, 'should have npub')
+    assert.ok(agent.did, 'should have did')
+  })
+
+  test('privkey is 64-character hex string', () => {
+    const { privkey } = generateAgent()
+    
+    assert.strictEqual(privkey.length, 64)
+    assert.match(privkey, /^[0-9a-f]{64}$/)
+  })
+
+  test('pubkey is 64-character hex string', () => {
+    const { pubkey } = generateAgent()
+    
+    assert.strictEqual(pubkey.length, 64)
+    assert.match(pubkey, /^[0-9a-f]{64}$/)
+  })
+
+  test('nsec starts with nsec1', () => {
+    const { nsec } = generateAgent()
+    
+    assert.ok(nsec.startsWith('nsec1'))
+  })
+
+  test('npub starts with npub1', () => {
+    const { npub } = generateAgent()
+    
+    assert.ok(npub.startsWith('npub1'))
+  })
+
+  test('did document has correct structure', () => {
+    const { did, pubkey } = generateAgent()
+    
+    assert.deepStrictEqual(did['@context'], [
+      'https://www.w3.org/ns/did/v1',
+      'https://w3id.org/nostr/context'
+    ])
+    assert.strictEqual(did.id, `did:nostr:${pubkey}`)
+    assert.ok(Array.isArray(did.verificationMethod))
+    assert.strictEqual(did.verificationMethod[0].type, 'SchnorrVerification2025')
+    assert.deepStrictEqual(did.authentication, ['#key1'])
+    assert.deepStrictEqual(did.assertionMethod, ['#key1'])
+    assert.deepStrictEqual(did.service, [])
+  })
+
+  test('generates unique keys on each call', () => {
+    const agent1 = generateAgent()
+    const agent2 = generateAgent()
+    
+    assert.notStrictEqual(agent1.privkey, agent2.privkey)
+    assert.notStrictEqual(agent1.pubkey, agent2.pubkey)
+    assert.notStrictEqual(agent1.nsec, agent2.nsec)
+    assert.notStrictEqual(agent1.npub, agent2.npub)
+  })
+})