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

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -5,6 +5,7 @@ import {
   registerAccessFrontmatterExtensions,
   accessFrontmatterExtensionList,
   parseOwnAccessEntries,
+  parseRolesYaml,
 } from '../access-grammar.js';
 import { parseGroupsFile } from '../group-files.js';
 
@@ -22,6 +23,23 @@ describe('parseYamlSubset — inline empty collections', () => {
   });
 });
 
+describe("the reserved 'plugin/' prefix — no role or group may pose as a plugin principal", () => {
+  it('parseGroupsFile skips such a group with a warning and keeps the rest', () => {
+    const res = parseGroupsFile('groups:\n  plugin/GTM/read:\n    - mallory@x.io\n  Sales:\n    - sam@x.io\n', 'groups.yaml');
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect([...res.groups.keys()]).toEqual(['sales']);
+    expect(res.warnings.some((w) => w.includes("reserved 'plugin/'"))).toBe(true);
+  });
+
+  it('parseRolesYaml refuses such a role outright', () => {
+    const res = parseRolesYaml('roles:\n  Admin:\n    - admin@x.io\n  plugin/GTM/read:\n    - mallory@x.io\n');
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.errors.some((e) => e.includes("reserved 'plugin/'"))).toBe(true);
+  });
+});
+
 describe('parseGroupsFile — empty group sources', () => {
   it('accepts a bare `groups:` as a valid empty set', () => {
     const res = parseGroupsFile('groups:\n', 'groups.yaml');

package/src/modules/access-model/__tests__/access-splice.test.ts

@@ -7,7 +7,13 @@ import {
   AccessSpliceError,
   type Principal,
 } from '../access-splice.js';
-import { parseAccessEntry, canonicalEmail } from '../access-grammar.js';
+import {
+  accessMdDeclaresBodyRules,
+  accessMdSelfEntries,
+  canonicalEmail,
+  parseAccessEntry,
+  parseAccessFile,
+} from '../access-grammar.js';
 
 const felix: Principal = { kind: 'user', email: 'felix.kissel@example.com', displayName: 'Felix' };
 const juan: Principal = { kind: 'user', email: 'juan@bevel.software', displayName: 'Juan V' };
@@ -93,6 +99,35 @@ describe('spliceGrant — idempotency + creation', () => {
     expect(r.text.startsWith('---\n')).toBe(true);
     expect(r.text).toContain('write:\n  - Felix <felix.kissel@example.com>');
   });
+
+  it("a fresh FOLDER access.md is the platform's two-block file: the grant in the body, both blocks explained in place", () => {
+    const r = spliceGrant('', 'read', felix, { target: 'folder' });
+    expect(r.changed).toBe(true);
+    // Two blocks: a comment-only frontmatter, then the body with the verb.
+    const close = r.text.indexOf('\n---\n', 4);
+    const frontmatter = r.text.slice(4, close);
+    const body = r.text.slice(close + 5);
+    expect(frontmatter.split('\n').every((l) => l.startsWith('#'))).toBe(true);
+    expect(frontmatter).toContain('governs this access.md FILE only');
+    expect(body).toContain('governs the FOLDER');
+    expect(body).toContain('`everyone` — every signed-in person, the whole organisation');
+    expect(body.endsWith('\nread:\n  - Felix <felix.kissel@example.com>\n')).toBe(true);
+    // The file parses as body-governed: the grant rules the FOLDER, and the
+    // file declares nothing for itself (a comment-only frontmatter is "no
+    // own rules" — the file follows the folder's).
+    expect(accessMdDeclaresBodyRules(r.text)).toBe(true);
+    const parsed = parseAccessFile(r.text, 'KnowledgeBase/Finance/access.md');
+    expect(parsed.ok && parsed.file.entries.read.map((e) => (e.kind === 'user' ? e.email : e.role))).toEqual([
+      'felix.kissel@example.com',
+    ]);
+    expect(accessMdSelfEntries(r.text)).toBeNull();
+    // A second grant lands beside the first, in the body, with every comment kept.
+    const again = spliceGrant(r.text, 'read', productTeam, { target: 'folder' });
+    expect(again.text).toContain('read:\n  - Felix <felix.kissel@example.com>\n  - Product Team\n');
+    expect(again.text).toContain('governs the FOLDER');
+    // Text without a frontmatter is the legacy format and is not rewritten.
+    expect(spliceGrant('write:\n  - Admin\n', 'read', felix, { target: 'folder' }).text).not.toContain('governs');
+  });
 });
 
 describe('spliceRevoke', () => {
@@ -331,3 +366,30 @@ write:
     expect(r.text).not.toContain('Sales'); // bare token falls back to the role — same principal
   });
 });
