@agentcash/router 0.6.8 → 0.7.0

package/README.md

@@ -106,9 +106,20 @@ export const GET = router.wellKnown();
 // app/openapi.json/route.ts
 import { router } from '@/lib/routes';
 import '@/lib/routes/barrel';
-export const GET = router.openapi({ title: 'My API', version: '1.0.0' });
+export const GET = router.openapi({
+  title: 'My API',
+  version: '1.0.0',
+  llmsTxtUrl: 'https://my-api.dev/llms.txt',
+  ownershipProofs: ['did:example:proof'],
+});
 ```
 
+OpenAPI output follows the discovery contract:
+
+- Paid signaling via `responses.402` + `x-payment-info`
+- Auth signaling via `security` + `components.securitySchemes`
+- Optional top-level metadata via `x-discovery` (`llmsTxtUrl`, `ownershipProofs`)
+
 ## API
 
 ### `createRouter(config)`

package/dist/index.cjs

@@ -74,12 +74,14 @@ var init_server = __esm({
 var index_exports = {};
 __export(index_exports, {
   HttpError: () => HttpError,
+  MemoryEntitlementStore: () => MemoryEntitlementStore,
   MemoryNonceStore: () => MemoryNonceStore,
   RouteBuilder: () => RouteBuilder,
   RouteRegistry: () => RouteRegistry,
   SIWX_CHALLENGE_EXPIRY_MS: () => SIWX_CHALLENGE_EXPIRY_MS,
   SIWX_ERROR_MESSAGES: () => SIWX_ERROR_MESSAGES,
   consolePlugin: () => consolePlugin,
+  createRedisEntitlementStore: () => createRedisEntitlementStore,
   createRedisNonceStore: () => createRedisNonceStore,
   createRouter: () => createRouter
 });
@@ -620,7 +622,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         }
       }
     }
-    if (routeEntry.authMode === "siwx") {
+    if (routeEntry.authMode === "siwx" || routeEntry.siwxEnabled) {
       if (routeEntry.validateFn && routeEntry.bodySchema && !request.headers.get("SIGN-IN-WITH-X")) {
         const requestForValidation = request.clone();
         const earlyBodyResult = await parseBody(requestForValidation, routeEntry);
@@ -634,7 +636,8 @@ function createRequestHandler(routeEntry, handler, deps) {
           }
         }
       }
-      if (!request.headers.get("SIGN-IN-WITH-X")) {
+      const siwxHeader = request.headers.get("SIGN-IN-WITH-X");
+      if (!siwxHeader && routeEntry.authMode === "siwx") {
         const url = new URL(request.url);
         const nonce = crypto.randomUUID().replace(/-/g, "");
         const siwxInfo = {
@@ -690,23 +693,41 @@ function createRequestHandler(routeEntry, handler, deps) {
         firePluginResponse(deps, pluginCtx, meta, response);
         return response;
       }
-      const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
-      if (!siwx.valid) {
-        const response = import_server2.NextResponse.json(
-          { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
-          { status: 402 }
-        );
-        firePluginResponse(deps, pluginCtx, meta, response);
-        return response;
+      if (siwxHeader) {
+        const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
+        if (!siwx.valid) {
+          if (routeEntry.authMode === "siwx") {
+            const response = import_server2.NextResponse.json(
+              { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
+              { status: 402 }
+            );
+            firePluginResponse(deps, pluginCtx, meta, response);
+            return response;
+          }
+        } else {
+          const wallet = siwx.wallet.toLowerCase();
+          pluginCtx.setVerifiedWallet(wallet);
+          if (routeEntry.authMode === "siwx") {
+            firePluginHook(deps.plugin, "onAuthVerified", pluginCtx, {
+              authMode: "siwx",
+              wallet,
+              route: routeEntry.key
+            });
+            return handleAuth(wallet, void 0);
+          }
+          if (routeEntry.siwxEnabled && routeEntry.pricing) {
+            const entitled = await deps.entitlementStore.has(routeEntry.key, wallet);
+            if (entitled) {
+              firePluginHook(deps.plugin, "onAuthVerified", pluginCtx, {
+                authMode: "siwx",
+                wallet,
+                route: routeEntry.key
+              });
+              return handleAuth(wallet, account);
+            }
+          }
+        }
       }
-      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") {
       if (routeEntry.pricing) {
@@ -814,6 +835,17 @@ function createRequestHandler(routeEntry, handler, deps) {
             verifyPayload,
             verifyRequirements
           );
+          if (routeEntry.siwxEnabled) {
+            try {
+              await deps.entitlementStore.grant(routeEntry.key, wallet);
+            } catch (error) {
+              firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+                level: "warn",
+                message: `Entitlement grant failed: ${error instanceof Error ? error.message : String(error)}`,
+                route: routeEntry.key
+              });
+            }
+          }
           response.headers.set("PAYMENT-RESPONSE", settle.encoded);
           firePluginHook(deps.plugin, "onPaymentSettled", pluginCtx, {
             protocol: "x402",
@@ -892,6 +924,17 @@ function createRequestHandler(routeEntry, handler, deps) {
         body.data
       );
       if (response.status < 400) {
+        if (routeEntry.siwxEnabled) {
+          try {
+            await deps.entitlementStore.grant(routeEntry.key, wallet);
+          } catch (error) {
+            firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+              level: "warn",
+              message: `Entitlement grant failed: ${error instanceof Error ? error.message : String(error)}`,
+              route: routeEntry.key
+            });
+          }
+        }
         const receiptResponse = mppResult.withReceipt(response);
         finalize(receiptResponse, rawResult, meta, pluginCtx, body.data);
         return receiptResponse;
@@ -1016,6 +1059,18 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
     }
   } catch {
   }
+  if (routeEntry.siwxEnabled) {
+    try {
+      const siwxExtension = await buildSIWXExtension();
+      if (siwxExtension && typeof siwxExtension === "object" && !Array.isArray(siwxExtension)) {
+        extensions = {
+          ...extensions ?? {},
+          ...siwxExtension
+        };
+      }
+    } catch {
+    }
+  }
   if (routeEntry.protocols.includes("x402") && deps.x402Server) {
     try {
       const payTo = await resolvePayTo(routeEntry, request, deps.payeeAddress);
@@ -1120,6 +1175,8 @@ var RouteBuilder = class {
   /** @internal */
   _pricing;
   /** @internal */
+  _siwxEnabled = false;
+  /** @internal */
   _protocols = ["x402"];
   /** @internal */
   _maxPrice;
@@ -1159,15 +1216,14 @@ 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;
-    if (options?.protocols) next._protocols = options.protocols;
+    if (options?.protocols) {
+      next._protocols = options.protocols;
+    } else if (next._protocols.length === 0) {
+      next._protocols = ["x402"];
+    }
     if (options?.maxPrice) next._maxPrice = options.maxPrice;
     if (options?.minPrice) next._minPrice = options.minPrice;
     if (options?.payTo) next._payTo = options.payTo;
@@ -1195,17 +1251,33 @@ var RouteBuilder = class {
     return next;
   }
   siwx() {
-    if (this._authMode === "paid") {
+    if (this._authMode === "unprotected") {
       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.`
