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

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__/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;
   }

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

@@ -12,7 +12,17 @@
  */
 
 import { parse as parseFullYaml } from 'yaml';
-import { pluginManifestName } from '@bevel-software/platform-shared';
+import {
+  KNOWN_VERBS,
+  VERB_REQUIRES,
+  VERBS_BROADEST_FIRST,
+  pluginManifestName,
+  requiredVerbsFor,
+  sourceVerbsFor,
+  type Verb,
+} from '@bevel-software/platform-shared';
+import { canonicalEmail } from '../../shared/email-identity.js';
+import { scanFrontmatter } from './frontmatter-lines.js';
 import type { GroupsIndex } from './group-files.js';
 
 // ---------------------------------------------------------------------------
@@ -28,44 +38,47 @@ export const ADMIN_CANONICAL = 'admin';
  *
  * `read` controls who may VIEW a path (the file viewer, embed surface, and
  * the agent's read tools). It is **default-deny**: a path with no effective
- * `read:` or `owner:` grant is not readable. To make content public, list the
- * built-in role `everyone` under `read:`.
+ * `read:`, `write:`, `download:` or `owner:` grant is not readable. To make
+ * content public, list the built-in role `everyone` under `read:`.
  *
  * The verbs nest: `owner` is a superset of `read` + `write` + `download`, and
- * `write` is itself a superset of `read` (anyone who can edit can view). An
- * `owner` grant therefore confers all three lower verbs, a `write` grant
- * additionally confers `read`, and `owner` also marks the principal as a
- * contact point for the node (surfaced in the UI so users know who to ask).
- * See `sourceVerbsFor` for how these implications fold into resolution.
+ * `write` and `download` are each a superset of `read` (anyone who can edit, or
+ * who may save a copy, can view). An `owner` grant therefore confers all three
+ * lower verbs, and a `write` or `download` grant additionally confers `read`;
+ * `owner` also marks the principal as a contact point for the node (surfaced in
+ * the UI so users know who to ask). `write` and `download` stay independent of
+ * each other — neither confers the other. Denials run the other way: a verb
+ * denied at a scope takes every verb that presupposes it down with it there.
+ *
+ * The verbs, the dependency graph between them (`VERB_REQUIRES`) and the two
+ * lists derived from it (`sourceVerbsFor`, `requiredVerbsFor`) live in
+ * `@bevel-software/platform-shared` (`workspace/access-verbs.ts`), because the
+ * share dialog folds the same verbs on the client and must never do it by a
+ * second table. They are re-exported here so the grammar remains the one
+ * import for everything on the server side.
  */
-export const KNOWN_VERBS = ['read', 'write', 'download', 'owner'] as const;
-export type Verb = (typeof KNOWN_VERBS)[number];
+export { KNOWN_VERBS, VERB_REQUIRES, VERBS_BROADEST_FIRST, requiredVerbsFor, sourceVerbsFor };
+export type { Verb };
 const KNOWN_VERBS_SET: ReadonlySet<string> = new Set<string>(KNOWN_VERBS);
 export const EVERYONE_CANONICAL = 'everyone';
 /** Display name for the built-in `everyone` role in the share UI. */
 export const EVERYONE_DISPLAY = 'Everyone';
 
-/**
- * Verbs whose entries contribute to resolving `verb`, target verb first.
- * `owner` implies `read`, `write`, and `download`; `write` additionally
- * implies `read`. So resolving `read` folds in `write` and `owner`, resolving
- * `write`/`download` folds in `owner`, and resolving `owner` uses only `owner`.
+/*
+ * How the graph is applied on the server (the table itself is in shared):
+ *
+ *   - `resolveScopes` reads `sourceVerbsFor` for the grants that confer the
+ *     target verb and `requiredVerbsFor` for the denials that strip it. Within
+ *     ONE scope a grant of the verb, or of one that confers it, beats a denial
+ *     of the verb or of one it presupposes.
+ *   - `plugin-principals.ts` reads `sourceVerbsFor` to decide who lands in
+ *     `plugin/<slug>/read`; `personal-spaces.step.ts` reads it to ask whether
+ *     a space is already open.
  *
- * The implication is **grant-only** (see `resolveAtPath`): a superset grant
- * confers the lower verb, but a superset *denial* does not — `deny write` says
- * nothing about `read`, so it never strips a separate read grant. The target
- * verb itself contributes both its grants and its denials.
+ * `download` presupposes `read` because the pair is otherwise a DEAD
+ * combination: the raw-file route read-gates before it download-gates, so a
+ * download-only grant let its holder neither open the file nor save it.
  */
-export function sourceVerbsFor(verb: Verb): Verb[] {
-  switch (verb) {
-    case 'owner':
-      return ['owner'];
-    case 'read':
-      return ['read', 'write', 'owner'];
-    default:
-      return [verb, 'owner'];
-  }
-}
 export const RESERVED_ROLE_NAMES = new Set(['deny', EVERYONE_CANONICAL]);
 export const DENY_PREFIX = 'deny ';
 /**
@@ -301,6 +314,15 @@ export interface RolesIndex {
       pluginName?: string;
       /** For `kind: 'plugin'`: the repo-relative plugin directory, e.g. `Plugins/GTM`. */
       pluginDir?: string;
+      /**
+       * For `kind: 'plugin'`: the role and group keys whose members the
+       * principal was expanded FROM — the non-user entries of the plugin's
+       * own rules, as `byCanonical` keys. `emails` is the flattened roster;
+       * this is its provenance, kept so a question asked of a PRINCIPAL
+       * rather than a person ("what can this team read?") can follow the
+       * team into the plugins that admit it, the way a member's key set does.
+       */
+      sourceKeys?: Set<string>;
     }
   >;
   byEmail: Map<string, Set<string>>;
