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

package/src/modules/access/access.routes.ts

@@ -1,6 +1,19 @@
 import express from 'express';
+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 type { AuthUser } from '@bevel-software/platform-shared';
-import { isProtectedBranch, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import {
+  isProtectedBranch,
+  DEFAULT_BRANCH,
+  pluginManifestName,
+  FOLDER_GOVERNS_ACCESS_KIND,
+} from '@bevel-software/platform-shared';
 import type {
   IAccessControl,
   GrantPrincipal,
@@ -17,15 +30,23 @@ import {
   AccessMutationService,
   AccessMutationError,
   accessMdPathForFolder,
+  assertFileCarriesAccessRules,
+  fileCarriesAccessRules,
+  governingFolderOf,
   type TargetKind,
 } from './access-mutation.service.js';
 import {
   canonicalRoleName,
   EVERYONE_CANONICAL,
+  PLUGIN_TOKEN_PREFIX,
+  PLUGIN_TOKEN_VERBS,
   ROLE_TOKEN_PREFIX,
+  type PluginTokenVerb,
   type Verb,
 } from '../access-model/access-grammar.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
+import { emailsInView, holderPrincipals, labelAccountHolders, resolveAccessView } from './access-view.js';
+import type { AccessView, LabelledAccessView } from './access-view.js';
 import { toHttpError as sharedToHttpError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import { RolesAdminService } from './roles-admin.service.js';
 import type { Principal } from '../access-model/access-splice.js';
@@ -48,6 +69,19 @@ function requireNonEmptyString(value: unknown, field: string): string {
   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: unknown): boolean {
+  return (
+    err instanceof AccessMutationError &&
+    err.payload?.kind === FOLDER_GOVERNS_ACCESS_KIND
+  );
+}
+
 export function createAccessRoutes(
   accessControl: IAccessControl,
   workspaceService: WorkspaceService,
@@ -79,20 +113,51 @@ export function createAccessRoutes(
   // accepts — the same principals the admin screens manage, regardless of
   // which branch the caller is viewing. People stay branch-local (the
   // caller's own workspace).
-  const defaultBranchPrincipals = async (): Promise<{ roles: string[]; groups: string[] }> => {
+  const defaultBranchPrincipals = async (): Promise<{
+    roles: string[];
+    groups: string[];
+    plugins: { name: string; folder: string }[];
+  }> => {
     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 ?? [] };
   };
 
   /**
-   * What the mutation routes accept as a principal. `group` exists only at
-   * this boundary: in the access.md entry grammar a group grant is a
-   * bare-name token (bare names resolve GROUP-FIRST, then fall back to the
-   * role), so it is spliced as a role-shaped principal — the separate kind
-   * buys validation against the right namespace and honest 404s.
+   * 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.
    */
-  type RoutePrincipal = Principal | { kind: 'group'; group: string };
+  const discoverablePlugins = async (
+    email: string,
+    plugins: { name: string; folder: string }[],
+  ): Promise<{ name: string; folder: string }[]> => {
+    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);
+  };
+
+  /**
+   * What the mutation routes accept as a principal. `group` and `plugin`
+   * exist only at this boundary: in the access.md entry grammar a group grant
+   * is a bare-name token (bare names resolve GROUP-FIRST, then fall back to
+   * the role) and a plugin grant is the `plugin/<Name>/<verb>` token, so both
+   * are spliced as role-shaped principals — the separate kinds buy validation
+   * against the right namespace and honest 404s.
+   */
+  type RoutePrincipal =
+    | Principal
+    | { kind: 'group'; group: string }
+    | { kind: 'plugin'; plugin: string; verb: PluginTokenVerb };
 
   /**
    * The role-shaped principal the splice layer actually writes/matches.
@@ -104,6 +169,9 @@ export function createAccessRoutes(
    */
   const asSplicePrincipal = (p: RoutePrincipal): Principal => {
     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)
@@ -184,26 +252,50 @@ export function createAccessRoutes(
     ) {
       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: TargetKind = 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: TargetKind = req.query.kind === 'folder' ? 'folder' : 'file';
 
     try {
       // Same sanitize/validate the POST routes apply: strip any kbDir prefix and
@@ -277,15 +369,84 @@ export function createAccessRoutes(
     }
   });
 
+  /**
+   * 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 as { paths?: unknown }).paths;
+    const { paths, verb = 'write' } = req.body as { paths?: unknown; verb?: unknown };
     if (!Array.isArray(paths) || paths.some((p) => typeof p !== 'string')) {
       res.status(400).json({ error: 'paths must be an array of strings' });
       return;
@@ -294,9 +455,15 @@ export function createAccessRoutes(
       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(
+      const batch = verb === 'owner' ? accessControl.canOwnerBatch : accessControl.canWriteBatch;
+      const result = await batch.call(
+        accessControl,
         req.params.id,
         user.email,
         paths as string[],
@@ -320,7 +487,9 @@ export function createAccessRoutes(
    * 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
@@ -332,14 +501,18 @@ export function createAccessRoutes(
 
     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
@@ -350,8 +523,21 @@ export function createAccessRoutes(
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
-      let people: { name: string; email: string }[] = [];
-      if (q.length >= 2) {
+      // 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: { name: string; email: string; hasAccount: boolean }[] = [];
+      if (!peopleWithheld) {
         // Union the KB-canonical people with the login-only users table.
         const byEmail = new Map<string, { name: string; email: string }>();
         for (const p of kbPeople) byEmail.set(p.email.toLowerCase(), p);
@@ -365,16 +551,45 @@ export function createAccessRoutes(
             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`.
@@ -428,8 +643,19 @@ export function createAccessRoutes(
         throw new AccessMutationError('group principal needs a group name');
       }
       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 as readonly string[]).includes(verb)) {
+        throw new AccessMutationError(
+          `plugin principal needs a verb: one of ${PLUGIN_TOKEN_VERBS.join(', ')}`,
+        );
+      }
+      principal = { kind: 'plugin', plugin: principalRaw.plugin, verb: verb as PluginTokenVerb };
     } 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 as TargetKind;
     const repoRelTarget = toRepoRelative(rawPath);
@@ -441,11 +667,16 @@ export function createAccessRoutes(
    * 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: TargetKind, repoRelTarget: string): {
     gatePath: string;
     editPath: string;
   } {
+    assertFileCarriesAccessRules(kind, repoRelTarget);
     const editPath = kind === 'folder' ? accessMdPathForFolder(repoRelTarget) : repoRelTarget;
     return { gatePath: editPath, editPath };
   }
@@ -483,6 +714,28 @@ export function createAccessRoutes(
     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: string[]): Promise<Set<string>> {
+    // `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: string,
@@ -490,69 +743,47 @@ export function createAccessRoutes(
     userEmail: string,
     kind: TargetKind,
   ) {
-    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<string, { name: string; kind: 'role' | 'group' }>();
-    for (const list of [eligible, readers, owners, downloaders]) {
-      const kinded =
-        list.principals ?? list.roles.map((name) => ({ name, kind: 'role' as const }));
-      for (const p of kinded) {
-        const key = `${p.kind === 'group' ? 'g' : 'r'}:${p.name.toLowerCase()}`;
-        if (!collectives.has(key)) collectives.set(key, p);
-      }
-    }
-    const userSet = new Map<string, { name: string; email: string }>();
-    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 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: AccessView | LabelledAccessView = resolved;
+    try {
+      view = labelAccountHolders(resolved, await accountsAmong(emailsInView(resolved)));
+    } 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),
+        )}`,
+      );
     }
-    const sources: Record<string, Awaited<ReturnType<IAccessControl['grantSources']>>> = {};
-    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 };
+    // 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 }) };
   }
 
   /**
@@ -560,6 +791,14 @@ export function createAccessRoutes(
    * 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: string,
@@ -569,6 +808,20 @@ export function createAccessRoutes(
     op: () => Promise<void>,
   ): Promise<void> {
     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: string,
+    branch: string,
+    wsEditPath: string,
+    editPath: string,
+    user: AuthUser,
+    op: () => Promise<void>,
+  ): Promise<void> {
     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.
@@ -598,7 +851,16 @@ export function createAccessRoutes(
       await op();
     } 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 */
       }
@@ -673,6 +935,22 @@ export function createAccessRoutes(
             { 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).
@@ -683,6 +961,8 @@ export function createAccessRoutes(
       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 () => {
@@ -693,17 +973,15 @@ export function createAccessRoutes(
       // 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);
@@ -814,8 +1092,8 @@ export function createAccessRoutes(
         });
 
         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));
@@ -826,13 +1104,14 @@ export function createAccessRoutes(
       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));
@@ -842,6 +1121,7 @@ export function createAccessRoutes(
       // ---- 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;
@@ -875,8 +1155,8 @@ export function createAccessRoutes(
         const sourcesToCheck: GrantSources = 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({
@@ -896,15 +1176,15 @@ export function createAccessRoutes(
       // 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} -> ${
+        logger('access.revoke.denied').warn(
+          `ws=${workspaceId} byUserId=${user.id} -> ${
             err instanceof WorkflowDomainError ? err.status : 500
           }`,
         );
@@ -915,7 +1195,7 @@ export function createAccessRoutes(
   });
 
   // -------------------------------------------------------------------------
-  // 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).
@@ -1045,7 +1325,7 @@ export function createAccessRoutes(
     if (!user) 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) {
       const { status, body } = toHttpError(err);