@bajustone/fortress 1.0.0-rc.1

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

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeEmail } from './email';
+
+describe('normalizeEmail', () => {
+  it('lowercases the complete address', () => {
+    expect(normalizeEmail('User.Name@EXAMPLE.COM')).toBe('user.name@example.com');
+  });
+
+  it('collapses canonically equivalent Unicode spellings with NFC', () => {
+    expect(normalizeEmail('E\u0301@Example.COM')).toBe('é@example.com');
+    expect(normalizeEmail('É@example.com')).toBe('é@example.com');
+  });
+
+  it('does not silently trim invalid surrounding whitespace', () => {
+    expect(normalizeEmail(' User@Example.COM ')).toBe(' user@example.com ');
+  });
+});

package/src/core/auth/email.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical representation used for persisted and compared email identities.
+ *
+ * NFC collapses canonically-equivalent Unicode spellings while lowercase
+ * makes the product's explicitly case-insensitive email policy deterministic
+ * across database collations. Deliberately does not trim: surrounding
+ * whitespace is invalid input, not part of identity canonicalization.
+ */
+export function normalizeEmail(email: string): string {
+  return email.toLowerCase().normalize('NFC');
+}

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

@@ -0,0 +1,251 @@
+import type { Fortress } from '../fortress';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { assertSuccess } from '../types';
+
+let fortress: Fortress;
+const SECRET = 'hooks-test-secret-at-least-32chars!!';
+
+async function seedUser(): Promise<{ id: string }> {
+  return fortress.auth.createUser({
+    email: 'hook-user@example.com',
+    name: 'Hook User',
+    password: 'password-123456',
+  });
+}
+
+describe('plugin hooks', () => {
+  describe('beforeRegister', () => {
+    it('re-normalizes email after a hook mutates registration data', async () => {
+      const beforeRegister = vi.fn(async (ctx: { data: { email: string } }) => {
+        ctx.data.email = 'E\u0301.HOOK@EXAMPLE.COM';
+      });
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{ name: 'test', hooks: { beforeRegister } }],
+      });
+
+      const user = await fortress.auth.createUser({
+        email: 'original@example.com',
+        name: 'Hook User',
+        password: 'password-123456',
+      });
+      expect(user.email).toBe('é.hook@example.com');
+      expect((await fortress.auth.getLoginIdentifiers(user.id))[0].value).toBe('é.hook@example.com');
+    });
+  });
+
+  describe('beforeLogout', () => {
+    it('is called before logout', async () => {
+      const beforeLogout = vi.fn(async () => {});
+
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{ name: 'test', hooks: { beforeLogout } }],
+      });
+
+      await seedUser();
+      const login = await fortress.auth.login('hook-user@example.com', 'password-123456');
+      assertSuccess(login);
+      await fortress.auth.logout(login.refreshToken as string);
+
+      expect(beforeLogout).toHaveBeenCalledOnce();
+      expect(beforeLogout).toHaveBeenCalledWith(expect.objectContaining({
+        token: login.refreshToken,
+      }));
+    });
+  });
+
+  describe('afterRegister', () => {
+    it('is called after user creation', async () => {
+      const afterRegister = vi.fn(async () => {});
+
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{ name: 'test', hooks: { afterRegister } }],
+      });
+
+      await fortress.auth.createUser({
+        email: 'new-user@example.com',
+        name: 'New User',
+        password: 'password-123456',
+      });
+
+      expect(afterRegister).toHaveBeenCalledOnce();
+      expect(afterRegister).toHaveBeenCalledWith(
+        expect.objectContaining({ responseHeaders: expect.any(Headers) }),
+        expect.objectContaining({ email: 'new-user@example.com' }),
+      );
+    });
+
+    it('receives the created user', async () => {
+      let receivedUser: unknown = null;
+      const afterRegister = vi.fn(async (_ctx: unknown, user: unknown) => {
+        receivedUser = user;
+      });
+
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{ name: 'test', hooks: { afterRegister } }],
+      });
+
+      await fortress.auth.createUser({
+        email: 'check-user@example.com',
+        name: 'Check User',
+        password: 'password-123456',
+      });
+
+      expect(receivedUser).toMatchObject({ email: 'check-user@example.com', name: 'Check User' });
+    });
+  });
+
+  describe('beforeTokenRefresh', () => {
+    it('is called before token refresh', async () => {
+      const beforeTokenRefresh = vi.fn(async () => {});
+
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{ name: 'test', hooks: { beforeTokenRefresh } }],
+      });
+
+      await seedUser();
+      const login = await fortress.auth.login('hook-user@example.com', 'password-123456');
+      assertSuccess(login);
+      await fortress.auth.refresh(login.refreshToken as string);
+
+      expect(beforeTokenRefresh).toHaveBeenCalledOnce();
+      expect(beforeTokenRefresh).toHaveBeenCalledWith(expect.objectContaining({
+        token: login.refreshToken,
+      }));
+    });
+
+    it('can block refresh with HookResult', async () => {
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{
+          name: 'blocker',
+          hooks: {
+            async beforeTokenRefresh() {
+              return { stop: true, response: { blocked: true } };
+            },
+          },
+        }],
+      });
+
+      await seedUser();
+      const login = await fortress.auth.login('hook-user@example.com', 'password-123456');
+      assertSuccess(login);
+      const result = await fortress.auth.refresh(login.refreshToken as string);
+
+      expect((result as any).blocked).toBe(true);
+    });
+  });
+
+  describe('afterTokenRefresh', () => {
+    it('is called after token refresh and can modify result', async () => {
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [{
+          name: 'test',
+          hooks: {
+            async afterTokenRefresh(_ctx, result) {
+              return { ...result, accessToken: `modified-${result.accessToken}` };
+            },
+          },
+        }],
+      });
+
+      await seedUser();
+      const login = await fortress.auth.login('hook-user@example.com', 'password-123456');
+      assertSuccess(login);
+      const result = await fortress.auth.refresh(login.refreshToken as string);
+
+      expect(result.accessToken).toMatch(/^modified-/);
+    });
+  });
+
+  describe('onLoginFailure isolation', () => {
+    it('preserves the auth error and continues after a hook throws', async () => {
+      const secondHook = vi.fn(async () => {});
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [
+          {
+            name: 'broken',
+            hooks: {
+              async onLoginFailure() {
+                throw new Error('hook bug');
+              },
+            },
+          },
+          { name: 'observer', hooks: { onLoginFailure: secondHook } },
+        ],
+      });
+      await seedUser();
+
+      await expect(
+        fortress.auth.login('hook-user@example.com', 'wrong-password'),
+      ).rejects.toThrow('Invalid credentials');
+      expect(secondHook).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('hook execution order', () => {
+    it('runs hooks in plugin registration order', async () => {
+      const order: string[] = [];
+
+      fortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [
+          {
+            name: 'first',
+            hooks: {
+              async afterLogin(_ctx, result) {
+                order.push('first');
+                return result;
+              },
+            },
+          },
+          {
+            name: 'second',
+            hooks: {
+              async afterLogin(_ctx, result) {
+                order.push('second');
+                return result;
+              },
+            },
+          },
+        ],
+      });
+
+      await seedUser();
+      await fortress.auth.login('hook-user@example.com', 'password-123456');
+
+      expect(order).toEqual(['first', 'second']);
+    });
+  });
+
+  describe('plugin validation', () => {
+    it('throws on duplicate plugin names', () => {
+      expect(() => createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [
+          { name: 'duplicate' },
+          { name: 'duplicate' },
+        ],
+      })).toThrow('Duplicate plugin name');
+    });
+  });
+});

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

