@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/local-file-io.cjs

@@ -0,0 +1,364 @@
+const require_error_reason = require("../util/error-reason.cjs");
+const require_local_file_identity = require("./local-file-identity.cjs");
+const require_path_safety = require("./path-safety.cjs");
+const require_download_staging = require("./download-staging.cjs");
+const require_b2_sha1_reader = require("./b2-sha1-reader.cjs");
+//#region src/sync/local-file-io.ts
+/** @internal */
+var localFileIoTestHooks = {};
+/**
+* Verifies that a previously scanned local file still points at the same regular file.
+*
+* @param path - Scanned local path and file identity.
+*
+* @internal
+*/
+async function validateScannedLocalFile(path) {
+	await (await openValidatedScannedLocalFile(path)).close();
+}
+async function openValidatedScannedLocalFile(path) {
+	const { constants } = await import("node:fs");
+	const { open } = await import("node:fs/promises");
+	const flags = constants.O_RDONLY | require_path_safety.noFollowFlag(constants) | (constants.O_NONBLOCK ?? 0);
+	const handle = await open(path.absolutePath, flags).catch((err) => {
+		if (require_path_safety.hasErrorCode(err, "ELOOP")) throw new Error("local file changed before upload: not a regular file");
+		throw new Error(`local file changed before upload: could not open scanned file: ${require_error_reason.sanitizeErrorReason(err)}`);
+	});
+	try {
+		require_local_file_identity.assertSameScannedRegularFile(await handle.stat(), path, "upload", { platform: localFileIoTestHooks.platform });
+		return handle;
+	} catch (err) {
+		await handle.close().catch(() => {});
+		throw err;
+	}
+}
+/**
+* Streams a B2 download under a local sync root with path, timeout, and size checks.
+*
+* @param root - Local sync root.
+* @param relPath - Destination path relative to the root.
+* @param body - Download body stream.
+* @param options - Expected byte count, idle timeout, and optional abort signal.
+*
+* @internal
+*/
+async function writeLocalStreamInsideRoot(root, relPath, body, options) {
+	const { constants } = await import("node:fs");
+	const { link, lstat, mkdir, open, realpath, rename, rm, stat } = await import("node:fs/promises");
+	const path = await import("node:path");
+	const { randomUUID } = await import("node:crypto");
+	assertValidExpectedBytes(options.expectedBytes);
+	const segments = require_path_safety.safeRelativePathSegments(relPath);
+	if (require_download_staging.isDownloadStagingDirectorySegment(segments[0])) throw new Error(`unsafe local destination path: ${require_download_staging.DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`);
+	const rootRealPath = await realpath(root);
+	let current = rootRealPath;
+	for (const segment of segments.slice(0, -1)) {
+		current = path.join(current, segment);
+		try {
+			await mkdir(current);
+		} catch (err) {
+			if (!require_path_safety.hasErrorCode(err, "EEXIST")) throw err;
+		}
+		if (!(await lstat(current)).isDirectory()) throw new Error("unsafe local destination path: parent is not a directory");
+		await localFileIoTestHooks.afterParentDirectoryValidated?.(current);
+	}
+	const destPath = path.join(rootRealPath, ...segments);
+	require_path_safety.assertPathInsideRoot(rootRealPath, destPath, path);
+	const parentRealPath = await realpath(path.dirname(destPath));
+	const finalPath = path.join(parentRealPath, path.basename(destPath));
+	require_path_safety.assertPathInsideRoot(rootRealPath, finalPath, path);
+	try {
+		const targetStats = await lstat(finalPath);
+		if (targetStats.isSymbolicLink()) throw new Error("unsafe local destination path: target is a symbolic link");
+		if (targetStats.isFile() && targetStats.nlink > 1) throw new Error("unsafe local destination path: target has multiple hard links");
+	} catch (err) {
+		if (!require_path_safety.hasErrorCode(err, "ENOENT")) throw err;
+	}
+	const statForDeviceCheck = localFileIoTestHooks.statForDeviceCheck ?? stat;
+	await require_download_staging.assertDownloadPathSameDevice(rootRealPath, parentRealPath, statForDeviceCheck, "unsafe local destination path: cannot publish download across filesystems");
+	let parentHandle;
+	let anchoredParentPath;
+	/* v8 ignore start -- Linux-only fd-relative path support is covered by Linux CI */
+	if (globalThis.process?.platform === "linux" && constants.O_DIRECTORY !== void 0 && localFileIoTestHooks.disableProcFdAnchoring !== true) try {
+		parentHandle = await open(parentRealPath, constants.O_RDONLY | constants.O_DIRECTORY | require_path_safety.noFollowFlag(constants));
+		anchoredParentPath = `/proc/self/fd/${parentHandle.fd}`;
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "ELOOP") || require_path_safety.hasErrorCode(err, "ENOTDIR")) throw new Error("unsafe local destination path: parent is not a directory");
+		throw err;
+	}
+	/* v8 ignore stop */
+	const finalName = path.basename(destPath);
+	const finalWritePath = path.join(anchoredParentPath ?? parentRealPath, finalName);
+	let publishMode;
+	try {
+		publishMode = await replacementFileMode(finalPath);
+	} catch (err) {
+		/* v8 ignore next -- best-effort close during setup failure */
+		await parentHandle?.close().catch(() => {});
+		throw err;
+	}
+	let stagingDirectory;
+	try {
+		stagingDirectory = await require_download_staging.createDownloadStagingDirectory(rootRealPath, path, randomUUID, statForDeviceCheck, localFileIoTestHooks.beforeStagingMarkerWrite);
+	} catch (err) {
+		/* v8 ignore next -- best-effort close during setup failure */
+		await parentHandle?.close().catch(() => {});
+		throw err;
+	}
+	const tmpPath = path.join(stagingDirectory, `.b2sdk-${randomUUID()}.partial`);
+	let handle;
+	try {
+		handle = await open(tmpPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | require_path_safety.noFollowFlag(constants), PRIVATE_DOWNLOAD_FILE_MODE);
+		/* v8 ignore next -- best-effort chmod */
+		await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {});
+		await localFileIoTestHooks.afterTempFileCreated?.(tmpPath, stagingDirectory);
+	} catch (err) {
+		await parentHandle?.close().catch(() => {});
+		await rm(stagingDirectory, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		throw err;
+	}
+	/* v8 ignore stop */
+	try {
+		const tmpRealPath = await realpath(tmpPath);
+		require_path_safety.assertPathInsideRoot(stagingDirectory, tmpRealPath, path);
+	} catch (err) {
+		/* v8 ignore next -- best-effort cleanup */
+		await handle?.close().catch(() => {});
+		/* v8 ignore next -- best-effort cleanup */
+		await rm(tmpPath, { force: true }).catch(() => {});
+		/* v8 ignore next -- best-effort cleanup */
+		await rm(stagingDirectory, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		/* v8 ignore next -- best-effort cleanup */
+		await parentHandle?.close().catch(() => {});
+		throw err;
+	}
+	const writeHandle = handle;
+	const reader = body.getReader();
+	let completed = false;
+	try {
+		let bytesWritten = 0;
+		while (true) {
+			const { done, value } = await require_b2_sha1_reader.readStreamChunkWithTimeout(reader, options.idleTimeoutMillis, `download read stalled for ${options.idleTimeoutMillis} ms`, options.signal);
+			if (done) break;
+			if (bytesWritten + value.byteLength > options.expectedBytes) throw new Error(`download read exceeded ${options.expectedBytes} byte limit`);
+			await writeAll(writeHandle, value, bytesWritten);
+			bytesWritten += value.byteLength;
+		}
+		if (bytesWritten !== options.expectedBytes) throw new Error(`download read ended after ${bytesWritten} bytes, expected ${options.expectedBytes}`);
+		if (publishMode !== PRIVATE_DOWNLOAD_FILE_MODE)
+ /* v8 ignore next -- best-effort mode preservation */
+		await writeHandle.chmod(publishMode).catch(() => {});
+		await writeHandle.close();
+		handle = void 0;
+		const [parentRealPathBeforeRename, parentStatsBeforeRename] = await Promise.all([realpath(path.dirname(destPath)), stat(path.dirname(destPath))]);
+		require_path_safety.assertPathInsideRoot(rootRealPath, path.join(parentRealPathBeforeRename, path.basename(destPath)), path);
+		await localFileIoTestHooks.beforeFinalRename?.(parentRealPathBeforeRename);
+		let publishPath = finalWritePath;
+		if (anchoredParentPath === void 0) {
+			const [parentRealPathAfterHook, parentStatsAfterHook] = await Promise.all([realpath(path.dirname(destPath)), stat(path.dirname(destPath))]);
+			if (parentRealPathAfterHook !== parentRealPathBeforeRename || !sameParentIdentity(parentStatsAfterHook, parentStatsBeforeRename)) throw new Error("unsafe local destination path: parent changed before final publish");
+			publishPath = path.join(parentRealPathAfterHook, path.basename(destPath));
+			require_path_safety.assertPathInsideRoot(rootRealPath, publishPath, path);
+		}
+		await publishDownload(lstat, link, path, randomUUID, rename, rm, tmpPath, publishPath, options.expectedDestination);
+		completed = true;
+	} catch (err) {
+		/* v8 ignore next -- best-effort cleanup */
+		reader.cancel(err).catch(() => {});
+		throw err;
+	} finally {
+		reader.releaseLock();
+		if (!completed) {
+			/* v8 ignore next -- best-effort cleanup */
+			await handle?.close().catch(() => {});
+			/* v8 ignore next -- best-effort cleanup */
+			await rm(tmpPath, { force: true }).catch(() => {});
+		}
+		/* v8 ignore next -- best-effort cleanup */
+		await rm(stagingDirectory, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		/* v8 ignore next -- best-effort cleanup */
+		await parentHandle?.close().catch(() => {});
+	}
+}
+function assertValidExpectedBytes(expectedBytes) {
+	if (!Number.isSafeInteger(expectedBytes) || expectedBytes < 0) throw new Error("download expectedBytes must be a non-negative safe integer");
+}
+async function assertExpectedDownloadDestination(lstat, finalPath, expectedDestination) {
+	if (expectedDestination === void 0) return;
+	try {
+		const stats = await lstat(finalPath);
+		if (expectedDestination === null) throw new Error("local destination changed before download: file was created");
+		require_local_file_identity.assertSameScannedRegularFile(stats, {
+			...expectedDestination,
+			absolutePath: finalPath
+		}, "download", { platform: localFileIoTestHooks.platform });
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) {
+			if (expectedDestination === null) return;
+			throw new Error("local file changed before download: file missing");
+		}
+		throw err;
+	}
+}
+async function publishDownload(lstat, link, path, randomUUID, rename, rm, tmpPath, publishPath, expectedDestination) {
+	await assertExpectedDownloadDestination(lstat, publishPath, expectedDestination);
+	await localFileIoTestHooks.beforeDownloadPublish?.(publishPath);
+	if (expectedDestination === void 0) {
+		await rename(tmpPath, publishPath);
+		return;
+	}
+	if (expectedDestination === null) {
+		await linkDownloadNoOverwrite(link, tmpPath, publishPath, "local destination changed before download: file was created");
+		/* v8 ignore next -- staging cleanup is best-effort after a guarded publish succeeds. */
+		await rm(tmpPath, { force: true }).catch(() => {});
+		return;
+	}
+	const backupPath = path.join(path.dirname(publishPath), require_path_safety.makeReservedSyncTempFileName(path.basename(publishPath), randomUUID()));
+	let backupExists = false;
+	let removeBackup = false;
+	try {
+		try {
+			await rename(publishPath, backupPath);
+			backupExists = true;
+			await localFileIoTestHooks.afterDownloadBackupRename?.(backupPath);
+		} catch (err) {
+			if (require_path_safety.hasErrorCode(err, "ENOENT")) throw new Error("local file changed before download: file missing");
+			throw err;
+		}
+		require_local_file_identity.assertSameScannedRegularFile(await lstat(backupPath), {
+			...expectedDestination,
+			absolutePath: backupPath
+		}, "download", {
+			compareChangeTime: false,
+			platform: localFileIoTestHooks.platform
+		});
+		await linkDownloadNoOverwrite(link, tmpPath, publishPath, "local destination changed before download: file was created");
+		removeBackup = true;
+		/* v8 ignore next -- staging cleanup is best-effort after a guarded publish succeeds. */
+		await rm(tmpPath, { force: true }).catch(() => {});
+	} catch (err) {
+		if (backupExists && !removeBackup) await restoreBackupWithoutOverwrite(link, rm, backupPath, publishPath).catch(() => {});
+		throw err;
+	} finally {
+		if (removeBackup)
+ /* v8 ignore next -- old destination cleanup is best-effort after publish succeeds. */
+		await rm(backupPath, { force: true }).catch(() => {});
+	}
+}
+async function linkDownloadNoOverwrite(link, sourcePath, destPath, message) {
+	try {
+		await link(sourcePath, destPath);
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "EEXIST")) throw new Error(message);
+		throw err;
+	}
+}
+async function restoreBackupWithoutOverwrite(link, rm, backupPath, publishPath) {
+	try {
+		await link(backupPath, publishPath);
+		await rm(backupPath, { force: true });
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "EEXIST")) return;
+		throw err;
+	}
+}
+var PRIVATE_DOWNLOAD_FILE_MODE = 384;
+async function replacementFileMode(filePath) {
+	const { lstat } = await import("node:fs/promises");
+	try {
+		const stats = await lstat(filePath);
+		return stats.isFile() ? stats.mode & 511 : PRIVATE_DOWNLOAD_FILE_MODE;
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return PRIVATE_DOWNLOAD_FILE_MODE;
+		throw err;
+	}
+}
+/**
+* Deletes a scanned local file under a sync root without re-resolving attacker-controlled parents.
+*
+* @param root - Local sync root.
+* @param scannedPath - Previously scanned local file metadata.
+*
+* @internal
+*/
+async function deleteLocalFileInsideRoot(root, scannedPath) {
+	if (root === "") throw new Error("Local sync root required for filesystem mutation");
+	const { constants } = await import("node:fs");
+	const { lstat, open, realpath, stat, unlink } = await import("node:fs/promises");
+	const path = await import("node:path");
+	const segments = require_path_safety.safeRelativePathSegments(scannedPath.relativePath);
+	const safeRoot = path.resolve(root);
+	const rootStats = await lstat(safeRoot);
+	if (rootStats.isSymbolicLink()) throw new Error(`Refusing to access sync root through symlink: ${scannedPath.relativePath}`);
+	if (!rootStats.isDirectory()) throw new Error(`Local sync root is not a directory: ${scannedPath.relativePath}`);
+	const rootRealPath = await realpath(safeRoot);
+	const expectedPath = path.join(rootRealPath, ...segments);
+	require_path_safety.assertPathInsideRoot(rootRealPath, expectedPath, path);
+	if (path.resolve(scannedPath.absolutePath) !== expectedPath) throw new Error(`Refusing to delete outside sync root: ${scannedPath.relativePath}`);
+	const [parentRealPath, parentStats] = await Promise.all([realpath(path.dirname(expectedPath)), stat(path.dirname(expectedPath))]);
+	const finalPath = path.join(parentRealPath, path.basename(expectedPath));
+	require_path_safety.assertPathInsideRoot(rootRealPath, finalPath, path);
+	const platform = globalThis.process?.platform;
+	let parentHandle;
+	let anchoredParentPath;
+	/* v8 ignore start -- Linux-only fd-relative path support is covered by Linux CI */
+	if (platform === "linux" && constants.O_DIRECTORY !== void 0 && localFileIoTestHooks.disableProcFdAnchoring !== true) try {
+		await localFileIoTestHooks.beforeLocalDeleteOpenParent?.(parentRealPath);
+		parentHandle = await open(parentRealPath, constants.O_RDONLY | constants.O_DIRECTORY | require_path_safety.noFollowFlag(constants));
+		anchoredParentPath = `/proc/self/fd/${parentHandle.fd}`;
+	} catch (err) {
+		if (require_path_safety.hasErrorCode(err, "ELOOP") || require_path_safety.hasErrorCode(err, "ENOTDIR")) throw new Error("unsafe local delete path: parent is not a directory");
+		throw err;
+	}
+	/* v8 ignore stop */
+	try {
+		const unlinkPath = anchoredParentPath === void 0 ? finalPath : path.join(anchoredParentPath, path.basename(expectedPath));
+		require_local_file_identity.assertSameScannedRegularFile(await lstat(unlinkPath), {
+			...scannedPath,
+			absolutePath: unlinkPath
+		}, "delete", { platform: localFileIoTestHooks.platform });
+		await localFileIoTestHooks.beforeLocalDeleteUnlink?.(parentRealPath);
+		if (anchoredParentPath === void 0 && localFileIoTestHooks.disableProcFdAnchoring === true && parentRealPath !== rootRealPath) throw new Error("unsafe local delete path: stable parent handle unavailable for unlink");
+		if (anchoredParentPath === void 0) {
+			const [parentRealPathBeforeUnlink, parentStatsBeforeUnlink] = await Promise.all([realpath(path.dirname(expectedPath)), stat(path.dirname(expectedPath))]);
+			if (parentRealPathBeforeUnlink !== parentRealPath || !sameParentIdentity(parentStatsBeforeUnlink, parentStats)) throw new Error("unsafe local delete path: parent changed before unlink");
+		}
+		require_local_file_identity.assertSameScannedRegularFile(await lstat(unlinkPath), {
+			...scannedPath,
+			absolutePath: unlinkPath
+		}, "delete", { platform: localFileIoTestHooks.platform });
+		await unlink(unlinkPath);
+	} finally {
+		/* v8 ignore next -- best-effort cleanup */
+		await parentHandle?.close().catch(() => {});
+	}
+}
+function sameParentIdentity(current, expected) {
+	return current.dev === expected.dev && current.ino === expected.ino;
+}
+async function writeAll(handle, data, position) {
+	let offset = 0;
+	while (offset < data.byteLength) {
+		const { bytesWritten } = await handle.write(data, offset, data.byteLength - offset, position + offset);
+		/* v8 ignore next -- defensive: FileHandle.write should progress for non-empty chunks. */
+		if (bytesWritten <= 0) throw new Error("download write made no progress");
+		offset += bytesWritten;
+	}
+}
+//#endregion
+exports.DOWNLOAD_STAGING_DIRECTORY_NAME = require_download_staging.DOWNLOAD_STAGING_DIRECTORY_NAME;
+exports.deleteLocalFileInsideRoot = deleteLocalFileInsideRoot;
+exports.localFileIoTestHooks = localFileIoTestHooks;
+exports.validateScannedLocalFile = validateScannedLocalFile;
+exports.writeLocalStreamInsideRoot = writeLocalStreamInsideRoot;
+
+//# sourceMappingURL=local-file-io.cjs.map

