# Iris 安全边界

版本：Iris 0.2.7，发布状态见 [README](../README.md)。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；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，仍依赖当前用户目录和系统账户权限。

[DSH 连接复用](DSH_PROVIDER_CONNECTIONS.md)对引用条目只保存宿主连接标识，不保存密钥或普通 Base URL。连接列表使用脱敏设置与凭据存在性，不读取值；执行操作时才通过公开凭据接口取得内存副本。副本按异步操作隔离，不回写配置、Task、Artifact、HTTP 状态或日志。OAuth 和自定义请求头不会被猜测转换为 Bearer 认证。

API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误会移除 Bearer token、常见 Key、签名查询参数、堆栈和私有绝对路径。0.2.6 的媒体 Provider Adapter 还会在截断之前移除本次已知 API Key，覆盖无固定前缀的密钥及错误码中的回显。不要把 `providers.json`、环境变量或含签名的临时 URL 上传到 Issue。

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

模型目录与可用性证据也保存在该私有配置中，只写入固定形状的模型/能力数据、时间与连接摘要，不保存解析后的凭据。摘要用于判断连接变化，不是身份认证。新自动请求可能按需读取目录；只读配置查询、手选请求及旧任务恢复不隐式同步或付费实测。目录出现新模型不授权使用，未列出也不自动删除或阻断；具体规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。

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

## 受理与费用安全

- 所有生成 Attempt 在网络副作用前落盘。
- 只有供应商明确证明未受理时才允许自动 failover。
- 通用候选切换不因500、超时、连接重置、响应丢失、轮询失败、事件失败或本地落盘失败自动重提。Music入口按本次配置对明确HTTP502执行有限的新任务重发，保留原受理未知事实并可能消耗额外额度；设置 `retry_502: 0` 可关闭，见 [音乐生成](MUSIC.md)。
- “重新观察”只查询已有远端任务；“重新交付”只消费已有成功结果。0.2.3 支持同步完整缓存的本地交付或原 URL 下载，异步保持 re-poll；均不重新生成。缓存缺失或损坏不授权自动重提，详见 [同步交付恢复](SYNC_DELIVERY_RECOVERY.md)。
- “知情重试”必须单独确认可能重复任务或重复计费，并创建带 `retryOf/manualRetries` 关系的新 Task。创建后只归档原提醒，不改写原任务的未知事实；当前只对能从安全记录无损重建的文生图和文生视频开放，文件型输入和截断文本要求用户从原始输入重新发起。
- “标为已读/恢复提醒”只操作有界的本地 `attentionEvents` 审计元数据，不发送网络请求，也不把用户处置等同于供应商已经受理。
- Iris 当前没有凭空假设 DashScope 的远端取消协议。停止本地观察后若远端结果无法确认，状态保持 unknown。
- Provider 健康不做后台探测。普通认证/权限失败为暗红；短时 429 以琥珀色冷却，优先遵从 `Retry-After`，默认 60 秒，到期只恢复候选资格。明确免费额度或预算耗尽以红色持续停用至手动实测成功，记录按账号和模型隔离。网络、5xx、内容安全、取消与未知受理不覆盖近期成功；任何健康变化均不授权自动重提已受理任务。

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

