okengine 0.3.6 → 0.5.0

package/src/auth/breach-check.ts

@@ -0,0 +1,112 @@
+/**
+ * Pluggable password breach check — optional Have I Been Pwned k-anonymity helper.
+ *
+ * HIBP Pwned Passwords range API (no API key):
+ * `GET https://api.pwnedpasswords.com/range/{5-char-SHA1-prefix}`
+ * with required `User-Agent`. Client matches the remaining suffix locally.
+ */
+
+/** Returns `true` when the password should be rejected as breached. */
+export type BreachCheckFn = (password: string) => Promise<boolean>;
+
+/** Behaviour when the breach-check network call fails. */
+export type BreachCheckErrorMode = "reject" | "allow";
+
+/** Options for {@link createHibpBreachCheck}. */
+export interface HibpBreachCheckOptions {
+  /** Required identifying User-Agent (HIBP terms). */
+  readonly userAgent: string;
+  /** Injectable fetch (tests). Defaults to global `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Send `Add-Padding: true` (recommended). Default true. */
+  readonly padding?: boolean;
+  /**
+   * When the range API errors / is unreachable.
+   * Default `"reject"` (fail closed while breach check is enabled).
+   */
+  readonly onError?: BreachCheckErrorMode;
+}
+
+const HIBP_RANGE_URL = "https://api.pwnedpasswords.com/range/";
+
+/**
+ * SHA-1 hex digest of a UTF-8 string (uppercase).
+ *
+ * @param password - Plaintext
+ */
+export async function sha1HexUpper(password: string): Promise<string> {
+  const data = new TextEncoder().encode(password);
+  const digest = await crypto.subtle.digest("SHA-1", data);
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .toUpperCase();
+}
+
+/**
+ * Create a Have I Been Pwned k-anonymity breach checker.
+ *
+ * Never sends the password or full hash — only the first 5 hex chars of SHA-1.
+ *
+ * @param options - User-Agent and fetch knobs
+ */
+export function createHibpBreachCheck(options: HibpBreachCheckOptions): BreachCheckFn {
+  const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const onError = options.onError ?? "reject";
+  const padding = options.padding !== false;
+
+  return async (password) => {
+    const full = await sha1HexUpper(password);
+    const prefix = full.slice(0, 5);
+    const suffix = full.slice(5);
+    try {
+      const res = await fetchFn(`${HIBP_RANGE_URL}${prefix}`, {
+        headers: {
+          "User-Agent": options.userAgent,
+          ...(padding ? { "Add-Padding": "true" } : {}),
+        },
+      });
+      if (!res.ok) {
+        if (onError === "allow") return false;
+        throw new BreachCheckError(`HIBP range HTTP ${res.status}`);
+      }
+      const body = await res.text();
+      for (const line of body.split("\n")) {
+        const [hashSuffix, countStr] = line.trim().split(":");
+        if (!hashSuffix || hashSuffix.length === 0) continue;
+        const count = Number(countStr ?? "0");
+        // Padded rows always have count 0 — discard.
+        if (count === 0) continue;
+        if (hashSuffix.toUpperCase() === suffix) return true;
+      }
+      return false;
+    } catch (err) {
+      if (err instanceof BreachCheckError) throw err;
+      if (onError === "allow") return false;
+      throw new BreachCheckError(err instanceof Error ? err.message : "HIBP range request failed");
+    }
+  };
+}
+
+/**
+ * Run an optional breach check. No-op when `check` is omitted.
+ *
+ * @param password - Plaintext
+ * @param check - Pluggable checker (`true` = breached)
+ */
+export async function assertNotBreached(
+  password: string,
+  check: BreachCheckFn | undefined,
+): Promise<void> {
+  if (!check) return;
+  const breached = await check(password);
+  if (breached) throw new BreachCheckError("password appears in a known breach");
+}
+
+/** Breach check rejected the password or failed closed. */
+export class BreachCheckError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BreachCheckError";
+  }
+}

package/src/auth/config.ts

