@powerhousedao/switchboard 6.2.3-dev.9 → 6.2.3

package/test/attachments/routes.test.ts

@@ -6,13 +6,20 @@ import {
 import { Kysely } from "kysely";
 import { PGliteDialect } from "kysely-pglite-dialect";
 import { mkdtemp, rm } from "node:fs/promises";
-import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  validateHeaderValue,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
 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,
+  buildMetadataHeader,
+  buildPendingHeader,
   makeDeleteReservationHandler,
   makeDownloadHandler,
   makeGetReservationHandler,
@@ -23,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;
@@ -46,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;
@@ -70,6 +92,9 @@ function makeRes(): CapturedRes {
     statusCode: 200,
     _headers: headers,
     setHeader(name: string, value: string | number | readonly string[]) {
+      // Same check Node's ServerResponse applies, so a header value it would
+      // reject fails here instead of passing silently.
+      validateHeaderValue(name, String(value));
       headers[name.toLowerCase()] = String(value);
     },
     getHeader(name: string) {
@@ -213,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 },
@@ -262,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 },
@@ -305,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 },
@@ -364,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();
@@ -377,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",
         },
@@ -403,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);
@@ -412,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);
@@ -514,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) },
@@ -526,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" },
@@ -565,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() },
@@ -603,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() },
@@ -651,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) },
@@ -899,6 +926,7 @@ describe("attachment routes", () => {
   describe("pending state: stat and download 202 responses", () => {
     async function createPendingReservation(
       content: string,
+      fileName = "pending.txt",
     ): Promise<{ hash: string }> {
       const { createHash } = await import("node:crypto");
       const hash = createHash("sha256").update(content, "utf8").digest("hex");
@@ -908,7 +936,7 @@ describe("attachment routes", () => {
         method: "POST",
         body: JSON.stringify({
           mimeType: "text/plain",
-          fileName: "pending.txt",
+          fileName,
           clientHash: hash,
           sizeBytes: Buffer.byteLength(content, "utf8"),
         }),
@@ -923,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);
@@ -948,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);
@@ -962,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);
@@ -984,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);
@@ -995,10 +1023,36 @@ describe("attachment routes", () => {
       expect(res.getHeader("attachment-metadata")).toBeFalsy();
     });
 
+    it.each(["opłata.pdf", "a – b’s.txt", "📎.png", "報告書.pdf"])(
+      "HEAD and GET 202 carry a parseable Attachment-Pending for %s",
+      async (fileName) => {
+        const { hash } = await createPendingReservation(
+          `pending ${fileName}`,
+          fileName,
+        );
+
+        for (const [method, handler] of [
+          ["HEAD", grantedStat(attachments)],
+          ["GET", grantedDownload(attachments)],
+        ] as const) {
+          const req = makeReq({ method, params: { hash } });
+          const res = makeRes();
+          await handler(req, res);
+          await waitFor(res);
+
+          expect(res.statusCode).toBe(202);
+          const parsed = JSON.parse(
+            res.getHeader("attachment-pending") as string,
+          ) as { fileName: string };
+          expect(parsed.fileName).toBe(fileName);
+        }
+      },
+    );
+
     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);
@@ -1215,6 +1269,54 @@ describe("attachment routes", () => {
       }
     });
 
+    const NON_LATIN1_NAMES = [
+      "opłata.pdf",
+      "a – b’s.txt",
+      "📎 notes.png",
+      "報告書.pdf",
+      "résumé.pdf",
+      'quote"back\\slash.txt',
+    ];
+
+    it.each(NON_LATIN1_NAMES)(
+      "buildMetadataHeader output is a valid header that parses back to %s",
+      (fileName) => {
+        const value = buildMetadataHeader({
+          mimeType: "application/pdf",
+          fileName,
+          sizeBytes: 1,
+          extension: null,
+          createdAtUtc: "2026-01-01T00:00:00.000Z",
+          lastAccessedAtUtc: "2026-01-01T00:00:00.000Z",
+        });
+        expect(() =>
+          validateHeaderValue("Attachment-Metadata", value),
+        ).not.toThrow();
+        expect(value).toMatch(/^[\x20-\x7e]*$/);
+        expect((JSON.parse(value) as { fileName: string }).fileName).toBe(
+          fileName,
+        );
+      },
+    );
+
+    it.each(NON_LATIN1_NAMES)(
+      "buildPendingHeader output is a valid header that parses back to %s",
+      (fileName) => {
+        const value = buildPendingHeader({
+          expiresAtUtc: "2026-01-01T00:00:00.000Z",
+          mimeType: "application/pdf",
+          fileName,
+          sizeBytes: 1,
+        });
+        expect(() =>
+          validateHeaderValue("Attachment-Pending", value),
+        ).not.toThrow();
+        expect((JSON.parse(value) as { fileName: string }).fileName).toBe(
+          fileName,
+        );
+      },
+    );
+
     it("buildContentDisposition encodes RFC-5987-reserved chars in the encoded form", () => {
       const value = buildContentDisposition("a'b(c)*!.txt");
       expect(value).toContain("filename*=UTF-8''a%27b%28c%29%2A%21.txt");
@@ -1238,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",
@@ -1281,5 +1383,45 @@ describe("attachment routes", () => {
       ) as { fileName: string };
       expect(meta.fileName).toBe("résumé.pdf");
     });
+
+    it("HEAD and GET answer 200 with a parseable Attachment-Metadata for a name above U+00FF", async () => {
+      const fileName = "opłata – 報告 📎.pdf";
+      const reserveReq = makeReq({
+        method: "POST",
+        body: JSON.stringify({ mimeType: "application/pdf", fileName }),
+      });
+      const reserveRes = makeRes();
+      await makeReserveHandler(attachments)(reserveReq, reserveRes);
+      await waitFor(reserveRes);
+      expect(reserveRes.statusCode).toBe(201);
+      const { reservationId } = JSON.parse(
+        reserveRes._body.toString("utf8"),
+      ) as { reservationId: string };
+
+      const uploadRes = makeRes();
+      await makeUploadHandler(attachments)(
+        makeReq({ method: "PUT", params: { reservationId }, body: "pdf" }),
+        uploadRes,
+      );
+      await waitFor(uploadRes);
+      expect(uploadRes.statusCode).toBe(200);
+      const { hash } = JSON.parse(uploadRes._body.toString("utf8")) as {
+        hash: string;
+      };
+
+      for (const [method, handler] of [
+        ["HEAD", grantedStat(attachments)],
+        ["GET", grantedDownload(attachments)],
+      ] as const) {
+        const res = makeRes();
+        await handler(makeReq({ method, params: { hash } }), res);
+        await waitFor(res);
+        expect(res.statusCode).toBe(200);
+        const meta = JSON.parse(
+          res.getHeader("attachment-metadata") as string,
+        ) as { fileName: string };
+        expect(meta.fileName).toBe(fileName);
+      }
+    });
   });
 });

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[] = [];

