File Access Control#

Dify enforces workflow-layer file access control through the api/core/app/file_access/ module. The system gates database lookups for UploadFile and ToolFile records using a request-scoped ownership context carried as a Python ContextVar. Access is always tenant-scoped; end-user executions apply additional per-user ownership checks, with an execution-local grant mechanism for files surfaced through trusted knowledge retrieval paths.

The module's public API 1: DatabaseFileAccessController, FileAccessControllerProtocol, FileAccessScope, bind_file_access_scope, get_current_file_access_scope, grant_upload_file_access, grant_retriever_segment_access, is_retriever_segment_access_granted.

Core Data Structures#

FileAccessScope#

FileAccessScope is a frozen dataclass held in a ContextVar. Key fields:

The requires_user_ownership property returns True when user_from == END_USER, triggering stricter ownership filtering.

FileAccessControllerProtocol#

The protocol is the testable interface implemented by DatabaseFileAccessController. It defines:

• apply_upload_file_filters / apply_tool_file_filters — append access-control predicates to SQLAlchemy Select statements
• get_upload_file / get_tool_file — load a single authorized record, returning None on access denial

Three-Layer Filtering Logic#

DatabaseFileAccessController.apply_upload_file_filters applies three conditions in order:

1. Tenant scope — unconditionally adds UploadFile.tenant_id == scope.tenant_id 2
2. User ownership — when requires_user_ownership, adds created_by_role == END_USER AND created_by == user_id 3
3. Execution-local grants — if granted_upload_file_ids is non-empty, the ownership condition is OR-expanded with UploadFile.id IN (granted_ids) 4

ToolFile access follows the same tenant + user_id pattern, but has no grant list 5.

Execution-Local Grant Mechanism#

The grant system solves a concrete problem: knowledge base images are indexed as UploadFile records owned by the indexing account, but published apps execute as end-users who fail the per-user ownership check 6. Before the fix, this caused Invalid upload file errors when a Knowledge Retrieval node returned segments containing images — only reproducible in the published app, not Studio Preview (which runs as the account user).

The fix, landed in PR #36175 / PR #36195, added two grant functions to scope.py:

• grant_retriever_segment_access(segment_ids) — allowlists segment IDs discovered during knowledge retrieval
• grant_upload_file_access(upload_file_ids) — allowlists specific UploadFile IDs when attachment bindings are resolved

Both mutate the scope via an immutable replace() on the ContextVar, keeping the dataclass frozen 7.

is_retriever_segment_access_granted(segment_id) returns True for account users unconditionally, or when the segment ID is in the execution's allowlist.

Grant Call Sites#

node_runtime.py also enforces grants before loading: the DifyRetrieverAttachmentLoader returns [] if is_retriever_segment_access_granted rejects the segment or if the context-aware segment_access_checker (injected from node_factory.py) cannot find the segment in the workflow's current variable pool 8.

Scope Lifecycle#

bind_file_access_scope is a context manager that sets the ContextVar for the duration of an app execution and resets it on exit. BaseAppGenerator._bind_file_access_scope constructs the initial FileAccessScope from tenant_id, user (distinguishing Account vs EndUser), and invoke_from, then wraps the execution generator. All app types — completion, chat, agent, advanced chat, workflow — call this base method.

Key Files#