@k9o/kibo-react-native 0.0.0-stage → 1.1.0

package/src/crypto.ts

@@ -0,0 +1,115 @@
+/**
+ * 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
+ * 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`.
+ *
+ * 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.
+ */
+
+import { KiboError } from "./KiboError";
+import type {
+  KiboEncryptInput,
+  KiboEncryptOutput,
+  KiboDecryptInput,
+  KiboDecryptOutput,
+} from "./crypto-types";
+
+/** The minimal surface the bound ZK-core wasm exposes. */
+export interface ZkWasm {
+  zk_encrypt(input: unknown): Promise<unknown>;
+  zk_decrypt(input: unknown): Promise<unknown>;
+}
+
+let zkWasm: 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.
+ */
+export function setZkWasm(mod: ZkWasm): void {
+  zkWasm = mod;
+}
+
+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: {},
+    });
+  }
+  return zkWasm;
+}
+
+/**
+ * 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
+ * it yourself; it is meaningless to the platform.
+ */
+export async function encrypt(input: KiboEncryptInput): Promise<KiboEncryptOutput> {
+  const wasm = requireWasm();
+  let out: unknown;
+  try {
+    out = await wasm.zk_encrypt(input);
+  } catch (e) {
+    throw mapZkError(e);
+  }
+  return { envelope: toBytes((out as { envelope?: unknown }).envelope) };
+}
+
+/**
+ * Decrypt a ZKFE `input.envelope`. `strategy`, `attestation_tier`, and
+ * `encryption_context` MUST match the values used at encrypt — they are AAD-bound
+ * and never recovered from the envelope (anti-substitution discipline).
+ */
+export async function decrypt(input: KiboDecryptInput): Promise<KiboDecryptOutput> {
+  const wasm = requireWasm();
+  let out: unknown;
+  try {
+    out = await wasm.zk_decrypt(input);
+  } catch (e) {
+    throw mapZkError(e);
+  }
+  return { plaintext: toBytes((out as { plaintext?: unknown }).plaintext) };
+}
+
+/** Normalise wasm byte output (serde-wasm-bindgen emits `Vec<u8>` as a number
+ *  array; some hosts return a `Uint8Array`) to `Uint8Array`. */
+function toBytes(v: unknown): Uint8Array {
+  if (v instanceof Uint8Array) return v;
+  if (Array.isArray(v)) return Uint8Array.from(v as number[]);
+  throw new KiboError({
+    code: "KIBO_WASM_DECODE_ERROR",
+    message: "ZK core returned a non-byte value where bytes were expected",
+    context: {},
+  });
+}
+
+/**
+ * Map the core's rejected error → `KiboError`. The wasm path flattens
+ * `ZkFfiError` to its display string: `"<CODE>: <message>"` where `<CODE>` is a
+ * `K9O_*` wire code (or `UPSTREAM_KMS_ERROR` for the customer's own KMS
+ * failures), optionally followed by `"(dimension: …, requested: …, declared: …)"`
+ * for a posture-floor violation. Codes are passed through (never hardcoded).
+ */
+function mapZkError(e: unknown): KiboError {
+  if (e instanceof KiboError) return e;
+  const raw = e instanceof Error ? e.message : String(e);
+  const head = /^([A-Z][A-Z0-9_]*):\s*([\s\S]*)$/.exec(raw);
+  const code = head?.[1] ?? "KIBO_WASM_ERROR";
+  let message = head?.[2] ?? raw;
+
+  let context: Record<string, unknown> = {};
+  const pv = /\(dimension:\s*([^,]+),\s*requested:\s*([^,]+),\s*declared:\s*([^)]+)\)\s*$/.exec(message);
+  if (pv) {
+    context = { dimension: pv[1]!.trim(), requested: pv[2]!.trim(), declared: pv[3]!.trim() };
+    message = message.slice(0, pv.index).trim();
+  }
+  return new KiboError({ code, message, context });
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * `@k9o/kibo-react-native` — Zero-Knowledge BYOK/HYOK vault SDK for React Native.
+ *
+ * `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
+ * 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.
+ */
+
+export { encrypt, decrypt, setZkWasm, type ZkWasm } from "./crypto";
+export { KiboError } from "./KiboError";
+export type {
+  KmsProvider,
+  KiboPosture,
+  KiboStrategy,
+  KiboOracleMode,
+  KiboAttestationTier,
+  KiboMinPosture,
+  KiboAllowedOracleModes,
+  KiboPosturePolicy,
+  KiboCredential,
+  KiboKeyRef,
+  KiboProviderConfig,
+  KiboKvPair,
+  KiboEncryptInput,
+  KiboEncryptOutput,
+  KiboDecryptInput,
+  KiboDecryptOutput,
+} from "./crypto-types";

package/wasm/kibo_kms_rest_ffi.d.ts

@@ -0,0 +1,105 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+
+type ReadableStreamType = "bytes";
+
+export class IntoUnderlyingByteSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+
+export class IntoUnderlyingSink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+
+export class IntoUnderlyingSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+
+/**
+ * Decrypt a ZKFE envelope (browser / React Native).
+ *
+ * `input_json` — JSON-serialized `DecryptInput`.
+ * Returns a `Promise<string>` resolving to JSON-serialized `DecryptOutput`.
+ */
+export function zk_decrypt(input_json: any): Promise<any>;
+
+/**
+ * Encrypt via the customer KMS (browser / React Native).
+ *
+ * `input_json` — JSON-serialized `EncryptInput`.
+ * Returns a `Promise<string>` resolving to JSON-serialized `EncryptOutput`,
+ * or rejecting with a `JsValue` error string.
+ */
+export function zk_encrypt(input_json: any): Promise<any>;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly zk_decrypt: (a: number) => number;
+    readonly zk_encrypt: (a: number) => number;
+    readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
+    readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
+    readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_autoAllocateChunkSize: (a: number) => number;
+    readonly intounderlyingbytesource_cancel: (a: number) => void;
+    readonly intounderlyingbytesource_pull: (a: number, b: number) => number;
+    readonly intounderlyingbytesource_start: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_type: (a: number) => number;
+    readonly intounderlyingsink_abort: (a: number, b: number) => number;
+    readonly intounderlyingsink_close: (a: number) => number;
+    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 __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;
+    readonly __wbindgen_export4: (a: number, b: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;