@bevel-software/platform-core-backend 0.20.0 → 0.22.0

package/src/modules/access/__tests__/access.routes.proposal-branch.test.ts

@@ -16,6 +16,7 @@ import { usersDbDouble } from './users-db-double.js';
 import { AccessControlService } from '../access-control.service.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { branchForWorkspaceId, workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * Manage access on a file that exists ONLY on a change request's branch.
@@ -136,7 +137,7 @@ describe('access routes on a proposal branch (real git)', () => {
         workflowService,
         { emit: () => {} } as unknown as WorkflowEventBus,
         usersDbDouble(),
-        KB,
+        testKbContext({ kbDirName: KB }),
       ),
     );
     server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.prospective.test.ts

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { Database } from '../../database/connection.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { WorkflowDomainError } from '../../../shared/domain-errors.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP contract for `GET /access/prospective` — what the move confirmation
@@ -67,7 +68,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
       {} as unknown as WorkflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       {} as unknown as Database,
-      KB,
+      testKbContext({ kbDirName: KB }),
     ),
   );
 

package/src/modules/access/__tests__/access.routes.revoke.test.ts

@@ -10,6 +10,7 @@ import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP-level contract tests for the revoke route's CLASSIFICATION + MODE logic —
@@ -133,7 +134,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, KB));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

package/src/modules/access/__tests__/access.routes.unknown-email.test.ts

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import type { Database } from '../../database/connection.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * A grant to an email with NO ACCOUNT says so, and stays allowed.
@@ -107,7 +108,7 @@ async function makeHarness(opts: {
       workflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       opts.db ?? usersDbDouble(opts.accounts ?? []),
-      KB,
+      testKbContext({ kbDirName: KB }),
     ),
   );
 

package/src/modules/access/__tests__/change-read-gate.test.ts

@@ -8,6 +8,8 @@ import { AccessControlService } from '../access-control.service.js';
 import { ChangeReadGate, isNewTopLevelFolderPath } from '../change-read-gate.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import { SYNCED_GROUPS_YAML } from '../../access-model/group-files.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
 const WS = 'ws-gate';
