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

package/src/modules/auth/__tests__/account-deactivation.test.ts

@@ -0,0 +1,252 @@
+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 {
+  AccountAdmissionRefusedError,
+  AccountChangeRefusedError,
+  AccountDeactivatedError,
+  AuthBackendError,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from '../account-admission.js';
+import { hashPassword } from '../password-hash.js';
+import { RECOVERY_BOT_EMAIL } from '../../workflow/recovery-bot.js';
+
+/**
+ * Drizzle chain stub, as in `auth.service.test.ts`: each db.select() /
+ * insert() / update() consumes the next queued result; awaiting any point of
+ * the chain resolves it. Records what was inserted and set.
+ */
+function makeFakeDb(queue: unknown[]) {
+  const captured: { values: Record<string, unknown>[]; set: Record<string, unknown>[] } = { values: [], set: [] };
+  function nextChain(): unknown {
+    const result = queue.shift();
+    const chain: Record<string, unknown> = {};
+    const passthrough = (recorder?: (arg: Record<string, unknown>) => void) =>
+      vi.fn((arg?: unknown) => {
+        recorder?.(arg as Record<string, unknown>);
+        return chain;
+      });
+    Object.assign(chain, {
+      values: passthrough((a) => captured.values.push(a)),
+      set: passthrough((a) => captured.set.push(a)),
+      where: passthrough(),
+      limit: passthrough(),
+      from: passthrough(),
+      orderBy: passthrough(),
+      returning: passthrough(),
+      onConflictDoUpdate: passthrough(),
+      onConflictDoNothing: passthrough(),
+      then: (ok: (v: unknown) => unknown, ko: (e: unknown) => unknown) => Promise.resolve(result).then(ok, ko),
+    });
+    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, onboardingDone: false, deactivatedAt: null };
+const OFF = { ...ROW, deactivatedAt: new Date('2026-09-01') };
+
+function recordingPort(verdict: Awaited<ReturnType<IAccountAdmission['canProvision']>>) {
+  const asked: Array<[string, AccountProvisionReason]> = [];
+  const port: IAccountAdmission = {
+    canProvision: async (email, reason) => {
+      asked.push([email, reason]);
+      return verdict;
+    },
+  };
+  return { port, asked };
+}
+
+describe('signing in with a switched-off account', () => {
+  it('refuses a password sign-in once the password is proven, and says why', async () => {
+    const passwordHash = await hashPassword('a-long-enough-password');
+    const { db } = makeFakeDb([[{ ...OFF, passwordHash }]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.loginWithPassword('alice@example.com', 'a-long-enough-password')).rejects.toBeInstanceOf(
+      AccountDeactivatedError,
+    );
+  });
+
+  it('gives a wrong password the same answer as for any account, so it reveals nothing', async () => {
+    const passwordHash = await hashPassword('a-long-enough-password');
+    const { db } = makeFakeDb([[{ ...OFF, passwordHash }]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.loginWithPassword('alice@example.com', 'the-wrong-password')).rejects.toThrow('Invalid credentials');
+  });
+
+  it('refuses a single sign-on sign-in, without issuing a session', async () => {
+    const { db } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.loginWithSso('alice@example.com', 'Alice')).rejects.toBeInstanceOf(AccountDeactivatedError);
+  });
+
+  it('refuses an embed identity', async () => {
+    const { db } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.getOrCreateByEmail('alice@example.com')).rejects.toBeInstanceOf(AccountDeactivatedError);
+  });
+});
+
+describe('a session that outlives a deactivation', () => {
+  it('stops being accepted once the account is switched off', async () => {
+    const { db } = makeFakeDb([[ROW], [{ deactivatedAt: new Date() }]]);
+    const svc = new AuthService(db, makeConfig());
+    const { token } = await svc.loginWithSso('alice@example.com', 'Alice');
+    // The signature alone is still good…
+    expect(svc.verifyToken(token).userId).toBe(ROW.id);
+    // …but the session is not.
+    await expect(svc.resolveSession(token)).rejects.toBeInstanceOf(AccountDeactivatedError);
+  });
+
+  it('is told apart from a refusal when the account cannot be looked up', async () => {
+    const { db } = makeFakeDb([[ROW]]);
+    const svc = new AuthService(db, makeConfig());
+    const { token } = await svc.loginWithSso('alice@example.com', 'Alice');
+    vi.mocked(db.select).mockImplementationOnce(() => {
+      throw new Error('db down');
+    });
+    await expect(svc.resolveSession(token)).rejects.toBeInstanceOf(AuthBackendError);
+  });
+
+  it('is accepted while the account is on', async () => {
+    const { db } = makeFakeDb([[ROW], [{ deactivatedAt: null }]]);
+    const svc = new AuthService(db, makeConfig());
+    const { token } = await svc.loginWithSso('alice@example.com', 'Alice');
+    await expect(svc.resolveSession(token)).resolves.toEqual({ userId: ROW.id, email: ROW.email });
+  });
+});
+
+describe('AuthService.isActive', () => {
+  it('reads once and keeps the answer briefly', async () => {
+    const { db } = makeFakeDb([[{ deactivatedAt: null }]]);
+    const svc = new AuthService(db, makeConfig());
+    expect(await svc.isActive('user-1')).toBe(true);
+    expect(await svc.isActive('user-1')).toBe(true);
+    expect(vi.mocked(db.select)).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats the deployment admin as on whatever its row says, so its rescue session works', async () => {
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
+    const { db } = makeFakeDb([[{ email: 'root@example.com', deactivatedAt: new Date() }]]);
+    expect(await new AuthService(db, config).isActive('root-id')).toBe(true);
+  });
+
+  it('treats an account that no longer exists as off', async () => {
+    const { db } = makeFakeDb([[]]);
+    expect(await new AuthService(db, makeConfig()).isActive('gone')).toBe(false);
+  });
+
+  it('forgets the cached answer when this process switches the account off', async () => {
+    const { db } = makeFakeDb([[{ deactivatedAt: null }], [ROW], [], [{ deactivatedAt: new Date() }]]);
+    const svc = new AuthService(db, makeConfig());
+    expect(await svc.isActive(ROW.id)).toBe(true);
+    expect(await svc.deactivate(ROW.id)).toBe(true);
+    expect(await svc.isActive(ROW.id)).toBe(false);
+  });
+});
+
+describe('AuthService.deactivate', () => {
+  it('records when the account was switched off', async () => {
+    const { db, captured } = makeFakeDb([[ROW], []]);
+    expect(await new AuthService(db, makeConfig()).deactivate(ROW.id)).toBe(true);
+    expect(captured.set[0].deactivatedAt).toBeInstanceOf(Date);
+  });
+
+  it('answers false for an account that does not exist', async () => {
+    const { db } = makeFakeDb([[]]);
+    expect(await new AuthService(db, makeConfig()).deactivate('nobody')).toBe(false);
+  });
+
+  it('refuses the deployment admin, whose environment password is the way back in', async () => {
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
+    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com' }]]);
+    await expect(new AuthService(db, config).deactivate(ROW.id)).rejects.toBeInstanceOf(AccountChangeRefusedError);
+    expect(vi.mocked(db.update)).not.toHaveBeenCalled();
+  });
+
+  it('refuses the accounts the platform runs its own work as', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: RECOVERY_BOT_EMAIL }]]);
+    await expect(new AuthService(db, makeConfig()).deactivate(ROW.id)).rejects.toThrow('platform itself');
+    expect(vi.mocked(db.update)).not.toHaveBeenCalled();
+  });
+});
+
+describe('AuthService.reactivate', () => {
+  it('asks the admission port, as for a new account, and switches it on when admitted', async () => {
+    const { port, asked } = recordingPort({ ok: true });
+    const { db, captured } = makeFakeDb([[OFF], []]);
+    expect(await new AuthService(db, makeConfig(), port).reactivate(ROW.id)).toBe(true);
+    expect(asked).toEqual([['alice@example.com', 'reactivate']]);
+    expect(captured.set[0].deactivatedAt).toBeNull();
+  });
+
+  it("refuses with the port's words when there is no room, and changes nothing", async () => {
+    const { port } = recordingPort({ ok: false, message: 'All 3 seats are taken' });
+    const { db } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig(), port);
+    await expect(svc.reactivate(ROW.id)).rejects.toThrow('All 3 seats are taken');
+    expect(vi.mocked(db.update)).not.toHaveBeenCalled();
+  });
+
+  it('does not ask about an account that is already on', async () => {
+    const { port, asked } = recordingPort({ ok: false, message: 'full' });
+    const { db } = makeFakeDb([[ROW]]);
+    expect(await new AuthService(db, makeConfig(), port).reactivate(ROW.id)).toBe(true);
+    expect(asked).toEqual([]);
+  });
+});
+
+describe('a first sign-in the port would rather keep waiting', () => {
+  const waiting = { ok: false as const, message: 'No seat left; the admin can let you in', waitForAdmin: true };
+
+  it('puts the person on file switched off, and still refuses the sign-in', async () => {
+    const { port } = recordingPort(waiting);
+    const { db, captured } = makeFakeDb([[], []]);
+    const svc = new AuthService(db, makeConfig(), port);
+    const err = await svc.loginWithSso('new@example.com', 'New').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(AccountAdmissionRefusedError);
+    expect((err as AccountAdmissionRefusedError).waitingForAdmin).toBe(true);
+    expect((err as Error).message).toBe(waiting.message);
+    expect(captured.values).toHaveLength(1);
+    expect(captured.values[0]).toMatchObject({ email: 'new@example.com' });
+    expect(captured.values[0].deactivatedAt).toBeInstanceOf(Date);
+  });
+
+  it('is a plain refusal when an admin creates the account', async () => {
+    const { port } = recordingPort(waiting);
+    const { db } = makeFakeDb([[]]);
+    const err = await new AuthService(db, makeConfig(), port)
+      .createAccount('new@example.com', 'New')
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(AccountAdmissionRefusedError);
+    expect((err as AccountAdmissionRefusedError).waitingForAdmin).toBe(false);
+    expect(vi.mocked(db.insert)).not.toHaveBeenCalled();
+  });
+});
+
+describe('AuthService.createAccount without a password', () => {
+  it('makes an account for single sign-on, with no hash stored', async () => {
+    const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: null }]]);
+    const user = await new AuthService(db, makeConfig()).createAccount('Alice@Example.com', '');
+    expect(user.email).toBe('alice@example.com');
+    expect(captured.values[0]).toEqual({ email: 'alice@example.com', name: 'alice' });
+  });
+
+  it('asks the admission port, as any new account does', async () => {
+    const { port, asked } = recordingPort({ ok: true });
+    const { db } = makeFakeDb([[], [{ ...ROW, passwordHash: null }]]);
+    await new AuthService(db, makeConfig(), port).createAccount('alice@example.com', 'Alice');
+    expect(asked).toEqual([['alice@example.com', 'admin-create']]);
+  });
+});

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'],
       );
     }
   });
