@bevel-software/platform-core-backend 0.26.0 → 0.28.0

package/src/modules/access/__tests__/access.routes.admins.test.ts

@@ -0,0 +1,203 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+import { AccessControlService } from '../access-control.service.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { WorkflowService } from '../../workflow/workflow.service.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import { createAccessRoutes } from '../access.routes.js';
+import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * `GET /api/access/admins`: who the admins are, for anyone signed in. It
+ * answers the Admin role's members — through a group too — and the deployment
+ * admins, each once, sorted by name, with names from the accounts table; and
+ * nothing else about roles. The roster stays admin-only.
+ */
+
+const KB = 'knowledge-base';
+const MEMBER = { id: 'u-lena', email: 'lena@acme.com', name: 'Lena Park' };
+
+const ROLES = `roles:
+  Admin:
+    - sam.ortiz@acme.com
+    - group:Ops
+  Sales:
+    - felix@acme.com
+`;
+
+const GROUPS = `groups:
+  Ops:
+    - dana@acme.com
+    - sam.ortiz@acme.com
+  Product:
+    - priya@acme.com
+`;
+
+const tmpDirs: string[] = [];
+
+async function makeHarness(
+  opts: {
+    roles?: string;
+    groups?: string;
+    signedIn?: boolean;
+    deploymentAdmins?: string[];
+    accounts?: { email: string; name?: string; deactivatedAt?: Date | null }[];
+  } = {},
+): Promise<{ server: Server; baseUrl: string }> {
+  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-admins-route-'));
+  tmpDirs.push(workspaceDir);
+  const repoDir = path.join(workspaceDir, KB);
+  await fs.mkdir(repoDir, { recursive: true });
+  await fs.writeFile(path.join(repoDir, 'roles.yaml'), opts.roles ?? ROLES, 'utf-8');
+  await fs.writeFile(path.join(repoDir, 'groups.yaml'), opts.groups ?? GROUPS, 'utf-8');
+
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async () => ({})),
+    getWorkspacePath: vi.fn(async () => workspaceDir),
+    readFile: vi.fn(async (_id: string, wsRel: string) => fs.readFile(path.join(workspaceDir, wsRel), 'utf-8')),
+  } as unknown as WorkspaceService;
+  // The real resolver: the admins read is its own membership answer. Nobody
+  // signed in here is an Admin, so nobody may read the roster either.
+  const deploymentAdmins = opts.deploymentAdmins ?? ['Owner@Acme.com'];
+  const accessControl = new AccessControlService(workspaceService, KB, new NodeFs(), deploymentAdmins);
+  const authService = { getUserById: vi.fn(async () => MEMBER) } as unknown as AuthService;
+  const db = usersDbDouble(
+    opts.accounts ?? [
+      { email: 'dana@acme.com', name: 'Dana Admin' },
+      { email: 'sam.ortiz@acme.com', name: 'Sam Ortiz' },
+      { email: 'felix@acme.com', name: 'Felix Sales' },
+      { email: 'priya@acme.com', name: 'Priya Product' },
+      MEMBER,
+    ],
+  );
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    if (opts.signedIn !== false) (req as unknown as { userId: string }).userId = MEMBER.id;
+    next();
+  });
+  app.use(
+    '/api',
+    createAccessRoutes(
+      accessControl,
+      workspaceService,
+      authService,
+      authService,
+      {} as unknown as WorkflowService,
+      { emit: vi.fn() } as unknown as WorkflowEventBus,
+      db,
+      testKbContext({ kbDirName: KB }),
+      deploymentAdmins,
+    ),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return { server, baseUrl: `http://127.0.0.1:${(server.address() as AddressInfo).port}` };
+}
+
+function close(s: Server): Promise<void> {
+  return new Promise((resolve, reject) => s.close((e) => (e ? reject(e) : resolve())));
+}
+
+describe('GET /api/access/admins', () => {
+  let server: Server | null = null;
+  afterEach(async () => {
+    if (server) await close(server);
+    server = null;
+    await Promise.all(tmpDirs.splice(0).map((d) => fs.rm(d, { recursive: true, force: true })));
+  });
+
+  it('tells a Member every admin — direct, through a group, and the deployment admin — once each, sorted by name', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    const res = await fetch(`${h.baseUrl}/api/access/admins`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      admins: [
+        { name: 'Dana Admin', email: 'dana@acme.com' },
+        // No account yet: named by address.
+        { name: 'owner@acme.com', email: 'owner@acme.com' },
+        { name: 'Sam Ortiz', email: 'sam.ortiz@acme.com' },
+      ],
+    });
+  });
+
+  it('reveals nothing else: no other role, group or member, and no other field', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    const text = await (await fetch(`${h.baseUrl}/api/access/admins`)).text();
+    for (const leak of ['felix', 'priya', 'Sales', 'Product', 'Ops', 'group:', 'lena']) {
+      expect(text).not.toContain(leak);
+    }
+    const body = JSON.parse(text) as { admins: Record<string, unknown>[] };
+    expect(Object.keys(body)).toEqual(['admins']);
+    for (const admin of body.admins) expect(Object.keys(admin).sort()).toEqual(['email', 'name']);
+  });
+
+  it('answers only the deployment admins when roles.yaml does not parse, as the resolver does', async () => {
+    const h = await makeHarness({ roles: 'roles:\n  Admin: not-a-list\n' });
+    server = h.server;
+    const body = (await (await fetch(`${h.baseUrl}/api/access/admins`)).json()) as { admins: unknown[] };
+    expect(body.admins).toEqual([{ name: 'owner@acme.com', email: 'owner@acme.com' }]);
+  });
+
+  it('answers only the deployment admins when the resolver rejects roles.yaml the editing model would read', async () => {
+    // A role named with the reserved plugin prefix: the resolver refuses the
+    // whole file, so nobody in it is an Admin — and nobody is listed as one.
+    const h = await makeHarness({
+      roles: 'roles:\n  Admin:\n    - sam.ortiz@acme.com\n    - group:Ops\n  plugin/x:\n    - felix@acme.com\n',
+    });
+    server = h.server;
+    const body = (await (await fetch(`${h.baseUrl}/api/access/admins`)).json()) as { admins: unknown[] };
+    expect(body.admins).toEqual([{ name: 'owner@acme.com', email: 'owner@acme.com' }]);
+  });
+
+  it('does not count the members of a GROUP named Admin, as the resolver does not', async () => {
+    const h = await makeHarness({ groups: 'groups:\n  Admin:\n    - priya@acme.com\n' });
+    server = h.server;
+    const text = await (await fetch(`${h.baseUrl}/api/access/admins`)).text();
+    expect(text).not.toContain('priya');
+    expect(text).toContain('sam.ortiz@acme.com');
+  });
+
+  it('leaves out a role member whose account is switched off, but not a switched-off deployment admin', async () => {
+    const off = new Date('2026-01-01T00:00:00Z');
+    const h = await makeHarness({
+      accounts: [
+        { email: 'dana@acme.com', name: 'Dana Admin', deactivatedAt: off },
+        { email: 'sam.ortiz@acme.com', name: 'Sam Ortiz' },
+        { email: 'owner@acme.com', name: 'Olive Owner', deactivatedAt: off },
+        MEMBER,
+      ],
+    });
+    server = h.server;
+    const body = (await (await fetch(`${h.baseUrl}/api/access/admins`)).json()) as { admins: unknown[] };
+    expect(body.admins).toEqual([
+      { name: 'Olive Owner', email: 'owner@acme.com' },
+      { name: 'Sam Ortiz', email: 'sam.ortiz@acme.com' },
+    ]);
+  });
+
+  it('refuses a caller who is not signed in', async () => {
+    const h = await makeHarness({ signedIn: false });
+    server = h.server;
+    expect((await fetch(`${h.baseUrl}/api/access/admins`)).status).toBe(401);
+  });
+
+  it('leaves the roles roster admin-only', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    expect((await fetch(`${h.baseUrl}/api/access/roles`)).status).toBe(403);
+  });
+});

