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

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

@@ -0,0 +1,385 @@
+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 { parseAccessEntry } from '../../access-model/access-grammar.js';
+
+/**
+ * `plugin/<Name>/<verb>` as a grantable principal: derived from the plugin
+ * folder's own access.md, resolved like any group, and usable on ANY path —
+ * a shared skill under `Skills/`, a Knowledge folder, anything. These tests
+ * drive the public resolver (`canRead`/`canWrite`, `eligibleReaders`,
+ * `kbPrincipals`) over a real on-disk tree; the synthesis is not tested
+ * through its own helper.
+ */
+
+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
+    - sue@x.io
+`;
+
+/** A plugin folder's access.md in the body-governed format. */
+function pluginAccessMd(body: string): string {
+  return `---\nread:\n  - everyone\n---\n${body}`;
+}
+
+describe('plugin principals', () => {
+  let root: string;
+  const workspaceId = 'ws-plugins-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-plugin-principals-'));
+  });
+  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());
+  }
+
+  // A plugin IS a folder with a manifest; its access.md is its roster.
+  const BASE = {
+    'roles.yaml': ROLES_YAML,
+    'groups.yaml': GROUPS_YAML,
+    'access.md': '---\nwrite:\n  - Admin\n---\n',
+    'Plugins/GTM/plugin.json': '{"name":"gtm"}',
+    'Plugins/GTM/access.md': pluginAccessMd(
+      'read:\n  - Sales Team\n  - Ali <ali@x.io>\nwrite:\n  - Engineer\nowner:\n  - Owen <owen@x.io>\n',
+    ),
+  };
+
+  describe('grammar', () => {
+    it('canonicalises the name half to the manifest slug and keeps the verb', () => {
+      const parsed = parseAccessEntry('plugin/Sales Team/read');
+      expect(parsed.ok && parsed.entry.kind === 'role' && parsed.entry.role).toBe('plugin/sales-team/read');
+      const upper = parseAccessEntry('Plugin/GTM/Write');
+      expect(upper.ok && upper.entry.kind === 'role' && upper.entry.role).toBe('plugin/gtm/write');
+      const denied = parseAccessEntry('deny plugin/GTM/owner');
+      expect(denied.ok && denied.entry.kind === 'role' && denied.entry.deny).toBe(true);
+    });
+
+    it('rejects a token with a missing or unknown verb, naming the valid shapes', () => {
+      for (const bad of ['plugin/GTM', 'plugin/GTM/', 'plugin/GTM/admin', 'plugin//read']) {
+        const parsed = parseAccessEntry(bad);
+        expect(parsed.ok, bad).toBe(false);
+        expect(!parsed.ok && parsed.error).toMatch(/plugin\/<plugin>\/read/);
+      }
+    });
+  });
+
+  describe('resolution', () => {
+    it('grants a shared skill to the plugin\'s readers, writers and owners — and to nobody else', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Skills/Eng/deploy/access.md': '---\n---\nread:\n  - plugin/GTM/read\n',
+      });
+      const skill = 'Skills/Eng/deploy/SKILL.md';
+      // Group member, direct reader, writer (write implies read), owner.
+      for (const email of ['sam@x.io', 'ali@x.io', 'eng@x.io', 'owen@x.io']) {
+        expect(await svc.canRead(workspaceId, email, skill), email).toBe(true);
+      }
+      expect(await svc.canRead(workspaceId, 'mallory@x.io', skill)).toBe(false);
+      // Read on the plugin is read on the skill, nothing more.
+      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,
+        'Skills/Eng/deploy/access.md': '---\n---\nread:\n  - plugin/GTM/read\nwrite:\n  - plugin/GTM/write\n',
+      });
+      const skill = 'Skills/Eng/deploy/SKILL.md';
+      expect(await svc.canWrite(workspaceId, 'eng@x.io', skill)).toBe(true);
+      expect(await svc.canWrite(workspaceId, 'owen@x.io', skill)).toBe(true);
+      expect(await svc.canWrite(workspaceId, 'sam@x.io', skill)).toBe(false);
+      expect(await svc.canWrite(workspaceId, 'ali@x.io', skill)).toBe(false);
+    });
+
+    it('the owner token names owners alone', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'KnowledgeBase/Ops/access.md': '---\n---\nread:\n  - plugin/GTM/owner\n',
+      });
+      expect(await svc.canRead(workspaceId, 'owen@x.io', 'KnowledgeBase/Ops/x.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'eng@x.io', 'KnowledgeBase/Ops/x.md')).toBe(false);
+    });
+
+    it('follows the plugin\'s roster live: a member removed from the plugin loses the skill', async () => {
+      const files = {
+        ...BASE,
+        'Skills/Eng/deploy/access.md': '---\n---\nread:\n  - plugin/GTM/read\n',
+      };
+      const svc = await makeService(files);
+      const skill = 'Skills/Eng/deploy/SKILL.md';
+      expect(await svc.canRead(workspaceId, 'ali@x.io', skill)).toBe(true);
+
+      // Drop Ali from the plugin's own access.md — nothing on the skill changes.
+      await fs.writeFile(
+        path.join(root, workspaceId, KB_DIR, 'Plugins/GTM/access.md'),
+        pluginAccessMd('read:\n  - Sales Team\nwrite:\n  - Engineer\n'),
+      );
+      svc.invalidate(workspaceId);
+      expect(await svc.canRead(workspaceId, 'ali@x.io', skill)).toBe(false);
+      expect(await svc.canRead(workspaceId, 'sam@x.io', skill)).toBe(true);
+    });
+
+    it('a public WRITE principal makes the path writable by everyone — and the eligible set says so', async () => {
+      // A gate that counts approvers must not see "a principal with no
+      // enumerable members" where the truth is "anyone signed in".
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/Open/plugin.json': '{"name":"open"}',
+        'Plugins/Open/access.md': pluginAccessMd('read:\n  - everyone\nwrite:\n  - everyone\n'),
+        'Skills/Common/tips/access.md': '---\n---\nwrite:\n  - plugin/Open/write\n',
+      });
+      const writers = await svc.eligibleWriters(workspaceId, 'Skills/Common/tips/SKILL.md');
+      expect(writers.roles).toContain('everyone');
+      expect(await svc.canWrite(workspaceId, 'nobody@elsewhere.io', 'Skills/Common/tips/SKILL.md')).toBe(true);
+    });
+
+    it('two folders folding to one slug: the first by path claims it, roster or none — a twin never supplies the members', async () => {
+      // Discovery keeps the first folder by path and skips its twin; the
+      // principal follows the same rule, so the twin's roster never becomes
+      // the grant's membership through the back door.
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/a/GTM/plugin.json': '{"name":"gtm"}',
+        'Plugins/b/GTM/plugin.json': '{"name":"gtm"}',
+        'Plugins/b/GTM/access.md': pluginAccessMd('read:\n  - Zed <zed@x.io>\n'),
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - plugin/GTM/read\n',
+      });
+      // Path order is the walk's order: a/GTM comes first, claims the slug
+      // and has no roster — so the principal is EMPTY. Neither the root-level
+      // GTM's Ali nor the later twin's Zed gets in through it.
+      expect(await svc.canRead(workspaceId, 'ali@x.io', 'Skills/Common/tips/SKILL.md')).toBe(false);
+      expect(await svc.canRead(workspaceId, 'zed@x.io', 'Skills/Common/tips/SKILL.md')).toBe(false);
+    });
+
+    it('a public READ principal makes the path unrestricted — one truth for the flag and the lists', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/Open/plugin.json': '{"name":"open"}',
+        'Plugins/Open/access.md': pluginAccessMd('read:\n  - everyone\nwrite:\n  - Admin\n'),
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - plugin/Open/read\n',
+      });
+      const readers = await svc.eligibleReaders(workspaceId, 'Skills/Common/tips/SKILL.md');
+      expect(readers.restricted).toBe(false);
+    });
+
+    it('orders twins the way the walk does: component by component, never by the whole string', async () => {
+      // `a/b/GTM` is visited before `a-b/GTM` (the walk sorts each level:
+      // "a" < "a-b"); a whole-string compare would weigh "-" against "/" and
+      // could pick the other one — and with it the other roster.
+      const svc = await makeService({
+        'roles.yaml': ROLES_YAML,
+        'groups.yaml': GROUPS_YAML,
+        'access.md': '---\nwrite:\n  - Admin\n---\n',
+        'Plugins/a/b/GTM/plugin.json': '{"name":"gtm"}',
+        'Plugins/a/b/GTM/access.md': pluginAccessMd('read:\n  - Ali <ali@x.io>\n'),
+        'Plugins/a-b/GTM/plugin.json': '{"name":"gtm"}',
+        'Plugins/a-b/GTM/access.md': pluginAccessMd('read:\n  - Zed <zed@x.io>\n'),
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - plugin/GTM/read\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ali@x.io', 'Skills/Common/tips/SKILL.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'zed@x.io', 'Skills/Common/tips/SKILL.md')).toBe(false);
+    });
+
+    it('a public principal is a verdict, not a line: nothing spells everyone, so nothing under that name is removable', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/Open/plugin.json': '{"name":"open"}',
+        'Plugins/Open/access.md': pluginAccessMd('read:\n  - everyone\nwrite:\n  - Admin\n'),
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - plugin/Open/read\n',
+      });
+      const skill = 'Skills/Common/tips/SKILL.md';
+      const readers = await svc.eligibleReaders(workspaceId, skill);
+      expect(readers.restricted).toBe(false);
+      // Public — and the lists still name the grant that makes it so, so the
+      // share dialog has a row to remove it by.
+      expect(readers.principals).toEqual([
+        { name: 'Admin', kind: 'role' }, // the root's write, folded into read
+        { name: 'everyone', kind: 'role' },
+        { name: 'plugin/open/read', kind: 'plugin' },
+      ]);
+      // And WHY it is public: the resolver names the public plugin principal,
+      // which the lists alone cannot tell from an ordinary one.
+      expect(readers.publicVia).toEqual(['plugin/open/read']);
+      // A revoke of `everyone` here would strip no line — so no source claims one.
+      expect(await svc.grantSources(workspaceId, 'file', skill, { kind: 'role', role: 'everyone' })).toEqual({});
+      // The plugin grant IS the line, and the one whose removal ends public read.
+      expect(await svc.grantSources(workspaceId, 'file', skill, { kind: 'role', role: 'plugin/open/read' })).toEqual({
+        read: [{ kind: 'ancestor', path: 'Skills/Common/tips/access.md' }],
+      });
+      // A literal grant, by contrast, is a removable line.
+      const literal = await makeService({
+        ...BASE,
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - everyone\n',
+      });
+      expect(await literal.grantSources(workspaceId, 'file', skill, { kind: 'role', role: 'everyone' })).toEqual({
+        read: [{ kind: 'ancestor', path: 'Skills/Common/tips/access.md' }],
+      });
+    });
+
+    it('a DENIAL of a public principal denies everyone — it beats a literal everyone grant beside it and a farther one', async () => {
+      // Every NAMED person still reads (Admin is granted by name, and a grant
+      // wins among a caller's own keys), so re-checking named people finds
+      // nothing wrong; only the derived everyone verdict can say that the
+      // unnamed caller — who holds the public key and nothing else — is denied.
+      const svc = await makeService({
+        // The admin is the only named person in the whole knowledge base.
+        'roles.yaml': 'roles:\n  Admin:\n    - admin@x.io\n',
+        'groups.yaml': 'groups: {}\n',
+        'access.md': '---\nwrite:\n  - Admin\n---\n',
+        'Plugins/Open/plugin.json': '{"name":"open"}',
+        'Plugins/Open/access.md': pluginAccessMd('read:\n  - everyone\nwrite:\n  - Admin\n'),
+        // Public at the scope above; the folder itself carves everyone back out
+        // through the public principal, next to a literal grant that must lose.
+        'Skills/Common/access.md': '---\n---\nread:\n  - everyone\n',
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - everyone\n  - Admin\n  - deny plugin/Open/read\n',
+      });
+      const skill = 'Skills/Common/tips/SKILL.md';
+      expect(await svc.canRead(workspaceId, 'admin@x.io', skill)).toBe(true);
+      expect(await svc.canRead(workspaceId, 'nobody@elsewhere.io', skill)).toBe(false);
+      expect((await svc.eligibleReaders(workspaceId, skill)).restricted).toBe(true);
+      // The parent, where nothing denies, stays public.
+      expect((await svc.eligibleReaders(workspaceId, 'Skills/Common/SKILL.md')).restricted).toBe(false);
+    });
+
+    it('a plugin readable by everyone yields a public principal', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/Open/plugin.json': '{"name":"open"}',
+        'Plugins/Open/access.md': pluginAccessMd('read:\n  - everyone\nwrite:\n  - Admin\n'),
+        'Skills/Common/tips/access.md': '---\n---\nread:\n  - plugin/Open/read\n',
+      });
+      expect(await svc.canRead(workspaceId, 'nobody@elsewhere.io', 'Skills/Common/tips/SKILL.md')).toBe(true);
+      // The write token of that plugin is still its writers only.
+      expect(await svc.canWrite(workspaceId, 'nobody@elsewhere.io', 'Skills/Common/tips/SKILL.md')).toBe(false);
+    });
+
+    it('membership never counts the access.md frontmatter, a deny, or another plugin token', async () => {
+      const svc = await makeService({
+        ...BASE,
+        // Frontmatter `read: everyone` is discoverability of the FILE. The body
+        // denies Sue, and points at another plugin's token.
+        'Plugins/Narrow/plugin.json': '{"name":"narrow"}',
+        'Plugins/Narrow/access.md': pluginAccessMd(
+          'read:\n  - Sales Team\n  - deny Sue <sue@x.io>\n  - plugin/GTM/read\nwrite:\n  - Admin\n',
+        ),
+        'Skills/S/x/access.md': '---\n---\nread:\n  - plugin/Narrow/read\n',
+      });
+      const skill = 'Skills/S/x/SKILL.md';
+      expect(await svc.canRead(workspaceId, 'sam@x.io', skill)).toBe(true);
+      // Deny entries are skipped, not subtracted: Sue is still in Sales Team.
+      expect(await svc.canRead(workspaceId, 'sue@x.io', skill)).toBe(true);
+      // GTM's reader Ali is NOT a member of Narrow through the nested token.
+      expect(await svc.canRead(workspaceId, 'ali@x.io', skill)).toBe(false);
+      // And nobody at random: the frontmatter `everyone` did not leak in.
+      expect(await svc.canRead(workspaceId, 'mallory@x.io', skill)).toBe(false);
+    });
+
+    it('a token naming a plugin that does not exist is ignored like an unknown role', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Skills/S/x/access.md': '---\n---\nread:\n  - plugin/Ghost/read\n  - Ali <ali@x.io>\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ali@x.io', 'Skills/S/x/SKILL.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'sam@x.io', 'Skills/S/x/SKILL.md')).toBe(false);
+    });
+  });
+
+  describe('display', () => {
+    it('eligibleReaders reports the token as a plugin-kind principal spelled by the identity, whatever the grant wrote', async () => {
+      const svc = await makeService({
+        ...BASE,
+        // The folder's casing — how grants were written before the manifest became the identity.
+        'Skills/Eng/deploy/access.md': '---\n---\nread:\n  - plugin/GTM/read\n',
+      });
+      const readers = await svc.eligibleReaders(workspaceId, 'Skills/Eng/deploy');
+      expect(readers.restricted).toBe(true);
+      expect(readers.principals).toContainEqual({ name: 'plugin/gtm/read', kind: 'plugin' });
+    });
+
+    it('a plugin nested deeper than the root gets its principals too — a plugin is a folder with a manifest', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/teams/Deep/plugin.json': '{"name":"deep"}',
+        'Plugins/teams/Deep/access.md': pluginAccessMd('read:\n  - Ali <ali@x.io>\n'),
+        // A scope folder's own access.md is NOT a roster: no manifest beside it.
+        'Plugins/teams/access.md': '---\n---\nread:\n  - everyone\n',
+        'Skills/S/x/access.md': '---\n---\nread:\n  - plugin/Deep/read\n  - plugin/teams/read\n',
+      });
+      expect(await svc.canRead(workspaceId, 'ali@x.io', 'Skills/S/x/SKILL.md')).toBe(true);
+      expect(await svc.canRead(workspaceId, 'mallory@x.io', 'Skills/S/x/SKILL.md')).toBe(false);
+    });
+
+    it('kbPrincipals lists plugin folders once each, personal SHELVES excluded — by folder, never by name', async () => {
+      const svc = await makeService({
+        ...BASE,
+        'Plugins/Ops/plugin.json': '{"name":"ops"}',
+        'Plugins/Ops/access.md': pluginAccessMd('read:\n  - Admin\n'),
+        'Plugins/personal-abc123/plugin.json': '{"name":"personal-abc123"}',
+        'Plugins/personal-abc123/access.md': '---\n---\nread:\n  - Ali <ali@x.io>\n',
+        // A plugin whose hand-written manifest name wears the prefix is a
+        // plugin all the same: the shelf is a place, decided by the folder.
+        'Plugins/Odd/plugin.json': '{"name":"personal-odd"}',
+        'Plugins/Odd/access.md': pluginAccessMd('read:\n  - Admin\n'),
+      });
+      const { plugins } = await svc.kbPrincipals(workspaceId);
+      // Named by identity — the manifest — with the folder beside it.
+      expect([...plugins].sort((a, b) => a.folder.localeCompare(b.folder))).toEqual([
+        { name: 'gtm', folder: 'Plugins/GTM' },
+        { name: 'personal-odd', folder: 'Plugins/Odd' },
+        { name: 'ops', folder: 'Plugins/Ops' },
+      ]);
+    });
+  });
+});