@kairoguard/sdk 0.0.1

package/README.md

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

package/dist/auditBundle.d.ts

@@ -0,0 +1,28 @@
+import type { Hex } from "./types";
+export type AuditBundle = {
+    v: 1;
+    network: "testnet" | "mainnet";
+    receipts: Array<{
+        receiptObjectId: string;
+        expected: {
+            policyId: string;
+            policyVersion: string;
+            evmChainId: number;
+            intentHash: Hex;
+            toEvm: Hex;
+        };
+    }>;
+};
+/**
+ * Minimal verifier for an audit bundle (v1).
+ * This intentionally verifies only receipt commitments using on-chain receipt contents.
+ */
+export declare function verifyAuditBundle(args: {
+    suiRpcUrl: string;
+    bundle: AuditBundle;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/auditBundle.js

@@ -0,0 +1,20 @@
+import { fetchAndValidatePolicyReceipt } from "./suiReceipts";
+/**
+ * Minimal verifier for an audit bundle (v1).
+ * This intentionally verifies only receipt commitments using on-chain receipt contents.
+ */
+export async function verifyAuditBundle(args) {
+    try {
+        for (const r of args.bundle.receipts) {
+            await fetchAndValidatePolicyReceipt({
+                suiRpcUrl: args.suiRpcUrl,
+                receiptObjectId: r.receiptObjectId,
+                expected: r.expected,
+            });
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/backend.d.ts

@@ -0,0 +1,288 @@
+/**
+ * HTTP client for the Kairo backend API.
+ *
+ * Handles authentication, request formatting, and response parsing.
+ * All methods automatically attach the X-Kairo-Api-Key header.
+ */
+export declare const DEFAULT_BACKEND_URL = "https://api.kairoguard.com";
+export interface BackendClientOpts {
+    backendUrl?: string;
+    apiKey?: string;
+}
+export interface HealthResponse {
+    status: string;
+    adminAddress: string;
+    suiNetwork: string;
+    timestamp: string;
+}
+export interface DKGSubmitRequest {
+    userPublicOutput: number[];
+    userDkgMessage: number[];
+    encryptedUserShareAndProof: number[];
+    sessionIdentifier: number[];
+    signerPublicKey: number[];
+    encryptionKeyAddress: string;
+    encryptionKey: number[];
+    encryptionKeySignature: number[];
+    curve?: number;
+}
+export interface DKGSubmitResponse {
+    success: boolean;
+    requestId: string;
+    status: string;
+}
+export interface DKGStatusResponse {
+    success: boolean;
+    requestId: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    dWalletCapObjectId?: string;
+    dWalletObjectId?: string;
+    encryptedUserSecretKeyShareId?: string;
+    ethereumAddress?: string;
+    solanaAddress?: string;
+    error?: string;
+}
+export interface ProvisionRequest {
+    dwalletObjectId: string;
+    policyObjectId: string;
+    stableId: string;
+    isImportedKey?: boolean;
+}
+export interface ProvisionResponse {
+    success: boolean;
+    digest: string;
+    bindingObjectId: string | null;
+    vaultObjectId: string;
+    dwalletObjectId: string;
+    walletState: string;
+}
+export interface RegisterKeyRequest {
+    label: string;
+    email?: string;
+}
+export interface RegisterKeyResponse {
+    success: boolean;
+    apiKey: string;
+    label: string;
+    tier: string;
+    createdAt: number;
+}
+export type RequestStatus = "pending" | "processing" | "completed" | "failed";
+export interface PresignRequestParams {
+    dWalletId: string;
+    dWalletCapId?: string;
+    curve?: number;
+    signatureAlgorithm?: number;
+    encryptedUserSecretKeyShareId?: string;
+    userOutputSignature?: number[];
+}
+export interface PresignRequestResponse {
+    success: boolean;
+    requestId: string;
+    status: RequestStatus;
+}
+export interface PresignStatusResponse {
+    success: boolean;
+    requestId: string;
+    status: RequestStatus;
+    presignId?: string;
+    presignBytes?: number[];
+    error?: string;
+}
+export interface EthTxParams {
+    to: string;
+    value: string;
+    nonce: number;
+    gasLimit: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    chainId: number;
+    from: string;
+}
+export interface SignRequestParams {
+    dWalletId: string;
+    dWalletCapId: string;
+    encryptedUserSecretKeyShareId: string;
+    userOutputSignature: number[];
+    presignId: string;
+    messageHex: string;
+    userSignMessage: number[];
+    policyReceiptId: string;
+    policyBindingObjectId?: string;
+    policyObjectId?: string;
+    policyVersion?: string;
+    custodyChainObjectId?: string;
+    custodyPackageId?: string;
+    ethTx?: EthTxParams;
+}
+export interface SignRequestResponse {
+    success: boolean;
+    requestId: string;
+    status: RequestStatus;
+}
+export interface SignStatusResponse {
+    success: boolean;
+    requestId: string;
+    status: RequestStatus;
+    digest?: string;
+    signatureHex?: string;
+    signId?: string;
+    ethTxHash?: string;
+    ethBlockNumber?: number;
+    error?: string;
+}
+export interface CreatePolicyV4Rule {
+    ruleType: number;
+    namespace?: number;
+    params: string;
+}
+export interface CreatePolicyV4Params {
+    stableId: string;
+    version: string;
+    expiresAtMs?: number;
+    allowNamespaces?: number[];
+    allowChainIds?: Array<{
+        namespace: number;
+        chainId: string;
+    }>;
+    allowDestinations?: string[];
+    denyDestinations?: string[];
+    rules: CreatePolicyV4Rule[];
+}
+export interface CreatePolicyV4Response {
+    success: boolean;
+    policyObjectId: string;
+    digest: string;
+    error?: string;
+}
+export interface RegisterFromPolicyParams {
+    policyObjectId: string;
+    note?: string;
+    registryObjectId?: string;
+}
+export interface RegisterFromPolicyResponse {
+    success: boolean;
+    policyVersionObjectId: string;
+    digest: string;
+    error?: string;
+}
+export interface GovernanceProposeParams {
+    governanceId: string;
+    bindingId: string;
+    targetVersionId: string;
+}
+export interface GovernanceProposeResponse {
+    success: boolean;
+    proposalId: string;
+    digest: string;
+    error?: string;
+}
+export interface GovernanceApproveParams {
+    governanceId: string;
+    proposalId: string;
+}
+export interface GovernanceApproveResponse {
+    success: boolean;
+    digest: string;
+    error?: string;
+}
+export interface GovernanceExecuteAndReaffirmParams {
+    governanceId: string;
+    proposalId: string;
+    bindingObjectId: string;
+}
+export interface GovernanceExecuteAndReaffirmResponse {
+    success: boolean;
+    digest: string;
+    error?: string;
+}
+export interface GovernanceInfo {
+    id: string;
+    stableId: string;
+    approvers: string[];
+    threshold: number;
+    timelockDurationMs: number;
+    proposalCount: number;
+    admin: string;
+}
+export interface GovernanceGetResponse {
+    success: boolean;
+    governance?: GovernanceInfo;
+    error?: string;
+}
+export interface GovernanceProposalInfo {
+    id: string;
+    governanceId: string;
+    bindingId: string;
+    targetVersionId: string;
+    proposer: string;
+    approvals: string[];
+    createdAtMs: number;
+    thresholdMetAtMs: number;
+    executed: boolean;
+    cancelled: boolean;
+}
+export interface GovernanceProposalGetResponse {
+    success: boolean;
+    proposal?: GovernanceProposalInfo;
+    error?: string;
+}
+export interface PolicyDetailsResponse {
+    success: boolean;
+    policy?: Record<string, unknown>;
+    error?: string;
+}
+export interface DWalletFullResponse {
+    success: boolean;
+    dWallet?: unknown;
+    error?: string;
+}
+export interface SuiObjectResponse {
+    success: boolean;
+    object?: {
+        data?: {
+            content?: {
+                fields?: Record<string, unknown>;
+            };
+        };
+    };
+    error?: string;
+}
+export declare class BackendClient {
+    private baseUrl;
+    private apiKey;
+    constructor(opts: BackendClientOpts);
+    setApiKey(key: string): void;
+    private request;
+    getHealth(): Promise<HealthResponse>;
+    register(label: string, email?: string): Promise<RegisterKeyResponse>;
+    submitDKG(data: DKGSubmitRequest): Promise<DKGSubmitResponse>;
+    getDKGStatus(requestId: string): Promise<DKGStatusResponse>;
+    provision(params: ProvisionRequest): Promise<ProvisionResponse>;
+    mintReceipt(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    requestPresign(params: PresignRequestParams): Promise<PresignRequestResponse>;
+    getPresignStatus(requestId: string): Promise<PresignStatusResponse>;
+    requestSign(params: SignRequestParams): Promise<SignRequestResponse>;
+    getSignStatus(requestId: string): Promise<SignStatusResponse>;
+    createPolicyV4(params: CreatePolicyV4Params): Promise<CreatePolicyV4Response>;
+    registerPolicyVersionFromPolicy(params: RegisterFromPolicyParams): Promise<RegisterFromPolicyResponse>;
+    proposeGovernancePolicyChange(params: GovernanceProposeParams): Promise<GovernanceProposeResponse>;
+    approveGovernancePolicyChange(params: GovernanceApproveParams): Promise<GovernanceApproveResponse>;
+    executeAndReaffirmGovernancePolicyChange(params: GovernanceExecuteAndReaffirmParams): Promise<GovernanceExecuteAndReaffirmResponse>;
+    getGovernance(governanceId: string): Promise<GovernanceGetResponse>;
+    getGovernanceProposal(proposalId: string): Promise<GovernanceProposalGetResponse>;
+    getPolicy(policyObjectId: string): Promise<PolicyDetailsResponse>;
+    getDWalletFull(dWalletId: string): Promise<DWalletFullResponse>;
+    getSuiObject(objectId: string): Promise<SuiObjectResponse>;
+    policySign(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    activateDWallet(params: {
+        dWalletId: string;
+        encryptedUserSecretKeyShareId: string;
+        userOutputSignature: number[];
+    }): Promise<{
+        success: boolean;
+        digest: string;
+    }>;
+    getVaultStatus(dWalletId: string): Promise<Record<string, unknown>>;
+    getAuditEvents(limit?: number): Promise<Record<string, unknown>>;
+}

package/dist/backend.js

@@ -0,0 +1,107 @@
+/**
+ * HTTP client for the Kairo backend API.
+ *
+ * Handles authentication, request formatting, and response parsing.
+ * All methods automatically attach the X-Kairo-Api-Key header.
+ */
+export const DEFAULT_BACKEND_URL = "https://api.kairoguard.com";
+export class BackendClient {
+    baseUrl;
+    apiKey;
+    constructor(opts) {
+        this.baseUrl = (opts.backendUrl ?? DEFAULT_BACKEND_URL).replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+    }
+    setApiKey(key) {
+        this.apiKey = key;
+    }
+    async request(method, path, body) {
+        const headers = { "Content-Type": "application/json" };
+        if (this.apiKey) {
+            headers["X-Kairo-Api-Key"] = this.apiKey;
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const json = await res.json();
+        if (!res.ok) {
+            const msg = json.error || json.message || `HTTP ${res.status}`;
+            throw new Error(`Kairo API error (${path}): ${msg}`);
+        }
+        return json;
+    }
+    async getHealth() {
+        return this.request("GET", "/health");
+    }
+    async register(label, email) {
+        return this.request("POST", "/api/keys/register", { label, email });
+    }
+    async submitDKG(data) {
+        return this.request("POST", "/api/dkg/submit", data);
+    }
+    async getDKGStatus(requestId) {
+        return this.request("GET", `/api/dkg/status/${requestId}`);
+    }
+    async provision(params) {
+        return this.request("POST", "/api/vault/provision", params);
+    }
+    async mintReceipt(params) {
+        return this.request("POST", "/api/policy/receipt/mint", params);
+    }
+    async requestPresign(params) {
+        return this.request("POST", "/api/presign/request", params);
+    }
+    async getPresignStatus(requestId) {
+        return this.request("GET", `/api/presign/status/${requestId}`);
+    }
+    async requestSign(params) {
+        return this.request("POST", "/api/sign/request", params);
+    }
+    async getSignStatus(requestId) {
+        return this.request("GET", `/api/sign/status/${requestId}`);
+    }
+    async createPolicyV4(params) {
+        return this.request("POST", "/api/policy/create", params);
+    }
+    async registerPolicyVersionFromPolicy(params) {
+        return this.request("POST", "/api/policy/registry/register-from-policy", params);
+    }
+    async proposeGovernancePolicyChange(params) {
+        return this.request("POST", "/api/policy/governance/propose", params);
+    }
+    async approveGovernancePolicyChange(params) {
+        return this.request("POST", "/api/policy/governance/approve", params);
+    }
+    async executeAndReaffirmGovernancePolicyChange(params) {
+        return this.request("POST", "/api/policy/governance/execute-and-reaffirm", params);
+    }
+    async getGovernance(governanceId) {
+        return this.request("GET", `/api/policy/governance/${governanceId}`);
+    }
+    async getGovernanceProposal(proposalId) {
+        return this.request("GET", `/api/policy/governance/proposal/${proposalId}`);
+    }
+    async getPolicy(policyObjectId) {
+        return this.request("GET", `/api/policies/${policyObjectId}`);
+    }
+    async getDWalletFull(dWalletId) {
+        return this.request("GET", `/api/dwallet/full/${dWalletId}`);
+    }
+    async getSuiObject(objectId) {
+        return this.request("GET", `/api/sui/object/${objectId}`);
+    }
+    async policySign(params) {
+        return this.request("POST", "/api/policy/sign", params);
+    }
+    async activateDWallet(params) {
+        return this.request("POST", "/api/dwallet/activate", params);
+    }
+    async getVaultStatus(dWalletId) {
+        return this.request("GET", `/api/vault/status/${dWalletId}`);
+    }
+    async getAuditEvents(limit = 10) {
+        return this.request("GET", `/api/audit/events?limit=${limit}`);
+    }
+}

package/dist/bitcoinIntent.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Bitcoin Intent Utilities
+ *
+ * Client-side helpers for Bitcoin transaction intent hashing and validation.
+ */
+import type { Hex } from "./types.js";
+/**
+ * Bitcoin script types.
+ */
+export declare enum BitcoinScriptType {
+    P2PKH = 0,
+    P2WPKH = 1,
+    P2TR = 2
+}
+/**
+ * Bitcoin network types.
+ */
+export type BitcoinNetwork = "mainnet" | "testnet" | "signet";
+/**
+ * Parsed PSBT output.
+ */
+export interface PSBTOutput {
+    address: string;
+    value: bigint;
+}
+/**
+ * Parsed PSBT input (UTXO).
+ */
+export interface PSBTInput {
+    txid: string;
+    vout: number;
+    value: bigint;
+    scriptType?: BitcoinScriptType;
+}
+/**
+ * Parsed PSBT structure.
+ */
+export interface ParsedPSBT {
+    inputs: PSBTInput[];
+    outputs: PSBTOutput[];
+    fee: bigint;
+    scriptType: BitcoinScriptType;
+}
+/**
+ * Bitcoin intent for policy verification.
+ */
+export interface BitcoinIntent {
+    network: BitcoinNetwork;
+    /** 32-byte intent hash (sighash) */
+    intentHash: Hex;
+    /** Destination addresses */
+    destinations: string[];
+    /** Amounts in satoshis */
+    amounts: bigint[];
+    /** Script type */
+    scriptType: BitcoinScriptType;
+    /** Raw PSBT hex */
+    psbtHex: string;
+}
+/**
+ * Compute double SHA256 (hash256).
+ */
+export declare function hash256(data: Uint8Array): Uint8Array;
+/**
+ * Compute BIP340 tagged hash for Taproot.
+ */
+export declare function taggedHash(tag: string, data: Uint8Array): Uint8Array;
+/**
+ * Convert hex string to bytes.
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert bytes to hex string.
+ */
+export declare function bytesToHex(bytes: Uint8Array): Hex;
+/**
+ * Validate a Bitcoin address format.
+ * This is a basic check - full validation requires network context.
+ */
+export declare function validateBitcoinAddress(address: string, network?: BitcoinNetwork): boolean;
+/**
+ * Detect script type from address format.
+ */
+export declare function detectScriptTypeFromAddress(address: string): BitcoinScriptType;
+/**
+ * Compute total input value from parsed PSBT.
+ */
+export declare function computeTotalInputValue(psbt: ParsedPSBT): bigint;
+/**
+ * Compute total output value from parsed PSBT.
+ */
+export declare function computeTotalOutputValue(psbt: ParsedPSBT): bigint;
+/**
+ * Compute fee from parsed PSBT.
+ */
+export declare function computeFee(psbt: ParsedPSBT): bigint;
+/**
+ * Format satoshis as BTC string.
+ */
+export declare function satoshisToBTC(satoshis: bigint): string;
+/**
+ * Parse BTC string to satoshis.
+ */
+export declare function btcToSatoshis(btc: string | number): bigint;