@odingard/guardian-x402 0.0.0-stage → 0.1.1

package/dist-dts/ledger.d.ts

@@ -0,0 +1,84 @@
+import type { SupportedNetwork } from "./constants.js";
+/**
+ * A durable key-value store with an atomic compare-and-set, supplied by the
+ * developer (a database row with a version column, for example). The guard
+ * keeps budgets and live authorizations in it, so a restart forgets neither.
+ */
+export interface X402GuardStore {
+    /** The current value and its version, or null when the key is absent. */
+    get(key: string): Promise<{
+        value: string;
+        version: string;
+    } | null>;
+    /**
+     * Write `value` only if the key's version is still `expectedVersion`
+     * (null: only if the key is absent). Returns false on a conflict. Must be
+     * atomic.
+     */
+    compareAndSet(key: string, expectedVersion: string | null, value: string): Promise<boolean>;
+}
+/** Reads `authorizationState(from, nonce)` on the token contract. */
+export type AuthorizationStateReader = (query: {
+    network: SupportedNetwork;
+    asset: string;
+    from: string;
+    nonce: string;
+}) => Promise<boolean>;
+export type BudgetConfig = Readonly<{
+    network: SupportedNetwork;
+    asset: string;
+    period: "day" | "month";
+    /** Atomic units of the asset. */
+    limit: string;
+}>;
+/**
+ * One payment's local entry.
+ * - reserved: amount held before Guardian is asked, nothing signed yet
+ * - signing: about to sign; nonce and validBefore are known
+ * - signed: an authorization exists and may be settled until validBefore
+ * - spent: settled, or the chain shows the nonce used; never released
+ * - released: no signature was made, or validBefore passed and the chain
+ *   shows the nonce unused
+ */
+export type LedgerEntry = {
+    id: string;
+    requestKey: string;
+    network: SupportedNetwork;
+    asset: string;
+    amount: string;
+    createdAtMs: number;
+    /** A "reserved" entry is not released by reconcile before this time. */
+    holdUntilMs?: number;
+    state: "reserved" | "signing" | "signed" | "spent" | "released";
+    from?: string;
+    nonce?: string;
+    /** Unix seconds. */
+    validBefore?: number;
+    requestId?: string;
+    sent?: "unknown" | "not-sent";
+};
+/** In-process store used for live authorizations when none is given. */
+export declare function processStore(): X402GuardStore;
+/** Live: may still be settled (or may still be signed). */
+export declare function isLive(e: LedgerEntry, nowMs: number): boolean;
+export declare class Ledger {
+    private readonly store;
+    private readonly budgets;
+    constructor(store: X402GuardStore, budgets: readonly BudgetConfig[]);
+    private read;
+    /** Read-modify-write with compare-and-set; `change` may throw to abort. */
+    private update;
+    entries(): Promise<LedgerEntry[]>;
+    /**
+     * Atomically checks budgets and records a reservation. Returns the live
+     * entries for the same request that existed before this one: same
+     * request key, or one of `sameRequestIds`.
+     */
+    reserve(entry: LedgerEntry, nowMs: number, sameRequestIds?: readonly string[]): Promise<{
+        liveForRequest: LedgerEntry[];
+    }>;
+    patch(id: string, change: (entry: LedgerEntry) => void): Promise<LedgerEntry | undefined>;
+    patchByNonce(nonce: string, change: (entry: LedgerEntry) => void): Promise<LedgerEntry | undefined>;
+    /** Release an entry only if no signature was made for it. */
+    releaseUnsigned(id: string): Promise<void>;
+}

package/dist-dts/mcp.d.ts

@@ -0,0 +1,30 @@
+import { x402MCPClient, type PaymentRequiredHook } from "@x402/mcp";
+import { type X402Guard } from "./guard.js";
+type McpClient = ConstructorParameters<typeof x402MCPClient>[0];
+export type GuardedMcpOptions = Readonly<{
+    /**
+     * The MCP server's URL. When given, a payment whose `resource.url` is
+     * exactly `<serverUrl origin>/tools/<called tool>` is accepted as well as
+     * `mcp://tool/<called tool>`. Any other path or tool on the host is refused.
+     */
+    serverUrl?: string;
+    maxRequestTimeoutSeconds?: number;
+}>;
+/**
+ * The official `x402MCPClient`, built on the guard's client. Each MCP
+ * payment, including the corrective-402 retry, gets exactly one Guardian
+ * decision before the wallet signs.
+ */
+export declare class GuardedX402MCPClient extends x402MCPClient {
+    private readonly serverUrl;
+    constructor(guard: X402Guard, mcpClient: McpClient, options?: GuardedMcpOptions);
+    /**
+     * Refused: an `onPaymentRequired` hook can hand x402 a ready-made payment
+     * that skips the guard.
+     */
+    onPaymentRequired(_hook: PaymentRequiredHook): this;
+    callTool(name: string, args?: Record<string, unknown>, options?: Parameters<x402MCPClient["callTool"]>[2]): ReturnType<x402MCPClient["callTool"]>;
+}
+/** Builds a guarded `x402MCPClient` around an MCP SDK `Client`. */
+export declare function guardedMcpClient(guard: X402Guard, mcpClient: McpClient, options?: GuardedMcpOptions): GuardedX402MCPClient;
+export {};

