认证与授权模型
身份在哪里读取、每个边界如何判定访问权限,以及为什么没有兜底用户。
认证确定调用者是谁,授权确定调用者能否执行某个操作。Kernlift 把两者放在同一个目录里,在多个层次上检查,并且没有身份兜底。配置登录方式与角色,见配置邮箱密码登录和管理用户、角色与权限。
只有一个地方读取会话
src/server/auth/ 是唯一允许读取 Better Auth 会话的代码。它分为三部分:
| 文件 | 决定什么 | 主要导出 |
|---|---|---|
context.ts | 调用者是谁 | requireAuthContext()(默认用法,没有身份时抛错)、getAuthContext()(返回 null,只用于身份确实可选的路径) |
guards.ts | 调用者能否执行操作 | requirePermission、requireOwnership、requireNotBanned、hasPermission |
api-boundary.ts | API 处理器如何认证 | withApiAuth,接受会话;路由声明后也接受带指定 scope 的 API Key |
AuthContext 包含 userId、roles、permissions、status、sessionId、apiKeyId 和 source。来源为 session、api-key 或 dev-impersonation。
Better Auth 实例在 auth.ts 中根据管理后台保存的设置构建,并挂载在 /api/auth/*,用于 OAuth 回调和重置密码链接。Google 与 GitHub 凭据按请求读取,所以保存后无需重启。
没有身份兜底
未认证的调用者会被拒绝。任何代码路径都不会把它映射为默认用户。唯一的例外是开发环境的登录绕过,它要求同时满足 APP_ENV=development 和显式设置的 AUTH_DEV_IMPERSONATE_USER_ID。只满足其一不会生效。绕过第一次生效时,服务端会打印一条警告。
分层检查访问权限
访问受保护页面的请求要经过多层检查,其中任何一层都足以单独拒绝它。
| 层 | 位置 | 检查内容 |
|---|---|---|
| 请求中间件 | src/start.ts | 没有会话 cookie 的 /app/* 与 /admin/* 页面请求跳转到 /auth/sign-in |
| 工作台布局 | app.tsx | 被封禁的用户跳转到 /system/permission-denied;没有身份或账号未激活跳转到 /system/session-expired |
| 后台布局 | admin.tsx | 要求 admin.access;没有身份跳转到 /system/session-expired,缺少权限跳转到 /system/permission-denied |
| 服务端函数 | requireAdminPermission | 每个后台函数检查自己的权限键,页面从来不是数据的唯一关卡 |
| API 路由 | withApiAuth | 会话或带 scope 的 API Key;否则该路由必须出现在显式的公开列表中 |
在布局层守卫意味着 /app 或 /admin 下新增的页面默认就受到保护。
角色、权限与状态
角色、权限和状态从用户的访问档案、角色分配以及各角色的权限中一并解析。只有运营人员修改用户访问权限时才会写入档案,所以没有档案的用户解析为 active。
| 状态 | 效果 |
|---|---|
active | 正常访问,受权限约束 |
banned | 被所有守卫拒绝,创建会话时即被拒绝。封禁结束时间已过的用户解析为 active |
pending | 未激活,工作台与后台守卫都会拒绝 |
requirePermission 和 requireOwnership 都会先调用 requireNotBanned,所以未激活的账号在任何权限检查之前就会失败。角色是权限键的组合,见角色与权限。
归属检查隐藏存在性
按归属读取的查询把调用者 id 写进查询条件。这样,属于别人的记录与不存在的记录无法区分,接口不能用来探测他人的数据。当记录是否存在本身属于敏感信息时,路由返回 404 而不是 403,/api/status 对他人的任务就是这样处理的。
公开接口需要列出并说明理由
每个 API 路由要么使用 withApiAuth,要么出现在显式的公开接口列表中并写明理由。服务商 Webhook 和签名授权兑换都在这个列表里:它们通过签名或不可猜测的凭据认证。
API Key 与 scope
API Key 以哈希形式存储、只显示一次,并带有 scope:ai:run、ai:read、files:write 和 files:read。用户可以在自己的 Key 上选择 ai:run、ai:read 和 files:write。files:read 为保留项。安装了 agent 时,运营人员还可以签发带 agent:read 和 agent:run 的 Key。
登录限流
auth.sign-in 规则按 IP 与邮箱每 300 秒允许 10 次尝试。它属于 pnpm db:bootstrap-super-admin 写入的基线内容,每次判定都会记入审计日志。被拦截的调用者会跳转到 /system/rate-limited。
如何强制执行
pnpm validate:auth-boundary 检查:会话只在 src/server/auth/ 中读取、布局守卫各自的路由树、没有身份兜底、开发身份模拟需要双重条件、生产环境拒绝模板默认会话密钥,以及每个 API 路由都使用 withApiAuth 或被列为公开。