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

package/dist/modules/access/access.routes.js

@@ -1,11 +1,19 @@
 import express from 'express';
-import { isProtectedBranch, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { inArray } from 'drizzle-orm';
+import { logger } from '../../shared/logging.js';
+import { printable } from '../../shared/printable.js';
+// The audit lines this file writes have always carried their own tags —
+// `access.grant`, `access.revoke` and their sub-cases — so each keeps it.
+const grantLog = logger('access.grant');
+const revokeLog = logger('access.revoke');
+import { isProtectedBranch, DEFAULT_BRANCH, pluginManifestName, FOLDER_GOVERNS_ACCESS_KIND, } from '@bevel-software/platform-shared';
 import { branchForWorkspaceId, workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { AccessDeniedError } from '../access-model/access-errors.js';
-import { AccessMutationService, AccessMutationError, accessMdPathForFolder, } from './access-mutation.service.js';
-import { canonicalRoleName, EVERYONE_CANONICAL, ROLE_TOKEN_PREFIX, } from '../access-model/access-grammar.js';
+import { AccessMutationService, AccessMutationError, accessMdPathForFolder, assertFileCarriesAccessRules, fileCarriesAccessRules, governingFolderOf, } from './access-mutation.service.js';
+import { canonicalRoleName, EVERYONE_CANONICAL, PLUGIN_TOKEN_PREFIX, PLUGIN_TOKEN_VERBS, ROLE_TOKEN_PREFIX, } from '../access-model/access-grammar.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
+import { emailsInView, holderPrincipals, labelAccountHolders, resolveAccessView } from './access-view.js';
 import { toHttpError as sharedToHttpError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import { RolesAdminService } from './roles-admin.service.js';
 import { users } from '../database/schema.js';
@@ -22,6 +30,16 @@ function toHttpError(err) {
 function requireNonEmptyString(value, field) {
     return sharedRequireNonEmptyString(value, field);
 }
+/**
+ * Is this the "the folder governs this file" refusal? It is the one mutation
+ * failure that is guaranteed to have written nothing — it is thrown as the
+ * file is read — so the lock it holds must be released without discarding the
+ * path (see `withEditLock`).
+ */
+function isFolderGovernsRefusal(err) {
+    return (err instanceof AccessMutationError &&
+        err.payload?.kind === FOLDER_GOVERNS_ACCESS_KIND);
+}
 export function createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, kbDirName, 
 /** This deployment's configured admins — the break-glass recovery roster. */
 recoveryAdmins = []) {
@@ -38,8 +56,22 @@ recoveryAdmins = []) {
     // caller's own workspace).
     const defaultBranchPrincipals = async () => {
         await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
-        const { roles, groups } = await accessControl.kbPrincipals(workspaceIdForBranch(DEFAULT_BRANCH));
-        return { roles, groups };
+        const { roles, groups, plugins } = await accessControl.kbPrincipals(workspaceIdForBranch(DEFAULT_BRANCH));
+        // `plugins` is defensive: an older resolver double may omit it.
+        return { roles, groups, plugins: plugins ?? [] };
+    };
+    /**
+     * The plugins `email` may DISCOVER — read the folder's access.md, the same
+     * verdict the plugin index lists on. Both the suggest list and the grant
+     * route go through this, so a plugin hidden from the picker cannot be
+     * named in a grant either, and an undiscoverable one answers exactly like
+     * one that does not exist.
+     */
+    const discoverablePlugins = async (email, plugins) => {
+        if (plugins.length === 0)
+            return [];
+        const verdicts = await accessControl.canReadBatch(workspaceIdForBranch(DEFAULT_BRANCH), email, plugins.map((p) => `${p.folder}/access.md`));
+        return plugins.filter((p) => verdicts.get(`${p.folder}/access.md`) === true);
     };
     /**
      * The role-shaped principal the splice layer actually writes/matches.
@@ -52,6 +84,10 @@ recoveryAdmins = []) {
     const asSplicePrincipal = (p) => {
         if (p.kind === 'group')
             return { kind: 'role', role: p.group };
+        // Written with the folder's own casing; `parseAccessEntry` canonicalises
+        // the name half to the manifest slug on the way back in.
+        if (p.kind === 'plugin')
+            return { kind: 'role', role: `${PLUGIN_TOKEN_PREFIX}${p.plugin.trim()}/${p.verb}` };
         if (p.kind === 'role') {
             const canonical = canonicalRoleName(p.role);
             const bare = canonical.startsWith(ROLE_TOKEN_PREFIX)
@@ -127,25 +163,49 @@ recoveryAdmins = []) {
             repoRelTarget.split('/').some((segment) => segment === '..')) {
             throw new AccessMutationError('path must stay inside the KB repo');
         }
+        // One spelling per target, as the file verbs and the edit lock require: a
+        // `./README.md` would reach the resolver as a different chain from
+        // `README.md` (and a `./A/x.md` would skip `A/access.md`).
+        if (repoRelTarget.split('/').some((segment) => segment === '.')) {
+            throw new AccessMutationError("path must not contain '.' segments");
+        }
     }
     /**
      * GET /api/workspace/:id/access?path=<relativePath>&kind=<folder|file>
      * Returns the resolved access view for the current user at a single path,
      * including a per-principal `sources` map (where each principal's access comes
-     * from) so the dialog can show inherited-vs-direct. `kind` defaults to `file`
-     * (the resolver treats a folder vs a file's own scope differently only for the
-     * `sources` direct/ancestor split; the eligible/verdict fields are identical).
+     * from) so the dialog can show inherited-vs-direct, the matching `denials` map
+     * (per verb, the entries that DENY it — same direct/ancestor split, closest
+     * first, stopping at a grant that beats them) and `deniedHere` — every
+     * principal a deny ON THIS TARGET names, however many verbs it took. Note what
+     * that is NOT: a partial restriction (edit denied, read still inherited) puts
+     * the principal in `deniedHere` while they stay in the eligible lists for the
+     * verbs they keep; only a principal denied every verb holds nothing and drops
+     * out of those lists. A deny naming a role nobody knows appears in neither
+     * field — the resolver ignores such a line, so it restricts nothing.
+     *
+     * Together those two let the dialog decide its sections by LOCAL ENTRY, grant
+     * or denial, rather than by local grant alone: without them a person
+     * restricted here reads as merely inherited and drops into the collapsed
+     * parent section, looking removed.
+     *
+     * `kind` defaults to `file` (the resolver treats a folder vs a file's own scope
+     * differently only for the direct/ancestor split; the eligible/verdict fields
+     * are identical).
      */
     router.get('/workspace/:id/access', async (req, res) => {
         const user = await requireUser(req, res);
         if (!user)
             return;
         const rawPath = req.query.path;
-        if (typeof rawPath !== 'string' || !rawPath) {
+        const kind = req.query.kind === 'folder' ? 'folder' : 'file';
+        // The dialog addresses the repository root as the empty repo-relative path,
+        // so an empty `path` is the root FOLDER — refusing it left the root
+        // dialog unable to re-read its view after a change.
+        if (typeof rawPath !== 'string' || (!rawPath && kind !== 'folder')) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
-        const kind = req.query.kind === 'folder' ? 'folder' : 'file';
         try {
             // Same sanitize/validate the POST routes apply: strip any kbDir prefix and
             // refuse paths that escape the KB repo before handing to the resolver.
@@ -208,15 +268,81 @@ recoveryAdmins = []) {
             res.status(status).json(body);
         }
     });
+    /**
+     * GET /api/workspace/:id/access/prospective?from=<file>&toDir=<folder>
+     *
+     * Who can open and who can edit one file where it is, and where a move
+     * would put it — `{ before, after }`, each `{ read, write }` lists of
+     * principals named as their grants name them. `toDir` is the destination
+     * FOLDER (`''` is the repo root); the file keeps its name, so the route
+     * derives the destination path itself rather than trusting a second one.
+     *
+     * The destination path does not exist yet, which is why this cannot be two
+     * calls to `GET /access`: the resolver is asked for a hypothetical, with
+     * the file's own frontmatter (read where the file actually is) layered over
+     * the destination's folder chain. Nothing is written and nothing is moved.
+     *
+     * Gated like the sibling `overrides` route rather than the permissive
+     * `GET /access`: the caller must resolve read on the file being moved. The
+     * lists name people, and someone who cannot see the file has no business
+     * learning who can.
+     *
+     * `from` must be a FILE. A folder carries its own `access.md` and governs
+     * everything under it, which is a different question; the resolver refuses
+     * one with a 400 rather than answering it as if it were a file.
+     */
+    router.get('/workspace/:id/access/prospective', async (req, res) => {
+        const user = await requireUser(req, res);
+        if (!user)
+            return;
+        const rawFrom = req.query.from;
+        // An empty `toDir` is the repo ROOT, a real destination — only a missing
+        // one is a bad request.
+        const rawToDir = req.query.toDir;
+        if (typeof rawFrom !== 'string' || !rawFrom) {
+            res.status(400).json({ error: 'from query parameter is required' });
+            return;
+        }
+        if (typeof rawToDir !== 'string') {
+            res.status(400).json({ error: 'toDir query parameter is required' });
+            return;
+        }
+        try {
+            const from = toRepoRelative(rawFrom);
+            assertRepoRelativeTarget(from, 'file');
+            const toDir = toRepoRelative(rawToDir);
+            assertRepoRelativeTarget(toDir, 'folder');
+            if (!(await accessControl.canRead(req.params.id, user.email, from))) {
+                res.status(403).json({ error: 'You do not have access to this file.' });
+                return;
+            }
+            const name = from.slice(from.lastIndexOf('/') + 1);
+            const to = toDir ? `${toDir}/${name}` : name;
+            const { before, after } = await accessControl.prospectiveHolders(req.params.id, from, to);
+            res.json({
+                before: { read: holderPrincipals(before.read), write: holderPrincipals(before.write) },
+                after: { read: holderPrincipals(after.read), write: holderPrincipals(after.write) },
+            });
+        }
+        catch (err) {
+            const { status, body } = toHttpError(err);
+            res.status(status).json(body);
+        }
+    });
     /**
      * POST /api/workspace/:id/access/batch
-     * Body: `{ paths: string[] }`. Returns `{ results: { [path]: boolean } }`.
+     * Body: `{ paths: string[], verb?: 'write' | 'owner' }`. Returns
+     * `{ results: { [path]: boolean } }`.
+     *
+     * `verb` defaults to `write`, the question every existing caller asks.
+     * `owner` answers from the `owner:` lists alone — no admin rescue, and a
+     * writer is not an owner — which is what an Owner pill has to mean.
      */
     router.post('/workspace/:id/access/batch', async (req, res) => {
         const user = await requireUser(req, res);
         if (!user)
             return;
-        const paths = req.body.paths;
+        const { paths, verb = 'write' } = req.body;
         if (!Array.isArray(paths) || paths.some((p) => typeof p !== 'string')) {
             res.status(400).json({ error: 'paths must be an array of strings' });
             return;
@@ -225,8 +351,13 @@ recoveryAdmins = []) {
             res.status(400).json({ error: 'paths cannot exceed 500 entries per request' });
             return;
         }
+        if (verb !== 'write' && verb !== 'owner') {
+            res.status(400).json({ error: 'verb must be "write" or "owner"' });
+            return;
+        }
         try {
-            const result = await accessControl.canWriteBatch(req.params.id, user.email, paths);
+            const batch = verb === 'owner' ? accessControl.canOwnerBatch : accessControl.canWriteBatch;
+            const result = await batch.call(accessControl, req.params.id, user.email, paths);
             const obj = {};
             for (const [k, v] of result)
                 obj[k] = v;
@@ -247,7 +378,9 @@ recoveryAdmins = []) {
      * always show; PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
      * can't dump the whole directory (email-harvesting guard). People are the
      * union of the KB-canonical set (roles.yaml + access.md grants) and the
-     * `users` table (logged-in users). Results are capped.
+     * `users` table (logged-in users). Results are capped. Each person carries
+     * `hasAccount` — false for someone named only in the KB, who has never
+     * signed in — so the dialog can label them; it withholds nobody.
      *
      * A name shared by a group and a role is offered as BOTH — nothing is
      * withheld: grant precedence resolves the collision (bare token = the
@@ -259,14 +392,18 @@ recoveryAdmins = []) {
             return;
         const q = (typeof req.query.q === 'string' ? req.query.q : '').trim().toLowerCase();
         const CAP = 15;
+        // The harvesting guard, named once: it decides both that people are not
+        // returned and that this answer says nothing about accounts. The two must
+        // never disagree — a withheld list is not evidence that nobody has one.
+        const peopleWithheld = q.length < 2;
         try {
             // Independent lookups batched in ONE Promise.all: the default-branch
             // principals (cached model), the branch-local KB people (cached model),
             // and the users table (only consulted once the query is long enough).
-            const [{ roles, groups }, { people: kbPeople }, userRows] = await Promise.all([
+            const [{ roles, groups, plugins }, { people: kbPeople }, userRows] = await Promise.all([
                 defaultBranchPrincipals(),
                 accessControl.kbPrincipals(req.params.id),
-                q.length >= 2 ? db.select().from(users) : Promise.resolve([]),
+                peopleWithheld ? Promise.resolve([]) : db.select().from(users),
             ]);
             const matchedRoles = roles
                 .filter((g) => !q || g.toLowerCase().includes(q))
@@ -274,8 +411,15 @@ recoveryAdmins = []) {
             const matchedGroups = groups
                 .filter((g) => !q || g.toLowerCase().includes(q))
                 .slice(0, CAP);
+            // Plugins the caller can DISCOVER (read the folder's access.md — the
+            // same verdict the plugin index lists on), so the picker never names a
+            // plugin its enumeration would hide. Their `plugin/<Name>/<verb>`
+            // tokens are built client-side; the name is what a person searches for.
+            const matchedPlugins = (await discoverablePlugins(user.email, plugins.filter((p) => !q || p.name.toLowerCase().includes(q))))
+                .map((p) => p.name)
+                .slice(0, CAP);
             let people = [];
-            if (q.length >= 2) {
+            if (!peopleWithheld) {
                 // Union the KB-canonical people with the login-only users table.
                 const byEmail = new Map();
                 for (const p of kbPeople)
@@ -290,15 +434,44 @@ recoveryAdmins = []) {
                         byEmail.set(key, { name: u.name || u.email, email: u.email });
                     }
                 }
+                // A suggestion says whether that person has an ACCOUNT, the same fact
+                // the access view reports: `users` is exactly the set that has signed
+                // in, so a KB-canonical person named only in access rules — someone
+                // granted ahead of their first sign-in — comes back `false` and the
+                // dialog labels the chip it makes of them.
+                const accountEmails = new Set(userRows.map((u) => u.email.trim().toLowerCase()));
                 people = [...byEmail.values()]
                     .filter((p) => p.email.toLowerCase().includes(q) || p.name.toLowerCase().includes(q))
-                    .slice(0, CAP);
+                    // The address actually TYPED is never hidden by the cap. A chip made
+                    // from a free-typed email labels itself by ABSENCE from this list, so
+                    // an exact match dropped at the 15th match would say "hasn't signed
+                    // in yet" about somebody who has. Exact email first, then the rest in
+                    // the order they were unioned (sort is stable), then cap.
+                    .sort((a, b) => Number(b.email.toLowerCase() === q) - Number(a.email.toLowerCase() === q))
+                    .slice(0, CAP)
+                    .map((p) => ({ ...p, hasAccount: accountEmails.has(p.email.trim().toLowerCase()) }));
             }
             res.json({
                 roles: matchedRoles,
                 groups: matchedGroups,
+                // Plugin FOLDER names; each stands for three grantable principals
+                // (`plugin/<Name>/read|write|owner`). Not `plugins` — that key is the
+                // deprecated alias of `roles` below.
+                pluginPrincipals: matchedPlugins,
                 people,
-                peopleWithheld: q.length < 2,
+                peopleWithheld,
+                // THIS ANSWER rules on accounts — not "this build can": every person
+                // above carries `hasAccount`, and an email absent from `people` is
+                // absent because no account exists for it. The dialog labels a
+                // free-typed chip only on this evidence.
+                //
+                // It is therefore false whenever people were WITHHELD: under two
+                // characters the harvesting guard returns nobody, and an empty list
+                // there means "not asked", which is not the same fact at all. An
+                // older server (no such field) and a failed lookup (no response) are
+                // the other two ways to say nothing — all three leave the address
+                // unjudged rather than labelled on a guess.
+                accountsKnown: !peopleWithheld,
                 // DEPRECATED alias of `roles` — the shipped share dialog still reads
                 // `plugins`. Kept populated for ONE release; remove in 0.2.0 together
                 // with the dialog's rename to `roles`.
@@ -351,8 +524,18 @@ recoveryAdmins = []) {
             }
             principal = { kind: 'group', group: principalRaw.group };
         }
+        else if (principalRaw.kind === 'plugin') {
+            if (typeof principalRaw.plugin !== 'string' || !principalRaw.plugin.trim()) {
+                throw new AccessMutationError('plugin principal needs a plugin name');
+            }
+            const verb = principalRaw.verb;
+            if (typeof verb !== 'string' || !PLUGIN_TOKEN_VERBS.includes(verb)) {
+                throw new AccessMutationError(`plugin principal needs a verb: one of ${PLUGIN_TOKEN_VERBS.join(', ')}`);
+            }
+            principal = { kind: 'plugin', plugin: principalRaw.plugin, verb: verb };
+        }
         else {
-            throw new AccessMutationError("principal.kind must be 'user', 'group', or 'role'");
+            throw new AccessMutationError("principal.kind must be 'user', 'group', 'plugin', or 'role'");
         }
         const targetKind = kind;
         const repoRelTarget = toRepoRelative(rawPath);
@@ -363,8 +546,13 @@ recoveryAdmins = []) {
      * The access.md / node path the write lands on, and the path the write-gate
      * keys on. For a folder both are the folder's access.md; for a file they are
      * the node file itself.
+     *
+     * A file that cannot carry frontmatter has no path of its own to edit: this
+     * throws `folder-governs-access` (422) before any gate, lock or read, so the
+     * grant, default revoke and deny-here all refuse it identically.
      */
     function gateAndEditPaths(kind, repoRelTarget) {
+        assertFileCarriesAccessRules(kind, repoRelTarget);
         const editPath = kind === 'folder' ? accessMdPathForFolder(repoRelTarget) : repoRelTarget;
         return { gatePath: editPath, editPath };
     }
@@ -395,72 +583,85 @@ recoveryAdmins = []) {
         void branch;
         void isProtectedBranch;
     }
+    /**
+     * Which of `emails` have an ACCOUNT — a row in `users`, which exists only
+     * once that person has signed in at least once. Emails are stored canonical
+     * (the auth service lowercases every address it writes), so the canonical
+     * forms match the unique index directly and the lookup stays one indexed
+     * query scoped to the addresses asked about.
+     *
+     * Purely informational. No grant is refused, delayed or rewritten because
+     * an email is missing here — pre-provisioning under single sign-on means
+     * granting to an address whose account does not exist yet, and that is a
+     * supported thing to do.
+     */
+    async function accountsAmong(emails) {
+        // `inArray` refuses an empty list, and there is nothing to ask anyway.
+        if (emails.length === 0)
+            return new Set();
+        const rows = await db
+            .select({ email: users.email })
+            .from(users)
+            .where(inArray(users.email, emails));
+        return new Set(rows.map((r) => r.email.trim().toLowerCase()));
+    }
     /** The full resolved-access view returned after a successful mutation. */
     async function resolvedView(workspaceId, repoRelTarget, userEmail, kind) {
-        const [canRead, canWrite, canDownload, canOwner, eligible, readers, owners, downloaders] = await Promise.all([
-            accessControl.canRead(workspaceId, userEmail, repoRelTarget),
-            accessControl.canWrite(workspaceId, userEmail, repoRelTarget),
-            accessControl.canDownload(workspaceId, userEmail, repoRelTarget),
-            accessControl.canOwner(workspaceId, userEmail, repoRelTarget),
-            accessControl.eligibleWriters(workspaceId, repoRelTarget),
-            accessControl.eligibleReaders(workspaceId, repoRelTarget),
-            accessControl.eligibleOwners(workspaceId, repoRelTarget),
-            accessControl.eligibleDownloaders(workspaceId, repoRelTarget),
-        ]);
-        // Per-principal, per-verb origin (direct / ancestor — MECE over editable
-        // files). Keyed `u:<email>` / `r:<role>` / `g:<group>` to match the
-        // dialog's row keys, so each row can show where its access comes from and
-        // which verbs are removable here. Groups get their OWN `g:` namespace: a
-        // group and a role sharing a name are DIFFERENT principals (bare token vs
-        // `role/<name>`), and one shared `r:` entry could only describe one of
-        // them. Each kind resolves through the token spelling that IS that
-        // principal — a group through its bare token (group-first precedence), a
-        // role through its explicit `role/<name>` alias (correct whether or not a
-        // group shadows the name; the built-in `everyone` keeps its bare spelling,
-        // it has no alias). A row whose verbs resolve only via a
-        // group/everyone/rescue has no source (the verb is absent) and renders
-        // non-actionable. Built over the union of every principal in the four
-        // eligible lists (kinded `principals`, with the name-only `roles` list as
-        // the all-roles fallback).
-        const collectives = new Map();
-        for (const list of [eligible, readers, owners, downloaders]) {
-            const kinded = list.principals ?? list.roles.map((name) => ({ name, kind: 'role' }));
-            for (const p of kinded) {
-                const key = `${p.kind === 'group' ? 'g' : 'r'}:${p.name.toLowerCase()}`;
-                if (!collectives.has(key))
-                    collectives.set(key, p);
-            }
+        const resolved = await resolveAccessView(accessControl, workspaceId, repoRelTarget, userEmail, kind);
+        // Every person the view names says whether they have signed in yet, so the
+        // dialog can label a grant made ahead of a first sign-in (`hasAccount:
+        // false`) without changing what the grant does. The flag is read from the
+        // users table each time the view is built, so it flips to true on its own
+        // the first time that person signs in.
+        //
+        // BEST-EFFORT, deliberately: this view is built AFTER the mutation has
+        // committed, so a users lookup that fails must not turn a grant that was
+        // written into a 500 the caller reads as "it did not save". On failure the
+        // flag is simply ABSENT — which the dialog reads as "the server did not
+        // say", not as "no account", so nobody is labelled on a guess.
+        let view = resolved;
+        try {
+            view = labelAccountHolders(resolved, await accountsAmong(emailsInView(resolved)));
         }
-        const userSet = new Map();
-        for (const u of [...eligible.users, ...readers.users, ...owners.users, ...downloaders.users]) {
-            if (!userSet.has(u.email.toLowerCase()))
-                userSet.set(u.email.toLowerCase(), u);
-        }
-        const sources = {};
-        await Promise.all([
-            ...[...collectives.entries()].map(async ([key, p]) => {
-                const token = p.kind === 'role' && canonicalRoleName(p.name) !== EVERYONE_CANONICAL
-                    ? `${ROLE_TOKEN_PREFIX}${p.name}`
-                    : p.name;
-                sources[key] = await accessControl.grantSources(workspaceId, kind, repoRelTarget, {
-                    kind: 'role',
-                    role: token,
-                });
-            }),
-            ...[...userSet.values()].map(async (u) => {
-                sources[`u:${u.email.toLowerCase()}`] = await accessControl.grantSources(workspaceId, kind, repoRelTarget, { kind: 'user', email: u.email });
-            }),
-        ]);
-        return { canRead, canWrite, canDownload, canOwner, eligible, readers, owners, downloaders, sources };
+        catch (err) {
+            // Every piece of this line is caller-controlled — the workspace id and
+            // path come off the request, and the driver's message can carry back
+            // text from the query. `printable` quotes each as one token, the same
+            // rule the rest of the backend's logs follow.
+            logger('access.view.accounts').warn(`users lookup failed for ws=${printable(workspaceId)} path=${printable(repoRelTarget)}; hasAccount omitted: ${printable(err instanceof Error ? err.message : String(err))}`);
+        }
+        // A file that cannot carry frontmatter has no rules of its own: name the
+        // folder whose rules govern it (repo-relative, `''` for the root), which
+        // is where the mutation routes point too.
+        // Content counts as much as the name: bytes that are not text (a binary
+        // saved as `.md`) are refused by the mutations too, so the view must say
+        // so — otherwise the dialog offers a field whose every write answers 422.
+        const governedByFolder = kind === 'file' &&
+            (!fileCarriesAccessRules(repoRelTarget) || !(await mutation.targetHoldsText(workspaceId, repoRelTarget)))
+            ? governingFolderOf(repoRelTarget)
+            : undefined;
+        return { ...view, ...(governedByFolder !== undefined && { governedByFolder }) };
     }
     /**
      * Run a mutation under the edit-file lock: acquire → op (mutation writes
      * under the lock) → release (enqueues the commit + push out of band). Mirrors
      * the human-save `withLock` so protected-branch enforcement + commit-as-user
      * are inherited. On op failure, release WITHOUT committing partial bytes.
+     *
+     * The whole sequence takes the path's TURN first, exactly as `PUT /file`
+     * does (turn outside, lock inside — the same order, so the two can never
+     * wait on each other). The mutation re-reads the file under the lock and
+     * refuses binary content; without the turn an upload landing between that
+     * read and the write would be overwritten by frontmatter, or would arrive
+     * just after the read and turn a refusal into a discard of the upload. The
+     * write inside takes the same turn re-entrantly.
      */
     async function withEditLock(workspaceId, branch, editPath, user, op) {
         const wsEditPath = `${kbDirName}/${editPath}`;
+        return workspaceService.withPathTurn(workspaceId, wsEditPath, () => lockAndRun(workspaceId, branch, wsEditPath, editPath, user, op));
+    }
+    /** The acquire → op → release half of {@link withEditLock}, inside the turn. */
+    async function lockAndRun(workspaceId, branch, wsEditPath, editPath, user, op) {
         const existing = await workflowService.getLock(workspaceId, branch, wsEditPath);
         if (existing && existing.holderUserId === user.id) {
             // Caller already holds the lock (mid-edit) — write without touching it.
@@ -489,7 +690,17 @@ recoveryAdmins = []) {
         }
         catch (err) {
             try {
-                await workflowService.releaseLockNoCommit(workspaceId, branch, wsEditPath, user);
+                // A refusal wrote NOTHING, so the release must leave the disk alone:
+                // `releaseLockNoCommit` discards the path's working-tree changes, and
+                // right after an upload whose commit is still queued that deletes the
+                // upload. Every other failure may have left partial bytes, so it keeps
+                // the discarding release.
+                if (isFolderGovernsRefusal(err)) {
+                    await workflowService.releaseLockUntouched(workspaceId, branch, wsEditPath, user);
+                }
+                else {
+                    await workflowService.releaseLockNoCommit(workspaceId, branch, wsEditPath, user);
+                }
             }
             catch {
                 /* best-effort */
@@ -554,6 +765,19 @@ recoveryAdmins = []) {
                     throw new AccessMutationError(`No group named "${principal.group}". Pick an existing group.`, 404, { kind: 'unknown-group', group: principal.group });
                 }
             }
+            else if (principal.kind === 'plugin') {
+                // A plugin grant must name a plugin the caller can DISCOVER on the
+                // default branch — the same set the suggest list offers, so a plugin
+                // hidden from the picker is refused here with the same words as one
+                // that does not exist. Matched on the manifest slug, the identity the
+                // token canonicalises to.
+                const { plugins } = await defaultBranchPrincipals();
+                const slug = pluginManifestName(principal.plugin);
+                const visible = await discoverablePlugins(user.email, plugins);
+                if (!visible.some((p) => pluginManifestName(p.name) === slug)) {
+                    throw new AccessMutationError(`No plugin named "${principal.plugin}". Pick an existing plugin.`, 404, { kind: 'unknown-plugin', plugin: principal.plugin });
+                }
+            }
             // Splice shape: group → bare token (group-first precedence); role →
             // explicit `role/<Name>` token (see asSplicePrincipal).
             const splicePrincipal = asSplicePrincipal(principal);
@@ -562,6 +786,8 @@ recoveryAdmins = []) {
             await workspaceService.getOrCreateForBranch(branch);
             // Fail-closed gate (BEFORE acquiring the lock).
             await assertCanMutate(workspaceId, branch, user.email, gatePath);
+            // Binary content refuses BEFORE the lock (see assertTargetHoldsText).
+            await mutation.assertTargetHoldsText(workspaceId, kind, repoRelTarget);
             const editPath = gatePath; // grant edits the same path it gates on
             await withEditLock(workspaceId, branch, editPath, user, async () => {
                 await mutation.grant(workspaceId, kind, repoRelTarget, verb, splicePrincipal);
@@ -570,14 +796,14 @@ recoveryAdmins = []) {
             // re-resolve reads the just-written bytes (the async commit's own
             // invalidate is too late for this synchronous response).
             accessControl.invalidate(workspaceId);
-            console.log(`[access.grant] ws=${workspaceId} branch=${branch} byUserId=${user.id} ` +
+            grantLog.info(`ws=${workspaceId} branch=${branch} byUserId=${user.id} ` +
                 `verb=${verb} kind=${kind} target=${repoRelTarget} ` +
                 `principalKind=${principal.kind} -> ok`);
             res.json(await resolvedView(workspaceId, repoRelTarget, user.email, kind));
         }
         catch (err) {
             if (err instanceof AccessDeniedError) {
-                console.warn(`[access.grant.denied] ws=${workspaceId} byUserId=${user.id} -> 403`);
+                logger('access.grant.denied').warn(`ws=${workspaceId} byUserId=${user.id} -> 403`);
             }
             const { status, body } = toHttpError(err);
             res.status(status).json(body);
@@ -673,7 +899,7 @@ recoveryAdmins = []) {
                     await mutation.revoke(workspaceId, 'folder', ancestorDir, principal, user.email, verb, revokeOpts);
                 });
                 accessControl.invalidate(workspaceId);
-                console.log(`[access.revoke.remove-from-parent] ws=${workspaceId} branch=${branch} ` +
+                logger('access.revoke.remove-from-parent').info(`ws=${workspaceId} branch=${branch} ` +
                     `byUserId=${user.id} ancestor=${ancestorDir} target=${repoRelTarget} verb=${verb ?? 'all'} -> ok`);
                 res.json(await resolvedView(workspaceId, repoRelTarget, user.email, kind));
                 return;
@@ -682,12 +908,13 @@ recoveryAdmins = []) {
             if (mode === 'deny-here') {
                 const { gatePath } = gateAndEditPaths(kind, repoRelTarget);
                 await assertCanMutate(workspaceId, branch, user.email, gatePath);
+                await mutation.assertTargetHoldsText(workspaceId, kind, repoRelTarget);
                 await withEditLock(workspaceId, branch, gatePath, user, async () => {
                     // Scope the deny to the same verb the user acted on (if any).
                     await mutation.denyHere(workspaceId, kind, repoRelTarget, principal, verb, revokeOpts);
                 });
                 accessControl.invalidate(workspaceId);
-                console.log(`[access.revoke.deny-here] ws=${workspaceId} branch=${branch} ` +
+                logger('access.revoke.deny-here').info(`ws=${workspaceId} branch=${branch} ` +
                     `byUserId=${user.id} target=${repoRelTarget} verb=${verb ?? 'all'} -> ok`);
                 res.json(await resolvedView(workspaceId, repoRelTarget, user.email, kind));
                 return;
@@ -695,6 +922,7 @@ recoveryAdmins = []) {
             // ---- default: revoke on the target, classified -----------------------
             const { gatePath } = gateAndEditPaths(kind, repoRelTarget);
             await assertCanMutate(workspaceId, branch, user.email, gatePath);
+            await mutation.assertTargetHoldsText(workspaceId, kind, repoRelTarget);
             const editPath = gatePath;
             let changed = false;
             await withEditLock(workspaceId, branch, editPath, user, async () => {
@@ -720,7 +948,7 @@ recoveryAdmins = []) {
                 const sourcesToCheck = verb ? { [verb]: sources[verb] } : sources;
                 const inherited = collectInheritedSources(sourcesToCheck);
                 if (inherited.length > 0) {
-                    console.log(`[access.revoke.inherited] ws=${workspaceId} branch=${branch} byUserId=${user.id} ` +
+                    logger('access.revoke.inherited').info(`ws=${workspaceId} branch=${branch} byUserId=${user.id} ` +
                         `target=${repoRelTarget} ancestors=${inherited.join(',')}`);
                     res.status(409).json({
                         error: "This person's access comes from a parent folder. Remove it there, or restrict just this item.",
@@ -737,20 +965,20 @@ recoveryAdmins = []) {
             // shows an `ancestor` source). The dialog reads that to chain into
             // "Remove from parent?" with no extra response field needed (the old
             // `stillInherited` shortcut is subsumed by the richer per-verb sources).
-            console.log(`[access.revoke] ws=${workspaceId} branch=${branch} byUserId=${user.id} ` +
+            revokeLog.info(`ws=${workspaceId} branch=${branch} byUserId=${user.id} ` +
                 `kind=${kind} target=${repoRelTarget} principalKind=${principal.kind} changed=${changed} -> ok`);
             res.json(await resolvedView(workspaceId, repoRelTarget, user.email, kind));
         }
         catch (err) {
             if (err instanceof AccessDeniedError || err instanceof AccessMutationError) {
-                console.warn(`[access.revoke.denied] ws=${workspaceId} byUserId=${user.id} -> ${err instanceof WorkflowDomainError ? err.status : 500}`);
+                logger('access.revoke.denied').warn(`ws=${workspaceId} byUserId=${user.id} -> ${err instanceof WorkflowDomainError ? err.status : 500}`);
             }
             const { status, body } = toHttpError(err);
             res.status(status).json(body);
         }
     });
     // -------------------------------------------------------------------------
-    // Roles & Members (admin) — MEMBERSHIP editing on the DEFAULT-branch
+    // App roles (admin) — MEMBERSHIP editing on the DEFAULT-branch
     // roles.yaml. Roles are app-defined capabilities: there is deliberately NO
     // create/rename/delete route — the admin surface cannot mint, rebrand, or
     // retire a role (legacy people-set roles migrate out via convert-to-group).
@@ -884,7 +1112,7 @@ recoveryAdmins = []) {
             return;
         try {
             const roles = await rolesAdmin.recover(user);
-            console.warn(`[access.roles.recover] roles.yaml recovered byUserId=${user.id}`);
+            logger('access.roles.recover').warn(`roles.yaml recovered byUserId=${user.id}`);
             res.json({ roles });
         }
         catch (err) {