okengine 0.8.0 → 0.9.0

package/src/auth/otp-seal.ts

@@ -0,0 +1,84 @@
+/**
+ * Domain-separated sealed OTP copy for Tier-2 redelivery.
+ *
+ * AES-GCM key is **never** the raw auth secret. It is derived via
+ * HKDF-SHA-256 with info `oke-otp-seal-v1` so session HMAC material stays
+ * cryptographically isolated from seal encryption.
+ */
+
+/** HKDF `info` — versioned; bump when the seal format changes. */
+export const OTP_SEAL_HKDF_INFO = "oke-otp-seal-v1";
+
+const INFO_BYTES = new TextEncoder().encode(OTP_SEAL_HKDF_INFO);
+const EMPTY_SALT = new Uint8Array(0);
+
+/**
+ * Derive the AES-256-GCM key for OTP sealing from the method secret.
+ *
+ * @param secret - Root auth secret (`resolveMethodSecret`)
+ */
+export async function deriveOtpSealKey(secret: string): Promise<CryptoKey> {
+  const ikm = new TextEncoder().encode(secret);
+  const baseKey = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: EMPTY_SALT,
+      info: INFO_BYTES,
+    },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * Seal a plaintext OTP for later redelivery (base64 `IV || ciphertext+tag`).
+ *
+ * @param secret - Root auth secret
+ * @param otp - Raw OTP digits
+ */
+export async function sealOtp(secret: string, otp: string): Promise<string> {
+  const key = await deriveOtpSealKey(secret);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cipher = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    new TextEncoder().encode(otp),
+  );
+  const packed = new Uint8Array(iv.length + cipher.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(cipher), iv.length);
+  return Buffer.from(packed).toString("base64");
+}
+
+/**
+ * Unseal a previously sealed OTP. Call only at the deliberate delivery boundary.
+ *
+ * @param secret - Root auth secret
+ * @param blob - Base64 sealed blob from {@link sealOtp}
+ */
+export async function unsealOtp(secret: string, blob: string): Promise<string> {
+  const key = await deriveOtpSealKey(secret);
+  const packed = Buffer.from(blob, "base64");
+  if (packed.byteLength < 13) {
+    throw new Error("otp-seal: malformed sealed blob");
+  }
+  const iv = packed.subarray(0, 12);
+  const data = packed.subarray(12);
+  const plain = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: new Uint8Array(iv) },
+    key,
+    toArrayBuffer(data),
+  );
+  return new TextDecoder().decode(plain);
+}
+
+/** Copy into a real ArrayBuffer for Web Crypto BufferSource typing. */
+function toArrayBuffer(view: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(view.byteLength);
+  copy.set(view);
+  return copy.buffer;
+}

package/src/auth/schema.ts

@@ -73,6 +73,8 @@ export const AUTH_MODEL_DEFAULT_FIELDS: Readonly<
     createdAt: "created_at",
     expiresAt: "expires_at",
     lastActiveAt: "last_active_at",
