@kairoguard/sdk 0.0.1

package/dist/skill-templates.js

@@ -0,0 +1,252 @@
+/**
+ * Embedded skill file templates shipped with the SDK.
+ * Generated by `kairo init` into .cursor/skills/kairo/.
+ * 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 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)
+`;

package/dist/solanaIntent.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Solana Intent Utilities
+ *
+ * Client-side helpers for Solana transaction intent hashing and validation.
+ */
+import type { Hex } from "./types.js";
+/**
+ * Solana cluster types.
+ */
+export type SolanaCluster = "mainnet-beta" | "devnet" | "testnet";
+/**
+ * Lamports per SOL.
+ */
+export declare const LAMPORTS_PER_SOL = 1000000000n;
+/**
+ * Parsed Solana instruction.
+ */
+export interface ParsedInstruction {
+    programId: string;
+    accounts: string[];
+    data: Uint8Array;
+}
+/**
+ * Parsed Solana transaction.
+ */
+export interface ParsedSolanaTransaction {
+    feePayer: string;
+    recentBlockhash: string;
+    instructions: ParsedInstruction[];
+    programIds: string[];
+}
+/**
+ * Solana intent for policy verification.
+ */
+export interface SolanaIntent {
+    cluster: SolanaCluster;
+    /** 32-byte intent hash (message hash) */
+    intentHash: Hex;
+    /** Fee payer (signer) */
+    feePayer: string;
+    /** Destination addresses (extracted from transfer instructions) */
+    destinations: string[];
+    /** Amounts in lamports */
+    amounts: bigint[];
+    /** Program IDs involved */
+    programIds: string[];
+    /** Raw transaction bytes (base58) */
+    transactionBase58: string;
+}
+/**
+ * Common Solana program IDs.
+ */
+export declare const PROGRAM_IDS: {
+    readonly SYSTEM: "11111111111111111111111111111111";
+    readonly TOKEN: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+    readonly TOKEN_2022: "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+    readonly ASSOCIATED_TOKEN: "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+    readonly MEMO: "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+    readonly COMPUTE_BUDGET: "ComputeBudget111111111111111111111111111111";
+};
+/**
+ * System instruction types.
+ */
+export declare enum SystemInstructionType {
+    CreateAccount = 0,
+    Assign = 1,
+    Transfer = 2,
+    CreateAccountWithSeed = 3,
+    AdvanceNonceAccount = 4,
+    WithdrawNonceAccount = 5,
+    InitializeNonceAccount = 6,
+    AuthorizeNonceAccount = 7,
+    Allocate = 8,
+    AllocateWithSeed = 9,
+    AssignWithSeed = 10,
+    TransferWithSeed = 11
+}
+/**
+ * Convert hex string to bytes.
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert bytes to hex string.
+ */
+export declare function bytesToHex(bytes: Uint8Array): Hex;
+/**
+ * Decode base58 string to bytes.
+ */
+export declare function base58Decode(str: string): Uint8Array;
+/**
+ * Encode bytes to base58.
+ */
+export declare function base58Encode(data: Uint8Array): string;
+/**
+ * Validate a Solana address (base58 encoded Ed25519 public key).
+ */
+export declare function validateSolanaAddress(address: string): boolean;
+/**
+ * Compute intent hash from transaction message bytes.
+ */
+export declare function computeSolanaIntentHash(messageBytes: Uint8Array): Uint8Array;
+/**
+ * Check if a program ID is a known safe program.
+ */
+export declare function isKnownSafeProgram(programId: string): boolean;
+/**
+ * Check if a program ID is a token program.
+ */
+export declare function isTokenProgram(programId: string): boolean;
+/**
+ * Get human-readable name for a program.
+ */
+export declare function getProgramName(programId: string): string;
+/**
+ * Format lamports as SOL string.
+ */
+export declare function lamportsToSOL(lamports: bigint): string;
+/**
+ * Parse SOL string to lamports.
+ */
+export declare function solToLamports(sol: string | number): bigint;
+/**
+ * Extract transfer destinations and amounts from System Program instructions.
+ */
+export declare function extractSystemTransfers(instructions: ParsedInstruction[]): {
+    destinations: string[];
+    amounts: bigint[];
+};

