@buildersgarden/siwa 0.0.9 → 0.0.11

package/dist/erc8128.d.ts

@@ -18,18 +18,26 @@ export interface VerifyOptions {
     verifyOnchain?: boolean;
     publicClient?: PublicClient;
 }
+/** Verified agent identity returned from a successful auth check. */
+export interface SiwaAgent {
+    address: string;
+    agentId: number;
+    agentRegistry: string;
+    chainId: number;
+}
 export type AuthResult = {
     valid: true;
-    agent: {
-        address: string;
-        agentId: number;
-        agentRegistry: string;
-        chainId: number;
-    };
+    agent: SiwaAgent;
 } | {
     valid: false;
     error: string;
 };
+/**
+ * Resolve the receipt secret from an explicit value or environment variables.
+ *
+ * Checks (in order): `explicit` → `RECEIPT_SECRET` env → `SIWA_SECRET` env → throws.
+ */
+export declare function resolveReceiptSecret(explicit?: string): string;
 /** Header name for the verification receipt */
 export declare const RECEIPT_HEADER = "X-SIWA-Receipt";
 /**

package/dist/erc8128.js

@@ -12,6 +12,18 @@
 import { signRequest, verifyRequest, } from '@slicekit/erc8128';
 import { signRawMessage, getAddress } from './keystore.js';
 import { verifyReceipt } from './receipt.js';
+/**
+ * Resolve the receipt secret from an explicit value or environment variables.
+ *
+ * Checks (in order): `explicit` → `RECEIPT_SECRET` env → `SIWA_SECRET` env → throws.
+ */
+export function resolveReceiptSecret(explicit) {
+    const secret = explicit || process.env.RECEIPT_SECRET || process.env.SIWA_SECRET;
+    if (!secret) {
+        throw new Error('Missing receipt secret: pass receiptSecret option, or set RECEIPT_SECRET / SIWA_SECRET env var');
+    }
+    return secret;
+}
 /** Header name for the verification receipt */
 export const RECEIPT_HEADER = 'X-SIWA-Receipt';
 // ---------------------------------------------------------------------------

package/dist/express.d.ts

@@ -0,0 +1,61 @@
+/**
+ * express.ts
+ *
+ * Server-side wrappers for Express applications.
+ *
+ * @example
+ * ```ts
+ * import { siwaMiddleware, siwaJsonParser, siwaCors } from "@buildersgarden/siwa/express";
+ *
+ * app.use(siwaJsonParser());
+ * app.use(siwaCors());
+ * app.get('/api/protected', siwaMiddleware(), (req, res) => {
+ *   res.json({ agent: req.agent });
+ * });
+ * ```
+ */
+import type { RequestHandler } from 'express';
+import { type SiwaAgent, type VerifyOptions } from './erc8128.js';
+export type { SiwaAgent };
+declare global {
+    namespace Express {
+        interface Request {
+            agent?: SiwaAgent;
+            rawBody?: string;
+        }
+    }
+}
+export interface SiwaMiddlewareOptions {
+    /** HMAC secret for receipt verification. Defaults to RECEIPT_SECRET or SIWA_SECRET env. */
+    receiptSecret?: string;
+    /** RPC URL for optional onchain verification. */
+    rpcUrl?: string;
+    /** Enable onchain ownerOf check. */
+    verifyOnchain?: boolean;
+    /** Public client for ERC-1271 or onchain checks. */
+    publicClient?: VerifyOptions['publicClient'];
+}
+export interface SiwaCorsOptions {
+    /** Allowed origin(s). Defaults to "*". */
+    origin?: string;
+    /** Allowed HTTP methods. */
+    methods?: string;
+    /** Allowed headers. */
+    headers?: string;
+}
+/**
+ * CORS middleware pre-configured with SIWA-specific headers.
+ * Handles OPTIONS preflight automatically.
+ */
+export declare function siwaCors(options?: SiwaCorsOptions): RequestHandler;
+/**
+ * `express.json()` pre-configured with rawBody capture for Content-Digest verification.
+ */
+export declare function siwaJsonParser(): RequestHandler;
+/**
+ * Express middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
+ *
+ * On success, sets `req.agent` with the verified agent identity.
+ * On failure, responds with 401.
+ */
+export declare function siwaMiddleware(options?: SiwaMiddlewareOptions): RequestHandler;

package/dist/express.js

