@bevel-software/platform-core-backend 0.33.0 → 0.34.0

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

@@ -40,11 +40,10 @@ import type { IAccessControl } from './access-control.interface.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { isTextBytes } from '../workspace/index.js';
 import {
-  type Verb,
   ADMIN_CANONICAL,
   KNOWN_VERBS,
-  ROLE_TOKEN_PREFIX,
   canonicalRoleName,
+  splitPrincipalToken,
   accessFrontmatterExtensionList,
 } from '../access-model/index.js';
 import {
@@ -52,9 +51,8 @@ import {
   spliceGrant,
   validatePrincipal,
   AccessSpliceError,
-  type Principal,
-  type TokenMatch,
 } from '../access-model/index.js';
+import type { Verb, Principal, TokenMatch } from '../access-model/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import {
   canCarryFrontmatter,
@@ -90,23 +88,21 @@ export const ADMIN_ROOT_WRITE_MESSAGE =
  * this target touches the Admin ROLE's write at the repository root — the
  * root folder's `access.md`, or a file directly in the root. The resolver
  * ignores such a rule anyway (the Admin write floor), so writing it would only
- * leave a line that says something the app does not do. A bare token matched
- * `exact` is a group's (or a shadowed name's), never the Admin role. Targets
- * arrive in one spelling: the routes refuse `.` and `..` segments.
+ * leave a line that says something the app does not do. A bare `Admin` is the
+ * role (a bare name is always the role when one exists, and roles.yaml always
+ * declares Admin); `group/Admin` is a group and never the role. Targets arrive
+ * in one spelling: the routes refuse `.` and `..` segments.
  */
 export function removesAdminRootWrite(
   kind: TargetKind,
   repoRelTarget: string,
   principal: Principal,
   verb: Verb | undefined,
-  tokenMatch: TokenMatch,
 ): boolean {
   if (principal.kind !== 'role') return false;
   if (!touchesRootWrite(kind, repoRelTarget, verb)) return false;
-  const canonical = canonicalRoleName(principal.role);
-  const explicit = canonical.startsWith(ROLE_TOKEN_PREFIX);
-  if (!explicit && tokenMatch === 'exact') return false;
-  return (explicit ? canonical.slice(ROLE_TOKEN_PREFIX.length) : canonical) === ADMIN_CANONICAL;
+  const { prefix, name } = splitPrincipalToken(canonicalRoleName(principal.role));
+  return prefix !== 'group' && name === ADMIN_CANONICAL;
 }
 
 /** Whether a mutation on `verb` (absent = every verb) at this target reaches write at the repository root. */
@@ -276,38 +272,40 @@ export class AccessMutationService {
   }
 
   /**
-   * How a REVOKE of `principal` matches file tokens — the shadowing rule:
+   * How a REVOKE of `principal` matches file tokens. `'name'` strips the
+   * principal's explicit spelling AND the bare name (never the other kind's
+   * explicit spelling — see `TokenMatch`); `'exact'` strips the literal
+   * spelling alone. The bare name is stripped only when it is THIS
+   * principal's under role-first precedence:
    *
-   *   - 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.
+   *   - A ROLE (`role/<name>`, or a bare name) owns the bare key unless no
+   *     role of that name exists and a group does — then the bare token is
+   *     the group's, and matching is `'exact'`. A model that fails to load
+   *     keeps it `'exact'` too.
+   *   - A GROUP (`group/<name>`) owns the bare key only while no role of
+   *     that name exists — otherwise the bare token is the role's, and
+   *     matching is `'exact'`. A group that has VANISHED from the active
+   *     source still reads correctly: the question is whether a ROLE holds
+   *     the name. A model that fails to load says nothing about roles, so a
+   *     group revoke then stays `'exact'` rather than risk a role's grant.
    *
    * 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.
+   * who owns the bare key.
    */
   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';
