企业官网建设流程全解析

T3 Code认证体系全解：环境认证、按方法授权与Scope映射如何协同

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code

T3 Code 是一款面向 AI 编程代理的开源开发工具（支持 Web、桌面与移动端客户端），其认证体系由三层协同构成：环境认证（谁能连上来）、按方法授权（连上来能调什么）、Scope 映射（每个方法对应哪把"钥匙"）。本文带你快速看懂这套 OAuth 风格的设计，以及它是如何保证最小权限的。

🧩 三层结构：一次连接中发生了什么

T3 Code 的架构是"一个服务端运行时 + 多个客户端"，所有客户端通过一条已认证的 RPC WebSocket与服务端通信（契约定义在 packages/contracts/src/rpc.ts）。认证贯穿其中：

这套模型刻意模仿 OAuth 的既有概念（RFC 6749 的 scope、RFC 6750 的 Bearer、RFC 8693 的令牌交换），以便权限检查可被审计——详见官方内部文档 docs/internals/environment-auth.md。

🔑 环境认证：从配对到会话

配对的起点是一个一次性 Bootstrap 凭证（one-time-token，桌面端另有desktop-bootstrap免登录交接）。客户端拿它向服务端"兑换"一个真正的会话，会话上携带若干Scope 字符串：

关键点在于权限子集原则：普通配对链接只授予前四个客户端操作 Scope 加relay:read；而access:*、relay:write等管理权限只属于桌面引导凭证与 CLI 管理凭证。也就是说，一个普通配对客户端无法通过令牌交换把自己升级成管理员。

兑换时支持三种会话方法（定义于 packages/contracts/src/auth.ts）：

• browser-session-cookie：浏览器用一次性凭证换会话 Cookie，Cookie 只是传输适配器，响应绝不把会话密钥暴露给浏览器 JS；
• bearer-access-token：非浏览器客户端通过 OAuth 令牌交换端点获取，默认有效期 30 天；
• dpop-access-token：附带 DPoP 持有证明的令牌，有效期 1 小时。受管中继连接一律使用这种模式——即使令牌泄露，没有对应的密钥也无法重放。

🎯 按方法授权：拿到 WebSocket ≠ 可以调一切

会话建立后，客户端先向/api/auth/websocket-ticket申请一张短期 WebSocket 票证（默认 5 分钟），再把票证拼进 WebSocket URL 完成握手。这一步只是"进门"，真正的门禁在每一次方法调用：

客户端 ──Bearer/DPoP 凭证──▶ 申请 wsTicket ──▶ 升级 WebSocket │ 每个 RPC 方法调用 ──▶ 查 RPC_REQUIRED_SCOPES ──▶ Scope 不足则拒绝

映射表维护在 apps/server/src/auth/RpcAuthorization.ts，例如：

• orchestration.searchThreads、orchestration.subscribeThread→orchestration:read
• orchestration.dispatchCommand→orchestration:operate
• cloudGetRelayClientStatus→relay:read，cloudInstallRelayClient→relay:write
• pullRequestsList→orchestration:read，pullRequestsSubmitReview→orchestration:operate

🗺️ Scope 映射如何"强制协同"

T3 Code 把映射做成了编译期约束：RPC_REQUIRED_SCOPES与 RPC 方法组WsRpcGroup绑定，新增一个 RPC 方法却不指定 Scope，会直接变成类型错误而不是生产环境的运行时漏洞。

Scope 字符串本身也由 packages/shared/src/oauthScope.ts 统一解析与编码——按 RFC 6749 空格分隔、校验字符集合法、去重，杜绝了格式歧义。这样三层就形成了闭环：

1. 配对时决定能申请哪些 Scope（子集检查）；
2. 会话携带已授权的 Scope 集合；
3. 每次方法调用按映射表精确核对所需 Scope。

🚀 快速上手：远程配对与连接

想体验这套认证的实际流程，可以从远程访问入手：

1. 在桌面端Settings → Connections中打开Network access，用Create Link生成配对链接；
2. 或在命令行执行npx t3 pair，直接生成一次性配对令牌与二维码，手机扫码即完成环境认证；
3. 云连接（T3 Connect）则走独立的 Clerk 认证：Web、桌面、移动共用一个 Clerk 应用，CLI 使用支持 PKCE 的无头 OAuth 流程，中继侧通过模板 JWT 与会话令牌校验身份。完整流程见 docs/internals/t3-connect.md 与 docs/user/remote-access.md。

💡 升级注意：认证记录的迁移是一次硬性切换——旧的角色制凭据（owner/client）不会被静默映射为新 Scope，升级后需要重新配对。

📚 关键源码与文档速查

一句话总结：T3 Code 的认证体系把"配对信任"（环境认证）、"会话凭证"（Cookie/Bearer/DPoP）与"逐方法权限"（Scope 映射）拆成三段可审计的关卡，并用类型系统保证任何新增方法都无法绕过授权检查——这正是它既能支撑浏览器、桌面、手机、中继等多种客户端，又始终保持最小权限的关键。

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code