okengine 0.11.2 → 0.13.0

package/src/console/ui-next/src/features/vault/lib/backend.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Vault backend status card — badges, facts, operator hint.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  formatVaultBackend,
+  vaultDriverHint,
+  vaultDriverKind,
+  vaultDriverShortLabel,
+  vaultDriverTitle,
+} from "./backend.ts";
+import { VAULT_BACKEND_FIXTURE } from "./fixture.ts";
+import type { VaultBackend } from "./types.ts";
+
+describe("formatVaultBackend", () => {
+  test("lock-path says driver; title names built-in vs managed provider", () => {
+    expect(vaultDriverShortLabel(VAULT_BACKEND_FIXTURE)).toBe("driver");
+    expect(vaultDriverKind(VAULT_BACKEND_FIXTURE)).toBe("built-in");
+    expect(vaultDriverTitle(VAULT_BACKEND_FIXTURE)).toBe("Built-in vault");
+    expect(
+      vaultDriverTitle({
+        driverId: "managed",
+        builtin: false,
+        status: null,
+        unavailable: null,
+        provider: "aws-secrets-manager",
+      }),
+    ).toBe("AWS Secrets Manager");
+    expect(
+      vaultDriverKind({
+        driverId: "managed",
+        builtin: false,
+        status: null,
+        unavailable: null,
+        provider: "aws-secrets-manager",
+      }),
+    ).toBe("managed · aws");
+    expect(
+      vaultDriverKind({
+        driverId: "env",
+        builtin: false,
+        status: null,
+        unavailable: null,
+      }),
+    ).toBe("simulate");
+    expect(
+      vaultDriverTitle({
+        driverId: "env",
+        builtin: false,
+        status: null,
+        unavailable: null,
+      }),
+    ).toBe("Simulated env");
+    expect(
+      vaultDriverShortLabel({
+        driverId: "env",
+        builtin: false,
+        status: null,
+        unavailable: null,
+      }),
+    ).toBe("driver");
+    expect(vaultDriverHint(VAULT_BACKEND_FIXTURE)).toContain("Built-in vault");
+    expect(
+      vaultDriverHint({
+        driverId: "managed",
+        builtin: false,
+        status: null,
+        unavailable: null,
+        provider: "aws-secrets-manager",
+      }),
+    ).toBe("Managed provider — AWS Secrets Manager");
+    expect(
+      vaultDriverHint({
+        driverId: "env",
+        builtin: false,
+        status: null,
+        unavailable: null,
+      }),
+    ).toContain("No built-in vault or managed provider");
+  });
+
+  test("null backend renders no card", () => {
+    expect(formatVaultBackend(null)).toBeNull();
+  });
+
+  test("non-builtin driver shows the id with no seal badges", () => {
+    const card = formatVaultBackend({
+      driverId: "managed",
+      builtin: false,
+      status: null,
+      unavailable: null,
+    });
+    expect(card?.title).toBe("Managed vault");
+    expect(card?.badges).toEqual([]);
+    expect(card?.facts).toEqual([]);
+    expect(card?.hint).toBeNull();
+  });
+
+  test("sealed builtin backend warns and points at the master key", () => {
+    const card = formatVaultBackend(VAULT_BACKEND_FIXTURE);
+    expect(card?.badges.map((b) => b.id)).toEqual(["initialized", "sealed"]);
+    expect(card?.badges.find((b) => b.id === "sealed")?.tone).toBe("warn");
+    expect(card?.facts).toContainEqual({ label: "KEK generation", value: "v2" });
+    expect(card?.facts).toContainEqual({ label: "Secrets stored", value: "7" });
+    expect(card?.hint).toContain("OKE_VAULT_MASTER_KEY");
+  });
+
+  test("unsealed builtin backend has no hint", () => {
+    const backend: VaultBackend = {
+      ...VAULT_BACKEND_FIXTURE,
+      status: { ...VAULT_BACKEND_FIXTURE.status!, sealed: false },
+    };
+    const card = formatVaultBackend(backend);
+    expect(card?.badges.map((b) => b.id)).toEqual(["initialized", "unsealed"]);
+    expect(card?.hint).toBeNull();
+  });
+
+  test("uninitialized backend points at `oke vault init`", () => {
+    const backend: VaultBackend = {
+      ...VAULT_BACKEND_FIXTURE,
+      status: { ...VAULT_BACKEND_FIXTURE.status!, initialized: false },
+    };
+    const card = formatVaultBackend(backend);
+    expect(card?.badges.map((b) => b.id)).toEqual(["uninitialized"]);
+    expect(card?.hint).toContain("oke vault init");
+  });
+
+  test("an in-flight master rotation surfaces the rewrap target", () => {
+    const backend: VaultBackend = {
+      ...VAULT_BACKEND_FIXTURE,
+      status: { ...VAULT_BACKEND_FIXTURE.status!, rewrapTargetKekVersion: 3 },
+    };
+    expect(formatVaultBackend(backend)?.badges.map((b) => b.label)).toContain("rewrap → kek v3");
+  });
+
+  test("unreachable builtin backend surfaces the reason", () => {
+    const card = formatVaultBackend({
+      driverId: "vault",
+      builtin: true,
+      status: null,
+      unavailable: "connection refused",
+    });
+    expect(card?.badges.map((b) => b.id)).toEqual(["unreachable"]);
+    expect(card?.hint).toBe("connection refused");
+  });
+});

