@x402/extensions 2.7.0 → 2.8.0

package/dist/cjs/index.js

@@ -124,6 +124,7 @@ __export(src_exports, {
   isQueryExtensionConfig: () => isQueryExtensionConfig,
   isSolanaSigner: () => isSolanaSigner,
   isValidPaymentId: () => isValidPaymentId,
+  isValidRouteTemplate: () => isValidRouteTemplate,
   parseSIWxHeader: () => parseSIWxHeader,
   paymentIdentifierResourceServerExtension: () => paymentIdentifierResourceServerExtension,
   paymentIdentifierSchema: () => paymentIdentifierSchema,
@@ -140,6 +141,7 @@ __export(src_exports, {
   validateErc20ApprovalGasSponsoringInfo: () => validateErc20ApprovalGasSponsoringInfo,
   validatePaymentIdentifier: () => validatePaymentIdentifier,
   validatePaymentIdentifierRequirement: () => validatePaymentIdentifierRequirement,
+  validateRouteTemplate: () => validateRouteTemplate,
   validateSIWxMessage: () => validateSIWxMessage,
   verifyEVMSignature: () => verifyEVMSignature,
   verifyOfferSignatureEIP712: () => verifyOfferSignatureEIP712,
@@ -175,6 +177,8 @@ function createQueryDiscoveryExtension({
   method,
   input = {},
   inputSchema = { properties: {} },
+  pathParams,
+  pathParamsSchema,
   output
 }) {
   return {
@@ -182,7 +186,8 @@ function createQueryDiscoveryExtension({
       input: {
         type: "http",
         ...method ? { method } : {},
-        ...input ? { queryParams: input } : {}
+        ...input ? { queryParams: input } : {},
+        ...pathParams ? { pathParams } : {}
       },
       ...output?.example ? {
         output: {
@@ -211,9 +216,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 ? {
@@ -240,6 +254,8 @@ function createBodyDiscoveryExtension({
   method,
   input = {},
   inputSchema = { properties: {} },
+  pathParams,
+  pathParamsSchema,
   bodyType,
   output
 }) {
@@ -249,7 +265,8 @@ function createBodyDiscoveryExtension({
         type: "http",
         ...method ? { method } : {},
         bodyType,
-        body: input
+        body: input,
+        ...pathParams ? { pathParams } : {}
       },
       ...output?.example ? {
         output: {
@@ -277,9 +294,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 ? {
@@ -400,9 +426,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) => {
@@ -422,7 +496,7 @@ var bazaarResourceServerExtension = {
         enum: [method]
       }
     };
-    return {
+    const enrichedResult = {
       ...extension,
       info: {
         ...extension.info || {},
@@ -446,6 +520,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;
   }
 };
 
@@ -567,6 +672,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 });
@@ -592,12 +714,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);
@@ -627,7 +755,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) {
@@ -639,7 +767,7 @@ function extractDiscoveryInfo(paymentPayload, paymentRequirements, validate = tr
     mimeType = requirementsV1.mimeType;
   }
   const base = {
-    resourceUrl: normalizedResourceUrl,
+    resourceUrl: canonicalUrl,
     description,
     mimeType,
     x402Version: paymentPayload.x402Version,
@@ -648,7 +776,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) {
@@ -1386,7 +1514,7 @@ function createSIWxRequestHook(options) {
       "SIWxStorage nonce tracking requires both hasUsedNonce and recordNonce to be implemented"
     );
   }
-  return async (context) => {
+  return async (context, routeConfig) => {
     const header = context.adapter.getHeader(SIGN_IN_WITH_X) || context.adapter.getHeader(SIGN_IN_WITH_X.toLowerCase());
     if (!header) return;
     try {
@@ -1409,8 +1537,9 @@ function createSIWxRequestHook(options) {
           return;
         }
       }
-      const hasPaid = await storage.hasPaid(context.path, verification.address);
-      if (hasPaid) {
+      const isAuthOnly = Array.isArray(routeConfig?.accepts) && routeConfig.accepts.length === 0;
+      const shouldGrant = isAuthOnly || await storage.hasPaid(context.path, verification.address);
+      if (shouldGrant) {
         if (storage.recordNonce) {
           await storage.recordNonce(payload.nonce);
         }
@@ -2713,6 +2842,7 @@ function validateErc20ApprovalGasSponsoringInfo(info) {
   isQueryExtensionConfig,
   isSolanaSigner,
   isValidPaymentId,
+  isValidRouteTemplate,
   parseSIWxHeader,
   paymentIdentifierResourceServerExtension,
   paymentIdentifierSchema,
@@ -2729,6 +2859,7 @@ function validateErc20ApprovalGasSponsoringInfo(info) {
   validateErc20ApprovalGasSponsoringInfo,
   validatePaymentIdentifier,
   validatePaymentIdentifierRequirement,
+  validateRouteTemplate,
   validateSIWxMessage,
   verifyEVMSignature,
   verifyOfferSignatureEIP712,