From 876dbca074794f572867bc22936090d730bd8110 Mon Sep 17 00:00:00 2001
From: Codeman maintainer <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 17:09:00 +0200
Subject: [PATCH] fix(html-view): re-check workspace confinement on every
 served request

The serving route checked the blocklist per request but not
attachmentConfineToWorkspace, while the attachment serve path
(file-routes.ts) re-checks it every time. A capability minted for a
folder outside the workspace before an admin turned confinement on kept
serving that folder for the rest of its TTL.

The capability record now says whether its folder was admitted from
outside the workspace, and the serving route refuses such a record while
confinement is on. The flag is part of the reuse key, so an
out-of-workspace mint never picks up a capability recorded as
in-workspace for the same folder.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/architecture-invariants.md      |  2 +-
 src/html-view-capabilities.ts        | 20 ++++++++++++++------
 src/web/routes/html-view-routes.ts   |  6 +++++-
 test/routes/html-view-routes.test.ts | 20 ++++++++++++++++++++
 4 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md
index 1f47b9ca..c548ee9d 100644
--- a/docs/architecture-invariants.md
+++ b/docs/architecture-invariants.md
@@ -373,7 +373,7 @@ A file path an agent prints is a link on both surfaces it can appear on, and cli
 
 ⚠️ **The terminal routes an out-of-workspace path to the preview, not the log viewer.** The log viewer spawns `tail -f` and allows only the workspace, `/var/log` and `~/logs`, so an external `.log`/`.json`/code path answered `Path must be within working directory or allowed log directories` while the SAME path clicked in the response viewer previewed fine. `activate()` now checks `_isExternalPreviewPath` alongside `previewsInFileViewer`. In-workspace text keeps the tail viewer, which is the point of it (live follow), except `.html`/`.htm`, which always go to the preview so they render as a page (see below); nothing widened `file-stream-manager`'s allowlist, so no `tail -f` is spawned on an arbitrary host path.
 
