📝 docs: 建立魂镜完整 1.0 设计文档体系
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标 - 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处） - 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识 - 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测 - 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等） - 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档 - 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
This commit is contained in:
chenxin committed
commit
42513d13c6
37 files changed
+5795
No files matched your search
@@ -0,0 +1,171 @@
|
||||
# 安全与诊断访问
|
||||
|
||||
## 1. 威胁模型
|
||||
|
||||
保护对象包括：用户消息、角色设定、记忆、文件、私箧密文（用户独立持钥，平台不可恢复）、BYOK/Provider/MCP 凭据、工具输入输出、模型 Prompt、诊断数据和审计记录。
|
||||
|
||||
主要威胁：
|
||||
|
||||
- 跨用户或跨角色 IDOR；
|
||||
- Prompt Injection 诱导工具越权或秘密外传；
|
||||
- 恶意插件获得进程权限；
|
||||
- Header 透传泄露凭据；
|
||||
- 诊断接口成为管理员旁路；账户恢复、管理员或诊断接口试图读取私箧明文；
|
||||
- 工具重试造成重复副作用；
|
||||
- 日志、APM、CDN 和浏览器缓存保存敏感数据；
|
||||
- 删除后索引、缓存或派生内容继续使用；
|
||||
- 恶意社区内容、角色卡、媒体或插件供应链；
|
||||
- 支付 Webhook 重放、金额篡改、重复退款或重复结算；
|
||||
- 创作者账户接管、虚假交易、洗钱、拒付与恶意退款；
|
||||
- 相机、麦克风、屏幕、位置或声音克隆越权；
|
||||
- 推荐系统泄露私密特征或放大有害内容；欠费或封禁流程删除角色与记忆数据。
|
||||
|
||||
## 2. 插件与工具安全
|
||||
|
||||
- [产品宪章](../product/product-charter.md)定义的核心禁域不能被 Prompt、插件、管理员或普通自托管配置关闭；自托管档位可裁剪能力，不得混淆职责或关闭禁域。
|
||||
- 只有 bundled Core plugin 可以在主进程运行。
|
||||
- 声明式/远程插件默认受限；部署者信任的本地代码插件也必须运行在独立进程或容器。
|
||||
- 语言 VM 不算安全隔离。
|
||||
- 插件依赖和权限必须在 Manifest 声明。
|
||||
- 工具输入视为模型产生的不可信输入，必须 Schema 校验和 Policy 判定。Policy 按四维综合裁决而非只看工具名称：**能力**（动作自身与可逆性）、**数据**（读取或传出的数据及敏感度）、**后果**（现实副作用、传播范围与费用）、**情境**（界域、设备状态、对象与用户状态）；亲密程度、角色信任或"过去允许过"不能替代具体授权。
|
||||
- 文件路径 canonicalize 后必须位于授权根目录；网络使用 allowlist；命令执行限制资源和时间。
|
||||
- 无隔离后端时拒绝危险工具，禁止 unconfined fallback。
|
||||
|
||||
## 3. 凭据与客户端认证
|
||||
|
||||
- 1.0 使用 OAuth 2.1：Web 为安全 HttpOnly Session Cookie，Tauri 为 Authorization Code + PKCE，公共客户端为短期 Bearer，自动化为限 scope Service Account API key。
|
||||
- 用户登录、API、Service Account、诊断和 Provider 凭据只通过 HTTP Header 传递；不进入 query、业务 body、SSE data 或 WebSocket URL。对象存储预签名 URL 是短期、对象绑定 capability，仅按上传契约作为受控例外。
|
||||
- Cookie 状态变更验证 Origin 和 CSRF token；Tauri 回调只允许已登记 loopback/deep link。
|
||||
- 2.0 才设计自研加密登录、刷新和设备令牌协议；1.0 不自创密码协议。
|
||||
- 密钥存 Secret Store，只在执行边界注入。
|
||||
- 浏览器、Prompt、记忆、工具结果和普通日志都不出现密钥。
|
||||
- 记忆提取器和插件只能提出 Candidate，Core 在写入和召回前执行所有权、敏感度与审批策略；设备 Restricted 数据不得自动写入记忆。
|
||||
- 记忆召回先在数据库查询层授权和过滤，再访问全文、向量或图投影；禁止跨域召回后应用层过滤，临时/Working Context 也不能跳过 Conversation、Branch 和 Run 隔离。
|
||||
- 记忆来源中的 Prompt Injection 只能作为不可信内容处理，不得改变 actor、scope、审批、敏感度或删除策略。
|
||||
- APM 与代理对 `Authorization`、Cookie、Provider keys、`Hunjing-Diagnostic-Token` 全量脱敏。
|
||||
- Header 与 body 注入应限制目标 host；URL path/query 不注入秘密。
|
||||
- 支持密钥撤销、轮换和按数据域分配。
|
||||
|
||||
## 4. 设备与媒体安全
|
||||
|
||||
- 设备能力同时受 OS 权限、`device_grant`、角色范围、用途和期限约束。
|
||||
- 摄像头、麦克风和屏幕采集必须有持续可见指示与即时停止。
|
||||
- 人脸、声纹、精确位置和屏幕内容为 Restricted；不进入推荐、普通日志或自动记忆。
|
||||
- 声音克隆需要可验证授权、用途/传播范围、撤回和滥用举报。
|
||||
- 上传媒体先做类型验证、恶意文件扫描、内容安全和许可检查。
|
||||
- Tauri command 使用最小 allowlist；WebView 内容不能直接调用通用 Shell。
|
||||
|
||||
## 5. 社区、协作与市场安全
|
||||
|
||||
- Community、Workspace、Personal Domain 与 Finance 使用不同授权策略。
|
||||
- 公开角色版本不包含私密记忆、关系、对话、设备授权或密钥。
|
||||
- 举报和审核保留证据摘要、处置、申诉和操作者审计；审核模型不独立执行永久高影响处置。
|
||||
- 插件和数字商品发布前检查签名、恶意代码、权限、许可证、来源和隐私声明。
|
||||
- 购买不等于启用插件，也不等于批准权限。
|
||||
- 内容推荐禁止使用 Restricted 数据，并提供关闭个性化、屏蔽和重置。
|
||||
|
||||
## 6. 支付与结算安全
|
||||
|
||||
- 支付和结算只接受服务端价格快照；客户端金额不可信。
|
||||
- Provider Webhook 验签、校验时间窗、按 event ID 幂等，并通过重放测试。
|
||||
- Order、PaymentAttempt、Refund、Dispute、Ledger、Entitlement 和 Payout 分离。
|
||||
- Ledger 不可变；退款和冲正写新分录，不修改历史金额。
|
||||
- 同一退款、结算批次和 Payout 使用稳定幂等键。
|
||||
- KYC、银行和税号优先由合规 Provider 托管；本地只存引用、状态和脱敏信息。
|
||||
- 反欺诈限制不能静默没收创作者余额；冻结、申诉和释放过程可审计。
|
||||
|
||||
## 7. 诊断双重授权
|
||||
|
||||
### 7.1 流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User
|
||||
participant A as API
|
||||
participant G as Grant Service
|
||||
participant D as Diagnostics
|
||||
participant L as Audit Log
|
||||
|
||||
U->>A: re-authenticate and request Run diagnostics
|
||||
A->>G: issue scoped grant
|
||||
G-->>U: one-time opaque token
|
||||
U->>D: Bearer session + diagnostic headers
|
||||
D->>G: validate hash, scope, target, expiry, uses
|
||||
G-->>D: allow or deny
|
||||
D->>L: record access result
|
||||
D-->>U: redacted response, no-store
|
||||
```
|
||||
|
||||
普通登录态证明“是谁”；诊断授权证明“为何、在什么范围、多久、读取哪个 Run”。任一单独存在都不足以读取。
|
||||
|
||||
### 7.2 请求头
|
||||
|
||||
| Header | 规则 |
|
||||
| --- | --- |
|
||||
| `Authorization` | 普通 `Bearer` 登录令牌 |
|
||||
| `Hunjing-Diagnostic-Token` | opaque token，`hjd_` 前缀，不带 Bearer |
|
||||
| `Hunjing-Diagnostic-Purpose` | 固定枚举 |
|
||||
| `Hunjing-Request-ID` | 推荐 |
|
||||
|
||||
Purpose：`user_inspection`、`support_case`、`security_investigation`、`automated_evaluation`。
|
||||
|
||||
令牌不得放 query、body、Cookie、SSE data 或 WebSocket URL。重复头、逗号合并、控制字符和未知 Purpose 一律拒绝。
|
||||
|
||||
### 7.3 Grant
|
||||
|
||||
数据库只保存 token hash：
|
||||
|
||||
- issuer、subject、personal domain；
|
||||
- 绑定 `run_id`，可进一步绑定 `turn_id`；
|
||||
- scopes、diagnostic level、purpose；
|
||||
- support case；
|
||||
- issued/expires/used/revoked；
|
||||
- max uses、region、creation trace。
|
||||
|
||||
默认有效期 15 分钟、单次、绑定一个 Run。Sensitive level 需要重新认证和逐次确认。
|
||||
|
||||
### 7.4 Scopes
|
||||
|
||||
- `diagnostics:turn:summary`
|
||||
- `diagnostics:model:usage`
|
||||
- `diagnostics:tool:summary`
|
||||
- `diagnostics:tool:sensitive`
|
||||
- `diagnostics:context:manifest`
|
||||
- `diagnostics:audit:read`
|
||||
|
||||
管理员角色不自动获得这些 scope。支持人员只能读取用户主动绑定工单生成的支持包。
|
||||
|
||||
## 8. 响应和审计
|
||||
|
||||
诊断响应必须设置：
|
||||
|
||||
```http
|
||||
Cache-Control: no-store, private
|
||||
Pragma: no-cache
|
||||
Content-Security-Policy: default-src 'none'
|
||||
X-Content-Type-Options: nosniff
|
||||
```
|
||||
|
||||
每次成功和失败访问记录 actor、grant、purpose、目标、scope、结果、IP/设备摘要、时间和 trace。审计本身不保存被访问的敏感正文。
|
||||
|
||||
对象错配返回 404，减少资源枚举；token 失效、过期、撤销、scope/region 不符返回统一权限错误，不向调用方区分细节。
|
||||
|
||||
## 9. 数据分级
|
||||
|
||||
| 级别 | 示例 | 默认观测 |
|
||||
| --- | --- | --- |
|
||||
| Public | 插件 ID、事件类型 | 可记录 |
|
||||
| Internal | 逻辑模型、耗时、状态 | 结构化记录 |
|
||||
| Sensitive | 用户消息摘要、脱敏工具参数 | 受控诊断 |
|
||||
| Secret | Token、Key、Cookie、签名 URL | 永不记录 |
|
||||
| Restricted | 私密原文、高敏文件 | 仅明确授权支持包、限期加密 |
|
||||
|
||||
隐藏 chain-of-thought 不属于可申请诊断内容；只允许用户可见的思路摘要和供应商返回的计数。PersonalDomain 数据默认不用于模型训练；自愿贡献需独立、明确、可撤销的同意，且不进入默认观测与诊断。审计链至少能回答：谁、在何时、基于何种授权和输入、对什么对象、执行了什么、结果如何、关联哪条 trace。
|
||||
|
||||
## 10. 删除与保留
|
||||
|
||||
- 撤权和删除立即阻止普通查询与召回。
|
||||
- 诊断授权不能绕过删除墓碑。
|
||||
- Provider 原始请求/响应默认不保存；支持包到期自动删除。
|
||||
- 常规 usage 与审计保留期独立于消息原文，并遵守最小化原则。
|
||||
- 备份到期恢复后必须重放删除清单，防止已删数据复活。
|
||||
Reference in new issue
Block a user