@powerhousedao/reactor-attachments 6.2.2-dev.9 → 6.2.2-staging.0

package/dist/{null-attachment-transport-Drx03s02.js → null-attachment-transport-CrsUafCi.js}

@@ -90,16 +90,20 @@ var SizeMismatch = class extends Error {
 	}
 };
 /**
-* Thrown by get() when the hash is reserved by an in-flight upload and
-* bytes are not yet available anywhere. Deliberately NOT a subclass of
-* AttachmentNotFound -- callers must distinguish "retry later" from "unknown".
-* After expiresAtUtc has passed the hash reads as not found.
-*
-* metadata is populated when the reservation is local and its fields are
-* known (mimeType, fileName, sizeBytes). It is undefined when the pending
-* state is learned from a remote transport that did not supply the full
-* Attachment-Pending header (transport-pending / degraded wire case).
+* Thrown when a remote transfer step fails. Identifies the stage only; it
+* intentionally carries no URL, signature query, bucket key, or bearer
+* material so it is always safe to log or surface.
 */
+var AttachmentTransferError = class extends Error {
+	stage;
+	status;
+	constructor(stage, status) {
+		super(status === void 0 ? `Attachment ${stage} request failed` : `Attachment ${stage} request failed with status ${status}`);
+		this.name = "AttachmentTransferError";
+		this.stage = stage;
+		this.status = status;
+	}
+};
 var AttachmentPending = class extends Error {
 	hash;
 	expiresAtUtc;
@@ -113,6 +117,107 @@ var AttachmentPending = class extends Error {
 	}
 };
 //#endregion
+//#region src/targets.ts
+function isRecord$4(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseUrl(value) {
+	if (typeof value !== "string" || value.length === 0) throw new Error("Attachment target URL must be a non-empty string");
+	if (value.trim() !== value || hasForbiddenUrlWhitespace(value)) throw new Error("Attachment target URL must not contain raw whitespace");
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new Error("Attachment target URL is invalid");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "") throw new Error("Attachment target URL must be HTTP(S) and must not contain credentials");
+	return value;
+}
+function parseHeaders(value) {
+	if (!isRecord$4(value)) throw new Error("Attachment target headers must be an object");
+	const headers = Object.create(null);
+	const headerName = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+	for (const [name, headerValue] of Object.entries(value)) {
+		if (!headerName.test(name)) throw new Error(`Attachment target header name is invalid: ${name}`);
+		if (typeof headerValue !== "string" || hasForbiddenHeaderCharacter(headerValue)) throw new Error(`Attachment target header value is invalid: ${name}`);
+		headers[name] = headerValue;
+	}
+	return headers;
+}
+function hasForbiddenHeaderCharacter(value) {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 8 || code >= 10 && code <= 31 || code === 127 || code > 255) return true;
+	}
+	return false;
+}
+function hasForbiddenUrlWhitespace(value) {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 32 || code === 127) return true;
+	}
+	return false;
+}
+function parseExpiry(value, required) {
+	if (value === void 0 && !required) return void 0;
+	if (typeof value !== "string") throw new Error("Attachment target expiry must be an ISO 8601 UTC string");
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== value) throw new Error("Attachment target expiry must be an ISO 8601 UTC string");
+	return value;
+}
+function parseAttachmentUploadTarget(value) {
+	if (!isRecord$4(value)) throw new Error("Attachment upload target must be an object");
+	const url = parseUrl(value.url);
+	const headers = parseHeaders(value.headers);
+	switch (value.kind) {
+		case "switchboard":
+			if (value.method !== "PUT") throw new Error("Switchboard upload target method must be PUT");
+			return {
+				kind: "switchboard",
+				method: "PUT",
+				url,
+				headers,
+				...value.expiresAtUtc === void 0 ? {} : { expiresAtUtc: parseExpiry(value.expiresAtUtc, false) }
+			};
+		case "presigned-put":
+			if (value.method !== "PUT") throw new Error("Presigned upload target method must be PUT");
+			return {
+				kind: "presigned-put",
+				method: "PUT",
+				url,
+				headers,
+				expiresAtUtc: parseExpiry(value.expiresAtUtc, true)
+			};
+		default: throw new Error("Attachment upload target kind is unknown");
+	}
+}
+function parseAttachmentDownloadTarget(value) {
+	if (!isRecord$4(value)) throw new Error("Attachment download target must be an object");
+	const url = parseUrl(value.url);
+	const headers = parseHeaders(value.headers);
+	switch (value.kind) {
+		case "switchboard":
+			if (value.method !== "GET") throw new Error("Switchboard download target method must be GET");
+			return {
+				kind: "switchboard",
+				method: "GET",
+				url,
+				headers,
+				...value.expiresAtUtc === void 0 ? {} : { expiresAtUtc: parseExpiry(value.expiresAtUtc, false) }
+			};
+		case "presigned-get":
+			if (value.method !== "GET") throw new Error("Presigned download target method must be GET");
+			return {
+				kind: "presigned-get",
+				method: "GET",
+				url,
+				headers,
+				expiresAtUtc: parseExpiry(value.expiresAtUtc, true)
+			};
+		default: throw new Error("Attachment download target kind is unknown");
+	}
+}
+//#endregion
 //#region src/ref.ts
 const REF_PATTERN = /^attachment:\/\/v(\d+):(.+)$/;
 const DEFAULT_VERSION = 1;
