feat: API sync and documentation audit - 100% endpoint coverage (#94)

Code quality:
- Add Zod validation to 14 route handlers that used raw JSON.parse
  (favicon, find-duplicates, barcode-read, upscale, blur-faces,
  erase-object, colorize, enhance-faces, red-eye-removal,
  remove-background/effects, auth, api-keys, roles, teams,
  analytics, settings, user-files)
- Standardize error responses to safeParse + formatZodErrors pattern
- Replace unsafe `as` type casts with schema validation

OpenAPI spec (89 -> 115 operations):
- Add 14 missing tool endpoints (adjust-colors, sharpening,
  optimize-for-web, image-enhancement, noise-removal, red-eye-removal,
  restore-photo, passport-photo, colorize, enhance-faces, image-to-base64)
- Add 12 missing non-tool endpoints (analytics, features, audit-log,
  roles, admin-health)
- Add typed error schemas for 401/403/409 responses
- Add descriptions to all path parameters
- Bump version from 0.9.0 to 1.15.9

Documentation:
- Fix 8 incorrect env var defaults in configuration guide
- Add 15 undocumented env vars to configuration guide
- Fix tool ID mismatch (color-adjustments -> adjust-colors)
- Add 4 new API sections (Roles, Audit Log, Analytics, Features)
- Add image-enhancement to AI engine reference
- Update AI tool count from 13 to 14 across all docs
- Add 6 missing doc links to README

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

@@ -3,12 +3,18 @@ import { writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
+import { z } from "zod";
 import { readBarcodes } from "zxing-wasm/reader";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { ensureSharpCompat } from "../../lib/heic-converter.js";
 import { createWorkspace } from "../../lib/workspace.js";
 
+const settingsSchema = z.object({
+  tryHarder: z.boolean().default(true),
+});
+
 /**
  * Color palette for bounding-box overlays.
  * Semi-transparent fills paired with solid strokes.
@@ -111,9 +117,23 @@ export function registerBarcodeRead(app: FastifyInstance) {
       });
     }
 
+    // Parse and validate settings
+    let settings: z.infer<typeof settingsSchema>;
     try {
-      const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
-      const tryHarder = settings.tryHarder !== false; // default true
+      const parsed = settingsRaw ? JSON.parse(settingsRaw) : {};
+      const result = settingsSchema.safeParse(parsed);
+      if (!result.success) {
+        return reply
+          .status(400)
+          .send({ error: "Invalid settings", details: formatZodErrors(result.error.issues) });
+      }
+      settings = result.data;
+    } catch {
+      return reply.status(400).send({ error: "Settings must be valid JSON" });
+    }
+
+    try {
+      const tryHarder = settings.tryHarder;
 
       // Decode HEIC/HEIF if needed, then auto-orient
       fileBuffer = await ensureSharpCompat(fileBuffer);

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

@@ -6,6 +6,7 @@ import { getBundleForTool, TOOL_BUNDLE_MAP } from "@ashim/shared";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -14,6 +15,11 @@ import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
 import { registerToolProcessFn } from "../tool-factory.js";
 
+const settingsSchema = z.object({
+  blurRadius: z.number().min(1).max(100).default(30),
+  sensitivity: z.number().min(0).max(1).default(0.5),
+});
+
 /** Face detection and blurring route. */
 export function registerBlurFaces(app: FastifyInstance) {
   app.post("/api/v1/tools/blur-faces", async (request: FastifyRequest, reply: FastifyReply) => {
@@ -67,7 +73,19 @@ export function registerBlurFaces(app: FastifyInstance) {
     }
 
     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: formatZodErrors(result.error.issues) });
+        }
+        settings = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
 
       if (validation.format === "heif") {
         fileBuffer = await decodeHeic(fileBuffer);
@@ -78,12 +96,13 @@ export function registerBlurFaces(app: FastifyInstance) {
         fileBuffer = await decodeToSharpCompat(fileBuffer, validation.format);
       }
 
+      const { blurRadius, sensitivity } = settings;
       request.log.info(
         {
           toolId: "blur-faces",
           imageSize: fileBuffer.length,
-          blurRadius: settings.blurRadius,
-          sensitivity: settings.sensitivity,
+          blurRadius,
+          sensitivity,
         },
         "Starting face blur",
       );
@@ -114,8 +133,8 @@ export function registerBlurFaces(app: FastifyInstance) {
         fileBuffer,
         join(workspacePath, "output"),
         {
-          blurRadius: settings.blurRadius ?? 30,
-          sensitivity: settings.sensitivity ?? 0.5,
+          blurRadius,
+          sensitivity,
         },
         onProgress,
       );

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

@@ -7,6 +7,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -16,6 +17,11 @@ import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
 import { registerToolProcessFn } from "../tool-factory.js";
 
+const settingsSchema = z.object({
+  intensity: z.number().min(0).max(1).default(1.0),
+  model: z.enum(["auto", "ddcolor", "opencv"]).default("auto"),
+});
+
 /**
  * AI photo colorization route.
  * Converts B&W / grayscale photos to full color using DDColor,
@@ -73,9 +79,21 @@ export function registerColorize(app: FastifyInstance) {
     }
 
     try {
-      const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
-      const intensity = Math.min(1, Math.max(0, Number(settings.intensity) || 1.0));
-      const model = settings.model || "auto";
+      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: formatZodErrors(result.error.issues) });
+        }
+        settings = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
+
+      const { intensity, model } = settings;
 
       request.log.info(
         { toolId: "colorize", imageSize: fileBuffer.length, intensity, model },

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

@@ -7,6 +7,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -15,6 +16,13 @@ import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
 import { registerToolProcessFn } from "../tool-factory.js";
 
+const settingsSchema = z.object({
+  model: z.enum(["auto", "gfpgan", "codeformer"]).default("auto"),
+  strength: z.number().min(0).max(1).default(0.8),
+  onlyCenterFace: z.boolean().default(false),
+  sensitivity: z.number().min(0).max(1).default(0.5),
+});
+
 /** Face enhancement route using GFPGAN/CodeFormer. */
 export function registerEnhanceFaces(app: FastifyInstance) {
   app.post("/api/v1/tools/enhance-faces", async (request: FastifyRequest, reply: FastifyReply) => {
@@ -68,11 +76,21 @@ export function registerEnhanceFaces(app: FastifyInstance) {
     }
 
     try {
-      const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
-      const model = settings.model || "auto";
-      const strength = Number(settings.strength) || 0.8;
-      const onlyCenterFace = Boolean(settings.onlyCenterFace);
-      const sensitivity = Number(settings.sensitivity) || 0.5;
+      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: formatZodErrors(result.error.issues) });
+        }
+        settings = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
+
+      const { model, strength, onlyCenterFace, sensitivity } = settings;
       request.log.info(
         { toolId: "enhance-faces", imageSize: fileBuffer.length, model, strength },
         "Starting face enhancement",

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

@@ -5,6 +5,7 @@ import { inpaint } from "@ashim/ai";
 import { getBundleForTool, TOOL_BUNDLE_MAP } from "@ashim/shared";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
+import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
@@ -27,6 +28,13 @@ const EXT_MAP: Record<string, string> = {
 
 const BROWSER_PREVIEWABLE = new Set(["png", "jpg", "jpeg", "webp", "gif", "avif", "bmp"]);
 
+const settingsSchema = z.object({
+  format: z
+    .enum(["png", "jpg", "jpeg", "webp", "tiff", "gif", "avif", "heic", "heif"])
+    .default("png"),
+  quality: z.number().int().min(1).max(100).default(95),
+});
+
 /**
  * Object eraser / inpainting route.
  * Accepts an image and a mask image, erases masked areas using LaMa.
@@ -101,6 +109,19 @@ export function registerEraseObject(app: FastifyInstance) {
     }
 
     try {
+      // Validate format and quality via Zod
+      const settingsResult = settingsSchema.safeParse({ format, quality });
+      if (!settingsResult.success) {
+        return reply.status(400).send({
+          error: "Invalid settings",
+          details: settingsResult.error.issues
+            .map((i) => (i.path.length > 0 ? `${i.path.join(".")}: ${i.message}` : i.message))
+            .join("; "),
+        });
+      }
+      format = settingsResult.data.format;
+      quality = settingsResult.data.quality;
+
       request.log.info(
         {
           toolId: "erase-object",

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

@@ -3,9 +3,14 @@ import { basename, extname } from "node:path";
 import archiver from "archiver";
 import type { FastifyInstance } from "fastify";
 import sharp from "sharp";
+import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
 import { ensureSharpCompat } from "../../lib/heic-converter.js";
 
+const settingsSchema = z.object({}).passthrough();
+
 const FAVICON_SIZES = [
   { name: "favicon-16x16.png", size: 16, format: "png" as const },
   { name: "favicon-32x32.png", size: 32, format: "png" as const },
@@ -23,6 +28,7 @@ interface UploadedFile {
 export function registerFavicon(app: FastifyInstance) {
   app.post("/api/v1/tools/favicon", async (request, reply) => {
     const uploadedFiles: UploadedFile[] = [];
+    let settingsRaw: string | null = null;
 
     try {
       const parts = request.parts();
@@ -35,6 +41,8 @@ export function registerFavicon(app: FastifyInstance) {
           const buffer = Buffer.concat(chunks);
           const filename = basename(part.filename ?? `image-${uploadedFiles.length + 1}`);
           uploadedFiles.push({ buffer, filename });
+        } else if (part.fieldname === "settings") {
+          settingsRaw = part.value as string;
         }
       }
     } catch (err) {
@@ -48,6 +56,30 @@ export function registerFavicon(app: FastifyInstance) {
       return reply.status(400).send({ error: "No image file provided" });
     }
 
+    // Validate all uploaded files
+    for (const file of uploadedFiles) {
+      const validation = await validateImageBuffer(file.buffer, file.filename);
+      if (!validation.valid) {
+        return reply
+          .status(400)
+          .send({ error: `Invalid file "${file.filename}": ${validation.reason}` });
+      }
+    }
+
+    if (settingsRaw) {
+      try {
+        const parsed = JSON.parse(settingsRaw);
+        const result = settingsSchema.safeParse(parsed);
+        if (!result.success) {
+          return reply
+            .status(400)
+            .send({ error: "Invalid settings", details: formatZodErrors(result.error.issues) });
+        }
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
+    }
+
     try {
       const jobId = randomUUID();
       const isSingleFile = uploadedFiles.length === 1;

apps/api/src/routes/tools/find-duplicates.ts

@@ -1,10 +1,15 @@
 import { basename } from "node:path";
 import type { FastifyInstance } from "fastify";
 import sharp from "sharp";
+import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { ensureSharpCompat } from "../../lib/heic-converter.js";
 
-const DEFAULT_THRESHOLD = 8;
+const settingsSchema = z.object({
+  threshold: z.number().min(0).max(20).default(8),
+});
+
 const THUMBNAIL_WIDTH = 200;
 
 /**
@@ -89,7 +94,7 @@ async function extractFileInfo(file: FileData): Promise<FileInfo> {
 export function registerFindDuplicates(app: FastifyInstance) {
   app.post("/api/v1/tools/find-duplicates", async (request, reply) => {
     const files: FileData[] = [];
-    let threshold = DEFAULT_THRESHOLD;
+    let settingsRaw: string | null = null;
 
     try {
       const parts = request.parts();
@@ -107,11 +112,11 @@ export function registerFindDuplicates(app: FastifyInstance) {
               originalSize: buf.length,
             });
           }
+        } else if (part.type === "field" && part.fieldname === "settings") {
+          settingsRaw = part.value as string;
         } else if (part.type === "field" && part.fieldname === "threshold") {
-          const val = Number(part.value);
-          if (!Number.isNaN(val) && val >= 0 && val <= 20) {
-            threshold = val;
-          }
+          // Legacy: accept bare threshold field as settings
+          settingsRaw = JSON.stringify({ threshold: Number(part.value) });
         }
       }
     } catch (err) {
@@ -121,6 +126,23 @@ export function registerFindDuplicates(app: FastifyInstance) {
       });
     }
 
+    // Parse and validate settings
+    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: formatZodErrors(result.error.issues) });
+      }
+      settings = result.data;
+    } catch {
+      return reply.status(400).send({ error: "Settings must be valid JSON" });
+    }
+
+    const threshold = settings.threshold;
+
     if (files.length < 2) {
       return reply
         .status(400)

apps/api/src/routes/tools/image-to-base64.ts

@@ -2,6 +2,7 @@ import { basename } from "node:path";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
+import { formatZodErrors } from "../../lib/errors.js";
 import { ensureSharpCompat } from "../../lib/heic-converter.js";
 
 const settingsSchema = z.object({
@@ -89,7 +90,7 @@ export function registerImageToBase64(app: FastifyInstance) {
       if (!parsed.success) {
         return reply.status(400).send({
           error: "Invalid settings",
-          details: parsed.error.flatten().fieldErrors,
+          details: formatZodErrors(parsed.error.issues),
         });
       }
       const opts = parsed.data;

apps/api/src/routes/tools/noise-removal.ts

@@ -6,6 +6,7 @@ import { getBundleForTool, TOOL_BUNDLE_MAP } from "@ashim/shared";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -79,7 +80,20 @@ export function registerNoiseRemoval(app: FastifyInstance) {
     }
 
     try {
-      const parsed = settingsSchema.parse(settingsRaw ? JSON.parse(settingsRaw) : {});
+      let parsed: z.infer<typeof settingsSchema>;
+      try {
+        const raw = settingsRaw ? JSON.parse(settingsRaw) : {};
+        const result = settingsSchema.safeParse(raw);
+        if (!result.success) {
+          return reply
+            .status(400)
+            .send({ error: "Invalid settings", details: formatZodErrors(result.error.issues) });
+        }
+        parsed = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
+
       request.log.info(
         { toolId: "noise-removal", imageSize: fileBuffer.length, tier: parsed.tier },
         "Starting noise removal",

apps/api/src/routes/tools/red-eye-removal.ts

@@ -6,6 +6,7 @@ import { getBundleForTool, TOOL_BUNDLE_MAP } from "@ashim/shared";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -14,6 +15,13 @@ import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
 import { registerToolProcessFn } from "../tool-factory.js";
 
+const settingsSchema = z.object({
+  sensitivity: z.number().min(0).max(100).default(50),
+  strength: z.number().min(0).max(100).default(70),
+  format: z.string().optional(),
+  quality: z.number().min(1).max(100).default(90),
+});
+
 /** Red eye detection and removal route. */
 export function registerRedEyeRemoval(app: FastifyInstance) {
   app.post(
@@ -69,7 +77,19 @@ export function registerRedEyeRemoval(app: FastifyInstance) {
       }
 
       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: formatZodErrors(result.error.issues) });
+          }
+          settings = result.data;
+        } catch {
+          return reply.status(400).send({ error: "Settings must be valid JSON" });
+        }
 
         if (validation.format === "heif") {
           fileBuffer = await decodeHeic(fileBuffer);
@@ -80,12 +100,13 @@ export function registerRedEyeRemoval(app: FastifyInstance) {
           fileBuffer = await decodeToSharpCompat(fileBuffer, validation.format);
         }
 
+        const { sensitivity, strength, format: outputFormat, quality } = settings;
         request.log.info(
           {
             toolId: "red-eye-removal",
             imageSize: fileBuffer.length,
-            sensitivity: settings.sensitivity,
-            strength: settings.strength,
+            sensitivity,
+            strength,
           },
           "Starting red eye removal",
         );
@@ -116,10 +137,10 @@ export function registerRedEyeRemoval(app: FastifyInstance) {
           fileBuffer,
           join(workspacePath, "output"),
           {
-            sensitivity: settings.sensitivity ?? 50,
-            strength: settings.strength ?? 70,
-            format: settings.format,
-            quality: settings.quality ?? 90,
+            sensitivity,
+            strength,
+            format: outputFormat,
+            quality,
           },
           onProgress,
         );

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

@@ -7,6 +7,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
 import { applyEffects } from "../../lib/bg-effects.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -92,7 +93,19 @@ export function registerRemoveBackground(app: FastifyInstance) {
       }
 
       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: formatZodErrors(result.error.issues) });
+          }
+          settings = result.data;
+        } catch {
+          return reply.status(400).send({ error: "Settings must be valid JSON" });
+        }
 
         // Decode HEIC/HEIF before processing
         if (validation.format === "heif") {
@@ -210,14 +223,38 @@ export function registerRemoveBackground(app: FastifyInstance) {
         return reply.status(400).send({ error: "No settings provided" });
       }
 
-      try {
-        const settings = JSON.parse(settingsRaw);
-        const { jobId, filename } = settings;
+      const effectsSchema = z.object({
+        jobId: z.string().min(1),
+        filename: z.string().min(1),
+        backgroundType: z.enum(["transparent", "color", "gradient", "blur", "image"]).optional(),
+        backgroundColor: z.string().optional(),
+        gradientColor1: z.string().optional(),
+        gradientColor2: z.string().optional(),
+        gradientAngle: z.number().optional(),
+        blurEnabled: z.boolean().optional(),
+        blurIntensity: z.number().min(0).max(100).optional(),
+        shadowEnabled: z.boolean().optional(),
+        shadowOpacity: z.number().min(0).max(100).optional(),
+      });
 
-        if (!jobId || !filename) {
-          return reply.status(400).send({ error: "jobId and filename are required" });
+      try {
+        let settings: z.infer<typeof effectsSchema>;
+        try {
+          const parsed = JSON.parse(settingsRaw);
+          const result = effectsSchema.safeParse(parsed);
+          if (!result.success) {
+            return reply.status(400).send({
+              error: "Invalid settings",
+              details: formatZodErrors(result.error.issues),
+            });
+          }
+          settings = result.data;
+        } catch {
+          return reply.status(400).send({ error: "Settings must be valid JSON" });
         }
 
+        const { jobId, filename } = settings;
+
         const workspacePath = getWorkspacePath(jobId);
 
         const baseName = filename.replace(/\.[^.]+$/, "");

apps/api/src/routes/tools/restore-photo.ts

@@ -7,6 +7,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -82,7 +83,19 @@ export function registerRestorePhoto(app: FastifyInstance) {
     }
 
     try {
-      const settings = settingsSchema.parse(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: formatZodErrors(result.error.issues) });
+        }
+        settings = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
 
       request.log.info(
         { toolId: "restore-photo", imageSize: fileBuffer.length, mode: settings.mode },

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

@@ -7,6 +7,7 @@ import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
+import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
@@ -15,6 +16,15 @@ import { createWorkspace } from "../../lib/workspace.js";
 import { updateSingleFileProgress } from "../progress.js";
 import { registerToolProcessFn } from "../tool-factory.js";
 
+const settingsSchema = z.object({
+  scale: z.union([z.number(), z.string()]).transform(Number).default(2),
+  model: z.string().default("auto"),
+  faceEnhance: z.boolean().default(false),
+  denoise: z.union([z.number(), z.string()]).transform(Number).default(0),
+  format: z.string().default("png"),
+  quality: z.union([z.number(), z.string()]).transform(Number).default(95),
+});
+
 /**
  * AI image upscaling route.
  * Uses Real-ESRGAN when available, falls back to Lanczos.
@@ -71,13 +81,26 @@ export function registerUpscale(app: FastifyInstance) {
     }
 
     try {
-      const settings = settingsRaw ? JSON.parse(settingsRaw) : {};
-      const scale = Number(settings.scale) || 2;
-      const model = settings.model || "auto";
-      const faceEnhance = Boolean(settings.faceEnhance);
-      const denoise = Number(settings.denoise) || 0;
-      const format = settings.format || "png";
-      const outputQuality = Number(settings.quality) || 95;
+      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: formatZodErrors(result.error.issues) });
+        }
+        settings = result.data;
+      } catch {
+        return reply.status(400).send({ error: "Settings must be valid JSON" });
+      }
+
+      const scale = settings.scale;
+      const model = settings.model;
+      const faceEnhance = settings.faceEnhance;
+      const denoise = settings.denoise;
+      const format = settings.format;
+      const outputQuality = settings.quality;
       request.log.info(
         { toolId: "upscale", imageSize: fileBuffer.length, scale, model, format },
         "Starting upscale",