@1agh/maude 0.53.1 → 0.54.0

package/apps/studio/http.ts

@@ -5,7 +5,7 @@
 // top-level fall-through for paths Bun's `routes` field doesn't cover.
 
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, unlinkSync, watch } from 'node:fs';
 import { dirname, join, posix, relative, resolve, sep } from 'node:path';
 
 import {
@@ -22,6 +22,7 @@ import { type Api, ASSET_MAX_BYTES, ASSET_MAX_VIDEO_BYTES } from './api.ts';
 import { ImportAssetError, importSvg, SVG_MAX_BYTES } from './bin/_import-asset.mjs';
 import { ImportBrandError, importBrand } from './bin/_import-brand.mjs';
 import { buildCanvasModule } from './canvas-build.ts';
+import { buildCanvasSandboxed } from './canvas-build-sandbox.ts';
 import { canvasLibPath } from './canvas-lib-resolver.ts';
 import { TranspileError } from './canvas-pipeline.ts';
 import { createCloudEndpoints } from './cloud/endpoints.ts';
@@ -80,17 +81,19 @@ import {
 import { createGitEndpoints } from './git/endpoints.ts';
 import { gitShowFile } from './git/service.ts';
 import { createGitHubEndpoints } from './github/endpoints.ts';
-import type { Inspect } from './inspect.ts';
+import type { InspectRegistry } from './inspect.ts';
 import { canvasSlug, writeLocator } from './locator.ts';
-import { DEV_SERVER_ROOT, MEDIA_DIR, STICKERS_DIR } from './paths.ts';
+import { BIN_DIR, DEV_SERVER_ROOT, MEDIA_DIR, STICKERS_DIR } from './paths.ts';
 import { createPhotoStore, PHOTO_EDIT_MAX_BYTES } from './photo-store.ts';
 import { probeReadiness } from './readiness.ts';
 import { getRuntimeBundle, packageForSlug } from './runtime-bundle.ts';
+import { currentSession } from './session-scope.ts';
 import { linkHub } from './sync/hub-link.ts';
 import { isHubReadOnly } from './sync/hubs-config.ts';
 import { signInToWorkspace, workspaceDisclosure } from './sync/workspace-signin.ts';
 import { readUiPrefs, type UiPrefs, writeUiPrefs } from './ui-prefs.ts';
 import { loadWhatsNew, resolveMaudeVersion } from './whats-new.ts';
+import { isWorkspaceMode } from './workspace-mode.ts';
 import { isLoopbackHost } from './ws.ts';
 
 // Real disk install root — never the virtual `/$bunfs/root` of compiled bins.
@@ -178,6 +181,25 @@ function ext(p: string): string {
  * do not read it as precedent for adding further hosts without the same
  * scrutiny (exact hostname, no wildcard subdomain, a DDR record).
  */
+/**
+ * A stable, non-revealing name for the tree this process is serving.
+ *
+ * `realpath` first, so a bind-mount and a symlink to the same checkout are the
+ * same identity rather than two — the supervisor computes it from its own
+ * configured path and the two must agree. Falls back to the path as given when
+ * it cannot be resolved: an unresolvable root is a difference worth reporting,
+ * not one worth hiding behind a throw.
+ */
+export function rootIdentity(root: string): string {
+  let resolved = root;
+  try {
+    resolved = realpathSync(root);
+  } catch {
+    /* not on disk (yet) — hash what we were told */
+  }
+  return createHash('sha256').update(resolved, 'utf8').digest('hex').slice(0, 12);
+}
+
 export function cspForCanvasShell(html: string, mainOrigin?: string): string {
   const hashes: string[] = [];
   // Match inline <script> blocks only (no src=). `[^>]*` excludes any with src.
@@ -317,17 +339,48 @@ export const READ_ONLY_ALLOWED_WRITES = new Set([
   '/_api/export-jobs/download',
   '/_api/report', // bug reports are about Maude, not the project
   '/_api/report-fallback',
+  // Cloud Phase 27 — COMMENT IS THE ONE WRITE A VIEWER HOLDS. The role matrix
+  // has said so since Phase 25 C4 (`viewer.comment === true`), the People page
+  // promises it in those words, and the cell's proxy allows it — but this list
+  // did not, so a viewer's comment was accepted by the authority and then
+  // refused by the defence-in-depth layer behind it. Found by commenting as a
+  // viewer against a real cell. A second gate that is STRICTER than the first is
+  // still a gate that is wrong.
+  '/_comments',
   '/_api/hub/link', // link/unlink ≈ session management (cell allows /auth/logout)
   '/_api/workspace/sign-in', // signing in is how the role is (re)learned
   '/_api/workspace/disclosure',
   '/_api/cloud/signin/start', // account session, not project state
   '/_api/cloud/signin/poll',
   '/_api/cloud/signout',
-  '/_api/git/fetch', // syncing the project DOWN is a read of the project
-  '/_api/git/pull',
-  '/_api/git/checkout', // viewing another branch, not changing one
+  // Fetch moves remote-tracking refs and nothing else — no working tree, no
+  // index. It stays a read.
+  '/_api/git/fetch',
+  // `pull` and `checkout` USED TO BE HERE, on the reasoning that "viewing
+  // another branch is not changing one". Cloud Phase 27 D2 retired that: both
+  // rewrite the working tree, and the tree is SHARED — in a cell by every
+  // member, and on a hub-linked desktop by whoever else has that project open.
+  // A viewer switching branches replaces the files under someone mid-edit.
+  //
+  // The proxy's manifest already refuses them, but this gate is the one the
+  // hub-linked desktop and self-host path consult (`isHubReadOnly`), where no
+  // manifest runs at all — so leaving them here would have left the hole open
+  // exactly where the proxy cannot reach. Two gates, and neither is trusted to
+  // be the last word.
 ]);
 
+/**
+ * Write paths a read-only session may use whose members are GENERATED rather
+ * than declared, so an exact-match set cannot name them.
+ *
+ * Deliberately one entry. Every regex here is a hole nobody can see by reading
+ * the list above, so the bar for adding one is that an exact path genuinely
+ * cannot express it.
+ */
+export const READ_ONLY_ALLOWED_WRITE_PATTERNS: RegExp[] = [
+  /^\/_api\/comments\/[A-Za-z0-9_-]+\/reply$/,
+];
+
 /** The refusal a read-only session gets for a project-mutating write. */
 export function readOnlyRefusalResponse(): Response {
   return Response.json(
@@ -502,6 +555,40 @@ async function serveCanvasTsx(
     const source = await file.text();
     const deps = localDepsFromSource(source, absPath, ctx.paths.designRoot);
     let result: Awaited<ReturnType<typeof buildCanvasModule>>;
+    // DDR-209 A′2 — SAME ENGINE, DIFFERENT HOST. On a desktop the process that
+    // parses your canvas is the process you own, so an in-process build costs
+    // nothing. In a cell it holds HUB_SECRET and the tenant's storage
+    // credentials, and the source is written by somebody who is not us — so the
+    // build goes out of process, with an empty environment, an import allowlist
+    // and wall-clock + RSS ceilings (Cloud Phase 25 A1's contract, unchanged).
+    // This branch is also what `sandboxArmed` in the containment boot-assert
+    // attests: the cell may serve the canvas surfaces BECAUSE this exists.
+    if (isWorkspaceMode()) {
+      const built = await buildCanvasSandboxed({
+        designRoot: ctx.paths.designRoot,
+        canvasAbs: absPath,
+      });
+      if (!built.ok) {
+        return new Response(`Canvas build error: ${built.error}`, {
+          status: built.kind === 'build' ? 422 : 500,
+          headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+        });
+      }
+      result = {
+        js: built.js,
+        locator: built.locator,
+        etag: built.etag,
+      } as Awaited<ReturnType<typeof buildCanvasModule>>;
+      cached = {
+        sig: canvasFreshnessSig(absPath, deps),
+        etag: `${result.etag}-${RUNTIME_BOOT_ID}-${CHROME_EPOCH}`,
+        js: result.js,
+        deps,
+      };
+      canvasCache.set(absPath, cached);
+      await writeLocator(locatorAbsPath, canvasSlug(absPath, ctx.paths.designRoot), result.locator);
+      return respondWithCanvasModule(req, cached);
+    }
     try {
       result = await buildCanvasModule(absPath, source, {
         designRoot: ctx.paths.designRoot,
@@ -538,6 +625,13 @@ async function serveCanvasTsx(
     await writeLocator(locatorAbsPath, canvasSlug(absPath, ctx.paths.designRoot), result.locator);
   }
 
+  return respondWithCanvasModule(req, cached);
+}
+
+/** The conditional-GET half of serving a built canvas module. Shared by the
+ *  in-process (desktop) and sandboxed (cell) build paths so the two cannot
+ *  disagree about caching semantics. */
+function respondWithCanvasModule(req: Request, cached: { js: string; etag: string }): Response {
   const ifNoneMatch = req.headers.get('if-none-match');
   if (ifNoneMatch === cached.etag) {
     return new Response(null, {
@@ -650,14 +744,70 @@ async function serveHistoricalCanvas(
   });
 }
 
+/**
+ * How long a served file may be reused — Cloud Phase 27 B2.
+ *
+ * `no-store` on everything is correct on a laptop, where the round trip is a
+ * memcpy and the designer is editing the file you just served. Over the
+ * internet it means a teammate re-downloads every photograph on every pan, on
+ * a project whose media is 266 MB. So:
+ *
+ *   content-addressed name  →  immutable, a year. The name IS the content
+ *                              (sha8), so a changed file is a changed URL and
+ *                              a stale answer is impossible by construction.
+ *   everything else         →  revalidate (`no-cache` + ETag). A designer
+ *                              editing `hero.png` in place still sees their
+ *                              edit; the wire cost of not having changed it is
+ *                              a 304, not the file.
+ *
+ * Universal, not cloud-only: the rule is true on all three shells, and a
+ * caching policy that differs per shell is a bug report nobody can reproduce.
+ */
+export function cacheControlFor(absPath: string): { cacheControl: string; addEtag: boolean } {
+  const name = absPath.slice(absPath.lastIndexOf('/') + 1);
+  // The shape every writer emits — timeline insert/replace/assemble, the asset
+  // upload route, `maude design fetch-asset`: <sha8>.<ext>, lowercase hex.
+  if (/^[0-9a-f]{8,64}\.[A-Za-z0-9]+$/.test(name)) {
+    return { cacheControl: 'public, max-age=31536000, immutable', addEtag: false };
+  }
+  return { cacheControl: 'no-cache', addEtag: true };
+}
+
+/** A weak validator from the file's own metadata — no read, no hash. */
+function etagFor(file: { size: number; lastModified: number }): string {
+  return `W/"${file.size.toString(16)}-${Math.trunc(file.lastModified).toString(16)}"`;
+}
+
+/**
+ * An SVG is a DOCUMENT, and a document runs script.
+ *
+ * `image/svg+xml` is inert as an `<img>`, a CSS `url()` or a `<use>` target —
+ * none of those are browsing contexts. Navigate to one directly and it is a
+ * page, with `<script>` in it, executing on whatever origin served it. On the
+ * canvas origin that is a stored-XSS primitive: canvases carry the tenant's own
+ * SVGs, only the shell HTML gets a CSP, and every other static response here
+ * has carried `nosniff` and nothing else.
+ *
+ * `default-src 'none'; sandbox` costs the legitimate uses nothing (an image is
+ * not a document, so the policy never applies to them) and makes the
+ * navigate-to-it case a blank page instead of a foothold. Found by an
+ * adversarial pass as step one of a three-link cross-tenant chain; the other
+ * two links are closed in the same change, and this is the cheapest of the
+ * three to break.
+ */
+const INERT_DOCUMENT_CSP = "default-src 'none'; sandbox";
+
 async function serveFile(absPath: string, headers: Record<string, string> = {}): Promise<Response> {
   const file = Bun.file(absPath);
   if (!(await file.exists())) return new Response('Not found', { status: 404 });
   const e = ext(absPath);
+  const policy = cacheControlFor(absPath);
   return new Response(file, {
     headers: {
       'Content-Type': MIME[e] || 'application/octet-stream',
-      'Cache-Control': 'no-store',
+      'Cache-Control': policy.cacheControl,
+      ...(policy.addEtag ? { ETag: etagFor(file) } : {}),
+      ...(e === '.svg' ? { 'Content-Security-Policy': INERT_DOCUMENT_CSP } : {}),
       ...headers,
     },
   });
@@ -685,7 +835,9 @@ async function serveMediaFile(
   const size = file.size;
   const base = {
     'Content-Type': MIME[ext(absPath)] || 'application/octet-stream',
-    'Cache-Control': 'no-store',
+    // B2 — same policy as serveFile. Media is the heaviest thing a member
+    // fetches, so the content-addressed case matters most here.
+    'Cache-Control': cacheControlFor(absPath).cacheControl,
     'Accept-Ranges': 'bytes',
     ...headers,
   };
@@ -738,11 +890,18 @@ export interface Http {
 export function createHttp(
   ctx: Context,
   api: Api,
-  inspect: Inspect,
+  /** D3 — one inspector per member. `inspect()` resolves the ambient session's
+   *  instance, which on a desktop is the single one this used to be. */
+  inspects: InspectRegistry,
   ai: AiActivity,
   exportJobs: ExportJobQueue,
   generateJobs: GenerationJobQueue
 ): Http {
+  /** The current request's inspector state (Cloud Phase 27 D3). Resolved per
+   *  call rather than captured, because "whose" changes per request and a
+   *  captured instance would hand one member another's open canvas. */
+  const inspect = () => inspects.for(currentSession());
+
   // Task 2.7 (approach A) — in-flight whisper-model download state (one at a
   // time), polled by the Settings "Download model" card via GET
   // /_api/generate/whisper-model. Closure-scoped: one server, one download.
@@ -905,7 +1064,7 @@ export function createHttp(
     req: Request,
     body: { format: Format; scope: Scope; options?: Record<string, unknown> }
   ) {
-    const activeJson = inspect.state as unknown as ActiveJsonShape;
+    const activeJson = inspect().state as unknown as ActiveJsonShape;
     return {
       format: body.format,
       scope: body.scope,
@@ -935,10 +1094,23 @@ export function createHttp(
         ok: true,
         app: 'design',
         project: ctx.cfg.name,
+        // WHICH TREE THIS PROCESS IS ACTUALLY SERVING — Cloud Phase 27 D5.
+        //
+        // A supervisor that only asks "did something answer" cannot tell a
+        // studio serving the tenant's checkout from one serving whatever was
+        // left in the working directory, and "boots, looks fine, serves the
+        // wrong root" is exactly the mistake `studioLaunch` warns about one
+        // process up. A tag is not an identity; a hash is.
+        //
+        // The HASH and not the path: this route is on the canvas origin's
+        // allowlist, so the tenant's own untrusted code can read it, and a
+        // server filesystem path is not something it should learn. The
+        // supervisor hashes its own expected root and compares.
+        rootId: rootIdentity(ctx.paths.repoRoot),
         pid: process.pid,
       }),
 
-    '/_active': () => Response.json(inspect.state),
+    '/_active': () => Response.json(inspect().state),
 
     // Phase 31 (DDR-123) — ACP chat readiness. Cheap, side-effect-free probe
     // (is the adapter present + is `claude` on PATH); no subprocess spawned.
@@ -1218,11 +1390,45 @@ export function createHttp(
     // knows before it draws anything. It decides what the UI OFFERS and is
     // never what stops a write — the cell enforces that (Phase 25 C1),
     // whatever a patched client believes.
-    '/_config': () =>
+    '/_config': (req: Request) =>
       Response.json({
         ...ctx.cfg,
         canvasOrigin: ctx.canvasOrigin,
-        readOnly: projectReadOnly(),
+        readOnly: projectReadOnly(req),
+        // Cloud Phase 27 (DDR-209) — the capability that opens the cookieless
+        // canvas origin, minted per session by the proxy. Absent on a desktop,
+        // where the canvas origin is loopback and needs none. `canvasUrl()`
+        // appends it exactly the way it already appends `readOnly`, which is
+        // what keeps this a FLAG on the shared client rather than a fork of it.
+        ...(req.headers.get('x-maude-canvas-token')
+          ? { canvasToken: req.headers.get('x-maude-canvas-token') }
+          : {}),
+        // Cloud Phase 27 C2/C4 — the ONE cloud-only input the shared client
+        // takes. Its presence says "you are in a browser tab, on somebody
+        // else's machine", which is what lets the client state the agent's
+        // absence and offer a way back to the dashboard. A flag, not a fork:
+        // every other difference between the three shells stays zero.
+        ...(isWorkspaceMode()
+          ? {
+              cloud: {
+                dashboardUrl: process.env.HUB_DASHBOARD_URL ?? 'https://cloud.maude.sh',
+                projectName: process.env.MAUDE_PROJECT_NAME ?? ctx.cfg.name ?? null,
+                // WHO the tab is signed in as, and WHAT that makes them —
+                // per REQUEST, from the proxy's injected headers, never from
+                // this process's environment (one cell serves an owner and a
+                // viewer at the same time).
+                //
+                // The owner who could not edit his own project could not see
+                // why: the stamp said VIEW ONLY and nothing on screen said
+                // which account that verdict was about. Naming the account and
+                // the role turns "this is broken" into "I am signed in as the
+                // wrong person", which is a thing someone can act on — and the
+                // sign-out beside it is how they act on it.
+                user: req.headers.get('x-maude-user') || null,
+                role: req.headers.get('x-maude-role') || null,
+              },
+            }
+          : {}),
       }),
 
     // What's New feed (DDR-A) — read-only product-update list surfaced in the
@@ -1244,13 +1450,95 @@ export function createHttp(
         buildDebugBundle({
           maudeVersion: resolveMaudeVersion(),
           projectName: ctx.cfg.name ?? null,
-          activeCanvas: (inspect.state as { active?: string | null }).active ?? null,
+          activeCanvas: (inspect().state as { active?: string | null }).active ?? null,
           repoRoot: ctx.paths.repoRoot,
         }),
         { headers: { 'Cache-Control': 'no-store' } }
       );
     },
 
+    // feature-bug-report-button — capture the STUDIO SHELL (menubar, sidebar,
+    // status bar, toasts) as a PNG. `/_api/export` can only ever render a canvas
+    // headlessly, so Maude's own chrome — where most reported UI bugs actually
+    // live — has never been capturable from inside the app. This shells out to
+    // the same `screenshot.sh` spine every `/design:*` capture uses, in its
+    // `--shell` mode, so it inherits engine resolution (the desktop bundle's
+    // agent-browser via MAUDE_AGENT_BROWSER, DDR-144), one-time browser
+    // provisioning, and the playwright fallback.
+    //
+    // The capture is a SEPARATE headless session, not a mirror of the user's
+    // window: it reproduces the app's chrome and the active canvas, but not
+    // transient state (an open dropdown, a stuck spinner). That's why the
+    // dialog keeps the manual attach/paste lane alongside this.
+    //
+    // PRIVILEGED: main-origin only + double gate — it spawns a process and
+    // renders the project, so the untrusted canvas origin must never reach it
+    // (absent from CANVAS_SAFE_API + startCanvasServer routes, per DDR-088).
+    '/_api/shell-shot': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req)) return new Response('cross-origin rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      // Target the very server handling this request — no _server.json read, so
+      // a stale/absent state file can't point the capture at another instance.
+      const port = new URL(req.url).port;
+      if (!/^\d+$/.test(port)) {
+        return Response.json({ error: 'no port on the request URL' }, { status: 500 });
+      }
+      // Which canvas to open is the CLIENT's call, always sent explicitly —
+      // `null` means "open nothing". The server's `_active.json` is global and
+      // sticky (it outlives every closed tab and any session may write it), so
+      // resolving it here would photograph a canvas the reporter never had open.
+      const body = await readJson<{ canvas?: unknown }>(req);
+      const canvas = typeof body?.canvas === 'string' ? body.canvas : '';
+      const out = join(ctx.paths.designRoot, '_reports', `shell-${Date.now()}.png`);
+      try {
+        const proc = Bun.spawn(
+          [
+            'bash',
+            join(BIN_DIR, 'screenshot.sh'),
+            '--shell',
+            '--port',
+            port,
+            '--out',
+            out,
+            '--root',
+            ctx.paths.repoRoot,
+            '--canvas',
+            canvas,
+          ],
+          { stdout: 'ignore', stderr: 'pipe' }
+        );
+        // Booting a browser, loading the studio, opening the active canvas and
+        // painting it runs well past a default fetch timeout on a cold cache;
+        // the dialog shows a pending row meanwhile. Kill rather than hang.
+        const timer = setTimeout(() => proc.kill(), 60_000);
+        const code = await proc.exited;
+        clearTimeout(timer);
+        if (code !== 0 || !existsSync(out)) {
+          const why = (await new Response(proc.stderr).text())
+            .trim()
+            .split('\n')
+            .slice(-3)
+            .join(' ');
+          return Response.json({ error: `shell capture failed: ${why}` }, { status: 502 });
+        }
+        const png = await Bun.file(out).arrayBuffer();
+        // The PNG is handed to the client and never needed again — leaving it on
+        // disk would quietly grow `_reports/` on every dialog open.
+        try {
+          unlinkSync(out);
+        } catch {
+          /* already gone — nothing to clean up */
+        }
+        return new Response(png, {
+          headers: { 'content-type': 'image/png', 'Cache-Control': 'no-store' },
+        });
+      } catch (e) {
+        return Response.json({ error: `shell capture failed: ${String(e)}` }, { status: 502 });
+      }
+    },
+
     // feature-bug-report-button — submit proxy. The client never talks to
     // cloud.maude.sh directly (no CORS surface to open, and the endpoint can be
     // overridden for self-hosters/tests via MAUDE_REPORT_URL). Forwards the
@@ -1371,7 +1659,7 @@ export function createHttp(
         // the api layer — DDR-115). The layout lane mutates the versioned
         // `.meta.json`, so a read-only session is refused here, in-handler,
         // where the two lanes are distinguishable.
-        if (projectReadOnly() && 'layout' in body.patch) {
+        if (projectReadOnly(req) && 'layout' in body.patch) {
           return readOnlyRefusalResponse();
         }
         const next = await api.patchCanvasMeta(body.file, body.patch);
@@ -1504,6 +1792,17 @@ export function createHttp(
       // identity. Color-hash derives from this; falls back to anonymous-<pid>
       // client-side when empty.
       if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      // Cloud Phase 27 — IN A CELL, `git config user.name` IS THE MACHINE.
+      //
+      // It is "Maude Workspace", the committer the autosave agent signs with
+      // (sync/autocommit.ts), and it is the right answer for a commit and the
+      // wrong one for a person: a member opened their project and the presence
+      // chip introduced them as the server. The proxy already vouches who this
+      // is per request, so in a cell that is who it is.
+      const vouched = req.headers.get('x-maude-user');
+      if (isWorkspaceMode() && vouched) {
+        return Response.json({ name: vouched }, { headers: { 'Cache-Control': 'no-store' } });
+      }
       const name = await api.gitCurrentUser();
       return Response.json({ name }, { headers: { 'Cache-Control': 'no-store' } });
     },
@@ -4072,17 +4371,13 @@ export function createHttp(
           if (RANGE_MEDIA_EXTS.has(ext(name))) {
             return serveMediaFile(abs, req, { 'X-Content-Type-Options': 'nosniff' });
           }
-          const f = Bun.file(abs);
-          if (await f.exists()) {
-            return new Response(f, {
-              headers: {
-                'Content-Type': MIME[ext(name)] || 'application/octet-stream',
-                'Cache-Control': 'no-store',
-                'X-Content-Type-Options': 'nosniff',
-              },
-            });
-          }
-          return new Response('Not found', { status: 404 });
+          // B2 — the SAME caching policy as every other static lane. This
+          // route is the one a canvas's photographs actually come down, so
+          // `no-store` here is the difference between a teammate re-fetching
+          // 266 MB of media on every pan and re-fetching none of it. Content-
+          // addressed names (`<sha8>.<ext>`, which is what every writer emits)
+          // are immutable by construction; anything else revalidates.
+          return serveFile(abs, { 'X-Content-Type-Options': 'nosniff' });
         }
       }
 
@@ -4181,15 +4476,38 @@ export function createHttp(
         return serveMediaFile(fp, req, { 'X-Content-Type-Options': 'nosniff' });
       }
       // Bun.file streams transparently for binary content.
+      //
+      // B2 — THIS is the lane a design system's own photographs and webfonts
+      // come down (`system/<ds>/assets/graphics/camo-bg.png`, 446 kB;
+      // `…/fonts/*.woff2`). `no-store` here meant a teammate re-downloaded all
+      // of it on every pan, across the internet, on a project whose media is
+      // 266 MB. Verified against the real one after the first cloud deploy said
+      // `no-store` on exactly these files.
+      //
+      // `cacheControlFor` gives content-addressed names a year and everything
+      // else a revalidation — so a designer editing `hero.png` in place still
+      // sees the edit, at the cost of a 304 rather than the file.
+      const policy = cacheControlFor(fp);
       return new Response(file, {
         headers: {
           'Content-Type': MIME[e] || 'application/octet-stream',
-          'Cache-Control': 'no-store',
+          'Cache-Control': policy.cacheControl,
+          ...(policy.addEtag
+            ? {
+                ETag: `W/"${file.size.toString(16)}-${Math.trunc(file.lastModified).toString(16)}"`,
+              }
+            : {}),
           // DDR-088 follow-up — never let a browser MIME-sniff a served file
           // (e.g. an uploaded GIF/WEBP polyglot) into a richer type. Assets are
           // only referenced via <image href> + the canvas CSP blocks script, so
           // this is defense-in-depth on the static lane.
           'X-Content-Type-Options': 'nosniff',
+          // …and `nosniff` is not enough for the one type that is a DOCUMENT
+          // whether you sniff it or not. See INERT_DOCUMENT_CSP: an SVG
+          // NAVIGATED TO is a page with `<script>` in it, executing on this
+          // origin, and "the canvas CSP blocks script" above is true only of
+          // the shell — not of the asset served on its own.
+          ...(e === '.svg' ? { 'Content-Security-Policy': INERT_DOCUMENT_CSP } : {}),
         },
       });
     } catch (err) {
@@ -4201,7 +4519,7 @@ export function createHttp(
   async function serveCanvasShell(applyCsp: boolean, capture = false): Promise<Response> {
     const shellHtml = await Bun.file(join(TEMPLATES_DIR, '_shell.html')).text();
     // Inject inspector overlay — Cmd+Click selection + add-comment flow.
-    const injected = inspect.injectInspector(shellHtml);
+    const injected = inspect().injectInspector(shellHtml);
     const headers: Record<string, string> = {
       'Content-Type': 'text/html; charset=utf-8',
       'Cache-Control': 'no-store',
@@ -4304,7 +4622,22 @@ export function createHttp(
     if (safe.startsWith(designPrefix)) {
       const rest = safe.slice(designPrefix.length);
       // Reject runtime/state dirs+files (_comments, _sync.json, _history, …).
-      if (rest.split('/').some((seg) => seg.startsWith('_'))) return false;
+      //
+      // FIRST SEGMENT ONLY, and that is the taxonomy rather than a relaxation.
+      // Every runtime-state path DDR-115 names lives at the top level of the
+      // designRoot — `_history/`, `_canvas-state/`, `_state/`, `_chat/`,
+      // `_comments/`, `_untrusted/`, `_trash/`, `_draw/`, `_smoke/`,
+      // `_server.json`, `_active.json` — so a first-segment test rejects the
+      // whole of it, including everything nested underneath.
+      //
+      // Testing EVERY segment additionally rejected files that are versioned,
+      // shipped, and required: a design system's `system/<ds>/preview/
+      // _components.css` is the stylesheet the shell itself names in the
+      // iframe URL, and the underscore there is the DS's own convention for
+      // "aggregate, not a specimen". It 403'd, so every canvas rendered with
+      // its component styles missing and looked broken in a way that pointed
+      // nowhere near this line.
+      if (rest.split('/')[0].startsWith('_')) return false;
       return CANVAS_ASSET_EXTS.has(ext(safe));
     }
     // DDR-150 dogfood — `/assets/<file>`: the canvas-RELATIVE form every writer
@@ -4327,13 +4660,28 @@ export function createHttp(
   // covers all three doors at once: the main-origin `routes` table, the
   // canvas-origin `routes` allowlist in server.ts (it references these same
   // handlers), and the dynamic-path `fetch` fall-through (comment replies).
-  function projectReadOnly(): boolean {
+  function projectReadOnly(req?: Request): boolean {
+    // ---- Cloud Phase 27 A3/A4 (DDR-209): the role is PER SESSION ----------
+    //
+    // In a cell this process serves an owner and a viewer at the same time, so
+    // the on-disk answer below — one role per hub URL — is not merely stale, it
+    // is the wrong SHAPE. The proxy in front vouches a role per request and
+    // injects the capability it derived from the one role table.
+    //
+    // AND IT DEFAULTS CLOSED. The local path fails OPEN by design: `catch`
+    // returns false, an unset `linkedHub` returns false, and a fully writable
+    // studio is the correct answer for a tool running on your own laptop. On
+    // the internet it is the whole ballgame — so in a cloud build read-only is
+    // the default and an edit role requires positive proof.
+    if (isWorkspaceMode()) {
+      return req?.headers.get('x-maude-readonly') !== '0';
+    }
     return ctx.cfg.linkedHub ? isHubReadOnly(ctx.cfg.linkedHub.url) : false;
   }
 
   function readOnlyRefusal(req: Request): Response | null {
     if (READ_ONLY_SAFE_METHODS.has(req.method)) return null;
-    if (!projectReadOnly()) return null;
+    if (!projectReadOnly(req)) return null;
     let pathname: string;
     try {
       pathname = new URL(req.url).pathname;
@@ -4341,6 +4689,10 @@ export function createHttp(
       return readOnlyRefusalResponse();
     }
     if (READ_ONLY_ALLOWED_WRITES.has(pathname)) return null;
+    // The dynamic half of the comment lane. An exact-match set cannot express
+    // it, and leaving it out would mean a viewer may leave a comment but not
+    // reply to one — a distinction nobody promised and nobody wants.
+    if (READ_ONLY_ALLOWED_WRITE_PATTERNS.some((re) => re.test(pathname))) return null;
     return readOnlyRefusalResponse();
   }