package/src/console/ui-next/src/features/vault/lib/backend.ts

@@ -0,0 +1,216 @@
+/**
+ * Format the Vault backend status card (console §9.8).
+ *
+ * Only the built-in `vault` driver has a seal lifecycle; every other driver
+ * shows its id alone so the operator still knows which layer starts the
+ * resolution chain.
+ */
+
+import type { VaultBackend } from "./types.ts";
+
+/** One badge in the status card. */
+export interface VaultBackendBadge {
+  /** Stable id for keys and tests. */
+  readonly id: string;
+  /** Short badge text. */
+  readonly label: string;
+  /** `warn` renders as an alert; `ok` and `neutral` are status text. */
+  readonly tone: "ok" | "warn" | "neutral";
+}
+
+/** Rendered status card. */
+export interface VaultBackendCard {
+  /** Driver id headline (`Backend vault`). */
+  readonly title: string;
+  /** One-line explanation of what that backend is. */
+  readonly description: string;
+  /** Seal / initialization badges — empty for non-builtin drivers. */
+  readonly badges: readonly VaultBackendBadge[];
+  /** `label: value` facts (KEK generation, secret count, …). */
+  readonly facts: readonly { readonly label: string; readonly value: string }[];
+  /** Operator next step, when one applies. */
+  readonly hint: string | null;
+}
+
+/** What each driver id means, in one line. */
+const DRIVER_DESCRIPTION: Readonly<Record<string, string>> = {
+  vault: "okengine's own store — encrypted at rest, sealed until unsealed with the master key",
+  env: "No remote store — values come from process.env and .env.local",
+  managed: "Managed KMS / provider secret store",
+  memory: "In-memory bag — test only, nothing survives restart",
+};
+
+const PROVIDER_TITLE: Readonly<Record<string, string>> = {
+  "aws-secrets-manager": "AWS Secrets Manager",
+  "azure-key-vault": "Azure Key Vault",
+  "gcp-secret-manager": "GCP Secret Manager",
+  doppler: "Doppler",
+  "1password": "1Password",
+};
+
+const PROVIDER_KIND: Readonly<Record<string, string>> = {
+  "aws-secrets-manager": "aws",
+  "azure-key-vault": "azure",
+  "gcp-secret-manager": "gcp",
+  doppler: "doppler",
+  "1password": "1password",
+};
+
+/**
+ * Lock-path label — always `driver`. Kind (built-in vs managed) lives in
+ * {@link vaultDriverTitle} / {@link vaultDriverHint}.
+ *
+ * @param _backend - Unused; kept so call sites stay typed
+ */
+export function vaultDriverShortLabel(_backend?: VaultBackend | null): string {
+  return "driver";
+}
+
+/**
+ * Headline for the backend card and the selected lock-path layer.
+ *
+ * @param backend - Server-reported backend
+ */
+export function vaultDriverTitle(backend: VaultBackend | null | undefined): string {
+  if (!backend) return "Vault backend";
+  switch (backend.driverId) {
+    case "vault":
+      return "Built-in vault";
+    case "managed": {
+      const id = backend.provider?.trim() ?? "";
+      if (id.length === 0) return "Managed vault";
+      return PROVIDER_TITLE[id] ?? `Managed · ${id}`;
+    }
+    case "memory":
+      return "Memory bag";
+    case "env":
+      return "Simulated env";
+  }
+}
+
+/**
+ * Kind on the lock-path driver step — built-in, managed, or neither.
+ *
+ * @param backend - Server-reported backend
+ */
+export function vaultDriverKind(backend: VaultBackend | null | undefined): string {
+  if (!backend) return "unknown";
+  switch (backend.driverId) {
+    case "vault":
+      return "built-in";
+    case "managed": {
+      const id = backend.provider?.trim() ?? "";
+      const kind = PROVIDER_KIND[id];
+      if (kind !== undefined) return `managed · ${kind}`;
+      if (id.length > 0) return `managed · ${id.length > 8 ? id.slice(0, 8) : id}`;
+      return "managed";
+    }
+    case "memory":
+      return "memory";
+    case "env":
+      // Not "env" — that word is the process.env lock-path layer.
+      return "simulate";
+  }
+}
+
+/**
+ * One-line explanation of the driver layer.
+ *
+ * @param backend - Server-reported backend
+ */
+export function vaultDriverHint(backend: VaultBackend | null | undefined): string {
+  if (!backend) return "Set drivers.vault to built-in vault or a managed provider";
+  switch (backend.driverId) {
+    case "vault":
+      return "Built-in vault — encrypted at rest, sealed until unsealed with the master key";
+    case "managed": {
+      const id = backend.provider?.trim() ?? "";
+      const title = PROVIDER_TITLE[id];
+      if (title !== undefined) return `Managed provider — ${title}`;
+      if (id.length > 0) return `Managed provider — ${id}`;
+      return "Managed provider — platform-injected secrets (no remote provider id)";
+    }
+    case "memory":
+      return "In-memory driver — test only, nothing survives restart";
+    case "env":
+      return "No built-in vault or managed provider — values come from process.env and .env.local";
+    default:
+      return DRIVER_DESCRIPTION[backend.driverId] ?? "Custom vault backend";
+  }
+}
+
+/**
+ * Build the status card for a backend.
+ *
+ * @param backend - Server-reported backend, or `null` when unresolved
+ */
+export function formatVaultBackend(backend: VaultBackend | null): VaultBackendCard | null {
+  if (!backend) return null;
+
+  const title = vaultDriverTitle(backend);
+  const description = vaultDriverHint(backend);
+
+  if (!backend.builtin) {
+    return { title, description, badges: [], facts: [], hint: null };
+  }
+
+  const status = backend.status;
+  if (!status) {
+    return {
+      title,
+      description,
+      badges: [{ id: "unreachable", label: "status unavailable", tone: "warn" }],
+      facts: [],
+      hint: backend.unavailable ?? "Run `oke vault status` to inspect the backend directly",
+    };
+  }
+
+  if (!status.initialized) {
+    return {
+      title,
+      description,
+      badges: [{ id: "uninitialized", label: "not initialized", tone: "warn" }],
+      facts: [],
+      hint: "Run `oke vault init` to create the vault and print its master key once",
+    };
+  }
+
+  const badges: VaultBackendBadge[] = [
+    { id: "initialized", label: "initialized", tone: "ok" },
+    status.sealed
+      ? { id: "sealed", label: "sealed", tone: "warn" }
+      : { id: "unsealed", label: "unsealed", tone: "ok" },
+  ];
+  if (status.rewrapTargetKekVersion !== null) {
+    badges.push({
+      id: "rewrap",
+      label: `rewrap → kek v${status.rewrapTargetKekVersion}`,
+      tone: "warn",
+    });
+  }
+
+  const facts: { label: string; value: string }[] = [
+    { label: "KEK generation", value: `v${status.kekVersion}` },
+    { label: "Secrets stored", value: String(status.secretCount) },
+    { label: "Seal count", value: String(status.sealCount) },
+  ];
+  if (status.lastUnsealedAt !== null) {
+    facts.push({
+      label: "Last unsealed",
+      value: new Date(status.lastUnsealedAt).toISOString(),
+    });
+  }
+  if (status.lastSealedAt !== null) {
+    facts.push({ label: "Last sealed", value: new Date(status.lastSealedAt).toISOString() });
+  }
+
+  return {
+    title,
+    description,
+    badges,
+    facts,
+    hint: status.sealed
+      ? "This process holds no master key — export OKE_VAULT_MASTER_KEY or run `oke vault unseal`"
+      : null,
+  };
+}

