@powerhousedao/switchboard 6.2.3-dev.5 → 6.2.3-dev.50

package/test/attachments/download-target.test.ts

@@ -9,15 +9,24 @@ import type {
   IAttachmentAccessService,
 } from "@powerhousedao/reactor-api";
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { AttachmentActorContext } from "../../src/attachments/auth.js";
 import { registerAttachmentRoutes } from "../../src/attachments/index.js";
 import { makeDownloadTargetHandler } from "../../src/attachments/routes.js";
+import { AttachmentUrlSigner } from "../../src/attachments/url-signer.js";
 
 const HASH = "a".repeat(64) as AttachmentHash;
 const REF = `attachment://v1:${HASH}`;
 const DOC_ID = "doc-1";
 const EXPIRES = "2026-07-23T00:00:00.000Z";
+const NOW_MS = Date.parse("2026-07-22T00:00:00.000Z");
+const SIGNER = new AttachmentUrlSigner("s".repeat(32), () => NOW_MS);
+
+function signedUrlParts(body: string) {
+  const target = JSON.parse(body) as { url: string; expiresAtUtc: string };
+  const url = new URL(target.url);
+  return { target, url, params: url.searchParams };
+}
 
 const ACTOR: AttachmentActorContext = {
   user: {
@@ -82,7 +91,13 @@ function makeAccess(result: AttachmentAccessResult): {
   spy: ReturnType<typeof vi.fn>;
 } {
   const spy = vi.fn().mockResolvedValue(result);
-  return { access: { canReadAttachment: spy }, spy };
+  return {
+    access: {
+      canReadAttachment: spy,
+      admitCaller: () => Promise.resolve({ kind: "admitted" }),
+    },
+    spy,
+  };
 }
 
 function makeAttachments(opts: {
@@ -106,27 +121,118 @@ const ALLOWED: AttachmentAccessResult = {
 };
 
 describe("makeDownloadTargetHandler", () => {
-  it("returns a switchboard target for filesystem with no-store", async () => {
+  it("returns a signed switchboard target for filesystem with no-store", async () => {
     const { access, spy } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
 
     expect(res.statusCode).toBe(200);
     expect(res._headers["cache-control"]).toBe("no-store");
-    expect(JSON.parse(res._body)).toEqual({
+    const { target, url, params } = signedUrlParts(res._body);
+    expect(target).toMatchObject({
       kind: "switchboard",
       method: "GET",
-      url: `http://sb.example.com/attachments/${HASH}`,
       headers: {},
+      expiresAtUtc: new Date(NOW_MS + 300_000).toISOString(),
     });
+    expect(`${url.origin}${url.pathname}`).toBe(
+      `http://sb.example.com/attachments/${HASH}`,
+    );
+    expect(params.get("documentId")).toBe(DOC_ID);
+    expect(
+      SIGNER.verify(
+        HASH,
+        DOC_ID,
+        params.get("expires")!,
+        params.get("signature")!,
+      ),
+    ).toBe(true);
     expect(spy).toHaveBeenCalledWith({
       documentId: DOC_ID,
       attachmentRef: REF,
       userAddress: "0xverified",
+      appKey: "did:key:zAppTest",
+    });
+  });
+
+  it("signs for the requested expiresIn, clamped to the download-target ceiling", async () => {
+    const { access } = makeAccess(ALLOWED);
+    const handler = makeDownloadTargetHandler(
+      makeAttachments({}),
+      access,
+      SIGNER,
+    );
+
+    for (const [requested, granted] of [
+      [60, 60],
+      [3600, 300],
+      [99999999, 300],
+    ]) {
+      const res = makeRes();
+      await handler(
+        makeReq({
+          url: `/attachments/${HASH}/download-target?documentId=${DOC_ID}&expiresIn=${requested}`,
+        }),
+        res,
+        undefined,
+        ACTOR,
+      );
+      expect(signedUrlParts(res._body).target.expiresAtUtc).toBe(
+        new Date(NOW_MS + granted * 1000).toISOString(),
+      );
+    }
+  });
+
+  it("signs the canonical document id the access decision resolved", async () => {
+    const { access } = makeAccess({ ...ALLOWED, documentId: "canon" as never });
+    const handler = makeDownloadTargetHandler(
+      makeAttachments({}),
+      access,
+      SIGNER,
+    );
+    const res = makeRes();
+
+    await handler(makeReq({}), res, undefined, ACTOR);
+
+    expect(signedUrlParts(res._body).params.get("documentId")).toBe("canon");
+  });
+
+  it("fails closed with 503 on filesystem when no signer is configured", async () => {
+    const { access } = makeAccess(ALLOWED);
+    const handler = makeDownloadTargetHandler(
+      makeAttachments({}),
+      access,
+      null,
+    );
+    const res = makeRes();
+
+    await handler(makeReq({}), res, undefined, ACTOR);
+
+    expect(res.statusCode).toBe(503);
+    expect(res._body).not.toContain("/attachments/");
+  });
+
+  it("needs no signer for S3 presigned targets", async () => {
+    const { access } = makeAccess(ALLOWED);
+    const prepareDownloadTarget = vi.fn().mockResolvedValue({
+      kind: "presigned-get",
+      method: "GET",
+      url: "https://bucket.example.com/attachments/aa?sig=1",
+      headers: {},
+      expiresAtUtc: EXPIRES,
+    });
+    const attachments = makeAttachments({
+      backend: { kind: "s3", prepareDownloadTarget } as never,
     });
+    const handler = makeDownloadTargetHandler(attachments, access, null);
+    const res = makeRes();
+
+    await handler(makeReq({}), res, undefined, ACTOR);
+
+    expect(res.statusCode).toBe(200);
   });
 
   it("returns the backend presigned-get target in S3 mode", async () => {
@@ -141,14 +247,14 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       backend: { kind: "s3", prepareDownloadTarget } as never,
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
 
     expect(res.statusCode).toBe(200);
     expect(JSON.parse(res._body)).toMatchObject({ kind: "presigned-get" });
-    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, undefined);
+    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, 300);
   });
 
   it("passes a requested expiresIn through to the backend presigner", async () => {
@@ -163,12 +269,12 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       backend: { kind: "s3", prepareDownloadTarget } as never,
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(
       makeReq({
-        url: `/attachments/${HASH}/download-target?documentId=${DOC_ID}&expiresIn=3600`,
+        url: `/attachments/${HASH}/download-target?documentId=${DOC_ID}&expiresIn=60`,
       }),
       res,
       undefined,
@@ -176,10 +282,10 @@ describe("makeDownloadTargetHandler", () => {
     );
 
     expect(res.statusCode).toBe(200);
-    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, 3600);
+    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, 60);
   });
 
-  it("clamps expiresIn to the 7-day presigning ceiling", async () => {
+  it("clamps a requested expiresIn to the ceiling", async () => {
     const { access } = makeAccess(ALLOWED);
     const prepareDownloadTarget = vi.fn().mockResolvedValue({
       kind: "presigned-get",
@@ -191,7 +297,7 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       backend: { kind: "s3", prepareDownloadTarget } as never,
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(
@@ -203,10 +309,10 @@ describe("makeDownloadTargetHandler", () => {
       ACTOR,
     );
 
-    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, 604800);
+    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, 300);
   });
 
-  it("omits the TTL override when expiresIn is absent", async () => {
+  it("applies the ceiling when expiresIn is absent, rather than the backend default", async () => {
     const { access } = makeAccess(ALLOWED);
     const prepareDownloadTarget = vi.fn().mockResolvedValue({
       kind: "presigned-get",
@@ -218,11 +324,73 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       backend: { kind: "s3", prepareDownloadTarget } as never,
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
 
     await handler(makeReq({}), makeRes(), undefined, ACTOR);
 
-    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, undefined);
+    expect(prepareDownloadTarget).toHaveBeenCalledWith(HASH, 300);
+  });
+
+  describe("ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS", () => {
+    const ORIGINAL = process.env.ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS;
+
+    afterEach(() => {
+      if (ORIGINAL === undefined) {
+        delete process.env.ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS;
+      } else {
+        process.env.ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS = ORIGINAL;
+      }
+    });
+
+    async function ttlFor(configured: string | undefined, query = "") {
+      if (configured === undefined) {
+        delete process.env.ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS;
+      } else {
+        process.env.ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS = configured;
+      }
+      const { access } = makeAccess(ALLOWED);
+      const prepareDownloadTarget = vi.fn().mockResolvedValue({
+        kind: "presigned-get",
+        method: "GET",
+        url: "https://bucket.example.com/attachments/aa?sig=1",
+        headers: {},
+        expiresAtUtc: EXPIRES,
+      });
+      const attachments = makeAttachments({
+        backend: { kind: "s3", prepareDownloadTarget } as never,
+      });
+      const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
+      await handler(
+        makeReq({
+          url: `/attachments/${HASH}/download-target?documentId=${DOC_ID}${query}`,
+        }),
+        makeRes(),
+        undefined,
+        ACTOR,
+      );
+      return (prepareDownloadTarget.mock.calls[0] as unknown[])[1];
+    }
+
+    it("raises the ceiling when a deployment configures one", async () => {
+      await expect(ttlFor("1800")).resolves.toBe(1800);
+    });
+
+    it("never lets a configured ceiling exceed the signing maximum", async () => {
+      await expect(ttlFor("99999999")).resolves.toBe(604800);
+    });
+
+    it.each(["not-a-number", "0", "-5", "12.5"])(
+      "falls back to the default, not the maximum, on %s",
+      async (configured) => {
+        // A typo must narrow nothing and widen nothing: falling back to the
+        // signing ceiling would turn a misconfiguration into a week-long URL.
+        await expect(ttlFor(configured)).resolves.toBe(300);
+      },
+    );
+
+    it("still clamps a caller's request to the configured ceiling", async () => {
+      await expect(ttlFor("1800", "&expiresIn=99999")).resolves.toBe(1800);
+    });
   });
 
   it.each([
@@ -234,7 +402,7 @@ describe("makeDownloadTargetHandler", () => {
   ])("rejects a %s expiresIn with 400 before authorization", async (_, qs) => {
     const { access, spy } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(
@@ -253,7 +421,7 @@ describe("makeDownloadTargetHandler", () => {
   it("normalizes an uppercase path hash before authorization and lookup", async () => {
     const { access, spy } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({ hash: HASH.toUpperCase() }), res, undefined, ACTOR);
@@ -268,7 +436,7 @@ describe("makeDownloadTargetHandler", () => {
   it("rejects an invalid hash before any access or storage call", async () => {
     const { access, spy } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({ hash: "nothex" }), res, undefined, ACTOR);
@@ -292,7 +460,7 @@ describe("makeDownloadTargetHandler", () => {
   ])("rejects a %s documentId before authorization", async (_, url) => {
     const { access, spy } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({ url }), res, undefined, ACTOR);
@@ -307,7 +475,7 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       backend: { kind: "s3", prepareDownloadTarget } as never,
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
@@ -321,7 +489,7 @@ describe("makeDownloadTargetHandler", () => {
   it("maps projection-unavailable to a generic non-cacheable 503 before storage", async () => {
     const { access } = makeAccess({ kind: "projection-unavailable" });
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
@@ -337,7 +505,7 @@ describe("makeDownloadTargetHandler", () => {
     const { AttachmentNotFound } =
       await import("@powerhousedao/reactor-attachments");
     attachments.statSpy.mockRejectedValue(new AttachmentNotFound(HASH));
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
@@ -351,7 +519,7 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       stat: () => Promise.resolve({ ...AVAILABLE_HEADER, status: "pending" }),
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
@@ -371,7 +539,7 @@ describe("makeDownloadTargetHandler", () => {
     const attachments = makeAttachments({
       backend: { kind: "s3", prepareDownloadTarget } as never,
     });
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, ACTOR);
@@ -384,7 +552,7 @@ describe("makeDownloadTargetHandler", () => {
   it("passes an anonymous actor as an undefined address (OPEN mode)", async () => {
     const { access, spy } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(makeReq({}), res, undefined, {
@@ -400,7 +568,7 @@ describe("makeDownloadTargetHandler", () => {
   it("honours x-forwarded proto/host when building the switchboard target", async () => {
     const { access } = makeAccess(ALLOWED);
     const attachments = makeAttachments({});
-    const handler = makeDownloadTargetHandler(attachments, access);
+    const handler = makeDownloadTargetHandler(attachments, access, SIGNER);
     const res = makeRes();
 
     await handler(
@@ -415,9 +583,10 @@ describe("makeDownloadTargetHandler", () => {
       ACTOR,
     );
 
-    expect(JSON.parse(res._body)).toMatchObject({
-      url: `https://public.example.com/attachments/${HASH}`,
-    });
+    const { url } = signedUrlParts(res._body);
+    expect(`${url.origin}${url.pathname}`).toBe(
+      `https://public.example.com/attachments/${HASH}`,
+    );
   });
 });
 
@@ -435,7 +604,7 @@ describe("registerAttachmentRoutes inventory", () => {
       attachmentAccess: { canReadAttachment: vi.fn() },
     } as unknown as API;
 
-    registerAttachmentRoutes(api);
+    registerAttachmentRoutes(api, { urlSigner: null });
 
     expect(captured).toEqual([
       { method: "POST", path: "/attachments/reservations" },

package/test/attachments/index.test.ts

@@ -13,8 +13,16 @@ type Captured = {
   ) => void | Promise<void>;
 };
 
-function makeFakeApi(authService: AuthService | undefined): {
-  api: Pick<API, "httpAdapter" | "authService">;
+type FakeApi = Pick<
+  API,
+  "httpAdapter" | "authService" | "requireAuthenticatedCaller"
+>;
+
+function makeFakeApi(
+  authService: AuthService | undefined,
+  requireAuthenticatedCaller = false,
+): {
+  api: FakeApi;
   captured: Captured[];
 } {
   const captured: Captured[] = [];
@@ -29,7 +37,8 @@ function makeFakeApi(authService: AuthService | undefined): {
       },
     },
     authService,
-  } as unknown as Pick<API, "httpAdapter" | "authService">;
+    requireAuthenticatedCaller,
+  } as unknown as FakeApi;
   return { api, captured };
 }
 
@@ -138,6 +147,28 @@ describe("mountAuthenticatedNodeRoute", () => {
     });
   });
 
+  it("carries the deployment's authenticated-caller floor onto the route, over allowAnonymous", async () => {
+    // auth_enabled false is the shape a deployment running the document
+    // policies has: the boundary policy is OPEN, and this floor is what keeps
+    // an anonymous caller off the attachment routes.
+    const verifyBearer = vi.fn(() =>
+      Promise.resolve({ user: undefined, admins: [], auth_enabled: false }),
+    );
+    const authService = { verifyBearer } as unknown as AuthService;
+    const { api, captured } = makeFakeApi(authService, true);
+    const inner = vi.fn();
+
+    mountAuthenticatedNodeRoute(api, "GET", "/x", inner, {
+      allowAnonymous: true,
+    });
+
+    const res = makeRes();
+    await captured[0].handler(makeReq(), res);
+
+    expect(res.statusCode).toBe(401);
+    expect(inner).not.toHaveBeenCalled();
+  });
+
   it("mounts a wrapper that forwards the anonymous actor when authService is undefined", async () => {
     const { api, captured } = makeFakeApi(undefined);
     const inner = vi.fn();

package/test/attachments/reserve-metadata-parity.test.ts

@@ -0,0 +1,96 @@
+import {
+  InvalidAttachmentMetadata,
+  validateReserveMetadata,
+  type ReserveMetadata,
+} from "@powerhousedao/reactor-attachments";
+import { describe, expect, it } from "vitest";
+import { parseReserveOptions } from "../../src/attachments/routes.js";
+
+type Case = [name: string, meta: Record<string, unknown>];
+
+const base = { mimeType: "text/plain", fileName: "note.txt" };
+
+// The download route's setHeader throws on each of these.
+const headerBreaking: Case[] = [
+  ["CRLF before a parameter", { ...base, mimeType: "text/plain\r\n;a=b" }],
+  ["LF after a ;", { ...base, mimeType: "text/plain;\na=b" }],
+  ["a control char quoted", { ...base, mimeType: 'text/plain; a="\x01"' }],
+  ["a DEL quoted", { ...base, mimeType: 'text/plain; a="\x7f"' }],
+  ["a char above 0xFF quoted", { ...base, mimeType: 'text/plain;a="\u0100"' }],
+];
+
+const cases: Case[] = [
+  ["plain metadata", base],
+  ["an extension", { ...base, extension: "txt" }],
+  ["a null extension", { ...base, extension: null }],
+  ["a parameter", { ...base, mimeType: "text/plain; charset=utf-8" }],
+  ["a quoted parameter", { ...base, mimeType: 'text/plain; a="b c"' }],
+  ["a unicode file name", { ...base, fileName: "résumé.pdf" }],
+  ["a 255-char mimeType", { ...base, mimeType: `a/${"b".repeat(253)}` }],
+  ["a 256-char mimeType", { ...base, mimeType: `a/${"b".repeat(254)}` }],
+  ["a 255-char fileName", { ...base, fileName: "f".repeat(255) }],
+  ["a 256-char fileName", { ...base, fileName: "f".repeat(256) }],
+  ["an empty mimeType", { ...base, mimeType: "" }],
+  ["an empty fileName", { ...base, fileName: "" }],
+  ["an empty extension", { ...base, extension: "" }],
+  ["a mimeType with no slash", { ...base, mimeType: "text" }],
+  ["a mimeType with no subtype", { ...base, mimeType: "text/" }],
+  ["a mimeType with no type", { ...base, mimeType: "/plain" }],
+  ["a mimeType with two slashes", { ...base, mimeType: "text/plain/x" }],
+  ["a mimeType with a space", { ...base, mimeType: "text plain" }],
+  ["a mimeType with a dangling ;", { ...base, mimeType: "text/plain;" }],
+  ["a non-string mimeType", { ...base, mimeType: 5 }],
+  ["a trailing CRLF in mimeType", { ...base, mimeType: "text/plain\r\n" }],
+  [
+    "an injected header in mimeType",
+    { ...base, mimeType: "text/plain\nX-Injected: 1" },
+  ],
+  ["a NUL in mimeType", { ...base, mimeType: "text/pl\x00ain" }],
+  ...headerBreaking,
+  ["a NUL in fileName", { ...base, fileName: "a\x00b" }],
+  ["a LF in fileName", { ...base, fileName: "a\nb" }],
+  ["a CR in fileName", { ...base, fileName: "a\rb" }],
+  ["a tab in fileName", { ...base, fileName: "a\tb" }],
+  ["a DEL in fileName", { ...base, fileName: "a\x7fb" }],
+  ["a non-string fileName", { ...base, fileName: null }],
+  ["a slash in extension", { ...base, extension: "a/b" }],
+  ["a backslash in extension", { ...base, extension: "a\\b" }],
+  ["a bare slash extension", { ...base, extension: "/" }],
+  ["a non-string extension", { ...base, extension: 5 }],
+];
+
+function routeAccepts(meta: Record<string, unknown>): boolean {
+  return parseReserveOptions(meta) !== null;
+}
+
+function validatorAccepts(meta: Record<string, unknown>): boolean {
+  try {
+    validateReserveMetadata(meta as ReserveMetadata);
+    return true;
+  } catch (err) {
+    if (err instanceof InvalidAttachmentMetadata) return false;
+    throw err;
+  }
+}
+
+describe("reserve metadata parity between the route and validateReserveMetadata", () => {
+  it("covers both accepted and rejected metadata", () => {
+    const verdicts = cases.map(([, meta]) => routeAccepts(meta));
+    expect(verdicts).toContain(true);
+    expect(verdicts).toContain(false);
+  });
+
+  it.each(cases)("agrees on %s", (_name, meta) => {
+    expect(validatorAccepts(meta)).toBe(routeAccepts(meta));
+  });
+});
+
+describe("header-breaking mimeType values", () => {
+  it.each(headerBreaking)("the route rejects %s", (_name, meta) => {
+    expect(routeAccepts(meta)).toBe(false);
+  });
+
+  it.each(headerBreaking)("the validator rejects %s", (_name, meta) => {
+    expect(validatorAccepts(meta)).toBe(false);
+  });
+});

package/test/attachments/routes-integration.test.ts

@@ -1,11 +1,12 @@
 import { PGlite } from "@electric-sql/pglite";
 import {
+  AttachmentAlreadyExists,
   AttachmentBuilder,
   S3AttachmentBackend,
   type AttachmentBuildResult,
   createRemoteAttachmentService,
 } from "@powerhousedao/reactor-attachments";
-import type { API } from "@powerhousedao/reactor-api";
+import type { API, IAttachmentAccessService } from "@powerhousedao/reactor-api";
 import { createHttpAdapter } from "@powerhousedao/reactor-api";
 import { Kysely } from "kysely";
 import { PGliteDialect } from "kysely-pglite-dialect";
@@ -22,6 +23,17 @@ import { registerAttachmentRoutes } from "../../src/attachments/index.js";
 const EMPTY_STRING_SHA256 =
   "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 
+const DOC_ID = "doc-1";
+const ALLOW_ALL: IAttachmentAccessService = {
+  canReadAttachment: (request) =>
+    Promise.resolve({
+      kind: "allowed",
+      documentId: request.documentId as never,
+      ref: request.attachmentRef as never,
+    }),
+  admitCaller: () => Promise.resolve({ kind: "admitted" }),
+};
+
 describe("attachment routes through the real Express middleware stack", () => {
   let attachments: AttachmentBuildResult;
   let kysely: Kysely<unknown>;
@@ -42,10 +54,11 @@ describe("attachment routes through the real Express middleware stack", () => {
     registerAttachmentRoutes({
       httpAdapter: adapter,
       attachments,
+      attachmentAccess: ALLOW_ALL,
       authService: undefined,
     } as unknown as API);
 
-    server = await adapter.listen(0);
+    server = await adapter.listen(0, undefined, "127.0.0.1");
     const addr = server.address();
     if (!addr || typeof addr === "string") throw new Error("no addr");
     baseUrl = `http://127.0.0.1:${addr.port}`;
@@ -82,7 +95,7 @@ describe("attachment routes through the real Express middleware stack", () => {
     expect(result.hash).not.toBe(EMPTY_STRING_SHA256);
     expect(result.header.sizeBytes).toBe(bytes.byteLength);
 
-    const got = await service.get(result.ref);
+    const got = await service.get(result.ref, { documentId: DOC_ID });
     expect(got.header.sizeBytes).toBe(bytes.byteLength);
     expect(got.header.mimeType).toBe("application/json");
     const reader = got.body.getReader();
@@ -101,6 +114,48 @@ describe("attachment routes through the real Express middleware stack", () => {
     }
     expect(new TextDecoder().decode(merged)).toBe(payload);
   });
+
+  it("HEAD and GET /attachments/:hash serve a file name above U+00FF", async () => {
+    const fileName = "opłata – 報告 📎.pdf";
+    const service = createRemoteAttachmentService({ remoteUrl: baseUrl });
+    const upload = await service.reserve({
+      mimeType: "application/pdf",
+      fileName,
+    });
+    const bytes = new TextEncoder().encode("%PDF-unicode-name");
+    const { hash } = await upload.send(
+      new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      }),
+    );
+
+    for (const method of ["HEAD", "GET"]) {
+      const res = await fetch(
+        `${baseUrl}/attachments/${hash}?documentId=${DOC_ID}`,
+        { method },
+      );
+      expect(res.status).toBe(200);
+      const meta = JSON.parse(res.headers.get("attachment-metadata")!) as {
+        fileName: string;
+      };
+      expect(meta.fileName).toBe(fileName);
+      await res.arrayBuffer();
+    }
+
+    // A hash-first reserve of the same bytes is what the client sends on the
+    // next upload; it stats the hash first.
+    await expect(
+      service.reserve({
+        mimeType: "application/pdf",
+        fileName,
+        clientHash: hash,
+        sizeBytes: bytes.byteLength,
+      }),
+    ).rejects.toBeInstanceOf(AttachmentAlreadyExists);
+  });
 });
 
 describe("authenticated S3 reservation production path", () => {
@@ -138,9 +193,10 @@ describe("authenticated S3 reservation production path", () => {
     registerAttachmentRoutes({
       httpAdapter: adapter,
       attachments,
+      attachmentAccess: ALLOW_ALL,
       authService: { verifyBearer },
     } as unknown as API);
-    const server = await adapter.listen(0);
+    const server = await adapter.listen(0, undefined, "127.0.0.1");
     const address = server.address();
     if (!address || typeof address === "string") throw new Error("no addr");
     const baseUrl = `http://127.0.0.1:${address.port}`;