@bosonprotocol/x402-server 0.1.0-alpha-0

package/dist/esm/chunk-Y5HFLCAT.js

@@ -0,0 +1,657 @@
+import { FacilitatorHttpError } from './chunk-PU5Y7FZG.js';
+import { verifyExchange } from './chunk-4NQ3VKC3.js';
+import { decodeXPaymentHeader, validatePaymentPayload } from './chunk-CGVXQX5V.js';
+import { ExchangeState, deriveNextActions } from '@bosonprotocol/x402-actions';
+import { ACTION_POST_STATE } from '@bosonprotocol/x402-core/state-machine';
+import { decodeSignedPayload } from '@bosonprotocol/x402-evm';
+import { ADDRESS, DECIMAL_UINT } from '@bosonprotocol/x402-core/schemes/escrow';
+
+// 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 === ExchangeState.DISPUTED ? deriveNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: ExchangeState.DISPUTED,
+      disputeState: input.disputeState
+    },
+    registry
+  ) : 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 };
+}
+
+// src/handlers/commit-and-redeem.ts
+async function handleCommit(input, ctx) {
+  return await handleCommitImpl(input, ctx, {
+    expectedAction: "boson-createOfferAndCommit",
+    expectedState: ExchangeState.COMMITTED
+  });
+}
+async function handleCommitAndRedeem(input, ctx) {
+  return await handleCommitImpl(input, ctx, {
+    expectedAction: "boson-createOfferCommitAndRedeem",
+    expectedState: 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 === ExchangeState.COMMITTED) {
+    ctx.exchangeFulfillmentOptionStore.set(
+      settleResult.exchangeId,
+      input.requirements.fulfillment?.options.map((option) => option.id) ?? []
+    );
+  }
+  const warnings = [];
+  if (expected.expectedState === 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 = 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 === ExchangeState.DISPUTED && postState.dispute !== void 0 ? emitNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: 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 = 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 = DECIMAL_UINT;
+var ADDRESS_RE = 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;
+}
+
+export { ADDRESS_RE, DECIMAL_UINT_RE, HEX_BYTES_RE, emitNextActions, handleCommit, handleCommitAndRedeem, handleComplete, handleDisputeEscalate, handleDisputeRaise, handleDisputeResolve, handleDisputeRetract, handleGetAvailableFunds, handlePerformAction, handleRedeem, handleWithdrawFunds, handlerErr, handlerOk, plainHandlerOk, resolveEntityId, stampFacilitatorEndpoints };
+//# sourceMappingURL=chunk-Y5HFLCAT.js.map
+//# sourceMappingURL=chunk-Y5HFLCAT.js.map