okengine 0.5.1 → 0.6.1

package/src/plugins/username-policy.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Username policy unit + sign-up integration.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { oke } from "../kernel/app.ts";
+import { resetFlowSeq } from "../kernel/flow.ts";
+import { resetBindings } from "../kernel/on.ts";
+import {
+  assertUsernamePolicy,
+  DEFAULT_RESERVED_USERNAMES,
+  DEFAULT_USERNAME_MAX_LENGTH,
+  DEFAULT_USERNAME_MIN_LENGTH,
+  resolveUsernamePolicy,
+  username,
+  UsernamePolicyError,
+} from "./username.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("username policy", () => {
+  test("defaults: 3–64 from a-z0-9._-", () => {
+    const policy = resolveUsernamePolicy();
+    expect(policy.minLength).toBe(DEFAULT_USERNAME_MIN_LENGTH);
+    expect(policy.maxLength).toBe(DEFAULT_USERNAME_MAX_LENGTH);
+    expect(() => assertUsernamePolicy("ali")).not.toThrow();
+    expect(() => assertUsernamePolicy("a.b_c-1")).not.toThrow();
+    expect(() => assertUsernamePolicy("ab")).toThrow(UsernamePolicyError);
+    expect(() => assertUsernamePolicy("ali!")).toThrow(UsernamePolicyError);
+  });
+
+  test("extraAllowedChars extends default; allowedChars replaces then extends", () => {
+    expect(() => assertUsernamePolicy("al!ice")).toThrow(/allowedChars/);
+    expect(() => assertUsernamePolicy("al!ice", { extraAllowedChars: "!" })).not.toThrow();
+    expect(() => assertUsernamePolicy("al+ice", { extraAllowedChars: "!" })).toThrow(
+      /allowedChars/,
+    );
+
+    const replaced = resolveUsernamePolicy({
+      allowedChars: "abc",
+      extraAllowedChars: "!",
+    });
+    expect(replaced.allowedChars).toBe("abc!");
+    expect(() =>
+      assertUsernamePolicy("a!b", {
+        allowedChars: "abc",
+        extraAllowedChars: "!",
+        forbidEdgeSymbols: false,
+      }),
+    ).not.toThrow();
+    expect(() =>
+      assertUsernamePolicy("ali", { allowedChars: "abc", extraAllowedChars: "!" }),
+    ).toThrow(/allowedChars/);
+  });
+
+  test("requireLetter / requireNumber / requireSymbol", () => {
+    expect(() => assertUsernamePolicy("12345", { minLength: 3, requireLetter: true })).toThrow(
+      /requireLetter/,
+    );
+    expect(() => assertUsernamePolicy("alice", { minLength: 3, requireNumber: true })).toThrow(
+      /requireNumber/,
+    );
+    expect(() => assertUsernamePolicy("alice1", { minLength: 3, requireSymbol: true })).toThrow(
+      /requireSymbol/,
+    );
+    expect(() =>
+      assertUsernamePolicy("alice.1", {
+        minLength: 3,
+        requireLetter: true,
+        requireNumber: true,
+        requireSymbol: true,
+      }),
+    ).not.toThrow();
+  });
+
+  test("default reserved blocks admin; [] opts out; custom replaces; extraReserved appends", () => {
+    const policy = resolveUsernamePolicy();
+    expect(policy.reserved.size).toBe(DEFAULT_RESERVED_USERNAMES.length);
+    expect(() => assertUsernamePolicy("admin")).toThrow(/reserved/);
+    expect(() => assertUsernamePolicy("anonymous")).toThrow(/reserved/);
+    expect(() => assertUsernamePolicy("admin", { reserved: [] })).not.toThrow();
+    expect(() => assertUsernamePolicy("admin", { reserved: ["brand"] })).not.toThrow();
+    expect(() => assertUsernamePolicy("brand", { reserved: ["Brand"] })).toThrow(/reserved/);
+    expect(() => assertUsernamePolicy("acme", { extraReserved: ["Acme"] })).toThrow(/reserved/);
+    expect(() => assertUsernamePolicy("admin", { extraReserved: ["acme"] })).toThrow(/reserved/);
+    const long = "a".repeat(DEFAULT_USERNAME_MAX_LENGTH + 1);
+    expect(() => assertUsernamePolicy(long)).toThrow(/maxLength/);
+  });
+
+  test("shape rules: edge / consecutive symbols + mustStartWithLetter", () => {
+    expect(() => assertUsernamePolicy(".alice")).toThrow(/forbidEdgeSymbols/);
+    expect(() => assertUsernamePolicy("alice.")).toThrow(/forbidEdgeSymbols/);
+    expect(() => assertUsernamePolicy("ali..ce")).toThrow(/forbidConsecutiveSymbols/);
+    expect(() => assertUsernamePolicy("a.b_c-1")).not.toThrow();
+    expect(() => assertUsernamePolicy(".alice", { forbidEdgeSymbols: false })).not.toThrow();
+    expect(() => assertUsernamePolicy("12345", { mustStartWithLetter: true })).toThrow(
+      /mustStartWithLetter/,
+    );
+    expect(() => assertUsernamePolicy("a2345", { mustStartWithLetter: true })).not.toThrow();
+  });
+
+  test("sign-up rejects default reserved names", async () => {
+    const app = oke({
+      name: "username-default-reserved",
+      env: "test",
+      registry: "ignore",
+      gate: { auth: { secret: "test-secret-at-least-16" } },
+    }).plug(username());
+    await app.boot({ env: "test" });
+
+    const res = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "Admin", password: "CorrectHorse1" }),
+      }),
+    );
+    const body = (await res.json()) as {
+      error: { data?: { reason?: string; reasons?: string[] } };
+    };
+    expect(body.error.data?.reason).toBe("username_policy");
+    expect(body.error.data?.reasons).toContain("reserved");
+
+    await app.stop();
+  });
+
+  test("sign-up returns username_policy / password_policy reasons", async () => {
+    const app = oke({
+      name: "username-policy",
+      env: "test",
+      registry: "ignore",
+      gate: { auth: { secret: "test-secret-at-least-16" } },
+    }).plug(
+      username({
+        usernamePolicy: {
+          minLength: 5,
+          requireLetter: true,
+          requireNumber: true,
+          reserved: ["root"],
+        },
+        passwordPolicy: {
+          minLength: 12,
+          requireLetter: true,
+          requireNumber: true,
+          requireSymbol: true,
+        },
+      }),
+    );
+    await app.boot({ env: "test" });
+
+    const shortName = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "ab", password: "CorrectHorse1!" }),
+      }),
+    );
+    const shortBody = (await shortName.json()) as {
+      error: { data?: { reason?: string; reasons?: string[] } };
+    };
+    expect(shortBody.error.data?.reason).toBe("username_policy");
+    expect(shortBody.error.data?.reasons?.some((r) => r.includes("minLength"))).toBe(true);
+
+    const reserved = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "root", password: "CorrectHorse1!" }),
+      }),
+    );
+    const reservedBody = (await reserved.json()) as {
+      error: { data?: { reason?: string; reasons?: string[] } };
+    };
+    expect(reservedBody.error.data?.reason).toBe("username_policy");
+    expect(reservedBody.error.data?.reasons).toContain("reserved");
+
+    const weakPass = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice1", password: "CorrectHorse1" }),
+      }),
+    );
+    const weakBody = (await weakPass.json()) as {
+      error: { data?: { reason?: string; reasons?: string[] } };
+    };
+    expect(weakBody.error.data?.reason).toBe("password_policy");
+    expect(weakBody.error.data?.reasons).toContain("requireSymbol");
+
+    const ok = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice1", password: "CorrectHorse1!" }),
+      }),
+    );
+    expect(ok.status).toBe(200);
+
+    await app.stop();
+  });
+
+  test("default password policy rejects short passwords on sign-up", async () => {
+    const app = oke({
+      name: "username-default-pw",
+      env: "test",
+      registry: "ignore",
+      gate: { auth: { secret: "test-secret-at-least-16" } },
+    }).plug(username());
+    await app.boot({ env: "test" });
+
+    const res = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "short" }),
+      }),
+    );
+    const body = (await res.json()) as {
+      error: { data?: { reason?: string; reasons?: string[] } };
+    };
+    expect(body.error.data?.reason).toBe("password_policy");
+    expect(body.error.data?.reasons?.some((r) => r.includes("minLength"))).toBe(true);
+
+    await app.stop();
+  });
+
+  test("inherits gate.auth.passwordPolicy when plugin omits passwordPolicy", async () => {
+    const app = oke({
+      name: "username-inherit-pw",
+      env: "test",
+      registry: "ignore",
+      gate: {
+        auth: {
+          secret: "test-secret-at-least-16",
+          passwordPolicy: {
+            minLength: 12,
+            requireLetter: true,
+            requireNumber: true,
+            requireSymbol: true,
+          },
+        },
+      },
+    }).plug(username());
+    await app.boot({ env: "test" });
+
+    const weak = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "CorrectHorse1" }),
+      }),
+    );
+    const weakBody = (await weak.json()) as {
+      error: { data?: { reason?: string; reasons?: string[] } };
+    };
+    expect(weakBody.error.data?.reason).toBe("password_policy");
+    expect(weakBody.error.data?.reasons).toContain("requireSymbol");
+
+    const ok = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "CorrectHorse1!" }),
+      }),
+    );
+    expect(ok.status).toBe(200);
+
+    await app.stop();
+  });
+
+  test("inherits gate.auth.breachCheck on sign-up", async () => {
+    const app = oke({
+      name: "username-inherit-breach",
+      env: "test",
+      registry: "ignore",
+      gate: {
+        auth: {
+          secret: "test-secret-at-least-16",
+          breachCheck: async () => true,
+        },
+      },
+    }).plug(username());
+    await app.boot({ env: "test" });
+
+    const res = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "CorrectHorse1" }),
+      }),
+    );
+    const body = (await res.json()) as {
+      error: { data?: { reason?: string } };
+    };
+    expect(body.error.data?.reason).toBe("password_breached");
+
+    await app.stop();
+  });
+});

