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 | """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 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: |
| 74 | """True iff ``child`` equals ``parent`` or is nested inside it on a path |
| 75 | component boundary. |
| 76 | |
| 77 | ``/tmp/foo`` contains ``/tmp/foo/bar`` but NOT ``/tmp/foo-bar`` — a plain |
| 78 | string prefix test gets that wrong. Comparison is case-insensitive on |
| 79 | Windows, where ``C:\\Foo`` and ``c:\\foo`` are the same directory. |
| 80 | |
| 81 | Both arguments are assumed absolute and normalized. |
| 82 | """ |
| 83 | try: |
| 84 | child_str = str(child) |
| 85 | parent_str = str(parent) |
| 86 | if sys.platform == "win32": |
| 87 | child_str = child_str.lower() |
| 88 | parent_str = parent_str.lower() |
| 89 | if child_str == parent_str: |
| 90 | return True |
| 91 | sep = os.sep |
| 92 | parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep |
| 93 | return child_str.startswith(parent_with_sep) |
| 94 | except OSError: |
| 95 | return False |
| 96 | |
| 97 | |
| 98 | def assert_safe_path_component(value: str, *, label: str = "path component") -> str: |
| 99 | """Return ``value`` unchanged if it is safe to use as a single path |
| 100 | component, else raise. |
| 101 | |
| 102 | Fails closed. Rejects traversal (``..``), separators of either platform, |
| 103 | absolute paths, drive letters, NUL bytes, reserved device names, and |
| 104 | anything outside :data:`SAFE_COMPONENT_REGEX`. |
| 105 | |
| 106 | :raises UnsafePathComponentError: when ``value`` is unsafe. |
| 107 | """ |
| 108 | if not isinstance(value, str) or not value: |
| 109 | raise UnsafePathComponentError( |
| 110 | f"Refusing to build a path from an empty or non-string {label}: {value!r}" |
| 111 | ) |
| 112 | |
| 113 | # `PureWindowsPath` treats both `/` and `\` as separators, so a single check |
| 114 | # catches `../x` and `..\x` regardless of the host platform. A slug crafted |
| 115 | # for a Windows target must not slip through on a POSIX build machine. |
| 116 | as_windows_path = PureWindowsPath(value) |
| 117 | if len(as_windows_path.parts) != 1 or as_windows_path.anchor: |
| 118 | raise UnsafePathComponentError( |
| 119 | f"Refusing to build a path from a {label} containing path separators " |
| 120 | f"or a drive letter: {value!r}" |
| 121 | ) |
| 122 | |
| 123 | if len(value) > MAX_COMPONENT_LENGTH: |
| 124 | raise UnsafePathComponentError( |
| 125 | f"Refusing to build a path from a {label} longer than " |
| 126 | f"{MAX_COMPONENT_LENGTH} characters: {value[:32]!r}... " |
| 127 | f"({len(value)} characters)" |
| 128 | ) |
| 129 | |
| 130 | # `.` and `..` are excluded by the regex (no `.` in the character class), |
| 131 | # as are NUL bytes and every separator. The explicit checks above exist to |
| 132 | # produce a precise error message rather than a generic pattern mismatch. |
| 133 | # |
| 134 | # `fullmatch`, not `match`: in a `match`, `$` also matches just before a |
| 135 | # single trailing newline, so `"GMAIL\n"` would satisfy `^[A-Za-z0-9_-]+$` |
| 136 | # and reach the filesystem with a control character in the name. |
| 137 | if not SAFE_COMPONENT_REGEX.fullmatch(value): |
| 138 | raise UnsafePathComponentError( |
| 139 | f"Refusing to build a path from an unsafe {label}: {value!r}. " |
| 140 | f"Expected only letters, digits, underscores, and hyphens " |
| 141 | f"(pattern {SAFE_COMPONENT_REGEX.pattern})." |
| 142 | ) |
| 143 | |
| 144 | if value.upper() in WINDOWS_RESERVED_NAMES: |
| 145 | raise UnsafePathComponentError( |
| 146 | f"Refusing to build a path from a reserved device name as {label}: {value!r}" |
| 147 | ) |
| 148 | |
| 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 _split_extension(name: str) -> t.Tuple[str, str]: |
| 170 | """Split off a short trailing extension (with its dot); a leading dot is |
| 171 | not one.""" |
| 172 | dot = name.rfind(".") |
| 173 | extension = name[dot:] if dot > 0 else "" |
| 174 | if extension and _encoded_length(extension) <= MAX_PRESERVED_EXTENSION_BYTES: |
| 175 | return name[:dot], extension |
| 176 | return name, "" |
| 177 | |
| 178 | |
| 179 | def _fit_filename_bytes(name: str, max_bytes: int = MAX_COMPONENT_LENGTH) -> str: |
| 180 | """Truncate ``name`` to ``max_bytes``, keeping a short extension so the file |
| 181 | still opens with the right application.""" |
| 182 | if _encoded_length(name) <= max_bytes: |
| 183 | return name |
| 184 | stem, extension = _split_extension(name) |
| 185 | return _truncate_to_bytes(stem, max_bytes - _encoded_length(extension)) + extension |
| 186 | |
| 187 | |
| 188 | def numbered_basename(name: str, copy: int) -> str: |
| 189 | """Add a copy number before the extension within the filename byte limit.""" |
| 190 | suffix = f"-{copy}" |
| 191 | stem, extension = _split_extension(name) |
| 192 | return ( |
| 193 | _truncate_to_bytes( |
| 194 | stem, MAX_COMPONENT_LENGTH - _encoded_length(extension) - len(suffix) |
| 195 | ) |
| 196 | + suffix |
| 197 | + extension |
| 198 | ) |
| 199 | |
| 200 | |
| 201 | def open_unique_file(path: Path) -> t.Tuple[Path, t.BinaryIO]: |
| 202 | """Claim a validated download path without replacing an existing file. |
| 203 | |
| 204 | Numbered alternatives stay in the same directory and preserve a short |
| 205 | extension. Exclusive creation also prevents concurrent saves from sharing |
| 206 | a destination. |
| 207 | """ |
| 208 | copy = 0 |
| 209 | while True: |
| 210 | candidate = ( |
| 211 | path if copy == 0 else path.with_name(numbered_basename(path.name, copy)) |
| 212 | ) |
| 213 | try: |
| 214 | return candidate, candidate.open("xb") |
| 215 | except FileExistsError: |
| 216 | copy += 1 |
| 217 | |
| 218 | |
| 219 | _FNV_OFFSET_BASIS_64 = 0xCBF29CE484222325 |
| 220 | _FNV_PRIME_64 = 0x100000001B3 |
| 221 | _UINT64_MASK = 0xFFFFFFFFFFFFFFFF |
| 222 | |
| 223 | |
| 224 | def _fnv1a64_hex(value: str) -> str: |
| 225 | """64-bit FNV-1a of the UTF-8 bytes, as 16 hex digits. ``fnv1a64Hex`` in |
| 226 | the TypeScript SDK matches it.""" |
| 227 | digest = _FNV_OFFSET_BASIS_64 |
| 228 | for byte in value.encode("utf-8", "surrogatepass"): |
| 229 | digest = ((digest ^ byte) * _FNV_PRIME_64) & _UINT64_MASK |
| 230 | return f"{digest:016x}" |
| 231 | |
| 232 | |
| 233 | def _tag_with_original(portable: str, original: str) -> str: |
| 234 | """Tag a name that portability changed with a digest of the name it came |
| 235 | from, before the extension: ``report?.png`` and ``report*.png`` both become |
| 236 | ``report_.png``, and two long names can share a truncated prefix, so |
| 237 | without the tag one download would overwrite the other in a shared |
| 238 | directory.""" |
| 239 | tag = f"-{_fnv1a64_hex(original)}" |
| 240 | stem, extension = _split_extension( |
| 241 | _fit_filename_bytes(portable, MAX_COMPONENT_LENGTH - len(tag)) |
| 242 | ) |
| 243 | return stem + tag + extension |
| 244 | |
| 245 | |
| 246 | def safe_basename(name: str, *, label: str = "filename") -> str: |
| 247 | """Collapse an untrusted filename to a bare basename that is safe to write |
| 248 | on every platform. |
| 249 | |
| 250 | Filenames need their own validator: :func:`assert_safe_path_component` |
| 251 | forbids ``.``, which nearly every real filename contains. |
| 252 | |
| 253 | ``PureWindowsPath`` treats both ``/`` and ``\\`` as separators, so a name |
| 254 | crafted for a Windows target (``..\\..\\evil``) is stripped even when the |
| 255 | SDK runs on POSIX, where ``Path(...).name`` would return it intact. |
| 256 | |
| 257 | Names that cannot be written at all are refused: a NUL byte, invalid |
| 258 | Unicode, or no usable basename (empty or a run of dots). A response that |
| 259 | cannot name its own file is malformed or hostile, and inventing a name |
| 260 | would hide that. ``.`` and the empty string both basename to ``""``, which |
| 261 | makes an output path equal to its own directory and surfaces as |
| 262 | ``IsADirectoryError`` at write time. |
| 263 | |
| 264 | Names that are merely unportable are made portable instead, because |
| 265 | ordinary files have them (``report_2026-09-29T10:30:00.csv``, |
| 266 | ``What is this?.png``), on every platform so a name does not depend on |
| 267 | where the SDK runs: control and Windows-reserved characters become ``_``, |
| 268 | names over :data:`MAX_COMPONENT_LENGTH` bytes are truncated with their |
| 269 | extension kept, trailing spaces and dots are dropped as Windows would, and |
| 270 | a resulting reserved device name gets a ``_`` prefix. A name any of these |
| 271 | rules changed is then tagged with a digest of the original before its |
| 272 | extension (``report_-<16 hex>.png``) to distinguish ordinary normalization |
| 273 | collisions; a name that was already portable is returned unchanged. The |
| 274 | result can still equal a literal server name, so download writes use |
| 275 | :func:`open_unique_file` to preserve existing files. |
| 276 | ``safeBasename`` in the TypeScript SDK applies the same rules in the same |
| 277 | order. |
| 278 | |
| 279 | ``str.strip`` removes surrounding whitespace first, and the usability check |
| 280 | runs last, on the value that gets written, so neither ``"\\u00a0.\\u00a0"`` |
| 281 | nor ``". ."`` can be written as ``.`` or as its own directory. |
| 282 | |
| 283 | :raises UnsafePathComponentError: when ``name`` contains a NUL byte or |
| 284 | invalid Unicode, or leaves no usable basename. |
| 285 | """ |
| 286 | if not isinstance(name, str): |
| 287 | raise UnsafePathComponentError( |
| 288 | f"Refusing to write a non-string {label}: {name!r}" |
| 289 | ) |
| 290 | |
| 291 | basename = PureWindowsPath(name).name.strip() |
| 292 | if "\x00" in basename: |
| 293 | raise UnsafePathComponentError( |
| 294 | f"Refusing to write {label} containing a NUL byte: {name!r}" |
| 295 | ) |
| 296 | try: |
| 297 | _encoded_length(basename) |
| 298 | except UnicodeEncodeError as e: |
| 299 | raise UnsafePathComponentError( |
| 300 | f"Refusing to write {label} containing invalid Unicode: {name!r}" |
| 301 | ) from e |
| 302 | |
| 303 | def fit(value: str) -> str: |
| 304 | return _fit_filename_bytes(value).rstrip(". ") |
| 305 | |
| 306 | portable = fit(_WINDOWS_INVALID_FILENAME_CHARS.sub("_", basename)) |
| 307 | # Checked on the fitted name, because truncation and trailing-dot removal |
| 308 | # can expose one (`NUL` followed by spaces and a long tail). Compare |
| 309 | # everything before the first dot: on Windows `NUL.tar.gz` opens the null |
| 310 | # device just as `NUL` does, so extensions provide no protection. Fitting |
| 311 | # again keeps the byte bound, and a `_`-prefixed name is never a device. |
| 312 | device_name = portable.split(".", 1)[0].rstrip(" ").upper() |
| 313 | if device_name in WINDOWS_RESERVED_NAMES: |
| 314 | portable = fit(f"_{portable}") |
| 315 | |
| 316 | if not portable: |
| 317 | raise UnsafePathComponentError( |
| 318 | f"Path traversal detected: {label} {name!r} leaves no usable " |
| 319 | "basename to write to." |
| 320 | ) |
| 321 | return portable if portable == basename else _tag_with_original(portable, basename) |
| 322 | |
| 323 | |
| 324 | def resolve_root(root: t.Union[str, Path]) -> Path: |
| 325 | """Normalize a trusted root to an absolute, symlink-resolved path. |
| 326 | |
| 327 | Every containment check must derive its anchor through this one function. |
| 328 | When two call sites normalize differently — one expanding ``~`` and one not |
| 329 | — the check compares mismatched paths and rejects legitimate writes while |
| 330 | reporting them as attacks. Sharing the normalization is what keeps the two |
| 331 | ends of a containment check comparable. |
| 332 | """ |
| 333 | expanded = Path(root).expanduser() |
| 334 | try: |
| 335 | return expanded.resolve(strict=False) |
| 336 | except OSError: |
| 337 | return expanded |
| 338 | |
| 339 | |
| 340 | def secure_basename_join( |
| 341 | base: t.Union[str, Path], |
| 342 | name: str, |
| 343 | *, |
| 344 | root: t.Optional[t.Union[str, Path]] = None, |
| 345 | label: str = "filename", |
| 346 | ) -> Path: |
| 347 | """Join a single untrusted filename under ``base``, contained within ``root``. |
| 348 | |
| 349 | The filename counterpart to :func:`secure_join`, which cannot be reused here |
| 350 | because it forbids ``.`` — correct for a slug, wrong for ``report.pdf``. |
| 351 | |
| 352 | ``root`` defaults to ``base`` but is separate for the download path, where |
| 353 | ``base`` is a per-tool subdirectory that untrusted slugs helped build and |
| 354 | only the configured ``root`` above it is trusted. Anchoring on ``base`` |
| 355 | there would check the result against a directory those slugs had moved. |
| 356 | |
| 357 | :raises UnsafePathComponentError: when ``name`` is unsafe, or when the |
| 358 | result escapes ``root``. |
| 359 | """ |
| 360 | resolved_base = resolve_root(base) |
| 361 | resolved_root = resolved_base if root is None else resolve_root(root) |
| 362 | candidate = resolved_base / safe_basename(name, label=label) |
| 363 | if not is_inside_dir(candidate.resolve(), resolved_root): |
| 364 | raise UnsafePathComponentError( |
| 365 | f"Path traversal detected: {label} {name!r} resolves to " |
| 366 | f"{candidate.resolve()}, which is outside {resolved_root}." |
| 367 | ) |
| 368 | return candidate |
| 369 | |
| 370 | |
| 371 | def secure_join(root: t.Union[str, Path], *components: str) -> Path: |
| 372 | """Join untrusted ``components`` beneath the trusted ``root``. |
| 373 | |
| 374 | ``root`` is the sole anchor of trust and must not itself be derived from |
| 375 | untrusted input — that is the whole point. Each component is validated by |
| 376 | :func:`assert_safe_path_component`, then the joined result is resolved and |
| 377 | re-checked against the resolved root. The second check is belt-and-braces: |
| 378 | it catches a symlink inside ``root`` pointing outside it, which per-component |
| 379 | validation cannot see. |
| 380 | |
| 381 | Performs no filesystem writes; the caller creates directories only after |
| 382 | this returns. |
| 383 | |
| 384 | :raises UnsafePathComponentError: when any component is unsafe, or when the |
| 385 | joined path escapes ``root``. |
| 386 | """ |
| 387 | resolved_root = resolve_root(root) |
| 388 | |
| 389 | safe_components = [ |
| 390 | assert_safe_path_component(component) for component in components |
| 391 | ] |
| 392 | |
| 393 | candidate = resolved_root.joinpath(*safe_components) |
| 394 | try: |
| 395 | resolved_candidate = candidate.resolve(strict=False) |
| 396 | except OSError: |
| 397 | resolved_candidate = candidate |
| 398 | |
| 399 | if not is_inside_dir(resolved_candidate, resolved_root): |
| 400 | raise UnsafePathComponentError( |
| 401 | f"Refusing to write outside the configured directory: " |
| 402 | f"{components!r} resolves to {resolved_candidate}, " |
| 403 | f"which is outside {resolved_root}." |
| 404 | ) |
| 405 | |
| 406 | return resolved_candidate |