@k9o/kibo 1.2.0 → 1.3.0

package/src/crypto.ts

@@ -1,6 +1,6 @@
 /**
  * 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
+ * (`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 → `KError`.
@@ -9,12 +9,13 @@
  * 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).
+ * These are standalone exports (`import { encrypt, decrypt } from "@k9o/kibo"`), not methods of the client: they run
+ * locally against the customer's own KMS and make no platform call. The `vault.zkDeks.{store,fetch}` surface
+ * (envelope persistence) is separate and decoupled (the core never sees the store).
  */
 
 import { KError } from "@k9o/core/errors";
+import { loadZkGlue, nodeDeps } from "./wasm-loader.ts";
 import type {
   KiboEncryptInput,
   KiboEncryptOutput,
@@ -40,34 +41,20 @@ export function setZkWasm(mod: ZkWasm): void {
 }
 
 /**
- * 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.
+ * Lazily load the bound core wasm. ONE all-provider artifact is generated from `kibo-kms-rest-ffi` (the core compiles
+ * every KMS provider in; the `provider` input field selects at call time) and vendored under `wasm/` by the publish
+ * pipeline. See `wasm-loader.ts` for how the CommonJS glue is loaded from this ESM package and for the failure modes.
  */
 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.",
-    });
-  }
+  // A failure is not cached: the next call tries again.
+  cachedWasm = await loadZkGlue(nodeDeps(import.meta.url));
   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