package/dist/solanaIntent.js

@@ -0,0 +1,214 @@
+/**
+ * Solana Intent Utilities
+ *
+ * Client-side helpers for Solana transaction intent hashing and validation.
+ */
+import { sha256 } from "@noble/hashes/sha256";
+/**
+ * Lamports per SOL.
+ */
+export const LAMPORTS_PER_SOL = 1000000000n;
+/**
+ * Common Solana program IDs.
+ */
+export const PROGRAM_IDS = {
+    SYSTEM: "11111111111111111111111111111111",
+    TOKEN: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+    TOKEN_2022: "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
+    ASSOCIATED_TOKEN: "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+    MEMO: "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
+    COMPUTE_BUDGET: "ComputeBudget111111111111111111111111111111",
+};
+/**
+ * System instruction types.
+ */
+export var SystemInstructionType;
+(function (SystemInstructionType) {
+    SystemInstructionType[SystemInstructionType["CreateAccount"] = 0] = "CreateAccount";
+    SystemInstructionType[SystemInstructionType["Assign"] = 1] = "Assign";
+    SystemInstructionType[SystemInstructionType["Transfer"] = 2] = "Transfer";
+    SystemInstructionType[SystemInstructionType["CreateAccountWithSeed"] = 3] = "CreateAccountWithSeed";
+    SystemInstructionType[SystemInstructionType["AdvanceNonceAccount"] = 4] = "AdvanceNonceAccount";
+    SystemInstructionType[SystemInstructionType["WithdrawNonceAccount"] = 5] = "WithdrawNonceAccount";
+    SystemInstructionType[SystemInstructionType["InitializeNonceAccount"] = 6] = "InitializeNonceAccount";
+    SystemInstructionType[SystemInstructionType["AuthorizeNonceAccount"] = 7] = "AuthorizeNonceAccount";
+    SystemInstructionType[SystemInstructionType["Allocate"] = 8] = "Allocate";
+    SystemInstructionType[SystemInstructionType["AllocateWithSeed"] = 9] = "AllocateWithSeed";
+    SystemInstructionType[SystemInstructionType["AssignWithSeed"] = 10] = "AssignWithSeed";
+    SystemInstructionType[SystemInstructionType["TransferWithSeed"] = 11] = "TransferWithSeed";
+})(SystemInstructionType || (SystemInstructionType = {}));
+/**
+ * Convert hex string to bytes.
+ */
+export function hexToBytes(hex) {
+    const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(cleanHex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Convert bytes to hex string.
+ */
+export function bytesToHex(bytes) {
+    return `0x${Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+/**
+ * Base58 alphabet (Bitcoin/Solana variant).
+ */
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/**
+ * Decode base58 string to bytes.
+ */
+export function base58Decode(str) {
+    const bytes = [];
+    for (const char of str) {
+        const index = BASE58_ALPHABET.indexOf(char);
+        if (index === -1)
+            throw new Error(`Invalid base58 character: ${char}`);
+        let carry = index;
+        for (let i = 0; i < bytes.length; i++) {
+            carry += bytes[i] * 58;
+            bytes[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    for (const char of str) {
+        if (char !== "1")
+            break;
+        bytes.push(0);
+    }
+    return Uint8Array.from(bytes.reverse());
+}
+/**
+ * Encode bytes to base58.
+ */
+export function base58Encode(data) {
+    const digits = [0];
+    for (const byte of data) {
+        let carry = byte;
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = Math.floor(carry / 58);
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = Math.floor(carry / 58);
+        }
+    }
+    let result = "";
+    for (const byte of data) {
+        if (byte !== 0)
+            break;
+        result += "1";
+    }
+    for (let i = digits.length - 1; i >= 0; i--) {
+        result += BASE58_ALPHABET[digits[i]];
+    }
+    return result;
+}
+/**
+ * Validate a Solana address (base58 encoded Ed25519 public key).
+ */
+export function validateSolanaAddress(address) {
+    try {
+        const decoded = base58Decode(address);
+        return decoded.length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compute intent hash from transaction message bytes.
+ */
+export function computeSolanaIntentHash(messageBytes) {
+    return sha256(messageBytes);
+}
+/**
+ * Check if a program ID is a known safe program.
+ */
+export function isKnownSafeProgram(programId) {
+    return (programId === PROGRAM_IDS.SYSTEM ||
+        programId === PROGRAM_IDS.MEMO ||
+        programId === PROGRAM_IDS.COMPUTE_BUDGET);
+}
+/**
+ * Check if a program ID is a token program.
+ */
+export function isTokenProgram(programId) {
+    return (programId === PROGRAM_IDS.TOKEN ||
+        programId === PROGRAM_IDS.TOKEN_2022 ||
+        programId === PROGRAM_IDS.ASSOCIATED_TOKEN);
+}
+/**
+ * Get human-readable name for a program.
+ */
+export function getProgramName(programId) {
+    switch (programId) {
+        case PROGRAM_IDS.SYSTEM:
+            return "System Program";
+        case PROGRAM_IDS.TOKEN:
+            return "Token Program";
+        case PROGRAM_IDS.TOKEN_2022:
+            return "Token 2022 Program";
+        case PROGRAM_IDS.ASSOCIATED_TOKEN:
+            return "Associated Token Program";
+        case PROGRAM_IDS.MEMO:
+            return "Memo Program";
+        case PROGRAM_IDS.COMPUTE_BUDGET:
+            return "Compute Budget Program";
+        default:
+            return `Unknown (${programId.slice(0, 8)}...)`;
+    }
+}
+/**
+ * Format lamports as SOL string.
+ */
+export function lamportsToSOL(lamports) {
+    const sol = Number(lamports) / Number(LAMPORTS_PER_SOL);
+    return sol.toFixed(9);
+}
+/**
+ * Parse SOL string to lamports.
+ */
+export function solToLamports(sol) {
+    const value = typeof sol === "string" ? parseFloat(sol) : sol;
+    return BigInt(Math.round(value * Number(LAMPORTS_PER_SOL)));
+}
+/**
+ * Extract transfer destinations and amounts from System Program instructions.
+ */
+export function extractSystemTransfers(instructions) {
+    const destinations = [];
+    const amounts = [];
+    for (const ix of instructions) {
+        if (ix.programId !== PROGRAM_IDS.SYSTEM)
+            continue;
+        if (ix.data.length < 12)
+            continue;
+        // Check instruction type (first 4 bytes, little-endian)
+        const instructionType = ix.data[0] | (ix.data[1] << 8) | (ix.data[2] << 16) | (ix.data[3] << 24);
+        if (instructionType === SystemInstructionType.Transfer) {
+            // Next 8 bytes are lamports (little-endian u64)
+            let lamports = 0n;
+            for (let i = 0; i < 8; i++) {
+                lamports |= BigInt(ix.data[4 + i]) << BigInt(i * 8);
+            }
+            // Destination is the second account
+            if (ix.accounts.length >= 2) {
+                destinations.push(ix.accounts[1]);
+                amounts.push(lamports);
+            }
+        }
+    }
+    return { destinations, amounts };
+}

package/dist/suiCustody.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Verify a custody event hash by recomputing the canonical BCS encoding (v2/v3 hashing).
+ *
+ * Note: This does NOT discover events. You must provide a specific `CustodyEvent` object id.
+ */
+export declare function fetchAndVerifyCustodyEvent(args: {
+    suiRpcUrl: string;
+    custodyEventObjectId: string;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;