@k9o/kibo 0.0.0-stage → 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `@k9o/kibo` — Zero-Knowledge BYOK/HYOK vault SDK types.
+ *
+ * Surface: the ZK-DEK store/fetch. The wrapped
+ * envelope is produced client-side by the audited ZK core (the
+ * `kibo-kms-rest` binding); this SDK ships it **verbatim and opaque** and never
+ * reads its interior — the strict-ZK invariant + envelope framing live in the
+ * core, never here.
+ */
+/** Customer KMS/HSM provider — non-secret routing metadata (mirrors the ZK FFI provider selector). */
+type KmsProvider = "aws-kms" | "gcp-kms" | "azure-kv" | "hashicorp-vault";
+/**
+ * Input to store an opaque customer-wrapped DEK.
+ * `provider` + `keyVersionRef` are explicit non-secret fields the SDK supplies
+ * (vault-ops never parses the envelope to derive them).
+ */
+type StoreZkDekInput = {
+    /** base64 opaque `WrappedDek` envelope (AEAD-sealed under the customer KEK). */
+    envelope: string;
+    /** Which customer KMS/HSM holds the wrapping KEK. */
+    provider: KmsProvider;
+    /** Customer key reference (KMS ARN / GCP resource / AKV id / Vault path). */
+    keyVersionRef: string;
+};
+/** Store response — the opaque `zkdek_<base62>` handle + creation timestamp. */
+type ZkDekHandle = {
+    /** `zkdek_<base62>` handle. */
+    id: string;
+    createdAt: string;
+};
+/** Fetch response — the stored record: opaque envelope + non-secret metadata. */
+type ZkDekRecord = {
+    id: string;
+    /** base64 opaque `WrappedDek` envelope, returned verbatim for the customer to unwrap. */
+    envelope: string;
+    provider: KmsProvider;
+    keyVersionRef: string;
+    createdAt: string;
+};
+/** secret visibility — write ops (create/update) stay owner-only regardless of this tag. */
+type SecretVisibility = {
+    kind: "private";
+} | {
+    kind: "shared";
+    principals?: string[];
+    roles?: string[];
+};
+/** Input to create a vault secret — `POST /@<projectSlug>/vault/secrets/<name>?region=<region>`. */
+type CreateSecretInput = {
+    /** Hierarchical path the secret is addressed under, e.g. `byos/s3-prod` (also the `:name` URL segment). */
+    name: string;
+    /** The plaintext to seal, as a regular (non-base64) string — `vault.secrets.create` base64-encodes
+     *  it for the wire itself (live-verified against staging: the route's OpenAPI description says
+     *  "the plaintext to seal" but a raw non-base64 `value` is rejected as unparseable). */
+    value: string;
+    /** The authoritative region for this vault write (sent as `?region=`), REQUIRED — the vault-forward
+     *  proxy fail-closes without it (live-verified against staging, not documented in the route's
+     *  OpenAPI schema as of this writing). Distinct from any region carried inside `value`'s own
+     *  envelope. */
+    region: string;
+    visibility?: SecretVisibility;
+    metadata?: Record<string, string>;
+};
+/** A secret WITHOUT its sealed ciphertext — the create/list/read metadata shape. */
+type SecretSummary = {
+    /** `sec_<base62>`. */
+    id: string;
+    name: string;
+    ownerId: string;
+    visibility: SecretVisibility;
+    version: number;
+    /** The wrapping-key id at this version. */
+    kid: string;
+    createdAt: string;
+    createdBy: string;
+    updatedAt: string;
+    updatedBy: string;
+    rotatedAt: string | null;
+    retiredAt: string | null;
+    metadata: Record<string, string>;
+};
+/** `client.kibo.vault.secrets.list()` input — none of these need `region` (live-verified: unlike every
+ *  other secrets operation, list is NOT region-gated). */
+type ListSecretsInput = {
+    /** Filter to a path prefix. */
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+};
+type ListSecretsResult = {
+    secrets: readonly SecretSummary[];
+    nextCursor: string | null;
+};
+/** releasing-node observed attestation tier (K4) — present on every reveal. */
+type AttestationTier = {
+    /** `attestation:destination:region` trust-tier URN. */
+    urn: string;
+    /** Node provenance: `platform` (Kibo-operated) or `client` (Private Perimeter). */
+    operator: string;
+    /** Whether node attestation was verified against the vendor PKI on the URN's attestation segment. */
+    verified: boolean;
+};
+/** `revealChallenge()` result — a single-use challenge to present on the immediately-following `reveal()`. */
+type RevealChallenge = {
+    challenge: string;
+    expiresAt: string;
+};
+/** `reveal()` result. `value` is the decoded plaintext (the SDK base64-decodes the wire value, the
+ *  inverse of `create`'s encode) — never the raw base64. */
+type RevealSecretResult = {
+    id: string;
+    name: string;
+    version: number;
+    value: string;
+    revealedAt: string;
+    attestationTier: AttestationTier;
+};
+/** `update()` input. */
+type UpdateSecretInput = {
+    /** The authoritative region for this write (sent as `?region=`), REQUIRED — same live-verified gate
+     *  as `create`. */
+    region: string;
+    /** New plaintext — bumps `version`. The SDK base64-encodes it for the wire. */
+    value: string;
+    metadata?: Record<string, string>;
+};
+/**
+ * `update()` result — 🔴 live-verified NARROWER than the documented `SecretSummary`: the gateway
+ * returns only `{id, name, version}` on a real PUT, not the full summary the OpenAPI schema claims.
+ * Typed to what's actually observed rather than the aspirational doc shape; call `get()` afterward if
+ * the full summary is needed.
+ */
+type UpdateSecretResult = {
+    id: string;
+    name: string;
+    version: number;
+};
+/**
+ * `rotate()` result — 🔴 live-verified shape, not documented anywhere in the OpenAPI schema (the route
+ * only declares `t.Union([SecretSummary, RevealChallengeResponse])`, which this matches neither).
+ * `ledgerSequenceNumber` is undocumented; kept as-observed.
+ */
+type RotateSecretResult = {
+    id: string;
+    name: string;
+    version: number;
+    rotatedAt: string;
+    ledgerSequenceNumber: number;
+};
+/**
+ * `move()` result — 🔴 live-verified shape, also not the documented `SecretSummary`: no `version`, and
+ * an undocumented `event` field (`"SECRET_PATH_CHANGED"` observed; typed as `string` since only one
+ * sample was seen and a closed enum can't be asserted from one observation).
+ */
+type MoveSecretResult = {
+    id: string;
+    name: string;
+    event: string;
+};
+
+export type { AttestationTier, CreateSecretInput, KmsProvider, ListSecretsInput, ListSecretsResult, MoveSecretResult, RevealChallenge, RevealSecretResult, RotateSecretResult, SecretSummary, SecretVisibility, StoreZkDekInput, UpdateSecretInput, UpdateSecretResult, ZkDekHandle, ZkDekRecord };

