okengine 0.4.3 → 0.5.0

package/src/auth/secondary-storage.ts

@@ -0,0 +1,37 @@
+/**
+ * Optional secondary storage for hot auth data (Phase 1a) — `store.kv`.
+ */
+
+import type { ResolvedGateAuth } from "./config.ts";
+
+/** Minimal kv surface used by auth secondary storage. */
+export interface AuthKv {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown, opts?: { readonly ttlMs?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Create a namespaced kv helper for session / challenge hot paths.
+ *
+ * @param kv - Kv handle
+ * @param config - Resolved auth
+ */
+export function createAuthSecondaryStorage(
+  kv: AuthKv,
+  config: ResolvedGateAuth,
+): AuthKv | undefined {
+  if (!config.secondaryStorage.enabled) return undefined;
+  const prefix = config.secondaryStorage.prefix;
+  return {
+    async get(key) {
+      return kv.get(`${prefix}${key}`);
+    },
+    async set(key, value, opts) {
+      await kv.set(`${prefix}${key}`, value, opts);
+    },
+    async delete(key) {
+      await kv.delete(`${prefix}${key}`);
+    },
+  };
+}

package/src/auth/sessions.ts

@@ -52,6 +52,21 @@ export interface SessionCrypto {
   readonly now?: () => number;
   readonly accessTtlMs?: number;
   readonly refreshTtlMs?: number;
+  /**
+   * Idle timeout — reject refresh when `now - lastActiveAt > idleTtlMs`.
+   * Opt-in (undefined = disabled).
+   */
+  readonly idleTtlMs?: number;
+  /**
+   * Absolute lifetime from `session.createdAt` (hard stop even if refresh would extend).
+   * Opt-in; when set should be ≤ refreshTtlMs.
+   */
+  readonly absoluteTtlMs?: number;
+  /**
+   * When true, issuing a session revokes other active families for the same principal.
+   * Opt-in (default false).
+   */
+  readonly singleSessionPerUser?: boolean;
   /**
    * Audience stamped on issued access tokens.
    * MCP tokens must use `"oke-mcp"` (console §10.3 — never accept another aud).
@@ -97,9 +112,15 @@ export async function issueSession(
   const t = now();
   const accessTtl = crypto.accessTtlMs ?? ACCESS_TTL_MS;
   const refreshTtl = crypto.refreshTtlMs ?? REFRESH_TTL_MS;
+  const absoluteCap =
+    crypto.absoluteTtlMs !== undefined ? Math.min(refreshTtl, crypto.absoluteTtlMs) : refreshTtl;
   const sessionId = cryptoRandomId();
   const familyId = cryptoRandomId();
 
+  if (crypto.singleSessionPerUser) {
+    revokePrincipalSessions(store, principal.plane, principal.id, t);
+  }
+
   const session: SessionRow = {
     id: sessionId,
     plane: principal.plane,
@@ -107,7 +128,8 @@ export async function issueSession(
     familyId,
     revokedAt: null,
     createdAt: t,
-    expiresAt: t + refreshTtl,
+    expiresAt: t + absoluteCap,
+    lastActiveAt: t,
   };
   store.sessions.set(sessionId, session);
   if (crypto.audience !== undefined) {
@@ -174,9 +196,17 @@ export async function rotateRefresh(
   if (existing.expiresAt <= t || session.expiresAt <= t) {
     throw new SessionError("refresh token expired");
   }
+  if (crypto.absoluteTtlMs !== undefined && session.createdAt + crypto.absoluteTtlMs <= t) {
+    throw new SessionError("session absolute lifetime exceeded");
+  }
+  const lastActive = session.lastActiveAt ?? session.createdAt;
+  if (crypto.idleTtlMs !== undefined && lastActive + crypto.idleTtlMs <= t) {
+    throw new SessionError("session idle timeout exceeded");
+  }
 
   existing.usedAt = t;
   existing.revokedAt = t;
+  session.lastActiveAt = t;
 
   const accessTtl = crypto.accessTtlMs ?? ACCESS_TTL_MS;
   const refreshTtl = crypto.refreshTtlMs ?? REFRESH_TTL_MS;
@@ -305,6 +335,8 @@ export async function verifyAccess(
   if (session.principalId !== claims.sub) {
     throw new SessionError("session does not belong to requester");
   }
+  // Touch idle clock on successful access verify.
+  session.lastActiveAt = now();
   return claims;
 }
 
@@ -324,6 +356,31 @@ export function revokeFamily(store: SessionStore, familyId: string, at: number =
   }
 }
 
+/**
+ * Revoke all active sessions for a principal (single-session-per-user).
+ *
+ * @param store - Session store
+ * @param plane - Auth plane
+ * @param principalId - Subject id
+ * @param at - Timestamp
+ */
+export function revokePrincipalSessions(
+  store: SessionStore,
+  plane: AuthPlane,
+  principalId: string,
+  at: number = Date.now(),
+): void {
+  for (const session of store.sessions.values()) {
+    if (
+      session.plane === plane &&
+      session.principalId === principalId &&
+      session.revokedAt === null
+    ) {
+      revokeFamily(store, session.familyId, at);
+    }
+  }
+}
+
 /** Session / token error. */
 export class SessionError extends Error {
   /** @param message - Diagnostic */

package/src/auth/tables.ts

@@ -23,6 +23,8 @@ export const AUTH_TABLES = {
   // Session tables (auth element owns these)
   sessions: "oke_sessions",
   refreshTokens: "oke_refresh_tokens",
+  // Challenges / OTP / magic-link (Gate auth + method plugins)
+  verifications: "oke_verifications",
 } as const;
 
 /** Plane column values stored on shared tables. */
@@ -117,6 +119,8 @@ export interface SessionRow {
   revokedAt: number | null;
   createdAt: number;
   expiresAt: number;
+  /** Last activity epoch-ms (idle timeout). Updated on refresh / access touch. */
+  lastActiveAt: number;
 }
 
 /** Refresh token (hashed at rest); rotation with reuse detection. */

package/src/auth/verification.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared verification / challenge store for magic-link, OTP, phone, etc.
+ */
+
+/** One pending challenge. */
+export interface VerificationRow {
+  id: string;
+  identifier: string;
+  value: string;
+  expiresAt: number;
+  createdAt: number;
+  consumedAt: number | null;
+  attempts: number;
+}
+
+/** In-memory verification store. */
+export interface VerificationStore {
+  rows: Map<string, VerificationRow>;
+}
+
+/**
+ * Create an empty verification store.
+ */
+export function createVerificationStore(): VerificationStore {
+  return { rows: new Map() };
+}
+
+/**
+ * Store a challenge (hashed value recommended by callers).
+ *
+ * @param store - Store
+ * @param row - Challenge row
+ */
+export function putVerification(store: VerificationStore, row: VerificationRow): void {
+  store.rows.set(row.id, row);
+}
+
+/**
+ * Find a non-consumed, non-expired challenge by identifier.
+ *
+ * @param store - Store
+ * @param identifier - Email / phone / username key
+ * @param now - Clock
+ */
+export function findActiveVerification(
+  store: VerificationStore,
+  identifier: string,
+  now: number,
+): VerificationRow | undefined {
+  for (const row of store.rows.values()) {
+    if (row.identifier !== identifier) continue;
+    if (row.consumedAt !== null) continue;
+    if (row.expiresAt <= now) continue;
+    return row;
+  }
+  return undefined;
+}
+
+/**
+ * SHA-256 hex hash for challenge secrets / OTPs.
+ *
+ * @param raw - Raw secret
+ */
+export async function hashChallenge(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("");
+}
+
+/**
+ * Generate a numeric OTP of `digits` length.
+ *
+ * @param digits - Length (default 6)
+ */
+export function generateOtp(digits = 6): string {
+  const max = 10 ** digits;
+  const n = crypto.getRandomValues(new Uint32Array(1))[0]! % max;
+  return n.toString().padStart(digits, "0");
+}

package/src/cli/dev.test.ts

@@ -396,14 +396,14 @@ describe("oke dev docs MCP", () => {
 async function writePingApp(dir: string, version: string): Promise<void> {
   await Bun.write(
     join(dir, "src/flows/ping.ts"),
-    `import { on, flow, http } from ${JSON.stringify(OKE_INDEX)};
+    `import { on, flow, http, gate } from ${JSON.stringify(OKE_INDEX)};
 
-export const ping = on(http.get("/ping"), flow({
+export const ping = on(http.get("/ping").gate(gate.public), flow({
   name: "ping",
   do: () => ({ version: ${JSON.stringify(version)} as const }),
 }));
 
-export const slow = on(http.get("/slow"), flow({
+export const slow = on(http.get("/slow").gate(gate.public), flow({
   name: "slow",
   do: async () => {
     const started = ${JSON.stringify(version)};

package/src/cli/schema.ts

@@ -1,10 +1,16 @@
 /**
- * `oke schema generate` — core + plugin tables → `schema/oke.ts`.
+ * `oke schema generate` — core + auth + plugin tables → `schema/oke.ts`.
  */
 
 import { createHash } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import {
+  resolveAuthSchema,
+  type AuthSchemaOptions,
+  type ResolvedAuthModel,
+  type ResolvedAuthSchema,
+} from "../auth/schema.ts";
 import type { Manifest } from "../manifest/types.ts";
 import { loadManifest } from "./load-config.ts";
 
@@ -25,10 +31,12 @@ export interface SchemaGenerateOptions {
   readonly write?: (text: string) => void;
   /** Extra table names (plugins / tests). */
   readonly extraTables?: readonly string[];
+  /** Auth schema customization (from `gate.auth` / tests). */
+  readonly authSchema?: AuthSchemaOptions | false;
 }
 
 /**
- * Generate `schema/oke.ts` from Manifest store tables + core Console tables.
+ * Generate `schema/oke.ts` from Manifest store tables + core auth columns.
  *
  * @param options - Manifest / check flag
  */
@@ -42,23 +50,41 @@ export async function runSchemaGenerate(options: SchemaGenerateOptions = {}): Pr
     if (await file.exists()) manifest = await loadManifest(path);
   }
 
+  const authSchema =
+    options.authSchema === false
+      ? undefined
+      : resolveAuthSchema(options.authSchema ?? loadAuthSchemaFromManifest(manifest));
+
   const tables = new Set<string>([
-    "oke_roles",
-    "oke_role_grants",
-    "oke_api_keys",
     "oke_overrides",
     "oke_crons",
     "oke_signal_config",
     "oke_console_prefs",
     ...(options.extraTables ?? []),
   ]);
+  if (authSchema) {
+    for (const name of authSchema.tableNames) tables.add(name);
+  } else {
+    for (const name of [
+      "oke_roles",
+      "oke_role_grants",
+      "oke_api_keys",
+      "oke_identities",
+      "oke_credentials",
+      "oke_sessions",
+      "oke_refresh_tokens",
+      "oke_verifications",
+    ]) {
+      tables.add(name);
+    }
+  }
   if (manifest?.stores) {
     for (const store of Object.values(manifest.stores)) {
       for (const t of Object.keys(store.tables ?? {})) tables.add(t);
     }
   }
 
-  const source = emitSchemaSource([...tables].sort());
+  const source = emitSchemaSource([...tables].sort(), authSchema);
   const out = resolve(cwd, options.out ?? SCHEMA_OUT);
   const fp = hashSource(source);
 
@@ -91,26 +117,25 @@ export async function runSchemaGenerate(options: SchemaGenerateOptions = {}): Pr
  * @param manifest - Optional manifest
  */
 export async function schemaFingerprint(cwd: string, manifest?: Manifest): Promise<string> {
+  let m = manifest;
+  if (!m) {
+    const path = resolve(cwd, "oke.manifest.json");
+    if (await Bun.file(path).exists()) m = await loadManifest(path);
+  }
+  const authSchema = resolveAuthSchema(loadAuthSchemaFromManifest(m));
   const tables = new Set<string>([
-    "oke_roles",
-    "oke_role_grants",
-    "oke_api_keys",
     "oke_overrides",
     "oke_crons",
     "oke_signal_config",
     "oke_console_prefs",
+    ...authSchema.tableNames,
   ]);
-  let m = manifest;
-  if (!m) {
-    const path = resolve(cwd, "oke.manifest.json");
-    if (await Bun.file(path).exists()) m = await loadManifest(path);
-  }
   if (m?.stores) {
     for (const store of Object.values(m.stores)) {
       for (const t of Object.keys(store.tables ?? {})) tables.add(t);
     }
   }
-  return hashSource(emitSchemaSource([...tables].sort()));
+  return hashSource(emitSchemaSource([...tables].sort(), authSchema));
 }
 
 /**
@@ -150,7 +175,7 @@ export async function schemaCli(args: readonly string[]): Promise<number> {
     else if (a === "--help" || a === "-h") {
       console.log(`oke schema generate [--check|-c] [--out|-o schema/oke.ts]
 
-Emit core + plugin tables. Use --check in CI to fail on drift.
+Emit core auth columns + Manifest store tables. Use --check in CI to fail on drift.
 `);
       return 0;
     }
@@ -159,20 +184,33 @@ Emit core + plugin tables. Use --check in CI to fail on drift.
 }
 
 /**
- * Emit a Drizzle-compatible stub schema module.
+ * Emit a schema module with real auth columns when resolved.
  *
  * @param tables - Table names
+ * @param authSchema - Resolved auth schema (optional)
  */
-export function emitSchemaSource(tables: readonly string[]): string {
+export function emitSchemaSource(
+  tables: readonly string[],
+  authSchema?: ResolvedAuthSchema,
+): string {
+  const byTable = new Map<string, ResolvedAuthModel>();
+  if (authSchema) {
+    for (const model of Object.values(authSchema.models)) {
+      byTable.set(model.tableName, model);
+    }
+  }
+
   const decls = tables
-    .map(
-      (name) =>
-        `/** Generated table handle — wire columns in your app schema. */\nexport const ${camel(name)} = { name: "${name}" } as const;\n`,
-    )
+    .map((name) => {
+      const model = byTable.get(name);
+      if (model) return emitAuthTable(model);
+      return `/** Generated table handle — wire columns in your app schema. */\nexport const ${camel(name)} = { name: "${name}" } as const;\n`;
+    })
     .join("\n");
+
   return `/**
  * Generated by \`oke schema generate\` — do not edit.
- * Core Console tables + Manifest store tables.
+ * Core Gate auth tables + Manifest store tables.
  */
 
 ${decls}
@@ -180,6 +218,40 @@ export const okeTables = [${tables.map((t) => `"${t}"`).join(", ")}] as const;
 `;
 }
 
+function emitAuthTable(model: ResolvedAuthModel): string {
+  const cols = model.columns
+    .map((c) => {
+      const extras: string[] = [`sqlType: "${c.sqlType}"`];
+      if (c.primary) extras.push("primary: true");
+      if (c.required) extras.push("required: true");
+      if (c.defaultValue !== undefined) {
+        extras.push(`defaultValue: ${JSON.stringify(c.defaultValue)}`);
+      }
+      return `    ${c.logical}: { name: "${c.sqlName}", ${extras.join(", ")} }`;
+    })
+    .join(",\n");
+  return `/** Auth model \`${model.model}\` → \`${model.tableName}\`. */
+export const ${camel(model.tableName)} = {
+  name: "${model.tableName}",
+  model: "${model.model}",
+  columns: {
+${cols}
+  },
+} as const;
+`;
+}
+
+/**
+ * Read optional auth schema customization from Manifest extensions.
+ *
+ * @param manifest - Loaded Manifest
+ */
+function loadAuthSchemaFromManifest(manifest: Manifest | undefined): AuthSchemaOptions {
+  if (!manifest) return {};
+  const ext = (manifest as { authSchema?: AuthSchemaOptions }).authSchema;
+  return ext ?? {};
+}
+
 function hashSource(source: string): string {
   return createHash("sha256").update(source).digest("hex");
 }

package/src/client/auth.ts

@@ -0,0 +1,120 @@
+/**
+ * Optional auth helpers for {@link createClient} — not a second client factory.
+ *
+ * @module
+ */
+
+/** Common auth Flow error codes (server `fail` codes). */
+export const AUTH_ERROR_CODES = {
+  AuthFailed: "AuthFailed",
+  AuthRateLimited: "AuthRateLimited",
+  Unauthorized: "Unauthorized",
+  Forbidden: "Forbidden",
+} as const;
+
+/** In-memory session token bag for SPA / Node clients. */
+export interface MemorySession {
+  accessToken: string | null;
+  refreshToken: string | null;
+  accessExpiresAt: number | null;
+  userId: string | null;
+  set(tokens: {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly accessExpiresAt?: number;
+    readonly userId?: string;
+  }): void;
+  clear(): void;
+  /** Wire into `createClient` `auth.getToken`. */
+  getToken(): string | null;
+  /**
+   * Wire into `createClient` `auth.refresh` — calls the refresh Flow via the client.
+   *
+   * @param api - Client with `auth.refresh` route (or custom path)
+   */
+  refresh(api: {
+    auth: {
+      refresh: (input: { refreshToken: string }) => Promise<{
+        data: {
+          accessToken: string;
+          refreshToken: string;
+          accessExpiresAt?: number;
+          userId?: string;
+        } | null;
+        error: unknown;
+      }>;
+    };
+  }): Promise<string | null>;
+}
+
+/**
+ * Create an in-memory session helper for Bearer `createClient` wiring.
+ */
+export function memorySession(): MemorySession {
+  const state: {
+    accessToken: string | null;
+    refreshToken: string | null;
+    accessExpiresAt: number | null;
+    userId: string | null;
+  } = {
+    accessToken: null,
+    refreshToken: null,
+    accessExpiresAt: null,
+    userId: null,
+  };
+
+  return {
+    get accessToken() {
+      return state.accessToken;
+    },
+    set accessToken(v) {
+      state.accessToken = v;
+    },
+    get refreshToken() {
+      return state.refreshToken;
+    },
+    set refreshToken(v) {
+      state.refreshToken = v;
+    },
+    get accessExpiresAt() {
+      return state.accessExpiresAt;
+    },
+    set accessExpiresAt(v) {
+      state.accessExpiresAt = v;
+    },
+    get userId() {
+      return state.userId;
+    },
+    set userId(v) {
+      state.userId = v;
+    },
+    set(tokens) {
+      state.accessToken = tokens.accessToken;
+      state.refreshToken = tokens.refreshToken;
+      state.accessExpiresAt = tokens.accessExpiresAt ?? null;
+      state.userId = tokens.userId ?? null;
+    },
+    clear() {
+      state.accessToken = null;
+      state.refreshToken = null;
+      state.accessExpiresAt = null;
+      state.userId = null;
+    },
+    getToken() {
+      return state.accessToken;
+    },
+    async refresh(api) {
+      if (!state.refreshToken) return null;
+      const { data, error } = await api.auth.refresh({ refreshToken: state.refreshToken });
+      if (error || !data) {
+        state.accessToken = null;
+        return null;
+      }
+      state.accessToken = data.accessToken;
+      state.refreshToken = data.refreshToken;
+      state.accessExpiresAt = data.accessExpiresAt ?? null;
+      if (data.userId) state.userId = data.userId;
+      return data.accessToken;
+    },
+  };
+}

package/src/client-react/index.ts

@@ -0,0 +1,93 @@
+/**
+ * React helpers for okengine clients — `useSession` over {@link createClient}.
+ *
+ * @module
+ */
+
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import type { MemorySession } from "../client/auth.ts";
+
+/** Minimal client surface for session reading. */
+export interface SessionClient {
+  auth: {
+    me: (input?: unknown) => Promise<{
+      data: {
+        userId: string;
+        email: string;
+        name: string;
+        emailVerified?: boolean;
+      } | null;
+      error: unknown;
+    }>;
+  };
+}
+
+/** Session snapshot returned by {@link useSession}. */
+export interface SessionState {
+  readonly status: "loading" | "authenticated" | "unauthenticated";
+  readonly user: {
+    readonly userId: string;
+    readonly email: string;
+    readonly name: string;
+    readonly emailVerified?: boolean;
+  } | null;
+  readonly accessToken: string | null;
+  refresh(): Promise<void>;
+  signOut(): void;
+}
+
+/**
+ * React hook: read session via `auth.me` + optional {@link memorySession} helper.
+ *
+ * @param api - Typed client from `createClient`
+ * @param session - Optional memory session (Bearer storage)
+ */
+export function useSession(api: SessionClient, session?: MemorySession): SessionState {
+  const token = useSyncExternalStore(
+    (onStoreChange) => {
+      if (!session) return () => {};
+      const id = setInterval(onStoreChange, 250);
+      return () => clearInterval(id);
+    },
+    () => session?.accessToken ?? null,
+    () => session?.accessToken ?? null,
+  );
+
+  const [user, setUser] = useState<SessionState["user"]>(null);
+  const [status, setStatus] = useState<SessionState["status"]>("loading");
+
+  const refresh = useCallback(async () => {
+    if (!token) {
+      setUser(null);
+      setStatus("unauthenticated");
+      return;
+    }
+    setStatus("loading");
+    const { data, error } = await api.auth.me({});
+    if (error || !data) {
+      setUser(null);
+      setStatus("unauthenticated");
+      return;
+    }
+    setUser(data);
+    setStatus("authenticated");
+  }, [api, token]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const signOut = useCallback(() => {
+    session?.clear();
+    setUser(null);
+    setStatus("unauthenticated");
+  }, [session]);
+
+  return {
+    status,
+    user,
+    accessToken: token,
+    refresh,
+    signOut,
+  };
+}

package/src/compiler/aot.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
+import { gate } from "../elements/gate.ts";
 import { oke } from "../kernel/app.ts";
 import { flow, resetFlowSeq } from "../kernel/flow.ts";
 import { on, resetBindings } from "../kernel/on.ts";
@@ -118,7 +119,7 @@ describe("typed error narrowing end-to-end", () => {
     const FlightFull = z.object({ seatsLeft: z.number() });
 
     on(
-      http.post("/bookings"),
+      http.post("/bookings").gate(gate.public),
       flow({
         name: "bookings.create",
         in: Booking,