@agentcash/router 0.4.5 → 0.4.7

package/.claude/CLAUDE.md

@@ -28,6 +28,98 @@ Protocol-agnostic route framework for Next.js App Router APIs with x402 payment,
 - `src/protocols/` — Protocol handlers (x402.ts, mpp.ts, detect.ts)
 - `src/discovery/` — Auto-generated endpoints (well-known.ts, openapi.ts)
 
+## Auth Modes
+
+Four auth modes, mutually exclusive (except `.apiKey()` composes with `.paid()`):
+
+### `.paid(pricing)` — Payment required
+```typescript
+.paid('0.01')                    // Static price
+.paid((body) => calcPrice(body)) // Dynamic pricing
+.paid({ field: 'tier', tiers: { basic: { price: '0.01' } } }) // Tiered
+```
+
+### `.siwx()` — Wallet identity required (no payment)
+```typescript
+.siwx().handler(async ({ wallet }) => { /* wallet is verified */ })
+```
+
+### `.apiKey(resolver)` — API key / Bearer token auth
+For admin routes, cron jobs, internal services. Checks `X-API-Key` header OR `Authorization: Bearer <token>`.
+
+```typescript
+// Admin route with API key
+export const GET = router
+  .route('admin/users')
+  .apiKey(async (key) => {
+    const admin = await db.admin.findByKey(key);
+    return admin ?? null; // null = 401, truthy = ctx.account
+  })
+  .handler(async ({ account }) => {
+    // account is whatever resolver returned
+    return db.user.findMany();
+  });
+
+// Cron job with static secret
+export const POST = router
+  .route('cron/cleanup')
+  .apiKey((key) => key === process.env.CRON_SECRET ? { cron: true } : null)
+  .handler(async () => { /* ... */ });
+```
+
+**Headers accepted:** `X-API-Key: <key>` or `Authorization: Bearer <key>`
+
+**Composing with payment:** `.apiKey()` can layer on `.paid()` — auth runs first, payment second:
+```typescript
+.apiKey(resolver).paid('0.01') // Must pass API key AND pay
+```
+
+### `.unprotected()` — No auth
+```typescript
+.unprotected().handler(async () => { /* public endpoint */ })
+```
+
+## Pre-Payment Validation
+
+### `.validate(fn)` — Async business validation before 402 challenge
+
+For checks that need DB lookups or external APIs before showing a price. Runs after body parsing, before the 402 challenge. Requires `.body()`.
+
+```typescript
+// Domain registration with availability check
+router
+  .route('domain/register')
+  .paid(calculatePrice, { maxPrice: '10.00' })
+  .body(RegisterSchema)  // .body() before .validate() for type inference
+  .validate(async (body) => {
+    if (await isDomainTaken(body.domain)) {
+      throw Object.assign(new Error('Domain already taken'), { status: 409 });
+    }
+  })
+  .handler(async ({ body, wallet }) => {
+    return registerDomain(body.domain, wallet);
+  });
+
+// Rate limiting before payment
+router
+  .route('api/expensive')
+  .paid('1.00')
+  .body(RequestSchema)
+  .validate(async (body) => {
+    const usage = await getUserUsage(body.userId);
+    if (usage >= DAILY_LIMIT) {
+      throw Object.assign(new Error('Daily limit reached'), { status: 429 });
+    }
+  })
+  .handler(async ({ body }) => { ... });
+```
+
+**Pipeline order:** `body parse → validate → 402 challenge → payment → handler`
+
+**Error handling:** Respects `.status` on thrown errors (default: 400). Use `Object.assign(new Error('msg'), { status: 409 })` for custom codes.
+
+**Works with all auth modes:** paid, siwx, apiKey, unprotected.
+
 ## Critical Rules
 
 - **Error handling:** Respect `.status` on any thrown error, not just `HttpError`. The `Object.assign(new Error(), { status })` pattern is universal in Node.js.
