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

package/Auth.md

@@ -275,8 +275,10 @@ including authenticated ones.
 It also covers the attachment routes, which are mounted on the HTTP adapter and
 never pass the GraphQL fetch chain. Their own 401 keys on `AUTH_ENABLED`, so
 without this switch a deployment running `OPEN` serves them to anyone; with it,
-every attachment route refuses a caller it cannot name — `download-target`
-included, even though that route decides per document on its own.
+every attachment route refuses a caller it cannot name — `download-target` and
+the `GET`/`HEAD /attachments/:hash` byte routes included, even though they
+decide per document (or by a signed URL) on their own. A filesystem signed
+download URL therefore needs a bearer too while this switch is on.
 
 ##### Serving one path anonymously
 

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 6.2.3-dev.26 (2026-09-26)
+
+### 🚀 Features
+
+- ⚠️  **switchboard:** serve attachment bytes only under a document grant ([275e88da0](https://github.com/powerhouse-inc/powerhouse/commit/275e88da0))
+- **switchboard:** sign short-lived attachment byte-route URLs ([18e09cdb5](https://github.com/powerhouse-inc/powerhouse/commit/18e09cdb5))
+
+### 🩹 Fixes
+
+- **switchboard:** sign byte-route URLs under main's download-target TTL cap ([d503b4f67](https://github.com/powerhouse-inc/powerhouse/commit/d503b4f67))
+- **reactor-workflow:** serve workflow reads and runs as the caller ([b2ddd126a](https://github.com/powerhouse-inc/powerhouse/commit/b2ddd126a))
+- **reactor-drive:** gate the reactor-drive subgraph as the caller ([7041635f4](https://github.com/powerhouse-inc/powerhouse/commit/7041635f4))
+- **reactor-api:** gate attachment reads through the reactor's read gate ([d6c3b4df1](https://github.com/powerhouse-inc/powerhouse/commit/d6c3b4df1))
+
+### ⚠️  Breaking Changes
+
+- **switchboard:** serve attachment bytes only under a document grant  ([275e88da0](https://github.com/powerhouse-inc/powerhouse/commit/275e88da0))
+
+### ❤️ Thank You
+
+- Benjamin Jordan
+- Claude Opus 5.5
+
 ## 6.2.3-dev.25 (2026-09-25)
 
 ### 🚀 Features

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f6ffead6-4742-59d9-948c-1c651716e65b")}catch(e){}}();
-import { a as parseForcePgVersion, r as startSwitchboard } from "./server-C3WaP3kE.mjs";
+import { a as parseForcePgVersion, r as startSwitchboard } from "./server-DQCIIJzK.mjs";
 import { metrics } from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

package/dist/{server-C3WaP3kE.mjs → server-DQCIIJzK.mjs}

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8174bb20-5463-598a-9c2d-44a8760037a5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3a84ab97-af9a-5a44-94fa-3b59ffe5eed8")}catch(e){}}();
 import { n as addDefaultReactorDrive, r as isPostgresUrl, t as addDefaultDrive } from "./utils-uaBlzyjS.mjs";
 import { createRequire, register } from "node:module";
 import { ReactorInstrumentation } from "@powerhousedao/opentelemetry-instrumentation-reactor";
@@ -11,7 +11,7 @@ import { existsSync, promises, realpathSync } from "node:fs";
 import path, { resolve } from "node:path";
 import { AtomicNodeFs } from "@powerhousedao/pglite-fs";
 import { ChannelScheme, DriveCollectionId, EventBus, REACTOR_SCHEMA, ReactorBuilder, ReactorClientBuilder, createHybridProjectionCoordinatorFactory, instrumentPgPool, parseDriveUrl, supportsLiveReadModelRegistration } from "@powerhousedao/reactor";
-import { AuthorizationPolicy, BaseSubgraph, ForbiddenError, HttpPackageLoader, ImportPackageLoader, PGLITE_UTC_PARSERS, PackageManagementService, PackagesSubgraph, createCanonicalDocumentIdResolver, getUniqueDocumentModels, initializeAndStartAPI, resolveRenownConfig } from "@powerhousedao/reactor-api";
+import { AuthorizationPolicy, BaseSubgraph, ForbiddenError, HttpPackageLoader, ImportPackageLoader, PGLITE_UTC_PARSERS, PackageManagementService, PackagesSubgraph, callerSubject, createCanonicalDocumentIdResolver, getUniqueDocumentModels, initializeAndStartAPI, resolveRenownConfig } from "@powerhousedao/reactor-api";
 import { httpsHooksPath } from "@powerhousedao/reactor-api/https-hooks";
 import { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, AttachmentReferenceReadModel, AttachmentSchemaCompiler, HashMismatch, InvalidAttachmentRef, ReservationNotFound, SizeMismatch, UploadTooLarge, createRef, createRemoteAttachmentService, parseAttachmentDownloadTarget, parseRef } from "@powerhousedao/reactor-attachments";
 import { createAttachmentClient } from "@powerhousedao/reactor-attachments/client";
@@ -22,6 +22,7 @@ import net from "node:net";
 import path$1 from "path";
 import { Pool } from "pg";
 import { Readable } from "node:stream";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { ReactorGroupV1 } from "@powerhousedao/reactor-group";
 import { driveDocumentModelModule } from "@powerhousedao/shared/document-drive";
 import { DEFAULT_SIGNATURE_POLICY, isSignaturePolicy } from "@powerhousedao/shared/document-model";
@@ -147,7 +148,7 @@ function mountAuthenticatedNodeRoute(api, method, path, handler, options) {
 }
 //#endregion
 //#region src/attachments/routes.ts
-const logger$1 = childLogger(["switchboard", "attachments"]);
+const logger$2 = childLogger(["switchboard", "attachments"]);
 const RETRY_AFTER_SECONDS = 5;
 const HASH_PATTERN = /^[a-f0-9]{64}$/i;
 const CONTROL_CHARS = /[\x00-\x1f\x7f]/;
@@ -172,7 +173,7 @@ function statusForError(err) {
 function sendErrorFromException(res, err) {
 	const status = statusForError(err);
 	if (status >= 500) {
-		logger$1.error("Attachment route error: @error", err);
+		logger$2.error("Attachment route error: @error", err);
 		sendError(res, status, "Internal error");
 		return;
 	}
@@ -301,22 +302,25 @@ function makeUploadHandler(attachments) {
 		}
 	};
 }
-function makeDownloadHandler(attachments) {
-	return async (req, res) => {
+function makeDownloadHandler(attachments, attachmentAccess, urlSigner) {
+	return async (req, res, _body, actor) => {
 		const hash = extractParam(req, "hash");
 		if (!hash || !HASH_PATTERN.test(hash)) {
 			sendError(res, 400, "Invalid attachment hash");
 			return;
 		}
+		const canonicalHash = hash.toLowerCase();
+		const grant = await resolveByteGrant(req, canonicalHash, actor, attachmentAccess, urlSigner);
+		if (!admitGrant(res, grant)) return;
 		const controller = new AbortController();
 		req.once("close", () => controller.abort());
-		const canonicalHash = hash.toLowerCase();
 		let response;
 		try {
-			response = await attachments.store.get(canonicalHash, controller.signal);
+			response = await attachments.store.get(canonicalHash, controller.signal, grant.documentId);
 		} catch (err) {
 			if (err instanceof AttachmentPending) {
 				res.statusCode = 202;
+				res.setHeader("Cache-Control", "private");
 				res.setHeader("Retry-After", String(RETRY_AFTER_SECONDS));
 				res.setHeader("Attachment-Pending", buildPendingHeader({
 					expiresAtUtc: err.expiresAtUtc,
@@ -330,6 +334,7 @@ function makeDownloadHandler(attachments) {
 		}
 		const { header, body } = response;
 		res.statusCode = 200;
+		res.setHeader("Cache-Control", "private");
 		res.setHeader("Content-Type", header.mimeType);
 		res.setHeader("Content-Length", String(header.sizeBytes));
 		res.setHeader("Content-Disposition", buildContentDisposition(header.fileName));
@@ -353,14 +358,15 @@ function buildMetadataHeader(header) {
 		lastAccessedAtUtc: header.lastAccessedAtUtc
 	});
 }
-function makeStatHandler(attachments) {
-	return async (req, res) => {
+function makeStatHandler(attachments, attachmentAccess, urlSigner) {
+	return async (req, res, _body, actor) => {
 		const hash = extractParam(req, "hash");
 		if (!hash || !HASH_PATTERN.test(hash)) {
 			sendError(res, 400, "Invalid attachment hash");
 			return;
 		}
 		const canonicalHash = hash.toLowerCase();
+		if (!admitGrant(res, await resolveByteGrant(req, canonicalHash, actor, attachmentAccess, urlSigner))) return;
 		let header;
 		try {
 			header = await attachments.store.stat(canonicalHash);
@@ -368,6 +374,7 @@ function makeStatHandler(attachments) {
 			sendErrorFromException(res, err);
 			return;
 		}
+		res.setHeader("Cache-Control", "private");
 		if (header.status === "pending") {
 			res.statusCode = 202;
 			res.setHeader("Retry-After", String(RETRY_AFTER_SECONDS));
@@ -449,7 +456,7 @@ function downloadTargetTtlCapSeconds() {
 	if (configured === void 0) return DEFAULT_DOWNLOAD_TARGET_TTL_SECONDS;
 	const parsed = Number(configured);
 	if (!Number.isInteger(parsed) || parsed <= 0) {
-		logger$1.warn(`Ignoring invalid ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS="${configured}" (expected a positive integer number of seconds) — using ${DEFAULT_DOWNLOAD_TARGET_TTL_SECONDS}`);
+		logger$2.warn(`Ignoring invalid ATTACHMENT_DOWNLOAD_TARGET_MAX_TTL_SECONDS="${configured}" (expected a positive integer number of seconds) — using ${DEFAULT_DOWNLOAD_TARGET_TTL_SECONDS}`);
 		return DEFAULT_DOWNLOAD_TARGET_TTL_SECONDS;
 	}
 	return Math.min(parsed, MAX_DOWNLOAD_TARGET_TTL_SECONDS);
@@ -498,10 +505,71 @@ function extractExpiresIn(req) {
 	if (!Number.isInteger(parsed) || parsed <= 0) return "invalid";
 	return Math.min(parsed, cap);
 }
+function singleQueryValue(params, name) {
+	const values = params.getAll(name);
+	return values.length === 1 ? values[0] : null;
+}
+/**
+* Byte routes serve only under a grant: a signed URL minted by the
+* download-target route, or a documentId the caller may read the attachment
+* through. A signed request is judged by its signature alone.
+*/
+async function resolveByteGrant(req, hash, actor, attachmentAccess, urlSigner) {
+	let params;
+	try {
+		params = new URL(req.url ?? "", "http://switchboard.invalid").searchParams;
+	} catch {
+		return { kind: "denied" };
+	}
+	const documentId = extractSingleDocumentId(req);
+	if (documentId === null) return { kind: "denied" };
+	if (params.has("signature") || params.has("expires")) {
+		const signature = singleQueryValue(params, "signature");
+		const expires = singleQueryValue(params, "expires");
+		if (!urlSigner || signature === null || expires === null) return { kind: "denied" };
+		return urlSigner.verify(hash, documentId, expires, signature) ? {
+			kind: "granted",
+			documentId
+		} : { kind: "denied" };
+	}
+	let decision;
+	try {
+		decision = await attachmentAccess.canReadAttachment({
+			documentId,
+			attachmentRef: createRef(hash),
+			userAddress: actor?.user?.address,
+			appKey: actor?.user?.appKey
+		});
+	} catch (err) {
+		logger$2.error("Attachment access decision failed: @error", err);
+		return { kind: "error" };
+	}
+	if (decision.kind === "projection-unavailable") return { kind: "unavailable" };
+	if (decision.kind === "denied") return { kind: "denied" };
+	return {
+		kind: "granted",
+		documentId: decision.documentId
+	};
+}
+/** Answers a refused grant; true when the request may proceed. */
+function admitGrant(res, grant) {
+	switch (grant.kind) {
+		case "granted": return true;
+		case "denied":
+			sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+			return false;
+		case "unavailable":
+			sendError(res, 503, "Attachment downloads are temporarily unavailable");
+			return false;
+		case "error":
+			sendError(res, 500, "Internal error");
+			return false;
+	}
+}
 /**
 * Base URL of this Switchboard as seen by the caller, used to build
-* filesystem `switchboard` download targets that point back at the existing
-* authenticated byte route.
+* filesystem `switchboard` download targets that point back at the signed
+* byte route.
 */
 function requestBaseUrl(req) {
 	const forwardedProto = req.headers["x-forwarded-proto"];
@@ -511,7 +579,7 @@ function requestBaseUrl(req) {
 	if (!host) return null;
 	return `${proto}://${host}`;
 }
-function makeDownloadTargetHandler(attachments, attachmentAccess) {
+function makeDownloadTargetHandler(attachments, attachmentAccess, urlSigner) {
 	return async (req, res, _body, actor) => {
 		res.setHeader("Cache-Control", "no-store");
 		const hash = extractParam(req, "hash");
@@ -539,7 +607,7 @@ function makeDownloadTargetHandler(attachments, attachmentAccess) {
 				appKey: actor?.user?.appKey
 			});
 		} catch (err) {
-			logger$1.error("Attachment access decision failed: @error", err);
+			logger$2.error("Attachment access decision failed: @error", err);
 			sendError(res, 500, "Internal error");
 			return;
 		}
@@ -559,7 +627,7 @@ function makeDownloadTargetHandler(attachments, attachmentAccess) {
 				sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
 				return;
 			}
-			logger$1.error("Attachment metadata lookup failed: @error", err);
+			logger$2.error("Attachment metadata lookup failed: @error", err);
 			sendError(res, 500, "Internal error");
 			return;
 		}
@@ -575,17 +643,23 @@ function makeDownloadTargetHandler(attachments, attachmentAccess) {
 			return;
 		}
 		else {
+			if (!urlSigner) {
+				sendError(res, 503, "Attachment download signing is not configured");
+				return;
+			}
 			const base = requestBaseUrl(req);
 			if (!base) {
 				sendError(res, 500, "Internal error");
 				return;
 			}
+			const signed = urlSigner.sign(canonicalHash, decision.documentId, expiresIn);
 			try {
 				target = parseAttachmentDownloadTarget({
 					kind: "switchboard",
 					method: "GET",
-					url: `${base}/attachments/${canonicalHash}`,
-					headers: {}
+					url: `${base}/attachments/${canonicalHash}?${signed.query}`,
+					headers: {},
+					expiresAtUtc: signed.expiresAtUtc
 				});
 			} catch {
 				sendError(res, 500, "Internal error");
@@ -596,16 +670,82 @@ function makeDownloadTargetHandler(attachments, attachmentAccess) {
 	};
 }
 //#endregion
+//#region src/attachments/url-signer.ts
+const ATTACHMENT_URL_SIGNING_SECRET_ENV = "PH_ATTACHMENT_URL_SIGNING_SECRET";
+const MIN_SECRET_LENGTH = 32;
+const EXPIRES_PATTERN = /^[1-9]\d{0,15}$/;
+const SIGNATURE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+var AttachmentUrlSigner = class {
+	secret;
+	now;
+	constructor(secret, now = Date.now) {
+		this.secret = secret;
+		this.now = now;
+	}
+	sign(hash, documentId, ttlSeconds) {
+		const expires = Math.floor(this.now() / 1e3) + ttlSeconds;
+		return {
+			query: new URLSearchParams({
+				documentId,
+				expires: String(expires),
+				signature: this.mac(hash, documentId, String(expires))
+			}).toString(),
+			expiresAtUtc: (/* @__PURE__ */ new Date(expires * 1e3)).toISOString()
+		};
+	}
+	verify(hash, documentId, expires, signature) {
+		if (!EXPIRES_PATTERN.test(expires) || !SIGNATURE_PATTERN.test(signature)) return false;
+		if (Number(expires) * 1e3 <= this.now()) return false;
+		const expected = Buffer.from(this.mac(hash, documentId, expires));
+		const presented = Buffer.from(signature);
+		return expected.length === presented.length && timingSafeEqual(expected, presented);
+	}
+	mac(hash, documentId, expires) {
+		return createHmac("sha256", this.secret).update(JSON.stringify([
+			"attachment-download/v1",
+			hash,
+			documentId,
+			expires
+		])).digest("base64url");
+	}
+};
+function resolveAttachmentUrlSigning(env = process.env) {
+	const secret = env[ATTACHMENT_URL_SIGNING_SECRET_ENV];
+	if (secret !== void 0) {
+		if (secret.trim() !== secret || secret.length < MIN_SECRET_LENGTH) throw new Error(`${ATTACHMENT_URL_SIGNING_SECRET_ENV} must be at least ${MIN_SECRET_LENGTH} characters with no leading or trailing whitespace`);
+		return {
+			status: "configured",
+			signer: new AttachmentUrlSigner(secret)
+		};
+	}
+	if (env.NODE_ENV === "production") return { status: "unconfigured" };
+	return {
+		status: "ephemeral",
+		signer: new AttachmentUrlSigner(randomBytes(32))
+	};
+}
+//#endregion
 //#region src/attachments/index.ts
-function registerAttachmentRoutes(api) {
-	const { attachments } = api;
+const logger$1 = childLogger(["switchboard", "attachments"]);
+function registerAttachmentRoutes(api, options = {}) {
+	const { attachments, attachmentAccess } = api;
+	const urlSigner = options.urlSigner === void 0 ? signerFromEnvironment(attachments.backend?.kind ?? "filesystem") : options.urlSigner;
 	mountAuthenticatedNodeRoute(api, "POST", "/attachments/reservations", makeReserveHandler(attachments));
 	mountAuthenticatedNodeRoute(api, "GET", "/attachments/reservations/:reservationId", makeGetReservationHandler(attachments));
 	mountAuthenticatedNodeRoute(api, "DELETE", "/attachments/reservations/:reservationId", makeDeleteReservationHandler(attachments));
 	mountAuthenticatedNodeRoute(api, "PUT", "/attachments/reservations/:reservationId", makeUploadHandler(attachments));
-	mountAuthenticatedNodeRoute(api, "HEAD", "/attachments/:hash", makeStatHandler(attachments));
-	mountAuthenticatedNodeRoute(api, "GET", "/attachments/:hash/download-target", makeDownloadTargetHandler(attachments, api.attachmentAccess), { allowAnonymous: true });
-	mountAuthenticatedNodeRoute(api, "GET", "/attachments/:hash", makeDownloadHandler(attachments));
+	mountAuthenticatedNodeRoute(api, "HEAD", "/attachments/:hash", makeStatHandler(attachments, attachmentAccess, urlSigner), { allowAnonymous: true });
+	mountAuthenticatedNodeRoute(api, "GET", "/attachments/:hash/download-target", makeDownloadTargetHandler(attachments, attachmentAccess, urlSigner), { allowAnonymous: true });
+	mountAuthenticatedNodeRoute(api, "GET", "/attachments/:hash", makeDownloadHandler(attachments, attachmentAccess, urlSigner), { allowAnonymous: true });
+}
+function signerFromEnvironment(backend) {
+	const signing = resolveAttachmentUrlSigning();
+	if (signing.status === "unconfigured") {
+		if (backend === "filesystem") logger$1.error(`${ATTACHMENT_URL_SIGNING_SECRET_ENV} is not set: filesystem attachment download targets are refused until it is`);
+		return null;
+	}
+	if (signing.status === "ephemeral" && backend === "filesystem") logger$1.warn(`${ATTACHMENT_URL_SIGNING_SECRET_ENV} is not set: signing attachment download URLs with a per-process secret`);
+	return signing.signer;
 }
 //#endregion
 //#region src/attachment-reference-read-model.mts
@@ -1357,8 +1497,7 @@ async function assertWorkflowPackageLoadable(load = () => import("@powerhousedao
 }
 function readAssertion(authorizationService, reactorClient) {
 	const resolveCanonical = createCanonicalDocumentIdResolver(reactorClient);
-	return async (identifier, caller) => {
-		const ctx = caller;
+	const hostCanRead = async (identifier, ctx) => {
 		if (authorizationService.isSupremeAdmin(ctx.user?.address)) return;
 		if (authorizationService.config.policy !== AuthorizationPolicy.DOCUMENT_PERMISSIONS) throw new ForbiddenError();
 		let documentId;
@@ -1369,6 +1508,17 @@ function readAssertion(authorizationService, reactorClient) {
 		}
 		if (!await authorizationService.canRead(documentId, ctx.user?.address)) throw new ForbiddenError("to read this document");
 	};
+	return async (identifier, caller) => {
+		const ctx = caller;
+		await hostCanRead(identifier, ctx);
+		let served;
+		try {
+			served = await reactorClient.isServed(identifier, { subject: callerSubject(ctx.user) });
+		} catch {
+			throw new ForbiddenError();
+		}
+		if (!served) throw new ForbiddenError("to read this document");
+	};
 }
 /** The same, for a design-time call that writes what it names. */
 function writeAssertion(authorizationService, reactorClient) {
@@ -1446,6 +1596,7 @@ async function composeWorkflowRuntime(deps) {
 		relationalDb: deps.relationalDb,
 		reactorClient: deps.reactorClient,
 		assertCanRead: readAssertion(deps.authorizationService, deps.reactorClient),
+		subjectOf: (caller) => callerSubject(caller.user),
 		assertCanWrite: writeAssertion(deps.authorizationService, deps.reactorClient),
 		webhooks: deps.webhooks,
 		attachments: deps.attachments,
@@ -2215,10 +2366,15 @@ async function initServer(serverPort, options, renown, renownConfig) {
 	}
 	if (driveNodeView) {
 		graphqlManager.setAdditionalContextFields({ readModel: driveNodeView });
+		const authorizationService = graphqlManager.getAuthorizationService();
 		const reactorDriveSubgraph = {
 			name: "reactor-drive",
 			path: graphqlManager.getBasePath(),
-			resolvers: createReactorDriveResolvers(),
+			resolvers: createReactorDriveResolvers({
+				reactorClient: client,
+				readModel: driveNodeView,
+				hostCanRead: (documentId, address) => authorizationService.canRead(documentId, address)
+			}),
 			typeDefs: reactorDriveSubgraphTypeDefs,
 			reactorClient: client,
 			relationalDb: void 0
@@ -2334,5 +2490,5 @@ if (import.meta.main) await startSwitchboard({ fatalErrorShutdown: true });
 //#endregion
 export { parseForcePgVersion as a, applySwitchboardReactorDefaults as i, isPortAvailable as n, startSwitchboard as r, deriveAttachmentServiceConfig as t };
 
-//# sourceMappingURL=server-C3WaP3kE.mjs.map
-//# debugId=8174bb20-5463-598a-9c2d-44a8760037a5
+//# sourceMappingURL=server-DQCIIJzK.mjs.map
+//# debugId=3a84ab97-af9a-5a44-94fa-3b59ffe5eed8