Soar API Setup
将 Swift 连接到兼容 Unified Platform 宿主：客户端构建、宿主环境、Session 与验证。
本页是 Unified Mode 版的 Supabase Setup： 让 iOS App 对着一个兼容 Web 宿主（而不是 Supabase 项目）运行所需的全部配置。 还没确定模式的话，先看后端模式。
不按框架名称给予宿主特权——Next.js、Nuxt、TanStack Start 都可以；是否符合 冻结契约才是兼容边界。
1. 部署兼容宿主
把任意一个 Web 模板部署为 Unified Platform Host，并完成其宿主侧配置 （数据库、Better Auth URL 与密钥、App API）：
先在 Web 端注册并确认 /api/auth/get-session 正常，再动 iOS 侧。跨模板的
整体流程见平台 Unified 快速开始。
2. 配置客户端构建
Unified Mode 只需要 Secrets.xcconfig 里的两个键：
// Secrets.xcconfig
SOAR_BACKEND_MODE = soar_api
SOAR_API_BASE_URL = https:/$()/your-app.example.comSUPABASE_URL/SUPABASE_PUBLISHABLE_KEY 可以留空——这个模式下永远不会构建
Supabase 客户端。
两种模式下 Google 登录都仍需要客户端 xcconfig 里的
GOOGLE_IOS_CLIENT_ID/GOOGLE_REVERSED_CLIENT_ID（原生 Google SDK 在设备上
运行）；Apple 登录使用 App capability，不需要客户端键。
配置错误会终止当前构建。缺少 SOAR_API_BASE_URL 时每个请求都会抛出可诊断
的错误——不存在静默 Supabase 回退。
3. 为这个 App 配置宿主
服务端（所选宿主的部署环境）需要 原生认证 所描述的原生支持：
| 服务端变量 | iOS App 为什么需要它 |
|---|---|
APP_SCHEME=soar:// | App 在每个请求上发送 Origin: soar://；Better Auth 会用 403 拒绝不受信任的 Origin。必须与 App Info.plist 中注册的 scheme 一致。 |
GOOGLE_IOS_CLIENT_ID | 原生 Google ID Token 登录的 audience 白名单条目。 |
APPLE_APP_BUNDLE_IDENTIFIER | 原生 Apple ID Token 登录的 audience——无需 Services ID。 |
REVENUECAT_WEBHOOK_AUTHORIZATION + REVENUECAT_PRODUCT_* | 把 App Store 购买同步到共享的订阅行。 |
APNS_* | 测试推送端点的服务端 APNs 凭据。 |
STORAGE_PROVIDER（生产另加 R2_*） | 支撑 UploadsRepository 的 presigned 直传对象存储。 |
4. Session 存在 Keychain 里
Unified Mode 下 App 使用 Better Auth 的 Bearer token（set-auth-token
响应 header）认证，而不是 Cookie：
- Token 连同最小用户快照（
userId、email、name、image、emailVerified、过期时间）只持久化在 Keychain （KeychainSessionStore）——绝不进UserDefaults，绝不进日志。 - 重启后从 Keychain 恢复会话并向服务端校验；退出登录会同时清理 Keychain 条目和内存状态。
- 任何响应带来新的
set-auth-token时，存储的 token 都会被替换。 - Session 存于数据库、可撤销：在 Web 端撤销会话会让 iOS token 立即失效，
App 把
401视为「需要重新登录」——不会无限重试，也不会回退到 Supabase 认证。
5. RevenueCat appUserID
PurchasesController 始终用当前用户的 UserID.rawValue 登录 RevenueCat——
Unified Mode 下即 Better Auth 用户 ID。正是它让服务端的
RevenueCat Webhook 能把 app_user_id
解析回同一个 Better Auth 用户，并更新 Web 端也在读取的同一行共享订阅。
保持 RevenueCat 的 Restore Behavior 为禁用 Transfer：收据已绑定其他账户 时应当出现面向支持的明确错误，而不是在用户之间悄悄转移权益。
验证配置
在两端跑一遍共享冒烟测试：
- 在 iOS 注册或登录，然后在 Web 端打开同一个账户。
- 在一端更新 Profile，从另一端读取。
- 跨两端创建、编辑、排序、删除 Todo。
- 上传头像并确认其完成 URL 可读。
- 从 Web 端撤销 iOS 会话，确认 App 回到登录页。
- 沙盒购买后，确认两端出现同一份权益。
- 注册设备 Token 并触发 APNs 测试推送。
想要一组具体宿主+客户端的端到端流程，跟 Next.js + Swift Unified Setup 走。