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

package/dist/x402-buyer/guarded-fetch.js

@@ -0,0 +1,147 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+/** A request the guard refused; nothing was sent. */
+export class OutboundRequestRefusedError extends Error {
+    constructor(reason) {
+        super(`outbound request refused: ${reason}`);
+        this.name = "OutboundRequestRefusedError";
+    }
+}
+const defaultLookup = async (hostname) => await dnsLookup(hostname, { all: true, verbatim: true });
+function ipv4ToInt(address) {
+    return address.split(".").reduce((acc, part) => acc * 256 + Number(part), 0);
+}
+const BLOCKED_V4 = [
+    ["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) {
+    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) {
+    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) {
+    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, allowed) {
+    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, options = {}) {
+    let 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;
+    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 = {}) {
+    const base = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const guarded = async (input, init) => {
+        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;
+}
+//# sourceMappingURL=guarded-fetch.js.map

package/dist/x402-buyer/guarded-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-fetch.js","sourceRoot":"","sources":["../../src/x402-buyer/guarded-fetch.ts"],"names":[],"mappings":"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"}

package/dist/x402-buyer/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@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";
+//# sourceMappingURL=index.d.ts.map

package/dist/x402-buyer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/x402-buyer/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC"}

package/dist/x402-buyer/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@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";
+//# sourceMappingURL=index.js.map

package/dist/x402-buyer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/x402-buyer/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC"}

package/dist/x402-buyer/pay.d.ts

@@ -0,0 +1,157 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import { payWithX402, type PayWithX402Options, type PayWithX402Result, type SignedTransferAuthorization, type X402PayerSigner, type X402QuoteSummary } from "@absol-labs/sdk/x402";
+import { type PublicClient } from "viem";
+import { type HireRequest, type MandateDecision, type SignedSpendMandate } from "../mandates/mandate.js";
+/**
+ * Buyer-side x402 payments under a spend mandate (metrik-agent#121).
+ *
+ * The golden rule of this package — no spend without a mandate — applies to an
+ * x402 payment exactly as it applies to `metrik open`, because a Metrik x402
+ * payment IS a stream open: the opener facilitator settles the payer's EIP-3009
+ * authorization with `factory.deployAndSettle`, which opens a `StreamEscrowV2`
+ * stream with `deposit = price`. So the payment is mapped onto the SAME
+ * {@link HireRequest} a stream open is checked as, from the quote's opener terms
+ * (which the SDK has already proven on-chain: `payTo == factory.predict(terms)`):
+ *
+ * | Mandate field          | x402 quote field                                 |
+ * | ---------------------- | ------------------------------------------------ |
+ * | `maxPerStreamUsdc`     | `amount` (the deposit; the price of the call)    |
+ * | `maxTotalUsdc`         | `spentSoFar + amount`                            |
+ * | `maxRatePerSecondUsdc` | `ratePerSecond` (how fast the seller can earn)   |
+ * | `maxDurationSeconds`   | `maxDuration` (the stream's window)              |
+ * | `allowedOperators`     | `operator` (who the stream pays)                 |
+ *
+ * An UPFRONT ("minimum charge") opener quote is mapped the same way, with
+ * `budgetUsdc = price` — the WHOLE payment, of which `upfrontAmount` is
+ * non-refundable (paid to the seller at settlement) and only the rest is
+ * escrowed. So the per-stream and total caps always count the upfront part as
+ * spent, and nothing a refund returns is ever credited back. Its size is also
+ * capped separately, before signing, by the SDK's `maxUpfrontAmount` (default
+ * 0.10 USDC; pass {@link PayX402WithMandateInput.maxUpfrontAmount} to tighten
+ * it, `0n` to refuse every upfront charge).
+ *
+ * The check runs inside the SDK's `onQuote` hook — after every SDK protection
+ * (scheme, network, USDC domain, EIP-3009 only, registered factory, on-chain
+ * `predict`, authorization lifetime) and BEFORE anything is signed — so a
+ * denied payment never produces a signature. It is enforced twice: the mandate's
+ * caps are also handed to the SDK as `maxAmount` / `maxRatePerSecond`. A quote
+ * that is not a Metrik opener payment (no operator/rate/duration terms) is
+ * refused: there would be no stream to bound and nothing to recover.
+ *
+ * The mandate itself (signature, expiry, revocation) is verified FIRST, before
+ * any request reaches the seller.
+ */
+/** A payment refused by the spend mandate. Nothing was signed. */
+export declare class X402MandateDeniedError extends Error {
+    readonly reason: NonNullable<MandateDecision["reason"]> | "not-an-opener-quote";
+    readonly quote: X402QuoteSummary | null;
+    constructor(reason: X402MandateDeniedError["reason"], quote: X402QuoteSummary | null, detail?: string);
+}
+/**
+ * The stream-open request an x402 quote would create, or a refusal reason when
+ * the quote does not carry Metrik opener terms.
+ */
+export declare function x402QuoteToHireRequest(quote: X402QuoteSummary): HireRequest | {
+    readonly refused: string;
+};
+export interface PayX402WithMandateInput {
+    readonly url: string | URL;
+    readonly init?: RequestInit;
+    /** The payer: signs the EIP-3009 authorization. Needs USDC, no gas. */
+    readonly signer: X402PayerSigner;
+    readonly network: MetrikNetwork;
+    readonly signedMandate: SignedSpendMandate;
+    /** USDC already spent under this mandate (the cumulative-cap input). */
+    readonly spentSoFarUsdc: bigint;
+    readonly nowSeconds: number;
+    readonly revokedMandateIds?: Iterable<`0x${string}`>;
+    /** An explicit price ceiling, tighter than the mandate (never looser). */
+    readonly maxAmount?: bigint;
+    /** An explicit rate ceiling, tighter than the mandate (never looser). */
+    readonly maxRatePerSecond?: bigint;
+    /** Refuse a quote the seller can fully earn in fewer verified seconds. */
+    readonly minDurationSeconds?: number;
+    /**
+     * Ceiling on the NON-REFUNDABLE upfront part of an upfront-opener quote, base
+     * units (the SDK's `maxUpfrontAmount`). Default the SDK's 0.10 USDC; `0n`
+     * refuses any upfront charge. Never above the price ceiling in effect.
+     */
+    readonly maxUpfrontAmount?: bigint;
+    /** Passed through to the SDK (transport, fetch, publicClient, ...). */
+    readonly sdkOptions?: Pick<PayWithX402Options, "publicClient" | "transport" | "fetch" | "allowInsecureHttp" | "maxAuthorizationSeconds" | "allowLegacyFactory">;
+    /** Test seam: the SDK payer. Default `payWithX402`. */
+    readonly payImpl?: typeof payWithX402;
+    /**
+     * Called once the mandate APPROVES a quote, BEFORE the SDK signs it. A
+     * caller that tracks cumulative spend reserves the payment here, so a
+     * failure after the signature is handed out can never leave it uncounted.
+     * Throwing refuses the quote (nothing is signed).
+     */
+    readonly onApproved?: (approval: {
+        readonly request: HireRequest;
+        readonly quote: X402QuoteSummary;
+    }) => void | Promise<void>;
+    /**
+     * Chain reads used after a post-signature failure (USDC
+     * `authorizationState`, the opener's `StreamOpenedFor` log). Default: the
+     * SDK options' `publicClient`, else a client over their `transport`, else
+     * the network's first RPC.
+     */
+    readonly chainReader?: Pick<PublicClient, "readContract" | "getLogs" | "getBlockNumber">;
+}
+/** What is known about a payment whose signature was handed out but that did not complete cleanly. */
+export type X402PostSignatureState = 
+/** The authorization was used: the money left the payer. */
+"used"
+/** It could not be established either way. Treat as used. */
+ | "possibly-used"
+/** Not used yet, but still valid until `validBefore`: a holder can still submit it. */
+ | "unused-but-valid"
+/** Not used and past `validBefore`: it can never move funds. */
+ | "unused-expired";
+/**
+ * The payment was APPROVED and its authorization signed and handed to the
+ * seller, then something failed (a malformed or missing PAYMENT-RESPONSE, a
+ * settlement the SDK could not confirm, a dropped connection). The money may
+ * have moved: {@link X402PostSignatureError.state} says what is known, and
+ * {@link X402PostSignatureError.releasable} is `true` only when the
+ * authorization provably can never be used. A spend reservation must be kept
+ * otherwise.
+ */
+export declare class X402PostSignatureError extends Error {
+    readonly state: X402PostSignatureState;
+    readonly approved: HireRequest;
+    readonly quote: X402QuoteSummary;
+    readonly authorization: SignedTransferAuthorization | null;
+    /** The stream the payment opened, when it could be identified. */
+    readonly streamId: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    /**
+     * `true` when the chain shows (or the signed quote implies) an UPFRONT-ONLY
+     * payment: no stream, the whole price was a non-refundable charge, nothing
+     * to recover.
+     */
+    readonly upfrontOnly: boolean;
+    constructor(context: {
+        readonly state: X402PostSignatureState;
+        readonly approved: HireRequest;
+        readonly quote: X402QuoteSummary;
+        readonly authorization: SignedTransferAuthorization | null;
+        readonly streamId: `0x${string}` | null;
+        readonly upfrontOnly?: boolean;
+        readonly cause: unknown;
+    });
+    /** Only an authorization that provably can never move funds frees its reservation. */
+    get releasable(): boolean;
+}
+export interface PayX402WithMandateResult extends PayWithX402Result {
+    /** The stream-open request the mandate approved (null if nothing was paid). */
+    readonly approved: HireRequest | null;
+}
+/**
+ * Pay an x402 v2 endpoint through the SDK's `payWithX402`, gated by
+ * `checkMandate()`. Fail closed: a mandate that does not verify, a quote it
+ * denies, or a quote without opener terms is a hard stop with nothing signed.
+ */
+export declare function payX402WithMandate(input: PayX402WithMandateInput): Promise<PayX402WithMandateResult>;
+//# sourceMappingURL=pay.d.ts.map

package/dist/x402-buyer/pay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../../src/x402-buyer/pay.ts"],"names":[],"mappings":"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"}