Tool File URL Signing#

Tool file URLs in Dify are protected by an HMAC-SHA256 signature scheme. Every URL for a tool-generated file must carry timestamp, nonce, and sign query parameters; the server rejects requests where the signature doesn't verify or the timestamp has expired.

Architecture: URI Generation and URL Binding#

Tool file signing now separates two concerns:

1. URI generation — produces an origin-free /files/... path with HMAC signature and expiry
2. URL binding — attaches the appropriate base URL (FILES_URL, INTERNAL_FILES_URL, or a custom URL) based on the intended audience

This separation allows the same signed URI to be bound to different base URLs for different consumers (plugin, browser, internal services).

URI Generation (sign_tool_file_uri)#

sign_tool_file_uri(tool_file_id, extension) produces an origin-free, signed URI:

1. Signed path — /files/tools/{tool_file_id}{extension}
2. Payload — "file-preview|{tool_file_id}|{timestamp}|{nonce}"
3. Signature — HMAC-SHA256(SECRET_KEY, payload), base64url-encoded
4. Query string — ?timestamp={ts}&nonce={nonce}&sign={encoded_sign}

The nonce is 16 random bytes (hex-encoded); the timestamp is the current Unix epoch as a string.

URL Binding (bind_file_uri)#

bind_file_uri(uri, base_url) attaches a base URL to an origin-free URI:

• Absolute HTTP(S) URLs (remote files) pass through unchanged
• /files/... URIs are prefixed with base_url to produce the final URL

Complete Signing (sign_tool_file)#

sign_tool_file(tool_file_id, extension, for_external=True) is a convenience wrapper that calls sign_tool_file_uri and bind_file_uri:

1. Calls sign_tool_file_uri to generate the signed /files/tools/... URI
2. Calls bind_file_uri with dify_config.FILES_URL (when for_external=True) or dify_config.INTERNAL_FILES_URL (when for_external=False)

Verification (verify_tool_file_signature)#

verify_tool_file_signature recomputes the HMAC over the same payload and checks two conditions:

• Signatures must match byte-for-byte (constant-time via hmac.new). 6
• current_time - timestamp ≤ FILES_ACCESS_TIMEOUT — default 300 seconds (5 minutes). 7

The HTTP endpoint GET /files/tools/<file_id>.<extension> calls verify_tool_file_signature on every request and raises 403 Forbidden on failure. 8

Related Functions in signature.py#

The same file contains two additional signing functions that use the same pattern:

Configuration#

Where Signing Functions Are Called#

Known Inconsistency: Unsigned URLs in the Pipeline#

ToolFileMessageTransformer.get_tool_file_url() returns a bare, unsigned relative URL (/files/tools/{tool_file_id}{extension}) 9. This method is used when constructing IMAGE_LINK and BINARY_LINK messages for tools and blobs inside transform_tool_invoke_messages 10 11.

Similarly, base_app_runner.py stores the URL /files/tools/{tool_file.id} directly in a MessageFile record's url field without signing 12. Those unsigned URLs are later picked up by message_file_utils.py, which does call sign_tool_file at read time 13.

The practical effect is a two-stage pattern: tool-file URLs are often stored or passed as unsigned relative paths early in the pipeline, then signed only when being serialized for an external client response. Code paths that bypass message_file_utils.py may expose unsigned URLs that the /files/tools/ endpoint will reject with 403.

Key Files#