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

package/src/x402-opener/facilitator-server.ts

@@ -0,0 +1,1014 @@
+import { timingSafeEqual, createHash } from "node:crypto";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { networkForCaip2 } from "@absol-labs/sdk";
+import { x402Facilitator } from "@x402/core/facilitator";
+import type { Network } from "@x402/core/types";
+import {
+  createPublicClient,
+  createWalletClient,
+  getAddress,
+  http,
+  isAddress,
+  isHex,
+  type Address,
+  type Hex,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+import { DEFAULT_METRIK_PUBLIC_REGISTRY_URL } from "../discovery/registry.js";
+import {
+  DEFAULT_LISTING_CACHE_SECONDS,
+  RegistryListingResolver,
+  type OperatorSignedListingResolver,
+} from "./listing-resolver.js";
+import {
+  DEFAULT_REFUND_READ_CACHE_SECONDS,
+  DEFAULT_REFUND_SUBMISSIONS_PER_MINUTE,
+  DEFAULT_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE,
+  OpenerRefundRelay,
+  type RefundRelayHandler,
+  type RefundRelayResponse,
+} from "./refund-relay.js";
+import { RelayerQueue } from "./relayer-queue.js";
+import {
+  MetrikOpenerExactScheme,
+  type OpenerFacilitatorBinding,
+} from "./scheme.js";
+import { chainIdFromNetwork } from "./terms.js";
+import { chainForChainId, defaultNetwork } from "../network.js";
+
+/**
+ * The Metrik x402 v2 opener facilitator as an HTTP service
+ * (`/verify`, `/settle`, `/supported`), built on the official
+ * `@x402/core` `x402Facilitator` with {@link MetrikOpenerExactScheme} as its
+ * only registered scheme — so it can only ever settle into the escrow opener.
+ *
+ * - `/settle` spends relayer gas and moves buyer funds, so it requires a bearer
+ *   token (constant-time compared). `/verify` and `/supported` are read-only.
+ * - The relayer key comes from the environment only and is never logged.
+ * - OFF unless explicitly enabled; refuses to start without the relayer key,
+ *   RPC, token and a factory whose on-chain wiring checks out.
+ */
+
+/** Maximum accepted request body, bytes. A payment payload is well under 8 KiB. */
+const MAX_BODY_BYTES = 64 * 1024;
+
+/** Maximum refund-relay request body, bytes: `{deadline, signature}` is tiny. */
+const MAX_REFUND_BODY_BYTES = 8 * 1024;
+
+/** `/streams/:streamId` and `/streams/:streamId/:action`. */
+const STREAMS_ROUTE = /^\/streams\/([^/]+)(?:\/([^/]+))?\/?$/;
+
+class BodyTooLargeError extends Error {}
+
+export interface OpenerFacilitatorServerConfig {
+  readonly facilitator: x402Facilitator;
+  /** Bearer token required on `/settle`. At least 32 characters. */
+  readonly authToken: string;
+  /**
+   * Require the token on `/verify` too. Default TRUE: every verify costs RPC
+   * reads, and the gateway always sends the token. Opt out only explicitly.
+   */
+  readonly requireAuthOnVerify?: boolean;
+  /** Authorized `/settle` calls allowed per token per minute. Default 60. */
+  readonly settleRateLimitPerMinute?: number;
+  /** Injectable clock (ms), for tests. */
+  readonly nowMs?: () => number;
+  readonly logger?: Pick<Console, "error">;
+  /**
+   * The gasless refund relay (metrik-agent#119), mounted at
+   * `GET /streams/:streamId` and `POST /streams/:streamId/{close,reclaim,reclaim-unverified}`.
+   * Unauthenticated by design (the contract fixes who can act and where money
+   * goes); bounded by the relay's own checks plus a per-IP limit. Absent = 404.
+   */
+  readonly refundRelay?: RefundRelayHandler;
+  /** `/streams/*` requests allowed per client IP per minute. Default 30. */
+  readonly refundRateLimitPerIpPerMinute?: number;
+  /**
+   * `/streams/*` requests allowed per minute from ALL clients together — an
+   * IP-independent bound on the RPC and oracle reads the public routes fan
+   * out to. Default {@link DEFAULT_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE}.
+   */
+  readonly refundGlobalRateLimitPerMinute?: number;
+  /**
+   * Key the per-IP limit on the right-most `X-Forwarded-For` entry (the hop
+   * the trusted reverse proxy appended) instead of the socket address. Enable
+   * ONLY behind a proxy that appends it; default false.
+   */
+  readonly trustProxy?: boolean;
+}
+
+export interface OpenerFacilitatorServer {
+  readonly httpServer: Server;
+  listen(port: number, host?: string): Promise<{ port: number; host: string }>;
+  close(): Promise<void>;
+}
+
+export const MIN_AUTH_TOKEN_LENGTH = 32;
+export const DEFAULT_SETTLE_RATE_LIMIT_PER_MINUTE = 60;
+export const DEFAULT_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE = 30;
+export const DEFAULT_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE = 120;
+/** Cap on remembered client IPs; beyond it new clients are refused (fail closed). */
+const MAX_TRACKED_CLIENTS = 100_000;
+
+export function createOpenerFacilitatorServer(
+  config: OpenerFacilitatorServerConfig,
+): OpenerFacilitatorServer {
+  if (config.authToken.length < MIN_AUTH_TOKEN_LENGTH) {
+    throw new Error(
+      `authToken must be at least ${MIN_AUTH_TOKEN_LENGTH} characters`,
+    );
+  }
+  const logger = config.logger ?? console;
+  const tokenDigest = digest(config.authToken);
+  const requireAuthOnVerify = config.requireAuthOnVerify ?? true;
+  const settleLimit =
+    config.settleRateLimitPerMinute ?? DEFAULT_SETTLE_RATE_LIMIT_PER_MINUTE;
+  if (!Number.isInteger(settleLimit) || settleLimit <= 0) {
+    throw new Error("settleRateLimitPerMinute must be a positive integer");
+  }
+  const nowMs = config.nowMs ?? (() => Date.now());
+  // Fixed one-minute windows, keyed by the token's digest (never the token).
+  const settleWindows = new Map<string, { start: number; count: number }>();
+  const allowSettle = (key: string): boolean => {
+    const now = nowMs();
+    const window = settleWindows.get(key);
+    if (window === undefined || now - window.start >= 60_000) {
+      settleWindows.set(key, { start: now, count: 1 });
+      return true;
+    }
+    if (window.count >= settleLimit) return false;
+    window.count += 1;
+    return true;
+  };
+
+  const refundLimit =
+    config.refundRateLimitPerIpPerMinute ??
+    DEFAULT_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE;
+  if (!Number.isInteger(refundLimit) || refundLimit <= 0) {
+    throw new Error("refundRateLimitPerIpPerMinute must be a positive integer");
+  }
+  const globalRefundLimit =
+    config.refundGlobalRateLimitPerMinute ??
+    DEFAULT_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE;
+  if (!Number.isInteger(globalRefundLimit) || globalRefundLimit <= 0) {
+    throw new Error(
+      "refundGlobalRateLimitPerMinute must be a positive integer",
+    );
+  }
+  const globalRefundWindow = { start: -Infinity, count: 0 };
+  /** Seconds until the global window resets, or 0 when the request is allowed. */
+  const takeGlobalRefundBudget = (): number => {
+    const now = nowMs();
+    if (now - globalRefundWindow.start >= 60_000) {
+      globalRefundWindow.start = now;
+      globalRefundWindow.count = 1;
+      return 0;
+    }
+    if (globalRefundWindow.count >= globalRefundLimit) {
+      return Math.max(
+        1,
+        Math.ceil((globalRefundWindow.start + 60_000 - now) / 1000),
+      );
+    }
+    globalRefundWindow.count += 1;
+    return 0;
+  };
+  const refundWindows = new Map<string, { start: number; count: number }>();
+  /** Seconds until the client's window resets, or 0 when the request is allowed. */
+  const takeRefundBudget = (client: string): number => {
+    const now = nowMs();
+    const window = refundWindows.get(client);
+    if (window === undefined || now - window.start >= 60_000) {
+      if (window === undefined && refundWindows.size >= MAX_TRACKED_CLIENTS) {
+        for (const [key, value] of refundWindows) {
+          if (now - value.start >= 60_000) refundWindows.delete(key);
+        }
+        if (refundWindows.size >= MAX_TRACKED_CLIENTS) return 60;
+      }
+      refundWindows.set(client, { start: now, count: 1 });
+      return 0;
+    }
+    if (window.count >= refundLimit) {
+      return Math.max(1, Math.ceil((window.start + 60_000 - now) / 1000));
+    }
+    window.count += 1;
+    return 0;
+  };
+  const clientKey = (req: IncomingMessage): string => {
+    if (config.trustProxy === true) {
+      const header = req.headers["x-forwarded-for"];
+      const value = Array.isArray(header) ? header.at(-1) : header;
+      const hop = value?.split(",").at(-1)?.trim();
+      if (hop !== undefined && hop.length > 0 && hop.length <= 64) return hop;
+    }
+    return req.socket.remoteAddress ?? "unknown";
+  };
+
+  const authorized = (req: IncomingMessage): boolean => {
+    const header = req.headers.authorization;
+    if (typeof header !== "string" || !header.startsWith("Bearer ")) {
+      return false;
+    }
+    // Compare fixed-length digests so neither length nor content leaks.
+    return timingSafeEqual(digest(header.slice("Bearer ".length)), tokenDigest);
+  };
+
+  const httpServer = createServer((req, res) => {
+    handle(req, res).catch((error) => {
+      logger.error(
+        `[metrik-opener-facilitator] unhandled error: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      if (!res.headersSent) {
+        json(res, 500, { error: "internal-error" });
+      } else {
+        res.end();
+      }
+    });
+  });
+
+  async function handle(req: IncomingMessage, res: ServerResponse) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const method = req.method ?? "GET";
+
+    if (url.pathname === "/health" && method === "GET") {
+      json(res, 200, { ok: true });
+      return;
+    }
+    if (url.pathname === "/supported" && method === "GET") {
+      json(res, 200, config.facilitator.getSupported());
+      return;
+    }
+    const streamsRoute = STREAMS_ROUTE.exec(url.pathname);
+    if (streamsRoute !== null && config.refundRelay !== undefined) {
+      let streamId: string;
+      try {
+        streamId = decodeURIComponent(streamsRoute[1] as string);
+      } catch {
+        json(res, 400, { ok: false, error: "invalid-stream-id" });
+        return;
+      }
+      await handleRefund(
+        req,
+        res,
+        config.refundRelay,
+        method,
+        streamId,
+        streamsRoute[2],
+      );
+      return;
+    }
+    if (
+      (url.pathname === "/verify" || url.pathname === "/settle") &&
+      method === "POST"
+    ) {
+      const isSettle = url.pathname === "/settle";
+      if ((isSettle || requireAuthOnVerify) && !authorized(req)) {
+        json(res, 401, { error: "unauthorized" });
+        return;
+      }
+      if (isSettle && !allowSettle(tokenDigest.toString("hex"))) {
+        json(res, 429, { error: "rate-limited" });
+        return;
+      }
+      let body: unknown;
+      try {
+        body = JSON.parse((await readBody(req)).toString("utf8"));
+      } catch {
+        json(res, 400, { error: "invalid-json" });
+        return;
+      }
+      const request = body as {
+        paymentPayload?: unknown;
+        paymentRequirements?: unknown;
+      };
+      if (
+        typeof request !== "object" ||
+        request === null ||
+        typeof request.paymentPayload !== "object" ||
+        request.paymentPayload === null ||
+        typeof request.paymentRequirements !== "object" ||
+        request.paymentRequirements === null
+      ) {
+        json(res, 400, {
+          error: "paymentPayload and paymentRequirements are required",
+        });
+        return;
+      }
+      const payload = request.paymentPayload as Parameters<
+        x402Facilitator["verify"]
+      >[0];
+      const requirements = request.paymentRequirements as Parameters<
+        x402Facilitator["verify"]
+      >[1];
+      if (isSettle) {
+        try {
+          json(
+            res,
+            200,
+            await config.facilitator.settle(payload, requirements),
+          );
+        } catch (error) {
+          json(res, 200, {
+            success: false,
+            errorReason: "metrik_opener_settle_error",
+            errorMessage:
+              error instanceof Error ? error.message : String(error),
+            transaction: "",
+            network: requirements.network ?? "",
+          });
+        }
+        return;
+      }
+      try {
+        json(res, 200, await config.facilitator.verify(payload, requirements));
+      } catch (error) {
+        json(res, 200, {
+          isValid: false,
+          invalidReason: "metrik_opener_verify_error",
+          invalidMessage:
+            error instanceof Error ? error.message : String(error),
+        });
+      }
+      return;
+    }
+    json(res, 404, { error: "not-found" });
+  }
+
+  async function handleRefund(
+    req: IncomingMessage,
+    res: ServerResponse,
+    relay: RefundRelayHandler,
+    method: string,
+    streamId: string,
+    action: string | undefined,
+  ) {
+    const route =
+      action === undefined
+        ? "status"
+        : action === "close"
+          ? "close"
+          : action === "reclaim"
+            ? "reclaim"
+            : action === "reclaim-unverified"
+              ? "reclaimUnverified"
+              : undefined;
+    if (route === undefined) {
+      json(res, 404, { error: "not-found" });
+      return;
+    }
+    if ((route === "status") !== (method === "GET")) {
+      res.setHeader("Allow", route === "status" ? "GET" : "POST");
+      json(res, 405, { error: "method-not-allowed" });
+      return;
+    }
+    // Per client first (one noisy client cannot drain the global budget
+    // beyond its own share), then the IP-independent global cap.
+    let retryAfter = takeRefundBudget(clientKey(req));
+    if (retryAfter === 0) retryAfter = takeGlobalRefundBudget();
+    if (retryAfter > 0) {
+      res.setHeader("Retry-After", String(retryAfter));
+      json(res, 429, { ok: false, error: "rate-limited" });
+      return;
+    }
+    let result: RefundRelayResponse;
+    if (route === "status") {
+      result = await relay.status(streamId);
+    } else if (route === "reclaim") {
+      // Permissionless: no body is needed, and any body is ignored.
+      await readBody(req, MAX_REFUND_BODY_BYTES).catch(() => undefined);
+      result = await relay.reclaim(streamId);
+    } else {
+      let body: unknown;
+      try {
+        body = JSON.parse(
+          (await readBody(req, MAX_REFUND_BODY_BYTES)).toString("utf8"),
+        );
+      } catch (error) {
+        if (error instanceof BodyTooLargeError) {
+          json(res, 413, { ok: false, error: "body-too-large" });
+        } else {
+          json(res, 400, { ok: false, error: "invalid-json" });
+        }
+        return;
+      }
+      result =
+        route === "close"
+          ? await relay.close(streamId, body)
+          : await relay.reclaimUnverified(streamId, body);
+    }
+    if (result.retryAfterSeconds !== undefined) {
+      res.setHeader("Retry-After", String(result.retryAfterSeconds));
+    }
+    json(res, result.status, result.body);
+  }
+
+  return {
+    httpServer,
+    listen: (port, host = "127.0.0.1") =>
+      new Promise((resolve, reject) => {
+        const onError = (error: Error) => reject(error);
+        httpServer.once("error", onError);
+        httpServer.listen(port, host, () => {
+          httpServer.removeListener("error", onError);
+          const address = httpServer.address() as AddressInfo;
+          resolve({ port: address.port, host });
+        });
+      }),
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        httpServer.close((error) => (error ? reject(error) : resolve()));
+      }),
+  };
+}
+
+function digest(value: string): Buffer {
+  return createHash("sha256").update(value, "utf8").digest();
+}
+
+function json(res: ServerResponse, status: number, body: unknown): void {
+  res
+    .writeHead(status, {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    })
+    .end(
+      JSON.stringify(body, (_key, value) =>
+        typeof value === "bigint" ? value.toString() : value,
+      ),
+    );
+}
+
+async function readBody(
+  req: IncomingMessage,
+  limit: number = MAX_BODY_BYTES,
+): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer;
+    size += buffer.length;
+    if (size > limit) {
+      throw new BodyTooLargeError("request body too large");
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+// ── Building the facilitator ────────────────────────────────────────────────
+
+export interface OpenerFacilitatorOptions {
+  readonly network: Network;
+  readonly rpcUrl: string;
+  readonly relayerPrivateKey: Hex;
+  readonly factoryAddress: Address;
+  readonly escrowAddress: Address;
+  readonly assetAllowlist: readonly Address[];
+  /** Default: a {@link RegistryListingResolver} on the public registry. */
+  readonly listingResolver?: OperatorSignedListingResolver;
+  readonly registryUrl?: string;
+  readonly listingCacheSeconds?: number;
+  readonly receiptTimeoutMs?: number;
+  /** Smallest accepted payment, base units. Default 10000 (0.01 USDC). */
+  readonly minAmount?: bigint;
+  /**
+   * Mount the gasless refund relay (metrik-agent#119) on the same relayer,
+   * sharing its serialized submission queue. Omit to run without it.
+   */
+  readonly refundRelay?: OpenerRefundRelayOptions;
+}
+
+/** Refund-relay options of {@link buildOpenerFacilitator}. */
+export interface OpenerRefundRelayOptions {
+  /** Oracle base URL serving `GET /checkpoint/proof?streamId=`. */
+  readonly oracleUrl: string;
+  /** Public origin of this service, for absolute links in responses. */
+  readonly publicBaseUrl?: string;
+  readonly submissionsPerStreamPerMinute?: number;
+  readonly submissionsPerMinute?: number;
+  readonly oracleTimeoutMs?: number;
+  readonly readCacheSeconds?: number;
+  readonly fetch?: typeof fetch;
+}
+
+/**
+ * Builds an `x402Facilitator` whose ONLY scheme is {@link MetrikOpenerExactScheme}
+ * on one network, and proves the on-chain wiring (chain id, factory code,
+ * factory → escrow, factory token allowlisted) before returning.
+ */
+export async function buildOpenerFacilitator(
+  options: OpenerFacilitatorOptions,
+): Promise<{
+  readonly facilitator: x402Facilitator;
+  readonly scheme: MetrikOpenerExactScheme;
+  readonly binding: OpenerFacilitatorBinding;
+  /** Present when `options.refundRelay` was given. */
+  readonly refundRelay?: OpenerRefundRelay;
+}> {
+  const chainId = chainIdFromNetwork(options.network);
+  const chain = chainForChainId(chainId, options.rpcUrl);
+  const account = privateKeyToAccount(options.relayerPrivateKey);
+  const transport = http(options.rpcUrl);
+  const publicClient = createPublicClient({ chain, transport });
+  const walletClient = createWalletClient({ account, chain, transport });
+  // ONE queue for every transaction this relayer key sends.
+  const relayerQueue = new RelayerQueue();
+  const receiptTimeoutMs = options.receiptTimeoutMs;
+
+  const scheme = new MetrikOpenerExactScheme({
+    relayerQueue,
+    advertiseRefundRelay: options.refundRelay !== undefined,
+    network: options.network,
+    factoryAddress: options.factoryAddress,
+    escrowAddress: options.escrowAddress,
+    assetAllowlist: options.assetAllowlist,
+    publicClient,
+    walletClient,
+    listingResolver:
+      options.listingResolver ??
+      new RegistryListingResolver({
+        registryUrl: options.registryUrl ?? DEFAULT_METRIK_PUBLIC_REGISTRY_URL,
+        cacheSeconds:
+          options.listingCacheSeconds ?? DEFAULT_LISTING_CACHE_SECONDS,
+      }),
+    ...(options.receiptTimeoutMs === undefined
+      ? {}
+      : { receiptTimeoutMs: options.receiptTimeoutMs }),
+    ...(options.minAmount === undefined
+      ? {}
+      : { minAmount: options.minAmount }),
+  });
+  const binding = await scheme.init();
+  let refundRelay: OpenerRefundRelay | undefined;
+  if (options.refundRelay !== undefined) {
+    const relay = options.refundRelay;
+    refundRelay = new OpenerRefundRelay({
+      network: options.network,
+      factoryAddress: options.factoryAddress,
+      escrowAddress: options.escrowAddress,
+      oracleUrl: relay.oracleUrl,
+      publicClient,
+      walletClient,
+      relayerQueue,
+      ...(receiptTimeoutMs === undefined ? {} : { receiptTimeoutMs }),
+      ...(relay.publicBaseUrl === undefined
+        ? {}
+        : { publicBaseUrl: relay.publicBaseUrl }),
+      ...(relay.submissionsPerStreamPerMinute === undefined
+        ? {}
+        : {
+            maxSubmissionsPerStreamPerMinute:
+              relay.submissionsPerStreamPerMinute,
+          }),
+      ...(relay.submissionsPerMinute === undefined
+        ? {}
+        : { maxSubmissionsPerMinute: relay.submissionsPerMinute }),
+      ...(relay.oracleTimeoutMs === undefined
+        ? {}
+        : { oracleTimeoutMs: relay.oracleTimeoutMs }),
+      ...(relay.fetch === undefined ? {} : { fetch: relay.fetch }),
+      ...(relay.readCacheSeconds === undefined
+        ? {}
+        : { readCacheSeconds: relay.readCacheSeconds }),
+    });
+    await refundRelay.init();
+  }
+  const facilitator = new x402Facilitator().register(options.network, scheme);
+  return {
+    facilitator,
+    scheme,
+    binding,
+    ...(refundRelay === undefined ? {} : { refundRelay }),
+  };
+}
+
+// ── Environment configuration ────────────────────────────────────────────────
+
+export interface OpenerFacilitatorEnvConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly network: Network;
+  readonly rpcUrl: string;
+  readonly relayerPrivateKey: Hex;
+  readonly authToken: string;
+  readonly requireAuthOnVerify: boolean;
+  readonly factoryAddress: Address;
+  readonly escrowAddress: Address;
+  readonly assetAllowlist: readonly Address[];
+  readonly registryUrl: string;
+  readonly listingCacheSeconds: number;
+  readonly receiptTimeoutMs: number;
+  readonly minAmount: bigint;
+  readonly settleRateLimitPerMinute: number;
+  /** The gasless refund relay; undefined when switched off. */
+  readonly refundRelay?: OpenerRefundRelayEnvConfig;
+}
+
+export interface OpenerRefundRelayEnvConfig {
+  readonly oracleUrl: string;
+  readonly publicBaseUrl?: string;
+  readonly rateLimitPerIpPerMinute: number;
+  readonly globalRateLimitPerMinute: number;
+  readonly readCacheSeconds: number;
+  readonly submissionsPerStreamPerMinute: number;
+  readonly submissionsPerMinute: number;
+  readonly trustProxy: boolean;
+}
+
+/**
+ * Parses the facilitator's env contract. OFF unless
+ * `METRIK_OPENER_FACILITATOR_ENABLED` is truthy, and then every required
+ * variable must be present (fail closed):
+ *
+ * - `METRIK_OPENER_FACILITATOR_ENABLED` — `1`/`true`/`yes`/`on`.
+ * - `METRIK_OPENER_FACILITATOR_RPC_URL` (required).
+ * - `METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY` (required) — pays gas only.
+ * - `METRIK_OPENER_FACILITATOR_AUTH_TOKEN` (required, >= 32 chars) — bearer on `/settle`.
+ * - `METRIK_OPENER_FACILITATOR_NETWORK` — CAIP-2 id; default the registry's
+ *   default network. Factory, escrow, USDC and oracle default to THAT network's
+ *   registry entry; on a network the registry does not know (or one with no
+ *   opener factory) each must be given explicitly.
+ * - `METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS` — default the network's registered factory.
+ * - `METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS` — default the network's registered `StreamEscrowV2`.
+ * - `METRIK_OPENER_FACILITATOR_ASSETS` — comma-separated allowlist; default the network's USDC.
+ * - `METRIK_OPENER_FACILITATOR_REGISTRY_URL` — default the public listings registry.
+ * - `METRIK_OPENER_FACILITATOR_LISTING_CACHE_SECONDS` — default 60.
+ * - `METRIK_OPENER_FACILITATOR_RECEIPT_TIMEOUT_SECONDS` — default 60.
+ * - `METRIK_OPENER_FACILITATOR_REQUIRE_AUTH_ON_VERIFY` — default ON; `0` opts out.
+ * - `METRIK_OPENER_FACILITATOR_MIN_AMOUNT` — smallest payment, base units; default 10000 (0.01 USDC).
+ * - `METRIK_OPENER_FACILITATOR_SETTLE_RATE_LIMIT_PER_MINUTE` — per token; default 60.
+ * - `METRIK_OPENER_FACILITATOR_PORT` / `PORT` — default 8788.
+ * - `METRIK_OPENER_FACILITATOR_HOST` — default `127.0.0.1`.
+ *
+ * Gasless refund relay (metrik-agent#119), ON with the facilitator unless
+ * switched off. Its endpoints are public and unauthenticated by design:
+ *
+ * - `METRIK_OPENER_FACILITATOR_REFUND_RELAY` — default on; `0` switches it off
+ *   (and a gateway, which promises refunds without ETH, then refuses to start).
+ * - `METRIK_OPENER_FACILITATOR_ORACLE_URL` — oracle serving
+ *   `/checkpoint/proof`; default the network's registered oracle, required
+ *   on a network the registry does not know.
+ * - `METRIK_OPENER_FACILITATOR_PUBLIC_URL` — public origin, for absolute links.
+ * - `METRIK_OPENER_FACILITATOR_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE` — default 30.
+ * - `METRIK_OPENER_FACILITATOR_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE` — all clients; default 120.
+ * - `METRIK_OPENER_FACILITATOR_REFUND_READ_CACHE_SECONDS` — per-stream status/proof reuse; default 5 (0 = off).
+ * - `METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE` — relayed
+ *   transactions per stream per minute; default 3.
+ * - `METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_MINUTE` — all streams; default 30.
+ * - `METRIK_OPENER_FACILITATOR_TRUST_PROXY` — key the per-IP limit on the
+ *   right-most `X-Forwarded-For` hop; default off. Enable only behind a proxy.
+ */
+export function parseOpenerFacilitatorEnvConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): OpenerFacilitatorEnvConfig | undefined {
+  if (
+    !parseBoolean(
+      env.METRIK_OPENER_FACILITATOR_ENABLED,
+      "METRIK_OPENER_FACILITATOR_ENABLED",
+    )
+  ) {
+    return undefined;
+  }
+  const network = (env.METRIK_OPENER_FACILITATOR_NETWORK?.trim() ||
+    defaultNetwork().caip2) as Network;
+  // Validates the CAIP-2 shape (eip155:<chainId>) before anything else.
+  chainIdFromNetwork(network);
+  // Defaults come from the registry entry for THIS network, never from
+  // another network's: a factory is bound to one escrow on one chain.
+  const registered = networkForCaip2(network);
+  const rpcUrl = requireEnv(env, "METRIK_OPENER_FACILITATOR_RPC_URL");
+  // eslint-disable-next-line no-new -- validates the URL is well-formed.
+  new URL(rpcUrl);
+  const relayerPrivateKey = requireEnv(
+    env,
+    "METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY",
+  );
+  if (
+    !isHex(relayerPrivateKey, { strict: true }) ||
+    relayerPrivateKey.length !== 66
+  ) {
+    // Never echo the value.
+    throw new Error(
+      "METRIK_OPENER_FACILITATOR_RELAYER_PRIVATE_KEY must be a 32-byte 0x-hex private key",
+    );
+  }
+  const authToken = requireEnv(env, "METRIK_OPENER_FACILITATOR_AUTH_TOKEN");
+  if (authToken.length < MIN_AUTH_TOKEN_LENGTH) {
+    throw new Error(
+      `METRIK_OPENER_FACILITATOR_AUTH_TOKEN must be at least ${MIN_AUTH_TOKEN_LENGTH} characters`,
+    );
+  }
+  const factoryRaw = env.METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS?.trim();
+  let factoryAddress: Address;
+  if (factoryRaw === undefined || factoryRaw.length === 0) {
+    if (registered?.openerFactory == null) {
+      throw new Error(
+        `METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS is required on ${network}: the network registry has no opener factory for it`,
+      );
+    }
+    factoryAddress = registered.openerFactory.address;
+  } else {
+    factoryAddress = requireAddress(
+      env,
+      "METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS",
+    );
+  }
+  const escrowRaw = env.METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS?.trim();
+  let escrowAddress: Address;
+  if (escrowRaw === undefined || escrowRaw.length === 0) {
+    if (registered === undefined) {
+      throw new Error(
+        `METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS is required on ${network}: the network registry does not know it`,
+      );
+    }
+    escrowAddress = registered.escrow.address;
+  } else {
+    escrowAddress = requireAddress(
+      env,
+      "METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS",
+    );
+  }
+  const assetsRaw = env.METRIK_OPENER_FACILITATOR_ASSETS?.trim();
+  let assetAllowlist: Address[];
+  if (assetsRaw === undefined || assetsRaw.length === 0) {
+    if (registered === undefined) {
+      throw new Error(
+        `METRIK_OPENER_FACILITATOR_ASSETS is required on ${network}: the network registry does not know it`,
+      );
+    }
+    assetAllowlist = [registered.usdc.address];
+  } else {
+    assetAllowlist = assetsRaw
+      .split(",")
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0)
+      .map((value) => {
+        if (!isAddress(value)) {
+          throw new Error(
+            `METRIK_OPENER_FACILITATOR_ASSETS entry is not an address: ${value}`,
+          );
+        }
+        return getAddress(value);
+      });
+  }
+  const registryUrl =
+    env.METRIK_OPENER_FACILITATOR_REGISTRY_URL?.trim() ||
+    DEFAULT_METRIK_PUBLIC_REGISTRY_URL;
+  // eslint-disable-next-line no-new -- validates the URL is well-formed.
+  new URL(registryUrl);
+  const listingCacheSeconds = nonNegativeInt(
+    env,
+    "METRIK_OPENER_FACILITATOR_LISTING_CACHE_SECONDS",
+    DEFAULT_LISTING_CACHE_SECONDS,
+  );
+  const receiptTimeoutSeconds = positiveInt(
+    env,
+    "METRIK_OPENER_FACILITATOR_RECEIPT_TIMEOUT_SECONDS",
+    60,
+  );
+  const portRaw = env.METRIK_OPENER_FACILITATOR_PORT ?? env.PORT ?? "8788";
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`invalid port: ${portRaw}`);
+  }
+  const refundRelay = parseRefundRelayEnv(env, network);
+  return {
+    ...(refundRelay === undefined ? {} : { refundRelay }),
+    host: env.METRIK_OPENER_FACILITATOR_HOST?.trim() || "127.0.0.1",
+    port,
+    network,
+    rpcUrl,
+    relayerPrivateKey: relayerPrivateKey as Hex,
+    authToken,
+    requireAuthOnVerify:
+      (env.METRIK_OPENER_FACILITATOR_REQUIRE_AUTH_ON_VERIFY?.trim() ?? "") ===
+      ""
+        ? true
+        : parseBoolean(
+            env.METRIK_OPENER_FACILITATOR_REQUIRE_AUTH_ON_VERIFY,
+            "METRIK_OPENER_FACILITATOR_REQUIRE_AUTH_ON_VERIFY",
+          ),
+    minAmount: BigInt(
+      positiveInt(env, "METRIK_OPENER_FACILITATOR_MIN_AMOUNT", 10_000),
+    ),
+    settleRateLimitPerMinute: positiveInt(
+      env,
+      "METRIK_OPENER_FACILITATOR_SETTLE_RATE_LIMIT_PER_MINUTE",
+      DEFAULT_SETTLE_RATE_LIMIT_PER_MINUTE,
+    ),
+    factoryAddress,
+    escrowAddress,
+    assetAllowlist,
+    registryUrl,
+    listingCacheSeconds,
+    receiptTimeoutMs: receiptTimeoutSeconds * 1000,
+  };
+}
+
+function parseRefundRelayEnv(
+  env: NodeJS.ProcessEnv,
+  network: Network,
+): OpenerRefundRelayEnvConfig | undefined {
+  const raw = env.METRIK_OPENER_FACILITATOR_REFUND_RELAY?.trim() ?? "";
+  if (
+    raw.length > 0 &&
+    !parseBoolean(raw, "METRIK_OPENER_FACILITATOR_REFUND_RELAY")
+  ) {
+    return undefined;
+  }
+  const oracleRaw = env.METRIK_OPENER_FACILITATOR_ORACLE_URL?.trim();
+  let oracleUrl: string;
+  if (oracleRaw === undefined || oracleRaw.length === 0) {
+    const registered = networkForCaip2(network);
+    if (registered === undefined) {
+      throw new Error(
+        `METRIK_OPENER_FACILITATOR_ORACLE_URL is required on ${network}: the network registry does not know it (or set METRIK_OPENER_FACILITATOR_REFUND_RELAY=0)`,
+      );
+    }
+    oracleUrl = registered.oracleBaseUrl;
+  } else {
+    oracleUrl = requireHttpUrl(
+      oracleRaw,
+      "METRIK_OPENER_FACILITATOR_ORACLE_URL",
+    );
+  }
+  const publicRaw = env.METRIK_OPENER_FACILITATOR_PUBLIC_URL?.trim();
+  const publicBaseUrl =
+    publicRaw === undefined || publicRaw.length === 0
+      ? undefined
+      : requireHttpUrl(publicRaw, "METRIK_OPENER_FACILITATOR_PUBLIC_URL");
+  const trustRaw = env.METRIK_OPENER_FACILITATOR_TRUST_PROXY?.trim() ?? "";
+  return {
+    oracleUrl,
+    ...(publicBaseUrl === undefined ? {} : { publicBaseUrl }),
+    rateLimitPerIpPerMinute: positiveInt(
+      env,
+      "METRIK_OPENER_FACILITATOR_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE",
+      DEFAULT_REFUND_RATE_LIMIT_PER_IP_PER_MINUTE,
+    ),
+    globalRateLimitPerMinute: positiveInt(
+      env,
+      "METRIK_OPENER_FACILITATOR_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE",
+      DEFAULT_REFUND_GLOBAL_RATE_LIMIT_PER_MINUTE,
+    ),
+    readCacheSeconds: nonNegativeInt(
+      env,
+      "METRIK_OPENER_FACILITATOR_REFUND_READ_CACHE_SECONDS",
+      DEFAULT_REFUND_READ_CACHE_SECONDS,
+    ),
+    submissionsPerStreamPerMinute: positiveInt(
+      env,
+      "METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE",
+      DEFAULT_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE,
+    ),
+    submissionsPerMinute: positiveInt(
+      env,
+      "METRIK_OPENER_FACILITATOR_REFUND_SUBMISSIONS_PER_MINUTE",
+      DEFAULT_REFUND_SUBMISSIONS_PER_MINUTE,
+    ),
+    trustProxy:
+      trustRaw.length > 0 &&
+      parseBoolean(trustRaw, "METRIK_OPENER_FACILITATOR_TRUST_PROXY"),
+  };
+}
+
+function requireHttpUrl(value: string, name: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${name} must be an absolute URL`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`${name} must be an http(s) URL`);
+  }
+  return value.replace(/\/+$/, "");
+}
+
+/** Builds and starts the facilitator service entirely from the environment. */
+export async function startOpenerFacilitatorServerFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<
+  OpenerFacilitatorServer & {
+    readonly boundPort: number;
+    readonly binding: OpenerFacilitatorBinding;
+    readonly refundRelayEnabled: boolean;
+  }
+> {
+  const config = parseOpenerFacilitatorEnvConfig(env);
+  if (config === undefined) {
+    throw new Error(
+      "the Metrik x402 opener facilitator is OFF: set METRIK_OPENER_FACILITATOR_ENABLED=1 (plus its required variables) to run it",
+    );
+  }
+  const { facilitator, binding, refundRelay } = await buildOpenerFacilitator({
+    network: config.network,
+    rpcUrl: config.rpcUrl,
+    relayerPrivateKey: config.relayerPrivateKey,
+    factoryAddress: config.factoryAddress,
+    escrowAddress: config.escrowAddress,
+    assetAllowlist: config.assetAllowlist,
+    registryUrl: config.registryUrl,
+    listingCacheSeconds: config.listingCacheSeconds,
+    receiptTimeoutMs: config.receiptTimeoutMs,
+    minAmount: config.minAmount,
+    ...(config.refundRelay === undefined
+      ? {}
+      : {
+          refundRelay: {
+            oracleUrl: config.refundRelay.oracleUrl,
+            submissionsPerStreamPerMinute:
+              config.refundRelay.submissionsPerStreamPerMinute,
+            submissionsPerMinute: config.refundRelay.submissionsPerMinute,
+            readCacheSeconds: config.refundRelay.readCacheSeconds,
+            ...(config.refundRelay.publicBaseUrl === undefined
+              ? {}
+              : { publicBaseUrl: config.refundRelay.publicBaseUrl }),
+          },
+        }),
+  });
+  const server = createOpenerFacilitatorServer({
+    facilitator,
+    authToken: config.authToken,
+    requireAuthOnVerify: config.requireAuthOnVerify,
+    settleRateLimitPerMinute: config.settleRateLimitPerMinute,
+    ...(refundRelay === undefined || config.refundRelay === undefined
+      ? {}
+      : {
+          refundRelay,
+          refundRateLimitPerIpPerMinute:
+            config.refundRelay.rateLimitPerIpPerMinute,
+          refundGlobalRateLimitPerMinute:
+            config.refundRelay.globalRateLimitPerMinute,
+          trustProxy: config.refundRelay.trustProxy,
+        }),
+  });
+  const { port } = await server.listen(config.port, config.host);
+  return Object.assign(server, {
+    boundPort: port,
+    binding,
+    refundRelayEnabled: refundRelay !== undefined,
+  });
+}
+
+function parseBoolean(raw: string | undefined, name: string): boolean {
+  const value = raw?.trim().toLowerCase();
+  if (value === undefined || value.length === 0) return false;
+  if (["1", "true", "yes", "on"].includes(value)) return true;
+  if (["0", "false", "no", "off"].includes(value)) return false;
+  throw new Error(`invalid ${name}: ${value} (expected a boolean)`);
+}
+
+function requireEnv(env: NodeJS.ProcessEnv, name: string): string {
+  const value = env[name]?.trim();
+  if (value === undefined || value.length === 0) {
+    throw new Error(`${name} is required (fail-closed)`);
+  }
+  return value;
+}
+
+function requireAddress(env: NodeJS.ProcessEnv, name: string): Address {
+  const value = requireEnv(env, name);
+  if (!isAddress(value)) {
+    throw new Error(`${name} must be an EVM address`);
+  }
+  return getAddress(value);
+}
+
+function positiveInt(
+  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 nonNegativeInt(
+  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 non-negative integer)`,
+    );
+  }
+  return value;
+}