@kairoguard/sdk 0.0.2 → 0.0.3

package/README.md

@@ -1,92 +1,92 @@
-# `@kairo/sdk` (MVP)
-
-MVP helpers for:
-
-- computing an **EVM intent hash** (Keccak256 over serialized unsigned tx bytes)
-- building a Sui transaction to mint a **hard-gate** `PolicyReceipt`
-- fetching + validating a `PolicyReceipt` / `PolicyReceiptV2` object for gating
-- verifying a Sui custody `CustodyEvent` hash (v2/v3 canonical BCS hashing)
-
-## Install
-
-From repo root:
-
-```bash
-npm install
-```
-
-## DApp flow (user mints receipt with their Sui wallet)
-
-1) Your app computes the EVM unsigned tx bytes and intent hash:
-
-```ts
-import { computeEvmIntentFromUnsignedTxBytes } from "@kairo/sdk";
-
-const { intentHash } = computeEvmIntentFromUnsignedTxBytes({
-  chainId: 84532, // Base Sepolia (example)
-  unsignedTxBytesHex, // 0x... serialized unsigned EIP-1559 tx bytes
-});
-```
-
-2) Build a Sui tx that mints a receipt:
-
-```ts
-import { buildMintEvmReceiptTx } from "@kairo/sdk";
-
-const tx = buildMintEvmReceiptTx({
-  packageId,
-  policyObjectId,
-  evmChainId: 84532,
-  intentHash,
-  toEvm,
-});
-```
-
-3) Have the user sign+execute the Sui tx with their wallet (example using Sui dApp kit):
-
-```ts
-// Pseudocode: your wallet adapter will differ depending on your stack.
-const result = await wallet.signAndExecuteTransaction({
-  transaction: tx,
-  chain: "sui:testnet",
-});
-```
-
-4) Extract the created receipt object id from the execution result, then hard-gate EVM signing:
-
-```ts
-// We’ll add a helper for extracting created receipt IDs once we standardize receipt type strings.
-// For now, you can scan result.effects.created for the created object id of PolicyReceipt.
-```
-
-## Demo/extension flow (backend mints receipt)
-
-In this repo’s Key‑Spring demo, the backend mints the receipt (so the extension UX stays “approve action” instead of “approve Sui tx”).
-The verifier helper `fetchAndValidatePolicyReceipt` supports both receipt types:
-
-- legacy `PolicyReceipt` (MVP)
-- `PolicyReceiptV2` (includes `policy_root` + `policy_version_id` + optional selector/amount)
-
-If you also log to the custody ledger, you can verify a specific custody event hash:
-
-```ts
-import { fetchAndVerifyCustodyEvent } from "@kairo/sdk";
-
-const res = await fetchAndVerifyCustodyEvent({
-  suiRpcUrl,
-  custodyEventObjectId: "0x...",
-});
-if (!res.ok) throw new Error(res.error);
-```
-
-
-
-
-
-
-
-
-
-
-
-
+# `@kairo/sdk` (MVP)
+
+MVP helpers for:
+
+- computing an **EVM intent hash** (Keccak256 over serialized unsigned tx bytes)
+- building a Sui transaction to mint a **hard-gate** `PolicyReceipt`
+- fetching + validating a `PolicyReceipt` / `PolicyReceiptV2` object for gating
+- verifying a Sui custody `CustodyEvent` hash (v2/v3 canonical BCS hashing)
+
+## Install
+
+From repo root:
+
+```bash
+npm install
+```
+
+## DApp flow (user mints receipt with their Sui wallet)
+
+1) Your app computes the EVM unsigned tx bytes and intent hash:
+
+```ts
+import { computeEvmIntentFromUnsignedTxBytes } from "@kairo/sdk";
+
+const { intentHash } = computeEvmIntentFromUnsignedTxBytes({
+  chainId: 84532, // Base Sepolia (example)
+  unsignedTxBytesHex, // 0x... serialized unsigned EIP-1559 tx bytes
+});
+```
+
+2) Build a Sui tx that mints a receipt:
+
+```ts
+import { buildMintEvmReceiptTx } from "@kairo/sdk";
+
+const tx = buildMintEvmReceiptTx({
+  packageId,
+  policyObjectId,
+  evmChainId: 84532,
+  intentHash,
+  toEvm,
+});
+```
+
+3) Have the user sign+execute the Sui tx with their wallet (example using Sui dApp kit):
+
+```ts
+// Pseudocode: your wallet adapter will differ depending on your stack.
+const result = await wallet.signAndExecuteTransaction({
+  transaction: tx,
+  chain: "sui:testnet",
+});
+```
+
+4) Extract the created receipt object id from the execution result, then hard-gate EVM signing:
+
+```ts
+// We’ll add a helper for extracting created receipt IDs once we standardize receipt type strings.
+// For now, you can scan result.effects.created for the created object id of PolicyReceipt.
+```
+
+## Demo/extension flow (backend mints receipt)
+
+In this repo’s Key‑Spring demo, the backend mints the receipt (so the extension UX stays “approve action” instead of “approve Sui tx”).
+The verifier helper `fetchAndValidatePolicyReceipt` supports both receipt types:
+
+- legacy `PolicyReceipt` (MVP)
+- `PolicyReceiptV2` (includes `policy_root` + `policy_version_id` + optional selector/amount)
+
+If you also log to the custody ledger, you can verify a specific custody event hash:
+
+```ts
+import { fetchAndVerifyCustodyEvent } from "@kairo/sdk";
+
+const res = await fetchAndVerifyCustodyEvent({
+  suiRpcUrl,
+  custodyEventObjectId: "0x...",
+});
+if (!res.ok) throw new Error(res.error);
+```
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/auditBundle.d.ts

