@parallel-protocol/mpp 0.2.1 → 0.2.2

package/README.md

@@ -40,9 +40,11 @@ Agent                        Merchant (this SDK)           Facilitator
 **Key properties:**
 - The handler only runs after the credential is verified.
 - Settlement (on-chain) happens after a 2xx handler response — the agent is never charged on errors.
-- If settlement fails, the middleware returns `402` and discards the handler response.
+- If settlement fails, the middleware returns `402` and discards the handler response, its headers, cookies and trailers included. For the `cookies()` of Next.js, see [Next.js](#nextjs-app-router).
 - If the handler does not finish within 30 seconds, the Express, Hono and Next.js adapters answer `504` and nothing is settled. Next.js also answers an empty `504` when the handler throws.
-- CORS preflight (`OPTIONS`) is always passed through without challenge.
+- 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 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).
 - The `402` challenge body also includes the `challenge` object as JSON for agents that prefer parsing the body over parsing the header.
 
 ---
@@ -62,7 +64,7 @@ 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 fastify       # Fastify 5.12.7 or a later 5.x
 npm install hono          # Hono 4
 ```
 
@@ -153,6 +155,8 @@ export const GET = withPayment(
 );
 ```
 
+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
@@ -183,6 +187,8 @@ app.get("/api/data", async () => ({ data: "protected content" }));
 
 `paymentMiddleware` returns a Fastify plugin that adds `onRequest` and `onSend` hooks. Fastify keeps a plugin's hooks inside the plugin, so wrap it with [`fastify-plugin`](https://www.npmjs.com/package/fastify-plugin) (`npm install fastify-plugin`) as above. The hooks then also apply to routes declared outside it, like `/api/data` here.
 
+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.
+
 ---
 
 ## Configuration
