@powerhousedao/switchboard 6.2.3-dev.25 → 6.2.3-dev.26

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

@@ -13,11 +13,20 @@ 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: {
@@ -106,22 +115,35 @@ 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,
@@ -130,6 +152,83 @@ describe("makeDownloadTargetHandler", () => {
     });
   });
 
+  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 () => {
     const { access } = makeAccess(ALLOWED);
     const prepareDownloadTarget = vi.fn().mockResolvedValue({
@@ -142,7 +241,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);
@@ -164,7 +263,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(
@@ -192,7 +291,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(
@@ -219,7 +318,7 @@ 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);
 
@@ -254,7 +353,7 @@ 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({
           url: `/attachments/${HASH}/download-target?documentId=${DOC_ID}${query}`,
@@ -297,7 +396,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(
@@ -316,7 +415,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);
@@ -331,7 +430,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);
@@ -355,7 +454,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);
@@ -370,7 +469,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 +483,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);
@@ -400,7 +499,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);
@@ -414,7 +513,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);
@@ -434,7 +533,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);
@@ -447,7 +546,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, {
@@ -463,7 +562,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(
@@ -478,9 +577,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}`,
+    );
   });
 });
 
@@ -498,7 +598,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/routes-integration.test.ts

@@ -6,7 +6,7 @@ import {
   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";
@@ -23,6 +23,16 @@ 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,
+    }),
+};
+
 describe("attachment routes through the real Express middleware stack", () => {
   let attachments: AttachmentBuildResult;
   let kysely: Kysely<unknown>;
@@ -43,10 +53,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}`;
@@ -83,7 +94,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();
@@ -121,7 +132,10 @@ describe("attachment routes through the real Express middleware stack", () => {
     );
 
     for (const method of ["HEAD", "GET"]) {
-      const res = await fetch(`${baseUrl}/attachments/${hash}`, { method });
+      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;
@@ -178,9 +192,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}`;

package/test/attachments/routes.test.ts

@@ -14,6 +14,7 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Readable, Writable } from "node:stream";
+import type { IAttachmentAccessService } from "@powerhousedao/reactor-api";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   buildContentDisposition,
@@ -29,6 +30,21 @@ import {
   quoteFilename,
 } from "../../src/attachments/routes.js";
 
+// Byte-serving mechanics under a granted read; grant decisions are tested in
+// byte-grants.test.ts.
+const ALLOW_ALL: IAttachmentAccessService = {
+  canReadAttachment: (request) =>
+    Promise.resolve({
+      kind: "allowed",
+      documentId: request.documentId as never,
+      ref: request.attachmentRef as never,
+    }),
+};
+const grantedDownload = (attachments: AttachmentBuildResult) =>
+  makeDownloadHandler(attachments, ALLOW_ALL, null);
+const grantedStat = (attachments: AttachmentBuildResult) =>
+  makeStatHandler(attachments, ALLOW_ALL, null);
+
 type CapturedRes = ServerResponse & {
   _headers: Record<string, string>;
   _body: Buffer;
@@ -52,7 +68,7 @@ function makeReq(opts: {
     params?: Record<string, string>;
   };
   req.method = opts.method;
-  req.url = opts.url ?? "/";
+  req.url = opts.url ?? "/?documentId=doc-1";
   req.headers = {};
   if (opts.params) req.params = opts.params;
   return req as unknown as IncomingMessage;
@@ -222,7 +238,7 @@ describe("attachment routes", () => {
     expect(row!.deleted_at_utc).not.toBeNull();
 
     // Download
-    const downloadHandler = makeDownloadHandler(attachments);
+    const downloadHandler = grantedDownload(attachments);
     const downloadReq = makeReq({
       method: "GET",
       params: { hash: upload.hash },
@@ -271,7 +287,7 @@ describe("attachment routes", () => {
       hash: string;
     };
 
-    const downloadHandler = makeDownloadHandler(attachments);
+    const downloadHandler = grantedDownload(attachments);
     const downloadReq = makeReq({
       method: "GET",
       params: { hash: upload.hash },
@@ -314,7 +330,7 @@ describe("attachment routes", () => {
       hash: string;
     };
 
-    const statHandler = makeStatHandler(attachments);
+    const statHandler = grantedStat(attachments);
     const statReq = makeReq({
       method: "HEAD",
       params: { hash: upload.hash },
@@ -373,9 +389,9 @@ describe("attachment routes", () => {
     };
 
     const { createServer } = await import("node:http");
-    const statHandler = makeStatHandler(attachments);
+    const statHandler = grantedStat(attachments);
     const server = createServer((req, res) => {
-      const m = /^\/attachments\/([^/]+)$/.exec(req.url ?? "/");
+      const m = /^\/attachments\/([^/?]+)(?:\?|$)/.exec(req.url ?? "/");
       if (!m) {
         res.statusCode = 404;
         res.end();
@@ -386,12 +402,14 @@ describe("attachment routes", () => {
       };
       void statHandler(req, res);
     });
-    await new Promise<void>((resolve) => server.listen(0, resolve));
+    await new Promise<void>((resolve) =>
+      server.listen(0, "127.0.0.1", resolve),
+    );
     const port = (server.address() as { port: number }).port;
 
     try {
       const response = await fetch(
-        `http://127.0.0.1:${port}/attachments/${upload.hash}`,
+        `http://127.0.0.1:${port}/attachments/${upload.hash}?documentId=doc-1`,
         {
           method: "HEAD",
         },
@@ -412,7 +430,7 @@ describe("attachment routes", () => {
   });
 
   it("HEAD stat returns 404 for unknown hash", async () => {
-    const handler = makeStatHandler(attachments);
+    const handler = grantedStat(attachments);
     const req = makeReq({ method: "HEAD", params: { hash: "a".repeat(64) } });
     const res = makeRes();
     await handler(req, res);
@@ -421,7 +439,7 @@ describe("attachment routes", () => {
   });
 
   it("HEAD stat returns 400 for malformed hash", async () => {
-    const handler = makeStatHandler(attachments);
+    const handler = grantedStat(attachments);
     const req = makeReq({ method: "HEAD", params: { hash: "not-a-hash" } });
     const res = makeRes();
     await handler(req, res);
@@ -523,7 +541,7 @@ describe("attachment routes", () => {
   });
 
   it("GET download returns 404 for unknown hash", async () => {
-    const handler = makeDownloadHandler(attachments);
+    const handler = grantedDownload(attachments);
     const req = makeReq({
       method: "GET",
       params: { hash: "a".repeat(64) },
@@ -535,7 +553,7 @@ describe("attachment routes", () => {
   });
 
   it("GET download returns 400 for malformed hash", async () => {
-    const handler = makeDownloadHandler(attachments);
+    const handler = grantedDownload(attachments);
     const req = makeReq({
       method: "GET",
       params: { hash: "not-a-hash" },
@@ -574,7 +592,7 @@ describe("attachment routes", () => {
       hash: string;
     };
 
-    const handler = makeDownloadHandler(attachments);
+    const handler = grantedDownload(attachments);
     const req = makeReq({
       method: "GET",
       params: { hash: upload.hash.toUpperCase() },
@@ -612,7 +630,7 @@ describe("attachment routes", () => {
       hash: string;
     };
 
-    const statHandler = makeStatHandler(attachments);
+    const statHandler = grantedStat(attachments);
     const statReq = makeReq({
       method: "HEAD",
       params: { hash: upload.hash.toUpperCase() },
@@ -660,7 +678,7 @@ describe("attachment routes", () => {
       throw new Error(secret);
     };
     try {
-      const handler = makeDownloadHandler(attachments);
+      const handler = grantedDownload(attachments);
       const req = makeReq({
         method: "GET",
         params: { hash: "a".repeat(64) },
@@ -933,7 +951,7 @@ describe("attachment routes", () => {
     it("HEAD stat returns 202 with Retry-After and Attachment-Pending for pending hash", async () => {
       const { hash } = await createPendingReservation("pending content data");
 
-      const handler = makeStatHandler(attachments);
+      const handler = grantedStat(attachments);
       const req = makeReq({ method: "HEAD", params: { hash } });
       const res = makeRes();
       await handler(req, res);
@@ -958,7 +976,7 @@ describe("attachment routes", () => {
     it("HEAD stat 202 for pending hash does not set Content-Disposition or Attachment-Metadata", async () => {
       const { hash } = await createPendingReservation("no metadata content");
 
-      const handler = makeStatHandler(attachments);
+      const handler = grantedStat(attachments);
       const req = makeReq({ method: "HEAD", params: { hash } });
       const res = makeRes();
       await handler(req, res);
@@ -972,7 +990,7 @@ describe("attachment routes", () => {
     it("GET download returns 202 with Retry-After and Attachment-Pending for pending hash", async () => {
       const { hash } = await createPendingReservation("download pending data");
 
-      const handler = makeDownloadHandler(attachments);
+      const handler = grantedDownload(attachments);
       const req = makeReq({ method: "GET", params: { hash } });
       const res = makeRes();
       await handler(req, res);
@@ -994,7 +1012,7 @@ describe("attachment routes", () => {
       // the response as a successful zero-byte attachment.
       const { hash } = await createPendingReservation("check-headers content");
 
-      const handler = makeDownloadHandler(attachments);
+      const handler = grantedDownload(attachments);
       const req = makeReq({ method: "GET", params: { hash } });
       const res = makeRes();
       await handler(req, res);
@@ -1014,8 +1032,8 @@ describe("attachment routes", () => {
         );
 
         for (const [method, handler] of [
-          ["HEAD", makeStatHandler(attachments)],
-          ["GET", makeDownloadHandler(attachments)],
+          ["HEAD", grantedStat(attachments)],
+          ["GET", grantedDownload(attachments)],
         ] as const) {
           const req = makeReq({ method, params: { hash } });
           const res = makeRes();
@@ -1034,7 +1052,7 @@ describe("attachment routes", () => {
     it("GET download 202 body is empty (not a zero-byte attachment)", async () => {
       const { hash } = await createPendingReservation("empty body assertion");
 
-      const handler = makeDownloadHandler(attachments);
+      const handler = grantedDownload(attachments);
       const req = makeReq({ method: "GET", params: { hash } });
       const res = makeRes();
       await handler(req, res);
@@ -1322,7 +1340,7 @@ describe("attachment routes", () => {
     it("download with non-ASCII fileName produces RFC 6266 Content-Disposition", async () => {
       const reserveHandler = makeReserveHandler(attachments);
       const uploadHandler = makeUploadHandler(attachments);
-      const downloadHandler = makeDownloadHandler(attachments);
+      const downloadHandler = grantedDownload(attachments);
 
       const reserveReq = makeReq({
         method: "POST",
@@ -1392,8 +1410,8 @@ describe("attachment routes", () => {
       };
 
       for (const [method, handler] of [
-        ["HEAD", makeStatHandler(attachments)],
-        ["GET", makeDownloadHandler(attachments)],
+        ["HEAD", grantedStat(attachments)],
+        ["GET", grantedDownload(attachments)],
       ] as const) {
         const res = makeRes();
         await handler(makeReq({ method, params: { hash } }), res);

package/test/attachments/service-config.test.ts

@@ -1,5 +1,5 @@
 import { PGlite } from "@electric-sql/pglite";
-import type { API } from "@powerhousedao/reactor-api";
+import type { API, IAttachmentAccessService } from "@powerhousedao/reactor-api";
 import { createHttpAdapter } from "@powerhousedao/reactor-api";
 import {
   AttachmentBuilder,
@@ -109,10 +109,20 @@ describe("attachment service built from deriveAttachmentServiceConfig round-trip
     registerAttachmentRoutes({
       httpAdapter: adapter,
       attachments,
+      attachmentAccess: {
+        canReadAttachment: (
+          request: Parameters<IAttachmentAccessService["canReadAttachment"]>[0],
+        ) =>
+          Promise.resolve({
+            kind: "allowed",
+            documentId: request.documentId as never,
+            ref: request.attachmentRef as never,
+          }),
+      },
       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");
     port = addr.port;
@@ -149,7 +159,7 @@ describe("attachment service built from deriveAttachmentServiceConfig round-trip
     const result = await upload.send(stream);
     expect(result.header.sizeBytes).toBe(bytes.byteLength);
 
-    const got = await service.get(result.ref);
+    const got = await service.get(result.ref, { documentId: "doc-1" });
     expect(got.header.mimeType).toBe("text/plain");
     const reader = got.body.getReader();
     const chunks: Uint8Array[] = [];