@bevel-software/platform-core-backend 0.14.0 → 0.19.0

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

@@ -0,0 +1,360 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+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 type { WorkflowService } from '../../workflow/workflow.service.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import { createAccessRoutes } from '../access.routes.js';
+import type { Database } from '../../database/connection.js';
+import { usersDbDouble } from './users-db-double.js';
+
+/**
+ * A grant to an email with NO ACCOUNT says so, and stays allowed.
+ *
+ * Under single sign-on an account exists only after the first sign-in, so
+ * granting ahead of time is a real use case — nothing here refuses it. What
+ * the routes owe the share dialog is the fact: `hasAccount` on every person
+ * in the access view and in a suggestion, so the dialog can label the chip
+ * and the row "hasn't signed in yet". The three cases the ticket names are
+ * each pinned below: a known email, an unknown one, and one that becomes
+ * known once that person signs in.
+ */
+
+const USER = { id: 'u-1', email: 'alice@bevel.software', name: 'Alice' };
+const WS = 'alice/feature';
+const KB = 'knowledge-base';
+
+const KNOWN = { name: 'Alice', email: 'alice@bevel.software' };
+const UNKNOWN = { name: 'new.colleague', email: 'new.colleague@company.com' };
+
+async function makeHarness(opts: {
+  /** People named in the access rules (whether or not they have an account). */
+  granted?: { name: string; email: string }[];
+  /** Emails that have SIGNED IN — the `users` table. */
+  accounts?: string[];
+  /** People the knowledge base knows of, for the suggest route. */
+  kbPeople?: { name: string; email: string }[];
+  /** People RESTRICTED on the target — named by a `deny`, holding nothing. */
+  denied?: { name: string; email: string }[];
+  /** Override the users database — to stand in a lookup that is DOWN. */
+  db?: Database;
+}): Promise<{ server: Server; baseUrl: string; files: Map<string, string> }> {
+  const files = new Map<string, string>();
+  const granted = opts.granted ?? [];
+
+  const accessControl = {
+    canWrite: vi.fn(async () => true),
+    canRead: vi.fn(async () => true),
+    canDownload: vi.fn(async () => false),
+    canOwner: vi.fn(async () => false),
+    grantSources: vi.fn(async () => ({ read: [{ kind: 'direct' }] })),
+    invalidate: vi.fn(),
+    kbPrincipals: vi.fn(async () => ({ roles: [], groups: [], people: opts.kbPeople ?? [] })),
+    eligibleWriters: vi.fn(async () => ({ roles: [], users: granted })),
+    eligibleReaders: vi.fn(async () => ({ restricted: true, roles: [], users: granted })),
+    eligibleOwners: vi.fn(async () => ({ roles: [], users: [] })),
+    eligibleDownloaders: vi.fn(async () => ({ roles: [], users: [] })),
+    locallyDeniedPrincipals: vi.fn(async () => ({ principals: [], users: opts.denied ?? [] })),
+  } as unknown as IAccessControl;
+
+  const workspaceService = {
+    withPathTurn: async (_id: string, _p: string, op: () => Promise<unknown>) => op(),
+    getOrCreateForBranch: vi.fn(async () => ({ id: WS, name: WS, kbDirName: KB })),
+    readFile: vi.fn(async (_id: string, wsRel: string) => {
+      const v = files.get(wsRel);
+      if (v === undefined) {
+        const err = new Error(`ENOENT ${wsRel}`) as NodeJS.ErrnoException;
+        err.code = 'ENOENT';
+        throw err;
+      }
+      return v;
+    }),
+    readFileBinary: vi.fn(async (_id: string, wsRel: string) =>
+      Buffer.from(
+        await (workspaceService.readFile as (id: string, p: string) => Promise<string>)(_id, wsRel),
+        'utf-8',
+      ),
+    ),
+    writeFile: vi.fn(async (_id: string, wsRel: string, content: string) => {
+      files.set(wsRel, content);
+    }),
+  } as unknown as WorkspaceService;
+
+  const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
+  const workflowService = {
+    getLock: vi.fn(async () => null),
+    acquireLock: vi.fn(async () => ({ acquired: true, lock: {} })),
+    releaseLock: vi.fn(async () => undefined),
+    releaseLockNoCommit: vi.fn(async () => undefined),
+  } as unknown as WorkflowService;
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = USER.id;
+    next();
+  });
+  app.use(
+    '/api',
+    createAccessRoutes(
+      accessControl,
+      workspaceService,
+      authService,
+      workflowService,
+      { emit: vi.fn() } as unknown as WorkflowEventBus,
+      opts.db ?? usersDbDouble(opts.accounts ?? []),
+      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}`, files };
+}
+
+function close(s: Server): Promise<void> {
+  return new Promise((resolve, reject) => s.close((e) => (e ? reject(e) : resolve())));
+}
+
+describe('a grant to an email with no account', () => {
+  let h: Awaited<ReturnType<typeof makeHarness>> | null = null;
+  afterEach(async () => {
+    if (h) await close(h.server);
+    h = null;
+  });
+
+  const view = async () =>
+    fetch(
+      `${h!.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access?path=${encodeURIComponent(`${KB}/Sales`)}&kind=folder`,
+    );
+
+  const grantRead = (email: string, displayName: string) =>
+    fetch(`${h!.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/grant`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        path: `${KB}/Sales`,
+        kind: 'folder',
+        verb: 'read',
+        principal: { kind: 'user', email, displayName },
+      }),
+    });
+
+  it('saves the grant — an email with no account is accepted, written and labelled', async () => {
+    // `granted` is the resolver's answer AFTER the splice: the grant route
+    // writes the file, and the view it returns comes from the resolver.
+    h = await makeHarness({ granted: [UNKNOWN], accounts: [KNOWN.email] });
+
+    const res = await grantRead(UNKNOWN.email, UNKNOWN.name);
+    expect(res.status).toBe(200);
+    // Written, verbatim, to the same place a known email would be — no
+    // refusal, no rewriting, nothing conditional on the account existing.
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain(UNKNOWN.email);
+
+    // And the view that same response returns already carries the label, so
+    // the dialog can show it without a second round trip.
+    const body = (await res.json()) as {
+      readers: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(body.readers.users).toEqual([{ ...UNKNOWN, hasAccount: false }]);
+  });
+
+  it('marks a KNOWN email as having an account', async () => {
+    h = await makeHarness({ granted: [KNOWN], accounts: [KNOWN.email] });
+
+    const body = (await (await view()).json()) as {
+      readers: { users: { email: string; hasAccount: boolean }[] };
+      eligible: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(body.readers.users).toEqual([{ ...KNOWN, hasAccount: true }]);
+    // Every list the dialog reads says the same thing about the same person.
+    expect(body.eligible.users).toEqual([{ ...KNOWN, hasAccount: true }]);
+  });
+
+  it('marks an UNKNOWN email as having no account, without dropping them from any list', async () => {
+    h = await makeHarness({ granted: [KNOWN, UNKNOWN], accounts: [KNOWN.email] });
+
+    const body = (await (await view()).json()) as {
+      readers: { users: { email: string; hasAccount: boolean }[] };
+      eligible: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(body.readers.users).toEqual([
+      { ...KNOWN, hasAccount: true },
+      { ...UNKNOWN, hasAccount: false },
+    ]);
+    // "Any list" means every list the dialog reads, not just the readers: a
+    // regression that filtered account-less people out of the eligible set
+    // would hide them from the writers half of the dialog while the readers
+    // assertion above still passed.
+    expect(body.eligible.users).toEqual([
+      { ...KNOWN, hasAccount: true },
+      { ...UNKNOWN, hasAccount: false },
+    ]);
+  });
+
+  it('labels a person who is only RESTRICTED here — a deny on a mistyped address restricts nobody', async () => {
+    // Restricted people hold nothing, so no eligible list names them; the
+    // `deny` is still an entry on this target with a row of its own, and that
+    // row is where a typo would otherwise stay invisible.
+    h = await makeHarness({ denied: [KNOWN, UNKNOWN], accounts: [KNOWN.email] });
+
+    const body = (await (await view()).json()) as {
+      deniedHere: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(body.deniedHere.users).toEqual([
+      { ...KNOWN, hasAccount: true },
+      { ...UNKNOWN, hasAccount: false },
+    ]);
+  });
+
+  it('flips to hasAccount: true once that person signs in — the written grant is byte-identical', async () => {
+    // The same grant, made twice: once against a deployment where that person
+    // has never signed in, once where they have. The only difference between
+    // the two is the `users` row that signing in creates — so the BYTES each
+    // one writes to access.md are compared, not assumed: the label is allowed
+    // to flip, the grant is not allowed to differ.
+    const ACCESS_MD = `${KB}/Sales/access.md`;
+
+    const before = await makeHarness({ granted: [UNKNOWN], accounts: [] });
+    h = before;
+    expect((await grantRead(UNKNOWN.email, UNKNOWN.name)).status).toBe(200);
+    const writtenBefore = before.files.get(ACCESS_MD);
+    expect(writtenBefore).toContain(UNKNOWN.email);
+    const beforeBody = (await (await view()).json()) as {
+      readers: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(beforeBody.readers.users).toEqual([{ ...UNKNOWN, hasAccount: false }]);
+    await close(before.server);
+
+    h = await makeHarness({ granted: [UNKNOWN], accounts: [UNKNOWN.email] });
+    expect((await grantRead(UNKNOWN.email, UNKNOWN.name)).status).toBe(200);
+    // Same address, same file, same bytes — having an account changed nothing
+    // about what the grant IS.
+    expect(h.files.get(ACCESS_MD)).toBe(writtenBefore);
+    const afterBody = (await (await view()).json()) as {
+      readers: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(afterBody.readers.users).toEqual([{ ...UNKNOWN, hasAccount: true }]);
+  });
+
+  it('still answers the grant when the users lookup is down — the label is omitted, not guessed', async () => {
+    // The view is built AFTER the mutation commits. A users table that is
+    // unreachable at that instant must not turn a grant that was written into
+    // a 500 the caller reads as "it did not save" — the flag is informational,
+    // so it goes missing and nothing else does.
+    const down = {
+      select: () => ({
+        from: () => {
+          const query = Promise.reject(new Error('users table unavailable')) as Promise<never> & {
+            where: () => Promise<never>;
+          };
+          // The bare-await form is rejected too; swallow its unhandled
+          // rejection, the route only reaches the `.where()` branch here.
+          query.catch(() => {});
+          query.where = () => Promise.reject(new Error('users table unavailable'));
+          return query;
+        },
+      }),
+    } as unknown as Parameters<typeof makeHarness>[0]['db'];
+
+    h = await makeHarness({ granted: [UNKNOWN], db: down });
+
+    const res = await grantRead(UNKNOWN.email, UNKNOWN.name);
+    expect(res.status).toBe(200);
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain(UNKNOWN.email);
+
+    // No `hasAccount` at all — "the server did not say", which the dialog
+    // reads as no label, rather than a false claim that nobody has an account.
+    const body = (await res.json()) as {
+      readers: { users: { email: string; hasAccount?: boolean }[] };
+    };
+    expect(body.readers.users).toEqual([UNKNOWN]);
+    expect(body.readers.users[0].hasAccount).toBeUndefined();
+  });
+
+  it('matches accounts case-insensitively — a grant typed in capitals is still the same person', async () => {
+    h = await makeHarness({
+      granted: [{ name: 'Alice', email: 'Alice@Bevel.Software' }],
+      accounts: [KNOWN.email],
+    });
+
+    const body = (await (await view()).json()) as {
+      readers: { users: { email: string; hasAccount: boolean }[] };
+    };
+    expect(body.readers.users[0].hasAccount).toBe(true);
+  });
+
+  it('suggest puts the exact address asked for first, so the cap can never hide it', async () => {
+    // Twenty-one people all match the query (each filler email CONTAINS the
+    // exact one), with the exact match last in union order. The cap is 15, so
+    // without exact-first it falls off the end — and a chip labels itself by
+    // ABSENCE from this list, which would say "hasn't signed in yet" about
+    // somebody who has.
+    const EXACT = { name: 'Zoe', email: 'zoe.team@company.com' };
+    const crowd = Array.from({ length: 20 }, (_, i) => ({
+      name: `Filler ${i}`,
+      email: `a${i}.${EXACT.email}`,
+    }));
+    h = await makeHarness({ kbPeople: [...crowd, EXACT], accounts: [EXACT.email] });
+
+    const body = (await (
+      await fetch(
+        `${h.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/suggest?q=${encodeURIComponent(EXACT.email)}`,
+      )
+    ).json()) as { people: { email: string; hasAccount: boolean }[]; accountsKnown?: boolean };
+
+    expect(body.people).toHaveLength(15);
+    expect(body.people[0]).toEqual(
+      expect.objectContaining({ email: EXACT.email, hasAccount: true }),
+    );
+    // And the answer says it SPEAKS about accounts, which is the evidence the
+    // dialog needs before it labels a free-typed chip at all.
+    expect(body.accountsKnown).toBe(true);
+  });
+
+  it('suggest marks each person the same way, and withholds nobody', async () => {
+    h = await makeHarness({
+      kbPeople: [KNOWN, UNKNOWN],
+      accounts: [KNOWN.email],
+    });
+
+    const suggest = async (q: string) =>
+      (await (
+        await fetch(
+          `${h!.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/suggest?q=${encodeURIComponent(q)}`,
+        )
+      ).json()) as {
+        people: { email: string; hasAccount: boolean }[];
+        peopleWithheld: boolean;
+        accountsKnown: boolean;
+      };
+
+    // One character — people are withheld below two (the harvesting guard),
+    // and that is unchanged by this ticket.
+    const short = await suggest('a');
+    expect(short.people).toEqual([]);
+    // And a withheld answer must not pass itself off as a complete account
+    // answer: it names nobody BY DESIGN, so reading its empty list as "nobody
+    // has an account" would label every address at once. The two flags agree.
+    expect(short.peopleWithheld).toBe(true);
+    expect(short.accountsKnown).toBe(false);
+
+    // A real query rules on accounts, and says so.
+    expect((await suggest('alice')).accountsKnown).toBe(true);
+    expect((await suggest('alice')).peopleWithheld).toBe(false);
+    expect((await suggest('alice')).people).toEqual([
+      expect.objectContaining({ email: KNOWN.email, hasAccount: true }),
+    ]);
+    // Named in the knowledge base, never signed in: offered exactly as before,
+    // now carrying the fact the chip labels itself with.
+    expect((await suggest('colleague')).people).toEqual([
+      expect.objectContaining({ email: UNKNOWN.email, hasAccount: false }),
+    ]);
+  });
+});

package/src/modules/access/__tests__/change-read-gate.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+import { ChangeReadGate, isNewTopLevelFolderPath } from '../change-read-gate.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
+import { SYNCED_GROUPS_YAML } from '../../access-model/group-files.js';
+
+const KB = 'knowledge-base';
+const WS = 'ws-gate';
+const ALICE = 'alice@example.com';
+const ADMIN = 'razvan@bevel.software';
+
+const ROLES_YAML = `roles:
+  Admin:
+    - ${ADMIN}
+`;
+
+async function write(repo: string, rel: string, contents: string): Promise<void> {
+  const abs = path.join(repo, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents);
+}
+
+function stubWorkspaceService(workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== WS) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+/**
+ * "You can only change what you can see": the verdict every lock acquire
+ * asks for, against a real access tree on disk. Read is default-deny and the
+ * test tree's root grants nobody, so every path is unreadable until a case
+ * says otherwise.
+ */
+describe('ChangeReadGate', () => {
+  let root: string;
+  let repo: string;
+  let gate: ChangeReadGate;
+  let access: AccessControlService;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-change-gate-'));
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB);
+    for (const d of ['KnowledgeBase', 'Skills', 'Plugins', 'Data']) {
+      await fs.mkdir(path.join(repo, d), { recursive: true });
+    }
+    await write(repo, 'roles.yaml', ROLES_YAML);
+    const ws = stubWorkspaceService(workspaceDir);
+    access = new AccessControlService(ws, KB, new NodeFs());
+    gate = new ChangeReadGate(ws, access, KB, new NodeFs());
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  const judge = (email: string, wsPath: string, kind: 'file' | 'dir' = 'file') =>
+    gate.judge(WS, email, wsPath, kind);
+
+  it('a path outside the knowledge-base repository has no read rules and passes', async () => {
+    expect(await judge(ALICE, 'reserved-config.json')).toEqual({ allowed: true, via: 'outside-kb' });
+  });
+
+  it('a readable folder lets a new file in, a readable file lets a change through', async () => {
+    await write(repo, 'KnowledgeBase/Sales/access.md', '---\nread:\n  - everyone\n---\n');
+    await write(repo, 'KnowledgeBase/Sales/deal.md', 'x');
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/Sales/new.md`)).toEqual({ allowed: true, via: 'readable' });
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/Sales/deal.md`)).toEqual({ allowed: true, via: 'readable' });
+  });
+
+  it('a new file in a folder the caller cannot read is refused, naming the folder', async () => {
+    await fs.mkdir(path.join(repo, 'KnowledgeBase/Sealed'), { recursive: true });
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/Sealed/brief.pdf`)).toEqual({
+      allowed: false,
+      unreadable: 'KnowledgeBase/Sealed',
+    });
+  });
+
+  it('a change to a file the caller cannot read is refused, naming the file', async () => {
+    await write(repo, 'KnowledgeBase/Sealed/deal.md', 'x');
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/Sealed/deal.md`)).toEqual({
+      allowed: false,
+      unreadable: 'KnowledgeBase/Sealed/deal.md',
+    });
+  });
+
+  it('a write grant does not stand in for read: a nearer deny read still refuses', async () => {
+    await write(repo, 'KnowledgeBase/access.md', `---\nwrite:\n  - Alice <${ALICE}>\n---\n`);
+    await write(repo, 'KnowledgeBase/Board/access.md', `---\nread:\n  - deny Alice <${ALICE}>\n---\n`);
+    // Write folds into read at the root scope…
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/memo.md`)).toEqual({ allowed: true, via: 'readable' });
+    // …but the nearer folder takes the read away, and the write with it.
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/Board/memo.md`)).toEqual({
+      allowed: false,
+      unreadable: 'KnowledgeBase/Board',
+    });
+  });
+
+  it('a loose file directly at an unreadable root is refused, naming the root', async () => {
+    expect(await judge(ALICE, `${KB}/KnowledgeBase/notes.md`)).toEqual({
+      allowed: false,
+      unreadable: 'KnowledgeBase',
+    });
+    expect(await judge(ALICE, `${KB}/AGENTS.md`)).toEqual({ allowed: false, unreadable: '' });
+  });
+
+  describe('the exception: a new folder directly under one of the three roots', () => {
+    it('lets a file inside a folder that does not exist yet through, at each of the three roots', async () => {
+      for (const p of ['KnowledgeBase/Projects/plan.md', 'Skills/my-skill/SKILL.md', 'Plugins/team/access.md']) {
+        expect(await judge(ALICE, `${KB}/${p}`), p).toEqual({ allowed: true, via: 'new-top-level-folder' });
+      }
+    });
+
+    it('lets the folder itself through when asked about as a folder', async () => {
+      expect(await judge(ALICE, `${KB}/KnowledgeBase/Projects`, 'dir')).toEqual({
+        allowed: true,
+        via: 'new-top-level-folder',
+      });
+    });
+
+    it('covers the whole new subtree, however deep', async () => {
+      expect(await judge(ALICE, `${KB}/KnowledgeBase/Projects/2026/q4/plan.md`)).toEqual({
+        allowed: true,
+        via: 'new-top-level-folder',
+      });
+    });
+
+    it('does not cover a folder that already exists', async () => {
+      await fs.mkdir(path.join(repo, 'KnowledgeBase/Projects'), { recursive: true });
+      expect(await judge(ALICE, `${KB}/KnowledgeBase/Projects/plan.md`)).toEqual({
+        allowed: false,
+        unreadable: 'KnowledgeBase/Projects',
+      });
+    });
+
+    it('does not cover a new folder under any other root', async () => {
+      expect(await judge(ALICE, `${KB}/Data/Engineering/plan.md`)).toEqual({
+        allowed: false,
+        unreadable: 'Data/Engineering',
+      });
+      expect(await judge(ALICE, `${KB}/Data/Engineering`, 'dir')).toEqual({
+        allowed: false,
+        unreadable: 'Data',
+      });
+    });
+
+    it('does not cover a loose file at the root, asked about as a file', async () => {
+      // `KnowledgeBase/Projects` as a FILE is a loose file at the root, not a folder.
+      expect(await judge(ALICE, `${KB}/KnowledgeBase/Projects`, 'file')).toEqual({
+        allowed: false,
+        unreadable: 'KnowledgeBase',
+      });
+    });
+  });
+
+  describe('the rescues the write rule already has', () => {
+    it('an admin may change a file directly in the repository root whatever the root grants', async () => {
+      expect(await judge(ADMIN, `${KB}/groups.yaml`)).toEqual({ allowed: true, via: 'admin-rescue' });
+      expect(await judge(ADMIN, `${KB}/access.md`)).toEqual({ allowed: true, via: 'admin-rescue' });
+      expect(await judge(ADMIN, `${KB}/roles.yaml`)).toEqual({ allowed: true, via: 'admin-rescue' });
+    });
+
+    it('the rescue stops at the root: an admin excluded from a subfolder cannot change its rules', async () => {
+      await write(repo, 'KnowledgeBase/Board/access.md', '---\nread:\n  - deny everyone\n---\n');
+      expect(await judge(ADMIN, `${KB}/KnowledgeBase/Board/access.md`)).toEqual({
+        allowed: false,
+        unreadable: 'KnowledgeBase/Board/access.md',
+      });
+    });
+
+    it('a non-admin gets no rescue on root files', async () => {
+      expect(await judge(ALICE, `${KB}/groups.yaml`)).toEqual({ allowed: false, unreadable: '' });
+    });
+
+    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.
+      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' });
+    });
+
+    it('a roles.yaml that is there but unusable is not an open door', async () => {
+      await fs.mkdir(path.join(repo, 'KnowledgeBase/Sealed'), { recursive: true });
+      await write(repo, 'roles.yaml', 'roles: [not: valid\n');
+      await expect(judge(ALICE, `${KB}/KnowledgeBase/Sealed/x.md`)).rejects.toThrow(/Access-control config is invalid/);
+    });
+
+    it('a link where the new folder would be is something there, not a new folder', async () => {
+      await fs.symlink(path.join(root, 'elsewhere'), path.join(repo, 'KnowledgeBase/Linked'));
+      expect(await judge(ALICE, `${KB}/KnowledgeBase/Linked/a.md`)).toEqual({
+        allowed: false,
+        unreadable: 'KnowledgeBase/Linked',
+      });
+    });
+
+    it('the directory-sync file is machine-owned: the write rule names its writer, not this gate', async () => {
+      expect(await judge(ALICE, `${KB}/${SYNCED_GROUPS_YAML}`)).toEqual({ allowed: true, via: 'machine-owned' });
+    });
+
+    it('a tree with no usable access config decides nothing, like the write gate', async () => {
+      await fs.mkdir(path.join(repo, 'KnowledgeBase/Sealed'), { recursive: true });
+      await fs.rm(path.join(repo, 'roles.yaml'));
+      expect(await judge(ALICE, `${KB}/KnowledgeBase/Sealed/x.md`)).toEqual({ allowed: true, via: 'no-rules' });
+    });
+  });
+
+  describe('assertMayChange', () => {
+    it('throws an AccessDeniedError that names the unreadable place and carries no eligible lists', async () => {
+      await fs.mkdir(path.join(repo, 'KnowledgeBase/Sealed'), { recursive: true });
+      const err = await gate
+        .assertMayChange(WS, ALICE, `${KB}/KnowledgeBase/Sealed/brief.pdf`, 'file')
+        .then(() => null, (e: unknown) => e);
+      expect(err).toBeInstanceOf(AccessDeniedError);
+      const denied = err as AccessDeniedError;
+      expect(denied.access).toEqual({
+        path: `${KB}/KnowledgeBase/Sealed/brief.pdf`,
+        eligibleRoles: [],
+        eligibleUsers: [],
+        unreadable: 'KnowledgeBase/Sealed',
+      });
+      expect(denied.message).toBe(
+        `You don't have permission to write to "${KB}/KnowledgeBase/Sealed/brief.pdf". You don't have read access to "KnowledgeBase/Sealed"; only what you can read can be created, changed or removed.`,
+      );
+      expect(denied.status).toBe(403);
+    });
+
+    it('names the top level when the root itself is the unreadable place', async () => {
+      const err = await gate
+        .assertMayChange(WS, ALICE, `${KB}/notes.md`, 'file')
+        .then(() => null, (e: unknown) => e);
+      expect((err as AccessDeniedError).message).toContain("You don't have read access to the top level;");
+    });
+
+    it('resolves quietly when the change is allowed', async () => {
+      await expect(gate.assertMayChange(WS, ALICE, `${KB}/Skills/new-skill/SKILL.md`, 'file')).resolves.toBeUndefined();
+    });
+  });
+});
+
+describe('isNewTopLevelFolderPath', () => {
+  const onDisk = new Set(['KnowledgeBase/Existing', 'Skills/known']);
+  const exists = async (p: string) => onDisk.has(p);
+
+  it('is true for a path inside a folder directly under a creatable root that is not on disk', async () => {
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/New/a.md', 'file', exists)).toBe(true);
+    expect(await isNewTopLevelFolderPath('Skills/fresh/SKILL.md', 'file', exists)).toBe(true);
+    expect(await isNewTopLevelFolderPath('Plugins/team/deep/er/x', 'file', exists)).toBe(true);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/New', 'dir', exists)).toBe(true);
+  });
+
+  it('is false when the top-level folder exists, for a loose file at the root, and outside the three roots', async () => {
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/Existing/a.md', 'file', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('Skills/known', 'dir', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/loose.md', 'file', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase', 'dir', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('Data/New/a.md', 'file', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('roles.yaml', 'file', exists)).toBe(false);
+  });
+});