tanstack-start-auth

TanStack Start + Better Auth

适用于 FMC 应用（TILDA、Trassenscout 迁移等）的库配置和 Start 专用接线技能。

适用场景

• 创建或修改 betterAuth() / createAuthClient() 配置
• 挂载 /api/auth/*、tanstackStartCookies() 插件、OAuth 登录路由
• beforeLoad 守卫、endpointAuth、服务器函数或 API 处理器中的会话
• 公开与受保护的服务器函数（public*.functions.ts 命名）
• 自动化端点上的 API 密钥 + 会话双重身份验证

参考资料（按需阅读）

主题	文件
TanStack 路由、Cookie、会话辅助函数、TILDA 模式	references/auth.md
Trassenscout 身份验证 lint 模式	references/endpoint-auth-lint.md
betterAuth 选项、数据库、插件、会话、钩子	references/better-auth-config.md

在线文档： better-auth.com/docs · llms.txt

相关技能

• tanstack-router-conventions — validateSearch、搜索序列化、加载器 + Query
• tanstack-start-conventions — 布局、.server.ts / .functions.ts、边界、SSR
• playwright-skill — E2E 模拟身份验证（TILDA）

不可妥协的规则

1. 会话辅助函数始终接收当前请求中的 headers: Headers。
2. 路由 beforeLoad 不直接调用数据库/会话 — 使用服务器函数 + getRequestHeaders()。
3. 使用官方的 tanstackStartCookies() 作为最后一个插件；在 better-auth 版本变更后确认没有客户端包泄漏（auth.md）。
4. /api/auth/$ 和其他仅处理器 API 路由：ssr: false（selective-ssr.md）。
5. API 路由：在每个处理器中进行身份验证（不使用路由级 beforeLoad）。
6. 使用 Cookie 缓存进行管理员/角色检查时：getSession({ query: { disableCookieCache: true } })。
7. 使用时序安全的相等比较来比较 API 密钥。
8. 两层机制：beforeLoad = 仅用于路由 UX；endpointAuth / 守卫 = 数据边界。绝不能只依赖 beforeLoad。
9. 不要使用身份验证中间件进行路由守卫 — 使用布局 beforeLoad。全局身份验证中间件会破坏公开 RPC（public*.functions.ts、getSessionForRouteFn），也不符合 FMC 的身份验证路由模式。

快速模式

// beforeLoad (via server fn)
await routeSessionFn({ data: location })

// API handler
const session = await endpointAuth.session(request.headers)

// Server function
const headers = getRequestHeaders()
await endpointAuth.admin(headers)

设置概览

1. 在 auth.server.ts 中配置 betterAuth()（Prisma/Drizzle 适配器、插件）
2. 使用匹配的客户端插件配置 createAuthClient()
3. /api/auth/$ → auth.handler(request)（通过 tanstackStartCookies() 插件处理 Cookie）
4. 接收 Headers 的 session.server.ts 辅助函数
5. 插件变更后运行 CLI 迁移/生成 — 详情见 better-auth-config.md