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

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;
 }

package/src/modules/access/access-control.interface.ts

@@ -678,6 +678,16 @@ export interface IAccessControl {
    */
   holdsAdminRootWrite(workspaceId: string, userEmail: string): Promise<boolean>;
 
+  /**
+   * Every address the resolver treats as an Admin in the working-tree model,
+   * each once: the Admin role's members — through a group too — and the
+   * deployment owners. The same membership answer {@link holdsAdminRootWrite}
+   * gives one address at a time, enumerated. When the model cannot be loaded
+   * (a `roles.yaml` that does not parse makes nobody an Admin), the
+   * deployment owners alone.
+   */
+  adminEmails(workspaceId: string): Promise<string[]>;
+
   /**
    * Whether `userEmail` may put a misplaced platform file back at
    * `destinationRelativePath` — the ONE write that is allowed to land on a

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

@@ -2164,6 +2164,25 @@ export class AccessControlService implements IAccessControl {
     return isAdminEmail(model, canonicalEmail(userEmail));
   }
 
+  async adminEmails(workspaceId: string): Promise<string[]> {
+    let model: AccessModel;
+    try {
+      model = await this.loadModel(workspaceId);
+    } catch (err) {
+      // As canRestorePlatformFile: with no model to ask, the deployment owners
+      // are the only admins left. A `roles.yaml` that does not parse is that
+      // by design; anything else (a clone being read, the disk) is said, so a
+      // list that names fewer admins than there are is diagnosable.
+      if (!(err instanceof AccessConfigError)) {
+        log.warn('the access model could not be loaded; the admins list names the deployment owners only:', { err });
+      }
+      return [...this.deploymentOwners];
+    }
+    const candidates = new Set<string>(model.deploymentOwners);
+    for (const email of model.roles.byEmail.keys()) candidates.add(email);
+    return [...candidates].filter((email) => isAdminEmail(model, email));
+  }
+
   async canRestorePlatformFile(
     workspaceId: string,
     userEmail: string,

package/src/modules/access/access.routes.ts

@@ -21,6 +21,7 @@ import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { AuthService } from '../auth/auth.service.js';
+import type { IAccountSwitchGuard } from '../auth/account-switch-guard.js';
 import type { WorkflowService } from '../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
@@ -51,6 +52,7 @@ import { RolesAdminService } from './roles-admin.service.js';
 import type { Principal } from '../access-model/access-splice.js';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import '../auth/auth.middleware.js';
 
 /** Verbs the share UI may grant. Verbs are independent — `download` is grantable on its own. */
@@ -85,6 +87,8 @@ export function createAccessRoutes(
   accessControl: IAccessControl,
   workspaceService: WorkspaceService,
   authService: AuthService,
+  /** Auth's switch-off coordination, for the invite's promotion (`ifActive`). */
+  switchGuard: IAccountSwitchGuard,
   workflowService: WorkflowService,
   eventBus: WorkflowEventBus,
   db: Database,
@@ -431,12 +435,15 @@ export function createAccessRoutes(
 
   /**
    * POST /api/workspace/:id/access/batch
-   * Body: `{ paths: string[], verb?: 'write' | 'owner' }`. Returns
+   * Body: `{ paths: string[], verb?: 'write' | 'owner' | 'read' }`. Returns
    * `{ results: { [path]: boolean } }`.
    *
    * `verb` defaults to `write`, the question every existing caller asks.
    * `owner` answers from the `owner:` lists alone — no admin rescue, and a
-   * writer is not an owner — which is what an Owner pill has to mean.
+   * writer is not an owner — which is what an Owner pill has to mean. `read`
+   * is the verdict the single lookup's `canRead` gives, for many paths at
+   * once: what New page asks on a draft branch, where a page may go wherever
+   * its author may read, of every Knowledge folder in one request.
    */
   router.post('/workspace/:id/access/batch', async (req, res) => {
     const user = await requireUser(req, res);
@@ -451,13 +458,18 @@ export function createAccessRoutes(
       res.status(400).json({ error: 'paths cannot exceed 500 entries per request' });
       return;
     }
-    if (verb !== 'write' && verb !== 'owner') {
-      res.status(400).json({ error: 'verb must be "write" or "owner"' });
+    if (verb !== 'write' && verb !== 'owner' && verb !== 'read') {
+      res.status(400).json({ error: 'verb must be "write", "owner" or "read"' });
       return;
     }
 
     try {
-      const batch = verb === 'owner' ? accessControl.canOwnerBatch : accessControl.canWriteBatch;
+      const batch =
+        verb === 'owner'
+          ? accessControl.canOwnerBatch
+          : verb === 'read'
+            ? accessControl.canReadBatch
+            : accessControl.canWriteBatch;
       const result = await batch.call(
         accessControl,
         req.params.id,
@@ -1228,6 +1240,39 @@ export function createAccessRoutes(
     }
   });
 
+  // Who the admins are, for anyone signed in: the top bar tells someone who
+  // is not an admin to ask one, and names them. Names and emails ONLY — the
+  // roster above (every role, its members, groups and references) stays
+  // admin-only. Names come from the accounts table; an admin with no account
+  // yet (a deployment admin before first sign-in, say) is named by address.
+  // A role member whose account is switched off cannot sign in to invite
+  // anyone, so is left out; a deployment admin is not (it signs in with the
+  // environment's password regardless).
+  router.get('/access/admins', async (req, res) => {
+    const user = await requireUser(req, res);
+    if (!user) return;
+    try {
+      const emails = await rolesAdmin.getAdminEmails();
+      const rows =
+        emails.length === 0
+          ? []
+          : await db
+              .select({ email: users.email, name: users.name, deactivatedAt: users.deactivatedAt })
+              .from(users)
+              .where(inArray(users.emailBidx, emails));
+      const names = new Map(rows.map((r) => [canonicalEmail(r.email), r.name?.trim() ?? '']));
+      const off = new Set(rows.filter((r) => r.deactivatedAt).map((r) => canonicalEmail(r.email)));
+      const admins = emails
+        .filter((email) => !off.has(email) || rolesAdmin.isFixedAdmin(email))
+        .map((email) => ({ name: names.get(email) || email, email }))
+        .sort((a, b) => a.name.localeCompare(b.name) || a.email.localeCompare(b.email));
+      res.json({ admins });
+    } catch (err) {
+      const { status, body } = toHttpError(err);
+      res.status(status).json(body);
+    }
+  });
+
   // NOTE: POST /access/roles (create), PATCH /access/roles/:canonical
   // (rename), and DELETE /access/roles/:canonical are GONE — roles are
   // app-defined capabilities, not user-editable objects.
@@ -1239,7 +1284,23 @@ export function createAccessRoutes(
       await assertRolesAdmin(user.email);
       const canonical = canonicalRoleName(req.params.canonical);
       const email = requireNonEmptyString((req.body ?? {}).email, 'email');
-      res.json({ roles: await rolesAdmin.addMember(user, canonical, email) });
+      // `ifActive`: the invite's promotion, which leaves a switched-off
+      // account unchanged. Inside the roles file's lock, auth reads the
+      // account under the address's switch lock and keeps that transaction
+      // open until roles.yaml is written and committed
+      // (`IAccountSwitchGuard.whileSwitchedOn`). So a switch-off either committed
+      // before the read (the promotion is refused) or waits until the
+      // promotion is written (it lands after, as for any Admin switched off
+      // later: the place in roles stays, the credentials stop being honoured).
+      const ifActive = (req.body ?? {}).ifActive;
+      if (ifActive !== undefined && typeof ifActive !== 'boolean') {
+        res.status(400).json({ error: 'ifActive must be a boolean' });
+        return;
+      }
+      const whileSwitchedOn = (write: () => Promise<void>): Promise<void> => switchGuard.whileSwitchedOn(email, write);
+      res.json({
+        roles: await rolesAdmin.addMember(user, canonical, email, ifActive ? { aroundWrite: whileSwitchedOn } : undefined),
+      });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);

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

@@ -103,6 +103,13 @@ export interface RoleRosterEntry {
    * email once, as fixed.
    */
   fixedMembers: string[];
+  /**
+   * The note the page prints beside {@link fixedMembers}, and the sentence
+   * both Admin-membership refusals lead with. Sent with the roster so the
+   * page keeps no copy of the wording. Null when the role has no fixed
+   * members.
+   */
+  fixedMembersNote: string | null;
   /** Canonical names of groups this role is assigned to (`group:` members). */
   groups: string[];
   isAdmin: boolean;
@@ -165,11 +172,12 @@ export class RolesAdminService {
   private readonly fixedAdminEmails: readonly string[];
   /**
    * The one explanation both Admin-role refusals carry, verbatim: the note the
-   * page prints beside a fixed member. Kept as a named constant so the refusal
-   * an API caller reads and the note a UI reader sees cannot drift apart.
+   * page prints beside a fixed member, which it reads from the roster's
+   * `fixedMembersNote`. One constant, so the refusal an API caller reads and
+   * the note a UI reader sees cannot drift apart.
    */
   private static readonly FIXED_ADMIN_NOTE =
-    'Deployment admin, set in the server configuration; cannot be removed here';
+    'Owner; cannot be removed here';
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
@@ -227,9 +235,10 @@ export class RolesAdminService {
   /**
    * Is `email` a deployment admin — an address the server configuration makes
    * an Admin, ahead of `roles.yaml`? Drives both the fixed member rows and
-   * the add/remove refusals on the Admin role.
+   * the add/remove refusals on the Admin role, and keeps a switched-off
+   * deployment admin among the admins people are told to ask.
    */
-  private isFixedAdmin(email: string): boolean {
+  isFixedAdmin(email: string): boolean {
     return this.fixedAdminEmails.includes(canonicalEmail(email));
   }
 
@@ -326,6 +335,8 @@ export class RolesAdminService {
         // Only Admin has fixed members: `deploymentOwners` is an Admin rescue
         // in the resolver, never a general grant, so no other role gains one.
         fixedMembers: isAdmin ? [...this.fixedAdminEmails] : [],
+        fixedMembersNote:
+          isAdmin && this.fixedAdminEmails.length > 0 ? RolesAdminService.FIXED_ADMIN_NOTE : null,
         groups: role.members
           .filter(isGroupRefMember)
           .map((m) => canonicalRoleName(m.slice(GROUP_REF_PREFIX.length))),
@@ -342,6 +353,18 @@ export class RolesAdminService {
     return out;
   }
 
+  /**
+   * The addresses the app treats as an Admin, each once — the resolver's own
+   * membership answer ({@link IAccessControl.adminEmails}), so who this names
+   * and who the admin gates admit cannot drift apart. Nothing else about
+   * roles: this backs a read any signed-in person may make (who to ask for an
+   * invite), unlike the roster.
+   */
+  async getAdminEmails(): Promise<string[]> {
+    const workspaceId = await this.ensureWorkspace();
+    return this.accessControl.adminEmails(workspaceId);
+  }
+
   /**
    * Whether the default-branch roles.yaml parses. Drives the "roles file
    * corrupted" banner. Auth-only (never admin-gated): a corrupted file resolves
@@ -446,10 +469,24 @@ export class RolesAdminService {
    * admits it ahead of `roles.yaml` — so the write would add a row that means
    * nothing, next to the fixed row the page already shows. Other roles are
    * unaffected: a deployment admin is an ordinary member of "Sales".
+   *
+   * `aroundWrite`, when given, runs once the roles file's lock is held and
+   * is handed the edit itself (read, check, write, commit) to run. What it
+   * does around that call brackets the whole write: the invite holds the
+   * address's account-switch lock (a transaction-scoped advisory lock keyed
+   * on the canonical email, see `AuthService.whileSwitchedOn`) across it, so
+   * a switch-off cannot commit in between, whether or not the account exists
+   * yet (see the members route). It may throw instead of calling `write`;
+   * nothing is written then.
    */
-  async addMember(actor: AuthUser, canonical: string, email: string): Promise<RoleRosterEntry[]> {
+  async addMember(
+    actor: AuthUser,
+    canonical: string,
+    email: string,
+    opts?: { aroundWrite?: (write: () => Promise<void>) => Promise<void> },
+  ): Promise<RoleRosterEntry[]> {
     this.assertNotFixedAdmin(canonical, email);
-    await this.runEdit(actor, (text) => editAddMember(text, canonical, email));
+    await this.runEdit(actor, (text) => editAddMember(text, canonical, email), opts?.aroundWrite);
     return this.getRoster();
   }
 
@@ -682,17 +719,20 @@ export class RolesAdminService {
    * `pre` produces the candidate (and may throw RolesAdminError for invariant
    * violations before any write). Skips on a no-op. Every candidate passes
    * the resolver's own parser (assertLoadable) plus the pre-disk validator
-   * before a byte lands.
+   * before a byte lands. `aroundWrite` wraps the locked edit (see
+   * {@link addMember}).
    */
   private async runEdit(
     actor: AuthUser,
     pre: (currentText: string) => EditResult,
+    aroundWrite?: (write: () => Promise<void>) => Promise<void>,
   ): Promise<void> {
     const workspaceId = await this.ensureWorkspace();
     await this.assertRolesUnlocked(workspaceId, actor);
-    return this.locked.withFileLocks(workspaceId, actor, [ROLES_YAML], () =>
-      this.runEditLocked(workspaceId, actor, pre),
-    );
+    return this.locked.withFileLocks(workspaceId, actor, [ROLES_YAML], () => {
+      const write = () => this.runEditLocked(workspaceId, actor, pre);
+      return aroundWrite ? aroundWrite(write) : write();
+    });
   }
 
   private async runEditLocked(

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

@@ -492,7 +492,7 @@ export class UserAccessRemovalService {
   /** Why `email` may not be removed from access files, or null when it may. */
   private blockedReason(rolesText: string | undefined, email: string): string | null {
     if (this.deploymentOwners.some((o) => canonicalEmail(o) === email)) {
-      return 'This is the deployment owner (ADMIN_EMAIL); their access cannot be removed here.';
+      return 'The owner stays in roles and access rules.';
     }
     const admin = rolesText
       ? (() => {