feat(api): add multipart file upload, workspace management, and download routes

- Register @fastify/multipart plugin with size limits from env config
- Workspace manager: createWorkspace, getWorkspacePath, cleanupWorkspace
- File validation: magic byte detection, format check, megapixel limit
- POST /api/v1/upload: multipart upload with validation, returns jobId + file metadata
- GET /api/v1/download/:jobId/:filename: serve files with Content-Disposition
- Path traversal guards on all file-serving endpoints
- Add @stirling-image/image-engine and sharp as API dependencies
- Add apiUpload, getDownloadUrl, apiDownloadBlob to web client

apps/api/src/index.ts

@@ -7,8 +7,10 @@ import { env } from "./config.js";
 import { APP_VERSION } from "@stirling-image/shared";
 import { runMigrations } from "./db/migrate.js";
 import { ensureDefaultAdmin, authRoutes, authMiddleware } from "./plugins/auth.js";
+import { registerUpload } from "./plugins/upload.js";
 import { registerStatic } from "./plugins/static.js";
 import { startCleanupCron } from "./lib/cleanup.js";
+import { fileRoutes } from "./routes/files.js";
 
 // Run before anything else
 runMigrations();
@@ -45,12 +47,18 @@ await app.register(swaggerUi, {
   routePrefix: "/api/docs",
 });
 
+// Multipart upload support
+await registerUpload(app);
+
 // Auth middleware (must be registered before routes it protects)
 await authMiddleware(app);
 
 // Auth routes
 await authRoutes(app);
 
