@goassay-ai/sdk 0.0.0-stage → 0.1.0

package/dist/core/binding.js

@@ -0,0 +1,132 @@
+import { SignerRefusal } from "./errors.js";
+import { getAddress, isAddress } from "./hex.js";
+/** The binding proof's own EIP-712 domain (spec section 5). Not the escrow's. */
+export const DELEGATE_BINDING_DOMAIN_NAME = "GoAssay Agent Binding";
+export const DELEGATE_BINDING_DOMAIN_VERSION = "1";
+/** The longest challenge life a client accepts: the server's challenge TTL. */
+export const MAX_BINDING_CHALLENGE_SECONDS = 300;
+/** Exactly these fields, in this order. The order is part of the type hash. */
+export const DELEGATE_BINDING_TYPES = {
+    DelegateBinding: [
+        { name: "delegate", type: "address" },
+        { name: "credentialId", type: "string" },
+        { name: "nonce", type: "string" },
+        { name: "expiresAt", type: "uint64" },
+    ],
+};
+/** The typed data for checked values. */
+export function bindingTypedData(chainId, message) {
+    return {
+        domain: { name: DELEGATE_BINDING_DOMAIN_NAME, version: DELEGATE_BINDING_DOMAIN_VERSION, chainId },
+        types: DELEGATE_BINDING_TYPES,
+        primaryType: "DelegateBinding",
+        message,
+    };
+}
+const DOMAIN_KEYS = ["name", "version", "chainId"];
+const MESSAGE_KEYS = ["delegate", "credentialId", "nonce", "expiresAt"];
+const MAX_UINT64 = 2n ** 64n - 1n;
+const MAX_NONCE_LENGTH = 256;
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function refuse(field, reason) {
+    throw new SignerRefusal("the binding challenge", field, reason);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A non-negative integer given as a JSON number or a decimal string. */
+function toInteger(value) {
+    if (typeof value === "number")
+        return Number.isSafeInteger(value) && value >= 0 ? BigInt(value) : null;
+    if (typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value))
+        return BigInt(value);
+    return null;
+}
+/**
+ * Checks the server's `DelegateBinding` challenge (the `data` of the challenge answer) field by
+ * field (spec section 5.2) and returns the typed data to sign, rebuilt from the client's own
+ * constants. Throws `SignerRefusal` naming the first field that fails.
+ */
+export function checkBindingChallenge(challenge, ctx) {
+    if (!Number.isSafeInteger(ctx.chainId) || ctx.chainId < 1)
+        refuse("context.chainId", "is not a chain id");
+    if (!Number.isFinite(ctx.nowSeconds) || ctx.nowSeconds < 0)
+        refuse("context.nowSeconds", "is not a usable time");
+    if (!isAddress(ctx.localAddress))
+        refuse("context.localAddress", "is not an address");
+    if (typeof ctx.credentialId !== "string" || ctx.credentialId.length === 0)
+        refuse("context.credentialId", "is empty");
+    if (!isRecord(challenge))
+        refuse("challenge", "is not an object");
+    const t = challenge.typedData;
+    if (!isRecord(t))
+        refuse("typedData", "is not an object");
+    const domain = t.domain;
+    if (!isRecord(domain))
+        refuse("domain", "is not an object");
+    for (const key of Object.keys(domain)) {
+        if (!DOMAIN_KEYS.includes(key))
+            refuse(`domain.${key}`, "must not be present");
+    }
+    if (domain.name !== DELEGATE_BINDING_DOMAIN_NAME)
+        refuse("domain.name", `must be "${DELEGATE_BINDING_DOMAIN_NAME}"`);
+    if (domain.version !== DELEGATE_BINDING_DOMAIN_VERSION) {
+        refuse("domain.version", `must be "${DELEGATE_BINDING_DOMAIN_VERSION}"`);
+    }
+    const chainId = toInteger(domain.chainId);
+    if (chainId === null || chainId !== BigInt(ctx.chainId))
+        refuse("domain.chainId", `must be ${ctx.chainId}`);
+    if (t.primaryType !== "DelegateBinding")
+        refuse("primaryType", 'must be "DelegateBinding"');
+    const types = t.types;
+    if (!isRecord(types))
+        refuse("types", "is not an object");
+    for (const key of Object.keys(types)) {
+        if (key !== "DelegateBinding")
+            refuse(`types.${key}`, "must not be present");
+    }
+    const fields = types.DelegateBinding;
+    const expected = DELEGATE_BINDING_TYPES.DelegateBinding;
+    const fieldsMatch = Array.isArray(fields) &&
+        fields.length === expected.length &&
+        fields.every((f, i) => isRecord(f) && Object.keys(f).length === 2 && f.name === expected[i].name && f.type === expected[i].type);
+    if (!fieldsMatch) {
+        refuse("types.DelegateBinding", "must be exactly delegate:address, credentialId:string, nonce:string, expiresAt:uint64");
+    }
+    const message = t.message;
+    if (!isRecord(message))
+        refuse("message", "is not an object");
+    for (const key of Object.keys(message)) {
+        if (!MESSAGE_KEYS.includes(key))
+            refuse(`message.${key}`, "must not be present");
+    }
+    const delegate = message.delegate;
+    if (!isAddress(delegate))
+        refuse("message.delegate", "is not an address");
+    if (getAddress(delegate) !== getAddress(ctx.localAddress))
+        refuse("message.delegate", "is not the local key");
+    if (message.credentialId !== ctx.credentialId)
+        refuse("message.credentialId", "is not this key's credential");
+    const nonce = message.nonce;
+    if (typeof nonce !== "string" || nonce.length === 0 || nonce.length > MAX_NONCE_LENGTH) {
+        refuse("message.nonce", "is not a usable nonce");
+    }
+    const expiresAt = toInteger(message.expiresAt);
+    if (expiresAt === null || expiresAt > MAX_UINT64)
+        refuse("message.expiresAt", "is not a uint64");
+    const now = BigInt(Math.floor(ctx.nowSeconds));
+    if (expiresAt <= now)
+        refuse("message.expiresAt", "is not in the future");
+    if (expiresAt > now + BigInt(MAX_BINDING_CHALLENGE_SECONDS)) {
+        refuse("message.expiresAt", `is more than ${MAX_BINDING_CHALLENGE_SECONDS}s away`);
+    }
+    if (typeof challenge.challengeId !== "string" || !UUID.test(challenge.challengeId)) {
+        refuse("challengeId", "is not a UUID");
+    }
+    return bindingTypedData(ctx.chainId, {
+        delegate: getAddress(delegate),
+        credentialId: ctx.credentialId,
+        nonce,
+        expiresAt,
+    });
+}