package/dist/sync/local-file-io.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-io.cjs","names":[],"sources":["../../src/sync/local-file-io.ts"],"sourcesContent":["import { sanitizeErrorReason } from '../util/error-reason.ts'\nimport { readStreamChunkWithTimeout } from './b2-sha1-reader.ts'\nimport {\n  assertDownloadPathSameDevice,\n  createDownloadStagingDirectory,\n  DOWNLOAD_STAGING_DIRECTORY_NAME,\n  isDownloadStagingDirectorySegment,\n} from './download-staging.ts'\nimport { assertSameScannedRegularFile } from './local-file-identity.ts'\nimport {\n  assertPathInsideRoot,\n  hasErrorCode,\n  makeReservedSyncTempFileName,\n  noFollowFlag,\n  safeRelativePathSegments,\n} from './path-safety.ts'\nimport { DEFAULT_SHA1_IDLE_TIMEOUT_MILLIS } from './sha1-options.ts'\nimport type { LocalSyncPath } from './types.ts'\n\ntype DeviceStat = { readonly dev: number | bigint }\ntype DeviceStatFn = (path: string) => Promise<DeviceStat>\n\nexport { DOWNLOAD_STAGING_DIRECTORY_NAME }\n\n/** @internal */\nexport const localFileIoTestHooks: {\n  afterParentDirectoryValidated?: (path: string) => Promise<void> | void\n  afterDownloadBackupRename?: (path: string) => Promise<void> | void\n  afterTempFileCreated?: (path: string, stagingDirectory: string) => Promise<void> | void\n  beforeDownloadPublish?: (path: string) => Promise<void> | void\n  beforeFinalRename?: (path: string) => Promise<void> | void\n  beforeLocalDeleteOpenParent?: (path: string) => Promise<void> | void\n  beforeLocalDeleteUnlink?: (path: string) => Promise<void> | void\n  beforeStagingMarkerWrite?: (path: string) => Promise<void> | void\n  disableProcFdAnchoring?: boolean\n  platform?: string\n  statForDeviceCheck?: DeviceStatFn\n} = {}\n\ninterface ScannedLocalFileHandle {\n  stat(): Promise<{\n    isFile(): boolean\n    readonly dev: number\n    readonly ino: number\n    readonly mtimeMs: number\n    readonly ctimeMs: number\n    readonly size: number\n  }>\n  readFile(): Promise<Uint8Array>\n  close(): Promise<void>\n}\n\n/**\n * Verifies that a previously scanned local file still points at the same regular file.\n *\n * @param path - Scanned local path and file identity.\n *\n * @internal\n */\nexport async function validateScannedLocalFile(path: LocalSyncPath): Promise<void> {\n  const handle = await openValidatedScannedLocalFile(path)\n  await handle.close()\n}\n\n/**\n * Reads a previously scanned local file while rejecting symlink swaps and metadata drift.\n *\n * @param path - Scanned local path and file identity.\n *\n * @returns The file bytes.\n *\n * @internal\n */\nexport async function readScannedLocalFile(path: LocalSyncPath): Promise<Uint8Array> {\n  const handle = await openValidatedScannedLocalFile(path)\n  try {\n    const data = await handle.readFile()\n    if (data.byteLength !== path.size) {\n      throw new Error('local file changed before upload: size changed while reading')\n    }\n    return data\n  } finally {\n    await handle.close()\n  }\n}\n\nasync function openValidatedScannedLocalFile(path: LocalSyncPath): Promise<ScannedLocalFileHandle> {\n  const { constants } = await import('node:fs')\n  const { open } = await import('node:fs/promises')\n  const flags =\n    constants.O_RDONLY |\n    noFollowFlag(constants) |\n    ((constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0)\n  const handle = await open(path.absolutePath, flags).catch((err: unknown) => {\n    if (hasErrorCode(err, 'ELOOP')) {\n      throw new Error('local file changed before upload: not a regular file')\n    }\n    throw new Error(\n      `local file changed before upload: could not open scanned file: ${sanitizeErrorReason(err)}`,\n    )\n  })\n  try {\n    const stats = await handle.stat()\n    assertSameScannedRegularFile(stats, path, 'upload', {\n      platform: localFileIoTestHooks.platform,\n    })\n    return handle\n  } catch (err) {\n    await handle.close().catch(() => {})\n    throw err\n  }\n}\n\n/**\n * Writes bytes under a local sync root after path containment checks.\n *\n * @param root - Local sync root.\n * @param relPath - Destination path relative to the root.\n * @param data - Bytes to write.\n *\n * @internal\n */\nexport async function writeLocalFileInsideRoot(\n  root: string,\n  relPath: string,\n  data: Uint8Array,\n): Promise<void> {\n  await writeLocalStreamInsideRoot(\n    root,\n    relPath,\n    new ReadableStream<Uint8Array>({\n      start(controller) {\n        controller.enqueue(data)\n        controller.close()\n      },\n    }),\n    {\n      expectedBytes: data.byteLength,\n      idleTimeoutMillis: DEFAULT_SHA1_IDLE_TIMEOUT_MILLIS,\n    },\n  )\n}\n\n/**\n * Streams a B2 download under a local sync root with path, timeout, and size checks.\n *\n * @param root - Local sync root.\n * @param relPath - Destination path relative to the root.\n * @param body - Download body stream.\n * @param options - Expected byte count, idle timeout, and optional abort signal.\n *\n * @internal\n */\nexport async function writeLocalStreamInsideRoot(\n  root: string,\n  relPath: string,\n  body: ReadableStream<Uint8Array>,\n  options: {\n    readonly expectedBytes: number\n    readonly expectedDestination?: LocalSyncPath | null\n    readonly idleTimeoutMillis: number\n    readonly signal?: AbortSignal\n  },\n): Promise<void> {\n  const { constants } = await import('node:fs')\n  const { link, lstat, mkdir, open, realpath, rename, rm, stat } = await import('node:fs/promises')\n  const path = await import('node:path')\n  const { randomUUID } = await import('node:crypto')\n  assertValidExpectedBytes(options.expectedBytes)\n  const segments = safeRelativePathSegments(relPath)\n  if (isDownloadStagingDirectorySegment(segments[0])) {\n    throw new Error(\n      `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`,\n    )\n  }\n  const rootRealPath = await realpath(root)\n\n  let current = rootRealPath\n  for (const segment of segments.slice(0, -1)) {\n    current = path.join(current, segment)\n    try {\n      await mkdir(current)\n    } catch (err) {\n      if (!hasErrorCode(err, 'EEXIST')) throw err\n    }\n    const stats = await lstat(current)\n    if (!stats.isDirectory()) {\n      throw new Error('unsafe local destination path: parent is not a directory')\n    }\n    await localFileIoTestHooks.afterParentDirectoryValidated?.(current)\n  }\n\n  const destPath = path.join(rootRealPath, ...segments)\n  assertPathInsideRoot(rootRealPath, destPath, path)\n\n  const parentRealPath = await realpath(path.dirname(destPath))\n  const finalPath = path.join(parentRealPath, path.basename(destPath))\n  assertPathInsideRoot(rootRealPath, finalPath, path)\n  try {\n    const targetStats = await lstat(finalPath)\n    if (targetStats.isSymbolicLink()) {\n      throw new Error('unsafe local destination path: target is a symbolic link')\n    }\n    if (targetStats.isFile() && targetStats.nlink > 1) {\n      throw new Error('unsafe local destination path: target has multiple hard links')\n    }\n  } catch (err) {\n    if (!hasErrorCode(err, 'ENOENT')) throw err\n  }\n  const statForDeviceCheck = localFileIoTestHooks.statForDeviceCheck ?? stat\n  await assertDownloadPathSameDevice(\n    rootRealPath,\n    parentRealPath,\n    statForDeviceCheck,\n    'unsafe local destination path: cannot publish download across filesystems',\n  )\n\n  let parentHandle: Awaited<ReturnType<typeof open>> | undefined\n  let anchoredParentPath: string | undefined\n  const platform = (globalThis as { process?: { platform?: string } }).process?.platform\n  /* v8 ignore start -- Linux-only fd-relative path support is covered by Linux CI */\n  if (\n    platform === 'linux' &&\n    constants.O_DIRECTORY !== undefined &&\n    localFileIoTestHooks.disableProcFdAnchoring !== true\n  ) {\n    try {\n      parentHandle = await open(\n        parentRealPath,\n        constants.O_RDONLY | constants.O_DIRECTORY | noFollowFlag(constants),\n      )\n      anchoredParentPath = `/proc/self/fd/${parentHandle.fd}`\n    } catch (err) {\n      if (hasErrorCode(err, 'ELOOP') || hasErrorCode(err, 'ENOTDIR')) {\n        throw new Error('unsafe local destination path: parent is not a directory')\n      }\n      throw err\n    }\n  }\n  /* v8 ignore stop */\n  const finalName = path.basename(destPath)\n  const finalWritePath = path.join(anchoredParentPath ?? parentRealPath, finalName)\n  let publishMode: number\n  try {\n    publishMode = await replacementFileMode(finalPath)\n  } catch (err) {\n    /* v8 ignore next -- best-effort close during setup failure */\n    await parentHandle?.close().catch(() => {})\n    throw err\n  }\n  let stagingDirectory: string\n  try {\n    stagingDirectory = await createDownloadStagingDirectory(\n      rootRealPath,\n      path,\n      randomUUID,\n      statForDeviceCheck,\n      localFileIoTestHooks.beforeStagingMarkerWrite,\n    )\n  } catch (err) {\n    /* v8 ignore next -- best-effort close during setup failure */\n    await parentHandle?.close().catch(() => {})\n    throw err\n  }\n  const tmpPath = path.join(stagingDirectory, `.b2sdk-${randomUUID()}.partial`)\n  let handle: Awaited<ReturnType<typeof open>> | undefined\n  try {\n    handle = await open(\n      tmpPath,\n      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(constants),\n      PRIVATE_DOWNLOAD_FILE_MODE,\n    )\n    /* v8 ignore next -- best-effort chmod */\n    await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {})\n    await localFileIoTestHooks.afterTempFileCreated?.(tmpPath, stagingDirectory)\n    /* v8 ignore start -- defensive cleanup before the main write try/finally exists */\n  } catch (err) {\n    await parentHandle?.close().catch(() => {})\n    await rm(stagingDirectory, { recursive: true, force: true }).catch(() => {})\n    throw err\n  }\n  /* v8 ignore stop */\n  try {\n    const tmpRealPath = await realpath(tmpPath)\n    assertPathInsideRoot(stagingDirectory, tmpRealPath, path)\n  } catch (err) {\n    /* v8 ignore next -- best-effort cleanup */\n    await handle?.close().catch(() => {})\n    /* v8 ignore next -- best-effort cleanup */\n    await rm(tmpPath, { force: true }).catch(() => {})\n    /* v8 ignore next -- best-effort cleanup */\n    await rm(stagingDirectory, { recursive: true, force: true }).catch(() => {})\n    /* v8 ignore next -- best-effort cleanup */\n    await parentHandle?.close().catch(() => {})\n    throw err\n  }\n  const writeHandle = handle\n  const reader = body.getReader()\n  let completed = false\n  try {\n    let bytesWritten = 0\n    while (true) {\n      const { done, value } = await readStreamChunkWithTimeout(\n        reader,\n        options.idleTimeoutMillis,\n        `download read stalled for ${options.idleTimeoutMillis} ms`,\n        options.signal,\n      )\n      if (done) break\n      if (bytesWritten + value.byteLength > options.expectedBytes) {\n        throw new Error(`download read exceeded ${options.expectedBytes} byte limit`)\n      }\n      await writeAll(writeHandle, value, bytesWritten)\n      bytesWritten += value.byteLength\n    }\n    if (bytesWritten !== options.expectedBytes) {\n      throw new Error(\n        `download read ended after ${bytesWritten} bytes, expected ${options.expectedBytes}`,\n      )\n    }\n    if (publishMode !== PRIVATE_DOWNLOAD_FILE_MODE) {\n      /* v8 ignore next -- best-effort mode preservation */\n      await writeHandle.chmod(publishMode).catch(() => {})\n    }\n    await writeHandle.close()\n    handle = undefined\n\n    const [parentRealPathBeforeRename, parentStatsBeforeRename] = await Promise.all([\n      realpath(path.dirname(destPath)),\n      stat(path.dirname(destPath)),\n    ])\n    const finalPathBeforeRename = path.join(parentRealPathBeforeRename, path.basename(destPath))\n    assertPathInsideRoot(rootRealPath, finalPathBeforeRename, path)\n    await localFileIoTestHooks.beforeFinalRename?.(parentRealPathBeforeRename)\n    let publishPath = finalWritePath\n    if (anchoredParentPath === undefined) {\n      const [parentRealPathAfterHook, parentStatsAfterHook] = await Promise.all([\n        realpath(path.dirname(destPath)),\n        stat(path.dirname(destPath)),\n      ])\n      if (\n        parentRealPathAfterHook !== parentRealPathBeforeRename ||\n        !sameParentIdentity(parentStatsAfterHook, parentStatsBeforeRename)\n      ) {\n        throw new Error('unsafe local destination path: parent changed before final publish')\n      }\n      publishPath = path.join(parentRealPathAfterHook, path.basename(destPath))\n      assertPathInsideRoot(rootRealPath, publishPath, path)\n    }\n    await publishDownload(\n      lstat,\n      link,\n      path,\n      randomUUID,\n      rename,\n      rm,\n      tmpPath,\n      publishPath,\n      options.expectedDestination,\n    )\n    completed = true\n  } catch (err) {\n    /* v8 ignore next -- best-effort cleanup */\n    void reader.cancel(err).catch(() => {})\n    throw err\n  } finally {\n    reader.releaseLock()\n    if (!completed) {\n      /* v8 ignore next -- best-effort cleanup */\n      await handle?.close().catch(() => {})\n      /* v8 ignore next -- best-effort cleanup */\n      await rm(tmpPath, { force: true }).catch(() => {})\n    }\n    /* v8 ignore next -- best-effort cleanup */\n    await rm(stagingDirectory, { recursive: true, force: true }).catch(() => {})\n    /* v8 ignore next -- best-effort cleanup */\n    await parentHandle?.close().catch(() => {})\n  }\n}\n\nfunction assertValidExpectedBytes(expectedBytes: number): void {\n  if (!Number.isSafeInteger(expectedBytes) || expectedBytes < 0) {\n    throw new Error('download expectedBytes must be a non-negative safe integer')\n  }\n}\n\nasync function assertExpectedDownloadDestination(\n  lstat: typeof import('node:fs/promises')['lstat'],\n  finalPath: string,\n  expectedDestination: LocalSyncPath | null | undefined,\n): Promise<void> {\n  if (expectedDestination === undefined) return\n\n  try {\n    const stats = await lstat(finalPath)\n    if (expectedDestination === null) {\n      throw new Error('local destination changed before download: file was created')\n    }\n    assertSameScannedRegularFile(\n      stats,\n      { ...expectedDestination, absolutePath: finalPath },\n      'download',\n      { platform: localFileIoTestHooks.platform },\n    )\n  } catch (err) {\n    if (hasErrorCode(err, 'ENOENT')) {\n      if (expectedDestination === null) return\n      throw new Error('local file changed before download: file missing')\n    }\n    throw err\n  }\n}\n\nasync function publishDownload(\n  lstat: typeof import('node:fs/promises')['lstat'],\n  link: typeof import('node:fs/promises')['link'],\n  path: typeof import('node:path'),\n  randomUUID: () => string,\n  rename: typeof import('node:fs/promises')['rename'],\n  rm: typeof import('node:fs/promises')['rm'],\n  tmpPath: string,\n  publishPath: string,\n  expectedDestination: LocalSyncPath | null | undefined,\n): Promise<void> {\n  await assertExpectedDownloadDestination(lstat, publishPath, expectedDestination)\n  await localFileIoTestHooks.beforeDownloadPublish?.(publishPath)\n\n  if (expectedDestination === undefined) {\n    await rename(tmpPath, publishPath)\n    return\n  }\n\n  if (expectedDestination === null) {\n    await linkDownloadNoOverwrite(\n      link,\n      tmpPath,\n      publishPath,\n      'local destination changed before download: file was created',\n    )\n    /* v8 ignore next -- staging cleanup is best-effort after a guarded publish succeeds. */\n    await rm(tmpPath, { force: true }).catch(() => {})\n    return\n  }\n\n  const backupPath = path.join(\n    path.dirname(publishPath),\n    makeReservedSyncTempFileName(path.basename(publishPath), randomUUID()),\n  )\n  let backupExists = false\n  let removeBackup = false\n\n  try {\n    try {\n      await rename(publishPath, backupPath)\n      backupExists = true\n      await localFileIoTestHooks.afterDownloadBackupRename?.(backupPath)\n    } catch (err) {\n      if (hasErrorCode(err, 'ENOENT')) {\n        throw new Error('local file changed before download: file missing')\n      }\n      throw err\n    }\n\n    const backupStats = await lstat(backupPath)\n    assertSameScannedRegularFile(\n      backupStats,\n      { ...expectedDestination, absolutePath: backupPath },\n      'download',\n      { compareChangeTime: false, platform: localFileIoTestHooks.platform },\n    )\n    await linkDownloadNoOverwrite(\n      link,\n      tmpPath,\n      publishPath,\n      'local destination changed before download: file was created',\n    )\n    removeBackup = true\n    /* v8 ignore next -- staging cleanup is best-effort after a guarded publish succeeds. */\n    await rm(tmpPath, { force: true }).catch(() => {})\n  } catch (err) {\n    if (backupExists && !removeBackup) {\n      await restoreBackupWithoutOverwrite(link, rm, backupPath, publishPath).catch(() => {})\n    }\n    throw err\n  } finally {\n    if (removeBackup) {\n      /* v8 ignore next -- old destination cleanup is best-effort after publish succeeds. */\n      await rm(backupPath, { force: true }).catch(() => {})\n    }\n  }\n}\n\nasync function linkDownloadNoOverwrite(\n  link: typeof import('node:fs/promises')['link'],\n  sourcePath: string,\n  destPath: string,\n  message: string,\n): Promise<void> {\n  try {\n    await link(sourcePath, destPath)\n  } catch (err) {\n    if (hasErrorCode(err, 'EEXIST')) throw new Error(message)\n    throw err\n  }\n}\n\nasync function restoreBackupWithoutOverwrite(\n  link: typeof import('node:fs/promises')['link'],\n  rm: typeof import('node:fs/promises')['rm'],\n  backupPath: string,\n  publishPath: string,\n): Promise<void> {\n  try {\n    await link(backupPath, publishPath)\n    await rm(backupPath, { force: true })\n  } catch (err) {\n    if (hasErrorCode(err, 'EEXIST')) return\n    throw err\n  }\n}\n\nconst PRIVATE_DOWNLOAD_FILE_MODE = 0o600\nasync function replacementFileMode(filePath: string): Promise<number> {\n  const { lstat } = await import('node:fs/promises')\n  try {\n    const stats = await lstat(filePath)\n    return stats.isFile() ? stats.mode & 0o777 : PRIVATE_DOWNLOAD_FILE_MODE\n  } catch (err) {\n    if (hasErrorCode(err, 'ENOENT')) return PRIVATE_DOWNLOAD_FILE_MODE\n    throw err\n  }\n}\n\n/**\n * Deletes a scanned local file under a sync root without re-resolving attacker-controlled parents.\n *\n * @param root - Local sync root.\n * @param scannedPath - Previously scanned local file metadata.\n *\n * @internal\n */\nexport async function deleteLocalFileInsideRoot(\n  root: string,\n  scannedPath: LocalSyncPath,\n): Promise<void> {\n  if (root === '') {\n    throw new Error('Local sync root required for filesystem mutation')\n  }\n\n  const { constants } = await import('node:fs')\n  const { lstat, open, realpath, stat, unlink } = await import('node:fs/promises')\n  const path = await import('node:path')\n  const segments = safeRelativePathSegments(scannedPath.relativePath)\n  const safeRoot = path.resolve(root)\n  const rootStats = await lstat(safeRoot)\n  if (rootStats.isSymbolicLink()) {\n    throw new Error(`Refusing to access sync root through symlink: ${scannedPath.relativePath}`)\n  }\n  if (!rootStats.isDirectory()) {\n    throw new Error(`Local sync root is not a directory: ${scannedPath.relativePath}`)\n  }\n  const rootRealPath = await realpath(safeRoot)\n  const expectedPath = path.join(rootRealPath, ...segments)\n  assertPathInsideRoot(rootRealPath, expectedPath, path)\n\n  const scannerPath = path.resolve(scannedPath.absolutePath)\n  if (scannerPath !== expectedPath) {\n    throw new Error(`Refusing to delete outside sync root: ${scannedPath.relativePath}`)\n  }\n\n  const [parentRealPath, parentStats] = await Promise.all([\n    realpath(path.dirname(expectedPath)),\n    stat(path.dirname(expectedPath)),\n  ])\n  const finalPath = path.join(parentRealPath, path.basename(expectedPath))\n  assertPathInsideRoot(rootRealPath, finalPath, path)\n\n  const platform = (globalThis as { process?: { platform?: string } }).process?.platform\n  let parentHandle: Awaited<ReturnType<typeof open>> | undefined\n  let anchoredParentPath: string | undefined\n  /* v8 ignore start -- Linux-only fd-relative path support is covered by Linux CI */\n  if (\n    platform === 'linux' &&\n    constants.O_DIRECTORY !== undefined &&\n    localFileIoTestHooks.disableProcFdAnchoring !== true\n  ) {\n    try {\n      await localFileIoTestHooks.beforeLocalDeleteOpenParent?.(parentRealPath)\n      parentHandle = await open(\n        parentRealPath,\n        constants.O_RDONLY | constants.O_DIRECTORY | noFollowFlag(constants),\n      )\n      anchoredParentPath = `/proc/self/fd/${parentHandle.fd}`\n    } catch (err) {\n      if (hasErrorCode(err, 'ELOOP') || hasErrorCode(err, 'ENOTDIR')) {\n        throw new Error('unsafe local delete path: parent is not a directory')\n      }\n      throw err\n    }\n  }\n  /* v8 ignore stop */\n\n  try {\n    const unlinkPath =\n      anchoredParentPath === undefined\n        ? finalPath\n        : path.join(anchoredParentPath, path.basename(expectedPath))\n    const stats = await lstat(unlinkPath)\n    assertSameScannedRegularFile(stats, { ...scannedPath, absolutePath: unlinkPath }, 'delete', {\n      platform: localFileIoTestHooks.platform,\n    })\n    await localFileIoTestHooks.beforeLocalDeleteUnlink?.(parentRealPath)\n    if (\n      anchoredParentPath === undefined &&\n      localFileIoTestHooks.disableProcFdAnchoring === true &&\n      parentRealPath !== rootRealPath\n    ) {\n      throw new Error('unsafe local delete path: stable parent handle unavailable for unlink')\n    }\n\n    if (anchoredParentPath === undefined) {\n      const [parentRealPathBeforeUnlink, parentStatsBeforeUnlink] = await Promise.all([\n        realpath(path.dirname(expectedPath)),\n        stat(path.dirname(expectedPath)),\n      ])\n      if (\n        parentRealPathBeforeUnlink !== parentRealPath ||\n        !sameParentIdentity(parentStatsBeforeUnlink, parentStats)\n      ) {\n        throw new Error('unsafe local delete path: parent changed before unlink')\n      }\n    }\n    const finalStats = await lstat(unlinkPath)\n    assertSameScannedRegularFile(\n      finalStats,\n      { ...scannedPath, absolutePath: unlinkPath },\n      'delete',\n      { platform: localFileIoTestHooks.platform },\n    )\n    await unlink(unlinkPath)\n  } finally {\n    /* v8 ignore next -- best-effort cleanup */\n    await parentHandle?.close().catch(() => {})\n  }\n}\n\nfunction sameParentIdentity(\n  current: { readonly dev: number | bigint; readonly ino: number | bigint },\n  expected: { readonly dev: number | bigint; readonly ino: number | bigint },\n): boolean {\n  return current.dev === expected.dev && current.ino === expected.ino\n}\n\nasync function writeAll(\n  handle: {\n    write(\n      buffer: Uint8Array,\n      offset: number,\n      length: number,\n      position: number,\n    ): Promise<{ readonly bytesWritten: number }>\n  },\n  data: Uint8Array,\n  position: number,\n): Promise<void> {\n  let offset = 0\n  while (offset < data.byteLength) {\n    const { bytesWritten } = await handle.write(\n      data,\n      offset,\n      data.byteLength - offset,\n      position + offset,\n    )\n    /* v8 ignore next -- defensive: FileHandle.write should progress for non-empty chunks. */\n    if (bytesWritten <= 0) throw new Error('download write made no progress')\n    offset += bytesWritten\n  }\n}\n"],"mappings":"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"}

