@buildersgarden/siwa 0.0.1

package/dist/memory.js

@@ -0,0 +1,134 @@
+/**
+ * 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)
+ */
+import * as fs from 'fs';
+const DEFAULT_MEMORY_PATH = './MEMORY.md';
+/**
+ * Ensure MEMORY.md exists. If not, copy from template or create minimal.
+ */
+export function ensureMemoryExists(memoryPath = DEFAULT_MEMORY_PATH, templatePath) {
+    if (fs.existsSync(memoryPath))
+        return;
+    if (templatePath && fs.existsSync(templatePath)) {
+        fs.copyFileSync(templatePath, memoryPath);
+    }
+    else {
+        const minimal = `# Agent Identity Memory
+
+> This file contains **public** agent identity data only. The private key is stored
+> securely in the keystore backend (OS keychain or encrypted file) — never here.
+
+## Wallet
+
+- **Address**: \`<NOT SET>\`
+- **Keystore Backend**: \`<NOT SET>\`
+- **Keystore Path**: \`<NOT SET>\`
+- **Created At**: \`<NOT SET>\`
+
+## Registration
+
+- **Status**: \`unregistered\`
+- **Agent ID**: \`<NOT SET>\`
+- **Agent Registry**: \`<NOT SET>\`
+- **Agent URI**: \`<NOT SET>\`
+- **Chain ID**: \`<NOT SET>\`
+- **Registered At**: \`<NOT SET>\`
+
+## Agent Profile
+
+- **Name**: \`<NOT SET>\`
+- **Description**: \`<NOT SET>\`
+- **Image**: \`<NOT SET>\`
+
+## Services
+
+## Sessions
+
+## Notes
+`;
+        fs.writeFileSync(memoryPath, minimal);
+    }
+}
+/**
+ * Read all populated fields from MEMORY.md.
+ * Returns a map of Key → value (skips <NOT SET> fields).
+ */
+export function readMemory(memoryPath = DEFAULT_MEMORY_PATH) {
+    if (!fs.existsSync(memoryPath))
+        return {};
+    const content = fs.readFileSync(memoryPath, '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];
+        }
+    }
+    return fields;
+}
+/**
+ * Write a single field value in MEMORY.md.
+ */
+export function writeMemoryField(key, value, memoryPath = DEFAULT_MEMORY_PATH) {
+    let content = fs.readFileSync(memoryPath, '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(memoryPath, content);
+}
+/**
+ * Append a line under a ## Section header in MEMORY.md.
+ */
+export function appendToMemorySection(section, line, memoryPath = DEFAULT_MEMORY_PATH) {
+    let content = fs.readFileSync(memoryPath, 'utf-8');
+    const marker = `## ${section}`;
+    const idx = content.indexOf(marker);
+    if (idx === -1) {
+        content += `\n## ${section}\n\n${line}\n`;
+    }
+    else {
+        const headerEnd = content.indexOf('\n', idx);
+        if (headerEnd === -1) {
+            content += `\n${line}\n`;
+        }
+        else {
+            let insertPos = headerEnd + 1;
+            const afterHeader = content.slice(insertPos);
+            const commentMatch = afterHeader.match(/^<!--.*?-->\n/);
+            if (commentMatch)
+                insertPos += commentMatch[0].length;
+            if (content[insertPos] === '\n')
+                insertPos += 1;
+            content = content.slice(0, insertPos) + line + '\n' + content.slice(insertPos);
+        }
+    }
+    fs.writeFileSync(memoryPath, content);
+}
+/**
+ * Check if the agent has a wallet address recorded.
+ * Note: This only checks MEMORY.md — the actual key is in the keystore.
+ */
+export function hasWalletRecord(memoryPath = DEFAULT_MEMORY_PATH) {
+    const mem = readMemory(memoryPath);
+    return !!mem['Address'];
+}
+/**
+ * Check if the agent is registered onchain.
+ */
+export function isRegistered(memoryPath = DEFAULT_MEMORY_PATH) {
+    const mem = readMemory(memoryPath);
+    return mem['Status'] === 'registered' && !!mem['Agent ID'];
+}

package/dist/proxy-auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * proxy-auth.ts
+ *
+ * Shared HMAC-SHA256 authentication utility for the keyring proxy.
+ * Used by both the proxy client (keystore.ts) and server (test/proxy/index.ts).
+ *
+ * Security features:
+ *   - HMAC-SHA256 over method + path + body + timestamp
+ *   - 30-second timestamp drift limit for replay protection
+ *   - Constant-time comparison via crypto.timingSafeEqual
+ */
+export interface HmacHeaders {
+    'X-Proxy-Timestamp': string;
+    'X-Proxy-Signature': string;
+}
+/**
+ * Compute HMAC-SHA256 headers for an outgoing request.
+ */
+export declare function computeHmac(secret: string, method: string, path: string, body: string): HmacHeaders;
+/**
+ * Verify an incoming HMAC-SHA256 signature.
+ * Returns { valid: true } or { valid: false, error: string }.
+ */
+export declare function verifyHmac(secret: string, method: string, path: string, body: string, timestamp: string, signature: string): {
+    valid: boolean;
+    error?: string;
+};

package/dist/proxy-auth.js

@@ -0,0 +1,58 @@
+/**
+ * proxy-auth.ts
+ *
+ * Shared HMAC-SHA256 authentication utility for the keyring proxy.
+ * Used by both the proxy client (keystore.ts) and server (test/proxy/index.ts).
+ *
+ * Security features:
+ *   - HMAC-SHA256 over method + path + body + timestamp
+ *   - 30-second timestamp drift limit for replay protection
+ *   - Constant-time comparison via crypto.timingSafeEqual
+ */
+import * as crypto from 'crypto';
+const MAX_DRIFT_MS = 30_000; // 30 seconds
+/**
+ * Compute HMAC-SHA256 headers for an outgoing request.
+ */
+export function computeHmac(secret, method, path, body) {
+    const timestamp = Date.now().toString();
+    const payload = `${method.toUpperCase()}\n${path}\n${timestamp}\n${body}`;
+    const signature = crypto
+        .createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    return {
+        'X-Proxy-Timestamp': timestamp,
+        'X-Proxy-Signature': signature,
+    };
+}
+/**
+ * Verify an incoming HMAC-SHA256 signature.
+ * Returns { valid: true } or { valid: false, error: string }.
+ */
+export function verifyHmac(secret, method, path, body, timestamp, signature) {
+    // Check timestamp drift
+    const ts = parseInt(timestamp, 10);
+    if (isNaN(ts))
+        return { valid: false, error: 'Invalid timestamp' };
+    const drift = Math.abs(Date.now() - ts);
+    if (drift > MAX_DRIFT_MS) {
+        return { valid: false, error: `Timestamp drift ${drift}ms exceeds ${MAX_DRIFT_MS}ms limit` };
+    }
+    // Recompute expected signature
+    const payload = `${method.toUpperCase()}\n${path}\n${timestamp}\n${body}`;
+    const expected = crypto
+        .createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    // Constant-time comparison
+    const sigBuf = Buffer.from(signature, 'utf-8');
+    const expBuf = Buffer.from(expected, 'utf-8');
+    if (sigBuf.length !== expBuf.length) {
+        return { valid: false, error: 'Signature mismatch' };
+    }
+    if (!crypto.timingSafeEqual(sigBuf, expBuf)) {
+        return { valid: false, error: 'Signature mismatch' };
+    }
+    return { valid: true };
+}

package/dist/registry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * registry.ts
+ *
+ * Agent Identity Registry reader.
+ * Provides functions to read agent profiles and reputation from on-chain registries.
+ *
+ * Dependencies:
+ *   npm install ethers
+ */
+import { ethers } from 'ethers';
+/** Service endpoint types defined in ERC-8004 */
+export type ServiceType = 'web' | 'A2A' | 'MCP' | 'OASF' | 'ENS' | 'DID' | 'email';
+/** Trust models defined in ERC-8004 */
+export type TrustModel = 'reputation' | 'crypto-economic' | 'tee-attestation';
+/** Predefined reputation feedback tags defined in ERC-8004 */
+export type ReputationTag = 'starred' | 'reachable' | 'ownerVerified' | 'uptime' | 'successRate' | 'responseTime' | 'blocktimeFreshness' | 'revenues' | 'tradingYield';
+export interface AgentService {
+    name: ServiceType | (string & {});
+    endpoint: string;
+    version?: string;
+}
+export interface AgentRegistration {
+    agentId: number;
+    agentRegistry: string;
+}
+export interface AgentMetadata {
+    name: string;
+    description: string;
+    image: string;
+    services: AgentService[];
+    active: boolean;
+    x402Support?: boolean;
+    supportedTrust?: (TrustModel | (string & {}))[];
+    registrations?: AgentRegistration[];
+}
+export interface AgentProfile {
+    agentId: number;
+    owner: string;
+    uri: string;
+    agentWallet: string | null;
+    metadata: AgentMetadata | null;
+}
+export interface GetAgentOptions {
+    registryAddress: string;
+    provider: ethers.Provider;
+    fetchMetadata?: boolean;
+}
+export interface ReputationSummary {
+    count: number;
+    score: number;
+    rawValue: bigint;
+    decimals: number;
+}
+export interface GetReputationOptions {
+    reputationRegistryAddress: string;
+    provider: ethers.Provider;
+    clients?: string[];
+    tag1?: ReputationTag | (string & {});
+    tag2?: string;
+}
+/**
+ * Read an agent from the Identity Registry and parse its profile.
+ *
+ * @param agentId  The on-chain agent token ID
+ * @param options  Registry address, provider, and optional fetchMetadata flag
+ */
+export declare function getAgent(agentId: number, options: GetAgentOptions): Promise<AgentProfile>;
+/**
+ * Read an agent's reputation summary from the Reputation Registry.
+ *
+ * @param agentId  The on-chain agent token ID
+ * @param options  Reputation registry address, provider, and optional filters
+ */
+export declare function getReputation(agentId: number, options: GetReputationOptions): Promise<ReputationSummary>;

package/dist/registry.js

@@ -0,0 +1,89 @@
+/**
+ * registry.ts
+ *
+ * Agent Identity Registry reader.
+ * Provides functions to read agent profiles and reputation from on-chain registries.
+ *
+ * Dependencies:
+ *   npm install ethers
+ */
+import { ethers } from 'ethers';
+// ─── ABI Fragments ──────────────────────────────────────────────────
+const IDENTITY_REGISTRY_ABI = [
+    'function ownerOf(uint256 tokenId) view returns (address)',
+    'function tokenURI(uint256 tokenId) view returns (string)',
+    'function getAgentWallet(uint256 agentId) view returns (address)',
+];
+const REPUTATION_REGISTRY_ABI = [
+    'function getSummary(uint256 agentId, address[] clients, string tag1, string tag2) view returns (uint64 count, int128 summaryValue, uint8 valueDecimals)',
+];
+// ─── Internal Helpers ───────────────────────────────────────────────
+const IPFS_GATEWAY = 'https://gateway.pinata.cloud/ipfs/';
+/**
+ * Resolve a URI to its JSON content.
+ * Supports ipfs://, data:application/json;base64, and http(s):// schemes.
+ */
+async function resolveURI(uri) {
+    if (uri.startsWith('ipfs://')) {
+        const cid = uri.slice('ipfs://'.length);
+        const response = await fetch(`${IPFS_GATEWAY}${cid}`);
+        if (!response.ok)
+            throw new Error(`IPFS fetch failed: ${response.status}`);
+        return response.json();
+    }
+    if (uri.startsWith('data:application/json;base64,')) {
+        const base64 = uri.slice('data:application/json;base64,'.length);
+        const json = Buffer.from(base64, 'base64').toString('utf-8');
+        return JSON.parse(json);
+    }
+    if (uri.startsWith('http://') || uri.startsWith('https://')) {
+        const response = await fetch(uri);
+        if (!response.ok)
+            throw new Error(`HTTP fetch failed: ${response.status}`);
+        return response.json();
+    }
+    throw new Error(`Unsupported URI scheme: ${uri}`);
+}
+// ─── Public API ─────────────────────────────────────────────────────
+/**
+ * Read an agent from the Identity Registry and parse its profile.
+ *
+ * @param agentId  The on-chain agent token ID
+ * @param options  Registry address, provider, and optional fetchMetadata flag
+ */
+export async function getAgent(agentId, options) {
+    const { registryAddress, provider, fetchMetadata = true } = options;
+    const registry = new ethers.Contract(registryAddress, IDENTITY_REGISTRY_ABI, provider);
+    const [owner, uri, walletAddr] = await Promise.all([
+        registry.ownerOf(agentId),
+        registry.tokenURI(agentId),
+        registry.getAgentWallet(agentId),
+    ]);
+    const agentWallet = walletAddr === ethers.ZeroAddress ? null : walletAddr;
+    let metadata = null;
+    if (fetchMetadata) {
+        try {
+            const raw = await resolveURI(uri);
+            metadata = raw;
+        }
+        catch {
+            metadata = null;
+        }
+    }
+    return { agentId, owner, uri, agentWallet, metadata };
+}
+/**
+ * Read an agent's reputation summary from the Reputation Registry.
+ *
+ * @param agentId  The on-chain agent token ID
+ * @param options  Reputation registry address, provider, and optional filters
+ */
+export async function getReputation(agentId, options) {
+    const { reputationRegistryAddress, provider, clients = [], tag1 = '', tag2 = '', } = options;
+    const reputation = new ethers.Contract(reputationRegistryAddress, REPUTATION_REGISTRY_ABI, provider);
+    const [count, summaryValue, valueDecimals] = await reputation.getSummary(agentId, clients, tag1, tag2);
+    const decimals = Number(valueDecimals);
+    const rawValue = BigInt(summaryValue);
+    const score = Number(rawValue) / 10 ** decimals;
+    return { count: Number(count), score, rawValue, decimals };
+}

package/dist/siwa.d.ts

@@ -0,0 +1,99 @@
+/**
+ * siwa.ts
+ *
+ * SIWA (Sign In With Agent) utility functions.
+ * Provides message building, signing (agent-side), and verification (server-side).
+ *
+ * Dependencies:
+ *   npm install ethers
+ */
+import { ethers } from 'ethers';
+import { AgentProfile, ServiceType, TrustModel } from './registry.js';
+export interface SIWAMessageFields {
+    domain: string;
+    address: string;
+    statement?: string;
+    uri: string;
+    version?: string;
+    agentId: number;
+    agentRegistry: string;
+    chainId: number;
+    nonce: string;
+    issuedAt: string;
+    expirationTime?: string;
+    notBefore?: string;
+    requestId?: string;
+}
+export interface SIWAVerificationResult {
+    valid: boolean;
+    address: string;
+    agentId: number;
+    agentRegistry: string;
+    chainId: number;
+    error?: string;
+    agent?: AgentProfile;
+}
+export interface SIWAVerifyCriteria {
+    minScore?: number;
+    minFeedbackCount?: number;
+    reputationRegistryAddress?: string;
+    requiredServices?: (ServiceType | (string & {}))[];
+    mustBeActive?: boolean;
+    requiredTrust?: (TrustModel | (string & {}))[];
+    custom?: (agent: AgentProfile) => boolean | Promise<boolean>;
+}
+/**
+ * Build a SIWA plaintext message string from structured fields.
+ */
+export declare function buildSIWAMessage(fields: SIWAMessageFields): string;
+/**
+ * Parse a SIWA message string back into structured fields.
+ */
+export declare function parseSIWAMessage(message: string): SIWAMessageFields;
+/**
+ * Generate a cryptographically secure nonce (≥ 8 alphanumeric characters).
+ */
+export declare function generateNonce(length?: number): string;
+/**
+ * Sign a SIWA message using the secure keystore.
+ *
+ * The private key is loaded from the keystore, used to sign, and discarded.
+ * It is NEVER returned or exposed to the caller.
+ *
+ * @param fields — SIWA message fields (domain, agentId, etc.)
+ * @param keystoreConfig — Optional keystore configuration override
+ * @returns { message, signature } — only the plaintext message and EIP-191 signature
+ */
+export declare function signSIWAMessage(fields: SIWAMessageFields, keystoreConfig?: import('./keystore').KeystoreConfig): Promise<{
+    message: string;
+    signature: string;
+}>;
+/**
+ * Sign a SIWA message using a raw private key.
+ * ⚠️ DEPRECATED: Use signSIWAMessage() with keystore instead.
+ * Kept only for server-side testing or environments without keystore.
+ */
+export declare function signSIWAMessageUnsafe(privateKey: string, fields: SIWAMessageFields): Promise<{
+    message: string;
+    signature: string;
+}>;
+/**
+ * Verify a SIWA message + signature.
+ *
+ * Checks:
+ * 1. Message format validity
+ * 2. Signature → address recovery
+ * 3. Address matches message
+ * 4. Domain matches expected domain
+ * 5. Nonce matches (caller must validate against their nonce store)
+ * 6. Time window (expirationTime / notBefore)
+ * 7. Onchain: ownerOf(agentId) === recovered address
+ *
+ * @param message    Full SIWA message string
+ * @param signature  EIP-191 signature hex string
+ * @param expectedDomain  The server's domain (for domain binding)
+ * @param nonceValid  Callback that returns true if the nonce is valid and unconsumed
+ * @param provider   ethers Provider for onchain verification
+ * @param criteria   Optional criteria to validate agent profile/reputation after ownership check
+ */
+export declare function verifySIWA(message: string, signature: string, expectedDomain: string, nonceValid: (nonce: string) => boolean | Promise<boolean>, provider: ethers.Provider, criteria?: SIWAVerifyCriteria): Promise<SIWAVerificationResult>;