fix: first-run QA sweep of the single-container image (#413)

Fixes found by manually testing a fresh install end to end:

- auth: the must-change-password gate returned 403 on public routes
  including /api/v1/health, so every fresh install showed a false
  "Reconnecting to server" banner on the forced password change
  screen. Public routes are now exempt (they need no session at all).
  Adds the gate's first direct tests.
- multipart: @fastify/multipart's parts() iterator (9.4.0 and 10.0.0)
  ends on the request stream's "close", which on a reused keep-alive
  connection fires while an earlier part is still streaming to storage,
  silently dropping the parts behind it. The object eraser lost its
  mask file on every second POST per connection. Replaced with a
  busboy-driven iterator (lib/multipart-parts.ts) that ends on busboy's
  own "finish", installed for all routes via a preValidation hook;
  the tool-factory field-recovery workaround for the same bug is now
  unnecessary and removed.
- eraser: the mask canvas backing store is natural resolution, but
  "absolute inset-0" does not stretch replaced elements, so the
  canvas rendered at intrinsic size and the brush ring, strokes, and
  exported mask were all misscaled on photos larger than the viewport.
  The canvas now gets an explicit CSS box at the fitted size.
- compare slider: solid white divider with a dark halo so it stays
  visible over light images; still initialised at the painted region.
- tool page: the AI bundle install prompt now centers in the content
  area instead of hugging the top.
- api docs: disabled Scalar's cloud features (Ask AI, Generate MCP,
  Open API Client, dev toolbar), hid the "Powered by Scalar" footer
  link, and set the page title to "SnapOtter API Reference". The docs
  CSP blocks those cloud calls by design, so the buttons were dead UI.
