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

package/src/modules/auth/auth.service.ts

@@ -1,4 +1,3 @@
-import { timingSafeEqual } from 'node:crypto';
 import jwt from 'jsonwebtoken';
 import { eq } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
@@ -6,9 +5,28 @@ import type { CoreConfig } from '../../core-config.js';
 import { users } from '../database/schema.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { hashEmail } from '../../shared/hash-email.js';
+import {
+  hashPassword,
+  verifyPassword,
+  timingSafeStringEqual,
+  MIN_PASSWORD_LENGTH,
+} from './password-hash.js';
 
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
+/**
+ * Decoy hash verified when the email is unknown or has no password set, so
+ * those paths cost the same scrypt work as a real wrong-password attempt —
+ * without it, response timing would reveal which emails have accounts.
+ * Lazily computed once; the compared password never matches it (verification
+ * result is discarded — those paths always refuse).
+ */
+let decoyHashPromise: Promise<string> | null = null;
+function decoyHash(): Promise<string> {
+  decoyHashPromise ??= hashPassword('bevel-decoy-password-never-matches');
+  return decoyHashPromise;
+}
+
 function toAuthUser(user: {
   id: string;
   email: string;
@@ -29,6 +47,21 @@ export class AuthService {
     private readonly config: CoreConfig,
   ) {}
 
+  /**
+   * Password login. Two credential sources, in order:
+   *
+   *  1. The env bootstrap admin (`ADMIN_EMAIL` + `ADMIN_PASSWORD`), checked
+   *     directly against the environment — never stored, so unsetting either
+   *     variable disables it immediately. Lets a fresh deployment sign in
+   *     before any account exists.
+   *  2. A per-user account: the `users` row's scrypt `password_hash`
+   *     (created by an admin from Roles & Members, or set by the user on
+   *     their Account page). Accounts that only ever signed in via SSO have
+   *     no hash and are refused here.
+   *
+   * A generic "Invalid credentials" error for every failure mode — never
+   * reveal whether the email exists or has a password.
+   */
   async loginWithPassword(
     email: string,
     password: string,
@@ -36,34 +69,54 @@ export class AuthService {
     const normalizedEmail = (email ?? '').trim().toLowerCase();
 
     if (!EMAIL_REGEX.test(normalizedEmail)) {
-      throw new Error('Invalid email');
+      throw new Error('Invalid credentials');
     }
     this.assertAllowedDomain(normalizedEmail);
-    if (!this.checkPassword(password ?? '')) {
-      throw new Error('Invalid password');
+
+    const provided = password ?? '';
+    const isEnvAdmin =
+      this.config.adminEmail.length > 0 &&
+      this.config.adminPassword.length > 0 &&
+      normalizedEmail === this.config.adminEmail &&
+      timingSafeStringEqual(provided, this.config.adminPassword);
+
+    if (isEnvAdmin) {
+      const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
+      const user = await this.upsertUserByEmail(normalizedEmail, defaultName);
+      return { token: this.signToken(user.id, user.email), user: toAuthUser(user) };
     }
 
-    // Derive a default display name from the local-part of the email
-    const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
-    const user = await this.upsertUserByEmail(normalizedEmail, defaultName);
+    const [user] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.email, normalizedEmail))
+      .limit(1);
+    // Always run one scrypt verification — against the stored hash when there
+    // is one, against the decoy otherwise — so unknown emails and
+    // password-less (SSO-only) accounts take the same time as a wrong
+    // password and can't be enumerated via response timing.
+    const stored = user?.passwordHash ?? (await decoyHash());
+    const matches = await verifyPassword(provided, stored);
+    if (!user?.passwordHash || !matches) {
+      throw new Error('Invalid credentials');
+    }
     return { token: this.signToken(user.id, user.email), user: toAuthUser(user) };
   }
 
   /**
-   * Establish a session for a user who authenticated via "Sign in with
-   * Microsoft". Same upsert-by-email + JWT path as password login — the only
-   * difference is identity came from a verified Microsoft id_token instead of
-   * the shared password. Email is the idempotency key, so a user who first
-   * used password login and later signs in with Microsoft (same email) keeps
-   * the same account/id.
+   * Establish a session for a user whose identity an SSO provider (the
+   * generic OIDC plugin, or the enterprise "Sign in with Microsoft") already
+   * verified. Same upsert-by-email + JWT path as password login. Email is the
+   * idempotency key, so a user who first used password login and later signs
+   * in via SSO (same email) keeps the same account/id.
    */
-  async loginWithMicrosoft(
+  async loginWithSso(
     email: string,
     name: string,
   ): Promise<{ token: string; user: AuthUser }> {
     const normalizedEmail = (email ?? '').trim().toLowerCase();
     if (!EMAIL_REGEX.test(normalizedEmail)) {
-      throw new Error('Microsoft sign-in returned an invalid email');
+      throw new Error('Sign-in returned an invalid email');
     }
     this.assertAllowedDomain(normalizedEmail);
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
@@ -71,6 +124,89 @@ export class AuthService {
     return { token: this.signToken(user.id, user.email), user: toAuthUser(user) };
   }
 
+  /**
+   * Admin-driven account provisioning (Roles & Members → Accounts). Upserts
+   * the user by email and sets their password — re-provisioning an existing
+   * account (e.g. one that first arrived via SSO, or a reset for a locked-out
+   * user) is deliberate admin behavior, not an error.
+   */
+  async createAccount(
+    email: string,
+    name: string | undefined,
+    password: string,
+  ): Promise<AuthUser> {
+    const normalizedEmail = (email ?? '').trim().toLowerCase();
+    if (!EMAIL_REGEX.test(normalizedEmail)) {
+      throw new Error('Invalid email');
+    }
+    this.assertAllowedDomain(normalizedEmail);
+    this.assertPasswordPolicy(password);
+    const suppliedName = (name ?? '').trim();
+    const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
+    const passwordHash = await hashPassword(password);
+    // One atomic upsert. On conflict (re-provisioning an existing account) an
+    // EXPLICITLY supplied name is persisted too; a blank name keeps the
+    // existing display name rather than clobbering it with the local-part
+    // fallback. `returning()` yields the authoritative row either way.
+    const [row] = await this.db
+      .insert(users)
+      .values({ email: normalizedEmail, name: displayName, passwordHash })
+      .onConflictDoUpdate({
+        target: users.email,
+        set: suppliedName
+          ? { passwordHash, name: suppliedName, updatedAt: new Date() }
+          : { passwordHash, updatedAt: new Date() },
+      })
+      .returning();
+    return toAuthUser(row);
+  }
+
+  /**
+   * Self-service password change (the Account page). The current password is
+   * required whenever one is set; an SSO-only account (no hash yet) may set
+   * its first password without one. The env bootstrap-admin credential is not
+   * affected — it lives in the environment, not in this row.
+   */
+  async changePassword(
+    userId: string,
+    currentPassword: string | undefined,
+    newPassword: string,
+  ): Promise<void> {
+    this.assertPasswordPolicy(newPassword);
+    const [user] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!user) throw new Error('User not found');
+    if (user.passwordHash) {
+      if (!currentPassword || !(await verifyPassword(currentPassword, user.passwordHash))) {
+        throw new Error('Current password is incorrect');
+      }
+    }
+    const passwordHash = await hashPassword(newPassword);
+    await this.db
+      .update(users)
+      .set({ passwordHash, updatedAt: new Date() })
+      .where(eq(users.id, userId));
+  }
+
+  /** Accounts overview for the admin management screen (never exposes hashes). */
+  async listAccounts(): Promise<
+    Array<{ id: string; email: string; name: string; hasPassword: boolean; createdAt: Date }>
+  > {
+    const rows = await this.db.select().from(users).orderBy(users.email);
+    return rows.map((row) => ({
+      id: row.id,
+      email: row.email,
+      name: row.name,
+      hasPassword: row.passwordHash != null,
+      createdAt: row.createdAt,
+    }));
+  }
+
+  private assertPasswordPolicy(password: string): void {
+    if ((password ?? '').length < MIN_PASSWORD_LENGTH) {
+      throw new Error(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+    }
+  }
+
   private signToken(userId: string, email: string): string {
     return jwt.sign({ userId, email }, this.config.jwtSecret, { expiresIn: '7d' });
   }
@@ -179,21 +315,4 @@ export class AuthService {
     }
   }
 
-  private checkPassword(provided: string): boolean {
-    const expected = this.config.testPassword;
-    // Reject if no password is configured on the server
-    if (!expected) return false;
-
-    const a = Buffer.from(provided, 'utf8');
-    const b = Buffer.from(expected, 'utf8');
-    // Pad both buffers to the same length so timingSafeEqual runs unconditionally —
-    // returning early on length mismatch would leak the expected password's length via timing.
-    const len = Math.max(a.length, b.length);
-    const aPadded = Buffer.alloc(len);
-    const bPadded = Buffer.alloc(len);
-    a.copy(aPadded);
-    b.copy(bPadded);
-    const equal = timingSafeEqual(aPadded, bPadded);
-    return equal && a.length === b.length;
-  }
 }

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

@@ -0,0 +1,229 @@
+import { createHash, randomBytes } from 'node:crypto';
+import type express from 'express';
+import type { AuthProviderPlugin } from './auth.routes.js';
+import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
+import { AUTH_COOKIE_NAME } from './auth.middleware.js';
+import type { AuthService } from './auth.service.js';
+
+// Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
+// redirecting to the provider, verified/consumed on callback.
+const OAUTH_STATE_COOKIE = 'oidc_oauth_state';
+const OAUTH_STATE_MAX_AGE_S = 10 * 60;
+
+/** The subset of the issuer's discovery document this provider consumes. */
+interface OidcDiscovery {
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint: string;
+}
+
+export interface OidcAuthProviderOptions {
+  /** Issuer base URL; `<issuer>/.well-known/openid-configuration` must exist. */
+  issuerUrl: string;
+  clientId: string;
+  clientSecret: string;
+  /** Space-separated; must include `openid` (and `email` for most providers). */
+  scopes: string;
+  /** Login-button label shown by the login screen. */
+  label: string;
+  publicBackendUrl: string;
+  publicFrontendUrl: string;
+  /** See MicrosoftAuthDeps.cookieSecure — scheme-derived, not NODE_ENV. */
+  cookieSecure: boolean;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Read one named cookie from the raw header (no cookie-parser dep, matching auth.middleware). */
+function readCookie(req: express.Request, name: string): string | null {
+  const header = req.headers.cookie;
+  if (!header) return null;
+  for (const segment of header.split(';')) {
+    const trimmed = segment.trim();
+    if (!trimmed.startsWith(`${name}=`)) continue;
+    const value = trimmed.slice(name.length + 1);
+    if (!value) return null;
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Generic OIDC single sign-on as an {@link AuthProviderPlugin} — works with
+ * any spec-compliant provider (Entra, Okta, Auth0, Keycloak, Google, …),
+ * configured purely from the environment (see CoreConfig `oidc*`).
+ *
+ * Flow: authorization-code with PKCE (S256) as a confidential client.
+ * Identity claims come from the `userinfo` endpoint called with the freshly
+ * exchanged access token — the token arrived over TLS directly from the
+ * issuer's token endpoint, so no local id_token signature verification (and
+ * no JWKS handling) is needed to trust it.
+ *
+ * Register `<PUBLIC_BACKEND_URL>/api/auth/oidc/callback` as the redirect URI
+ * with the provider.
+ */
+export class OidcAuthProvider implements AuthProviderPlugin {
+  readonly key = 'oidc';
+  readonly label: string;
+  readonly startPath = '/api/auth/oidc/login';
+
+  private readonly fetchImpl: typeof fetch;
+  private discovery: OidcDiscovery | null = null;
+
+  constructor(private readonly opts: OidcAuthProviderOptions) {
+    this.label = opts.label;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  /**
+   * Fetch + cache the issuer's discovery document. Resolved lazily (not at
+   * boot) so a temporarily unreachable issuer delays the first login instead
+   * of failing the whole deployment; a failed attempt is not cached.
+   */
+  private async discover(): Promise<OidcDiscovery> {
+    if (this.discovery) return this.discovery;
+    const url = `${this.opts.issuerUrl}/.well-known/openid-configuration`;
+    const res = await this.fetchImpl(url);
+    if (!res.ok) throw new Error(`OIDC discovery failed: ${res.status} ${url}`);
+    const doc = (await res.json()) as Partial<OidcDiscovery>;
+    if (!doc.authorization_endpoint || !doc.token_endpoint || !doc.userinfo_endpoint) {
+      throw new Error('OIDC discovery document is missing required endpoints');
+    }
+    this.discovery = {
+      authorization_endpoint: doc.authorization_endpoint,
+      token_endpoint: doc.token_endpoint,
+      userinfo_endpoint: doc.userinfo_endpoint,
+    };
+    return this.discovery;
+  }
+
+  private redirectUri(): string {
+    return `${this.opts.publicBackendUrl}/api/auth/oidc/callback`;
+  }
+
+  mountRoutes(router: express.Router, authService: AuthService): void {
+    const { publicFrontendUrl, cookieSecure } = this.opts;
+
+    // GET /api/auth/oidc/login — start the round-trip: mint state + PKCE
+    // verifier (both in one short-lived HttpOnly cookie), redirect to the
+    // provider's authorization endpoint.
+    router.get('/auth/oidc/login', async (_req, res) => {
+      try {
+        const discovery = await this.discover();
+        const state = randomBytes(16).toString('hex');
+        const verifier = randomBytes(32).toString('base64url');
+        const challenge = createHash('sha256').update(verifier).digest('base64url');
+        res.cookie(OAUTH_STATE_COOKIE, `${state}.${verifier}`, {
+          httpOnly: true,
+          sameSite: 'lax',
+          secure: cookieSecure,
+          maxAge: OAUTH_STATE_MAX_AGE_S * 1000,
+          path: '/',
+        });
+        const url = new URL(discovery.authorization_endpoint);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', this.opts.clientId);
+        url.searchParams.set('redirect_uri', this.redirectUri());
+        url.searchParams.set('scope', this.opts.scopes);
+        url.searchParams.set('state', state);
+        url.searchParams.set('code_challenge', challenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        res.redirect(url.toString());
+      } catch (error) {
+        console.error('OIDC start error:', error instanceof Error ? error.message : error);
+        res.redirect(`${publicFrontendUrl}/auth/oidc/callback#error=start`);
+      }
+    });
+
+    // GET /api/auth/oidc/callback — verify state, exchange the code (PKCE +
+    // client secret), read identity from userinfo, issue the app JWT, and hand
+    // it to the frontend in the URL fragment (kept out of query/logs/Referer).
+    router.get('/auth/oidc/callback', async (req, res) => {
+      const fail = (reason: string) =>
+        res.redirect(`${publicFrontendUrl}/auth/oidc/callback#error=${reason}`);
+      try {
+        const { code, state } = req.query as { code?: string; state?: string };
+        const cookie = readCookie(req, OAUTH_STATE_COOKIE);
+        res.clearCookie(OAUTH_STATE_COOKIE, { path: '/' });
+        const [expectedState, verifier] = cookie?.split('.') ?? [];
+        if (!code || !state || !expectedState || !verifier || state !== expectedState) {
+          fail('state');
+          return;
+        }
+
+        const discovery = await this.discover();
+        const basic = Buffer.from(
+          `${encodeURIComponent(this.opts.clientId)}:${encodeURIComponent(this.opts.clientSecret)}`,
+          'utf8',
+        ).toString('base64');
+        const tokenRes = await this.fetchImpl(discovery.token_endpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Authorization: `Basic ${basic}`,
+          },
+          body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: this.redirectUri(),
+            code_verifier: verifier,
+          }).toString(),
+        });
+        if (!tokenRes.ok) {
+          console.error('OIDC token exchange failed:', tokenRes.status, await tokenRes.text().catch(() => ''));
+          fail('auth');
+          return;
+        }
+        const tokens = (await tokenRes.json()) as { access_token?: string };
+        if (!tokens.access_token) {
+          fail('auth');
+          return;
+        }
+
+        const infoRes = await this.fetchImpl(discovery.userinfo_endpoint, {
+          headers: { Authorization: `Bearer ${tokens.access_token}` },
+        });
+        if (!infoRes.ok) {
+          console.error('OIDC userinfo failed:', infoRes.status);
+          fail('auth');
+          return;
+        }
+        const claims = (await infoRes.json()) as {
+          email?: string;
+          name?: string;
+          preferred_username?: string;
+          given_name?: string;
+          family_name?: string;
+        };
+        if (!claims.email) {
+          // Most likely a missing `email` scope / claim mapping at the provider.
+          console.error('OIDC userinfo returned no email claim');
+          fail('auth');
+          return;
+        }
+        const name =
+          claims.name ??
+          [claims.given_name, claims.family_name].filter(Boolean).join(' ').trim() ??
+          claims.preferred_username ??
+          '';
+
+        const { token } = await authService.loginWithSso(claims.email, name);
+        res.cookie(AUTH_COOKIE_NAME, token, {
+          httpOnly: true,
+          sameSite: 'lax',
+          secure: cookieSecure,
+          maxAge: AUTH_COOKIE_MAX_AGE_S * 1000,
+          path: '/',
+        });
+        res.redirect(`${publicFrontendUrl}/auth/oidc/callback#token=${encodeURIComponent(token)}`);
+      } catch (error) {
+        console.error('OIDC callback error:', error instanceof Error ? error.message : error);
+        fail('auth');
+      }
+    });
+  }
+}

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

@@ -0,0 +1,80 @@
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Password hashing for per-user accounts: scrypt via node:crypto — memory-hard
+ * (unlike sha/hmac), built in (no native bcrypt/argon dependency), async so a
+ * login burst doesn't block the event loop.
+ *
+ * Stored format: `scrypt:N=<cost>,r=<block>,p=<par>:<salt b64url>:<key b64url>`
+ * — parameters travel with the hash, so costs can be raised later while old
+ * hashes keep verifying (and get re-hashed on next successful login/change).
+ */
+
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const KEY_LEN = 32;
+const SALT_LEN = 16;
+
+/** Guard rail surfaced by the routes as a 400 — not a silent truncation. */
+export const MIN_PASSWORD_LENGTH = 8;
+
+function scryptAsync(
+  password: string,
+  salt: Buffer,
+  params: { N: number; r: number; p: number },
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(
+      password,
+      salt,
+      KEY_LEN,
+      // maxmem must accommodate 128*N*r bytes; default (32 MiB) is exactly at
+      // the boundary for N=16384,r=8 — give it headroom.
+      { N: params.N, r: params.r, p: params.p, maxmem: 128 * params.N * params.r * 2 },
+      (err, key) => (err ? reject(err) : resolve(key)),
+    );
+  });
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_LEN);
+  const key = await scryptAsync(password, salt, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P });
+  return `scrypt:N=${SCRYPT_N},r=${SCRYPT_R},p=${SCRYPT_P}:${salt.toString('base64url')}:${key.toString('base64url')}`;
+}
+
+/** Constant-time verify of `password` against a stored {@link hashPassword} string. */
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const match = /^scrypt:N=(\d+),r=(\d+),p=(\d+):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+)$/.exec(stored);
+  if (!match) return false;
+  const [, n, r, p, saltB64, keyB64] = match;
+  const salt = Buffer.from(saltB64, 'base64url');
+  const expected = Buffer.from(keyB64, 'base64url');
+  try {
+    const actual = await scryptAsync(password, salt, {
+      N: Number(n),
+      r: Number(r),
+      p: Number(p),
+    });
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+  } catch {
+    // Absurd parameters (corrupted row / DoS-shaped input) — fail closed.
+    return false;
+  }
+}
+
+/**
+ * Constant-time comparison of two plaintext secrets (the env bootstrap-admin
+ * check). Pads to a common length so a length mismatch doesn't return early
+ * and leak the expected secret's length via timing.
+ */
+export function timingSafeStringEqual(provided: string, expected: string): boolean {
+  const a = Buffer.from(provided, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  const len = Math.max(a.length, b.length, 1);
+  const aPadded = Buffer.alloc(len);
+  const bPadded = Buffer.alloc(len);
+  a.copy(aPadded);
+  b.copy(bPadded);
+  return timingSafeEqual(aPadded, bPadded) && a.length === b.length;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Tiny fixed-window in-memory rate limiter for the password endpoints —
+ * brute-force / scrypt-DoS protection, not traffic shaping. In-memory is the
+ * right scope for the single-instance deployment model (same assumption as
+ * the MCP session store); a multi-replica future moves this behind a shared
+ * store.
+ *
+ * Expired windows are pruned opportunistically on each hit so the map stays
+ * bounded by the number of DISTINCT active keys per window.
+ */
+export class FixedWindowRateLimiter {
+  private readonly hits = new Map<string, { count: number; resetAt: number }>();
+
+  constructor(
+    /** Attempts allowed per window per key. */
+    private readonly max: number,
+    private readonly windowMs: number,
+    /** Injectable clock for tests. */
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * Record one attempt for `key`; returns true when the attempt is ALLOWED
+   * (i.e. the key is within its budget for the current window).
+   */
+  consume(key: string): boolean {
+    const now = this.now();
+    for (const [k, entry] of this.hits) {
+      if (entry.resetAt <= now) this.hits.delete(k);
+    }
+    const entry = this.hits.get(key);
+    if (!entry || entry.resetAt <= now) {
+      this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
+      return true;
+    }
+    entry.count += 1;
+    return entry.count <= this.max;
+  }
+
+  /** Clear a key's window — called after a SUCCESSFUL login so legitimate
+   * users who fumbled a few attempts aren't locked out of their next visit. */
+  reset(key: string): void {
+    this.hits.delete(key);
+  }
+}