okengine 0.11.1 → 0.12.0

package/src/elements/vault/runtime.ts

@@ -34,14 +34,17 @@ export class VaultBootError extends Error {
 
 /**
  * Named layer in the resolution chain (console §9.8).
- * Spec order: process.env → .env.local → .env.docker → driver → dev-fallback.
+ * Spec order: driver → process.env → .env.local → dev-fallback.
  */
-export type VaultResolutionSource =
-  | "process.env"
-  | ".env.local"
-  | ".env.docker"
-  | "driver"
-  | "dev-fallback";
+export type VaultResolutionSource = "driver" | "process.env" | ".env.local" | "dev-fallback";
+
+/** Spec lock-path — first hit wins. */
+export const VAULT_RESOLUTION_ORDER: readonly VaultResolutionSource[] = [
+  "driver",
+  "process.env",
+  ".env.local",
+  "dev-fallback",
+];
 
 /** One layer in the resolution chain. */
 export interface VaultChainLayer {
@@ -85,6 +88,11 @@ export interface CreateVaultRuntimeOptions {
    * Never enable in production boot.
    */
   readonly allowDevFallbacks?: boolean;
+  /**
+   * When true, boot succeeds with missing contracts so Console can `put`
+   * the first value. App boot must leave this off.
+   */
+  readonly allowGaps?: boolean;
   /** Clock for last-read timestamps (tests). */
   readonly now?: () => number;
 }
@@ -245,7 +253,7 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
       }
     }
     gaps.push(...requiredEnvGaps(options.requiredEnv ?? [], new Set(contracts.keys())));
-    if (gaps.length > 0) {
+    if (gaps.length > 0 && options.allowGaps !== true) {
       throw new VaultBootError(gaps);
     }
 
@@ -281,7 +289,7 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
       if (!booted) {
         throw new Error(`vault: put("${name}") before boot`);
       }
-      const idx = bags.findIndex((b) => typeof b.set === "function");
+      const idx = writableBagIndex(bags, layerSources);
       if (idx < 0) {
         throw new Error("vault: no mutable bag for put()");
       }
@@ -355,7 +363,10 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
           won: winner === "dev-fallback",
         });
       }
