技能介绍

认证接入的现实痛点

在 TypeScript/JavaScript 项目里加登录，远不止"调个 API"那么简单。Next.js、Nuxt、SvelteKit 这些框架各有自己的路由和中间件模型，邮箱密码、社交 OAuth、2FA、Passkey 与 RBAC 的组合方式又千差万别。开发者真正卡住的往往是：BETTER_AUTH_SECRET 该放哪、schema 怎么迁移、插件启用后表结构会不会变、受保护路由和会话刷新要怎么衔接。这个技能就是把这套决策过程结构化，避免"照着文档拼凑"导致的安全问题。

技能的核心工作方式

它以认证安全工程师的角色介入，围绕 Better Auth 这个框架无关的认证库展开。核心流程分七步：

环境与配置：确认框架类型后，准备 BETTER_AUTH_SECRET 与 BETTER_AUTH_URL 等环境变量。
服务端实例：在 auth.ts 中配置数据库、邮箱密码、社交 provider，密钥一律走环境变量。
数据库迁移：用 Better Auth CLI 的 generate / migrate 命令生成并应用 schema。
路由挂载：按目标框架挂载 API 处理器，例如 Next.js App Router 下的 app/api/auth/[...all]/route.ts。
客户端封装：创建 auth-client.ts，暴露 signUp、signIn、useSession 等方法。
插件取舍：邮箱密码、OAuth、邮箱验证、密码重置、限流、会话属于内置能力；twoFactor、Passkey/WebAuthn、魔法链接、用户名、组织/多租户、RBAC 则需要额外插件。
检查清单：输出一份覆盖安装、迁移、UI、会话、受保护路由、测试与生产的完整清单。

最终产物是一个结构化工件 AuthPlan，包含框架、认证方式、插件列表、环境变量与迁移标志，可以直接交给后端开发、代码评审或 DevOps 消费。

适用边界与注意点

这个技能只面向 JS/TS 技术栈。非 JavaScript 的认证方案、密钥保管与合规审计不在它的覆盖范围内，需要团队自行负责。另外两个容易踩坑的点：启用 2FA 或 Passkey 等插件后，必须用 CLI 重新生成 schema 并迁移，否则表结构缺失会导致运行时报错；社交 provider 的 clientId / clientSecret 必须放在环境变量里，不要硬编码进仓库。