@buildersgarden/siwa 0.0.5 → 0.0.7

package/README.md

@@ -4,29 +4,27 @@ A Claude Code skill for registering AI agents on the [ERC-8004 (Trustless Agents
 
 ## What it does
 
-- **Create Wallet** — Generate an Ethereum wallet with secure key storage (encrypted V3 file, keyring proxy, or env var)
+- **Create Wallet** — Generate an Ethereum wallet via a keyring proxy (private key never enters the agent process)
 - **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
+src/               Core SDK modules
+  keystore.ts        Proxy-only keystore (signing delegated over HMAC-authenticated HTTP)
+  identity.ts        IDENTITY.md read/write helpers
   siwa.ts            SIWA message building, signing, verification
-  create_wallet.ts   Wallet creation flow
-  register_agent.ts  Onchain registration flow
+  proxy-auth.ts      HMAC-SHA256 authentication utilities
+  registry.ts        Onchain agent profile & reputation lookups
+  addresses.ts       Deployed contract addresses
 
 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
+  IDENTITY.template.md
 
 test/              Local test environment (Express server + CLI agent)
 ```
@@ -51,13 +49,7 @@ 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 |
+The agent's private key never enters the agent process. All signing is delegated to a **keyring proxy** over HMAC-authenticated HTTP. Even full agent compromise cannot extract the key — only request signatures.
 
 See [`references/security-model.md`](references/security-model.md) for the full threat model.
 

package/dist/identity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * identity.ts
+ *
+ * Read/write helpers for the agent's IDENTITY.md file.
+ * Minimal 4-field identity: Address, Agent ID, Agent Registry, Chain ID.
+ *
+ * IDENTITY.md uses the pattern: - **Key**: `value`
+ *
+ * Registration checks are done onchain via ownerOf() when a PublicClient
+ * is provided, otherwise the local file is used as a cache.
+ *
+ * Dependencies: fs (Node built-in), viem (optional for onchain checks)
+ */
+import type { PublicClient } from 'viem';
+export interface AgentIdentity {
+    address?: string;
+    agentId?: number;
+    agentRegistry?: string;
+    chainId?: number;
+}
+/**
+ * Ensure IDENTITY.md exists. If not, copy from template or create minimal.
+ */
+export declare function ensureIdentityExists(identityPath?: string, templatePath?: string): void;
+/**
+ * Read the agent identity from IDENTITY.md.
+ * Returns typed AgentIdentity with parsed values.
+ */
+export declare function readIdentity(identityPath?: string): AgentIdentity;
+/**
+ * Write a single field value in IDENTITY.md.
+ */
+export declare function writeIdentityField(key: string, value: string, identityPath?: string): void;
+/**
+ * Check if the agent has a wallet address recorded in IDENTITY.md.
+ */
+export declare function hasWalletRecord(identityPath?: string): boolean;
+/**
+ * Check if the agent is registered.
+ *
+ * Without a client: returns true if IDENTITY.md has an Agent ID and Agent Registry (local cache).
+ * With a client: performs an onchain ownerOf(agentId) check on the registry contract.
+ */
+export declare function isRegistered(options?: {
+    identityPath?: string;
+    client?: PublicClient;
+}): Promise<boolean>;

package/dist/identity.js

@@ -0,0 +1,123 @@
+/**
+ * identity.ts
+ *
+ * Read/write helpers for the agent's IDENTITY.md file.
+ * Minimal 4-field identity: Address, Agent ID, Agent Registry, Chain ID.
+ *
+ * IDENTITY.md uses the pattern: - **Key**: `value`
+ *
+ * Registration checks are done onchain via ownerOf() when a PublicClient
+ * is provided, otherwise the local file is used as a cache.
+ *
+ * Dependencies: fs (Node built-in), viem (optional for onchain checks)
+ */
+import * as fs from 'fs';
+const DEFAULT_IDENTITY_PATH = './IDENTITY.md';
+// ---------------------------------------------------------------------------
+// File Operations
+// ---------------------------------------------------------------------------
+/**
+ * Ensure IDENTITY.md exists. If not, copy from template or create minimal.
+ */
+export function ensureIdentityExists(identityPath = DEFAULT_IDENTITY_PATH, templatePath) {
+    if (fs.existsSync(identityPath))
+        return;
+    if (templatePath && fs.existsSync(templatePath)) {
+        fs.copyFileSync(templatePath, identityPath);
+    }
+    else {
+        const minimal = `# Agent Identity
+- **Address**: \`<NOT SET>\`
+- **Agent ID**: \`<NOT SET>\`
+- **Agent Registry**: \`<NOT SET>\`
+- **Chain ID**: \`<NOT SET>\`
+`;
+        fs.writeFileSync(identityPath, minimal);
+    }
+}
+/**
+ * Read the agent identity from IDENTITY.md.
+ * Returns typed AgentIdentity with parsed values.
+ */
+export function readIdentity(identityPath = DEFAULT_IDENTITY_PATH) {
+    if (!fs.existsSync(identityPath))
+        return {};
+    const content = fs.readFileSync(identityPath, 'utf-8');
+    const fields = {};
+    for (const line of content.split('\n')) {
+        const match = line.match(/^- \*\*(.+?)\*\*:\s*`(.+?)`/);
+        if (match && match[2] !== '<NOT SET>') {
+            fields[match[1]] = match[2];
+        }
+    }
+    const identity = {};
+    if (fields['Address'])
+        identity.address = fields['Address'];
+    if (fields['Agent ID'])
+        identity.agentId = parseInt(fields['Agent ID']);
+    if (fields['Agent Registry'])
+        identity.agentRegistry = fields['Agent Registry'];
+    if (fields['Chain ID'])
+        identity.chainId = parseInt(fields['Chain ID']);
+    return identity;
+}
+/**
+ * Write a single field value in IDENTITY.md.
+ */
+export function writeIdentityField(key, value, identityPath = DEFAULT_IDENTITY_PATH) {
+    let content = fs.readFileSync(identityPath, 'utf-8');
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`(- \\*\\*${escaped}\\*\\*:\\s*)\`.+?\``);
+    if (pattern.test(content)) {
+        content = content.replace(pattern, `$1\`${value}\``);
+    }
+    else {
+        content += `\n- **${key}**: \`${value}\`\n`;
+    }
+    fs.writeFileSync(identityPath, content);
+}
+/**
+ * Check if the agent has a wallet address recorded in IDENTITY.md.
+ */
+export function hasWalletRecord(identityPath = DEFAULT_IDENTITY_PATH) {
+    const identity = readIdentity(identityPath);
+    return !!identity.address;
+}
+/**
+ * Check if the agent is registered.
+ *
+ * Without a client: returns true if IDENTITY.md has an Agent ID and Agent Registry (local cache).
+ * With a client: performs an onchain ownerOf(agentId) check on the registry contract.
+ */
+export async function isRegistered(options) {
+    const identityPath = options?.identityPath ?? DEFAULT_IDENTITY_PATH;
+    const identity = readIdentity(identityPath);
+    if (!identity.agentId || !identity.agentRegistry)
+        return false;
+    const client = options?.client;
+    if (!client)
+        return true; // Local cache says registered
+    // Onchain check: ownerOf(agentId) on the registry
+    const registryParts = identity.agentRegistry.split(':');
+    if (registryParts.length !== 3 || registryParts[0] !== 'eip155')
+        return false;
+    const registryAddress = registryParts[2];
+    try {
+        await client.readContract({
+            address: registryAddress,
+            abi: [{
+                    name: 'ownerOf',
+                    type: 'function',
+                    stateMutability: 'view',
+                    inputs: [{ name: 'tokenId', type: 'uint256' }],
+                    outputs: [{ name: '', type: 'address' }],
+                }],
+            functionName: 'ownerOf',
+            args: [BigInt(identity.agentId)],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './keystore.js';
 export * from './siwa.js';
-export * from './memory.js';
+export * from './identity.js';
 export * from './proxy-auth.js';
 export * from './registry.js';
 export * from './addresses.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export * from './keystore.js';
 export * from './siwa.js';
-export * from './memory.js';
+export * from './identity.js';
 export * from './proxy-auth.js';
 export * from './registry.js';
 export * from './addresses.js';

package/dist/keystore.d.ts

@@ -1,52 +1,30 @@
 /**
  * keystore.ts
  *
- * Secure private key storage abstraction for ERC-8004 agents.
+ * Secure signing 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 @noble/ciphers) — password-encrypted file on disk
- *   2. Environment variable fallback (AGENT_PRIVATE_KEY) — least secure, for CI/testing only
+ * All signing is delegated to a **keyring proxy server** — a separate process
+ * that holds the encrypted private key and exposes only HMAC-authenticated
+ * signing endpoints. The private key NEVER enters the agent process.
  *
- * 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)
+ *   - signMessage(msg)        → returns { signature, address }
+ *   - signTransaction(tx)     → returns { signedTx, address }
+ *   - signAuthorization(auth) → returns signed EIP-7702 authorization
  *   - getAddress()            → returns the public address
  *   - hasWallet()             → returns boolean
  *
- * EIP-7702 Support:
- *   Wallets are standard EOAs created via viem's generatePrivateKey().
- *   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 viem
- *
  * 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
+ *   KEYRING_PROXY_URL     — URL of the keyring proxy server
+ *   KEYRING_PROXY_SECRET  — HMAC shared secret
  */
-import { type WalletClient, type Account, type Chain, type Transport } from "viem";
-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;
@@ -79,20 +57,13 @@ export interface TransactionLike {
     gasPrice?: bigint | null;
     accessList?: any[];
 }
-export declare function detectBackend(): Promise<KeystoreBackend>;
 /**
- * Create a new random wallet and store it securely.
+ * Create a new random wallet via the keyring proxy.
  * 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.
+ * Check if a wallet is available via the keyring proxy.
  */
 export declare function hasWallet(config?: KeystoreConfig): Promise<boolean>;
 /**
@@ -100,14 +71,12 @@ export declare function hasWallet(config?: KeystoreConfig): Promise<boolean>;
  */
 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.
+ * Sign a message (EIP-191 personal_sign) via the keyring proxy.
  * 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.
+ * Sign a transaction via the keyring proxy.
  * Only the signed transaction is returned.
  */
 export declare function signTransaction(tx: TransactionLike, config?: KeystoreConfig): Promise<{
@@ -118,22 +87,6 @@ export declare function signTransaction(tx: TransactionLike, config?: KeystoreCo
  * Sign an EIP-7702 authorization for delegating the EOA to a contract.
  *
  * 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)
+ * during a type 4 transaction. Only the signed authorization tuple is returned.
  */
 export declare function signAuthorization(auth: AuthorizationRequest, config?: KeystoreConfig): Promise<SignedAuthorization>;
-/**
- * Get a wallet client for contract interactions.
- * NOTE: This creates a client with the private key in memory.
- * Use only within a narrow scope and discard immediately.
- * Prefer signMessage() / signTransaction() when possible.
- */
-export declare function getWalletClient(rpcUrl: string, config?: KeystoreConfig): Promise<WalletClient<Transport, Chain | undefined, Account>>;
-/**
- * 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>;