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

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

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

@@ -149,8 +149,11 @@ export type AccessDecisionSource = {
  * `via` names the tier that matched and `principal` the display name of the
  * group, role or plugin principal it matched on (the caller's own email for
  * `person`, `everyone` for the built-in). `admin-floor` is Admin's write at
- * the repository root, which no rule there can take away; its source is the
- * root's rules, or null when the root has none.
+ * the repository root, and the read that write implies, which no rule there
+ * can take away; its source is the scope the floor decided at — the root's
+ * rules (`folder`), or the own `frontmatter` of a file directly in the root,
+ * whose entries are part of the root and cannot take the floor away either —
+ * or null when the walk found no scope at all.
  */
 export interface AccessDecision {
   allowed: boolean;
@@ -678,6 +681,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

@@ -130,15 +130,16 @@ interface AccessModel {
    * Canonical emails that count as Admin whatever `roles.yaml` says — the
    * deployment owner (`ADMIN_EMAIL`). Empty when none is configured.
    *
-   * This exists for the two hardcoded `write` rescues below and the root write
-   * floor, and only those. It is NOT a general grant: it never enters scope
-   * resolution, so it gives no read, no download, and no write beyond
-   * `roles.yaml`, `access.md`, and what the root floor reaches (see
-   * `hasPermissionResolved`). The deployment owner is the person who can already change
-   * `ADMIN_EMAIL` itself, so admitting them to the rescue path concedes
-   * nothing they could not already take — while withholding it turns a
-   * `roles.yaml` that has lost its last Admin into a knowledge base nobody
-   * can repair through the app.
+   * An owner IS an Admin, for every verb: resolution gives them the Admin
+   * role's own keys (`principalKeysOf`), so they read, download, write and
+   * own exactly where a member of the role does and are excluded exactly
+   * where the role is, and they hold the two hardcoded `write` rescues and
+   * the root floor as the role does. The owner is the person who can already
+   * change `ADMIN_EMAIL` itself, so none of this concedes anything they could
+   * not already take — while withholding it turns a `roles.yaml` that has
+   * lost its last Admin into a knowledge base nobody can repair through the
+   * app, and an owner the file does not name into someone the write floor
+   * admits everywhere and the read gate admits nowhere.
    */
   deploymentOwners: ReadonlySet<string>;
 }
@@ -478,19 +479,38 @@ function resolveAtPath(
 /**
  * Every principal key a caller holds: the tokens their email is a member of,
  * plus the PUBLIC keys every caller holds regardless (a plugin principal
- * whose plugin grants `everyone`). Undefined when there is nothing at all,
+ * whose plugin grants `everyone`), plus — for a deployment owner — the Admin
+ * role's own keys, whether or not `roles.yaml` names them: the owner IS an
+ * Admin (see `AccessModel.deploymentOwners`), so every rule that binds the
+ * role binds them, for every verb. Undefined when there is nothing at all,
  * matching the plain `byEmail.get` the tier-2 check used to read.
  */
 function principalKeysOf(model: AccessModel, email: string): Set<string> | undefined {
   const own = model.roles.byEmail.get(email);
   const pub = model.roles.publicKeys;
-  if (!pub?.size) return own;
-  return new Set([...(own ?? []), ...pub]);
+  const asOwner = model.deploymentOwners.has(email) && !own?.has(ADMIN_ROLE_KEY);
+  if (!pub?.size && !asOwner) return own;
+  return new Set([
+    ...(own ?? []),
+    ...(pub ?? []),
+    ...(asOwner ? principalKeysOfToken(model, ADMIN_ROLE_KEY) : []),
+  ]);
 }
 
 /** The explicit key of the Admin ROLE — never the bare token, which a same-named group may own. */
 const ADMIN_ROLE_KEY = `${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`;
 
+/**
+ * The verbs the Admin floor at the repository root confers: write, and the
+ * read that write implies (`VERB_REQUIRES`). An admin who may change
+ * everything under the root may see it; otherwise the read-before-write gate
+ * refuses them the very change the floor grants. Download is not implied by
+ * write and stays with the access tree.
+ */
+function holdsAdminFloor(verb: Verb): boolean {
+  return verb === 'write' || verb === 'read';
+}
+
 /**
  * Add to `keys` what holding them confers on top: every plugin principal
  * expanded from one of the keys, and the public keys every caller holds.
@@ -540,9 +560,10 @@ const NO_KEYS: ReadonlySet<string> = new Set();
 /**
  * The tier-2 half of `hasPermissionResolved` on its own: a verdict for a set
  * of principal KEYS with no person behind them — no direct-email tier, no
- * admin rescue, no machine-owned rule — only the Admin write floor, when the
- * keys include the Admin role. Closest scope first; within a scope a
- * grant to any key wins over a denial to another, exactly as for a person.
+ * admin rescue, no machine-owned rule — only the Admin floor (write, and the
+ * read it implies), when the keys include the Admin role. Closest scope
+ * first; within a scope a grant to any key wins over a denial to another,
+ * exactly as for a person.
  */
 function hasPermissionForKeys(
   model: AccessModel,
@@ -551,7 +572,7 @@ function hasPermissionForKeys(
   relativePath: string,
   fileOwn?: OwnEntries | null,
 ): boolean {
-  const adminFloor = verb === 'write' && keys.has(ADMIN_ROLE_KEY);
+  const adminFloor = holdsAdminFloor(verb) && keys.has(ADMIN_ROLE_KEY);
   for (const scope of resolveScopes(model, verb, relativePath, fileOwn)) {
     if (adminFloor && isAdminFloorScope(scope, relativePath)) return true;
     let grant = false;
@@ -620,17 +641,20 @@ function isAdminEmail(model: AccessModel, email: string): boolean {
  * owner is whoever can already set `ADMIN_EMAIL`, so this concedes no
  * authority they did not have; it only gives it a door.
  *
- * One floor for `write`, applied during the walk: an admin (same definition)
- * always holds `write` at the repository root. When the walk reaches the root
- * `access.md` (or the own frontmatter of a file directly in the root) — or runs
- * out of scopes without a verdict — an admin is granted,
- * whatever the root file says, so no root rule can lock the deployment out of
- * its own tree. A NEARER scope still decides first: a subfolder that denies
- * Admin (or denies `everyone` without naming Admin) excludes admins there like
- * anyone else. The root file's own entries are not rewritten — the floor is a
- * verdict, not a grant line — so `grantSources` stays file-backed.
+ * One floor for `write` and the `read` it implies (`holdsAdminFloor`), applied
+ * during the walk: an admin (same definition) always holds both at the
+ * repository root. When the walk reaches the root `access.md` (or the own
+ * frontmatter of a file directly in the root) — or runs out of scopes without
+ * a verdict — an admin is granted, whatever the root file says, so no root
+ * rule can lock the deployment out of its own tree, and nobody who may change
+ * everything under the root is refused the sight of it. A NEARER scope still
+ * decides first: a subfolder that denies Admin (or denies `everyone` without
+ * naming Admin) excludes admins there like anyone else. The root file's own
+ * entries are not rewritten — the floor is a verdict, not a grant line — so
+ * `grantSources` stays file-backed.
  *
- * No special-cases for `read`/`download` — they fall through to scope resolution.
+ * No special-case for `download` (or `owner`) — they fall through to scope
+ * resolution; write implies read, not download.
  */
 function hasPermissionResolved(
   model: AccessModel,
@@ -676,14 +700,12 @@ function decidePermissionResolved(
     }
   }
 
-  const adminFloor = verb === 'write' && isAdminEmail(model, email);
-  // For write, the deployment owner IS Admin — the floor admits them, so the
-  // Admin rules along the way bind them too: a subfolder denying Admin excludes
-  // the owner exactly as it excludes the role's members.
-  let userRoles = principalKeysOf(model, email);
-  if (adminFloor && !userRoles?.has(ADMIN_ROLE_KEY)) {
-    userRoles = new Set([...(userRoles ?? []), ...principalKeysOfToken(model, ADMIN_ROLE_KEY)]);
-  }
+  const adminFloor = holdsAdminFloor(verb) && isAdminEmail(model, email);
+  // The deployment owner IS Admin: `principalKeysOf` gives them the role's
+  // keys, so the Admin rules along the way bind them too — a subfolder
+  // denying Admin excludes the owner exactly as it excludes the role's
+  // members, and one granting Admin admits them.
+  const userRoles = principalKeysOf(model, email);
   const scopes = resolveScopes(model, verb, relativePath, fileOwn);
 
   for (const scope of scopes) {
@@ -1090,12 +1112,11 @@ function canEveryoneReadResolved(
   // Every *named* principal must also still read. A collapsed deny may have
   // been shadowed by a closer-scope `everyone` grant, so re-resolve each
   // candidate through the closeness-first gate rather than trusting the
-  // collapsed deny state. (Role members live in roles.yaml; inline-named users
-  // come from `byEmail`.)
-  const candidates = new Set<string>();
-  for (const email of model.roles.byEmail.keys()) candidates.add(email);
-  for (const email of byEmail.keys()) candidates.add(email);
-  for (const email of candidates) {
+  // collapsed deny state. The candidates are the same set the eligible-email
+  // lists enumerate — roles.yaml members, inline-named users, and the
+  // deployment owner, whom a `deny Admin` carves out like any member of the
+  // role whether or not roles.yaml names them.
+  for (const email of namedCandidateEmails(model, byEmail)) {
     if (!hasPermissionResolved(model, 'read', email, relativePath, fileOwn)) return false;
   }
   return true;
@@ -1106,11 +1127,14 @@ function canEveryoneReadResolved(
  *
  * Read is default-deny: a path is readable only when resolution grants the
  * caller `read` directly, via one of their roles, via the built-in `everyone`
- * role, or via `owner:` (owners implicitly read).
+ * role, or via `write:`/`owner:` (both imply read).
  *
- * No admin rescue (mirrors `download`): admins read a node only if an
- * `access.md` lists them — directly, via a role, through `everyone`, or as an
- * owner.
+ * No admin rescue on root files (that is write's), but the Admin floor
+ * holds: an admin — a member of the role or the deployment owner — reads
+ * wherever no nearer scope excludes Admin, whether or not the root names it,
+ * because the floor gives them write there and write implies read. A
+ * subfolder that denies Admin, or everyone, takes the read away as it does
+ * for any principal.
  */
 function canReadResolved(
   model: AccessModel,
@@ -1183,9 +1207,10 @@ function eligibleHoldersResolved(
     const record = model.roles.byCanonical.get(canonical);
     addPrincipal(record ? record.displayName : canonical, record?.kind ?? 'role');
   }
-  // The Admin write floor (see `hasPermissionResolved`): Admin holds write here
-  // whenever no nearer scope excludes it, whether or not any file names it.
-  if (verb === 'write' && model.roles.byCanonical.has(ADMIN_ROLE_KEY)) {
+  // The Admin floor (see `hasPermissionResolved`): Admin holds write, and the
+  // read it implies, here whenever no nearer scope excludes it, whether or not
+  // any file names it.
+  if (holdsAdminFloor(verb) && model.roles.byCanonical.has(ADMIN_ROLE_KEY)) {
     const adminRole = model.roles.byCanonical.get(ADMIN_ROLE_KEY)!;
     if (allowedFor(principalKeysOfToken(model, ADMIN_ROLE_KEY))) addPrincipal(adminRole.displayName, 'role');
   }
@@ -1232,8 +1257,8 @@ function eligibleHoldersResolved(
 
 /**
  * Every individual the model names: `roles.yaml` members, emails named inline
- * at this path's scope, and the deployment owner (Admin for the write floor
- * even when `roles.yaml` does not list them).
+ * at this path's scope, and the deployment owner (bound by every rule that
+ * names Admin even when `roles.yaml` does not list them).
  */
 function namedCandidateEmails(model: AccessModel, byEmail: CollapsedScope['byEmail']): Set<string> {
   const candidates = new Set<string>(model.deploymentOwners);
@@ -2164,6 +2189,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,