@powerhousedao/switchboard 6.2.2-dev.16 → 6.2.2-dev.17

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 6.2.2-dev.17 (2026-07-26)
+
+### 🚀 Features
+
+- **attachments:** S3-compatible storage, direct transfers, and document-derived authorization ([#2884](https://github.com/powerhouse-inc/powerhouse/pull/2884))
+
+### ❤️ Thank You
+
+- Guillermo Puente Sandoval @gpuente
+
 ## 6.2.2-dev.16 (2026-07-25)
 
 ### 🩹 Fixes

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]="5a65c537-fadb-5705-95c0-4cec44d7b4d2")}catch(e){}}();
-import { a as parseForcePgVersion, r as startSwitchboard } from "./server-Cgud_ONM.mjs";
+import { a as parseForcePgVersion, r as startSwitchboard } from "./server-ChK0GLG8.mjs";
 import "./utils-Baw7rThP.mjs";
 import { metrics } from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

package/dist/{server-Cgud_ONM.mjs → server-ChK0GLG8.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]="5eb0a978-689a-51dd-978a-cd3d7fe5df4b")}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]="b1867ed0-059f-587c-9a5f-677da3666de7")}catch(e){}}();
 import { n as addDefaultReactorDrive, r as isPostgresUrl, t as addDefaultDrive } from "./utils-Baw7rThP.mjs";
 import { register } from "node:module";
 import * as Sentry from "@sentry/node";
@@ -10,10 +10,10 @@ import { existsSync, promises, realpathSync } from "node:fs";
 import path from "node:path";
 import { ReactorInstrumentation } from "@powerhousedao/opentelemetry-instrumentation-reactor";
 import { AtomicNodeFs } from "@powerhousedao/pglite-fs";
-import { ChannelScheme, DriveCollectionId, EventBus, REACTOR_SCHEMA, ReactorBuilder, ReactorClientBuilder, parseDriveUrl } from "@powerhousedao/reactor";
+import { ChannelScheme, DriveCollectionId, EventBus, REACTOR_SCHEMA, ReactorBuilder, ReactorClientBuilder, parseDriveUrl, supportsLiveReadModelRegistration } from "@powerhousedao/reactor";
 import { HttpPackageLoader, ImportPackageLoader, PackageManagementService, PackagesSubgraph, getUniqueDocumentModels, initializeAndStartAPI } from "@powerhousedao/reactor-api";
 import { httpsHooksPath } from "@powerhousedao/reactor-api/https-hooks";
-import { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, HashMismatch, InvalidAttachmentRef, ReservationNotFound, SizeMismatch, UploadTooLarge, createRemoteAttachmentService } from "@powerhousedao/reactor-attachments";
+import { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, AttachmentReferenceReadModel, AttachmentSchemaCompiler, HashMismatch, InvalidAttachmentRef, ReservationNotFound, SizeMismatch, UploadTooLarge, createRef, createRemoteAttachmentService, parseAttachmentDownloadTarget } from "@powerhousedao/reactor-attachments";
 import { DriveNodeView, NodeProcessor, ReactorDriveClient, createReactorDriveResolvers, reactorDriveDocumentModelModule, reactorDriveSubgraphTypeDefs } from "@powerhousedao/reactor-drive";
 import { Kysely, PostgresDialect } from "kysely";
 import net from "node:net";
@@ -64,13 +64,20 @@ async function loadPgDump(major) {
 }
 //#endregion
 //#region src/attachments/auth.ts
+const ANONYMOUS_ACTOR = {
+	user: void 0,
+	authEnabled: false
+};
 /**
 * Wrap a Node-style handler so that, when `authService` is provided and auth is
-* enabled, the request must carry a verifiable Bearer token.
+* enabled, the request must carry a verifiable Bearer token. The handler always
+* receives an actor context: the verified bearer user when auth is enabled, or
+* the anonymous context when it is disabled. With `allowAnonymous`, a missing
+* bearer yields an anonymous actor with `authEnabled: true` instead of a 401.
 */