package/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@k9o/kibo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Kibo — Zero-Knowledge BYOK/HYOK vault SDK (client-side; composes into @k9o/core as client.kibo). ZK-DEK store/fetch (F.5) + encrypt/decrypt (thin wrappers over the audited bound core compiled to wasm).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    }
+  },
+  "files": [
+    "src",
+    "wasm",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md",
+    "dist"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/k9o-dev",
+    "directory": "packages/kibo"
+  },
+  "dependencies": {
+    "@k9o/core": "1.1.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.1.0",
+    "typescript": "^5.6.0"
+  },
+  "module": "./dist/index.js"
+}

package/src/client-factory.ts

@@ -0,0 +1,24 @@
+/**
+ * `createKiboClient(config)` — per-instance Kibo (ZK vault) SDK factory.
+ *
+ * Composes into `@k9o/core` as `client.kibo` (re-export, available when a
+ * project is bound — the same composition pattern as `@k9o/gate`). Reuses the
+ * core HTTP layer (`@k9o/core/http`) so the bearer/header/retry contract is
+ * identical to the rest of the SDK pool.
+ */
+
+import { type HttpClientConfig } from "@k9o/core/http";
+import { makeVaultNamespace } from "./vault.ts";
+
+/** Shape of the per-instance client returned by `createKiboClient`. */
+export type KiboClient = {
+  /** Vault surface — `client.kibo.vault.zkDeks.{store,fetch}` (F.5). */
+  vault: ReturnType<typeof makeVaultNamespace>;
+};
+
+/** Construct a Kibo client bound to the supplied (core) HTTP config. */
+export function createKiboClient(config: HttpClientConfig): KiboClient {
+  return {
+    vault: makeVaultNamespace(config),
+  };
+}

package/src/crypto-types.ts

