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

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

@@ -3,7 +3,11 @@ import path from 'node:path';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
+import { isAbsence } from '../../shared/fs-errors.js';
+import { walkKb } from '../../shared/kb-walk.js';
+import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, isPersonalPluginDir, pluginIdentityOf, } from '@bevel-software/platform-shared';
 import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
+import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
 import { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, } from '../access-model/group-files.js';
 import { ADMIN_CANONICAL, EVERYONE_CANONICAL, EVERYONE_DISPLAY, KNOWN_VERBS, ROLE_TOKEN_PREFIX, accessMdSelfEntries, canonicalEmail, canonicalRoleName, isAccessMdPath, mergeGroupsIntoRoles, parseAccessFile, parseOwnAccessEntries, parseRolesYaml, sourceVerbsFor, } from '../access-model/access-grammar.js';
 import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-sync-bot.js';
@@ -78,11 +82,6 @@ function isBuiltInRole(canonicalRole) {
 function roleKnown(roles, canonicalRole) {
     return roles.byCanonical.has(canonicalRole) || isBuiltInRole(canonicalRole);
 }
-/** 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):
@@ -119,7 +118,7 @@ export async function loadActiveGroups(read) {
         // the same error; groups cannot be the one input that does not.
         if (err instanceof AccessUnreadableError)
             throw err;
-        if (isAbsenceError(err)) {
+        if (isAbsence(err)) {
             syncedText = null;
         }
         else {
@@ -141,7 +140,7 @@ export async function loadActiveGroups(read) {
         catch (err) {
             if (err instanceof AccessUnreadableError)
                 throw err; // see above
-            if (isAbsenceError(err))
+            if (isAbsence(err))
                 text = null;
             else
                 return broken(GROUPS_YAML, err instanceof Error ? err.message : String(err));
@@ -165,6 +164,64 @@ export async function loadActiveGroups(read) {
  * `hasPermissionResolved`). `collapseScopes` flattens this into the
  * closest-wins-per-principal view the display helpers use.
  */
+/**
+ * The rules listener on the one walk of the checkout: every `access.md` at
+ * any depth (the access tree is structure-agnostic — the root's included),
+ * plus every plugin manifest under the plugins root, for principal
+ * synthesis. A reader: a folder the walk could not list is simply not in
+ * the model (a writer that needs completeness asks the walk for its holes).
+ *
+ * Per-file failures (malformed YAML, bad role refs, unknown verbs) are
+ * logged and the offending file is dropped from the model — they do NOT
+ * throw. A typo in one nested access.md must not 500 the entire editor;
+ * admins can still write `access.md` / `roles.yaml` because
+ * `hasPermissionResolved` admin-rescues those paths, so the bad config
+ * remains fixable from inside the app.
+ */
+function accessFileListener(repoDir, out, pluginDirs) {
+    return {
+        async onFile(dir, name) {
+            const rel = dir ? `${dir}/${name}` : name;
+            if (name === PLUGIN_MANIFEST_FILE && dir.startsWith(`${PLUGINS_DIR}/`)) {
+                const text = await fs.readFile(path.join(repoDir, rel), 'utf-8').catch(() => null);
+                pluginDirs.set(dir, pluginIdentityOf(parseManifestText(text), path.posix.basename(dir)));
+                return;
+            }
+            if (name !== 'access.md')
+                return;
+            const text = await fs.readFile(path.join(repoDir, rel), 'utf-8');
+            const parsed = parseAccessFile(text, rel);
+            if (!parsed.ok) {
+                // Treat as if the file didn't exist for resolution purposes.
+                // Admin-rescue on access.md paths still lets an admin fix it.
+                for (const e of parsed.errors)
+                    console.warn(`[access] ${e} — file ignored`);
+                return;
+            }
+            for (const w of parsed.warnings)
+                console.warn(`[access] ${w}`);
+            if (out.has(parsed.file.dir)) {
+                console.warn(`[access] ${rel}: duplicate access.md for directory '${parsed.file.dir}' — keeping the first one seen`);
+                return;
+            }
+            out.set(parsed.file.dir, parsed.file);
+        },
+    };
+}
+/** A manifest's parsed object, or null for absent, unparsable or not-an-object text. */
+function parseManifestText(text) {
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 function resolveScopes(model, verb, relativePath, fileOwn) {
     const target = verb;
     const supersets = sourceVerbsFor(verb).filter((v) => v !== verb);
@@ -197,7 +254,32 @@ function resolveScopes(model, verb, relativePath, fileOwn) {
                 set(entry, 'grant');
             }
         }
-        return { byRole, byEmail, source };
+        // The anonymous caller's verdict at this scope — what someone who holds
+        // exactly the PUBLIC keys (a plugin principal whose plugin admits
+        // everyone, so everyone holds it) resolves to, by the same tiers a named
+        // caller gets: a grant via any public key wins, else a denial via one
+        // denies, else the built-in `everyone` entry decides. Derived HERE, where
+        // a scope's verdicts are built, so every reader of it — the permission
+        // check, the eligible lists, the `restricted` flag, the compiler's
+        // everyone audience — sees one truth; and derived into its own field,
+        // never into `byRole`, so the entries a person can remove stay exactly
+        // the lines the files hold.
+        let publicGrant = false;
+        let publicDeny = false;
+        for (const [key, state] of byRole) {
+            if (!model.roles.publicKeys?.has(key))
+                continue;
+            if (state === 'grant')
+                publicGrant = true;
+            else if (state === 'denied')
+                publicDeny = true;
+        }
+        const everyone = publicGrant
+            ? 'grant'
+            : publicDeny
+                ? 'denied'
+                : byRole.get(EVERYONE_CANONICAL);
+        return { byRole, byEmail, everyone, source };
     };
     const scopes = [];
     // The node's own frontmatter is the most specific scope. Role refs there are
@@ -221,17 +303,33 @@ function resolveScopes(model, verb, relativePath, fileOwn) {
 function collapseScopes(scopes) {
     const byRole = new Map();
     const byEmail = new Map();
+    let everyone;
     for (let i = scopes.length - 1; i >= 0; i--) {
         for (const [k, v] of scopes[i].byRole)
             byRole.set(k, v);
         for (const [k, v] of scopes[i].byEmail)
             byEmail.set(k, v);
+        if (scopes[i].everyone !== undefined)
+            everyone = scopes[i].everyone;
     }
-    return { byRole, byEmail };
+    return { byRole, byEmail, everyone };
 }
 function resolveAtPath(model, verb, relativePath, fileOwn) {
     return collapseScopes(resolveScopes(model, verb, relativePath, fileOwn));
 }
+/**
+ * Every principal key a caller holds: the tokens their email is a member of,
+ * plus the PUBLIC keys every caller holds regardless (a plugin principal
+ * whose plugin grants `everyone`). Undefined when there is nothing at all,
+ * matching the plain `byEmail.get` the tier-2 check used to read.
+ */
+function principalKeysOf(model, email) {
+    const own = model.roles.byEmail.get(email);
+    const pub = model.roles.publicKeys;
+    if (!pub?.size)
+        return own;
+    return new Set([...(own ?? []), ...pub]);
+}
 function isAdminEmail(model, email) {
     if (model.deploymentOwners.has(email))
         return true;
@@ -282,7 +380,7 @@ function hasPermissionResolved(model, verb, userEmail, relativePath, fileOwn) {
         if (isAccessMdPath(relativePath) && isAdminEmail(model, email))
             return true;
     }
-    const userRoles = model.roles.byEmail.get(email);
+    const userRoles = principalKeysOf(model, email);
     const scopes = resolveScopes(model, verb, relativePath, fileOwn);
     for (const scope of scopes) {
         // Tier 1 — direct email entry is the most specific verdict at this scope.
@@ -307,10 +405,10 @@ function hasPermissionResolved(model, verb, userEmail, relativePath, fileOwn) {
             if (deny)
                 return false;
         }
-        // Tier 3 — the built-in `everyone` role.
-        const everyone = scope.byRole.get(EVERYONE_CANONICAL);
-        if (everyone)
-            return everyone === 'grant';
+        // Tier 3 — the built-in `everyone` role (derived: a public plugin
+        // principal granted here counts, see `AccessScope.everyone`).
+        if (scope.everyone)
+            return scope.everyone === 'grant';
         // No verdict at this scope — fall through to the next (farther) one.
     }
     return false;
@@ -454,11 +552,11 @@ function dirChainFor(relativePath) {
  * reported as restricted.
  */
 function canEveryoneReadResolved(model, relativePath, fileOwn) {
-    const { byRole, byEmail } = resolveAtPath(model, 'read', relativePath, fileOwn);
+    const { byEmail, everyone } = resolveAtPath(model, 'read', relativePath, fileOwn);
     // Baseline: an unnamed signed-in user (no email/role entries) reads only via
     // `everyone`. As a single principal, its collapsed verdict is its closest —
     // exactly what that user resolves to.
-    if (byRole.get(EVERYONE_CANONICAL) !== 'grant')
+    if (everyone !== 'grant')
         return false;
     // Every *named* principal must also still read. A collapsed deny may have
     // been shadowed by a closer-scope `everyone` grant, so re-resolve each
@@ -491,7 +589,7 @@ function canReadResolved(model, userEmail, relativePath, fileOwn) {
     return hasPermissionResolved(model, 'read', userEmail, relativePath, fileOwn);
 }
 function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
-    const { byRole, byEmail } = resolveAtPath(model, verb, relativePath, fileOwn);
+    const { byRole, byEmail, everyone } = resolveAtPath(model, verb, relativePath, fileOwn);
     // (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
@@ -515,6 +613,12 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
         const record = model.roles.byCanonical.get(canonical);
         addPrincipal(record ? record.displayName : canonical, record?.kind ?? 'role');
     }
+    // The derived everyone verdict: a public plugin principal granted here
+    // means anyone signed in holds the verb, and a list that counts holders (an
+    // approval gate, a "restricted to" banner) must say so — as `everyone`, the
+    // same row a literal grant produces.
+    if (everyone === 'grant')
+        addPrincipal(EVERYONE_CANONICAL, 'role');
     // Mirror the admin overrides applied in `hasPermissionResolved`: write on
     // `roles.yaml` and on any `access.md` is granted to Admin even if the
     // file content doesn't list it. Without surfacing that here, the
@@ -674,7 +778,29 @@ export class AccessControlService {
     invalidate(workspaceId) {
         this.cache.delete(workspaceId);
         this.ownEntriesCache.delete(workspaceId);
+        this.generation++;
     }
+    /**
+     * Bumped by every `invalidate()`, for any workspace. A model load reads the
+     * tree across many awaits, and an invalidation fires exactly when that tree
+     * changes underneath it: the load that started on the old tree would
+     * otherwise store its model AFTER the drop, and every read for the next TTL
+     * would resolve against a tree that is already gone. `loadModel` takes the
+     * generation before its first read and refuses to store a model fetched
+     * under an older one — the caller that started it still gets its answer,
+     * as old as the moment it started, and the next caller reloads.
+     *
+     * ONE counter, not one per workspace: a per-workspace map would keep an
+     * entry for every branch workspace the process ever loaded, with nothing to
+     * tell it when a workspace is gone. The price of sharing is that a drop on
+     * some other workspace, landing mid-load, costs this one a single reload —
+     * a load is tens of milliseconds and a drop is a commit, so that is rare
+     * and cheap, and it never stores a wrong model. (The own-entries memo needs
+     * no token: it is keyed by the map object a reader took BEFORE its disk
+     * read, and `invalidate()` replaces the map, so a late store lands in an
+     * orphan nobody consults.)
+     */
+    generation = 0;
     /** Memoized `readOwnEntries` for the batch paths; see `ownEntriesCache`. */
     async cachedOwnEntries(workspaceId, repoDir, relativePath) {
         let ws = this.ownEntriesCache.get(workspaceId);
@@ -773,14 +899,26 @@ export class AccessControlService {
     async eligibleReaders(workspaceId, relativePath) {
         const model = await this.loadModel(workspaceId);
         const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
-        // When `read: everyone` applies cleanly, the node is readable by all users
-        // 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, principals: [], roles: [], users: [] };
-        }
+        // `restricted` is the verdict — whether `read: everyone` applies cleanly —
+        // and the lists are the GRANTS that exist regardless: on a public node
+        // they name what makes it public (`everyone`, and a public plugin
+        // principal whose grant is the one to remove), so the share dialog can
+        // show that grant as a row. Consumers that only want to know whether the
+        // node is public read the flag; the lists may be empty for a
+        // default-denied path with no grants.
         const { principals, roles, users } = eligibleHoldersResolved(model, 'read', relativePath, own);
-        return { restricted: true, principals, roles, users };
+        // WHY it is public, when it is: the public plugin principals granted read
+        // here — the one thing the dialog cannot tell from the lists alone (a
+        // plugin principal in them may or may not be public), so the resolver,
+        // which knows, says it. A literal `everyone` line shows up as a source
+        // of the `everyone` row instead; together the two answer "what remains
+        // public after this grant is removed".
+        const collapsed = resolveAtPath(model, 'read', relativePath, own);
+        const publicVia = [...collapsed.byRole]
+            .filter(([key, state]) => state === 'grant' && model.roles.publicKeys?.has(key))
+            .map(([key]) => key)
+            .sort();
+        return { restricted: !canEveryoneReadResolved(model, relativePath, own), principals, roles, users, publicVia };
     }
     async eligibleDownloaders(workspaceId, relativePath) {
         const model = await this.loadModel(workspaceId);
@@ -819,7 +957,7 @@ export class AccessControlService {
             model = await this.loadModel(workspaceId);
         }
         catch {
-            return { roles: [], groups: [], people: [] };
+            return { roles: [], groups: [], plugins: [], people: [] };
         }
         // Roles = the built-in `everyone` role plus every declared role's display
         // name — ROLE principals only, never groups. Each role is enumerated via
@@ -831,11 +969,22 @@ export class AccessControlService {
         // direct-access.md edit).
         const roles = [EVERYONE_DISPLAY];
         const groups = [];
+        // Plugins = the identities behind the synthesised `plugin/<name>/<verb>`
+        // principals, once each (three keys share a folder). Personal shelves are
+        // plugins to the resolver but not to a person picking a grantee — told
+        // apart by their FOLDER (the one structural rule), never by their name.
+        const plugins = new Map();
         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);
+            else if (principal.kind === 'plugin' &&
+                principal.pluginName &&
+                principal.pluginDir &&
+                !isPersonalPluginDir(principal.pluginDir)) {
+                plugins.set(principal.pluginName, principal.pluginDir);
+            }
         }
         // People = roles.yaml member emails (name-less) ∪ access.md `Name <email>`
         // grants (named). The login-only users table is unioned in by the caller.
@@ -857,7 +1006,14 @@ export class AccessControlService {
             name: name || email.split('@')[0],
             email,
         }));
-        return { roles, groups, people };
+        return {
+            roles,
+            groups,
+            plugins: [...plugins.entries()]
+                .map(([name, folder]) => ({ name, folder }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+            people,
+        };
     }
     async findEmailByHash(workspaceId, hash) {
         let model;
@@ -1012,6 +1168,8 @@ export class AccessControlService {
         if (cached && Date.now() - cached.loadedAt < AccessControlService.CACHE_TTL_MS) {
             return cached.model;
         }
+        // Taken before the first read; see `generation`.
+        const generation = this.generation;
         const repoDir = await this.repoDir(workspaceId);
         let rolesYaml;
         try {
@@ -1063,7 +1221,14 @@ export class AccessControlService {
         // must not 500 the entire editor; admins can still write `access.md`
         // / `roles.yaml` because `hasPermissionResolved` admin-rescues those
         // paths, so the bad config remains fixable from inside the app.
-        await this.collectAccessFiles(repoDir, '', accessFiles);
+        const pluginDirs = new Map();
+        await walkKb(repoDir, [accessFileListener(repoDir, accessFiles, pluginDirs)]);
+        // Plugin principals (`plugin/<Name>/<verb>`), derived from each plugin
+        // folder's own access.md — a plugin being a folder with a manifest, at
+        // any depth — after groups merged (so their rosters expand through the
+        // finished index) and before the unknown-role sweep below (so a grant
+        // naming one counts as known).
+        synthesizePluginPrincipals(rolesParsed.index, accessFiles, pluginDirs);
         // Validate role refs against roles.yaml. `everyone` is a built-in role and
         // is valid without a roles.yaml entry. Unknown refs are dropped from the
         // parsed entry list (along with a warn log) so the rest of the file still
@@ -1085,49 +1250,12 @@ export class AccessControlService {
             groupsHealth: activeGroups.health,
             deploymentOwners: this.deploymentOwners,
         };
-        this.cache.set(workspaceId, { model, loadedAt: Date.now() });
-        return model;
-    }
-    async collectAccessFiles(absDir, relDir, out) {
-        let entries;
-        try {
-            entries = await fs.readdir(absDir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            // Skip VCS metadata + vendored deps. Hidden dirs (`.git`, `.vscode`,
-            // etc.) and `node_modules` can't host KB rules and are often huge —
-            // walking them would slow every cache miss without benefit.
-            if (entry.name.startsWith('.'))
-                continue;
-            if (entry.name === 'node_modules')
-                continue;
-            const abs = path.join(absDir, entry.name);
-            const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
-            if (entry.isDirectory()) {
-                await this.collectAccessFiles(abs, rel, out);
-            }
-            else if (entry.isFile() && entry.name === 'access.md') {
-                const text = await fs.readFile(abs, 'utf-8');
-                const parsed = parseAccessFile(text, rel);
-                if (!parsed.ok) {
-                    // Treat as if the file didn't exist for resolution purposes.
-                    // Admin-rescue on access.md paths still lets an admin fix it.
-                    for (const e of parsed.errors)
-                        console.warn(`[access] ${e} — file ignored`);
-                    continue;
-                }
-                for (const w of parsed.warnings)
-                    console.warn(`[access] ${w}`);
-                if (out.has(parsed.file.dir)) {
-                    console.warn(`[access] ${rel}: duplicate access.md for directory '${parsed.file.dir}' — keeping the first one seen`);
-                    continue;
-                }
-                out.set(parsed.file.dir, parsed.file);
-            }
+        // An invalidation landed mid-load: this model describes a tree that is
+        // already gone, so it is returned to this caller but never stored.
+        if (this.generation === generation) {
+            this.cache.set(workspaceId, { model, loadedAt: Date.now() });
         }
+        return model;
     }
     async repoDir(workspaceId) {
         const wsDir = await this.workspaceService.getWorkspacePath(workspaceId);
@@ -1255,14 +1383,18 @@ export class AccessControlService {
         try {
             const { stdout } = await execFileAsync('git', ['-C', repoDir, 'ls-tree', '-r', '--name-only', ref], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
             const out = [];
+            const pluginDirs = [];
             for (const line of stdout.split('\n')) {
                 const p = line.trim();
                 if (!p)
                     continue;
                 if (p === 'access.md' || p.endsWith('/access.md'))
                     out.push(p);
+                else if (p.startsWith(`${PLUGINS_DIR}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
+                    pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
+                }
             }
-            return out;
+            return { accessFiles: out, pluginDirs };
         }
         catch {
             return 'error';
@@ -1407,7 +1539,7 @@ export class AccessControlService {
             console.warn(`[access@${tag}] listing access.md files failed; refusing to decide from a partial tree`);
             throw new AccessUnreadableError(label, 'access.md (ls-tree)');
         }
-        for (const p of listed) {
+        for (const p of listed.accessFiles) {
             const text = await read(p);
             if (text === null)
                 continue;
@@ -1419,6 +1551,16 @@ export class AccessControlService {
             // duplicates, but be defensive.
             accessFiles.set(parsed.file.dir, parsed.file);
         }
+        // Mirror `loadModel`: plugin principals from the plugins the ref carries,
+        // each under the identity its manifest AT THAT REF declares, so a PR-time
+        // verdict on a skill granted to `plugin/<name>/write` counts the plugin's
+        // writers exactly as the working tree would.
+        const pluginIdentities = new Map();
+        for (const dir of listed.pluginDirs) {
+            const manifest = parseManifestText(await read(`${dir}/${PLUGIN_MANIFEST_FILE}`));
+            pluginIdentities.set(dir, pluginIdentityOf(manifest, path.posix.basename(dir)));
+        }
+        synthesizePluginPrincipals(rolesParsed.index, accessFiles, pluginIdentities);
         // Mirror `loadModel`: drop entries whose role ref is unknown to roles.yaml,
         // while preserving the built-in `everyone` role.
         for (const [, file] of accessFiles) {