- docker: embedded Redis comes from packages.redis.io pinned to the
  8.x major (was Debian's 7.0.15), matching the Compose stack and the
  documented claim. Build fails fast if the major ever drifts.
- docs: DOCKERHUB.md quick start now leads with the one-command docker
  run (matching the README) with Compose as the production path;
  README says embedded Postgres 17 + Redis 8.

Claude-Session: https://claude.ai/code/session_01XGB4pGvTvb7sUX4JN745U7

tests/integration/platform/auth-edge-cases.test.ts

@@ -450,3 +450,64 @@ describe("Register validation", () => {
     expect(res.statusCode).toBe(404);
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FORCED PASSWORD CHANGE GATE
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Forced password change gate", () => {
+  // The register route leaves mustChangePassword=true; log straight in
+  // without clearing it so the gate is active for the session.
+  async function loginWithMustChange(): Promise<{ password: string; token: string }> {
+    const username = uid();
+    const password = "ValidPass1";
+    const res = await testApp.app.inject({
+      method: "POST",
+      url: "/api/auth/register",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { username, password, role: "admin" },
+    });
+    if (res.statusCode !== 201) {
+      throw new Error(`register failed: ${res.statusCode} ${res.body}`);
+    }
+    return { password, token: await loginAs(username, password) };
+  }
+
+  it("keeps public endpoints reachable while the flag is set", async () => {
+    const { token } = await loginWithMustChange();
+    // Regression: /api/v1/health returned 403 here, tripping the SPA's
+    // "Reconnecting to server" banner on the forced change-password screen.
+    const health = await testApp.app.inject({
+      method: "GET",
+      url: "/api/v1/health",
+      headers: { authorization: `Bearer ${token}` },
+    });
+    expect(health.statusCode).toBe(200);
+  });
+
+  it("blocks protected endpoints until the password is changed", async () => {
+    const { password, token } = await loginWithMustChange();
+
+    const blocked = await testApp.app.inject({
+      method: "GET",
+      url: "/api/v1/api-keys",
+      headers: { authorization: `Bearer ${token}` },
+    });
+    expect(blocked.statusCode).toBe(403);
+    expect(JSON.parse(blocked.body).code).toBe("MUST_CHANGE_PASSWORD");
+
+    const change = await testApp.app.inject({
+      method: "POST",
+      url: "/api/auth/change-password",
+      headers: { authorization: `Bearer ${token}` },
+      payload: { currentPassword: password, newPassword: "RotatedPass1" },
+    });
+    expect(change.statusCode).toBe(200);
+
+    const after = await testApp.app.inject({
+      method: "GET",
+      url: "/api/v1/api-keys",
+      headers: { authorization: `Bearer ${token}` },
+    });
+    expect(after.statusCode).toBe(200);
+  });
+});

tests/integration/tools/image/erase-object-mask.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Integration tests for the erase-object multipart contract
+ * (/api/v1/tools/image/erase-object).
+ *
+ * Every AI-matrix test stops at the 501 FEATURE_NOT_INSTALLED guard, so the
+ * file+mask parse path behind it had no coverage. These tests mock the
+ * install gate open and replay the exact multipart shape the web client
+ * sends. The AI sidecar is not running in tests, so a successful parse
+ * yields 202 (job enqueued); any 4xx means the request was misparsed.
+ */
+
+import { randomUUID } from "node:crypto";
+import { Agent as HttpAgent, request as httpRequest } from "node:http";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { fixtures, readFixture } from "../../../fixtures/index.js";
+import {
+  buildTestApp,
+  createMultipartPayload,
+  loginAsAdmin,
+  type TestApp,
+} from "../../test-server.js";
+
+vi.mock("../../../../apps/api/src/lib/feature-status.js", async (importOriginal) => {
+  const mod =
+    await importOriginal<typeof import("../../../../apps/api/src/lib/feature-status.js")>();
+  return { ...mod, isToolInstalled: () => true };
+});
+
+const JPG = readFixture(fixtures.image.base.jpg100);
+const PNG = readFixture(fixtures.image.base.png200);
+// Large first file: widens the window in which the request stream fully
+// buffers (firing "close") while the first part is still streaming to
+// storage, which is what dropped the trailing mask part.
+const LARGE_JPG = readFixture(fixtures.image.stressLarge);
+
+let testApp: TestApp;
+let app: TestApp["app"];
+let adminToken: string;
+
+beforeAll(async () => {
+  testApp = await buildTestApp();
+  app = testApp.app;
+  adminToken = await loginAsAdmin(app);
+}, 30_000);
+
+afterAll(async () => {
+  await testApp.cleanup();
+}, 10_000);
+
+describe("erase-object multipart contract", () => {
+  it("accepts the web client's file + mask + fields shape", async () => {
+    const { body, contentType } = createMultipartPayload([
+      { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: JPG },
+      { name: "mask", filename: "mask.png", contentType: "image/png", content: PNG },
+      { name: "clientJobId", content: randomUUID() },
+      { name: "format", content: "png" },
+      { name: "quality", content: "95" },
+    ]);
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image/erase-object",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      payload: body,
+    });
+    expect(res.statusCode, res.body).toBeLessThan(400);
+  });
+
+  it("keeps trailing parts across reused keep-alive connections", async () => {
+    // Regression for the @fastify/multipart parts() race: its iterator ends
+    // on the REQUEST stream's "close", which on a warm keep-alive connection
+    // fires while the first file is still streaming to storage, dropping the
+    // trailing mask part. inject() cannot reproduce it (no real socket), so
+    // this test runs real sequential HTTP posts over one connection. Before
+    // the busboy-driven iterator fix, the second post reliably 400'd with
+    // "No mask image provided".
+    await app.listen({ port: 0, host: "127.0.0.1" });
+    const address = app.server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    const agent = new HttpAgent({ keepAlive: true, maxSockets: 1 });
+
+    const post = (): Promise<{ status: number; body: string }> =>
+      new Promise((resolve, reject) => {
+        const { body, contentType } = createMultipartPayload([
+          { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: LARGE_JPG },
+          { name: "mask", filename: "mask.png", contentType: "image/png", content: PNG },
+          { name: "clientJobId", content: randomUUID() },
+          { name: "format", content: "png" },
+          { name: "quality", content: "95" },
+        ]);
+        const req = httpRequest(
+          {
+            host: "127.0.0.1",
+            port,
+            path: "/api/v1/tools/image/erase-object",
+            method: "POST",
+            agent,
+            headers: {
+              authorization: `Bearer ${adminToken}`,
+              "content-type": contentType,
+              "content-length": body.length,
+            },
+          },
+          (res) => {
+            let text = "";
+            res.on("data", (chunk) => {
+              text += chunk;
+            });
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, body: text }));
+          },
+        );
+        req.on("error", reject);
+        req.end(body);
+      });
+
+    try {
+      const results = [await post(), await post(), await post()];
+      for (const [i, r] of results.entries()) {
+        expect(r.status, `request ${i + 1} of 3: ${r.body}`).toBeLessThan(400);
+      }
+    } finally {
+      agent.destroy();
+    }
+  }, 30_000);
+});

