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

package/src/modules/access/__tests__/access.routes.folder-governs.test.ts

@@ -16,6 +16,7 @@ import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
 import { AccessMutationError, AccessMutationService } from '../access-mutation.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * A file that cannot carry frontmatter is never written by an access mutation.
@@ -161,6 +162,7 @@ describe('access mutations on a file that cannot carry frontmatter', () => {
         { emit: vi.fn() } as unknown as WorkflowEventBus,
         usersDbDouble(),
         testKbContext({ kbDirName: KB }),
+        new NodeFs(),
       ),
     );
     server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.group-grant.test.ts

@@ -12,6 +12,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 GROUP and ROLE principals on the share
@@ -99,7 +100,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));
@@ -126,7 +127,7 @@ describe('group principals on the share surface', () => {
       body: JSON.stringify(body),
     });
 
-  it('grants read to a known group — spliced as the bare-name token', async () => {
+  it('grants read to a known group — spliced as the explicit group/<Name> token', async () => {
     h = await makeHarness({ groups: ['GTM Team', 'Product'] });
     const res = await post('grant', {
       path: `${KB}/Sales`,
@@ -136,8 +137,8 @@ describe('group principals on the share surface', () => {
     });
     expect(res.status).toBe(200);
     const md = h.files.get(`${KB}/Sales/access.md`)!;
-    expect(md).toContain('- GTM Team');
-    expect(md).not.toContain('role/'); // a GROUP grant is the bare token
+    expect(md.split('\n')).toContain('  - group/GTM Team'); // never the bare name
+    expect(md).not.toContain('role/');
   });
 
   it('grants a ROLE as the explicit role/<Name> token', async () => {
@@ -190,7 +191,7 @@ describe('group principals on the share surface', () => {
     expect(await res.json()).toMatchObject({ kind: 'unknown-role', role: 'Ghost Role' });
   });
 
-  it('a group sharing a role name is grantable — precedence resolves it (no refusal)', async () => {
+  it('a group sharing a role name is grantable — each kind is written with its prefix (no refusal)', async () => {
     h = await makeHarness({ roles: ['Everyone', 'Product'], groups: ['Product'] });
     const asGroup = await post('grant', {
       path: `${KB}/Sales`,
@@ -199,7 +200,7 @@ describe('group principals on the share surface', () => {
       principal: { kind: 'group', group: 'Product' },
     });
     expect(asGroup.status).toBe(200);
-    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- Product');
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- group/Product');
     // The ROLE of the same name grants as the explicit token, side by side.
     const asRole = await post('grant', {
       path: `${KB}/Sales`,
@@ -249,7 +250,19 @@ describe('group principals on the share surface', () => {
       principal: { kind: 'group', group: 'Product' },
     });
     expect(res.status).toBe(200);
-    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- Product');
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- group/Product');
+  });
+
+  it('a group named with its group/ prefix is written once-prefixed', async () => {
+    h = await makeHarness({ groups: ['GTM Team'] });
+    const res = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'group/GTM Team' },
+    });
+    expect(res.status).toBe(200);
+    expect(h.files.get(`${KB}/Sales/access.md`)!.split('\n')).toContain('  - group/GTM Team');
   });
 
   it('a non-admin granting to a group they are not in is refused exactly like an unknown group', async () => {
@@ -281,9 +294,11 @@ describe('group principals on the share surface', () => {
 
   it('revokes with a group principal (name-based, no existence check)', async () => {
     h = await makeHarness({
+      roles: ['Everyone'],
       groups: ['GTM Team'],
       files: {
-        [`${KB}/Sales/access.md`]: '---\nread:\n  - Vanished Team\n---\n',
+        // Both spellings: the legacy bare one and the explicit one.
+        [`${KB}/Sales/access.md`]: '---\nread:\n  - Vanished Team\n  - group/Vanished Team\n---\n',
       },
     });
     const res = await post('revoke', {
@@ -369,11 +384,11 @@ describe('token-kind family at the route boundary', () => {
     expect(md).toContain('- Admin');
   });
 
-  it('granting a GROUP that shadows an already-granted role/<Name> is NOT swallowed as idempotent', async () => {
+  it('granting a GROUP that shares an already-granted role name is NOT swallowed as idempotent', async () => {
     h = await makeHarness({
       roles: ['Everyone', 'Product'],
       groups: ['Product'],
-      files: { [`${KB}/Sales/access.md`]: '---\nread:\n  - role/Product\n---\n' },
+      files: { [`${KB}/Sales/access.md`]: '---\nread:\n  - role/Product\n  - Product\n---\n' },
     });
     const res = await post('grant', {
       path: `${KB}/Sales`,
@@ -384,15 +399,15 @@ describe('token-kind family at the route boundary', () => {
     expect(res.status).toBe(200);
     const md = h.files.get(`${KB}/Sales/access.md`)!;
     expect(md).toContain('- role/Product');
-    expect(md.split('\n')).toContain('  - Product'); // the group's bare token landed
+    expect(md.split('\n')).toContain('  - group/Product'); // the group's token landed
   });
 
-  it('revoking the ROLE while a same-named GROUP is granted leaves the bare token (kbPrincipals-driven shadowing)', async () => {
+  it("revoking the ROLE while a same-named GROUP is granted leaves the group's token", async () => {
     h = await makeHarness({
       roles: ['Everyone', 'Product'],
       groups: ['Product'],
       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',
       },
     });
     const res = await post('revoke', {
@@ -403,6 +418,27 @@ describe('token-kind family at the route boundary', () => {
     expect(res.status).toBe(200);
     const md = h.files.get(`${KB}/Sales/access.md`)!;
     expect(md).not.toContain('role/Product');
-    expect(md.split('\n')).toContain('  - Product'); // the GROUP's grant survives
+    expect(md.split('\n')).not.toContain('  - Product'); // the bare name was the role's
+    expect(md.split('\n')).toContain('  - group/Product'); // the GROUP's grant survives
+  });
+
+  it("revoking the GROUP while a same-named ROLE is granted leaves the role's spellings", async () => {
+    h = await makeHarness({
+      roles: ['Everyone', 'Product'],
+      groups: ['Product'],
+      files: {
+        [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n  - group/Product\n---\n',
+      },
+    });
+    const res = await post('revoke', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      principal: { kind: 'group', group: 'Product' },
+    });
+    expect(res.status).toBe(200);
+    const md = h.files.get(`${KB}/Sales/access.md`)!;
+    expect(md).not.toContain('group/Product');
+    expect(md.split('\n')).toContain('  - Product');
+    expect(md).toContain('- role/Product');
   });
 });

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

@@ -12,6 +12,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 contract for `GET /access/overrides`. The scan itself is covered in
@@ -98,7 +99,7 @@ async function makeHarness(opts: {
   });
   app.use(
     '/api',
-    createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })),
+    createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()),
   );
 
   const server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.proposal-branch.test.ts

@@ -139,6 +139,7 @@ describe('access routes on a proposal branch (real git)', () => {
         { emit: () => {} } as unknown as WorkflowEventBus,
         usersDbDouble(),
         testKbContext({ kbDirName: KB }),
+        new NodeFs(),
       ),
     );
     server = await new Promise<Server>((resolve) => {

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

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { Database } from '../../database/connection.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * HTTP contract for `GET /access/prospective` — what the move confirmation
@@ -69,6 +70,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       {} as unknown as Database,
       testKbContext({ kbDirName: KB }),
+      new NodeFs(),
     ),
   );
 

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