+        `route '${this._key}': Cannot combine .unprotected() and .siwx() on the same route.`
+      );
+    }
+    if (this._apiKeyResolver) {
+      throw new Error(
+        `route '${this._key}': Combining .siwx() and .apiKey() is not supported on the same route.`
       );
     }
     const next = this.fork();
+    next._siwxEnabled = true;
+    if (next._authMode === "paid" || next._pricing) {
+      next._authMode = "paid";
+      if (next._protocols.length === 0) next._protocols = ["x402"];
+      return next;
+    }
     next._authMode = "siwx";
     next._protocols = [];
     return next;
   }
   apiKey(resolver) {
+    if (this._siwxEnabled) {
+      throw new Error(
+        `route '${this._key}': Combining .apiKey() and .siwx() is not supported on the same route.`
+      );
+    }
     const next = this.fork();
     next._authMode = "apiKey";
     next._apiKeyResolver = resolver;
@@ -1298,6 +1370,7 @@ var RouteBuilder = class {
     const entry = {
       key: this._key,
       authMode: this._authMode,
+      siwxEnabled: this._siwxEnabled,
       pricing: this._pricing,
       protocols: this._protocols,
       bodySchema: this._bodySchema,
@@ -1319,6 +1392,68 @@ var RouteBuilder = class {
   }
 };
 
+// src/auth/entitlement.ts
+var MemoryEntitlementStore = class {
+  routeToWallets = /* @__PURE__ */ new Map();
+  async has(route, wallet) {
+    const wallets = this.routeToWallets.get(route);
+    if (!wallets) return false;
+    return wallets.has(wallet.toLowerCase());
+  }
+  async grant(route, wallet) {
+    const normalizedWallet = wallet.toLowerCase();
+    let wallets = this.routeToWallets.get(route);
+    if (!wallets) {
+      wallets = /* @__PURE__ */ new Set();
+      this.routeToWallets.set(route, wallets);
+    }
+    wallets.add(normalizedWallet);
+  }
+};
+function detectRedisClientType2(client) {
+  if (!client || typeof client !== "object") {
+    throw new Error(
+      "createRedisEntitlementStore requires a Redis client. Supported: @upstash/redis, ioredis."
+    );
+  }
+  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.sadd === "function" && typeof client.sismember === "function") {
+    return "upstash";
+  }
+  throw new Error("Unrecognized Redis client for entitlement store.");
+}
+function createRedisEntitlementStore(client, options) {
+  const clientType = detectRedisClientType2(client);
+  const prefix = options?.prefix ?? "siwx:entitlement:";
+  return {
+    async has(route, wallet) {
+      const key = `${prefix}${route}`;
+      const normalizedWallet = wallet.toLowerCase();
+      if (clientType === "upstash") {
+        const redis2 = client;
+        const result2 = await redis2.sismember(key, normalizedWallet);
+        return result2 === 1 || result2 === true;
+      }
+      const redis = client;
+      const result = await redis.sismember(key, normalizedWallet);
+      return result === 1;
+    },
+    async grant(route, wallet) {
+      const key = `${prefix}${route}`;
+      const normalizedWallet = wallet.toLowerCase();
+      if (clientType === "upstash") {
+        const redis2 = client;
+        await redis2.sadd(key, normalizedWallet);
+        return;
+      }
+      const redis = client;
+      await redis.sadd(key, normalizedWallet);
+    }
+  };
+}
+
 // src/discovery/well-known.ts
 var import_server3 = require("next/server");
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
@@ -1384,14 +1519,41 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
     const { createDocument } = await import("zod-openapi");
     const paths = {};
     const tagSet = /* @__PURE__ */ new Set();
+    let requiresSiwxScheme = false;
+    let requiresApiKeyScheme = false;
     for (const [key, entry] of registry.entries()) {
       const apiPath = `/api/${entry.path ?? key}`;
       const method = entry.method.toLowerCase();
       const tag = deriveTag(key);
       tagSet.add(tag);
-      paths[apiPath] = { ...paths[apiPath], [method]: buildOperation(key, entry, tag) };
+      const built = buildOperation(key, entry, tag);
+      if (built.requiresSiwxScheme) requiresSiwxScheme = true;
+      if (built.requiresApiKeyScheme) requiresApiKeyScheme = true;
+      paths[apiPath] = { ...paths[apiPath], [method]: built.operation };
+    }
+    const securitySchemes = {};
+    if (requiresSiwxScheme) {
+      securitySchemes.siwx = {
+        type: "apiKey",
+        in: "header",
+        name: "SIGN-IN-WITH-X"
+      };
+    }
+    if (requiresApiKeyScheme) {
+      securitySchemes.apiKey = {
+        type: "apiKey",
+        in: "header",
+        name: "X-API-Key"
+      };
+    }
+    const discoveryMetadata = {};
+    if (options.ownershipProofs && options.ownershipProofs.length > 0) {
+      discoveryMetadata.ownershipProofs = options.ownershipProofs;
     }
-    cached = createDocument({
+    if (options.llmsTxtUrl) {
+      discoveryMetadata.llmsTxtUrl = options.llmsTxtUrl;
+    }
+    const openApiDocument = {
       openapi: "3.1.0",
       info: {
         title: options.title,
@@ -1401,8 +1563,17 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       },
       servers: [{ url: (options.baseUrl ?? normalizedBase).replace(/\/+$/, "") }],
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
+      ...Object.keys(securitySchemes).length > 0 ? {
+        components: {
+          securitySchemes
+        }
+      } : {},
+      ...Object.keys(discoveryMetadata).length > 0 ? {
+        "x-discovery": discoveryMetadata
+      } : {},
       paths
-    });
+    };
+    cached = createDocument(openApiDocument);
     return import_server4.NextResponse.json(cached);
   };
 }