package/dist/core/caip.d.ts

@@ -0,0 +1,15 @@
+import { type Address } from "./hex.js";
+/** The namespace of a CAIP-2 chain id (`eip155` of `eip155:1`), or `null`. */
+export declare function namespaceOf(caip2: unknown): string | null;
+/** The chain id of an `eip155:<id>` CAIP-2 chain, or `null`. */
+export declare function eip155ChainId(caip2: unknown): number | null;
+/** A CAIP-10 account on eip155 with a checksummed address, or `null`. */
+export declare function parseCaip10(value: string): {
+    chainId: number;
+    address: Address;
+} | null;
+/** A CAIP-19 erc20 asset on eip155 with a checksummed address, or `null`. */
+export declare function parseCaip19Erc20(value: string): {
+    chainId: number;
+    address: Address;
+} | null;

package/dist/core/caip.js

@@ -0,0 +1,31 @@
+import { isChecksummed } from "./hex.js";
+const CAIP2_EIP155 = /^eip155:([1-9][0-9]*)$/;
+const CAIP10 = /^eip155:([1-9][0-9]*):(0x[0-9a-fA-F]{40})$/;
+const CAIP19_ERC20 = /^eip155:([1-9][0-9]*)\/erc20:(0x[0-9a-fA-F]{40})$/;
+/** The namespace of a CAIP-2 chain id (`eip155` of `eip155:1`), or `null`. */
+export function namespaceOf(caip2) {
+    const m = typeof caip2 === "string" ? /^([-a-z0-9]{3,8}):[-_a-zA-Z0-9]{1,32}$/.exec(caip2) : null;
+    return m ? m[1] : null;
+}
+/** The chain id of an `eip155:<id>` CAIP-2 chain, or `null`. */
+export function eip155ChainId(caip2) {
+    const m = typeof caip2 === "string" ? CAIP2_EIP155.exec(caip2) : null;
+    if (!m)
+        return null;
+    const id = Number(m[1]);
+    return Number.isSafeInteger(id) ? id : null;
+}
+/** A CAIP-10 account on eip155 with a checksummed address, or `null`. */
+export function parseCaip10(value) {
+    const m = CAIP10.exec(value);
+    if (!m || !isChecksummed(m[2]))
+        return null;
+    return { chainId: Number(m[1]), address: m[2] };
+}
+/** A CAIP-19 erc20 asset on eip155 with a checksummed address, or `null`. */
+export function parseCaip19Erc20(value) {
+    const m = CAIP19_ERC20.exec(value);
+    if (!m || !isChecksummed(m[2]))
+        return null;
+    return { chainId: Number(m[1]), address: m[2] };
+}

