Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 253 lines 10 KB
Raw
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 }