@kairoguard/sdk 0.0.1

package/dist/bitcoinIntent.js

@@ -0,0 +1,126 @@
+/**
+ * Bitcoin Intent Utilities
+ *
+ * Client-side helpers for Bitcoin transaction intent hashing and validation.
+ */
+import { sha256 } from "@noble/hashes/sha256";
+/**
+ * Bitcoin script types.
+ */
+export var BitcoinScriptType;
+(function (BitcoinScriptType) {
+    BitcoinScriptType[BitcoinScriptType["P2PKH"] = 0] = "P2PKH";
+    BitcoinScriptType[BitcoinScriptType["P2WPKH"] = 1] = "P2WPKH";
+    BitcoinScriptType[BitcoinScriptType["P2TR"] = 2] = "P2TR";
+})(BitcoinScriptType || (BitcoinScriptType = {}));
+/**
+ * Compute double SHA256 (hash256).
+ */
+export function hash256(data) {
+    return sha256(sha256(data));
+}
+/**
+ * Compute BIP340 tagged hash for Taproot.
+ */
+export function taggedHash(tag, data) {
+    const tagHash = sha256(new TextEncoder().encode(tag));
+    const combined = new Uint8Array(tagHash.length * 2 + data.length);
+    combined.set(tagHash, 0);
+    combined.set(tagHash, tagHash.length);
+    combined.set(data, tagHash.length * 2);
+    return sha256(combined);
+}
+/**
+ * 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("")}`;
+}
+/**
+ * Validate a Bitcoin address format.
+ * This is a basic check - full validation requires network context.
+ */
+export function validateBitcoinAddress(address, network = "mainnet") {
+    // Bech32/Bech32m addresses
+    if (network === "mainnet") {
+        if (address.startsWith("bc1q") || address.startsWith("bc1p")) {
+            return address.length >= 42 && address.length <= 62;
+        }
+        // Legacy P2PKH
+        if (address.startsWith("1") || address.startsWith("3")) {
+            return address.length >= 26 && address.length <= 35;
+        }
+    }
+    else {
+        // Testnet/Signet
+        if (address.startsWith("tb1q") || address.startsWith("tb1p")) {
+            return address.length >= 42 && address.length <= 62;
+        }
+        if (address.startsWith("m") || address.startsWith("n") || address.startsWith("2")) {
+            return address.length >= 26 && address.length <= 35;
+        }
+    }
+    return false;
+}
+/**
+ * Detect script type from address format.
+ */
+export function detectScriptTypeFromAddress(address) {
+    // Taproot (bech32m)
+    if (address.startsWith("bc1p") || address.startsWith("tb1p")) {
+        return BitcoinScriptType.P2TR;
+    }
+    // Native SegWit (bech32)
+    if (address.startsWith("bc1q") || address.startsWith("tb1q")) {
+        return BitcoinScriptType.P2WPKH;
+    }
+    // Legacy (base58check)
+    return BitcoinScriptType.P2PKH;
+}
+/**
+ * Compute total input value from parsed PSBT.
+ */
+export function computeTotalInputValue(psbt) {
+    return psbt.inputs.reduce((sum, input) => sum + input.value, 0n);
+}
+/**
+ * Compute total output value from parsed PSBT.
+ */
+export function computeTotalOutputValue(psbt) {
+    return psbt.outputs.reduce((sum, output) => sum + output.value, 0n);
+}
+/**
+ * Compute fee from parsed PSBT.
+ */
+export function computeFee(psbt) {
+    const totalIn = computeTotalInputValue(psbt);
+    const totalOut = computeTotalOutputValue(psbt);
+    return totalIn - totalOut;
+}
+/**
+ * Format satoshis as BTC string.
+ */
+export function satoshisToBTC(satoshis) {
+    const btc = Number(satoshis) / 100_000_000;
+    return btc.toFixed(8);
+}
+/**
+ * Parse BTC string to satoshis.
+ */
+export function btcToSatoshis(btc) {
+    const value = typeof btc === "string" ? parseFloat(btc) : btc;
+    return BigInt(Math.round(value * 100_000_000));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { verifyAuditBundle } from "./auditBundle.js";
+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");
+function loadConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return null;
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function requireConfig() {
+    const cfg = loadConfig();
+    if (!cfg) {
+        console.error("No Kairo config found. Run: npx @kairo/sdk init <api-key>");
+        process.exit(1);
+    }
+    return cfg;
+}
+function getClient(apiKeyOverride) {
+    const key = apiKeyOverride ?? requireConfig().apiKey;
+    return new BackendClient({ apiKey: key });
+}
+// ── Arg helpers ─────────────────────────────────────────────────────────────
+function flag(args, name) {
+    const idx = args.indexOf(name);
+    if (idx < 0)
+        return undefined;
+    return args[idx + 1];
+}
+function requireFlag(args, name, label) {
+    const v = flag(args, name);
+    if (!v) {
+        console.error(`Required: ${name} <${label}>`);
+        process.exit(1);
+    }
+    return v;
+}
+// ── Commands ────────────────────────────────────────────────────────────────
+async function cmdInit(args) {
+    const apiKey = args[0];
+    if (!apiKey) {
+        console.error("Usage: kairo init <api-key>");
+        process.exit(1);
+    }
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify({ apiKey }, null, 2) + "\n", "utf8");
+    console.log(`  Config written to ${CONFIG_PATH}`);
+    const skillDir = join(process.cwd(), ".cursor", "skills", "kairo");
+    const refsDir = join(skillDir, "references");
+    mkdirSync(refsDir, { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), SKILL_MD, "utf8");
+    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 });
+    try {
+        await client.getHealth();
+        console.log("  Backend connection verified.");
+    }
+    catch {
+        console.log("  Warning: could not reach backend (check your network).");
+    }
+    console.log("\nKairo is ready. Your AI agent can now read the skill at .cursor/skills/kairo/SKILL.md");
+}
+async function cmdHealth() {
+    const client = getClient();
+    const res = await client.getHealth();
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdRegister(args) {
+    const label = requireFlag(args, "--label", "name");
+    const client = getClient();
+    const res = await client.register(label);
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdPolicyCreate(args) {
+    const stableId = requireFlag(args, "--stable-id", "id");
+    const version = flag(args, "--version") ?? "1.0.0";
+    const allowRaw = flag(args, "--allow");
+    if (!allowRaw) {
+        console.error("Required: --allow <comma-separated addresses>");
+        process.exit(1);
+    }
+    const addresses = allowRaw.split(",").map((a) => a.trim());
+    const rules = addresses.map((addr) => ({ ruleType: 1, params: addr }));
+    const client = getClient();
+    const res = await client.createPolicyV4({ stableId, version, rules });
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdPolicyRegister(args) {
+    const policyId = requireFlag(args, "--policy-id", "objectId");
+    const client = getClient();
+    const res = await client.registerPolicyVersionFromPolicy({ policyObjectId: policyId });
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdPolicyDetails(args) {
+    const policyId = requireFlag(args, "--policy-id", "objectId");
+    const client = getClient();
+    const res = await client.getPolicy(policyId);
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdVaultStatus(args) {
+    const walletId = requireFlag(args, "--wallet-id", "dwalletId");
+    const client = getClient();
+    const res = await client.getVaultStatus(walletId);
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdVaultProvision(args) {
+    const walletId = requireFlag(args, "--wallet-id", "dwalletId");
+    const policyId = requireFlag(args, "--policy-id", "objectId");
+    const stableId = requireFlag(args, "--stable-id", "id");
+    const client = getClient();
+    const res = await client.provision({ dwalletObjectId: walletId, policyObjectId: policyId, stableId });
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdReceiptMint(args) {
+    const policyId = requireFlag(args, "--policy-id", "objectId");
+    const bindingId = requireFlag(args, "--binding-id", "objectId");
+    const destination = requireFlag(args, "--destination", "hex");
+    const intentHash = requireFlag(args, "--intent-hash", "hex");
+    const namespace = Number(flag(args, "--namespace") ?? "1");
+    const chainId = flag(args, "--chain-id") ?? "0x0aa36a7f";
+    const nativeValue = flag(args, "--native-value") ?? ("0x" + "00".repeat(32));
+    const client = getClient();
+    const res = await client.mintReceipt({
+        policyObjectId: policyId,
+        bindingObjectId: bindingId,
+        namespace,
+        chainId,
+        intentHashHex: intentHash,
+        destinationHex: destination,
+        nativeValueHex: nativeValue,
+    });
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdAudit(args) {
+    const limit = Number(flag(args, "--limit") ?? "10");
+    const client = getClient();
+    const res = await client.getAuditEvents(limit);
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdAuditVerify(args) {
+    const suiIdx = args.indexOf("--sui");
+    const bundleIdx = args.indexOf("--bundle");
+    if (suiIdx < 0 || bundleIdx < 0) {
+        console.error("Usage: kairo audit verify --sui <suiRpcUrl> --bundle <path.json>");
+        process.exit(2);
+    }
+    const suiRpcUrl = String(args[suiIdx + 1] ?? "").trim();
+    const bundlePath = String(args[bundleIdx + 1] ?? "").trim();
+    if (!suiRpcUrl || !bundlePath) {
+        console.error("Usage: kairo audit verify --sui <suiRpcUrl> --bundle <path.json>");
+        process.exit(2);
+    }
+    const raw = readFileSync(bundlePath, "utf8");
+    const bundle = JSON.parse(raw);
+    const res = await verifyAuditBundle({ suiRpcUrl, bundle });
+    if (!res.ok) {
+        console.error(res.error);
+        process.exit(1);
+    }
+    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
+  audit verify --sui <url> --bundle <path>  Verify audit bundle`);
+}
+// ── Main ────────────────────────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    const rest = args.slice(1);
+    switch (cmd) {
+        case "init":
+            return cmdInit(rest);
+        case "health":
+            return cmdHealth();
+        case "register":
+            return cmdRegister(rest);
+        case "policy-create":
+            return cmdPolicyCreate(rest);
+        case "policy-register":
+            return cmdPolicyRegister(rest);
+        case "policy-details":
+            return cmdPolicyDetails(rest);
+        case "vault-status":
+            return cmdVaultStatus(rest);
+        case "vault-provision":
+            return cmdVaultProvision(rest);
+        case "receipt-mint":
+            return cmdReceiptMint(rest);
+        case "audit":
+            if (rest[0] === "verify")
+                return cmdAuditVerify(rest.slice(1));
+            return cmdAudit(rest);
+        case "--help":
+        case "-h":
+        case undefined:
+            printUsage();
+            return;
+        default:
+            console.error(`Unknown command: ${cmd}`);
+            printUsage();
+            process.exit(1);
+    }
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,186 @@
+/**
+ * KairoClient -- the main entry point for agents.
+ *
+ * Usage:
+ *   const kairo = new KairoClient({
+ *     apiKey: "ka_abc123...",
+ *   });
+ *   const wallet = await kairo.createWallet();
+ *   // { walletId: "0xabc...", address: "0x742d...", curve: "secp256k1" }
+ */
+import { type GovernanceProposalInfo } from "./backend.js";
+import { type SupportedCurve } from "./ika-protocol.js";
+import type { Hex } from "./types.js";
+export interface KairoClientOpts {
+    apiKey: string;
+    /** Kairo backend URL. Defaults to production if omitted. */
+    backendUrl?: string;
+    /** Local directory for secret share storage. Defaults to ~/.kairo/keys */
+    storePath?: string;
+    /** Sui RPC URL for fetching Ika protocol params. Defaults to public testnet. */
+    suiRpcUrl?: string;
+    /** Sui network. Defaults to "testnet". */
+    network?: "testnet" | "mainnet";
+    /** Optional chainId -> EVM RPC URL mapping used by signEvm/broadcast/getBalance. */
+    evmRpcUrls?: Record<number, string>;
+}
+export interface CreateWalletOpts {
+    /** Key curve. Defaults to "secp256k1" (Ethereum). */
+    curve?: SupportedCurve;
+    /** Policy object ID to bind during provisioning. */
+    policyObjectId?: string;
+    /** Human-readable label for the binding (derived from policy if omitted). */
+    stableId?: string;
+}
+export interface WalletInfo {
+    walletId: string;
+    address: string;
+    curve: string;
+    bindingObjectId?: string;
+    createdAt: number;
+}
+export interface PresignResult {
+    requestId: string;
+    presignId: string;
+    presignBytes: Uint8Array;
+}
+export interface SignResult {
+    requestId: string;
+    signId?: string;
+    presignId: string;
+    signatureHex: Hex;
+}
+export interface SignEvmParams {
+    walletId: string;
+    to: Hex;
+    value: bigint | number | string;
+    chainId: number;
+    data?: Hex;
+    rpcUrl?: string;
+}
+export interface ProposePolicyUpdateParams {
+    walletId: string;
+    governanceId: string;
+    stableId: string;
+    version: string;
+    expiresAtMs?: number;
+    allowNamespaces?: number[];
+    allowChainIds?: Array<{
+        namespace: number;
+        chainId: string;
+    }>;
+    allowDestinations?: string[];
+    denyDestinations?: string[];
+    rules: Array<{
+        ruleType: number;
+        namespace?: number;
+        params: string;
+    }>;
+    registryObjectId?: string;
+    note?: string;
+}
+export interface PolicyUpdateProposalResult {
+    walletId: string;
+    governanceId: string;
+    bindingObjectId: string;
+    policyObjectId: string;
+    policyVersionObjectId: string;
+    proposalId: string;
+    policyDigest: string;
+    registerDigest: string;
+    proposalDigest: string;
+}
+export interface ApprovePolicyUpdateParams {
+    governanceId: string;
+    proposalId: string;
+}
+export interface ExecutePolicyUpdateParams {
+    walletId: string;
+    governanceId: string;
+    proposalId: string;
+}
+export interface PolicyUpdateStatus {
+    proposal: GovernanceProposalInfo;
+    threshold?: number;
+    timelockDurationMs?: number;
+    approvalsCollected: number;
+    approvalsNeeded?: number;
+    state: "awaiting_approvals" | "awaiting_timelock" | "ready_to_execute" | "executed" | "cancelled";
+}
+interface SignPolicyContext {
+    namespace: number;
+    chainId: number;
+    intentHashHex: Hex;
+    destinationHex: Hex;
+    nativeValue: bigint;
+    contextDataHex?: Hex;
+}
+interface SignOpts {
+    presignId?: string;
+    presignBytes?: Uint8Array;
+    policyContext?: SignPolicyContext;
+    ethTx?: {
+        to: string;
+        value: string;
+        nonce: number;
+        gasLimit: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+        chainId: number;
+        from: string;
+    };
+    policyVersion?: string;
+}
+export declare class KairoClient {
+    private backend;
+    private store;
+    private suiRpcUrl;
+    private network;
+    private evmRpcUrls;
+    constructor(opts: KairoClientOpts);
+    /**
+     * Create a new dWallet. Runs DKG on the agent's machine, submits to backend,
+     * and optionally provisions the wallet in the vault.
+     *
+     * The agent's secret share is stored locally and never sent to the server.
+     */
+    createWallet(opts?: CreateWalletOpts): Promise<WalletInfo>;
+    /** List all wallets in local key store. */
+    listWallets(): WalletInfo[];
+    /** Get a wallet from local key store by ID. */
+    getWallet(walletId: string): WalletInfo | null;
+    /**
+     * Governance-first policy update: creates a new policy + version, then proposes
+     * a change for approvers. This method does NOT execute/reaffirm directly.
+     */
+    updatePolicy(params: ProposePolicyUpdateParams): Promise<PolicyUpdateProposalResult>;
+    /**
+     * Create and register a new policy version, then create governance proposal.
+     * This is the safe default for agents so policy changes require approvers.
+     */
+    proposePolicyUpdate(params: ProposePolicyUpdateParams): Promise<PolicyUpdateProposalResult>;
+    approvePolicyUpdate(params: ApprovePolicyUpdateParams): Promise<{
+        digest: string;
+    }>;
+    executePolicyUpdate(params: ExecutePolicyUpdateParams): Promise<{
+        digest: string;
+    }>;
+    getPolicyUpdateStatus(proposalId: string): Promise<PolicyUpdateStatus>;
+    getPolicy(walletId: string): Promise<Record<string, unknown>>;
+    createPresign(walletId: string): Promise<PresignResult>;
+    sign(walletId: string, messageHex: string, opts?: SignOpts): Promise<SignResult>;
+    signEvm(params: SignEvmParams): Promise<Hex>;
+    broadcastEvm(signedTx: Hex, rpcUrl: string): Promise<Hex>;
+    getBalance(address: Hex, rpcUrl: string): Promise<bigint>;
+    private activateWallet;
+    private pollDKGStatus;
+    private requireWalletRecord;
+    private pollPresignStatus;
+    private pollSignStatus;
+    private mintPolicyReceipt;
+    private computeUserSignMessageWithExtensionFallback;
+    private rebuildSigningMaterialFromChain;
+    private resolveEvmRpcUrl;
+    private evmRpcCall;
+}
+export {};