@bajustone/fortress 1.0.0-rc.1

package/src/core/auth/jwt.ts

@@ -0,0 +1,239 @@
+/**
+ * JWT signing and verification helpers built on `jose` (Web Crypto API).
+ *
+ * Provides {@link signAccessToken} and {@link verifyAccessToken} for short-lived
+ * access tokens. Refresh tokens are handled separately in
+ * `core/auth/refresh-token.ts`. Supports key rotation by accepting an array
+ * of keys — the first is used to sign, all are accepted on verify.
+ *
+ * @module
+ */
+
+import type { JWTVerifyOptions } from 'jose';
+import type { SubjectType, TokenClaims } from '../types';
+
+import { jwtVerify, SignJWT } from 'jose';
+import { Errors } from '../errors';
+
+/**
+ * Key material accepted by {@link signAccessToken} / {@link verifyAccessToken}.
+ *
+ * Today this is just an HS256 shared secret (string) or a rotation array of
+ * shared secrets. The alias exists so the public signature is stable when we
+ * expand to asymmetric algorithms (RS256 / EdDSA) and JWKS-backed verification.
+ *
+ * Expected expansion:
+ *
+ * ```ts
+ * import type { CryptoKey, JWK, JWTVerifyGetKey, KeyObject } from 'jose';
+ *
+ * export type JwtStaticKey =
+ *   | string        // HS* shared secret (utf-8)
+ *   | Uint8Array    // HS* shared secret (raw bytes)
+ *   | CryptoKey     // Web Crypto key (any alg)
+ *   | KeyObject     // Node KeyObject (any alg)
+ *   | JWK;          // JSON Web Key
+ *
+ * export type JwtKeyMaterial = JwtStaticKey | readonly JwtStaticKey[];
+ *
+ * // Verification additionally accepts a resolver (e.g. createRemoteJWKSet):
+ * export type JwtVerifyKeyMaterial = JwtKeyMaterial | JWTVerifyGetKey;
+ * ```
+ *
+ * Until then, the runtime helpers ({@link normalizeKeys}) only know how to
+ * encode strings — widening the type without widening the helpers would be a
+ * lie, so do both together.
+ */
+export type JwtKeyMaterial = string | string[];
+
+/**
+ * JWT claim names fortress controls and that must never be overridable by
+ * caller-supplied `customClaims` or by plugin `enrichTokenClaims` output.
+ *
+ * Letting a caller set `act` would forge an impersonation marker; letting a
+ * caller set `sub`/`iss`/`exp` would let them mint a token for any subject
+ * or extend its lifetime. The denylist is enforced in {@link signAccessToken}
+ * — extra claims are dropped (with a `warn` log in dev) before the safe
+ * claims are spread.
+ */
+export const RESERVED_JWT_CLAIMS: ReadonlySet<string> = new Set([
+  'sub',
+  'iss',
+  'iat',
+  'exp',
+  'nbf',
+  'aud',
+  'jti',
+  'act',
+  'groups',
+  'subjectType',
+  'name',
+]);
+
+export interface SignAccessTokenOptions {
+  /** Audience to include in the JWT `aud` claim. Omitted when unset. */
+  audience?: string | string[];
+}
+
+export interface VerifyAccessTokenOptions {
+  /** Expected issuer. When set, jose also requires the `iss` claim to be present. */
+  issuer?: string | string[];
+  /** Expected audience. When set, jose also requires the `aud` claim to be present. */
+  audience?: string | string[];
+  /** Clock skew tolerance for `nbf`, `exp`, and max-token-age checks. */
+  clockTolerance?: string | number;
+  /** Additional claim names that must be present alongside Fortress's required access-token claims. */
+  requiredClaims?: string[];
+}
+
+const REQUIRED_ACCESS_TOKEN_CLAIMS = ['sub', 'subjectType', 'name', 'groups', 'iss', 'iat', 'exp'] as const;
+const SUBJECT_TYPES: readonly SubjectType[] = ['USER', 'GROUP', 'SERVICE_ACCOUNT'];
+
+/**
+ * Strip any reserved keys from a custom-claims object. In development we
+ * log a warning so library users notice the collision; in production we
+ * silently drop (the safe default — a misbehaving plugin shouldn't be able
+ * to break token issuance).
+ */
+export function stripReservedClaims(
+  claims: Record<string, unknown> | undefined,
+  context: string,
+): Record<string, unknown> {
+  if (!claims)
+    return {};
+  const out: Record<string, unknown> = {};
+  let stripped: string[] | undefined;
+  for (const [key, value] of Object.entries(claims)) {
+    if (RESERVED_JWT_CLAIMS.has(key)) {
+      (stripped ??= []).push(key);
+      continue;
+    }
+    out[key] = value;
+  }
+  if (stripped && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+    console.warn(`[fortress/jwt] dropping reserved claim(s) from ${context}: ${stripped.join(', ')}`);
+  }
+  return out;
+}
+
+/**
+ * Encode a shared-secret string to Uint8Array for jose.
+ */
+function encodeSecret(secret: string): Uint8Array {
+  return new TextEncoder().encode(secret);
+}
+
+/**
+ * Normalize key material to an array of encoded keys.
+ * First entry is used for signing, all are used for verification.
+ */
+function normalizeKeys(key: JwtKeyMaterial): Uint8Array[] {
+  const keys = Array.isArray(key) ? key : [key];
+  return keys.map(encodeSecret);
+}
+
+/**
+ * Sign a JWT access token.
+ */
+export async function signAccessToken(
+  claims: Omit<TokenClaims, 'iat' | 'exp' | 'aud'>,
+  key: JwtKeyMaterial,
+  expiresInSeconds: number,
+  options?: SignAccessTokenOptions,
+): Promise<string> {
+  const [signingKey] = normalizeKeys(key);
+
+  // Strip reserved claim names from customClaims before spreading — a caller
+  // (or a plugin contributing via enrichTokenClaims) MUST NOT be able to
+  // overwrite `act`, `sub`, `groups`, etc. (See RESERVED_JWT_CLAIMS.)
+  const safeCustom = stripReservedClaims(claims.customClaims, 'signAccessToken.customClaims');
+
+  let jwt = new SignJWT({
+    name: claims.name,
+    subjectType: claims.subjectType,
+    groups: claims.groups,
+    ...(claims.act ? { act: claims.act } : {}),
+    ...safeCustom,
+  })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(`${expiresInSeconds}s`)
+    .setIssuer(claims.iss);
+  if (options?.audience !== undefined)
+    jwt = jwt.setAudience(options.audience);
+  return jwt.setSubject(claims.sub).sign(signingKey);
+}
+
+/**
+ * Verify a JWT access token. Tries each key in order for rotation support.
+ *
+ * Pins `alg: HS256` and (when supplied) the expected `issuer`. jose already
+ * rejects `alg: none` by default; the explicit allowlist is defense in
+ * depth against future jose behavioural drift and against confused-deputy
+ * attacks if anyone later adds asymmetric key support.
+ */
+export async function verifyAccessToken(
+  token: string,
+  key: JwtKeyMaterial,
+  options?: VerifyAccessTokenOptions,
+): Promise<TokenClaims> {
+  const keys = normalizeKeys(key);
+  const requiredClaims = [...new Set([...REQUIRED_ACCESS_TOKEN_CLAIMS, ...(options?.requiredClaims ?? [])])];
+  const verifyOptions: JWTVerifyOptions = { algorithms: ['HS256'], requiredClaims };
+  if (options?.issuer)
+    verifyOptions.issuer = options.issuer;
+  if (options?.audience)
+    verifyOptions.audience = options.audience;
+  if (options?.clockTolerance !== undefined)
+    verifyOptions.clockTolerance = options.clockTolerance;
+
+  for (const candidate of keys) {
+    try {
+      const { payload } = await jwtVerify(token, candidate, verifyOptions);
+      const subjectType = payload.subjectType;
+      const groups = payload.groups;
+      const name = payload.name;
+      const issuer = payload.iss;
+      const audience = payload.aud;
+      const issuedAt = payload.iat;
+      const expiresAt = payload.exp;
+
+      if (typeof payload.sub !== 'string' || payload.sub.length === 0)
+        throw new Error('Invalid sub claim');
+      if (typeof subjectType !== 'string' || !SUBJECT_TYPES.includes(subjectType as SubjectType))
+        throw new Error('Invalid subjectType claim');
+      if (typeof name !== 'string')
+        throw new Error('Invalid name claim');
+      if (!Array.isArray(groups) || !groups.every(group => typeof group === 'string'))
+        throw new Error('Invalid groups claim');
+      if (typeof issuer !== 'string' || issuer.length === 0)
+        throw new Error('Invalid iss claim');
+      if (audience !== undefined && (!Array.isArray(audience) || !audience.every(value => typeof value === 'string')) && typeof audience !== 'string')
+        throw new Error('Invalid aud claim');
+      if (typeof issuedAt !== 'number')
+        throw new Error('Invalid iat claim');
+      if (typeof expiresAt !== 'number')
+        throw new Error('Invalid exp claim');
+
+      return {
+        sub: payload.sub,
+        subjectType: subjectType as SubjectType,
+        name,
+        groups,
+        iss: issuer,
+        ...(audience !== undefined ? { aud: audience } : {}),
+        iat: issuedAt,
+        exp: expiresAt,
+        act: payload.act as { sub: string; subjectType?: SubjectType } | undefined,
+        customClaims: Object.fromEntries(
+          Object.entries(payload).filter(([k]) => !RESERVED_JWT_CLAIMS.has(k)),
+        ),
+      };
+    }
+    catch {
+      continue;
+    }
+  }
+
+  throw Errors.unauthorized('Invalid or expired token');
+}

