@k9o/kibo-react-native 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @k9o/kibo-react-native — Changelog
+
+## 1.3.0 — 2026-10-26
+
+### Changed
+
+- The web glue of the Kibo core initialises lazily on the first `encrypt` or `decrypt`.
+- A core that was supplied but cannot start fails with the new `KIBO_WASM_INIT_FAILED`. A later call retries.
+- README: the core ships inside the package under `wasm/`. It is not something your app has to bundle.
+
+### Removed
+
+- Nothing.
+
+### Added
+
+- `init({ core, wasm? })` supplies the core and initialises it now. `wasm` takes the compiled `.wasm` bytes.
+- Types `ZkCoreModule` and `InitOptions`.
+
+## 1.0.0
+
+First public release.

package/README.md

@@ -2,7 +2,8 @@
 
 Kibo for React Native. Encrypt and decrypt on the device with keys held in your own KMS, so the platform never sees your plaintext.
 
-Kilimanjaro is an AI-native platform on a Governed Database. Its products are Keep (AI Security and Governance), Pulse (Data Intelligence), Gate (Customer Identity and Access Management) and Kibo (Keys and Secrets Management).
+Kilimanjaro is the AI-native foundation for building critical applications. Its products are Keep (AI Security and Governance),
+Pulse (Data Intelligence), Gate (Customer Identity and Access Management) and Kibo (Keys and Secrets Management).
 
 ## Contents
 