+    scopes: "scopes",
+    audience: "audience",
   },
   refreshToken: {
     id: "id",
@@ -186,6 +188,7 @@ const CORE_SQL_TYPES: Readonly<Record<string, AuthColumnSqlType>> = {
   value: "TEXT",
   description: "TEXT",
   scopes: "TEXT",
+  audience: "TEXT",
   lastUsedAt: "INTEGER",
 };
 

package/src/auth/sessions.ts

@@ -130,11 +130,10 @@ export async function issueSession(
     createdAt: t,
     expiresAt: t + absoluteCap,
     lastActiveAt: t,
+    scopes: [...principal.scopes],
+    ...(crypto.audience !== undefined ? { audience: crypto.audience } : {}),
   };
   store.sessions.set(sessionId, session);
-  if (crypto.audience !== undefined) {
-    sessionAudiences.set(sessionId, crypto.audience);
-  }
 
   const refreshRaw = `rt_${cryptoRandomId()}`;
   const refreshRow: RefreshTokenRow = {
@@ -223,20 +222,15 @@ export async function rotateRefresh(
   };
   store.refresh.set(newRefresh.id, newRefresh);
 
-  // Recover scopes from the previous access path — stored on session via
-  // a side map would be ideal; for builtin we re-sign with empty and let
-  // callers pass scopes through verify. We keep scopes on a claim cache:
-  const priorScopes = sessionScopes.get(session.id) ?? [];
-  const priorAud = sessionAudiences.get(session.id);
   const accessExpiresAt = t + accessTtl;
   const accessToken = await signAccess(crypto.secret, {
     sub: session.principalId,
     plane: session.plane,
     sid: session.id,
-    scopes: priorScopes,
+    scopes: session.scopes,
     iat: t,
     exp: accessExpiresAt,
-    ...(priorAud !== undefined ? { aud: priorAud } : {}),
+    ...(session.audience !== undefined ? { aud: session.audience } : {}),
   });
 
   return {
@@ -247,34 +241,44 @@ export async function rotateRefresh(
   };
 }
 
-/** Session id → scopes (access-token material). */
-const sessionScopes = new Map<string, string[]>();
-
-/** Session id → audience stamped at issue time. */
-const sessionAudiences = new Map<string, string>();
-
 /**
  * Remember scopes for refresh rotation (call after {@link issueSession}).
+ * Scopes live on the session row — shared with any store hydrate/persist path.
  *
+ * @param store - Session store
  * @param sessionId - Session id
  * @param scopes - Scopes
  */
-export function bindSessionScopes(sessionId: string, scopes: Iterable<string>): void {
-  sessionScopes.set(sessionId, [...scopes]);
+export function bindSessionScopes(
+  store: SessionStore,
+  sessionId: string,
+  scopes: Iterable<string>,
+): void {
+  const session = store.sessions.get(sessionId);
+  if (!session) return;
+  // Mutate in place — SessionRow is a store-owned mutable row.
+  (session as { scopes: string[] }).scopes = [...scopes];
 }
 
 /**
  * Remember audience for refresh rotation (call after {@link issueSession}).
  *
+ * @param store - Session store
  * @param sessionId - Session id
  * @param audience - Audience claim
  */
-export function bindSessionAudience(sessionId: string, audience: string): void {
-  sessionAudiences.set(sessionId, audience);
+export function bindSessionAudience(
+  store: SessionStore,
+  sessionId: string,
+  audience: string,
+): void {
+  const session = store.sessions.get(sessionId);
+  if (!session) return;
+  (session as { audience?: string }).audience = audience;
 }
 
 /**
- * Issue a session and bind scopes for later rotation.
+ * Issue a session with scopes (and optional audience) on the session row.
  *
  * @param store - Session store
  * @param crypto - Crypto
@@ -289,12 +293,7 @@ export async function issueSessionWithScopes(
     readonly scopes: Iterable<string>;
   },
 ): Promise<IssuedSession> {
-  const issued = await issueSession(store, crypto, principal);
-  bindSessionScopes(issued.session.id, principal.scopes);
-  if (crypto.audience !== undefined) {
-    bindSessionAudience(issued.session.id, crypto.audience);
-  }
-  return issued;
+  return issueSession(store, crypto, principal);
 }
 
 /**

package/src/auth/tables.ts

@@ -121,6 +121,10 @@ export interface SessionRow {
   expiresAt: number;
   /** Last activity epoch-ms (idle timeout). Updated on refresh / access touch. */
   lastActiveAt: number;
+  /** Access-token scopes — survives refresh / process restart with the session row. */
+  scopes: string[];
+  /** Audience stamped at issue (`oke-console` · `oke-mcp` · `oke-app`). */
+  audience?: string;
 }
 
 /** Refresh token (hashed at rest); rotation with reuse detection. */

package/src/auth/verification.ts

@@ -2,6 +2,9 @@
  * Shared verification / challenge store for magic-link, OTP, phone, etc.
  */
 
+/** Delivery channel for Tier-2 OTP challenges. */
+export type OtpChannel = "sms" | "whatsapp" | "email";
+
 /** One pending challenge. */
 export interface VerificationRow {
   id: string;
@@ -11,6 +14,19 @@ export interface VerificationRow {
   createdAt: number;
   consumedAt: number | null;
   attempts: number;
+  /**
+   * Tier-2 sealed OTP (AES-GCM via HKDF `oke-otp-seal-v1`).
+   * Wiped on consume / expire — never left after TTL.
+   */
+  sealedOtp?: string | null;
+  /** Last successful delivery time (resend cooldown). */
+  lastDeliveredAt?: number;
+  /** Last channel used for delivery. */
+  lastChannel?: OtpChannel;
+  /** Email address captured at request (channel-neutral challenge). */
+  email?: string | null;
+  /** E.164 phone captured at request. */
+  phone?: string | null;
 }
 
 /** In-memory verification store. */
@@ -25,6 +41,15 @@ export function createVerificationStore(): VerificationStore {
   return { rows: new Map() };
 }
 
+/**
+ * Wipe the sealed OTP copy (and clear the field). Safe to call repeatedly.
+ *
+ * @param row - Challenge row
+ */
+export function wipeSealedOtp(row: VerificationRow): void {
+  row.sealedOtp = null;
+}
+
 /**
  * Store a challenge (hashed value recommended by callers).
  *
@@ -37,6 +62,7 @@ export function putVerification(store: VerificationStore, row: VerificationRow):
 
 /**
  * Find a non-consumed, non-expired challenge by identifier.
+ * Expired active rows have their sealed OTP wiped before being skipped.
  *
  * @param store - Store
  * @param identifier - Email / phone / username key
@@ -50,12 +76,46 @@ export function findActiveVerification(
   for (const row of store.rows.values()) {
     if (row.identifier !== identifier) continue;
     if (row.consumedAt !== null) continue;
-    if (row.expiresAt <= now) continue;
+    if (row.expiresAt <= now) {
+      wipeSealedOtp(row);
+      continue;
+    }
     return row;
   }
   return undefined;
 }
 
+/**
+ * Consume a challenge: set `consumedAt`, wipe sealed OTP.
+ *
+ * @param row - Active challenge
+ * @param now - Clock
+ */
+export function consumeVerification(row: VerificationRow, now: number): void {
+  row.consumedAt = now;
+  wipeSealedOtp(row);
+}
+
+/**
+ * Invalidate every non-consumed challenge for an identifier (fresh request).
+ * Wipes sealed copies on the invalidated rows.
+ *
+ * @param store - Store
+ * @param identifier - Challenge key
+ * @param now - Clock
+ */
+export function invalidateVerifications(
+  store: VerificationStore,
+  identifier: string,
+  now: number,
+): void {
+  for (const row of store.rows.values()) {
+    if (row.identifier === identifier && row.consumedAt === null) {
+      consumeVerification(row, now);
+    }
+  }
+}
+
 /**
  * SHA-256 hex hash for challenge secrets / OTPs.
  *

package/src/cli/dev-app-runner.ts

@@ -17,6 +17,7 @@
 
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { installGracefulShutdown, type GracefulShutdownApp } from "../kernel/graceful-shutdown.ts";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
 import { clearTerminalScreen, formatAppReadyLine, formatDevHero } from "../term.ts";
@@ -33,6 +34,8 @@ type DevRunnerGlobals = typeof globalThis & {
 /** App entry shape — FetchApp plus boot before serve. */
 type BootableApp = FetchApp & {
   boot(): Promise<unknown>;
+  stop(): Promise<void>;
+  readonly bootResult?: GracefulShutdownApp["bootResult"];
 };
 
 const entry = Bun.env["OKE_ENTRY"];
@@ -68,6 +71,7 @@ const handle = createBunRuntime().serve(mod.app, {
   hostname,
   id: DEV_APP_SERVE_ID,
 });
+installGracefulShutdown({ app: mod.app, handle });
 
 const appUrl = `http://${formatHostForUrl(hostname)}:${handle.port}`;
 const g = globalThis as DevRunnerGlobals;

package/src/cli/docker.ts

@@ -105,7 +105,10 @@ export async function runDockerDerive(
     write(
       `compose merge order (cwd ${composeDir}/):\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
     );
-    write(`(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n`);
+    write(
+      `(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n` +
+        `(${composeDir}/compose.all.yml is layers 1–3 merged — single-file alternative for Swarm / one \`-c\`)\n`,
+    );
     return { code: 0, result };
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));

package/src/cli/load-config.images.test.ts

@@ -21,6 +21,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
       "store.kv": "redis:8-alpine",
     });
   });
@@ -35,6 +36,7 @@ describe("defaultImagesFromConfig", () => {
       },
     });
     expect(images["store.sql"]).toBe("pgvector/pgvector:pg17");
+    expect(images.pgdog).toBe("ghcr.io/pgdogdev/pgdog:v0.1.51");
   });
 
   test("clock postgres alone pulls store.sql image", () => {
@@ -45,6 +47,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
     });
   });
 
