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

package/src/gateway/x402-mode.ts

@@ -1,350 +0,0 @@
-import type {
-  PaymentRequirements,
-  SettleResponse,
-  VerifyResponse,
-} from "x402/types";
-
-import {
-  buildMetrikPaymentRequirements,
-  buildX402PaymentRequiredBody,
-  type SignedListingPayee,
-  type X402AssetConfig,
-  type X402PaymentRequiredBody,
-} from "../x402/payment-requirements.js";
-
-/**
- * Standard x402 mode for the seller-side gateway (Tier 1).
- *
- * The gateway already authorizes requests that carry a Metrik
- * `InvocationCapability` — a buyer with an open, funded, verified stream. That
- * path is untouched. This module adds a SECOND, independent way in: a request
- * with no capability gets an ordinary HTTP `402` carrying real x402
- * `PaymentRequirements`, so an agent holding nothing but `x402-fetch` can pay
- * per call without knowing Metrik exists.
- *
- * ## The two paths never overlap
- *
- * - capability header present -> stream path, exactly as before;
- * - capability header absent, x402 mode on -> `402` + `PaymentRequirements`;
- * - BOTH present -> rejected. A request that looks like both is ambiguous about
- *   which one is paying for it, and the failure mode of guessing is charging the
- *   caller twice for one call. Better a loud `400` than a silent double charge.
- *
- * ## The per-call price is the seller's, and is not signed
- *
- * `payTo` comes from the operator-signed descriptor (see
- * `../x402/payment-requirements.ts`). The price does not — the descriptor has no
- * per-call price field. It is the seller's own number on the seller's own
- * gateway, which is legitimate, but a buyer cannot cross-check it against the
- * registry the way they can cross-check the payee.
- */
-
-/** Request header carrying the x402 payment payload (x402 v1). */
-export const X402_PAYMENT_HEADER = "x-payment" as const;
-
-/** Response header carrying the settlement result (x402 v1). */
-export const X402_PAYMENT_RESPONSE_HEADER = "x-payment-response" as const;
-
-/** The facilitator the gateway delegates verify/settle to. */
-export interface X402FacilitatorClient {
-  verify(
-    payload: unknown,
-    requirements: PaymentRequirements,
-  ): Promise<VerifyResponse>;
-  settle(
-    payload: unknown,
-    requirements: PaymentRequirements,
-  ): Promise<SettleResponse>;
-}
-
-export interface HttpFacilitatorClientOptions {
-  /** Base URL of a facilitator exposing `/verify` and `/settle`. */
-  readonly url: string;
-  /**
-   * Shared secret for the facilitator's `/settle`. Sent as
-   * `Authorization: Bearer`. Metrik's own facilitator refuses to start a
-   * settling deployment without one, because `/settle` spends its gas.
-   */
-  readonly token?: string;
-  readonly headers?: Readonly<Record<string, string>>;
-  readonly timeoutMs?: number;
-  readonly fetch?: typeof globalThis.fetch;
-}
-
-/**
- * Talks to any x402 facilitator over HTTP — including Metrik's own
- * (`../x402/facilitator-server.ts`), which is the point: a seller who wires this
- * gateway to the Metrik facilitator gets a paywall whose payments stop when
- * their own delivery stops being verifiable.
- */
-export function createHttpFacilitatorClient(
-  options: HttpFacilitatorClientOptions,
-): X402FacilitatorClient {
-  const base = options.url.replace(/\/+$/, "");
-  const timeoutMs = options.timeoutMs ?? 10_000;
-  const doFetch = options.fetch ?? globalThis.fetch;
-
-  async function post(path: string, body: unknown): Promise<unknown> {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const response = await doFetch(`${base}${path}`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          ...(options.token === undefined
-            ? {}
-            : { authorization: `Bearer ${options.token}` }),
-          ...(options.headers ?? {}),
-        },
-        body: JSON.stringify(body),
-        signal: controller.signal,
-      });
-      return await response.json();
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  return {
-    async verify(payload, requirements) {
-      const result = (await post("/verify", {
-        x402Version: 1,
-        paymentPayload: payload,
-        paymentRequirements: requirements,
-      })) as VerifyResponse;
-      // Fail closed: an unreadable facilitator answer is not a pass.
-      if (typeof result !== "object" || result === null) {
-        return { isValid: false, invalidReason: "unexpected_verify_error" };
-      }
-      return result;
-    },
-    async settle(payload, requirements) {
-      return (await post("/settle", {
-        x402Version: 1,
-        paymentPayload: payload,
-        paymentRequirements: requirements,
-      })) as SettleResponse;
-    },
-  };
-}
-
-/** Builds the `PaymentRequirements` quoted for a given request. */
-export type X402Quoter = (request: {
-  readonly method: string;
-  readonly path: string;
-}) => readonly PaymentRequirements[] | Promise<readonly PaymentRequirements[]>;
-
-export interface ListingPriceQuoterOptions {
-  /** Projected from the OPERATOR-SIGNED descriptor. `payTo` comes from here. */
-  readonly listing: SignedListingPayee;
-  /** Public origin buyers reach this gateway on, e.g. `https://svc.example.com`. */
-  readonly resourceBaseUrl: string;
-  /** Per-call price in the asset's base units (micro-USDC). Seller-set, unsigned. */
-  readonly pricePerCallBaseUnits: bigint;
-  readonly chainId: number;
-  readonly description?: string;
-  readonly mimeType?: string;
-  readonly maxTimeoutSeconds?: number;
-  readonly asset?: X402AssetConfig;
-}
-
-/** One flat price per call, quoted against the request's own path. */
-export function createListingPriceQuoter(
-  options: ListingPriceQuoterOptions,
-): X402Quoter {
-  const base = new URL(options.resourceBaseUrl);
-  return (request) => [
-    buildMetrikPaymentRequirements({
-      listing: options.listing,
-      resource: new URL(request.path, base).toString(),
-      priceBaseUnits: options.pricePerCallBaseUnits,
-      chainId: options.chainId,
-      ...(options.description === undefined
-        ? {}
-        : { description: options.description }),
-      ...(options.mimeType === undefined ? {} : { mimeType: options.mimeType }),
-      ...(options.maxTimeoutSeconds === undefined
-        ? {}
-        : { maxTimeoutSeconds: options.maxTimeoutSeconds }),
-      ...(options.asset === undefined ? {} : { asset: options.asset }),
-    }),
-  ];
-}
-
-export interface GatewayX402Mode {
-  readonly quote: X402Quoter;
-  readonly facilitator: X402FacilitatorClient;
-}
-
-/** Decoded, still-untrusted `X-PAYMENT` payload plus the quote it answers. */
-export interface AcceptedX402Payment {
-  readonly payload: unknown;
-  readonly requirements: PaymentRequirements;
-  readonly payer?: string;
-  /**
-   * Unix seconds after which the signed authorization is no longer settleable
-   * (`validBefore`), when the payload carried one.
-   *
-   * The upstream runs BEFORE settlement, so an upstream slower than this window
-   * would produce its side effects and then fail to be paid for. The server
-   * bounds the upstream call by this instead of letting that happen.
-   */
-  readonly validBefore?: number;
-}
-
-export type X402EvaluationOutcome =
-  | {
-      readonly outcome: "payment-required";
-      readonly body: X402PaymentRequiredBody;
-    }
-  | { readonly outcome: "accepted"; readonly payment: AcceptedX402Payment };
-
-/**
- * Evaluates the x402 half of a request. Returns either the `402` body to send or
- * an accepted payment to settle after the upstream has been called.
- */
-export async function evaluateX402Request(
-  request: { readonly method: string; readonly path: string },
-  paymentHeader: string | undefined,
-  mode: GatewayX402Mode,
-): Promise<X402EvaluationOutcome> {
-  const accepts = await mode.quote(request);
-  if (paymentHeader === undefined || paymentHeader.trim().length === 0) {
-    return {
-      outcome: "payment-required",
-      body: buildX402PaymentRequiredBody(accepts),
-    };
-  }
-
-  const payload = decodePaymentHeader(paymentHeader);
-  if (payload === undefined) {
-    return {
-      outcome: "payment-required",
-      body: buildX402PaymentRequiredBody(
-        accepts,
-        "X-PAYMENT header is not base64-encoded JSON",
-      ),
-    };
-  }
-
-  const requirements = selectRequirements(accepts, payload);
-  if (requirements === undefined) {
-    return {
-      outcome: "payment-required",
-      body: buildX402PaymentRequiredBody(
-        accepts,
-        "X-PAYMENT does not match any offered payment requirements",
-      ),
-    };
-  }
-
-  let verified: VerifyResponse;
-  try {
-    verified = await mode.facilitator.verify(payload, requirements);
-  } catch (error) {
-    // An unreachable facilitator is a refusal, never a free call.
-    return {
-      outcome: "payment-required",
-      body: buildX402PaymentRequiredBody(
-        accepts,
-        `payment could not be verified: ${
-          error instanceof Error ? error.message : "facilitator unreachable"
-        }`,
-      ),
-    };
-  }
-  if (!verified.isValid) {
-    return {
-      outcome: "payment-required",
-      body: buildX402PaymentRequiredBody(
-        accepts,
-        verified.invalidReason ?? "payment rejected by facilitator",
-      ),
-    };
-  }
-
-  // A Metrik facilitator reports up front whether it would actually broadcast
-  // this payment (asset allowlist, settlement scope, ...). Refusing HERE — before
-  // the upstream runs — is the difference between "the caller gets nothing" and
-  // "the caller gets the upstream's side effects for free and we cannot charge
-  // for them". A non-Metrik facilitator omits the field and nothing changes.
-  const annotation = (
-    verified as { metrik?: { settleable?: boolean; detail?: string } }
-  ).metrik;
-  if (annotation?.settleable === false) {
-    return {
-      outcome: "payment-required",
-      body: buildX402PaymentRequiredBody(
-        accepts,
-        `facilitator will not settle this payment: ${annotation.detail ?? "refused"}`,
-      ),
-    };
-  }
-
-  const validBefore = readValidBefore(payload);
-
-  return {
-    outcome: "accepted",
-    payment: {
-      payload,
-      requirements,
-      ...(verified.payer === undefined ? {} : { payer: verified.payer }),
-      ...(validBefore === undefined ? {} : { validBefore }),
-    },
-  };
-}
-
-/** Reads the exact-EVM authorization deadline, if the payload has one. */
-function readValidBefore(payload: unknown): number | undefined {
-  const authorization = (
-    payload as { payload?: { authorization?: { validBefore?: unknown } } }
-  )?.payload?.authorization;
-  const raw = authorization?.validBefore;
-  if (typeof raw !== "string" && typeof raw !== "number") {
-    return undefined;
-  }
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-
-/**
- * Seconds of headroom the settlement leg needs after the upstream returns.
- *
- * The x402 `exact` verifier rejects an authorization whose `validBefore` is less
- * than 6 s away, so an upstream allowed to run right up to the deadline would
- * hand back a response that can never be settled. This leaves room for that
- * check plus the settle round trip.
- */
-export const X402_SETTLEMENT_HEADROOM_SECONDS = 10;
-
-/** Matches the payload's scheme+network against the quotes actually offered. */
-function selectRequirements(
-  accepts: readonly PaymentRequirements[],
-  payload: unknown,
-): PaymentRequirements | undefined {
-  if (typeof payload !== "object" || payload === null) {
-    return undefined;
-  }
-  const { scheme, network } = payload as {
-    scheme?: unknown;
-    network?: unknown;
-  };
-  return accepts.find(
-    (candidate) => candidate.scheme === scheme && candidate.network === network,
-  );
-}
-
-export function decodePaymentHeader(header: string): unknown {
-  try {
-    const decoded = Buffer.from(header.trim(), "base64").toString("utf8");
-    const parsed: unknown = JSON.parse(decoded);
-    return typeof parsed === "object" && parsed !== null ? parsed : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function encodeSettleResponseHeader(response: SettleResponse): string {
-  return Buffer.from(JSON.stringify(response), "utf8").toString("base64");
-}

package/src/x402/delivery-oracle.ts

@@ -1,285 +0,0 @@
-import { z } from "zod";
-
-/**
- * The Metrik delivery signal, as consumed by the x402 facilitator.
- *
- * ## Where the signal comes from
- *
- * The oracle publishes `GET /services` — one row per `serviceRef`, reduced from
- * the oracle's own settlement-path verdicts for the active streams of that
- * service (`streamproof-oracle/src/service-status.ts`). Its three states are
- * already buyer-favouring at the source: a FRESH failing stream beats a fresh
- * delivering sibling, and absent/stale evidence is reported as `unverified`
- * rather than folded into "fine".
- *
- * ## Why this module re-checks freshness the oracle already checked
- *
- * The oracle's own bound is 5 minutes (`DEFAULT_SERVICE_STATUS_TTL_MS`), which
- * is a sensible bound for a dashboard and far too loose for a payment gate. On
- * top of that the HTTP response itself can be cached or served by a stale
- * replica, and `lastCheckedAt` is the only field that dates the EVIDENCE rather
- * than the response. So the age of `lastCheckedAt` is re-derived here against
- * this module's own, much tighter window.
- *
- * ## The freshness window: 90 seconds, and why
- *
- * The oracle checkpoints every ~15–22 s, and a service's recorded status is
- * refreshed on that cadence. A window has to be wide enough that ordinary
- * jitter does not flap the gate, and narrow enough that "verified" still means
- * "now":
- *
- *   - 3 worst-case probe intervals (3 x 22 s = 66 s) absorbs two consecutive
- *     missed or slow ticks, which is normal operational noise, not evidence of
- *     a dead service.
- *   - plus the oracle's own record-and-serve latency and this process's fetch
- *     round trip, rounded up: **90 s**.
- *
- * Tighter (e.g. 30 s) and a single slow tick turns a healthy service's gate
- * indeterminate. Looser (e.g. the oracle's own 300 s) and a service that died
- * four minutes ago still reads `delivering`, which is exactly the claim this
- * gate exists to avoid making.
- *
- * Note this window is strictly stricter than the oracle's: a verdict aged
- * between 90 s and 300 s is `delivering` at the source and `indeterminate`
- * here.
- */
-export const DEFAULT_DELIVERY_FRESHNESS_SECONDS = 90;
-
-/** How long a fetched `/services` snapshot may be reused. See `verdictFor`. */
-export const DEFAULT_DELIVERY_SNAPSHOT_TTL_MS = 10_000;
-
-/** Request timeout for the oracle read. Short: this sits in a payment hot path. */
-export const DEFAULT_DELIVERY_ORACLE_TIMEOUT_MS = 4_000;
-
-export const DEFAULT_METRIK_ORACLE_URL = "https://oracle.metrik.live";
-
-/**
- * Three states, never two.
- *
- * `indeterminate` is deliberately NOT collapsed into either of the others: the
- * facilitator's policy for "no fresh evidence" is a separate, configurable
- * decision (see `./verified-delivery-facilitator.ts`), and folding it into
- * `failing` would make Metrik refuse every payment whenever its own oracle is
- * quiet or unreachable.
- */
-export type DeliveryVerdict = "delivering" | "failing" | "indeterminate";
-
-/** Why the verdict is what it is — machine-readable, for logs and for tests. */
-export type DeliveryVerdictReason =
-  | "fresh-delivering"
-  | "fresh-failing"
-  | "no-fresh-evidence"
-  | "verdict-stale"
-  | "service-not-listed"
-  | "oracle-unreachable"
-  | "oracle-malformed";
-
-export interface DeliveryAssessment {
-  readonly serviceRef: string;
-  readonly verdict: DeliveryVerdict;
-  readonly reason: DeliveryVerdictReason;
-  /** Unix ms of the newest recorded check for this service, when known. */
-  readonly lastCheckedAt: number | null;
-  /** Age of `lastCheckedAt` in seconds, when known. */
-  readonly ageSeconds: number | null;
-  /** The freshness window applied, in seconds. */
-  readonly freshnessWindowSeconds: number;
-}
-
-export interface MetrikDeliveryOracle {
-  /** Never throws: an unreachable oracle is an `indeterminate` verdict, not an exception. */
-  verdictFor(serviceRef: string): Promise<DeliveryAssessment>;
-}
-
-/** The subset of the oracle's `/services` row this module relies on. */
-const serviceStatusRowSchema = z
-  .object({
-    serviceRef: z.string(),
-    status: z.enum(["delivering", "failing", "unverified"]),
-    lastCheckedAt: z.number().nullable().optional(),
-  })
-  .passthrough();
-
-const servicesResponseSchema = z.object({
-  services: z.array(serviceStatusRowSchema),
-});
-
-export type FetchLike = (
-  input: string,
-  init?: { signal?: AbortSignal; headers?: Record<string, string> },
-) => Promise<{
-  ok: boolean;
-  status: number;
-  json(): Promise<unknown>;
-}>;
-
-export interface OracleDeliveryOracleOptions {
-  /** Oracle base URL. Default {@link DEFAULT_METRIK_ORACLE_URL}. */
-  readonly oracleUrl?: string;
-  /** Default {@link DEFAULT_DELIVERY_FRESHNESS_SECONDS}. */
-  readonly freshnessWindowSeconds?: number;
-  /** Default {@link DEFAULT_DELIVERY_SNAPSHOT_TTL_MS}. */
-  readonly snapshotTtlMs?: number;
-  readonly timeoutMs?: number;
-  readonly fetch?: FetchLike;
-  /** Injectable clock (unix ms), for tests. */
-  readonly now?: () => number;
-}
-
-/**
- * Reads `GET {oracleUrl}/services` and projects one row onto a
- * {@link DeliveryAssessment}.
- *
- * The snapshot is cached for {@link DEFAULT_DELIVERY_SNAPSHOT_TTL_MS} so a burst
- * of payments does not become a burst of oracle reads. The cache is SHORTER than
- * the freshness window by design, and caching cannot make a verdict look fresher
- * than it is: freshness is computed from the row's own `lastCheckedAt`, never
- * from when we fetched it.
- */
-export function createOracleDeliveryOracle(
-  options: OracleDeliveryOracleOptions = {},
-): MetrikDeliveryOracle {
-  const oracleUrl = (options.oracleUrl ?? DEFAULT_METRIK_ORACLE_URL).replace(
-    /\/+$/,
-    "",
-  );
-  const freshnessWindowSeconds =
-    options.freshnessWindowSeconds ?? DEFAULT_DELIVERY_FRESHNESS_SECONDS;
-  if (!Number.isFinite(freshnessWindowSeconds) || freshnessWindowSeconds <= 0) {
-    throw new Error("freshnessWindowSeconds must be a positive number");
-  }
-  const snapshotTtlMs =
-    options.snapshotTtlMs ?? DEFAULT_DELIVERY_SNAPSHOT_TTL_MS;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_DELIVERY_ORACLE_TIMEOUT_MS;
-  const doFetch = (options.fetch ??
-    ((input, init) => globalThis.fetch(input, init))) as FetchLike;
-  const now = options.now ?? (() => Date.now());
-
-  type Snapshot = {
-    readonly fetchedAtMs: number;
-    readonly rows: Map<string, z.infer<typeof serviceStatusRowSchema>> | null;
-    readonly failure: DeliveryVerdictReason | null;
-  };
-  let snapshot: Snapshot | undefined;
-  let inFlight: Promise<Snapshot> | undefined;
-
-  async function loadSnapshot(): Promise<Snapshot> {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const response = await doFetch(`${oracleUrl}/services`, {
-        signal: controller.signal,
-        headers: { accept: "application/json", "cache-control": "no-cache" },
-      });
-      if (!response.ok) {
-        return {
-          fetchedAtMs: now(),
-          rows: null,
-          failure: "oracle-unreachable",
-        };
-      }
-      const parsed = servicesResponseSchema.safeParse(await response.json());
-      if (!parsed.success) {
-        return { fetchedAtMs: now(), rows: null, failure: "oracle-malformed" };
-      }
-      const rows = new Map<string, z.infer<typeof serviceStatusRowSchema>>();
-      for (const row of parsed.data.services) {
-        rows.set(row.serviceRef.toLowerCase(), row);
-      }
-      return { fetchedAtMs: now(), rows, failure: null };
-    } catch {
-      return { fetchedAtMs: now(), rows: null, failure: "oracle-unreachable" };
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  async function currentSnapshot(): Promise<Snapshot> {
-    const cached = snapshot;
-    if (cached !== undefined && now() - cached.fetchedAtMs < snapshotTtlMs) {
-      return cached;
-    }
-    // Collapse concurrent misses onto one request.
-    inFlight ??= loadSnapshot().finally(() => {
-      inFlight = undefined;
-    });
-    const loaded = await inFlight;
-    snapshot = loaded;
-    return loaded;
-  }
-
-  return {
-    async verdictFor(serviceRef) {
-      const key = serviceRef.toLowerCase();
-      const loaded = await currentSnapshot();
-      if (loaded.rows === null) {
-        return indeterminate(
-          serviceRef,
-          loaded.failure ?? "oracle-unreachable",
-          null,
-          freshnessWindowSeconds,
-        );
-      }
-      const row = loaded.rows.get(key);
-      if (row === undefined) {
-        return indeterminate(
-          serviceRef,
-          "service-not-listed",
-          null,
-          freshnessWindowSeconds,
-        );
-      }
-      const lastCheckedAt = row.lastCheckedAt ?? null;
-      const ageSeconds =
-        lastCheckedAt === null
-          ? null
-          : Math.max(0, Math.round((now() - lastCheckedAt) / 1000));
-
-      if (row.status === "unverified") {
-        return indeterminate(
-          serviceRef,
-          "no-fresh-evidence",
-          lastCheckedAt,
-          freshnessWindowSeconds,
-          ageSeconds,
-        );
-      }
-      // The oracle dated its own verdict; if it cannot be shown to be recent it
-      // is not evidence of anything, in EITHER direction.
-      if (ageSeconds === null || ageSeconds > freshnessWindowSeconds) {
-        return indeterminate(
-          serviceRef,
-          "verdict-stale",
-          lastCheckedAt,
-          freshnessWindowSeconds,
-          ageSeconds,
-        );
-      }
-      return {
-        serviceRef,
-        verdict: row.status === "failing" ? "failing" : "delivering",
-        reason: row.status === "failing" ? "fresh-failing" : "fresh-delivering",
-        lastCheckedAt,
-        ageSeconds,
-        freshnessWindowSeconds,
-      };
-    },
-  };
-}
-
-function indeterminate(
-  serviceRef: string,
-  reason: DeliveryVerdictReason,
-  lastCheckedAt: number | null,
-  freshnessWindowSeconds: number,
-  ageSeconds: number | null = null,
-): DeliveryAssessment {
-  return {
-    serviceRef,
-    verdict: "indeterminate",
-    reason,
-    lastCheckedAt,
-    ageSeconds,
-    freshnessWindowSeconds,
-  };
-}

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

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-import { startMetrikFacilitatorServerFromEnv } from "./facilitator-server.js";
-
-/**
- * Runnable entrypoint for Metrik's x402 facilitator (`metrik-x402-facilitator`).
- * All configuration comes from the environment; see
- * {@link parseMetrikFacilitatorEnvConfig}. Refuses to start without a
- * settlement relayer unless `METRIK_X402_ALLOW_VERIFY_ONLY=true`.
- */
-async function main(): Promise<void> {
-  const server = await startMetrikFacilitatorServerFromEnv();
-  const host = process.env.METRIK_X402_HOST ?? "0.0.0.0";
-  console.error(
-    `[metrik-x402-facilitator] listening on http://${host}:${server.boundPort}`,
-  );
-
-  const shutdown = (signal: string) => {
-    console.error(
-      `[metrik-x402-facilitator] ${signal} received — shutting down`,
-    );
-    server
-      .close()
-      .then(() => process.exit(0))
-      .catch(() => process.exit(1));
-  };
-  process.on("SIGINT", () => shutdown("SIGINT"));
-  process.on("SIGTERM", () => shutdown("SIGTERM"));
-}
-
-main().catch((error) => {
-  console.error(
-    error instanceof Error ? error.message : "failed to start x402 facilitator",
-  );
-  process.exit(1);
-});