package/src/console/ui-next/src/features/vault/lib/blast-radius.ts

@@ -0,0 +1,53 @@
+/**
+ * Format journal-queried rotation blast radius for the Vault page.
+ */
+
+import type { VaultBlastRadius } from "./types.ts";
+
+/** Human-readable blast-radius line. */
+export interface BlastRadiusLine {
+  readonly summary: string;
+  readonly detail: string | null;
+  readonly warn: boolean;
+}
+
+/**
+ * Format blast radius for display.
+ *
+ * @param blast - Queried radius
+ */
+export function formatBlastRadius(blast: VaultBlastRadius): BlastRadiusLine {
+  if (blast.count === 0) {
+    return {
+      summary: "No in-flight durable runs hold this secret",
+      detail: null,
+      warn: false,
+    };
+  }
+  const remaining =
+    blast.longestOutstandingMs != null ? formatDuration(blast.longestOutstandingMs) : null;
+  return {
+    summary: `${blast.count} in-flight durable run(s) will wake holding a new key`,
+    detail: remaining
+      ? `Longest outstanding wake in ${remaining}`
+      : blast.longestWakeAt != null
+        ? `Longest wake at ${new Date(blast.longestWakeAt).toISOString()}`
+        : null,
+    warn: true,
+  };
+}
+
+/**
+ * @param ms - Duration
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1_000) return `${ms}ms`;
+  const sec = Math.floor(ms / 1_000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  if (hr < 48) return `${hr}h`;
+  const days = Math.floor(hr / 24);
+  return `${days}d`;
+}

package/src/console/ui-next/src/features/vault/lib/confirmation.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createConfirmation,
+  rotateConfirmation,
+  rotateMasterConfirmation,
+  setConfirmation,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+
+describe("vault confirmation", () => {
+  test("create / set / rotate use a review dialog, not a typed phrase", () => {
+    expect(createConfirmation()).toEqual({ kind: "review" });
+    expect(setConfirmation({ production: true })).toEqual({ kind: "review" });
+    expect(rotateConfirmation({ production: false })).toEqual({ kind: "review" });
+  });
+
+  test("rotate-master always requires typed confirm", () => {
+    expect(rotateMasterConfirmation()).toEqual({
+      kind: "typed",
+      phrase: "ROTATE_MASTER",
+      requireReason: true,
+    });
+  });
+
+  test("validateTypedConfirm", () => {
+    expect(
+      validateTypedConfirm({
+        typed: "ROTATE",
+        reason: "key compromise",
+        phrase: "ROTATE",
+      }),
+    ).toBeNull();
+    expect(
+      validateTypedConfirm({
+        typed: "nope",
+        reason: "x",
+        phrase: "ROTATE",
+      }),
+    ).not.toBeNull();
+  });
+});

package/src/console/ui-next/src/features/vault/lib/confirmation.ts

@@ -0,0 +1,50 @@
+/**
+ * Confirmation for vault writes. Set / rotate record a reason.
+ * Rotate-master stays a typed phrase (dual-KEK window).
+ */
+
+import {
+  validateTypedConfirm,
+  type StoreConfirmationPattern,
+} from "../../store/lib/confirmation.ts";
+
+export { validateTypedConfirm };
+
+/** Confirmation strategy for a vault write. */
+export type VaultConfirmationPattern = StoreConfirmationPattern | { readonly kind: "review" };
+
+/**
+ * Confirmation for adding a contract from Console — review dialog.
+ */
+export function createConfirmation(): VaultConfirmationPattern {
+  return { kind: "review" };
+}
+
+/**
+ * Confirmation for setting a vault value — reason + review dialog.
+ *
+ * @param _options - Reserved for environment flags
+ */
+export function setConfirmation(
+  _options: { readonly production: boolean } = { production: true },
+): VaultConfirmationPattern {
+  return { kind: "review" };
+}
+
+/**
+ * Confirmation for rotating a vault value — reason + review dialog.
+ *
+ * @param _options - Reserved for environment flags
+ */
+export function rotateConfirmation(
+  _options: { readonly production: boolean } = { production: true },
+): VaultConfirmationPattern {
+  return { kind: "review" };
+}
+
+/**
+ * Confirmation for master-key rotation — always typed (dual-KEK window).
+ */
+export function rotateMasterConfirmation(): VaultConfirmationPattern {
+  return { kind: "typed", phrase: "ROTATE_MASTER", requireReason: true };
+}

