@agentcash/router 0.4.6 → 0.4.7

package/dist/index.cjs

@@ -76,7 +76,10 @@ __export(index_exports, {
   MemoryNonceStore: () => MemoryNonceStore,
   RouteBuilder: () => RouteBuilder,
   RouteRegistry: () => RouteRegistry,
+  SIWX_CHALLENGE_EXPIRY_MS: () => SIWX_CHALLENGE_EXPIRY_MS,
+  SIWX_ERROR_MESSAGES: () => SIWX_ERROR_MESSAGES,
   consolePlugin: () => consolePlugin,
+  createRedisNonceStore: () => createRedisNonceStore,
   createRouter: () => createRouter
 });
 module.exports = __toCommonJS(index_exports);
@@ -164,6 +167,10 @@ function consolePlugin() {
       const ctx = createDefaultContext(meta);
       return ctx;
     },
+    onAuthVerified(_ctx, auth) {
+      const wallet = auth.wallet ? ` wallet=${auth.wallet}` : "";
+      console.log(`[router] AUTH ${auth.authMode} ${auth.route}${wallet}`);
+    },
     onPaymentVerified(_ctx, payment) {
       console.log(`[router] VERIFIED ${payment.protocol} ${payment.payer} ${payment.amount}`);
     },
@@ -193,6 +200,65 @@ function consolePlugin() {
   };
 }
 