@@ -485,26 +507,18 @@ export function parseYamlSubset(
 export function extractFrontmatter(
   text: string,
 ): { ok: true; frontmatter: string } | { ok: false; error: string } {
-  const lines = text.split(/\r?\n/);
-  if (lines.length === 0 || lines[0].trim() !== '---') {
-    return { ok: false, error: 'expected `---` on the first line' };
-  }
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') {
-      return { ok: true, frontmatter: lines.slice(1, i).join('\n') };
-    }
+  const scan = scanFrontmatter(text);
+  if (scan.kind === 'none') return { ok: false, error: 'expected `---` on the first line' };
+  if (scan.kind === 'unterminated') {
+    return { ok: false, error: 'unterminated frontmatter — no closing `---` found' };
   }
-  return { ok: false, error: 'unterminated frontmatter — no closing `---` found' };
+  return { ok: true, frontmatter: scan.fm.join('\n') };
 }
 
-/** The text AFTER the closing frontmatter fence ('' when there is no fence). */
+/** The text AFTER the closing frontmatter fence ('' when there is no closed block). */
 export function bodyAfterFrontmatter(text: string): string {
-  const lines = text.split(/\r?\n/);
-  if (lines.length === 0 || lines[0].trim() !== '---') return '';
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') return lines.slice(i + 1).join('\n');
-  }
-  return '';
+  const scan = scanFrontmatter(text);
+  return scan.kind === 'frontmatter' ? scan.post.slice(1).join('\n') : '';
 }
 
 // ---------------------------------------------------------------------------
@@ -517,9 +531,13 @@ export function canonicalRoleName(name: string): string {
   return canonicalPluginToken(name) ?? name.trim().toLowerCase().replace(/\s+/g, ' ');
 }
 
-export function canonicalEmail(email: string): string {
-  return email.trim().toLowerCase();
-}
+/**
+ * Re-exported from `shared/email-identity.ts`, where it lives beside the
+ * identity HASH that must normalise identically. The grammar keeps the name
+ * because its parsers and splices read as prose with it, and its own callers
+ * keep importing it from here.
+ */
+export { canonicalEmail };
 
 // ---------------------------------------------------------------------------
 // Entry parser
@@ -966,6 +984,25 @@ function verbValuesNeedFullYaml(root: unknown): boolean {
   return false;
 }
 