@@ -217,7 +223,7 @@ interface MppMiddlewareConfig {
 | `description` | `string` | No | Human-readable description included in the challenge. |
 | `realm` | `string` | No | Optional realm identifier in the `WWW-Authenticate` header. |
 
-Route matching uses **longest prefix wins**, on whole path segments: `/api/v1/data` matches `/api/v1` before `/api`, and `/api/database` does not match `/api/data`.
+Route matching uses **longest prefix wins**, on whole path segments: `/api/v1/data` matches `/api/v1` before `/api`, and `/api/database` does not match `/api/data`. 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.
 
 > **Note:** Unlike x402's `acceptedTokens` list, MPP charges a **single currency per route**. To accept multiple tokens, declare multiple routes.
 
@@ -400,7 +406,7 @@ import {
 |-------------|--------|-----------|
 | `@parallel-protocol/mpp/express` | `paymentMiddleware(config)`, `ExpressAdapter` | Express 4/5 |
 | `@parallel-protocol/mpp/next` | `withPayment(config, handler)`, `NextAdapter` | Next.js 14/15 |
-| `@parallel-protocol/mpp/fastify` | `paymentMiddleware(config)` (a plugin, see [Fastify](#fastify)), `FastifyAdapter` | Fastify 4/5 |
+| `@parallel-protocol/mpp/fastify` | `paymentMiddleware(config)` (a plugin, see [Fastify](#fastify)), `FastifyAdapter` | Fastify 5 (5.12.7 or later) |
 | `@parallel-protocol/mpp/hono` | `paymentMiddleware(config)`, `HonoAdapter` | Hono 4 |
 
 ---
@@ -422,7 +428,9 @@ const result = await gate({
 });
 
 if (result.type === "pass") {
-  // Route not configured, or OPTIONS — proceed normally
+  // Route not configured, or OPTIONS: 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") {
   // 402 challenge: result.result.status / .headers / .body
 } else {
@@ -512,7 +520,7 @@ Both methods use a 10-second timeout. `verify` throws `MppRuntimeError` on any f
 
 | Error class | When |
 |-------------|------|
-| `MppConfigError` | Invalid config at startup, when the middleware is created: for example no routes, a bad `price`, `payTo` or `currency`, a `network` other than `ethereum`, `base`, `avalanche` or `hyperevm`, or a facilitator URL that does not parse |
+| `MppConfigError` | Invalid config at startup, when the middleware is created, the message naming the first field at fault: for example no routes, two routes that are the same path once normalized with different configs, a bad `price`, `payTo` or `currency`, a `network` other than `ethereum`, `base`, `avalanche` or `hyperevm`, or a facilitator URL that does not parse |
 | `MppRuntimeError` | Thrown by `MppFacilitatorClient`. `.code` is one of the SDK codes below, or the facilitator's own code |
 
 | `MPP_ERROR_CODES` | Meaning |
@@ -521,6 +529,7 @@ Both methods use a 10-second timeout. `verify` throws `MppRuntimeError` on any f
 | `FACILITATOR_INVALID_RESPONSE` | The facilitator answered 2xx with something other than `{ "valid": true }` at verify, or other than a receipt at settle |
 | `METHOD_MISMATCH` | The credential's `challenge.method` is not the route's `method`. The middleware returns it in the 402 body and does not throw it |
 | `INVALID_CREDENTIAL` | Not emitted. A credential that cannot be read gets a challenge without `error` |
+| `INVALID_PATH` | The path has `.` or `..` segments and reaches a paid route. The middleware answers it with a `400` and `{ error, message }`, before any challenge, and does not throw it |
 
 ### Propagated from the facilitator
 
@@ -573,7 +582,7 @@ import { chainIdFromSlug, matchRoute, parsePrice } from "@parallel-protocol/mpp"
 |----------|-----------|-------------|
 | `parsePrice` | `(price: string \| bigint, decimals?: number) => bigint` | Parse `"0.10"` → `100000n` (6 decimals by default) |
 | `chainIdFromSlug` | `(network: string) => number \| undefined` | `"base"` → `8453`, `undefined` for unknown chains |
-| `matchRoute` | `<T>(path: string, routes: Record<string, T>) => T \| undefined` | Longest-prefix route matching |
+| `matchRoute` | `<T>(path: string, routes: Record<string, T>) => T \| undefined` | Longest-prefix route matching, on the normalized path, see [Route matching](#mpprouteconfig) |
 
 ---
 

package/dist/{chunk-MEDPOLT4.cjs → chunk-76KPBYGA.cjs}

@@ -9,6 +9,8 @@ var MPP_ERROR_CODES = {
   FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
   FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
   INVALID_CREDENTIAL: "INVALID_CREDENTIAL",
+  /** A path with `.` or `..` segments on a paid route, refused with 400. */
+  INVALID_PATH: "INVALID_PATH",
   METHOD_MISMATCH: "METHOD_MISMATCH"
 };
 var MppConfigError = class extends Error {
@@ -54,18 +56,147 @@ var SETTLE_FAILURE_BODY = {
   error: "PAYMENT_SETTLEMENT_FAILED",
   message: "Payment could not be confirmed after multiple attempts. Please retry."
 };
-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 matchRoute(path, routes) {
+  return findRoute(path, routeTable(routes)).route;
+}
+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 };
+}
 var DEFAULT_TIMEOUT_SECONDS = 300;
 function challengeId() {
   return globalThis.crypto.randomUUID();
@@ -226,9 +357,31 @@ var routeConfigSchema = zod.z.object({
   description: zod.z.string().optional(),
   realm: zod.z.string().optional()
 });
+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 mppMiddlewareConfigSchema = 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)
 });
 
 // src/middleware.ts
@@ -248,15 +401,17 @@ function challengeResponse(route, request, error) {
   };
 }
 function createMppPaymentGate(config) {
-  try {
-    mppMiddlewareConfigSchema.parse(config);
-  } catch (cause) {
+  const checked = mppMiddlewareConfigSchema.safeParse(config);
+  if (!checked.success) {
+    const issue = checked.error.issues[0];
+    const where = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
     throw new MppConfigError(
-      "Invalid MPP middleware config \u2014 check your routes, facilitator URL, payTo and currency addresses",
-      cause
+      `Invalid MPP middleware config${where}: ${issue?.message ?? "check your routes, facilitator URL, payTo and currency addresses"}`,
+      checked.error
     );
   }
   const client = new MppFacilitatorClient(config.facilitator);
+  const routes = routeTable(config.routes);
   const requestByRoute = new Map(
     Object.values(config.routes).map((route) => [
       route,
@@ -264,10 +419,27 @@ function createMppPaymentGate(config) {
     ])
   );
   return async (adapter) => {
-    if (adapter.getMethod().toUpperCase() === "OPTIONS")
-      return { type: "pass" };
-    const route = matchRoute(adapter.getPath(), config.routes);
+    const path = adapter.getPath();
+    const fullPath = adapter.getFullPath?.();
+    let { route, dotSegments } = findRoute(path, routes);
+    if (!route && fullPath !== void 0 && fullPath !== path)
+      ({ route, dotSegments } = findRoute(fullPath, routes));
     if (!route) return { type: "pass" };
+    if (dotSegments) {
+      return {
+        type: "error",
+        result: {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+          body: {
+            error: MPP_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 request = requestByRoute.get(route);
     const credential = parseAuthorizationHeader(
       adapter.getHeader("authorization")
@@ -304,7 +476,8 @@ function createMppPaymentMiddleware(config) {
   const gate = createMppPaymentGate(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 {
@@ -348,12 +521,15 @@ exports.MppConfigError = MppConfigError;
 exports.MppFacilitatorClient = MppFacilitatorClient;
 exports.MppRuntimeError = MppRuntimeError;
 exports.SETTLE_FAILURE_BODY = SETTLE_FAILURE_BODY;
+exports.answerAsPreflight = answerAsPreflight;
 exports.buildChallenge = buildChallenge;
 exports.chainIdFromSlug = chainIdFromSlug;
 exports.createMppPaymentGate = createMppPaymentGate;
 exports.createMppPaymentMiddleware = createMppPaymentMiddleware;
+exports.dropConditionalHeaders = dropConditionalHeaders;
 exports.isSuccessStatus = isSuccessStatus;
 exports.matchRoute = matchRoute;
 exports.parseAuthorizationHeader = parseAuthorizationHeader;
 exports.parsePrice = parsePrice;
+exports.preflightInit = preflightInit;
 exports.serializeChallenge = serializeChallenge;

package/dist/{chunk-CQ62EEHN.js → chunk-BYNIZG5S.js}

@@ -7,6 +7,8 @@ var MPP_ERROR_CODES = {
   FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
   FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
   INVALID_CREDENTIAL: "INVALID_CREDENTIAL",
+  /** A path with `.` or `..` segments on a paid route, refused with 400. */
+  INVALID_PATH: "INVALID_PATH",
   METHOD_MISMATCH: "METHOD_MISMATCH"
 };
 var MppConfigError = class extends Error {
@@ -52,18 +54,147 @@ var SETTLE_FAILURE_BODY = {
   error: "PAYMENT_SETTLEMENT_FAILED",
   message: "Payment could not be confirmed after multiple attempts. Please retry."
 };
-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 matchRoute(path, routes) {
+  return findRoute(path, routeTable(routes)).route;
+}
+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 };
+}
 var DEFAULT_TIMEOUT_SECONDS = 300;
 function challengeId() {
   return globalThis.crypto.randomUUID();
@@ -224,9 +355,31 @@ var routeConfigSchema = z.object({
   description: z.string().optional(),
   realm: z.string().optional()
 });
+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 mppMiddlewareConfigSchema = z.object({
   facilitator: facilitatorConfigSchema,
-  routes: z.record(z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required")
+  routes: z.record(z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required").superRefine(consistentRoutePaths)
 });
 
 // src/middleware.ts
@@ -246,15 +399,17 @@ function challengeResponse(route, request, error) {
   };
 }
 function createMppPaymentGate(config) {
-  try {
-    mppMiddlewareConfigSchema.parse(config);
-  } catch (cause) {
+  const checked = mppMiddlewareConfigSchema.safeParse(config);
+  if (!checked.success) {
+    const issue = checked.error.issues[0];
+    const where = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
     throw new MppConfigError(
-      "Invalid MPP middleware config \u2014 check your routes, facilitator URL, payTo and currency addresses",
-      cause
+      `Invalid MPP middleware config${where}: ${issue?.message ?? "check your routes, facilitator URL, payTo and currency addresses"}`,
+      checked.error
     );
   }
   const client = new MppFacilitatorClient(config.facilitator);
+  const routes = routeTable(config.routes);
   const requestByRoute = new Map(
     Object.values(config.routes).map((route) => [
       route,
@@ -262,10 +417,27 @@ function createMppPaymentGate(config) {
     ])
   );
   return async (adapter) => {
-    if (adapter.getMethod().toUpperCase() === "OPTIONS")
-      return { type: "pass" };
-    const route = matchRoute(adapter.getPath(), config.routes);
+    const path = adapter.getPath();
+    const fullPath = adapter.getFullPath?.();
+    let { route, dotSegments } = findRoute(path, routes);
+    if (!route && fullPath !== void 0 && fullPath !== path)
+      ({ route, dotSegments } = findRoute(fullPath, routes));
     if (!route) return { type: "pass" };
+    if (dotSegments) {
+      return {
+        type: "error",
+        result: {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+          body: {
+            error: MPP_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 request = requestByRoute.get(route);
     const credential = parseAuthorizationHeader(
       adapter.getHeader("authorization")
@@ -302,7 +474,8 @@ function createMppPaymentMiddleware(config) {
   const gate = createMppPaymentGate(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 {
@@ -341,4 +514,4 @@ function createMppPaymentMiddleware(config) {
   };
 }
 
-export { MPP_ERROR_CODES, MppConfigError, MppFacilitatorClient, MppRuntimeError, SETTLE_FAILURE_BODY, buildChallenge, chainIdFromSlug, createMppPaymentGate, createMppPaymentMiddleware, isSuccessStatus, matchRoute, parseAuthorizationHeader, parsePrice, serializeChallenge };
+export { MPP_ERROR_CODES, MppConfigError, MppFacilitatorClient, MppRuntimeError, SETTLE_FAILURE_BODY, answerAsPreflight, buildChallenge, chainIdFromSlug, createMppPaymentGate, createMppPaymentMiddleware, dropConditionalHeaders, isSuccessStatus, matchRoute, parseAuthorizationHeader, parsePrice, preflightInit, serializeChallenge };