+// src/auth/nonce.ts
+var SIWX_CHALLENGE_EXPIRY_MS = 5 * 60 * 1e3;
+var MemoryNonceStore = class {
+  seen = /* @__PURE__ */ new Map();
+  async check(nonce) {
+    this.evict();
+    if (this.seen.has(nonce)) return false;
+    this.seen.set(nonce, Date.now() + SIWX_CHALLENGE_EXPIRY_MS);
+    return true;
+  }
+  evict() {
+    const now = Date.now();
+    for (const [n, exp] of this.seen) {
+      if (exp < now) this.seen.delete(n);
+    }
+  }
+};
+function detectRedisClientType(client) {
+  if (!client || typeof client !== "object") {
+    throw new Error(
+      "createRedisNonceStore requires a Redis client. Supported: @upstash/redis, ioredis. Pass your Redis client instance as the first argument."
+    );
+  }
+  if ("options" in client && "status" in client) {
+    return "ioredis";
+  }
+  const constructor = client.constructor?.name;
+  if (constructor === "Redis" && "url" in client) {
+    return "upstash";
+  }
+  if (typeof client.set === "function") {
+    return "upstash";
+  }
+  throw new Error(
+    "Unrecognized Redis client. Supported: @upstash/redis, ioredis. If using a different client, implement NonceStore interface directly."
+  );
+}
+function createRedisNonceStore(client, opts) {
+  const prefix = opts?.prefix ?? "siwx:nonce:";
+  const ttlSeconds = Math.ceil((opts?.ttlMs ?? SIWX_CHALLENGE_EXPIRY_MS) / 1e3);
+  const clientType = detectRedisClientType(client);
+  return {
+    async check(nonce) {
+      const key = `${prefix}${nonce}`;
+      if (clientType === "upstash") {
+        const redis = client;
+        const result = await redis.set(key, "1", { ex: ttlSeconds, nx: true });
+        return result !== null;
+      }
+      if (clientType === "ioredis") {
+        const redis = client;
+        const result = await redis.set(key, "1", "EX", ttlSeconds, "NX");
+        return result === "OK";
+      }
+      throw new Error("Unknown Redis client type");
+    }
+  };
+}
+
 // src/protocols/detect.ts
 function detectProtocol(request) {
   if (request.headers.get("PAYMENT-SIGNATURE") || request.headers.get("X-PAYMENT")) {
@@ -467,21 +533,47 @@ function buildMPPReceipt(reference) {
 }
 
 // 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"
+};
+function categorizeValidationError(error) {
+  if (!error) return "siwx_malformed";
+  const err = error.toLowerCase();
+  if (err.includes("expired") || err.includes("message too old")) {
+    return "siwx_expired";
+  }
+  if (err.includes("nonce validation failed")) {
+    return "siwx_nonce_used";
+  }
+  return "siwx_malformed";
+}
 async function verifySIWX(request, _routeEntry, nonceStore) {
   const { parseSIWxHeader, validateSIWxMessage, verifySIWxSignature } = await import("@x402/extensions/sign-in-with-x");
   const header = request.headers.get("SIGN-IN-WITH-X");
-  if (!header) return { valid: false, wallet: null };
-  const payload = parseSIWxHeader(header);
+  if (!header) {
+    return { valid: false, wallet: null, code: "siwx_missing_header" };
+  }
+  let payload;
+  try {
+    payload = parseSIWxHeader(header);
+  } catch {
+    return { valid: false, wallet: null, code: "siwx_malformed" };
+  }
   const uri = request.url;
   const validation = await validateSIWxMessage(payload, uri, {
     checkNonce: (nonce) => nonceStore.check(nonce)
   });
   if (!validation.valid) {
-    return { valid: false, wallet: null };
+    const code = categorizeValidationError(validation.error);
+    return { valid: false, wallet: null, code };
   }
   const verified = await verifySIWxSignature(payload);
   if (!verified?.valid) {
-    return { valid: false, wallet: null };
+    return { valid: false, wallet: null, code: "siwx_invalid_signature" };
   }
   return { valid: true, wallet: verified.address };
 }
@@ -555,6 +647,15 @@ function createRequestHandler(routeEntry, handler, deps) {
         firePluginResponse(deps, pluginCtx, meta, body2.response);
         return body2.response;
       }
+      if (routeEntry.validateFn) {
+        try {
+          await routeEntry.validateFn(body2.data);
+        } catch (err) {
+          const status = err.status ?? 400;
+          const message = err instanceof Error ? err.message : "Validation failed";
+          return fail(status, message, meta, pluginCtx);
+        }
+      }
       const { response, rawResult } = await invoke(
         request,
         meta,
@@ -579,13 +680,20 @@ function createRequestHandler(routeEntry, handler, deps) {
         return fail(401, "Invalid or missing API key", meta, pluginCtx);
       }
       account = keyResult.account;
+      firePluginHook(deps.plugin, "onAuthVerified", pluginCtx, {
+        authMode: "apiKey",
+        wallet: null,
+        route: routeEntry.key,
+        account
+      });
       if (routeEntry.authMode === "apiKey" && !routeEntry.pricing) {
         return handleAuth(null, account);
       }
     }
     const protocol = detectProtocol(request);
     let earlyBodyData;
-    if (!protocol && typeof routeEntry.pricing === "function" && routeEntry.bodySchema) {
+    const needsEarlyParse = !protocol && routeEntry.bodySchema && (typeof routeEntry.pricing === "function" || routeEntry.validateFn);
+    if (needsEarlyParse) {
       const requestForPricing = request.clone();
       const earlyBodyResult = await parseBody(requestForPricing, routeEntry);
       if (!earlyBodyResult.ok) {
@@ -593,11 +701,35 @@ function createRequestHandler(routeEntry, handler, deps) {
         return earlyBodyResult.response;
       }
       earlyBodyData = earlyBodyResult.data;
+      if (routeEntry.validateFn) {
+        try {
+          await routeEntry.validateFn(earlyBodyData);
+        } catch (err) {
+          const status = err.status ?? 400;
+          const message = err instanceof Error ? err.message : "Validation failed";
+          return fail(status, message, meta, pluginCtx);
+        }
+      }
     }
     if (routeEntry.authMode === "siwx") {
+      if (routeEntry.validateFn && routeEntry.bodySchema && !request.headers.get("SIGN-IN-WITH-X")) {
+        const requestForValidation = request.clone();
+        const earlyBodyResult = await parseBody(requestForValidation, routeEntry);
+        if (!earlyBodyResult.ok) {
+          firePluginResponse(deps, pluginCtx, meta, earlyBodyResult.response);
+          return earlyBodyResult.response;
+        }
+        try {
+          await routeEntry.validateFn(earlyBodyResult.data);
+        } catch (err) {
+          const status = err.status ?? 400;
+          const message = err instanceof Error ? err.message : "Validation failed";
+          return fail(status, message, meta, pluginCtx);
+        }
+      }
       if (!request.headers.get("SIGN-IN-WITH-X")) {
         const url = new URL(request.url);
-        const nonce = crypto.randomUUID();
+        const nonce = crypto.randomUUID().replace(/-/g, "");
         const siwxInfo = {
           domain: url.hostname,
           uri: request.url,
@@ -606,7 +738,7 @@ function createRequestHandler(routeEntry, handler, deps) {
           type: "eip191",
           nonce,
           issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          expirationTime: new Date(Date.now() + 3e5).toISOString(),
+          expirationTime: new Date(Date.now() + SIWX_CHALLENGE_EXPIRY_MS).toISOString(),
           statement: "Sign in to verify your wallet identity"
         };
         let siwxSchema;
@@ -626,6 +758,8 @@ function createRequestHandler(routeEntry, handler, deps) {
           extensions: {
             "sign-in-with-x": {
               info: siwxInfo,
+              // supportedChains at top level required by MCP tools for chain detection
+              supportedChains: [{ chainId: deps.network, type: "eip191" }],
               ...siwxSchema ? { schema: siwxSchema } : {}
             }
           }
@@ -651,15 +785,21 @@ function createRequestHandler(routeEntry, handler, deps) {
       }
       const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
       if (!siwx.valid) {
-        return fail(
-          402,
-          "SIWX verification failed \u2014 signature invalid, message expired, or nonce already used",
-          meta,
-          pluginCtx
+        const response = import_server3.NextResponse.json(
+          { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
+          { status: 402 }
         );
+        firePluginResponse(deps, pluginCtx, meta, response);
+        return response;
       }
-      pluginCtx.setVerifiedWallet(siwx.wallet);
-      return handleAuth(siwx.wallet, void 0);
+      const wallet = siwx.wallet.toLowerCase();
+      pluginCtx.setVerifiedWallet(wallet);
+      firePluginHook(deps.plugin, "onAuthVerified", pluginCtx, {
+        authMode: "siwx",
+        wallet,
+        route: routeEntry.key
+      });
+      return handleAuth(wallet, void 0);
     }
     if (!protocol || protocol === "siwx") {
       return await build402(request, routeEntry, deps, meta, pluginCtx, earlyBodyData);
@@ -669,6 +809,15 @@ function createRequestHandler(routeEntry, handler, deps) {
       firePluginResponse(deps, pluginCtx, meta, body.response);
       return body.response;
     }
+    if (routeEntry.validateFn) {
+      try {
+        await routeEntry.validateFn(body.data);
+      } catch (err) {
+        const status = err.status ?? 400;
+        const message = err instanceof Error ? err.message : "Validation failed";
+        return fail(status, message, meta, pluginCtx);
+      }
+    }
     let price;
     try {
       price = await resolvePrice(routeEntry.pricing, body.data);
@@ -695,10 +844,11 @@ function createRequestHandler(routeEntry, handler, deps) {
       );
       if (!verify?.valid) return await build402(request, routeEntry, deps, meta, pluginCtx);
       const { payload: verifyPayload, requirements: verifyRequirements } = verify;
-      pluginCtx.setVerifiedWallet(verify.payer);
+      const wallet = verify.payer.toLowerCase();
+      pluginCtx.setVerifiedWallet(wallet);
       firePluginHook(deps.plugin, "onPaymentVerified", pluginCtx, {
         protocol: "x402",
-        payer: verify.payer,
+        payer: wallet,
         amount: price,
         network: deps.network
       });
@@ -706,7 +856,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         request,
         meta,
         pluginCtx,
-        verify.payer,
+        wallet,
         account,
         body.data
       );
@@ -757,7 +907,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       if (!deps.mppConfig) return await build402(request, routeEntry, deps, meta, pluginCtx);
       const verify = await verifyMPPCredential(request, routeEntry, deps.mppConfig, price);
       if (!verify?.valid) return await build402(request, routeEntry, deps, meta, pluginCtx);
-      const wallet = verify.payer;
+      const wallet = verify.payer.toLowerCase();
       pluginCtx.setVerifiedWallet(wallet);
       firePluginHook(deps.plugin, "onPaymentVerified", pluginCtx, {
         protocol: "mpp",
@@ -1016,6 +1166,8 @@ var RouteBuilder = class {
   _providerName;
   /** @internal */
   _providerConfig;
+  /** @internal */
+  _validateFn;
   constructor(key, registry, deps) {
     this._key = key;
     this._registry = registry;
@@ -1028,6 +1180,11 @@ var RouteBuilder = class {
     return next;
   }
   paid(pricing, options) {
+    if (this._authMode === "siwx") {
+      throw new Error(
+        `route '${this._key}': Cannot combine .paid() and .siwx() on the same route. Paid routes get wallet identity from the payment proof. Use separate routes if you need both payment and SIWX auth.`
+      );
+    }
     const next = this.fork();
     next._authMode = "paid";
     next._pricing = pricing;
@@ -1057,6 +1214,11 @@ var RouteBuilder = class {
     return next;
   }
   siwx() {
+    if (this._authMode === "paid") {
+      throw new Error(
+        `route '${this._key}': Cannot combine .paid() and .siwx() on the same route. Paid routes get wallet identity from the payment proof. Use separate routes if you need both payment and SIWX auth.`
+      );
+    }
     const next = this.fork();
     next._authMode = "siwx";
     next._protocols = [];
@@ -1117,7 +1279,41 @@ var RouteBuilder = class {
     next._method = m;
     return next;
   }
+  // -------------------------------------------------------------------------
+  // Pre-payment validation
+  // -------------------------------------------------------------------------
+  /**
+   * Add pre-payment validation that runs after body parsing but before the 402
+   * challenge is shown. Use this for async business logic like "is this resource
+   * available?" or "has this user hit their rate limit?".
+   *
+   * Requires `.body()` — call `.body()` before `.validate()` for type inference.
+   *
+   * @example
+   * ```typescript
+   * router
+   *   .route('domain/register')
+   *   .paid(calculatePrice)
+   *   .body(RegisterSchema)  // .body() first for type inference
+   *   .validate(async (body) => {
+   *     if (await isDomainTaken(body.domain)) {
+   *       throw Object.assign(new Error('Domain taken'), { status: 409 });
+   *     }
+   *   })
+   *   .handler(async ({ body }) => { ... });
+   * ```
+   */
+  validate(fn) {
+    const next = this.fork();
+    next._validateFn = fn;
+    return next;
+  }
   handler(fn) {
+    if (this._validateFn && !this._bodySchema) {
+      throw new Error(
+        `route '${this._key}': .validate() requires .body() \u2014 validation runs on parsed body`
+      );
+    }
     const entry = {
       key: this._key,
       authMode: this._authMode,
@@ -1132,30 +1328,14 @@ var RouteBuilder = class {
       maxPrice: this._maxPrice,
       apiKeyResolver: this._apiKeyResolver,
       providerName: this._providerName,
-      providerConfig: this._providerConfig
+      providerConfig: this._providerConfig,
+      validateFn: this._validateFn
     };
     this._registry.register(entry);
     return createRequestHandler(entry, fn, this._deps);
   }
 };
 
-// src/auth/nonce.ts
-var MemoryNonceStore = class {
-  seen = /* @__PURE__ */ new Map();
-  async check(nonce) {
-    this.evict();
-    if (this.seen.has(nonce)) return false;
-    this.seen.set(nonce, Date.now() + 5 * 60 * 1e3);
-    return true;
-  }
-  evict() {
-    const now = Date.now();
-    for (const [n, exp] of this.seen) {
-      if (exp < now) this.seen.delete(n);
-    }
-  }
-};
-
 // src/discovery/well-known.ts
 var import_server4 = require("next/server");
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
@@ -1388,6 +1568,9 @@ function createRouter(config) {
   MemoryNonceStore,
   RouteBuilder,
   RouteRegistry,
+  SIWX_CHALLENGE_EXPIRY_MS,
+  SIWX_ERROR_MESSAGES,
   consolePlugin,
+  createRedisNonceStore,
   createRouter
 });

package/dist/index.d.cts

@@ -1,15 +1,53 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
+export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.cjs';
 
+/**
+ * SIWX challenge expiry in milliseconds.
+ * Currently not configurable per-route — this is a known limitation.
+ * Future versions may add `siwx: { expiryMs }` to RouterConfig.
+ */
+declare const SIWX_CHALLENGE_EXPIRY_MS: number;
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
 }
+/**
+ * In-memory nonce store for development and testing.
+ * NOT suitable for production serverless environments (Vercel, etc.)
+ * where each function invocation gets fresh memory.
+ *
+ * For production, use `createRedisNonceStore()` with Upstash or ioredis.
+ */
 declare class MemoryNonceStore implements NonceStore {
     private seen;
     check(nonce: string): Promise<boolean>;
     private evict;
 }
+interface RedisNonceStoreOptions {
+    /** Key prefix for nonce storage. Default: 'siwx:nonce:' */
+    prefix?: string;
+    /** TTL in milliseconds. Default: SIWX_CHALLENGE_EXPIRY_MS (5 minutes) */
+    ttlMs?: number;
+}
+/**
+ * Create a Redis-backed nonce store for production SIWX replay protection.
+ * Auto-detects client type (Upstash or ioredis) and uses appropriate API.
+ *
+ * @example
+ * ```ts
+ * // Upstash (Vercel)
+ * import { Redis } from '@upstash/redis';
+ * const redis = new Redis({ url: process.env.UPSTASH_URL, token: process.env.UPSTASH_TOKEN });
+ * const nonceStore = createRedisNonceStore(redis);
+ *
+ * // ioredis
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const nonceStore = createRedisNonceStore(redis);
+ * ```
+ */
+declare function createRedisNonceStore(client: unknown, opts?: RedisNonceStoreOptions): NonceStore;
 
 interface RequestMeta {
     requestId: string;
@@ -57,11 +95,23 @@ interface ErrorEvent {
     message: string;
     settled: boolean;
 }
+interface AuthEvent {
+    /** Authentication mode that was verified */
+    authMode: 'siwx' | 'apiKey';
+    /** Verified wallet address (lowercase) */
+    wallet: string | null;
+    /** Route key */
+    route: string;
+    /** Account data from API key resolver (for apiKey auth) */
+    account?: unknown;
+}
 interface RouterPlugin {
     init?(config: {
         origin?: string;
     }): void | Promise<void>;
     onRequest?(meta: RequestMeta): PluginContext;
+    /** Fired after successful SIWX or API key verification, before handler */
+    onAuthVerified?(ctx: PluginContext, event: AuthEvent): void;
     onPaymentVerified?(ctx: PluginContext, payment: PaymentEvent): void;
     onPaymentSettled?(ctx: PluginContext, settlement: SettlementEvent): void;
     onResponse?(ctx: PluginContext, response: ResponseMeta): void;
@@ -171,6 +221,7 @@ interface RouteEntry {
     apiKeyResolver?: (key: string) => unknown | Promise<unknown>;
     providerName?: string;
     providerConfig?: ProviderConfig;
+    validateFn?: (body: unknown) => void | Promise<void>;
 }
 interface RouterConfig {
     payeeAddress: string;
@@ -266,6 +317,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ _apiKeyResolver: ((key: string) => unknown | Promise<unknown>) | undefined;
     /** @internal */ _providerName: string | undefined;
     /** @internal */ _providerConfig: ProviderConfig | undefined;
+    /** @internal */ _validateFn: ((body: TBody) => void | Promise<void>) | undefined;
     constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
     private fork;
     paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
@@ -290,6 +342,28 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     description(text: string): this;
     path(p: string): this;
     method(m: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH'): this;
+    /**
+     * Add pre-payment validation that runs after body parsing but before the 402
+     * challenge is shown. Use this for async business logic like "is this resource
+     * available?" or "has this user hit their rate limit?".
+     *
+     * Requires `.body()` — call `.body()` before `.validate()` for type inference.
+     *
+     * @example
+     * ```typescript
+     * router
+     *   .route('domain/register')
+     *   .paid(calculatePrice)
+     *   .body(RegisterSchema)  // .body() first for type inference
+     *   .validate(async (body) => {
+     *     if (await isDomainTaken(body.domain)) {
+     *       throw Object.assign(new Error('Domain taken'), { status: 409 });
+     *     }
+     *   })
+     *   .handler(async ({ body }) => { ... });
+     * ```
+     */
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, HasAuth, NeedsBody, HasBody>;
     handler(this: RouteBuilder<TBody, TQuery, True, true, false>, fn: never): never;
     handler(this: RouteBuilder<TBody, TQuery, false, boolean, boolean>, fn: never): never;
     handler(this: RouteBuilder<TBody, TQuery, True, False, HasBody>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
@@ -313,4 +387,4 @@ interface ServiceRouter {
 }
 declare function createRouter(config: RouterConfig): ServiceRouter;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthMode, type ErrorEvent, type HandlerContext, HttpError, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type ErrorEvent, type HandlerContext, HttpError, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisNonceStore, createRouter };

package/dist/index.d.ts

@@ -1,15 +1,53 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
+export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.js';
 
+/**
+ * SIWX challenge expiry in milliseconds.
+ * Currently not configurable per-route — this is a known limitation.
+ * Future versions may add `siwx: { expiryMs }` to RouterConfig.
+ */
+declare const SIWX_CHALLENGE_EXPIRY_MS: number;
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
 }
+/**
+ * In-memory nonce store for development and testing.
+ * NOT suitable for production serverless environments (Vercel, etc.)
+ * where each function invocation gets fresh memory.
+ *
+ * For production, use `createRedisNonceStore()` with Upstash or ioredis.
+ */
 declare class MemoryNonceStore implements NonceStore {
     private seen;
     check(nonce: string): Promise<boolean>;
     private evict;
 }
+interface RedisNonceStoreOptions {
+    /** Key prefix for nonce storage. Default: 'siwx:nonce:' */
+    prefix?: string;
+    /** TTL in milliseconds. Default: SIWX_CHALLENGE_EXPIRY_MS (5 minutes) */
+    ttlMs?: number;
+}
+/**
+ * Create a Redis-backed nonce store for production SIWX replay protection.
+ * Auto-detects client type (Upstash or ioredis) and uses appropriate API.
+ *
+ * @example
+ * ```ts
+ * // Upstash (Vercel)
+ * import { Redis } from '@upstash/redis';
+ * const redis = new Redis({ url: process.env.UPSTASH_URL, token: process.env.UPSTASH_TOKEN });
+ * const nonceStore = createRedisNonceStore(redis);
+ *
+ * // ioredis
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const nonceStore = createRedisNonceStore(redis);
+ * ```
+ */
+declare function createRedisNonceStore(client: unknown, opts?: RedisNonceStoreOptions): NonceStore;
 
 interface RequestMeta {
     requestId: string;
@@ -57,11 +95,23 @@ interface ErrorEvent {
     message: string;
     settled: boolean;
 }
+interface AuthEvent {
+    /** Authentication mode that was verified */
+    authMode: 'siwx' | 'apiKey';
+    /** Verified wallet address (lowercase) */
+    wallet: string | null;
+    /** Route key */
+    route: string;
+    /** Account data from API key resolver (for apiKey auth) */
+    account?: unknown;
+}
 interface RouterPlugin {
     init?(config: {
         origin?: string;
     }): void | Promise<void>;
     onRequest?(meta: RequestMeta): PluginContext;
+    /** Fired after successful SIWX or API key verification, before handler */
+    onAuthVerified?(ctx: PluginContext, event: AuthEvent): void;
     onPaymentVerified?(ctx: PluginContext, payment: PaymentEvent): void;
     onPaymentSettled?(ctx: PluginContext, settlement: SettlementEvent): void;
     onResponse?(ctx: PluginContext, response: ResponseMeta): void;
@@ -171,6 +221,7 @@ interface RouteEntry {
     apiKeyResolver?: (key: string) => unknown | Promise<unknown>;
     providerName?: string;
     providerConfig?: ProviderConfig;
+    validateFn?: (body: unknown) => void | Promise<void>;
 }
 interface RouterConfig {
     payeeAddress: string;
@@ -266,6 +317,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ _apiKeyResolver: ((key: string) => unknown | Promise<unknown>) | undefined;
     /** @internal */ _providerName: string | undefined;
     /** @internal */ _providerConfig: ProviderConfig | undefined;
+    /** @internal */ _validateFn: ((body: TBody) => void | Promise<void>) | undefined;
     constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
     private fork;
     paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
@@ -290,6 +342,28 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     description(text: string): this;
     path(p: string): this;
     method(m: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH'): this;
+    /**
+     * Add pre-payment validation that runs after body parsing but before the 402
+     * challenge is shown. Use this for async business logic like "is this resource
+     * available?" or "has this user hit their rate limit?".
+     *
+     * Requires `.body()` — call `.body()` before `.validate()` for type inference.
+     *
+     * @example
+     * ```typescript
+     * router
+     *   .route('domain/register')
+     *   .paid(calculatePrice)
+     *   .body(RegisterSchema)  // .body() first for type inference
+     *   .validate(async (body) => {
+     *     if (await isDomainTaken(body.domain)) {
+     *       throw Object.assign(new Error('Domain taken'), { status: 409 });
+     *     }
+     *   })
+     *   .handler(async ({ body }) => { ... });
+     * ```
+     */
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, HasAuth, NeedsBody, HasBody>;
     handler(this: RouteBuilder<TBody, TQuery, True, true, false>, fn: never): never;
     handler(this: RouteBuilder<TBody, TQuery, false, boolean, boolean>, fn: never): never;
     handler(this: RouteBuilder<TBody, TQuery, True, False, HasBody>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
@@ -313,4 +387,4 @@ interface ServiceRouter {
 }
 declare function createRouter(config: RouterConfig): ServiceRouter;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthMode, type ErrorEvent, type HandlerContext, HttpError, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type ErrorEvent, type HandlerContext, HttpError, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisNonceStore, createRouter };