okengine 0.18.4 → 0.19.0

package/src/auth/sessions.ts

@@ -407,17 +407,23 @@ export class SessionError extends Error {
   }
 }
 
+/** Compact JWS algorithm for session access tokens (HMAC-SHA256). */
+const ACCESS_TOKEN_ALG = "HS256" as const;
+
 async function hashToken(raw: string): Promise<string> {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(raw));
   return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
 function cryptoRandomId(): string {
-  return crypto.randomUUID().replace(/-/g, "");
+  // Refresh / opaque session secrets — not application ids (those use OKID).
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
 async function signAccess(secret: string, claims: AccessClaims): Promise<string> {
-  const header = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const header = b64url(JSON.stringify({ alg: ACCESS_TOKEN_ALG, typ: "JWT" }));
   const payload = b64url(JSON.stringify(claims));
   const data = `${header}.${payload}`;
   const sig = await hmac(secret, data);
@@ -426,9 +432,19 @@ async function signAccess(secret: string, claims: AccessClaims): Promise<string>
 
 async function verifyAccessSignature(secret: string, token: string): Promise<AccessClaims> {
   const parts = token.split(".");
+  // JWS compact = 3 parts; JWE compact = 5 — reject anything else before crypto.
   if (parts.length !== 3) throw new SessionError("malformed access token");
-  const [header, payload, sig] = parts as [string, string, string];
-  const data = `${header}.${payload}`;
+  const [headerPart, payload, sig] = parts as [string, string, string];
+  let header: { alg?: string };
+  try {
+    header = JSON.parse(b64urlDecode(headerPart)) as { alg?: string };
+  } catch {
+    throw new SessionError("malformed access token header");
+  }
+  if (header.alg !== ACCESS_TOKEN_ALG) {
+    throw new SessionError("unsupported access token alg");
+  }
+  const data = `${headerPart}.${payload}`;
   const expected = await hmac(secret, data);
   if (sig !== expected) throw new SessionError("invalid access token signature");
   return JSON.parse(b64urlDecode(payload)) as AccessClaims;

package/src/auth/tenants.ts

@@ -7,6 +7,7 @@
 
 import { isApplicationScope } from "../elements/gate/permissions.ts";
 import type { TenantMemberRow, TenantRoleRow, TenantRow } from "./tables.ts";
+import { okid } from "../okid.ts";
 
 export type { TenantMemberRow, TenantRoleRow, TenantRow };
 
@@ -99,7 +100,7 @@ export async function createTenant(
 ): Promise<TenantRow> {
   const now = options.now ?? (() => Date.now());
   const t = now();
-  const id = options.id ?? crypto.randomUUID();
+  const id = options.id ?? okid();
   if (store.tenants.has(id)) {
     throw new TenantError("tenant_exists", `tenant already exists: ${id}`);
   }
@@ -180,7 +181,7 @@ export function addMember(store: TenantStore, options: AddMemberOptions): Tenant
   }
   const now = options.now ?? (() => Date.now());
   const row: TenantMemberRow = {
-    id: options.id ?? crypto.randomUUID(),
+    id: options.id ?? okid(),
     tenantId: options.tenantId,
     userId: options.userId,
     role: options.role ?? DEFAULT_TENANT_ROLE,

package/src/auth/two-factor-challenge.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Pending 2FA challenge + step-up grant store.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  consumeChallenge,
+  consumeStepUp,
+  createPendingTwoFactorStore,
+  createStepUpStore,
+  findActiveForUser,
+  getChallenge,
+  grantStepUp,
+  hasActiveChallenge,
+  issueChallenge,
+  twoFactorEmailOtpIdentifier,
+} from "./two-factor-challenge.ts";
+
+describe("pending two-factor challenge store", () => {
+  test("issue locks method and replaces prior active challenge", () => {
+    const store = createPendingTwoFactorStore();
+    const first = issueChallenge(store, {
+      userId: "u1",
+      method: "email_otp",
+      now: 1_000,
+      ttlMs: 60_000,
+    });
+    expect(first.method).toBe("email_otp");
+    expect(hasActiveChallenge(store, "u1", 1_000)).toBe(true);
+
+    const second = issueChallenge(store, {
+      userId: "u1",
+      method: "totp",
+      now: 2_000,
+      ttlMs: 60_000,
+    });
+    expect(second.id).not.toBe(first.id);
+    expect(getChallenge(store, first.id, 2_000)).toBeUndefined();
+    expect(findActiveForUser(store, "u1", 2_000)?.method).toBe("totp");
+  });
+
+  test("consume clears active pointer", () => {
+    const store = createPendingTwoFactorStore();
+    const row = issueChallenge(store, { userId: "u1", method: "totp", now: 1_000 });
+    consumeChallenge(store, row, 1_500);
+    expect(hasActiveChallenge(store, "u1", 1_500)).toBe(false);
+    expect(getChallenge(store, row.id, 1_500)).toBeUndefined();
+  });
+
+  test("step-up grant is single-use and purpose-scoped", () => {
+    const stepUp = createStepUpStore();
+    grantStepUp(stepUp, "u1", "change", 1_000, 60_000);
+    expect(consumeStepUp(stepUp, "u1", "enroll", 1_100)).toBe(false);
+    expect(consumeStepUp(stepUp, "u1", ["change", "enroll"], 1_100)).toBe(true);
+    expect(consumeStepUp(stepUp, "u1", "change", 1_200)).toBe(false);
+  });
+
+  test("twoFactorEmailOtpIdentifier namespaces by user", () => {
+    expect(twoFactorEmailOtpIdentifier("abc")).toBe("2fa:abc");
+  });
+});

package/src/auth/two-factor-challenge.ts

@@ -0,0 +1,284 @@
+import { okid } from "../okid.ts";
+/**
+ * Pending login 2FA challenges + short-lived step-up grants.
+ *
+ * One active unresolved challenge per user; method is locked at issue time
+ * so enrollment / method-switch cannot bypass the configured factor.
+ */
+
+/** Locked second-factor method for a login challenge. */
+export type TwoFactorMethod = "totp" | "email_otp";
+
+/** Default login-challenge TTL (align with OTP). */
+export const DEFAULT_TWO_FACTOR_CHALLENGE_TTL_MS = 10 * 60 * 1000;
+
+/** Default step-up grant TTL for privileged 2FA ops. */
+export const DEFAULT_STEP_UP_TTL_MS = 5 * 60 * 1000;
+
+/** One pending login 2FA challenge. */
+export interface PendingTwoFactorChallenge {
+  id: string;
+  userId: string;
+  method: TwoFactorMethod;
+  createdAt: number;
+  expiresAt: number;
+  consumedAt: number | null;
+}
+
+/** In-memory pending 2FA challenge store. */
+export interface PendingTwoFactorStore {
+  readonly byId: Map<string, PendingTwoFactorChallenge>;
+  /** userId → active challenge id (at most one). */
+  readonly byUserId: Map<string, string>;
+}
+
+/**
+ * Create an empty pending 2FA challenge store.
+ */
+export function createPendingTwoFactorStore(): PendingTwoFactorStore {
+  return { byId: new Map(), byUserId: new Map() };
+}
+
+/** Options for {@link issueChallenge}. */
+export interface IssueChallengeOptions {
+  readonly userId: string;
+  readonly method: TwoFactorMethod;
+  readonly now?: number;
+  readonly ttlMs?: number;
+}
+
+/**
+ * Invalidate any prior active challenge for the user and issue a new locked one.
+ *
+ * @param store - Pending store
+ * @param options - User, method, clock
+ */
+export function issueChallenge(
+  store: PendingTwoFactorStore,
+  options: IssueChallengeOptions,
+): PendingTwoFactorChallenge {
+  const now = options.now ?? Date.now();
+  const ttlMs = options.ttlMs ?? DEFAULT_TWO_FACTOR_CHALLENGE_TTL_MS;
+  invalidateActiveForUser(store, options.userId, now);
+  const row: PendingTwoFactorChallenge = {
+    id: okid(),
+    userId: options.userId,
+    method: options.method,
+    createdAt: now,
+    expiresAt: now + ttlMs,
+    consumedAt: null,
+  };
+  store.byId.set(row.id, row);
+  store.byUserId.set(options.userId, row.id);
+  return row;
+}
+
+/**
+ * Find a non-consumed, non-expired challenge by id.
+ *
+ * @param store - Pending store
+ * @param challengeId - Challenge id
+ * @param now - Clock
+ */
+export function getChallenge(
+  store: PendingTwoFactorStore,
+  challengeId: string,
+  now: number = Date.now(),
+): PendingTwoFactorChallenge | undefined {
+  const row = store.byId.get(challengeId);
+  if (!row) return undefined;
+  if (row.consumedAt !== null) return undefined;
+  if (row.expiresAt <= now) {
+    clearUserPointer(store, row);
+    return undefined;
+  }
+  return row;
+}
+
+/**
+ * Find the active unresolved challenge for a user, if any.
+ *
+ * @param store - Pending store
+ * @param userId - User id
+ * @param now - Clock
+ */
+export function findActiveForUser(
+  store: PendingTwoFactorStore,
+  userId: string,
+  now: number = Date.now(),
+): PendingTwoFactorChallenge | undefined {
+  const id = store.byUserId.get(userId);
+  if (!id) return undefined;
+  const row = getChallenge(store, id, now);
+  if (!row) {
+    store.byUserId.delete(userId);
+    return undefined;
+  }
+  return row;
+}
+
+/**
+ * True when the user has an active unresolved login 2FA challenge.
+ *
+ * @param store - Pending store
+ * @param userId - User id
+ * @param now - Clock
+ */
+export function hasActiveChallenge(
+  store: PendingTwoFactorStore,
+  userId: string,
+  now: number = Date.now(),
+): boolean {
+  return findActiveForUser(store, userId, now) !== undefined;
+}
+
+/**
+ * Consume a challenge after successful verification.
+ *
+ * @param store - Pending store
+ * @param row - Active challenge
+ * @param now - Clock
+ */
+export function consumeChallenge(
+  store: PendingTwoFactorStore,
+  row: PendingTwoFactorChallenge,
+  now: number = Date.now(),
+): void {
+  row.consumedAt = now;
+  clearUserPointer(store, row);
+}
+
+/**
+ * Invalidate the active challenge for a user (fresh sign-in / abort).
+ *
+ * @param store - Pending store
+ * @param userId - User id
+ * @param now - Clock
+ */
+export function invalidateActiveForUser(
+  store: PendingTwoFactorStore,
+  userId: string,
+  now: number = Date.now(),
+): void {
+  const id = store.byUserId.get(userId);
+  if (!id) return;
+  const row = store.byId.get(id);
+  if (row && row.consumedAt === null) {
+    row.consumedAt = now;
+  }
+  store.byUserId.delete(userId);
+}
+
+function clearUserPointer(store: PendingTwoFactorStore, row: PendingTwoFactorChallenge): void {
+  if (store.byUserId.get(row.userId) === row.id) {
+    store.byUserId.delete(row.userId);
+  }
+}
+
+/** Privileged step-up grant after verifying the current 2FA method. */
+export interface StepUpGrant {
+  userId: string;
+  expiresAt: number;
+  purpose: "enroll" | "change" | "disable";
+}
+
+/** In-memory step-up grant store. */
+export interface StepUpStore {
+  readonly byUserId: Map<string, StepUpGrant>;
+}
+
+/**
+ * Create an empty step-up grant store.
+ */
+export function createStepUpStore(): StepUpStore {
+  return { byUserId: new Map() };
+}
+
+/**
+ * Record a short-lived step-up grant for privileged 2FA operations.
+ *
+ * @param store - Step-up store
+ * @param userId - User id
+ * @param purpose - Intended privileged op
+ * @param now - Clock
+ * @param ttlMs - Grant TTL
+ */
+export function grantStepUp(
+  store: StepUpStore,
+  userId: string,
+  purpose: StepUpGrant["purpose"],
+  now: number = Date.now(),
+  ttlMs: number = DEFAULT_STEP_UP_TTL_MS,
+): StepUpGrant {
+  const grant: StepUpGrant = { userId, purpose, expiresAt: now + ttlMs };
+  store.byUserId.set(userId, grant);
+  return grant;
+}
+
+/**
+ * Consume a valid step-up grant (single-use). Returns false if missing/expired/wrong purpose.
+ *
+ * @param store - Step-up store
+ * @param userId - User id
+ * @param purpose - Required purpose (or any of the listed)
+ * @param now - Clock
+ */
+export function consumeStepUp(
+  store: StepUpStore,
+  userId: string,
+  purpose: StepUpGrant["purpose"] | readonly StepUpGrant["purpose"][],
+  now: number = Date.now(),
+): boolean {
+  const grant = store.byUserId.get(userId);
+  if (!grant) return false;
+  if (grant.expiresAt <= now) {
+    store.byUserId.delete(userId);
+    return false;
+  }
+  const allowed = typeof purpose === "string" ? [purpose] : purpose;
+  if (!allowed.includes(grant.purpose)) return false;
+  store.byUserId.delete(userId);
+  return true;
+}
+
+/**
+ * Peek whether a valid step-up grant exists (does not consume).
+ *
+ * @param store - Step-up store
+ * @param userId - User id
+ * @param purpose - Required purpose
+ * @param now - Clock
+ */
+export function hasStepUp(
+  store: StepUpStore,
+  userId: string,
+  purpose: StepUpGrant["purpose"] | readonly StepUpGrant["purpose"][],
+  now: number = Date.now(),
+): boolean {
+  const grant = store.byUserId.get(userId);
+  if (!grant) return false;
+  if (grant.expiresAt <= now) {
+    store.byUserId.delete(userId);
+    return false;
+  }
+  const allowed = typeof purpose === "string" ? [purpose] : purpose;
+  return allowed.includes(grant.purpose);
+}
+
+/** Sign-in response when 2FA must complete before session issue. */
+export interface TwoFactorRequiredOut {
+  readonly twoFactorRequired: true;
+  readonly challengeId: string;
+  readonly method: TwoFactorMethod;
+  readonly userId: string;
+  readonly devOtp?: string;
+}
+
+/**
+ * Verification-store identifier for email OTP used as a second factor.
+ *
+ * @param userId - User id
+ */
+export function twoFactorEmailOtpIdentifier(userId: string): string {
+  return `2fa:${userId}`;
+}

package/src/auth/verification.ts

@@ -27,6 +27,11 @@ export interface VerificationRow {
   email?: string | null;
   /** E.164 phone captured at request. */
   phone?: string | null;
+  /**
+   * Ceremony session id (passkey WebAuthn) — challenge is bound to this id.
+   * Other auth methods leave it unset.
+   */
+  sessionId?: string | null;
 }
 
 /** In-memory verification store. */

package/src/bench/REPORT.md

@@ -174,3 +174,52 @@ Artifact: `G15-postgres-degradation-…json` (+ extra stress-level artifacts)
 2. G3b wave-2 steady-state sat below the ~500-subscriber target; fd-per-subscriber trend unaffected.
 3. Channel bulk throughput now bounded by per-transport serialization (correctness over throughput); revisit if fan-out email volume matters.
 4. G15 is in-process backpressure only (see honesty note).
+
+---
+
+## G17 — Hybrid SQL search (BM25 / LSH / fusion)
+
+**Command:** `OKE_BENCH=1 OKE_TEST_POSTGRES=1 DATABASE_URL=$DATABASE_URL bun test ./src/bench/g17-hybrid-search.bench.ts --timeout 3600000`  
+**Date:** 2026-09-10 · **Engine:** Bun 1.4.2 · **Postgres:** 16.15 (dedicated live instance, not PGlite)  
+**Hardware:** Apple M4, 24 GB · trend-analysis only (not SLA; macOS ≠ Linux prod)  
+**Artifact:** `g17-hybrid-search-1789039639500.json`
+
+Synthetic 32-dim embeddings (deterministic hash bag — not a production model). Modes: text-only (BM25/GIN), vector-only (LSH buckets + cosine), hybrid (RRF k=60). Recall = precision@10 of the LSH/hybrid path vs **exact brute-force cosine** on the same in-memory vectors.
+
+### Latency (p50 / p99 ms)
+
+| N    | text p50 | text p99 | vector p50 | vector p99 | hybrid p50 | hybrid p99 |
+| ---- | -------- | -------- | ---------- | ---------- | ---------- | ---------- |
+| 1k   | 1.32     | 3.6      | 1.35       | 2.19       | 1.43       | 2.04       |
+| 10k  | 2.77     | 3.85     | 3.74       | 4.38       | 2.99       | 5.97       |
+| 100k | 39.86    | 59.73    | 57.05      | 126.14     | 52.08      | 288.09     |
+| 1M   | 877.57   | 2243.68  | 1165.5     | 3370.19    | 649.14     | 1861.91    |
+
+### Recall — LSH approx vs exact cosine (precision@10)
+
+| N    | vector P@10 | hybrid P@10 | exact cosine p50 (ms) | approx p50 (ms) |
+| ---- | ----------- | ----------- | --------------------- | --------------- |
+| 1k   | **0.000**   | 0.067       | 0.16                  | 1.41 / 1.6      |
+| 10k  | **0.000**   | **0.000**   | ~1.6                  | ~3.5            |
+| 100k | **0.000**   | **0.000**   | ~36                   | ~54             |
+| 1M   | 0.008       | **0.000**   | ~445                  | ~600            |
+
+**Honest verdict:** on this corpus the random-hyperplane LSH path (K=64, Hamming-1 neighbors, candidate oversample ≤50) does **not** recover the exact cosine top-10. Treat built-in LSH as a cheap candidate generator for hybrid fusion — **not** a drop-in for HNSW/pgvector recall. Prefer BM25-only or an external `store.index` (`pgvector` / Meilisearch) when semantic recall matters.
+
+### EXPLAIN (ANALYZE, BUFFERS) at N=100k
+
+Postgres 16 chose a **Seq Scan** with a Filter on `__oke_tsv @@ plainto_tsquery(…) OR __oke_lsh_body = ANY(…)` (Limit 50; execution ~0.27 ms; shared hit=27). GIN + LSH B-tree indexes exist; the planner did **not** emit BitmapOr on this hardware/stats for the measured query. Do not claim BitmapOr from design alone — re-check `EXPLAIN` on production data volumes and `ANALYZE`d tables.
+
+### Backfill kill / resume (50k pre-populated rows)
+
+| Metric                             | Value  |
+| ---------------------------------- | ------ |
+| Kill after embeds                  | 2,000  |
+| Embeds at kill                     | 2,000  |
+| Kill wall                          | 726 ms |
+| Resume wall (re-run to completion) | 29.3 s |
+| Final embedded rows                | 50,000 |
+
+Re-running `oke db search-backfill` after interrupt completed idempotently (safe re-entry; DF/stats rebuilt).
+
+**Issues recorded in artifact:** eight low-recall notes (all sizes). No product fix applied mid-bench — numbers stand as measured.

package/src/bench/g03-signal-once.bench.ts

@@ -33,7 +33,7 @@ let bus: SignalBus;
 beforeAll(async () => {
   if (!LIVE_PG) throw new Error("G3 needs live Postgres: set OKE_TEST_POSTGRES=1 + DATABASE_URL");
   sql = createBunSignalSql(LIVE_PG);
-  const decl = signal(SIGNAL_NAME, { delivery: "once", retries: 2, deadLetter: true });
+  const decl = signal.once(SIGNAL_NAME, { retries: 2, deadLetter: true });
   bus = await openPostgresSignal({
     signals: new Map([[decl.name, decl]]),
     sql,

package/src/bench/g10-observability-contention.bench.ts

@@ -137,7 +137,7 @@ async function runArm(
     const obsLats: number[] = [];
     let obsQueries = 0;
     if (observers && sql) {
-      const decl = signal("g10-watch", { delivery: "once", optional: true });
+      const decl = signal.once("g10-watch", { optional: true });
       const consoleBus: SignalBus = await openPostgresSignal({
         signals: new Map([[decl.name, decl]]),
         sql,