@absol-labs/agent 0.9.1 → 0.11.0

package/src/gateway/http-server.ts

@@ -12,8 +12,18 @@ import {
   CallerAuthGateway,
   DEFAULT_MAX_STATE_STALENESS_SECONDS,
   MAX_CORROBORATING_STREAM_READERS,
+  type CallerAuthDecision,
   type CallerAuthDenialReason,
 } from "./caller-auth-gateway.js";
+import {
+  createHttpFacilitatorClient,
+  createListingPriceQuoter,
+  encodeSettleResponseHeader,
+  X402_PAYMENT_RESPONSE_HEADER,
+  X402_SETTLEMENT_HEADROOM_SECONDS,
+  type GatewayX402Mode,
+} from "./x402-mode.js";
+import { discoverServices } from "../discovery/registry.js";
 
 /**
  * Reference standalone reverse-proxy gateway server (metrik-agent#63).
@@ -49,6 +59,12 @@ export interface CallerAuthGatewayServerConfig {
   readonly upstreamUrl: string;
   /** Extra request-timeout for the upstream fetch, in ms. Default 30000. */
   readonly upstreamTimeoutMs?: number;
+  /**
+   * The same {@link GatewayX402Mode} given to the gateway. Required for the
+   * x402 path: the gateway VERIFIES a payment, this server SETTLES it once the
+   * upstream has produced a response.
+   */
+  readonly x402?: GatewayX402Mode;
 }
 
 export interface CallerAuthGatewayServer {
@@ -70,6 +86,7 @@ export function createCallerAuthGatewayServer(
       config.gateway,
       upstreamBase,
       upstreamTimeoutMs,
+      config.x402,
     ).catch((error) => {
       logError("unhandled request error", error);
       if (!res.headersSent) {
@@ -105,6 +122,7 @@ async function handleRequest(
   gateway: CallerAuthGateway,
   upstreamBase: URL,
   upstreamTimeoutMs: number,
+  x402: GatewayX402Mode | undefined,
 ): Promise<void> {
   const requestUrl = new URL(req.url ?? "/", "http://localhost");
   const method = req.method ?? "GET";
@@ -117,6 +135,14 @@ async function handleRequest(
   });
 
   if (!decision.authorized) {
+    // The x402 challenge is a PROTOCOL body, not Metrik's `{authorized,reason}`
+    // shape: `x402-fetch` parses `{x402Version, accepts}` and nothing else.
+    if (decision.x402PaymentRequired !== undefined) {
+      res
+        .writeHead(402, { "Content-Type": "application/json" })
+        .end(JSON.stringify(decision.x402PaymentRequired));
+      return;
+    }
     writeJsonError(
       res,
       decision.httpStatus ?? 403,
@@ -143,8 +169,23 @@ async function handleRequest(
     upstreamBase,
   );
 
+  // Bound the upstream by the payment's OWN deadline, not just by the server's
+  // timeout. Settlement happens after the upstream returns, so an upstream that
+  // outlives the signed authorization would produce its side effects and then
+  // be unsettleable — the caller would get the work for free (never the response
+  // body, which is only flushed after settlement, but the side effects are
+  // real). Aborting early turns that into an ordinary 502.
+  const effectiveTimeoutMs = boundedUpstreamTimeoutMs(
+    upstreamTimeoutMs,
+    decision.x402Payment?.validBefore,
+  );
+  if (effectiveTimeoutMs <= 0) {
+    writeJsonError(res, 402, "x402-authorization-too-short");
+    return;
+  }
+
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), upstreamTimeoutMs);
+  const timeout = setTimeout(() => controller.abort(), effectiveTimeoutMs);
   try {
     const upstreamResponse = await fetch(upstreamUrl, {
       method,
@@ -153,11 +194,26 @@ 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);
+
+    // Settle AFTER the upstream produced a response and BEFORE that response is
+    // flushed. Buyer-favouring on both edges: a call that never produced a
+    // response is never charged for, and a payment that cannot be settled
+    // returns `402` instead of handing over the goods for free.
+    if (decision.x402Payment !== undefined) {
+      const settled = await settleX402(decision, x402);
+      if (settled === undefined) {
+        writeJsonError(res, 402, "x402-settlement-failed");
+        return;
+      }
+      responseHeaders[X402_PAYMENT_RESPONSE_HEADER] =
+        encodeSettleResponseHeader(settled);
+      responseHeaders["access-control-expose-headers"] =
+        X402_PAYMENT_RESPONSE_HEADER;
+    }
+
+    res.writeHead(upstreamResponse.status, responseHeaders);
     res.end(buffer);
   } catch (error) {
     logError("upstream request failed", error);
@@ -167,6 +223,67 @@ async function handleRequest(
   }
 }
 
+/**
+ * The upstream budget, capped so the signed authorization is still settleable
+ * when the call returns. Returns <= 0 when there is no usable window at all.
+ */
+export function boundedUpstreamTimeoutMs(
+  upstreamTimeoutMs: number,
+  validBeforeSeconds: number | undefined,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): number {
+  if (validBeforeSeconds === undefined) {
+    return upstreamTimeoutMs;
+  }
+  const remainingSeconds =
+    validBeforeSeconds - nowSeconds - X402_SETTLEMENT_HEADROOM_SECONDS;
+  if (remainingSeconds <= 0) {
+    return 0;
+  }
+  return Math.min(upstreamTimeoutMs, remainingSeconds * 1000);
+}
+
+/** Returns the settlement result, or `undefined` if nothing was settled. */
+async function settleX402(
+  decision: CallerAuthDecision,
+  x402: GatewayX402Mode | undefined,
+): Promise<
+  Awaited<ReturnType<GatewayX402Mode["facilitator"]["settle"]>> | undefined
+> {
+  const payment = decision.x402Payment;
+  if (payment === undefined) {
+    return undefined;
+  }
+  if (x402 === undefined) {
+    // The gateway accepted an x402 payment but this server was given no
+    // facilitator to settle it with. Refuse: serving here would be free service.
+    logError(
+      "x402 settlement",
+      new Error(
+        "gateway accepted an x402 payment but the server has no x402 facilitator configured",
+      ),
+    );
+    return undefined;
+  }
+  try {
+    const settled = await x402.facilitator.settle(
+      payment.payload,
+      payment.requirements,
+    );
+    if (settled.success !== true) {
+      logError(
+        "x402 settlement",
+        new Error(settled.errorReason ?? "facilitator reported failure"),
+      );
+      return undefined;
+    }
+    return settled;
+  } catch (error) {
+    logError("x402 settlement", error);
+    return undefined;
+  }
+}
+
 function normalizeIncomingHeaders(
   headers: IncomingMessage["headers"],
 ): Record<string, string | undefined> {
@@ -210,7 +327,9 @@ function writeJsonError(
     | CallerAuthDenialReason
     | "unauthorized"
     | "internal-error"
-    | "upstream-unavailable",
+    | "upstream-unavailable"
+    | "x402-settlement-failed"
+    | "x402-authorization-too-short",
 ): void {
   if (res.headersSent) {
     res.end();
@@ -242,6 +361,22 @@ export interface CallerAuthGatewayEnvConfig {
   readonly corroboratingRpcUrls: readonly string[];
   /** Freshness bound for on-chain stream state, in seconds. */
   readonly maxStateStalenessSeconds: number;
+  /** Set only when standard-x402 mode is enabled. */
+  readonly x402?: CallerAuthGatewayX402EnvConfig;
+}
+
+export interface CallerAuthGatewayX402EnvConfig {
+  /** Per-call price in the asset's base units (micro-USDC). Seller-set, unsigned. */
+  readonly pricePerCallBaseUnits: bigint;
+  /** A facilitator exposing `/verify` and `/settle` — e.g. Metrik's own. */
+  readonly facilitatorUrl: string;
+  /** The public origin buyers reach this gateway on. Becomes `resource`. */
+  readonly resourceBaseUrl: string;
+  /** Listing source used to derive `payTo` from the operator-signed descriptor. */
+  readonly registryUrl?: string;
+  readonly maxTimeoutSeconds?: number;
+  /** Bearer token for the facilitator's `/settle`. Required by Metrik's own. */
+  readonly facilitatorToken?: string;
 }
 
 /**
@@ -346,6 +481,8 @@ export function parseCallerAuthGatewayEnvConfig(
     );
   }
 
+  const x402 = parseGatewayX402EnvConfig(env);
+
   return {
     host,
     port,
@@ -360,6 +497,132 @@ export function parseCallerAuthGatewayEnvConfig(
     corroboratingRpcUrls,
     maxStateStalenessSeconds,
     ...(headerName === undefined ? {} : { headerName }),
+    ...(x402 === undefined ? {} : { x402 }),
+  };
+}
+
+/**
+ * x402 mode is OFF unless `METRIK_GATEWAY_X402_PRICE_BASE_UNITS` is set. Once
+ * on, every other x402 var is required: a half-configured paywall would answer
+ * `402` with a quote it cannot settle.
+ *
+ * Note what is NOT here: `payTo`. It is never configurable — it is resolved at
+ * startup from the operator-signed descriptor for this gateway's `serviceRef`
+ * (see {@link resolveSignedListingPayee}), and the gateway refuses to start if
+ * that lookup fails.
+ */
+export function parseGatewayX402EnvConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): CallerAuthGatewayX402EnvConfig | undefined {
+  const rawPrice = env.METRIK_GATEWAY_X402_PRICE_BASE_UNITS?.trim();
+  if (rawPrice === undefined || rawPrice.length === 0) {
+    return undefined;
+  }
+  let pricePerCallBaseUnits: bigint;
+  try {
+    pricePerCallBaseUnits = BigInt(rawPrice);
+  } catch {
+    throw new Error(
+      `invalid METRIK_GATEWAY_X402_PRICE_BASE_UNITS: ${rawPrice} (integer base units, e.g. 1000 = 0.001 USDC)`,
+    );
+  }
+  if (pricePerCallBaseUnits <= 0n) {
+    throw new Error("METRIK_GATEWAY_X402_PRICE_BASE_UNITS must be positive");
+  }
+  const facilitatorUrl = requireEnv(env, "METRIK_GATEWAY_X402_FACILITATOR_URL");
+  const resourceBaseUrl = requireEnv(
+    env,
+    "METRIK_GATEWAY_X402_RESOURCE_BASE_URL",
+  );
+  for (const candidate of [facilitatorUrl, resourceBaseUrl]) {
+    // eslint-disable-next-line no-new -- validates the URL is well-formed.
+    new URL(candidate);
+  }
+  const registryUrl = env.METRIK_GATEWAY_X402_REGISTRY_URL;
+  const facilitatorToken = env.METRIK_GATEWAY_X402_FACILITATOR_TOKEN?.trim();
+  const rawTimeout = env.METRIK_GATEWAY_X402_MAX_TIMEOUT_SECONDS;
+  let maxTimeoutSeconds: number | undefined;
+  if (rawTimeout !== undefined && rawTimeout.trim().length > 0) {
+    maxTimeoutSeconds = Number(rawTimeout);
+    if (!Number.isInteger(maxTimeoutSeconds) || maxTimeoutSeconds <= 0) {
+      throw new Error(
+        `invalid METRIK_GATEWAY_X402_MAX_TIMEOUT_SECONDS: ${rawTimeout}`,
+      );
+    }
+  }
+
+  return {
+    pricePerCallBaseUnits,
+    facilitatorUrl,
+    resourceBaseUrl,
+    ...(registryUrl === undefined ? {} : { registryUrl }),
+    ...(maxTimeoutSeconds === undefined ? {} : { maxTimeoutSeconds }),
+    ...(facilitatorToken === undefined || facilitatorToken.length === 0
+      ? {}
+      : { facilitatorToken }),
+  };
+}
+
+export class UnresolvedListingPayeeError extends Error {
+  constructor(serviceRef: string) {
+    super(
+      `no operator-signed listing found for serviceRef ${serviceRef}. ` +
+        "x402 mode refuses to start: payTo is derived from the signed descriptor and " +
+        "is never taken from configuration, so an unresolved listing has no payee.",
+    );
+    this.name = "UnresolvedListingPayeeError";
+  }
+}
+
+/**
+ * Resolves `{serviceRef, operator}` from the registry. `discoverServices`
+ * re-derives `serviceRef` from the signed content and recovers the operator's
+ * EIP-712 signature, dropping anything that fails — so what comes back here is
+ * signed, not merely served.
+ */
+export async function resolveSignedListingPayee(
+  serviceRef: Hex,
+  registryUrl?: string,
+): Promise<{ readonly serviceRef: Hex; readonly operator: Address }> {
+  const listings = await discoverServices(
+    registryUrl === undefined ? {} : { registryUrl },
+  );
+  const match = listings.find(
+    (listing) => listing.serviceRef.toLowerCase() === serviceRef.toLowerCase(),
+  );
+  if (match === undefined) {
+    throw new UnresolvedListingPayeeError(serviceRef);
+  }
+  return { serviceRef: match.serviceRef, operator: match.operator };
+}
+
+/** Builds the gateway's x402 mode, deriving `payTo` from the signed listing. */
+export async function buildGatewayX402Mode(
+  config: CallerAuthGatewayEnvConfig,
+): Promise<GatewayX402Mode | undefined> {
+  if (config.x402 === undefined) {
+    return undefined;
+  }
+  const listing = await resolveSignedListingPayee(
+    config.serviceRef,
+    config.x402.registryUrl,
+  );
+  return {
+    quote: createListingPriceQuoter({
+      listing,
+      resourceBaseUrl: config.x402.resourceBaseUrl,
+      pricePerCallBaseUnits: config.x402.pricePerCallBaseUnits,
+      chainId: config.chainId,
+      ...(config.x402.maxTimeoutSeconds === undefined
+        ? {}
+        : { maxTimeoutSeconds: config.x402.maxTimeoutSeconds }),
+    }),
+    facilitator: createHttpFacilitatorClient({
+      url: config.x402.facilitatorUrl,
+      ...(config.x402.facilitatorToken === undefined
+        ? {}
+        : { token: config.x402.facilitatorToken }),
+    }),
   };
 }
 
@@ -376,6 +639,7 @@ export async function startCallerAuthGatewayServerFromEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<CallerAuthGatewayServer & { readonly boundPort: number }> {
   const config = parseCallerAuthGatewayEnvConfig(env);
+  const x402 = await buildGatewayX402Mode(config);
   const gateway = new CallerAuthGateway({
     escrowAddress: config.escrowAddress,
     rpcUrl: config.rpcUrl,
@@ -387,6 +651,7 @@ export async function startCallerAuthGatewayServerFromEnv(
     ...(config.headerName === undefined
       ? {}
       : { headerName: config.headerName }),
+    ...(x402 === undefined ? {} : { x402 }),
   });
   if (config.corroboratingRpcUrls.length === 0) {
     console.error(
@@ -397,9 +662,18 @@ export async function startCallerAuthGatewayServerFromEnv(
         "one INDEPENDENT provider to close that window.",
     );
   }
+  if (x402 !== undefined && config.x402 !== undefined) {
+    console.error(
+      "[metrik-caller-auth-gateway] standard x402 mode ENABLED: callers with no Metrik " +
+        `capability are quoted ${config.x402.pricePerCallBaseUnits} base units per call, ` +
+        `settled through ${config.x402.facilitatorUrl}. This is a per-call payment with NO ` +
+        "escrow and NO recoverability — the stream path remains the only recoverable one.",
+    );
+  }
   const server = createCallerAuthGatewayServer({
     gateway,
     upstreamUrl: config.upstreamUrl,
+    ...(x402 === undefined ? {} : { x402 }),
   });
   const { port } = await server.listen(config.port, config.host);
   return Object.assign(server, { boundPort: port });

package/src/gateway/server-entry.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startCallerAuthGatewayServerFromEnv } from "./http-server.js";
 
 /**