@@ -1,4 +1,4 @@
-import type { Hex } from "./types.js";
+import type { Hex } from "./types";
 export type AuditBundle = {
     v: 1;
     network: "testnet" | "mainnet";

package/dist/auditBundle.js

@@ -1,4 +1,4 @@
-import { fetchAndValidatePolicyReceipt } from "./suiReceipts.js";
+import { fetchAndValidatePolicyReceipt } from "./suiReceipts";
 /**
  * Minimal verifier for an audit bundle (v1).
  * This intentionally verifies only receipt commitments using on-chain receipt contents.

package/dist/cli.js

@@ -7,6 +7,7 @@ import { BackendClient } from "./backend.js";
 import { SKILL_MD, API_REFERENCE_MD, SDK_REFERENCE_MD } from "./skill-templates.js";
 const CONFIG_DIR = join(homedir(), ".kairo");
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const DEFAULT_BACKEND_URL = "https://backend.0xlegacy.link";
 function loadConfig() {
     if (!existsSync(CONFIG_PATH))
         return null;
@@ -20,14 +21,16 @@ function loadConfig() {
 function requireConfig() {
     const cfg = loadConfig();
     if (!cfg) {
-        console.error("No Kairo config found. Run: npx @kairo/sdk init <api-key>");
+        console.error("No Kairo config found. Run: npx @kairo/sdk init <YOUR_KEY>");
         process.exit(1);
     }
     return cfg;
 }
-function getClient(apiKeyOverride) {
-    const key = apiKeyOverride ?? requireConfig().apiKey;
-    return new BackendClient({ apiKey: key });
+function getClient(apiKeyOverride, backendUrlOverride) {
+    const cfg = requireConfig();
+    const key = apiKeyOverride ?? cfg.apiKey;
+    const backendUrl = backendUrlOverride ?? cfg.backendUrl ?? DEFAULT_BACKEND_URL;
+    return new BackendClient({ apiKey: key, backendUrl });
 }
 // ── Arg helpers ─────────────────────────────────────────────────────────────
 function flag(args, name) {
@@ -47,12 +50,13 @@ function requireFlag(args, name, label) {
 // ── Commands ────────────────────────────────────────────────────────────────
 async function cmdInit(args) {
     const apiKey = args[0];
+    const backendUrl = flag(args, "--backend-url") ?? DEFAULT_BACKEND_URL;
     if (!apiKey) {
-        console.error("Usage: kairo init <api-key>");
+        console.error("Usage: kairo init <YOUR_KEY> [--backend-url <url>]");
         process.exit(1);
     }
     mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(CONFIG_PATH, JSON.stringify({ apiKey }, null, 2) + "\n", "utf8");
+    writeFileSync(CONFIG_PATH, JSON.stringify({ apiKey, backendUrl }, null, 2) + "\n", "utf8");
     console.log(`  Config written to ${CONFIG_PATH}`);
     const skillDir = join(process.cwd(), ".cursor", "skills", "kairo");
     const refsDir = join(skillDir, "references");
@@ -61,13 +65,13 @@ async function cmdInit(args) {
     writeFileSync(join(refsDir, "api.md"), API_REFERENCE_MD, "utf8");
     writeFileSync(join(refsDir, "sdk.md"), SDK_REFERENCE_MD, "utf8");
     console.log(`  Skill files installed to ${skillDir}`);
-    const client = new BackendClient({ apiKey });
+    const client = new BackendClient({ apiKey, backendUrl });
     try {
         await client.getHealth();
-        console.log("  Backend connection verified.");
+        console.log(`  Backend connection verified (${backendUrl}).`);
     }
     catch {
-        console.log("  Warning: could not reach backend (check your network).");
+        console.log(`  Warning: could not reach backend ${backendUrl} (check your network).`);
     }
     console.log("\nKairo is ready. Your AI agent can now read the skill at .cursor/skills/kairo/SKILL.md");
 }
@@ -171,25 +175,25 @@ async function cmdAuditVerify(args) {
     console.log("OK");
 }
 function printUsage() {
-    console.log(`Kairo CLI — Agent Wallet Operations
-
-Usage: kairo <command> [options]
-
-Setup:
-  init <api-key>                    Store API key + install agent skill files
-
-Wallet & Policy:
-  health                            Server health check
-  register --label <name>           Register new API key
-  policy-create --stable-id <id> --allow <addrs>  Create policy
-  policy-register --policy-id <id>  Register policy version
-  policy-details --policy-id <id>   Get policy details
-  vault-status --wallet-id <id>     Check vault registration
-  vault-provision --wallet-id <id> --policy-id <id> --stable-id <id>
-  receipt-mint --policy-id <id> --binding-id <id> --destination <hex> --intent-hash <hex>
-
-Utility:
-  audit --limit <n>                 List audit events
+    console.log(`Kairo CLI — Agent Wallet Operations
+
+Usage: kairo <command> [options]
+
+Setup:
+  init <YOUR_KEY> [--backend-url <url>]  Store API key, backend URL, and install skill files
+
+Wallet & Policy:
+  health                            Server health check
+  register --label <name>           Register new API key
+  policy-create --stable-id <id> --allow <addrs>  Create policy
+  policy-register --policy-id <id>  Register policy version
+  policy-details --policy-id <id>   Get policy details
+  vault-status --wallet-id <id>     Check vault registration
+  vault-provision --wallet-id <id> --policy-id <id> --stable-id <id>
+  receipt-mint --policy-id <id> --binding-id <id> --destination <hex> --intent-hash <hex>
+
+Utility:
+  audit --limit <n>                 List audit events
   audit verify --sui <url> --bundle <path>  Verify audit bundle`);
 }
 // ── Main ────────────────────────────────────────────────────────────────────

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-export * from "./types.js";
-export * from "./evmIntent.js";
-export * from "./evm.js";
-export * from "./bitcoinIntent.js";
-export { type SolanaCluster, LAMPORTS_PER_SOL, type ParsedInstruction, type ParsedSolanaTransaction, type SolanaIntent, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent.js";
-export * from "./suiReceipts.js";
-export * from "./suiResult.js";
-export * from "./suiTxBuilders.js";
-export * from "./auditBundle.js";
-export * from "./suiCustody.js";
-export { KairoClient, type KairoClientOpts, type CreateWalletOpts, type WalletInfo, type ProposePolicyUpdateParams, type PolicyUpdateProposalResult, type ApprovePolicyUpdateParams, type ExecutePolicyUpdateParams, type PolicyUpdateStatus, } from "./client.js";
-export { KeyStore, type WalletRecord } from "./keystore.js";
-export { BackendClient, DEFAULT_BACKEND_URL, type BackendClientOpts } from "./backend.js";
+export * from "./types";
+export * from "./evmIntent";
+export * from "./evm";
+export * from "./bitcoinIntent";
+export { type SolanaCluster, LAMPORTS_PER_SOL, type ParsedInstruction, type ParsedSolanaTransaction, type SolanaIntent, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent";
+export * from "./suiReceipts";
+export * from "./suiResult";
+export * from "./suiTxBuilders";
+export * from "./auditBundle";
+export * from "./suiCustody";
+export { KairoClient, type KairoClientOpts, type CreateWalletOpts, type WalletInfo, type ProposePolicyUpdateParams, type PolicyUpdateProposalResult, type ApprovePolicyUpdateParams, type ExecutePolicyUpdateParams, type PolicyUpdateStatus, } from "./client";
+export { KeyStore, type WalletRecord } from "./keystore";
+export { BackendClient, DEFAULT_BACKEND_URL, type BackendClientOpts } from "./backend";

package/dist/index.js

@@ -1,13 +1,13 @@
-export * from "./types.js";
-export * from "./evmIntent.js";
-export * from "./evm.js";
-export * from "./bitcoinIntent.js";
-export { LAMPORTS_PER_SOL, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent.js";
-export * from "./suiReceipts.js";
-export * from "./suiResult.js";
-export * from "./suiTxBuilders.js";
-export * from "./auditBundle.js";
-export * from "./suiCustody.js";
-export { KairoClient, } from "./client.js";
-export { KeyStore } from "./keystore.js";
-export { BackendClient, DEFAULT_BACKEND_URL } from "./backend.js";
+export * from "./types";
+export * from "./evmIntent";
+export * from "./evm";
+export * from "./bitcoinIntent";
+export { LAMPORTS_PER_SOL, PROGRAM_IDS, SystemInstructionType, base58Decode, base58Encode, validateSolanaAddress, computeSolanaIntentHash, isKnownSafeProgram, isTokenProgram, getProgramName, lamportsToSOL, solToLamports, extractSystemTransfers, } from "./solanaIntent";
+export * from "./suiReceipts";
+export * from "./suiResult";
+export * from "./suiTxBuilders";
+export * from "./auditBundle";
+export * from "./suiCustody";
+export { KairoClient, } from "./client";
+export { KeyStore } from "./keystore";
+export { BackendClient, DEFAULT_BACKEND_URL } from "./backend";

package/dist/skill-templates.d.ts

@@ -4,6 +4,6 @@
  * All backend URLs are intentionally omitted -- the SDK and CLI
  * resolve the endpoint internally.
  */
-export declare const SKILL_MD = "---\nname: kairo\ndescription: Manage Kairo policy-enforced agent wallets. Use when creating wallets, setting transaction policies, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Supports full wallet lifecycle: register API key -> create wallet (DKG) -> create policy -> bind -> vault provision -> mint receipt -> sign. Uses @kairo/sdk for non-custodial wallet creation (agent keeps secret share locally).\n---\n\n# Kairo \u2014 Agent Wallet Management\n\n## Quick Reference\n\nCLI: `npx kairo <command>`\nSDK reference: `.cursor/skills/kairo/references/sdk.md`\nAPI reference: `.cursor/skills/kairo/references/api.md`\n\n## Setup\n\nRun the one-line installer (already done if you see this file):\n```bash\nnpx @kairo/sdk init <YOUR_API_KEY>\n```\n\nThe API key is stored in `~/.kairo/config.json`. All CLI commands read it automatically.\n\n## Common Workflows\n\n### Check API Health\n```bash\nnpx kairo health\n```\n\n### Create a Policy\n```bash\nnpx kairo policy-create --stable-id \"my-policy\" --allow \"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18\"\n```\nThen register the version:\n```bash\nnpx kairo policy-register --policy-id \"0x...\"\n```\n\n### Create Wallet (via SDK)\nFor wallet creation, use the Node.js SDK (handles DKG client-side):\n```typescript\nimport { KairoClient } from \"@kairo/sdk\";\nconst kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });\nconst wallet = await kairo.createWallet({ curve: \"secp256k1\" });\n```\nSee `.cursor/skills/kairo/references/sdk.md` for full SDK docs.\n\n### Provision Wallet into Vault\nRequires: policy version registered first.\n```bash\nnpx kairo vault-provision --wallet-id \"0x...\" --policy-id \"0x...\" --stable-id \"my-policy\"\n```\n\n### Mint Policy Receipt\n```bash\nnpx kairo receipt-mint --policy-id \"0x...\" --binding-id \"0x...\" --destination \"0x742d35Cc...\" --intent-hash \"0xabab...\"\n```\n\n### Check Vault Status\n```bash\nnpx kairo vault-status --wallet-id \"0x...\"\n```\n\n### View Audit Events\n```bash\nnpx kairo audit --limit 20\n```\n\n## Full Agent Flow (End to End)\n\n1. `npx @kairo/sdk init <key>` \u2014 store API key, install skill\n2. `npx kairo policy-create` \u2014 create transaction policy with allowed addresses\n3. `npx kairo policy-register` \u2014 register version in on-chain registry\n4. Create wallet via SDK `createWallet()` \u2014 runs DKG locally, secret share stays on agent\n5. `npx kairo vault-provision` \u2014 bind policy + register wallet in vault (atomic)\n6. `npx kairo receipt-mint` \u2014 request policy check for a transaction\n7. Sign via SDK \u2014 both shares combine, only if policy allows\n\n## Trust Model\n\n- Agent's key share stays local (`~/.kairo/keys/`)\n- Server's key share stays on Kairo backend\n- Neither party can sign alone\n- Policy engine gates every transaction before server releases its share\n- All policy decisions are on-chain (Sui) and verifiable\n\n## Troubleshooting\n\n- **401 Unauthorized**: API key missing/invalid or not registered in backend key store. Re-run `npx @kairo/sdk init <key>` with a valid key.\n- **403 Forbidden: key does not own wallet**: Wallet wasn't created/provisioned with this API key (ownership mismatch).\n- **429 Rate limit**: Public Sui RPC throttled \u2014 use Shinami or own RPC provider.\n- **MoveAbort code 102**: Policy version not registered \u2014 call `npx kairo policy-register` before `vault-provision`.\n- **`nonce too low` / `already known`**: Rapid reruns or duplicate raw tx; wait for pending tx, then re-sign and rebroadcast.\n- **AwaitingKeyHolderSignature**: Wallet needs activation after DKG \u2014 SDK activation flow required.\n";
+export declare const SKILL_MD = "---\nname: kairo\ndescription: Manage Kairo policy-enforced agent wallets. Use when creating wallets, setting transaction policies, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Supports full wallet lifecycle: register API key -> create wallet (DKG) -> create policy -> bind -> vault provision -> mint receipt -> sign. Uses @kairo/sdk for non-custodial wallet creation (agent keeps secret share locally).\n---\n\n# Kairo \u2014 Agent Wallet Management\n\n## Quick Reference\n\nCLI: `npx kairo <command>`\nSDK reference: `.cursor/skills/kairo/references/sdk.md`\nAPI reference: `.cursor/skills/kairo/references/api.md`\n\n## Setup\n\nRun the one-line installer (already done if you see this file):\n```bash\nnpx @kairo/sdk init <YOUR_KEY>\n```\n\nThe API key is stored in `~/.kairo/config.json`. All CLI commands read it automatically.\n\n## Common Workflows\n\n### Check API Health\n```bash\nnpx kairo health\n```\n\n### Create a Policy\n```bash\nnpx kairo policy-create --stable-id \"my-policy\" --allow \"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18\"\n```\nThen register the version:\n```bash\nnpx kairo policy-register --policy-id \"0x...\"\n```\n\n### Create Wallet (via SDK)\nFor wallet creation, use the Node.js SDK (handles DKG client-side):\n```typescript\nimport { KairoClient } from \"@kairo/sdk\";\nconst kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });\nconst wallet = await kairo.createWallet({ curve: \"secp256k1\" });\n```\nSee `.cursor/skills/kairo/references/sdk.md` for full SDK docs.\n\n### Provision Wallet into Vault\nRequires: policy version registered first.\n```bash\nnpx kairo vault-provision --wallet-id \"0x...\" --policy-id \"0x...\" --stable-id \"my-policy\"\n```\n\n### Mint Policy Receipt\n```bash\nnpx kairo receipt-mint --policy-id \"0x...\" --binding-id \"0x...\" --destination \"0x742d35Cc...\" --intent-hash \"0xabab...\"\n```\n\n### Check Vault Status\n```bash\nnpx kairo vault-status --wallet-id \"0x...\"\n```\n\n### View Audit Events\n```bash\nnpx kairo audit --limit 20\n```\n\n## Full Agent Flow (End to End)\n\n1. `npx @kairo/sdk init <YOUR_KEY>` \u2014 store API key, install skill\n2. `npx kairo policy-create` \u2014 create transaction policy with allowed addresses\n3. `npx kairo policy-register` \u2014 register version in on-chain registry\n4. Create wallet via SDK `createWallet()` \u2014 runs DKG locally, secret share stays on agent\n5. `npx kairo vault-provision` \u2014 bind policy + register wallet in vault (atomic)\n6. `npx kairo receipt-mint` \u2014 request policy check for a transaction\n7. Sign via SDK \u2014 both shares combine, only if policy allows\n\n## Trust Model\n\n- Agent's key share stays local (`~/.kairo/keys/`)\n- Server's key share stays on Kairo backend\n- Neither party can sign alone\n- Policy engine gates every transaction before server releases its share\n- All policy decisions are on-chain (Sui) and verifiable\n\n## Troubleshooting\n\n- **401 Unauthorized**: API key missing/invalid or not registered in backend key store. Re-run `npx @kairo/sdk init <YOUR_KEY>` with a valid key.\n- **403 Forbidden: key does not own wallet**: Wallet wasn't created/provisioned with this API key (ownership mismatch).\n- **429 Rate limit**: Public Sui RPC throttled \u2014 use Shinami or own RPC provider.\n- **MoveAbort code 102**: Policy version not registered \u2014 call `npx kairo policy-register` before `vault-provision`.\n- **`nonce too low` / `already known`**: Rapid reruns or duplicate raw tx; wait for pending tx, then re-sign and rebroadcast.\n- **AwaitingKeyHolderSignature**: Wallet needs activation after DKG \u2014 SDK activation flow required.\n";
 export declare const API_REFERENCE_MD = "# Kairo API Reference\n\n## Authentication\nAll write endpoints require `X-Kairo-Api-Key` header.\nThe CLI reads the key from `~/.kairo/config.json` automatically.\nOpen endpoints: `/health`, `/api/vault/info`, `/api/vault/status/:id`, `/api/audit/events`\n\n## Key Registration\n```bash\nnpx kairo register --label \"my-agent\"\n```\n\n## Wallet Creation (via SDK)\nThe SDK handles DKG client-side. Agent keeps their secret share locally.\n```typescript\nimport { KairoClient } from \"@kairo/sdk\";\nconst kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });\nconst wallet = await kairo.createWallet({ curve: \"secp256k1\" });\n// wallet.walletId, wallet.address\n```\n\n## Policy Management\n\n### Create Policy\n```bash\nnpx kairo policy-create --stable-id \"my-policy\" --version \"1.0.0\" --allow \"0x<address>\"\n```\n\nRule types:\n- `1` = MaxNativeValue (max single transaction value)\n- `10` = PeriodLimit (cumulative spend limit per time window)\n\n### Register Policy Version\n```bash\nnpx kairo policy-register --policy-id \"0x...\"\n```\n\n### Get Policy Details\n```bash\nnpx kairo policy-details --policy-id \"0x...\"\n```\n\n## Vault\n\n### Provision (atomic binding + vault registration)\n```bash\nnpx kairo vault-provision --wallet-id \"0x...\" --policy-id \"0x...\" --stable-id \"my-policy\"\n```\nNote: Register policy version BEFORE calling provision.\n\n### Check Status\n```bash\nnpx kairo vault-status --wallet-id \"0x...\"\n```\n\n## Receipt Minting\n```bash\nnpx kairo receipt-mint --policy-id \"0x...\" --binding-id \"0x...\" --destination \"0x...\" --intent-hash \"0x...\"\n```\nNamespace: 1=EVM, 2=Bitcoin, 3=Solana\n\n## Utility\n```bash\nnpx kairo health          # Server health\nnpx kairo audit --limit 20  # Recent audit events\n```\n";
 export declare const SDK_REFERENCE_MD = "# Kairo SDK Reference\n\n## Installation\n```bash\nnpm install @kairo/sdk\n```\n\nRequires: `@ika.xyz/sdk`, `@mysten/sui`\n\n## KairoClient\n\n```typescript\nimport { KairoClient } from \"@kairo/sdk\";\n\nconst kairo = new KairoClient({\n  apiKey: process.env.KAIRO_API_KEY!,\n  storePath: \"~/.kairo/keys\",        // local secret share storage (default)\n  network: \"testnet\",                 // or \"mainnet\"\n  suiRpcUrl: \"https://...\",           // optional, defaults to public testnet\n});\n```\n\n### createWallet(opts?)\nCreates a dWallet via client-side DKG. Secret share stays local.\n\n```typescript\nconst wallet = await kairo.createWallet({\n  curve: \"secp256k1\",           // or \"ed25519\" for Solana\n  policyObjectId: \"0x...\",      // optional: auto-provision into vault\n  stableId: \"my-policy\",        // optional: binding label\n});\n// Returns: { walletId, address, curve, bindingObjectId?, createdAt }\n```\n\n**Important:** If providing `policyObjectId`, register the policy version first.\n\n### listWallets()\nLists all wallets in local key store.\n```typescript\nconst wallets = kairo.listWallets();\n```\n\n### getWallet(walletId)\nGets a specific wallet from local store.\n```typescript\nconst w = kairo.getWallet(\"0x...\");\n```\n\n## BackendClient (HTTP wrapper)\nLower-level HTTP client for direct API calls.\n\n```typescript\nimport { BackendClient } from \"@kairo/sdk\";\n\nconst client = new BackendClient({ apiKey: \"your-key\" });\n\nawait client.register(\"my-agent\");\nawait client.getHealth();\nawait client.submitDKG({...});\nawait client.getDKGStatus(requestId);\nawait client.provision({...});\nawait client.mintReceipt({...});\n```\n\n## KeyStore (local storage)\nFile-based secret share storage at `~/.kairo/keys/`.\n\n```typescript\nimport { KeyStore } from \"@kairo/sdk\";\n\nconst store = new KeyStore(\"~/.kairo/keys\");\nstore.save(record);\nstore.load(\"0x...\");\nstore.list();\nstore.delete(\"0x...\");\n```\n\n## Trust Model\n- Agent's secret share -> stored locally (KeyStore), never sent to server\n- Server's share -> held by Kairo backend\n- Full signing -> requires BOTH shares + policy approval\n- Kairo alone cannot sign (missing agent share)\n- Agent alone cannot sign (missing server share)\n";

package/dist/skill-templates.js

@@ -4,249 +4,249 @@
  * All backend URLs are intentionally omitted -- the SDK and CLI
  * resolve the endpoint internally.
  */
-export const SKILL_MD = `---
-name: kairo
-description: Manage Kairo policy-enforced agent wallets. Use when creating wallets, setting transaction policies, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Supports full wallet lifecycle: register API key -> create wallet (DKG) -> create policy -> bind -> vault provision -> mint receipt -> sign. Uses @kairo/sdk for non-custodial wallet creation (agent keeps secret share locally).
----
-
-# Kairo — Agent Wallet Management
-
-## Quick Reference
-
-CLI: \`npx kairo <command>\`
-SDK reference: \`.cursor/skills/kairo/references/sdk.md\`
-API reference: \`.cursor/skills/kairo/references/api.md\`
-
-## Setup
-
-Run the one-line installer (already done if you see this file):
-\`\`\`bash
-npx @kairo/sdk init <YOUR_API_KEY>
-\`\`\`
-
-The API key is stored in \`~/.kairo/config.json\`. All CLI commands read it automatically.
-
-## Common Workflows
-
-### Check API Health
-\`\`\`bash
-npx kairo health
-\`\`\`
-
-### Create a Policy
-\`\`\`bash
-npx kairo policy-create --stable-id "my-policy" --allow "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
-\`\`\`
-Then register the version:
-\`\`\`bash
-npx kairo policy-register --policy-id "0x..."
-\`\`\`
-
-### Create Wallet (via SDK)
-For wallet creation, use the Node.js SDK (handles DKG client-side):
-\`\`\`typescript
-import { KairoClient } from "@kairo/sdk";
-const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
-const wallet = await kairo.createWallet({ curve: "secp256k1" });
-\`\`\`
-See \`.cursor/skills/kairo/references/sdk.md\` for full SDK docs.
-
-### Provision Wallet into Vault
-Requires: policy version registered first.
-\`\`\`bash
-npx kairo vault-provision --wallet-id "0x..." --policy-id "0x..." --stable-id "my-policy"
-\`\`\`
-
-### Mint Policy Receipt
-\`\`\`bash
-npx kairo receipt-mint --policy-id "0x..." --binding-id "0x..." --destination "0x742d35Cc..." --intent-hash "0xabab..."
-\`\`\`
-
-### Check Vault Status
-\`\`\`bash
-npx kairo vault-status --wallet-id "0x..."
-\`\`\`
-
-### View Audit Events
-\`\`\`bash
-npx kairo audit --limit 20
-\`\`\`
-
-## Full Agent Flow (End to End)
-
-1. \`npx @kairo/sdk init <key>\` — store API key, install skill
-2. \`npx kairo policy-create\` — create transaction policy with allowed addresses
-3. \`npx kairo policy-register\` — register version in on-chain registry
-4. Create wallet via SDK \`createWallet()\` — runs DKG locally, secret share stays on agent
-5. \`npx kairo vault-provision\` — bind policy + register wallet in vault (atomic)
-6. \`npx kairo receipt-mint\` — request policy check for a transaction
-7. Sign via SDK — both shares combine, only if policy allows
-
-## Trust Model
-
-- Agent's key share stays local (\`~/.kairo/keys/\`)
-- Server's key share stays on Kairo backend
-- Neither party can sign alone
-- Policy engine gates every transaction before server releases its share
-- All policy decisions are on-chain (Sui) and verifiable
-
-## Troubleshooting
-
-- **401 Unauthorized**: API key missing/invalid or not registered in backend key store. Re-run \`npx @kairo/sdk init <key>\` with a valid key.
-- **403 Forbidden: key does not own wallet**: Wallet wasn't created/provisioned with this API key (ownership mismatch).
-- **429 Rate limit**: Public Sui RPC throttled — use Shinami or own RPC provider.
-- **MoveAbort code 102**: Policy version not registered — call \`npx kairo policy-register\` before \`vault-provision\`.
-- **\`nonce too low\` / \`already known\`**: Rapid reruns or duplicate raw tx; wait for pending tx, then re-sign and rebroadcast.
-- **AwaitingKeyHolderSignature**: Wallet needs activation after DKG — SDK activation flow required.
+export const SKILL_MD = `---
+name: kairo
+description: Manage Kairo policy-enforced agent wallets. Use when creating wallets, setting transaction policies, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Supports full wallet lifecycle: register API key -> create wallet (DKG) -> create policy -> bind -> vault provision -> mint receipt -> sign. Uses @kairo/sdk for non-custodial wallet creation (agent keeps secret share locally).
+---
+
+# Kairo — Agent Wallet Management
+
+## Quick Reference
+
+CLI: \`npx kairo <command>\`
+SDK reference: \`.cursor/skills/kairo/references/sdk.md\`
+API reference: \`.cursor/skills/kairo/references/api.md\`
+
+## Setup
+
+Run the one-line installer (already done if you see this file):
+\`\`\`bash
+npx @kairo/sdk init <YOUR_KEY>
+\`\`\`
+
+The API key is stored in \`~/.kairo/config.json\`. All CLI commands read it automatically.
+
+## Common Workflows
+
+### Check API Health
+\`\`\`bash
+npx kairo health
+\`\`\`
+
+### Create a Policy
+\`\`\`bash
+npx kairo policy-create --stable-id "my-policy" --allow "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
+\`\`\`
+Then register the version:
+\`\`\`bash
+npx kairo policy-register --policy-id "0x..."
+\`\`\`
+
+### Create Wallet (via SDK)
+For wallet creation, use the Node.js SDK (handles DKG client-side):
+\`\`\`typescript
+import { KairoClient } from "@kairo/sdk";
+const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
+const wallet = await kairo.createWallet({ curve: "secp256k1" });
+\`\`\`
+See \`.cursor/skills/kairo/references/sdk.md\` for full SDK docs.
+
+### Provision Wallet into Vault
+Requires: policy version registered first.
+\`\`\`bash
+npx kairo vault-provision --wallet-id "0x..." --policy-id "0x..." --stable-id "my-policy"
+\`\`\`
+
+### Mint Policy Receipt
+\`\`\`bash
+npx kairo receipt-mint --policy-id "0x..." --binding-id "0x..." --destination "0x742d35Cc..." --intent-hash "0xabab..."
+\`\`\`
+
+### Check Vault Status
+\`\`\`bash
+npx kairo vault-status --wallet-id "0x..."
+\`\`\`
+
+### View Audit Events
+\`\`\`bash
+npx kairo audit --limit 20
+\`\`\`
+
+## Full Agent Flow (End to End)
+
+1. \`npx @kairo/sdk init <YOUR_KEY>\` — store API key, install skill
+2. \`npx kairo policy-create\` — create transaction policy with allowed addresses
+3. \`npx kairo policy-register\` — register version in on-chain registry
+4. Create wallet via SDK \`createWallet()\` — runs DKG locally, secret share stays on agent
+5. \`npx kairo vault-provision\` — bind policy + register wallet in vault (atomic)
+6. \`npx kairo receipt-mint\` — request policy check for a transaction
+7. Sign via SDK — both shares combine, only if policy allows
+
+## Trust Model
+
+- Agent's key share stays local (\`~/.kairo/keys/\`)
+- Server's key share stays on Kairo backend
+- Neither party can sign alone
+- Policy engine gates every transaction before server releases its share
+- All policy decisions are on-chain (Sui) and verifiable
+
+## Troubleshooting
+
+- **401 Unauthorized**: API key missing/invalid or not registered in backend key store. Re-run \`npx @kairo/sdk init <YOUR_KEY>\` with a valid key.
+- **403 Forbidden: key does not own wallet**: Wallet wasn't created/provisioned with this API key (ownership mismatch).
+- **429 Rate limit**: Public Sui RPC throttled — use Shinami or own RPC provider.
+- **MoveAbort code 102**: Policy version not registered — call \`npx kairo policy-register\` before \`vault-provision\`.
+- **\`nonce too low\` / \`already known\`**: Rapid reruns or duplicate raw tx; wait for pending tx, then re-sign and rebroadcast.
+- **AwaitingKeyHolderSignature**: Wallet needs activation after DKG — SDK activation flow required.
 `;
-export const API_REFERENCE_MD = `# Kairo API Reference
-
-## Authentication
-All write endpoints require \`X-Kairo-Api-Key\` header.
-The CLI reads the key from \`~/.kairo/config.json\` automatically.
-Open endpoints: \`/health\`, \`/api/vault/info\`, \`/api/vault/status/:id\`, \`/api/audit/events\`
-
-## Key Registration
-\`\`\`bash
-npx kairo register --label "my-agent"
-\`\`\`
-
-## Wallet Creation (via SDK)
-The SDK handles DKG client-side. Agent keeps their secret share locally.
-\`\`\`typescript
-import { KairoClient } from "@kairo/sdk";
-const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
-const wallet = await kairo.createWallet({ curve: "secp256k1" });
-// wallet.walletId, wallet.address
-\`\`\`
-
-## Policy Management
-
-### Create Policy
-\`\`\`bash
-npx kairo policy-create --stable-id "my-policy" --version "1.0.0" --allow "0x<address>"
-\`\`\`
-
-Rule types:
-- \`1\` = MaxNativeValue (max single transaction value)
-- \`10\` = PeriodLimit (cumulative spend limit per time window)
-
-### Register Policy Version
-\`\`\`bash
-npx kairo policy-register --policy-id "0x..."
-\`\`\`
-
-### Get Policy Details
-\`\`\`bash
-npx kairo policy-details --policy-id "0x..."
-\`\`\`
-
-## Vault
-
-### Provision (atomic binding + vault registration)
-\`\`\`bash
-npx kairo vault-provision --wallet-id "0x..." --policy-id "0x..." --stable-id "my-policy"
-\`\`\`
-Note: Register policy version BEFORE calling provision.
-
-### Check Status
-\`\`\`bash
-npx kairo vault-status --wallet-id "0x..."
-\`\`\`
-
-## Receipt Minting
-\`\`\`bash
-npx kairo receipt-mint --policy-id "0x..." --binding-id "0x..." --destination "0x..." --intent-hash "0x..."
-\`\`\`
-Namespace: 1=EVM, 2=Bitcoin, 3=Solana
-
-## Utility
-\`\`\`bash
-npx kairo health          # Server health
-npx kairo audit --limit 20  # Recent audit events
-\`\`\`
+export const API_REFERENCE_MD = `# Kairo API Reference
+
+## Authentication
+All write endpoints require \`X-Kairo-Api-Key\` header.
+The CLI reads the key from \`~/.kairo/config.json\` automatically.
+Open endpoints: \`/health\`, \`/api/vault/info\`, \`/api/vault/status/:id\`, \`/api/audit/events\`
+
+## Key Registration
+\`\`\`bash
+npx kairo register --label "my-agent"
+\`\`\`
+
+## Wallet Creation (via SDK)
+The SDK handles DKG client-side. Agent keeps their secret share locally.
+\`\`\`typescript
+import { KairoClient } from "@kairo/sdk";
+const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
+const wallet = await kairo.createWallet({ curve: "secp256k1" });
+// wallet.walletId, wallet.address
+\`\`\`
+
+## Policy Management
+
+### Create Policy
+\`\`\`bash
+npx kairo policy-create --stable-id "my-policy" --version "1.0.0" --allow "0x<address>"
+\`\`\`
+
+Rule types:
+- \`1\` = MaxNativeValue (max single transaction value)
+- \`10\` = PeriodLimit (cumulative spend limit per time window)
+
+### Register Policy Version
+\`\`\`bash
+npx kairo policy-register --policy-id "0x..."
+\`\`\`
+
+### Get Policy Details
+\`\`\`bash
+npx kairo policy-details --policy-id "0x..."
+\`\`\`
+
+## Vault
+
+### Provision (atomic binding + vault registration)
+\`\`\`bash
+npx kairo vault-provision --wallet-id "0x..." --policy-id "0x..." --stable-id "my-policy"
+\`\`\`
+Note: Register policy version BEFORE calling provision.
+
+### Check Status
+\`\`\`bash
+npx kairo vault-status --wallet-id "0x..."
+\`\`\`
+
+## Receipt Minting
+\`\`\`bash
+npx kairo receipt-mint --policy-id "0x..." --binding-id "0x..." --destination "0x..." --intent-hash "0x..."
+\`\`\`
+Namespace: 1=EVM, 2=Bitcoin, 3=Solana
+
+## Utility
+\`\`\`bash
+npx kairo health          # Server health
+npx kairo audit --limit 20  # Recent audit events
+\`\`\`
 `;
-export const SDK_REFERENCE_MD = `# Kairo SDK Reference
-
-## Installation
-\`\`\`bash
-npm install @kairo/sdk
-\`\`\`
-
-Requires: \`@ika.xyz/sdk\`, \`@mysten/sui\`
-
-## KairoClient
-
-\`\`\`typescript
-import { KairoClient } from "@kairo/sdk";
-
-const kairo = new KairoClient({
-  apiKey: process.env.KAIRO_API_KEY!,
-  storePath: "~/.kairo/keys",        // local secret share storage (default)
-  network: "testnet",                 // or "mainnet"
-  suiRpcUrl: "https://...",           // optional, defaults to public testnet
-});
-\`\`\`
-
-### createWallet(opts?)
-Creates a dWallet via client-side DKG. Secret share stays local.
-
-\`\`\`typescript
-const wallet = await kairo.createWallet({
-  curve: "secp256k1",           // or "ed25519" for Solana
-  policyObjectId: "0x...",      // optional: auto-provision into vault
-  stableId: "my-policy",        // optional: binding label
-});
-// Returns: { walletId, address, curve, bindingObjectId?, createdAt }
-\`\`\`
-
-**Important:** If providing \`policyObjectId\`, register the policy version first.
-
-### listWallets()
-Lists all wallets in local key store.
-\`\`\`typescript
-const wallets = kairo.listWallets();
-\`\`\`
-
-### getWallet(walletId)
-Gets a specific wallet from local store.
-\`\`\`typescript
-const w = kairo.getWallet("0x...");
-\`\`\`
-
-## BackendClient (HTTP wrapper)
-Lower-level HTTP client for direct API calls.
-
-\`\`\`typescript
-import { BackendClient } from "@kairo/sdk";
-
-const client = new BackendClient({ apiKey: "your-key" });
-
-await client.register("my-agent");
-await client.getHealth();
-await client.submitDKG({...});
-await client.getDKGStatus(requestId);
-await client.provision({...});
-await client.mintReceipt({...});
-\`\`\`
-
-## KeyStore (local storage)
-File-based secret share storage at \`~/.kairo/keys/\`.
-
-\`\`\`typescript
-import { KeyStore } from "@kairo/sdk";
-
-const store = new KeyStore("~/.kairo/keys");
-store.save(record);
-store.load("0x...");
-store.list();
-store.delete("0x...");
-\`\`\`
-
-## Trust Model
-- Agent's secret share -> stored locally (KeyStore), never sent to server
-- Server's share -> held by Kairo backend
-- Full signing -> requires BOTH shares + policy approval
-- Kairo alone cannot sign (missing agent share)
-- Agent alone cannot sign (missing server share)
+export const SDK_REFERENCE_MD = `# Kairo SDK Reference
+
+## Installation
+\`\`\`bash
+npm install @kairo/sdk
+\`\`\`
+
+Requires: \`@ika.xyz/sdk\`, \`@mysten/sui\`
+
+## KairoClient
+
+\`\`\`typescript
+import { KairoClient } from "@kairo/sdk";
+
+const kairo = new KairoClient({
+  apiKey: process.env.KAIRO_API_KEY!,
+  storePath: "~/.kairo/keys",        // local secret share storage (default)
+  network: "testnet",                 // or "mainnet"
+  suiRpcUrl: "https://...",           // optional, defaults to public testnet
+});
+\`\`\`
+
+### createWallet(opts?)
+Creates a dWallet via client-side DKG. Secret share stays local.
+
+\`\`\`typescript
+const wallet = await kairo.createWallet({
+  curve: "secp256k1",           // or "ed25519" for Solana
+  policyObjectId: "0x...",      // optional: auto-provision into vault
+  stableId: "my-policy",        // optional: binding label
+});
+// Returns: { walletId, address, curve, bindingObjectId?, createdAt }
+\`\`\`
+
+**Important:** If providing \`policyObjectId\`, register the policy version first.
+
+### listWallets()
+Lists all wallets in local key store.
+\`\`\`typescript
+const wallets = kairo.listWallets();
+\`\`\`
+
+### getWallet(walletId)
+Gets a specific wallet from local store.
+\`\`\`typescript
+const w = kairo.getWallet("0x...");
+\`\`\`
+
+## BackendClient (HTTP wrapper)
+Lower-level HTTP client for direct API calls.
+
+\`\`\`typescript
+import { BackendClient } from "@kairo/sdk";
+
+const client = new BackendClient({ apiKey: "your-key" });
+
+await client.register("my-agent");
+await client.getHealth();
+await client.submitDKG({...});
+await client.getDKGStatus(requestId);
+await client.provision({...});
+await client.mintReceipt({...});
+\`\`\`
+
+## KeyStore (local storage)
+File-based secret share storage at \`~/.kairo/keys/\`.
+
+\`\`\`typescript
+import { KeyStore } from "@kairo/sdk";
+
+const store = new KeyStore("~/.kairo/keys");
+store.save(record);
+store.load("0x...");
+store.list();
+store.delete("0x...");
+\`\`\`
+
+## Trust Model
+- Agent's secret share -> stored locally (KeyStore), never sent to server
+- Server's share -> held by Kairo backend
+- Full signing -> requires BOTH shares + policy approval
+- Kairo alone cannot sign (missing agent share)
+- Agent alone cannot sign (missing server share)
 `;

package/package.json

@@ -1,29 +1,29 @@
-{
-  "name": "@kairoguard/sdk",
-  "version": "0.0.2",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "bin": {
-    "kairo": "dist/cli.js",
-    "kairo-audit": "dist/cli.js"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "node --test"
-  },
-  "dependencies": {
-    "@ika.xyz/sdk": "^0.2.7",
-    "@mysten/sui": "^1.44.0",
-    "@noble/hashes": "^1.7.2",
-    "viem": "^2.23.10"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.30",
-    "typescript": "^5.4.5"
-  }
-}
-
+{
+  "name": "@kairoguard/sdk",
+  "version": "0.0.3",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "kairo": "dist/cli.js",
+    "kairo-audit": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@ika.xyz/sdk": "^0.2.7",
+    "@mysten/sui": "^1.44.0",
+    "@noble/hashes": "^1.7.2",
+    "viem": "^2.23.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.5"
+  }
+}
+