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/api-keys.ts

@@ -8,36 +8,39 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { and, eq } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
 import { db, schema } from "../db/index.js";
 import { auditLog } from "../lib/audit.js";
 import { getPermissions, hasEffectivePermission } from "../permissions.js";
 import { computeKeyPrefix, hashPassword, requireAuth } from "../plugins/auth.js";
 
+const createApiKeySchema = z.object({
+  name: z.string().max(100, "Key name must be 100 characters or fewer").optional(),
+  permissions: z.array(z.string()).optional(),
+  expiresAt: z.string().optional(),
+});
+
 export async function apiKeyRoutes(app: FastifyInstance): Promise<void> {
   // POST /api/v1/api-keys — Generate a new API key
   app.post("/api/v1/api-keys", async (request: FastifyRequest, reply: FastifyReply) => {
     const user = requireAuth(request, reply);
     if (!user) return;
 
-    const body = request.body as {
-      name?: string;
-      permissions?: string[];
-      expiresAt?: string;
-    } | null;
-    const name = body?.name?.trim() || "Default API Key";
-
-    if (name.length > 100) {
+    const parsed = createApiKeySchema.safeParse(request.body ?? {});
+    if (!parsed.success) {
       return reply.status(400).send({
-        error: "Key name must be 100 characters or fewer",
+        error: parsed.error.issues.map((i) => i.message).join("; "),
         code: "VALIDATION_ERROR",
       });
     }
+    const body = parsed.data;
+    const name = body.name?.trim() || "Default API Key";
 
     let scopedPermissions: string[] | null = null;
-    if (Array.isArray(body?.permissions) && body.permissions.length > 0) {
+    if (body.permissions && body.permissions.length > 0) {
       const userPerms = getPermissions(user.role);
       const permSet = new Set<string>(userPerms);
-      const invalid = body.permissions.filter((p: string) => !permSet.has(p));
+      const invalid = body.permissions.filter((p) => !permSet.has(p));
       if (invalid.length > 0) {
         return reply.status(400).send({
           error: `Cannot scope key with permissions you don't have: ${invalid.join(", ")}`,
@@ -48,19 +51,19 @@ export async function apiKeyRoutes(app: FastifyInstance): Promise<void> {
     }
 
     let expiresAt: Date | null = null;
-    if (body?.expiresAt) {
-      const parsed = new Date(body.expiresAt);
-      if (Number.isNaN(parsed.getTime())) {
+    if (body.expiresAt) {
+      const parsedDate = new Date(body.expiresAt);
+      if (Number.isNaN(parsedDate.getTime())) {
         return reply
           .status(400)
           .send({ error: "Invalid expiresAt date", code: "VALIDATION_ERROR" });
       }
-      if (parsed <= new Date()) {
+      if (parsedDate <= new Date()) {
         return reply
           .status(400)
           .send({ error: "expiresAt must be in the future", code: "VALIDATION_ERROR" });
       }
-      expiresAt = parsed;
+      expiresAt = parsedDate;
     }
 
     // Generate a raw API key: "si_" prefix + 48 random bytes as hex