@kairoguard/sdk 0.0.12 → 0.0.14

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 API. 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).
+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 API. Supports full wallet lifecycle: register API key → create wallet (DKG) → create policy → bind → vault provision → mint receipt → sign. Uses @kairoguard/sdk for non-custodial wallet creation (agent keeps secret share locally).
 ---
 
 # Kairo — Agent Wallet Management
@@ -44,6 +44,29 @@ console.log(`✅ Wallet created: ${wallet.address}`);
 
 The wallet will be provisioned into the vault when the user connects their agent through the Kairo dashboard onboarding flow.
 
+## API Key Scopes
+
+Kairo uses scoped API keys to separate agent operations from dashboard administration:
+
+- **Agent scope** (default for SDK/CLI): Can create wallets, sign transactions, and mint receipts. Cannot create/modify policies or governance.
+- **Dashboard scope**: Can create policies, manage governance, and provision vaults. These are created through the Kairo dashboard.
+
+When your agent registers an API key via `kairo.ps1 register` or the SDK, it receives an **agent-scoped key**. This is intentional — agents should focus on executing transactions, not managing policy rules. The user creates and binds policies through the dashboard.
+
+**Agent-scoped keys CAN:**
+- Create wallets via DKG
+- Request signatures (with valid policy receipts)
+- Mint policy receipts
+- Query vault status and audit logs
+
+**Agent-scoped keys CANNOT:**
+- Create or modify policies
+- Provision wallets into vaults
+- Create or manage governance
+- Approve policy changes
+
+If your agent receives a **403 Forbidden** response with the message "This action is restricted to the dashboard", it means the operation requires dashboard scope. Guide the user to perform that action through the Kairo dashboard instead.
+
 ## Common Workflows
 
 ### Check API Health
@@ -69,7 +92,7 @@ powershell -File skills/kairo/scripts/kairo.ps1 policy-register -ApiKey $key -Po
 ### Create Wallet (via SDK)
 For wallet creation, use the Node.js SDK (handles DKG client-side):
 ```typescript
-import { KairoClient } from "@kairo/sdk";
+import { KairoClient } from "@kairoguard/sdk";
 const kairo = new KairoClient({ apiKey, backendUrl: "https://api.kairoguard.com" });
 const wallet = await kairo.createWallet({ curve: "secp256k1" });
 ```
