@absol-labs/agent 0.11.0 → 0.12.0-rc.1

package/src/gateway/x402-opener-mode.ts

@@ -0,0 +1,974 @@
+import {
+  HTTPFacilitatorClient,
+  SETTLEMENT_OVERRIDES_HEADER,
+  withPrivateCacheControl,
+  x402HTTPResourceServer,
+  x402ResourceServer,
+  type FacilitatorClient,
+  type HTTPAdapter,
+  type HTTPProcessResult,
+  type HTTPRequestContext,
+  type HTTPResponseInstructions,
+  type ProcessSettleResultResponse,
+  type RouteConfig,
+  type SettleResultContext,
+} from "@x402/core/server";
+import type { Network } from "@x402/core/types";
+import { decodePaymentSignatureHeader } from "@x402/core/http";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import {
+  createPublicClient,
+  formatUnits,
+  getAddress,
+  http,
+  isAddress,
+  type Address,
+  type PublicClient,
+} from "viem";
+
+import { x402StreamOpenerFactoryAbi } from "../x402-opener/abi.js";
+import {
+  RegistryListingResolver,
+  type OperatorSignedListingResolver,
+} from "../x402-opener/listing-resolver.js";
+import { readOpenerFacilitatorMarker } from "../x402-opener/scheme.js";
+import {
+  assertValidPrice,
+  assertValidTerms,
+  chainIdFromNetwork,
+  assertSchemaDeclaration,
+  DEFAULT_OPENER_DOCS_URL,
+  isHttpLink,
+  OPENER_EXTRA_KEY,
+  OPENER_SCHEME,
+  termsToExtra,
+  termsTuple,
+  type OpenerTerms,
+  type X402SchemaDeclaration,
+} from "../x402-opener/terms.js";
+
+/**
+ * The gateway's x402 v2 mode (metrik-agent#116): answer an uncapabilitied
+ * request with a standard x402 v2 `402` whose `payTo` is the listing's
+ * `X402StreamOpener` address, and settle every accepted payment INTO a
+ * `StreamEscrowV2` stream through the Metrik opener facilitator.
+ *
+ * The wire format is the official `@x402/core` resource server's, not a
+ * re-implementation: `x402HTTPResourceServer` builds `PAYMENT-REQUIRED`,
+ * matches `PAYMENT-SIGNATURE`, verifies and settles through the facilitator and
+ * builds `PAYMENT-RESPONSE`.
+ *
+ * ## The opener payTo must ONLY ever be settled by the Metrik opener facilitator
+ *
+ * A stock x402 `exact` facilitator settles by calling
+ * `USDC.transferWithAuthorization(to = payTo)` directly. Pointed at an opener,
+ * that strands 100% of the payer's funds in the opener permanently (there is,
+ * deliberately, no sweep). So this mode:
+ *
+ * - refuses to START unless the configured facilitator's `GET /supported`
+ *   advertises the opener marker for exactly this factory, escrow, token and
+ *   chain; and re-checks that marker on a timer, failing CLOSED (503, no
+ *   `payTo` quoted, nothing verified or settled) whenever it cannot;
+ * - uses exactly one facilitator client, never a fallback list;
+ * - registers no discovery (Bazaar) extension and never submits the route to
+ *   any catalog. When (and only when) the operator configures an input/output
+ *   schema, it is DECLARED in the 402 in the standard `extensions.bazaar`
+ *   shape so a client can read what to send; only the Metrik opener
+ *   facilitator ever sees the payment, and it catalogs nothing;
+ * - states plainly in the 402 `description` what is bought (the stream
+ *   window, rate, that the seller earns only verified seconds, and that
+ *   unearned money is refundable without ETH through the facilitator's
+ *   refund relay) and refuses to start unless that facilitator advertises
+ *   the relay (`refundRelay: true` in its marker) — the 402 never promises a
+ *   refund path that is not there. Refunds are not automatic;
+ * - authenticates the opener only as `factory.predict(terms)` — never by code
+ *   or codehash, which a clone outside the factory can reproduce;
+ * - serves one EIP-3009 authorization at most once: a `PAYMENT-SIGNATURE`
+ *   whose authorization is in flight or already settled gets `409` WITHOUT an
+ *   upstream call (in-memory, per gateway instance). A retry after
+ *   `settlement_pending` is let through so it can reconcile;
+ * - refuses to start if its price is below the facilitator's advertised
+ *   minimum, or if its facilitator timeout would not outlast the facilitator's
+ *   receipt wait.
+ */
+
+/** How long a successful `/supported` marker check is trusted, seconds. */
+export const DEFAULT_FACILITATOR_MARKER_TTL_SECONDS = 300;
+
+/** Default per-request facilitator HTTP timeout. Must outlast its receipt wait. */
+export const DEFAULT_FACILITATOR_TIMEOUT_MS = 120_000;
+
+/** Headroom the facilitator timeout must leave over the facilitator's receipt wait. */
+const FACILITATOR_TIMEOUT_HEADROOM_MS = 30_000;
+
+export interface GatewayX402OpenerModeConfig {
+  /** Base URL of the Metrik opener facilitator (e.g. `https://facilitator.example`). */
+  readonly facilitatorUrl: string;
+  /** Bearer token the facilitator requires on `/settle`. */
+  readonly facilitatorToken: string;
+  /** CAIP-2 network (`eip155:<chainId>`), as the registry gives it. */
+  readonly network: Network;
+  readonly factoryAddress: Address;
+  /** The escrow this gateway checks streams against; the factory must point at it. */
+  readonly escrowAddress: Address;
+  /** Settlement token; must equal the factory's. */
+  readonly asset: Address;
+  /** EIP-712 domain of the token (Circle USDC: `USDC` / `2`). */
+  readonly assetName: string;
+  readonly assetVersion: string;
+  /** Opener terms. `operator` + `serviceRef` must resolve to one operator-signed listing. */
+  readonly terms: OpenerTerms;
+  /** Price per paid request in token base units. Becomes the stream deposit. */
+  readonly price: bigint;
+  /** Authorization validity the client signs for. Default 300s. */
+  readonly maxTimeoutSeconds?: number;
+  /** Public origin clients reach this gateway at, for the 402 `resource.url`. */
+  readonly resourceBaseUrl?: string;
+  /**
+   * What the service does, in one sentence. Prefixed to the fixed disclosure
+   * of what the payment buys ({@link describeOpenerPurchase}); it can never
+   * replace that disclosure.
+   */
+  readonly description?: string;
+  /**
+   * Public base URL of the facilitator's refund relay (`/streams/:streamId`).
+   * Default `facilitatorUrl`. When different, its `/supported` must advertise
+   * the same opener marker with `refundRelay: true` (checked at startup).
+   */
+  readonly refundBaseUrl?: string;
+  /** Docs link carried in the 402. Default {@link DEFAULT_OPENER_DOCS_URL}. */
+  readonly docsUrl?: string;
+  /** Token decimals for the human-readable amounts in the description. Default 6 (USDC). */
+  readonly assetDecimals?: number;
+  /**
+   * Optional input/output schema, declared in the 402 as
+   * `extensions.bazaar` (`{info: {input, output}, schema}`). Declared only;
+   * never registered with any discovery catalog.
+   */
+  readonly schemaDeclaration?: X402SchemaDeclaration;
+  /** Registry used to prove the listing at startup. Default the public registry. */
+  readonly registryUrl?: string;
+  readonly markerTtlSeconds?: number;
+  /**
+   * Per-request facilitator HTTP timeout, ms. Default
+   * {@link DEFAULT_FACILITATOR_TIMEOUT_MS}. Must exceed the facilitator's
+   * advertised receipt timeout by 30 s, so the gateway never gives up on a
+   * settlement the facilitator is still waiting for.
+   */
+  readonly facilitatorTimeoutMs?: number;
+}
+
+/**
+ * The plain statement of what one payment buys, used as the 402 resource
+ * `description`. It names the window, the rate, that the seller earns only for
+ * seconds Metrik's verifier confirms, and where unearned money is refundable
+ * without ETH. It says that refunds are not automatic, because they are not:
+ * someone has to call the refund relay.
+ */
+export function describeOpenerPurchase(input: {
+  readonly terms: OpenerTerms;
+  readonly price: bigint;
+  readonly assetDecimals: number;
+  readonly assetSymbol: string;
+  /** Refund URL template containing `{streamId}`. */
+  readonly refundUrlTemplate: string;
+  readonly docsUrl: string;
+  readonly serviceDescription?: string;
+}): string {
+  const amount = (value: bigint) =>
+    `${formatUnits(value, input.assetDecimals)} ${input.assetSymbol}`;
+  const { ratePerSecond, maxDuration } = input.terms;
+  const cap =
+    input.price < ratePerSecond * maxDuration
+      ? ` (the seller can earn at most ${amount(input.price)})`
+      : "";
+  const prefix =
+    input.serviceDescription === undefined ||
+    input.serviceDescription.trim().length === 0
+      ? ""
+      : `${input.serviceDescription.trim()} `;
+  return (
+    `${prefix}Pays for one call. Your payment of ${amount(input.price)} funds a Metrik escrow stream of ` +
+    `${maxDuration.toString()} seconds at ${amount(ratePerSecond)}/s${cap}; ` +
+    "the seller earns only for seconds Metrik's verifier confirms the service is delivering, " +
+    `and anything unearned is refundable to you (no ETH needed) via ${input.refundUrlTemplate}. ` +
+    "Refunds are not automatic: close the stream and reclaim there, using the streamId from the PAYMENT-RESPONSE. " +
+    `Docs: ${input.docsUrl}`
+  );
+}
+
+/**
+ * The stock `exact` server scheme, plus ONE additive settlement enrichment:
+ * the successful `PAYMENT-RESPONSE` gets `extra.metrikStreamOpener.refundUrl`
+ * for the opened stream. It never touches the settlement outcome fields
+ * (`@x402/core` enforces that the enrichment is additive).
+ */
+class OpenerExactServerScheme extends ExactEvmScheme {
+  constructor(private readonly refundBaseUrl: string) {
+    super();
+  }
+
+  enrichSettlementResponse = async (
+    context: SettleResultContext,
+  ): Promise<Record<string, unknown> | undefined> => {
+    if (!context.result.success) return undefined;
+    const opened = context.result.extra?.[OPENER_EXTRA_KEY] as
+      | Record<string, unknown>
+      | undefined;
+    const streamId = opened?.streamId;
+    if (
+      typeof streamId !== "string" ||
+      !/^0x[0-9a-fA-F]{64}$/.test(streamId) ||
+      opened?.refundUrl !== undefined
+    ) {
+      return undefined;
+    }
+    return {
+      [OPENER_EXTRA_KEY]: {
+        refundUrl: `${this.refundBaseUrl}/streams/${streamId.toLowerCase()}`,
+      },
+    };
+  };
+}
+
+export interface GatewayX402OpenerModeDeps {
+  /** Read client for the factory. Default built from `rpcUrl`. */
+  readonly publicClient?: PublicClient;
+  readonly rpcUrl?: string;
+  readonly listingResolver?: OperatorSignedListingResolver;
+  /** Override the facilitator transport (tests). Default {@link HTTPFacilitatorClient}. */
+  readonly facilitatorClient?: FacilitatorClient;
+  readonly now?: () => number;
+  /** HTTP client for checking a separate `refundBaseUrl`. Default global fetch. */
+  readonly fetch?: typeof fetch;
+}
+
+export interface GatewayX402OpenerMode {
+  /** The predicted opener address quoted as `payTo`. */
+  readonly payTo: Address;
+  readonly network: Network;
+  readonly terms: OpenerTerms;
+  readonly price: bigint;
+  readonly resourceBaseUrl: string | undefined;
+  /** The 402 `description` (what the payment buys). */
+  readonly description: string;
+  /** Refund relay base; a stream's refund page is `${refundBaseUrl}/streams/:streamId`. */
+  readonly refundBaseUrl: string;
+  readonly httpServer: x402HTTPResourceServer;
+  /** One-use accounting of authorizations this gateway has seen. */
+  readonly authorizations: GatewayAuthorizationLedger;
+  /**
+   * Resolves once the facilitator is proven to be the Metrik opener
+   * facilitator for this factory (cached for the marker TTL) and the resource
+   * server is initialized. Rejects otherwise — callers must fail closed.
+   */
+  ready(): Promise<void>;
+  /** Serves one x402-mode request over the supplied transport. Never throws. */
+  handle(io: X402GatewayRequestIO): Promise<void>;
+}
+
+/** JSON reasons the x402 path can answer with, beyond the gateway's own. */
+export type X402GatewayResponseReason =
+  | "x402-facilitator-unavailable"
+  | "x402-settlement-failed"
+  | "internal-error"
+  | "upstream-unavailable"
+  | "x402-payment-already-used";
+
+export interface X402UpstreamResult {
+  readonly status: number;
+  readonly headers: Record<string, string>;
+  readonly body: Buffer;
+}
+
+/** The transport the HTTP server hands the x402 path. */
+export interface X402GatewayRequestIO {
+  readonly requestUrl: URL;
+  readonly method: string;
+  /** Lower-cased request headers. */
+  readonly headers: Readonly<Record<string, string | undefined>>;
+  /** Proxies the request upstream (payment headers stripped) and buffers the response. */
+  callUpstream(): Promise<X402UpstreamResult>;
+  writeJson(status: number, reason: X402GatewayResponseReason): void;
+  write(
+    status: number,
+    headers: Record<string, string>,
+    body: Buffer | string,
+  ): void;
+  logError(context: string, error: unknown): void;
+}
+
+const PAYMENT_SIGNATURE_HEADER = "payment-signature";
+
+/**
+ * Per-gateway, in-memory record of EIP-3009 authorizations (chain + asset +
+ * payer + nonce): `in-flight` while a request is being verified/served/
+ * settled, `pending` after a `settlement_pending` (a retry may reconcile), and
+ * `settled` once a success was delivered. In-flight and settled
+ * authorizations are refused before the upstream is ever called. Entries are
+ * dropped once the authorization's `validBefore` has passed (plus a grace).
+ */
+export class GatewayAuthorizationLedger {
+  private readonly entries = new Map<
+    string,
+    { state: "in-flight" | "pending" | "settled"; validBefore: bigint }
+  >();
+
+  constructor(
+    private readonly now: () => number,
+    private readonly maxEntries = 100_000,
+  ) {}
+
+  /** Claims the authorization for one request; false if it is in flight or settled. */
+  claim(key: string, validBefore: bigint): boolean {
+    this.prune();
+    const entry = this.entries.get(key);
+    if (entry !== undefined && entry.state !== "pending") return false;
+    if (entry === undefined && this.entries.size >= this.maxEntries)
+      return false;
+    this.entries.set(key, { state: "in-flight", validBefore });
+    return true;
+  }
+
+  release(key: string): void {
+    this.entries.delete(key);
+  }
+
+  markPending(key: string, validBefore: bigint): void {
+    this.entries.set(key, { state: "pending", validBefore });
+  }
+
+  markSettled(key: string, validBefore: bigint): void {
+    this.entries.set(key, { state: "settled", validBefore });
+  }
+
+  private prune(): void {
+    const now = BigInt(this.now());
+    for (const [key, entry] of this.entries) {
+      if (entry.state !== "in-flight" && entry.validBefore + 600n < now) {
+        this.entries.delete(key);
+      }
+    }
+  }
+}
+
+/** Ledger key for a `PAYMENT-SIGNATURE`, or undefined if it does not decode. */
+function authorizationKey(
+  header: string,
+): { readonly key: string; readonly validBefore: bigint } | undefined {
+  try {
+    const payload = decodePaymentSignatureHeader(header);
+    const authorization = (
+      payload.payload as {
+        authorization?: {
+          from?: unknown;
+          nonce?: unknown;
+          validBefore?: unknown;
+        };
+      }
+    ).authorization;
+    const network = payload.accepted?.network;
+    const asset = payload.accepted?.asset;
+    if (
+      typeof authorization?.from !== "string" ||
+      typeof authorization.nonce !== "string" ||
+      typeof authorization.validBefore !== "string" ||
+      !/^\d+$/.test(authorization.validBefore) ||
+      typeof network !== "string" ||
+      typeof asset !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      key: [
+        network,
+        asset.toLowerCase(),
+        authorization.from.toLowerCase(),
+        authorization.nonce.toLowerCase(),
+      ].join(":"),
+      validBefore: BigInt(authorization.validBefore),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export class X402OpenerModeConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "X402OpenerModeConfigError";
+  }
+}
+
+export class X402OpenerFacilitatorUnverifiedError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "X402OpenerFacilitatorUnverifiedError";
+  }
+}
+
+/**
+ * Builds the x402 mode and proves, before returning, every fact it will quote:
+ * valid terms and price, one operator-signed listing for the terms, the
+ * factory's escrow and token, the predicted `payTo`, and the facilitator's
+ * opener marker. Throws on any doubt; the gateway then refuses to start.
+ */
+export async function buildGatewayX402OpenerMode(
+  config: GatewayX402OpenerModeConfig,
+  deps: GatewayX402OpenerModeDeps = {},
+): Promise<GatewayX402OpenerMode> {
+  try {
+    assertValidTerms(config.terms);
+    assertValidPrice(config.price, config.terms);
+  } catch (error) {
+    throw new X402OpenerModeConfigError(
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+  const chainId = chainIdFromNetwork(config.network);
+  for (const [name, value] of [
+    ["factoryAddress", config.factoryAddress],
+    ["escrowAddress", config.escrowAddress],
+    ["asset", config.asset],
+  ] as const) {
+    if (!isAddress(value)) {
+      throw new X402OpenerModeConfigError(`${name} must be an EVM address`);
+    }
+  }
+  const maxTimeoutSeconds = config.maxTimeoutSeconds ?? 300;
+  if (!Number.isInteger(maxTimeoutSeconds) || maxTimeoutSeconds < 30) {
+    throw new X402OpenerModeConfigError(
+      "maxTimeoutSeconds must be an integer >= 30",
+    );
+  }
+  if (config.facilitatorToken.length === 0) {
+    throw new X402OpenerModeConfigError("facilitatorToken is required");
+  }
+  if (config.resourceBaseUrl !== undefined) {
+    // eslint-disable-next-line no-new -- validates the URL is well-formed.
+    new URL(config.resourceBaseUrl);
+  }
+  const refundBaseUrl = (config.refundBaseUrl ?? config.facilitatorUrl).replace(
+    /\/+$/,
+    "",
+  );
+  const docsUrl = config.docsUrl ?? DEFAULT_OPENER_DOCS_URL;
+  for (const [name, value] of [
+    ["refundBaseUrl", refundBaseUrl],
+    ["docsUrl", docsUrl],
+  ] as const) {
+    if (!isHttpLink(value)) {
+      throw new X402OpenerModeConfigError(`${name} must be an http(s) URL`);
+    }
+  }
+  const assetDecimals = config.assetDecimals ?? 6;
+  if (
+    !Number.isInteger(assetDecimals) ||
+    assetDecimals < 0 ||
+    assetDecimals > 36
+  ) {
+    throw new X402OpenerModeConfigError(
+      "assetDecimals must be an integer in [0, 36]",
+    );
+  }
+  if (config.schemaDeclaration !== undefined) {
+    try {
+      assertSchemaDeclaration(config.schemaDeclaration);
+    } catch (error) {
+      throw new X402OpenerModeConfigError(
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
+  const publicClient =
+    deps.publicClient ??
+    (deps.rpcUrl === undefined
+      ? undefined
+      : createPublicClient({ transport: http(deps.rpcUrl) }));
+  if (publicClient === undefined) {
+    throw new X402OpenerModeConfigError(
+      "an RPC (publicClient or rpcUrl) is required to predict the opener address",
+    );
+  }
+  const rpcChainId = await publicClient.getChainId();
+  if (rpcChainId !== chainId) {
+    throw new X402OpenerModeConfigError(
+      `RPC chain id ${rpcChainId} does not match network ${config.network}`,
+    );
+  }
+
+  const factory = getAddress(config.factoryAddress);
+  const escrow = getAddress(config.escrowAddress);
+  const asset = getAddress(config.asset);
+  const [factoryEscrow, factoryUsdc, predicted] = await Promise.all([
+    publicClient.readContract({
+      address: factory,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "escrow",
+    }),
+    publicClient.readContract({
+      address: factory,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "usdc",
+    }),
+    publicClient.readContract({
+      address: factory,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "predict",
+      args: [termsTuple(config.terms)],
+    }),
+  ]);
+  if (getAddress(factoryEscrow) !== escrow) {
+    throw new X402OpenerModeConfigError(
+      `factory ${factory} settles into ${factoryEscrow}, not this gateway's escrow ${escrow}`,
+    );
+  }
+  if (getAddress(factoryUsdc) !== asset) {
+    throw new X402OpenerModeConfigError(
+      `factory token ${factoryUsdc} is not the configured asset ${asset}`,
+    );
+  }
+  const payTo = getAddress(predicted);
+
+  const resolver =
+    deps.listingResolver ??
+    new RegistryListingResolver(
+      config.registryUrl === undefined
+        ? {}
+        : { registryUrl: config.registryUrl },
+    );
+  const listing = await resolver.resolve(config.terms);
+  if (!listing.ok) {
+    throw new X402OpenerModeConfigError(
+      `listing check failed (${listing.reason}): ${listing.message}`,
+    );
+  }
+
+  const facilitatorTimeoutMs =
+    config.facilitatorTimeoutMs ?? DEFAULT_FACILITATOR_TIMEOUT_MS;
+  if (!Number.isInteger(facilitatorTimeoutMs) || facilitatorTimeoutMs <= 0) {
+    throw new X402OpenerModeConfigError(
+      "facilitatorTimeoutMs must be a positive integer",
+    );
+  }
+  const facilitatorClient =
+    deps.facilitatorClient ??
+    new HTTPFacilitatorClient({
+      url: config.facilitatorUrl,
+      timeoutMs: facilitatorTimeoutMs,
+      createAuthHeaders: async () => {
+        const headers = { Authorization: `Bearer ${config.facilitatorToken}` };
+        return { verify: headers, settle: headers, supported: headers };
+      },
+    });
+
+  const now = deps.now ?? (() => Math.floor(Date.now() / 1000));
+  const markerTtl =
+    config.markerTtlSeconds ?? DEFAULT_FACILITATOR_MARKER_TTL_SECONDS;
+  let markerCheckedAt: number | undefined;
+  const checkMarker = async (): Promise<void> => {
+    let supported;
+    try {
+      supported = await facilitatorClient.getSupported();
+    } catch (cause) {
+      throw new X402OpenerFacilitatorUnverifiedError(
+        `the x402 facilitator at ${config.facilitatorUrl} is unreachable`,
+        { cause },
+      );
+    }
+    const kind = supported.kinds.find(
+      (candidate) =>
+        candidate.x402Version === 2 &&
+        candidate.scheme === OPENER_SCHEME &&
+        candidate.network === config.network,
+    );
+    const marker = readOpenerFacilitatorMarker(kind?.extra);
+    if (
+      marker === undefined ||
+      marker.factory !== factory ||
+      marker.escrow !== escrow ||
+      marker.usdc !== asset ||
+      marker.chainId !== chainId
+    ) {
+      throw new X402OpenerFacilitatorUnverifiedError(
+        `the x402 facilitator at ${config.facilitatorUrl} does not advertise Metrik opener settlement for factory ${factory} on ${config.network}. ` +
+          "Refusing to quote an opener payTo: a stock exact facilitator would transfer the payment straight to the opener and strand it permanently.",
+      );
+    }
+    if (marker.refundRelay !== true) {
+      throw new X402OpenerFacilitatorUnverifiedError(
+        `the x402 facilitator at ${config.facilitatorUrl} does not advertise the gasless refund relay (refundRelay: true). ` +
+          "Refusing to quote: the 402 tells payers unearned money is refundable without ETH, which needs that relay.",
+      );
+    }
+    if (config.price < BigInt(marker.minAmount)) {
+      throw new X402OpenerModeConfigError(
+        `price ${config.price} is below the facilitator minimum ${marker.minAmount}`,
+      );
+    }
+    if (
+      facilitatorTimeoutMs <
+      marker.receiptTimeoutSeconds * 1000 + FACILITATOR_TIMEOUT_HEADROOM_MS
+    ) {
+      throw new X402OpenerModeConfigError(
+        `the facilitator timeout ${facilitatorTimeoutMs}ms does not outlast the facilitator's ${marker.receiptTimeoutSeconds}s receipt wait by ${FACILITATOR_TIMEOUT_HEADROOM_MS / 1000}s`,
+      );
+    }
+  };
+
+  const resourceServer = new x402ResourceServer(facilitatorClient).register(
+    config.network,
+    new OpenerExactServerScheme(refundBaseUrl),
+  );
+  const description = describeOpenerPurchase({
+    terms: config.terms,
+    price: config.price,
+    assetDecimals,
+    assetSymbol: config.assetName,
+    refundUrlTemplate: `${refundBaseUrl}/streams/{streamId}`,
+    docsUrl,
+    ...(config.description === undefined
+      ? {}
+      : { serviceDescription: config.description }),
+  });
+  const route: RouteConfig = {
+    accepts: {
+      scheme: OPENER_SCHEME,
+      network: config.network,
+      payTo,
+      price: {
+        asset,
+        amount: config.price.toString(),
+        extra: {
+          name: config.assetName,
+          version: config.assetVersion,
+          assetTransferMethod: "eip3009",
+          [OPENER_EXTRA_KEY]: {
+            ...termsToExtra(factory, config.terms),
+            refundUrl: `${refundBaseUrl}/streams/{streamId}`,
+            docsUrl,
+          },
+        },
+      },
+      maxTimeoutSeconds,
+    },
+    description,
+    mimeType: "application/json",
+    ...(config.schemaDeclaration === undefined
+      ? {}
+      : { extensions: { bazaar: config.schemaDeclaration } }),
+    unpaidResponseBody: () => ({
+      contentType: "application/json",
+      body: { authorized: false, reason: "payment-required" },
+    }),
+  };
+  const httpServer = new x402HTTPResourceServer(resourceServer, route);
+
+  let initialized: Promise<void> | undefined;
+  const ready = async (): Promise<void> => {
+    const nowSeconds = now();
+    if (
+      markerCheckedAt === undefined ||
+      nowSeconds - markerCheckedAt >= markerTtl
+    ) {
+      markerCheckedAt = undefined;
+      await checkMarker();
+      markerCheckedAt = nowSeconds;
+    }
+    if (initialized === undefined) {
+      initialized = httpServer.initialize().catch((error: unknown) => {
+        initialized = undefined;
+        throw new X402OpenerFacilitatorUnverifiedError(
+          "the x402 resource server could not initialize against the facilitator",
+          { cause: error },
+        );
+      });
+    }
+    await initialized;
+  };
+
+  // Prove the facilitator at startup: refuse to start otherwise.
+  await ready();
+  if (refundBaseUrl !== config.facilitatorUrl.replace(/\/+$/, "")) {
+    await checkRefundRelayAt(refundBaseUrl, deps.fetch ?? fetch, {
+      factory,
+      escrow,
+      asset,
+      chainId,
+      network: config.network,
+    });
+  }
+
+  const mode: GatewayX402OpenerMode = {
+    payTo,
+    network: config.network,
+    terms: config.terms,
+    price: config.price,
+    resourceBaseUrl: config.resourceBaseUrl,
+    description,
+    refundBaseUrl,
+    httpServer,
+    authorizations: new GatewayAuthorizationLedger(now),
+    ready,
+    handle: (io) =>
+      handleX402GatewayRequest(mode, io).catch((error: unknown) => {
+        io.logError("x402 request failed", error);
+        io.writeJson(500, "internal-error");
+      }),
+  };
+  return mode;
+}
+
+/**
+ * A refund base URL other than the facilitator URL (e.g. the public origin of
+ * the same service) must serve the same opener marker with the relay on, so
+ * the 402 never points payers at a URL that cannot refund them.
+ */
+async function checkRefundRelayAt(
+  refundBaseUrl: string,
+  fetchImpl: typeof fetch,
+  expected: {
+    readonly factory: Address;
+    readonly escrow: Address;
+    readonly asset: Address;
+    readonly chainId: number;
+    readonly network: Network;
+  },
+): Promise<void> {
+  let supported: {
+    kinds?: {
+      x402Version?: unknown;
+      scheme?: unknown;
+      network?: unknown;
+      extra?: Record<string, unknown>;
+    }[];
+  };
+  try {
+    const response = await fetchImpl(`${refundBaseUrl}/supported`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    supported = (await response.json()) as typeof supported;
+  } catch (cause) {
+    throw new X402OpenerFacilitatorUnverifiedError(
+      `the refund relay at ${refundBaseUrl} is unreachable`,
+      { cause },
+    );
+  }
+  const kind = supported.kinds?.find(
+    (candidate) =>
+      candidate.x402Version === 2 &&
+      candidate.scheme === OPENER_SCHEME &&
+      candidate.network === expected.network,
+  );
+  const marker = readOpenerFacilitatorMarker(kind?.extra);
+  if (
+    marker === undefined ||
+    marker.factory !== expected.factory ||
+    marker.escrow !== expected.escrow ||
+    marker.usdc !== expected.asset ||
+    marker.chainId !== expected.chainId ||
+    marker.refundRelay !== true
+  ) {
+    throw new X402OpenerFacilitatorUnverifiedError(
+      `${refundBaseUrl} does not serve the Metrik opener refund relay for factory ${expected.factory}; refusing to advertise it as the refund URL`,
+    );
+  }
+}
+
+/**
+ * One x402-mode request, mirroring the reference `@x402/*` middleware: verify
+ * via the facilitator, run the upstream, and settle ONLY when the upstream
+ * status is < 400 — before any upstream byte is sent. A failed settlement sends
+ * no upstream body. Every facilitator error fails closed: never a free call.
+ */
+async function handleX402GatewayRequest(
+  mode: GatewayX402OpenerMode,
+  io: X402GatewayRequestIO,
+): Promise<void> {
+  try {
+    await mode.ready();
+  } catch (error) {
+    // The facilitator is not provably the Metrik opener facilitator right now:
+    // quote no payTo and verify nothing (a stock facilitator would strand it).
+    io.logError("x402 facilitator unverified", error);
+    io.writeJson(503, "x402-facilitator-unavailable");
+    return;
+  }
+
+  const { requestUrl, method, headers } = io;
+  const origin =
+    mode.resourceBaseUrl ?? `http://${headers.host ?? "localhost"}`;
+  const fullUrl = new URL(
+    requestUrl.pathname + requestUrl.search,
+    origin,
+  ).toString();
+  const adapter: HTTPAdapter = {
+    getHeader: (name) => headers[name.toLowerCase()],
+    getMethod: () => method,
+    getPath: () => requestUrl.pathname,
+    getUrl: () => fullUrl,
+    getAcceptHeader: () => headers.accept ?? "",
+    getUserAgent: () => headers["user-agent"] ?? "",
+  };
+  const paymentHeader = headers[PAYMENT_SIGNATURE_HEADER]?.trim();
+  const context: HTTPRequestContext = {
+    adapter,
+    path: requestUrl.pathname,
+    method,
+    ...(paymentHeader === undefined || paymentHeader.length === 0
+      ? {}
+      : { paymentHeader }),
+  };
+
+  // One authorization, at most one served response: claim it before verify so
+  // a concurrent duplicate never reaches the facilitator or the upstream.
+  const claim =
+    paymentHeader === undefined || paymentHeader.length === 0
+      ? undefined
+      : authorizationKey(paymentHeader);
+  if (
+    claim !== undefined &&
+    !mode.authorizations.claim(claim.key, claim.validBefore)
+  ) {
+    io.writeJson(409, "x402-payment-already-used");
+    return;
+  }
+  const release = () => {
+    if (claim !== undefined) mode.authorizations.release(claim.key);
+  };
+
+  let result: HTTPProcessResult;
+  try {
+    result = await mode.httpServer.processHTTPRequest(context);
+  } catch (error) {
+    release();
+    io.logError("x402 verification failed", error);
+    io.writeJson(402, "x402-facilitator-unavailable");
+    return;
+  }
+
+  if (result.type === "no-payment-required") {
+    // The route covers every path; reaching here is a misconfiguration.
+    release();
+    io.writeJson(500, "internal-error");
+    return;
+  }
+  if (result.type === "payment-error") {
+    release();
+    writeInstructions(io, result.response);
+    return;
+  }
+
+  const {
+    cancellationDispatcher,
+    beforeHandlerSettlement,
+    paymentPayload,
+    paymentRequirements,
+    declaredExtensions,
+  } = result;
+
+  let upstream: X402UpstreamResult;
+  try {
+    upstream = await io.callUpstream();
+  } catch (error) {
+    await cancellationDispatcher
+      .cancel({ reason: "handler_threw", error })
+      .catch(() => undefined);
+    release();
+    io.logError("upstream request failed", error);
+    io.writeJson(502, "upstream-unavailable");
+    return;
+  }
+
+  // The seller's upstream must not steer settlement.
+  const upstreamHeaders: Record<string, string> = {};
+  for (const [key, value] of Object.entries(upstream.headers)) {
+    if (key.toLowerCase() === SETTLEMENT_OVERRIDES_HEADER.toLowerCase())
+      continue;
+    upstreamHeaders[key] = value;
+  }
+
+  if (upstream.status >= 400) {
+    // Nothing is settled for a failed upstream: the authorization is never
+    // submitted, so no funds move.
+    await cancellationDispatcher
+      .cancel({ reason: "handler_failed", responseStatus: upstream.status })
+      .catch(() => undefined);
+    release();
+    io.write(upstream.status, upstreamHeaders, upstream.body);
+    return;
+  }
+
+  let settled: ProcessSettleResultResponse;
+  try {
+    settled = await mode.httpServer.processSettlement(
+      paymentPayload,
+      paymentRequirements,
+      declaredExtensions,
+      {
+        request: context,
+        responseBody: upstream.body,
+        responseHeaders: upstreamHeaders,
+      },
+      undefined,
+      beforeHandlerSettlement,
+    );
+  } catch (error) {
+    // Unknown outcome (e.g. the facilitator timed out): let a retry of the same
+    // signature through so the facilitator's ledger can reconcile it — that
+    // ledger, not this one, guarantees at most one success.
+    if (claim !== undefined) {
+      mode.authorizations.markPending(claim.key, claim.validBefore);
+    }
+    io.logError("x402 settlement failed", error);
+    io.writeJson(402, "x402-settlement-failed");
+    return;
+  }
+  if (!settled.success) {
+    if (claim !== undefined) {
+      if (settled.errorReason === "settlement_pending") {
+        mode.authorizations.markPending(claim.key, claim.validBefore);
+      } else if (settled.errorReason === "duplicate_settlement") {
+        mode.authorizations.markSettled(claim.key, claim.validBefore);
+      } else {
+        release();
+      }
+    }
+    // No upstream body on a failed settlement.
+    writeInstructions(io, settled.response);
+    return;
+  }
+  if (claim !== undefined) {
+    mode.authorizations.markSettled(claim.key, claim.validBefore);
+  }
+
+  const responseHeaders: Record<string, string> = {};
+  let existingCacheControl: string | null = null;
+  for (const [key, value] of Object.entries(upstreamHeaders)) {
+    if (key.toLowerCase() === "cache-control") {
+      existingCacheControl = value;
+      continue;
+    }
+    responseHeaders[key] = value;
+  }
+  Object.assign(responseHeaders, settled.headers);
+  responseHeaders["Cache-Control"] =
+    withPrivateCacheControl(existingCacheControl);
+  io.write(upstream.status, responseHeaders, upstream.body);
+}
+
+function writeInstructions(
+  io: X402GatewayRequestIO,
+  response: HTTPResponseInstructions,
+): void {
+  const headers: Record<string, string> = { ...response.headers };
+  if (response.isHtml === true) {
+    headers["Content-Type"] = "text/html; charset=utf-8";
+    io.write(response.status, headers, String(response.body ?? ""));
+    return;
+  }
+  headers["Content-Type"] = "application/json";
+  io.write(response.status, headers, JSON.stringify(response.body ?? {}));
+}