package/src/modules/access/__tests__/access.routes.batch.test.ts

@@ -28,11 +28,14 @@ interface Harness {
   baseUrl: string;
   canWriteBatch: ReturnType<typeof vi.fn>;
   canOwnerBatch: ReturnType<typeof vi.fn>;
+  canReadBatch: ReturnType<typeof vi.fn>;
 }
 
-// Alice WRITES both skills but is named in the `owner:` grant of one.
+// Alice WRITES both skills but is named in the `owner:` grant of one, and
+// READS a folder she may not write.
 const WRITABLE = new Set(['Skills/a/SKILL.md', 'Skills/b/SKILL.md']);
 const OWNED = new Set(['Skills/a/SKILL.md']);
+const READABLE = new Set(['Skills/a/SKILL.md', 'Skills/b/SKILL.md', 'KnowledgeBase/Sales']);
 
 const verdicts = (set: Set<string>) =>
   vi.fn(async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, set.has(p)])));
@@ -40,7 +43,8 @@ const verdicts = (set: Set<string>) =>
 async function makeHarness(): Promise<Harness> {
   const canWriteBatch = verdicts(WRITABLE);
   const canOwnerBatch = verdicts(OWNED);
-  const accessControl = { canWriteBatch, canOwnerBatch } as unknown as IAccessControl;
+  const canReadBatch = verdicts(READABLE);
+  const accessControl = { canWriteBatch, canOwnerBatch, canReadBatch } as unknown as IAccessControl;
 
   const workspaceService = {} as unknown as WorkspaceService;
   const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
@@ -57,6 +61,7 @@ async function makeHarness(): Promise<Harness> {
       accessControl,
       workspaceService,
       authService,
+      authService,
       {} as unknown as WorkflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       usersDbDouble(),
@@ -68,7 +73,7 @@ async function makeHarness(): Promise<Harness> {
     const s = app.listen(0, () => resolve(s));
   });
   const addr = server.address() as AddressInfo;
-  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, canWriteBatch, canOwnerBatch };
+  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, canWriteBatch, canOwnerBatch, canReadBatch };
 }
 
 function close(s: Server): Promise<void> {
@@ -119,16 +124,31 @@ describe('POST /access/batch', () => {
     expect(h.canWriteBatch).not.toHaveBeenCalled();
   });
 
+  it('answers READ for `verb: read` — a folder the caller may read but not write gets true', async () => {
+    h = await makeHarness();
+
+    const paths = [...PATHS, 'KnowledgeBase/Sales'];
+    const res = await post({ paths, verb: 'read' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      results: { 'Skills/a/SKILL.md': true, 'Skills/b/SKILL.md': true, 'KnowledgeBase/Sales': true },
+    });
+    expect(h.canReadBatch).toHaveBeenCalledWith(WS, USER.email, paths);
+    expect(h.canWriteBatch).not.toHaveBeenCalled();
+    expect(h.canOwnerBatch).not.toHaveBeenCalled();
+  });
+
   it('400s a verb it does not dispatch, resolving nothing', async () => {
     h = await makeHarness();
 
-    for (const verb of ['read', 'admin', 42, null]) {
+    for (const verb of ['download', 'admin', 42, null]) {
       const res = await post({ paths: PATHS, verb });
       expect(res.status).toBe(400);
-      expect(await res.json()).toEqual({ error: 'verb must be "write" or "owner"' });
+      expect(await res.json()).toEqual({ error: 'verb must be "write", "owner" or "read"' });
     }
     expect(h.canWriteBatch).not.toHaveBeenCalled();
     expect(h.canOwnerBatch).not.toHaveBeenCalled();
+    expect(h.canReadBatch).not.toHaveBeenCalled();
   });
 
   it('keeps the paths validation ahead of the verb', async () => {

package/src/modules/access/__tests__/access.routes.folder-governs.test.ts

@@ -156,6 +156,7 @@ describe('access mutations on a file that cannot carry frontmatter', () => {
         accessControl,
         workspaceService,
         { getUserById: vi.fn(async () => USER) } as unknown as AuthService,
+        { whileSwitchedOn: async (_email: string, write: () => Promise<void>) => write() },
         workflowService,
         { emit: vi.fn() } as unknown as WorkflowEventBus,
         usersDbDouble(),

package/src/modules/access/__tests__/access.routes.group-grant.test.ts

@@ -88,7 +88,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

package/src/modules/access/__tests__/access.routes.overrides.test.ts

@@ -98,7 +98,7 @@ async function makeHarness(opts: {
   });
   app.use(
     '/api',
-    createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })),
+    createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })),
   );
 
   const server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.proposal-branch.test.ts

