okengine 0.4.3 → 0.5.0

package/src/auth/method-context.ts

@@ -0,0 +1,33 @@
+/**
+ * Active Gate auth context for method plugins plugged on the same app.
+ *
+ * Set during `oke({ gate: { auth } })` so `.plug(username())` etc. share
+ * the app session store + HMAC secret without callers re-passing them.
+ */
+
+import type { SessionStore } from "./sessions.ts";
+
+/** Shared context for auth method plugins. */
+export interface ActiveGateAuthContext {
+  readonly secret: string;
+  readonly sessions: SessionStore;
+  readonly now?: () => number;
+}
+
+let active: ActiveGateAuthContext | undefined;
+
+/**
+ * Publish the app's Gate auth binding for subsequent `.plug()` method plugins.
+ *
+ * @param ctx - Secret + sessions (or undefined to clear)
+ */
+export function setActiveGateAuthContext(ctx: ActiveGateAuthContext | undefined): void {
+  active = ctx;
+}
+
+/**
+ * Read the active Gate auth context, if any.
+ */
+export function getActiveGateAuthContext(): ActiveGateAuthContext | undefined {
+  return active;
+}

package/src/auth/operator.ts

@@ -7,7 +7,10 @@
  * @see docs/spec/console.md §2.2–2.3
  */
 
+import type { PasswordHashOptions } from "../runtime/types.ts";
 import { createBunCrypto } from "../runtime/primitives.ts";
+import { assertNotBreached, type BreachCheckFn } from "./breach-check.ts";
+import { assertPasswordPolicy, type PasswordPolicyOptions } from "./password-policy.ts";
 import type { OperatorCredentialRow, OperatorRow, OperatorSsoLinkRow } from "./tables.ts";
 
 /** Operator-plane store. */
