@buildersgarden/siwa 0.0.1

package/README.md

@@ -0,0 +1,75 @@
+# SIWA — Sign In With Agent
+
+A Claude Code skill for registering AI agents on the [ERC-8004 (Trustless Agents)](https://github.com/builders-garden/ERC-8004) standard and authenticating them via SIWA, a challenge-response protocol inspired by [EIP-4361 (SIWE)](https://eips.ethereum.org/EIPS/eip-4361).
+
+## What it does
+
+- **Create Wallet** — Generate an Ethereum wallet with secure key storage (encrypted V3 file, keyring proxy, or env var)
+- **Register Agent (Sign Up)** — Mint an ERC-721 identity NFT on the ERC-8004 Identity Registry with metadata (endpoints, trust model, services)
+- **Authenticate (Sign In)** — Prove ownership of an onchain agent identity by signing a structured SIWA message; receive a JWT from the relying party
+
+## Project Structure
+
+```
+scripts/           Core skill implementation
+  keystore.ts        Secure key storage (3 backends)
+  memory.ts          MEMORY.md read/write helpers
+  siwa.ts            SIWA message building, signing, verification
+  create_wallet.ts   Wallet creation flow
+  register_agent.ts  Onchain registration flow
+
+references/        Protocol documentation
+  siwa-spec.md       Full SIWA specification
+  security-model.md  Threat model and keystore architecture
+  contract-addresses.md  Deployed registry addresses
+  registration-guide.md  Registration file schema
+
+assets/            Templates
+  MEMORY.md.template
+  registration-template.json
+
+test/              Local test environment (Express server + CLI agent)
+```
+
+## Quick Start (Local Test)
+
+```bash
+cd test
+pnpm install
+
+# Terminal 1: Start the SIWA relying-party server
+pnpm run server
+
+# Terminal 2: Run the full agent flow (create wallet → register → sign in → authenticated call)
+pnpm run agent:flow
+
+# Or run both at once:
+pnpm run dev
+```
+
+See [`test/README.md`](test/README.md) for full details on the test environment.
+
+## Security Model
+
+The agent's private key never enters the agent's context window. All cryptographic operations are handled by the keystore module, which loads the key, uses it, and discards it immediately.
+
+| Backend | Storage | Use case |
+|---------|---------|----------|
+| `proxy` | HMAC-authenticated HTTP to a keyring proxy server | Production — process isolation, key never enters agent |
+| `encrypted-file` | Ethereum V3 JSON Keystore (AES-128-CTR + scrypt) | Local development, Docker, CI |
+| `env` | `AGENT_PRIVATE_KEY` environment variable | Testing only |
+
+See [`references/security-model.md`](references/security-model.md) for the full threat model.
+
+## Tech Stack
+
+- **TypeScript** (ES modules, strict mode)
+- **ethers.js** v6 — wallet management and contract interaction
+- **pnpm** — package manager
+
+## References
+
+- [SKILL.md](SKILL.md) — Full skill documentation and API reference
+- [ERC-8004 specification](https://github.com/builders-garden/ERC-8004)
+- [SIWA protocol spec](references/siwa-spec.md)
+

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './keystore.js';
+export * from './siwa.js';
+export * from './memory.js';
+export * from './proxy-auth.js';
+export * from './registry.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './keystore.js';
+export * from './siwa.js';
+export * from './memory.js';
+export * from './proxy-auth.js';
+export * from './registry.js';

package/dist/keystore.d.ts

@@ -0,0 +1,126 @@
+/**
+ * keystore.ts
+ *
+ * Secure private key storage abstraction for ERC-8004 agents.
+ *
+ * Three backends, in order of preference:
+ *   0. Keyring Proxy (via HMAC-authenticated HTTP) — key never enters agent process
+ *   1. Ethereum V3 Encrypted JSON Keystore (via ethers.js) — password-encrypted file on disk
+ *   2. Environment variable fallback (AGENT_PRIVATE_KEY) — least secure, for CI/testing only
+ *
+ * The private key NEVER leaves this module as a return value.
+ * External code interacts only through:
+ *   - createWallet()          → returns { address } (no private key)
+ *   - importWallet(pk)        → stores and returns { address }
+ *   - signMessage(msg)        → returns { signature }
+ *   - signTransaction(tx)     → returns { signedTx }
+ *   - signAuthorization(auth) → returns signed EIP-7702 authorization (no key exposed)
+ *   - getAddress()            → returns the public address
+ *   - hasWallet()             → returns boolean
+ *
+ * EIP-7702 Support (requires ethers >= 6.14.3):
+ *   Wallets are standard EOAs created via ethers.Wallet.createRandom().
+ *   EIP-7702 allows these EOAs to temporarily delegate to smart contract
+ *   implementations via authorization lists in type 4 transactions.
+ *   Use signAuthorization() to sign delegation authorizations without
+ *   exposing the private key.
+ *
+ * Dependencies:
+ *   npm install ethers
+ *
+ * Configuration (via env vars or passed options):
+ *   KEYSTORE_BACKEND      — "encrypted-file" | "env" | "proxy" (auto-detected if omitted)
+ *   KEYSTORE_PASSWORD     — Password for encrypted-file backend (prompted interactively if omitted)
+ *   KEYSTORE_PATH         — Path to encrypted keystore file (default: ./agent-keystore.json)
+ *   AGENT_PRIVATE_KEY     — Fallback for env backend only
+ */
+import { ethers } from 'ethers';
+export type KeystoreBackend = 'encrypted-file' | 'env' | 'proxy';
+export interface KeystoreConfig {
+    backend?: KeystoreBackend;
+    keystorePath?: string;
+    password?: string;
+    proxyUrl?: string;
+    proxySecret?: string;
+}
+export interface WalletInfo {
+    address: string;
+    backend: KeystoreBackend;
+    keystorePath?: string;
+}
+export interface SignResult {
+    signature: string;
+    address: string;
+}
+export interface AuthorizationRequest {
+    address: string;
+    chainId?: number;
+    nonce?: number;
+}
+export interface SignedAuthorization {
+    address: string;
+    nonce: number;
+    chainId: number;
+    yParity: number;
+    r: string;
+    s: string;
+}
+export declare function detectBackend(): Promise<KeystoreBackend>;
+/**
+ * Create a new random wallet and store it securely.
+ * Returns only the public address — NEVER the private key.
+ */
+export declare function createWallet(config?: KeystoreConfig): Promise<WalletInfo>;
+/**
+ * Import an existing private key into the secure store.
+ * After calling this, the caller should discard its copy of the key.
+ * Returns only the public address.
+ */
+export declare function importWallet(privateKey: string, config?: KeystoreConfig): Promise<WalletInfo>;
+/**
+ * Check if a wallet is available in any backend.
+ */
+export declare function hasWallet(config?: KeystoreConfig): Promise<boolean>;
+/**
+ * Get the wallet's public address (no private key exposed).
+ */
+export declare function getAddress(config?: KeystoreConfig): Promise<string | null>;
+/**
+ * Sign a message (EIP-191 personal_sign).
+ * The private key is loaded, used, and immediately discarded.
+ * Only the signature is returned.
+ */
+export declare function signMessage(message: string, config?: KeystoreConfig): Promise<SignResult>;
+/**
+ * Sign a transaction.
+ * The private key is loaded, used, and immediately discarded.
+ * Only the signed transaction is returned.
+ */
+export declare function signTransaction(tx: ethers.TransactionRequest, config?: KeystoreConfig): Promise<{
+    signedTx: string;
+    address: string;
+}>;
+/**
+ * Sign an EIP-7702 authorization for delegating the EOA to a contract.
+ * Requires ethers >= 6.14.3.
+ *
+ * This allows the agent's EOA to temporarily act as a smart contract
+ * during a type 4 transaction. The private key is loaded, used, and
+ * immediately discarded — only the signed authorization tuple is returned.
+ *
+ * @param auth — Authorization request (target contract address, optional chainId/nonce)
+ * @returns Signed authorization tuple (address, nonce, chainId, yParity, r, s)
+ */
+export declare function signAuthorization(auth: AuthorizationRequest, config?: KeystoreConfig): Promise<SignedAuthorization>;
+/**
+ * Get a connected signer (for contract interactions).
+ * NOTE: This returns a signer with the private key in memory.
+ * Use only within a narrow scope and discard immediately.
+ * Prefer signMessage() / signTransaction() when possible.
+ */
+export declare function getSigner(provider: ethers.Provider, config?: KeystoreConfig): Promise<ethers.Wallet>;
+/**
+ * Delete the stored wallet from the active backend.
+ * DESTRUCTIVE — the identity is lost if no backup exists.
+ */
+export declare function deleteWallet(config?: KeystoreConfig): Promise<boolean>;

package/dist/keystore.js

@@ -0,0 +1,355 @@
+/**
+ * keystore.ts
+ *
+ * Secure private key storage abstraction for ERC-8004 agents.
+ *
+ * Three backends, in order of preference:
+ *   0. Keyring Proxy (via HMAC-authenticated HTTP) — key never enters agent process
+ *   1. Ethereum V3 Encrypted JSON Keystore (via ethers.js) — password-encrypted file on disk
+ *   2. Environment variable fallback (AGENT_PRIVATE_KEY) — least secure, for CI/testing only
+ *
+ * The private key NEVER leaves this module as a return value.
+ * External code interacts only through:
+ *   - createWallet()          → returns { address } (no private key)
+ *   - importWallet(pk)        → stores and returns { address }
+ *   - signMessage(msg)        → returns { signature }
+ *   - signTransaction(tx)     → returns { signedTx }
+ *   - signAuthorization(auth) → returns signed EIP-7702 authorization (no key exposed)
+ *   - getAddress()            → returns the public address
+ *   - hasWallet()             → returns boolean
+ *
+ * EIP-7702 Support (requires ethers >= 6.14.3):
+ *   Wallets are standard EOAs created via ethers.Wallet.createRandom().
+ *   EIP-7702 allows these EOAs to temporarily delegate to smart contract
+ *   implementations via authorization lists in type 4 transactions.
+ *   Use signAuthorization() to sign delegation authorizations without
+ *   exposing the private key.
+ *
+ * Dependencies:
+ *   npm install ethers
+ *
+ * Configuration (via env vars or passed options):
+ *   KEYSTORE_BACKEND      — "encrypted-file" | "env" | "proxy" (auto-detected if omitted)
+ *   KEYSTORE_PASSWORD     — Password for encrypted-file backend (prompted interactively if omitted)
+ *   KEYSTORE_PATH         — Path to encrypted keystore file (default: ./agent-keystore.json)
+ *   AGENT_PRIVATE_KEY     — Fallback for env backend only
+ */
+import { ethers } from 'ethers';
+import * as fs from 'fs';
+import * as crypto from 'crypto';
+import { computeHmac } from './proxy-auth.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_KEYSTORE_PATH = './agent-keystore.json';
+// ---------------------------------------------------------------------------
+// Proxy backend — HMAC-authenticated HTTP to a keyring proxy server
+// ---------------------------------------------------------------------------
+async function proxyRequest(config, endpoint, body = {}) {
+    const url = config.proxyUrl || process.env.KEYRING_PROXY_URL;
+    const secret = config.proxySecret || process.env.KEYRING_PROXY_SECRET;
+    if (!url)
+        throw new Error('Proxy backend requires KEYRING_PROXY_URL or config.proxyUrl');
+    if (!secret)
+        throw new Error('Proxy backend requires KEYRING_PROXY_SECRET or config.proxySecret');
+    const bodyStr = JSON.stringify(body, (_key, value) => typeof value === 'bigint' ? '0x' + value.toString(16) : value);
+    const hmacHeaders = computeHmac(secret, 'POST', endpoint, bodyStr);
+    const res = await fetch(`${url}${endpoint}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...hmacHeaders,
+        },
+        body: bodyStr,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Proxy ${endpoint} failed (${res.status}): ${text}`);
+    }
+    return res.json();
+}
+// ---------------------------------------------------------------------------
+// Backend detection
+// ---------------------------------------------------------------------------
+export async function detectBackend() {
+    // 0. Proxy backend (if URL is set)
+    if (process.env.KEYRING_PROXY_URL)
+        return 'proxy';
+    // 1. Check for existing encrypted keystore file
+    if (fs.existsSync(process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH)) {
+        return 'encrypted-file';
+    }
+    // 2. Check for env var
+    if (process.env.AGENT_PRIVATE_KEY)
+        return 'env';
+    // 3. Default to encrypted-file (will be created on first use)
+    return 'encrypted-file';
+}
+// ---------------------------------------------------------------------------
+// Encrypted V3 JSON Keystore backend (ethers.js built-in)
+// ---------------------------------------------------------------------------
+async function encryptedFileStore(privateKey, address, password, filePath) {
+    const account = { address, privateKey };
+    // ethers v6: encryptKeystoreJsonSync or encryptKeystoreJson
+    const json = await ethers.encryptKeystoreJson(account, password);
+    fs.writeFileSync(filePath, json, { mode: 0o600 }); // Owner-only read/write
+}
+async function encryptedFileLoad(password, filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    const json = fs.readFileSync(filePath, 'utf-8');
+    const wallet = await ethers.Wallet.fromEncryptedJson(json, password);
+    return wallet.privateKey;
+}
+function encryptedFileExists(filePath) {
+    return fs.existsSync(filePath);
+}
+// ---------------------------------------------------------------------------
+// Password derivation for encrypted-file backend
+//
+// When no explicit password is given, derive one from the machine's identity.
+// This is NOT meant as a strong user password — it's a fallback so agents
+// can operate without interactive prompts. For production, always set
+// KEYSTORE_PASSWORD or use the OS keychain.
+// ---------------------------------------------------------------------------
+function deriveMachinePassword() {
+    const factors = [
+        process.env.USER || process.env.USERNAME || 'agent',
+        process.env.HOME || process.env.USERPROFILE || '/tmp',
+        require('os').hostname(),
+        require('os').platform(),
+    ];
+    return crypto
+        .createHash('sha256')
+        .update(factors.join(':'))
+        .digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Public API — the ONLY way external code touches private keys
+// ---------------------------------------------------------------------------
+/**
+ * Create a new random wallet and store it securely.
+ * Returns only the public address — NEVER the private key.
+ */
+export async function createWallet(config = {}) {
+    const backend = config.backend || await detectBackend();
+    const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
+    if (backend === 'proxy') {
+        const data = await proxyRequest(config, '/create-wallet');
+        return { address: data.address, backend, keystorePath: undefined };
+    }
+    const wallet = ethers.Wallet.createRandom();
+    const privateKey = wallet.privateKey;
+    const address = wallet.address;
+    switch (backend) {
+        case 'encrypted-file': {
+            const password = config.password || process.env.KEYSTORE_PASSWORD || deriveMachinePassword();
+            await encryptedFileStore(privateKey, address, password, keystorePath);
+            break;
+        }
+        case 'env':
+            // For env backend, we print the key ONCE for the operator to capture.
+            // This is the ONLY time the raw key is ever exposed.
+            console.log('=== ENV BACKEND (testing only) ===');
+            console.log(`Set this in your environment:`);
+            console.log(`  export AGENT_PRIVATE_KEY="${privateKey}"`);
+            console.log('=================================');
+            break;
+    }
+    return {
+        address,
+        backend,
+        keystorePath: backend === 'encrypted-file' ? keystorePath : undefined,
+    };
+}
+/**
+ * Import an existing private key into the secure store.
+ * After calling this, the caller should discard its copy of the key.
+ * Returns only the public address.
+ */
+export async function importWallet(privateKey, config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        throw new Error('importWallet() is not supported via proxy. Import the wallet on the proxy server directly.');
+    }
+    const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
+    const wallet = new ethers.Wallet(privateKey);
+    const address = wallet.address;
+    switch (backend) {
+        case 'encrypted-file': {
+            const password = config.password || process.env.KEYSTORE_PASSWORD || deriveMachinePassword();
+            await encryptedFileStore(privateKey, address, password, keystorePath);
+            break;
+        }
+        case 'env':
+            // Nothing to persist for env backend
+            break;
+    }
+    return {
+        address,
+        backend,
+        keystorePath: backend === 'encrypted-file' ? keystorePath : undefined,
+    };
+}
+/**
+ * Check if a wallet is available in any backend.
+ */
+export async function hasWallet(config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        const data = await proxyRequest(config, '/has-wallet');
+        return data.hasWallet;
+    }
+    const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
+    switch (backend) {
+        case 'encrypted-file':
+            return encryptedFileExists(keystorePath);
+        case 'env':
+            return !!process.env.AGENT_PRIVATE_KEY;
+    }
+}
+/**
+ * Get the wallet's public address (no private key exposed).
+ */
+export async function getAddress(config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        const data = await proxyRequest(config, '/get-address');
+        return data.address;
+    }
+    const wallet = await _loadWalletInternal(config);
+    if (!wallet)
+        return null;
+    const address = wallet.address;
+    // wallet goes out of scope and is GC'd — private key not returned
+    return address;
+}
+/**
+ * Sign a message (EIP-191 personal_sign).
+ * The private key is loaded, used, and immediately discarded.
+ * Only the signature is returned.
+ */
+export async function signMessage(message, config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        const data = await proxyRequest(config, '/sign-message', { message });
+        return { signature: data.signature, address: data.address };
+    }
+    const wallet = await _loadWalletInternal(config);
+    if (!wallet)
+        throw new Error('No wallet found. Run createWallet() first.');
+    const signature = await wallet.signMessage(message);
+    const address = wallet.address;
+    // wallet goes out of scope — private key discarded
+    return { signature, address };
+}
+/**
+ * Sign a transaction.
+ * The private key is loaded, used, and immediately discarded.
+ * Only the signed transaction is returned.
+ */
+export async function signTransaction(tx, config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        const data = await proxyRequest(config, '/sign-transaction', { tx: tx });
+        return { signedTx: data.signedTx, address: data.address };
+    }
+    const wallet = await _loadWalletInternal(config);
+    if (!wallet)
+        throw new Error('No wallet found. Run createWallet() first.');
+    const signedTx = await wallet.signTransaction(tx);
+    const address = wallet.address;
+    return { signedTx, address };
+}
+/**
+ * Sign an EIP-7702 authorization for delegating the EOA to a contract.
+ * Requires ethers >= 6.14.3.
+ *
+ * This allows the agent's EOA to temporarily act as a smart contract
+ * during a type 4 transaction. The private key is loaded, used, and
+ * immediately discarded — only the signed authorization tuple is returned.
+ *
+ * @param auth — Authorization request (target contract address, optional chainId/nonce)
+ * @returns Signed authorization tuple (address, nonce, chainId, yParity, r, s)
+ */
+export async function signAuthorization(auth, config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        const data = await proxyRequest(config, '/sign-authorization', { auth });
+        return data;
+    }
+    const wallet = await _loadWalletInternal(config);
+    if (!wallet)
+        throw new Error('No wallet found. Run createWallet() first.');
+    // ethers v6.14.3+ exposes wallet.authorize()
+    if (typeof wallet.authorize !== 'function') {
+        throw new Error('wallet.authorize() not available. EIP-7702 requires ethers >= 6.14.3. ' +
+            'Run: pnpm add ethers@latest');
+    }
+    const authorization = await wallet.authorize({
+        address: auth.address,
+        ...(auth.chainId !== undefined && { chainId: auth.chainId }),
+        ...(auth.nonce !== undefined && { nonce: auth.nonce }),
+    });
+    // wallet goes out of scope — private key discarded
+    return authorization;
+}
+/**
+ * Get a connected signer (for contract interactions).
+ * NOTE: This returns a signer with the private key in memory.
+ * Use only within a narrow scope and discard immediately.
+ * Prefer signMessage() / signTransaction() when possible.
+ */
+export async function getSigner(provider, config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        throw new Error('getSigner() is not supported via proxy. The private key cannot be serialized over HTTP. Use signMessage() or signTransaction() instead.');
+    }
+    const wallet = await _loadWalletInternal(config);
+    if (!wallet)
+        throw new Error('No wallet found. Run createWallet() first.');
+    return wallet.connect(provider);
+}
+/**
+ * Delete the stored wallet from the active backend.
+ * DESTRUCTIVE — the identity is lost if no backup exists.
+ */
+export async function deleteWallet(config = {}) {
+    const backend = config.backend || await detectBackend();
+    if (backend === 'proxy') {
+        throw new Error('deleteWallet() is not supported via proxy. Delete the wallet on the proxy server directly.');
+    }
+    const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
+    switch (backend) {
+        case 'encrypted-file':
+            if (fs.existsSync(keystorePath)) {
+                fs.unlinkSync(keystorePath);
+                return true;
+            }
+            return false;
+        case 'env':
+            console.warn('Cannot delete env-based wallet. Unset AGENT_PRIVATE_KEY manually.');
+            return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal — loads the wallet. NEVER exposed publicly.
+// ---------------------------------------------------------------------------
+async function _loadWalletInternal(config = {}) {
+    const backend = config.backend || await detectBackend();
+    const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
+    let privateKey = null;
+    switch (backend) {
+        case 'encrypted-file': {
+            const password = config.password || process.env.KEYSTORE_PASSWORD || deriveMachinePassword();
+            privateKey = await encryptedFileLoad(password, keystorePath);
+            break;
+        }
+        case 'env':
+            privateKey = process.env.AGENT_PRIVATE_KEY || null;
+            break;
+    }
+    if (!privateKey)
+        return null;
+    return new ethers.Wallet(privateKey);
+}

package/dist/memory.d.ts

@@ -0,0 +1,37 @@
+/**
+ * memory.ts
+ *
+ * Read/write helpers for the agent's MEMORY.md public identity file.
+ * MEMORY.md uses the pattern: - **Key**: `value`
+ *
+ * IMPORTANT: This file stores ONLY public data (address, agentId, etc.).
+ * Private keys are managed exclusively by keystore.ts.
+ *
+ * Dependencies: fs (Node built-in)
+ */
+/**
+ * Ensure MEMORY.md exists. If not, copy from template or create minimal.
+ */
+export declare function ensureMemoryExists(memoryPath?: string, templatePath?: string): void;
+/**
+ * Read all populated fields from MEMORY.md.
+ * Returns a map of Key → value (skips <NOT SET> fields).
+ */
+export declare function readMemory(memoryPath?: string): Record<string, string>;
+/**
+ * Write a single field value in MEMORY.md.
+ */
+export declare function writeMemoryField(key: string, value: string, memoryPath?: string): void;
+/**
+ * Append a line under a ## Section header in MEMORY.md.
+ */
+export declare function appendToMemorySection(section: string, line: string, memoryPath?: string): void;
+/**
+ * Check if the agent has a wallet address recorded.
+ * Note: This only checks MEMORY.md — the actual key is in the keystore.
+ */
+export declare function hasWalletRecord(memoryPath?: string): boolean;
+/**
+ * Check if the agent is registered onchain.
+ */
+export declare function isRegistered(memoryPath?: string): boolean;