@parallel-protocol/x402 0.10.0 → 0.10.1

package/README.md

@@ -40,11 +40,12 @@ Agent                        Merchant (this SDK)           Facilitator
 - The handler only runs after the signature is verified.
 - The on-chain settlement happens after the handler produces a 2xx response — the agent is not charged on errors.
 - The settle is bound to the merchant that verified: `POST /x402/verify` hands the middleware a settle token that `POST /x402/settle` must present. The token stays in memory for the life of the request and never reaches the agent.
-- If settlement fails, the middleware discards the handler's response and returns `402` with `{ error: "PAYMENT_SETTLEMENT_FAILED", reason, message }`: `reason` is the facilitator's code (`INSUFFICIENT_BALANCE`, `AUTHORIZATION_USED`, `PAYMENT_EXPIRED`, ...) or this SDK's (`SETTLE_TIMEOUT`, `FACILITATOR_UNAVAILABLE`, `FACILITATOR_INVALID_RESPONSE`, `AMOUNT_MISMATCH`, `UNKNOWN`), `message` the facilitator's text or this SDK's, and the facilitator's `Retry-After` is copied when it sent one. A settle that timed out or could not reach the facilitator is retried once first, with the same settle token: once the first attempt has finished, the facilitator answers its recorded outcome, and any other answer to the retry tells the agent to check with the merchant.
+- If settlement fails, the middleware discards the handler's response, its headers, cookies and trailers included (for the `cookies()` of Next.js, see [Next.js](#nextjs-app-router)), and returns `402` with `{ error: "PAYMENT_SETTLEMENT_FAILED", reason, message }`: `reason` is the facilitator's code (`INSUFFICIENT_BALANCE`, `AUTHORIZATION_USED`, `PAYMENT_EXPIRED`, ...) or this SDK's (`SETTLE_TIMEOUT`, `FACILITATOR_UNAVAILABLE`, `FACILITATOR_INVALID_RESPONSE`, `AMOUNT_MISMATCH`, `UNKNOWN`), `message` the facilitator's text or this SDK's, and the facilitator's `Retry-After` is copied when it sent one. A settle that timed out or could not reach the facilitator is retried once first, with the same settle token: once the first attempt has finished, the facilitator answers its recorded outcome, and any other answer to the retry tells the agent to check with the merchant.
 - A metered settle must settle the amount the handler asked for: a confirmation for another amount is refused and the response discarded.
 - Handlers are bounded by a 30-second timeout on Express, Hono and Next.js — a slow handler returns `504` and the agent is not charged. (Fastify manages handler execution itself, so no timeout is applied there.) Metered routes get their announced window minus two minutes kept for the settlement and its retry.
+- On paid Express and Fastify routes, the handler does not see the conditional request headers (`If-Match`, `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`): Express, or a plugin such as `@fastify/etag`, would turn the paid response into a `304` or a `412`, which is not settled. A paid request always gets the resource.
 - On paid Fastify routes, writing to `reply.raw` (the SSE/streaming pattern) fails loudly instead of sending: a raw response skips the settlement hooks and would go out unpaid. Streaming is not supported on paid routes.
