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

package/src/gateway/http-server.ts

@@ -12,8 +12,31 @@ import {
   CallerAuthGateway,
   DEFAULT_MAX_STATE_STALENESS_SECONDS,
   MAX_CORROBORATING_STREAM_READERS,
+  type CallerAuthDecision,
   type CallerAuthDenialReason,
 } from "./caller-auth-gateway.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 } 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).
@@ -49,6 +72,15 @@ export interface CallerAuthGatewayServerConfig {
   readonly upstreamUrl: string;
   /** Extra request-timeout for the upstream fetch, in ms. Default 30000. */
   readonly upstreamTimeoutMs?: number;
+  /**
+   * 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 x402Opener?: GatewayX402OpenerMode;
 }
 
 export interface CallerAuthGatewayServer {
@@ -70,6 +102,7 @@ export function createCallerAuthGatewayServer(
       config.gateway,
       upstreamBase,
       upstreamTimeoutMs,
+      config.x402Opener,
     ).catch((error) => {
       logError("unhandled request error", error);
       if (!res.headersSent) {
@@ -105,11 +138,37 @@ async function handleRequest(
   gateway: CallerAuthGateway,
   upstreamBase: URL,
   upstreamTimeoutMs: number,
+  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,
@@ -138,6 +197,16 @@ 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,
@@ -153,11 +222,10 @@ async function handleRequest(
       signal: controller.signal,
     });
 
-    res.writeHead(
-      upstreamResponse.status,
-      headersToObject(upstreamResponse.headers),
-    );
     const buffer = Buffer.from(await upstreamResponse.arrayBuffer());
+    const responseHeaders = headersToObject(upstreamResponse.headers);
+
+    res.writeHead(upstreamResponse.status, responseHeaders);
     res.end(buffer);
   } catch (error) {
     logError("upstream request failed", error);
@@ -167,6 +235,130 @@ 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";
+
+/**
+ * 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.
+ */
+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,
+): 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,
+  });
+}
+
+/** 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);
+  }
+  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 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);
+  }
+}
+
 function normalizeIncomingHeaders(
   headers: IncomingMessage["headers"],
 ): Record<string, string | undefined> {
@@ -210,7 +402,9 @@ function writeJsonError(
     | CallerAuthDenialReason
     | "unauthorized"
     | "internal-error"
-    | "upstream-unavailable",
+    | "upstream-unavailable"
+    | "ambiguous-capability-and-payment"
+    | X402GatewayResponseReason,
 ): void {
   if (res.headersSent) {
     res.end();
@@ -242,6 +436,50 @@ export interface CallerAuthGatewayEnvConfig {
   readonly corroboratingRpcUrls: readonly string[];
   /** Freshness bound for on-chain stream state, in seconds. */
   readonly maxStateStalenessSeconds: number;
+  /** 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;
+}
+
+/** Env view of the gateway's x402 v2 opener mode (see {@link parseGatewayX402OpenerEnvConfig}). */
+export interface CallerAuthGatewayX402OpenerEnvConfig {
+  readonly facilitatorUrl: string;
+  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;
+  /** 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;
 }
 
 /**
@@ -260,8 +498,14 @@ export interface CallerAuthGatewayEnvConfig {
  * - `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`.
  *
@@ -294,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);
@@ -346,6 +594,15 @@ export function parseCallerAuthGatewayEnvConfig(
     );
   }
 
+  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,
     port,
@@ -360,9 +617,321 @@ export function parseCallerAuthGatewayEnvConfig(
     corroboratingRpcUrls,
     maxStateStalenessSeconds,
     ...(headerName === undefined ? {} : { headerName }),
+    ...(probe === undefined ? {} : { probe }),
+    ...(x402Opener === undefined ? {} : { x402Opener }),
+    ...(signedDescriptorFile === undefined ? {} : { signedDescriptorFile }),
+  };
+}
+
+/**
+ * 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.
+ *
+ * - `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 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;
+  }
+  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(
+      `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();
+  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 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_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 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(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_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 {
+    facilitatorUrl,
+    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
+      ? {}
+      : { 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 }),
   };
 }
 
+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`,
+    );
+  }
+  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);
+}
+
+/**
+ * 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 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 signerCacheSeconds = requirePositiveIntEnv(
+    env,
+    "METRIK_GATEWAY_PROBE_SIGNER_CACHE_SECONDS",
+    DEFAULT_ORACLE_SIGNER_CACHE_SECONDS,
+  );
+  return { maxProbesPerMinute, signerCacheSeconds };
+}
+
+function requirePositiveIntEnv(
+  env: NodeJS.ProcessEnv,
+  name: string,
+  fallback: number,
+): number {
+  const raw = env[name]?.trim();
+  if (raw === undefined || raw.length === 0) {
+    return fallback;
+  }
+  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 {
   const value = env[name];
   if (value === undefined || value.trim().length === 0) {
@@ -376,7 +945,14 @@ export async function startCallerAuthGatewayServerFromEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<CallerAuthGatewayServer & { readonly boundPort: number }> {
   const config = parseCallerAuthGatewayEnvConfig(env);
+  // 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,
@@ -387,7 +963,32 @@ export async function startCallerAuthGatewayServerFromEnv(
     ...(config.headerName === undefined
       ? {}
       : { headerName: config.headerName }),
+    ...(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 " +
@@ -397,9 +998,91 @@ export async function startCallerAuthGatewayServerFromEnv(
         "one INDEPENDENT provider to close that window.",
     );
   }
+  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] 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,
+    ...(x402Opener === undefined ? {} : { x402Opener }),
   });
   const { port } = await server.listen(config.port, config.host);
   return Object.assign(server, { boundPort: port });