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

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

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/workflow/harness.ts

@@ -97,7 +97,7 @@ export async function startWebhookHost(
   // constructing it would test a path no consumer can take.
   const { adapter } = await createHttpAdapter("express");
   adapter.setupMiddleware({});
-  const server = await adapter.listen(0);
+  const server = await adapter.listen(0, undefined, "127.0.0.1");
   const { port } = server.address() as { port: number };
   const url = `http://127.0.0.1:${port}`;
 

package/test/workflow-read-gate.test.ts

@@ -0,0 +1,145 @@
+import {
+  ReactorBuilder,
+  ReactorClientBuilder,
+  type InProcessReactorClientModule,
+} from "@powerhousedao/reactor";
+import { AuthorizationPolicy, type Context } from "@powerhousedao/reactor-api";
+import {
+  initializeAuth,
+  withSignaturePolicy,
+  type DocumentModelModule,
+} from "@powerhousedao/shared/document-model";
+import type { ILogger } from "document-model";
+import { documentModelDocumentModelModule } from "document-model";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { composeWorkflowRuntime } from "../src/workflow-runtime.mjs";
+
+const READER = "0xreader";
+const OUTSIDER = "0xoutsider";
+
+// The host's legacy layer under OPEN admits everyone, anonymous included.
+const openAuthorization = {
+  config: {
+    admins: [],
+    defaultProtection: false,
+    policy: AuthorizationPolicy.OPEN,
+  },
+  isSupremeAdmin: () => true,
+  canRead: () => Promise.resolve(true),
+  canWrite: () => Promise.resolve(true),
+};
+
+const logger = {
+  verbose: vi.fn(),
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  child: () => logger,
+} as unknown as ILogger;
+
+const contextFor = (address?: string) =>
+  ({ headers: {}, db: {}, user: address ? { address } : undefined }) as Context;
+
+describe("the workflow runtime's read check", () => {
+  let module: InProcessReactorClientModule | undefined;
+
+  afterEach(() => {
+    module?.reactor.kill();
+    module = undefined;
+  });
+
+  async function hostDeps() {
+    module = await new ReactorClientBuilder()
+      .withReactorBuilder(
+        new ReactorBuilder()
+          .withDocumentModelSources([
+            documentModelDocumentModelModule as unknown as DocumentModelModule,
+          ])
+          .withExecutorConfig({
+            featureFlags: { documentDecisions: true, authEnforcement: true },
+          }),
+      )
+      .buildModule();
+    const client = module.client;
+    const id = "wf-policed";
+    await client.create(
+      withSignaturePolicy(
+        documentModelDocumentModelModule.utils.createDocument(),
+        "legacy",
+        { id },
+      ),
+    );
+    await client.execute(id, "main", [
+      initializeAuth({
+        version: 1,
+        grants: [
+          {
+            id: "g-read",
+            description: "the reader reads the domain",
+            effect: "allow",
+            principal: { address: READER },
+            capability: { can: "read", scope: "global" },
+          },
+          {
+            id: "g-admin",
+            description: "administration stays reachable",
+            effect: "allow",
+            principal: { anyone: true },
+            capability: { can: "execute", scope: "auth" },
+          },
+        ],
+      }),
+    ]);
+
+    const createWorkflowRuntime = vi.fn((_deps: Record<string, unknown>) => ({
+      shutdown: vi.fn(),
+    }));
+    await composeWorkflowRuntime({
+      reactorClient: client,
+      relationalDb: {} as never,
+      attachments: {} as never,
+      authorizationService: openAuthorization as never,
+      logger,
+      load: () =>
+        Promise.resolve({
+          WORKFLOW_PACKAGE_NAME: "@powerhousedao/workflow",
+          setPieceRegistryUrl: vi.fn(),
+          createWorkflowRuntime,
+        } as never),
+    });
+    const [deps] = createWorkflowRuntime.mock.calls[0]!;
+    return {
+      id,
+      deps: deps as {
+        assertCanRead: (id: string, caller: object) => Promise<unknown>;
+        subjectOf: (caller: object) => unknown;
+      },
+    };
+  }
+
+  it("refuses under OPEN a document the caller is not served", async () => {
+    const { id, deps } = await hostDeps();
+
+    await expect(deps.assertCanRead(id, contextFor())).rejects.toThrow();
+    await expect(
+      deps.assertCanRead(id, contextFor(OUTSIDER)),
+    ).rejects.toThrow();
+    await expect(
+      deps.assertCanRead(id, contextFor(READER)),
+    ).resolves.toBeUndefined();
+  });
+
+  it("reads a caller as its own subject, anonymous as the empty one", async () => {
+    const { deps } = await hostDeps();
+
+    expect(deps.subjectOf(contextFor(READER))).toEqual({
+      address: READER,
+      key: undefined,
+    });
+    expect(deps.subjectOf(contextFor())).toEqual({
+      address: undefined,
+      key: undefined,
+    });
+  });
+});

package/tsdown.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from "tsdown";
+import { dtsExportList } from "../../tsdown.dts.mjs";
 
 export default defineConfig({
   entry: [
@@ -11,6 +12,7 @@ export default defineConfig({
   platform: "node",
   outDir: "dist",
   clean: true,
-  dts: true,
+  dts: { generator: "tsgo" },
+  plugins: [dtsExportList()],
   sourcemap: true,
 });