-- CORS preflight (`OPTIONS`) is always passed through without challenge.
+- CORS preflight (`OPTIONS`) is passed through without challenge, unless its path has `.` or `..` segments. On a paid route the handler still answers it, but only its status code and its `Access-Control-*`, `Vary` and `Allow` headers go out, with the standard reason phrase: no body, no other header, no trailer and no early hints. A handler that answers every method does not serve the paid content. On Next.js the handler does not run, see [Next.js](#nextjs-app-router).
 
 ---
 
@@ -61,8 +62,8 @@ Install your framework separately (all are optional peer dependencies):
 ```bash
 npm install express       # Express 4 or 5
 npm install next          # Next.js 14 or 15
-npm install fastify       # Fastify 4 or 5
-npm install hono          # Hono 4+
+npm install fastify       # Fastify 5.12.7 or a later 5.x
+npm install hono          # Hono 4
 ```
 
 TypeScript consumers should also install `viem` (peer dependency) — the public types use its `Address` type. Node ≥ 18 is required.
@@ -123,6 +124,8 @@ export const GET = withPayment(config, async (req) => {
 });
 ```
 
+On a paid route, a CORS preflight (`OPTIONS`) gets an empty `204` without running the handler, so set the route's CORS headers in the `headers` of `next.config.js`. Next.js adds the cookies set with `cookies()` from `next/headers` to the response the route returns, even to the `402` of a failed settlement. Set the cookies of a paid response on the `NextResponse` the handler returns instead: they leave with it only.
+
 ### Fastify
 
 ```typescript
@@ -149,6 +152,8 @@ app.get("/api/data", async () => {
 });
 ```
 
+On a refusal after the handler, only the cookies already set on the reply before the handler go out. Cookies that a plugin such as `@fastify/cookie` writes from its own `onSend` hook are left out of the `402`, even those set with `reply.setCookie` before the handler.
+
 ### Hono
 
 ```typescript
@@ -207,7 +212,7 @@ interface PaymentMiddlewareConfig {
 | `meter` | `(ctx) => string \| bigint \| undefined` | No | `upto` routes only: reads the amount to charge from the handler's response, see [Reading the amount from the response](#reading-the-amount-from-the-response-meter). |
 | `maxTimeoutSeconds` | `number` | No | Settlement window announced to the payer (default 300). `@parallel-protocol/x402-fetch` signs for it on `upto` routes, and for five minutes on `exact` routes. Metered routes announce how long their handler may take. On an `upto` route it is 3600 (one hour) at most: a larger value raises `X402ConfigError` at construction, and the facilitator refuses an authorization valid for longer with `WINDOW_TOO_LONG`. On metered routes, Express, Hono and Next.js derive the handler timeout from it, minus two minutes kept for the settlement and its retry: a 300 s window leaves the handler 180 s, and a handler always gets at least 30 s. Fastify does not time handlers out, set the server's `connectionTimeout` / `requestTimeout` yourself. |
 
-Route matching uses **longest prefix wins**: `/api/v1/users` will match a `/api/v1` route config before a `/api` one.
+Route matching uses **longest prefix wins**: `/api/v1/users` will match a `/api/v1` route config before a `/api` one. The request path and the route keys are compared once normalized: case, percent-encoding, repeated or trailing slashes, a fragment, `;` path parameters and an absolute-form origin make no difference, so another form of a paid path is charged like the path itself. A key with a trailing slash, such as `/api/`, covers the paths below it as `/api` does. Routers and proxies do not all resolve `.` and `..` segments, so a path that has some and reaches a paid route is refused with a `400` and `INVALID_PATH`. Under an Express mount prefix, such as `app.use("/api", ...)`, a key can be written with the full path or relative to the mount, and the key `/` covers only the mount's root: write `/api` to cover every path below it. A Next.js route handler sees the path without the `basePath`, so write keys without it.
 
 ---
 
@@ -495,7 +500,7 @@ routes: {
 },
 ```
 
-The function gets `{ method, path, url, header(name), body }`. `body` is the request body as the framework parsed it (`undefined` when there is none), so it is available where your framework parses it:
+The function gets `{ method, path, routePath, url, header(name), body }`. `path` is the request path as the framework gives it, and `routePath` the path the route matched, in the form routes are matched on. Under an Express mount, that is the full path when the route key is written with it. To price by path, compare `routePath`, so that another form of the same path, such as `/API/premium`, gets the same price. `body` is the request body as the framework parsed it (`undefined` when there is none), so it is available where your framework parses it:
 
 | Framework | `body` |
 |-----------|--------|
@@ -676,6 +681,7 @@ import {
 
   // Utils
   encodeBase64,
+  normalizeRoutePath,
   parsePrice,
   toEip155Network,
   validateAddress,
@@ -688,8 +694,8 @@ import {
 |-------------|--------|-----------|
 | `@parallel-protocol/x402/express` | `paymentMiddleware(config)` | Express 4/5 |
 | `@parallel-protocol/x402/next` | `withPayment(config, handler)` | Next.js 14/15 |
-| `@parallel-protocol/x402/fastify` | `paymentMiddleware(config)` | Fastify 4/5 |
-| `@parallel-protocol/x402/hono` | `paymentMiddleware(config)` | Hono 4+ |
+| `@parallel-protocol/x402/fastify` | `paymentMiddleware(config)` | Fastify 5 (5.12.7 or later) |
+| `@parallel-protocol/x402/hono` | `paymentMiddleware(config)` | Hono 4 |
 
 Each subpath also exports its adapter class (`ExpressAdapter`, `NextAdapter`, `FastifyAdapter`, `HonoAdapter`) for use with [`createPaymentGate`](#advanced-createpaymentgate).
 
@@ -743,7 +749,9 @@ const result = await gate({
 });
 
 if (result.type === "pass") {
-  // Route not configured for payment, proceed normally
+  // Route not configured for payment, proceed normally.
+  // result.preflight: an OPTIONS on a paid route, send only the handler's
+  // status code and its Access-Control-*, Vary and Allow headers
 } else if (result.type === "error") {
   // Send result.result.status (402, or the status of a price refusal)
   // with result.result.headers and result.result.body
@@ -820,12 +828,13 @@ What the middleware answers on a paid route instead of the handler's response:
 | 402 | `{ error: "INVALID_SETTLE_AMOUNT", message }` | A metered route named an amount the middleware cannot settle, see [Metered routes](#metered-routes-upto) |
 | 504 | `{ error: "HANDLER_TIMEOUT", message }` on Express and Hono, an empty body on Next.js | The handler did not answer within its timeout, and nothing is settled. Next.js also answers this empty 504 when the handler throws |
 | 400, or the status the price function chose | `{ error, message }` | A price function refused the request with `X402PriceRejectedError`, and nothing was invoiced |
+| 400 | `{ error: "INVALID_PATH", message }` | The path has `.` or `..` segments, and reaches a paid route. Nothing was invoiced |
 
 ### Thrown by the SDK
 
 | Error class | When |
 |-------------|------|
-| `X402ConfigError` | Invalid config at construction, the message naming the first field at fault: a bad `payTo`, a facilitator URL that is neither https nor plain http on `localhost`, `127.0.0.1` or `[::1]`, empty `routes`, a `network` of the catalog other than `ethereum`, `base`, `avalanche` or `hyperevm`, a malformed or non-positive `price`, a `meter` on a route that is not `upto`, or an `upto` route with `maxTimeoutSeconds` above 3600, a token other than USDp and the network's USDC paid through Permit2, or a bigint price or an explicit `decimals` while it accepts tokens with different decimals. Then, on a request to a route: an unknown network with no `acceptedTokens`, an accepted token whose decimals are neither in the catalog nor set via `decimals`, a price finer than the token's precision, or a price function that throws, returns something that is not a price, or returns a bigint on an `upto` route that accepts tokens with different decimals |
+| `X402ConfigError` | Invalid config at construction, the message naming the first field at fault: a bad `payTo`, a facilitator URL that is neither https nor plain http on `localhost`, `127.0.0.1` or `[::1]`, empty `routes`, a `network` of the catalog other than `ethereum`, `base`, `avalanche` or `hyperevm`, a malformed or non-positive `price`, two routes that are the same path once normalized with different configs, a `meter` on a route that is not `upto`, or an `upto` route with `maxTimeoutSeconds` above 3600, a token other than USDp and the network's USDC paid through Permit2, or a bigint price or an explicit `decimals` while it accepts tokens with different decimals. Then, on a request to a route: an unknown network with no `acceptedTokens`, an accepted token whose decimals are neither in the catalog nor set via `decimals`, a price finer than the token's precision, or a price function that throws, returns something that is not a price, or returns a bigint on an `upto` route that accepts tokens with different decimals |
 | `X402RuntimeError` | Runtime failure; `.code` is one of the SDK codes below, or a facilitator error code propagated verbatim (see next table) |
 | `X402PriceRejectedError` | Thrown by a price function to refuse a request before anything is invoiced; the client gets `.status` (400 by default) with `{ error: .code, message }`. `isPriceRejection(err)` recognises one by shape. |
 
@@ -948,6 +957,7 @@ import {
 | `validateAddress` | `(address: string) => address is Address` | Check 0x + 40-hex-char format |
 | `toEip155Network` | `(network: string) => string` | `"base"` → `"eip155:8453"` |
 | `encodeBase64` | `(obj: unknown) => string` | `JSON.stringify` → base64 |
+| `normalizeRoutePath` | `(path: string) => string` | The form routes are matched on: `normalizeRoutePath("/API//Data/")` is `"/api/data"` |
 | `getDefaultAcceptedTokens` | `(network: string) => [Address, Address, Address] \| undefined` | `[USDp, USDC, sUSDp]` for known networks |
 
 ---

package/dist/{chunk-KZZY5LS6.cjs → chunk-4CEMNRCZ.cjs}

@@ -5,6 +5,8 @@ var X402_ERROR_CODES = {
   FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
   FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
   INVALID_PAYMENT: "INVALID_PAYMENT",
+  /** A path with `.` or `..` segments on a paid route, refused with 400. */
+  INVALID_PATH: "INVALID_PATH",
   /** The facilitator did not answer a settle within the client's timeout: the payment may still settle. */
   SETTLE_TIMEOUT: "SETTLE_TIMEOUT"
 };

package/dist/{chunk-MYCUOJ3H.cjs → chunk-AYMDIX7A.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkKZZY5LS6_cjs = require('./chunk-KZZY5LS6.cjs');
+var chunk4CEMNRCZ_cjs = require('./chunk-4CEMNRCZ.cjs');
 var chains = require('@parallel-protocol/chains');
 var paymentCore = require('@parallel-protocol/payment-core');
 var zod = require('zod');
@@ -116,18 +116,144 @@ function encodeBase64(obj) {
 function decodeBase64(str) {
   return JSON.parse(Buffer.from(str, "base64").toString("utf8"));
 }
-function matchRoute(path, routes) {
-  if (routes[path]) return routes[path];
+var CONDITIONAL_HEADERS = [
+  "if-match",
+  "if-none-match",
+  "if-modified-since",
+  "if-unmodified-since"
+];
+function dropConditionalHeaders(headers) {
+  for (const name of CONDITIONAL_HEADERS) delete headers[name];
+}
+var UTF8 = new TextDecoder();
+var DECODE_ROUNDS = 8;
+function decodePercent(path) {
+  try {
+    return decodeURIComponent(path);
+  } catch {
+    return path.replace(
+      /(?:%[\da-f]{2})+/gi,
+      (run) => UTF8.decode(
+        Uint8Array.from(
+          run.slice(1).split("%"),
+          (hex) => Number.parseInt(hex, 16)
+        )
+      )
+    );
+  }
+}
+function hasLongMarkRun(segment) {
+  for (const [run] of segment.matchAll(/\p{M}+/gu))
+    if (run.length > 8) return true;
+  return false;
+}
+function foldCase(segment) {
+  const composed = hasLongMarkRun(segment) ? segment : segment.normalize("NFC");
+  return composed.toLowerCase().toUpperCase().toLowerCase();
+}
+function pathSegments(path) {
+  let decoded = path;
+  for (let round = 0; round < DECODE_ROUNDS && decoded.includes("%"); round++) {
+    const next = decodePercent(decoded);
+    if (next === decoded) break;
+    decoded = next;
+  }
+  const target = decoded.replaceAll("\\", "/").replace(/^[a-z][\d+.a-z-]*:\/\/[^/]*/i, "").split(/[?#]/, 1)[0] ?? "";
+  return target.split("/").map((segment) => foldCase(segment).split(";", 1)[0] ?? "").filter((segment) => segment !== "");
+}
+function resolveDots(segments) {
+  const resolved = [];
+  for (const segment of segments) {
+    if (segment === "..") resolved.pop();
+    else if (segment !== ".") resolved.push(segment);
+  }
+  return resolved;
+}
+function normalizeRoutePath(path) {
+  return `/${resolveDots(pathSegments(path)).join("/")}`;
+}
+function routeTable(routes) {
+  return Object.entries(routes).map(([key, route]) => [
+    normalizeRoutePath(key),
+    route
+  ]);
+}
+function longestMatch(target, table) {
   let bestMatch;
   let bestLength = 0;
-  for (const [pattern, config] of Object.entries(routes)) {
-    if (path.startsWith(`${pattern}/`) && pattern.length > bestLength) {
-      bestMatch = config;
-      bestLength = pattern.length;
+  for (const [key, route] of table) {
+    if (key === target) return route;
+    if (target.startsWith(`${key}/`) && key.length > bestLength) {
+      bestMatch = route;
+      bestLength = key.length;
     }
   }
   return bestMatch;
 }
+function findRoute(path, table) {
+  const segments = pathSegments(path);
+  const dotSegments = segments.some(
+    (segment) => segment === "." || segment === ".."
+  );
+  const routePath = `/${resolveDots(segments).join("/")}`;
+  const route = longestMatch(routePath, table) ?? (dotSegments ? longestMatch(`/${segments.join("/")}`, table) : void 0);
+  return { route, dotSegments, routePath };
+}
+function isPreflightHeader(name) {
+  return /^(?:access-control-|vary$|allow$)/i.test(String(name));
+}
+function preflightHeaders(headers) {
+  if (Array.isArray(headers)) {
+    if (Array.isArray(headers[0]))
+      return headers.filter((pair) => isPreflightHeader(pair[0]));
+    return headers.flatMap(
+      (item, i) => i % 2 === 0 && isPreflightHeader(item) ? [item, headers[i + 1]] : []
+    );
+  }
+  if (headers !== null && typeof headers === "object")
+    return Object.fromEntries(
+      Object.entries(headers).filter(([name]) => isPreflightHeader(name))
+    );
+  return headers;
+}
+function answerAsPreflight(res) {
+  const writeHead = res.writeHead.bind(res);
+  const end = res.end.bind(res);
+  const callbackOf = (args) => args.find((arg) => typeof arg === "function");
+  const dropOtherHeaders = () => {
+    for (const name of res.getHeaderNames())
+      if (!isPreflightHeader(name)) res.removeHeader(name);
+  };
+  res.writeHead = ((statusCode, ...rest) => {
+    dropOtherHeaders();
+    res.statusMessage = "";
+    const headers = rest.find((arg) => typeof arg !== "string");
+    return headers === void 0 ? writeHead(statusCode) : writeHead(statusCode, preflightHeaders(headers));
+  });
+  res.write = ((...args) => {
+    const done = callbackOf(args);
+    if (done) queueMicrotask(done);
+    return true;
+  });
+  res.end = ((...args) => {
+    if (!res.headersSent) dropOtherHeaders();
+    const done = callbackOf(args);
+    return done ? end(done) : end();
+  });
+  res.addTrailers = () => {
+  };
+  res.writeEarlyHints = ((_hints, done) => {
+    if (done) queueMicrotask(done);
+  });
+}
+function preflightInit(res) {
+  res.body?.cancel().catch(() => {
+  });
+  const headers = new Headers();
+  for (const [name, value] of res.headers)
+    if (isPreflightHeader(name)) headers.append(name, value);
+  return { status: res.status, headers };
+}
 function permit2Extra(network, asset) {
   const domain = USDC_EIP712_DOMAIN[network];
   const escrow = chains.getUptoEscrowAddress(network);
@@ -298,9 +424,31 @@ var routeConfigSchema = zod.z.object({
   (route) => route.scheme !== "upto" || !hasMixedDecimals(route.network, route.acceptedTokens) || typeof route.price !== "bigint" && route.decimals === void 0,
   'An upto route that accepts tokens with different decimals needs a price like "0.01", not a bigint or an explicit decimals'
 );
+function sameValue(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+  const entries = Object.entries(a);
+  return Array.isArray(a) === Array.isArray(b) && entries.length === Object.keys(b).length && entries.every(
+    ([key, value]) => sameValue(value, b[key])
+  );
+}
+function consistentRoutePaths(routes, ctx) {
+  const keyByPath = /* @__PURE__ */ new Map();
+  for (const [key, route] of Object.entries(routes)) {
+    const path = normalizeRoutePath(key);
+    const other = keyByPath.get(path);
+    if (other === void 0) keyByPath.set(path, key);
+    else if (!sameValue(routes[other], route))
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: `Same path as "${other}" once normalized, with another config: keep one of the two routes`
+      });
+  }
+}
 var paymentMiddlewareConfigSchema = zod.z.object({
   facilitator: facilitatorConfigSchema,
-  routes: zod.z.record(zod.z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required")
+  routes: zod.z.record(zod.z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required").superRefine(consistentRoutePaths)
 });
 var facilitatorResponseSchema = zod.z.discriminatedUnion("success", [
   zod.z.object({
@@ -371,7 +519,7 @@ function throwIfRedirect(response) {
   if (!redirected) return;
   response.body?.cancel().catch(() => {
   });
-  throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
+  throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
     status: response.status
   });
 }
@@ -379,7 +527,7 @@ function decodePaymentHeader(paymentHeader, network) {
   try {
     return toFacilitatorPayload(decodeBase64(paymentHeader), network);
   } catch {
-    throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.INVALID_PAYMENT);
+    throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.INVALID_PAYMENT);
   }
 }
 function payerOf(paymentPayload) {
@@ -394,7 +542,7 @@ var FacilitatorClient = class {
   constructor(config) {
     const url = facilitatorUrlSchema.safeParse(config.url);
     if (!url.success) {
-      throw new chunkKZZY5LS6_cjs.X402ConfigError(
+      throw new chunk4CEMNRCZ_cjs.X402ConfigError(
         url.error.issues[0]?.message ?? "Invalid facilitator URL",
         url.error
       );
@@ -419,8 +567,8 @@ var FacilitatorClient = class {
       throwIfRedirect(response);
       if (!response.ok) {
         const body = await readErrorBody(response);
-        throw new chunkKZZY5LS6_cjs.X402RuntimeError(
-          body.error ?? chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE,
+        throw new chunk4CEMNRCZ_cjs.X402RuntimeError(
+          body.error ?? chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE,
           {
             detail: body.message,
             status: response.status,
@@ -430,14 +578,14 @@ var FacilitatorClient = class {
       }
       json = await response.json();
     } catch (e) {
-      if (e instanceof chunkKZZY5LS6_cjs.X402RuntimeError) throw e;
-      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      if (e instanceof chunk4CEMNRCZ_cjs.X402RuntimeError) throw e;
+      throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
     }
     try {
       const { settleToken } = verifyResponseSchema.parse(json);
       return { settleToken };
     } catch {
-      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+      throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
   async settle(paymentHeader, paymentRequirements, options) {
@@ -469,7 +617,7 @@ var FacilitatorClient = class {
       if (!response.ok) {
         const body = await readErrorBody(response);
         if (body.error === void 0) {
-          throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
+          throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
             status: response.status
           });
         }
@@ -486,11 +634,11 @@ var FacilitatorClient = class {
       }
       json = await response.json();
     } catch (e) {
-      if (e instanceof chunkKZZY5LS6_cjs.X402RuntimeError) throw e;
+      if (e instanceof chunk4CEMNRCZ_cjs.X402RuntimeError) throw e;
       if (e instanceof Error && e.name === "TimeoutError") {
-        throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT);
+        throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT);
       }
-      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
     }
     try {
       const parsed = settleResponseSchema.parse(json);
@@ -523,7 +671,7 @@ var FacilitatorClient = class {
         error: { code: parsed.error, message: parsed.message }
       };
     } catch {
-      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+      throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
   /**
@@ -543,17 +691,17 @@ var FacilitatorClient = class {
       });
       throwIfRedirect(response);
       if (!response.ok) {
-        throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+        throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
       }
       json = await response.json();
     } catch (e) {
-      if (e instanceof chunkKZZY5LS6_cjs.X402RuntimeError) throw e;
-      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      if (e instanceof chunk4CEMNRCZ_cjs.X402RuntimeError) throw e;
+      throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
     }
     try {
       return facilitatorResponseSchema.parse(json);
     } catch {
-      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+      throw new chunk4CEMNRCZ_cjs.X402RuntimeError(chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
   buildHeaders() {
@@ -585,10 +733,11 @@ async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
 
 // src/middleware.ts
 var PRICE_FORMAT = /^\d+(?:\.\d+)?$/;
-async function requestContext(adapter) {
+async function requestContext(adapter, routePath) {
   return {
     method: adapter.getMethod(),
     path: adapter.getPath(),
+    routePath,
     url: adapter.getUrl(),
     header: (name) => adapter.getHeader(name),
     body: adapter.getBody ? await adapter.getBody() : void 0
@@ -596,27 +745,27 @@ async function requestContext(adapter) {
 }
 async function resolvePrice(config, ctx, tokens) {
   if (typeof config.price !== "function") return config.price;
-  if (!ctx) throw new chunkKZZY5LS6_cjs.X402ConfigError("A price function needs the request");
+  if (!ctx) throw new chunk4CEMNRCZ_cjs.X402ConfigError("A price function needs the request");
   let price;
   try {
     price = await config.price(ctx);
   } catch (cause) {
-    if (chunkKZZY5LS6_cjs.isPriceRejection(cause)) throw cause;
-    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+    if (chunk4CEMNRCZ_cjs.isPriceRejection(cause)) throw cause;
+    throw new chunk4CEMNRCZ_cjs.X402ConfigError(
       `The price function of route "${config.network}${ctx.path}" threw`,
       cause
     );
   }
   const valid = typeof price === "bigint" ? price > 0n : typeof price === "string" && PRICE_FORMAT.test(price) && Number(price) > 0;
   if (!valid) {
-    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+    throw new chunk4CEMNRCZ_cjs.X402ConfigError(
       `The price function of route "${config.network}${ctx.path}" returned ${JSON.stringify(
         typeof price === "bigint" ? price.toString() : price
       )} \u2014 expected a positive amount like "0.01" or a bigint`
     );
   }
   if (typeof price === "bigint" && config.scheme === "upto" && hasMixedDecimals(config.network, tokens)) {
-    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+    throw new chunk4CEMNRCZ_cjs.X402ConfigError(
       `The price function of route "${config.network}${ctx.path}" returned a bigint, but the route accepts tokens with different decimals: return a price like "0.01"`
     );
   }
@@ -675,7 +824,7 @@ function refusingBigints(meter) {
   return async (ctx) => {
     const amount = await meter(ctx);
     if (typeof amount === "bigint") {
-      throw new chunkKZZY5LS6_cjs.X402ConfigError(
+      throw new chunk4CEMNRCZ_cjs.X402ConfigError(
         'The meter returned a bigint, but the route accepts tokens with different decimals: return an amount like "0.75"'
       );
     }
@@ -686,7 +835,7 @@ var AMOUNT_FORMAT = /^\d+(?:\.\d+)?$/;
 async function resolveCharge(verified, settleHeader, response) {
   if (verified.meter) {
     if (!verified.request) {
-      throw new chunkKZZY5LS6_cjs.X402ConfigError(
+      throw new chunk4CEMNRCZ_cjs.X402ConfigError(
         "A metered payment carries a meter but no request context"
       );
     }
@@ -737,14 +886,14 @@ function resolveAcceptedTokens(config) {
   }
   const defaults = config.scheme === "upto" ? getMeteredAcceptedTokens(config.network) : getDefaultAcceptedTokens(config.network);
   if (defaults) return defaults;
-  throw new chunkKZZY5LS6_cjs.X402ConfigError(
+  throw new chunk4CEMNRCZ_cjs.X402ConfigError(
     `acceptedTokens is required for network "${config.network}" \u2014 no defaults available for this chain`
   );
 }
 function resolveDecimals(config, asset) {
   const decimals = config.decimals ?? getTokenDecimals(config.network, asset);
   if (decimals === void 0) {
-    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+    throw new chunk4CEMNRCZ_cjs.X402ConfigError(
       `Unknown decimals for token ${asset} on "${config.network}" \u2014 add it to the @parallel-protocol/chains catalog or set the route's \`decimals\` explicitly`
     );
   }