+// File upload/download routes
+await fileRoutes(app);
+
 // Health check
 app.get("/api/v1/health", async () => ({
   status: "healthy",

apps/api/src/lib/file-validation.ts

@@ -0,0 +1,118 @@
+import sharp from "sharp";
+import { env } from "../config.js";
+
+/** Formats we accept as input. */
+const SUPPORTED_INPUT_FORMATS = new Set([
+  "jpeg",
+  "png",
+  "webp",
+  "gif",
+  "tiff",
+  "bmp",
+  "avif",
+]);
+
+interface MagicEntry {
+  bytes: number[];
+  offset: number;
+  format: string;
+}
+
+const MAGIC_BYTES: MagicEntry[] = [
+  { bytes: [0xff, 0xd8, 0xff], offset: 0, format: "jpeg" },
+  { bytes: [0x89, 0x50, 0x4e, 0x47], offset: 0, format: "png" },
+  { bytes: [0x52, 0x49, 0x46, 0x46], offset: 0, format: "webp" }, // RIFF; verified below
+  { bytes: [0x47, 0x49, 0x46], offset: 0, format: "gif" },
+  { bytes: [0x42, 0x4d], offset: 0, format: "bmp" },
+  { bytes: [0x49, 0x49, 0x2a, 0x00], offset: 0, format: "tiff" },
+  { bytes: [0x4d, 0x4d, 0x00, 0x2a], offset: 0, format: "tiff" },
+];
+
+export interface ValidationResult {
+  valid: true;
+  format: string;
+  width: number;
+  height: number;
+}
+
+export interface ValidationError {
+  valid: false;
+  reason: string;
+}
+
+/**
+ * Validate an uploaded image buffer.
+ *
+ * Checks:
+ * 1. Buffer is not empty
+ * 2. Magic bytes match a known image format
+ * 3. Format is in the supported input formats list
+ * 4. Image dimensions do not exceed MAX_MEGAPIXELS
+ */
+export async function validateImageBuffer(
+  buffer: Buffer,
+): Promise<ValidationResult | ValidationError> {
+  // 1. Empty check
+  if (!buffer || buffer.length === 0) {
+    return { valid: false, reason: "File is empty" };
+  }
+
+  // 2. Magic byte detection
+  const detectedFormat = detectMagicBytes(buffer);
+  if (!detectedFormat) {
+    return { valid: false, reason: "Unrecognized image format" };
+  }
+
+  // 3. Supported format check
+  if (!SUPPORTED_INPUT_FORMATS.has(detectedFormat)) {
+    return {
+      valid: false,
+      reason: `Unsupported format: ${detectedFormat}`,
+    };
+  }
+
+  // 4. Dimensions check via sharp metadata
+  try {
+    const metadata = await sharp(buffer).metadata();
+    const width = metadata.width ?? 0;
+    const height = metadata.height ?? 0;
+    const megapixels = (width * height) / 1_000_000;
+
+    if (megapixels > env.MAX_MEGAPIXELS) {
+      return {
+        valid: false,
+        reason: `Image exceeds maximum size: ${megapixels.toFixed(1)}MP (limit: ${env.MAX_MEGAPIXELS}MP)`,
+      };
+    }
+
+    return { valid: true, format: detectedFormat, width, height };
+  } catch {
+    return { valid: false, reason: "Failed to read image metadata" };
+  }
+}
+
+function detectMagicBytes(buffer: Buffer): string | null {
+  for (const entry of MAGIC_BYTES) {
+    if (buffer.length < entry.offset + entry.bytes.length) continue;
+
+    let match = true;
+    for (let i = 0; i < entry.bytes.length; i++) {
+      if (buffer[entry.offset + i] !== entry.bytes[i]) {
+        match = false;
+        break;
+      }
+    }
+
+    if (match) {
+      // For RIFF, verify WEBP signature at bytes 8-11
+      if (entry.format === "webp") {
+        if (buffer.length < 12) continue;
+        const sig = buffer.slice(8, 12).toString("ascii");
+        if (sig !== "WEBP") continue;
+      }
+      return entry.format;
+    }
+  }
+
+  return null;
+}

apps/api/src/lib/workspace.ts

@@ -0,0 +1,29 @@
+import { mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { env } from "../config.js";
+
+/**
+ * Create a workspace directory structure for a processing job.
+ * Returns the workspace root path.
+ */
+export async function createWorkspace(jobId: string): Promise<string> {
+  const root = getWorkspacePath(jobId);
+  await mkdir(join(root, "input"), { recursive: true });
+  await mkdir(join(root, "output"), { recursive: true });
+  return root;
+}
+
+/**
+ * Get the workspace root path for a job.
+ */
+export function getWorkspacePath(jobId: string): string {
+  return join(env.WORKSPACE_PATH, jobId);
+}
+
+/**
+ * Remove the entire workspace directory for a job.
+ */
+export async function cleanupWorkspace(jobId: string): Promise<void> {
+  const root = getWorkspacePath(jobId);
+  await rm(root, { recursive: true, force: true });
+}

apps/api/src/plugins/upload.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance } from "fastify";
+import multipart from "@fastify/multipart";
+import { env } from "../config.js";
+
+export async function registerUpload(app: FastifyInstance): Promise<void> {
+  await app.register(multipart, {
+    limits: {
+      fileSize: env.MAX_UPLOAD_SIZE_MB * 1024 * 1024,
+      files: env.MAX_BATCH_SIZE,
+    },
+  });
+}

apps/api/src/routes/files.ts

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import { writeFile, readFile, stat } from "node:fs/promises";
+import { join, basename, extname } from "node:path";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { createWorkspace, getWorkspacePath } from "../lib/workspace.js";
+import { validateImageBuffer } from "../lib/file-validation.js";
+
+/**
+ * Sanitize a filename to prevent path traversal attacks.
+ * Strips directory separators and `..` sequences, keeps only the base name.
+ */
+function sanitizeFilename(raw: string): string {
+  // Take only the base name (no directories)
+  let name = basename(raw);
+  // Remove any remaining path traversal sequences
+  name = name.replace(/\.\./g, "");
+  // Remove null bytes
+  name = name.replace(/\0/g, "");
+  // If nothing is left, use a fallback
+  if (!name || name === "." || name === "..") {
+    name = "upload";
+  }
+  return name;
+}
+
+/**
+ * Guard against path traversal in URL params.
+ */
+function isPathTraversal(segment: string): boolean {
+  return (
+    segment.includes("..") ||
+    segment.includes("/") ||
+    segment.includes("\\") ||
+    segment.includes("\0")
+  );
+}
+
+export async function fileRoutes(app: FastifyInstance): Promise<void> {
+  // ── POST /api/v1/upload ────────────────────────────────────────
+  app.post(
+    "/api/v1/upload",
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      const jobId = randomUUID();
+      const workspacePath = await createWorkspace(jobId);
+      const inputDir = join(workspacePath, "input");
+
+      const uploadedFiles: Array<{
+        name: string;
+        size: number;
+        format: string;
+      }> = [];
+
+      const parts = request.parts();
+
+      for await (const part of parts) {
+        // Skip non-file fields
+        if (part.type !== "file") continue;
+
+        // Consume buffer from the stream
+        const chunks: Buffer[] = [];
+        for await (const chunk of part.file) {
+          chunks.push(chunk);
+        }
+        const buffer = Buffer.concat(chunks);
+
+        // Skip empty parts (e.g. empty file field)
+        if (buffer.length === 0) continue;
+
+        // Validate the image
+        const validation = await validateImageBuffer(buffer);
+        if (!validation.valid) {
+          return reply.status(400).send({
+            error: `Invalid file "${part.filename}": ${validation.reason}`,
+          });
+        }
+
+        // Sanitize filename
+        const safeName = sanitizeFilename(part.filename ?? "upload");
+
+        // Write to workspace input directory
+        const filePath = join(inputDir, safeName);
+        await writeFile(filePath, buffer);
+
+        uploadedFiles.push({
+          name: safeName,
+          size: buffer.length,
+          format: validation.format,
+        });
+      }
+
+      if (uploadedFiles.length === 0) {
+        return reply.status(400).send({ error: "No valid files uploaded" });
+      }
+
+      return reply.send({
+        jobId,
+        files: uploadedFiles,
+      });
+    },
+  );
+
+  // ── GET /api/v1/download/:jobId/:filename ──────────────────────
+  app.get(
+    "/api/v1/download/:jobId/:filename",
+    async (
+      request: FastifyRequest<{
+        Params: { jobId: string; filename: string };
+      }>,
+      reply: FastifyReply,
+    ) => {
+      const { jobId, filename } = request.params;
+
+      // Guard against path traversal
+      if (isPathTraversal(jobId) || isPathTraversal(filename)) {
+        return reply.status(400).send({ error: "Invalid path" });
+      }
+
+      const workspacePath = getWorkspacePath(jobId);
+
+      // Try output directory first, then input
+      let filePath = join(workspacePath, "output", filename);
+      try {
+        await stat(filePath);
+      } catch {
+        filePath = join(workspacePath, "input", filename);
+        try {
+          await stat(filePath);
+        } catch {
+          return reply.status(404).send({ error: "File not found" });
+        }
+      }
+
+      const buffer = await readFile(filePath);
+      const ext = extname(filename).toLowerCase().replace(/^\./, "");
+      const contentType = getContentType(ext);
+
+      return reply
+        .header("Content-Type", contentType)
+        .header(
+          "Content-Disposition",
+          `attachment; filename="${encodeURIComponent(filename)}"`,
+        )
+        .send(buffer);
+    },
+  );
+}
+
+function getContentType(ext: string): string {
+  const map: Record<string, string> = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp",
+    gif: "image/gif",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+    tif: "image/tiff",
+    avif: "image/avif",
+    svg: "image/svg+xml",
+  };
+  return map[ext] ?? "application/octet-stream";
+}