@devries-cameron20 / composio Mirror · read-only / commits / f67d56574
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, 16:00 UTC

refactor(python): consolidate path construction from untrusted input (#4144)

This PR: - centralizes filesystem path construction for API-provided slugs and filenames in `composio.utils.safe_path` - rejects traversal, Windows-invalid names, invalid Unicode, and overlong encoded filenames before creating directories or writing files - normalizes trusted roots consistently and routes both Python download paths through the shared helpers - adds a fail-closed AST guard for new dynamic path construction, including direct `Path(...)` calls - isolates provider initialization from the real home directory and makes the home-write guard report changes without deleting them - removes the obsolete download filename wrapper ## Verification - `pytest -q`: 1,248 passed, 47 skipped - repository-configured Ruff checks and formatting passed for every changed Python file - targeted mypy checks passed for the changed helpers and tests

Alberto Schiabel committed Aug 18, 2026 at 13:07 UTC f67d565743c180ab7f33c1e9921ca5a6bb12972e
13 files changed +1440 -78
python/AGENTS.md
+25
@@ -40,3 +40,28 @@ make build
40 - Add pytest coverage for behavior changes.
41 - Keep provider-specific changes under the relevant `python/providers/<provider>/` package.
42 - When bumping `composio-client`, update `python/pyproject.toml`, `python/setup.py`, and root `uv.lock` together.
43 +
44 +## Trust boundary
45 +
46 +**Every field of an API response is untrusted input** — including slugs, IDs, and
47 +filenames. The SDK's threat model assumes the backend may be compromised or the
48 +connection MITM'd, and that a third-party toolkit can return anything.
49 +
50 +When untrusted directory components such as slugs or IDs become part of a
51 +filesystem path, use
52 +`composio.utils.safe_path.secure_join(root, *components)`. For an untrusted
53 +filename, use `secure_basename_join(base, filename, root=root)` so ordinary
54 +extensions remain valid while the write stays anchored to the trusted root.
55 +Both helpers enforce two rules:
56 +
57 +1. **Anchor containment on a constant.** Checking a derived path against a
58 + directory that untrusted input helped build compares tainted against tainted
59 + and always passes. A directory built as `root / untrusted_a / untrusted_b`
60 + and then validated against that same built directory is checked against a
61 + reference the input was free to move.
62 +2. **Validate before touching the filesystem.** No `mkdir` or `open` until the
63 + final path is known to be inside the root, so a rejected write leaves no
64 + attacker-chosen directories behind.
65 +
66 +`tests/test_path_join_guardrail.py` enforces this: any path join whose right-hand
67 +side is not a literal or module constant must be listed there with a reason.
python/composio/core/models/_files.py
+34 -14
@@ -22,9 +22,11 @@ from composio.exceptions import (
22 FileUploadAbortedError,
23 ResponseTooLargeError,
24 SDKFileNotFoundError,
25 + UnsafePathComponentError,
26 )
27 from composio.utils import mimetypes
28 from composio.utils.json_schema import dereference_json_schema
29 +from composio.utils.safe_path import secure_basename_join, secure_join
30 from composio.utils.url_safety import assert_safe_fetch_target
31 from composio.utils.sensitive_file_upload_paths import (
32 assert_safe_local_file_upload_path,
@@ -580,19 +582,31 @@ class FileDownloadable(BaseModel):
582 mimetype: str = Field(..., description="Mime type of the file.")
583 s3url: str = Field(..., description="URL of the file.")
584
583 - def download(self, outdir: Path, chunk_size: int = _DEFAULT_CHUNK_SIZE) -> Path:
584 - # SEC-316: `self.name` comes from the (potentially compromised or
585 - # MITM'd) Composio API response. Strip directory components with
586 - # `Path(...).name` so traversal sequences like `../../../foo` collapse
587 - # to `foo`, then verify the resolved output stays under `outdir` so a
588 - # name like `output_evil/foo` (sibling-prefix attack) is also rejected.
589 - safe_name = Path(self.name).name
590 - outfile = outdir / safe_name
591 - if not outfile.resolve().is_relative_to(outdir.resolve()):
592 - raise ErrorDownloadingFile(
593 - f"Path traversal detected: filename '{self.name}' resolves "
594 - "outside the intended output directory."
595 - )
585 + def download(
586 + self,
587 + outdir: Path,
588 + chunk_size: int = _DEFAULT_CHUNK_SIZE,
589 + *,
590 + root: Path,
591 + ) -> Path:
592 + """Fetch the file into ``outdir``.
593 +
594 + :param outdir: Directory to write into. May be derived from untrusted
595 + input, provided it was produced by :func:`secure_join`.
596 + :param root: Trusted containment anchor, configured locally and never
597 + derived from an API response. Required rather than defaulted:
598 + checking containment against a directory that untrusted input has
599 + already relocated is not a check at all, and ``outdir`` may be
600 + exactly such a directory. Callers must name the anchor explicitly.
601 + """
602 + # SEC-316: `self.name` also comes from the (potentially compromised or
603 + # MITM'd) API response. Collapsed to a bare filename and checked against
604 + # `root` — not `outdir` — so a name like `output_evil/foo`
605 + # (sibling-prefix attack) is rejected too.
606 + try:
607 + outfile = secure_basename_join(outdir, self.name, root=root)
608 + except UnsafePathComponentError as e:
609 + raise ErrorDownloadingFile(str(e)) from e
610 outdir.mkdir(exist_ok=True, parents=True)
611 try:
612 response = requests.get(
@@ -1085,9 +1099,15 @@ class FileHelper(WithLogger):
1099
1100 def _download_file_value(self, value: t.Any, tool: Tool) -> t.Any:
1101 if isinstance(value, dict) and "s3url" in value:
1102 + # `tool.toolkit.slug` and `tool.slug` come from the API response and
1103 + # are untrusted, so joining them directly would let the response pick
1104 + # the download directory. `secure_join` validates each component and
1105 + # anchors containment on `self._outdir`, which is configured locally
1106 + # and never derived from the response.
1107 return str(
1108 FileDownloadable(**value).download(
1090 - self._outdir / tool.toolkit.slug / tool.slug
1109 + outdir=secure_join(self._outdir, tool.toolkit.slug, tool.slug),
1110 + root=self._outdir,
1111 )
1112 )
1113 return value
python/composio/core/models/custom_tool_types.py
+11 -2
@@ -5,7 +5,6 @@ Mirrors the TypeScript types in ts/packages/core/src/types/customTool.types.ts
5
6 from __future__ import annotations
7
8 -import re
8 import typing as t
9 from dataclasses import dataclass, field
10
@@ -20,13 +19,23 @@ from composio_client.types.tool_router.session_proxy_execute_response import (
19 SessionProxyExecuteResponse,
20 )
21
22 +from composio.utils.safe_path import SAFE_COMPONENT_REGEX
23 +
24 # ────────────────────────────────────────────────────────────────
25 # Constants
26 # ────────────────────────────────────────────────────────────────
27
28 LOCAL_TOOL_PREFIX = "LOCAL_"
29 MAX_SLUG_LENGTH = 60
29 -SLUG_REGEX = re.compile(r"^[A-Za-z0-9_-]+$")
30 +
31 +SLUG_REGEX = SAFE_COMPONENT_REGEX
32 +"""Alias of the canonical pattern in :mod:`composio.utils.safe_path`.
33 +
34 +One definition, not two kept in sync by hand: this pattern is what makes a slug
35 +safe to use as a filesystem path component, so client-created custom tools and
36 +backend-fetched tools must be held to exactly the same rule. Keeping two copies
37 +in sync by hand is how they drift apart.
38 +"""
39
40 # ────────────────────────────────────────────────────────────────
41 # Execute function type
python/composio/core/models/tool_router_session_files.py
+32 -13
@@ -6,7 +6,7 @@ in the session's virtual filesystem.
6 from __future__ import annotations
7
8 import typing as t
9 -from pathlib import Path
9 +from pathlib import Path, PureWindowsPath
10 from urllib.parse import unquote, urlparse
11
12 import requests
@@ -22,8 +22,13 @@ from composio_client.types.tool_router.session.file_list_response import (
22 )
23
24 from composio.client import HttpClient
25 -from composio.exceptions import RemoteFileDownloadError, ValidationError
25 +from composio.exceptions import (
26 + RemoteFileDownloadError,
27 + UnsafePathComponentError,
28 + ValidationError,
29 +)
30 from composio.utils.mimetypes import get_extension_from_mime_type
31 +from composio.utils.safe_path import secure_basename_join
32 from composio.utils.url_safety import assert_safe_fetch_target
33 from composio.utils.uuid import generate_short_id
34
@@ -115,8 +120,18 @@ class RemoteFile:
120
121 @property
122 def filename(self) -> str:
118 - """Filename extracted from the mount path (e.g. 'report.pdf' from 'output/report.pdf')."""
119 - return Path(self.mount_relative_path).name
123 + """Filename extracted from the mount path (e.g. 'report.pdf' from 'output/report.pdf').
124 +
125 + Deliberately non-raising: this is a display value, and ``buffer()``
126 + reads it while constructing ``RemoteFileDownloadError``. A validator
127 + here would replace a genuine download error with a validation error
128 + raised from inside the error constructor. ``save()`` validates instead,
129 + at the point the value actually becomes a path.
130 +
131 + ``PureWindowsPath`` so a mount path crafted for a Windows target
132 + (``..\\..\\evil``) is stripped on POSIX too.
133 + """
134 + return PureWindowsPath(self.mount_relative_path).name
135
136 def buffer(self) -> bytes:
137 """Fetch the file content as bytes."""
@@ -160,17 +175,21 @@ class RemoteFile:
175 if path is not None:
176 save_path = Path(path)
177 else:
163 - # SEC-316 defense-in-depth: `self.filename` is `Path(mount_relative_path).name`,
164 - # so directory components are already stripped — but verify the resolved
165 - # default-location path stays inside the cache dir to reject residual `..`
166 - # cases (e.g. ``mount_relative_path == ".."`` keeps ``filename == ".."``).
178 + # SEC-316 defense-in-depth. `safe_basename` collapses the
179 + # server-controlled mount path and rejects what has no usable
180 + # basename — `""` and `"."` previously made `save_path` equal
181 + # `default_dir`, passed the containment check (a path contains
182 + # itself), and failed as a raw `IsADirectoryError` after the
183 + # directory had been created. The containment check stays as a
184 + # second line of defence, anchored on the constant `default_dir`,
185 + # which is what makes it meaningful; see `composio.utils.safe_path`.
186 default_dir = Path.home() / COMPOSIO_DIR / TEMP_FILES_DIRECTORY_NAME
168 - save_path = default_dir / self.filename
169 - if not save_path.resolve().is_relative_to(default_dir.resolve()):
170 - raise ValidationError(
171 - f"Path traversal detected: filename {self.filename!r} resolves "
172 - "outside the intended output directory."
187 + try:
188 + save_path = secure_basename_join(
189 + default_dir, self.mount_relative_path, label="mount path"
190 )
191 + except UnsafePathComponentError as e:
192 + raise ValidationError(str(e)) from e
193
194 save_path.parent.mkdir(parents=True, exist_ok=True)
195 save_path.write_bytes(content)
python/composio/exceptions.py
+10
@@ -210,6 +210,16 @@ class FileUploadAbortedError(FileError):
210 """Raised when a ``before_file_upload`` hook returns ``False``."""
211
212
213 +class UnsafePathComponentError(FileError):
214 + """
215 + Raised when untrusted input (a tool slug, toolkit slug, or server-supplied
216 + filename) cannot be safely used as part of a filesystem path.
217 +
218 + Fails closed: the SDK refuses the write rather than sanitizing the value
219 + into something that merely looks safe.
220 + """
221 +
222 +
223 class ErrorDownloadingFile(FileError):
224 pass
225
python/composio/utils/safe_path.py new
+295
@@ -0,0 +1,295 @@
1 +"""Path containment primitives for untrusted input.
2 +
3 +Every field of an API response is untrusted, including slugs, identifiers, and
4 +filenames. A compromised toolkit or a MITM on the Composio API can set them to
5 +anything. When such a value becomes part of a filesystem path, it must pass
6 +through this module.
7 +
8 +Two rules make the difference between a real check and a decorative one:
9 +
10 +1. **Anchor on a constant.** Containment is only meaningful when the root is a
11 + trusted value. Checking a derived path against a directory that untrusted
12 + input helped build compares tainted against tainted and always passes. A
13 + directory built as ``root / untrusted_a / untrusted_b`` and then validated
14 + against that same built directory is checked against a reference the input
15 + was free to move.
16 +
17 +2. **Validate before touching the filesystem.** No ``mkdir``, no ``open``, until
18 + the final path is known to be inside the root. Otherwise a rejected write
19 + still leaves attacker-chosen directories behind.
20 +
21 +:func:`secure_join` enforces both. Prefer it over hand-rolled
22 +``resolve() / is_relative_to()`` pairs — see ``python/AGENTS.md``.
23 +"""
24 +
25 +from __future__ import annotations
26 +
27 +import os
28 +import re
29 +import sys
30 +import typing as t
31 +from pathlib import Path, PureWindowsPath
32 +
33 +from composio.exceptions import UnsafePathComponentError
34 +
35 +SAFE_COMPONENT_REGEX = re.compile(r"^[A-Za-z0-9_-]+$")
36 +"""Characters permitted in a path component derived from untrusted input.
37 +
38 +Deliberately identical to ``SLUG_REGEX`` in ``custom_tool_types.py``, which the
39 +SDK already enforces on client-created custom tools. Backend-fetched tools were
40 +never held to the same standard; they are now.
41 +
42 +Every one of the 1070 toolkit slugs in the catalog snapshot at
43 +``ts/packages/cli/src/generated/toolkit-slugs.ts`` conforms, so this is not
44 +expected to reject anything legitimate. That snapshot is not the live catalog:
45 +a production slug containing a dot or a non-ASCII character would hard-fail its
46 +downloads rather than degrade.
47 +"""
48 +
49 +MAX_COMPONENT_LENGTH = 128
50 +"""Upper bound on a single component, well under the 255-byte limit common to
51 +ext4/APFS/NTFS. Keeps a long slug from raising ``OSError`` mid-write."""
52 +
53 +WINDOWS_RESERVED_NAMES = frozenset(
54 + {"CON", "PRN", "AUX", "NUL"}
55 + | {f"COM{i}" for i in range(1, 10)}
56 + | {f"LPT{i}" for i in range(1, 10)}
57 + | {f"COM{i}" for i in "¹²³"}
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."""
63 +
64 +
65 +def is_inside_dir(child: Path, parent: Path) -> bool:
66 + """True iff ``child`` equals ``parent`` or is nested inside it on a path
67 + component boundary.
68 +
69 + ``/tmp/foo`` contains ``/tmp/foo/bar`` but NOT ``/tmp/foo-bar`` — a plain
70 + string prefix test gets that wrong. Comparison is case-insensitive on
71 + Windows, where ``C:\\Foo`` and ``c:\\foo`` are the same directory.
72 +
73 + Both arguments are assumed absolute and normalized.
74 + """
75 + try:
76 + child_str = str(child)
77 + parent_str = str(parent)
78 + if sys.platform == "win32":
79 + child_str = child_str.lower()
80 + parent_str = parent_str.lower()
81 + if child_str == parent_str:
82 + return True
83 + sep = os.sep
84 + parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep
85 + return child_str.startswith(parent_with_sep)
86 + except OSError:
87 + return False
88 +
89 +
90 +def assert_safe_path_component(value: str, *, label: str = "path component") -> str:
91 + """Return ``value`` unchanged if it is safe to use as a single path
92 + component, else raise.
93 +
94 + Fails closed. Rejects traversal (``..``), separators of either platform,
95 + absolute paths, drive letters, NUL bytes, reserved device names, and
96 + anything outside :data:`SAFE_COMPONENT_REGEX`.
97 +
98 + :raises UnsafePathComponentError: when ``value`` is unsafe.
99 + """
100 + if not isinstance(value, str) or not value:
101 + raise UnsafePathComponentError(
102 + f"Refusing to build a path from an empty or non-string {label}: {value!r}"
103 + )
104 +
105 + # `PureWindowsPath` treats both `/` and `\` as separators, so a single check
106 + # catches `../x` and `..\x` regardless of the host platform. A slug crafted
107 + # for a Windows target must not slip through on a POSIX build machine.
108 + as_windows_path = PureWindowsPath(value)
109 + if len(as_windows_path.parts) != 1 or as_windows_path.anchor:
110 + raise UnsafePathComponentError(
111 + f"Refusing to build a path from a {label} containing path separators "
112 + f"or a drive letter: {value!r}"
113 + )
114 +
115 + if len(value) > MAX_COMPONENT_LENGTH:
116 + raise UnsafePathComponentError(
117 + f"Refusing to build a path from a {label} longer than "
118 + f"{MAX_COMPONENT_LENGTH} characters: {value[:32]!r}... "
119 + f"({len(value)} characters)"
120 + )
121 +
122 + # `.` and `..` are excluded by the regex (no `.` in the character class),
123 + # as are NUL bytes and every separator. The explicit checks above exist to
124 + # produce a precise error message rather than a generic pattern mismatch.
125 + #
126 + # `fullmatch`, not `match`: in a `match`, `$` also matches just before a
127 + # single trailing newline, so `"GMAIL\n"` would satisfy `^[A-Za-z0-9_-]+$`
128 + # and reach the filesystem with a control character in the name.
129 + if not SAFE_COMPONENT_REGEX.fullmatch(value):
130 + raise UnsafePathComponentError(
131 + f"Refusing to build a path from an unsafe {label}: {value!r}. "
132 + f"Expected only letters, digits, underscores, and hyphens "
133 + f"(pattern {SAFE_COMPONENT_REGEX.pattern})."
134 + )
135 +
136 + if value.upper() in WINDOWS_RESERVED_NAMES:
137 + raise UnsafePathComponentError(
138 + f"Refusing to build a path from a reserved device name as {label}: {value!r}"
139 + )
140 +
141 + return value
142 +
143 +
144 +def safe_basename(name: str, *, label: str = "filename") -> str:
145 + """Collapse an untrusted filename to a bare, writable basename.
146 +
147 + 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.
151 +
152 + ``PureWindowsPath`` treats both ``/`` and ``\\`` as separators, so a name
153 + crafted for a Windows target (``..\\..\\evil``) is stripped even when the
154 + SDK runs on POSIX, where ``Path(...).name`` would return it intact.
155 +
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 + :raises UnsafePathComponentError: when ``name`` yields no usable basename or
163 + is unsafe to write.
164 + """
165 + if not isinstance(name, str):
166 + raise UnsafePathComponentError(
167 + f"Refusing to write a non-string {label}: {name!r}"
168 + )
169 +
170 + raw_basename = PureWindowsPath(name).name
171 + if not raw_basename or not raw_basename.strip() or set(raw_basename) == {"."}:
172 + raise UnsafePathComponentError(
173 + f"Path traversal detected: {label} {name!r} leaves no usable "
174 + "basename to write to."
175 + )
176 + if "\x00" in raw_basename:
177 + raise UnsafePathComponentError(
178 + f"Refusing to write {label} containing a NUL byte: {name!r}"
179 + )
180 + if any(ord(char) < 32 or char in '<>:"|?*' for char in raw_basename):
181 + raise UnsafePathComponentError(
182 + f"Refusing to write {label} containing characters reserved by "
183 + f"Windows: {name!r}"
184 + )
185 + if raw_basename.endswith((" ", ".")):
186 + raise UnsafePathComponentError(
187 + f"Refusing to write {label} ending in a space or dot: {name!r}"
188 + )
189 +
190 + basename = raw_basename.strip()
191 + try:
192 + encoded_length = len(os.fsencode(basename))
193 + except UnicodeEncodeError as e:
194 + raise UnsafePathComponentError(
195 + f"Refusing to write {label} containing invalid Unicode: {name!r}"
196 + ) from e
197 + if encoded_length > MAX_COMPONENT_LENGTH:
198 + raise UnsafePathComponentError(
199 + f"Refusing to write {label} longer than {MAX_COMPONENT_LENGTH} bytes: "
200 + f"{basename[:32]!r}... ({encoded_length} bytes)"
201 + )
202 + # Compare everything before the first dot: on Windows `NUL.tar.gz` opens
203 + # the null device just as `NUL` does, so any number of extensions provides
204 + # no protection.
205 + device_name = basename.split(".", 1)[0].rstrip(" ").upper()
206 + if device_name in WINDOWS_RESERVED_NAMES:
207 + raise UnsafePathComponentError(
208 + f"Refusing to write {label} that is a reserved device name: {name!r}"
209 + )
210 + return basename
211 +
212 +
213 +def resolve_root(root: t.Union[str, Path]) -> Path:
214 + """Normalize a trusted root to an absolute, symlink-resolved path.
215 +
216 + Every containment check must derive its anchor through this one function.
217 + When two call sites normalize differently — one expanding ``~`` and one not
218 + — the check compares mismatched paths and rejects legitimate writes while
219 + reporting them as attacks. Sharing the normalization is what keeps the two
220 + ends of a containment check comparable.
221 + """
222 + expanded = Path(root).expanduser()
223 + try:
224 + return expanded.resolve(strict=False)
225 + except OSError:
226 + return expanded
227 +
228 +
229 +def secure_basename_join(
230 + base: t.Union[str, Path],
231 + name: str,
232 + *,
233 + root: t.Optional[t.Union[str, Path]] = None,
234 + label: str = "filename",
235 +) -> Path:
236 + """Join a single untrusted filename under ``base``, contained within ``root``.
237 +
238 + The filename counterpart to :func:`secure_join`, which cannot be reused here
239 + because it forbids ``.`` — correct for a slug, wrong for ``report.pdf``.
240 +
241 + ``root`` defaults to ``base`` but is separate for the download path, where
242 + ``base`` is a per-tool subdirectory that untrusted slugs helped build and
243 + only the configured ``root`` above it is trusted. Anchoring on ``base``
244 + there would check the result against a directory those slugs had moved.
245 +
246 + :raises UnsafePathComponentError: when ``name`` is unsafe, or when the
247 + result escapes ``root``.
248 + """
249 + resolved_base = resolve_root(base)
250 + resolved_root = resolved_base if root is None else resolve_root(root)
251 + candidate = resolved_base / safe_basename(name, label=label)
252 + if not is_inside_dir(candidate.resolve(), resolved_root):
253 + raise UnsafePathComponentError(
254 + f"Path traversal detected: {label} {name!r} resolves to "
255 + f"{candidate.resolve()}, which is outside {resolved_root}."
256 + )
257 + return candidate
258 +
259 +
260 +def secure_join(root: t.Union[str, Path], *components: str) -> Path:
261 + """Join untrusted ``components`` beneath the trusted ``root``.
262 +
263 + ``root`` is the sole anchor of trust and must not itself be derived from
264 + untrusted input — that is the whole point. Each component is validated by
265 + :func:`assert_safe_path_component`, then the joined result is resolved and
266 + re-checked against the resolved root. The second check is belt-and-braces:
267 + it catches a symlink inside ``root`` pointing outside it, which per-component
268 + validation cannot see.
269 +
270 + Performs no filesystem writes; the caller creates directories only after
271 + this returns.
272 +
273 + :raises UnsafePathComponentError: when any component is unsafe, or when the
274 + joined path escapes ``root``.
275 + """
276 + resolved_root = resolve_root(root)
277 +
278 + safe_components = [
279 + assert_safe_path_component(component) for component in components
280 + ]
281 +
282 + candidate = resolved_root.joinpath(*safe_components)
283 + try:
284 + resolved_candidate = candidate.resolve(strict=False)
285 + except OSError:
286 + resolved_candidate = candidate
287 +
288 + if not is_inside_dir(resolved_candidate, resolved_root):
289 + raise UnsafePathComponentError(
290 + f"Refusing to write outside the configured directory: "
291 + f"{components!r} resolves to {resolved_candidate}, "
292 + f"which is outside {resolved_root}."
293 + )
294 +
295 + return resolved_candidate
python/composio/utils/upload_dir_allowlist.py
+3 -28
@@ -24,6 +24,7 @@ from composio.exceptions import (
24 FileUploadPathNotAllowedError,
25 SDKFileNotFoundError,
26 )
27 +from composio.utils.safe_path import is_inside_dir, resolve_root
28
29 UPLOAD_TEMP_DIRECTORY_NAME = "temp"
30
@@ -96,24 +97,6 @@ def resolve_effective_upload_allowlist(
97 return out
98
99
99 -def _is_inside_dir(child: Path, parent: Path) -> bool:
100 - """True iff ``child`` equals ``parent`` or is nested inside on a component
101 - boundary. Assumes both are absolute and normalized."""
102 - try:
103 - child_str = str(child)
104 - parent_str = str(parent)
105 - if sys.platform == "win32":
106 - child_str = child_str.lower()
107 - parent_str = parent_str.lower()
108 - if child_str == parent_str:
109 - return True
110 - sep = os.sep
111 - parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep
112 - return child_str.startswith(parent_with_sep)
113 - except OSError:
114 - return False
115 -
116 -
100 def _format_allowlist(dirs: t.Sequence[Path]) -> str:
101 if not dirs:
102 return " (none configured — all local paths are blocked)"
@@ -164,11 +147,7 @@ def assert_path_inside_upload_dirs(
147 entry of ``allowlist`` (including when allowlist is empty).
148 """
149 attempted = str(file_path)
167 - abs_path = Path(attempted).expanduser()
168 - try:
169 - abs_path = abs_path.resolve(strict=False)
170 - except OSError:
171 - pass
150 + abs_path = resolve_root(attempted)
151
152 if not abs_path.exists():
153 cwd = Path.cwd()
@@ -218,11 +197,7 @@ def assert_path_inside_upload_dirs(
197 )
198
199 for dir_entry in allowlist:
221 - try:
222 - real_dir = Path(dir_entry).expanduser().resolve(strict=False)
223 - except OSError:
224 - real_dir = Path(dir_entry)
225 - if _is_inside_dir(real_path, real_dir):
200 + if is_inside_dir(real_path, resolve_root(dir_entry)):
201 return
202
203 raise FileUploadPathNotAllowedError(
python/tests/conftest.py
+56
@@ -4,6 +4,7 @@ import base64
4 import hashlib
5 import hmac
6 import json
7 +import os
8 from pathlib import Path
9 from unittest.mock import Mock
10
@@ -120,3 +121,58 @@ def webhook_fixtures() -> list[dict]:
121 def golden_signatures() -> dict:
122 """Load golden signatures."""
123 return load_golden_signatures()
124 +
125 +
126 +@pytest.fixture(scope="session")
127 +def _real_home_baseline():
128 + """The real home directory and its top-level entries, captured once.
129 +
130 + Session-scoped so it is read before any test can monkeypatch ``$HOME``.
131 + Resolving it per-test would let a test that repoints ``$HOME`` also move
132 + the guard's own reference point, which is exactly the class of mistake the
133 + guard exists to catch.
134 + """
135 + real_home = Path(os.path.expanduser("~"))
136 + try:
137 + return {"path": real_home, "entries": set(os.listdir(real_home))}
138 + except OSError:
139 + return {"path": real_home, "entries": None}
140 +
141 +
142 +@pytest.fixture(autouse=True)
143 +def guard_real_home_directory(request, _real_home_baseline):
144 + """Fail any test that creates entries directly in the real home directory.
145 +
146 + A test that meant to sandbox `~` but patched the wrong thing
147 + (`Path.home` does not affect `Path.expanduser`, which reads `$HOME`)
148 + silently writes into the developer's actual home instead. That has already
149 + destroyed real user data once. This turns the silent case into a failure.
150 +
151 + Only top-level entries are compared, so a test writing under an existing
152 + `~/.composio` is unaffected; creating `~/downloads` is not.
153 + """
154 + if _real_home_baseline["entries"] is None:
155 + yield
156 + return
157 +
158 + yield
159 +
160 + real_home = _real_home_baseline["path"]
161 + try:
162 + after = set(os.listdir(real_home))
163 + except OSError:
164 + return
165 +
166 + created = after - _real_home_baseline["entries"]
167 + # Roll the baseline forward before failing, so one offending test does not
168 + # then fail every test that follows it.
169 + _real_home_baseline["entries"] = after
170 + if not created:
171 + return
172 +
173 + pytest.fail(
174 + f"{request.node.nodeid} created {sorted(created)} in the real home "
175 + f"directory ({real_home}). Sandbox `$HOME` with "
176 + f"`monkeypatch.setenv('HOME', str(tmp_path))` — patching `Path.home` "
177 + f"does not affect `Path.expanduser`."
178 + )
python/tests/test_files.py
+206 -21
@@ -31,6 +31,7 @@ from composio.exceptions import (
31 ErrorUploadingFile,
32 ResponseTooLargeError,
33 SensitiveFilePathBlockedError,
34 + UnsafePathComponentError,
35 )
36
37
@@ -2546,7 +2547,7 @@ class TestFileDownloadablePathTraversal:
2547 "composio.core.models._files.requests.get",
2548 return_value=self._mock_response(b"#!/bin/sh\n"),
2549 ):
2549 - written = f.download(outdir)
2550 + written = f.download(outdir, root=outdir)
2551
2552 # Traversal sequence collapsed to basename and stayed inside outdir.
2553 assert written == outdir / "PWNED.sh"
@@ -2565,7 +2566,7 @@ class TestFileDownloadablePathTraversal:
2566 "composio.core.models._files.requests.get",
2567 return_value=self._mock_response(b"x"),
2568 ):
2568 - written = f.download(outdir)
2569 + written = f.download(outdir, root=outdir)
2570
2571 # `Path('/etc/passwd').name == 'passwd'` — absolute path is stripped.
2572 assert written == outdir / "passwd"
@@ -2587,7 +2588,7 @@ class TestFileDownloadablePathTraversal:
2588 return_value=self._mock_response(),
2589 ):
2590 with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):
2590 - f.download(outdir)
2591 + f.download(outdir, root=outdir)
2592 # No file was written under the parent.
2593 assert not (tmp_path / "x").exists()
2594
@@ -2602,7 +2603,7 @@ class TestFileDownloadablePathTraversal:
2603 "composio.core.models._files.requests.get",
2604 return_value=self._mock_response(b"%PDF-1.4"),
2605 ):
2605 - written = f.download(outdir)
2606 + written = f.download(outdir, root=outdir)
2607
2608 assert written == outdir / "report.pdf"
2609 assert written.read_bytes() == b"%PDF-1.4"
@@ -2618,7 +2619,7 @@ class TestFileDownloadablePathTraversal:
2619 "composio.core.models._files.requests.get",
2620 return_value=self._mock_response(b"%PDF-1.4"),
2621 ) as mock_get:
2621 - f.download(outdir)
2622 + f.download(outdir, root=outdir)
2623
2624 mock_get.assert_called_once_with(
2625 url="https://example.com/file",
@@ -2640,7 +2641,7 @@ class TestFileDownloadablePathTraversal:
2641 ),
2642 ):
2643 with pytest.raises(ErrorDownloadingFile) as exc_info:
2643 - f.download(outdir)
2644 + f.download(outdir, root=outdir)
2645
2646 assert "Error downloading file" in str(exc_info.value)
2647 assert "token=abc" not in str(exc_info.value)
@@ -2663,7 +2664,7 @@ class TestFileDownloadablePathTraversal:
2664 return_value=response,
2665 ):
2666 with pytest.raises(ErrorDownloadingFile) as exc_info:
2666 - f.download(outdir)
2667 + f.download(outdir, root=outdir)
2668
2669 assert "Error downloading file" in str(exc_info.value)
2670 assert "token=abc" not in str(exc_info.value)
@@ -2683,7 +2684,7 @@ class TestFileDownloadablePathTraversal:
2684 return_value=response,
2685 ):
2686 with pytest.raises(ErrorDownloadingFile) as exc_info:
2686 - f.download(outdir)
2687 + f.download(outdir, root=outdir)
2688
2689 assert "token=abc" not in str(exc_info.value)
2690 response.close.assert_called_once()
@@ -2707,20 +2708,25 @@ class TestFileDownloadablePathTraversal:
2708 return_value=self._mock_response(),
2709 ):
2710 with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):
2710 - f.download(outdir)
2711 + f.download(outdir, root=outdir)
2712 # SEC-316 P3.1: check runs before mkdir, so outdir is not created
2713 # as a side effect of a rejected payload.
2714 assert not outdir.exists()
2715
2715 - def test_empty_name_safe_fails_at_write_time(self, tmp_path):
2716 - """`Path('').name == ''` — `outdir / ''` resolves to `outdir` itself,
2717 - which passes the containment check (a path is relative to itself).
2718 - The write then fails with `IsADirectoryError` because the target is
2719 - the directory. Documents the safe-fail behavior so a future change
2720 - to the check cannot silently weaken it without breaking this test."""
2716 + @pytest.mark.parametrize("name", ["", "."])
2717 + def test_name_without_usable_basename_is_rejected(self, name, tmp_path):
2718 + """`Path('').name` and `Path('.').name` are both `''`, so `outdir / ''`
2719 + used to resolve to `outdir` itself, pass the containment check (a path
2720 + is relative to itself), and only fail at write time with a raw
2721 + `IsADirectoryError` after the directory had been created.
2722 +
2723 + These are now refused up front. Documents the fail-closed behavior so a
2724 + future change cannot silently weaken it without breaking this test."""
2725 + from composio.exceptions import ErrorDownloadingFile
2726 +
2727 outdir = tmp_path / "safe"
2728 f = FileDownloadable(
2723 - name="",
2729 + name=name,
2730 mimetype="application/octet-stream",
2731 s3url="https://example.com/file",
2732 )
@@ -2728,13 +2734,192 @@ class TestFileDownloadablePathTraversal:
2734 "composio.core.models._files.requests.get",
2735 return_value=self._mock_response(b"x"),
2736 ):
2731 - with pytest.raises(IsADirectoryError):
2732 - f.download(outdir)
2733 - # outdir got created (mkdir runs after the check, which passed),
2734 - # but no file was written inside it.
2735 - assert outdir.is_dir()
2737 + with pytest.raises(ErrorDownloadingFile, match="no usable basename"):
2738 + f.download(outdir, root=outdir)
2739 +
2740 + # Rejected before `mkdir`, so nothing was created on disk at all.
2741 + assert not outdir.exists()
2742 +
2743 + @pytest.mark.parametrize(
2744 + "name,reason",
2745 + [
2746 + ("NUL", "reserved device name"),
2747 + ("nul.txt", "reserved device name"),
2748 + ("NUL.tar.gz", "reserved device name"),
2749 + ("COM1", "reserved device name"),
2750 + ("report.txt:payload", "reserved by Windows"),
2751 + ("a\x00b", "NUL byte"),
2752 + ("😀" * 128, "longer than"),
2753 + ("x" * 300, "longer than"),
2754 + ],
2755 + )
2756 + def test_unsafe_filenames_are_rejected(self, name, reason, tmp_path):
2757 + """`self.name` is untrusted by the same rule as the slugs. Without these
2758 + checks a NUL byte escapes as a raw ValueError from `resolve()`, an
2759 + over-long name as a raw OSError mid-write, and `NUL` opens the Windows
2760 + null device — silently discarding the payload while returning a path."""
2761 + from composio.exceptions import ErrorDownloadingFile
2762 +
2763 + outdir = tmp_path / "safe"
2764 + f = FileDownloadable(
2765 + name=name,
2766 + mimetype="application/octet-stream",
2767 + s3url="https://example.com/file",
2768 + )
2769 + with patch(
2770 + "composio.core.models._files.requests.get",
2771 + return_value=self._mock_response(b"x"),
2772 + ):
2773 + with pytest.raises(ErrorDownloadingFile, match=reason):
2774 + f.download(outdir, root=outdir)
2775 + assert not outdir.exists()
2776 +
2777 +
2778 +class TestDownloadDirSlugTraversal:
2779 + """Server-controlled tool/toolkit slugs must not relocate the download
2780 + directory.
2781 +
2782 + The directory is built from API response fields, so containment has to be
2783 + checked against the locally configured root rather than against the built
2784 + directory itself — the latter is a reference those fields can move. These
2785 + tests pin the anchor to the configured root.
2786 + """
2787 +
2788 + TRAVERSALS = [
2789 + "../../../../../etc/escaped",
2790 + "..",
2791 + ".",
2792 + "",
2793 + "/etc",
2794 + "..\\..\\evil",
2795 + "a/b",
2796 + "CON",
2797 + "x" * 200,
2798 + "a\x00b",
2799 + ]
2800 +
2801 + def _tool(self, tool_slug="GMAIL_GET_ATTACHMENT", toolkit_slug="GMAIL"):
2802 + tool = MagicMock()
2803 + tool.slug = tool_slug
2804 + tool.toolkit.slug = toolkit_slug
2805 + tool.output_parameters = {
2806 + "type": "object",
2807 + "properties": {"attachment": {"file_downloadable": True}},
2808 + }
2809 + return tool
2810 +
2811 + def _response(self):
2812 + return {
2813 + "attachment": {
2814 + "name": "composio",
2815 + "mimetype": "text/plain",
2816 + "s3url": "https://example.com/file",
2817 + }
2818 + }
2819 +
2820 + def _mock_get(self, content: bytes = b"payload"):
2821 + response = MagicMock()
2822 + response.status_code = 200
2823 + response.iter_content = lambda chunk_size: [content]
2824 + response.close = MagicMock()
2825 + return patch("composio.core.models._files.requests.get", return_value=response)
2826 +
2827 + @pytest.mark.parametrize("slug", TRAVERSALS)
2828 + def test_hostile_tool_slug_is_rejected(self, slug, tmp_path):
2829 + outdir = tmp_path / "files"
2830 + outdir.mkdir()
2831 + helper = FileHelper(client=None, outdir=str(outdir))
2832 + with self._mock_get():
2833 + with pytest.raises(UnsafePathComponentError):
2834 + helper.substitute_file_downloads(
2835 + tool=self._tool(tool_slug=slug), response=self._response()
2836 + )
2837 + # The write is refused before any directory is created.
2838 assert list(outdir.iterdir()) == []
2839
2840 + @pytest.mark.parametrize("slug", TRAVERSALS)
2841 + def test_hostile_toolkit_slug_is_rejected(self, slug, tmp_path):
2842 + outdir = tmp_path / "files"
2843 + outdir.mkdir()
2844 + helper = FileHelper(client=None, outdir=str(outdir))
2845 + with self._mock_get():
2846 + with pytest.raises(UnsafePathComponentError):
2847 + helper.substitute_file_downloads(
2848 + tool=self._tool(toolkit_slug=slug), response=self._response()
2849 + )
2850 + assert list(outdir.iterdir()) == []
2851 +
2852 + def test_traversal_does_not_escape_the_configured_root(self, tmp_path):
2853 + """A deep `../` chain in `tool.slug` must not land the payload in a
2854 + sibling of the configured directory."""
2855 + outdir = tmp_path / "home" / "app" / ".composio" / "files"
2856 + outdir.mkdir(parents=True)
2857 + helper = FileHelper(client=None, outdir=str(outdir))
2858 + depth = len(outdir.resolve().parts) - len(tmp_path.resolve().parts) + 1
2859 + traversal = "/".join([".."] * depth) + "/etc/escaped"
2860 +
2861 + with self._mock_get(b"payload-that-must-not-be-written"):
2862 + with pytest.raises(UnsafePathComponentError):
2863 + helper.substitute_file_downloads(
2864 + tool=self._tool(tool_slug=traversal), response=self._response()
2865 + )
2866 +
2867 + assert not (tmp_path / "etc").exists()
2868 + assert list(outdir.iterdir()) == []
2869 +
2870 + def test_legitimate_slugs_still_nest_under_the_root(self, tmp_path):
2871 + outdir = tmp_path / "files"
2872 + outdir.mkdir()
2873 + helper = FileHelper(client=None, outdir=str(outdir))
2874 + with self._mock_get(b"payload"):
2875 + result = helper.substitute_file_downloads(
2876 + tool=self._tool(), response=self._response()
2877 + )
2878 +
2879 + written = Path(result["attachment"])
2880 + assert (
2881 + written.resolve()
2882 + == (outdir / "GMAIL" / "GMAIL_GET_ATTACHMENT" / "composio").resolve()
2883 + )
2884 + assert written.read_bytes() == b"payload"
2885 +
2886 + def test_tilde_download_dir_still_works(self, tmp_path, monkeypatch):
2887 + """`secure_join` expands `~` in the root; the containment check in
2888 + `download()` must expand it too. When only one side did, every download
2889 + under `file_download_dir='~/...'` failed as a path traversal."""
2890 + monkeypatch.setenv("HOME", str(tmp_path))
2891 + helper = FileHelper(client=None, outdir="~/downloads")
2892 + with self._mock_get(b"payload"):
2893 + result = helper.substitute_file_downloads(
2894 + tool=self._tool(), response=self._response()
2895 + )
2896 +
2897 + written = Path(result["attachment"])
2898 + assert (
2899 + written.resolve()
2900 + == (
2901 + tmp_path / "downloads" / "GMAIL" / "GMAIL_GET_ATTACHMENT" / "composio"
2902 + ).resolve()
2903 + )
2904 + assert written.read_bytes() == b"payload"
2905 +
2906 + def test_symlink_inside_root_cannot_be_used_to_escape(self, tmp_path):
2907 + """Per-component validation cannot see a symlink; the post-resolve
2908 + containment check in `secure_join` is what catches this."""
2909 + outdir = tmp_path / "files"
2910 + outdir.mkdir()
2911 + outside = tmp_path / "outside"
2912 + outside.mkdir()
2913 + (outdir / "GMAIL").symlink_to(outside, target_is_directory=True)
2914 +
2915 + helper = FileHelper(client=None, outdir=str(outdir))
2916 + with self._mock_get():
2917 + with pytest.raises(UnsafePathComponentError, match="outside"):
2918 + helper.substitute_file_downloads(
2919 + tool=self._tool(), response=self._response()
2920 + )
2921 + assert list(outside.iterdir()) == []
2922 +
2923
2924 class TestEnhanceSchemaDescriptionsEmptySchema:
2925 """Regression tests for the empty-input-parameters crash.
python/tests/test_home_guard.py new
+22
@@ -0,0 +1,22 @@
1 +"""Behavioral tests for the real-home write guard."""
2 +
3 +from types import SimpleNamespace
4 +
5 +import pytest
6 +
7 +from tests.conftest import guard_real_home_directory
8 +
9 +
10 +def test_real_home_guard_reports_without_deleting_new_directory(tmp_path):
11 + baseline = {"path": tmp_path, "entries": set()}
12 + request = SimpleNamespace(node=SimpleNamespace(nodeid="test_external_write"))
13 + guard = guard_real_home_directory.__wrapped__(request, baseline)
14 +
15 + next(guard)
16 + unrelated = tmp_path / "unrelated-empty-directory"
17 + unrelated.mkdir()
18 +
19 + with pytest.raises(pytest.fail.Exception, match="created"):
20 + next(guard)
21 +
22 + assert unrelated.is_dir()
python/tests/test_path_join_guardrail.py new
+498
@@ -0,0 +1,498 @@
1 +"""Guardrail against building filesystem paths out of untrusted input.
2 +
3 +The failure mode this prevents: a path built from unvalidated API response
4 +fields, with a containment check that compares the result against the very
5 +directory those fields helped build — tainted against tainted, so it always
6 +passes.
7 +
8 +A convention in `AGENTS.md` would not catch that. Such a line gets written by
9 +someone who has already thought about traversal and added a check. So this
10 +enforces the rule mechanically: every path built from something that is
11 +not a literal or a module-level constant must be recorded in `REVIEWED_JOINS`
12 +with a reason, and each entry must still be backed by the validation its reason
13 +cites.
14 +
15 +Three properties matter, and each is a test below, because each is easy to get
16 +wrong in a way that leaves the check looking present but doing nothing:
17 +
18 +1. **Cover every spelling.** A detector that only understands the `/` operator
19 + is green while `os.path.join` reintroduces the bug.
20 +2. **Fail closed.** No guessing from variable names — renaming `outdir` to
21 + `base` must not silently disable the check.
22 +3. **Bind the allowlist to its evidence.** An entry keyed only on source text
23 + keeps passing after the validation around it is deleted.
24 +
25 +To satisfy this test, prefer `composio.utils.safe_path.secure_join`, which
26 +validates each untrusted component and anchors containment on a trusted root.
27 +"""
28 +
29 +import ast
30 +import functools
31 +import typing as t
32 +from pathlib import Path
33 +
34 +import pytest
35 +
36 +PYTHON_ROOT = Path(__file__).parent.parent
37 +SCANNED_ROOTS = (PYTHON_ROOT / "composio", PYTHON_ROOT / "providers")
38 +
39 +_PATH_CALLS = frozenset({"Path", "PurePath", "PurePosixPath", "PureWindowsPath"})
40 +"""Constructors whose result is a path."""
41 +
42 +_DIRECT_PATH_SINKS = frozenset({"open", "makedirs", "mkdir"})
43 +"""Functions whose first argument becomes a filesystem path."""
44 +
45 +
46 +def _reviewed_path(
47 + reason: str,
48 + *requires: str,
49 + occurrences: int = 1,
50 +) -> t.Dict[str, t.Any]:
51 + return {
52 + "reason": reason,
53 + "requires": frozenset(requires),
54 + "occurrences": occurrences,
55 + }
56 +
57 +
58 +REVIEWED_JOINS: t.Dict[t.Tuple[str, str], t.Dict[str, t.Any]] = {
59 + (
60 + "composio/core/models/_files.py",
61 + (
62 + "Path( os.environ.get( ENV_LOCAL_CACHE_DIRECTORY, Path.home() / "
63 + "LOCAL_CACHE_DIRECTORY_NAME, # Fallback to user directory ) )"
64 + ),
65 + ): _reviewed_path(
66 + "The cache root comes from local configuration or the user's home, not an "
67 + "API response."
68 + ),
69 + (
70 + "composio/core/models/_files.py",
71 + "Path(path_in)",
72 + ): _reviewed_path(
73 + "`FileUploadable.from_path` converts the caller's local upload path after "
74 + "the upload allowlist and sensitive-path checks have run.",
75 + "assert_path_inside_upload_dirs",
76 + "assert_safe_local_file_upload_path",
77 + ),
78 + (
79 + "composio/core/models/_files.py",
80 + "Path(outdir)",
81 + ): _reviewed_path(
82 + "`FileHelper` accepts this download root from local SDK configuration; API "
83 + "response values are joined beneath it through the safe-path helpers."
84 + ),
85 + (
86 + "composio/core/models/tool_router_session_files.py",
87 + "PureWindowsPath(self.mount_relative_path)",
88 + ): _reviewed_path(
89 + "This property only extracts a display basename. `RemoteFile.save` validates "
90 + "the same server value before using it as a filesystem path."
91 + ),
92 + (
93 + "composio/core/models/tool_router_session_files.py",
94 + "Path(path)",
95 + ): _reviewed_path(
96 + "A non-default `RemoteFile.save` destination is selected explicitly by the "
97 + "caller and does not contain an API-derived path component."
98 + ),
99 + (
100 + "composio/core/models/tool_router_session_files.py",
101 + "Path(path_str)",
102 + ): _reviewed_path(
103 + "The upload input is a caller-selected local file and is checked before it is "
104 + "read; it is not a path constructed from a remote response.",
105 + "exists",
106 + "is_file",
107 + ),
108 + (
109 + "composio/integration_test/conftest.py",
110 + "Path(__file__)",
111 + ): _reviewed_path("`__file__` is the trusted location of this installed module."),
112 + (
113 + "composio/utils/mimetypes.py",
114 + "Path(file)",
115 + ): _reviewed_path(
116 + "`mimetypes.guess` uses `Path` for suffix parsing only and never accesses the "
117 + "filesystem."
118 + ),
119 + (
120 + "composio/utils/safe_path.py",
121 + "PureWindowsPath(value)",
122 + ): _reviewed_path(
123 + "The path parser detects cross-platform separators before the component is "
124 + "accepted by the strict slug pattern.",
125 + "fullmatch",
126 + ),
127 + (
128 + "composio/utils/safe_path.py",
129 + "PureWindowsPath(name)",
130 + ): _reviewed_path(
131 + "`safe_basename` collapses the value, rejects Windows-invalid forms, checks "
132 + "its encoded length, and rejects reserved device names.",
133 + "fsencode",
134 + ),
135 + (
136 + "composio/utils/safe_path.py",
137 + "Path(root)",
138 + ): _reviewed_path(
139 + "`resolve_root` normalizes a caller-supplied trusted anchor before any "
140 + "containment comparison.",
141 + "expanduser",
142 + "resolve",
143 + ),
144 + (
145 + "composio/utils/safe_path.py",
146 + "resolved_base / safe_basename(name, label=label)",
147 + ): {
148 + "reason": (
149 + "`secure_basename_join`, the sanctioned single-filename join. The "
150 + "name is collapsed and validated by `safe_basename`, and the result "
151 + "is re-checked with `is_inside_dir` against a `resolve_root`-derived "
152 + "anchor that the caller supplies separately from the join base — the "
153 + "distinction this whole module turns on."
154 + ),
155 + "requires": frozenset({"resolve_root", "safe_basename", "is_inside_dir"}),
156 + "occurrences": 1,
157 + },
158 + ("composio/utils/safe_path.py", "resolved_root.joinpath(*safe_components)"): {
159 + "reason": (
160 + "`secure_join`, the sanctioned multi-component join. Every component "
161 + "has passed `assert_safe_path_component`, the root came from "
162 + "`resolve_root`, and the joined result is re-checked with "
163 + "`is_inside_dir` before return."
164 + ),
165 + "requires": frozenset(
166 + {"resolve_root", "assert_safe_path_component", "is_inside_dir"}
167 + ),
168 + "occurrences": 1,
169 + },
170 + (
171 + "composio/utils/sensitive_file_upload_paths.py",
172 + "Path(file_path)",
173 + ): _reviewed_path(
174 + "This converts a caller-selected upload path so the sensitive-path denylist "
175 + "can inspect its normalized components.",
176 + "expanduser",
177 + "resolve",
178 + ),
179 + (
180 + "composio/utils/upload_dir_allowlist.py",
181 + "Path(s)",
182 + ): _reviewed_path(
183 + "This converts a locally configured upload-allowlist entry and resolves it "
184 + "before comparisons.",
185 + "expanduser",
186 + "resolve",
187 + ),
188 +}
189 +"""Reviewed dynamic path construction in the shipped Python packages.
190 +
191 +Entries outside `safe_path` are limited to caller-selected local paths, local
192 +configuration, module locations, or lexical parsing. API-derived components
193 +must use `secure_join` or `secure_basename_join`.
194 +"""
195 +
196 +for _provider_setup in (
197 + "anthropic",
198 + "autogen",
199 + "claude_agent_sdk",
200 + "crewai",
201 + "gemini",
202 + "google",
203 + "google_adk",
204 + "langchain",
205 + "langgraph",
206 + "llamaindex",
207 + "openai",
208 + "openai_agents",
209 +):
210 + REVIEWED_JOINS[(f"providers/{_provider_setup}/setup.py", "Path(__file__)")] = (
211 + _reviewed_path("`__file__` is the trusted location of this provider package.")
212 + )
213 +del _provider_setup
214 +
215 +
216 +def _module_constants(tree: ast.Module) -> t.Set[str]:
217 + """Module-level ALL_CAPS names bound to a literal.
218 +
219 + Both halves matter. Without the module-level requirement a function-local
220 + `SLUG = tool.slug` is exempt; without the literal requirement a module-level
221 + `SLUG = os.environ[...]` is exempt. Either one is a one-token bypass.
222 + """
223 + out: t.Set[str] = set()
224 + for node in tree.body:
225 + targets: t.List[ast.expr]
226 + if isinstance(node, ast.Assign):
227 + targets = list(node.targets)
228 + value = node.value
229 + elif isinstance(node, ast.AnnAssign) and node.value is not None:
230 + targets = [node.target]
231 + value = node.value
232 + else:
233 + continue
234 + if not _is_literal_expr(value):
235 + continue
236 + for tgt in targets:
237 + if isinstance(tgt, ast.Name) and tgt.id.isupper():
238 + out.add(tgt.id)
239 + return out
240 +
241 +
242 +def _is_literal_expr(node: ast.expr) -> bool:
243 + """True for expressions built only from literals."""
244 + try:
245 + ast.literal_eval(node)
246 + return True
247 + except (ValueError, TypeError, SyntaxError, MemoryError, RecursionError):
248 + return False
249 +
250 +
251 +def _is_trusted(node: ast.expr, consts: t.Set[str]) -> bool:
252 + if isinstance(node, ast.Constant):
253 + return True
254 + if isinstance(node, ast.Name) and node.id in consts:
255 + return True
256 + return False
257 +
258 +
259 +def _call_name(func: ast.expr) -> str:
260 + if isinstance(func, ast.Attribute):
261 + return func.attr
262 + if isinstance(func, ast.Name):
263 + return func.id
264 + return ""
265 +
266 +
267 +def _is_os_path_join(func: ast.expr) -> bool:
268 + """`os.path.join(...)` / `posixpath.join(...)`, not `",".join(...)`."""
269 + if not (isinstance(func, ast.Attribute) and func.attr == "join"):
270 + return False
271 + recv = func.value
272 + if isinstance(recv, ast.Attribute):
273 + return recv.attr == "path"
274 + if isinstance(recv, ast.Name):
275 + return recv.id in {"posixpath", "ntpath", "path"}
276 + return False
277 +
278 +
279 +def _is_direct_path_sink(func: ast.expr) -> bool:
280 + """Builtins or ``os`` functions whose first argument is the path.
281 +
282 + Method calls such as ``Path.open(mode)`` and ``Path.write_bytes(data)``
283 + carry the path in their receiver, not in the positional arguments. Their
284 + receiver construction is reviewed separately by the ``_PATH_CALLS`` rule.
285 + """
286 + if isinstance(func, ast.Name):
287 + return func.id in _DIRECT_PATH_SINKS
288 + return (
289 + isinstance(func, ast.Attribute)
290 + and func.attr in _DIRECT_PATH_SINKS
291 + and isinstance(func.value, ast.Name)
292 + and func.value.id == "os"
293 + )
294 +
295 +
296 +@functools.lru_cache(maxsize=None)
297 +def _read_and_parse(path: Path, mtime_ns: int) -> t.Tuple[str, ast.Module]:
298 + source = path.read_text()
299 + return source, ast.parse(source)
300 +
301 +
302 +def _parse_cached(path: Path) -> t.Tuple[str, ast.Module]:
303 + """Parse ``path``, reusing the previous result while its mtime is unchanged.
304 +
305 + Keyed on mtime so the detector's own self-tests, which rewrite the same
306 + synthetic file with different content, still see the new source.
307 + """
308 + return _read_and_parse(path, path.stat().st_mtime_ns)
309 +
310 +
311 +class Join(t.NamedTuple):
312 + module: str
313 + lineno: int
314 + text: str
315 + kind: str
316 +
317 +
318 +def _collect_joins(roots: t.Sequence[Path] = SCANNED_ROOTS) -> t.List[Join]:
319 + """Every path construction from a non-literal, non-module-constant value."""
320 + found: t.List[Join] = []
321 + for root in roots:
322 + if not root.exists():
323 + continue
324 + for py in sorted(root.rglob("*.py")):
325 + try:
326 + source, tree = _parse_cached(py)
327 + except SyntaxError: # pragma: no cover - lint job fails first
328 + continue
329 + consts = _module_constants(tree)
330 + try:
331 + module = str(py.relative_to(PYTHON_ROOT))
332 + except ValueError:
333 + # Synthetic roots used by the detector's own self-tests.
334 + module = str(py.relative_to(root.parent))
335 +
336 + def record(node: t.Union[ast.expr, ast.stmt], kind: str) -> None:
337 + text = ast.get_source_segment(source, node) or ""
338 + found.append(Join(module, node.lineno, " ".join(text.split()), kind))
339 +
340 + for node in ast.walk(tree):
341 + if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):
342 + if not _is_trusted(node.right, consts):
343 + record(node, "div")
344 + elif isinstance(node, ast.AugAssign) and isinstance(node.op, ast.Div):
345 + if not _is_trusted(node.value, consts):
346 + record(node, "augdiv")
347 + elif isinstance(node, ast.Call):
348 + name = _call_name(node.func)
349 + args = node.args
350 + if name == "joinpath":
351 + if any(not _is_trusted(a, consts) for a in args):
352 + record(node, "joinpath")
353 + elif _is_os_path_join(node.func):
354 + if any(not _is_trusted(a, consts) for a in args):
355 + record(node, "os.path.join")
356 + elif name in _PATH_CALLS:
357 + if any(not _is_trusted(a, consts) for a in args):
358 + record(node, "Path(...)")
359 + elif _is_direct_path_sink(node.func):
360 + if args and not _is_trusted(args[0], consts):
361 + record(node, name)
362 + return found
363 +
364 +
365 +def _enclosing_function_calls(module: str, lineno: int) -> t.Set[str]:
366 + """Names called inside the function containing ``lineno``."""
367 + path = PYTHON_ROOT / module
368 + _, tree = _parse_cached(path)
369 + best: t.Optional[t.Union[ast.FunctionDef, ast.AsyncFunctionDef]] = None
370 + for node in ast.walk(tree):
371 + if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
372 + end = getattr(node, "end_lineno", None) or lineno
373 + if node.lineno <= lineno <= end:
374 + if best is None or node.lineno > best.lineno: # innermost
375 + best = node
376 + if best is None:
377 + return set()
378 + return {_call_name(n.func) for n in ast.walk(best) if isinstance(n, ast.Call)}
379 +
380 +
381 +def test_every_untrusted_path_join_is_reviewed():
382 + unreviewed = [
383 + j for j in _collect_joins() if (j.module, j.text) not in REVIEWED_JOINS
384 + ]
385 + assert not unreviewed, (
386 + "Found path construction(s) from non-constant input that are not "
387 + "recorded in REVIEWED_JOINS:\n"
388 + + "\n".join(f" [{j.kind}] {j.module}:{j.lineno}: {j.text}" for j in unreviewed)
389 + + "\n\nIf the value can come from an API response, use "
390 + "`composio.utils.safe_path.secure_join(root, *components)` instead. "
391 + "If the construction is genuinely safe, add it to REVIEWED_JOINS in "
392 + f"{Path(__file__).name} with a reason and the validators it relies on."
393 + )
394 +
395 +
396 +def test_reviewed_joins_all_still_exist():
397 + """Keeps the allowlist from rotting into stale entries that silently permit
398 + whatever moves into their place."""
399 + found = {(j.module, j.text) for j in _collect_joins()}
400 + stale = set(REVIEWED_JOINS) - found
401 + assert not stale, (
402 + "REVIEWED_JOINS entries no longer present in the source (remove them):\n"
403 + + "\n".join(f" {m}: {tx}" for m, tx in sorted(stale))
404 + )
405 +
406 +
407 +def test_reviewed_joins_still_have_their_validation():
408 + """Entries that depend on validators still call them in the same function."""
409 + for join in _collect_joins():
410 + entry = REVIEWED_JOINS.get((join.module, join.text))
411 + if entry is None:
412 + continue
413 + calls = _enclosing_function_calls(join.module, join.lineno)
414 + missing = entry["requires"] - calls
415 + assert not missing, (
416 + f"{join.module}:{join.lineno}: `{join.text}` is allowlisted because "
417 + f"it is guarded by {sorted(entry['requires'])}, but "
418 + f"{sorted(missing)} is no longer called in the enclosing function. "
419 + "Either restore the validation or re-review the entry."
420 + )
421 +
422 +
423 +def test_reviewed_joins_occurrence_counts_match():
424 + """One entry must not blanket-approve unlimited future joins that happen to
425 + share its source text."""
426 + counts: t.Dict[t.Tuple[str, str], int] = {}
427 + for join in _collect_joins():
428 + counts[(join.module, join.text)] = counts.get((join.module, join.text), 0) + 1
429 + for key, entry in REVIEWED_JOINS.items():
430 + actual = counts.get(key, 0)
431 + assert actual == entry["occurrences"], (
432 + f"{key[0]}: `{key[1]}` appears {actual} time(s), but the "
433 + f"REVIEWED_JOINS entry expects {entry['occurrences']}. A new "
434 + "occurrence is not covered by the existing review."
435 + )
436 +
437 +
438 +EVASIONS = {
439 + "div": "return self._outdir / tool.toolkit.slug / tool.slug",
440 + "div-unhinted-name": "return base / tool.slug",
441 + "augdiv": "p = Path('/tmp')\n p /= tool.slug\n return p",
442 + "joinpath": "return self._outdir.joinpath(tool.slug)",
443 + "os.path.join": "return os.path.join(self._outdir, tool.slug)",
444 + "Path(a, b)": "return Path(self._outdir, tool.slug)",
445 + "Path(value)": "return Path(tool.slug)",
446 + "Path(value, literal)": "return Path(tool.slug, 'payload')",
447 + "Path(value).write": "Path(tool.slug).write_bytes(b'x')\n return None",
448 + "f-string": "return Path(f'{self._outdir}/{tool.slug}')",
449 + "concat": "return Path(self._outdir + '/' + tool.slug)",
450 + "local-uppercase": "SLUG = tool.slug\n return self._outdir / SLUG",
451 + "open-direct": "return open(tool.slug, 'rb')",
452 + "open-fstring": "return open(f'{self._outdir}/{tool.slug}', 'rb')",
453 + "mkdir-direct": "return os.mkdir(tool.slug)",
454 + "makedirs-concat": "return os.makedirs(self._outdir + tool.slug)",
455 +}
456 +
457 +
458 +@pytest.mark.parametrize("label", sorted(EVASIONS))
459 +def test_detector_catches_known_evasions(label, tmp_path):
460 + """Each of these builds a path from untrusted input in a different
461 + spelling. A detector that recognizes only the first stays green for the
462 + rest, which is the whole reason this test is table-driven."""
463 + pkg = tmp_path / "composio"
464 + pkg.mkdir()
465 + (pkg / "vulnerable.py").write_text(
466 + "import os\nfrom pathlib import Path\n\n\n"
467 + f"def f(self, tool):\n {EVASIONS[label]}\n"
468 + )
469 + found = _collect_joins([pkg])
470 + assert found, f"detector missed evasion: {label}"
471 +
472 +
473 +def test_module_constant_exemption_requires_a_literal(tmp_path):
474 + """A module-level ALL_CAPS name bound at runtime is not a constant."""
475 + pkg = tmp_path / "composio"
476 + pkg.mkdir()
477 + (pkg / "vulnerable.py").write_text(
478 + "import os\nfrom pathlib import Path\n\n"
479 + "SAFE = 'literal'\n"
480 + "SLUG = os.environ['SLUG']\n\n\n"
481 + "def f(self):\n return self._outdir / SLUG\n"
482 + )
483 + assert _collect_joins([pkg]), "runtime-bound ALL_CAPS name was treated as constant"
484 +
485 + (pkg / "vulnerable.py").write_text(
486 + "from pathlib import Path\n\n"
487 + "SAFE = 'literal'\n\n\n"
488 + "def f(self):\n return self._outdir / SAFE\n"
489 + )
490 + assert not _collect_joins([pkg]), "literal module constant should be exempt"
491 +
492 +
493 +def test_scan_roots_are_pinned():
494 + """Narrowing the scan silently shrinks the guarantee, so the roots are
495 + asserted rather than assumed."""
496 + assert {p.name for p in SCANNED_ROOTS} == {"composio", "providers"}
497 + for root in SCANNED_ROOTS:
498 + assert root.is_dir(), f"scanned root missing: {root}"
python/tests/test_provider_argument_serialization.py
+6
@@ -14,6 +14,12 @@ from composio.utils.shared import (
14 PROVIDERS = ("crewai", "langchain", "langgraph")
15
16
17 +@pytest.fixture(autouse=True)
18 +def _sandbox_provider_home(tmp_path, monkeypatch):
19 + """Keep provider initialization from writing caches into the real home."""
20 + monkeypatch.setenv("HOME", str(tmp_path))
21 +
22 +
23 def _make_tool(input_parameters: t.Dict[str, t.Any]) -> Tool:
24 return Tool(
25 name="Test tool",
python/tests/test_safe_path.py new
+242
@@ -0,0 +1,242 @@
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 sys
8 +from pathlib import Path
9 +
10 +import pytest
11 +
12 +from composio.exceptions import UnsafePathComponentError
13 +from composio.utils.safe_path import (
14 + SAFE_COMPONENT_REGEX,
15 + assert_safe_path_component,
16 + is_inside_dir,
17 + resolve_root,
18 + safe_basename,
19 + secure_basename_join,
20 + secure_join,
21 +)
22 +
23 +
24 +class TestResolveRoot:
25 + """Both ends of a containment check must normalize through this one
26 + function; when they diverge the check compares mismatched paths."""
27 +
28 + def test_expands_tilde(self, tmp_path, monkeypatch):
29 + monkeypatch.setenv("HOME", str(tmp_path))
30 + assert resolve_root("~/downloads") == (tmp_path / "downloads").resolve()
31 +
32 + def test_resolves_relative(self, tmp_path, monkeypatch):
33 + monkeypatch.chdir(tmp_path)
34 + assert resolve_root("./downloads") == (tmp_path / "downloads").resolve()
35 +
36 + def test_accepts_path_and_str_identically(self, tmp_path):
37 + assert resolve_root(tmp_path) == resolve_root(str(tmp_path))
38 +
39 + def test_nonexistent_root_does_not_raise(self, tmp_path):
40 + assert resolve_root(tmp_path / "nope") == (tmp_path / "nope").resolve()
41 +
42 +
43 +class TestAssertSafePathComponent:
44 + @pytest.mark.parametrize(
45 + "value",
46 + [
47 + "GMAIL",
48 + "GMAIL_GET_ATTACHMENT",
49 + "github",
50 + "some-toolkit",
51 + "v2",
52 + "a",
53 + "A1_b-2",
54 + ],
55 + )
56 + def test_accepts_realistic_slugs(self, value):
57 + assert assert_safe_path_component(value) == value
58 +
59 + @pytest.mark.parametrize(
60 + "value",
61 + [
62 + "..",
63 + ".",
64 + "../etc",
65 + "../../../../../etc/escaped",
66 + "a/b",
67 + "a\\b",
68 + "..\\..\\evil",
69 + "/etc",
70 + "/",
71 + "C:\\Windows",
72 + "C:/Windows",
73 + "",
74 + "a\x00b",
75 + "a b",
76 + "a.b",
77 + "café",
78 + "x" * 129,
79 + ],
80 + )
81 + def test_rejects_unsafe_values(self, value):
82 + with pytest.raises(UnsafePathComponentError):
83 + assert_safe_path_component(value)
84 +
85 + @pytest.mark.parametrize("value", ["GMAIL\n", "GMAIL\r\n", "GMAIL\x0b", "\nGMAIL"])
86 + def test_rejects_control_characters(self, value):
87 + """`re.match` with a `$` anchor also matches just before a single
88 + trailing newline, so `"GMAIL\\n"` satisfied the pattern and reached the
89 + filesystem. `fullmatch` is what closes that."""
90 + with pytest.raises(UnsafePathComponentError):
91 + assert_safe_path_component(value)
92 +
93 + @pytest.mark.parametrize("value", ["CON", "con", "NUL", "COM1", "lpt9", "AUX"])
94 + def test_rejects_windows_device_names_on_every_platform(self, value):
95 + """Rejected regardless of host OS so a POSIX test run cannot pass code
96 + that would target a device on a Windows deployment."""
97 + with pytest.raises(UnsafePathComponentError, match="reserved device name"):
98 + assert_safe_path_component(value)
99 +
100 + def test_rejects_non_string(self):
101 + with pytest.raises(UnsafePathComponentError):
102 + assert_safe_path_component(None) # type: ignore[arg-type]
103 +
104 + def test_label_appears_in_the_error(self):
105 + with pytest.raises(UnsafePathComponentError, match="tool slug"):
106 + assert_safe_path_component("../x", label="tool slug")
107 +
108 + def test_boundary_length(self):
109 + assert assert_safe_path_component("x" * 128) == "x" * 128
110 + with pytest.raises(UnsafePathComponentError, match="longer than"):
111 + assert_safe_path_component("x" * 129)
112 +
113 + def test_matches_the_custom_tool_slug_pattern(self):
114 + """The SDK already enforced this pattern on client-created custom
115 + tools; backend-fetched tools are now held to the same standard."""
116 + from composio.core.models.custom_tool_types import SLUG_REGEX
117 +
118 + assert SAFE_COMPONENT_REGEX.pattern == SLUG_REGEX.pattern
119 +
120 +
121 +class TestIsInsideDir:
122 + def test_nested_path_is_inside(self, tmp_path):
123 + assert is_inside_dir(tmp_path / "a" / "b", tmp_path)
124 +
125 + def test_same_path_is_inside(self, tmp_path):
126 + assert is_inside_dir(tmp_path, tmp_path)
127 +
128 + def test_sibling_prefix_is_not_inside(self, tmp_path):
129 + """`/tmp/foo` must not be treated as containing `/tmp/foo-bar`. A plain
130 + string prefix check gets this wrong."""
131 + assert not is_inside_dir(Path(f"{tmp_path}-evil") / "x", tmp_path)
132 +
133 + def test_parent_is_not_inside(self, tmp_path):
134 + assert not is_inside_dir(tmp_path.parent, tmp_path)
135 +
136 + @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only casing rule")
137 + def test_case_insensitive_on_windows(self):
138 + assert is_inside_dir(Path("C:\\Foo\\Bar"), Path("c:\\foo"))
139 +
140 +
141 +class TestSafeBasename:
142 + @pytest.mark.parametrize(
143 + "value",
144 + ["NUL.tar.gz", "COM1.log.bak", "COM¹.txt", "LPT³.data"],
145 + )
146 + def test_rejects_windows_device_names_with_any_extension(self, value):
147 + with pytest.raises(UnsafePathComponentError, match="reserved device name"):
148 + safe_basename(value)
149 +
150 + @pytest.mark.parametrize(
151 + "value",
152 + ["report?.txt", "report.txt:payload", "report.txt.", "report.txt "],
153 + )
154 + def test_rejects_windows_invalid_names_on_every_platform(self, value):
155 + with pytest.raises(UnsafePathComponentError):
156 + safe_basename(value)
157 +
158 + def test_limits_encoded_filename_bytes(self):
159 + with pytest.raises(UnsafePathComponentError, match="longer than"):
160 + safe_basename("😀" * 128)
161 +
162 + def test_rejects_unencodable_filename(self):
163 + with pytest.raises(UnsafePathComponentError, match="invalid Unicode"):
164 + safe_basename("report-\ud800.txt")
165 +
166 +
167 +class TestSecureBasenameJoin:
168 + def test_tilde_base_is_expanded_before_containment(self, tmp_path, monkeypatch):
169 + monkeypatch.setenv("HOME", str(tmp_path))
170 + assert (
171 + secure_basename_join("~/downloads", "report.pdf")
172 + == (tmp_path / "downloads" / "report.pdf").resolve()
173 + )
174 +
175 +
176 +class TestSecureJoin:
177 + def test_joins_safe_components(self, tmp_path):
178 + assert (
179 + secure_join(tmp_path, "GMAIL", "GMAIL_GET_ATTACHMENT")
180 + == (tmp_path / "GMAIL" / "GMAIL_GET_ATTACHMENT").resolve()
181 + )
182 +
183 + def test_no_components_returns_the_root(self, tmp_path):
184 + assert secure_join(tmp_path) == tmp_path.resolve()
185 +
186 + @pytest.mark.parametrize("component", ["..", "../etc", "/etc", "a/b", "..\\evil"])
187 + def test_rejects_traversal_components(self, component, tmp_path):
188 + with pytest.raises(UnsafePathComponentError):
189 + secure_join(tmp_path, component)
190 +
191 + def test_rejects_traversal_in_any_position(self, tmp_path):
192 + with pytest.raises(UnsafePathComponentError):
193 + secure_join(tmp_path, "GMAIL", "..")
194 +
195 + def test_creates_nothing_on_disk(self, tmp_path):
196 + """Validation must complete before any filesystem write, so a rejected
197 + join leaves no attacker-chosen directories behind."""
198 + root = tmp_path / "root"
199 + root.mkdir()
200 + with pytest.raises(UnsafePathComponentError):
201 + secure_join(root, "../evil")
202 + assert list(root.iterdir()) == []
203 +
204 + secure_join(root, "GMAIL", "TOOL")
205 + assert list(root.iterdir()) == []
206 +
207 + def test_symlink_escape_is_caught_after_resolve(self, tmp_path):
208 + """Per-component validation cannot see a symlink pointing out of the
209 + root; the post-resolve containment check is what catches it."""
210 + root = tmp_path / "root"
211 + root.mkdir()
212 + outside = tmp_path / "outside"
213 + outside.mkdir()
214 + (root / "GMAIL").symlink_to(outside, target_is_directory=True)
215 +
216 + with pytest.raises(UnsafePathComponentError, match="outside"):
217 + secure_join(root, "GMAIL", "TOOL")
218 +
219 + def test_root_is_expanded_and_resolved(self, tmp_path):
220 + nested = tmp_path / "a" / ".." / "b"
221 + (tmp_path / "b").mkdir(parents=True)
222 + assert secure_join(nested, "TOOL") == (tmp_path / "b" / "TOOL").resolve()
223 +
224 + def test_accepts_str_root(self, tmp_path):
225 + assert secure_join(str(tmp_path), "TOOL") == (tmp_path / "TOOL").resolve()
226 +
227 + def test_tilde_root_is_expanded(self, tmp_path, monkeypatch):
228 + """`~` must expand identically here and in every containment check that
229 + shares this root, or a legitimate download is rejected as an attack."""
230 + monkeypatch.setenv("HOME", str(tmp_path))
231 + assert (
232 + secure_join("~/downloads", "GMAIL")
233 + == (tmp_path / "downloads" / "GMAIL").resolve()
234 + )
235 +
236 + def test_nonexistent_root_still_validates(self, tmp_path):
237 + """`resolve(strict=False)` means the root need not exist yet — the
238 + download directory is created lazily."""
239 + root = tmp_path / "not-created-yet"
240 + assert secure_join(root, "TOOL") == (root / "TOOL").resolve()
241 + with pytest.raises(UnsafePathComponentError):
242 + secure_join(root, "..")