@bevel-software/platform-core-backend 0.10.0 → 0.11.0

package/src/modules/access/access-declarations.ts

@@ -4,6 +4,7 @@ import { accessMdPathForFolder } from './access-mutation.service.js';
 import {
   EVERYONE_CANONICAL,
   KNOWN_VERBS,
+  hasAccessFrontmatterExtension,
   parseAccessFile,
   parseOwnAccessEntries,
   type ParsedEntry,
@@ -81,9 +82,11 @@ export class AccessDeclarationsError extends WorkflowDomainError {
   }
 }
 
-/** Node files whose own frontmatter may declare verbs. */
+/** Node files whose own frontmatter may declare verbs — the resolver's shared
+ *  extension set (`ACCESS_FRONTMATTER_EXTENSIONS`), which the reference
+ *  scanner mirrors. */
 function isNodeCandidate(name: string): boolean {
-  return name.endsWith('.md') || name.endsWith('.tool');
+  return hasAccessFrontmatterExtension(name);
 }
 
 /** Walk a workspace-relative path down the file tree; null when absent. */

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

@@ -36,20 +36,26 @@ import path from 'node:path';
 
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from './access-control.interface.js';
-import { type Verb, KNOWN_VERBS } from './access-control.service.js';
+import {
+  type Verb,
+  KNOWN_VERBS,
+  ROLE_TOKEN_PREFIX,
+  canonicalRoleName,
+} from './access-control.service.js';
 import {
   spliceRevoke,
   spliceGrant,
   validatePrincipal,
   AccessSpliceError,
   type Principal,
+  type TokenMatch,
 } from './access-splice.js';
 import { WorkflowDomainError } from '../workflow/workflow.errors.js';
 
 /** Whether the dialog target is a folder (edit folder access.md) or a file (edit node frontmatter). */
 export type TargetKind = 'folder' | 'file';
 