@@ -753,7 +902,7 @@ function resolveDecimals(config, asset) {
 function priceInUnits(price, decimals, asset) {
   const units = parsePrice(price, decimals);
   if (units === 0n) {
-    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+    throw new chunk4CEMNRCZ_cjs.X402ConfigError(
       `Price ${typeof price === "bigint" ? price.toString() : `"${price}"`} is below the precision of token ${asset} (${decimals} decimals)`
     );
   }
@@ -861,7 +1010,7 @@ function paymentRequiredResponse(url, config, resolvedTokens, price, refusal) {
     price
   );
   if (refusal) {
-    paymentRequired.error = shapedCode(refusal.code) ?? chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE;
+    paymentRequired.error = shapedCode(refusal.code) ?? chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE;
     const message = boundedMessage(refusal.detail);
     if (message) paymentRequired.message = message;
   }
@@ -878,24 +1027,39 @@ function createPaymentGate(config) {
   if (!checked.success) {
     const issue = checked.error.issues[0];
     const where = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
-    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+    throw new chunk4CEMNRCZ_cjs.X402ConfigError(
       `Invalid paymentMiddleware config${where}: ${issue?.message ?? "check your routes, facilitator URL and payTo addresses"}`,
       checked.error
     );
   }
   const client = new FacilitatorClient(config.facilitator);
+  const routes = routeTable(config.routes);
   return async (adapter) => {
-    if (adapter.getMethod().toUpperCase() === "OPTIONS")
-      return { type: "pass" };
-    const routeConfig = matchRoute(adapter.getPath(), config.routes);
+    const path = adapter.getPath();
+    const fullPath = adapter.getFullPath?.();
+    let match = findRoute(path, routes);
+    if (!match.route && fullPath !== void 0 && fullPath !== path)
+      match = findRoute(fullPath, routes);
+    const { route: routeConfig, dotSegments, routePath } = match;
     if (!routeConfig) return { type: "pass" };
+    if (dotSegments) {
+      return {
+        type: "error",
+        result: jsonResult(400, {
+          error: chunk4CEMNRCZ_cjs.X402_ERROR_CODES.INVALID_PATH,
+          message: "A paid route is not served on a path with . or .. segments: send the path resolved"
+        })
+      };
+    }
+    if (adapter.getMethod().toUpperCase() === "OPTIONS")
+      return { type: "pass", preflight: true };
     const resolvedTokens = resolveAcceptedTokens(routeConfig);
-    let request = typeof routeConfig.price === "function" ? await requestContext(adapter) : void 0;
+    let request = typeof routeConfig.price === "function" ? await requestContext(adapter, routePath) : void 0;
     let price;
     try {
       price = await resolvePrice(routeConfig, request, resolvedTokens);
     } catch (err) {
-      if (!chunkKZZY5LS6_cjs.isPriceRejection(err)) throw err;
+      if (!chunk4CEMNRCZ_cjs.isPriceRejection(err)) throw err;
       const status = Number.isInteger(err.status) && err.status >= 400 && err.status <= 599 ? err.status : 400;
       return {
         type: "error",
@@ -932,7 +1096,7 @@ function createPaymentGate(config) {
     try {
       ({ settleToken } = await client.verify(paymentHeader, requirements));
     } catch (e) {
-      const refusal = e instanceof chunkKZZY5LS6_cjs.X402RuntimeError ? { code: e.code, detail: e.detail, retryAfter: e.retryAfter } : { code: chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE };
+      const refusal = e instanceof chunk4CEMNRCZ_cjs.X402RuntimeError ? { code: e.code, detail: e.detail, retryAfter: e.retryAfter } : { code: chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE };
       return {
         type: "error",
         result: paymentRequiredResponse(
@@ -945,7 +1109,7 @@ function createPaymentGate(config) {
       };
     }
     const meter = routeConfig.meter && hasMixedDecimals(routeConfig.network, resolvedTokens) ? refusingBigints(routeConfig.meter) : routeConfig.meter;
-    if (meter && !request) request = await requestContext(adapter);
+    if (meter && !request) request = await requestContext(adapter, routePath);
     return {
       type: "verified",
       scheme: routeConfig.scheme ?? "exact",
@@ -961,9 +1125,9 @@ var DEFAULT_SETTLEMENT_MESSAGE = "The payment could not be settled.";
 var MERCHANT_SETTLEMENT_MESSAGE = "The merchant could not complete the settlement of this payment. The payment was not taken: do not sign another payment for this request before checking with the merchant.";
 var UNAVAILABLE_SETTLEMENT_MESSAGE = "The facilitator could not settle the payment for now. It may still settle until its authorization expires, or an earlier attempt may already have settled it: do not sign another payment for this request before checking with the merchant.";
 var AGENT_MESSAGES = {
-  [chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT]: "The facilitator did not confirm the settlement in time. The payment may still settle: do not sign another payment for this request before checking with the merchant.",
-  [chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE]: "The facilitator could not be reached to settle the payment. It may still have settled: do not sign another payment for this request before checking with the merchant.",
-  [chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE]: "The facilitator answered the settlement with an unexpected response. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
+  [chunk4CEMNRCZ_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT]: "The facilitator did not confirm the settlement in time. The payment may still settle: do not sign another payment for this request before checking with the merchant.",
+  [chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE]: "The facilitator could not be reached to settle the payment. It may still have settled: do not sign another payment for this request before checking with the merchant.",
+  [chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE]: "The facilitator answered the settlement with an unexpected response. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
   SETTLE_IN_PROGRESS: "The facilitator is still settling this payment. Do not sign another payment for this request before checking with the merchant.",
   RECEIPT_UNAVAILABLE: "The facilitator sent the transaction but could not read its confirmation. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
   SETTLE_TOKEN_INVALID: MERCHANT_SETTLEMENT_MESSAGE,
@@ -988,8 +1152,8 @@ function settlementFailure(code, failure) {
   };
 }
 var RETRY_ONCE_CODES = /* @__PURE__ */ new Set([
-  chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT,
-  chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE
+  chunk4CEMNRCZ_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT,
+  chunk4CEMNRCZ_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE
 ]);
 async function settleVerified(verified, options) {
   let response;
@@ -997,7 +1161,7 @@ async function settleVerified(verified, options) {
     try {
       response = await verified.settle(options);
     } catch (e) {
-      const code = e instanceof chunkKZZY5LS6_cjs.X402RuntimeError ? e.code : "UNKNOWN";
+      const code = e instanceof chunk4CEMNRCZ_cjs.X402RuntimeError ? e.code : "UNKNOWN";
       if (attempt > 0 || !RETRY_ONCE_CODES.has(code)) {
         return settlementFailure(code);
       }
@@ -1027,7 +1191,8 @@ function createPaymentMiddleware(config) {
   const gate = createPaymentGate(config);
   return async (adapter) => {
     const gateResult = await gate(adapter);
-    if (gateResult.type === "pass") return { pass: true };
+    if (gateResult.type === "pass")
+      return gateResult.preflight ? { pass: true, preflight: true } : { pass: true };
     if (gateResult.type === "error") return gateResult.result;
     let handlerResult;
     try {
@@ -1083,19 +1248,24 @@ exports.FacilitatorClient = FacilitatorClient;
 exports.HANDLER_TIMEOUT = HANDLER_TIMEOUT;
 exports.PARALLEL_TOKENS = PARALLEL_TOKENS;
 exports.SETTLE_AMOUNT_HEADER = SETTLE_AMOUNT_HEADER;
+exports.answerAsPreflight = answerAsPreflight;
 exports.createPaymentGate = createPaymentGate;
 exports.createPaymentMiddleware = createPaymentMiddleware;
+exports.dropConditionalHeaders = dropConditionalHeaders;
 exports.encodeBase64 = encodeBase64;
+exports.findRoute = findRoute;
 exports.getDefaultAcceptedTokens = getDefaultAcceptedTokens;
 exports.invalidSettleAmountResponse = invalidSettleAmountResponse;
 exports.isJsonContentType = isJsonContentType;
 exports.jsonFromResponse = jsonFromResponse;
-exports.matchRoute = matchRoute;
+exports.normalizeRoutePath = normalizeRoutePath;
 exports.parseJsonBody = parseJsonBody;
 exports.parsePrice = parsePrice;
+exports.preflightInit = preflightInit;
 exports.raceTimeout = raceTimeout;
 exports.resolveCharge = resolveCharge;
 exports.resolveSettleAmount = resolveSettleAmount;
+exports.routeTable = routeTable;
 exports.settleVerified = settleVerified;
 exports.settlementFailureResponse = settlementFailureResponse;
 exports.toEip155Network = toEip155Network;