@@ -56,7 +58,7 @@ describe('ChangeReadGate', () => {
     await write(repo, 'roles.yaml', ROLES_YAML);
     const ws = stubWorkspaceService(workspaceDir);
     access = new AccessControlService(ws, KB, new NodeFs());
-    gate = new ChangeReadGate(ws, access, KB, new NodeFs());
+    gate = new ChangeReadGate(ws, access, testKbContext({ kbDirName: KB }), new NodeFs());
   });
 
   afterEach(async () => {
@@ -255,18 +257,18 @@ describe('isNewTopLevelFolderPath', () => {
   const exists = async (p: string) => onDisk.has(p);
 
   it('is true for a path inside a folder directly under a creatable root that is not on disk', async () => {
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/New/a.md', 'file', exists)).toBe(true);
-    expect(await isNewTopLevelFolderPath('Skills/fresh/SKILL.md', 'file', exists)).toBe(true);
-    expect(await isNewTopLevelFolderPath('Plugins/team/deep/er/x', 'file', exists)).toBe(true);
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/New', 'dir', exists)).toBe(true);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/New/a.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(true);
+    expect(await isNewTopLevelFolderPath('Skills/fresh/SKILL.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(true);
+    expect(await isNewTopLevelFolderPath('Plugins/team/deep/er/x', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(true);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/New', 'dir', exists, DEFAULT_KB_LAYOUT)).toBe(true);
   });
 
   it('is false when the top-level folder exists, for a loose file at the root, and outside the three roots', async () => {
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/Existing/a.md', 'file', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('Skills/known', 'dir', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/loose.md', 'file', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('KnowledgeBase', 'dir', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('Data/New/a.md', 'file', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('roles.yaml', 'file', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/Existing/a.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('Skills/known', 'dir', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/loose.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase', 'dir', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('Data/New/a.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('roles.yaml', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
   });
 });

package/src/modules/access/__tests__/creator-access.test.ts

@@ -7,6 +7,7 @@ import os from 'node:os';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
 import { CreatorAccessService } from '../creator-access.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
 const WS = 'ws-creator';
@@ -61,7 +62,7 @@ describe('CreatorAccessService.planForCreate', () => {
     await fs.mkdir(path.join(repo, 'Plugins'), { recursive: true });
     await write(repo, 'roles.yaml', ROLES_YAML);
     const ws = stubWorkspaceService(workspaceDir);
-    svc = new CreatorAccessService(ws, new AccessControlService(ws, KB, new NodeFs()), KB, new NodeFs());
+    svc = new CreatorAccessService(ws, new AccessControlService(ws, KB, new NodeFs()), testKbContext({ kbDirName: KB }), new NodeFs());
   });
 
   afterEach(async () => {
@@ -175,7 +176,7 @@ describe('CreatorAccessService.planForCreate', () => {
       },
     });
     const ws = stubWorkspaceService(path.join(root, WS));
-    const withFailingDisk = new CreatorAccessService(ws, new AccessControlService(ws, KB, real), KB, failing);
+    const withFailingDisk = new CreatorAccessService(ws, new AccessControlService(ws, KB, real), testKbContext({ kbDirName: KB }), failing);
     expect(await withFailingDisk.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Projects`, 'dir')).toBeNull();
     expect(await withFailingDisk.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Projects/a.md`, 'file')).toBeNull();
     // The same creation on a disk that answers is planned, so it was the

package/src/modules/access/__tests__/roles.routes.test.ts

@@ -15,6 +15,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { FileTreeEntry } from '@bevel-software/platform-shared';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP-level contract tests for the /api/access/roles routes: the admin gate
@@ -137,7 +138,7 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
     (req as unknown as { userId: string }).userId = ADMIN.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, KB));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

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

@@ -22,10 +22,14 @@ import type {
   ProspectiveHolders,
   ResolvedPrincipal,
 } from './access-control.interface.js';
-import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, isPersonalPluginDir,
+import {
+  DEFAULT_KB_LAYOUT,
+  PLUGIN_MANIFEST_FILE,
+  isPersonalPluginDir,
   pluginIdentityOf,
   platformRestoreDestination,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
@@ -291,13 +295,14 @@ interface AccessScope {
  */
 function accessFileListener(
   repoDir: string,
+  pluginsDir: string,
   out: Map<string, AccessFile>,
   pluginDirs: Map<string, string>,
 ): WalkListener {
   return {
     async onFile(dir, name) {
       const rel = dir ? `${dir}/${name}` : name;
-      if (name === PLUGIN_MANIFEST_FILE && dir.startsWith(`${PLUGINS_DIR}/`)) {
+      if (name === PLUGIN_MANIFEST_FILE && dir.startsWith(`${pluginsDir}/`)) {
         const text = await fs.readFile(path.join(repoDir, rel), 'utf-8').catch(() => null);
         pluginDirs.set(dir, pluginIdentityOf(parseManifestText(text), path.posix.basename(dir)));
         return;
@@ -1301,6 +1306,14 @@ export class AccessControlService implements IAccessControl {
      * many fixtures construct this service directly.
      */
     private readonly gitRunner: IGitRunner = new NodeGitRunner(),
+    /**
+     * The knowledge base's layout — which folder is the plugins root, what the
+     * platform files are called. Read per use, never captured: the roots are
+     * renameable from the setup screen. Defaulted for the same reason as
+     * `deploymentOwners`: the fixtures that construct this service directly
+     * run on the default layout.
+     */
+    private readonly kb: Pick<KbContext, 'layout'> = { layout: DEFAULT_KB_LAYOUT },
   ) {
     this.deploymentOwners = new Set(
       deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)),
@@ -1806,7 +1819,7 @@ export class AccessControlService implements IAccessControl {
         principal.kind === 'plugin' &&
         principal.pluginName &&
         principal.pluginDir &&
-        !isPersonalPluginDir(principal.pluginDir)
+        !isPersonalPluginDir(principal.pluginDir, this.kb.layout)
       ) {
         plugins.set(principal.pluginName, principal.pluginDir);
       }
@@ -1982,7 +1995,7 @@ export class AccessControlService implements IAccessControl {
     userEmail: string,
     destinationRelativePath: string,
   ): Promise<boolean> {
-    const target = platformRestoreDestination(destinationRelativePath);
+    const target = platformRestoreDestination(destinationRelativePath, this.kb.layout);
     if (target === null) return false;
     const email = canonicalEmail(userEmail);
 
@@ -2143,7 +2156,7 @@ export class AccessControlService implements IAccessControl {
     // / `roles.yaml` because `hasPermissionResolved` admin-rescues those
     // paths, so the bad config remains fixable from inside the app.
     const pluginDirs = new Map<string, string>();
-    await this.disk.walkKb(repoDir, [accessFileListener(repoDir, accessFiles, pluginDirs)]);
+    await this.disk.walkKb(repoDir, [accessFileListener(repoDir, this.kb.layout.pluginsDir, accessFiles, pluginDirs)]);
 
     // Plugin principals (`plugin/<Name>/<verb>`), derived from each plugin
     // folder's own access.md — a plugin being a folder with a manifest, at
@@ -2320,11 +2333,12 @@ export class AccessControlService implements IAccessControl {
       const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
       const out: string[] = [];
       const pluginDirs: string[] = [];
+      const { pluginsDir } = this.kb.layout;
       for (const line of stdout.split('\n')) {
         const p = line.trim();
         if (!p) continue;
         if (p === 'access.md' || p.endsWith('/access.md')) out.push(p);
-        else if (p.startsWith(`${PLUGINS_DIR}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
+        else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
           pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
         }
       }

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

@@ -0,0 +1,93 @@
+import type { AuthUser, ChangeRequest } from '@bevel-software/platform-shared';
+import type { Verb } from '../access-model/access-grammar.js';
+import { accessMdPathForFolder, type TargetKind } from './access-mutation.service.js';
+
+/**
+ * The ITEM a request is about — a folder, or a file that carries its own
+ * rules. Everything downstream (the branch name, the file spliced, the
+ * permission checked) is derived from this pair, so a request on a file can
+ * never reach beyond that file.
+ */
+export interface AccessRequestTarget {
+  /** Repo-relative path of the item itself — NOT of its rules file. */
+  path: string;
+  kind: TargetKind;
+}
+
+/** A folder target, spelled once. */
+export function folderTarget(repoRelFolder: string): AccessRequestTarget {
+  return { path: repoRelFolder, kind: 'folder' };
+}
+
+/**
+ * The file whose rules a request on this item edits: a folder's `access.md`,
+ * or the file itself (its own frontmatter). The one place the two cases part,
+ * so a file request writes nothing a sibling can see.
+ */
+export function rulesFileFor(target: AccessRequestTarget): string {
+  return target.kind === 'folder' ? accessMdPathForFolder(target.path) : target.path;
+}
+
+/** The levels the Manage access dialog can ask for. `owner` covers `write`. */
+export type RequestLevel = Extract<Verb, 'write' | 'owner'>;
+export const REQUEST_LEVELS: readonly RequestLevel[] = ['write', 'owner'];
+export function isRequestLevel(value: unknown): value is RequestLevel {
+  return typeof value === 'string' && (REQUEST_LEVELS as readonly string[]).includes(value);
+}
+
+/** The optional note a requester may attach, in characters. */
+export const REQUEST_NOTE_MAX = 500;
+
+/**
+ * One grant a request's branch still proposes. Structurally the plugin
+ * module's `JoinProposal` — stated here so the access module can consume the
+ * request lifecycle without importing the module that implements it (the
+ * dependency runs library → access, and this keeps it that way).
+ */
+export interface AccessProposal {
+  verb: Verb;
+  id: string;
+  principal:
+    | { kind: 'user'; email: string; displayName: string }
+    | { kind: 'role'; role: string };
+  label: string;
+}
+
+/** One open request, as the editors' surfaces render it. */
+export interface AccessRequestSummary {
+  number: number;
+  branch: string;
+  requesterName: string;
+  createdAt: string;
+  proposals: AccessProposal[];
+  /** The requester's note, as plain text, when they gave one. */
+  note?: string;
+}
+
+/**
+ * The request lifecycle, as the access module needs it: what a branch still
+ * proposes, the open requests for an item, and the settle-if-nothing-is-left
+ * check. Implemented by `JoinRequestsService`.
+ *
+ * `key` is what `joinBranchFor` was given when the branch was named — a
+ * plugin's name for a Subscribe request, and the ITEM'S OWN PATH for every
+ * request that comes from the Manage access dialog. Keying a skill folder's
+ * request on its path is what makes the skill page's "Request write access"
+ * and a Can edit request on that same folder one request rather than two.
+ */
+export interface IAccessRequestLifecycle {
+  /** Null ⇒ the branch could not be read; that is not "proposes nothing". */
+  proposalsOn(branch: string, target: AccessRequestTarget): Promise<AccessProposal[] | null>;
+  list(
+    key: string,
+    target: AccessRequestTarget,
+    crs: ChangeRequest[],
+    actor: AuthUser,
+  ): Promise<AccessRequestSummary[]>;
+  reconcile(
+    key: string,
+    target: AccessRequestTarget,
+    cr: ChangeRequest,
+    actor: AuthUser,
+  ): Promise<boolean>;
+}

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

@@ -0,0 +1,286 @@
+import express from 'express';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { 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 { IAccessControl } from './access-control.interface.js';
+import {
+  AccessMutationError,
+  AccessMutationService,
+  fileCarriesAccessRules,
+  governingFolderOf,
+  type TargetKind,
+} from './access-mutation.service.js';
+import { toHttpError as sharedToHttpError } from './admin-route-helpers.js';
+import {
+  isRequestLevel,
+  rulesFileFor,
+  REQUEST_NOTE_MAX,
+  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
+
+const log = logger('access.request');
+
+/**
+ * Asking for Can edit or Owner on one item, and the editors' answer.
+ *
+ *   POST /api/workspace/:id/access/request                  → { ok, number, state, level }
+ *   GET  /api/workspace/:id/access/request?path=&kind=      → { state, level?, number? }
+ *   GET  /api/workspace/:id/access/requests?path=&kind=     → { requests }   (editors)
+ *   POST /api/workspace/:id/access/requests/:n/reconcile    → { closed }
+ *
+ * LIVE WORKSPACE ONLY. A draft branch's rules may differ from the ones the
+ * person is asking about, and a request opened against a draft would propose a
+ * grant into a branch nobody merges — so every route here refuses any
+ * workspace but the default one, rather than quietly retargeting.
+ *
+ * Fail-closed like the rest of the access family: an item the caller cannot
+ * read answers as unknown, and the editors' listing answers `[]` to everyone
+ * else rather than 403 — "am I an editor here" stays a question only the
+ * server answers.
+ */
+export function createAccessRequestRoutes(deps: {
+  accessControl: IAccessControl;
+  workspaceService: WorkspaceService;
+  authService: AuthService;
+  workflow: IWorkflowService;
+  lifecycle: IAccessRequestLifecycle;
+  kb: KbContext;
+}): express.Router {
+  const { accessControl, workspaceService, authService, workflow, lifecycle, kb } = deps;
+  const { kbDirName } = kb;
+  const router = express.Router({ mergeParams: true });
+  const mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
+  const requests = new AccessRequestsService({ workflow, workspaceService, lifecycle, kb });
+
+  async function requireUser(
+    req: express.Request,
+    res: express.Response,
+  ): Promise<AuthUser | null> {
+    if (!req.userId) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return null;
+    }
+    const user = await authService.getUserById(req.userId);
+    if (!user) {
+      res.status(401).json({ error: 'User not found' });
+      return null;
+    }
+    return user;
+  }
+
+  /** Workspace-relative (what the dialog holds) → repo-relative (what the model speaks). */
+  function toRepoRelative(p: string): string {
+    const prefix = `${kbDirName}/`;
+    if (p === kbDirName) return '';
+    return p.startsWith(prefix) ? p.slice(prefix.length) : p;
+  }
+
+  /**
+   * Refuse a target that could escape the KB repo, or that is spelled in more
+   * than one way. Mirrors the grant route's guard — the branch name and the
+   * spliced path are both derived from this string, so two spellings of one
+   * item would be two different requests.
+   */
+  function assertSafeTarget(repoRelTarget: string, kind: TargetKind): void {
+    if (kind === 'file' && !repoRelTarget) {
+      throw new AccessMutationError('file path is required');
+    }
+    if (
+      repoRelTarget.startsWith('/') ||
+      repoRelTarget.includes('\\') ||
+      repoRelTarget.includes('\0') ||
+      repoRelTarget.split('/').some((s) => s === '..' || s === '.')
+    ) {
+      throw new AccessMutationError('path must stay inside the KB repo');
+    }
+  }
+
+  /**
+   * The (live workspace, readable item) pair every route here needs, or null
+   * after the refusal has been answered.
+   *
+   * The two refusals are deliberately different shapes: a non-default
+   * workspace is the CALLER asking the wrong question (400), while an item the
+   * caller cannot read answers exactly as one that does not exist (404) — a
+   * 403 would confirm the item is there.
+   */
+  async function resolveTarget(
+    req: express.Request,
+    res: express.Response,
+    rawPath: unknown,
+    rawKind: unknown,
+  ): Promise<{ user: AuthUser; target: AccessRequestTarget; wsId: string } | null> {
+    const user = await requireUser(req, res);
+    if (!user) return null;
+    const wsId = kb.defaultWorkspaceId();
+    if (branchForWorkspaceId(String(req.params.id)) !== kb.defaultBranch) {
+      res.status(400).json({
+        error: 'Access requests are only made on the live workspace.',
+        kind: 'not-live-workspace',
+      });
+      return null;
+    }
+    if (typeof rawPath !== 'string') {
+      res.status(400).json({ error: 'path is required', kind: 'access-error' });
+      return null;
+    }
+    const kind: TargetKind = rawKind === 'folder' ? 'folder' : 'file';
+    const target: AccessRequestTarget = { path: toRepoRelative(rawPath), kind };
+    try {
+      assertSafeTarget(target.path, kind);
+    } catch (err) {
+      const { status, body } = sharedToHttpError(err, 'access');
+      res.status(status).json(body);
+      return null;
+    }
+    if (!(await accessControl.canRead(wsId, user.email, target.path))) {
+      res.status(404).json({ error: 'Not found', kind: 'unknown-target' });
+      return null;
+    }
+    return { user, target, wsId };
+  }
+
+  /** Can the caller change this item's rules — the gate an Accept runs through. */
+  const isEditor = (wsId: string, email: string, target: AccessRequestTarget) =>
+    accessControl.canWrite(wsId, email, rulesFileFor(target));
+
+  /**
+   * A FILE that cannot hold rules of its own is governed by its folder, and
+   * there is nothing here to request. The dialog already points at the folder
+   * for these; the route says the same thing rather than splicing YAML into a
+   * PDF. Content counts as much as the name — bytes that are not text refuse
+   * too, exactly as the grant route refuses them.
+   */
+  async function assertCanCarryRules(wsId: string, target: AccessRequestTarget): Promise<void> {
+    if (target.kind !== 'file') return;
+    if (fileCarriesAccessRules(target.path) && (await mutation.targetHoldsText(wsId, target.path))) {
+      return;
+    }
+    throw new AccessMutationError(
+      `Access for this file is managed on its folder. Ask there instead.`,
+      409,
+      { kind: 'folder-governs', folder: governingFolderOf(target.path) },
+    );
+  }
+
+  router.post('/workspace/:id/access/request', async (req, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const ctx = await resolveTarget(req, res, body.path, body.kind);
+    if (!ctx) return;
+    const { user, target, wsId } = ctx;
+    try {
+      if (!isRequestLevel(body.level)) {
+        throw new AccessMutationError('level must be "write" or "owner"');
+      }
+      const note = typeof body.note === 'string' ? body.note : '';
+      if (typeof body.note !== 'undefined' && typeof body.note !== 'string') {
+        throw new AccessMutationError('note must be text');
+      }
+      if (note.length > REQUEST_NOTE_MAX) {
+        throw new AccessMutationError(`A note can be at most ${REQUEST_NOTE_MAX} characters.`);
+      }
+      await assertCanCarryRules(wsId, target);
+      if (await isEditor(wsId, user.email, target)) {
+        throw new AccessMutationError(
+          `You can already change who can use this ${target.kind}.`,
+          409,
+          { kind: 'already-writable' },
+        );
+      }
+      const opened = await requests.open({
+        user,
+        target,
+        itemName: itemNameOf(target.path),
+        level: body.level,
+        note,
+      });
+      res.json({ ok: true, state: 'pending', number: opened.number, level: opened.level });
+    } catch (err) {
+      const { status, body: errBody } = sharedToHttpError(err, 'access');
+      if (status >= 500) log.error('failed to open an access request:', { err });
+      res.status(status).json(errBody);
+    }
+  });
+
+  router.get('/workspace/:id/access/request', async (req, res) => {
+    const ctx = await resolveTarget(req, res, req.query.path, req.query.kind);
+    if (!ctx) return;
+    try {
+      res.json(await requests.status(ctx.user, ctx.target));
+    } catch (err) {
+      log.error('failed to read an access request:', { err });
+      res.status(500).json({ error: 'Failed to read the request' });
+    }
+  });
+
+  router.get('/workspace/:id/access/requests', async (req, res) => {
+    const ctx = await resolveTarget(req, res, req.query.path, req.query.kind);
+    if (!ctx) return;
+    const { user, target, wsId } = ctx;
+    try {
+      if (!(await isEditor(wsId, user.email, target))) {
+        res.json({ requests: [] });
+        return;
+      }
+      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.
+      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);
+          return note ? { ...row, note } : row;
+        }),
+      );
+      res.json({ requests: withNotes });
+    } catch (err) {
+      log.error('failed to list access requests:', { err });
+      res.status(500).json({ error: 'Failed to list access requests' });
+    }
+  });
+
+  router.post('/workspace/:id/access/requests/:number/reconcile', async (req, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const ctx = await resolveTarget(req, res, body.path, body.kind);
+    if (!ctx) return;
+    const { user, target, wsId } = ctx;
+    try {
+      if (!(await isEditor(wsId, user.email, target))) {
+        res.status(404).json({ error: 'Not found' });
+        return;
+      }
+      const number = Number(req.params.number);
+      if (!Number.isSafeInteger(number) || number <= 0) {
+        res.status(400).json({ error: 'Invalid change request number' });
+        return;
+      }
+      const cr = await workflow.getChangeRequest(number);
+      if (!cr) {
+        res.status(404).json({ error: 'Not found' });
+        return;
+      }
+      res.json({ closed: await lifecycle.reconcile(target.path, target, cr, user) });
+    } catch (err) {
+      log.error('failed to reconcile an access request:', { err });
+      res.status(500).json({ error: 'Failed to reconcile the request' });
+    }
+  });
+
+  return router;
+}