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

package/src/modules/access/access-mutation.service.ts

@@ -35,26 +35,24 @@
 
 import path from 'node:path';
 
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import { isTextBytes } from '../workspace/file-readers/text-reader.js';
+import { isTextBytes } from '../workspace/index.js';
 import {
-  type Verb,
   ADMIN_CANONICAL,
   KNOWN_VERBS,
-  ROLE_TOKEN_PREFIX,
   canonicalRoleName,
+  splitPrincipalToken,
   accessFrontmatterExtensionList,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import {
   spliceRevoke,
   spliceGrant,
   validatePrincipal,
   AccessSpliceError,
-  type Principal,
-  type TokenMatch,
-} from '../access-model/access-splice.js';
+} from '../access-model/index.js';
+import type { Verb, Principal, TokenMatch } from '../access-model/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import {
   canCarryFrontmatter,
@@ -90,23 +88,21 @@ export const ADMIN_ROOT_WRITE_MESSAGE =
  * this target touches the Admin ROLE's write at the repository root — the
  * root folder's `access.md`, or a file directly in the root. The resolver
  * ignores such a rule anyway (the Admin write floor), so writing it would only
- * leave a line that says something the app does not do. A bare token matched
- * `exact` is a group's (or a shadowed name's), never the Admin role. Targets
- * arrive in one spelling: the routes refuse `.` and `..` segments.
+ * leave a line that says something the app does not do. A bare `Admin` is the
+ * role (a bare name is always the role when one exists, and roles.yaml always
+ * declares Admin); `group/Admin` is a group and never the role. Targets arrive
+ * in one spelling: the routes refuse `.` and `..` segments.
  */
 export function removesAdminRootWrite(
   kind: TargetKind,
   repoRelTarget: string,
   principal: Principal,
   verb: Verb | undefined,
-  tokenMatch: TokenMatch,
 ): boolean {
   if (principal.kind !== 'role') return false;
   if (!touchesRootWrite(kind, repoRelTarget, verb)) return false;
-  const canonical = canonicalRoleName(principal.role);
-  const explicit = canonical.startsWith(ROLE_TOKEN_PREFIX);
-  if (!explicit && tokenMatch === 'exact') return false;
-  return (explicit ? canonical.slice(ROLE_TOKEN_PREFIX.length) : canonical) === ADMIN_CANONICAL;
+  const { prefix, name } = splitPrincipalToken(canonicalRoleName(principal.role));
+  return prefix !== 'group' && name === ADMIN_CANONICAL;
 }
 
 /** Whether a mutation on `verb` (absent = every verb) at this target reaches write at the repository root. */
