@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/prefix.cjs

@@ -0,0 +1,96 @@
+const require_download_staging = require("./download-staging.cjs");
+//#region src/sync/prefix.ts
+/**
+* Treats the supplied string as a raw B2 key prefix without adding a folder boundary.
+*
+* B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real
+* key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should
+* pass `/` explicitly.
+*
+* @param prefix - User-supplied raw B2 key prefix.
+*
+* @returns Raw B2 key prefix.
+*/
+function asRawB2KeyPrefix(prefix) {
+	return prefix;
+}
+/**
+* Normalizes a B2 object name into a safe folder-relative sync path.
+*
+* Object names are converted to forward-slash sync paths for local compatibility. Callers that scan
+* B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.
+*
+* @param path - B2 object name or prefix-stripped suffix returned by a listing.
+* @param options - Optional normalization behavior for legacy slashless raw prefixes.
+*
+* @returns Folder-relative sync path.
+*
+* @throws When the object name cannot be represented as a safe relative path.
+*/
+function normalizeB2RelativePath(path, options = {}) {
+	const slashPath = path.split("\\").join("/");
+	const relativePath = options.stripLeadingSlashes === true ? stripSingleLeadingSlash(slashPath) : slashPath;
+	const segments = relativePath.split("/");
+	if (/^[A-Za-z]:/.test(relativePath) || segments.some((segment) => segmentIsUnsafe(segment))) throw new Error("Unsafe B2 file name cannot be used as a sync relative path");
+	return relativePath;
+}
+/**
+* Converts a B2 object key under a configured raw prefix into a sync relative path.
+*
+* @param prefix - Raw B2 key prefix used for the scan or mutation guard.
+* @param fileName - Full B2 object key.
+*
+* @returns The normalized sync relative path for the key suffix.
+*/
+function b2KeyToRelativePathUnderPrefix(prefix, fileName) {
+	const rawPrefix = asRawB2KeyPrefix(prefix);
+	return normalizeB2RelativePath(rawPrefix === "" ? fileName : fileName.slice(rawPrefix.length), { stripLeadingSlashes: rawPrefix !== "" && !rawPrefix.endsWith("/") });
+}
+/**
+* Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.
+* B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.
+*
+* @param relativePath - Folder-relative sync path.
+*
+* @returns True when any segment is Windows-dangerous or ambiguous.
+*/
+function localFilesystemSyncPathIsUnsafe(relativePath) {
+	const segments = relativePath.split("/");
+	return require_download_staging.isDownloadStagingDirectorySegment(segments[0]) || segments.some((segment) => segmentIsLocalFilesystemUnsafe(segment));
+}
+/**
+* Produces an approximate Windows/macOS-style canonical key for local collision detection.
+*
+* @param relativePath - Folder-relative sync path.
+*
+* @returns A canonicalized path key for detecting case/Unicode collisions before local writes.
+*/
+function localFilesystemCanonicalSyncPath(relativePath) {
+	return relativePath.split("/").map((segment) => segment.normalize("NFC").toLocaleLowerCase("en-US")).join("/");
+}
+function segmentIsUnsafe(segment) {
+	return segment === "" || segment === "." || segment === ".." || containsControlCharacter(segment);
+}
+function segmentIsLocalFilesystemUnsafe(segment) {
+	if (segment.includes(":") || segment.endsWith(".") || segment.endsWith(" ")) return true;
+	const basename = segment.split(".")[0]?.toUpperCase();
+	return basename !== void 0 && /^(CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|COM[0-9¹²³]|LPT[0-9¹²³])$/u.test(basename);
+}
+function containsControlCharacter(segment) {
+	for (let index = 0; index < segment.length; index++) {
+		const code = segment.charCodeAt(index);
+		if (code >= 0 && code <= 31) return true;
+	}
+	return false;
+}
+function stripSingleLeadingSlash(path) {
+	return path.startsWith("/") ? path.slice(1) : path;
+}
+//#endregion
+exports.asRawB2KeyPrefix = asRawB2KeyPrefix;
+exports.b2KeyToRelativePathUnderPrefix = b2KeyToRelativePathUnderPrefix;
+exports.localFilesystemCanonicalSyncPath = localFilesystemCanonicalSyncPath;
+exports.localFilesystemSyncPathIsUnsafe = localFilesystemSyncPathIsUnsafe;
+exports.normalizeB2RelativePath = normalizeB2RelativePath;
+
+//# sourceMappingURL=prefix.cjs.map

