@devries-cameron20 / composio-1 / commits / 8c7e40a00
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.

fix(sdk): write server-provided file names portably instead of rejecting them

`safeBasename` (TS) and `safe_basename` (Python) refused names that ordinary files have: a `:` or `?`, a name over 128 bytes, a trailing dot, or a Windows device name. `RemoteFile.save()` without a path and Python automatic file downloads failed on them, the latter after the tool had already run. Both helpers now replace Windows-reserved and control characters with `_`, prefix device names with `_`, truncate long names keeping a short extension, and drop trailing spaces and dots. Names with a NUL byte, invalid Unicode, or no usable basename are still refused. Python automatic downloads also follow redirects again, through `safe_request`, which validates and pins every hop, as the TypeScript SDK already does.

jkomyno committed Sep 29, 2026 at 15:02 UTC 8c7e40a00eaa264592fa9739b2c439739fdcbe8f
9 files changed +402 -216
.changeset/remote-file-portable-names.md new
+5
@@ -0,0 +1,5 @@
1 +---
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.
python/composio/core/models/_files.py
+4 -1
@@ -716,8 +716,11 @@ class FileDownloadable(BaseModel):
716 outfile = secure_basename_join(outdir, self.name, root=root)
717 except UnsafePathComponentError as e:
718 raise ErrorDownloadingFile(str(e)) from e
719 + # A presigned storage URL can legitimately answer with a redirect (an S3
720 + # region redirect, say), so it is followed, with every hop validated.
721 try:
720 - response = safe_get(
722 + response = safe_request(
723 + "GET",
724 self.s3url,
725 stream=True,
726 timeout=(_CONNECT_TIMEOUT, _READ_TIMEOUT),
python/composio/utils/safe_path.py
+79 -48
@@ -58,8 +58,16 @@ WINDOWS_RESERVED_NAMES = frozenset(
58 | {f"LPT{i}" for i in "¹²³"}
59 )
60 """Reserved DOS device names. Writing to one on Windows targets the device
61 -rather than a file. Rejected on every platform so behaviour does not diverge
62 -between a POSIX developer machine and a Windows deployment."""
61 +rather than a file. Rejected as slugs and prefixed in filenames, on every
62 +platform, so behaviour does not diverge between a POSIX developer machine and a
63 +Windows deployment."""
64 +
65 +MAX_PRESERVED_EXTENSION_BYTES = 32
66 +"""Longest extension, in bytes and including its dot, that filename truncation
67 +keeps. Anything longer is not a real extension and is truncated with the rest."""
68 +
69 +_WINDOWS_INVALID_FILENAME_CHARS = re.compile(r'[\x00-\x1f<>:"|?*]')
70 +"""Control characters and characters reserved by Windows."""
71
72
73 def is_inside_dir(child: Path, parent: Path) -> bool:
@@ -141,80 +149,103 @@ def assert_safe_path_component(value: str, *, label: str = "path component") ->
149 return value
150
151
152 +def _encoded_length(value: str) -> int:
153 + return len(os.fsencode(value))
154 +
155 +
156 +def _truncate_to_bytes(value: str, max_bytes: int) -> str:
157 + """The longest prefix of ``value``, by whole code points, that fits in
158 + ``max_bytes``."""
159 + truncated = []
160 + size = 0
161 + for char in value:
162 + size += _encoded_length(char)
163 + if size > max_bytes:
164 + break
165 + truncated.append(char)
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
174 + dot = name.rfind(".")
175 + 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)
181 +
182 +
183 def safe_basename(name: str, *, label: str = "filename") -> str:
145 - """Collapse an untrusted filename to a bare, writable basename.
184 + """Collapse an untrusted filename to a bare basename that is safe to write
185 + on every platform.
186
187 Filenames need their own validator: :func:`assert_safe_path_component`
148 - forbids ``.``, which nearly every real filename contains. This applies the
149 - remaining checks — no separators, no traversal, no NUL, bounded length, no
150 - reserved device name — to the one component a server most directly controls.
188 + forbids ``.``, which nearly every real filename contains.
189
190 ``PureWindowsPath`` treats both ``/`` and ``\\`` as separators, so a name
191 crafted for a Windows target (``..\\..\\evil``) is stripped even when the
192 SDK runs on POSIX, where ``Path(...).name`` would return it intact.
193
156 - Names that leave no usable basename are refused rather than replaced with a
157 - generated one: a response that cannot name its own file is malformed or
158 - hostile, and inventing a name would hide that. ``.`` and the empty string
159 - both basename to ``""``, which makes an output path equal to its own
160 - directory and surfaces as ``IsADirectoryError`` at write time.
161 -
162 - The usability check runs on the *stripped* basename, because that is the
163 - value that gets written: ``str.strip`` removes Unicode whitespace, so
164 - ``"\\u00a0.\\u00a0"`` would otherwise pass a check on the raw segment and
165 - then be written as ``"."``. The hazard checks that follow stay on the raw
166 - segment so that a trailing ASCII space or dot is refused, not trimmed away.
167 -
168 - :raises UnsafePathComponentError: when ``name`` yields no usable basename or
169 - is unsafe to write.
194 + Names that cannot be written at all are refused: a NUL byte, invalid
195 + Unicode, or no usable basename (empty or a run of dots). A response that
196 + cannot name its own file is malformed or hostile, and inventing a name
197 + would hide that. ``.`` and the empty string both basename to ``""``, which
198 + makes an output path equal to its own directory and surfaces as
199 + ``IsADirectoryError`` at write time.
200 +
201 + Names that are merely unportable are made portable instead, because
202 + ordinary files have them (``report_2026-09-29T10:30:00.csv``,
203 + ``What is this?.png``), on every platform so a name does not depend on
204 + where the SDK runs: control and Windows-reserved characters become ``_``,
205 + reserved device names get a ``_`` prefix, names over
206 + :data:`MAX_COMPONENT_LENGTH` bytes are truncated with their extension kept,
207 + and trailing spaces and dots are dropped as Windows would. ``safeBasename``
208 + in the TypeScript SDK applies the same rules in the same order.
209 +
210 + ``str.strip`` removes surrounding whitespace first, and the usability check
211 + runs last, on the value that gets written, so neither ``"\\u00a0.\\u00a0"``
212 + nor ``". ."`` can be written as ``.`` or as its own directory.
213 +
214 + :raises UnsafePathComponentError: when ``name`` contains a NUL byte or
215 + invalid Unicode, or leaves no usable basename.
216 """
217 if not isinstance(name, str):
218 raise UnsafePathComponentError(
219 f"Refusing to write a non-string {label}: {name!r}"
220 )
221
176 - raw_basename = PureWindowsPath(name).name
177 - basename = raw_basename.strip()
178 - if not basename or set(basename) == {"."}:
179 - raise UnsafePathComponentError(
180 - f"Path traversal detected: {label} {name!r} leaves no usable "
181 - "basename to write to."
182 - )
183 - if "\x00" in raw_basename:
222 + basename = PureWindowsPath(name).name.strip()
223 + if "\x00" in basename:
224 raise UnsafePathComponentError(
225 f"Refusing to write {label} containing a NUL byte: {name!r}"
226 )
187 - if any(ord(char) < 32 or char in '<>:"|?*' for char in raw_basename):
188 - raise UnsafePathComponentError(
189 - f"Refusing to write {label} containing characters reserved by "
190 - f"Windows: {name!r}"
191 - )
192 - # Stripping Unicode whitespace can expose a trailing dot on the written name.
193 - if raw_basename.endswith((" ", ".")) or basename.endswith("."):
194 - raise UnsafePathComponentError(
195 - f"Refusing to write {label} ending in a space or dot: {name!r}"
196 - )
197 -
227 try:
199 - encoded_length = len(os.fsencode(basename))
228 + _encoded_length(basename)
229 except UnicodeEncodeError as e:
230 raise UnsafePathComponentError(
231 f"Refusing to write {label} containing invalid Unicode: {name!r}"
232 ) from e
204 - if encoded_length > MAX_COMPONENT_LENGTH:
205 - raise UnsafePathComponentError(
206 - f"Refusing to write {label} longer than {MAX_COMPONENT_LENGTH} bytes: "
207 - f"{basename[:32]!r}... ({encoded_length} bytes)"
208 - )
233 +
234 + portable = _WINDOWS_INVALID_FILENAME_CHARS.sub("_", basename)
235 # Compare everything before the first dot: on Windows `NUL.tar.gz` opens
236 # the null device just as `NUL` does, so any number of extensions provides
237 # no protection.
212 - device_name = basename.split(".", 1)[0].rstrip(" ").upper()
238 + device_name = portable.split(".", 1)[0].rstrip(" ").upper()
239 if device_name in WINDOWS_RESERVED_NAMES:
240 + portable = f"_{portable}"
241 + portable = _fit_filename_bytes(portable).rstrip(". ")
242 +
243 + if not portable:
244 raise UnsafePathComponentError(
215 - f"Refusing to write {label} that is a reserved device name: {name!r}"
245 + f"Path traversal detected: {label} {name!r} leaves no usable "
246 + "basename to write to."
247 )
217 - return basename
248 + return portable
249
250
251 def resolve_root(root: t.Union[str, Path]) -> Path:
python/tests/test_files.py
+74 -50
@@ -2659,7 +2659,7 @@ class TestDownloadSizeLimit:
2659 s3url="https://example.com/report.bin",
2660 )
2661
2662 - @patch("composio.core.models._files.safe_get")
2662 + @patch("composio.core.models._files.safe_request")
2663 def test_download_rejects_oversized_content_length(self, mock_get, tmp_path):
2664 """A self-declared oversized body is rejected before any bytes are read."""
2665 mock_response = MagicMock()
@@ -2673,7 +2673,7 @@ class TestDownloadSizeLimit:
2673
2674 mock_response.iter_content.assert_not_called()
2675
2676 - @patch("composio.core.models._files.safe_get")
2676 + @patch("composio.core.models._files.safe_request")
2677 def test_download_rejects_oversized_during_streaming(self, mock_get, tmp_path):
2678 """A dishonest (here, absent) Content-Length cannot bypass the cap."""
2679 mock_response = MagicMock()
@@ -2686,7 +2686,7 @@ class TestDownloadSizeLimit:
2686 with pytest.raises(ResponseTooLargeError):
2687 self._downloadable().download(outdir=tmp_path, root=tmp_path, max_size=1024)
2688
2689 - @patch("composio.core.models._files.safe_get")
2689 + @patch("composio.core.models._files.safe_request")
2690 def test_download_removes_partial_file_on_failure(self, mock_get, tmp_path):
2691 """A truncated download must not be left behind as if it succeeded."""
2692 mock_response = MagicMock()
@@ -2701,7 +2701,7 @@ class TestDownloadSizeLimit:
2701
2702 assert list(tmp_path.iterdir()) == []
2703
2704 - @patch("composio.core.models._files.safe_get")
2704 + @patch("composio.core.models._files.safe_request")
2705 def test_download_accepts_file_within_limit(self, mock_get, tmp_path):
2706 """A body under the cap is written through unchanged."""
2707 mock_response = MagicMock()
@@ -2718,7 +2718,7 @@ class TestDownloadSizeLimit:
2718 assert outfile.exists()
2719 assert outfile.read_bytes() == b"x" * 256 + b"y" * 256
2720
2721 - @patch("composio.core.models._files.safe_get")
2721 + @patch("composio.core.models._files.safe_request")
2722 def test_download_wraps_stream_failure_and_removes_partial_file(
2723 self, mock_get, tmp_path
2724 ):
@@ -2740,7 +2740,7 @@ class TestDownloadSizeLimit:
2740
2741 assert list(tmp_path.iterdir()) == []
2742
2743 - @patch("composio.core.models._files.safe_get")
2743 + @patch("composio.core.models._files.safe_request")
2744 def test_download_wraps_write_failure_and_removes_partial_file(
2745 self, mock_get, tmp_path
2746 ):
@@ -2942,7 +2942,7 @@ class TestFileDownloadablePathTraversal:
2942 s3url="https://example.com/file",
2943 )
2944 with patch(
2945 - "composio.core.models._files.safe_get",
2945 + "composio.core.models._files.safe_request",
2946 return_value=self._mock_response(b"#!/bin/sh\n"),
2947 ):
2948 written = f.download(outdir, root=outdir)
@@ -2961,7 +2961,7 @@ class TestFileDownloadablePathTraversal:
2961 s3url="https://example.com/file",
2962 )
2963 with patch(
2964 - "composio.core.models._files.safe_get",
2964 + "composio.core.models._files.safe_request",
2965 return_value=self._mock_response(b"x"),
2966 ):
2967 written = f.download(outdir, root=outdir)
@@ -2982,7 +2982,7 @@ class TestFileDownloadablePathTraversal:
2982 s3url="https://example.com/file",
2983 )
2984 with patch(
2985 - "composio.core.models._files.safe_get",
2985 + "composio.core.models._files.safe_request",
2986 return_value=self._mock_response(),
2987 ):
2988 with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):
@@ -2998,7 +2998,7 @@ class TestFileDownloadablePathTraversal:
2998 s3url="https://example.com/file",
2999 )
3000 with patch(
3001 - "composio.core.models._files.safe_get",
3001 + "composio.core.models._files.safe_request",
3002 return_value=self._mock_response(b"%PDF-1.4"),
3003 ):
3004 written = f.download(outdir, root=outdir)
@@ -3014,12 +3014,13 @@ class TestFileDownloadablePathTraversal:
3014 s3url="https://example.com/file",
3015 )
3016 with patch(
3017 - "composio.core.models._files.safe_get",
3017 + "composio.core.models._files.safe_request",
3018 return_value=self._mock_response(b"%PDF-1.4"),
3019 ) as mock_get:
3020 f.download(outdir, root=outdir)
3021
3022 mock_get.assert_called_once_with(
3023 + "GET",
3024 "https://example.com/file",
3025 stream=True,
3026 timeout=(5, 60),
@@ -3033,7 +3034,7 @@ class TestFileDownloadablePathTraversal:
3034 s3url="https://example.com/file?token=abc",
3035 )
3036 with patch(
3036 - "composio.core.models._files.safe_get",
3037 + "composio.core.models._files.safe_request",
3038 side_effect=requests.exceptions.Timeout(
3039 "Max retries exceeded with url: /file?token=abc"
3040 ),
@@ -3058,7 +3059,7 @@ class TestFileDownloadablePathTraversal:
3059 s3url="https://example.com/file?token=abc",
3060 )
3061 with patch(
3061 - "composio.core.models._files.safe_get",
3062 + "composio.core.models._files.safe_request",
3063 return_value=response,
3064 ):
3065 with pytest.raises(ErrorDownloadingFile) as exc_info:
@@ -3078,7 +3079,7 @@ class TestFileDownloadablePathTraversal:
3079 s3url="https://example.com/file?token=abc",
3080 )
3081 with patch(
3081 - "composio.core.models._files.safe_get",
3082 + "composio.core.models._files.safe_request",
3083 return_value=response,
3084 ):
3085 with pytest.raises(ErrorDownloadingFile) as exc_info:
@@ -3102,7 +3103,7 @@ class TestFileDownloadablePathTraversal:
3103 s3url="https://example.com/file",
3104 )
3105 with patch(
3105 - "composio.core.models._files.safe_get",
3106 + "composio.core.models._files.safe_request",
3107 return_value=self._mock_response(),
3108 ):
3109 with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):
@@ -3129,7 +3130,7 @@ class TestFileDownloadablePathTraversal:
3130 s3url="https://example.com/file",
3131 )
3132 with patch(
3132 - "composio.core.models._files.safe_get",
3133 + "composio.core.models._files.safe_request",
3134 return_value=self._mock_response(b"x"),
3135 ):
3136 with pytest.raises(ErrorDownloadingFile, match="no usable basename"):
@@ -3138,26 +3139,41 @@ class TestFileDownloadablePathTraversal:
3139 # Rejected before `mkdir`, so nothing was created on disk at all.
3140 assert not outdir.exists()
3141
3142 + def test_nul_byte_filename_is_rejected(self, tmp_path):
3143 + """`self.name` is untrusted by the same rule as the slugs. Without this
3144 + check a NUL byte escapes as a raw ValueError from `resolve()`."""
3145 + from composio.exceptions import ErrorDownloadingFile
3146 +
3147 + outdir = tmp_path / "safe"
3148 + f = FileDownloadable(
3149 + name="a\x00b",
3150 + mimetype="application/octet-stream",
3151 + s3url="https://example.com/file",
3152 + )
3153 + with patch(
3154 + "composio.core.models._files.safe_request",
3155 + return_value=self._mock_response(b"x"),
3156 + ):
3157 + with pytest.raises(ErrorDownloadingFile, match="NUL byte"):
3158 + f.download(outdir, root=outdir)
3159 + assert not outdir.exists()
3160 +
3161 @pytest.mark.parametrize(
3142 - "name,reason",
3162 + "name,expected",
3163 [
3144 - ("NUL", "reserved device name"),
3145 - ("nul.txt", "reserved device name"),
3146 - ("NUL.tar.gz", "reserved device name"),
3147 - ("COM1", "reserved device name"),
3148 - ("report.txt:payload", "reserved by Windows"),
3149 - ("a\x00b", "NUL byte"),
3150 - ("😀" * 128, "longer than"),
3151 - ("x" * 300, "longer than"),
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"),
3171 ],
3172 )
3154 - def test_unsafe_filenames_are_rejected(self, name, reason, tmp_path):
3155 - """`self.name` is untrusted by the same rule as the slugs. Without these
3156 - checks a NUL byte escapes as a raw ValueError from `resolve()`, an
3157 - over-long name as a raw OSError mid-write, and `NUL` opens the Windows
3158 - null device — silently discarding the payload while returning a path."""
3159 - from composio.exceptions import ErrorDownloadingFile
3160 -
3173 + def test_unportable_filenames_are_made_portable(self, name, expected, tmp_path):
3174 + """Ordinary names with a `:` or `?`, reserved device names, and names over
3175 + the byte limit are written under a portable name rather than failing
3176 + the download after the tool has already run."""
3177 outdir = tmp_path / "safe"
3178 f = FileDownloadable(
3179 name=name,
@@ -3165,12 +3181,12 @@ class TestFileDownloadablePathTraversal:
3181 s3url="https://example.com/file",
3182 )
3183 with patch(
3168 - "composio.core.models._files.safe_get",
3184 + "composio.core.models._files.safe_request",
3185 return_value=self._mock_response(b"x"),
3186 ):
3171 - with pytest.raises(ErrorDownloadingFile, match=reason):
3172 - f.download(outdir, root=outdir)
3173 - assert not outdir.exists()
3187 + outfile = f.download(outdir, root=outdir)
3188 + assert outfile == (outdir / expected).resolve()
3189 + assert outfile.read_bytes() == b"x"
3190
3191
3192 class TestDownloadDirSlugTraversal:
@@ -3220,7 +3236,7 @@ class TestDownloadDirSlugTraversal:
3236 response.status_code = 200
3237 response.iter_content = lambda chunk_size: [content]
3238 response.close = MagicMock()
3223 - return patch("composio.core.models._files.safe_get", return_value=response)
3239 + return patch("composio.core.models._files.safe_request", return_value=response)
3240
3241 @pytest.mark.parametrize("slug", TRAVERSALS)
3242 def test_hostile_tool_slug_is_rejected(self, slug, tmp_path):
@@ -3469,14 +3485,14 @@ class TestResponseDerivedUrlsAreGuarded:
3485 s3url="https://s3.example.com/file",
3486 )
3487 with patch(
3472 - "composio.core.models._files.safe_get",
3488 + "composio.core.models._files.safe_request",
3489 return_value=self._download_response(),
3490 ) as mock_get:
3491 f.download(tmp_path / "out", root=tmp_path / "out")
3492
3477 - # `safe_get` is the guard: it validates the target and connects to the
3478 - # address it validated, rather than re-resolving the hostname.
3479 - assert mock_get.call_args.args == ("https://s3.example.com/file",)
3493 + # `safe_request` is the guard: it validates each hop and connects to
3494 + # the address it validated, rather than re-resolving the hostname.
3495 + assert mock_get.call_args.args == ("GET", "https://s3.example.com/file")
3496
3497 def test_download_blocked_url_never_reaches_the_network(self, tmp_path):
3498 outdir = tmp_path / "out"
@@ -3498,21 +3514,29 @@ class TestResponseDerivedUrlsAreGuarded:
3514 mock_send.assert_not_called()
3515 assert not outdir.exists()
3516
3501 - def test_download_refuses_to_follow_redirects(self, tmp_path):
3517 + def test_download_follows_a_validated_redirect(self, tmp_path):
3518 + """A presigned URL may answer with a redirect (an S3 region redirect,
3519 + say). The download follows it, and every hop goes through the pinned,
3520 + validated request rather than a plain ``requests`` redirect."""
3521 + redirect = MagicMock()
3522 + redirect.status_code = 307
3523 + redirect.headers = {"Location": "https://s3.eu.example.com/file"}
3524 f = FileDownloadable(
3525 name="report.pdf",
3526 mimetype="application/pdf",
3527 s3url="https://s3.example.com/file",
3528 )
3529 with patch(
3508 - "composio.core.models._files.safe_get",
3509 - return_value=self._download_response(),
3510 - ) as mock_get:
3511 - f.download(tmp_path / "out", root=tmp_path / "out")
3512 -
3513 - # `safe_get` never follows redirects, and passing `allow_redirects`
3514 - # through to it would be a way to turn that off.
3515 - assert "allow_redirects" not in mock_get.call_args.kwargs
3530 + "composio.utils.url_safety._pinned_request",
3531 + side_effect=[redirect, self._download_response()],
3532 + ) as mock_pinned:
3533 + outfile = f.download(tmp_path / "out", root=tmp_path / "out")
3534 +
3535 + assert outfile.read_bytes() == b"%PDF-1.4"
3536 + assert [call.args[:2] for call in mock_pinned.call_args_list] == [
3537 + ("GET", "https://s3.example.com/file"),
3538 + ("GET", "https://s3.eu.example.com/file"),
3539 + ]
3540
3541 def test_upload_bytes_to_s3_goes_through_safe_request(self):
3542 client = self._s3_client("https://s3.example.com/upload")
python/tests/test_safe_path.py
+74 -18
@@ -11,6 +11,7 @@ import pytest
11
12 from composio.exceptions import UnsafePathComponentError
13 from composio.utils.safe_path import (
14 + MAX_COMPONENT_LENGTH,
15 SAFE_COMPONENT_REGEX,
16 assert_safe_path_component,
17 is_inside_dir,
@@ -172,32 +173,87 @@ class TestSafeBasename:
173 with pytest.raises(UnsafePathComponentError, match="no usable basename"):
174 safe_basename(value)
175
176 + @pytest.mark.parametrize("value", [". .", ".. ", " . . "])
177 + def test_rejects_dot_runs_once_windows_trims_them(self, value):
178 + with pytest.raises(UnsafePathComponentError, match="no usable basename"):
179 + safe_basename(value)
180 +
181 + def test_rejects_nul_byte(self):
182 + with pytest.raises(UnsafePathComponentError, match="NUL byte"):
183 + safe_basename("report\x00.pdf")
184 +
185 @pytest.mark.parametrize(
176 - "value",
177 - ["NUL.tar.gz", "COM1.log.bak", "COM¹.txt", "LPT³.data"],
186 + ("value", "expected"),
187 + [
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"),
197 + ],
198 )
179 - def test_rejects_windows_device_names_with_any_extension(self, value):
180 - with pytest.raises(UnsafePathComponentError, match="reserved device name"):
181 - safe_basename(value)
199 + def test_replaces_windows_reserved_characters(self, value, expected):
200 + assert safe_basename(value) == expected
201
202 @pytest.mark.parametrize(
184 - "value",
203 + ("value", "expected"),
204 [
186 - "report?.txt",
187 - "report.txt:payload",
188 - "report.txt.",
189 - "report.txt ",
190 - "report.\u00a0",
191 - "report.\u0085",
205 + ("report.txt.", "report.txt"),
206 + ("report.txt ", "report.txt"),
207 + ("report. .", "report"),
208 + ("report.\u00a0", "report"),
209 + ("report.\u0085", "report"),
210 + ("\ufeff..", "\ufeff"),
211 ],
212 )
194 - def test_rejects_windows_invalid_names_on_every_platform(self, value):
195 - with pytest.raises(UnsafePathComponentError):
196 - safe_basename(value)
213 + def test_drops_trailing_spaces_and_dots(self, value, expected):
214 + assert safe_basename(value) == expected
215
198 - def test_limits_encoded_filename_bytes(self):
199 - with pytest.raises(UnsafePathComponentError, match="longer than"):
200 - safe_basename("😀" * 128)
216 + @pytest.mark.parametrize(
217 + ("value", "expected"),
218 + [
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"),
228 + ],
229 + )
230 + def test_prefixes_windows_device_names_with_any_extension(self, value, expected):
231 + assert safe_basename(value) == expected
232 +
233 + def test_keeps_a_filename_at_the_byte_limit(self):
234 + name = "x" * MAX_COMPONENT_LENGTH
235 + assert safe_basename(name) == name
236 +
237 + def test_truncates_to_the_byte_limit_and_keeps_the_extension(self):
238 + assert (
239 + safe_basename("x" * 200 + ".pdf")
240 + == "x" * (MAX_COMPONENT_LENGTH - 4) + ".pdf"
241 + )
242 +
243 + def test_truncates_by_whole_code_points_measured_in_bytes(self):
244 + cjk = safe_basename("請" * 70 + ".pdf")
245 + assert cjk == "請" * 41 + ".pdf"
246 + assert len(cjk.encode()) <= MAX_COMPONENT_LENGTH
247 + assert safe_basename("😀" * 33) == "😀" * 32
248 +
249 + def test_truncates_an_over_long_extension_with_the_rest(self):
250 + assert safe_basename("report." + "x" * 200) == "report." + "x" * (
251 + MAX_COMPONENT_LENGTH - 7
252 + )
253 +
254 + def test_drops_a_trailing_dot_exposed_by_truncation(self):
255 + name = "x" * (MAX_COMPONENT_LENGTH - 1) + "." + "y" * 40
256 + assert safe_basename(name) == "x" * (MAX_COMPONENT_LENGTH - 1)
257
258 def test_rejects_unencodable_filename(self):
259 with pytest.raises(UnsafePathComponentError, match="invalid Unicode"):
python/tests/test_tool_router_session_files.py
+15 -6
@@ -352,19 +352,28 @@ class TestRemoteFile:
352
353 assert not (tmp_path / ".composio").exists()
354
355 - @pytest.mark.parametrize("mount_relative_path", ["report.\u00a0", "report.\u0085"])
356 - def test_save_rejects_dot_exposed_by_stripping(self, tmp_path, mount_relative_path):
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"),
361 + ],
362 + )
363 + def test_save_makes_unportable_names_portable(
364 + self, tmp_path, mount_relative_path, expected
365 + ):
366 rf = RemoteFile(
367 expires_at="2026-01-01",
368 mount_relative_path=mount_relative_path,
369 sandbox_mount_prefix="/mnt/files",
370 download_url="https://example.com/file",
371 )
363 - with patch.object(rf, "buffer", return_value=b"should not be written"):
372 + with patch.object(rf, "buffer", return_value=b"content"):
373 with patch("pathlib.Path.home", return_value=tmp_path):
365 - with pytest.raises(ValidationError, match="ending in a space or dot"):
366 - rf.save()
367 - assert not (tmp_path / ".composio").exists()
374 + saved = Path(rf.save())
375 + assert saved.name == expected
376 + assert saved.read_bytes() == b"content"
377
378
379 class TestResponseDerivedUrlsAreGuarded:
ts/packages/core/src/utils/safePath.ts
+80 -53
@@ -17,14 +17,21 @@ import { ValidationError } from '../errors/ValidationErrors';
17
18 /**
19 * Upper bound on a filename, well under the 255-byte limit common to
20 - * ext4/APFS/NTFS. Keeps a long server-supplied name from failing with a raw
21 - * `ENAMETOOLONG` mid-write. Matches `MAX_COMPONENT_LENGTH` in the Python SDK.
20 + * ext4/APFS/NTFS. A longer server-supplied name is truncated to fit rather
21 + * than failing with a raw `ENAMETOOLONG` mid-write. Matches
22 + * `MAX_COMPONENT_LENGTH` in the Python SDK.
23 */
24 export const MAX_FILENAME_BYTES = 128;
25
26 +/**
27 + * Longest extension, in bytes and including its dot, that truncation keeps.
28 + * Anything longer is not a real extension and is truncated with the rest.
29 + */
30 +const MAX_PRESERVED_EXTENSION_BYTES = 32;
31 +
32 /**
33 * Reserved DOS device names. Writing to one on Windows targets the device
27 - * rather than a file. Rejected on every platform so behavior does not diverge
34 + * rather than a file. Prefixed on every platform so behavior does not diverge
35 * between a POSIX developer machine and a Windows deployment.
36 */
37 const WINDOWS_RESERVED_NAMES: ReadonlySet<string> = new Set([
@@ -38,7 +45,12 @@ const WINDOWS_RESERVED_NAMES: ReadonlySet<string> = new Set([
45 ]);
46
47 /** Control characters and characters reserved by Windows. */
41 -const WINDOWS_INVALID_CHARS = /[\u0000-\u001f<>:"|?*]/;
48 +const WINDOWS_INVALID_CHARS = /[\u0000-\u001f<>:"|?*]/g;
49 +
50 +/** Windows drops trailing spaces and dots from a filename. */
51 +const TRAILING_SPACES_AND_DOTS = /[. ]+$/;
52 +
53 +const utf8Length = (value: string): number => new TextEncoder().encode(value).length;
54
55 /**
56 * Python str.strip() whitespace: Unicode White_Space plus U+001C–U+001F.
@@ -93,80 +105,95 @@ function hasLoneSurrogate(value: string): boolean {
105 return false;
106 }
107
108 +/** The longest prefix of `value`, by whole code points, that fits in `maxBytes`. */
109 +function truncateToBytes(value: string, maxBytes: number): string {
110 + let truncated = '';
111 + let bytes = 0;
112 + for (const char of value) {
113 + bytes += utf8Length(char);
114 + if (bytes > maxBytes) {
115 + break;
116 + }
117 + truncated += char;
118 + }
119 + return truncated;
120 +}
121 +
122 +/**
123 + * Truncates `name` to {@link MAX_FILENAME_BYTES}, keeping a short extension so
124 + * the file still opens with the right application.
125 + */
126 +function fitFilenameBytes(name: string): string {
127 + if (utf8Length(name) <= MAX_FILENAME_BYTES) {
128 + return name;
129 + }
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);
137 +}
138 +
139 /**
97 - * Collapses an untrusted filename to a bare, writable basename.
140 + * Collapses an untrusted filename to a bare basename that is safe to write on
141 + * every platform.
142 *
99 - * Applies, in order: no usable basename (empty or a run of dots once
100 - * surrounding whitespace is stripped), NUL bytes, control and Windows-reserved
101 - * characters, trailing space or dot, invalid Unicode, a byte-length bound, and
102 - * reserved device names. This is the order `safe_basename` uses in the Python
103 - * SDK. This implementation rejects lone surrogates rather than relying on
104 - * Python filesystem encoding behavior.
143 + * Names that cannot be written at all are refused: a NUL byte, invalid
144 + * Unicode, or no usable basename (empty or a run of dots). A response that
145 + * cannot name its own file is malformed or hostile, and inventing a name would
146 + * hide that. `""`, `"."` and `".."` make an output path equal to, or escape,
147 + * its own directory, which surfaces as a raw `EISDIR` at write time instead of
148 + * a validation error.
149 *
106 - * Names that leave no usable basename are refused rather than replaced with a
107 - * generated one: a response that cannot name its own file is malformed or
108 - * hostile, and inventing a name would hide that. `""`, `"."` and `".."` make
109 - * an output path equal to, or escape, its own directory, which surfaces as a
110 - * raw `EISDIR` at write time instead of a validation error.
150 + * Names that are merely unportable are made portable instead, because ordinary
151 + * files have them (`report_2026-09-29T10:30:00.csv`, `What is this?.png`), on
152 + * every platform so a name does not depend on where the SDK runs:
153 + * control and Windows-reserved characters become `_`, reserved device names
154 + * get a `_` prefix, names over {@link MAX_FILENAME_BYTES} are truncated with
155 + * their extension kept, and trailing spaces and dots are dropped as Windows
156 + * would. `safe_basename` in the Python SDK applies the same rules in the same
157 + * order.
158 *
112 - * The usability check runs on the *trimmed* basename because that is what gets
113 - * written: Python-compatible stripping removes whitespace, so `"\u00a0.\u00a0"` would
114 - * otherwise pass a check on the raw segment and then be written as `"."`. The
115 - * hazard checks that follow run on the raw segment so a trailing ASCII space or
116 - * dot is refused, not trimmed away. Check the stripped value for trailing dots
117 - * too, since stripping whitespace can expose one.
159 + * Python-compatible stripping removes surrounding whitespace first, and the
160 + * usability check runs last, on the value that gets written, so neither
161 + * `"\u00a0.\u00a0"` nor `". ."` can be written as `.` or as its own directory.
162 *
163 * @param name - The untrusted filename or relative path to reduce.
164 * @param label - How the value is described in error messages.
121 - * @returns The validated bare basename, with surrounding whitespace trimmed.
122 - * @throws ValidationError if `name` yields no usable basename or is unsafe to write.
165 + * @returns The bare basename to write, adjusted to be portable.
166 + * @throws ValidationError if `name` contains a NUL byte or invalid Unicode, or
167 + * leaves no usable basename.
168 */
169 export function safeBasename(name: string, label: string = 'filename'): string {
125 - const rawBasename = untrustedBasename(name);
126 - const basename = rawBasename.replace(SURROUNDING_WHITESPACE, '');
170 + const basename = untrustedBasename(name).replace(SURROUNDING_WHITESPACE, '');
171
128 - if (!basename || /^\.+$/.test(basename)) {
129 - throw new ValidationError(
130 - `Path traversal detected: ${label} ${JSON.stringify(name)} leaves no usable basename to write to.`
131 - );
132 - }
133 - if (rawBasename.includes('\u0000')) {
172 + if (basename.includes('\u0000')) {
173 throw new ValidationError(
174 `Refusing to write ${label} containing a NUL byte: ${JSON.stringify(name)}`
175 );
176 }
138 - if (WINDOWS_INVALID_CHARS.test(rawBasename)) {
139 - throw new ValidationError(
140 - `Refusing to write ${label} containing characters reserved by Windows: ${JSON.stringify(name)}`
141 - );
142 - }
143 - if (rawBasename.endsWith(' ') || rawBasename.endsWith('.') || basename.endsWith('.')) {
144 - throw new ValidationError(
145 - `Refusing to write ${label} ending in a space or dot: ${JSON.stringify(name)}`
146 - );
147 - }
177 if (hasLoneSurrogate(basename)) {
178 throw new ValidationError(
179 `Refusing to write ${label} containing invalid Unicode: ${JSON.stringify(name)}`
180 );
181 }
182
154 - const encodedLength = new TextEncoder().encode(basename).length;
155 - if (encodedLength > MAX_FILENAME_BYTES) {
156 - throw new ValidationError(
157 - `Refusing to write ${label} longer than ${MAX_FILENAME_BYTES} bytes: ` +
158 - `${JSON.stringify(basename.slice(0, 32))}... (${encodedLength} bytes)`
159 - );
160 - }
161 -
183 + let portable = basename.replace(WINDOWS_INVALID_CHARS, '_');
184 // Compare everything before the first dot: on Windows `NUL.tar.gz` opens the
185 // null device just as `NUL` does, so extensions provide no protection.
164 - const deviceName = basename.split('.', 1)[0].replace(/ +$/, '').toUpperCase();
186 + const deviceName = portable.split('.', 1)[0].replace(/ +$/, '').toUpperCase();
187 if (WINDOWS_RESERVED_NAMES.has(deviceName)) {
188 + portable = `_${portable}`;
189 + }
190 + portable = fitFilenameBytes(portable).replace(TRAILING_SPACES_AND_DOTS, '');
191 +
192 + if (!portable) {
193 throw new ValidationError(
167 - `Refusing to write ${label} that is a reserved device name: ${JSON.stringify(name)}`
194 + `Path traversal detected: ${label} ${JSON.stringify(name)} leaves no usable basename to write to.`
195 );
196 }
197
171 - return basename;
198 + return portable;
199 }
ts/packages/core/test/models/RemoteFile.test.ts
+5 -10
@@ -319,6 +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`],
327 ])(
328 'should save %j under the default directory as %j',
329 async (mountRelativePath, expectedName) => {
@@ -351,16 +356,6 @@ describe('RemoteFile', () => {
356 }
357 );
358
354 - it.each(['report.\u00a0', 'report.\u0085'])(
355 - 'should reject a trailing dot exposed by stripping %j before creating directories',
356 - async mountRelativePath => {
357 - const { platform } = await import('../../src/platform/node');
358 - const file = new RemoteFile({ ...validCamelCaseData, mountRelativePath });
359 - await expect(file.save()).rejects.toThrow(/ending in a space or dot/);
360 - expect(platform.existsSync(composioDir)).toBe(false);
361 - }
362 - );
363 -
359 it('should still honor an explicit path when the mount path is unusable', async () => {
360 const { platform } = await import('../../src/platform/node');
361 const { join } = await import('node:path');
ts/packages/core/test/utils/safePath.test.ts
+66 -30
@@ -50,7 +50,7 @@ describe('safeBasename', () => {
50 expect(safeBasename(input)).toBe(expected);
51 });
52
53 - it('accepts a filename at the byte limit', () => {
53 + it('keeps a filename at the byte limit unchanged', () => {
54 const name = 'x'.repeat(MAX_FILENAME_BYTES);
55 expect(safeBasename(name)).toBe(name);
56 });
@@ -82,50 +82,86 @@ describe('safeBasename', () => {
82 });
83 });
84
85 - describe('rejects unsafe names', () => {
85 + describe('rejects names that cannot be written', () => {
86 it.each(['report\u0000.pdf', 'report.pdf\u0000.exe'])('rejects NUL byte in %j', input => {
87 expect(() => safeBasename(input)).toThrow(/NUL byte/);
88 });
89
90 - it.each([
91 - 'report?.txt',
92 - 'report.txt:payload',
93 - 'report<1>.txt',
94 - 'a|b.txt',
95 - 'tab\there.txt',
96 - '\u001creport.txt\u001f',
97 - 'output/C:report.txt',
98 - ])('rejects Windows-reserved characters in %j on every platform', input => {
99 - expect(() => safeBasename(input)).toThrow(/reserved by Windows/);
90 + it('rejects a lone surrogate, which cannot be encoded as UTF-8', () => {
91 + expect(() => safeBasename('report-\ud800.txt')).toThrow(/invalid Unicode/);
92 + expect(() => safeBasename('report-\udc00.txt')).toThrow(/invalid Unicode/);
93 });
94
102 - it.each(['report.txt.', 'report.txt ', '\ufeff..', 'report.\u00a0', 'report.\u0085'])(
103 - 'rejects trailing space or dot in %j',
95 + it.each(['. .', '.. ', ' . . '])(
96 + 'rejects %j, which is a dot run once Windows trims it',
97 input => {
105 - expect(() => safeBasename(input)).toThrow(/ending in a space or dot/);
98 + expect(() => safeBasename(input)).toThrow(/leaves no usable basename/);
99 }
100 );
101 + });
102
109 - it.each(['NUL', 'nul', 'NUL.tar.gz', 'COM1.log.bak', 'COM¹.txt', 'LPT³.data', 'aux.txt'])(
110 - 'rejects reserved device name %j with any extension',
111 - input => {
112 - expect(() => safeBasename(input)).toThrow(/reserved device name/);
113 - }
114 - );
103 + describe('makes unportable names portable on every platform', () => {
104 + 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 + });
117
116 - it('rejects a filename over the byte limit', () => {
117 - expect(() => safeBasename('x'.repeat(MAX_FILENAME_BYTES + 1))).toThrow(/longer than/);
118 + 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);
127 });
128
120 - it('measures the limit in bytes, not code units', () => {
121 - // Each emoji is two UTF-16 code units but four UTF-8 bytes.
122 - expect(safeBasename('😀'.repeat(32))).toBe('😀'.repeat(32));
123 - expect(() => safeBasename('😀'.repeat(33))).toThrow(/longer than/);
129 + 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);
141 });
142
126 - it('rejects a lone surrogate, which cannot be encoded as UTF-8', () => {
127 - expect(() => safeBasename('report-\ud800.txt')).toThrow(/invalid Unicode/);
128 - expect(() => safeBasename('report-\udc00.txt')).toThrow(/invalid Unicode/);
143 + it('truncates a long name to the byte limit and keeps its extension', () => {
144 + const result = safeBasename(`${'x'.repeat(200)}.pdf`);
145 + expect(result).toBe(`${'x'.repeat(MAX_FILENAME_BYTES - 4)}.pdf`);
146 + });
147 +
148 + it('truncates by whole code points, measured in bytes', () => {
149 + // Each CJK character is one UTF-16 code unit but three UTF-8 bytes, and
150 + // each emoji is two code units but four bytes.
151 + const cjk = safeBasename(`${'請'.repeat(70)}.pdf`);
152 + expect(cjk).toBe(`${'請'.repeat(41)}.pdf`);
153 + expect(new TextEncoder().encode(cjk).length).toBeLessThanOrEqual(MAX_FILENAME_BYTES);
154 + expect(safeBasename('😀'.repeat(33))).toBe('😀'.repeat(32));
155 + });
156 +
157 + it('truncates an over-long extension with the rest of the name', () => {
158 + const result = safeBasename(`report.${'x'.repeat(200)}`);
159 + expect(result).toBe(`report.${'x'.repeat(MAX_FILENAME_BYTES - 7)}`);
160 + });
161 +
162 + it('drops a trailing dot exposed by truncation', () => {
163 + const name = `${'x'.repeat(MAX_FILENAME_BYTES - 1)}.${'y'.repeat(40)}`;
164 + expect(safeBasename(name)).toBe('x'.repeat(MAX_FILENAME_BYTES - 1));
165 });
166 });
167