- 浏览器上传使用大小上限、随机文件名、`.part` 临时文件和完成后的原子改名；中断时清理临时文件，过期副本按 TTL 回收。
- 输出文件名由 Iris 生成或通过 `basename` 收口，API 不返回宿主绝对路径。
- legacy 任务与独立作品的媒体链接使用随机 128-bit 能力令牌。令牌应视为临时访问凭据，不应发布到公网。
- Core 媒体路由 `/iris/api/core/artifact/<artifact_id>/media` **没有独立 token**。它使用随机 96-bit Artifact ID 作为不可猜测的持有者标识，并叠加默认回环/显式 trusted Host、浏览器 `Origin`/`Sec-Fetch-Site` 拒绝跨站、`Cross-Origin-Resource-Policy: same-origin`、`Referrer-Policy: no-referrer` 与每次 SHA-256 校验。任何能访问受信 Host 且持有 Artifact ID 的客户端都能读取对应媒体；`IRIS_TRUSTED_HOSTS` 不是身份认证。不要把 Core Artifact ID 或媒体 URL 发布到不受信任位置。
- 清理任务元数据默认不删除作品；legacy 独立作品索引不保存 Prompt、Provider、Model 或任务关系；Core Manifest 保存中性元数据、SHA-256 和来源/派生关系，不保存凭据或私有下载 URL。
- `delivery-cache/v0/` 是私有同步结果证据，不属于公共 Task/Artifact DTO：可能包含签名下载 URL 和媒体正文，不上传到 Issue，也不由媒体路由暴露。缓存随显式 Task 隔离/恢复，不自动删除；需要为额外磁盘占用留出空间。
- legacy 删除单件作品、清空作品库或删除真正的孤儿文件都需要独立确认，会保留任务历史，但旧媒体链接将失效。0.2.1 Core 删除使用可恢复隔离，任务/产物引用会阻止删除；同时移除关联的已结束任务记录需要明确选择和确认，恢复不会覆盖冲突文件。见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
- 符号链接不会被私有树权限收紧逻辑跟随。Doctor 会把 Iris 数据根为符号链接视为硬错误。

## Web 与渲染

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

## 显式本地 API 与 Skill 安装

0.2.7 的 [本地 API](LOCAL_API.md)由用户显式启动，只监听 `127.0.0.1`，与 DSH 路由的身份边界分别管理。每次启动产生独立会话 Token，写入新的根外私有文件；全部 API 与媒体都要求 Bearer、准确 Host 和受控 Origin，不将 Token 放入 URL 或 stdout。服务关闭后旧 Token 失效，原私有文件保留。

默认 GET/HEAD 不写 Core 或调用 Provider。新空 Flow 根须显式 `api init`，并通过 `--allow-local-writes` 开启 [上传/创建](LOCAL_CREATION.md)；这两个 POST 不执行生成。请求意图与业务效果在同一 writer 内提交，同 Key 接回原身份，损坏请求保留并拒写，成功结果删除后不自动复活。固定流程的 Prompt 保存为专用根中的私有 Run 输入，不进入公共 Task/Artifact DTO；备份该根时应按私人创作数据保护。旧 writer 不得写入新流程根，回退应使用完整备份。

[Core Skill 安装器](CORE_SKILLS.md)只有显式 `skills install/uninstall` 才修改目标，`status` 与 dry-run 只读。安装记录用于内容与归属检查，不能作为对恶意本机用户的认证。无归属目录、用户修改及软链不被接管；升级/卸载保留扫描根外备份，不自动清理。安装不改变模型、MCP 或宿主权限；文件完整不等于宿主已发现 Skill，也不等于 Agent 已完成业务验收。

## 图像处理依赖

0.2.6 将 `sharp` 最低版本提高到 `0.35.5`，锁文件同步其修复后的预编译依赖，以处理 [librsvg 高危公告 GHSA-wq5f-xc86-pv6w](https://github.com/lovell/sharp/security/advisories/GHSA-wq5f-xc86-pv6w)。公告涉及特定 glibc Linux 运行条件下的 SVG 内存安全问题；这不是本项目已发生利用的证据。只检查文件扩展名不能代替更新解码器。

若部署时自行替换为系统 libvips/librsvg，应单独核对系统库修复版本；npm 锁文件和审计不覆盖自行安装的系统库。公开图片导入仍限制静态 PNG/JPEG/WebP，内部摘要使用程序构造的 SVG 标签。

## 离线 Doctor

`dsh-iris doctor` 不启动 DSH，不发送供应商或计费请求，也不打印 API Key。默认 DSH 模式会在 Iris 数据目录或最近可写父目录创建一个随机小文件并立即删除，用于验证真实写权限；显式 `--data-root <abs>` Core 模式只读检查指定根的结构、索引、任务和租约，不做写探针，也不自动释放租约。`--json` 与文本输出使用同一结果模型，退出码为：`0` 正常、`1` 有警告、`2` 有硬错误。

Doctor 不能证明 DSH 工具注册、浏览器、附件服务、客户端资源或真实 Provider 在线；这些仍需各自验证。

## 报告问题

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