@absol-labs/agent 0.9.1 → 0.11.0

package/src/x402/facilitator-server.ts

@@ -0,0 +1,445 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { timingSafeEqual } from "node:crypto";
+
+import { isAddress, isHex, type Hex } from "viem";
+
+import {
+  createOracleDeliveryOracle,
+  DEFAULT_DELIVERY_FRESHNESS_SECONDS,
+  DEFAULT_METRIK_ORACLE_URL,
+} from "./delivery-oracle.js";
+import { createRegistryResourceIndex } from "./resource-index.js";
+import {
+  createX402PaymentSettler,
+  createX402PaymentVerifier,
+  relayerAddress,
+} from "./relayer.js";
+import {
+  DEFAULT_SETTLEMENT_SCOPE,
+  MetrikVerifiedDeliveryFacilitator,
+  RelayerNotConfiguredError,
+  type IndeterminatePolicy,
+  type SettlementScope,
+} from "./verified-delivery-facilitator.js";
+
+/**
+ * Reference HTTP server for Metrik's x402 facilitator: `POST /verify`,
+ * `POST /settle`, `GET /supported` — the three endpoints the x402 facilitator
+ * interface defines, with Metrik's verified-delivery gate wired into `/verify`.
+ *
+ * Point any x402 resource server at this with
+ * `facilitator: { url: "https://<host>" }` and it becomes a resource server
+ * whose payments stop when the seller stops delivering.
+ */
+
+const MAX_BODY_BYTES = 256 * 1024;
+
+export interface MetrikFacilitatorServerConfig {
+  readonly facilitator: MetrikVerifiedDeliveryFacilitator;
+  /** Present only to report settlement availability on `/supported`. */
+  readonly settlementEnabled: boolean;
+  /**
+   * Shared secret required on `POST /settle`.
+   *
+   * `/settle` spends the operator's gas: it makes the relayer sign and
+   * broadcast. It is not a public read, and leaving it open on `0.0.0.0` makes
+   * it a permissionless "make the relayer broadcast for me" endpoint. `/verify`
+   * and `/supported` stay public — they cost nothing and are genuinely useful
+   * to anyone.
+   *
+   * Omit ONLY for a verify-only server. `startMetrikFacilitatorServerFromEnv`
+   * refuses to start a settling facilitator without one.
+   */
+  readonly settlementToken?: string;
+}
+
+export interface MetrikFacilitatorServer {
+  readonly httpServer: Server;
+  listen(port: number, host?: string): Promise<{ port: number; host: string }>;
+  close(): Promise<void>;
+}
+
+export function createMetrikFacilitatorServer(
+  config: MetrikFacilitatorServerConfig,
+): MetrikFacilitatorServer {
+  const httpServer = createServer((req, res) => {
+    handle(req, res, config).catch((error) => {
+      if (error instanceof RelayerNotConfiguredError) {
+        writeJson(res, 503, {
+          success: false,
+          errorReason: "unexpected_settle_error",
+          transaction: "",
+          error: error.message,
+        });
+        return;
+      }
+      logError("unhandled request error", error);
+      writeJson(res, 500, { error: "internal-error" });
+    });
+  });
+
+  return {
+    httpServer,
+    listen: (port, host = "0.0.0.0") =>
+      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()));
+      }),
+  };
+}
+
+async function handle(
+  req: IncomingMessage,
+  res: ServerResponse,
+  config: MetrikFacilitatorServerConfig,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const path = url.pathname.replace(/\/+$/, "") || "/";
+
+  if (req.method === "GET" && (path === "/supported" || path === "/")) {
+    writeJson(res, 200, {
+      ...config.facilitator.supported(),
+      settlementEnabled: config.settlementEnabled,
+    });
+    return;
+  }
+  if (req.method !== "POST") {
+    writeJson(res, 405, { error: "method-not-allowed" });
+    return;
+  }
+  if (path !== "/verify" && path !== "/settle") {
+    writeJson(res, 404, { error: "not-found" });
+    return;
+  }
+
+  // Authenticate BEFORE reading the body: an unauthenticated caller must not be
+  // able to make this process do work, parse input, or reach the chain.
+  if (path === "/settle" && !isAuthorizedSettle(req, config)) {
+    writeJson(res, 401, {
+      success: false,
+      errorReason: "invalid_payment",
+      transaction: "",
+      error:
+        "POST /settle requires the facilitator's bearer token. It spends the operator's gas.",
+    });
+    return;
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    writeJson(res, 400, { error: "invalid-json" });
+    return;
+  }
+
+  if (path === "/verify") {
+    writeJson(res, 200, await config.facilitator.verify(body));
+    return;
+  }
+  writeJson(res, 200, await config.facilitator.settle(body));
+}
+
+/**
+ * Constant-time bearer check. A missing configured token denies, so a
+ * misconfiguration can never silently open the endpoint.
+ */
+function isAuthorizedSettle(
+  req: IncomingMessage,
+  config: MetrikFacilitatorServerConfig,
+): boolean {
+  const expected = config.settlementToken;
+  if (expected === undefined || expected.length === 0) {
+    return false;
+  }
+  const header = req.headers.authorization;
+  if (typeof header !== "string") {
+    return false;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  if (match === null) {
+    return false;
+  }
+  const presented = Buffer.from(match[1] as string, "utf8");
+  const target = Buffer.from(expected, "utf8");
+  // `timingSafeEqual` throws on a length mismatch, which would itself leak the
+  // length, so compare a fixed-width digest-shaped pair instead: pad both to the
+  // longer length and AND in the length equality.
+  const width = Math.max(presented.length, target.length);
+  const a = Buffer.alloc(width);
+  const b = Buffer.alloc(width);
+  presented.copy(a);
+  target.copy(b);
+  return timingSafeEqual(a, b) && presented.length === target.length;
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer;
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) {
+      throw new Error("request body too large");
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  res
+    .writeHead(status, { "Content-Type": "application/json" })
+    .end(JSON.stringify(body));
+}
+
+function logError(context: string, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[metrik-x402-facilitator] ${context}: ${message}`);
+}
+
+// ── Environment configuration ────────────────────────────────────────────────
+
+export interface MetrikFacilitatorEnvConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly chainId: number;
+  readonly rpcUrl: string;
+  readonly oracleUrl: string;
+  readonly registryUrl?: string;
+  readonly freshnessWindowSeconds: number;
+  readonly indeterminatePolicy: IndeterminatePolicy;
+  /** `undefined` means settlement is DISABLED — `/settle` will refuse loudly. */
+  readonly relayerPrivateKey?: Hex;
+  /** Required whenever a relayer is configured. Guards `POST /settle`. */
+  readonly settlementToken?: string;
+  /** Token contracts the relayer may be asked to call. Defaults to chain USDC. */
+  readonly settlementAssetAllowlist?: readonly string[];
+  readonly settlementScope: SettlementScope;
+}
+
+/**
+ * Env contract:
+ * - `METRIK_X402_RPC_URL` (required) — RPC for balance checks and, when a relayer
+ *   is configured, for broadcasting.
+ * - `METRIK_X402_RELAYER_PRIVATE_KEY` (required unless
+ *   `METRIK_X402_ALLOW_VERIFY_ONLY=true`) — the relayer that broadcasts EIP-3009
+ *   transfers and pays gas.
+ * - `METRIK_X402_ALLOW_VERIFY_ONLY` (optional) — explicit opt-in to booting a
+ *   verify-only facilitator. Without it, a missing relayer key is a STARTUP
+ *   FAILURE rather than a server that silently never settles.
+ * - `METRIK_X402_CHAIN_ID` (optional) — default `84532`.
+ * - `METRIK_X402_ORACLE_URL` (optional) — default the public Metrik oracle.
+ * - `METRIK_X402_REGISTRY_URL` (optional) — listing source; default the oracle's
+ *   public credential-free registry.
+ * - `METRIK_X402_FRESHNESS_SECONDS` (optional) — default
+ *   {@link DEFAULT_DELIVERY_FRESHNESS_SECONDS}.
+ * - `METRIK_X402_INDETERMINATE_POLICY` (optional) — `allow` (default) or `deny`.
+ * - `PORT` / `METRIK_X402_PORT` (optional) — default `8788`.
+ * - `METRIK_X402_HOST` (optional) — default `0.0.0.0`.
+ */
+export function parseMetrikFacilitatorEnvConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): MetrikFacilitatorEnvConfig {
+  const rpcUrl = env.METRIK_X402_RPC_URL;
+  if (rpcUrl === undefined || rpcUrl.trim().length === 0) {
+    throw new Error("METRIK_X402_RPC_URL is required (fail-closed)");
+  }
+
+  const rawKey = env.METRIK_X402_RELAYER_PRIVATE_KEY?.trim();
+  const allowVerifyOnly = env.METRIK_X402_ALLOW_VERIFY_ONLY === "true";
+  let relayerPrivateKey: Hex | undefined;
+  if (rawKey !== undefined && rawKey.length > 0) {
+    if (!isHex(rawKey, { strict: true }) || rawKey.length !== 66) {
+      throw new Error(
+        "METRIK_X402_RELAYER_PRIVATE_KEY must be a 32-byte 0x-prefixed hex private key",
+      );
+    }
+    relayerPrivateKey = rawKey;
+  } else if (!allowVerifyOnly) {
+    throw new Error(
+      "METRIK_X402_RELAYER_PRIVATE_KEY is required to settle payments. " +
+        "This facilitator will NOT start without one, because a facilitator that " +
+        "accepts /settle and never broadcasts is worse than one that is absent. " +
+        "Set METRIK_X402_ALLOW_VERIFY_ONLY=true to deliberately run verify-only.",
+    );
+  }
+
+  // `/settle` makes the relayer sign and pay gas. An open one is a
+  // permissionless "broadcast for me" endpoint, so a settling facilitator
+  // cannot boot without a token. Fail closed at startup, not at request time.
+  const settlementToken = env.METRIK_X402_FACILITATOR_TOKEN?.trim();
+  if (relayerPrivateKey !== undefined) {
+    if (settlementToken === undefined || settlementToken.length < 32) {
+      throw new Error(
+        "METRIK_X402_FACILITATOR_TOKEN is required (at least 32 characters) whenever a " +
+          "settlement relayer is configured. POST /settle spends the operator's gas and " +
+          "binds 0.0.0.0; without a token anyone who can reach it can make the relayer " +
+          "broadcast and pay for it.",
+      );
+    }
+  }
+
+  const rawAllowlist = (env.METRIK_X402_SETTLEMENT_ASSETS ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+  for (const candidate of rawAllowlist) {
+    if (!isAddress(candidate)) {
+      throw new Error(
+        `METRIK_X402_SETTLEMENT_ASSETS must contain only EVM addresses (got ${candidate})`,
+      );
+    }
+  }
+
+  const rawScope = env.METRIK_X402_SETTLEMENT_SCOPE ?? DEFAULT_SETTLEMENT_SCOPE;
+  if (rawScope !== "tracked-resources" && rawScope !== "any-resource") {
+    throw new Error(
+      `invalid METRIK_X402_SETTLEMENT_SCOPE: ${rawScope} (tracked-resources|any-resource)`,
+    );
+  }
+
+  const chainId = Number(env.METRIK_X402_CHAIN_ID ?? "84532");
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error(
+      `invalid METRIK_X402_CHAIN_ID: ${env.METRIK_X402_CHAIN_ID}`,
+    );
+  }
+
+  const freshnessWindowSeconds = Number(
+    env.METRIK_X402_FRESHNESS_SECONDS ??
+      String(DEFAULT_DELIVERY_FRESHNESS_SECONDS),
+  );
+  if (!Number.isFinite(freshnessWindowSeconds) || freshnessWindowSeconds <= 0) {
+    throw new Error(
+      `invalid METRIK_X402_FRESHNESS_SECONDS: ${env.METRIK_X402_FRESHNESS_SECONDS}`,
+    );
+  }
+
+  const rawPolicy = env.METRIK_X402_INDETERMINATE_POLICY ?? "allow";
+  if (rawPolicy !== "allow" && rawPolicy !== "deny") {
+    throw new Error(
+      `invalid METRIK_X402_INDETERMINATE_POLICY: ${rawPolicy} (allow|deny)`,
+    );
+  }
+
+  const port = Number(env.METRIK_X402_PORT ?? env.PORT ?? "8788");
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`invalid port: ${env.METRIK_X402_PORT ?? env.PORT}`);
+  }
+
+  const registryUrl = env.METRIK_X402_REGISTRY_URL;
+
+  return {
+    host: env.METRIK_X402_HOST ?? "0.0.0.0",
+    port,
+    chainId,
+    rpcUrl,
+    oracleUrl: env.METRIK_X402_ORACLE_URL ?? DEFAULT_METRIK_ORACLE_URL,
+    freshnessWindowSeconds,
+    indeterminatePolicy: rawPolicy,
+    settlementScope: rawScope,
+    ...(rawAllowlist.length === 0
+      ? {}
+      : { settlementAssetAllowlist: rawAllowlist }),
+    ...(registryUrl === undefined ? {} : { registryUrl }),
+    ...(relayerPrivateKey === undefined ? {} : { relayerPrivateKey }),
+    ...(settlementToken === undefined || settlementToken.length === 0
+      ? {}
+      : { settlementToken }),
+  };
+}
+
+export function buildMetrikFacilitatorFromEnvConfig(
+  config: MetrikFacilitatorEnvConfig,
+): MetrikVerifiedDeliveryFacilitator {
+  return new MetrikVerifiedDeliveryFacilitator({
+    paymentVerifier: createX402PaymentVerifier({
+      chainId: config.chainId,
+      rpcUrl: config.rpcUrl,
+    }),
+    ...(config.relayerPrivateKey === undefined
+      ? {}
+      : {
+          paymentSettler: createX402PaymentSettler({
+            chainId: config.chainId,
+            rpcUrl: config.rpcUrl,
+            privateKey: config.relayerPrivateKey,
+          }),
+        }),
+    resourceIndex: createRegistryResourceIndex(
+      config.registryUrl === undefined
+        ? {}
+        : { discoverOptions: { registryUrl: config.registryUrl } },
+    ),
+    deliveryOracle: createOracleDeliveryOracle({
+      oracleUrl: config.oracleUrl,
+      freshnessWindowSeconds: config.freshnessWindowSeconds,
+    }),
+    indeterminatePolicy: config.indeterminatePolicy,
+    chainId: config.chainId,
+    settlementScope: config.settlementScope,
+    ...(config.settlementAssetAllowlist === undefined
+      ? {}
+      : { settlementAssetAllowlist: config.settlementAssetAllowlist }),
+  });
+}
+
+export async function startMetrikFacilitatorServerFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<MetrikFacilitatorServer & { readonly boundPort: number }> {
+  const config = parseMetrikFacilitatorEnvConfig(env);
+  const facilitator = buildMetrikFacilitatorFromEnvConfig(config);
+
+  if (config.relayerPrivateKey === undefined) {
+    console.error(
+      "[metrik-x402-facilitator] SETTLEMENT DISABLED — no METRIK_X402_RELAYER_PRIVATE_KEY. " +
+        "/verify works; /settle will return 503 and broadcast nothing.",
+    );
+  } else {
+    console.error(
+      `[metrik-x402-facilitator] settlement relayer ${relayerAddress(
+        config.relayerPrivateKey,
+      )} — this address must hold native gas on chain ${config.chainId}.`,
+    );
+  }
+  console.error(
+    `[metrik-x402-facilitator] delivery gate: oracle=${config.oracleUrl} ` +
+      `freshness=${config.freshnessWindowSeconds}s policy-on-no-evidence=${config.indeterminatePolicy}`,
+  );
+  console.error(
+    `[metrik-x402-facilitator] settlement policy: scope=${config.settlementScope} ` +
+      `assets=${facilitator.allowedSettlementAssets.join(",")} — the relayer will not be ` +
+      "asked to call any other contract.",
+  );
+
+  const server = createMetrikFacilitatorServer({
+    facilitator,
+    settlementEnabled: config.relayerPrivateKey !== undefined,
+    ...(config.settlementToken === undefined
+      ? {}
+      : { settlementToken: config.settlementToken }),
+  });
+  const { port } = await server.listen(config.port, config.host);
+  return Object.assign(server, { boundPort: port });
+}