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 | /** |
| 2 | * Filename containment for untrusted input. |
| 3 | * |
| 4 | * Every field of an API response is untrusted, including filenames. When such a |
| 5 | * value becomes part of a filesystem path it must pass through this module |
| 6 | * first, and validation must happen before any `mkdir` or write so a rejected |
| 7 | * value leaves nothing behind on disk. |
| 8 | * |
| 9 | * TypeScript counterpart of `safe_basename` in `python/composio/utils/safe_path.py`. |
| 10 | * The two use the same validation order and whitespace rules. Path extraction |
| 11 | * is intentionally limited here; see `untrustedBasename`. |
| 12 | * |
| 13 | * Pure string logic with no filesystem access: no static `node:*` imports, so |
| 14 | * it is usable from edge/workerd builds. |
| 15 | */ |
| 16 | import { ValidationError } from '../errors/ValidationErrors'; |
| 17 | |
| 18 | /** |
| 19 | * Upper bound on a filename, well under the 255-byte limit common to |
| 20 | * ext4/APFS/NTFS. A longer server-supplied name is truncated to fit rather |
| 21 | * than failing with a raw `ENAMETOOLONG` mid-write. Matches |
| 22 | * `MAX_COMPONENT_LENGTH` in the Python SDK. |
| 23 | */ |
| 24 | export const MAX_FILENAME_BYTES = 128; |
| 25 | |
| 26 | /** |
| 27 | * Longest extension, in bytes and including its dot, that truncation keeps. |
| 28 | * Anything longer is not a real extension and is truncated with the rest. |
| 29 | */ |
| 30 | const MAX_PRESERVED_EXTENSION_BYTES = 32; |
| 31 | |
| 32 | /** |
| 33 | * Reserved DOS device names. Writing to one on Windows targets the device |
| 34 | * rather than a file. Prefixed on every platform so behavior does not diverge |
| 35 | * between a POSIX developer machine and a Windows deployment. |
| 36 | */ |
| 37 | const WINDOWS_RESERVED_NAMES: ReadonlySet<string> = new Set([ |
| 38 | 'CON', |
| 39 | 'PRN', |
| 40 | 'AUX', |
| 41 | 'NUL', |
| 42 | ...Array.from({ length: 9 }, (_, i) => `COM${i + 1}`), |
| 43 | ...Array.from({ length: 9 }, (_, i) => `LPT${i + 1}`), |
| 44 | ...['¹', '²', '³'].flatMap(superscript => [`COM${superscript}`, `LPT${superscript}`]), |
| 45 | ]); |
| 46 | |
| 47 | /** Control characters and characters reserved by Windows. */ |
| 48 | const WINDOWS_INVALID_CHARS = /[\u0000-\u001f<>:"|?*]/g; |
| 49 | |
| 50 | /** Windows drops trailing spaces and dots from a filename. */ |
| 51 | const TRAILING_SPACES_AND_DOTS = /[. ]+$/; |
| 52 | |
| 53 | const utf8Length = (value: string): number => new TextEncoder().encode(value).length; |
| 54 | |
| 55 | const FNV_OFFSET_BASIS_64 = 0xcbf29ce484222325n; |
| 56 | const FNV_PRIME_64 = 0x100000001b3n; |
| 57 | const UINT64_MASK = 0xffffffffffffffffn; |
| 58 | |
| 59 | /** |
| 60 | * 64-bit FNV-1a of the UTF-8 bytes, as 16 hex digits. Pure and synchronous, so |
| 61 | * it runs on every runtime; `_fnv1a64_hex` in the Python SDK matches it. |
| 62 | */ |
| 63 | function fnv1a64Hex(value: string): string { |
| 64 | let hash = FNV_OFFSET_BASIS_64; |
| 65 | for (const byte of new TextEncoder().encode(value)) { |
| 66 | hash = ((hash ^ BigInt(byte)) * FNV_PRIME_64) & UINT64_MASK; |
| 67 | } |
| 68 | return hash.toString(16).padStart(16, '0'); |
| 69 | } |
| 70 | |
| 71 | /** |
| 72 | * Python str.strip() whitespace: Unicode White_Space plus U+001C–U+001F. |
| 73 | * Unlike JavaScript trim(), this includes U+0085 and preserves U+FEFF. |
| 74 | */ |
| 75 | const PYTHON_WHITESPACE = |
| 76 | '[\\u0009-\\u000d\\u001c-\\u0020\\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]'; |
| 77 | const SURROUNDING_WHITESPACE = new RegExp(`^${PYTHON_WHITESPACE}+|${PYTHON_WHITESPACE}+$`, 'g'); |
| 78 | |
| 79 | /** |
| 80 | * Returns the last path segment of `value`, treating both `/` and `\` as |
| 81 | * separators, or `''` when there is none. |
| 82 | * |
| 83 | * `path.basename()` on POSIX only splits on `/`, so a name crafted for a |
| 84 | * Windows target (`..\..\evil`) comes back intact on macOS and Linux. Splitting |
| 85 | * on both and removing an initial drive prefix also handles `C:report.txt`. |
| 86 | * This is not a full `PureWindowsPath` parser: dot components stay literal, |
| 87 | * and UNC anchors are not interpreted. |
| 88 | * |
| 89 | * Never throws: this is a display value as well as the input to |
| 90 | * {@link safeBasename}, and it is read while constructing download errors. |
| 91 | */ |
| 92 | export function untrustedBasename(value: string): string { |
| 93 | const segments = value.replace(/^[a-z]:/i, '').split(/[/\\]+/); |
| 94 | // Trailing separators name the same file: `a/b/` and `a/b` both basename to `b`. |
| 95 | while (segments.length > 0 && segments[segments.length - 1] === '') { |
| 96 | segments.pop(); |
| 97 | } |
| 98 | return segments[segments.length - 1] ?? ''; |
| 99 | } |
| 100 | |
| 101 | /** |
| 102 | * True when `value` contains a surrogate code unit that is not part of a valid |
| 103 | * pair. Such a string cannot be encoded as UTF-8; `TextEncoder` silently |
| 104 | * substitutes U+FFFD, which would write a file under a name the response never |
| 105 | * specified. `String.prototype.isWellFormed()` is ES2024 and this package |
| 106 | * targets es2022, hence the manual scan. |
| 107 | */ |
| 108 | function hasLoneSurrogate(value: string): boolean { |
| 109 | for (let i = 0; i < value.length; i++) { |
| 110 | const code = value.charCodeAt(i); |
| 111 | if (code >= 0xd800 && code <= 0xdbff) { |
| 112 | const next = value.charCodeAt(i + 1); |
| 113 | if (!(next >= 0xdc00 && next <= 0xdfff)) { |
| 114 | return true; |
| 115 | } |
| 116 | i++; |
| 117 | } else if (code >= 0xdc00 && code <= 0xdfff) { |
| 118 | return true; |
| 119 | } |
| 120 | } |
| 121 | return false; |
| 122 | } |
| 123 | |
| 124 | /** The longest prefix of `value`, by whole code points, that fits in `maxBytes`. */ |
| 125 | function truncateToBytes(value: string, maxBytes: number): string { |
| 126 | let truncated = ''; |
| 127 | let bytes = 0; |
| 128 | for (const char of value) { |
| 129 | bytes += utf8Length(char); |
| 130 | if (bytes > maxBytes) { |
| 131 | break; |
| 132 | } |
| 133 | truncated += char; |
| 134 | } |
| 135 | return truncated; |
| 136 | } |
| 137 | |
| 138 | /** Splits off a short trailing extension (with its dot); a leading dot is not one. */ |
| 139 | function splitExtension(name: string): [stem: string, extension: string] { |
| 140 | const dot = name.lastIndexOf('.'); |
| 141 | const extension = dot > 0 ? name.slice(dot) : ''; |
| 142 | return extension && utf8Length(extension) <= MAX_PRESERVED_EXTENSION_BYTES |
| 143 | ? [name.slice(0, dot), extension] |
| 144 | : [name, '']; |
| 145 | } |
| 146 | |
| 147 | /** |
| 148 | * Truncates `name` to `maxBytes`, keeping a short extension so the file still |
| 149 | * opens with the right application. |
| 150 | */ |
| 151 | function fitFilenameBytes(name: string, maxBytes: number = MAX_FILENAME_BYTES): string { |
| 152 | if (utf8Length(name) <= maxBytes) { |
| 153 | return name; |
| 154 | } |
| 155 | const [stem, extension] = splitExtension(name); |
| 156 | return truncateToBytes(stem, maxBytes - utf8Length(extension)) + extension; |
| 157 | } |
| 158 | |
| 159 | /** Adds a copy number before the extension without exceeding the filename byte limit. */ |
| 160 | export function numberedBasename(name: string, copy: number): string { |
| 161 | const suffix = `-${copy}`; |
| 162 | const [stem, extension] = splitExtension(name); |
| 163 | return ( |
| 164 | truncateToBytes(stem, MAX_FILENAME_BYTES - utf8Length(extension) - suffix.length) + |
| 165 | suffix + |
| 166 | extension |
| 167 | ); |
| 168 | } |
| 169 | |
| 170 | /** |
| 171 | * Tags a name that portability changed with a digest of the name it came |
| 172 | * from, before the extension: `report?.png` and `report*.png` both become |
| 173 | * `report_.png`, and two long names can share a truncated prefix, so without |
| 174 | * the tag one download would overwrite the other in a shared directory. |
| 175 | */ |
| 176 | function tagWithOriginal(portable: string, original: string): string { |
| 177 | const tag = `-${fnv1a64Hex(original)}`; |
| 178 | const [stem, extension] = splitExtension( |
| 179 | fitFilenameBytes(portable, MAX_FILENAME_BYTES - tag.length) |
| 180 | ); |
| 181 | return stem + tag + extension; |
| 182 | } |
| 183 | |
| 184 | /** |
| 185 | * Collapses an untrusted filename to a bare basename that is safe to write on |
| 186 | * every platform. |
| 187 | * |
| 188 | * Names that cannot be written at all are refused: a NUL byte, invalid |
| 189 | * Unicode, or no usable basename (empty or a run of dots). A response that |
| 190 | * cannot name its own file is malformed or hostile, and inventing a name would |
| 191 | * hide that. `""`, `"."` and `".."` make an output path equal to, or escape, |
| 192 | * its own directory, which surfaces as a raw `EISDIR` at write time instead of |
| 193 | * a validation error. |
| 194 | * |
| 195 | * Names that are merely unportable are made portable instead, because ordinary |
| 196 | * files have them (`report_2026-09-29T10:30:00.csv`, `What is this?.png`), on |
| 197 | * every platform so a name does not depend on where the SDK runs: |
| 198 | * control and Windows-reserved characters become `_`, names over |
| 199 | * {@link MAX_FILENAME_BYTES} are truncated with their extension kept, trailing |
| 200 | * spaces and dots are dropped as Windows would, and a resulting reserved |
| 201 | * device name gets a `_` prefix. A name any of these rules changed is then |
| 202 | * tagged with a digest of the original before its extension |
| 203 | * (`report_-<16 hex>.png`) to distinguish ordinary normalization collisions; |
| 204 | * a name that was already portable is returned unchanged. A result can still |
| 205 | * equal a literal server name, so default saves create files exclusively. |
| 206 | * `safe_basename` in |
| 207 | * the Python SDK applies the same rules in the same order. |
| 208 | * |
| 209 | * Python-compatible stripping removes surrounding whitespace first, and the |
| 210 | * usability check runs last, on the value that gets written, so neither |
| 211 | * `"\u00a0.\u00a0"` nor `". ."` can be written as `.` or as its own directory. |
| 212 | * |
| 213 | * @param name - The untrusted filename or relative path to reduce. |
| 214 | * @param label - How the value is described in error messages. |
| 215 | * @returns The bare basename to write, adjusted to be portable. |
| 216 | * @throws ValidationError if `name` contains a NUL byte or invalid Unicode, or |
| 217 | * leaves no usable basename. |
| 218 | */ |
| 219 | export function safeBasename(name: string, label: string = 'filename'): string { |
| 220 | const basename = untrustedBasename(name).replace(SURROUNDING_WHITESPACE, ''); |
| 221 | |
| 222 | if (basename.includes('\u0000')) { |
| 223 | throw new ValidationError( |
| 224 | `Refusing to write ${label} containing a NUL byte: ${JSON.stringify(name)}` |
| 225 | ); |
| 226 | } |
| 227 | if (hasLoneSurrogate(basename)) { |
| 228 | throw new ValidationError( |
| 229 | `Refusing to write ${label} containing invalid Unicode: ${JSON.stringify(name)}` |
| 230 | ); |
| 231 | } |
| 232 | |
| 233 | const fit = (value: string): string => |
| 234 | fitFilenameBytes(value).replace(TRAILING_SPACES_AND_DOTS, ''); |
| 235 | let portable = fit(basename.replace(WINDOWS_INVALID_CHARS, '_')); |
| 236 | // Checked on the fitted name, because truncation and trailing-dot removal |
| 237 | // can expose one (`NUL` followed by spaces and a long tail). Compare |
| 238 | // everything before the first dot: on Windows `NUL.tar.gz` opens the null |
| 239 | // device just as `NUL` does, so extensions provide no protection. Fitting |
| 240 | // again keeps the byte bound, and a `_`-prefixed name is never a device. |
| 241 | const deviceName = portable.split('.', 1)[0].replace(/ +$/, '').toUpperCase(); |
| 242 | if (WINDOWS_RESERVED_NAMES.has(deviceName)) { |
| 243 | portable = fit(`_${portable}`); |
| 244 | } |
| 245 | |
| 246 | if (!portable) { |
| 247 | throw new ValidationError( |
| 248 | `Path traversal detected: ${label} ${JSON.stringify(name)} leaves no usable basename to write to.` |
| 249 | ); |
| 250 | } |
| 251 | |
| 252 | return portable === basename ? portable : tagWithOriginal(portable, basename); |
| 253 | } |