better-auth

在 Next.js 16 App Router 项目中实现 Better Auth（一个 TypeScript 优先的身份验证库）：服务器配置、客户端（`createAuthClient`）、会话管理和 `app/api/auth/[...all]/route.ts` 处理程序，以及用于路由保护的 `proxy.ts`（取代 middleware）。

涵盖完整功能范围：40 多个 OAuth 提供商（Google、GitHub、Discord、Apple、Microsoft 等）、20 多个插件（2FA、magic links、passkeys、organizations/multi-tenant、enterprise SSO/SAML、SCIM provisioning、Stripe/Polar billing、JWT/Bearer、API keys）和数据库适配器（Prisma、Drizzle、MongoDB、raw SQL）。还涵盖从 Auth.js、Clerk、Auth0、Supabase 和 WorkOS 迁移的路径。Better Auth 本身与框架无关，但此技能中的架构指南（proxy.ts、App Router API 路由）特定于 Next.js；Prisma schema/query 详情请参阅 prisma-7。

Better Auth - 完整身份验证

TypeScript 优先的身份验证库，支持 40 多个 OAuth 提供商和 20 多个插件。

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用一次，并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有身份验证设置和模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 Better Auth 文档
3. mcp__context7__query-docs - 检查提供商/插件的可用情况

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

适用场景

• 在 TypeScript/JavaScript 应用中实现身份验证
• 需要 OAuth 提供商（Google、GitHub、Discord、Apple、Microsoft 等）
• 添加 2FA、magic links、passkeys 或电话身份验证
• 使用 SAML、SCIM provisioning 或 organizations 实现企业 SSO
• 集成 Stripe 或 Polar 订阅付款
• 使用 Sign-In with Ethereum（SIWE）实现 Web3 身份验证
• 从 Auth.js、Clerk、Auth0、Supabase 或 WorkOS 迁移

为什么选择 Better Auth

功能	优势
与框架无关	Next.js、SvelteKit、Nuxt、Remix、Astro、Expo、NestJS
插件架构	只添加所需功能（20 多个插件）
完整 TypeScript 支持	端到端类型安全，包含类型推断
可自托管	数据保留在自己的基础设施上
灵活的数据库支持	Prisma、Drizzle、MongoDB、PostgreSQL、MySQL、SQLite
满足企业需求	SSO、SCIM、organizations、审计日志

版本说明（当前稳定版：1.7.x）

自版本	变更
1.5	独立 CLI npx auth@latest（generate、migrate、secret、init、check…）取代 @better-auth/cli；OAuth 2.1 Provider（@better-auth/oauth-provider）
1.6	根据 createdAt 计算 session.freshAge；弃用 oidcProvider
1.7	移除 oidcProvider；通用 OAuth 提供商使用 signIn.social（不再使用 genericOAuthClient）；通过 advanced.database.joins 进行数据库联接；账户以 (issuer, accountId) 为键；twoFactor.enable 返回由 method 区分的响应；MCP → @better-auth/mcp；SCIM 与 organization 解耦

升级到 1.7 后，重新生成 schema（npx auth@latest generate），并遵循官方 1.7 升级指南。

---

覆盖范围

OAuth 提供商（40+）

Google、GitHub、Discord、Apple、Microsoft、Slack、Spotify、Twitter/X、Facebook、LinkedIn、GitLab、Bitbucket、Dropbox、Twitch、Reddit、TikTok，以及 providers/ 中记录的 25 多个其他提供商。

插件（20+）

插件	用途
2FA	TOTP 验证器、备用代码
Magic Link	通过电子邮件免密码登录
Passkey	WebAuthn 生物特征身份验证
Organization	多租户、角色、邀请
SSO	企业 SAML/OIDC 单点登录
SCIM	目录同步、用户 provisioning
Stripe	订阅计费集成
API Key	机器到机器身份验证
JWT/Bearer	基于令牌的 API 身份验证

数据库适配器

Prisma、Drizzle、MongoDB、raw SQL（PostgreSQL、MySQL、SQLite）和社区适配器。

---

SOLID 架构（Next.js 16）

组件按关注点分离原则组织在 modules/auth/ 中：

• 服务：betterAuth 配置和初始化
• Hooks：用于客户端身份验证状态的 createAuthClient
• API 路由：app/api/auth/[...all]/route.ts 处理程序
• 代理：用于路由保护的 proxy.ts（替代 middleware）

---

参考指南

需求	参考资料
初始设置	installation.md、server-config.md
客户端用法	client.md、session.md
OAuth 提供商	providers/overview.md、各提供商的文档
添加插件	plugins/overview.md、各插件的文档
数据库设置	adapters/prisma.md、adapters/drizzle.md
企业级 SSO	plugins/sso.md、guides/saml-okta.md
付款	plugins/stripe.md、plugins/polar.md
迁移	guides/clerk-migration.md、其他迁移指南
完整示例	examples/ 中的完整实现

---

最佳实践

1. 按需使用插件 - 仅添加实际需要的插件
2. 类型安全的客户端 - 使用从服务端配置生成的类型
3. 会话缓存 - 启用会话缓存以提升性能
4. 速率限制 - 为身份验证端点配置速率限制
5. 安全 Cookie - 使用 secure、httpOnly、sameSite Cookie
6. 数据库索引 - 在用户查询字段上添加索引

---

概念

concepts/ 中介绍了核心概念：

• 会话 - 令牌管理、刷新、撤销
• 数据库 - 架构设计、迁移、适配器
• 插件 - 扩展系统、组合
• OAuth - 提供商配置、回调
• 安全 - CSRF、速率限制、密码哈希
• Cookie - 会话存储、跨域