nuxt4-demo/docs/superpowers/specs/2026-04-16-auth-access-control-design.md

权限与访问控制设计（Nuxt）

背景与目标

当前项目已有基础账号体系与会话能力（登录、注册、获取当前用户），但缺少统一的页面与 API 访问控制策略。
本设计目标：

• 采用登录优先：默认受保护，少量白名单放行
• 保持实现简洁、易维护、可扩展
• 避免常见安全问题（越权、开放重定向、误放行、重定向循环）
• 支持“同一路由按登录态展示不同内容”的页面模式

需求结论（已确认）

• 白名单配置方式：代码静态配置
• 页面策略：默认拦截，白名单放行
• 未登录白名单页面：/、/login、/register，并预留认证辅助页扩展
• 页面展示模式：混合模式
  • 入口页（如 /）同路由按登录态切换
  • 复杂业务页拆分为受保护路由
• 未登录访问受保护页面：跳转 /login?redirect=...，登录后回跳
• API 策略：默认要求登录，仅少数白名单 API 放行

总体方案（方案 1）

采用“双层守卫”：

1. 前端全局路由中间件（页面守卫）
2. 服务端 API 中间件（接口守卫）

两层共同保证：即使前端绕过，后端仍可阻断未授权调用。

架构设计

1) 前端会话状态层

新增统一会话组合式函数（例如 app/composables/useAuthSession.ts）：

• 负责请求 /api/auth/me
• 暴露 loggedIn、user、pending、refresh、clear
• 登录成功后调用 refresh
• 登出或 401 时调用 clear

设计原则：

• 不在多个页面重复写“是否登录”逻辑
• 统一处理会话失效状态

2) 页面守卫层（全局）

新增 app/middleware/auth.global.ts，策略如下：

• 默认：页面需要登录
• 放行白名单：/、/login、/register 及后续认证辅助页（代码增补）
• 未登录访问受保护页：
  • 跳转 /login?redirect=<当前完整路径>
• 已登录访问游客页（如登录/注册页）：
  • 优先跳 redirect
  • 无合法 redirect 则跳默认登录后落地页（初始可设为 /）

3) API 守卫层（服务端）

新增 server/middleware/10.auth-guard.ts，策略如下：

• 仅处理 /api/**
• 默认要求登录
• API 白名单（初始）：
  • /api/auth/login
  • /api/auth/register
  • 必要公开读取接口（如 /api/config/global 的 GET）
• 未登录或无效会话：统一返回 401

补充：

• 登录态来源统一走 event.context.auth.getCurrent()（沿用现有上下文能力）
• 不在错误响应中暴露内部实现细节

关键安全设计

1) redirect 安全校验（防开放重定向）

redirect 仅接受站内相对路径，校验规则：

• 必须以 / 开头
• 禁止 // 开头
• 禁止包含协议（如 http:、https:、javascript:）
• 非法值全部降级为默认落地页

2) 白名单匹配规则（防误放行）

采用“精确匹配 + 明确前缀匹配”：

• 精确：/login
• 前缀：/auth/forgot-password（示例）

禁止宽泛正则（如 ^/a 这类容易误伤或放大权限边界的规则）。

3) 未授权语义统一

• API 统一返回 401
• 页面统一重定向到登录页
• 前端收到 401 后同步清理本地会话状态，避免脏态

4) 防重定向循环

• 登录/注册页不再跳自身
• 当 redirect 指向游客页本身时，降级到默认落地页

代码组织建议

建议新增/调整文件：

• app/composables/useAuthSession.ts：会话读取与缓存
• app/middleware/auth.global.ts：页面访问控制
• app/utils/auth-routes.ts：页面白名单、游客页集合、redirect 校验工具
• server/middleware/10.auth-guard.ts：API 访问控制
• server/utils/auth-api-routes.ts：API 白名单规则

约束：

• 路由规则只在一处定义，避免多处分叉
• 页面与 API 规则分别维护，但命名和模式保持一致

数据流与行为流

场景 A：未登录访问受保护页面

1. 用户进入受保护路由
2. auth.global 判定未登录
3. 跳转 /login?redirect=<原路由>
4. 登录成功后读取并校验 redirect
5. 合法则回跳，不合法则去默认页

场景 B：会话过期后访问受保护 API

1. 请求命中 API 守卫
2. 会话失效，返回 401
3. 前端拦截到 401，清理登录态
4. 若当前在受保护页面，触发跳转到登录页

场景 C：首页双态展示

1. 首页属于白名单可访问
2. 页面内部根据 loggedIn 渲染访客态或用户态
3. 刷新会话后自动切换显示

测试与验收标准

路由访问测试

• 未登录访问受保护页应跳登录并保留 redirect
• 已登录访问登录/注册页应跳转到有效 redirect 或默认页
• 白名单页面在未登录下可直接访问

API 鉴权测试

• 未登录访问受保护 API 返回 401
• 白名单 API 未登录可正常请求
• 过期会话访问受保护 API 返回 401

安全测试

• redirect 注入（http://...、//...、javascript:...）均被拦截
• 白名单边界：/login-xxx 不应命中 /login
• 不出现登录页/注册页重定向死循环

体验测试

• 首页登录态切换稳定，不出现明显错误闪烁
• 登出后状态同步清空，页面表现与未登录一致

渐进实施顺序

1. 增加路由规则常量与 redirect 校验工具
2. 落地前端全局中间件（先页面策略）
3. 落地 API 守卫中间件（再后端兜底）
4. 接入统一会话组合式函数，替换分散状态判断
5. 补齐回归测试与手工验收清单

非目标（本次不做）

• 角色/权限点（RBAC）细粒度控制
• 多租户权限隔离
• OAuth、SSO 等第三方登录
• 动态远端下发白名单配置

风险与应对

• 风险：误将必要接口放入受保护导致前端初始化失败
  应对：白名单初始集合最小化后，逐个验证关键页面
• 风险：新增页面忘记考虑权限属性
  应对：默认拦截策略天然兜底，新增页面仅在确需公开时加入白名单
• 风险：重定向逻辑复杂导致跳转异常
  应对：redirect 工具函数集中实现，并覆盖异常值测试

设计结论

在当前项目阶段，采用“前端全局路由守卫 + 服务端 API 统一守卫”的登录优先模型，能以最小复杂度建立稳定安全边界，并保留后续扩展（认证辅助页、业务页拆分、角色权限）的空间。