@@ -56,6 +59,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
     });
   });
 

package/src/cli/load-config.ts

@@ -9,6 +9,7 @@ import type { Manifest } from "../manifest/types.ts";
 /** Default image pins when `images` is omitted but prod drivers need containers. */
 const DEFAULT_SQL_IMAGE = "postgres:18-alpine";
 const DEFAULT_PGVECTOR_IMAGE = "pgvector/pgvector:pg17";
+const DEFAULT_PGDOG_IMAGE = "ghcr.io/pgdogdev/pgdog:v0.1.51";
 const DEFAULT_KV_IMAGE = "redis:8-alpine";
 const DEFAULT_VAULT_IMAGE = "openbao/openbao:2.6.1";
 
@@ -64,6 +65,8 @@ export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<stri
   if (needsSql) {
     out["store.sql"] =
       sql === "pgvector" || index === "pgvector" ? DEFAULT_PGVECTOR_IMAGE : DEFAULT_SQL_IMAGE;
+    // PgDog in front of Postgres — caps real server connections under horizontal scale.
+    out.pgdog = DEFAULT_PGDOG_IMAGE;
   }
 
   const needsKv =

package/src/cli/registry.ts

@@ -329,7 +329,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
       {
         long: "--prod",
         short: "-p",
-        summary: "Prod overlays (healthchecks, limits, replicas)",
+        summary: "Prod overlays (app /_/ready healthcheck, deploy, limits)",
       },
       OUT,
       CONFIG,

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

