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

package/src/modules/access/__tests__/access-control.deny-dependents.test.ts

@@ -0,0 +1,215 @@
+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 {
+  KNOWN_VERBS,
+  VERB_REQUIRES,
+  requiredVerbsFor,
+  sourceVerbsFor,
+} from '../../access-model/access-grammar.js';
+
+/**
+ * A DENIAL TAKES DOWN EVERYTHING THAT PRESUPPOSES THE DENIED VERB.
+ *
+ * On core-staging, `KnowledgeBase/Finance/access.md` denied the Admin role
+ * read, write and download — and the Manage access sheet still showed Admin as
+ * Owner, because the root grants `owner: Admin` and resolving `owner` read
+ * only `owner:` lines. Owner presupposes write, which presupposes read; a
+ * denial of either at a closer scope has to strip owner there, or the sheet
+ * says "Owner" about someone who may not open the folder, and `canOwner`
+ * still lets them manage its access.
+ *
+ * The rule is not written into the resolver. The grammar declares what each
+ * verb presupposes (`VERB_REQUIRES`) and the resolver reads the two lists
+ * derived from it: grants confer downwards, denials strip upwards. These tests
+ * pin the derivation, the enforcement, and the one thing that did NOT change:
+ * a superset denial (`deny write`) still says nothing about `read`.
+ */
+
+const KB_DIR = 'knowledge-base';
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+    ensureRemotesFetched: async () => undefined,
+  } as unknown as WorkspaceService;
+}
+
+const ROLES_YAML = `roles:
+  Admin:
+    - admin@x.io
+  Finance:
+    - fin@x.io
+`;
+
+describe('the grammar derives both folds from one dependency graph', () => {
+  it('declares what each verb presupposes, and only that', () => {
+    expect(VERB_REQUIRES).toEqual({
+      read: [],
+      write: ['read'],
+      download: ['read'],
+      owner: ['write', 'download'],
+    });
+  });
+
+  it('grants confer downwards: the verbs whose grant confers each verb', () => {
+    expect(sourceVerbsFor('read')).toEqual(['read', 'write', 'download', 'owner']);
+    expect(sourceVerbsFor('write')).toEqual(['write', 'owner']);
+    expect(sourceVerbsFor('download')).toEqual(['download', 'owner']);
+    expect(sourceVerbsFor('owner')).toEqual(['owner']);
+  });
+
+  it('denials strip upwards: the verbs whose denial strips each verb', () => {
+    expect(requiredVerbsFor('read')).toEqual(['read']);
+    expect(requiredVerbsFor('write')).toEqual(['write', 'read']);
+    expect(requiredVerbsFor('download')).toEqual(['download', 'read']);
+    expect(requiredVerbsFor('owner')).toEqual(['owner', 'read', 'write', 'download']);
+  });
+
+  it('the two lists are each other\'s transpose, for every verb', () => {
+    // A grant of v confers w exactly when a denial of w strips v: both are
+    // "v presupposes w", read from the one table, so the lists cannot disagree.
+    for (const v of KNOWN_VERBS) {
+      for (const w of KNOWN_VERBS) {
+        expect(sourceVerbsFor(w).includes(v)).toBe(requiredVerbsFor(v).includes(w));
+      }
+    }
+  });
+});
+
+describe('a closer denial strips the verbs that presuppose it', () => {
+  let root: string;
+  const workspaceId = 'ws-deny-dependents';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-deny-dependents-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeService(files: Record<string, string>) {
+    const workspaceDir = path.join(root, workspaceId);
+    const repo = path.join(workspaceDir, KB_DIR);
+    for (const [rel, contents] of Object.entries(files)) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
+  }
+
+  const BASE = { 'roles.yaml': ROLES_YAML };
+  const FINANCE = 'KnowledgeBase/Finance';
+  const DOC = `${FINANCE}/Budget.md`;
+
+  it('the Finance case: read, write and download denied here leave no owner standing', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Admin\nread:\n  - everyone\n',
+      [`${FINANCE}/access.md`]:
+        '---\n---\nread:\n  - Finance\n  - deny role/Admin\nwrite:\n  - Finance\n  - deny Admin\ndownload:\n  - deny Admin\n',
+    });
+    expect(await svc.canOwner(workspaceId, 'admin@x.io', DOC)).toBe(false);
+    expect(await svc.canWrite(workspaceId, 'admin@x.io', DOC)).toBe(false);
+    expect(await svc.canDownload(workspaceId, 'admin@x.io', DOC)).toBe(false);
+    expect(await svc.canRead(workspaceId, 'admin@x.io', DOC)).toBe(false);
+    // And the sheet's owner list — what read "Owner" on staging — agrees.
+    const owners = await svc.eligibleOwners(workspaceId, FINANCE);
+    expect(owners.roles).not.toContain('Admin');
+    // Above Finance the root grant is untouched.
+    expect(await svc.canOwner(workspaceId, 'admin@x.io', 'KnowledgeBase/Sales/Deal.md')).toBe(true);
+    expect((await svc.eligibleOwners(workspaceId, 'KnowledgeBase/Sales')).roles).toContain('Admin');
+  });
+
+  it('`deny write` alone strips owner, and leaves the read and download the owner grant conferred', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Ana <ana@x.io>\n',
+      [`${FINANCE}/access.md`]: '---\n---\nwrite:\n  - deny Ana <ana@x.io>\n',
+    });
+    expect(await svc.canOwner(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    expect(await svc.canWrite(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    // A superset denial still says nothing about the verbs below it.
+    expect(await svc.canRead(workspaceId, 'ana@x.io', DOC)).toBe(true);
+    expect(await svc.canDownload(workspaceId, 'ana@x.io', DOC)).toBe(true);
+  });
+
+  it('`deny read` alone strips write, download and owner: nobody edits or saves what they may not open', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Ana <ana@x.io>\n',
+      [`${FINANCE}/access.md`]: '---\n---\nread:\n  - deny Ana <ana@x.io>\n',
+    });
+    expect(await svc.canRead(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    expect(await svc.canWrite(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    expect(await svc.canDownload(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    expect(await svc.canOwner(workspaceId, 'ana@x.io', DOC)).toBe(false);
+  });
+
+  it('`deny download` alone strips owner and nothing else', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Ana <ana@x.io>\n',
+      [`${FINANCE}/access.md`]: '---\n---\ndownload:\n  - deny Ana <ana@x.io>\n',
+    });
+    expect(await svc.canOwner(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    expect(await svc.canDownload(workspaceId, 'ana@x.io', DOC)).toBe(false);
+    expect(await svc.canWrite(workspaceId, 'ana@x.io', DOC)).toBe(true);
+    expect(await svc.canRead(workspaceId, 'ana@x.io', DOC)).toBe(true);
+  });
+
+  it('a grant in the SAME scope still beats a prerequisite denial beside it', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Ana <ana@x.io>\nwrite:\n  - deny Ana <ana@x.io>\n',
+    });
+    // Within one file a grant wins, as it always has (`owner:` beats `deny write`).
+    expect(await svc.canOwner(workspaceId, 'ana@x.io', DOC)).toBe(true);
+    expect(await svc.canWrite(workspaceId, 'ana@x.io', DOC)).toBe(true);
+  });
+
+  it('the implied denial is an effective verdict, not a line: sources report the prerequisite, and the owner grant is cut off', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Ana <ana@x.io>\n',
+      [`${FINANCE}/access.md`]: '---\n---\nwrite:\n  - deny Ana <ana@x.io>\n',
+    });
+    const ana = { kind: 'user' as const, email: 'ana@x.io' };
+    // What can be lifted here is the `deny write` line — the sheet must not
+    // offer a `deny owner` that no file holds.
+    const denials = await svc.denialSources(workspaceId, 'folder', FINANCE, ana);
+    expect(denials.write).toEqual([{ kind: 'direct' }]);
+    expect(denials.owner).toBeUndefined();
+    // And the root's owner grant no longer reaches Finance: it is shadowed by
+    // the closer denial, so it is not a source of anything held here.
+    const grants = await svc.grantSources(workspaceId, 'folder', FINANCE, ana);
+    expect(grants.owner).toBeUndefined();
+    expect(grants.write).toBeUndefined();
+    expect(grants.read).toEqual([{ kind: 'ancestor', path: 'access.md' }]);
+  });
+
+  it('a role denied read at a closer scope takes the Admin write floor down with it there', async () => {
+    const svc = await makeService({
+      ...BASE,
+      'access.md': '---\n---\nowner:\n  - Admin\n',
+      [`${FINANCE}/access.md`]: '---\n---\nread:\n  - Finance\n  - deny role/Admin\n',
+    });
+    // The floor holds at the ROOT scope; a nearer scope that denies Admin
+    // decides first, as it already did for a `deny write` — and now for the
+    // `deny read` that write presupposes.
+    expect(await svc.canWrite(workspaceId, 'admin@x.io', DOC)).toBe(false);
+    expect(await svc.canWrite(workspaceId, 'admin@x.io', 'KnowledgeBase/Sales/Deal.md')).toBe(true);
+    // The rescue on access files themselves is untouched: an admin can still
+    // repair the very file that excludes them.
+    expect(await svc.canWrite(workspaceId, 'admin@x.io', `${FINANCE}/access.md`)).toBe(true);
+  });
+});

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