+    const { prefix, name } = splitPrincipalToken(canonicalRoleName(principal.role));
+    const { roles, groups } = await this.accessControl.kbPrincipals(workspaceId);
+    const isRole = roles.some((r) => canonicalRoleName(r) === name);
+    if (prefix === 'group') {
+      // `roles` always carries at least `Everyone` once the model loads.
+      return isRole || roles.length === 0 ? 'exact' : 'name';
+    }
+    const isGroup = groups.some((g) => canonicalRoleName(g) === name);
+    // No roles at all means the model failed to load: stay exact, so a role
+    // revoke never strips a same-named group's bare grant.
+    return roles.length === 0 || (!isRole && isGroup) ? 'exact' : 'name';
   }
 
   /**
@@ -372,11 +370,10 @@ export class AccessMutationService {
     // 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.
+    // `tokenMatch` overrides the derived matching (see revokeTokenMatch).
+    // One production caller: the plugin-links unlink pins `'exact'` for its
+    // `plugin/<Name>/<verb>` tokens. Pin only `'exact'` — a pinned `'name'`
+    // would bypass the guard that never strips across kinds.
     opts?: { tokenMatch?: TokenMatch },
   ): Promise<{ changed: boolean; editPath: string }> {
     void _actingUserEmail; // referenced to satisfy no-unused-vars until something consumes it
@@ -386,8 +383,8 @@ export class AccessMutationService {
     // missing FILE node is a bad target and should surface, not silently no-op
     // — same rule grant() uses.
     const original = await this.readOrEmpty(workspaceId, kind, repoRelTarget, editPath);
-    // Alias-tolerant vs exact-token matching, decided by group shadowing —
-    // see revokeTokenMatch — unless the caller pinned it.
+    // Alias-tolerant vs exact-token matching, decided by who owns the bare
+    // name — see revokeTokenMatch — unless the caller pinned it.
     const tokenMatch = opts?.tokenMatch ?? (await this.revokeTokenMatch(workspaceId, principal));
     let next = original;
     let changed = false;
@@ -409,7 +406,7 @@ export class AccessMutationService {
     // Refused only when an Admin write entry would really go: a whole-row
     // Remove at a root that grants Admin other verbs but no write line (write
     // comes from the floor) strips those verbs as usual.
-    if (writeRemoved && removesAdminRootWrite(kind, repoRelTarget, principal, verb, tokenMatch)) {
+    if (writeRemoved && removesAdminRootWrite(kind, repoRelTarget, principal, verb)) {
       throw adminRootWriteRefusal();
     }
     if (!changed) return { changed: false, editPath };
@@ -457,7 +454,7 @@ export class AccessMutationService {
     repoRelTarget: string,
     principal: Principal,
     verb?: Verb,
-    // Same override as `revoke` — the route pins 'exact' for GROUP principals.
+    // Same override as `revoke`; no production caller passes it here.
     opts?: { tokenMatch?: TokenMatch },
   ): Promise<{ changed: boolean; editPath: string }> {
     this.assertPrincipalSafe(principal);
@@ -465,10 +462,10 @@ export class AccessMutationService {
     const original = await this.readOrEmpty(workspaceId, kind, repoRelTarget, editPath);
 
     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).
+    // Same matching as revoke(): the strip must not swallow a same-named
+    // OTHER principal's grant (`group/<name>` vs the role's bare/`role/`).
     const tokenMatch = opts?.tokenMatch ?? (await this.revokeTokenMatch(workspaceId, principal));
-    if (removesAdminRootWrite(kind, repoRelTarget, principal, verb, tokenMatch)) {
+    if (removesAdminRootWrite(kind, repoRelTarget, principal, verb)) {
       throw adminRootWriteRefusal();
     }
     // A PERSON who is an admin keeps root write through the floor, so a deny
@@ -508,10 +505,8 @@ export class AccessMutationService {
 
     // (3) Assert the deny actually removed effective access on the targeted
     // 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".
+    // the deny above spliced (`tokenMatch` rides along), so a pinned exact
+    // deny is never judged by spellings it did not touch.
     const stillHas = await this.principalStillHasAccess(
       workspaceId,
       kind,

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

@@ -13,6 +13,7 @@ import {
   EVERYONE_CANONICAL,
   KNOWN_VERBS,
   ROLE_TOKEN_PREFIX,
+  GROUP_TOKEN_PREFIX,
   type Verb,
 } from '../access-model/index.js';
 
@@ -51,13 +52,12 @@ export async function resolveAccessView(
   // files). Keyed `u:<email>` / `r:<role>` / `g:<group>` to match the
   // dialog's row keys, so each row can show where its access comes from and
   // which verbs are removable here. Groups get their OWN `g:` namespace: a
-  // group and a role sharing a name are DIFFERENT principals (bare token vs
-  // `role/<name>`), and one shared `r:` entry could only describe one of
-  // them. Each kind resolves through the token spelling that IS that
-  // principal — a group through its bare token (group-first precedence), a
-  // role through its explicit `role/<name>` alias (correct whether or not a
-  // group shadows the name; the built-in `everyone` keeps its bare spelling,
-  // it has no alias). A row whose verbs resolve only via a
+  // group and a role sharing a name are DIFFERENT principals (`group/<name>`
+  // vs the bare name and `role/<name>`), and one shared `r:` entry could only
+  // describe one of them. Each kind resolves through the explicit token that
+  // IS that principal — a group through `group/<name>`, a role through
+  // `role/<name>` (the built-in `everyone` keeps its bare spelling, it has no
+  // alias); the bare spelling counts toward whichever kind owns it. A row whose verbs resolve only via a
   // group/everyone/rescue has no source (the verb is absent) and renders
   // non-actionable. Built over the union of every principal in the four
   // eligible lists (kinded `principals`, with the name-only `roles` list as
@@ -96,9 +96,11 @@ export async function resolveAccessView(
   await Promise.all([
     ...[...collectives.entries()].map(async ([key, p]) => {
       const token =
-        p.kind === 'role' && canonicalRoleName(p.name) !== EVERYONE_CANONICAL
-          ? `${ROLE_TOKEN_PREFIX}${p.name}`
-          : p.name;
+        p.kind === 'group'
+          ? `${GROUP_TOKEN_PREFIX}${p.name}`
+          : p.kind === 'role' && canonicalRoleName(p.name) !== EVERYONE_CANONICAL
+            ? `${ROLE_TOKEN_PREFIX}${p.name}`
+            : p.name;
       const principal = { kind: 'role' as const, role: token };
       const [grants, denied] = await Promise.all([
         accessControl.grantSources(workspaceId, kind, repoRelTarget, principal),

package/src/modules/access/access.routes.ts

@@ -19,6 +19,7 @@ import type {
 } from './access-control.interface.js';
 import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { AuthService, IAccountSwitchGuard } from '../auth/index.js';
 import type { WorkflowService, WorkflowEventBus } from '../workflow/index.js';
@@ -39,7 +40,10 @@ import {
   PLUGIN_TOKEN_PREFIX,
   PLUGIN_TOKEN_VERBS,
   ROLE_TOKEN_PREFIX,
+  GROUP_TOKEN_PREFIX,
+  splitPrincipalToken,
   type PluginTokenVerb,
+  type Principal,
   type Verb,
 } from '../access-model/index.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
@@ -47,7 +51,6 @@ import { emailsInView, holderPrincipals, labelAccountHolders, resolveAccessView
 import type { AccessView, LabelledAccessView } from './access-view.js';
 import { toHttpError as sharedToHttpError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import { RolesAdminService } from './roles-admin.service.js';
-import type { Principal } from '../access-model/index.js';
 import type { Database } from '../database/index.js';
 import { users } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
@@ -91,6 +94,8 @@ export function createAccessRoutes(
   eventBus: WorkflowEventBus,
   db: Database,
   kb: KbContext,
+  /** The composition root's walk, for the roles admin's reference scan. */
+  disk: ITreeWalker,
   /** This deployment's configured admins — the break-glass recovery roster. */
   recoveryAdmins: readonly string[] = [],
 ): express.Router {
@@ -101,6 +106,7 @@ export function createAccessRoutes(
     workspaceService,
     workflowService,
     accessControl,
+    disk,
     kbDirName,
     () => kb.defaultBranch,
     eventBus,
@@ -161,10 +167,10 @@ export function createAccessRoutes(
   /**
    * What the mutation routes accept as a principal. `group` and `plugin`
    * exist only at this boundary: in the access.md entry grammar a group grant
-   * is a bare-name token (bare names resolve GROUP-FIRST, then fall back to
-   * the role) and a plugin grant is the `plugin/<Name>/<verb>` token, so both
-   * are spliced as role-shaped principals — the separate kinds buy validation
-   * against the right namespace and honest 404s.
+   * is the `group/<Name>` token and a plugin grant is the
+   * `plugin/<Name>/<verb>` token, so both are spliced as role-shaped
+   * principals — the separate kinds buy validation against the right
+   * namespace and honest 404s.
    */
   type RoutePrincipal =
     | Principal
@@ -173,14 +179,16 @@ export function createAccessRoutes(
 
   /**
    * The role-shaped principal the splice layer actually writes/matches.
-   *   - group     → its bare name (group-first precedence resolves it).
-   *   - role      → the explicit `role/<Name>` token — the grant route WRITES
-   *                 roles that way from now on (bare role tokens remain
-   *                 read-compatible). The built-in `everyone` stays bare: it
-   *                 is not a roles.yaml role and has no `role/` alias.
+   *   - group     → the explicit `group/<Name>` token. Never the bare name:
+   *                 a bare name is the ROLE whenever one of that name exists,
+   *                 so a bare group grant could silently mean someone else.
+   *   - role      → the explicit `role/<Name>` token. Bare spellings in
+   *                 existing files remain read-compatible. The built-in
+   *                 `everyone` stays bare: it is not a roles.yaml role and
+   *                 has no `role/` alias.
    */
   const asSplicePrincipal = (p: RoutePrincipal): Principal => {
-    if (p.kind === 'group') return { kind: 'role', role: p.group };
+    if (p.kind === 'group') return { kind: 'role', role: `${GROUP_TOKEN_PREFIX}${groupName(p.group)}` };
     // Written with the folder's own casing; `parseAccessEntry` canonicalises
     // the name half to the manifest slug on the way back in.
     if (p.kind === 'plugin') return { kind: 'role', role: `${PLUGIN_TOKEN_PREFIX}${p.plugin.trim()}/${p.verb}` };
@@ -209,6 +217,14 @@ export function createAccessRoutes(
     return p;
   };
 
+  /** A group as the caller named it, without a `group/` prefix it may carry (casing kept). */
+  function groupName(group: string): string {
+    const raw = group.trim();
+    return splitPrincipalToken(canonicalRoleName(raw)).prefix === 'group'
+      ? raw.slice(GROUP_TOKEN_PREFIX.length).trim()
+      : raw;
+  }
+
   // Authentication gate only. Per PLAN §3 the workspace `:id` is a branch
   // identifier — any authenticated user can read its access tree.
   async function requireUser(
@@ -511,8 +527,8 @@ export function createAccessRoutes(
    * signed in — so the dialog can label them; it withholds nobody.
    *
    * A name shared by a group and a role is offered as BOTH — nothing is
-   * withheld: grant precedence resolves the collision (bare token = the
-   * group; the role is written as `role/<Name>`).
+   * withheld: each is written with its own prefix (`group/<Name>`,
+   * `role/<Name>`), so the collision never reaches the file.
    */
   router.get('/workspace/:id/access/suggest', async (req, res) => {
     const user = await requireUser(req, res);
@@ -948,10 +964,10 @@ export function createAccessRoutes(
         // uses — and one the caller may see (`visibleGroups`): a group hidden
         // from the picker is refused here with the same words as one that
         // does not exist, so the grant route is no oracle for group names.
-        // No role-collision refusal: bare tokens resolve GROUP-FIRST, so the
-        // written bare name IS the group.
+        // No role-collision refusal: the grant is written `group/<Name>`,
+        // which always resolves to the group.
         const groups = await visibleGroups(user.email, (await defaultBranchPrincipals()).groups);
-        const canonical = canonicalRoleName(principal.group);
+        const canonical = canonicalRoleName(groupName(principal.group));
         if (!groups.some((g) => canonicalRoleName(g) === canonical)) {
           throw new AccessMutationError(
             `No group named "${principal.group}". Pick an existing group.`,
@@ -976,8 +992,8 @@ export function createAccessRoutes(
           );
         }
       }
-      // Splice shape: group → bare token (group-first precedence); role →
-      // explicit `role/<Name>` token (see asSplicePrincipal).
+      // Splice shape: group → explicit `group/<Name>` token; role → explicit
+      // `role/<Name>` token (see asSplicePrincipal).
       const splicePrincipal = asSplicePrincipal(principal);
 
       const { gatePath } = gateAndEditPaths(kind, repoRelTarget);
@@ -1045,18 +1061,12 @@ export function createAccessRoutes(
     try {
       const mode = (req.body as { mode?: unknown }).mode;
       const { repoRelTarget, kind, principal: routePrincipal } = parseMutationBody(req.body);
-      // A group principal converts straight to the role-shaped bare token —
-      // no existence check (revoking a grant whose group has since vanished
-      // must keep working).
+      // A group principal converts straight to its `group/<Name>` token — no
+      // existence check (revoking a grant whose group has since vanished must
+      // keep working). Which spellings a revoke strips is the mutation
+      // service's call: `group/<Name>` never matches `role/<Name>`, and the
+      // bare name only when no role of that name owns it.
       const principal = asSplicePrincipal(routePrincipal);
-      // GROUP revokes match the EXACT bare token only. The service's own
-      // shadow probe decides exact-vs-name for roles, but it cannot know a
-      // bare token was a GROUP once that group vanished from the active
-      // source — the name would read "unshadowed" and name-level matching
-      // would strip a same-named role's live `role/<Name>` grant. The route
-      // still knows the caller's kind, so it pins the matching here.
-      const revokeOpts =
-        routePrincipal.kind === 'group' ? ({ tokenMatch: 'exact' } as const) : undefined;
       // Optional `verb` scopes ALL three paths to a single verb: a default revoke
       // strips just that verb; remove-from-parent removes just that verb on the
       // ancestor; deny-here denies just that verb at the target. Absent ⇒ the
@@ -1112,7 +1122,7 @@ export function createAccessRoutes(
             );
           }
           // Scope the ancestor revoke to the same verb the user acted on (if any).
-          await mutation.revoke(workspaceId, 'folder', ancestorDir, principal, user.email, verb, revokeOpts);
+          await mutation.revoke(workspaceId, 'folder', ancestorDir, principal, user.email, verb);
         });
 
         accessControl.invalidate(workspaceId);
@@ -1131,7 +1141,7 @@ export function createAccessRoutes(
         await mutation.assertTargetHoldsText(workspaceId, kind, repoRelTarget);
         await withEditLock(workspaceId, branch, gatePath, user, async () => {
           // Scope the deny to the same verb the user acted on (if any).
-          await mutation.denyHere(workspaceId, kind, repoRelTarget, principal, verb, revokeOpts);
+          await mutation.denyHere(workspaceId, kind, repoRelTarget, principal, verb);
         });
         accessControl.invalidate(workspaceId);
         logger('access.revoke.deny-here').info(
@@ -1150,7 +1160,7 @@ export function createAccessRoutes(
       const editPath = gatePath;
       let changed = false;
       await withEditLock(workspaceId, branch, editPath, user, async () => {
-        const r = await mutation.revoke(workspaceId, kind, repoRelTarget, principal, user.email, verb, revokeOpts);
+        const r = await mutation.revoke(workspaceId, kind, repoRelTarget, principal, user.email, verb);
         changed = r.changed;
       });
 
@@ -1247,7 +1257,7 @@ export function createAccessRoutes(
       // surface). The frontend hides the page, but the API must gate too — the
       // roster exposes every role + member email.
       await assertRolesAdmin(user.email);
-      res.json({ roles: await rolesAdmin.getRoster() });
+      res.json({ roles: await rolesAdmin.getRoster(user.email) });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);

package/src/modules/access/groups-admin.routes.ts

@@ -50,9 +50,11 @@ export function createGroupsAdminRoutes(deps: {
   // role assignments) + `groupsHealth` (the broken-source banner marker; a
   // broken MANUAL groups.yaml instead answers 422 with the parse message so
   // the operator sees what to fix).
-  router.get('/admin/groups', requireAdmin, async (_req, res) => {
+  router.get('/admin/groups', requireAdmin, async (req, res) => {
     try {
-      res.json(await groupsAdmin.getRoster());
+      // A read needs no commit attribution: the roster is filtered for the
+      // email `requireAdmin` just checked, with no second user lookup to fail.
+      res.json(await groupsAdmin.getRoster(req.userEmail!));
     } catch (err) {
       sendError(res, err);
     }