Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
feat(sdk): default-off auto file upload/download; add dangerouslyAllowAutoUploadDownloadFiles (#3260)
Musthaq Ahamadebc977859573
diff --git a/.changeset/fluffy-kids-lose.md b/.changeset/fluffy-kids-lose.mdnew file mode 100644index 000000000..9403e940e--- /dev/null+++ b/.changeset/fluffy-kids-lose.md@@ -0,0 +1,16 @@+---+'@composio/core': minor+---++Make automatic file upload/download opt-in and add scoped allowlist controls.++- **Removed:** the legacy `autoUploadDownloadFiles` constructor option. Code that sets it must migrate to the new opt-in flag.+- **Added:** `dangerouslyAllowAutoUploadDownloadFiles` (default `false`). When `true`, the SDK collapses `file_uploadable` schemas to `{ type: 'string', format: 'path' }` for the model and stages local paths/URLs at execute time.+- **Added:** `fileUploadDirs?: string[] | false` — fail-closed allowlist for local upload paths. `undefined` defaults to `[<home>/.composio/temp]`; `false` rejects all local paths; an explicit `string[]` replaces the default.+- **Added:** `fileDownloadDir?: string` — directory used to stage S3 downloads on `file_downloadable` results.+- **Added:** `beforeFileUpload` modifier now receives `source: 'path' | 'url' | 'file'` so hooks can branch on the original input type.+- **Added:** when auto-upload is **off** but a tool with `file_uploadable` inputs is executed, the SDK emits a one-shot warning per tool slug pointing at `composio.files.upload()` for manual staging.++See the changelog entry at [`docs/content/changelog/04-24-26-legacy-auto-upload-config-removal.mdx`](https://github.com/ComposioHQ/composio/blob/master/docs/content/changelog/04-24-26-legacy-auto-upload-config-removal.mdx) for migration steps.++Provider packages that depend on `@composio/core` receive automatic patch bumps in the same release train via the changesets `updateInternalDependencies: "patch"` setting — no public-API change in those packages.diff --git a/docs/content/changelog/01-29-26-sdk-major-update.mdx b/docs/content/changelog/01-29-26-sdk-major-update.mdxindex cdacb2e9a..02c7d15f3 100644--- a/docs/content/changelog/01-29-26-sdk-major-update.mdx+++ b/docs/content/changelog/01-29-26-sdk-major-update.mdx@@ -242,6 +242,10 @@ Changed the `autoUploadDownloadFiles` default configuration for the Cloudflare W}```+<Callout type="warn">+**Removed in a later release.** The `autoUploadDownloadFiles` flag described above was removed in the v0.7.0 / Python v0.12.0 release train. Automatic file handling is now off by default on every runtime, and you opt in with `dangerouslyAllowAutoUploadDownloadFiles` instead. See [SDKs remove legacy automatic file handling config](/docs/changelog/2026/04/24) for the full migration.+</Callout>+**Benefits:**- **Zero config** for common use casesdiff --git a/docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdx b/docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdxindex c39cbcc61..ed8b88f4d 100644--- a/docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdx+++ b/docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdx@@ -23,6 +23,7 @@ Custom tools support three patterns — standalone tools for internal logic, ext<Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";import { z } from "zod/v3";// ---cut---diff --git a/docs/content/changelog/04-07-26-bearer-token-patch.mdx b/docs/content/changelog/04-07-26-bearer-token-patch.mdxindex b428dfa4e..e450cb750 100644--- a/docs/content/changelog/04-07-26-bearer-token-patch.mdx+++ b/docs/content/changelog/04-07-26-bearer-token-patch.mdx@@ -29,6 +29,7 @@ See the [importing connections guide](/docs/importing-existing-connections) forNew `PATCH /api/v3/connected_accounts/{nanoid}` endpoint and SDK method — update credentials and alias on existing connections without recreating them.```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });// ---cut---diff --git a/docs/content/changelog/04-09-26-multi-account-aliases.mdx b/docs/content/changelog/04-09-26-multi-account-aliases.mdxindex ec027d88d..290b3c911 100644--- a/docs/content/changelog/04-09-26-multi-account-aliases.mdx+++ b/docs/content/changelog/04-09-26-multi-account-aliases.mdx@@ -11,6 +11,7 @@ This release adds two features for managing multiple accounts per toolkit.Sessions now support a `multiAccount` config that lets users connect and use multiple accounts for the same toolkit (e.g., work and personal Gmail) within a single session.```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -30,6 +31,7 @@ By default, multi-account mode is disabled and each session uses one account perConnected accounts can now have human-readable aliases (e.g., `"work-gmail"`, `"personal-github"`). Aliases can be set during connection or updated after.```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create('user_123');diff --git a/docs/content/changelog/04-24-26-legacy-auto-upload-config-removal.mdx b/docs/content/changelog/04-24-26-legacy-auto-upload-config-removal.mdxnew file mode 100644index 000000000..7478fb498--- /dev/null+++ b/docs/content/changelog/04-24-26-legacy-auto-upload-config-removal.mdx@@ -0,0 +1,156 @@+---+title: 'SDKs remove legacy automatic file handling config'+description: 'SDKs remove deprecated `autoUploadDownloadFiles` / `auto_upload_download_files`. Automatic file handling is off unless you set `dangerouslyAllowAutoUploadDownloadFiles` / `dangerously_allow_auto_upload_download_files`. Minor releases.'+date: '2026-04-24'+---++The Composio SDKs no longer accept the legacy flags that previously controlled automatic file upload and download during tool execution. Automatic handling of `file_uploadable` fields stays **off by default**; you opt in with the explicit `dangerously*` option only.++<Callout type="warn">+**Breaking change**++Those legacy properties are removed from the public constructors and config types. Code that still passes them must migrate. Anyone who **relied on the old default-on behavior** (no file flag in the constructor) must now **explicitly** set the `dangerously*` flag to `true` to keep automatic path/URL file handling.+</Callout>++### SDK versions (minor releases)++| Package | Previous | This release |+| ------- | -------- | ------------ |+| TypeScript `@composio/core` | v0.6.11 | **v0.7.0** |+| Python `composio` | v0.11.6 | **v0.12.0** |++Other `@composio/*` npm packages that depend on core are published as **patch** bumps in the same release train (via the changesets `updateInternalDependencies: "patch"` setting) so they pick up the updated `ComposioConfig` surface — they have no public-API changes of their own.++### Migration++Earlier SDK versions treated automatic file upload/download for `file_uploadable` tool fields as **on by default** (TypeScript: `autoUploadDownloadFiles` defaulted to `true` when unset; Python followed the same idea for `auto_upload_download_files` in prior releases). **That default is now off.** If you still want that behavior, you must **explicitly** set `dangerouslyAllowAutoUploadDownloadFiles: true` (TypeScript) or `dangerously_allow_auto_upload_download_files=True` (Python).++**TypeScript — before (legacy):**++```typescript+// @noErrors+// If you omitted autoUploadDownloadFiles, it used to default to true+new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+});++// Equivalent when you set it explicitly:+new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ autoUploadDownloadFiles: true,+});+```++**TypeScript — going forward** (set `true` to match either legacy pattern above):++```typescript+// @noErrors+new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+});+```++To leave automatic file handling **off** (new default), omit `dangerouslyAllowAutoUploadDownloadFiles` or set it to `false`.++**Python — before (legacy):**++```python+# If you omitted auto_upload_download_files, it used to default to True (prior releases)+Composio(api_key="...")++# Equivalent when you set it explicitly:+Composio(api_key="...", auto_upload_download_files=True)+```++**Python — going forward** (set `True` to match either legacy pattern above):++```python+Composio(api_key="...", dangerously_allow_auto_upload_download_files=True)+```++If you construct `ToolRouterSession` directly (unusual), the keyword argument is now `dangerously_allow_auto_upload_download_files` instead of `auto_upload_download_files`.++### Local paths must live inside an allowlisted directory++Even with `dangerouslyAllowAutoUploadDownloadFiles` enabled, the SDK will **only** auto-upload local file paths that resolve inside an allowlisted directory. Paths outside the allowlist are rejected with `ComposioFileUploadPathNotAllowed` (TypeScript) / `FileUploadPathNotAllowed` (Python) before any file is read or sent.++This is a behavior change. Earlier SDK versions had no allowlist: any local path the legacy default-on flag saw was uploaded.++**Default allowlist:**++| `fileUploadDirs` value | Effective allowlist |+| ---------------------- | ------------------- |+| omitted / `undefined` | `[ <home>/.composio/temp ]` (default staging dir) |+| `false` | `[]` — **all** local paths rejected (URLs and `File` objects still work) |+| `[]` | `[]` — same as `false`; explicit "no local paths" |+| `[<dir1>, <dir2>, …]` | exactly those directories (replaces the default; `~` is expanded, paths are `realpath`-resolved, comparison is on a path-component boundary) |++URLs (`http://…` / `https://…`) and JavaScript `File` objects are **not** subject to the allowlist — only local string paths are.++**TypeScript:**++```typescript+// @noErrors+// Match the *broadest* legacy behavior: auto-upload on, allowlist widened to+// the directories your code actually reads from. Set this scope as tightly+// as you can — every path inside these dirs becomes uploadable to Composio.+new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: ['/srv/uploads', '~/data/inbox'],+});++// Disallow local-path uploads entirely; the SDK will only stage URLs and+// File objects, and reject string paths outright.+new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: false,+});+```++**Python:**++```python+# Equivalent of the TypeScript example above.+Composio(+ api_key="...",+ dangerously_allow_auto_upload_download_files=True,+ file_upload_dirs=["/srv/uploads", "~/data/inbox"],+)++# Reject all local paths.+Composio(+ api_key="...",+ dangerously_allow_auto_upload_download_files=True,+ file_upload_dirs=False,+)+```++**Manual staging (TypeScript only):**++If you don't want to widen the allowlist, the TypeScript SDK lets you stage files yourself via `composio.files.upload(...)`. That call **bypasses the allowlist** by design (the caller is expected to control the path), and the returned `{ name, mimetype, s3key }` descriptor can be passed straight into `tools.execute`:++```typescript+// @noErrors+const staged = await composio.files.upload({+ file: '/anywhere/on/disk/report.pdf',+ toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE',+ toolkitSlug: 'googledrive',+});++await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {+ userId: 'user-1',+ arguments: { file_to_upload: staged },+});+```++The Python SDK does not currently expose a top-level manual-staging API; opt in with `dangerously_allow_auto_upload_download_files=True` and configure `file_upload_dirs` to cover the directories your code reads from.++### What else changed++- TypeScript: `resolveAutoUploadDownloadFilesEnabled` only considers `dangerouslyAllowAutoUploadDownloadFiles`; the old deprecation warning for the legacy property is removed.+- Python: the small `composio.utils.auto_upload_download` helper that merged legacy + new flags is removed; `Tools` and `ToolRouter` take only the explicit opt-in boolean.++Documentation for [executing tools](/docs/tools-direct/executing-tools) and the TypeScript [Composio reference](/reference/sdk-reference/typescript/composio) is updated to describe defaults and the opt-in flag.diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdxindex 04b7c29ad..feddf4e6d 100644--- a/docs/content/docs/configuring-sessions.mdx+++ b/docs/content/docs/configuring-sessions.mdx@@ -14,6 +14,7 @@ session = composio.create(user_id="user_123")</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -48,6 +49,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -79,6 +81,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -107,6 +110,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -140,6 +144,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -182,6 +187,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -213,6 +219,7 @@ mcp_url = session.mcp.url</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123");@@ -237,6 +244,7 @@ tools = session.tools()</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123");@@ -262,6 +270,7 @@ connected_account = connection_request.wait_for_connection()</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123");@@ -295,6 +304,7 @@ for toolkit in toolkits.items:</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123");diff --git a/docs/content/docs/importing-existing-connections.mdx b/docs/content/docs/importing-existing-connections.mdxindex 0f998fc70..29c1cb22d 100644--- a/docs/content/docs/importing-existing-connections.mdx+++ b/docs/content/docs/importing-existing-connections.mdx@@ -52,6 +52,7 @@ print(f"Connected: {connection.id}")</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, AuthScheme } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });@@ -102,6 +103,7 @@ print(f"Connected: {connection.id}")</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, AuthScheme } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });@@ -147,6 +149,7 @@ print(f"Connected: {connection.id}")</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, AuthScheme } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });@@ -190,6 +193,7 @@ composio.connected_accounts.update(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });// ---cut---@@ -230,6 +234,7 @@ composio.connected_accounts.update(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });// ---cut---@@ -270,6 +275,7 @@ composio.connected_accounts.update(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });// ---cut---@@ -311,6 +317,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });// ---cut---diff --git a/docs/content/docs/managing-multiple-connected-accounts.mdx b/docs/content/docs/managing-multiple-connected-accounts.mdxindex d5270d230..bf49b376f 100644--- a/docs/content/docs/managing-multiple-connected-accounts.mdx+++ b/docs/content/docs/managing-multiple-connected-accounts.mdx@@ -25,6 +25,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -71,6 +72,7 @@ personal_connection = personal_auth.wait_for_connection()</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -128,6 +130,7 @@ connection_request = composio.connected_accounts.link(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123");@@ -166,6 +169,7 @@ composio.connected_accounts.update("ca_abc123", alias="")</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -196,6 +200,7 @@ session = composio.create(</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -225,6 +230,7 @@ for toolkit in toolkits.items:</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123");diff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdxindex 7f89d7983..e4d57f87c 100644--- a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx@@ -49,6 +49,7 @@ pip install composio<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });@@ -72,6 +73,7 @@ A standalone tool handles internal app logic that doesn't need Composio auth. `c<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createTool } from "@composio/core";import { z } from "zod/v3";// ---cut---@@ -132,6 +134,7 @@ Pass custom tools via the `experimental` option. `session.tools()` returns both<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createTool } from "@composio/core";import { z } from "zod/v3";@@ -194,6 +197,7 @@ pip install composio<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });@@ -219,6 +223,7 @@ Prefer relative `endpoint` values in proxy calls. They resolve against the toolk<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createTool } from "@composio/core";import { z } from "zod/v3";// ---cut---@@ -298,6 +303,7 @@ Pass custom tools via the `experimental` option. Extension tools inherit auth fr<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createTool } from "@composio/core";import { z } from "zod/v3";@@ -362,6 +368,7 @@ pip install composio<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });@@ -385,6 +392,7 @@ A custom toolkit groups related standalone tools under a namespace. Tools inside<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core";import { z } from "zod/v3";// ---cut---@@ -443,6 +451,7 @@ Pass custom toolkits via the `experimental` option. `session.tools()` returns bo<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio, experimental_createToolkit } from "@composio/core";import { z } from "zod/v3";@@ -531,6 +540,7 @@ Use these methods to list registered tools and toolkits. Slugs include their fin<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });const session = await composio.create("user_1");@@ -554,6 +564,7 @@ Use `session.execute()` to run custom tools directly, outside of an agent loop.<Tabs groupId="language" items={['TypeScript', 'Python']} persist><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });const session = await composio.create("user_1");diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdxindex 380b0fa06..5ff605929 100644--- a/docs/content/docs/tools-direct/executing-tools.mdx+++ b/docs/content/docs/tools-direct/executing-tools.mdx@@ -312,7 +312,7 @@ Need an API that isn't supported by any Composio toolkit, or want to extend an e## Automatic File Handling-Composio handles file operations automatically. Pass file paths to tools that need them, and get local file paths back from tools that return files.+Automatic file handling is **off by default**. Enable it with `dangerouslyAllowAutoUploadDownloadFiles: true` (TypeScript) or `dangerously_allow_auto_upload_download_files=True` (Python). Once enabled, pass file paths to tools that accept files and get local paths back from tools that return files.### File Upload@@ -321,6 +321,11 @@ Pass local file paths, URLs, or File objects to tools that accept files:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python+composio = Composio(+ api_key="your_composio_key",+ dangerously_allow_auto_upload_download_files=True,+)+# Upload a local file to Google Driveresult = composio.tools.execute(slug="GOOGLEDRIVE_UPLOAD_FILE",@@ -333,9 +338,13 @@ print(result) # Print Google Drive file details</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';import path from 'path';-const composio = new Composio({ apiKey: 'your_api_key' });+const composio = new Composio({+ apiKey: 'your_api_key',+ dangerouslyAllowAutoUploadDownloadFiles: true,+});// ---cut---// Upload a local file to Google Driveconst result = await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {@@ -359,7 +368,8 @@ When tools return files, Composio downloads them to the local directory and prov```pythoncomposio = Composio(api_key="your_composio_key",- file_download_dir="./downloads" # Optional: Specify download directory+ dangerously_allow_auto_upload_download_files=True,+ file_download_dir="./downloads", # Optional: Specify download directory)result = composio.tools.execute(@@ -374,8 +384,12 @@ print(result)</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';-const composio = new Composio({ apiKey: 'your_api_key' });+const composio = new Composio({+ apiKey: 'your_api_key',+ dangerouslyAllowAutoUploadDownloadFiles: true,+});// ---cut---// Download a file from Google Driveconst result = await composio.tools.execute('GOOGLEDRIVE_DOWNLOAD_FILE', {@@ -438,7 +452,13 @@ composio = Composio(import { Composio, type beforeFileUploadModifier } from '@composio/core';import path from 'node:path';const composio = new Composio({ apiKey: 'your_api_key' });-const beforeFileUpload: beforeFileUploadModifier = async ctx => ctx.path;+// ctx.source is 'path' | 'url' | 'file' — useful if you only want to audit+// local paths and let URLs / File objects pass through unchanged.+const beforeFileUpload: beforeFileUploadModifier = async ctx => {+ if (ctx.source !== 'path') return ctx.path;+ // ...audit ctx.path...+ return ctx.path;+};// ---cut---await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE',@@ -456,9 +476,14 @@ await composio.tools.execute(import osfrom composio import Composio, before_file_upload+# New form: take a single ``context`` arg; ``context["source"]`` is "path"+# or "url". The legacy ``(path, tool, toolkit)`` 3-arg form is still accepted.@before_file_upload(tools=["GOOGLEDRIVE_UPLOAD_FILE"])-def audit_path(path: str, tool: str, toolkit: str) -> str | bool:- return path+def audit_path(ctx) -> str | bool:+ if ctx["source"] != "path":+ return ctx["path"]+ # ...audit ctx["path"]...+ return ctx["path"]composio = Composio()@@ -474,9 +499,40 @@ composio.tools.execute(**Errors:** `ComposioSensitiveFilePathBlockedError` / `SensitiveFilePathBlockedError` when a path is blocked; `ComposioFileUploadAbortedError` / `FileUploadAbortedError` when the hook returns `false` (or equivalent abort).-### Disabling Auto File Handling+### Automatic file handling (off by default)++Both SDKs ship with automatic file handling **off**. Opt in with `dangerouslyAllowAutoUploadDownloadFiles: true` (TypeScript) or `dangerously_allow_auto_upload_download_files=True` (Python). Even with the flag enabled, **local paths must resolve inside an allowlisted directory** — see the matrix in the [legacy auto-upload removal changelog](/docs/changelog/2026/04/24) for the full `fileUploadDirs` / `file_upload_dirs` semantics.++When auto-handling is off, handle the staging yourself.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+The Python SDK does not expose a top-level manual-staging API. Either:++1. Enable auto-handling and configure `file_upload_dirs` to cover the directories your code reads from:++```python+from composio import Composio++composio = Composio(+ api_key="your_composio_key",+ dangerously_allow_auto_upload_download_files=True,+ file_upload_dirs=["/srv/agent/uploads", "~/.composio/temp"],+)+```-You can disable automatic file handling when initializing the TypeScript SDK. When disabled, handle file uploads and downloads manually using `files.upload` and `files.download`:+2. Or keep auto-handling off and pass an already-staged `{ "name", "mimetype", "s3key" }` dict directly into `tools.execute`. Pre-stage your files via your own pipeline (or an upstream tool) and inject the descriptor:++```python+result = composio.tools.execute(+ "GOOGLEDRIVE_UPLOAD_FILE",+ user_id="user-1",+ arguments={"file_to_upload": prestaged_descriptor},+)+```+ </Tab>+ <Tab value="TypeScript">+With `dangerouslyAllowAutoUploadDownloadFiles: false` (the default), call `composio.files.upload(...)` to stage paths/URLs explicitly. That call bypasses `fileUploadDirs` by design — the caller controls the path:```typescriptimport { Composio } from '@composio/core';@@ -484,16 +540,24 @@ import path from 'path';// ---cut---const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,- autoUploadDownloadFiles: false+ // Default: dangerouslyAllowAutoUploadDownloadFiles is false; set true only to opt in});-// Now you need to handle files manually using composio.files API+// Stage manually using composio.files APIconst fileData = await composio.files.upload({file: path.join(__dirname, 'document.pdf'),toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE',toolkitSlug: 'googledrive'});++// Then pass the { name, mimetype, s3key } descriptor into tools.execute+await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {+ userId: 'user-1',+ arguments: { file_to_upload: fileData },+});```+ </Tab>+</Tabs>## What to read nextdiff --git a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdxindex cc761c650..278561ca4 100644--- a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx+++ b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx@@ -184,13 +184,21 @@ For tools with `file_uploadable` parameters, the SDK can read a local path and uSee [Executing tools: security for local file paths](/docs/tools-direct/executing-tools#security-for-local-file-paths) for constructor options, errors, and a full tabbed example.+The hook takes either a single `context` argument (preferred) or the legacy+3-arg `(path, tool, toolkit)` form. The context object exposes+`context["source"]` — `"path"` for local filesystem inputs and `"url"` for+`http(s)://...` inputs — so you can scope audits to just local paths:+```pythonfrom composio import Composio, before_file_upload@before_file_upload(tools=["GOOGLEDRIVE_UPLOAD_FILE"])-def audit_path(path: str, tool: str, toolkit: str) -> str | bool:+def audit_path(ctx) -> str | bool:+ # ctx = {"path": ..., "source": "path" | "url", "tool": ..., "toolkit": ...}+ if ctx["source"] != "path":+ return ctx["path"] # let URLs through untouched# return a new path string, or False to abort the upload- return path+ return ctx["path"]composio = Composio()composio.tools.execute(diff --git a/docs/content/reference/sdk-reference/python/composio.mdx b/docs/content/reference/sdk-reference/python/composio.mdxindex 965b8602e..0c02f909e 100644--- a/docs/content/reference/sdk-reference/python/composio.mdx+++ b/docs/content/reference/sdk-reference/python/composio.mdx@@ -15,3 +15,95 @@ description: "Composio SDK for Python. Generic parameters: TTool: The individua| [`mcp`](/reference/sdk-reference/python/mcp) | `MCP` |[View source](https://github.com/composiohq/composio/blob/next/python/composio/sdk.py#L46)++---++## Constructor++```python+Composio(+ provider: BaseProvider | None = None,+ *,+ api_key: str | None = None,+ base_url: str | None = None,+ timeout: int | None = None,+ max_retries: int | None = None,+ toolkit_versions: dict[str, str] | str | None = None,+ dangerously_allow_auto_upload_download_files: bool = False,+ sensitive_file_upload_protection: bool = True,+ file_upload_path_deny_segments: Sequence[str] | None = None,+ file_upload_dirs: Sequence[str] | Literal[False] | None = None,+ file_download_dir: str | None = None,+ allow_tracking: bool = True,+ environment: str = "production",+)+```++`api_key` falls back to `os.environ["COMPOSIO_API_KEY"]` when not passed.++### Common options++| Option | Type | Default | Description |+|--------|------|---------|-------------|+| `provider` | `BaseProvider` | `OpenAIProvider()` | Provider used to wrap tools (Anthropic, LangChain, Gemini, etc.). |+| `api_key` | `str` | `$COMPOSIO_API_KEY` | API key. Required. |+| `base_url` | `str` | Composio default | Override the API base URL. |+| `timeout` | `int` | client default | Per-request timeout in seconds. |+| `max_retries` | `int` | `3` | HTTP client retry count. |+| `toolkit_versions` | `dict \| str \| None` | `'latest'` | Pin toolkit versions globally (string) or per-toolkit (dict). |++---++## File upload security++Automatic file handling for `file_uploadable` tool fields is **off by default**. Set `dangerously_allow_auto_upload_download_files=True` to opt in. Once on, the SDK can read local paths and stage them to S3 on your behalf, but only from an allowlisted set of directories.++| Option | Type | Default | Description |+|--------|------|---------|-------------|+| `dangerously_allow_auto_upload_download_files` | `bool` | `False` | Master opt-in. When `False`, paths and URLs in `file_uploadable` arguments are forwarded as-is — the backend will reject anything that isn't already a staged `{name, mimetype, s3key}` descriptor. Set to `True` to let the SDK stage local paths and URLs on your behalf at execute time. |+| `sensitive_file_upload_protection` | `bool` | `True` | Block local paths matching a built-in denylist of segments (`.ssh`, `.aws`, etc.) and credential-like file names. Disable only if you accept the tradeoff. |+| `file_upload_path_deny_segments` | `Sequence[str] \| None` | `None` | Extra single path components merged with the built-in denylist. |+| `file_upload_dirs` | `Sequence[str] \| Literal[False] \| None` | `[~/.composio/temp]` | Allowlist of directories the SDK may read during **automatic** upload. Pass `False` (or `[]`) to reject every local path — URLs still work. Providing a list **replaces** the default; include `~/.composio/temp` explicitly if you want the default staging dir to keep working. Comparison is on a path-component boundary after `os.path.realpath`. On Windows, entries are compared case-insensitively. |+| `file_download_dir` | `str \| None` | `~/.composio/files` | Directory where files from tool responses marked `file_downloadable` are streamed. |++Per-execution hooks live on the `modifiers=[...]` argument to `composio.tools.execute`, not on the constructor. Use the `@before_file_upload` decorator from `composio.core.models._modifiers` to inspect or rewrite each path before it is read. The hook context includes a `source` field (`'path' | 'url'`) so you can branch on local paths vs URLs.++**Related errors:** `FileUploadPathNotAllowed`, `SensitiveFilePathBlocked`, `FileUploadAbortedError`, `SDKFileNotFoundError` (all from `composio.exceptions`).++### Restricting automatic uploads to specific directories++When `dangerously_allow_auto_upload_download_files=True`, the SDK only reads local files from directories listed in `file_upload_dirs`. This stacks with (it does NOT replace) the sensitive-path denylist.++```python+from composio import Composio++composio = Composio(+ api_key="your_composio_key",+ dangerously_allow_auto_upload_download_files=True,+ # Replaces the default `[~/.composio/temp]`. List every directory you want+ # the SDK to read from during tool execution.+ file_upload_dirs=["/srv/agent/uploads", "~/.composio/temp"],+)+```++Pass `file_upload_dirs=False` (or `[]`) to reject every filesystem path; URLs and in-memory bytes still upload normally:++```python+Composio(+ api_key="your_composio_key",+ dangerously_allow_auto_upload_download_files=True,+ file_upload_dirs=False,+)+```++### Tool-Router session files++The Tool-Router session API exposes a separate files surface (`session.files.upload(...)` / `session.files.download(...)`) for streaming files into and out of a long-running router session. Those calls are unrelated to the `file_uploadable` schema flow on individual tool execution and are not gated by `dangerously_allow_auto_upload_download_files` or `file_upload_dirs`. See [`tool-router-session`](/reference/sdk-reference/python/tool-router-session) for usage.++---++## See also++- [Executing tools](/docs/tools-direct/executing-tools) — automatic vs. manual file handling, before-execute modifiers.+- [Before-execution modifiers](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers#before-file-upload-python) — `@before_file_upload` decorator and the context-form hook signature.+- [Legacy auto-upload config removal changelog](/docs/changelog/2026/04/24) — migration from the removed `auto_upload_download_files` flag and the allowlist semantics matrix.diff --git a/docs/content/reference/sdk-reference/typescript/composio.mdx b/docs/content/reference/sdk-reference/typescript/composio.mdxindex 196557c70..5cef39db5 100644--- a/docs/content/reference/sdk-reference/typescript/composio.mdx+++ b/docs/content/reference/sdk-reference/typescript/composio.mdx@@ -180,15 +180,39 @@ getConfig(): ComposioConfig## File upload security-When `autoUploadDownloadFiles` is true (default), the SDK can read local file paths and upload them before tool execution. The constructor accepts options that work together with the optional `beforeFileUpload` modifier on `tools.execute` (see [Executing tools: security](/docs/tools-direct/executing-tools#security-for-local-file-paths)).+When `dangerouslyAllowAutoUploadDownloadFiles` is true, the SDK can read local file paths and upload them before tool execution (this behavior is **off** by default). The constructor accepts options that work together with the optional `beforeFileUpload` modifier on `tools.execute` (see [Executing tools: security](/docs/tools-direct/executing-tools#security-for-local-file-paths)).| Option | Type | Default | Description ||--------|------|---------|-------------|| `sensitiveFileUploadProtection` | `boolean` | `true` | When true, local path strings for auto-upload and `files.upload` are checked against a built-in denylist of path segments (for example `.ssh`, `.aws`) and credential-like file names. Set to `false` only if you accept the security tradeoff. || `fileUploadPathDenySegments` | `string[]` | `undefined` | Additional single path *components* (directory or file names) merged with the built-in list; matched anywhere in the resolved path. |+| `fileUploadDirs` | `string[] \| false` | `[~/.composio/temp]` | Allowlist of directories the SDK may read during **automatic** upload (when `dangerouslyAllowAutoUploadDownloadFiles: true`). Pass `false` (or `[]`) to reject every local path; URLs and `File`/`Blob` objects still work. Providing a list **replaces** the default — include `~/.composio/temp` explicitly if you want the default staging dir to keep working. Does **not** affect manual `composio.files.upload()` calls. |+| `fileDownloadDir` | `string` | `~/.composio/files` | Directory where files from tool responses marked `file_downloadable` are streamed. |-Pass **`beforeFileUpload`** on the **third argument** to `composio.tools.execute` (with `beforeExecute` / `afterExecute`), not on the constructor. The hook runs for each `file_uploadable` value before read/upload: return a path string, `false` to abort, or throw.+Pass **`beforeFileUpload`** on the **third argument** to `composio.tools.execute` (with `beforeExecute` / `afterExecute`), not on the constructor. The hook runs for each `file_uploadable` value before read/upload: return a path string, `false` to abort, or throw. The hook's context includes a `source` field (`'path' | 'url' | 'file'`) so it can scope its logic to local paths vs URLs vs `File` objects.-**Related errors:** `ComposioSensitiveFilePathBlockedError`, `ComposioFileUploadAbortedError` (from `@composio/core`).+**Related errors:** `ComposioSensitiveFilePathBlockedError`, `ComposioFileUploadAbortedError`, `ComposioFileUploadPathNotAllowedError`, `ComposioFileNotFoundError` (from `@composio/core`).++### Restricting automatic uploads to specific directories++When `dangerouslyAllowAutoUploadDownloadFiles: true`, the SDK only reads local+files from directories in `fileUploadDirs`. This stacks with (it does NOT+replace) the sensitive-path denylist.++```typescript+// @noErrors+import { Composio } from '@composio/core';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ // Replaces the default `[~/.composio/temp]`. List every directory you want+ // the SDK to read from during tool execution.+ fileUploadDirs: ['/srv/agent/uploads', '~/.composio/temp'],+});+```++Pass `fileUploadDirs: false` (or `[]`) to reject every filesystem path; URLs+and in-memory `File`/`Blob` objects still upload normally.---diff --git a/docs/examples/chat-app/page-with-tools.tsx b/docs/examples/chat-app/page-with-tools.tsxindex 704b32b73..700c87541 100644--- a/docs/examples/chat-app/page-with-tools.tsx+++ b/docs/examples/chat-app/page-with-tools.tsx@@ -1,4 +1,4 @@-// @errors: 2307+// @noErrors"use client";import { useState } from "react";diff --git a/docs/examples/chat-app/page.tsx b/docs/examples/chat-app/page.tsxindex dbc7d5dd1..691e4a49b 100644--- a/docs/examples/chat-app/page.tsx+++ b/docs/examples/chat-app/page.tsx@@ -1,3 +1,4 @@+// @noErrors"use client";import { useState } from "react";diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.pyindex 26ebf9914..bef1095b6 100644--- a/python/composio/core/models/_files.py+++ b/python/composio/core/models/_files.py@@ -26,10 +26,14 @@ from composio.utils import mimetypesfrom composio.utils.sensitive_file_upload_paths import (assert_safe_local_file_upload_path,)+from composio.utils.upload_dir_allowlist import (+ assert_path_inside_upload_dirs,+)from composio.utils.logging import WithLoggerif t.TYPE_CHECKING:from .tools import ToolExecutionResponse+ from ._modifiers import BeforeFileUploadContextCallable # noqa: F401_DEFAULT_CHUNK_SIZE = 1024 * 1024_FILE_UPLOAD = "/api/v3/files/upload/request"@@ -86,9 +90,12 @@ except OSError as e:) from e-LOCAL_OUTPUT_FILE_DIRECTORY = LOCAL_CACHE_DIRECTORY / "outputs"+LOCAL_OUTPUT_FILE_DIRECTORY = LOCAL_CACHE_DIRECTORY / "files""""-Local output file directory name for composio tools+Default local directory into which files downloaded during tool execution are+written. Previously ``<cache>/outputs``; now ``<cache>/files`` for parity with+the TypeScript SDK. Override by passing ``file_download_dir=...`` to Composio,+or by setting ``outdir`` on ``FileHelper`` directly."""@@ -106,7 +113,11 @@ def get_md5(file: Path) -> str:Returns:Hexadecimal MD5 hash string"""- obj = hashlib.md5()+ # `usedforsecurity=False` lets this run on FIPS-mode systems, where+ # `hashlib.md5()` without the flag raises `ValueError: [digital envelope+ # routines] unsupported`. We're hashing for integrity / deduplication,+ # not security — the API just needs the digest for upload verification.+ obj = hashlib.md5(usedforsecurity=False)with file.open("rb") as fp:while True:line = fp.read(_DEFAULT_CHUNK_SIZE)@@ -345,7 +356,7 @@ def _upload_bytes_to_s3(toolkit: str,) -> str:"""Upload bytes content to S3 and return the S3 key."""- md5_hash = hashlib.md5(content).hexdigest()+ md5_hash = hashlib.md5(content, usedforsecurity=False).hexdigest()s3meta = client.post(path=_FILE_UPLOAD,@@ -423,9 +434,8 @@ class FileUploadable(BaseModel):*,sensitive_file_upload_protection: bool = True,file_upload_path_deny_segments: t.Optional[t.Sequence[str]] = None,- before_file_upload: t.Optional[- t.Callable[[str, str, str], t.Union[str, bool]]- ] = None,+ file_upload_allowlist: t.Optional[t.Sequence[Path]] = None,+ before_file_upload: t.Optional["BeforeFileUploadContextCallable"] = None,) -> te.Self:"""Create a FileUploadable from a local file path or public URL.@@ -439,27 +449,34 @@ class FileUploadable(BaseModel)::param toolkit: The toolkit slug:param sensitive_file_upload_protection: When True, block paths on the built-in denylist.:param file_upload_path_deny_segments: Extra path segment names to merge with the built-in list.- :param before_file_upload: Optional ``(path, tool, toolkit) -> str | bool``; return a new path string, or False to abort.+ :param file_upload_allowlist: When provided (not None), local paths must+ resolve inside one of these directories on a component boundary.+ Pass ``None`` to skip the check (e.g. manual upload APIs). URLs are+ never checked against the allowlist. An empty sequence means+ "no paths are allowed" (fail-closed).+ :param before_file_upload: Optional context-form hook produced by+ :func:`composio.core.models._modifiers.merge_before_file_upload`.+ Receives ``{"path", "source", "tool", "toolkit"}`` where ``source``+ is ``"url"`` for ``http(s)://...`` inputs and ``"path"`` for local+ filesystem paths. Return a new string to substitute, or ``False``+ to abort.:return: FileUploadable instance with S3 key"""file_str = str(file) if isinstance(file, Path) else file-- # Check if it's a URL- if isinstance(file_str, str) and _is_url(file_str):- path_in = file_str- if before_file_upload is not None:- out = before_file_upload(path_in, tool, toolkit)- if out is False:- raise FileUploadAbortedError(- "File upload was aborted because before_file_upload returned False."- )- if isinstance(out, str):- path_in = out- return cls.from_url(client=client, url=path_in, tool=tool, toolkit=toolkit)-path_in = file_str+ source: t.Literal["url", "path"] = (+ "url" if isinstance(file_str, str) and _is_url(file_str) else "path"+ )+if before_file_upload is not None:- out = before_file_upload(path_in, tool, toolkit)+ out = before_file_upload(+ {+ "path": path_in,+ "source": source,+ "tool": tool,+ "toolkit": toolkit,+ }+ )if out is False:raise FileUploadAbortedError("File upload was aborted because before_file_upload returned False."@@ -467,6 +484,21 @@ class FileUploadable(BaseModel):if isinstance(out, str):path_in = out+ # Re-decide routing on the post-hook value: a URL-source hook may return+ # a local path (and vice versa). Re-checking with `_is_url` keeps the+ # URL fetch path and the local-file path properly separated, so a hook+ # cannot, for example, smuggle `/etc/passwd` past the URL branch's+ # missing allowlist/denylist by rewriting the URL into a path.+ if isinstance(path_in, str) and _is_url(path_in):+ return cls.from_url(client=client, url=path_in, tool=tool, toolkit=toolkit)++ # Allowlist check runs BEFORE the denylist / existence checks when enabled,+ # so the "configure file_upload_dirs" hint fires first for the common case+ # (user has auto-upload on but hasn't configured dirs). Caller passes+ # ``None`` to bypass the allowlist (manual upload APIs).+ if file_upload_allowlist is not None:+ assert_path_inside_upload_dirs(path_in, file_upload_allowlist)+assert_safe_local_file_upload_path(path_in,enabled=sensitive_file_upload_protection,@@ -527,7 +559,11 @@ class FileDownloadable(BaseModel):return outfile-BeforeFileUpload = t.Callable[[str, str, str], t.Union[str, bool]]+# Internal alias — ``FileHelper`` receives the already-adapted context-form+# callable produced by :func:`merge_before_file_upload`.+from composio.core.models._modifiers import ( # noqa: E402+ BeforeFileUploadContextCallable as BeforeFileUpload,+)class FileHelper(WithLogger):@@ -538,12 +574,24 @@ class FileHelper(WithLogger):*,sensitive_file_upload_protection: bool = True,file_upload_path_deny_segments: t.Optional[t.Sequence[str]] = None,+ file_upload_allowlist: t.Optional[t.Sequence[Path]] = None,) -> None:+ """+ :param outdir: Where files downloaded during tool execution are written.+ Defaults to ``~/.composio/files``.+ :param file_upload_allowlist: Directories from which local files may be+ auto-uploaded. ``None`` disables the allowlist check (used when+ auto-upload is off, or for manual upload APIs). An empty list means+ "no paths allowed" (fail-closed).+ """super().__init__()self._client = client- self._outdir = Path(outdir or LOCAL_OUTPUT_FILE_DIRECTORY)+ self._outdir = Path(outdir) if outdir else LOCAL_OUTPUT_FILE_DIRECTORYself._sensitive_file_upload_protection = sensitive_file_upload_protectionself._file_upload_path_deny_segments = file_upload_path_deny_segments+ self._file_upload_allowlist: t.Optional[t.Sequence[Path]] = (+ list(file_upload_allowlist) if file_upload_allowlist is not None else None+ )def _has_file_property(self, schema: t.Dict, property_name: str = "file_uploadable"@@ -672,7 +720,7 @@ class FileHelper(WithLogger):- Required notes ("This parameter is required.")This is separate from file processing and should always run- regardless of the auto_upload_download_files setting.+ regardless of `dangerously_allow_auto_upload_download_files`."""required = schema.get("required") or []for _param, _schema in schema["properties"].items():@@ -694,7 +742,8 @@ class FileHelper(WithLogger):"""Process file_uploadable fields in schema.This method converts file_uploadable fields to path format.- Should only be called when auto_upload_download_files is True.+ Should only be called when the caller opted in via+ `dangerously_allow_auto_upload_download_files=True`.Recursively handles anyOf, oneOf, allOf, nested properties, and array items."""if "properties" not in schema:@@ -770,6 +819,7 @@ class FileHelper(WithLogger):toolkit=tool.toolkit.slug,sensitive_file_upload_protection=self._sensitive_file_upload_protection,file_upload_path_deny_segments=self._file_upload_path_deny_segments,+ file_upload_allowlist=self._file_upload_allowlist,before_file_upload=before_file_upload,).model_dump()continue@@ -790,6 +840,7 @@ class FileHelper(WithLogger):toolkit=tool.toolkit.slug,sensitive_file_upload_protection=self._sensitive_file_upload_protection,file_upload_path_deny_segments=self._file_upload_path_deny_segments,+ file_upload_allowlist=self._file_upload_allowlist,before_file_upload=before_file_upload,).model_dump()continue@@ -841,6 +892,7 @@ class FileHelper(WithLogger):toolkit=tool.toolkit.slug,sensitive_file_upload_protection=self._sensitive_file_upload_protection,file_upload_path_deny_segments=self._file_upload_path_deny_segments,+ file_upload_allowlist=self._file_upload_allowlist,before_file_upload=before_file_upload,).model_dump())diff --git a/python/composio/core/models/_modifiers.py b/python/composio/core/models/_modifiers.pyindex 70ba1a5ea..7d1991195 100644--- a/python/composio/core/models/_modifiers.py+++ b/python/composio/core/models/_modifiers.py@@ -66,7 +66,12 @@ class SchemaModifier(t.Protocol):class BeforeFileUploadCallable(t.Protocol):- """Called for each local file path before read/upload (``file_uploadable``)."""+ """Legacy positional form of the ``before_file_upload`` hook.++ ``(path, tool, toolkit) -> str | bool``. Still supported for back-compat,+ but new code should use :class:`BeforeFileUploadContextCallable` so it can+ discriminate local paths from URLs via ``context["source"]``.+ """def __call__(self,@@ -76,6 +81,83 @@ class BeforeFileUploadCallable(t.Protocol):) -> t.Union[str, bool]: ...+class BeforeFileUploadContext(te.TypedDict):+ """Context passed to the new-form ``before_file_upload`` hook.++ - ``path``: the local filesystem path for ``source="path"``, or the URL+ string for ``source="url"``.+ - ``source``: discriminator — ``"path"`` for local paths, ``"url"`` for+ ``http(s)://...`` inputs. Mirrors the TypeScript SDK's ``source`` field+ (TS additionally emits ``"file"`` for ``File`` objects; Python has no+ equivalent runtime type).+ - ``tool`` / ``toolkit``: slugs of the tool being executed.+ """++ path: str+ source: te.Literal["path", "url"]+ tool: str+ toolkit: str+++class BeforeFileUploadContextCallable(t.Protocol):+ """Preferred form of the ``before_file_upload`` hook.++ Takes a single :class:`BeforeFileUploadContext` argument and returns either+ a new path/URL string, or ``False`` to abort the upload.+ """++ def __call__(+ self,+ context: BeforeFileUploadContext,+ ) -> t.Union[str, bool]: ...+++BeforeFileUploadLike = t.Union[+ BeforeFileUploadCallable,+ BeforeFileUploadContextCallable,+]+"""Either form of ``before_file_upload``. Adapted internally."""+++def _count_positional_params(fn: t.Callable) -> int:+ """Return the number of positional (or positional-or-keyword) params, or+ -1 if the signature can't be introspected (e.g. builtins)."""+ import inspect++ try:+ sig = inspect.signature(fn)+ except (TypeError, ValueError):+ return -1+ return sum(+ 1+ for p in sig.parameters.values()+ if p.kind+ in (+ inspect.Parameter.POSITIONAL_ONLY,+ inspect.Parameter.POSITIONAL_OR_KEYWORD,+ )+ )+++def _adapt_before_file_upload(+ hook: BeforeFileUploadLike,+) -> BeforeFileUploadContextCallable:+ """Normalise a user-supplied hook to the context-object form.++ A hook declared with exactly 3 positional parameters is treated as the+ legacy ``(path, tool, toolkit)`` form; anything else (typically a single+ positional ``context`` parameter) is treated as the new form.+ """+ if _count_positional_params(hook) == 3:+ legacy = t.cast(BeforeFileUploadCallable, hook)++ def wrap(context: BeforeFileUploadContext) -> t.Union[str, bool]:+ return legacy(context["path"], context["tool"], context["toolkit"])++ return wrap+ return t.cast(BeforeFileUploadContextCallable, hook)++ModifierSlug: t.TypeAlias = strAfterExecuteModifierL: t.TypeAlias = t.Literal["after_execute"]BeforeExecuteModifierL: t.TypeAlias = t.Literal["before_execute"]@@ -93,6 +175,7 @@ class Modifier:| BeforeExecuteMeta| AfterExecuteMeta| BeforeFileUploadCallable+ | BeforeFileUploadContextCallable],type_: (AfterExecuteModifierL@@ -222,7 +305,7 @@ def before_execute(@t.overload-def before_file_upload(modifier: t.Optional[BeforeFileUploadCallable]) -> Modifier: ...+def before_file_upload(modifier: t.Optional[BeforeFileUploadLike]) -> Modifier: ...@t.overload@@ -230,19 +313,30 @@ def before_file_upload(*,tools: t.Optional[t.List[str]] = None,toolkits: t.Optional[t.List[str]] = None,-) -> t.Callable[[BeforeFileUploadCallable], Modifier]: ...+) -> t.Callable[[BeforeFileUploadLike], Modifier]: ...def before_file_upload(- modifier: t.Optional[BeforeFileUploadCallable] = None,+ modifier: t.Optional[BeforeFileUploadLike] = None,*,tools: t.Optional[t.List[str]] = None,toolkits: t.Optional[t.List[str]] = None,-) -> Modifier | t.Callable[[BeforeFileUploadCallable], Modifier]:+) -> Modifier | t.Callable[[BeforeFileUploadLike], Modifier]:"""Build a ``Modifier`` for the file-upload hook (same scoping pattern as:func:`before_execute`).+ Your callable may take **either**:++ - a single ``context`` argument (:class:`BeforeFileUploadContext`) — the+ preferred form, exposes ``context["source"]`` (``"path"`` or ``"url"``),+ or+ - three positional arguments ``(path, tool, toolkit)`` — legacy form, kept+ for back-compat.++ Return a new path/URL string to substitute, or ``False`` to abort the+ upload (raises :class:`~composio.exceptions.FileUploadAbortedError`).+Pass the returned ``Modifier`` in ``modifiers=[...]`` on:meth:`composio.core.models.tools.Tools.execute` or ``tools.get``. Multiplesuch modifiers are composed in list order.@@ -257,7 +351,7 @@ def before_file_upload(if tools is not None or toolkits is not None:return t.cast(- t.Callable[[BeforeFileUploadCallable], Modifier],+ t.Callable[[BeforeFileUploadLike], Modifier],functools.partial(before_file_upload,tools=tools or [],@@ -392,10 +486,15 @@ def merge_before_file_upload(modifiers: t.Optional[Modifiers],tool: str,toolkit: str,-) -> t.Optional[BeforeFileUploadCallable]:+) -> t.Optional[BeforeFileUploadContextCallable]:"""Compose ``before_file_upload``-type :class:`Modifier`\\ s for this *tool* / *toolkit*.Scoping matches :class:`Modifier` (empty ``tools`` and ``toolkits`` = all tools).++ Each user-supplied hook is adapted to the context form by+ :func:`_adapt_before_file_upload`, so legacy 3-arg callables keep working+ while new-form callables receive the full :class:`BeforeFileUploadContext`+ (including ``source``)."""to_chain = [m@@ -410,12 +509,25 @@ def merge_before_file_upload(return Truereturn tool in m.tools or toolkit in m.toolkits- def combined(path: str, tool: str, toolkit: str) -> t.Union[str, bool]:- p: str = path- for m in to_chain:+ adapted_chain = [+ (m, _adapt_before_file_upload(t.cast(BeforeFileUploadLike, m.modifier)))+ for m in to_chain+ ]++ def combined(context: BeforeFileUploadContext) -> t.Union[str, bool]:+ p: str = context["path"]+ for m, hook in adapted_chain:if not _applies(m):continue- out = t.cast(BeforeFileUploadCallable, m.modifier)(p, tool, toolkit)+ # Preserve source/tool/toolkit while forwarding the (possibly+ # rewritten) path to the next hook.+ next_ctx: BeforeFileUploadContext = {+ "path": p,+ "source": context["source"],+ "tool": context["tool"],+ "toolkit": context["toolkit"],+ }+ out = hook(next_ctx)if out is False:return Falseif isinstance(out, str):diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex afeee6a20..36e1f2cf5 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -360,24 +360,29 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):self,client: HttpClient,provider: t.Optional["BaseProvider[TTool, TToolCollection]"] = None,- auto_upload_download_files: bool = True,+ dangerously_allow_auto_upload_download_files: bool = False,sensitive_file_upload_protection: bool = True,file_upload_path_deny_segments: t.Optional[t.Sequence[str]] = None,+ file_upload_dirs: t.Union[t.Sequence[str], t.Literal[False], None] = None,):"""Initialize ToolRouter instance.:param client: HTTP client for API calls:param provider: Optional provider for tool wrapping- :param auto_upload_download_files: Whether to automatically upload and download files. Defaults to True.+ :param dangerously_allow_auto_upload_download_files: Opt-in for automatic file upload/download. Defaults to False.:param sensitive_file_upload_protection: When True, block local paths on the built-in sensitive-path denylist before upload.:param file_upload_path_deny_segments: Extra path segment names to merge with the built-in denylist.+ :param file_upload_dirs: Allowlist of directories for auto-upload. See ``Composio`` for details."""super().__init__(client)self._provider = provider- self._auto_upload_download_files = auto_upload_download_filesself._sensitive_file_upload_protection = sensitive_file_upload_protectionself._file_upload_path_deny_segments = file_upload_path_deny_segments+ self._file_upload_dirs = file_upload_dirs+ self._auto_upload_download_files = bool(+ dangerously_allow_auto_upload_download_files+ )def _create_mcp_server_config(self,@@ -809,9 +814,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):return ToolRouterSession(client=self._client,provider=self._provider,- auto_upload_download_files=self._auto_upload_download_files,+ dangerously_allow_auto_upload_download_files=self._auto_upload_download_files,sensitive_file_upload_protection=self._sensitive_file_upload_protection,file_upload_path_deny_segments=self._file_upload_path_deny_segments,+ file_upload_dirs=self._file_upload_dirs,session_id=session.session_id,mcp=self._create_mcp_server_config(mcp_type=ToolRouterMCPServerType(session.mcp.type.lower()),@@ -864,9 +870,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):return ToolRouterSession(client=self._client,provider=self._provider,- auto_upload_download_files=self._auto_upload_download_files,+ dangerously_allow_auto_upload_download_files=self._auto_upload_download_files,sensitive_file_upload_protection=self._sensitive_file_upload_protection,file_upload_path_deny_segments=self._file_upload_path_deny_segments,+ file_upload_dirs=self._file_upload_dirs,session_id=session.session_id,mcp=self._create_mcp_server_config(mcp_type=ToolRouterMCPServerType(session.mcp.type.lower()),diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.pyindex 6cd1b2c45..fca6d9629 100644--- a/python/composio/core/models/tool_router_session.py+++ b/python/composio/core/models/tool_router_session.py@@ -76,9 +76,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):*,client: HttpClient,provider: t.Optional[BaseProvider[t.Any, t.Any]],- auto_upload_download_files: bool,+ dangerously_allow_auto_upload_download_files: bool,sensitive_file_upload_protection: bool = True,file_upload_path_deny_segments: t.Optional[t.Sequence[str]] = None,+ file_upload_dirs: t.Union[t.Sequence[str], t.Literal[False], None] = None,session_id: str,mcp: t.Any,experimental: "ToolRouterSessionExperimental",@@ -87,9 +88,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):) -> None:self._client = clientself._provider = provider- self._auto_upload_download_files = auto_upload_download_files+ self._auto_upload_download_files = dangerously_allow_auto_upload_download_filesself._sensitive_file_upload_protection = sensitive_file_upload_protectionself._file_upload_path_deny_segments = file_upload_path_deny_segments+ self._file_upload_dirs = file_upload_dirsself.session_id = session_idself.mcp = mcpself.experimental = experimental@@ -146,9 +148,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):tools_model = ToolsModel(client=self._client,provider=self._provider,- auto_upload_download_files=self._auto_upload_download_files,+ dangerously_allow_auto_upload_download_files=self._auto_upload_download_files,sensitive_file_upload_protection=self._sensitive_file_upload_protection,file_upload_path_deny_segments=self._file_upload_path_deny_segments,+ file_upload_dirs=self._file_upload_dirs,)router_tools = tools_model.get_raw_tool_router_meta_tools(diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.pyindex 664040898..b8f8e99fd 100644--- a/python/composio/core/models/tools.py+++ b/python/composio/core/models/tools.py@@ -2,6 +2,7 @@ from __future__ import annotationsimport functoolsimport typing as t+from pathlib import Pathimport typing_extensions as tefrom pydantic import BaseModel as PydanticBaseModel@@ -26,6 +27,7 @@ from composio.core.types import ToolkitVersionParamfrom composio.exceptions import InvalidParams, NotFoundError, ToolVersionRequiredErrorfrom composio.utils.pydantic import none_to_omitfrom composio.utils.toolkit_version import get_toolkit_version+from composio.utils.upload_dir_allowlist import resolve_effective_upload_allowlistfrom ._modifiers import (Modifiers,@@ -102,9 +104,10 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):provider: BaseProvider[TTool, TToolCollection],file_download_dir: t.Optional[str] = None,toolkit_versions: t.Optional[ToolkitVersionParam] = None,- auto_upload_download_files: bool = True,+ dangerously_allow_auto_upload_download_files: bool = False,sensitive_file_upload_protection: bool = True,file_upload_path_deny_segments: t.Optional[t.Sequence[str]] = None,+ file_upload_dirs: t.Union[t.Sequence[str], t.Literal[False], None] = None,):"""Initialize the tools resource.@@ -113,10 +116,27 @@ class Tools(Resource, t.Generic[TTool, TToolCollection])::param provider: The provider to use for the tools resource.:param file_download_dir: Output directory for downloadable files:param toolkit_versions: The versions of the toolkits to use. Defaults to 'latest' if not provided.- :param auto_upload_download_files: Whether to automatically upload and download files. Defaults to True.+ :param dangerously_allow_auto_upload_download_files: Opt-in for automatic file upload/download. Defaults to False.:param sensitive_file_upload_protection: When True, block local paths on the built-in sensitive-path denylist before upload.:param file_upload_path_deny_segments: Extra path segment names to merge with the built-in denylist.+ :param file_upload_dirs: Allowlist of directories from which local files may+ be auto-uploaded. Only consulted when+ ``dangerously_allow_auto_upload_download_files=True``. See Composio docs+ for details."""+ self._auto_upload_download_files = bool(+ dangerously_allow_auto_upload_download_files+ )+ # Resolve allowlist once, but only if auto-upload is enabled. When it's+ # disabled there's no auto-upload code path, so we pass ``None`` and+ # FileHelper won't run the allowlist check either way. Manual APIs (if+ # ever added in the future) should also pass ``None``.+ resolved_allowlist: t.Optional[t.List[Path]] = (+ resolve_effective_upload_allowlist(file_upload_dirs)+ if self._auto_upload_download_files+ else None+ )+self._client = clientself._custom_tools = CustomTools(client)self._tool_schemas: t.Dict[str, Tool] = {}@@ -125,9 +145,9 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):outdir=file_download_dir,sensitive_file_upload_protection=sensitive_file_upload_protection,file_upload_path_deny_segments=file_upload_path_deny_segments,+ file_upload_allowlist=resolved_allowlist,)self._toolkit_versions = toolkit_versions- self._auto_upload_download_files = auto_upload_download_filesself.custom_tool = self._custom_tools.registerself.provider = provider@@ -314,13 +334,14 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):)# Always enhance schema descriptions (type hints and required notes)- # regardless of auto_upload_download_files setting+ # regardless of dangerously_allow_auto_upload_download_filesfor tool in tools_list:tool.input_parameters = self._file_helper.enhance_schema_descriptions(schema=tool.input_parameters,)- # Only process file_uploadable schemas when auto_upload_download_files is True+ # Only process file_uploadable schemas when the caller opted in via+ # `dangerously_allow_auto_upload_download_files=True`.if self._auto_upload_download_files:for tool in tools_list:tool.input_parameters = (diff --git a/python/composio/exceptions.py b/python/composio/exceptions.pyindex 2cd408170..381b0f671 100644--- a/python/composio/exceptions.py+++ b/python/composio/exceptions.py@@ -172,6 +172,17 @@ class SensitiveFilePathBlockedError(FileError):"""Raised when a local file path is refused before upload (sensitive directory or credential-like name)."""+class FileUploadPathNotAllowedError(FileError):+ """+ Raised when automatic file upload during tool execution is attempted from a+ path outside the configured ``file_upload_dirs`` allowlist.++ Only fires for auto-upload (enabled via+ ``dangerously_allow_auto_upload_download_files=True``). Manual upload APIs+ are not subject to this check.+ """++class FileUploadAbortedError(FileError):"""Raised when a ``before_file_upload`` hook returns ``False``."""diff --git a/python/composio/sdk.py b/python/composio/sdk.pyindex e8447555c..7e718600c 100644--- a/python/composio/sdk.py+++ b/python/composio/sdk.py@@ -40,9 +40,10 @@ class SDKConfig(te.TypedDict):allow_tracking: te.NotRequired[bool]file_download_dir: te.NotRequired[str]toolkit_versions: te.NotRequired[ToolkitVersionParam]- auto_upload_download_files: te.NotRequired[bool]+ dangerously_allow_auto_upload_download_files: te.NotRequired[bool]sensitive_file_upload_protection: te.NotRequired[bool]file_upload_path_deny_segments: te.NotRequired[t.Sequence[str]]+ file_upload_dirs: te.NotRequired[t.Union[t.Sequence[str], t.Literal[False]]]class Composio(t.Generic[TTool, TToolCollection], WithLogger):@@ -105,9 +106,25 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):- A dictionary mapping toolkit names to specific versions- A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits- None or omitted to use 'latest' as default- :param auto_upload_download_files: Whether to automatically upload and download files. Defaults to True.+ :param dangerously_allow_auto_upload_download_files: Opt-in for automatic file+ upload and download during tool execution. Defaults to False.:param sensitive_file_upload_protection: When True, block local paths on the built-in sensitive-path denylist before upload. Defaults to True.:param file_upload_path_deny_segments: Extra path segment names merged with the built-in denylist.+ :param file_upload_dirs: Allowlist of directories from which the SDK is allowed+ to read local files during **automatic** file upload (the flow gated by+ ``dangerously_allow_auto_upload_download_files=True``).++ - ``None`` (default) -> ``[~/.composio/temp]``.+ - ``False`` -> reject every local path during auto-upload. URLs and+ in-memory bytes still work because they aren't path-checked.+ - ``Sequence[str]`` (non-empty) -> use as the allowlist. A file is accepted+ iff its symlink-resolved absolute path is inside one of these directories+ on a path-component boundary (``/tmp/foo`` allows ``/tmp/foo/bar`` but+ NOT ``/tmp/foo-bar``).+ - ``[]`` -> behaves like ``False`` (kept as an alias; prefer ``False``).+ - Providing a value REPLACES the default. Include ``~/.composio/temp`` in+ your list if you want the default staging dir to keep working.+ - On Windows, entries are compared case-insensitively."""WithLogger.__init__(self)api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))@@ -140,14 +157,20 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):file_upload_path_deny_segments: t.Optional[t.Sequence[str]] = kwargs.get("file_upload_path_deny_segments")+ file_upload_dirs: t.Union[t.Sequence[str], t.Literal[False], None] = kwargs.get(+ "file_upload_dirs"+ )self.tools = Tools(client=self._client,provider=actual_provider,file_download_dir=kwargs.get("file_download_dir"),toolkit_versions=toolkit_versions,- auto_upload_download_files=kwargs.get("auto_upload_download_files", True),+ dangerously_allow_auto_upload_download_files=kwargs.get(+ "dangerously_allow_auto_upload_download_files", False+ ),sensitive_file_upload_protection=sensitive_file_upload_protection,file_upload_path_deny_segments=file_upload_path_deny_segments,+ file_upload_dirs=file_upload_dirs,)self.toolkits = Toolkits(client=self._client)@@ -165,9 +188,12 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):self.tool_router = ToolRouter(client=self._client,provider=actual_provider,- auto_upload_download_files=kwargs.get("auto_upload_download_files", True),+ dangerously_allow_auto_upload_download_files=kwargs.get(+ "dangerously_allow_auto_upload_download_files", False+ ),sensitive_file_upload_protection=sensitive_file_upload_protection,file_upload_path_deny_segments=file_upload_path_deny_segments,+ file_upload_dirs=file_upload_dirs,)self.create = self.tool_router.createself.use = self.tool_router.usediff --git a/python/composio/utils/upload_dir_allowlist.py b/python/composio/utils/upload_dir_allowlist.pynew file mode 100644index 000000000..eabc951d2--- /dev/null+++ b/python/composio/utils/upload_dir_allowlist.py@@ -0,0 +1,239 @@+"""Allowlist enforcement for automatic file upload during tool execution.++This is only consulted when+``dangerously_allow_auto_upload_download_files=True``. Manual upload APIs are+not subject to the allowlist (parity with the TypeScript SDK).++- A local path is accepted iff its symlink-resolved absolute path is inside one+ of the allowed directories on a path-component boundary. ``/tmp/foo`` allows+ ``/tmp/foo/bar`` but NOT ``/tmp/foo-bar``.+- URLs never hit this check.+- User-provided ``file_upload_dirs`` fully REPLACES the default+ ``[~/.composio/temp]``.+- On Windows, path comparisons are case-insensitive.+"""++from __future__ import annotations++import os+import sys+import typing as t+from pathlib import Path++from composio.exceptions import (+ FileUploadPathNotAllowedError,+ SDKFileNotFoundError,+)++UPLOAD_TEMP_DIRECTORY_NAME = "temp"+++def get_default_upload_dir() -> t.Optional[Path]:+ """Absolute path of the default upload staging directory+ (``<home>/.composio/temp``), or None when a home directory cannot be+ determined."""+ try:+ home = Path.home()+ except (RuntimeError, OSError):+ return None+ return (home / ".composio" / UPLOAD_TEMP_DIRECTORY_NAME).resolve()+++def ensure_dir_exists(p: Path) -> None:+ """Best-effort directory creation. Allowlist enforcement still works if+ creation fails (e.g. read-only filesystem)."""+ try:+ p.mkdir(parents=True, exist_ok=True)+ except OSError:+ pass+++FileUploadDirs = t.Union[t.Sequence[str], t.Literal[False], None]+"""User-facing type for ``file_upload_dirs``.++- ``None`` (default) -> use ``[<home>/.composio/temp]``.+- ``False`` -> reject every local path during auto-upload (URLs / bytes still+ work).+- ``[]`` -> same as ``False`` (kept as an alias; prefer ``False``).+- ``Sequence[str]`` (non-empty) -> allowlist replacing the default.+"""+++def resolve_effective_upload_allowlist(+ user_dirs: FileUploadDirs,+) -> t.List[Path]:+ """Resolve the effective allowlist.++ - ``None`` -> ``[<default>]`` when available, else ``[]`` (fail-closed).+ - ``False`` -> ``[]`` (explicit "reject all local paths"). URLs and+ in-memory bytes still work because they aren't path-checked.+ - ``Sequence[str]`` (including ``[]``) REPLACES the default and is returned+ verbatim after ``~``-expansion and ``resolve()``. ``[]`` is treated as+ equivalent to ``False``.+ - Empty / blank / non-string entries are skipped.+ - Duplicates are removed (case-insensitive on Windows).+ """+ if user_dirs is None:+ default = get_default_upload_dir()+ return [default] if default is not None else []+ if user_dirs is False:+ return []++ seen: t.Set[str] = set()+ out: t.List[Path] = []+ for raw in user_dirs:+ if not isinstance(raw, (str, os.PathLike)):+ continue+ s = str(raw).strip()+ if not s:+ continue+ abs_path = Path(s).expanduser().resolve()+ key = str(abs_path).lower() if sys.platform == "win32" else str(abs_path)+ if key in seen:+ continue+ seen.add(key)+ out.append(abs_path)+ return out+++def _is_inside_dir(child: Path, parent: Path) -> bool:+ """True iff ``child`` equals ``parent`` or is nested inside on a component+ boundary. Assumes both are absolute and normalized."""+ try:+ child_str = str(child)+ parent_str = str(parent)+ if sys.platform == "win32":+ child_str = child_str.lower()+ parent_str = parent_str.lower()+ if child_str == parent_str:+ return True+ sep = os.sep+ parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep+ return child_str.startswith(parent_with_sep)+ except OSError:+ return False+++def _format_allowlist(dirs: t.Sequence[Path]) -> str:+ if not dirs:+ return " (none configured — all local paths are blocked)"+ return "\n".join(f" - {d}" for d in dirs)+++def _build_help_footer(allowlist: t.Sequence[Path]) -> str:+ return "\n".join(+ [+ "",+ "Allowed upload directories (file_upload_dirs):",+ _format_allowlist(allowlist),+ "",+ "Fix one of the following:",+ "",+ " 1. Recommended — move the file under an allowed directory, or add your",+ " directory to the allowlist:",+ " Composio(",+ " file_upload_dirs=['/abs/path/to/uploads', '~/.composio/temp'],",+ " )",+ " Note: user-provided `file_upload_dirs` REPLACES the default",+ " `~/.composio/temp`. Include it explicitly if you want staged uploads",+ " to keep working.",+ "",+ " 2. Pass the file by URL (http://... / https://...) instead of a",+ " filesystem path. URLs are never path-checked.",+ "",+ " 3. (Dangerous) Bypass the allowlist entirely by opting into automatic",+ " file upload/download from any readable path:",+ " Composio(dangerously_allow_auto_upload_download_files=True, ...)",+ " WARNING: This lets a prompt-injected or misbehaving tool read ANY",+ " file the process can access. Only enable it in trusted, sandboxed",+ " environments. The built-in sensitive-path denylist (.ssh, .aws,",+ " .env, private SSH keys, etc.) still applies unless you also set",+ " `sensitive_file_upload_protection=False`.",+ ]+ )+++def assert_path_inside_upload_dirs(+ file_path: t.Union[str, Path],+ allowlist: t.Sequence[Path],+) -> None:+ """Raise an elaborate error if the path is missing or outside the allowlist.++ :raises SDKFileNotFoundError: when ``file_path`` does not exist on disk.+ :raises FileUploadPathNotAllowedError: when resolved path is outside every+ entry of ``allowlist`` (including when allowlist is empty).+ """+ attempted = str(file_path)+ abs_path = Path(attempted).expanduser()+ try:+ abs_path = abs_path.resolve(strict=False)+ except OSError:+ pass++ if not abs_path.exists():+ cwd = Path.cwd()+ parent = abs_path.parent+ parent_exists = parent.exists()+ raise SDKFileNotFoundError(+ "\n".join(+ [+ f'Refusing to auto-upload "{attempted}": the file does not exist on disk.',+ "",+ f"Path attempted: {attempted}",+ f"Resolved to: {abs_path}",+ f"Process cwd: {cwd}",+ f"Parent exists: {'yes (' + str(parent) + ')' if parent_exists else 'no (' + str(parent) + ')'}",+ "",+ "Common causes:",+ " - Typo in the filename passed to the tool.",+ " - Relative path resolved against the wrong working directory",+ " (relative paths use os.getcwd() at the moment of upload).",+ " - File was deleted between the tool being called and the upload starting.",+ "",+ _build_help_footer(allowlist),+ ]+ )+ )++ try:+ real_path = abs_path.resolve(strict=True)+ except OSError:+ real_path = abs_path++ if not allowlist:+ raise FileUploadPathNotAllowedError(+ "\n".join(+ [+ f'Refusing to auto-upload "{attempted}": no upload directories are configured.',+ "",+ f"Path attempted: {attempted}",+ f"Resolved to: {real_path}",+ "",+ "Automatic file upload during tool execution is locked down by default",+ "to prevent a prompt-injected tool from exfiltrating server files",+ "(source code, .env, SSH keys, etc.).",+ _build_help_footer(allowlist),+ ]+ )+ )++ for dir_entry in allowlist:+ try:+ real_dir = Path(dir_entry).expanduser().resolve(strict=False)+ except OSError:+ real_dir = Path(dir_entry)+ if _is_inside_dir(real_path, real_dir):+ return++ raise FileUploadPathNotAllowedError(+ "\n".join(+ [+ f'Refusing to auto-upload "{attempted}": resolved path is not inside any',+ "directory in the configured `file_upload_dirs` allowlist.",+ "",+ f"Path attempted: {attempted}",+ f"Resolved to: {real_path}",+ _build_help_footer(allowlist),+ ]+ )+ )diff --git a/python/tests/test_auto_upload_download_files.py b/python/tests/test_auto_upload_download_files.pyindex 8af9a0cb8..216d8b093 100644--- a/python/tests/test_auto_upload_download_files.py+++ b/python/tests/test_auto_upload_download_files.py@@ -75,7 +75,7 @@ class TestAutoUploadDownloadFilesEnabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -119,7 +119,7 @@ class TestAutoUploadDownloadFilesEnabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -182,7 +182,7 @@ class TestAutoUploadDownloadFilesEnabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -243,7 +243,7 @@ class TestAutoUploadDownloadFilesEnabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -314,7 +314,6 @@ class TestAutoUploadDownloadFilesDisabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -363,7 +362,6 @@ class TestAutoUploadDownloadFilesDisabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -419,7 +417,6 @@ class TestAutoUploadDownloadFilesDisabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -464,7 +461,6 @@ class TestAutoUploadDownloadFilesDisabled:tools = Tools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,toolkit_versions={"test_toolkit": "20251201_01"},)@@ -518,12 +514,11 @@ class TestAutoUploadDownloadFilesDisabled:class TestAutoUploadDownloadFilesWithSDK:"""Test cases for auto_upload_download_files with SDK initialization."""- def test_sdk_passes_auto_upload_download_files_to_tools(self):- """Test that Composio SDK passes auto_upload_download_files to Tools."""+ def test_sdk_passes_auto_upload_download_off_to_tools_by_default(self):+ """Test that Composio SDK disables automatic file upload/download by default."""from composio.sdk import Composiowith patch("composio.sdk.HttpClient"):- # Test with default (True)with patch.object(Tools, "__init__", return_value=None) as mock_init:mock_provider = Mock()mock_provider.name = "test"@@ -533,13 +528,15 @@ class TestAutoUploadDownloadFilesWithSDK:api_key="test-key",)- # Should have passed auto_upload_download_files=True (default)mock_init.assert_called()call_kwargs = mock_init.call_args[1]- assert call_kwargs.get("auto_upload_download_files", True) is True+ assert (+ call_kwargs.get("dangerously_allow_auto_upload_download_files")+ is False+ )- def test_sdk_passes_false_to_tools(self):- """Test that Composio SDK correctly passes auto_upload_download_files=False."""+ def test_sdk_passes_true_when_dangerously_enabled(self):+ """Test that Composio SDK passes through dangerously_allow_auto_upload_download_files."""from composio.sdk import Composiowith patch("composio.sdk.HttpClient"):@@ -550,9 +547,12 @@ class TestAutoUploadDownloadFilesWithSDK:Composio(provider=mock_provider,api_key="test-key",- auto_upload_download_files=False,+ dangerously_allow_auto_upload_download_files=True,)mock_init.assert_called()call_kwargs = mock_init.call_args[1]- assert call_kwargs.get("auto_upload_download_files") is False+ assert (+ call_kwargs.get("dangerously_allow_auto_upload_download_files")+ is True+ )diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.pyindex 9dc0850ca..eebb42432 100644--- a/python/tests/test_custom_tools.py+++ b/python/tests/test_custom_tools.py@@ -576,7 +576,7 @@ def _session(deps, **overrides):kwargs = dict(client=deps["client"],provider=deps["provider"],- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,session_id="s",mcp=MagicMock(),experimental=deps["experimental"],@@ -644,7 +644,7 @@ class TestToolRouterSessionCustomTools:s = ToolRouterSession(client=MagicMock(),provider=MagicMock(),- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,session_id="s",mcp=MagicMock(),experimental=MagicMock(),@@ -663,7 +663,7 @@ class TestMultiExecuteRouting:return ToolRouterSession(client=MagicMock(),provider=MagicMock(),- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=True,session_id="s",mcp=MagicMock(),experimental=MagicMock(),diff --git a/python/tests/test_files.py b/python/tests/test_files.pyindex ad3583aa8..1d26fa958 100644--- a/python/tests/test_files.py+++ b/python/tests/test_files.py@@ -1322,6 +1322,123 @@ class TestFileUploadableFromUrl:assert "Fetch failed" in str(exc_info.value)+ def test_before_file_upload_hook_receives_source_url(self):+ """from_path emits ``source="url"`` to the hook for http(s) inputs.++ We abort from the hook to avoid the downstream network path; the+ pre-abort capture is what we're asserting on.+ """+ from composio.exceptions import FileUploadAbortedError++ mock_client = MagicMock()+ seen = {}++ def hook(ctx):+ seen.update(ctx)+ return False++ with pytest.raises(FileUploadAbortedError):+ FileUploadable.from_path(+ client=mock_client,+ file="https://example.com/photo.png",+ tool="SEND_EMAIL",+ toolkit="gmail",+ before_file_upload=hook,+ )++ assert seen == {+ "path": "https://example.com/photo.png",+ "source": "url",+ "tool": "SEND_EMAIL",+ "toolkit": "gmail",+ }++ def test_before_file_upload_hook_receives_source_path(self, tmp_path):+ """from_path emits ``source="path"`` to the hook for local inputs."""+ from composio.exceptions import FileUploadAbortedError++ f = tmp_path / "doc.txt"+ f.write_text("hello")+ mock_client = MagicMock()+ seen = {}++ def hook(ctx):+ seen.update(ctx)+ return False++ with pytest.raises(FileUploadAbortedError):+ FileUploadable.from_path(+ client=mock_client,+ file=str(f),+ tool="MY_TOOL",+ toolkit="my_toolkit",+ before_file_upload=hook,+ )++ assert seen == {+ "path": str(f),+ "source": "path",+ "tool": "MY_TOOL",+ "toolkit": "my_toolkit",+ }++ def test_url_hook_returning_local_path_routes_through_path_branch(self, tmp_path):+ """A hook that rewrites a URL into a local path must NOT be fed to+ ``from_url``. It has to route back into the local-file branch so the+ allowlist / denylist / existence checks all run."""+ from composio.exceptions import SDKFileNotFoundError++ # A path that's syntactically a path but does not exist — if routing+ # is correct, we'll get SDKFileNotFoundError from the local branch.+ # If the bug is still there, we'd hit `from_url` and the URL fetch+ # would explode (or worse, succeed) instead.+ rewritten = str(tmp_path / "does-not-exist.txt")++ def hook(ctx):+ assert ctx["source"] == "url"+ return rewritten++ mock_client = MagicMock()++ with pytest.raises(SDKFileNotFoundError):+ FileUploadable.from_path(+ client=mock_client,+ file="https://example.com/photo.png",+ tool="T",+ toolkit="tk",+ before_file_upload=hook,+ )++ @patch("composio.core.models._files._fetch_file_from_url")+ @patch("composio.core.models._files._upload_bytes_to_s3")+ def test_path_hook_returning_url_routes_through_url_branch(+ self, mock_upload, mock_fetch, tmp_path+ ):+ """Inverse of the above: a hook on a local path that returns a URL+ must route through ``from_url``, not stat the URL string as a file."""+ f = tmp_path / "local.txt"+ f.write_text("hi")++ mock_fetch.return_value = ("photo.png", b"x", "image/png")+ mock_upload.return_value = "s3-key"++ def hook(ctx):+ assert ctx["source"] == "path"+ return "https://example.com/photo.png"++ mock_client = MagicMock()+ result = FileUploadable.from_path(+ client=mock_client,+ file=str(f),+ tool="T",+ toolkit="tk",+ before_file_upload=hook,+ )++ # If routing worked, the URL fetch path was taken.+ mock_fetch.assert_called_once_with("https://example.com/photo.png")+ assert result.s3key == "s3-key"+class TestFileHelperWithUrls:"""Test cases for FileHelper handling URLs in file uploads."""diff --git a/python/tests/test_sdk.py b/python/tests/test_sdk.pyindex de669408b..a83d4f65f 100644--- a/python/tests/test_sdk.py+++ b/python/tests/test_sdk.py@@ -56,9 +56,10 @@ class TestComposioSDK:"allow_tracking","file_download_dir","toolkit_versions",- "auto_upload_download_files",+ "dangerously_allow_auto_upload_download_files","sensitive_file_upload_protection","file_upload_path_deny_segments",+ "file_upload_dirs",}assert set(SDKConfig.__annotations__.keys()) == expected_fieldsdiff --git a/python/tests/test_tool_execution.py b/python/tests/test_tool_execution.pyindex 898104f53..dff406fc4 100644--- a/python/tests/test_tool_execution.py+++ b/python/tests/test_tool_execution.py@@ -855,12 +855,17 @@ class TestToolExecution:scoped = before_file_upload(tools=["OTHER_TOOL"])(lambda p, t, k: p + "_X")fn = merge_before_file_upload([scoped], tool="MY", toolkit="gh")assert fn is not None- assert fn("/a", "MY", "gh") == "/a"+ assert (+ fn({"path": "/a", "source": "path", "tool": "MY", "toolkit": "gh"}) == "/a"+ )all_tools = before_file_upload(lambda p, t, k: p + "_Y")fn2 = merge_before_file_upload([all_tools], tool="MY", toolkit="gh")assert fn2 is not None- assert fn2("/a", "MY", "gh") == "/a_Y"+ assert (+ fn2({"path": "/a", "source": "path", "tool": "MY", "toolkit": "gh"})+ == "/a_Y"+ )def test_merge_before_file_upload_chains_modifiers(self):from composio.core.models._modifiers import (@@ -872,7 +877,103 @@ class TestToolExecution:m2 = before_file_upload(lambda p, t, k: f"{p}|2")fn = merge_before_file_upload([m1, m2], tool="T", toolkit="k")assert fn is not None- assert fn("p", "T", "k") == "p|1|2"+ assert (+ fn({"path": "p", "source": "path", "tool": "T", "toolkit": "k"}) == "p|1|2"+ )++ def test_before_file_upload_context_form_receives_source(self):+ """New-form hooks (single ``context`` arg) see ``source`` in the context."""+ from composio.core.models._modifiers import (+ before_file_upload,+ merge_before_file_upload,+ )++ seen: t.Dict[str, t.Any] = {}++ def hook(ctx):+ seen.update(ctx)+ return ctx["path"] + "!"++ m = before_file_upload(hook)+ fn = merge_before_file_upload([m], tool="T", toolkit="k")+ assert fn is not None++ out = fn({"path": "/x", "source": "path", "tool": "T", "toolkit": "k"})+ assert out == "/x!"+ assert seen == {"path": "/x", "source": "path", "tool": "T", "toolkit": "k"}++ seen.clear()+ out = fn(+ {+ "path": "https://example.com/a.pdf",+ "source": "url",+ "tool": "T",+ "toolkit": "k",+ }+ )+ assert out == "https://example.com/a.pdf!"+ assert seen["source"] == "url"++ def test_before_file_upload_legacy_3arg_form_still_works(self):+ """Hooks declared as ``(path, tool, toolkit)`` keep working unchanged."""+ from composio.core.models._modifiers import (+ before_file_upload,+ merge_before_file_upload,+ )++ def legacy(path, tool, toolkit):+ return f"{path}@{tool}/{toolkit}"++ m = before_file_upload(legacy)+ fn = merge_before_file_upload([m], tool="T", toolkit="k")+ assert fn is not None+ # Driver always passes context form; adapter unwraps to positional args.+ assert (+ fn({"path": "/x", "source": "path", "tool": "T", "toolkit": "k"})+ == "/x@T/k"+ )++ def test_before_file_upload_chain_preserves_source(self):+ """``source`` stays stable as the ``path`` is rewritten down the chain."""+ from composio.core.models._modifiers import (+ before_file_upload,+ merge_before_file_upload,+ )++ seen_sources: t.List[str] = []++ def h1(ctx):+ seen_sources.append(ctx["source"])+ return ctx["path"] + "|1"++ def h2(ctx):+ seen_sources.append(ctx["source"])+ return ctx["path"] + "|2"++ fn = merge_before_file_upload(+ [before_file_upload(h1), before_file_upload(h2)], tool="T", toolkit="k"+ )+ assert fn is not None+ out = fn({"path": "p", "source": "url", "tool": "T", "toolkit": "k"})+ assert out == "p|1|2"+ assert seen_sources == ["url", "url"]++ def test_before_file_upload_abort_propagates_as_false(self):+ from composio.core.models._modifiers import (+ before_file_upload,+ merge_before_file_upload,+ )++ def abort(ctx):+ return False++ fn = merge_before_file_upload(+ [before_file_upload(abort)], tool="T", toolkit="k"+ )+ assert fn is not None+ assert (+ fn({"path": "/x", "source": "path", "tool": "T", "toolkit": "k"}) is False+ )def test_execute_includes_before_file_upload_modifier_in_compose(self,@@ -888,6 +989,7 @@ class TestToolExecution:client=mock_client,provider=mock_provider,toolkit_versions={"github": "20251201_01"},+ dangerously_allow_auto_upload_download_files=True,)github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")@@ -923,7 +1025,17 @@ class TestToolExecution:bfu = cap.get("bfu")assert bfu is not None- assert bfu("/p", "GITHUB_GET_REPOS", "github") == "/p>"+ assert (+ bfu(+ {+ "path": "/p",+ "source": "path",+ "tool": "GITHUB_GET_REPOS",+ "toolkit": "github",+ }+ )+ == "/p>"+ )def test_execute_with_environment_variable_toolkit_version(self):"""Test that execute uses environment variable for toolkit version."""diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex 5d0050fec..36559907b 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -966,13 +966,14 @@ class TestToolRouter:session = tool_router.create(user_id="user_123")result = session.tools()- # Verify Tools was instantiated+ # Verify Tools was instantiated (resolved flag; default ToolRouter is off)mock_tools_class.assert_called_once_with(client=mock_client,provider=mock_provider,- auto_upload_download_files=True,+ dangerously_allow_auto_upload_download_files=False,sensitive_file_upload_protection=True,file_upload_path_deny_segments=None,+ file_upload_dirs=None,)# Verify get_raw_tool_router_meta_tools was called@@ -1267,7 +1268,7 @@ class TestToolRouterExecution:real_tools = RealTools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,+ dangerously_allow_auto_upload_download_files=False,)execute_fn = real_tools._wrap_execute_tool_for_tool_router(session_id="session_123"@@ -1318,7 +1319,7 @@ class TestToolRouterExecution:real_tools = RealTools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,+ dangerously_allow_auto_upload_download_files=False,)modifiers = [@@ -1361,7 +1362,7 @@ class TestToolRouterExecution:real_tools = RealTools(client=mock_client,provider=mock_provider,- auto_upload_download_files=False,+ dangerously_allow_auto_upload_download_files=False,)execute_fn = real_tools._wrap_execute_tool_for_tool_router(session_id="session_123"diff --git a/python/tests/test_upload_dir_allowlist.py b/python/tests/test_upload_dir_allowlist.pynew file mode 100644index 000000000..0c6127075--- /dev/null+++ b/python/tests/test_upload_dir_allowlist.py@@ -0,0 +1,251 @@+"""Tests for the auto-upload directory allowlist (parity with TS sdk)."""++from __future__ import annotations++import os+import sys+from pathlib import Path++import pytest++from composio.core.models.base import allow_tracking+from composio.exceptions import (+ FileUploadPathNotAllowedError,+ SDKFileNotFoundError,+)+from composio.utils.upload_dir_allowlist import (+ assert_path_inside_upload_dirs,+ get_default_upload_dir,+ resolve_effective_upload_allowlist,+)++[email protected](autouse=True)+def disable_telemetry():+ token = allow_tracking.set(False)+ yield+ allow_tracking.reset(token)+++class TestResolveEffectiveUploadAllowlist:+ def test_none_returns_default(self):+ result = resolve_effective_upload_allowlist(None)+ default = get_default_upload_dir()+ assert default is not None, "Expected a default upload dir in this env."+ assert result == [default]++ def test_empty_list_replaces_default(self):+ assert resolve_effective_upload_allowlist([]) == []++ def test_false_means_no_local_paths(self):+ # Explicit "reject all local paths during auto-upload". Equivalent to []+ # but reads better at call sites.+ assert resolve_effective_upload_allowlist(False) == []++ def test_explicit_list_replaces_default(self, tmp_path: Path):+ result = resolve_effective_upload_allowlist([str(tmp_path)])+ assert result == [tmp_path.resolve()]++ def test_tilde_is_expanded(self):+ result = resolve_effective_upload_allowlist(["~"])+ assert result == [Path.home().resolve()]++ def test_skips_blank_and_non_string_entries(self, tmp_path: Path):+ result = resolve_effective_upload_allowlist([str(tmp_path), "", " "])+ assert result == [tmp_path.resolve()]++ def test_deduplicates_entries(self, tmp_path: Path):+ result = resolve_effective_upload_allowlist([str(tmp_path), str(tmp_path)])+ assert result == [tmp_path.resolve()]+++class TestAssertPathInsideUploadDirs:+ def test_accepts_direct_child(self, tmp_path: Path):+ allowed = tmp_path+ f = allowed / "a.txt"+ f.write_text("hi")+ assert_path_inside_upload_dirs(str(f), [allowed])++ def test_accepts_nested_child(self, tmp_path: Path):+ allowed = tmp_path+ nested = allowed / "sub" / "deeper"+ nested.mkdir(parents=True)+ f = nested / "a.txt"+ f.write_text("hi")+ assert_path_inside_upload_dirs(str(f), [allowed])++ def test_rejects_path_outside(self, tmp_path: Path):+ allowed = tmp_path / "inside"+ outside = tmp_path / "outside"+ allowed.mkdir()+ outside.mkdir()+ f = outside / "a.txt"+ f.write_text("hi")+ with pytest.raises(FileUploadPathNotAllowedError):+ assert_path_inside_upload_dirs(str(f), [allowed])++ def test_enforces_component_boundary(self, tmp_path: Path):+ # /tmp/foo must NOT accept /tmp/foo-bar/x.+ allowed = tmp_path / "foo"+ sibling = tmp_path / "foo-bar"+ allowed.mkdir()+ sibling.mkdir()+ f = sibling / "x.txt"+ f.write_text("hi")+ with pytest.raises(FileUploadPathNotAllowedError):+ assert_path_inside_upload_dirs(str(f), [allowed])++ def test_raises_not_found_when_missing(self, tmp_path: Path):+ allowed = tmp_path+ missing = tmp_path / "does_not_exist.txt"+ with pytest.raises(SDKFileNotFoundError) as excinfo:+ assert_path_inside_upload_dirs(str(missing), [allowed])+ assert "does not exist on disk" in str(excinfo.value)+ assert "file_upload_dirs" in str(excinfo.value)++ def test_empty_allowlist_fails_closed(self, tmp_path: Path):+ f = tmp_path / "a.txt"+ f.write_text("hi")+ with pytest.raises(FileUploadPathNotAllowedError) as excinfo:+ assert_path_inside_upload_dirs(str(f), [])+ msg = str(excinfo.value)+ assert "no upload directories are configured" in msg+ assert "dangerously_allow_auto_upload_download_files" in msg++ def test_error_message_lists_allowlist(self, tmp_path: Path):+ allowed = tmp_path / "inside"+ outside = tmp_path / "outside"+ allowed.mkdir()+ outside.mkdir()+ f = outside / "a.txt"+ f.write_text("hi")+ with pytest.raises(FileUploadPathNotAllowedError) as excinfo:+ assert_path_inside_upload_dirs(str(f), [allowed])+ msg = str(excinfo.value)+ assert str(allowed) in msg+ assert "file_upload_dirs" in msg+ assert "dangerously_allow_auto_upload_download_files" in msg++ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX-only symlink semantics")+ def test_rejects_symlink_pointing_outside(self, tmp_path: Path):+ allowed = tmp_path / "inside"+ outside = tmp_path / "outside"+ allowed.mkdir()+ outside.mkdir()+ secret = outside / "secret.txt"+ secret.write_text("pw")+ link = allowed / "link.txt"+ os.symlink(secret, link)++ with pytest.raises(FileUploadPathNotAllowedError):+ assert_path_inside_upload_dirs(str(link), [allowed])+++class TestToolsWiresAllowlistCorrectly:+ """Verifies ``Tools`` forwards the right allowlist to ``FileHelper`` given+ the full flag/value matrix."""++ @staticmethod+ def _make_tools(+ dangerously_allow_auto_upload_download_files: bool,+ file_upload_dirs,+ ):+ from composio.core.models.tools import Tools+ from unittest.mock import Mock++ return Tools(+ client=Mock(),+ provider=Mock(name="provider"),+ dangerously_allow_auto_upload_download_files=dangerously_allow_auto_upload_download_files,+ file_upload_dirs=file_upload_dirs,+ )++ def test_flag_off_means_no_allowlist_is_ever_built(self):+ # Flag off ⇒ auto-upload code path is never run. We pass ``None`` to+ # FileHelper so manual/no-op paths don't accidentally enforce anything.+ t = self._make_tools(False, None)+ assert t._file_helper._file_upload_allowlist is None # noqa: SLF001++ def test_flag_off_ignores_file_upload_dirs_entirely(self):+ t = self._make_tools(False, ["/tmp/whatever"])+ assert t._file_helper._file_upload_allowlist is None # noqa: SLF001++ t = self._make_tools(False, False)+ assert t._file_helper._file_upload_allowlist is None # noqa: SLF001++ t = self._make_tools(False, [])+ assert t._file_helper._file_upload_allowlist is None # noqa: SLF001++ def test_flag_on_none_uses_default(self):+ t = self._make_tools(True, None)+ assert t._file_helper._file_upload_allowlist == [ # noqa: SLF001+ get_default_upload_dir()+ ]++ def test_flag_on_false_means_empty_allowlist(self):+ t = self._make_tools(True, False)+ assert t._file_helper._file_upload_allowlist == [] # noqa: SLF001++ def test_flag_on_empty_list_means_empty_allowlist(self):+ t = self._make_tools(True, [])+ assert t._file_helper._file_upload_allowlist == [] # noqa: SLF001++ def test_flag_on_explicit_dirs_replace_default(self, tmp_path: Path):+ t = self._make_tools(True, [str(tmp_path)])+ assert t._file_helper._file_upload_allowlist == [ # noqa: SLF001+ tmp_path.resolve()+ ]+++class TestFileUploadableAllowlistWiring:+ """Sanity: FileUploadable.from_path must honor the allowlist param."""++ def test_from_path_with_allowlist_blocks_outside(self, tmp_path: Path):+ from composio.core.models._files import FileUploadable+ from unittest.mock import Mock++ inside = tmp_path / "inside"+ outside = tmp_path / "outside"+ inside.mkdir()+ outside.mkdir()+ f = outside / "a.txt"+ f.write_text("hi")++ with pytest.raises(FileUploadPathNotAllowedError):+ FileUploadable.from_path(+ client=Mock(),+ file=str(f),+ tool="T",+ toolkit="tk",+ file_upload_allowlist=[inside],+ )++ def test_from_path_without_allowlist_skips_check(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ):+ """Passing ``file_upload_allowlist=None`` must NOT trigger the check.++ This simulates manual upload paths and the no-auto-upload default.+ """+ from composio.core.models import _files as files_mod+ from composio.core.models._files import FileUploadable+ from unittest.mock import Mock++ f = tmp_path / "a.txt"+ f.write_text("hi")++ # Short-circuit the network-bound parts.+ mock_client = Mock()+ mock_client.post.return_value = Mock(+ new_presigned_url="https://example/upload", key="k"+ )+ monkeypatch.setattr(files_mod, "upload", lambda url, file: True)++ result = FileUploadable.from_path(+ client=mock_client,+ file=str(f),+ tool="T",+ toolkit="tk",+ file_upload_allowlist=None,+ )+ assert result.s3key == "k"diff --git a/ts/docs/advanced/auto-upload-download.md b/ts/docs/advanced/auto-upload-download.mdindex 25eec542b..b43329eb8 100644--- a/ts/docs/advanced/auto-upload-download.md+++ b/ts/docs/advanced/auto-upload-download.md@@ -6,10 +6,11 @@ Composio SDK includes an automatic file handling system that manages file uploadThe file handling system in Composio SDK is:-- **Opt-out**: Enabled by default but can be disabled-- **Automatic**: Handles file uploads and downloads transparently-- **Configurable**: Can be disabled for manual file handling-- **Sensitive path protection (Node)**: Local string paths used for upload are checked by default against a denylist of path segments and file names (see below)+- **Opt-in**: Disabled by default. Set `dangerouslyAllowAutoUploadDownloadFiles: true` to enable.+- **Automatic** (when enabled): Handles file uploads and downloads transparently.+- **Allowlisted**: Even when enabled, local upload paths must resolve inside one of the directories listed in `fileUploadDirs` (default `[~/.composio/temp]`). See [Restricting upload paths with `fileUploadDirs`](#restricting-upload-paths-with-fileuploaddirs) below.+- **Configurable**: Manual handling via `composio.files.upload()` / `composio.files.download()` is always available and is **not** subject to `fileUploadDirs`.+- **Sensitive path protection (Node)**: Local string paths used for upload are checked by default against a denylist of path segments and file names (see below).## Security: sensitive local paths@@ -67,10 +68,10 @@ const toolSchema = {}```-When executing a tool with file upload:+When executing a tool with file upload (auto-handling enabled):```typescript-// With auto upload enabled (default)+// Requires `dangerouslyAllowAutoUploadDownloadFiles: true` AND a path inside `fileUploadDirs`const result = await composio.tools.execute('your-tool', {arguments: {file: '/path/to/local/file.txt' // Local file path@@ -124,22 +125,48 @@ Example tool response with file download:}```-## Disabling Auto File Handling+## Default: auto file handling is off-You can disable automatic file handling when initializing the SDK:+Automatic file upload/download during tool execution is **disabled** unless you pass `dangerouslyAllowAutoUploadDownloadFiles: true` to the `Composio` constructor.++## Restricting upload paths with `fileUploadDirs`++When auto-handling is on, the SDK only reads local files from directories you have explicitly allowlisted via `fileUploadDirs`. Anything outside the list is rejected with `ComposioFileUploadPathNotAllowedError` before the file is read.++| `fileUploadDirs` value | Effective allowlist |+| ---------------------- | ------------------- |+| omitted / `undefined` | `[~/.composio/temp]` (default staging dir) |+| `false` | `[]` — **all** local paths rejected (URLs and `File`/`Blob` still work) |+| `[]` | `[]` — same as `false`; explicit "no local paths" |+| `[<dir1>, <dir2>, …]` | exactly those directories. `~` is expanded; entries are `realpath`-resolved; comparison is on a path-component boundary (`/tmp/foo` allows `/tmp/foo/bar` but **not** `/tmp/foo-bar`) |++URLs (`http://…` / `https://…`) and JavaScript `File` / `Blob` objects are not subject to the allowlist — only local string paths are. The denylist (`sensitiveFileUploadProtection`) still runs in addition to the allowlist; both must accept the path.```typescriptimport { Composio } from '@composio/core';+// Widen the allowlist to the directories your code actually reads from.const composio = new Composio({- apiKey: 'your-api-key',- autoUploadDownloadFiles: false+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ // Replaces the default `[~/.composio/temp]`. Include it explicitly if you+ // still want the default staging dir to keep working.+ fileUploadDirs: ['/srv/agent/uploads', '~/.composio/temp'],+});++// Reject every local path; only URLs and File/Blob objects work.+const composioStrict = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: false,});```+If you want to upload from arbitrary paths without widening the allowlist, use the manual `composio.files.upload(...)` API below — it bypasses `fileUploadDirs` by design (the caller is expected to control the path).+## Manual File Handling-When auto file handling is disabled, you'll need to handle the file operations yourself using the `composio.files` API:+When auto file handling is not enabled, you'll need to handle the file operations yourself using the `composio.files` API:### Manual Upload@@ -193,12 +220,13 @@ if (result.data.file?.s3url) {## File Storage Location-Downloaded files are stored in a temporary directory:+Downloaded files are stored in:-- Location: `~/.composio/files/` (user's home directory)-- Files are named using the pattern: `{toolSlug}_{timestamp}.{extension}`-- The directory is created automatically when needed-- File extensions are derived from the MIME type+- **Default**: `~/.composio/files/` (user's home directory).+- **Custom**: pass `fileDownloadDir: '/some/abs/path'` to the `Composio` constructor.+- Files are named using the pattern: `{toolSlug}_{timestamp}.{extension}` (server-synthesized; the S3 URL never affects the local filename).+- The directory is created automatically when needed.+- File extensions are derived from the MIME type.## Error Handling@@ -209,6 +237,7 @@ import {ComposioFileUploadError,ComposioSensitiveFilePathBlockedError,ComposioFileUploadAbortedError,+ ComposioFileUploadPathNotAllowedError,} from '@composio/core';try {@@ -220,7 +249,9 @@ try {dangerouslySkipVersionCheck: true,});} catch (error) {- if (error instanceof ComposioSensitiveFilePathBlockedError) {+ if (error instanceof ComposioFileUploadPathNotAllowedError) {+ console.error('Path is outside fileUploadDirs:', error.message);+ } else if (error instanceof ComposioSensitiveFilePathBlockedError) {console.error('Blocked sensitive path:', error.message);} else if (error instanceof ComposioFileUploadAbortedError) {console.error('Upload aborted by beforeFileUpload:', error.message);diff --git a/ts/docs/api/composio.md b/ts/docs/api/composio.mdindex 81926afb6..3b87b792c 100644--- a/ts/docs/api/composio.md+++ b/ts/docs/api/composio.md@@ -11,9 +11,11 @@ const composio = new Composio({apiKey: 'your-api-key',baseURL: 'https://api.composio.dev', // Optional: Custom API endpointallowTracking: true, // Optional: Enable/disable telemetry- autoUploadDownloadFiles: true, // Optional: Enable/disable automatic file handling+ dangerouslyAllowAutoUploadDownloadFiles: false, // Optional: set to true to opt in to automatic file handling (default: false)sensitiveFileUploadProtection: true, // Optional: block uploads from sensitive paths (Node; default true)fileUploadPathDenySegments: undefined, // Optional: extra path component denylist+ fileUploadDirs: undefined, // Optional: allowlist for automatic upload (defaults to [~/.composio/temp])+ fileDownloadDir: undefined, // Optional: where auto-downloaded files are written (defaults to ~/.composio/files)provider: new OpenAIProvider(), // Optional: Custom provider});```@@ -27,9 +29,11 @@ The `Composio` constructor accepts a configuration object with the following pro| `apiKey` | string | Yes | - | Your Composio API key || `baseURL` | string | No | `https://api.composio.dev` | The base URL for the Composio API || `allowTracking` | boolean | No | `true` | Whether to allow analytics/tracking |-| `autoUploadDownloadFiles`| boolean | No | `true` | Whether to automatically handle file operations |+| `dangerouslyAllowAutoUploadDownloadFiles` | boolean | No | `false` | Opt in to automatic file upload/download during tool execution || `sensitiveFileUploadProtection` | `boolean` | No | `true` (Node) | When true, local upload paths are checked against a denylist of sensitive segments and credential-like names before read/upload. || `fileUploadPathDenySegments` | `string[]` | No | `undefined` | Additional path *components* merged with the built-in denylist. |+| `fileUploadDirs` | `string[] \| false` | No | `[~/.composio/temp]` | Allowlist of directories from which the SDK may read local files during **automatic** upload (when `dangerouslyAllowAutoUploadDownloadFiles: true`). Pass `false` (or `[]`) to reject every local path; URLs and `File`/`Blob` objects still work. Providing a list **replaces** the default — include `~/.composio/temp` explicitly if you want the default staging dir to keep working. Does **not** affect manual `composio.files.upload()` calls. |+| `fileDownloadDir` | `string` | No | `~/.composio/files` | Directory where files downloaded during tool execution (and `composio.files.download()`) are written. Relative paths resolve against `process.cwd()` at SDK-init time. || `provider` | `BaseComposioProvider` | No | `new OpenAIProvider()` | The provider to use for this Composio instance |## Properties@@ -97,14 +101,49 @@ const composio = new Composio({});```-### Disable Automatic File Handling+### Automatic file handling (opt-in)++Automatic upload/download of file-marked tool fields is **off** by default. Set `dangerouslyAllowAutoUploadDownloadFiles: true` only if you intend to use that behavior:```typescriptimport { Composio } from '@composio/core';const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,- autoUploadDownloadFiles: false,+ dangerouslyAllowAutoUploadDownloadFiles: true,+});+```++#### What the LLM sees vs. what the SDK does++The flag is a **contract between the SDK and the model**. The schema handed+to the LLM always reflects what will actually happen at runtime:++- **Flag `true`** — `composio.tools.get(...)` rewrites `file_uploadable`+ inputs down to `{ type: 'string', format: 'path' }`. The model passes a+ path or URL, the SDK stages it, the backend receives a proper+ `{ name, mimetype, s3key }` object. Works end-to-end.+- **Flag `false`** (or omitted) — the raw backend shape+ (`{ name, mimetype, s3key }`) is preserved. You are expected to stage+ files yourself via `composio.files.upload(...)` and inject the returned+ descriptor into the tool arguments before calling `tools.execute`. Handing+ this shape directly to an LLM is not recommended — the model cannot+ produce a valid `s3key`. On first execution of a file-uploadable tool in+ this mode, the SDK emits a single warning per tool slug nudging you+ toward either enabling the flag or staging manually.++Manual staging example (flag off):++```typescript+const staged = await composio.files.upload({+ file: '/tmp/report.pdf',+ toolSlug: 'SOME_FILE_TOOL',+ toolkitSlug: 'some-toolkit',+});++await composio.tools.execute('SOME_FILE_TOOL', {+ userId: 'u',+ arguments: { file: staged }, // { name, mimetype, s3key }});```@@ -121,7 +160,12 @@ await composio.tools.execute('SOME_FILE_TOOL',{ userId: 'u', arguments: { file: '/tmp/report.pdf' }, dangerouslySkipVersionCheck: true },{- beforeFileUpload: async ({ path, toolSlug, toolkitSlug }) => {+ beforeFileUpload: async ({ path, source, toolSlug, toolkitSlug }) => {+ // `source` discriminates the input:+ // 'path' — a local filesystem path+ // 'url' — an http(s):// URL+ // 'file' — a File object; `path` is `file.name` (filename only)+ if (source !== 'path') return path; // let URLs / File objects through// return path, a different path, or false to abortreturn path;},@@ -130,3 +174,60 @@ await composio.tools.execute(```See [Auto upload and download](./advanced/auto-upload-download.md#security-sensitive-local-paths) for the security model and error types.++### Restricting automatic uploads to specific directories++When `dangerouslyAllowAutoUploadDownloadFiles: true`, the SDK only reads local+files from directories in `fileUploadDirs`. This stacks with (it does NOT+replace) the sensitive-path denylist.++```typescript+import { Composio } from '@composio/core';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ // User-provided list REPLACES the default `[~/.composio/temp]`.+ // Include it explicitly if you want staged uploads to keep working.+ fileUploadDirs: ['/srv/agent/uploads', '~/.composio/temp'],+});+```++A local path is accepted if its symlink-resolved absolute path is inside one+of these directories on a path-component boundary. Paths outside the allowlist+throw `ComposioFileUploadPathNotAllowedError`. Missing files throw+`ComposioFileNotFoundError`. URLs (`http(s)://...`) and `File`/`Blob` objects+are not path-checked.++**Manual upload API (`composio.files.upload(...)`) is _not_ subject to this+allowlist** — it bypasses the allowlist check entirely. Use the allowlist to+constrain what models/agents can ask the SDK to upload during tool execution.++#### Blocking local paths entirely++Pass `false` to allow only URLs and in-memory `File`/`Blob` objects during+automatic upload:++```typescript+const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: false, // reject every filesystem path for auto-upload+});+```++`fileUploadDirs: []` behaves identically; prefer `false` for readability.++### Changing the download directory++```typescript+import { Composio } from '@composio/core';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY!,+ fileDownloadDir: '/var/app/composio-downloads',+});+```++Files returned by tools as `s3url` are streamed into this directory. The+default is `~/.composio/files`.diff --git a/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/README.md b/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/README.mdindex 0eac3f9b0..1a069c144 100644--- a/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/README.md+++ b/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/README.md@@ -7,9 +7,9 @@ This package tests `@composio/core` file operations in Cloudflare Workers enviroVerifies that:1. `composio.files.upload()` throws the expected "not supported in Cloudflare Workers" error2. `composio.files.download()` throws the expected "not supported in Cloudflare Workers" error-3. The `FileToolModifier.workerd.ts` is correctly loaded and provides the expected error message when `autoUploadDownloadFiles` is explicitly enabled-4. Composio initializes correctly with the default configuration (`autoUploadDownloadFiles: false` in workerd runtime)-5. Composio can be explicitly initialized with `autoUploadDownloadFiles: false`+3. The `FileToolModifier.workerd.ts` is correctly loaded and provides the expected error message when `dangerouslyAllowAutoUploadDownloadFiles` is explicitly enabled+4. Composio initializes correctly with the default configuration (`dangerouslyAllowAutoUploadDownloadFiles: false` in workerd runtime)+5. Composio can be explicitly initialized with `dangerouslyAllowAutoUploadDownloadFiles: false`## Endpoints@@ -18,8 +18,8 @@ Verifies that:| `GET /` | Lists all available test endpoints || `GET /test/files/upload` | Tests that `files.upload()` throws the expected error || `GET /test/files/download` | Tests that `files.download()` throws the expected error |-| `GET /test/file-modifier/error-message` | Tests the error when `autoUploadDownloadFiles: true` is explicitly set |-| `GET /test/auto-upload-disabled` | Tests Composio initialization with explicit `autoUploadDownloadFiles: false` |+| `GET /test/file-modifier/error-message` | Tests the error when `dangerouslyAllowAutoUploadDownloadFiles: true` is explicitly set |+| `GET /test/auto-upload-disabled` | Tests Composio initialization with explicit `dangerouslyAllowAutoUploadDownloadFiles: false` || `GET /test/default-config` | Tests Composio initialization with default configuration (no explicit setting) |## Running Tests@@ -44,7 +44,7 @@ Note: For file operation tests, a dummy API key works since the operations throw## Default Configuration-**In Cloudflare Workers (workerd runtime), `autoUploadDownloadFiles` defaults to `false`.**+**In Cloudflare Workers (workerd runtime), `dangerouslyAllowAutoUploadDownloadFiles` defaults to `false`.**This means you can initialize Composio without any special configuration:@@ -52,26 +52,26 @@ This means you can initialize Composio without any special configuration:const composio = new Composio({apiKey: 'your-key',});-// autoUploadDownloadFiles is false by default in workerd+// dangerouslyAllowAutoUploadDownloadFiles is false by default in workerd```## FileToolModifier Error-If you explicitly set `autoUploadDownloadFiles: true` and execute a tool with file properties in Cloudflare Workers, the following error is thrown:+If you explicitly set `dangerouslyAllowAutoUploadDownloadFiles: true` and execute a tool with file properties in Cloudflare Workers, the following error is thrown:```File upload/download modifiers are not available on edge runtimes yet.-Please set `autoUploadDownloadFiles: false` or run Composio in another JS runtime (Node.js / Bun).+Please set `dangerouslyAllowAutoUploadDownloadFiles: false` (or unset it; it defaults to false) or run Composio in another JS runtime (Node.js / Bun).```### Best Practice-For edge runtimes, use the default configuration or explicitly set `autoUploadDownloadFiles: false`:+For edge runtimes, use the default configuration or explicitly set `dangerouslyAllowAutoUploadDownloadFiles: false`:```typescriptconst composio = new Composio({apiKey: 'your-key',- autoUploadDownloadFiles: false, // This is the default for workerd+ dangerouslyAllowAutoUploadDownloadFiles: false, // This is the default for workerd});```diff --git a/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/src/index.ts b/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/src/index.tsindex 8b8c9cf38..d60e486e4 100644--- a/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/src/index.ts+++ b/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/src/index.ts@@ -94,10 +94,10 @@ app.get('/test/files/download', async c => {});/**- * Test: FileToolModifier behavior (triggers the autoUploadDownloadFiles error)+ * Test: FileToolModifier behavior (triggers the auto-upload/download error)*- * The FileToolModifier.workerd.ts throws an error when autoUploadDownloadFiles is enabled.- * In workerd runtime, the default is false, so we explicitly enable it here to test the error.+ * The FileToolModifier.workerd.ts throws an error when automatic file upload/download is enabled.+ * In workerd runtime, the default is off, so we explicitly opt in here to test the error.** This endpoint actually executes a tool to trigger the real error from FileToolModifier.workerd.ts.*/@@ -105,11 +105,11 @@ app.get('/test/file-modifier/error-message', async c => {try {const composio = new Composio({apiKey: c.env.COMPOSIO_API_KEY,- autoUploadDownloadFiles: true,+ dangerouslyAllowAutoUploadDownloadFiles: true,});// Use a local custom tool to avoid depending on remote Composio tool registry.- // Any execute() call with autoUploadDownloadFiles enabled will trigger FileToolModifier+ // Any execute() with automatic file handling enabled will trigger FileToolModifier// in the workerd runtime.await composio.tools.createCustomTool({slug: 'CUSTOM_FILE_TOOL',@@ -149,24 +149,24 @@ app.get('/test/file-modifier/error-message', async c => {});/**- * Test: Composio initialization with autoUploadDownloadFiles disabled- *- * In workerd runtime (Cloudflare Workers), autoUploadDownloadFiles defaults to false.+ * Test: Composio initialization with automatic file upload/download disabled+ *+ * In workerd runtime (Cloudflare Workers), dangerouslyAllowAutoUploadDownloadFiles defaults to false.* This test verifies that the default configuration works correctly and that* Composio can be initialized successfully without file upload/download support.*/app.get('/test/auto-upload-disabled', async c => {try {- // Explicitly set autoUploadDownloadFiles: false (which is the default for workerd)- // This is the recommended configuration for edge runtimes+ // Explicitly keep automatic file handling off (default everywhere)const composio = new Composio({apiKey: c.env.COMPOSIO_API_KEY,- autoUploadDownloadFiles: false,+ dangerouslyAllowAutoUploadDownloadFiles: false,});return c.json({success: true,- message: 'Composio initialized successfully with autoUploadDownloadFiles: false',+ message:+ 'Composio initialized successfully with dangerouslyAllowAutoUploadDownloadFiles: false',hasProvider: typeof composio.provider !== 'undefined',hasTools: typeof composio.tools !== 'undefined',hasFiles: typeof composio.files !== 'undefined',@@ -189,12 +189,12 @@ app.get('/test/auto-upload-disabled', async c => {* Test: Composio initialization with default configuration** This test verifies that Composio initializes correctly with the default- * configuration for workerd runtime (autoUploadDownloadFiles: false by default).+ * configuration for workerd runtime (dangerouslyAllowAutoUploadDownloadFiles: false by default).* No explicit configuration is provided, relying on the runtime defaults.*/app.get('/test/default-config', async c => {try {- // Initialize Composio without explicitly setting autoUploadDownloadFiles+ // Initialize Composio without explicitly setting dangerouslyAllowAutoUploadDownloadFiles// Should use the workerd default (false)const composio = new Composio({apiKey: c.env.COMPOSIO_API_KEY,@@ -206,7 +206,7 @@ app.get('/test/default-config', async c => {hasProvider: typeof composio.provider !== 'undefined',hasTools: typeof composio.tools !== 'undefined',hasFiles: typeof composio.files !== 'undefined',- note: 'In workerd runtime, autoUploadDownloadFiles defaults to false',+ note: 'In workerd runtime, dangerouslyAllowAutoUploadDownloadFiles defaults to false',});} catch (error) {return c.json(diff --git a/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/test/files.spec.ts b/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/test/files.spec.tsindex 37b1fd9bc..0952e2566 100644--- a/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/test/files.spec.ts+++ b/ts/e2e-tests/runtimes/cloudflare/cf-workers-files/test/files.spec.ts@@ -75,7 +75,7 @@ describe('@composio/core Files - Cloudflare Workers compatibility', () => {expect(body.error).toContain('not available on edge runtimes');});- it('should successfully initialize Composio with autoUploadDownloadFiles disabled', async () => {+ it('should successfully initialize Composio with automatic file handling disabled', async () => {const request = new IncomingRequest('http://localhost/test/auto-upload-disabled');const ctx = createExecutionContext();const response = await app.fetch(request, env, ctx);@@ -93,7 +93,7 @@ describe('@composio/core Files - Cloudflare Workers compatibility', () => {};expect(body.success).toBe(true);- expect(body.message).toContain('autoUploadDownloadFiles: false');+ expect(body.message).toContain('dangerouslyAllowAutoUploadDownloadFiles: false');expect(body.hasProvider).toBe(true);expect(body.hasTools).toBe(true);expect(body.hasFiles).toBe(true);@@ -121,6 +121,6 @@ describe('@composio/core Files - Cloudflare Workers compatibility', () => {expect(body.hasProvider).toBe(true);expect(body.hasTools).toBe(true);expect(body.hasFiles).toBe(true);- expect(body.note).toContain('autoUploadDownloadFiles defaults to false');+ expect(body.note).toContain('dangerouslyAllowAutoUploadDownloadFiles defaults to false');});});diff --git a/ts/examples/file-handling/src/index.ts b/ts/examples/file-handling/src/index.tsindex dca8afb7e..22f6c01e9 100644--- a/ts/examples/file-handling/src/index.ts+++ b/ts/examples/file-handling/src/index.ts@@ -13,10 +13,23 @@ import 'dotenv/config';import path from 'path';/**- * Initialize Composio+ * Initialize Composio.+ *+ * `dangerouslyAllowAutoUploadDownloadFiles: true` enables the SDK to read local+ * files from disk during tool execution. When that flag is on, local paths are+ * restricted to the directories listed in `fileUploadDirs`. Passing a value+ * REPLACES the default `[~/.composio/temp]` — include it if you want staged+ * uploads to keep working. Pass `false` (or `[]`) to reject every local path+ * while still allowing URLs and `File`/`Blob` objects.+ *+ * `fileDownloadDir` controls where files in tool responses (`s3url` fields) are+ * written. Defaults to `~/.composio/files`.*/const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: [path.join(__dirname, '..'), '~/.composio/temp'],+ fileDownloadDir: path.join(__dirname, '..', '.composio-downloads'),});/**diff --git a/ts/packages/core/README.md b/ts/packages/core/README.mdindex baeae8679..6c07aace7 100644--- a/ts/packages/core/README.md+++ b/ts/packages/core/README.md@@ -122,7 +122,7 @@ interface ComposioConfig {apiKey?: string | null; // Your Composio API keybaseURL?: string | null; // Custom API base URL (optional)allowTracking?: boolean; // Enable/disable telemetry (default: true)- autoUploadDownloadFiles?: boolean; // Whether to automatically upload and download files during tool execution (default: true)+ dangerouslyAllowAutoUploadDownloadFiles?: boolean; // Opt-in for automatic file upload/download during tool execution (default: false)provider?: TProvider; // Custom provider (default: OpenAIProvider)host?: string; // Name of the host service which is using the SDK, this is for telemetrydefaultHeaders?: ComposioRequestHeaders; // Request headers to be passed to the Composio API clientdiff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.tsindex 10f1f3e23..6fd154d4b 100644--- a/ts/packages/core/src/composio.ts+++ b/ts/packages/core/src/composio.ts@@ -20,7 +20,7 @@ import { ToolkitVersionParam } from './types/tool.types';import { ToolRouter } from './models/ToolRouter';import { ToolRouterCreateSessionConfig, Session } from './types/toolRouter.types';import { CONFIG_DEFAULTS } from './utils/config-defaults';-+import { expandHomeAndResolve, expandHomeAndResolveMany } from './utils/fileDirs';export type ComposioConfig<TProvider extends BaseComposioProvider<unknown, unknown, unknown> = OpenAIProvider,> = {@@ -41,11 +41,11 @@ export type ComposioConfig<*/allowTracking?: boolean;/**- * Whether to automatically upload and download files during tool execution.- * @example true, false- * @default true+ * Opt in to automatic file upload and download during tool execution (reads local paths+ * and fetches URLs marked as file-uploadable in tool schemas). Disabled by default.+ * @default false*/- autoUploadDownloadFiles?: boolean;+ dangerouslyAllowAutoUploadDownloadFiles?: boolean;/*** When true, local file paths for auto-upload and `files.upload` are checked against* a built-in denylist of sensitive path segments (e.g. `.ssh`, `.aws`) and@@ -59,6 +59,33 @@ export type ComposioConfig<* they appear anywhere in the resolved path. Merged with the built-in list.*/fileUploadPathDenySegments?: string[];+ /**+ * Allowlist of directories from which the SDK is allowed to read local files+ * during **automatic** file upload (when+ * `dangerouslyAllowAutoUploadDownloadFiles: true`). Manual+ * `composio.files.upload()` calls are NOT subject to this allowlist.+ *+ * - `undefined` (default) → `[<home>/.composio/temp]`.+ * - `false` → reject every local path during auto-upload. URLs+ * (`http(s)://...`) and `File`/`Blob` objects continue to work.+ * - `string[]` (non-empty) → use as the allowlist. A file is accepted iff+ * its symlink-resolved absolute path is inside one of these directories+ * on a path-component boundary (so `/tmp/foo` allows `/tmp/foo/bar` but+ * NOT `/tmp/foo-bar`).+ * - `[]` → behaves like `false` (kept as an alias; prefer `false` for+ * readability).+ * - Providing any value **replaces** the default. Include `~/.composio/temp`+ * in your list if you want the default staging dir to keep working.+ * - On Windows, entries are compared case-insensitively.+ */+ fileUploadDirs?: string[] | false;+ /**+ * Directory where files downloaded during tool execution (and+ * `composio.files.download()`) are written. Defaults to+ * `<home>/.composio/files`. Path is expanded at SDK-init time; relative+ * paths resolve against `process.cwd()`.+ */+ fileDownloadDir?: string;/*** The tool provider to use for this Composio instance.* @example new OpenAIProvider()@@ -264,10 +291,13 @@ export class Composio<apiKey: apiKeyParsed,toolkitVersions: getToolkitVersionsFromEnv(config?.toolkitVersions),allowTracking: config?.allowTracking ?? CONFIG_DEFAULTS.allowTracking,- autoUploadDownloadFiles:- config?.autoUploadDownloadFiles ?? CONFIG_DEFAULTS.autoUploadDownloadFiles,+ dangerouslyAllowAutoUploadDownloadFiles:+ config?.dangerouslyAllowAutoUploadDownloadFiles ??+ CONFIG_DEFAULTS.dangerouslyAllowAutoUploadDownloadFiles,sensitiveFileUploadProtection: config?.sensitiveFileUploadProtection,fileUploadPathDenySegments: config?.fileUploadPathDenySegments,+ fileUploadDirs: expandHomeAndResolveMany(config?.fileUploadDirs),+ fileDownloadDir: expandHomeAndResolve(config?.fileDownloadDir),provider: config?.provider ?? this.provider,};@@ -292,6 +322,7 @@ export class Composio<this.files = new Files(this.client, {sensitiveFileUploadProtection: this.config.sensitiveFileUploadProtection,fileUploadPathDenySegments: this.config.fileUploadPathDenySegments,+ fileDownloadDir: this.config.fileDownloadDir,});this.connectedAccounts = new ConnectedAccounts(this.client);this.toolRouter = new ToolRouter(this.client, this.config);@@ -343,11 +374,20 @@ export class Composio<}/**- * Get the configuration SDK is initialized with- * @returns {ComposioConfig<TProvider>} The configuration SDK is initialized with+ * Get the configuration SDK is initialized with.+ *+ * Returns a frozen shallow clone — the SDK has already snapshotted+ * configuration values such as `dangerouslyAllowAutoUploadDownloadFiles`,+ * `fileUploadDirs`, and `fileDownloadDir` into its internal models, so+ * mutating the live config object would silently no-op. Freezing makes+ * that contract visible at the call site instead of letting the mutation+ * appear successful.+ *+ * @returns {Readonly<ComposioConfig<TProvider>>} The frozen configuration+ * the SDK is initialized with.*/- getConfig(): ComposioConfig<TProvider> {- return this.config;+ getConfig(): Readonly<ComposioConfig<TProvider>> {+ return Object.freeze({ ...this.config });}/**diff --git a/ts/packages/core/src/errors/FileModifierErrors.ts b/ts/packages/core/src/errors/FileModifierErrors.tsindex 943da80f2..a4aeed8a3 100644--- a/ts/packages/core/src/errors/FileModifierErrors.ts+++ b/ts/packages/core/src/errors/FileModifierErrors.ts@@ -4,6 +4,8 @@ export const FileModifierErrorCodes = {FILE_UPLOAD_FAILED: 'FILE_UPLOAD_FAILED',SENSITIVE_FILE_PATH_BLOCKED: 'SENSITIVE_FILE_PATH_BLOCKED',FILE_UPLOAD_ABORTED: 'FILE_UPLOAD_ABORTED',+ FILE_UPLOAD_PATH_NOT_ALLOWED: 'FILE_UPLOAD_PATH_NOT_ALLOWED',+ FILE_NOT_FOUND: 'FILE_NOT_FOUND',} as const;export class ComposioFileUploadError extends ComposioError {@@ -52,3 +54,47 @@ export class ComposioFileUploadAbortedError extends ComposioFileUploadError {this.name = 'ComposioFileUploadAbortedError';}}++/**+ * Thrown when automatic file upload during tool execution is attempted from a path+ * that is outside the configured {@link ComposioConfig.fileUploadDirs} allowlist.+ *+ * This only fires for auto-upload (enabled via+ * `dangerouslyAllowAutoUploadDownloadFiles: true`). Manual `composio.files.upload()`+ * calls are never subject to this check.+ */+export class ComposioFileUploadPathNotAllowedError extends ComposioFileUploadError {+ constructor(message: string, options: ComposioErrorOptions = {}) {+ super(message, {+ ...options,+ code: FileModifierErrorCodes.FILE_UPLOAD_PATH_NOT_ALLOWED,+ possibleFixes: options.possibleFixes ?? [+ 'Move the file under one of the directories in `fileUploadDirs`',+ 'Stage the file under the default upload dir (`~/.composio/temp`)',+ 'Add the containing directory to `fileUploadDirs` when constructing Composio',+ 'Pass the file by URL or as a File/Blob object instead of a filesystem path',+ ],+ });+ this.name = 'ComposioFileUploadPathNotAllowedError';+ }+}++/**+ * Thrown when a local file path passed for upload does not exist on disk.+ * Provides extra debugging context (resolved absolute path, cwd, allowlist state)+ * to help the caller distinguish between "typo" and "not-allowlisted" failures.+ */+export class ComposioFileNotFoundError extends ComposioFileUploadError {+ constructor(message: string, options: ComposioErrorOptions = {}) {+ super(message, {+ ...options,+ code: FileModifierErrorCodes.FILE_NOT_FOUND,+ possibleFixes: options.possibleFixes ?? [+ 'Double-check the path for typos',+ 'Remember relative paths are resolved against process.cwd() at upload time',+ 'Verify the file exists and the process has read permission',+ ],+ });+ this.name = 'ComposioFileNotFoundError';+ }+}diff --git a/ts/packages/core/src/models/Files.node.ts b/ts/packages/core/src/models/Files.node.tsindex db18820ab..97ac32bc9 100644--- a/ts/packages/core/src/models/Files.node.ts+++ b/ts/packages/core/src/models/Files.node.ts@@ -11,19 +11,21 @@ import { downloadFileFromS3, getFileDataAfterUploadingToS3 } from '../utils/fileimport { telemetry } from '../telemetry/Telemetry';export class Files {- private readonly fileUploadPathOptions: {+ private readonly fileOptions: {sensitiveFileUploadProtection?: boolean;fileUploadPathDenySegments?: string[];+ fileDownloadDir?: string;};constructor(private readonly client: ComposioClient,- fileUploadPathOptions: {+ fileOptions: {sensitiveFileUploadProtection?: boolean;fileUploadPathDenySegments?: string[];+ fileDownloadDir?: string;} = {}) {- this.fileUploadPathOptions = fileUploadPathOptions;+ this.fileOptions = fileOptions;telemetry.instrument(this, 'Files');}@@ -53,12 +55,15 @@ export class Files {toolSlug: string;toolkitSlug: string;}): Promise<FileUploadData> {+ // Note: manual `composio.files.upload()` intentionally skips the+ // `fileUploadDirs` allowlist. The allowlist only gates *automatic* upload+ // during tool execution (see FileToolModifier).const fileData = await getFileDataAfterUploadingToS3(file, {toolSlug,toolkitSlug,client: this.client,- sensitiveFileUploadProtection: this.fileUploadPathOptions.sensitiveFileUploadProtection,- fileUploadPathDenySegments: this.fileUploadPathOptions.fileUploadPathDenySegments,+ sensitiveFileUploadProtection: this.fileOptions.sensitiveFileUploadProtection,+ fileUploadPathDenySegments: this.fileOptions.fileUploadPathDenySegments,});return fileData;}@@ -77,7 +82,12 @@ export class Files {toolSlug: string;mimeType: string;}): Promise<FileDownloadData> {- const fileDownloadData = await downloadFileFromS3({ toolSlug, s3Url, mimeType });+ const fileDownloadData = await downloadFileFromS3({+ toolSlug,+ s3Url,+ mimeType,+ fileDownloadDir: this.fileOptions.fileDownloadDir,+ });return fileDownloadData;}}diff --git a/ts/packages/core/src/models/Tools.ts b/ts/packages/core/src/models/Tools.tsindex d2352cd37..91bca8ab4 100644--- a/ts/packages/core/src/models/Tools.ts+++ b/ts/packages/core/src/models/Tools.ts@@ -56,6 +56,8 @@ import { handleToolExecutionError } from '../errors/ToolErrors';import { ToolExecuteMetaParams } from '../types/tool.types';import { SessionExecuteMetaParams } from '@composio/client/resources/tool-router.mjs';import { CONFIG_DEFAULTS } from '../utils/config-defaults';+import { resolveEffectiveUploadAllowlist } from '../utils/fileDirs';+import { schemaHasFileUploadable } from '../utils/modifiers/FileToolModifier.utils.neutral';/*** This class is used to manage tools in the Composio SDK.* It provides methods to list, get, and execute tools.@@ -73,7 +75,15 @@ export class Tools<private fileUploadPathOptions: {sensitiveFileUploadProtection?: boolean;fileUploadPathDenySegments?: string[];+ fileUploadAllowlist?: string[];+ fileDownloadDir?: string;};+ /**+ * Tracks tool slugs we've already warned about to avoid spamming the log when+ * the same file-input tool is executed repeatedly while auto-upload is off.+ * Scoped per-instance so a fresh `Composio` starts with a clean slate.+ */+ private readonly warnedAutoUploadDisabledForTool = new Set<string>();constructor(client: ComposioClient, config?: ComposioConfig<TProvider>) {if (!client) {@@ -86,12 +96,17 @@ export class Tools<this.client = client;this.customTools = new CustomTools(client);this.provider = config.provider;- this.autoUploadDownloadFiles =- config?.autoUploadDownloadFiles ?? CONFIG_DEFAULTS.autoUploadDownloadFiles;+ this.autoUploadDownloadFiles = config?.dangerouslyAllowAutoUploadDownloadFiles === true;this.toolkitVersions = config?.toolkitVersions ?? CONFIG_DEFAULTS.toolkitVersions;this.fileUploadPathOptions = {sensitiveFileUploadProtection: config?.sensitiveFileUploadProtection,fileUploadPathDenySegments: config?.fileUploadPathDenySegments,+ // The allowlist is only enforced during automatic upload (see+ // FileToolModifier). Manual `composio.files.upload()` calls don't see it.+ fileUploadAllowlist: this.autoUploadDownloadFiles+ ? resolveEffectiveUploadAllowlist(config?.fileUploadDirs)+ : undefined,+ fileDownloadDir: config?.fileDownloadDir,};// Bind the execute method to ensure correct 'this' contextthis.execute = this.execute.bind(this);@@ -150,21 +165,29 @@ export class Tools<}/**- * Applies the default schema modifiers to the tools+ * Applies the default schema modifiers to the tools.+ *+ * The `file_uploadable` transform (collapsing the backend's internal+ * `{ name, mimetype, s3key }` staging shape to `{ type: 'string',+ * format: 'path' }`) is **gated on `dangerouslyAllowAutoUploadDownloadFiles`**+ * — the collapsed shape is a promise that the SDK will stage local paths+ * on your behalf at execute time, and that's only true when the flag is on.+ *+ * When the flag is off, the raw schema is returned unchanged; callers are+ * expected to stage files themselves via `composio.files.upload()` and pass+ * the resulting descriptor into `tools.execute`. If an LLM ends up calling+ * a file-uploadable tool in this mode, the execute path emits a one-shot+ * warning per tool slug (see `applyBeforeExecuteModifiers`).+ ** @param tools - The tools to apply the default schema modifiers to* @returns The tools with the default schema modifiers applied*/private async applyDefaultSchemaModifiers(tools: Tool[]): Promise<Tool[]> {- if (this.autoUploadDownloadFiles) {- const fileToolModifier = new FileToolModifier(this.client, this.fileUploadPathOptions);- return await Promise.all(- tools.map(tool =>- fileToolModifier.modifyToolSchema(tool.slug, tool.toolkit?.slug ?? 'unknown', tool)- )- );- } else {+ if (!this.autoUploadDownloadFiles) {return tools;}+ const fileToolModifier = new FileToolModifier(this.client, this.fileUploadPathOptions);+ return await Promise.all(tools.map(tool => fileToolModifier.modifyToolSchema(tool)));}/**@@ -200,6 +223,26 @@ export class Tools<toolkitSlug,params: modifiedParams,});+ } else if (+ schemaHasFileUploadable(tool.inputParameters) &&+ !this.warnedAutoUploadDisabledForTool.has(toolSlug)+ ) {+ // With auto-upload off, the raw `{ name, mimetype, s3key }` shape is+ // what the LLM / caller sees on `tool.inputParameters`. LLMs can't+ // produce a valid `s3key` and will hallucinate one, which then fails+ // at the staging-lookup step on the backend. Nudge the caller toward+ // manual staging or opting into auto-upload.+ this.warnedAutoUploadDisabledForTool.add(toolSlug);+ logger.warn(+ `Tool "${toolSlug}" (toolkit "${toolkitSlug}") has a file-uploadable input, but ` ++ `\`dangerouslyAllowAutoUploadDownloadFiles\` is disabled. The SDK will forward ` ++ `the file argument as-is; if it isn't already a staged ` ++ `{ name, mimetype, s3key } descriptor, the backend will reject the call. Either:\n` ++ ` 1) Stage the file yourself: \`const f = await composio.files.upload({ file, toolSlug, toolkitSlug }); ` ++ `await composio.tools.execute('${toolSlug}', { userId, arguments: { <fileField>: f } })\`, or\n` ++ ` 2) Enable auto-upload with a scoped allowlist: ` ++ `\`new Composio({ dangerouslyAllowAutoUploadDownloadFiles: true, fileUploadDirs: ['/safe/dir'] })\`.`+ );}// apply the before execute modifiersif (modifiers?.beforeExecute) {diff --git a/ts/packages/core/src/platform/node.ts b/ts/packages/core/src/platform/node.tsindex 11947e322..ab7b110c3 100644--- a/ts/packages/core/src/platform/node.ts+++ b/ts/packages/core/src/platform/node.ts@@ -22,6 +22,14 @@ export const platform = {return path.join(...paths);},+ resolvePath(...paths: string[]): string {+ return path.resolve(...paths);+ },++ isAbsolutePath(filePath: string): boolean {+ return path.isAbsolute(filePath);+ },+basename(filePath: string): string {return path.basename(filePath);},diff --git a/ts/packages/core/src/platform/types.ts b/ts/packages/core/src/platform/types.tsindex e8393c886..87ffb5ad7 100644--- a/ts/packages/core/src/platform/types.ts+++ b/ts/packages/core/src/platform/types.ts@@ -16,6 +16,18 @@ export interface Platform {*/joinPath(...paths: string[]): string;+ /**+ * Resolves a sequence of paths into an absolute path. On Node this is+ * `path.resolve`; on edge runtimes without a working directory it+ * normalizes/joins the segments and returns the result verbatim.+ */+ resolvePath(...paths: string[]): string;++ /**+ * Returns true if the given path is absolute.+ */+ isAbsolutePath(filePath: string): boolean;+/*** Returns the last portion of a path (the filename).* @param filePath - The path to extract the basename from.diff --git a/ts/packages/core/src/platform/workerd.ts b/ts/packages/core/src/platform/workerd.tsindex 1dd4e500c..ee3b3d459 100644--- a/ts/packages/core/src/platform/workerd.ts+++ b/ts/packages/core/src/platform/workerd.ts@@ -26,6 +26,18 @@ export const platform: Platform = {.join('/');},+ resolvePath(...paths: string[]): string {+ // No working directory in edge runtimes. Best-effort: join the segments+ // and return the result. Callers that need a real `path.resolve` should+ // gate on `supportsFileSystem`.+ return this.joinPath(...paths);+ },++ isAbsolutePath(filePath: string): boolean {+ // POSIX-only check; edge runtimes don't have Windows-style drive letters.+ return filePath.startsWith('/');+ },+basename(filePath: string): string {// Simple basename extraction without Node.js path moduleconst segments = filePath.replace(/\/+$/, '').split('/');diff --git a/ts/packages/core/src/types/modifiers.types.ts b/ts/packages/core/src/types/modifiers.types.tsindex 9966c462f..38768863e 100644--- a/ts/packages/core/src/types/modifiers.types.ts+++ b/ts/packages/core/src/types/modifiers.types.ts@@ -180,12 +180,30 @@ export type afterExecuteModifier = (context: {}) => Promise<ToolExecuteResponse> | ToolExecuteResponse;/**- * Called for each `file_uploadable` value before the SDK reads the file and uploads to storage.- * For a string, `path` is the local path or URL. For a `File` object, `path` is the file's name; you may return- * a different filesystem path to upload instead, or return `false` to abort the upload. Throwing an error also aborts.+ * Discriminates what kind of input the hook is seeing:+ *+ * - `'path'` — a local filesystem path string.+ * - `'url'` — an `http(s)://...` URL string.+ * - `'file'` — a `File` object; `path` holds `file.name` (a filename, NOT a+ * filesystem path). Returning a string from the hook in this case replaces+ * the `File` with a local-path upload.+ */+export type BeforeFileUploadSource = 'path' | 'url' | 'file';++/**+ * Called for each `file_uploadable` value before the SDK reads the file and+ * uploads to storage.+ *+ * - `context.path` holds the local path, the URL, or the `File`'s name+ * depending on `context.source`.+ * - Return a string to replace the input (e.g. rewrite the path, redirect a+ * URL, or swap a `File` for a filesystem path).+ * - Return `false` to abort the upload with `ComposioFileUploadAbortedError`.+ * - Throwing an error also aborts.*/export type beforeFileUploadModifier = (context: {path: string;+ source: BeforeFileUploadSource;toolSlug: string;toolkitSlug: string;}) => Promise<string | false> | string | false;diff --git a/ts/packages/core/src/utils/config-defaults/ConfigDefaults.node.ts b/ts/packages/core/src/utils/config-defaults/ConfigDefaults.node.tsindex d83d095c5..aab05cb72 100644--- a/ts/packages/core/src/utils/config-defaults/ConfigDefaults.node.ts+++ b/ts/packages/core/src/utils/config-defaults/ConfigDefaults.node.ts@@ -1,7 +1,7 @@import type { ConfigDefaults } from './types';export const CONFIG_DEFAULTS: ConfigDefaults = {- autoUploadDownloadFiles: true,+ dangerouslyAllowAutoUploadDownloadFiles: false,allowTracking: true,toolkitVersions: 'latest',};diff --git a/ts/packages/core/src/utils/config-defaults/ConfigDefaults.workerd.ts b/ts/packages/core/src/utils/config-defaults/ConfigDefaults.workerd.tsindex 76550bf67..0a3ab621a 100644--- a/ts/packages/core/src/utils/config-defaults/ConfigDefaults.workerd.ts+++ b/ts/packages/core/src/utils/config-defaults/ConfigDefaults.workerd.ts@@ -4,7 +4,7 @@ export const CONFIG_DEFAULTS: ConfigDefaults = {/*** We don't support auto-uploading/download files in Cloudflare Workers yet.*/- autoUploadDownloadFiles: false,+ dangerouslyAllowAutoUploadDownloadFiles: false,allowTracking: true,toolkitVersions: 'latest',};diff --git a/ts/packages/core/src/utils/config-defaults/types.ts b/ts/packages/core/src/utils/config-defaults/types.tsindex 4e4ba2b39..625d3bb48 100644--- a/ts/packages/core/src/utils/config-defaults/types.ts+++ b/ts/packages/core/src/utils/config-defaults/types.ts@@ -9,6 +9,6 @@ import type { BaseComposioProvider } from '../../provider/BaseProvider';export type ConfigDefaults = Required<Pick<ComposioConfig<BaseComposioProvider<never, never, never>>,- 'autoUploadDownloadFiles' | 'allowTracking' | 'toolkitVersions'+ 'dangerouslyAllowAutoUploadDownloadFiles' | 'allowTracking' | 'toolkitVersions'>>;diff --git a/ts/packages/core/src/utils/fileDirs.ts b/ts/packages/core/src/utils/fileDirs.tsnew file mode 100644index 000000000..e60dfe244--- /dev/null+++ b/ts/packages/core/src/utils/fileDirs.ts@@ -0,0 +1,81 @@+/**+ * Runtime-neutral helpers for normalizing user-provided filesystem paths.+ *+ * In filesystem-less runtimes (Cloudflare Workers, etc.) the platform+ * abstraction reports `supportsFileSystem: false` and `homedir()` returns+ * `null`. We use that as the signal to drop unresolvable entries from the+ * allowlist (fail-closed) rather than silently passing `~/foo` through as+ * a literal directory name.+ */++import { platform } from '#platform';++/**+ * Expands a leading `~` to the user's home directory and resolves to an+ * absolute path. Returns `undefined` when expansion is required but no+ * home directory is available — that signals "unusable, drop me" to+ * {@link expandHomeAndResolveMany}, which is safer than letting the literal+ * `~/foo` survive as a CWD-relative path.+ */+export function expandHomeAndResolve(p: string | undefined): string | undefined {+ if (!p) return p;+ let expanded = p;+ if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {+ const home = platform.homedir();+ if (!home) return undefined;+ expanded = p === '~' ? home : platform.joinPath(home, p.slice(2));+ }+ return platform.resolvePath(expanded);+}++/**+ * Applies {@link expandHomeAndResolve} to each entry, dropping empty/invalid+ * values. Preserves `undefined` and `false` (so downstream can distinguish+ * "user did not configure" from "user explicitly disabled local uploads"+ * from "user configured []").+ */+export function expandHomeAndResolveMany(+ list: string[] | false | undefined+): string[] | false | undefined {+ if (list === undefined) return undefined;+ if (list === false) return false;+ const out: string[] = [];+ for (const raw of list) {+ if (typeof raw !== 'string' || raw.trim() === '') continue;+ const resolved = expandHomeAndResolve(raw);+ if (resolved) out.push(resolved);+ }+ return out;+}++/**+ * Absolute path of the default upload staging directory+ * (`<home>/.composio/temp`), or `null` when a home directory is unavailable+ * (e.g. Cloudflare Workers).+ */+export function getDefaultUploadDir(): string | null {+ const home = platform.homedir();+ if (!home) return null;+ return platform.resolvePath(platform.joinPath(home, '.composio', 'temp'));+}++/**+ * Resolve the effective upload allowlist for a given user-provided value.+ *+ * - `undefined` → `[<default>]` when a home directory is available, else `[]`+ * (fail-closed if we can't derive the default staging dir).+ * - `false` → `[]` (explicit "reject all local paths"). URLs / File objects+ * still work because they aren't path-checked.+ * - `string[]` (including `[]`) replaces the default and is returned+ * verbatim after `~` expansion / `path.resolve`. `[]` is treated as+ * equivalent to `false`.+ */+export function resolveEffectiveUploadAllowlist(userDirs: string[] | false | undefined): string[] {+ if (userDirs === undefined) {+ const def = getDefaultUploadDir();+ return def ? [def] : [];+ }+ if (userDirs === false) return [];+ const resolved = expandHomeAndResolveMany(userDirs);+ return Array.isArray(resolved) ? resolved : [];+}diff --git a/ts/packages/core/src/utils/fileUtils.node.ts b/ts/packages/core/src/utils/fileUtils.node.tsindex 3d907e0dc..05ac20b27 100644--- a/ts/packages/core/src/utils/fileUtils.node.ts+++ b/ts/packages/core/src/utils/fileUtils.node.ts@@ -8,6 +8,7 @@ import { getRandomShortId } from './uuid';import { base64ToUint8Array, uint8ArrayToBase64 } from './buffer';import type { FileDownloadData, FileUploadData } from '../types/files.types';import { assertSafeFileUploadPath } from './sensitiveFileUploadPaths.node';+import { assertPathInsideUploadDirs } from './uploadDirAllowlist.node';/*** Options for {@link getFileDataAfterUploadingToS3} (S3 presigned upload from local path, URL, or File).@@ -26,6 +27,15 @@ export type GetFileDataAfterUploadingToS3Options = {* merged with the built-in list.*/fileUploadPathDenySegments?: string[];+ /**+ * When provided, the local path must resolve inside one of these directories+ * (after symlink resolution, on a component boundary) or upload is rejected.+ * Intended for automatic upload during tool execution; manual+ * `composio.files.upload()` calls pass `undefined` here to skip enforcement.+ *+ * An empty array means "no paths are allowed" (fail-closed).+ */+ fileUploadAllowlist?: string[];};// Helper function to get file extension from MIME type@@ -244,18 +254,23 @@ export const getFileDataAfterUploadingToS3 = async (client,sensitiveFileUploadProtection,fileUploadPathDenySegments,+ fileUploadAllowlist,}: GetFileDataAfterUploadingToS3Options): Promise<FileUploadData> => {if (!file) {throw new Error('Either path or blob must be provided');}- if (- sensitiveFileUploadProtection !== false &&- typeof file === 'string' &&- !file.startsWith('http')- ) {- assertSafeFileUploadPath(file, { additionalDenySegments: fileUploadPathDenySegments });+ const isLocalPath = typeof file === 'string' && !file.startsWith('http');++ if (isLocalPath && fileUploadAllowlist !== undefined) {+ assertPathInsideUploadDirs(file as string, fileUploadAllowlist);+ }++ if (sensitiveFileUploadProtection !== false && isLocalPath) {+ assertSafeFileUploadPath(file as string, {+ additionalDenySegments: fileUploadPathDenySegments,+ });}const fileData = await readFile(file);@@ -281,10 +296,16 @@ export const downloadFileFromS3 = async ({toolSlug,s3Url,mimeType,+ fileDownloadDir,}: {toolSlug: string;s3Url: string;mimeType: string;+ /**+ * Absolute path to the directory to save the file into. When omitted, falls+ * back to `<home>/.composio/files` (the legacy default).+ */+ fileDownloadDir?: string;}): Promise<FileDownloadData> => {const response = await fetch(s3Url);if (!response.ok) {@@ -294,7 +315,10 @@ export const downloadFileFromS3 = async ({const extension = getExtensionFromMimeType(mimeType);const fileName = generateTimestampedFilename(extension, `${toolSlug}_`);- const filePath = saveFile(fileName, new Uint8Array(data), true);+ const filePath = saveFile(fileName, new Uint8Array(data), {+ isTempFile: fileDownloadDir === undefined,+ outputDir: fileDownloadDir,+ });return {name: fileName,mimeType: mimeType,@@ -354,23 +378,50 @@ export const getComposioTempFilesDir = (createDirIfNotExists: boolean = false) =};/**- * Saves a file to the Composio directory.- * @param file - The name of the file to save.- * @param content - The content of the file to save. Can be a string or Uint8Array.- * @param isTempFile - Whether the file is a temporary file.- * @returns The path to the saved file.+ * Saves a file to a local directory.+ *+ * Directory precedence (highest first):+ * 1. `options.outputDir` (explicit, absolute or relative; created if missing)+ * 2. `options.isTempFile === true` → `<home>/.composio/files`+ * 3. fallback → `<home>/.composio`+ *+ * @returns The absolute path to the saved file, or `null` if the runtime has+ * no filesystem (e.g. Cloudflare Workers) or the save failed.*/export const saveFile = (file: string,content: string | Uint8Array,- isTempFile: boolean = false+ options: { isTempFile?: boolean; outputDir?: string } | boolean = {}) => {+ // Back-compat: legacy callers passed a boolean `isTempFile` positional.+ const opts: { isTempFile?: boolean; outputDir?: string } =+ typeof options === 'boolean' ? { isTempFile: options } : options;+try {if (!platform.supportsFileSystem) {logger.debug('File system operations are not supported in this runtime environment');return null;}- const composioFilesDir = isTempFile ? getComposioTempFilesDir(true) : getComposioDir(true);++ let composioFilesDir: string | null | undefined;+ if (opts.outputDir) {+ const absDir = platform.joinPath(opts.outputDir); // platform.joinPath normalizes+ try {+ if (!platform.existsSync(absDir)) {+ platform.mkdirSync(absDir);+ }+ composioFilesDir = absDir;+ } catch (err) {+ logger.warn(+ `fileDownloadDir "${absDir}" is not writable, falling back to the default ` ++ `(~/.composio/files). Error: ${err}`+ );+ composioFilesDir = getComposioTempFilesDir(true);+ }+ } else {+ composioFilesDir = opts.isTempFile ? getComposioTempFilesDir(true) : getComposioDir(true);+ }+if (!composioFilesDir) {return null;}diff --git a/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts b/ts/packages/core/src/utils/modifiers/FileToolModifier.node.tsindex ff6c31efd..f3809eb00 100644--- a/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts+++ b/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts@@ -7,8 +7,10 @@ import {import ComposioClient from '@composio/client';import logger from '../logger';import {+ ComposioFileNotFoundError,ComposioFileUploadAbortedError,ComposioFileUploadError,+ ComposioFileUploadPathNotAllowedError,ComposioSensitiveFilePathBlockedError,} from '../../errors/FileModifierErrors';import type { beforeFileUploadModifier } from '../../types/modifiers.types';@@ -39,7 +41,7 @@ const hydrateFiles = async (client: ComposioClient;} & Pick<GetFileDataAfterUploadingToS3Options,- 'sensitiveFileUploadProtection' | 'fileUploadPathDenySegments'+ 'sensitiveFileUploadProtection' | 'fileUploadPathDenySegments' | 'fileUploadAllowlist'> & {beforeFileUpload?: beforeFileUploadModifier;}@@ -51,12 +53,16 @@ const hydrateFiles = async (// Upload only if the runtime value is a string (i.e., a local path) or blobif (typeof value !== 'string' && !(value instanceof File)) return value;- const runBeforeFileUpload = async (path: string): Promise<string> => {+ const runBeforeFileUpload = async (+ path: string,+ source: 'path' | 'url' | 'file'+ ): Promise<string> => {if (!ctx.beforeFileUpload) {return path;}const out = await ctx.beforeFileUpload({path,+ source,toolSlug: ctx.toolSlug,toolkitSlug: ctx.toolkitSlug,});@@ -69,7 +75,10 @@ const hydrateFiles = async (};if (typeof value === 'string') {- const pathOrUrl = await runBeforeFileUpload(value);+ // Match the URL/local-path split used downstream in+ // getFileDataAfterUploadingToS3 so the hook sees the same categorisation.+ const source = value.startsWith('http') ? 'url' : 'path';+ const pathOrUrl = await runBeforeFileUpload(value, source);logger.debug(`Uploading file "${pathOrUrl}"`);return getFileDataAfterUploadingToS3(pathOrUrl, {toolSlug: ctx.toolSlug,@@ -77,13 +86,16 @@ const hydrateFiles = async (client: ctx.client,sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,+ fileUploadAllowlist: ctx.fileUploadAllowlist,});}- // File+ // File — `path` is the filename only; a string return replaces it with a+ // local-path upload.if (ctx.beforeFileUpload) {const out = await ctx.beforeFileUpload({path: value.name,+ source: 'file',toolSlug: ctx.toolSlug,toolkitSlug: ctx.toolkitSlug,});@@ -100,10 +112,12 @@ const hydrateFiles = async (client: ctx.client,sensitiveFileUploadProtection: ctx.sensitiveFileUploadProtection,fileUploadPathDenySegments: ctx.fileUploadPathDenySegments,+ fileUploadAllowlist: ctx.fileUploadAllowlist,});}}logger.debug(`Uploading file "${value.name}"`);+ // File/Blob values are not subject to the upload-dir allowlist.return getFileDataAfterUploadingToS3(value, {toolSlug: ctx.toolSlug,toolkitSlug: ctx.toolkitSlug,@@ -114,7 +128,14 @@ const hydrateFiles = async (}// ──────────────────────────────────────────────────────────────────────────- // 2. Handle anyOf/oneOf/allOf - try each variant that may contain file_uploadable+ // 2. Handle anyOf/oneOf/allOf — pick the first variant that contains a+ // file_uploadable property and hydrate against it.+ //+ // We deliberately do NOT loop over every uploadable variant. With `oneOf`,+ // exactly one variant should apply at runtime, and applying multiple would+ // upload the same file once per variant — two presigned-URL round-trips and+ // two S3 PUTs for a two-variant `oneOf`. Matching the Python SDK+ // (`_find_uploadable_schema_variant`), we short-circuit on the first match.// ──────────────────────────────────────────────────────────────────────────const schemaVariants = [...(schema?.anyOf ?? []),@@ -123,16 +144,9 @@ const hydrateFiles = async (];if (schemaVariants.length > 0) {- // Find variants that have file_uploadable properties- const uploadableVariants = schemaVariants.filter(schemaHasFileUploadable);-- if (uploadableVariants.length > 0) {- // Process with each uploadable variant - we try all since we can't know which one matches at runtime- let result = value;- for (const variant of uploadableVariants) {- result = await hydrateFiles(result, variant, ctx);- }- return result;+ const firstUploadableVariant = schemaVariants.find(schemaHasFileUploadable);+ if (firstUploadableVariant) {+ return hydrateFiles(value, firstUploadableVariant, ctx);}// If no uploadable variants found, fall through to check base properties}@@ -172,7 +186,7 @@ const hydrateFiles = async (*/const downloadS3File = async (value: Record<string, unknown>,- ctx: { toolSlug: string }+ ctx: { toolSlug: string; fileDownloadDir?: string }): Promise<unknown> => {const { s3url, mimetype } = value as {s3url: string;@@ -186,6 +200,7 @@ const downloadS3File = async (toolSlug: ctx.toolSlug,s3Url: s3url,mimeType: mimetype ?? 'application/octet-stream',+ fileDownloadDir: ctx.fileDownloadDir,});logger.debug(`Downloaded → ${dl.filePath}`);@@ -223,7 +238,7 @@ const downloadS3File = async (const hydrateDownloads = async (value: unknown,schema: JSONSchemaProperty | undefined,- ctx: { toolSlug: string }+ ctx: { toolSlug: string; fileDownloadDir?: string }): Promise<unknown> => {// ──────────────────────────────────────────────────────────────────────────// 1. Direct S3 reference (data-driven detection)@@ -304,8 +319,8 @@ export class FileToolModifier {private client: ComposioClient;private fileUploadPathOptions: Pick<GetFileDataAfterUploadingToS3Options,- 'sensitiveFileUploadProtection' | 'fileUploadPathDenySegments'- > & { beforeFileUpload?: beforeFileUploadModifier };+ 'sensitiveFileUploadProtection' | 'fileUploadPathDenySegments' | 'fileUploadAllowlist'+ > & { beforeFileUpload?: beforeFileUploadModifier; fileDownloadDir?: string };constructor(client: ComposioClient,@@ -315,7 +330,7 @@ export class FileToolModifier {this.fileUploadPathOptions = fileUploadPathOptions;}- async modifyToolSchema(toolSlug: string, toolkitSlug: string, schema: Tool): Promise<Tool> {+ async modifyToolSchema(schema: Tool): Promise<Tool> {if (!schema.inputParameters?.properties) {return schema;}@@ -356,7 +371,9 @@ export class FileToolModifier {} catch (error) {if (error instanceof ComposioSensitiveFilePathBlockedError ||- error instanceof ComposioFileUploadAbortedError+ error instanceof ComposioFileUploadAbortedError ||+ error instanceof ComposioFileUploadPathNotAllowedError ||+ error instanceof ComposioFileNotFoundError) {throw error;}@@ -379,6 +396,7 @@ export class FileToolModifier {// Walk result.data without mutating the original, using output schema for guidanceconst dataWithDownloads = await hydrateDownloads(result.data, tool.outputParameters, {toolSlug,+ fileDownloadDir: this.fileUploadPathOptions.fileDownloadDir,});return { ...result, data: dataWithDownloads as typeof result.data };diff --git a/ts/packages/core/src/utils/modifiers/FileToolModifier.workerd.ts b/ts/packages/core/src/utils/modifiers/FileToolModifier.workerd.tsindex a217c8904..c38c81e6c 100644--- a/ts/packages/core/src/utils/modifiers/FileToolModifier.workerd.ts+++ b/ts/packages/core/src/utils/modifiers/FileToolModifier.workerd.ts@@ -4,12 +4,12 @@ import { transformProperties } from './FileToolModifier.utils.neutral';const UNSUPPORTED_MESSAGE ='File upload/download modifiers are not available on edge runtimes yet. ' +- 'Please set `autoUploadDownloadFiles: false` or run Composio in another JS runtime (Node.js / Bun).';+ 'Please set `dangerouslyAllowAutoUploadDownloadFiles: false` (or unset it; it defaults to false) or run Composio in another JS runtime (Node.js / Bun).';export class FileToolModifier {constructor(_client: ComposioClient) {}- async modifyToolSchema(toolSlug: string, toolkitSlug: string, schema: Tool): Promise<Tool> {+ async modifyToolSchema(schema: Tool): Promise<Tool> {if (!schema.inputParameters?.properties) {return schema;}diff --git a/ts/packages/core/src/utils/uploadDirAllowlist.node.ts b/ts/packages/core/src/utils/uploadDirAllowlist.node.tsnew file mode 100644index 000000000..923532534--- /dev/null+++ b/ts/packages/core/src/utils/uploadDirAllowlist.node.ts@@ -0,0 +1,178 @@+/**+ * Allowlist for automatic file upload during tool execution.+ *+ * This is only consulted when `dangerouslyAllowAutoUploadDownloadFiles` is enabled.+ * Manual `composio.files.upload()` calls are not subject to the allowlist.+ *+ * - A local path is accepted iff its real (symlink-resolved, absolute) path is+ * inside one of the allowed directories on a path-component boundary.+ * `/tmp/foo` allows `/tmp/foo/bar` but NOT `/tmp/foo-bar`.+ * - URLs (`http(s)://…`) and `File`/`Blob` values never hit this check.+ * - User-provided `fileUploadDirs` fully replaces the default `[~/.composio/temp]`.+ * - On Windows, path comparisons are case-insensitive.+ */+import * as path from 'node:path';+import fs from 'node:fs';+import {+ ComposioFileUploadPathNotAllowedError,+ ComposioFileNotFoundError,+} from '../errors/FileModifierErrors';++/**+ * Ensures the given directory exists (best-effort, non-throwing). Safe to call+ * during SDK init; allowlist enforcement still works even if creation fails.+ */+export function ensureDirExists(dir: string): void {+ try {+ fs.mkdirSync(dir, { recursive: true });+ } catch {+ // ignore+ }+}++function normalizeForCompare(p: string): string {+ return process.platform === 'win32' ? p.toLowerCase() : p;+}++/**+ * True if `child` is equal to `parent` or nested inside it on a component+ * boundary. Assumes both paths are absolute and normalized.+ */+function isInsideDir(child: string, parent: string): boolean {+ const a = normalizeForCompare(child);+ const b = normalizeForCompare(parent);+ if (a === b) return true;+ const sep = path.sep;+ const bWithSep = b.endsWith(sep) ? b : b + sep;+ return a.startsWith(bWithSep);+}++/**+ * Returns the real (symlink-resolved) absolute path when the target exists,+ * else `null`. Mirrors the semantics of the sensitive-path util.+ */+function tryRealpath(absPath: string): string | null {+ try {+ if (fs.existsSync(absPath)) {+ return fs.realpathSync(absPath);+ }+ } catch {+ // ignore and fall through+ }+ return null;+}++function formatAllowlist(dirs: string[]): string {+ if (dirs.length === 0) return ' (none configured \u2014 all local paths are blocked)';+ return dirs.map(d => ` - ${d}`).join('\n');+}++function buildHelpFooter(allowlist: string[]): string {+ return [+ '',+ 'Allowed upload directories (fileUploadDirs):',+ formatAllowlist(allowlist),+ '',+ 'Fix one of the following:',+ '',+ ' 1. Recommended \u2014 move the file under an allowed directory, or add your',+ ' directory to the allowlist:',+ ' new Composio({',+ " fileUploadDirs: ['/abs/path/to/uploads', '~/.composio/temp'],",+ ' })',+ ' Note: user-provided `fileUploadDirs` REPLACES the default',+ ' `~/.composio/temp`. Include it explicitly if you want staged uploads',+ ' to keep working.',+ '',+ ' 2. Pass the file by URL or as a File/Blob object instead of a filesystem',+ ' path. URLs and File objects are never path-checked.',+ '',+ ' 3. (Dangerous) Bypass the allowlist entirely by opting into automatic',+ ' file upload/download from any readable path:',+ ' new Composio({ dangerouslyAllowAutoUploadDownloadFiles: true })',+ ' WARNING: This lets a prompt-injected or misbehaving tool read ANY',+ ' file the process can access. Only enable it in trusted, sandboxed',+ ' environments. The built-in sensitive-path denylist (.ssh, .aws,',+ ' .env, private SSH keys, etc.) still applies unless you also set',+ ' `sensitiveFileUploadProtection: false`.',+ ].join('\n');+}++/**+ * @throws {ComposioFileNotFoundError} when `filePath` does not exist on disk.+ * @throws {ComposioFileUploadPathNotAllowedError} when the resolved path is+ * outside every entry of `allowlist`.+ */+export function assertPathInsideUploadDirs(filePath: string, allowlist: string[]): void {+ const attempted = filePath;+ const abs = path.resolve(filePath);+ const real = tryRealpath(abs);++ if (!real) {+ const cwd = process.cwd();+ const parent = path.dirname(abs);+ const parentExists = (() => {+ try {+ return fs.existsSync(parent);+ } catch {+ return false;+ }+ })();++ throw new ComposioFileNotFoundError(+ [+ `Refusing to auto-upload "${attempted}": the file does not exist on disk.`,+ '',+ `Path attempted: ${attempted}`,+ `Resolved to: ${abs}`,+ `Process cwd: ${cwd}`,+ `Parent exists: ${parentExists ? 'yes (' + parent + ')' : 'no (' + parent + ')'}`,+ '',+ 'Common causes:',+ ' - Typo in the filename passed to the tool.',+ ' - Relative path resolved against the wrong working directory',+ ' (relative paths use process.cwd() at the moment of upload).',+ ' - File was deleted between the tool being called and the upload starting.',+ '',+ buildHelpFooter(allowlist),+ ].join('\n'),+ { meta: { attempted, resolved: abs, cwd, allowlist } }+ );+ }++ if (allowlist.length === 0) {+ throw new ComposioFileUploadPathNotAllowedError(+ [+ `Refusing to auto-upload "${attempted}": no upload directories are configured.`,+ '',+ `Path attempted: ${attempted}`,+ `Resolved to: ${real}`,+ '',+ 'Automatic file upload during tool execution is locked down by default',+ 'to prevent a prompt-injected tool from exfiltrating server files',+ '(source code, .env, SSH keys, etc.).',+ buildHelpFooter(allowlist),+ ].join('\n'),+ { meta: { attempted, resolved: real, allowlist } }+ );+ }++ for (const dir of allowlist) {+ const realDir = tryRealpath(dir) ?? path.resolve(dir);+ if (isInsideDir(real, realDir)) {+ return;+ }+ }++ throw new ComposioFileUploadPathNotAllowedError(+ [+ `Refusing to auto-upload "${attempted}": resolved path is not inside any`,+ 'directory in the configured `fileUploadDirs` allowlist.',+ '',+ `Path attempted: ${attempted}`,+ `Resolved to: ${real}`,+ buildHelpFooter(allowlist),+ ].join('\n'),+ { meta: { attempted, resolved: real, allowlist } }+ );+}diff --git a/ts/packages/core/test/tools/fileModifiers.test.ts b/ts/packages/core/test/tools/fileModifiers.test.tsindex 06023bb41..3c6d80dc7 100644--- a/ts/packages/core/test/tools/fileModifiers.test.ts+++ b/ts/packages/core/test/tools/fileModifiers.test.ts@@ -41,7 +41,7 @@ describe('FileToolModifier', () => {availableVersions: ['20251201_01'],};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result).toEqual(schema);});@@ -67,7 +67,7 @@ describe('FileToolModifier', () => {},};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result.inputParameters?.properties?.file).toHaveProperty('format', 'path');expect(result.inputParameters?.properties?.text).not.toHaveProperty('format');});@@ -102,7 +102,7 @@ describe('FileToolModifier', () => {},};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result.inputParameters?.properties?.fileInput?.anyOf?.[0]).toHaveProperty('format','path'@@ -145,7 +145,7 @@ describe('FileToolModifier', () => {},};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result.inputParameters?.properties?.fileInput?.oneOf?.[0]).toHaveProperty('format','path'@@ -185,7 +185,7 @@ describe('FileToolModifier', () => {},};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result.inputParameters?.properties?.fileInput?.allOf?.[0]).toHaveProperty('format','path'@@ -230,7 +230,7 @@ describe('FileToolModifier', () => {},};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result.inputParameters?.properties?.content?.anyOf?.[0]?.properties?.attachment).toHaveProperty('format', 'path');@@ -268,7 +268,7 @@ describe('FileToolModifier', () => {},};- const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);+ const result = await fileToolModifier.modifyToolSchema(schema);expect(result.inputParameters?.properties?.files?.items?.anyOf?.[0]).toHaveProperty('format','path'@@ -371,6 +371,80 @@ describe('FileToolModifier', () => {expect(result.arguments?.file).toEqual(mockFileData);});+ it('should pass source="path" to beforeFileUpload for local filesystem paths', async () => {+ const mockFileData = {+ name: 'file.txt',+ mimetype: 'text/plain',+ s3key: 'uploads/file.txt',+ };+ vi.mocked(fileUtils.getFileDataAfterUploadingToS3).mockResolvedValue(mockFileData);++ const hook = vi.fn(async ({ path }) => path);+ const withHook = new FileToolModifier(mockClient, { beforeFileUpload: hook });++ await withHook.fileUploadModifier(mockTool, {+ toolSlug: 'test-tool',+ toolkitSlug: 'test-toolkit',+ params: { arguments: { file: '/path/to/a.txt' }, userId: 'u' },+ });++ expect(hook).toHaveBeenCalledWith(+ expect.objectContaining({ path: '/path/to/a.txt', source: 'path' })+ );+ });++ it('should pass source="url" to beforeFileUpload for http(s) URLs', async () => {+ const mockFileData = {+ name: 'file.txt',+ mimetype: 'text/plain',+ s3key: 'uploads/file.txt',+ };+ vi.mocked(fileUtils.getFileDataAfterUploadingToS3).mockResolvedValue(mockFileData);++ const hook = vi.fn(async ({ path }) => path);+ const withHook = new FileToolModifier(mockClient, { beforeFileUpload: hook });++ await withHook.fileUploadModifier(mockTool, {+ toolSlug: 'test-tool',+ toolkitSlug: 'test-toolkit',+ params: {+ arguments: { file: 'https://example.com/report.pdf' },+ userId: 'u',+ },+ });++ expect(hook).toHaveBeenCalledWith(+ expect.objectContaining({+ path: 'https://example.com/report.pdf',+ source: 'url',+ })+ );+ });++ it('should pass source="file" to beforeFileUpload for File objects', async () => {+ const mockFileData = {+ name: 'file.txt',+ mimetype: 'text/plain',+ s3key: 'uploads/file.txt',+ };+ vi.mocked(fileUtils.getFileDataAfterUploadingToS3).mockResolvedValue(mockFileData);++ const hook = vi.fn(async () => undefined as unknown as string);+ const withHook = new FileToolModifier(mockClient, { beforeFileUpload: hook });++ const fileObject = new File(['x'], 'uploaded.txt', { type: 'text/plain' });+ await withHook.fileUploadModifier(mockTool, {+ toolSlug: 'test-tool',+ toolkitSlug: 'test-toolkit',+ params: { arguments: { file: fileObject }, userId: 'u' },+ });++ // `path` is the File's name, not a filesystem path.+ expect(hook).toHaveBeenCalledWith(+ expect.objectContaining({ path: 'uploaded.txt', source: 'file' })+ );+ });+it('should throw ComposioFileUploadAbortedError when beforeFileUpload returns false', async () => {const withHook = new FileToolModifier(mockClient, {beforeFileUpload: async () => false,@@ -668,6 +742,54 @@ describe('FileToolModifier', () => {);});+ it('uploads once when multiple oneOf variants are file_uploadable', async () => {+ // Regression: previously hydrateFiles iterated over every uploadable+ // variant in anyOf/oneOf/allOf and re-uploaded the same file once per+ // variant. With `oneOf` semantics this is doubly wrong (only one+ // variant matches at runtime). Match the Python SDK and short-circuit+ // on the first uploadable variant.+ const mockFileData = {+ name: 'file.txt',+ mimetype: 'text/plain',+ s3key: 'uploads/file.txt',+ };+ vi.mocked(fileUtils.getFileDataAfterUploadingToS3).mockResolvedValue(mockFileData);++ const toolWithTwoUploadableVariants: Tool = {+ slug: 'test-tool',+ name: 'Test Tool',+ description: 'A test tool',+ tags: ['test'],+ inputParameters: {+ type: 'object',+ properties: {+ fileInput: {+ oneOf: [+ { type: 'string', file_uploadable: true },+ { type: 'string', file_uploadable: true },+ ],+ },+ },+ },+ version: '20251201_01',+ availableVersions: ['20251201_01'],+ };++ const params = {+ arguments: { fileInput: '/path/to/file.txt' },+ userId: 'test-user',+ };++ const result = await fileToolModifier.fileUploadModifier(toolWithTwoUploadableVariants, {+ toolSlug: 'test-tool',+ toolkitSlug: 'test-toolkit',+ params,+ });++ expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenCalledTimes(1);+ expect(result.arguments?.fileInput).toEqual(mockFileData);+ });+it('should not upload when value is null for anyOf with null variant', async () => {const toolWithAnyOf: Tool = {slug: 'test-tool',@@ -1326,7 +1448,7 @@ describe('FileToolModifier', () => {});});-describe('Tools with autoUploadDownloadFiles', () => {+describe('Tools with dangerouslyAllowAutoUploadDownloadFiles', () => {const context = createTestContext();setupTest(context);@@ -1410,11 +1532,11 @@ describe('Tools with autoUploadDownloadFiles', () => {availableVersions: ['20251201_01'],};- describe('when autoUploadDownloadFiles is false', () => {+ describe('when dangerouslyAllowAutoUploadDownloadFiles is false', () => {beforeEach(async () => {context.tools = new Tools(mockClient as unknown as ComposioClient, {provider: context.mockProvider,- autoUploadDownloadFiles: false,+ dangerouslyAllowAutoUploadDownloadFiles: false,});// Mock the tool execution@@ -1447,6 +1569,12 @@ describe('Tools with autoUploadDownloadFiles', () => {});it('should not modify tool schema for file upload', async () => {+ // The collapsed `{ type: 'string', format: 'path' }` shape is a promise+ // that the SDK will stage local paths for the caller. That promise is+ // only true when auto-upload is on, so we leave the raw shape+ // untouched when the flag is off — callers are expected to pre-stage+ // via `composio.files.upload()`. Runtime behavior is documented by+ // the warning emitted from `applyBeforeExecuteModifiers`.const result = await context.tools.getRawComposioTools({ tools: ['COMPOSIO_TOOL'] });expect(result[0].inputParameters?.properties?.file).not.toHaveProperty('format');expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();@@ -1481,6 +1609,35 @@ describe('Tools with autoUploadDownloadFiles', () => {});});+ it('warns once per tool when auto-upload is off and the tool has a file-uploadable input', async () => {+ const warnSpy = vi.spyOn((await import('../../src/utils/logger')).default, 'warn');+ warnSpy.mockImplementation(() => {}); // silence the log in test output++ vi.spyOn(context.tools, 'getRawComposioToolBySlug').mockResolvedValue(mockToolWithFileUpload);++ // First call emits the warning.+ await context.tools.execute('COMPOSIO_TOOL', {+ arguments: { file: '/path/to/file.txt' },+ userId: 'u',+ dangerouslySkipVersionCheck: true,+ });+ expect(warnSpy).toHaveBeenCalledTimes(1);+ const msg = String(warnSpy.mock.calls[0]?.[0] ?? '');+ expect(msg).toContain('COMPOSIO_TOOL');+ expect(msg).toContain('dangerouslyAllowAutoUploadDownloadFiles');+ expect(msg).toContain('composio.files.upload');++ // Repeated executions of the same tool do NOT re-warn.+ await context.tools.execute('COMPOSIO_TOOL', {+ arguments: { file: '/path/to/file.txt' },+ userId: 'u',+ dangerouslySkipVersionCheck: true,+ });+ expect(warnSpy).toHaveBeenCalledTimes(1);++ warnSpy.mockRestore();+ });+it('should not download files from execution results', async () => {// Mock getRawComposioToolBySlug for this testvi.spyOn(context.tools, 'getRawComposioToolBySlug').mockResolvedValueOnce(diff --git a/ts/packages/core/test/tools/fileUploadMatrix.test.ts b/ts/packages/core/test/tools/fileUploadMatrix.test.tsnew file mode 100644index 000000000..eda8e350c--- /dev/null+++ b/ts/packages/core/test/tools/fileUploadMatrix.test.ts@@ -0,0 +1,281 @@+/**+ * Behavior matrix for the file upload / download gating introduced with+ * `fileUploadDirs` and `fileDownloadDir`. Exercises the interaction between:+ *+ * - `dangerouslyAllowAutoUploadDownloadFiles` (off | on)+ * - Caller (automatic via `tools.execute` | manual via `composio.files.*`)+ * - Direction (upload | download)+ * - `fileUploadDirs` shape (`undefined`, `false`, `[]`, `string[]`)+ *+ * Runtime filesystem operations and HTTP are mocked; we only assert what the+ * SDK tries to do and what errors it raises.+ */++import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';+import * as os from 'node:os';+import * as path from 'node:path';+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';+import ComposioClient from '@composio/client';++import { Tools } from '../../src/models/Tools';+import { Files } from '../../src/models/Files.node';+import * as fileUtilsModule from '../../src/utils/fileUtils.node';+import { mockClient } from '../utils/mocks/client.mock';+import { MockProvider } from '../utils/mocks/provider.mock';+import {+ ComposioFileUploadPathNotAllowedError,+ ComposioFileNotFoundError,+} from '../../src/errors/FileModifierErrors';+import { getDefaultUploadDir } from '../../src/utils/fileDirs';++// Mock network-bound helpers so we can assert inputs without hitting the API.+vi.mock('../../src/utils/fileUtils.node', async importOriginal => {+ const actual = await importOriginal<typeof import('../../src/utils/fileUtils.node')>();+ return {+ ...actual,+ downloadFileFromS3: vi.fn(),+ // Keep the real `getFileDataAfterUploadingToS3` so path checks run, but+ // stub the S3 upload happening inside it.+ uploadFileToS3: vi.fn(),+ };+});++const mkTemp = () => mkdtempSync(path.join(os.tmpdir(), 'composio-matrix-'));++const makeTools = (opts: {+ dangerouslyAllowAutoUploadDownloadFiles?: boolean;+ fileUploadDirs?: string[] | false;+ fileDownloadDir?: string;+}) => {+ return new Tools(mockClient as unknown as ComposioClient, {+ provider: new MockProvider(),+ ...opts,+ });+};++describe('File handling matrix — Tools constructor resolves allowlist correctly', () => {+ afterEach(() => vi.clearAllMocks());++ describe('dangerouslyAllowAutoUploadDownloadFiles = false (default)', () => {+ it('leaves fileUploadAllowlist undefined (auto-upload code path is never run)', () => {+ const t = makeTools({});+ // `fileUploadAllowlist` lives on the private options the class forwards+ // to FileToolModifier. When the flag is off we leave it undefined so the+ // modifier isn't even constructed.+ expect(+ (t as unknown as { fileUploadPathOptions: { fileUploadAllowlist?: string[] } })+ .fileUploadPathOptions.fileUploadAllowlist+ ).toBeUndefined();+ });++ it('ignores fileUploadDirs entirely (including `false`)', () => {+ const t = makeTools({ fileUploadDirs: false });+ expect(+ (t as unknown as { fileUploadPathOptions: { fileUploadAllowlist?: string[] } })+ .fileUploadPathOptions.fileUploadAllowlist+ ).toBeUndefined();+ });+ });++ describe('dangerouslyAllowAutoUploadDownloadFiles = true', () => {+ it('defaults fileUploadAllowlist to [~/.composio/temp] when fileUploadDirs is unset', () => {+ const t = makeTools({ dangerouslyAllowAutoUploadDownloadFiles: true });+ const opts = (t as unknown as { fileUploadPathOptions: { fileUploadAllowlist?: string[] } })+ .fileUploadPathOptions;+ expect(opts.fileUploadAllowlist).toEqual([getDefaultUploadDir()]);+ });++ it('resolves to [] when fileUploadDirs is `false` (explicit "no local paths")', () => {+ const t = makeTools({+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: false,+ });+ const opts = (t as unknown as { fileUploadPathOptions: { fileUploadAllowlist?: string[] } })+ .fileUploadPathOptions;+ expect(opts.fileUploadAllowlist).toEqual([]);+ });++ it('resolves to [] when fileUploadDirs is `[]` (alias for `false`)', () => {+ const t = makeTools({+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: [],+ });+ const opts = (t as unknown as { fileUploadPathOptions: { fileUploadAllowlist?: string[] } })+ .fileUploadPathOptions;+ expect(opts.fileUploadAllowlist).toEqual([]);+ });++ it('uses user-provided dirs verbatim when fileUploadDirs is a non-empty array', () => {+ const dir = mkTemp();+ try {+ const t = makeTools({+ dangerouslyAllowAutoUploadDownloadFiles: true,+ fileUploadDirs: [dir],+ });+ const opts = (t as unknown as { fileUploadPathOptions: { fileUploadAllowlist?: string[] } })+ .fileUploadPathOptions;+ expect(opts.fileUploadAllowlist).toEqual([path.resolve(dir)]);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });+ });+});++describe('File handling matrix — manual Files API bypasses the allowlist', () => {+ const mkClient = () =>+ ({+ baseURL: 'https://api.composio.dev',+ apiKey: 'test',+ }) as unknown as ComposioClient;++ beforeEach(() => vi.clearAllMocks());++ it('composio.files.upload() accepts a local path that is NOT in any allowlist', async () => {+ const tmp = mkTemp();+ try {+ const file = path.join(tmp, 'a.txt');+ writeFileSync(file, 'x');++ // Stub the actual S3 call so the manual upload can complete.+ const stubbed = vi.spyOn(fileUtilsModule, 'getFileDataAfterUploadingToS3');+ stubbed.mockResolvedValueOnce({ name: 'a.txt', mimetype: 'text/plain', s3key: 'k' });++ const files = new Files(mkClient());+ const result = await files.upload({+ file,+ toolSlug: 'T',+ toolkitSlug: 'tk',+ });++ expect(result.s3key).toBe('k');++ // The call must NOT include a `fileUploadAllowlist` — that's what keeps+ // manual upload unconstrained.+ const callArg = stubbed.mock.calls[0]?.[1] as { fileUploadAllowlist?: unknown };+ expect(callArg.fileUploadAllowlist).toBeUndefined();+ } finally {+ rmSync(tmp, { recursive: true, force: true });+ }+ });++ it('composio.files.download() works regardless of `dangerouslyAllowAutoUploadDownloadFiles`', async () => {+ const downloadMock = vi.spyOn(fileUtilsModule, 'downloadFileFromS3');+ downloadMock.mockResolvedValueOnce({+ name: 'x.txt',+ mimeType: 'text/plain',+ s3Url: 'https://s3.example/x',+ filePath: '/tmp/fake/x.txt',+ });++ const files = new Files(mkClient(), { fileDownloadDir: '/var/app/dl' });+ const res = await files.download({+ toolSlug: 'T',+ s3Url: 'https://s3.example/x',+ mimeType: 'text/plain',+ });++ expect(res.filePath).toBe('/tmp/fake/x.txt');+ // The manual download path forwards the configured `fileDownloadDir`.+ expect(downloadMock.mock.calls[0]?.[0]).toMatchObject({+ fileDownloadDir: '/var/app/dl',+ });+ });+});++describe('File handling matrix — auto upload honors the resolved allowlist', () => {+ let getFileDataSpy: ReturnType<typeof vi.spyOn>;++ beforeEach(() => {+ vi.clearAllMocks();+ // Keep the real implementation so allowlist enforcement runs, but stub the+ // S3 upload that happens inside it.+ getFileDataSpy = vi.spyOn(fileUtilsModule, 'uploadFileToS3' as never);+ (getFileDataSpy as unknown as { mockResolvedValue: (v: string) => void }).mockResolvedValue(+ 's3-key'+ );+ });++ const callUpload = async (file: string, fileUploadAllowlist: string[] | undefined) => {+ return fileUtilsModule.getFileDataAfterUploadingToS3(file, {+ toolSlug: 'T',+ toolkitSlug: 'tk',+ client: mockClient as unknown as ComposioClient,+ fileUploadAllowlist,+ });+ };++ it('rejects local paths outside the allowlist with ComposioFileUploadPathNotAllowedError', async () => {+ const allowed = mkTemp();+ const outside = mkTemp();+ try {+ const file = path.join(outside, 'leak.txt');+ writeFileSync(file, 'x');+ await expect(callUpload(file, [allowed])).rejects.toBeInstanceOf(+ ComposioFileUploadPathNotAllowedError+ );+ } finally {+ rmSync(allowed, { recursive: true, force: true });+ rmSync(outside, { recursive: true, force: true });+ }+ });++ it('rejects ALL local paths when allowlist is [] (the `false` / fail-closed case)', async () => {+ const tmp = mkTemp();+ try {+ const file = path.join(tmp, 'a.txt');+ writeFileSync(file, 'x');+ await expect(callUpload(file, [])).rejects.toBeInstanceOf(+ ComposioFileUploadPathNotAllowedError+ );+ } finally {+ rmSync(tmp, { recursive: true, force: true });+ }+ });++ it('allows URLs even when allowlist is [] (URLs are never path-checked)', async () => {+ // Stub global fetch so `readFile` (URL branch) doesn't hit the network.+ const fetchSpy = vi+ .spyOn(globalThis, 'fetch')+ .mockRejectedValueOnce(new Error('stubbed-network'));++ // Passes the allowlist gate (because the URL isn't a local path), then+ // fails at the network layer. Any non-allowlist error proves the gate+ // didn't reject the URL.+ const http = 'https://example.com/file.pdf';+ await expect(callUpload(http, [])).rejects.toThrowError('stubbed-network');+ expect(fetchSpy).toHaveBeenCalledTimes(1);+ });++ it('raises ComposioFileNotFoundError when the file is missing under auto-upload', async () => {+ const allowed = mkTemp();+ try {+ const missing = path.join(allowed, 'nope.txt');+ await expect(callUpload(missing, [allowed])).rejects.toBeInstanceOf(+ ComposioFileNotFoundError+ );+ } finally {+ rmSync(allowed, { recursive: true, force: true });+ }+ });++ it('does NOT throw an allowlist error when the file is inside an allowed dir', async () => {+ // We can't easily stub the S3 upload from outside the module, so we just+ // assert the error (if any) is not the allowlist rejection. The happy+ // path for `assertPathInsideUploadDirs` itself is covered directly in+ // `test/utils/uploadDirAllowlist.test.ts`.+ const allowed = mkTemp();+ try {+ const file = path.join(allowed, 'ok.txt');+ writeFileSync(file, 'x');+ try {+ await callUpload(file, [allowed]);+ } catch (err) {+ expect(err).not.toBeInstanceOf(ComposioFileUploadPathNotAllowedError);+ expect(err).not.toBeInstanceOf(ComposioFileNotFoundError);+ }+ } finally {+ rmSync(allowed, { recursive: true, force: true });+ }+ });+});diff --git a/ts/packages/core/test/utils/fileUtils.test.ts b/ts/packages/core/test/utils/fileUtils.test.tsindex 67ec74618..d413fb616 100644--- a/ts/packages/core/test/utils/fileUtils.test.ts+++ b/ts/packages/core/test/utils/fileUtils.test.ts@@ -335,6 +335,58 @@ describe('fileUtils', () => {})).rejects.toThrow('Failed to download file: Not Found');});++ it('synthesizes the filename server-side and ignores the s3Url path', async () => {+ // Regression: lock the invariant that the saved filename comes from+ // (toolSlug, mimeType, timestamp, random id) — never from the s3Url.+ // If a future change started reflecting the s3Url path or query into+ // the local filename, an attacker-controlled CDN response could write+ // outside the download dir or stomp on existing files.+ mockFetch.mockResolvedValue({+ ok: true,+ arrayBuffer: () => Promise.resolve(new ArrayBuffer(10)),+ });++ const result = await downloadFileFromS3({+ toolSlug: 'github',+ // The URL path contains traversal-looking segments and a totally+ // different "filename"; none of this should leak into result.name.+ s3Url:+ 'https://s3.example.com/../../../etc/passwd?response-content-disposition=attachment%3Bfilename%3Devil.sh',+ mimeType: 'text/plain',+ });++ expect(result.name).toBe('github_1640995200000abc12345.txt');+ expect(result.name).not.toContain('..');+ expect(result.name).not.toContain('/');+ expect(result.name).not.toContain('passwd');+ expect(result.name).not.toContain('evil');+ });++ it('strips path components from a path-laden toolSlug before saving', async () => {+ // Regression: the prefix is `${toolSlug}_`, so a slug containing `/`+ // could in theory smuggle path components into the saved filename.+ // `saveFile` defends against that by running the assembled filename+ // through `path.basename` before joining with the download dir.+ mockFetch.mockResolvedValue({+ ok: true,+ arrayBuffer: () => Promise.resolve(new ArrayBuffer(10)),+ });++ const result = await downloadFileFromS3({+ toolSlug: 'AAA/../etc/passwd',+ s3Url: 'https://s3.example.com/file.bin',+ mimeType: 'text/plain',+ });++ // `result.name` is the pre-basename string (raw composed name); the+ // actual on-disk path goes through `path.basename`. We assert that+ // the on-disk path stays under the download dir by checking the+ // returned filePath.+ expect(result.filePath).toBeDefined();+ expect(path.dirname(result.filePath as string)).not.toContain('etc');+ expect(path.basename(result.filePath as string)).toBe('passwd_1640995200000abc12345.txt');+ });});describe('File object handling', () => {diff --git a/ts/packages/core/test/utils/uploadDirAllowlist.test.ts b/ts/packages/core/test/utils/uploadDirAllowlist.test.tsnew file mode 100644index 000000000..a237df810--- /dev/null+++ b/ts/packages/core/test/utils/uploadDirAllowlist.test.ts@@ -0,0 +1,148 @@+import { describe, it, expect } from 'vitest';+import * as path from 'node:path';+import * as os from 'node:os';+import { mkdtempSync, writeFileSync, symlinkSync, rmSync, mkdirSync } from 'node:fs';+import { assertPathInsideUploadDirs } from '../../src/utils/uploadDirAllowlist.node';+import { resolveEffectiveUploadAllowlist, getDefaultUploadDir } from '../../src/utils/fileDirs';+import {+ ComposioFileNotFoundError,+ ComposioFileUploadPathNotAllowedError,+} from '../../src/errors/FileModifierErrors';++describe('resolveEffectiveUploadAllowlist', () => {+ it('returns the default [<home>/.composio/temp] when userDirs is undefined', () => {+ const out = resolveEffectiveUploadAllowlist(undefined);+ const def = getDefaultUploadDir();+ expect(def).not.toBeNull();+ expect(out).toEqual([def]);+ });++ it('returns [] (fail-closed) when user passes []', () => {+ expect(resolveEffectiveUploadAllowlist([])).toEqual([]);+ });++ it('returns [] when user passes `false` (explicit "no local paths")', () => {+ expect(resolveEffectiveUploadAllowlist(false)).toEqual([]);+ });++ it('replaces the default when user passes explicit dirs', () => {+ const dirs = ['/tmp/one', '/tmp/two'];+ const out = resolveEffectiveUploadAllowlist(dirs);+ expect(out).toEqual(dirs.map(d => path.resolve(d)));+ });++ it('expands leading ~ in entries', () => {+ const out = resolveEffectiveUploadAllowlist(['~/foo']);+ expect(out[0]).toBe(path.resolve(os.homedir(), 'foo'));+ });+});++describe('assertPathInsideUploadDirs', () => {+ const makeTempRoot = () => mkdtempSync(path.join(os.tmpdir(), 'composio-allowlist-'));++ it('accepts a file inside an allowed directory', () => {+ const root = makeTempRoot();+ try {+ const file = path.join(root, 'hello.txt');+ writeFileSync(file, 'hi');+ expect(() => assertPathInsideUploadDirs(file, [root])).not.toThrow();+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it('throws ComposioFileUploadPathNotAllowedError when path is outside all allowed dirs', () => {+ const root = makeTempRoot();+ const other = makeTempRoot();+ try {+ const file = path.join(root, 'hello.txt');+ writeFileSync(file, 'hi');+ expect(() => assertPathInsideUploadDirs(file, [other])).toThrow(+ ComposioFileUploadPathNotAllowedError+ );+ } finally {+ rmSync(root, { recursive: true, force: true });+ rmSync(other, { recursive: true, force: true });+ }+ });++ it('enforces component-boundary matching (does not treat sibling prefix as inside)', () => {+ const root = mkdtempSync(path.join(os.tmpdir(), 'composio-boundary-'));+ try {+ const allowed = path.join(root, 'uploads');+ const sibling = path.join(root, 'uploads-not-allowed');+ mkdirSync(allowed);+ mkdirSync(sibling);+ const file = path.join(sibling, 'leak.txt');+ writeFileSync(file, 'nope');+ expect(() => assertPathInsideUploadDirs(file, [allowed])).toThrow(+ ComposioFileUploadPathNotAllowedError+ );+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it('rejects paths that escape via symlink (realpath is enforced)', () => {+ const root = mkdtempSync(path.join(os.tmpdir(), 'composio-symesc-'));+ try {+ const allowed = path.join(root, 'allowed');+ const outside = path.join(root, 'outside');+ mkdirSync(allowed);+ mkdirSync(outside);+ const target = path.join(outside, 'secret.txt');+ writeFileSync(target, 'x');+ const link = path.join(allowed, 'innocent.txt');+ symlinkSync(target, link);+ expect(() => assertPathInsideUploadDirs(link, [allowed])).toThrow(+ ComposioFileUploadPathNotAllowedError+ );+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it('throws ComposioFileNotFoundError when the file does not exist', () => {+ const root = makeTempRoot();+ try {+ const missing = path.join(root, 'does-not-exist.txt');+ expect(() => assertPathInsideUploadDirs(missing, [root])).toThrow(ComposioFileNotFoundError);+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it('throws ComposioFileUploadPathNotAllowedError with empty allowlist (fail-closed)', () => {+ const root = makeTempRoot();+ try {+ const file = path.join(root, 'a.txt');+ writeFileSync(file, 'x');+ expect(() => assertPathInsideUploadDirs(file, [])).toThrow(+ ComposioFileUploadPathNotAllowedError+ );+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it('includes actionable guidance and the resolved path in the error message', () => {+ const root = makeTempRoot();+ try {+ const file = path.join(root, 'a.txt');+ writeFileSync(file, 'x');+ try {+ assertPathInsideUploadDirs(file, ['/tmp/definitely-not-here-xyz']);+ throw new Error('expected to throw');+ } catch (err) {+ expect(err).toBeInstanceOf(ComposioFileUploadPathNotAllowedError);+ const message = (err as Error).message;+ expect(message).toContain('fileUploadDirs');+ expect(message).toContain('dangerouslyAllowAutoUploadDownloadFiles');+ expect(message).toContain('~/.composio/temp');+ expect(message).toContain(file);+ }+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });+});