@@ -0,0 +1,268 @@
+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 { sourceVerbsFor } from '../../access-model/access-grammar.js';
+
+/**
+ * `download` folds into `read`, the way `write` does.
+ *
+ * A download-only grant used to be a DEAD combination: the raw-file route
+ * read-gates before it download-gates, so its holder could neither open the
+ * file nor save it — and the share dialog let anyone create that pairing.
+ * These tests pin the fold across every shape a grant can take (direct user,
+ * role, group, plugin token, inherited from an ancestor, a node's own
+ * frontmatter) and pin the half that did NOT change: the implication is
+ * grant-only, so a `deny download` says nothing about read, and `download`
+ * still confers no `write`.
+ */
+
+const KB_DIR = 'knowledge-base';
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+    ensureRemotesFetched: async () => undefined,
+  } as unknown as WorkspaceService;
+}
+
+const ROLES_YAML = `roles:
+  Admin:
+    - admin@x.io
+  Product Manager:
+    - pm@x.io
+`;
+
+const GROUPS_YAML = `groups:
+  Sales Team:
+    - sam@x.io
+`;
+
+describe('download implies read', () => {
+  let root: string;
+  const workspaceId = 'ws-download-read';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-download-read-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeService(files: Record<string, string>) {
+    const workspaceDir = path.join(root, workspaceId);
+    const repo = path.join(workspaceDir, KB_DIR);
+    for (const [rel, contents] of Object.entries(files)) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
+  }
+
+  const BASE = {
+    'roles.yaml': ROLES_YAML,
+    'groups.yaml': GROUPS_YAML,
+  };
+
+  describe('the grammar table', () => {
+    it('folds download into read, alongside write and owner', () => {
+      expect(sourceVerbsFor('read')).toEqual(['read', 'write', 'download', 'owner']);
+    });
+
+    it('leaves the other verbs where they were — download is not conferred by write or read', () => {
+      expect(sourceVerbsFor('download')).toEqual(['download', 'owner']);
+      expect(sourceVerbsFor('write')).toEqual(['write', 'owner']);
+      expect(sourceVerbsFor('owner')).toEqual(['owner']);
+    });
+  });
+
+  describe('a download-only grant confers read', () => {
+    it('for a DIRECT user grant', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(true);
+      expect(await svc.canDownload(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(true);
+      // Nobody else: the fold adds no grant that was not written.
+      expect(await svc.canRead(workspaceId, 'mallory@x.io', 'Knowledge/Deal.md')).toBe(false);
+    });
+
+    it('for a ROLE grant', async () => {
+      const svc = await makeService({
+        ...BASE,
+        '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);
+    });
+
+    it('for a GROUP grant', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Sales Team\n',
+      });
+      expect(await svc.canRead(workspaceId, 'sam@x.io', 'Knowledge/Deal.md')).toBe(true);
+    });
+
+    it('for a PLUGIN-token grant', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/GTM/plugin.json': '{"name":"gtm"}',
+        'Plugins/GTM/access.md': '---\nread:\n  - everyone\n---\nread:\n  - Sales Team\n',
+        'Knowledge/access.md': '---\n---\ndownload:\n  - plugin/GTM/read\n',
+      });
+      expect(await svc.canRead(workspaceId, 'sam@x.io', 'Knowledge/Deal.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'pm@x.io', 'Knowledge/Deal.md')).toBe(false);
+    });
+
+    it('for an INHERITED grant, several folders up', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+        'Knowledge/Sales/access.md': '---\n---\nwrite:\n  - Admin\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Sales/Deal.md')).toBe(true);
+    });
+
+    it("for a node's OWN frontmatter, on that node alone", async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\nwrite:\n  - Admin\n',
+        'Knowledge/Deal.md': '---\ndownload:\n  - Ana <ana@x.io>\n---\n# Deal\n',
+        'Knowledge/Other.md': '# Other\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Other.md')).toBe(false);
+    });
+
+    it('through the BATCHED read, the file tree resolves every node with', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Knowledge/access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+      });
+      const verdicts = await svc.canReadBatch(workspaceId, 'ana@x.io', [
+        'Knowledge/Deal.md',
+        'Elsewhere/Other.md',
+      ]);
+      expect(verdicts.get('Knowledge/Deal.md')).toBe(true);
+      expect(verdicts.get('Elsewhere/Other.md')).toBe(false);
+    });
+
+    it('for a GROUP lens and the EVERYONE lens', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Knowledge/access.md': '---\n---\ndownload:\n  - Sales Team\n',
+        'Public/access.md': '---\n---\ndownload:\n  - everyone\n',
+      });
+      const asGroup = await svc.canReadAsGroupBatch(workspaceId, 'Sales Team', ['Knowledge/Deal.md']);
+      expect(asGroup?.get('Knowledge/Deal.md')).toBe(true);
+      const asEveryone = await svc.canReadAsEveryoneBatch(workspaceId, [
+        'Public/Brochure.md',
+        'Knowledge/Deal.md',
+      ]);
+      expect(asEveryone.get('Public/Brochure.md')).toBe(true);
+      expect(asEveryone.get('Knowledge/Deal.md')).toBe(false);
+    });
+  });
+
+  describe('the fold is GRANT-ONLY', () => {
+    it('a `deny download` says nothing about read — a separate read grant survives it', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\nread:\n  - Ana <ana@x.io>\n',
+        'Knowledge/access.md': '---\n---\ndownload:\n  - deny Ana <ana@x.io>\n',
+      });
+      // The scenario from the spec: read inherited from the parent, download
+      // denied here. She can still open the file; she cannot save it.
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(true);
+      expect(await svc.canDownload(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(false);
+    });
+
+    it('a `deny download` on its own grants no read', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - deny Ana <ana@x.io>\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(false);
+    });
+
+    it('a closer `deny read` beats a farther download grant, and takes download with it', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+        'Knowledge/Secret/access.md': '---\n---\nread:\n  - deny Ana <ana@x.io>\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Secret/Deal.md')).toBe(false);
+      // Download presupposes read (`VERB_REQUIRES`): she may not save a copy
+      // of what she may not open. The grant is not dead upstream — it still
+      // holds where the read denial does not reach.
+      expect(await svc.canDownload(workspaceId, 'ana@x.io', 'Knowledge/Secret/Deal.md')).toBe(false);
+      expect(await svc.canDownload(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(true);
+    });
+
+    it('a same-scope download grant overrides a `deny read` beside it, as a write grant does', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md':
+          '---\n---\nread:\n  - deny Ana <ana@x.io>\ndownload:\n  - Ana <ana@x.io>\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(true);
+    });
+
+    it('confers no write and no ownership', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+      });
+      expect(await svc.canWrite(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(false);
+      expect(await svc.canOwner(workspaceId, 'ana@x.io', 'Knowledge/Deal.md')).toBe(false);
+    });
+  });
+
+  describe('the share surface sees the fold', () => {
+    it('eligibleReaders names the downloaders', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Product Manager\n  - Ana <ana@x.io>\n',
+      });
+      const readers = await svc.eligibleReaders(workspaceId, 'Knowledge/Deal.md');
+      expect(readers.roles).toContain('Product Manager');
+      // Names are not carried on eligible-holder rows (they never have been).
+      expect(readers.users).toEqual([{ name: '', email: 'ana@x.io' }]);
+    });
+
+    it('`download: everyone` makes a node public', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - everyone\n',
+      });
+      const readers = await svc.eligibleReaders(workspaceId, 'Knowledge/Deal.md');
+      expect(readers.restricted).toBe(false);
+    });
+
+    it('grantSources reports the download grant as the source of the implied read', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'access.md': '---\n---\ndownload:\n  - Ana <ana@x.io>\n',
+      });
+      const sources = await svc.grantSources(
+        workspaceId,
+        'file',
+        'Knowledge/Deal.md',
+        { kind: 'user', email: 'ana@x.io' },
+      );
+      expect(sources.download).toEqual([{ kind: 'ancestor', path: 'access.md' }]);
+      expect(sources.read).toEqual([{ kind: 'ancestor', path: 'access.md' }]);
+      expect(sources.write).toBeUndefined();
+    });
+  });
+});

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

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+
+/**
+ * `canReadAsEveryoneBatch`: what the org-wide `everyone` principal reads,
+ * asked of nobody in particular. Driven over a real on-disk tree through the
+ * public resolver, like the group-read tests, because the answer has to
+ * agree with what a signed-in person who is in no group and holds no role
+ * gets — and with nothing anyone holds for a reason of their own.
+ */
+
+const KB_DIR = 'knowledge-base';
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+    ensureRemotesFetched: async () => undefined,
+  } as unknown as WorkspaceService;
+}
+
+const ROLES_YAML = `roles:
+  Admin:
+    - admin@x.io
+  Engineer:
+    - eng@x.io
+`;
+
+const GROUPS_YAML = `groups:
+  Sales Team:
+    - sam@x.io
+`;
+
+const rules = (body: string) => `---\n${body}---\n`;
+
+describe('canReadAsEveryoneBatch', () => {
+  let root: string;
+  const workspaceId = 'ws-everyone-read-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-everyone-read-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeService(files: Record<string, string>) {
+    const workspaceDir = path.join(root, workspaceId);
+    const repo = path.join(workspaceDir, KB_DIR);
+    for (const [rel, contents] of Object.entries(files)) {
+      const abs = path.join(repo, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, contents);
+    }
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
+  }
+
+  const TREE = {
+    'roles.yaml': ROLES_YAML,
+    'groups.yaml': GROUPS_YAML,
+    'access.md': rules('write:\n  - Admin\n'),
+    // Org-wide: the plugin's own rules admit everyone.
+    'Plugins/Handbook/plugin.json': '{"name":"handbook"}',
+    'Plugins/Handbook/access.md': rules('read:\n  - everyone\n') + 'read:\n  - everyone\n',
+    // A team's: discoverable by everyone (the file), readable by the group (the folder).
+    'Plugins/GTM/plugin.json': '{"name":"gtm"}',
+    'Plugins/GTM/access.md': rules('read:\n  - everyone\n') + 'read:\n  - Sales Team\n',
+    // A shared skill the public plugin links — reachable through its public principal.
+    'Skills/Shared/access.md': rules('read:\n  - plugin/handbook/read\n'),
+    'Skills/Shared/welcome/SKILL.md': '# Welcome\n',
+    // A shared skill only the team's plugin links.
+    'Skills/Sales/access.md': rules('read:\n  - plugin/gtm/read\n'),
+    'Skills/Sales/deal/SKILL.md': '# Deal\n',
+    // Public by the built-in principal, with a closer carve-out beneath.
+    'Skills/Open/access.md': rules('read:\n  - everyone\n'),
+    'Skills/Open/hello/SKILL.md': '# Hello\n',
+    'Skills/Open/secret/access.md': rules('read:\n  - deny everyone\n  - Engineer\n'),
+    'Skills/Open/secret/SKILL.md': '# Secret\n',
+    // Granted to a role, and to a person: theirs, not the organisation's.
+    'Skills/Eng/access.md': rules('read:\n  - Engineer\n'),
+    'Skills/Eng/deploy/SKILL.md': '# Deploy\n',
+    'Skills/Mine/access.md': rules('read:\n  - Sam <sam@x.io>\n'),
+    'Skills/Mine/notes/SKILL.md': '# Notes\n',
+  };
+
+  const PATHS = [
+    'Plugins/Handbook',
+    'Plugins/Handbook/access.md',
+    'Plugins/GTM',
+    'Plugins/GTM/access.md',
+    'Skills/Shared/welcome/SKILL.md',
+    'Skills/Sales/deal/SKILL.md',
+    'Skills/Open/hello/SKILL.md',
+    'Skills/Open/secret/SKILL.md',
+    'Skills/Eng/deploy/SKILL.md',
+    'Skills/Mine/notes/SKILL.md',
+  ];
+
+  it('answers for the organisation: the built-in grant, a public plugin and what it links, and no one\'s own', async () => {
+    const svc = await makeService(TREE);
+    const verdict = await svc.canReadAsEveryoneBatch(workspaceId, PATHS);
+    expect(Object.fromEntries(verdict)).toEqual({
+      'Plugins/Handbook': true, // admits everyone
+      'Plugins/Handbook/access.md': true,
+      'Plugins/GTM': false, // a team's
+      'Plugins/GTM/access.md': true, // …but discoverable by all
+      'Skills/Shared/welcome/SKILL.md': true, // through the public plugin's principal
+      'Skills/Sales/deal/SKILL.md': false, // through a team plugin's only
+      'Skills/Open/hello/SKILL.md': true, // read: everyone
+      'Skills/Open/secret/SKILL.md': false, // a closer deny everyone wins
+      'Skills/Eng/deploy/SKILL.md': false, // a role's
+      'Skills/Mine/notes/SKILL.md': false, // a person's
+    });
+  });
+
+  it('agrees with what a signed-in person in no group and no role holds, and with nothing more', async () => {
+    const svc = await makeService(TREE);
+    const everyone = await svc.canReadAsEveryoneBatch(workspaceId, PATHS);
+    expect(everyone).toEqual(await svc.canReadBatch(workspaceId, 'nobody@x.io', PATHS));
+    // Members and admins hold more, for reasons of their own: none of it is the organisation's.
+    const sam = await svc.canReadBatch(workspaceId, 'sam@x.io', PATHS);
+    expect(sam.get('Plugins/GTM')).toBe(true);
+    expect(sam.get('Skills/Mine/notes/SKILL.md')).toBe(true);
+    expect(everyone.get('Plugins/GTM')).toBe(false);
+    expect(everyone.get('Skills/Mine/notes/SKILL.md')).toBe(false);
+  });
+
+  it('has no admin rescue: what only Admin may read is not org-wide', async () => {
+    const svc = await makeService({
+      ...TREE,
+      'Skills/Board/access.md': rules('read:\n  - Admin\n'),
+      'Skills/Board/minutes/SKILL.md': '# Minutes\n',
+    });
+    const verdict = await svc.canReadAsEveryoneBatch(workspaceId, ['Skills/Board/minutes/SKILL.md']);
+    expect(verdict.get('Skills/Board/minutes/SKILL.md')).toBe(false);
+  });
+});