T3 Connect 设置¶

T3 Connect 的部署与客户端配置。架构说明 解释了信任边界；relay README 包含 relay 的部署说明。

公共应用配置¶

T3 Connect 在全新克隆的仓库中默认禁用。要针对生产部署进行构建，请复制仓库根目录的示例文件：

cp .env.example .env

对于其他部署，请在仓库根目录的 .env 或 .env.local 中设置以下值：

T3CODE_CLERK_PUBLISHABLE_KEY=<publishable key>
T3CODE_CLERK_JWT_TEMPLATE=<JWT template name>
T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=<public OAuth application client ID>
T3CODE_RELAY_URL=https://relay.example.com

进程变量优先于 .env.local，而 .env.local 优先于 .env。请使用这些规范名称；构建加载器会提供框架特定的别名。这些值是公开标识符。CLERK_SECRET_KEY 只应放在 relay 的 secrets 中，绝不能放在客户端配置中。

客户端和捆绑服务器构建会嵌入这些公共值，因此请在构建前设置好。EAS 预览和生产环境需要 publishable key、JWT 模板名称和 relay URL。捆绑服务器也接受面向运维管理部署的运行时覆盖。

将 infra/relay/.env.example 复制到 infra/relay/.env 以进行 relay 部署设置。请先部署 prod，再部署个人阶段，因为 prod 拥有其分支所依赖的保留数据库。该部署栈的 PublishClientConfig 操作会将生成的 relay URL 写回根目录的 .env。

CLI OAuth 应用¶

在 Clerk 的 OAuth 应用设置中：

1. 为 T3 CLI 创建一个公共 OAuth 应用，使用带 PKCE 的授权码交换（authorization-code exchange）。
2. 允许重定向 URI http://127.0.0.1:34338/callback。
3. 启用 openid、profile、email 和 offline_access 这些 scope。
4. 在该应用上启用 Device authorization grant。Headless 和 SSH 授权会使用它；Clerk 只有在该功能启用后才会通告设备端点。该功能处于 beta 阶段，Clerk 会在收到请求后按账户启用。
5. 在本地和发布构建环境中，将 T3CODE_CLERK_CLI_OAUTH_CLIENT_ID 设置为生成的公共客户端 ID。

JWT 模板¶

创建一个名为 t3-relay 的 Clerk JWT 模板，并包含以下 claims：

{ "aud": "t3-code-relay" }

对于客户端，设置 T3CODE_CLERK_JWT_TEMPLATE=t3-relay；对于 relay，设置 CLERK_JWT_AUDIENCE=t3-code-relay。生产 relay 部署环境还会定义 CLERK_JWT_TEMPLATE。audience 在所有 relay 阶段中保持不变；relay URL 决定选择哪个部署。

桌面 OAuth 重定向¶

启用 Clerk 的 Native API，并将桌面重定向添加到其 SSO 重定向允许列表：

t3code-dev://app/
t3code://app/

将对应的 origin 添加到 Clerk 实例的 Backend API allowed_origins 数组中。开发环境使用 t3code-dev://app，生产环境使用 t3code://app。使用 Clerk secret key，通过 PATCH https://api.clerk.com/v1/instance 更新数组，并保留现有条目。Clerk Electron 集成负责处理令牌持久化和系统浏览器回调投递。

Android 原生登录重定向¶

Clerk 的原生 Android SDK 使用 clerk://<applicationId>.callback。在由应用的 publishable key 选定的 Clerk 实例中，将每个受支持的包添加到 Native applications > Allowlist for mobile SSO redirect：

保留现有条目。这些回调与 t3code-dev / t3code-preview / t3code 导航方案相互独立。使用生产 Clerk key 的私有开发构建仍需要该实例管理员允许其开发回调；重新构建相同的包不会改变允许列表。

桌面 passkey¶

对于 bundle ID 为 com.t3tools.t3code 的生产 macOS 应用：

1. 在 Apple Developer 门户中创建一个显式 macOS App ID，并启用 Associated Domains（关联域名）。
2. 为该 App ID 和分发签名证书创建一个 provisioning profile。
3. 在 Clerk 的 Native API 设置中，添加一个具有相同 Apple Team ID 和 bundle ID 的 iOS 应用。此设置也会配置 Electron/macOS passkey。
4. 检查 https://<frontend-api>/.well-known/apple-app-site-association。其 webcredentials.apps 必须包含 <TEAM_ID>.com.t3tools.t3code。
5. 按照发布手册中的说明配置签名。

本地签名构建还会使用：

T3CODE_APPLE_TEAM_ID=ABC1234567
T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
# Override only when the RP domain differs from the Clerk Frontend API hostname.
T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com

如果没有这个覆盖，构建会从 Clerk publishable key 推导出 RP 域。更改 Associated Domains 后，在重新构建之前应递增构建版本。否则，macOS 可能会为相同的应用/版本组合复用过期的 Shared Web Credentials 元数据。

普通的 dev:desktop 启动器未签名，无法使用 macOS passkey。要进行 renderer HMR，请先安装签名构建，启动 vp run dev:web，然后使用实际的 web 和服务端口启动已安装的可执行文件。例如，使用默认端口：

VITE_DEV_SERVER_URL=http://127.0.0.1:5733 \
T3CODE_PORT=13773 \
  "/Applications/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)"

在原生依赖、主进程、preload、entitlement、provisioning 或签名发生变更后，请重新构建签名应用。renderer 的编辑可以复用该构建。测试前请验证已安装的 bundle：

codesign --verify --deep --strict "/Applications/T3 Code (Alpha).app"
codesign -d --entitlements :- "/Applications/T3 Code (Alpha).app"

限制注册¶

使用 Clerk 的 allowlist（白名单）来限定允许的电子邮件地址或域名，或使用 Restricted（受限）模式进行仅限邀请的注册。启用的空 allowlist 会阻止所有新用户注册。

注册限制不会撤销现有账户的访问权限。当需要禁用某个账户的有效会话和未来登录时，应在 Clerk 中封禁该账户。