+
+describe('line endings: a splice rewrites the file, so it must rewrite it the way the file is written', () => {
+  const felix = { kind: 'user', email: 'felix@example.com', displayName: 'Felix' } as const;
+
+  it('a CRLF file comes back CRLF', () => {
+    const text = '---\r\nread:\r\n  - Admin\r\n---\r\nread:\r\n  - Admin\r\n';
+    const out = spliceGrant(text, 'read', felix, { target: 'folder' }).text;
+    expect(out).toContain('\r\n');
+    expect(out.split('\n').every((l, i, a) => i === a.length - 1 || l.endsWith('\r'))).toBe(true);
+  });
+
+  it('an LF file with ONE stray CRLF stays LF — the stray does not rewrite every other line', () => {
+    // The rule this pins replaces "CRLF if the text contains one anywhere",
+    // under which a single stray ending — in a comment, in the body, pasted
+    // from somewhere else — re-wrote every line of a knowledge base's access
+    // rules and surfaced as churn in somebody's change request.
+    const text = '---\nread:\n  - Admin\n---\nread:\n  - Admin\n# a pasted comment\r\n';
+    const out = spliceGrant(text, 'read', felix, { target: 'folder' }).text;
+    expect(out).not.toContain('\r');
+  });
+
+  it('a mostly-CRLF file with one stray LF stays CRLF — the majority is the file', () => {
+    const text = '---\r\nread:\r\n  - Admin\r\n---\r\nread:\r\n  - Admin\r\n# a pasted comment\n';
+    const out = spliceGrant(text, 'read', felix, { target: 'folder' }).text;
+    expect(out.split('\n').every((l, i, a) => i === a.length - 1 || l.endsWith('\r'))).toBe(true);
+  });
+});