@@ -0,0 +1,179 @@
+import type { Fortress } from '../fortress';
+
+import { beforeEach, describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+
+const SECRET = 'impersonation-test-secret-32chars!!';
+
+let fortress: Fortress;
+let adminId: string;
+let targetId: string;
+
+beforeEach(async () => {
+  fortress = createFortress({
+    jwt: { key: SECRET },
+    database: createTestAdapter(),
+  });
+
+  const admin = await fortress.auth.createUser({
+    email: 'admin@example.com',
+    name: 'Admin User',
+    password: 'admin-pass-1234',
+  });
+  adminId = admin.id;
+
+  const target = await fortress.auth.createUser({
+    email: 'target@example.com',
+    name: 'Target User',
+    password: 'target-pass-123',
+  });
+  targetId = target.id;
+
+  await fortress.iam.bindPermissionToUser(adminId, {
+    resource: 'fortress',
+    action: 'impersonate',
+  });
+});
+
+describe('impersonation', () => {
+  it('direct service call denies an admin without fortress:impersonate', async () => {
+    const other = await fortress.auth.createUser({
+      email: 'other-admin@example.com',
+      name: 'Other Admin',
+      password: 'other-pass-1234',
+    });
+
+    await expect(fortress.auth.impersonate(other.id, targetId))
+      .rejects
+      .toThrow('Insufficient permissions');
+  });
+
+  it('http route denies a user without fortress:impersonate', async () => {
+    const user = await fortress.auth.createUser({
+      email: 'plain@example.com',
+      name: 'Plain User',
+      password: 'plain-pass-1234',
+    });
+    const token = await fortress.auth.signToken({
+      sub: user.id,
+      subjectType: 'USER',
+      name: user.name,
+      groups: [],
+      iss: 'fortress',
+    });
+
+    const response = await fortress.handleRequest(new Request('http://localhost/auth/impersonate', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ targetUserId: targetId }),
+    }));
+
+    expect(response.status).toBe(403);
+  });
+
+  it('returns an access token with act claim containing admin userId', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId);
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+    const claims = await fortress.auth.verifyToken(result.accessToken as string);
+
+    expect(claims.act).toEqual({ sub: adminId, subjectType: 'USER' });
+  });
+
+  it('token has the target user sub, name, and groups', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId);
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+    const claims = await fortress.auth.verifyToken(result.accessToken as string);
+
+    expect(claims.sub).toBe(targetId);
+    expect(claims.name).toBe('Target User');
+    expect(claims.groups).toEqual([]);
+  });
+
+  it('does not issue a refresh token', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId);
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+
+    expect(result.refreshToken).toBeNull();
+  });
+
+  it('includes impersonation metadata in pluginData', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId);
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+
+    expect(result.pluginData).toEqual({
+      impersonation: {
+        adminUserId: adminId,
+        reason: null,
+        expiresInSeconds: 3600,
+      },
+    });
+  });
+
+  it('uses custom expiry when provided', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId, { expirySeconds: 600 });
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+    const claims = await fortress.auth.verifyToken(result.accessToken as string);
+
+    expect(result.pluginData).toMatchObject({
+      impersonation: { expiresInSeconds: 600 },
+    });
+    // Token lifetime should be roughly 600 seconds
+    expect(claims.exp - claims.iat).toBeLessThanOrEqual(600);
+    expect(claims.exp - claims.iat).toBeGreaterThanOrEqual(599);
+  });
+
+  it('throws NOT_FOUND if target user does not exist or is inactive', async () => {
+    await expect(fortress.auth.impersonate(adminId, '99999')).rejects.toThrow('Target user not found');
+
+    await fortress.auth.updateUser(targetId, { isActive: false });
+    await expect(fortress.auth.impersonate(adminId, targetId)).rejects.toThrow('Target user not found');
+  });
+
+  it('includes reason in pluginData when provided', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId, {
+      reason: 'Debugging user account issue #1234',
+    });
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+
+    expect(result.pluginData).toMatchObject({
+      impersonation: {
+        adminUserId: adminId,
+        reason: 'Debugging user account issue #1234',
+      },
+    });
+  });
+
+  it('returns the target user object without passwordHash', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId);
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+
+    expect(result.user.id).toBe(targetId);
+    expect(result.user.email).toBe('target@example.com');
+    expect(result.user.name).toBe('Target User');
+    expect((result.user as unknown as Record<string, unknown>).passwordHash).toBeUndefined();
+  });
+
+  // M4 regression: caller-supplied `expirySeconds` must be clamped to a
+  // configured maximum so an admin can't mint a years-long act token.
+  it('clamps oversized expirySeconds to the configured cap (M4)', async () => {
+    const result = await fortress.auth.impersonate(adminId, targetId, {
+      expirySeconds: 60 * 60 * 24 * 365 * 10, // 10 years
+    });
+    if (result.status !== 'impersonation')
+      throw new Error('Expected impersonation result');
+    const impersonationData = (result.pluginData as { impersonation?: { expiresInSeconds?: number } } | undefined)?.impersonation;
+    // Default cap is 3600s.
+    expect(impersonationData?.expiresInSeconds).toBeLessThanOrEqual(3600);
+  });
+});

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