@@ -1411,19 +1582,10 @@ function deriveTag(routeKey) {
 }
 function buildOperation(routeKey, entry, tag) {
   const protocols = entry.protocols.length > 0 ? entry.protocols : void 0;
-  let price;
-  if (typeof entry.pricing === "string") {
-    price = entry.pricing;
-  } else if (typeof entry.pricing === "object" && "tiers" in entry.pricing) {
-    const tierPrices = Object.values(entry.pricing.tiers).map((t) => parseFloat(t.price));
-    const min = Math.min(...tierPrices);
-    const max = Math.max(...tierPrices);
-    price = min === max ? String(min) : `${min}-${max}`;
-  } else if (entry.minPrice && entry.maxPrice) {
-    price = `${entry.minPrice}-${entry.maxPrice}`;
-  } else if (entry.maxPrice) {
-    price = entry.maxPrice;
-  }
+  const paymentRequired = Boolean(entry.pricing) || entry.authMode === "paid";
+  const requiresSiwxScheme = entry.authMode === "siwx" || Boolean(entry.siwxEnabled);
+  const requiresApiKeyScheme = Boolean(entry.apiKeyResolver) && entry.authMode !== "siwx";
+  const pricingInfo = buildPricingInfo(entry);
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
     summary: entry.description ?? routeKey,
@@ -1437,19 +1599,29 @@ function buildOperation(routeKey, entry, tag) {
           }
         }
       },
-      ...entry.authMode === "paid" && {
+      ...(paymentRequired || requiresSiwxScheme) && {
         "402": {
-          description: "Payment Required"
+          description: requiresSiwxScheme ? "Authentication Required" : "Payment Required"
+        }
+      },
+      ...requiresApiKeyScheme && {
+        "401": {
+          description: "Unauthorized"
         }
       }
     }
   };
