@devries-cameron20 / composio Mirror · read-only / commits / 587a1c350
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 11:00 UTC

fix(sdk): keep file names that normalize alike from overwriting each other

Making a server-provided name portable maps distinct names to one file: `report?.png`, `report*.png` and `report_.png` all became `report_.png`, and long names that differ only past the truncation point shared a prefix, so one download silently replaced another in a shared directory. Tag a name that any portability rule changed with a 64-bit FNV-1a digest of the original, before its extension (`report_-05fcb95aa5b918e9.png`), within the 128-byte bound. Names that were already portable stay unchanged, and a tagged name is itself portable, so saving is idempotent. The digest is pure and synchronous in both SDKs, so edge builds keep working and TypeScript and Python write a given name to the same file. Also re-review the path-join guardrail entry for `safe_basename`, whose validators moved into helpers.

jkomyno committed Sep 29, 2026 at 15:36 UTC 587a1c3501dc0d0edfa6c1794ab96ba3e8320520
9 files changed +352 -128
.changeset/remote-file-portable-names.md
+1 -1
@@ -2,4 +2,4 @@
2 '@composio/core': patch
3 ---
4
5 -`RemoteFile.save()` without a path no longer rejects ordinary file names. Names with characters Windows reserves, such as `report_2026-09-29T10:30:00.csv` or `What is this?.png`, are saved with those characters replaced by `_`. Names longer than 128 bytes are truncated with their extension kept, and reserved device names such as `NUL` get a `_` prefix. Names with a NUL byte or no usable basename are still refused.
5 +`RemoteFile.save()` without a path no longer rejects ordinary file names. Names with characters Windows reserves, such as `report_2026-09-29T10:30:00.csv` or `What is this?.png`, are saved with those characters replaced by `_`. Names longer than 128 bytes are truncated with their extension kept, and reserved device names such as `NUL` get a `_` prefix. A name changed this way also gets a short digest of the original before its extension (`What is this_-9c68adf2da8b6e8d.png`), so two files whose names differ only in those characters never overwrite each other. Names with a NUL byte or no usable basename are still refused.
python/composio/utils/safe_path.py
+49 -13
@@ -166,18 +166,50 @@ def _truncate_to_bytes(value: str, max_bytes: int) -> str:
166 return "".join(truncated)
167
168
169 -def _fit_filename_bytes(name: str) -> str:
170 - """Truncate ``name`` to :data:`MAX_COMPONENT_LENGTH` bytes, keeping a short
171 - extension so the file still opens with the right application."""
172 - if _encoded_length(name) <= MAX_COMPONENT_LENGTH:
173 - return name
169 +def _split_extension(name: str) -> t.Tuple[str, str]:
170 + """Split off a short trailing extension (with its dot); a leading dot is
171 + not one."""
172 dot = name.rfind(".")
173 extension = name[dot:] if dot > 0 else ""
176 - extension_length = _encoded_length(extension)
177 - if extension and extension_length <= MAX_PRESERVED_EXTENSION_BYTES:
178 - stem = _truncate_to_bytes(name[:dot], MAX_COMPONENT_LENGTH - extension_length)
179 - return stem + extension
180 - return _truncate_to_bytes(name, MAX_COMPONENT_LENGTH)
174 + if extension and _encoded_length(extension) <= MAX_PRESERVED_EXTENSION_BYTES:
175 + return name[:dot], extension
176 + return name, ""
177 +
178 +
179 +def _fit_filename_bytes(name: str, max_bytes: int = MAX_COMPONENT_LENGTH) -> str:
180 + """Truncate ``name`` to ``max_bytes``, keeping a short extension so the file
181 + still opens with the right application."""
182 + if _encoded_length(name) <= max_bytes:
183 + return name
184 + stem, extension = _split_extension(name)
185 + return _truncate_to_bytes(stem, max_bytes - _encoded_length(extension)) + extension
186 +
187 +
188 +_FNV_OFFSET_BASIS_64 = 0xCBF29CE484222325
189 +_FNV_PRIME_64 = 0x100000001B3
190 +_UINT64_MASK = 0xFFFFFFFFFFFFFFFF
191 +
192 +
193 +def _fnv1a64_hex(value: str) -> str:
194 + """64-bit FNV-1a of the UTF-8 bytes, as 16 hex digits. ``fnv1a64Hex`` in
195 + the TypeScript SDK matches it."""
196 + digest = _FNV_OFFSET_BASIS_64
197 + for byte in value.encode("utf-8", "surrogatepass"):
198 + digest = ((digest ^ byte) * _FNV_PRIME_64) & _UINT64_MASK
199 + return f"{digest:016x}"
200 +
201 +
202 +def _tag_with_original(portable: str, original: str) -> str:
203 + """Tag a name that portability changed with a digest of the name it came
204 + from, before the extension: ``report?.png`` and ``report*.png`` both become
205 + ``report_.png``, and two long names can share a truncated prefix, so
206 + without the tag one download would overwrite the other in a shared
207 + directory."""
208 + tag = f"-{_fnv1a64_hex(original)}"
209 + stem, extension = _split_extension(
210 + _fit_filename_bytes(portable, MAX_COMPONENT_LENGTH - len(tag))
211 + )
212 + return stem + tag + extension
213
214
215 def safe_basename(name: str, *, label: str = "filename") -> str:
@@ -204,8 +236,12 @@ def safe_basename(name: str, *, label: str = "filename") -> str:
236 where the SDK runs: control and Windows-reserved characters become ``_``,
237 names over :data:`MAX_COMPONENT_LENGTH` bytes are truncated with their
238 extension kept, trailing spaces and dots are dropped as Windows would, and
207 - a resulting reserved device name gets a ``_`` prefix. ``safeBasename`` in
208 - the TypeScript SDK applies the same rules in the same order.
239 + a resulting reserved device name gets a ``_`` prefix. A name any of these
240 + rules changed is then tagged with a digest of the original before its
241 + extension (``report_-<16 hex>.png``), so distinct names never land on the
242 + same file; a name that was already portable is returned unchanged.
243 + ``safeBasename`` in the TypeScript SDK applies the same rules in the same
244 + order.
245
246 ``str.strip`` removes surrounding whitespace first, and the usability check
247 runs last, on the value that gets written, so neither ``"\\u00a0.\\u00a0"``
@@ -249,7 +285,7 @@ def safe_basename(name: str, *, label: str = "filename") -> str:
285 f"Path traversal detected: {label} {name!r} leaves no usable "
286 "basename to write to."
287 )
252 - return portable
288 + return portable if portable == basename else _tag_with_original(portable, basename)
289
290
291 def resolve_root(root: t.Union[str, Path]) -> Path:
python/tests/test_files.py
+35 -8
@@ -3161,19 +3161,23 @@ class TestFileDownloadablePathTraversal:
3161 @pytest.mark.parametrize(
3162 "name,expected",
3163 [
3164 - ("report_2026-09-29T10:30:00.csv", "report_2026-09-29T10_30_00.csv"),
3165 - ("What is this?.png", "What is this_.png"),
3166 - ('invoice "final".pdf', "invoice _final_.pdf"),
3167 - ("NUL", "_NUL"),
3168 - ("NUL.tar.gz", "_NUL.tar.gz"),
3169 - ("x" * 300 + ".pdf", "x" * 124 + ".pdf"),
3170 - ("請" * 70 + ".pdf", "請" * 41 + ".pdf"),
3164 + (
3165 + "report_2026-09-29T10:30:00.csv",
3166 + "report_2026-09-29T10_30_00-d7211bb25cb815fe.csv",
3167 + ),
3168 + ("What is this?.png", "What is this_-9c68adf2da8b6e8d.png"),
3169 + ('invoice "final".pdf', "invoice _final_-ec493385353bf798.pdf"),
3170 + ("NUL", "_NUL-369eba19c29ffe00"),
3171 + ("NUL.tar.gz", "_NUL.tar-c5d0283bb0ecb474.gz"),
3172 + ("x" * 300 + ".pdf", "x" * 107 + "-b8191dd974368539.pdf"),
3173 + ("請" * 70 + ".pdf", "請" * 35 + "-a7cbc40614b84819.pdf"),
3174 ],
3175 )
3176 def test_unportable_filenames_are_made_portable(self, name, expected, tmp_path):
3177 """Ordinary names with a `:` or `?`, reserved device names, and names over
3178 the byte limit are written under a portable name rather than failing
3176 - the download after the tool has already run."""
3179 + the download after the tool has already run. The name is tagged with a
3180 + digest of the original, so names that normalize alike stay apart."""
3181 outdir = tmp_path / "safe"
3182 f = FileDownloadable(
3183 name=name,
@@ -3188,6 +3192,29 @@ class TestFileDownloadablePathTraversal:
3192 assert outfile == (outdir / expected).resolve()
3193 assert outfile.read_bytes() == b"x"
3194
3195 + def test_names_that_normalize_alike_do_not_overwrite_each_other(self, tmp_path):
3196 + outdir = tmp_path / "safe"
3197 + names = ["report?.png", "report*.png", "report_.png"]
3198 + outfiles = []
3199 + for index, name in enumerate(names):
3200 + f = FileDownloadable(
3201 + name=name,
3202 + mimetype="image/png",
3203 + s3url="https://example.com/file",
3204 + )
3205 + with patch(
3206 + "composio.core.models._files.safe_request",
3207 + return_value=self._mock_response(bytes([index])),
3208 + ):
3209 + outfiles.append(f.download(outdir, root=outdir))
3210 +
3211 + assert len(set(outfiles)) == len(names)
3212 + assert [outfile.read_bytes() for outfile in outfiles] == [
3213 + b"\x00",
3214 + b"\x01",
3215 + b"\x02",
3216 + ]
3217 +
3218
3219 class TestDownloadDirSlugTraversal:
3220 """Server-controlled tool/toolkit slugs must not relocate the download
python/tests/test_path_join_guardrail.py
+7 -3
@@ -125,9 +125,13 @@ REVIEWED_JOINS: t.Dict[t.Tuple[str, str], t.Dict[str, t.Any]] = {
125 "composio/utils/safe_path.py",
126 "PureWindowsPath(name)",
127 ): _reviewed_path(
128 - "`safe_basename` collapses the value, rejects Windows-invalid forms, checks "
129 - "its encoded length, and rejects reserved device names.",
130 - "fsencode",
128 + "`safe_basename` collapses the value, rejects NUL bytes and invalid "
129 + "Unicode, rewrites Windows-invalid forms and reserved device names, fits "
130 + "the encoded length, and tags a rewritten name with a digest of the "
131 + "original so distinct names never share a file.",
132 + "_encoded_length",
133 + "_fit_filename_bytes",
134 + "_tag_with_original",
135 ),
136 (
137 "composio/utils/safe_path.py",
python/tests/test_safe_path.py
+94 -44
@@ -4,6 +4,7 @@ See that module's docstring for why containment must be anchored on a constant
4 root rather than on a directory the input helped build.
5 """
6
7 +import re
8 import sys
9 from pathlib import Path
10
@@ -139,6 +140,16 @@ class TestIsInsideDir:
140 assert is_inside_dir(Path("C:\\Foo\\Bar"), Path("c:\\foo"))
141
142
143 +TAG_BYTES = 17
144 +"""Bytes a changed name gains: ``-`` and 16 hex digits of the original's
145 +digest."""
146 +
147 +
148 +def tagged(stem: str, extension: str = "") -> "re.Pattern[str]":
149 + """Match ``stem``, the digest tag of a changed name, then ``extension``."""
150 + return re.compile(re.escape(stem) + "-[0-9a-f]{16}" + re.escape(extension))
151 +
152 +
153 class TestSafeBasename:
154 @pytest.mark.parametrize(
155 ("value", "expected"),
@@ -149,6 +160,8 @@ class TestSafeBasename:
160 (".gitignore", ".gitignore"),
161 ("..\\..\\evil", "evil"),
162 (" report.pdf", "report.pdf"),
163 + ("report.pdf ", "report.pdf"),
164 + ("\x1creport.txt\x1f", "report.txt"),
165 ("café.txt", "café.txt"),
166 ("C:report.txt", "report.txt"),
167 ("\ufeffreport.txt", "\ufeffreport.txt"),
@@ -183,83 +196,120 @@ class TestSafeBasename:
196 safe_basename("report\x00.pdf")
197
198 @pytest.mark.parametrize(
186 - ("value", "expected"),
199 + ("value", "stem", "extension"),
200 [
188 - ("report_2026-09-29T10:30:00.csv", "report_2026-09-29T10_30_00.csv"),
189 - ("What is this?.png", "What is this_.png"),
190 - ('invoice "final".pdf', "invoice _final_.pdf"),
191 - ("report.txt:payload", "report.txt_payload"),
192 - ("report<1>.txt", "report_1_.txt"),
193 - ("a|b*.txt", "a_b_.txt"),
194 - ("tab\there.txt", "tab_here.txt"),
195 - ("\x1creport.txt\x1f", "report.txt"),
196 - ("output/C:report.txt", "C_report.txt"),
201 + ("report_2026-09-29T10:30:00.csv", "report_2026-09-29T10_30_00", ".csv"),
202 + ("What is this?.png", "What is this_", ".png"),
203 + ('invoice "final".pdf', "invoice _final_", ".pdf"),
204 + ("report.txt:payload", "report", ".txt_payload"),
205 + ("report<1>.txt", "report_1_", ".txt"),
206 + ("a|b*.txt", "a_b_", ".txt"),
207 + ("tab\there.txt", "tab_here", ".txt"),
208 + ("output/C:report.txt", "C_report", ".txt"),
209 ],
210 )
199 - def test_replaces_windows_reserved_characters(self, value, expected):
200 - assert safe_basename(value) == expected
211 + def test_replaces_windows_reserved_characters(self, value, stem, extension):
212 + assert tagged(stem, extension).fullmatch(safe_basename(value))
213
214 @pytest.mark.parametrize(
203 - ("value", "expected"),
215 + ("value", "stem", "extension"),
216 [
205 - ("report.txt.", "report.txt"),
206 - ("report.txt ", "report.txt"),
207 - ("report. .", "report"),
208 - ("report.\u00a0", "report"),
209 - ("report.\u0085", "report"),
210 - ("\ufeff..", "\ufeff"),
217 + ("report.txt.", "report", ".txt"),
218 + ("report. .", "report", ""),
219 + ("report.\u00a0", "report", ""),
220 + ("report.\u0085", "report", ""),
221 + ("\ufeff..", "\ufeff", ""),
222 ],
223 )
213 - def test_drops_trailing_spaces_and_dots(self, value, expected):
214 - assert safe_basename(value) == expected
224 + def test_drops_trailing_spaces_and_dots(self, value, stem, extension):
225 + assert tagged(stem, extension).fullmatch(safe_basename(value))
226
227 @pytest.mark.parametrize(
217 - ("value", "expected"),
228 + ("value", "stem", "extension"),
229 [
219 - ("NUL", "_NUL"),
220 - ("nul", "_nul"),
221 - ("NUL.tar.gz", "_NUL.tar.gz"),
222 - ("COM1.log.bak", "_COM1.log.bak"),
223 - ("COM¹.txt", "_COM¹.txt"),
224 - ("LPT³.data", "_LPT³.data"),
225 - ("aux.txt", "_aux.txt"),
226 - ("CON .txt", "_CON .txt"),
227 - ("COM1:.txt", "COM1_.txt"),
230 + ("NUL", "_NUL", ""),
231 + ("nul", "_nul", ""),
232 + ("NUL.tar.gz", "_NUL.tar", ".gz"),
233 + ("COM1.log.bak", "_COM1.log", ".bak"),
234 + ("COM¹.txt", "_COM¹", ".txt"),
235 + ("LPT³.data", "_LPT³", ".data"),
236 + ("aux.txt", "_aux", ".txt"),
237 + ("CON .txt", "_CON ", ".txt"),
238 + ("COM1:.txt", "COM1_", ".txt"),
239 ],
240 )
230 - def test_prefixes_windows_device_names_with_any_extension(self, value, expected):
231 - assert safe_basename(value) == expected
241 + def test_prefixes_windows_device_names_with_any_extension(
242 + self, value, stem, extension
243 + ):
244 + assert tagged(stem, extension).fullmatch(safe_basename(value))
245
246 def test_prefixes_a_device_name_exposed_by_truncation(self):
247 # Truncation keeps `NUL` plus spaces before `.txt`, and Windows ignores
248 # the spaces, so the checked name must be the fitted one.
236 - assert safe_basename("NUL" + " " * 200 + "x.txt") == "_NUL" + " " * 120 + ".txt"
237 - assert safe_basename("CON" + " " * 200 + "x") == "_CON"
249 + spaces = " " * (MAX_COMPONENT_LENGTH - TAG_BYTES - 8)
250 + assert tagged("_NUL" + spaces, ".txt").fullmatch(
251 + safe_basename("NUL" + " " * 200 + "x.txt")
252 + )
253 + assert tagged("_CON").fullmatch(safe_basename("CON" + " " * 200 + "x"))
254
255 def test_keeps_a_filename_at_the_byte_limit(self):
256 name = "x" * MAX_COMPONENT_LENGTH
257 assert safe_basename(name) == name
258
259 def test_truncates_to_the_byte_limit_and_keeps_the_extension(self):
244 - assert (
245 - safe_basename("x" * 200 + ".pdf")
246 - == "x" * (MAX_COMPONENT_LENGTH - 4) + ".pdf"
260 + result = safe_basename("x" * 200 + ".pdf")
261 + assert tagged("x" * (MAX_COMPONENT_LENGTH - TAG_BYTES - 4), ".pdf").fullmatch(
262 + result
263 )
264 + assert len(result) == MAX_COMPONENT_LENGTH
265
266 def test_truncates_by_whole_code_points_measured_in_bytes(self):
267 cjk = safe_basename("請" * 70 + ".pdf")
251 - assert cjk == "請" * 41 + ".pdf"
268 + assert tagged("請" * 35, ".pdf").fullmatch(cjk)
269 assert len(cjk.encode()) <= MAX_COMPONENT_LENGTH
253 - assert safe_basename("😀" * 33) == "😀" * 32
270 + assert tagged("😀" * 27).fullmatch(safe_basename("😀" * 33))
271
272 def test_truncates_an_over_long_extension_with_the_rest(self):
256 - assert safe_basename("report." + "x" * 200) == "report." + "x" * (
257 - MAX_COMPONENT_LENGTH - 7
258 - )
273 + stem = "report." + "x" * (MAX_COMPONENT_LENGTH - TAG_BYTES - 7)
274 + assert tagged(stem).fullmatch(safe_basename("report." + "x" * 200))
275
276 def test_drops_a_trailing_dot_exposed_by_truncation(self):
277 name = "x" * (MAX_COMPONENT_LENGTH - 1) + "." + "y" * 40
262 - assert safe_basename(name) == "x" * (MAX_COMPONENT_LENGTH - 1)
278 + assert tagged("x" * (MAX_COMPONENT_LENGTH - TAG_BYTES)).fullmatch(
279 + safe_basename(name)
280 + )
281 +
282 + @pytest.mark.parametrize(
283 + ("value", "expected"),
284 + [
285 + # safePath.test.ts asserts the same vectors, so both SDKs write a
286 + # given server name to the same file.
287 + ("report?.png", "report_-05fcb95aa5b918e9.png"),
288 + ("report*.png", "report_-aa921bdab2b33292.png"),
289 + (
290 + "report_2026-09-29T10:30:00.csv",
291 + "report_2026-09-29T10_30_00-d7211bb25cb815fe.csv",
292 + ),
293 + ("NUL.txt", "_NUL-d0848f78ce05ded6.txt"),
294 + ],
295 + )
296 + def test_tags_a_changed_name_with_a_digest_of_the_original(self, value, expected):
297 + assert safe_basename(value) == expected
298 +
299 + def test_distinct_names_that_normalize_alike_stay_distinct(self):
300 + names = ["report?.png", "report*.png", "report:.png", "report_.png"]
301 + assert len({safe_basename(name) for name in names}) == len(names)
302 +
303 + def test_distinct_long_names_sharing_a_truncated_prefix_stay_distinct(self):
304 + prefix = "a" * 200
305 + assert safe_basename(prefix + "-1.txt") != safe_basename(prefix + "-2.txt")
306 +
307 + def test_returns_an_already_portable_name_unchanged(self):
308 + assert safe_basename("report_.png") == "report_.png"
309 +
310 + def test_treats_a_tagged_name_as_already_portable(self):
311 + written = safe_basename("report?.png")
312 + assert safe_basename(written) == written
313
314 def test_rejects_unencodable_filename(self):
315 with pytest.raises(UnsafePathComponentError, match="invalid Unicode"):
python/tests/test_tool_router_session_files.py
+6 -3
@@ -355,9 +355,12 @@ class TestRemoteFile:
355 @pytest.mark.parametrize(
356 ("mount_relative_path", "expected"),
357 [
358 - ("report.\u00a0", "report"),
359 - ("out/report_2026-09-29T10:30:00.csv", "report_2026-09-29T10_30_00.csv"),
360 - ("What is this?.png", "What is this_.png"),
358 + ("report.\u00a0", "report-11aada8ba3168adf"),
359 + (
360 + "out/report_2026-09-29T10:30:00.csv",
361 + "report_2026-09-29T10_30_00-d7211bb25cb815fe.csv",
362 + ),
363 + ("What is this?.png", "What is this_-9c68adf2da8b6e8d.png"),
364 ],
365 )
366 def test_save_makes_unportable_names_portable(
ts/packages/core/src/utils/safePath.ts
+51 -14
@@ -52,6 +52,22 @@ const TRAILING_SPACES_AND_DOTS = /[. ]+$/;
52
53 const utf8Length = (value: string): number => new TextEncoder().encode(value).length;
54
55 +const FNV_OFFSET_BASIS_64 = 0xcbf29ce484222325n;
56 +const FNV_PRIME_64 = 0x100000001b3n;
57 +const UINT64_MASK = 0xffffffffffffffffn;
58 +
59 +/**
60 + * 64-bit FNV-1a of the UTF-8 bytes, as 16 hex digits. Pure and synchronous, so
61 + * it runs on every runtime; `_fnv1a64_hex` in the Python SDK matches it.
62 + */
63 +function fnv1a64Hex(value: string): string {
64 + let hash = FNV_OFFSET_BASIS_64;
65 + for (const byte of new TextEncoder().encode(value)) {
66 + hash = ((hash ^ BigInt(byte)) * FNV_PRIME_64) & UINT64_MASK;
67 + }
68 + return hash.toString(16).padStart(16, '0');
69 +}
70 +
71 /**
72 * Python str.strip() whitespace: Unicode White_Space plus U+001C–U+001F.
73 * Unlike JavaScript trim(), this includes U+0085 and preserves U+FEFF.
@@ -119,21 +135,39 @@ function truncateToBytes(value: string, maxBytes: number): string {
135 return truncated;
136 }
137
138 +/** Splits off a short trailing extension (with its dot); a leading dot is not one. */
139 +function splitExtension(name: string): [stem: string, extension: string] {
140 + const dot = name.lastIndexOf('.');
141 + const extension = dot > 0 ? name.slice(dot) : '';
142 + return extension && utf8Length(extension) <= MAX_PRESERVED_EXTENSION_BYTES
143 + ? [name.slice(0, dot), extension]
144 + : [name, ''];
145 +}
146 +
147 /**
123 - * Truncates `name` to {@link MAX_FILENAME_BYTES}, keeping a short extension so
124 - * the file still opens with the right application.
148 + * Truncates `name` to `maxBytes`, keeping a short extension so the file still
149 + * opens with the right application.
150 */
126 -function fitFilenameBytes(name: string): string {
127 - if (utf8Length(name) <= MAX_FILENAME_BYTES) {
151 +function fitFilenameBytes(name: string, maxBytes: number = MAX_FILENAME_BYTES): string {
152 + if (utf8Length(name) <= maxBytes) {
153 return name;
154 }
130 - const dot = name.lastIndexOf('.');
131 - const extension = dot > 0 ? name.slice(dot) : '';
132 - const extensionBytes = utf8Length(extension);
133 - if (extension && extensionBytes <= MAX_PRESERVED_EXTENSION_BYTES) {
134 - return truncateToBytes(name.slice(0, dot), MAX_FILENAME_BYTES - extensionBytes) + extension;
135 - }
136 - return truncateToBytes(name, MAX_FILENAME_BYTES);
155 + const [stem, extension] = splitExtension(name);
156 + return truncateToBytes(stem, maxBytes - utf8Length(extension)) + extension;
157 +}
158 +
159 +/**
160 + * Tags a name that portability changed with a digest of the name it came
161 + * from, before the extension: `report?.png` and `report*.png` both become
162 + * `report_.png`, and two long names can share a truncated prefix, so without
163 + * the tag one download would overwrite the other in a shared directory.
164 + */
165 +function tagWithOriginal(portable: string, original: string): string {
166 + const tag = `-${fnv1a64Hex(original)}`;
167 + const [stem, extension] = splitExtension(
168 + fitFilenameBytes(portable, MAX_FILENAME_BYTES - tag.length)
169 + );
170 + return stem + tag + extension;
171 }
172
173 /**
@@ -153,8 +187,11 @@ function fitFilenameBytes(name: string): string {
187 * control and Windows-reserved characters become `_`, names over
188 * {@link MAX_FILENAME_BYTES} are truncated with their extension kept, trailing
189 * spaces and dots are dropped as Windows would, and a resulting reserved
156 - * device name gets a `_` prefix. `safe_basename` in the Python SDK applies the
157 - * same rules in the same order.
190 + * device name gets a `_` prefix. A name any of these rules changed is then
191 + * tagged with a digest of the original before its extension
192 + * (`report_-<16 hex>.png`), so distinct names never land on the same file; a
193 + * name that was already portable is returned unchanged. `safe_basename` in
194 + * the Python SDK applies the same rules in the same order.
195 *
196 * Python-compatible stripping removes surrounding whitespace first, and the
197 * usability check runs last, on the value that gets written, so neither
@@ -199,5 +236,5 @@ export function safeBasename(name: string, label: string = 'filename'): string {
236 );
237 }
238
202 - return portable;
239 + return portable === basename ? portable : tagWithOriginal(portable, basename);
240 }
ts/packages/core/test/models/RemoteFile.test.ts
+28 -5
@@ -319,11 +319,11 @@ describe('RemoteFile', () => {
319 ['C:report.txt', 'report.txt'],
320 ['\ufeffreport.txt', '\ufeffreport.txt'],
321 ['\u0085report.txt\u0085', 'report.txt'],
322 - ['out/report_2026-09-29T10:30:00.csv', 'report_2026-09-29T10_30_00.csv'],
323 - ['What is this?.png', 'What is this_.png'],
324 - ['report.\u00a0', 'report'],
325 - ['NUL.txt', '_NUL.txt'],
326 - [`${'請'.repeat(70)}.pdf`, `${'請'.repeat(41)}.pdf`],
322 + ['out/report_2026-09-29T10:30:00.csv', 'report_2026-09-29T10_30_00-d7211bb25cb815fe.csv'],
323 + ['What is this?.png', 'What is this_-9c68adf2da8b6e8d.png'],
324 + ['report.\u00a0', 'report-11aada8ba3168adf'],
325 + ['NUL.txt', '_NUL-d0848f78ce05ded6.txt'],
326 + [`${'請'.repeat(70)}.pdf`, `${'請'.repeat(35)}-a7cbc40614b84819.pdf`],
327 ])(
328 'should save %j under the default directory as %j',
329 async (mountRelativePath, expectedName) => {
@@ -338,6 +338,29 @@ describe('RemoteFile', () => {
338 }
339 );
340
341 + it('should not let files whose names normalize alike overwrite each other', async () => {
342 + const { platform } = await import('../../src/platform/node');
343 + const bodies = [new Uint8Array([1]), new Uint8Array([2]), new Uint8Array([3])];
344 + globalThis.fetch = vi
345 + .fn()
346 + .mockResolvedValueOnce({ ok: true, arrayBuffer: () => Promise.resolve(bodies[0].buffer) })
347 + .mockResolvedValueOnce({ ok: true, arrayBuffer: () => Promise.resolve(bodies[1].buffer) })
348 + .mockResolvedValueOnce({
349 + ok: true,
350 + arrayBuffer: () => Promise.resolve(bodies[2].buffer),
351 + });
352 +
353 + const paths = [];
354 + for (const mountRelativePath of ['report?.png', 'report*.png', 'report_.png']) {
355 + paths.push(await new RemoteFile({ ...validCamelCaseData, mountRelativePath }).save());
356 + }
357 +
358 + expect(new Set(paths).size).toBe(3);
359 + expect(
360 + paths.map(path => new Uint8Array(platform.readFileSync(path) as Uint8Array))
361 + ).toEqual(bodies);
362 + });
363 +
364 // Each of these would make the save path equal its own directory (or the
365 // parent), which previously surfaced as an unhandled `EISDIR` from
366 // `writeFileSync` after the directory had already been created.
ts/packages/core/test/utils/safePath.test.ts
+81 -37
@@ -8,6 +8,15 @@ import { describe, it, expect } from 'vitest';
8 import { MAX_FILENAME_BYTES, safeBasename, untrustedBasename } from '../../src/utils/safePath';
9 import { ValidationError } from '../../src/errors';
10
11 +/** Bytes a changed name gains: `-` and 16 hex digits of the original's digest. */
12 +const TAG_BYTES = 17;
13 +
14 +const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
15 +
16 +/** Matches `stem`, the digest tag of a changed name, then `extension`. */
17 +const tagged = (stem: string, extension: string = ''): RegExp =>
18 + new RegExp(`^${escapeRegExp(stem)}-[0-9a-f]{16}${escapeRegExp(extension)}$`, 'u');
19 +
20 describe('untrustedBasename', () => {
21 it.each([
22 ['report.pdf', 'report.pdf'],
@@ -36,6 +45,7 @@ describe('safeBasename', () => {
45 ['\ufeffreport.txt', '\ufeffreport.txt'],
46 ['report.txt\ufeff', 'report.txt\ufeff'],
47 ['\u0085report.txt\u0085', 'report.txt'],
48 + ['\u001creport.txt\u001f', 'report.txt'],
49 ['output/report.pdf', 'report.pdf'],
50 ['output/subdir/data.json', 'data.json'],
51 ['/absolute/report.pdf', 'report.pdf'],
@@ -44,6 +54,7 @@ describe('safeBasename', () => {
54 ['archive.tar.gz', 'archive.tar.gz'],
55 ['.gitignore', '.gitignore'],
56 [' report.pdf', 'report.pdf'],
57 + ['report.pdf ', 'report.pdf'],
58 ['café.txt', 'café.txt'],
59 ['😀.png', '😀.png'],
60 ])('reduces %j to %j', (input, expected) => {
@@ -102,73 +113,106 @@ describe('safeBasename', () => {
113
114 describe('makes unportable names portable on every platform', () => {
115 it.each([
105 - ['report_2026-09-29T10:30:00.csv', 'report_2026-09-29T10_30_00.csv'],
106 - ['What is this?.png', 'What is this_.png'],
107 - ['invoice "final".pdf', 'invoice _final_.pdf'],
108 - ['report.txt:payload', 'report.txt_payload'],
109 - ['report<1>.txt', 'report_1_.txt'],
110 - ['a|b*.txt', 'a_b_.txt'],
111 - ['tab\there.txt', 'tab_here.txt'],
112 - ['\u001creport.txt\u001f', 'report.txt'],
113 - ['output/C:report.txt', 'C_report.txt'],
114 - ])('replaces reserved characters in %j', (input, expected) => {
115 - expect(safeBasename(input)).toBe(expected);
116 + ['report_2026-09-29T10:30:00.csv', 'report_2026-09-29T10_30_00', '.csv'],
117 + ['What is this?.png', 'What is this_', '.png'],
118 + ['invoice "final".pdf', 'invoice _final_', '.pdf'],
119 + ['report.txt:payload', 'report', '.txt_payload'],
120 + ['report<1>.txt', 'report_1_', '.txt'],
121 + ['a|b*.txt', 'a_b_', '.txt'],
122 + ['tab\there.txt', 'tab_here', '.txt'],
123 + ['output/C:report.txt', 'C_report', '.txt'],
124 + ])('replaces reserved characters in %j', (input, stem, extension) => {
125 + expect(safeBasename(input)).toMatch(tagged(stem, extension));
126 });
127
128 it.each([
119 - ['report.txt.', 'report.txt'],
120 - ['report.txt ', 'report.txt'],
121 - ['report. .', 'report'],
122 - ['report.\u00a0', 'report'],
123 - ['report.\u0085', 'report'],
124 - ['\ufeff..', '\ufeff'],
125 - ])('drops trailing spaces and dots from %j', (input, expected) => {
126 - expect(safeBasename(input)).toBe(expected);
129 + ['report.txt.', 'report', '.txt'],
130 + ['report. .', 'report', ''],
131 + ['report.\u00a0', 'report', ''],
132 + ['report.\u0085', 'report', ''],
133 + ['\ufeff..', '\ufeff', ''],
134 + ])('drops trailing spaces and dots from %j', (input, stem, extension) => {
135 + expect(safeBasename(input)).toMatch(tagged(stem, extension));
136 });
137
138 it.each([
130 - ['NUL', '_NUL'],
131 - ['nul', '_nul'],
132 - ['NUL.tar.gz', '_NUL.tar.gz'],
133 - ['COM1.log.bak', '_COM1.log.bak'],
134 - ['COM¹.txt', '_COM¹.txt'],
135 - ['LPT³.data', '_LPT³.data'],
136 - ['aux.txt', '_aux.txt'],
137 - ['CON .txt', '_CON .txt'],
138 - ['COM1:.txt', 'COM1_.txt'],
139 - ])('prefixes reserved device name %j', (input, expected) => {
140 - expect(safeBasename(input)).toBe(expected);
139 + ['NUL', '_NUL', ''],
140 + ['nul', '_nul', ''],
141 + ['NUL.tar.gz', '_NUL.tar', '.gz'],
142 + ['COM1.log.bak', '_COM1.log', '.bak'],
143 + ['COM¹.txt', '_COM¹', '.txt'],
144 + ['LPT³.data', '_LPT³', '.data'],
145 + ['aux.txt', '_aux', '.txt'],
146 + ['CON .txt', '_CON ', '.txt'],
147 + ['COM1:.txt', 'COM1_', '.txt'],
148 + ])('prefixes reserved device name %j', (input, stem, extension) => {
149 + expect(safeBasename(input)).toMatch(tagged(stem, extension));
150 });
151
152 it('prefixes a device name exposed by truncation or trailing-space removal', () => {
153 // Truncation keeps `NUL` plus spaces before `.txt`, and Windows ignores
154 // the spaces, so the checked name must be the fitted one.
146 - expect(safeBasename(`NUL${' '.repeat(200)}x.txt`)).toBe(`_NUL${' '.repeat(120)}.txt`);
147 - expect(safeBasename(`CON${' '.repeat(200)}x`)).toBe('_CON');
155 + expect(safeBasename(`NUL${' '.repeat(200)}x.txt`)).toMatch(
156 + tagged(`_NUL${' '.repeat(MAX_FILENAME_BYTES - TAG_BYTES - 8)}`, '.txt')
157 + );
158 + expect(safeBasename(`CON${' '.repeat(200)}x`)).toMatch(tagged('_CON'));
159 });
160
161 it('truncates a long name to the byte limit and keeps its extension', () => {
162 const result = safeBasename(`${'x'.repeat(200)}.pdf`);
152 - expect(result).toBe(`${'x'.repeat(MAX_FILENAME_BYTES - 4)}.pdf`);
163 + expect(result).toMatch(tagged('x'.repeat(MAX_FILENAME_BYTES - TAG_BYTES - 4), '.pdf'));
164 + expect(result).toHaveLength(MAX_FILENAME_BYTES);
165 });
166
167 it('truncates by whole code points, measured in bytes', () => {
168 // Each CJK character is one UTF-16 code unit but three UTF-8 bytes, and
169 // each emoji is two code units but four bytes.
170 const cjk = safeBasename(`${'請'.repeat(70)}.pdf`);
159 - expect(cjk).toBe(`${'請'.repeat(41)}.pdf`);
171 + expect(cjk).toMatch(tagged('請'.repeat(35), '.pdf'));
172 expect(new TextEncoder().encode(cjk).length).toBeLessThanOrEqual(MAX_FILENAME_BYTES);
161 - expect(safeBasename('😀'.repeat(33))).toBe('😀'.repeat(32));
173 + expect(safeBasename('😀'.repeat(33))).toMatch(tagged('😀'.repeat(27)));
174 });
175
176 it('truncates an over-long extension with the rest of the name', () => {
177 const result = safeBasename(`report.${'x'.repeat(200)}`);
166 - expect(result).toBe(`report.${'x'.repeat(MAX_FILENAME_BYTES - 7)}`);
178 + expect(result).toMatch(tagged(`report.${'x'.repeat(MAX_FILENAME_BYTES - TAG_BYTES - 7)}`));
179 });
180
181 it('drops a trailing dot exposed by truncation', () => {
182 const name = `${'x'.repeat(MAX_FILENAME_BYTES - 1)}.${'y'.repeat(40)}`;
171 - expect(safeBasename(name)).toBe('x'.repeat(MAX_FILENAME_BYTES - 1));
183 + expect(safeBasename(name)).toMatch(tagged('x'.repeat(MAX_FILENAME_BYTES - TAG_BYTES)));
184 + });
185 + });
186 +
187 + describe('keeps names that portability changed from colliding', () => {
188 + // `TestSafeBasename` in the Python SDK asserts the same vectors, so both
189 + // SDKs write a given server name to the same file.
190 + it.each([
191 + ['report?.png', 'report_-05fcb95aa5b918e9.png'],
192 + ['report*.png', 'report_-aa921bdab2b33292.png'],
193 + ['report_2026-09-29T10:30:00.csv', 'report_2026-09-29T10_30_00-d7211bb25cb815fe.csv'],
194 + ['NUL.txt', '_NUL-d0848f78ce05ded6.txt'],
195 + ])('tags %j with a digest of the original name', (input, expected) => {
196 + expect(safeBasename(input)).toBe(expected);
197 + });
198 +
199 + it('writes distinct names that normalize alike to distinct files', () => {
200 + const names = ['report?.png', 'report*.png', 'report:.png', 'report_.png'];
201 + expect(new Set(names.map(name => safeBasename(name))).size).toBe(names.length);
202 + });
203 +
204 + it('writes distinct long names that share a truncated prefix to distinct files', () => {
205 + const prefix = 'a'.repeat(200);
206 + expect(safeBasename(`${prefix}-1.txt`)).not.toBe(safeBasename(`${prefix}-2.txt`));
207 + });
208 +
209 + it('returns an already portable name unchanged', () => {
210 + expect(safeBasename('report_.png')).toBe('report_.png');
211 + });
212 +
213 + it('treats a tagged name as already portable', () => {
214 + const written = safeBasename('report?.png');
215 + expect(safeBasename(written)).toBe(written);
216 });
217 });
218