File Download Security#

Dify protects file downloads through two complementary layers: HMAC-signed URLs that expire, and response headers that prevent browsers from rendering dangerous file types inline.

HMAC-Signed URL Scheme#

Every file download URL carries three query parameters — timestamp, nonce, and sign — that must pass server-side verification before any bytes are served.

Signing is implemented in api/core/tools/signature.py. The signing functions all follow the same pattern 1:

1. Record the current Unix time as timestamp.
2. Generate a 16-byte random nonce (hex-encoded).
3. Construct a pipe-delimited payload, e.g. "file-preview|{file_id}|{timestamp}|{nonce}".
4. Compute HMAC-SHA256(SECRET_KEY, payload) and base64url-encode it as sign.
5. Append ?timestamp=…&nonce=…&sign=… to the URI.

The architecture separates URI generation (with HMAC signature) from URL binding (base URL selection). This allows the same signed URI to be bound to different base URLs for different network audiences (browser, internal services, remote Sandbox) while maintaining the same security mechanisms.

sign_tool_file accepts a for_external flag that is passed to bind_file_uri to select between FILES_URL (public-facing) and INTERNAL_FILES_URL (Docker-internal, for plugin daemon use) 2. The overall behavior for callers remains the same, but the implementation is refactored to use the new separation of URI generation and URL binding.

Verification happens in verify_tool_file_signature: the server recomputes the HMAC over the same payload and checks two conditions 3:

• The recomputed signature must match the sign parameter exactly.
• current_time − timestamp ≤ FILES_ACCESS_TIMEOUT — default 300 seconds (5 minutes).

The HTTP endpoint GET /files/tools/<file_id>.<extension> calls verify_tool_file_signature on every request and raises 403 Forbidden if either check fails 4.

Response Headers: Preventing Inline Browser Execution#

After signature verification, the endpoint applies two defenses against browser-based attacks:

1. Attachment disposition on request — If the client sends ?as_attachment=true, the endpoint sets Content-Disposition: attachment; filename*=UTF-8''<encoded_filename>, forcing a download dialog instead of inline rendering 5.

2. HTML content enforcement — enforce_download_for_html() in api/controllers/common/file_response.py detects HTML by MIME type (text/html, application/xhtml+xml) or file extension (.html, .htm) and, when matched, forcibly sets 6:

• Content-Disposition: attachment (with filename if available)
• Content-Type: application/octet-stream
• X-Content-Type-Options: nosniff

This prevents an attacker from uploading an HTML file and tricking the browser into executing it as a same-origin page. Both ToolFileApi 7 and the file preview endpoint 8 call this helper before returning any response.

Additionally, file preview endpoints (/files/<id>/image-preview, /files/<id>/file-preview) apply a broader set of security headers via the @add_security_headers decorator 8:

• Content-Security-Policy: default-src 'none'; sandbox
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy: no-referrer

Configuration#

Two-Stage URL Signing Pattern#

Tool-file URLs are frequently stored as unsigned relative paths early in the pipeline (e.g., /files/tools/{id} in MessageFile.url), then signed at serialization time when a response is sent to a client. The main signing call-sites are:

Code paths that bypass message_file_utils.py — such as ToolFileMessageTransformer.get_tool_file_url(), which returns a bare unsigned relative URL — will produce URLs the /files/tools/ endpoint rejects with 403 10. This is a known inconsistency tracked in issue #39222.

Key Files#