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

package/src/gateway/http-server.ts

@@ -16,14 +16,27 @@ import {
   type CallerAuthDenialReason,
 } from "./caller-auth-gateway.js";
 import {
-  createHttpFacilitatorClient,
-  createListingPriceQuoter,
-  encodeSettleResponseHeader,
-  X402_PAYMENT_RESPONSE_HEADER,
-  X402_SETTLEMENT_HEADROOM_SECONDS,
-  type GatewayX402Mode,
-} from "./x402-mode.js";
-import { discoverServices } from "../discovery/registry.js";
+  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 } from "@absol-labs/sdk";
+import {
+  chainIdFromNetwork,
+  assertSchemaDeclaration,
+  assertValidPrice,
+  assertValidTerms,
+  isHttpLink,
+  type OpenerTerms,
+  type X402SchemaDeclaration,
+} from "../x402-opener/terms.js";
+import type {
+  GatewayX402OpenerMode,
+  X402GatewayResponseReason,
+  X402UpstreamResult,
+} from "./x402-opener-mode.js";
+import { loadSignedRateBoundsFile } from "./signed-rate-bounds.js";
+import { defaultNetwork, requireNetworkForChainId } from "../network.js";
 
 /**
  * Reference standalone reverse-proxy gateway server (metrik-agent#63).
@@ -60,11 +73,14 @@ export interface CallerAuthGatewayServerConfig {
   /** Extra request-timeout for the upstream fetch, in ms. Default 30000. */
   readonly upstreamTimeoutMs?: number;
   /**
-   * The same {@link GatewayX402Mode} given to the gateway. Required for the
-   * x402 path: the gateway VERIFIES a payment, this server SETTLES it once the
-   * upstream has produced a response.
+   * Optional x402 v2 mode (metrik-agent#116): an uncapabilitied request gets a
+   * standard x402 `402` whose `payTo` is the listing's escrow opener, and a
+   * `PAYMENT-SIGNATURE` is verified, served, and settled into a
+   * `StreamEscrowV2` stream. OFF when unset — the server is then byte for byte
+   * the capability-only gateway (`test/gateway-http-baseline.test.ts`).
+   * Build it with `buildGatewayX402OpenerMode`.
    */