package/src/core/auth/login-timing.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Login timing-oracle regression test.
+ *
+ * Background: an earlier implementation used a hard-coded malformed Argon2 PHC
+ * string as the dummy hash for the "user not found / no password" branch in
+ * `login()`. `hash-wasm`'s parser threw before running the KDF, so that branch
+ * completed in ~0.3ms while a real password verify took ~50-200ms. The gap
+ * allowed user enumeration over the network.
+ *
+ * This test asserts the two branches are within the same order of magnitude
+ * so the dummy hash continues to be a *real* Argon2 hash (i.e. the verify
+ * actually runs the KDF). It is intentionally generous: Argon2 timings vary
+ * across runtimes, but a malformed dummy regresses by ~100x which this
+ * threshold catches reliably without false positives.
+ */
+
+import type { Fortress } from '../fortress';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+
+const SECRET = 'login-timing-test-secret-32chars!!';
+const PASSWORD = 'password-123456';
+const EMAIL = 'timing@example.com';
+
+let fortress: Fortress;
+
+async function timeFailedLogin(identifier: string): Promise<number> {
+  const start = performance.now();
+  try {
+    await fortress.auth.login(identifier, 'definitely-not-the-password');
+  }
+  catch {
+    /* expected */
+  }
+  return performance.now() - start;
+}
+
+async function median(samples: number[]): Promise<number> {
+  const sorted = [...samples].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+
+describe('login timing-oracle defense', () => {
+  beforeEach(async () => {
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+    await fortress.auth.createUser({
+      email: EMAIL,
+      name: 'Timing User',
+      password: PASSWORD,
+    });
+    // Warm the lazy dummy hash so the *first* miss isn't unfairly slow.
+    await timeFailedLogin('missing@example.com');
+  });
+
+  it('user-not-found branch takes a real Argon2-verify amount of time', async () => {
+    const N = 5;
+    const missSamples: number[] = [];
+    const hitSamples: number[] = [];
+    for (let i = 0; i < N; i++) {
+      missSamples.push(await timeFailedLogin(`ghost-${i}@example.com`));
+      hitSamples.push(await timeFailedLogin(EMAIL));
+    }
+
+    const missMedian = await median(missSamples);
+    const hitMedian = await median(hitSamples);
+
+    // Both branches should perform a real Argon2 verify. We require the miss
+    // branch to be at least ~30% of the hit branch's wall-clock time. The
+    // malformed-dummy regression produced a ~300x gap, so this catches it
+    // with comfortable margin while tolerating GC / jitter noise.
+    expect(missMedian).toBeGreaterThan(hitMedian * 0.3);
+  });
+});

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

@@ -0,0 +1,253 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { clearHibpCache, isPasswordBreached, validatePassword } from './password-policy';
+
+describe('password-policy', () => {
+  afterEach(() => {
+    clearHibpCache();
+    vi.restoreAllMocks();
+  });
+
+  describe('validatePassword', () => {
+    it('accepts a valid password with default config', async () => {
+      await expect(validatePassword('secureP@ss12345')).resolves.toBeUndefined();
+    });
+
+    it('rejects passwords shorter than minLength', async () => {
+      await expect(validatePassword('short', { minLength: 8 })).rejects.toThrow(
+        'Password must be at least 8 characters',
+      );
+    });
+
+    it('rejects passwords longer than maxLength', async () => {
+      const longPassword = 'a'.repeat(200);
+      await expect(validatePassword(longPassword, { maxLength: 128 })).rejects.toThrow(
+        'Password must be at most 128 characters',
+      );
+    });
+
+    it('accepts password at exact minLength boundary', async () => {
+      await expect(validatePassword('12345678', { minLength: 8 })).resolves.toBeUndefined();
+    });
+
+    it('accepts password at exact maxLength boundary', async () => {
+      const exactMax = 'a'.repeat(128);
+      await expect(validatePassword(exactMax, { maxLength: 128 })).resolves.toBeUndefined();
+    });
+
+    it('uses default min 15 and max 128 when not configured', async () => {
+      await expect(validatePassword('12345678901234')).rejects.toThrow('at least 15');
+      await expect(validatePassword('a'.repeat(129))).rejects.toThrow('at most 128');
+    });
+
+    it('respects custom minLength and maxLength', async () => {
+      await expect(validatePassword('abc', { minLength: 3, maxLength: 10 })).resolves.toBeUndefined();
+      await expect(validatePassword('ab', { minLength: 3 })).rejects.toThrow('at least 3');
+    });
+
+    it('applies NFKC before length checks', async () => {
+      await expect(validatePassword('ffi', { minLength: 3, maxLength: 3 })).resolves.toBeUndefined();
+    });
+  });
+
+  describe('isPasswordBreached (HIBP)', () => {
+    it('detects a breached password', async () => {
+      // "password" is SHA-1: 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8
+      // prefix: 5BAA6, suffix: 1E4C9B93F3F0682250B6CF8331B7EE68FD8
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        new Response('1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493\r\nABCDEF1234567890ABCDEF1234567890ABC:5', {
+          status: 200,
+        }),
+      );
+
+      const result = await isPasswordBreached('password');
+      expect(result).toBe(true);
+    });
+
+    it('returns false for a clean password', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        new Response('0000000000000000000000000000000000000:1\r\nFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF:2', {
+          status: 200,
+        }),
+      );
+
+      const result = await isPasswordBreached('my-unique-fortress-password-xyz');
+      expect(result).toBe(false);
+    });
+
+    it('fails open on network error', async () => {
+      vi.spyOn(globalThis, 'fetch').mockRejectedValueOnce(new Error('Network error'));
+
+      const result = await isPasswordBreached('password');
+      expect(result).toBe(false);
+    });
+
+    it('fails open on non-200 API response', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        new Response('Service Unavailable', { status: 503 }),
+      );
+
+      const result = await isPasswordBreached('password');
+      expect(result).toBe(false);
+    });
+
+    it('uses cached HIBP response within TTL', async () => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+        new Response('1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493', { status: 200 }),
+      );
+
+      await isPasswordBreached('password');
+      await isPasswordBreached('password');
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('evicts the least-recently-used range rather than the oldest inserted range', async () => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async () =>
+        new Response('00000000000000000000000000000000000:1', { status: 200 }));
+      const options = { cacheMaxEntries: 2 };
+
+      await isPasswordBreached('first-unique-password', options);
+      await isPasswordBreached('second-unique-password', options);
+      await isPasswordBreached('first-unique-password', options); // touch first
+      await isPasswordBreached('third-unique-password', options); // evicts second
+      await isPasswordBreached('first-unique-password', options); // still cached
+      await isPasswordBreached('second-unique-password', options); // fetch again
+
+      expect(fetchSpy).toHaveBeenCalledTimes(4);
+    });
+
+    it('bypasses existing cache entries when caching is disabled', async () => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async () =>
+        new Response('1E4C9B93F3F0682250B6CF8331B7EE68FD8:1', { status: 200 }));
+
+      await expect(isPasswordBreached('password')).resolves.toBe(true);
+      await expect(isPasswordBreached('password', { cacheMaxEntries: 0 })).resolves.toBe(true);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('fails closed and notifies its observer when HIBP is unavailable', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        new Response('Service Unavailable', { status: 503 }),
+      );
+      const observer = vi.fn();
+
+      await expect(isPasswordBreached('password', {
+        failureMode: 'closed',
+        observer,
+      })).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE' });
+      expect(observer).toHaveBeenCalledOnce();
+      expect(observer).toHaveBeenCalledWith({ failureMode: 'closed', status: 503 });
+    });
+  });
+
+  describe('validatePassword with breach checking', () => {
+    it('rejects breached password when checkBreached is enabled', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        new Response('1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493', { status: 200 }),
+      );
+
+      await expect(
+        validatePassword('password', { checkBreached: true, minLength: 8 }),
+      ).rejects.toThrow('data breach');
+    });
+
+    it('does not check breaches when checkBreached is false', async () => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+      await expect(
+        validatePassword('password', { checkBreached: false, minLength: 8 }),
+      ).resolves.toBeUndefined();
+
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('integration with createUser', () => {
+    it('rejects short passwords during user creation', async () => {
+      const fortress = createFortress({
+        jwt: { key: 'test-secret-at-least-32-characters!!' },
+        database: createTestAdapter(),
+        passwordPolicy: { minLength: 10 },
+      });
+
+      await expect(
+        fortress.auth.createUser({ email: 'a@b.com', name: 'Test', password: 'short' }),
+      ).rejects.toThrow('at least 10');
+    });
+
+    it('emits a degraded event and honors fail-closed mode during user creation', async () => {
+      vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        new Response('Service Unavailable', { status: 503 }),
+      );
+      const fortress = createFortress({
+        jwt: { key: 'test-secret-at-least-32-characters!!' },
+        database: createTestAdapter(),
+        passwordPolicy: { checkBreached: true, breachedFailureMode: 'closed' },
+      });
+      const events: string[] = [];
+      fortress.auth.addAuthObserver(event => void events.push(event.eventType));
+
+      await expect(fortress.auth.createUser({
+        email: 'degraded@b.com',
+        name: 'Test',
+        password: 'valid-password-123456',
+      })).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE' });
+      expect(events.filter(event => event === 'PASSWORD_BREACH_CHECK_DEGRADED')).toHaveLength(1);
+    });
+
+    it('allows valid passwords during user creation', async () => {
+      const fortress = createFortress({
+        jwt: { key: 'test-secret-at-least-32-characters!!' },
+        database: createTestAdapter(),
+        passwordPolicy: { minLength: 6 },
+      });
+
+      const user = await fortress.auth.createUser({
+        email: 'a@b.com',
+        name: 'Test',
+        password: 'validpass',
+      });
+
+      expect(user.email).toBe('a@b.com');
+    });
+
+    it('allows passwordless user creation (no validation)', async () => {
+      const fortress = createFortress({
+        jwt: { key: 'test-secret-at-least-32-characters!!' },
+        database: createTestAdapter(),
+        passwordPolicy: { minLength: 10 },
+      });
+
+      const user = await fortress.auth.createUser({ email: 'a@b.com', name: 'Test' });
+      expect(user.email).toBe('a@b.com');
+    });
+
+    it('normalizes passwords consistently across create, update, and login', async () => {
+      const passwordHasher = {
+        hash: async (password: string) => `hash:${password}`,
+        verify: async (hash: string, password: string) => hash === `hash:${password}`,
+      };
+      const fortress = createFortress({
+        jwt: { key: 'test-secret-at-least-32-characters!!' },
+        database: createTestAdapter(),
+        passwordHasher,
+      });
+
+      const user = await fortress.auth.createUser({
+        email: 'nfkc@test.com',
+        name: 'NFKC',
+        password: 'Ｐａｓｓｗｏｒｄ１２３４５６！',
+      });
+      await expect(fortress.auth.login('nfkc@test.com', 'Password123456!')).resolves.toMatchObject({
+        status: 'success',
+      });
+
+      await fortress.auth.updateUser(user.id, { password: 'ＮｅｗＰａｓｓｗｏｒｄ１２３！' });
+      await expect(fortress.auth.login('nfkc@test.com', 'NewPassword123!')).resolves.toMatchObject({
+        status: 'success',
+      });
+    });
+  });
+});