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

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

@@ -0,0 +1,368 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import 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);
+  }
+
+  // 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('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' },
+      ]);
+    });
+  });
+});

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

@@ -184,6 +184,14 @@ describe('GroupsAdminService', () => {
     expect(await groupsYaml()).not.toContain('role/');
   });
 
+  it("createGroup refuses the reserved 'plugin/' prefix — a group could otherwise pose as a plugin's members", async () => {
+    await expect(service.createGroup(ADMIN, 'plugin/GTM/read')).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining('plugin/'),
+    });
+    expect(await groupsYaml()).not.toContain('plugin/');
+  });
+
   it('create → add → remove → delete lifecycle lands on disk', async () => {
     await service.createGroup(ADMIN, 'Contractors');
     await service.addMember(ADMIN, 'contractors', 'temp@x.io');

package/src/modules/access/access-control.interface.ts

@@ -67,7 +67,7 @@ export type GrantPrincipal =
  * returns it, and payload consumers fall back to `roles` (all treated as
  * roles) when absent.
  */
-export type ResolvedPrincipal = { name: string; kind: 'role' | 'group' };
+export type ResolvedPrincipal = { name: string; kind: 'role' | 'group' | 'plugin' };
 
 /**
  * Per-verb sources of a principal's access on a target. Only verbs the principal
@@ -199,11 +199,13 @@ export interface IAccessControl {
   /**
    * Answers the file viewer's "who can see this?" affordance. `restricted` is
    * false only when `read: everyone` applies without an effective user-level
-   * denial — the node is readable by all signed-in users, and the role/user
-   * lists are empty because their content would be meaningless. When
-   * `restricted` is true the lists name the principals (roles + direct users)
-   * that may read, with owners folded in (an `owner:` grant confers read). The
-   * lists may be empty for a default-denied path with no grants.
+   * denial — the node is readable by all signed-in users. The lists name the
+   * principals (roles + direct users) granted read whether or not the node
+   * is public, with owners folded in (an `owner:` grant confers read); on a
+   * public node they include what makes it public. `publicVia` names the
+   * PUBLIC plugin principals granted read here — principals every signed-in
+   * user holds — so a caller can tell public-through-a-plugin from a literal
+   * `everyone` grant. The lists may be empty for a default-denied path.
    */
   eligibleReaders(
     workspaceId: string,
@@ -213,6 +215,7 @@ export interface IAccessControl {
     principals?: ResolvedPrincipal[];
     roles: string[];
     users: { name: string; email: string }[];
+    publicVia?: string[];
   }>;
 
   /**
@@ -323,9 +326,17 @@ export interface IAccessControl {
    * (named). The login-only `users` table is unioned in by the caller — this
    * method covers the KB-canonical people the users table misses.
    */
-  kbPrincipals(
-    workspaceId: string,
-  ): Promise<{ roles: string[]; groups: string[]; people: { name: string; email: string }[] }>;
+  kbPrincipals(workspaceId: string): Promise<{
+    roles: string[];
+    groups: string[];
+    /**
+     * Plugins whose `plugin/<Name>/<verb>` principals exist (personal folders
+     * excluded): the display name and the repo-relative folder, so a caller
+     * can apply the discoverability verdict (`canRead` on `<folder>/access.md`).
+     */
+    plugins: { name: string; folder: string }[];
+    people: { name: string; email: string }[];
+  }>;
 
   /**
    * Reverse-lookup an email by its SHA-256 hash (per `hashEmail` semantics)