-  readonly x402?: GatewayX402Mode;
+  readonly x402Opener?: GatewayX402OpenerMode;
 }
 
 export interface CallerAuthGatewayServer {
@@ -86,7 +102,7 @@ export function createCallerAuthGatewayServer(
       config.gateway,
       upstreamBase,
       upstreamTimeoutMs,
-      config.x402,
+      config.x402Opener,
     ).catch((error) => {
       logError("unhandled request error", error);
       if (!res.headersSent) {
@@ -122,12 +138,37 @@ async function handleRequest(
   gateway: CallerAuthGateway,
   upstreamBase: URL,
   upstreamTimeoutMs: number,
-  x402: GatewayX402Mode | undefined,
+  x402Opener: GatewayX402OpenerMode | undefined,
 ): Promise<void> {
   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,
@@ -135,14 +176,6 @@ async function handleRequest(
   });
 
   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,
@@ -164,28 +197,23 @@ async function handleRequest(
     upstreamHeaders.set(key, value);
   }
 
+  // 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,
   );
 
-  // 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;
-  }
-
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), effectiveTimeoutMs);
+  const timeout = setTimeout(() => controller.abort(), upstreamTimeoutMs);
   try {
     const upstreamResponse = await fetch(upstreamUrl, {
       method,
@@ -197,22 +225,6 @@ async function handleRequest(
     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);
   } catch (error) {
@@ -223,64 +235,127 @@ async function handleRequest(
   }
 }
 
+/** 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";
+
+type X402Route =
+  | "x402"
+  | "capability-or-probe"
+  | "ambiguous-probe-mode"
+  | "ambiguous-capability-and-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(
+function routeX402(
+  headers: Record<string, string | undefined>,
+  gateway: CallerAuthGateway,
+): X402Route {
+  const present = (name: string) => {
+    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";
+}
+
+/**
+ * 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: IncomingMessage,
+  res: ServerResponse,
+  mode: GatewayX402OpenerMode,
+  requestUrl: URL,
+  method: string,
+  headers: Record<string, string | undefined>,
+  upstreamBase: URL,
   upstreamTimeoutMs: number,
-  validBeforeSeconds: number | undefined,
-  nowSeconds: number = Math.floor(Date.now() / 1000),
-): number {
-  if (validBeforeSeconds === undefined) {
-    return upstreamTimeoutMs;
-  }
-  const remainingSeconds =
-    validBeforeSeconds - nowSeconds - X402_SETTLEMENT_HEADROOM_SECONDS;
-  if (remainingSeconds <= 0) {
-    return 0;
-  }
-  return Math.min(upstreamTimeoutMs, remainingSeconds * 1000);
+): Promise<void> {
+  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,
+  });
 }
 
-/** Returns the settlement result, or `undefined` if nothing was settled. */
-async function settleX402(
-  decision: CallerAuthDecision,
-  x402: GatewayX402Mode | undefined,
-): Promise<
-  Awaited<ReturnType<GatewayX402Mode["facilitator"]["settle"]>> | undefined
-> {
-  const payment = decision.x402Payment;
-  if (payment === undefined) {
-    return undefined;
+/** Buffers one upstream call. Payment headers are never forwarded. */
+async function callUpstream(
+  req: IncomingMessage,
+  method: string,
+  headers: Record<string, string | undefined>,
+  requestUrl: URL,
+  upstreamBase: URL,
+  upstreamTimeoutMs: number,
+): Promise<X402UpstreamResult> {
+  let body: Buffer | undefined;
+  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;
-  } catch (error) {
-    logError("x402 settlement", error);
-    return undefined;
+    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,
+    };
+  } finally {
+    clearTimeout(timeout);
   }
 }
 
@@ -328,8 +403,8 @@ function writeJsonError(
     | "unauthorized"
     | "internal-error"
     | "upstream-unavailable"
-    | "x402-settlement-failed"
-    | "x402-authorization-too-short",
+    | "ambiguous-capability-and-payment"
+    | X402GatewayResponseReason,
 ): void {
   if (res.headersSent) {
     res.end();
@@ -361,22 +436,50 @@ export interface CallerAuthGatewayEnvConfig {
   readonly corroboratingRpcUrls: readonly string[];
   /** Freshness bound for on-chain stream state, in seconds. */
   readonly maxStateStalenessSeconds: number;
-  /** Set only when standard-x402 mode is enabled. */
-  readonly x402?: CallerAuthGatewayX402EnvConfig;
+  /** Set only when oracle probe verification is enabled. */
+  readonly probe?: CallerAuthGatewayProbeEnvConfig;
+  /** Set only when the x402 v2 opener mode is enabled. */
+  readonly x402Opener?: CallerAuthGatewayX402OpenerEnvConfig;
+  /**
+   * Path of the operator-signed descriptor(s) whose rate band the capability
+   * path enforces (`METRIK_GATEWAY_SIGNED_DESCRIPTOR_FILE`). Loaded and
+   * verified at startup by {@link startCallerAuthGatewayServerFromEnv}.
+   */
+  readonly signedDescriptorFile?: string;
 }
 
-export interface CallerAuthGatewayX402EnvConfig {
-  /** Per-call price in the asset's base units (micro-USDC). Seller-set, unsigned. */
-  readonly pricePerCallBaseUnits: bigint;
-  /** A facilitator exposing `/verify` and `/settle` — e.g. Metrik's own. */
+/** Env view of the gateway's x402 v2 opener mode (see {@link parseGatewayX402OpenerEnvConfig}). */
+export interface CallerAuthGatewayX402OpenerEnvConfig {
   readonly facilitatorUrl: string;
-  /** The public origin buyers reach this gateway on. Becomes `resource`. */
-  readonly resourceBaseUrl: string;
-  /** Listing source used to derive `payTo` from the operator-signed descriptor. */
+  readonly facilitatorToken: string;
+  readonly network: `${string}:${string}`;
+  readonly factoryAddress: Address;
+  readonly asset: Address;
+  readonly assetName: string;
+  readonly assetVersion: string;
+  readonly terms: OpenerTerms;
+  readonly price: bigint;
+  readonly maxTimeoutSeconds: number;
+  /** Per-request facilitator HTTP timeout, ms. */
+  readonly facilitatorTimeoutMs: number;
+  readonly resourceBaseUrl?: string;
   readonly registryUrl?: string;
-  readonly maxTimeoutSeconds?: number;
-  /** Bearer token for the facilitator's `/settle`. Required by Metrik's own. */
-  readonly facilitatorToken?: string;
+  /** Public base URL of the facilitator's refund relay (default: facilitatorUrl). */
+  readonly refundBaseUrl?: string;
+  readonly docsUrl?: string;
+  /** Token decimals for the 402 description (default 6). */
+  readonly assetDecimals?: number;
+  /** One-sentence service description, prefixed to the fixed disclosure. */
+  readonly description?: string;
+  /** Optional input/output schema, declared as `extensions.bazaar`. */
+  readonly schemaDeclaration?: X402SchemaDeclaration;
+}
+
+export interface CallerAuthGatewayProbeEnvConfig {
+  /** Free-probe budget per minute. */
+  readonly maxProbesPerMinute: number;
+  /** Freshness bound for the cached on-chain oracle signer set, in seconds. */
+  readonly signerCacheSeconds: number;
 }
 
 /**
@@ -395,8 +498,14 @@ export interface CallerAuthGatewayX402EnvConfig {
  * - `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`.
  *
@@ -429,11 +538,15 @@ export function parseCallerAuthGatewayEnvConfig(
   // 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);
@@ -481,7 +594,14 @@ export function parseCallerAuthGatewayEnvConfig(
     );
   }
 
-  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 as Hex,
+  });
 
   return {
     host,
@@ -497,133 +617,319 @@ export function parseCallerAuthGatewayEnvConfig(
     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`.
  *
- * 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.
+ * 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.
+ *
+ * - `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_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: NodeJS.ProcessEnv = process.env,
-): CallerAuthGatewayX402EnvConfig | undefined {
-  const rawPrice = env.METRIK_GATEWAY_X402_PRICE_BASE_UNITS?.trim();
-  if (rawPrice === undefined || rawPrice.length === 0) {
+export function parseGatewayX402OpenerEnvConfig(
+  env: NodeJS.ProcessEnv,
+  context: { readonly chainId: number; readonly serviceRef: Hex },
+): CallerAuthGatewayX402OpenerEnvConfig | undefined {
+  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: bigint;
-  try {
-    pricePerCallBaseUnits = BigInt(rawPrice);
-  } catch {
+  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)}`) as `${string}:${string}`;
+  if (chainIdFromNetwork(network) !== context.chainId) {
     throw new Error(
-      `invalid METRIK_GATEWAY_X402_PRICE_BASE_UNITS: ${rawPrice} (integer base units, e.g. 1000 = 0.001 USDC)`,
+      `METRIK_GATEWAY_X402V2_NETWORK ${network} does not match METRIK_GATEWAY_CHAIN_ID ${context.chainId}`,
     );
   }
-  if (pricePerCallBaseUnits <= 0n) {
-    throw new Error("METRIK_GATEWAY_X402_PRICE_BASE_UNITS must be positive");
+  // Defaults come from the registry entry for THIS network only.
+  const registered = networkForCaip2(network);
+  const factoryRaw = env.METRIK_GATEWAY_X402V2_FACTORY_ADDRESS?.trim();
+  let factoryAddress: Address;
+  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;
+  } else if (isAddress(factoryRaw)) {
+    factoryAddress = factoryRaw;
+  } 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: Address;
+  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 facilitatorUrl = requireEnv(env, "METRIK_GATEWAY_X402_FACILITATOR_URL");
-  const resourceBaseUrl = requireEnv(
+  const terms: OpenerTerms = {
+    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");
+  // Startup validation: rate/duration > 0 and 0 < price <= rate * maxDuration.
+  assertValidTerms(terms);
+  assertValidPrice(price, terms);
+  const maxTimeoutSeconds = requirePositiveIntEnv(
     env,
-    "METRIK_GATEWAY_X402_RESOURCE_BASE_URL",
+    "METRIK_GATEWAY_X402V2_MAX_TIMEOUT_SECONDS",
+    300,
   );
-  for (const candidate of [facilitatorUrl, resourceBaseUrl]) {
+  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 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: number | undefined;
-  if (rawTimeout !== undefined && rawTimeout.trim().length > 0) {
-    maxTimeoutSeconds = Number(rawTimeout);
-    if (!Number.isInteger(maxTimeoutSeconds) || maxTimeoutSeconds <= 0) {
+    new URL(registryUrl);
+  }
+  const optionalLink = (name: string): string | undefined => {
+    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: number | undefined;
+  if (decimalsRaw !== undefined && decimalsRaw.length > 0) {
+    assetDecimals = Number(decimalsRaw);
+    if (
+      !/^\d+$/.test(decimalsRaw) ||
+      !Number.isInteger(assetDecimals) ||
+      assetDecimals > 36
+    ) {
       throw new Error(
-        `invalid METRIK_GATEWAY_X402_MAX_TIMEOUT_SECONDS: ${rawTimeout}`,
+        `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: X402SchemaDeclaration | undefined;
+  if (schemaRaw !== undefined && schemaRaw.length > 0) {
+    try {
+      const parsed: unknown = 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,
+    maxTimeoutSeconds,
+    facilitatorTimeoutMs: facilitatorTimeoutSeconds * 1000,
+    ...(resourceBaseUrl === undefined || resourceBaseUrl.length === 0
       ? {}
-      : { facilitatorToken }),
+      : { resourceBaseUrl }),
+    ...(registryUrl === undefined || registryUrl.length === 0
+      ? {}
+      : { 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: string) {
-    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.",
+function requireAssetDomainField(
+  raw: string | undefined,
+  registered: string | undefined,
+  name: string,
+  network: string,
+): string {
+  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`,
     );
-    this.name = "UnresolvedListingPayeeError";
   }
+  return registered;
+}
+
+function requireUintEnv(env: NodeJS.ProcessEnv, name: string): bigint {
+  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: Hex,
-  registryUrl?: string,
-): Promise<{ readonly serviceRef: Hex; readonly operator: Address }> {
-  const listings = await discoverServices(
-    registryUrl === undefined ? {} : { registryUrl },
+export function parseGatewayProbeEnvConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): CallerAuthGatewayProbeEnvConfig | undefined {
+  const raw = env.METRIK_GATEWAY_PROBE_CAPABILITY?.trim().toLowerCase();
+  if (raw === undefined || raw.length === 0) {
+    return undefined;
+  }
+  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 match = listings.find(
-    (listing) => listing.serviceRef.toLowerCase() === serviceRef.toLowerCase(),
+  const signerCacheSeconds = requirePositiveIntEnv(
+    env,
+    "METRIK_GATEWAY_PROBE_SIGNER_CACHE_SECONDS",
+    DEFAULT_ORACLE_SIGNER_CACHE_SECONDS,
   );
-  if (match === undefined) {
-    throw new UnresolvedListingPayeeError(serviceRef);
-  }
-  return { serviceRef: match.serviceRef, operator: match.operator };
+  return { maxProbesPerMinute, signerCacheSeconds };
 }
 
-/** Builds the gateway's x402 mode, deriving `payTo` from the signed listing. */
-export async function buildGatewayX402Mode(
-  config: CallerAuthGatewayEnvConfig,
-): Promise<GatewayX402Mode | undefined> {
-  if (config.x402 === undefined) {
-    return undefined;
+function requirePositiveIntEnv(
+  env: NodeJS.ProcessEnv,
+  name: string,
+  fallback: number,
+): number {
+  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: NodeJS.ProcessEnv, name: string): string {
@@ -639,8 +945,14 @@ export async function startCallerAuthGatewayServerFromEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<CallerAuthGatewayServer & { readonly boundPort: number }> {
   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,
@@ -651,8 +963,32 @@ export async function startCallerAuthGatewayServerFromEnv(
     ...(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 " +
@@ -662,18 +998,91 @@ export async function startCallerAuthGatewayServerFromEnv(
         "one INDEPENDENT provider to close that window.",
     );
   }
-  if (x402 !== undefined && config.x402 !== undefined) {
+  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: GatewayX402OpenerMode | undefined;
+  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,
+        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 },
+    );
     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.",
+      "[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 escrow opener for serviceRef ${config.serviceRef}), price ` +
+        `${config.x402Opener.price} base units. Payments settle into StreamEscrowV2 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 });