COD-37 add server-side attachment pipeline (registry, magic-link, path guard)

Adds the foundation for serving local files to the browser as live external
attachments with a stable id, so requests never carry arbitrary absolute paths.

- attachment-registry: in-memory, session-scoped registry. registerExternalAttachment
  validates an absolute path, resolves symlinks, enforces the path guard, and mints
  an `att_<uuid>` id; records are cleared when the session is removed.
- attachment path guard: a configurable blocklist (secret locations + /root,/etc
  trees, extendable via attachmentBlockedPaths / CODEMAN_ATTACHMENT_BLOCKED_PATHS)
  plus an optional, default-off workspace-confinement mode. Shares one
  sensitive-path blocklist (web/sensitive-path.ts) with /api/download, which is
  refactored to use the extracted module instead of an inline copy.
- terminal magic links: the session scans output for codeman://attach?path=... and
  emits `attachmentRequested`; the web server registers the file and broadcasts an
  `attachment:detected` SSE event. `codeman attach <path>` (CLI) prints the magic
  link or POSTs directly when a session id is known.
- image watcher: detects png/pdf/docx/pptx dropped into a session's working dir and
  emits `attachment:detected`.
- routes: POST /api/sessions/:id/attachments (register) and
  GET /api/sessions/:id/attachments/:attachmentId/raw (serve), both re-checking the
  guard before streaming.

Document previews/thumbnails and the attachment-history drawer build on this
foundation and land separately.

Verified: tsc --noEmit, lint, format, frontend-syntax, full test:ci (2846 passed),
and a server boot smoke (/api/status 200).

src/web/public/constants.js

