@bevel-software/platform-core-backend 0.22.0 → 0.23.0

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

@@ -3,7 +3,7 @@ import express from 'express';
 import type { Server } from 'node:http';
 import { createAccountRoutes } from '../account.routes.js';
 import { AuthService } from '../auth.service.js';
-import { AccountAdmissionRefusedError } from '../account-admission.js';
+import { AccountAdmissionRefusedError, AccountChangeRefusedError } from '../account-admission.js';
 import { hashPassword } from '../password-hash.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
@@ -13,6 +13,8 @@ const authService = {
     { id: 'u1', email: 'a@example.com', name: 'A', hasPassword: true, createdAt: new Date() },
   ]),
   createAccount: vi.fn(async (email: string) => ({ id: 'u2', email, name: 'B' })),
+  deactivate: vi.fn(async (userId: string) => userId !== 'missing'),
+  reactivate: vi.fn(async (userId: string) => userId !== 'missing'),
 } as unknown as AuthService;
 
 // Satisfies the route's narrow Pick<IAccountErasureService, 'eraseUser'>
@@ -172,12 +174,12 @@ describe('account routes — admin gate', () => {
     expect(JSON.stringify(body)).not.toContain('relation');
   });
 
-  it('400s on missing fields and surfaces service validation errors', async () => {
+  it('400s without an email (a password is optional) 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' }),
+      body: JSON.stringify({ name: 'B' }),
     });
     expect(missing.status).toBe(400);
 
@@ -326,3 +328,79 @@ describe('account routes — removing the erased address from access files', ()
     expect(accessRemoval.remove).not.toHaveBeenCalled();
   });
 });
+
+describe('account routes — switching an account off and on', () => {
+  const post = (base: string, path: string) => fetch(`${base}/api/admin/accounts/${path}`, { method: 'POST' });
+
+  it('switches another account off and back on', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    expect((await post(base, 'u2/deactivate')).status).toBe(204);
+    expect(authService.deactivate).toHaveBeenCalledWith('u2');
+    expect((await post(base, 'u2/reactivate')).status).toBe(204);
+    expect(authService.reactivate).toHaveBeenCalledWith('u2');
+  });
+
+  it('refuses an admin switching off their own account, so an admin who can sign in always remains', async () => {
+    vi.mocked(authService.deactivate).mockClear();
+    const base = await listen(makeApp({ admin: true }));
+    const res = await post(base, 'u1/deactivate');
+    expect(res.status).toBe(400);
+    expect(authService.deactivate).not.toHaveBeenCalled();
+  });
+
+  it('refuses non-admins', async () => {
+    vi.mocked(authService.deactivate).mockClear();
+    const base = await listen(makeApp({ admin: false }));
+    expect((await post(base, 'u2/deactivate')).status).toBe(403);
+    expect((await post(base, 'u2/reactivate')).status).toBe(403);
+    expect(authService.deactivate).not.toHaveBeenCalled();
+  });
+
+  it('404s for an account that does not exist', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    expect((await post(base, 'missing/deactivate')).status).toBe(404);
+    expect((await post(base, 'missing/reactivate')).status).toBe(404);
+  });
+
+  it("answers a reactivation the deployment has no room for with 403 and the port's words", async () => {
+    vi.mocked(authService.reactivate).mockRejectedValueOnce(new AccountAdmissionRefusedError('All 3 seats are taken'));
+    const base = await listen(makeApp({ admin: true }));
+    const res = await post(base, 'u2/reactivate');
+    expect(res.status).toBe(403);
+    expect(((await res.json()) as { error: string }).error).toBe('All 3 seats are taken');
+  });
+
+  it('answers a refused deactivation (the deployment admin, say) with 400 and the reason', async () => {
+    vi.mocked(authService.deactivate).mockRejectedValueOnce(new AccountChangeRefusedError('The deployment admin cannot be switched off'));
+    const base = await listen(makeApp({ admin: true }));
+    const res = await post(base, 'u2/deactivate');
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { error: string }).error).toContain('deployment admin');
+  });
+
+  it('answers an unexpected failure with a 500 that names nothing of it', async () => {
+    vi.mocked(authService.deactivate).mockRejectedValueOnce(new Error('relation "users" does not exist'));
+    vi.mocked(authService.reactivate).mockRejectedValueOnce(new Error('relation "users" does not exist'));
+    const base = await listen(makeApp({ admin: true }));
+    const off = await post(base, 'u2/deactivate');
+    expect(off.status).toBe(500);
+    expect(JSON.stringify(await off.json())).not.toContain('relation');
+    const on = await post(base, 'u2/reactivate');
+    expect(on.status).toBe(500);
+    expect(JSON.stringify(await on.json())).not.toContain('relation');
+  });
+
+  it('refuses a password that is not a string, rather than making an account for single sign-on', async () => {
+    vi.mocked(authService.createAccount).mockClear();
+    const base = await listen(makeApp({ admin: true }));
+    for (const password of [false, null, 0]) {
+      const res = await fetch(`${base}/api/admin/accounts`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: 'b@example.com', password }),
+      });
+      expect(res.status).toBe(400);
+    }
+    expect(authService.createAccount).not.toHaveBeenCalled();
+  });
+});

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

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import type { Request, Response, NextFunction } from 'express';
 import { createAuthMiddleware, AUTH_COOKIE_NAME } from '../auth.middleware.js';