+/**
+ * Whether an access.md's FRONTMATTER says the file is private: its `read`
+ * denies `everyone` and names nobody but people — the shape the personal
+ * template seeds (`deny everyone` and the owner), and what a person writes
+ * to keep a plugin to a few named colleagues. A role or group beside the
+ * denial is a roster, not a private list; no frontmatter, or a `read` that
+ * never mentions `everyone`, is not a statement of privacy at all (what such
+ * a file admits is whatever the folder above it says). The frontmatter
+ * alone is read on purpose: it is the block a reader sees first and the one
+ * the Library's "Private" mark reflects, so the mark and the file agree.
+ */
+export function isPrivateAccessMd(text: string): boolean {
+  const own = parseOwnAccessEntries(text);
+  if (!own) return false;
+  const deniesEveryone = (e: ParsedEntry) => e.kind === 'role' && e.deny && e.role === EVERYONE_CANONICAL;
+  if (!own.read.some(deniesEveryone)) return false;
+  return own.read.every((e) => deniesEveryone(e) || (e.kind === 'user' && !e.deny));
+}
+
 /**
  * Parse the access verbs a node file declares in its own YAML frontmatter.
  * Returns the per-verb entry lists, or null when the file has no frontmatter

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

@@ -34,6 +34,8 @@ import {
   canonicalRoleName,
   accessMdDeclaresBodyRules,
 } from './access-grammar.js';
+import { freshAccessMd } from './access-template.js';
+import { scanFrontmatter } from './frontmatter-lines.js';
 
 /**
  * Which rule block a mutation edits.
@@ -195,24 +197,14 @@ interface Frontmatter {
  * grant into a fresh file synthesise one.
  */
 function splitFrontmatter(text: string): Frontmatter & { hasFrontmatter: boolean } {
-  const eol = text.includes('\r\n') ? '\r\n' : '\n';
-  const lines = text.split(/\r?\n/);
-  // Opening fence must be the very first line.
-  if (lines[0]?.trim() !== '---') {
-    return { pre: [], fm: [], post: lines, eol, hasFrontmatter: false };
+  const scan = scanFrontmatter(text);
+  if (scan.kind === 'unterminated') {
+    throw new AccessSpliceError('unterminated frontmatter — no closing `---`');
   }
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') {
-      return {
-        pre: lines.slice(0, 1), // the opening ---
-        fm: lines.slice(1, i),
-        post: lines.slice(i), // closing --- onward (body preserved)
-        eol,
-        hasFrontmatter: true,
-      };
-    }
+  if (scan.kind === 'none') {
+    return { pre: [], fm: [], post: scan.lines, eol: scan.eol, hasFrontmatter: false };
   }
-  throw new AccessSpliceError('unterminated frontmatter — no closing `---`');
+  return { pre: scan.open, fm: scan.fm, post: scan.post, eol: scan.eol, hasFrontmatter: true };
 }
 
 function joinFrontmatter(f: Frontmatter): string {
@@ -383,8 +375,16 @@ export function spliceGrant(
   const f = splitFrontmatter(text);
 
   if (!f.hasFrontmatter) {
-    // Fresh file — synthesise a minimal frontmatter block, keep any body lines
-    // the caller passed (usually none for a new access.md).
+    // A fresh FOLDER access.md gets the platform's two-block shape, the grant
+    // in the body and the explanation of both blocks in place — the same
+    // file a person would find beside a plugin, so every generated
+    // access.md teaches the same rules. (Only for an EMPTY file: text
+    // without a frontmatter is the legacy single-block format, kept as it is.)
+    if (opts.target === 'folder' && text.trim() === '') {
+      return { text: freshAccessMd(`${verb}:${f.eol}  - ${renderEntry(principal, deny)}`, f.eol), changed: true };
+    }
+    // Fresh node frontmatter — synthesise a minimal block, keep any body
+    // lines the caller passed.
     const itemLine = opts.allowScalar
       ? `${verb}: ${renderEntry(principal, deny)}`
       : `${verb}:${f.eol}  - ${renderEntry(principal, deny)}`;