@@ -0,0 +1,93 @@
+/**
+ * express.ts
+ *
+ * Server-side wrappers for Express applications.
+ *
+ * @example
+ * ```ts
+ * import { siwaMiddleware, siwaJsonParser, siwaCors } from "@buildersgarden/siwa/express";
+ *
+ * app.use(siwaJsonParser());
+ * app.use(siwaCors());
+ * app.get('/api/protected', siwaMiddleware(), (req, res) => {
+ *   res.json({ agent: req.agent });
+ * });
+ * ```
+ */
+import express from 'express';
+import { verifyAuthenticatedRequest, expressToFetchRequest, resolveReceiptSecret, } from './erc8128.js';
+// ---------------------------------------------------------------------------
+// CORS middleware
+// ---------------------------------------------------------------------------
+const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest';
+/**
+ * CORS middleware pre-configured with SIWA-specific headers.
+ * Handles OPTIONS preflight automatically.
+ */
+export function siwaCors(options) {
+    const origin = options?.origin ?? '*';
+    const methods = options?.methods ?? 'GET, POST, OPTIONS';
+    const headers = options?.headers ?? DEFAULT_SIWA_HEADERS;
+    return (req, res, next) => {
+        res.header('Access-Control-Allow-Origin', origin);
+        res.header('Access-Control-Allow-Methods', methods);
+        res.header('Access-Control-Allow-Headers', headers);
+        if (req.method === 'OPTIONS') {
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    };
+}
+// ---------------------------------------------------------------------------
+// JSON parser with rawBody capture
+// ---------------------------------------------------------------------------
+/**
+ * `express.json()` pre-configured with rawBody capture for Content-Digest verification.
+ */
+export function siwaJsonParser() {
+    return express.json({
+        verify: (req, _res, buf) => {
+            req.rawBody = buf.toString();
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Auth middleware
+// ---------------------------------------------------------------------------
+/**
+ * Express middleware that verifies ERC-8128 HTTP Message Signatures + SIWA receipt.
+ *
+ * On success, sets `req.agent` with the verified agent identity.
+ * On failure, responds with 401.
+ */
+export function siwaMiddleware(options) {
+    return async (req, res, next) => {
+        const hasSignature = req.headers['signature'] && req.headers['x-siwa-receipt'];
+        if (!hasSignature) {
+            res.status(401).json({
+                error: 'Unauthorized — provide ERC-8128 Signature + X-SIWA-Receipt headers',
+            });
+            return;
+        }
+        try {
+            const secret = resolveReceiptSecret(options?.receiptSecret);
+            const fetchReq = expressToFetchRequest(req);
+            const result = await verifyAuthenticatedRequest(fetchReq, {
+                receiptSecret: secret,
+                rpcUrl: options?.rpcUrl,
+                verifyOnchain: options?.verifyOnchain,
+                publicClient: options?.publicClient,
+            });
+            if (!result.valid) {
+                res.status(401).json({ error: result.error });
+                return;
+            }
+            req.agent = result.agent;
+            next();
+        }
+        catch (err) {
+            res.status(401).json({ error: `ERC-8128 auth failed: ${err.message}` });
+        }
+    };
+}

package/dist/next.d.ts

@@ -0,0 +1,46 @@
+/**
+ * next.ts
+ *
+ * Server-side wrappers for Next.js App Router route handlers.
+ * Uses only web standard APIs (Request, Response, Headers) — no `next` dependency needed.
+ *
+ * @example
+ * ```ts
+ * import { withSiwa, siwaOptions } from "@buildersgarden/siwa/next";
+ *
+ * export const POST = withSiwa(async (agent, req) => {
+ *   const body = await req.json();
+ *   return { received: body, agent: { address: agent.address, agentId: agent.agentId } };
+ * });
+ *
+ * export { siwaOptions as OPTIONS };
+ * ```
+ */
+import { type SiwaAgent } from './erc8128.js';
+export type { SiwaAgent };
+export interface WithSiwaOptions {
+    /** HMAC secret for receipt verification. Defaults to RECEIPT_SECRET or SIWA_SECRET env. */
+    receiptSecret?: string;
+    /** RPC URL for optional onchain verification. */
+    rpcUrl?: string;
+    /** Enable onchain ownerOf check. */
+    verifyOnchain?: boolean;
+}
+/** CORS headers required by SIWA-authenticated requests. */
+export declare function corsHeaders(): Record<string, string>;
+/** Return a JSON Response with CORS headers. */
+export declare function corsJson(data: unknown, init?: {
+    status?: number;
+}): Response;
+/** Return a 204 OPTIONS response with CORS headers. */
+export declare function siwaOptions(): Response;
+type SiwaHandler = (agent: SiwaAgent, req: Request) => Promise<Record<string, unknown> | Response> | Record<string, unknown> | Response;
+/**
+ * Wrap a Next.js route handler with SIWA ERC-8128 authentication.
+ *
+ * - Clones POST/PUT/PATCH requests so the body is available after verification
+ * - Normalizes the request URL for reverse-proxy environments
+ * - Returns 401 with CORS headers on auth failure
+ * - If the handler returns a plain object, it is auto-wrapped in a JSON Response with CORS headers
+ */
+export declare function withSiwa(handler: SiwaHandler, options?: WithSiwaOptions): (req: Request) => Promise<Response>;

package/dist/next.js

@@ -0,0 +1,83 @@
+/**
+ * next.ts
+ *
+ * Server-side wrappers for Next.js App Router route handlers.
+ * Uses only web standard APIs (Request, Response, Headers) — no `next` dependency needed.
+ *
+ * @example
+ * ```ts
+ * import { withSiwa, siwaOptions } from "@buildersgarden/siwa/next";
+ *
+ * export const POST = withSiwa(async (agent, req) => {
+ *   const body = await req.json();
+ *   return { received: body, agent: { address: agent.address, agentId: agent.agentId } };
+ * });
+ *
+ * export { siwaOptions as OPTIONS };
+ * ```
+ */
+import { verifyAuthenticatedRequest, nextjsToFetchRequest, resolveReceiptSecret, } from './erc8128.js';
+// ---------------------------------------------------------------------------
+// CORS helpers
+// ---------------------------------------------------------------------------
+/** CORS headers required by SIWA-authenticated requests. */
+export function corsHeaders() {
+    return {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest',
+    };
+}
+/** Return a JSON Response with CORS headers. */
+export function corsJson(data, init) {
+    return new Response(JSON.stringify(data), {
+        status: init?.status ?? 200,
+        headers: {
+            'Content-Type': 'application/json',
+            ...corsHeaders(),
+        },
+    });
+}
+/** Return a 204 OPTIONS response with CORS headers. */
+export function siwaOptions() {
+    return new Response(null, { status: 204, headers: corsHeaders() });
+}
+/**
+ * Wrap a Next.js route handler with SIWA ERC-8128 authentication.
+ *
+ * - Clones POST/PUT/PATCH requests so the body is available after verification
+ * - Normalizes the request URL for reverse-proxy environments
+ * - Returns 401 with CORS headers on auth failure
+ * - If the handler returns a plain object, it is auto-wrapped in a JSON Response with CORS headers
+ */
+export function withSiwa(handler, options) {
+    return async (req) => {
+        const secret = resolveReceiptSecret(options?.receiptSecret);
+        // Clone for body-consuming methods so handler can still read the body
+        const hasBody = !['GET', 'HEAD'].includes(req.method);
+        const verifyReq = hasBody ? req.clone() : req;
+        const verifyOptions = {
+            receiptSecret: secret,
+            rpcUrl: options?.rpcUrl,
+            verifyOnchain: options?.verifyOnchain,
+        };
+        const result = await verifyAuthenticatedRequest(nextjsToFetchRequest(verifyReq), verifyOptions);
+        if (!result.valid) {
+            return corsJson({ error: result.error }, { status: 401 });
+        }
+        const response = await handler(result.agent, req);
+        if (response instanceof Response) {
+            // Merge CORS headers into existing response
+            const headers = new Headers(response.headers);
+            for (const [k, v] of Object.entries(corsHeaders())) {
+                headers.set(k, v);
+            }
+            return new Response(response.body, {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+            });
+        }
+        return corsJson(response);
+    };
+}

package/dist/registry.d.ts

@@ -8,6 +8,7 @@
  *   npm install viem
  */
 import { type PublicClient } from 'viem';
+import { type KeystoreConfig } from './keystore.js';
 /** Service endpoint types defined in ERC-8004 */
 export type ServiceType = 'web' | 'A2A' | 'MCP' | 'OASF' | 'ENS' | 'DID' | 'email';
 /** Trust models defined in ERC-8004 */
@@ -72,3 +73,22 @@ export declare function getAgent(agentId: number, options: GetAgentOptions): Pro
  * @param options  Reputation registry address, client, and optional filters
  */
 export declare function getReputation(agentId: number, options: GetReputationOptions): Promise<ReputationSummary>;
+export interface RegisterAgentOptions {
+    agentURI: string;
+    chainId: number;
+    rpcUrl?: string;
+    keystoreConfig: KeystoreConfig;
+}
+export interface RegisterAgentResult {
+    agentId: string;
+    txHash: string;
+    registryAddress: string;
+    agentRegistry: string;
+}
+/**
+ * Register an agent on the ERC-8004 Identity Registry in a single call.
+ *
+ * Builds, signs (via keyring proxy), and broadcasts the `register(agentURI)`
+ * transaction, then waits for confirmation and parses the `Registered` event.
+ */
+export declare function registerAgent(options: RegisterAgentOptions): Promise<RegisterAgentResult>;

package/dist/registry.js

@@ -7,7 +7,9 @@
  * Dependencies:
  *   npm install viem
  */
-import { zeroAddress, } from 'viem';
+import { zeroAddress, createPublicClient, http, encodeFunctionData, parseEventLogs, } from 'viem';
+import { getRegistryAddress, getAgentRegistryString, RPC_ENDPOINTS } from './addresses.js';
+import { getAddress, signTransaction } from './keystore.js';
 // ─── ABI Fragments ──────────────────────────────────────────────────
 const IDENTITY_REGISTRY_ABI = [
     {
@@ -31,6 +33,22 @@ const IDENTITY_REGISTRY_ABI = [
         inputs: [{ name: 'agentId', type: 'uint256' }],
         outputs: [{ name: '', type: 'address' }],
     },
+    {
+        name: 'register',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'agentURI', type: 'string' }],
+        outputs: [{ name: 'agentId', type: 'uint256' }],
+    },
+    {
+        name: 'Registered',
+        type: 'event',
+        inputs: [
+            { name: 'agentId', type: 'uint256', indexed: true },
+            { name: 'agentURI', type: 'string', indexed: false },
+            { name: 'owner', type: 'address', indexed: true },
+        ],
+    },
 ];
 const REPUTATION_REGISTRY_ABI = [
     {
@@ -139,3 +157,61 @@ export async function getReputation(agentId, options) {
     const score = Number(rawValue) / 10 ** decimals;
     return { count: Number(count), score, rawValue, decimals };
 }
+/**
+ * Register an agent on the ERC-8004 Identity Registry in a single call.
+ *
+ * Builds, signs (via keyring proxy), and broadcasts the `register(agentURI)`
+ * transaction, then waits for confirmation and parses the `Registered` event.
+ */
+export async function registerAgent(options) {
+    const { agentURI, chainId, keystoreConfig } = options;
+    const registryAddress = getRegistryAddress(chainId);
+    const rpcUrl = options.rpcUrl || RPC_ENDPOINTS[chainId];
+    if (!rpcUrl) {
+        throw new Error(`No RPC URL provided and no default endpoint for chain ${chainId}.`);
+    }
+    const publicClient = createPublicClient({ transport: http(rpcUrl) });
+    const address = await getAddress(keystoreConfig);
+    if (!address) {
+        throw new Error('Could not resolve wallet address from keyring proxy.');
+    }
+    const data = encodeFunctionData({
+        abi: IDENTITY_REGISTRY_ABI,
+        functionName: 'register',
+        args: [agentURI],
+    });
+    const nonce = await publicClient.getTransactionCount({ address: address });
+    const feeData = await publicClient.estimateFeesPerGas();
+    const gasEstimate = await publicClient.estimateGas({
+        to: registryAddress,
+        data,
+        account: address,
+    });
+    const gas = (gasEstimate * 120n) / 100n;
+    const txReq = {
+        to: registryAddress,
+        data,
+        nonce,
+        chainId,
+        type: 2,
+        maxFeePerGas: feeData.maxFeePerGas,
+        maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
+        gas,
+    };
+    const { signedTx } = await signTransaction(txReq, keystoreConfig);
+    const txHash = await publicClient.sendRawTransaction({
+        serializedTransaction: signedTx,
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+    const logs = parseEventLogs({
+        abi: IDENTITY_REGISTRY_ABI,
+        logs: receipt.logs,
+        eventName: 'Registered',
+    });
+    if (logs.length === 0) {
+        throw new Error(`Registration tx ${txHash} succeeded but no Registered event was found.`);
+    }
+    const agentId = logs[0].args.agentId.toString();
+    const agentRegistry = getAgentRegistryString(chainId);
+    return { agentId, txHash, registryAddress, agentRegistry };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildersgarden/siwa",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "exports": {
     ".": {
@@ -38,6 +38,14 @@
     "./erc8128": {
       "types": "./dist/erc8128.d.ts",
       "default": "./dist/erc8128.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "default": "./dist/express.js"
     }
   },
   "main": "./dist/index.js",
@@ -61,7 +69,16 @@
     "@slicekit/erc8128": "^0.1.0",
     "viem": "^2.21.0"
   },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/express": "^4.17.0",
     "@types/node": "^25.2.1",
     "typescript": "^5.5.0"
   }