-  if (price !== void 0 || protocols) {
+  if (paymentRequired && (pricingInfo || protocols)) {
     operation["x-payment-info"] = {
-      ...price !== void 0 && { price },
+      ...pricingInfo ?? {},
       ...protocols && { protocols }
     };
   }
+  if (requiresSiwxScheme) {
+    operation.security = [{ siwx: [] }];
+  } else if (requiresApiKeyScheme) {
+    operation.security = [{ apiKey: [] }];
+  }
   if (entry.bodySchema) {
     operation.requestBody = {
       required: true,
@@ -1463,13 +1635,57 @@ function buildOperation(routeKey, entry, tag) {
       query: entry.querySchema
     };
   }
-  return operation;
+  return {
+    operation,
+    requiresSiwxScheme,
+    requiresApiKeyScheme
+  };
+}
+function buildPricingInfo(entry) {
+  if (!entry.pricing) return void 0;
+  if (typeof entry.pricing === "string") {
+    return {
+      pricingMode: "fixed",
+      price: entry.pricing
+    };
+  }
+  if (typeof entry.pricing === "function") {
+    return {
+      pricingMode: "quote",
+      ...entry.minPrice ? { minPrice: entry.minPrice } : {},
+      ...entry.maxPrice ? { maxPrice: entry.maxPrice } : {}
+    };
+  }
+  if ("tiers" in entry.pricing) {
+    const tierPrices = Object.values(entry.pricing.tiers).map((tier) => parseFloat(tier.price));
+    const min = Math.min(...tierPrices);
+    const max = Math.max(...tierPrices);
+    if (Number.isFinite(min) && Number.isFinite(max)) {
+      if (min === max) {
+        return {
+          pricingMode: "fixed",
+          price: String(min)
+        };
+      }
+      return {
+        pricingMode: "range",
+        minPrice: String(min),
+        maxPrice: String(max)
+      };
+    }
+    return {
+      pricingMode: "quote",
+      ...entry.maxPrice ? { maxPrice: entry.maxPrice } : {}
+    };
+  }
+  return void 0;
 }
 
 // src/index.ts
 function createRouter(config) {
   const registry = new RouteRegistry();
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
+  const entitlementStore = config.siwx?.entitlementStore ?? new MemoryEntitlementStore();
   const network = config.network ?? "eip155:8453";
   if (!config.baseUrl) {
     throw new Error(
@@ -1518,6 +1734,7 @@ function createRouter(config) {
     initPromise: Promise.resolve(),
     plugin: config.plugin,
     nonceStore,
+    entitlementStore,
     payeeAddress: config.payeeAddress,
     network,
     mppx: null
@@ -1602,12 +1819,14 @@ function createRouter(config) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HttpError,
+  MemoryEntitlementStore,
   MemoryNonceStore,
   RouteBuilder,
   RouteRegistry,
   SIWX_CHALLENGE_EXPIRY_MS,
   SIWX_ERROR_MESSAGES,
   consolePlugin,
+  createRedisEntitlementStore,
   createRedisNonceStore,
   createRouter
 });

package/dist/index.d.cts

@@ -3,6 +3,29 @@ 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';
 
+interface EntitlementStore {
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+/**
+ * In-memory SIWX entitlement store.
+ *
+ * Suitable for development and tests. Not durable across server restarts.
+ */
+declare class MemoryEntitlementStore implements EntitlementStore {
+    private readonly routeToWallets;
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+interface RedisEntitlementStoreOptions {
+    /** Key prefix. Default: 'siwx:entitlement:' */
+    prefix?: string;
+}
+/**
+ * Redis-backed entitlement store for paid+SIWX acceleration.
+ */
+declare function createRedisEntitlementStore(client: unknown, options?: RedisEntitlementStoreOptions): EntitlementStore;
+
 /**
  * SIWX challenge expiry in milliseconds.
  * Currently not configurable per-route — this is a known limitation.
@@ -216,6 +239,11 @@ interface ProviderQuotaEvent {
 interface RouteEntry {
     key: string;
     authMode: AuthMode;
+    /**
+     * Enables SIWX acceleration on paid routes.
+     * When true, valid SIWX proofs can bypass repeat payment if entitlement exists.
+     */
+    siwxEnabled?: boolean;
     pricing?: PricingConfig;
     protocols: ProtocolType[];
     bodySchema?: ZodType;
@@ -247,6 +275,7 @@ interface RouterConfig {
     plugin?: RouterPlugin;
     siwx?: {
         nonceStore?: NonceStore;
+        entitlementStore?: EntitlementStore;
     };
     prices?: Record<string, string>;
     mpp?: {
@@ -297,6 +326,8 @@ interface OpenAPIOptions {
         name?: string;
         url?: string;
     };
+    llmsTxtUrl?: string;
+    ownershipProofs?: string[];
 }
 
 interface OrchestrateDeps {
@@ -306,6 +337,7 @@ interface OrchestrateDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    entitlementStore: EntitlementStore;
     payeeAddress: string;
     network: string;
     mppx?: {
@@ -329,6 +361,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ readonly _deps: OrchestrateDeps;
     /** @internal */ _authMode: AuthMode | null;
     /** @internal */ _pricing: PricingConfig | undefined;
+    /** @internal */ _siwxEnabled: boolean;
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
     /** @internal */ _minPrice: string | undefined;
@@ -357,7 +390,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
         }>;
         default?: string;
     }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
-    siwx(): HasAuth extends true ? never : RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    siwx(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, True, NeedsBody, HasBody>;
     unprotected(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     provider(name: string, config?: ProviderConfig): this;
@@ -414,4 +447,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-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 };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, 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 RedisEntitlementStoreOptions, 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, createRedisEntitlementStore, createRedisNonceStore, createRouter };

package/dist/index.d.ts

@@ -3,6 +3,29 @@ 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';
 
+interface EntitlementStore {
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+/**
+ * In-memory SIWX entitlement store.
+ *
+ * Suitable for development and tests. Not durable across server restarts.
+ */
+declare class MemoryEntitlementStore implements EntitlementStore {
+    private readonly routeToWallets;
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+interface RedisEntitlementStoreOptions {
+    /** Key prefix. Default: 'siwx:entitlement:' */
+    prefix?: string;
+}
+/**
+ * Redis-backed entitlement store for paid+SIWX acceleration.
+ */
+declare function createRedisEntitlementStore(client: unknown, options?: RedisEntitlementStoreOptions): EntitlementStore;
+
 /**
  * SIWX challenge expiry in milliseconds.
  * Currently not configurable per-route — this is a known limitation.
@@ -216,6 +239,11 @@ interface ProviderQuotaEvent {
 interface RouteEntry {
     key: string;
     authMode: AuthMode;
+    /**
+     * Enables SIWX acceleration on paid routes.
+     * When true, valid SIWX proofs can bypass repeat payment if entitlement exists.
+     */
+    siwxEnabled?: boolean;
     pricing?: PricingConfig;
     protocols: ProtocolType[];
     bodySchema?: ZodType;
@@ -247,6 +275,7 @@ interface RouterConfig {
     plugin?: RouterPlugin;
     siwx?: {
         nonceStore?: NonceStore;
+        entitlementStore?: EntitlementStore;
     };
     prices?: Record<string, string>;
     mpp?: {
@@ -297,6 +326,8 @@ interface OpenAPIOptions {
         name?: string;
         url?: string;
     };
+    llmsTxtUrl?: string;
+    ownershipProofs?: string[];
 }
 
 interface OrchestrateDeps {
@@ -306,6 +337,7 @@ interface OrchestrateDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    entitlementStore: EntitlementStore;
     payeeAddress: string;
     network: string;
     mppx?: {
@@ -329,6 +361,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ readonly _deps: OrchestrateDeps;
     /** @internal */ _authMode: AuthMode | null;
     /** @internal */ _pricing: PricingConfig | undefined;
+    /** @internal */ _siwxEnabled: boolean;
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
     /** @internal */ _minPrice: string | undefined;
@@ -357,7 +390,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
         }>;
         default?: string;
     }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
-    siwx(): HasAuth extends true ? never : RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    siwx(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, True, NeedsBody, HasBody>;
     unprotected(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     provider(name: string, config?: ProviderConfig): this;
@@ -414,4 +447,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-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 };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, 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 RedisEntitlementStoreOptions, 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, createRedisEntitlementStore, createRedisNonceStore, createRouter };

package/dist/index.js

@@ -583,7 +583,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         }
       }
     }
-    if (routeEntry.authMode === "siwx") {
+    if (routeEntry.authMode === "siwx" || routeEntry.siwxEnabled) {
       if (routeEntry.validateFn && routeEntry.bodySchema && !request.headers.get("SIGN-IN-WITH-X")) {
         const requestForValidation = request.clone();
         const earlyBodyResult = await parseBody(requestForValidation, routeEntry);
@@ -597,7 +597,8 @@ function createRequestHandler(routeEntry, handler, deps) {
           }
         }
       }
-      if (!request.headers.get("SIGN-IN-WITH-X")) {
+      const siwxHeader = request.headers.get("SIGN-IN-WITH-X");
+      if (!siwxHeader && routeEntry.authMode === "siwx") {
         const url = new URL(request.url);
         const nonce = crypto.randomUUID().replace(/-/g, "");
         const siwxInfo = {
@@ -653,23 +654,41 @@ function createRequestHandler(routeEntry, handler, deps) {
         firePluginResponse(deps, pluginCtx, meta, response);
         return response;
       }
-      const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
-      if (!siwx.valid) {
-        const response = NextResponse2.json(
-          { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
-          { status: 402 }
-        );
-        firePluginResponse(deps, pluginCtx, meta, response);
-        return response;
+      if (siwxHeader) {
+        const siwx = await verifySIWX(request, routeEntry, deps.nonceStore);
+        if (!siwx.valid) {
+          if (routeEntry.authMode === "siwx") {
+            const response = NextResponse2.json(
+              { error: siwx.code, message: SIWX_ERROR_MESSAGES[siwx.code] },
+              { status: 402 }
+            );
+            firePluginResponse(deps, pluginCtx, meta, response);
+            return response;
+          }
+        } else {
+          const wallet = siwx.wallet.toLowerCase();
+          pluginCtx.setVerifiedWallet(wallet);
+          if (routeEntry.authMode === "siwx") {
+            firePluginHook(deps.plugin, "onAuthVerified", pluginCtx, {
+              authMode: "siwx",
+              wallet,
+              route: routeEntry.key
+            });
+            return handleAuth(wallet, void 0);
+          }
+          if (routeEntry.siwxEnabled && routeEntry.pricing) {
+            const entitled = await deps.entitlementStore.has(routeEntry.key, wallet);
+            if (entitled) {
+              firePluginHook(deps.plugin, "onAuthVerified", pluginCtx, {
+                authMode: "siwx",
+                wallet,
+                route: routeEntry.key
+              });
+              return handleAuth(wallet, account);
+            }
+          }
+        }
       }
-      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") {
       if (routeEntry.pricing) {
@@ -777,6 +796,17 @@ function createRequestHandler(routeEntry, handler, deps) {
             verifyPayload,
             verifyRequirements
           );
+          if (routeEntry.siwxEnabled) {
+            try {
+              await deps.entitlementStore.grant(routeEntry.key, wallet);
+            } catch (error) {
+              firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+                level: "warn",
+                message: `Entitlement grant failed: ${error instanceof Error ? error.message : String(error)}`,
+                route: routeEntry.key
+              });
+            }
+          }
           response.headers.set("PAYMENT-RESPONSE", settle.encoded);
           firePluginHook(deps.plugin, "onPaymentSettled", pluginCtx, {
             protocol: "x402",
@@ -855,6 +885,17 @@ function createRequestHandler(routeEntry, handler, deps) {
         body.data
       );
       if (response.status < 400) {
+        if (routeEntry.siwxEnabled) {
+          try {
+            await deps.entitlementStore.grant(routeEntry.key, wallet);
+          } catch (error) {
+            firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+              level: "warn",
+              message: `Entitlement grant failed: ${error instanceof Error ? error.message : String(error)}`,
+              route: routeEntry.key
+            });
+          }
+        }
         const receiptResponse = mppResult.withReceipt(response);
         finalize(receiptResponse, rawResult, meta, pluginCtx, body.data);
         return receiptResponse;
@@ -979,6 +1020,18 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
     }
   } catch {
   }
+  if (routeEntry.siwxEnabled) {
+    try {
+      const siwxExtension = await buildSIWXExtension();
+      if (siwxExtension && typeof siwxExtension === "object" && !Array.isArray(siwxExtension)) {
+        extensions = {
+          ...extensions ?? {},
+          ...siwxExtension
+        };
+      }
+    } catch {
+    }
+  }
   if (routeEntry.protocols.includes("x402") && deps.x402Server) {
     try {
       const payTo = await resolvePayTo(routeEntry, request, deps.payeeAddress);
@@ -1083,6 +1136,8 @@ var RouteBuilder = class {
   /** @internal */
   _pricing;
   /** @internal */
+  _siwxEnabled = false;
+  /** @internal */
   _protocols = ["x402"];
   /** @internal */
   _maxPrice;
@@ -1122,15 +1177,14 @@ 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;
-    if (options?.protocols) next._protocols = options.protocols;
+    if (options?.protocols) {
+      next._protocols = options.protocols;
+    } else if (next._protocols.length === 0) {
+      next._protocols = ["x402"];
+    }
     if (options?.maxPrice) next._maxPrice = options.maxPrice;
     if (options?.minPrice) next._minPrice = options.minPrice;
     if (options?.payTo) next._payTo = options.payTo;
@@ -1158,17 +1212,33 @@ var RouteBuilder = class {
     return next;
   }
   siwx() {
-    if (this._authMode === "paid") {
+    if (this._authMode === "unprotected") {
       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.`
+        `route '${this._key}': Cannot combine .unprotected() and .siwx() on the same route.`
+      );
+    }
+    if (this._apiKeyResolver) {
+      throw new Error(
+        `route '${this._key}': Combining .siwx() and .apiKey() is not supported on the same route.`
       );
     }
     const next = this.fork();
+    next._siwxEnabled = true;
+    if (next._authMode === "paid" || next._pricing) {
+      next._authMode = "paid";
+      if (next._protocols.length === 0) next._protocols = ["x402"];
+      return next;
+    }
     next._authMode = "siwx";
     next._protocols = [];
     return next;
   }
   apiKey(resolver) {
+    if (this._siwxEnabled) {
+      throw new Error(
+        `route '${this._key}': Combining .apiKey() and .siwx() is not supported on the same route.`
+      );
+    }
     const next = this.fork();
     next._authMode = "apiKey";
     next._apiKeyResolver = resolver;
@@ -1261,6 +1331,7 @@ var RouteBuilder = class {
     const entry = {
       key: this._key,
       authMode: this._authMode,
+      siwxEnabled: this._siwxEnabled,
       pricing: this._pricing,
       protocols: this._protocols,
       bodySchema: this._bodySchema,
@@ -1282,6 +1353,68 @@ var RouteBuilder = class {
   }
 };
 
+// src/auth/entitlement.ts
+var MemoryEntitlementStore = class {
+  routeToWallets = /* @__PURE__ */ new Map();
+  async has(route, wallet) {
+    const wallets = this.routeToWallets.get(route);
+    if (!wallets) return false;
+    return wallets.has(wallet.toLowerCase());
+  }
+  async grant(route, wallet) {
+    const normalizedWallet = wallet.toLowerCase();
+    let wallets = this.routeToWallets.get(route);
+    if (!wallets) {
+      wallets = /* @__PURE__ */ new Set();
+      this.routeToWallets.set(route, wallets);
+    }
+    wallets.add(normalizedWallet);
+  }
+};
+function detectRedisClientType2(client) {
+  if (!client || typeof client !== "object") {
+    throw new Error(
+      "createRedisEntitlementStore requires a Redis client. Supported: @upstash/redis, ioredis."
+    );
+  }
+  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.sadd === "function" && typeof client.sismember === "function") {
+    return "upstash";
+  }
+  throw new Error("Unrecognized Redis client for entitlement store.");
+}
+function createRedisEntitlementStore(client, options) {
+  const clientType = detectRedisClientType2(client);
+  const prefix = options?.prefix ?? "siwx:entitlement:";
+  return {
+    async has(route, wallet) {
+      const key = `${prefix}${route}`;
+      const normalizedWallet = wallet.toLowerCase();
+      if (clientType === "upstash") {
+        const redis2 = client;
+        const result2 = await redis2.sismember(key, normalizedWallet);
+        return result2 === 1 || result2 === true;
+      }
+      const redis = client;
+      const result = await redis.sismember(key, normalizedWallet);
+      return result === 1;
+    },
+    async grant(route, wallet) {
+      const key = `${prefix}${route}`;
+      const normalizedWallet = wallet.toLowerCase();
+      if (clientType === "upstash") {
+        const redis2 = client;
+        await redis2.sadd(key, normalizedWallet);
+        return;
+      }
+      const redis = client;
+      await redis.sadd(key, normalizedWallet);
+    }
+  };
+}
+
 // src/discovery/well-known.ts
 import { NextResponse as NextResponse3 } from "next/server";
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
@@ -1347,14 +1480,41 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
     const { createDocument } = await import("zod-openapi");
     const paths = {};
     const tagSet = /* @__PURE__ */ new Set();
+    let requiresSiwxScheme = false;
+    let requiresApiKeyScheme = false;
     for (const [key, entry] of registry.entries()) {
       const apiPath = `/api/${entry.path ?? key}`;
       const method = entry.method.toLowerCase();
       const tag = deriveTag(key);
       tagSet.add(tag);
-      paths[apiPath] = { ...paths[apiPath], [method]: buildOperation(key, entry, tag) };
+      const built = buildOperation(key, entry, tag);
+      if (built.requiresSiwxScheme) requiresSiwxScheme = true;
+      if (built.requiresApiKeyScheme) requiresApiKeyScheme = true;
+      paths[apiPath] = { ...paths[apiPath], [method]: built.operation };
+    }
+    const securitySchemes = {};
+    if (requiresSiwxScheme) {
+      securitySchemes.siwx = {
+        type: "apiKey",
+        in: "header",
+        name: "SIGN-IN-WITH-X"
+      };
+    }
+    if (requiresApiKeyScheme) {
+      securitySchemes.apiKey = {
+        type: "apiKey",
+        in: "header",
+        name: "X-API-Key"
+      };
+    }
+    const discoveryMetadata = {};
+    if (options.ownershipProofs && options.ownershipProofs.length > 0) {
+      discoveryMetadata.ownershipProofs = options.ownershipProofs;
     }
-    cached = createDocument({
+    if (options.llmsTxtUrl) {
+      discoveryMetadata.llmsTxtUrl = options.llmsTxtUrl;
+    }
+    const openApiDocument = {
       openapi: "3.1.0",
       info: {
         title: options.title,
@@ -1364,8 +1524,17 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       },
       servers: [{ url: (options.baseUrl ?? normalizedBase).replace(/\/+$/, "") }],
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
+      ...Object.keys(securitySchemes).length > 0 ? {
+        components: {
+          securitySchemes
+        }
+      } : {},
+      ...Object.keys(discoveryMetadata).length > 0 ? {
+        "x-discovery": discoveryMetadata
+      } : {},
       paths
-    });
+    };
+    cached = createDocument(openApiDocument);
     return NextResponse4.json(cached);
   };
 }
@@ -1374,19 +1543,10 @@ function deriveTag(routeKey) {
 }
 function buildOperation(routeKey, entry, tag) {
   const protocols = entry.protocols.length > 0 ? entry.protocols : void 0;
-  let price;
-  if (typeof entry.pricing === "string") {
-    price = entry.pricing;
-  } else if (typeof entry.pricing === "object" && "tiers" in entry.pricing) {
-    const tierPrices = Object.values(entry.pricing.tiers).map((t) => parseFloat(t.price));
-    const min = Math.min(...tierPrices);
-    const max = Math.max(...tierPrices);
-    price = min === max ? String(min) : `${min}-${max}`;
-  } else if (entry.minPrice && entry.maxPrice) {
-    price = `${entry.minPrice}-${entry.maxPrice}`;
-  } else if (entry.maxPrice) {
-    price = entry.maxPrice;
-  }
+  const paymentRequired = Boolean(entry.pricing) || entry.authMode === "paid";
+  const requiresSiwxScheme = entry.authMode === "siwx" || Boolean(entry.siwxEnabled);
+  const requiresApiKeyScheme = Boolean(entry.apiKeyResolver) && entry.authMode !== "siwx";
+  const pricingInfo = buildPricingInfo(entry);
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
     summary: entry.description ?? routeKey,
@@ -1400,19 +1560,29 @@ function buildOperation(routeKey, entry, tag) {
           }
         }
       },
-      ...entry.authMode === "paid" && {
+      ...(paymentRequired || requiresSiwxScheme) && {
         "402": {
-          description: "Payment Required"
+          description: requiresSiwxScheme ? "Authentication Required" : "Payment Required"
+        }
+      },
+      ...requiresApiKeyScheme && {
+        "401": {
+          description: "Unauthorized"
         }
       }
     }
   };
-  if (price !== void 0 || protocols) {
+  if (paymentRequired && (pricingInfo || protocols)) {
     operation["x-payment-info"] = {
-      ...price !== void 0 && { price },
+      ...pricingInfo ?? {},
       ...protocols && { protocols }
     };
   }
+  if (requiresSiwxScheme) {
+    operation.security = [{ siwx: [] }];
+  } else if (requiresApiKeyScheme) {
+    operation.security = [{ apiKey: [] }];
+  }
   if (entry.bodySchema) {
     operation.requestBody = {
       required: true,
@@ -1426,13 +1596,57 @@ function buildOperation(routeKey, entry, tag) {
       query: entry.querySchema
     };
   }
-  return operation;
+  return {
+    operation,
+    requiresSiwxScheme,
+    requiresApiKeyScheme
+  };
+}
+function buildPricingInfo(entry) {
+  if (!entry.pricing) return void 0;
+  if (typeof entry.pricing === "string") {
+    return {
+      pricingMode: "fixed",
+      price: entry.pricing
+    };
+  }
+  if (typeof entry.pricing === "function") {
+    return {
+      pricingMode: "quote",
+      ...entry.minPrice ? { minPrice: entry.minPrice } : {},
+      ...entry.maxPrice ? { maxPrice: entry.maxPrice } : {}
+    };
+  }
+  if ("tiers" in entry.pricing) {
+    const tierPrices = Object.values(entry.pricing.tiers).map((tier) => parseFloat(tier.price));
+    const min = Math.min(...tierPrices);
+    const max = Math.max(...tierPrices);
+    if (Number.isFinite(min) && Number.isFinite(max)) {
+      if (min === max) {
+        return {
+          pricingMode: "fixed",
+          price: String(min)
+        };
+      }
+      return {
+        pricingMode: "range",
+        minPrice: String(min),
+        maxPrice: String(max)
+      };
+    }
+    return {
+      pricingMode: "quote",
+      ...entry.maxPrice ? { maxPrice: entry.maxPrice } : {}
+    };
+  }
+  return void 0;
 }
 
 // src/index.ts
 function createRouter(config) {
   const registry = new RouteRegistry();
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
+  const entitlementStore = config.siwx?.entitlementStore ?? new MemoryEntitlementStore();
   const network = config.network ?? "eip155:8453";
   if (!config.baseUrl) {
     throw new Error(
@@ -1481,6 +1695,7 @@ function createRouter(config) {
     initPromise: Promise.resolve(),
     plugin: config.plugin,
     nonceStore,
+    entitlementStore,
     payeeAddress: config.payeeAddress,
     network,
     mppx: null
@@ -1564,12 +1779,14 @@ function createRouter(config) {
 }
 export {
   HttpError,
+  MemoryEntitlementStore,
   MemoryNonceStore,
   RouteBuilder,
   RouteRegistry,
   SIWX_CHALLENGE_EXPIRY_MS,
   SIWX_ERROR_MESSAGES,
   consolePlugin,
+  createRedisEntitlementStore,
   createRedisNonceStore,
   createRouter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -48,7 +48,7 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "eslint": "^10.0.0",
-    "mppx": "^0.3.8",
+    "mppx": "^0.3.9",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
     "react": "^19.0.0",