@k9o/kibo 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,259 @@
+// src/client-factory.ts
+import "@k9o/core/http";
+
+// src/vault.ts
+import { request } from "@k9o/core/http";
+import { projectPath } from "@k9o/core/url-grammar";
+import { KError } from "@k9o/core/errors";
+function encodeBase64Utf8(plaintext) {
+  return btoa(unescape(encodeURIComponent(plaintext)));
+}
+function decodeBase64Utf8(b64) {
+  return decodeURIComponent(escape(atob(b64)));
+}
+function requireProjectSlug(config) {
+  if (config.projectSlug === void 0 || config.projectSlug.length === 0) {
+    throw new KError({
+      code: "K9O_MISSING_PROJECT_CONTEXT",
+      message: "client.kibo.vault requires a bound projectSlug (member-plane resource)",
+      context: {},
+      recommendation: "Pass projectSlug when constructing the client."
+    });
+  }
+  return config.projectSlug;
+}
+function makeVaultNamespace(config) {
+  return {
+    /** ZK-DEK opaque store/fetch (ch08 §11.3.2 F.5). */
+    zkDeks: {
+      /**
+       * Store an opaque customer-wrapped DEK envelope.
+       * `POST /@<projectSlug>/vault/zk-deks` → the `zkdek_<base62>` handle.
+       * The SDK ships the envelope verbatim; it is never parsed here.
+       */
+      async store(input) {
+        return request(config, {
+          method: "POST",
+          path: projectPath(requireProjectSlug(config), "vault/zk-deks"),
+          body: input
+        });
+      },
+      /**
+       * Fetch a stored `WrappedDek` by its handle.
+       * `GET /@<projectSlug>/vault/zk-deks/<id>` → the opaque envelope + the
+       * non-secret `provider`/`keyVersionRef` the caller needs to unwrap it.
+       */
+      async fetch(id) {
+        return request(config, {
+          method: "GET",
+          path: projectPath(requireProjectSlug(config), `vault/zk-deks/${encodeURIComponent(id)}`)
+        });
+      }
+    },
+    /**
+     * §14 typed secrets surface (`services/gateway/src/routes/vault-secrets.ts`) — the full family:
+     * list/get/create/revealChallenge/reveal/update/rotate/move/delete. Every operation on a NAMED
+     * secret (everything except `list`) requires `region` — live-verified against staging, not
+     * documented in the route's OpenAPI schema. `list` is the one exception (verified it does NOT
+     * need `region`).
+     *
+     * Response shapes for `update`/`rotate`/`move` are typed to what the gateway ACTUALLY returns
+     * (live-verified), not the OpenAPI's documented (and inaccurate for these three) `SecretSummary` —
+     * see the 🔴 notes on `UpdateSecretResult`/`RotateSecretResult`/`MoveSecretResult` in `types.ts`.
+     */
+    secrets: {
+      /** List secrets (metadata only — never lists ciphertext). `GET /@<projectSlug>/vault/secrets`.
+       *  The one secrets operation that does NOT need `region` (live-verified). */
+      async list(input) {
+        return request(config, {
+          method: "GET",
+          path: projectPath(requireProjectSlug(config), "vault/secrets"),
+          query: { prefix: input?.prefix, cursor: input?.cursor, limit: input?.limit }
+        });
+      },
+      /**
+       * Read a secret's metadata (never its value — use `revealChallenge`+`reveal` for that).
+       * `GET /@<projectSlug>/vault/secrets/<name>?region=<region>`.
+       *
+       * 🔴 KNOWN LIVE BUG (staging, 2026-09-05): this call currently fails with
+       * `K9O_REVEAL_CHALLENGE_REQUIRED` on every attempt — the gateway/kibo does not honor the
+       * documented "no `X-K9O-Reveal-Challenge` header ⇒ return metadata" behavior; it demands a
+       * challenge unconditionally. Implemented per the documented contract (this is a backend defect,
+       * not a client workaround); `list({prefix: exactName})` is the current working alternative for a
+       * single secret's metadata until the gateway/kibo side is fixed.
+       */
+      async get(name, opts) {
+        return request(config, {
+          method: "GET",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { region: opts.region }
+        });
+      },
+      /**
+       * Create a secret under the caller's own auth.
+       * `POST /@<projectSlug>/vault/secrets/<name>?region=<region>` → the `sec_<base62>` summary.
+       *
+       * 🔴 `region` is REQUIRED on the query string, live-verified against staging — the vault-forward
+       * proxy fail-closes with `K9O_INVALID_FIELD_VALUE` ("this request requires an authoritative
+       * region") without it. Distinct from any `region` carried inside `input.value`'s envelope (e.g.
+       * the BYOS aws_sigv4 STS-signing region): this one scopes the vault WRITE itself, mirroring the
+       * gateway's `gatewayRegion()` residency guard (region-guard.ts) that closed a 2026-08 wrong-region
+       * incident for the audit path — the request-shape unit tests never caught this because they don't
+       * exercise a real gateway.
+       */
+      async create(input) {
+        const { name, region, value, ...rest } = input;
+        return request(config, {
+          method: "POST",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { region },
+          // Live-verified against staging: the wire `value` MUST be base64 — a raw plaintext string
+          // (matching the route's own "the plaintext to seal" OpenAPI description literally) is
+          // rejected with K9O_INVALID_FIELD_VALUE "Request body could not be parsed." `input.value`
+          // stays the caller-facing plaintext; base64 is purely a wire-transport detail handled here.
+          body: { ...rest, value: encodeBase64Utf8(value) }
+        });
+      },
+      /** Mint a single-use reveal challenge — present it as `X-K9O-Reveal-Challenge` on the
+       *  immediately-following `reveal()` call. `POST .../<name>?op=reveal-challenge&region=<region>`. */
+      async revealChallenge(name, opts) {
+        return request(config, {
+          method: "POST",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { op: "reveal-challenge", region: opts.region }
+        });
+      },
+      /** Reveal a secret's plaintext value using a single-use challenge from `revealChallenge()`.
+       *  `GET .../<name>?region=<region>` with `X-K9O-Reveal-Challenge`. Decodes the wire's base64
+       *  `value` back to plaintext (live-verified: the reveal response's `value` is base64, symmetric
+       *  with `create`'s encode). */
+      async reveal(name, opts) {
+        const envelope = await request(config, {
+          method: "GET",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { region: opts.region },
+          headers: { "X-K9O-Reveal-Challenge": opts.challenge }
+        });
+        return { ...envelope, data: { ...envelope.data, value: decodeBase64Utf8(envelope.data.value) } };
+      },
+      /** Update a secret's value (bumps version) — owner-only. `PUT .../<name>?region=<region>`.
+       *  🔴 Returns only `{id, name, version}` live (see `UpdateSecretResult`), not the full summary
+       *  the OpenAPI schema documents — call `get()` after if you need the rest. */
+      async update(name, input) {
+        return request(config, {
+          method: "PUT",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { region: input.region },
+          body: { value: encodeBase64Utf8(input.value), ...input.metadata !== void 0 ? { metadata: input.metadata } : {} }
+        });
+      },
+      /** Rotate a secret's wrapping key (re-wraps under a fresh `kid`; content unchanged) — owner-only.
+       *  `POST .../<name>?op=rotate&region=<region>`. */
+      async rotate(name, opts) {
+        return request(config, {
+          method: "POST",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { op: "rotate", region: opts.region }
+        });
+      },
+      /** Move (rename) a secret's hierarchical path — owner-only.
+       *  `POST .../<name>?op=move&region=<region>`. */
+      async move(name, opts) {
+        return request(config, {
+          method: "POST",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { op: "move", region: opts.region },
+          body: { newPath: opts.newPath }
+        });
+      },
+      /** Retire a secret — owner-only. `DELETE .../<name>?region=<region>` → `204 No Content`. */
+      async delete(name, opts) {
+        return request(config, {
+          method: "DELETE",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { region: opts.region }
+        });
+      }
+    }
+  };
+}
+
+// src/client-factory.ts
+function createKiboClient(config) {
+  return {
+    vault: makeVaultNamespace(config)
+  };
+}
+
+// src/crypto.ts
+import { KError as KError2 } from "@k9o/core/errors";
+var cachedWasm;
+function setZkWasm(mod) {
+  cachedWasm = mod;
+}
+async function loadWasm() {
+  if (cachedWasm) return cachedWasm;
+  const pkg = ["..", "wasm", "kibo_kms_rest_ffi.js"].join("/");
+  try {
+    cachedWasm = await import(pkg);
+  } catch {
+    throw new KError2({
+      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;
+}
+async function encrypt(input) {
+  const wasm = await loadWasm();
+  let out;
+  try {
+    out = await wasm.zk_encrypt(input);
+  } catch (e) {
+    throw mapZkError(e);
+  }
+  return { envelope: toBytes(out.envelope) };
+}
+async function decrypt(input) {
+  const wasm = await loadWasm();
+  let out;
+  try {
+    out = await wasm.zk_decrypt(input);
+  } catch (e) {
+    throw mapZkError(e);
+  }
+  return { plaintext: toBytes(out.plaintext) };
+}
+function toBytes(v) {
+  if (v instanceof Uint8Array) return v;
+  if (Array.isArray(v)) return Uint8Array.from(v);
+  throw new KError2({
+    code: "KIBO_WASM_DECODE_ERROR",
+    message: "ZK core returned a non-byte value where bytes were expected",
+    context: {}
+  });
+}
+function mapZkError(e) {
+  if (e instanceof KError2) 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 = {};
+  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 KError2({ code, message, context });
+}
+export {
+  createKiboClient,
+  decrypt,
+  encrypt,
+  makeVaultNamespace,
+  setZkWasm
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client-factory.ts","../src/vault.ts","../src/crypto.ts"],"sourcesContent":["/**\n * `createKiboClient(config)` — per-instance Kibo (ZK vault) SDK factory.\n *\n * Composes into `@k9o/core` as `client.kibo` (re-export, available when a\n * project is bound — the same composition pattern as `@k9o/gate`). Reuses the\n * core HTTP layer (`@k9o/core/http`) so the bearer/header/retry contract is\n * identical to the rest of the SDK pool.\n */\n\nimport { type HttpClientConfig } from \"@k9o/core/http\";\nimport { makeVaultNamespace } from \"./vault.ts\";\n\n/** Shape of the per-instance client returned by `createKiboClient`. */\nexport type KiboClient = {\n  /** Vault surface — `client.kibo.vault.zkDeks.{store,fetch}` (ch08 §11.3.2 F.5). */\n  vault: ReturnType<typeof makeVaultNamespace>;\n};\n\n/** Construct a Kibo client bound to the supplied (core) HTTP config. */\nexport function createKiboClient(config: HttpClientConfig): KiboClient {\n  return {\n    vault: makeVaultNamespace(config),\n  };\n}\n","/**\n * `client.kibo.vault.*` — the Kibo vault surface.\n *\n * v0.1.0: `vault.zkDeks.{store,fetch}` (ch08 §11.3.2 F.5) — member-plane,\n * project-scoped storage of the opaque customer-wrapped DEK envelope. Zero\n * crypto SDK-side: this is a plain authenticated REST round-trip carrying an\n * opaque blob (the wrapping happens in the ZK core, piece C). The encryption\n * surface (`kibo.encrypt`/`decrypt`) lands in a later version once the C\n * binding is consumable.\n */\n\nimport { request, type HttpClientConfig } from \"@k9o/core/http\";\nimport { projectPath } from \"@k9o/core/url-grammar\";\nimport { KError } from \"@k9o/core/errors\";\nimport type { Envelope } from \"@k9o/core/envelope\";\nimport type {\n  StoreZkDekInput, ZkDekHandle, ZkDekRecord,\n  CreateSecretInput, SecretSummary, ListSecretsInput, ListSecretsResult,\n  RevealChallenge, RevealSecretResult, UpdateSecretInput, UpdateSecretResult,\n  RotateSecretResult, MoveSecretResult,\n} from \"./types.ts\";\n\n/** UTF-8-safe base64 encode, usable across browser/Node/Bun (unlike `Buffer`) — the vault-secrets wire\n *  `value` field is base64 (live-verified; the OpenAPI \"plaintext to seal\" description does not mean\n *  raw-on-the-wire). */\nfunction encodeBase64Utf8(plaintext: string): string {\n  return btoa(unescape(encodeURIComponent(plaintext)));\n}\n\n/** Inverse of {@link encodeBase64Utf8} — decodes a revealed wire `value` back to plaintext. */\nfunction decodeBase64Utf8(b64: string): string {\n  return decodeURIComponent(escape(atob(b64)));\n}\n\n/** Both `vault.zkDeks` and `vault.secrets` require a project context (member-plane, ch08 §11.3/§14). */\nfunction requireProjectSlug(config: HttpClientConfig): string {\n  if (config.projectSlug === undefined || config.projectSlug.length === 0) {\n    throw new KError({\n      code: \"K9O_MISSING_PROJECT_CONTEXT\",\n      message: \"client.kibo.vault requires a bound projectSlug (member-plane resource)\",\n      context: {},\n      recommendation: \"Pass projectSlug when constructing the client.\",\n    });\n  }\n  return config.projectSlug;\n}\n\nexport function makeVaultNamespace(config: HttpClientConfig) {\n  return {\n    /** ZK-DEK opaque store/fetch (ch08 §11.3.2 F.5). */\n    zkDeks: {\n      /**\n       * Store an opaque customer-wrapped DEK envelope.\n       * `POST /@<projectSlug>/vault/zk-deks` → the `zkdek_<base62>` handle.\n       * The SDK ships the envelope verbatim; it is never parsed here.\n       */\n      async store(input: StoreZkDekInput): Promise<Envelope<ZkDekHandle>> {\n        return request<ZkDekHandle>(config, {\n          method: \"POST\",\n          path: projectPath(requireProjectSlug(config), \"vault/zk-deks\"),\n          body: input,\n        });\n      },\n\n      /**\n       * Fetch a stored `WrappedDek` by its handle.\n       * `GET /@<projectSlug>/vault/zk-deks/<id>` → the opaque envelope + the\n       * non-secret `provider`/`keyVersionRef` the caller needs to unwrap it.\n       */\n      async fetch(id: string): Promise<Envelope<ZkDekRecord>> {\n        return request<ZkDekRecord>(config, {\n          method: \"GET\",\n          path: projectPath(requireProjectSlug(config), `vault/zk-deks/${encodeURIComponent(id)}`),\n        });\n      },\n    },\n\n    /**\n     * §14 typed secrets surface (`services/gateway/src/routes/vault-secrets.ts`) — the full family:\n     * list/get/create/revealChallenge/reveal/update/rotate/move/delete. Every operation on a NAMED\n     * secret (everything except `list`) requires `region` — live-verified against staging, not\n     * documented in the route's OpenAPI schema. `list` is the one exception (verified it does NOT\n     * need `region`).\n     *\n     * Response shapes for `update`/`rotate`/`move` are typed to what the gateway ACTUALLY returns\n     * (live-verified), not the OpenAPI's documented (and inaccurate for these three) `SecretSummary` —\n     * see the 🔴 notes on `UpdateSecretResult`/`RotateSecretResult`/`MoveSecretResult` in `types.ts`.\n     */\n    secrets: {\n      /** List secrets (metadata only — never lists ciphertext). `GET /@<projectSlug>/vault/secrets`.\n       *  The one secrets operation that does NOT need `region` (live-verified). */\n      async list(input?: ListSecretsInput): Promise<Envelope<ListSecretsResult>> {\n        return request<ListSecretsResult>(config, {\n          method: \"GET\",\n          path: projectPath(requireProjectSlug(config), \"vault/secrets\"),\n          query: { prefix: input?.prefix, cursor: input?.cursor, limit: input?.limit },\n        });\n      },\n\n      /**\n       * Read a secret's metadata (never its value — use `revealChallenge`+`reveal` for that).\n       * `GET /@<projectSlug>/vault/secrets/<name>?region=<region>`.\n       *\n       * 🔴 KNOWN LIVE BUG (staging, 2026-09-05): this call currently fails with\n       * `K9O_REVEAL_CHALLENGE_REQUIRED` on every attempt — the gateway/kibo does not honor the\n       * documented \"no `X-K9O-Reveal-Challenge` header ⇒ return metadata\" behavior; it demands a\n       * challenge unconditionally. Implemented per the documented contract (this is a backend defect,\n       * not a client workaround); `list({prefix: exactName})` is the current working alternative for a\n       * single secret's metadata until the gateway/kibo side is fixed.\n       */\n      async get(name: string, opts: { region: string }): Promise<Envelope<SecretSummary>> {\n        return request<SecretSummary>(config, {\n          method: \"GET\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { region: opts.region },\n        });\n      },\n\n      /**\n       * Create a secret under the caller's own auth.\n       * `POST /@<projectSlug>/vault/secrets/<name>?region=<region>` → the `sec_<base62>` summary.\n       *\n       * 🔴 `region` is REQUIRED on the query string, live-verified against staging — the vault-forward\n       * proxy fail-closes with `K9O_INVALID_FIELD_VALUE` (\"this request requires an authoritative\n       * region\") without it. Distinct from any `region` carried inside `input.value`'s envelope (e.g.\n       * the BYOS aws_sigv4 STS-signing region): this one scopes the vault WRITE itself, mirroring the\n       * gateway's `gatewayRegion()` residency guard (region-guard.ts) that closed a 2026-08 wrong-region\n       * incident for the audit path — the request-shape unit tests never caught this because they don't\n       * exercise a real gateway.\n       */\n      async create(input: CreateSecretInput): Promise<Envelope<SecretSummary>> {\n        const { name, region, value, ...rest } = input;\n        return request<SecretSummary>(config, {\n          method: \"POST\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { region },\n          // Live-verified against staging: the wire `value` MUST be base64 — a raw plaintext string\n          // (matching the route's own \"the plaintext to seal\" OpenAPI description literally) is\n          // rejected with K9O_INVALID_FIELD_VALUE \"Request body could not be parsed.\" `input.value`\n          // stays the caller-facing plaintext; base64 is purely a wire-transport detail handled here.\n          body: { ...rest, value: encodeBase64Utf8(value) },\n        });\n      },\n\n      /** Mint a single-use reveal challenge — present it as `X-K9O-Reveal-Challenge` on the\n       *  immediately-following `reveal()` call. `POST .../<name>?op=reveal-challenge&region=<region>`. */\n      async revealChallenge(name: string, opts: { region: string }): Promise<Envelope<RevealChallenge>> {\n        return request<RevealChallenge>(config, {\n          method: \"POST\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { op: \"reveal-challenge\", region: opts.region },\n        });\n      },\n\n      /** Reveal a secret's plaintext value using a single-use challenge from `revealChallenge()`.\n       *  `GET .../<name>?region=<region>` with `X-K9O-Reveal-Challenge`. Decodes the wire's base64\n       *  `value` back to plaintext (live-verified: the reveal response's `value` is base64, symmetric\n       *  with `create`'s encode). */\n      async reveal(name: string, opts: { region: string; challenge: string }): Promise<Envelope<RevealSecretResult>> {\n        const envelope = await request<RevealSecretResult>(config, {\n          method: \"GET\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { region: opts.region },\n          headers: { \"X-K9O-Reveal-Challenge\": opts.challenge },\n        });\n        return { ...envelope, data: { ...envelope.data, value: decodeBase64Utf8(envelope.data.value) } };\n      },\n\n      /** Update a secret's value (bumps version) — owner-only. `PUT .../<name>?region=<region>`.\n       *  🔴 Returns only `{id, name, version}` live (see `UpdateSecretResult`), not the full summary\n       *  the OpenAPI schema documents — call `get()` after if you need the rest. */\n      async update(name: string, input: UpdateSecretInput): Promise<Envelope<UpdateSecretResult>> {\n        return request<UpdateSecretResult>(config, {\n          method: \"PUT\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { region: input.region },\n          body: { value: encodeBase64Utf8(input.value), ...(input.metadata !== undefined ? { metadata: input.metadata } : {}) },\n        });\n      },\n\n      /** Rotate a secret's wrapping key (re-wraps under a fresh `kid`; content unchanged) — owner-only.\n       *  `POST .../<name>?op=rotate&region=<region>`. */\n      async rotate(name: string, opts: { region: string }): Promise<Envelope<RotateSecretResult>> {\n        return request<RotateSecretResult>(config, {\n          method: \"POST\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { op: \"rotate\", region: opts.region },\n        });\n      },\n\n      /** Move (rename) a secret's hierarchical path — owner-only.\n       *  `POST .../<name>?op=move&region=<region>`. */\n      async move(name: string, opts: { region: string; newPath: string }): Promise<Envelope<MoveSecretResult>> {\n        return request<MoveSecretResult>(config, {\n          method: \"POST\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { op: \"move\", region: opts.region },\n          body: { newPath: opts.newPath },\n        });\n      },\n\n      /** Retire a secret — owner-only. `DELETE .../<name>?region=<region>` → `204 No Content`. */\n      async delete(name: string, opts: { region: string }): Promise<Envelope<void>> {\n        return request<void>(config, {\n          method: \"DELETE\",\n          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),\n          query: { region: opts.region },\n        });\n      },\n    },\n  };\n}\n","/**\n * ZK encrypt/decrypt — the thin TS wrapper over the bound crypto core\n * (`kibo-kms-rest-ffi`, piece C) compiled to wasm. ZERO crypto here: every\n * wrap/unwrap, envelope framing, posture-floor enforcement, and KMS round-trip\n * lives in the audited Rust core. This layer only marshals the typed input\n * across the wasm boundary and maps the core's error string → `KError`.\n *\n * The core exposes `zk_encrypt`/`zk_decrypt` (async) taking/returning plain JS\n * objects via serde-wasm-bindgen, and rejecting with the `ZkFfiError` display\n * string (`\"<K9O_CODE>: <message>\"`, optionally with a posture-violation tail).\n *\n * Composes into `@k9o/core` as `client.kibo.encrypt`/`decrypt`; the F.5\n * `vault.zkDeks.{store,fetch}` surface (envelope persistence) is separate +\n * decoupled (the core never sees the store).\n */\n\nimport { KError } from \"@k9o/core/errors\";\nimport type {\n  KiboEncryptInput,\n  KiboEncryptOutput,\n  KiboDecryptInput,\n  KiboDecryptOutput,\n} from \"./crypto-types.ts\";\n\n/** The minimal surface the bound ZK-core wasm exposes. */\nexport interface ZkWasm {\n  zk_encrypt(input: unknown): Promise<unknown>;\n  zk_decrypt(input: unknown): Promise<unknown>;\n}\n\nlet cachedWasm: ZkWasm | undefined;\n\n/**\n * Inject a pre-loaded core wasm module. Hosts that bundle the wasm themselves\n * (browser/RN, or a test) call this; otherwise `encrypt`/`decrypt` lazy-load\n * the vendored per-provider artifact.\n */\nexport function setZkWasm(mod: ZkWasm): void {\n  cachedWasm = mod;\n}\n\n/**\n * Lazily load the bound core wasm. ONE all-provider artifact is generated from\n * `kibo-kms-rest-ffi` (the core compiles every v2 KMS provider in; the\n * `provider` input field selects at call time), vendored under `wasm/` by the\n * publish pipeline and gitignored in-repo. The specifier is assembled at\n * runtime so the bundler/typechecker must not hard-resolve it — the contract\n * is the `ZkWasm` interface above.\n */\nasync function loadWasm(): Promise<ZkWasm> {\n  if (cachedWasm) return cachedWasm;\n  const pkg = [\"..\", \"wasm\", \"kibo_kms_rest_ffi.js\"].join(\"/\");\n  try {\n    cachedWasm = (await import(pkg)) as unknown as ZkWasm;\n  } catch {\n    // A package published without its native core (no bundle at publish time). Say so; never surface a bare\n    // module-resolution error, and do not cache the failure.\n    throw new KError({\n      code: \"KIBO_WASM_ERROR\",\n      message: \"the Kibo zero-knowledge core (wasm) is not bundled in this build of @k9o/kibo; encrypt and decrypt are unavailable\",\n      context: {},\n      recommendation: \"Install a release of @k9o/kibo that ships the core, or load it yourself.\",\n    });\n  }\n  return cachedWasm;\n}\n\n/**\n * Encrypt `input.plaintext` via the customer KMS, client-side. Returns the\n * opaque ZKFE envelope — store it via `vault.zkDeks.store` (F.5) or keep it\n * yourself; it is meaningless to the platform.\n */\nexport async function encrypt(input: KiboEncryptInput): Promise<KiboEncryptOutput> {\n  const wasm = await loadWasm();\n  let out: unknown;\n  try {\n    out = await wasm.zk_encrypt(input);\n  } catch (e) {\n    throw mapZkError(e);\n  }\n  return { envelope: toBytes((out as { envelope?: unknown }).envelope) };\n}\n\n/**\n * Decrypt a ZKFE `input.envelope`. `strategy`, `attestation_tier`, and\n * `encryption_context` MUST match the values used at encrypt — they are AAD-bound\n * and never recovered from the envelope (anti-substitution discipline).\n */\nexport async function decrypt(input: KiboDecryptInput): Promise<KiboDecryptOutput> {\n  const wasm = await loadWasm();\n  let out: unknown;\n  try {\n    out = await wasm.zk_decrypt(input);\n  } catch (e) {\n    throw mapZkError(e);\n  }\n  return { plaintext: toBytes((out as { plaintext?: unknown }).plaintext) };\n}\n\n/** Normalise wasm byte output (serde-wasm-bindgen emits `Vec<u8>` as a number\n *  array; some hosts return a `Uint8Array`) to `Uint8Array`. */\nfunction toBytes(v: unknown): Uint8Array {\n  if (v instanceof Uint8Array) return v;\n  if (Array.isArray(v)) return Uint8Array.from(v as number[]);\n  throw new KError({\n    code: \"KIBO_WASM_DECODE_ERROR\",\n    message: \"ZK core returned a non-byte value where bytes were expected\",\n    context: {},\n  });\n}\n\n/**\n * Map the core's rejected error → `KError`. The wasm path flattens `ZkFfiError`\n * to its display string: `\"<CODE>: <message>\"` where `<CODE>` is a `K9O_*` wire\n * code (or `UPSTREAM_KMS_ERROR` for the customer's own KMS failures), optionally\n * followed by `\"(dimension: …, requested: …, declared: …)\"` for a posture-floor\n * violation. Codes are passed through (never hardcoded), per the KError discipline.\n */\nfunction mapZkError(e: unknown): KError {\n  if (e instanceof KError) return e;\n  const raw = e instanceof Error ? e.message : String(e);\n  const head = /^([A-Z][A-Z0-9_]*):\\s*([\\s\\S]*)$/.exec(raw);\n  const code = head?.[1] ?? \"KIBO_WASM_ERROR\";\n  let message = head?.[2] ?? raw;\n\n  let context: Record<string, unknown> = {};\n  const pv = /\\(dimension:\\s*([^,]+),\\s*requested:\\s*([^,]+),\\s*declared:\\s*([^)]+)\\)\\s*$/.exec(message);\n  if (pv) {\n    context = { dimension: pv[1]!.trim(), requested: pv[2]!.trim(), declared: pv[3]!.trim() };\n    message = message.slice(0, pv.index).trim();\n  }\n  return new KError({ code, message, context });\n}\n"],"mappings":"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","names":["KError"]}

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `@k9o/kibo` — Zero-Knowledge BYOK/HYOK vault SDK types.
+ *
+ * v0.1.0 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;
+};
+/** §14.2 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 (ch08 §14) — `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;
+};
+/** §14.10 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.0.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.0.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}` (ch08 §11.3.2 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),
+  };
+}