@vellumai/assistant 0.6.5 → 0.7.0

package/src/runtime/routes/attachment-routes.ts

@@ -12,15 +12,31 @@ import { join, resolve, sep } from "node:path";
 
 import { z } from "zod";
 
-import * as attachmentsStore from "../../memory/attachments-store.js";
+import {
+  deleteAttachment,
+  getAttachmentById,
+  getFilePathBySourcePath,
+  StoredAttachment,
+  uploadAttachment,
+  uploadAttachmentFromBytes,
+  uploadFileBackedAttachment,
+} from "../../memory/attachments-store.js";
 import {
   AttachmentUploadError,
   getFilePathForAttachment,
   validateAttachmentUpload,
 } from "../../memory/attachments-store.js";
 import { getWorkspaceDir } from "../../util/platform.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
+import {
+  BadRequestError,
+  ConflictError,
+  NotFoundError,
+  PayloadTooLargeError,
+  RangeNotSatisfiableError,
+  UnsupportedMediaTypeError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+import { RouteResponse } from "./types.js";
 
 /** 150 MB — base64-encoded 100 MB attachment ≈ 134 MB plus JSON wrapper overhead. */
 const MAX_UPLOAD_BODY_BYTES = 150 * 1024 * 1024;
@@ -101,18 +117,16 @@ export function resolveAllowedFileBackedAttachmentPath(
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 
 /**
- * Build the standard JSON success response for an uploaded attachment.
+ * Build the standard JSON success payload for an uploaded attachment.
  */
-function attachmentResponse(
-  attachment: attachmentsStore.StoredAttachment,
-): Response {
-  return Response.json({
+function attachmentPayload(attachment: StoredAttachment) {
+  return {
     id: attachment.id,
     original_filename: attachment.originalFilename,
     mime_type: attachment.mimeType,
     size_bytes: attachment.sizeBytes,
     kind: attachment.kind,
-  });
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -122,195 +136,180 @@ function attachmentResponse(
 /**
  * Handle multipart/form-data upload.
  * Expects: "file" (Blob), "filename" (string), "mimeType" (string).
+ *
+ * `gatewayTrustedSource` is true only when the caller is the gateway
+ * service AND requested the bypass — see `handleUploadAttachmentRoute`.
  */
-async function handleMultipartUpload(req: Request): Promise<Response> {
-  // Pre-check Content-Length before parsing to reject oversized requests
-  // without buffering the full multipart body into memory. Binary uploads
-  // have no base64 overhead, so use the raw file size limit directly.
-  const contentLength = req.headers.get("content-length");
+async function handleMultipartUpload(
+  rawBody: Uint8Array,
+  headers: Record<string, string>,
+  gatewayTrustedSource: boolean,
+) {
+  const contentLength = headers["content-length"];
   if (contentLength && Number(contentLength) > MAX_UPLOAD_BYTES) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new PayloadTooLargeError(
       `File too large (limit: ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB)`,
-      413,
     );
   }
 
+  // Reconstruct a Request to use the platform's multipart parser.
+  const syntheticReq = new Request("http://localhost", {
+    method: "POST",
+    headers: { "content-type": headers["content-type"] ?? "" },
+    body: rawBody.buffer as ArrayBuffer,
+  });
+
   let formData: FormData;
   try {
-    formData = await req.formData();
+    formData = await syntheticReq.formData();
   } catch {
-    return httpError("BAD_REQUEST", "Invalid multipart form data", 400);
+    throw new BadRequestError("Invalid multipart form data");
   }
 
   const file = formData.get("file");
   if (!file || !(file instanceof Blob)) {
-    return httpError(
-      "BAD_REQUEST",
-      'Multipart upload requires a "file" field',
-      400,
-    );
+    throw new BadRequestError('Multipart upload requires a "file" field');
   }
 
   const filename = formData.get("filename");
   if (!filename || typeof filename !== "string") {
-    return httpError("BAD_REQUEST", "filename field is required", 400);
+    throw new BadRequestError("filename field is required");
   }
 
   const mimeType = formData.get("mimeType");
   if (!mimeType || typeof mimeType !== "string") {
-    return httpError("BAD_REQUEST", "mimeType field is required", 400);
+    throw new BadRequestError("mimeType field is required");
   }
 
-  // Check file part size against the raw file limit (Content-Length may be
-  // absent or inaccurate, so this is the authoritative check).
   if (file.size > MAX_UPLOAD_BYTES) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new PayloadTooLargeError(
       `File is ${Math.round(file.size / (1024 * 1024))} MB which exceeds the ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB upload limit`,
-      413,
     );
   }
 
-  const validation = validateAttachmentUpload(filename, mimeType);
+  const trustedSource =
+    gatewayTrustedSource && formData.get("trustedSource") === "true";
+
+  const validation = validateAttachmentUpload(filename, mimeType, {
+    trustedSource,
+  });
   if (!validation.ok) {
-    return httpError("UNPROCESSABLE_ENTITY", validation.error, 415);
+    throw new UnsupportedMediaTypeError(validation.error);
   }
 
   const bytes = new Uint8Array(await file.arrayBuffer());
 
-  const attachment = attachmentsStore.uploadAttachmentFromBytes(
-    filename,
-    mimeType,
-    bytes,
-  );
-  return attachmentResponse(attachment);
+  const attachment = uploadAttachmentFromBytes(filename, mimeType, bytes);
+  return attachmentPayload(attachment);
 }
 
 /**
  * Handle application/octet-stream upload.
  * filename and mimeType come from URL query params.
+ *
+ * See `handleMultipartUpload` for `gatewayTrustedSource` semantics.
  */
-async function handleOctetStreamUpload(req: Request): Promise<Response> {
-  // Pre-check Content-Length before buffering to reject oversized requests
-  // without reading the full body into memory.
-  const contentLength = req.headers.get("content-length");
+function handleOctetStreamUpload(
+  rawBody: Uint8Array,
+  headers: Record<string, string>,
+  queryParams: Record<string, string>,
+  gatewayTrustedSource: boolean,
+) {
+  const contentLength = headers["content-length"];
   if (contentLength && Number(contentLength) > MAX_UPLOAD_BYTES) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new PayloadTooLargeError(
       `File too large (limit: ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB)`,
-      413,
     );
   }
 
-  const url = new URL(req.url);
-  const filename = url.searchParams.get("filename");
+  const filename = queryParams.filename;
   if (!filename || typeof filename !== "string") {
-    return httpError(
-      "BAD_REQUEST",
-      "filename query parameter is required",
-      400,
-    );
+    throw new BadRequestError("filename query parameter is required");
   }
 
-  const mimeType = url.searchParams.get("mimeType");
+  const mimeType = queryParams.mimeType;
   if (!mimeType || typeof mimeType !== "string") {
-    return httpError(
-      "BAD_REQUEST",
-      "mimeType query parameter is required",
-      400,
-    );
+    throw new BadRequestError("mimeType query parameter is required");
   }
 
-  const rawBody = await req.arrayBuffer();
-  // Post-read check (Content-Length may be absent or inaccurate).
   if (rawBody.byteLength > MAX_UPLOAD_BYTES) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new PayloadTooLargeError(
       `File is ${Math.round(rawBody.byteLength / (1024 * 1024))} MB which exceeds the ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB upload limit`,
-      413,
     );
   }
 
-  const validation = validateAttachmentUpload(filename, mimeType);
+  const trustedSource =
+    gatewayTrustedSource && queryParams.trustedSource === "true";
+
+  const validation = validateAttachmentUpload(filename, mimeType, {
+    trustedSource,
+  });
   if (!validation.ok) {
-    return httpError("UNPROCESSABLE_ENTITY", validation.error, 415);
+    throw new UnsupportedMediaTypeError(validation.error);
   }
 
-  const bytes = new Uint8Array(rawBody);
-
-  const attachment = attachmentsStore.uploadAttachmentFromBytes(
-    filename,
-    mimeType,
-    bytes,
-  );
-  return attachmentResponse(attachment);
+  const attachment = uploadAttachmentFromBytes(filename, mimeType, rawBody);
+  return attachmentPayload(attachment);
 }
 
 /**
  * Handle application/json upload (existing behaviour — base64 or file-path).
+ *
+ * See `handleMultipartUpload` for `gatewayTrustedSource` semantics.
  */
-async function handleJsonUpload(req: Request): Promise<Response> {
-  const rawBody = await req.arrayBuffer();
-  if (rawBody.byteLength > MAX_UPLOAD_BODY_BYTES) {
-    return httpError(
-      "BAD_REQUEST",
+function handleJsonUpload(
+  body: Record<string, unknown>,
+  rawBody: Uint8Array | undefined,
+  gatewayTrustedSource: boolean,
+) {
+  if (rawBody && rawBody.byteLength > MAX_UPLOAD_BODY_BYTES) {
+    throw new PayloadTooLargeError(
       `Request body too large (limit: ${MAX_UPLOAD_BODY_BYTES} bytes)`,
-      413,
     );
   }
 
-  const body = JSON.parse(new TextDecoder().decode(rawBody)) as {
+  const { filename, mimeType, data, filePath } = body as {
     filename?: string;
     mimeType?: string;
     data?: string;
     filePath?: string;
+    trustedSource?: boolean;
   };
 
-  const { filename, mimeType, data, filePath } = body;
-
   if (!filename || typeof filename !== "string") {
-    return httpError("BAD_REQUEST", "filename is required", 400);
+    throw new BadRequestError("filename is required");
   }
 
   if (!mimeType || typeof mimeType !== "string") {
-    return httpError("BAD_REQUEST", "mimeType is required", 400);
+    throw new BadRequestError("mimeType is required");
   }
 
-  const validation = validateAttachmentUpload(filename, mimeType);
+  const trustedSource =
+    gatewayTrustedSource &&
+    (body as { trustedSource?: boolean }).trustedSource === true;
+
+  const validation = validateAttachmentUpload(filename, mimeType, {
+    trustedSource,
+  });
   if (!validation.ok) {
-    return httpError("UNPROCESSABLE_ENTITY", validation.error, 415);
+    throw new UnsupportedMediaTypeError(validation.error);
   }
 
-  let attachment: attachmentsStore.StoredAttachment;
+  let attachment: StoredAttachment;
 
-  // File-backed upload: when filePath is provided and data is empty/missing,
-  // register the attachment by path reference instead of requiring base64 data.
-  // This supports:
-  //   1. Desktop client file-picker uploads — the file is copied into the
-  //      workspace attachments directory so it passes the directory allowlist.
-  //   2. Retry of file-backed attachments (e.g. recordings) where the client
-  //      no longer holds the inline data but the file still exists on disk.
   if (filePath && typeof filePath === "string" && (!data || data === "")) {
     let resolvedPath = resolveAllowedFileBackedAttachmentPath(filePath);
 
-    // If the file isn't in an allowed directory, copy it into the workspace
-    // attachments directory. This handles desktop client file-picker uploads
-    // where the source file lives in an arbitrary user directory (e.g.
-    // ~/Desktop, ~/Downloads). The copy lands in the allowlisted workspace
-    // directory, preserving the security model.
     if (!resolvedPath) {
       const canonicalSource = resolveCanonicalPath(filePath);
       if (!existsSync(canonicalSource)) {
-        return httpError("BAD_REQUEST", "filePath does not exist on disk", 400);
+        throw new BadRequestError("filePath does not exist on disk");
       }
       const sourceSize = statSync(canonicalSource).size;
       if (sourceSize > MAX_FILE_BACKED_UPLOAD_BYTES) {
         const sizeMB = Math.round(sourceSize / (1024 * 1024));
-        return httpError(
-          "BAD_REQUEST",
+        throw new PayloadTooLargeError(
           `File is ${sizeMB} MB which exceeds the ${MAX_FILE_BACKED_UPLOAD_BYTES / (1024 * 1024)} MB upload limit`,
-          413,
         );
       }
       const workspaceAttachmentsDir = join(
@@ -326,10 +325,10 @@ async function handleJsonUpload(req: Request): Promise<Response> {
     }
 
     if (!existsSync(resolvedPath)) {
-      return httpError("BAD_REQUEST", "filePath does not exist on disk", 400);
+      throw new BadRequestError("filePath does not exist on disk");
     }
     const sizeBytes = statSync(resolvedPath).size;
-    attachment = attachmentsStore.uploadFileBackedAttachment(
+    attachment = uploadFileBackedAttachment(
       filename,
       mimeType,
       resolvedPath,
@@ -337,11 +336,11 @@ async function handleJsonUpload(req: Request): Promise<Response> {
     );
   } else {
     if (!data || typeof data !== "string") {
-      return httpError("BAD_REQUEST", "data (base64) is required", 400);
+      throw new BadRequestError("data (base64) is required");
     }
 
     try {
-      attachment = attachmentsStore.uploadAttachment(
+      attachment = uploadAttachment(
         filename,
         mimeType,
         data,
@@ -349,65 +348,69 @@ async function handleJsonUpload(req: Request): Promise<Response> {
       );
     } catch (err) {
       if (err instanceof AttachmentUploadError) {
-        const status = err.message.startsWith("Attachment too large")
-          ? 413
-          : 400;
-        return httpError("BAD_REQUEST", err.message, status);
+        if (err.message.startsWith("Attachment too large")) {
+          throw new PayloadTooLargeError(err.message);
+        }
+        throw new BadRequestError(err.message);
       }
       throw err;
     }
   }
 
-  return attachmentResponse(attachment);
+  return attachmentPayload(attachment);
 }
 
-export async function handleUploadAttachment(req: Request): Promise<Response> {
-  const contentType = req.headers.get("content-type") ?? "";
+async function handleUploadAttachmentRoute(args: RouteHandlerArgs) {
+  const { rawBody, headers = {}, queryParams = {}, body } = args;
+  const contentType = headers["content-type"] ?? "";
+
+  // The gateway sets x-vellum-principal-type when proxying authenticated
+  // requests. Only gateway service principals can opt into the trusted
+  // source bypass (skips attachment validation for channel-sourced files).
+  const gatewayTrustedSource =
+    headers["x-vellum-principal-type"] === "svc_gateway";
 
-  if (contentType.includes("multipart/form-data")) {
-    return handleMultipartUpload(req);
+  if (contentType.includes("multipart/form-data") && rawBody) {
+    return handleMultipartUpload(rawBody, headers, gatewayTrustedSource);
   }
 
-  if (contentType.includes("application/octet-stream")) {
-    return handleOctetStreamUpload(req);
+  if (contentType.includes("application/octet-stream") && rawBody) {
+    return handleOctetStreamUpload(
+      rawBody,
+      headers,
+      queryParams,
+      gatewayTrustedSource,
+    );
   }
 
   // Default: JSON+base64 (existing behaviour)
-  return handleJsonUpload(req);
+  return handleJsonUpload(body ?? {}, rawBody, gatewayTrustedSource);
 }
 
-export async function handleDeleteAttachment(req: Request): Promise<Response> {
-  let body: { attachmentId?: string };
-  try {
-    body = (await req.json()) as { attachmentId?: string };
-  } catch {
-    return httpError("BAD_REQUEST", "Invalid or missing JSON body", 400);
-  }
-
-  const { attachmentId } = body;
+function handleDeleteAttachmentRoute({ body }: RouteHandlerArgs) {
+  const attachmentId = body?.attachmentId as string | undefined;
 
   if (!attachmentId || typeof attachmentId !== "string") {
-    return httpError("BAD_REQUEST", "attachmentId is required", 400);
+    throw new BadRequestError("attachmentId is required");
   }
 
-  const result = attachmentsStore.deleteAttachment(attachmentId);
+  const result = deleteAttachment(attachmentId);
 
   if (result === "not_found") {
-    return httpError("NOT_FOUND", "Attachment not found", 404);
+    throw new NotFoundError("Attachment not found");
   }
 
   if (result === "still_referenced") {
-    return httpError(
-      "CONFLICT",
+    throw new ConflictError(
       "Attachment is still referenced by one or more messages",
-      409,
     );
   }
 
-  return new Response(null, { status: 204 });
+  return null;
 }
 
-function handleGetAttachment(attachmentId: string): Response {
+function handleGetAttachmentRoute({ pathParams }: RouteHandlerArgs) {
+  const attachmentId = pathParams!.id;
   // Use the file_path column to detect file-backed attachments, not string
   // truthiness of dataBase64 (which would also match valid zero-byte uploads).
   const isFileBacked = !!getFilePathForAttachment(attachmentId);
@@ -415,14 +418,14 @@ function handleGetAttachment(attachmentId: string): Response {
   // Skip hydrating file data for file-backed attachments — clients should
   // fetch content via GET /attachments/:id/content (which validates the path
   // against the directory allowlist).
-  const attachment = attachmentsStore.getAttachmentById(attachmentId, {
+  const attachment = getAttachmentById(attachmentId, {
     hydrateFileData: !isFileBacked,
   });
   if (!attachment) {
-    return httpError("NOT_FOUND", "Attachment not found", 404);
+    throw new NotFoundError("Attachment not found");
   }
 
-  return Response.json({
+  return {
     id: attachment.id,
     filename: attachment.originalFilename,
     mimeType: attachment.mimeType,
@@ -433,7 +436,7 @@ function handleGetAttachment(attachmentId: string): Response {
     data: isFileBacked ? null : attachment.dataBase64,
     // Signal to clients that they should fetch content via the /content endpoint
     ...(isFileBacked ? { fileBacked: true } : {}),
-  });
+  };
 }
 
 /**
@@ -441,105 +444,92 @@ function handleGetAttachment(attachmentId: string): Response {
  * streams from disk; for inline attachments it decodes the base64 data.
  * Supports Range headers for video seeking.
  */
-export function handleGetAttachmentContent(
-  attachmentId: string,
-  req: Request,
-): Response {
-  // Check for file-backed attachment first so we can skip hydration — file-backed
-  // content is served directly from disk via Bun.file, not from the hydrated base64.
+function handleGetAttachmentContentRoute({
+  pathParams,
+  headers = {},
+}: RouteHandlerArgs): RouteResponse {
+  const attachmentId = pathParams!.id;
   const filePath = getFilePathForAttachment(attachmentId);
   const isFileBacked = !!filePath;
 
-  const attachment = attachmentsStore.getAttachmentById(attachmentId, {
+  const attachment = getAttachmentById(attachmentId, {
     hydrateFileData: !isFileBacked,
   });
   if (!attachment) {
-    return httpError("NOT_FOUND", "Attachment not found", 404);
+    throw new NotFoundError("Attachment not found");
   }
   if (filePath) {
     const resolvedPath = resolveAllowedFileBackedAttachmentPath(filePath);
     if (!resolvedPath) {
-      return httpError("NOT_FOUND", "Attachment content not found", 404);
+      throw new NotFoundError("Attachment content not found");
     }
     if (!existsSync(resolvedPath)) {
-      return httpError("NOT_FOUND", "Recording file not found on disk", 404);
+      throw new NotFoundError("Recording file not found on disk");
     }
 
     const file = Bun.file(resolvedPath);
-    const rangeHeader = req.headers.get("Range");
+    const rangeHeader = headers["range"];
 
     if (rangeHeader) {
       const fileSize = attachment.sizeBytes;
       let start: number;
       let end: number;
 
-      // Parse suffix range: bytes=-N (last N bytes)
       const suffixMatch = rangeHeader.match(/bytes=-(\d+)/);
       if (suffixMatch) {
         const suffixLen = parseInt(suffixMatch[1]);
         start = Math.max(0, fileSize - suffixLen);
         end = fileSize - 1;
       } else {
-        // Parse standard range: bytes=start-end
         const match = rangeHeader.match(/bytes=(\d+)-(\d*)/);
         if (!match) {
-          // Unparseable range — return full file
-          return new Response(file, {
-            headers: {
+          // Unparseable range — return full file at 200 (not 206)
+          return new RouteResponse(
+            file,
+            {
               "Content-Type": attachment.mimeType,
               "Content-Length": String(fileSize),
               "Accept-Ranges": "bytes",
             },
-          });
+            200,
+          );
         }
         start = parseInt(match[1]);
         end = match[2] ? parseInt(match[2]) : fileSize - 1;
       }
 
-      // Clamp end to file size
       end = Math.min(end, fileSize - 1);
 
-      // Reject invalid ranges
       if (start > end || start >= fileSize) {
-        return new Response(null, {
-          status: 416,
-          headers: { "Content-Range": `bytes */${fileSize}` },
-        });
+        throw new RangeNotSatisfiableError(`bytes */${fileSize}`);
       }
 
       const slice = file.slice(start, end + 1);
-      return new Response(slice, {
-        status: 206,
-        headers: {
-          "Content-Type": attachment.mimeType,
-          "Content-Range": `bytes ${start}-${end}/${fileSize}`,
-          "Accept-Ranges": "bytes",
-          "Content-Length": String(end - start + 1),
-        },
+      return new RouteResponse(slice, {
+        "Content-Type": attachment.mimeType,
+        "Content-Range": `bytes ${start}-${end}/${fileSize}`,
+        "Accept-Ranges": "bytes",
+        "Content-Length": String(end - start + 1),
       });
     }
 
-    return new Response(file, {
-      headers: {
-        "Content-Type": attachment.mimeType,
-        "Content-Length": String(attachment.sizeBytes),
-        "Accept-Ranges": "bytes",
-      },
+    return new RouteResponse(file, {
+      "Content-Type": attachment.mimeType,
+      "Content-Length": String(attachment.sizeBytes),
+      "Accept-Ranges": "bytes",
     });
   }
 
   // Fall back to base64-decoded content for inline attachments
   if (!attachment.dataBase64) {
-    return httpError("NOT_FOUND", "No content available", 404);
+    throw new NotFoundError("No content available");
   }
 
   const buffer = Buffer.from(attachment.dataBase64, "base64");
-  return new Response(buffer, {
-    headers: {
-      "Content-Type": attachment.mimeType,
-      "Content-Length": String(buffer.length),
-      "Accept-Ranges": "bytes",
-    },
+  return new RouteResponse(buffer, {
+    "Content-Type": attachment.mimeType,
+    "Content-Length": String(buffer.length),
+    "Accept-Ranges": "bytes",
   });
 }
 
@@ -547,72 +537,238 @@ export function handleGetAttachmentContent(
 // Route definitions
 // ---------------------------------------------------------------------------
 
-export function attachmentRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "attachments",
-      method: "POST",
-      summary: "Upload attachment",
-      description:
-        "Upload an attachment. Supports application/json (base64 data or file path reference), multipart/form-data (file + filename + mimeType fields), and application/octet-stream (raw bytes with filename and mimeType query params).",
-      tags: ["attachments"],
-      requestBody: z.object({
-        filename: z.string(),
-        mimeType: z.string(),
-        data: z.string().describe("Base64-encoded file data").optional(),
-        filePath: z
-          .string()
-          .describe("On-disk file path (file-backed upload)")
-          .optional(),
-      }),
-      responseBody: z.object({
-        id: z.string(),
-        original_filename: z.string(),
-        mime_type: z.string(),
-        size_bytes: z.number(),
-        kind: z.string(),
-      }),
-      handler: async ({ req }) => handleUploadAttachment(req),
-    },
-    {
-      endpoint: "attachments",
-      method: "DELETE",
-      summary: "Delete attachment",
-      description: "Delete an attachment by ID.",
-      tags: ["attachments"],
-      requestBody: z.object({
-        attachmentId: z.string(),
-      }),
-      handler: async ({ req }) => handleDeleteAttachment(req),
-    },
-    {
-      endpoint: "attachments/:id/content",
-      method: "GET",
-      policyKey: "attachments/content",
-      summary: "Get attachment content",
-      description:
-        "Serve raw file bytes for an attachment. Supports Range headers.",
-      tags: ["attachments"],
-      handler: ({ req, params }) => handleGetAttachmentContent(params.id, req),
-    },
-    {
-      endpoint: "attachments/:id",
-      method: "GET",
-      policyKey: "attachments",
-      summary: "Get attachment metadata",
-      description:
-        "Return metadata and optional base64 data for an attachment.",
-      tags: ["attachments"],
-      responseBody: z.object({
-        id: z.string(),
-        filename: z.string(),
-        mimeType: z.string(),
-        sizeBytes: z.number(),
-        kind: z.string(),
-        data: z.string().describe("Base64-encoded content"),
-        fileBacked: z.boolean(),
-      }),
-      handler: ({ params }) => handleGetAttachment(params.id),
-    },
-  ];
+// ---------------------------------------------------------------------------
+// Shared (transport-agnostic) routes — served via HTTP + IPC
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify that a resolved path is within the workspace directory.
+ * Resolves symlinks on the nearest existing ancestor to prevent
+ * symlink-based escapes.
+ */
+function assertWithinWorkspace(filePath: string): string {
+  const workspaceDir = getWorkspaceDir();
+  const resolvedWorkspace = resolveCanonicalPath(workspaceDir);
+  const resolved = resolve(filePath);
+
+  // Walk up to the nearest existing ancestor and resolve symlinks.
+  let current = resolved;
+  const trailing: string[] = [];
+  while (current !== join(current, "..")) {
+    try {
+      const real = realpathSync(current);
+      const realResolved =
+        trailing.length > 0 ? resolve(real, ...trailing) : real;
+      if (!isPathWithinDirectory(realResolved, resolvedWorkspace)) {
+        throw new BadRequestError(
+          `Path must be within the workspace directory. Got: ${filePath}`,
+        );
+      }
+      return resolved;
+    } catch (err) {
+      if (err instanceof BadRequestError) throw err;
+      trailing.unshift(join(current).split(sep).pop()!);
+      current = join(current, "..");
+    }
+  }
+
+  throw new BadRequestError(
+    `Path must be within the workspace directory. Got: ${filePath}`,
+  );
+}
+
+function handleAttachmentRegister({ body = {} }: RouteHandlerArgs) {
+  const { path, mimeType, filename } = body as {
+    path?: string;
+    mimeType?: string;
+    filename?: string;
+  };
+
+  if (!path || typeof path !== "string") {
+    throw new BadRequestError("path is required");
+  }
+  if (!mimeType || typeof mimeType !== "string") {
+    throw new BadRequestError("mimeType is required");
+  }
+
+  const resolvedPath = assertWithinWorkspace(path);
+
+  let sizeBytes: number;
+  try {
+    const stat = statSync(resolvedPath);
+    if (!stat.isFile()) {
+      throw new BadRequestError(
+        `Path is not a regular file: ${path}. Provide a path to a file, not a directory.`,
+      );
+    }
+    sizeBytes = stat.size;
+  } catch (err) {
+    if (err instanceof BadRequestError) throw err;
+    throw new NotFoundError(`File not found: ${path}`);
+  }
+
+  const resolvedFilename =
+    filename ?? resolvedPath.split(sep).pop() ?? "unknown";
+
+  const validation = validateAttachmentUpload(resolvedFilename, mimeType);
+  if (!validation.ok) {
+    throw new BadRequestError(validation.error);
+  }
+
+  return uploadFileBackedAttachment(
+    resolvedFilename,
+    mimeType,
+    resolvedPath,
+    sizeBytes,
+  );
 }
+
+function handleAttachmentLookup({ body = {} }: RouteHandlerArgs) {
+  const { sourcePath, conversationId } = body as {
+    sourcePath?: string;
+    conversationId?: string;
+  };
+
+  if (!sourcePath || typeof sourcePath !== "string") {
+    throw new BadRequestError("sourcePath is required");
+  }
+  if (!conversationId || typeof conversationId !== "string") {
+    throw new BadRequestError("conversationId is required");
+  }
+
+  assertWithinWorkspace(sourcePath);
+
+  const result = getFilePathBySourcePath(sourcePath, conversationId);
+  if (result === null) {
+    throw new NotFoundError(
+      `No attachment found for source path: ${sourcePath} in conversation ${conversationId}. Run 'assistant attachment register' to register a file first.`,
+    );
+  }
+
+  return { filePath: result };
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "attachment_content",
+    endpoint: "attachments/:id/content",
+    method: "GET",
+    policyKey: "attachments/content",
+    summary: "Get attachment content",
+    description:
+      "Serve raw file bytes for an attachment. Supports Range headers.",
+    tags: ["attachments"],
+    responseStatus: ({ headers }) => (headers?.["range"] ? "206" : "200"),
+    additionalResponses: {
+      "416": { description: "Range Not Satisfiable" },
+    },
+    handler: handleGetAttachmentContentRoute,
+  },
+  {
+    operationId: "attachment_delete",
+    endpoint: "attachments",
+    method: "DELETE",
+    summary: "Delete attachment",
+    description: "Delete an attachment by ID.",
+    tags: ["attachments"],
+    requestBody: z.object({
+      attachmentId: z.string(),
+    }),
+    responseStatus: "204",
+    handler: handleDeleteAttachmentRoute,
+  },
+  {
+    operationId: "attachment_get",
+    endpoint: "attachments/:id",
+    method: "GET",
+    summary: "Get attachment metadata",
+    description: "Return metadata and optional base64 data for an attachment.",
+    tags: ["attachments"],
+    responseBody: z.object({
+      id: z.string(),
+      filename: z.string(),
+      mimeType: z.string(),
+      sizeBytes: z.number(),
+      kind: z.string(),
+      data: z.string().describe("Base64-encoded content").nullable(),
+      fileBacked: z.boolean().optional(),
+    }),
+    handler: handleGetAttachmentRoute,
+  },
+  {
+    operationId: "attachment_upload",
+    endpoint: "attachments",
+    method: "POST",
+    summary: "Upload attachment",
+    description:
+      "Upload an attachment. Supports application/json (base64 data or file path reference), multipart/form-data (file + filename + mimeType fields), and application/octet-stream (raw bytes with filename and mimeType query params).",
+    tags: ["attachments"],
+    requestBody: z.object({
+      filename: z.string(),
+      mimeType: z.string(),
+      data: z.string().describe("Base64-encoded file data").optional(),
+      filePath: z
+        .string()
+        .describe("On-disk file path (file-backed upload)")
+        .optional(),
+      trustedSource: z
+        .boolean()
+        .describe(
+          "Set by the gateway when the file came from a guardian-bound channel actor. Honored only when the request is authenticated as a gateway service token; ignored otherwise.",
+        )
+        .optional(),
+    }),
+    responseBody: z.object({
+      id: z.string(),
+      original_filename: z.string(),
+      mime_type: z.string(),
+      size_bytes: z.number(),
+      kind: z.string(),
+    }),
+    handler: handleUploadAttachmentRoute,
+  },
+  {
+    operationId: "attachment_register",
+    endpoint: "attachments/register",
+    method: "POST",
+    summary: "Register a file-backed attachment",
+    description:
+      "Register an on-disk file as a file-backed attachment. The file must be within the workspace directory and must remain on disk for the lifetime of the attachment.",
+    tags: ["attachments"],
+    requestBody: z.object({
+      path: z.string().describe("Absolute path to the file"),
+      mimeType: z.string().describe("MIME type of the file"),
+      filename: z
+        .string()
+        .describe("Display filename (defaults to basename of path)")
+        .optional(),
+    }),
+    responseBody: z.object({
+      id: z.string(),
+      originalFilename: z.string(),
+      mimeType: z.string(),
+      sizeBytes: z.number(),
+      kind: z.string(),
+      filePath: z.string(),
+      createdAt: z.number(),
+    }),
+    handler: handleAttachmentRegister,
+  },
+  {
+    operationId: "attachment_lookup",
+    endpoint: "attachments/lookup",
+    method: "POST",
+    summary: "Look up attachment by source path",
+    description:
+      "Search for a previously registered attachment by its original source path, scoped to a conversation.",
+    tags: ["attachments"],
+    requestBody: z.object({
+      sourcePath: z.string().describe("Original source path of the file"),
+      conversationId: z.string().describe("Conversation ID to search within"),
+    }),
+    responseBody: z.object({
+      filePath: z.string(),
+    }),
+    handler: handleAttachmentLookup,
+  },
+];