@bosonprotocol/x402-server 0.2.0 → 0.3.0-alpha-0

package/dist/cjs/index.js

@@ -116,6 +116,31 @@ function buildForwardingAdapter(signer, chainId) {
     getCurrentTimeMs: () => unreachable2("getCurrentTimeMs")
   };
 }
+
+// src/store.ts
+function mapAsStore(m) {
+  return {
+    async get(key) {
+      return m.get(key);
+    },
+    async set(key, value) {
+      m.set(key, value);
+    },
+    async delete(key) {
+      m.delete(key);
+    },
+    async *entries() {
+      for (const e of m.entries()) yield e;
+    }
+  };
+}
+function isStore(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.get === "function" && typeof v.set === "function" && typeof v.delete === "function" && typeof v.entries === "function";
+}
+
+// src/config.ts
 var httpUrlSchema = zod.z.string().url().refine((url) => url.startsWith("http://") || url.startsWith("https://"), {
   message: "must be an http(s) URL"
 });
@@ -138,22 +163,40 @@ var coreSdkReadShallowSchema = zod.z.object({
 var fulfillmentChannelShallowSchema = zod.z.object({
   id: zod.z.string().min(1),
   validate: zod.z.function(),
-  onCommit: zod.z.function()
+  onCommit: zod.z.function(),
+  // Optional delivery dispatch — present on real channels, omitted by
+  // hosts that deliver out-of-band.
+  onFulfill: zod.z.function().optional()
 }).passthrough();
+var asyncStoreSchema = () => zod.z.custom(isStore, {
+  message: "must implement the async Store<V> interface (get/set/delete/entries)"
+});
 var x402bServerConfigSchema = zod.z.object({
   network: escrow.evmNetworkSchema,
   chainId: zod.z.number().int().positive(),
   escrow: escrow.addressSchema,
   signer: sellerSignerSchema,
   facilitator: zod.z.object({
-    url: httpUrlSchema
+    url: httpUrlSchema,
+    timeoutMs: zod.z.number().int().positive().optional(),
+    retry: zod.z.object({
+      attempts: zod.z.number().int().positive(),
+      backoffMs: zod.z.number().int().nonnegative()
+    }).strict().optional(),
+    idempotencyKey: zod.z.function().args().returns(zod.z.string()).optional()
   }).strict(),
   channelRegistry: x402Actions.channelRegistryZodSchema,
   exchangeReader: exchangeReaderShallowSchema.optional(),
   subgraphUrl: httpUrlSchema.optional(),
   coreSdkRead: coreSdkReadShallowSchema.optional(),
-  exchangeFulfillmentOptionStore: zod.z.instanceof(Map).optional(),
-  fulfillmentRecoveryStore: zod.z.instanceof(Map).optional(),
+  exchangeFulfillmentOptionStore: asyncStoreSchema().optional(),
+  fulfillmentRecoveryStore: asyncStoreSchema().optional(),
+  logger: zod.z.object({
+    debug: zod.z.function(),
+    info: zod.z.function(),
+    warn: zod.z.function(),
+    error: zod.z.function()
+  }).passthrough().optional(),
   fulfillmentChannels: zod.z.array(fulfillmentChannelShallowSchema).superRefine((channels, ctx) => {
     const seen = /* @__PURE__ */ new Set();
     const duplicates = /* @__PURE__ */ new Set();
@@ -167,7 +210,8 @@ var x402bServerConfigSchema = zod.z.object({
         message: `fulfillmentChannels has duplicate id(s): ${[...duplicates].join(", ")}`
       });
     }
-  }).optional()
+  }).optional(),
+  mode: zod.z.enum(["development", "production"]).optional()
 }).strict().superRefine((cfg, ctx) => {
   const networkChainId = Number(cfg.network.split(":")[1]);
   if (networkChainId !== cfg.chainId) {
@@ -177,6 +221,36 @@ var x402bServerConfigSchema = zod.z.object({
       message: `chainId (${cfg.chainId}) must match network (${cfg.network})`
     });
   }
+  if (cfg.mode === "production") {
+    if (cfg.exchangeReader === void 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        path: ["exchangeReader"],
+        message: "required when mode is 'production' (post-settle state verification)"
+      });
+    }
+    if (cfg.coreSdkRead === void 0 && cfg.subgraphUrl === void 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        path: ["subgraphUrl"],
+        message: "one of `coreSdkRead` or `subgraphUrl` is required when mode is 'production' (read client for withdraw / available-funds)"
+      });
+    }
+    if (cfg.exchangeFulfillmentOptionStore === void 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        path: ["exchangeFulfillmentOptionStore"],
+        message: "required when mode is 'production'; without a persistent store the Flow A redeem-time option gate silently relaxes after a restart"
+      });
+    }
+    if (cfg.fulfillmentRecoveryStore === void 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        path: ["fulfillmentRecoveryStore"],
+        message: "required when mode is 'production'; without a persistent store, post-settle channel-onCommit failures lose their replay handle"
+      });
+    }
+  }
 });
 function assertChannelRegistryEscrowMatch(config) {
   if (config.escrow.toLowerCase() !== config.channelRegistry.escrow.toLowerCase()) {
@@ -197,7 +271,22 @@ var FacilitatorHttpError = class extends Error {
   }
 };
 
+// src/logger.ts
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+
 // src/facilitator/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_RETRY = { attempts: 3, backoffMs: 200 };
+var IDEMPOTENCY_KEY_HEADER = "x-x402b-idempotency-key";
 function createFacilitatorClient(opts) {
   const fetchImpl = opts.fetch ?? globalThis.fetch;
   if (fetchImpl === void 0) {
@@ -207,19 +296,49 @@ function createFacilitatorClient(opts) {
   }
   const baseUrl = opts.url.replace(/\/+$/, "");
   const baseHeaders = { "content-type": "application/json", ...opts.headers ?? {} };
-  const post = async (path, body, validate) => {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retry = opts.retry ?? DEFAULT_RETRY;
+  if (!Number.isInteger(retry.attempts) || retry.attempts < 1) {
+    throw new Error("createFacilitatorClient: retry.attempts must be an integer >= 1");
+  }
+  if (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0) {
+    throw new Error("createFacilitatorClient: retry.backoffMs must be a finite number >= 0");
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("createFacilitatorClient: timeoutMs must be a finite number > 0");
+  }
+  const newIdempotencyKey = opts.idempotencyKey ?? (() => globalThis.crypto.randomUUID());
+  const setTimeoutImpl = opts.setTimeout ?? setTimeout;
+  const clearTimeoutImpl = opts.clearTimeout ?? clearTimeout;
+  const logger = opts.logger ?? noopLogger;
+  const postOnce = async (path, body, validate, extraHeaders) => {
+    const controller = new AbortController();
+    const timer = setTimeoutImpl(() => controller.abort(), timeoutMs);
+    const headers = { ...baseHeaders, ...extraHeaders };
     let res;
     try {
       res = await fetchImpl(`${baseUrl}${path}`, {
         method: "POST",
-        headers: baseHeaders,
-        body: JSON.stringify(body)
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
       });
     } catch (cause) {
-      throw new FacilitatorHttpError(`facilitator network error (${path})`, {
-        code: "NETWORK_ERROR",
-        cause
+      const aborted = controller.signal.aborted;
+      logger.warn(aborted ? "facilitator request timed out" : "facilitator network error", {
+        path,
+        timeoutMs: aborted ? timeoutMs : void 0,
+        error: cause instanceof Error ? cause.message : String(cause)
       });
+      throw new FacilitatorHttpError(
+        aborted ? `facilitator request timed out after ${timeoutMs}ms (${path})` : `facilitator network error (${path})`,
+        {
+          code: aborted ? "TIMEOUT" : "NETWORK_ERROR",
+          cause
+        }
+      );
+    } finally {
+      clearTimeoutImpl(timer);
     }
     let text;
     try {
@@ -246,6 +365,12 @@ function createFacilitatorClient(opts) {
         return parsed;
       }
       const facilitatorCode = extractFacilitatorCode(parsed);
+      logger.warn("facilitator HTTP non-2xx", {
+        path,
+        status: res.status,
+        facilitatorCode,
+        reason: reasonString(parsed)
+      });
       throw new FacilitatorHttpError(
         `facilitator HTTP ${res.status} (${path}): ${reasonString(parsed) ?? text}`,
         {
@@ -263,16 +388,76 @@ function createFacilitatorClient(opts) {
     }
     return parsed;
   };
+  const post = async (path, body, validate, extraHeaders = {}) => {
+    let lastError;
+    for (let attempt = 0; attempt < retry.attempts; attempt += 1) {
+      if (attempt > 0) {
+        await sleep(retry.backoffMs * attempt, setTimeoutImpl);
+      }
+      try {
+        return await postOnce(path, body, validate, extraHeaders);
+      } catch (e) {
+        if (e instanceof FacilitatorHttpError && isRetryable(e)) {
+          lastError = e;
+          continue;
+        }
+        throw e;
+      }
+    }
+    throw lastError;
+  };
   return {
     verify: (input) => post("/verify", input, isVerifyResult),
-    settle: (input) => post("/settle", input, isSettleResult),
+    settle: (input) => post("/settle", input, isSettleResult, {
+      [IDEMPOTENCY_KEY_HEADER]: newIdempotencyKey()
+    }),
     performAction: (input) => post(
       `/perform-action?action=${encodeURIComponent(input.action)}`,
       input,
       isPerformActionResult
-    )
+    ),
+    async healthCheck() {
+      const controller = new AbortController();
+      const timer = setTimeoutImpl(() => controller.abort(), timeoutMs);
+      let res;
+      try {
+        res = await fetchImpl(`${baseUrl}/healthz`, {
+          method: "GET",
+          headers: { ...opts.headers ?? {} },
+          signal: controller.signal
+        });
+      } catch (cause) {
+        const aborted = controller.signal.aborted;
+        throw new FacilitatorHttpError(
+          aborted ? `facilitator request timed out after ${timeoutMs}ms (/healthz)` : "facilitator network error (/healthz)",
+          {
+            code: aborted ? "TIMEOUT" : "NETWORK_ERROR",
+            cause
+          }
+        );
+      } finally {
+        clearTimeoutImpl(timer);
+      }
+      if (!res.ok) {
+        throw new FacilitatorHttpError(`facilitator HTTP ${res.status} (/healthz)`, {
+          code: "BAD_HTTP_STATUS",
+          status: res.status
+        });
+      }
+    }
   };
 }
+function isRetryable(e) {
+  if (e.code === "NETWORK_ERROR" || e.code === "TIMEOUT") return true;
+  if (e.code === "BAD_HTTP_STATUS" && e.status !== void 0 && e.status >= 500) return true;
+  return false;
+}
+function sleep(ms, setTimeoutImpl) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    setTimeoutImpl(resolve, ms);
+  });
+}
 function isObject(v) {
   return v !== null && typeof v === "object";
 }
@@ -368,6 +553,21 @@ function emitNextActions(input, registry, facilitatorUrl) {
   };
 }
 
+// src/handlers/fulfillment-result.ts
+function serializeFulfillmentResult(result) {
+  if (result.kind === "inline") {
+    return {
+      kind: "inline",
+      body: Buffer.from(result.body).toString("base64"),
+      contentType: result.contentType
+    };
+  }
+  return {
+    kind: "async",
+    ...result.pointer !== void 0 ? { pointer: result.pointer } : {}
+  };
+}
+
 // src/handlers/types.ts
 function handlerOk(body) {
   return { ok: true, status: 200, body };
@@ -889,6 +1089,7 @@ async function handleCommitAndRedeem(input, ctx) {
   });
 }
 async function handleCommitImpl(input, ctx, expected) {
+  const logger = ctx.logger ?? noopLogger;
   const decoded = decodeXPaymentHeader(input.paymentHeader);
   if (!decoded.ok) {
     const status = decoded.code === "MISSING_HEADER" ? 402 : 400;
@@ -977,28 +1178,38 @@ async function handleCommitImpl(input, ctx, expected) {
     );
   }
   if (expected.expectedState === x402Actions.ExchangeState.COMMITTED) {
-    ctx.exchangeFulfillmentOptionStore.set(
+    await ctx.exchangeFulfillmentOptionStore.set(
       settleResult.exchangeId,
       input.requirements.fulfillment?.options.map((option) => option.id) ?? []
     );
   }
   const warnings = [];
+  let delivery;
   if (expected.expectedState === x402Actions.ExchangeState.REDEEMED && decoded.payload.fulfillment !== void 0 && decoded.payload.fulfillment.data !== void 0) {
     const pending = {
       exchangeId: settleResult.exchangeId,
       option: decoded.payload.fulfillment.option,
       data: decoded.payload.fulfillment.data,
       redeemer: decoded.payload.payload.buyer,
-      recordedAt: Date.now()
+      recordedAt: Date.now(),
+      phase: "commit"
     };
-    ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, pending);
+    await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, pending);
+    logger.debug("x402-server: fulfillment recovery entry recorded (Flow B)", {
+      exchangeId: settleResult.exchangeId,
+      option: decoded.payload.fulfillment.option
+    });
     const channel = channelById.get(decoded.payload.fulfillment.option);
     if (channel === void 0) {
       const reason = "no channel adapter is registered";
-      ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+      await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
         ...pending,
         error: reason
       });
+      logger.error("x402-server: Flow B channel adapter missing post-settle", {
+        exchangeId: settleResult.exchangeId,
+        option: decoded.payload.fulfillment.option
+      });
       warnings.push({
         code: "FULFILLMENT_COMMIT_DEFERRED",
         reason: "atomic redeem succeeded on-chain, but no channel adapter is registered",
@@ -1011,13 +1222,54 @@ async function handleCommitImpl(input, ctx, expected) {
     } else {
       try {
         await channel.onCommit(settleResult.exchangeId, decoded.payload.fulfillment.data);
-        ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+        if (channel.onFulfill !== void 0) {
+          const deliveryPending = {
+            ...pending,
+            phase: "delivery",
+            recordedAt: Date.now()
+          };
+          await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, deliveryPending);
+          try {
+            delivery = serializeFulfillmentResult(await channel.onFulfill(settleResult.exchangeId));
+            await ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+            logger.debug("x402-server: Flow B channel onCommit succeeded", {
+              exchangeId: settleResult.exchangeId,
+              option: decoded.payload.fulfillment.option
+            });
+          } catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+              ...deliveryPending,
+              error: reason
+            });
+            warnings.push({
+              code: "FULFILLMENT_DELIVERY_DEFERRED",
+              reason: "atomic redeem succeeded on-chain, but the channel's delivery dispatch failed",
+              details: {
+                exchangeId: settleResult.exchangeId,
+                option: decoded.payload.fulfillment.option,
+                error: reason
+              }
+            });
+          }
+        } else {
+          await ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+          logger.debug("x402-server: Flow B channel onCommit succeeded", {
+            exchangeId: settleResult.exchangeId,
+            option: decoded.payload.fulfillment.option
+          });
+        }
       } catch (e) {
         const reason = e instanceof Error ? e.message : String(e);
-        ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+        await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
           ...pending,
           error: reason
         });