@@ -276,38 +272,40 @@ export class AccessMutationService {
   }
 
   /**
-   * How a REVOKE of `principal` matches file tokens — the shadowing rule:
+   * How a REVOKE of `principal` matches file tokens. `'name'` strips the
+   * principal's explicit spelling AND the bare name (never the other kind's
+   * explicit spelling — see `TokenMatch`); `'exact'` strips the literal
+   * spelling alone. The bare name is stripped only when it is THIS
+   * principal's under role-first precedence:
    *
-   *   - When a GROUP owns the principal's bare name (group-first precedence),
-   *     the two spellings are DIFFERENT principals: the bare token is the
-   *     group's, `role/<name>` is the role's. Matching is `'exact'` so
-   *     revoking the role never strips the group's bare grant (and revoking
-   *     the group never strips the role's explicit grant).
-   *   - Unshadowed, both spellings resolve to the ROLE (bare falls back to
-   *     it), so matching is `'name'`: revoking the role also removes legacy
-   *     bare spellings — the historical cleanup behavior.
+   *   - A ROLE (`role/<name>`, or a bare name) owns the bare key unless no
+   *     role of that name exists and a group does — then the bare token is
+   *     the group's, and matching is `'exact'`. A model that fails to load
+   *     keeps it `'exact'` too.
+   *   - A GROUP (`group/<name>`) owns the bare key only while no role of
+   *     that name exists — otherwise the bare token is the role's, and
+   *     matching is `'exact'`. A group that has VANISHED from the active
+   *     source still reads correctly: the question is whether a ROLE holds
+   *     the name. A model that fails to load says nothing about roles, so a
+   *     group revoke then stays `'exact'` rather than risk a role's grant.
    *
    * Judged against THIS workspace's merged principal index (`kbPrincipals` —
    * the same model the resolver reads), so revoke agrees with resolution on
-   * who owns the bare key. A model that fails to load yields no groups, i.e.
-   * unshadowed — matching degrades to the pre-groups name-level behavior.
-   *
-   * GROUP revokes never take the name-level path: the route passes
-   * `tokenMatch: 'exact'` explicitly (see `revoke`'s `opts`), because this
-   * shadow probe cannot tell a group apart from a role once the group has
-   * VANISHED from the active source — the bare name then reads "unshadowed"
-   * and a name-level group revoke would strip a same-named role's live
-   * `role/<Name>` grant.
+   * who owns the bare key.
    */
   private async revokeTokenMatch(workspaceId: string, principal: Principal): Promise<TokenMatch> {
     if (principal.kind !== 'role') return 'exact'; // user matching ignores the mode
-    const canonical = canonicalRoleName(principal.role);
-    const bare = canonical.startsWith(ROLE_TOKEN_PREFIX)
-      ? canonical.slice(ROLE_TOKEN_PREFIX.length)
-      : canonical;
-    const { groups } = await this.accessControl.kbPrincipals(workspaceId);
-    const shadowed = groups.some((g) => canonicalRoleName(g) === bare);
-    return shadowed ? 'exact' : 'name';
+    const { prefix, name } = splitPrincipalToken(canonicalRoleName(principal.role));
+    const { roles, groups } = await this.accessControl.kbPrincipals(workspaceId);
+    const isRole = roles.some((r) => canonicalRoleName(r) === name);
+    if (prefix === 'group') {
+      // `roles` always carries at least `Everyone` once the model loads.
+      return isRole || roles.length === 0 ? 'exact' : 'name';
+    }
+    const isGroup = groups.some((g) => canonicalRoleName(g) === name);
+    // No roles at all means the model failed to load: stay exact, so a role
+    // revoke never strips a same-named group's bare grant.
+    return roles.length === 0 || (!isRole && isGroup) ? 'exact' : 'name';
   }
 
   /**
@@ -372,11 +370,10 @@ export class AccessMutationService {
     // When present, strip ONLY this verb (a per-checkbox toggle in the share UI);
     // absent strips the principal from every verb (the whole-principal Remove).
     verb?: Verb,
-    // `tokenMatch` overrides the shadow-derived matching. The route passes
-    // 'exact' for GROUP principals: a group's grant is its bare token only,
-    // and once the group has vanished the shadow probe can no longer tell it
-    // from a role — name-level matching would then strip a same-named role's
-    // `role/<Name>` grant.
+    // `tokenMatch` overrides the derived matching (see revokeTokenMatch).
+    // One production caller: the plugin-links unlink pins `'exact'` for its
+    // `plugin/<Name>/<verb>` tokens. Pin only `'exact'` — a pinned `'name'`
+    // would bypass the guard that never strips across kinds.
     opts?: { tokenMatch?: TokenMatch },
   ): Promise<{ changed: boolean; editPath: string }> {
     void _actingUserEmail; // referenced to satisfy no-unused-vars until something consumes it
@@ -386,8 +383,8 @@ export class AccessMutationService {
     // missing FILE node is a bad target and should surface, not silently no-op
     // — same rule grant() uses.
     const original = await this.readOrEmpty(workspaceId, kind, repoRelTarget, editPath);
-    // Alias-tolerant vs exact-token matching, decided by group shadowing —
-    // see revokeTokenMatch — unless the caller pinned it.
+    // Alias-tolerant vs exact-token matching, decided by who owns the bare
+    // name — see revokeTokenMatch — unless the caller pinned it.
     const tokenMatch = opts?.tokenMatch ?? (await this.revokeTokenMatch(workspaceId, principal));
     let next = original;
     let changed = false;
@@ -409,7 +406,7 @@ export class AccessMutationService {
     // Refused only when an Admin write entry would really go: a whole-row
     // Remove at a root that grants Admin other verbs but no write line (write
     // comes from the floor) strips those verbs as usual.
-    if (writeRemoved && removesAdminRootWrite(kind, repoRelTarget, principal, verb, tokenMatch)) {
+    if (writeRemoved && removesAdminRootWrite(kind, repoRelTarget, principal, verb)) {
       throw adminRootWriteRefusal();
     }
     if (!changed) return { changed: false, editPath };
@@ -457,7 +454,7 @@ export class AccessMutationService {
     repoRelTarget: string,
     principal: Principal,
     verb?: Verb,
-    // Same override as `revoke` — the route pins 'exact' for GROUP principals.
+    // Same override as `revoke`; no production caller passes it here.
     opts?: { tokenMatch?: TokenMatch },
   ): Promise<{ changed: boolean; editPath: string }> {
     this.assertPrincipalSafe(principal);
@@ -465,10 +462,10 @@ export class AccessMutationService {
     const original = await this.readOrEmpty(workspaceId, kind, repoRelTarget, editPath);
 
     const verbsToDeny = verb ? [verb] : KNOWN_VERBS;
-    // Same shadowing-aware matching as revoke(): the strip must not swallow a
-    // same-named OTHER principal's grant (bare = group vs role/<name> = role).
+    // Same matching as revoke(): the strip must not swallow a same-named
+    // OTHER principal's grant (`group/<name>` vs the role's bare/`role/`).
     const tokenMatch = opts?.tokenMatch ?? (await this.revokeTokenMatch(workspaceId, principal));
-    if (removesAdminRootWrite(kind, repoRelTarget, principal, verb, tokenMatch)) {
+    if (removesAdminRootWrite(kind, repoRelTarget, principal, verb)) {
       throw adminRootWriteRefusal();
     }
     // A PERSON who is an admin keeps root write through the floor, so a deny
@@ -508,10 +505,8 @@ export class AccessMutationService {
 
     // (3) Assert the deny actually removed effective access on the targeted
     // verb(s) — else roll back. The check evaluates the SAME token identity
-    // the deny above spliced (`tokenMatch` rides along): with a pinned exact
-    // GROUP deny whose group has vanished, alias-tolerant matching would read
-    // a same-named role's surviving `role/<Name>` grant as the group still
-    // having access — rolling back a fully effective deny as "ineffective".
+    // the deny above spliced (`tokenMatch` rides along), so a pinned exact
+    // deny is never judged by spellings it did not touch.
     const stillHas = await this.principalStillHasAccess(
       workspaceId,
       kind,
@@ -610,3 +605,9 @@ export class AccessMutationService {
     return new AccessMutationError(err instanceof Error ? err.message : 'mutation failed', 500);
   }
 }
+
+/**
+ * What another module needs of the mutation service: to grant and to revoke.
+ * Injected by the composition root, which owns the implementation.
+ */
+export type IAccessMutation = Pick<AccessMutationService, 'grant' | 'revoke'>;

