fix(api): gate every tool endpoint and stop ZIP streams failing quietly (#646)

Three defects from #645, all of which let the server report something
that was not true.

Tool access was enforced per route, so it drifted. createToolRoute calls
requireToolAccess and the factory tools were fine, but all 45
hand-written routes had to remember the same call and none of them did.
A role without tools:use could run image-to-pdf, svg-to-raster,
erase-object, favicon, qr-generate, upscale, sign-pdf and the rest. The
issue described this as affecting two routes; it was every one of them.

The check now lives in a single preHandler keyed off the tool the router
matched, so it covers sub-paths (/batch, /info, /preview, /analyze,
/inspect) and any route added later without that route opting in. Ids no
tool claims stay unresolved, which keeps an unknown or misfiled tool a
404 rather than telling an unauthorized caller which ids exist.

Resolution reads request.routeOptions.url, the pattern the app itself
registered, rather than parsing request.url a second time. find-my-way
decodes before matching, so an independent parse disagrees with the
router and the router wins: `/api/v1/tools/image/%66avicon` ran favicon
while the gate saw no tool at all. Absolute-form request targets slipped
it the same way. Taking the router's own answer removes the disagreement.

A ZIP stream that failed after the 200 headers were out called
reply.raw.end(). On a chunked response that is indistinguishable from
success, so a client kept an archive with no central directory believing
it whole. Worse, a source stream that errored had no listener: the
request hung until it timed out and the error surfaced as unhandled. A
poisoned-storage probe reproduced both. The socket is destroyed instead,
and every source stream is listened to. svg-to-raster additionally ran
its append loop past the hijack with no try/catch, where a throw leaves
Fastify logging and walking away with the socket neither ended nor
destroyed. pdf-to-image is fixed alongside the other two: it shipped in
#643 with the destroy half but not the listener, so it hung the same way.

A zero-byte upload was dropped during parsing. The client pairs results
with its own file list by index, so every later result shifted onto the
wrong file: one document's output was presented as another's, under
another's name, while the file that actually converted was marked "not
found in batch results". Empty parts now keep their slot and fail in
place with a reason.

Two tests in adversarial-extended.test.ts asserted the old zero-byte
behavior, including a comment that batch "silently skips zero-byte
parts". They now pin the replacement: still rejected, nothing processed,
but the caller is told which files were empty instead of being told it
sent none.

A guard walks the whole catalog and fails if any of the 241 tools answers
anything but 403 for a role without tools:use, so a tool cannot escape
the gate by being registered in a shape nobody thought to sample.

Fixes #645

tests/unit/api/tool-access-url.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Route resolution for the tool access gate (issue #645).
+ *
+ * The gate protects whatever tool this resolves, so getting it wrong either
+ * opens a tool up or 403s something that was never a tool run. It reads the
+ * matched route pattern rather than the raw URL on purpose: find-my-way
+ * decodes before matching, so a second parse of the raw string disagrees with
+ * the router and fails open on `/api/v1/tools/image/%66avicon`.
+ */
+import { apiToolPath, TOOLS, toolSection } from "@snapotter/shared";
+import { describe, expect, it } from "vitest";
+import { toolIdFromRoute } from "../../../apps/api/src/plugins/tool-access.js";
+
+const BATCH_PATTERN = "/api/v1/tools/:section/:toolId/batch";
+
+describe("toolIdFromRoute", () => {
+  it("resolves every tool in the catalog from its own registered path", () => {
+    const unresolved = TOOLS.filter(
+      (tool) => toolIdFromRoute(apiToolPath(tool.id)) !== tool.id,
+    ).map((tool) => tool.id);
+    expect(unresolved, `tools whose own path does not resolve: ${unresolved.join(", ")}`).toEqual(
+      [],
+    );
+  });
+
+  it.each(["batch", "info", "preview", "analyze", "inspect", "generate", "effects"])(
+    "resolves the /%s sub-path to its parent tool",
+    (suffix) => {
+      expect(toolIdFromRoute(`/api/v1/tools/image/resize/${suffix}`)).toBe("resize");
+    },
+  );
+
+  it("resolves the parametric batch route from the router's decoded params", () => {
+    expect(toolIdFromRoute(BATCH_PATTERN, { section: "image", toolId: "resize" })).toBe("resize");
+  });
+
+  it("returns null when the parametric route names an unknown tool", () => {
+    expect(toolIdFromRoute(BATCH_PATTERN, { section: "image", toolId: "nope" })).toBeNull();
+  });
+
+  it("returns null when the parametric route's section does not match the tool", () => {
+    expect(toolIdFromRoute(BATCH_PATTERN, { section: "video", toolId: "resize" })).toBeNull();
+  });
+
+  it("returns null when the parametric route has no params", () => {
+    expect(toolIdFromRoute(BATCH_PATTERN)).toBeNull();
+  });
+
+  it.each([
+    ["no matched route", undefined],
+    ["the catalog root", "/api/v1/tools/"],
+    ["a single-segment listing", "/api/v1/tools/popular"],
+    ["an unrelated route", "/api/v1/jobs/:jobId/progress"],
+    ["a path that merely looks similar", "/api/v1/toolsomething/image/resize"],
+  ])("returns null for %s", (_label, routeUrl) => {
+    expect(toolIdFromRoute(routeUrl)).toBeNull();
+  });
+
+  it("returns null for an unknown tool id so the route can still 404", () => {
+    expect(toolIdFromRoute("/api/v1/tools/image/not-a-real-tool")).toBeNull();
+  });
+
+  it("returns null when a real tool is registered under the wrong section", () => {
+    const image = TOOLS.find((t) => toolSection(t) === "image");
+    if (!image) throw new Error("no image-section tool in the catalog");
+    expect(toolIdFromRoute(`/api/v1/tools/video/${image.id}`)).toBeNull();
+  });
+});