package/src/modules/access-model/__tests__/frontmatter-fences.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { extractFrontmatter as sharedSplit } from '@bevel-software/platform-shared';
+import { scanFrontmatter } from '../frontmatter-lines.js';
+
+/**
+ * Two frontmatter readers survive in the platform, on purpose:
+ *
+ *   - the SHARED splitter (`@bevel-software/platform-shared`), used by the
+ *     skill catalog, the tool manuals, node ids and the frontmatter panel —
+ *     everything that wants the two halves as strings;
+ *   - the access model's LINE scan, which has to put bytes back exactly as it
+ *     found them and so needs the lines.
+ *
+ * They do not share an implementation, but they share ONE fence rule
+ * (`isFrontmatterFence`: a line that is `---` once whitespace is trimmed).
+ * They used not to: the splitter demanded `---` at column 0, so a file with a
+ * near-miss fence had access rules that applied while its catalog entry had
+ * no id. Every case below is asserted for BOTH readers, so if they ever drift
+ * apart again it shows up here, in review, rather than in a customer's
+ * knowledge base.
+ */
+
+const hasShared = (text: string) => sharedSplit(text) !== null;
+const hasLines = (text: string) => scanFrontmatter(text).kind === 'frontmatter';
+
+describe('frontmatter fences: both readers give the same answer', () => {
+  it.each([
+    ['a plain block', '---\nread:\n  - everyone\n---\nbody\n', true],
+    ['no fence at all', 'just a body\n', false],
+    ['an unterminated block', '---\nread:\n  - everyone\n', false],
+    ['a fence that is not the first line', 'title\n---\nread: x\n---\n', false],
+    ['a lone fence and nothing else', '---', false],
+    ['an empty block', '---\n---\nbody\n', true],
+    // The near-miss fences — forgiving everywhere now.
+    ['an opening fence with trailing whitespace', '--- \nread:\n  - everyone\n---\nbody\n', true],
+    ['an indented opening fence', '  ---\nread:\n  - everyone\n---\nbody\n', true],
+    ['an indented closing fence', '---\nread:\n  - everyone\n  ---\nbody\n', true],
+    ['a closing fence with trailing whitespace', '---\nread:\n  - everyone\n--- \nbody\n', true],
+    ['a tab-indented fence pair', '\t---\nid: x\n\t---\n', true],
+    // Not fences: more dashes, or dashes with words after them.
+    ['four dashes is not a fence', '----\nid: x\n----\n', false],
+    ['a dashed line with text after it is not a closing fence', '---\nid: x\n--- not a fence\n', false],
+  ])('%s → %s for both', (_name, text, expected) => {
+    expect(hasShared(text)).toBe(expected);
+    expect(hasLines(text)).toBe(expected);
+  });
+});
+
+describe('the shared splitter hands back both halves byte for byte', () => {
+  it('splits a near-miss block into the lines between the fences and the text after', () => {
+    expect(sharedSplit('  --- \nid: my-skill\ndescription: Does a thing.\n ---\n# Title\n')).toEqual({
+      frontmatter: 'id: my-skill\ndescription: Does a thing.',
+      body: '# Title\n',
+    });
+  });
+
+  it("keeps a CRLF file's own line endings inside the frontmatter and the body", () => {
+    expect(sharedSplit('---\r\nid: a\r\nname: b\r\n---\r\nline one\r\nline two')).toEqual({
+      frontmatter: 'id: a\r\nname: b',
+      body: 'line one\r\nline two',
+    });
+  });
+
+  it('gives an empty body when the closing fence is the last line', () => {
+    expect(sharedSplit('---\nid: a\n---')).toEqual({ frontmatter: 'id: a', body: '' });
+  });
+
+  it('gives an empty frontmatter for a block with nothing between its fences', () => {
+    expect(sharedSplit('---\n---\nbody')).toEqual({ frontmatter: '', body: 'body' });
+  });
+});

package/src/modules/access-model/__tests__/plugin-token-canonical.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import {
+  canonicalPluginToken,
+  canonicalRoleName,
+  parseAccessEntry,
+  parsePluginPrincipalKey,
+} from '../access-grammar.js';
+
+/**
+ * ONE spelling for a plugin principal. Every spelling of a token folds to the
+ * same canonical key — through the parser, through the role canonicaliser
+ * that grants and revocations compare with — and a canonical key is exactly
+ * one name and one verb: nothing nested, nothing that is not already a slug.
+ */
+describe('plugin principal tokens — one canonical form', () => {
+  it('folds any spelling of a plugin token to its slugged key', () => {
+    for (const spelling of ['plugin/Sales Team/read', 'plugin/sales-team/read', 'Plugin/SALES TEAM/READ', ' plugin/Sales  Team/read ']) {
+      expect(canonicalPluginToken(spelling)).toBe('plugin/sales-team/read');
+      expect(canonicalRoleName(spelling)).toBe('plugin/sales-team/read');
+    }
+    const parsed = parseAccessEntry('plugin/Sales Team/write');
+    expect(parsed.ok && parsed.entry.kind === 'role' ? parsed.entry.role : null).toBe('plugin/sales-team/write');
+  });
+
+  it('is not a plugin token without a name, with a nested name, or with an unknown verb', () => {
+    for (const bad of ['plugin//read', 'plugin/GTM', 'plugin/GTM/foo/read', 'plugin/GTM/delete', 'role/GTM/read']) {
+      expect(canonicalPluginToken(bad)).toBeNull();
+    }
+    // A non-plugin role still canonicalises the old way.
+    expect(canonicalRoleName('  Sales   Team ')).toBe('sales team');
+  });
+
+  it('accepts as a canonical key only what it would itself generate', () => {
+    expect(parsePluginPrincipalKey('plugin/gtm/read')).toEqual({ slug: 'gtm', verb: 'read' });
+    expect(parsePluginPrincipalKey('plugin/gtm/foo/read')).toBeNull();
+    expect(parsePluginPrincipalKey('plugin/GTM/read')).toBeNull(); // not a slug
+    expect(parsePluginPrincipalKey('plugin/gtm/delete')).toBeNull();
+    expect(parsePluginPrincipalKey('plugin//read')).toBeNull();
+  });
+});

