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

package/dist/gateway/x402-opener-mode.js

@@ -0,0 +1,772 @@
+import { HTTPFacilitatorClient, SETTLEMENT_OVERRIDES_HEADER, withPrivateCacheControl, x402HTTPResourceServer, x402ResourceServer, } from "@x402/core/server";
+import { decodePaymentSignatureHeader } from "@x402/core/http";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { createPublicClient, formatUnits, getAddress, http, isAddress, } from "viem";
+import { predictUpfrontOpenerAddress, x402UpfrontStreamOpenerFactoryAbi, } from "@absol-labs/shared";
+import { x402StreamOpenerFactoryAbi } from "../x402-opener/abi.js";
+import { RegistryListingResolver, } from "../x402-opener/listing-resolver.js";
+import { readOpenerFacilitatorMarker } from "../x402-opener/scheme.js";
+import { assertValidPrice, assertValidTerms, assertValidUpfrontTerms, chainIdFromNetwork, assertSchemaDeclaration, DEFAULT_OPENER_DOCS_URL, isHttpLink, OPENER_EXTRA_KEY, OPENER_SCHEME, termsToExtra, termsTuple, upfrontTermsToExtra, upfrontTermsTuple, } 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.
+ *
+ * ## Two opener kinds
+ *
+ * Without `upfrontAmount` the listing quotes the `X402StreamOpenerFactory`
+ * (`"stream"`): the whole price funds a metered stream. With `upfrontAmount`
+ * it quotes the `X402UpfrontStreamOpenerFactory` (`"upfront"`, the "minimum
+ * charge"): `amount == price`, `payTo = predict(6 terms)`, the
+ * `upfrontAmount` is paid to the seller at settlement and is NOT refundable,
+ * and only `price - upfrontAmount` funds a metered, refundable stream. The 402
+ * description states that split. `upfrontAmount == price` is an upfront-only
+ * listing: no stream opens (the settlement reports `streamId: null`), the
+ * response is served, and no metered session or refund exists for it.
+ */
+/** 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;
+/**
+ * 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) {
+    const amount = (value) => `${formatUnits(value, input.assetDecimals)} ${input.assetSymbol}`;
+    const { ratePerSecond, maxDuration } = input.terms;
+    const prefix = input.serviceDescription === undefined ||
+        input.serviceDescription.trim().length === 0
+        ? ""
+        : `${input.serviceDescription.trim()} `;
+    if (input.upfrontAmount !== undefined) {
+        const upfront = input.upfrontAmount;
+        const metered = input.price - upfront;
+        if (metered === 0n) {
+            return (`${prefix}Pays for one call: ${amount(input.price)}, charged in full at settlement as a NON-REFUNDABLE per-call charge ` +
+                "(paid to the seller whatever is delivered). No escrow stream is opened, so nothing is metered and there is nothing to refund or reclaim. " +
+                `Docs: ${input.docsUrl}`);
+        }
+        const meteredCap = metered < ratePerSecond * maxDuration
+            ? ` (the seller can earn at most ${amount(metered)} of it)`
+            : "";
+        return (`${prefix}Pays for one call: ${amount(input.price)} in total. ` +
+            (upfront === 0n
+                ? "Nothing of it is charged upfront. "
+                : `${amount(upfront)} is a NON-REFUNDABLE per-call charge, paid to the seller at settlement whatever is delivered. `) +
+            `The remaining ${amount(metered)} is metered and refundable: it funds a Metrik escrow stream of ` +
+            `${maxDuration.toString()} seconds at ${amount(ratePerSecond)}/s${meteredCap}; ` +
+            "the seller earns it only for seconds Metrik's verifier confirms the service is delivering, " +
+            `and any unearned part of it (at most ${amount(metered)}) 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}`);
+    }
+    const cap = input.price < ratePerSecond * maxDuration
+        ? ` (the seller can earn at most ${amount(input.price)})`
+        : "";
+    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 {
+    refundBaseUrl;
+    constructor(refundBaseUrl) {
+        super();
+        this.refundBaseUrl = refundBaseUrl;
+    }
+    enrichSettlementResponse = async (context) => {
+        if (!context.result.success)
+            return undefined;
+        const opened = context.result.extra?.[OPENER_EXTRA_KEY];
+        const streamId = opened?.streamId;
+        // An upfront-only payment reports `streamId: null` (no stream): it gets no
+        // refund URL, since there is nothing to refund. bytes32(0) is treated the
+        // same, defensively.
+        if (typeof streamId !== "string" ||
+            !/^0x[0-9a-fA-F]{64}$/.test(streamId) ||
+            /^0x0{64}$/i.test(streamId) ||
+            opened?.refundUrl !== undefined) {
+            return undefined;
+        }
+        return {
+            [OPENER_EXTRA_KEY]: {
+                refundUrl: `${this.refundBaseUrl}/streams/${streamId.toLowerCase()}`,
+            },
+        };
+    };
+}
+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 {
+    now;
+    maxEntries;
+    entries = new Map();
+    constructor(now, maxEntries = 100_000) {
+        this.now = now;
+        this.maxEntries = maxEntries;
+    }
+    /** Claims the authorization for one request; false if it is in flight or settled. */
+    claim(key, validBefore) {
+        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) {
+        this.entries.delete(key);
+    }
+    markPending(key, validBefore) {
+        this.entries.set(key, { state: "pending", validBefore });
+    }
+    markSettled(key, validBefore) {
+        this.entries.set(key, { state: "settled", validBefore });
+    }
+    prune() {
+        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) {
+    try {
+        const payload = decodePaymentSignatureHeader(header);
+        const authorization = payload.payload.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) {
+        super(message);
+        this.name = "X402OpenerModeConfigError";
+    }
+}
+export class X402OpenerFacilitatorUnverifiedError extends Error {
+    constructor(message, options) {
+        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, deps = {}) {
+    const kind = config.upfrontAmount === undefined ? "stream" : "upfront";
+    const upfrontTerms = config.upfrontAmount === undefined
+        ? undefined
+        : {
+            ...config.terms,
+            price: config.price,
+            upfrontAmount: config.upfrontAmount,
+        };
+    try {
+        if (upfrontTerms === undefined) {
+            assertValidTerms(config.terms);
+            assertValidPrice(config.price, config.terms);
+        }
+        else {
+            // The factory's own validateTerms rules + amount == price + the metered
+            // part within rate * maxDuration: exactly what the SDK buyer requires.
+            assertValidUpfrontTerms(upfrontTerms);
+        }
+    }
+    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],
+    ]) {
+        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],
+    ]) {
+        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);
+    let factoryEscrow;
+    let factoryUsdc;
+    let predicted;
+    if (upfrontTerms === undefined) {
+        [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)],
+            }),
+        ]);
+    }
+    else {
+        let implementation;
+        [factoryEscrow, factoryUsdc, predicted, implementation] = await Promise.all([
+            publicClient.readContract({
+                address: factory,
+                abi: x402UpfrontStreamOpenerFactoryAbi,
+                functionName: "escrow",
+            }),
+            publicClient.readContract({
+                address: factory,
+                abi: x402UpfrontStreamOpenerFactoryAbi,
+                functionName: "usdc",
+            }),
+            publicClient.readContract({
+                address: factory,
+                abi: x402UpfrontStreamOpenerFactoryAbi,
+                functionName: "predict",
+                args: [upfrontTermsTuple(upfrontTerms)],
+            }),
+            publicClient.readContract({
+                address: factory,
+                abi: x402UpfrontStreamOpenerFactoryAbi,
+                functionName: "implementation",
+            }),
+        ]).catch((error) => {
+            throw new X402OpenerModeConfigError(`factory ${factory} is not an X402UpfrontStreamOpenerFactory that accepts these upfront terms (${error instanceof Error ? (error.message.split("\n")[0] ?? "error") : String(error)})`);
+        });
+        if (config.upfrontImplementation !== undefined &&
+            getAddress(implementation) !== getAddress(config.upfrontImplementation)) {
+            throw new X402OpenerModeConfigError(`upfront factory ${factory} reports implementation ${implementation}, not the expected ${config.upfrontImplementation}`);
+        }
+        // The SDK buyer recomputes payTo OFFLINE; quote only a payTo both agree on.
+        const offline = predictUpfrontOpenerAddress({
+            factory,
+            implementation: getAddress(implementation),
+            terms: {
+                operator: getAddress(upfrontTerms.operator),
+                serviceRef: upfrontTerms.serviceRef.toLowerCase(),
+                ratePerSecond: upfrontTerms.ratePerSecond,
+                maxDuration: upfrontTerms.maxDuration,
+                price: upfrontTerms.price,
+                upfrontAmount: upfrontTerms.upfrontAmount,
+            },
+        });
+        if (getAddress(offline) !== getAddress(predicted)) {
+            throw new X402OpenerModeConfigError(`factory.predict(terms) = ${predicted} disagrees with the offline CREATE2 derivation ${offline}; refusing to quote it`);
+        }
+    }
+    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;
+    const checkMarker = async () => {
+        let supported;
+        try {
+            supported = await facilitatorClient.getSupported();
+        }
+        catch (cause) {
+            throw new X402OpenerFacilitatorUnverifiedError(`the x402 facilitator at ${config.facilitatorUrl} is unreachable`, { cause });
+        }
+        const supportedKind = supported.kinds.find((candidate) => candidate.x402Version === 2 &&
+            candidate.scheme === OPENER_SCHEME &&
+            candidate.network === config.network);
+        const marker = readOpenerFacilitatorMarker(supportedKind?.extra);
+        if (marker === undefined ||
+            !markerSettles(marker, upfrontTerms === undefined ? "stream" : "upfront", factory, escrow) ||
+            marker.usdc !== asset ||
+            marker.chainId !== chainId) {
+            throw new X402OpenerFacilitatorUnverifiedError(`the x402 facilitator at ${config.facilitatorUrl} does not advertise Metrik ${upfrontTerms === undefined ? "" : "upfront "}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,
+        ...(config.upfrontAmount === undefined
+            ? {}
+            : { upfrontAmount: config.upfrontAmount }),
+        assetDecimals,
+        assetSymbol: config.assetName,
+        refundUrlTemplate: `${refundBaseUrl}/streams/{streamId}`,
+        docsUrl,
+        ...(config.description === undefined
+            ? {}
+            : { serviceDescription: config.description }),
+    });
+    const route = {
+        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]: upfrontTerms === undefined
+                        ? {
+                            ...termsToExtra(factory, config.terms),
+                            refundUrl: `${refundBaseUrl}/streams/{streamId}`,
+                            docsUrl,
+                        }
+                        : {
+                            ...upfrontTermsToExtra(factory, upfrontTerms),
+                            // An upfront-only listing opens no stream: no refund URL.
+                            ...(upfrontTerms.upfrontAmount === upfrontTerms.price
+                                ? {}
+                                : { 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;
+    const ready = async () => {
+        const nowSeconds = now();
+        if (markerCheckedAt === undefined ||
+            nowSeconds - markerCheckedAt >= markerTtl) {
+            markerCheckedAt = undefined;
+            await checkMarker();
+            markerCheckedAt = nowSeconds;
+        }
+        if (initialized === undefined) {
+            initialized = httpServer.initialize().catch((error) => {
+                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, {
+            kind,
+            factory,
+            escrow,
+            asset,
+            chainId,
+            network: config.network,
+        });
+    }
+    const mode = {
+        payTo,
+        network: config.network,
+        terms: config.terms,
+        price: config.price,
+        openerKind: kind,
+        upfrontAmount: config.upfrontAmount ?? null,
+        resourceBaseUrl: config.resourceBaseUrl,
+        description,
+        refundBaseUrl,
+        httpServer,
+        authorizations: new GatewayAuthorizationLedger(now),
+        ready,
+        handle: (io) => handleX402GatewayRequest(mode, io).catch((error) => {
+            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, fetchImpl, expected) {
+    let supported;
+    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());
+    }
+    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 ||
+        !markerSettles(marker, expected.kind, expected.factory, 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`);
+    }
+}
+/**
+ * Whether a facilitator marker settles THIS listing's opener kind: the stream
+ * factory is the marker's `factory`; the upfront factory its `upfrontOpener`.
+ */
+function markerSettles(marker, kind, factory, escrow) {
+    if (kind === "upfront") {
+        return (marker.upfrontOpener !== undefined &&
+            marker.upfrontOpener.factory === factory &&
+            marker.upfrontOpener.escrow === escrow &&
+            marker.escrow === escrow);
+    }
+    return marker.factory === factory && marker.escrow === escrow;
+}
+/**
+ * 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, io) {
+    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 = {
+        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 = {
+        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;
+    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;
+    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 = {};
+    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;
+    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 = {};
+    let existingCacheControl = 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, response) {
+    const headers = { ...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 ?? {}));
+}
+//# sourceMappingURL=x402-opener-mode.js.map