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

package/src/x402/facilitator.ts

@@ -1,3 +1,17 @@
+/**
+ * Metrik-native HTTP `402` challenge flow.
+ *
+ * This is NOT an implementation of the x402 protocol. It uses its own scheme
+ * string (`streamproof-verified-stream`), its own wire format, and its own
+ * request header (`x-metrik-payment`). It does not interoperate with
+ * `x402-fetch`, `x402-axios`, `x402-express`, or any other x402 client or
+ * facilitator. See `docs/x402.md` for the full explanation of why Metrik's
+ * metered-stream settlement does not fit any shipped x402 scheme.
+ *
+ * The directory name is historical. The deprecated `X402*` / `x402*` alias
+ * exports that used to live here were removed with the x402 v1 integration
+ * (metrik-agent#115); only the canonical names below are exported.
+ */
 import type { StreamProofClientConfig } from "@absol-labs/sdk";
 import { z } from "zod";
 
@@ -16,7 +30,19 @@ import {
   type VerifiedConsumedHttpsResponseProof,
 } from "../zktls/reclaim.js";
 
-export const X402_SCHEME = "streamproof-verified-stream" as const;
+/**
+ * Immutable wire constant for the Metrik-native 402 scheme. The value is
+ * historical (`streamproof-*` predates the Metrik rename) and MUST NOT change:
+ * the live gateway and deployed callers depend on it.
+ */
+export const METRIK_STREAM_SCHEME = "streamproof-verified-stream" as const;
+
+/**
+ * Request header carrying the Metrik verified-stream payload. Deliberately NOT
+ * `x-payment`: that header belongs to the x402 protocol, which this flow does
+ * not implement.
+ */
+export const METRIK_PAYMENT_HEADER = "x-metrik-payment" as const;
 
 const addressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
 const bytes32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
@@ -35,36 +61,36 @@ export interface VerifiedStreamRequirements extends z.infer<
   typeof verifiedStreamRequirementsSchema
 > {}
 