package/dist/sync/local-file-io.d.cts

@@ -0,0 +1,75 @@
+import { DOWNLOAD_STAGING_DIRECTORY_NAME } from './download-staging.js';
+import { LocalSyncPath } from './types.js';
+type DeviceStat = {
+    readonly dev: number | bigint;
+};
+type DeviceStatFn = (path: string) => Promise<DeviceStat>;
+export { DOWNLOAD_STAGING_DIRECTORY_NAME };
+/** @internal */
+export declare const localFileIoTestHooks: {
+    afterParentDirectoryValidated?: (path: string) => Promise<void> | void;
+    afterDownloadBackupRename?: (path: string) => Promise<void> | void;
+    afterTempFileCreated?: (path: string, stagingDirectory: string) => Promise<void> | void;
+    beforeDownloadPublish?: (path: string) => Promise<void> | void;
+    beforeFinalRename?: (path: string) => Promise<void> | void;
+    beforeLocalDeleteOpenParent?: (path: string) => Promise<void> | void;
+    beforeLocalDeleteUnlink?: (path: string) => Promise<void> | void;
+    beforeStagingMarkerWrite?: (path: string) => Promise<void> | void;
+    disableProcFdAnchoring?: boolean;
+    platform?: string;
+    statForDeviceCheck?: DeviceStatFn;
+};
+/**
+ * Verifies that a previously scanned local file still points at the same regular file.
+ *
+ * @param path - Scanned local path and file identity.
+ *
+ * @internal
+ */
+export declare function validateScannedLocalFile(path: LocalSyncPath): Promise<void>;
+/**
+ * Reads a previously scanned local file while rejecting symlink swaps and metadata drift.
+ *
+ * @param path - Scanned local path and file identity.
+ *
+ * @returns The file bytes.
+ *
+ * @internal
+ */
+export declare function readScannedLocalFile(path: LocalSyncPath): Promise<Uint8Array>;
+/**
+ * Writes bytes under a local sync root after path containment checks.
+ *
+ * @param root - Local sync root.
+ * @param relPath - Destination path relative to the root.
+ * @param data - Bytes to write.
+ *
+ * @internal
+ */
+export declare function writeLocalFileInsideRoot(root: string, relPath: string, data: Uint8Array): Promise<void>;
+/**
+ * Streams a B2 download under a local sync root with path, timeout, and size checks.
+ *
+ * @param root - Local sync root.
+ * @param relPath - Destination path relative to the root.
+ * @param body - Download body stream.
+ * @param options - Expected byte count, idle timeout, and optional abort signal.
+ *
+ * @internal
+ */
+export declare function writeLocalStreamInsideRoot(root: string, relPath: string, body: ReadableStream<Uint8Array>, options: {
+    readonly expectedBytes: number;
+    readonly expectedDestination?: LocalSyncPath | null;
+    readonly idleTimeoutMillis: number;
+    readonly signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * Deletes a scanned local file under a sync root without re-resolving attacker-controlled parents.
+ *
+ * @param root - Local sync root.
+ * @param scannedPath - Previously scanned local file metadata.
+ *
+ * @internal
+ */
+export declare function deleteLocalFileInsideRoot(root: string, scannedPath: LocalSyncPath): Promise<void>;
+//# sourceMappingURL=local-file-io.d.ts.map

package/dist/sync/local-file-io.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-io.d.ts","sourceRoot":"","sources":["../../src/sync/local-file-io.js"],"names":[],"mappings":"AAEA,OAAO,EAGL,+BAA+B,EAEhC,MAAM,uBAAuB,CAAA;AAU9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AACnD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEzD,OAAO,EAAE,+BAA+B,EAAE,CAAA;AAE1C,gBAAgB;AAChB,eAAO,MAAM,oBAAoB,EAAE;IACjC,6BAA6B,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACtE,yBAAyB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAClE,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACvF,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1D,2BAA2B,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACpE,uBAAuB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAChE,wBAAwB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACjE,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kBAAkB,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAeN;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjF;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAWnF;AA6BD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,OAAO,EAAE;IACP,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B,GACA,OAAO,CAAC,IAAI,CAAC,CAuNf;AA2JD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,aAAa,GACzB,OAAO,CAAC,IAAI,CAAC,CAoGf"}

package/dist/sync/local-file-io.d.ts

@@ -0,0 +1,75 @@
+import { DOWNLOAD_STAGING_DIRECTORY_NAME } from './download-staging.js';
+import { LocalSyncPath } from './types.js';
+type DeviceStat = {
+    readonly dev: number | bigint;
+};
+type DeviceStatFn = (path: string) => Promise<DeviceStat>;
+export { DOWNLOAD_STAGING_DIRECTORY_NAME };
+/** @internal */
+export declare const localFileIoTestHooks: {
+    afterParentDirectoryValidated?: (path: string) => Promise<void> | void;
+    afterDownloadBackupRename?: (path: string) => Promise<void> | void;
+    afterTempFileCreated?: (path: string, stagingDirectory: string) => Promise<void> | void;
+    beforeDownloadPublish?: (path: string) => Promise<void> | void;
+    beforeFinalRename?: (path: string) => Promise<void> | void;
+    beforeLocalDeleteOpenParent?: (path: string) => Promise<void> | void;
+    beforeLocalDeleteUnlink?: (path: string) => Promise<void> | void;
+    beforeStagingMarkerWrite?: (path: string) => Promise<void> | void;
+    disableProcFdAnchoring?: boolean;
+    platform?: string;
+    statForDeviceCheck?: DeviceStatFn;
+};
+/**
+ * Verifies that a previously scanned local file still points at the same regular file.
+ *
+ * @param path - Scanned local path and file identity.
+ *
+ * @internal
+ */
+export declare function validateScannedLocalFile(path: LocalSyncPath): Promise<void>;
+/**
+ * Reads a previously scanned local file while rejecting symlink swaps and metadata drift.
+ *
+ * @param path - Scanned local path and file identity.
+ *
+ * @returns The file bytes.
+ *
+ * @internal
+ */
+export declare function readScannedLocalFile(path: LocalSyncPath): Promise<Uint8Array>;
+/**
+ * Writes bytes under a local sync root after path containment checks.
+ *
+ * @param root - Local sync root.
+ * @param relPath - Destination path relative to the root.
+ * @param data - Bytes to write.
+ *
+ * @internal
+ */
+export declare function writeLocalFileInsideRoot(root: string, relPath: string, data: Uint8Array): Promise<void>;
+/**
+ * Streams a B2 download under a local sync root with path, timeout, and size checks.
+ *
+ * @param root - Local sync root.
+ * @param relPath - Destination path relative to the root.
+ * @param body - Download body stream.
+ * @param options - Expected byte count, idle timeout, and optional abort signal.
+ *
+ * @internal
+ */
+export declare function writeLocalStreamInsideRoot(root: string, relPath: string, body: ReadableStream<Uint8Array>, options: {
+    readonly expectedBytes: number;
+    readonly expectedDestination?: LocalSyncPath | null;
+    readonly idleTimeoutMillis: number;
+    readonly signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * Deletes a scanned local file under a sync root without re-resolving attacker-controlled parents.
+ *
+ * @param root - Local sync root.
+ * @param scannedPath - Previously scanned local file metadata.
+ *
+ * @internal
+ */
+export declare function deleteLocalFileInsideRoot(root: string, scannedPath: LocalSyncPath): Promise<void>;
+//# sourceMappingURL=local-file-io.d.ts.map

package/dist/sync/local-file-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-io.d.ts","sourceRoot":"","sources":["../../src/sync/local-file-io.js"],"names":[],"mappings":"AAEA,OAAO,EAGL,+BAA+B,EAEhC,MAAM,uBAAuB,CAAA;AAU9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AACnD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEzD,OAAO,EAAE,+BAA+B,EAAE,CAAA;AAE1C,gBAAgB;AAChB,eAAO,MAAM,oBAAoB,EAAE;IACjC,6BAA6B,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACtE,yBAAyB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAClE,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACvF,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC9D,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1D,2BAA2B,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACpE,uBAAuB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAChE,wBAAwB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACjE,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kBAAkB,CAAC,EAAE,YAAY,CAAA;CAC7B,CAAA;AAeN;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjF;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAWnF;AA6BD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,OAAO,EAAE;IACP,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B,GACA,OAAO,CAAC,IAAI,CAAC,CAuNf;AA2JD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,aAAa,GACzB,OAAO,CAAC,IAAI,CAAC,CAoGf"}