@@ -574,6 +574,44 @@ describe('AuthService — the SSO domain allow-list', () => {
     ).rejects.toThrow(/domain is not allowed/i);
   });
 
+  /**
+   * One rule per sign-in. A provider that decided for itself who may enter
+   * (an invitation, a claimed domain) is not overruled by a list the admin
+   * set for the deployment's own provider; the plan still has its say.
+   */
+  it('is not laid on top of a provider that decided admission itself', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'invited@gmail.com', name: 'Invited' }]]);
+    const out = await new AuthService(db, config).loginWithSso('invited@gmail.com', 'Invited', {
+      admittedByProvider: true,
+    });
+    expect(out.user.email).toBe('invited@gmail.com');
+  });
+
+  it('still asks the plan about someone the provider admitted', async () => {
+    const asked: Array<[string, string]> = [];
+    const plan: IAccountAdmission = {
+      canProvision: async (email, reason) => {
+        asked.push([email, reason]);
+        return { ok: false, message: 'No seat left on this plan' };
+      },
+    };
+    const { db } = makeFakeDb([[]]);
+    await expect(
+      new AuthService(db, config, plan).loginWithSso('invited@gmail.com', 'Invited', { admittedByProvider: true }),
+    ).rejects.toBeInstanceOf(AccountAdmissionRefusedError);
+    expect(asked).toEqual([['invited@gmail.com', 'sso']]);
+    expect(vi.mocked(db.insert)).not.toHaveBeenCalled();
+  });
+
+  it('governs a provider that says nothing, or says it did not decide', async () => {
+    for (const opts of [undefined, {}, { admittedByProvider: false }]) {
+      const { db } = makeFakeDb([[]]);
+      await expect(new AuthService(db, config).loginWithSso('someone@gmail.com', 'Someone', opts)).rejects.toThrow(
+        /domain is not allowed/i,
+      );
+    }
+  });
+
   it('admits a subdomain of an allowed domain', async () => {
     const { db } = makeFakeDb([[{ ...ROW, email: 'eu@eu.bevel.software', name: 'EU' }]]);
     const out = await new AuthService(db, config).loginWithSso('eu@eu.bevel.software', 'EU');

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.';