-**Text reuses the edit-mode allowlist; markup stays download-only.** `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (`config/file-editing.ts`) rather than a second curated list that would drift from it: if the viewer would open a file for editing inside the workspace, the same file outside it can be read. The justification for widening is that the agent in the session can already `cat` any of these and the picker already previews them, so the suffix was never the confidentiality gate; the path guard is (sensitive-file blocklist, `/root` and `/etc` trees, realpath first). ⚠️ Two consequences had to be handled at the same time: `~/.codeman*/state.json` joined `isSensitivePath` (it persists `SessionState.envOverrides`, and the env allowlist admits key-shaped names like `GEMINI_API_KEY`, so it can hold a live credential), and `html`/`htm` joined `svg` in `serveRawFile`'s **download-only** branch so that widening what can be READ never widens what can RUN on our own origin. Text with no dedicated MIME entry goes out as inert `text/plain; charset=utf-8` + `nosniff`, matching the picker. ⚠️ **The one place HTML renders is `/html-view/<cap>/...`** (`html-view-routes.ts`, `html-view-capabilities.ts`), never these routes: `POST /api/sessions/:id/html-view` mints a capability for the HTML file's own directory, and every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin`, so the page is opaque-origin even as a top-level tab and cannot read Codeman or drive its API. The directory is served recursively to the page's scripts (non-dot, asset-allowlisted, realpath-confined, blocklist applied, GET/HEAD only; the dot and extension rules run on the requested name AND on the symlink-resolved target, or a `cfg.json -> .git/config` link would serve the git config), which is why minting is refused for an HTML file in a hidden directory or directly in a broad root (`/`, home, `/tmp`, `/var/tmp` and `$TMPDIR` (named literally, since macOS sets `TMPDIR` in every terminal), the cases and user-space roots, a drive's mount point such as WSL's `/mnt/d`) or in any directory above one of them (`/home`, `/Users`, macOS's `/private`; `isBroadHtmlViewRoot`). The preview renders it by default; the **Page** pill (`htmlRendered`, per-device like `mdRendered`) and any refused mint fall through to the source view with its Edit button. Tests: `test/routes/html-view-routes.test.ts`, the html-view block in `test/webview-auth-exemption.test.ts`, `test/webview-capability-revocation.test.ts`. The by-id text preview is bounded like the workspace one: a `Range` request for the first 512KB (a real partial read, not a discarded 50MB download) plus a 500-line cap, with the footer saying so.
+**Text reuses the edit-mode allowlist; markup stays download-only.** `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (`config/file-editing.ts`) rather than a second curated list that would drift from it: if the viewer would open a file for editing inside the workspace, the same file outside it can be read. The justification for widening is that the agent in the session can already `cat` any of these and the picker already previews them, so the suffix was never the confidentiality gate; the path guard is (sensitive-file blocklist, `/root` and `/etc` trees, realpath first). ⚠️ Two consequences had to be handled at the same time: `~/.codeman*/state.json` joined `isSensitivePath` (it persists `SessionState.envOverrides`, and the env allowlist admits key-shaped names like `GEMINI_API_KEY`, so it can hold a live credential), and `html`/`htm` joined `svg` in `serveRawFile`'s **download-only** branch so that widening what can be READ never widens what can RUN on our own origin. Text with no dedicated MIME entry goes out as inert `text/plain; charset=utf-8` + `nosniff`, matching the picker. ⚠️ **The one place HTML renders is `/html-view/<cap>/...`** (`html-view-routes.ts`, `html-view-capabilities.ts`), never these routes: `POST /api/sessions/:id/html-view` mints a capability for the HTML file's own directory, and every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin`, so the page is opaque-origin even as a top-level tab and cannot read Codeman or drive its API. The directory is served recursively to the page's scripts (non-dot, asset-allowlisted, realpath-confined, blocklist applied, GET/HEAD only; the dot and extension rules run on the requested name AND on the symlink-resolved target, or a `cfg.json -> .git/config` link would serve the git config), which is why minting is refused for an HTML file in a hidden directory or directly in a broad root (`/`, home, `/tmp`, `/var/tmp` and `$TMPDIR` (named literally, since macOS sets `TMPDIR` in every terminal), the cases and user-space roots, a drive's mount point such as WSL's `/mnt/d`) or in any directory above one of them (`/home`, `/Users`, macOS's `/private`; `isBroadHtmlViewRoot`). A capability minted for a folder outside the workspace records that, and the serving route refuses it per request once `attachmentConfineToWorkspace` is on, the same re-check the attachment serve path makes. The preview renders it by default; the **Page** pill (`htmlRendered`, per-device like `mdRendered`) and any refused mint fall through to the source view with its Edit button. Tests: `test/routes/html-view-routes.test.ts`, the html-view block in `test/webview-auth-exemption.test.ts`, `test/webview-capability-revocation.test.ts`. The by-id text preview is bounded like the workspace one: a `Range` request for the first 512KB (a real partial read, not a discarded 50MB download) plus a 500-line cap, with the footer saying so.
 
 **Media is single-sourced across the two preview paths.** `VIDEO_ATTACHMENT_EXTENSIONS` / `AUDIO_ATTACHMENT_EXTENSIONS` live in `attachment-registry.ts` and are imported by `file-content`'s media classification, so a clip plays identically whether it is in the workspace or reached by id from outside it. They diverged first: the workspace path had its own inline sets and the registry allowlist had no media at all, so a video an agent wrote to `/tmp` was refused as an unsupported type while the same file inside the repo played. ⚠️ Three things have to line up for a player rather than a dead frame: the extension in the allowlist, a **real MIME entry** in `MIME_TYPES` (a `<video>` refuses to decode `application/octet-stream`, which presents as a player that renders and then does nothing), and the range-aware body (`serveRawFile` → `sendFileBody`) that makes the scrub bar work. `getAttachmentType()` returns the `video`/`audio` members of `AttachmentDetectedType` for them; the attachment card has no per-type CSS and its thumbnail falls back to the type label, since `generateFirstPageThumbnail` has no media branch and answers 204. ⚠️ The image-watcher keeps its OWN narrow detection list (`png/pdf/docx/pptx`), so this does not start popping cards for every video an agent writes.
 
diff --git a/src/html-view-capabilities.ts b/src/html-view-capabilities.ts
index 9d62ebb4..0137dab2 100644
--- a/src/html-view-capabilities.ts
+++ b/src/html-view-capabilities.ts
@@ -31,6 +31,12 @@ export interface HtmlViewCapabilityRecord {
   rootDir: string;
   /** Username that minted it (multi-user); undefined in single-user mode. */
   owner?: string;
+  /**
+   * Whether the directory lies outside the minting session's workspace (admitted
+   * under the attachment guard). Recorded so the serving route can refuse it the
+   * moment workspace confinement is switched on, as the attachment routes do.
+   */
+  outsideWorkspace: boolean;
   createdAt: number;
 }
 
@@ -44,15 +50,17 @@ export class HtmlViewCapabilityStore {
       ttlMs,
       refreshOnGet: true,
       onExpire: (token, record) => {
-        const key = rootKey(record.rootDir, record.owner);
+        const key = rootKey(record.rootDir, record.owner, record.outsideWorkspace);
         if (this.byRoot.get(key) === token) this.byRoot.delete(key);
       },
     });
   }
 
   /** Mint (or reuse) a capability for a directory. Returns the token. */
