@bosonprotocol/x402-server 0.1.0-alpha-0

package/dist/cjs/handlers/index.js

@@ -0,0 +1,1182 @@
+'use strict';
+
+var x402Actions = require('@bosonprotocol/x402-actions');
+var escrow = require('@bosonprotocol/x402-core/schemes/escrow');
+var eip712 = require('@bosonprotocol/x402-core/eip712');
+var x402Evm = require('@bosonprotocol/x402-evm');
+var stateMachine = require('@bosonprotocol/x402-core/state-machine');
+
+// src/handlers/commit-and-redeem.ts
+
+// src/internal/facilitator-endpoints.ts
+var COMMIT_ACTION_IDS = /* @__PURE__ */ new Set([
+  "boson-createOfferAndCommit",
+  "boson-createOfferCommitAndRedeem"
+]);
+function facilitatorEndpointFor(actionId, facilitatorUrl) {
+  const base = facilitatorUrl.replace(/\/+$/, "");
+  if (COMMIT_ACTION_IDS.has(actionId)) {
+    return `${base}/settle`;
+  }
+  return `${base}/perform-action?action=${encodeURIComponent(actionId)}`;
+}
+function stampFacilitatorEndpoints(next, facilitatorUrl) {
+  return next.map((entry) => {
+    if (!entry.channels.includes("facilitator")) {
+      return entry;
+    }
+    if (entry.endpoints?.facilitator !== void 0) {
+      return entry;
+    }
+    return {
+      ...entry,
+      endpoints: {
+        ...entry.endpoints,
+        facilitator: facilitatorEndpointFor(entry.id, facilitatorUrl)
+      }
+    };
+  });
+}
+
+// src/handlers/next-actions.ts
+function emitNextActions(input, registry, facilitatorUrl) {
+  const derived = input.exchangeState === x402Actions.ExchangeState.DISPUTED ? x402Actions.deriveNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: x402Actions.ExchangeState.DISPUTED,
+      disputeState: input.disputeState
+    },
+    registry
+  ) : x402Actions.deriveNextActions(
+    { exchangeId: input.exchangeId, exchangeState: input.exchangeState },
+    registry
+  );
+  if (facilitatorUrl === void 0) {
+    return derived;
+  }
+  return {
+    ...derived,
+    next: stampFacilitatorEndpoints(derived.next, facilitatorUrl)
+  };
+}
+
+// src/handlers/types.ts
+function handlerOk(body) {
+  return { ok: true, status: 200, body };
+}
+function plainHandlerOk(body) {
+  return { ok: true, status: 200, body };
+}
+function handlerErr(status, code, reason, details) {
+  const body = { code, reason };
+  if (details !== void 0) body.details = details;
+  return { ok: false, status, body };
+}
+function decodeXPaymentHeader(header) {
+  if (header === void 0 || header === null || header.length === 0) {
+    return { ok: false, code: "MISSING_HEADER", reason: "X-PAYMENT header is missing" };
+  }
+  const padded = base64UrlToBase64(header);
+  let decoded;
+  try {
+    if (typeof atob === "function") {
+      const binary = atob(padded);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+      decoded = new TextDecoder().decode(bytes);
+    } else {
+      decoded = Buffer.from(padded, "base64").toString("utf8");
+    }
+  } catch (e) {
+    return { ok: false, code: "INVALID_BASE64", reason: e.message };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch (e) {
+    return { ok: false, code: "INVALID_JSON", reason: e.message };
+  }
+  try {
+    const payload = escrow.parseEscrowPaymentPayload(parsed);
+    return { ok: true, payload };
+  } catch (e) {
+    return { ok: false, code: "INVALID_PAYLOAD", reason: e.message };
+  }
+}
+function base64UrlToBase64(input) {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
+  return normalized + padding;
+}
+async function validatePaymentPayload(args) {
+  const { payload, requirements } = args;
+  if (payload.scheme !== "escrow" || requirements.scheme !== "escrow") {
+    return failure(1, "SCHEME_MISMATCH", "scheme", "escrow", payload.scheme);
+  }
+  if (payload.network !== requirements.network) {
+    return failure(2, "NETWORK_MISMATCH", "network", requirements.network, payload.network);
+  }
+  if (!deepEqual(payload.payload.offerRef.fullOffer, requirements.offer.fullOffer)) {
+    return failure(
+      3,
+      "FULL_OFFER_MISMATCH",
+      "payload.offerRef.fullOffer",
+      "<requirements.offer.fullOffer>",
+      "<payload.offerRef.fullOffer>"
+    );
+  }
+  if (payload.payload.offerRef.sellerSig !== requirements.offer.sellerSig) {
+    return failure(
+      4,
+      "SELLER_SIG_MISMATCH",
+      "payload.offerRef.sellerSig",
+      requirements.offer.sellerSig,
+      payload.payload.offerRef.sellerSig
+    );
+  }
+  const advertisedActions = requirements.actions.next.map((entry) => entry.id);
+  if (!advertisedActions.includes(payload.payload.action)) {
+    return failure(
+      5,
+      "ACTION_NOT_IN_REQUIREMENTS",
+      "payload.action",
+      advertisedActions,
+      payload.payload.action
+    );
+  }
+  if (!requirements.tokenAuthStrategies.includes(payload.payload.tokenAuthStrategy)) {
+    return failure(
+      6,
+      "TOKEN_AUTH_NOT_IN_REQUIREMENTS",
+      "payload.tokenAuthStrategy",
+      requirements.tokenAuthStrategies,
+      payload.payload.tokenAuthStrategy
+    );
+  }
+  const calldataResult = await checkFunctionSignatureAndCalldataEquality(payload);
+  if (calldataResult !== null) return calldataResult;
+  if (payload.payload.buyer.toLowerCase() !== payload.payload.metaTx.from.toLowerCase()) {
+    return failure(
+      8,
+      "BAD_META_TX_SIGNATURE",
+      "payload.metaTx.from",
+      payload.payload.buyer,
+      payload.payload.metaTx.from
+    );
+  }
+  let recovered;
+  try {
+    recovered = await eip712.recoverMetaTransactionSigner({
+      chainId: args.chainId,
+      verifyingContract: requirements.escrowAddress,
+      message: {
+        nonce: BigInt(payload.payload.metaTx.nonce),
+        from: payload.payload.metaTx.from,
+        contractAddress: requirements.escrowAddress,
+        functionName: payload.payload.metaTx.functionName,
+        functionSignature: payload.payload.metaTx.functionSignature
+      },
+      signature: encodeRsv(payload.payload.metaTx.sig)
+    });
+  } catch (e) {
+    return failure(
+      8,
+      "BAD_META_TX_SIGNATURE",
+      "payload.metaTx.sig",
+      "recoverable ECDSA signature",
+      payload.payload.metaTx.sig,
+      e.message
+    );
+  }
+  if (recovered.toLowerCase() !== payload.payload.buyer.toLowerCase()) {
+    return failure(
+      8,
+      "BAD_META_TX_SIGNATURE",
+      "payload.metaTx.sig",
+      payload.payload.buyer,
+      recovered
+    );
+  }
+  const strategyResult = checkTokenAuthRules(payload, requirements, args.now);
+  if (strategyResult !== null) return strategyResult;
+  const fulfillmentResult = checkFulfillment(payload, requirements, args.validateFulfillmentData);
+  if (fulfillmentResult !== null) return fulfillmentResult;
+  return { ok: true };
+}
+async function checkFunctionSignatureAndCalldataEquality(payload) {
+  const action = payload.payload.action;
+  const buildCalldata = action === "boson-createOfferAndCommit" ? x402Evm.buildCreateOfferAndCommitCalldata : action === "boson-createOfferCommitAndRedeem" ? x402Evm.buildCreateOfferCommitAndRedeemCalldata : void 0;
+  if (!buildCalldata) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.action",
+      "boson-createOfferAndCommit | boson-createOfferCommitAndRedeem",
+      action,
+      "rule-7 calldata reconstruction is only defined for commit-time actions"
+    );
+  }
+  const fullOfferWithSig = {
+    ...payload.payload.offerRef.fullOffer,
+    committer: payload.payload.buyer,
+    signature: payload.payload.offerRef.sellerSig
+  };
+  let expected;
+  try {
+    expected = await buildCalldata({ fullOffer: fullOfferWithSig });
+  } catch (e) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.metaTx.functionSignature",
+      void 0,
+      void 0,
+      e.message
+    );
+  }
+  if (expected.functionName !== payload.payload.metaTx.functionName) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.metaTx.functionName",
+      expected.functionName,
+      payload.payload.metaTx.functionName
+    );
+  }
+  if (expected.functionSignature.toLowerCase() !== payload.payload.metaTx.functionSignature.toLowerCase()) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.metaTx.functionSignature",
+      expected.functionSignature,
+      payload.payload.metaTx.functionSignature
+    );
+  }
+  return null;
+}
+function checkTokenAuthRules(payload, requirements, nowSec) {
+  const strategy = payload.payload.tokenAuthStrategy;
+  const tokenAuth = payload.payload.tokenAuth;
+  const now = nowSec ?? Math.floor(Date.now() / 1e3);
+  const horizon = now + requirements.maxTimeoutSeconds;
+  if (strategy === "none") {
+    if (tokenAuth !== void 0) {
+      return failure(
+        9,
+        "TOKEN_AUTH_UNEXPECTED",
+        "payload.tokenAuth",
+        "undefined (strategy=none)",
+        tokenAuth.kind
+      );
+    }
+    return null;
+  }
+  if (tokenAuth === void 0) {
+    return failure(
+      9,
+      "TOKEN_AUTH_MISSING",
+      "payload.tokenAuth",
+      `<${strategy} authorization>`,
+      "undefined"
+    );
+  }
+  if (tokenAuth.kind !== strategy) {
+    return failure(9, "TOKEN_AUTH_MISSING", "payload.tokenAuth.kind", strategy, tokenAuth.kind);
+  }
+  switch (tokenAuth.kind) {
+    case "erc3009": {
+      if (tokenAuth.data.value !== requirements.amount) {
+        return failure(
+          9,
+          "TOKEN_AUTH_AMOUNT_MISMATCH",
+          "payload.tokenAuth.data.value",
+          requirements.amount,
+          tokenAuth.data.value
+        );
+      }
+      if (tokenAuth.data.to.toLowerCase() !== requirements.escrowAddress.toLowerCase()) {
+        return failure(
+          9,
+          "TOKEN_AUTH_RECIPIENT_MISMATCH",
+          "payload.tokenAuth.data.to",
+          requirements.escrowAddress,
+          tokenAuth.data.to
+        );
+      }
+      if (tokenAuth.data.validBefore > horizon) {
+        return failure(
+          9,
+          "TOKEN_AUTH_DEADLINE_EXCEEDED",
+          "payload.tokenAuth.data.validBefore",
+          `<= ${horizon}`,
+          tokenAuth.data.validBefore
+        );
+      }
+      return null;
+    }
+    case "permit": {
+      if (tokenAuth.data.value !== requirements.amount) {
+        return failure(
+          10,
+          "TOKEN_AUTH_AMOUNT_MISMATCH",
+          "payload.tokenAuth.data.value",
+          requirements.amount,
+          tokenAuth.data.value
+        );
+      }
+      if (tokenAuth.data.spender.toLowerCase() !== requirements.escrowAddress.toLowerCase()) {
+        return failure(
+          10,
+          "TOKEN_AUTH_SPENDER_MISMATCH",
+          "payload.tokenAuth.data.spender",
+          requirements.escrowAddress,
+          tokenAuth.data.spender
+        );
+      }
+      if (tokenAuth.data.deadline > horizon) {
+        return failure(
+          10,
+          "TOKEN_AUTH_DEADLINE_EXCEEDED",
+          "payload.tokenAuth.data.deadline",
+          `<= ${horizon}`,
+          tokenAuth.data.deadline
+        );
+      }
+      return null;
+    }
+    case "permit2": {
+      if (tokenAuth.data.permitted.amount !== requirements.amount) {
+        return failure(
+          11,
+          "TOKEN_AUTH_AMOUNT_MISMATCH",
+          "payload.tokenAuth.data.permitted.amount",
+          requirements.amount,
+          tokenAuth.data.permitted.amount
+        );
+      }
+      if (tokenAuth.data.permitted.token.toLowerCase() !== requirements.asset.toLowerCase()) {
+        return failure(
+          11,
+          "TOKEN_AUTH_TOKEN_MISMATCH",
+          "payload.tokenAuth.data.permitted.token",
+          requirements.asset,
+          tokenAuth.data.permitted.token
+        );
+      }
+      if (tokenAuth.data.spender.toLowerCase() !== requirements.escrowAddress.toLowerCase()) {
+        return failure(
+          11,
+          "TOKEN_AUTH_SPENDER_MISMATCH",
+          "payload.tokenAuth.data.spender",
+          requirements.escrowAddress,
+          tokenAuth.data.spender
+        );
+      }
+      if (tokenAuth.data.deadline > horizon) {
+        return failure(
+          11,
+          "TOKEN_AUTH_DEADLINE_EXCEEDED",
+          "payload.tokenAuth.data.deadline",
+          `<= ${horizon}`,
+          tokenAuth.data.deadline
+        );
+      }
+      return null;
+    }
+    default:
+      return failure(
+        9,
+        "TOKEN_AUTH_UNKNOWN_STRATEGY",
+        "payload.tokenAuth.kind",
+        "erc3009 | permit | permit2",
+        tokenAuth.kind
+      );
+  }
+}
+function checkFulfillment(payload, requirements, validator) {
+  const required = requirements.fulfillment?.required === true;
+  const carried = payload.fulfillment;
+  if (carried === void 0) {
+    return required ? failure(13, "FULFILLMENT_REQUIRED", "payload.fulfillment", "<option>", "undefined") : null;
+  }
+  const advertised = requirements.fulfillment?.options ?? [];
+  const matched = advertised.find((option) => option.id === carried.option);
+  if (!matched) {
+    return failure(
+      13,
+      "FULFILLMENT_OPTION_NOT_ADVERTISED",
+      "payload.fulfillment.option",
+      advertised.map((o) => o.id),
+      carried.option
+    );
+  }
+  const action = payload.payload.action;
+  if (action === "boson-createOfferCommitAndRedeem") {
+    if (carried.data === void 0) {
+      return failure(
+        13,
+        "FULFILLMENT_DATA_REQUIRED",
+        "payload.fulfillment.data",
+        matched.schema ?? "null",
+        "undefined",
+        "atomic createOfferCommitAndRedeem requires fulfillment.data at commit time"
+      );
+    }
+    if (validator !== void 0) {
+      const result = validator(matched.id, carried.data);
+      if (!result.ok) {
+        return failure(
+          13,
+          "FULFILLMENT_DATA_INVALID",
+          "payload.fulfillment.data",
+          matched.schema,
+          carried.data,
+          result.reason
+        );
+      }
+    }
+    return null;
+  }
+  if (carried.data !== void 0) {
+    return failure(
+      13,
+      "FULFILLMENT_DATA_UNEXPECTED",
+      "payload.fulfillment.data",
+      "undefined",
+      carried.data,
+      "two-step boson-createOfferAndCommit defers fulfillment.data to the redeem POST body"
+    );
+  }
+  return null;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const ao = a;
+  const bo = b;
+  const aKeys = Object.keys(ao);
+  const bKeys = Object.keys(bo);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(bo, k)) return false;
+    if (!deepEqual(ao[k], bo[k])) return false;
+  }
+  return true;
+}
+function encodeRsv(sig) {
+  if (sig.v !== 0 && sig.v !== 1 && sig.v !== 27 && sig.v !== 28) {
+    throw new Error("signature v must be 0, 1, 27, or 28");
+  }
+  const r = sig.r.replace(/^0x/, "").padStart(64, "0");
+  const s = sig.s.replace(/^0x/, "").padStart(64, "0");
+  const normalizedV = sig.v === 0 || sig.v === 1 ? sig.v + 27 : sig.v;
+  const v = normalizedV.toString(16).padStart(2, "0");
+  return `0x${r}${s}${v}`;
+}
+function failure(rule, code, field, expected, got, reason) {
+  const out = { ok: false, rule, code };
+  if (field !== void 0) out.field = field;
+  if (expected !== void 0) out.expected = expected;
+  if (got !== void 0) out.got = got;
+  if (reason !== void 0) out.reason = reason;
+  return out;
+}
+function verifyExchangeSnapshot(snapshot, expected) {
+  if (snapshot === null) {
+    return { ok: false, code: "EXCHANGE_NOT_FOUND" };
+  }
+  if (snapshot.state !== expected.state) {
+    return {
+      ok: false,
+      code: "STATE_MISMATCH",
+      field: "state",
+      expected: expected.state,
+      got: snapshot.state
+    };
+  }
+  if (expected.state === x402Actions.ExchangeState.DISPUTED) {
+    if (snapshot.disputeState !== expected.disputeState) {
+      return {
+        ok: false,
+        code: "DISPUTE_STATE_MISMATCH",
+        field: "disputeState",
+        expected: expected.disputeState,
+        got: snapshot.disputeState
+      };
+    }
+  }
+  if (snapshot.seller.toLowerCase() !== expected.seller.toLowerCase()) {
+    return {
+      ok: false,
+      code: "SELLER_MISMATCH",
+      field: "seller",
+      expected: expected.seller,
+      got: snapshot.seller
+    };
+  }
+  if (snapshot.exchangeToken.toLowerCase() !== expected.exchangeToken.toLowerCase()) {
+    return {
+      ok: false,
+      code: "TOKEN_MISMATCH",
+      field: "exchangeToken",
+      expected: expected.exchangeToken,
+      got: snapshot.exchangeToken
+    };
+  }
+  if (snapshot.price !== expected.price) {
+    return {
+      ok: false,
+      code: "PRICE_MISMATCH",
+      field: "price",
+      expected: expected.price,
+      got: snapshot.price
+    };
+  }
+  return { ok: true };
+}
+async function verifyExchange(reader, exchangeId, expected, options = {}) {
+  const attempts = Math.max(1, Math.floor(options.attempts ?? 3));
+  const delayMs = Math.max(0, Math.floor(options.delayMs ?? 50));
+  let result = { ok: false, code: "EXCHANGE_NOT_FOUND" };
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const snapshot = await reader.read(exchangeId);
+    result = verifyExchangeSnapshot(snapshot, expected);
+    if (result.ok || !isRetryableVerifyResult(result) || attempt === attempts) {
+      return result;
+    }
+    if (delayMs > 0) {
+      await delay(delayMs);
+    }
+  }
+  return result;
+}
+function isRetryableVerifyResult(result) {
+  return !result.ok && (result.code === "EXCHANGE_NOT_FOUND" || result.code === "STATE_MISMATCH" || result.code === "DISPUTE_STATE_MISMATCH");
+}
+async function delay(ms) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// src/facilitator/errors.ts
+var FacilitatorHttpError = class extends Error {
+  constructor(message, init) {
+    super(message, init.cause !== void 0 ? { cause: init.cause } : void 0);
+    this.name = "FacilitatorHttpError";
+    this.code = init.code;
+    if (init.status !== void 0) this.status = init.status;
+    if (init.facilitatorCode !== void 0) this.facilitatorCode = init.facilitatorCode;
+  }
+};
+
+// src/handlers/commit-and-redeem.ts
+async function handleCommit(input, ctx) {
+  return await handleCommitImpl(input, ctx, {
+    expectedAction: "boson-createOfferAndCommit",
+    expectedState: x402Actions.ExchangeState.COMMITTED
+  });
+}
+async function handleCommitAndRedeem(input, ctx) {
+  return await handleCommitImpl(input, ctx, {
+    expectedAction: "boson-createOfferCommitAndRedeem",
+    expectedState: x402Actions.ExchangeState.REDEEMED
+  });
+}
+async function handleCommitImpl(input, ctx, expected) {
+  const decoded = decodeXPaymentHeader(input.paymentHeader);
+  if (!decoded.ok) {
+    const status = decoded.code === "MISSING_HEADER" ? 402 : 400;
+    return handlerErr(status, decoded.code, decoded.reason);
+  }
+  if (decoded.payload.payload.action !== expected.expectedAction) {
+    return handlerErr(
+      400,
+      "ACTION_ROUTE_MISMATCH",
+      `handler expected action ${expected.expectedAction}, got ${decoded.payload.payload.action}`,
+      {
+        expected: expected.expectedAction,
+        got: decoded.payload.payload.action
+      }
+    );
+  }
+  const channels = ctx.config.fulfillmentChannels ?? [];
+  const channelById = new Map(channels.map((c) => [c.id, c]));
+  const validation = await validatePaymentPayload({
+    payload: decoded.payload,
+    requirements: input.requirements,
+    chainId: ctx.config.chainId,
+    validateFulfillmentData: (option, data) => {
+      const channel = channelById.get(option);
+      if (channel === void 0) {
+        return {
+          ok: false,
+          reason: `fulfillment.option '${option}' has no registered channel adapter on this server`
+        };
+      }
+      try {
+        return channel.validate(data);
+      } catch (e) {
+        return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+      }
+    }
+  });
+  if (!validation.ok) {
+    return handlerErr(400, validation.code, validation.reason ?? `rule ${validation.rule} failed`, {
+      rule: validation.rule,
+      field: validation.field,
+      expected: validation.expected,
+      got: validation.got
+    });
+  }
+  let settleResult;
+  try {
+    settleResult = await ctx.facilitator.settle({
+      scheme: "escrow",
+      network: input.requirements.network,
+      payload: decoded.payload,
+      requirements: input.requirements
+    });
+  } catch (e) {
+    if (e instanceof FacilitatorHttpError) {
+      return handlerErr(502, "FACILITATOR_UNREACHABLE", e.message, {
+        code: e.code,
+        status: e.status,
+        facilitatorCode: e.facilitatorCode
+      });
+    }
+    throw e;
+  }
+  if (!settleResult.ok) {
+    return handlerErr(502, "FACILITATOR_REJECTED", settleResult.reason, {
+      facilitatorCode: settleResult.code
+    });
+  }
+  const verifyResult = await verifyExchange(
+    ctx.exchangeReader,
+    settleResult.exchangeId,
+    buildExpectedFromRequirements(input.requirements, expected.expectedState)
+  );
+  if (!verifyResult.ok) {
+    return handlerErr(
+      502,
+      `STATE_VERIFY_${verifyResult.code}`,
+      "post-settle state verification failed",
+      {
+        exchangeId: settleResult.exchangeId,
+        txHash: settleResult.txHash,
+        field: verifyResult.field,
+        expected: verifyResult.expected,
+        got: verifyResult.got
+      }
+    );
+  }
+  if (expected.expectedState === x402Actions.ExchangeState.COMMITTED) {
+    ctx.exchangeFulfillmentOptionStore.set(
+      settleResult.exchangeId,
+      input.requirements.fulfillment?.options.map((option) => option.id) ?? []
+    );
+  }
+  const warnings = [];
+  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()
+    };
+    ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, pending);
+    const channel = channelById.get(decoded.payload.fulfillment.option);
+    if (channel === void 0) {
+      const reason = "no channel adapter is registered";
+      ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+        ...pending,
+        error: reason
+      });
+      warnings.push({
+        code: "FULFILLMENT_COMMIT_DEFERRED",
+        reason: "atomic redeem succeeded on-chain, but no channel adapter is registered",
+        details: {
+          exchangeId: settleResult.exchangeId,
+          option: decoded.payload.fulfillment.option,
+          error: reason
+        }
+      });
+    } else {
+      try {
+        await channel.onCommit(settleResult.exchangeId, decoded.payload.fulfillment.data);
+        ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+      } catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+          ...pending,
+          error: reason
+        });
+        warnings.push({
+          code: "FULFILLMENT_COMMIT_DEFERRED",
+          reason: "atomic redeem succeeded on-chain, but the channel adapter rejected the data",
+          details: {
+            exchangeId: settleResult.exchangeId,
+            option: decoded.payload.fulfillment.option,
+            error: reason
+          }
+        });
+      }
+    }
+  }
+  const nextActions = emitNextActions(
+    {
+      exchangeId: settleResult.exchangeId,
+      exchangeState: expected.expectedState
+    },
+    ctx.config.channelRegistry,
+    ctx.config.facilitator.url
+  );
+  return handlerOk({
+    exchangeId: settleResult.exchangeId,
+    txHash: settleResult.txHash,
+    nextActions,
+    ...warnings.length > 0 ? { warnings } : {}
+  });
+}
+function buildExpectedFromRequirements(requirements, state) {
+  return {
+    state,
+    seller: requirements.offer.creator,
+    exchangeToken: requirements.asset,
+    price: requirements.amount
+  };
+}
+async function handlePerformAction(action, input, ctx) {
+  const reference = await ctx.exchangeReader.read(input.exchangeId);
+  if (reference === null) {
+    return handlerErr(
+      502,
+      "STATE_VERIFY_EXCHANGE_NOT_FOUND",
+      "pre-action exchange reference could not be read",
+      { action, exchangeId: input.exchangeId }
+    );
+  }
+  let result;
+  try {
+    result = await ctx.facilitator.performAction({
+      network: ctx.config.network,
+      escrowAddress: ctx.config.escrow,
+      exchangeId: input.exchangeId,
+      action,
+      signedPayload: input.signedPayload
+    });
+  } catch (e) {
+    if (e instanceof FacilitatorHttpError) {
+      return handlerErr(502, "FACILITATOR_UNREACHABLE", e.message, {
+        code: e.code,
+        status: e.status,
+        facilitatorCode: e.facilitatorCode
+      });
+    }
+    throw e;
+  }
+  if (!result.ok) {
+    return handlerErr(502, "FACILITATOR_REJECTED", result.reason, {
+      facilitatorCode: result.code
+    });
+  }
+  const postState = stateMachine.ACTION_POST_STATE[action];
+  const expected = {
+    state: postState.exchange,
+    ...postState.dispute !== void 0 ? { disputeState: postState.dispute } : {},
+    seller: reference.seller,
+    exchangeToken: reference.exchangeToken,
+    price: reference.price
+  };
+  const verifyResult = await verifyExchange(ctx.exchangeReader, input.exchangeId, expected);
+  if (!verifyResult.ok) {
+    return handlerErr(
+      502,
+      `STATE_VERIFY_${verifyResult.code}`,
+      "post-action state verification failed",
+      {
+        action,
+        exchangeId: input.exchangeId,
+        txHash: result.txHash,
+        field: verifyResult.field,
+        expected: verifyResult.expected,
+        got: verifyResult.got
+      }
+    );
+  }
+  const nextActions = postState.exchange === x402Actions.ExchangeState.DISPUTED && postState.dispute !== void 0 ? emitNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: x402Actions.ExchangeState.DISPUTED,
+      disputeState: postState.dispute
+    },
+    ctx.config.channelRegistry,
+    ctx.config.facilitator.url
+  ) : emitNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: postState.exchange
+    },
+    ctx.config.channelRegistry,
+    ctx.config.facilitator.url
+  );
+  return handlerOk({ txHash: result.txHash, nextActions });
+}
+async function handleRedeem(input, ctx) {
+  let redeemer;
+  try {
+    redeemer = x402Evm.decodeSignedPayload(input.signedPayload).from;
+  } catch (e) {
+    return handlerErr(
+      400,
+      "SIGNED_PAYLOAD_DECODE_FAILED",
+      e instanceof Error ? e.message : "signedPayload could not be decoded"
+    );
+  }
+  let resolvedChannel;
+  if (input.fulfillment !== void 0) {
+    const advertisedOptions = ctx.exchangeFulfillmentOptionStore.get(input.exchangeId);
+    if (advertisedOptions !== void 0 && !advertisedOptions.includes(input.fulfillment.option)) {
+      return handlerErr(
+        400,
+        "FULFILLMENT_OPTION_NOT_ADVERTISED",
+        `fulfillment.option '${input.fulfillment.option}' was not advertised for this exchange`,
+        { option: input.fulfillment.option, advertised: advertisedOptions }
+      );
+    }
+    const channels = ctx.config.fulfillmentChannels;
+    if (channels === void 0) {
+      return handlerErr(
+        400,
+        "FULFILLMENT_CHANNELS_NOT_CONFIGURED",
+        "server received redeem-time fulfillment data but has no fulfillmentChannels registered"
+      );
+    }
+    const channel = channels.find((c) => c.id === input.fulfillment.option);
+    if (channel === void 0) {
+      return handlerErr(
+        400,
+        "FULFILLMENT_OPTION_UNKNOWN",
+        `fulfillment.option '${input.fulfillment.option}' is not registered with the server`,
+        { option: input.fulfillment.option, registered: channels.map((c) => c.id) }
+      );
+    }
+    let validation;
+    try {
+      validation = channel.validate(input.fulfillment.data);
+    } catch (e) {
+      return handlerErr(400, "FULFILLMENT_DATA_INVALID", errorMessage(e), {
+        option: input.fulfillment.option
+      });
+    }
+    if (!validation.ok) {
+      return handlerErr(400, "FULFILLMENT_DATA_INVALID", validation.reason, {
+        option: input.fulfillment.option
+      });
+    }
+    resolvedChannel = channel;
+  }
+  const result = await handlePerformAction("boson-redeem", input, ctx);
+  if (!result.ok) return result;
+  let warning;
+  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()
+    };
+    ctx.fulfillmentRecoveryStore.set(input.exchangeId, pending);
+    try {
+      await resolvedChannel.onCommit(input.exchangeId, input.fulfillment.data);
+      ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+    } catch (e) {
+      const reason = errorMessage(e);
+      ctx.fulfillmentRecoveryStore.set(input.exchangeId, { ...pending, error: reason });
+      warning = {
+        code: "FULFILLMENT_UPDATE_DEFERRED",
+        reason: "redeem succeeded on-chain, but the server could not persist the fulfillment update",
+        details: {
+          exchangeId: input.exchangeId,
+          option: input.fulfillment.option,
+          error: reason
+        }
+      };
+    }
+  }
+  ctx.exchangeFulfillmentOptionStore.delete(input.exchangeId);
+  if (warning !== void 0) {
+    return {
+      ...result,
+      body: {
+        ...result.body,
+        warnings: [...result.body.warnings ?? [], warning]
+      }
+    };
+  }
+  return result;
+}
+function errorMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+var handleComplete = (input, ctx) => handlePerformAction("boson-completeExchange", input, ctx);
+var handleDisputeRaise = (input, ctx) => handlePerformAction("boson-raiseDispute", input, ctx);
+var handleDisputeResolve = (input, ctx) => handlePerformAction("boson-resolveDispute", input, ctx);
+var handleDisputeRetract = (input, ctx) => handlePerformAction("boson-retractDispute", input, ctx);
+var handleDisputeEscalate = (input, ctx) => handlePerformAction("boson-escalateDispute", input, ctx);
+var DECIMAL_UINT_RE = escrow.DECIMAL_UINT;
+var ADDRESS_RE = escrow.ADDRESS;
+var HEX_BYTES_RE = /^0x([0-9a-fA-F]{2})*$/;
+
+// src/handlers/resolve-entity.ts
+async function resolveEntityId(coreSdk, input) {
+  const address = input.address.toLowerCase();
+  let sellers = [];
+  let buyers = [];
+  try {
+    [sellers, buyers] = await Promise.all([
+      input.role === "buyer" ? Promise.resolve([]) : coreSdk.getSellersByAddress(address),
+      input.role === "seller" ? Promise.resolve([]) : coreSdk.getBuyers({ buyersFilter: { wallet: address } })
+    ]);
+  } catch (e) {
+    return {
+      ok: false,
+      code: "SUBGRAPH_FAILURE",
+      reason: e instanceof Error ? e.message : "subgraph lookup failed"
+    };
+  }
+  const sellerIds = sellers.map((s) => s.id);
+  const buyerIds = buyers.map((b) => b.id);
+  if (input.role === "seller") {
+    if (sellerIds.length === 0) {
+      return {
+        ok: false,
+        code: "NOT_FOUND",
+        reason: `no seller entity found for address ${address}`
+      };
+    }
+    if (sellerIds.length > 1) {
+      return {
+        ok: false,
+        code: "AMBIGUOUS",
+        reason: `address ${address} resolves to multiple seller entities (ids ${sellerIds.join(", ")}); pass entityId to disambiguate`,
+        sellerIds
+      };
+    }
+    return { ok: true, entityId: sellerIds[0], role: "seller" };
+  }
+  if (input.role === "buyer") {
+    if (buyerIds.length === 0) {
+      return {
+        ok: false,
+        code: "NOT_FOUND",
+        reason: `no buyer entity found for address ${address}`
+      };
+    }
+    if (buyerIds.length > 1) {
+      return {
+        ok: false,
+        code: "AMBIGUOUS",
+        reason: `address ${address} resolves to multiple buyer entities (ids ${buyerIds.join(", ")}); pass entityId to disambiguate`,
+        buyerIds
+      };
+    }
+    return { ok: true, entityId: buyerIds[0], role: "buyer" };
+  }
+  const totalMatches = sellerIds.length + buyerIds.length;
+  if (totalMatches === 0) {
+    return {
+      ok: false,
+      code: "NOT_FOUND",
+      reason: `no seller or buyer entity found for address ${address}`
+    };
+  }
+  if (totalMatches > 1) {
+    return {
+      ok: false,
+      code: "AMBIGUOUS",
+      reason: `address ${address} resolves to ${describeMatches(sellerIds, buyerIds)}; pass role and/or entityId to disambiguate`,
+      ...sellerIds.length > 0 ? { sellerIds } : {},
+      ...buyerIds.length > 0 ? { buyerIds } : {}
+    };
+  }
+  if (sellerIds.length === 1) return { ok: true, entityId: sellerIds[0], role: "seller" };
+  return { ok: true, entityId: buyerIds[0], role: "buyer" };
+}
+function describeMatches(sellerIds, buyerIds) {
+  const parts = [];
+  if (sellerIds.length > 0) {
+    parts.push(
+      sellerIds.length === 1 ? `seller (id ${sellerIds[0]})` : `${sellerIds.length} sellers (ids ${sellerIds.join(", ")})`
+    );
+  }
+  if (buyerIds.length > 0) {
+    parts.push(
+      buyerIds.length === 1 ? `buyer (id ${buyerIds[0]})` : `${buyerIds.length} buyers (ids ${buyerIds.join(", ")})`
+    );
+  }
+  return parts.join(" and ");
+}
+
+// src/handlers/withdraw-funds.ts
+async function handleWithdrawFunds(input, ctx) {
+  let entityId;
+  let role;
+  if ("entityId" in input) {
+    if (!DECIMAL_UINT_RE.test(input.entityId)) {
+      return handlerErr(
+        400,
+        "INVALID_ENTITY_ID",
+        `entityId must be a decimal uint256 string, got "${input.entityId}"`
+      );
+    }
+    entityId = input.entityId;
+  } else {
+    if (!ADDRESS_RE.test(input.address)) {
+      return handlerErr(
+        400,
+        "INVALID_ADDRESS",
+        `address must be a 20-byte 0x-prefixed hex string, got "${input.address}"`
+      );
+    }
+    const resolved = await resolveEntityId(ctx.coreSdkRead, {
+      address: input.address,
+      ...input.role !== void 0 ? { role: input.role } : {}
+    });
+    if (!resolved.ok) {
+      const status = resolved.code === "NOT_FOUND" ? 404 : resolved.code === "AMBIGUOUS" ? 409 : 502;
+      const details = resolved.code === "AMBIGUOUS" ? {
+        ...resolved.sellerIds !== void 0 ? { sellerIds: resolved.sellerIds } : {},
+        ...resolved.buyerIds !== void 0 ? { buyerIds: resolved.buyerIds } : {}
+      } : void 0;
+      return handlerErr(status, resolved.code, resolved.reason, details);
+    }
+    entityId = resolved.entityId;
+    role = resolved.role;
+  }
+  let result;
+  try {
+    result = await ctx.facilitator.performAction({
+      network: ctx.config.network,
+      escrowAddress: ctx.config.escrow,
+      entityId,
+      action: "boson-withdrawFunds",
+      signedPayload: input.signedPayload
+    });
+  } catch (e) {
+    if (e instanceof FacilitatorHttpError) {
+      return handlerErr(502, "FACILITATOR_UNREACHABLE", e.message, {
+        code: e.code,
+        status: e.status,
+        facilitatorCode: e.facilitatorCode
+      });
+    }
+    throw e;
+  }
+  if (!result.ok) {
+    return handlerErr(502, "FACILITATOR_REJECTED", result.reason, {
+      facilitatorCode: result.code
+    });
+  }
+  return plainHandlerOk({
+    txHash: result.txHash,
+    entityId,
+    ...role !== void 0 ? { role } : {}
+  });
+}
+
+// src/handlers/available-funds.ts
+async function handleGetAvailableFunds(query, ctx) {
+  let entityId;
+  let role;
+  if ("entityId" in query) {
+    if (!DECIMAL_UINT_RE.test(query.entityId)) {
+      return handlerErr(
+        400,
+        "INVALID_ENTITY_ID",
+        `entityId must be a decimal uint256 string, got "${query.entityId}"`
+      );
+    }
+    entityId = query.entityId;
+  } else {
+    if (!ADDRESS_RE.test(query.address)) {
+      return handlerErr(
+        400,
+        "INVALID_ADDRESS",
+        `address must be a 20-byte 0x-prefixed hex string, got "${query.address}"`
+      );
+    }
+    const resolved = await resolveEntityId(ctx.coreSdkRead, {
+      address: query.address,
+      ...query.role !== void 0 ? { role: query.role } : {}
+    });
+    if (!resolved.ok) {
+      const status = resolved.code === "NOT_FOUND" ? 404 : resolved.code === "AMBIGUOUS" ? 409 : 502;
+      return handlerErr(status, resolved.code, resolved.reason, omitErrorMetadata(resolved));
+    }
+    entityId = resolved.entityId;
+    role = resolved.role;
+  }
+  let raw;
+  try {
+    raw = await ctx.coreSdkRead.getFunds({ fundsFilter: { accountId: entityId } });
+  } catch (e) {
+    return handlerErr(
+      502,
+      "SUBGRAPH_FAILURE",
+      e instanceof Error ? e.message : "subgraph getFunds lookup failed"
+    );
+  }
+  const funds = raw.map((entry) => ({
+    tokenAddress: entry.token.address,
+    tokenSymbol: entry.token.symbol,
+    tokenName: entry.token.name,
+    decimals: Number(entry.token.decimals),
+    availableAmount: entry.availableAmount
+  }));
+  return plainHandlerOk({
+    entityId,
+    ...role !== void 0 ? { role } : {},
+    funds
+  });
+}
+function omitErrorMetadata(resolved) {
+  if (resolved.code !== "AMBIGUOUS") return void 0;
+  const details = {};
+  if (resolved.sellerIds !== void 0) details.sellerIds = resolved.sellerIds;
+  if (resolved.buyerIds !== void 0) details.buyerIds = resolved.buyerIds;
+  return Object.keys(details).length > 0 ? details : void 0;
+}
+
+exports.ADDRESS_RE = ADDRESS_RE;
+exports.DECIMAL_UINT_RE = DECIMAL_UINT_RE;
+exports.HEX_BYTES_RE = HEX_BYTES_RE;
+exports.emitNextActions = emitNextActions;
+exports.handleCommit = handleCommit;
+exports.handleCommitAndRedeem = handleCommitAndRedeem;
+exports.handleComplete = handleComplete;
+exports.handleDisputeEscalate = handleDisputeEscalate;
+exports.handleDisputeRaise = handleDisputeRaise;
+exports.handleDisputeResolve = handleDisputeResolve;
+exports.handleDisputeRetract = handleDisputeRetract;
+exports.handleGetAvailableFunds = handleGetAvailableFunds;
+exports.handlePerformAction = handlePerformAction;
+exports.handleRedeem = handleRedeem;
+exports.handleWithdrawFunds = handleWithdrawFunds;
+exports.handlerErr = handlerErr;
+exports.handlerOk = handlerOk;
+exports.plainHandlerOk = plainHandlerOk;
+exports.resolveEntityId = resolveEntityId;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map