@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/sync/pairing.js.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.js","sources":["../../src/sync/pairing.ts"],"sourcesContent":["import type { SyncFolder, SyncPath } from './types.ts'\n\n/** A paired tuple of source and destination files. Either side may be null if the file is absent. */\nexport type SyncPair = readonly [SyncPath | null, SyncPath | null]\n\n/**\n * Merge-joins two sorted folder scans by relative path, yielding paired tuples.\n * Files present only in source yield `[source, null]`, only in dest yield `[null, dest]`,\n * and files in both yield `[source, dest]`.\n *\n * @param source - The source folder to scan.\n * @param dest - The destination folder to scan.\n */\nexport async function* zipFolders(source: SyncFolder, dest: SyncFolder): AsyncGenerator<SyncPair> {\n  const sourceIter = source.scan()[Symbol.asyncIterator]()\n  const destIter = dest.scan()[Symbol.asyncIterator]()\n\n  let sourceResult = await sourceIter.next()\n  let destResult = await destIter.next()\n\n  while (!sourceResult.done || !destResult.done) {\n    const s = sourceResult.done ? null : sourceResult.value\n    const d = destResult.done ? null : destResult.value\n\n    if (s === null) {\n      yield [null, d]\n      destResult = await destIter.next()\n    } else if (d === null) {\n      yield [s, null]\n      sourceResult = await sourceIter.next()\n    } else if (s.relativePath < d.relativePath) {\n      yield [s, null]\n      sourceResult = await sourceIter.next()\n    } else if (d.relativePath < s.relativePath) {\n      yield [null, d]\n      destResult = await destIter.next()\n    } else {\n      yield [s, d]\n      sourceResult = await sourceIter.next()\n      destResult = await destIter.next()\n    }\n  }\n}\n"],"names":[],"mappings":"AAaA,gBAAuB,WAAW,QAAoB,MAA4C;AAChG,QAAM,aAAa,OAAO,KAAA,EAAO,OAAO,aAAa,EAAA;AACrD,QAAM,WAAW,KAAK,KAAA,EAAO,OAAO,aAAa,EAAA;AAEjD,MAAI,eAAe,MAAM,WAAW,KAAA;AACpC,MAAI,aAAa,MAAM,SAAS,KAAA;AAEhC,SAAO,CAAC,aAAa,QAAQ,CAAC,WAAW,MAAM;AAC7C,UAAM,IAAI,aAAa,OAAO,OAAO,aAAa;AAClD,UAAM,IAAI,WAAW,OAAO,OAAO,WAAW;AAE9C,QAAI,MAAM,MAAM;AACd,YAAM,CAAC,MAAM,CAAC;AACd,mBAAa,MAAM,SAAS,KAAA;AAAA,IAC9B,WAAW,MAAM,MAAM;AACrB,YAAM,CAAC,GAAG,IAAI;AACd,qBAAe,MAAM,WAAW,KAAA;AAAA,IAClC,WAAW,EAAE,eAAe,EAAE,cAAc;AAC1C,YAAM,CAAC,GAAG,IAAI;AACd,qBAAe,MAAM,WAAW,KAAA;AAAA,IAClC,WAAW,EAAE,eAAe,EAAE,cAAc;AAC1C,YAAM,CAAC,MAAM,CAAC;AACd,mBAAa,MAAM,SAAS,KAAA;AAAA,IAC9B,OAAO;AACL,YAAM,CAAC,GAAG,CAAC;AACX,qBAAe,MAAM,WAAW,KAAA;AAChC,mBAAa,MAAM,SAAS,KAAA;AAAA,IAC9B;AAAA,EACF;AACF;"}
+{"version":3,"file":"pairing.js","names":[],"sources":["../../src/sync/pairing.ts"],"sourcesContent":["import { filterSyncPaths } from './filters.ts'\nimport { compareSyncRelativePaths } from './path-order.ts'\nimport { validateSyncFilters } from './regexp-safety.ts'\nimport { assertScanEntryLimit, scanEntryLimit } from './scan-limit.ts'\nimport type {\n  SyncFilterPattern,\n  SyncFolder,\n  SyncPath,\n  SyncScanOptions,\n  SyncSkipEvent,\n} from './types.ts'\n\n/** A paired tuple of source and destination files. Either side may be null if the file is absent. */\nexport type SyncPair = readonly [SyncPath | null, SyncPath | null]\n\n/**\n * Merge-joins two sorted folder scans by relative path, yielding paired tuples.\n * Files present only in source yield `[source, null]`, only in dest yield `[null, dest]`,\n * and files in both yield `[source, dest]`.\n *\n * @param source - The source folder to scan.\n * @param dest - The destination folder to scan.\n * @param options - Optional scan controls and filters shared by both folders.\n * @param scanCallbacks - Optional internal source/destination skip callbacks.\n */\nexport async function* zipFolders(\n  source: SyncFolder,\n  dest: SyncFolder,\n  options: SyncScanOptions = {},\n  scanCallbacks: {\n    readonly onSourceSkip?: (event: SyncSkipEvent) => void\n    readonly onDestSkip?: (event: SyncSkipEvent) => void\n  } = {},\n): AsyncGenerator<SyncPair> {\n  validateSyncFilters(options)\n  const sourceOptions = scanOptionsSnapshot(options, scanCallbacks.onSourceSkip)\n  const destOptions = scanOptionsSnapshot(options, scanCallbacks.onDestSkip)\n  const sourceIter = scanWithFilters(source, sourceOptions)[Symbol.asyncIterator]()\n  const destIter = scanWithFilters(dest, destOptions)[Symbol.asyncIterator]()\n  let sourceDone = false\n  let destDone = false\n\n  try {\n    let [sourceResult, destResult] = await Promise.all([sourceIter.next(), destIter.next()])\n    sourceDone = sourceResult.done === true\n    destDone = destResult.done === true\n\n    while (!sourceResult.done || !destResult.done) {\n      const s = sourceResult.done ? null : sourceResult.value\n      const d = destResult.done ? null : destResult.value\n\n      if (s === null) {\n        yield [null, d]\n        destResult = await destIter.next()\n        destDone = destResult.done === true\n      } else if (d === null) {\n        yield [s, null]\n        sourceResult = await sourceIter.next()\n        sourceDone = sourceResult.done === true\n      } else {\n        const comparison = compareSyncRelativePaths(s.relativePath, d.relativePath)\n        if (comparison < 0) {\n          yield [s, null]\n          sourceResult = await sourceIter.next()\n          sourceDone = sourceResult.done === true\n        } else if (comparison > 0) {\n          yield [null, d]\n          destResult = await destIter.next()\n          destDone = destResult.done === true\n        } else {\n          yield [s, d]\n          sourceResult = await sourceIter.next()\n          destResult = await destIter.next()\n          sourceDone = sourceResult.done === true\n          destDone = destResult.done === true\n        }\n      }\n    }\n  } finally {\n    await closeScanIterator(sourceIter, sourceDone)\n    await closeScanIterator(destIter, destDone)\n  }\n}\n\nasync function closeScanIterator(\n  iterator: AsyncIterator<SyncPath>,\n  alreadyDone: boolean,\n): Promise<void> {\n  if (alreadyDone || iterator.return === undefined) return\n  try {\n    await iterator.return()\n  } catch {\n    // Best-effort scanner cleanup should not mask the original stop reason.\n  }\n}\n\nfunction scanWithFilters(\n  folder: SyncFolder,\n  options: { readonly scanner: SyncScanOptions; readonly sdk: SyncScanOptions },\n): AsyncIterable<SyncPath> {\n  const scanned = filterSyncPaths(folder.scan(options.scanner), options.sdk)\n  if (folder.appliesScanSorting === true) return limitSyncPaths(scanned, options.sdk)\n  return sortSyncPaths(scanned, options.sdk)\n}\n\nasync function* limitSyncPaths(\n  paths: AsyncIterable<SyncPath>,\n  filters: SyncScanOptions | undefined,\n): AsyncGenerator<SyncPath> {\n  const maxScanEntries = scanEntryLimit(filters)\n  let count = 0\n  for await (const path of paths) {\n    count++\n    assertScanEntryLimit(count, maxScanEntries)\n    yield path\n  }\n}\n\nasync function* sortSyncPaths(\n  paths: AsyncIterable<SyncPath>,\n  filters: SyncScanOptions | undefined,\n): AsyncGenerator<SyncPath> {\n  const maxScanEntries = scanEntryLimit(filters)\n  const collected: SyncPath[] = []\n  for await (const path of paths) {\n    collected.push(path)\n    assertScanEntryLimit(collected.length, maxScanEntries)\n  }\n  collected.sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath))\n  yield* collected\n}\n\nfunction scanOptionsSnapshot(\n  options: SyncScanOptions,\n  onSkip: ((event: SyncSkipEvent) => void) | undefined,\n): { readonly scanner: SyncScanOptions; readonly sdk: SyncScanOptions } {\n  const onSkipSnapshot =\n    options.onSkip === undefined && onSkip === undefined\n      ? undefined\n      : (event: SyncSkipEvent): void => {\n          options.onSkip?.(event)\n          onSkip?.(event)\n        }\n\n  return {\n    scanner: frozenScanOptions(\n      options,\n      frozenPatterns(options.include),\n      frozenPatterns(options.exclude),\n      onSkipSnapshot,\n    ),\n    sdk: frozenScanOptions(\n      options,\n      frozenPatterns(options.include),\n      frozenPatterns(options.exclude),\n      onSkipSnapshot,\n    ),\n  }\n}\n\nfunction frozenScanOptions(\n  options: SyncScanOptions,\n  include: readonly SyncFilterPattern[] | undefined,\n  exclude: readonly SyncFilterPattern[] | undefined,\n  onSkip: ((event: SyncSkipEvent) => void) | undefined,\n): SyncScanOptions {\n  return Object.freeze({\n    ...(include !== undefined ? { include } : {}),\n    ...(exclude !== undefined ? { exclude } : {}),\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n    ...(options.onError !== undefined ? { onError: options.onError } : {}),\n    ...(onSkip !== undefined ? { onSkip } : {}),\n    ...(options.requireLocalSafePaths !== undefined\n      ? { requireLocalSafePaths: options.requireLocalSafePaths }\n      : {}),\n    ...(options.maxScanEntries !== undefined ? { maxScanEntries: options.maxScanEntries } : {}),\n  })\n}\n\nfunction frozenPatterns(\n  patterns: readonly SyncFilterPattern[] | undefined,\n): readonly SyncFilterPattern[] | undefined {\n  return patterns === undefined ? undefined : Object.freeze([...patterns])\n}\n"],"mappings":"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"}

