@bajustone/fortress 1.0.0-rc.1

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

@@ -0,0 +1,220 @@
+import { Errors } from '../errors';
+import { createOutboundClient } from '../http/outbound';
+import { normalizePasswordInput } from './password';
+
+export type PasswordBreachFailureMode = 'open' | 'closed';
+
+export interface PasswordBreachDegradedEvent {
+  failureMode: PasswordBreachFailureMode;
+  status?: number;
+  error?: unknown;
+}
+
+/** Called whenever the HIBP control is unavailable, regardless of failure mode. */
+export type PasswordPolicyObserver = (event: PasswordBreachDegradedEvent) => void;
+
+export interface PasswordPolicyConfig {
+  /** Minimum password length. Default: 15 (NIST 800-63B). */
+  minLength?: number;
+  /** Maximum password length. Default: 128 (NIST 800-63B). */
+  maxLength?: number;
+  /** Check password against HIBP breached password database via k-anonymity API. Default: false. */
+  checkBreached?: boolean;
+  /** Cache TTL for HIBP range responses in milliseconds. Default: 86400000 (24h). */
+  breachedCacheTtlMs?: number;
+  /** Maximum cached HIBP range responses. Default: 1000. Set to 0 to disable caching. */
+  breachedCacheMaxEntries?: number;
+  /** Whether HIBP unavailability permits password writes. Default: 'open'. */
+  breachedFailureMode?: PasswordBreachFailureMode;
+}
+
+type HibpCache = Map<string, { data: string; expiresAt: number }>;
+
+export interface PasswordBreachCheckOptions {
+  cacheTtlMs?: number;
+  cacheMaxEntries?: number;
+  failureMode?: PasswordBreachFailureMode;
+  observer?: PasswordPolicyObserver;
+  /** Internal per-Fortress-instance cache supplied by validatePassword. */
+  cache?: HibpCache;
+}
+
+const DEFAULT_MIN_LENGTH = 15;
+const DEFAULT_MAX_LENGTH = 128;
+const DEFAULT_CACHE_TTL_MS = 86_400_000; // 24 hours
+const DEFAULT_CACHE_MAX_ENTRIES = 1_000;
+// Tighter timeout than the default outbound budget: the breach check runs in
+// the password-validation hot path, so a slow HIBP must not stall writes.
+const HIBP_TIMEOUT_MS = 6_000;
+const hibpOutboundClient = createOutboundClient(HIBP_TIMEOUT_MS);
+
+// Direct isPasswordBreached callers share this convenience cache. Fortress
+// instances use a cache keyed by their own PasswordPolicyConfig object so one
+// tenant's bound/eviction policy cannot mutate a co-resident instance's cache.
+const directHibpCache: HibpCache = new Map();
+const policyCaches = new WeakMap<PasswordPolicyConfig, HibpCache>();
+const knownCaches = new Set<HibpCache>([directHibpCache]);
+
+function cacheForPolicy(config: PasswordPolicyConfig): HibpCache {
+  let cache = policyCaches.get(config);
+  if (!cache) {
+    cache = new Map();
+    policyCaches.set(config, cache);
+    knownCaches.add(cache);
+  }
+  return cache;
+}
+
+/**
+ * Validate a password against the configured policy.
+ * Throws `Errors.badRequest()` if the password does not meet requirements.
+ */
+export async function validatePassword(
+  password: string,
+  config: PasswordPolicyConfig = {},
+  observer?: PasswordPolicyObserver,
+): Promise<void> {
+  const normalizedPassword = normalizePasswordInput(password);
+  const minLength = config.minLength ?? DEFAULT_MIN_LENGTH;
+  const maxLength = config.maxLength ?? DEFAULT_MAX_LENGTH;
+  if (!Number.isInteger(minLength) || minLength <= 0)
+    throw Errors.badRequest('passwordPolicy.minLength must be a positive integer');
+  if (!Number.isInteger(maxLength) || maxLength <= 0)
+    throw Errors.badRequest('passwordPolicy.maxLength must be a positive integer');
+  if (minLength > maxLength)
+    throw Errors.badRequest('passwordPolicy.minLength cannot exceed maxLength');
+
+  if (normalizedPassword.length < minLength) {
+    throw Errors.badRequest(`Password must be at least ${minLength} characters`);
+  }
+
+  if (normalizedPassword.length > maxLength) {
+    throw Errors.badRequest(`Password must be at most ${maxLength} characters`);
+  }
+
+  if (config.checkBreached) {
+    const breached = await isPasswordBreached(normalizedPassword, {
+      cacheTtlMs: config.breachedCacheTtlMs,
+      cacheMaxEntries: config.breachedCacheMaxEntries,
+      failureMode: config.breachedFailureMode,
+      observer,
+      cache: cacheForPolicy(config),
+    });
+    if (breached) {
+      throw Errors.badRequest('This password has appeared in a data breach and cannot be used');
+    }
+  }
+}
+
+function rememberRange(cache: HibpCache, prefix: string, data: string, expiresAt: number, maxEntries: number): void {
+  if (maxEntries <= 0)
+    return;
+
+  cache.delete(prefix);
+  while (cache.size >= maxEntries) {
+    const oldest = cache.keys().next().value as string | undefined;
+    if (oldest === undefined)
+      break;
+    cache.delete(oldest);
+  }
+  cache.set(prefix, { data, expiresAt });
+}
+
+function handleDegradedCheck(
+  options: PasswordBreachCheckOptions,
+  details: { status?: number; error?: unknown },
+): false {
+  const failureMode = options.failureMode ?? 'open';
+  options.observer?.({ failureMode, ...details });
+
+  // Direct callers may not provide an observer. Keep degraded controls visible
+  // rather than silently failing open/closed.
+  if (!options.observer) {
+    const reason = details.status !== undefined
+      ? `HTTP ${details.status}`
+      : details.error instanceof Error ? details.error.message : String(details.error);
+    console.warn(`[fortress/password-policy] HIBP range API unavailable (${reason}); failing ${failureMode}.`);
+  }
+
+  if (failureMode === 'closed') {
+    throw Errors.serviceUnavailable('Password breach check unavailable', { cause: details.error });
+  }
+  return false;
+}
+
+/**
+ * Check if a password appears in the Have I Been Pwned breached password database
+ * using the k-anonymity API (only the first 5 characters of the SHA-1 hash are sent).
+ */
+export async function isPasswordBreached(
+  password: string,
+  options: PasswordBreachCheckOptions = {},
+): Promise<boolean> {
+  const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  const cacheMaxEntries = options.cacheMaxEntries ?? DEFAULT_CACHE_MAX_ENTRIES;
+  const hibpCache = options.cache ?? directHibpCache;
+  if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0)
+    throw Errors.badRequest('passwordPolicy.breachedCacheTtlMs must be a non-negative number');
+  if (!Number.isInteger(cacheMaxEntries) || cacheMaxEntries < 0)
+    throw Errors.badRequest('passwordPolicy.breachedCacheMaxEntries must be a non-negative integer');
+  if (options.failureMode !== undefined && options.failureMode !== 'open' && options.failureMode !== 'closed')
+    throw Errors.badRequest('passwordPolicy.breachedFailureMode must be \'open\' or \'closed\'');
+
+  // SHA-1 hash of the canonical password form.
+  const encoded = new TextEncoder().encode(normalizePasswordInput(password));
+  const hashBuffer = await crypto.subtle.digest('SHA-1', encoded);
+  const hashHex = Array.from(new Uint8Array(hashBuffer))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('')
+    .toUpperCase();
+
+  const prefix = hashHex.slice(0, 5);
+  const suffix = hashHex.slice(5);
+
+  // Enforce the active caller's bound before reading as well as writing. This
+  // makes `0` a real cache bypass and lets deployments safely lower a bound.
+  while (hibpCache.size > cacheMaxEntries) {
+    const oldest = hibpCache.keys().next().value as string | undefined;
+    if (oldest === undefined)
+      break;
+    hibpCache.delete(oldest);
+  }
+
+  const cached = cacheMaxEntries > 0 ? hibpCache.get(prefix) : undefined;
+  if (cached && cached.expiresAt > Date.now()) {
+    // Touch the entry so Map insertion order remains LRU order.
+    hibpCache.delete(prefix);
+    hibpCache.set(prefix, cached);
+    return cached.data.includes(suffix);
+  }
+  if (cached)
+    hibpCache.delete(prefix);
+
+  let response: Response;
+  try {
+    response = await hibpOutboundClient.get(`https://api.pwnedpasswords.com/range/${prefix}`, {
+      headers: { 'Add-Padding': 'true' },
+    });
+  }
+  catch (error) {
+    return handleDegradedCheck(options, { error });
+  }
+
+  if (!response.ok)
+    return handleDegradedCheck(options, { status: response.status });
+
+  try {
+    const data = await response.text();
+    rememberRange(hibpCache, prefix, data, Date.now() + cacheTtlMs, cacheMaxEntries);
+    return data.includes(suffix);
+  }
+  catch (error) {
+    return handleDegradedCheck(options, { error });
+  }
+}
+
+/** Clear the HIBP cache. Useful for testing. */
+export function clearHibpCache(): void {
+  for (const cache of knownCaches)
+    cache.clear();
+}