package/src/console/ui-next/src/features/vault/lib/contract-ops.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { FIXTURE_SECRET_VALUE, VAULT_FIXTURE } from "./fixture.ts";
+import {
+  vaultDotenvLine,
+  vaultFxSnippet,
+  vaultLayerFill,
+  vaultRotateCli,
+  vaultSetCli,
+} from "./contract-ops.ts";
+
+describe("vault contract ops", () => {
+  test("snippets never include a secret value", () => {
+    const name = VAULT_FIXTURE[0]!.name;
+    const blobs = [
+      vaultFxSnippet(name),
+      vaultSetCli(name),
+      vaultRotateCli(name),
+      vaultDotenvLine(name),
+      vaultLayerFill("process.env", name).command,
+      vaultLayerFill("driver", name).command,
+    ];
+    for (const blob of blobs) {
+      expect(blob).not.toContain(FIXTURE_SECRET_VALUE);
+      expect(blob).toContain(name);
+    }
+  });
+
+  test("dotenv line is an empty assignment", () => {
+    expect(vaultDotenvLine("SLACK_WEBHOOK")).toBe("SLACK_WEBHOOK=");
+  });
+
+  test("driver fill is the set CLI", () => {
+    expect(vaultLayerFill("driver", "SLACK_WEBHOOK").command).toBe("oke vault set SLACK_WEBHOOK");
+  });
+});