package/dist/core/chain.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read-only chain reads of the payment key's grant and caps (G4, G6): three escrow views at one
+ * pinned block, on every RPC the caller listed for the network. Every RPC must answer the same
+ * chain id and the same bytes, or there is no read (the guards then refuse: fail closed).
+ *
+ * `delegationOf(payer, delegate)`, `effectiveCapsOf(payer, delegate)` and `escrowOf(payer)`. Each
+ * cap is the lower of the effective envelope and the current value: strictest wins.
+ */
+import type { ChainState } from "./guard-types.js";
+import { type Address } from "./hex.js";
+/** How long an agreed read stands (G4 accepts a read at most 600 s old). */
+export declare const CHAIN_CACHE_MS: number;
+/** The most two RPCs' latest heights may differ before the read refuses. */
+export declare const MAX_BLOCK_SPREAD = 5n;
+export type FetchFn = (input: string, init: RequestInit) => Promise<Response>;
+export interface ChainReaderOptions {
+    fetch: FetchFn;
+    /** Milliseconds clock. */
+    now: () => number;
+}
+export interface ChainNetwork {
+    /** CAIP-2, `eip155:<id>`. */
+    id: string;
+    chainId: number;
+    escrow: Address;
+    rpc: readonly string[];
+}
+/** https, or http to a loopback host; no credentials, query or fragment. */
+export declare function isUsableRpcUrl(value: string): boolean;
+export declare class ChainReader {
+    #private;
+    constructor(options: ChainReaderOptions);
+    /** The agreed read for `payer` and `delegate` (checksummed), or `null` (fail closed). */
+    read(net: ChainNetwork, payer: Address, delegate: Address): Promise<ChainState | null>;
+    /** Drops a cached read, so the next payment reads the chain again (after a revocation). */
+    invalidate(net: string, payer: string, delegate: string): void;
+}

package/dist/core/chain.js

