@bevel-software/platform-core-backend 0.1.1 → 0.2.1

package/src/core-config.ts

@@ -43,7 +43,32 @@ export class CoreConfig {
    */
   readonly spillRoot: string;
   readonly jwtSecret: string;
-  readonly testPassword: string;
+  /**
+   * Bootstrap admin credential, checked directly against the environment at
+   * login time (never stored). Lets a fresh deployment sign in before any
+   * account exists; that admin (or any user with the Admin role in
+   * `roles.yaml`) then creates per-user accounts from Roles & Members.
+   * Remove EITHER variable and the credential stops working immediately —
+   * accounts created in the database are unaffected. The email is also
+   * always recognized as an admin (see AdminAccessService), so a fresh KB
+   * whose `roles.yaml` doesn't list it yet is still administrable.
+   */
+  readonly adminEmail: string;
+  readonly adminPassword: string;
+  /**
+   * Generic OIDC single sign-on (any spec-compliant provider: Entra, Okta,
+   * Auth0, Keycloak, Google, …). Enabled when issuer URL + client id + client
+   * secret are ALL set; the issuer's `/.well-known/openid-configuration` is
+   * discovered at first use. The redirect URI to register with the provider is
+   * `<PUBLIC_BACKEND_URL>/api/auth/oidc/callback`.
+   */
+  readonly oidcIssuerUrl: string;
+  readonly oidcClientId: string;
+  readonly oidcClientSecret: string;
+  /** Space-separated scopes requested (default `openid profile email`). */
+  readonly oidcScopes: string;
+  /** Login-button label (default "Single sign-on"). */
+  readonly oidcProviderLabel: string;
   /** Clone/push URL for the KB repo. Any https git host (GitHub, GitLab, Bitbucket, Azure DevOps, self-hosted). */
   readonly kbRepoUrl: string;
   /** Directory name the KB lives under inside each user's workspace dir. */
@@ -115,6 +140,16 @@ export class CoreConfig {
    * independently of user sessions.
    */
   readonly internalTokenSecret: string;
+  /**
+   * Express `trust proxy` setting, from `TRUST_PROXY`: the number of reverse
+   * proxy hops in front of this backend (e.g. `1`), or an address/CIDR list
+   * (`loopback`, `10.0.0.0/8`). Unset (default) → forwarded headers are
+   * IGNORED and `req.ip` is the socket peer — correct for direct exposure,
+   * but behind a proxy it makes every client share the proxy's IP (so the
+   * per-IP login rate limit would pool all users). Set it to the actual hop
+   * count — never a blanket trust — so clients can't spoof X-Forwarded-For.
+   */
+  readonly trustProxy: string;
   /**
    * Public base URL of THIS backend, used to build OAuth redirect URIs.
    * Must match a redirect URI registered with the OAuth provider(s).
@@ -137,7 +172,24 @@ export class CoreConfig {
     this.backupsRoot = process.env.BACKUPS_ROOT || path.resolve(this.workspacesRoot, '..', 'backups');
     this.spillRoot = process.env.SPILL_ROOT || path.resolve(this.workspacesRoot, '..', 'tool-chain-spills');
     this.jwtSecret = process.env.JWT_SECRET || '';
-    this.testPassword = process.env.TEST_PASSWORD || '';
+    this.adminEmail = (process.env.ADMIN_EMAIL || '').trim().toLowerCase();
+    this.adminPassword = process.env.ADMIN_PASSWORD || '';
+    if (this.adminEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(this.adminEmail)) {
+      throw new Error(`ADMIN_EMAIL is not a valid email: "${this.adminEmail}"`);
+    }
+    this.oidcIssuerUrl = (process.env.OIDC_ISSUER_URL || '').trim().replace(/\/+$/, '');
+    this.oidcClientId = (process.env.OIDC_CLIENT_ID || '').trim();
+    this.oidcClientSecret = (process.env.OIDC_CLIENT_SECRET || '').trim();
+    this.oidcScopes = (process.env.OIDC_SCOPES || 'openid profile email').trim();
+    this.oidcProviderLabel = (process.env.OIDC_PROVIDER_LABEL || 'Single sign-on').trim();
+    if (this.oidcIssuerUrl) {
+      // Parse-validate so a typo'd issuer fails at boot, not at first login.
+      try {
+        new URL(this.oidcIssuerUrl);
+      } catch {
+        throw new Error(`OIDC_ISSUER_URL is not a valid URL: "${this.oidcIssuerUrl}"`);
+      }
+    }
     // No default: the KB repo is deployment-specific, and a wrong fallback
     // would surface much later as a confusing clone failure. Fail at boot.
     this.kbRepoUrl = (process.env.KB_REPO_URL || '').trim();
@@ -185,6 +237,7 @@ export class CoreConfig {
       ''
     ).trim();
     this.internalTokenSecret = (process.env.INTERNAL_TOKEN_SECRET || '').trim();
+    this.trustProxy = (process.env.TRUST_PROXY || '').trim();
     this.publicBackendUrl = (process.env.PUBLIC_BACKEND_URL || `http://localhost:${this.port}`)
       .trim()
       .replace(/\/+$/, '');

package/src/modules/admin/admin-access.service.ts

@@ -18,10 +18,20 @@ export class AdminAccessService implements IAdminAccessService {
     private readonly workspaceService: WorkspaceService,
     /** Branch whose `roles.yaml` defines admins (the authoritative default branch). */
     private readonly branch: string,
+    /**
+     * Emails treated as admin WITHOUT consulting `roles.yaml` — the env
+     * bootstrap admin (`ADMIN_EMAIL`). A fresh deployment's KB may not list
+     * that email yet, and the bootstrap credential must be able to administer
+     * accounts/roles regardless; membership here tracks the env var, so
+     * removing the var removes the privilege.
+     */
+    private readonly alwaysAdminEmails: string[] = [],
   ) {}
 
   async isAdmin(email: string | undefined): Promise<boolean> {
     if (!email) return false;
+    const normalized = email.trim().toLowerCase();
+    if (this.alwaysAdminEmails.includes(normalized)) return true;
     try {
       // Ensure the authoritative clone is on disk, then resolve Admin-role
       // membership via the access model. Any failure (missing/invalid

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

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAccountRoutes } from '../account.routes.js';
+import type { AuthService } from '../auth.service.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+
+const authService = {
+  listAccounts: vi.fn(async () => [
+    { id: 'u1', email: 'a@example.com', name: 'A', hasPassword: true, createdAt: new Date() },
+  ]),
+  createAccount: vi.fn(async (email: string) => ({ id: 'u2', email, name: 'B' })),
+} as unknown as AuthService;
+
+function makeApp(opts: { admin: boolean; email?: string }) {
+  const adminAccess: IAdminAccessService = {
+    isAdmin: vi.fn(async () => opts.admin),
+  };
+  const app = express();
+  app.use(express.json());
+  // Stand-in auth middleware: stamps the caller identity the way the real JWT
+  // middleware does.
+  app.use((req, _res, next) => {
+    req.userId = 'u1';
+    req.userEmail = opts.email ?? 'caller@example.com';
+    next();
+  });
+  app.use('/api', createAccountRoutes(authService, adminAccess));
+  return app;
+}
+
+let server: Server;
+afterEach(() => {
+  server?.close();
+  vi.mocked(authService.createAccount).mockClear();
+});
+
+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}`;
+}
+
+describe('account routes — admin gate', () => {
+  it('refuses non-admins on both endpoints', async () => {
+    const base = await listen(makeApp({ admin: false }));
+    const list = await fetch(`${base}/api/admin/accounts`);
+    expect(list.status).toBe(403);
+    const create = await fetch(`${base}/api/admin/accounts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'x@example.com', password: 'long-enough-pw' }),
+    });
+    expect(create.status).toBe(403);
+    expect(authService.createAccount).not.toHaveBeenCalled();
+  });
+
+  it('serves admins: list + create', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const list = await fetch(`${base}/api/admin/accounts`);
+    expect(list.status).toBe(200);
+    const listBody = (await list.json()) as { accounts: Array<{ email: string }> };
+    expect(listBody.accounts[0].email).toBe('a@example.com');
+
+    const create = await fetch(`${base}/api/admin/accounts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'b@example.com', name: 'B', password: 'long-enough-pw' }),
+    });
+    expect(create.status).toBe(201);
+    expect(authService.createAccount).toHaveBeenCalledWith('b@example.com', 'B', 'long-enough-pw');
+  });
+
+  it('400s on missing fields and surfaces service validation errors', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const missing = await fetch(`${base}/api/admin/accounts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'b@example.com' }),
+    });
+    expect(missing.status).toBe(400);
+
+    vi.mocked(authService.createAccount).mockRejectedValueOnce(
+      new Error('Password must be at least 8 characters'),
+    );
+    const tooShort = await fetch(`${base}/api/admin/accounts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'b@example.com', password: 'short' }),
+    });
+    expect(tooShort.status).toBe(400);
+    const body = (await tooShort.json()) as { error: string };
+    expect(body.error).toContain('at least 8');
+  });
+});

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

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAuthRoutes } from '../auth.routes.js';
+import type { AuthService } from '../auth.service.js';
+
+const authService = {
+  loginWithPassword: vi.fn(async () => {
+    throw new Error('Invalid credentials');
+  }),
+  changePassword: vi.fn(async () => {
+    throw new Error('Current password is incorrect');
+  }),
+  getUserById: vi.fn(async () => null),
+} as unknown as AuthService;
+
+const fakeAuthMiddleware: express.RequestHandler = (req, _res, next) => {
+  req.userId = 'user-1';
+  req.userEmail = 'alice@example.com';
+  next();
+};
+
+let server: Server;
+beforeEach(() => {
+  vi.mocked(authService.loginWithPassword).mockClear();
+});
+afterEach(() => {
+  server?.close();
+});
+
+async function listen(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createAuthRoutes(authService, fakeAuthMiddleware));
+  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}`;
+}
+
+function postLogin(base: string, email: string, password = 'wrong') {
+  return fetch(`${base}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+}
+
+describe('auth routes — rate limiting', () => {
+  it('429s login for an (ip, email) pair after repeated failures; other emails unaffected', async () => {
+    const base = await listen();
+    for (let i = 0; i < 10; i++) {
+      expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
+    }
+    const limited = await postLogin(base, 'alice@example.com');
+    expect(limited.status).toBe(429);
+    // The service is not even consulted once the limit is hit.
+    expect(authService.loginWithPassword).toHaveBeenCalledTimes(10);
+    // A different email from the same address still has pair budget (the
+    // wider per-ip budget is 50).
+    expect((await postLogin(base, 'bob@example.com')).status).toBe(401);
+  });
+
+  it('a successful login resets the pair budget', async () => {
+    const base = await listen();
+    for (let i = 0; i < 9; i++) await postLogin(base, 'alice@example.com');
+    vi.mocked(authService.loginWithPassword).mockResolvedValueOnce({
+      token: 'jwt',
+      user: { id: 'user-1', email: 'alice@example.com', name: 'Alice' },
+    });
+    expect((await postLogin(base, 'alice@example.com', 'right')).status).toBe(200);
+    // Budget is fresh again — failures start counting from zero.
+    expect((await postLogin(base, 'alice@example.com')).status).toBe(401);
+  });
+
+  it('429s change-password per account after repeated failures', async () => {
+    const base = await listen();
+    const post = () =>
+      fetch(`${base}/api/auth/change-password`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ currentPassword: 'wrong', newPassword: 'new-password-1' }),
+      });
+    for (let i = 0; i < 10; i++) {
+      expect((await post()).status).toBe(400);
+    }
+    expect((await post()).status).toBe(429);
+  });
+});

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

@@ -0,0 +1,217 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Database } from '../../database/connection.js';
+import type { CoreConfig } from '../../../core-config.js';
+import { AuthService } from '../auth.service.js';
+import { hashPassword } from '../password-hash.js';
+
+/**
+ * Minimal drizzle chain stub (same idiom as the secrets-vault tests): each
+ * db.select()/insert()/update() consumes the next queued result; awaiting any
+ * point of the chain resolves it.
+ */
+interface FakeChain extends PromiseLike<unknown> {
+  values: (...args: unknown[]) => FakeChain;
+  set: (...args: unknown[]) => FakeChain;
+  where: (...args: unknown[]) => FakeChain;
+  limit: (...args: unknown[]) => FakeChain;
+  from: (...args: unknown[]) => FakeChain;
+  orderBy: (...args: unknown[]) => FakeChain;
+  returning: (...args: unknown[]) => FakeChain;
+  onConflictDoUpdate: (...args: unknown[]) => FakeChain;
+}
+
+function makeFakeDb(queue: unknown[]) {
+  const captured: { values: unknown[]; set: unknown[]; conflict: unknown[] } = {
+    values: [],
+    set: [],
+    conflict: [],
+  };
+  function nextChain(): FakeChain {
+    const result = queue.shift();
+    const passthrough = (recorder?: (args: unknown[]) => void) =>
+      vi.fn((...args: unknown[]) => {
+        recorder?.(args);
+        return chain;
+      });
+    const chain: FakeChain = {
+      values: passthrough((a) => captured.values.push(a[0])),
+      set: passthrough((a) => captured.set.push(a[0])),
+      where: passthrough(),
+      limit: passthrough(),
+      from: passthrough(),
+      orderBy: passthrough(),
+      returning: passthrough(),
+      onConflictDoUpdate: passthrough((a) => captured.conflict.push(a[0])),
+      then: (onFulfilled, onRejected) => Promise.resolve(result).then(onFulfilled, onRejected),
+    };
+    return chain;
+  }
+  const db = {
+    insert: vi.fn(() => nextChain()),
+    select: vi.fn(() => nextChain()),
+    update: vi.fn(() => nextChain()),
+  } as unknown as Database;
+  return { db, captured };
+}
+
+function makeConfig(over: Partial<CoreConfig> = {}): CoreConfig {
+  return {
+    jwtSecret: 'test-jwt-secret',
+    adminEmail: '',
+    adminPassword: '',
+    allowedEmailDomains: [],
+    ...over,
+  } as CoreConfig;
+}
+
+const ROW = {
+  id: 'user-1',
+  email: 'alice@example.com',
+  name: 'Alice',
+  avatarUrl: null,
+};
+
+describe('AuthService.loginWithPassword — env bootstrap admin', () => {
+  const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
+
+  it('signs in the env admin and upserts their user row', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com', name: 'root' }]]);
+    const svc = new AuthService(db, config);
+    const result = await svc.loginWithPassword('Root@Example.com', 'sup3r-secret');
+    expect(result.user.email).toBe('root@example.com');
+    expect(result.token.length).toBeGreaterThan(20);
+  });
+
+  it('rejects the admin email with a wrong password (and does not fall back oddly)', async () => {
+    // Wrong env password → falls through to the DB path; no row → refused.
+    const { db } = makeFakeDb([[]]);
+    const svc = new AuthService(db, config);
+    await expect(svc.loginWithPassword('root@example.com', 'wrong')).rejects.toThrow(
+      'Invalid credentials',
+    );
+  });
+
+  it('is disabled entirely when either env var is empty', async () => {
+    for (const cfg of [
+      makeConfig({ adminEmail: 'root@example.com', adminPassword: '' }),
+      makeConfig({ adminEmail: '', adminPassword: 'sup3r-secret' }),
+    ]) {
+      const { db } = makeFakeDb([[]]);
+      const svc = new AuthService(db, cfg);
+      await expect(svc.loginWithPassword('root@example.com', 'sup3r-secret')).rejects.toThrow(
+        'Invalid credentials',
+      );
+    }
+  });
+});
+
+describe('AuthService.loginWithPassword — per-user accounts', () => {
+  it('accepts a user whose stored hash matches', async () => {
+    const passwordHash = await hashPassword('alices-password');
+    const { db } = makeFakeDb([[{ ...ROW, passwordHash }]]);
+    const svc = new AuthService(db, makeConfig());
+    const result = await svc.loginWithPassword('alice@example.com', 'alices-password');
+    expect(result.user.id).toBe('user-1');
+  });
+
+  it('rejects a wrong password and an account with no password set', async () => {
+    const passwordHash = await hashPassword('alices-password');
+    const withHash = makeFakeDb([[{ ...ROW, passwordHash }]]);
+    await expect(
+      new AuthService(withHash.db, makeConfig()).loginWithPassword('alice@example.com', 'nope'),
+    ).rejects.toThrow('Invalid credentials');
+
+    // SSO-only account: row exists but has no hash.
+    const noHash = makeFakeDb([[{ ...ROW, passwordHash: null }]]);
+    await expect(
+      new AuthService(noHash.db, makeConfig()).loginWithPassword('alice@example.com', 'anything'),
+    ).rejects.toThrow('Invalid credentials');
+  });
+
+  it('never leaks whether the email exists — same error for unknown emails', async () => {
+    const { db } = makeFakeDb([[]]);
+    await expect(
+      new AuthService(db, makeConfig()).loginWithPassword('ghost@example.com', 'whatever'),
+    ).rejects.toThrow('Invalid credentials');
+  });
+});
+
+describe('AuthService.createAccount / changePassword', () => {
+  it('createAccount upserts the user in ONE query and stores a verifying hash', async () => {
+    const { db, captured } = makeFakeDb([[ROW]]);
+    const svc = new AuthService(db, makeConfig());
+    const user = await svc.createAccount('alice@example.com', 'Alice', 'brand-new-pass');
+    expect(user.email).toBe('alice@example.com');
+    // Insert values carry the hash; the conflict branch re-sets it too.
+    const values = captured.values[0] as { passwordHash: string; name: string };
+    expect(values.passwordHash.startsWith('scrypt:')).toBe(true);
+    expect(values.name).toBe('Alice');
+    const conflict = captured.conflict[0] as { set: { passwordHash: string } };
+    expect(conflict.set.passwordHash.startsWith('scrypt:')).toBe(true);
+  });
+
+  it('createAccount persists an explicitly supplied name on re-provisioning', async () => {
+    // Existing row conflicts; admin re-provisions with a new name.
+    const { db, captured } = makeFakeDb([[{ ...ROW, name: 'Alice Lidell' }]]);
+    const svc = new AuthService(db, makeConfig());
+    const user = await svc.createAccount('alice@example.com', 'Alice Lidell', 'brand-new-pass');
+    const conflict = captured.conflict[0] as { set: { name?: string } };
+    expect(conflict.set.name).toBe('Alice Lidell');
+    expect(user.name).toBe('Alice Lidell');
+  });
+
+  it('createAccount without a name keeps the existing display name on conflict', async () => {
+    const { db, captured } = makeFakeDb([[ROW]]);
+    const svc = new AuthService(db, makeConfig());
+    const user = await svc.createAccount('alice@example.com', undefined, 'brand-new-pass');
+    const conflict = captured.conflict[0] as { set: { name?: string } };
+    expect(conflict.set.name).toBeUndefined();
+    expect(user.name).toBe('Alice');
+  });
+
+  it('createAccount enforces the password policy', async () => {
+    const { db } = makeFakeDb([]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.createAccount('alice@example.com', 'Alice', 'short')).rejects.toThrow(
+      /at least/,
+    );
+  });
+
+  it('changePassword requires the current password once one is set', async () => {
+    const passwordHash = await hashPassword('old-password');
+    const wrong = makeFakeDb([[{ ...ROW, passwordHash }]]);
+    await expect(
+      new AuthService(wrong.db, makeConfig()).changePassword('user-1', 'not-it', 'new-password-1'),
+    ).rejects.toThrow('Current password is incorrect');
+
+    const right = makeFakeDb([[{ ...ROW, passwordHash }], undefined]);
+    await expect(
+      new AuthService(right.db, makeConfig()).changePassword('user-1', 'old-password', 'new-password-1'),
+    ).resolves.toBeUndefined();
+  });
+
+  it('changePassword lets an SSO-only account set its first password without one', async () => {
+    const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: null }], undefined]);
+    await new AuthService(db, makeConfig()).changePassword('user-1', undefined, 'first-password');
+    const set = captured.set[0] as { passwordHash: string };
+    expect(set.passwordHash.startsWith('scrypt:')).toBe(true);
+  });
+});
+
+describe('AuthService.listAccounts', () => {
+  it('reports hasPassword without ever exposing the hash', async () => {
+    const passwordHash = await hashPassword('pw-longer-than-8');
+    const { db } = makeFakeDb([
+      [
+        { ...ROW, passwordHash, createdAt: new Date() },
+        { ...ROW, id: 'user-2', email: 'bob@example.com', name: 'Bob', passwordHash: null, createdAt: new Date() },
+      ],
+    ]);
+    const accounts = await new AuthService(db, makeConfig()).listAccounts();
+    expect(accounts.map((a) => [a.email, a.hasPassword])).toEqual([
+      ['alice@example.com', true],
+      ['bob@example.com', false],
+    ]);
+    expect(JSON.stringify(accounts)).not.toContain('scrypt:');
+  });
+});