chore: remove dead code, add test infrastructure, update docs

- Delete 3 dead files: use-batch-processor.ts, use-i18n.ts, smart-crop.ts (AI package)
- Remove dead getJobProgress function and unused runPythonScript wrapper
- Remove 6 unused imports across API and web apps
- Remove unused shared types (ImageFormat, AppConfig, ApiError, HealthResponse, JobProgress)
  and constants (SUPPORTED_INPUT_FORMATS/OUTPUT_FORMATS, DEFAULT_OUTPUT_FORMAT)
- Remove unused store method (setOriginalBlobUrl) and clean AI package re-exports
- Add test infrastructure: vitest config, unit/integration/e2e tests, fixtures, screenshots
- Add Docker test infrastructure: Dockerfile.test, docker-compose.test.yml
- Add download_models.py for pre-baking AI model weights in Docker
- Add filename sanitization utility (apps/api/src/lib/filename.ts)
- Update .gitignore to exclude coverage/, *.tsbuildinfo, .superpowers/, test artifacts
- Update .dockerignore to exclude test/coverage/IDE artifacts from builds
- Update docs: remove smart crop from AI docs (uses Sharp directly), update bridge docs

apps/api/src/routes/batch.ts

@@ -8,28 +8,15 @@
  * Returns a ZIP file containing all processed images.
  */
 import { randomUUID } from "node:crypto";
-import { basename } from "node:path";
 import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
 import archiver from "archiver";
 import PQueue from "p-queue";
 import { getToolConfig } from "./tool-factory.js";
 import { validateImageBuffer } from "../lib/file-validation.js";
+import { sanitizeFilename } from "../lib/filename.js";
 import { env } from "../config.js";
 import { updateJobProgress, type JobProgress } from "./progress.js";
 
