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

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";