package/src/modules/access-model/__tests__/roles-yaml-guard.test.ts

@@ -3,7 +3,12 @@ import {
   isRolesYamlPath,
   assertRolesYamlParsable,
   makeRolesYamlWriteValidator,
+  makeAgentRolesYamlWriteValidator,
+  NEW_ROLE_GUIDANCE,
   RolesYamlInvalidError,
+  RolesYamlNewRoleError,
+  RolesYamlUnknownGroupError,
+  assertKnownGroups,
 } from '../roles-yaml-guard.js';
 
 const KB = 'knowledge-base';
@@ -66,5 +71,131 @@ describe('roles-yaml-guard', () => {
       // Binary write to the roles path is nonsensical → left alone, not parsed.
       expect(() => validate(`${KB}/roles.yaml`, new Uint8Array([1, 2, 3]))).not.toThrow();
     });
+
+    it('lets a role be created — the editor and the App roles service are not held to the agent rule', () => {
+      expect(() => validate(`${KB}/roles.yaml`, `${VALID}  Project Phoenix:\n    - p@x.eu\n`)).not.toThrow();
+    });
+
+    it('claims only the roles.yaml path', () => {
+      expect(validate.appliesTo?.(`${KB}/roles.yaml`)).toBe(true);
+      expect(validate.appliesTo?.(`${KB}/access.md`)).toBe(false);
+    });
+  });
+
+  describe('makeAgentRolesYamlWriteValidator', () => {
+    const CURRENT = `roles:
+  Admin:
+    - a@x.eu
+  Sales:
+    - s@x.eu
+    - t@x.eu
+`;
+
+    /** Run the agent validator against `current` (null = no file), as a promise either way. */
+    const run = (content: string | Uint8Array, current: string | null = CURRENT, path = `${KB}/roles.yaml`) =>
+      Promise.resolve().then(() => makeAgentRolesYamlWriteValidator(KB, async () => current)(path, content));
+
+    it('refuses a role absent from the current file, naming it and redirecting to a group', async () => {
+      const err = await run(`${CURRENT}  Project Phoenix:\n    - p@x.eu\n`).then(
+        () => null,
+        (e: unknown) => e,
+      );
+      expect(err).toBeInstanceOf(RolesYamlNewRoleError);
+      const refusal = err as RolesYamlNewRoleError;
+      expect(refusal.status).toBe(422);
+      expect(refusal.payload).toEqual({ kind: 'roles-yaml-new-role', roleNames: ['Project Phoenix'] });
+      expect(refusal.message).toContain("'Project Phoenix' is not an existing role");
+      expect(refusal.message).toContain(NEW_ROLE_GUIDANCE);
+      expect(NEW_ROLE_GUIDANCE).toMatch(/add people to existing roles, and use a GROUP for a task- or team-scoped set of people/);
+    });
+
+    it('names every created role', async () => {
+      await expect(run(`${CURRENT}  Phoenix:\n    - p@x.eu\n  Onboarding:\n    - o@x.eu\n`)).rejects.toMatchObject({
+        roleNames: ['Phoenix', 'Onboarding'],
+        message: expect.stringContaining("'Phoenix', 'Onboarding' are not existing roles"),
+      });
+    });
+
+    it('passes a write that only changes membership: add, remove, reorder, respell', async () => {
+      await expect(run(`${CURRENT}    - u@x.eu\n`)).resolves.toBeUndefined();
+      await expect(run('roles:\n  Admin:\n    - a@x.eu\n  Sales:\n    - t@x.eu\n')).resolves.toBeUndefined();
+      await expect(run('roles:\n  Sales:\n    - t@x.eu\n    - s@x.eu\n  Admin:\n    - a@x.eu\n')).resolves.toBeUndefined();
+      // Role names are case- and whitespace-insensitive: a respelling is the same role.
+      await expect(run('roles:\n  ADMIN:\n    - a@x.eu\n  sales:\n    - s@x.eu\n')).resolves.toBeUndefined();
+    });
+
+    it('refuses a rename for the created name — a delete plus a create, no special case', async () => {
+      await expect(run('roles:\n  Admin:\n    - a@x.eu\n  Marketing:\n    - s@x.eu\n')).rejects.toMatchObject({
+        name: 'RolesYamlNewRoleError',
+        roleNames: ['Marketing'],
+      });
+    });
+
+    it('still refuses an unparseable candidate first, with the invalid-file error', async () => {
+      await expect(run('roles: [oops')).rejects.toBeInstanceOf(RolesYamlInvalidError);
+    });
+
+    it('fails closed when the current file vouches for no roles (absent, or not a roles mapping)', async () => {
+      await expect(run(VALID, null)).rejects.toMatchObject({ roleNames: ['Admin'] });
+      await expect(run(VALID, 'roles: oops\n')).rejects.toMatchObject({ roleNames: ['Admin'] });
+    });
+
+    it('checks bytes as text, so a binary write cannot carry a role past it', async () => {
+      await expect(run(new TextEncoder().encode(`${CURRENT}  Phoenix:\n    - p@x.eu\n`))).rejects.toBeInstanceOf(
+        RolesYamlNewRoleError,
+      );
+    });
+
+    describe('group entries', () => {
+      const GROUPS = new Map([['platform team', { displayName: 'Platform Team', emails: new Set(['p@x.eu']) }]]);
+      const active = { groups: GROUPS, sourceFile: 'groups.yaml' };
+      const runWithGroups = (content: string, groups: typeof active | null = active, current: string | null = CURRENT) =>
+        Promise.resolve().then(() =>
+          makeAgentRolesYamlWriteValidator(KB, async () => current, async () => groups)(`${KB}/roles.yaml`, content),
+        );
+
+      it('passes an entry naming a known group, in any case or spacing', async () => {
+        await expect(runWithGroups(`${CURRENT}    - group:Platform Team\n`)).resolves.toBeUndefined();
+        await expect(runWithGroups(`${CURRENT}    - group:platform   TEAM\n`)).resolves.toBeUndefined();
+      });
+
+      it('refuses an unknown group with a 422 naming the entry and its role; nothing else is named', async () => {
+        const err = await runWithGroups(`${CURRENT}    - group:Platfrom Team\n    - group:Platform Team\n`).then(
+          () => null,
+          (e: unknown) => e,
+        );
+        expect(err).toBeInstanceOf(RolesYamlUnknownGroupError);
+        const refusal = err as RolesYamlUnknownGroupError;
+        expect(refusal.status).toBe(422);
+        expect(refusal.payload).toEqual({
+          kind: 'roles-yaml-unknown-group',
+          entries: [{ role: 'Sales', entry: 'group:Platfrom Team' }],
+          sourceFile: 'groups.yaml',
+        });
+        expect(refusal.message).toContain("'- group:Platfrom Team' under role 'Sales'");
+        expect(refusal.message).toContain('groups.yaml does not declare');
+      });
+
+      it('leaves an entry already in the file alone, so a retired group cannot block a membership edit', async () => {
+        const current = `${CURRENT}    - group:Retired\n`;
+        await expect(runWithGroups(`${current}    - u@x.eu\n`, active, current)).resolves.toBeUndefined();
+        // The same group added under ANOTHER role is a new entry, and is checked.
+        await expect(
+          runWithGroups('roles:\n  Admin:\n    - a@x.eu\n    - group:Retired\n  Sales:\n    - group:Retired\n', active, current),
+        ).rejects.toMatchObject({ entries: [{ role: 'Admin', entry: 'group:Retired' }] });
+      });
+
+      it('checks nothing when the group source cannot be read', async () => {
+        await expect(runWithGroups(`${CURRENT}    - group:Anything\n`, null)).resolves.toBeUndefined();
+      });
+
+      it('assertKnownGroups is the same check, callable on its own', () => {
+        expect(() => assertKnownGroups(CURRENT, `${CURRENT}    - group:Nope\n`, active)).toThrow(RolesYamlUnknownGroupError);
+      });
+    });
+
+    it('leaves every other path alone', async () => {
+      await expect(run(`${CURRENT}  Phoenix:\n    - p@x.eu\n`, CURRENT, `${KB}/KnowledgeBase/roles.yaml`)).resolves.toBeUndefined();
+    });
   });
 });