-export const x402StreamChallengeSchema = z.object({
-  scheme: z.literal(X402_SCHEME),
+export const streamChallengeSchema = z.object({
+  scheme: z.literal(METRIK_STREAM_SCHEME),
   requirements: verifiedStreamRequirementsSchema,
 });
 
-export interface X402StreamChallenge extends z.infer<
-  typeof x402StreamChallengeSchema
+export interface StreamChallenge extends z.infer<
+  typeof streamChallengeSchema
 > {}
 
-export const x402OpenPayloadSchema = z.object({
-  challenge: x402StreamChallengeSchema,
+export const streamOpenPayloadSchema = z.object({
+  challenge: streamChallengeSchema,
   signedMandate: signedSpendMandateSchema,
 });
 
-export interface X402OpenPayload extends z.infer<
-  typeof x402OpenPayloadSchema
+export interface StreamOpenPayload extends z.infer<
+  typeof streamOpenPayloadSchema
 > {}
 
-export interface X402Facilitator {
+export interface StreamFacilitator {
   /** Build the 402 challenge a server returns to prompt a verified stream. */
-  challenge(req: VerifiedStreamRequirements): X402StreamChallenge;
+  challenge(req: VerifiedStreamRequirements): StreamChallenge;
   /** Verify + open the stream from an agent's signed payment payload. */
   open(payloadHeader: string): Promise<{ streamId: `0x${string}` }>;
   /** Prove the HTTPS response consumed after opening a verified stream. */
   proveConsumedHttpsResponse(
-    input: X402ConsumedHttpsResponseProofInput,
+    input: ConsumedHttpsResponseProofInput,
   ): Promise<VerifiedConsumedHttpsResponseProof>;
 }
 
-export interface X402ConsumedHttpsResponseProofInput {
+export interface ConsumedHttpsResponseProofInput {
   readonly signedMandate: SignedSpendMandate;
   readonly streamId?: `0x${string}`;
   readonly operator?: `0x${string}`;
@@ -109,9 +135,11 @@ function warnFacilitatorOnce(key: string, message: string): void {
   console.error(message);
 }
 
-export class X402PayloadError extends Error {
+export class StreamPayloadError extends Error {
   constructor(message: string) {
     super(message);
+    // Unchanged on purpose: `error.name` is an observable value that existing
+    // consumers may match on. The class was renamed; its `name` was not.
     this.name = "X402PayloadError";
   }
 }
@@ -137,14 +165,15 @@ export class DeliveryProofUnavailableError extends Error {
  * facilitator denies the open in this case (fail-closed, buyer-favoring) rather
  * than proceeding on an unverified assumption of "0 spent / none revoked".
  */
-export class X402SpendControlUnavailableError extends Error {
+export class SpendControlUnavailableError extends Error {
   constructor(message: string) {
     super(message);
+    // Unchanged on purpose: see StreamPayloadError above.
     this.name = "X402SpendControlUnavailableError";
   }
 }
 
-export class VerifiedStreamX402Facilitator implements X402Facilitator {
+export class VerifiedStreamFacilitator implements StreamFacilitator {
   private readonly agentClient: VerifiedStreamAgentOpener;
   private readonly deliveryProofs: ConsumerDeliveryProofService | undefined;
   private readonly sdkConfig: StreamProofClientConfig;
@@ -181,26 +210,26 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     // both resolvers are wired; warn once so the reason is visible at deploy time.
     if (options.resolveSpentSoFarUsdc === undefined) {
       warnFacilitatorOnce(
-        "x402-spent",
-        "[metrik] x402 facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
+        "metrik-stream-spent",
+        "[metrik] Metrik verified-stream facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
       );
     }
     if (options.resolveRevokedMandateIds === undefined) {
       warnFacilitatorOnce(
-        "x402-revocation",
-        "[metrik] x402 facilitator: no resolveRevokedMandateIds wired — revocation state cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
+        "metrik-stream-revocation",
+        "[metrik] Metrik verified-stream facilitator: no resolveRevokedMandateIds wired — revocation state cannot be verified, so open() will DENY every spend (fail-closed) until a resolver is wired.",
       );
     }
   }
 
-  challenge(req: VerifiedStreamRequirements): X402StreamChallenge {
+  challenge(req: VerifiedStreamRequirements): StreamChallenge {
     const requirements = verifiedStreamRequirementsSchema.parse(req);
     assertSettlementTarget(requirements, this.sdkConfig);
-    return { scheme: X402_SCHEME, requirements };
+    return { scheme: METRIK_STREAM_SCHEME, requirements };
   }
 
   async open(payloadHeader: string): Promise<{ streamId: `0x${string}` }> {
-    const payload = parseX402PayloadHeader(payloadHeader);
+    const payload = parseStreamPayloadHeader(payloadHeader);
     assertSettlementTarget(payload.challenge.requirements, this.sdkConfig);
 
     // FAIL-CLOSED fund safety (B6). Both the cumulative-cap accounting and the
@@ -209,12 +238,12 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     // returns a non-bigint/negative spend is treated as "state cannot be
     // verified" and DENIES the open — never a silent fail-open to 0/none.
     if (this.resolveSpentSoFarUsdc === undefined) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot open verified stream: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) cannot be verified (fail-closed)",
       );
     }
     if (this.resolveRevokedMandateIds === undefined) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot open verified stream: no resolveRevokedMandateIds wired — mandate revocation state cannot be verified (fail-closed)",
       );
     }
@@ -223,14 +252,14 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
     try {
       spentSoFarUsdc = await this.resolveSpentSoFarUsdc(payload.signedMandate);
     } catch (error) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         `cannot verify mandate cumulative cap (maxTotalUsdc): ${
           error instanceof Error ? error.message : String(error)
         } (fail-closed)`,
       );
     }
     if (typeof spentSoFarUsdc !== "bigint" || spentSoFarUsdc < 0n) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot verify mandate cumulative cap (maxTotalUsdc): resolver returned an invalid spent-so-far value (fail-closed)",
       );
     }
@@ -241,7 +270,7 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
         payload.signedMandate,
       );
     } catch (error) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         `cannot verify mandate revocation state: ${
           error instanceof Error ? error.message : String(error)
         } (fail-closed)`,
@@ -254,7 +283,7 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
         Symbol.iterator
       ] !== "function"
     ) {
-      throw new X402SpendControlUnavailableError(
+      throw new SpendControlUnavailableError(
         "cannot verify mandate revocation state: resolver returned a non-iterable value (fail-closed)",
       );
     }
@@ -275,11 +304,11 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
   }
 
   async proveConsumedHttpsResponse(
-    input: X402ConsumedHttpsResponseProofInput,
+    input: ConsumedHttpsResponseProofInput,
   ): Promise<VerifiedConsumedHttpsResponseProof> {
     if (this.deliveryProofs === undefined) {
       throw new DeliveryProofUnavailableError(
-        "zkTLS delivery proofs are not configured on this x402 facilitator",
+        "zkTLS delivery proofs are not configured on this Metrik verified-stream facilitator",
       );
     }
 
@@ -317,42 +346,52 @@ export class VerifiedStreamX402Facilitator implements X402Facilitator {
   }
 }
 
