@k9o/kibo 0.0.0-stage → 1.0.0

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 (ch08 §11.3.3.4). 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 (ch08 §11.3.2) — `vault.zkDeks.{store,fetch}`;
+ *     decoupled, gateway-only opaque-blob persistence.
+ *   - ZK `encrypt`/`decrypt` (§11.3.1/§11.3.3.6) — 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";

package/src/types.ts

@@ -0,0 +1,171 @@
+/**
+ * `@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). */
+export 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).
+ */
+export 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. */
+export type ZkDekHandle = {
+  /** `zkdek_<base62>` handle. */
+  id: string;
+  createdAt: string;
+};
+
+/** Fetch response — the stored record: opaque envelope + non-secret metadata. */
+export 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. */
+export 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>`. */
+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). */
+  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. */
+export 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). */
+export type ListSecretsInput = {
+  /** Filter to a path prefix. */
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+};
+
+export type ListSecretsResult = {
+  secrets: readonly SecretSummary[];
+  nextCursor: string | null;
+};
+
+/** §14.10 releasing-node observed attestation tier (K4) — present on every reveal. */
+export 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()`. */
+export 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. */
+export type RevealSecretResult = {
+  id: string;
+  name: string;
+  version: number;
+  value: string;
+  revealedAt: string;
+  attestationTier: AttestationTier;
+};
+
+/** `update()` input. */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export type MoveSecretResult = {
+  id: string;
+  name: string;
+  event: string;
+};

package/src/vault.ts

@@ -0,0 +1,212 @@
+/**
+ * `client.kibo.vault.*` — the Kibo vault surface.
+ *
+ * v0.1.0: `vault.zkDeks.{store,fetch}` (ch08 §11.3.2 F.5) — 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`) lands in a later version once the C
+ * binding is consumable.
+ */
+
+import { request, type HttpClientConfig } from "@k9o/core/http";
+import { projectPath } from "@k9o/core/url-grammar";
+import { KError } from "@k9o/core/errors";
+import type { Envelope } from "@k9o/core/envelope";
+import type {
+  StoreZkDekInput, ZkDekHandle, ZkDekRecord,
+  CreateSecretInput, SecretSummary, ListSecretsInput, ListSecretsResult,
+  RevealChallenge, RevealSecretResult, UpdateSecretInput, UpdateSecretResult,
+  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). */
+function encodeBase64Utf8(plaintext: string): string {
+  return btoa(unescape(encodeURIComponent(plaintext)));
+}
+
+/** Inverse of {@link encodeBase64Utf8} — decodes a revealed wire `value` back to plaintext. */
+function decodeBase64Utf8(b64: string): string {
+  return decodeURIComponent(escape(atob(b64)));
+}
+
+/** Both `vault.zkDeks` and `vault.secrets` require a project context (member-plane, ch08 §11.3/§14). */
+function requireProjectSlug(config: HttpClientConfig): string {
+  if (config.projectSlug === undefined || 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;
+}
+
+export function makeVaultNamespace(config: HttpClientConfig) {
+  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: StoreZkDekInput): Promise<Envelope<ZkDekHandle>> {
+        return request<ZkDekHandle>(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: string): Promise<Envelope<ZkDekRecord>> {
+        return request<ZkDekRecord>(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?: 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 },
+        });
+      },
+
+      /**
+       * 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: 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 },
+        });
+      },
+
+      /**
+       * 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: CreateSecretInput): Promise<Envelope<SecretSummary>> {
+        const { name, region, value, ...rest } = input;
+        return request<SecretSummary>(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: string, opts: { region: 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 },
+        });
+      },
+
+      /** 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>> {
+        const envelope = await request<RevealSecretResult>(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: string, input: UpdateSecretInput): Promise<Envelope<UpdateSecretResult>> {
+        return request<UpdateSecretResult>(config, {
+          method: "PUT",
+          path: projectPath(requireProjectSlug(config), `vault/secrets/${encodeURIComponent(name)}`),
+          query: { region: input.region },
+          body: { value: encodeBase64Utf8(input.value), ...(input.metadata !== undefined ? { 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: 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 },
+        });
+      },
+
+      /** 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>> {
+        return request<MoveSecretResult>(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: 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 },
+        });
+      },
+    },
+  };
+}