package/src/core/auth/password.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { createDefaultHasher } from './password';
+
+describe('defaultHasher', () => {
+  const hasher = createDefaultHasher();
+
+  it('hashes a password and returns an encoded string', async () => {
+    const hash = await hasher.hash('my-password');
+    expect(hash).toBeTruthy();
+    expect(hash).toContain('$argon2id$');
+  });
+
+  it('produces different hashes for the same password (random salt)', async () => {
+    const hash1 = await hasher.hash('same-password');
+    const hash2 = await hasher.hash('same-password');
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('verifies a correct password', async () => {
+    const hash = await hasher.hash('correct-password');
+    const result = await hasher.verify(hash, 'correct-password');
+    expect(result).toBe(true);
+  });
+
+  it('normalizes password input with NFKC before hashing and verifying', async () => {
+    const hash = await hasher.hash('Password123!');
+    const result = await hasher.verify(hash, 'Ｐａｓｓｗｏｒｄ１２３！');
+    expect(result).toBe(true);
+  });
+
+  it('rejects an incorrect password', async () => {
+    const hash = await hasher.hash('correct-password');
+    const result = await hasher.verify(hash, 'wrong-password');
+    expect(result).toBe(false);
+  });
+
+  it('returns false for malformed hash instead of throwing', async () => {
+    const result = await hasher.verify('not-a-valid-hash', 'any-password');
+    expect(result).toBe(false);
+  });
+});

package/src/core/auth/password.ts

@@ -0,0 +1,62 @@
+/**
+ * Password hashing primitives for fortress.
+ *
+ * Exports {@link createDefaultHasher}, a WASM-based Argon2id `PasswordHasher`
+ * that works across every runtime fortress targets (Bun, Deno, Node, Cloudflare
+ * Workers, Vercel Edge). Consumers can drop in a faster native hasher
+ * (`@node-rs/argon2`, `Bun.password`) by implementing the `PasswordHasher`
+ * contract and passing it to `createFortress({ passwordHasher })`.
+ *
+ * @module
+ */
+
+import { argon2id, argon2Verify } from 'hash-wasm';
+
+export type { PasswordHasher } from '../config';
+
+/**
+ * Canonicalize password input before policy checks, breach checks, hashing,
+ * and verification. NFKC collapses visually/confusably equivalent Unicode
+ * forms (for example full-width ASCII) so users are not locked out by input
+ * method differences.
+ */
+export function normalizePasswordInput(password: string): string {
+  return password.normalize('NFKC');
+}
+
+/**
+ * Default PasswordHasher using WASM-based Argon2id.
+ * Works across all runtimes (Bun, Deno, Node, edge).
+ * Consumers can swap for @node-rs/argon2 or Bun.password for native speed.
+ */
+export function createDefaultHasher(): {
+  hash: (password: string) => Promise<string>;
+  verify: (hash: string, password: string) => Promise<boolean>;
+} {
+  return {
+    async hash(password: string): Promise<string> {
+      const normalizedPassword = normalizePasswordInput(password);
+      const salt = new Uint8Array(16);
+      crypto.getRandomValues(salt);
+
+      return argon2id({
+        password: normalizedPassword,
+        salt,
+        parallelism: 1,
+        iterations: 3,
+        memorySize: 65536, // 64 MB
+        hashLength: 32,
+        outputType: 'encoded',
+      });
+    },
+
+    async verify(hash: string, password: string): Promise<boolean> {
+      try {
+        return await argon2Verify({ hash, password: normalizePasswordInput(password) });
+      }
+      catch {
+        return false;
+      }
+    },
+  };
+}

package/src/core/auth/post-auth-gate.test.ts

@@ -0,0 +1,258 @@
+import type { FortressPlugin } from '../plugin';
+import type { AuthEvent } from './auth-service';
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { Errors } from '../errors';
+import { createFortress } from '../fortress';
+
+const SECRET = 'post-auth-gate-test-secret-32chars';
+
+function factorPlugin(
+  name: string,
+  reason: 'two-factor' | 'webauthn',
+  expectedCompletion: string,
+  onVerify?: () => void,
+  policy?: { maxAttempts?: number; cooldownSeconds?: number },
+): FortressPlugin {
+  return {
+    name,
+    hooks: {
+      postAuthGate: {
+        reason,
+        ...policy,
+        async evaluate() {
+          return { pluginData: { factor: reason } };
+        },
+        async verify(_ctx, completion) {
+          onVerify?.();
+          if (completion !== expectedCompletion)
+            throw Errors.unauthorized('Invalid factor proof');
+        },
+      },
+    },
+    methods: ctx => ({
+      async verify(continuationToken: string, completion: string) {
+        return ctx.auth!.completePendingAuth(continuationToken, completion);
+      },
+    }),
+  };
+}
+
+async function seedUser(fortress: ReturnType<typeof createFortress>): Promise<void> {
+  await fortress.auth.createUser({
+    email: 'gated@example.com',
+    name: 'Gated User',
+    password: 'password-123456',
+  });
+}
+
+describe('post-auth gate', () => {
+  it('holds before token issuance and completes exactly once', async () => {
+    const database = createTestAdapter();
+    let afterLoginCalls = 0;
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database,
+      plugins: [
+        {
+          name: 'observer',
+          hooks: {
+            afterLogin: async (_ctx, result) => {
+              afterLoginCalls++;
+              return result;
+            },
+          },
+        },
+        factorPlugin('factor', 'two-factor', '123456', undefined, { cooldownSeconds: 0 }),
+      ],
+    });
+    await seedUser(fortress);
+    const events: AuthEvent[] = [];
+    fortress.auth.addAuthObserver(event => void events.push(event));
+
+    const pending = await fortress.auth.login('gated@example.com', 'password-123456');
+    expect(pending).toMatchObject({
+      status: 'pending',
+      pending: { reason: 'two-factor' },
+      pluginData: { factor: 'two-factor' },
+    });
+    expect(await database.count({ model: 'refresh_token' })).toBe(0);
+    expect(await database.count({ model: 'auth_continuation' })).toBe(1);
+    const storedContinuation = await database.findOne<{ tokenHash: string }>({
+      model: 'auth_continuation',
+      where: [{ field: 'userId', operator: '=', value: pending.user.id }],
+    });
+    expect(events.map(event => event.eventType)).toContain('LOGIN_PENDING');
+    expect(events.map(event => event.eventType)).not.toContain('LOGIN_SUCCESS');
+    expect(afterLoginCalls).toBe(0);
+
+    if (pending.status !== 'pending' || !pending.pending)
+      throw new Error('Expected pending auth challenge');
+    expect(storedContinuation?.tokenHash).not.toBe(pending.pending.continuationToken);
+
+    await expect(
+      fortress.auth.completePendingAuth(pending.pending.continuationToken, 'wrong'),
+    ).rejects.toThrow('Invalid factor proof');
+    expect(events.some(event => event.eventType === 'MFA_VERIFY_FAILURE' && event.method === '2fa')).toBe(true);
+    expect(await database.count({
+      model: 'auth_continuation',
+      where: [{ field: 'consumedAt', operator: 'isNull', value: null }],
+    })).toBe(1);
+
+    const completed = await fortress.auth.completePendingAuth(
+      pending.pending.continuationToken,
+      '123456',
+    );
+    expect(completed).toMatchObject({
+      status: 'success',
+      method: 'two-factor',
+      user: { email: 'gated@example.com' },
+    });
+    if (completed.status !== 'success')
+      throw new Error('Expected completed authentication');
+    expect(completed.accessToken).toBeTruthy();
+    expect(completed.refreshToken).toBeTruthy();
+    expect('passwordHash' in completed.user).toBe(false);
+    expect(await database.count({ model: 'refresh_token' })).toBe(1);
+    expect(events.some(event => event.eventType === 'MFA_VERIFY_SUCCESS' && event.method === '2fa')).toBe(true);
+    expect(events.some(event => event.eventType === 'LOGIN_SUCCESS' && event.method === '2fa')).toBe(true);
+    expect(afterLoginCalls).toBe(1);
+
+    await expect(
+      fortress.auth.completePendingAuth(pending.pending.continuationToken, '123456'),
+    ).rejects.toThrow('Invalid or expired auth continuation');
+    expect(await database.count({ model: 'refresh_token' })).toBe(1);
+  });
+
+  it('durably caps concurrent rejected proofs at the continuation attempt limit', async () => {
+    const database = createTestAdapter();
+    let verificationCalls = 0;
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database,
+      plugins: [factorPlugin(
+        'factor',
+        'two-factor',
+        'correct',
+        () => verificationCalls++,
+        { maxAttempts: 3, cooldownSeconds: 0 },
+      )],
+    });
+    await seedUser(fortress);
+
+    const pending = await fortress.auth.login('gated@example.com', 'password-123456');
+    if (pending.status !== 'pending' || !pending.pending)
+      throw new Error('Expected pending auth challenge');
+
+    const results = await Promise.allSettled(
+      Array.from({ length: 20 }, () =>
+        fortress.auth.completePendingAuth(pending.pending!.continuationToken, 'wrong')),
+    );
+    expect(results.every(result => result.status === 'rejected')).toBe(true);
+    expect(verificationCalls).toBe(3);
+
+    const continuation = await database.findOne<{
+      failedAttempts: number;
+      invalidatedAt: Date | null;
+      consumedAt: Date | null;
+    }>({
+      model: 'auth_continuation',
+      where: [{ field: 'userId', operator: '=', value: pending.user.id }],
+    });
+    expect(continuation).toMatchObject({ failedAttempts: 3, consumedAt: null });
+    expect(continuation?.invalidatedAt).toBeInstanceOf(Date);
+  });
+
+  it('reruns remaining gates after one factor completes', async () => {
+    const database = createTestAdapter();
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database,
+      plugins: [
+        factorPlugin('totp', 'two-factor', 'totp-ok'),
+        factorPlugin('passkey', 'webauthn', 'passkey-ok'),
+      ],
+    });
+    await seedUser(fortress);
+
+    const first = await fortress.auth.login('gated@example.com', 'password-123456');
+    if (first.status !== 'pending' || !first.pending)
+      throw new Error('Expected first pending auth challenge');
+    expect(first.pending.reason).toBe('two-factor');
+
+    const second = await fortress.auth.completePendingAuth(first.pending.continuationToken, 'totp-ok');
+    if (second.status !== 'pending' || !second.pending)
+      throw new Error('Expected second pending auth challenge');
+    expect(second.pending.reason).toBe('webauthn');
+    expect(await database.count({ model: 'refresh_token' })).toBe(0);
+
+    const completed = await fortress.auth.completePendingAuth(second.pending.continuationToken, 'passkey-ok');
+    expect(completed.status).toBe('success');
+    expect(await database.count({ model: 'refresh_token' })).toBe(1);
+  });
+
+  it('exposes pending and completion through the frozen HTTP wire without premature token fields', async () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [factorPlugin('two-factor', 'two-factor', '123456')],
+    });
+    await seedUser(fortress);
+
+    const loginResponse = await fortress.handleRequest(new Request('http://localhost/auth/login', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ identifier: 'gated@example.com', password: 'password-123456' }),
+    }));
+    const pending = await loginResponse.json() as {
+      pending: { continuationToken: string; reason: string };
+      [key: string]: unknown;
+    };
+    expect(pending).toMatchObject({
+      status: 'pending',
+      pending: { reason: 'two-factor' },
+    });
+    expect(pending).not.toHaveProperty('accessToken');
+    expect(pending).not.toHaveProperty('refreshToken');
+    expect(loginResponse.headers.getSetCookie()).toHaveLength(0);
+
+    const completedResponse = await fortress.handleRequest(new Request('http://localhost/auth/2fa/verify', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        continuationToken: pending.pending.continuationToken,
+        code: '123456',
+      }),
+    }));
+    expect(completedResponse.status).toBe(200);
+    const completed = await completedResponse.json() as Record<string, unknown>;
+    expect(completed).toMatchObject({ status: 'success', method: 'two-factor' });
+    expect(completed.accessToken).toEqual(expect.any(String));
+    expect(completed.refreshToken).toEqual(expect.any(String));
+    expect(completedResponse.headers.getSetCookie().length).toBeGreaterThan(0);
+  });
+
+  it('allows only one concurrent completion to issue a session', async () => {
+    const database = createTestAdapter();
+    let verifyCalls = 0;
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database,
+      plugins: [factorPlugin('factor', 'two-factor', 'ok', () => verifyCalls++)],
+    });
+    await seedUser(fortress);
+
+    const pending = await fortress.auth.login('gated@example.com', 'password-123456');
+    if (pending.status !== 'pending' || !pending.pending)
+      throw new Error('Expected pending auth challenge');
+
+    const results = await Promise.allSettled([
+      fortress.auth.completePendingAuth(pending.pending.continuationToken, 'ok'),
+      fortress.auth.completePendingAuth(pending.pending.continuationToken, 'ok'),
+    ]);
+    expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1);
+    expect(results.filter(result => result.status === 'rejected')).toHaveLength(1);
+    expect(verifyCalls).toBe(1);
+    expect(await database.count({ model: 'refresh_token' })).toBe(1);
+  });
+});