-/**
- * Sanitize a filename to prevent path traversal attacks.
- */
-function sanitizeFilename(raw: string): string {
-  let name = basename(raw);
-  name = name.replace(/\.\./g, "");
-  name = name.replace(/\0/g, "");
-  if (!name || name === "." || name === "..") {
-    name = "image";
-  }
-  return name;
-}
-
 interface ParsedFile {
   buffer: Buffer;
   filename: string;

apps/api/src/routes/files.ts

@@ -1,27 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { writeFile, readFile, stat } from "node:fs/promises";
-import { join, basename, extname } from "node:path";
+import { join, 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;
-}
+import { sanitizeFilename } from "../lib/filename.js";
 
 /**
  * Guard against path traversal in URL params.

apps/api/src/routes/pipeline.ts

@@ -8,13 +8,14 @@
  */
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
-import { join, basename } from "node:path";
+import { join } from "node:path";
 import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { getToolConfig } from "./tool-factory.js";
 import { validateImageBuffer } from "../lib/file-validation.js";
 import { createWorkspace } from "../lib/workspace.js";
+import { sanitizeFilename } from "../lib/filename.js";
 import { db, schema } from "../db/index.js";
 
 /** Schema for a single pipeline step. */
@@ -25,29 +26,16 @@ const pipelineStepSchema = z.object({
 
 /** Schema for a full pipeline definition. */
 const pipelineDefinitionSchema = z.object({
-  steps: z.array(pipelineStepSchema).min(1, "Pipeline must have at least one step"),
+  steps: z.array(pipelineStepSchema).min(1, "Pipeline must have at least one step").max(20, "Pipeline cannot exceed 20 steps"),
 });
 
 /** Schema for saving a pipeline. */
 const savePipelineSchema = z.object({
   name: z.string().min(1, "Pipeline name is required").max(100),
   description: z.string().max(500).optional(),
-  steps: z.array(pipelineStepSchema).min(1, "Pipeline must have at least one step"),
+  steps: z.array(pipelineStepSchema).min(1, "Pipeline must have at least one step").max(20, "Pipeline cannot exceed 20 steps"),
 });
 
-/**
- * Sanitize a filename to prevent path traversal attacks.
- */
-function sanitizeFilename(raw: string): string {
-  let name = basename(raw);
-  name = name.replace(/\.\./g, "");
-  name = name.replace(/\0/g, "");
-  if (!name || name === "." || name === "..") {
-    name = "image";
-  }
-  return name;
-}
-
 export async function registerPipelineRoutes(app: FastifyInstance): Promise<void> {
   /**
    * POST /api/v1/pipeline/execute

apps/api/src/routes/progress.ts

@@ -75,13 +75,6 @@ export function updateSingleFileProgress(
   }
 }
 
-/**
- * Get current progress for a job.
- */
-export function getJobProgress(jobId: string): JobProgress | undefined {
-  return jobProgressStore.get(jobId);
-}
-
 export async function registerProgressRoutes(
   app: FastifyInstance,
 ): Promise<void> {

apps/api/src/routes/tool-factory.ts

@@ -1,10 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
-import { join, extname, basename } from "node:path";
+import { join } from "node:path";
 import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
 import { z } from "zod";
 import { createWorkspace } from "../lib/workspace.js";
 import { validateImageBuffer } from "../lib/file-validation.js";
+import { sanitizeFilename } from "../lib/filename.js";
 
 export interface ToolRouteConfig<T> {
   /** Unique tool identifier, used as the URL path segment. */
@@ -34,19 +35,6 @@ export function getToolConfig(toolId: string): ToolRouteConfig<any> | undefined
   return toolRegistry.get(toolId);
 }
 
-/**
- * Sanitize a filename to prevent path traversal attacks.
- */
-function sanitizeFilename(raw: string): string {
-  let name = basename(raw);
-  name = name.replace(/\.\./g, "");
-  name = name.replace(/\0/g, "");
-  if (!name || name === "." || name === "..") {
-    name = "image";
-  }
-  return name;
-}
-
 /**
  * Factory that registers a POST /api/v1/tools/:toolId route.
  *
@@ -159,11 +147,11 @@ export function createToolRoute<T>(
         });
       } catch (err) {
         // Catch Sharp / processing errors and return a clean API error
-        const message =
-          err instanceof Error ? err.message : "Image processing failed";
+        const message = err instanceof Error ? err.message : "Image processing failed";
+        request.log.error({ err, toolId: config.toolId }, "Tool processing failed");
         return reply.status(422).send({
           error: "Processing failed",
-          details: message,
+          details: process.env.NODE_ENV === "production" ? undefined : message,
         });
       }
     },

apps/api/src/routes/tools/barcode-read.ts

@@ -2,6 +2,7 @@ import sharp from "sharp";
 import jsQR from "jsqr";
 import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
 import { basename } from "node:path";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 
 /**
  * Read QR codes and barcodes from uploaded images.
@@ -36,6 +37,12 @@ export function registerBarcodeRead(app: FastifyInstance) {
         return reply.status(400).send({ error: "No image file provided" });
       }
 
+      // Validate the uploaded image
+      const validation = await validateImageBuffer(fileBuffer);
+      if (!validation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+      }
+
       try {
         // Convert to RGBA raw pixel data for jsQR
         const image = sharp(fileBuffer);

apps/api/src/routes/tools/blur-faces.ts

@@ -5,6 +5,7 @@ import { join, basename } from "node:path";
 import { blurFaces } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 
 /**
  * Face detection and blurring route.
@@ -46,6 +47,11 @@ export function registerBlurFaces(app: FastifyInstance) {
         return reply.status(400).send({ error: "No image file provided" });
       }
 
+      const validation = await validateImageBuffer(fileBuffer);
+      if (!validation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+      }
+
       try {
         const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
         const jobId = randomUUID();

apps/api/src/routes/tools/bulk-rename.ts

@@ -85,7 +85,7 @@ export function registerBulkRename(app: FastifyInstance) {
               .replace(/\{\{original\}\}/g, files[i].filename.replace(ext, "")) +
             ext;
 
-          archive.append(files[i].buffer, { name: newName });
+          archive.append(files[i].buffer, { name: basename(newName) });
         }
 
         await archive.finalize();

apps/api/src/routes/tools/collage.ts

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { createWorkspace } from "../../lib/workspace.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 
 const settingsSchema = z.object({
   layout: z.enum(["2x2", "3x3", "1x3", "2x1", "3x1", "1x2"]).default("2x2"),
@@ -54,6 +55,14 @@ export function registerCollage(app: FastifyInstance) {
         return reply.status(400).send({ error: "No images provided" });
       }
 
+      // Validate all files
+      for (const file of files) {
+        const validation = await validateImageBuffer(file.buffer);
+        if (!validation.valid) {
+          return reply.status(400).send({ error: `Invalid file "${file.filename}": ${validation.reason}` });
+        }
+      }
+
       let settings: z.infer<typeof settingsSchema>;
       try {
         const parsed = settingsRaw ? JSON.parse(settingsRaw) : {};

apps/api/src/routes/tools/compose.ts

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createWorkspace } from "../../lib/workspace.js";
+import { sanitizeFilename } from "../../lib/filename.js";
 
 const settingsSchema = z.object({
   x: z.number().min(0).default(0),
@@ -41,7 +42,7 @@ export function registerCompose(app: FastifyInstance) {
               overlayBuffer = buf;
             } else {
               baseBuffer = buf;
-              filename = part.filename ?? "image";
+              filename = sanitizeFilename(part.filename ?? "image");
             }
           } else if (part.fieldname === "settings") {
             settingsRaw = part.value as string;

apps/api/src/routes/tools/erase-object.ts

@@ -5,6 +5,7 @@ import { join, basename } from "node:path";
 import { inpaint } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 
 /**
  * Object eraser / inpainting route.
@@ -54,6 +55,15 @@ export function registerEraseObject(app: FastifyInstance) {
           .send({ error: "No mask image provided. Upload a mask as a second file with fieldname 'mask'" });
       }
 
+      const imageValidation = await validateImageBuffer(imageBuffer);
+      if (!imageValidation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${imageValidation.reason}` });
+      }
+      const maskValidation = await validateImageBuffer(maskBuffer);
+      if (!maskValidation.valid) {
+        return reply.status(400).send({ error: `Invalid mask: ${maskValidation.reason}` });
+      }
+
       try {
         const jobId = randomUUID();
         const workspacePath = await createWorkspace(jobId);

apps/api/src/routes/tools/favicon.ts

@@ -1,9 +1,7 @@
-import { z } from "zod";
 import sharp from "sharp";
 import archiver from "archiver";
 import type { FastifyInstance } from "fastify";
 import { randomUUID } from "node:crypto";
-import { basename } from "node:path";
 
 const FAVICON_SIZES = [
   { name: "favicon-16x16.png", size: 16, format: "png" as const },

apps/api/src/routes/tools/ocr.ts

@@ -1,9 +1,16 @@
 import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
 import { randomUUID } from "node:crypto";
 import { basename } from "node:path";
+import { z } from "zod";
 import { extractText } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
+
+const settingsSchema = z.object({
+  engine: z.enum(["tesseract", "paddleocr"]).default("tesseract"),
+  language: z.enum(["en", "de", "fr", "es", "zh", "ja", "ko"]).default("en"),
+});
 
 /**
  * OCR / text extraction route.
@@ -45,8 +52,24 @@ export function registerOcr(app: FastifyInstance) {
         return reply.status(400).send({ error: "No image file provided" });
       }
 
+      const validation = await validateImageBuffer(fileBuffer);
+      if (!validation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+      }
+
       try {
-        const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
+        let settings: z.infer<typeof settingsSchema>;
+        try {
+          const parsed = settingsRaw ? JSON.parse(settingsRaw) : {};
+          const result = settingsSchema.safeParse(parsed);
+          if (!result.success) {
+            return reply.status(400).send({ error: "Invalid settings", details: result.error.issues });
+          }
+          settings = result.data;
+        } catch {
+          return reply.status(400).send({ error: "Settings must be valid JSON" });
+        }
+
         const jobId = randomUUID();
         const workspacePath = await createWorkspace(jobId);
 

apps/api/src/routes/tools/remove-background.ts

@@ -5,6 +5,7 @@ import { join, basename } from "node:path";
 import { removeBackground } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 
 /**
  * AI background removal route.
@@ -46,6 +47,11 @@ export function registerRemoveBackground(app: FastifyInstance) {
         return reply.status(400).send({ error: "No image file provided" });
       }
 
+      const validation = await validateImageBuffer(fileBuffer);
+      if (!validation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+      }
+
       try {
         const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
         const jobId = randomUUID();

apps/api/src/routes/tools/svg-to-raster.ts

@@ -13,6 +13,25 @@ const settingsSchema = z.object({
   outputFormat: z.enum(["png", "jpg", "webp"]).default("png"),
 });
 
+const MAX_SVG_SIZE = 10 * 1024 * 1024; // 10MB
+
+function sanitizeSvg(buffer: Buffer): Buffer {
+  if (buffer.length > MAX_SVG_SIZE) {
+    throw new Error(`SVG exceeds maximum size of ${MAX_SVG_SIZE / 1024 / 1024}MB`);
+  }
+  let svg = buffer.toString("utf-8");
+  // Remove DOCTYPE to prevent XXE
+  svg = svg.replace(/<!DOCTYPE[^>]*>/gi, "");
+  // Remove script tags
+  svg = svg.replace(/<script[\s\S]*?<\/script>/gi, "");
+  // Remove event handlers (onload, onclick, etc.)
+  svg = svg.replace(/\bon\w+\s*=/gi, "data-removed=");
+  // Remove external resource references
+  svg = svg.replace(/xlink:href\s*=\s*["']https?:\/\//gi, 'xlink:href="data:,');
+  svg = svg.replace(/href\s*=\s*["']https?:\/\//gi, 'href="data:,');
+  return Buffer.from(svg, "utf-8");
+}
+
 /**
  * SVG to raster conversion.
  * Custom route since input is SVG (not validated as image by magic bytes).
@@ -50,6 +69,15 @@ export function registerSvgToRaster(app: FastifyInstance) {
         return reply.status(400).send({ error: "No SVG file provided" });
       }
 
+      // Sanitize SVG to prevent XXE, SSRF, and script injection
+      try {
+        fileBuffer = sanitizeSvg(fileBuffer);
+      } catch (err) {
+        return reply.status(400).send({
+          error: err instanceof Error ? err.message : "Invalid SVG",
+        });
+      }
+
       let settings: z.infer<typeof settingsSchema>;
       try {
         const parsed = settingsRaw ? JSON.parse(settingsRaw) : {};

apps/api/src/routes/tools/upscale.ts

@@ -5,6 +5,7 @@ import { join, basename } from "node:path";
 import { upscale } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 
 /**
  * AI image upscaling route.
@@ -46,6 +47,11 @@ export function registerUpscale(app: FastifyInstance) {
         return reply.status(400).send({ error: "No image file provided" });
       }
 
+      const validation = await validateImageBuffer(fileBuffer);
+      if (!validation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+      }
+
       try {
         const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
         const scale = Number(settings.scale) || 2;

apps/api/src/routes/tools/watermark-image.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { createToolRoute } from "../tool-factory.js";
 import sharp from "sharp";
 import type { FastifyInstance } from "fastify";
 

apps/api/src/routes/tools/watermark-text.ts

@@ -49,9 +49,13 @@ export function registerWatermarkText(app: FastifyInstance) {
         const spacingX = settings.fontSize * 6;
         const spacingY = settings.fontSize * 4;
         let textElements = "";
-        for (let y = 0; y < height + spacingY; y += spacingY) {
+        const maxElements = 500;
+        let count = 0;
+        outer: for (let y = 0; y < height + spacingY; y += spacingY) {
           for (let x = 0; x < width + spacingX; x += spacingX) {
+            if (count >= maxElements) break outer;
             textElements += `<text x="${x}" y="${y}" font-size="${settings.fontSize}" fill="${rgba}" font-family="sans-serif" transform="rotate(${settings.rotation},${x},${y})">${escapedText}</text>`;
+            count++;
           }
         }
         svgOverlay = `<svg width="${width}" height="${height}">${textElements}</svg>`;