package/src/console/ui-next/src/features/vault/lib/contract-ops.ts

@@ -0,0 +1,94 @@
+/**
+ * Operator snippets for one vault contract — never include secret values.
+ */
+
+import { vaultDriverHint, vaultDriverShortLabel } from "./backend.ts";
+import type { VaultBackend, VaultResolutionSource } from "./types.ts";
+
+/** One copyable fill recipe for a resolution layer. */
+export interface VaultLayerFill {
+  readonly source: VaultResolutionSource;
+  readonly label: string;
+  readonly command: string;
+  readonly hint: string;
+}
+
+/**
+ * Flow read snippet for a contract name.
+ *
+ * @param name - Contract name
+ */
+export function vaultFxSnippet(name: string): string {
+  return `await fx.vault.get(${name})`;
+}
+
+/**
+ * CLI set — value is typed at the prompt, never in this string.
+ *
+ * @param name - Contract name
+ */
+export function vaultSetCli(name: string): string {
+  return `oke vault set ${name}`;
+}
+
+/**
+ * CLI rotate — value is typed at the prompt.
+ *
+ * @param name - Contract name
+ */
+export function vaultRotateCli(name: string): string {
+  return `oke vault rotate ${name}`;
+}
+
+/**
+ * Dotenv assignment with an empty value (operator fills it).
+ *
+ * @param name - Contract name
+ */
+export function vaultDotenvLine(name: string): string {
+  return `${name}=`;
+}
+
+/**
+ * How to populate one resolution layer — commands only, no values.
+ *
+ * @param source - Layer
+ * @param name - Contract name
+ * @param backend - Active vault backend (names the driver layer)
+ */
+export function vaultLayerFill(
+  source: VaultResolutionSource,
+  name: string,
+  backend?: VaultBackend | null,
+): VaultLayerFill {
+  switch (source) {
+    case "process.env":
+      return {
+        source,
+        label: "env",
+        command: `export ${name}=`,
+        hint: "Process environment for this Console process",
+      };
+    case ".env.local":
+      return {
+        source,
+        label: "local",
+        command: vaultDotenvLine(name),
+        hint: "Write to .env.local (gitignored)",
+      };
+    case "driver":
+      return {
+        source,
+        label: vaultDriverShortLabel(backend),
+        command: vaultSetCli(name),
+        hint: vaultDriverHint(backend),
+      };
+    case "dev-fallback":
+      return {
+        source,
+        label: "fallback",
+        command: `dev: "…"`,
+        hint: "Local-only option on the contract — never used in prod",
+      };
+  }
+}

