@buildersgarden/siwa 0.0.7 → 0.0.9

package/README.md

@@ -6,7 +6,7 @@ A Claude Code skill for registering AI agents on the [ERC-8004 (Trustless Agents
 
 - **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
+- **Authenticate (Sign In)** — Prove ownership of an onchain agent identity by signing a structured SIWA message; receive a verification receipt from the relying party and use ERC-8128 per-request signatures for subsequent API calls
 
 ## Project Structure
 
@@ -18,6 +18,8 @@ src/               Core SDK modules
   proxy-auth.ts      HMAC-SHA256 authentication utilities
   registry.ts        Onchain agent profile & reputation lookups
   addresses.ts       Deployed contract addresses
+  receipt.ts         Stateless HMAC receipt creation and verification
+  erc8128.ts         ERC-8128 HTTP Message Signatures (sign/verify)
 
 references/        Protocol documentation
   siwa-spec.md       Full SIWA specification
@@ -26,13 +28,14 @@ references/        Protocol documentation
 assets/            Templates
   IDENTITY.template.md
 
-test/              Local test environment (Express server + CLI agent)
 ```
 
 ## Quick Start (Local Test)
 
+The test harness lives in the `siwa-testing` package (sibling in this monorepo):
+
 ```bash
-cd test
+cd packages/siwa-testing
 pnpm install
 
 # Terminal 1: Start the SIWA relying-party server
@@ -45,7 +48,7 @@ pnpm run agent:flow
 pnpm run dev
 ```
 
-See [`test/README.md`](test/README.md) for full details on the test environment.
+See [`packages/siwa-testing/README.md`](../siwa-testing/README.md) for full details on the test environment.
 
 ## Security Model
 

package/dist/erc8128.d.ts

@@ -0,0 +1,104 @@
+/**
+ * erc8128.ts
+ *
+ * Full ERC-8128 HTTP Message Signatures integration for SIWA.
+ *
+ * The SDK fully abstracts `@slicekit/erc8128`. Platform developers call:
+ *   - signAuthenticatedRequest()   — agent-side: attach receipt + sign request
+ *   - verifyAuthenticatedRequest() — server-side: verify signature + receipt + optional onchain
+ *
+ * These are the two main entry points. Everything else is internal.
+ */
+import type { PublicClient } from 'viem';
+import { type EthHttpSigner } from '@slicekit/erc8128';
+import { type KeystoreConfig } from './keystore.js';
+export interface VerifyOptions {
+    receiptSecret: string;
+    rpcUrl?: string;
+    verifyOnchain?: boolean;
+    publicClient?: PublicClient;
+}
+export type AuthResult = {
+    valid: true;
+    agent: {
+        address: string;
+        agentId: number;
+        agentRegistry: string;
+        chainId: number;
+    };
+} | {
+    valid: false;
+    error: string;
+};
+/** Header name for the verification receipt */
+export declare const RECEIPT_HEADER = "X-SIWA-Receipt";
+/**
+ * Create an ERC-8128 signer backed by the keyring proxy.
+ *
+ * The `signMessage` callback converts the RFC 9421 signature base
+ * (Uint8Array) to a hex string and delegates to the proxy via
+ * `signRawMessage`, which signs with `{ raw: true }`.
+ */
+export declare function createProxySigner(config: KeystoreConfig, chainId: number): Promise<EthHttpSigner>;
+/**
+ * Attach a verification receipt to a request.
+ *
+ * Sets the `X-SIWA-Receipt` header.
+ */
+export declare function attachReceipt(request: Request, receipt: string): Request;
+/**
+ * Sign an authenticated request: attach receipt + ERC-8128 signature.
+ *
+ * This is the main function platform developers use on the agent side.
+ * One call does everything:
+ *   1. Attaches the receipt header
+ *   2. Creates a proxy-backed ERC-8128 signer
+ *   3. Signs the request with HTTP Message Signatures (RFC 9421)
+ *
+ * @param request  The outgoing Request object
+ * @param receipt  Verification receipt from SIWA sign-in
+ * @param config   Keystore config (proxy URL + secret)
+ * @param chainId  Chain ID for the ERC-8128 keyid
+ * @returns        A new Request with Signature, Signature-Input, Content-Digest, and X-SIWA-Receipt headers
+ */
+export declare function signAuthenticatedRequest(request: Request, receipt: string, config: KeystoreConfig, chainId: number): Promise<Request>;
+/**
+ * Verify an authenticated request: ERC-8128 signature + receipt + optional onchain check.
+ *
+ * This is the main function platform developers use on the server side.
+ * One call does everything:
+ *   1. Extracts and verifies the HMAC receipt
+ *   2. Verifies the ERC-8128 HTTP signature (recovers signer address)
+ *   3. Checks that the signer address matches the receipt address
+ *   4. Optionally does an onchain ownerOf check
+ *
+ * @param request  The incoming Request object (with Signature + X-SIWA-Receipt headers)
+ * @param options  Verification options (receipt secret, optional onchain settings)
+ * @returns        `{ valid: true, agent }` or `{ valid: false, error }`
+ */
+export declare function verifyAuthenticatedRequest(request: Request, options: VerifyOptions): Promise<AuthResult>;
+/**
+ * Convert an Express request to a Fetch API Request.
+ *
+ * Needed because ERC-8128 operates on the Fetch `Request` object,
+ * but Express uses its own request type.
+ *
+ * @param req  Express request object (must have `rawBody` for Content-Digest verification)
+ */
+export declare function expressToFetchRequest(req: {
+    method: string;
+    protocol: string;
+    get: (name: string) => string | undefined;
+    originalUrl: string;
+    headers: Record<string, string | string[] | undefined>;
+    rawBody?: string;
+}): Request;
+/**
+ * Normalize a Next.js/serverless Request for ERC-8128 verification.
+ *
+ * Behind reverse proxies (Vercel, Railway, Cloudflare), the request URL
+ * may reflect internal routing instead of the public origin. This helper
+ * reads X-Forwarded-Host / X-Forwarded-Proto headers and reconstructs
+ * the URL to match what the agent signed.
+ */
+export declare function nextjsToFetchRequest(req: Request): Request;

package/dist/erc8128.js

@@ -0,0 +1,260 @@
+/**
+ * erc8128.ts
+ *
+ * Full ERC-8128 HTTP Message Signatures integration for SIWA.
+ *
+ * The SDK fully abstracts `@slicekit/erc8128`. Platform developers call:
+ *   - signAuthenticatedRequest()   — agent-side: attach receipt + sign request
+ *   - verifyAuthenticatedRequest() — server-side: verify signature + receipt + optional onchain
+ *
+ * These are the two main entry points. Everything else is internal.
+ */
+import { signRequest, verifyRequest, } from '@slicekit/erc8128';
+import { signRawMessage, getAddress } from './keystore.js';
+import { verifyReceipt } from './receipt.js';
+/** Header name for the verification receipt */
+export const RECEIPT_HEADER = 'X-SIWA-Receipt';
+// ---------------------------------------------------------------------------
+// Agent-side: signer creation
+// ---------------------------------------------------------------------------
+/**
+ * Create an ERC-8128 signer backed by the keyring proxy.
+ *
+ * The `signMessage` callback converts the RFC 9421 signature base
+ * (Uint8Array) to a hex string and delegates to the proxy via
+ * `signRawMessage`, which signs with `{ raw: true }`.
+ */
+export async function createProxySigner(config, chainId) {
+    const address = await getAddress(config);
+    if (!address)
+        throw new Error('No wallet found in keystore');
+    return {
+        address: address,
+        chainId,
+        signMessage: async (message) => {
+            const hex = ('0x' + Array.from(message).map(b => b.toString(16).padStart(2, '0')).join(''));
+            const result = await signRawMessage(hex, config);
+            return result.signature;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Agent-side: high-level request signing
+// ---------------------------------------------------------------------------
+/**
+ * Attach a verification receipt to a request.
+ *
+ * Sets the `X-SIWA-Receipt` header.
+ */
+export function attachReceipt(request, receipt) {
+    const headers = new Headers(request.headers);
+    headers.set(RECEIPT_HEADER, receipt);
+    return new Request(request, { headers });
+}
+/**
+ * Sign an authenticated request: attach receipt + ERC-8128 signature.
+ *
+ * This is the main function platform developers use on the agent side.
+ * One call does everything:
+ *   1. Attaches the receipt header
+ *   2. Creates a proxy-backed ERC-8128 signer
+ *   3. Signs the request with HTTP Message Signatures (RFC 9421)
+ *
+ * @param request  The outgoing Request object
+ * @param receipt  Verification receipt from SIWA sign-in
+ * @param config   Keystore config (proxy URL + secret)
+ * @param chainId  Chain ID for the ERC-8128 keyid
+ * @returns        A new Request with Signature, Signature-Input, Content-Digest, and X-SIWA-Receipt headers
+ */
+export async function signAuthenticatedRequest(request, receipt, config, chainId) {
+    // 1. Attach receipt header
+    const withReceipt = attachReceipt(request, receipt);
+    // 2. Create proxy-backed signer
+    const signer = await createProxySigner(config, chainId);
+    // 3. Sign with ERC-8128 (includes Content-Digest for bodies)
+    return signRequest(withReceipt, signer);
+}
+// ---------------------------------------------------------------------------
+// Server-side: high-level request verification
+// ---------------------------------------------------------------------------
+/**
+ * In-memory nonce store for ERC-8128 replay protection.
+ *
+ * Uses a Map with TTL-based expiry. For production, replace with Redis
+ * or another persistent store via the NonceStore interface.
+ */
+function createMemoryNonceStore() {
+    const seen = new Map(); // key → expiry timestamp (ms)
+    return {
+        async consume(key, ttlSeconds) {
+            // Lazy cleanup of expired entries
+            const now = Date.now();
+            for (const [k, expiry] of seen) {
+                if (expiry < now)
+                    seen.delete(k);
+            }
+            if (seen.has(key))
+                return false; // replay
+            seen.set(key, now + ttlSeconds * 1000);
+            return true;
+        },
+    };
+}
+/** Singleton nonce store — shared across the server process */
+const nonceStore = createMemoryNonceStore();
+/**
+ * Verify an authenticated request: ERC-8128 signature + receipt + optional onchain check.
+ *
+ * This is the main function platform developers use on the server side.
+ * One call does everything:
+ *   1. Extracts and verifies the HMAC receipt
+ *   2. Verifies the ERC-8128 HTTP signature (recovers signer address)
+ *   3. Checks that the signer address matches the receipt address
+ *   4. Optionally does an onchain ownerOf check
+ *
+ * @param request  The incoming Request object (with Signature + X-SIWA-Receipt headers)
+ * @param options  Verification options (receipt secret, optional onchain settings)
+ * @returns        `{ valid: true, agent }` or `{ valid: false, error }`
+ */
+export async function verifyAuthenticatedRequest(request, options) {
+    // 1. Extract and verify receipt
+    const receiptToken = request.headers.get(RECEIPT_HEADER);
+    if (!receiptToken) {
+        return { valid: false, error: 'Missing X-SIWA-Receipt header' };
+    }
+    const receipt = verifyReceipt(receiptToken, options.receiptSecret);
+    if (!receipt) {
+        return { valid: false, error: 'Invalid or expired receipt' };
+    }
+    // 2. Verify ERC-8128 signature
+    const { verifyMessage } = await import('viem');
+    const verifyResult = await verifyRequest(request, async (args) => {
+        // If a publicClient is provided, use it for ERC-1271 support
+        if (options.publicClient) {
+            return options.publicClient.verifyMessage({
+                address: args.address,
+                message: args.message,
+                signature: args.signature,
+            });
+        }
+        // Fallback to pure EOA verification
+        return verifyMessage({
+            address: args.address,
+            message: args.message,
+            signature: args.signature,
+        });
+    }, nonceStore);
+    if (!verifyResult.ok) {
+        return { valid: false, error: `ERC-8128 verification failed: ${verifyResult.reason}${verifyResult.detail ? ` (${verifyResult.detail})` : ''}` };
+    }
+    // 3. Address match: signer must match receipt
+    if (verifyResult.address.toLowerCase() !== receipt.address.toLowerCase()) {
+        return { valid: false, error: 'Signer address does not match receipt address' };
+    }
+    // 4. Optional onchain check
+    if (options.verifyOnchain) {
+        const client = options.publicClient ?? (await createOnchainClient(options.rpcUrl));
+        if (!client) {
+            return { valid: false, error: 'Onchain verification requested but no RPC URL or publicClient provided' };
+        }
+        const registryParts = receipt.agentRegistry.split(':');
+        if (registryParts.length !== 3 || registryParts[0] !== 'eip155') {
+            return { valid: false, error: 'Invalid agentRegistry format in receipt' };
+        }
+        const registryAddress = registryParts[2];
+        try {
+            const owner = 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(receipt.agentId)],
+            });
+            if (owner.toLowerCase() !== receipt.address.toLowerCase()) {
+                return { valid: false, error: 'Onchain ownership check failed: signer is not the NFT owner' };
+            }
+        }
+        catch {
+            return { valid: false, error: 'Onchain ownership check failed: agent not registered' };
+        }
+    }
+    return {
+        valid: true,
+        agent: {
+            address: receipt.address,
+            agentId: receipt.agentId,
+            agentRegistry: receipt.agentRegistry,
+            chainId: receipt.chainId,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+/**
+ * Convert an Express request to a Fetch API Request.
+ *
+ * Needed because ERC-8128 operates on the Fetch `Request` object,
+ * but Express uses its own request type.
+ *
+ * @param req  Express request object (must have `rawBody` for Content-Digest verification)
+ */
+export function expressToFetchRequest(req) {
+    const host = req.get('host') || 'localhost';
+    const url = `${req.protocol}://${host}${req.originalUrl}`;
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                headers.append(key, v);
+        }
+        else {
+            headers.set(key, value);
+        }
+    }
+    const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+    return new Request(url, {
+        method: req.method,
+        headers,
+        body: hasBody ? (req.rawBody ?? null) : null,
+    });
+}
+/**
+ * Normalize a Next.js/serverless Request for ERC-8128 verification.
+ *
+ * Behind reverse proxies (Vercel, Railway, Cloudflare), the request URL
+ * may reflect internal routing instead of the public origin. This helper
+ * reads X-Forwarded-Host / X-Forwarded-Proto headers and reconstructs
+ * the URL to match what the agent signed.
+ */
+export function nextjsToFetchRequest(req) {
+    const forwardedHost = req.headers.get('x-forwarded-host') || req.headers.get('host');
+    const forwardedProto = req.headers.get('x-forwarded-proto') || 'https';
+    if (!forwardedHost)
+        return req; // no proxy headers, return as-is
+    const url = new URL(req.url);
+    const publicUrl = `${forwardedProto}://${forwardedHost}${url.pathname}${url.search}`;
+    return new Request(publicUrl, {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        // @ts-ignore - duplex required for streaming bodies in Node 18+
+        duplex: 'half',
+    });
+}
+/**
+ * Lazily create a viem PublicClient from an RPC URL.
+ */
+async function createOnchainClient(rpcUrl) {
+    if (!rpcUrl)
+        return null;
+    const { createPublicClient, http } = await import('viem');
+    return createPublicClient({ transport: http(rpcUrl) });
+}

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export * from './identity.js';
 export * from './proxy-auth.js';
 export * from './registry.js';
 export * from './addresses.js';
