@bevel-software/platform-core-backend 0.1.0 → 0.2.0

package/src/modules/auth/__tests__/oidc-auth-provider.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { OidcAuthProvider } from '../oidc-auth-provider.js';
+import type { AuthService } from '../auth.service.js';
+
+const ISSUER = 'https://idp.example.com';
+const DISCOVERY = {
+  authorization_endpoint: `${ISSUER}/authorize`,
+  token_endpoint: `${ISSUER}/token`,
+  userinfo_endpoint: `${ISSUER}/userinfo`,
+};
+
+function makeProvider(fetchImpl: typeof fetch, authService: AuthService) {
+  const provider = new OidcAuthProvider({
+    issuerUrl: ISSUER,
+    clientId: 'client-1',
+    clientSecret: 'secret-1',
+    scopes: 'openid profile email',
+    label: 'Sign in with Example',
+    publicBackendUrl: 'http://localhost:3001',
+    publicFrontendUrl: 'http://localhost:5173',
+    cookieSecure: false,
+    fetchImpl,
+  });
+  const router = express.Router();
+  provider.mountRoutes(router, authService);
+  const app = express();
+  app.use('/api', router);
+  return app;
+}
+
+/** fetch stub that serves discovery, token and userinfo; records requests. */
+function makeIdpFetch(overrides: { userinfo?: Record<string, unknown> } = {}) {
+  const calls: Array<{ url: string; init?: RequestInit }> = [];
+  const impl = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, init });
+    if (url.endsWith('/.well-known/openid-configuration')) {
+      return new Response(JSON.stringify(DISCOVERY), { status: 200 });
+    }
+    if (url === DISCOVERY.token_endpoint) {
+      return new Response(JSON.stringify({ access_token: 'at-123' }), { status: 200 });
+    }
+    if (url === DISCOVERY.userinfo_endpoint) {
+      return new Response(
+        JSON.stringify(overrides.userinfo ?? { email: 'carol@example.com', name: 'Carol' }),
+        { status: 200 },
+      );
+    }
+    return new Response('not found', { status: 404 });
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
+let server: Server;
+afterEach(() => {
+  server?.close();
+});
+
+async function listen(app: express.Express): Promise<string> {
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+const authService = {
+  loginWithSso: vi.fn(async (email: string) => ({
+    token: 'jwt-for-' + email,
+    user: { id: 'u', email, name: 'Carol' },
+  })),
+} as unknown as AuthService;
+
+beforeEach(() => {
+  vi.mocked(authService.loginWithSso).mockClear();
+});
+
+describe('OidcAuthProvider', () => {
+  it('advertises key/label/startPath for the login screen', () => {
+    const provider = new OidcAuthProvider({
+      issuerUrl: ISSUER,
+      clientId: 'c',
+      clientSecret: 's',
+      scopes: 'openid',
+      label: 'Sign in with Example',
+      publicBackendUrl: 'http://localhost:3001',
+      publicFrontendUrl: 'http://localhost:5173',
+      cookieSecure: false,
+    });
+    expect(provider.key).toBe('oidc');
+    expect(provider.label).toBe('Sign in with Example');
+    expect(provider.startPath).toBe('/api/auth/oidc/login');
+  });
+
+  it('login redirects to the authorization endpoint with PKCE + state, setting the state cookie', async () => {
+    const idp = makeIdpFetch();
+    const base = await listen(makeProvider(idp.impl, authService));
+    const res = await fetch(`${base}/api/auth/oidc/login`, { redirect: 'manual' });
+    expect(res.status).toBe(302);
+    const location = new URL(res.headers.get('location')!);
+    expect(location.origin + location.pathname).toBe(DISCOVERY.authorization_endpoint);
+    expect(location.searchParams.get('client_id')).toBe('client-1');
+    expect(location.searchParams.get('response_type')).toBe('code');
+    expect(location.searchParams.get('redirect_uri')).toBe(
+      'http://localhost:3001/api/auth/oidc/callback',
+    );
+    expect(location.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(location.searchParams.get('state')).toMatch(/^[0-9a-f]{32}$/);
+    expect(res.headers.get('set-cookie')).toContain('oidc_oauth_state=');
+  });
+
+  it('callback exchanges the code, reads userinfo, and redirects with the app JWT in the fragment', async () => {
+    const idp = makeIdpFetch();
+    const base = await listen(makeProvider(idp.impl, authService));
+
+    const start = await fetch(`${base}/api/auth/oidc/login`, { redirect: 'manual' });
+    const state = new URL(start.headers.get('location')!).searchParams.get('state')!;
+    const cookie = start.headers.get('set-cookie')!.split(';')[0];
+
+    const cb = await fetch(
+      `${base}/api/auth/oidc/callback?code=code-1&state=${state}`,
+      { redirect: 'manual', headers: { cookie } },
+    );
+    expect(cb.status).toBe(302);
+    expect(cb.headers.get('location')).toBe(
+      'http://localhost:5173/auth/oidc/callback#token=' +
+        encodeURIComponent('jwt-for-carol@example.com'),
+    );
+    // Session cookie set alongside the fragment hand-off.
+    expect(cb.headers.get('set-cookie')).toContain('bevel_token=');
+
+    // Token exchange used PKCE (verifier from the cookie) + Basic client auth.
+    const tokenCall = idp.calls.find((c) => c.url === DISCOVERY.token_endpoint)!;
+    const body = String(tokenCall.init?.body);
+    expect(body).toContain('grant_type=authorization_code');
+    expect(body).toContain('code_verifier=');
+    expect((tokenCall.init?.headers as Record<string, string>).Authorization).toMatch(/^Basic /);
+    // userinfo was called with the freshly exchanged access token.
+    const infoCall = idp.calls.find((c) => c.url === DISCOVERY.userinfo_endpoint)!;
+    expect((infoCall.init?.headers as Record<string, string>).Authorization).toBe('Bearer at-123');
+    expect(authService.loginWithSso).toHaveBeenCalledWith('carol@example.com', 'Carol');
+  });
+
+  it('rejects a state mismatch without touching the token endpoint', async () => {
+    const idp = makeIdpFetch();
+    const base = await listen(makeProvider(idp.impl, authService));
+    const start = await fetch(`${base}/api/auth/oidc/login`, { redirect: 'manual' });
+    const cookie = start.headers.get('set-cookie')!.split(';')[0];
+    const cb = await fetch(`${base}/api/auth/oidc/callback?code=code-1&state=forged`, {
+      redirect: 'manual',
+      headers: { cookie },
+    });
+    expect(cb.headers.get('location')).toBe('http://localhost:5173/auth/oidc/callback#error=state');
+    expect(idp.calls.some((c) => c.url === DISCOVERY.token_endpoint)).toBe(false);
+    expect(authService.loginWithSso).not.toHaveBeenCalled();
+  });
+
+  it('fails with #error=auth when userinfo has no email claim', async () => {
+    const idp = makeIdpFetch({ userinfo: { name: 'No Email' } });
+    const base = await listen(makeProvider(idp.impl, authService));
+    const start = await fetch(`${base}/api/auth/oidc/login`, { redirect: 'manual' });
+    const state = new URL(start.headers.get('location')!).searchParams.get('state')!;
+    const cookie = start.headers.get('set-cookie')!.split(';')[0];
+    const cb = await fetch(`${base}/api/auth/oidc/callback?code=c&state=${state}`, {
+      redirect: 'manual',
+      headers: { cookie },
+    });
+    expect(cb.headers.get('location')).toBe('http://localhost:5173/auth/oidc/callback#error=auth');
+    expect(authService.loginWithSso).not.toHaveBeenCalled();
+  });
+});

package/src/modules/auth/__tests__/password-hash.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import {
+  hashPassword,
+  verifyPassword,
+  timingSafeStringEqual,
+  MIN_PASSWORD_LENGTH,
+} from '../password-hash.js';
+
+describe('password-hash', () => {
+  it('round-trips a password', async () => {
+    const stored = await hashPassword('correct horse battery staple');
+    expect(stored.startsWith('scrypt:N=')).toBe(true);
+    expect(await verifyPassword('correct horse battery staple', stored)).toBe(true);
+  });
+
+  it('rejects a wrong password', async () => {
+    const stored = await hashPassword('correct horse battery staple');
+    expect(await verifyPassword('incorrect horse', stored)).toBe(false);
+  });
+
+  it('salts: same password twice → different stored strings, both verify', async () => {
+    const a = await hashPassword('same-password');
+    const b = await hashPassword('same-password');
+    expect(a).not.toBe(b);
+    expect(await verifyPassword('same-password', a)).toBe(true);
+    expect(await verifyPassword('same-password', b)).toBe(true);
+  });
+
+  it('fails closed on malformed / foreign stored values', async () => {
+    expect(await verifyPassword('x', '')).toBe(false);
+    expect(await verifyPassword('x', 'bcrypt$whatever')).toBe(false);
+    expect(await verifyPassword('x', 'scrypt:N=abc,r=8,p=1:AA:BB')).toBe(false);
+  });
+
+  it('verifies params from the stored string (future cost bumps keep old hashes valid)', async () => {
+    // A hash produced at lower cost still verifies — parameters are read from
+    // the string, not assumed from current constants.
+    const stored = await hashPassword('pw');
+    const weaker = stored.replace(/N=\d+/, 'N=16384'); // same params today; string form is authoritative
+    expect(await verifyPassword('pw', weaker)).toBe(true);
+  });
+
+  it('timingSafeStringEqual matches only exact strings', () => {
+    expect(timingSafeStringEqual('secret', 'secret')).toBe(true);
+    expect(timingSafeStringEqual('secret', 'secret2')).toBe(false);
+    expect(timingSafeStringEqual('', '')).toBe(true);
+    expect(timingSafeStringEqual('a', '')).toBe(false);
+  });
+
+  it('exposes a sane minimum length for the routes to enforce', () => {
+    expect(MIN_PASSWORD_LENGTH).toBeGreaterThanOrEqual(8);
+  });
+});

package/src/modules/auth/__tests__/rate-limit.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { FixedWindowRateLimiter } from '../rate-limit.js';
+
+describe('FixedWindowRateLimiter', () => {
+  it('allows up to max attempts per window, then refuses', () => {
+    let now = 0;
+    const limiter = new FixedWindowRateLimiter(3, 1000, () => now);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(false);
+    // A different key has its own budget.
+    expect(limiter.consume('other')).toBe(true);
+    // Window rollover restores the budget.
+    now = 1001;
+    expect(limiter.consume('k')).toBe(true);
+  });
+
+  it('reset() clears a key immediately', () => {
+    const limiter = new FixedWindowRateLimiter(1, 60_000, () => 0);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(false);
+    limiter.reset('k');
+    expect(limiter.consume('k')).toBe(true);
+  });
+
+  it('prunes expired windows so the map stays bounded', () => {
+    let now = 0;
+    const limiter = new FixedWindowRateLimiter(1, 1000, () => now);
+    for (let i = 0; i < 100; i++) limiter.consume(`k${i}`);
+    now = 2000;
+    limiter.consume('fresh');
+    // Internal map pruned to just the fresh key.
+    expect((limiter as unknown as { hits: Map<string, unknown> }).hits.size).toBe(1);
+  });
+});

package/src/modules/auth/account.routes.ts

@@ -0,0 +1,59 @@
+import express from 'express';
+import type { AuthService } from './auth.service.js';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import './auth.middleware.js'; // Express Request augmentation
+
+/**
+ * Admin account management (Roles & Members → Accounts): list accounts and
+ * create/reset password accounts. Gated per request by
+ * {@link IAdminAccessService} — the Admin role in `roles.yaml`, plus the env
+ * bootstrap admin (always-admin, see AdminAccessService).
+ *
+ * Deliberately namespaced `/admin/accounts` (not `/admin/users`): the
+ * enterprise overlay mounts its own richer user administration (listing with
+ * activity, GDPR erasure) at `/admin/users`, and the two must not shadow each
+ * other across mount phases.
+ */
+export function createAccountRoutes(
+  authService: AuthService,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  const requireAdmin: express.RequestHandler = async (req, res, next) => {
+    if (!(await adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    next();
+  };
+
+  // GET /api/admin/accounts — id, email, name, whether a password is set.
+  router.get('/admin/accounts', requireAdmin, async (_req, res) => {
+    res.json({ accounts: await authService.listAccounts() });
+  });
+
+  // POST /api/admin/accounts { email, name?, password } — create an account
+  // (or reset the password of an existing one; upsert-by-email is deliberate,
+  // see AuthService.createAccount).
+  router.post('/admin/accounts', requireAdmin, async (req, res) => {
+    const { email, name, password } = req.body as {
+      email?: string;
+      name?: string;
+      password?: string;
+    };
+    if (!email || !password) {
+      res.status(400).json({ error: 'email and password are required' });
+      return;
+    }
+    try {
+      const user = await authService.createAccount(email, name, password);
+      res.status(201).json(user);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      res.status(400).json({ error: msg });
+    }
+  });
+
+  return router;
+}

package/src/modules/auth/auth.routes.ts

@@ -1,6 +1,7 @@
 import express from 'express';
 import type { AuthService } from './auth.service.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js'; // also imports Express Request augmentation
+import { FixedWindowRateLimiter } from './rate-limit.js';
 
 /**
  * Max age of the JWT cookie (seconds). Matches the JWT's own `expiresIn:
@@ -11,16 +12,22 @@ import { AUTH_COOKIE_NAME } from './auth.middleware.js'; // also imports Express
 export const AUTH_COOKIE_MAX_AGE_S = 7 * 24 * 60 * 60;
 
 /**
- * A pluggable SSO login method. Core ships password login only; the
- * composition root passes provider plugins (e.g. Microsoft OIDC, owned by the
- * sharepoint module) which mount their own routes under `/auth/<key>/…` and
- * are advertised to the login screen under `key` by the capability probe.
- * A plugin is only passed in when its machinery is configured AND the
- * instance hasn't switched it off — presence means enabled.
+ * A pluggable SSO login method. Core ships password login and (when
+ * configured) the generic OIDC provider; overlays may pass additional plugins
+ * (e.g. the enterprise "Sign in with Microsoft", owned by its sharepoint
+ * module). A plugin mounts its own routes under `/auth/<key>/…` and is
+ * advertised to the login screen by the capability probe, which renders one
+ * button per provider from `label` + `startPath`. A plugin is only present
+ * when its machinery is configured AND the instance hasn't switched it off —
+ * presence means enabled.
  */
 export interface AuthProviderPlugin {
-  /** Probe key + route namespace (e.g. 'microsoft' → /auth/microsoft/…). */
+  /** Probe key + route namespace (e.g. 'oidc' → /auth/oidc/…). */
   readonly key: string;
+  /** Login-button label (e.g. "Sign in with Microsoft"). */
+  readonly label: string;
+  /** Browser navigation target that starts the flow (e.g. '/api/auth/oidc/login'). */
+  readonly startPath: string;
   /** Mount the provider's routes (login redirect, callback) on the auth router. */
   mountRoutes(router: express.Router, authService: AuthService): void;
 }
@@ -33,7 +40,20 @@ export function createAuthRoutes(
 ): express.Router {
   const router = express.Router();
 
-  // POST /api/auth/login — email + shared-password login (unprotected)
+  // Brute-force guards on the password endpoints (scrypt also makes each
+  // attempt expensive server-side, so these double as DoS protection):
+  //  - login: a tight per-(ip, email) budget plus a wider per-ip budget so a
+  //    single address can't spray many emails; the pair key resets on a
+  //    successful login.
+  //  - change-password: per authenticated account (a stolen session must not
+  //    get unlimited guesses at the current password).
+  const loginPairLimiter = new FixedWindowRateLimiter(10, 15 * 60_000);
+  const loginIpLimiter = new FixedWindowRateLimiter(50, 15 * 60_000);
+  const changePasswordLimiter = new FixedWindowRateLimiter(10, 15 * 60_000);
+  const clientIp = (req: express.Request) => req.ip ?? req.socket.remoteAddress ?? 'unknown';
+
+  // POST /api/auth/login — email + password login (unprotected): the env
+  // bootstrap admin or a per-user account password (see AuthService).
   router.post('/auth/login', async (req, res) => {
     if (!passwordLoginEnabled) {
       res.status(403).json({ error: 'Password login is disabled' });
@@ -44,9 +64,19 @@ export function createAuthRoutes(
       res.status(400).json({ error: 'email and password are required' });
       return;
     }
+    const ip = clientIp(req);
+    const pairKey = `${ip}|${email.trim().toLowerCase()}`;
+    if (!loginPairLimiter.consume(pairKey) || !loginIpLimiter.consume(ip)) {
+      res.status(429).json({ error: 'Too many attempts. Try again later.' });
+      return;
+    }
 
     try {
       const result = await authService.loginWithPassword(email, password);
+      // A real login clears the pair budget — a user who fumbled a few
+      // attempts isn't rate-limited on their next visit. (The wider per-ip
+      // window intentionally keeps counting.)
+      loginPairLimiter.reset(pairKey);
       // Also set the JWT as an HttpOnly cookie so transports that can't
       // carry headers (EventSource for SSE, image tags) authenticate
       // automatically. JSON callers continue to use the Bearer header
@@ -68,16 +98,44 @@ export function createAuthRoutes(
   });
 
   // GET /api/auth/providers — unprotected capability probe so the login screen
-  // knows which login methods to render. SSO providers appear under their key.
+  // knows which login methods to render: the password form, plus one button
+  // per SSO provider (label + the path that starts its flow).
   router.get('/auth/providers', (_req, res) => {
     res.json({
       password: passwordLoginEnabled,
-      ...Object.fromEntries(providers.map((p) => [p.key, true])),
+      sso: providers.map((p) => ({ key: p.key, label: p.label, startPath: p.startPath })),
     });
   });
 
   for (const provider of providers) provider.mountRoutes(router, authService);
 
+  // POST /api/auth/change-password — self-service (protected). Requires the
+  // current password whenever one is set; an SSO-only account sets its first
+  // password without one.
+  router.post('/auth/change-password', authMiddleware, async (req, res) => {
+    const { currentPassword, newPassword } = req.body as {
+      currentPassword?: string;
+      newPassword?: string;
+    };
+    if (!newPassword) {
+      res.status(400).json({ error: 'newPassword is required' });
+      return;
+    }
+    if (!changePasswordLimiter.consume(req.userId!)) {
+      res.status(429).json({ error: 'Too many attempts. Try again later.' });
+      return;
+    }
+    try {
+      await authService.changePassword(req.userId!, currentPassword, newPassword);
+      res.json({ ok: true });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      // Policy violations and a wrong current password are caller errors, not
+      // server faults — and the message is safe to show verbatim.
+      res.status(400).json({ error: msg });
+    }
+  });
+
   // GET /api/auth/me — validate stored JWT, return user info (protected)
   router.get('/auth/me', authMiddleware, async (req, res) => {
     try {