-  mint(rootDir: string, owner?: string): string {
-    const key = rootKey(rootDir, owner);
+  mint(rootDir: string, owner?: string, outsideWorkspace = false): string {
+    // The flag is part of the key: an out-of-workspace mint must never reuse a
+    // capability recorded as in-workspace, which confinement would not stop.
+    const key = rootKey(rootDir, owner, outsideWorkspace);
     const existing = this.byRoot.get(key);
     if (existing && this.capabilities.get(existing)) return existing;
     if (existing) this.byRoot.delete(key);
@@ -60,7 +68,7 @@ export class HtmlViewCapabilityStore {
     if (this.capabilities.size >= MAX_WEBVIEW_CAPABILITIES) this.capabilities.cleanup();
 
     const token = randomBytes(24).toString('base64url');
-    this.capabilities.set(token, { rootDir, owner, createdAt: Date.now() });
+    this.capabilities.set(token, { rootDir, owner, outsideWorkspace, createdAt: Date.now() });
     this.byRoot.set(key, token);
     return token;
   }
@@ -95,8 +103,8 @@ export class HtmlViewCapabilityStore {
   }
 }
 
-function rootKey(rootDir: string, owner: string | undefined): string {
-  return `${owner ?? ''}\0${rootDir}`;
+function rootKey(rootDir: string, owner: string | undefined, outsideWorkspace: boolean): string {
+  return `${owner ?? ''}\0${outsideWorkspace ? 'out' : 'in'}\0${rootDir}`;
 }
 
 /** The capability token in an `/html-view/<cap>/...` path, or null. */
diff --git a/src/web/routes/html-view-routes.ts b/src/web/routes/html-view-routes.ts
index eda18688..dab9b4c5 100644
--- a/src/web/routes/html-view-routes.ts
+++ b/src/web/routes/html-view-routes.ts
@@ -201,7 +201,7 @@ export function registerHtmlViewRoutes(app: FastifyInstance, ctx: SessionPort):
       return;
     }
 
-    const cap = htmlViewCapabilities.mint(dirname(resolvedPath), ownerFor(req));
+    const cap = htmlViewCapabilities.mint(dirname(resolvedPath), ownerFor(req), !inWorkspace);
     return {
       success: true,
       data: { url: `${HTML_VIEW_PREFIX}/${cap}/${encodeURIComponent(basename(resolvedPath))}` },
@@ -238,6 +238,10 @@ export function registerHtmlViewRoutes(app: FastifyInstance, ctx: SessionPort):
     if (!contentType) return notFound();
     const guard = await loadAttachmentGuardConfig();
     if (isBlockedAttachmentPath(resolvedPath, guard.blockedTrees)) return notFound();
+    // Re-checked per request, like the attachment serve path (file-routes.ts): a
+    // page minted from outside the workspace before an admin switched confinement
+    // on stops serving once it is on, instead of living out its capability.
+    if (record.outsideWorkspace && guard.confineToWorkspace) return notFound();
 
     const stat = await fs.stat(resolvedPath).catch(() => null);
     if (!stat?.isFile() || exceedsDownloadLimit(stat.size)) return notFound();
diff --git a/test/routes/html-view-routes.test.ts b/test/routes/html-view-routes.test.ts
index f160755b..6fb7db48 100644
--- a/test/routes/html-view-routes.test.ts
+++ b/test/routes/html-view-routes.test.ts
@@ -153,6 +153,26 @@ describe('html-view routes', () => {
       expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(403);
     });
 
+    it('stops serving an out-of-workspace page once confinement is switched on', async () => {
+      const res = await open(join(outsideDir, 'report.html'));
+      expect(res.statusCode).toBe(200);
+      const url = JSON.parse(res.body).data.url as string;
+      expect((await harness.app.inject({ method: 'GET', url })).statusCode).toBe(200);
+      const inside = await openUrl();
+
+      process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
+      expect((await harness.app.inject({ method: 'GET', url })).statusCode).toBe(404);
+      // A page minted from inside the workspace is not affected.
+      expect((await harness.app.inject({ method: 'GET', url: inside })).statusCode).toBe(200);
+    });
+
+    it('never reuses an in-workspace capability for the same folder minted from outside', () => {
+      const inside = htmlViewCapabilities.mint(outsideDir, undefined, false);
+      const outside = htmlViewCapabilities.mint(outsideDir, undefined, true);
+      expect(outside).not.toBe(inside);
+      expect(htmlViewCapabilities.resolve(outside)?.outsideWorkspace).toBe(true);
+    });
+
     it('refuses every out-of-workspace page when attachments are confined to the workspace', async () => {
       process.env.CODEMAN_ATTACHMENT_CONFINE = '1';
       expect((await open(join(outsideDir, 'report.html'))).statusCode).toBe(403);