@@ -0,0 +1,288 @@
+/**
+ * Gate auth options — resolved from `oke({ gate: { auth } })`.
+ *
+ * Better Auth is inspiration for shape only; this is OKE-native.
+ */
+
+import type { PasswordHashOptions } from "../runtime/types.ts";
+import type { SessionStore } from "./sessions.ts";
+import type { BreachCheckFn } from "./breach-check.ts";
+import type { PasswordPolicyOptions } from "./password-policy.ts";
+import {
+  resolveAuthSchema,
+  type AuthModelOptions,
+  type AuthSchemaOptions,
+  type ResolvedAuthSchema,
+} from "./schema.ts";
+import { sessionCryptoFromAuthOptions, type AuthSessionOptions } from "./plugin.ts";
+
+/** Email + password method knobs. */
+export interface EmailAndPasswordOptions {
+  readonly enabled?: boolean;
+  /** Require verified email before sign-in (default false). */
+  readonly requireEmailVerification?: boolean;
+}
+
+/** Account-linking policy (Phase 1 stub — enforced later with OAuth). */
+export interface AccountLinkingOptions {
+  readonly enabled?: boolean;
+  readonly trustedProviders?: readonly string[];
+  readonly allowDifferentEmails?: boolean;
+}
+
+/** Opt-in cookie session mirror (Phase 1a). Bearer remains default. */
+export interface AuthCookieOptions {
+  readonly enabled?: boolean;
+  /** Cookie name prefix (default `oke`). */
+  readonly prefix?: string;
+  readonly secure?: boolean;
+  /** Share across subdomains (`.example.com`). */
+  readonly crossSubdomain?: boolean;
+  readonly domain?: string;
+  readonly sameSite?: "strict" | "lax" | "none";
+  readonly path?: string;
+}
+
+/** Secondary hot-path storage (Phase 1a) — uses `store.kv` when configured. */
+export interface AuthSecondaryStorageOptions {
+  readonly enabled?: boolean;
+  /** Kv namespace prefix (default `auth:`). */
+  readonly prefix?: string;
+}
+
+/** Lifecycle hooks (Phase 1a) — fx-safe, no side-channel I/O. */
+export interface AuthDatabaseHooks {
+  readonly user?: {
+    readonly create?: {
+      readonly before?: (user: Record<string, unknown>) => unknown | Promise<unknown>;
+      readonly after?: (user: Record<string, unknown>) => void | Promise<void>;
+    };
+  };
+  readonly session?: {
+    readonly create?: {
+      readonly after?: (session: Record<string, unknown>) => void | Promise<void>;
+    };
+  };
+  readonly account?: {
+    readonly create?: {
+      readonly after?: (account: Record<string, unknown>) => void | Promise<void>;
+    };
+  };
+}
+
+/** Session options under `gate.auth.session` (extends plugin session + schema). */
+export interface GateAuthSessionOptions extends AuthSessionOptions, AuthModelOptions {
+  /**
+   * Max age (ms) from session creation for "fresh" step-up policies.
+   * Default 24h. `fx.auth` / gate policies can require freshness.
+   */
+  readonly freshAgeMs?: number;
+}
+
+/** Public `gate.auth` bag. */
+export interface GateAuthOptions extends AuthSchemaOptions {
+  /** HMAC secret for access tokens. Required in prod; minted in dev when omitted. */
+  readonly secret?: string;
+  /** HTTP base path for auth Flows (default `/auth`). */
+  readonly basePath?: string;
+  /**
+   * When `false`, skip materializing `/auth/*` HTTP Bindings
+   * (embedding / Console — secret + tables only). Default `true`.
+   */
+  readonly http?: boolean;
+  /** Audience stamped on access tokens (default `oke-app`). */
+  readonly audience?: string;
+  readonly emailAndPassword?: EmailAndPasswordOptions;
+  readonly session?: GateAuthSessionOptions;
+  readonly accountLinking?: AccountLinkingOptions;
+  readonly password?: PasswordHashOptions;
+  readonly passwordPolicy?: PasswordPolicyOptions;
+  readonly breachCheck?: BreachCheckFn;
+  /** Opt-in HttpOnly cookie mirror (Phase 1a). */
+  readonly cookies?: AuthCookieOptions;
+  /** Opt-in secondary kv storage (Phase 1a). */
+  readonly secondaryStorage?: AuthSecondaryStorageOptions;
+  /** Lifecycle hooks (Phase 1a). */
+  readonly hooks?: AuthDatabaseHooks;
+  /**
+   * Pre-built session store (Console / tests). Created when omitted.
+   * Not part of the public app DX — escape hatch for embedding.
+   */
+  readonly sessions?: SessionStore;
+  /** Injectable clock. */
+  readonly now?: () => number;
+}
+
+/** Resolved account-linking stub. */
+export interface ResolvedAccountLinking {
+  readonly enabled: boolean;
+  readonly trustedProviders: readonly string[];
+  readonly allowDifferentEmails: boolean;
+}
+
+/** Resolved cookie options. */
+export interface ResolvedAuthCookies {
+  readonly enabled: boolean;
+  readonly prefix: string;
+  readonly secure: boolean;
+  readonly crossSubdomain: boolean;
+  readonly domain: string | undefined;
+  readonly sameSite: "strict" | "lax" | "none";
+  readonly path: string;
+}
+
+/** Fully resolved Gate auth config. */
+export interface ResolvedGateAuth {
+  readonly enabled: true;
+  readonly secret: string;
+  readonly secretMinted: boolean;
+  readonly basePath: string;
+  /** When false, no `/auth/*` Bindings (secret / tables / Bearer only). */
+  readonly http: boolean;
+  readonly audience: string;
+  readonly emailAndPassword: {
+    readonly enabled: boolean;
+    readonly requireEmailVerification: boolean;
+  };
+  readonly session: {
+    readonly accessTtlMs: number | undefined;
+    readonly refreshTtlMs: number | undefined;
+    readonly idleTtlMs: number | undefined;
+    readonly absoluteTtlMs: number | undefined;
+    readonly singleSessionPerUser: boolean;
+    readonly freshAgeMs: number;
+  };
+  readonly accountLinking: ResolvedAccountLinking;
+  readonly schema: ResolvedAuthSchema;
+  readonly password: PasswordHashOptions | undefined;
+  readonly passwordPolicy: PasswordPolicyOptions | undefined;
+  readonly breachCheck: BreachCheckFn | undefined;
+  readonly cookies: ResolvedAuthCookies;
+  readonly secondaryStorage: {
+    readonly enabled: boolean;
+    readonly prefix: string;
+  };
+  readonly hooks: AuthDatabaseHooks | undefined;
+  readonly sessions: SessionStore | undefined;
+  readonly now: (() => number) | undefined;
+}
+
+/** Default fresh-age window (24h). */
+export const DEFAULT_FRESH_AGE_MS = 24 * 60 * 60 * 1000;
+
+/** Options for {@link resolveGateAuth}. */
+export interface ResolveGateAuthOptions {
+  readonly auth: GateAuthOptions;
+  /** Boot / app env (`prod` fails without secret). */
+  readonly env?: string;
+}
+
+/**
+ * Mint a development HMAC secret (never used in production boots).
+ */
+export function mintDevAuthSecret(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `oke_dev_${Buffer.from(bytes).toString("base64url")}`;
+}
+
+/**
+ * Resolve `gate.auth` — fails in prod when `secret` is missing.
+ *
+ * @param options - Auth bag + env
+ */
+export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAuth {
+  const { auth, env } = options;
+  const isProd = env === "prod" || env === "production";
+  let secret = auth.secret;
+  let secretMinted = false;
+  if (!secret || secret.length === 0) {
+    if (isProd) {
+      throw new Error(
+        "gate.auth: secret is required in production (set gate.auth.secret or OKE_AUTH_SECRET)",
+      );
+    }
+    secret = mintDevAuthSecret();
+    secretMinted = true;
+  }
+
+  const sessionOpts = auth.session ?? {};
+  const crypto = sessionCryptoFromAuthOptions({
+    accessTtlMs: sessionOpts.accessTtlMs,
+    refreshTtlMs: sessionOpts.refreshTtlMs,
+    session: sessionOpts,
+  });
+
+  const schema = resolveAuthSchema({
+    user: auth.user,
+    account: auth.account,
+    session: auth.session,
+    refreshToken: auth.refreshToken,
+    verification: auth.verification,
+    roles: auth.roles,
+    apiKeys: auth.apiKeys,
+  });
+
+  const basePath = normalizeBasePath(auth.basePath ?? "/auth");
+  const cookies = auth.cookies ?? {};
+  const secondary = auth.secondaryStorage ?? {};
+  const linking = auth.accountLinking ?? {};
+
+  return {
+    enabled: true,
+    secret,
+    secretMinted,
+    basePath,
+    http: auth.http !== false,
+    audience: auth.audience ?? "oke-app",
+    emailAndPassword: {
+      enabled: auth.emailAndPassword?.enabled === true,
+      requireEmailVerification: auth.emailAndPassword?.requireEmailVerification === true,
+    },
+    session: {
+      accessTtlMs: crypto.accessTtlMs,
+      refreshTtlMs: crypto.refreshTtlMs,
+      idleTtlMs: crypto.idleTtlMs,
+      absoluteTtlMs: crypto.absoluteTtlMs,
+      singleSessionPerUser: crypto.singleSessionPerUser === true,
+      freshAgeMs: sessionOpts.freshAgeMs ?? DEFAULT_FRESH_AGE_MS,
+    },
+    accountLinking: {
+      enabled: linking.enabled === true,
+      trustedProviders: linking.trustedProviders ?? ["credential"],
+      allowDifferentEmails: linking.allowDifferentEmails === true,
+    },
+    schema,
+    password: auth.password,
+    passwordPolicy: auth.passwordPolicy,
+    breachCheck: auth.breachCheck,
+    cookies: {
+      enabled: cookies.enabled === true,
+      prefix: cookies.prefix ?? "oke",
+      secure: cookies.secure !== false,
+      crossSubdomain: cookies.crossSubdomain === true,
+      domain: cookies.domain,
+      sameSite: cookies.sameSite ?? "lax",
+      path: cookies.path ?? "/",
+    },
+    secondaryStorage: {
+      enabled: secondary.enabled === true,
+      prefix: secondary.prefix ?? "auth:",
+    },
+    hooks: auth.hooks,
+    sessions: auth.sessions,
+    now: auth.now,
+  };
+}
+
+/**
+ * Normalize auth base path (`/auth`, no trailing slash except root).
+ *
+ * @param path - Raw base path
+ */
+export function normalizeBasePath(path: string): string {
+  const trimmed = path.trim();
+  if (trimmed === "" || trimmed === "/") return "/auth";
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withSlash.replace(/\/+$/, "") || "/auth";
+}

