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

package/dist/modules/access/access-control.service.js

@@ -4,6 +4,11 @@ import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
 import { AccessConfigError } from './access-errors.js';
+// NOTE: deliberate module cycle — group-files.ts imports this module's parsing
+// primitives. Benign: both sides only dereference the other's exports inside
+// function bodies, never at module-evaluation time.
+import { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, } from './group-files.js';
+import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-sync-bot.js';
 const execFileAsync = promisify(execFile);
 /**
  * Read many objects from a git repo in ONE `git cat-file --batch` process.
@@ -119,6 +124,24 @@ export function sourceVerbsFor(verb) {
 }
 export const RESERVED_ROLE_NAMES = new Set(['deny', EVERYONE_CANONICAL]);
 export const DENY_PREFIX = 'deny ';
+/**
+ * Member-entry prefix in roles.yaml that references a GROUP instead of an
+ * email: `- group:Engineering`. Explicit on purpose — membership kind is
+ * never guessed from string shape. Valid on EVERY role including Admin, with
+ * one kept invariant (see `parseRolesYaml`): Admin must always retain at
+ * least one direct email member, so a misconfigured or unreachable directory
+ * can never leave the deployment without a rescuable admin.
+ */
+export const GROUP_REF_PREFIX = 'group:';
+/**
+ * Explicit ROLE token prefix in access.md entries: `role/<Name>` resolves to
+ * the roles.yaml role only, never a group. A BARE name resolves GROUP-FIRST
+ * and falls back to the role — so `role/` is the escape hatch when a group
+ * shares the role's name. The prefix is reserved in the group name-safety
+ * rules (a group may never be named `role/...`), and every role is also
+ * registered in the principal index under its `role/<canonical>` alias.
+ */
+export const ROLE_TOKEN_PREFIX = 'role/';
 export const USER_REF_REGEX = /^(.+?)\s+<\s*([^<>\s]+@[^<>\s]+)\s*>\s*$/;
 export const EMAIL_REGEX = /^[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+$/;
 function emptyEntries() {
@@ -130,13 +153,33 @@ function emptyEntries() {
 export function isAccessMdPath(p) {
     return p === 'access.md' || p.endsWith('/access.md');
 }
+/**
+ * Extensions of node files whose OWN `---` frontmatter can carry access verbs
+ * the resolver enforces (`readOwnEntries` → `parseOwnAccessEntries`). The
+ * SINGLE source of truth for every surface that enumerates candidate files —
+ * the access-declarations scan and the shared `KbReferenceScanner` (which
+ * must scan/rewrite the same set, or a rename strands a live `.tool`
+ * frontmatter grant). `access.md` is covered by `.md`.
+ */
+export const ACCESS_FRONTMATTER_EXTENSIONS = ['.md', '.tool'];
+/** True when `p` is a file the resolver reads access frontmatter from. */
+export function hasAccessFrontmatterExtension(p) {
+    return ACCESS_FRONTMATTER_EXTENSIONS.some((ext) => p.endsWith(ext));
+}
 function isBuiltInRole(canonicalRole) {
     return canonicalRole === EVERYONE_CANONICAL;
 }
 function roleKnown(roles, canonicalRole) {
     return roles.byCanonical.has(canonicalRole) || isBuiltInRole(canonicalRole);
 }
-function stripComment(line) {
+/**
+ * Strip a trailing `# comment` the way the YAML-subset tokeniser reads a
+ * line: a `#` at the start (after only whitespace) or preceded by whitespace
+ * begins a comment. Exported so the reference scanner matches tokens against
+ * the SAME comment rule the resolver parses with (a `- GTM Team  # sales`
+ * entry is the token `GTM Team`, never `GTM Team # sales`).
+ */
+export function stripComment(line) {
     let inWs = true;
     for (let i = 0; i < line.length; i++) {
         const ch = line[i];
@@ -148,9 +191,14 @@ function stripComment(line) {
     }
     return line;
 }
-function tokenise(text) {
+function tokenise(text, opts) {
     const lines = text.split(/\r?\n/);
     const tokens = [];
+    // Tolerated blank keys are uniquified as runs of spaces so a SECOND blank
+    // key doesn't trip the duplicate-key check (which would retire every valid
+    // group after it). All-whitespace keys still canonicalize to '' downstream,
+    // so the entry-level "empty group name — skipped" handling sees them all.
+    let blankKeySeq = 0;
     for (let i = 0; i < lines.length; i++) {
         const stripped = stripComment(lines[i]).replace(/\s+$/, '');
         if (!stripped.trim())
@@ -168,16 +216,24 @@ function tokenise(text) {
         if (colonIdx < 0) {
             return { ok: false, error: `line ${lineNum}: expected 'key:' or '- value' but got '${content}'` };
         }
-        const key = content.slice(0, colonIdx).trim();
+        let key = content.slice(0, colonIdx).trim();
         const valuePart = content.slice(colonIdx + 1).trim();
-        if (!key)
-            return { ok: false, error: `line ${lineNum}: empty mapping key` };
+        // An empty key is normally a hard error (roles.yaml/access.md want loud
+        // failures), but a parser with ENTRY-level forgiveness (the group files:
+        // one bad entry must not retire every other group) keeps it as a
+        // whitespace key for its own skip-with-warning handling.
+        if (!key) {
+            if (!opts?.tolerateEmptyKeys) {
+                return { ok: false, error: `line ${lineNum}: empty mapping key` };
+            }
+            key = ' '.repeat(++blankKeySeq);
+        }
         tokens.push({ lineNum, indent, kind: 'kv', key, value: valuePart });
     }
     return { ok: true, tokens };
 }
-export function parseYamlSubset(text) {
-    const tok = tokenise(text);
+export function parseYamlSubset(text, opts) {
+    const tok = tokenise(text, opts);
     if (!tok.ok)
         return tok;
     if (tok.tokens.length === 0)
@@ -309,9 +365,18 @@ export function parseAccessEntry(raw) {
             error: `entry '${body}' looks like a user reference but doesn't match 'Name <email>' shape`,
         };
     }
-    const role = canonicalRoleName(body);
+    let role = canonicalRoleName(body);
     if (!role)
         return { ok: false, error: `empty role name in entry '${raw}'` };
+    // Explicit role token: normalize `role/ <Name>` spacing so the canonical
+    // form is always `role/<canonicalName>` — the exact alias key the principal
+    // index registers for every role.
+    if (role.startsWith(ROLE_TOKEN_PREFIX)) {
+        const suffix = canonicalRoleName(role.slice(ROLE_TOKEN_PREFIX.length));
+        if (!suffix)
+            return { ok: false, error: `entry '${body}' names no role after '${ROLE_TOKEN_PREFIX}'` };
+        role = `${ROLE_TOKEN_PREFIX}${suffix}`;
+    }
     return { ok: true, entry: { kind: 'role', role, displayRole: body, deny } };
 }
 // ---------------------------------------------------------------------------
@@ -344,6 +409,10 @@ export function parseRolesYaml(text) {
             errors.push(`roles.yaml: role '${displayName}' uses reserved name '${canonical}' — this token has special meaning in access entries and cannot be a roles.yaml role`);
             continue;
         }
+        if (canonical.startsWith(ROLE_TOKEN_PREFIX)) {
+            errors.push(`roles.yaml: role '${displayName}' starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix — that spelling is the explicit role token in access entries`);
+            continue;
+        }
         if (index.byCanonical.has(canonical)) {
             const prev = index.byCanonical.get(canonical).displayName;
             errors.push(`roles.yaml: role '${displayName}' canonicalises to '${canonical}', which is already declared as '${prev}'`);
@@ -354,11 +423,26 @@ export function parseRolesYaml(text) {
             continue;
         }
         const emails = new Set();
+        const groupRefs = new Set();
         for (const rawEmail of value) {
             if (typeof rawEmail !== 'string') {
                 errors.push(`roles.yaml: role '${displayName}' has a non-string entry`);
                 continue;
             }
+            // `- group:<Name>` assigns the role to a whole group (expanded against
+            // the active group source by `mergeGroupsIntoRoles`). Allowed on every
+            // role, Admin included — the Admin invariant below only demands at
+            // least one DIRECT email member so a broken directory can never leave
+            // the deployment adminless.
+            if (rawEmail.trim().toLowerCase().startsWith(GROUP_REF_PREFIX)) {
+                const refName = canonicalRoleName(rawEmail.trim().slice(GROUP_REF_PREFIX.length));
+                if (!refName) {
+                    errors.push(`roles.yaml: role '${displayName}' has an empty group reference '${rawEmail}'`);
+                    continue;
+                }
+                groupRefs.add(refName);
+                continue;
+            }
             const email = canonicalEmail(rawEmail);
             if (!EMAIL_REGEX.test(email)) {
                 errors.push(`roles.yaml: role '${displayName}' has malformed email '${rawEmail}'`);
@@ -372,18 +456,158 @@ export function parseRolesYaml(text) {
             }
             set.add(canonical);
         }
-        index.byCanonical.set(canonical, { displayName: displayName.trim(), emails });
+        index.byCanonical.set(canonical, { displayName: displayName.trim(), emails, groupRefs });
     }
     if (!index.byCanonical.has(ADMIN_CANONICAL)) {
         errors.push(`roles.yaml: must declare at least one 'Admin' role`);
     }
     else if (index.byCanonical.get(ADMIN_CANONICAL).emails.size === 0) {
-        errors.push(`roles.yaml: 'Admin' role has no emails`);
+        // The kept invariant: Admin may reference groups, but must ALWAYS retain
+        // at least one direct email member — the rescue story requires an admin
+        // whose membership does not depend on a reachable, well-configured
+        // directory. A group-only Admin is as hard an error as an adminless one.
+        errors.push(`roles.yaml: 'Admin' role has no direct email members — Admin must keep at least one individual email (group references alone are not enough)`);
     }
     if (errors.length)
         return { ok: false, errors };
     return { ok: true, index };
 }
+/**
+ * Merge the active group source into the principal index and expand role →
+ * group assignments. Mutates `index` in place; returns human-readable
+ * warnings (callers log them — nothing here ever throws, because group
+ * problems must degrade, not brick access resolution).
+ *
+ * Rules (the grant-grammar precedence):
+ *   - Every role is ALSO registered under its explicit `role/<canonical>`
+ *     alias — the token that always resolves to the role.
+ *   - A BARE name resolves GROUP-FIRST: when a group's canonical name
+ *     collides with a role's, the bare key resolves to the GROUP (warned);
+ *     the role stays reachable via `role/<canonical>`.
+ *   - Role `group:<Name>` refs — Admin's included — expand against the
+ *     merged groups; an unknown ref contributes nothing (warned).
+ *   - `byEmail` is rebuilt so each member holds exactly the tokens that
+ *     resolve to a principal they belong to (bare + `role/` alias for roles,
+ *     bare for groups).
+ */
+export function mergeGroupsIntoRoles(index, groups, sourceFile) {
+    const warnings = [];
+    // Snapshot before any group lands: at this point the index holds roles only.
+    const roleRecords = new Map(index.byCanonical);
+    // 1. Expand role → group assignments (Admin included — its safety net is
+    //    the parse-time "at least one direct email" invariant, not a merge skip).
+    for (const [, principal] of roleRecords) {
+        if (!principal.groupRefs?.size)
+            continue;
+        for (const ref of principal.groupRefs) {
+            const group = groups.get(ref);
+            if (!group) {
+                warnings.push(`roles.yaml: role '${principal.displayName}' references unknown group '${ref}' — reference ignored`);
+                continue;
+            }
+            for (const email of group.emails)
+                principal.emails.add(email);
+        }
+    }
+    // 2. Bare-name precedence: groups win the bare token; the role keeps its
+    //    `role/<canonical>` alias registered below.
+    for (const [canonical, def] of groups) {
+        if (roleRecords.has(canonical)) {
+            warnings.push(`${sourceFile}: group '${def.displayName}' shares its name with a role — the bare name now resolves to the GROUP; use '${ROLE_TOKEN_PREFIX}${canonical}' to reference the role`);
+        }
+        index.byCanonical.set(canonical, {
+            displayName: def.displayName,
+            emails: new Set(def.emails),
+            kind: 'group',
+        });
+    }
+    // 3. Explicit `role/<canonical>` alias for every role (same record — the
+    //    alias and the bare key, when the role still owns it, stay in lockstep).
+    for (const [canonical, principal] of roleRecords) {
+        principal.kind = 'role';
+        index.byCanonical.set(`${ROLE_TOKEN_PREFIX}${canonical}`, principal);
+    }
+    // 4. Rebuild the email → tokens map from the final index so membership
+    //    reflects the post-precedence keys (a collided role's members no longer
+    //    hold the bare token unless the group also contains them).
+    index.byEmail.clear();
+    for (const [key, principal] of index.byCanonical) {
+        for (const email of principal.emails) {
+            let set = index.byEmail.get(email);
+            if (!set) {
+                set = new Set();
+                index.byEmail.set(email, set);
+            }
+            set.add(key);
+        }
+    }
+    return warnings;
+}
+/** True for the errno codes that mean "the file genuinely is not there". */
+function isAbsenceError(err) {
+    const code = err?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+/**
+ * Load the ACTIVE group source through `read` (working tree or at-ref — the
+ * caller supplies the reader, so both model loaders share one mode rule):
+ * `synced-groups.yaml` existing → IdP mode (groups.yaml ignored entirely,
+ * even when the synced file is empty or malformed — falling back would
+ * resurrect retired manual groups); otherwise `groups.yaml` → manual mode.
+ *
+ * `read` returns null for a genuinely-absent file and may THROW for any other
+ * failure. Only ENOENT/ENOTDIR count as absent (the caller may also whitelist
+ * them into null); every other read error — notably a non-absence error on
+ * `synced-groups.yaml` — is treated as a BROKEN source: no groups, no
+ * fallback to the manual file (falling back would resurrect retired groups),
+ * and an `ok: false` health marker. Structural parse failures degrade the
+ * same way; this function never throws.
+ */
+export async function loadActiveGroups(read) {
+    const broken = (file, reason) => ({
+        groups: new Map(),
+        sourceFile: file,
+        warnings: [],
+        health: { ok: false, file, reason },
+    });
+    let syncedText;
+    try {
+        syncedText = await read(SYNCED_GROUPS_YAML);
+    }
+    catch (err) {
+        if (isAbsenceError(err)) {
+            syncedText = null;
+        }
+        else {
+            // A non-absence read error on the SYNCED source must NOT fall back to
+            // groups.yaml — the synced file may exist and its manual predecessor is
+            // retired. Broken-groups instead.
+            return broken(SYNCED_GROUPS_YAML, err instanceof Error ? err.message : String(err));
+        }
+    }
+    const sourceFile = syncedText !== null ? SYNCED_GROUPS_YAML : GROUPS_YAML;
+    let text;
+    if (syncedText !== null) {
+        text = syncedText;
+    }
+    else {
+        try {
+            text = await read(GROUPS_YAML);
+        }
+        catch (err) {
+            if (isAbsenceError(err))
+                text = null;
+            else
+                return broken(GROUPS_YAML, err instanceof Error ? err.message : String(err));
+        }
+    }
+    if (text === null)
+        return { groups: new Map(), sourceFile, warnings: [], health: { ok: true } };
+    const parsed = parseGroupsFile(text, sourceFile);
+    if (!parsed.ok)
+        return broken(sourceFile, parsed.errors.join('; '));
+    return { groups: parsed.groups, sourceFile, warnings: parsed.warnings, health: { ok: true } };
+}
 /**
  * Does an `access.md` body declare access rules — i.e. is the file in the NEW
  * (body-governs-the-folder) format?
@@ -630,7 +854,10 @@ function isAdminEmail(model, email) {
     if (model.deploymentOwners.has(email))
         return true;
     const roles = model.roles.byEmail.get(email);
-    return !!roles && roles.has(ADMIN_CANONICAL);
+    // Check the explicit `role/admin` alias, NOT the bare token: bare-name
+    // precedence is group-first, so a group that happens to be named "Admin"
+    // owns the bare key — and its members must never inherit the capability.
+    return !!roles && roles.has(`${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`);
 }
 /**
  * Resolve whether `userEmail` has `verb` on `relativePath`.
@@ -737,7 +964,7 @@ function scopeToGrantSource(scope, kind, relativePath) {
  * returning the WHOLE list of removable entries rather than just the winner.
  *
  * Only the principal's OWN named entry yields a source — a `user` by their email,
- * a `role` by its role token. A grant that reaches the user via a plugin they
+ * a `role` by its role token. A grant that reaches the user via a group/role they
  * belong to, the built-in `everyone`, or admin-rescue is NOT their entry, so it
  * never adds a source (the group/role shows as its own row instead). The list is:
  *   - `[]` (verb omitted by the caller) when the principal effectively holds no
@@ -753,19 +980,48 @@ function scopeToGrantSource(scope, kind, relativePath) {
  * under closest-wins), and the revoke flow needs the inherited remainder that
  * survives removing the direct entry. A group/everyone grant at some scope does
  * not add a source AND does not hide a farther own-entry the principal is named
- * in (removing it is still meaningful if the plugin grant is later removed).
+ * in (removing it is still meaningful if the group/role grant is later removed).
  */
-function resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal, fileOwn) {
+function resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal, fileOwn, tokenMatch) {
     const scopes = resolveScopes(model, verb, relativePath, fileOwn);
     const out = [];
     if (principal.kind === 'role') {
-        const role = canonicalRoleName(principal.role);
+        // A named principal can be spelled two ways in a file: the bare token and
+        // the explicit `role/<name>` token. WHICH spellings are THIS principal's
+        // entries depends on who owns the bare key in the merged index:
+        //
+        //   - UNSHADOWED (no group named `<bare>`): both spellings resolve to the
+        //     role, so both count — a grant under either adds a source; a deny
+        //     under either cuts off farther grants. (The revoke splice strips both
+        //     spellings in this case too, so classification and removal agree.)
+        //   - SHADOWED (a group owns the bare key): the spellings are DIFFERENT
+        //     principals. A bare-token principal is the GROUP — only bare entries
+        //     are its own; a `role/`-token principal is the ROLE — only `role/`
+        //     entries are its own. Counting the other spelling would attribute a
+        //     shadowed bare token to the role (hiding a real `role/<name>`
+        //     ancestor grant and making its revoke a false no-op), or vice versa.
+        //
+        //   - PINNED EXACT (`tokenMatch: 'exact'`): only the literally-spelled
+        //     token is this principal's entry, shadowing notwithstanding. The
+        //     caller pinned the same identity into the splice it is checking —
+        //     a GROUP whose group has VANISHED reads "unshadowed" here, and the
+        //     alias-tolerant pair would then attribute a same-named role's
+        //     surviving `role/<name>` grant to the group.
+        const canonical = canonicalRoleName(principal.role);
+        const explicit = canonical.startsWith(ROLE_TOKEN_PREFIX);
+        const bare = explicit ? canonical.slice(ROLE_TOKEN_PREFIX.length) : canonical;
+        const shadowed = model.roles.byCanonical.get(bare)?.kind === 'group';
+        const tokens = tokenMatch === 'exact' || shadowed
+            ? [explicit ? `${ROLE_TOKEN_PREFIX}${bare}` : bare]
+            : [bare, `${ROLE_TOKEN_PREFIX}${bare}`];
         for (const scope of scopes) {
-            const s = scope.byRole.get(role);
-            if (s === 'denied')
-                break; // a closer deny of this role cuts off farther grants
-            if (s === 'grant')
+            const states = tokens.map((t) => scope.byRole.get(t));
+            if (states.includes('grant')) {
                 out.push(scopeToGrantSource(scope, kind, relativePath));
+                continue;
+            }
+            if (states.includes('denied'))
+                break; // a closer deny cuts off farther grants
         }
         return out;
     }
@@ -854,12 +1110,28 @@ function canReadResolved(model, userEmail, relativePath, fileOwn) {
 }
 function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
     const { byRole, byEmail } = resolveAtPath(model, verb, relativePath, fileOwn);
-    const roleSet = new Set();
+    // (kind, display name) → one entry. The `byRole` keys are the merged
+    // index's canonical tokens exactly as granted (bare, or the
+    // `role/<canonical>` alias); the `byCanonical` record a key hits carries
+    // its kind — a `role/` alias always hits the role record, a bare key hits
+    // whichever principal owns it under group-first precedence. A token with no
+    // record (the built-in `everyone`, or a grant naming a since-vanished
+    // principal) degrades to 'role', the pre-groups display. When one display
+    // name is granted as BOTH (a role via its `role/` alias plus a same-named
+    // group via the bare token) BOTH entries survive — they are DIFFERENT
+    // principals, and collapsing them to one would hide the role's live
+    // `role/<name>` grant from every consumer of the eligible list.
+    const byIdentity = new Map();
+    const addPrincipal = (name, kind) => {
+        const key = `${kind}\0${name.toLowerCase()}`;
+        if (!byIdentity.has(key))
+            byIdentity.set(key, { name, kind });
+    };
     for (const [canonical, state] of byRole) {
         if (state !== 'grant')
             continue;
-        const role = model.roles.byCanonical.get(canonical);
-        roleSet.add(role ? role.displayName : canonical);
+        const record = model.roles.byCanonical.get(canonical);
+        addPrincipal(record ? record.displayName : canonical, record?.kind ?? 'role');
     }
     // Mirror the admin overrides applied in `hasPermissionResolved`: write on
     // `roles.yaml` and on any `access.md` is granted to Admin even if the
@@ -868,10 +1140,17 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
     // access.md (it'd say "restricted to no one" when Admin is the answer).
     if (verb === 'write' &&
         (relativePath === 'roles.yaml' || isAccessMdPath(relativePath))) {
-        const adminRole = model.roles.byCanonical.get(ADMIN_CANONICAL);
-        roleSet.add(adminRole ? adminRole.displayName : ADMIN_CANONICAL);
-    }
-    const roles = [...roleSet].sort();
+        // Look the Admin ROLE up via its explicit alias — the bare key may be
+        // owned by a same-named group under group-first precedence. The override
+        // is the ROLE's capability, so the row's kind is 'role' regardless.
+        const adminRole = model.roles.byCanonical.get(`${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`);
+        addPrincipal(adminRole ? adminRole.displayName : ADMIN_CANONICAL, 'role');
+    }
+    const principals = [...byIdentity.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0);
+    // Legacy name-only list, kind erased — kept for the many consumers that
+    // only ever render names (banners, contact lines, PR-routing messages).
+    // De-duplicated: a name granted as both group and role appears once here.
+    const roles = [...new Set(principals.map((p) => p.name))];
     const users = [];
     for (const [email, state] of byEmail) {
         if (state !== 'grant')
@@ -879,7 +1158,7 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
         users.push({ name: '', email });
     }
     users.sort((a, b) => a.email.localeCompare(b.email));
-    return { roles, users };
+    return { principals, roles, users };
 }
 /**
  * Expand the eligible-writer set to the underlying emails.
@@ -1017,27 +1296,10 @@ export class AccessControlService {
         const parsed = parseRolesYaml(text);
         return parsed.ok ? { ok: true } : { ok: false, errors: parsed.errors };
     }
-    /**
-     * Advisory scan of folder `access.md` files for references to a role (by
-     * canonical name). See `IAccessControl.referencesToRole` — undercounts node
-     * frontmatter by design; powers the delete warning only, never the rename
-     * gate.
-     */
-    async referencesToRole(workspaceId, canonicalRole) {
-        const model = await this.loadModel(workspaceId);
-        const out = [];
-        for (const file of model.accessFilesByDir.values()) {
-            for (const verb of KNOWN_VERBS) {
-                for (const entry of file.entries[verb]) {
-                    if (entry.kind === 'role' && entry.role === canonicalRole) {
-                        out.push({ path: file.path, verb });
-                    }
-                }
-            }
-        }
-        return out;
-    }
     async canWrite(workspaceId, userEmail, relativePath) {
+        const machineOwned = this.machineOwnedWriteRule(userEmail, relativePath);
+        if (machineOwned !== null)
+            return machineOwned;
         const model = await this.loadModel(workspaceId);
         const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
         return hasPermissionResolved(model, 'write', userEmail, relativePath, own);
@@ -1067,7 +1329,8 @@ export class AccessControlService {
         const owns = await Promise.all(relativePaths.map((p) => this.cachedOwnEntries(workspaceId, repoDir, p)));
         const result = new Map();
         relativePaths.forEach((p, i) => {
-            result.set(p, hasPermissionResolved(model, 'write', userEmail, p, owns[i]));
+            const machineOwned = this.machineOwnedWriteRule(userEmail, p);
+            result.set(p, machineOwned ?? hasPermissionResolved(model, 'write', userEmail, p, owns[i]));
         });
         return result;
     }
@@ -1109,10 +1372,10 @@ export class AccessControlService {
         // and the role/user lists are meaningless. Otherwise return the explicit
         // reader set; it may be empty for a default-denied path with no grants.
         if (canEveryoneReadResolved(model, relativePath, own)) {
-            return { restricted: false, roles: [], users: [] };
+            return { restricted: false, principals: [], roles: [], users: [] };
         }
-        const { roles, users } = eligibleHoldersResolved(model, 'read', relativePath, own);
-        return { restricted: true, roles, users };
+        const { principals, roles, users } = eligibleHoldersResolved(model, 'read', relativePath, own);
+        return { restricted: true, principals, roles, users };
     }
     async eligibleDownloaders(workspaceId, relativePath) {
         const model = await this.loadModel(workspaceId);
@@ -1129,7 +1392,7 @@ export class AccessControlService {
         const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
         return eligibleHolderEmailsResolved(model, 'owner', relativePath, own);
     }
-    async grantSources(workspaceId, kind, relativePath, principal) {
+    async grantSources(workspaceId, kind, relativePath, principal, opts) {
         const model = await this.loadModel(workspaceId);
         // A file target consults its own frontmatter as the most-specific scope; a
         // folder target's most-specific scope is its own access.md (in the dir
@@ -1139,7 +1402,7 @@ export class AccessControlService {
             : null;
         const out = {};
         for (const verb of KNOWN_VERBS) {
-            const sources = resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal, own);
+            const sources = resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal, own, opts?.tokenMatch);
             if (sources.length > 0)
                 out[verb] = sources;
         }
@@ -1151,16 +1414,24 @@ export class AccessControlService {
             model = await this.loadModel(workspaceId);
         }
         catch {
-            return { plugins: [], people: [] };
-        }
-        // Plugins = the built-in `everyone` role plus every declared role's display
-        // name. `everyone` is surfaced so the share UI can grant public read; the
-        // grant route gates it to the `read` verb only (write/owner/download
-        // everyone stay a direct-access.md edit).
-        const plugins = [
-            EVERYONE_DISPLAY,
-            ...[...model.roles.byCanonical.values()].map((r) => r.displayName),
-        ];
+            return { roles: [], groups: [], people: [] };
+        }
+        // Roles = the built-in `everyone` role plus every declared role's display
+        // name — ROLE principals only, never groups. Each role is enumerated via
+        // its `role/<canonical>` alias key, which exists exactly once per role
+        // (the bare key may be owned by a same-named group under group-first
+        // precedence, and merged group entries must not appear here). `everyone`
+        // is surfaced so the share UI can grant public read; the grant route
+        // gates it to the `read` verb only (write/owner/download everyone stay a
+        // direct-access.md edit).
+        const roles = [EVERYONE_DISPLAY];
+        const groups = [];
+        for (const [key, principal] of model.roles.byCanonical) {
+            if (key.startsWith(ROLE_TOKEN_PREFIX))
+                roles.push(principal.displayName);
+            else if (principal.kind === 'group')
+                groups.push(principal.displayName);
+        }
         // People = roles.yaml member emails (name-less) ∪ access.md `Name <email>`
         // grants (named). The login-only users table is unioned in by the caller.
         const byEmail = new Map(); // email -> display name ('' if unknown)
@@ -1181,7 +1452,7 @@ export class AccessControlService {
             name: name || email.split('@')[0],
             email,
         }));
-        return { plugins, people };
+        return { roles, groups, people };
     }
     async findEmailByHash(workspaceId, hash) {
         let model;
@@ -1218,7 +1489,24 @@ export class AccessControlService {
         }
         return null;
     }
+    /**
+     * `synced-groups.yaml` is MACHINE-OWNED: regenerated wholesale from the
+     * directory mirror and committed by the directory-sync bot. The bot is its
+     * ONLY writer — role/grant resolution never applies to it. That cuts both
+     * ways: the bot needs no role to write it (it isn't in roles.yaml, and on a
+     * protected branch nothing else would make it eligible), and no HUMAN can
+     * hand-edit it through the app (an edit would be silently overwritten by
+     * the next provisioning push anyway).
+     */
+    machineOwnedWriteRule(userEmail, relativePath) {
+        if (relativePath !== SYNCED_GROUPS_YAML)
+            return null;
+        return userEmail.trim().toLowerCase() === DIRECTORY_SYNC_BOT_EMAIL;
+    }
     async canWriteAtRef(workspaceId, ref, userEmail, relativePath) {
+        const machineOwned = this.machineOwnedWriteRule(userEmail, relativePath);
+        if (machineOwned !== null)
+            return machineOwned;
         const loaded = await this.loadModelAtRef(workspaceId, ref);
         if (!loaded)
             return null;
@@ -1235,6 +1523,16 @@ export class AccessControlService {
         return canReadResolved(loaded.model, userEmail, relativePath, own);
     }
     async canWriteBatchAtRef(workspaceId, ref, userEmail, relativePaths) {
+        // Machine-owned paths resolve without the model (see machineOwnedWriteRule)
+        // — matching canWriteAtRef, including on a repo with no rules at the ref.
+        const machineAnswers = new Map();
+        for (const p of relativePaths) {
+            const machineOwned = this.machineOwnedWriteRule(userEmail, p);
+            if (machineOwned !== null)
+                machineAnswers.set(p, machineOwned);
+        }
+        if (machineAnswers.size === relativePaths.length)
+            return machineAnswers;
         const loaded = await this.loadModelAtRef(workspaceId, ref);
         if (!loaded)
             return null;
@@ -1244,11 +1542,19 @@ export class AccessControlService {
         const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
         const result = new Map();
         for (const p of relativePaths) {
-            result.set(p, hasPermissionResolved(loaded.model, 'write', userEmail, p, owns.get(p) ?? null));
+            const machineOwned = machineAnswers.get(p);
+            result.set(p, machineOwned ?? hasPermissionResolved(loaded.model, 'write', userEmail, p, owns.get(p) ?? null));
         }
         return result;
     }
     async eligibleWritersAtRef(workspaceId, ref, relativePath) {
+        if (relativePath === SYNCED_GROUPS_YAML) {
+            // Machine-owned — see machineOwnedWriteRule.
+            return {
+                roles: [],
+                users: [{ name: DIRECTORY_SYNC_BOT_NAME, email: DIRECTORY_SYNC_BOT_EMAIL }],
+            };
+        }
         const loaded = await this.loadModelAtRef(workspaceId, ref);
         if (!loaded)
             return null;
@@ -1257,14 +1563,34 @@ export class AccessControlService {
         return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
     }
     async eligibleWritersForPathsAtRef(workspaceId, ref, relativePaths) {
+        const result = new Map();
+        // Machine-owned paths resolve without the model — same answer
+        // eligibleWritersAtRef gives (including at a ref with no usable
+        // roles.yaml), so batched consumers (CR owner-routing, approval state)
+        // agree with the single-path surface.
+        for (const p of relativePaths) {
+            if (p === SYNCED_GROUPS_YAML) {
+                result.set(p, {
+                    roles: [],
+                    users: [{ name: DIRECTORY_SYNC_BOT_NAME, email: DIRECTORY_SYNC_BOT_EMAIL }],
+                    emails: new Set([DIRECTORY_SYNC_BOT_EMAIL]),
+                });
+            }
+        }
+        // Only short-circuit when there IS a machine-owned path covering the
+        // whole request: an EMPTY request must still answer null for an
+        // unresolvable ref, as documented.
+        if (relativePaths.length > 0 && result.size === relativePaths.length)
+            return result;
         const loaded = await this.loadModelAtRef(workspaceId, ref);
         if (!loaded)
             return null;
         const repoDir = await this.repoDir(workspaceId);
-        const result = new Map();
         // One `git cat-file --batch` for the whole path set — see canWriteBatchAtRef.
         const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
         for (const p of relativePaths) {
+            if (result.has(p))
+                continue;
             const own = owns.get(p) ?? null;
             const display = eligibleHoldersResolved(loaded.model, 'write', p, own);
             const emails = new Set(eligibleHolderEmailsResolved(loaded.model, 'write', p, own).keys());
@@ -1292,6 +1618,32 @@ export class AccessControlService {
         const rolesParsed = parseRolesYaml(rolesYaml);
         if (!rolesParsed.ok)
             throw new AccessConfigError(rolesParsed.errors);
+        // Groups — the other named-principal source. Loaded forgivingly (a broken
+        // group file degrades to "contributes nothing"; only roles.yaml problems
+        // may throw) and merged into the principal index, after which the resolver
+        // below needs no group awareness at all. The reader whitelists ONLY
+        // genuine absence (ENOENT/ENOTDIR → null, like synced-groups-committer);
+        // any other read error propagates so loadActiveGroups records a
+        // broken-groups marker instead of silently treating the file as missing.
+        const activeGroups = await loadActiveGroups(async (filename) => {
+            try {
+                return await fs.readFile(path.join(repoDir, filename), 'utf-8');
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code === 'ENOENT' || code === 'ENOTDIR')
+                    return null;
+                throw err;
+            }
+        });
+        if (!activeGroups.health.ok) {
+            console.error(`[access] groups source ${activeGroups.health.file} is broken (${activeGroups.health.reason}) — groups contribute nothing until it is fixed`);
+        }
+        for (const w of activeGroups.warnings)
+            console.warn(`[access] ${w}`);
+        const mergeWarnings = mergeGroupsIntoRoles(rolesParsed.index, activeGroups.groups, activeGroups.sourceFile);
+        for (const w of mergeWarnings)
+            console.warn(`[access] ${w}`);
         const accessFiles = new Map();
         // Walk the entire repo for `access.md` files. The access tree is
         // structure-agnostic — any `access.md` at any depth (including repo
@@ -1325,6 +1677,7 @@ export class AccessControlService {
         const model = {
             roles: rolesParsed.index,
             accessFilesByDir: accessFiles,
+            groupsHealth: activeGroups.health,
             deploymentOwners: this.deploymentOwners,
         };
         this.cache.set(workspaceId, { model, loadedAt: Date.now() });
@@ -1525,6 +1878,21 @@ export class AccessControlService {
         const rolesParsed = parseRolesYaml(rolesYaml);
         if (!rolesParsed.ok)
             return null;
+        // Same group loading as the working-tree model, read AT THE REF — the
+        // whole point of file-materialized groups is that the merge/push gates
+        // can evaluate them at the commit they gate. (`showAtRef` folds every git
+        // failure into null/absent — at-ref reads cannot distinguish a missing
+        // path from a repo error, so the broken-groups marker here fires only on
+        // parse failures.)
+        const activeGroups = await loadActiveGroups((filename) => this.showAtRef(repoDir, resolvedRef, filename));
+        if (!activeGroups.health.ok) {
+            console.error(`[access@${resolvedRef}] groups source ${activeGroups.health.file} is broken (${activeGroups.health.reason}) — groups contribute nothing until it is fixed`);
+        }
+        for (const w of activeGroups.warnings)
+            console.warn(`[access@${resolvedRef}] ${w}`);
+        const mergeWarnings = mergeGroupsIntoRoles(rolesParsed.index, activeGroups.groups, activeGroups.sourceFile);
+        for (const w of mergeWarnings)
+            console.warn(`[access@${resolvedRef}] ${w}`);
         const accessFiles = new Map();
         const accessPaths = await this.listAccessFilesAtRef(repoDir, resolvedRef);
         for (const p of accessPaths) {
@@ -1550,6 +1918,7 @@ export class AccessControlService {
             model: {
                 roles: rolesParsed.index,
                 accessFilesByDir: accessFiles,
+                groupsHealth: activeGroups.health,
                 // Same owners as the working-tree model. The at-ref model backs the
                 // PUSH gate, so omitting them here would let the deployment owner save
                 // a roles.yaml repair locally and then be refused when it tries to