状态：v1 定稿（对应 docs/plugin-swarm-execution.md §4-S10 与 docs/plugin-api.md §3） 实现：angelus/plugins/security.py（权限门禁 + integrity checksum + 审计日志） 本文档描述插件系统的风险模型、v1 的安全边界与 v2 子进程隔离路线。任何安全相关决策 的变更（新增权限 action、放宽白名单、改变 checksum 语义）必须先更新本文档再改代码。

插件系统引入的资产与信任假设：

信任边界（v1，D1 决策）：

1. 同进程 import（D1 默认）：插件代码以 angelus_plugins.<name> 命名空间 import 进主进程， 与主进程同特权级。插件一旦被加载，其 Python 代码能访问主进程能访问的一切；
2. 因此 v1 的防线不是运行时沙箱，而是权限门禁——插件只能通过 PluginRuntime 提供的 注册面暴露扩展点，而扩展点背后的宿主能力（工具、钩子、路由、连接器）在真正执行前必须 经过 check_permission 核对 plugins.json 的 permissions_granted；
3. 不在白名单内的能力一律拒绝并记日志，绝不静默放行（fail closed）；
4. 未启用（disabled）的插件不 import、不执行（S3 load_all 只加载 registry 中 enabled 的插件， S10 在运行时门禁中再次确认 enabled is True，双保险）。

MVP 阶段与内建工具（shell/swarm/knowledge 等）同权，实现简单、调试直观；子进程隔离 （真正的沙箱）成本高，列为 v2 路线（§8）。

同进程 import 下权限边界不能依赖 Python 层面的强制（插件代码可 import os 后自行 subprocess.run），边界成立依赖三个正交机制：

1. 能力注册面收窄（S3/S4–S7）：插件只能通过 PluginRuntime.register_* 在 setup() 内注册扩展；bridge 层（bridge_tools.py / bridge_hooks.py / bridge_routes.py / bridge_connectors.py）是宿主能力与插件之间的唯一通道；
2. 权限门禁前置于能力执行（S10）：bridge 层在把插件 handler 接入宿主能力（shell 工具、 钩子总线、静态文件、connector 读取）之前调用 check_permission；未授权则拒绝并记日志；
3. 启用门（S3+S10）：registry 未启用或启用时未授予权限的插件，其代码根本不进入执行路径。

结论：v1 的权限边界是"信任插件作者 + 门禁拦截误用/越权调用"，不是"隔离不可信代码"。 插件安装即信任（用户显式确认权限清单），这一立场写入 v1 文档与 CLI 交互文案。

• 声明（manifest.permissions，permission 对象数组）＝ 插件请求的权限；
• 授予（plugins.json[].permissions_granted，"action:scope" 字符串数组）＝ 用户批准的权限；
• 运行时的唯一判据是授予。插件声明了 shell 但未被授予 ⇒ 调用被拒并记日志； 插件声明之外、被授予的权限（如 install 时勾选）同样有效——授予是权威；
• install/enable 流程（S9）以 declared_permissions(manifest) 生成确认清单，用户逐项批准后 才写入 permissions_granted；-y 只跳过交互确认，不跳过门禁。

check_permission(plugin_id, action, scope, registry=None) -> bool

1. action 不在 9 枚举 ⇒ 拒绝（error 级日志，fail closed）；
2. scope 非字符串或长度不在 1..512 ⇒ 拒绝；
3. registry 中找不到插件记录（或 registry 读失败）⇒ 拒绝（reason=not-installed / REGISTRY_LOOKUP_FAILED）；
4. 插件未启用（enabled is not True）⇒ 拒绝（reason=plugin-disabled）；
5. permissions_granted 不含精确的 "action:scope" ⇒ 拒绝（reason=not-granted）。

registry 参数可注入（默认 angelus.plugin_registry），bridge/CLI/测试均可传入替代实现； require_permission 提供异常语义（deny 时抛 PermissionError）。

插件可订阅的事件名（点命名，见 docs/plugin-api.md §5）：

agent.started、agent.stopped、tool.before、tool.after、session.created

• 白名单由 S3 angelus/plugins/base.py::HOOK_EVENTS 定义，bridge（S5）映射到内部冒号事件；
• 白名单外事件注册被拒绝（register_hook 拒绝 + 日志）；
• 钩子同步调用、单个钩子异常被隔离（不击穿 agent 主流程）；
• event.subscribe 权限的 scope 应为白名单内事件名，由门禁与白名单双重校验。

