File Downloads & Sanitization

Relevant source files

The following files were used as context for generating this wiki page:

• stackone_ai/types.py
• stackone_ai/tools.py
• CLAUDE.md
• tests/test_tool_calling.py
• CHANGELOG.md

The StackOne AI SDK implements specialized handling for non-JSON responses to support file downloads from SaaS providers. When a tool execution returns a binary payload, the SDK bypasses standard JSON parsing to return raw bytes and associated metadata. This system protects against directory traversal and header injection attacks by sanitizing server-supplied filenames before exposing them to the user.

This module ensures that binary data, such as PDFs or documents from providers like Google Drive, are handled as opaque content rather than being forced through UTF-8 or JSON decoding.

Binary Response Handling

The SDK distinguishes between standard JSON API responses and binary file downloads based on the Content-Type header. If the response is not a recognized JSON media type, the StackOneTool.execute method returns a dictionary containing the raw bytes and file metadata.

The flow above describes how the SDK routes responses based on media types.
Sources: stackone_ai/tools.py:270-305, stackone_ai/types.py:73-82

Response Structure for Downloads

When a file is downloaded, the SDK returns a dictionary with the following fields:

Field	Type	Description
content	bytes	The raw binary payload of the file.
content_type	str	The MIME type from the server (defaults to application/octet-stream).
status_code	int	The HTTP response status code.
headers	dict	The complete dictionary of HTTP response headers.
file_name	str | None	The sanitized filename extracted from Content-Disposition.

Sources: stackone_ai/tools.py:299-305, tests/test_tool_calling.py:269-281

Filename Extraction & Sanitization

The SDK extracts filenames from the Content-Disposition header. It supports both standard filename="..." and RFC 5987 extended filename*=... formats. Because these values are often provided by third-party SaaS users, the SDK treats them as attacker-controlled and performs rigorous sanitization to prevent arbitrary file writes.

Extraction Logic

1. It searches for the RFC 5987 extended form, which takes precedence.
2. It percent-decodes the extended value using the declared charset (e.g., UTF-8 or ISO-8859-1).
3. It falls back to the standard quoted or bare filename if the extended form is absent.

Sources: stackone_ai/types.py:115-135, tests/test_tool_calling.py:382-402

Sanitization Procedures

The _safe_basename function reduces a supplied path to a safe, writable filename through the following steps:

• Path Traversal Prevention: It uses both posixpath and ntpath to extract only the final basename. This neutralizes attempts like ../../.ssh/authorized_keys or C:evil.exe.
• Control Character Removal: It strips Unicode categories Cc (control) and Cf (format) to prevent log injection and extension spoofing (e.g., using U+202E Right-to-Left Override).
• Length Capping: It truncates filenames to a maximum of 255 bytes while attempting to preserve the file extension.
• Reserved Name Filtering: It returns None if the resulting name is empty, ., or ...

Sources: stackone_ai/types.py:91-110, tests/test_tool_calling.py:461-483

The diagram shows the multi-stage sanitization process applied to server-supplied filenames.
Sources: stackone_ai/types.py:91-110

Security Guards

The SDK implements specific protections for both incoming and outgoing data related to tool execution and downloads.

Header Sanitization

When executing tools (especially meta-tools over MCP), the SDK validates headers against an allowlist derived from the served schema. This prevents model-controlled arguments from smuggling unauthorized credentials (like Authorization or x-account-id) into the request envelope.

• Reserved Headers: Headers like Authorization are stripped case-insensitively.
• CRLF Injection: Header values are validated with a strict regex ([\x20-\x7e\t\x80-\xff]*) using fullmatch to prevent newline injection that could lead to header smuggling.

Sources: stackone_ai/tools.py:221-255, tests/test_tool_calling.py:539-568

JSON Content-Type Validation

The SDK uses a specific helper is_json_content_type to determine if a body should be parsed. It only accepts genuine JSON media types (application/json) or structured suffixes (+json). An absent Content-Type causes the SDK to treat the response as binary bytes, preventing dangerous attempts to decode binary data as UTF-8.

Sources: stackone_ai/types.py:73-82, tests/test_tool_calling.py:338-355

Summary

The File Downloads & Sanitization system provides a robust pathway for handling SaaS documents within the StackOne AI SDK. By strictly validating Content-Type and aggressively sanitizing filenames from Content-Disposition headers, the SDK enables secure file access while protecting the host system from path traversal and injection vulnerabilities.