认证与授权模型

身份在哪里读取、每个边界如何判定访问权限,以及为什么没有兜底用户。

认证确定调用者是谁,授权确定调用者能否执行某个操作。Kernlift 把两者放在同一个目录里,在多个层次上检查,并且没有身份兜底。配置登录方式与角色,见配置邮箱密码登录和管理用户、角色与权限。

只有一个地方读取会话

src/server/auth/ 是唯一允许读取 Better Auth 会话的代码。它分为三部分:

文件决定什么主要导出
context.ts调用者是谁requireAuthContext()(默认用法,没有身份时抛错)、getAuthContext()(返回 null,只用于身份确实可选的路径)
guards.ts调用者能否执行操作requirePermission、requireOwnership、requireNotBanned、hasPermission
api-boundary.tsAPI 处理器如何认证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 或被列为公开。

相关文件

src/server/auth/context.ts
src/server/auth/guards.ts
src/server/auth/api-boundary.ts
src/server/auth/auth.ts
src/routes/{-$locale}/app.tsx
src/routes/{-$locale}/admin.tsx

下一步