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

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

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
 import { logger } from '../../shared/logging.js';
 const log = logger('access');
 import { isAbsence } from '../../shared/fs.contract.js';
@@ -7,10 +8,8 @@ import { assertOneSpecPerLine, isCommitSha, isGitTimeout } from '../../shared/gi
 import { hashEmail } from '../../shared/email-identity.js';
 import { NodeGitRunner } from '../workflow/index.js';
 import { readRevSha } from '../kb-fs/index.js';
-import { DEFAULT_KB_LAYOUT, PLUGIN_MANIFEST_FILE, isPersonalPluginDir, pluginIdentityOf, platformRestoreDestination, } from '@bevel-software/platform-shared';
-import { AccessConfigError, AccessUnreadableError, synthesizePluginPrincipals } from '../access-model/index.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, } from '../access-model/index.js';
-import { ADMIN_CANONICAL, EVERYONE_CANONICAL, EVERYONE_DISPLAY, KNOWN_VERBS, ROLE_TOKEN_PREFIX, accessMdSelfEntries, canonicalEmail, canonicalRoleName, isAccessMdPath, mergeGroupsIntoRoles, parseAccessFile, parseOwnAccessEntries, parseRolesYaml, requiredVerbsFor, sourceVerbsFor, } from '../access-model/index.js';
+import { DEFAULT_KB_LAYOUT, PLUGIN_MANIFEST_FILE, isFrontmatterFence, isPersonalPluginDir, pluginIdentityOf, platformRestoreDestination, } from '@bevel-software/platform-shared';
+import { AccessConfigError, AccessUnreadableError, synthesizePluginPrincipals, GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, ADMIN_CANONICAL, EVERYONE_CANONICAL, EVERYONE_DISPLAY, KNOWN_VERBS, ROLE_TOKEN_PREFIX, GROUP_TOKEN_PREFIX, splitPrincipalToken, accessMdSelfEntries, canonicalEmail, canonicalRoleName, isAccessMdPath, mergeGroupsIntoRoles, parseAccessFile, parseOwnAccessEntries, parseRolesYaml, requiredVerbsFor, sourceVerbsFor, } from '../access-model/index.js';
 import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-sync-bot.js';
 /**
  * Read many objects from a git repo in ONE `git cat-file --batch` process.
@@ -387,18 +386,22 @@ function addDerivedKeys(model, keys) {
  * twin of `principalKeysOf`: a member's key set minus everything they hold
  * for reasons of their own. `null` when no group of that name exists.
  *
- * Groups are keyed by their bare canonical name (`mergeGroupsIntoRoles`);
- * roles by `role/<name>`. A bare key whose record is a ROLE is not a group,
- * however it was spelled.
+ * Groups are keyed by `group/<name>`, and by their bare canonical name
+ * when no role owns it (`mergeGroupsIntoRoles`); roles by the bare name and
+ * `role/<name>`. `group` may be spelled either way: a bare name whose record
+ * is a ROLE still finds the group through its `group/` alias, because this
+ * question is always asked of the group.
  */
 function principalKeysOfGroup(model, group) {
-    const canonical = canonicalRoleName(group);
-    const record = model.roles.byCanonical.get(canonical);
+    const { name } = splitPrincipalToken(canonicalRoleName(group));
+    const record = model.roles.byCanonical.get(`${GROUP_TOKEN_PREFIX}${name}`);
     if (!record || record.kind !== 'group')
         return null;
-    const keys = new Set([canonical]);
+    const keys = new Set();
     for (const [key, principal] of model.roles.byCanonical) {
-        if (principal.kind === 'role' && principal.groupRefs?.has(canonical))
+        if (principal === record)
+            keys.add(key);
+        else if (principal.kind === 'role' && principal.groupRefs?.has(name))
             keys.add(key);
     }
     // Plugin principals were expanded from role/group entries; a plugin that
@@ -454,9 +457,9 @@ function isAdminEmail(model, email) {
     if (model.deploymentOwners.has(email))
         return true;
     const roles = model.roles.byEmail.get(email);
-    // 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.
+    // Check the explicit `role/admin` alias: it is the role's whatever the
+    // bare key holds, and a group that happens to be named "Admin" is only
+    // ever `group/admin` — its members never inherit the capability.
     return !!roles && roles.has(ADMIN_ROLE_KEY);
 }
 /**
@@ -649,26 +652,11 @@ function resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal,
     const out = [];
     if (principal.kind === '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.
+        //     its explicit `role/<name>` or `group/<name>` token. Which spellings
+        //     are THIS principal's entries is `ownTokensOf`'s one rule — the bare
+        //     token counts only when the bare key is this principal's (the role
+        //     when one exists, else the group), and a pinned `'exact'` counts the
+        //     literal spelling alone.
         const tokens = ownTokensOf(model, principal.role, tokenMatch);
         for (const scope of scopes) {
             const states = tokens.map((t) => scope.byRole.get(t));
@@ -698,20 +686,37 @@ function resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal,
 }
 /**
  * WHICH token spellings in a file are THIS role-shaped principal's own entries
- * — the shadowing rule, in one place because the grant walk, the denial walk
- * and the revoke splice must all agree on it (a disagreement attributes a
- * shadowed bare token to the wrong principal, which is how a "restrict" silently
- * strips a same-named role's grant). See `resolveGrantSourcesForVerb` for the
- * full reasoning behind each branch.
+ * — in one place because the grant walk, the denial walk and the revoke splice
+ * must all agree on it (a disagreement attributes a bare token to the wrong
+ * principal, which is how a "restrict" silently strips a same-named role's
+ * grant).
+ *
+ *   - `role/X` is the role: its own entries are `role/X`, plus the bare `X`
+ *     unless a GROUP owns the bare key (no role X exists, a group X does).
+ *   - `group/X` is the group: `group/X`, plus the bare `X` unless a ROLE
+ *     owns it — under role-first precedence a same-named role always does.
+ *   - A bare `X` is whoever owns the bare key, with that kind's explicit
+ *     spelling; a bare token with no record (`everyone`, a plugin token, a
+ *     vanished principal) is just itself plus the `role/` spelling a legacy
+ *     role grant may carry.
+ *   - PINNED EXACT (`tokenMatch: 'exact'`): only the literal spelling. The
+ *     caller pinned the same identity into the splice it is checking.
  */
 function ownTokensOf(model, role, tokenMatch) {
     const canonical = canonicalRoleName(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';
-    return tokenMatch === 'exact' || shadowed
-        ? [explicit ? `${ROLE_TOKEN_PREFIX}${bare}` : bare]
-        : [bare, `${ROLE_TOKEN_PREFIX}${bare}`];
+    if (tokenMatch === 'exact')
+        return [canonical];
+    const { prefix, name } = splitPrincipalToken(canonical);
+    const bareOwner = model.roles.byCanonical.get(name)?.kind;
+    if (prefix === 'role')
+        return bareOwner === 'group' ? [canonical] : [name, canonical];
+    if (prefix === 'group')
+        return bareOwner === 'role' ? [canonical] : [name, canonical];
+    if (bareOwner === 'group')
+        return [name, `${GROUP_TOKEN_PREFIX}${name}`];
+    if (bareOwner === 'plugin')
+        return [name];
+    return [name, `${ROLE_TOKEN_PREFIX}${name}`];
 }
 /**
  * The polarity twin of {@link resolveGrantSourcesForVerb}: every file scope
@@ -836,6 +841,73 @@ function parentDirOf(relativePath) {
     const cut = relativePath.lastIndexOf('/');
     return cut === -1 ? '' : relativePath.slice(0, cut);
 }
+/** The first read of {@link frontmatterHead}; each later one doubles, up to the last. */
+const HEAD_FIRST_READ = 1_024;
+const HEAD_LAST_READ = 64 * 1_024;
+/**
+ * The start of `file` that holds everything its frontmatter can say: its
+ * first line when that is no fence (no frontmatter at all), the text through
+ * the closing fence when there is one, and the whole file when an opening
+ * fence is never closed. Scanned for its frontmatter (`scanFrontmatter`), it
+ * answers exactly as the whole file does, by the same fence rule
+ * (`isFrontmatterFence`) — and a file with no frontmatter costs one small
+ * read however long it is.
+ */
+async function frontmatterHead(file) {
+    const handle = await fs.open(file, 'r');
+    try {
+        const decoder = new StringDecoder('utf8');
+        // What was read, kept as it was decoded and joined once, when answered:
+        // each character is scanned once, however long a line runs.
+        const pieces = [];
+        let before = 0;
+        // The line being read so far, folded (see `foldLine`), or null once it
+        // can no longer be a fence.
+        let line = '';
+        let first = true;
+        let position = 0;
+        for (let size = HEAD_FIRST_READ;; size = Math.min(size * 2, HEAD_LAST_READ)) {
+            const chunk = Buffer.allocUnsafe(size);
+            const { bytesRead } = await handle.read(chunk, 0, size, position);
+            if (bytesRead === 0)
+                return pieces.join('') + decoder.end();
+            position += bytesRead;
+            const piece = decoder.write(chunk.subarray(0, bytesRead));
+            pieces.push(piece);
+            let from = 0;
+            for (let nl = piece.indexOf('\n'); nl !== -1; nl = piece.indexOf('\n', from)) {
+                const fence = line !== null && isFrontmatterFence(foldLine(line, piece.slice(from, nl)));
+                // The first line opens a block or there is none; after it, the first
+                // fence closes the block.
+                if (first ? !fence : fence)
+                    return pieces.join('').slice(0, before + nl);
+                first = false;
+                line = '';
+                from = nl + 1;
+            }
+            if (line !== null) {
+                line = foldLine(line, piece.slice(from));
+                if (!'---'.startsWith(line.trim()))
+                    line = null;
+            }
+            // A first line still unfinished that already cannot be a fence.
+            if (first && line === null)
+                return pieces.join('');
+            before += piece.length;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * `line` continued by `more`, every run of whitespace folded to one space.
+ * Trimmed, it is `---` exactly when the unfolded line is, so it judges a fence
+ * as `isFrontmatterFence` does while staying a few characters long.
+ */
+function foldLine(line, more) {
+    return `${line}${more}`.replace(/\s+/g, ' ');
+}
 /**
  * One file's own-entries, parsed as the path `asName` would be read.
  *
@@ -946,15 +1018,15 @@ function eligibleHoldersResolved(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
-    // 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.
+    // `role/` or `group/` alias); the `byCanonical` record a key hits carries
+    // its kind — a `role/` alias always hits the role record, a `group/` alias
+    // the group record, a bare key the role when one exists, else the group. 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 (the role plus a same-named
+    // group via `group/`) BOTH entries survive — they are DIFFERENT
+    // principals, and collapsing them to one would hide one of the grants from
+    // every consumer of the eligible list.
     const byIdentity = new Map();
     const addPrincipal = (name, kind) => {
         const key = `${kind}\0${name.toLowerCase()}`;
@@ -997,9 +1069,9 @@ 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))) {
-        // 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.
+        // Look the Admin ROLE up via its explicit alias, the key that is always
+        // the role's. The override is the ROLE's capability, so the row's kind is
+        // 'role' regardless.
         const adminRole = model.roles.byCanonical.get(ADMIN_ROLE_KEY);
         addPrincipal(adminRole ? adminRole.displayName : ADMIN_CANONICAL, 'role');
     }
@@ -1323,7 +1395,11 @@ export class AccessControlService {
         const model = await this.loadModel(workspaceId);
         const email = canonicalEmail(userEmail);
         const names = [];
-        for (const principal of model.roles.byCanonical.values()) {
+        // Each group once, through its `group/` alias (the bare key, when the
+        // group owns it, is the same record).
+        for (const [key, principal] of model.roles.byCanonical) {
+            if (!key.startsWith(GROUP_TOKEN_PREFIX))
+                continue;
             if (principal.kind === 'group' && principal.emails.has(email))
                 names.push(principal.displayName);
         }
@@ -1479,7 +1555,7 @@ export class AccessControlService {
      */
     async previewAccessAfterRelocation(workspaceId, userEmail, fromPath, toPath, opts) {
         const repoDir = await this.repoDir(workspaceId);
-        const { isFolder, ownThere: own, landing } = await this.relocationSubject(repoDir, fromPath, toPath);
+        const { isFolder, ownThere: own, landing } = await this.relocationSubject(repoDir, fromPath, toPath, opts?.sourceContent);
         const model = withRelocatedAccessFiles(await this.loadModel(workspaceId), fromPath, toPath, { sourceRemains: opts?.sourceRemains === true, sourceIsFolder: isFolder, landing });
         const machineOwned = this.machineOwnedWriteRule(userEmail, toPath);
         return {
@@ -1604,9 +1680,9 @@ export class AccessControlService {
         }
         // 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`
+        // its `role/<canonical>` alias key, which exists exactly once per role;
+        // each group likewise via its `group/<canonical>` alias (a group that
+        // owns its bare key is registered under both, as one record). `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).
@@ -1620,7 +1696,7 @@ export class AccessControlService {
         for (const [key, principal] of model.roles.byCanonical) {
             if (key.startsWith(ROLE_TOKEN_PREFIX))
                 roles.push(principal.displayName);
-            else if (principal.kind === 'group')
+            else if (key.startsWith(GROUP_TOKEN_PREFIX) && principal.kind === 'group')
                 groups.push(principal.displayName);
             else if (principal.kind === 'plugin' &&
                 principal.pluginName &&
@@ -1990,13 +2066,18 @@ export class AccessControlService {
      * in the new (body-governed) format, where its frontmatter is self-access —
      * see {@link accessMdSelfEntries}. A legacy `access.md` still yields null:
      * its frontmatter IS the folder rules the dir chain already applies.
+     *
+     * Any other file declares them in its frontmatter alone, so only as much of
+     * it is read as the frontmatter takes (see {@link frontmatterHead}): a batch
+     * over a tree of megabyte transcripts reads a line of each, not the tree.
      */
     async readOwnEntries(repoDir, relativePath) {
         if (relativePath === 'roles.yaml')
             return null;
+        const file = path.join(repoDir, relativePath);
         let text;
         try {
-            text = await fs.readFile(path.join(repoDir, relativePath), 'utf-8');
+            text = isAccessMdPath(relativePath) ? await fs.readFile(file, 'utf-8') : await frontmatterHead(file);
         }
         catch {
             return null;
@@ -2028,18 +2109,26 @@ export class AccessControlService {
      * Only absence is an answer (see `isAbsence`): a probe that failed on
      * permissions or I/O does not say "this is a file", and reading a folder as
      * one would resolve it through frontmatter it does not have.
+     *
+     * `sourceContent` is the text of a source that is NO repository path — a
+     * file staged in the workspace's `tmp/` folder, which `copy_file` lands in
+     * the repository. Nothing is probed on disk for it: it is one file by the
+     * ref's own rule, and its text is read exactly as a repository file's is,
+     * so the copy previews the rules it carries in.
      */
-    async relocationSubject(repoDir, fromPath, toPath) {
+    async relocationSubject(repoDir, fromPath, toPath, sourceContent) {
         const nothing = { isFolder: false, ownHere: null, ownThere: null, landing: null };
-        const fromStat = await fs.lstat(path.join(repoDir, fromPath)).catch((err) => {
-            if (isAbsence(err))
-                return null;
-            throw err;
-        });
-        if (fromStat?.isSymbolicLink() === true)
-            return nothing;
-        if (fromStat?.isDirectory() === true)
-            return { ...nothing, isFolder: true };
+        if (sourceContent === undefined) {
+            const fromStat = await fs.lstat(path.join(repoDir, fromPath)).catch((err) => {
+                if (isAbsence(err))
+                    return null;
+                throw err;
+            });
+            if (fromStat?.isSymbolicLink() === true)
+                return nothing;
+            if (fromStat?.isDirectory() === true)
+                return { ...nothing, isFolder: true };
+        }
         // `roles.yaml` carries no own-entries wherever it sits, exactly as
         // `readOwnEntries` has it; a read that fails for any reason is no rules,
         // which is what the gates would say about the same file.
@@ -2047,7 +2136,7 @@ export class AccessControlService {
             return nothing;
         let text;
         try {
-            text = await fs.readFile(path.join(repoDir, fromPath), 'utf-8');
+            text = sourceContent ?? (await fs.readFile(path.join(repoDir, fromPath), 'utf-8'));
         }
         catch {
             return nothing;