@x402/extensions 2.6.0 → 2.8.0

package/README.md

@@ -471,7 +471,7 @@ The Sign-In-With-X extension implements [CAIP-122](https://chainagnostic.org/CAI
 1. Server returns 402 with `sign-in-with-x` extension containing challenge parameters
 2. Client signs the CAIP-122 message with their wallet
 3. Client sends signed proof in `SIGN-IN-WITH-X` header
-4. Server verifies signature and grants access if wallet has previous payment
+4. Server verifies signature and grants access either because the route is auth-only or because the wallet has previously paid
 
 ### Server Usage
 
@@ -495,7 +495,7 @@ const resourceServer = new x402ResourceServer(facilitatorClient)
   .registerExtension(siwxResourceServerExtension)  // Refreshes nonce/timestamps per request
   .onAfterSettle(createSIWxSettleHook({ storage }));  // Records payments
 
-// 2. Declare SIWX support in routes (network/domain/uri derived automatically)
+// 2. Declare SIWX support in routes
 const routes = {
   "GET /data": {
     accepts: [{scheme: "exact", price: "$0.01", network: "eip155:8453", payTo}],
@@ -503,11 +503,19 @@ const routes = {
       statement: 'Sign in to access your purchased content',
     }),
   },
+  "GET /profile": {
+    accepts: [],
+    extensions: declareSIWxExtension({
+      network: ["eip155:8453", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"],
+      statement: 'Sign in to view your profile',
+      expirationSeconds: 300,
+    }),
+  },
 };
 
 // 3. Verify incoming SIWX proofs
 const httpServer = new x402HTTPResourceServer(resourceServer, routes)
-  .onProtectedRequest(createSIWxRequestHook({ storage }));  // Grants access if paid
+  .onProtectedRequest(createSIWxRequestHook({ storage }));  // Grants access when SIWX auth is sufficient
 
 // Optional: Enable smart wallet support (EIP-1271/EIP-6492)
 import { createPublicClient, http } from 'viem';
@@ -524,7 +532,7 @@ const httpServerWithSmartWallets = new x402HTTPResourceServer(resourceServer, ro
 The hooks automatically:
 - **siwxResourceServerExtension**: Derives `network` from `accepts`, `domain`/`uri` from request URL, refreshes `nonce`/`issuedAt`/`expirationTime` per request
 - **createSIWxSettleHook**: Records payment when settlement succeeds
-- **createSIWxRequestHook**: Validates and verifies SIWX proofs, grants access if wallet has paid
+- **createSIWxRequestHook**: Validates and verifies SIWX proofs, grants access for auth-only routes or when the wallet has paid
 
 #### Manual Usage (Advanced)
 
@@ -534,18 +542,15 @@ import {
   parseSIWxHeader,
   validateSIWxMessage,
   verifySIWxSignature,
-  SIGN_IN_WITH_X,
 } from '@x402/extensions/sign-in-with-x';
 
 // 1. Declare in PaymentRequired response
-const extensions = {
-  [SIGN_IN_WITH_X]: declareSIWxExtension({
-    domain: 'api.example.com',
-    resourceUri: 'https://api.example.com/data',
-    network: 'eip155:8453',
-    statement: 'Sign in to access your purchased content',
-  }),
-};
+const extensions = declareSIWxExtension({
+  domain: 'api.example.com',
+  resourceUri: 'https://api.example.com/data',
+  network: 'eip155:8453',
+  statement: 'Sign in to access your purchased content',
+});
 
 // 2. Verify incoming proof
 async function handleRequest(request: Request) {
@@ -571,10 +576,8 @@ async function handleRequest(request: Request) {
   }
 
   // verification.address is the verified wallet
-  // Check if this wallet has paid before
-  const hasPaid = await checkPaymentHistory(verification.address);
-  if (hasPaid) {
-    // Grant access without payment
+  if (await isAuthOnlyRoute(request) || await checkPaymentHistory(verification.address)) {
+    // Grant access
   }
 }
 ```
@@ -612,15 +615,15 @@ import {
 // 1. Get extension and network from 402 response
 const paymentRequired = await response.json();
 const extension = paymentRequired.extensions['sign-in-with-x'];
-const paymentNetwork = paymentRequired.accepts[0].network; // e.g., "eip155:8453"
+const paymentNetwork = paymentRequired.accepts[0]?.network; // undefined for auth-only routes
 
 // 2. Find matching chain in supportedChains
-const matchingChain = extension.supportedChains.find(
-  chain => chain.chainId === paymentNetwork
-);
+const matchingChain = paymentNetwork
+  ? extension.supportedChains.find(chain => chain.chainId === paymentNetwork)
+  : extension.supportedChains[0];
 
 if (!matchingChain) {
-  // Payment network not supported for SIWX
+  // No chain supported by this signer / route combination
   throw new Error('Chain not supported');
 }
 
@@ -664,6 +667,8 @@ declareSIWxExtension({
 - `resourceUri` → from request URL
 - `domain` → parsed from resourceUri
 
+For auth-only routes declared with `accepts: []`, `network` cannot be inferred from payment requirements and should be provided explicitly.
+
 **Multi-chain support:** When `network` is an array (or multiple networks in `accepts`), `supportedChains` will contain one entry per network.
 
 #### `parseSIWxHeader(header)`

package/dist/cjs/bazaar/index.d.ts

@@ -1,3 +1,3 @@
-export { k as BAZAAR, A as BazaarClientExtension, c as BodyDiscoveryExtension, B as BodyDiscoveryInfo, g as DeclareBodyDiscoveryExtensionConfig, i as DeclareDiscoveryExtensionConfig, j as DeclareDiscoveryExtensionInput, h as DeclareMcpDiscoveryExtensionConfig, f as DeclareQueryDiscoveryExtensionConfig, s as DiscoveredHTTPResource, t as DiscoveredMCPResource, u as DiscoveredResource, e as DiscoveryExtension, D as DiscoveryInfo, C as DiscoveryResource, E as DiscoveryResourcesResponse, L as ListDiscoveryResourcesParams, d as McpDiscoveryExtension, M as McpDiscoveryInfo, a as QueryDiscoveryExtension, Q as QueryDiscoveryInfo, V as ValidationResult, b as bazaarResourceServerExtension, o as declareDiscoveryExtension, p as extractDiscoveryInfo, q as extractDiscoveryInfoFromExtension, w as extractDiscoveryInfoV1, y as extractResourceMetadataV1, n as isBodyExtensionConfig, x as isDiscoverableV1, l as isMcpExtensionConfig, m as isQueryExtensionConfig, r as validateAndExtract, v as validateDiscoveryExtension, z as withBazaar } from '../index-CtOzXcjN.js';
+export { k as BAZAAR, E as BazaarClientExtension, c as BodyDiscoveryExtension, B as BodyDiscoveryInfo, g as DeclareBodyDiscoveryExtensionConfig, i as DeclareDiscoveryExtensionConfig, j as DeclareDiscoveryExtensionInput, h as DeclareMcpDiscoveryExtensionConfig, f as DeclareQueryDiscoveryExtensionConfig, u as DiscoveredHTTPResource, w as DiscoveredMCPResource, x as DiscoveredResource, e as DiscoveryExtension, D as DiscoveryInfo, F as DiscoveryResource, G as DiscoveryResourcesResponse, L as ListDiscoveryResourcesParams, d as McpDiscoveryExtension, M as McpDiscoveryInfo, a as QueryDiscoveryExtension, Q as QueryDiscoveryInfo, V as ValidationResult, b as bazaarResourceServerExtension, o as declareDiscoveryExtension, r as extractDiscoveryInfo, s as extractDiscoveryInfoFromExtension, y as extractDiscoveryInfoV1, A as extractResourceMetadataV1, n as isBodyExtensionConfig, z as isDiscoverableV1, l as isMcpExtensionConfig, m as isQueryExtensionConfig, p as isValidRouteTemplate, t as validateAndExtract, v as validateDiscoveryExtension, q as validateRouteTemplate, C as withBazaar } from '../index-DihVrF7v.js';
 import '@x402/core/types';
 import '@x402/core/http';

package/dist/cjs/bazaar/index.js

@@ -41,8 +41,10 @@ __export(bazaar_exports, {
   isDiscoverableV1: () => isDiscoverableV1,
   isMcpExtensionConfig: () => isMcpExtensionConfig,
   isQueryExtensionConfig: () => isQueryExtensionConfig,
+  isValidRouteTemplate: () => isValidRouteTemplate,
   validateAndExtract: () => validateAndExtract,
   validateDiscoveryExtension: () => validateDiscoveryExtension,
+  validateRouteTemplate: () => validateRouteTemplate,
   withBazaar: () => withBazaar
 });
 module.exports = __toCommonJS(bazaar_exports);
@@ -68,6 +70,8 @@ function createQueryDiscoveryExtension({
   method,
   input = {},
   inputSchema = { properties: {} },
+  pathParams,
+  pathParamsSchema,
   output
 }) {
   return {
@@ -75,7 +79,8 @@ function createQueryDiscoveryExtension({
       input: {
         type: "http",
         ...method ? { method } : {},
-        ...input ? { queryParams: input } : {}
+        ...input ? { queryParams: input } : {},
+        ...pathParams ? { pathParams } : {}
       },
       ...output?.example ? {
         output: {
@@ -104,9 +109,18 @@ function createQueryDiscoveryExtension({
                 type: "object",
                 ...typeof inputSchema === "object" ? inputSchema : {}
               }
+            } : {},
+            ...pathParamsSchema ? {
+              pathParams: {
+                type: "object",
+                ...typeof pathParamsSchema === "object" ? pathParamsSchema : {}
+              }
             } : {}
           },
           required: ["type"],
+          // pathParams and method are not declared here at schema build time --
+          // the server extension's enrichDeclaration adds them to both info and schema
+          // atomically at request time, keeping data and schema consistent.
           additionalProperties: false
         },
         ...output?.example ? {
@@ -133,6 +147,8 @@ function createBodyDiscoveryExtension({
   method,
   input = {},
   inputSchema = { properties: {} },
+  pathParams,
+  pathParamsSchema,
   bodyType,
   output
 }) {
@@ -142,7 +158,8 @@ function createBodyDiscoveryExtension({
         type: "http",
         ...method ? { method } : {},
         bodyType,
-        body: input
+        body: input,
+        ...pathParams ? { pathParams } : {}
       },
       ...output?.example ? {
         output: {
@@ -170,9 +187,18 @@ function createBodyDiscoveryExtension({
               type: "string",
               enum: ["json", "form-data", "text"]
             },
-            body: inputSchema
+            body: inputSchema,
+            ...pathParamsSchema ? {
+              pathParams: {
+                type: "object",
+                ...typeof pathParamsSchema === "object" ? pathParamsSchema : {}
+              }
+            } : {}
           },
           required: ["type", "bodyType", "body"],
+          // pathParams and method are not declared here at schema build time --
+          // the server extension's enrichDeclaration adds them to both info and schema
+          // atomically at request time, keeping data and schema consistent.
           additionalProperties: false
         },
         ...output?.example ? {
@@ -293,9 +319,57 @@ function declareDiscoveryExtension(config) {
 }
 
 // src/bazaar/server.ts
+var BRACKET_PARAM_REGEX = /\[([^\]]+)\]/;
+var BRACKET_PARAM_REGEX_ALL = /\[([^\]]+)\]/g;
+var COLON_PARAM_REGEX = /:([a-zA-Z_][a-zA-Z0-9_]*)/;
 function isHTTPRequestContext(ctx) {
   return ctx !== null && typeof ctx === "object" && "method" in ctx && "adapter" in ctx;
 }
+function normalizeWildcardPattern(pattern) {
+  if (!pattern.includes("*")) {
+    return pattern;
+  }
+  let counter = 0;
+  return pattern.split("/").map((seg) => {
+    if (seg === "*") {
+      counter++;
+      return `:var${counter}`;
+    }
+    return seg;
+  }).join("/");
+}
+function extractDynamicRouteInfo(routePattern, urlPath) {
+  const hasBracket = BRACKET_PARAM_REGEX.test(routePattern);
+  const hasColon = COLON_PARAM_REGEX.test(routePattern);
+  if (!hasBracket && !hasColon) {
+    return null;
+  }
+  const normalizedPattern = hasBracket ? routePattern.replace(BRACKET_PARAM_REGEX_ALL, ":$1") : routePattern;
+  const pathParams = extractPathParams(normalizedPattern, urlPath, false);
+  return { routeTemplate: normalizedPattern, pathParams };
+}
+function extractPathParams(routePattern, urlPath, isBracket) {
+  const paramNames = [];
+  const splitRegex = isBracket ? BRACKET_PARAM_REGEX : COLON_PARAM_REGEX;
+  const parts = routePattern.split(splitRegex);
+  const regexParts = [];
+  parts.forEach((part, i) => {
+    if (i % 2 === 0) {
+      regexParts.push(part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    } else {
+      paramNames.push(part);
+      regexParts.push("([^/]+)");
+    }
+  });
+  const regex = new RegExp(`^${regexParts.join("")}$`);
+  const match = urlPath.match(regex);
+  if (!match) return {};
+  const result = {};
+  paramNames.forEach((name, idx) => {
+    result[name] = match[idx + 1];
+  });
+  return result;
+}
 var bazaarResourceServerExtension = {
   key: BAZAAR.key,
   enrichDeclaration: (declaration, transportContext) => {
@@ -315,7 +389,7 @@ var bazaarResourceServerExtension = {
         enum: [method]
       }
     };
-    return {
+    const enrichedResult = {
       ...extension,
       info: {
         ...extension.info || {},
@@ -339,6 +413,37 @@ var bazaarResourceServerExtension = {
         }
       }
     };
+    const rawRoutePattern = transportContext.routePattern;
+    const routePattern = rawRoutePattern ? normalizeWildcardPattern(rawRoutePattern) : void 0;
+    const dynamicRoute = routePattern ? extractDynamicRouteInfo(routePattern, transportContext.adapter.getPath()) : null;
+    if (dynamicRoute) {
+      const inputSchemaProps = enrichedResult.schema?.properties?.input?.properties || {};
+      const hasPathParamsInSchema = "pathParams" in inputSchemaProps;
+      return {
+        ...enrichedResult,
+        routeTemplate: dynamicRoute.routeTemplate,
+        info: {
+          ...enrichedResult.info,
+          input: { ...enrichedResult.info.input, pathParams: dynamicRoute.pathParams }
+        },
+        ...!hasPathParamsInSchema ? {
+          schema: {
+            ...enrichedResult.schema,
+            properties: {
+              ...enrichedResult.schema?.properties,
+              input: {
+                ...enrichedResult.schema?.properties?.input,
+                properties: {
+                  ...inputSchemaProps,
+                  pathParams: { type: "object" }
+                }
+              }
+            }
+          }
+        } : {}
+      };
+    }
+    return enrichedResult;
   }
 };
 
@@ -460,6 +565,23 @@ function extractResourceMetadataV1(paymentRequirements) {
 }
 
 // src/bazaar/facilitator.ts
+var ROUTE_TEMPLATE_REGEX = /^\/[a-zA-Z0-9_/:.\-~%]+$/;
+function isValidRouteTemplate(value) {
+  if (!value) return false;
+  if (!ROUTE_TEMPLATE_REGEX.test(value)) return false;
+  let decoded;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return false;
+  }
+  if (decoded.includes("..")) return false;
+  if (decoded.includes("://")) return false;
+  return true;
+}
+function validateRouteTemplate(value) {
+  return isValidRouteTemplate(value) ? value : void 0;
+}
 function validateDiscoveryExtension(extension) {
   try {
     const ajv = new import__.default({ strict: false, allErrors: true });
@@ -485,12 +607,18 @@ function validateDiscoveryExtension(extension) {
 function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = true) {
   let discoveryInfo = null;
   let resourceUrl;
+  let routeTemplate;
   if (paymentPayload.x402Version === 2) {
     resourceUrl = paymentPayload.resource?.url ?? "";
     if (paymentPayload.extensions) {
       const bazaarExtension = paymentPayload.extensions[BAZAAR.key];
       if (bazaarExtension && typeof bazaarExtension === "object") {
         try {
+          const rawExt = bazaarExtension;
+          const rawTemplate = typeof rawExt.routeTemplate === "string" ? rawExt.routeTemplate : void 0;
+          if (isValidRouteTemplate(rawTemplate)) {
+            routeTemplate = rawTemplate;
+          }
           const extension = bazaarExtension;
           if (validate) {
             const result = validateDiscoveryExtension(extension);
@@ -520,7 +648,7 @@ function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = tr
     return null;
   }
   const url = new URL(resourceUrl);
-  const normalizedResourceUrl = `${url.origin}${url.pathname}`;
+  const canonicalUrl = routeTemplate ? `${url.origin}${routeTemplate}` : `${url.origin}${url.pathname}`;
   let description;
   let mimeType;
   if (paymentPayload.x402Version === 2) {
@@ -532,7 +660,7 @@ function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = tr
     mimeType = requirementsV1.mimeType;
   }
   const base = {
-    resourceUrl: normalizedResourceUrl,
+    resourceUrl: canonicalUrl,
     description,
     mimeType,
     x402Version: paymentPayload.x402Version,
@@ -541,7 +669,7 @@ function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = tr
   if (discoveryInfo.input.type === "mcp") {
     return { ...base, toolName: discoveryInfo.input.toolName };
   }
-  return { ...base, method: discoveryInfo.input.method };
+  return { ...base, routeTemplate, method: discoveryInfo.input.method };
 }
 function extractDiscoveryInfoFromExtension(extension, validate = true) {
   if (validate) {
@@ -622,8 +750,10 @@ function withBazaar(client) {
   isDiscoverableV1,
   isMcpExtensionConfig,
   isQueryExtensionConfig,
+  isValidRouteTemplate,
   validateAndExtract,
   validateDiscoveryExtension,
+  validateRouteTemplate,
   withBazaar
 });
 //# sourceMappingURL=index.js.map