package/dist/sync/prefix.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.cjs","names":[],"sources":["../../src/sync/prefix.ts"],"sourcesContent":["import { isDownloadStagingDirectorySegment } from './download-staging.ts'\n\n/**\n * Treats the supplied string as a raw B2 key prefix without adding a folder boundary.\n *\n * B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real\n * key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should\n * pass `/` explicitly.\n *\n * @param prefix - User-supplied raw B2 key prefix.\n *\n * @returns Raw B2 key prefix.\n */\nexport function asRawB2KeyPrefix(prefix: string): string {\n  return prefix\n}\n\n/**\n * Normalizes a B2 object name into a safe folder-relative sync path.\n *\n * Object names are converted to forward-slash sync paths for local compatibility. Callers that scan\n * B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.\n *\n * @param path - B2 object name or prefix-stripped suffix returned by a listing.\n * @param options - Optional normalization behavior for legacy slashless raw prefixes.\n *\n * @returns Folder-relative sync path.\n *\n * @throws When the object name cannot be represented as a safe relative path.\n */\nexport function normalizeB2RelativePath(\n  path: string,\n  options: { readonly stripLeadingSlashes?: boolean } = {},\n): string {\n  const slashPath = path.split('\\\\').join('/')\n  const relativePath =\n    options.stripLeadingSlashes === true ? stripSingleLeadingSlash(slashPath) : slashPath\n  const segments = relativePath.split('/')\n  if (/^[A-Za-z]:/.test(relativePath) || segments.some((segment) => segmentIsUnsafe(segment))) {\n    throw new Error('Unsafe B2 file name cannot be used as a sync relative path')\n  }\n  return relativePath\n}\n\n/**\n * Converts a B2 object key under a configured raw prefix into a sync relative path.\n *\n * @param prefix - Raw B2 key prefix used for the scan or mutation guard.\n * @param fileName - Full B2 object key.\n *\n * @returns The normalized sync relative path for the key suffix.\n */\nexport function b2KeyToRelativePathUnderPrefix(prefix: string, fileName: string): string {\n  const rawPrefix = asRawB2KeyPrefix(prefix)\n  const suffix = rawPrefix === '' ? fileName : fileName.slice(rawPrefix.length)\n  return normalizeB2RelativePath(suffix, {\n    stripLeadingSlashes: rawPrefix !== '' && !rawPrefix.endsWith('/'),\n  })\n}\n\n/**\n * Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.\n * B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.\n *\n * @param relativePath - Folder-relative sync path.\n *\n * @returns True when any segment is Windows-dangerous or ambiguous.\n */\nexport function localFilesystemSyncPathIsUnsafe(relativePath: string): boolean {\n  const segments = relativePath.split('/')\n  return (\n    isDownloadStagingDirectorySegment(segments[0]) ||\n    segments.some((segment) => segmentIsLocalFilesystemUnsafe(segment))\n  )\n}\n\n/**\n * Produces an approximate Windows/macOS-style canonical key for local collision detection.\n *\n * @param relativePath - Folder-relative sync path.\n *\n * @returns A canonicalized path key for detecting case/Unicode collisions before local writes.\n */\nexport function localFilesystemCanonicalSyncPath(relativePath: string): string {\n  return relativePath\n    .split('/')\n    .map((segment) => segment.normalize('NFC').toLocaleLowerCase('en-US'))\n    .join('/')\n}\n\nfunction segmentIsUnsafe(segment: string): boolean {\n  return segment === '' || segment === '.' || segment === '..' || containsControlCharacter(segment)\n}\n\nfunction segmentIsLocalFilesystemUnsafe(segment: string): boolean {\n  if (segment.includes(':') || segment.endsWith('.') || segment.endsWith(' ')) return true\n  const basename = segment.split('.')[0]?.toUpperCase()\n  return (\n    basename !== undefined &&\n    /^(CON|PRN|AUX|NUL|CONIN\\$|CONOUT\\$|COM[0-9¹²³]|LPT[0-9¹²³])$/u.test(basename)\n  )\n}\n\nfunction containsControlCharacter(segment: string): boolean {\n  for (let index = 0; index < segment.length; index++) {\n    const code = segment.charCodeAt(index)\n    if (code >= 0 && code <= 31) return true\n  }\n  return false\n}\n\nfunction stripSingleLeadingSlash(path: string): string {\n  return path.startsWith('/') ? path.slice(1) : path\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,iBAAiB,QAAwB;CACvD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,wBACd,MACA,UAAsD,CAAC,GAC/C;CACR,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,GAAG;CAC3C,MAAM,eACJ,QAAQ,wBAAwB,OAAO,wBAAwB,SAAS,IAAI;CAC9E,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,IAAI,aAAa,KAAK,YAAY,KAAK,SAAS,MAAM,YAAY,gBAAgB,OAAO,CAAC,GACxF,MAAM,IAAI,MAAM,4DAA4D;CAE9E,OAAO;AACT;;;;;;;;;AAUA,SAAgB,+BAA+B,QAAgB,UAA0B;CACvF,MAAM,YAAY,iBAAiB,MAAM;CAEzC,OAAO,wBADQ,cAAc,KAAK,WAAW,SAAS,MAAM,UAAU,MAAM,GACrC,EACrC,qBAAqB,cAAc,MAAM,CAAC,UAAU,SAAS,GAAG,EAClE,CAAC;AACH;;;;;;;;;AAUA,SAAgB,gCAAgC,cAA+B;CAC7E,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,OACE,yBAAA,kCAAkC,SAAS,EAAE,KAC7C,SAAS,MAAM,YAAY,+BAA+B,OAAO,CAAC;AAEtE;;;;;;;;AASA,SAAgB,iCAAiC,cAA8B;CAC7E,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,KAAK,YAAY,QAAQ,UAAU,KAAK,CAAC,CAAC,kBAAkB,OAAO,CAAC,CAAC,CACrE,KAAK,GAAG;AACb;AAEA,SAAS,gBAAgB,SAA0B;CACjD,OAAO,YAAY,MAAM,YAAY,OAAO,YAAY,QAAQ,yBAAyB,OAAO;AAClG;AAEA,SAAS,+BAA+B,SAA0B;CAChE,IAAI,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,GAAG,GAAG,OAAO;CACpF,MAAM,WAAW,QAAQ,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,YAAY;CACpD,OACE,aAAa,KAAA,KACb,gEAAgE,KAAK,QAAQ;AAEjF;AAEA,SAAS,yBAAyB,SAA0B;CAC1D,KAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS;EACnD,MAAM,OAAO,QAAQ,WAAW,KAAK;EACrC,IAAI,QAAQ,KAAK,QAAQ,IAAI,OAAO;CACtC;CACA,OAAO;AACT;AAEA,SAAS,wBAAwB,MAAsB;CACrD,OAAO,KAAK,WAAW,GAAG,IAAI,KAAK,MAAM,CAAC,IAAI;AAChD"}

package/dist/sync/prefix.d.cts

@@ -0,0 +1,55 @@
+/**
+ * Treats the supplied string as a raw B2 key prefix without adding a folder boundary.
+ *
+ * B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real
+ * key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should
+ * pass `/` explicitly.
+ *
+ * @param prefix - User-supplied raw B2 key prefix.
+ *
+ * @returns Raw B2 key prefix.
+ */
+export declare function asRawB2KeyPrefix(prefix: string): string;
+/**
+ * Normalizes a B2 object name into a safe folder-relative sync path.
+ *
+ * Object names are converted to forward-slash sync paths for local compatibility. Callers that scan
+ * B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.
+ *
+ * @param path - B2 object name or prefix-stripped suffix returned by a listing.
+ * @param options - Optional normalization behavior for legacy slashless raw prefixes.
+ *
+ * @returns Folder-relative sync path.
+ *
+ * @throws When the object name cannot be represented as a safe relative path.
+ */
+export declare function normalizeB2RelativePath(path: string, options?: {
+    readonly stripLeadingSlashes?: boolean;
+}): string;
+/**
+ * Converts a B2 object key under a configured raw prefix into a sync relative path.
+ *
+ * @param prefix - Raw B2 key prefix used for the scan or mutation guard.
+ * @param fileName - Full B2 object key.
+ *
+ * @returns The normalized sync relative path for the key suffix.
+ */
+export declare function b2KeyToRelativePathUnderPrefix(prefix: string, fileName: string): string;
+/**
+ * Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.
+ * B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.
+ *
+ * @param relativePath - Folder-relative sync path.
+ *
+ * @returns True when any segment is Windows-dangerous or ambiguous.
+ */
+export declare function localFilesystemSyncPathIsUnsafe(relativePath: string): boolean;
+/**
+ * Produces an approximate Windows/macOS-style canonical key for local collision detection.
+ *
+ * @param relativePath - Folder-relative sync path.
+ *
+ * @returns A canonicalized path key for detecting case/Unicode collisions before local writes.
+ */
+export declare function localFilesystemCanonicalSyncPath(relativePath: string): string;
+//# sourceMappingURL=prefix.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.d.ts","sourceRoot":"","sources":["../../src/sync/prefix.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMvF;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAM7E;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAK7E"}

package/dist/sync/prefix.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Treats the supplied string as a raw B2 key prefix without adding a folder boundary.
+ *
+ * B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real
+ * key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should
+ * pass `/` explicitly.
+ *
+ * @param prefix - User-supplied raw B2 key prefix.
+ *
+ * @returns Raw B2 key prefix.
+ */
+export declare function asRawB2KeyPrefix(prefix: string): string;
+/**
+ * Normalizes a B2 object name into a safe folder-relative sync path.
+ *
+ * Object names are converted to forward-slash sync paths for local compatibility. Callers that scan
+ * B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.
+ *
+ * @param path - B2 object name or prefix-stripped suffix returned by a listing.
+ * @param options - Optional normalization behavior for legacy slashless raw prefixes.
+ *
+ * @returns Folder-relative sync path.
+ *
+ * @throws When the object name cannot be represented as a safe relative path.
+ */
+export declare function normalizeB2RelativePath(path: string, options?: {
+    readonly stripLeadingSlashes?: boolean;
+}): string;
+/**
+ * Converts a B2 object key under a configured raw prefix into a sync relative path.
+ *
+ * @param prefix - Raw B2 key prefix used for the scan or mutation guard.
+ * @param fileName - Full B2 object key.
+ *
+ * @returns The normalized sync relative path for the key suffix.
+ */
+export declare function b2KeyToRelativePathUnderPrefix(prefix: string, fileName: string): string;
+/**
+ * Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.
+ * B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.
+ *
+ * @param relativePath - Folder-relative sync path.
+ *
+ * @returns True when any segment is Windows-dangerous or ambiguous.
+ */
+export declare function localFilesystemSyncPathIsUnsafe(relativePath: string): boolean;
+/**
+ * Produces an approximate Windows/macOS-style canonical key for local collision detection.
+ *
+ * @param relativePath - Folder-relative sync path.
+ *
+ * @returns A canonicalized path key for detecting case/Unicode collisions before local writes.
+ */
+export declare function localFilesystemCanonicalSyncPath(relativePath: string): string;
+//# sourceMappingURL=prefix.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.d.ts","sourceRoot":"","sources":["../../src/sync/prefix.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMvF;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAM7E;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAK7E"}

package/dist/sync/prefix.js

@@ -0,0 +1,92 @@
+import { isDownloadStagingDirectorySegment } from "./download-staging.js";
+//#region src/sync/prefix.ts
+/**
+* Treats the supplied string as a raw B2 key prefix without adding a folder boundary.
+*
+* B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real
+* key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should
+* pass `/` explicitly.
+*
+* @param prefix - User-supplied raw B2 key prefix.
+*
+* @returns Raw B2 key prefix.
+*/
+function asRawB2KeyPrefix(prefix) {
+	return prefix;
+}
+/**
+* Normalizes a B2 object name into a safe folder-relative sync path.
+*
+* Object names are converted to forward-slash sync paths for local compatibility. Callers that scan
+* B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.
+*
+* @param path - B2 object name or prefix-stripped suffix returned by a listing.
+* @param options - Optional normalization behavior for legacy slashless raw prefixes.
+*
+* @returns Folder-relative sync path.
+*
+* @throws When the object name cannot be represented as a safe relative path.
+*/
+function normalizeB2RelativePath(path, options = {}) {
+	const slashPath = path.split("\\").join("/");
+	const relativePath = options.stripLeadingSlashes === true ? stripSingleLeadingSlash(slashPath) : slashPath;
+	const segments = relativePath.split("/");
+	if (/^[A-Za-z]:/.test(relativePath) || segments.some((segment) => segmentIsUnsafe(segment))) throw new Error("Unsafe B2 file name cannot be used as a sync relative path");
+	return relativePath;
+}
+/**
+* Converts a B2 object key under a configured raw prefix into a sync relative path.
+*
+* @param prefix - Raw B2 key prefix used for the scan or mutation guard.
+* @param fileName - Full B2 object key.
+*
+* @returns The normalized sync relative path for the key suffix.
+*/
+function b2KeyToRelativePathUnderPrefix(prefix, fileName) {
+	const rawPrefix = asRawB2KeyPrefix(prefix);
+	return normalizeB2RelativePath(rawPrefix === "" ? fileName : fileName.slice(rawPrefix.length), { stripLeadingSlashes: rawPrefix !== "" && !rawPrefix.endsWith("/") });
+}
+/**
+* Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.
+* B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.
+*
+* @param relativePath - Folder-relative sync path.
+*
+* @returns True when any segment is Windows-dangerous or ambiguous.
+*/
+function localFilesystemSyncPathIsUnsafe(relativePath) {
+	const segments = relativePath.split("/");
+	return isDownloadStagingDirectorySegment(segments[0]) || segments.some((segment) => segmentIsLocalFilesystemUnsafe(segment));
+}
+/**
+* Produces an approximate Windows/macOS-style canonical key for local collision detection.
+*
+* @param relativePath - Folder-relative sync path.
+*
+* @returns A canonicalized path key for detecting case/Unicode collisions before local writes.
+*/
+function localFilesystemCanonicalSyncPath(relativePath) {
+	return relativePath.split("/").map((segment) => segment.normalize("NFC").toLocaleLowerCase("en-US")).join("/");
+}
+function segmentIsUnsafe(segment) {
+	return segment === "" || segment === "." || segment === ".." || containsControlCharacter(segment);
+}
+function segmentIsLocalFilesystemUnsafe(segment) {
+	if (segment.includes(":") || segment.endsWith(".") || segment.endsWith(" ")) return true;
+	const basename = segment.split(".")[0]?.toUpperCase();
+	return basename !== void 0 && /^(CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|COM[0-9¹²³]|LPT[0-9¹²³])$/u.test(basename);
+}
+function containsControlCharacter(segment) {
+	for (let index = 0; index < segment.length; index++) {
+		const code = segment.charCodeAt(index);
+		if (code >= 0 && code <= 31) return true;
+	}
+	return false;
+}
+function stripSingleLeadingSlash(path) {
+	return path.startsWith("/") ? path.slice(1) : path;
+}
+//#endregion
+export { asRawB2KeyPrefix, b2KeyToRelativePathUnderPrefix, localFilesystemCanonicalSyncPath, localFilesystemSyncPathIsUnsafe, normalizeB2RelativePath };
+
+//# sourceMappingURL=prefix.js.map

package/dist/sync/prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.js","names":[],"sources":["../../src/sync/prefix.ts"],"sourcesContent":["import { isDownloadStagingDirectorySegment } from './download-staging.ts'\n\n/**\n * Treats the supplied string as a raw B2 key prefix without adding a folder boundary.\n *\n * B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real\n * key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should\n * pass `/` explicitly.\n *\n * @param prefix - User-supplied raw B2 key prefix.\n *\n * @returns Raw B2 key prefix.\n */\nexport function asRawB2KeyPrefix(prefix: string): string {\n  return prefix\n}\n\n/**\n * Normalizes a B2 object name into a safe folder-relative sync path.\n *\n * Object names are converted to forward-slash sync paths for local compatibility. Callers that scan\n * B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.\n *\n * @param path - B2 object name or prefix-stripped suffix returned by a listing.\n * @param options - Optional normalization behavior for legacy slashless raw prefixes.\n *\n * @returns Folder-relative sync path.\n *\n * @throws When the object name cannot be represented as a safe relative path.\n */\nexport function normalizeB2RelativePath(\n  path: string,\n  options: { readonly stripLeadingSlashes?: boolean } = {},\n): string {\n  const slashPath = path.split('\\\\').join('/')\n  const relativePath =\n    options.stripLeadingSlashes === true ? stripSingleLeadingSlash(slashPath) : slashPath\n  const segments = relativePath.split('/')\n  if (/^[A-Za-z]:/.test(relativePath) || segments.some((segment) => segmentIsUnsafe(segment))) {\n    throw new Error('Unsafe B2 file name cannot be used as a sync relative path')\n  }\n  return relativePath\n}\n\n/**\n * Converts a B2 object key under a configured raw prefix into a sync relative path.\n *\n * @param prefix - Raw B2 key prefix used for the scan or mutation guard.\n * @param fileName - Full B2 object key.\n *\n * @returns The normalized sync relative path for the key suffix.\n */\nexport function b2KeyToRelativePathUnderPrefix(prefix: string, fileName: string): string {\n  const rawPrefix = asRawB2KeyPrefix(prefix)\n  const suffix = rawPrefix === '' ? fileName : fileName.slice(rawPrefix.length)\n  return normalizeB2RelativePath(suffix, {\n    stripLeadingSlashes: rawPrefix !== '' && !rawPrefix.endsWith('/'),\n  })\n}\n\n/**\n * Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.\n * B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.\n *\n * @param relativePath - Folder-relative sync path.\n *\n * @returns True when any segment is Windows-dangerous or ambiguous.\n */\nexport function localFilesystemSyncPathIsUnsafe(relativePath: string): boolean {\n  const segments = relativePath.split('/')\n  return (\n    isDownloadStagingDirectorySegment(segments[0]) ||\n    segments.some((segment) => segmentIsLocalFilesystemUnsafe(segment))\n  )\n}\n\n/**\n * Produces an approximate Windows/macOS-style canonical key for local collision detection.\n *\n * @param relativePath - Folder-relative sync path.\n *\n * @returns A canonicalized path key for detecting case/Unicode collisions before local writes.\n */\nexport function localFilesystemCanonicalSyncPath(relativePath: string): string {\n  return relativePath\n    .split('/')\n    .map((segment) => segment.normalize('NFC').toLocaleLowerCase('en-US'))\n    .join('/')\n}\n\nfunction segmentIsUnsafe(segment: string): boolean {\n  return segment === '' || segment === '.' || segment === '..' || containsControlCharacter(segment)\n}\n\nfunction segmentIsLocalFilesystemUnsafe(segment: string): boolean {\n  if (segment.includes(':') || segment.endsWith('.') || segment.endsWith(' ')) return true\n  const basename = segment.split('.')[0]?.toUpperCase()\n  return (\n    basename !== undefined &&\n    /^(CON|PRN|AUX|NUL|CONIN\\$|CONOUT\\$|COM[0-9¹²³]|LPT[0-9¹²³])$/u.test(basename)\n  )\n}\n\nfunction containsControlCharacter(segment: string): boolean {\n  for (let index = 0; index < segment.length; index++) {\n    const code = segment.charCodeAt(index)\n    if (code >= 0 && code <= 31) return true\n  }\n  return false\n}\n\nfunction stripSingleLeadingSlash(path: string): string {\n  return path.startsWith('/') ? path.slice(1) : path\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,iBAAiB,QAAwB;CACvD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,wBACd,MACA,UAAsD,CAAC,GAC/C;CACR,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,GAAG;CAC3C,MAAM,eACJ,QAAQ,wBAAwB,OAAO,wBAAwB,SAAS,IAAI;CAC9E,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,IAAI,aAAa,KAAK,YAAY,KAAK,SAAS,MAAM,YAAY,gBAAgB,OAAO,CAAC,GACxF,MAAM,IAAI,MAAM,4DAA4D;CAE9E,OAAO;AACT;;;;;;;;;AAUA,SAAgB,+BAA+B,QAAgB,UAA0B;CACvF,MAAM,YAAY,iBAAiB,MAAM;CAEzC,OAAO,wBADQ,cAAc,KAAK,WAAW,SAAS,MAAM,UAAU,MAAM,GACrC,EACrC,qBAAqB,cAAc,MAAM,CAAC,UAAU,SAAS,GAAG,EAClE,CAAC;AACH;;;;;;;;;AAUA,SAAgB,gCAAgC,cAA+B;CAC7E,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,OACE,kCAAkC,SAAS,EAAE,KAC7C,SAAS,MAAM,YAAY,+BAA+B,OAAO,CAAC;AAEtE;;;;;;;;AASA,SAAgB,iCAAiC,cAA8B;CAC7E,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,KAAK,YAAY,QAAQ,UAAU,KAAK,CAAC,CAAC,kBAAkB,OAAO,CAAC,CAAC,CACrE,KAAK,GAAG;AACb;AAEA,SAAS,gBAAgB,SAA0B;CACjD,OAAO,YAAY,MAAM,YAAY,OAAO,YAAY,QAAQ,yBAAyB,OAAO;AAClG;AAEA,SAAS,+BAA+B,SAA0B;CAChE,IAAI,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,GAAG,GAAG,OAAO;CACpF,MAAM,WAAW,QAAQ,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,YAAY;CACpD,OACE,aAAa,KAAA,KACb,gEAAgE,KAAK,QAAQ;AAEjF;AAEA,SAAS,yBAAyB,SAA0B;CAC1D,KAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS;EACnD,MAAM,OAAO,QAAQ,WAAW,KAAK;EACrC,IAAI,QAAQ,KAAK,QAAQ,IAAI,OAAO;CACtC;CACA,OAAO;AACT;AAEA,SAAS,wBAAwB,MAAsB;CACrD,OAAO,KAAK,WAAW,GAAG,IAAI,KAAK,MAAM,CAAC,IAAI;AAChD"}

package/dist/sync/regexp-safety.cjs

@@ -0,0 +1,192 @@
+//#region src/sync/regexp-safety.ts
+var MAX_REGEXP_SOURCE_LENGTH = 512;
+var MAX_REGEXP_INPUT_LENGTH = 1024;
+var MAX_REGEXP_UNBOUNDED_QUANTIFIERS = 1;
+var MAX_REGEXP_BOUNDED_QUANTIFIER = 200;
+var MAX_REGEXP_BOUNDED_QUANTIFIERS = 16;
+var MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT = 1e4;
+var safeRegExpCache = /* @__PURE__ */ new WeakMap();
+var validatedFilterCache = /* @__PURE__ */ new WeakSet();
+/**
+* Validates every RegExp filter in an include/exclude filter set.
+*
+* @param filters - Optional include and exclude filters to validate.
+*
+* @throws When a RegExp filter is too large or structurally unsafe.
+*/
+function validateSyncFilters(filters) {
+	if (filters === void 0) return;
+	if (validatedFilterCache.has(filters)) return;
+	validateSyncFilterList("include", filters.include);
+	validateSyncFilterList("exclude", filters.exclude);
+	validatedFilterCache.add(filters);
+}
+/**
+* Tests a path with a caller-provided RegExp without retaining `lastIndex` state.
+*
+* @param relativePath - Folder-relative path to test.
+* @param pattern - Caller-provided RegExp filter.
+*
+* @returns True when the RegExp matches the relative path.
+*
+* @throws When the RegExp filter is too large or structurally unsafe.
+*/
+function regexpMatchesSyncPath(relativePath, pattern) {
+	if (pathExceedsSafeRegExpInput(relativePath)) return false;
+	return regexpWithoutState(pattern).test(relativePath);
+}
+/**
+* Tests whether a relative path is too long to feed to caller-provided RegExp filters.
+*
+* @param relativePath - Folder-relative path to test.
+*
+* @returns True when RegExp filters should not be evaluated for the path.
+*/
+function pathExceedsSafeRegExpInput(relativePath) {
+	return relativePath.length > MAX_REGEXP_INPUT_LENGTH;
+}
+function validateSyncFilterList(kind, patterns) {
+	for (const pattern of patterns ?? []) if (typeof pattern !== "string") regexpWithoutState(pattern, kind);
+}
+function regexpWithoutState(pattern, kind = "pattern") {
+	const cached = safeRegExpCache.get(pattern);
+	if (cached !== void 0) return cached;
+	assertSafeRegExp(pattern, kind);
+	const compiled = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+	safeRegExpCache.set(pattern, compiled);
+	return compiled;
+}
+function assertSafeRegExp(pattern, kind) {
+	const source = pattern.source;
+	if (source.length > MAX_REGEXP_SOURCE_LENGTH) throw new Error(`Sync filter RegExp is too long (${kind}: /${source}/)`);
+	if (!regexpSourceLooksSafe(source)) throw new Error(`Sync filter RegExp is too complex (${kind}: /${source}/)`);
+}
+/**
+* Best-effort linear RegExp guard for filters matched synchronously on attacker-controlled paths.
+*
+* The accepted subset intentionally rejects constructs that are hard to bound in the JavaScript
+* RegExp engine: backreferences, unterminated escapes/classes/groups, repeated unbounded
+* quantifiers, bounded quantifiers above {@link MAX_REGEXP_BOUNDED_QUANTIFIER}, too many bounded
+* quantifiers or too large a bounded-quantifier product, and any quantified group whose subtree
+* already contains a quantifier or alternation. Group state is propagated upward so nested groups
+* cannot hide a quantified or alternated subtree before an outer bounded or unbounded quantifier.
+*
+* @param source - RegExp source text to inspect.
+*
+* @returns True when the source passes the SDK's structural safety heuristic.
+*/
+function regexpSourceLooksSafe(source) {
+	let escaped = false;
+	let inClass = false;
+	let unboundedQuantifiers = 0;
+	let boundedQuantifiers = 0;
+	let boundedQuantifierProduct = 1;
+	const groups = [];
+	let lastToken = null;
+	for (let i = 0; i < source.length; i++) {
+		const char = source[i] ?? "";
+		if (escaped) {
+			if (!inClass && char === "k" && source[i + 1] === "<") return false;
+			if (!inClass && /[1-9]/.test(char)) return false;
+			escaped = false;
+			lastToken = { type: "atom" };
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (inClass) {
+			if (char === "]") inClass = false;
+			continue;
+		}
+		if (char === "[") {
+			inClass = true;
+			lastToken = { type: "atom" };
+			continue;
+		}
+		if (char === "(") {
+			groups.push({
+				hasQuantifier: false,
+				hasAlternation: false
+			});
+			lastToken = null;
+			continue;
+		}
+		if (char === ")") {
+			const group = groups.pop();
+			if (!group) return false;
+			const parent = groups.at(-1);
+			if (parent) mergeGroupState(parent, group);
+			lastToken = {
+				type: "group",
+				...group
+			};
+			continue;
+		}
+		if (char === "|") {
+			const group = groups.at(-1);
+			if (group) group.hasAlternation = true;
+			lastToken = null;
+			continue;
+		}
+		const quantifier = lastToken !== null ? parseQuantifier(source, i) : null;
+		if (lastToken !== null && quantifier !== null) {
+			if (lastToken?.type === "group" && (lastToken.hasQuantifier || lastToken.hasAlternation)) return false;
+			if (quantifier.unbounded) {
+				unboundedQuantifiers++;
+				if (unboundedQuantifiers > MAX_REGEXP_UNBOUNDED_QUANTIFIERS) return false;
+			} else {
+				boundedQuantifiers++;
+				if (boundedQuantifiers > MAX_REGEXP_BOUNDED_QUANTIFIERS) return false;
+				if (quantifier.maxRepetitions > MAX_REGEXP_BOUNDED_QUANTIFIER) return false;
+				boundedQuantifierProduct *= Math.max(quantifier.maxRepetitions, 1);
+				if (boundedQuantifierProduct > MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT) return false;
+			}
+			const group = groups.at(-1);
+			if (group) group.hasQuantifier = true;
+			i = quantifier.endIndex;
+			lastToken = null;
+			continue;
+		}
+		lastToken = { type: "atom" };
+	}
+	return !escaped && !inClass && groups.length === 0;
+}
+function mergeGroupState(target, source) {
+	target.hasQuantifier = target.hasQuantifier || source.hasQuantifier;
+	target.hasAlternation = target.hasAlternation || source.hasAlternation;
+}
+function parseQuantifier(source, index) {
+	const char = source[index];
+	if (char === "*" || char === "+") return {
+		endIndex: index,
+		maxRepetitions: Number.POSITIVE_INFINITY,
+		unbounded: true
+	};
+	if (char === "?") return {
+		endIndex: index,
+		maxRepetitions: 1,
+		unbounded: false
+	};
+	if (char !== "{") return null;
+	const end = source.indexOf("}", index + 1);
+	if (end === -1) return null;
+	const body = source.slice(index + 1, end);
+	const match = /^(\d+)(?:,(\d*))?$/.exec(body);
+	if (!match) return null;
+	const min = Number(match[1]);
+	const maxText = match[2];
+	const unbounded = body.includes(",") && maxText === "";
+	return {
+		endIndex: end,
+		maxRepetitions: unbounded ? Number.POSITIVE_INFINITY : Number(maxText ?? min),
+		unbounded
+	};
+}
+//#endregion
+exports.pathExceedsSafeRegExpInput = pathExceedsSafeRegExpInput;
+exports.regexpMatchesSyncPath = regexpMatchesSyncPath;
+exports.validateSyncFilters = validateSyncFilters;
+
+//# sourceMappingURL=regexp-safety.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"regexp-safety.cjs","names":[],"sources":["../../src/sync/regexp-safety.ts"],"sourcesContent":["import type { SyncFilterOptions, SyncFilterPattern } from './types.ts'\n\nconst MAX_REGEXP_SOURCE_LENGTH = 512\nconst MAX_REGEXP_INPUT_LENGTH = 1024\nconst MAX_REGEXP_UNBOUNDED_QUANTIFIERS = 1\nconst MAX_REGEXP_BOUNDED_QUANTIFIER = 200\nconst MAX_REGEXP_BOUNDED_QUANTIFIERS = 16\nconst MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT = 10_000\nconst safeRegExpCache = new WeakMap<RegExp, RegExp>()\n// Validation is memoized by object identity. Treat filter objects and their\n// include/exclude arrays as immutable after first use, otherwise new patterns\n// added later would not be revalidated through this cache.\nconst validatedFilterCache = new WeakSet<SyncFilterOptions>()\n\ninterface RegExpGroupState {\n  hasQuantifier: boolean\n  hasAlternation: boolean\n}\n\ntype RegExpTokenState = { type: 'atom' } | ({ type: 'group' } & RegExpGroupState)\n\ninterface RegExpQuantifier {\n  endIndex: number\n  maxRepetitions: number\n  unbounded: boolean\n}\n\n/**\n * Validates every RegExp filter in an include/exclude filter set.\n *\n * @param filters - Optional include and exclude filters to validate.\n *\n * @throws When a RegExp filter is too large or structurally unsafe.\n */\nexport function validateSyncFilters(filters: SyncFilterOptions | undefined): void {\n  if (filters === undefined) return\n  if (validatedFilterCache.has(filters)) return\n\n  validateSyncFilterList('include', filters.include)\n  validateSyncFilterList('exclude', filters.exclude)\n  validatedFilterCache.add(filters)\n}\n\n/**\n * Tests a path with a caller-provided RegExp without retaining `lastIndex` state.\n *\n * @param relativePath - Folder-relative path to test.\n * @param pattern - Caller-provided RegExp filter.\n *\n * @returns True when the RegExp matches the relative path.\n *\n * @throws When the RegExp filter is too large or structurally unsafe.\n */\nexport function regexpMatchesSyncPath(relativePath: string, pattern: RegExp): boolean {\n  if (pathExceedsSafeRegExpInput(relativePath)) return false\n  return regexpWithoutState(pattern).test(relativePath)\n}\n\n/**\n * Tests whether a relative path is too long to feed to caller-provided RegExp filters.\n *\n * @param relativePath - Folder-relative path to test.\n *\n * @returns True when RegExp filters should not be evaluated for the path.\n */\nexport function pathExceedsSafeRegExpInput(relativePath: string): boolean {\n  return relativePath.length > MAX_REGEXP_INPUT_LENGTH\n}\n\nfunction validateSyncFilterList(\n  kind: 'include' | 'exclude',\n  patterns: readonly SyncFilterPattern[] | undefined,\n): void {\n  for (const pattern of patterns ?? []) {\n    if (typeof pattern !== 'string') {\n      regexpWithoutState(pattern, kind)\n    }\n  }\n}\n\nfunction regexpWithoutState(pattern: RegExp, kind = 'pattern'): RegExp {\n  const cached = safeRegExpCache.get(pattern)\n  if (cached !== undefined) return cached\n\n  assertSafeRegExp(pattern, kind)\n  const compiled = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''))\n  safeRegExpCache.set(pattern, compiled)\n  return compiled\n}\n\nfunction assertSafeRegExp(pattern: RegExp, kind: string): void {\n  const source = pattern.source\n  if (source.length > MAX_REGEXP_SOURCE_LENGTH) {\n    throw new Error(`Sync filter RegExp is too long (${kind}: /${source}/)`)\n  }\n\n  if (!regexpSourceLooksSafe(source)) {\n    throw new Error(`Sync filter RegExp is too complex (${kind}: /${source}/)`)\n  }\n}\n\n/**\n * Best-effort linear RegExp guard for filters matched synchronously on attacker-controlled paths.\n *\n * The accepted subset intentionally rejects constructs that are hard to bound in the JavaScript\n * RegExp engine: backreferences, unterminated escapes/classes/groups, repeated unbounded\n * quantifiers, bounded quantifiers above {@link MAX_REGEXP_BOUNDED_QUANTIFIER}, too many bounded\n * quantifiers or too large a bounded-quantifier product, and any quantified group whose subtree\n * already contains a quantifier or alternation. Group state is propagated upward so nested groups\n * cannot hide a quantified or alternated subtree before an outer bounded or unbounded quantifier.\n *\n * @param source - RegExp source text to inspect.\n *\n * @returns True when the source passes the SDK's structural safety heuristic.\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: keep the regex safety scan linear.\nfunction regexpSourceLooksSafe(source: string): boolean {\n  let escaped = false\n  let inClass = false\n  let unboundedQuantifiers = 0\n  let boundedQuantifiers = 0\n  let boundedQuantifierProduct = 1\n  const groups: RegExpGroupState[] = []\n  let lastToken: RegExpTokenState | null = null\n\n  for (let i = 0; i < source.length; i++) {\n    const char = source[i] ?? ''\n\n    if (escaped) {\n      if (!inClass && char === 'k' && source[i + 1] === '<') return false\n      if (!inClass && /[1-9]/.test(char)) return false\n      escaped = false\n      lastToken = { type: 'atom' }\n      continue\n    }\n\n    if (char === '\\\\') {\n      escaped = true\n      continue\n    }\n\n    if (inClass) {\n      if (char === ']') inClass = false\n      continue\n    }\n\n    if (char === '[') {\n      inClass = true\n      lastToken = { type: 'atom' }\n      continue\n    }\n\n    if (char === '(') {\n      groups.push({ hasQuantifier: false, hasAlternation: false })\n      lastToken = null\n      continue\n    }\n\n    if (char === ')') {\n      const group = groups.pop()\n      if (!group) return false\n      const parent = groups.at(-1)\n      if (parent) mergeGroupState(parent, group)\n      lastToken = { type: 'group', ...group }\n      continue\n    }\n\n    if (char === '|') {\n      const group = groups.at(-1)\n      if (group) group.hasAlternation = true\n      lastToken = null\n      continue\n    }\n\n    const quantifier = lastToken !== null ? parseQuantifier(source, i) : null\n    if (lastToken !== null && quantifier !== null) {\n      if (lastToken?.type === 'group' && (lastToken.hasQuantifier || lastToken.hasAlternation)) {\n        return false\n      }\n\n      if (quantifier.unbounded) {\n        unboundedQuantifiers++\n        if (unboundedQuantifiers > MAX_REGEXP_UNBOUNDED_QUANTIFIERS) return false\n      } else {\n        boundedQuantifiers++\n        if (boundedQuantifiers > MAX_REGEXP_BOUNDED_QUANTIFIERS) return false\n        if (quantifier.maxRepetitions > MAX_REGEXP_BOUNDED_QUANTIFIER) return false\n        boundedQuantifierProduct *= Math.max(quantifier.maxRepetitions, 1)\n        if (boundedQuantifierProduct > MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT) return false\n      }\n\n      const group = groups.at(-1)\n      if (group) group.hasQuantifier = true\n\n      i = quantifier.endIndex\n      lastToken = null\n      continue\n    }\n\n    lastToken = { type: 'atom' }\n  }\n\n  return !escaped && !inClass && groups.length === 0\n}\n\nfunction mergeGroupState(target: RegExpGroupState, source: RegExpGroupState): void {\n  target.hasQuantifier = target.hasQuantifier || source.hasQuantifier\n  target.hasAlternation = target.hasAlternation || source.hasAlternation\n}\n\nfunction parseQuantifier(source: string, index: number): RegExpQuantifier | null {\n  const char = source[index]\n  if (char === '*' || char === '+') {\n    return { endIndex: index, maxRepetitions: Number.POSITIVE_INFINITY, unbounded: true }\n  }\n  if (char === '?') {\n    return { endIndex: index, maxRepetitions: 1, unbounded: false }\n  }\n  if (char !== '{') return null\n\n  const end = source.indexOf('}', index + 1)\n  if (end === -1) return null\n\n  const body = source.slice(index + 1, end)\n  const match = /^(\\d+)(?:,(\\d*))?$/.exec(body)\n  if (!match) return null\n\n  const min = Number(match[1])\n  const maxText = match[2]\n  const unbounded = body.includes(',') && maxText === ''\n  return {\n    endIndex: end,\n    maxRepetitions: unbounded ? Number.POSITIVE_INFINITY : Number(maxText ?? min),\n    unbounded,\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,29 @@
+import { SyncFilterOptions } from './types.js';
+/**
+ * Validates every RegExp filter in an include/exclude filter set.
+ *
+ * @param filters - Optional include and exclude filters to validate.
+ *
+ * @throws When a RegExp filter is too large or structurally unsafe.
+ */
+export declare function validateSyncFilters(filters: SyncFilterOptions | undefined): void;
+/**
+ * Tests a path with a caller-provided RegExp without retaining `lastIndex` state.
+ *
+ * @param relativePath - Folder-relative path to test.
+ * @param pattern - Caller-provided RegExp filter.
+ *
+ * @returns True when the RegExp matches the relative path.
+ *
+ * @throws When the RegExp filter is too large or structurally unsafe.
+ */
+export declare function regexpMatchesSyncPath(relativePath: string, pattern: RegExp): boolean;
+/**
+ * Tests whether a relative path is too long to feed to caller-provided RegExp filters.
+ *
+ * @param relativePath - Folder-relative path to test.
+ *
+ * @returns True when RegExp filters should not be evaluated for the path.
+ */
+export declare function pathExceedsSafeRegExpInput(relativePath: string): boolean;
+//# sourceMappingURL=regexp-safety.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"regexp-safety.d.ts","sourceRoot":"","sources":["../../src/sync/regexp-safety.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,YAAY,CAAA;AA2BtE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAOhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAExE"}

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

@@ -0,0 +1,29 @@
+import { SyncFilterOptions } from './types.js';
+/**
+ * Validates every RegExp filter in an include/exclude filter set.
+ *
+ * @param filters - Optional include and exclude filters to validate.
+ *
+ * @throws When a RegExp filter is too large or structurally unsafe.
+ */
+export declare function validateSyncFilters(filters: SyncFilterOptions | undefined): void;
+/**
+ * Tests a path with a caller-provided RegExp without retaining `lastIndex` state.
+ *
+ * @param relativePath - Folder-relative path to test.
+ * @param pattern - Caller-provided RegExp filter.
+ *
+ * @returns True when the RegExp matches the relative path.
+ *
+ * @throws When the RegExp filter is too large or structurally unsafe.
+ */
+export declare function regexpMatchesSyncPath(relativePath: string, pattern: RegExp): boolean;
+/**
+ * Tests whether a relative path is too long to feed to caller-provided RegExp filters.
+ *
+ * @param relativePath - Folder-relative path to test.
+ *
+ * @returns True when RegExp filters should not be evaluated for the path.
+ */
+export declare function pathExceedsSafeRegExpInput(relativePath: string): boolean;
+//# sourceMappingURL=regexp-safety.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"regexp-safety.d.ts","sourceRoot":"","sources":["../../src/sync/regexp-safety.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,YAAY,CAAA;AA2BtE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAOhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAExE"}