T3 Code认证体系全解环境认证、按方法授权与Scope映射如何协同【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 是一款面向 AI 编程代理的开源开发工具支持 Web、桌面与移动端客户端其认证体系由三层协同构成环境认证谁能连上来、按方法授权连上来能调什么、Scope 映射每个方法对应哪把钥匙。本文带你快速看懂这套 OAuth 风格的设计以及它是如何保证最小权限的。 三层结构一次连接中发生了什么T3 Code 的架构是一个服务端运行时 多个客户端所有客户端通过一条已认证的 RPC WebSocket与服务端通信契约定义在 packages/contracts/src/rpc.ts。认证贯穿其中层次解决的问题核心机制环境认证这个客户端是否可信配对链接 → 一次性 Bootstrap 凭证 → 换取带 Scope 的会话按方法授权调用的每个 RPC 方法是否被允许WebSocket 票证 逐方法 Scope 检查Scope 映射方法与权限如何绑定RPC_REQUIRED_SCOPES静态映射表类型层面强制覆盖这套模型刻意模仿 OAuth 的既有概念RFC 6749 的 scope、RFC 6750 的 Bearer、RFC 8693 的令牌交换以便权限检查可被审计——详见官方内部文档 docs/internals/environment-auth.md。 环境认证从配对到会话配对的起点是一个一次性 Bootstrap 凭证one-time-token桌面端另有desktop-bootstrap免登录交接。客户端拿它向服务端兑换一个真正的会话会话上携带若干Scope 字符串Scope权限orchestration:read读取快照、状态、事件、配置与文件系统/VCS 状态orchestration:operate派发用户操作、变更工作区状态terminal:operate创建、附加、输入、清屏、重启、终止终端review:write读取 Review diff 预览以撰写反馈access:read查看配对链接与客户端会话access:write创建或吊销配对链接与会话relay:read/relay:write查看 / 管理受管中继连接关键点在于权限子集原则普通配对链接只授予前四个客户端操作 Scope 加relay:read而access:*、relay:write等管理权限只属于桌面引导凭证与 CLI 管理凭证。也就是说一个普通配对客户端无法通过令牌交换把自己升级成管理员。兑换时支持三种会话方法定义于 packages/contracts/src/auth.tsbrowser-session-cookie浏览器用一次性凭证换会话 CookieCookie 只是传输适配器响应绝不把会话密钥暴露给浏览器 JSbearer-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:readorchestration.dispatchCommand→orchestration:operatecloudGetRelayClientStatus→relay:readcloudInstallRelayClient→relay:writepullRequestsList→orchestration:readpullRequestsSubmitReview→orchestration:operate️ Scope 映射如何强制协同T3 Code 把映射做成了编译期约束RPC_REQUIRED_SCOPES与 RPC 方法组WsRpcGroup绑定新增一个 RPC 方法却不指定 Scope会直接变成类型错误而不是生产环境的运行时漏洞。Scope 字符串本身也由 packages/shared/src/oauthScope.ts 统一解析与编码——按 RFC 6749 空格分隔、校验字符集合法、去重杜绝了格式歧义。这样三层就形成了闭环配对时决定能申请哪些 Scope子集检查会话携带已授权的 Scope 集合每次方法调用按映射表精确核对所需 Scope。 快速上手远程配对与连接想体验这套认证的实际流程可以从远程访问入手在桌面端Settings → Connections中打开Network access用Create Link生成配对链接或在命令行执行npx t3 pair直接生成一次性配对令牌与二维码手机扫码即完成环境认证云连接T3 Connect则走独立的 Clerk 认证Web、桌面、移动共用一个 Clerk 应用CLI 使用支持 PKCE 的无头 OAuth 流程中继侧通过模板 JWT 与会话令牌校验身份。完整流程见 docs/internals/t3-connect.md 与 docs/user/remote-access.md。 升级注意认证记录的迁移是一次硬性切换——旧的角色制凭据owner/client不会被静默映射为新 Scope升级后需要重新配对。 关键源码与文档速查想了解去哪里看认证模型、令牌交换、DPoP 细节docs/internals/environment-auth.md方法 → Scope 映射表apps/server/src/auth/RpcAuthorization.tsScope 与会话方法定义packages/contracts/src/auth.tsScope 解析与编码工具packages/shared/src/oauthScope.ts服务端认证实现apps/server/src/auth/EnvironmentAuth.ts整体架构与 RPC 边界docs/internals/overview.md一句话总结T3 Code 的认证体系把配对信任环境认证、会话凭证Cookie/Bearer/DPoP与逐方法权限Scope 映射拆成三段可审计的关卡并用类型系统保证任何新增方法都无法绕过授权检查——这正是它既能支撑浏览器、桌面、手机、中继等多种客户端又始终保持最小权限的关键。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考