@@ -134,6 +134,7 @@ describe('access routes on a proposal branch (real git)', () => {
         access,
         workspaceService,
         authService,
+        authService,
         workflowService,
         { emit: () => {} } as unknown as WorkflowEventBus,
         usersDbDouble(),

package/src/modules/access/__tests__/access.routes.prospective.test.ts

@@ -64,6 +64,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
       accessControl,
       {} as unknown as WorkspaceService,
       { getUserById: vi.fn(async () => USER) } as unknown as AuthService,
+      { whileSwitchedOn: async (_email: string, write: () => Promise<void>) => write() },
       {} as unknown as WorkflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       {} as unknown as Database,

package/src/modules/access/__tests__/access.routes.revoke.test.ts

@@ -134,7 +134,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

package/src/modules/access/__tests__/access.routes.unknown-email.test.ts

@@ -105,6 +105,7 @@ async function makeHarness(opts: {
       accessControl,
       workspaceService,
       authService,
+      authService,
       workflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       opts.db ?? usersDbDouble(opts.accounts ?? []),

package/src/modules/access/__tests__/roles-admin.security.test.ts

@@ -146,7 +146,7 @@ describe('SECURITY: Admin-role removal takes effect on the next request', () =>
       (req as unknown as { userEmail?: string }).userEmail = req.header('x-test-email') ?? undefined;
       next();
     });
-    app.use('/api', createAccountRoutes(authService, adminAccess, erasure));
+    app.use('/api', createAccountRoutes(authService, adminAccess, erasure, { runAccountInvited: async () => [] }));
     server = await new Promise<Server>((resolve) => {
       const s = app.listen(0, () => resolve(s));
     });

package/src/modules/access/__tests__/roles-admin.service.test.ts

@@ -637,6 +637,18 @@ describe('Admin fixed members — the deployment admin', () => {
     expect(roster.find((r) => r.canonical === 'sales')!.fixedMembers).toEqual([]);
   });
 
+  it('sends the note with the roster, and the refusal leads with that same note', async () => {
+    // The page prints `fixedMembersNote` as sent, so this is the one copy of
+    // the wording: the note and the API refusal cannot drift apart.
+    const svc = serviceWith([OWNER]);
+    const roster = await svc.getRoster();
+    const note = roster.find((r) => r.canonical === 'admin')!.fixedMembersNote;
+    expect(note).toBe('Owner; cannot be removed here');
+    expect(roster.find((r) => r.canonical === 'sales')!.fixedMembersNote).toBeNull();
+    const refusal = await svc.addMember(ADMIN, 'admin', OWNER).catch((e: Error) => e);
+    expect((refusal as Error).message.startsWith(`${note}. `)).toBe(true);
+  });
+
   it('canonicalises the configured address and drops a blank one', async () => {
     // The composition root passes `[config.adminEmail]` unconditionally, so an
     // unset ADMIN_EMAIL arrives as [''] — that must not become a member "".
@@ -665,7 +677,7 @@ describe('Admin fixed members — the deployment admin', () => {
       status: 422,
       payload: { kind: 'fixed-deployment-admin' },
       message: expect.stringContaining(
-        'Deployment admin, set in the server configuration; cannot be removed here',
+        'Owner; cannot be removed here',
       ),
     });
     // Nothing written: the file is byte-identical.
@@ -685,7 +697,7 @@ describe('Admin fixed members — the deployment admin', () => {
       status: 422,
       payload: { kind: 'fixed-deployment-admin' },
       message: expect.stringContaining(
-        'Deployment admin, set in the server configuration; cannot be removed here',
+        'Owner; cannot be removed here',
       ),
     });
     expect(await fs.readFile(path.join(repo, 'roles.yaml'), 'utf-8')).toContain(OWNER);
@@ -700,6 +712,7 @@ describe('Admin fixed members — the deployment admin', () => {
   it('with no ADMIN_EMAIL configured, no role has a fixed member', async () => {
     const roster = await serviceWith([]).getRoster();
     expect(roster.every((r) => r.fixedMembers.length === 0)).toBe(true);
+    expect(roster.every((r) => r.fixedMembersNote === null)).toBe(true);
     // ...and ordinary Admin membership stays editable.
     await expect(serviceWith([]).addMember(ADMIN, 'admin', OWNER)).resolves.toBeDefined();
   });

package/src/modules/access/__tests__/roles.routes.test.ts

@@ -4,12 +4,14 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import express from 'express';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import type { SQL } from 'drizzle-orm';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 
 import type { IAccessControl } from '../access-control.interface.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { AuthService } from '../../auth/auth.service.js';
+import { AuthService } from '../../auth/auth.service.js';
 import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { FileTreeEntry } from '@bevel-software/platform-shared';
@@ -40,7 +42,9 @@ const ROLES = `roles:
 /** Temp workspace dirs to clean up after each test. */
 const tmpDirs: string[] = [];
 
-async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server: Server; baseUrl: string }> {
+async function makeHarness(
+  opts: { isAdmin?: boolean; switchOffOnRolesLock?: string } = {},
+): Promise<{ server: Server; baseUrl: string; txLog: string[] }> {
   const isAdmin = opts.isAdmin ?? true;
 
   // Back the harness with a REAL temp workspace dir: the service's single-file
@@ -103,8 +107,6 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
     }),
   } as unknown as WorkspaceService;
 
-  const authService = { getUserById: vi.fn(async () => ADMIN) } as unknown as AuthService;
-
   // Lock holder tracked so the service's getLock pre-check passes; the single-
   // file write itself lands on disk via LockingFilesystem → LocalFilesystem.
   // Strict per-path locks — a live row is contended even for the same user,
@@ -119,6 +121,8 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
     acquireLock: vi.fn(async (_w: string, _b: string, p: string, user: { id: string; name: string }) => {
       const h = locks.get(p);
       if (h) return { acquired: false, lock: lockRow(h) };
+      // An account switched off while the promotion waited for the lock.
+      if (p.endsWith('roles.yaml')) rolesLocked = true;
       locks.set(p, user);
       return { acquired: true, lock: lockRow(user) };
     }),
@@ -130,7 +134,47 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
   } as unknown as WorkflowService;
 
   const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
-  const db = usersDbDouble();
+  const accounts = [
+    { email: 'off@example.com', deactivatedAt: new Date('2026-09-01T00:00:00Z') },
+    'on@example.com',
+  ];
+  const before = usersDbDouble(accounts);
+  const after = usersDbDouble(
+    accounts.map((a) =>
+      a === opts.switchOffOnRolesLock ? { email: a, deactivatedAt: new Date('2026-10-10T00:00:00Z') } : a,
+    ),
+  );
+  let rolesLocked = false;
+  const current = () => (rolesLocked ? after : before);
+  // What happened inside each users transaction, in order: the lock taken
+  // with `execute` (rendered), and what roles.yaml held when it ended.
+  const txLog: string[] = [];
+  const rolesOnDisk = () => fs.readFile(path.join(repoDir, 'roles.yaml'), 'utf-8');
+  const db = {
+    select: () => current().select(),
+    transaction: async <T>(cb: (tx: unknown) => Promise<T>): Promise<T> => {
+      txLog.push('begin');
+      const tx = {
+        execute: async (query: SQL) => {
+          const { sql, params } = new PgDialect().sqlToQuery(query);
+          txLog.push(`${sql} ${JSON.stringify(params)}`);
+          return [];
+        },
+        select: () => current().select(),
+      };
+      try {
+        return await cb(tx);
+      } finally {
+        const onDisk = await rolesOnDisk();
+        txLog.push(`end: ${['on@example.com', 'new@example.com'].filter((e) => onDisk.includes(e)).join(', ') || 'none'}`);
+      }
+    },
+  } as unknown as typeof before;
+
+  // The real auth service over the same double, so the promotion's switch
+  // lock and read run as they do in production (`whileSwitchedOn`).
+  const authService = new AuthService(db, { jwtSecret: 'test', adminEmail: '', adminPassword: '', allowedEmailDomains: [] });
+  vi.spyOn(authService, 'getUserById').mockImplementation(async () => ADMIN);
 
   const app = express();
   app.use(express.json());
@@ -138,13 +182,13 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
     (req as unknown as { userId: string }).userId = ADMIN.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });
   const addr = server.address() as AddressInfo;
-  return { server, baseUrl: `http://127.0.0.1:${addr.port}` };
+  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, txLog };
 }
 
 function close(s: Server): Promise<void> {
@@ -258,4 +302,85 @@ describe('/api/access/roles routes', () => {
     const body = (await add.json()) as { roles: { canonical: string; members: string[] }[] };
     expect(body.roles.find((r) => r.canonical === 'sales')!.members).toContain('mkt@example.com');
   });
+
+  // The invite's promotion (`ifActive`) reads whether the account is switched
+  // off inside the roles lock, not from the list the dialog read before the
+  // send nor before the lock was waited for.
+  async function addAdmin(baseUrl: string, body: unknown) {
+    return fetch(`${baseUrl}/api/access/roles/admin/members`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  it('ifActive refuses a switched-off account (409 deactivated) and writes nothing', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    const res = await addAdmin(h.baseUrl, { email: 'Off@Example.com', ifActive: true });
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: 'This account is switched off', kind: 'deactivated' });
+    const roster = (await (await fetch(`${h.baseUrl}/api/access/roles`)).json()) as {
+      roles: { canonical: string; members: string[] }[];
+    };
+    expect(roster.roles.find((r) => r.canonical === 'admin')!.members).not.toContain('off@example.com');
+  });
+
+  it('ifActive promotes a switched-on account, and one with no account yet', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    expect((await addAdmin(h.baseUrl, { email: 'on@example.com', ifActive: true })).status).toBe(200);
+    const res = await addAdmin(h.baseUrl, { email: 'new@example.com', ifActive: true });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { roles: { canonical: string; members: string[] }[] };
+    expect(body.roles.find((r) => r.canonical === 'admin')!.members).toEqual(
+      expect.arrayContaining(['on@example.com', 'new@example.com']),
+    );
+  });
+
+  it('ifActive reads the account once the roles lock is held: one switched off while it waited is refused', async () => {
+    const h = await makeHarness({ switchOffOnRolesLock: 'on@example.com' });
+    server = h.server;
+    const res = await addAdmin(h.baseUrl, { email: 'on@example.com', ifActive: true });
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: 'This account is switched off', kind: 'deactivated' });
+    const roster = (await (await fetch(`${h.baseUrl}/api/access/roles`)).json()) as {
+      roles: { canonical: string; members: string[] }[];
+    };
+    expect(roster.roles.find((r) => r.canonical === 'admin')!.members).not.toContain('on@example.com');
+  });
+
+  // Every switch-off (and an account created switched off) takes the same
+  // lock first; see account-deactivation.test for that side.
+  it.each([
+    ['an existing account', 'On@Example.com', 'on@example.com'],
+    ['an address with no account yet', 'new@example.com', 'new@example.com'],
+  ])(
+    'ifActive holds the address switch lock until roles.yaml is written, for %s',
+    async (_label, email, canonical) => {
+      const h = await makeHarness();
+      server = h.server;
+      expect((await addAdmin(h.baseUrl, { email, ifActive: true })).status).toBe(200);
+      expect(h.txLog).toEqual([
+        'begin',
+        `select set_config('lock_timeout', $1, true) ["15000"]`,
+        `select pg_advisory_xact_lock(hashtext($1)) ["account-switch:${canonical}"]`,
+        `end: ${canonical}`,
+      ]);
+    },
+  );
+
+  it('without ifActive, adding a switched-off account works as before', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    expect((await addAdmin(h.baseUrl, { email: 'off@example.com' })).status).toBe(200);
+  });
+
+  it('refuses a non-boolean ifActive (400)', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    for (const ifActive of ['true', 1, null]) {
+      expect((await addAdmin(h.baseUrl, { email: 'on@example.com', ifActive })).status).toBe(400);
+    }
+  });
 });

