@k9o/kibo 0.0.0-stage → 1.1.0

package/src/types.ts

@@ -0,0 +1,171 @@
+/**
+ * `@k9o/kibo` — Zero-Knowledge BYOK/HYOK vault SDK types.
+ *
+ * Surface: the ZK-DEK store/fetch. The wrapped
+ * envelope is produced client-side by the audited ZK core (the
+ * `kibo-kms-rest` binding); this SDK ships it **verbatim and opaque** and never
+ * reads its interior — the strict-ZK invariant + envelope framing live in the
+ * core, never here.
+ */
+
+/** Customer KMS/HSM provider — non-secret routing metadata (mirrors the ZK FFI provider selector). */
+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;
+};
+
+/** 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 — `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;
+};
+
+/** 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.
+ *
+ * `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.
+ */
+
+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, /). */
+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 (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)}`),
+        });
+      },
+    },
+
+    /**
+     * 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 },
+        });
+      },
+    },
+  };
+}

package/wasm/kibo_kms_rest_ffi.d.ts

@@ -0,0 +1,54 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+
+type ReadableStreamType = "bytes";
+
+export class IntoUnderlyingByteSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+
+export class IntoUnderlyingSink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+
+export class IntoUnderlyingSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+
+/**
+ * Decrypt a ZKFE envelope (browser / React Native).
+ *
+ * `input_json` — JSON-serialized `DecryptInput`.
+ * Returns a `Promise<string>` resolving to JSON-serialized `DecryptOutput`.
+ */
+export function zk_decrypt(input_json: any): Promise<any>;
+
+/**
+ * Encrypt via the customer KMS (browser / React Native).
+ *
+ * `input_json` — JSON-serialized `EncryptInput`.
+ * Returns a `Promise<string>` resolving to JSON-serialized `EncryptOutput`,
+ * or rejecting with a `JsValue` error string.
+ */
+export function zk_encrypt(input_json: any): Promise<any>;