Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | """Tests for the path containment primitives in `composio.utils.safe_path`. |
| 2 | |
| 3 | 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 | |
| 11 | import pytest |
| 12 | |
| 13 | from composio.exceptions import UnsafePathComponentError |
| 14 | from composio.utils.safe_path import ( |
| 15 | MAX_COMPONENT_LENGTH, |
| 16 | SAFE_COMPONENT_REGEX, |
| 17 | assert_safe_path_component, |
| 18 | is_inside_dir, |
| 19 | resolve_root, |
| 20 | safe_basename, |
| 21 | secure_basename_join, |
| 22 | secure_join, |
| 23 | ) |
| 24 | |
| 25 | |
| 26 | class TestResolveRoot: |
| 27 | """Both ends of a containment check must normalize through this one |
| 28 | function; when they diverge the check compares mismatched paths.""" |
| 29 | |
| 30 | def test_expands_tilde(self, tmp_path, monkeypatch): |
| 31 | monkeypatch.setenv("HOME", str(tmp_path)) |
| 32 | assert resolve_root("~/downloads") == (tmp_path / "downloads").resolve() |
| 33 | |
| 34 | def test_resolves_relative(self, tmp_path, monkeypatch): |
| 35 | monkeypatch.chdir(tmp_path) |
| 36 | assert resolve_root("./downloads") == (tmp_path / "downloads").resolve() |
| 37 | |
| 38 | def test_accepts_path_and_str_identically(self, tmp_path): |
| 39 | assert resolve_root(tmp_path) == resolve_root(str(tmp_path)) |
| 40 | |
| 41 | def test_nonexistent_root_does_not_raise(self, tmp_path): |
| 42 | assert resolve_root(tmp_path / "nope") == (tmp_path / "nope").resolve() |
| 43 | |
| 44 | |
| 45 | class TestAssertSafePathComponent: |
| 46 | @pytest.mark.parametrize( |
| 47 | "value", |
| 48 | [ |
| 49 | "GMAIL", |
| 50 | "GMAIL_GET_ATTACHMENT", |
| 51 | "github", |
| 52 | "some-toolkit", |
| 53 | "v2", |
| 54 | "a", |
| 55 | "A1_b-2", |
| 56 | ], |
| 57 | ) |
| 58 | def test_accepts_realistic_slugs(self, value): |
| 59 | assert assert_safe_path_component(value) == value |
| 60 | |
| 61 | @pytest.mark.parametrize( |
| 62 | "value", |
| 63 | [ |
| 64 | "..", |
| 65 | ".", |
| 66 | "../etc", |
| 67 | "../../../../../etc/escaped", |
| 68 | "a/b", |
| 69 | "a\\b", |
| 70 | "..\\..\\evil", |
| 71 | "/etc", |
| 72 | "/", |
| 73 | "C:\\Windows", |
| 74 | "C:/Windows", |
| 75 | "", |
| 76 | "a\x00b", |
| 77 | "a b", |
| 78 | "a.b", |
| 79 | "café", |
| 80 | "x" * 129, |
| 81 | ], |
| 82 | ) |
| 83 | def test_rejects_unsafe_values(self, value): |
| 84 | with pytest.raises(UnsafePathComponentError): |
| 85 | assert_safe_path_component(value) |
| 86 | |
| 87 | @pytest.mark.parametrize("value", ["GMAIL\n", "GMAIL\r\n", "GMAIL\x0b", "\nGMAIL"]) |
| 88 | def test_rejects_control_characters(self, value): |
| 89 | """`re.match` with a `$` anchor also matches just before a single |
| 90 | trailing newline, so `"GMAIL\\n"` satisfied the pattern and reached the |
| 91 | filesystem. `fullmatch` is what closes that.""" |
| 92 | with pytest.raises(UnsafePathComponentError): |
| 93 | assert_safe_path_component(value) |
| 94 | |
| 95 | @pytest.mark.parametrize("value", ["CON", "con", "NUL", "COM1", "lpt9", "AUX"]) |
| 96 | def test_rejects_windows_device_names_on_every_platform(self, value): |
| 97 | """Rejected regardless of host OS so a POSIX test run cannot pass code |
| 98 | that would target a device on a Windows deployment.""" |
| 99 | with pytest.raises(UnsafePathComponentError, match="reserved device name"): |
| 100 | assert_safe_path_component(value) |
| 101 | |
| 102 | def test_rejects_non_string(self): |
| 103 | with pytest.raises(UnsafePathComponentError): |
| 104 | assert_safe_path_component(None) # type: ignore[arg-type] |
| 105 | |
| 106 | def test_label_appears_in_the_error(self): |
| 107 | with pytest.raises(UnsafePathComponentError, match="tool slug"): |
| 108 | assert_safe_path_component("../x", label="tool slug") |
| 109 | |
| 110 | def test_boundary_length(self): |
| 111 | assert assert_safe_path_component("x" * 128) == "x" * 128 |
| 112 | with pytest.raises(UnsafePathComponentError, match="longer than"): |
| 113 | assert_safe_path_component("x" * 129) |
| 114 | |
| 115 | def test_matches_the_custom_tool_slug_pattern(self): |
| 116 | """The SDK already enforced this pattern on client-created custom |
| 117 | tools; backend-fetched tools are now held to the same standard.""" |
| 118 | from composio.core.models.custom_tool_types import SLUG_REGEX |
| 119 | |
| 120 | assert SAFE_COMPONENT_REGEX.pattern == SLUG_REGEX.pattern |
| 121 | |
| 122 | |
| 123 | class TestIsInsideDir: |
| 124 | def test_nested_path_is_inside(self, tmp_path): |
| 125 | assert is_inside_dir(tmp_path / "a" / "b", tmp_path) |
| 126 | |
| 127 | def test_same_path_is_inside(self, tmp_path): |
| 128 | assert is_inside_dir(tmp_path, tmp_path) |
| 129 | |
| 130 | def test_sibling_prefix_is_not_inside(self, tmp_path): |
| 131 | """`/tmp/foo` must not be treated as containing `/tmp/foo-bar`. A plain |
| 132 | string prefix check gets this wrong.""" |
| 133 | assert not is_inside_dir(Path(f"{tmp_path}-evil") / "x", tmp_path) |
| 134 | |
| 135 | def test_parent_is_not_inside(self, tmp_path): |
| 136 | assert not is_inside_dir(tmp_path.parent, tmp_path) |
| 137 | |
| 138 | @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only casing rule") |
| 139 | def test_case_insensitive_on_windows(self): |
| 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"), |
| 156 | [ |
| 157 | ("report.pdf", "report.pdf"), |
| 158 | ("output/report.pdf", "report.pdf"), |
| 159 | ("archive.tar.gz", "archive.tar.gz"), |
| 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"), |
| 168 | ("\u0085report.txt\u0085", "report.txt"), |
| 169 | ], |
| 170 | ) |
| 171 | def test_reduces_to_the_basename(self, value, expected): |
| 172 | assert safe_basename(value) == expected |
| 173 | |
| 174 | @pytest.mark.parametrize("value", ["", ".", "..", "...", "foo/..", "/", " "]) |
| 175 | def test_rejects_names_with_no_usable_basename(self, value): |
| 176 | with pytest.raises(UnsafePathComponentError, match="no usable basename"): |
| 177 | safe_basename(value) |
| 178 | |
| 179 | @pytest.mark.parametrize( |
| 180 | "value", |
| 181 | ["\u00a0.\u00a0", ".\u00a0", "\u00a0.", "\u2007..\u2007", "\u2028.\u2029"], |
| 182 | ) |
| 183 | def test_rejects_whitespace_wrapped_dot_runs(self, value): |
| 184 | """``str.strip`` removes Unicode whitespace, so these are written as |
| 185 | ``.`` or ``..``: the usability check must see the stripped value.""" |
| 186 | with pytest.raises(UnsafePathComponentError, match="no usable basename"): |
| 187 | safe_basename(value) |
| 188 | |
| 189 | @pytest.mark.parametrize("value", [". .", ".. ", " . . "]) |
| 190 | def test_rejects_dot_runs_once_windows_trims_them(self, value): |
| 191 | with pytest.raises(UnsafePathComponentError, match="no usable basename"): |
| 192 | safe_basename(value) |
| 193 | |
| 194 | def test_rejects_nul_byte(self): |
| 195 | with pytest.raises(UnsafePathComponentError, match="NUL byte"): |
| 196 | safe_basename("report\x00.pdf") |
| 197 | |
| 198 | @pytest.mark.parametrize( |
| 199 | ("value", "stem", "extension"), |
| 200 | [ |
| 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 | ) |
| 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( |
| 215 | ("value", "stem", "extension"), |
| 216 | [ |
| 217 | ("report.txt.", "report", ".txt"), |
| 218 | ("report. .", "report", ""), |
| 219 | ("report.\u00a0", "report", ""), |
| 220 | ("report.\u0085", "report", ""), |
| 221 | ("\ufeff..", "\ufeff", ""), |
| 222 | ], |
| 223 | ) |
| 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( |
| 228 | ("value", "stem", "extension"), |
| 229 | [ |
| 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 | ) |
| 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. |
| 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): |
| 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") |
| 268 | assert tagged("請" * 35, ".pdf").fullmatch(cjk) |
| 269 | assert len(cjk.encode()) <= MAX_COMPONENT_LENGTH |
| 270 | assert tagged("😀" * 27).fullmatch(safe_basename("😀" * 33)) |
| 271 | |
| 272 | def test_truncates_an_over_long_extension_with_the_rest(self): |
| 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 |
| 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"): |
| 316 | safe_basename("report-\ud800.txt") |
| 317 | |
| 318 | |
| 319 | class TestSecureBasenameJoin: |
| 320 | def test_tilde_base_is_expanded_before_containment(self, tmp_path, monkeypatch): |
| 321 | monkeypatch.setenv("HOME", str(tmp_path)) |
| 322 | assert ( |
| 323 | secure_basename_join("~/downloads", "report.pdf") |
| 324 | == (tmp_path / "downloads" / "report.pdf").resolve() |
| 325 | ) |
| 326 | |
| 327 | |
| 328 | class TestSecureJoin: |
| 329 | def test_joins_safe_components(self, tmp_path): |
| 330 | assert ( |
| 331 | secure_join(tmp_path, "GMAIL", "GMAIL_GET_ATTACHMENT") |
| 332 | == (tmp_path / "GMAIL" / "GMAIL_GET_ATTACHMENT").resolve() |
| 333 | ) |
| 334 | |
| 335 | def test_no_components_returns_the_root(self, tmp_path): |
| 336 | assert secure_join(tmp_path) == tmp_path.resolve() |
| 337 | |
| 338 | @pytest.mark.parametrize("component", ["..", "../etc", "/etc", "a/b", "..\\evil"]) |
| 339 | def test_rejects_traversal_components(self, component, tmp_path): |
| 340 | with pytest.raises(UnsafePathComponentError): |
| 341 | secure_join(tmp_path, component) |
| 342 | |
| 343 | def test_rejects_traversal_in_any_position(self, tmp_path): |
| 344 | with pytest.raises(UnsafePathComponentError): |
| 345 | secure_join(tmp_path, "GMAIL", "..") |
| 346 | |
| 347 | def test_creates_nothing_on_disk(self, tmp_path): |
| 348 | """Validation must complete before any filesystem write, so a rejected |
| 349 | join leaves no attacker-chosen directories behind.""" |
| 350 | root = tmp_path / "root" |
| 351 | root.mkdir() |
| 352 | with pytest.raises(UnsafePathComponentError): |
| 353 | secure_join(root, "../evil") |
| 354 | assert list(root.iterdir()) == [] |
| 355 | |
| 356 | secure_join(root, "GMAIL", "TOOL") |
| 357 | assert list(root.iterdir()) == [] |
| 358 | |
| 359 | def test_symlink_escape_is_caught_after_resolve(self, tmp_path): |
| 360 | """Per-component validation cannot see a symlink pointing out of the |
| 361 | root; the post-resolve containment check is what catches it.""" |
| 362 | root = tmp_path / "root" |
| 363 | root.mkdir() |
| 364 | outside = tmp_path / "outside" |
| 365 | outside.mkdir() |
| 366 | (root / "GMAIL").symlink_to(outside, target_is_directory=True) |
| 367 | |
| 368 | with pytest.raises(UnsafePathComponentError, match="outside"): |
| 369 | secure_join(root, "GMAIL", "TOOL") |
| 370 | |
| 371 | def test_root_is_expanded_and_resolved(self, tmp_path): |
| 372 | nested = tmp_path / "a" / ".." / "b" |
| 373 | (tmp_path / "b").mkdir(parents=True) |
| 374 | assert secure_join(nested, "TOOL") == (tmp_path / "b" / "TOOL").resolve() |
| 375 | |
| 376 | def test_accepts_str_root(self, tmp_path): |
| 377 | assert secure_join(str(tmp_path), "TOOL") == (tmp_path / "TOOL").resolve() |
| 378 | |
| 379 | def test_tilde_root_is_expanded(self, tmp_path, monkeypatch): |
| 380 | """`~` must expand identically here and in every containment check that |
| 381 | shares this root, or a legitimate download is rejected as an attack.""" |
| 382 | monkeypatch.setenv("HOME", str(tmp_path)) |
| 383 | assert ( |
| 384 | secure_join("~/downloads", "GMAIL") |
| 385 | == (tmp_path / "downloads" / "GMAIL").resolve() |
| 386 | ) |
| 387 | |
| 388 | def test_nonexistent_root_still_validates(self, tmp_path): |
| 389 | """`resolve(strict=False)` means the root need not exist yet — the |
| 390 | download directory is created lazily.""" |
| 391 | root = tmp_path / "not-created-yet" |
| 392 | assert secure_join(root, "TOOL") == (root / "TOOL").resolve() |
| 393 | with pytest.raises(UnsafePathComponentError): |
| 394 | secure_join(root, "..") |