package/src/auth/cookies.ts

@@ -0,0 +1,123 @@
+/**
+ * Opt-in auth cookie helpers (Phase 1a) — Bearer remains the default transport.
+ *
+ * Mirrors Console's cookie→Bearer pattern for app Gate auth when enabled.
+ */
+
+import type { ResolvedAuthCookies } from "./config.ts";
+
+/** Cookie names derived from prefix. */
+export interface AuthCookieNames {
+  readonly access: string;
+  readonly refresh: string;
+}
+
+/**
+ * Cookie names for a resolved cookie config.
+ *
+ * @param cookies - Resolved cookie options
+ */
+export function authCookieNames(cookies: ResolvedAuthCookies): AuthCookieNames {
+  const p = cookies.prefix;
+  return {
+    access: `${p}.session_token`,
+    refresh: `${p}.refresh_token`,
+  };
+}
+
+/**
+ * Build `Set-Cookie` header values for access + refresh tokens.
+ *
+ * @param cookies - Resolved cookie options
+ * @param tokens - Issued tokens
+ * @param maxAgeSec - Max-Age for refresh (access uses shorter when provided)
+ */
+export function buildAuthSetCookies(
+  cookies: ResolvedAuthCookies,
+  tokens: { readonly accessToken: string; readonly refreshToken: string },
+  maxAgeSec: { readonly access: number; readonly refresh: number },
+): string[] {
+  if (!cookies.enabled) return [];
+  const names = authCookieNames(cookies);
+  return [
+    serializeCookie(names.access, tokens.accessToken, cookies, maxAgeSec.access),
+    serializeCookie(names.refresh, tokens.refreshToken, cookies, maxAgeSec.refresh),
+  ];
+}
+
+/**
+ * Build clearing `Set-Cookie` headers (logout).
+ *
+ * @param cookies - Resolved cookie options
+ */
+export function clearAuthSetCookies(cookies: ResolvedAuthCookies): string[] {
+  if (!cookies.enabled) return [];
+  const names = authCookieNames(cookies);
+  return [
+    serializeCookie(names.access, "", cookies, 0),
+    serializeCookie(names.refresh, "", cookies, 0),
+  ];
+}
+
+/**
+ * Extract Bearer-equivalent token from Cookie header when cookies enabled.
+ * Prefers access cookie; falls back to refresh only when caller asks.
+ *
+ * @param cookieHeader - Raw `Cookie` header
+ * @param cookies - Resolved cookie options
+ */
+export function tokenFromCookieHeader(
+  cookieHeader: string | null | undefined,
+  cookies: ResolvedAuthCookies,
+): string | undefined {
+  if (!cookies.enabled || !cookieHeader) return undefined;
+  const names = authCookieNames(cookies);
+  const map = parseCookieHeader(cookieHeader);
+  return map.get(names.access) || undefined;
+}
+
+function serializeCookie(
+  name: string,
+  value: string,
+  cookies: ResolvedAuthCookies,
+  maxAge: number,
+): string {
+  const parts = [
+    `${name}=${encodeURIComponent(value)}`,
+    `Path=${cookies.path}`,
+    `Max-Age=${Math.max(0, Math.floor(maxAge))}`,
+    "HttpOnly",
+    `SameSite=${capitalizeSameSite(cookies.sameSite)}`,
+  ];
+  if (cookies.secure) parts.push("Secure");
+  const domain = cookies.domain ?? (cookies.crossSubdomain ? undefined : undefined);
+  if (domain) parts.push(`Domain=${domain}`);
+  return parts.join("; ");
+}
+
+function capitalizeSameSite(v: "strict" | "lax" | "none"): string {
+  if (v === "none") return "None";
+  if (v === "lax") return "Lax";
+  return "Strict";
+}
+
+/**
+ * Parse a Cookie header into a map.
+ *
+ * @param header - Raw Cookie header
+ */
+export function parseCookieHeader(header: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const part of header.split(";")) {
+    const idx = part.indexOf("=");
+    if (idx <= 0) continue;
+    const k = part.slice(0, idx).trim();
+    const v = part.slice(idx + 1).trim();
+    try {
+      out.set(k, decodeURIComponent(v));
+    } catch {
+      out.set(k, v);
+    }
+  }
+  return out;
+}