# Iris 安全边界

状态：v0.1.4 候选实现。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。

## 信任模型

- DSH Host、Iris 插件进程和 `$DSH_HOME` 当前属于同一操作系统用户。
- 浏览器工作台只通过 Iris 的同源 Host 路由访问数据；默认只接受回环 Host。显式 `IRIS_TRUSTED_HOSTS` 只扩展 Host 校验，不等于认证。
- API Key 只在 Host 侧配置与供应商请求中使用。工作台、状态 API、任务记录、错误和 Doctor 输出不得返回完整 Key。
- DSH 仍处于快速演进阶段。Iris 的兼容范围不是对 DSH 本身安全性或生产就绪度的背书。

## 凭据与配置

供应商凭据保存在 `$DSH_HOME/iris/v1/providers.json`。POSIX 上 Iris 创建的目录和文件分别使用 `0700` 与 `0600`，启动时会在不跟随符号链接的前提下收紧既有 Iris 树。Windows mode 不等同于 ACL，仍依赖当前用户目录和系统账户权限。

API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误会移除 Bearer token、常见 Key、签名查询参数、堆栈和私有绝对路径。不要把 `providers.json`、环境变量或含签名的临时 URL 上传到 Issue。

健康证据与供应商配置同存于 `providers.json`，只保存模型、能力、时间、来源、错误分类、可选 HTTP 状态和脱敏短说明；状态 API 不返回完整 Key。关键凭据、端点或协议变化会清空旧证据，避免把另一组配置的成功错误沿用为当前事实。

`ai-paint` 是维护者未公开的本地前身，不是用户依赖。Iris 只有在用户显式设置 `IRIS_IMPORT_WORKBENCH_CONFIG` 为绝对路径且自身配置为空时才做一次性导入，不扫描其他项目，也不回写来源文件。

## 受理与费用安全

- 所有生成 Attempt 在网络副作用前落盘。
- 只有供应商明确证明未受理时才允许自动 failover。
- 500、超时、连接重置、响应丢失、轮询失败、事件失败和本地落盘失败都不能授权自动重提。
- “重新观察”只查询已有远端任务；“重新交付”只查询并下载已成功产物。
- “知情重试”必须单独确认可能重复任务或重复计费，并创建带 `retryOf/manualRetries` 关系的新 Task。创建后只归档原提醒，不改写原任务的未知事实；当前只对能从安全记录无损重建的文生图和文生视频开放，文件型输入和截断文本要求用户从原始输入重新发起。
- “标为已读/恢复提醒”只操作有界的本地 `attentionEvents` 审计元数据，不发送网络请求，也不把用户处置等同于供应商已经受理。
- Iris 当前没有凭空假设 DashScope 的远端取消协议。停止本地观察后若远端结果无法确认，状态保持 unknown。
- Provider 健康不做后台探测。只有 401、403 或明确认证/权限分类可变为暗红；429、网络、5xx、内容安全、取消与未知受理不得覆盖近期成功或授权自动重提。

## 文件、上传与媒体访问

- 浏览器上传使用大小上限、随机文件名、`.part` 临时文件和完成后的原子改名；中断时清理临时文件，过期副本按 TTL 回收。
- 输出文件名由 Iris 生成或通过 `basename` 收口，API 不返回宿主绝对路径。
- 媒体播放链接使用随机能力令牌。令牌应视为临时访问凭据，不应发布到公网。
- 清理任务元数据默认不删除作品；独立作品索引不保存 Prompt、Provider、Model 或任务关系。
- 删除单件作品、清空作品库或删除真正的孤儿文件都需要独立确认。作品删除会保留任务历史，但旧媒体链接将失效。
- 符号链接不会被私有树权限收紧逻辑跟随。Doctor 会把 Iris 数据根为符号链接视为硬错误。

## Web 与渲染

- 修改状态的路由拒绝明确跨站请求，并限制 JSON/上传 Body 大小。
- HTML 截图在离线沙箱中运行，不具备 Iris/宿主同源权限；远程资源和页面脚本不可用。
- SSE 使用同源连接、节流和背压合并；慢消费者只保留最新快照，避免积压历史状态。
- 如果把 DSH 通过 LAN、反向代理或隧道暴露，必须由部署者另加真正的认证、TLS、访问控制和来源限制。

## 离线 Doctor

`dsh-iris doctor` 不启动 DSH，不发送供应商或计费请求，也不打印 API Key。它会在 Iris 数据目录或最近可写父目录创建一个随机小文件并立即删除，用于验证真实写权限。`--json` 与文本输出使用同一结果模型，退出码为：`0` 正常、`1` 有警告、`2` 有硬错误。

Doctor 不能证明 DSH 工具注册、浏览器、附件服务、客户端资源或真实 Provider 在线；这些属于后续 Host 扩展诊断。

## 报告问题

报告安全问题前请移除 API Key、Authorization、完整 `providers.json`、私有路径、媒体能力令牌和供应商签名 URL。建议提供版本、平台、Doctor 的脱敏输出、最小复现步骤及是否发生真实费用。