@@ -0,0 +1,184 @@
+import { generateKeyPair, SignJWT } from 'jose';
+import { describe, expect, it } from 'vitest';
+
+import { signAccessToken, verifyAccessToken } from './jwt';
+
+describe('jwt', () => {
+  const secret = 'test-secret-at-least-32-chars-long!';
+  const claims = {
+    sub: '42',
+    subjectType: 'USER' as const,
+    name: 'Test User',
+    groups: ['admin', 'editor'],
+    iss: 'fortress-test',
+  };
+
+  describe('signAccessToken', () => {
+    it('signs a token and returns a string', async () => {
+      const token = await signAccessToken(claims, secret, 900);
+      expect(token).toBeTruthy();
+      expect(typeof token).toBe('string');
+      expect(token.split('.')).toHaveLength(3); // JWT has 3 parts
+    });
+  });
+
+  describe('verifyAccessToken', () => {
+    it('verifies a valid token and returns claims', async () => {
+      const token = await signAccessToken(claims, secret, 900);
+      const decoded = await verifyAccessToken(token, secret);
+
+      expect(decoded.sub).toBe('42');
+      expect(decoded.name).toBe('Test User');
+      expect(decoded.groups).toEqual(['admin', 'editor']);
+      expect(decoded.iss).toBe('fortress-test');
+      expect(decoded.iat).toBeGreaterThan(0);
+      expect(decoded.exp).toBeGreaterThan(decoded.iat);
+    });
+
+    it('rejects a token signed with a different secret', async () => {
+      const token = await signAccessToken(claims, secret, 900);
+      await expect(verifyAccessToken(token, 'wrong-secret')).rejects.toThrow('Invalid or expired token');
+    });
+
+    it('rejects an expired token', async () => {
+      const token = await signAccessToken(claims, secret, 0); // expires immediately
+      // Small delay to ensure expiration
+      await new Promise(resolve => setTimeout(resolve, 1100));
+      await expect(verifyAccessToken(token, secret)).rejects.toThrow('Invalid or expired token');
+    }, 5000);
+  });
+
+  describe('secret rotation', () => {
+    const oldSecret = 'old-secret-for-rotation-testing!!';
+    const newSecret = 'new-secret-for-rotation-testing!!';
+
+    it('verifies a token signed with old secret using [new, old] array', async () => {
+      const token = await signAccessToken(claims, oldSecret, 900);
+      const decoded = await verifyAccessToken(token, [newSecret, oldSecret]);
+      expect(decoded.sub).toBe('42');
+    });
+
+    it('signs with first secret in array', async () => {
+      const token = await signAccessToken(claims, [newSecret, oldSecret], 900);
+      // Should verify with newSecret alone
+      const decoded = await verifyAccessToken(token, newSecret);
+      expect(decoded.sub).toBe('42');
+    });
+
+    it('fails if token was signed with a secret not in the array', async () => {
+      const token = await signAccessToken(claims, 'unknown-secret-not-in-array!!', 900);
+      await expect(verifyAccessToken(token, [newSecret, oldSecret])).rejects.toThrow();
+    });
+  });
+
+  describe('custom claims', () => {
+    it('includes custom claims in the token', async () => {
+      const claimsWithCustom = {
+        ...claims,
+        customClaims: { tenantId: '5', tenantCode: 'acme' },
+      };
+      const token = await signAccessToken(claimsWithCustom, secret, 900);
+      const decoded = await verifyAccessToken(token, secret);
+
+      expect(decoded.customClaims?.tenantId).toBe('5');
+      expect(decoded.customClaims?.tenantCode).toBe('acme');
+    });
+
+    // M2 regression: a caller (or a plugin contributing via
+    // enrichTokenClaims) MUST NOT be able to forge `act`, `sub`, `groups`,
+    // `subjectType`, etc. through customClaims.
+    it('drops reserved keys from customClaims (no forged impersonation)', async () => {
+      const originalNodeEnv = process.env.NODE_ENV;
+      process.env.NODE_ENV = 'production'; // silent drop in prod
+      try {
+        const sneaky = {
+          ...claims,
+          customClaims: {
+            // attacker tries to overwrite trusted claims
+            sub: '9999',
+            act: { sub: '1', subjectType: 'USER' },
+            groups: ['admin'],
+            subjectType: 'SERVICE_ACCOUNT',
+            tenantId: 'real-tenant',
+          },
+        };
+        const token = await signAccessToken(sneaky, secret, 900);
+        const decoded = await verifyAccessToken(token, secret);
+
+        // Real sub/groups/subjectType prevail; forged act dropped.
+        expect(decoded.sub).toBe('42');
+        expect(decoded.subjectType).toBe('USER');
+        expect(decoded.groups).toEqual(['admin', 'editor']);
+        expect(decoded.act).toBeUndefined();
+        // Non-reserved custom claims survive.
+        expect(decoded.customClaims?.tenantId).toBe('real-tenant');
+      }
+      finally {
+        if (originalNodeEnv === undefined)
+          delete process.env.NODE_ENV;
+        else process.env.NODE_ENV = originalNodeEnv;
+      }
+    });
+  });
+
+  describe('remediation: alg + issuer pinning (M5 / P2.5)', () => {
+    it('verifies with the expected issuer', async () => {
+      const token = await signAccessToken(claims, secret, 900);
+      const decoded = await verifyAccessToken(token, secret, { issuer: 'fortress-test' });
+      expect(decoded.iss).toBe('fortress-test');
+    });
+
+    it('rejects a token whose iss does not match', async () => {
+      const token = await signAccessToken(claims, secret, 900);
+      await expect(
+        verifyAccessToken(token, secret, { issuer: 'someone-else' }),
+      ).rejects.toThrow();
+    });
+
+    it('rejects unsigned and asymmetric-algorithm confusion tokens', async () => {
+      const encoded = (value: unknown): string => btoa(JSON.stringify(value)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+      const unsigned = `${encoded({ alg: 'none' })}.${encoded({ ...claims, iat: 1, exp: 4_102_444_800 })}.`;
+      await expect(verifyAccessToken(unsigned, secret)).rejects.toThrow('Invalid or expired token');
+
+      const { privateKey } = await generateKeyPair('RS256');
+      const asymmetric = await new SignJWT({ ...claims, sub: claims.sub })
+        .setProtectedHeader({ alg: 'RS256' })
+        .setIssuedAt()
+        .setExpirationTime('900s')
+        .sign(privateKey);
+      await expect(verifyAccessToken(asymmetric, secret)).rejects.toThrow('Invalid or expired token');
+    });
+
+    it('rejects tokens missing Fortress-required claims instead of fabricating defaults', async () => {
+      const token = await new SignJWT({ subjectType: 'USER', groups: [] })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setIssuedAt()
+        .setExpirationTime('900s')
+        .setIssuer('fortress-test')
+        .setSubject('42')
+        .sign(new TextEncoder().encode(secret));
+
+      await expect(verifyAccessToken(token, secret)).rejects.toThrow('Invalid or expired token');
+    });
+
+    it('signs and verifies audience end-to-end', async () => {
+      const token = await signAccessToken(
+        { ...claims, customClaims: { tenantId: 'acme' } },
+        secret,
+        900,
+        { audience: 'fortress-api' },
+      );
+
+      const decoded = await verifyAccessToken(token, secret, {
+        audience: 'fortress-api',
+        requiredClaims: ['tenantId'],
+      });
+      expect(decoded.aud).toBe('fortress-api');
+      expect(decoded.customClaims?.tenantId).toBe('acme');
+
+      await expect(
+        verifyAccessToken(token, secret, { audience: 'other-api' }),
+      ).rejects.toThrow('Invalid or expired token');
+    });
+  });
+});