@@ -0,0 +1,148 @@
+import { getAddress, keccakUtf8 } from "./hex.js";
+/** How long an agreed read stands (G4 accepts a read at most 600 s old). */
+export const CHAIN_CACHE_MS = 10 * 60 * 1000;
+/** The most two RPCs' latest heights may differ before the read refuses. */
+export const MAX_BLOCK_SPREAD = 5n;
+const MAX_RESPONSE_CHARS = 16 * 1024;
+const RPC_TIMEOUT_MS = 5_000;
+const selector = (signature) => keccakUtf8(signature).slice(2, 10);
+const DELEGATION_OF = selector("delegationOf(address,address)");
+const EFFECTIVE_CAPS_OF = selector("effectiveCapsOf(address,address)");
+const ESCROW_OF = selector("escrowOf(address)");
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+/** https, or http to a loopback host; no credentials, query or fragment. */
+export function isUsableRpcUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (url.username || url.password || url.search || url.hash)
+        return false;
+    return url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK.has(url.hostname));
+}
+const word = (address) => address.slice(2).toLowerCase().padStart(64, "0");
+/** Splits canonical ABI return data into words, checking each word's bit width. */
+function words(data, widths) {
+    if (!/^0x[0-9a-f]*$/.test(data) || data.length !== 2 + widths.length * 64)
+        return null;
+    const out = [];
+    for (let i = 0; i < widths.length; i++) {
+        const n = BigInt(`0x${data.slice(2 + i * 64, 2 + (i + 1) * 64)}`);
+        if (n >> BigInt(widths[i]) !== 0n)
+            return null;
+        out.push(n);
+    }
+    return out;
+}
+const DELEGATION_WIDTHS = [64, 64, 64, 64, 64, 32, 1];
+const CAPS_WIDTHS = [64, 64, 64, 64];
+const ESCROW_WIDTHS = [128, 64, 64, 64, 64, 64, 64, 64, 64, 128, 128, 128];
+const min = (a, b) => (a < b ? a : b);
+export class ChainReader {
+    #fetch;
+    #now;
+    #cache = new Map();
+    #id = 1;
+    constructor(options) {
+        this.#fetch = options.fetch;
+        this.#now = options.now;
+    }
+    /** The agreed read for `payer` and `delegate` (checksummed), or `null` (fail closed). */
+    async read(net, payer, delegate) {
+        const key = JSON.stringify([net.id, payer, delegate]);
+        const hit = this.#cache.get(key);
+        const t = this.#now();
+        if (hit && t >= hit.at && t - hit.at < CHAIN_CACHE_MS)
+            return hit.value;
+        this.#cache.delete(key);
+        let value;
+        try {
+            value = await this.#readOnce(net, payer, delegate, Math.floor(t / 1000));
+        }
+        catch {
+            value = null;
+        }
+        if (value !== null)
+            this.#cache.set(key, { at: t, value });
+        return value;
+    }
+    /** Drops a cached read, so the next payment reads the chain again (after a revocation). */
+    invalidate(net, payer, delegate) {
+        this.#cache.delete(JSON.stringify([net, payer, delegate]));
+    }
+    async #readOnce(net, payer, delegate, readAt) {
+        const rpcs = net.rpc;
+        if (rpcs.length < 1 || new Set(rpcs).size !== rpcs.length || !rpcs.every(isUsableRpcUrl))
+            return null;
+        const heads = await Promise.all(rpcs.map(async (url) => {
+            const [id, height] = await Promise.all([
+                this.#call(url, "eth_chainId", []),
+                this.#call(url, "eth_blockNumber", []),
+            ]);
+            return { id: quantity(id), height: quantity(height) };
+        }));
+        if (heads.some((h) => h.id === null || h.height === null || h.id !== BigInt(net.chainId)))
+            return null;
+        const heights = heads.map((h) => h.height);
+        const low = heights.reduce((x, y) => (y < x ? y : x));
+        const high = heights.reduce((x, y) => (y > x ? y : x));
+        if (high - low > MAX_BLOCK_SPREAD || low < 1n)
+            return null;
+        // One block behind the lowest head, so every RPC has it.
+        const block = `0x${(low - 1n).toString(16)}`;
+        const calls = [
+            `0x${DELEGATION_OF}${word(payer)}${word(delegate)}`,
+            `0x${EFFECTIVE_CAPS_OF}${word(payer)}${word(delegate)}`,
+            `0x${ESCROW_OF}${word(payer)}`,
+        ];
+        const answers = await Promise.all(rpcs.map((url) => Promise.all(calls.map(async (data) => String(await this.#call(url, "eth_call", [{ to: net.escrow, data }, block])).toLowerCase()))));
+        const first = answers[0];
+        if (answers.some((a) => a.some((x, i) => x !== first[i])))
+            return null;
+        const d = words(first[0], DELEGATION_WIDTHS);
+        const caps = words(first[1], CAPS_WIDTHS);
+        const e = words(first[2], ESCROW_WIDTHS);
+        if (!d || !caps || !e)
+            return null;
+        const [dMax, , , , validUntil, , revoked] = d;
+        return {
+            payer: getAddress(payer),
+            delegate: getAddress(delegate),
+            readAt,
+            active: validUntil !== 0n && revoked === 0n,
+            validUntil: validUntil.toString(),
+            maxVoucherAmount: min(caps[0], e[3]).toString(),
+            delegateMaxVoucherAmount: min(caps[2], dMax).toString(),
+        };
+    }
+    async #call(url, method, params) {
+        const id = this.#id++;
+        const signal = AbortSignal.timeout(RPC_TIMEOUT_MS);
+        const res = await this.#fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+            redirect: "error",
+            signal,
+        });
+        const text = await res.text();
+        if (res.status !== 200 || text.length > MAX_RESPONSE_CHARS)
+            throw new Error("rpc failed");
+        const msg = JSON.parse(text);
+        if (msg === null ||
+            typeof msg !== "object" ||
+            msg.jsonrpc !== "2.0" ||
+            msg.id !== id ||
+            "error" in msg ||
+            !("result" in msg)) {
+            throw new Error("rpc failed");
+        }
+        return msg.result;
+    }
+}
+function quantity(value) {
+    return typeof value === "string" && /^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/i.test(value) ? BigInt(value) : null;
+}

package/dist/core/clock.d.ts

@@ -0,0 +1,12 @@
+/** The largest correction the HTTP `Date` header may apply to the local clock (spec section 7). */
+export declare const MAX_CLOCK_CORRECTION_SECONDS = 120;
+/**
+ * The server's clock minus the local one, in whole seconds, from an HTTP `Date` header. A missing
+ * or unreadable header gives 0. Not clamped here: {@link correctedNow} clamps.
+ */
+export declare function dateHeaderOffset(dateHeader: string | null | undefined, localNowSeconds: number): number;
+/**
+ * The local time corrected by a `Date` offset clamped to +-120 s, so a server (or anyone on the
+ * path) can move the client's clock by at most 120 s either way.
+ */
+export declare function correctedNow(localNowSeconds: number, offsetSeconds: number): number;

package/dist/core/clock.js

@@ -0,0 +1,25 @@
+/** The largest correction the HTTP `Date` header may apply to the local clock (spec section 7). */
+export const MAX_CLOCK_CORRECTION_SECONDS = 120;
+/**
+ * The server's clock minus the local one, in whole seconds, from an HTTP `Date` header. A missing
+ * or unreadable header gives 0. Not clamped here: {@link correctedNow} clamps.
+ */
+export function dateHeaderOffset(dateHeader, localNowSeconds) {
+    if (!dateHeader)
+        return 0;
+    const serverMs = Date.parse(dateHeader);
+    if (!Number.isFinite(serverMs) || !Number.isFinite(localNowSeconds))
+        return 0;
+    return Math.floor(serverMs / 1000) - Math.floor(localNowSeconds);
+}
+/**
+ * The local time corrected by a `Date` offset clamped to +-120 s, so a server (or anyone on the
+ * path) can move the client's clock by at most 120 s either way.
+ */
+export function correctedNow(localNowSeconds, offsetSeconds) {
+    if (!Number.isFinite(localNowSeconds) || localNowSeconds < 0)
+        throw new Error("the local clock is not a usable time");
+    const offset = Number.isFinite(offsetSeconds) ? offsetSeconds : 0;
+    const clamped = Math.max(-MAX_CLOCK_CORRECTION_SECONDS, Math.min(MAX_CLOCK_CORRECTION_SECONDS, offset));
+    return Math.floor(localNowSeconds) + Math.trunc(clamped);
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A refusal to sign. `field` names the first value that failed its check, so a caller (and a
+ * test) can tell which check refused without parsing the message. The message never carries a
+ * key or a signature.
+ */
+export declare class SignerRefusal extends Error {
+    readonly field: string;
+    constructor(what: string, field: string, reason: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,13 @@
+/**
+ * A refusal to sign. `field` names the first value that failed its check, so a caller (and a
+ * test) can tell which check refused without parsing the message. The message never carries a
+ * key or a signature.
+ */
+export class SignerRefusal extends Error {
+    field;
+    constructor(what, field, reason) {
+        super(`refusing to sign ${what}: ${field} ${reason}`);
+        this.name = "SignerRefusal";
+        this.field = field;
+    }
+}

package/dist/core/guard-types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Inputs and results of the local guards (spec section 9). Every value the guards read is passed in:
+ * the guards do no I/O, read no clock and keep no state, so the same vectors (`vectors/guards.json`)
+ * can drive every implementation.
+ *
+ * Integers that can exceed 2^53 (amounts, caps, spend) are decimal strings. Addresses the client
+ * holds itself (`localKey`, `recordedPayer`, `chain.payer`, `limits.providers`) may be a bare
+ * `0x` address in any case or a CAIP-10 account; values from the server's requirement must be
+ * checksummed CAIP-10 accounts on the requirement's network.
+ */
+/** The guard that refused. */
+export type GuardId = "G1" | "G2" | "G3" | "G4" | "G5" | "G6" | "G7" | "G8" | "G9" | "G10" | "G11" | "G12";
+/**
+ * Stable refusal codes, shared with every implementation through the vectors. Each code names
+ * one check; never rename or reuse one.
+ */
+export declare const REFUSAL_CODES: {
+    readonly G1_NOT_A_REQUIREMENT: "G1";
+    readonly G1_RAIL: "G1";
+    readonly G1_SCHEME: "G1";
+    readonly G1_NOT_FORWARDED: "G1";
+    readonly G1_FORWARD_TOO_OLD: "G1";
+    readonly G2_NETWORK: "G2";
+    readonly G2_PAY_TO: "G2";
+    readonly G2_ASSET: "G2";
+    readonly G2_DECIMALS: "G2";
+    readonly G2_AMOUNT: "G2";
+    readonly G3_NO_QUOTE: "G3";
+    readonly G3_QUOTE_ASSET: "G3";
+    readonly G3_ABOVE_QUOTE: "G3";
+    readonly G4_NO_CHAIN_READ: "G4";
+    readonly G4_PAYER_INVALID: "G4";
+    readonly G4_PAYER_CHANGED: "G4";
+    readonly G4_NOT_DELEGATED: "G4";
+    readonly G4_OTHER_KEY: "G4";
+    readonly G4_STALE_READ: "G4";
+    readonly G4_INACTIVE: "G4";
+    readonly G4_EXPIRED: "G4";
+    readonly G5_LOCAL_KEY_INVALID: "G5";
+    readonly G5_NO_DELEGATE_SIGNER: "G5";
+    readonly G5_DELEGATE_MISMATCH: "G5";
+    readonly G5_LOCAL_KEY_IS_PAYER: "G5";
+    readonly G6_CAPS_UNREADABLE: "G6";
+    readonly G6_DELEGATE_CAP: "G6";
+    readonly G6_ESCROW_CAP: "G6";
+    readonly G7_LIMITS_UNREADABLE: "G7";
+    readonly G7_PER_CALL: "G7";
+    readonly G7_STATE_UNREADABLE: "G7";
+    readonly G7_PER_DAY: "G7";
+    readonly G7_CONFIRMATION_REQUIRED: "G7";
+    readonly G7_CONFIRMATION_MISMATCH: "G7";
+    readonly G8_PROVIDER_INVALID: "G8";
+    readonly G8_PROVIDERS_UNREADABLE: "G8";
+    readonly G8_PROVIDER_NOT_ALLOWED: "G8";
+    readonly G9_SEQ: "G9";
+    readonly G10_REQUEST_HASH: "G10";
+    readonly G10_RESOURCE: "G10";
+    readonly G10_MAX_TIMEOUT: "G10";
+    /** App-only (a per-URL paid list, as in assay-mcp); the SDK never raises it. */
+    readonly G11_URL_NOT_PAID: "G11";
+    readonly G12_DEBT_OR_SEQ_ENDPOINT: "G12";
+    readonly G12_NOT_A_TOOL_CALL: "G12";
+    readonly G12_OTHER_TOOL: "G12";
+};
+export type RefusalCode = keyof typeof REFUSAL_CODES;
+/** The client's own entry for a network (never from the server), with its CAIP-2 id. */
+export interface BuiltInNetwork {
+    id: string;
+    escrow: string;
+    asset: string;
+    decimals: number;
+}
+/**
+ * `assay/price` for the forwarded tool (`forwardedCall.tool`, never a name taken from the
+ * requirement) in the same exchange (G3). `maxAmount` is in atomic units of `asset`.
+ */
+export interface Quote {
+    maxAmount: string;
+    /** CAIP-19; must be the requirement's asset. */
+    asset: string;
+}
+/** The agreed chain read of the payment key's grant and caps (G4, G6). */
+export interface ChainState {
+    /** The payer the grant was read for. */
+    payer: string;
+    /** The key the grant was read for; must be the local key. */
+    delegate: string;
+    /** When the read was made, Unix seconds on the same clock as `nowSeconds`; at most 600 s old. */
+    readAt: number;
+    delegateMaxVoucherAmount: string;
+    maxVoucherAmount: string;
+    /** The grant exists and is not revoked. */
+    active: boolean;
+    /** `delegationOf(...).validUntil`, Unix seconds. */
+    validUntil: string | number;
+}
+/** The local limits (G7, G8). Dollar values are decimal strings. */
+export interface LocalLimits {
+    /** Dollars per call, e.g. "0.50". */
+    perCall: string;
+    /** Dollars per rolling 24 h, e.g. "5". */
+    perDay: string;
+    /** Dollars; above this the user must confirm. `null` is off. */
+    confirmAbove: string | null;
+    /** Provider allow-list (G8). `null` is off (any provider). */
+    providers: string[] | null;
+}
+/** The default local limits (G7): $0.50 a call, $5 per rolling 24 h. */
+export declare const DEFAULT_LIMITS: Readonly<LocalLimits>;
+/**
+ * The `tools/call` this process forwarded, whose answer carried the requirement (G1, G12).
+ * `tool` is the original tool name the call reached (after alias mapping; on `call_tool`, the
+ * inner `name`).
+ */
+export interface ForwardedCall {
+    tool: string;
+    /** When the call was forwarded, Unix seconds on the same clock as `nowSeconds`. */
+    at: number;
+}
+/** One signed voucher: when it was signed and its atomic amount. */
+export interface SignedVoucher {
+    at: number;
+    amount: string;
+}
+/**
+ * What the user was shown and approved through MCP elicitation (G7 `confirmAbove`). It approves
+ * only a requirement with exactly these values; build it with `confirmationFor`.
+ */
+export interface Confirmation {
+    tool: string;
+    provider: string;
+    amount: string;
+    asset: string;
+    network: string;
+    payTo: string;
+    seq: string;
+}
+export interface GuardContext {
+    /** `_meta["x402/paymentRequired"]` as received; untrusted, so not typed. */
+    requirement: unknown;
+    /** The call this requirement answers, or `null` when there is none (G1). */
+    forwardedCall: ForwardedCall | null;
+    /** The built-in entry for `requirement.network`, or `null` when the table has none (G2). */
+    network: BuiltInNetwork | null;
+    /** The quote for this tool (cached ≤ 60 s, or a fresh `get_tool`), or `null` (G3). */
+    quote: Quote | null;
+    /** The agreed chain read, or `null` when there is none or the RPCs disagree (G4, G6). */
+    chain: ChainState | null;
+    /** The local delegate key's address (G5). */
+    localKey: string;
+    /** The payer recorded after a chain-confirmed first voucher, or `null` (G4). */
+    recordedPayer: string | null;
+    limits: LocalLimits;
+    /**
+     * Every voucher this key signed (G7). Each one signed after
+     * `nowSeconds - 86400` counts, including any dated in the future.
+     */
+    signed: SignedVoucher[];
+    /** The user's approval of this exact payment, or `null` (G7 `confirmAbove`). */
+    confirmation: Confirmation | null;
+    /**
+     * Unix seconds from the local clock, never the `Date`-corrected one, for G1, G4 and the G7
+     * window. (The `Date` correction applies only to the voucher's `issuedAt`.)
+     */
+    nowSeconds: number;
+}
+export type GuardResult = {
+    ok: true;
+} | {
+    ok: false;
+    guard: GuardId;
+    code: RefusalCode;
+    reason: string;
+};

package/dist/core/guard-types.js

@@ -0,0 +1,69 @@
+/**
+ * Inputs and results of the local guards (spec section 9). Every value the guards read is passed in:
+ * the guards do no I/O, read no clock and keep no state, so the same vectors (`vectors/guards.json`)
+ * can drive every implementation.
+ *
+ * Integers that can exceed 2^53 (amounts, caps, spend) are decimal strings. Addresses the client
+ * holds itself (`localKey`, `recordedPayer`, `chain.payer`, `limits.providers`) may be a bare
+ * `0x` address in any case or a CAIP-10 account; values from the server's requirement must be
+ * checksummed CAIP-10 accounts on the requirement's network.
+ */
+/**
+ * Stable refusal codes, shared with every implementation through the vectors. Each code names
+ * one check; never rename or reuse one.
+ */
+export const REFUSAL_CODES = {
+    G1_NOT_A_REQUIREMENT: "G1",
+    G1_RAIL: "G1",
+    G1_SCHEME: "G1",
+    G1_NOT_FORWARDED: "G1",
+    G1_FORWARD_TOO_OLD: "G1",
+    G2_NETWORK: "G2",
+    G2_PAY_TO: "G2",
+    G2_ASSET: "G2",
+    G2_DECIMALS: "G2",
+    G2_AMOUNT: "G2",
+    G3_NO_QUOTE: "G3",
+    G3_QUOTE_ASSET: "G3",
+    G3_ABOVE_QUOTE: "G3",
+    G4_NO_CHAIN_READ: "G4",
+    G4_PAYER_INVALID: "G4",
+    G4_PAYER_CHANGED: "G4",
+    G4_NOT_DELEGATED: "G4",
+    G4_OTHER_KEY: "G4",
+    G4_STALE_READ: "G4",
+    G4_INACTIVE: "G4",
+    G4_EXPIRED: "G4",
+    G5_LOCAL_KEY_INVALID: "G5",
+    G5_NO_DELEGATE_SIGNER: "G5",
+    G5_DELEGATE_MISMATCH: "G5",
+    G5_LOCAL_KEY_IS_PAYER: "G5",
+    G6_CAPS_UNREADABLE: "G6",
+    G6_DELEGATE_CAP: "G6",
+    G6_ESCROW_CAP: "G6",
+    G7_LIMITS_UNREADABLE: "G7",
+    G7_PER_CALL: "G7",
+    G7_STATE_UNREADABLE: "G7",
+    G7_PER_DAY: "G7",
+    G7_CONFIRMATION_REQUIRED: "G7",
+    G7_CONFIRMATION_MISMATCH: "G7",
+    G8_PROVIDER_INVALID: "G8",
+    G8_PROVIDERS_UNREADABLE: "G8",
+    G8_PROVIDER_NOT_ALLOWED: "G8",
+    G9_SEQ: "G9",
+    G10_REQUEST_HASH: "G10",
+    G10_RESOURCE: "G10",
+    G10_MAX_TIMEOUT: "G10",
+    /** App-only (a per-URL paid list, as in assay-mcp); the SDK never raises it. */
+    G11_URL_NOT_PAID: "G11",
+    G12_DEBT_OR_SEQ_ENDPOINT: "G12",
+    G12_NOT_A_TOOL_CALL: "G12",
+    G12_OTHER_TOOL: "G12",
+};
+/** The default local limits (G7): $0.50 a call, $5 per rolling 24 h. */
+export const DEFAULT_LIMITS = Object.freeze({
+    perCall: "0.50",
+    perDay: "5",
+    confirmAbove: null,
+    providers: null,
+});