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
/* eslint-disable-next-line no-restricted-imports */
import crypto from 'node:crypto'; // we're in a Node.js-specific module
import { platform } from '#platform';
import ComposioClient from '@composio/client';
import { COMPOSIO_DIR, TEMP_FILES_DIRECTORY_NAME } from './constants';
import logger from './logger';
import { getRandomShortId } from './uuid';
import { base64ToUint8Array, uint8ArrayToBase64 } from './buffer';
import type { FileDownloadData, FileUploadData } from '../types/files.types';
import { assertSafeFileUploadPath } from './sensitiveFileUploadPaths';
import { assertPathInsideUploadDirs } from './uploadDirAllowlist.node';
import { ssrfSafeFetch } from './ssrfGuard.node';
import { readResponseBodyWithLimit } from './readResponseBody';
/**
* Options for {@link getFileDataAfterUploadingToS3} (S3 presigned upload from local path, URL, or File).
*/
export type GetFileDataAfterUploadingToS3Options = {
toolSlug: string;
toolkitSlug: string;
client: ComposioClient;
/**
* When false, skips the sensitive-path blocklist. URLs and {@link File} objects are never checked.
* @default true
*/
sensitiveFileUploadProtection?: boolean;
/**
* Extra path segments (one directory/file component) to block anywhere in the resolved path;
* 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[];
signal?: AbortSignal;
};
/**
* Checks whether `value` is an absolute http(s) URL rather than a local path.
*
* A bare `startsWith('http')` check also matches local paths like
* `http_export/report.csv` or `httpdocs/.env`, which routes them into the URL
* fetch branch and skips the allowlist/denylist checks in
* {@link getFileDataAfterUploadingToS3}. `new URL()` requires a real scheme
* (`http:` or `https:`) followed by `//`, so relative-looking paths correctly
* fail to parse and are treated as local.
*/
export const isHttpUrl = (value: string): boolean => {
try {
const url = new URL(value);
return url.protocol === 'http:' || url.protocol === 'https:';
} catch {
return false;
}
};
// Helper function to get file extension from MIME type
const getExtensionFromMimeType = (mimeType: string): string => {
const mimeToExt: Record<string, string> = {
'text/plain': 'txt',
'text/html': 'html',
'text/css': 'css',
'text/javascript': 'js',
'application/json': 'json',
'application/xml': 'xml',
'application/pdf': 'pdf',
'application/zip': 'zip',
'application/x-zip-compressed': 'zip',
'application/gzip': 'gz',
'application/x-tar': 'tar',
'application/msword': 'doc',
'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx',
'application/vnd.ms-excel': 'xls',
'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',
'application/vnd.ms-powerpoint': 'ppt',
'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'pptx',
'image/jpeg': 'jpg',
'image/jpg': 'jpg',
'image/png': 'png',
'image/gif': 'gif',
'image/svg+xml': 'svg',
'image/webp': 'webp',
'image/bmp': 'bmp',
'image/tiff': 'tiff',
'audio/mpeg': 'mp3',
'audio/wav': 'wav',
'audio/ogg': 'ogg',
'video/mp4': 'mp4',
'video/mpeg': 'mpeg',
'video/quicktime': 'mov',
'video/x-msvideo': 'avi',
'video/webm': 'webm',
};
// Clean the MIME type by removing parameters (e.g., "text/plain; charset=utf-8" -> "text/plain")
const cleanMimeType = mimeType.split(';')[0].toLowerCase().trim();
// Try exact match first
if (mimeToExt[cleanMimeType]) {
return mimeToExt[cleanMimeType];
}
// Try to extract from the MIME type (e.g., "image/png" -> "png")
const parts = cleanMimeType.split('/');
if (parts.length === 2) {
const subtype = parts[1].toLowerCase();
const cleanSubtype = subtype; // Already cleaned above
// Handle structured MIME types with + (e.g., "application/vnd.api+json" -> "json")
if (cleanSubtype.includes('+')) {
const plusParts = cleanSubtype.split('+');
const prefix = plusParts[0];
const suffix = plusParts[plusParts.length - 1]; // Get the part after the last +
// For specific formats, prefer the prefix (e.g., "atom+xml" -> "atom")
const knownPrefixes = ['svg', 'atom', 'rss'];
if (knownPrefixes.includes(prefix)) {
return prefix;
}
// For common structured suffixes, use the suffix (e.g., "vnd.api+json" -> "json")
const structuredSuffixes = ['json', 'xml', 'yaml', 'zip', 'gzip'];
if (structuredSuffixes.includes(suffix)) {
return suffix;
}
// Default to the suffix for other structured types
return suffix;
}
return cleanSubtype || 'txt';
}
return 'txt'; // Default fallback
};
// Helper function to generate a filename with timestamp and random ID
const generateTimestampedFilename = (extension: string, prefix?: string): string => {
const basePrefix = prefix || 'file_ts';
return `${basePrefix}${Date.now()}${getRandomShortId()}.${extension}`;
};
const readFileContent = async (
filePath: string
): Promise<{ fileName: string; content: string; mimeType: string }> => {
try {
if (!platform.supportsFileSystem) {
throw new Error('File system operations are not supported in this runtime environment');
}
const content = platform.readFileSync(filePath);
return {
fileName: generateTimestampedFilename(filePath.split('.').pop() || 'txt'),
content:
content instanceof Uint8Array
? uint8ArrayToBase64(content)
: uint8ArrayToBase64(new TextEncoder().encode(content)),
mimeType: 'application/octet-stream',
};
} catch (error) {
throw new Error(`Error reading file at ${filePath}: ${error}`);
}
};
const readFileContentFromURL = async (
path: string,
signal?: AbortSignal
): Promise<{ fileName: string; content: string; mimeType: string }> => {
// SSRF guard: `path` is user-supplied (and can come from an LLM-produced tool
// argument), so it must not be allowed to reach internal/private addresses or
// redirect into them. See ssrfGuard.node.ts.
const response = await ssrfSafeFetch(path, { signal });
if (!response.ok) {
// The error path never reads the body, so release it explicitly (mirrors
// `readResponseBodyWithLimit`) instead of leaving it to the garbage collector.
await response.body?.cancel().catch(() => undefined);
throw new Error(`Failed to fetch file: ${response.statusText}`);
}
const content = await readResponseBodyWithLimit(response);
const mimeType = response.headers.get('content-type') || 'application/octet-stream';
// Extract clean filename from URL, removing query parameters
const url = new URL(path);
const pathname = url.pathname;
let fileName = platform.basename(pathname);
// If no filename from URL, generate one with appropriate extension
if (!fileName || fileName === '/') {
// Try to get extension from mimeType
const extension = getExtensionFromMimeType(mimeType);
fileName = generateTimestampedFilename(extension);
} else {
// If filename has no extension, try to add one from mimeType
const hasExtension = fileName.includes('.');
if (!hasExtension) {
const extension = getExtensionFromMimeType(mimeType);
fileName = generateTimestampedFilename(extension);
}
}
return {
content: uint8ArrayToBase64(content),
mimeType,
fileName,
};
};
const uploadFileToS3 = async (
fileName: string,
content: string,
toolSlug: string,
toolkitSlug: string,
mimeType: string,
client: ComposioClient,
signal?: AbortSignal
): Promise<string> => {
const contentBytes = base64ToUint8Array(content);
const response = await client.files.createPresignedURL(
{
filename: fileName,
mimetype: mimeType,
md5: crypto.createHash('md5').update(contentBytes).digest('hex'),
tool_slug: toolSlug,
toolkit_slug: toolkitSlug,
},
{ signal }
);
const { key, new_presigned_url: signedURL } = response;
// Upload file using presigned URL
// Note: API now always returns type: 'new' with new_presigned_url
logger.debug(`Uploading ${key} file to S3: ${key}`);
// Create a new ArrayBuffer to ensure compatibility with fetch API
const uploadBuffer = new Uint8Array(contentBytes.byteLength);
uploadBuffer.set(contentBytes);
// Note: do not set `Content-Length` manually. Node.js's built-in fetch (undici)
// computes it from `body` and rejects any user-supplied value with
// `InvalidArgumentError: invalid content-length header`, which surfaces as
// `TypeError: fetch failed` and breaks every `file_uploadable` connector tool
// on Node 22+.
// SSRF guard: `new_presigned_url` comes from the API response, which the SDK
// treats as untrusted — a response naming an internal address would otherwise
// have the file's bytes PUT to it. See ssrfGuard.node.ts.
const uploadResponse = await ssrfSafeFetch(signedURL, {
method: 'PUT',
body: uploadBuffer,
signal,
headers: {
'Content-Type': mimeType,
},
});
if (!uploadResponse.ok) {
throw new Error(`Failed to upload file to S3: ${uploadResponse.statusText}`);
}
return key;
};
const readFile = async (
file: File | string,
signal?: AbortSignal
): Promise<{ fileName: string; content: string; mimeType: string }> => {
if (file instanceof File) {
const content = await file.arrayBuffer();
return {
fileName: file.name,
content: uint8ArrayToBase64(new Uint8Array(content)),
mimeType: file.type,
};
} else if (typeof file === 'string') {
if (isHttpUrl(file)) {
return await readFileContentFromURL(file, signal);
} else {
return await readFileContent(file);
}
}
throw new Error('Invalid file type');
};
export const getFileDataAfterUploadingToS3 = async (
file: File | string,
{
toolSlug,
toolkitSlug,
client,
sensitiveFileUploadProtection,
fileUploadPathDenySegments,
fileUploadAllowlist,
signal,
}: GetFileDataAfterUploadingToS3Options
): Promise<FileUploadData> => {
if (!file) {
throw new Error('Either path or blob must be provided');
}
const isLocalPath = typeof file === 'string' && !isHttpUrl(file);
if (isLocalPath && fileUploadAllowlist !== undefined) {
assertPathInsideUploadDirs(file as string, fileUploadAllowlist);
}
if (sensitiveFileUploadProtection !== false && isLocalPath) {
assertSafeFileUploadPath(file as string, {
additionalDenySegments: fileUploadPathDenySegments,
});
}
const fileData = await readFile(file, signal);
logger.debug(`Uploading file to S3...`);
const s3key = await uploadFileToS3(
platform.basename(fileData.fileName),
fileData.content,
toolSlug,
toolkitSlug,
fileData.mimeType,
client,
signal
);
logger.debug(`Done! File uploaded to S3: ${s3key}`, JSON.stringify(fileData, null, 2));
return {
name: fileData.fileName,
mimetype: fileData.mimeType,
s3key: s3key,
};
};
export const downloadFileFromS3 = async ({
toolSlug,
s3Url,
mimeType,
fileDownloadDir,
signal,
maxDownloadBytes,
}: {
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;
signal?: AbortSignal;
/**
* Maximum number of bytes to read from the response before rejecting.
* Defaults to {@link MAX_URL_UPLOAD_SIZE_BYTES} (100 MiB).
*/
maxDownloadBytes?: number;
}): Promise<FileDownloadData> => {
// SSRF guard: `s3Url` is a field of the tool-execution response, so it is no
// more trusted than a user-supplied URL — and the bytes it returns are
// written to disk. See ssrfGuard.node.ts.
const response = await ssrfSafeFetch(s3Url, { signal });
if (!response.ok) {
throw new Error(`Failed to download file: ${response.statusText}`);
}
// The response is attacker-influencable and streamed to disk, so the body is
// read through the shared size guard rather than buffered wholesale.
const data = await readResponseBodyWithLimit(response, maxDownloadBytes);
const extension = getExtensionFromMimeType(mimeType);
const fileName = generateTimestampedFilename(extension, `${toolSlug}_`);
const filePath = saveFile(fileName, data, {
isTempFile: fileDownloadDir === undefined,
outputDir: fileDownloadDir,
});
return {
name: fileName,
mimeType: mimeType,
s3Url: s3Url,
/**
* @todo: fix in follow-up PR.
*/
filePath: filePath as string,
};
};
/**
* Gets the Composio directory.
* @param createDirIfNotExists - Whether to create the directory if it doesn't exist.
* @returns The path to the Composio directory.
*/
export const getComposioDir = (createDirIfNotExists: boolean = false) => {
try {
const homeDir = platform.homedir();
if (!homeDir) {
return null;
}
const composioDir = platform.joinPath(homeDir, COMPOSIO_DIR);
if (createDirIfNotExists && platform.supportsFileSystem && !platform.existsSync(composioDir)) {
platform.mkdirSync(composioDir);
}
return composioDir;
} catch (_error) {
return null;
}
};
/**
* Gets the Composio temporary files directory.
* @param createDirIfNotExists - Whether to create the directory if it doesn't exist.
* @returns The path to the Composio temporary files directory.
*/
export const getComposioTempFilesDir = (createDirIfNotExists: boolean = false) => {
try {
const homeDir = platform.homedir();
if (!homeDir) {
return null;
}
const composioFilesDir = platform.joinPath(homeDir, COMPOSIO_DIR, TEMP_FILES_DIRECTORY_NAME);
if (
createDirIfNotExists &&
platform.supportsFileSystem &&
!platform.existsSync(composioFilesDir)
) {
platform.mkdirSync(composioFilesDir);
}
return composioFilesDir;
} catch (_error) {
return null;
}
};
/**
* 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,
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;
}
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;
}
const filePath = platform.joinPath(composioFilesDir, platform.basename(file));
logger.info(`Saving file to: ${filePath}`);
if (content instanceof Uint8Array) {
platform.writeFileSync(filePath, content);
} else {
platform.writeFileSync(filePath, content, 'utf8');
}
return filePath;
} catch (_error) {
logger.debug(`Error saving file: ${_error}`);
return null;
}
};