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

package/dist/gateway/http-server.js

@@ -1,8 +1,12 @@
 import { createServer, } from "node:http";
 import { isAddress, isHex } from "viem";
 import { CallerAuthGateway, DEFAULT_MAX_STATE_STALENESS_SECONDS, MAX_CORROBORATING_STREAM_READERS, } from "./caller-auth-gateway.js";
-import { createHttpFacilitatorClient, createListingPriceQuoter, encodeSettleResponseHeader, X402_PAYMENT_RESPONSE_HEADER, X402_SETTLEMENT_HEADROOM_SECONDS, } from "./x402-mode.js";
-import { discoverServices } from "../discovery/registry.js";
+import { DEFAULT_MAX_PROBES_PER_MINUTE, DEFAULT_ORACLE_SIGNER_CACHE_SECONDS, } from "./probe-auth.js";
+import { PROBE_MARKER_HEADER_NAME } from "../capability/probe-capability.js";
+import { networkForCaip2, networkOpenerFactories } from "@absol-labs/sdk";
+import { chainIdFromNetwork, assertSchemaDeclaration, assertValidPrice, assertValidTerms, assertValidUpfrontTerms, isHttpLink, } from "../x402-opener/terms.js";
+import { loadSignedRateBoundsFile } from "./signed-rate-bounds.js";
+import { defaultNetwork, requireNetworkForChainId } from "../network.js";
 /**
  * Reference standalone reverse-proxy gateway server (metrik-agent#63).
  *
@@ -32,7 +36,7 @@ export function createCallerAuthGatewayServer(config) {
     const upstreamBase = new URL(config.upstreamUrl);
     const upstreamTimeoutMs = config.upstreamTimeoutMs ?? 30_000;
     const httpServer = createServer((req, res) => {
-        handleRequest(req, res, config.gateway, upstreamBase, upstreamTimeoutMs, config.x402).catch((error) => {
+        handleRequest(req, res, config.gateway, upstreamBase, upstreamTimeoutMs, config.x402Opener).catch((error) => {
             logError("unhandled request error", error);
             if (!res.headersSent) {
                 writeJsonError(res, 500, "internal-error");
@@ -58,24 +62,31 @@ export function createCallerAuthGatewayServer(config) {
         }),
     };
 }
-async function handleRequest(req, res, gateway, upstreamBase, upstreamTimeoutMs, x402) {
+async function handleRequest(req, res, gateway, upstreamBase, upstreamTimeoutMs, x402Opener) {
     const requestUrl = new URL(req.url ?? "/", "http://localhost");
     const method = req.method ?? "GET";
     const headers = normalizeIncomingHeaders(req.headers);
+    if (x402Opener !== undefined) {
+        const route = routeX402(headers, gateway);
+        if (route === "ambiguous-probe-mode") {
+            writeJsonError(res, 400, "ambiguous-probe-mode");
+            return;
+        }
+        if (route === "ambiguous-capability-and-payment") {
+            writeJsonError(res, 400, "ambiguous-capability-and-payment");
+            return;
+        }
+        if (route === "x402") {
+            await handleX402Request(req, res, x402Opener, requestUrl, method, headers, upstreamBase, upstreamTimeoutMs);
+            return;
+        }
+    }
     const decision = await gateway.authorize({
         headers,
         method,
         path: requestUrl.pathname,
     });
     if (!decision.authorized) {
-        // The x402 challenge is a PROTOCOL body, not Metrik's `{authorized,reason}`
-        // shape: `x402-fetch` parses `{x402Version, accepts}` and nothing else.
-        if (decision.x402PaymentRequired !== undefined) {
-            res
-                .writeHead(402, { "Content-Type": "application/json" })
-                .end(JSON.stringify(decision.x402PaymentRequired));
-            return;
-        }
         writeJsonError(res, decision.httpStatus ?? 403, decision.reason ?? "unauthorized");
         return;
     }
@@ -90,20 +101,18 @@ async function handleRequest(req, res, gateway, upstreamBase, upstreamTimeoutMs,
         }
         upstreamHeaders.set(key, value);
     }
-    const upstreamUrl = new URL(requestUrl.pathname + requestUrl.search, upstreamBase);
-    // Bound the upstream by the payment's OWN deadline, not just by the server's
-    // timeout. Settlement happens after the upstream returns, so an upstream that
-    // outlives the signed authorization would produce its side effects and then
-    // be unsettleable — the caller would get the work for free (never the response
-    // body, which is only flushed after settlement, but the side effects are
-    // real). Aborting early turns that into an ordinary 502.
-    const effectiveTimeoutMs = boundedUpstreamTimeoutMs(upstreamTimeoutMs, decision.x402Payment?.validBefore);
-    if (effectiveTimeoutMs <= 0) {
-        writeJsonError(res, 402, "x402-authorization-too-short");
-        return;
+    // The probe marker is gateway-asserted, never client-asserted: strip any
+    // inbound copy first, so a paying caller cannot mark its own billable request
+    // as verification traffic and slip past the seller's metering.
+    upstreamHeaders.delete(PROBE_MARKER_HEADER_NAME);
+    if (decision.probe !== undefined) {
+        // Advisory marker so the seller's OWN metering can exclude verification
+        // traffic from billable usage. The gateway itself charges nothing for it.
+        upstreamHeaders.set(PROBE_MARKER_HEADER_NAME, "1");
     }
+    const upstreamUrl = new URL(requestUrl.pathname + requestUrl.search, upstreamBase);
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), effectiveTimeoutMs);
+    const timeout = setTimeout(() => controller.abort(), upstreamTimeoutMs);
     try {
         const upstreamResponse = await fetch(upstreamUrl, {
             method,
@@ -113,21 +122,6 @@ async function handleRequest(req, res, gateway, upstreamBase, upstreamTimeoutMs,
         });
         const buffer = Buffer.from(await upstreamResponse.arrayBuffer());
         const responseHeaders = headersToObject(upstreamResponse.headers);
-        // Settle AFTER the upstream produced a response and BEFORE that response is
-        // flushed. Buyer-favouring on both edges: a call that never produced a
-        // response is never charged for, and a payment that cannot be settled
-        // returns `402` instead of handing over the goods for free.
-        if (decision.x402Payment !== undefined) {
-            const settled = await settleX402(decision, x402);
-            if (settled === undefined) {
-                writeJsonError(res, 402, "x402-settlement-failed");
-                return;
-            }
-            responseHeaders[X402_PAYMENT_RESPONSE_HEADER] =
-                encodeSettleResponseHeader(settled);
-            responseHeaders["access-control-expose-headers"] =
-                X402_PAYMENT_RESPONSE_HEADER;
-        }
         res.writeHead(upstreamResponse.status, responseHeaders);
         res.end(buffer);
     }
@@ -139,43 +133,93 @@ async function handleRequest(req, res, gateway, upstreamBase, upstreamTimeoutMs,
         clearTimeout(timeout);
     }
 }
+/** x402 v2 request header (base64 `PaymentPayload`). */
+const PAYMENT_SIGNATURE_HEADER = "payment-signature";
+/** x402 v1 request header. Never forwarded upstream in x402 mode either. */
+const LEGACY_PAYMENT_HEADER = "x-payment";
 /**
- * The upstream budget, capped so the signed authorization is still settleable
- * when the call returns. Returns <= 0 when there is no usable window at all.
+ * Decides which path an x402-mode request takes. A payment is never mixed with
+ * a capability or a probe: both-present is a `400`, not a guess.
  */
