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

package/src/core/create-core-services.ts

@@ -65,6 +65,7 @@ import type { Request } from 'express';
 import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
+import { AccountHooks, type IAccountHooks } from '../modules/auth/account-hooks.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
 import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
@@ -302,6 +303,12 @@ export interface CoreServices {
   githubFacade: GitHubFacade;
   githubFacadeCredentials: GitHubFacadeCredentialsService;
   authService: AuthService;
+  /**
+   * The seam for "an account was invited": a deployment registers here how
+   * the person is told (the cloud's mail, say), and the invite's answer says
+   * whether somebody did. Core registers nothing.
+   */
+  accountHooks: IAccountHooks;
   authMiddleware: ReturnType<typeof createAuthMiddleware>;
   accountErasureService: AccountErasureService;
   gitService: GitService;
@@ -815,6 +822,9 @@ export async function createCoreServices(
     ports.accountAdmission,
   );
   const authMiddleware = createAuthMiddleware(authService);
+  // Who tells an invited person: the composition root of a distribution
+  // registers its listener here, after this returns (see `AccountHooks`).
+  const accountHooks = new AccountHooks();
 
   // Shared mutex so git and diff operations on the same workspace serialize
   // against each other — a backup-reseed races a concurrent commit otherwise.
@@ -1608,6 +1618,7 @@ export async function createCoreServices(
     githubFacade,
     githubFacadeCredentials,
     authService,
+    accountHooks,
     authMiddleware,
     accountErasureService,
     gitService,

package/src/modules/access/__tests__/access-control.admin-root-floor.test.ts

@@ -133,11 +133,31 @@ describe('Admin write floor at the repository root', () => {
       expect(await service().canWrite(WS, ADMIN, 'README.md')).toBe(true);
     });
 
-    it('is write only: read and download still answer to the access tree', async () => {
-      await write(repo, 'access.md', '---\n---\nwrite:\n  - deny Admin\n');
+    it('is write and the read it implies: download still answers to the access tree', async () => {
+      await write(repo, 'access.md', '---\n---\nwrite:\n  - deny Admin\nread:\n  - deny Admin\n');
       const svc = service();
-      expect(await svc.canDownload(WS, ADMIN, 'README.md')).toBe(false);
+      for (const who of [ADMIN, OWNER]) {
+        expect(await svc.canRead(WS, who, 'README.md')).toBe(true);
+        expect(await svc.canRead(WS, who, 'Knowledge/Foo.md')).toBe(true);
+        expect(await svc.canDownload(WS, who, 'README.md')).toBe(false);
+      }
       expect(await svc.canWrite(WS, ENGINEER, 'README.md')).toBe(false);
+      expect(await svc.canRead(WS, ENGINEER, 'README.md')).toBe(false);
+      // Who may read, for the banner: the floor's holders, and nobody else.
+      expect((await svc.eligibleReaders(WS, 'Knowledge/Foo.md')).roles).toEqual(['Admin']);
+    });
+
+    it('the deployment owner, absent from roles.yaml, reads where the Admin role reads and not where it is excluded', async () => {
+      await write(repo, 'access.md', '---\n---\nread:\n  - Engineer\n');
+      await write(repo, 'HR/access.md', '---\n---\nread:\n  - Engineer\n  - deny Admin\n');
+      await write(repo, 'Ops/access.md', '---\n---\nread:\n  - deny everyone\n  - Admin\n');
+      const svc = service();
+      for (const who of [ADMIN, OWNER]) {
+        expect(await svc.canRead(WS, who, 'Knowledge/Foo.md')).toBe(true);
+        expect(await svc.canRead(WS, who, 'HR/Salaries.md')).toBe(false);
+        expect(await svc.canRead(WS, who, 'Ops/Runbook.md')).toBe(true);
+      }
+      expect(await svc.canRead(WS, ENGINEER, 'Ops/Runbook.md')).toBe(false);
     });
 
     describe('a subfolder that excludes Admin', () => {
@@ -280,6 +300,7 @@ describe('Admin write floor at the repository root', () => {
           service(),
           { ...ws, getOrCreateForBranch: async () => ({ id: WS, kbDirName: KB }) } as unknown as WorkspaceService,
           { getUserById: async (id: string) => users[id as 'u-admin'] ?? null } as unknown as AuthService,
+          { whileSwitchedOn: async (_email: string, write: () => Promise<void>) => write() },
           {
             getLock: async () => null,
             acquireLock: async () => ({ acquired: true, lock: {} }),

package/src/modules/access/__tests__/access-control.download-read.test.ts

@@ -102,7 +102,9 @@ describe('download implies read', () => {
         'access.md': '---\n---\ndownload:\n  - Product Manager\n',
       });
       expect(await svc.canRead(workspaceId, 'pm@x.io', 'Knowledge/Deal.md')).toBe(true);
-      expect(await svc.canRead(workspaceId, 'admin@x.io', 'Knowledge/Deal.md')).toBe(false);
+      // Nobody else: the fold adds no grant that was not written. (An admin
+      // reads here too, through the root floor, not through this fold.)
+      expect(await svc.canRead(workspaceId, 'mallory@x.io', 'Knowledge/Deal.md')).toBe(false);
     });
 
     it('for a GROUP grant', async () => {

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

@@ -943,16 +943,24 @@ describe('AccessControlService', () => {
       expect(await svc.canRead(workspaceId, 'sara@example.com', 'Knowledge/Foo.md')).toBe(true);
     });
 
-    it('no admin rescue for read — admins read a restricted node only if listed', async () => {
+    it('the root floor gives admins read (write implies it) whatever the root says; a nearer scope can still exclude them', async () => {
       const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
       await writeFile(repo, 'roles.yaml', ROLES_YAML);
-      // Write/read restricted to Product Manager — Admin is neither listed nor a
-      // writer here, so there's no rescue path to read (unlike write on access.md).
+      // Write/read restricted to Product Manager — Admin is not named at the
+      // root, but the floor gives Admin write there and write implies read, so
+      // an admin who could create anything under the root can also see it.
       await writeFile(repo, 'access.md', '---\nwrite:\n  - Product Manager\nread:\n  - Product Manager\n---\n');
+      // A subfolder is an ordinary scope: it takes Admin's read away as it would anyone's.
+      await writeFile(repo, 'Knowledge/Board/access.md', '---\nread:\n  - deny Admin\n---\n');
 
       const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR, new NodeFs());
-      // razvan is Admin but not a Product Manager — restricted read denies him.
-      expect(await svc.canRead(workspaceId, 'razvan@bevel.software', 'Knowledge/Foo.md')).toBe(false);
+      // razvan is Admin but not a Product Manager.
+      expect(await svc.canRead(workspaceId, 'razvan@bevel.software', 'Knowledge/Foo.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'razvan@bevel.software', 'Knowledge/Board/Minutes.md')).toBe(false);
+      // The floor is write and read, not download.
+      expect(await svc.canDownload(workspaceId, 'razvan@bevel.software', 'Knowledge/Foo.md')).toBe(false);
+      // Nobody else gains anything from it.
+      expect(await svc.canRead(workspaceId, 'ali@bevel.software', 'Knowledge/Foo.md')).toBe(false);
     });
 
     it("a node's own read: frontmatter grants just that file", async () => {
@@ -1002,17 +1010,24 @@ describe('AccessControlService', () => {
     });
 
     describe('eligibleReaders', () => {
-      it('reports restricted=true with no readers for a default-denied node', async () => {
+      it('reports restricted=true, with Admin as the one reader, for a default-denied node', async () => {
         const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
         await writeFile(repo, 'roles.yaml', ROLES_YAML);
         // The only line in the tree is a DENIAL — a denial grants nobody, and
         // no verb that folds into read grants anyone either, so the node is
-        // default-denied with no readers to name.
+        // default-denied. Admin still reads it through the root floor, and the
+        // list says so: the banner must name who can actually open it.
         await writeFile(repo, 'access.md', '---\nread:\n  - deny everyone\n---\n');
 
         const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR, new NodeFs());
         const e = await svc.eligibleReaders(workspaceId, 'Knowledge/Foo.md');
-        expect(e).toEqual({ restricted: true, principals: [], roles: [], users: [], publicVia: [] });
+        expect(e).toEqual({
+          restricted: true,
+          principals: [{ name: 'Admin', kind: 'role' }],
+          roles: ['Admin'],
+          users: [],
+          publicVia: [],
+        });
       });
 
       it('reports restricted=false when read: everyone applies', async () => {
@@ -1047,10 +1062,15 @@ describe('AccessControlService', () => {
         // node really is readable by everyone — not restricted.
         expect(await svc.canRead(workspaceId, 'felix@example.com', 'Knowledge/Open/Foo.md')).toBe(true);
         const e = await svc.eligibleReaders(workspaceId, 'Knowledge/Open/Foo.md');
+        // Admin is listed beside everyone, as it is for write: the floor holds
+        // wherever no nearer scope excludes it.
         expect(e).toEqual({
           restricted: false,
-          principals: [{ name: 'everyone', kind: 'role' }],
-          roles: ['everyone'],
+          principals: [
+            { name: 'Admin', kind: 'role' },
+            { name: 'everyone', kind: 'role' },
+          ],
+          roles: ['Admin', 'everyone'],
           users: [],
           publicVia: [],
         });
@@ -1133,19 +1153,60 @@ describe('AccessControlService', () => {
     });
 
     /**
-     * Beyond the two rescue files, the owner gets exactly what the Admin role
-     * gets: the root write floor, and nothing a nearer rule takes away. Read
-     * and download still answer to the access tree.
+     * Beyond the two rescue files, the owner IS the Admin role: the root floor
+     * (write, and the read it implies), every grant and denial that names
+     * Admin along the way, and nothing more. An owner the file does not name
+     * used to hold write everywhere and read nowhere, so the read-before-write
+     * gate refused them the very file the floor let them create.
      */
-    it('gets write only through the root floor, never past a subfolder that excludes Admin', async () => {
+    it('is bound by the Admin rules for every verb, as a member of the role would be', async () => {
       const ws = await seeded();
       const { repo } = await seedWorkspace(root, workspaceId);
       await writeFile(repo, 'HR/access.md', '---\nwrite:\n  - deny Admin\n---\n');
+      await writeFile(repo, 'Board/access.md', '---\nread:\n  - deny Admin\n---\n');
+      await writeFile(repo, 'Vault/access.md', '---\ndownload:\n  - Admin\n---\n');
       const svc = new AccessControlService(ws, PROCESS_MAP_DIR, new NodeFs(), [OWNER]);
+      // The floor: write and read under the root, not download.
       expect(await svc.canWrite(workspaceId, OWNER, 'Knowledge/Foo.md')).toBe(true);
-      expect(await svc.canWrite(workspaceId, OWNER, 'HR/Salaries.md')).toBe(false);
-      expect(await svc.canRead(workspaceId, OWNER, 'Knowledge/Foo.md')).toBe(false);
+      expect(await svc.canRead(workspaceId, OWNER, 'Knowledge/Foo.md')).toBe(true);
       expect(await svc.canDownload(workspaceId, OWNER, 'Knowledge/Foo.md')).toBe(false);
+      // A nearer rule naming Admin binds the owner too, each verb on its own.
+      expect(await svc.canWrite(workspaceId, OWNER, 'HR/Salaries.md')).toBe(false);
+      expect(await svc.canRead(workspaceId, OWNER, 'HR/Salaries.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, OWNER, 'Board/Minutes.md')).toBe(false);
+      expect(await svc.canWrite(workspaceId, OWNER, 'Board/Minutes.md')).toBe(false);
+      // A grant to Admin is a grant to the owner — the role's keys are theirs.
+      expect(await svc.canDownload(workspaceId, OWNER, 'Vault/Keys.md')).toBe(true);
+      // The explorer's batch asks the same question and gets the same answer.
+      const batch = await svc.canReadBatch(workspaceId, OWNER, ['Knowledge/Foo.md', 'Board/Minutes.md']);
+      expect([...batch.entries()]).toEqual([
+        ['Knowledge/Foo.md', true],
+        ['Board/Minutes.md', false],
+      ]);
+    });
+
+    it('is counted when the share dialog asks whether everyone can read: a public folder that denies Admin is restricted for them', async () => {
+      const ws = await seeded();
+      const { repo } = await seedWorkspace(root, workspaceId);
+      // Everyone reads, Admin is carved out, and the role's one member is let
+      // back in by name (a direct entry outranks the role's denial). The only
+      // person the denial still reaches is the owner, whom roles.yaml does not
+      // name — so a check that enumerates roles.yaml alone sees nobody denied.
+      await writeFile(
+        repo,
+        'Open/access.md',
+        '---\nread:\n  - everyone\n  - deny Admin\n  - Someone Else <someone-else@example.com>\n---\n',
+      );
+      await writeFile(repo, 'Public/access.md', '---\nread:\n  - everyone\n---\n');
+      const svc = new AccessControlService(ws, PROCESS_MAP_DIR, new NodeFs(), [OWNER]);
+      expect(await svc.canRead(workspaceId, 'someone-else@example.com', 'Open/Notes.md')).toBe(true);
+      // The denial reaches the owner, so the folder is not readable by
+      // everyone and the dialog must not say it is.
+      expect(await svc.canRead(workspaceId, OWNER, 'Open/Notes.md')).toBe(false);
+      expect((await svc.eligibleReaders(workspaceId, 'Open/Notes.md')).restricted).toBe(true);
+      // Without the carve-out the same owner reads, and the folder is public.
+      expect(await svc.canRead(workspaceId, OWNER, 'Public/Notes.md')).toBe(true);
+      expect((await svc.eligibleReaders(workspaceId, 'Public/Notes.md')).restricted).toBe(false);
     });
 
     it('is matched case-insensitively, like every other email here', async () => {

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__/change-read-gate.test.ts

@@ -185,13 +185,44 @@ describe('ChangeReadGate', () => {
 
     it('the rescues name FILES: a folder target at the root is judged as a folder, even for an admin', async () => {
       // The KB clone's own folder, asked about as an extraction destination:
-      // the root scope, which here grants nobody — an admin included.
-      expect(await judge(ADMIN, KB, 'dir')).toEqual({ allowed: false, unreadable: '' });
-      expect(await judge(ADMIN, `${KB}/KnowledgeBase`, 'dir')).toEqual({ allowed: false, unreadable: 'KnowledgeBase' });
-      // With a root that lets the admin read (write folds into read), the same folders open.
+      // the root scope. It grants nobody here, so a non-admin is refused; an
+      // admin reads it through the root floor (write implies read), which is
+      // the access tree's own answer, not a rescue.
+      expect(await judge(ALICE, KB, 'dir')).toEqual({ allowed: false, unreadable: '' });
+      expect(await judge(ALICE, `${KB}/KnowledgeBase`, 'dir')).toEqual({ allowed: false, unreadable: 'KnowledgeBase' });
+      expect(await judge(ADMIN, KB, 'dir')).toEqual({ allowed: true, via: 'readable' });
+      expect(await judge(ADMIN, `${KB}/KnowledgeBase`, 'dir')).toEqual({ allowed: true, via: 'readable' });
+    });
+
+    it('an admin may add a loose file directly in the knowledge folder, with or without a root access.md', async () => {
+      // The reported case: an admin could make a folder under the knowledge
+      // root (the new-folder exception) and write inside it, but not a page
+      // directly in the root — the floor gave them write there and nothing
+      // gave them read. Write implies read, so the floor gives both.
+      expect(await judge(ADMIN, `${KB}/KnowledgeBase/notes.md`)).toEqual({ allowed: true, via: 'readable' });
       await write(repo, 'access.md', `---\nowner:\n  - Admin\n---\nwrite:\n  - Admin\n`);
       access.invalidate(WS);
-      expect(await judge(ADMIN, KB, 'dir')).toEqual({ allowed: true, via: 'readable' });
+      expect(await judge(ADMIN, `${KB}/KnowledgeBase/notes.md`)).toEqual({ allowed: true, via: 'readable' });
+    });
+
+    it('the deployment owner is an admin for this gate too, whether or not roles.yaml names them', async () => {
+      const OWNER = 'owner@bevel.software';
+      const ws = stubWorkspaceService(path.join(root, WS));
+      const owned = new ChangeReadGate(
+        ws,
+        new AccessControlService(ws, KB, new NodeFs(), [OWNER]),
+        testKbContext({ kbDirName: KB }),
+        new NodeFs(),
+      );
+      await write(repo, 'KnowledgeBase/Board/access.md', '---\nread:\n  - deny Admin\n---\n');
+      expect(await owned.judge(WS, OWNER, `${KB}/KnowledgeBase/notes.md`, 'file')).toEqual({ allowed: true, via: 'readable' });
+      // Excluded exactly where the Admin role is.
+      expect(await owned.judge(WS, OWNER, `${KB}/KnowledgeBase/Board/memo.md`, 'file')).toEqual({
+        allowed: false,
+        unreadable: 'KnowledgeBase/Board',
+      });
+      // Not an owner on the gate's own service: no floor, no read.
+      expect(await judge(OWNER, `${KB}/KnowledgeBase/notes.md`)).toEqual({ allowed: false, unreadable: 'KnowledgeBase' });
     });
 
     it('a roles.yaml that is there but unusable is not an open door', async () => {

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