package/src/console/ui-next/src/features/vault/lib/dormant.ts

@@ -0,0 +1,28 @@
+/**
+ * Dormant (dead) secrets — last-read timestamps expose attack surface
+ * that grows by forgetting (console §9.8 · §9.16).
+ */
+
+import type { VaultRecord } from "./types.ts";
+
+/** Secrets unread for this long (or never) are dormant. */
+export const DORMANT_MS = 90 * 86_400_000;
+
+/**
+ * Secrets with no recent read — never read, or idle ≥ 90 days.
+ *
+ * Config values are excluded; only secrets grow attack surface by neglect.
+ *
+ * @param secrets - Vault page rows
+ * @param now - Clock (epoch ms)
+ */
+export function dormantSecrets(
+  secrets: readonly VaultRecord[],
+  now: number,
+): readonly VaultRecord[] {
+  return secrets.filter((s) => {
+    if (s.kind !== "secret") return false;
+    if (s.lastReadAt == null) return true;
+    return now - s.lastReadAt >= DORMANT_MS;
+  });
+}

package/src/console/ui-next/src/features/vault/lib/export-safe.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { assertExportHasNoSecrets, exportSafeList, exportSafeRow } from "./export-safe.ts";
+import { FIXTURE_SECRET_VALUE, VAULT_FIXTURE } from "./fixture.ts";
+
+describe("exportSafe", () => {
+  test("never includes secret cleartext; config cleartext is allowed", () => {
+    const secret = VAULT_FIXTURE[0]!;
+    const config = VAULT_FIXTURE[1]!;
+    const leaked = {
+      ...secret,
+      cleartext: FIXTURE_SECRET_VALUE,
+    };
+    const safe = exportSafeRow(leaked);
+    expect(safe.cleartext).toBeNull();
+    expect(JSON.stringify(safe)).not.toContain(FIXTURE_SECRET_VALUE);
+
+    const configSafe = exportSafeRow(config);
+    expect(configSafe.cleartext).toBe("https://app.example.com");
+
+    const list = exportSafeList(VAULT_FIXTURE);
+    assertExportHasNoSecrets(list, [FIXTURE_SECRET_VALUE]);
+    expect(list).toContain("sha256:aaaaaaaaaaaaaaaa");
+    expect(list).toContain("https://app.example.com");
+  });
+});