@@ -165,8 +188,9 @@ Before running a live demo, verify these in order:
 2. **Backend key persistence is enabled**
    - `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `KAIRO_API_KEYS_TABLE=api_keys`
    - Confirm key hash exists in Supabase `public.api_keys`
-3. **Policy version is registered before provision**
-   - `policy-create` -> `policy-register` -> then `vault-provision`
+3. **Policy and provisioning done through dashboard**
+   - User creates policy through dashboard (agents cannot)
+   - Wallet gets provisioned during dashboard onboarding
 4. **Wallet ownership matches key**
    - Wallet must be created/provisioned using the same API key
 5. **Fund wallet before signing test**

package/dist/backend.d.ts

@@ -59,6 +59,8 @@ export interface ProvisionResponse {
 export interface RegisterKeyRequest {
     label: string;
     email?: string;
+    userId?: string;
+    scope?: "dashboard" | "agent";
 }
 export interface RegisterKeyResponse {
     success: boolean;
@@ -66,6 +68,8 @@ export interface RegisterKeyResponse {
     label: string;
     tier: string;
     createdAt: number;
+    linkedUserId?: string | null;
+    linkedEmail?: string | null;
 }
 export type RequestStatus = "pending" | "processing" | "completed" | "failed";
 export interface PresignRequestParams {
@@ -258,6 +262,29 @@ export interface SuiObjectResponse {
     };
     error?: string;
 }
+/** PolicyBinding info returned by /api/policies/user */
+export interface UserBinding {
+    bindingId: string;
+    dWalletId: string;
+    stableId: string;
+    activeVersionId: string | null;
+    governanceId: string | null;
+    governanceMode: number | null;
+    isGoverned: boolean;
+}
+export interface UserBindingsResponse {
+    success?: boolean;
+    policies: UserBinding[];
+    _debug?: Record<string, unknown>;
+    error?: string;
+}
+/** Response from /api/policy/binding/:id/policy */
+export interface BindingPolicyResponse {
+    success: boolean;
+    bindingId?: string;
+    policyObjectId?: string;
+    error?: string;
+}
 export declare class BackendClient {
     private baseUrl;
     private apiKey;
@@ -266,7 +293,17 @@ export declare class BackendClient {
     getBaseUrl(): string;
     private request;
     getHealth(): Promise<HealthResponse>;
-    register(label: string, email?: string): Promise<RegisterKeyResponse>;
+    register(params: {
+        label: string;
+        email?: string;
+        userId?: string;
+        scope?: "dashboard" | "agent";
+        authToken?: string;
+    }): Promise<RegisterKeyResponse>;
+    /** List policy bindings for the current API key (with wallet ownership). */
+    listUserBindings(): Promise<UserBindingsResponse>;
+    /** Resolve policyObjectId from a bindingObjectId. */
+    getPolicyFromBinding(bindingObjectId: string): Promise<BindingPolicyResponse>;
     submitDKG(data: DKGSubmitRequest): Promise<DKGSubmitResponse>;
     getDKGStatus(requestId: string): Promise<DKGStatusResponse>;
     provision(params: ProvisionRequest): Promise<ProvisionResponse>;

package/dist/backend.js

@@ -18,11 +18,14 @@ export class BackendClient {
     getBaseUrl() {
         return this.baseUrl;
     }
-    async request(method, path, body) {
+    async request(method, path, body, extraHeaders) {
         const headers = { "Content-Type": "application/json" };
         if (this.apiKey) {
             headers["X-Kairo-Api-Key"] = this.apiKey;
         }
+        if (extraHeaders) {
+            Object.assign(headers, extraHeaders);
+        }
         const res = await fetch(`${this.baseUrl}${path}`, {
             method,
             headers,
@@ -38,8 +41,26 @@ export class BackendClient {
     async getHealth() {
         return this.request("GET", "/health");
     }
-    async register(label, email) {
-        return this.request("POST", "/api/keys/register", { label, email });
+    async register(params) {
+        const headers = {};
+        if (params.authToken) {
+            headers.Authorization = `Bearer ${params.authToken}`;
+        }
+        const body = {
+            label: params.label,
+            email: params.email,
+            userId: params.userId,
+            scope: params.scope,
+        };
+        return this.request("POST", "/api/keys/register", body, headers);
+    }
+    /** List policy bindings for the current API key (with wallet ownership). */
+    async listUserBindings() {
+        return this.request("GET", "/api/policies/user");
+    }
+    /** Resolve policyObjectId from a bindingObjectId. */
+    async getPolicyFromBinding(bindingObjectId) {
+        return this.request("GET", `/api/policy/binding/${bindingObjectId}/policy`);
     }
     async submitDKG(data) {
         return this.request("POST", "/api/dkg/submit", data);

package/dist/cli.js

@@ -24,7 +24,7 @@ function loadConfig() {
 function requireConfig() {
     const cfg = loadConfig();
     if (!cfg) {
-        console.error("No Kairo config found. Run: npx @kairo/sdk init <YOUR_KEY>");
+        console.error("No Kairo config found. Run: npx @kairoguard/sdk init <YOUR_KEY>");
         process.exit(1);
     }
     return cfg;
@@ -150,9 +150,22 @@ async function cmdWalletCreate(args) {
 }
 async function cmdRegister(args) {
     const label = requireFlag(args, "--label", "name");
+    const userId = flag(args, "--user-id") ?? process.env.KAIRO_USER_ID;
+    const email = flag(args, "--email");
+    const authToken = flag(args, "--auth-token") ?? process.env.KAIRO_AUTH_TOKEN;
     const client = getClient();
-    const res = await client.register(label);
+    const res = await client.register({
+        label,
+        email,
+        userId,
+        scope: "agent",
+        authToken,
+    });
     console.log(JSON.stringify(res, null, 2));
+    if (!res.linkedUserId) {
+        console.log("Note: key created without user linkage (headless mode). " +
+            "Set --user-id (or KAIRO_USER_ID) or --auth-token (or KAIRO_AUTH_TOKEN) to link this key to a user.");
+    }
 }
 async function cmdPolicyCreate(args) {
     const stableId = requireFlag(args, "--stable-id", "id");
@@ -256,6 +269,19 @@ async function cmdAuditVerify(args) {
     }
     console.log("OK");
 }
+async function cmdSync() {
+    const cfg = requireConfig();
+    const kairo = new KairoClient({
+        apiKey: cfg.apiKey,
+        backendUrl: cfg.backendUrl,
+    });
+    const updated = await kairo.syncWallets();
+    console.log(`Synced local wallet records: ${updated} updated`);
+    const wallets = kairo.listWallets();
+    for (const w of wallets) {
+        console.log(`  ${w.walletId} binding=${w.bindingObjectId ?? "(none)"}`);
+    }
+}
 function printUsage() {
     console.log(`Kairo CLI — Agent Wallet Operations
 
