@hubfluencer/mcp 0.8.2 → 0.9.0

package/src/uploads.ts

@@ -12,15 +12,18 @@
  * are confined to HUBFLUENCER_INPUT_DIR (or cwd) and an extension allowlist.
  */
 
-import { createReadStream, type ReadStream } from "node:fs";
-import { open, readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { type FileHandle, open, realpath, stat } from "node:fs/promises";
 import { basename, extname, isAbsolute, resolve, sep } from "node:path";
+import { Readable } from "node:stream";
 import type { HubfluencerClient } from "./client.js";
 import {
 	assertSafeFetchUrl,
 	backoffDelayMs,
 	DEFAULT_RETRY,
 	isRetryableNetworkError,
+	isRetryableStatus,
 } from "./core.js";
 import { USER_AGENT } from "./version.js";
 
@@ -58,10 +61,13 @@ const ALLOW_LOOPBACK_FETCH =
 // Mirror the server-side constants (editor_upload.ex / editor_asset_controller.ex)
 // so we fail fast client-side with a clear message instead of after a wasted PUT.
 const MAX_VIDEO_BYTES = 500_000_000; // EditorUpload.@max_upload_bytes
-const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // editor_asset @max_image_size (logos share this inspector)
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+export const MAX_PRODUCT_IMAGE_BYTES = 8 * 1024 * 1024;
+export const MAX_LOGO_BYTES = 1 * 1024 * 1024; // Editor.Logo.@max_logo_bytes
+export const MAX_CLOSING_IMAGE_BYTES = 20 * 1024 * 1024;
 const MULTIPART_THRESHOLD = 50 * 1024 * 1024; // @multipart_min_size — at/above this, use multipart
 const MAX_CATALOG_VIDEO_DURATION_SECONDS = 60; // CatalogAsset video validator
-type FilePutBody = { filePath: string; size: number };
+type FilePutBody = { handle: FileHandle; size: number };
 
 const VIDEO_EXT_MIME: Record<string, string> = {
 	mp4: "video/mp4",
@@ -104,6 +110,95 @@ export interface ResolvedFile {
 	size: number;
 }
 
+export interface PreparedUploadFile extends ResolvedFile {
+	handle: FileHandle;
+	/** Optional pre-side-effect snapshot for bounded buffered uploads. */
+	bytes?: Buffer;
+}
+
+/** Stable identity for the exact pre-side-effect snapshot retained in memory. */
+export function preparedUploadIdentity(file: PreparedUploadFile): string {
+	if (!file.bytes) {
+		throw new Error("Prepared upload has no retained byte snapshot.");
+	}
+	return `${file.size}:${createHash("sha256").update(file.bytes).digest("hex")}`;
+}
+
+/** Fill a positional range despite legal short reads; return early only at EOF. */
+export async function fillPositionalRead(
+	handle: Pick<FileHandle, "read">,
+	buffer: Buffer,
+	offset: number,
+	length: number,
+	position: number,
+): Promise<number> {
+	let filled = 0;
+	while (filled < length) {
+		const { bytesRead } = await handle.read(
+			buffer,
+			offset + filled,
+			length - filled,
+			position + filled,
+		);
+		if (bytesRead === 0) break;
+		filled += bytesRead;
+	}
+	return filled;
+}
+
+async function closeReadHandle(handle: FileHandle): Promise<void> {
+	await handle.close();
+}
+
+/** Reads exactly the size validated at open time; later growth is ignored. */
+async function readValidatedBytes(file: PreparedUploadFile): Promise<Buffer> {
+	const buffer = Buffer.allocUnsafe(file.size);
+	let offset = 0;
+	while (offset < file.size) {
+		const { bytesRead } = await file.handle.read(
+			buffer,
+			offset,
+			file.size - offset,
+			offset,
+		);
+		if (bytesRead === 0) {
+			throw new Error(
+				`Short read: got ${offset} of ${file.size} validated bytes (file changed under us?).`,
+			);
+		}
+		offset += bytesRead;
+	}
+	return buffer;
+}
+
+/** A replayable stream over exactly the bytes validated when the file was opened. */
+function validatedByteStream(file: FilePutBody): Readable {
+	return Readable.from(
+		(async function* () {
+			const chunkSize = 1024 * 1024;
+			let offset = 0;
+			while (offset < file.size) {
+				const length = Math.min(chunkSize, file.size - offset);
+				const chunk = Buffer.allocUnsafe(length);
+				const filled = await fillPositionalRead(
+					file.handle,
+					chunk,
+					0,
+					length,
+					offset,
+				);
+				if (filled !== length) {
+					throw new Error(
+						`Short stream read: got ${filled} of ${length} bytes at offset ${offset} (file changed under us?).`,
+					);
+				}
+				offset += filled;
+				yield chunk;
+			}
+		})(),
+	);
+}
+
 export interface PartSlice {
 	/** 1-based part number, as S3/R2 multipart expects. */
 	part_number: number;
@@ -163,27 +258,52 @@ export function assertFullRead(
 }
 
 /**
- * Confines a model-supplied read path to an allowlisted input base and an
- * extension allowlist, then stats it. Base = HUBFLUENCER_INPUT_DIR if set, else
- * the current working directory. Rejects traversal outside the base — the same
- * `target === base || target.startsWith(base + sep)` guard `resolveSavePath`
- * uses, which defeats the `/base-evil` sibling-prefix bypass.
+ * Opens a confined local file without ever reopening it by pathname. Both the
+ * base and target are canonicalized so a symlink cannot escape the input root.
+ * After open, the descriptor is checked against the canonical target inode,
+ * closing the realpath-to-open swap window before any bytes are read.
  */
-export async function resolveReadPath(
+async function openReadPath(
 	filePath: string,
 	extToMime: Record<string, string>,
 	maxBytes: number,
-): Promise<ResolvedFile> {
+): Promise<PreparedUploadFile> {
 	if (!filePath || typeof filePath !== "string") {
 		throw new Error("file_path is required.");
 	}
-	const base = resolve(process.env.HUBFLUENCER_INPUT_DIR || process.cwd());
-	const target = isAbsolute(filePath)
+	const configuredBase = resolve(
+		process.env.HUBFLUENCER_INPUT_DIR || process.cwd(),
+	);
+	let base: string;
+	try {
+		base = await realpath(configuredBase);
+	} catch (e) {
+		throw new Error(
+			`Cannot resolve input directory ${configuredBase}: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+	const requested = isAbsolute(filePath)
 		? resolve(filePath)
-		: resolve(base, filePath);
+		: resolve(configuredBase, filePath);
+	if (
+		requested !== configuredBase &&
+		!requested.startsWith(configuredBase + sep)
+	) {
+		throw new Error(
+			`file_path must be inside ${base} (set HUBFLUENCER_INPUT_DIR to change). Refusing to read ${requested}.`,
+		);
+	}
+	let target: string;
+	try {
+		target = await realpath(requested);
+	} catch (e) {
+		throw new Error(
+			`Cannot read ${requested}: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
 	if (target !== base && !target.startsWith(base + sep)) {
 		throw new Error(
-			`file_path must be inside ${base} (set HUBFLUENCER_INPUT_DIR to change). Refusing to read ${target}.`,
+			`file_path must resolve inside ${base} (set HUBFLUENCER_INPUT_DIR to change). Refusing to read ${target}.`,
 		);
 	}
 	const ext = extname(target).slice(1).toLowerCase();
@@ -194,23 +314,71 @@ export async function resolveReadPath(
 			.join(", ");
 		throw new Error(`Unsupported file type ".${ext}". Allowed: ${allowed}.`);
 	}
-	let size: number;
+	let handle: FileHandle | undefined;
 	try {
-		const st = await stat(target);
+		handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+		const [openedStat, targetStat, currentTarget] = await Promise.all([
+			handle.stat(),
+			stat(target),
+			realpath(requested),
+		]);
+		if (currentTarget !== target) throw new Error("path changed while opening");
+		const st = openedStat;
 		if (!st.isFile()) throw new Error("not a regular file");
-		size = st.size;
+		if (st.dev !== targetStat.dev || st.ino !== targetStat.ino) {
+			throw new Error("opened file does not match the validated target");
+		}
+		if (st.size <= 0) throw new Error(`${target} is empty.`);
+		if (st.size > maxBytes) {
+			throw new Error(
+				`${target} is ${st.size} bytes — over the ${maxBytes}-byte cap for this asset type.`,
+			);
+		}
+		return { path: target, ext, mime, size: st.size, handle };
 	} catch (e) {
+		if (handle) await closeReadHandle(handle).catch(() => undefined);
 		throw new Error(
 			`Cannot read ${target}: ${e instanceof Error ? e.message : String(e)}`,
 		);
 	}
-	if (size <= 0) throw new Error(`${target} is empty.`);
-	if (size > maxBytes) {
-		throw new Error(
-			`${target} is ${size} bytes — over the ${maxBytes}-byte cap for this asset type.`,
-		);
+}
+
+/**
+ * Opens and retains a validated image descriptor for a multi-step operation.
+ * The caller must close it with `closePreparedUploadFile` in a finally block.
+ */
+export async function prepareImageUpload(
+	filePath: string,
+	maxBytes: number = MAX_IMAGE_BYTES,
+): Promise<PreparedUploadFile> {
+	const file = await openReadPath(filePath, IMAGE_EXT_MIME, maxBytes);
+	try {
+		file.bytes = await readValidatedBytes(file);
+		return file;
+	} catch (error) {
+		await closeReadHandle(file.handle);
+		throw error;
+	}
+}
+
+export function closePreparedUploadFile(
+	file: PreparedUploadFile,
+): Promise<void> {
+	return closeReadHandle(file.handle);
+}
+
+export async function resolveReadPath(
+	filePath: string,
+	extToMime: Record<string, string>,
+	maxBytes: number,
+): Promise<ResolvedFile> {
+	const file = await openReadPath(filePath, extToMime, maxBytes);
+	try {
+		const { handle: _, ...resolved } = file;
+		return resolved;
+	} finally {
+		await closeReadHandle(file.handle);
 	}
-	return { path: target, ext, mime, size };
 }
 
 /**
@@ -225,6 +393,14 @@ export async function resolveVideoReadPath(
 	return resolveReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
 }
 
+/** Fail-fast validation for a local jpeg/png before a draft is created. */
+export async function resolveImageReadPath(
+	filePath: string,
+	maxBytes: number = MAX_IMAGE_BYTES,
+): Promise<ResolvedFile> {
+	return resolveReadPath(filePath, IMAGE_EXT_MIME, maxBytes);
+}
+
 /**
  * PUTs bytes to a presigned S3/R2 URL. `contentType` is sent ONLY when the URL
  * signed it (single-object presign does — see S3Client.presign_put's
@@ -250,7 +426,7 @@ export async function putToPresignedUrl(
 	if (contentType) headers["content-type"] = contentType;
 	let fetchBody: BodyInit;
 	let fetchInit: RequestInit & { duplex?: "half" };
-	let stream: ReadStream | undefined;
+	let stream: Readable | undefined;
 	if (Buffer.isBuffer(body)) {
 		// Pass an exact ArrayBuffer slice — the generic Uint8Array<ArrayBufferLike>
 		// type doesn't resolve cleanly against fetch's BodyInit union, but a plain
@@ -261,7 +437,10 @@ export async function putToPresignedUrl(
 		) as ArrayBuffer;
 		fetchInit = { method: "PUT", headers, body: fetchBody };
 	} else {
-		stream = createReadStream(body.filePath);
+		// Never hand fetch the descriptor itself: Bun closes supplied fds even when
+		// fs.ReadStream says autoClose:false. This positional Readable has no fd
+		// ownership, reads exactly the validated range, and can be rebuilt for retry.
+		stream = validatedByteStream(body);
 		headers["content-length"] = String(contentLength ?? body.size);
 		fetchInit = {
 			method: "PUT",
@@ -271,11 +450,19 @@ export async function putToPresignedUrl(
 		};
 	}
 	fetchInit.signal = AbortSignal.timeout(timeoutMs);
+	const closeStream = async (): Promise<void> => {
+		if (!stream || stream.closed) return;
+		await new Promise<void>((resolve, reject) => {
+			stream?.once("close", resolve);
+			stream?.once("error", reject);
+			stream?.destroy();
+		});
+	};
 	let resp: Response;
 	try {
 		resp = await fetch(url, fetchInit);
 	} catch (e) {
-		stream?.destroy();
+		await closeStream().catch(() => undefined);
 		// A connection-level blip or timeout on a PUT is transient — re-wrap it with
 		// the `retryable` marker so a caller (uploadPartWithRetry) can re-sign and
 		// retry the part. The friendly message would otherwise erase the original
@@ -290,14 +477,19 @@ export async function putToPresignedUrl(
 			? markRetryable(`Upload PUT failed: ${e.message}`)
 			: e;
 	}
+	await closeStream();
 	if (!resp.ok) {
 		// An HTTP-status rejection from S3 (bad/expired signature, 4xx) is NOT
 		// marked retryable — re-uploading the same bytes would just be rejected the
 		// same way. Only the transient connection failures above are retried.
 		const text = await resp.text().catch(() => "");
-		throw new Error(
+		const error = new Error(
 			`Upload PUT rejected (HTTP ${resp.status})${text ? `: ${text.slice(0, 200)}` : ""}.`,
 		);
+		if (isRetryableStatus(resp.status)) {
+			Object.assign(error, { retryable: true });
+		}
+		throw error;
 	}
 	return resp.headers.get("etag") ?? undefined;
 }
@@ -348,48 +540,54 @@ export async function uploadVideoFile(
 		onProgress?: UploadProgress;
 	} = {},
 ): Promise<UploadedVideo> {
-	const file = await resolveReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
+	const file = await openReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
 	const filename = basename(file.path);
 	const fit_mode = opts.fitMode === "cover" ? "cover" : undefined;
 	const product_description = opts.productDescription;
 
-	if (file.size >= MULTIPART_THRESHOLD) {
-		return uploadVideoMultipart(
-			client,
-			slug,
-			file,
+	try {
+		if (file.size >= MULTIPART_THRESHOLD) {
+			return await uploadVideoMultipart(
+				client,
+				slug,
+				file,
+				{
+					filename,
+					fit_mode,
+					product_description,
+				},
+				opts.onProgress,
+			);
+		}
+		// Snapshot before creating the server upload row. A later truncate/growth
+		// cannot leave a post-presign orphan or change the bytes that were validated.
+		const buf = await readValidatedBytes(file);
+
+		const presign = await client.post<PresignVideoResponse>(
+			`/editor/${slug}/uploads/presign`,
 			{
 				filename,
+				mime_type: file.mime,
+				size_bytes: file.size,
 				fit_mode,
 				product_description,
 			},
-			opts.onProgress,
 		);
+		const { upload_id, presigned_url } = presign.data;
+		// A small file is one PUT — report it as a single 1-of-1 step so the caller
+		// still gets a progress beat during the transfer.
+		await opts.onProgress?.(0, 1, `uploading ${filename}`);
+		// Content-Type MUST equal the presigned mime exactly — confirm HEADs the
+		// object and 422s on mismatch (editor/uploads.ex).
+		await putToPresignedUrl(presigned_url, buf, file.mime);
+		await opts.onProgress?.(1, 1, `uploaded ${filename}, confirming`);
+		const confirmed = await client.post<ConfirmUploadResponse>(
+			`/editor/${slug}/uploads/${upload_id}/confirm`,
+		);
+		return { upload_id, status: confirmed.data?.status ?? "processing" };
+	} finally {
+		await closeReadHandle(file.handle);
 	}
-
-	const presign = await client.post<PresignVideoResponse>(
-		`/editor/${slug}/uploads/presign`,
-		{
-			filename,
-			mime_type: file.mime,
-			size_bytes: file.size,
-			fit_mode,
-			product_description,
-		},
-	);
-	const { upload_id, presigned_url } = presign.data;
-	const buf = await readFile(file.path);
-	// A small file is one PUT — report it as a single 1-of-1 step so the caller
-	// still gets a progress beat during the transfer.
-	await opts.onProgress?.(0, 1, `uploading ${filename}`);
-	// Content-Type MUST equal the presigned mime exactly — confirm HEADs the
-	// object and 422s on mismatch (editor/uploads.ex).
-	await putToPresignedUrl(presigned_url, buf, file.mime);
-	await opts.onProgress?.(1, 1, `uploaded ${filename}, confirming`);
-	const confirmed = await client.post<ConfirmUploadResponse>(
-		`/editor/${slug}/uploads/${upload_id}/confirm`,
-	);
-	return { upload_id, status: confirmed.data?.status ?? "processing" };
 }
 
 /**
@@ -431,7 +629,12 @@ async function uploadPartWithRetry(
 			// Retry only a transient network/timeout failure, and only while attempts
 			// remain. A definite rejection (e.g. a 4xx from S3, or a sign-part error
 			// the client already classified as non-retryable) propagates immediately.
-			if (attempt <= PART_RETRIES && isRetryableNetworkError(e)) {
+			const status = (e as { status?: unknown })?.status;
+			if (
+				attempt <= PART_RETRIES &&
+				(isRetryableNetworkError(e) ||
+					(typeof status === "number" && isRetryableStatus(status)))
+			) {
 				await sleep(backoffDelayMs(attempt, DEFAULT_RETRY));
 				continue;
 			}
@@ -443,7 +646,7 @@ async function uploadPartWithRetry(
 async function uploadVideoMultipart(
 	client: HubfluencerClient,
 	slug: string,
-	file: ResolvedFile,
+	file: PreparedUploadFile,
 	meta: { filename: string; fit_mode?: string; product_description?: string },
 	onProgress?: UploadProgress,
 ): Promise<UploadedVideo> {
@@ -458,29 +661,31 @@ async function uploadVideoMultipart(
 		},
 	);
 	const { upload_id, s3_upload_id, parts_count, part_size } = init.data;
-	const plan = planMultipartParts(file.size, part_size);
-	// The server signs parts by number and validates the set on complete; if its
-	// part count disagrees with our slicing, fail loudly before uploading rather
-	// than producing an unmatchable set.
-	if (plan.length !== parts_count) {
-		throw new Error(
-			`Multipart plan mismatch: server expects ${parts_count} parts, computed ${plan.length} for ${file.size} bytes at ${part_size}/part.`,
-		);
-	}
-	await onProgress?.(
-		0,
-		plan.length,
-		`uploading ${meta.filename} in ${plan.length} parts`,
-	);
-	const fh = await open(file.path, "r");
-	const parts: Array<{ part_number: number; etag: string }> = [];
 	try {
+		const plan = planMultipartParts(file.size, part_size);
+		// Once init succeeds, every later failure must abort the server upload,
+		// including an invalid server plan or a caller progress callback throwing.
+		if (plan.length !== parts_count) {
+			throw new Error(
+				`Multipart plan mismatch: server expects ${parts_count} parts, computed ${plan.length} for ${file.size} bytes at ${part_size}/part.`,
+			);
+		}
+		await onProgress?.(
+			0,
+			plan.length,
+			`uploading ${meta.filename} in ${plan.length} parts`,
+		);
+		const parts: Array<{ part_number: number; etag: string }> = [];
 		for (const { part_number, offset, len } of plan) {
 			const chunk = Buffer.alloc(len);
-			// Verify the read filled the whole part — a short read would upload a
-			// zero-padded, silently-corrupt part (see assertFullRead).
-			const { bytesRead } = await fh.read(chunk, 0, len, offset);
-			assertFullRead(bytesRead, len, part_number, offset);
+			const filled = await fillPositionalRead(
+				file.handle,
+				chunk,
+				0,
+				len,
+				offset,
+			);
+			assertFullRead(filled, len, part_number, offset);
 			const etag = await uploadPartWithRetry(
 				client,
 				slug,
@@ -514,8 +719,6 @@ async function uploadVideoMultipart(
 			// abort is cleanup — never mask the original failure
 		}
 		throw e;
-	} finally {
-		await fh.close();
 	}
 }
 
@@ -533,18 +736,25 @@ interface PresignImageResponse {
 export async function uploadImageFile(
 	client: HubfluencerClient,
 	presignPath: string,
-	filePath: string,
+	filePath: string | PreparedUploadFile,
 	maxBytes: number = MAX_IMAGE_BYTES,
 ): Promise<{ s3_key: string }> {
-	const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, maxBytes);
-	const presign = await client.post<PresignImageResponse>(presignPath, {
-		mime_type: file.mime,
-		size_bytes: file.size,
-	});
-	const { presigned_url, s3_key } = presign.data;
-	const buf = await readFile(file.path);
-	await putToPresignedUrl(presigned_url, buf, file.mime);
-	return { s3_key };
+	const ownsFile = typeof filePath === "string";
+	const file = ownsFile
+		? await openReadPath(filePath, IMAGE_EXT_MIME, maxBytes)
+		: filePath;
+	try {
+		const buf = file.bytes ?? (await readValidatedBytes(file));
+		const presign = await client.post<PresignImageResponse>(presignPath, {
+			mime_type: file.mime,
+			size_bytes: file.size,
+		});
+		const { presigned_url, s3_key } = presign.data;
+		await putToPresignedUrl(presigned_url, buf, file.mime);
+		return { s3_key };
+	} finally {
+		if (ownsFile) await closeReadHandle(file.handle);
+	}
 }
 
 /**
@@ -561,15 +771,19 @@ export async function uploadShortPoster(
 	slug: string,
 	filePath: string,
 ): Promise<{ s3_key: string }> {
-	const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
-	const presign = await client.post<{ upload_url: string; s3_key: string }>(
-		`/shorts/${slug}/poster/presign`,
-		{ content_type: file.mime },
-	);
-	const { upload_url, s3_key } = presign;
-	const buf = await readFile(file.path);
-	await putToPresignedUrl(upload_url, buf, file.mime);
-	return { s3_key };
+	const file = await openReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
+	try {
+		const buf = await readValidatedBytes(file);
+		const presign = await client.post<{ upload_url: string; s3_key: string }>(
+			`/shorts/${slug}/poster/presign`,
+			{ content_type: file.mime },
+		);
+		const { upload_url, s3_key } = presign;
+		await putToPresignedUrl(upload_url, buf, file.mime);
+		return { s3_key };
+	} finally {
+		await closeReadHandle(file.handle);
+	}
 }
 
 interface CatalogPresignResponse {
@@ -618,70 +832,94 @@ export async function uploadCatalogAsset(
 	// Resolve against the larger (video) ceiling first so a valid image/video
 	// path passes the confinement + extension check, then enforce the true
 	// per-type cap (images are capped lower) with a precise message.
-	const file = await resolveReadPath(
-		filePath,
-		CATALOG_EXT_MIME,
-		MAX_VIDEO_BYTES,
-	);
-	const cap = catalogMaxBytes(file.mime);
-	if (file.size > cap) {
-		throw new Error(
-			`${file.path} is ${file.size} bytes — over the ${cap}-byte cap for ${file.mime} catalog uploads.`,
-		);
-	}
-	if (file.mime.startsWith("video/")) {
-		const duration = opts.durationSeconds;
-		if (
-			typeof duration !== "number" ||
-			!Number.isFinite(duration) ||
-			duration <= 0 ||
-			duration > MAX_CATALOG_VIDEO_DURATION_SECONDS
-		) {
+	const file = await openReadPath(filePath, CATALOG_EXT_MIME, MAX_VIDEO_BYTES);
+	try {
+		const cap = catalogMaxBytes(file.mime);
+		if (file.size > cap) {
 			throw new Error(
-				`Catalog video uploads require durationSeconds to be greater than 0 and no more than ${MAX_CATALOG_VIDEO_DURATION_SECONDS} seconds.`,
+				`${file.path} is ${file.size} bytes — over the ${cap}-byte cap for ${file.mime} catalog uploads.`,
 			);
 		}
-	}
-	const filename = basename(file.path);
-	const presign = await client.post<CatalogPresignResponse>("/assets/presign", {
-		filename,
-		mime_type: file.mime,
-		size_bytes: file.size,
-	});
-	const { asset_id, presigned_url } = presign.data;
-	// Content-Type MUST equal the presigned mime exactly — the catalog presign
-	// signs it and confirm HEADs the object, 422ing on mismatch.
-	if (file.size >= MULTIPART_THRESHOLD) {
-		await putToPresignedUrl(
-			presigned_url,
-			{ filePath: file.path, size: file.size },
-			file.mime,
-			300_000,
-			file.size,
+		if (file.mime.startsWith("video/")) {
+			const duration = opts.durationSeconds;
+			if (
+				typeof duration !== "number" ||
+				!Number.isFinite(duration) ||
+				duration <= 0 ||
+				duration > MAX_CATALOG_VIDEO_DURATION_SECONDS
+			) {
+				throw new Error(
+					`Catalog video uploads require durationSeconds to be greater than 0 and no more than ${MAX_CATALOG_VIDEO_DURATION_SECONDS} seconds.`,
+				);
+			}
+		}
+		const bufferedBytes =
+			file.size < MULTIPART_THRESHOLD
+				? await readValidatedBytes(file)
+				: undefined;
+		const filename = basename(file.path);
+		const presign = await client.post<CatalogPresignResponse>(
+			"/assets/presign",
+			{
+				filename,
+				mime_type: file.mime,
+				size_bytes: file.size,
+			},
 		);
-	} else {
-		const buf = await readFile(file.path);
-		await putToPresignedUrl(presigned_url, buf, file.mime);
+		const { asset_id, presigned_url } = presign.data;
+		// Content-Type MUST equal the presigned mime exactly — the catalog presign
+		// signs it and confirm HEADs the object, 422ing on mismatch.
+		if (file.size >= MULTIPART_THRESHOLD) {
+			for (let attempt = 1; ; attempt++) {
+				try {
+					await putToPresignedUrl(
+						presigned_url,
+						{ handle: file.handle, size: file.size },
+						file.mime,
+						300_000,
+						file.size,
+					);
+					break;
+				} catch (error) {
+					if (
+						attempt >= DEFAULT_RETRY.attempts ||
+						!isRetryableNetworkError(error)
+					) {
+						throw error;
+					}
+					await sleep(backoffDelayMs(attempt, DEFAULT_RETRY));
+				}
+			}
+		} else {
+			await putToPresignedUrl(
+				presigned_url,
+				bufferedBytes as Buffer,
+				file.mime,
+			);
+		}
+		const confirmBody: Record<string, unknown> = {};
+		if (typeof opts.description === "string" && opts.description.trim() !== "")
+			confirmBody.description = opts.description;
+		if (typeof opts.width === "number") confirmBody.width = opts.width;
+		if (typeof opts.height === "number") confirmBody.height = opts.height;
+		if (typeof opts.durationSeconds === "number")
+			confirmBody.duration_seconds = opts.durationSeconds;
+		const confirmed = await client.post<{ data: Record<string, unknown> }>(
+			`/assets/${asset_id}/confirm`,
+			confirmBody,
+		);
+		const data = confirmed.data ?? {};
+		return {
+			asset_id,
+			status: typeof data.status === "string" ? data.status : "ready",
+			media_type: typeof data.media_type === "string" ? data.media_type : "",
+			mime_type:
+				typeof data.mime_type === "string" ? data.mime_type : file.mime,
+			filename: typeof data.filename === "string" ? data.filename : filename,
+			size_bytes:
+				typeof data.size_bytes === "number" ? data.size_bytes : file.size,
+		};
+	} finally {
+		await closeReadHandle(file.handle);
 	}
-	const confirmBody: Record<string, unknown> = {};
-	if (typeof opts.description === "string" && opts.description.trim() !== "")
-		confirmBody.description = opts.description;
-	if (typeof opts.width === "number") confirmBody.width = opts.width;
-	if (typeof opts.height === "number") confirmBody.height = opts.height;
-	if (typeof opts.durationSeconds === "number")
-		confirmBody.duration_seconds = opts.durationSeconds;
-	const confirmed = await client.post<{ data: Record<string, unknown> }>(
-		`/assets/${asset_id}/confirm`,
-		confirmBody,
-	);
-	const data = confirmed.data ?? {};
-	return {
-		asset_id,
-		status: typeof data.status === "string" ? data.status : "ready",
-		media_type: typeof data.media_type === "string" ? data.media_type : "",
-		mime_type: typeof data.mime_type === "string" ? data.mime_type : file.mime,
-		filename: typeof data.filename === "string" ? data.filename : filename,
-		size_bytes:
-			typeof data.size_bytes === "number" ? data.size_bytes : file.size,
-	};
 }