@@ -38,6 +41,22 @@ export interface CreateOperatorOptions {
   readonly invitedBy?: string | null;
   readonly id?: string;
   readonly roles?: readonly string[];
+  /**
+   * Password length / character-class policy. Defaults applied when omitted
+   * (minLength 12, letter + number). Pass custom knobs to tighten/loosen
+   * within reason — never skip without {@link skipPasswordPolicy}.
+   */
+  readonly passwordPolicy?: PasswordPolicyOptions;
+  /**
+   * Explicit opt-out of password policy (test harness only).
+   * Production credential-set paths must omit this — same shape as
+   * `unguardedHttp: "allow"` restricted to tests.
+   */
+  readonly skipPasswordPolicy?: boolean;
+  /** Bun.password cost knobs (argon2id floor enforced). */
+  readonly passwordHash?: PasswordHashOptions;
+  /** Optional breach check (`true` = reject). */
+  readonly breachCheck?: BreachCheckFn;
 }
 
 /**
@@ -50,6 +69,10 @@ export async function createOperator(
   store: OperatorStore,
   options: CreateOperatorOptions,
 ): Promise<OperatorRow> {
+  if (!options.skipPasswordPolicy) {
+    assertPasswordPolicy(options.password, options.passwordPolicy ?? {});
+  }
+  await assertNotBreached(options.password, options.breachCheck);
   const crypto = createBunCrypto();
   const id = options.id ?? crypto.randomUUID();
   const row: OperatorRow = {
@@ -64,7 +87,10 @@ export async function createOperator(
   store.operators.set(id, row);
   store.credentials.set(id, {
     operatorId: id,
-    passwordHash: await crypto.hashPassword(options.password, "argon2id"),
+    passwordHash: await crypto.hashPassword(
+      options.password,
+      options.passwordHash ?? { algorithm: "argon2id" },
+    ),
     loginEnabled: true,
   });
   store.ssoLinks.set(id, []);

package/src/auth/password-policy.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import {
+  assertNotBreached,
+  createHibpBreachCheck,
+  sha1HexUpper,
+  BreachCheckError,
+} from "./breach-check.ts";
+import { assertPasswordPolicy, PasswordPolicyError } from "./password-policy.ts";
+import { createBunCrypto } from "../runtime/primitives.ts";
+import { ARGON2ID_MEMORY_COST_FLOOR } from "../runtime/types.ts";
+import { createOperator, createOperatorStore } from "./operator.ts";
+import { createSessionStore, issueSession, rotateRefresh, SessionError } from "./sessions.ts";
+
+describe("password policy", () => {
+  test("defaults require length 12, letter, number", () => {
+    expect(() => assertPasswordPolicy("short1A", {})).toThrow(PasswordPolicyError);
+    expect(() => assertPasswordPolicy("longenoughword", {})).toThrow(PasswordPolicyError);
+    expect(() => assertPasswordPolicy("Longenough12", {})).not.toThrow();
+  });
+
+  test("createOperator rejects weak passwords by default without passwordPolicy", async () => {
+    const store = createOperatorStore();
+    await expect(
+      createOperator(store, {
+        email: "a@example.com",
+        name: "A",
+        password: "123",
+      }),
+    ).rejects.toThrow(PasswordPolicyError);
+  });
+
+  test("createOperator skipPasswordPolicy is the explicit test opt-out", async () => {
+    const store = createOperatorStore();
+    const op = await createOperator(store, {
+      email: "b@example.com",
+      name: "B",
+      password: "123",
+      skipPasswordPolicy: true,
+    });
+    expect(op.email).toBe("b@example.com");
+  });
+});
+
+describe("Bun.password costs", () => {
+  test("rejects memoryCost below Bun floor", async () => {
+    const crypto = createBunCrypto();
+    await expect(
+      crypto.hashPassword("Longenough12", { algorithm: "argon2id", memoryCost: 1024 }),
+    ).rejects.toThrow(/memoryCost/);
+  });
+
+  test("hashes at Bun default floor", async () => {
+    const crypto = createBunCrypto();
+    const hash = await crypto.hashPassword("Longenough12", {
+      algorithm: "argon2id",
+      memoryCost: ARGON2ID_MEMORY_COST_FLOOR,
+      timeCost: 2,
+    });
+    expect(hash).toContain("m=65536,t=2");
+    expect(await crypto.verifyPassword("Longenough12", hash)).toBe(true);
+  });
+});
+
+describe("HIBP k-anonymity helper", () => {
+  test("matches suffix locally without sending full hash", async () => {
+    const full = await sha1HexUpper("password");
+    const prefix = full.slice(0, 5);
+    const suffix = full.slice(5);
+    const check = createHibpBreachCheck({
+      userAgent: "oke-test",
+      fetch: (async (input) => {
+        const url = String(input);
+        expect(url).toContain("/range/");
+        if (url.includes(`/range/${prefix}`)) {
+          return new Response(`${suffix}:12\nDEADBEEF00:1\n`, { status: 200 });
+        }
+        return new Response("AAAAA00000:1\n", { status: 200 });
+      }) as typeof fetch,
+    });
+    expect(await check("password")).toBe(true);
+    expect(await check("not-in-list-xyz")).toBe(false);
+  });
+
+  test("assertNotBreached throws when check returns true", async () => {
+    await expect(assertNotBreached("x", async () => true)).rejects.toThrow(BreachCheckError);
+  });
+});
+
+describe("session idle / absolute / single-session", () => {
+  test("idle timeout rejects refresh", async () => {
+    let now = 1_000_000;
+    const store = createSessionStore();
+    const crypto = {
+      secret: "test-secret-at-least-32-bytes-long!!",
+      now: () => now,
+      idleTtlMs: 60_000,
+    };
+    const issued = await issueSession(store, crypto, {
+      id: "u1",
+      plane: "user",
+      scopes: [],
+    });
+    now += 120_000;
+    await expect(rotateRefresh(store, crypto, issued.refreshToken)).rejects.toThrow(SessionError);
+  });
+
+  test("singleSessionPerUser revokes prior family", async () => {
+    const store = createSessionStore();
+    const crypto = {
+      secret: "test-secret-at-least-32-bytes-long!!",
+      now: () => 1_000_000,
+      singleSessionPerUser: true,
+    };
+    const first = await issueSession(store, crypto, {
+      id: "u1",
+      plane: "user",
+      scopes: [],
+    });
+    await issueSession(store, crypto, {
+      id: "u1",
+      plane: "user",
+      scopes: [],
+    });
+    expect(store.sessions.get(first.session.id)?.revokedAt).not.toBeNull();
+  });
+});

package/src/auth/password-policy.ts

@@ -0,0 +1,77 @@
+/**
+ * Password policy — length + character-class rules (never weaker defaults).
+ */
+
+/** Options for {@link assertPasswordPolicy}. */
+export interface PasswordPolicyOptions {
+  /** Minimum length (default 12). */
+  readonly minLength?: number;
+  /** Require at least one letter (default true). */
+  readonly requireLetter?: boolean;
+  /** Require at least one digit (default true). */
+  readonly requireNumber?: boolean;
+  /** Require at least one non-alphanumeric symbol (default false). */
+  readonly requireSymbol?: boolean;
+}
+
+/** Resolved policy with defaults applied. */
+export interface ResolvedPasswordPolicy {
+  readonly minLength: number;
+  readonly requireLetter: boolean;
+  readonly requireNumber: boolean;
+  readonly requireSymbol: boolean;
+}
+
+/** Default minimum password length. */
+export const DEFAULT_PASSWORD_MIN_LENGTH = 12;
+
+/**
+ * Resolve policy options with safe defaults.
+ *
+ * @param options - Partial policy
+ */
+export function resolvePasswordPolicy(options: PasswordPolicyOptions = {}): ResolvedPasswordPolicy {
+  return {
+    minLength: options.minLength ?? DEFAULT_PASSWORD_MIN_LENGTH,
+    requireLetter: options.requireLetter ?? true,
+    requireNumber: options.requireNumber ?? true,
+    requireSymbol: options.requireSymbol ?? false,
+  };
+}
+
+/**
+ * Validate a password against policy. Throws {@link PasswordPolicyError}.
+ *
+ * @param password - Plaintext
+ * @param options - Policy (defaults applied)
+ */
+export function assertPasswordPolicy(password: string, options: PasswordPolicyOptions = {}): void {
+  const policy = resolvePasswordPolicy(options);
+  const reasons: string[] = [];
+  if (password.length < policy.minLength) {
+    reasons.push(`minLength ${policy.minLength} (got ${password.length})`);
+  }
+  if (policy.requireLetter && !/[A-Za-z]/.test(password)) {
+    reasons.push("requireLetter");
+  }
+  if (policy.requireNumber && !/\d/.test(password)) {
+    reasons.push("requireNumber");
+  }
+  if (policy.requireSymbol && !/[^A-Za-z0-9]/.test(password)) {
+    reasons.push("requireSymbol");
+  }
+  if (reasons.length > 0) {
+    throw new PasswordPolicyError(reasons);
+  }
+}
+
+/** Password failed policy checks. */
+export class PasswordPolicyError extends Error {
+  readonly reasons: readonly string[];
+
+  constructor(reasons: readonly string[]) {
+    super(`password policy failed: ${reasons.join(", ")}`);
+    this.name = "PasswordPolicyError";
+    this.reasons = reasons;
+  }
+}

