Paperclip 连接器安全威胁模型：官方文档定的八条硬决策与负向测试清单
给 Agent 接第三方系统，是所有 Agent 平台绕不过去的一步。接上 GitHub、Slack、Google Drive，Agent 才算能干活；可一旦接上，问题就从”Agent 会不会写错代码”变成了”Agent 拿着谁的 token、能碰到哪些仓库、被一封邮件骗了会发生什么”。
Paperclip 仓库里有一份 docs/connections/SECURITY-THREAT-MODEL.md，写明面向的读者是”在 Apps v2 底座上做集成开发或做集成评审的工程师”，读完之后要做的事是：在新增一个 app、一条 connection、一种传输方式或一个 provider 包装层之前，先把授权、凭据、审计、负向测试这四类强制要求确认一遍。文档也交代了来源——从 PAP-2359 里整理出来，映射到 PAP-13211 里通过的 Apps v2 对象模型上；Connections v1 退休之后，这些安全决策留下来了，v1 的实现细节没留。
这篇就照着这份文档讲它写了什么。需要先说清楚：本文只转述文档里明确写下来的威胁分类和要求，不评价这套设计的实际防护效果，也不提供任何绕过手法。文档是一份”必须做到的清单”，不是”做到就安全了”的承诺，它自己在最后单列了一节残余风险。
先看八条硬性决策
文档开头列的这八条叫 Required Security Decisions，语气是命令式的，不是建议：
| # | 决策 | 文档里的具体口径 |
|---|---|---|
| 1 | 凭据只活在 company_secrets 里 | connection 只存 secret 引用和脱敏元数据；原始 OAuth access token、refresh token、API key、app 私钥、webhook secret、远程 MCP bearer token，不许出现在 connection 配置、插件配置、issue 评论、活动日志、导出文件、Agent 可见载荷里 |
| 2 | 连接操作按公司隔离，由 Paperclip 代理 | Agent 不拿长期有效的 provider 凭据；插件/provider 代码只拿单次调用所需的最小材料 |
| 3 | 完全仲裁是强制的 | 工具调用、同步任务、webhook、会影响权限的目录刷新、broker 投影，都要在执行那一刻重新检查 connection 状态、secret 状态、profile/policy 状态、资源过滤器、actor 与公司归属 |
| 4 | 默认拒绝 | 新建的 connection 在明确的 profile/binding/policy 路径出现之前，不产生任何 Agent 可见的访问权 |
| 5 | 权限面宽的 provider 必须带资源过滤器 | GitHub 要 repo/org 边界，Slack 要 channel/workspace 边界，Google Drive/Docs 要 drive/folder/doc 边界；同类宽面 provider 也要各自的边界，否则授权不可用 |
| 6 | 写和管理操作必须显式开 | 有读权限不等于有写权限；破坏性操作，以及新出现或发生变化的写操作，默认走审核 |
| 7 | 吊销立即生效且失败即关闭 | secret 被吊销、connection 被停用、policy 过期、secret 引用丢失、健康检查失败，都会挡住新的执行和排队中的变更类工作 |
| 8 | 外部内容不可信 | provider 返回、聊天消息、文档、webhook 载荷、远程 MCP 输出都可能带提示注入，不得据此放大授权或跳过审批 |
第 5 条和第 8 条是这份文档里最能看出取向的两条。第 5 条等于承认”OAuth 授权本身给的范围往往比你想要的宽”，所以在平台侧再收一层；第 8 条则把提示注入直接写成了一类必须建模的威胁，而不是当作模型能力问题。
保护对象和信任边界
文档把”要保护什么”列成了七类资产：各类令牌与签名密钥；connection 元数据（provider、workspace/账号 id、资源过滤器、健康状态、传输配置、状态）；subject/grant 元数据、provider 租户标识、触发器注册、连接器服务的中继路由状态；治理状态（目录条目、风险等级、隔离状态、profile、binding、policy、action request、信任规则）；被集成改动的 Paperclip 对象（issue、评论、文档、项目、目标、活动行、插件实体、工作产物）；Agent 运行时的能力面，也就是一次心跳里到底暴露了哪些工具；以及审计轨迹本身。
信任边界画了七条，值得单独看一眼的是第 3 条和第 7 条：
- 看板/API 边界：人类认证过的 API 请求。
- Agent/API 边界：Agent bearer key 和运行期作用域令牌。
- 服务端/插件边界：插件 worker 不是授权边界。
- 服务端/provider 边界：厂商 API 和远程 MCP 服务器在信任边界之外。
- Webhook 边界：入站请求在签名校验和去重通过之前，一律当作攻击者可控。
- 连接器服务中继边界：回调和触发器投递，在签名上下文于服务端解析出公司、connection、grant、subject 之前保持不可信。
- 外部内容边界：即使数据是通过一条已认证的 connection 取回来的，它仍然是不可信内容。
“插件 worker 不是授权边界”这句话决定了很多实现细节的归属：授权判断得留在核心服务端路径里，不能挪进插件。
逐个流程的控制点
文档把要求按流程拆开，每段先列威胁再列控制。挑几段说。
创建连接与认证。 威胁列的是伪造 OAuth 回调、state 重放、跨公司绑定 secret、伪造 app 安装元数据、伪造远程 MCP 元数据、令牌泄漏。要求是：OAuth start 记录短时有效，并且绑定到公司、app/provider、请求的 scope、创建者、connection、redirect URI，支持时用 PKCE；回调要拒绝缺失、过期、重放、state 不匹配、redirect 不匹配的请求；API key 和 app 安装这类流程，先把密钥材料写进 company_secrets，再在 connection 上只留引用和脱敏后的账号元数据；健康与认证失败要往 missing_secret、degraded、failed、auth_required 或对应的停用态迁移，也就是失败即关闭；错误载荷和日志里要脱敏可能含凭据的 provider 响应。密钥落地的那一层怎么配，可以对着 密钥管理与 AWS provider 一起看。
目录刷新与工具暴露。 这段防的是上游 schema 漂移悄悄加进破坏性工具、provider 元数据被伪造、Agent 看到自己其实没权限的工具。要求包括：Agent 可见的工具由服务端从当前 profile、binding、policy、目录、connection 状态推导出来，provider 不能不经宿主过滤就把工具自注册进 Agent 会话；新增或改动过的写/破坏性目录条目先隔离待审；目录条目带稳定的 schema/版本哈希，schema 一漂移，之前的审批和信任规则就不再适用。
工具执行。 调用发生那一刻要满足的条件，文档列了一串：actor 属于该 connection 的公司；connection 已启用且状态可用；secret 引用能解析到未被吊销的可用版本；有效 profile 暴露了被请求的目录条目；policy 允许这次请求，或者要求走 action request；工具/操作的风险等级没超过允许路径；资源标识满足该 provider 的过滤器；由审批推导出的信任规则要匹配当前目录 schema 哈希和审批时的确切参数形状；参数和结果在进审计、返回给 Agent 之前先脱敏。这套逐次校验的思路和 MCP 访问治理机制 是同一路数。
同步任务与定时抓取。 威胁是吊销之后排队的活儿还在跑、宽面 provider 大范围爬取、把数据存到批准范围之外。要求是每次任务运行开始时重新解析 connection 状态并重查 profile/policy/资源过滤器；吊销、停用、secret 引用丢失、授权过期都会阻止后续任务启动；同步游标按 connection 和允许的资源限定；任务配置只能收窄，不能放宽资源过滤器。
Webhook。 要求在分发前校验 provider 签名或真实性材料；在改动数据之前先持久化并去重 delivery id；webhook secret 从 company_secrets 里取，不许复制进内联配置；只路由到归属的公司/connection，在签名或 provider 认证过的信封解析出 connection 之前，不采信请求体里的 id；在存外部映射或改动 Paperclip 之前先套资源过滤器；对已吊销或停用的 connection，在 provider 语义要求时可以回 ack，但要记录被过滤/丢弃的结果，且不改 Paperclip 状态。
导入导出。 公司导出只包含 provider 声明、展示元数据、脱敏后的 secret 引用、profile 和 policy 形状，不含密钥值和 refresh token；导入进来的 connection 处于不可用状态，直到目标公司的 secret 引用完成重映射和校验；导入的 profile/binding/policy 只有在被引用的主体和 connection 都能在目标公司里解析出来时才生效。
必须写的负向测试
这份文档少见地把”要写哪些失败用例”直接列进了规范，分五组：
| 组别 | 要覆盖的用例（节选） |
|---|---|
| 跨公司隔离 | A 公司看板用户读写不到 B 公司的 app、connection、目录条目、profile、policy、action request、gateway session；A 公司 Agent 列不出也调不动 B 公司工具；创建/更新接口拒绝来自其他公司的各类 id；A 公司的 webhook 即使外部 id 撞车也改不了 B 公司实体 |
| 越权或无治理访问 | 没有有效 profile/binding 的 Agent 看不到该 connection 的工具；只读授权调不动写/管理/破坏性工具；缺目录选择器、目录条目被停用或被隔离时拒绝执行；宽面 provider 的空资源过滤器被拒；即便上游 token 能访问，对不在允许范围内的 repo/channel/folder/doc/project 的调用也被拒 |
| 吊销与失败即关闭 | 被吊销的 secret 版本、停用的 connection、归档的 app、过期的 policy、丢失的 secret 引用，立即挡住执行；吊销后排队的同步/webhook 工作只记录不改数据；对无效凭据做健康检查不泄漏 provider 密钥材料 |
| OAuth 与回调完整性 | 缺失、过期、不匹配、重放的 state 被拒；redirect URI 不匹配被拒；回调不能把凭据绑进发起 OAuth 之外的公司 |
| 脱敏与 Agent 安全 | API 响应、活动行、issue 评论、action request、导出、工具调用审计里都不出现原始密钥值；外部内容不能放大授权、不能创建 policy、不能审批它自己发起的特权调用；远程 MCP 输出按不可信内容处理，不能绕过 ask-first 门槛 |
把这张表当成接入新连接器时的自查表，比读前面的原则段更好用。真要动手接一个新 provider，接入流程本身在 连接器接入手册与首批 30 个 里。
文档自己承认没解决的部分
结尾的 Residual Risks 一节写了四条，写得挺直白：
- 插件 worker 今天是受信任的运行时代码，不是硬沙箱，所以授权要留在核心服务端路径里。
- 远程 MCP provider 仍然是供应链和提示注入的暴露面，对策是窄的默认 profile、schema 哈希、工具变更隔离、看板监督下的灰度。
- provider 的 OAuth / app 安装 scope 可能比 Paperclip 的资源过滤器更宽，需要 Paperclip 这边执行更窄的内部过滤器。
- 高风险写操作还缺好的交互设计，在产品文案和评审流程被验证之前，默认走 ask-first、dry-run 或草稿语义。
另外文档在开头提示，Connections v3 引入了几个后续阶段才会详细建模的新面：主体绑定的 token 请求、workspace/user 级授权、provider 触发器、托管连接器服务的回调与 webhook 中继。在那些阶段落地之前，文档要求把这四个都当作不可信边界处理。
什么时候这篇不适用
这份文档是给做集成开发和评审的人看的，不是运维手册。它给的是”必须满足的条件”，没有给具体的实现代码、配置项名称、接口路径，也没有给任何检测或验证工具。想知道某个开关在哪里配、某条策略怎么落到具体表单上，得去看对应的部署与治理文档。
它也不覆盖 Agent 侧的默认收紧策略——那部分在 低信任预设 里另有口径。还有一点要留意：文中的对象模型名词（app、connection、profile、binding、policy、action request、catalog entry）是 Apps v2 的说法，官方明确讲了 Connections v1 的实现细节已经作废，看老资料时别混用。
最后，这套要求本身没有给出任何有效性证明或测试结果，文档也没有承诺照做就不会出事。它的价值在于把该问的问题列全了：凭据放哪、谁来判权限、吊销之后排队的活儿怎么办、外部文本能不能改变授权、跨公司的 id 会不会串。接第三方系统之前，这几个问题总得有答案。
延伸阅读
- 从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
- 本专题共 40 篇，完整分组目录见专题页
- Paperclip 连接器怎么接：默认做成目录条目而不是插件，以及首批 30 个的排期逻辑
- Paperclip 的 skill 怎么写：SKILL.md 格式、信任等级与技能库的完整流程
本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档
与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。
我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；
部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。
请以仓库最新内容为准。