okengine 0.10.2 → 0.11.0

package/src/elements/vault/resilience.ts

@@ -0,0 +1,107 @@
+/**
+ * Retry wrapper for Vault SQL — connection blips, not business errors.
+ *
+ * Audit writes must use the raw {@link SqlExec}: retrying an append can
+ * duplicate rows and break the hash chain.
+ */
+
+import type { SqlExec } from "./storage.ts";
+
+/** Tunables for {@link withResilience}. */
+export interface RetryConfig {
+  /** Attempts after the first failure. */
+  readonly maxRetries: number;
+  /** Initial backoff in milliseconds. */
+  readonly baseDelayMs: number;
+  /** Cap on exponential backoff. */
+  readonly maxDelayMs: number;
+  /** Substrings matched against `error.code` or `error.message`. */
+  readonly retryableErrors: readonly string[];
+}
+
+/** Default Postgres / network blip codes. */
+export const DEFAULT_RETRY: RetryConfig = {
+  maxRetries: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 5000,
+  retryableErrors: ["ECONNRESET", "ETIMEDOUT", "08006", "08003", "57P01"],
+};
+
+/**
+ * Whether `error` looks like a transient connection failure.
+ *
+ * @param error - Caught value
+ * @param config - Retry tunables
+ */
+export function isRetryableError(error: unknown, config: RetryConfig = DEFAULT_RETRY): boolean {
+  if (!error || typeof error !== "object") return false;
+  const record = error as { code?: string | number; message?: string };
+  const code =
+    typeof record.code === "string" || typeof record.code === "number" ? String(record.code) : "";
+  const message =
+    typeof record.message === "string"
+      ? record.message
+      : error instanceof Error
+        ? error.message
+        : "";
+  return config.retryableErrors.some(
+    (retryable) => code.includes(retryable) || message.includes(retryable),
+  );
+}
+
+/**
+ * Sleep without journaling (CLI / adapter path, not a durable Flow step).
+ *
+ * @param ms - Delay
+ */
+export async function sleep(ms: number): Promise<void> {
+  await new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Run `operation` with exponential backoff on retryable failures.
+ *
+ * @param operation - Thunk to retry
+ * @param config - Retry tunables
+ */
+export async function withResilience<T>(
+  operation: () => Promise<T>,
+  config: RetryConfig = DEFAULT_RETRY,
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt === config.maxRetries) break;
+      if (!isRetryableError(error, config)) throw error;
+      const delay = Math.min(config.baseDelayMs * 2 ** attempt, config.maxDelayMs);
+      console.warn(`[vault] Query failed (attempt ${attempt + 1}), retrying in ${delay}ms...`);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Wrap a {@link SqlExec} so every `query` / `execute` retries on blips.
+ *
+ * Do **not** pass the result to {@link createSqlAuditWriter} — audit must
+ * fail loudly or be best-effort without duplicate appends.
+ *
+ * @param db - Underlying SQL surface
+ * @param config - Retry tunables
+ */
+export function createResilientSqlExec(db: SqlExec, config: RetryConfig = DEFAULT_RETRY): SqlExec {
+  return {
+    query<T>(sql: string, params?: unknown[]): Promise<T[]> {
+      return withResilience(() => db.query<T>(sql, params), config);
+    },
+    execute(sql: string, params?: unknown[]): Promise<void> {
+      return withResilience(() => db.execute(sql, params), config);
+    },
+  };
+}

package/src/elements/vault/runtime.ts

@@ -3,7 +3,7 @@
  */
 
 import type { VaultBag, VaultDriver } from "../../drivers/vault-types.ts";
-import { fromDockerRole, isFromDocker } from "./declare.ts";
+import { fromDockerRole, isFromDocker, readEnv } from "./declare.ts";
 import type { VaultSecretDecl } from "./declare.ts";
 import { fingerprintSecretSync } from "./fingerprint.ts";
 import { createSecretRedactor, SECRET_MASK } from "./redact.ts";
@@ -69,9 +69,15 @@ export interface VaultResolutionStep {
 export interface CreateVaultRuntimeOptions {
   /** Declared secret / config contracts. */
   readonly secrets?: readonly VaultSecretDecl[];
+  /**
+   * Environment variables declared through `vault.env.required`. Missing
+   * ones are reported as {@link VaultGap}s in the same boot pass as secrets,
+   * so one run lists every hole in the configuration.
+   */
+  readonly requiredEnv?: readonly string[];
   /**
    * Resolution chain — first hit wins.
-   * Callers pass the env-appropriate layers (env / openbao / memory / …).
+   * Callers pass the env-appropriate layers (env / vault / memory / managed).
    */
   readonly chain?: readonly VaultChainLayer[];
   /**
@@ -88,7 +94,7 @@ export interface VaultRuntime {
   /** Declared contracts by name. */
   readonly contracts: ReadonlyMap<string, VaultSecretDecl>;
   /**
-   * Driver ids of each chain layer in order (`env` · `openbao` · `memory` · `managed`).
+   * Driver ids of each chain layer in order (`env` · `vault` · `memory` · `managed`).
    * Available before {@link boot}.
    */
   readonly chainDriverIds: readonly string[];
@@ -100,7 +106,7 @@ export interface VaultRuntime {
   /** Whether {@link boot} has succeeded. */
   readonly booted: boolean;
   /**
-   * Read a secret (capability is enforced by `fx.vault`).
+   * Read a secret (capability is enforced by `fx.vault.get`).
    * Records {@link lastReadAt}.
    *
    * @param name - Secret name
@@ -238,6 +244,7 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
         });
       }
     }
+    gaps.push(...requiredEnvGaps(options.requiredEnv ?? [], new Set(contracts.keys())));
     if (gaps.length > 0) {
       throw new VaultBootError(gaps);
     }
@@ -378,6 +385,31 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
   };
 }
 
+/**
+ * Gaps for every `vault.env.required` name absent from the process
+ * environment. Names that are also declared contracts are skipped — those
+ * resolve through the boot chain (`.env.local`, driver, dev fallback), so
+ * `process.env` alone would report a false gap.
+ *
+ * @param names - Required environment variable names
+ * @param declared - Contract names already validated by the boot chain
+ */
+export function requiredEnvGaps(
+  names: readonly string[],
+  declared: ReadonlySet<string> = new Set(),
+): VaultGap[] {
+  const gaps: VaultGap[] = [];
+  const seen = new Set<string>();
+  for (const name of names) {
+    if (declared.has(name) || seen.has(name)) continue;
+    seen.add(name);
+    if (readEnv(name) === undefined) {
+      gaps.push({ name, description: "required environment variable (vault.env.required)" });
+    }
+  }
+  return gaps;
+}
+
 /**
  * Infer the Console source id for a chain layer.
  *

package/src/elements/vault/security-checklist.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Phase 10 security checklist — threat-model assertions for the built-in vault.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { connectPglite } from "../../drivers/pglite.ts";
+import type { SqlConnection } from "../../drivers/types.ts";
+import {
+  createBuiltinVaultAdapter,
+  sqlConnectionAsExec,
+  type BuiltinVaultAdapter,
+} from "./builtin-adapter.ts";
+import {
+  ALGORITHM,
+  buildAad,
+  decryptSecret,
+  encryptSecret,
+  generateDek,
+  importAesKey,
+  unwrapDek,
+  wrapDek,
+} from "./crypto.ts";
+import { VaultError } from "./errors.ts";
+import { canonicalizePath } from "./path.ts";
+import type { SqlExec } from "./storage.ts";
+import { createMemoryUnsealer } from "./unseal.ts";
+
+/** Fresh initialized + unsealed adapter. */
+async function harness(): Promise<{
+  adapter: BuiltinVaultAdapter;
+  db: SqlExec;
+  conn: SqlConnection;
+  close(): Promise<void>;
+}> {
+  const conn = await connectPglite({ url: `memory://vault-sec-${crypto.randomUUID()}` });
+  const db = sqlConnectionAsExec(conn);
+  const adapter = createBuiltinVaultAdapter({ db });
+  const init = await adapter.initialize!();
+  await adapter.unseal!(init.masterKey);
+  return {
+    adapter,
+    db,
+    conn,
+    async close() {
+      await conn.close();
+    },
+  };
+}
+
+describe("vault security checklist", () => {
+  test("DB rows never contain the cleartext secret", async () => {
+    const h = await harness();
+    try {
+      const secret = `sk_live_${crypto.randomUUID()}`;
+      await h.adapter.set("prod/api/stripe", secret);
+      const rows = await h.conn.query(
+        "select encode(encrypted_value, 'escape') as blob from oke_vault_secrets",
+      );
+      for (const row of rows) {
+        const blob = String((row as { blob?: unknown }).blob ?? "");
+        expect(blob.includes(secret)).toBe(false);
+      }
+    } finally {
+      await h.close();
+    }
+  });
+
+  test("sealed vault fails closed on get and set", async () => {
+    const h = await harness();
+    try {
+      await h.adapter.set("a/b", "v1");
+      await h.adapter.seal!();
+      await expect(h.adapter.get("a/b")).rejects.toBeInstanceOf(VaultError);
+      await expect(h.adapter.set("a/b", "v2")).rejects.toBeInstanceOf(VaultError);
+    } finally {
+      await h.close();
+    }
+  });
+
+  test("canonical path is what enters AAD — non-canonical input is rejected before store", () => {
+    expect(() => canonicalizePath("../etc/passwd")).toThrow(VaultError);
+    expect(() => canonicalizePath("a\\b")).toThrow(VaultError);
+    expect(() => canonicalizePath("a\0b")).toThrow(VaultError);
+    expect(canonicalizePath("/prod//api/stripe/")).toBe("prod/api/stripe");
+  });
+
+  test("AAD path mismatch fails decrypt even with the correct DEK", async () => {
+    const dekBytes = generateDek();
+    const dek = await importAesKey(dekBytes);
+    const aad = buildAad("prod/api/stripe", 1, ALGORITHM, 1);
+    const sealed = await encryptSecret(dek, "plain", aad);
+    const wrongAad = buildAad("prod/api/other", 1, ALGORITHM, 1);
+    await expect(decryptSecret(dek, sealed, wrongAad)).rejects.toBeInstanceOf(VaultError);
+  });
+
+  test("VaultError from unwrap paths never exposes a cause chain", async () => {
+    const unsealer = createMemoryUnsealer(crypto.getRandomValues(new Uint8Array(32)));
+    const kek = await unsealer.unwrapKek();
+    const dekBytes = generateDek();
+    const aad = buildAad("p", 1, ALGORITHM, 1);
+    const wrapped = await wrapDek(kek, dekBytes, aad);
+    const other = createMemoryUnsealer(crypto.getRandomValues(new Uint8Array(32)));
+    const otherKek = await other.unwrapKek();
+    try {
+      await unwrapDek(otherKek, wrapped, aad);
+      expect.unreachable();
+    } catch (err) {
+      expect(err).toBeInstanceOf(VaultError);
+      expect((err as Error & { cause?: unknown }).cause).toBeUndefined();
+      expect(String(err)).not.toContain(Buffer.from(dekBytes).toString("base64"));
+    }
+    unsealer.seal();
+    other.seal();
+  });
+
+  test("audit verify detects a tampered row_hash", async () => {
+    const h = await harness();
+    try {
+      await h.adapter.set("x/y", "one");
+      await h.conn.exec(
+        "update oke_vault_audit set row_hash = $1 where seq = (select max(seq) from oke_vault_audit)",
+        ["0".repeat(64)],
+      );
+      const result = await h.adapter.verifyAudit();
+      expect(result.ok).toBe(false);
+    } finally {
+      await h.close();
+    }
+  });
+});