package/test/attachments/url-signer.test.ts

@@ -0,0 +1,105 @@
+import type { AttachmentHash } from "@powerhousedao/reactor";
+import { describe, expect, it } from "vitest";
+import {
+  ATTACHMENT_URL_SIGNING_SECRET_ENV,
+  AttachmentUrlSigner,
+  resolveAttachmentUrlSigning,
+} from "../../src/attachments/url-signer.js";
+
+const HASH = "a".repeat(64) as AttachmentHash;
+const OTHER_HASH = "b".repeat(64) as AttachmentHash;
+const SECRET = "k".repeat(32);
+
+function signed(now: number, ttl = 300) {
+  const signer = new AttachmentUrlSigner(SECRET, () => now);
+  const { query, expiresAtUtc } = signer.sign(HASH, "doc-1", ttl);
+  const params = new URLSearchParams(query);
+  return {
+    signer,
+    expiresAtUtc,
+    documentId: params.get("documentId")!,
+    expires: params.get("expires")!,
+    signature: params.get("signature")!,
+  };
+}
+
+describe("AttachmentUrlSigner", () => {
+  const NOW = Date.parse("2026-09-24T00:00:00.000Z");
+
+  it("verifies what it signed until the expiry", () => {
+    const { signer, expiresAtUtc, documentId, expires, signature } =
+      signed(NOW);
+
+    expect(documentId).toBe("doc-1");
+    expect(expiresAtUtc).toBe(new Date(NOW + 300_000).toISOString());
+    expect(signer.verify(HASH, documentId, expires, signature)).toBe(true);
+  });
+
+  it("refuses at and after the expiry", () => {
+    const { expires, signature } = signed(NOW);
+    const at = new AttachmentUrlSigner(SECRET, () => NOW + 300_000);
+
+    expect(at.verify(HASH, "doc-1", expires, signature)).toBe(false);
+  });
+
+  it("refuses a different hash, document, expiry or secret", () => {
+    const { signer, expires, signature } = signed(NOW);
+
+    expect(signer.verify(OTHER_HASH, "doc-1", expires, signature)).toBe(false);
+    expect(signer.verify(HASH, "doc-2", expires, signature)).toBe(false);
+    expect(
+      signer.verify(HASH, "doc-1", String(Number(expires) + 1), signature),
+    ).toBe(false);
+    expect(
+      new AttachmentUrlSigner("x".repeat(32), () => NOW).verify(
+        HASH,
+        "doc-1",
+        expires,
+        signature,
+      ),
+    ).toBe(false);
+  });
+
+  it("refuses malformed expiry and signature values", () => {
+    const { signer, expires, signature } = signed(NOW);
+
+    expect(signer.verify(HASH, "doc-1", `${expires}.0`, signature)).toBe(false);
+    expect(signer.verify(HASH, "doc-1", expires, `${signature}=`)).toBe(false);
+    expect(signer.verify(HASH, "doc-1", expires, "")).toBe(false);
+  });
+});
+
+describe("resolveAttachmentUrlSigning", () => {
+  it("uses a configured secret", () => {
+    const signing = resolveAttachmentUrlSigning({
+      [ATTACHMENT_URL_SIGNING_SECRET_ENV]: SECRET,
+      NODE_ENV: "production",
+    });
+    expect(signing.status).toBe("configured");
+  });
+
+  it("fails closed in production when unset", () => {
+    expect(resolveAttachmentUrlSigning({ NODE_ENV: "production" })).toEqual({
+      status: "unconfigured",
+    });
+  });
+
+  it.each([undefined, "development", "test"])(
+    "uses a per-process secret when unset and NODE_ENV is %s",
+    (nodeEnv) => {
+      const signing = resolveAttachmentUrlSigning({ NODE_ENV: nodeEnv });
+      expect(signing.status).toBe("ephemeral");
+    },
+  );
+
+  it.each(["short", ` ${"k".repeat(32)}`, ""])(
+    "refuses to boot on an unusable secret %j",
+    (secret) => {
+      expect(() =>
+        resolveAttachmentUrlSigning({
+          [ATTACHMENT_URL_SIGNING_SECRET_ENV]: secret,
+        }),
+      ).toThrow(ATTACHMENT_URL_SIGNING_SECRET_ENV);
+    },
+  );
+});