+import { AccountDeactivatedError, AuthBackendError } from '../account-admission.js';
 import type { AuthService } from '../auth.service.js';
 
 /**
@@ -11,68 +12,90 @@ import type { AuthService } from '../auth.service.js';
  */
 
 const GOOD_TOKEN = 'good-token';
+const OFF_TOKEN = 'switched-off-token';
+const DOWN_TOKEN = 'database-down-token';
 const IDENTITY = { userId: 'user-1', email: 'alice@example.com' };
 
-function run(headers: Record<string, string>) {
-  const verifyToken = vi.fn((token: string) => {
+async function run(headers: Record<string, string>) {
+  const resolveSession = vi.fn(async (token: string) => {
+    if (token === OFF_TOKEN) throw new AccountDeactivatedError();
+    if (token === DOWN_TOKEN) throw new AuthBackendError(new Error('db down'));
     if (token !== GOOD_TOKEN) throw new Error('bad token');
     return IDENTITY;
   });
-  const authService = { verifyToken } as unknown as AuthService;
+  const authService = { resolveSession } as unknown as AuthService;
   const req = { headers } as unknown as Request;
   const json = vi.fn();
   const status = vi.fn(() => ({ json }));
   const res = { status } as unknown as Response;
   const next = vi.fn() as unknown as NextFunction;
-  createAuthMiddleware(authService)(req, res, next);
-  return { req, next, status, json, verifyToken };
+  await createAuthMiddleware(authService)(req, res, next);
+  return { req, next, status, json, resolveSession };
 }
 
-describe('createAuthMiddleware', () => {
-  it('authenticates a request that carries only the auth cookie (an <img>, an EventSource)', () => {
-    const { req, next, status } = run({ cookie: `${AUTH_COOKIE_NAME}=${GOOD_TOKEN}` });
+describe('createAuthMiddleware', async () => {
+  it('authenticates a request that carries only the auth cookie (an <img>, an EventSource)', async () => {
+    const { req, next, status } = await run({ cookie: `${AUTH_COOKIE_NAME}=${GOOD_TOKEN}` });
     expect(next).toHaveBeenCalledTimes(1);
     expect(status).not.toHaveBeenCalled();
     expect(req.userId).toBe(IDENTITY.userId);
     expect(req.userEmail).toBe(IDENTITY.email);
   });
 
-  it('finds the cookie among others, and decodes a percent-encoded value', () => {
-    const { next, verifyToken } = run({
+  it('finds the cookie among others, and decodes a percent-encoded value', async () => {
+    const { next, resolveSession } = await run({
       cookie: `theme=dark; ${AUTH_COOKIE_NAME}=${encodeURIComponent(GOOD_TOKEN)}; seen=1`,
     });
-    expect(verifyToken).toHaveBeenCalledWith(GOOD_TOKEN);
+    expect(resolveSession).toHaveBeenCalledWith(GOOD_TOKEN);
     expect(next).toHaveBeenCalledTimes(1);
   });
 
-  it('prefers the Bearer header when both are present', () => {
-    const { next, verifyToken } = run({
+  it('prefers the Bearer header when both are present', async () => {
+    const { next, resolveSession } = await run({
       authorization: `Bearer ${GOOD_TOKEN}`,
       cookie: `${AUTH_COOKIE_NAME}=stale-cookie`,
     });
-    expect(verifyToken).toHaveBeenCalledTimes(1);
-    expect(verifyToken).toHaveBeenCalledWith(GOOD_TOKEN);
+    expect(resolveSession).toHaveBeenCalledTimes(1);
+    expect(resolveSession).toHaveBeenCalledWith(GOOD_TOKEN);
     expect(next).toHaveBeenCalledTimes(1);
   });
 
-  it('refuses a request with neither', () => {
-    const { next, status, json } = run({});
+  it('refuses a request with neither', async () => {
+    const { next, status, json } = await run({});
     expect(next).not.toHaveBeenCalled();
     expect(status).toHaveBeenCalledWith(401);
     expect(json.mock.calls[0][0].error).toContain('auth cookie');
   });
 
-  it('refuses an empty cookie value as missing, not as a token to verify', () => {
-    const { next, status, verifyToken } = run({ cookie: `${AUTH_COOKIE_NAME}=` });
-    expect(verifyToken).not.toHaveBeenCalled();
+  it('refuses an empty cookie value as missing, not as a token to verify', async () => {
+    const { next, status, resolveSession } = await run({ cookie: `${AUTH_COOKIE_NAME}=` });
+    expect(resolveSession).not.toHaveBeenCalled();
     expect(next).not.toHaveBeenCalled();
     expect(status).toHaveBeenCalledWith(401);
   });
 
-  it('refuses a cookie the auth service rejects', () => {
-    const { next, status, json } = run({ cookie: `${AUTH_COOKIE_NAME}=forged` });
+  it('refuses a cookie the auth service rejects', async () => {
+    const { next, status, json } = await run({ cookie: `${AUTH_COOKIE_NAME}=forged` });
     expect(next).not.toHaveBeenCalled();
     expect(status).toHaveBeenCalledWith(401);
     expect(json.mock.calls[0][0].error).toBe('Invalid or expired token');
   });
 });
+
+describe('createAuthMiddleware — a switched-off account', () => {
+  it('refuses a valid session whose account an admin switched off, and says why', async () => {
+    const { next, status, json } = await run({ authorization: `Bearer ${OFF_TOKEN}` });
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+    expect(json.mock.calls[0][0].error).toContain('switched off');
+  });
+});
+
+describe('createAuthMiddleware — the account cannot be looked up', () => {
+  it('500s rather than signing a valid session out during an outage', async () => {
+    const { next, status, json } = await run({ authorization: `Bearer ${DOWN_TOKEN}` });
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(500);
+    expect(json.mock.calls[0][0].error).toBe('Authentication backend unavailable');
+  });
+});

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

@@ -537,7 +537,7 @@ describe('AuthService.listAccounts', () => {
     expect(json).not.toContain('sup3r-secret');
     for (const account of [...withHash, ...withoutHash]) {
       expect(Object.keys(account).sort()).toEqual(
-        ['createdAt', 'email', 'hasPassword', 'id', 'isEnvAdmin', 'name'],
+        ['createdAt', 'deactivatedAt', 'email', 'hasPassword', 'id', 'isEnvAdmin', 'isSystem', 'name'],
       );
     }
   });

package/src/modules/auth/account-admission.ts

@@ -1,12 +1,14 @@
 /**
  * Whether a NEW account may be provisioned on this deployment, asked before
- * the row is inserted. The one seam a host that sells seats needs: core
- * admits everyone, and a cloud overlay answers from its plan without
- * forking any sign-in path.
+ * the row is inserted — and whether a deactivated one may be switched back
+ * on, which takes up the same place. The one seam a host that sells seats
+ * needs: core admits everyone, and a cloud overlay answers from its plan
+ * without forking any sign-in path.
  *
- * Asked only for an address with no account yet. An existing user's sign-in
- * is never a provisioning, so a refusal can never lock out someone who is
- * already in.
+ * Never asked for an account that is already on. An existing user's sign-in
+ * is not a provisioning, so a refusal can never lock out someone who is
+ * already in; taking someone out is the admin's act (deactivation), not the
+ * port's.
  */
 export type AccountProvisionReason =
   /** A first sign-in through single sign-on, which provisions on its own. */
@@ -16,9 +18,29 @@ export type AccountProvisionReason =
   /** The deployment owner's first password sign-in, which creates their row. */
   | 'bootstrap'
   /** A verified identity from an embedding surface that needs a row without a session. */
-  | 'embed';
+  | 'embed'
+  /** An admin switching a deactivated account back on. */
+  | 'reactivate';
 
-export type AccountAdmissionVerdict = { ok: true } | { ok: false; message: string };
+export type AccountAdmissionVerdict =
+  | { ok: true }
+  | {
+      ok: false;
+      message: string;
+      /**
+       * Keep the person on file instead of turning them away: the account is
+       * created DEACTIVATED, the sign-in is still refused with `message`, and
+       * an admin finds them on the accounts list, ready to be switched on.
+       * For a host whose rule is "whoever is on our domain may join while
+       * there is room" — the one past the room waits instead of bouncing.
+       *
+       * Honoured only for a sign-in through single sign-on, the one
+       * provisioning nobody asked for. Everywhere else a verdict carrying it
+       * is a plain refusal: an admin creating an account would be told no,
+       * and a deactivated account is never reactivated into one.
+       */
+      waitForAdmin?: boolean;
+    };
 
 export interface IAccountAdmission {
   canProvision(email: string, reason: AccountProvisionReason): Promise<AccountAdmissionVerdict>;
@@ -36,9 +58,56 @@ export const admitEveryone: IAccountAdmission = {
  */
 export class AccountAdmissionRefusedError extends Error {
   readonly status = 403;
+  /** The person was put on file, switched off, for an admin to switch on (see `waitForAdmin`). */
+  readonly waitingForAdmin: boolean;
 
-  constructor(message: string) {
+  constructor(message: string, opts: { waitingForAdmin?: boolean } = {}) {
     super(message);
     this.name = 'AccountAdmissionRefusedError';
+    this.waitingForAdmin = opts.waitingForAdmin ?? false;
+  }
+}
+
+/**
+ * The account exists and an admin switched it off — at sign-in, or for a
+ * credential it still holds. A 403 like a refusal: the identity is fine,
+ * the deployment no longer lets it in.
+ */
+export class AccountDeactivatedError extends Error {
+  readonly status = 403;
+
+  constructor(message = ACCOUNT_DEACTIVATED_MESSAGE) {
+    super(message);
+    this.name = 'AccountDeactivatedError';
   }
 }
+
+/**
+ * Whether the account behind a credential is on could not be asked — the
+ * database failed. Not the caller's fault and not a verdict on them: a
+ * route answers it with a 500, never with the 401 that would sign a valid
+ * caller out during an outage.
+ */
+export class AuthBackendError extends Error {
+  constructor(readonly cause: unknown) {
+    super('The account could not be looked up');
+    this.name = 'AuthBackendError';
+  }
+}
+
+/**
+ * An admin's change to an account that the deployment refuses on purpose
+ * (switching off the deployment admin, or an account the platform runs its
+ * own work as). Its message is for the admin; a route answers it with 400.
+ */
+export class AccountChangeRefusedError extends Error {
+  readonly status = 400;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'AccountChangeRefusedError';
+  }
+}
+
+/** What a person with a deactivated account is told, wherever they knock. */
+export const ACCOUNT_DEACTIVATED_MESSAGE = 'Your account on this workspace is switched off. Ask its admin to turn it back on.';

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

@@ -6,7 +6,7 @@ import { printable } from '../../shared/printable.js';
 const log = logger('accounts');
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { AuthService } from './auth.service.js';
-import { AccountAdmissionRefusedError } from './account-admission.js';
+import { AccountAdmissionRefusedError, AccountChangeRefusedError } from './account-admission.js';
 import { erasedAccountId, type IAccountErasureService } from './account-erasure.service.js';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
 import type { UserAccessRemovalService } from '../access/user-access-removal.service.js';
@@ -26,7 +26,7 @@ import './auth.middleware.js'; // Express Request augmentation
  * bootstrap admin (always-admin, see AdminAccessService).
  */
 export function createAccountRoutes(
-  authService: Pick<AuthService, 'listAccounts' | 'createAccount' | 'getUserById'>,
+  authService: Pick<AuthService, 'listAccounts' | 'createAccount' | 'getUserById' | 'deactivate' | 'reactivate'>,
   adminAccess: IAdminAccessService,
   accountErasure: Pick<IAccountErasureService, 'eraseUser'>,
   accessRemoval?: Pick<UserAccessRemovalService, 'report' | 'assertRemovable' | 'remove' | 'filesNaming'>,
@@ -47,17 +47,23 @@ export function createAccountRoutes(
     res.json({ accounts: await authService.listAccounts() });
   });
 
-  // POST /api/admin/accounts { email, name?, password } — create an account
+  // 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).
+  // see AuthService.createAccount). Without a password the account is for
+  // single sign-on: the person finds it waiting when they first sign in.
   router.post('/admin/accounts', requireAdmin, async (req, res) => {
     const { email, name, password } = req.body as {
       email?: string;
       name?: string;
-      password?: string;
+      password?: unknown;
     };
-    if (!email || !password) {
-      res.status(400).json({ error: 'email and password are required' });
+    if (!email) {
+      res.status(400).json({ error: 'email is required' });
+      return;
+    }
+    // Absent means single sign-on; anything else that is not text is a mistake, not that.
+    if (password !== undefined && typeof password !== 'string') {
+      res.status(400).json({ error: 'password must be a string' });
       return;
     }
     try {
@@ -71,6 +77,56 @@ export function createAccountRoutes(
     }
   });
 
+  // POST /api/admin/accounts/:userId/deactivate — switch an account off. It
+  // keeps its row, history and place in roles and groups; nothing it holds
+  // signs in any more (see AuthService.isActive). An admin's own account is
+  // refused, so whoever does this is still an admin who is on afterwards —
+  // the deployment is never left with no admin able to sign in.
+  router.post('/admin/accounts/:userId/deactivate', requireAdmin, async (req, res) => {
+    const userId = String(req.params.userId);
+    if (userId === req.userId) {
+      res.status(400).json({ error: 'You cannot switch off your own account. Ask another admin.' });
+      return;
+    }
+    try {
+      if (!(await authService.deactivate(userId))) {
+        res.status(404).json({ error: 'No such user' });
+        return;
+      }
+      log.info('account audit:', { action: 'deactivate', actorUserId: req.userId, targetUserId: userId });
+      res.status(204).end();
+    } catch (error) {
+      if (error instanceof AccountChangeRefusedError) {
+        res.status(400).json({ error: error.message });
+        return;
+      }
+      log.error('switching an account off failed:', { err: error });
+      res.status(500).json({ error: 'Could not switch this account off' });
+    }
+  });
+
+  // POST /api/admin/accounts/:userId/reactivate — switch it back on, if the
+  // deployment has room: the admission port is asked, as for a new account
+  // (a host that sells seats answers from its plan; 403 with its words).
+  router.post('/admin/accounts/:userId/reactivate', requireAdmin, async (req, res) => {
+    const userId = String(req.params.userId);
+    try {
+      if (!(await authService.reactivate(userId))) {
+        res.status(404).json({ error: 'No such user' });
+        return;
+      }
+      log.info('account audit:', { action: 'reactivate', actorUserId: req.userId, targetUserId: userId });
+      res.status(204).end();
+    } catch (error) {
+      if (error instanceof AccountAdmissionRefusedError) {
+        res.status(403).json({ error: error.message });
+        return;
+      }
+      log.error('switching an account on failed:', { err: error });
+      res.status(500).json({ error: 'Could not switch this account on' });
+    }
+  });
+
   // GET /api/admin/accounts/:userId/references — how many places in the
   // knowledge base name this account's address (roles, groups, access rules,
   // file grants) and whether removing them is allowed. Feeds the delete

package/src/modules/auth/auth.middleware.ts

@@ -1,5 +1,6 @@
 import type { Request, Response, NextFunction } from 'express';
 import type { AuthService } from './auth.service.js';
+import { AccountDeactivatedError, AuthBackendError } from './account-admission.js';
 
 // Augment Express Request so userId/userEmail are available after auth middleware
 declare global {
@@ -46,8 +47,8 @@ function readAuthCookie(req: Request): string | null {
   return null;
 }
 
-export function createAuthMiddleware(authService: AuthService) {
-  return (req: Request, res: Response, next: NextFunction) => {
+export function createAuthMiddleware(authService: Pick<AuthService, 'resolveSession'>) {
+  return async (req: Request, res: Response, next: NextFunction) => {
     // Bearer is the primary path — every JSON API call in the frontend
     // attaches it via `authFetch`. Cookie is the fallback for transports
     // that can't carry headers (EventSource, image tags), set at login by
@@ -66,13 +67,23 @@ export function createAuthMiddleware(authService: AuthService) {
       return;
     }
 
+    let session: { userId: string; email: string };
     try {
-      const { userId, email } = authService.verifyToken(token);
-      req.userId = userId;
-      req.userEmail = email;
-      next();
-    } catch {
-      res.status(401).json({ error: 'Invalid or expired token' });
+      session = await authService.resolveSession(token);
+    } catch (err) {
+      // The account could not be looked up: not the caller's doing, and a
+      // 401 here would sign every valid session out during an outage.
+      if (err instanceof AuthBackendError) {
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
+      // A 401 otherwise, so the app drops the session and shows the login
+      // page; a switched-off account is told why there.
+      res.status(401).json({ error: err instanceof AccountDeactivatedError ? err.message : 'Invalid or expired token' });
+      return;
     }
+    req.userId = session.userId;
+    req.userEmail = session.email;
+    next();
   };
 }

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

@@ -5,6 +5,7 @@ const log = logger('auth');
 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';
+import { AccountDeactivatedError } from './account-admission.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 
 /**
@@ -113,6 +114,13 @@ export function createAuthRoutes(
       });
       res.json(result);
     } catch (error) {
+      // The password was right and an admin switched the account off: said
+      // as such (only ever after the password is proven, see
+      // `loginWithPassword`), so the person knows whom to ask.
+      if (error instanceof AccountDeactivatedError) {
+        res.status(403).json({ error: error.message });
+        return;
+      }
       const msg = error instanceof Error ? error.message : 'Unknown error';
       log.error('Login error:', { detail: msg });
       res.status(401).json({ error: 'Authentication failed' });