package/src/modules/access/__tests__/user-access-removal.service.test.ts

@@ -329,11 +329,11 @@ describe('UserAccessRemovalService', () => {
     }
   });
 
-  it('refuses the deployment owner and the last Admin, writing nothing', async () => {
+  it('refuses the owner and the last Admin, writing nothing', async () => {
     const { service, workflow } = build(stubWorkflow(), ['Lee@x.io']);
     const report = await service.report(LEE);
     expect(report.removable).toBe(false);
-    expect(report.blockedReason).toMatch(/deployment owner/);
+    expect(report.blockedReason).toBe('The owner stays in roles and access rules.');
     await expect(service.remove(ADMIN, LEE, 'deleted-1')).rejects.toMatchObject({ status: 409 });
 
     const other = build(stubWorkflow(), []);

package/src/modules/access/__tests__/users-db-double.ts

@@ -48,12 +48,13 @@ function boundValues(node: unknown, depth = 0): string[] {
 const canonical = (email: string) => email.trim().toLowerCase();
 
 export function usersDbDouble(
-  accounts: readonly (string | { email: string; name?: string })[] = [],
+  accounts: readonly (string | { email: string; name?: string; deactivatedAt?: Date | null })[] = [],
 ): Database {
   const rows = accounts.map((a) => {
     const email = typeof a === 'string' ? a : a.email;
     const name = typeof a === 'string' ? undefined : a.name;
-    return { id: `u-${email}`, email, name: name ?? email.split('@')[0] };
+    const deactivatedAt = typeof a === 'string' ? null : (a.deactivatedAt ?? null);
+    return { id: `u-${email}`, email, name: name ?? email.split('@')[0], deactivatedAt };
   });
   const from = () => {
     // Thenable so a bare `await db.select().from(users)` resolves, with
@@ -68,5 +69,13 @@ export function usersDbDouble(
     };
     return query;
   };
-  return { select: () => ({ from }) } as unknown as Database;
+  const db = {
+    select: () => ({ from }),
+    // One connection, no isolation to model: the callback runs on the same
+    // double.
+    transaction: async <T>(cb: (tx: unknown) => Promise<T>) => cb(db),
+    // Locks taken with `execute` (advisory locks) answer nothing.
+    execute: async () => [],
+  };
+  return db as unknown as Database;
 }