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

package/src/modules/workspace/write-denial.ts

@@ -7,14 +7,6 @@ import { toKbRelative } from '../access-model/kb-read-filter.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 
-/**
- * Appended to the description of every workspace tool whose refusal is mapped
- * by `writeDenial`, so an agent knows before it is refused that a refusal is
- * not necessarily the end of the road.
- */
-export const PROPOSAL_ROUTE_NOTE =
-  ' If this is refused for permissions, the `write-denied` error says whether you may propose the change instead (create a branch from this one, repeat this call on it, then `open_change_request` into this branch) and lists those steps.';
-
 /** One step of the proposal route, named by the tool the agent calls. */
 export interface ProposalStep {
   tool: string;

package/src/modules/workspace/zip-entry-rules.ts

@@ -0,0 +1,173 @@
+import { inflateRawSync } from 'node:zlib';
+import { validateFilename } from '@bevel-software/platform-shared';
+import { GitInternalsError } from '../../shared/domain-errors.js';
+import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+
+/**
+ * What an archive's entry NAMES are allowed to be, as one set of rules two
+ * surfaces ask: `unzip` (a .zip already in the workspace) and
+ * `apply_file_upload` (a .zip the agent sent to the upload route). Both land
+ * bytes an agent never typed at paths the archive chose, so both have to judge
+ * the same names the same way — and they did not, for as long as the rules
+ * lived inside `WorkspaceService.unzipFile` as three inline blocks.
+ *
+ * NAMES, and how an entry's BYTES are read ({@link readZipEntry}) — the two
+ * things decidable from the archive alone. Whether a target sits behind a
+ * symbolic link already on disk, whether the caller may write there, and what
+ * is already at the path are facts about a workspace, so each surface asks
+ * those where its own writes land.
+ */
+
+/**
+ * The entries an archive from macOS carries that nobody asked for: the
+ * resource-fork sidecar tree and the Finder's own index. SILENTLY dropped
+ * rather than reported — they are not the caller's content and a list of
+ * refusals about them says nothing.
+ */
+export function isZipNoiseEntry(rawName: string): boolean {
+  return (
+    rawName.startsWith('__MACOSX/') ||
+    rawName === '__MACOSX' ||
+    rawName.endsWith('/.DS_Store') ||
+    rawName === '.DS_Store' ||
+    /(^|\/)\._/.test(rawName)
+  );
+}
+
+/**
+ * An entry's name with separators in the one spelling the rules read. A zip
+ * written on Windows may use `\`, which every check below (and every path
+ * built from the result) would otherwise read as part of a single segment.
+ */
+export function zipEntryName(entryName: string): string {
+  return entryName.replace(/\\/g, '/');
+}
+
+/** The path segments `rawName` names, with a trailing slash and empty parts dropped. */
+export function zipEntrySegments(rawName: string): string[] {
+  return rawName
+    .replace(/\/+$/, '')
+    .split('/')
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Why `rawName` may not be landed at all — the reason a caller reports beside
+ * the entry — or null when the name is one a workspace path can be built from.
+ *
+ * Three rules, in the order that makes each refusal say the most useful thing:
+ * a path that climbs out or is anchored at the root is invalid whatever its
+ * segments are; the git folder is refused in every spelling, because an
+ * archive must not be a way to write what git reads as its own metadata; and
+ * then each segment has to be a name a filesystem on any of the three
+ * operating systems keeps intact (`validateFilename`).
+ */
+export function zipEntryNameRefusal(rawName: string): string | null {
+  if (!rawName || rawName.startsWith('/') || /(^|\/)\.\.($|\/)/.test(rawName)) return 'Invalid path';
+  if (hasGitInternalsSegment(rawName)) return new GitInternalsError().message;
+  for (const segment of zipEntrySegments(rawName)) {
+    const reason = validateFilename(segment);
+    if (reason) return reason;
+  }
+  return null;
+}
+
+/**
+ * Whether a zip entry is a symbolic LINK rather than a file or a folder.
+ *
+ * A zip stores a link as an ordinary member whose bytes are the link's target
+ * text and whose unix mode (the high half of the external attributes) carries
+ * `S_IFLNK`. A reader that ignores the mode writes the target text out as a
+ * regular file — content nobody sent, under a name that was meant to point
+ * somewhere. `apply_file_upload` refuses such an entry outright; the entry is
+ * not a file, so there are no bytes of the caller's to land.
+ */
+export function isSymlinkZipEntry(entry: {
+  header?: { attr?: number };
+  attr?: number;
+}): boolean {
+  const attr = entry.header?.attr ?? entry.attr ?? 0;
+  if (!Number.isFinite(attr) || attr <= 0) return false;
+  // The external attributes' high 16 bits are the unix mode when the archive
+  // was written on a unix host; `S_IFMT & mode === S_IFLNK` is the link bit.
+  return ((attr >>> 16) & 0o170000) === 0o120000;
+}
+
+/** A zip's compression method for DEFLATE, the only one that can expand. */
+const ZIP_METHOD_DEFLATED = 8;
+
+/** What {@link readZipEntry} needs of an entry — the part of adm-zip's it reads. */
+export interface ReadableZipEntry {
+  header: { size: number; compressedSize: number; method: number };
+  getData(): Buffer;
+  getCompressedData(): Buffer;
+}
+
+/** An entry's bytes, or why they were not read. */
+export type ZipEntryRead =
+  | { ok: true; data: Buffer }
+  /** The entry is, or would expand to, more than the caller's budget allows. */
+  | { ok: false; reason: 'too_large' }
+  /** The entry cannot be read as what its header says it is. `detail` says how. */
+  | { ok: false; reason: 'unreadable'; detail: string };
+
+/**
+ * Read one entry's bytes, inflating NO MORE than `budget` of them.
+ *
+ * The one read both surfaces use, because the bound is the whole point and it
+ * has a hole when each surface writes it itself. An entry's header DECLARES its
+ * uncompressed size, and the reader caps the inflation at that — but only when
+ * the size it declares is above zero. An entry that declares zero is inflated
+ * with no cap at all, so "check the declared size against the budget, then
+ * read" passes a 20 KB archive that expands to 20 MB, and a 50 MB one that
+ * expands to tens of gigabytes in a single call, before any check on the bytes
+ * that arrived has run. A thousandfold is what deflate does to a run of one
+ * byte; the header saying "empty" was the only thing standing in front of it.
+ *
+ * So the declared size is never the only bound:
+ *
+ *  - an entry declaring more than `budget` is refused unread;
+ *  - a DEFLATED entry declaring ZERO with a stream of its own is inflated here,
+ *    capped at a single byte. An empty file compressed with deflate is exactly
+ *    this shape (a two-byte stream that inflates to nothing) and is read as the
+ *    empty file it is; anything that inflates to a byte or more contradicts its
+ *    own header and is refused;
+ *  - every other entry is read by the archive reader, which caps the inflation
+ *    at the declared size this function has just held against the budget, and
+ *    the bytes that arrive are measured again.
+ *
+ * A read that throws — a failed checksum, a stream longer than it declared, an
+ * unknown method — is that entry's refusal, not the whole archive's: one bad
+ * member must not cost the caller the others.
+ */
+export function readZipEntry(entry: ReadableZipEntry, budget: number): ZipEntryRead {
+  const { size: declared, compressedSize, method } = entry.header;
+  if (declared > budget) return { ok: false, reason: 'too_large' };
+  if (declared === 0 && method === ZIP_METHOD_DEFLATED && compressedSize > 0) {
+    let inflated: Buffer;
+    try {
+      inflated = inflateRawSync(entry.getCompressedData(), { maxOutputLength: 1 });
+    } catch (err) {
+      // Past the one-byte cap, or not a deflate stream at all: either way it
+      // is not the empty file its header says it is.
+      return { ok: false, reason: 'unreadable', detail: declaresEmptyButIsNot(err) };
+    }
+    if (inflated.byteLength > 0) return { ok: false, reason: 'unreadable', detail: declaresEmptyButIsNot() };
+    return { ok: true, data: inflated };
+  }
+  let data: Buffer;
+  try {
+    data = entry.getData();
+  } catch (err) {
+    return { ok: false, reason: 'unreadable', detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (data.byteLength > budget) return { ok: false, reason: 'too_large' };
+  return { ok: true, data };
+}
+
+function declaresEmptyButIsNot(err?: unknown): string {
+  const outputLimit = (err as { code?: string } | undefined)?.code === 'ERR_BUFFER_TOO_LARGE';
+  return err === undefined || outputLimit
+    ? 'its header declares an empty file, but it holds content'
+    : `its header declares an empty file, and its content could not be read (${err instanceof Error ? err.message : String(err)})`;
+}

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

@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { Request, Response } from 'express';
+import {
+  alwaysWritable,
+  createWriteAccessRoutes,
+  createWriteGateMiddleware,
+  isAlwaysWritable,
+  READ_ONLY_CODE,
+  type IWriteAccess,
+} from '../write-access.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ResolveToolContext } from '../../tool-helpers/tool-context.js';
+
+const READ_ONLY_MESSAGE = 'This workspace has 5 people switched on and room for 3.';
+const readOnly: IWriteAccess = { canWrite: async () => ({ ok: false, message: READ_ONLY_MESSAGE }) };
+
+const servers: Server[] = [];
+afterEach(async () => {
+  await Promise.all(servers.splice(0).map((s) => new Promise<void>((resolve) => s.close(() => resolve()))));
+});
+
+async function listen(app: express.Express): Promise<string> {
+  const server = app.listen(0);
+  servers.push(server);
+  await new Promise<void>((resolve) => server.once('listening', () => resolve()));
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+describe('isAlwaysWritable', () => {
+  it.each([
+    ['GET', '/api/workspace/w1/file'],
+    ['HEAD', '/api/workspace/w1/file'],
+    ['POST', '/health'],
+    ['POST', '/api/auth/login'],
+    ['POST', '/api/mcp'],
+    ['POST', '/api/mcp/external-api-keys'],
+    ['POST', '/api/agent/tools/write_file'],
+    ['POST', '/api/admin/accounts'],
+    ['POST', '/api/admin/accounts/u1/deactivate'],
+    ['DELETE', '/api/admin/accounts/u1'],
+    ['POST', '/api/sync'],
+    ['POST', '/api/setup/settings'],
+    ['POST', '/api/workspace/w1/access/batch'],
+    ['POST', '/api/workspace/w1/workflow/locks/heartbeat'],
+    ['POST', '/api/events/s1/focus'],
+  ])('lets %s %s through', (method, path) => {
+    expect(isAlwaysWritable(method, path)).toBe(true);
+  });
+
+  it.each([
+    ['PUT', '/api/workspace/w1/file'],
+    ['DELETE', '/api/workspace/w1/file'],
+    ['POST', '/api/workspace/w1/workflow/changes'],
+    ['POST', '/api/workflow/change-requests/7/merge'],
+    ['POST', '/api/workspace/w1/workflow/locks'],
+    ['POST', '/api/plugins'],
+    ['POST', '/api/admin/groups'],
+    // A look-alike of an allowed path is not that path.
+    ['POST', '/api/admin/accountsx'],
+    ['POST', '/api/workspace/w1/access/batch/extra'],
+    // A route nobody listed is refused by default.
+    ['POST', '/api/some-new-route'],
+    // The API root is inside the gated namespace too.
+    ['POST', '/api'],
+  ])('holds %s %s for the port', (method, path) => {
+    expect(isAlwaysWritable(method, path)).toBe(false);
+  });
+
+  it("lets the host's own paths through", () => {
+    expect(isAlwaysWritable('PUT', '/api/cloud/workspace/billing/seats', ['/api/cloud/workspace/billing'])).toBe(true);
+    expect(isAlwaysWritable('PUT', '/api/cloud/workspace/sign-in/domains', ['/api/cloud/workspace/billing'])).toBe(false);
+  });
+});
+
+describe('createWriteGateMiddleware', () => {
+  function appWith(writeAccess: IWriteAccess) {
+    const app = express();
+    app.use(createWriteGateMiddleware(writeAccess));
+    app.all('/{*any}', (_req, res) => {
+      res.json({ reached: true });
+    });
+    return app;
+  }
+
+  it("refuses a change with the port's words and a code the app recognises", async () => {
+    const base = await listen(appWith(readOnly));
+    const res = await fetch(`${base}/api/workspace/w1/file`, { method: 'PUT' });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual({ error: READ_ONLY_MESSAGE, code: READ_ONLY_CODE });
+  });
+
+  /**
+   * The router matches a path whatever its letter case, so the gate has to
+   * read it the same way: here the route is mounted as the server mounts
+   * its own, under `/api`, and a spelling the gate did not recognise as
+   * that namespace would reach it.
+   */
+  it('refuses a change however the path is cased, since the router matches it either way', async () => {
+    const app = express();
+    app.use(createWriteGateMiddleware(readOnly));
+    const routes = express.Router();
+    const wrote = vi.fn();
+    routes.put('/workspace/:id/file', (_req, res) => {
+      wrote();
+      res.json({ wrote: true });
+    });
+    app.use('/api', routes);
+    const base = await listen(app);
+    for (const path of ['/api/workspace/w1/file', '/API/workspace/w1/file', '/Api/Workspace/w1/File']) {
+      const res = await fetch(`${base}${path}`, { method: 'PUT' });
+      expect({ path, status: res.status }).toEqual({ path, status: 403 });
+    }
+    expect(wrote).not.toHaveBeenCalled();
+  });
+
+  it('keeps an open route open however it is cased', async () => {
+    const base = await listen(appWith(readOnly));
+    expect((await fetch(`${base}/API/Auth/login`, { method: 'POST' })).status).toBe(200);
+  });
+
+  it('still serves reads, and the routes that sign people in and manage accounts', async () => {
+    const base = await listen(appWith(readOnly));
+    expect((await fetch(`${base}/api/workspace/w1/file`)).status).toBe(200);
+    expect((await fetch(`${base}/api/auth/login`, { method: 'POST' })).status).toBe(200);
+    expect((await fetch(`${base}/api/admin/accounts/u1/deactivate`, { method: 'POST' })).status).toBe(200);
+  });
+
+  it('does not ask the port about a request it lets through anyway', async () => {
+    const canWrite = vi.fn(readOnly.canWrite);
+    const base = await listen(appWith({ canWrite }));
+    await fetch(`${base}/api/workspace/w1/file`);
+    await fetch(`${base}/api/auth/login`, { method: 'POST' });
+    expect(canWrite).not.toHaveBeenCalled();
+  });
+
+  it('lets a change through while the port says yes', async () => {
+    const base = await listen(appWith({ canWrite: async () => ({ ok: true }) }));
+    expect((await fetch(`${base}/api/workspace/w1/file`, { method: 'PUT' })).status).toBe(200);
+  });
+
+  it('lets a change through when the port itself fails, rather than freezing the workspace', async () => {
+    const base = await listen(appWith({ canWrite: async () => Promise.reject(new Error('billing down')) }));
+    expect((await fetch(`${base}/api/workspace/w1/file`, { method: 'PUT' })).status).toBe(200);
+  });
+
+  it('is a no-op on core, which is always writable', async () => {
+    const base = await listen(appWith(alwaysWritable));
+    expect((await fetch(`${base}/api/workspace/w1/file`, { method: 'PUT' })).status).toBe(200);
+  });
+});
+
+describe('the tool layer', () => {
+  /**
+   * One tool, mounted the way the server mounts it and called over HTTP: a
+   * parsed body, then an auth step that does not wait for anything, then the
+   * handler. A request closes once its body has been read, so only a real
+   * request shows what the handler makes of that.
+   */
+  async function mounted(writeAccess: IWriteAccess, write: boolean) {
+    const resolve = (async () => ({})) as unknown as ResolveToolContext;
+    const handler = vi.fn(async () => ({ done: true }));
+    const closed = { count: 0 };
+    const app = express();
+    app.use(express.json());
+    app.use((req: Request, res: Response, next) => {
+      req.toolAuth = { source: 'external', userId: 'u1', scope: 'write' } as Request['toolAuth'];
+      res.on('close', () => {
+        closed.count += 1;
+      });
+      next();
+    });
+    app.post('/api/agent/tools/a_tool', createToolHandlerFactory(resolve, writeAccess)(handler as never, { write }));
+    const url = `${await listen(app)}/api/agent/tools/a_tool`;
+    const post = (signal?: AbortSignal) =>
+      fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', signal });
+    return { post, handler, closed };
+  }
+
+  it('refuses a write tool while the deployment is read-only', async () => {
+    const { post, handler } = await mounted(readOnly, true);
+    const res = await post();
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual({ error: READ_ONLY_MESSAGE, code: READ_ONLY_CODE });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  /**
+   * The verdict is awaited, and by then the request has closed: its body was
+   * read. Taken for the client leaving, that left every write tool on a
+   * deployment with a port unanswered, for as long as the caller would wait.
+   */
+  it('answers a write tool the port allows, with the client still there', async () => {
+    const { post, handler } = await mounted({ canWrite: async () => ({ ok: true }) }, true);
+    const res = await post();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ done: true });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not run a write tool whose client left while the verdict was awaited', async () => {
+    const asked = { count: 0 };
+    let allow: () => void = () => undefined;
+    const { post, handler, closed } = await mounted(
+      {
+        canWrite: () => {
+          asked.count += 1;
+          return new Promise((resolve) => {
+            allow = () => resolve({ ok: true });
+          });
+        },
+      },
+      true,
+    );
+    const leaving = new AbortController();
+    const call = post(leaving.signal).catch(() => undefined);
+    await vi.waitFor(() => expect(asked.count).toBe(1));
+    leaving.abort();
+    await call;
+    await vi.waitFor(() => expect(closed.count).toBe(1));
+    allow();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('still runs a read tool', async () => {
+    const { post, handler } = await mounted(readOnly, false);
+    expect((await post()).status).toBe(200);
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('GET /write-access', () => {
+  it("says whether the deployment can be changed, and the port's words when not", async () => {
+    const app = express();
+    app.use('/api', createWriteAccessRoutes(readOnly));
+    const base = await listen(app);
+    expect(await (await fetch(`${base}/api/write-access`)).json()).toEqual({ writable: false, message: READ_ONLY_MESSAGE });
+
+    const open = express();
+    open.use('/api', createWriteAccessRoutes(alwaysWritable));
+    const openBase = await listen(open);
+    expect(await (await fetch(`${openBase}/api/write-access`)).json()).toEqual({ writable: true });
+  });
+});

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

@@ -0,0 +1,153 @@
+import express, { type RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('write-access');
+
+/**
+ * Whether the deployment may be CHANGED right now. The seam a host that
+ * sells seats needs for a workspace that has more people on it than its plan
+ * allows: nobody is removed and everyone can still sign in and read, but
+ * nothing can be edited until an admin brings the count down or the plan up
+ * — the way Notion handles a lapsed workspace.
+ *
+ * Core is always writable. The port is asked on every request that would
+ * change something (a mutating HTTP route, a write tool), so a host answers
+ * from something cheap — its own cached view of the plan.
+ */
+export type WriteAccessVerdict = { ok: true } | { ok: false; message: string };
+
+export interface IWriteAccess {
+  canWrite(): Promise<WriteAccessVerdict>;
+  /**
+   * Paths of the host's own routes that must stay usable while the
+   * deployment is read-only — above all, the ones that END it (buying
+   * seats, the billing portal). Matched as prefixes of the request path.
+   */
+  readonly alwaysWritablePaths?: readonly string[];
+}
+
+/** Core's default: always writable. */
+export const alwaysWritable: IWriteAccess = {
+  canWrite: async () => ({ ok: true }),
+};
+
+/** The `code` a refused write answers with, so a client can tell it from a permission error. */
+export const READ_ONLY_CODE = 'workspace_read_only';
+
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * The mutating routes that stay open while the deployment is read-only.
+ * EVERY OTHER mutating route under `/api` is refused, so a route added
+ * later is read-only until someone decides otherwise — the safe default for
+ * a list nobody re-reads when adding a route.
+ *
+ * What stays open, and why:
+ *  - Signing in and out of everything: sessions, agent connections and
+ *    their keys. A read-only workspace is still one people read.
+ *  - Account administration: the way an admin brings the number of people
+ *    down. Erasing an account with `removeFromAccess` commits to the
+ *    knowledge base, and that commit is part of the same act.
+ *  - The tool surface: every tool call is judged by the tool layer itself,
+ *    which knows a read tool from a write tool (see `toolHandler`); the MCP
+ *    endpoint only relays to it.
+ *  - Deployment setup, tool secrets and pulling remote changes in: the
+ *    deployment's configuration, not its content, and what an admin needs
+ *    to keep it working.
+ *  - Requests that are POST only because they carry a body: permission
+ *    queries, previews, probes, focus and heartbeat signals, fetching
+ *    remotes, accepting a review baseline. None of them changes content.
+ */
+const ALWAYS_WRITABLE: readonly RegExp[] = [
+  /^\/api\/auth\//,
+  /^\/api\/mcp(\/|$)/,
+  /^\/api\/agent\//,
+  /^\/api\/admin\/accounts(\/|$)/,
+  /^\/api\/admin\/connection-keys\//,
+  /^\/api\/audit\//,
+  /^\/api\/sync(\/|$)/,
+  /^\/api\/setup\//,
+  /^\/api\/secrets\//,
+  /^\/api\/admin\/github-facade\//,
+  /^\/api\/workspace\/[^/]+\/access\/batch$/,
+  /^\/api\/workspace\/[^/]+\/review\/accept$/,
+  /^\/api\/workspace\/[^/]+\/flush$/,
+  /^\/api\/workspace\/[^/]+\/workflow\/refresh-remotes$/,
+  /^\/api\/workspace\/[^/]+\/workflow\/locks\/heartbeat$/,
+  /^\/api\/events\/[^/]+\/focus$/,
+  /^\/api\/tools\/preview$/,
+];
+
+/**
+ * Whether a request may go ahead while the deployment is read-only, without asking.
+ *
+ * Judged on the path in LOWER CASE, because that is how the router reads
+ * it: routes match whatever the letter case, so `/API/workspace/…` reaches
+ * the same handler as `/api/workspace/…`. Judged as written, it would be
+ * outside the gated namespace and walk past the gate.
+ */
+export function isAlwaysWritable(method: string, path: string, hostPaths: readonly string[] = []): boolean {
+  if (!MUTATING_METHODS.has(method.toUpperCase())) return true;
+  const asRouted = path.toLowerCase();
+  if (asRouted !== '/api' && !asRouted.startsWith('/api/')) return true;
+  return (
+    ALWAYS_WRITABLE.some((rule) => rule.test(asRouted)) ||
+    hostPaths.some((prefix) => asRouted.startsWith(prefix.toLowerCase()))
+  );
+}
+
+/**
+ * Refuse every change to the deployment while the port says it is
+ * read-only, with a 403 the app recognises by {@link READ_ONLY_CODE}.
+ * Mounted ahead of every route under `/api`; a request the port is not
+ * asked about costs nothing. A port that fails is treated as writable —
+ * a billing lookup that is down must not freeze every workspace.
+ */
+export function createWriteGateMiddleware(writeAccess: IWriteAccess): RequestHandler {
+  if (writeAccess === alwaysWritable) return (_req, _res, next) => next();
+  return async (req, res, next) => {
+    if (isAlwaysWritable(req.method, req.path, writeAccess.alwaysWritablePaths)) return next();
+    let verdict: WriteAccessVerdict;
+    try {
+      verdict = await writeAccess.canWrite();
+    } catch (err) {
+      log.warn('the write-access port failed; letting the request through:', { err });
+      return next();
+    }
+    if (verdict.ok) return next();
+    res.status(403).json({ error: verdict.message, code: READ_ONLY_CODE });
+  };
+}
+
+/**
+ * The verdict for a write tool, the tool layer's half of the gate: `null`
+ * when it may run, the refusal otherwise. Same failure rule as the HTTP gate.
+ */
+export async function refuseWriteTool(writeAccess: IWriteAccess): Promise<string | null> {
+  if (writeAccess === alwaysWritable) return null;
+  try {
+    const verdict = await writeAccess.canWrite();
+    return verdict.ok ? null : verdict.message;
+  } catch (err) {
+    log.warn('the write-access port failed; letting the tool run:', { err });
+    return null;
+  }
+}
+
+/**
+ * GET /api/write-access — whether the deployment can be changed right now,
+ * and if not, the host's words for why. The app reads it to say so once, in
+ * a banner, instead of letting every save fail on its own.
+ */
+export function createWriteAccessRoutes(writeAccess: IWriteAccess): express.Router {
+  const router = express.Router();
+  router.get('/write-access', async (_req, res) => {
+    try {
+      const verdict = await writeAccess.canWrite();
+      res.json(verdict.ok ? { writable: true } : { writable: false, message: verdict.message });
+    } catch {
+      res.json({ writable: true });
+    }
+  });
+  return router;
+}