@@ -0,0 +1,117 @@
+/**
+ * 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.
+ *
+ * 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:
+ *   - `KmsProvider`        kebab-case   (`aws-kms`, `gcp-kms`, `azure-kv`, `hashicorp-vault`)
+ *   - all other enums      snake_case   (`byok`, `local_envelope`, `hardware_backed`, …)
+ *   - bytes (`Vec<u8>`)    `Uint8Array` at the boundary
+ *
+ * Strict-ZK invariant: the `secret` in `KiboCredential` is a customer-issued
+ * short-lived federated token — never a platform KEK; it is zeroized in the core
+ * after use and never logged or returned. The platform never sees plaintext.
+ */
+
+// The customer KMS provider — the same routing selector as the F.5 store
+// surface. Reuse the canonical definition (no duplication).
+import type { KmsProvider } from "./types.ts";
+export type { KmsProvider };
+
+/** Custody posture for an encrypt call. `platform-managed` is structurally absent
+ *  here — `kibo-kms-rest` is the KEK-free customer-KMS layer (ZK is never PM). */
+export type KiboPosture = "byok" | "hyok";
+
+/** Explicit strategy pin. Omit → `local_envelope` (the posture default). */
+export type KiboStrategy = "local_envelope" | "customer_kms_oracle";
+
+/** Oracle routing mode. Omit → `brokered` (default). */
+export type KiboOracleMode = "brokered" | "direct";
+
+/** Device attestation tier bound into the AAD for every operation. */
+export type KiboAttestationTier = "software" | "hardware_backed" | "confidential";
+
+/** The min-custody-posture floor ladder (3-mode; `platform_managed` = no floor).
+ *  Ordering: `PLATFORM_MANAGED < BYOK < HYOK`. */
+export type KiboMinPosture = "platform_managed" | "byok" | "hyok";
+
+/** Acceptable oracle-mode set (the `allowed_oracle_modes` policy dial). */
+export interface KiboAllowedOracleModes {
+  brokered: boolean;
+  direct: boolean;
+}
+
+/** 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;
+  allowed_oracle_modes?: KiboAllowedOracleModes;
+}
+
+/** Short-lived customer KMS credential — the edge device's federated token.
+ *  `secret` is treated as secret material (zeroized in-core; never returned). */
+export interface KiboCredential {
+  secret: string;
+  expires_at_unix_secs: number;
+}
+
+/** Key version reference identifying the customer KMS key. `external_ref` is
+ *  provider-specific (AWS key ARN / GCP resource name / Azure key URL / Vault
+ *  `<mount>/<key>:<ver>`). `version` is the monotone KEK-rotation counter. */
+export interface KiboKeyRef {
+  version: number;
+  external_ref: string;
+}
+
+/** Provider-specific init params. Only the compiled-in provider's field is read. */
+export interface KiboProviderConfig {
+  aws_region?: string;
+  vault_address?: string;
+}
+
+/** A single encryption-context key/value pair. Bound into the AAD at encrypt and
+ *  re-supplied byte-for-byte at decrypt. (Record shape — uniffi can't cross
+ *  tuples; the wasm JSON is `[{"key":"…","value":"…"}]`.) `kibo:` is reserved. */
+export interface KiboKvPair {
+  key: string;
+  value: string;
+}
+
+/** All inputs to `encrypt` — mirrors Rust `EncryptInput`. */
+export interface KiboEncryptInput {
+  provider: KmsProvider;
+  posture: KiboPosture;
+  strategy?: KiboStrategy;
+  oracle_mode?: KiboOracleMode;
+  kms_cred: KiboCredential;
+  key_ref: KiboKeyRef;
+  provider_config: KiboProviderConfig;
+  attestation_tier: KiboAttestationTier;
+  encryption_context: KiboKvPair[];
+  /** Plaintext bytes to encrypt. */
+  plaintext: Uint8Array;
+  posture_policy?: KiboPosturePolicy;
+}
+
+/** All inputs to `decrypt` — mirrors Rust `DecryptInput`. `strategy`,
+ *  `attestation_tier`, and `encryption_context` MUST be re-supplied (never read
+ *  from the envelope — anti-envelope-substitution discipline). */
+export interface KiboDecryptInput {
+  kms_cred: KiboCredential;
+  provider_config: KiboProviderConfig;
+  /** The canonical (`b"KIBO"`) envelope from a prior `encrypt`. */
+  envelope: Uint8Array;
+  strategy: KiboStrategy;
+  attestation_tier: KiboAttestationTier;
+  encryption_context: KiboKvPair[];
+}
+
+/** Output of `encrypt` — the opaque ZKFE envelope (pass straight to `decrypt`). */
+export interface KiboEncryptOutput {
+  envelope: Uint8Array;
+}
+
+/** Output of `decrypt` — the recovered plaintext. */
+export interface KiboDecryptOutput {
+  plaintext: Uint8Array;
+}

package/src/crypto.ts