-function requireAuth(authService, handler) {
-	if (!authService) return handler;
-	return async (req, res) => {
+function requireAuth(authService, handler, options) {
+	if (!authService) return (req, res, body) => handler(req, res, body, ANONYMOUS_ACTOR);
+	return async (req, res, body) => {
 		let result;
 		try {
 			result = await authService.verifyBearer(req.headers.authorization);
@@ -88,25 +95,32 @@ function requireAuth(authService, handler) {
 			res.end(body);
 			return;
 		}
-		if (result.auth_enabled && !result.user) {
+		if (result.auth_enabled && !result.user && !options?.allowAnonymous) {
 			res.statusCode = 401;
 			res.setHeader("Content-Type", "application/json");
 			res.end(JSON.stringify({ error: "Authentication required" }));
 			return;
 		}
-		await handler(req, res);
+		await handler(req, res, body, {
+			user: result.user,
+			authEnabled: result.auth_enabled
+		});
 	};
 }
 //#endregion
 //#region src/attachments/mount-auth.ts
 /**
 * Mount a Node-style attachment route with `requireAuth` applied unconditionally.
-* When `api.authService` is undefined (auth disabled), `requireAuth` returns the
-* handler unchanged — that is the only way to opt out. To register a route
-* without auth wrapping you must call `api.httpAdapter.mountNodeRoute` directly.
+* When `api.authService` is undefined (auth disabled), the handler still runs
+* through `requireAuth` and receives the anonymous actor context — that is the
+* only way to opt out of bearer verification. To register a route without auth
+* wrapping you must call `api.httpAdapter.mountNodeRoute` directly.
+*
+* `allowAnonymous` is reserved for routes whose handlers make a per-document
+* authorization decision themselves; identity-only routes must not use it.
 */
-function mountAuthenticatedNodeRoute(api, method, path, handler) {
-	api.httpAdapter.mountNodeRoute(method, path, requireAuth(api.authService, handler));
+function mountAuthenticatedNodeRoute(api, method, path, handler, options) {
+	api.httpAdapter.mountNodeRoute(method, path, requireAuth(api.authService, handler, options));
 }
 //#endregion
 //#region src/attachments/routes.ts
@@ -216,7 +230,8 @@ function makeReserveHandler(attachments) {
 		sendJson(res, 201, {
 			reservationId: upload.reservationId,
 			ref: upload.ref,
-			expiresAtUtc: upload.expiresAtUtc
+			expiresAtUtc: upload.expiresAtUtc,
+			...upload.uploadTarget ? { uploadTarget: upload.uploadTarget } : {}
 		});
 	};
 }
@@ -227,6 +242,10 @@ function makeUploadHandler(attachments) {
 			sendError(res, 400, "Missing reservationId");
 			return;
 		}
+		if (attachments.backend?.kind === "s3") {
+			sendError(res, 405, "Use the reservation uploadTarget for S3 uploads");
+			return;
+		}
 		let reservation;
 		try {
 			reservation = await attachments.reservations.get(reservationId);
@@ -373,6 +392,144 @@ function makeDeleteReservationHandler(attachments) {
 function extractParam(req, name) {
 	return req.params?.[name];
 }
+const MAX_DOCUMENT_ID_LEN = 512;
+const ATTACHMENT_NOT_FOUND_BODY = { error: "Attachment not found" };
+const MAX_DOWNLOAD_TARGET_TTL_SECONDS = 10080 * 60;
+/**
+* Returns the single `documentId` query value, or null when it is missing,
+* duplicated, blank, or oversized. Validation happens before authorization so
+* malformed requests never reach the access service.
+*/
+function extractSingleDocumentId(req) {
+	if (!req.url) return null;
+	let url;
+	try {
+		url = new URL(req.url, "http://switchboard.invalid");
+	} catch {
+		return null;
+	}
+	const values = url.searchParams.getAll("documentId");
+	if (values.length !== 1) return null;
+	const value = values[0];
+	if (value.trim().length === 0 || value.length > MAX_DOCUMENT_ID_LEN) return null;
+	return value;
+}
+/**
+* Returns the requested target TTL in seconds: undefined when absent,
+* "invalid" when malformed (duplicated, non-integer, or non-positive), and
+* otherwise the value clamped to the presigning ceiling.
+*/
+function extractExpiresIn(req) {
+	if (!req.url) return void 0;
+	let url;
+	try {
+		url = new URL(req.url, "http://switchboard.invalid");
+	} catch {
+		return;
+	}
+	const values = url.searchParams.getAll("expiresIn");
+	if (values.length === 0) return void 0;
+	if (values.length > 1) return "invalid";
+	const parsed = Number(values[0]);
+	if (!Number.isInteger(parsed) || parsed <= 0) return "invalid";
+	return Math.min(parsed, MAX_DOWNLOAD_TARGET_TTL_SECONDS);
+}
+/**
+* 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.
+*/
+function requestBaseUrl(req) {
+	const forwardedProto = req.headers["x-forwarded-proto"];
+	const proto = (Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto)?.split(",")[0]?.trim() || (req.socket.encrypted ? "https" : "http");
+	const forwardedHost = req.headers["x-forwarded-host"];
+	const host = (Array.isArray(forwardedHost) ? forwardedHost[0] : forwardedHost) ?? req.headers.host;
+	if (!host) return null;
+	return `${proto}://${host}`;
+}
+function makeDownloadTargetHandler(attachments, attachmentAccess) {
+	return async (req, res, _body, actor) => {
+		res.setHeader("Cache-Control", "no-store");
+		const hash = extractParam(req, "hash");
+		if (!hash || !HASH_PATTERN.test(hash)) {
+			sendError(res, 400, "Invalid attachment hash");
+			return;
+		}
+		const documentId = extractSingleDocumentId(req);
+		if (documentId === null) {
+			sendError(res, 400, "documentId is required exactly once as a non-empty query parameter");
+			return;
+		}
+		const expiresIn = extractExpiresIn(req);
+		if (expiresIn === "invalid") {
+			sendError(res, 400, "expiresIn must be a single positive integer number of seconds");
+			return;
+		}
+		const canonicalHash = hash.toLowerCase();
+		let decision;
+		try {
+			decision = await attachmentAccess.canReadAttachment({
+				documentId,
+				attachmentRef: createRef(canonicalHash),
+				userAddress: actor?.user?.address
+			});
+		} catch (err) {
+			logger$1.error("Attachment access decision failed: @error", err);
+			sendError(res, 500, "Internal error");
+			return;
+		}
+		if (decision.kind === "projection-unavailable") {
+			sendError(res, 503, "Attachment downloads are temporarily unavailable");
+			return;
+		}
+		if (decision.kind === "denied") {
+			sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+			return;
+		}
+		let header;
+		try {
+			header = await attachments.store.stat(canonicalHash);
+		} catch (err) {
+			if (err instanceof AttachmentNotFound) {
+				sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+				return;
+			}
+			logger$1.error("Attachment metadata lookup failed: @error", err);
+			sendError(res, 500, "Internal error");
+			return;
+		}
+		if (header.status !== "available") {
+			sendJson(res, 404, ATTACHMENT_NOT_FOUND_BODY);
+			return;
+		}
+		let target;
+		if (attachments.backend && attachments.backend.kind !== "filesystem") try {
+			target = await attachments.backend.prepareDownloadTarget(canonicalHash, expiresIn);
+		} catch {
+			sendError(res, 502, "Attachment download target unavailable");
+			return;
+		}
+		else {
+			const base = requestBaseUrl(req);
+			if (!base) {
+				sendError(res, 500, "Internal error");
+				return;
+			}
+			try {
+				target = parseAttachmentDownloadTarget({
+					kind: "switchboard",
+					method: "GET",
+					url: `${base}/attachments/${canonicalHash}`,
+					headers: {}
+				});
+			} catch {
+				sendError(res, 500, "Internal error");
+				return;
+			}
+		}
+		sendJson(res, 200, target);
+	};
+}
 //#endregion
 //#region src/attachments/index.ts
 function registerAttachmentRoutes(api) {
@@ -382,9 +539,50 @@ function registerAttachmentRoutes(api) {
 	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));
 }
 //#endregion
+//#region src/attachment-reference-read-model.mts
+const attachmentSchemaCompiler = new AttachmentSchemaCompiler();
+function createAttachmentReferenceReadModel(baseKysely, dependencies, attachmentReferenceWriter) {
+	return new AttachmentReferenceReadModel(baseKysely.withSchema(REACTOR_SCHEMA), dependencies.operationIndex, dependencies.writeCache, dependencies.processorManagerConsistencyTracker, dependencies.documentModelRegistry, attachmentSchemaCompiler, attachmentReferenceWriter);
+}
+function registerAttachmentReferenceReadModel(reactorBuilder, registration) {
+	reactorBuilder.withReadModelFactory(async ({ documentModelRegistry, operationIndex, writeCache, processorManagerConsistencyTracker }) => {
+		const readModel = createAttachmentReferenceReadModel(registration.baseKysely, {
+			operationIndex,
+			writeCache,
+			processorManagerConsistencyTracker,
+			documentModelRegistry
+		}, registration.attachmentReferenceWriter);
+		await readModel.init();
+		return readModel;
+	});
+}
+async function registerAttachmentReferenceReadModelOnModule(clientModule, attachmentReferenceWriter) {
+	const reactorModule = clientModule.reactorModule;
+	if (!reactorModule) return {
+		status: "unavailable",
+		reason: "in-process-reactor-module-unavailable"
+	};
+	const coordinator = reactorModule.readModelCoordinator;
+	if (!supportsLiveReadModelRegistration(coordinator)) return {
+		status: "unavailable",
+		reason: "live-read-model-registration-unsupported"
+	};
+	const readModel = createAttachmentReferenceReadModel(reactorModule.database, {
+		operationIndex: reactorModule.operationIndex,
+		writeCache: reactorModule.writeCache,
+		processorManagerConsistencyTracker: reactorModule.processorManagerConsistencyTracker,
+		documentModelRegistry: reactorModule.documentModelRegistry
+	}, attachmentReferenceWriter);
+	await readModel.init();
+	coordinator.addReadModel(readModel, "pre_ready");
+	await readModel.init();
+	return { status: "available" };
+}
+//#endregion
 //#region src/builder-defaults.mts
 /**
 * Apply switchboard's standard configuration to a reactor + client builder
@@ -911,13 +1109,17 @@ async function initServer(serverPort, options, renown) {
 		});
 	}
 	const reactorLogger = logger.child(["reactor"]);
-	const initializeClient = async (documentModels) => {
+	const initializeClient = async (documentModels, { attachmentReferenceWriter }) => {
 		if (options.reactor) {
+			const attachmentReferenceProjection = await registerAttachmentReferenceReadModelOnModule(options.reactor, attachmentReferenceWriter);
 			if (options.reactor.reactorModule) {
 				new ReactorInstrumentation(options.reactor.reactorModule).start();
 				reactorLogger.info("Reactor metrics instrumentation started (using caller-provided reactor)");
 			}
-			return { module: options.reactor };
+			return {
+				module: options.reactor,
+				attachmentReferenceProjection
+			};
 		}
 		const baseKysely = await createReactorKysely({
 			reactorDbUrl,
@@ -955,6 +1157,10 @@ async function initServer(serverPort, options, renown) {
 			await nodeProcessor.init();
 			return nodeProcessor;
 		});
+		registerAttachmentReferenceReadModel(reactorBuilder, {
+			baseKysely,
+			attachmentReferenceWriter
+		});
 		reactorBuilder.withShutdownHook(async () => {
 			if (apiRef.current) await apiRef.current.dispose();
 		});
@@ -969,7 +1175,8 @@ async function initServer(serverPort, options, renown) {
 			reactorDriveClient: new ReactorDriveClient({
 				reactor: module.client,
 				readModel: driveNodeView
-			})
+			}),
+			attachmentReferenceProjection: { status: "available" }
 		};
 	};
 	let defaultDriveUrl = void 0;
@@ -1100,6 +1307,7 @@ async function initServer(serverPort, options, renown) {
 		api,
 		reactor: client,
 		attachmentService,
+		attachmentReferenceProjection: api.attachmentReferenceProjection,
 		renown,
 		port: serverPort,
 		shutdown: () => api.dispose()
@@ -1157,5 +1365,5 @@ if (import.meta.main) await startSwitchboard();
 //#endregion
 export { parseForcePgVersion as a, applySwitchboardReactorDefaults as i, isPortAvailable as n, startSwitchboard as r, deriveAttachmentServiceConfig as t };
 
-//# sourceMappingURL=server-Cgud_ONM.mjs.map
-//# debugId=5eb0a978-689a-51dd-978a-cd3d7fe5df4b
+//# sourceMappingURL=server-ChK0GLG8.mjs.map
+//# debugId=b1867ed0-059f-587c-9a5f-677da3666de7