17 · 执行环境、配对与远程访问
Direct、Relay、Tailscale、SSH 如何落到同一环境模型，token、DPoP 与 WS ticket 又如何分工。
先分清 Identity、Launch 与 Access
“远程服务器”常被写成一个 URL，但 T3 Code 将它拆成三件事：
- ExecutionEnvironment identity：这是哪一个 T3 Server/工作环境；
- Launch method：谁负责启动它，例如本机 Electron、SSH、WSL、已有 daemon；
- Access method：客户端怎样到达它，例如 direct URL、managed relay tunnel、Tailscale。
同一环境可以更换 IP、从局域网切到 Tailscale，或由桌面 SSH 重新启动。只要 identity 稳定，项目/thread 不应被复制成“新服务器”。
client-runtime/environment 描述 identity/endpoint，connection/resolver 根据已知环境与当前平台能力解析可用路径。
本地认证也不能省
Server 拥有终端、Git 与 Agent 权限。即使只监听 localhost，也不能默认所有网页脚本都可信；Electron 未来还可能暴露局域网/Tailscale。
EnvironmentAuth 因此统一处理 session、pairing、scope 和 WebSocket upgrade。
Server 侧关键持久对象包括：
- Server secret / identity；
- auth session 与 last connected metadata；
- pairing grant/link；
- authorization scopes；
- DPoP proof key thumbprint。
迁移 020、031、032 显示权限从简单 session 逐步演化为 access management、方法 scope 和 proof-of-possession。
配对流程
配对解决“新手机怎样得到访问某执行环境的授权”。典型流程：
- 已有管理员/本机界面请求一次性 pairing grant；
- 生成带短期材料的链接/二维码；
- 新设备打开链接，验证环境身份与 grant；
- 新设备提交自己的 proof key / metadata；
- Server 原子消费 grant，创建有 scopes 的 session；
- 客户端把 session/私钥存进 secure storage；
- 后续连接只使用常规授权，不重复携带 pairing secret。
Hosted pairing link 将敏感 token 放在 URL fragment (#...)，而非 query。Fragment 默认不随 HTTP request 发给承载页面的 server，
前端脚本再读取并兑换，降低 CDN/access log 泄漏。
Fragment 不是完整安全方案
它只减少传输到页面服务器的机会。浏览器扩展、恶意脚本和截图仍可能读取，因此 grant 还必须短期、单次消费、绑定环境并在兑换后清理 URL。
Bearer、DPoP 与 WS ticket 的分工
Bearer / session token
证明客户端拥有一个已授权 session，适合放在 HTTPS Authorization header。若单独泄漏，持有者可能重放。
DPoP
客户端为请求签名，Server 验证 proof、时间、目标、nonce/jti 等，并将 session 绑定到公钥 thumbprint。窃取 token 而没有私钥时难以使用。 Server 与 relay 都有 DPoP 验证/消费测试，重放 proof 必须被拒绝。
WebSocket ticket
浏览器建立 WS 时难以设置自定义 header，于是先用 bearer/DPoP 的 HTTPS 请求兑换短期、单用途 ticket，再把 ticket 放 WS URL。 Ticket 过期/消费后不可作为长期 API 凭据。
RPC scopes
握手成功只建立 principal；每个方法仍通过 requiredScopeForRpcMethod 授权。即使某条 transport 被错误复用，低权限 session
也不能调用管理/写入方法。
T3 Connect 控制面
infra/relay 包含边缘 Worker/API、环境链接、managed endpoint allocation、token/DPoP、数据库、队列和移动 activity/push 设施。
Server 侧 cloud/ 管理登录、环境 key、managed endpoint runtime、boot/pinned service 与 tracing。
一个重要边界是：Relay/Connect 负责发现、配对、路由和控制元数据；正常 Agent RPC 热路径经分配的 tunnel/endpoint 到 Server， 不是让所有消息内容先进入中心 Worker 再转发。
签名环境发布用于防止 Relay 将错误 endpoint 绑定到环境；managed tunnel limits 防止滥用/资源无限分配。
Agent activity 与推送
Relay 的 agentActivity/ 包含 device registration、live activities、APNs token、delivery queue/attempt。合理原则是只发送唤醒和最小状态，
客户端随后从 Server 获取权威 thread projection；不要把完整提示、代码 diff 或凭据放进 push payload。
Delivery 是至少一次、可能延迟的外部系统，因此 UI 不应把“收到 push”当 turn 完成事实。它只触发连接 runtime wakeup。
Tailscale
Tailscale endpoint provider 发现 tailnet 可达地址。它提供网络层私有可达性，但不替代 T3 auth：tailnet 成员不一定都应拥有终端写权限， 浏览器来源和 session 撤销仍需应用层控制。
Desktop-managed SSH
SSH 模式由 Desktop 启动/连接远端 T3 Server，处理密码/host-key prompt，再把环境 descriptor 交给 renderer。 SSH transport 的认证只证明桌面能登录远端机器；T3 Server RPC 仍建立自己的 environment session，以保持 Web/Mobile/Direct 行为一致。
威胁与控制对照
| 威胁 | 控制 |
|---|---|
| URL 日志泄漏长期 token | HTTPS header + 短期 WS ticket；pair token 放 fragment |
| token 被复制重放 | DPoP proof key、jti/时间验证与消费 |
| 低权限设备调用终端写入 | 方法级 scope 授权 |
| 恶意 pairing link 重复使用 | 短期、单次原子消费、环境绑定 |
| Relay 篡改环境 endpoint | 环境发布签名/身份校验 |
| 隧道资源滥用 | managed allocation 与 limits |
| Push 泄漏代码 | 只发送最小活动/wakeup metadata |
| endpoint 变化产生重复环境 | identity 与 access method 分离 |
源码锚点
- EnvironmentAuth
- DPoP
- RPC Authorization
- Client environment model
- Managed endpoint runtime
- Relay API
- Environment connector
可迁移经验
- 环境身份、启动方式、访问路径分开建模，网络切换才不会复制业务对象。
- 浏览器 WS 使用短期 ticket；握手之后仍做方法级授权。
- Pairing 是授权委派协议，不只是二维码字符串。
- 网络私有层（Tailscale/SSH）不替代应用授权。
- 云控制面只保留发现和路由所需数据，业务热路径尽量端到端到执行环境。