package/src/auth/plugin.ts

@@ -4,23 +4,79 @@
  * Uses only the public plugin API (unified-theory §14).
  */
 
+import type { PasswordHashOptions } from "../runtime/types.ts";
 import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import type { BreachCheckFn } from "./breach-check.ts";
+import type { PasswordPolicyOptions } from "./password-policy.ts";
 import { AUTH_TABLES } from "./tables.ts";
 
+/** Session knobs beyond raw access/refresh TTLs. */
+export interface AuthSessionOptions {
+  /** Access-token TTL override (ms). Default 14 minutes. */
+  readonly accessTtlMs?: number;
+  /** Refresh-token TTL override (ms). Default 30 days. */
+  readonly refreshTtlMs?: number;
+  /** Idle timeout from last activity (ms). Opt-in. */
+  readonly idleTtlMs?: number;
+  /** Absolute lifetime from session creation (ms). Opt-in. */
+  readonly absoluteTtlMs?: number;
+  /** Revoke other families for the same principal on issue. Opt-in. */
+  readonly singleSessionPerUser?: boolean;
+}
+
 /** Options for {@link auth}. */
 export interface AuthPluginOptions {
   /** HMAC secret for access tokens (required in production). */
   readonly secret?: string;
-  /** Access-token TTL override (ms). */
+  /** Access-token TTL override (ms). Prefer {@link session}. */
+  readonly accessTtlMs?: number;
+  /** Refresh-token TTL override (ms). Prefer {@link session}. */
+  readonly refreshTtlMs?: number;
+  /** Session timeouts and single-session policy. */
+  readonly session?: AuthSessionOptions;
+  /**
+   * Bun.password cost knobs. Defaults match Bun argon2id (`m=65536`, `t=2`);
+   * weaker values are rejected.
+   */
+  readonly password?: PasswordHashOptions;
+  /**
+   * Password length / character-class policy (defaults: minLength 12,
+   * letter + number). Credential-set paths enforce defaults unless a
+   * caller passes `skipPasswordPolicy` (tests only).
+   */
+  readonly passwordPolicy?: PasswordPolicyOptions;
+  /**
+   * Pluggable breach check (`true` = reject). Default off.
+   * Use {@link createHibpBreachCheck} for Have I Been Pwned k-anonymity.
+   */
+  readonly breachCheck?: BreachCheckFn;
+}
+
+/**
+ * Flatten plugin options into {@link SessionCrypto}-compatible fields.
+ *
+ * @param options - Auth plugin options
+ */
+export function sessionCryptoFromAuthOptions(options: AuthPluginOptions): {
   readonly accessTtlMs?: number;
-  /** Refresh-token TTL override (ms). */
   readonly refreshTtlMs?: number;
+  readonly idleTtlMs?: number;
+  readonly absoluteTtlMs?: number;
+  readonly singleSessionPerUser?: boolean;
+} {
+  return {
+    accessTtlMs: options.session?.accessTtlMs ?? options.accessTtlMs,
+    refreshTtlMs: options.session?.refreshTtlMs ?? options.refreshTtlMs,
+    idleTtlMs: options.session?.idleTtlMs,
+    absoluteTtlMs: options.session?.absoluteTtlMs,
+    singleSessionPerUser: options.session?.singleSessionPerUser,
+  };
 }
 
 /**
  * Builtin auth plugin.
  *
- * @param options - Session crypto options
+ * @param options - Session crypto / password policy options
  */
 export function auth(options: AuthPluginOptions = {}): PluginDef {
   let builder = plugin("auth", { version: "0.0.1", config: options }).hook("onAuth", (_ctx) => {
@@ -31,7 +87,9 @@ export function auth(options: AuthPluginOptions = {}): PluginDef {
     builder = builder.table(name, undefined, {
       plane: name.includes("operator")
         ? "operator"
-        : name.includes("identit") || name === AUTH_TABLES.credentials
+        : name.includes("identit") ||
+            name === AUTH_TABLES.credentials ||
+            name === AUTH_TABLES.verifications
           ? "user"
           : "shared",
     });

package/src/auth/rate.ts

@@ -0,0 +1,45 @@
+/**
+ * Sliding-window rate limit for auth credential checks.
+ *
+ * Shared strategy with Console operator login (5 / 60s).
+ */
+
+/** Max attempts per window. */
+export const AUTH_RATE_LIMIT = 5;
+
+/** Rate-limit window. */
+export const AUTH_RATE_WINDOW_MS = 60 * 1000;
+
+/**
+ * Record an attempt and return whether the key is still under the limit.
+ *
+ * @param attempts - Sliding timestamps for one key
+ * @param now - Epoch-ms
+ * @param limit - Max attempts
+ * @param windowMs - Window length
+ */
+export function touchRateLimit(
+  attempts: number[],
+  now: number,
+  limit: number = AUTH_RATE_LIMIT,
+  windowMs: number = AUTH_RATE_WINDOW_MS,
+): "ok" | "rate_limited" {
+  while (attempts.length > 0 && attempts[0]! <= now - windowMs) {
+    attempts.shift();
+  }
+  if (attempts.length >= limit) {
+    return "rate_limited";
+  }
+  attempts.push(now);
+  return "ok";
+}
+
+/** Per-key attempt bags (email → timestamps). */
+export type LoginAttemptBag = Map<string, number[]>;
+
+/**
+ * Create an empty login attempt bag.
+ */
+export function createLoginAttemptBag(): LoginAttemptBag {
+  return new Map();
+}

package/src/auth/schema.ts

@@ -0,0 +1,260 @@
+/**
+ * Core Gate auth schema — defaults + `modelName` / `fields` / `additionalFields`.
+ *
+ * Used by `gate.auth` resolution and `oke schema generate`.
+ */
+
+import { AUTH_TABLES } from "./tables.ts";
+
+/** Supported additional-field value types. */
+export type AuthFieldType = "string" | "number" | "boolean" | "json";
+
+/** Extra column declared on a core auth model. */
+export interface AuthAdditionalField {
+  readonly type: AuthFieldType;
+  readonly required?: boolean;
+  readonly defaultValue?: unknown;
+  /** Database column name when different from the field key. */
+  readonly fieldName?: string;
+}
+
+/** Per-model customization. */
+export interface AuthModelOptions {
+  /** Physical table name. */
+  readonly modelName?: string;
+  /**
+   * Rename logical fields → physical columns
+   * (e.g. `{ principalId: "user_id" }`).
+   */
+  readonly fields?: Readonly<Record<string, string>>;
+  /** Extra columns beyond the core set. */
+  readonly additionalFields?: Readonly<Record<string, AuthAdditionalField>>;
+}
+
+/** Logical core models Gate auth owns. */
+export type AuthCoreModel =
+  | "user"
+  | "account"
+  | "session"
+  | "refreshToken"
+  | "verification"
+  | "roles"
+  | "apiKeys";
+
+/** Default logical → physical field map per model. */
+export const AUTH_MODEL_DEFAULT_FIELDS: Readonly<
+  Record<AuthCoreModel, Readonly<Record<string, string>>>
+> = {
+  user: {
+    id: "id",
+    email: "email",
+    name: "name",
+    emailVerified: "email_verified",
+    image: "image",
+    createdAt: "created_at",
+    updatedAt: "updated_at",
+    status: "status",
+  },
+  account: {
+    id: "id",
+    userId: "user_id",
+    provider: "provider",
+    providerAccountId: "provider_account_id",
+    passwordHash: "password_hash",
+    createdAt: "created_at",
+    updatedAt: "updated_at",
+  },
+  session: {
+    id: "id",
+    principalId: "principal_id",
+    plane: "plane",
+    familyId: "family_id",
+    revokedAt: "revoked_at",
+    createdAt: "created_at",
+    expiresAt: "expires_at",
+    lastActiveAt: "last_active_at",
+  },
+  refreshToken: {
+    id: "id",
+    sessionId: "session_id",
+    familyId: "family_id",
+    hash: "hash",
+    expiresAt: "expires_at",
+    usedAt: "used_at",
+    revokedAt: "revoked_at",
+  },
+  verification: {
+    id: "id",
+    identifier: "identifier",
+    value: "value",
+    expiresAt: "expires_at",
+    createdAt: "created_at",
+  },
+  roles: {
+    id: "id",
+    name: "name",
+    plane: "plane",
+    description: "description",
+  },
+  apiKeys: {
+    id: "id",
+    plane: "plane",
+    hash: "hash",
+    name: "name",
+    scopes: "scopes",
+    expiresAt: "expires_at",
+    createdAt: "created_at",
+    lastUsedAt: "last_used_at",
+    revokedAt: "revoked_at",
+  },
+};
+
+/** Default table names (aligned with {@link AUTH_TABLES} where they overlap). */
+export const AUTH_MODEL_DEFAULT_TABLES: Readonly<Record<AuthCoreModel, string>> = {
+  user: AUTH_TABLES.identities,
+  account: AUTH_TABLES.credentials,
+  session: AUTH_TABLES.sessions,
+  refreshToken: AUTH_TABLES.refreshTokens,
+  verification: "oke_verifications",
+  roles: AUTH_TABLES.roles,
+  apiKeys: AUTH_TABLES.apiKeys,
+};
+
+/** SQL type hint for generated columns. */
+export type AuthColumnSqlType = "TEXT" | "INTEGER" | "REAL" | "BLOB";
+
+/** One resolved column for schema generate / DDL. */
+export interface ResolvedAuthColumn {
+  readonly logical: string;
+  readonly sqlName: string;
+  readonly sqlType: AuthColumnSqlType;
+  readonly primary?: boolean;
+  readonly required?: boolean;
+  readonly defaultValue?: unknown;
+}
+
+/** One resolved auth model. */
+export interface ResolvedAuthModel {
+  readonly model: AuthCoreModel;
+  readonly tableName: string;
+  readonly fields: Readonly<Record<string, string>>;
+  readonly columns: readonly ResolvedAuthColumn[];
+  readonly additionalFields: Readonly<Record<string, AuthAdditionalField>>;
+}
+
+/** Fully resolved auth schema. */
+export interface ResolvedAuthSchema {
+  readonly models: Readonly<Record<AuthCoreModel, ResolvedAuthModel>>;
+  /** All physical table names (sorted unique). */
+  readonly tableNames: readonly string[];
+}
+
+/** Input bag for {@link resolveAuthSchema}. */
+export interface AuthSchemaOptions {
+  readonly user?: AuthModelOptions;
+  readonly account?: AuthModelOptions;
+  readonly session?: AuthModelOptions;
+  readonly refreshToken?: AuthModelOptions;
+  readonly verification?: AuthModelOptions;
+  readonly roles?: AuthModelOptions;
+  readonly apiKeys?: AuthModelOptions;
+}
+
+const CORE_SQL_TYPES: Readonly<Record<string, AuthColumnSqlType>> = {
+  id: "TEXT",
+  email: "TEXT",
+  name: "TEXT",
+  emailVerified: "INTEGER",
+  image: "TEXT",
+  createdAt: "INTEGER",
+  updatedAt: "INTEGER",
+  status: "TEXT",
+  userId: "TEXT",
+  provider: "TEXT",
+  providerAccountId: "TEXT",
+  passwordHash: "TEXT",
+  principalId: "TEXT",
+  plane: "TEXT",
+  familyId: "TEXT",
+  revokedAt: "INTEGER",
+  expiresAt: "INTEGER",
+  lastActiveAt: "INTEGER",
+  sessionId: "TEXT",
+  hash: "TEXT",
+  usedAt: "INTEGER",
+  identifier: "TEXT",
+  value: "TEXT",
+  description: "TEXT",
+  scopes: "TEXT",
+  lastUsedAt: "INTEGER",
+};
+
+/**
+ * Map an additional-field type to a SQL column type.
+ *
+ * @param type - Declared field type
+ */
+export function authFieldSqlType(type: AuthFieldType): AuthColumnSqlType {
+  switch (type) {
+    case "number":
+      return "INTEGER";
+    case "boolean":
+      return "INTEGER";
+    case "json":
+      return "TEXT";
+    default:
+      return "TEXT";
+  }
+}
+
+/**
+ * Resolve core auth schema with defaults + caller overrides.
+ *
+ * @param options - Per-model customization from `gate.auth`
+ */
+export function resolveAuthSchema(options: AuthSchemaOptions = {}): ResolvedAuthSchema {
+  const models = {} as Record<AuthCoreModel, ResolvedAuthModel>;
+  const tableNames = new Set<string>();
+
+  for (const model of Object.keys(AUTH_MODEL_DEFAULT_TABLES) as AuthCoreModel[]) {
+    const opts = options[model] ?? {};
+    const defaults = AUTH_MODEL_DEFAULT_FIELDS[model];
+    const fields: Record<string, string> = { ...defaults, ...(opts.fields ?? {}) };
+    const additional = opts.additionalFields ?? {};
+    const tableName = opts.modelName ?? AUTH_MODEL_DEFAULT_TABLES[model];
+    tableNames.add(tableName);
+
+    const columns: ResolvedAuthColumn[] = [];
+    for (const [logical, sqlName] of Object.entries(fields)) {
+      columns.push({
+        logical,
+        sqlName,
+        sqlType: CORE_SQL_TYPES[logical] ?? "TEXT",
+        primary: logical === "id",
+        required: logical === "id" || logical === "email" || logical === "principalId",
+      });
+    }
+    for (const [key, field] of Object.entries(additional)) {
+      columns.push({
+        logical: key,
+        sqlName: field.fieldName ?? fields[key] ?? key,
+        sqlType: authFieldSqlType(field.type),
+        required: field.required === true,
+        defaultValue: field.defaultValue,
+      });
+    }
+
+    models[model] = {
+      model,
+      tableName,
+      fields,
+      columns,
+      additionalFields: additional,
+    };
+  }
+
+  return {
+    models,
+    tableNames: [...tableNames].sort(),
+  };
+}