@@ -0,0 +1,133 @@
+/**
+ * ZK encrypt/decrypt — the thin TS 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 → `KError`.
+ *
+ * The core exposes `zk_encrypt`/`zk_decrypt` (async) taking/returning plain JS
+ * objects via serde-wasm-bindgen, and rejecting with the `ZkFfiError` display
+ * string (`"<K9O_CODE>: <message>"`, optionally with a posture-violation tail).
+ *
+ * Composes into `@k9o/core` as `client.kibo.encrypt`/`decrypt`; the F.5
+ * `vault.zkDeks.{store,fetch}` surface (envelope persistence) is separate +
+ * decoupled (the core never sees the store).
+ */
+
+import { KError } from "@k9o/core/errors";
+import type {
+  KiboEncryptInput,
+  KiboEncryptOutput,
+  KiboDecryptInput,
+  KiboDecryptOutput,
+} from "./crypto-types.ts";
+
+/** 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 cachedWasm: ZkWasm | undefined;
+
+/**
+ * Inject a pre-loaded core wasm module. Hosts that bundle the wasm themselves
+ * (browser/RN, or a test) call this; otherwise `encrypt`/`decrypt` lazy-load
+ * the vendored per-provider artifact.
+ */
+export function setZkWasm(mod: ZkWasm): void {
+  cachedWasm = mod;
+}
+
+/**
+ * Lazily load the bound core wasm. ONE all-provider artifact is generated from
+ * `kibo-kms-rest-ffi` (the core compiles every v2 KMS provider in; the
+ * `provider` input field selects at call time), vendored under `wasm/` by the
+ * publish pipeline and gitignored in-repo. The specifier is assembled at
+ * runtime so the bundler/typechecker must not hard-resolve it — the contract
+ * is the `ZkWasm` interface above.
+ */
+async function loadWasm(): Promise<ZkWasm> {
+  if (cachedWasm) return cachedWasm;
+  const pkg = ["..", "wasm", "kibo_kms_rest_ffi.js"].join("/");
+  try {
+    cachedWasm = (await import(pkg)) as unknown as ZkWasm;
+  } catch {
+    // A package published without its native core (no bundle at publish time). Say so; never surface a bare
+    // module-resolution error, and do not cache the failure.
+    throw new KError({
+      code: "KIBO_WASM_ERROR",
+      message: "the Kibo zero-knowledge core (wasm) is not bundled in this build of @k9o/kibo; encrypt and decrypt are unavailable",
+      context: {},
+      recommendation: "Install a release of @k9o/kibo that ships the core, or load it yourself.",
+    });
+  }
+  return cachedWasm;
+}
+
+/**
+ * Encrypt `input.plaintext` via the customer KMS, client-side. Returns the
+ * opaque ZKFE envelope — store it via `vault.zkDeks.store` (F.5) or keep it
+ * yourself; it is meaningless to the platform.
+ */
+export async function encrypt(input: KiboEncryptInput): Promise<KiboEncryptOutput> {
+  const wasm = await loadWasm();
+  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 = await loadWasm();
+  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 KError({
+    code: "KIBO_WASM_DECODE_ERROR",
+    message: "ZK core returned a non-byte value where bytes were expected",
+    context: {},
+  });
+}
+
+/**
+ * Map the core's rejected error → `KError`. 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), per the KError discipline.
+ */
+function mapZkError(e: unknown): KError {
+  if (e instanceof KError) 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 KError({ code, message, context });
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * `@k9o/kibo` — Zero-Knowledge BYOK/HYOK vault SDK (client-side).
+ *
+ * Composes into `@k9o/core` as `client.kibo`. Two surfaces:
+ *   - F.5 ZK-DEK store/fetch — `vault.zkDeks.{store,fetch}`;
+ *     decoupled, gateway-only opaque-blob persistence.
+ *   - ZK `encrypt`/`decrypt` (/) — thin wrappers over the
+ *     audited core (piece C, `kibo-kms-rest-ffi` compiled to wasm).
+ *
+ * Zero crypto in this package: every wrap/unwrap, envelope framing, and
+ * posture-floor enforcement lives in the bound core; the SDK only marshals
+ * typed input across the wasm boundary + ships/retrieves opaque blobs.
+ */
+
+export { createKiboClient, type KiboClient } from "./client-factory.ts";
+export { makeVaultNamespace } from "./vault.ts";
+export type {
+  KmsProvider, StoreZkDekInput, ZkDekHandle, ZkDekRecord,
+  SecretVisibility, CreateSecretInput, SecretSummary,
+  ListSecretsInput, ListSecretsResult, AttestationTier, RevealChallenge, RevealSecretResult,
+  UpdateSecretInput, UpdateSecretResult, RotateSecretResult, MoveSecretResult,
+} from "./types.ts";
+
+// ZK encrypt/decrypt (bound-core wasm). The ergonomic client-bound surface
+// (gathering provider/posture/key-ref from config) composes per the
+// method-shape contract; these are the FFI-mapped primitives it builds on.
+export { encrypt, decrypt, setZkWasm, type ZkWasm } from "./crypto.ts";
+export type {
+  KiboPosture, KiboStrategy, KiboOracleMode, KiboAttestationTier, KiboMinPosture,
+  KiboAllowedOracleModes, KiboPosturePolicy, KiboCredential, KiboKeyRef,
+  KiboProviderConfig, KiboKvPair, KiboEncryptInput, KiboEncryptOutput,
+  KiboDecryptInput, KiboDecryptOutput,
+} from "./crypto-types.ts";