@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/access/__tests__/access.routes.revoke.test.ts

@@ -11,6 +11,7 @@ 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';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * HTTP-level contract tests for the revoke route's CLASSIFICATION + MODE logic —
@@ -56,6 +57,8 @@ async function makeHarness(opts: {
   effectiveEmails?: Record<string, boolean>;
   /** Override the (otherwise-empty) eligibleWriters list so a principal shows as a row in resolvedView. */
   eligibleWriters?: { roles: string[]; users: { name: string; email: string }[] };
+  /** kbPrincipals' roles — empty (the default) reads as a model that failed to load. */
+  roles?: string[];
 }): Promise<Harness> {
   const files = new Map<string, string>(Object.entries(opts.files ?? {}));
 
@@ -79,8 +82,8 @@ async function makeHarness(opts: {
     invalidate: vi.fn(),
     // The mutation service consults the merged principal index to decide
     // exact-vs-name token matching on revoke (group shadowing). No groups in
-    // these fixtures → unshadowed (name-level) matching, the legacy behavior.
-    kbPrincipals: vi.fn(async () => ({ roles: [], groups: [], people: [] })),
+    // these fixtures; no roles (the default) reads as a failed load → exact.
+    kbPrincipals: vi.fn(async () => ({ roles: opts.roles ?? [], groups: [], people: [] })),
     // resolvedView() fans out to these after a successful mutation; harmless stubs.
     // canRead/canDownload/canOwner are ALSO consumed by denyHere's assert.
     canRead: vi.fn(async (_w: string, email: string) => effEmail(email, true)),
@@ -134,7 +137,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
@@ -285,16 +288,16 @@ describe('POST /access/revoke — route classification + modes', () => {
       expect(h.stubs.files.get(`${KB}/Sales/access.md`)).toContain('Admin'); // untouched
     });
 
-    it('a GROUP revoke matches its exact bare token only — a VANISHED group never strips role/<Name>', async () => {
-      // The file grants BOTH spellings of one name: the bare token (the
-      // group's grant) and role/Product (the role's). The group has since
-      // vanished from the active source (kbPrincipals reports no groups), so
-      // the mutation layer's shadow probe reads "unshadowed" — name-level
-      // matching would strip BOTH spellings, silently revoking the ROLE. The
-      // route pins exact-token matching for group principals instead.
+    it('a GROUP revoke strips group/<Name> — a VANISHED group never strips the role spellings', async () => {
+      // The file grants every spelling of one name: the bare token and
+      // role/Product (the role's) and group/Product (the group's). The group
+      // has since vanished from the active source and the principal index
+      // says nothing about roles either (kbPrincipals reports none), so
+      // nothing vouches that the bare name is the group's: only the explicit
+      // group token goes.
       h = await makeHarness({
         files: {
-          [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n---\n',
+          [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n  - group/Product\n---\n',
         },
         grantSources: () => ({}),
       });
@@ -305,9 +308,10 @@ describe('POST /access/revoke — route classification + modes', () => {
       });
       expect(res.status).toBe(200);
       const text = h.stubs.files.get(`${KB}/Sales/access.md`)!;
-      // The group's bare grant is gone; the role's explicit grant survives.
+      // The group's grant is gone; the role's spellings survive.
+      expect(text).not.toContain('group/Product');
       expect(text).toContain('- role/Product');
-      expect(text.split('\n')).not.toContain('  - Product');
+      expect(text.split('\n')).toContain('  - Product');
     });
 
     it('a ROLE revoke still sweeps legacy bare spellings when nothing shadows the name', async () => {
@@ -318,6 +322,7 @@ describe('POST /access/revoke — route classification + modes', () => {
           [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n---\n',
         },
         grantSources: () => ({}),
+        roles: ['Everyone', 'Product'],
       });
       const res = await revoke({
         path: `${KB}/Sales`,

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

@@ -12,6 +12,7 @@ import { createAccessRoutes } from '../access.routes.js';
 import type { Database } from '../../database/connection.js';
 import { usersDbDouble } from './users-db-double.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * A grant to an email with NO ACCOUNT says so, and stays allowed.
@@ -112,6 +113,7 @@ async function makeHarness(opts: {
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       opts.db ?? usersDbDouble(opts.accounts ?? []),
       testKbContext({ kbDirName: KB }),
+      new NodeFs(),
     ),
   );
 

package/src/modules/access/__tests__/grant-sources.test.ts

@@ -204,7 +204,7 @@ describe('AccessControlService.grantSources', () => {
   });
 });
 
-describe('grantSources — principal kind under group shadowing', () => {
+describe('grantSources — principal kind when a group shares a role name', () => {
   let root: string;
   let repo: string;
   let svc: AccessControlService;
@@ -216,8 +216,8 @@ describe('grantSources — principal kind under group shadowing', () => {
     repo = path.join(workspaceDir, PROCESS_MAP_DIR);
     await fs.mkdir(repo, { recursive: true });
     await writeFile(repo, 'roles.yaml', ROLES_YAML);
-    // A GROUP named Engineer shadows the Engineer ROLE: the bare token is the
-    // group's, `role/engineer` is the role's.
+    // A GROUP named Engineer shares the Engineer ROLE's name: the bare token
+    // and `role/engineer` are the role's, `group/engineer` is the group's.
     await writeFile(repo, 'groups.yaml', 'groups:\n  Engineer:\n    - pat@x.io\n');
     svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR, new NodeFs());
   });
@@ -226,13 +226,13 @@ describe('grantSources — principal kind under group shadowing', () => {
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  it("a shadowed BARE grant belongs to the GROUP — it must not hide the role's ancestor grant", async () => {
-    // The cubic case: bare (group) grant on the target, role/ grant on the
-    // ancestor. Attributing the bare token to the role would report the role
-    // as `direct` here — hiding the real role/<Name> ancestor grant and
-    // making its revoke a false no-op.
+  it("a group/ grant belongs to the GROUP — it must not hide the role's ancestor grant", async () => {
+    // group/ grant on the target, role/ grant on the ancestor. Attributing the
+    // group's token to the role would report the role as `direct` here —
+    // hiding the real role/<Name> ancestor grant and making its revoke a
+    // false no-op.
     await writeFile(repo, 'access.md', '---\nwrite:\n  - role/Engineer\n---\n');
-    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - group/Engineer\n---\n');
 
     const roleSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
       kind: 'role',
@@ -243,23 +243,28 @@ describe('grantSources — principal kind under group shadowing', () => {
 
     const groupSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
       kind: 'role',
-      role: 'Engineer', // bare = whoever owns the bare key = the group
+      role: 'group/Engineer',
     });
-    // The GROUP's only entry is the direct bare grant.
+    // The GROUP's only entry is the direct group/ grant.
     expect(groupSrc.write).toEqual([{ kind: 'direct' }]);
   });
 
-  it("a shadowed role/ grant is never attributed to the GROUP principal", async () => {
+  it('a BARE grant of a shared name is the ROLE\'s, never attributed to the GROUP principal', async () => {
     await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
-    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - role/Engineer\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
     const groupSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
       kind: 'role',
-      role: 'Engineer',
+      role: 'group/Engineer',
     });
     expect(groupSrc).toEqual({}); // the group holds nothing here
+    const roleSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'role/Engineer',
+    });
+    expect(roleSrc.write).toEqual([{ kind: 'direct' }]);
   });
 
-  it('UNSHADOWED both spellings still count as the role (legacy bare grants stay removable)', async () => {
+  it('with no group of the name, both spellings count as the role (legacy bare grants stay removable)', async () => {
     await fs.rm(path.join(repo, 'groups.yaml'));
     await writeFile(repo, 'access.md', '---\nwrite:\n  - role/Engineer\n---\n');
     await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');

package/src/modules/access/__tests__/groups-admin.routes.test.ts

@@ -0,0 +1,61 @@
+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 { IAdminAccessService } from '../../admin/index.js';
+import type { GroupsAdminService } from '../groups-admin.service.js';
+import { createGroupsAdminRoutes } from '../groups-admin.routes.js';
+
+/**
+ * GET /admin/groups is a read: the roster is filtered for the email the admin
+ * gate checked, and a failing user lookup (needed only to attribute commits)
+ * never fails it.
+ */
+describe('GET /admin/groups', () => {
+  let server: Server | null = null;
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => (server ? server.close(() => resolve()) : resolve()));
+    server = null;
+  });
+
+  async function start(email: string, isAdmin: boolean) {
+    const getRoster = vi.fn(async (viewer: string) => ({ viewer, groups: [] }));
+    const getUserById = vi.fn(async () => {
+      throw new Error('users table unavailable');
+    });
+    const app = express();
+    app.use((req, _res, next) => {
+      req.userId = 'u-1';
+      req.userEmail = email;
+      next();
+    });
+    app.use(
+      createGroupsAdminRoutes({
+        groupsAdmin: { getRoster } as unknown as GroupsAdminService,
+        adminAccess: { isAdmin: async () => isAdmin } as unknown as IAdminAccessService,
+        getUserById,
+      }),
+    );
+    server = app.listen(0);
+    await new Promise<void>((resolve) => server!.once('listening', () => resolve()));
+    const { port } = server.address() as AddressInfo;
+    return { url: `http://127.0.0.1:${port}/admin/groups`, getRoster, getUserById };
+  }
+
+  it('reads the roster for the gated email without a user lookup', async () => {
+    const { url, getRoster, getUserById } = await start('admin@x.io', true);
+    const res = await fetch(url);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ viewer: 'admin@x.io', groups: [] });
+    expect(getRoster).toHaveBeenCalledWith('admin@x.io');
+    expect(getUserById).not.toHaveBeenCalled();
+  });
+
+  it('still refuses a non-admin', async () => {
+    const { url, getRoster } = await start('pat@x.io', false);
+    expect((await fetch(url)).status).toBe(403);
+    expect(getRoster).not.toHaveBeenCalled();
+  });
+});

package/src/modules/access/__tests__/groups-admin.service.test.ts

@@ -11,6 +11,9 @@ import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { AccessControlService } from '../access-control.service.js';
 import { GroupsAdminService, GroupsAdminError } from '../groups-admin.service.js';
 import { createGroup, addGroupMember, GroupsEditError } from '../groups-edit.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { AccessDeniedError } from '../../access-model/index.js';
+import { UNSHOWN_REFERENCE_REFUSAL } from '../reference-scan.js';
 
 const KB = 'knowledge-base';
 const ADMIN: AuthUser = { id: 'u-admin', email: 'admin@x.io', name: 'Admin' } as AuthUser;
@@ -108,6 +111,7 @@ describe('GroupsAdminService', () => {
       workspace,
       workflow.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
+      new NodeFs(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -126,7 +130,7 @@ describe('GroupsAdminService', () => {
       'roles.yaml',
       'roles:\n  Admin:\n    - admin@x.io\n  Reviewer:\n    - rev@x.io\n    - group:gtm team\n',
     );
-    const roster = await service.getRoster();
+    const roster = await service.getRoster('admin@x.io');
     expect(roster.mode).toBe('manual');
     expect(roster.groupsHealth).toEqual({ ok: true });
     expect(roster.groups.map((g) => g.displayName).sort()).toEqual(['GTM Team', 'Product']);
@@ -141,7 +145,7 @@ describe('GroupsAdminService', () => {
 
   it('a broken MANUAL groups.yaml answers the roster with 422 + the parse message', async () => {
     await write(repo, 'groups.yaml', 'groups:\n  - not\n  - a\n  - mapping\n');
-    const err = await service.getRoster().catch((e: unknown) => e);
+    const err = await service.getRoster('admin@x.io').catch((e: unknown) => e);
     expect(err).toBeInstanceOf(GroupsAdminError);
     expect((err as GroupsAdminError).status).toBe(422);
     expect((err as GroupsAdminError).message).toMatch(/groups.yaml/);
@@ -152,7 +156,7 @@ describe('GroupsAdminService', () => {
 
   it('a broken SYNCED file keeps IdP mode: empty roster + groupsHealth marker (no manual fallback)', async () => {
     await write(repo, 'synced-groups.yaml', 'groups:\n  - not\n  - a\n  - mapping\n');
-    const roster = await service.getRoster();
+    const roster = await service.getRoster('admin@x.io');
     expect(roster.mode).toBe('idp');
     // Falling back to groups.yaml would resurrect retired manual groups.
     expect(roster.groups).toEqual([]);
@@ -218,7 +222,7 @@ describe('GroupsAdminService', () => {
 
   it('IdP mode: mutations refuse with the typed 409; reads still work', async () => {
     await write(repo, 'synced-groups.yaml', 'groups:\n  Engineering:\n    - ada@x.io\n');
-    const roster = await service.getRoster();
+    const roster = await service.getRoster('admin@x.io');
     expect(roster.mode).toBe('idp');
     // The roster IS the synced file now — not the retired manual list.
     expect(roster.groups.map((g) => g.canonical)).toEqual(['engineering']);
@@ -241,18 +245,106 @@ describe('GroupsAdminService', () => {
   });
 
   it('canonical-changing rename rewrites grant references in ONE commit', async () => {
-    await write(repo, 'Knowledge/Sales/access.md', '---\nread:\n  - GTM Team\nwrite:\n  - deny GTM Team\n---\n');
+    await write(
+      repo,
+      'Knowledge/Sales/access.md',
+      '---\nread:\n  - GTM Team\n  - group/GTM Team\nwrite:\n  - deny GTM Team\n---\n',
+    );
     await service.renameGroup(ADMIN, 'gtm team', 'Go To Market');
 
     expect(await groupsYaml()).toContain('Go To Market:');
     const rewritten = await fs.readFile(path.join(repo, 'Knowledge/Sales/access.md'), 'utf-8');
-    expect(rewritten).toContain('- Go To Market');
-    expect(rewritten).toContain('- deny Go To Market');
+    // Rewritten as the explicit group token, whatever the old spelling.
+    expect(rewritten).toContain('- group/Go To Market');
+    expect(rewritten).toContain('- deny group/Go To Market');
     expect(rewritten).not.toContain('GTM Team');
     expect(commits).toHaveLength(1);
     expect(commits[0].summary).toContain('gtm team → Go To Market');
   });
 
+  // Another person's private plugin is closed to the Admin: the rewrite still
+  // covers it (no reference left behind). Whether the Admin may WRITE it is
+  // the commit gate's call — see the gated cases below; this stub allows it.
+  it('rename rewrites a file the Admin cannot read when the commit allows it', async () => {
+    await write(
+      repo,
+      'Plugins/Sara/access.md',
+      '---\nread:\n  - deny everyone\n  - Sara <sara@x.io>\nwrite:\n  - Sara <sara@x.io>\n---\n',
+    );
+    await write(repo, 'Plugins/Sara/Notes.md', "---\nread: ['group/GTM Team']\n---\n# Notes\n");
+    const access = new AccessControlService(stubWorkspace(root) as never, KB, new NodeFs());
+    expect(await access.canRead(workspaceIdForBranch(DEFAULT_BRANCH), ADMIN.email, 'Plugins/Sara/Notes.md')).toBe(false);
+
+    await service.renameGroup(ADMIN, 'gtm team', 'Go To Market');
+
+    expect(await fs.readFile(path.join(repo, 'Plugins/Sara/Notes.md'), 'utf-8')).toBe(
+      "---\nread: ['group/Go To Market']\n---\n# Notes\n",
+    );
+    expect(commits).toHaveLength(1);
+  });
+
+  describe('rename against the commit write gate', () => {
+    // The real commit gates every touched path on the actor's write rules and
+    // refuses the first one they may not write (git.service
+    // `assertCanWriteAtRef`); this stub does the same through the live model.
+    function gatedService(): { gated: GroupsAdminService; gatedCommits: { summary: string }[] } {
+      const workspace = stubWorkspace(root);
+      const access = new AccessControlService(workspace as never, KB, new NodeFs());
+      const workflow = stubWorkflow();
+      const svc = workflow.svc as unknown as Record<string, unknown>;
+      svc.commitChanges = async (ws: string, user: AuthUser, summary: string, onlyPaths: string[] = []) => {
+        const rel = onlyPaths.map((p) => p.slice(KB.length + 1));
+        const verdicts = await access.canWriteBatch(ws, user.email, rel);
+        const denied = rel.find((p) => verdicts.get(p) !== true);
+        if (denied) throw new AccessDeniedError({ path: denied, eligibleRoles: [], eligibleUsers: [] });
+        workflow.commits.push({ summary });
+        return {} as unknown;
+      };
+      const gated = new GroupsAdminService(workspace, workflow.svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH);
+      return { gated, gatedCommits: workflow.commits };
+    }
+
+    const SARA_ACCESS = '---\nread:\n  - deny everyone\n  - Sara <sara@x.io>\nwrite:\n  - Sara <sara@x.io>\n---\n';
+
+    it('a file the Admin cannot read refuses generically, never naming it, and writes nothing', async () => {
+      await write(repo, 'Plugins/Sara/access.md', SARA_ACCESS);
+      const notes = "---\nread: ['group/GTM Team']\n---\n# Notes\n";
+      await write(repo, 'Plugins/Sara/Notes.md', notes);
+      const { gated, gatedCommits } = gatedService();
+
+      const err = await gated.renameGroup(ADMIN, 'gtm team', 'Go To Market').catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(GroupsAdminError);
+      expect((err as GroupsAdminError).status).toBe(422);
+      expect((err as Error).message).toBe(UNSHOWN_REFERENCE_REFUSAL);
+      expect((err as Error).message).not.toContain('Sara');
+      // Restored: the hidden file, and the roster, as they were.
+      expect(await fs.readFile(path.join(repo, 'Plugins/Sara/Notes.md'), 'utf-8')).toBe(notes);
+      expect(await groupsYaml()).toBe(GROUPS);
+      expect(gatedCommits).toHaveLength(0);
+    });
+
+    it('a file the Admin can read but not write keeps the refusal that names it', async () => {
+      await write(repo, 'Knowledge/Locked/access.md', '---\nread:\n  - everyone\nwrite:\n  - deny Admin\n---\n');
+      await write(repo, 'Knowledge/Locked/Plan.md', '---\nread:\n  - group/GTM Team\n---\n# Plan\n');
+      const { gated } = gatedService();
+
+      const err = await gated.renameGroup(ADMIN, 'gtm team', 'Go To Market').catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(AccessDeniedError);
+      expect((err as AccessDeniedError).access.path).toMatch(/^Knowledge\/Locked\//);
+    });
+
+    it('a hidden file that names something else does not block the rename', async () => {
+      await write(repo, 'Plugins/Sara/access.md', SARA_ACCESS);
+      await write(repo, 'Plugins/Sara/Notes.md', "---\nread: ['group/Product']\n---\n# Notes\n");
+      await write(repo, 'Knowledge/Sales/access.md', '---\nread:\n  - group/GTM Team\n---\n');
+      const { gated, gatedCommits } = gatedService();
+
+      await gated.renameGroup(ADMIN, 'gtm team', 'Go To Market');
+      expect(await fs.readFile(path.join(repo, 'Knowledge/Sales/access.md'), 'utf-8')).toContain('group/Go To Market');
+      expect(gatedCommits).toHaveLength(1);
+    });
+  });
+
   it('rename rewrites a BODY-GOVERNED access.md (rules live below the frontmatter)', async () => {
     // New-format file: frontmatter governs access.md itself, the body is the
     // folder's rules — exactly what the resolver enforces.
@@ -262,14 +354,15 @@ describe('GroupsAdminService', () => {
       '---\nwrite:\n  - Admin\n---\nread:\n  - GTM Team\nwrite:\n  - deny GTM Team\n',
     );
     // The scan must see the body rule too (delete warnings / referencedBy).
-    const roster = await service.getRoster();
+    const roster = await service.getRoster('admin@x.io');
     const gtm = roster.groups.find((g) => g.canonical === 'gtm team');
     expect(gtm?.referencedBy).toContainEqual({ path: 'Knowledge/Sales/access.md', verb: 'read' });
 
     await service.renameGroup(ADMIN, 'gtm team', 'Go To Market');
     const rewritten = await fs.readFile(path.join(repo, 'Knowledge/Sales/access.md'), 'utf-8');
-    expect(rewritten).toContain('- Go To Market');
-    expect(rewritten).toContain('- deny Go To Market');
+    // Rewritten as the explicit group token, whatever the old spelling.
+    expect(rewritten).toContain('- group/Go To Market');
+    expect(rewritten).toContain('- deny group/Go To Market');
     expect(rewritten).not.toContain('GTM Team');
     // The frontmatter self-rule is a rule source too, and Admin is untouched.
     expect(rewritten).toContain('- Admin');
@@ -303,6 +396,7 @@ describe('GroupsAdminService', () => {
       workspace,
       workflow.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
+      new NodeFs(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -349,6 +443,7 @@ describe('GroupsAdminService', () => {
       workspace,
       workflow.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
+      new NodeFs(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -388,6 +483,7 @@ describe('GroupsAdminService', () => {
       workspace,
       workflow.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
+      new NodeFs(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -421,27 +517,124 @@ describe('groups-edit guardrails', () => {
 });
 
 describe('groups roster referencedBy — the mirror of the roles roster attribution', () => {
-  it('a group shadowed BY a role name still owns its bare-token hits; role/<name> hits are never the group’s', async () => {
+  it('a group sharing a role name owns only its group/ hits; bare and role/ hits are the role’s', async () => {
     const root2 = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-groups-shadow-'));
     try {
       const repo2 = path.join(root2, KB);
-      // A group named Reviewer shares the Reviewer role's name. Group-first
-      // precedence gives the GROUP the bare key, so the bare hit is its
-      // reference; the explicit role/ hit belongs to the ROLE roster only.
+      // A group named Reviewer shares the Reviewer role's name. Role-first
+      // precedence gives the ROLE the bare key, so the bare and role/ hits
+      // belong to the ROLE roster; the group's reference is its group/ hit.
+      // The bare hit is reported so an Admin can rewrite it if the group
+      // was meant.
       await write(repo2, 'roles.yaml', ROLES); // declares role Reviewer
-      await write(repo2, 'groups.yaml', 'groups:\n  Reviewer:\n    - pat@x.io\n');
-      await write(repo2, 'team/access.md', '---\nread:\n  - Reviewer\nwrite:\n  - role/Reviewer\n---\n');
+      await write(repo2, 'groups.yaml', 'groups:\n  Reviewer:\n    - pat@x.io\n  Ops:\n    - ops@x.io\n');
+      await write(repo2, 'ops/access.md', '---\nread:\n  - Ops\nwrite:\n  - group/Ops\n---\n');
+      await write(
+        repo2,
+        'team/access.md',
+        '---\nread:\n  - Reviewer\nwrite:\n  - role/Reviewer\nowner:\n  - group/Reviewer\ndownload:\n  - deny Reviewer\n---\n',
+      );
       const workspace = stubWorkspace(root2);
       const svc = new GroupsAdminService(
         workspace,
         stubWorkflow().svc,
         new AccessControlService(workspace as never, KB, new NodeFs()),
+        new NodeFs(),
         KB,
         () => DEFAULT_BRANCH,
       );
-      const roster = await svc.getRoster();
+      // rev@x.io holds the Reviewer role, so it can read team/access.md.
+      const roster = await svc.getRoster('rev@x.io');
       const reviewer = roster.groups.find((g) => g.canonical === 'reviewer')!;
-      expect(reviewer.referencedBy).toEqual([{ path: 'team/access.md', verb: 'read' }]);
+      expect(reviewer.referencedBy).toEqual([{ path: 'team/access.md', verb: 'owner' }]);
+      // A bare DENIAL changed meaning too (it now denies the role, not the
+      // group), so it is reported alongside the bare grant.
+      expect(reviewer.bareNameResolvesToRole).toEqual([
+        { path: 'team/access.md', verb: 'read' },
+        { path: 'team/access.md', verb: 'download' },
+      ]);
+      // A group no role shares a name with keeps its bare hits, and has nothing
+      // to report. ops@x.io is in Ops, so it can read ops/access.md.
+      const ops = (await svc.getRoster('ops@x.io')).groups.find((g) => g.canonical === 'ops')!;
+      expect(ops.referencedBy).toEqual(
+        expect.arrayContaining([
+          { path: 'ops/access.md', verb: 'read' },
+          { path: 'ops/access.md', verb: 'write' },
+        ]),
+      );
+      expect(ops.referencedBy).toHaveLength(2);
+      expect(ops.bareNameResolvesToRole).toEqual([]);
+    } finally {
+      await fs.rm(root2, { recursive: true, force: true });
+    }
+  });
+
+  it('bareNameResolvesToRole names only the files the viewer can read', async () => {
+    const root2 = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-groups-disclose-'));
+    try {
+      const repo2 = path.join(root2, KB);
+      await write(repo2, 'roles.yaml', ROLES); // Admin: admin@x.io, Reviewer: rev@x.io
+      await write(repo2, 'groups.yaml', 'groups:\n  Reviewer:\n    - pat@x.io\n');
+      await write(repo2, 'access.md', '---\nread:\n  - everyone\nwrite:\n  - Admin\n---\n');
+      // Two bare Reviewer rules: one in an open folder, one in a node only
+      // the Reviewer role may read.
+      await write(repo2, 'team/access.md', '---\nwrite:\n  - Reviewer\n---\n');
+      await write(repo2, 'secret/Plan.md', '---\nread:\n  - deny everyone\n  - Reviewer\n---\n# Plan\n');
+      const workspace = stubWorkspace(root2);
+      const access = new AccessControlService(workspace as never, KB, new NodeFs());
+      const svc = new GroupsAdminService(workspace, stubWorkflow().svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH);
+      const rowsFor = async (email: string) =>
+        (await svc.getRoster(email)).groups.find((g) => g.canonical === 'reviewer')!.bareNameResolvesToRole;
+
+      expect(await rowsFor('rev@x.io')).toEqual(
+        expect.arrayContaining([
+          { path: 'team/access.md', verb: 'write' },
+          { path: 'secret/Plan.md', verb: 'read' },
+        ]),
+      );
+      // pat@x.io is in the Reviewer GROUP, not the role: the bare grant is the
+      // role's, so the secret file is closed to pat, and so is its path.
+      expect(await access.canRead(workspaceIdForBranch(DEFAULT_BRANCH), 'pat@x.io', 'secret/Plan.md')).toBe(false);
+      expect(await rowsFor('pat@x.io')).toEqual([{ path: 'team/access.md', verb: 'write' }]);
+    } finally {
+      await fs.rm(root2, { recursive: true, force: true });
+    }
+  });
+
+  it('referencedBy names only the files the viewer can read and omits the rest entirely, uncounted', async () => {
+    const root2 = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-groups-disclose-refs-'));
+    try {
+      const repo2 = path.join(root2, KB);
+      await write(repo2, 'roles.yaml', ROLES); // Admin: admin@x.io, Reviewer: rev@x.io
+      await write(repo2, 'groups.yaml', 'groups:\n  Ops:\n    - ops@x.io\n');
+      await write(repo2, 'access.md', '---\nread:\n  - everyone\nwrite:\n  - Admin\n---\n');
+      // Two group/Ops rules: one in an open folder, one in a node only the
+      // Reviewer role may read.
+      await write(repo2, 'team/access.md', '---\nwrite:\n  - group/Ops\n---\n');
+      await write(
+        repo2,
+        'secret/Plan.md',
+        '---\nread:\n  - deny everyone\n  - Reviewer\nowner:\n  - deny group/Ops\n---\n# Plan\n',
+      );
+      const workspace = stubWorkspace(root2);
+      const svc = new GroupsAdminService(
+        workspace,
+        stubWorkflow().svc,
+        new AccessControlService(workspace as never, KB, new NodeFs()),
+        new NodeFs(),
+        KB,
+        () => DEFAULT_BRANCH,
+      );
+      const opsFor = async (email: string) =>
+        (await svc.getRoster(email)).groups.find((g) => g.canonical === 'ops')!;
+
+      const asReviewer = await opsFor('rev@x.io');
+      expect(asReviewer.referencedBy.map((r) => r.path).sort()).toEqual(['secret/Plan.md', 'team/access.md']);
+      // The Admin cannot read secret/Plan.md: its rule is left out entirely —
+      // not named, and not counted either (Admin status does not grant read).
+      const asAdmin = await opsFor('admin@x.io');
+      expect(asAdmin.referencedBy).toEqual([{ path: 'team/access.md', verb: 'write' }]);
+      expect(asAdmin).not.toHaveProperty('referencesHidden');
     } finally {
       await fs.rm(root2, { recursive: true, force: true });
     }