package/dist-dts/terms.d.ts

@@ -0,0 +1,79 @@
+import { type PinnedAsset, type SupportedNetwork } from "./constants.js";
+import { type Refusal } from "./util.js";
+/** The request a payment belongs to, as the guard saw it. */
+export type PaymentRequestInfo = Readonly<{
+    transport: "http";
+    method: string;
+    /** The URL the agent asked for, before any redirect. */
+    originalUrl: string;
+    /** The URL that answered 402, after redirects (as x402 reports it). */
+    finalUrl: string | null;
+} | {
+    transport: "mcp";
+    method: "tools/call";
+    /** `mcp://tool/<name>` for the tool the agent called. */
+    originalUrl: string;
+    finalUrl: null;
+    toolName: string;
+    /** The MCP server's URL, when the developer gave it. */
+    serverUrl: string | null;
+}>;
+/** What Guardian decides on. Plain JSON, deep-copied and frozen. */
+export type CanonicalTerms = Readonly<{
+    schema: "odingard.guardian.x402.pay.v1";
+    x402Version: 1 | 2;
+    scheme: "exact";
+    network: SupportedNetwork;
+    networkName: string;
+    /** Lowercase token address. */
+    asset: string;
+    assetSymbol: string;
+    /** Integer string in the asset's atomic units. */
+    amount: string;
+    /** For people, from the guard's pinned decimals, e.g. "0.01 USDC". */
+    amountDisplay: string;
+    /** Lowercase recipient address. */
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Readonly<{
+        name: string;
+        version: string;
+        assetTransferMethod: "eip3009";
+        paymentFlow: "authorization";
+    }>;
+    resourceUrl: string;
+    request: Readonly<{
+        transport: "http" | "mcp";
+        method: string;
+        originalUrl: string;
+        finalUrl: string | null;
+    }>;
+}>;
+export type TermsResult = {
+    ok: true;
+    terms: CanonicalTerms;
+    pinned: PinnedAsset;
+} | Refusal;
+export type TermsOptions = Readonly<{
+    enabledNetworks: readonly SupportedNetwork[];
+    maxTimeoutSecondsLimit: number;
+}>;
+/**
+ * The resource URLs that name the called MCP tool, and nothing else:
+ * - `mcp://tool/<tool>`, what `@x402/mcp` names by default
+ *   (`createToolResourceUrl`), compared exactly;
+ * - only when `serverUrl` is given, `<serverUrl origin>/tools/<tool>` with no
+ *   query or fragment (the tool name percent-encoded as a path segment).
+ * Any other path, query or tool on the server host is refused.
+ */
+export declare function mcpResourceMatches(resourceUrl: string, toolName: string, serverUrl: string | null): boolean;
+/**
+ * Reads one payment entry into canonical terms, or refuses. Everything it
+ * cannot read exactly is refused.
+ */
+export declare function readTerms(x402Version: unknown, requirement: unknown, paymentRequired: unknown, request: PaymentRequestInfo | null, options: TermsOptions): TermsResult;
+/**
+ * Same request = same method, original URL and resource URL. On MCP the
+ * resource is named by the server, so the key is the called tool alone.
+ */
+export declare function requestKeyOf(terms: CanonicalTerms): string;

package/dist-dts/util.d.ts