@@ -268,7 +294,9 @@ Wallet & Policy:
   health                            Server health check
   wallet-create [--curve secp256k1|ed25519] [--policy-id <id>] [--stable-id <id>] [--auto-provision]
                                     Create a new dWallet via SDK DKG flow
-  register --label <name>           Register new API key
+  register --label <name> [--user-id <uuid>] [--email <email>] [--auth-token <jwt>]
+                                    Register new API key (agent scope). Prefer linking with user id/jwt.
+  sync                              Sync local wallet metadata from backend (binding/policy IDs)
   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
@@ -276,6 +304,7 @@ Wallet & Policy:
   vault-provision --wallet-id <id> --policy-id <id> [--stable-id <id>]
   reaffirm --wallet-id <id>         Reaffirm a wallet's current policy binding
   receipt-mint --policy-id <id> --binding-id <id> --destination <hex> --intent-hash <hex>
+  sync                              Sync local wallet records with backend binding metadata
 
 Utility:
   audit --limit <n>                 List audit events
@@ -309,10 +338,14 @@ async function main() {
             return cmdReaffirm(rest);
         case "receipt-mint":
             return cmdReceiptMint(rest);
+        case "sync":
+            return cmdSync();
         case "audit":
             if (rest[0] === "verify")
                 return cmdAuditVerify(rest.slice(1));
             return cmdAudit(rest);
+        case "sync":
+            return cmdSync();
         case "--help":
         case "-h":
         case undefined:

package/dist/client.d.ts

@@ -153,6 +153,13 @@ export declare class KairoClient {
     listWallets(): WalletInfo[];
     /** Get a wallet from local key store by ID. */
     getWallet(walletId: string): WalletInfo | null;
+    /**
+     * Sync local wallet metadata from the backend.
+     * Queries /api/policies/user for bindings and updates local records
+     * with bindingObjectId and policyObjectId where available.
+     * Returns count of wallets updated.
+     */
+    syncWallets(): Promise<number>;
     /**
      * Provision an existing local wallet into the policy vault.
      * Persists binding/policy metadata to local keystore.

package/dist/client.js

@@ -14,6 +14,7 @@ import { Curve, fetchProtocolParams, deriveEncryptionKeys, generateSeed, generat
 import { Hash, SignatureAlgorithm, createUserSignMessageWithPublicOutput } from "@ika.xyz/sdk";
 import { computeEvmIntentFromUnsignedTxBytes } from "./evmIntent.js";
 import { keccak256, recoverTransactionAddress, serializeTransaction, } from "viem";
+import { convertWeiToUsdMicros, fetchEthUsdMicros } from "./price.js";
 const FALLBACK_SUI_RPC = "https://fullnode.testnet.sui.io:443";
 async function testRpcEndpoint(url) {
     try {
@@ -207,6 +208,61 @@ export class KairoClient {
             createdAt: r.createdAt,
         };
     }
+    /**
+     * Sync local wallet metadata from the backend.
+     * Queries /api/policies/user for bindings and updates local records
+     * with bindingObjectId and policyObjectId where available.
+     * Returns count of wallets updated.
+     */
+    async syncWallets() {
+        const response = await this.backend.listUserBindings();
+        if (!response.policies?.length)
+            return 0;
+        // Build lookup map by dWalletId (case-insensitive)
+        const bindingsByWallet = new Map();
+        for (const binding of response.policies) {
+            const wid = binding.dWalletId?.toLowerCase();
+            if (!wid)
+                continue;
+            if (!bindingsByWallet.has(wid)) {
+                bindingsByWallet.set(wid, {
+                    bindingId: binding.bindingId,
+                    stableId: binding.stableId,
+                    activeVersionId: binding.activeVersionId,
+                });
+            }
+        }
+        let updated = 0;
+        for (const record of this.store.list()) {
+            const remote = bindingsByWallet.get(record.walletId.toLowerCase());
+            if (!remote)
+                continue;
+            const needsBindingUpdate = !record.bindingObjectId && remote.bindingId?.startsWith("0x");
+            const needsPolicyUpdate = !record.policyObjectId && remote.activeVersionId?.startsWith("0x");
+            if (needsBindingUpdate || needsPolicyUpdate) {
+                let policyObjectId = record.policyObjectId;
+                // If we have activeVersionId but no policyObjectId, resolve it from the binding
+                if (!policyObjectId && remote.activeVersionId) {
+                    try {
+                        const policyRes = await this.backend.getPolicyFromBinding(remote.bindingId);
+                        if (policyRes.success && policyRes.policyObjectId?.startsWith("0x")) {
+                            policyObjectId = policyRes.policyObjectId;
+                        }
+                    }
+                    catch {
+                        // Resolution failed, will remain undefined; caller may need to handle
+                    }
+                }
+                this.store.save({
+                    ...record,
+                    bindingObjectId: record.bindingObjectId ?? remote.bindingId,
+                    policyObjectId,
+                });
+                updated++;
+            }
+        }
+        return updated;
+    }
     /**
      * Provision an existing local wallet into the policy vault.
      * Persists binding/policy metadata to local keystore.
@@ -686,20 +742,41 @@ export class KairoClient {
         throw new Error(`Sign timed out after ${SIGN_POLL_TIMEOUT_MS / 1000}s (requestId: ${requestId})`);
     }
     async mintPolicyReceipt(wallet, ctx) {
+        // If binding metadata is missing, attempt to sync from backend before failing
         if (!wallet.policyObjectId || !wallet.bindingObjectId) {
-            throw new Error("Wallet is missing policy binding metadata. Ensure it is provisioned with policyObjectId and bindingObjectId.");
+            await this.syncWallets();
+            const refreshed = this.store.load(wallet.walletId);
+            if (refreshed) {
+                wallet = refreshed;
+            }
         }
-        const mintOnce = () => this.backend.mintReceipt({
-            policyObjectId: wallet.policyObjectId,
-            bindingObjectId: wallet.bindingObjectId,
-            namespace: ctx.namespace,
-            // chainId is encoded as u64 bytes (16 hex chars)
-            chainId: ctx.chainId.toString(16).padStart(16, "0"),
-            intentHashHex: stripHexPrefix(ctx.intentHashHex),
-            destinationHex: stripHexPrefix(ctx.destinationHex),
-            nativeValueHex: ctx.nativeValue.toString(16).padStart(64, "0"),
-            contextDataHex: ctx.contextDataHex ? stripHexPrefix(ctx.contextDataHex) : undefined,
-        });
+        if (!wallet.policyObjectId || !wallet.bindingObjectId) {
+            throw new Error("Wallet is missing policy binding metadata. Provision the wallet via dashboard or SDK before signing.");
+        }
+        const mintOnce = async () => {
+            let normalizedNativeValue = ctx.nativeValue;
+            // MaxNativeValue rules are encoded in USD-micros; normalize EVM wei inputs.
+            if (ctx.namespace === 1) {
+                try {
+                    const ethUsdMicros = await fetchEthUsdMicros();
+                    normalizedNativeValue = convertWeiToUsdMicros(ctx.nativeValue, ethUsdMicros);
+                }
+                catch {
+                    // Keep raw value as fallback if price feed is unavailable.
+                }
+            }
+            return this.backend.mintReceipt({
+                policyObjectId: wallet.policyObjectId ?? undefined,
+                bindingObjectId: wallet.bindingObjectId,
+                namespace: ctx.namespace,
+                // chainId is encoded as u64 bytes (16 hex chars)
+                chainId: ctx.chainId.toString(16).padStart(16, "0"),
+                intentHashHex: stripHexPrefix(ctx.intentHashHex),
+                destinationHex: stripHexPrefix(ctx.destinationHex),
+                nativeValueHex: normalizedNativeValue.toString(16).padStart(64, "0"),
+                contextDataHex: ctx.contextDataHex ? stripHexPrefix(ctx.contextDataHex) : undefined,
+            });
+        };
         let response = await mintOnce();
         const initialError = String(response?.error ?? "");
         if (response.success === false && this.isReaffirmRequiredError(initialError)) {
@@ -722,18 +799,28 @@ export class KairoClient {
         const explicit = String(override ?? "").trim();
         if (explicit)
             return explicit;
-        if (!wallet.policyObjectId?.startsWith("0x")) {
-            throw new Error("Wallet is missing policyObjectId. Provision the wallet before signing.");
-        }
-        const response = await this.backend.getPolicy(wallet.policyObjectId);
-        if (!response.success || !response.policy) {
-            throw new Error(response.error ?? "Failed to resolve policy details for signing");
+        if (wallet.policyObjectId?.startsWith("0x")) {
+            const response = await this.backend.getPolicy(wallet.policyObjectId);
+            if (response.success && response.policy) {
+                const version = decodeMoveString(response.policy.version).trim();
+                if (version)
+                    return version;
+            }
         }
-        const version = decodeMoveString(response.policy.version).trim();
-        if (!version) {
-            throw new Error("Policy version is missing on-chain. Pass policyVersion explicitly.");
+        // policyObjectId unknown (e.g. provisioned via dashboard); resolve from binding metadata
+        if (wallet.bindingObjectId?.startsWith("0x")) {
+            const bindings = await this.backend.listUserBindings();
+            const match = bindings.policies?.find((b) => b.bindingId?.toLowerCase() === wallet.bindingObjectId.toLowerCase());
+            if (match?.activeVersionId?.startsWith("0x")) {
+                const versionDetails = await this.backend.getPolicy(match.activeVersionId);
+                if (versionDetails.success && versionDetails.policy) {
+                    const version = decodeMoveString(versionDetails.policy.version).trim();
+                    if (version)
+                        return version;
+                }
+            }
         }
-        return version;
+        throw new Error("Could not resolve policy version. Pass policyVersion explicitly or provision via SDK.");
     }
     isReaffirmRequiredError(err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/price.d.ts

@@ -0,0 +1,2 @@
+export declare function fetchEthUsdMicros(): Promise<bigint>;
+export declare function convertWeiToUsdMicros(weiValue: bigint, ethUsdMicros: bigint): bigint;

package/dist/price.js

@@ -0,0 +1,65 @@
+const WEI_PER_ETH = 1000000000000000000n;
+const USD_MICROS_SCALE = 1000000n;
+const CACHE_MS = 60_000;
+let cachedEthUsdMicros = null;
+function parseUsdToMicros(input) {
+    const s = input.trim();
+    if (!s)
+        throw new Error("ETH/USD response is empty");
+    if (!/^\d+(\.\d+)?$/.test(s)) {
+        throw new Error(`Invalid ETH/USD amount: ${s}`);
+    }
+    const [wholeRaw, fracRaw = ""] = s.split(".");
+    const whole = BigInt(wholeRaw);
+    const frac = BigInt((fracRaw + "000000").slice(0, 6));
+    return whole * USD_MICROS_SCALE + frac;
+}
+async function fetchJsonWithTimeout(url, timeoutMs) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const resp = await fetch(url, { signal: ctrl.signal });
+        if (!resp.ok) {
+            throw new Error(`HTTP ${resp.status} from ${url}`);
+        }
+        return await resp.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchEthUsdMicros() {
+    const now = Date.now();
+    if (cachedEthUsdMicros && now - cachedEthUsdMicros.atMs < CACHE_MS) {
+        return cachedEthUsdMicros.value;
+    }
+    const providers = [
+        async () => {
+            const j = await fetchJsonWithTimeout("https://api.coinbase.com/v2/prices/ETH-USD/spot", 7000);
+            const amount = String(j?.data?.amount ?? "").trim();
+            return parseUsdToMicros(amount);
+        },
+        async () => {
+            const j = await fetchJsonWithTimeout("https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd", 7000);
+            const amount = String(j?.ethereum?.usd ?? "").trim();
+            return parseUsdToMicros(amount);
+        },
+    ];
+    let lastErr = null;
+    for (const getPrice of providers) {
+        try {
+            const value = await getPrice();
+            if (value > 0n) {
+                cachedEthUsdMicros = { value, atMs: now };
+                return value;
+            }
+        }
+        catch (error) {
+            lastErr = error;
+        }
+    }
+    throw new Error(`Could not fetch ETH/USD price${lastErr ? `: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}` : ""}`);
+}
+export function convertWeiToUsdMicros(weiValue, ethUsdMicros) {
+    return (weiValue * ethUsdMicros) / WEI_PER_ETH;
+}

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, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Default onboarding is dashboard-first: register API key -> create wallet (DKG) in agent -> dashboard auto-binds/provisions policy. 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### Dashboard-First Onboarding (Recommended)\n1. In dashboard onboarding, create/select policy + governance.\n2. In your agent:\n```bash\nnpx @kairo/sdk init <YOUR_KEY>\n```\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```\n3. Return to dashboard \"Verify Connection\". Dashboard auto-provisions wallet policy binding + vault registration.\n\n### Create a Policy (Advanced / Self-Managed)\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 (Dashboard-First)\n\n1. `npx @kairo/sdk init <YOUR_KEY>` \u2014 store API key, install skill\n2. Create/select policy in dashboard onboarding\n3. Configure governance approvers in dashboard onboarding (optional)\n4. Create wallet via SDK `createWallet()` \u2014 runs DKG locally, secret share stays on agent\n5. Dashboard Verify step auto-provisions wallet with selected policy\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## Advanced: Self-Managed Flow (CLI Heavy)\n\n1. `npx @kairo/sdk init <YOUR_KEY>`\n2. `npx kairo policy-create`\n3. `npx kairo policy-register`\n4. SDK `createWallet()`\n5. `npx kairo vault-provision`\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});\n// Returns: { walletId, address, curve, bindingObjectId?, createdAt }\n```\n\nDashboard-first default: create wallet in agent and let dashboard onboarding handle policy provisioning.\n\nAdvanced optional params are still supported:\n```typescript\nconst wallet = await kairo.createWallet({\n  curve: \"secp256k1\",\n  policyObjectId: \"0x...\",\n  stableId: \"my-policy\",\n});\n```\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";
+export declare const SKILL_MD = "---\nname: kairo\ndescription: Manage Kairo policy-enforced agent wallets. Use when creating wallets, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Default onboarding is dashboard-first: register API key -> create wallet (DKG) in agent -> dashboard auto-binds/provisions policy. Uses @kairoguard/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 @kairoguard/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### Dashboard-First Onboarding (Recommended)\n1. In dashboard onboarding, create/select policy + governance.\n2. In your agent:\n```bash\nnpx @kairoguard/sdk init <YOUR_KEY>\n```\n```typescript\nimport { KairoClient } from \"@kairoguard/sdk\";\nconst kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });\nconst wallet = await kairo.createWallet({ curve: \"secp256k1\" });\n```\n3. Return to dashboard \"Verify Connection\". Dashboard auto-provisions wallet policy binding + vault registration.\n\n### Create a Policy (Advanced / Self-Managed)\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 \"@kairoguard/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 (Dashboard-First)\n\n1. `npx @kairoguard/sdk init <YOUR_KEY>` \u2014 store API key, install skill\n2. Create/select policy in dashboard onboarding\n3. Configure governance approvers in dashboard onboarding (optional)\n4. Create wallet via SDK `createWallet()` \u2014 runs DKG locally, secret share stays on agent\n5. Dashboard Verify step auto-provisions wallet with selected policy\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## Advanced: Self-Managed Flow (CLI Heavy)\n\n1. `npx @kairoguard/sdk init <YOUR_KEY>`\n2. `npx kairo policy-create`\n3. `npx kairo policy-register`\n4. SDK `createWallet()`\n5. `npx kairo vault-provision`\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 @kairoguard/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 \"@kairoguard/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 @kairoguard/sdk\n```\n\nRequires: `@ika.xyz/sdk`, `@mysten/sui`\n\n## KairoClient\n\n```typescript\nimport { KairoClient } from \"@kairoguard/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});\n// Returns: { walletId, address, curve, bindingObjectId?, createdAt }\n```\n\nDashboard-first default: create wallet in agent and let dashboard onboarding handle policy provisioning.\n\nAdvanced optional params are still supported:\n```typescript\nconst wallet = await kairo.createWallet({\n  curve: \"secp256k1\",\n  policyObjectId: \"0x...\",\n  stableId: \"my-policy\",\n});\n```\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 \"@kairoguard/sdk\";\n\nconst client = new BackendClient({ apiKey: \"your-key\" });\n\nawait client.register({ label: \"my-agent\", scope: \"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 \"@kairoguard/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

@@ -6,7 +6,7 @@
  */
 export const SKILL_MD = `---
 name: kairo
-description: Manage Kairo policy-enforced agent wallets. Use when creating wallets, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Default onboarding is dashboard-first: register API key -> create wallet (DKG) in agent -> dashboard auto-binds/provisions policy. Uses @kairo/sdk for non-custodial wallet creation (agent keeps secret share locally).
+description: Manage Kairo policy-enforced agent wallets. Use when creating wallets, checking vault status, minting policy receipts, or signing transactions through the Kairo SDK/CLI. Default onboarding is dashboard-first: register API key -> create wallet (DKG) in agent -> dashboard auto-binds/provisions policy. Uses @kairoguard/sdk for non-custodial wallet creation (agent keeps secret share locally).
 ---
 
 # Kairo — Agent Wallet Management
@@ -21,7 +21,7 @@ API reference: \`.cursor/skills/kairo/references/api.md\`
 
 Run the one-line installer (already done if you see this file):
 \`\`\`bash
-npx @kairo/sdk init <YOUR_KEY>
+npx @kairoguard/sdk init <YOUR_KEY>
 \`\`\`
 
 The API key is stored in \`~/.kairo/config.json\`. All CLI commands read it automatically.
@@ -37,10 +37,10 @@ npx kairo health
 1. In dashboard onboarding, create/select policy + governance.
 2. In your agent:
 \`\`\`bash
-npx @kairo/sdk init <YOUR_KEY>
+npx @kairoguard/sdk init <YOUR_KEY>
 \`\`\`
 \`\`\`typescript
-import { KairoClient } from "@kairo/sdk";
+import { KairoClient } from "@kairoguard/sdk";
 const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
 const wallet = await kairo.createWallet({ curve: "secp256k1" });
 \`\`\`
@@ -58,7 +58,7 @@ 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";
+import { KairoClient } from "@kairoguard/sdk";
 const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
 const wallet = await kairo.createWallet({ curve: "secp256k1" });
 \`\`\`
@@ -87,7 +87,7 @@ npx kairo audit --limit 20
 
 ## Full Agent Flow (Dashboard-First)
 
-1. \`npx @kairo/sdk init <YOUR_KEY>\` — store API key, install skill
+1. \`npx @kairoguard/sdk init <YOUR_KEY>\` — store API key, install skill
 2. Create/select policy in dashboard onboarding
 3. Configure governance approvers in dashboard onboarding (optional)
 4. Create wallet via SDK \`createWallet()\` — runs DKG locally, secret share stays on agent
@@ -97,7 +97,7 @@ npx kairo audit --limit 20
 
 ## Advanced: Self-Managed Flow (CLI Heavy)
 
-1. \`npx @kairo/sdk init <YOUR_KEY>\`
+1. \`npx @kairoguard/sdk init <YOUR_KEY>\`
 2. \`npx kairo policy-create\`
 3. \`npx kairo policy-register\`
 4. SDK \`createWallet()\`
@@ -113,7 +113,7 @@ npx kairo audit --limit 20
 
 ## 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.
+- **401 Unauthorized**: API key missing/invalid or not registered in backend key store. Re-run \`npx @kairoguard/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\`.
@@ -135,7 +135,7 @@ 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";
+import { KairoClient } from "@kairoguard/sdk";
 const kairo = new KairoClient({ apiKey: process.env.KAIRO_API_KEY! });
 const wallet = await kairo.createWallet({ curve: "secp256k1" });
 // wallet.walletId, wallet.address
@@ -191,7 +191,7 @@ export const SDK_REFERENCE_MD = `# Kairo SDK Reference
 
 ## Installation
 \`\`\`bash
-npm install @kairo/sdk
+npm install @kairoguard/sdk
 \`\`\`
 
 Requires: \`@ika.xyz/sdk\`, \`@mysten/sui\`
@@ -199,7 +199,7 @@ Requires: \`@ika.xyz/sdk\`, \`@mysten/sui\`
 ## KairoClient
 
 \`\`\`typescript
-import { KairoClient } from "@kairo/sdk";
+import { KairoClient } from "@kairoguard/sdk";
 
 const kairo = new KairoClient({
   apiKey: process.env.KAIRO_API_KEY!,
@@ -246,11 +246,11 @@ const w = kairo.getWallet("0x...");
 Lower-level HTTP client for direct API calls.
 
 \`\`\`typescript
-import { BackendClient } from "@kairo/sdk";
+import { BackendClient } from "@kairoguard/sdk";
 
 const client = new BackendClient({ apiKey: "your-key" });
 
-await client.register("my-agent");
+await client.register({ label: "my-agent", scope: "agent" });
 await client.getHealth();
 await client.submitDKG({...});
 await client.getDKGStatus(requestId);
@@ -262,7 +262,7 @@ await client.mintReceipt({...});
 File-based secret share storage at \`~/.kairo/keys/\`.
 
 \`\`\`typescript
-import { KeyStore } from "@kairo/sdk";
+import { KeyStore } from "@kairoguard/sdk";
 
 const store = new KeyStore("~/.kairo/keys");
 store.save(record);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairoguard/sdk",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Kairo SDK for multi-chain policy-based transaction signing with dWallet support (EVM, Bitcoin, Solana, Sui)",
   "license": "MIT",
   "author": "Kairo <mehraab@thewidercollective.com>",