package/test/boot-create-signature-policy.test.ts

@@ -0,0 +1,108 @@
+import {
+  hasDerivedDocumentId,
+  isDerivedDocumentId,
+  signaturePolicyOf,
+} from "@powerhousedao/shared/document-model";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ILogger } from "document-model";
+import { describe, expect, it, vi } from "vitest";
+import { startSwitchboard } from "../src/server.mjs";
+
+function stubLogger(): ILogger {
+  const logger = {
+    verbose: vi.fn(),
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(),
+  };
+  logger.child.mockReturnValue(logger);
+  return logger as unknown as ILogger;
+}
+
+async function withSwitchboard(
+  env: Record<string, string>,
+  run: (
+    switchboard: Awaited<ReturnType<typeof startSwitchboard>>,
+  ) => Promise<void>,
+): Promise<void> {
+  const tempRoot = await mkdtemp(join(tmpdir(), "switchboard-create-policy-"));
+  const names = ["PH_REACTOR_DATABASE_URL", ...Object.keys(env)];
+  const previous = names.map((name) => [name, process.env[name]] as const);
+  process.env.PH_REACTOR_DATABASE_URL = join(tempRoot, "reactor-storage");
+  Object.assign(process.env, env);
+  let switchboard: Awaited<ReturnType<typeof startSwitchboard>> | undefined;
+
+  try {
+    switchboard = await startSwitchboard({
+      workflows: { enabled: false },
+      dbPath: join(tempRoot, "read-model"),
+      port: 0,
+      mcp: false,
+      disableLocalPackages: true,
+      identity: { keypairPath: join(tempRoot, "identity.json") },
+      drive: {
+        slug: "default-drive",
+        global: { name: "Default Drive" },
+      },
+      logger: stubLogger(),
+    });
+    await run(switchboard);
+    await switchboard.shutdown();
+    switchboard = undefined;
+  } finally {
+    await switchboard?.shutdown();
+    for (const [name, value] of previous) {
+      if (value === undefined) {
+        delete process.env[name];
+      } else {
+        process.env[name] = value;
+      }
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+describe("booting Switchboard", () => {
+  it("creates v2-required documents and drives by default", async () => {
+    await withSwitchboard({}, async ({ reactor }) => {
+      const document = await reactor.createEmpty("powerhouse/document-model");
+      expect(signaturePolicyOf(document.header)).toBe("v2-required");
+      expect(hasDerivedDocumentId(document.header)).toBe(true);
+
+      const drive = await reactor.drives.create({ global: { name: "Drive" } });
+      expect(signaturePolicyOf(drive.header)).toBe("v2-required");
+
+      const defaultDrive = await reactor.get("default-drive");
+      expect(signaturePolicyOf(defaultDrive.header)).toBe("v2-required");
+    });
+  }, 60_000);
+
+  it("creates legacy documents and drives under CREATE_SIGNATURE_POLICY=legacy", async () => {
+    await withSwitchboard(
+      { CREATE_SIGNATURE_POLICY: "legacy" },
+      async ({ reactor }) => {
+        const document = await reactor.createEmpty("powerhouse/document-model");
+        expect(signaturePolicyOf(document.header)).toBe("legacy");
+        expect(isDerivedDocumentId(document.header.id)).toBe(false);
+
+        const drive = await reactor.drives.create({
+          global: { name: "Drive" },
+        });
+        expect(signaturePolicyOf(drive.header)).toBe("legacy");
+        expect(isDerivedDocumentId(drive.header.id)).toBe(false);
+
+        const defaultDrive = await reactor.get("default-drive");
+        expect(signaturePolicyOf(defaultDrive.header)).toBe("legacy");
+
+        const asked = await reactor.createEmpty("powerhouse/document-model", {
+          signaturePolicy: "v2-required",
+        });
+        expect(hasDerivedDocumentId(asked.header)).toBe(true);
+      },
+    );
+  }, 60_000);
+});