package/dist/sync/path-order.cjs

@@ -0,0 +1,30 @@
+//#region src/sync/path-order.ts
+/**
+* Compares sync-relative paths using the same code-unit order everywhere sorted scans are consumed.
+*
+* @param left - First sync-relative path.
+* @param right - Second sync-relative path.
+*
+* @returns Negative, zero, or positive using JavaScript code-unit order.
+*/
+function compareSyncRelativePaths(left, right) {
+	return compareCodeUnits(left, right);
+}
+/**
+* Compares strings by JavaScript code-unit order.
+*
+* @param left - First string.
+* @param right - Second string.
+*
+* @returns Negative, zero, or positive using code-unit order.
+*/
+function compareCodeUnits(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+//#endregion
+exports.compareCodeUnits = compareCodeUnits;
+exports.compareSyncRelativePaths = compareSyncRelativePaths;
+
+//# sourceMappingURL=path-order.cjs.map

package/dist/sync/path-order.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.cjs","names":[],"sources":["../../src/sync/path-order.ts"],"sourcesContent":["/**\n * Compares sync-relative paths using the same code-unit order everywhere sorted scans are consumed.\n *\n * @param left - First sync-relative path.\n * @param right - Second sync-relative path.\n *\n * @returns Negative, zero, or positive using JavaScript code-unit order.\n */\nexport function compareSyncRelativePaths(left: string, right: string): number {\n  return compareCodeUnits(left, right)\n}\n\n/**\n * Backwards-compatible alias for the SDK scan ordering.\n *\n * @param a - First sync-relative path.\n * @param b - Second sync-relative path.\n *\n * @returns Negative, zero, or positive using JavaScript code-unit order.\n */\nexport function compareSyncPathNames(a: string, b: string): number {\n  return compareSyncRelativePaths(a, b)\n}\n\n/**\n * Compares strings by JavaScript code-unit order.\n *\n * @param left - First string.\n * @param right - Second string.\n *\n * @returns Negative, zero, or positive using code-unit order.\n */\nexport function compareCodeUnits(left: string, right: string): number {\n  if (left < right) return -1\n  if (left > right) return 1\n  return 0\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,yBAAyB,MAAc,OAAuB;CAC5E,OAAO,iBAAiB,MAAM,KAAK;AACrC;;;;;;;;;AAsBA,SAAgB,iBAAiB,MAAc,OAAuB;CACpE,IAAI,OAAO,OAAO,OAAO;CACzB,IAAI,OAAO,OAAO,OAAO;CACzB,OAAO;AACT"}

package/dist/sync/path-order.d.cts

@@ -0,0 +1,28 @@
+/**
+ * Compares sync-relative paths using the same code-unit order everywhere sorted scans are consumed.
+ *
+ * @param left - First sync-relative path.
+ * @param right - Second sync-relative path.
+ *
+ * @returns Negative, zero, or positive using JavaScript code-unit order.
+ */
+export declare function compareSyncRelativePaths(left: string, right: string): number;
+/**
+ * Backwards-compatible alias for the SDK scan ordering.
+ *
+ * @param a - First sync-relative path.
+ * @param b - Second sync-relative path.
+ *
+ * @returns Negative, zero, or positive using JavaScript code-unit order.
+ */
+export declare function compareSyncPathNames(a: string, b: string): number;
+/**
+ * Compares strings by JavaScript code-unit order.
+ *
+ * @param left - First string.
+ * @param right - Second string.
+ *
+ * @returns Negative, zero, or positive using code-unit order.
+ */
+export declare function compareCodeUnits(left: string, right: string): number;
+//# sourceMappingURL=path-order.d.ts.map

package/dist/sync/path-order.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.d.ts","sourceRoot":"","sources":["../../src/sync/path-order.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE"}

package/dist/sync/path-order.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Compares sync-relative paths using the same code-unit order everywhere sorted scans are consumed.
+ *
+ * @param left - First sync-relative path.
+ * @param right - Second sync-relative path.
+ *
+ * @returns Negative, zero, or positive using JavaScript code-unit order.
+ */
+export declare function compareSyncRelativePaths(left: string, right: string): number;
+/**
+ * Backwards-compatible alias for the SDK scan ordering.
+ *
+ * @param a - First sync-relative path.
+ * @param b - Second sync-relative path.
+ *
+ * @returns Negative, zero, or positive using JavaScript code-unit order.
+ */
+export declare function compareSyncPathNames(a: string, b: string): number;
+/**
+ * Compares strings by JavaScript code-unit order.
+ *
+ * @param left - First string.
+ * @param right - Second string.
+ *
+ * @returns Negative, zero, or positive using code-unit order.
+ */
+export declare function compareCodeUnits(left: string, right: string): number;
+//# sourceMappingURL=path-order.d.ts.map

package/dist/sync/path-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.d.ts","sourceRoot":"","sources":["../../src/sync/path-order.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE"}

package/dist/sync/path-order.js

@@ -0,0 +1,29 @@
+//#region src/sync/path-order.ts
+/**
+* Compares sync-relative paths using the same code-unit order everywhere sorted scans are consumed.
+*
+* @param left - First sync-relative path.
+* @param right - Second sync-relative path.
+*
+* @returns Negative, zero, or positive using JavaScript code-unit order.
+*/
+function compareSyncRelativePaths(left, right) {
+	return compareCodeUnits(left, right);
+}
+/**
+* Compares strings by JavaScript code-unit order.
+*
+* @param left - First string.
+* @param right - Second string.
+*
+* @returns Negative, zero, or positive using code-unit order.
+*/
+function compareCodeUnits(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+//#endregion
+export { compareCodeUnits, compareSyncRelativePaths };
+
+//# sourceMappingURL=path-order.js.map

package/dist/sync/path-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-order.js","names":[],"sources":["../../src/sync/path-order.ts"],"sourcesContent":["/**\n * Compares sync-relative paths using the same code-unit order everywhere sorted scans are consumed.\n *\n * @param left - First sync-relative path.\n * @param right - Second sync-relative path.\n *\n * @returns Negative, zero, or positive using JavaScript code-unit order.\n */\nexport function compareSyncRelativePaths(left: string, right: string): number {\n  return compareCodeUnits(left, right)\n}\n\n/**\n * Backwards-compatible alias for the SDK scan ordering.\n *\n * @param a - First sync-relative path.\n * @param b - Second sync-relative path.\n *\n * @returns Negative, zero, or positive using JavaScript code-unit order.\n */\nexport function compareSyncPathNames(a: string, b: string): number {\n  return compareSyncRelativePaths(a, b)\n}\n\n/**\n * Compares strings by JavaScript code-unit order.\n *\n * @param left - First string.\n * @param right - Second string.\n *\n * @returns Negative, zero, or positive using code-unit order.\n */\nexport function compareCodeUnits(left: string, right: string): number {\n  if (left < right) return -1\n  if (left > right) return 1\n  return 0\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,yBAAyB,MAAc,OAAuB;CAC5E,OAAO,iBAAiB,MAAM,KAAK;AACrC;;;;;;;;;AAsBA,SAAgB,iBAAiB,MAAc,OAAuB;CACpE,IAAI,OAAO,OAAO,OAAO;CACzB,IAAI,OAAO,OAAO,OAAO;CACzB,OAAO;AACT"}

package/dist/sync/path-safety.cjs

@@ -0,0 +1,111 @@
+//#region src/sync/path-safety.ts
+var RESERVED_SYNC_TEMP_FILE_RE = /^\.b2sdk-[0-9a-f]{24}-[^/\\]+-[0-9a-f]{32}\.partial$/i;
+var UUID_HEX_RE = /^[0-9a-f]{32}$/i;
+/**
+* Checks whether a basename is reserved for SDK-owned sync partial files.
+* @param name - Basename to inspect.
+*
+* @returns Whether the basename matches the SDK reserved partial-file pattern.
+*
+* @internal
+*/
+function isReservedSyncTempFileName(name) {
+	return RESERVED_SYNC_TEMP_FILE_RE.test(name);
+}
+/**
+* Rejects sync paths whose basename is reserved for SDK-owned temporary files.
+* @param relativePath - Sync-relative path using slash separators.
+*
+* @throws If any path segment uses the SDK's reserved temporary-file pattern.
+*
+* @internal
+*/
+function assertSyncPathAllowed(relativePath) {
+	if (relativePath.split(/[\\/]+/).filter(Boolean).some((part) => isReservedSyncTempFileName(part))) throw new Error(`Sync path uses reserved SDK temporary-file name: ${relativePath}`);
+}
+/**
+* Creates a download staging basename inside the SDK-reserved temp namespace.
+* @param finalName - Final destination basename.
+* @param uuid - UUID used to make the temp basename unique.
+*
+* @returns A basename that local and B2 scanners reject as SDK-owned temp data.
+*
+* @throws If the provided UUID cannot be normalized to 32 hex characters.
+*
+* @internal
+*/
+function makeReservedSyncTempFileName(finalName, uuid) {
+	if (finalName.length === 0 || /[\\/]/.test(finalName)) throw new Error("invalid sync temporary-file basename");
+	const hex = uuid.replaceAll("-", "").toLowerCase();
+	if (!UUID_HEX_RE.test(hex)) throw new Error("invalid sync temporary-file nonce");
+	return `.b2sdk-${hex.slice(0, 24)}-${finalName}-${hex}.partial`;
+}
+/**
+* Validates B2 relative names before they are materialized on a local filesystem.
+*
+* @param relPath - B2-style relative path.
+*
+* @returns Validated path segments.
+*
+* @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.
+*
+* @internal
+*/
+function safeRelativePathSegments(relPath) {
+	assertSyncPathAllowed(relPath);
+	if (relPath.length === 0 || relPath.includes("\0") || relPath.includes("\\") || relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath)) throw new Error("unsafe local destination path");
+	const segments = relPath.split("/");
+	if (segments.some((segment) => segment.length === 0 || segment === "." || segment === ".." || segment.includes(":") || segment.endsWith(".") || segment.endsWith(" ") || WINDOWS_RESERVED_NAME.test(segment))) throw new Error("unsafe local destination path");
+	return segments;
+}
+var WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3])(?:\..*)?$/i;
+/**
+* Throws if {@link target} is outside {@link root} or names the root itself.
+*
+* @param root - Resolved filesystem root.
+* @param target - Candidate path to validate.
+* @param path - Node path module.
+*
+* @throws When the target is outside the root or equal to the root.
+*
+* @internal
+*/
+function assertPathInsideRoot(root, target, path) {
+	const relative = path.relative(root, target);
+	if (relative.length === 0 || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error("unsafe local destination path");
+}
+/**
+* Returns the platform's no-follow open flag when available.
+*
+* @param constants - Node filesystem constants.
+*
+* @returns The `O_NOFOLLOW` bit or `0`.
+*
+* @internal
+*/
+function noFollowFlag(constants) {
+	return constants.O_NOFOLLOW ?? 0;
+}
+/**
+* Checks whether an unknown thrown value has a specific Node error code.
+*
+* @param err - Unknown thrown value.
+* @param code - Expected Node error code.
+*
+* @returns True when the value exposes the expected code.
+*
+* @internal
+*/
+function hasErrorCode(err, code) {
+	return err.code === code;
+}
+//#endregion
+exports.assertPathInsideRoot = assertPathInsideRoot;
+exports.assertSyncPathAllowed = assertSyncPathAllowed;
+exports.hasErrorCode = hasErrorCode;
+exports.isReservedSyncTempFileName = isReservedSyncTempFileName;
+exports.makeReservedSyncTempFileName = makeReservedSyncTempFileName;
+exports.noFollowFlag = noFollowFlag;
+exports.safeRelativePathSegments = safeRelativePathSegments;
+
+//# sourceMappingURL=path-safety.cjs.map

package/dist/sync/path-safety.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.cjs","names":[],"sources":["../../src/sync/path-safety.ts"],"sourcesContent":["const RESERVED_SYNC_TEMP_FILE_RE = /^\\.b2sdk-[0-9a-f]{24}-[^/\\\\]+-[0-9a-f]{32}\\.partial$/i\nconst UUID_HEX_RE = /^[0-9a-f]{32}$/i\n\n/**\n * Checks whether a basename is reserved for SDK-owned sync partial files.\n * @param name - Basename to inspect.\n *\n * @returns Whether the basename matches the SDK reserved partial-file pattern.\n *\n * @internal\n */\nexport function isReservedSyncTempFileName(name: string): boolean {\n  return RESERVED_SYNC_TEMP_FILE_RE.test(name)\n}\n\n/**\n * Rejects sync paths whose basename is reserved for SDK-owned temporary files.\n * @param relativePath - Sync-relative path using slash separators.\n *\n * @throws If any path segment uses the SDK's reserved temporary-file pattern.\n *\n * @internal\n */\nexport function assertSyncPathAllowed(relativePath: string): void {\n  const parts = relativePath.split(/[\\\\/]+/).filter(Boolean)\n  if (parts.some((part) => isReservedSyncTempFileName(part))) {\n    throw new Error(`Sync path uses reserved SDK temporary-file name: ${relativePath}`)\n  }\n}\n\n/**\n * Creates a download staging basename inside the SDK-reserved temp namespace.\n * @param finalName - Final destination basename.\n * @param uuid - UUID used to make the temp basename unique.\n *\n * @returns A basename that local and B2 scanners reject as SDK-owned temp data.\n *\n * @throws If the provided UUID cannot be normalized to 32 hex characters.\n *\n * @internal\n */\nexport function makeReservedSyncTempFileName(finalName: string, uuid: string): string {\n  if (finalName.length === 0 || /[\\\\/]/.test(finalName)) {\n    throw new Error('invalid sync temporary-file basename')\n  }\n  const hex = uuid.replaceAll('-', '').toLowerCase()\n  if (!UUID_HEX_RE.test(hex)) {\n    throw new Error('invalid sync temporary-file nonce')\n  }\n  return `.b2sdk-${hex.slice(0, 24)}-${finalName}-${hex}.partial`\n}\n\n/**\n * Validates B2 relative names before they are materialized on a local filesystem.\n *\n * @param relPath - B2-style relative path.\n *\n * @returns Validated path segments.\n *\n * @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.\n *\n * @internal\n */\nexport function safeRelativePathSegments(relPath: string): string[] {\n  assertSyncPathAllowed(relPath)\n  if (\n    relPath.length === 0 ||\n    relPath.includes('\\0') ||\n    relPath.includes('\\\\') ||\n    relPath.startsWith('/') ||\n    /^[A-Za-z]:/.test(relPath)\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n\n  const segments = relPath.split('/')\n  if (\n    segments.some(\n      (segment) =>\n        segment.length === 0 ||\n        segment === '.' ||\n        segment === '..' ||\n        segment.includes(':') ||\n        segment.endsWith('.') ||\n        segment.endsWith(' ') ||\n        WINDOWS_RESERVED_NAME.test(segment),\n    )\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n  return segments\n}\n\nconst WINDOWS_RESERVED_NAME =\n  /^(con|prn|aux|nul|conin\\$|conout\\$|com[0-9\\u00b9\\u00b2\\u00b3]|lpt[0-9\\u00b9\\u00b2\\u00b3])(?:\\..*)?$/i\n\n/**\n * Throws if {@link target} is outside {@link root} or names the root itself.\n *\n * @param root - Resolved filesystem root.\n * @param target - Candidate path to validate.\n * @param path - Node path module.\n *\n * @throws When the target is outside the root or equal to the root.\n *\n * @internal\n */\nexport function assertPathInsideRoot(\n  root: string,\n  target: string,\n  path: typeof import('node:path'),\n): void {\n  const relative = path.relative(root, target)\n  if (\n    relative.length === 0 ||\n    relative === '..' ||\n    relative.startsWith(`..${path.sep}`) ||\n    path.isAbsolute(relative)\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n}\n\n/**\n * Returns the platform's no-follow open flag when available.\n *\n * @param constants - Node filesystem constants.\n *\n * @returns The `O_NOFOLLOW` bit or `0`.\n *\n * @internal\n */\nexport function noFollowFlag(constants: { readonly O_NOFOLLOW?: number }): number {\n  return constants.O_NOFOLLOW ?? 0\n}\n\n/**\n * Checks whether an unknown thrown value has a specific Node error code.\n *\n * @param err - Unknown thrown value.\n * @param code - Expected Node error code.\n *\n * @returns True when the value exposes the expected code.\n *\n * @internal\n */\nexport function hasErrorCode(err: unknown, code: string): boolean {\n  return (err as { readonly code?: unknown }).code === code\n}\n"],"mappings":";AAAA,IAAM,6BAA6B;AACnC,IAAM,cAAc;;;;;;;;;AAUpB,SAAgB,2BAA2B,MAAuB;CAChE,OAAO,2BAA2B,KAAK,IAAI;AAC7C;;;;;;;;;AAUA,SAAgB,sBAAsB,cAA4B;CAEhE,IADc,aAAa,MAAM,QAAQ,CAAC,CAAC,OAAO,OAC9C,CAAA,CAAM,MAAM,SAAS,2BAA2B,IAAI,CAAC,GACvD,MAAM,IAAI,MAAM,oDAAoD,cAAc;AAEtF;;;;;;;;;;;;AAaA,SAAgB,6BAA6B,WAAmB,MAAsB;CACpF,IAAI,UAAU,WAAW,KAAK,QAAQ,KAAK,SAAS,GAClD,MAAM,IAAI,MAAM,sCAAsC;CAExD,MAAM,MAAM,KAAK,WAAW,KAAK,EAAE,CAAC,CAAC,YAAY;CACjD,IAAI,CAAC,YAAY,KAAK,GAAG,GACvB,MAAM,IAAI,MAAM,mCAAmC;CAErD,OAAO,UAAU,IAAI,MAAM,GAAG,EAAE,EAAE,GAAG,UAAU,GAAG,IAAI;AACxD;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,SAA2B;CAClE,sBAAsB,OAAO;CAC7B,IACE,QAAQ,WAAW,KACnB,QAAQ,SAAS,IAAI,KACrB,QAAQ,SAAS,IAAI,KACrB,QAAQ,WAAW,GAAG,KACtB,aAAa,KAAK,OAAO,GAEzB,MAAM,IAAI,MAAM,+BAA+B;CAGjD,MAAM,WAAW,QAAQ,MAAM,GAAG;CAClC,IACE,SAAS,MACN,YACC,QAAQ,WAAW,KACnB,YAAY,OACZ,YAAY,QACZ,QAAQ,SAAS,GAAG,KACpB,QAAQ,SAAS,GAAG,KACpB,QAAQ,SAAS,GAAG,KACpB,sBAAsB,KAAK,OAAO,CACtC,GAEA,MAAM,IAAI,MAAM,+BAA+B;CAEjD,OAAO;AACT;AAEA,IAAM,wBACJ;;;;;;;;;;;;AAaF,SAAgB,qBACd,MACA,QACA,MACM;CACN,MAAM,WAAW,KAAK,SAAS,MAAM,MAAM;CAC3C,IACE,SAAS,WAAW,KACpB,aAAa,QACb,SAAS,WAAW,KAAK,KAAK,KAAK,KACnC,KAAK,WAAW,QAAQ,GAExB,MAAM,IAAI,MAAM,+BAA+B;AAEnD;;;;;;;;;;AAWA,SAAgB,aAAa,WAAqD;CAChF,OAAO,UAAU,cAAc;AACjC;;;;;;;;;;;AAYA,SAAgB,aAAa,KAAc,MAAuB;CAChE,OAAQ,IAAoC,SAAS;AACvD"}

package/dist/sync/path-safety.d.cts

@@ -0,0 +1,78 @@
+/**
+ * Checks whether a basename is reserved for SDK-owned sync partial files.
+ * @param name - Basename to inspect.
+ *
+ * @returns Whether the basename matches the SDK reserved partial-file pattern.
+ *
+ * @internal
+ */
+export declare function isReservedSyncTempFileName(name: string): boolean;
+/**
+ * Rejects sync paths whose basename is reserved for SDK-owned temporary files.
+ * @param relativePath - Sync-relative path using slash separators.
+ *
+ * @throws If any path segment uses the SDK's reserved temporary-file pattern.
+ *
+ * @internal
+ */
+export declare function assertSyncPathAllowed(relativePath: string): void;
+/**
+ * Creates a download staging basename inside the SDK-reserved temp namespace.
+ * @param finalName - Final destination basename.
+ * @param uuid - UUID used to make the temp basename unique.
+ *
+ * @returns A basename that local and B2 scanners reject as SDK-owned temp data.
+ *
+ * @throws If the provided UUID cannot be normalized to 32 hex characters.
+ *
+ * @internal
+ */
+export declare function makeReservedSyncTempFileName(finalName: string, uuid: string): string;
+/**
+ * Validates B2 relative names before they are materialized on a local filesystem.
+ *
+ * @param relPath - B2-style relative path.
+ *
+ * @returns Validated path segments.
+ *
+ * @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.
+ *
+ * @internal
+ */
+export declare function safeRelativePathSegments(relPath: string): string[];
+/**
+ * Throws if {@link target} is outside {@link root} or names the root itself.
+ *
+ * @param root - Resolved filesystem root.
+ * @param target - Candidate path to validate.
+ * @param path - Node path module.
+ *
+ * @throws When the target is outside the root or equal to the root.
+ *
+ * @internal
+ */
+export declare function assertPathInsideRoot(root: string, target: string, path: typeof import('node:path')): void;
+/**
+ * Returns the platform's no-follow open flag when available.
+ *
+ * @param constants - Node filesystem constants.
+ *
+ * @returns The `O_NOFOLLOW` bit or `0`.
+ *
+ * @internal
+ */
+export declare function noFollowFlag(constants: {
+    readonly O_NOFOLLOW?: number;
+}): number;
+/**
+ * Checks whether an unknown thrown value has a specific Node error code.
+ *
+ * @param err - Unknown thrown value.
+ * @param code - Expected Node error code.
+ *
+ * @returns True when the value exposes the expected code.
+ *
+ * @internal
+ */
+export declare function hasErrorCode(err: unknown, code: string): boolean;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/sync/path-safety.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../src/sync/path-safety.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CASpF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BlE;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,WAAW,CAAC,GAC/B,IAAI,CAUN;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE"}

package/dist/sync/path-safety.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Checks whether a basename is reserved for SDK-owned sync partial files.
+ * @param name - Basename to inspect.
+ *
+ * @returns Whether the basename matches the SDK reserved partial-file pattern.
+ *
+ * @internal
+ */
+export declare function isReservedSyncTempFileName(name: string): boolean;
+/**
+ * Rejects sync paths whose basename is reserved for SDK-owned temporary files.
+ * @param relativePath - Sync-relative path using slash separators.
+ *
+ * @throws If any path segment uses the SDK's reserved temporary-file pattern.
+ *
+ * @internal
+ */
+export declare function assertSyncPathAllowed(relativePath: string): void;
+/**
+ * Creates a download staging basename inside the SDK-reserved temp namespace.
+ * @param finalName - Final destination basename.
+ * @param uuid - UUID used to make the temp basename unique.
+ *
+ * @returns A basename that local and B2 scanners reject as SDK-owned temp data.
+ *
+ * @throws If the provided UUID cannot be normalized to 32 hex characters.
+ *
+ * @internal
+ */
+export declare function makeReservedSyncTempFileName(finalName: string, uuid: string): string;
+/**
+ * Validates B2 relative names before they are materialized on a local filesystem.
+ *
+ * @param relPath - B2-style relative path.
+ *
+ * @returns Validated path segments.
+ *
+ * @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.
+ *
+ * @internal
+ */
+export declare function safeRelativePathSegments(relPath: string): string[];
+/**
+ * Throws if {@link target} is outside {@link root} or names the root itself.
+ *
+ * @param root - Resolved filesystem root.
+ * @param target - Candidate path to validate.
+ * @param path - Node path module.
+ *
+ * @throws When the target is outside the root or equal to the root.
+ *
+ * @internal
+ */
+export declare function assertPathInsideRoot(root: string, target: string, path: typeof import('node:path')): void;
+/**
+ * Returns the platform's no-follow open flag when available.
+ *
+ * @param constants - Node filesystem constants.
+ *
+ * @returns The `O_NOFOLLOW` bit or `0`.
+ *
+ * @internal
+ */
+export declare function noFollowFlag(constants: {
+    readonly O_NOFOLLOW?: number;
+}): number;
+/**
+ * Checks whether an unknown thrown value has a specific Node error code.
+ *
+ * @param err - Unknown thrown value.
+ * @param code - Expected Node error code.
+ *
+ * @returns True when the value exposes the expected code.
+ *
+ * @internal
+ */
+export declare function hasErrorCode(err: unknown, code: string): boolean;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/sync/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../src/sync/path-safety.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CASpF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BlE;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,WAAW,CAAC,GAC/B,IAAI,CAUN;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE"}

package/dist/sync/path-safety.js

@@ -0,0 +1,105 @@
+//#region src/sync/path-safety.ts
+var RESERVED_SYNC_TEMP_FILE_RE = /^\.b2sdk-[0-9a-f]{24}-[^/\\]+-[0-9a-f]{32}\.partial$/i;
+var UUID_HEX_RE = /^[0-9a-f]{32}$/i;
+/**
+* Checks whether a basename is reserved for SDK-owned sync partial files.
+* @param name - Basename to inspect.
+*
+* @returns Whether the basename matches the SDK reserved partial-file pattern.
+*
+* @internal
+*/
+function isReservedSyncTempFileName(name) {
+	return RESERVED_SYNC_TEMP_FILE_RE.test(name);
+}
+/**
+* Rejects sync paths whose basename is reserved for SDK-owned temporary files.
+* @param relativePath - Sync-relative path using slash separators.
+*
+* @throws If any path segment uses the SDK's reserved temporary-file pattern.
+*
+* @internal
+*/
+function assertSyncPathAllowed(relativePath) {
+	if (relativePath.split(/[\\/]+/).filter(Boolean).some((part) => isReservedSyncTempFileName(part))) throw new Error(`Sync path uses reserved SDK temporary-file name: ${relativePath}`);
+}
+/**
+* Creates a download staging basename inside the SDK-reserved temp namespace.
+* @param finalName - Final destination basename.
+* @param uuid - UUID used to make the temp basename unique.
+*
+* @returns A basename that local and B2 scanners reject as SDK-owned temp data.
+*
+* @throws If the provided UUID cannot be normalized to 32 hex characters.
+*
+* @internal
+*/
+function makeReservedSyncTempFileName(finalName, uuid) {
+	if (finalName.length === 0 || /[\\/]/.test(finalName)) throw new Error("invalid sync temporary-file basename");
+	const hex = uuid.replaceAll("-", "").toLowerCase();
+	if (!UUID_HEX_RE.test(hex)) throw new Error("invalid sync temporary-file nonce");
+	return `.b2sdk-${hex.slice(0, 24)}-${finalName}-${hex}.partial`;
+}
+/**
+* Validates B2 relative names before they are materialized on a local filesystem.
+*
+* @param relPath - B2-style relative path.
+*
+* @returns Validated path segments.
+*
+* @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.
+*
+* @internal
+*/
+function safeRelativePathSegments(relPath) {
+	assertSyncPathAllowed(relPath);
+	if (relPath.length === 0 || relPath.includes("\0") || relPath.includes("\\") || relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath)) throw new Error("unsafe local destination path");
+	const segments = relPath.split("/");
+	if (segments.some((segment) => segment.length === 0 || segment === "." || segment === ".." || segment.includes(":") || segment.endsWith(".") || segment.endsWith(" ") || WINDOWS_RESERVED_NAME.test(segment))) throw new Error("unsafe local destination path");
+	return segments;
+}
+var WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3])(?:\..*)?$/i;
+/**
+* Throws if {@link target} is outside {@link root} or names the root itself.
+*
+* @param root - Resolved filesystem root.
+* @param target - Candidate path to validate.
+* @param path - Node path module.
+*
+* @throws When the target is outside the root or equal to the root.
+*
+* @internal
+*/
+function assertPathInsideRoot(root, target, path) {
+	const relative = path.relative(root, target);
+	if (relative.length === 0 || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error("unsafe local destination path");
+}
+/**
+* Returns the platform's no-follow open flag when available.
+*
+* @param constants - Node filesystem constants.
+*
+* @returns The `O_NOFOLLOW` bit or `0`.
+*
+* @internal
+*/
+function noFollowFlag(constants) {
+	return constants.O_NOFOLLOW ?? 0;
+}
+/**
+* Checks whether an unknown thrown value has a specific Node error code.
+*
+* @param err - Unknown thrown value.
+* @param code - Expected Node error code.
+*
+* @returns True when the value exposes the expected code.
+*
+* @internal
+*/
+function hasErrorCode(err, code) {
+	return err.code === code;
+}
+//#endregion
+export { assertPathInsideRoot, assertSyncPathAllowed, hasErrorCode, isReservedSyncTempFileName, makeReservedSyncTempFileName, noFollowFlag, safeRelativePathSegments };
+
+//# sourceMappingURL=path-safety.js.map

package/dist/sync/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.js","names":[],"sources":["../../src/sync/path-safety.ts"],"sourcesContent":["const RESERVED_SYNC_TEMP_FILE_RE = /^\\.b2sdk-[0-9a-f]{24}-[^/\\\\]+-[0-9a-f]{32}\\.partial$/i\nconst UUID_HEX_RE = /^[0-9a-f]{32}$/i\n\n/**\n * Checks whether a basename is reserved for SDK-owned sync partial files.\n * @param name - Basename to inspect.\n *\n * @returns Whether the basename matches the SDK reserved partial-file pattern.\n *\n * @internal\n */\nexport function isReservedSyncTempFileName(name: string): boolean {\n  return RESERVED_SYNC_TEMP_FILE_RE.test(name)\n}\n\n/**\n * Rejects sync paths whose basename is reserved for SDK-owned temporary files.\n * @param relativePath - Sync-relative path using slash separators.\n *\n * @throws If any path segment uses the SDK's reserved temporary-file pattern.\n *\n * @internal\n */\nexport function assertSyncPathAllowed(relativePath: string): void {\n  const parts = relativePath.split(/[\\\\/]+/).filter(Boolean)\n  if (parts.some((part) => isReservedSyncTempFileName(part))) {\n    throw new Error(`Sync path uses reserved SDK temporary-file name: ${relativePath}`)\n  }\n}\n\n/**\n * Creates a download staging basename inside the SDK-reserved temp namespace.\n * @param finalName - Final destination basename.\n * @param uuid - UUID used to make the temp basename unique.\n *\n * @returns A basename that local and B2 scanners reject as SDK-owned temp data.\n *\n * @throws If the provided UUID cannot be normalized to 32 hex characters.\n *\n * @internal\n */\nexport function makeReservedSyncTempFileName(finalName: string, uuid: string): string {\n  if (finalName.length === 0 || /[\\\\/]/.test(finalName)) {\n    throw new Error('invalid sync temporary-file basename')\n  }\n  const hex = uuid.replaceAll('-', '').toLowerCase()\n  if (!UUID_HEX_RE.test(hex)) {\n    throw new Error('invalid sync temporary-file nonce')\n  }\n  return `.b2sdk-${hex.slice(0, 24)}-${finalName}-${hex}.partial`\n}\n\n/**\n * Validates B2 relative names before they are materialized on a local filesystem.\n *\n * @param relPath - B2-style relative path.\n *\n * @returns Validated path segments.\n *\n * @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.\n *\n * @internal\n */\nexport function safeRelativePathSegments(relPath: string): string[] {\n  assertSyncPathAllowed(relPath)\n  if (\n    relPath.length === 0 ||\n    relPath.includes('\\0') ||\n    relPath.includes('\\\\') ||\n    relPath.startsWith('/') ||\n    /^[A-Za-z]:/.test(relPath)\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n\n  const segments = relPath.split('/')\n  if (\n    segments.some(\n      (segment) =>\n        segment.length === 0 ||\n        segment === '.' ||\n        segment === '..' ||\n        segment.includes(':') ||\n        segment.endsWith('.') ||\n        segment.endsWith(' ') ||\n        WINDOWS_RESERVED_NAME.test(segment),\n    )\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n  return segments\n}\n\nconst WINDOWS_RESERVED_NAME =\n  /^(con|prn|aux|nul|conin\\$|conout\\$|com[0-9\\u00b9\\u00b2\\u00b3]|lpt[0-9\\u00b9\\u00b2\\u00b3])(?:\\..*)?$/i\n\n/**\n * Throws if {@link target} is outside {@link root} or names the root itself.\n *\n * @param root - Resolved filesystem root.\n * @param target - Candidate path to validate.\n * @param path - Node path module.\n *\n * @throws When the target is outside the root or equal to the root.\n *\n * @internal\n */\nexport function assertPathInsideRoot(\n  root: string,\n  target: string,\n  path: typeof import('node:path'),\n): void {\n  const relative = path.relative(root, target)\n  if (\n    relative.length === 0 ||\n    relative === '..' ||\n    relative.startsWith(`..${path.sep}`) ||\n    path.isAbsolute(relative)\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n}\n\n/**\n * Returns the platform's no-follow open flag when available.\n *\n * @param constants - Node filesystem constants.\n *\n * @returns The `O_NOFOLLOW` bit or `0`.\n *\n * @internal\n */\nexport function noFollowFlag(constants: { readonly O_NOFOLLOW?: number }): number {\n  return constants.O_NOFOLLOW ?? 0\n}\n\n/**\n * Checks whether an unknown thrown value has a specific Node error code.\n *\n * @param err - Unknown thrown value.\n * @param code - Expected Node error code.\n *\n * @returns True when the value exposes the expected code.\n *\n * @internal\n */\nexport function hasErrorCode(err: unknown, code: string): boolean {\n  return (err as { readonly code?: unknown }).code === code\n}\n"],"mappings":";AAAA,IAAM,6BAA6B;AACnC,IAAM,cAAc;;;;;;;;;AAUpB,SAAgB,2BAA2B,MAAuB;CAChE,OAAO,2BAA2B,KAAK,IAAI;AAC7C;;;;;;;;;AAUA,SAAgB,sBAAsB,cAA4B;CAEhE,IADc,aAAa,MAAM,QAAQ,CAAC,CAAC,OAAO,OAC9C,CAAA,CAAM,MAAM,SAAS,2BAA2B,IAAI,CAAC,GACvD,MAAM,IAAI,MAAM,oDAAoD,cAAc;AAEtF;;;;;;;;;;;;AAaA,SAAgB,6BAA6B,WAAmB,MAAsB;CACpF,IAAI,UAAU,WAAW,KAAK,QAAQ,KAAK,SAAS,GAClD,MAAM,IAAI,MAAM,sCAAsC;CAExD,MAAM,MAAM,KAAK,WAAW,KAAK,EAAE,CAAC,CAAC,YAAY;CACjD,IAAI,CAAC,YAAY,KAAK,GAAG,GACvB,MAAM,IAAI,MAAM,mCAAmC;CAErD,OAAO,UAAU,IAAI,MAAM,GAAG,EAAE,EAAE,GAAG,UAAU,GAAG,IAAI;AACxD;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,SAA2B;CAClE,sBAAsB,OAAO;CAC7B,IACE,QAAQ,WAAW,KACnB,QAAQ,SAAS,IAAI,KACrB,QAAQ,SAAS,IAAI,KACrB,QAAQ,WAAW,GAAG,KACtB,aAAa,KAAK,OAAO,GAEzB,MAAM,IAAI,MAAM,+BAA+B;CAGjD,MAAM,WAAW,QAAQ,MAAM,GAAG;CAClC,IACE,SAAS,MACN,YACC,QAAQ,WAAW,KACnB,YAAY,OACZ,YAAY,QACZ,QAAQ,SAAS,GAAG,KACpB,QAAQ,SAAS,GAAG,KACpB,QAAQ,SAAS,GAAG,KACpB,sBAAsB,KAAK,OAAO,CACtC,GAEA,MAAM,IAAI,MAAM,+BAA+B;CAEjD,OAAO;AACT;AAEA,IAAM,wBACJ;;;;;;;;;;;;AAaF,SAAgB,qBACd,MACA,QACA,MACM;CACN,MAAM,WAAW,KAAK,SAAS,MAAM,MAAM;CAC3C,IACE,SAAS,WAAW,KACpB,aAAa,QACb,SAAS,WAAW,KAAK,KAAK,KAAK,KACnC,KAAK,WAAW,QAAQ,GAExB,MAAM,IAAI,MAAM,+BAA+B;AAEnD;;;;;;;;;;AAWA,SAAgB,aAAa,WAAqD;CAChF,OAAO,UAAU,cAAc;AACjC;;;;;;;;;;;AAYA,SAAgB,aAAa,KAAc,MAAuB;CAChE,OAAQ,IAAoC,SAAS;AACvD"}

package/dist/sync/paths.d.cts

@@ -0,0 +1,19 @@
+export { assertSyncPathAllowed } from './path-safety.js';
+interface PathOperations {
+    isAbsolute(path: string): boolean;
+    resolve(...paths: string[]): string;
+    readonly sep: string;
+}
+/**
+ * Resolves a sync-relative path under a local root without allowing traversal
+ * or SDK-reserved temporary-file names.
+ * @param root - Absolute local sync root.
+ * @param relativePath - Sync-relative path to resolve.
+ * @param path - Node path operations for the local platform.
+ *
+ * @returns The absolute local filesystem path.
+ *
+ * @throws If the path is absolute, escapes the root, or uses a reserved basename.
+ */
+export declare function resolveSafeLocalPath(root: string, relativePath: string, path: PathOperations): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sync/paths.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/sync/paths.js"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,UAAU,cAAc;IACtB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,GACnB,MAAM,CAYR"}

package/dist/sync/paths.d.ts

@@ -0,0 +1,19 @@
+export { assertSyncPathAllowed } from './path-safety.js';
+interface PathOperations {
+    isAbsolute(path: string): boolean;
+    resolve(...paths: string[]): string;
+    readonly sep: string;
+}
+/**
+ * Resolves a sync-relative path under a local root without allowing traversal
+ * or SDK-reserved temporary-file names.
+ * @param root - Absolute local sync root.
+ * @param relativePath - Sync-relative path to resolve.
+ * @param path - Node path operations for the local platform.
+ *
+ * @returns The absolute local filesystem path.
+ *
+ * @throws If the path is absolute, escapes the root, or uses a reserved basename.
+ */
+export declare function resolveSafeLocalPath(root: string, relativePath: string, path: PathOperations): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sync/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/sync/paths.js"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,UAAU,cAAc;IACtB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,GACnB,MAAM,CAYR"}