@@ -158,7 +158,9 @@ export function migrateOperatorSchema(db: Database): void {
       revoked_at INTEGER,
       created_at INTEGER NOT NULL,
       expires_at INTEGER NOT NULL,
-      last_active_at INTEGER
+      last_active_at INTEGER,
+      scopes TEXT NOT NULL DEFAULT '[]',
+      audience TEXT
     );
     CREATE TABLE IF NOT EXISTS ${AUTH_TABLES.refreshTokens} (
       id TEXT PRIMARY KEY NOT NULL,
@@ -170,20 +172,28 @@ export function migrateOperatorSchema(db: Database): void {
       revoked_at INTEGER
     );
   `);
-  ensureSessionLastActiveColumn(db);
+  ensureSessionColumns(db);
 }
 
 /**
- * Add `last_active_at` when opening an older console.sqlite that predates idle TTL.
+ * Add session columns when opening an older console.sqlite.
  *
  * @param db - Open database
  */
-function ensureSessionLastActiveColumn(db: Database): void {
+function ensureSessionColumns(db: Database): void {
   const cols = db.query(`PRAGMA table_info(${AUTH_TABLES.sessions})`).all() as Array<{
     name: string;
   }>;
-  if (cols.some((c) => c.name === "last_active_at")) return;
-  db.exec(`ALTER TABLE ${AUTH_TABLES.sessions} ADD COLUMN last_active_at INTEGER`);
+  const names = new Set(cols.map((c) => c.name));
+  if (!names.has("last_active_at")) {
+    db.exec(`ALTER TABLE ${AUTH_TABLES.sessions} ADD COLUMN last_active_at INTEGER`);
+  }
+  if (!names.has("scopes")) {
+    db.exec(`ALTER TABLE ${AUTH_TABLES.sessions} ADD COLUMN scopes TEXT NOT NULL DEFAULT '[]'`);
+  }
+  if (!names.has("audience")) {
+    db.exec(`ALTER TABLE ${AUTH_TABLES.sessions} ADD COLUMN audience TEXT`);
+  }
 }
 
 /**
@@ -196,7 +206,7 @@ export function loadSessionStore(db: Database): SessionStore {
 
   const sessionRows = db
     .query(
-      `SELECT id, plane, principal_id, family_id, revoked_at, created_at, expires_at, last_active_at
+      `SELECT id, plane, principal_id, family_id, revoked_at, created_at, expires_at, last_active_at, scopes, audience
        FROM ${AUTH_TABLES.sessions}`,
     )
     .all() as Array<{
@@ -208,9 +218,20 @@ export function loadSessionStore(db: Database): SessionStore {
     created_at: number;
     expires_at: number;
     last_active_at: number | null;
+    scopes: string | null;
+    audience: string | null;
   }>;
 
   for (const row of sessionRows) {
+    let scopes: string[] = [];
+    if (row.scopes) {
+      try {
+        const parsed = JSON.parse(row.scopes) as unknown;
+        if (Array.isArray(parsed)) scopes = parsed.map(String);
+      } catch {
+        scopes = [];
+      }
+    }
     const session: SessionRow = {
       id: row.id,
       plane: row.plane,
@@ -220,6 +241,8 @@ export function loadSessionStore(db: Database): SessionStore {
       createdAt: row.created_at,
       expiresAt: row.expires_at,
       lastActiveAt: row.last_active_at ?? row.created_at,
+      scopes,
+      ...(row.audience ? { audience: row.audience } : {}),
     };
     store.sessions.set(session.id, session);
   }
@@ -267,8 +290,8 @@ export function persistSessions(db: Database, store: SessionStore): void {
 
   const insertSession = db.query(
     `INSERT INTO ${AUTH_TABLES.sessions}
-      (id, plane, principal_id, family_id, revoked_at, created_at, expires_at, last_active_at)
-     VALUES ($id, $plane, $principal, $family, $revoked, $created, $expires, $lastActive)`,
+      (id, plane, principal_id, family_id, revoked_at, created_at, expires_at, last_active_at, scopes, audience)
+     VALUES ($id, $plane, $principal, $family, $revoked, $created, $expires, $lastActive, $scopes, $audience)`,
   );
   for (const session of store.sessions.values()) {
     insertSession.run({
@@ -280,6 +303,8 @@ export function persistSessions(db: Database, store: SessionStore): void {
       $created: session.createdAt,
       $expires: session.expiresAt,
       $lastActive: session.lastActiveAt,
+      $scopes: JSON.stringify(session.scopes ?? []),
+      $audience: session.audience ?? null,
     });
   }