@@ -13,6 +14,11 @@ Kilimanjaro is an AI-native platform on a Governed Database. Its products are Ke
 - [Encrypt and decrypt](#encrypt-and-decrypt)
 - [Handle errors](#handle-errors)
 - [Appendix](#appendix)
+  - [Requirements](#requirements)
+  - [Methods](#methods)
+  - [Encrypt and decrypt fields](#encrypt-and-decrypt-fields)
+  - [Error codes](#error-codes)
+  - [Related packages](#related-packages)
 
 ## Links
 
@@ -20,11 +26,6 @@ Kilimanjaro is an AI-native platform on a Governed Database. Its products are Ke
 - Documentation / Developer Hub: <https://docs.kilimanjaro.dev>
 - Platform API: <https://api.k9o.io>
 - Platform Console: <https://console.k9o.io>
-  - [Requirements](#requirements)
-  - [Methods](#methods)
-  - [Encrypt and decrypt fields](#encrypt-and-decrypt-fields)
-  - [Error codes](#error-codes)
-  - [Related packages](#related-packages)
 
 ## Install
 
@@ -36,25 +37,29 @@ Yarn works too: `yarn add @k9o/kibo-react-native`. See [requirements](#requireme
 
 ## Quick start
 
-- Load the Kibo core once at app start. See [load the core](#load-the-core).
+- Hand the Kibo core to the package once at app start. See [load the core](#load-the-core).
 - Call `encrypt` and `decrypt`. See [encrypt and decrypt](#encrypt-and-decrypt).
 
 This package has no cryptography of its own. It passes typed input to the Kibo core, a WebAssembly module, and returns the result.
+The core ships inside the package, under `wasm/`.
 
 ## Load the core
 
-React Native cannot import the WebAssembly core on demand. Your app loads it and hands it over once with `setZkWasm`.
+React Native cannot import the WebAssembly core on demand. Your app imports it and hands it over once with `init`.
 
 ```ts
-import { setZkWasm } from "@k9o/kibo-react-native";
-import * as core from "./kibo_kms_rest_ffi.js";
+import { init } from "@k9o/kibo-react-native";
+import * as core from "@k9o/kibo-react-native/wasm/kibo_kms_rest_ffi.js";
 
-setZkWasm(core);
+await init({ core });
 ```
 
-- The core is not shipped inside this package. Your app bundles it.
-- It must expose async `zk_encrypt` and `zk_decrypt` functions (the `ZkWasm` type).
-- Until `setZkWasm` runs, `encrypt` and `decrypt` fail with `KIBO_WASM_NOT_LOADED`.
+- `init` is optional. Without it, the core is initialised on the first `encrypt` or `decrypt`.
+- `setZkWasm(core)` supplies the core without initialising it. `init({ core })` does both.
+- If your runtime cannot fetch the `.wasm` file itself, pass its bytes: `init({ core, wasm })`.
+- The module must expose async `zk_encrypt` and `zk_decrypt` functions (the `ZkWasm` type).
+- Before a core is supplied, `encrypt` and `decrypt` fail with `KIBO_WASM_NOT_LOADED`.
+- If the core is supplied but cannot start, they fail with `KIBO_WASM_INIT_FAILED`. A later call retries.
 
 ## Encrypt and decrypt
 
@@ -62,12 +67,13 @@ The example encrypts the title of a task. `kms_cred.secret` is a short-lived fed
 
 ```ts
 import { encrypt, decrypt } from "@k9o/kibo-react-native";
+import type { KiboEncryptInput } from "@k9o/kibo-react-native";
 
 const kmsToken = "FEDERATED_TOKEN";
 const context = [{ key: "collection", value: "tasks" }];
 const title = new TextEncoder().encode("Write the README");
 
-const sealed = await encrypt({
+const input: KiboEncryptInput = {
   provider: "aws-kms",
   posture: "byok",
   kms_cred: { secret: kmsToken, expires_at_unix_secs: 1_800_000_000 },
@@ -76,7 +82,9 @@ const sealed = await encrypt({
   attestation_tier: "software",
   encryption_context: context,
   plaintext: title,
-});
+};
+
+const sealed = await encrypt(input);
 
 const opened = await decrypt({
   kms_cred: { secret: kmsToken, expires_at_unix_secs: 1_800_000_000 },
@@ -100,7 +108,7 @@ Write the README
 
 ## Handle errors
 
-Every failure is a `KiboError` with `code`, `message` and `context`.
+Every failure is a `KiboError` with `code`, `message` and `context`. The `input` is the one from the previous section.
 
 ```ts
 import { KiboError } from "@k9o/kibo-react-native";
@@ -114,7 +122,7 @@ try {
 }
 ```
 
-If `setZkWasm` was skipped, this prints:
+If no core was supplied, this prints:
 
 ```text
 KIBO_WASM_NOT_LOADED
@@ -130,13 +138,14 @@ See [error codes](#error-codes) for the full list.
 |---|---|
 | React | 18 or later |
 | React Native | 0.74 or later |
-| Kibo core (WebAssembly) | Bundled by your app |
+| Kibo core (WebAssembly) | Shipped in the package under `wasm/` |
 
 ### Methods
 
 | Function | What it does |
 |---|---|
-| `setZkWasm(core)` | Supply the Kibo core; call once at app start |
+| `init({ core, wasm? })` | Supply the core and initialise it now; optional, `encrypt` initialises on first use |
+| `setZkWasm(core)` | Supply the core; it is initialised on first use |
 | `encrypt(input)` | Encrypt bytes with your KMS; returns `{ envelope }` |
 | `decrypt(input)` | Decrypt an envelope; returns `{ plaintext }` |
 
@@ -163,7 +172,8 @@ Codes from the core are passed through unchanged.
 
 | Code | When |
 |---|---|
-| `KIBO_WASM_NOT_LOADED` | `setZkWasm` has not been called |
+| `KIBO_WASM_NOT_LOADED` | No core was supplied with `init` or `setZkWasm` |
+| `KIBO_WASM_INIT_FAILED` | A core was supplied but failed to initialise; `context.cause` has the reason |
 | `K9O_CRYPTO_POSTURE_FLOOR_VIOLATION` | `posture` is below the floor in `posture_policy`; `context` has `dimension`, `requested`, `declared` |
 | `UPSTREAM_KMS_ERROR` | Your own KMS rejected or failed the call |
 | `KIBO_WASM_DECODE_ERROR` | The core returned something other than bytes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k9o/kibo-react-native",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Kibo Zero-Knowledge BYOK/HYOK vault SDK for React Native — client-side encrypt/decrypt against your own KMS, over the audited Rust core (kibo-kms-rest-ffi) compiled to wasm. The platform never sees plaintext.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -10,7 +10,8 @@
     "!src/__tests__",
     "LICENSE",
     "NOTICE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "repository": {
     "type": "git",

package/src/KiboError.ts

@@ -15,8 +15,9 @@ export class KiboError extends Error {
   readonly code: string;
   readonly context: Record<string, unknown>;
 
-  constructor(opts: { code: string; message: string; context?: Record<string, unknown> }) {
+  constructor(opts: { code: string; message: string; context?: Record<string, unknown>; cause?: unknown }) {
     super(opts.message);
+    if (opts.cause !== undefined) (this as { cause?: unknown }).cause = opts.cause;
     this.name = "KiboError";
     this.code = opts.code;
     this.context = opts.context ?? {};

package/src/crypto-types.ts

@@ -1,6 +1,6 @@
 /**
  * TS contract for the ZK encrypt/decrypt FFI surface — mirrors the Rust
- * `kibo-kms-rest-ffi::types` (the bound core, piece C) field-for-field.
+ * `kibo-kms-rest-ffi::types` (the bound core) field-for-field.
  *
  * These types cross the wasm boundary as plain JS objects (serde-wasm-bindgen),
  * so the field names + enum wire-tokens must match the Rust serde exactly:
@@ -42,7 +42,7 @@ export interface KiboAllowedOracleModes {
   direct: boolean;
 }
 
-/** Project-declared crypto-posture floor. Omit fields for the
+/** Project-declared crypto-posture floor . Omit fields for the
  *  most-permissive default (`platform_managed` floor + both oracle modes). */
 export interface KiboPosturePolicy {
   min_custody_posture?: KiboMinPosture;

package/src/crypto.ts

@@ -1,14 +1,15 @@
 /**
- * ZK encrypt/decrypt — the thin React Native wrapper over the bound crypto core
- * (`kibo-kms-rest-ffi`, piece C) compiled to wasm. ZERO crypto here: every
+ * ZK encrypt/decrypt - the thin React Native wrapper over the bound crypto core
+ * (`kibo-kms-rest-ffi`) compiled to wasm. ZERO crypto here: every
  * wrap/unwrap, envelope framing, posture-floor enforcement, and KMS round-trip
- * lives in the audited Rust core. This layer only marshals the typed input
- * across the wasm boundary and maps the core's error string → `KiboError`.
+ * lives in the Rust core. This layer only marshals the typed input
+ * across the wasm boundary and maps the core's error string to `KiboError`.
  *
- * Unlike the Node `@k9o/kibo` package, RN cannot dynamically `import()` the
- * vendored wasm at runtime — the host must load the core wasm (per its bundler /
- * `react-native-wasm` runtime) and inject it via `setZkWasm` before the first
- * `encrypt` / `decrypt`. This mirrors `@k9o/kibo`'s `setZkWasm` escape hatch.
+ * The core is the wasm-bindgen web-target module (`wasm/kibo_kms_rest_ffi.js`, shipped in this package). That module
+ * must be initialised (its default export instantiates the `.wasm`) before `zk_encrypt` / `zk_decrypt` exist in a
+ * usable state. `init()` does that; `encrypt` / `decrypt` call it for you on first use when a core has been supplied
+ * with `init({ core })` or `setZkWasm(core)`. React Native cannot `import()` the artifact on demand, so the app
+ * imports the module itself and hands it over.
  */
 
 import { KiboError } from "./KiboError";
@@ -25,35 +26,102 @@ export interface ZkWasm {
   zk_decrypt(input: unknown): Promise<unknown>;
 }
 
-let zkWasm: ZkWasm | undefined;
+/** The wasm-bindgen web-target module namespace: `ZkWasm` plus its initialisers. */
+export interface ZkCoreModule extends ZkWasm {
+  /** Instantiates the `.wasm`. Takes the module bytes, a `WebAssembly.Module`, a `URL`/string, or nothing (then the glue fetches
+   *  its sibling `.wasm`, which works on the web but usually not in React Native). */
+  default?: (input?: unknown) => Promise<unknown>;
+  /** Synchronous instantiation from bytes or a `WebAssembly.Module`. */
+  initSync?: (input: unknown) => unknown;
+}
+
+export interface InitOptions {
+  /** The core module: `import * as core from "@k9o/kibo-react-native/wasm/kibo_kms_rest_ffi.js"`. Optional when `setZkWasm` was called. */
+  core?: ZkCoreModule;
+  /** The compiled `.wasm`, as bytes (`ArrayBuffer`/typed array), a `WebAssembly.Module`, or whatever your runtime can hand the glue
+   *  (URL, string, `Response`). Omit it to let the glue locate its own `.wasm`. */
+  wasm?: unknown;
+}
+
+let core: ZkCoreModule | undefined;
+let wasmInput: unknown;
+let ready: ZkWasm | undefined;
+let pending: Promise<ZkWasm> | undefined;
 
 /**
- * Inject the host-loaded core wasm module. MUST be called once at app start
- * (before any `encrypt` / `decrypt`) with the provider-matched core build.
+ * Supply the core module. Call it once at app start, or use `init({ core })`. If the module still needs
+ * instantiating (it has a default export), that happens on the first `encrypt` / `decrypt`, or earlier via `init()`.
+ * A module with only `zk_encrypt` / `zk_decrypt` (already instantiated, or a test double) is used as is.
  */
-export function setZkWasm(mod: ZkWasm): void {
-  zkWasm = mod;
+export function setZkWasm(mod: ZkWasm | ZkCoreModule | undefined): void {
+  core = mod as ZkCoreModule | undefined;
+  ready = undefined;
+  pending = undefined;
+}
+
+function isSyncInput(v: unknown): boolean {
+  if (v === undefined || v === null) return false;
+  const W = (globalThis as { WebAssembly?: { Module?: new (...a: never[]) => unknown } }).WebAssembly;
+  return v instanceof ArrayBuffer || ArrayBuffer.isView(v) || (W?.Module !== undefined && v instanceof (W.Module as new (...a: never[]) => object));
+}
+
+/**
+ * Initialise the core now (optional: `encrypt` / `decrypt` do it on first use). Safe to call more than once; concurrent
+ * calls share one initialisation, and a failed one can be retried.
+ */
+export async function init(options: InitOptions = {}): Promise<void> {
+  if (options.core !== undefined) setZkWasm(options.core);
+  if (options.wasm !== undefined) {
+    wasmInput = options.wasm;
+    ready = undefined;
+    pending = undefined;
+  }
+  await ensureReady();
 }
 
-function requireWasm(): ZkWasm {
-  if (!zkWasm) {
-    throw new KiboError({
-      code: "KIBO_WASM_NOT_LOADED",
-      message:
-        "ZK core wasm not loaded. Call setZkWasm(coreModule) once at app start before encrypt/decrypt.",
-      context: {},
-    });
+function ensureReady(): Promise<ZkWasm> {
+  if (ready) return Promise.resolve(ready);
+  if (!core) {
+    return Promise.reject(
+      new KiboError({
+        code: "KIBO_WASM_NOT_LOADED",
+        message:
+          "The Kibo core (wasm) has not been supplied. Call init({ core }) or setZkWasm(core) once, with the module from wasm/kibo_kms_rest_ffi.js in this package (or a build your app bundles), before encrypt/decrypt.",
+        context: {},
+      }),
+    );
   }
-  return zkWasm;
+  const mod = core;
+  pending ??= (async () => {
+    try {
+      if (typeof mod.initSync === "function" && isSyncInput(wasmInput)) mod.initSync(wasmInput);
+      else if (typeof mod.default === "function") await mod.default(wasmInput);
+      if (typeof mod.zk_encrypt !== "function" || typeof mod.zk_decrypt !== "function") {
+        throw new Error("the module does not export zk_encrypt and zk_decrypt");
+      }
+      ready = mod;
+      return mod;
+    } catch (e) {
+      pending = undefined; // allow a retry
+      const why = e instanceof Error ? e.message : String(e);
+      throw new KiboError({
+        code: "KIBO_WASM_INIT_FAILED",
+        message: `The Kibo core (wasm) was supplied but failed to initialise: ${why}`,
+        context: { cause: why },
+        cause: e,
+      });
+    }
+  })();
+  return pending;
 }
 
 /**
  * Encrypt `input.plaintext` via the customer KMS, client-side. Returns the
- * opaque ZKFE envelope — store it via the gateway ZK-DEK surface (F.5) or keep
+ * opaque ZKFE envelope - store it via the gateway ZK-DEK surface or keep
  * it yourself; it is meaningless to the platform.
  */
 export async function encrypt(input: KiboEncryptInput): Promise<KiboEncryptOutput> {
-  const wasm = requireWasm();
+  const wasm = await ensureReady();
   let out: unknown;
   try {
     out = await wasm.zk_encrypt(input);
@@ -69,7 +137,7 @@ export async function encrypt(input: KiboEncryptInput): Promise<KiboEncryptOutpu
  * and never recovered from the envelope (anti-substitution discipline).
  */
 export async function decrypt(input: KiboDecryptInput): Promise<KiboDecryptOutput> {
-  const wasm = requireWasm();
+  const wasm = await ensureReady();
   let out: unknown;
   try {
     out = await wasm.zk_decrypt(input);

package/src/index.ts

@@ -3,15 +3,14 @@
  *
  * `encrypt` / `decrypt` run entirely client-side against the customer's own KMS;
  * the platform never sees plaintext or unwrapped keys. All cryptography lives in
- * the audited Rust core (`kibo-kms-rest-ffi`) compiled to wasm; this package only
+ * the Rust core (`kibo-kms-rest-ffi`) compiled to wasm; this package only
  * marshals typed input across the wasm boundary.
  *
- * The host loads the core wasm and injects it via `setZkWasm` once at app start
- * (RN cannot dynamically import the artifact). The F.5 ZK-DEK store/fetch surface
- * (envelope persistence over the gateway) is separate + decoupled.
+ * The core ships in this package under `wasm/`. The app imports it and hands it over once with `init({ core })` (or
+ * `setZkWasm(core)`); `encrypt` / `decrypt` initialise it on first use if `init()` was not awaited earlier.
  */
 
-export { encrypt, decrypt, setZkWasm, type ZkWasm } from "./crypto";
+export { encrypt, decrypt, init, setZkWasm, type ZkWasm, type ZkCoreModule, type InitOptions } from "./crypto";
 export { KiboError } from "./KiboError";
 export type {
   KmsProvider,

package/wasm/kibo_kms_rest_ffi.d.ts

@@ -72,9 +72,9 @@ export interface InitOutput {
     readonly intounderlyingsink_write: (a: number, b: number) => number;
     readonly intounderlyingsource_cancel: (a: number) => void;
     readonly intounderlyingsource_pull: (a: number, b: number) => number;
-    readonly __wasm_bindgen_func_elem_441: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_722: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_1519: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_440: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_721: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1520: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/wasm/kibo_kms_rest_ffi.js

@@ -412,7 +412,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_722(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_721(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -570,12 +570,12 @@ function __wbg_get_imports() {
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 39, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_441);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_440);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 73, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_1519);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_1520);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0) {
@@ -612,14 +612,14 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_1519(arg0, arg1) {
-    wasm.__wasm_bindgen_func_elem_1519(arg0, arg1);
+function __wasm_bindgen_func_elem_1520(arg0, arg1) {
+    wasm.__wasm_bindgen_func_elem_1520(arg0, arg1);
 }
 
-function __wasm_bindgen_func_elem_441(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_440(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_441(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_440(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -630,8 +630,8 @@ function __wasm_bindgen_func_elem_441(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_722(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_722(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_721(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_721(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 

package/wasm/kibo_kms_rest_ffi_bg.wasm.d.ts

@@ -16,9 +16,9 @@ export const intounderlyingsink_close: (a: number) => number;
 export const intounderlyingsink_write: (a: number, b: number) => number;
 export const intounderlyingsource_cancel: (a: number) => void;
 export const intounderlyingsource_pull: (a: number, b: number) => number;
-export const __wasm_bindgen_func_elem_441: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_722: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_1519: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_440: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_721: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_1520: (a: number, b: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;