@@ -336,6 +336,7 @@ const SSE_EVENTS = {
 
   // Images
   IMAGE_DETECTED: 'image:detected',
+  ATTACHMENT_DETECTED: 'attachment:detected',
 
   // Tunnel
   TUNNEL_STARTED: 'tunnel:started',

src/web/routes/file-routes.ts

@@ -3,16 +3,146 @@
  * Provides directory listing, file content preview, raw file serving, and tail streaming.
  */
 
-import { FastifyInstance } from 'fastify';
+import { FastifyInstance, type FastifyReply } from 'fastify';
 import { basename as pathBasename, join } from 'node:path';
-import { homedir } from 'node:os';
+import { createReadStream, realpathSync, type ReadStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import { fileStreamManager } from '../../file-stream-manager.js';
+import {
+  AttachmentRegistrationError,
+  attachmentRegistry,
+  registerExternalAttachment,
+  type AttachmentRecord,
+} from '../../attachment-registry.js';
+import { isBlockedAttachmentPath, loadAttachmentGuardConfig } from '../../config/attachment-guard.js';
 import { findSessionOrFail, validateSessionFilePath } from '../route-helpers.js';
-import type { SessionPort } from '../ports/index.js';
+import { isSensitivePath } from '../sensitive-path.js';
+import { SseEvent } from '../sse-events.js';
+import type { EventPort, SessionPort } from '../ports/index.js';
 
-export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void {
+const MIME_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  ico: 'image/x-icon',
+  bmp: 'image/bmp',
+  pdf: 'application/pdf',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  json: 'application/json',
+  md: 'text/markdown',
+  txt: 'text/plain',
+};
+
+function sanitizeDownloadName(fileName: string): string {
+  return fileName.replace(/["\\\r\n]/g, '_');
+}
+
+function sendRawStream(reply: FastifyReply, content: ReadStream): void {
+  const headers = reply.getHeaders();
+  reply.hijack();
+
+  for (const [name, value] of Object.entries(headers)) {
+    if (value !== undefined) {
+      reply.raw.setHeader(name, value);
+    }
+  }
+
+  content.on('error', (err) => {
+    if (reply.raw.headersSent) {
+      reply.raw.destroy(err);
+      return;
+    }
+
+    reply.raw.statusCode = 500;
+    reply.raw.end('Failed to read file');
+  });
+  content.pipe(reply.raw);
+}
+
+async function serveRawFile(
+  reply: FastifyReply,
+  resolvedPath: string,
+  fileName: string,
+  extension: string,
+  download?: boolean
+): Promise<void> {
+  const stat = await fs.stat(resolvedPath);
+  const content = createReadStream(resolvedPath);
+  const safeName = sanitizeDownloadName(fileName);
+  if (download || extension === 'svg') {
+    reply.header(
+      'Content-Type',
+      extension === 'svg' ? 'application/octet-stream' : MIME_TYPES[extension] || 'application/octet-stream'
+    );
+    reply.header('Content-Disposition', `attachment; filename="${safeName}"`);
+    reply.header('Content-Length', stat.size);
+    reply.header('X-Content-Type-Options', 'nosniff');
+    sendRawStream(reply, content);
+    return;
+  }
+
+  reply.header('Content-Type', MIME_TYPES[extension] || 'application/octet-stream');
+  reply.header('Content-Disposition', `inline; filename="${safeName}"`);
+  reply.header('Content-Length', stat.size);
+  reply.header('X-Content-Type-Options', 'nosniff');
+  sendRawStream(reply, content);
+}
+
+function getAttachmentOr404(
+  reply: FastifyReply,
+  sessionId: string,
+  attachmentId: string
+): AttachmentRecord | undefined {
+  const record = attachmentRegistry.get(sessionId, attachmentId);
+  if (!record) {
+    reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Attachment not found'));
+    return undefined;
+  }
+  return record;
+}
+
+/**
+ * COD-53 defense-in-depth: refuse to stream a record whose underlying path is
+ * blocked by the active attachment-guard policy, even though registration
+ * already blocks them. Guards against records that predate the guard or were
+ * crafted to point at a sensitive file. Resolves symlinks before the check so a
+ * record pointing at a symlink that now resolves to a sensitive target is also
+ * caught; if the path can't be resolved (deleted/unreadable) the check still
+ * runs on the stored path. When workspace confinement is enabled it additionally
+ * rejects any record outside the session workspace. Returns true (and sends a
+ * 403) when blocked.
+ */
+async function rejectIfSensitiveRecord(
+  reply: FastifyReply,
+  record: AttachmentRecord,
+  sessionWorkingDir?: string
+): Promise<boolean> {
+  let pathToCheck = record.filePath;
+  try {
+    pathToCheck = realpathSync(record.filePath);
+  } catch {
+    // Fall back to the stored (already realpath-resolved at registration) path.
+  }
+
+  const guard = await loadAttachmentGuardConfig();
+
+  const blocked =
+    isBlockedAttachmentPath(pathToCheck, guard.blockedTrees) ||
+    isBlockedAttachmentPath(record.filePath, guard.blockedTrees) ||
+    (guard.confineToWorkspace && (!sessionWorkingDir || !validateSessionFilePath(sessionWorkingDir, pathToCheck)));
+
+  if (blocked) {
+    reply.code(403).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Access to this file is blocked'));
+    return true;
+  }
+  return false;
+}
+
+export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & EventPort): void {
   // File tree listing
   app.get('/api/sessions/:id/files', async (req) => {
     const { id } = req.params as { id: string };
@@ -315,6 +445,58 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
     }
   });
 
+  // ===== Live external attachments =====
+  // Register an explicit, live external file (absolute host path) as an
+  // attachment with a stable id so browser requests never carry arbitrary
+  // paths. Registration enforces the COD-53 attachment-guard policy. Serving is
+  // by id via the /raw route below; document previews/thumbnails and the
+  // attachment-history list are layered on separately.
+  app.post('/api/sessions/:id/attachments', async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const session = findSessionOrFail(ctx, id);
+    const body = (req.body || {}) as { path?: string };
+
+    if (!body.path || typeof body.path !== 'string') {
+      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing attachment path'));
+      return;
+    }
+
+    try {
+      const event = await registerExternalAttachment(id, body.path, { sessionWorkingDir: session.workingDir });
+      ctx.broadcast(SseEvent.AttachmentDetected, event);
+      return { success: true, data: event };
+    } catch (err) {
+      if (err instanceof AttachmentRegistrationError) {
+        reply.code(err.statusCode).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, err.message));
+        return;
+      }
+      return reply
+        .code(500)
+        .send(
+          createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to register attachment: ${getErrorMessage(err)}`)
+        );
+    }
+  });
+
+  // Serve the raw bytes of a registered attachment by id. Re-checks the
+  // attachment-guard policy on every request (defense-in-depth) before streaming.
+  app.get('/api/sessions/:id/attachments/:attachmentId/raw', async (req, reply) => {
+    const { id, attachmentId } = req.params as { id: string; attachmentId: string };
+    const { download } = req.query as { download?: string };
+    const session = findSessionOrFail(ctx, id);
+    const record = getAttachmentOr404(reply, id, attachmentId);
+    if (!record) return;
+    if (await rejectIfSensitiveRecord(reply, record, session.workingDir)) return;
+
+    try {
+      await serveRawFile(reply, record.filePath, record.fileName, record.extension, download === 'true');
+    } catch (err) {
+      reply
+        .code(500)
+        .send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read file: ${getErrorMessage(err)}`));
+    }
+  });
+
   // Stream file content via tail -f (SSE endpoint)
   app.get('/api/sessions/:id/tail-file', async (req, reply) => {
     const { id } = req.params as { id: string };
@@ -387,24 +569,8 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
   });
   // Session-scoped file download.
   // Uses the same realpath-based workspace boundary as file preview/raw routes;
