@odingard/guardian-x402 0.0.0-stage → 0.1.1

package/dist/chunk-C2QTXTL6.js

@@ -0,0 +1,1443 @@
+import {
+  assertSupportedX402,
+  flowStorage,
+  requestStorage
+} from "./chunk-DJIAG2IA.js";
+
+// src/constants.ts
+var PAY_TOOL = "x402.pay";
+var PAY_ABOVE_CAP_TOOL = "x402.pay.above_cap";
+var BASE_SEPOLIA = "eip155:84532";
+var BASE_MAINNET = "eip155:8453";
+var PINNED_ASSETS = Object.freeze([
+  Object.freeze({
+    network: BASE_SEPOLIA,
+    chainId: 84532,
+    networkName: "Base Sepolia",
+    asset: "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+    name: "USDC",
+    version: "2",
+    decimals: 6,
+    symbol: "USDC"
+  }),
+  Object.freeze({
+    network: BASE_MAINNET,
+    chainId: 8453,
+    networkName: "Base",
+    asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    name: "USD Coin",
+    version: "2",
+    decimals: 6,
+    symbol: "USDC"
+  })
+]);
+var V1_NETWORK_NAMES = Object.freeze({
+  "base-sepolia": BASE_SEPOLIA,
+  base: BASE_MAINNET
+});
+var EIP3009_TYPES = Object.freeze({
+  TransferWithAuthorization: Object.freeze([
+    Object.freeze({ name: "from", type: "address" }),
+    Object.freeze({ name: "to", type: "address" }),
+    Object.freeze({ name: "value", type: "uint256" }),
+    Object.freeze({ name: "validAfter", type: "uint256" }),
+    Object.freeze({ name: "validBefore", type: "uint256" }),
+    Object.freeze({ name: "nonce", type: "bytes32" })
+  ])
+});
+var DEFAULT_MAX_TIMEOUT_SECONDS_LIMIT = 300;
+var DEFAULT_SIGNING_WINDOW_MS = 3e4;
+var DEFAULT_CLAIM_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_GUARDIAN_CALL_TIMEOUT_MS = 15e3;
+var MAX_SIGNING_WINDOW_MS = 12e4;
+var MAX_CLAIM_POLL_INTERVAL_MS = 6e4;
+var MAX_GUARDIAN_CALL_TIMEOUT_MS = 6e4;
+var RECONCILE_MARGIN_MS = 3e5;
+function pinnedAsset(network, asset) {
+  const lower = asset.toLowerCase();
+  return PINNED_ASSETS.find((a) => a.network === network && a.asset === lower);
+}
+
+// src/util.ts
+var X402GuardRefused = class extends Error {
+  code;
+  /** Guardian's own reason code, when Guardian refused. */
+  guardianReasonCode;
+  /**
+   * 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.
+   */
+  outcomeUnknown;
+  /** The Guardian request this refusal is about, when there is one. */
+  requestId;
+  constructor(code, detail, guardianReasonCode, extra) {
+    super(
+      `[guardian-x402 ${code}${guardianReasonCode ? `:${guardianReasonCode}` : ""}] ${detail}`
+    );
+    this.name = "X402GuardRefused";
+    this.code = code;
+    if (guardianReasonCode !== void 0) {
+      this.guardianReasonCode = guardianReasonCode;
+    }
+    if (extra?.outcomeUnknown === true) this.outcomeUnknown = true;
+    if (extra?.requestId !== void 0) this.requestId = extra.requestId;
+  }
+};
+var refusal = (code, detail) => ({
+  ok: false,
+  code,
+  detail
+});
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function canonical(value, depth = 0) {
+  if (depth > 32) throw new TypeError("too deep");
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return JSON.stringify(value);
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError("non-finite number");
+      return JSON.stringify(value);
+    case "bigint":
+      return JSON.stringify(`bigint:${value.toString()}`);
+    case "object":
+      break;
+    default:
+      throw new TypeError(`cannot compare ${typeof value}`);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonical(v, depth + 1)).join(",")}]`;
+  }
+  if (!isPlainObject(value)) throw new TypeError("not a plain object");
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k], depth + 1)}`).join(",")}}`;
+}
+function sameData(a, b) {
+  try {
+    return canonical(a) === canonical(b);
+  } catch {
+    return false;
+  }
+}
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object") {
+    for (const key of Object.keys(value)) {
+      deepFreeze(value[key]);
+    }
+    Object.freeze(value);
+  }
+  return value;
+}
+function frozenCopy(value) {
+  return deepFreeze(JSON.parse(JSON.stringify(value)));
+}
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var ATOMIC_RE = /^[1-9][0-9]{0,77}$/;
+function formatAtomic(amount, decimals) {
+  const digits = amount.padStart(decimals + 1, "0");
+  const whole = digits.slice(0, digits.length - decimals);
+  const fraction = digits.slice(digits.length - decimals).replace(/0+$/, "");
+  return fraction ? `${whole}.${fraction}` : whole;
+}
+function withTimeout(promise, ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve({ ok: false, timedOut: true }), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve({ ok: true, value });
+      },
+      (error) => {
+        clearTimeout(timer);
+        resolve({ ok: false, timedOut: false, error });
+      }
+    );
+  });
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/ledger.ts
+var LEDGER_KEY = "guardian-x402:v1:ledger";
+var MAX_CAS_ATTEMPTS = 16;
+var KEEP_FINAL_MS = 40 * 24 * 3600 * 1e3;
+function processStore() {
+  const data = /* @__PURE__ */ new Map();
+  let counter = 0;
+  return {
+    async get(key) {
+      return data.get(key) ?? null;
+    },
+    async compareAndSet(key, expectedVersion, value) {
+      const current = data.get(key) ?? null;
+      if ((current?.version ?? null) !== expectedVersion) return false;
+      counter += 1;
+      data.set(key, { value, version: String(counter) });
+      return true;
+    }
+  };
+}
+function periodId(ms, period) {
+  const iso = new Date(ms).toISOString();
+  return period === "day" ? iso.slice(0, 10) : iso.slice(0, 7);
+}
+var counts = (e) => e.state !== "released";
+function isLive(e, nowMs) {
+  if (e.state === "released") return false;
+  if (e.state === "reserved") return true;
+  return e.validBefore === void 0 || e.validBefore * 1e3 > nowMs;
+}
+var Ledger = class {
+  constructor(store, budgets) {
+    this.store = store;
+    this.budgets = budgets;
+  }
+  store;
+  budgets;
+  async read() {
+    let current;
+    try {
+      current = await this.store.get(LEDGER_KEY);
+    } catch {
+      throw new X402GuardRefused(
+        "STORE_UNAVAILABLE",
+        "The guard's store cannot be read."
+      );
+    }
+    if (current === null) return { doc: { entries: [] }, version: null };
+    try {
+      const doc = JSON.parse(current.value);
+      if (!doc || !Array.isArray(doc.entries)) throw new Error("bad");
+      return { doc, version: current.version };
+    } catch {
+      throw new X402GuardRefused(
+        "STORE_UNAVAILABLE",
+        "The guard's store holds data it cannot read."
+      );
+    }
+  }
+  /** Read-modify-write with compare-and-set; `change` may throw to abort. */
+  async update(change) {
+    for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt += 1) {
+      const { doc, version } = await this.read();
+      const result = change(doc);
+      let written;
+      try {
+        written = await this.store.compareAndSet(
+          LEDGER_KEY,
+          version,
+          JSON.stringify(doc)
+        );
+      } catch {
+        throw new X402GuardRefused(
+          "STORE_UNAVAILABLE",
+          "The guard's store cannot be written."
+        );
+      }
+      if (written) return result;
+    }
+    throw new X402GuardRefused(
+      "STORE_UNAVAILABLE",
+      "The guard's store kept changing; nothing was reserved."
+    );
+  }
+  async entries() {
+    return (await this.read()).doc.entries;
+  }
+  /**
+   * 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`.
+   */
+  async reserve(entry, nowMs, sameRequestIds = []) {
+    return this.update((doc) => {
+      doc.entries = doc.entries.filter(
+        (e) => !(nowMs - e.createdAtMs > KEEP_FINAL_MS && !isLive(e, nowMs))
+      );
+      for (const budget of this.budgets) {
+        if (budget.network !== entry.network || budget.asset.toLowerCase() !== entry.asset) {
+          continue;
+        }
+        const pid = periodId(entry.createdAtMs, budget.period);
+        let used = 0n;
+        for (const e of doc.entries) {
+          if (counts(e) && e.network === entry.network && e.asset === entry.asset && periodId(e.createdAtMs, budget.period) === pid) {
+            used += BigInt(e.amount);
+          }
+        }
+        if (used + BigInt(entry.amount) > BigInt(budget.limit)) {
+          throw new X402GuardRefused(
+            "BUDGET_EXCEEDED",
+            `This payment would exceed the local ${budget.period} budget for this asset.`
+          );
+        }
+      }
+      const liveForRequest = doc.entries.filter(
+        (e) => (e.requestKey === entry.requestKey || sameRequestIds.includes(e.id)) && isLive(e, nowMs)
+      );
+      doc.entries.push(entry);
+      return { liveForRequest };
+    });
+  }
+  async patch(id, change) {
+    return this.update((doc) => {
+      const entry = doc.entries.find((e) => e.id === id);
+      if (entry) change(entry);
+      return entry ? { ...entry } : void 0;
+    });
+  }
+  async patchByNonce(nonce, change) {
+    const lower = nonce.toLowerCase();
+    return this.update((doc) => {
+      const entry = doc.entries.find((e) => e.nonce === lower);
+      if (entry) change(entry);
+      return entry ? { ...entry } : void 0;
+    });
+  }
+  /** Release an entry only if no signature was made for it. */
+  async releaseUnsigned(id) {
+    await this.patch(id, (e) => {
+      if (e.state === "reserved") e.state = "released";
+    });
+  }
+};
+
+// src/terms.ts
+var KNOWN_EXTRA = /* @__PURE__ */ new Set([
+  "name",
+  "version",
+  "assetTransferMethod",
+  "paymentFlow"
+]);
+function hostOf(url) {
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+function mcpResourceMatches(resourceUrl, toolName, serverUrl) {
+  if (resourceUrl === `mcp://tool/${toolName}`) return true;
+  if (serverUrl === null) return false;
+  let server;
+  let resource;
+  try {
+    server = new URL(serverUrl);
+    resource = new URL(resourceUrl);
+  } catch {
+    return false;
+  }
+  if (server.protocol !== "https:" && server.protocol !== "http:") return false;
+  const expected = new URL(`/tools/${encodeURIComponent(toolName)}`, server.origin);
+  return resource.href === expected.href;
+}
+function readTerms(x402Version, requirement, paymentRequired, request, options) {
+  if (x402Version !== 1 && x402Version !== 2) {
+    return refusal(
+      "UNSUPPORTED_VERSION",
+      `x402Version ${String(x402Version)} is not supported (only 1 and 2).`
+    );
+  }
+  if (!isPlainObject(requirement)) {
+    return refusal(
+      "MALFORMED_PAYMENT_REQUIRED",
+      "A payment entry is not an object."
+    );
+  }
+  const r = requirement;
+  if (r.scheme !== "exact") {
+    return refusal(
+      "UNSUPPORTED_SCHEME",
+      `Scheme ${JSON.stringify(r.scheme)} is not supported (only "exact").`
+    );
+  }
+  let network;
+  if (typeof r.network === "string") {
+    if (x402Version === 2) {
+      if (r.network === BASE_SEPOLIA || r.network === BASE_MAINNET) {
+        network = r.network;
+      }
+    } else if (Object.hasOwn(V1_NETWORK_NAMES, r.network)) {
+      network = V1_NETWORK_NAMES[r.network];
+    }
+  }
+  if (network === void 0) {
+    return refusal(
+      "UNSUPPORTED_NETWORK",
+      `Network ${JSON.stringify(r.network)} is not supported.`
+    );
+  }
+  if (!options.enabledNetworks.includes(network)) {
+    return refusal(
+      "NETWORK_NOT_ENABLED",
+      `Network ${network} is not enabled in this guard.`
+    );
+  }
+  if (typeof r.asset !== "string" || !ADDRESS_RE.test(r.asset)) {
+    return refusal("UNSUPPORTED_ASSET", "The asset is not an address.");
+  }
+  const pinned = pinnedAsset(network, r.asset);
+  if (!pinned) {
+    return refusal(
+      "UNSUPPORTED_ASSET",
+      `Asset ${r.asset} is not a supported asset on ${network}.`
+    );
+  }
+  const rawAmount = x402Version === 1 ? r.maxAmountRequired : r.amount;
+  if (typeof rawAmount !== "string" || !ATOMIC_RE.test(rawAmount)) {
+    return refusal(
+      "INVALID_AMOUNT",
+      "The amount is not a positive integer string in atomic units."
+    );
+  }
+  if (x402Version === 1 && r.amount !== void 0 && r.amount !== rawAmount) {
+    return refusal(
+      "INVALID_AMOUNT",
+      "The v1 entry names two different amounts."
+    );
+  }
+  if (typeof r.payTo !== "string" || !ADDRESS_RE.test(r.payTo) || r.payTo.toLowerCase() === ZERO_ADDRESS) {
+    return refusal("INVALID_PAY_TO", "payTo is not a plain address.");
+  }
+  const timeout = r.maxTimeoutSeconds;
+  if (typeof timeout !== "number" || !Number.isSafeInteger(timeout) || timeout <= 0) {
+    return refusal(
+      "INVALID_TIMEOUT",
+      "maxTimeoutSeconds is not a positive whole number."
+    );
+  }
+  if (timeout > options.maxTimeoutSecondsLimit) {
+    return refusal(
+      "TIMEOUT_ABOVE_LIMIT",
+      `maxTimeoutSeconds ${timeout} is above the limit of ${options.maxTimeoutSecondsLimit}.`
+    );
+  }
+  if (!isPlainObject(r.extra)) {
+    return refusal("DOMAIN_MISMATCH", "extra.name and extra.version are missing.");
+  }
+  const extra = r.extra;
+  if (Object.hasOwn(extra, "splits")) {
+    return refusal("SPLITS_REFUSED", "extra.splits is not supported.");
+  }
+  if (extra.assetTransferMethod !== void 0 && extra.assetTransferMethod !== "eip3009") {
+    return refusal(
+      "UNSUPPORTED_TRANSFER_METHOD",
+      `Transfer method ${JSON.stringify(extra.assetTransferMethod)} is not supported (only eip3009).`
+    );
+  }
+  if (extra.paymentFlow !== void 0 && extra.paymentFlow !== "authorization") {
+    return refusal(
+      "UNSUPPORTED_PAYMENT_FLOW",
+      `Payment flow ${JSON.stringify(extra.paymentFlow)} is not supported (only authorization).`
+    );
+  }
+  const unknownExtra = Object.keys(extra).filter((k) => !KNOWN_EXTRA.has(k));
+  if (unknownExtra.length > 0) {
+    return refusal(
+      "UNKNOWN_EXTRA_FIELD",
+      `extra has fields the guard cannot read: ${unknownExtra.join(", ")}.`
+    );
+  }
+  if (extra.name !== pinned.name || extra.version !== pinned.version) {
+    return refusal(
+      "DOMAIN_MISMATCH",
+      `extra.name/version do not match the pinned ${pinned.symbol} on ${pinned.networkName}.`
+    );
+  }
+  let resourceUrl;
+  if (x402Version === 2) {
+    const pr = paymentRequired;
+    resourceUrl = isPlainObject(pr?.resource) ? pr.resource.url : void 0;
+  } else {
+    resourceUrl = r.resource;
+  }
+  if (typeof resourceUrl !== "string" || hostOf(resourceUrl) === null) {
+    return refusal("MISSING_RESOURCE", "The resource URL is missing or invalid.");
+  }
+  if (request === null) {
+    return refusal(
+      "ORIGINAL_REQUEST_MISSING",
+      "The guard did not see the original request for this payment."
+    );
+  }
+  if (request.transport === "mcp") {
+    if (x402Version !== 2) {
+      return refusal(
+        "V1_NOT_SUPPORTED_ON_MCP",
+        "Only x402 v2 is supported on MCP."
+      );
+    }
+    if (!mcpResourceMatches(resourceUrl, request.toolName, request.serverUrl)) {
+      return refusal(
+        "RESOURCE_HOST_MISMATCH",
+        `The resource ${resourceUrl} is not the called tool ${request.toolName} (expected mcp://tool/${request.toolName}${request.serverUrl === null ? "" : " or <serverUrl origin>/tools/" + request.toolName}).`
+      );
+    }
+  } else {
+    const originalHost = hostOf(request.originalUrl);
+    if (originalHost === null) {
+      return refusal(
+        "ORIGINAL_REQUEST_MISSING",
+        "The original request URL cannot be read."
+      );
+    }
+    if (hostOf(resourceUrl) !== originalHost) {
+      return refusal(
+        "RESOURCE_HOST_MISMATCH",
+        `The resource host does not match the host the agent asked (${originalHost}).`
+      );
+    }
+  }
+  const terms = {
+    schema: "odingard.guardian.x402.pay.v1",
+    x402Version,
+    scheme: "exact",
+    network,
+    networkName: pinned.networkName,
+    asset: pinned.asset,
+    assetSymbol: pinned.symbol,
+    amount: rawAmount,
+    amountDisplay: `${formatAtomic(rawAmount, pinned.decimals)} ${pinned.symbol}`,
+    payTo: r.payTo.toLowerCase(),
+    maxTimeoutSeconds: timeout,
+    extra: {
+      name: pinned.name,
+      version: pinned.version,
+      assetTransferMethod: "eip3009",
+      paymentFlow: "authorization"
+    },
+    resourceUrl,
+    request: {
+      transport: request.transport,
+      method: request.method,
+      originalUrl: request.originalUrl,
+      finalUrl: request.finalUrl
+    }
+  };
+  return { ok: true, terms, pinned };
+}
+function requestKeyOf(terms) {
+  if (terms.request.transport === "mcp") {
+    return JSON.stringify(["mcp", terms.request.method, terms.request.originalUrl]);
+  }
+  return JSON.stringify([
+    terms.request.transport,
+    terms.request.method.toUpperCase(),
+    terms.request.originalUrl,
+    terms.resourceUrl
+  ]);
+}
+
+// src/guard.ts
+import { randomBytes } from "node:crypto";
+import {
+  classifyRequestResult,
+  verifyReceiptOffline,
+  GUARDIAN_DEFAULT_REQUEST_TTL_MS,
+  GUARDIAN_MAX_REQUEST_TTL_MS
+} from "@odingard/guardian-sdk";
+import {
+  x402Client,
+  x402HTTPClient
+} from "@x402/core/client";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+var newId = (prefix) => `${prefix}_${randomBytes(12).toString("hex")}`;
+function refused(code, detail, guardianReasonCode, extra) {
+  return new X402GuardRefused(code, detail, guardianReasonCode, extra);
+}
+var CLAIM_STILL_HELD = /* @__PURE__ */ new Set([
+  "APPROVAL_PENDING",
+  "APPROVAL_REQUIRED",
+  "SERVICE_UNAVAILABLE",
+  "RATE_LIMITED",
+  "DB_BUSY",
+  "HTTP_429"
+]);
+function claimStillHeld(reasonCode) {
+  return CLAIM_STILL_HELD.has(reasonCode) || /^HTTP_5\d\d$/.test(reasonCode);
+}
+var OUTCOME_UNKNOWN_DETAIL = (requestId) => `Guardian may have redeemed this decision (execute outcome unknown); nothing was signed. Look up request ${requestId} before retrying; a retry needs a new decision.`;
+function toBig(value) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "string" && /^\d{1,78}$/.test(value)) return BigInt(value);
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    return BigInt(value);
+  }
+  return null;
+}
+var hasExactKeys = (obj, keys) => {
+  const own = Reflect.ownKeys(obj);
+  return own.length === keys.length && keys.every((k) => own.includes(k));
+};
+function mismatch(field) {
+  return refused(
+    "TYPED_DATA_MISMATCH",
+    `The data to sign does not match the approved terms (${field}).`
+  );
+}
+var X402Guard = class {
+  client;
+  config;
+  ledger;
+  durable;
+  startedAtMs;
+  now;
+  termsOptions;
+  requestTtlMs;
+  signingWindowMs;
+  pollMs;
+  callTimeoutMs;
+  walletAddress;
+  wallet;
+  log = [];
+  /** PaymentRequired object → the request it answered (set by the HTTP hook). */
+  pending = /* @__PURE__ */ new WeakMap();
+  constructor(config) {
+    assertSupportedX402("@x402/core");
+    assertSupportedX402("@x402/evm");
+    this.config = config;
+    this.now = config.now ?? Date.now;
+    if (!config.guardian || typeof config.guardian.request !== "function") {
+      throw new Error("guardian-x402: `guardian` must be a Guardian client.");
+    }
+    if (typeof config.connectionId !== "string" || !config.connectionId) {
+      throw new Error("guardian-x402: `connectionId` is required.");
+    }
+    const signer = config.signer;
+    if (!signer || typeof signer.address !== "string" || !ADDRESS_RE.test(signer.address) || typeof signer.signTypedData !== "function") {
+      throw new Error(
+        "guardian-x402: `signer` must have an address and signTypedData."
+      );
+    }
+    this.wallet = signer;
+    this.walletAddress = signer.address.toLowerCase();
+    this.guardedSigner = Object.freeze({
+      address: signer.address,
+      signTypedData: (message) => this.signGuarded(message),
+      signTransaction: async () => {
+        throw refused("SIGNING_REFUSED", "The guard does not sign transactions.");
+      }
+    });
+    const enabled = config.enabledNetworks ?? [BASE_SEPOLIA];
+    for (const n of enabled) {
+      if (n !== BASE_SEPOLIA && n !== BASE_MAINNET) {
+        throw new Error(`guardian-x402: network ${String(n)} is not supported.`);
+      }
+    }
+    const limit = config.maxTimeoutSecondsLimit ?? DEFAULT_MAX_TIMEOUT_SECONDS_LIMIT;
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+      throw new Error("guardian-x402: maxTimeoutSecondsLimit must be a positive whole number.");
+    }
+    this.termsOptions = Object.freeze({
+      enabledNetworks: Object.freeze([...enabled]),
+      maxTimeoutSecondsLimit: limit
+    });
+    this.requestTtlMs = config.requestTtlMs ?? GUARDIAN_DEFAULT_REQUEST_TTL_MS;
+    if (!Number.isSafeInteger(this.requestTtlMs) || this.requestTtlMs < 1 || this.requestTtlMs > GUARDIAN_MAX_REQUEST_TTL_MS) {
+      throw new Error(
+        `guardian-x402: requestTtlMs must be from 1 to ${GUARDIAN_MAX_REQUEST_TTL_MS}.`
+      );
+    }
+    this.signingWindowMs = boundedMs(
+      "signingWindowMs",
+      config.signingWindowMs ?? DEFAULT_SIGNING_WINDOW_MS,
+      MAX_SIGNING_WINDOW_MS
+    );
+    this.pollMs = boundedMs(
+      "claimPollIntervalMs",
+      config.claimPollIntervalMs ?? DEFAULT_CLAIM_POLL_INTERVAL_MS,
+      MAX_CLAIM_POLL_INTERVAL_MS
+    );
+    this.callTimeoutMs = boundedMs(
+      "guardianCallTimeoutMs",
+      config.guardianCallTimeoutMs ?? DEFAULT_GUARDIAN_CALL_TIMEOUT_MS,
+      MAX_GUARDIAN_CALL_TIMEOUT_MS
+    );
+    for (const l of config.limits ?? []) {
+      if (!pinnedAsset(l.network, l.asset)) {
+        throw new Error(`guardian-x402: limit for an unsupported asset ${l.asset} on ${l.network}.`);
+      }
+      if (!ATOMIC_RE.test(l.askAbove) && l.askAbove !== "0") {
+        throw new Error("guardian-x402: askAbove must be an atomic integer string.");
+      }
+      if (!ATOMIC_RE.test(l.max)) {
+        throw new Error("guardian-x402: max must be a positive atomic integer string.");
+      }
+      for (const p of l.payTo ?? []) {
+        if (!ADDRESS_RE.test(p)) throw new Error(`guardian-x402: payTo ${p} is not an address.`);
+      }
+    }
+    const budgets = config.budgets ?? [];
+    if (budgets.length > 0 && !config.store) {
+      throw new Error("guardian-x402: budgets need a durable `store`.");
+    }
+    for (const b of budgets) {
+      if (!pinnedAsset(b.network, b.asset) || !ATOMIC_RE.test(b.limit)) {
+        throw new Error("guardian-x402: each budget needs a pinned asset and an atomic limit.");
+      }
+      if (b.period !== "day" && b.period !== "month") {
+        throw new Error("guardian-x402: budget period must be day or month.");
+      }
+    }
+    if (config.spendControls === false) {
+      throw new Error("guardian-x402: x402 spendControls cannot be turned off.");
+    }
+    this.durable = config.store !== void 0;
+    this.ledger = new Ledger(config.store ?? processStore(), budgets);
+    this.startedAtMs = this.now();
+    this.client = new GuardedX402Client(this, config);
+  }
+  // ---------------------------------------------------------------- records
+  /** Local records (newest last). No keys, signatures or payment payloads. */
+  records() {
+    return [...this.log];
+  }
+  /** @internal */
+  record(r) {
+    const full = Object.freeze({ at: this.now(), ...r });
+    this.log.push(full);
+    try {
+      this.config.onRecord?.(full);
+    } catch {
+    }
+  }
+  /** Authorizations the guard signed that may still be settled. */
+  async liveAuthorizations() {
+    const now = this.now();
+    return (await this.ledger.entries()).filter(
+      (e) => (e.state === "signed" || e.state === "signing" || e.state === "spent") && isLive(e, now)
+    );
+  }
+  /**
+   * Releases budget held by authorizations whose `validBefore` has passed
+   * and whose nonce the chain shows unused. Needs `authorizationState`.
+   */
+  async reconcile() {
+    const reader = this.config.authorizationState;
+    let released = 0;
+    let spent = 0;
+    const now = this.now();
+    for (const e of await this.ledger.entries()) {
+      const holdUntil = e.holdUntilMs ?? e.createdAtMs + LONGEST_FLOW_MS;
+      if (e.state === "reserved" && now > holdUntil) {
+        await this.ledger.releaseUnsigned(e.id);
+        released += 1;
+        continue;
+      }
+      if (!reader || e.state !== "signed" && e.state !== "signing" || e.validBefore === void 0 || now <= e.validBefore * 1e3 + RECONCILE_MARGIN_MS || !e.nonce || !e.from) {
+        continue;
+      }
+      let used;
+      try {
+        used = await reader({ network: e.network, asset: e.asset, from: e.from, nonce: e.nonce });
+      } catch {
+        continue;
+      }
+      if (used === false) {
+        await this.ledger.patch(e.id, (x) => {
+          if (x.state === "signed" || x.state === "signing") x.state = "released";
+        });
+        this.record({ event: "released", nonce: e.nonce, network: e.network });
+        released += 1;
+      } else if (used === true) {
+        await this.ledger.patch(e.id, (x) => {
+          if (x.state === "signed" || x.state === "signing") x.state = "spent";
+        });
+        this.record({ event: "spent", nonce: e.nonce, network: e.network });
+        spent += 1;
+      }
+    }
+    return { released, spent };
+  }
+  // ------------------------------------------------------- transport glue
+  /**
+   * An x402 HTTP client for this guard. Its only `onPaymentRequired` hook
+   * records which request the 402 answered; it never returns headers.
+   */
+  httpClient() {
+    const http = new x402HTTPClient(this.client);
+    http.onPaymentRequired(async ({ paymentRequired, requestUrl }) => {
+      const ctx = requestStorage.getStore();
+      if (ctx && ctx.info.transport === "http" && paymentRequired && typeof paymentRequired === "object") {
+        this.pending.set(paymentRequired, {
+          ctx,
+          info: { ...ctx.info, finalUrl: typeof requestUrl === "string" ? requestUrl : null }
+        });
+      }
+      return void 0;
+    });
+    return http;
+  }
+  /** @internal */
+  requestInfoFor(paymentRequired) {
+    const ctx = requestStorage.getStore() ?? null;
+    if (ctx?.info.transport === "mcp") return { info: ctx.info, ctx };
+    const found = this.pending.get(paymentRequired);
+    if (found && found.ctx === ctx) return { info: found.info, ctx };
+    return { info: null, ctx };
+  }
+  /** @internal Fetch: "Payment already attempted" after the payload was signed. */
+  async markSignedNotSent(ctx) {
+    const id = ctx.signedEntries.at(-1);
+    if (!id) return;
+    const entry = await this.ledger.patch(id, (e) => {
+      e.sent = "not-sent";
+    }).catch(() => void 0);
+    this.record({
+      event: "signed-not-sent",
+      ...entry?.nonce ? { nonce: entry.nonce } : {},
+      ...entry?.requestId ? { requestId: entry.requestId } : {},
+      detail: "Signed, not sent: x402 stopped before sending. The authorization stays live until validBefore."
+    });
+  }
+  /** @internal v1 settlement, read by the transport wrapper. */
+  async recordV1Settlement(ctx, settle) {
+    const id = [...ctx.signedEntries].reverse().find((e) => ctx.versions.get(e) === 1);
+    if (!id || !settle) return;
+    const entry = await this.ledger.patch(id, (e) => {
+      if (settle.success === true && (e.state === "signed" || e.state === "signing")) {
+        e.state = "spent";
+      }
+    }).catch(() => void 0);
+    this.recordSettlement(entry, settle);
+  }
+  recordSettlement(entry, settle) {
+    this.record({
+      event: "settlement",
+      ...entry?.requestId ? { requestId: entry.requestId } : {},
+      ...entry?.nonce ? { nonce: entry.nonce } : {},
+      success: settle.success === true,
+      ...typeof settle.transaction === "string" ? { transaction: settle.transaction } : {},
+      ...typeof settle.network === "string" ? { network: settle.network } : {},
+      ...typeof settle.errorReason === "string" ? { errorReason: settle.errorReason } : {}
+    });
+  }
+  // --------------------------------------------------------- core hooks
+  /** @internal Drops entries the guard cannot pay before x402 selects one. */
+  policy = (x402Version, requirements) => {
+    const flow = flowStorage.getStore();
+    if (!flow) return [];
+    return requirements.filter((r) => {
+      const read = readTerms(x402Version, r, flow.paymentRequired, flow.request, this.termsOptions);
+      if (!read.ok) flow.dropped.push({ code: read.code, detail: read.detail });
+      return read.ok;
+    });
+  };
+  /** @internal Pre-check before x402 runs: refuse what nothing can pay. */
+  precheck(paymentRequired, request) {
+    if (!isPlainObject(paymentRequired)) {
+      throw refused("MALFORMED_PAYMENT_REQUIRED", "The payment terms are not an object.");
+    }
+    const version = paymentRequired.x402Version;
+    if (version !== 1 && version !== 2) {
+      throw refused("UNSUPPORTED_VERSION", `x402Version ${String(version)} is not supported.`);
+    }
+    const accepts = paymentRequired.accepts;
+    if (!Array.isArray(accepts) || accepts.length === 0) {
+      throw refused("MALFORMED_PAYMENT_REQUIRED", "The payment terms list no payment options.");
+    }
+    let first = null;
+    for (const r of accepts) {
+      const read = readTerms(version, r, paymentRequired, request, this.termsOptions);
+      if (read.ok) return;
+      first ??= { code: read.code, detail: read.detail };
+    }
+    throw refused(first.code, first.detail);
+  }
+  /** @internal The decision point: x402's onBeforePaymentCreation. */
+  beforePaymentCreation = async (ctx) => {
+    const flow = flowStorage.getStore();
+    try {
+      if (!flow || flow.paymentRequired !== ctx.paymentRequired) {
+        throw refused("NO_PAYMENT_FLOW", "This payment did not start through the guard.");
+      }
+      if (flow.decided) {
+        throw refused("NO_PAYMENT_FLOW", "This payment was already decided.");
+      }
+      flow.decided = true;
+      flow.selectedRequirements = ctx.selectedRequirements;
+      await this.decide(flow, ctx);
+      return void 0;
+    } catch (error) {
+      const err = error instanceof X402GuardRefused ? error : refused("SIGNING_REFUSED", "The guard failed while deciding; nothing was signed.");
+      if (flow) {
+        flow.refusal = err;
+        if (flow.ledgerId) await this.ledger.releaseUnsigned(flow.ledgerId).catch(() => void 0);
+      }
+      this.recordRefusal(err, flow?.id);
+      return { abort: true, reason: err.message };
+    }
+  };
+  limitFor(terms) {
+    return (this.config.limits ?? []).find(
+      (l) => l.network === terms.network && l.asset.toLowerCase() === terms.asset
+    );
+  }
+  async decide(flow, ctx) {
+    const read = readTerms(
+      ctx.paymentRequired.x402Version,
+      ctx.selectedRequirements,
+      ctx.paymentRequired,
+      flow.request,
+      this.termsOptions
+    );
+    if (!read.ok) throw refused(read.code, read.detail);
+    const terms = frozenCopy(read.terms);
+    let snapshot;
+    try {
+      snapshot = frozenCopy(ctx.selectedRequirements);
+    } catch {
+      throw refused("MALFORMED_PAYMENT_REQUIRED", "The selected entry cannot be copied.");
+    }
+    const amount = BigInt(terms.amount);
+    const limit = this.limitFor(terms);
+    if (limit && amount > BigInt(limit.max)) {
+      throw refused("ABOVE_MAX", `${terms.amountDisplay} is above the local max for this asset.`);
+    }
+    if (limit?.payTo && !limit.payTo.some((p) => p.toLowerCase() === terms.payTo)) {
+      throw refused("PAY_TO_NOT_ALLOWED", `payTo ${terms.payTo} is not on the allowlist.`);
+    }
+    const reasons = [];
+    if (!limit) reasons.push("NO_CAP_FOR_ASSET");
+    else if (amount > BigInt(limit.askAbove)) reasons.push("ABOVE_ASK_ABOVE");
+    const now = this.now();
+    if (!this.durable && now < this.startedAtMs + this.termsOptions.maxTimeoutSecondsLimit * 1e3) {
+      reasons.push("RECENT_START_WITHOUT_STORE");
+    }
+    const entry = {
+      id: newId("x4e"),
+      requestKey: requestKeyOf(terms),
+      network: terms.network,
+      asset: terms.asset,
+      amount: terms.amount,
+      createdAtMs: now,
+      holdUntilMs: now + this.longestFlowMs(),
+      state: "reserved",
+      sent: "unknown"
+    };
+    const { liveForRequest } = await this.ledger.reserve(
+      entry,
+      now,
+      flow.requestContext?.signedEntries ?? []
+    );
+    flow.ledgerId = entry.id;
+    if (liveForRequest.length > 0) {
+      reasons.push("LIVE_AUTHORIZATION_FOR_REQUEST");
+      const exposure = liveForRequest.reduce((s, e) => s + BigInt(e.amount), amount);
+      if (limit && exposure > BigInt(limit.max)) {
+        throw refused(
+          "ABOVE_MAX",
+          "This payment plus live authorizations for the same request is above the local max."
+        );
+      }
+    }
+    const aboveCap = reasons.length > 0;
+    const tool = aboveCap ? PAY_ABOVE_CAP_TOOL : PAY_TOOL;
+    const args = { ...terms, reviewReasons: [...reasons] };
+    const { requestId, capabilityToken, viaAsk } = await this.askGuardian(
+      tool,
+      args,
+      terms,
+      aboveCap
+    );
+    const executed = await withTimeout(
+      Promise.resolve().then(
+        () => this.config.guardian.execute({ requestId, capabilityToken })
+      ),
+      this.callTimeoutMs
+    );
+    if (!executed.ok) {
+      flow.executeOutcomeUnknown = { requestId };
+      throw refused(
+        "EXECUTE_FAILED",
+        `${executed.timedOut ? "Guardian did not answer execute in time." : "Guardian execute failed."} ${OUTCOME_UNKNOWN_DETAIL(requestId)}`,
+        void 0,
+        { outcomeUnknown: true, requestId }
+      );
+    }
+    const ex = executed.value;
+    const exOk = isPlainObject(ex) && ex.ok === true && isPlainObject(ex.receipt) && ex.receipt.status === "sent-verified" && ex.receipt.requestId === requestId && typeof ex.receipt.receiptReference === "string";
+    if (!exOk) {
+      const code = isPlainObject(ex) && typeof ex.reasonCode === "string" ? ex.reasonCode : "EXECUTE_FAILED";
+      const definitiveRefusal = isPlainObject(ex) && ex.ok === false && ex.outcomeUnknown !== true;
+      if (!definitiveRefusal) {
+        flow.executeOutcomeUnknown = { requestId };
+        throw refused(
+          "EXECUTE_FAILED",
+          `Guardian did not redeem the decision cleanly. ${OUTCOME_UNKNOWN_DETAIL(requestId)}`,
+          code,
+          { outcomeUnknown: true, requestId }
+        );
+      }
+      throw refused("EXECUTE_FAILED", "Guardian did not redeem the decision.", code, {
+        requestId
+      });
+    }
+    const receiptReference = ex.receipt.receiptReference;
+    flow.redeemed = { requestId, receiptReference };
+    await this.ledger.patch(entry.id, (e) => {
+      e.requestId = requestId;
+    }).catch(() => void 0);
+    let approvedByPerson = false;
+    if (aboveCap) {
+      if (!viaAsk) {
+        throw refused(
+          "PERSON_APPROVAL_REQUIRED",
+          "This payment needs a person's approval; a rule ALLOW is not enough."
+        );
+      }
+      await this.checkApprovedByPerson(requestId, tool, args);
+      approvedByPerson = true;
+    }
+    const token = {
+      terms,
+      pinned: read.pinned,
+      requirementSnapshot: snapshot,
+      requestId,
+      receiptReference,
+      expiresAtMs: this.now() + this.signingWindowMs,
+      used: false
+    };
+    flow.token = token;
+    this.record({
+      event: "redeemed",
+      flowId: flow.id,
+      tool,
+      requestId,
+      receiptReference,
+      terms,
+      reviewReasons: [...reasons],
+      approvedByPerson
+    });
+  }
+  /** The longest a flow can hold a reservation before it signs. */
+  longestFlowMs() {
+    return 4 * this.callTimeoutMs + this.requestTtlMs + this.pollMs + this.signingWindowMs + 6e4;
+  }
+  async guardianCall(fn) {
+    const r = await withTimeout(Promise.resolve().then(fn), this.callTimeoutMs);
+    if (!r.ok) {
+      throw r.timedOut ? refused("GUARDIAN_TIMEOUT", "Guardian did not answer in time.") : refused("GUARDIAN_UNREACHABLE", "Guardian could not be reached.");
+    }
+    return r.value;
+  }
+  async askGuardian(tool, args, terms, aboveCap) {
+    const purpose = `Pay ${terms.amountDisplay} on ${terms.networkName} over x402${aboveCap ? " (needs a person's approval)" : ""}`;
+    const answer = await this.guardianCall(
+      () => this.config.guardian.request({
+        action: "tool.invoke",
+        connectionId: this.config.connectionId,
+        toolName: tool,
+        arguments: args,
+        purpose,
+        ttlMs: this.requestTtlMs
+      })
+    );
+    const startedAt = this.now();
+    if (!wellFormed(answer)) {
+      throw refused("GUARDIAN_UNREACHABLE", "Guardian's answer was malformed.");
+    }
+    const decision = classifyRequestResult(answer);
+    if (decision.decision === "DENY") {
+      if (decision.reasonCode === "SERVICE_UNAVAILABLE") {
+        throw refused("GUARDIAN_UNREACHABLE", "Guardian could not be reached.");
+      }
+      throw refused("GUARDIAN_DENIED", "Guardian denied this payment.", decision.reasonCode);
+    }
+    if (decision.decision === "ALLOW") {
+      if (aboveCap) {
+        throw refused(
+          "PERSON_APPROVAL_REQUIRED",
+          "This payment needs a person's approval; a rule ALLOW is not enough."
+        );
+      }
+      return {
+        requestId: decision.requestId,
+        capabilityToken: decision.capabilityToken,
+        viaAsk: false
+      };
+    }
+    const requestId = decision.requestId;
+    const deadline = startedAt + this.requestTtlMs;
+    while (this.now() < deadline) {
+      await sleep(Math.max(1, Math.min(this.pollMs, deadline - this.now())));
+      let claimed;
+      try {
+        claimed = await this.guardianCall(() => this.config.guardian.claim(requestId));
+      } catch {
+        continue;
+      }
+      if (!wellFormed(claimed)) {
+        throw refused("GUARDIAN_UNREACHABLE", "Guardian's answer was malformed.");
+      }
+      if (claimed.ok && claimed.requestId !== requestId) {
+        throw refused("GUARDIAN_UNREACHABLE", "Guardian answered for a different request.");
+      }
+      if (claimed.ok && claimed.decision === "ALLOW") {
+        if (typeof claimed.capabilityToken !== "string" || !claimed.capabilityToken) {
+          throw refused("GUARDIAN_DENIED", "Guardian issued no capability.", "CAPABILITY_MISSING");
+        }
+        return { requestId, capabilityToken: claimed.capabilityToken, viaAsk: true };
+      }
+      const held = claimed.ok && claimed.decision === "ASK" || !claimed.ok && claimStillHeld(claimed.reasonCode);
+      if (held) continue;
+      throw refused(
+        "GUARDIAN_DENIED",
+        "Guardian denied this payment.",
+        claimed.ok ? claimed.reasonCode ?? "DENIED" : claimed.reasonCode
+      );
+    }
+    throw refused("APPROVAL_TIMEOUT", "No person approved this payment in time.");
+  }
+  /** The receipt must show a person approved this exact request. */
+  async checkApprovedByPerson(requestId, tool, args) {
+    const fail = (why) => refused("RECEIPT_CHECK_FAILED", `Cannot confirm a person approved this payment (${why}).`);
+    const got = await this.guardianCall(() => this.config.guardian.portableReceipt(requestId));
+    if (!isPlainObject(got) || got.ok !== true) throw fail("no receipt");
+    const receipt = got.receipt;
+    if (this.config.receiptVerificationKeys !== void 0) {
+      const verified = verifyReceiptOffline(receipt, this.config.receiptVerificationKeys);
+      if (!verified.valid) throw fail("receipt does not verify");
+    }
+    if (!isPlainObject(receipt)) throw fail("malformed receipt");
+    const subject = receipt.subject;
+    const action = receipt.action;
+    const decision = receipt.decision;
+    const approval = receipt.approval;
+    if (!isPlainObject(subject) || subject.requestId !== requestId) throw fail("other request");
+    if (!isPlainObject(action) || action.requestId !== requestId) throw fail("other request");
+    if (action.action !== "tool.invoke") throw fail("action");
+    const params = action.materialParameters;
+    if (!isPlainObject(params) || params.toolName !== tool || params.connectionId !== this.config.connectionId || !sameData(params.arguments, args)) {
+      throw fail("terms differ");
+    }
+    if (!isPlainObject(decision) || decision.decision !== "ASK") throw fail("not an ASK");
+    if (!isPlainObject(approval) || approval.state !== "approved" && approval.state !== "consumed") {
+      throw fail("not approved");
+    }
+  }
+  // -------------------------------------------------------------- signer
+  /** @internal The only signer x402 gets: EIP-3009 typed data, nothing else. */
+  guardedSigner;
+  recordedRefusals = /* @__PURE__ */ new WeakSet();
+  /** @internal Records a refusal once. */
+  recordRefusal(err, flowId) {
+    if (this.recordedRefusals.has(err)) return;
+    this.recordedRefusals.add(err);
+    this.record({
+      event: "refused",
+      ...flowId ? { flowId } : {},
+      code: err.code,
+      ...err.guardianReasonCode ? { guardianReasonCode: err.guardianReasonCode } : {},
+      ...err.requestId ? { requestId: err.requestId } : {},
+      ...err.outcomeUnknown ? { outcomeUnknown: true } : {},
+      detail: err.message
+    });
+  }
+  async signGuarded(raw) {
+    try {
+      return await this.signChecked(raw);
+    } catch (error) {
+      if (error instanceof X402GuardRefused) {
+        this.recordRefusal(error, flowStorage.getStore()?.id);
+      }
+      throw error;
+    }
+  }
+  async signChecked(raw) {
+    const flow = flowStorage.getStore();
+    if (!flow) throw refused("NO_PAYMENT_FLOW", "Signing outside a guarded payment is refused.");
+    flow.signAttempted = true;
+    const token = flow.token;
+    if (!token) throw refused("NO_SIGNING_TOKEN", "No approved payment in this flow.");
+    if (token.used) throw refused("SIGNING_TOKEN_USED", "This approval was already used to sign.");
+    token.used = true;
+    if (this.now() > token.expiresAtMs) {
+      throw refused("SIGNING_TOKEN_EXPIRED", "The approval's signing window has passed.");
+    }
+    const pr = flow.paymentRequired;
+    const live = readTerms(
+      pr?.x402Version,
+      flow.selectedRequirements,
+      flow.paymentRequired,
+      flow.request,
+      this.termsOptions
+    );
+    if (!live.ok || !sameData(live.terms, token.terms) || !sameData(jsonCopy(flow.selectedRequirements), token.requirementSnapshot)) {
+      throw refused("TERMS_CHANGED", "The payment terms changed after the decision.");
+    }
+    let data;
+    try {
+      data = structuredClone(raw);
+    } catch {
+      throw mismatch("not plain data");
+    }
+    const checked = this.checkTypedData(data, token);
+    const ledgerId = flow.ledgerId;
+    if (!ledgerId) throw refused("SIGNING_REFUSED", "No reservation for this payment.");
+    const marked = await this.ledger.patch(ledgerId, (e) => {
+      if (e.state !== "reserved") {
+        throw refused("SIGNING_REFUSED", "This payment's reservation was released; nothing was signed.");
+      }
+      e.state = "signing";
+      e.from = checked.from;
+      e.nonce = checked.nonce;
+      e.validBefore = checked.validBefore;
+    });
+    if (!marked) throw refused("SIGNING_REFUSED", "No reservation for this payment.");
+    let signature;
+    try {
+      signature = await this.wallet.signTypedData(
+        data
+      );
+    } catch (error) {
+      throw error instanceof X402GuardRefused ? error : refused("SIGNING_REFUSED", "The wallet failed to sign.");
+    }
+    flow.signed = { nonce: checked.nonce, from: checked.from, validBefore: checked.validBefore };
+    await this.ledger.patch(ledgerId, (e) => {
+      if (e.state === "signing") e.state = "signed";
+    }).catch(() => void 0);
+    if (flow.requestContext) {
+      flow.requestContext.signedEntries.push(ledgerId);
+      flow.requestContext.versions.set(ledgerId, token.terms.x402Version);
+    }
+    this.record({
+      event: "signed",
+      flowId: flow.id,
+      requestId: token.requestId,
+      receiptReference: token.receiptReference,
+      nonce: checked.nonce,
+      from: checked.from,
+      validBefore: checked.validBefore,
+      network: token.terms.network
+    });
+    return signature;
+  }
+  checkTypedData(data, token) {
+    const { terms, pinned } = token;
+    if (!isPlainObject(data) || !hasExactKeys(data, ["domain", "types", "primaryType", "message"])) {
+      throw mismatch("shape");
+    }
+    if (data.primaryType !== "TransferWithAuthorization") throw mismatch("primaryType");
+    if (!sameData(data.types, EIP3009_TYPES)) throw mismatch("types");
+    const domain = data.domain;
+    if (!isPlainObject(domain) || !hasExactKeys(domain, ["name", "version", "chainId", "verifyingContract"])) {
+      throw mismatch("domain fields");
+    }
+    const chainId = toBig(domain.chainId);
+    if (chainId === null || chainId !== BigInt(pinned.chainId)) throw mismatch("chainId");
+    if (typeof domain.verifyingContract !== "string" || domain.verifyingContract.toLowerCase() !== terms.asset) {
+      throw mismatch("verifyingContract");
+    }
+    if (domain.name !== terms.extra.name || domain.name !== pinned.name) throw mismatch("name");
+    if (domain.version !== terms.extra.version || domain.version !== pinned.version) {
+      throw mismatch("version");
+    }
+    const m = data.message;
+    if (!isPlainObject(m) || !hasExactKeys(m, ["from", "to", "value", "validAfter", "validBefore", "nonce"])) {
+      throw mismatch("message fields");
+    }
+    if (typeof m.from !== "string" || m.from.toLowerCase() !== this.walletAddress) {
+      throw mismatch("from");
+    }
+    if (typeof m.to !== "string" || m.to.toLowerCase() !== terms.payTo) throw mismatch("to");
+    const value = toBig(m.value);
+    if (value === null || value !== BigInt(terms.amount)) throw mismatch("value");
+    const nowSec = BigInt(Math.floor(this.now() / 1e3));
+    const validAfter = toBig(m.validAfter);
+    if (validAfter === null || validAfter > nowSec) throw mismatch("validAfter");
+    const validBefore = toBig(m.validBefore);
+    if (validBefore === null || validBefore > nowSec + BigInt(terms.maxTimeoutSeconds) || validBefore <= validAfter) {
+      throw mismatch("validBefore");
+    }
+    if (typeof m.nonce !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(m.nonce)) {
+      throw mismatch("nonce");
+    }
+    return {
+      from: m.from.toLowerCase(),
+      nonce: m.nonce.toLowerCase(),
+      validBefore: Number(validBefore)
+    };
+  }
+  // --------------------------------------------------------- after hooks
+  /** @internal */
+  afterPaymentCreation = async (ctx) => {
+    const flow = flowStorage.getStore();
+    if (!flow?.signed) return;
+    const auth = ctx.paymentPayload?.payload?.authorization;
+    if (typeof auth?.nonce !== "string" || auth.nonce.toLowerCase() !== flow.signed.nonce) {
+      this.record({
+        event: "refused",
+        flowId: flow.id,
+        code: "TYPED_DATA_MISMATCH",
+        detail: "The payload's nonce is not the one the guard signed."
+      });
+    }
+  };
+  /** @internal v2 only (x402 skips this hook for v1). */
+  paymentResponse = async (ctx) => {
+    const auth = ctx.paymentPayload?.payload?.authorization;
+    const settle = ctx.settleResponse;
+    if (typeof auth?.nonce !== "string" || !settle) return;
+    const entry = await this.ledger.patchByNonce(auth.nonce, (e) => {
+      if (settle.success === true && (e.state === "signed" || e.state === "signing")) {
+        e.state = "spent";
+      }
+    }).catch(() => void 0);
+    this.recordSettlement(entry, settle);
+  };
+  /** @internal Called when a flow ends. */
+  async endFlow(flow) {
+    if (flow.signed) return;
+    if (flow.redeemed) {
+      this.record({
+        event: "redeemed-not-signed",
+        flowId: flow.id,
+        requestId: flow.redeemed.requestId,
+        receiptReference: flow.redeemed.receiptReference,
+        detail: "Redeemed, not signed. The decision is spent; a retry needs a new decision."
+      });
+    } else if (flow.executeOutcomeUnknown) {
+      this.record({
+        event: "redeemed-not-signed",
+        flowId: flow.id,
+        requestId: flow.executeOutcomeUnknown.requestId,
+        outcomeUnknown: true,
+        detail: "Redeemed or unknown, not signed. The decision may be spent; look up the request before retrying, and a retry needs a new decision."
+      });
+    }
+    if (flow.ledgerId) await this.ledger.releaseUnsigned(flow.ledgerId).catch(() => void 0);
+  }
+  /** @internal */
+  newFlow(paymentRequired) {
+    const { info, ctx } = isPlainObject(paymentRequired) ? this.requestInfoFor(paymentRequired) : { info: null, ctx: requestStorage.getStore() ?? null };
+    return {
+      id: newId("x4f"),
+      paymentRequired,
+      request: info,
+      requestContext: ctx,
+      dropped: [],
+      decided: false,
+      signAttempted: false
+    };
+  }
+};
+var LONGEST_FLOW_MS = 4 * MAX_GUARDIAN_CALL_TIMEOUT_MS + GUARDIAN_MAX_REQUEST_TTL_MS + MAX_CLAIM_POLL_INTERVAL_MS + MAX_SIGNING_WINDOW_MS + 6e4;
+function boundedMs(name, value, max) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > max) {
+    throw new Error(`guardian-x402: ${name} must be a whole number of ms from 1 to ${max}.`);
+  }
+  return value;
+}
+function jsonCopy(value) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return /* @__PURE__ */ Symbol("not comparable");
+  }
+}
+function wellFormed(value) {
+  if (!isPlainObject(value)) return false;
+  if (value.ok === true) {
+    return typeof value.requestId === "string" && (value.decision === "ALLOW" || value.decision === "ASK" || value.decision === "DENY");
+  }
+  return value.ok === false && typeof value.reasonCode === "string";
+}
+var GuardedX402Client = class extends x402Client {
+  /** @internal */
+  guard;
+  sealed = false;
+  constructor(guard, config) {
+    super(config.paymentRequirementsSelector);
+    this.guard = guard;
+    if (config.spendControls) super.setSpendControls(config.spendControls);
+    this.registerPolicy(guard.policy);
+    this.onBeforePaymentCreation(guard.beforePaymentCreation);
+    this.onAfterPaymentCreation(guard.afterPaymentCreation);
+    this.onPaymentResponse(guard.paymentResponse);
+    registerExactEvmScheme(this, {
+      signer: guard.guardedSigner,
+      networks: [...config.enabledNetworks ?? [BASE_SEPOLIA]]
+    });
+    this.sealed = true;
+  }
+  register(...args) {
+    if (this.sealed) throw refused("GUARD_SEALED", "The guarded client takes no other schemes.");
+    return super.register(...args);
+  }
+  registerV1(...args) {
+    if (this.sealed) throw refused("GUARD_SEALED", "The guarded client takes no other schemes.");
+    return super.registerV1(...args);
+  }
+  registerExtension(...args) {
+    if (this.sealed) throw refused("GUARD_SEALED", "The guarded client takes no extensions.");
+    return super.registerExtension(...args);
+  }
+  /**
+   * Refused once sealed: a failure hook can return its own payload, which
+   * x402 would send in place of a guard refusal.
+   */
+  onPaymentCreationFailure(...args) {
+    if (this.sealed) {
+      throw refused("GUARD_SEALED", "onPaymentCreationFailure hooks are refused on the guarded client.");
+    }
+    return super.onPaymentCreationFailure(...args);
+  }
+  setSpendControls(controls) {
+    if (this.sealed && controls === false) {
+      throw refused("GUARD_SEALED", "x402 spendControls cannot be turned off.");
+    }
+    return super.setSpendControls(controls);
+  }
+  async createPaymentPayload(paymentRequired) {
+    const flow = this.guard.newFlow(paymentRequired);
+    return flowStorage.run(flow, async () => {
+      try {
+        this.guard.precheck(paymentRequired, flow.request);
+        return await super.createPaymentPayload(paymentRequired);
+      } catch (error) {
+        const own = flow.refusal;
+        if (own) throw own;
+        if (error instanceof X402GuardRefused) {
+          this.guard.recordRefusal(error, flow.id);
+          throw error;
+        }
+        const msg = error instanceof Error ? error.message : "";
+        const dropped = flow.dropped[0];
+        if (dropped && /filtered out by policies/.test(msg)) {
+          const err = refused(dropped.code, dropped.detail);
+          this.guard.recordRefusal(err, flow.id);
+          throw err;
+        }
+        throw error;
+      } finally {
+        await this.guard.endFlow(flow);
+      }
+    });
+  }
+};
+function createX402Guard(config) {
+  return new X402Guard(config);
+}
+
+export {
+  PAY_TOOL,
+  PAY_ABOVE_CAP_TOOL,
+  BASE_SEPOLIA,
+  BASE_MAINNET,
+  PINNED_ASSETS,
+  EIP3009_TYPES,
+  X402GuardRefused,
+  readTerms,
+  X402Guard,
+  GuardedX402Client,
+  createX402Guard
+};