okengine 0.10.2 → 0.11.0

package/src/elements/vault/audit.ts

@@ -0,0 +1,233 @@
+/**
+ * Vault audit trail — a tamper-evident hash chain of *operations*.
+ *
+ * An audit row records that something happened to a path, never what the
+ * value was. Each row hashes its own payload together with the previous
+ * row's hash, so removing or editing a row breaks every hash after it
+ * (`verifyAuditChain` in `storage.ts` walks the chain).
+ */
+
+import { VaultError } from "./errors.ts";
+import type { VaultErrorCode } from "./errors.ts";
+import type { VaultActorType } from "./types.ts";
+import type { VaultAuditSinkKind } from "./types.ts";
+
+/** Operations recorded in the audit chain. */
+export type AuditAction =
+  | "get"
+  | "set"
+  | "delete"
+  | "rotate"
+  | "list"
+  | "seal"
+  | "unseal"
+  | "initialize"
+  | "rewrap"
+  | "purge";
+
+/** Hash-chain genesis marker used for the first row. */
+export const AUDIT_GENESIS_HASH = "genesis";
+
+/** One operation to append to the chain. */
+export interface AuditEntry {
+  /** What happened. */
+  readonly action: AuditAction;
+  /** Canonical path, when the operation targets one. */
+  readonly path?: string;
+  /** Actor class. */
+  readonly actorType: VaultActorType;
+  /** Actor id within its class. */
+  readonly actorId?: string;
+  /** Whether the operation succeeded. */
+  readonly success: boolean;
+  /** Failure reason when `success` is `false`. */
+  readonly errorCode?: VaultErrorCode;
+  /** Safe, secret-free failure description. */
+  readonly errorMessage?: string;
+  /** Correlation id for the enclosing request/run. */
+  readonly requestId?: string;
+  /** Event time. Defaults to now at append time. */
+  readonly at?: Date;
+}
+
+/**
+ * Exact field set covered by a row hash.
+ *
+ * Normalized (`null` rather than `undefined`, ISO-8601 timestamps) so a row
+ * read back from SQL hashes identically to the row that was written.
+ */
+export interface AuditHashPayload {
+  /** What happened. */
+  readonly action: AuditAction;
+  /** Canonical path or `null`. */
+  readonly path: string | null;
+  /** Actor class. */
+  readonly actorType: VaultActorType;
+  /** Actor id or `null`. */
+  readonly actorId: string | null;
+  /** Whether the operation succeeded. */
+  readonly success: boolean;
+  /** Failure reason or `null`. */
+  readonly errorCode: VaultErrorCode | null;
+  /** Failure description or `null`. */
+  readonly errorMessage: string | null;
+  /** Correlation id or `null`. */
+  readonly requestId: string | null;
+  /** ISO-8601 event time. */
+  readonly createdAt: string;
+}
+
+/** Destination for audit rows. */
+export interface AuditSink {
+  /** Sink kind, mirroring the configured `audit.sink`. */
+  readonly kind: VaultAuditSinkKind;
+  /**
+   * Append one operation.
+   *
+   * @param entry - Operation to record
+   */
+  append(entry: AuditEntry): Promise<void>;
+  /** Release sink resources, if any. */
+  close?(): Promise<void>;
+}
+
+/**
+ * Backend-side audit writer.
+ *
+ * `storage.ts` implements this over `oke_vault_audit`; the `db` sink is a
+ * thin adapter so the audit module never imports SQL.
+ */
+export interface AuditWriter {
+  /**
+   * Persist one operation, computing and linking its row hash.
+   *
+   * @param entry - Operation to record
+   */
+  appendAuditEntry(entry: AuditEntry): Promise<void>;
+}
+
+/** Options accepted by {@link createAuditSink}. */
+export interface CreateAuditSinkOptions {
+  /** Required for the `db` sink. */
+  readonly writer?: AuditWriter;
+  /** Required for the `webhook` sink (not yet implemented). */
+  readonly webhookUrl?: string;
+  /** Line writer for the `stdout` sink (tests). */
+  readonly write?: (line: string) => void;
+  /** Clock for `stdout` timestamps (tests). */
+  readonly now?: () => Date;
+}
+
+/**
+ * Normalize an entry into the exact fields a row hash covers.
+ *
+ * @param entry - Operation to record
+ * @param createdAt - Event time
+ */
+export function toAuditHashPayload(entry: AuditEntry, createdAt: Date): AuditHashPayload {
+  return {
+    action: entry.action,
+    path: entry.path ?? null,
+    actorType: entry.actorType,
+    actorId: entry.actorId ?? null,
+    success: entry.success,
+    errorCode: entry.errorCode ?? null,
+    errorMessage: entry.errorMessage ?? null,
+    requestId: entry.requestId ?? null,
+    createdAt: createdAt.toISOString(),
+  };
+}
+
+/**
+ * Hash one audit row into the chain.
+ *
+ * Fields are joined with NUL in a fixed order — no JSON key-order or
+ * whitespace ambiguity — and prefixed with the previous row's hash.
+ *
+ * @param prevHash - Previous row hash, or `null` / {@link AUDIT_GENESIS_HASH} for the first row
+ * @param payload - Normalized row fields
+ * @returns Lowercase hex SHA-256 digest
+ */
+export async function computeAuditRowHash(
+  prevHash: string | null,
+  payload: AuditHashPayload,
+): Promise<string> {
+  const parts = [
+    "oke-vault-audit-v1",
+    prevHash ?? AUDIT_GENESIS_HASH,
+    payload.action,
+    payload.path ?? "",
+    payload.actorType,
+    payload.actorId ?? "",
+    payload.success ? "1" : "0",
+    payload.errorCode ?? "",
+    payload.errorMessage ?? "",
+    payload.requestId ?? "",
+    payload.createdAt,
+  ];
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(parts.join("\0")));
+  return Buffer.from(new Uint8Array(digest)).toString("hex");
+}
+
+/**
+ * Build an audit sink.
+ *
+ * - `db` delegates to an {@link AuditWriter} supplied by storage.
+ * - `stdout` writes one secret-free JSON line per operation.
+ * - `webhook` is not implemented yet and throws `UNSUPPORTED`.
+ *
+ * @param kind - Sink kind from `audit.sink`
+ * @param opts - Writer / webhook URL / test seams
+ * @throws VaultError `UNSUPPORTED` for `webhook`, or `MISSING_PEER` when `db` has no writer
+ */
+export function createAuditSink(
+  kind: VaultAuditSinkKind,
+  opts: CreateAuditSinkOptions = {},
+): AuditSink {
+  if (kind === "webhook") {
+    throw new VaultError("UNSUPPORTED", "vault: webhook audit sink is not implemented");
+  }
+
+  if (kind === "db") {
+    const writer = opts.writer;
+    if (!writer) {
+      throw new VaultError("MISSING_PEER", "vault: db audit sink requires a storage writer");
+    }
+    return {
+      kind: "db",
+      append(entry) {
+        return writer.appendAuditEntry(entry);
+      },
+    };
+  }
+
+  const write = opts.write ?? ((line: string) => void process.stdout.write(`${line}\n`));
+  const now = opts.now ?? (() => new Date());
+  return {
+    kind: "stdout",
+    async append(entry) {
+      // Only normalized metadata is serialized — an entry never holds a value.
+      write(
+        JSON.stringify({
+          sink: "oke.vault.audit",
+          ...toAuditHashPayload(entry, entry.at ?? now()),
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Sink that drops every entry (`audit.enabled: false`).
+ *
+ * Reports `kind: "stdout"` because {@link VaultAuditSinkKind} has no
+ * "off" member — callers gate on config, not on this field.
+ */
+export function createNullAuditSink(): AuditSink {
+  return {
+    kind: "stdout",
+    async append() {
+      // Intentionally empty — auditing is disabled.
+    },
+  };
+}

package/src/elements/vault/boot-chain.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Vault boot chain — managed provider wiring and driver-id normalization.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import type { VaultOpenOptions } from "../../drivers/vault-types.ts";
+import { buildVaultBootChain, normalizeVaultDriverId } from "./boot-chain.ts";
+
+/** Env keys these tests own. */
+const OWNED = [
+  "OKE_VAULT_PROVIDER",
+  "OKE_VAULT_URL",
+  "OKE_VAULT_TOKEN",
+  "OKE_VAULT_MOUNT",
+  "OKE_VAULT_REGION",
+] as const;
+
+afterEach(() => {
+  for (const key of OWNED) delete process.env[key];
+});
+
+describe("managed vault boot chain", () => {
+  test("no provider stays a single platform-injected layer", () => {
+    const chain = buildVaultBootChain({ driverId: "managed", env: "test", seed: { A: "1" } });
+    expect(chain).toHaveLength(1);
+    expect(chain[0]?.driver.id).toBe("managed");
+  });
+
+  test("a provider puts the env layers in front of the managed layer", () => {
+    process.env.OKE_VAULT_PROVIDER = "aws-secrets-manager";
+    process.env.OKE_VAULT_REGION = "eu-central-1";
+    process.env.OKE_VAULT_MOUNT = "oke/prod/";
+
+    const chain = buildVaultBootChain({ driverId: "managed", env: "prod" });
+    expect(chain[0]?.driver.id).toBe("env");
+    const last = chain.at(-1);
+    expect(last?.driver.id).toBe("managed");
+    const options = last?.options as VaultOpenOptions;
+    expect(options.provider).toBe("aws-secrets-manager");
+    expect(options.region).toBe("eu-central-1");
+    expect(options.mount).toBe("oke/prod/");
+  });
+
+  test("aws-secrets-manager carries region and prefix without inventing a mount", () => {
+    process.env.OKE_VAULT_PROVIDER = "aws-secrets-manager";
+    process.env.OKE_VAULT_REGION = "eu-central-1";
+
+    const chain = buildVaultBootChain({ driverId: "managed", env: "prod" });
+    const options = chain.at(-1)?.options as VaultOpenOptions;
+    expect(options.region).toBe("eu-central-1");
+    expect(options.mount).toBeUndefined();
+  });
+
+  test("built-in vault sits behind env layers", () => {
+    const chain = buildVaultBootChain({ driverId: "vault", env: "prod" });
+    expect(chain.map((l) => l.driver.id)).toContain("env");
+    expect(chain.at(-1)?.driver.id).toBe("vault");
+  });
+});
+
+describe("normalizeVaultDriverId", () => {
+  test("maps legacy labels onto protocol ids", () => {
+    expect(normalizeVaultDriverId("dotenv")).toBe("env");
+    expect(normalizeVaultDriverId("builtin")).toBe("vault");
+    expect(normalizeVaultDriverId("managed")).toBe("managed");
+    expect(normalizeVaultDriverId("vault")).toBe("vault");
+  });
+
+  test("rejects an unknown label", () => {
+    expect(() => normalizeVaultDriverId("acme")).toThrow(/unknown vault driver/);
+  });
+
+  test("rejects removed external vault driver id", () => {
+    const removed = ["open", "bao"].join("");
+    expect(() => normalizeVaultDriverId(removed)).toThrow(/unknown vault driver/);
+    expect(() => normalizeVaultDriverId(removed)).toThrow(/aws-secrets-manager/);
+  });
+});

package/src/elements/vault/boot-chain.ts

@@ -2,17 +2,17 @@
  * Shared Vault resolution-chain assembly for app boot and Console.
  *
  * Order (first hit wins): process.env → .env.local → compose .env.docker →
- * backend layer (`env` seed / openbao / memory / managed).
+ * backend layer (`env` seed / vault / memory / managed).
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import type { ConfigEnv } from "../../config/index.ts";
 import {
+  builtinVaultDriver,
   envVaultDriver,
   managedVaultDriver,
   memoryVaultDriver,
-  openbaoVaultDriver,
 } from "../../drivers/index.ts";
 import { parseDotenv } from "../../drivers/vault-dotenv-parse.ts";
 import type { VaultDriverId } from "../../drivers/vault-types.ts";
@@ -25,32 +25,30 @@ export interface BuildVaultBootChainOptions {
   readonly cwd?: string;
   /** Resolved `drivers.vault` id for the active env. */
   readonly driverId: VaultDriverId;
-  /** Active config env — controls fail-loud vs soft fallback for openbao. */
+  /** Active config env. */
   readonly env?: ConfigEnv;
   /** Seed secrets for the terminal memory / managed layer. */
   readonly seed?: Readonly<Record<string, string>>;
-  /**
-   * When `openbao` is selected but credentials are missing:
-   * - `"throw"` — fail loud (default for `prod` / `docker`)
-   * - `"memory"` — soft-fallback to a seeded memory bag (Console / local)
-   */
-  readonly missingOpenbao?: "throw" | "memory";
 }
 
 /**
  * Normalize a config label to a {@link VaultDriverId}.
  *
- * Accepts legacy `"dotenv"` as an alias for `"env"`.
+ * Accepts legacy `"dotenv"` as an alias for `"env"`, and `"builtin"` as an
+ * alias for the built-in `"vault"` store.
  *
  * @param raw - Config string
  */
 export function normalizeVaultDriverId(raw: string): VaultDriverId {
   if (raw === "dotenv") return "env";
-  if (raw === "env" || raw === "openbao" || raw === "memory" || raw === "managed") {
+  if (raw === "builtin") return "vault";
+  if (raw === "env" || raw === "vault" || raw === "memory" || raw === "managed") {
     return raw;
   }
   throw new Error(
-    `oke boot: unknown vault driver "${raw}" (expected env · openbao · memory · managed)`,
+    `oke boot: unknown vault driver "${raw}" (expected env · vault · memory · managed). ` +
+      'Official backends: built-in vault (drivers.vault: "vault"), ENV, or managed with ' +
+      'provider "aws-secrets-manager".',
   );
 }
 
@@ -69,9 +67,11 @@ export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultC
     composeText = readFileSync(composeEnv.path, "utf8").toString();
   }
   const envMap = parseDotenv(composeText);
-  const openbaoUrl = process.env.OKE_VAULT_URL ?? envMap.get("OKE_VAULT_URL");
-  const openbaoToken = process.env.OKE_VAULT_TOKEN ?? envMap.get("OKE_VAULT_TOKEN");
-  const openbaoMount = process.env.OKE_VAULT_MOUNT ?? envMap.get("OKE_VAULT_MOUNT") ?? "secret";
+  const vaultUrl = process.env.OKE_VAULT_URL ?? envMap.get("OKE_VAULT_URL");
+  const vaultToken = process.env.OKE_VAULT_TOKEN ?? envMap.get("OKE_VAULT_TOKEN");
+  const vaultMount = process.env.OKE_VAULT_MOUNT ?? envMap.get("OKE_VAULT_MOUNT");
+  const vaultProvider = process.env.OKE_VAULT_PROVIDER ?? envMap.get("OKE_VAULT_PROVIDER");
+  const vaultRegion = process.env.OKE_VAULT_REGION ?? envMap.get("OKE_VAULT_REGION");
 
   const envLayers: VaultChainLayer[] = [
     { driver: envVaultDriver, source: "process.env" },
@@ -96,14 +96,36 @@ export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultC
           options: { secrets: seed },
         },
       ];
-    case "managed":
+    case "managed": {
+      // No provider: the platform injected the values as env vars, so the
+      // driver's own env+seed bag is the whole chain.
+      if (vaultProvider === undefined || vaultProvider === "") {
+        return [
+          {
+            driver: managedVaultDriver,
+            source: "driver",
+            options: { secrets: seed },
+          },
+        ];
+      }
+      // With a remote provider the bag is remote-only, so the env layers go
+      // in front — an operator override in `process.env` still wins.
       return [
+        ...envLayers,
         {
           driver: managedVaultDriver,
           source: "driver",
-          options: { secrets: seed },
+          options: {
+            provider: vaultProvider,
+            secrets: seed,
+            ...(vaultUrl === undefined ? {} : { url: vaultUrl }),
+            ...(vaultToken === undefined ? {} : { token: vaultToken }),
+            ...(vaultMount === undefined ? {} : { mount: vaultMount }),
+            ...(vaultRegion === undefined ? {} : { region: vaultRegion }),
+          },
         },
       ];
+    }
     case "env":
       return [
         ...envLayers,
@@ -113,35 +135,17 @@ export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultC
           options: { secrets: seed },
         },
       ];
-    case "openbao": {
-      if (openbaoUrl && openbaoToken) {
-        return [
-          ...envLayers,
-          {
-            driver: openbaoVaultDriver,
-            source: "driver",
-            options: { url: openbaoUrl, token: openbaoToken, mount: openbaoMount },
-          },
-        ];
-      }
-      const env = options.env ?? "local";
-      const missing =
-        options.missingOpenbao ?? (env === "prod" || env === "docker" ? "throw" : "memory");
-      if (missing === "throw") {
-        throw new Error(
-          'oke boot: vault driver "openbao" needs OKE_VAULT_URL and OKE_VAULT_TOKEN ' +
-            "(did `oke dev -d` bootstrap OpenBao / write docker/.env.docker?)",
-        );
-      }
+    case "vault":
+      // The built-in store sits behind the env layers: an operator override
+      // in `process.env` still wins, exactly as it does for every driver.
       return [
         ...envLayers,
         {
-          driver: memoryVaultDriver,
+          driver: builtinVaultDriver,
           source: "driver",
           options: { secrets: seed },
         },
       ];
-    }
     default: {
       const _exhaustive: never = options.driverId;
       throw new Error(`oke boot: unhandled vault driver ${String(_exhaustive)}`);