+export * from './receipt.js';
+export * from './erc8128.js';

package/dist/index.js

@@ -4,3 +4,5 @@ export * from './identity.js';
 export * from './proxy-auth.js';
 export * from './registry.js';
 export * from './addresses.js';
+export * from './receipt.js';
+export * from './erc8128.js';

package/dist/keystore.d.ts

@@ -75,6 +75,15 @@ export declare function getAddress(config?: KeystoreConfig): Promise<string | nu
  * Only the signature is returned.
  */
 export declare function signMessage(message: string, config?: KeystoreConfig): Promise<SignResult>;
+/**
+ * Sign a raw hex message via the keyring proxy.
+ *
+ * Used internally by the ERC-8128 signer — the signature base bytes are
+ * passed as a hex string and signed with `{ raw: true }` so the proxy
+ * interprets them as raw bytes (not UTF-8). Note: the proxy still applies
+ * EIP-191 personal_sign wrapping (viem `signMessage({ message: { raw } })`).
+ */
+export declare function signRawMessage(rawHex: string, config?: KeystoreConfig): Promise<SignResult>;
 /**
  * Sign a transaction via the keyring proxy.
  * Only the signed transaction is returned.

package/dist/keystore.js

@@ -80,6 +80,21 @@ export async function signMessage(message, config = {}) {
     const data = await proxyRequest(config, "/sign-message", { message: msg });
     return { signature: data.signature, address: data.address };
 }
+/**
+ * Sign a raw hex message via the keyring proxy.
+ *
+ * Used internally by the ERC-8128 signer — the signature base bytes are
+ * passed as a hex string and signed with `{ raw: true }` so the proxy
+ * interprets them as raw bytes (not UTF-8). Note: the proxy still applies
+ * EIP-191 personal_sign wrapping (viem `signMessage({ message: { raw } })`).
+ */
+export async function signRawMessage(rawHex, config = {}) {
+    const data = await proxyRequest(config, "/sign-message", {
+        message: rawHex,
+        raw: true,
+    });
+    return { signature: data.signature, address: data.address };
+}
 /**
  * Sign a transaction via the keyring proxy.
  * Only the signed transaction is returned.

package/dist/receipt.d.ts

@@ -0,0 +1,53 @@
+/**
+ * receipt.ts
+ *
+ * Stateless HMAC-signed verification receipts.
+ *
+ * A receipt proves that onchain registration was checked during SIWA sign-in.
+ * It is issued after successful verification and attached to every subsequent
+ * request alongside an ERC-8128 HTTP signature.
+ *
+ * Receipt alone is useless (can't forge signatures).
+ * Signature alone is insufficient (proves key control, not registration).
+ * Together = authentication + authorization.
+ *
+ * Format: base64url(json).base64url(hmac-sha256)
+ * Same token format as nonce tokens in siwa.ts.
+ */
+export interface ReceiptPayload {
+    address: string;
+    agentId: number;
+    agentRegistry: string;
+    chainId: number;
+    verified: 'offline' | 'onchain';
+    iat: number;
+    exp: number;
+}
+export interface ReceiptOptions {
+    secret: string;
+    ttl?: number;
+}
+export interface ReceiptResult {
+    receipt: string;
+    expiresAt: string;
+}
+/** Default receipt validity: 30 minutes */
+export declare const DEFAULT_RECEIPT_TTL: number;
+/**
+ * Create an HMAC-signed receipt token.
+ *
+ * @param payload  Agent identity fields from a successful SIWA verification
+ * @param options  HMAC secret and optional TTL override
+ * @returns        `{ receipt, expiresAt }` — the token and its ISO expiry
+ */
+export declare function createReceipt(payload: Omit<ReceiptPayload, 'iat' | 'exp'>, options: ReceiptOptions): ReceiptResult;
+/**
+ * Verify and decode a receipt token.
+ *
+ * Uses constant-time comparison and checks expiry.
+ *
+ * @param receipt  The `base64url(json).base64url(hmac)` token
+ * @param secret   HMAC secret used to sign the receipt
+ * @returns        Decoded payload, or `null` if invalid/expired
+ */
+export declare function verifyReceipt(receipt: string, secret: string): ReceiptPayload | null;

