okengine 0.2.2 → 0.2.3

package/src/console/server/operator-db.ts

@@ -0,0 +1,324 @@
+/**
+ * Durable operator plane for Console — `.oke/console.sqlite` + secret file.
+ *
+ * Spec: wizard closes permanently once the first operator exists (console §2.5).
+ * Claim codes stay ephemeral; operators and the signing secret must survive restarts.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+import {
+  createOperatorStore,
+  type OperatorStore,
+} from "../../auth/operator.ts";
+import type {
+  OperatorCredentialRow,
+  OperatorRow,
+  OperatorSsoLinkRow,
+} from "../../auth/tables.ts";
+import { AUTH_TABLES } from "../../auth/tables.ts";
+
+/** Relative paths under project cwd. */
+export const CONSOLE_OKE_DIR = ".oke";
+export const CONSOLE_SQLITE_NAME = "console.sqlite";
+export const CONSOLE_SECRET_NAME = "console.secret";
+
+/** Opened Console persistence handle. */
+export interface ConsolePersistence {
+  /** Stable signing secret. */
+  readonly secret: string;
+  /** Hydrated operator Maps. */
+  readonly operators: OperatorStore;
+  /** Persist (or update) one operator + credential + roles/sso. */
+  readonly persistOperator: (operatorId: string) => void;
+  /** Close the SQLite connection. */
+  readonly close: () => void;
+}
+
+/**
+ * Ensure `.oke/` exists and return absolute paths.
+ *
+ * @param cwd - Project root
+ */
+export function consoleOkePaths(cwd: string): {
+  readonly dir: string;
+  readonly sqlite: string;
+  readonly secret: string;
+} {
+  const dir = join(cwd, CONSOLE_OKE_DIR);
+  mkdirSync(dir, { recursive: true });
+  return {
+    dir,
+    sqlite: join(dir, CONSOLE_SQLITE_NAME),
+    secret: join(dir, CONSOLE_SECRET_NAME),
+  };
+}
+
+/**
+ * Load or create a stable Console signing secret under `.oke/console.secret`.
+ *
+ * @param cwd - Project root
+ * @param envSecret - Optional `OKE_CONSOLE_SECRET` override
+ */
+export async function resolveConsoleSecret(
+  cwd: string,
+  envSecret?: string,
+): Promise<string> {
+  if (envSecret !== undefined && envSecret.length > 0) return envSecret;
+  const paths = consoleOkePaths(cwd);
+  const file = Bun.file(paths.secret);
+  if (await file.exists()) {
+    const existing = (await file.text()).trim();
+    if (existing.length > 0) return existing;
+  }
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const secret = [...bytes]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  await Bun.write(paths.secret, `${secret}\n`);
+  return secret;
+}
+
+/**
+ * Open Console operator DB, migrate schema, hydrate Maps.
+ *
+ * @param cwd - Project root
+ * @param options - Optional env secret override
+ */
+export async function openConsolePersistence(
+  cwd: string,
+  options: { readonly envSecret?: string } = {},
+): Promise<ConsolePersistence> {
+  const paths = consoleOkePaths(cwd);
+  const secret = await resolveConsoleSecret(cwd, options.envSecret);
+  const db = new Database(paths.sqlite, { create: true });
+  db.exec("PRAGMA journal_mode = WAL;");
+  migrateOperatorSchema(db);
+  const operators = loadOperatorStore(db);
+
+  return {
+    secret,
+    operators,
+    persistOperator(operatorId: string) {
+      persistOperator(db, operators, operatorId);
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+/**
+ * Create operator tables if missing.
+ *
+ * @param db - bun:sqlite database
+ */
+export function migrateOperatorSchema(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operators} (
+      id TEXT PRIMARY KEY NOT NULL,
+      email TEXT NOT NULL UNIQUE,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL,
+      mfa_enabled INTEGER NOT NULL DEFAULT 0,
+      invited_by TEXT,
+      last_seen_at INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operatorCredentials} (
+      operator_id TEXT PRIMARY KEY NOT NULL,
+      password_hash TEXT NOT NULL,
+      login_enabled INTEGER NOT NULL DEFAULT 1,
+      FOREIGN KEY (operator_id) REFERENCES ${AUTH_TABLES.operators}(id)
+    );
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operatorSsoLinks} (
+      operator_id TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      PRIMARY KEY (operator_id, provider, subject),
+      FOREIGN KEY (operator_id) REFERENCES ${AUTH_TABLES.operators}(id)
+    );
+    CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.operatorRoles} (
+      operator_id TEXT NOT NULL,
+      role TEXT NOT NULL,
+      PRIMARY KEY (operator_id, role),
+      FOREIGN KEY (operator_id) REFERENCES ${AUTH_TABLES.operators}(id)
+    );
+  `);
+}
+
+/**
+ * Hydrate an {@link OperatorStore} from SQLite.
+ *
+ * @param db - Open database
+ */
+export function loadOperatorStore(db: Database): OperatorStore {
+  const store = createOperatorStore();
+
+  const opRows = db
+    .query(
+      `SELECT id, email, name, status, mfa_enabled, invited_by, last_seen_at
+       FROM ${AUTH_TABLES.operators}`,
+    )
+    .all() as Array<{
+    id: string;
+    email: string;
+    name: string;
+    status: OperatorRow["status"];
+    mfa_enabled: number;
+    invited_by: string | null;
+    last_seen_at: number | null;
+  }>;
+
+  for (const row of opRows) {
+    store.operators.set(row.id, {
+      id: row.id,
+      email: row.email,
+      name: row.name,
+      status: row.status,
+      mfaEnabled: row.mfa_enabled === 1,
+      invitedBy: row.invited_by,
+      lastSeenAt: row.last_seen_at,
+    });
+  }
+
+  const credRows = db
+    .query(
+      `SELECT operator_id, password_hash, login_enabled
+       FROM ${AUTH_TABLES.operatorCredentials}`,
+    )
+    .all() as Array<{
+    operator_id: string;
+    password_hash: string;
+    login_enabled: number;
+  }>;
+
+  for (const row of credRows) {
+    const cred: OperatorCredentialRow = {
+      operatorId: row.operator_id,
+      passwordHash: row.password_hash,
+      loginEnabled: row.login_enabled === 1,
+    };
+    store.credentials.set(row.operator_id, cred);
+  }
+
+  const ssoRows = db
+    .query(
+      `SELECT operator_id, provider, subject FROM ${AUTH_TABLES.operatorSsoLinks}`,
+    )
+    .all() as Array<{
+    operator_id: string;
+    provider: string;
+    subject: string;
+  }>;
+
+  for (const row of ssoRows) {
+    const link: OperatorSsoLinkRow = {
+      operatorId: row.operator_id,
+      provider: row.provider,
+      subject: row.subject,
+    };
+    const list = store.ssoLinks.get(row.operator_id) ?? [];
+    list.push(link);
+    store.ssoLinks.set(row.operator_id, list);
+  }
+
+  const roleRows = db
+    .query(
+      `SELECT operator_id, role FROM ${AUTH_TABLES.operatorRoles}`,
+    )
+    .all() as Array<{ operator_id: string; role: string }>;
+
+  for (const row of roleRows) {
+    const list = store.roles.get(row.operator_id) ?? [];
+    list.push(row.role);
+    store.roles.set(row.operator_id, list);
+  }
+
+  return store;
+}
+
+/**
+ * Upsert one operator (and related rows) from the in-memory store.
+ *
+ * @param db - Open database
+ * @param store - In-memory store
+ * @param operatorId - Operator id
+ */
+export function persistOperator(
+  db: Database,
+  store: OperatorStore,
+  operatorId: string,
+): void {
+  const op = store.operators.get(operatorId);
+  if (!op) {
+    throw new Error(`oke console: unknown operator ${operatorId}`);
+  }
+  const cred = store.credentials.get(operatorId);
+  if (!cred) {
+    throw new Error(`oke console: missing credential for ${operatorId}`);
+  }
+
+  const upsertOp = db.query(
+    `INSERT INTO ${AUTH_TABLES.operators}
+      (id, email, name, status, mfa_enabled, invited_by, last_seen_at)
+     VALUES ($id, $email, $name, $status, $mfa, $invited, $seen)
+     ON CONFLICT(id) DO UPDATE SET
+       email = excluded.email,
+       name = excluded.name,
+       status = excluded.status,
+       mfa_enabled = excluded.mfa_enabled,
+       invited_by = excluded.invited_by,
+       last_seen_at = excluded.last_seen_at`,
+  );
+  upsertOp.run({
+    $id: op.id,
+    $email: op.email,
+    $name: op.name,
+    $status: op.status,
+    $mfa: op.mfaEnabled ? 1 : 0,
+    $invited: op.invitedBy,
+    $seen: op.lastSeenAt,
+  });
+
+  const upsertCred = db.query(
+    `INSERT INTO ${AUTH_TABLES.operatorCredentials}
+      (operator_id, password_hash, login_enabled)
+     VALUES ($id, $hash, $enabled)
+     ON CONFLICT(operator_id) DO UPDATE SET
+       password_hash = excluded.password_hash,
+       login_enabled = excluded.login_enabled`,
+  );
+  upsertCred.run({
+    $id: cred.operatorId,
+    $hash: cred.passwordHash,
+    $enabled: cred.loginEnabled ? 1 : 0,
+  });
+
+  db.query(
+    `DELETE FROM ${AUTH_TABLES.operatorSsoLinks} WHERE operator_id = $id`,
+  ).run({ $id: operatorId });
+  const insertSso = db.query(
+    `INSERT INTO ${AUTH_TABLES.operatorSsoLinks} (operator_id, provider, subject)
+     VALUES ($id, $provider, $subject)`,
+  );
+  for (const link of store.ssoLinks.get(operatorId) ?? []) {
+    insertSso.run({
+      $id: link.operatorId,
+      $provider: link.provider,
+      $subject: link.subject,
+    });
+  }
+
+  db.query(
+    `DELETE FROM ${AUTH_TABLES.operatorRoles} WHERE operator_id = $id`,
+  ).run({ $id: operatorId });
+  const insertRole = db.query(
+    `INSERT INTO ${AUTH_TABLES.operatorRoles} (operator_id, role)
+     VALUES ($id, $role)`,
+  );
+  for (const role of store.roles.get(operatorId) ?? []) {
+    insertRole.run({ $id: operatorId, $role: role });
+  }
+}

package/src/console/server/serve.ts

@@ -22,6 +22,7 @@ import {
   type CreateConsoleAppOptions,
 } from "./app.ts";
 import { createLiveWebsocket, type ConsoleLiveData } from "./live.ts";
+import { openConsolePersistence } from "./operator-db.ts";
 import {
   CONSOLE_COOKIES,
   consoleSessionCookie,
@@ -37,6 +38,11 @@ export interface ServeConsoleOptions extends CreateConsoleAppOptions {
   readonly staticDir?: string;
   /** Boot environment — use `"dev"` / `"prod"` so Bearer auth is production-like. */
   readonly env?: "dev" | "prod" | "test";
+  /**
+   * Persist operators + secret under `.oke/` (default true).
+   * Set false for ephemeral test servers.
+   */
+  readonly persist?: boolean;
 }
 
 /** Running Console server handle. */
@@ -54,9 +60,24 @@ export async function serveConsole(
 ): Promise<ConsoleServerHandle> {
   const hostname = options.hostname ?? "127.0.0.1";
   const port = options.port ?? CONSOLE_PORT;
+  const cwd = options.cwd ?? process.cwd();
+  const wantPersist = options.persist !== false && options.operators === undefined;
+  const persistence = wantPersist
+    ? await openConsolePersistence(cwd, {
+        envSecret: options.secret ?? process.env.OKE_CONSOLE_SECRET,
+      })
+    : null;
   const handle = createConsoleApp({
     ...options,
+    cwd,
     silentClaim: options.silentClaim ?? false,
+    ...(persistence
+      ? {
+          secret: options.secret ?? persistence.secret,
+          operators: persistence.operators,
+          persistOperator: persistence.persistOperator,
+        }
+      : {}),
   });
 
   const env = options.env ?? "dev";
@@ -160,6 +181,7 @@ export async function serveConsole(
     stop(closeActive = false) {
       server.stop(closeActive);
       void handle.app.stop();
+      persistence?.close();
     },
   };
 }
@@ -172,11 +194,28 @@ export async function serveConsole(
 export async function startConsoleApp(
   options: CreateConsoleAppOptions & {
     readonly env?: "dev" | "prod" | "test";
+    /** Opt-in durable operators under `.oke/` (default false for unit tests). */
+    readonly persist?: boolean;
   } = {},
 ): Promise<ConsoleAppHandle> {
+  const cwd = options.cwd ?? process.cwd();
+  const persistence =
+    options.persist === true && options.operators === undefined
+      ? await openConsolePersistence(cwd, {
+          envSecret: options.secret ?? process.env.OKE_CONSOLE_SECRET,
+        })
+      : null;
   const handle = createConsoleApp({
     ...options,
+    cwd,
     silentClaim: options.silentClaim ?? true,
+    ...(persistence
+      ? {
+          secret: options.secret ?? persistence.secret,
+          operators: persistence.operators,
+          persistOperator: persistence.persistOperator,
+        }
+      : {}),
   });
   await bootConsoleApp(handle);
   return handle;

package/src/console/server/state.ts

@@ -345,6 +345,11 @@ export interface ConsoleState {
   }>;
   /** Whether first operator exists (wizard permanently closed). */
   get setupClosed(): boolean;
+  /**
+   * Persist an operator after claim/create (SQLite under `.oke/`).
+   * No-op when persistence is disabled (tests / memory-only).
+   */
+  persistOperator: (operatorId: string) => void;
   /**
    * Per-email login attempt timestamps for credential-check rate limiting
    * (console §10.4 — same 5/60s strategy as setup-claim).
@@ -398,6 +403,10 @@ export interface CreateConsoleStateOptions {
   readonly okeConfig?: OkeConfig | null;
   /** Host plugin registry for scopes / capabilities. */
   readonly pluginRegistry?: PluginRegistry | null;
+  /** Pre-hydrated operator store (from `.oke/console.sqlite`). */
+  readonly operators?: OperatorStore;
+  /** Persist hook after claim/create. */
+  readonly persistOperator?: (operatorId: string) => void;
 }
 
 /**
@@ -413,10 +422,12 @@ export function createConsoleState(
     process.env.OKE_CONSOLE_SECRET ??
     `oke-console-dev-${crypto.randomUUID()}`;
   const now = options.now ?? (() => Date.now());
+  const operators = options.operators ?? createOperatorStore();
   const claim = mintClaimCode(now);
-  const operators = createOperatorStore();
   const sessions = createSessionStore();
   const liveSubscribers = new Set<(msg: ConsoleLiveMessage) => void>();
+  const persistOperator =
+    options.persistOperator ?? ((_operatorId: string) => {});
 
   const signalConfig = createMemorySignalConfigStore();
   const gateAuth = createDefaultGateAuthStores();
@@ -843,6 +854,7 @@ export function createConsoleState(
     get setupClosed() {
       return operators.operators.size > 0;
     },
+    persistOperator,
   };
 
   return state;