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

package/dist/x402-opener/facilitator-server.js

@@ -0,0 +1,696 @@
+import { timingSafeEqual, createHash } from "node:crypto";
+import { createServer, } from "node:http";
+import { networkForCaip2 } from "@absol-labs/sdk";
+import { x402Facilitator } from "@x402/core/facilitator";
+import { createPublicClient, createWalletClient, getAddress, http, isAddress, isHex, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { DEFAULT_METRIK_PUBLIC_REGISTRY_URL } from "../discovery/registry.js";
+import { DEFAULT_LISTING_CACHE_SECONDS, RegistryListingResolver, } from "./listing-resolver.js";
+import { DEFAULT_REFUND_READ_CACHE_SECONDS, DEFAULT_REFUND_SUBMISSIONS_PER_MINUTE, DEFAULT_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE, OpenerRefundRelay, } from "./refund-relay.js";
+import { RelayerQueue } from "./relayer-queue.js";
+import { MetrikOpenerExactScheme, } 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 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) {
+    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();
+    const allowSettle = (key) => {
+        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 = () => {
+        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();
+    /** Seconds until the client's window resets, or 0 when the request is allowed. */
+    const takeRefundBudget = (client) => {
+        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) => {
+        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) => {
+        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, res) {
+        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;
+            try {
+                streamId = decodeURIComponent(streamsRoute[1]);
+            }
+            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;
+            try {
+                body = JSON.parse((await readBody(req)).toString("utf8"));
+            }
+            catch {
+                json(res, 400, { error: "invalid-json" });
+                return;
+            }
+            const request = body;
+            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;
+            const requirements = request.paymentRequirements;
+            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, res, relay, method, streamId, action) {
+        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;
+        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;
+            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) => reject(error);
+            httpServer.once("error", onError);
+            httpServer.listen(port, host, () => {
+                httpServer.removeListener("error", onError);
+                const address = httpServer.address();
+                resolve({ port: address.port, host });
+            });
+        }),
+        close: () => new Promise((resolve, reject) => {
+            httpServer.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+}
+function digest(value) {
+    return createHash("sha256").update(value, "utf8").digest();
+}
+function json(res, status, body) {
+    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, limit = MAX_BODY_BYTES) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > limit) {
+            throw new BodyTooLargeError("request body too large");
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * 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) {
+    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;
+    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 }),
+    };
+}
+/**
+ * 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 = process.env) {
+    if (!parseBoolean(env.METRIK_OPENER_FACILITATOR_ENABLED, "METRIK_OPENER_FACILITATOR_ENABLED")) {
+        return undefined;
+    }
+    const network = (env.METRIK_OPENER_FACILITATOR_NETWORK?.trim() ||
+        defaultNetwork().caip2);
+    // 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;
+    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;
+    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;
+    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,
+        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, network) {
+    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;
+    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, name) {
+    let 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 = process.env) {
+    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, name) {
+    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, name) {
+    const value = env[name]?.trim();
+    if (value === undefined || value.length === 0) {
+        throw new Error(`${name} is required (fail-closed)`);
+    }
+    return value;
+}
+function requireAddress(env, name) {
+    const value = requireEnv(env, name);
+    if (!isAddress(value)) {
+        throw new Error(`${name} must be an EVM address`);
+    }
+    return getAddress(value);
+}
+function positiveInt(env, name, fallback) {
+    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, name, fallback) {
+    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;
+}
+//# sourceMappingURL=facilitator-server.js.map