@agentcash/router 0.4.6 → 0.4.7

package/dist/index.js

@@ -130,6 +130,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}`);
     },
@@ -159,6 +163,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")) {
@@ -433,21 +496,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 };
 }
@@ -521,6 +610,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,
@@ -545,13 +643,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) {
@@ -559,11 +664,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,
@@ -572,7 +701,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;
@@ -592,6 +721,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 } : {}
             }
           }
@@ -617,15 +748,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 = NextResponse2.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);
@@ -635,6 +772,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);
@@ -661,10 +807,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
       });
@@ -672,7 +819,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         request,
         meta,
         pluginCtx,
-        verify.payer,
+        wallet,
         account,
         body.data
       );
@@ -723,7 +870,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",
@@ -982,6 +1129,8 @@ var RouteBuilder = class {
   _providerName;
   /** @internal */
   _providerConfig;
+  /** @internal */
+  _validateFn;
   constructor(key, registry, deps) {
     this._key = key;
     this._registry = registry;
@@ -994,6 +1143,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;
@@ -1023,6 +1177,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 = [];
@@ -1083,7 +1242,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,
@@ -1098,30 +1291,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
 import { NextResponse as NextResponse3 } from "next/server";
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
@@ -1353,6 +1530,9 @@ export {
   MemoryNonceStore,
   RouteBuilder,
   RouteRegistry,
+  SIWX_CHALLENGE_EXPIRY_MS,
+  SIWX_ERROR_MESSAGES,
   consolePlugin,
+  createRedisNonceStore,
   createRouter
 };

package/dist/siwx-BMlja_nt.d.cts

@@ -0,0 +1,9 @@
+/**
+ * SIWX verification error codes.
+ * Enables clients to auto-retry transient failures (e.g., expired challenge).
+ */
+type SiwxErrorCode = 'siwx_missing_header' | 'siwx_malformed' | 'siwx_expired' | 'siwx_nonce_used' | 'siwx_invalid_signature';
+/** Human-readable error messages for each SIWX error code. */
+declare const SIWX_ERROR_MESSAGES: Record<SiwxErrorCode, string>;
+
+export { SIWX_ERROR_MESSAGES as S, type SiwxErrorCode as a };

package/dist/siwx-BMlja_nt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SIWX verification error codes.
+ * Enables clients to auto-retry transient failures (e.g., expired challenge).
+ */
+type SiwxErrorCode = 'siwx_missing_header' | 'siwx_malformed' | 'siwx_expired' | 'siwx_nonce_used' | 'siwx_invalid_signature';
+/** Human-readable error messages for each SIWX error code. */
+declare const SIWX_ERROR_MESSAGES: Record<SiwxErrorCode, string>;
+
+export { SIWX_ERROR_MESSAGES as S, type SiwxErrorCode as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {