@absol-labs/agent 0.10.0 → 0.11.0

package/src/gateway/x402-mode.ts

@@ -0,0 +1,350 @@
+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/index.ts

@@ -24,25 +24,45 @@ export {
   type SignServerMandateOptions,
 } from "./mandates/env.js";
 
+// Metrik-native 402 challenge flow. NOT the x402 protocol — see docs/x402.md.
 export {
-  VerifiedStreamX402Facilitator,
+  METRIK_PAYMENT_HEADER,
+  METRIK_STREAM_SCHEME,
+  VerifiedStreamFacilitator,
   DeliveryProofUnavailableError,
+  SettlementTargetMismatchError,
+  SpendControlUnavailableError,
+  StreamPayloadError,
+  encodeStreamPayloadHeader,
+  parseStreamChallengeJson,
+  parseStreamPayloadHeader,
+  streamChallengeSchema,
+  streamOpenPayloadSchema,
+  verifiedStreamRequirementsSchema,
+  type ConsumedHttpsResponseProofInput,
+  type StreamChallenge,
+  type StreamFacilitator,
+  type StreamOpenPayload,
+  type VerifiedStreamFacilitatorOptions,
+  type VerifiedStreamRequirements,
+} from "./x402/facilitator.js";
+
+// Deprecated `x402`-flavoured aliases of the exports above, kept for
+// compatibility. Same values and same class objects — prefer the names above.
+export {
+  VerifiedStreamX402Facilitator,
   X402PayloadError,
   X402SpendControlUnavailableError,
-  SettlementTargetMismatchError,
   X402_SCHEME,
   encodeX402PayloadHeader,
   parseX402ChallengeJson,
   parseX402PayloadHeader,
-  verifiedStreamRequirementsSchema,
   x402StreamChallengeSchema,
   x402OpenPayloadSchema,
   type X402ConsumedHttpsResponseProofInput,
   type X402Facilitator,
   type X402OpenPayload,
   type X402StreamChallenge,
-  type VerifiedStreamFacilitatorOptions,
-  type VerifiedStreamRequirements,
 } from "./x402/facilitator.js";
 
 export {
@@ -62,6 +82,8 @@ export {
 } from "./discovery/registry.js";
 
 export {
+  ALLOW_UNVERIFIED_OPERATOR_ENV,
+  METERING_MODEL,
   METRIK_MCP_TOOLS,
   STREAMPROOF_MCP_TOOLS,
   FileStreamRegistry,
@@ -71,6 +93,7 @@ export {
   createVerifiedStreamMcpServerOptionsFromEnv,
   parseMetrikAgentEnv,
   startVerifiedStreamMcpServerStdio,
+  type EscrowGeneration,
   type McpToolSpec,
   type ParsedMetrikAgentEnv,
   type StoredStreamRecord,
@@ -80,6 +103,16 @@ export {
   type VerifiedStreamMcpServerRuntime,
 } from "./mcp/server.js";
 
+export {
+  MAX_INVOCATION_RESPONSE_BYTES,
+  ServiceListingNotFoundError,
+  createServiceInvoker,
+  type CreateServiceInvokerOptions,
+  type ServiceInvocationRequest,
+  type ServiceInvocationResult,
+  type ServiceInvoker,
+} from "./mcp/service-invoker.js";
+
 export {
   StaticTenantResolver,
   createHostedMcpHttpServer,
@@ -288,6 +321,7 @@ export {
   type HttpMethod,
   type InvocationCapability,
   type InvocationCapabilityDomainInput,
+  type InvocationCapabilitySigner,
   type SignedInvocationCapability,
 } from "./capability/invocation-capability.js";
 
@@ -322,6 +356,7 @@ export {
   InvokeBuyerMismatchError,
   InvokeAccessUrlError,
   InvokePathError,
+  resolveInvocationUrl,
   InvokeServiceRefMismatchError,
   InvokeStreamExpiredError,
   InvokeStreamNotActiveError,

package/src/mandates/env.ts

@@ -17,8 +17,9 @@ import {
 /**
  * Server-side spend-mandate provisioning.
  *
- * The MCP/x402 fund-moving surface is driven by autonomous callers (an LLM over
- * MCP, a paying agent over x402) that CANNOT produce an EIP-712 signature. The
+ * The MCP / Metrik-402 fund-moving surface is driven by autonomous callers (an
+ * LLM over MCP, a paying agent driving Metrik's own `402` challenge flow — not
+ * the x402 protocol, see docs/x402.md) that CANNOT produce an EIP-712 signature. The
  * spend mandate is therefore NOT a per-call argument — it is configured once, at
  * the server's construction, exactly like the AgentKit action provider's
  * `signedMandate`. The deploying operator declares the spend caps via env and the