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

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

@@ -1,4 +1,5 @@
 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';
@@ -70,7 +71,7 @@ describe('group files as access principals', () => {
     for (const [rel, contents] of Object.entries(files)) {
       await writeFile(repo, rel, contents);
     }
-    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR);
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
   }
 
   it('manual mode: a groups.yaml group grants access when named in access.md', async () => {
@@ -214,13 +215,10 @@ describe('group files as access principals', () => {
     });
     expect(active.groups.size).toBe(0); // NOT the retired manual groups
     expect(active.health).toMatchObject({ ok: false, file: 'synced-groups.yaml' });
-    // While genuine absence (ENOENT) still means manual mode:
+    // While genuine absence — the reader's null, judged through the fs
+    // probe — still means manual mode:
     const manual = await loadActiveGroups(async (f) => {
-      if (f === 'synced-groups.yaml') {
-        const err = new Error('ENOENT') as NodeJS.ErrnoException;
-        err.code = 'ENOENT';
-        throw err;
-      }
+      if (f === 'synced-groups.yaml') return null;
       return 'groups:\n  Live Team:\n    - here@x.io\n';
     });
     expect(manual.health).toEqual({ ok: true });
@@ -245,11 +243,7 @@ describe('group files as access principals', () => {
     ).rejects.toBeInstanceOf(AccessUnreadableError);
     await expect(
       loadActiveGroups(async (f) => {
-        if (f === 'synced-groups.yaml') {
-          const err = new Error('ENOENT') as NodeJS.ErrnoException;
-          err.code = 'ENOENT';
-          throw err;
-        }
+        if (f === 'synced-groups.yaml') return null; // absent: manual mode
         throw unreadable(f); // groups.yaml unreadable
       }),
     ).rejects.toBeInstanceOf(AccessUnreadableError);
@@ -403,7 +397,7 @@ describe('group files as access principals', () => {
     // — the at-ref answer must come from the commit, not the tree.
     await fs.writeFile(path.join(repo, 'synced-groups.yaml'), 'groups: {}\n'.replace('{}', ''));
 
-    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR);
+    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
     expect(await svc.canWriteAtRef(workspaceId, 'main', 'ada@x.io', 'Knowledge/Doc.md')).toBe(true);
     expect(await svc.canWriteAtRef(workspaceId, 'main', 'zoe@x.io', 'Knowledge/Doc.md')).toBe(false);
   });
@@ -430,7 +424,7 @@ describe('group files as access principals', () => {
 
   it('synced-groups.yaml is machine-owned: only the sync bot writes it, ever', async () => {
     const { workspaceDir } = await seedWorkspace(root, workspaceId);
-    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR);
+    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
 
     // The bot needs no roles/grants — the rule resolves before the model
     // loads (this workspace has no git repo at all).
@@ -454,3 +448,42 @@ describe('group files as access principals', () => {
     expect(eligible?.roles).toEqual([]);
   });
 });
+
+describe('a role given to a group (`- group:<Name>`), as the agent guide documents it', () => {
+  let root: string;
+  const workspaceId = 'ws-groups-role-ref';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeService(files: Record<string, string>) {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    for (const [rel, contents] of Object.entries(files)) {
+      await writeFile(repo, rel, contents);
+    }
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
+  }
+
+  it('a denial of the role removes its contribution for the whole group; a direct grant to a person is unaffected', async () => {
+    const svc = await makeService({
+      // Spelled differently from groups.yaml: matched case- and whitespace-insensitively.
+      'roles.yaml': 'roles:\n  Admin:\n    - admin@x.io\n    - group:engineering\n',
+      'groups.yaml': GROUPS_YAML_TEXT,
+      'access.md': '---\nread:\n  - Admin\n---\n',
+      'Sub/access.md': '---\nread:\n  - deny Admin\n  - Bo <bo@x.io>\n---\n',
+    });
+    // Group members and direct emails hold the role alike.
+    expect(await svc.canRead(workspaceId, 'ada@x.io', 'Doc.md')).toBe(true);
+    expect(await svc.canRead(workspaceId, 'admin@x.io', 'Doc.md')).toBe(true);
+    // The role denial reaches everyone who held the role, group members included…
+    expect(await svc.canRead(workspaceId, 'ada@x.io', 'Sub/Doc.md')).toBe(false);
+    expect(await svc.canRead(workspaceId, 'admin@x.io', 'Sub/Doc.md')).toBe(false);
+    // …but not a person granted by name.
+    expect(await svc.canRead(workspaceId, 'bo@x.io', 'Sub/Doc.md')).toBe(true);
+  });
+});

package/src/modules/access/__tests__/access-md-format.test.ts

@@ -1,4 +1,5 @@
 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';
@@ -171,7 +172,7 @@ describe('end-to-end resolution over a new-format plugin', () => {
         return workspaceDir;
       },
     } as unknown as WorkspaceService;
-    return new AccessControlService(stub, KB);
+    return new AccessControlService(stub, KB, new NodeFs());
   }
 
   it('a NON-member can read the access.md itself (discovery) but nothing inside the folder', async () => {

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

@@ -1,7 +1,9 @@
 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 { parse as parseYaml } from 'yaml';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
@@ -29,6 +31,7 @@ function stubWorkspace(workspaceDir: string): WorkspaceService {
     getWorkspacePath: async () => workspaceDir,
     getOrCreateForBranch: async () => ({}) as unknown,
     readFile: async (_id: string, wsRel: string) => fs.readFile(resolve(wsRel), 'utf-8'),
+    readFileBinary: async (_id: string, wsRel: string) => fs.readFile(resolve(wsRel)),
     writeFile: async (_id: string, wsRel: string, content: string) => {
       const abs = resolve(wsRel);
       await fs.mkdir(path.dirname(abs), { recursive: true });
@@ -57,7 +60,7 @@ describe('AccessMutationService', () => {
     await write(repo, 'roles.yaml', ROLES_YAML);
     await write(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n# Root\n');
     const ws = stubWorkspace(workspaceDir);
-    access = new AccessControlService(ws, KB);
+    access = new AccessControlService(ws, KB, new NodeFs());
     mutation = new AccessMutationService(ws, access, KB);
   });
 
@@ -121,6 +124,48 @@ describe('AccessMutationService', () => {
     expect(text).toContain('Newbie <newbie@example.com>');
   });
 
+  it("a skill folder's first grant creates its access.md beside the plugin's, and both rules resolve", async () => {
+    // The skill page's Share opens the dialog on the SKILL folder — the same
+    // folder-grant path as anywhere else. The plugin's own rule is untouched,
+    // and the resolver reads the two at their depths as it does any nesting.
+    await write(repo, 'Plugins/newsroom/access.md', '---\nread:\n  - Product Team\n---\n# Newsroom\n');
+    await write(repo, 'Plugins/newsroom/skills/newsletter/SKILL.md', '# Newsletter\n');
+    const skillAccess = path.join(repo, 'Plugins/newsroom/skills/newsletter/access.md');
+    await expect(fs.readFile(skillAccess, 'utf-8')).rejects.toThrow();
+
+    // The folder rules (the access.md BODY, after the frontmatter) as a
+    // verb → entries map, so each grant is checked under its own verb rather
+    // than anywhere in the file.
+    const skillRules = async (): Promise<Record<string, string[]>> => {
+      const text = await fs.readFile(skillAccess, 'utf-8');
+      const m = /^---\n[\s\S]*?\n---\n([\s\S]*)$/.exec(text);
+      expect(m).not.toBeNull();
+      return parseYaml(m![1]) as Record<string, string[]>;
+    };
+
+    const r = await mutation.grant(WS, 'folder', 'Plugins/newsroom/skills/newsletter', 'write', felix);
+    access.invalidate(WS);
+
+    expect(r).toEqual({ changed: true, editPath: 'Plugins/newsroom/skills/newsletter/access.md' });
+    expect((await skillRules()).write).toEqual(['Newbie <newbie@example.com>']);
+    expect(await fs.readFile(path.join(repo, 'Plugins/newsroom/access.md'), 'utf-8')).not.toContain(
+      'newbie@example.com',
+    );
+    // The skill-level grant holds on the skill, not on the rest of the plugin…
+    const skillMd = 'Plugins/newsroom/skills/newsletter/SKILL.md';
+    expect(await access.canWrite(WS, 'newbie@example.com', skillMd)).toBe(true);
+    expect(await access.canWrite(WS, 'newbie@example.com', 'Plugins/newsroom/README.md')).toBe(false);
+    // …and the plugin-level rule still reaches into the skill folder.
+    expect(await access.canRead(WS, 'felix@example.com', skillMd)).toBe(true);
+
+    // A second grant edits the file it created rather than starting another.
+    const second = await mutation.grant(WS, 'folder', 'Plugins/newsroom/skills/newsletter', 'download', felix);
+    expect(second).toEqual({ changed: true, editPath: 'Plugins/newsroom/skills/newsletter/access.md' });
+    const rules = await skillRules();
+    expect(rules.write).toEqual(['Newbie <newbie@example.com>']);
+    expect(rules.download).toEqual(['Newbie <newbie@example.com>']);
+  });
+
   it('grant on a FILE edits the node frontmatter, NOT the folder (no sibling leak)', async () => {
     await write(
       repo,
@@ -304,13 +349,16 @@ describe('AccessMutationService', () => {
       // Admin write on an access.md comes from the hardcoded rescue, which a
       // `deny` entry cannot shadow. denyHere must detect the deny had no effect,
       // roll the file back, and refuse — never report a no-op success.
+      // (A subfolder's access.md: at the root the Admin write floor refuses the
+      // deny up front instead — see access-control.admin-root-floor.test.ts.)
+      await write(repo, 'Sales/access.md', '---\nwrite:\n  - Admin\n---\n# Sales folder\n');
       const admin: Principal = { kind: 'user', email: 'razvan@bevel.software', displayName: 'Razvan' };
-      await expect(mutation.denyHere(WS, 'file', 'access.md', admin)).rejects.toMatchObject({
+      await expect(mutation.denyHere(WS, 'file', 'Sales/access.md', admin)).rejects.toMatchObject({
         status: 409,
       });
       // The access.md is unchanged (rolled back) — admin still writes it.
       access.invalidate(WS);
-      expect(await access.canWrite(WS, 'razvan@bevel.software', 'access.md')).toBe(true);
+      expect(await access.canWrite(WS, 'razvan@bevel.software', 'Sales/access.md')).toBe(true);
     });
 
     it('GROUP deny with a VANISHED group succeeds even when a same-named ROLE keeps a role/<Name> grant', async () => {
@@ -519,7 +567,7 @@ describe('token-kind family — shadow-aware revoke, exact-token grant (real res
     await write(repo, 'roles.yaml', ROLES_YAML);
     await write(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
     const ws = stubWorkspace(workspaceDir);
-    access = new AccessControlService(ws, KB);
+    access = new AccessControlService(ws, KB, new NodeFs());
     mutation = new AccessMutationService(ws, access, KB);
   });
 

package/src/modules/access/__tests__/access-own-read-grant.test.ts

@@ -1,4 +1,5 @@
 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';
@@ -88,6 +89,7 @@ describe('a file-own read grant on a whole-document configuration file', () => {
     new AccessControlService(
       { getWorkspacePath: async () => path.join(root, ws) } as unknown as WorkspaceService,
       KB,
+      new NodeFs(),
     );
 
   it('the grantee reads the file (registered kinds)', async () => {

package/src/modules/access/__tests__/access-personal-plugin.test.ts

@@ -0,0 +1,153 @@
+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';
+import { personalAccessMd, pluginAccessMd } from '../../plugins/plugin-provision.service.js';
+import { defaultKbTemplateDir } from '../../../assets.js';
+import { closePersonalSpaceRules } from '../../workspace/startup/steps/personal-spaces.step.js';
+
+/**
+ * What the seeded access templates actually resolve to, through the public
+ * resolver over a real tree — the two things a customer tripped over:
+ *
+ *  - a personal space must stay private even after an administrator opens
+ *    the repository root with `read: everyone` (the usual way to let a new
+ *    joiner read anything), while its owner keeps reading it — and Admin,
+ *    who reads everything else, does not;
+ *  - the managed AGENTS.md must be readable by every signed-in person even
+ *    when the root grants read to nobody, because agents are told to read
+ *    it before their first action.
+ */
+
+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 OWNER = { name: 'Ali Vega', email: 'ali@x.io' };
+const ROLES_YAML = `roles:\n  Admin:\n    - admin@x.io\n`;
+
+describe('the seeded access templates, resolved', () => {
+  let root: string;
+  const workspaceId = 'ws-personal-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-personal-access-'));
+  });
+  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 PERSONAL = {
+    'roles.yaml': ROLES_YAML,
+    'Plugins/personal-ali/plugin.json': '{"name":"personal-ali"}',
+    'Plugins/personal-ali/access.md': personalAccessMd(OWNER),
+    'Plugins/personal-ali/skills/weekly/SKILL.md': '# Weekly\n',
+    'Plugins/GTM/plugin.json': '{"name":"gtm"}',
+    'Plugins/GTM/access.md': pluginAccessMd(OWNER),
+    'Plugins/GTM/skills/x/SKILL.md': '# X\n',
+  };
+  const PATHS = [
+    'Plugins/personal-ali/skills/weekly/SKILL.md',
+    'Plugins/personal-ali/access.md',
+    'Plugins/GTM/access.md',
+    'Plugins/GTM/skills/x/SKILL.md',
+  ];
+
+  it('a personal space stays closed to everyone else when the root says read: everyone — the owner still reads it, Admin does not', async () => {
+    const svc = await makeService({
+      ...PERSONAL,
+      'access.md': '---\nowner:\n  - Admin\n---\nread:\n  - everyone\nwrite:\n  - Admin\n',
+    });
+    const other = await svc.canReadBatch(workspaceId, 'bob@x.io', PATHS);
+    expect(Object.fromEntries(other)).toEqual({
+      'Plugins/personal-ali/skills/weekly/SKILL.md': false,
+      'Plugins/personal-ali/access.md': false, // not even listed for them
+      // A SHARED plugin's body denies nothing, so the root's opening reaches
+      // into it — that is the difference the personal template's `deny
+      // everyone` makes, and exactly what a customer saw: opening the root
+      // opened every plugin, personal ones included.
+      'Plugins/GTM/access.md': true,
+      'Plugins/GTM/skills/x/SKILL.md': true,
+    });
+    const owner = await svc.canReadBatch(workspaceId, OWNER.email, PATHS);
+    expect(owner.get('Plugins/personal-ali/skills/weekly/SKILL.md')).toBe(true);
+    expect(owner.get('Plugins/personal-ali/access.md')).toBe(true);
+    // Admin reads everything else in the repository; a private space is the
+    // one place the role is not named, so the denial reaches them too. (They
+    // can still WRITE the access.md, through the resolver's rescue, and grant
+    // themselves in — a visible act, not a default.)
+    const admin = await svc.canReadBatch(workspaceId, 'admin@x.io', PATHS);
+    expect(admin.get('Plugins/personal-ali/skills/weekly/SKILL.md')).toBe(false);
+    expect(admin.get('Plugins/personal-ali/access.md')).toBe(false);
+    expect(admin.get('Plugins/GTM/skills/x/SKILL.md')).toBe(true);
+    expect(await svc.canWrite(workspaceId, 'admin@x.io', 'Plugins/personal-ali/access.md')).toBe(true);
+  });
+
+  it("the owner reads, writes and owns their space; nobody else writes it", async () => {
+    const svc = await makeService({ ...PERSONAL, 'access.md': '---\nowner:\n  - Admin\n---\nwrite:\n  - Admin\n' });
+    const skill = 'Plugins/personal-ali/skills/weekly/SKILL.md';
+    expect(await svc.canWrite(workspaceId, OWNER.email, skill)).toBe(true);
+    expect(await svc.canOwner(workspaceId, OWNER.email, 'Plugins/personal-ali')).toBe(true);
+    expect(await svc.canWrite(workspaceId, 'bob@x.io', skill)).toBe(false);
+  });
+
+  it('a personal space seeded by the previous template, once the boot step has closed it, resolves like a new one', async () => {
+    // The old seed: the owner's grants in the legacy single-block shape.
+    const legacy =
+      '---\nread:\n  - Ali Vega <ali@x.io>\nwrite:\n  - Ali Vega <ali@x.io>\nowner:\n  - Ali Vega <ali@x.io>\n---\nread: []\n';
+    const closed = closePersonalSpaceRules(legacy, 'Plugins/personal-ali/access.md');
+    expect(closed).not.toBeNull();
+    // Closing it again changes nothing: the step is idempotent by parse, not by text.
+    expect(closePersonalSpaceRules(closed!, 'Plugins/personal-ali/access.md')).toBeNull();
+
+    const svc = await makeService({
+      'roles.yaml': ROLES_YAML,
+      'access.md': '---\nowner:\n  - Admin\n---\nread:\n  - everyone\nwrite:\n  - Admin\n',
+      'Plugins/personal-ali/plugin.json': '{"name":"personal-ali"}',
+      'Plugins/personal-ali/access.md': closed!,
+      'Plugins/personal-ali/skills/weekly/SKILL.md': '# Weekly\n',
+    });
+    const skill = 'Plugins/personal-ali/skills/weekly/SKILL.md';
+    expect(await svc.canRead(workspaceId, 'bob@x.io', skill)).toBe(false);
+    expect(await svc.canRead(workspaceId, OWNER.email, skill)).toBe(true);
+    expect(await svc.canWrite(workspaceId, OWNER.email, skill)).toBe(true);
+    expect(await svc.canRead(workspaceId, 'admin@x.io', skill)).toBe(false);
+  });
+
+  it('the packaged AGENTS.md is readable by a non-admin even when the root grants read to nobody', async () => {
+    const template = await fs.readFile(path.join(defaultKbTemplateDir(), 'AGENTS.md'), 'utf8');
+    const svc = await makeService({
+      'roles.yaml': ROLES_YAML,
+      'access.md': '---\nowner:\n  - Admin\n---\nwrite:\n  - Admin\n',
+      'AGENTS.md': template,
+      'KnowledgeBase/Notes.md': '# Notes\n',
+    });
+    const bob = await svc.canReadBatch(workspaceId, 'bob@x.io', ['AGENTS.md', 'KnowledgeBase/Notes.md']);
+    expect(bob.get('AGENTS.md')).toBe(true);
+    // The grant is the FILE's own, not a widening of the root.
+    expect(bob.get('KnowledgeBase/Notes.md')).toBe(false);
+  });
+});

package/src/modules/access/__tests__/access-plugin-principals.test.ts

@@ -1,4 +1,5 @@
 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';
@@ -65,7 +66,7 @@ describe('plugin principals', () => {
       await fs.mkdir(path.dirname(abs), { recursive: true });
       await fs.writeFile(abs, contents);
     }
-    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR);
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
   }
 
   // A plugin IS a folder with a manifest; its access.md is its roster.
@@ -114,6 +115,22 @@ describe('plugin principals', () => {
       expect(await svc.canWrite(workspaceId, 'sam@x.io', skill)).toBe(false);
     });
 
+    it('counts a download-only member of the plugin among its readers', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/GTM/access.md': pluginAccessMd('download:\n  - Dana <dana@x.io>\n'),
+        'Skills/Eng/deploy/access.md': '---\n---\nread:\n  - plugin/GTM/read\n',
+      });
+      const skill = 'Skills/Eng/deploy/SKILL.md';
+      // The roster folds exactly the way resolution does — one shared
+      // `sourceVerbsFor` table — so someone the plugin trusts with a copy of
+      // its files is one of its readers, and the read token names them.
+      expect(await svc.canRead(workspaceId, 'dana@x.io', skill)).toBe(true);
+      // Download is not write, and there is no download token: the read
+      // principal is the only one she lands in.
+      expect(await svc.canWrite(workspaceId, 'dana@x.io', skill)).toBe(false);
+    });
+
     it('the write token names the plugin\'s writers and owners only', async () => {
       const svc = await makeService({
         ...BASE,