tests/unit/api/multipart-parts.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Unit tests for lib/multipart-parts.ts, the keep-alive-safe replacement for
+ * @fastify/multipart's request.parts().
+ *
+ * The scenario that broke the plugin: the whole request body is already
+ * buffered (request "end"/"close" fire immediately once piped) while the
+ * consumer awaits slow storage writes between parts. The plugin's iterator
+ * queued its end marker on request "close" and dropped every part emitted
+ * after it; the busboy-driven iterator must deliver all parts regardless of
+ * consumer pacing.
+ */
+
+import { PassThrough } from "node:stream";
+import type { FastifyRequest } from "fastify";
+import { describe, expect, it } from "vitest";
+import { multipartParts } from "../../../apps/api/src/lib/multipart-parts.js";
+
+const BOUNDARY = "----UnitBoundary1234";
+
+function multipartBody(
+  parts: Array<{ name: string; filename?: string; content: string | Buffer }>,
+): Buffer {
+  const chunks: Buffer[] = [];
+  for (const part of parts) {
+    let header = `--${BOUNDARY}\r\n`;
+    if (part.filename) {
+      header += `Content-Disposition: form-data; name="${part.name}"; filename="${part.filename}"\r\n`;
+      header += "Content-Type: application/octet-stream\r\n\r\n";
+    } else {
+      header += `Content-Disposition: form-data; name="${part.name}"\r\n\r\n`;
+    }
+    chunks.push(Buffer.from(header), Buffer.from(part.content), Buffer.from("\r\n"));
+  }
+  chunks.push(Buffer.from(`--${BOUNDARY}--\r\n`));
+  return Buffer.concat(chunks);
+}
+
+/** Fake request whose raw stream has the whole body buffered up front. */
+function fakeRequest(body: Buffer): FastifyRequest {
+  const raw = new PassThrough();
+  Object.assign(raw, {
+    headers: { "content-type": `multipart/form-data; boundary=${BOUNDARY}` },
+  });
+  // Whole body available immediately: "end"/"close" fire as soon as the
+  // pipe drains the stream, exactly like a warm keep-alive socket.
+  raw.end(body);
+  return { raw } as unknown as FastifyRequest;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function drain(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks);
+}
+
+describe("multipartParts", () => {
+  it("yields every part when the consumer is slower than the body arrival", async () => {
+    const body = multipartBody([
+      { name: "file", filename: "photo.jpg", content: Buffer.alloc(256 * 1024, 7) },
+      { name: "mask", filename: "mask.png", content: Buffer.alloc(8 * 1024, 9) },
+      { name: "clientJobId", content: "abc-123" },
+      { name: "format", content: "png" },
+      { name: "quality", content: "95" },
+    ]);
+
+    const seen: string[] = [];
+    const sizes: Record<string, number> = {};
+    for await (const part of multipartParts(fakeRequest(body))) {
+      if (part.type === "file") {
+        const buf = await drain(part.file);
+        sizes[part.fieldname] = buf.length;
+        seen.push(`file:${part.fieldname}`);
+        // Slow consumer: the raw stream has long since closed by now.
+        await sleep(25);
+      } else {
+        seen.push(`field:${part.fieldname}=${part.value}`);
+      }
+    }
+
+    expect(seen).toEqual([
+      "file:file",
+      "file:mask",
+      "field:clientJobId=abc-123",
+      "field:format=png",
+      "field:quality=95",
+    ]);
+    expect(sizes.file).toBe(256 * 1024);
+    expect(sizes.mask).toBe(8 * 1024);
+  });
+
+  it("propagates malformed multipart as an error", async () => {
+    const raw = new PassThrough();
+    Object.assign(raw, {
+      headers: { "content-type": `multipart/form-data; boundary=${BOUNDARY}` },
+    });
+    raw.end(Buffer.from("this is not multipart at all"));
+    const request = { raw } as unknown as FastifyRequest;
+
+    await expect(async () => {
+      for await (const part of multipartParts(request)) {
+        if (part.type === "file") await drain(part.file);
+      }
+    }).rejects.toThrow();
+  });
+});

