@bevel-software/platform-core-backend 0.28.0 → 0.29.0

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

@@ -15,12 +15,11 @@ import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-
 /**
  * Read many objects from a git repo in ONE `git cat-file --batch` process.
  * `specs` are `<ref>:<path>` lines; the result array is index-aligned with
- * them — the blob's text, or null when the spec is missing/ambiguous at the
- * ref or resolves to a non-blob (e.g. a directory). Output protocol per
- * request: `<oid> <type> <size>\n<size bytes>\n`, or `<spec> missing\n`
- * (the spec may itself contain spaces, hence the endsWith checks).
+ * them. Output protocol per request: `<oid> <type> <size>\n<size bytes>\n`,
+ * or `<spec> missing\n` (the spec may itself contain spaces, hence the
+ * endsWith checks).
  */
-async function catFileBatch(runner, repoDir, specs) {
+async function catFileBatchOutcomes(runner, repoDir, specs) {
     // Bytes, not text: every `<size>` in the header counts bytes, and the walk
     // below has to step by that count through content that is not all ASCII.
     // One spec per LINE is the protocol, and this walk depends on getting back
@@ -42,7 +41,7 @@ async function catFileBatch(runner, repoDir, specs) {
         const header = out.subarray(off, nl).toString('utf-8');
         off = nl + 1;
         if (header.endsWith(' missing') || header.endsWith(' ambiguous')) {
-            results.push(null);
+            results.push({ kind: 'missing' });
             continue;
         }
         const parts = header.split(' ');
@@ -50,13 +49,25 @@ async function catFileBatch(runner, repoDir, specs) {
         if (parts.length !== 3 || !Number.isInteger(size) || size < 0) {
             throw new Error(`unexpected git cat-file header: ${header}`);
         }
-        // Non-blob (a directory path resolves to a tree) → null, but the
-        // payload still has to be skipped to stay aligned.
-        results.push(parts[1] === 'blob' ? out.subarray(off, off + size).toString('utf-8') : null);
+        // A non-blob (a directory path resolves to a tree) is reported as such,
+        // and its payload still has to be skipped to stay aligned.
+        results.push(parts[1] === 'blob'
+            ? { kind: 'blob', text: out.subarray(off, off + size).toString('utf-8') }
+            : { kind: 'non-blob', type: parts[1] });
         off += size + 1; // payload + trailing LF
     }
     return results;
 }
+/**
+ * {@link catFileBatchOutcomes} for callers that want text or nothing: the
+ * blob's text, or null when the spec is missing at the ref or resolves to a
+ * non-blob — the own-entries reads, where a directory where a file was
+ * named simply carries no entries.
+ */
+async function catFileBatch(runner, repoDir, specs) {
+    const outcomes = await catFileBatchOutcomes(runner, repoDir, specs);
+    return outcomes.map((o) => (o.kind === 'blob' ? o.text : null));
+}
 function isBuiltInRole(canonicalRole) {
     return canonicalRole === EVERYONE_CANONICAL;
 }
@@ -319,18 +330,36 @@ function resolveAtPath(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,
+ * whose plugin grants `everyone`), plus — for a deployment owner — the Admin
+ * role's own keys, whether or not `roles.yaml` names them: the owner IS an
+ * Admin (see `AccessModel.deploymentOwners`), so every rule that binds the
+ * role binds them, for every verb. 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)
+    const asOwner = model.deploymentOwners.has(email) && !own?.has(ADMIN_ROLE_KEY);
+    if (!pub?.size && !asOwner)
         return own;
-    return new Set([...(own ?? []), ...pub]);
+    return new Set([
+        ...(own ?? []),
+        ...(pub ?? []),
+        ...(asOwner ? principalKeysOfToken(model, ADMIN_ROLE_KEY) : []),
+    ]);
 }
 /** The explicit key of the Admin ROLE — never the bare token, which a same-named group may own. */
 const ADMIN_ROLE_KEY = `${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`;