-  // the sensitive-path blocklist remains defense-in-depth, not the primary boundary.
-  const SENSITIVE_PATTERNS: RegExp[] = [
-    /^\/etc\/shadow$/,
-    /^\/etc\/gshadow$/,
-    /^\/etc\/master\.passwd$/,
-    new RegExp(`^${homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/\\.ssh\\/`),
-    /\/\.env$/,
-    /\/\.env\./,
-    /\/credentials(\.json|\.yml|\.yaml|\.xml)?$/i,
-    /\/\.aws\/credentials$/,
-    /\/\.gcloud\/credentials\.db$/,
-    /\/\.docker\/config\.json$/,
-  ];
-
-  function isSensitivePath(absPath: string): boolean {
-    return SENSITIVE_PATTERNS.some((pattern) => pattern.test(absPath));
-  }
-
+  // the shared sensitive-path blocklist (../sensitive-path.js, also used by the
+  // attachment guard) remains defense-in-depth, not the primary boundary.
   app.get('/api/download', async (req, reply) => {
     const { path: filePath, sessionId } = req.query as { path?: string; sessionId?: string };
 

src/web/sensitive-path.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Shared sensitive-path blocklist.
+ *
+ * A small defense-in-depth blocklist of absolute paths that must never be
+ * served to the browser regardless of how the path was obtained (workspace
+ * download, cross-workspace attachment registration, raw/preview serving).
+ *
+ * This is intentionally a BLOCKLIST, not a workspace-confinement check:
+ * cross-workspace attachment is a supported feature (codeman-publish skill +
+ * the automated review-card loop attaching files under ~/.codeman/), so a
+ * strict session-workspace boundary would break legitimate use. The blocklist
+ * rejects well-known secret locations (system password files, SSH keys, cloud
+ * credentials, dotenv files) while leaving ordinary cross-workspace files
+ * attachable.
+ *
+ * Callers MUST resolve symlinks (realpath) BEFORE calling isSensitivePath so a
+ * symlink pointing at a sensitive target is also caught.
+ */
+
+import { homedir } from 'node:os';
+
+const SENSITIVE_PATTERNS: RegExp[] = [
+  /^\/etc\/shadow$/,
+  /^\/etc\/gshadow$/,
+  /^\/etc\/master\.passwd$/,
+  new RegExp(`^${homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/\\.ssh\\/`),
+  /\/\.env$/,
+  /\/\.env\./,
+  /\/credentials(\.json|\.yml|\.yaml|\.xml)?$/i,
+  /\/\.aws\/credentials$/,
+  /\/\.gcloud\/credentials\.db$/,
+  /\/\.docker\/config\.json$/,
+];
+
+/**
+ * Returns true if the given ABSOLUTE, symlink-resolved path matches the
+ * sensitive-file blocklist and must not be served to the browser.
+ */
+export function isSensitivePath(absPath: string): boolean {
+  return SENSITIVE_PATTERNS.some((pattern) => pattern.test(absPath));
+}

src/web/server.ts

@@ -60,6 +60,7 @@ import {
   type SubagentToolResult,
 } from '../subagent-watcher.js';
 import { imageWatcher } from '../image-watcher.js';
+import { attachmentRegistry, registerExternalAttachment } from '../attachment-registry.js';
 import { TranscriptWatcher } from '../transcript-watcher.js';
 import { TeamWatcher } from '../team-watcher.js';
 import { TunnelManager } from '../tunnel-manager.js';
@@ -110,6 +111,7 @@ import {
   type PersistedRespawnConfig,
   type NiceConfig,
   type ImageDetectedEvent,
+  type AttachmentDetectedEvent,
   DEFAULT_NICE_CONFIG,
 } from '../types.js';
 import {
@@ -248,6 +250,7 @@ export class WebServer extends EventEmitter {
   } | null = null;
   private imageWatcherHandlers: {
     detected: (event: ImageDetectedEvent) => void;
+    attachmentDetected: (event: AttachmentDetectedEvent) => void;
     error: (error: Error, sessionId?: string) => void;
   } | null = null;
   private tunnelManager: TunnelManager = new TunnelManager();
@@ -436,12 +439,15 @@ export class WebServer extends EventEmitter {
     // Store handlers for cleanup on shutdown
     this.imageWatcherHandlers = {
       detected: (event: ImageDetectedEvent) => this.broadcast(SseEvent.ImageDetected, event),
+      attachmentDetected: (event: AttachmentDetectedEvent) =>
+        this.broadcast(SseEvent.AttachmentDetected, { ...event, source: event.source || 'detected' }),
       error: (error: Error, sessionId?: string) => {
         console.error(`[ImageWatcher] Error${sessionId ? ` for ${sessionId}` : ''}:`, error.message);
       },
     };
 
     imageWatcher.on('image:detected', this.imageWatcherHandlers.detected);
+    imageWatcher.on('attachment:detected', this.imageWatcherHandlers.attachmentDetected);
     imageWatcher.on('image:error', this.imageWatcherHandlers.error);
   }
 
@@ -451,6 +457,7 @@ export class WebServer extends EventEmitter {
   private cleanupImageWatcherListeners(): void {
     if (this.imageWatcherHandlers) {
       imageWatcher.off('image:detected', this.imageWatcherHandlers.detected);
+      imageWatcher.off('attachment:detected', this.imageWatcherHandlers.attachmentDetected);
       imageWatcher.off('image:error', this.imageWatcherHandlers.error);
       this.imageWatcherHandlers = null;
     }
@@ -1067,6 +1074,8 @@ export class WebServer extends EventEmitter {
       session.removeAllListeners();
       // Close any active file streams for this session
       fileStreamManager.closeSessionStreams(sessionId);
+      // Drop live external attachment registrations for this session
+      attachmentRegistry.clearSession(sessionId);
       // Stop watching for images in this session's directory
       imageWatcher.unwatchSession(sessionId);
       // Clean up pasted images directory for this session
@@ -1252,9 +1261,23 @@ export class WebServer extends EventEmitter {
         }
       },
       getStore: () => this.store,
+      registerAttachment: (id: string, filePath: string) => this.registerAttachment(id, filePath),
     };
   }
 
+  /**
+   * Register a terminal-requested external file as a live attachment and
+   * broadcast it. Triggered by the session's `attachmentRequested` event
+   * (codeman://attach magic links). Registration enforces the COD-53
+   * attachment-guard policy.
+   */
+  private async registerAttachment(sessionId: string, filePath: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    const event = await registerExternalAttachment(sessionId, filePath, { sessionWorkingDir: session.workingDir });
+    this.broadcast(SseEvent.AttachmentDetected, event);
+  }
+
   private setupRespawnListeners(sessionId: string, controller: RespawnController): void {
     wireRespawnListeners(sessionId, controller, this.buildRespawnWiringDeps());
   }

src/web/session-listener-wiring.ts

@@ -58,6 +58,7 @@ export interface SessionListenerRefs {
   bashToolStart: (tool: ActiveBashTool) => void;
   bashToolEnd: (tool: ActiveBashTool) => void;
   bashToolsUpdate: (tools: ActiveBashTool[]) => void;
+  attachmentRequested: (event: { path: string }) => void;
 }
 
 /** Dependencies injected by WebServer — keeps listener creation decoupled from server internals. */
@@ -77,10 +78,11 @@ interface SessionListenerDeps {
   removeSessionListenerRefs(sessionId: string): void;
   cleanupRespawnOnExit(sessionId: string): void;
   getStore(): import('../state-store.js').StateStore;
+  registerAttachment(sessionId: string, filePath: string): Promise<void>;
 }
 
 /**
- * Creates all 25 session listener handlers, capturing dependencies via closure.
+ * Creates all 26 session listener handlers, capturing dependencies via closure.
  * Call `attachSessionListeners()` after to wire them to the session.
  */
 export function createSessionListeners(session: Session, deps: SessionListenerDeps): SessionListenerRefs {
@@ -355,6 +357,13 @@ export function createSessionListeners(session: Session, deps: SessionListenerDe
     bashToolsUpdate: (tools: ActiveBashTool[]) => {
       deps.broadcast(SseEvent.SessionBashToolsUpdate, { sessionId: session.id, tools });
     },
+
+    /** Registers an explicit attachment card requested by terminal magic text. */
+    attachmentRequested: (event: { path: string }) => {
+      deps.registerAttachment(session.id, event.path).catch((err) => {
+        console.error(`[Attachment] Failed to register ${event.path} for ${session.id}:`, err);
+      });
+    },
   };
 }
 
@@ -388,6 +397,7 @@ export function attachSessionListeners(session: Session, refs: SessionListenerRe
   session.on('bashToolStart', refs.bashToolStart);
   session.on('bashToolEnd', refs.bashToolEnd);
   session.on('bashToolsUpdate', refs.bashToolsUpdate);
+  session.on('attachmentRequested', refs.attachmentRequested);
 }
 
 /** Detach all listeners from a session (prevents memory leaks from closure references). */
@@ -420,4 +430,5 @@ export function detachSessionListeners(session: Session, refs: SessionListenerRe
   session.off('bashToolStart', refs.bashToolStart);
   session.off('bashToolEnd', refs.bashToolEnd);
   session.off('bashToolsUpdate', refs.bashToolsUpdate);
+  session.off('attachmentRequested', refs.attachmentRequested);
 }

src/web/sse-events.ts

@@ -284,6 +284,8 @@ export const TunnelQrAuthUsed = 'tunnel:qrAuthUsed' as const;
 
 /** New image file detected (e.g. screenshot upload). */
 export const ImageDetected = 'image:detected' as const;
+/** New document/image attachment detected in a session working directory. */
+export const AttachmentDetected = 'attachment:detected' as const;
 
 // ─── Hooks ───────────────────────────────────────────────────────────────────
 
@@ -479,6 +481,7 @@ export const SseEvent = {
 
   // Image
   ImageDetected,
+  AttachmentDetected,
 
   // Hooks
   HookIdlePrompt,