-export function encodeX402PayloadHeader(payload: X402OpenPayload): string {
-  const parsed = x402OpenPayloadSchema.parse(payload);
-  const token = Buffer.from(stringifyX402Payload(parsed)).toString("base64url");
-  return `${X402_SCHEME} ${token}`;
+export function encodeStreamPayloadHeader(payload: StreamOpenPayload): string {
+  const parsed = streamOpenPayloadSchema.parse(payload);
+  const token = Buffer.from(stringifyStreamPayload(parsed)).toString(
+    "base64url",
+  );
+  return `${METRIK_STREAM_SCHEME} ${token}`;
 }
 
-export function parseX402ChallengeJson(value: unknown): X402StreamChallenge {
-  const parsed = x402StreamChallengeSchema.safeParse(reviveBigInts(value));
+export function parseStreamChallengeJson(value: unknown): StreamChallenge {
+  const parsed = streamChallengeSchema.safeParse(reviveBigInts(value));
   if (!parsed.success) {
-    throw new X402PayloadError(
+    throw new StreamPayloadError(
       parsed.error.issues.map((issue) => issue.message).join("; "),
     );
   }
   return parsed.data;
 }
 
-export function parseX402PayloadHeader(payloadHeader: string): X402OpenPayload {
+export function parseStreamPayloadHeader(
+  payloadHeader: string,
+): StreamOpenPayload {
   const [scheme, token] = payloadHeader.split(" ", 2);
-  if (scheme !== X402_SCHEME || token === undefined || token.trim() === "") {
-    throw new X402PayloadError("invalid x402 verified-stream payload header");
+  if (
+    scheme !== METRIK_STREAM_SCHEME ||
+    token === undefined ||
+    token.trim() === ""
+  ) {
+    throw new StreamPayloadError(
+      "invalid Metrik verified-stream payload header",
+    );
   }
 
   let decoded: unknown;
   try {
     decoded = JSON.parse(Buffer.from(token, "base64url").toString("utf8"));
   } catch (error) {
-    throw new X402PayloadError(
-      `invalid x402 verified-stream payload encoding: ${
+    throw new StreamPayloadError(
+      `invalid Metrik verified-stream payload encoding: ${
         error instanceof Error ? error.message : String(error)
       }`,
     );
   }
 
-  const parsed = x402OpenPayloadSchema.safeParse(reviveBigInts(decoded));
+  const parsed = streamOpenPayloadSchema.safeParse(reviveBigInts(decoded));
   if (!parsed.success) {
-    throw new X402PayloadError(
+    throw new StreamPayloadError(
       parsed.error.issues.map((issue) => issue.message).join("; "),
     );
   }
@@ -381,7 +420,7 @@ function assertSettlementTarget(
   }
 }
 
-function stringifyX402Payload(payload: X402OpenPayload): string {
+function stringifyStreamPayload(payload: StreamOpenPayload): string {
   return JSON.stringify(payload, (_key, value) =>
     typeof value === "bigint" ? `${value.toString()}n` : value,
   );

package/src/x402-buyer/guarded-fetch.ts

@@ -0,0 +1,213 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+/**
+ * Outbound-request guard for x402 surfaces where the URL comes from a model
+ * (MCP `x402_pay`, `refund`, `refund_status`): without it, those tools are an
+ * SSRF probe of whatever network the server runs on.
+ *
+ * Every request is refused unless:
+ * - the URL is `https:` (or `http:` only when private networks are explicitly
+ *   allowed, i.e. local testing);
+ * - its host is on the allowlist, when one is configured
+ *   (`METRIK_AGENT_X402_ALLOWED_HOSTS`; `*.example.com` matches subdomains);
+ * - its host — an IP literal, or EVERY address the name resolves to — is not
+ *   loopback, private, link-local, unique-local, CGNAT, multicast, reserved or
+ *   unspecified.
+ *
+ * Redirects are never followed (`redirect: "manual"`; a 3xx is a refusal), so
+ * a public host cannot bounce the request — or a payment signature — onto an
+ * internal one.
+ *
+ * Limitation, stated: the address is checked at lookup time and the platform
+ * `fetch` resolves the name again when it connects, so a DNS-rebinding host
+ * with a near-zero TTL can still race the check. Use the allowlist where that
+ * matters.
+ */
+
+export type LookupFn = (
+  hostname: string,
+) => Promise<readonly { readonly address: string; readonly family: number }[]>;
+
+export interface GuardedFetchOptions {
+  /** Exact hostnames, or `*.domain` for subdomains. Unset = any public host. */
+  readonly allowedHosts?: readonly string[];
+  /** Tests / local development only: permit loopback and private ranges. */
+  readonly allowPrivateNetworks?: boolean;
+  /** The fetch to wrap. Default `globalThis.fetch`. */
+  readonly fetch?: typeof fetch;
+  /** DNS resolution. Default `dns.lookup(host, { all: true })`. */
+  readonly lookup?: LookupFn;
+}
+
+/** A request the guard refused; nothing was sent. */
+export class OutboundRequestRefusedError extends Error {
+  constructor(reason: string) {
+    super(`outbound request refused: ${reason}`);
+    this.name = "OutboundRequestRefusedError";
+  }
+}
+
+const defaultLookup: LookupFn = async (hostname) =>
+  await dnsLookup(hostname, { all: true, verbatim: true });
+
+function ipv4ToInt(address: string): number {
+  return address.split(".").reduce((acc, part) => acc * 256 + Number(part), 0);
+}
+
+const BLOCKED_V4: readonly (readonly [string, number])[] = [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 4],
+  ["240.0.0.0", 4],
+];
+
+function blockedV4(address: string): boolean {
+  const value = ipv4ToInt(address);
+  return BLOCKED_V4.some(([base, bits]) => {
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (value & mask) >>> 0 === (ipv4ToInt(base) & mask) >>> 0;
+  });
+}
+
+function blockedV6(raw: string): boolean {
+  const address = raw.toLowerCase().replace(/^\[|\]$/g, "");
+  if (address === "::" || address === "::1") return true;
+  // IPv4-mapped / -compatible: judge the embedded IPv4 address.
+  const mapped = /^(?:::ffff:|::)(\d+\.\d+\.\d+\.\d+)$/.exec(address);
+  if (mapped?.[1] !== undefined) return blockedV4(mapped[1]);
+  const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(address);
+  if (hexMapped?.[1] !== undefined && hexMapped[2] !== undefined) {
+    const hi = parseInt(hexMapped[1], 16);
+    const lo = parseInt(hexMapped[2], 16);
+    return blockedV4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+  }
+  const first = parseInt(address.split(":")[0] || "0", 16);
+  return (
+    (first & 0xfe00) === 0xfc00 || // fc00::/7 unique local
+    (first & 0xffc0) === 0xfe80 || // fe80::/10 link-local
+    (first & 0xffc0) === 0xfec0 || // fec0::/10 site-local (deprecated)
+    (first & 0xff00) === 0xff00 || // ff00::/8 multicast
+    address.startsWith("64:ff9b:") || // NAT64 (embeds IPv4)
+    address.startsWith("2001:db8:") // documentation
+  );
+}
+
+/** Whether an IP literal is in a range an outbound x402 request must not reach. */
+export function isBlockedAddress(address: string): boolean {
+  const bare = address.replace(/^\[|\]$/g, "");
+  const family = isIP(bare);
+  if (family === 4) return blockedV4(bare);
+  if (family === 6) return blockedV6(bare);
+  return true; // not an IP: never "safe" by default
+}
+
+function hostAllowed(hostname: string, allowed: readonly string[]): boolean {
+  const host = hostname.toLowerCase();
+  return allowed.some((entry) => {
+    const rule = entry.trim().toLowerCase();
+    if (rule.startsWith("*.")) return host.endsWith(rule.slice(1));
+    return host === rule;
+  });
+}
+
+/** Validate one URL against the guard; throws {@link OutboundRequestRefusedError}. */
+export async function assertOutboundUrlAllowed(
+  raw: string | URL,
+  options: GuardedFetchOptions = {},
+): Promise<URL> {
+  let url: URL;
+  try {
+    url = new URL(String(raw));
+  } catch {
+    throw new OutboundRequestRefusedError(`"${String(raw)}" is not a URL`);
+  }
+  const allowPrivate = options.allowPrivateNetworks === true;
+  if (
+    url.protocol !== "https:" &&
+    !(url.protocol === "http:" && allowPrivate)
+  ) {
+    throw new OutboundRequestRefusedError(
+      `${url.protocol} is not allowed (https only)`,
+    );
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new OutboundRequestRefusedError("credentials in the URL");
+  }
+  const hostname = url.hostname.replace(/^\[|\]$/g, "");
+  if (
+    options.allowedHosts !== undefined &&
+    options.allowedHosts.length > 0 &&
+    !hostAllowed(hostname, options.allowedHosts)
+  ) {
+    throw new OutboundRequestRefusedError(
+      `${hostname} is not in METRIK_AGENT_X402_ALLOWED_HOSTS`,
+    );
+  }
+  if (allowPrivate) return url;
+  if (isIP(hostname) !== 0) {
+    if (isBlockedAddress(hostname)) {
+      throw new OutboundRequestRefusedError(
+        `${hostname} is a loopback, private, link-local or reserved address`,
+      );
+    }
+    return url;
+  }
+  if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+    throw new OutboundRequestRefusedError(`${hostname} is loopback`);
+  }
+  let addresses: readonly { readonly address: string }[];
+  try {
+    addresses = await (options.lookup ?? defaultLookup)(hostname);
+  } catch {
+    throw new OutboundRequestRefusedError(`${hostname} did not resolve`);
+  }
+  if (addresses.length === 0) {
+    throw new OutboundRequestRefusedError(`${hostname} did not resolve`);
+  }
+  const blocked = addresses.find((entry) => isBlockedAddress(entry.address));
+  if (blocked !== undefined) {
+    throw new OutboundRequestRefusedError(
+      `${hostname} resolves to ${blocked.address}, a loopback, private, link-local or reserved address`,
+    );
+  }
+  return url;
+}
+
+/**
+ * A `fetch` that applies {@link assertOutboundUrlAllowed} to every request and
+ * never follows a redirect.
+ */
+export function createGuardedFetch(
+  options: GuardedFetchOptions = {},
+): typeof fetch {
+  const base = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const guarded = async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const target = input instanceof Request ? input.url : input;
+    await assertOutboundUrlAllowed(target, options);
+    const response = await base(input, { ...init, redirect: "manual" });
+    if (
+      response.type === "opaqueredirect" ||
+      (response.status >= 300 && response.status < 400)
+    ) {
+      throw new OutboundRequestRefusedError(
+        `${new URL(String(target)).host} answered with a redirect (${response.status}), which is never followed`,
+      );
+    }
+    return response;
+  };
+  return guarded as typeof fetch;
+}

package/src/x402-buyer/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `@absol-labs/agent/x402-buyer` — the BUYER side of Metrik x402: pay an x402
+ * v2 endpoint through `@absol-labs/sdk/x402`'s `payWithX402` with every SDK
+ * protection intact, gated by a spend mandate (`checkMandate()`) before
+ * anything is signed. Kept out of the root barrel so consumers that never use
+ * x402 do not load `@x402/*`. See docs/x402.md.
+ */
+export * from "./pay.js";
+export * from "./guarded-fetch.js";