tests/unit/api/static-upload.test.ts

@@ -118,7 +118,7 @@ describe("registerUpload", () => {
   it("registers multipart with correct file size limit", async () => {
     uploadConfig.MAX_UPLOAD_SIZE_MB = 10;
     uploadConfig.MAX_BATCH_SIZE = 5;
-    const app = { register: vi.fn().mockResolvedValue(undefined) };
+    const app = { register: vi.fn().mockResolvedValue(undefined), addHook: vi.fn() };
 
     await registerUpload(app as never);
     expect(app.register).toHaveBeenCalledWith(mockMultipartPlugin, {
@@ -132,7 +132,7 @@ describe("registerUpload", () => {
   it("passes undefined for fileSize when MAX_UPLOAD_SIZE_MB is 0", async () => {
     uploadConfig.MAX_UPLOAD_SIZE_MB = 0;
     uploadConfig.MAX_BATCH_SIZE = 5;
-    const app = { register: vi.fn().mockResolvedValue(undefined) };
+    const app = { register: vi.fn().mockResolvedValue(undefined), addHook: vi.fn() };
 
     await registerUpload(app as never);
     expect(app.register).toHaveBeenCalledWith(mockMultipartPlugin, {
@@ -146,7 +146,7 @@ describe("registerUpload", () => {
   it("passes undefined for files when MAX_BATCH_SIZE is 0", async () => {
     uploadConfig.MAX_UPLOAD_SIZE_MB = 10;
     uploadConfig.MAX_BATCH_SIZE = 0;
-    const app = { register: vi.fn().mockResolvedValue(undefined) };
+    const app = { register: vi.fn().mockResolvedValue(undefined), addHook: vi.fn() };
 
     await registerUpload(app as never);
     expect(app.register).toHaveBeenCalledWith(mockMultipartPlugin, {
@@ -160,7 +160,7 @@ describe("registerUpload", () => {
   it("passes undefined for both limits when both are 0", async () => {
     uploadConfig.MAX_UPLOAD_SIZE_MB = 0;
     uploadConfig.MAX_BATCH_SIZE = 0;
-    const app = { register: vi.fn().mockResolvedValue(undefined) };
+    const app = { register: vi.fn().mockResolvedValue(undefined), addHook: vi.fn() };
 
     await registerUpload(app as never);
     expect(app.register).toHaveBeenCalledWith(mockMultipartPlugin, {

tests/unit/api/tool-factory-route.test.ts

@@ -641,153 +641,4 @@ describe("createToolRoute", () => {
       );
     });
   });
-
-  describe("multipart field recovery", () => {
-    it("recovers settings from part.fields when the iterator drops trailing fields", async () => {
-      const app = createMockApp();
-      const id = "resize";
-      createToolRoute(app as never, makeMockConfig(id));
-      const handler = app.routes[apiToolPath(id)];
-      const reply = createMockReply();
-
-      // Simulate the @fastify/multipart race: the iterator yields only the
-      // file part; the settings field is present only on part.fields.
-      const req = {
-        parts: () => ({
-          [Symbol.asyncIterator]: async function* () {
-            yield {
-              type: "file",
-              filename: "test.png",
-              file: (async function* () {
-                yield Buffer.from("png-data");
-              })(),
-              fields: {
-                settings: { value: '{"x":1}' },
-              },
-            };
-          },
-        }),
-        headers: {},
-        log: { warn: vi.fn(), error: vi.fn(), info: vi.fn() },
-      };
-
-      await handler(req, reply);
-
-      // Settings must be recovered as {x:1}, not fall through to defaults ({})
-      const enqueueCall = vi.mocked(enqueueToolJob).mock.calls[0][0];
-      expect(enqueueCall.settings).toEqual({ x: 1 });
-      expect(reply.send).toHaveBeenCalledWith(
-        expect.objectContaining({ jobId: expect.any(String) }),
-      );
-    });
-
-    it("does not overwrite settings already collected from the iterator", async () => {
-      const app = createMockApp();
-      const id = "resize";
-      createToolRoute(app as never, makeMockConfig(id));
-      const handler = app.routes[apiToolPath(id)];
-      const reply = createMockReply();
-
-      // Both the iterator and part.fields carry settings; the iterator value wins
-      const req = {
-        parts: () => ({
-          [Symbol.asyncIterator]: async function* () {
-            yield {
-              type: "file",
-              filename: "test.png",
-              file: (async function* () {
-                yield Buffer.from("png-data");
-              })(),
-              fields: {
-                settings: { value: '{"from":"fields"}' },
-              },
-            };
-            yield {
-              type: "field",
-              fieldname: "settings",
-              value: '{"from":"iterator"}',
-              file: (async function* () {})(),
-              fields: {
-                settings: { value: '{"from":"fields"}' },
-              },
-            };
-          },
-        }),
-        headers: {},
-        log: { warn: vi.fn(), error: vi.fn(), info: vi.fn() },
-      };
-
-      await handler(req, reply);
-
-      const enqueueCall = vi.mocked(enqueueToolJob).mock.calls[0][0];
-      expect(enqueueCall.settings).toEqual({ from: "iterator" });
-    });
-
-    it("recovers fileId and clientJobId from part.fields", async () => {
-      const app = createMockApp();
-      const id = "resize";
-      createToolRoute(app as never, makeMockConfig(id));
-      const handler = app.routes[apiToolPath(id)];
-      const reply = createMockReply();
-
-      const req = {
-        parts: () => ({
-          [Symbol.asyncIterator]: async function* () {
-            yield {
-              type: "file",
-              filename: "test.png",
-              file: (async function* () {
-                yield Buffer.from("png-data");
-              })(),
-              fields: {
-                settings: { value: "{}" },
-                fileId: { value: "f-123" },
-                clientJobId: { value: "cj-456" },
-              },
-            };
-          },
-        }),
-        headers: {},
-        log: { warn: vi.fn(), error: vi.fn(), info: vi.fn() },
-      };
-
-      await handler(req, reply);
-
-      const enqueueCall = vi.mocked(enqueueToolJob).mock.calls[0][0];
-      expect(enqueueCall.fileId).toBe("f-123");
-      expect(enqueueCall.clientJobId).toBe("cj-456");
-    });
-
-    it("handles array-form fields from part.fields", async () => {
-      const app = createMockApp();
-      const id = "resize";
-      createToolRoute(app as never, makeMockConfig(id));
-      const handler = app.routes[apiToolPath(id)];
-      const reply = createMockReply();
-
-      const req = {
-        parts: () => ({
-          [Symbol.asyncIterator]: async function* () {
-            yield {
-              type: "file",
-              filename: "test.png",
-              file: (async function* () {
-                yield Buffer.from("png-data");
-              })(),
-              fields: {
-                settings: [{ value: '{"arr":true}' }],
-              },
-            };
-          },
-        }),
-        headers: {},
-        log: { warn: vi.fn(), error: vi.fn(), info: vi.fn() },
-      };
-
-      await handler(req, reply);
-
-      const enqueueCall = vi.mocked(enqueueToolJob).mock.calls[0][0];
-      expect(enqueueCall.settings).toEqual({ arr: true });
-    });
-  });
 });