• connector 凭据走既有 RSA-OAEP 加密存储（angelus/connectors.py），解密只发生在服务端 发起 run 的那一刻（_resolve_connector_key）；
• 插件只能注册 provider factory（register_connector，S7），不能读取已存密钥；
• 插件可读取的 connector 元数据（connector.read 授权后）一律经过 _public_connector 脱敏： 仅返回 id/name/provider/model/api_url/has_api_key，任何密钥字段不进入该视图； security.redact_connector(record) 封装该边界（本地兜底：剥离名称含 key/secret/token/password/credential 的字段）；
• 规则：插件拿到的 connector 信息中 has_api_key 只回答"有没有"，永远不回答"是什么"。

• 格式 ^sha256:[0-9a-f]{64}$（manifest.checksum 与 plugins.json[].checksum 同构）；
• 安装期（S9 cli install / compute_plugin_integrity）对插件的已安装载荷计算： sha256( canonical(manifest 去掉 checksum 字段) + "\n" + entry 文件字节 )；
  • canonical = json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=False)， 键序与空白不敏感、任何值的一字节变化都会改变哈希；
  • checksum 字段自身从哈希输入中排除，值才能自洽地写回 manifest（无循环）；
  • 同时覆盖 manifest 与 entry ⇒ manifest 或 entry 任一改一字节即校验失败。
• 校验值同时写入 manifest.checksum（随插件目录自描述）与 plugins.json[].checksum （registry 交叉核对）。

verify_plugin_integrity(plugin_dir, manifest, *, expected=None) -> (ok, errors)

由 manager load 在 import/setup 之前调用（S3 预留的 verify 钩子位，见 docs/plugin-swarm-execution.md §4-S3"加载前复核"），cli install/重装亦调用：

1. manifest 无合法 checksum ⇒ 拒绝加载（reason=missing-checksum）——未记录的插件不加载；
2. entry 无法在插件目录内解析为文件（含路径穿越尝试）⇒ 拒绝（reason=entry-unresolvable）；
3. 重算载荷哈希与期望值不一致（改一字节即不相等，hmac.compare_digest 常数时间比较） ⇒ 拒绝（reason=checksum-mismatch），错误级日志记录 expected/actual/entry；
4. expected 可注入：manager 若同时持有 registry 记录，可传入 plugins.json[].checksum 做第二重比对（防"manifest 被整体替换成新 checksum"式协同篡改）。

• checksum 是篡改检测（防意外损坏/部分篡改/被替换后重新计算可绕过），不是防恶意 攻击者的防伪——能重写 checksum 的写入者不在本模型威胁内（registry 0600、应用私有）；
• 完整防伪/签名与远程证明列入 v2 路线（§8）。

• /plugins/<name>/static/* 只服务 manifest.frontend.assets 白名单内的文件； 白名单外的文件一律 404；
• 服务前做 Path 规范化 + 白名单校验：../、绝对路径、符号链接逃逸解析后必须仍落在 插件目录内（与 security._resolve_entry_path 同款 resolve() + is_relative_to 防线）；
• 未启用插件不挂载静态资源；CSP 只放开同源自域插件路径，不放宽 open 等指令（S8）；
• 插件路由仅挂载于 /plugins/<name>/api 前缀下，前缀隔离。

D1 的 v2 演进：把插件从"同进程 import + 门禁"升级为"独立子进程 + IPC + 系统级隔离"。

v1→v2 迁移：verify_plugin_integrity 与权限门禁接口保持不变（manager load 的 verify 钩子位、 check_permission(plugin_id, action, scope, registry) 签名延续），桥接层改动集中在能力代理侧。

• logger：angelus.plugins.security（logging.getLogger，get_logger() 可取）；
• 行格式：SECURITY <EVENT> k=v k=v ...（键排序，机器可解析、grep 友好）；
• 事件表：

• 铁律：所有拒绝路径先记日志再返回 False，不允许静默放行/静默拒绝；
• 审计日志是取证与告警的基础：reason 字段区分"配置问题"（not-granted）与"攻击迹象" （checksum-mismatch / entry-unresolvable / traversal）。

• 未授权权限被拒并记日志（声明 shell 但未 granted ⇒ PERMISSION_DENIED reason=not-granted）；
• manifest/entry 改一字节 ⇒ INTEGRITY_DENIED reason=checksum-mismatch，拒绝加载；
• 本文档覆盖风险模型（§1–§7）与 v2 子进程隔离路线（§8）。