@k9o/kibo-react-native 0.1.0 → 1.1.0

package/README.md

@@ -1,35 +1,173 @@
 # @k9o/kibo-react-native
 
-Zero-Knowledge BYOK/HYOK vault SDK for React Native — the RN surface of
-[Kibo](https://kilimanjaro.dev/kibo).
+Kibo for React Native. Encrypt and decrypt on the device with keys held in your own KMS, so the platform never sees your plaintext.
 
-`encrypt` / `decrypt` run entirely client-side against your 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.
+## Contents
 
-## Loading the core
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Load the core](#load-the-core)
+- [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)
 
-React Native cannot dynamically `import()` the wasm artifact, so the host loads
-the provider-matched core build and injects it once at app start:
+## Install
+
+```bash
+npm install @k9o/kibo-react-native
+```
+
+Yarn works too: `yarn add @k9o/kibo-react-native`. See [requirements](#requirements).
+
+## Quick start
+
+- Load the Kibo core 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.
+
+## Load the core
+
+React Native cannot import the WebAssembly core on demand. Your app loads it and hands it over once with `setZkWasm`.
 
 ```ts
-import { setZkWasm, encrypt, decrypt } from "@k9o/kibo-react-native";
-import * as core from "./kibo_kms_rest_ffi.js"; // your bundled wasm build
+import { setZkWasm } from "@k9o/kibo-react-native";
+import * as core from "./kibo_kms_rest_ffi.js";
 
 setZkWasm(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`.
+
+## Encrypt and decrypt
+
+The example encrypts the title of a task. `kms_cred.secret` is a short-lived federated token you issue for your KMS.
+
+```ts
+import { encrypt, decrypt } 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({
+  provider: "aws-kms",
+  posture: "byok",
+  kms_cred: { secret: kmsToken, expires_at_unix_secs: 1_800_000_000 },
+  key_ref: { version: 1, external_ref: "arn:aws:kms:eu-central-1:111122223333:key/example" },
+  provider_config: { aws_region: "eu-central-1" },
+  attestation_tier: "software",
+  encryption_context: context,
+  plaintext: title,
+});
+
+const opened = await decrypt({
+  kms_cred: { secret: kmsToken, expires_at_unix_secs: 1_800_000_000 },
+  provider_config: { aws_region: "eu-central-1" },
+  envelope: sealed.envelope,
+  strategy: "local_envelope",
+  attestation_tier: "software",
+  encryption_context: context,
+});
+
+console.log(new TextDecoder().decode(opened.plaintext));
+```
+
+```text
+Write the README
+```
 
-const out = await encrypt(input);  // KiboEncryptInput → { envelope }
-const back = await decrypt(input); // KiboDecryptInput → { plaintext }
+- Give `decrypt` the same `strategy`, `attestation_tier` and `encryption_context` you used to encrypt.
+- The returned `envelope` is opaque bytes. Store it with the encrypted record.
+- All fields are listed in [encrypt and decrypt fields](#encrypt-and-decrypt-fields).
+
+## Handle errors
+
+Every failure is a `KiboError` with `code`, `message` and `context`.
+
+```ts
+import { KiboError } from "@k9o/kibo-react-native";
+
+try {
+  await encrypt(input);
+} catch (error) {
+  if (error instanceof KiboError) {
+    console.log(error.code);
+  }
+}
 ```
 
-Errors surface as `KiboError` (`code` + `message` + `context`), preserving the
-core's wire codes; a posture-floor violation carries `dimension` / `requested` /
-`declared` in `context`.
+If `setZkWasm` was skipped, this prints:
+
+```text
+KIBO_WASM_NOT_LOADED
+```
+
+See [error codes](#error-codes) for the full list.
+
+## Appendix
+
+### Requirements
+
+| Requirement | Version |
+|---|---|
+| React | 18 or later |
+| React Native | 0.74 or later |
+| Kibo core (WebAssembly) | Bundled by your app |
+
+### Methods
+
+| Function | What it does |
+|---|---|
+| `setZkWasm(core)` | Supply the Kibo core; call once at app start |
+| `encrypt(input)` | Encrypt bytes with your KMS; returns `{ envelope }` |
+| `decrypt(input)` | Decrypt an envelope; returns `{ plaintext }` |
+
+### Encrypt and decrypt fields
+
+| Field | Used by | Meaning |
+|---|---|---|
+| `provider` | encrypt | `aws-kms`, `gcp-kms`, `azure-kv` or `hashicorp-vault` |
+| `posture` | encrypt | `byok` or `hyok` |
+| `kms_cred` | both | `{ secret, expires_at_unix_secs }` |
+| `key_ref` | encrypt | `{ version, external_ref }` identifying your KMS key |
+| `provider_config` | both | `{ aws_region?, vault_address? }` |
+| `attestation_tier` | both | `software`, `hardware_backed` or `confidential` |
+| `encryption_context` | both | List of `{ key, value }` pairs; `kibo:` keys are reserved |
+| `strategy` | decrypt (optional on encrypt) | `local_envelope` or `customer_kms_oracle` |
+| `oracle_mode` | encrypt, optional | `brokered` or `direct` |
+| `posture_policy` | encrypt, optional | Minimum custody posture and allowed oracle modes |
+| `plaintext` | encrypt | Bytes to encrypt |
+| `envelope` | decrypt | Bytes returned by `encrypt` |
+
+### Error codes
+
+Codes from the core are passed through unchanged.
+
+| Code | When |
+|---|---|
+| `KIBO_WASM_NOT_LOADED` | `setZkWasm` has not been called |
+| `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 |
+| `KIBO_WASM_ERROR` | The core failed with a message that has no code |
+
+### Related packages
+
+| Package | Purpose |
+|---|---|
+| `@k9o/gate-react-native` | End-user sign-in for React Native |
+| `@k9o/kibo` | TypeScript package that also covers vault secrets and wrapped data keys |
+
+Documentation: <https://kilimanjaro.dev>
 
-## Native artifact
+## License
 
-The core wasm (`kibo_kms_rest_ffi_bg.wasm` + JS glue) is generated per provider
-by CI (`wasm-pack build --target web`) and is not vendored in this package — the
-host bundles it. The cross-platform packaging is the publish pipeline's
-responsibility — see `.gitlab/sdk-publish.yml`.
+Apache-2.0 © Formelo Inc. See `LICENSE` and `NOTICE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k9o/kibo-react-native",
-  "version": "0.1.0",
+  "version": "1.1.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",

package/src/crypto-types.ts

@@ -42,7 +42,7 @@ export interface KiboAllowedOracleModes {
   direct: boolean;
 }
 
-/** Project-declared crypto-posture floor (ch08 §11.3.3.4). 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;