@@ -131,13 +236,15 @@ function createRef(hash, version = DEFAULT_VERSION) {
 //#region src/attachment-service.ts
 const CLIENT_HASH_PATTERN = /^[a-f0-9]{64}$/;
 var AttachmentService = class {
-	constructor(store, reservations, uploadFactory) {
+	constructor(store, reservations, uploadFactory, backend) {
 		this.store = store;
 		this.reservations = reservations;
 		this.uploadFactory = uploadFactory;
+		this.backend = backend;
 	}
 	async reserve(options) {
 		if (options.clientHash !== void 0) return this.reserveHashFirst(options);
+		if (this.backend?.kind === "s3") throw new Error("S3 attachment reservations require a client hash");
 		const reservation = await this.reservations.create(options);
 		return this.uploadFactory.createUpload(reservation);
 	}
@@ -145,9 +252,16 @@ var AttachmentService = class {
 		const { hash } = parseRef(ref);
 		return this.store.stat(hash);
 	}
-	async get(ref, signal) {
+	async get(ref, options) {
 		const { hash } = parseRef(ref);
-		return this.store.get(hash, signal);
+		const normalized = options === void 0 || options instanceof AbortSignal ? { signal: options } : options;
+		return normalized.documentId === void 0 ? this.store.get(hash, normalized.signal) : this.store.get(hash, normalized.signal, normalized.documentId);
+	}
+	getDownloadTarget(ref, options) {
+		const { hash } = parseRef(ref);
+		const getTarget = this.store.getDownloadTarget?.bind(this.store);
+		if (getTarget === void 0) return Promise.reject(/* @__PURE__ */ new Error("Download targets are not supported by this attachment store: only remote stores negotiate direct URLs"));
+		return getTarget(hash, options);
 	}
 	async reserveHashFirst(options) {
 		const normalized = options.clientHash.toLowerCase();
@@ -163,9 +277,18 @@ var AttachmentService = class {
 		} catch (err) {
 			if (!(err instanceof AttachmentNotFound) && !(err instanceof AttachmentPending)) throw err;
 		}
-		if (existingHeader !== null && existingHeader.status === "available") throw new AttachmentAlreadyExists(normalized, createRef(normalized));
+		if (existingHeader !== null) {
+			if (this.backend?.kind === "s3") {
+				if (await this.backend.exists(normalized)) throw new AttachmentAlreadyExists(normalized, createRef(normalized));
+			} else if (existingHeader.status === "available") throw new AttachmentAlreadyExists(normalized, createRef(normalized));
+		}
 		const reservation = await this.reservations.create(normalizedOptions);
-		return this.uploadFactory.createUpload(reservation);
+		if (this.backend?.kind !== "s3") return this.uploadFactory.createUpload(reservation);
+		const uploadTarget = await this.backend.prepareUploadTarget(reservation);
+		return this.uploadFactory.createUpload({
+			...reservation,
+			uploadTarget
+		});
 	}
 };
 //#endregion
@@ -302,6 +425,115 @@ function contentTypeFallback$1(response) {
 	};
 }
 //#endregion
+//#region src/switchboard/upload-transport.ts
+/**
+* The default transport. Ignores `onProgress` — fetch has no upload-side
+* progress event, and silence is how a transport reports that bytes are
+* unobservable.
+*/
+function createFetchUploadTransport(fetchFn) {
+	return (request) => fetchFn(request.url, {
+		method: request.method,
+		headers: request.headers,
+		body: request.body,
+		...request.signal ? { signal: request.signal } : {}
+	});
+}
+//#endregion
+//#region src/switchboard/xhr-upload-transport.ts
+/**
+* Upload transport backed by `XMLHttpRequest`, the only browser API that
+* reports upload-side byte progress (`xhr.upload.onprogress`). Everything else
+* about the request is identical to the fetch path.
+*
+* Capability detection happens **inside** the returned function, never at
+* module load: this module is reachable from the client entry, which is
+* executed in Node by the entrypoint tests, and Node has no
+* `XMLHttpRequest`. Detecting per call also means a test can install a fake on
+* `globalThis` without any module-registry reset.
+*/
+function createXhrUploadTransport(options) {
+	return (request) => {
+		const XhrCtor = globalThis.XMLHttpRequest;
+		if (typeof XhrCtor !== "function") return createFetchUploadTransport((options?.fetchFn ?? globalThis.fetch).bind(globalThis))(request);
+		return sendWithXhr(new XhrCtor(), request);
+	};
+}
+/**
+* Mirrors fetch's observable behavior closely enough that
+* `RemoteAttachmentUpload` cannot tell the two apart:
+*
+* - `responseType` is left at `""`, so a non-JSON 422 body still reaches the
+*   caller's `json()` and fails there rather than being swallowed.
+* - status 0 never resolves. XHR reports 0 for network failure, CORS refusal
+*   and abort alike; resolving it would fabricate a transfer error claiming
+*   the provider answered 0.
+* - failures reject with fetch's error shapes: `TypeError` for network,
+*   `AbortError` for abort.
+*/
+function sendWithXhr(xhr, request) {
+	return new Promise((resolve, reject) => {
+		const signal = request.signal;
+		let settled = false;
+		const abortListener = () => xhr.abort();
+		const detach = () => signal?.removeEventListener("abort", abortListener);
+		const succeed = (response) => {
+			if (settled) return;
+			settled = true;
+			detach();
+			resolve(response);
+		};
+		const fail = (error) => {
+			if (settled) return;
+			settled = true;
+			detach();
+			reject(error);
+		};
+		if (signal?.aborted) {
+			fail(abortError());
+			return;
+		}
+		xhr.open(request.method, request.url, true);
+		for (const [name, value] of Object.entries(request.headers)) xhr.setRequestHeader(name, value);
+		if (request.onProgress) xhr.upload.addEventListener("progress", (event) => {
+			if (!event.lengthComputable) return;
+			request.onProgress?.(event.loaded, event.total);
+		});
+		xhr.addEventListener("load", () => {
+			if (xhr.status === 0) {
+				fail(networkError());
+				return;
+			}
+			succeed(toResponse(xhr));
+		});
+		xhr.addEventListener("error", () => fail(networkError()));
+		xhr.addEventListener("timeout", () => fail(networkError()));
+		xhr.addEventListener("abort", () => fail(abortError()));
+		signal?.addEventListener("abort", abortListener);
+		xhr.send(request.body);
+	});
+}
+function toResponse(xhr) {
+	return {
+		status: xhr.status,
+		statusText: xhr.statusText,
+		ok: xhr.status >= 200 && xhr.status < 300,
+		json: () => {
+			try {
+				return Promise.resolve(JSON.parse(xhr.responseText));
+			} catch (err) {
+				return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+			}
+		}
+	};
+}
+function networkError() {
+	return /* @__PURE__ */ new TypeError("Failed to fetch");
+}
+function abortError() {
+	return new DOMException("The operation was aborted", "AbortError");
+}
+//#endregion
 //#region src/switchboard/remote-reservation-store.ts
 function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -393,7 +625,8 @@ var RemoteReservationStore = class {
 			createdAtUtc: body.createdAtUtc ?? now.toISOString(),
 			expiresAtUtc: body.expiresAtUtc ?? new Date(now.getTime() + 1440 * 60 * 1e3).toISOString(),
 			clientHash: options.clientHash ?? null,
-			sizeBytes: options.sizeBytes ?? null
+			sizeBytes: options.sizeBytes ?? null,
+			...body.uploadTarget === void 0 ? {} : { uploadTarget: parseAttachmentUploadTarget(body.uploadTarget) }
 		};
 	}
 	async get(reservationId) {
@@ -417,7 +650,8 @@ var RemoteReservationStore = class {
 			createdAtUtc: parsed.createdAtUtc,
 			expiresAtUtc: parsed.expiresAtUtc,
 			clientHash: parsed.clientHash ?? null,
-			sizeBytes: parsed.sizeBytes ?? null
+			sizeBytes: parsed.sizeBytes ?? null,
+			...parsed.uploadTarget === void 0 ? {} : { uploadTarget: parseAttachmentUploadTarget(parsed.uploadTarget) }
 		};
 	}
 	async delete(reservationId) {
@@ -442,28 +676,36 @@ var RemoteAttachmentUpload = class {
 	reservationId;
 	ref;
 	expiresAtUtc;
+	uploadTarget;
+	reservation;
 	remoteUrl;
 	jwtHandler;
-	fetchFn;
+	uploadTransport;
 	constructor(reservation, config) {
 		this.reservationId = reservation.reservationId;
 		this.ref = reservation.clientHash !== null ? createRef(reservation.clientHash) : null;
 		this.expiresAtUtc = reservation.expiresAtUtc;
+		if (reservation.uploadTarget) this.uploadTarget = reservation.uploadTarget;
+		this.reservation = reservation;
 		this.remoteUrl = config.remoteUrl;
 		this.jwtHandler = config.jwtHandler;
-		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
+		this.uploadTransport = config.fetchFn ? createFetchUploadTransport(config.fetchFn.bind(globalThis)) : config.uploadTransport ?? createFetchUploadTransport(globalThis.fetch.bind(globalThis));
 	}
-	async send(data) {
+	async send(data, options) {
+		if (this.uploadTarget?.kind === "presigned-put") return this.sendPresigned(this.uploadTarget, data, options);
 		const url = `${this.remoteUrl}/attachments/reservations/${this.reservationId}`;
 		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
 		const body = await new Response(data).blob();
-		const response = await this.fetchFn(url, {
+		const response = await this.uploadTransport({
+			url,
 			method: "PUT",
 			headers: {
 				...authHeaders,
 				"Content-Type": "application/octet-stream"
 			},
-			body
+			body,
+			...options?.onProgress ? { onProgress: (loaded, total) => options.onProgress?.(loaded, total) } : {},
+			...options?.signal ? { signal: options.signal } : {}
 		});
 		if (response.status === 422) {
 			let errorBody;
@@ -481,6 +723,44 @@ var RemoteAttachmentUpload = class {
 		if (!response.ok) throw new Error(`Attachment upload failed: ${response.status} ${response.statusText}`);
 		return await response.json();
 	}
+	/**
+	* Direct provider upload: PUT the bytes to the presigned URL with exactly
+	* the returned headers — never the Switchboard JWT — and treat any 2xx as
+	* final success with no follow-up control request. The result is
+	* synthesized from the hash-first reservation, which is the only path that
+	* can produce a presigned target.
+	*/
+	async sendPresigned(target, data, options) {
+		if (this.reservation.clientHash === null || this.ref === null) throw new Error("Presigned upload targets require a hash-first reservation");
+		const body = await new Response(data).blob();
+		const response = await this.uploadTransport({
+			url: target.url,
+			method: target.method,
+			headers: { ...target.headers },
+			body,
+			...options?.onProgress ? { onProgress: (loaded, total) => options.onProgress?.(loaded, total) } : {},
+			...options?.signal ? { signal: options.signal } : {}
+		});
+		if (!response.ok) throw new AttachmentTransferError("presigned-put", response.status);
+		const hash = this.reservation.clientHash;
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		return {
+			hash,
+			ref: this.ref,
+			header: {
+				hash,
+				mimeType: this.reservation.mimeType,
+				fileName: this.reservation.fileName,
+				sizeBytes: this.reservation.sizeBytes ?? body.size,
+				extension: this.reservation.extension,
+				status: "available",
+				source: "local",
+				createdAtUtc: this.reservation.createdAtUtc || now,
+				lastAccessedAtUtc: now,
+				expiresAtUtc: null
+			}
+		};
+	}
 };
 //#endregion
 //#region src/switchboard/remote-attachment-upload-factory.ts
@@ -603,16 +883,70 @@ var RemoteAttachmentStore = class {
 		if (!response.ok) throw new Error(`Attachment stat failed: ${response.status} ${response.statusText}`);
 		return buildHeader(hash, parseMetadata(response));
 	}
-	async get(hash, signal) {
-		return this.fetchAttachment(hash, signal);
+	async get(hash, signal, documentId) {
+		if (documentId === void 0) return this.fetchAttachment(hash, signal);
+		const target = await this.getDownloadTarget(hash, {
+			documentId,
+			signal
+		});
+		if (target.kind === "presigned-get") return this.fetchPresigned(hash, target, signal);
+		return this.fetchAttachment(hash, signal, target);
 	}
-	async fetchAttachment(hash, signal) {
-		const url = `${this.remoteUrl}/attachments/${hash}`;
+	/**
+	* Asks Switchboard for an authorized download target. The request carries
+	* the JWT; the response is runtime-validated before any byte transfer.
+	* Public so callers can mint direct URLs (previews, share links) without
+	* transferring bytes; `expiresIn` requests a caller-chosen lifetime.
+	*/
+	async getDownloadTarget(hash, options) {
+		const { documentId, expiresIn, signal } = options;
+		const expiry = expiresIn === void 0 ? "" : `&expiresIn=${encodeURIComponent(String(expiresIn))}`;
+		const url = `${this.remoteUrl}/attachments/${hash}/download-target?documentId=${encodeURIComponent(documentId)}${expiry}`;
 		const headers = await buildAuthHeaders(url, this.jwtHandler);
 		const response = await this.fetchFn(url, {
 			signal,
 			headers
 		});
+		if (response.status === 404) throw new AttachmentNotFound(hash);
+		if (!response.ok) throw new AttachmentTransferError("download-target", response.status);
+		let body;
+		try {
+			body = await response.json();
+		} catch {
+			throw new AttachmentTransferError("download-target");
+		}
+		return parseAttachmentDownloadTarget(body);
+	}
+	/**
+	* Executes a presigned GET with exactly the returned headers and no JWT.
+	* A provider 404 means the object is missing despite available metadata
+	* (the accepted abandoned-upload trade-off) and surfaces as the same typed
+	* not-found error callers already handle.
+	*/
+	async fetchPresigned(hash, target, signal) {
+		const response = await this.fetchFn(target.url, {
+			signal,
+			headers: { ...target.headers }
+		});
+		if (response.status === 404) throw new AttachmentNotFound(hash);
+		if (!response.ok) throw new AttachmentTransferError("presigned-get", response.status);
+		if (!response.body) throw new Error("Response body is null");
+		return {
+			header: buildHeader(hash, parseMetadata(response)),
+			body: response.body
+		};
+	}
+	async fetchAttachment(hash, signal, target) {
+		const url = target?.url ?? `${this.remoteUrl}/attachments/${hash}`;
+		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
+		const headers = {
+			...target?.headers,
+			...authHeaders
+		};
+		const response = await this.fetchFn(url, {
+			signal,
+			headers
+		});
 		if (response.status === 202) {
 			const pending = parsePendingExpiry(response);
 			if (!pending) throw new Error("Attachment fetch returned 202 with missing or malformed Attachment-Pending header");
@@ -681,6 +1015,6 @@ var NullAttachmentTransport = class {
 	}
 };
 //#endregion
-export { SizeMismatch as _, RemoteAttachmentUpload as a, AttachmentService as c, AttachmentAlreadyExists as d, AttachmentNotFound as f, ReservationNotFound as g, InvalidAttachmentRef as h, RemoteAttachmentUploadFactory as i, createRef as l, HashMismatch as m, createRemoteAttachmentService as n, RemoteReservationStore as o, AttachmentPending as p, RemoteAttachmentStore as r, SwitchboardAttachmentTransport as s, NullAttachmentTransport as t, parseRef as u, UploadTooLarge as v };
+export { UploadTooLarge as C, SizeMismatch as S, AttachmentPending as _, RemoteAttachmentUpload as a, InvalidAttachmentRef as b, createFetchUploadTransport as c, createRef as d, parseRef as f, AttachmentNotFound as g, AttachmentAlreadyExists as h, RemoteAttachmentUploadFactory as i, SwitchboardAttachmentTransport as l, parseAttachmentUploadTarget as m, createRemoteAttachmentService as n, RemoteReservationStore as o, parseAttachmentDownloadTarget as p, RemoteAttachmentStore as r, createXhrUploadTransport as s, NullAttachmentTransport as t, AttachmentService as u, AttachmentTransferError as v, ReservationNotFound as x, HashMismatch as y };
 
-//# sourceMappingURL=null-attachment-transport-Drx03s02.js.map
+//# sourceMappingURL=null-attachment-transport-CrsUafCi.js.map