+ * opaque ZKFE envelope — store it via `vault.zkDeks.store`  or keep it
  * yourself; it is meaningless to the platform.
  */
 export async function encrypt(input: KiboEncryptInput): Promise<KiboEncryptOutput> {

package/src/index.ts

@@ -1,19 +1,16 @@
 /**
- * `@k9o/kibo` — Zero-Knowledge BYOK/HYOK vault SDK (client-side).
+ * `@k9o/kibo` - Zero-Knowledge BYOK/HYOK vault SDK.
  *
- * 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).
+ * Two surfaces:
+ *   - the vault client (`createKiboClient`; composed into `@k9o/core` as `client.kibo`): `vault.secrets.*` and
+ *     `vault.zkDeks.{store,fetch}`, plain REST calls to the platform.
+ *   - standalone `encrypt` / `decrypt`: local envelope encryption against the customer's own KMS, in WASM, with no
+ *     platform call. They are not methods of the client. `setZkWasm` supplies the WASM core yourself.
  *
- * 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.
+ * No cryptography lives in this package: wrapping, envelope framing and posture-floor enforcement are in the compiled core.
  */
 
 export { createKiboClient, type KiboClient } from "./client-factory.ts";
-export { makeVaultNamespace } from "./vault.ts";
 export type {
   KmsProvider, StoreZkDekInput, ZkDekHandle, ZkDekRecord,
   SecretVisibility, CreateSecretInput, SecretSummary,
@@ -21,9 +18,7 @@ export type {
   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.
+// Standalone zero-knowledge encrypt/decrypt (bound-core wasm).
 export { encrypt, decrypt, setZkWasm, type ZkWasm } from "./crypto.ts";
 export type {
   KiboPosture, KiboStrategy, KiboOracleMode, KiboAttestationTier, KiboMinPosture,

package/src/types.ts

@@ -1,11 +1,9 @@
 /**
  * `@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.
+ * Surface: the ZK-DEK store/fetch and the secrets family. The wrapped
+ * envelope is produced client-side by the ZK core (compiled to wasm); this SDK ships it
+ * **verbatim and opaque** and never reads its interior.
  */
 
 /** Customer KMS/HSM provider — non-secret routing metadata (mirrors the ZK FFI provider selector). */
@@ -42,24 +40,19 @@ export type ZkDekRecord = {
   createdAt: string;
 };
 
-/** secret visibility — write ops (create/update) stay owner-only regardless of this tag. */
+/** Secret visibility. Write operations (create/update) stay owner-only regardless of this tag. */
 export type SecretVisibility =
   | { kind: "private" }
   | { kind: "shared"; principals?: string[]; roles?: string[] };
 
-/** Input to create a vault secret — `POST /@<projectSlug>/vault/secrets/<name>?region=<region>`. */
+/** Input to create a vault secret: `POST /@<projectSlug>/vault/secrets/<name>`. */
 export 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). */
+  /** The plaintext to seal, as a regular (non-base64) string; `vault.secrets.create` base64-encodes it for the wire. */
   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;
+  /** Optional. The gateway sets the residency region of the write itself and discards this; it is sent only when given. */
+  region?: string;
   visibility?: SecretVisibility;
   metadata?: Record<string, string>;
 };
@@ -83,8 +76,7 @@ export type SecretSummary = {
   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). */
+/** `client.kibo.vault.secrets.list()` input. */
 export type ListSecretsInput = {
   /** Filter to a path prefix. */
   prefix?: string;
@@ -97,7 +89,7 @@ export type ListSecretsResult = {
   nextCursor: string | null;
 };
 
-/** releasing-node observed attestation tier (K4) — present on every reveal. */
+/** The releasing node's observed attestation tier; present on every reveal. */
 export type AttestationTier = {
   /** `attestation:destination:region` trust-tier URN. */
   urn: string;
@@ -126,19 +118,16 @@ export type RevealSecretResult = {
 
 /** `update()` input. */
 export type UpdateSecretInput = {
-  /** The authoritative region for this write (sent as `?region=`), REQUIRED — same live-verified gate
-   *  as `create`. */
-  region: string;
+  /** Optional. The gateway sets the residency region of the write itself and discards this; it is sent only when given. */
+  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.
+ * `update()` result: the gateway returns only `{id, name, version}`, narrower than the OpenAPI `SecretSummary`.
+ * Call `get()` afterward if the full summary is needed.
  */
 export type UpdateSecretResult = {
   id: string;
@@ -147,9 +136,8 @@ export type UpdateSecretResult = {
 };
 
 /**
- * `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.
+ * `rotate()` result: not described by the OpenAPI schema (which declares a summary or a reveal challenge for the
+ * route); typed to what the gateway returns. `ledgerSequenceNumber` is undocumented.
  */
 export type RotateSecretResult = {
   id: string;
@@ -160,9 +148,8 @@ export type RotateSecretResult = {
 };
 
 /**
- * `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).
+ * `move()` result: not the OpenAPI `SecretSummary`; it has no `version` and carries an undocumented `event`
+ * field (`"SECRET_PATH_CHANGED"` observed; typed as `string`).
  */
 export type MoveSecretResult = {
   id: string;

package/src/vault.ts

@@ -1,12 +1,10 @@
 /**
- * `client.kibo.vault.*` — the Kibo vault surface.
+ * `client.kibo.vault.*` - the Kibo vault surface.
  *
- * `vault.zkDeks.{store,fetch}` — member-plane,
- * project-scoped storage of the opaque customer-wrapped DEK envelope. Zero
- * crypto SDK-side: this is a plain authenticated REST round-trip carrying an
- * opaque blob (the wrapping happens in the ZK core, piece C). The encryption
- * surface (`kibo.encrypt`/`decrypt`) is provided by the ZK core binding when it is
- * bundled.
+ * `vault.zkDeks.{store,fetch}` store and fetch the opaque customer-wrapped DEK envelope, project-scoped. There is
+ * no cryptography in this client: it is a plain authenticated REST round-trip carrying an opaque blob (the
+ * wrapping happens in the standalone `encrypt`/`decrypt`, which never call the platform).
+ * `vault.secrets.*` is the typed secrets family.
  */
 
 import { request, type HttpClientConfig } from "@k9o/core/http";
@@ -20,9 +18,7 @@ import type {
   RotateSecretResult, MoveSecretResult,
 } from "./types.ts";
 
-/** UTF-8-safe base64 encode, usable across browser/Node/Bun (unlike `Buffer`) — the vault-secrets wire
- *  `value` field is base64 (live-verified; the OpenAPI "plaintext to seal" description does not mean
- *  raw-on-the-wire). */
+/** UTF-8-safe base64 encode, usable across browser/Node/Bun (unlike `Buffer`). The wire `value` field is base64. */
 function encodeBase64Utf8(plaintext: string): string {
   return btoa(unescape(encodeURIComponent(plaintext)));
 }
@@ -32,7 +28,7 @@ function decodeBase64Utf8(b64: string): string {
   return decodeURIComponent(escape(atob(b64)));
 }
 
-/** Both `vault.zkDeks` and `vault.secrets` require a project context (member-plane, /). */
+/** Both `vault.zkDeks` and `vault.secrets` require a project context (member-plane). */
 function requireProjectSlug(config: HttpClientConfig): string {
   if (config.projectSlug === undefined || config.projectSlug.length === 0) {
     throw new KError({
@@ -45,9 +41,20 @@ function requireProjectSlug(config: HttpClientConfig): string {
   return config.projectSlug;
 }
 
+/** Bound on the pages `secrets.get` scans for an exact name. */
+const MAX_GET_PAGES = 20;
+
+/** @internal */
 export function makeVaultNamespace(config: HttpClientConfig) {
+  const listSecrets = async (input?: ListSecretsInput): Promise<Envelope<ListSecretsResult>> =>
+    request<ListSecretsResult>(config, {
+      method: "GET",
+      path: projectPath(requireProjectSlug(config), "vault/secrets"),
+      query: { prefix: input?.prefix, cursor: input?.cursor, limit: input?.limit },
+    });
+
   return {
-    /** ZK-DEK opaque store/fetch (F.5). */
+    /** Opaque store/fetch of a customer-wrapped DEK envelope. */
     zkDeks: {
       /**
        * Store an opaque customer-wrapped DEK envelope.
@@ -76,57 +83,49 @@ export function makeVaultNamespace(config: HttpClientConfig) {
     },
 
     /**
-     * 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`).
+     * Typed secrets surface (`/@<projectSlug>/vault/secrets`): list / get / create / revealChallenge / reveal /
+     * update / rotate / move / delete.
+     *
+     * `region`: the gateway sets the residency region of every vault call itself and discards a caller-supplied
+     * `region` query parameter, so it is optional on every method. When given, it is still sent (older gateways
+     * required it).
      *
-     * 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`.
+     * Response shapes for `update`/`rotate`/`move` are typed to what the gateway returns, not the OpenAPI's
+     * `SecretSummary` (see `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?: ListSecretsInput): Promise<Envelope<ListSecretsResult>> {
-        return request<ListSecretsResult>(config, {
-          method: "GET",
-          path: projectPath(requireProjectSlug(config), "vault/secrets"),
-          query: { prefix: input?.prefix, cursor: input?.cursor, limit: input?.limit },
-        });
-      },
+      /** List secrets (metadata only, never ciphertext). `GET /@<projectSlug>/vault/secrets`. */
+      list: listSecrets,
 
       /**
-       * Read a secret's metadata (never its value — use `revealChallenge`+`reveal` for that).
-       * `GET /@<projectSlug>/vault/secrets/<name>?region=<region>`.
+       * Read one secret's metadata (never its value; use `revealChallenge` + `reveal` for that).
        *
-       * 🔴 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.
+       * Vault answers a `GET /@<projectSlug>/vault/secrets/<name>` only as a reveal: with no
+       * `X-K9O-Reveal-Challenge` header it refuses with 401 `K9O_REVEAL_CHALLENGE_REQUIRED`, whatever the caller's
+       * rights. There is no plain metadata read on that route, so `get` reads the metadata the route that exists
+       * for it returns: it lists by the exact name as prefix and picks the exact match. It throws `K9O_NOT_FOUND`
+       * (status 404) when no secret has that name.
        */
-      async get(name: string, opts: { region: string }): Promise<Envelope<SecretSummary>> {
-        return request<SecretSummary>(config, {
-          method: "GET",
-          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
-          query: { region: opts.region },
+      async get(name: string, _opts?: { region?: string }): Promise<Envelope<SecretSummary>> {
+        let cursor: string | undefined;
+        for (let page = 0; page < MAX_GET_PAGES; page++) {
+          const env = await listSecrets({ prefix: name, ...(cursor !== undefined ? { cursor } : {}), limit: 100 });
+          const hit = env.data.secrets.find((s) => s.name === name);
+          if (hit !== undefined) return { ...env, data: hit };
+          if (env.data.nextCursor === null || env.data.nextCursor === undefined) break;
+          cursor = env.data.nextCursor;
+        }
+        throw new KError({
+          code: "K9O_NOT_FOUND",
+          message: `No secret named '${name}' in this project.`,
+          context: { name },
+          status: 404,
         });
       },
 
       /**
        * 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.
+       * `POST /@<projectSlug>/vault/secrets/<name>` -> the `sec_<base62>` summary.
        */
       async create(input: CreateSecretInput): Promise<Envelope<SecretSummary>> {
         const { name, region, value, ...rest } = input;
@@ -134,29 +133,27 @@ export function makeVaultNamespace(config: HttpClientConfig) {
           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.
+          // The wire `value` is base64 (a raw string is rejected as unparseable). `input.value` stays the
+          // caller-facing plaintext; base64 is purely a wire 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: string, opts: { region: string }): Promise<Envelope<RevealChallenge>> {
+      /** Mint a single-use reveal challenge; pass it to the immediately-following `reveal()`.
+       *  `POST .../<name>?op=reveal-challenge`. The optional `reason` is accepted by the gateway and not forwarded. */
+      async revealChallenge(name: string, opts?: { region?: string; reason?: string }): Promise<Envelope<RevealChallenge>> {
         return request<RevealChallenge>(config, {
           method: "POST",
           path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
-          query: { op: "reveal-challenge", region: opts.region },
+          query: { op: "reveal-challenge", region: opts?.region },
+          ...(opts?.reason !== undefined ? { body: { reason: opts.reason } } : {}),
         });
       },
 
       /** 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: string, opts: { region: string; challenge: string }): Promise<Envelope<RevealSecretResult>> {
+       *  `GET .../<name>` with `X-K9O-Reveal-Challenge`. Decodes the wire's base64 `value` back to plaintext
+       *  (symmetric with `create`'s encode). */
+      async reveal(name: string, opts: { region?: string; challenge: string }): Promise<Envelope<RevealSecretResult>> {
         const envelope = await request<RevealSecretResult>(config, {
           method: "GET",
           path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
@@ -166,9 +163,8 @@ export function makeVaultNamespace(config: HttpClientConfig) {
         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. */
+      /** Update a secret's value (bumps version), owner-only. `PUT .../<name>`.
+       *  Returns only `{id, name, version}` (see `UpdateSecretResult`); call `get()` after for the rest. */
       async update(name: string, input: UpdateSecretInput): Promise<Envelope<UpdateSecretResult>> {
         return request<UpdateSecretResult>(config, {
           method: "PUT",
@@ -178,19 +174,18 @@ export function makeVaultNamespace(config: HttpClientConfig) {
         });
       },
 
-      /** 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: string, opts: { region: string }): Promise<Envelope<RotateSecretResult>> {
+      /** Rotate a secret's wrapping key (re-wraps under a fresh `kid`; content unchanged), owner-only.
+       *  `POST .../<name>?op=rotate`. */
+      async rotate(name: string, opts?: { region?: string }): Promise<Envelope<RotateSecretResult>> {
         return request<RotateSecretResult>(config, {
           method: "POST",
           path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
-          query: { op: "rotate", region: opts.region },
+          query: { op: "rotate", region: opts?.region },
         });
       },
 
-      /** Move (rename) a secret's hierarchical path — owner-only.
-       *  `POST .../<name>?op=move&region=<region>`. */
-      async move(name: string, opts: { region: string; newPath: string }): Promise<Envelope<MoveSecretResult>> {
+      /** Move (rename) a secret's hierarchical path, owner-only. `POST .../<name>?op=move`. */
+      async move(name: string, opts: { region?: string; newPath: string }): Promise<Envelope<MoveSecretResult>> {
         return request<MoveSecretResult>(config, {
           method: "POST",
           path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
@@ -199,12 +194,12 @@ export function makeVaultNamespace(config: HttpClientConfig) {
         });
       },
 
-      /** Retire a secret — owner-only. `DELETE .../<name>?region=<region>` → `204 No Content`. */
-      async delete(name: string, opts: { region: string }): Promise<Envelope<void>> {
+      /** Retire a secret, owner-only. `DELETE .../<name>`. */
+      async delete(name: string, opts?: { region?: string }): Promise<Envelope<void>> {
         return request<void>(config, {
           method: "DELETE",
           path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
-          query: { region: opts.region },
+          query: { region: opts?.region },
         });
       },
     },

package/src/wasm-loader.ts

@@ -0,0 +1,106 @@
+/**
+ * Loads the nodejs-target glue that wasm-bindgen emits for the bound core.
+ *
+ * That glue is CommonJS (`exports.zk_encrypt = ...`, `require("fs")`, a synchronous read of the sibling `_bg.wasm`).
+ * This package is ESM (`"type": "module"`), so Node parses any `.js` under it as ESM and the glue dies with
+ * `exports is not defined`; `import()` and `require()` of that file both hit it. The default loader therefore reads the
+ * glue source and evaluates it with a CommonJS wrapper itself, which does not depend on the file extension or on the
+ * nearest `package.json`.
+ *
+ * Failures are reported as what they are: no glue file at all, or a glue file that is there and failed (with the
+ * underlying error attached as `cause`).
+ */
+
+import { KError } from "@k9o/core/errors";
+import type { ZkWasm } from "./crypto.ts";
+
+/** What the loader needs from the host; injectable so the failure paths are testable without a wasm artefact. */
+export interface WasmLoaderDeps {
+  /** Absolute paths to try, in order. */
+  candidates: string[];
+  /** Load the glue at `path`. Must reject with an error whose `code` is `ENOENT`/`MODULE_NOT_FOUND`/`ERR_MODULE_NOT_FOUND`
+   *  and whose `path` (or message) names `path` when that file is missing. */
+  importGlue(path: string): Promise<unknown>;
+}
+
+const NOT_FOUND_CODES = new Set(["ENOENT", "MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
+
+function describe(e: unknown): string {
+  return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+
+/** True when `e` says the file `path` itself is missing (not a file the glue went on to read). */
+function isMissing(e: unknown, path: string): boolean {
+  if (typeof e !== "object" || e === null) return false;
+  const err = e as { code?: unknown; path?: unknown; message?: unknown };
+  if (typeof err.code !== "string" || !NOT_FOUND_CODES.has(err.code)) return false;
+  if (typeof err.path === "string") return err.path === path;
+  return typeof err.message === "string" && err.message.includes(path);
+}
+
+function withCause(err: KError, cause: unknown): KError {
+  (err as { cause?: unknown }).cause = cause;
+  return err;
+}
+
+export async function loadZkGlue(deps: WasmLoaderDeps): Promise<ZkWasm> {
+  for (const path of deps.candidates) {
+    let mod: unknown;
+    try {
+      mod = await deps.importGlue(path);
+    } catch (e) {
+      if (isMissing(e, path)) continue;
+      throw withCause(
+        new KError({
+          code: "KIBO_WASM_ERROR",
+          message: `the Kibo zero-knowledge core (wasm) is present at ${path} but failed to load: ${describe(e)}`,
+          context: { path, cause: describe(e) },
+          recommendation: "Reinstall @k9o/kibo; if it persists, load the core yourself and pass it to setZkWasm.",
+        }),
+        e,
+      );
+    }
+    const m = mod as Partial<ZkWasm> | null | undefined;
+    if (typeof m?.zk_encrypt !== "function" || typeof m?.zk_decrypt !== "function") {
+      throw new KError({
+        code: "KIBO_WASM_ERROR",
+        message: `the Kibo zero-knowledge core (wasm) loaded from ${path} does not export zk_encrypt and zk_decrypt`,
+        context: { path },
+        recommendation: "Reinstall @k9o/kibo; the bundled core does not match this version.",
+      });
+    }
+    return m as ZkWasm;
+  }
+  throw new KError({
+    code: "KIBO_WASM_ERROR",
+    message: `the Kibo zero-knowledge core (wasm) is not bundled in this build of @k9o/kibo: no file at ${deps.candidates.join(" or ")}; encrypt and decrypt are unavailable`,
+    context: { candidates: deps.candidates },
+    recommendation: "Install a release of @k9o/kibo that ships the core, or load it yourself and pass it to setZkWasm.",
+  });
+}
+
+/** Evaluate CommonJS source as a module living at `path`, with a `require` resolving from `path`. */
+export function evalCommonJs(source: string, path: string, req: (id: string) => unknown, dirname: string): unknown {
+  const module = { exports: {} as Record<string, unknown> };
+  // eslint-disable-next-line no-new-func
+  const wrapper = new Function("exports", "require", "module", "__filename", "__dirname", source);
+  wrapper(module.exports, req, module, path, dirname);
+  return module.exports;
+}
+
+/** Node host: glue next to this package's `wasm/` directory, evaluated as CommonJS. */
+export function nodeDeps(moduleUrl: string): WasmLoaderDeps {
+  // The node builtins are named at run time so a browser/RN bundler never tries to resolve them: this path only runs on Node.
+  const builtin = (n: string) => ["node", n].join(":");
+  const here = (rel: string) => decodeURIComponent(new URL(rel, moduleUrl).pathname.replace(/^\/([A-Za-z]:)/, "$1"));
+  return {
+    candidates: [here("../wasm/kibo_kms_rest_ffi.cjs"), here("../wasm/kibo_kms_rest_ffi.js")],
+    async importGlue(path: string) {
+      const fs = (await import(builtin("fs"))) as typeof import("node:fs");
+      const nodeModule = (await import(builtin("module"))) as typeof import("node:module");
+      const nodePath = (await import(builtin("path"))) as typeof import("node:path");
+      const source = fs.readFileSync(path, "utf8"); // throws ENOENT with err.path === path when the glue is missing
+      return evalCommonJs(source, path, nodeModule.createRequire(path), nodePath.dirname(path));
+    },
+  };
+}

package/wasm/kibo_kms_rest_ffi.js

@@ -417,7 +417,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;
                     }
@@ -575,12 +575,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) {
@@ -617,14 +617,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) {
@@ -635,8 +635,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));
 }