okengine 0.18.5 → 0.19.1

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,83 @@ 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`  
+**Hardware:** Apple M4, 24 GB · trend-analysis only (not SLA; macOS ≠ Linux prod)
+
+Synthetic 32-dim embeddings (deterministic hash bag — not a production model). Modes: text-only (BM25/GIN), vector-only (LSH + cosine), hybrid (RRF k=60). Recall = precision@10 of the LSH/hybrid path vs **exact brute-force cosine** on the same in-memory vectors.
+
+### Before — v0.19.0 (2026-09-10)
+
+**Postgres:** 16.15 · **Artifact:** `g17-hybrid-search-1789039639500.json`  
+Query path: K=64 bucket equality plus Hamming-1 (`= ANY(65 buckets)`), oversample ≤50.
+
+#### 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            |
+
+**Root cause (not an LSH-vs-HNSW tradeoff):** write-time and query-time buckets were byte-identical; `neighborBuckets` did emit 65 probes; `= ANY(?::bigint[])` matched stored rows. Hamming-1 at K=64 cannot see true neighbors. On this generator, same-topic docs sit at cosine ≈0.96 / Hamming ~5; a topic-string query vs those docs is cosine ≈0.82 / expected Hamming ~12. P(Hamming ≤ 1) at K=64 is ~10⁻⁵. A 40-row hand case recovered **0/10** exact neighbors via Hamming-1 and **10/10** via Hamming-rank + cosine. The hash-bag embedding is clustered (8 topics, near-duplicate bodies) — that makes exact top-10 at large N a lottery among the cluster, but it does **not** explain the zero collapse at N=40.
+
+The 2026-09-10 EXPLAIN (Seq Scan, `tsv @@ q OR lsh = ANY(…)`) was a separate planner finding on that query shape.
+
+### After — Hamming-rank candidate path (2026-09-11)
+
+**Date:** 2026-09-11 · **Engine:** Bun 1.4.2 · **Postgres:** 16 (dedicated live instance, not PGlite)  
+**Artifact:** `g17-hybrid-search-1789135622349.json`  
+Fix: UNION of GIN lexical `LIMIT` and SimHash k-NN (`ORDER BY bit_count((lsh # query)::bit(64)) LIMIT oversample`). Same K=64, same oversample formula `max(limit×5, 50)` capped at 500. Not a K/oversample paper-over.
+
+#### Latency (p50 / p99 ms)
+
+| N    | text p50 | text p99 | vector p50 | vector p99 | hybrid p50 | hybrid p99 |
+| ---- | -------- | -------- | ---------- | ---------- | ---------- | ---------- |
+| 1k   | 0.88     | 2.8      | 1.27       | 2.37       | 1.28       | 1.54       |
+| 10k  | 4.5      | 17.21    | 9.36       | 29.03      | 6.88       | 32.48      |
+| 100k | 21.03    | 27.61    | 30.61      | 49.8       | 34.08      | 89.99      |
+| 1M   | 305.61   | 377.7    | 388.98     | 548.36     | 391.96     | 469.76     |
+
+#### Recall — LSH approx vs exact cosine (precision@10)
+
+| N    | vector P@10 | hybrid P@10 | exact cosine p50 (ms) | approx p50 (ms) |
+| ---- | ----------- | ----------- | --------------------- | --------------- |
+| 1k   | 0.167       | 0.117       | 0.6 / 0.41            | 1.25 / 1.3      |
+| 10k  | 0.100       | 0.017       | ~6                    | ~9              |
+| 100k | 0.017       | 0.008       | ~45                   | ~32             |
+| 1M   | 0.017       | 0.000       | ~535                  | ~363            |
+
+**Honest verdict after the fix:** the near-total collapse at 10k/100k is gone on the vector path (smooth 0.17 → 0.10 → 0.017). Remaining low precision@10 vs exact cosine is the real K=64 SimHash + 50-candidate oversample tradeoff on this near-duplicate hash-bag corpus — not a hashing mismatch. Still **not** a drop-in for HNSW/pgvector. Prefer BM25-only or an external `store.index` (`pgvector` / Meilisearch) when semantic recall matters.
+
+### EXPLAIN (ANALYZE, BUFFERS) at N=100k (after)
+
+UNION Append (~14.7 ms): **Bitmap Index Scan** on the GIN tsvector (50 lexical rows) plus **Parallel Seq Scan** + top-N heapsort on `bit_count((lsh # query)::bit(64))` (50 SimHash-nearest). Hamming-rank cannot use the LSH B-tree (equality index). 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                             | Before (2026-09-10) | After (2026-09-11) |
+| ---------------------------------- | ------------------- | ------------------ |
+| Kill after embeds                  | 2,000               | 2,000              |
+| Embeds at kill                     | 2,000               | 2,000              |
+| Kill wall                          | 726 ms              | 732 ms             |
+| Resume wall (re-run to completion) | 29.3 s              | 28.3 s             |
+| Final embedded rows                | 50,000              | 50,000             |
+
+Re-running `oke db search-backfill` after interrupt completed idempotently (safe re-entry; DF/stats rebuilt).
+
+**Issues recorded in after artifact:** eight low-recall notes (P@10 still < 0.3 at every size — honest SimHash-vs-exact remainder, not the Hamming-1 zero collapse).

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,