package/src/modules/access-model/access-errors.ts

@@ -1,4 +1,5 @@
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { sanitizedPath } from '../../shared/printable.js';
 
 export interface AccessDeniedDetails {
   /** repo-relative POSIX path the caller tried to write */
@@ -7,11 +8,48 @@ export interface AccessDeniedDetails {
   eligibleRoles: string[];
   /** Direct user grants at this path, in `{name, email}` form. */
   eligibleUsers: { name: string; email: string }[];
+  /**
+   * Set when the refusal is the READ-BEFORE-WRITE rule rather than a missing
+   * write grant: the repo-relative path the caller cannot read — the file
+   * itself, or the folder a new file would land in (`''` for the repository
+   * root). Nothing can be created, changed or removed at a place the caller
+   * cannot see, whatever write rules say, so the eligible lists are empty
+   * and the message names the unreadable place instead.
+   */
+  unreadable?: string;
+  /**
+   * What `path` is, when the refuser knows: a folder a move or delete was
+   * judged on, or a file. Read by the tools' `write-denied` mapping to ask
+   * the read gate the right question about proposing the change on a draft —
+   * a folder directly under a root is proposable where a file there is not.
+   * Absent means file.
+   */
+  targetKind?: 'file' | 'dir';
+}
+
+/**
+ * How the read-before-write refusal names the unreadable place. The path is
+ * the caller's own text and goes into a one-line sentence, so a line break
+ * in it is shown, not obeyed.
+ */
+export function unreadablePlaceLabel(repoRelative: string): string {
+  return repoRelative === '' ? 'the top level' : `"${sanitizedPath(repoRelative)}"`;
+}
+
+/**
+ * The sentence a read-before-write refusal ends with. One spelling, shared
+ * with the write-denial mapping and the frontend's friendly rewrite, so the
+ * three never drift.
+ */
+export function unreadableRefusalSentence(repoRelative: string): string {
+  return `You don't have read access to ${unreadablePlaceLabel(repoRelative)}; only what you can read can be created, changed or removed.`;
 }
 
 /**
  * Thrown when a user lacks the `write` permission on a path under the
- * access-control rules in `roles.yaml` + `access.md`.
+ * access-control rules in `roles.yaml` + `access.md` — or, with `unreadable`
+ * set, when they may not READ where the write would land (see
+ * `AccessDeniedDetails.unreadable`).
  *
  * Carries enough detail in the JSON payload for the frontend to render
  * "you don't have permission to write to <path>; eligible: <roles + users>"
@@ -21,20 +59,23 @@ export class AccessDeniedError extends WorkflowDomainError {
   readonly access: AccessDeniedDetails;
 
   constructor(details: AccessDeniedDetails) {
-    const rolesPart = details.eligibleRoles.length
-      ? details.eligibleRoles.join(', ')
-      : 'none';
-    const usersPart = details.eligibleUsers.length
-      ? details.eligibleUsers
-          .map((u) => (u.name ? `${u.name} <${u.email}>` : u.email))
-          .join(', ')
-      : '';
-    const eligible = [rolesPart, usersPart].filter(Boolean).join('; ');
-    super(
-      `You don't have permission to write to "${details.path}". Eligible: ${eligible}.`,
-      403,
-      { access: details },
-    );
+    const lead = `You don't have permission to write to "${details.path}".`;
+    let tail: string;
+    if (details.unreadable !== undefined) {
+      tail = unreadableRefusalSentence(details.unreadable);
+    } else {
+      const rolesPart = details.eligibleRoles.length
+        ? details.eligibleRoles.join(', ')
+        : 'none';
+      const usersPart = details.eligibleUsers.length
+        ? details.eligibleUsers
+            .map((u) => (u.name ? `${u.name} <${u.email}>` : u.email))
+            .join(', ')
+        : '';
+      const eligible = [rolesPart, usersPart].filter(Boolean).join('; ');
+      tail = `Eligible: ${eligible}.`;
+    }
+    super(`${lead} ${tail}`, 403, { access: details });
     this.name = 'AccessDeniedError';
     this.access = details;
   }