agent/docs/security-boundaries.md

安全边界

信任模型

浏览器输入、模型输出、工具参数、上传文件名、MIME、Base URL、Skill 额外路径和 SSE cursor 都是不可信输入。Zod / TypeBox 负责结构校验，Harness 负责语义与权限校验，操作系统仍是最终权限边界。

已实现的课堂版保护

凭证

• Session 配置覆盖服务器环境变量；没有配置时明确报错。
• API Key 只保存在 Server 内存和 Pi InMemoryCredentialStore。
• 响应只返回 keyHint，不会返回原值或长度。
• 不写浏览器 Storage、日志、事件、URL、Pi 用户目录或仓库文件。
• 运行中禁止修改模型；清除凭证幂等。

Base URL / SSRF

• 使用 WHATWG URL，默认仅 HTTPS。
• 拒绝 userinfo、fragment、非 HTTP(S)、异常端口和含凭证 query。
• DNS 结果若命中 loopback、private、link-local、unspecified、multicast 或 metadata 范围则拒绝。
• 开发模式只对显式 localhost HTTP 开例外；企业内网需要服务器管理员设置环境变量。
• 当前请求策略要求同源重定向，不能依赖首次 URL 校验后任意跳转。

路径与写入

• 每个 Session 使用独立随机目录。
• realpath + relative containment 防止 .. 和绝对路径逃逸。
• 逐段拒绝符号链接，并保护 .env、.git、.ssh 和常见私钥名。
• write tool 只能调用 SafeWorkspace.writeReportDraft，目标固定为 report.md，临时文件以独占创建并原子 rename。
• 删除 Session 会取消 run 和审批，并清除附件和整个 Session 目录。

图片

• 只收 JPEG、PNG、WebP；同时检查扩展名、MIME 和 magic bytes。
• 流式字节上限、宽高上限与总像素上限阻止常见资源耗尽输入。
• Sharp 自动旋转并重新编码，去掉不需要的元数据。
• 随机服务端文件名，权限 0600；不提供任意路径下载或静态目录。
• base64 只在 Server 构造 Pi prompt 的最后阶段短暂存在。

工具与审批

• allowlist 只开放课堂所需 read-only 工具。
• 未知工具默认拒绝。
• save_report_draft 在 Pi tool preflight 阶段等待服务器 Broker。
• 审批绑定 approvalId、runId 和 toolCallId；支持 approve、deny、expired、cancelled。
• Browser 点击不是最终事实，只有 approval.resolved 事件能改变投影状态。

不提供的隔离

Pi 没有内置 Sandbox，Project Trust 也不是 Sandbox。Pi Agent、Extension、Sharp 和所有 Node 依赖继承启动进程的用户权限与网络权限。应用层路径校验和审批不能防御依赖漏洞、Node 进程逃逸、同用户数据读取或不受控的出站模型请求。

因此不要用该课堂版处理生产密钥、不可信租户代码或敏感业务文件。真正部署至少需要：低权限系统用户、只读基础镜像、每 Session 容器或 microVM、挂载白名单、seccomp、出站网络 allowlist、资源配额和销毁验证。

部署前仍需补齐

• 登录、Session 所有权、租户授权和管理员权限。
• SameSite Secure cookie、CSRF、防点击劫持和严格 CSP。
• API、上传、run 和审批的速率限制与配额。
• KMS / Secret Manager，不在应用堆中长期保存明文凭证。
• 持久化且防篡改的审计日志。
• 恶意图片扫描、对象存储隔离和生命周期策略。
• 分布式锁、幂等键、Broker 持久化和崩溃恢复。