+/**
+ * The verbs the Admin floor at the repository root confers: write, and the
+ * read that write implies (`VERB_REQUIRES`). An admin who may change
+ * everything under the root may see it; otherwise the read-before-write gate
+ * refuses them the very change the floor grants. Download is not implied by
+ * write and stays with the access tree.
+ */
+function holdsAdminFloor(verb) {
+    return verb === 'write' || verb === 'read';
+}
 /**
  * Add to `keys` what holding them confers on top: every plugin principal
  * expanded from one of the keys, and the public keys every caller holds.
@@ -381,12 +410,13 @@ const NO_KEYS = new Set();
 /**
  * The tier-2 half of `hasPermissionResolved` on its own: a verdict for a set
  * of principal KEYS with no person behind them — no direct-email tier, no
- * admin rescue, no machine-owned rule — only the Admin write floor, when the
- * keys include the Admin role. Closest scope first; within a scope a
- * grant to any key wins over a denial to another, exactly as for a person.
+ * admin rescue, no machine-owned rule — only the Admin floor (write, and the
+ * read it implies), when the keys include the Admin role. Closest scope
+ * first; within a scope a grant to any key wins over a denial to another,
+ * exactly as for a person.
  */
 function hasPermissionForKeys(model, verb, keys, relativePath, fileOwn) {
-    const adminFloor = verb === 'write' && keys.has(ADMIN_ROLE_KEY);
+    const adminFloor = holdsAdminFloor(verb) && keys.has(ADMIN_ROLE_KEY);
     for (const scope of resolveScopes(model, verb, relativePath, fileOwn)) {
         if (adminFloor && isAdminFloorScope(scope, relativePath))
             return true;
@@ -460,17 +490,20 @@ function isAdminEmail(model, email) {
  * owner is whoever can already set `ADMIN_EMAIL`, so this concedes no
  * authority they did not have; it only gives it a door.
  *
- * One floor for `write`, applied during the walk: an admin (same definition)
- * always holds `write` at the repository root. When the walk reaches the root
- * `access.md` (or the own frontmatter of a file directly in the root) — or runs
- * out of scopes without a verdict — an admin is granted,
- * whatever the root file says, so no root rule can lock the deployment out of
- * its own tree. A NEARER scope still decides first: a subfolder that denies
- * Admin (or denies `everyone` without naming Admin) excludes admins there like
- * anyone else. The root file's own entries are not rewritten — the floor is a
- * verdict, not a grant line — so `grantSources` stays file-backed.
+ * One floor for `write` and the `read` it implies (`holdsAdminFloor`), applied
+ * during the walk: an admin (same definition) always holds both at the
+ * repository root. When the walk reaches the root `access.md` (or the own
+ * frontmatter of a file directly in the root) — or runs out of scopes without
+ * a verdict — an admin is granted, whatever the root file says, so no root
+ * rule can lock the deployment out of its own tree, and nobody who may change
+ * everything under the root is refused the sight of it. A NEARER scope still
+ * decides first: a subfolder that denies Admin (or denies `everyone` without
+ * naming Admin) excludes admins there like anyone else. The root file's own
+ * entries are not rewritten — the floor is a verdict, not a grant line — so
+ * `grantSources` stays file-backed.
  *
- * No special-cases for `read`/`download` — they fall through to scope resolution.
+ * No special-case for `download` (or `owner`) — they fall through to scope
+ * resolution; write implies read, not download.
  */
 function hasPermissionResolved(model, verb, userEmail, relativePath, fileOwn) {
     return decidePermissionResolved(model, verb, userEmail, relativePath, fileOwn).allowed;
@@ -485,14 +518,12 @@ function decidePermissionResolved(model, verb, userEmail, relativePath, fileOwn)
             return { allowed: true, scope: null, via: 'admin-rescue' };
         }
     }
-    const adminFloor = verb === 'write' && isAdminEmail(model, email);
-    // For write, the deployment owner IS Admin — the floor admits them, so the
-    // Admin rules along the way bind them too: a subfolder denying Admin excludes
-    // the owner exactly as it excludes the role's members.
-    let userRoles = principalKeysOf(model, email);
-    if (adminFloor && !userRoles?.has(ADMIN_ROLE_KEY)) {
-        userRoles = new Set([...(userRoles ?? []), ...principalKeysOfToken(model, ADMIN_ROLE_KEY)]);
-    }
+    const adminFloor = holdsAdminFloor(verb) && isAdminEmail(model, email);
+    // The deployment owner IS Admin: `principalKeysOf` gives them the role's
+    // keys, so the Admin rules along the way bind them too — a subfolder
+    // denying Admin excludes the owner exactly as it excludes the role's
+    // members, and one granting Admin admits them.
+    const userRoles = principalKeysOf(model, email);
     const scopes = resolveScopes(model, verb, relativePath, fileOwn);
     for (const scope of scopes) {
         if (adminFloor && isAdminFloorScope(scope, relativePath))
@@ -858,14 +889,11 @@ function canEveryoneReadResolved(model, relativePath, fileOwn) {
     // Every *named* principal must also still read. A collapsed deny may have
     // been shadowed by a closer-scope `everyone` grant, so re-resolve each
     // candidate through the closeness-first gate rather than trusting the
-    // collapsed deny state. (Role members live in roles.yaml; inline-named users
-    // come from `byEmail`.)
-    const candidates = new Set();
-    for (const email of model.roles.byEmail.keys())
-        candidates.add(email);
-    for (const email of byEmail.keys())
-        candidates.add(email);
-    for (const email of candidates) {
+    // collapsed deny state. The candidates are the same set the eligible-email
+    // lists enumerate — roles.yaml members, inline-named users, and the
+    // deployment owner, whom a `deny Admin` carves out like any member of the
+    // role whether or not roles.yaml names them.
+    for (const email of namedCandidateEmails(model, byEmail)) {
         if (!hasPermissionResolved(model, 'read', email, relativePath, fileOwn))
             return false;
     }
@@ -876,11 +904,14 @@ function canEveryoneReadResolved(model, relativePath, fileOwn) {
  *
  * Read is default-deny: a path is readable only when resolution grants the
  * caller `read` directly, via one of their roles, via the built-in `everyone`
- * role, or via `owner:` (owners implicitly read).
+ * role, or via `write:`/`owner:` (both imply read).
  *
- * No admin rescue (mirrors `download`): admins read a node only if an
- * `access.md` lists them — directly, via a role, through `everyone`, or as an
- * owner.
+ * No admin rescue on root files (that is write's), but the Admin floor
+ * holds: an admin — a member of the role or the deployment owner — reads
+ * wherever no nearer scope excludes Admin, whether or not the root names it,
+ * because the floor gives them write there and write implies read. A
+ * subfolder that denies Admin, or everyone, takes the read away as it does
+ * for any principal.
  */
 function canReadResolved(model, userEmail, relativePath, fileOwn) {
     return hasPermissionResolved(model, 'read', userEmail, relativePath, fileOwn);
@@ -945,9 +976,10 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
         const record = model.roles.byCanonical.get(canonical);
         addPrincipal(record ? record.displayName : canonical, record?.kind ?? 'role');
     }
-    // The Admin write floor (see `hasPermissionResolved`): Admin holds write here
-    // whenever no nearer scope excludes it, whether or not any file names it.
-    if (verb === 'write' && model.roles.byCanonical.has(ADMIN_ROLE_KEY)) {
+    // The Admin floor (see `hasPermissionResolved`): Admin holds write, and the
+    // read it implies, here whenever no nearer scope excludes it, whether or not
+    // any file names it.
+    if (holdsAdminFloor(verb) && model.roles.byCanonical.has(ADMIN_ROLE_KEY)) {
         const adminRole = model.roles.byCanonical.get(ADMIN_ROLE_KEY);
         if (allowedFor(principalKeysOfToken(model, ADMIN_ROLE_KEY)))
             addPrincipal(adminRole.displayName, 'role');
@@ -989,8 +1021,8 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
 }
 /**
  * Every individual the model names: `roles.yaml` members, emails named inline
- * at this path's scope, and the deployment owner (Admin for the write floor
- * even when `roles.yaml` does not list them).
+ * at this path's scope, and the deployment owner (bound by every rule that
+ * names Admin even when `roles.yaml` does not list them).
  */
 function namedCandidateEmails(model, byEmail) {
     const candidates = new Set(model.deploymentOwners);
@@ -1086,22 +1118,31 @@ export class AccessControlService {
      *
      * This is what makes the change-request gates affordable. One detail read
      * plus one approval click runs six at-ref gates, and before this cache
-     * every one of them rebuilt the model from git: an `ls-tree -r` plus a
-     * `git show` per `access.md`, ~270ms each on a real knowledge base. Six
-     * builds per click was the lag behind the approve checkmark.
+     * every one of them rebuilt the model from git. A build is two git calls
+     * (`buildModelAtCommit`: one `ls-tree`, one `cat-file --batch` for every
+     * file the model reads), and each call forks the server process, which
+     * costs tens of milliseconds on a server holding a large heap.
+     *
+     * Bounded FIFO. The bound is sized for a listing that resolves access at
+     * every open change request's two refs: one commit per open request plus
+     * the targets, and a knowledge base with a hundred open requests was
+     * evicting in a cycle under the old bound of 64, rebuilding every model on
+     * every listing — thousands of forks, minutes of the main thread, and
+     * every other request waiting behind them. A commit's tree never changes,
+     * so a model is good for as long as it is held; the bound only caps memory.
      *
-     * Bounded FIFO, so a long-lived server holds the last few tips rather than
-     * one model per commit it ever gated against. A build that found no usable
-     * roles.yaml is deliberately NOT cached, and a build that saw any git read
-     * fail never becomes a model at all: it throws AccessUnreadableError and the
-     * gate fails closed for that call. Both are what a transient failure looks
-     * like, and pinning either to a commit would turn one hiccup into a wrong
-     * verdict, denying or granting, until the base branch moved. Concurrent
-     * misses on the same commit share one build via `atRefInFlight`.
+     * A commit with no roles.yaml is remembered too (`atRefNoRoles`): the batch
+     * read answers "missing" for it from git itself, which is as final as the
+     * commit. What is never cached is a build that saw a git read FAIL: it
+     * throws AccessUnreadableError and the gate fails closed for that call, and
+     * pinning that to a commit would turn one hiccup into a wrong verdict until
+     * the branch moved. Concurrent misses on the same commit share one build
+     * via `atRefInFlight`.
      */
     atRefCache = new Map();
+    atRefNoRoles = new Set();
     atRefInFlight = new Map();
-    static AT_REF_CACHE_MAX = 64;
+    static AT_REF_CACHE_MAX = 512;
     /**
      * Canonicalised deployment-owner emails (see `AccessModel.deploymentOwners`).
      * Held on the service rather than read per-model because it comes from the
@@ -2062,27 +2103,35 @@ export class AccessControlService {
     /**
      * List every `access.md` path that exists at any depth as of `ref`.
      * The access tree is structure-agnostic: any `access.md` participates
-     * regardless of where it sits. Uses `git ls-tree -r --name-only`.
-     * `'error'` when git failed: a model built without its access files is
-     * not the model, and the caller must not cache it as one.
+     * regardless of where it sits. Uses `git ls-tree -r -z --name-only`: `-z`
+     * puts a NUL between paths and prints them as they are, where the default
+     * output C-quotes a path with a non-ASCII or special character, which would
+     * then name nothing when read back. `'error'` when git failed: a model
+     * built without its access files is not the model, and the caller must not
+     * cache it as one.
      */
     async listAccessFilesAtRef(repoDir, ref) {
         try {
-            const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
+            const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '-z', '--name-only', ref]);
             const out = [];
             const pluginDirs = [];
+            // The fixed-name sources the tree carries (roles.yaml, the groups
+            // files): a read of one of these that comes back empty is "absent"
+            // only when the tree does not name it.
+            const named = new Set();
             const { pluginsDir } = this.kb.layout;
-            for (const line of stdout.split('\n')) {
-                const p = line.trim();
+            for (const p of stdout.split('\0')) {
                 if (!p)
                     continue;
                 if (p === 'access.md' || p.endsWith('/access.md'))
                     out.push(p);
+                else if (p === 'roles.yaml' || p === SYNCED_GROUPS_YAML || p === GROUPS_YAML)
+                    named.add(p);
                 else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
                     pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
                 }
             }
-            return { accessFiles: out, pluginDirs };
+            return { accessFiles: out, pluginDirs, named };
         }
         catch {
             return 'error';
@@ -2127,6 +2176,10 @@ export class AccessControlService {
             const hit = this.atRefCache.get(key);
             if (hit)
                 return hit;
+            // A commit known to carry no roles.yaml: the next candidate, without a
+            // build (see `atRefNoRoles`).
+            if (this.atRefNoRoles.has(key))
+                continue;
             // Registered BEFORE the first await on the build path, so concurrent
             // misses on one commit share a single build instead of all racing past
             // an empty in-flight check together.
@@ -2136,6 +2189,8 @@ export class AccessControlService {
                     .then((built) => {
                     if (typeof built !== 'string')
                         this.rememberAtRef(key, built);
+                    else if (built === 'no-roles')
+                        this.rememberNoRolesAtRef(key);
                     return built;
                 })
                     .finally(() => {
@@ -2184,6 +2239,14 @@ export class AccessControlService {
                 this.atRefCache.delete(oldest);
         }
     }
+    rememberNoRolesAtRef(key) {
+        this.atRefNoRoles.add(key);
+        if (this.atRefNoRoles.size > AccessControlService.AT_REF_CACHE_MAX) {
+            const oldest = this.atRefNoRoles.values().next().value;
+            if (oldest !== undefined)
+                this.atRefNoRoles.delete(oldest);
+        }
+    }
     /**
      * The uncached build behind `loadModelAtRef`: the whole access tree read
      * at `commit`. `label` is the candidate ref the commit came from, kept for
@@ -2191,6 +2254,15 @@ export class AccessControlService {
      * means the commit carries no roles.yaml (the caller tries its next
      * candidate); `'malformed'` means it does but it doesn't parse (the caller
      * answers null, as it always has).
+     *
+     * TWO git calls, whatever the tree holds: one `ls-tree` to learn which
+     * files the model is made of, then one `cat-file --batch` that reads all of
+     * them — roles.yaml, the groups sources, every access.md and every plugin
+     * manifest. It used to be one `git show` per file, and each git call forks
+     * the server process, which on a server holding a large heap costs tens of
+     * milliseconds of the main thread per call: a knowledge base with a few
+     * dozen access files paid a second or more per commit, times every ref a
+     * listing resolves.
      */
     async buildModelAtCommit(repoDir, commit, label) {
         // Every read below tells "absent" apart from "git failed". A failure
@@ -2199,20 +2271,76 @@ export class AccessControlService {
         // and the caller fails closed (AccessUnreadableError, a 503) until a
         // retry reads the tree in full.
         const tag = `${label}@${commit.slice(0, 7)}`;
+        const listed = await this.listAccessFilesAtRef(repoDir, commit);
+        if (listed === 'error') {
+            logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
+            throw new AccessUnreadableError(label, 'access.md (ls-tree)');
+        }
+        const wanted = [
+            'roles.yaml',
+            SYNCED_GROUPS_YAML,
+            GROUPS_YAML,
+            ...listed.accessFiles,
+            ...listed.pluginDirs.map((dir) => `${dir}/${PLUGIN_MANIFEST_FILE}`),
+        ];
+        let outcomes;
+        try {
+            outcomes = await catFileBatchOutcomes(this.gitRunner, repoDir, wanted.map((p) => `${commit}:${p}`));
+        }
+        catch (err) {
+            // The operational signal: one line per failed build, naming the commit,
+            // so a run of these is visible in the logs.
+            logger(`access@${tag}`).warn(`git read of the access tree failed; refusing to decide from a partial tree: ${err instanceof Error ? err.message : String(err)}`);
+            throw new AccessUnreadableError(label, 'access tree (cat-file)');
+        }
+        const fetched = new Map();
+        wanted.forEach((p, i) => fetched.set(p, outcomes[i] ?? { kind: 'missing' }));
+        const refuse = (relativePath, why) => {
+            logger(`access@${tag}`).warn(`${relativePath} ${why}; refusing to decide from a partial tree`);
+            throw new AccessUnreadableError(label, relativePath);
+        };
+        // What the build reads. "Missing" from the batch is "absent" only for a
+        // groups source the tree does not name. A path the tree names — an
+        // access.md, a plugin manifest, or a groups file the listing carried —
+        // that comes back missing has a blob git could not read (a lost object),
+        // and one that is not a file is a tree the model cannot be read from:
+        // either way the build fails closed rather than drop what that file
+        // would deny. A path the build did not prefetch (none today) is read on
+        // its own, told apart from a git failure as before.
+        const inTree = (relativePath) => listed.named.has(relativePath) || !(relativePath === SYNCED_GROUPS_YAML || relativePath === GROUPS_YAML);
         const read = async (relativePath) => {
-            const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
-            if (outcome.kind === 'error') {
-                // The operational signal: one line per failed read, naming the commit
-                // and the path, so a run of these is visible in the logs.
-                logger(`access@${tag}`).warn(`git read of ${relativePath} failed; refusing to decide from a partial tree`);
-                throw new AccessUnreadableError(label, relativePath);
+            const got = fetched.get(relativePath);
+            if (got === undefined) {
+                const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
+                if (outcome.kind === 'error')
+                    refuse(relativePath, 'could not be read');
+                return outcome.kind === 'text' ? outcome.text : null;
             }
-            return outcome.kind === 'text' ? outcome.text : null;
+            if (got.kind === 'blob')
+                return got.text;
+            if (got.kind === 'non-blob')
+                return refuse(relativePath, `is a ${got.type}, not a file`);
+            if (!inTree(relativePath))
+                return null;
+            return refuse(relativePath, 'is in the tree but its blob could not be read');
         };
-        const rolesYaml = await read('roles.yaml');
-        if (rolesYaml === null)
+        // roles.yaml decides the build's outcome, so its states are read
+        // directly. Absent from the tree is "no roles here" (the caller tries
+        // its next candidate ref). In the tree but unreadable refuses the build:
+        // answering "no roles" for it would be remembered for the commit and
+        // would send a short ref through to origin, which may grant. A directory
+        // of that name is as malformed as a file that does not parse (the caller
+        // answers null, and never falls through to a ref that might grant what
+        // this one does not).
+        const roles = fetched.get('roles.yaml') ?? { kind: 'missing' };
+        if (roles.kind === 'missing') {
+            if (listed.named.has('roles.yaml'))
+                refuse('roles.yaml', 'is in the tree but its blob could not be read');
             return 'no-roles';
-        const rolesParsed = parseRolesYaml(rolesYaml);
+        }
+        if (roles.kind === 'non-blob')
+            return 'malformed';
+        const rolesParsed = parseRolesYaml(roles.text);
         if (!rolesParsed.ok)
             return 'malformed';
         // Same group loading as the working-tree model, read AT THE COMMIT — the
@@ -2232,11 +2360,6 @@ export class AccessControlService {
         for (const w of mergeWarnings)
             logger(`access@${tag}`).warn(w);
         const accessFiles = new Map();
-        const listed = await this.listAccessFilesAtRef(repoDir, commit);
-        if (listed === 'error') {
-            logger(`access@${tag}`).warn('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.accessFiles) {
             const text = await read(p);
             if (text === null)