@@ -0,0 +1,51 @@
+/** Refusal codes the guard uses. */
+export type RefusalCode = "MALFORMED_PAYMENT_REQUIRED" | "UNSUPPORTED_VERSION" | "UNSUPPORTED_SCHEME" | "UNSUPPORTED_NETWORK" | "NETWORK_NOT_ENABLED" | "UNSUPPORTED_ASSET" | "UNSUPPORTED_TRANSFER_METHOD" | "UNSUPPORTED_PAYMENT_FLOW" | "SPLITS_REFUSED" | "UNKNOWN_EXTRA_FIELD" | "DOMAIN_MISMATCH" | "INVALID_AMOUNT" | "INVALID_PAY_TO" | "INVALID_TIMEOUT" | "TIMEOUT_ABOVE_LIMIT" | "MISSING_RESOURCE" | "RESOURCE_HOST_MISMATCH" | "ORIGINAL_REQUEST_MISSING" | "V1_NOT_SUPPORTED_ON_MCP" | "ABOVE_MAX" | "PAY_TO_NOT_ALLOWED" | "BUDGET_EXCEEDED" | "STORE_UNAVAILABLE" | "GUARDIAN_UNREACHABLE" | "GUARDIAN_TIMEOUT" | "GUARDIAN_DENIED" | "APPROVAL_TIMEOUT" | "PERSON_APPROVAL_REQUIRED" | "EXECUTE_FAILED" | "RECEIPT_CHECK_FAILED" | "NO_PAYMENT_FLOW" | "NO_SIGNING_TOKEN" | "SIGNING_TOKEN_USED" | "SIGNING_TOKEN_EXPIRED" | "TERMS_CHANGED" | "TYPED_DATA_MISMATCH" | "SIGNING_REFUSED" | "GUARD_SEALED";
+/** Thrown (or used as the abort reason) whenever the guard refuses. */
+export declare class X402GuardRefused extends Error {
+    readonly code: RefusalCode;
+    /** Guardian's own reason code, when Guardian refused. */
+    readonly guardianReasonCode?: string;
+    /**
+     * EXECUTE_FAILED only: `execute` was sent but its outcome is unknown, so
+     * Guardian may have redeemed the decision. Nothing was signed. Look the
+     * request up by `requestId` before retrying; a retry needs a new decision.
+     */
+    readonly outcomeUnknown?: true;
+    /** The Guardian request this refusal is about, when there is one. */
+    readonly requestId?: string;
+    constructor(code: RefusalCode, detail: string, guardianReasonCode?: string, extra?: {
+        outcomeUnknown?: boolean;
+        requestId?: string;
+    });
+}
+export type Refusal = Readonly<{
+    ok: false;
+    code: RefusalCode;
+    detail: string;
+}>;
+export declare const refusal: (code: RefusalCode, detail: string) => Refusal;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Stable JSON for comparisons. Throws on anything that is not plain JSON
+ * data (functions, symbols, cycles, class instances); bigint is written as
+ * a tagged string so typed-data values compare exactly.
+ */
+export declare function canonical(value: unknown, depth?: number): string;
+export declare function sameData(a: unknown, b: unknown): boolean;
+export declare function deepFreeze<T>(value: T): T;
+/** A detached, frozen copy of plain JSON data. */
+export declare function frozenCopy<T>(value: T): T;
+export declare const ADDRESS_RE: RegExp;
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** A positive integer with no leading zero, at most 78 digits (uint256). */
+export declare const ATOMIC_RE: RegExp;
+export declare function formatAtomic(amount: string, decimals: number): string;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    timedOut: boolean;
+    error?: unknown;
+}>;
+export declare const sleep: (ms: number) => Promise<void>;

package/dist-dts/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The x402 releases this guard was built and tested against: 2.30.x, the
+ * same range as the peer dependencies (`~2.30.0`).
+ */
+export declare const TESTED_X402_MAJOR = 2;
+export declare const TESTED_X402_MINOR = 30;
+export declare const TESTED_X402_RANGE = "~2.30.0";
+/** True only for a plain release in the tested range (no prerelease). */
+export declare function isSupportedX402Version(version: string | null | undefined): boolean;
+/**
+ * Refuses an x402 package outside the tested range (another major or minor
+ * line, a prerelease, or none installed). Throws; the guard is not built.
+ */
+export declare function assertSupportedX402(name: string, readVersion?: (name: string) => string | null): string;

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "@odingard/guardian-x402",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Guardian for x402: Guardian decides x402 payments made through the guarded official x402 clients (ALLOW/ASK/DENY on the exact terms), before the wallet signs.",
+  "license": "Apache-2.0",
+  "author": "Odingard Security LLC",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist-dts/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fetch": {
+      "types": "./dist-dts/fetch.d.ts",
+      "default": "./dist/fetch.js"
+    },
+    "./axios": {
+      "types": "./dist-dts/axios.d.ts",
+      "default": "./dist/axios.js"
+    },
+    "./mcp": {
+      "types": "./dist-dts/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    }
+  },
+  "files": [
+    "dist",
+    "dist-dts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && esbuild src/index.ts src/fetch.ts src/axios.ts src/mcp.ts --bundle --splitting --platform=node --format=esm --target=node22 --external:@odingard/guardian-sdk --external:@x402/* --external:axios --external:@modelcontextprotocol/* --outdir=dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "@odingard/guardian-sdk": "^0.4.1 || ^0.5.0 || ^0.6.0",
+    "@x402/axios": "~2.30.0",
+    "@x402/core": "~2.30.0",
+    "@x402/evm": "~2.30.0",
+    "@x402/fetch": "~2.30.0",
+    "@x402/mcp": "~2.30.0"
+  },
+  "peerDependenciesMeta": {
+    "@x402/axios": {
+      "optional": true
+    },
+    "@x402/fetch": {
+      "optional": true
+    },
+    "@x402/mcp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@odingard/guardian-sdk": "^0.4.1 || ^0.5.0 || ^0.6.0",
+    "@types/node": "^22.20.5",
+    "@x402/axios": "2.30.0",
+    "@x402/core": "2.30.0",
+    "@x402/evm": "2.30.0",
+    "@x402/fetch": "2.30.0",
+    "@x402/mcp": "2.30.0",
+    "axios": "^1.21.1",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.3",
+    "viem": "^2.57.17",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "guardian",
+    "x402",
+    "payments",
+    "ai-agents",
+    "authorization",
+    "human-in-the-loop"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Odingard/guardian-sdk.git",
+    "directory": "packages/x402"
+  },
+  "homepage": "https://odingard.com/guardian"
+}