T3 Connect 架构解析：可信中介、一次性铸造凭据与托管隧道生命周期

T3 Connect 架构解析可信中介、一次性铸造凭据与托管隧道生命周期【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Connect 是 t3code 项目中云端身份 远程环境直连的控制面方案它用 Clerk 承载云身份由 relay 负责环境链接、凭据签发与托管隧道分配但应用流量不经 relay 代理。本文以 docs/internals/t3-connect.md 为主干结合环境云处理器、relay 连接器与托管端点提供者的源码实现完整还原其信任模型、链接生命周期与 OAuth 细节帮助读者在接入、部署或修改协议时准确理解每一处安全约束。一、总体架构控制面与数据面分离T3 Connect 的核心设计是relay 只做控制面不做数据面云身份由Clerk提供relay 不自己维护账号体系relay托管控制面负责管理环境链接environment link、维护到达环境的凭据、以及托管隧道managed tunnel的分配客户端完成 bootstrap 之后应用流量HTTP 与 WebSocket 会话直接通过环境的隧道主机名传输relay Worker 全程不代理。这一点在 infra/relay/README.md 中被明确强调The relay is intentionally not in the hot path for normal T3 Code traffic它只负责将 T3 Code 环境链接到云账号预配并跟踪托管环境端点签发用于客户端连接链接环境的短时凭据列出账号下的链接环境与移动设备注册移动通知偏好与 APNs/FCM token接收发布的 agent activity 并投递通知或 Live Activity。因此relay 的停机不会中断已建立的直连会话它只影响新链接的建立、凭据签发与在线状态探测。二、relay 是可信中介trusted broker2.1 环境链接 一次性 bootstrap 凭据一个已经通过 Clerk 认证的云用户仍然需要一条活跃的环境链接才能连接到具体环境。整个信任链是这样建立的relay 要求目标环境铸造mint一个一次性 bootstrap 凭据该凭据绑定到客户端的 DPoP 证明密钥proof key客户端拿着 bootstrap 凭据直接与环境交换换取环境会话environment session详见 docs/internals/environment-auth.mdrelay 永远拿不到这个会话 token仅持有 bootstrap 凭据没有客户端的私钥就无法赎回——它被 DPoP 密钥绑定单独泄露不足以完成登录。从 apps/server/src/cloud/http.ts 的cloudMintCredentialHandler第 945 行起可以看到铸造实现relay 提交的 mint proof 通过verifyRelayJwt校验issuer 为 relayaudience 为t3-env:environmentId随后环境用createPairingLink签发一个仅有 2 分钟 TTL、subject 为cloud-connect、label 为 T3 Connect connect、并绑定proofKeyThumbprint: proof.clientProofKeyThumbprint的配对凭据。响应中的proof字段将requestNonce、clientProofKeyThumbprint与credential三者绑定签名作为 relay 侧验证的依据。2.2 双端认证与四重绑定检查这个交换是双向认证的环境侧接受 mint/health 请求时见 apps/server/src/cloud/http.ts只接受有界bounded、防重放replay-guarded的 relay proofproof 生命周期上限 5 分钟、时钟偏差容忍 60 秒CLOUD_PROOF_MAX_LIFETIME_SECONDS 5 * 60、CLOUD_PROOF_CLOCK_SKEW_SECONDS 60第 94-95 行校验 proof 的environmentId与自身一致、sub等于已链接用户 ID精确 scope 匹配environment:connectmint或environment:statushealth而不是包含即可hasExactScope第 335-340 行mint 时额外校验cnf.jkt clientProofKeyThumbprint第 989 行把凭据钉死在客户端密钥上防重放每个 proof 的jti与nonce都会以cloud-mint-jti-/cloud-mint-nonce-前缀写入 secret store重复消费直接返回EnvironmentHttpConflictErrorconsumeCloudReplayGuards第 134-152 行。relay 侧验证环境响应时见 infra/relay/src/environments/EnvironmentConnector.tsverifyEnvironmentResponse第 214-245 行检查环境签名的响应 proofenvironmentId匹配、requestNonce与 relay 发出的 nonce 一致、clientProofKeyThumbprint与请求一致、credential字段与响应体一致、exp与响应中的expiresAt一致环境使用自己的 Ed25519 密钥对签名verifyWithEnvironmentKeys会遍历该环境全部活跃公钥逐个尝试验证支持密钥轮换第 191-212 行请求全程withoutRedirectsredirect: manual第 188-189 行10 秒超时ENVIRONMENT_MINT_REQUEST_TIMEOUT_MS 10_000。签名的 JWT 类型在 packages/shared/src/relayJwt.ts 统一管理t3-env-linkjwt链接 proof、t3-cloud-mintjwt铸造请求、t3-cloud-healthjwt健康请求、t3-env-mintjwt/t3-env-healthjwt环境响应全部使用 EdDSA 算法验证时默认maxTokenAge5 分钟、时钟容忍 60 秒。这套双端校验意味着隧道背后的其他进程无法冒充已链接的环境——环境用自己的私钥签名响应第三方拿不到该私钥。2.3 签名权限与信任假设relay 持有 mint 请求的签名权限cloudMintPrivateKey这是整个模型最敏感的单点。文档明确提醒DPoP 保护的是一次诚实交换下的凭据不被重用它不能让一个被攻破的 relay 签名密钥变得无害。换句话说如果 relay 的签名私钥泄露攻击者可以伪造 mint proof诱导环境签发凭据。因此修改协议时这一信任假设必须被显式记录在案不能依赖 DPoP 来兜底。2.4 托管隧道只暴露校验过的 loopback 源托管隧道被刻意限制为只暴露一个经过校验的 loopback HTTP 源防止端点发现被滥用为任意出口SSRF 类风险相关约束分布在两处实现apps/server/src/cloud/http.tscloudLinkProofHandler第 427-452 行在生成链接 proof 前通过hasForwardedAuthorityHeaders拒绝携带x-forwarded-host/x-forwarded-proto的请求第 289-294 行防止权威信息被篡改isAllowedEndpointOrigin第 300-314 行要求 host 必须是127.0.0.1、::1或localhost端口必须与分配的端口一致infra/relay/src/environments/EnvironmentConnector.tsresolveManagedEndpoint第 302-392 行从relay 自己的分配记录解析端点而不是调用方提供的 URL依次检查 provider kind、分配是否存在、基础域是否配置、分配是否 ready、hostname 是否合法、解析出的端点与链接中记录的httpBaseUrl/wsBaseUrl是否一致managed_endpoint_mismatch任何一环不符都返回EnvironmentConnectNotAuthorized并附带精确的 reason 枚举此外health 与 mint 请求不得跟随重定向relay 侧withoutRedirects环境侧也以no-store/no-cache响应头CLOUD_CREDENTIAL_RESPONSE_HEADERS避免凭据被缓存。这些限制共同确保端点发现永远不会演变成relay 任意出口也不会暴露环境主机上的其他服务。三、链接的生命周期链接比连接器进程活得更久3.1 意图、暴露与运行是三个独立生命周期文档给出了一个容易被忽略的模型CLI 授权authorization、期望的暴露方式desired exposure、运行中的连接器running connector具有不同的生命周期链接可以记录意图即使服务器当前已停止setCliDesiredCloudLink写入的期望状态依然存在启动时 reconcilereconcileDesiredCloudLinkapps/server/src/cloud/http.ts 第 628-632 行会读取该意图并重新建立链接CLI logout 只移除存储的云凭据并禁用暴露而不会卸载环境的后台服务background service 仍然随系统启动只是不再暴露到云端从 apps/server/src/cli/connect.ts 可以看到 CLI 提供--headless标志与--json输出并会通过SSH_CONNECTION/SSH_TTY环境变量自动检测 SSH 会话。3.2 托管分配与 provisioning checkpoint托管分配managed allocation属于 user/environment 对而不是某个连接器进程。预配过程在 infra/relay/src/environments/ManagedEndpointProvider.ts 中是一组带检查点的阶段第 43-55 行derive-environment-hash → check-tunnel-limit → reserve-allocation → ensure-tunnel → validate-tunnel-response → record-tunnel → configure-tunnel → ensure-dns-record → record-dns → get-tunnel-token → mark-allocation-ready每个阶段完成即持久化对应结果tunnelId、dnsRecordId、readyAt因此重试可以 reconcile 部分完成的脏工作而不是从零开始DNS 记录已存在则更新而非重复创建ensureDnsRecord会先尝试更新首选记录再回退到列表查找、最后才创建隧道已存在则复用tunnels.list后Option.match决定复用或create。3.3 正常关闭释放隧道、保留主机名托管隧道按量计费Cloudflare 按已预配的隧道收费所以CLI 管理的链接在正常关闭时必须释放隧道避免为闲置资源付费但保留主机名保留hostname reservation下次启动重新预配时在同一 URL下重建隧道保留分配记录allocation使环境在离线期间保持offline健康探测失败而不是变成not authorized。release实现第 538-603 行只删除已预配的 Cloudflare 隧道刻意保留 allocation 行与 DNS 记录connect/status的授权要求完整记录的 allocation于是离线环境的 status 依然是可区分的 offline。3.4 两个必须保留隧道的例外有两类关闭场景不能释放隧道它们被显式实现在 apps/server/src/cloud/http.ts 的releaseManagedTunnelOnShutdown第 670-743 行通过客户端web/mobile安装的链接它没有启动 provisioning 路径重启后靠存储的连接器 token恢复没有 boot-time 重新预配流程所以隧道必须跨重启存活unlink 仍会删除它更新交接update handoff待定更新意味着启动器会立即拉起替换服务器此时若替换隧道新隧道 UUID 的路由传播需要 1-2 分钟成为每次更新重启的主导成本。实现通过读取 runtime 目录中的SERVICE_STATE_FILE与SERVICE_STOP_MARKER_FILE判定 pending update 且无停止标记 即为交接场景记录日志 Keeping the managed tunnel across the update restart 后跳过释放。此外只有CLI 期望的 managed 模式链接才会在关闭时释放publish-only 链接根本没有隧道可释放。3.5 并发安全代次声明claim机制释放与解除链接unlink都遵循同一原则在删除外部资源之前先声明claim分配代次allocation generation。原因很直接——延迟清理不得删除一个已被并发重启或重新链接复用的隧道。release用claimRelease携带updatedAt与tunnelId先声明若并发 provision 已经重写了updatedAt快速重启旧声明失效返回 false 表示连接器 token 仍然存活调用方会保留存储的配置deprovision用claimDeprovision先声明再按delete-dns-record → delete-tunnel → remove-allocation顺序拆除第 460-537 行prepareDeprovision第 443-456 行在 unlink 的授权撤销提交之前捕获分配快照防止并发 relink 的更新 allocation 被误删。还有一个重要的顺序约束unlink 先提交授权撤销再执行外部拆除——因为如果数据库失败活跃链接必须保持可用而失败的拆除会保留足够状态以便重试。实现上cloudUnlinkHandlerapps/server/src/cloud/http.ts 第 784-807 行先endpointRuntime.applyConfig(null)停止本地连接器并并发清除全部 7 个云配置 secret最后才setCliDesiredCloudLink(false)。四、OAuth 陷阱CLI 与交互客户端共用同一个 Clerk 应用4.1 同一应用、不同凭据交互式客户端桌面、Web、移动与 headless CLI使用同一个 Clerk 应用但使用不同的凭据体系交互客户端走 Clerk 的session-template JWTCLI 走OAuth token授权码 PKCE。relay同时接受这两种如果在 relay 侧强制要求 CLI 也出示 JWT template 签发的 token会拒绝掉合法登录。这是接入时最容易踩的坑。CLI 是公共 OAuth 客户端public client使用 PKCE不存储任何 client secret——客户端凭据对部署方透明。4.2 为什么授权必须从托管 /connect 页面开始CLI 的授权流程不是直接把浏览器丢进 Clerk 的/oauth/authorize而是先打开托管的/connect页面。原因在 packages/shared/src/connectAuth.ts 的注释里讲得很清楚把未登录的浏览器直接送到/oauth/authorize浏览器会先经过 Clerk 的登录重定向而该重定向无法可靠地保留 authorize 查询参数state、response_type、code_challenge。托管/connect页面会先等 Clerk 会话建立完成再携带完整参数转发authorize 请求。CLI 打印的授权 URL 中state与code_challenge被放在URL fragment#中buildConnectAuthorizeRequestUrl这样它们永远不会进入托管应用的服务器日志或 CDN 日志。4.3 loopback 与 pasted-code 两条回调packages/shared/src/connectAuth.ts 统一维护两条回调路径的 PKCE 与 stateloopback 流程CLI 在127.0.0.1:port/callback监听托管页面让 Clerk 直接把授权码重定向到本地端口loopbackPort通过 fragment 传递pasted-codeout-of-band流程回调结果被编码为code.state单个 blobencodeConnectAuthCode由用户在终端里粘贴checkConnectAuthCode校验返回的 state 与 CLI 自己生成的 state 一致从而在无后端的情况下完成 CSRF 检查授权码与 base64url 的 state 都不含.可安全拼接。SSH 与 headless 会话强制使用 pasted-code 流程——因为远程机器上通常没有浏览器能访问本地的 listenerapps/server/src/cli/connect.ts 通过SSH_CONNECTION/SSH_TTY自动判断。默认托管地址为https://app.t3.codesDEFAULT_HOSTED_APP_URLCLI 打印 URL 与 Web bundle 判断是否托管部署时都以此为准。五、部署与配置要点继承操作手册T3 Connect 的完整部署配置在 docs/operations/connect-setup.md以下是与之配套的关键配置项新克隆的仓库默认禁用T3 Connect。5.1 公共应用配置复制仓库根目录示例并填入生产部署值cp .env.example .envT3CODE_CLERK_PUBLISHABLE_KEYpublishable key T3CODE_CLERK_JWT_TEMPLATEJWT template name T3CODE_CLERK_CLI_OAUTH_CLIENT_IDpublic OAuth application client ID T3CODE_RELAY_URLhttps://relay.example.com注意进程环境变量优先于.env.local再优先于.env这些是公共标识符可以安全地内嵌进客户端构建但CLERK_SECRET_KEY只能存在于 relay 的 secrets 中。客户端与 bundled-server 构建会把公共值内嵌因此必须在构建前设置EAS preview/production 环境也需要 publishable key、JWT template 名与 relay URL。5.2 CLI OAuth 应用在 Clerk 的 OAuth 应用设置中为 T3 CLI 创建公共 OAuth 应用使用带 PKCE 的授权码交换同时允许两个重定向 URIhttp://127.0.0.1:34338/callback与https://app.t3.codes/connect/callback自定义T3CODE_HOSTED_APP_URL需要自己的/connect/callbackheadless 与 SSH 授权依赖托管重定向启用openid、profile、email三个 scope将生成的公共 client ID 写入本地与发布构建环境的T3CODE_CLERK_CLI_OAUTH_CLIENT_ID。5.3 JWT template创建名为t3-relay的 Clerk JWT template{ aud: t3-code-relay }客户端设T3CODE_CLERK_JWT_TEMPLATEt3-relayrelay 设CLERK_JWT_AUDIENCEt3-code-relayaudience 跨 relay 阶段保持不变用 relay URL 选择部署。5.4 桌面与 Android 原生重定向桌面端启用 Clerk Native API并把以下 scheme 加入 SSO 重定向白名单t3code-dev://app/ t3code://app/并用PATCH https://api.clerk.com/v1/instance更新 Backend API 的allowed_origins。Android 原生 SDK 使用clerk://applicationId.callbackVariantCallbackDevelopmentclerk://com.t3tools.t3code.dev.callbackPreviewclerk://com.t3tools.t3code.preview.callbackProductionclerk://com.t3tools.t3code.callback这些 callback 与t3code-dev/t3code-preview/t3code导航 scheme 相互独立即使使用生产 Clerk key 的私有开发构建也仍需要该实例管理员允许其开发 callback。5.5 限制注册使用 Clerk 的 allowlist按邮箱或域名或 Restricted 模式仅邀请注册。注意注册限制不会撤销已有账号的访问权限——需要禁用其活跃会话与未来登录时应在 Clerk 中封禁ban该账号。六、安全模型小结把整篇架构落到一条主线T3 Connect 用凭据铸造 双向签名 代次声明把信任边界收敛到可验证的窄接口。安全目标实现机制源码位置relay 不接触环境会话bootstrap 凭据由环境直接签发并绑定 DPoP 密钥apps/server/src/cloud/http.ts 第 945-1064 行防凭据重放/重用5 分钟有界生命周期 jti/nonce一次性消费 精确 scope同上前 90-95、134-152、335-352 行防端点发现变为任意出口拒绝转发权威头、只解析自有分配、禁止跟随重定向infra/relay/src/environments/EnvironmentConnector.ts 第 188-189、302-392 行防并发清理误删复用资源release/deprovision 先声明分配代次infra/relay/src/environments/ManagedEndpointProvider.ts 第 443-537、538-603 行离线可区分、空闲不付费关停只删隧道、保留主机名与分配记录apps/server/src/cloud/http.ts 第 670-743 行最后回到文档最直接的告诫DPoP 与一次性凭据保护的是诚实交换被攻破的 relay 签名密钥是协议模型的固有风险。任何改动引入新的凭据类型、放宽 scope 校验、改变隧道解析方式都必须先明确回答这一环的信任假设是什么、由谁背书。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考