package/src/plugins/username.ts

@@ -2,9 +2,17 @@
  * Username + password Gate auth method plugin.
  */
 
-import { createBunCrypto } from "../runtime/primitives.ts";
+import { assertNotBreached, BreachCheckError, type BreachCheckFn } from "../auth/breach-check.ts";
+import { getActiveGateAuthContext } from "../auth/method-context.ts";
+import {
+  assertPasswordPolicy,
+  PasswordPolicyError,
+  type PasswordPolicyOptions,
+} from "../auth/password-policy.ts";
 import { issueSessionWithScopes } from "../auth/sessions.ts";
 import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import { createBunCrypto } from "../runtime/primitives.ts";
+import type { PasswordHashOptions } from "../runtime/types.ts";
 import {
   AuthFailed,
   AuthRateLimited,
@@ -38,14 +46,237 @@ export function createUsernameStore(): UsernameStore {
   return { byUsername: new Map(), byUserId: new Map() };
 }
 
+/** Default allowed charset after normalize (`a-z`, digits, `.`, `_`, `-`). */
+export const DEFAULT_USERNAME_ALLOWED_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789._-" as const;
+
+/** Default minimum username length. */
+export const DEFAULT_USERNAME_MIN_LENGTH = 3;
+
+/** Default maximum username length. */
+export const DEFAULT_USERNAME_MAX_LENGTH = 64;
+
+/**
+ * Default reserved usernames (impersonation + common route collisions).
+ * Pass `reserved: []` to opt out; pass a custom list to replace.
+ * Use {@link UsernamePolicyOptions.extraReserved} to append.
+ */
+export const DEFAULT_RESERVED_USERNAMES = [
+  "admin",
+  "administrator",
+  "root",
+  "system",
+  "support",
+  "api",
+  "auth",
+  "www",
+  "console",
+  "oke",
+  "login",
+  "logout",
+  "signup",
+  "register",
+  "me",
+  "null",
+  "undefined",
+  "anonymous",
+] as const;
+
+/** Options for {@link assertUsernamePolicy}. */
+export interface UsernamePolicyOptions {
+  /** Minimum length after normalize (default 3). */
+  readonly minLength?: number;
+  /** Maximum length after normalize (default 64). */
+  readonly maxLength?: number;
+  /**
+   * Allowed characters after normalize (default `a-z0-9._-`).
+   * Replaces the default set. Prefer {@link extraAllowedChars} to keep
+   * the default and add more.
+   */
+  readonly allowedChars?: string;
+  /**
+   * Characters appended to the base set (`allowedChars` or the default).
+   * Duplicates are ignored.
+   */
+  readonly extraAllowedChars?: string;
+  /** Require at least one letter `a-z` (default false). */
+  readonly requireLetter?: boolean;
+  /** Require at least one digit (default false). */
+  readonly requireNumber?: boolean;
+  /**
+   * Require at least one non-alphanumeric from `allowedChars`
+   * (default false).
+   */
+  readonly requireSymbol?: boolean;
+  /** Require the first character to be `a-z` (default false). */
+  readonly mustStartWithLetter?: boolean;
+  /**
+   * Reject leading or trailing non-alphanumeric characters
+   * (default true).
+   */
+  readonly forbidEdgeSymbols?: boolean;
+  /**
+   * Reject two or more consecutive non-alphanumeric characters
+   * (default true).
+   */
+  readonly forbidConsecutiveSymbols?: boolean;
+  /**
+   * Reserved names (compared after normalize). Defaults to
+   * {@link DEFAULT_RESERVED_USERNAMES}. Pass `[]` to clear the base list;
+   * a non-empty list replaces the default (does not merge). Combine with
+   * {@link extraReserved} to append.
+   */
+  readonly reserved?: readonly string[];
+  /**
+   * Extra reserved names appended after {@link reserved} (or the default).
+   */
+  readonly extraReserved?: readonly string[];
+}
+
+/** Resolved username policy with defaults applied. */
+export interface ResolvedUsernamePolicy {
+  readonly minLength: number;
+  readonly maxLength: number;
+  readonly allowedChars: string;
+  readonly requireLetter: boolean;
+  readonly requireNumber: boolean;
+  readonly requireSymbol: boolean;
+  readonly mustStartWithLetter: boolean;
+  readonly forbidEdgeSymbols: boolean;
+  readonly forbidConsecutiveSymbols: boolean;
+  readonly reserved: ReadonlySet<string>;
+}
+
+/**
+ * Resolve username policy options with defaults.
+ *
+ * @param options - Partial policy
+ */
+export function resolveUsernamePolicy(options: UsernamePolicyOptions = {}): ResolvedUsernamePolicy {
+  const minLength = options.minLength ?? DEFAULT_USERNAME_MIN_LENGTH;
+  const maxLength = options.maxLength ?? DEFAULT_USERNAME_MAX_LENGTH;
+  if (minLength < 1) {
+    throw new RangeError("username policy: minLength must be >= 1");
+  }
+  if (maxLength < minLength) {
+    throw new RangeError("username policy: maxLength must be >= minLength");
+  }
+  const baseChars = options.allowedChars ?? DEFAULT_USERNAME_ALLOWED_CHARS;
+  const allowedChars = mergeAllowedChars(baseChars, options.extraAllowedChars);
+  if (allowedChars.length === 0) {
+    throw new RangeError("username policy: allowedChars must be non-empty");
+  }
+  const baseReserved =
+    options.reserved !== undefined ? options.reserved : DEFAULT_RESERVED_USERNAMES;
+  const reservedNames = [...baseReserved, ...(options.extraReserved ?? [])];
+  return {
+    minLength,
+    maxLength,
+    allowedChars,
+    requireLetter: options.requireLetter ?? false,
+    requireNumber: options.requireNumber ?? false,
+    requireSymbol: options.requireSymbol ?? false,
+    mustStartWithLetter: options.mustStartWithLetter ?? false,
+    forbidEdgeSymbols: options.forbidEdgeSymbols ?? true,
+    forbidConsecutiveSymbols: options.forbidConsecutiveSymbols ?? true,
+    reserved: new Set(reservedNames.map((r) => normalizeUsername(r))),
+  };
+}
+
+/**
+ * Validate a normalized username against policy.
+ * Throws {@link UsernamePolicyError}.
+ *
+ * @param username - Already normalized (`trim` + lowercase)
+ * @param options - Policy (defaults applied)
+ */
+export function assertUsernamePolicy(username: string, options: UsernamePolicyOptions = {}): void {
+  const policy = resolveUsernamePolicy(options);
+  const reasons: string[] = [];
+
+  if (username.length < policy.minLength) {
+    reasons.push(`minLength ${policy.minLength} (got ${username.length})`);
+  }
+  if (username.length > policy.maxLength) {
+    reasons.push(`maxLength ${policy.maxLength} (got ${username.length})`);
+  }
+
+  const allowed = new Set(policy.allowedChars);
+  for (const ch of username) {
+    if (!allowed.has(ch)) {
+      reasons.push("allowedChars");
+      break;
+    }
+  }
+
+  if (policy.requireLetter && !/[a-z]/.test(username)) {
+    reasons.push("requireLetter");
+  }
+  if (policy.requireNumber && !/\d/.test(username)) {
+    reasons.push("requireNumber");
+  }
+  if (policy.requireSymbol && !/[^a-z0-9]/.test(username)) {
+    reasons.push("requireSymbol");
+  }
+  if (policy.mustStartWithLetter && !/^[a-z]/.test(username)) {
+    reasons.push("mustStartWithLetter");
+  }
+  if (policy.forbidEdgeSymbols && username.length > 0) {
+    if (/^[^a-z0-9]/.test(username) || /[^a-z0-9]$/.test(username)) {
+      reasons.push("forbidEdgeSymbols");
+    }
+  }
+  if (policy.forbidConsecutiveSymbols && /[^a-z0-9]{2,}/.test(username)) {
+    reasons.push("forbidConsecutiveSymbols");
+  }
+  if (policy.reserved.has(username)) {
+    reasons.push("reserved");
+  }
+
+  if (reasons.length > 0) {
+    throw new UsernamePolicyError(reasons);
+  }
+}
+
+/** Username failed policy checks. */
+export class UsernamePolicyError extends Error {
+  readonly reasons: readonly string[];
+
+  constructor(reasons: readonly string[]) {
+    super(`username policy failed: ${reasons.join(", ")}`);
+    this.name = "UsernamePolicyError";
+    this.reasons = reasons;
+  }
+}
+
 /** Options for {@link username}. */
 export interface UsernamePluginOptions extends AuthMethodOptions {
   /** Shared username credential store. */
   readonly usernames?: UsernameStore;
+  /**
+   * Username length / charset / character-class / shape policy
+   * (defaults: 3–64 chars from `a-z0-9._-`, edge + consecutive symbols forbidden).
+   */
+  readonly usernamePolicy?: UsernamePolicyOptions;
+  /**
+   * Password length / character-class policy on sign-up.
+   * Defaults to `gate.auth.passwordPolicy` when plugged after `oke()`,
+   * else the same secure defaults (minLength 12, letter + number).
+   */
+  readonly passwordPolicy?: PasswordPolicyOptions;
+  /**
+   * Bun.password cost knobs. Defaults to `gate.auth.password`, else
+   * `{ algorithm: "argon2id" }`.
+   */
+  readonly password?: PasswordHashOptions;
+  /**
+   * Optional breach check (`true` = reject). Defaults to
+   * `gate.auth.breachCheck` when plugged after `oke()`.
+   */
+  readonly breachCheck?: BreachCheckFn;
 }
 
 const UsernameIn = z.object({
-  username: z.string().min(3).max(64),
+  username: z.string().min(1).max(256),
   password: z.string().min(1),
 });
 
@@ -53,14 +284,39 @@ function normalizeUsername(raw: string): string {
   return raw.trim().toLowerCase();
 }
 
+/**
+ * Merge base charset with extras, preserving first-seen order.
+ *
+ * @param base - Base allowed characters
+ * @param extra - Optional characters to append
+ */
+function mergeAllowedChars(base: string, extra?: string): string {
+  if (!extra || extra.length === 0) return base;
+  const seen = new Set<string>();
+  let out = "";
+  for (const ch of base + extra) {
+    if (seen.has(ch)) continue;
+    seen.add(ch);
+    out += ch;
+  }
+  return out;
+}
+
 /**
  * Username + password sign-up / sign-in (`oke_usernames`).
  *
- * @param opts - Secret / session / store overrides
+ * @param opts - Secret / session / store / policy overrides
  */
 export function username(opts: UsernamePluginOptions = {}): PluginDef {
   const runtime = createMethodRuntime(opts);
+  const active = getActiveGateAuthContext();
   const usernames = opts.usernames ?? createUsernameStore();
+  const usernamePolicy = opts.usernamePolicy ?? {};
+  const passwordPolicy = opts.passwordPolicy ?? active?.passwordPolicy ?? {};
+  const passwordHash = opts.password ?? active?.password ?? { algorithm: "argon2id" };
+  const breachCheck = opts.breachCheck ?? active?.breachCheck;
+  // Resolve once at plug-time so bad config fails early.
+  resolveUsernamePolicy(usernamePolicy);
   const crypto = createBunCrypto();
 
   const signUp = flow({
@@ -72,20 +328,45 @@ export function username(opts: UsernamePluginOptions = {}): PluginDef {
     errors: { AuthFailed, AuthRateLimited },
     do: async (input) => {
       const key = normalizeUsername(input.username);
-      if (!/^[a-z0-9._-]{3,64}$/.test(key)) {
-        return fail("AuthFailed", { reason: "invalid_credentials" });
+      try {
+        assertUsernamePolicy(key, usernamePolicy);
+      } catch (err) {
+        if (err instanceof UsernamePolicyError) {
+          return fail("AuthFailed", {
+            reason: "username_policy",
+            reasons: [...err.reasons],
+          });
+        }
+        throw err;
+      }
+      try {
+        assertPasswordPolicy(input.password, passwordPolicy);
+      } catch (err) {
+        if (err instanceof PasswordPolicyError) {
+          return fail("AuthFailed", {
+            reason: "password_policy",
+            reasons: [...err.reasons],
+          });
+        }
+        throw err;
+      }
+      try {
+        await assertNotBreached(input.password, breachCheck);
+      } catch (err) {
+        if (err instanceof BreachCheckError) {
+          return fail("AuthFailed", { reason: "password_breached" });
+        }
+        throw err;
       }
       if (usernames.byUsername.has(key)) {
         return fail("AuthFailed", { reason: "invalid_credentials" });
       }
       const userId = crypto.randomUUID();
-      const passwordHash = await crypto.hashPassword(input.password, {
-        algorithm: "argon2id",
-      });
+      const passwordHashValue = await crypto.hashPassword(input.password, passwordHash);
       const row: UsernameRow = {
         userId,
         username: key,
-        passwordHash,
+        passwordHash: passwordHashValue,
         createdAt: runtime.now(),
       };
       usernames.byUsername.set(key, row);