-/** Bad-request-class mutation failure (invalid principal, unknown plugin, lockout). */
+/** Bad-request-class mutation failure (invalid principal, unknown role/group, lockout). */
 export class AccessMutationError extends WorkflowDomainError {
   constructor(message: string, status = 400, payload?: Record<string, unknown>) {
     super(message, status, payload);
@@ -121,6 +127,41 @@ export class AccessMutationService {
     return path.posix.join(this.kbDirName, repoRelative);
   }
 
+  /**
+   * How a REVOKE of `principal` matches file tokens — the shadowing rule:
+   *
+   *   - When a GROUP owns the principal's bare name (group-first precedence),
+   *     the two spellings are DIFFERENT principals: the bare token is the
+   *     group's, `role/<name>` is the role's. Matching is `'exact'` so
+   *     revoking the role never strips the group's bare grant (and revoking
+   *     the group never strips the role's explicit grant).
+   *   - Unshadowed, both spellings resolve to the ROLE (bare falls back to
+   *     it), so matching is `'name'`: revoking the role also removes legacy
+   *     bare spellings — the historical cleanup behavior.
+   *
+   * Judged against THIS workspace's merged principal index (`kbPrincipals` —
+   * the same model the resolver reads), so revoke agrees with resolution on
+   * who owns the bare key. A model that fails to load yields no groups, i.e.
+   * unshadowed — matching degrades to the pre-groups name-level behavior.
+   *
+   * GROUP revokes never take the name-level path: the route passes
+   * `tokenMatch: 'exact'` explicitly (see `revoke`'s `opts`), because this
+   * shadow probe cannot tell a group apart from a role once the group has
+   * VANISHED from the active source — the bare name then reads "unshadowed"
+   * and a name-level group revoke would strip a same-named role's live
+   * `role/<Name>` grant.
+   */
+  private async revokeTokenMatch(workspaceId: string, principal: Principal): Promise<TokenMatch> {
+    if (principal.kind !== 'role') return 'exact'; // user matching ignores the mode
+    const canonical = canonicalRoleName(principal.role);
+    const bare = canonical.startsWith(ROLE_TOKEN_PREFIX)
+      ? canonical.slice(ROLE_TOKEN_PREFIX.length)
+      : canonical;
+    const { groups } = await this.accessControl.kbPrincipals(workspaceId);
+    const shadowed = groups.some((g) => canonicalRoleName(g) === bare);
+    return shadowed ? 'exact' : 'name';
+  }
+
   /**
    * Grant `principal` `verb` on `target`. Adds the principal under exactly this
    * verb and touches no other verb — verbs are independent, so a principal may
@@ -177,26 +218,38 @@ export class AccessMutationService {
     kind: TargetKind,
     repoRelTarget: string,
     principal: Principal,
-    // Kept on the signature: the route supplies it and the upcoming
-    // revoke-vs-deny slice needs the acting user. Not consumed yet.
+    // Kept on the signature: the route supplies it, for attribution / future
+    // per-principal checks. Not consumed yet.
     _actingUserEmail: string,
     // When present, strip ONLY this verb (a per-checkbox toggle in the share UI);
     // absent strips the principal from every verb (the whole-principal Remove).
     verb?: Verb,
+    // `tokenMatch` overrides the shadow-derived matching. The route passes
+    // 'exact' for GROUP principals: a group's grant is its bare token only,
+    // and once the group has vanished the shadow probe can no longer tell it
+    // from a role — name-level matching would then strip a same-named role's
+    // `role/<Name>` grant.
+    opts?: { tokenMatch?: TokenMatch },
   ): Promise<{ changed: boolean; editPath: string }> {
-    void _actingUserEmail; // referenced to satisfy no-unused-vars until Slice 2 consumes it
+    void _actingUserEmail; // referenced to satisfy no-unused-vars until something consumes it
     this.assertPrincipalSafe(principal); // same injection/shape guard grant runs
     const { editPath } = this.fileToEdit(kind, repoRelTarget);
     // Allow a missing target only for a folder (no access.md yet is normal); a
     // missing FILE node is a bad target and should surface, not silently no-op
     // — same rule grant() uses.
     const original = await this.readOrEmpty(workspaceId, editPath, kind === 'folder');
+    // Alias-tolerant vs exact-token matching, decided by group shadowing —
+    // see revokeTokenMatch — unless the caller pinned it.
+    const tokenMatch = opts?.tokenMatch ?? (await this.revokeTokenMatch(workspaceId, principal));
     let next = original;
     let changed = false;
     try {
       const verbsToRevoke = verb ? [verb] : KNOWN_VERBS;
       for (const v of verbsToRevoke) {
-        const r = spliceRevoke(next, v, principal, { target: kind === 'folder' ? 'folder' : 'node' });
+        const r = spliceRevoke(next, v, principal, {
+          target: kind === 'folder' ? 'folder' : 'node',
+          tokenMatch,
+        });
         next = r.text;
         changed = changed || r.changed;
       }
@@ -248,18 +301,26 @@ export class AccessMutationService {
     repoRelTarget: string,
     principal: Principal,
     verb?: Verb,
+    // Same override as `revoke` — the route pins 'exact' for GROUP principals.
+    opts?: { tokenMatch?: TokenMatch },
   ): Promise<{ changed: boolean; editPath: string }> {
     this.assertPrincipalSafe(principal);
     const { editPath, allowScalar } = this.fileToEdit(kind, repoRelTarget);
     const original = await this.readOrEmpty(workspaceId, editPath, kind === 'folder');
 
     const verbsToDeny = verb ? [verb] : KNOWN_VERBS;
+    // Same shadowing-aware matching as revoke(): the strip must not swallow a
+    // same-named OTHER principal's grant (bare = group vs role/<name> = role).
+    const tokenMatch = opts?.tokenMatch ?? (await this.revokeTokenMatch(workspaceId, principal));
     let next = original;
     try {
       for (const v of verbsToDeny) {
         // (1) Strip any same-scope GRANT for this principal so grant-beats-deny
         // can't silently swallow the deny we're about to add.
-        next = spliceRevoke(next, v, principal, { target: kind === 'folder' ? 'folder' : 'node' }).text;
+        next = spliceRevoke(next, v, principal, {
+          target: kind === 'folder' ? 'folder' : 'node',
+          tokenMatch,
+        }).text;
         // (2) Add the deny under the same verb.
         next = spliceGrant(next, v, principal, { allowScalar, deny: true, target: kind === 'folder' ? 'folder' : 'node' }).text;
       }
@@ -277,13 +338,18 @@ export class AccessMutationService {
     this.accessControl.invalidate(workspaceId);
 
     // (3) Assert the deny actually removed effective access on the targeted
-    // verb(s) — else roll back.
+    // verb(s) — else roll back. The check evaluates the SAME token identity
+    // the deny above spliced (`tokenMatch` rides along): with a pinned exact
+    // GROUP deny whose group has vanished, alias-tolerant matching would read
+    // a same-named role's surviving `role/<Name>` grant as the group still
+    // having access — rolling back a fully effective deny as "ineffective".
     const stillHas = await this.principalStillHasAccess(
       workspaceId,
       kind,
       repoRelTarget,
       principal,
       verb,
+      tokenMatch,
     );
     if (stillHas) {
       await this.workspaceService.writeFile(workspaceId, wsRelative, original);
@@ -305,7 +371,7 @@ export class AccessMutationService {
    * access — not just "is there a removable file entry."
    *
    * For a USER, that distinction matters: effective access includes admin-rescue
-   * on `access.md`/`roles.yaml`, plugin membership, and the built-in `everyone` —
+   * on `access.md`/`roles.yaml`, role/group membership, and the built-in `everyone` —
    * none of which `grantSources` reports (it is MECE over file-backed
    * direct/ancestor entries only). So we ask the same `canRead/canWrite/
    * canDownload/canOwner` resolver every real access decision uses; if the
@@ -319,6 +385,10 @@ export class AccessMutationService {
    * ever holds access by being NAMED in a file (no rescue / role-via-role /
    * everyone indirection applies to a role token), so `grantSources` IS its
    * complete effective-access answer (scoped to `verb` when given).
+   * `tokenMatch` keeps the check on the same token identity the preceding
+   * splice used: 'exact' asks `grantSources` to count only the literally
+   * spelled token — see the denyHere call site for why that matters when a
+   * same-named group and role diverge.
    */
   private async principalStillHasAccess(
     workspaceId: string,
@@ -326,6 +396,7 @@ export class AccessMutationService {
     repoRelTarget: string,
     principal: Principal,
     verb?: Verb,
+    tokenMatch?: TokenMatch,
   ): Promise<boolean> {
     if (principal.kind === 'user') {
       const email = principal.email;
@@ -339,10 +410,13 @@ export class AccessMutationService {
       const results = await Promise.all(verbs.map((v) => canOf[v]()));
       return results.some(Boolean);
     }
-    const sources = await this.accessControl.grantSources(workspaceId, kind, repoRelTarget, {
-      kind: 'role',
-      role: principal.role,
-    });
+    const sources = await this.accessControl.grantSources(
+      workspaceId,
+      kind,
+      repoRelTarget,
+      { kind: 'role', role: principal.role },
+      tokenMatch ? { tokenMatch } : undefined,
+    );
     return verb ? sources[verb] !== undefined : Object.keys(sources).length > 0;
   }
 
@@ -351,7 +425,7 @@ export class AccessMutationService {
    * asynchronously in the route (it needs the roles model). Here we only run the
    * cheap injection/shape validation so a malformed principal never reaches the
    * splice. Role-exists-in-roles.yaml is the route's job (so it can offer
-   * "Create Plugin" for an unknown plugin, an admin-only flow).
+   * an honest 404 for an unknown role/group).
    */
   private assertPrincipalSafe(principal: Principal): void {
     try {

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

@@ -122,7 +122,7 @@ export function validatePrincipal(p: Principal): Principal {
   }
   const role = p.role.trim();
   const canonical = canonicalRoleName(role);
-  if (!canonical) throw new AccessSpliceError('plugin grant needs a name');
+  if (!canonical) throw new AccessSpliceError('role grant needs a name');
   if (
     CONTROL_CHARS.test(role) ||
     role.includes('<') ||
@@ -130,24 +130,48 @@ export function validatePrincipal(p: Principal): Principal {
     role.includes(':') ||
     role.includes('#')
   ) {
-    throw new AccessSpliceError(`invalid plugin name: ${JSON.stringify(p.role)}`);
+    throw new AccessSpliceError(`invalid role name: ${JSON.stringify(p.role)}`);
   }
   // `deny` is never a grantee — it's the denial prefix. `everyone` IS grantable
   // (the built-in public role); the access route restricts it to the read verb.
   if (canonical === 'deny') {
-    throw new AccessSpliceError(`'${role}' is a reserved name and cannot be granted as a plugin`);
+    throw new AccessSpliceError(`'${role}' is a reserved name and cannot be granted as a role`);
   }
   const round = parseAccessEntry(role);
   if (!round.ok || round.entry.kind !== 'role' || round.entry.deny) {
-    throw new AccessSpliceError(`plugin grant does not round-trip: ${JSON.stringify(p)}`);
+    throw new AccessSpliceError(`role grant does not round-trip: ${JSON.stringify(p)}`);
   }
   return { kind: 'role', role };
 }
 
-/** True when a parsed entry names the given principal (ignoring deny prefix). */
-function entryMatches(entry: ParsedEntry, p: Principal): boolean {
+/**
+ * How a role-shaped principal's TOKEN is compared against a file entry:
+ *
+ *  - `'exact'`: the entry must carry the SAME spelling — a bare token and a
+ *    `role/<name>` token are DIFFERENT principals (bare = whoever owns the
+ *    bare key under group-first precedence, `role/` = the role). Grants
+ *    always use this: granting the group `X` while `role/X` is present (or
+ *    vice versa) must NOT be treated as already-granted, or the other
+ *    principal silently never receives the grant.
+ *  - `'name'`: both spellings of the name match. Revokes use this ONLY when
+ *    no group shadows the bare name — then both spellings resolve to the
+ *    role, and revoking the role must also remove legacy bare spellings.
+ */
+export type TokenMatch = 'exact' | 'name';
+
+/**
+ * True when a parsed entry names the given principal (ignoring deny prefix).
+ * `tokenMatch` (role-shaped principals only) selects exact-spelling vs
+ * name-level matching — see {@link TokenMatch}.
+ */
+function entryMatches(entry: ParsedEntry, p: Principal, tokenMatch: TokenMatch): boolean {
   if (p.kind === 'user') return entry.kind === 'user' && entry.email === canonicalEmail(p.email);
-  return entry.kind === 'role' && entry.role === canonicalRoleName(p.role);
+  if (entry.kind !== 'role') return false;
+  const canonicalPrincipal = canonicalRoleName(p.role);
+  if (tokenMatch === 'exact') return entry.role === canonicalPrincipal;
+  const strip = (token: string): string =>
+    token.startsWith('role/') ? canonicalRoleName(token.slice('role/'.length)) : token;
+  return strip(entry.role) === strip(canonicalPrincipal);
 }
 
 // ---------------------------------------------------------------------------
@@ -325,10 +349,15 @@ function blockEntries(fm: string[], block: VerbBlock): { entry: ParsedEntry; lin
 // ---------------------------------------------------------------------------
 
 /**
- * Add `principal` under `verb`. Idempotent: if an equivalent entry already
- * exists with the SAME deny-ness (a grant when granting, a deny when denying),
- * returns `changed: false`. Creates the verb key (and the frontmatter fence,
- * for a fresh file) as needed. Preserves everything else byte-for-byte.
+ * Add `principal` under `verb`. Idempotent: if an entry with the EXACT same
+ * token spelling already exists with the SAME deny-ness (a grant when
+ * granting, a deny when denying), returns `changed: false`. Idempotency is
+ * deliberately exact-token, never name-level: a bare token and a `role/`
+ * token are different principals (group-first precedence gives the bare key
+ * to a same-named group), so a bare-`X` GROUP grant must go through even when
+ * `role/X` is present, and vice versa. Creates the verb key (and the
+ * frontmatter fence, for a fresh file) as needed. Preserves everything else
+ * byte-for-byte.
  *
  * `allowScalar` controls whether a fresh single-entry verb may be written in
  * the node-frontmatter scalar form (`owner: Name <email>`). access.md always
@@ -369,9 +398,10 @@ export function spliceGrant(
   const block = findVerbBlock(region.lines, verb);
   const existing = blockEntries(region.lines, block);
 
-  // Idempotency: an entry for this principal with the same deny-ness is already
-  // present (a grant when granting, a deny when denying).
-  if (existing.some((e) => entryMatches(e.entry, principal) && e.entry.deny === deny)) {
+  // Idempotency: an entry for this EXACT token with the same deny-ness is
+  // already present (a grant when granting, a deny when denying). Exact-token
+  // on purpose — see the doc above.
+  if (existing.some((e) => entryMatches(e.entry, principal, 'exact') && e.entry.deny === deny)) {
     return { text, changed: false };
   }
 
@@ -413,14 +443,22 @@ export function spliceGrant(
  * last item empties the verb, the `verb:` key is collapsed to `verb: []` so the
  * file still parses cleanly (the resolver reads `[]` as an empty list).
  * Preserves everything else.
+ *
+ * Token matching for role-shaped principals is `tokenMatch` (default `'name'`:
+ * BOTH spellings — revoking the role removes legacy bare spellings too).
+ * Callers pass `'exact'` when a GROUP shadows the principal's bare name: the
+ * bare token then belongs to the group and the `role/` token to the role, so a
+ * revoke of one must never strip the other (see AccessMutationService, which
+ * derives the flag from the merged principal index).
  */
 export function spliceRevoke(
   text: string,
   verb: Verb,
   rawPrincipal: Principal,
-  opts: { target?: SpliceTarget } = {},
+  opts: { target?: SpliceTarget; tokenMatch?: TokenMatch } = {},
 ): SpliceResult {
   const principal = validatePrincipal(rawPrincipal);
+  const tokenMatch = opts.tokenMatch ?? 'name';
   const f = splitFrontmatter(text);
   if (!f.hasFrontmatter) return { text, changed: false };
 
@@ -430,7 +468,7 @@ export function spliceRevoke(
 
   if (block.inlineScalarValue !== null) {
     const r = parseAccessEntry(block.inlineScalarValue);
-    if (r.ok && entryMatches(r.entry, principal)) {
+    if (r.ok && entryMatches(r.entry, principal, tokenMatch)) {
       // Lone scalar entry removed -> collapse to empty list.
       region.lines[block.keyLine] = `${' '.repeat(block.keyIndent)}${verb}: []`;
       return { text: region.join(), changed: true };
@@ -439,7 +477,7 @@ export function spliceRevoke(
   }
 
   const entries = blockEntries(region.lines, block);
-  const victims = entries.filter((e) => entryMatches(e.entry, principal)).map((e) => e.line);
+  const victims = entries.filter((e) => entryMatches(e.entry, principal, tokenMatch)).map((e) => e.line);
   if (victims.length === 0) return { text, changed: false };
 
   // Delete from the bottom up so earlier indices stay valid.