package/dist/receipt.js

@@ -0,0 +1,80 @@
+/**
+ * receipt.ts
+ *
+ * Stateless HMAC-signed verification receipts.
+ *
+ * A receipt proves that onchain registration was checked during SIWA sign-in.
+ * It is issued after successful verification and attached to every subsequent
+ * request alongside an ERC-8128 HTTP signature.
+ *
+ * Receipt alone is useless (can't forge signatures).
+ * Signature alone is insufficient (proves key control, not registration).
+ * Together = authentication + authorization.
+ *
+ * Format: base64url(json).base64url(hmac-sha256)
+ * Same token format as nonce tokens in siwa.ts.
+ */
+import * as crypto from 'crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default receipt validity: 30 minutes */
+export const DEFAULT_RECEIPT_TTL = 30 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+/**
+ * Create an HMAC-signed receipt token.
+ *
+ * @param payload  Agent identity fields from a successful SIWA verification
+ * @param options  HMAC secret and optional TTL override
+ * @returns        `{ receipt, expiresAt }` — the token and its ISO expiry
+ */
+export function createReceipt(payload, options) {
+    const now = Date.now();
+    const ttl = options.ttl ?? DEFAULT_RECEIPT_TTL;
+    const exp = now + ttl;
+    const full = {
+        ...payload,
+        iat: now,
+        exp,
+    };
+    const data = Buffer.from(JSON.stringify(full)).toString('base64url');
+    const sig = crypto.createHmac('sha256', options.secret).update(data).digest('base64url');
+    return {
+        receipt: `${data}.${sig}`,
+        expiresAt: new Date(exp).toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Verify
+// ---------------------------------------------------------------------------
+/**
+ * Verify and decode a receipt token.
+ *
+ * Uses constant-time comparison and checks expiry.
+ *
+ * @param receipt  The `base64url(json).base64url(hmac)` token
+ * @param secret   HMAC secret used to sign the receipt
+ * @returns        Decoded payload, or `null` if invalid/expired
+ */
+export function verifyReceipt(receipt, secret) {
+    const dotIdx = receipt.indexOf('.');
+    if (dotIdx === -1)
+        return null;
+    const data = receipt.slice(0, dotIdx);
+    const sig = receipt.slice(dotIdx + 1);
+    if (!data || !sig)
+        return null;
+    const expected = crypto.createHmac('sha256', secret).update(data).digest('base64url');
+    // Constant-time comparison
+    if (sig.length !== expected.length)
+        return null;
+    if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
+        return null;
+    // Decode and check expiry
+    const payload = JSON.parse(Buffer.from(data, 'base64url').toString());
+    if (payload.exp < Date.now())
+        return null;
+    return payload;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildersgarden/siwa",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "exports": {
     ".": {
@@ -30,6 +30,14 @@
     "./addresses": {
       "types": "./dist/addresses.d.ts",
       "default": "./dist/addresses.js"
+    },
+    "./receipt": {
+      "types": "./dist/receipt.d.ts",
+      "default": "./dist/receipt.js"
+    },
+    "./erc8128": {
+      "types": "./dist/erc8128.d.ts",
+      "default": "./dist/erc8128.js"
     }
   },
   "main": "./dist/index.js",
@@ -50,6 +58,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@slicekit/erc8128": "^0.1.0",
     "viem": "^2.21.0"
   },
   "devDependencies": {