-export function boundedUpstreamTimeoutMs(upstreamTimeoutMs, validBeforeSeconds, nowSeconds = Math.floor(Date.now() / 1000)) {
-    if (validBeforeSeconds === undefined) {
-        return upstreamTimeoutMs;
-    }
-    const remainingSeconds = validBeforeSeconds - nowSeconds - X402_SETTLEMENT_HEADROOM_SECONDS;
-    if (remainingSeconds <= 0) {
-        return 0;
-    }
-    return Math.min(upstreamTimeoutMs, remainingSeconds * 1000);
+function routeX402(headers, gateway) {
+    const present = (name) => {
+        const value = headers[name];
+        return value !== undefined && value.trim().length > 0;
+    };
+    const hasPayment = present(PAYMENT_SIGNATURE_HEADER);
+    const hasCapability = present(gateway.capabilityHeaderName);
+    const hasProbe = present(gateway.probeCapabilityHeaderName);
+    if (hasProbe && hasPayment)
+        return "ambiguous-probe-mode";
+    if (hasCapability && hasPayment)
+        return "ambiguous-capability-and-payment";
+    if (hasPayment)
+        return "x402";
+    if (!hasCapability && !hasProbe)
+        return "x402";
+    return "capability-or-probe";
 }
-/** Returns the settlement result, or `undefined` if nothing was settled. */
-async function settleX402(decision, x402) {
-    const payment = decision.x402Payment;
-    if (payment === undefined) {
-        return undefined;
+/**
+ * The x402 v2 path. The protocol logic (verify → upstream → settle-before-body)
+ * lives with the mode in `./x402-opener-mode.ts`, so this module — and the
+ * package's root barrel — never loads `@x402/*` for a gateway that does not
+ * enable it. This function only supplies the transport.
+ */
+async function handleX402Request(req, res, mode, requestUrl, method, headers, upstreamBase, upstreamTimeoutMs) {
+    await mode.handle({
+        requestUrl,
+        method,
+        headers,
+        callUpstream: () => callUpstream(req, method, headers, requestUrl, upstreamBase, upstreamTimeoutMs),
+        writeJson: (status, reason) => writeJsonError(res, status, reason),
+        write: (status, responseHeaders, body) => {
+            if (res.headersSent) {
+                res.end();
+                return;
+            }
+            res.writeHead(status, responseHeaders);
+            res.end(body);
+        },
+        logError,
+    });
+}
+/** Buffers one upstream call. Payment headers are never forwarded. */
+async function callUpstream(req, method, headers, requestUrl, upstreamBase, upstreamTimeoutMs) {
+    let body;
+    if (method !== "GET" && method !== "HEAD") {
+        body = await readBody(req);
     }
-    if (x402 === undefined) {
-        // The gateway accepted an x402 payment but this server was given no
-        // facilitator to settle it with. Refuse: serving here would be free service.
-        logError("x402 settlement", new Error("gateway accepted an x402 payment but the server has no x402 facilitator configured"));
-        return undefined;
+    const upstreamHeaders = new Headers();
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined || HOP_BY_HOP_HEADERS.has(key))
+            continue;
+        upstreamHeaders.set(key, value);
     }
+    // A signed payment authorization must never reach the upstream: anyone who
+    // holds it can submit it to USDC directly, which strands the payer's funds
+    // in the opener. The probe marker is gateway-asserted only.
+    upstreamHeaders.delete(PAYMENT_SIGNATURE_HEADER);
+    upstreamHeaders.delete(LEGACY_PAYMENT_HEADER);
+    upstreamHeaders.delete(PROBE_MARKER_HEADER_NAME);
+    const upstreamUrl = new URL(requestUrl.pathname + requestUrl.search, upstreamBase);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), upstreamTimeoutMs);
     try {
-        const settled = await x402.facilitator.settle(payment.payload, payment.requirements);
-        if (settled.success !== true) {
-            logError("x402 settlement", new Error(settled.errorReason ?? "facilitator reported failure"));
-            return undefined;
-        }
-        return settled;
+        const response = await fetch(upstreamUrl, {
+            method,
+            headers: upstreamHeaders,
+            ...(body === undefined ? {} : { body }),
+            signal: controller.signal,
+        });
+        const buffer = Buffer.from(await response.arrayBuffer());
+        return {
+            status: response.status,
+            headers: headersToObject(response.headers),
+            body: buffer,
+        };
     }
-    catch (error) {
-        logError("x402 settlement", error);
-        return undefined;
+    finally {
+        clearTimeout(timeout);
     }
 }
 function normalizeIncomingHeaders(headers) {
@@ -240,8 +284,14 @@ function logError(context, error) {
  * - `METRIK_GATEWAY_MAX_STATE_STALENESS_SECONDS` (optional) - reject stream
  *   state observed more than N seconds behind the wall clock. Default
  *   {@link DEFAULT_MAX_STATE_STALENESS_SECONDS}.
- * - `METRIK_GATEWAY_CHAIN_ID` (optional) - default `84532` (Base Sepolia).
+ * - `METRIK_GATEWAY_CHAIN_ID` (optional) - default the registry's default
+ *   network. Must be a network the SDK registry knows.
  * - `METRIK_GATEWAY_HEADER_NAME` (optional) - default `x-metrik-capability`.
+ * - `METRIK_GATEWAY_SIGNED_DESCRIPTOR_FILE` (optional, recommended) - JSON file
+ *   holding this service's operator-signed descriptor (or an array, one per
+ *   served serviceRef). Verified at startup; the capability path then refuses
+ *   any stream whose on-chain `ratePerSecond` is outside the signed
+ *   `minRatePerSecond`/`maxRatePerSecond` (`stream-rate-out-of-bounds`).
  * - `PORT` / `METRIK_GATEWAY_PORT` (optional) - default `8787`.
  * - `METRIK_GATEWAY_HOST` (optional) - default `0.0.0.0`.
  *
@@ -269,11 +319,14 @@ export function parseCallerAuthGatewayEnvConfig(env = process.env) {
     const upstreamUrl = requireEnv(env, "METRIK_GATEWAY_UPSTREAM_URL");
     // eslint-disable-next-line no-new -- validates the URL is well-formed.
     new URL(upstreamUrl);
-    const chainIdRaw = env.METRIK_GATEWAY_CHAIN_ID ?? "84532";
+    const chainIdRaw = env.METRIK_GATEWAY_CHAIN_ID ?? String(defaultNetwork().chain.id);
     const chainId = Number(chainIdRaw);
     if (!Number.isInteger(chainId) || chainId <= 0) {
         throw new Error(`invalid METRIK_GATEWAY_CHAIN_ID: ${chainIdRaw}`);
     }
+    // The stream reader is built from the registry entry for this chain, so an
+    // unknown chain is refused at startup rather than at the first request.
+    requireNetworkForChainId(chainId, {}, "METRIK_GATEWAY_CHAIN_ID");
     const portRaw = env.METRIK_GATEWAY_PORT ?? env.PORT ?? "8787";
     const port = Number(portRaw);
     if (!Number.isInteger(port) || port < 0 || port > 65535) {
@@ -306,7 +359,12 @@ export function parseCallerAuthGatewayEnvConfig(env = process.env) {
         maxStateStalenessSeconds <= 0) {
         throw new Error(`invalid METRIK_GATEWAY_MAX_STATE_STALENESS_SECONDS: ${stalenessRaw}`);
     }
-    const x402 = parseGatewayX402EnvConfig(env);
+    const signedDescriptorFile = env.METRIK_GATEWAY_SIGNED_DESCRIPTOR_FILE?.trim() || undefined;
+    const probe = parseGatewayProbeEnvConfig(env);
+    const x402Opener = parseGatewayX402OpenerEnvConfig(env, {
+        chainId,
+        serviceRef: serviceRef,
+    });
     return {
         host,
         port,
@@ -321,106 +379,302 @@ export function parseCallerAuthGatewayEnvConfig(env = process.env) {
         corroboratingRpcUrls,
         maxStateStalenessSeconds,
         ...(headerName === undefined ? {} : { headerName }),
-        ...(x402 === undefined ? {} : { x402 }),
+        ...(probe === undefined ? {} : { probe }),
+        ...(x402Opener === undefined ? {} : { x402Opener }),
+        ...(signedDescriptorFile === undefined ? {} : { signedDescriptorFile }),
     };
 }
 /**
- * x402 mode is OFF unless `METRIK_GATEWAY_X402_PRICE_BASE_UNITS` is set. Once
- * on, every other x402 var is required: a half-configured paywall would answer
- * `402` with a quote it cannot settle.
+ * The x402 v2 opener mode is OFF unless `METRIK_GATEWAY_X402V2_OPENER` is
+ * truthy. When on, an uncapabilitied request is answered with a standard x402
+ * v2 `402` whose `payTo` is the opener for this listing's terms, and payments
+ * settle into a `StreamEscrowV2` stream through the Metrik opener facilitator.
+ * The listing is the gateway's primary `METRIK_GATEWAY_SERVICE_REF`.
+ *
+ * These names deliberately differ from the removed v1 mode's variables, so a
+ * leftover v1 environment can never switch a payment mode on by accident.
  *
- * Note what is NOT here: `payTo`. It is never configurable — it is resolved at
- * startup from the operator-signed descriptor for this gateway's `serviceRef`
- * (see {@link resolveSignedListingPayee}), and the gateway refuses to start if
- * that lookup fails.
+ * - `METRIK_GATEWAY_X402V2_OPENER` — `1`/`true`/`yes`/`on` to enable.
+ * - `METRIK_GATEWAY_X402V2_FACILITATOR_URL` (required) — the Metrik opener facilitator.
+ * - `METRIK_GATEWAY_X402V2_FACILITATOR_TOKEN` (required) — its `/settle` bearer token.
+ * - `METRIK_GATEWAY_X402V2_FACTORY_ADDRESS` — the `X402StreamOpenerFactory`; default the
+ *   network's registered factory (required where the registry has none).
+ * - `METRIK_GATEWAY_X402V2_OPERATOR` (required) — must be the signed listing's operator.
+ * - `METRIK_GATEWAY_X402V2_RATE_PER_SECOND` (required) — USDC base units per second.
+ * - `METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS` (required).
+ * - `METRIK_GATEWAY_X402V2_PRICE` (required) — base units per paid request (= deposit),
+ *   `0 < price <= rate * maxDuration`.
+ * - `METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT` — base units; when SET the listing
+ *   quotes the UPFRONT ("minimum charge") opener instead: `amount = price`,
+ *   `payTo = upfrontFactory.predict(6 terms)`; `upfrontAmount` is paid to the
+ *   seller at settlement and is NOT refundable, only `price - upfrontAmount`
+ *   (`<= rate * maxDuration`) is metered and refundable. `= PRICE` is
+ *   upfront-only (no stream). Validated with the factory's rules at startup.
+ * - `METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS` — the
+ *   `X402UpfrontStreamOpenerFactory`; default the network registry's (only
+ *   with `_UPFRONT_AMOUNT`). `_FACTORY_ADDRESS` names the STREAM factory and is
+ *   refused together with `_UPFRONT_AMOUNT`.
+ * - `METRIK_GATEWAY_X402V2_NETWORK` — default `eip155:<METRIK_GATEWAY_CHAIN_ID>`.
+ * - `METRIK_GATEWAY_X402V2_ASSET` — default the network's registered USDC.
+ * - `METRIK_GATEWAY_X402V2_ASSET_NAME` / `_ASSET_VERSION` — EIP-712 domain, default the
+ *   registered USDC's own EIP-712 name/version.
+ * - `METRIK_GATEWAY_X402V2_MAX_TIMEOUT_SECONDS` — authorization validity, default 300.
+ * - `METRIK_GATEWAY_X402V2_FACILITATOR_TIMEOUT_SECONDS` — per-request facilitator
+ *   timeout, default 120; must exceed the facilitator's receipt wait by 30 s.
+ * - `METRIK_GATEWAY_X402V2_RESOURCE_BASE_URL` — public origin for the 402 `resource.url`.
+ * - `METRIK_GATEWAY_X402V2_REGISTRY_URL` — registry used to prove the listing.
+ * - `METRIK_GATEWAY_X402V2_REFUND_BASE_URL` — public base URL of the facilitator's
+ *   gasless refund relay, advertised in the 402; default the facilitator URL. Its
+ *   `/supported` must show the opener marker with `refundRelay: true`.
+ * - `METRIK_GATEWAY_X402V2_DOCS_URL` — docs link in the 402; default docs/x402.md on GitHub.
+ * - `METRIK_GATEWAY_X402V2_ASSET_DECIMALS` — decimals for the 402 description; default 6.
+ * - `METRIK_GATEWAY_X402V2_DESCRIPTION` — one sentence on what the service does,
+ *   prefixed to the fixed disclosure of what the payment buys (at most 300 chars).
+ * - `METRIK_GATEWAY_X402V2_SCHEMA` — optional JSON `{info: {input, output}, schema}`
+ *   declared in the 402 as `extensions.bazaar` (declared only, never registered).
  */
-export function parseGatewayX402EnvConfig(env = process.env) {
-    const rawPrice = env.METRIK_GATEWAY_X402_PRICE_BASE_UNITS?.trim();
-    if (rawPrice === undefined || rawPrice.length === 0) {
+export function parseGatewayX402OpenerEnvConfig(env, context) {
+    const raw = env.METRIK_GATEWAY_X402V2_OPENER?.trim().toLowerCase();
+    if (raw === undefined ||
+        raw.length === 0 ||
+        ["0", "false", "no", "off"].includes(raw)) {
         return undefined;
     }
-    let pricePerCallBaseUnits;
-    try {
-        pricePerCallBaseUnits = BigInt(rawPrice);
+    if (!["1", "true", "yes", "on"].includes(raw)) {
+        throw new Error(`invalid METRIK_GATEWAY_X402V2_OPENER: ${raw} (expected a boolean)`);
+    }
+    const facilitatorUrl = requireEnv(env, "METRIK_GATEWAY_X402V2_FACILITATOR_URL").trim();
+    // eslint-disable-next-line no-new -- validates the URL is well-formed.
+    new URL(facilitatorUrl);
+    const facilitatorToken = requireEnv(env, "METRIK_GATEWAY_X402V2_FACILITATOR_TOKEN").trim();
+    const network = (env.METRIK_GATEWAY_X402V2_NETWORK?.trim() ||
+        `eip155:${String(context.chainId)}`);
+    if (chainIdFromNetwork(network) !== context.chainId) {
+        throw new Error(`METRIK_GATEWAY_X402V2_NETWORK ${network} does not match METRIK_GATEWAY_CHAIN_ID ${context.chainId}`);
+    }
+    // Defaults come from the registry entry for THIS network only.
+    const registered = networkForCaip2(network);
+    const factoryRaw = env.METRIK_GATEWAY_X402V2_FACTORY_ADDRESS?.trim();
+    const upfrontRaw = env.METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT?.trim();
+    const upfrontFactoryRaw = env.METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS?.trim();
+    const upfrontMode = upfrontRaw !== undefined && upfrontRaw.length > 0;
+    if (!upfrontMode &&
+        upfrontFactoryRaw !== undefined &&
+        upfrontFactoryRaw.length > 0) {
+        throw new Error("METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS needs METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT (it selects the upfront opener)");
+    }
+    let factoryAddress;
+    let upfrontImplementation;
+    if (upfrontMode) {
+        if (factoryRaw !== undefined && factoryRaw.length > 0) {
+            throw new Error("METRIK_GATEWAY_X402V2_FACTORY_ADDRESS names the STREAM opener factory; with METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT set the listing quotes the upfront factory — set METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS (or nothing, for the registry's) instead");
+        }
+        const registeredUpfront = registered === undefined
+            ? []
+            : networkOpenerFactories(registered).filter((entry) => entry.kind === "upfront");
+        if (upfrontFactoryRaw === undefined || upfrontFactoryRaw.length === 0) {
+            const current = registeredUpfront.find((entry) => !entry.legacy);
+            if (current === undefined) {
+                throw new Error(`METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS is required on ${network}: the network registry has no upfront opener factory for it`);
+            }
+            factoryAddress = current.address;
+            upfrontImplementation = current.implementation ?? undefined;
+        }
+        else if (isAddress(upfrontFactoryRaw)) {
+            factoryAddress = upfrontFactoryRaw;
+            upfrontImplementation =
+                registeredUpfront.find((entry) => entry.address.toLowerCase() === upfrontFactoryRaw.toLowerCase())?.implementation ?? undefined;
+        }
+        else {
+            throw new Error("METRIK_GATEWAY_X402V2_UPFRONT_FACTORY_ADDRESS must be an EVM address");
+        }
+    }
+    else if (factoryRaw === undefined || factoryRaw.length === 0) {
+        if (registered?.openerFactory == null) {
+            throw new Error(`METRIK_GATEWAY_X402V2_FACTORY_ADDRESS is required on ${network}: the network registry has no opener factory for it`);
+        }
+        factoryAddress = registered.openerFactory.address;
     }
-    catch {
-        throw new Error(`invalid METRIK_GATEWAY_X402_PRICE_BASE_UNITS: ${rawPrice} (integer base units, e.g. 1000 = 0.001 USDC)`);
+    else if (isAddress(factoryRaw)) {
+        factoryAddress = factoryRaw;
     }
-    if (pricePerCallBaseUnits <= 0n) {
-        throw new Error("METRIK_GATEWAY_X402_PRICE_BASE_UNITS must be positive");
+    else {
+        throw new Error("METRIK_GATEWAY_X402V2_FACTORY_ADDRESS must be an EVM address");
+    }
+    const operator = requireEnv(env, "METRIK_GATEWAY_X402V2_OPERATOR").trim();
+    if (!isAddress(operator)) {
+        throw new Error("METRIK_GATEWAY_X402V2_OPERATOR must be an EVM address");
+    }
+    const assetRaw = env.METRIK_GATEWAY_X402V2_ASSET?.trim();
+    let asset;
+    if (assetRaw === undefined || assetRaw.length === 0) {
+        if (registered === undefined) {
+            throw new Error(`METRIK_GATEWAY_X402V2_ASSET is required on ${network}: the network registry does not know it`);
+        }
+        asset = registered.usdc.address;
+    }
+    else if (isAddress(assetRaw)) {
+        asset = assetRaw;
+    }
+    else {
+        throw new Error("METRIK_GATEWAY_X402V2_ASSET must be an EVM address");
+    }
+    const terms = {
+        operator,
+        serviceRef: context.serviceRef,
+        ratePerSecond: requireUintEnv(env, "METRIK_GATEWAY_X402V2_RATE_PER_SECOND"),
+        maxDuration: requireUintEnv(env, "METRIK_GATEWAY_X402V2_MAX_DURATION_SECONDS"),
+    };
+    const price = requireUintEnv(env, "METRIK_GATEWAY_X402V2_PRICE");
+    let upfrontAmount;
+    if (upfrontMode) {
+        upfrontAmount = requireUintEnv(env, "METRIK_GATEWAY_X402V2_UPFRONT_AMOUNT");
+        // Startup validation, fail closed: the upfront factory's own validateTerms
+        // rules, 0 < price, upfrontAmount <= price, and the metered part
+        // (price - upfrontAmount) <= rate * maxDuration.
+        assertValidUpfrontTerms({ ...terms, price, upfrontAmount });
+    }
+    else {
+        // Startup validation: rate/duration > 0 and 0 < price <= rate * maxDuration.
+        assertValidTerms(terms);
+        assertValidPrice(price, terms);
+    }
+    const maxTimeoutSeconds = requirePositiveIntEnv(env, "METRIK_GATEWAY_X402V2_MAX_TIMEOUT_SECONDS", 300);
+    const facilitatorTimeoutSeconds = requirePositiveIntEnv(env, "METRIK_GATEWAY_X402V2_FACILITATOR_TIMEOUT_SECONDS", 120);
+    const resourceBaseUrl = env.METRIK_GATEWAY_X402V2_RESOURCE_BASE_URL?.trim();
+    if (resourceBaseUrl !== undefined && resourceBaseUrl.length > 0) {
+        // eslint-disable-next-line no-new -- validates the URL is well-formed.
+        new URL(resourceBaseUrl);
     }
-    const facilitatorUrl = requireEnv(env, "METRIK_GATEWAY_X402_FACILITATOR_URL");
-    const resourceBaseUrl = requireEnv(env, "METRIK_GATEWAY_X402_RESOURCE_BASE_URL");
-    for (const candidate of [facilitatorUrl, resourceBaseUrl]) {
+    const registryUrl = env.METRIK_GATEWAY_X402V2_REGISTRY_URL?.trim();
+    if (registryUrl !== undefined && registryUrl.length > 0) {
         // eslint-disable-next-line no-new -- validates the URL is well-formed.
-        new URL(candidate);
-    }
-    const registryUrl = env.METRIK_GATEWAY_X402_REGISTRY_URL;
-    const facilitatorToken = env.METRIK_GATEWAY_X402_FACILITATOR_TOKEN?.trim();
-    const rawTimeout = env.METRIK_GATEWAY_X402_MAX_TIMEOUT_SECONDS;
-    let maxTimeoutSeconds;
-    if (rawTimeout !== undefined && rawTimeout.trim().length > 0) {
-        maxTimeoutSeconds = Number(rawTimeout);
-        if (!Number.isInteger(maxTimeoutSeconds) || maxTimeoutSeconds <= 0) {
-            throw new Error(`invalid METRIK_GATEWAY_X402_MAX_TIMEOUT_SECONDS: ${rawTimeout}`);
+        new URL(registryUrl);
+    }
+    const optionalLink = (name) => {
+        const value = env[name]?.trim();
+        if (value === undefined || value.length === 0)
+            return undefined;
+        if (!isHttpLink(value)) {
+            throw new Error(`${name} must be an absolute http(s) URL`);
+        }
+        return value.replace(/\/+$/, "");
+    };
+    const refundBaseUrl = optionalLink("METRIK_GATEWAY_X402V2_REFUND_BASE_URL");
+    const docsUrl = optionalLink("METRIK_GATEWAY_X402V2_DOCS_URL");
+    const decimalsRaw = env.METRIK_GATEWAY_X402V2_ASSET_DECIMALS?.trim();
+    let assetDecimals;
+    if (decimalsRaw !== undefined && decimalsRaw.length > 0) {
+        assetDecimals = Number(decimalsRaw);
+        if (!/^\d+$/.test(decimalsRaw) ||
+            !Number.isInteger(assetDecimals) ||
+            assetDecimals > 36) {
+            throw new Error(`invalid METRIK_GATEWAY_X402V2_ASSET_DECIMALS: ${decimalsRaw} (expected an integer 0-36)`);
+        }
+    }
+    const description = env.METRIK_GATEWAY_X402V2_DESCRIPTION?.trim();
+    if (description !== undefined && description.length > 300) {
+        throw new Error("METRIK_GATEWAY_X402V2_DESCRIPTION must be at most 300 characters");
+    }
+    const schemaRaw = env.METRIK_GATEWAY_X402V2_SCHEMA?.trim();
+    let schemaDeclaration;
+    if (schemaRaw !== undefined && schemaRaw.length > 0) {
+        try {
+            const parsed = JSON.parse(schemaRaw);
+            assertSchemaDeclaration(parsed);
+            schemaDeclaration = parsed;
+        }
+        catch (error) {
+            throw new Error(`invalid METRIK_GATEWAY_X402V2_SCHEMA: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     return {
-        pricePerCallBaseUnits,
         facilitatorUrl,
-        resourceBaseUrl,
-        ...(registryUrl === undefined ? {} : { registryUrl }),
-        ...(maxTimeoutSeconds === undefined ? {} : { maxTimeoutSeconds }),
-        ...(facilitatorToken === undefined || facilitatorToken.length === 0
+        facilitatorToken,
+        network,
+        factoryAddress,
+        asset,
+        assetName: requireAssetDomainField(env.METRIK_GATEWAY_X402V2_ASSET_NAME, registered?.usdc.eip712.name, "METRIK_GATEWAY_X402V2_ASSET_NAME", network),
+        assetVersion: requireAssetDomainField(env.METRIK_GATEWAY_X402V2_ASSET_VERSION, registered?.usdc.eip712.version, "METRIK_GATEWAY_X402V2_ASSET_VERSION", network),
+        terms,
+        price,
+        ...(upfrontAmount === undefined ? {} : { upfrontAmount }),
+        ...(upfrontImplementation === undefined ? {} : { upfrontImplementation }),
+        maxTimeoutSeconds,
+        facilitatorTimeoutMs: facilitatorTimeoutSeconds * 1000,
+        ...(resourceBaseUrl === undefined || resourceBaseUrl.length === 0
+            ? {}
+            : { resourceBaseUrl }),
+        ...(registryUrl === undefined || registryUrl.length === 0
             ? {}
-            : { facilitatorToken }),
+            : { registryUrl }),
+        ...(refundBaseUrl === undefined ? {} : { refundBaseUrl }),
+        ...(docsUrl === undefined ? {} : { docsUrl }),
+        ...(assetDecimals === undefined ? {} : { assetDecimals }),
+        ...(description === undefined || description.length === 0
+            ? {}
+            : { description }),
+        ...(schemaDeclaration === undefined ? {} : { schemaDeclaration }),
     };
 }
-export class UnresolvedListingPayeeError extends Error {
-    constructor(serviceRef) {
-        super(`no operator-signed listing found for serviceRef ${serviceRef}. ` +
-            "x402 mode refuses to start: payTo is derived from the signed descriptor and " +
-            "is never taken from configuration, so an unresolved listing has no payee.");
-        this.name = "UnresolvedListingPayeeError";
+function requireAssetDomainField(raw, registered, name, network) {
+    const value = raw?.trim();
+    if (value !== undefined && value.length > 0)
+        return value;
+    if (registered === undefined) {
+        throw new Error(`${name} is required on ${network}: the network registry does not know the asset's EIP-712 domain`);
+    }
+    return registered;
+}
+function requireUintEnv(env, name) {
+    const raw = requireEnv(env, name).trim();
+    if (!/^(0|[1-9]\d*)$/.test(raw)) {
+        throw new Error(`invalid ${name}: ${raw} (expected a base-10 integer)`);
     }
+    return BigInt(raw);
 }
 /**
- * Resolves `{serviceRef, operator}` from the registry. `discoverServices`
- * re-derives `serviceRef` from the signed content and recovers the operator's
- * EIP-712 signature, dropping anything that fails — so what comes back here is
- * signed, not merely served.
+ * Oracle probe verification is OFF unless `METRIK_GATEWAY_PROBE_CAPABILITY` is
+ * truthy. Turning it on lets the neutral verifier exercise this gateway's PAID
+ * route with an oracle-signed, single-use, short-lived `ProbeCapability`
+ * instead of only its health route.
+ *
+ * There is NO credential to configure — authority is an EIP-712 signature by an
+ * address in the escrow's public `getOracleSigners()` set, read from the same
+ * `METRIK_GATEWAY_RPC_URL` the stream check already uses.
+ *
+ * - `METRIK_GATEWAY_PROBE_CAPABILITY` — `1`/`true`/`yes`/`on` to enable.
+ * - `METRIK_GATEWAY_PROBE_MAX_PER_MINUTE` (optional) — free-probe budget.
+ *   Default {@link DEFAULT_MAX_PROBES_PER_MINUTE}.
+ * - `METRIK_GATEWAY_PROBE_SIGNER_CACHE_SECONDS` (optional) — how long the
+ *   on-chain signer set is cached. Default
+ *   {@link DEFAULT_ORACLE_SIGNER_CACHE_SECONDS}.
  */
-export async function resolveSignedListingPayee(serviceRef, registryUrl) {
-    const listings = await discoverServices(registryUrl === undefined ? {} : { registryUrl });
-    const match = listings.find((listing) => listing.serviceRef.toLowerCase() === serviceRef.toLowerCase());
-    if (match === undefined) {
-        throw new UnresolvedListingPayeeError(serviceRef);
+export function parseGatewayProbeEnvConfig(env = process.env) {
+    const raw = env.METRIK_GATEWAY_PROBE_CAPABILITY?.trim().toLowerCase();
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
     }
-    return { serviceRef: match.serviceRef, operator: match.operator };
+    if (!["1", "true", "yes", "on"].includes(raw)) {
+        if (["0", "false", "no", "off"].includes(raw)) {
+            return undefined;
+        }
+        throw new Error(`invalid METRIK_GATEWAY_PROBE_CAPABILITY: ${raw} (expected a boolean)`);
+    }
+    const maxProbesPerMinute = requirePositiveIntEnv(env, "METRIK_GATEWAY_PROBE_MAX_PER_MINUTE", DEFAULT_MAX_PROBES_PER_MINUTE);
+    const signerCacheSeconds = requirePositiveIntEnv(env, "METRIK_GATEWAY_PROBE_SIGNER_CACHE_SECONDS", DEFAULT_ORACLE_SIGNER_CACHE_SECONDS);
+    return { maxProbesPerMinute, signerCacheSeconds };
 }
-/** Builds the gateway's x402 mode, deriving `payTo` from the signed listing. */
-export async function buildGatewayX402Mode(config) {
-    if (config.x402 === undefined) {
-        return undefined;
+function requirePositiveIntEnv(env, name, fallback) {
+    const raw = env[name]?.trim();
+    if (raw === undefined || raw.length === 0) {
+        return fallback;
     }
-    const listing = await resolveSignedListingPayee(config.serviceRef, config.x402.registryUrl);
-    return {
-        quote: createListingPriceQuoter({
-            listing,
-            resourceBaseUrl: config.x402.resourceBaseUrl,
-            pricePerCallBaseUnits: config.x402.pricePerCallBaseUnits,
-            chainId: config.chainId,
-            ...(config.x402.maxTimeoutSeconds === undefined
-                ? {}
-                : { maxTimeoutSeconds: config.x402.maxTimeoutSeconds }),
-        }),
-        facilitator: createHttpFacilitatorClient({
-            url: config.x402.facilitatorUrl,
-            ...(config.x402.facilitatorToken === undefined
-                ? {}
-                : { token: config.x402.facilitatorToken }),
-        }),
-    };
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`invalid ${name}: ${raw} (expected a positive integer)`);
+    }
+    return value;
 }
 function requireEnv(env, name) {
     const value = env[name];
@@ -432,8 +686,13 @@ function requireEnv(env, name) {
 /** Builds and starts the reference gateway server entirely from the environment. */
 export async function startCallerAuthGatewayServerFromEnv(env = process.env) {
     const config = parseCallerAuthGatewayEnvConfig(env);
-    const x402 = await buildGatewayX402Mode(config);
+    // Fail closed at startup: a configured descriptor that does not verify is a
+    // refusal to start, never a silently unenforced price band.
+    const signedRateBounds = config.signedDescriptorFile === undefined
+        ? undefined
+        : await loadSignedRateBoundsFile(config.signedDescriptorFile);
     const gateway = new CallerAuthGateway({
+        ...(signedRateBounds === undefined ? {} : { signedRateBounds }),
         escrowAddress: config.escrowAddress,
         rpcUrl: config.rpcUrl,
         serviceRef: config.serviceRef,
@@ -444,8 +703,26 @@ export async function startCallerAuthGatewayServerFromEnv(env = process.env) {
         ...(config.headerName === undefined
             ? {}
             : { headerName: config.headerName }),
-        ...(x402 === undefined ? {} : { x402 }),
+        ...(config.probe === undefined
+            ? {}
+            : {
+                probe: {
+                    maxProbesPerMinute: config.probe.maxProbesPerMinute,
+                    signerCacheSeconds: config.probe.signerCacheSeconds,
+                },
+            }),
     });
+    if (signedRateBounds === undefined) {
+        console.error("[metrik-caller-auth-gateway] WARNING: no METRIK_GATEWAY_SIGNED_DESCRIPTOR_FILE — the " +
+            "operator-signed minRatePerSecond/maxRatePerSecond are NOT enforced here. The escrow " +
+            "accepts any non-zero rate, so a buyer who opens a stream directly against it can be " +
+            "served below your signed price (metrik-contracts#41).");
+    }
+    else {
+        console.error(`[metrik-caller-auth-gateway] enforcing operator-signed rate bounds for ${signedRateBounds
+            .map((bounds) => `${bounds.serviceRef} [${bounds.minRatePerSecond ?? "-"}, ${bounds.maxRatePerSecond ?? "-"}]`)
+            .join(", ")}`);
+    }
     if (config.corroboratingRpcUrls.length === 0) {
         console.error("[metrik-caller-auth-gateway] WARNING: no METRIK_GATEWAY_CORROBORATING_RPC_URLS " +
             "configured — stream state is authorized from a single RPC view. A stale view " +
@@ -453,16 +730,90 @@ export async function startCallerAuthGatewayServerFromEnv(env = process.env) {
             `${config.maxStateStalenessSeconds}s by the freshness check). Configure at least ` +
             "one INDEPENDENT provider to close that window.");
     }
-    if (x402 !== undefined && config.x402 !== undefined) {
-        console.error("[metrik-caller-auth-gateway] standard x402 mode ENABLED: callers with no Metrik " +
-            `capability are quoted ${config.x402.pricePerCallBaseUnits} base units per call, ` +
-            `settled through ${config.x402.facilitatorUrl}. This is a per-call payment with NO ` +
-            "escrow and NO recoverability — the stream path remains the only recoverable one.");
+    if (config.probe !== undefined) {
+        console.error("[metrik-caller-auth-gateway] oracle probe verification ENABLED: a request carrying a " +
+            "valid EIP-712 ProbeCapability signed by an address in this escrow's on-chain " +
+            `getOracleSigners() set is proxied FREE, unmetered and unbilled, at most ` +
+            `${config.probe.maxProbesPerMinute} per minute. This is what lets the neutral ` +
+            "verifier check this gateway's PAID route instead of only its health route. " +
+            "Leaving it off is safe — the oracle then reports this listing's paid route as " +
+            "UNVERIFIABLE rather than as passing.");
+    }
+    else {
+        console.error("[metrik-caller-auth-gateway] oracle probe verification is OFF " +
+            "(METRIK_GATEWAY_PROBE_CAPABILITY unset). The verifier can only reach this service's " +
+            "health route, so paid-route delivery here is UNVERIFIED.");
+    }
+    let x402Opener;
+    if (config.x402Opener !== undefined) {
+        // Loaded only when enabled, so a capability-only gateway never imports @x402/*.
+        const { buildGatewayX402OpenerMode } = await import("./x402-opener-mode.js");
+        x402Opener = await buildGatewayX402OpenerMode({
+            facilitatorUrl: config.x402Opener.facilitatorUrl,
+            facilitatorToken: config.x402Opener.facilitatorToken,
+            network: config.x402Opener.network,
+            factoryAddress: config.x402Opener.factoryAddress,
+            escrowAddress: config.escrowAddress,
+            asset: config.x402Opener.asset,
+            assetName: config.x402Opener.assetName,
+            assetVersion: config.x402Opener.assetVersion,
+            terms: config.x402Opener.terms,
+            price: config.x402Opener.price,
+            ...(config.x402Opener.upfrontAmount === undefined
+                ? {}
+                : { upfrontAmount: config.x402Opener.upfrontAmount }),
+            ...(config.x402Opener.upfrontImplementation === undefined
+                ? {}
+                : { upfrontImplementation: config.x402Opener.upfrontImplementation }),
+            maxTimeoutSeconds: config.x402Opener.maxTimeoutSeconds,
+            facilitatorTimeoutMs: config.x402Opener.facilitatorTimeoutMs,
+            ...(config.x402Opener.resourceBaseUrl === undefined
+                ? {}
+                : { resourceBaseUrl: config.x402Opener.resourceBaseUrl }),
+            ...(config.x402Opener.registryUrl === undefined
+                ? {}
+                : { registryUrl: config.x402Opener.registryUrl }),
+            ...(config.x402Opener.refundBaseUrl === undefined
+                ? {}
+                : { refundBaseUrl: config.x402Opener.refundBaseUrl }),
+            ...(config.x402Opener.docsUrl === undefined
+                ? {}
+                : { docsUrl: config.x402Opener.docsUrl }),
+            ...(config.x402Opener.assetDecimals === undefined
+                ? {}
+                : { assetDecimals: config.x402Opener.assetDecimals }),
+            ...(config.x402Opener.description === undefined
+                ? {}
+                : { description: config.x402Opener.description }),
+            ...(config.x402Opener.schemaDeclaration === undefined
+                ? {}
+                : { schemaDeclaration: config.x402Opener.schemaDeclaration }),
+        }, { rpcUrl: config.rpcUrl });
+        const upfront = x402Opener.upfrontAmount;
+        console.error("[metrik-caller-auth-gateway] x402 v2 opener mode ENABLED: a request with neither a " +
+            "capability nor PAYMENT-SIGNATURE gets a 402 quoting payTo " +
+            `${x402Opener.payTo} (the ${x402Opener.openerKind} opener for serviceRef ${config.serviceRef}), price ` +
+            `${config.x402Opener.price} base units` +
+            (upfront === null
+                ? " (all of it escrowed and metered)"
+                : upfront === config.x402Opener.price
+                    ? " (UPFRONT-ONLY: all of it a non-refundable per-call charge; no stream, nothing to refund)"
+                    : ` (${upfront} a non-refundable per-call charge, ${config.x402Opener.price - upfront} escrowed, metered and refundable)`) +
+            `. Payments settle via the Metrik opener facilitator at ${config.x402Opener.facilitatorUrl}, and only after the upstream answers < 400. ` +
+            `Refunds (no ETH needed, never automatic): ${x402Opener.refundBaseUrl}/streams/:streamId.`);
+        const refundHost = new URL(x402Opener.refundBaseUrl).hostname;
+        if (refundHost === "localhost" ||
+            refundHost === "[::1]" ||
+            refundHost.startsWith("127.")) {
+            console.error("[metrik-caller-auth-gateway] WARNING: the 402 advertises a loopback refund URL " +
+                `(${x402Opener.refundBaseUrl}), which payers cannot reach. Set ` +
+                "METRIK_GATEWAY_X402V2_REFUND_BASE_URL to the facilitator's public origin.");
+        }
     }
     const server = createCallerAuthGatewayServer({
         gateway,
         upstreamUrl: config.upstreamUrl,
-        ...(x402 === undefined ? {} : { x402 }),
+        ...(x402Opener === undefined ? {} : { x402Opener }),
     });
     const { port } = await server.listen(config.port, config.host);
     return Object.assign(server, { boundPort: port });