kawasekit 0.1.0-alpha.1 → 0.1.0-beta.3

package/README.md

@@ -5,7 +5,11 @@
 [![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**: Pre-alpha (M3 milestone — externally-callable kawasekit). Built in public. Not yet ready for production use.
+🚧 **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.
+
+```bash
+pnpm add kawasekit@beta   # 0.1.0-beta.2 — pre-GA, mainnet-capable
+```
 
 ## Vision
 
@@ -19,9 +23,9 @@ Built around modern account abstraction (ERC-4337 / Kernel v3.1) and Japan's fir
 
 - [x] **M1**: Smart account skeleton on Polygon Amoy
 - [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 (this release)
-- [ ] **M4**: Mainnet support + observability + npm v0.1 release + CLI + docs site
-- [ ] **M5**: Community building + first real integrations
+- [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
 - [ ] **M6**: Managed service alpha + Rust policy engine
 
 ## Quick Start
@@ -64,6 +68,28 @@ pays 0.001 JPYC, and the summary prints Polygonscan tx URLs for every
 settlement. See the [example README](./examples/agent-x402-jpyc/README.md)
 for the full walkthrough.
 
+### CLI (M4-4)
+
+Installing the package exposes a `kawasekit` binary (`npx kawasekit <cmd>`, or
+`pnpm exec kawasekit` in a workspace):
+
+```bash
+pnpm add kawasekit@beta
+
+npx kawasekit init                              # scaffold .env + required vars
+npx kawasekit account create --chain polygonAmoy   # deploy a Kernel smart account
+npx kawasekit policy create  --chain polygonAmoy   # build a Daily Limit policy
+npx kawasekit transfer       --chain polygonAmoy   # send JPYC via a sponsored UserOp
+npx kawasekit session-key issue   --chain polygonAmoy   # issue a session key + envelope
+npx kawasekit session-key restore --chain polygonAmoy
+npx kawasekit session-key revoke  --chain polygonAmoy
+npx kawasekit session-key rotate  --chain polygonAmoy
+```
+
+Every on-chain command takes `--chain "polygon" | "polygonAmoy"`. Mainnet
+(`--chain polygon`) additionally requires `KAWASEKIT_ALLOW_MAINNET=1` in the
+environment as a safety guard against accidental real-funds broadcasts.
+
 ### Programmatic use (M2)
 
 ```typescript
@@ -147,7 +173,9 @@ const app = new Hono();
 app.use(
   "/weather/*",
   x402Middleware({
-    facilitator: createSelfFacilitator({ walletClient, publicClient }),
+    // `network` is required (M4-1): it is cross-checked against
+    // walletClient.chain.isTestnet and throws on mismatch.
+    facilitator: createSelfFacilitator({ network: "testnet", walletClient, publicClient }),
     requirementsFor: () => [
       buildPaymentRequirements({
         chainId: polygonAmoy.id,
@@ -164,16 +192,45 @@ app.get("/weather/:city", (c) => c.json({ city: c.req.param("city"), weather: "s
 Client (any `fetch` becomes x402-aware):
 
 ```typescript
-import { createX402PaymentSigner, wrapFetch } from "kawasekit";
+import { createX402PaymentSigner, JPYC_DECIMALS, wrapFetch } from "kawasekit";
+import { parseUnits } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 
-const signer = createX402PaymentSigner({ account: privateKeyToAccount("0x...") });
-const fetch402 = wrapFetch({ signer });
+const signer = createX402PaymentSigner({
+  network: "testnet",
+  account: privateKeyToAccount("0x..."),
+  // 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" },
+});
+
+// onPayment is *required* at the type level — kawasekit refuses to default
+// to "always pay" silently. The callback is your budget guard.
+let spent = 0n;
+const MAX_SPEND = parseUnits("100", JPYC_DECIMALS); // 100 JPYC (JPYC has 18 decimals)
+const fetch402 = wrapFetch({
+  signer,
+  onPayment: (req) => {
+    const next = spent + BigInt(req.amount);
+    if (next > MAX_SPEND) return false; // budget exhausted → 402 returned
+    spent = next;
+    return true;
+  },
+});
 
 const res = await fetch402("https://api.example.com/weather/Tokyo");
-// → 402 → signed retry → 200 with JPYC settled on-chain
+// → 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.
+
 ### Session-key lifecycle (M3-2)
 
 ```typescript
@@ -206,21 +263,30 @@ const restored = await restoreSessionAccount({
 
 ## Supported Chains
 
-| Chain | Status | JPYC |
+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 |
 |---|---|---|
-| Polygon | M2 | ✅ Live (`0xE7C3...c29`) |
-| Polygon Amoy (testnet) | M2 (primary dev target) | ✅ Live (`0xE7C3...c29`, mint-controlled) |
-| Kaia | M3+ | 🚧 In development |
-| Avalanche | M4+ | ✅ Live (`0xE7C3...c29`) |
-| Ethereum | M4+ | ✅ Live (`0xE7C3...c29`) |
+| 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 |
+
+¹ 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.
 
 ## Why Japan-first
 
 The Japanese stablecoin ecosystem in 2026 is uniquely positioned:
 
 - **JPYC** is a fully regulated yen-pegged stablecoin under the revised Payment Services Act
-- Multi-chain by design (same address on Ethereum, Polygon, Avalanche)
-- Kaia integration coming via LINE NEXT's Unifi
+- Multi-chain by design (same address on Ethereum, Polygon, Avalanche, and Kaia)
+- Now live on Kaia (2026-05), with LINE NEXT's Unifi supporting JPYC since 2026-05-22
 - Japanese AI startup ecosystem actively seeking modern payment rails
 
 kawasekit aims to be the developer-facing layer that connects this stablecoin infrastructure to the global AI agent ecosystem.
@@ -237,11 +303,11 @@ pnpm install
 pnpm dev
 ```
 
-The site will deploy to GitHub Pages on every push to `main` once Pages is enabled in the repository settings — see `.github/workflows/docs.yml`. The planned canonical URL is `kawasekit.k0yote.dev`.
+The site is live at **[kawasekit.k0yote.dev](https://kawasekit.k0yote.dev)**, auto-deployed from `main` via `.github/workflows/docs.yml`.
 
 ## Contributing
 
-This is currently a solo project, but contributions will be welcomed once we hit M3. See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for guidelines.
+This is currently a solo project, but with M1–M4 shipped and `0.1.0-beta` on npm, contributions are now welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for guidelines.
 
 For now, feedback, issues, and discussions are the most valuable contributions.
 
@@ -259,4 +325,4 @@ This license includes an explicit patent grant, which is important for working i
 
 ---
 
-Follow development progress: [@k0yote](https://github.com/k0yote) · Project home: kawasekit.k0yote.dev (coming soon)
+Follow development progress: [@k0yote](https://github.com/k0yote) · Project home: [kawasekit.k0yote.dev](https://kawasekit.k0yote.dev)

package/dist/{chunk-2QYCWRYR.js → chunk-2V3W4B64.js}

@@ -1,7 +1,8 @@
-import { X402InvalidPayloadError, X402_VERSION, chainIdToX402Network, X402_HEADER_PAYMENT_SIGNATURE, encodePaymentSignatureHeader, X402_HEADER_PAYMENT_RESPONSE, decodePaymentResponseHeader, x402NetworkToChainId, JPYC_V2_ADDRESS, JPYC_EIP712_DOMAIN_HINT, X402_HEADER_PAYMENT_REQUIRED, decodePaymentRequiredHeader, jpycAbi } from './chunk-LNXYCHRY.js';
+import { JPYC_EIP712_DOMAIN_HINT, JPYC_V2_ADDRESS, X402InvalidPayloadError, X402_HEADER_PAYMENT_SIGNATURE, encodePaymentSignatureHeader, X402_HEADER_IDEMPOTENCY_KEY, X402_HEADER_PAYMENT_RESPONSE, decodePaymentResponseHeader, X402InvalidConfigError, X402_HEADER_PAYMENT_REQUIRED, decodePaymentRequiredHeader, jpycAbi } from './chunk-CD6SQBZN.js';
+import { X402_VERSION, chainIdToX402Network, x402NetworkToChainId } from './chunk-WMFCI6KC.js';
 import { getChain, isSupportedChainId } from './chunk-SA7LMQFG.js';
 import { invokeHookSafely } from './chunk-LEHWRDVS.js';
-import { parseSignature, getAddress, recoverTypedDataAddress, isAddress } from 'viem';
+import { getAddress, keccak256, stringToHex, parseSignature, isAddress, recoverTypedDataAddress } from 'viem';
 
 var transferWithAuthorizationTypes = {
   TransferWithAuthorization: [
@@ -34,6 +35,20 @@ function generateAuthorizationNonce() {
   crypto.getRandomValues(bytes);
   return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
 }
+var EIP3009_NONCE_DOMAIN_TAG = "kawasekit/eip3009-nonce/1";
+function deriveAuthorizationNonce(input, scope) {
+  if (input.idempotencyKey === "") {
+    throw new Error("deriveAuthorizationNonce: idempotencyKey must be a non-empty string");
+  }
+  const preimage = JSON.stringify([
+    EIP3009_NONCE_DOMAIN_TAG,
+    input.idempotencyKey,
+    getAddress(scope.from),
+    getAddress(scope.verifyingContract),
+    scope.chainId
+  ]);
+  return keccak256(stringToHex(preimage));
+}
 function authorizationDeadlineFromNow(seconds, nowSec) {
   const now = nowSec ?? BigInt(Math.floor(Date.now() / 1e3));
   return now + BigInt(seconds);
@@ -98,6 +113,20 @@ function splitAuthorization(signature, domain, message) {
     message
   };
 }
+var KNOWN_ASSETS = [
+  {
+    id: "jpyc-v2",
+    name: JPYC_EIP712_DOMAIN_HINT.name,
+    version: JPYC_EIP712_DOMAIN_HINT.version,
+    verifyingContract: getAddress(JPYC_V2_ADDRESS)
+  }
+];
+function getKnownAssetDomain(id) {
+  return KNOWN_ASSETS.find((entry) => entry.id === id);
+}
+function listKnownAssetIds() {
+  return KNOWN_ASSETS.map((entry) => entry.id);
+}
 var X402_DEFAULT_AUTHORIZATION_LIFETIME_SECONDS = 300;
 var UINT256_MAX = (1n << 256n) - 1n;
 var UINT256_DECIMAL = /^(0|[1-9][0-9]*)$/;
@@ -126,20 +155,51 @@ function assertAddress(value, field) {
   }
   return value;
 }
-function resolveDomain(requirements, override) {
-  if (override) {
-    return override;
-  }
-  const extra = requirements.extra;
-  if (typeof extra.name === "string" && typeof extra.version === "string") {
-    return { name: extra.name, version: extra.version };
+function resolveAssetParam(asset) {
+  if (asset.kind === "known") {
+    const entry = getKnownAssetDomain(asset.id);
+    if (entry === void 0) {
+      throw new X402InvalidConfigError(
+        "asset.id",
+        `unknown asset id ${JSON.stringify(asset.id)}. Supported: ${listKnownAssetIds().map((id) => JSON.stringify(id)).join(", ")}.`
+      );
+    }
+    return {
+      name: entry.name,
+      version: entry.version,
+      verifyingContract: entry.verifyingContract
+    };
   }
-  if (getAddress(requirements.asset) === getAddress(JPYC_V2_ADDRESS)) {
-    return JPYC_EIP712_DOMAIN_HINT;
+  if (asset.kind === "unsafeOverride") {
+    const { domain } = asset;
+    if (typeof domain.name !== "string" || domain.name === "") {
+      throw new X402InvalidConfigError(
+        "asset.domain.name",
+        "`unsafeOverride.domain.name` must be a non-empty string"
+      );
+    }
+    if (typeof domain.version !== "string" || domain.version === "") {
+      throw new X402InvalidConfigError(
+        "asset.domain.version",
+        "`unsafeOverride.domain.version` must be a non-empty string"
+      );
+    }
+    if (!isAddress(domain.verifyingContract, { strict: false })) {
+      throw new X402InvalidConfigError(
+        "asset.domain.verifyingContract",
+        `\`unsafeOverride.domain.verifyingContract\` must be a valid address, got ${JSON.stringify(domain.verifyingContract)}`
+      );
+    }
+    return {
+      name: domain.name,
+      version: domain.version,
+      verifyingContract: getAddress(domain.verifyingContract)
+    };
   }
-  throw new X402InvalidPayloadError(
-    "PaymentRequirements",
-    "`extra.name` and `extra.version` are required for exact-EVM signing on a non-JPYC asset"
+  const exhaustive = asset;
+  throw new X402InvalidConfigError(
+    "asset.kind",
+    `unsupported kind ${JSON.stringify(exhaustive.kind)}. Expected "known" or "unsafeOverride".`
   );
 }
 function validateRequirements(requirements) {
@@ -179,7 +239,14 @@ function createX402PaymentSigner(params) {
       `\`defaultLifetimeSeconds\` must be positive, got ${defaultLifetimeSeconds}`
     );
   }
-  const domainOverride = params.domainOverride;
+  const maxAmountPerSign = params.maxAmountPerSign;
+  if (maxAmountPerSign !== void 0 && maxAmountPerSign <= 0n) {
+    throw new X402InvalidPayloadError(
+      "X402PaymentSignerConfig",
+      `\`maxAmountPerSign\` must be a positive bigint, got ${maxAmountPerSign}`
+    );
+  }
+  const pinnedDomain = resolveAssetParam(params.asset);
   return {
     address: account.address,
     async sign(signParams) {
@@ -198,7 +265,18 @@ function createX402PaymentSigner(params) {
           `signer was configured for network="testnet" but requirements.network="${paymentRequirements.network}" (chainId ${chainId}) is a mainnet \u2014 refusing to sign payment for real funds`
         );
       }
-      const domain = resolveDomain(paymentRequirements, domainOverride);
+      if (getAddress(asset) !== pinnedDomain.verifyingContract) {
+        throw new X402InvalidPayloadError(
+          "PaymentRequirements",
+          `requirements.asset (${getAddress(asset)}) does not match the signer's pinned verifyingContract (${pinnedDomain.verifyingContract}) \u2014 refusing to sign for an asset the signer was not configured to handle`
+        );
+      }
+      if (maxAmountPerSign !== void 0 && value > maxAmountPerSign) {
+        throw new X402InvalidPayloadError(
+          "PaymentRequirements",
+          `requirements.amount (${value}) exceeds the signer's \`maxAmountPerSign\` ceiling (${maxAmountPerSign}) \u2014 refusing to sign a payment above the configured per-signature limit (threat 1.14)`
+        );
+      }
       const lifetime = Math.min(defaultLifetimeSeconds, paymentRequirements.maxTimeoutSeconds);
       const validAfter = signParams.validAfter ?? 0n;
       const validBefore = signParams.validBefore ?? authorizationDeadlineFromNow(lifetime);
@@ -208,10 +286,22 @@ function createX402PaymentSigner(params) {
           `\`validBefore\` (${validBefore}) must be greater than \`validAfter\` (${validAfter})`
         );
       }
-      const nonce = generateAuthorizationNonce();
+      const nonce = signParams.idempotencyKey !== void 0 ? deriveAuthorizationNonce(
+        { idempotencyKey: signParams.idempotencyKey },
+        {
+          from: account.address,
+          verifyingContract: pinnedDomain.verifyingContract,
+          chainId
+        }
+      ) : generateAuthorizationNonce();
       const signed = await signTransferWithAuthorization(
         account,
-        { name: domain.name, version: domain.version, chainId, verifyingContract: asset },
+        {
+          name: pinnedDomain.name,
+          version: pinnedDomain.version,
+          chainId,
+          verifyingContract: pinnedDomain.verifyingContract
+        },
         {
           from: account.address,
           to: payTo,
@@ -302,7 +392,7 @@ var TRANSFER_AUTHORIZATION_TYPES = {
     { name: "nonce", type: "bytes32" }
   ]
 };
-function resolveDomain2(requirements) {
+function resolveDomain(requirements) {
   const extra = requirements.extra;
   if (typeof extra.name === "string" && typeof extra.version === "string") {
     return { name: extra.name, version: extra.version };
@@ -509,7 +599,7 @@ function createSelfFacilitator(params) {
     }
     let recovered;
     try {
-      const domain = resolveDomain2(req.paymentRequirements);
+      const domain = resolveDomain(req.paymentRequirements);
       recovered = await recoverTypedDataAddress({
         domain: {
           name: domain.name,
@@ -811,19 +901,22 @@ function wrapFetch(params) {
       emitFailure("no_acceptable_requirement", 402);
       return initialResponse;
     }
-    if (onPayment) {
-      const proceed = await onPayment(chosen, paymentRequired);
-      if (proceed === false) {
-        emitFailure("onPayment_declined", 402);
-        return initialResponse;
-      }
+    const proceed = await onPayment(chosen, paymentRequired);
+    if (proceed === false) {
+      emitFailure("onPayment_declined", 402);
+      return initialResponse;
     }
+    const idempotencyKey = params.idempotencyKeyFor?.(input, chosen, paymentRequired);
     const paymentPayload = await params.signer.sign({
       paymentRequirements: chosen,
-      ...paymentRequired.resource ? { resource: paymentRequired.resource } : {}
+      ...paymentRequired.resource ? { resource: paymentRequired.resource } : {},
+      ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
     });
     const retryHeaders = new Headers(init?.headers);
     retryHeaders.set(X402_HEADER_PAYMENT_SIGNATURE, encodePaymentSignatureHeader(paymentPayload));
+    if (idempotencyKey !== void 0) {
+      retryHeaders.set(X402_HEADER_IDEMPOTENCY_KEY, idempotencyKey);
+    }
     const retryResponse = await baseFetch(input, { ...init, headers: retryHeaders });
     if (retryResponse.status >= 200 && retryResponse.status < 300) {
       const settlementHeader = retryResponse.headers.get(X402_HEADER_PAYMENT_RESPONSE);
@@ -859,6 +952,6 @@ function wrapFetch(params) {
   };
 }
 
-export { X402_DEFAULT_AUTHORIZATION_LIFETIME_SECONDS, X402_FACILITATOR_ERROR_CODES, authorizationDeadlineFromNow, createCoinbaseFacilitator, createHttpFacilitator, createSelfFacilitator, createX402PaymentSigner, generateAuthorizationNonce, signCancelAuthorization, signReceiveWithAuthorization, signTransferWithAuthorization, wrapFetch };
-//# sourceMappingURL=chunk-2QYCWRYR.js.map
-//# sourceMappingURL=chunk-2QYCWRYR.js.map
+export { X402_DEFAULT_AUTHORIZATION_LIFETIME_SECONDS, X402_FACILITATOR_ERROR_CODES, authorizationDeadlineFromNow, createCoinbaseFacilitator, createHttpFacilitator, createSelfFacilitator, createX402PaymentSigner, deriveAuthorizationNonce, generateAuthorizationNonce, getKnownAssetDomain, listKnownAssetIds, signCancelAuthorization, signReceiveWithAuthorization, signTransferWithAuthorization, wrapFetch };
+//# sourceMappingURL=chunk-2V3W4B64.js.map
+//# sourceMappingURL=chunk-2V3W4B64.js.map