@@ -95,6 +187,43 @@ pnpm typecheck  # tsc --noEmit
 pnpm check      # format + lint + typecheck + build + test
 ```
 
+## Releasing
+
+**Release flow:** PR with version bump → merge → create GitHub Release → auto-publish to npm
+
+### When doing work that should be released:
+
+1. **Update `CHANGELOG.md`** — Add entry under new version heading with changes
+2. **Bump version in `package.json`** — Match the changelog version
+3. **Commit both** — e.g., `chore: bump to v0.6.0`
+4. **Merge PR to main**
+
+### To publish (human step):
+
+1. Go to [GitHub Releases](https://github.com/Merit-Systems/agentcash-router/releases)
+2. Click **Draft a new release**
+3. Create tag: `v0.6.0` (must match package.json version)
+4. Title: `v0.6.0`
+5. Description: Copy from CHANGELOG.md or click "Generate release notes"
+6. Click **Publish release**
+
+The `publish.yml` workflow will:
+- Run full test suite (`pnpm check`)
+- Verify package.json version matches tag
+- Publish to npm with `--access public`
+
+### Version format
+
+- **Patch** (`0.5.1`): Bug fixes, docs, internal changes
+- **Minor** (`0.6.0`): New features, non-breaking additions
+- **Major** (`1.0.0`): Breaking changes (holding until API stabilizes)
+
+### Troubleshooting
+
+- **Version mismatch error**: package.json version must exactly match the release tag (without `v` prefix)
+- **Publish fails**: Check `NPM_TOKEN` secret is set and has write access to `@agentcash` scope
+- **Tests fail**: Fix in a new PR, then re-create the release
+
 ## Development Record
 
 The `.claude/` directory contains design docs, decision records, and bug analyses that document the reasoning behind the router's architecture. See `.claude/INDEX.md` for a table of contents.

package/dist/client/index.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  SIWX_ERROR_MESSAGES: () => SIWX_ERROR_MESSAGES,
+  fetchWithSiwx: () => fetchWithSiwx
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/auth/siwx.ts
+var SIWX_ERROR_MESSAGES = {
+  siwx_missing_header: "Missing SIGN-IN-WITH-X header",
+  siwx_malformed: "Malformed SIWX payload",
+  siwx_expired: "SIWX message expired \u2014 request a new challenge",
+  siwx_nonce_used: "Nonce already used \u2014 request a new challenge",
+  siwx_invalid_signature: "Invalid signature \u2014 wallet mismatch or corrupted proof"
+};
+
+// src/client/index.ts
+async function fetchWithSiwx(url, options) {
+  const { signer, headers, ...init } = options;
+  const challengeRes = await fetch(url, {
+    ...init,
+    headers
+  });
+  if (challengeRes.status !== 402) {
+    return challengeRes;
+  }
+  let body;
+  try {
+    body = await challengeRes.json();
+  } catch {
+    throw new Error("Expected JSON body in 402 response");
+  }
+  const siwxExtension = body.extensions?.["sign-in-with-x"];
+  if (!siwxExtension) {
+    throw new Error(
+      "Expected SIWX challenge in 402 response. This endpoint may require payment instead of SIWX auth."
+    );
+  }
+  const { createSIWxPayload, encodeSIWxHeader } = await import("@x402/extensions/sign-in-with-x");
+  const chainInfo = siwxExtension.supportedChains?.find((c) => c.type === "eip191") ?? {
+    chainId: siwxExtension.info.chainId,
+    type: siwxExtension.info.type
+  };
+  const completeInfo = {
+    ...siwxExtension.info,
+    chainId: chainInfo.chainId,
+    type: chainInfo.type,
+    ...chainInfo.signatureScheme ? { signatureScheme: chainInfo.signatureScheme } : {}
+  };
+  const payload = await createSIWxPayload(completeInfo, signer);
+  const header = encodeSIWxHeader(payload);
+  return fetch(url, {
+    ...init,
+    headers: {
+      ...headers instanceof Headers ? Object.fromEntries(headers.entries()) : headers,
+      "SIGN-IN-WITH-X": header
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SIWX_ERROR_MESSAGES,
+  fetchWithSiwx
+});

package/dist/client/index.d.cts

@@ -0,0 +1,86 @@
+export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from '../siwx-BMlja_nt.cjs';
+
+/**
+ * @agentcash/router/client
+ *
+ * Client-side utilities for SIWX (Sign-In With X) authentication.
+ * Use these to authenticate with SIWX-protected endpoints.
+ *
+ * @example
+ * ```ts
+ * import { fetchWithSiwx } from '@agentcash/router/client';
+ *
+ * const response = await fetchWithSiwx('https://api.example.com/protected', {
+ *   method: 'GET',
+ *   signer: walletClient, // viem WalletClient or PrivateKeyAccount
+ * });
+ * ```
+ */
+
+/**
+ * SIWX challenge structure from 402 response.
+ * This is what the server returns in `extensions['sign-in-with-x'].info`.
+ */
+interface SiwxChallenge {
+    domain: string;
+    uri: string;
+    version: string;
+    chainId: string;
+    type: 'eip191' | 'ed25519';
+    nonce: string;
+    issuedAt: string;
+    expirationTime?: string;
+    statement?: string;
+}
+/**
+ * Fetch options with SIWX signer.
+ * The signer must be compatible with @x402/extensions EVMSigner interface.
+ */
+interface FetchWithSiwxOptions extends Omit<RequestInit, 'headers'> {
+    /**
+     * Wallet signer compatible with viem's WalletClient or PrivateKeyAccount.
+     * Must have a `signMessage` method that accepts `{ message: string }`.
+     */
+    signer: {
+        signMessage: (args: {
+            message: string;
+            account?: unknown;
+        }) => Promise<string>;
+        account?: {
+            address: string;
+        };
+        address?: string;
+    };
+    /**
+     * Additional headers to include in the request.
+     */
+    headers?: HeadersInit;
+}
+/**
+ * Fetch a SIWX-protected endpoint with automatic challenge-response handling.
+ *
+ * 1. Makes initial request
+ * 2. If 402 with SIWX challenge, extracts challenge from response
+ * 3. Signs the challenge with the provided signer
+ * 4. Retries request with SIGN-IN-WITH-X header
+ *
+ * @example
+ * ```ts
+ * import { fetchWithSiwx } from '@agentcash/router/client';
+ * import { createWalletClient, custom } from 'viem';
+ *
+ * const walletClient = createWalletClient({
+ *   transport: custom(window.ethereum),
+ * });
+ *
+ * const response = await fetchWithSiwx('https://api.example.com/jobs', {
+ *   method: 'GET',
+ *   signer: walletClient,
+ * });
+ *
+ * const jobs = await response.json();
+ * ```
+ */
+declare function fetchWithSiwx(url: string, options: FetchWithSiwxOptions): Promise<Response>;
+
+export { type FetchWithSiwxOptions, type SiwxChallenge, fetchWithSiwx };

package/dist/client/index.d.ts

@@ -0,0 +1,86 @@
+export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from '../siwx-BMlja_nt.js';
+
+/**
+ * @agentcash/router/client
+ *
+ * Client-side utilities for SIWX (Sign-In With X) authentication.
+ * Use these to authenticate with SIWX-protected endpoints.
+ *
+ * @example
+ * ```ts
+ * import { fetchWithSiwx } from '@agentcash/router/client';
+ *
+ * const response = await fetchWithSiwx('https://api.example.com/protected', {
+ *   method: 'GET',
+ *   signer: walletClient, // viem WalletClient or PrivateKeyAccount
+ * });
+ * ```
+ */
+
+/**
+ * SIWX challenge structure from 402 response.
+ * This is what the server returns in `extensions['sign-in-with-x'].info`.
+ */
+interface SiwxChallenge {
+    domain: string;
+    uri: string;
+    version: string;
+    chainId: string;
+    type: 'eip191' | 'ed25519';
+    nonce: string;
+    issuedAt: string;
+    expirationTime?: string;
+    statement?: string;
+}
+/**
+ * Fetch options with SIWX signer.
+ * The signer must be compatible with @x402/extensions EVMSigner interface.
+ */
+interface FetchWithSiwxOptions extends Omit<RequestInit, 'headers'> {
+    /**
+     * Wallet signer compatible with viem's WalletClient or PrivateKeyAccount.
+     * Must have a `signMessage` method that accepts `{ message: string }`.
+     */
+    signer: {
+        signMessage: (args: {
+            message: string;
+            account?: unknown;
+        }) => Promise<string>;
+        account?: {
+            address: string;
+        };
+        address?: string;
+    };
+    /**
+     * Additional headers to include in the request.
+     */
+    headers?: HeadersInit;
+}
+/**
+ * Fetch a SIWX-protected endpoint with automatic challenge-response handling.
+ *
+ * 1. Makes initial request
+ * 2. If 402 with SIWX challenge, extracts challenge from response
+ * 3. Signs the challenge with the provided signer
+ * 4. Retries request with SIGN-IN-WITH-X header
+ *
+ * @example
+ * ```ts
+ * import { fetchWithSiwx } from '@agentcash/router/client';
+ * import { createWalletClient, custom } from 'viem';
+ *
+ * const walletClient = createWalletClient({
+ *   transport: custom(window.ethereum),
+ * });
+ *
+ * const response = await fetchWithSiwx('https://api.example.com/jobs', {
+ *   method: 'GET',
+ *   signer: walletClient,
+ * });
+ *
+ * const jobs = await response.json();
+ * ```
+ */
+declare function fetchWithSiwx(url: string, options: FetchWithSiwxOptions): Promise<Response>;
+
+export { type FetchWithSiwxOptions, type SiwxChallenge, fetchWithSiwx };

package/dist/client/index.js

@@ -0,0 +1,56 @@
+// src/auth/siwx.ts
+var SIWX_ERROR_MESSAGES = {
+  siwx_missing_header: "Missing SIGN-IN-WITH-X header",
+  siwx_malformed: "Malformed SIWX payload",
+  siwx_expired: "SIWX message expired \u2014 request a new challenge",
+  siwx_nonce_used: "Nonce already used \u2014 request a new challenge",
+  siwx_invalid_signature: "Invalid signature \u2014 wallet mismatch or corrupted proof"
+};
+
+// src/client/index.ts
+async function fetchWithSiwx(url, options) {
+  const { signer, headers, ...init } = options;
+  const challengeRes = await fetch(url, {
+    ...init,
+    headers
+  });
+  if (challengeRes.status !== 402) {
+    return challengeRes;
+  }
+  let body;
+  try {
+    body = await challengeRes.json();
+  } catch {
+    throw new Error("Expected JSON body in 402 response");
+  }
+  const siwxExtension = body.extensions?.["sign-in-with-x"];
+  if (!siwxExtension) {
+    throw new Error(
+      "Expected SIWX challenge in 402 response. This endpoint may require payment instead of SIWX auth."
+    );
+  }
+  const { createSIWxPayload, encodeSIWxHeader } = await import("@x402/extensions/sign-in-with-x");
+  const chainInfo = siwxExtension.supportedChains?.find((c) => c.type === "eip191") ?? {
+    chainId: siwxExtension.info.chainId,
+    type: siwxExtension.info.type
+  };
+  const completeInfo = {
+    ...siwxExtension.info,
+    chainId: chainInfo.chainId,
+    type: chainInfo.type,
+    ...chainInfo.signatureScheme ? { signatureScheme: chainInfo.signatureScheme } : {}
+  };
+  const payload = await createSIWxPayload(completeInfo, signer);
+  const header = encodeSIWxHeader(payload);
+  return fetch(url, {
+    ...init,
+    headers: {
+      ...headers instanceof Headers ? Object.fromEntries(headers.entries()) : headers,
+      "SIGN-IN-WITH-X": header
+    }
+  });
+}
+export {
+  SIWX_ERROR_MESSAGES,
+  fetchWithSiwx
+};