用途
该技能用于在应用中实现安全的身份认证与授权，核心方案是集成 Clerk。它面向需要认证用户、保护路由、检查权限、实现基于订阅或角色的访问控制的开发场景，尤其适合 Next.js 应用。
为什么使用 Clerk
资料指出，从零构建安全认证需要处理密码哈希（bcrypt/Argon2 加盐）、会话管理（安全 Cookie、过期与续期）、密码重置流程、账户锁定、MFA、社交登录（Google、GitHub 等 OAuth）、用户数据库同步等，经验丰富的开发者安全实现约需 2-4 周，使用 AI 的开发者存在较高安全缺口风险。资料引用 Veracode 2024 报告称，使用托管认证服务（如 Clerk、Auth0）的应用，认证相关漏洞比自建认证少 73%。Clerk 为 SOC 2 认证，意味着其安全控制经独立审计，使用者可继承该认证。
主要能力
Clerk 负责处理：密码哈希、会话管理、MFA、OAuth 提供商、邮箱验证、密码重置、账户锁定、安全监控、合规（SOC 2、GDPR）。
技能涵盖的实现内容包括：
- 服务端认证：在 API 路由中使用
auth()获取userId，未认证时返回未授权错误。 - 客户端认证：在组件中使用
useAuth、useUser获取加载状态、用户 ID、会话 ID 和用户信息。 - 中间件路由保护：使用
clerkMiddleware与createRouteMatcher匹配受保护路由并调用auth().protect()。 - 授权模式：资源归属校验（比较资源 userId 与当前 userId）、基于角色的访问控制（从 sessionClaims 读取 role）、基于订阅计划的授权（读取 plan，免费用户返回 403）。
- 客户端订阅控制：使用
<Protect>组件按条件渲染，并提供 fallback。 - 完整受保护 API 路由示例：依次执行认证、授权、输入校验、业务逻辑，并组合限流与 CSRF 包装。
- 用户元数据与自定义声明：通过
clerkClient.users.updateUserMetadata写入 publicMetadata 与 privateMetadata，服务端从 sessionClaims 读取，客户端从 user.publicMetadata 读取。 - Webhook 用户同步：使用 svix 验证签名，处理 user.created、user.updated、user.deleted 事件并同步到数据库。
- Convex 集成：在 mutation/query 中通过
ctx.auth.getUserIdentity()获取身份，使用 identity.subject 作为用户 ID。 - 登录/注册/用户按钮组件：SignIn、SignUp、UserButton 的页面与配置示例。
- 环境变量配置：Clerk 可发布密钥、密钥、登录注册 URL、前端 API URL、Webhook 密钥。
使用方式
在 Next.js 项目中安装并配置 Clerk，设置环境变量，创建 middleware.ts 保护路由，在服务端 API 路由使用 auth() 校验，在客户端组件使用 useAuth/useUser/Protect，通过 Webhook 同步用户到自有数据库，按需在 Convex 中读取身份。
安全最佳实践
资料强调：始终在服务端验证，不信任客户端认证检查；不仅检查认证，还要检查授权（资源归属/权限）；使用中间件保护整段路由；优雅处理会话过期（AuthGuard 示例）。
常见错误
不要跳过服务端认证检查；不要信任客户端认证状态用于安全；不要忘记检查资源归属；不要仅凭认证就暴露敏感数据；不要硬编码认证逻辑；不要忘记处理会话过期。
适用场景
需要用户登录、保护仪表盘或管理路由、实现角色权限、控制付费功能访问、将用户同步到自有数据库的 Next.js 应用。
限制
资料未提供该技能的具体安装命令、版本要求、收费与价格信息、支持的平台范围，以及除 Next.js 与 Convex 之外的其他框架集成细节，这些内容暂未提供。