-      return steps;
+      return [...steps].sort(
+        (a, b) =>
+          VAULT_RESOLUTION_ORDER.indexOf(a.source) - VAULT_RESOLUTION_ORDER.indexOf(b.source),
+      );
     },
     lastReadAt(name) {
       return lastReads.get(name);
@@ -410,6 +421,32 @@ export function requiredEnvGaps(
   return gaps;
 }
 
+/**
+ * Prefer a real backend bag; for `env` driver write `.env.local` so the
+ * front memory seed does not swallow Console / `oke vault set`.
+ *
+ * @param bags - Opened bags (same order as {@link layerSources})
+ * @param layerSources - Spec source id per bag
+ */
+function writableBagIndex(
+  bags: readonly VaultBag[],
+  layerSources: readonly VaultResolutionSource[],
+): number {
+  const hasEnvLayer = bags.some((b) => b.driverId === "env");
+  const driverIdx = layerSources.findIndex(
+    (source, i) => source === "driver" && typeof bags[i]?.set === "function",
+  );
+  const localIdx = layerSources.findIndex(
+    (source, i) => source === ".env.local" && typeof bags[i]?.set === "function",
+  );
+  const driverBag = driverIdx >= 0 ? bags[driverIdx] : undefined;
+  if (driverIdx >= 0 && !(hasEnvLayer && driverBag?.driverId === "memory")) {
+    return driverIdx;
+  }
+  if (localIdx >= 0) return localIdx;
+  return bags.findIndex((b) => typeof b.set === "function");
+}
+
 /**
  * Infer the Console source id for a chain layer.
  *
@@ -422,9 +459,6 @@ export function resolveLayerSource(layer: VaultChainLayer): VaultResolutionSourc
     if (path.endsWith(".env.local") || path.includes("/.env.local")) {
       return ".env.local";
     }
-    if (path.endsWith(".env.docker") || path.includes("/.env.docker")) {
-      return ".env.docker";
-    }
   }
   if (layer.driver.id === "env" && path === undefined) {
     return "process.env";

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

@@ -1,9 +1,11 @@
 /**
  * Phase 10 security checklist — threat-model assertions for the built-in vault.
+ *
+ * SQL-backed cases use the in-memory Vault SQL fake: these tests assert seal
+ * physics and audit integrity, not Postgres dialect / pgvector behavior.
  */
 
 import { describe, expect, test } from "bun:test";
-import { connectPglite } from "../../drivers/pglite.ts";
 import type { SqlConnection } from "../../drivers/types.ts";
 import {
   createBuiltinVaultAdapter,
@@ -23,16 +25,17 @@ import {
 import { VaultError } from "./errors.ts";
 import { canonicalizePath } from "./path.ts";
 import type { SqlExec } from "./storage.ts";
+import { createMemoryVaultSql } from "./test-helpers.ts";
 import { createMemoryUnsealer } from "./unseal.ts";
 
-/** Fresh initialized + unsealed adapter. */
+/** Fresh initialized + unsealed adapter over the in-memory Vault SQL fake. */
 async function harness(): Promise<{
   adapter: BuiltinVaultAdapter;
   db: SqlExec;
   conn: SqlConnection;
   close(): Promise<void>;
 }> {
-  const conn = await connectPglite({ url: `memory://vault-sec-${crypto.randomUUID()}` });
+  const conn = createMemoryVaultSql();
   const db = sqlConnectionAsExec(conn);
   const adapter = createBuiltinVaultAdapter({ db });
   const init = await adapter.initialize!();
@@ -53,12 +56,11 @@ describe("vault security checklist", () => {
     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",
-      );
+      const rows = await h.conn.query("select encrypted_value from oke_vault_secrets");
       for (const row of rows) {
-        const blob = String((row as { blob?: unknown }).blob ?? "");
-        expect(blob.includes(secret)).toBe(false);
+        const raw = (row as { encrypted_value?: unknown }).encrypted_value;
+        const bytes = raw instanceof Uint8Array ? raw : new Uint8Array();
+        expect(Buffer.from(bytes).toString("utf8").includes(secret)).toBe(false);
       }
     } finally {
       await h.close();

package/src/elements/vault/storage.ts

@@ -35,6 +35,27 @@ export interface SqlExec {
    * @param params - Positional parameters
    */
   execute(sql: string, params?: unknown[]): Promise<void>;
+  /**
+   * Optional transactional scope — required for `FOR UPDATE` / `SKIP LOCKED`
+   * lease and audit serialization (Clock / Signal class).
+   *
+   * @param fn - Work that must see a single snapshot under row locks
+   */
+  begin?<T>(fn: (tx: SqlExec) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Run `fn` inside {@link SqlExec.begin} when available.
+ *
+ * @param db - SQL surface
+ * @param fn - Transactional work
+ */
+export async function withSqlTransaction<T>(
+  db: SqlExec,
+  fn: (tx: SqlExec) => Promise<T>,
+): Promise<T> {
+  if (db.begin) return db.begin(fn);
+  return fn(db);
 }
 
 /** Encrypted secret versions. One row per `(path, version)`. */
@@ -122,10 +143,21 @@ CREATE TABLE IF NOT EXISTS oke_vault_status (
   rewrap_checkpoint text,
   rewrap_target_kek_version integer,
   rewrap_key_hash text,
+  rotate_locked_by text,
+  rotate_lease_expires_at bigint,
   updated_at timestamptz NOT NULL DEFAULT now(),
   CONSTRAINT oke_vault_status_singleton CHECK (id = 1)
 )`;
 
+/**
+ * Claim the rotate-master lease — same predicate as Clock/Signal
+ * (`FOR UPDATE SKIP LOCKED` + lease-expiry reclaim).
+ */
+export const CLAIM_ROTATE_LEASE_SQL: string = `SELECT id FROM oke_vault_status WHERE id = 1 AND ((rotate_locked_by IS NULL) OR (rotate_locked_by = $1) OR (rotate_lease_expires_at IS NULL) OR (rotate_lease_expires_at <= $2)) FOR UPDATE SKIP LOCKED`;
+
+/** Default rotate-master lease TTL (ms) — lazy reclaim, no sweeper. */
+export const DEFAULT_ROTATE_LEASE_MS: number = 30_000;
+
 /** Index / seed statements applied after the tables exist. */
 const POST_DDL_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS oke_vault_secrets_path_idx ON oke_vault_secrets (path) WHERE deleted_at IS NULL`,
@@ -134,6 +166,8 @@ const POST_DDL_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS oke_vault_keys_kek_version_idx ON oke_vault_keys (kek_version)`,
   `ALTER TABLE oke_vault_audit ADD COLUMN IF NOT EXISTS seq bigserial NOT NULL`,
   `ALTER TABLE oke_vault_status ADD COLUMN IF NOT EXISTS rewrap_key_hash text`,
+  `ALTER TABLE oke_vault_status ADD COLUMN IF NOT EXISTS rotate_locked_by text`,
+  `ALTER TABLE oke_vault_status ADD COLUMN IF NOT EXISTS rotate_lease_expires_at bigint`,
   `CREATE INDEX IF NOT EXISTS oke_vault_audit_seq_idx ON oke_vault_audit (seq)`,
   `CREATE INDEX IF NOT EXISTS oke_vault_audit_created_idx ON oke_vault_audit (created_at, id)`,
   `CREATE INDEX IF NOT EXISTS oke_vault_audit_path_idx ON oke_vault_audit (path)`,
@@ -304,7 +338,33 @@ export async function readAuditPage(
     throw new VaultError("BACKEND_ERROR", "vault: failed to read audit rows");
   }
 
-  return rows.map((row) => ({
+  return rows.map((row) => toAuditRecord(row));
+}
+
+/**
+ * Load one audit row by id (operator-safe fields, no chain hashes).
+ *
+ * @param db - SQL surface
+ * @param id - Audit row id
+ */
+export async function readAuditRow(db: SqlExec, id: string): Promise<VaultAuditRecord | null> {
+  let rows: (AuditDbRow & { seq: number | string | bigint })[];
+  try {
+    rows = await db.query(
+      `SELECT id, seq, action, path, actor_type, actor_id, success, error_code, error_message,
+              request_id, prev_hash, row_hash, created_at
+       FROM oke_vault_audit WHERE id = $1`,
+      [id],
+    );
+  } catch {
+    throw new VaultError("BACKEND_ERROR", "vault: failed to read audit row");
+  }
+  const row = rows[0];
+  return row === undefined ? null : toAuditRecord(row);
+}
+
+function toAuditRecord(row: AuditDbRow & { seq: number | string | bigint }): VaultAuditRecord {
+  return {
     id: row.id,
     seq: typeof row.seq === "number" ? row.seq : Number(row.seq),
     action: row.action as AuditAction,
@@ -316,15 +376,20 @@ export async function readAuditPage(
     errorMessage: row.error_message,
     requestId: row.request_id,
     createdAt: row.created_at instanceof Date ? row.created_at : new Date(row.created_at),
-  }));
+  };
 }
 
+/** Why {@link verifyAuditChain} rejected a row. */
+export type AuditChainBreakReason = "link" | "payload";
+
 /** Result of {@link verifyAuditChain}. */
 export interface AuditChainResult {
   /** Whether every retained row hashes and links correctly. */
   readonly ok: boolean;
   /** Id of the first row that failed verification. */
   readonly brokenAt?: string;
+  /** `link` = prev_hash mismatch; `payload` = stored row_hash ≠ recomputed. */
+  readonly reason?: AuditChainBreakReason;
 }
 
 /** Raw `oke_vault_audit` row shape. */
@@ -370,7 +435,7 @@ export async function verifyAuditChain(db: SqlExec): Promise<AuditChainResult> {
   let previousHash: string | undefined;
   for (const row of rows) {
     if (previousHash !== undefined && row.prev_hash !== previousHash) {
-      return { ok: false, brokenAt: row.id };
+      return { ok: false, brokenAt: row.id, reason: "link" };
     }
     const expected = await computeAuditRowHash(row.prev_hash, {
       action: row.action as AuditAction,
@@ -384,20 +449,85 @@ export async function verifyAuditChain(db: SqlExec): Promise<AuditChainResult> {
       createdAt: toIso(row.created_at),
     });
     if (expected !== row.row_hash) {
-      return { ok: false, brokenAt: row.id };
+      return { ok: false, brokenAt: row.id, reason: "payload" };
     }
     previousHash = row.row_hash;
   }
   return { ok: true };
 }
 
+/**
+ * Acquire the rotate-master lease (Clock/Signal SKIP LOCKED + lease-expiry).
+ *
+ * Exactly one concurrent claimant wins; losers get `false` immediately
+ * (no wait). A crashed holder's lease is reclaimed lazily when
+ * `rotate_lease_expires_at <= now`.
+ *
+ * @param db - SQL surface (uses {@link SqlExec.begin} when present)
+ * @param holderId - Claimant id (per rotation attempt)
+ * @param now - Epoch-ms
+ * @param leaseMs - Lease TTL
+ */
+export async function acquireRotateLease(
+  db: SqlExec,
+  holderId: string,
+  now: number,
+  leaseMs: number = DEFAULT_ROTATE_LEASE_MS,
+): Promise<boolean> {
+  return withSqlTransaction(db, async (tx) => {
+    const claimed = await tx.query<{ id: number | string }>(CLAIM_ROTATE_LEASE_SQL, [
+      holderId,
+      now,
+    ]);
+    if (!claimed[0]) return false;
+    await tx.execute(
+      `UPDATE oke_vault_status
+       SET rotate_locked_by = $1, rotate_lease_expires_at = $2, updated_at = now()
+       WHERE id = 1`,
+      [holderId, now + leaseMs],
+    );
+    return true;
+  });
+}
+
+/**
+ * Drop the rotate-master lease when this holder still owns it.
+ *
+ * @param db - SQL surface
+ * @param holderId - Holder that acquired the lease
+ */
+export async function releaseRotateLease(db: SqlExec, holderId: string): Promise<void> {
+  await db.execute(
+    `UPDATE oke_vault_status
+     SET rotate_locked_by = NULL, rotate_lease_expires_at = NULL, updated_at = now()
+     WHERE id = 1 AND rotate_locked_by = $1`,
+    [holderId],
+  );
+}
+
+/**
+ * Renew the rotate-master lease for a long rewrap.
+ *
+ * @param db - SQL surface
+ * @param holderId - Current holder
+ * @param now - Epoch-ms
+ * @param leaseMs - Lease TTL
+ */
+export async function renewRotateLease(
+  db: SqlExec,
+  holderId: string,
+  now: number,
+  leaseMs: number = DEFAULT_ROTATE_LEASE_MS,
+): Promise<boolean> {
+  return acquireRotateLease(db, holderId, now, leaseMs);
+}
+
 /**
  * Backend-side {@link AuditWriter} over `oke_vault_audit`.
  *
- * Reads the current chain head, links the new row to it, and inserts.
- * Concurrent appends must be serialized by the caller (a transaction with
- * `SELECT … FOR UPDATE` on the head, or a single writer) — two racing
- * appends would otherwise share a `prev_hash`.
+ * Appends run inside a transaction that locks the status singleton with
+ * `SELECT … FOR UPDATE` so concurrent writers cannot share a `prev_hash`
+ * (same exclusivity class as Signal competing consumers).
  *
  * @param db - SQL surface
  */
@@ -407,29 +537,33 @@ export function createSqlAuditWriter(db: SqlExec): AuditWriter {
       const createdAt = entry.at ?? new Date();
       const payload = toAuditHashPayload(entry, createdAt);
       try {
-        const head = await db.query<{ row_hash: string }>(
-          `SELECT row_hash FROM oke_vault_audit ORDER BY seq DESC LIMIT 1`,
-        );
-        const prevHash = head[0]?.row_hash ?? AUDIT_GENESIS_HASH;
-        const rowHash = await computeAuditRowHash(prevHash, payload);
-        await db.execute(
-          `INSERT INTO oke_vault_audit
-             (action, path, actor_type, actor_id, success, error_code, error_message, request_id, prev_hash, row_hash, created_at)
-           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
-          [
-            payload.action,
-            payload.path,
-            payload.actorType,
-            payload.actorId,
-            payload.success,
-            payload.errorCode,
-            payload.errorMessage,
-            payload.requestId,
-            prevHash,
-            rowHash,
-            createdAt,
-          ],
-        );
+        await withSqlTransaction(db, async (tx) => {
+          // Serialize writers on the singleton — FOR UPDATE waits, does not skip.
+          await tx.query(`SELECT id FROM oke_vault_status WHERE id = 1 FOR UPDATE`);
+          const head = await tx.query<{ row_hash: string }>(
+            `SELECT row_hash FROM oke_vault_audit ORDER BY seq DESC LIMIT 1`,
+          );
+          const prevHash = head[0]?.row_hash ?? AUDIT_GENESIS_HASH;
+          const rowHash = await computeAuditRowHash(prevHash, payload);
+          await tx.execute(
+            `INSERT INTO oke_vault_audit
+               (action, path, actor_type, actor_id, success, error_code, error_message, request_id, prev_hash, row_hash, created_at)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+            [
+              payload.action,
+              payload.path,
+              payload.actorType,
+              payload.actorId,
+              payload.success,
+              payload.errorCode,
+              payload.errorMessage,
+              payload.requestId,
+              prevHash,
+              rowHash,
+              createdAt,
+            ],
+          );
+        });
       } catch (error) {
         if (error instanceof VaultError) throw error;
         throw new VaultError("BACKEND_ERROR", "vault: failed to append audit row");