@kairoguard/sdk 0.0.8 → 0.0.10

package/dist/backend.d.ts

@@ -232,6 +232,16 @@ export interface PolicyDetailsResponse {
     policy?: Record<string, unknown>;
     error?: string;
 }
+export interface ReaffirmPolicyBindingParams {
+    bindingObjectId: string;
+    registryObjectId?: string;
+}
+export interface ReaffirmPolicyBindingResponse {
+    success: boolean;
+    digest: string;
+    activeVersionObjectId?: string;
+    error?: string;
+}
 export interface DWalletFullResponse {
     success: boolean;
     dWallet?: unknown;
@@ -273,6 +283,7 @@ export declare class BackendClient {
     getGovernance(governanceId: string): Promise<GovernanceGetResponse>;
     getGovernanceProposal(proposalId: string): Promise<GovernanceProposalGetResponse>;
     getPolicy(policyObjectId: string): Promise<PolicyDetailsResponse>;
+    reaffirmPolicyBinding(params: ReaffirmPolicyBindingParams): Promise<ReaffirmPolicyBindingResponse>;
     getDWalletFull(dWalletId: string): Promise<DWalletFullResponse>;
     getSuiObject(objectId: string): Promise<SuiObjectResponse>;
     policySign(params: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/backend.js

@@ -89,6 +89,9 @@ export class BackendClient {
     async getPolicy(policyObjectId) {
         return this.request("GET", `/api/policies/${policyObjectId}`);
     }
+    async reaffirmPolicyBinding(params) {
+        return this.request("POST", "/api/policy/binding/reaffirm", params);
+    }
     async getDWalletFull(dWalletId) {
         return this.request("GET", `/api/dwallet/full/${dWalletId}`);
     }

package/dist/cli.js

@@ -2,9 +2,12 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { verifyAuditBundle } from "./auditBundle.js";
 import { BackendClient, DEFAULT_BACKEND_URL } from "./backend.js";
 import { KairoClient } from "./client.js";
+import { POLICY_TEMPLATE_PRESETS, buildPolicyTemplatePayload } from "./policy-templates.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");
@@ -39,6 +42,9 @@ function flag(args, name) {
         return undefined;
     return args[idx + 1];
 }
+function hasFlag(args, name) {
+    return args.includes(name);
+}
 function requireFlag(args, name, label) {
     const v = flag(args, name);
     if (!v) {
@@ -47,6 +53,24 @@ function requireFlag(args, name, label) {
     }
     return v;
 }
+async function promptPolicyTemplateId() {
+    const rl = createInterface({ input, output });
+    try {
+        console.log("Choose a default policy template:");
+        console.log(`  1) ${POLICY_TEMPLATE_PRESETS["tpl-1"].label}`);
+        console.log(`  2) ${POLICY_TEMPLATE_PRESETS["tpl-2"].label}`);
+        console.log(`  3) ${POLICY_TEMPLATE_PRESETS["tpl-3"].label}`);
+        const answer = (await rl.question("Template [1/2/3] (default 2): ")).trim();
+        if (answer === "1")
+            return "tpl-1";
+        if (answer === "3")
+            return "tpl-3";
+        return "tpl-2";
+    }
+    finally {
+        rl.close();
+    }
+}
 // ── Commands ────────────────────────────────────────────────────────────────
 async function cmdInit(args) {
     const apiKey = args[0];
@@ -88,17 +112,41 @@ async function cmdWalletCreate(args) {
     }
     const policyId = flag(args, "--policy-id");
     const stableId = flag(args, "--stable-id");
+    const autoProvision = hasFlag(args, "--auto-provision");
     const cfg = requireConfig();
+    let resolvedPolicyId = policyId;
+    if (autoProvision && !resolvedPolicyId) {
+        const templateId = await promptPolicyTemplateId();
+        const templatePayload = buildPolicyTemplatePayload(templateId);
+        const stable = stableId ?? `agent-policy-${Date.now()}`;
+        const client = getClient();
+        const created = await client.createPolicyV4({
+            stableId: stable,
+            version: "1.0.0",
+            allowNamespaces: templatePayload.allowNamespaces,
+            rules: templatePayload.rules,
+        });
+        if (!created.success || !created.policyObjectId?.startsWith("0x")) {
+            throw new Error(created.error ?? "Failed to create default policy from template");
+        }
+        await client.registerPolicyVersionFromPolicy({ policyObjectId: created.policyObjectId });
+        resolvedPolicyId = created.policyObjectId;
+        console.log(`Created + registered policy ${resolvedPolicyId} using ${templatePayload.template.id}.`);
+    }
     const kairo = new KairoClient({
         apiKey: cfg.apiKey,
         backendUrl: cfg.backendUrl,
     });
     const wallet = await kairo.createWallet({
         curve: curveRaw,
-        policyObjectId: policyId,
+        policyObjectId: resolvedPolicyId,
         stableId,
     });
     console.log(JSON.stringify(wallet, null, 2));
+    if (!resolvedPolicyId) {
+        console.log("Wallet created but not provisioned. To show it in dashboard policies, run: " +
+            `kairo vault-provision --wallet-id ${wallet.walletId} --policy-id <policyObjectId> [--stable-id <id>]`);
+    }
 }
 async function cmdRegister(args) {
     const label = requireFlag(args, "--label", "name");
@@ -141,9 +189,23 @@ async function cmdVaultStatus(args) {
 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 });
+    const stableId = flag(args, "--stable-id");
+    const cfg = requireConfig();
+    const kairo = new KairoClient({
+        apiKey: cfg.apiKey,
+        backendUrl: cfg.backendUrl,
+    });
+    const res = await kairo.provision(walletId, policyId, stableId);
+    console.log(JSON.stringify(res, null, 2));
+}
+async function cmdReaffirm(args) {
+    const walletId = requireFlag(args, "--wallet-id", "dwalletId");
+    const cfg = requireConfig();
+    const kairo = new KairoClient({
+        apiKey: cfg.apiKey,
+        backendUrl: cfg.backendUrl,
+    });
+    const res = await kairo.reaffirmBinding(walletId);
     console.log(JSON.stringify(res, null, 2));
 }
 async function cmdReceiptMint(args) {
@@ -204,14 +266,15 @@ Setup:
 
 Wallet & Policy:
   health                            Server health check
-  wallet-create [--curve secp256k1|ed25519] [--policy-id <id>] [--stable-id <id>]
+  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
   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>
+  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>
 
 Utility:
@@ -242,6 +305,8 @@ async function main() {
             return cmdVaultStatus(rest);
         case "vault-provision":
             return cmdVaultProvision(rest);
+        case "reaffirm":
+            return cmdReaffirm(rest);
         case "receipt-mint":
             return cmdReceiptMint(rest);
         case "audit":

package/dist/client.d.ts

@@ -153,6 +153,18 @@ export declare class KairoClient {
     listWallets(): WalletInfo[];
     /** Get a wallet from local key store by ID. */
     getWallet(walletId: string): WalletInfo | null;
+    /**
+     * Provision an existing local wallet into the policy vault.
+     * Persists binding/policy metadata to local keystore.
+     */
+    provision(walletId: string, policyObjectId: string, stableId?: string): Promise<{
+        bindingObjectId: string;
+        digest: string;
+    }>;
+    reaffirmBinding(walletId: string): Promise<{
+        digest: string;
+        activeVersionObjectId?: string;
+    }>;
     /**
      * Governance-first policy update: creates a new policy + version, then proposes
      * a change for approvers. This method does NOT execute/reaffirm directly.
@@ -182,6 +194,8 @@ export declare class KairoClient {
     private pollPresignStatus;
     private pollSignStatus;
     private mintPolicyReceipt;
+    private resolvePolicyVersion;
+    private isReaffirmRequiredError;
     private computeUserSignMessageWithExtensionFallback;
     private rebuildSigningMaterialFromChain;
     private resolveEvmRpcUrl;

package/dist/client.js

@@ -173,13 +173,8 @@ export class KairoClient {
         // 10. Provision into vault (binding + registration) if policy is provided
         let bindingObjectId;
         if (opts?.policyObjectId) {
-            const provisionResult = await this.backend.provision({
-                dwalletObjectId: walletId,
-                policyObjectId: opts.policyObjectId,
-                stableId: opts.stableId ?? `agent-wallet-${walletId.slice(0, 8)}`,
-            });
-            bindingObjectId = provisionResult.bindingObjectId ?? undefined;
-            this.store.save({ ...record, bindingObjectId });
+            const provisionResult = await this.provision(walletId, opts.policyObjectId, opts.stableId);
+            bindingObjectId = provisionResult.bindingObjectId;
         }
         return {
             walletId,
@@ -212,6 +207,56 @@ export class KairoClient {
             createdAt: r.createdAt,
         };
     }
+    /**
+     * Provision an existing local wallet into the policy vault.
+     * Persists binding/policy metadata to local keystore.
+     */
+    async provision(walletId, policyObjectId, stableId) {
+        const wallet = this.requireWalletRecord(walletId);
+        if (!policyObjectId?.startsWith("0x")) {
+            throw new Error("policyObjectId must be a valid 0x object id");
+        }
+        const result = await this.backend.provision({
+            dwalletObjectId: walletId,
+            policyObjectId,
+            stableId: stableId ?? `agent-wallet-${walletId.slice(0, 8)}`,
+        });
+        const bindingObjectId = String(result.bindingObjectId ?? "");
+        if (!bindingObjectId.startsWith("0x")) {
+            throw new Error("Provision succeeded but no bindingObjectId was returned");
+        }
+        this.store.save({
+            ...wallet,
+            bindingObjectId,
+            policyObjectId,
+        });
+        return { bindingObjectId, digest: result.digest };
+    }
+    async reaffirmBinding(walletId) {
+        const wallet = this.requireWalletRecord(walletId);
+        if (!wallet.bindingObjectId?.startsWith("0x")) {
+            throw new Error("Wallet is missing bindingObjectId. Provision the wallet before reaffirming.");
+        }
+        try {
+            const result = await this.backend.reaffirmPolicyBinding({
+                bindingObjectId: wallet.bindingObjectId,
+            });
+            return {
+                digest: result.digest,
+                activeVersionObjectId: result.activeVersionObjectId,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const governedGuardTriggered = /binding is governed/i.test(message) ||
+                /requires governance receipt flow/i.test(message) ||
+                /execute-and-reaffirm/i.test(message);
+            if (governedGuardTriggered) {
+                throw new Error("Binding is governed and cannot be directly reaffirmed. Complete governance execute-and-reaffirm first, then retry signing.");
+            }
+            throw error;
+        }
+    }
     /**
      * Governance-first policy update: creates a new policy + version, then proposes
      * a change for approvers. This method does NOT execute/reaffirm directly.
@@ -398,35 +443,52 @@ export class KairoClient {
             destinationHex: "0x0000000000000000000000000000000000000000",
             nativeValue: 0n,
         };
-        const policyReceiptId = await this.mintPolicyReceipt(wallet, policyContext);
+        const initialPolicyReceiptId = await this.mintPolicyReceipt(wallet, policyContext);
         const dWalletCapId = wallet.dWalletCapId;
         if (!dWalletCapId) {
             throw new Error("Wallet record is missing dWalletCapId. Recreate/provision this wallet before signing.");
         }
-        const req = await this.backend.requestSign({
-            dWalletId: wallet.walletId,
-            dWalletCapId,
-            encryptedUserSecretKeyShareId: wallet.encryptedUserSecretKeyShareId ?? "",
-            userOutputSignature: [],
-            presignId,
-            messageHex: messageHexNoPrefix,
-            userSignMessage: Array.from(userSignMessage),
-            policyReceiptId,
-            policyBindingObjectId: wallet.bindingObjectId,
-            policyObjectId: wallet.policyObjectId,
-            policyVersion: opts?.policyVersion ?? "1.0.0",
-            ethTx: opts?.ethTx,
-        });
-        if (!req.success) {
-            throw new Error(`Failed to request sign for wallet ${walletId}`);
-        }
-        const signStatus = await this.pollSignStatus(req.requestId);
-        return {
-            requestId: req.requestId,
-            signId: signStatus.signId,
-            presignId,
-            signatureHex: ensureHexPrefix(signStatus.signatureHex),
+        if (!presignId) {
+            throw new Error("Missing presignId after presign creation.");
+        }
+        const resolvedPolicyVersion = await this.resolvePolicyVersion(wallet, opts?.policyVersion);
+        const submitAndPoll = async (policyReceiptId) => {
+            const req = await this.backend.requestSign({
+                dWalletId: wallet.walletId,
+                dWalletCapId,
+                encryptedUserSecretKeyShareId: wallet.encryptedUserSecretKeyShareId ?? "",
+                userOutputSignature: [],
+                presignId,
+                messageHex: messageHexNoPrefix,
+                userSignMessage: Array.from(userSignMessage),
+                policyReceiptId,
+                policyBindingObjectId: wallet.bindingObjectId,
+                policyObjectId: wallet.policyObjectId,
+                policyVersion: resolvedPolicyVersion,
+                ethTx: opts?.ethTx,
+            });
+            if (!req.success) {
+                throw new Error(`Failed to request sign for wallet ${walletId}`);
+            }
+            const signStatus = await this.pollSignStatus(req.requestId);
+            return {
+                requestId: req.requestId,
+                signId: signStatus.signId,
+                presignId,
+                signatureHex: ensureHexPrefix(signStatus.signatureHex),
+            };
         };
+        try {
+            return await submitAndPoll(initialPolicyReceiptId);
+        }
+        catch (error) {
+            if (!this.isReaffirmRequiredError(error))
+                throw error;
+            await this.reaffirmBinding(wallet.walletId);
+            // Reaffirm changes active binding version; mint a fresh receipt bound to the new version.
+            const retriedPolicyReceiptId = await this.mintPolicyReceipt(wallet, policyContext);
+            return submitAndPoll(retriedPolicyReceiptId);
+        }
     }
     async signEvm(params) {
         const wallet = this.requireWalletRecord(params.walletId);
@@ -627,7 +689,7 @@ export class KairoClient {
         if (!wallet.policyObjectId || !wallet.bindingObjectId) {
             throw new Error("Wallet is missing policy binding metadata. Ensure it is provisioned with policyObjectId and bindingObjectId.");
         }
-        const response = await this.backend.mintReceipt({
+        const mintOnce = () => this.backend.mintReceipt({
             policyObjectId: wallet.policyObjectId,
             bindingObjectId: wallet.bindingObjectId,
             namespace: ctx.namespace,
@@ -638,6 +700,12 @@ export class KairoClient {
             nativeValueHex: ctx.nativeValue.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)) {
+            await this.reaffirmBinding(wallet.walletId);
+            response = await mintOnce();
+        }
         if (response.success === false) {
             throw new Error(String(response.error ?? "Failed to mint policy receipt"));
         }
@@ -650,6 +718,27 @@ export class KairoClient {
         }
         return receiptId;
     }
+    async resolvePolicyVersion(wallet, override) {
+        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");
+        }
+        const version = decodeMoveString(response.policy.version).trim();
+        if (!version) {
+            throw new Error("Policy version is missing on-chain. Pass policyVersion explicitly.");
+        }
+        return version;
+    }
+    isReaffirmRequiredError(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return /requires confirmation/i.test(message) || /reaffirm/i.test(message);
+    }
     async computeUserSignMessageWithExtensionFallback(wallet, protocolParams, presignBytes, messageBytes) {
         try {
             return await createUserSignMessageWithPublicOutput(protocolParams, new Uint8Array(wallet.userPublicOutput), new Uint8Array(wallet.userSecretKeyShare), presignBytes, messageBytes, Hash.KECCAK256, SignatureAlgorithm.ECDSASecp256k1, Curve.SECP256K1);
@@ -733,6 +822,26 @@ function toBigInt(value) {
         return BigInt(value);
     return value.startsWith("0x") ? BigInt(value) : BigInt(value);
 }
+function decodeMoveString(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && value.every((x) => Number.isInteger(x) && x >= 0 && x <= 255)) {
+        try {
+            return new TextDecoder().decode(Uint8Array.from(value));
+        }
+        catch {
+            return "";
+        }
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        return (decodeMoveString(obj.bytes) ||
+            decodeMoveString(obj.data) ||
+            decodeMoveString(obj.value) ||
+            decodeMoveString(obj.fields));
+    }
+    return "";
+}
 function buildNormalizedEncryptedShare(fields) {
     const { state } = normalizeMoveEnumState(fields.state);
     const candidate = {

package/dist/policy-templates.d.ts

@@ -0,0 +1,16 @@
+export interface PolicyTemplatePreset {
+    id: "tpl-1" | "tpl-2" | "tpl-3";
+    label: string;
+    singleTxUsd: number;
+    dailyLimitUsd: number;
+}
+export declare const POLICY_TEMPLATE_PRESETS: Record<PolicyTemplatePreset["id"], PolicyTemplatePreset>;
+export declare function buildPolicyTemplatePayload(templateId: string): {
+    template: PolicyTemplatePreset;
+    allowNamespaces: number[];
+    rules: Array<{
+        ruleType: number;
+        namespace?: number;
+        params: string;
+    }>;
+};

package/dist/policy-templates.js

@@ -0,0 +1,56 @@
+export const POLICY_TEMPLATE_PRESETS = {
+    "tpl-1": {
+        id: "tpl-1",
+        label: "Conservative ($200/tx, $1k/day)",
+        singleTxUsd: 200,
+        dailyLimitUsd: 1_000,
+    },
+    "tpl-2": {
+        id: "tpl-2",
+        label: "Standard ($2k/tx, $10k/day)",
+        singleTxUsd: 2_000,
+        dailyLimitUsd: 10_000,
+    },
+    "tpl-3": {
+        id: "tpl-3",
+        label: "High-limit ($10k/tx, $50k/day)",
+        singleTxUsd: 10_000,
+        dailyLimitUsd: 50_000,
+    },
+};
+function stripHexPrefix(value) {
+    return value.startsWith("0x") ? value.slice(2) : value;
+}
+function encodeU256(value) {
+    const big = typeof value === "bigint" ? value : BigInt(value);
+    return `0x${big.toString(16).padStart(64, "0")}`;
+}
+function encodeMaxNativeRule(maxNativeBaseUnits) {
+    return encodeU256(maxNativeBaseUnits);
+}
+function encodeDailyPeriodLimitRule(maxDailyBaseUnits) {
+    const periodTypeDaily = 1;
+    return `0x${periodTypeDaily.toString(16).padStart(2, "0")}${stripHexPrefix(encodeU256(maxDailyBaseUnits))}`;
+}
+export function buildPolicyTemplatePayload(templateId) {
+    const template = POLICY_TEMPLATE_PRESETS[templateId] ?? POLICY_TEMPLATE_PRESETS["tpl-2"];
+    const maxNativeBaseUnits = BigInt(Math.round(template.singleTxUsd * 1_000_000));
+    const dailyLimitBaseUnits = BigInt(Math.round(template.dailyLimitUsd * 1_000_000));
+    return {
+        template,
+        // Default to EVM namespace so newly onboarded users can sign EVM txs immediately.
+        allowNamespaces: [1],
+        rules: [
+            {
+                ruleType: 1,
+                namespace: 0,
+                params: encodeMaxNativeRule(maxNativeBaseUnits),
+            },
+            {
+                ruleType: 10,
+                namespace: 0,
+                params: encodeDailyPeriodLimitRule(dailyLimitBaseUnits),
+            },
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairoguard/sdk",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",