+        logger.warn("x402-server: Flow B channel onCommit failed; recovery entry retained", {
+          exchangeId: settleResult.exchangeId,
+          option: decoded.payload.fulfillment.option,
+          error: reason
+        });
         warnings.push({
           code: "FULFILLMENT_COMMIT_DEFERRED",
           reason: "atomic redeem succeeded on-chain, but the channel adapter rejected the data",
@@ -1042,7 +1294,8 @@ async function handleCommitImpl(input, ctx, expected) {
     exchangeId: settleResult.exchangeId,
     txHash: settleResult.txHash,
     nextActions,
-    ...warnings.length > 0 ? { warnings } : {}
+    ...warnings.length > 0 ? { warnings } : {},
+    ...delivery !== void 0 ? { fulfillment: delivery } : {}
   });
 }
 function buildExpectedFromRequirements(requirements, state) {
@@ -1142,7 +1395,7 @@ async function handleRedeem(input, ctx) {
   }
   let resolvedChannel;
   if (input.fulfillment !== void 0) {
-    const advertisedOptions = ctx.exchangeFulfillmentOptionStore.get(input.exchangeId);
+    const advertisedOptions = await ctx.exchangeFulfillmentOptionStore.get(input.exchangeId);
     if (advertisedOptions !== void 0 && !advertisedOptions.includes(input.fulfillment.option)) {
       return handlerErr(
         400,
@@ -1185,23 +1438,40 @@ async function handleRedeem(input, ctx) {
   }
   const result = await handlePerformAction("boson-redeem", input, ctx);
   if (!result.ok) return result;
-  let warning;
+  const warnings = [];
+  let delivery;
   if (resolvedChannel !== void 0 && input.fulfillment !== void 0) {
     const pending = {
       exchangeId: input.exchangeId,
       option: input.fulfillment.option,
       data: input.fulfillment.data,
       redeemer,
-      recordedAt: Date.now()
+      recordedAt: Date.now(),
+      phase: "commit"
     };
-    ctx.fulfillmentRecoveryStore.set(input.exchangeId, pending);
+    const logger = ctx.logger ?? noopLogger;
+    await ctx.fulfillmentRecoveryStore.set(input.exchangeId, pending);
+    logger.debug("x402-server: fulfillment recovery entry recorded (Flow A redeem)", {
+      exchangeId: input.exchangeId,
+      option: input.fulfillment.option
+    });
+    let onCommitOk = false;
     try {
       await resolvedChannel.onCommit(input.exchangeId, input.fulfillment.data);
-      ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+      onCommitOk = true;
+      logger.debug("x402-server: Flow A channel onCommit succeeded", {
+        exchangeId: input.exchangeId,
+        option: input.fulfillment.option
+      });
     } catch (e) {
       const reason = errorMessage(e);
-      ctx.fulfillmentRecoveryStore.set(input.exchangeId, { ...pending, error: reason });
-      warning = {
+      await ctx.fulfillmentRecoveryStore.set(input.exchangeId, { ...pending, error: reason });
+      logger.warn("x402-server: Flow A channel onCommit failed; recovery entry retained", {
+        exchangeId: input.exchangeId,
+        option: input.fulfillment.option,
+        error: reason
+      });
+      warnings.push({
         code: "FULFILLMENT_UPDATE_DEFERRED",
         reason: "redeem succeeded on-chain, but the server could not persist the fulfillment update",
         details: {
@@ -1209,16 +1479,48 @@ async function handleRedeem(input, ctx) {
           option: input.fulfillment.option,
           error: reason
         }
-      };
+      });
+    }
+    if (onCommitOk) {
+      if (resolvedChannel.onFulfill !== void 0) {
+        const deliveryPending = {
+          ...pending,
+          phase: "delivery",
+          recordedAt: Date.now()
+        };
+        await ctx.fulfillmentRecoveryStore.set(input.exchangeId, deliveryPending);
+        try {
+          delivery = serializeFulfillmentResult(await resolvedChannel.onFulfill(input.exchangeId));
+          await ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+        } catch (e) {
+          const reason = errorMessage(e);
+          await ctx.fulfillmentRecoveryStore.set(input.exchangeId, {
+            ...deliveryPending,
+            error: reason
+          });
+          warnings.push({
+            code: "FULFILLMENT_DELIVERY_DEFERRED",
+            reason: "redeem succeeded on-chain, but the fulfillment channel's delivery dispatch failed",
+            details: {
+              exchangeId: input.exchangeId,
+              option: input.fulfillment.option,
+              error: reason
+            }
+          });
+        }
+      } else {
+        await ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+      }
     }
   }
-  ctx.exchangeFulfillmentOptionStore.delete(input.exchangeId);
-  if (warning !== void 0) {
+  await ctx.exchangeFulfillmentOptionStore.delete(input.exchangeId);
+  if (warnings.length > 0 || delivery !== void 0) {
     return {
       ...result,
       body: {
         ...result.body,
-        warnings: [...result.body.warnings ?? [], warning]
+        ...delivery !== void 0 ? { fulfillment: delivery } : {},
+        ...warnings.length > 0 ? { warnings: [...result.body.warnings ?? [], ...warnings] } : {}
       }
     };
   }
@@ -1461,6 +1763,52 @@ function asCoreSdkReadAdapter(coreSdk) {
   return coreSdk;
 }
 
+// src/concurrency.ts
+function createKeyedMutex() {
+  const chains = /* @__PURE__ */ new Map();
+  return {
+    runExclusive(key, fn) {
+      const prev = chains.get(key) ?? Promise.resolve();
+      const run = prev.then(fn, fn);
+      const tracked = run.catch(() => void 0);
+      chains.set(key, tracked);
+      tracked.then(() => {
+        if (chains.get(key) === tracked) chains.delete(key);
+      });
+      return run;
+    }
+  };
+}
+
+// src/health.ts
+function createHealthCheck(deps) {
+  return async () => {
+    const facilitator = await probe(() => deps.facilitator.healthCheck()) ? "ok" : "down";
+    let readClient;
+    let readClientFailed = false;
+    if (typeof deps.coreSdkRead === "function") {
+      try {
+        readClient = deps.coreSdkRead();
+      } catch {
+        readClientFailed = true;
+      }
+    } else {
+      readClient = deps.coreSdkRead;
+    }
+    const subgraph = readClientFailed ? "down" : readClient === void 0 ? "n/a" : await probe(() => readClient.getSellersByAddress(ZERO_ADDRESS_PROBE)) ? "ok" : "down";
+    return { facilitator, subgraph };
+  };
+}
+async function probe(fn) {
+  try {
+    await fn();
+    return true;
+  } catch {
+    return false;
+  }
+}
+var ZERO_ADDRESS_PROBE = "0x0000000000000000000000000000000000000000";
+
 // src/server.ts
 function withFacilitatorEndpoints(requirements, facilitatorUrl) {
   return {
@@ -1474,9 +1822,23 @@ function withFacilitatorEndpoints(requirements, facilitatorUrl) {
 function createX402bServer(config) {
   const validated = x402bServerConfigSchema.parse(config);
   assertChannelRegistryEscrowMatch(validated);
-  const facilitator = createFacilitatorClient({ url: validated.facilitator.url });
-  const exchangeFulfillmentOptionStore = validated.exchangeFulfillmentOptionStore ?? /* @__PURE__ */ new Map();
-  const fulfillmentRecoveryStore = validated.fulfillmentRecoveryStore ?? /* @__PURE__ */ new Map();
+  const logger = validated.logger ?? noopLogger;
+  logger.info("x402-server: createX402bServer", {
+    network: validated.network,
+    chainId: validated.chainId,
+    escrow: validated.escrow,
+    facilitatorUrl: validated.facilitator.url
+  });
+  const facilitator = createFacilitatorClient({
+    url: validated.facilitator.url,
+    logger,
+    ...validated.facilitator.timeoutMs !== void 0 ? { timeoutMs: validated.facilitator.timeoutMs } : {},
+    ...validated.facilitator.retry !== void 0 ? { retry: validated.facilitator.retry } : {},
+    ...validated.facilitator.idempotencyKey !== void 0 ? { idempotencyKey: validated.facilitator.idempotencyKey } : {}
+  });
+  const exchangeMutex = createKeyedMutex();
+  const exchangeFulfillmentOptionStore = validated.exchangeFulfillmentOptionStore ?? mapAsStore(/* @__PURE__ */ new Map());
+  const fulfillmentRecoveryStore = validated.fulfillmentRecoveryStore ?? mapAsStore(/* @__PURE__ */ new Map());
   validated.exchangeFulfillmentOptionStore = exchangeFulfillmentOptionStore;
   validated.fulfillmentRecoveryStore = fulfillmentRecoveryStore;
   const signOffer = (unsigned) => signFullOffer({
@@ -1494,14 +1856,10 @@ function createX402bServer(config) {
     return validated.exchangeReader;
   };
   let cachedCoreSdkRead;
-  const requireCoreSdkRead = (action) => {
+  const getOrCreateCoreSdkRead = () => {
     if (validated.coreSdkRead !== void 0) return validated.coreSdkRead;
     if (cachedCoreSdkRead !== void 0) return cachedCoreSdkRead;
-    if (validated.subgraphUrl === void 0) {
-      throw new Error(
-        `x402-server: handlers.${action}() requires either \`coreSdkRead\` or \`subgraphUrl\` in config (subgraph read step).`
-      );
-    }
+    if (validated.subgraphUrl === void 0) return void 0;
     cachedCoreSdkRead = asCoreSdkReadAdapter(
       new coreSdk.CoreSDK({
         web3Lib: createReadOnlyWeb3LibStub(),
@@ -1512,10 +1870,106 @@ function createX402bServer(config) {
     );
     return cachedCoreSdkRead;
   };
+  const requireCoreSdkRead = (action) => {
+    const client = getOrCreateCoreSdkRead();
+    if (client === void 0) {
+      throw new Error(
+        `x402-server: handlers.${action}() requires either \`coreSdkRead\` or \`subgraphUrl\` in config (subgraph read step).`
+      );
+    }
+    return client;
+  };
+  const recovery = {
+    async list() {
+      const entries = [];
+      for await (const [, value] of fulfillmentRecoveryStore.entries()) {
+        entries.push(value);
+      }
+      return entries;
+    },
+    async replay(exchangeId) {
+      const entry = await fulfillmentRecoveryStore.get(exchangeId);
+      if (entry === void 0) {
+        return { ok: false, reason: `no pending recovery entry for exchangeId '${exchangeId}'` };
+      }
+      const channels = validated.fulfillmentChannels ?? [];
+      const channel = channels.find((c) => c.id === entry.option);
+      if (channel === void 0) {
+        const reason = `no channel adapter is registered for option '${entry.option}'`;
+        await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+        logger.warn("x402-server: recovery replay failed (no adapter)", {
+          exchangeId,
+          option: entry.option
+        });
+        return { ok: false, reason };
+      }
+      if (entry.phase === "delivery") {
+        if (channel.onFulfill === void 0) {
+          const reason = `channel '${entry.option}' has no onFulfill; cannot replay delivery phase`;
+          await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+          logger.warn("x402-server: recovery replay failed (no onFulfill)", {
+            exchangeId,
+            option: entry.option
+          });
+          return { ok: false, reason };
+        }
+        try {
+          await channel.onFulfill(exchangeId);
+          await fulfillmentRecoveryStore.delete(exchangeId);
+          logger.info("x402-server: recovery replay succeeded", {
+            exchangeId,
+            option: entry.option,
+            phase: entry.phase
+          });
+          return { ok: true };
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+          logger.warn("x402-server: recovery replay failed (channel error)", {
+            exchangeId,
+            option: entry.option,
+            phase: entry.phase,
+            error: reason
+          });
+          return { ok: false, reason };
+        }
+      }
+      try {
+        await channel.onCommit(exchangeId, entry.data);
+        await fulfillmentRecoveryStore.delete(exchangeId);
+        logger.info("x402-server: recovery replay succeeded", {
+          exchangeId,
+          option: entry.option,
+          phase: entry.phase
+        });
+        return { ok: true };
+      } catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+        logger.warn("x402-server: recovery replay failed (channel error)", {
+          exchangeId,
+          option: entry.option,
+          phase: entry.phase,
+          error: reason
+        });
+        return { ok: false, reason };
+      }
+    }
+  };
+  const healthCheck = createHealthCheck({
+    facilitator,
+    // Materialise the lazy `subgraphUrl`-backed read client on first
+    // probe so a configured subgraph is actually checked (reporting
+    // `"ok"` / `"down"` rather than `"n/a"`). Only the
+    // "no `coreSdkRead` AND no `subgraphUrl`" case maps to `"n/a"`.
+    coreSdkRead: () => getOrCreateCoreSdkRead()
+  });
   return {
     config: validated,
     facilitator,
     signOffer,
+    recovery,
+    healthCheck,
     async buildPaymentRequirements(input) {
       const offer = "unsigned" in input.offer ? await signOffer(input.offer.unsigned) : input.offer;
       const requirements = buildPaymentRequirements({
@@ -1538,47 +1992,73 @@ function createX402bServer(config) {
         facilitator,
         exchangeReader: await requireReader("commit"),
         fulfillmentRecoveryStore,
-        exchangeFulfillmentOptionStore
+        exchangeFulfillmentOptionStore,
+        logger
       }),
       commitAndRedeem: async (input) => handleCommitAndRedeem(input, {
         config: validated,
         facilitator,
         exchangeReader: await requireReader("commitAndRedeem"),
         fulfillmentRecoveryStore,
-        exchangeFulfillmentOptionStore
-      }),
-      redeem: async (input) => handleRedeem(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("redeem"),
         exchangeFulfillmentOptionStore,
-        fulfillmentRecoveryStore
-      }),
-      complete: async (input) => handleComplete(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("complete")
-      }),
-      disputeRaise: async (input) => handleDisputeRaise(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeRaise")
-      }),
-      disputeResolve: async (input) => handleDisputeResolve(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeResolve")
-      }),
-      disputeRetract: async (input) => handleDisputeRetract(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeRetract")
-      }),
-      disputeEscalate: async (input) => handleDisputeEscalate(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeEscalate")
+        logger
       }),
+      redeem: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleRedeem(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("redeem"),
+          exchangeFulfillmentOptionStore,
+          fulfillmentRecoveryStore,
+          logger
+        })
+      ),
+      complete: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleComplete(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("complete"),
+          logger
+        })
+      ),
+      disputeRaise: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeRaise(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeRaise"),
+          logger
+        })
+      ),
+      disputeResolve: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeResolve(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeResolve"),
+          logger
+        })
+      ),
+      disputeRetract: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeRetract(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeRetract"),
+          logger
+        })
+      ),
+      disputeEscalate: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeEscalate(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeEscalate"),
+          logger
+        })
+      ),
       withdrawFunds: async (input) => handleWithdrawFunds(input, {
         config: validated,
         facilitator,
@@ -1610,11 +2090,14 @@ exports.ADDRESS_RE = ADDRESS_RE;
 exports.DECIMAL_UINT_RE = DECIMAL_UINT_RE;
 exports.FacilitatorHttpError = FacilitatorHttpError;
 exports.HEX_BYTES_RE = HEX_BYTES_RE;
+exports.IDEMPOTENCY_KEY_HEADER = IDEMPOTENCY_KEY_HEADER;
 exports.X_PAYMENT_RESPONSE_HEADER = X_PAYMENT_RESPONSE_HEADER;
 exports.asCoreSdkReadAdapter = asCoreSdkReadAdapter;
 exports.assertChannelRegistryEscrowMatch = assertChannelRegistryEscrowMatch;
 exports.buildPaymentRequirements = buildPaymentRequirements;
 exports.createFacilitatorClient = createFacilitatorClient;
+exports.createHealthCheck = createHealthCheck;
+exports.createKeyedMutex = createKeyedMutex;
 exports.createX402bServer = createX402bServer;
 exports.decodeXPaymentHeader = decodeXPaymentHeader;
 exports.emitNextActions = emitNextActions;
@@ -1632,6 +2115,9 @@ exports.handleRedeem = handleRedeem;
 exports.handleWithdrawFunds = handleWithdrawFunds;
 exports.handlerErr = handlerErr;
 exports.handlerOk = handlerOk;
+exports.isStore = isStore;
+exports.mapAsStore = mapAsStore;
+exports.noopLogger = noopLogger;
 exports.plainHandlerOk = plainHandlerOk;
 exports.resolveEntityId = resolveEntityId;
 exports.signFullOffer = signFullOffer;