package/src/modules/access/access-requests.contract.ts

@@ -1,5 +1,5 @@
 import type { AuthUser, ChangeRequest } from '@bevel-software/platform-shared';
-import type { Verb } from '../access-model/access-grammar.js';
+import type { Verb } from '../access-model/index.js';
 import { accessMdPathForFolder, type TargetKind } from './access-mutation.service.js';
 
 /**

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

@@ -1,11 +1,10 @@
 import express from 'express';
-import type { AuthUser } from '@bevel-software/platform-shared';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { AuthService } from '../auth/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   AccessMutationError,
@@ -22,12 +21,8 @@ import {
   type AccessRequestTarget,
   type IAccessRequestLifecycle,
 } from './access-requests.contract.js';
-import {
-  AccessRequestsService,
-  extractRequestNote,
-  itemNameOf,
-} from './access-requests.service.js';
-import '../auth/auth.middleware.js'; // Express Request.userId augmentation
+import { AccessRequestsService, itemNameOf } from './access-requests.service.js';
+import '../auth/index.js'; // Express Request.userId augmentation
 
 const log = logger('access.request');
 
@@ -235,16 +230,16 @@ export function createAccessRequestRoutes(deps: {
       }
       const crs = await workflow.listChangeRequests();
       const rows = await lifecycle.list(target.path, target, crs, user);
-      // The note lives in the request's description and nowhere else, so it
-      // is read back per request. Bounded by the open requests on ONE item —
-      // a handful at most — and a detail that cannot be fetched costs the
-      // note, never the line it belongs to.
+      // The note is the request's own column, read back per request.
+      // Bounded by the open requests on ONE item — a handful at most — and a
+      // detail that cannot be fetched costs the note, never the line it
+      // belongs to.
       const withNotes = await Promise.all(
         rows.map(async (row) => {
           const detail = await workflow
             .getChangeRequestDetail(row.number, { patches: false })
             .catch(() => null);
-          const note = extractRequestNote(detail?.body);
+          const note = detail?.accessRequest?.note;
           return note ? { ...row, note } : row;
         }),
       );

package/src/modules/access/access-requests.service.ts

@@ -10,8 +10,8 @@ import {
 } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import { spliceGrant } from '../access-model/access-splice.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { spliceGrant } from '../access-model/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { logger } from '../../shared/logging.js';
 import { AccessMutationError } from './access-mutation.service.js';
 import {
@@ -50,7 +50,7 @@ export function itemNameOf(repoRelPath: string): string {
 /**
  * Neutralise every character a markdown renderer would read as structure.
  *
- * The note is somebody's free text and it lands in a change request's
+ * The note is somebody's free text and it is quoted in a change request's
  * description, which IS rendered. Escaping it is what makes "plain text" true:
  * without this a note can carry a heading, a link, or an image pointing at a
  * URL that logs whoever opens the request.
@@ -59,64 +59,6 @@ export function escapeMarkdown(text: string): string {
   return text.replace(/[\\`*_{}[\]()#+\-.!|<>~]/g, (c) => `\\${c}`);
 }
 
-/** The exact inverse of {@link escapeMarkdown} — only our own backslashes go. */
-function unescapeMarkdown(text: string): string {
-  return text.replace(/\\([\\`*_{}[\]()#+\-.!|<>~])/g, '$1');
-}
-
-/**
- * The fence the note sits behind in a request's description.
- *
- * The description is the note's only home — there is no column for it — so the
- * editors' banner has to read it back out of prose. Marking the block means
- * that read is exact rather than a guess at which paragraph was the note, and
- * an HTML comment is invisible in every surface that renders the description.
- */
-const NOTE_OPEN = '<!--hexis:access-request-note-->';
-const NOTE_CLOSE = '<!--/hexis:access-request-note-->';
-
-/**
- * The level, recorded on the change request itself.
- *
- * The branch says what is proposed, but only while it can be read — and a
- * clone whose refs are a few seconds stale cannot read a branch cut moments
- * ago. The request's own row always can. "Requested: <level>" is a promise
- * about a request, so it is answered from the request, not from a file at a
- * ref that may not have arrived yet.
- */
-const LEVEL_MARK = /<!--hexis:access-request-level:(write|owner)-->/;
-
-/**
- * The requester's own words, back out of a request's description, or
- * undefined when they wrote none. Unescaped exactly as they were escaped, so
- * what the banner shows is what was typed.
- */
-/**
- * The level a request asks for, off its own description. Undefined for a
- * request opened before this marker existed — those are the skill route's,
- * and the skill route only ever asked for `write`.
- */
-export function extractRequestLevel(body: string | null | undefined): RequestLevel | undefined {
-  const hit = body ? LEVEL_MARK.exec(body) : null;
-  return hit ? (hit[1] as RequestLevel) : undefined;
-}
-
-export function extractRequestNote(body: string | null | undefined): string | undefined {
-  if (!body) return undefined;
-  const start = body.indexOf(NOTE_OPEN);
-  if (start < 0) return undefined;
-  const end = body.indexOf(NOTE_CLOSE, start);
-  if (end < 0) return undefined;
-  const note = body
-    .slice(start + NOTE_OPEN.length, end)
-    .split(/\r?\n/)
-    .filter((line) => line.startsWith('>'))
-    .map((line) => unescapeMarkdown(line.replace(/^>\s?/, '')))
-    .join('\n')
-    .trim();
-  return note || undefined;
-}
-
 /**
  * Asking for Can edit or Owner on ONE item, and reading back what came of it.
  *
@@ -261,11 +203,15 @@ export class AccessRequestsService {
     }
 
     try {
+      // The level and the note are the request's own columns — what the
+      // dialog and the editors' banner read back. The description is for the
+      // people who read the request, and says the same things in prose.
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: kb.defaultBranch,
         title: `Access request: ${itemName}`,
         description: this.describe({ user, target, level, note }),
+        accessRequest: { level, ...(note ? { note } : {}) },
       });
       return { number: detail.number, level };
     } catch (err) {
@@ -331,18 +277,21 @@ export class AccessRequestsService {
   }
 
   /**
-   * The level change request `number` asks for, off its own description.
+   * The level change request `number` asks for, off the request's own row.
    *
-   * `write` when the description does not say: every request that predates the
-   * marker came from the skill page's "Request write access", which asks for
-   * exactly that. A detail that cannot be fetched falls there too — the line
-   * it feeds says which level was asked for, and Can edit is the lesser claim.
+   * The branch says what is proposed, but only while it can be read — and a
+   * clone whose refs are a few seconds stale cannot read a branch cut moments
+   * ago. The request's row always can. `write` when the row does not say:
+   * every request that predates the column came from the skill page's
+   * "Request write access", which asks for exactly that. A detail that cannot
+   * be fetched falls there too — the line it feeds says which level was asked
+   * for, and Can edit is the lesser claim.
    */
   private async levelOf(number: number): Promise<RequestLevel> {
     const detail = await this.deps.workflow
       .getChangeRequestDetail(number, { patches: false })
       .catch(() => null);
-    return extractRequestLevel(detail?.body) ?? 'write';
+    return detail?.accessRequest?.level ?? 'write';
   }
 
   /**
@@ -390,7 +339,12 @@ export class AccessRequestsService {
     }
   }
 
-  /** The description an editor reads: who, what, where, the note, and how to answer. */
+  /**
+   * The description an editor reads: who, what, where, the note, and how to
+   * answer. Prose only — the level and the note the platform reads back are
+   * the request's own columns, so nothing hidden is written here and an edit
+   * of the description loses nothing.
+   */
   private describe(input: {
     user: AuthUser;
     target: AccessRequestTarget;
@@ -400,14 +354,12 @@ export class AccessRequestsService {
     const { user, target, level, note } = input;
     const who = escapeMarkdown(user.name || user.email);
     const lines = [
-      `<!--hexis:access-request-level:${level}-->`,
       `${who} (${escapeMarkdown(user.email)}) asked for **${LEVEL_LABEL[level]}** on ` +
         `${escapeMarkdown(target.path || 'the workspace')}.`,
     ];
     if (note) {
-      lines.push('', `Note from ${who}:`, '', NOTE_OPEN);
+      lines.push('', `Note from ${who}:`, '');
       for (const line of note.split(/\r?\n/)) lines.push(`> ${escapeMarkdown(line)}`);
-      lines.push(NOTE_CLOSE);
     }
     lines.push(
       '',
@@ -418,3 +370,9 @@ export class AccessRequestsService {
     return lines.join('\n');
   }
 }
+
+/**
+ * What another module needs of the access-request service: to open one.
+ * Injected by the composition root, which owns the implementation.
+ */
+export type IAccessRequests = Pick<AccessRequestsService, 'open'>;

package/src/modules/access/access-view.ts

@@ -13,8 +13,9 @@ import {
   EVERYONE_CANONICAL,
   KNOWN_VERBS,
   ROLE_TOKEN_PREFIX,
+  GROUP_TOKEN_PREFIX,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /**
  * The resolved access view of one target, as the Manage access dialog reads it
@@ -51,13 +52,12 @@ export async function resolveAccessView(
   // 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 and a role sharing a name are DIFFERENT principals (`group/<name>`
+  // vs the bare name and `role/<name>`), and one shared `r:` entry could only
+  // describe one of them. Each kind resolves through the explicit token that
+  // IS that principal — a group through `group/<name>`, a role through
+  // `role/<name>` (the built-in `everyone` keeps its bare spelling, it has no
+  // alias); the bare spelling counts toward whichever kind owns it. 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
@@ -96,9 +96,11 @@ export async function resolveAccessView(
   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;
+        p.kind === 'group'
+          ? `${GROUP_TOKEN_PREFIX}${p.name}`
+          : p.kind === 'role' && canonicalRoleName(p.name) !== EVERYONE_CANONICAL
+            ? `${ROLE_TOKEN_PREFIX}${p.name}`
+            : p.name;
       const principal = { kind: 'role' as const, role: token };
       const [grants, denied] = await Promise.all([
         accessControl.grantSources(workspaceId, kind, repoRelTarget, principal),