kawasekit 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -5,10 +5,15 @@
 [![npm version](https://img.shields.io/npm/v/kawasekit.svg)](https://www.npmjs.com/package/kawasekit)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-🚧 **Status**: M4 complete — `kawasekit@0.1.0-beta.2` is published on npm (SLSA provenance, `beta` dist-tag) and mainnet-capable, with payment flows verified on Polygon mainnet. **Not yet GA.** Production use is currently constrained to **small per-call values**: the reasoning-step idempotency gap (see [`docs/THREAT_MODEL.md` §6.1](./docs/THREAT_MODEL.md#61-reasoning-step-idempotency-gap)) is not yet closed, so duplicate-payment scenarios are the integrator's responsibility. GA (`0.1.0` on the `latest` tag) is gated on closing the fund-correctness gaps — the §6.1 idempotency layer (or GA explicitly scoped to small per-call values) plus a `maxAmountPerSign` ceiling — and a clean beta soak. Review happens **continuously in the open**: issues and counter-examples are welcome on GitHub and via [SECURITY.md](./SECURITY.md) (the §6.1 gap itself came from public feedback). A formal third-party audit is a goal on the road to `1.0`, not a `0.1.0` GA blocker. Built in public.
+🚧 **Status**: M5 backbone complete — `kawasekit@0.1.0-beta.3` is published on npm (SLSA provenance, `beta` dist-tag) and mainnet-capable, with payment flows verified on Polygon mainnet. **Not yet GA**, but **both `0.1.0` fund-correctness gates are now closed**:
+
+- **Reasoning-step idempotency** ([`docs/THREAT_MODEL.md` §6.1](./docs/THREAT_MODEL.md), now closed) — a default-on server dedup layer prevents duplicate payments for identical re-sends, and an opt-in client-derived EIP-3009 nonce makes the token contract reject re-signed same-intent duplicates on-chain. See the [idempotency note](#x402-paywall-m3-1).
+- **`maxAmountPerSign`** (threat 1.14) — the signer can now pin a per-signature value ceiling, the way it already pins the asset.
+
+This removes the earlier blanket "small per-call values only" caveat: preventing duplicate payment is now a matter of correct integration (wiring a reasoning-step key for the regenerate / fan-out case), not a missing SDK capability. GA (`0.1.0` on the `latest` tag) now waits on a **clean one-week beta soak**. Review happens **continuously in the open**: issues and counter-examples are welcome on GitHub and via [SECURITY.md](./SECURITY.md) (the §6.1 gap itself came from public feedback). A formal third-party audit is a goal on the road to `1.0`, not a `0.1.0` GA blocker. Built in public.
 
 ```bash
-pnpm add kawasekit@beta   # 0.1.0-beta.2 — pre-GA, mainnet-capable
+pnpm add kawasekit@beta   # 0.1.0-beta.3 — pre-GA, mainnet-capable
 ```
 
 ## Vision
@@ -25,7 +30,7 @@ Built around modern account abstraction (ERC-4337 / Kernel v3.1) and Japan's fir
 - [x] **M2**: JPYC transfer via UserOp + EIP-3009 signing helpers + Daily Limit spending policy
 - [x] **M3**: x402 v2 server/client/facilitator + session-key lifecycle + Mastra/Hono integration example
 - [x] **M4**: Polygon mainnet support + observability (Prometheus / OTLP) + CLI + docs site + npm `0.1.0-alpha`/`0.1.0-beta` release
-- [ ] **M5**: Reasoning-step idempotency layer (§6.1) + `0.1.0` GA promote + Kaia support — the technical prerequisites for first real integrations
+- [ ] **M5** *(backbone done)*: reasoning-step idempotency layer (§6.1 ✅) + `maxAmountPerSign` ceiling (✅) → **both `0.1.0` fund-correctness gates closed**. Remaining: `0.1.0` GA promote (after a clean beta soak) and Kaia support (fast-follow). The README roadmap's framing — "Community building + first real integrations" — is the *outcome*; closing these gaps is the technical *prerequisite* for it.
 - [ ] **M6**: Managed service alpha + Rust policy engine
 
 ## Quick Start
@@ -173,8 +178,10 @@ const app = new Hono();
 app.use(
   "/weather/*",
   x402Middleware({
-    // `network` is required (M4-1): it is cross-checked against
-    // walletClient.chain.isTestnet and throws on mismatch.
+    // `network` is required (M4-1): cross-checked against walletClient.chain.isTestnet,
+    // throws on mismatch. walletClient.account MUST be built with viem's `nonceManager`
+    // — createSelfFacilitator throws at construction otherwise (threat 2.2). On mainnet
+    // it waits for 4 confirmations by default (1 on testnet); override with `confirmations`.
     facilitator: createSelfFacilitator({ network: "testnet", walletClient, publicClient }),
     requirementsFor: () => [
       buildPaymentRequirements({
@@ -189,10 +196,17 @@ app.use(
 app.get("/weather/:city", (c) => c.json({ city: c.req.param("city"), weather: "sunny" }));
 ```
 
+The server **deduplicates identical re-sent paid requests by default** (M5-1): an
+in-memory store replays the cached response instead of settling twice, and closes
+the verify→settle race. It is single-process — for multi-replica deployments pass a
+shared store (or rely on the client-derived nonce below); disable with
+`idempotency: { store: "none" }`. See the [idempotency note](#x402-paywall-m3-1) below.
+
 Client (any `fetch` becomes x402-aware):
 
 ```typescript
 import { createX402PaymentSigner, JPYC_DECIMALS, wrapFetch } from "kawasekit";
+import { createIdempotencyKeyBuilder } from "kawasekit/idempotency";
 import { parseUnits } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 
@@ -202,8 +216,16 @@ const signer = createX402PaymentSigner({
   // Pin to the JPYC v2 EIP-712 domain at construction. The wire-format
   // extra.name / extra.version are ignored — Threat 1.4 mitigation.
   asset: { kind: "known", id: "jpyc-v2" },
+  // Per-signature value ceiling (M5-2, threat 1.14): refuse to sign any
+  // requirement above this. Pins the *amount* the way `asset` pins the token.
+  maxAmountPerSign: parseUnits("1", JPYC_DECIMALS), // ≤ 1 JPYC per call
 });
 
+// One key builder per agent run; call .next(intent) at each tool-execution
+// boundary and reuse the returned key for retries of that step.
+const keys = createIdempotencyKeyBuilder({ conversationId: "conv-42" });
+let stepKey = keys.next("fetch_weather:Tokyo");
+
 // onPayment is *required* at the type level — kawasekit refuses to default
 // to "always pay" silently. The callback is your budget guard.
 let spent = 0n;
@@ -216,20 +238,36 @@ const fetch402 = wrapFetch({
     spent = next;
     return true;
   },
+  // Reasoning-step idempotency (M5-1): the key is sent as an `Idempotency-Key`
+  // header AND derives a deterministic EIP-3009 nonce, so a regenerate /
+  // multi-agent re-sign of the SAME intent reuses the nonce and the token
+  // contract rejects the duplicate on-chain. Omit for today's random-nonce path.
+  idempotencyKeyFor: () => stepKey,
 });
 
 const res = await fetch402("https://api.example.com/weather/Tokyo");
 // → 402 → onPayment guard → signed retry → 200 with JPYC settled on-chain
 ```
 
-> **⚠️ Call-level idempotency only.** kawasekit guarantees that a single
-> `fetch402(...)` call settles **at most once** (EIP-3009 nonce + viem
-> `nonceManager`). It does **not** prevent your agent from invoking
-> `fetch402(...)` twice for the same reasoning step — retries, regeneration,
-> pause-resume, and multi-agent fan-out can each cause duplicate charges.
-> **Step-level idempotency is your responsibility**: track an
-> `Idempotency-Key` per reasoning step at the agent framework layer.
-> See [`docs/THREAT_MODEL.md` §6.1](./docs/THREAT_MODEL.md#61-reasoning-step-idempotency-gap) for the threat boundary.
+> **Reasoning-step idempotency (M5-1).** kawasekit now prevents one agent
+> reasoning step from paying twice, across two layers:
+>
+> - **Identical re-send — handled by default.** The server dedup layer (shown in
+>   the server example above) replays the cached response for a re-sent /
+>   network-duplicate request and closes the verify→settle race — no
+>   configuration needed (threat 1.8c, ✅). It is single-process; use a shared
+>   store for multiple replicas, or rely on the derived nonce below.
+> - **Re-signed same intent — wire the key.** A "Regenerate" click or multi-agent
+>   fan-out signs a *fresh* authorization for the same intent. Pass a
+>   reasoning-step key (`idempotencyKeyFor` + `createIdempotencyKeyBuilder`, shown
+>   in the client example) so the EIP-3009 nonce is derived deterministically and
+>   the JPYC contract rejects the duplicate **on-chain**, across uncoordinated
+>   replicas. The SDK can't do this for you — it never sees the LLM intent, only
+>   your harness does — so this half is **operator responsibility** (threat 1.8b,
+>   parallel to the asset pin). Omit the key to fall back to random-nonce behaviour.
+>
+> See [`docs/THREAT_MODEL.md` §6.1](./docs/THREAT_MODEL.md) (now closed) and the
+> [design RFC](./docs/rfc/m5-1-reasoning-step-idempotency.md) for the full model.
 
 ### Session-key lifecycle (M3-2)
 
@@ -263,22 +301,36 @@ const restored = await restoreSessionAccount({
 
 ## Supported Chains
 
-JPYC availability and kawasekit support are **two separate axes** — JPYC being
-live on a chain does **not** mean kawasekit has a config or has been tested
-there. Today kawasekit ships a chain config only for **Polygon + Polygon Amoy**
-(`src/chains/`); `getJpycAddress` / `SupportedChainId` accept only those two.
-
-| Chain | JPYC availability | kawasekit support |
+JPYC availability and kawasekit support are **two separate axes**. As of M5-3,
+kawasekit ships chain configs for **Polygon, Kaia, Avalanche, and Ethereum**
+(+ their testnets) in `src/chains/`, each carrying a per-chain finality default
+(`defaultConfirmations`). JPYC is live at the same address on **all eight
+chains** (Kaia / Kairos / Avalanche / Fuji / Sepolia confirmed by a read-only
+on-chain `name()`/`symbol()` check; Polygon / Amoy / Ethereum established). Two
+honest caveats: the **x402 EOA-payer path** works on every chain, but the
+**smart-account path** (session keys, sponsored UserOps) is verified only on
+Polygon — Kaia's runs via Pimlico in a later phase. Real x402 settlement is
+**verified on Kaia Kairos** — a JPYC `transferWithAuthorization` settled through
+the self-facilitator ([tx `0xe0a0…79c0`](https://kairos.kaiascan.io/tx/0xe0a0bfc75a447ff86c3502d49ff4e45cdf0396a1edd7eb5ed132dcb0130379c0),
+`pnpm m5:kairos-x402-self-settle`); the other new chains are liveness-verified
+but settlement is not yet exercised there.
+
+| Chain (id) | JPYC (`0xE7C3…c29`) | kawasekit support |
 |---|---|---|
-| Polygon (mainnet) | ✅ Live (`0xE7C3…c29`) | ✅ M4 — config shipped, verified with live mainnet txs |
-| Polygon Amoy (testnet) | ✅ Live (`0xE7C3…c29`) | ✅ primary testnet target |
-| Kaia | ✅ Live (`0xE7C3…c29`, same address)¹ | 🚧 planned M5 (x402 EOA-payer path first) |
-| Avalanche | ✅ Live (`0xE7C3…c29`) | ⬜ not yet — no chain config |
-| Ethereum | ✅ Live (`0xE7C3…c29`) | ⬜ not yet — no chain config |
+| Polygon (137) | ✅ Live | ✅ config + x402 + smart-account; verified with live mainnet txs |
+| Polygon Amoy (80002) | ✅ Live | ✅ primary testnet target |
+| Kaia (8217) | ✅ Live, same address¹ | ✅ M5-3 config — x402 EOA path; smart-account via Pimlico (later) |
+| Kaia Kairos (1001) | ✅ Live (on-chain verified) | ✅ M5-3 — x402 EOA path, **settlement verified on-chain** (tx `0xe0a0…79c0`) |
+| Avalanche (43114) | ✅ Live | ✅ M5-3 config — x402 EOA path; smart-account untested |
+| Avalanche Fuji (43113) | ✅ Live (on-chain verified) | ✅ M5-3 config — x402 EOA path |
+| Ethereum (1) | ✅ Live | ✅ M5-3 config — x402 EOA path; smart-account untested; deep confirmations (32) |
+| Sepolia (11155111) | ✅ Live (on-chain verified) | ✅ M5-3 config — x402 EOA path |
 
 ¹ JPYC officially launched on Kaia in 2026-05 (Kaia DLT Foundation; Unifi began
-JPYC support 2026-05-22), same contract address as the other chains. kawasekit
-has no Kaia chain config yet — support is scheduled for M5.
+JPYC support 2026-05-22), at the same contract address as the other chains. Kaia
+runs IBFT consensus with immediate finality, so its `defaultConfirmations` is `1`
+(not Polygon's `4`). See the
+[finality-tuning recipe](./docs/recipes/facilitator-finality-tuning.md).
 
 ## Why Japan-first
 

package/dist/asset-domain-CpJuDkI2.d.cts

@@ -0,0 +1,102 @@
+import { Address } from 'viem';
+
+/**
+ * Known-asset registry for {@link createX402PaymentSigner}'s
+ * `asset: { kind: "known", id }` discriminated-union branch.
+ *
+ * kawasekit only ships pinned EIP-712 domain definitions for assets it has
+ * verified empirically against the deployed contracts. Adding a new entry
+ * here requires citing the source-file + line reference for the contract
+ * that owns the `name` / `version` (so the next reviewer can spot-check the
+ * claim, the same discipline `docs/THREAT_MODEL.md` §0 demands of any ✅
+ * verdict that delegates to an out-of-scope component).
+ *
+ * @packageDocumentation
+ */
+
+/** Known asset identifiers. New entries must update this union AND the table. */
+type KnownAssetId = "jpyc-v2";
+/** Fully-pinned EIP-712 domain for a known asset. */
+interface KnownAssetDomain {
+    readonly id: KnownAssetId;
+    readonly name: string;
+    readonly version: string;
+    readonly verifyingContract: Address;
+}
+/**
+ * Look up a known asset's pinned EIP-712 domain by id.
+ *
+ * @returns The domain, or `undefined` if the id is not in the registry.
+ *
+ * @example
+ * ```ts
+ * import { getKnownAssetDomain } from "kawasekit";
+ *
+ * const jpyc = getKnownAssetDomain("jpyc-v2");
+ * if (jpyc === undefined) throw new Error("unreachable");
+ * console.log(jpyc.verifyingContract); // 0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29
+ * ```
+ */
+declare function getKnownAssetDomain(id: KnownAssetId): KnownAssetDomain | undefined;
+/** List every known asset id (for diagnostics / error messages). */
+declare function listKnownAssetIds(): readonly KnownAssetId[];
+
+/**
+ * EIP-712 asset-domain resolution for x402 / EIP-3009 signing.
+ *
+ * Construction-time pinning of the EIP-712 domain (`name` / `version` /
+ * `verifyingContract`) a signer will use. The integrator declares an
+ * {@link X402AssetParam} — either a kawasekit-maintained `known` asset or a
+ * loud `unsafeOverride` — and {@link resolveAssetParam} resolves it to a pinned
+ * {@link ResolvedAsset}. The signer then trusts only this pinned domain and
+ * refuses to sign for a mismatched advertised asset (Threat 1.4: misadvertised
+ * EIP-712 domain).
+ *
+ * Token-domain concern, reused by both the x402 signer (`src/x402/client.ts`)
+ * and the M6 PolicyGatedSigner (`src/signer/`).
+ *
+ * @packageDocumentation
+ */
+
+/** EIP-712 token domain `name` / `version` pair. */
+interface X402TokenDomain {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Asset binding for {@link createX402PaymentSigner} and the M6 PolicyGatedSigner.
+ * Required, discriminated.
+ *
+ * **Default-on whitelist**: integrators MUST declare which asset they intend
+ * to sign for. The `known` branch references a kawasekit-maintained
+ * whitelist (see `src/tokens/known-assets.ts`); the `unsafeOverride` branch
+ * is the deliberate escape hatch for any other asset and is named loudly so
+ * it survives a code review. Either way, the signer pins the EIP-712 domain
+ * at construction time and refuses to sign if `paymentRequirements.asset`
+ * disagrees with the pinned `verifyingContract`.
+ *
+ * Closes Threat 1.4 (misadvertised EIP-712 domain): the server's advertised
+ * `extra.name` / `extra.version` and `asset` are all ignored for signing
+ * purposes — the signer trusts only what the integrator declared here.
+ */
+type X402AssetParam = {
+    /** Use a kawasekit-maintained pinned EIP-712 domain. */
+    readonly kind: "known";
+    /** The asset id to pin. See {@link KnownAssetId} for the registry. */
+    readonly id: KnownAssetId;
+} | {
+    /**
+     * Use a caller-supplied EIP-712 domain for an asset NOT on the
+     * kawasekit whitelist. The name is deliberately loud — pick this
+     * branch only when you have separately audited the contract and its
+     * `eip712Domain()` output.
+     */
+    readonly kind: "unsafeOverride";
+    readonly domain: {
+        readonly name: string;
+        readonly version: string;
+        readonly verifyingContract: Address;
+    };
+};
+
+export { type KnownAssetDomain as K, type X402AssetParam as X, type KnownAssetId as a, type X402TokenDomain as b, getKnownAssetDomain as g, listKnownAssetIds as l };

package/dist/asset-domain-CpJuDkI2.d.ts

@@ -0,0 +1,102 @@
+import { Address } from 'viem';
+
+/**
+ * Known-asset registry for {@link createX402PaymentSigner}'s
+ * `asset: { kind: "known", id }` discriminated-union branch.
+ *
+ * kawasekit only ships pinned EIP-712 domain definitions for assets it has
+ * verified empirically against the deployed contracts. Adding a new entry
+ * here requires citing the source-file + line reference for the contract
+ * that owns the `name` / `version` (so the next reviewer can spot-check the
+ * claim, the same discipline `docs/THREAT_MODEL.md` §0 demands of any ✅
+ * verdict that delegates to an out-of-scope component).
+ *
+ * @packageDocumentation
+ */
+
+/** Known asset identifiers. New entries must update this union AND the table. */
+type KnownAssetId = "jpyc-v2";
+/** Fully-pinned EIP-712 domain for a known asset. */
+interface KnownAssetDomain {
+    readonly id: KnownAssetId;
+    readonly name: string;
+    readonly version: string;
+    readonly verifyingContract: Address;
+}
+/**
+ * Look up a known asset's pinned EIP-712 domain by id.
+ *
+ * @returns The domain, or `undefined` if the id is not in the registry.
+ *
+ * @example
+ * ```ts
+ * import { getKnownAssetDomain } from "kawasekit";
+ *
+ * const jpyc = getKnownAssetDomain("jpyc-v2");
+ * if (jpyc === undefined) throw new Error("unreachable");
+ * console.log(jpyc.verifyingContract); // 0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29
+ * ```
+ */
+declare function getKnownAssetDomain(id: KnownAssetId): KnownAssetDomain | undefined;
+/** List every known asset id (for diagnostics / error messages). */
+declare function listKnownAssetIds(): readonly KnownAssetId[];
+
+/**
+ * EIP-712 asset-domain resolution for x402 / EIP-3009 signing.
+ *
+ * Construction-time pinning of the EIP-712 domain (`name` / `version` /
+ * `verifyingContract`) a signer will use. The integrator declares an
+ * {@link X402AssetParam} — either a kawasekit-maintained `known` asset or a
+ * loud `unsafeOverride` — and {@link resolveAssetParam} resolves it to a pinned
+ * {@link ResolvedAsset}. The signer then trusts only this pinned domain and
+ * refuses to sign for a mismatched advertised asset (Threat 1.4: misadvertised
+ * EIP-712 domain).
+ *
+ * Token-domain concern, reused by both the x402 signer (`src/x402/client.ts`)
+ * and the M6 PolicyGatedSigner (`src/signer/`).
+ *
+ * @packageDocumentation
+ */
+
+/** EIP-712 token domain `name` / `version` pair. */
+interface X402TokenDomain {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Asset binding for {@link createX402PaymentSigner} and the M6 PolicyGatedSigner.
+ * Required, discriminated.
+ *
+ * **Default-on whitelist**: integrators MUST declare which asset they intend
+ * to sign for. The `known` branch references a kawasekit-maintained
+ * whitelist (see `src/tokens/known-assets.ts`); the `unsafeOverride` branch
+ * is the deliberate escape hatch for any other asset and is named loudly so
+ * it survives a code review. Either way, the signer pins the EIP-712 domain
+ * at construction time and refuses to sign if `paymentRequirements.asset`
+ * disagrees with the pinned `verifyingContract`.
+ *
+ * Closes Threat 1.4 (misadvertised EIP-712 domain): the server's advertised
+ * `extra.name` / `extra.version` and `asset` are all ignored for signing
+ * purposes — the signer trusts only what the integrator declared here.
+ */
+type X402AssetParam = {
+    /** Use a kawasekit-maintained pinned EIP-712 domain. */
+    readonly kind: "known";
+    /** The asset id to pin. See {@link KnownAssetId} for the registry. */
+    readonly id: KnownAssetId;
+} | {
+    /**
+     * Use a caller-supplied EIP-712 domain for an asset NOT on the
+     * kawasekit whitelist. The name is deliberately loud — pick this
+     * branch only when you have separately audited the contract and its
+     * `eip712Domain()` output.
+     */
+    readonly kind: "unsafeOverride";
+    readonly domain: {
+        readonly name: string;
+        readonly version: string;
+        readonly verifyingContract: Address;
+    };
+};
+
+export { type KnownAssetDomain as K, type X402AssetParam as X, type KnownAssetId as a, type X402TokenDomain as b, getKnownAssetDomain as g, listKnownAssetIds as l };

package/dist/chunk-DYTONQW2.js

@@ -0,0 +1,76 @@
+import { PolicyGatedSignerConfigError, resolveAssetParam, signTransferWithAuthorization } from './chunk-VPRR3TNA.js';
+import { evaluateSpendingPolicy } from './chunk-MTMJNYOD.js';
+import { getAddress } from 'viem';
+
+function createLocalPolicyGatedSigner(params) {
+  if (params.acknowledgeAdvisory !== true) {
+    throw new PolicyGatedSignerConfigError(
+      "acknowledgeAdvisory",
+      "a local signer is advisory (a key-holder can bypass its policy); pass `acknowledgeAdvisory: true` to construct one consciously, or use a cryptographic adapter for bounded/regulated flows"
+    );
+  }
+  const { account, policy, spendState } = params;
+  const pinned = resolveAssetParam(params.asset);
+  const from = getAddress(account.address);
+  return {
+    enforcement: "advisory",
+    from,
+    async sign(intent) {
+      if (getAddress(intent.from) !== from) {
+        return {
+          ok: false,
+          rejection: {
+            reason: "from_mismatch",
+            detail: `intent.from ${getAddress(intent.from)} does not equal signer.from ${from}`
+          }
+        };
+      }
+      if (getAddress(intent.token) !== pinned.verifyingContract) {
+        return {
+          ok: false,
+          rejection: {
+            reason: "token_not_allowed",
+            detail: `intent.token ${getAddress(intent.token)} does not equal the signer's pinned verifyingContract ${pinned.verifyingContract}`
+          }
+        };
+      }
+      const state = await spendState?.() ?? { spentPerToken: [] };
+      const nowSeconds = BigInt(Math.floor(Date.now() / 1e3));
+      const decision = evaluateSpendingPolicy(policy, intent, state, nowSeconds);
+      if (!decision.ok) {
+        return { ok: false, rejection: decision.rejection };
+      }
+      const signed = await signTransferWithAuthorization(
+        account,
+        {
+          name: pinned.name,
+          version: pinned.version,
+          chainId: intent.chainId,
+          verifyingContract: pinned.verifyingContract
+        },
+        {
+          from,
+          to: intent.to,
+          value: intent.value,
+          validAfter: intent.validAfter,
+          validBefore: intent.validBefore,
+          nonce: intent.nonce
+        }
+      );
+      return { ok: true, signature: signed.signature, intent };
+    },
+    describe() {
+      return {
+        enforcement: "advisory",
+        from,
+        policyId: policy.session.id,
+        notAfter: policy.session.notAfter,
+        revoked: policy.revoked
+      };
+    }
+  };
+}
+
+export { createLocalPolicyGatedSigner };
+//# sourceMappingURL=chunk-DYTONQW2.js.map
+//# sourceMappingURL=chunk-DYTONQW2.js.map

package/dist/chunk-DYTONQW2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/signer/local.ts"],"names":[],"mappings":";;;;AAgEO,SAAS,6BACf,MAAA,EACgC;AAChC,EAAA,IAAI,MAAA,CAAO,wBAAwB,IAAA,EAAM;AACxC,IAAA,MAAM,IAAI,4BAAA;AAAA,MACT,qBAAA;AAAA,MACA;AAAA,KACD;AAAA,EACD;AAEA,EAAA,MAAM,EAAE,OAAA,EAAS,MAAA,EAAQ,UAAA,EAAW,GAAI,MAAA;AACxC,EAAA,MAAM,MAAA,GAAS,iBAAA,CAAkB,MAAA,CAAO,KAAK,CAAA;AAC7C,EAAA,MAAM,IAAA,GAAO,UAAA,CAAW,OAAA,CAAQ,OAAO,CAAA;AAEvC,EAAA,OAAO;AAAA,IACN,WAAA,EAAa,UAAA;AAAA,IACb,IAAA;AAAA,IACA,MAAM,KAAK,MAAA,EAA4C;AACtD,MAAA,IAAI,UAAA,CAAW,MAAA,CAAO,IAAI,CAAA,KAAM,IAAA,EAAM;AACrC,QAAA,OAAO;AAAA,UACN,EAAA,EAAI,KAAA;AAAA,UACJ,SAAA,EAAW;AAAA,YACV,MAAA,EAAQ,eAAA;AAAA,YACR,QAAQ,CAAA,YAAA,EAAe,UAAA,CAAW,OAAO,IAAI,CAAC,+BAA+B,IAAI,CAAA;AAAA;AAClF,SACD;AAAA,MACD;AACA,MAAA,IAAI,UAAA,CAAW,MAAA,CAAO,KAAK,CAAA,KAAM,OAAO,iBAAA,EAAmB;AAC1D,QAAA,OAAO;AAAA,UACN,EAAA,EAAI,KAAA;AAAA,UACJ,SAAA,EAAW;AAAA,YACV,MAAA,EAAQ,mBAAA;AAAA,YACR,MAAA,EAAQ,gBAAgB,UAAA,CAAW,MAAA,CAAO,KAAK,CAAC,CAAA,sDAAA,EAAyD,OAAO,iBAAiB,CAAA;AAAA;AAClI,SACD;AAAA,MACD;AAEA,MAAA,MAAM,QAAqB,MAAM,UAAA,QAAmB,EAAE,aAAA,EAAe,EAAC,EAAE;AACxE,MAAA,MAAM,UAAA,GAAa,OAAO,IAAA,CAAK,KAAA,CAAM,KAAK,GAAA,EAAI,GAAI,GAAI,CAAC,CAAA;AACvD,MAAA,MAAM,QAAA,GAAW,sBAAA,CAAuB,MAAA,EAAQ,MAAA,EAAQ,OAAO,UAAU,CAAA;AACzE,MAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AACjB,QAAA,OAAO,EAAE,EAAA,EAAI,KAAA,EAAO,SAAA,EAAW,SAAS,SAAA,EAAU;AAAA,MACnD;AAEA,MAAA,MAAM,SAAS,MAAM,6BAAA;AAAA,QACpB,OAAA;AAAA,QACA;AAAA,UACC,MAAM,MAAA,CAAO,IAAA;AAAA,UACb,SAAS,MAAA,CAAO,OAAA;AAAA,UAChB,SAAS,MAAA,CAAO,OAAA;AAAA,UAChB,mBAAmB,MAAA,CAAO;AAAA,SAC3B;AAAA,QACA;AAAA,UACC,IAAA;AAAA,UACA,IAAI,MAAA,CAAO,EAAA;AAAA,UACX,OAAO,MAAA,CAAO,KAAA;AAAA,UACd,YAAY,MAAA,CAAO,UAAA;AAAA,UACnB,aAAa,MAAA,CAAO,WAAA;AAAA,UACpB,OAAO,MAAA,CAAO;AAAA;AACf,OACD;AACA,MAAA,OAAO,EAAE,EAAA,EAAI,IAAA,EAAM,SAAA,EAAW,MAAA,CAAO,WAAW,MAAA,EAAO;AAAA,IACxD,CAAA;AAAA,IACA,QAAA,GAA8B;AAC7B,MAAA,OAAO;AAAA,QACN,WAAA,EAAa,UAAA;AAAA,QACb,IAAA;AAAA,QACA,QAAA,EAAU,OAAO,OAAA,CAAQ,EAAA;AAAA,QACzB,QAAA,EAAU,OAAO,OAAA,CAAQ,QAAA;AAAA,QACzB,SAAS,MAAA,CAAO;AAAA,OACjB;AAAA,IACD;AAAA,GACD;AACD","file":"chunk-DYTONQW2.js","sourcesContent":["/**\n * The `local` PolicyGatedSigner adapter — `enforcement: \"advisory\"`.\n *\n * Wraps a viem {@link Account} + a {@link SpendingPolicy} + a pinned EIP-712\n * domain. `sign(intent)` evaluates the policy SDK-side and, on pass, produces a\n * real EIP-3009 authorization via {@link signTransferWithAuthorization}. It is\n * **advisory** because the wrapped key can still sign anything elsewhere — the\n * gate is only reached if the caller chooses to call *this* `sign()`. Use it for\n * dev, the A1 cross-language fallback, and any flow that is explicitly not\n * bounded/regulated; the type-gate (`requireNonBypassable`) keeps it out of\n * flows that require non-bypassable enforcement.\n *\n * @packageDocumentation\n */\n\nimport type { Account } from \"viem\";\nimport { getAddress } from \"viem\";\nimport type { SpendingPolicy, SpendState } from \"../policy/spending-policy\";\nimport { evaluateSpendingPolicy } from \"../policy/spending-policy\";\nimport type { X402AssetParam } from \"../tokens/asset-domain\";\nimport { resolveAssetParam } from \"../tokens/asset-domain\";\nimport { signTransferWithAuthorization } from \"../tokens/eip3009\";\nimport { PolicyGatedSignerConfigError } from \"./errors\";\nimport type { PaymentIntent, PolicyGatedSigner, SignerDescription, SignResult } from \"./types\";\n\n/** Parameters for {@link createLocalPolicyGatedSigner}. */\nexport interface CreateLocalPolicyGatedSignerParams {\n\t/** EOA / LocalAccount that signs the EIP-3009 authorization. */\n\treadonly account: Account;\n\t/** The spending policy this signer enforces (SDK-side, advisory). */\n\treadonly policy: SpendingPolicy;\n\t/** Asset binding — pins the EIP-712 domain `name`/`version`/`verifyingContract`. */\n\treadonly asset: X402AssetParam;\n\t/**\n\t * Required literal acknowledgement that this signer is **advisory** (a\n\t * key-holder can bypass its policy). Omitting it is a compile error (TS) and\n\t * a construction-time throw (JS) — so constructing an advisory signer is a\n\t * conscious, greppable act. For bounded/regulated flows use a cryptographic\n\t * adapter instead.\n\t */\n\treadonly acknowledgeAdvisory: true;\n\t/**\n\t * Optional cumulative-spend view (read-only) the adapter evaluates\n\t * `cumulativeCap` against. `local` does not own an authoritative ledger; the\n\t * caller folds a successful spend back in (e.g. via `mergeSpendState`) before\n\t * the next call. Default: empty.\n\t */\n\treadonly spendState?: () => SpendState | Promise<SpendState>;\n}\n\n/**\n * Construct a `local` (advisory) PolicyGatedSigner.\n *\n * @example\n * ```ts\n * const signer = createLocalPolicyGatedSigner({\n *   account,\n *   policy: createSpendingPolicy({ session: { id, notAfter }, perToken: [{ token: JPYC, maxPerSign: 1_000n }] }),\n *   asset: { kind: \"known\", id: \"jpyc-v2\" },\n *   acknowledgeAdvisory: true,\n * });\n * const result = await signer.sign(intent);\n * ```\n */\nexport function createLocalPolicyGatedSigner(\n\tparams: CreateLocalPolicyGatedSignerParams,\n): PolicyGatedSigner<\"advisory\"> {\n\tif (params.acknowledgeAdvisory !== true) {\n\t\tthrow new PolicyGatedSignerConfigError(\n\t\t\t\"acknowledgeAdvisory\",\n\t\t\t\"a local signer is advisory (a key-holder can bypass its policy); pass `acknowledgeAdvisory: true` to construct one consciously, or use a cryptographic adapter for bounded/regulated flows\",\n\t\t);\n\t}\n\n\tconst { account, policy, spendState } = params;\n\tconst pinned = resolveAssetParam(params.asset);\n\tconst from = getAddress(account.address);\n\n\treturn {\n\t\tenforcement: \"advisory\",\n\t\tfrom,\n\t\tasync sign(intent: PaymentIntent): Promise<SignResult> {\n\t\t\tif (getAddress(intent.from) !== from) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\trejection: {\n\t\t\t\t\t\treason: \"from_mismatch\",\n\t\t\t\t\t\tdetail: `intent.from ${getAddress(intent.from)} does not equal signer.from ${from}`,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (getAddress(intent.token) !== pinned.verifyingContract) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\trejection: {\n\t\t\t\t\t\treason: \"token_not_allowed\",\n\t\t\t\t\t\tdetail: `intent.token ${getAddress(intent.token)} does not equal the signer's pinned verifyingContract ${pinned.verifyingContract}`,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst state: SpendState = (await spendState?.()) ?? { spentPerToken: [] };\n\t\t\tconst nowSeconds = BigInt(Math.floor(Date.now() / 1000));\n\t\t\tconst decision = evaluateSpendingPolicy(policy, intent, state, nowSeconds);\n\t\t\tif (!decision.ok) {\n\t\t\t\treturn { ok: false, rejection: decision.rejection };\n\t\t\t}\n\n\t\t\tconst signed = await signTransferWithAuthorization(\n\t\t\t\taccount,\n\t\t\t\t{\n\t\t\t\t\tname: pinned.name,\n\t\t\t\t\tversion: pinned.version,\n\t\t\t\t\tchainId: intent.chainId,\n\t\t\t\t\tverifyingContract: pinned.verifyingContract,\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tfrom,\n\t\t\t\t\tto: intent.to,\n\t\t\t\t\tvalue: intent.value,\n\t\t\t\t\tvalidAfter: intent.validAfter,\n\t\t\t\t\tvalidBefore: intent.validBefore,\n\t\t\t\t\tnonce: intent.nonce,\n\t\t\t\t},\n\t\t\t);\n\t\t\treturn { ok: true, signature: signed.signature, intent };\n\t\t},\n\t\tdescribe(): SignerDescription {\n\t\t\treturn {\n\t\t\t\tenforcement: \"advisory\",\n\t\t\t\tfrom,\n\t\t\t\tpolicyId: policy.session.id,\n\t\t\t\tnotAfter: policy.session.notAfter,\n\t\t\t\trevoked: policy.revoked,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}