Workspace file read authority
工作区文件读取权限
Workspace Files serves both file content and workspace navigation. Applying workspace containment to every operation creates a second read policy above the Session filesystem backend and prevents a user from previewing paths that the same Session can read outside its workspace. HTML preview also needs direct relative JavaScript and stylesheet files, including `..` paths, while its script-enabled document can use the
English
Problem
Workspace Files serves both file content and workspace navigation. Applying workspace containment to every operation creates a second read policy above the Session filesystem backend and prevents a user from previewing paths that the same Session can read outside its workspace. HTML preview also needs direct relative JavaScript and stylesheet files, including .. paths, while its script-enabled document can use the browser network.
Decision
read, readBytes, and stat inherit the addressed Session filesystem backend's read authority. The workspace root is the base for relative input paths, not a read boundary; absolute paths and relative paths that leave the workspace are readable when the backend allows them. The service still requires regular files, refuses symlinks, and applies its text and byte caps.
list and changes remain workspace-scoped because they expose workspace navigation and observation rather than a named file read. list rejects a directory outside the root, and changes filters observations through the backend's workspace-containment predicate.
readBytes with baseFile resolves a relative path from the base file's directory. A .. path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. With Developer tools enabled, Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with sandbox="allow-scripts"; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML.
The Workspace Files service owns paging, file checks, listing, and observation. Document Preview owns which related files are packaged and the iframe sandbox.
Alternatives considered
Contain every operation within the workspace. This gives previews a narrower policy than the Session filesystem backend, blocks explicitly addressed readable files, and prevents HTML beside external assets from rendering. Workspace containment remains where the operation itself represents the workspace.
Permit outside reads but block all iframe networking. A stricter CSP would reduce exfiltration risk, but it would also reject external assets and network behavior intentionally retained for the static-HTML preview. The opaque sandbox protects the parent application; it does not promise network isolation.
Consequences
Any caller holding a valid Session file address can receive bytes from every regular file that the Session filesystem backend permits it to read, including files outside the workspace. With Developer tools enabled, a previewed HTML document can execute packaged local JavaScript and make network requests. Outside files do not produce changes frames, so their previews require explicit refresh to observe updates.
中文
Problem
Workspace Files 同时提供文件内容与工作区导航。对所有操作应用工作区包含限制，会在 Session 文件系统后端之上形成第二套读取策略，并阻止用户预览同一 Session 在工作区外可读的路径。HTML 预览还需要直接读取相对 JavaScript 与样式表文件，包括含 .. 的路径，而启用脚本的文档可以使用浏览器网络。
Decision
read、readBytes 与 stat 继承被寻址 Session 的文件系统后端读取权限。工作区根是输入相对路径的基准，而不是读取边界；只要后端允许，就可以读取绝对路径和离开工作区的相对路径。服务仍要求普通文件、拒绝符号链接，并应用文本和字节上限。
list 与 changes 仍限于工作区，因为它们暴露工作区导航和观察，而不是读取一个具名文件。list 拒绝根外目录，changes 通过后端的工作区包含判定过滤观察。
带 baseFile 的 readBytes 从基准文件所在目录解析相对路径。因此，只要 Session 后端允许，.. 路径就可以读取工作区外的 JavaScript 或 CSS。开启开发者工具时，Document Preview 把有界、静态声明的本地脚本与样式表打包进带 sandbox="allow-scripts" 的 HTML Blob iframe；不透明源阻止访问父应用，但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。
Workspace Files 服务负责分页、文件检查、列举和观察。Document Preview负责选择要打包的关联文件及 iframe sandbox。
Alternatives considered
把所有操作限制在工作区内。 这会让预览采用比 Session 文件系统后端更窄的策略，阻止读取明确寻址的可读文件，并使位于外部资源旁的 HTML 无法渲染。操作本身代表工作区时，仍保留工作区包含限制。
允许根外读取，但阻断 iframe 的全部网络。 更严格的 CSP 可以降低数据外传风险，但也会拒绝静态 HTML 预览有意保留的外部资源与网络行为。不透明 sandbox 保护父应用，但不承诺网络隔离。
Consequences
持有有效 Session 文件地址的调用方可以接收 Session 文件系统后端允许读取的每个普通文件的字节，包括工作区外文件。开启开发者工具时，预览的 HTML 文档可以执行已打包的本地 JavaScript，并发起网络请求。工作区外文件不会产生 changes 帧，因此其预览需要显式刷新才能观察更新。