skillhub/docs/03-authentication-design.md

skillhub 认证与授权设计

外部身份架构说明：LDAP、DingTalk、CAS、SAML、可信代理及其他新外部身份接入， 以 统一身份联邦设计 为准。GitHub、 GitLab 和标准 OIDC 已迁入统一身份核心；DirectAuthProvider 和 PassiveSessionAuthenticator 仍是兼容扩展点，不是新 Provider 的目标契约。新 Provider 只能返回协议验证结果，由统一核心归一化为内部 IdentityAssertion，不得 直接返回 PlatformPrincipal。

0. 身份标识约束

• PlatformPrincipal.userId 必须是稳定的字符串标识，而不是 Long。
• 用户身份在系统内的主契约是字符串 userId；认证、授权、审计、资源 owner 判定都基于该字符串进行。
• 外部身份源的 subject、企业 SSO UID、工号型字符串等都必须可以原样或经确定性映射后进入系统，禁止先压缩成自增整数再作为正式用户主键在全链路传播。
• 历史草案里的整型用户主键描述全部废弃，当前认证与授权设计只承认字符串身份主键。

1. 认证架构

请求进入
  │
  ▼
┌─────────────────────────────┐
│  Layer 1: OAuth2/OIDC Login │  Spring Security OAuth2 Client
│  (GitHub/GitLab/OIDC 可扩展) │  授权码模式 (Authorization Code)
│  Layer 1b: Session Bootstrap│  显式被动会话引导（默认关闭）
└─────────────┬───────────────┘
              │ OAuth2User
              ▼
┌─────────────────────────────┐
│ Layer 2: Identity Core      │  受信 descriptor + Authority Lock
│                             │  Assertion Factory + 账号状态守卫
└─────────────┬───────────────┘
              │ IdentityAssertion
              ▼
┌─────────────────────────────┐
│  Layer 3: Policy + Mapping  │  Login / Provisioning Policy
│                             │  Binding V2 + 字段来源与资料同步
└─────────────┬───────────────┘
              │ PlatformPrincipal
              ▼
┌─────────────────────────────┐
│  Layer 4: Session / Token   │  Web: Spring Session (Redis)
│                             │  CLI: Device Flow + Bearer Token
└─────────────┬───────────────┘
              │ SecurityContext
              ▼
┌─────────────────────────────┐
│  Layer 5: Authorization     │  RBAC + 资源级判定
└─────────────────────────────┘

2. 准入策略（Access Policy）

OAuth 认证成功仅代表身份可信，不代表有权使用平台。准入层在认证成功后、创建平台用户前执行。

// 基于统一身份上下文的准入策略，与底层协议无关
public interface AccessPolicy {
    AccessDecision evaluate(IdentityAccessContext context);
}

public record IdentityAccessContext(
    String providerCode,
    String subjectType,
    String subject,
    Optional<String> email,
    EmailAssurance emailAssurance,
    IdentityLoginContext requestContext,
    IdentityAccessKind accessKind,
    Optional<UserStatus> existingAccountStatus
) {}

public enum AccessDecision {
    ALLOW,              // 本次登录准入
    DENY                // 拒绝，不建立 Session，重定向到拒绝页
}

2.1 一期支持的策略（通过配置切换）

skillhub:
  access-policy:
    mode: EMAIL_DOMAIN   # OPEN / PROVIDER_ALLOWLIST / EMAIL_DOMAIN / SUBJECT_WHITELIST
    allowed-providers:
      - github
    allowed-email-domains:
      - company.com
      - subsidiary.com

策略	判定依据	说明
OPEN	无限制	所有 OAuth 登录用户自动准入
PROVIDER_ALLOWLIST	context.providerCode	仅允许指定 Provider 登录
EMAIL_DOMAIN	context.email + context.emailAssurance	仅允许 VERIFIED / AUTHORITATIVE 邮箱且域名匹配
SUBJECT_WHITELIST	context.providerCode + context.subject	按 provider:subject 白名单，管理员预添加

2.2 准入失败处理

• DENY：抛出 OAuth2AccessDeniedException，由 failureHandler 重定向到 /access-denied 页面。不创建用户，不建立 Session。

安全边界：PENDING / DISABLED / MERGED 用户和 system account 绝不会通过交互式登录获得 业务 Session。外部身份命中这些账号时，在更新用户资料或加载角色前直接拒绝。

2.3 首次建号策略（Provisioning Policy）

Login Policy 每次登录执行；Provisioning Policy 只在外部身份尚未绑定时执行。二者不能 再通过 AccessDecision 混合表达。

模式	未绑定身份的行为
AUTO	创建 ACTIVE Account、Binding、typed Subjects 和 @global MEMBER
APPROVAL	创建 PENDING Account、Binding 和 typed Subjects，不建立 Session
EXISTING_BINDING_ONLY	不创建任何记录，返回 ACCESS_DENIED

APPROVAL 下，相同身份重复登录继续命中原 Binding 并返回 ACCOUNT_PENDING，不会重复 建号。管理员批准时在同一事务把账号改为 ACTIVE 并补齐 @global MEMBER；拒绝时改为 DISABLED 并保留 Binding，防止反复创建 PENDING 账号。

配置是受信 descriptor 的一部分，按 Provider Instance 生效：

skillhub:
  auth:
    identity:
      providers:
        corp-oidc:
          provisioning-mode: APPROVAL
          profile-sync:
            display-name: PRESERVE_LOCAL
            email: FILL_IF_EMPTY
            avatar-url: INITIAL_ONLY

2.4 资料同步策略

user_profile_field_source 记录 displayName、email、avatarUrl 当前值来自 Provider、 用户、管理员还是历史本地数据。升级迁移把已有非空值标记为 LEGACY_LOCAL，避免升级后 第一次外部登录覆盖历史资料。

每个字段支持 NEVER、INITIAL_ONLY、FILL_IF_EMPTY、PRESERVE_LOCAL 和 PROVIDER_AUTHORITATIVE。默认 displayName/avatarUrl 使用 PRESERVE_LOCAL，email 使用 FILL_IF_EMPTY，且 email 只有 VERIFIED / AUTHORITATIVE 才能写入。显式设置 PROVIDER_AUTHORITATIVE 后，登录 Provider 可以覆盖本地值；这项例外必须配置在具体 Provider 和具体字段上。

2.5 Email 碰撞

未绑定身份携带可信 email，而平台已有相同 email 时，核心只返回 LinkRequired("EMAIL_COLLISION")：

• 不按 email 自动绑定账号；
• 不返回目标 userId、账号资料或可直接完成绑定的 token；
• 不创建 Account、Binding 或 Subject；
• PR 5 的显式 Identity Link 完成前只展示安全提示和已有账号登录入口。

2.6 扩展性

后续新增 OAuth Provider（Google、GitLab、微信）时，准入策略与 Provider 无关，统一在 AccessPolicy 层判定，不需要重做入驻逻辑。

3. Web 认证流程（OAuth2 / OIDC Authorization Code）

浏览器点击"登录"
    │
    ▼
前端跳转: /oauth2/authorization/github
    │
    ▼
Spring Security 重定向到 GitHub 授权页
    │
    ▼
用户在 GitHub 授权
    │
    ▼
GitHub 回调: /login/oauth2/code/github?code=xxx&state=xxx
    │
    ▼
Spring Security 自动完成:
  ① 用 code 换取 access_token
  ② 调用 GitHub API 获取用户信息
  ③ 触发自定义 OAuth2UserService
    │
    ▼
CustomOAuth2UserService / CustomOidcUserService:
  ① Adapter 从已验证响应提取 ProviderAuthenticationResult
  ② 服务端路由解析 ResolvedProviderHandle
  ③ 统一身份核心读取受信 descriptor，执行 Authority pin/复核
  ④ Assertion Factory 固定 provider/authority/subject/属性映射
  ⑤ 解析全部 Subject，锁定已有 Binding / Account
  ⑥ Account Guard + AccessPolicy.evaluate(IdentityAccessContext)
  │
  ├── DENY → 抛出 OAuth2AccessDeniedException → failureHandler 重定向 /access-denied（不建立 Session）
  └── ALLOW ↓
  │
  ⑦ 已绑定 → 按字段来源和 Profile Sync Policy 同步允许字段
  └── 未绑定 → Provisioning Policy + email collision 检查
      ├── AUTO → 创建 ACTIVE Account + Binding + Subjects + membership
      ├── APPROVAL → 创建 PENDING Account + Binding + Subjects
      └── EXISTING_BINDING_ONLY → 拒绝且不写入
    │
    ▼
AuthenticationSuccessHandler:
  ① 创建 Spring Session (Redis)
  ② 重定向到前端页面 (可配置的 redirect_uri)

OIDC 登录沿用同一条业务链路，但由 Spring Security 的 oidcUserService 分支处理。CustomOidcUserService 会把标准 OIDC claims 映射为 ProviderAuthenticationResult：

• Subject candidate：类型固定为 oidc_sub，值为大小写敏感的 OIDC sub
• 属性事实：email、email_verified、preferred_username、name、picture
• 协议证据：只包含 oidc、认证时间和认证方法，不包含 token 或原始响应
• Provider code、issuer Authority 和最终属性映射由服务端受信 descriptor 固定

identity_binding(provider_code, subject) 保留兼容 primary 值， identity_binding_subject 保存 typed primary/alias，并通过数据库约束保证一个 ACTIVE Binding 恰有一个 ACTIVE primary。identity_provider_state 只保存 Provider code、 protocol、canonical Authority、SHA-256 fingerprint 和状态，不保存 client secret 或 token。 同一 registration id 切换 issuer 时进入粘性的 AUTHORITY_MISMATCH，不展示登录方式， 也不接受回调；恢复旧 Authority 后仍需显式恢复操作。

3.1 统一 Session 建立约束

所有 Web 登录入口都必须通过统一的 PlatformSessionService 建立登录态，包括：

• 本地用户名密码登录
• OAuth 登录成功回调
• POST /api/v1/auth/direct/login
• POST /api/v1/auth/session/bootstrap
• 本地开发态 MockAuthFilter

统一约束如下：

• 统一写入 platformPrincipal
• 统一写入 SPRING_SECURITY_CONTEXT
• 统一通过 HttpSession 持久化，确保 Spring Session Redis 能无差别接管
• 交互式登录默认调用 changeSessionId()，降低 session fixation 风险
• 已由 Spring Security 完成认证的入口可以复用现有 Authentication，避免重复构造认证结果

这意味着未来私有版新增企业 SSO provider 时，只能扩展认证来源本身，不能绕开统一的 session 建立服务直接操作 Session。

3.3 Session Bootstrap 扩展点

为了兼容未来私有部署中的企业 SSO 被动登录，开源版预留显式会话引导协议：

• 接口：POST /api/v1/auth/session/bootstrap
• 用途：前端在同域场景下显式触发一次“读取外部会话并尝试换取 skillhub Session”的流程
• 默认状态：关闭，开源版不提供任何 PassiveSessionAuthenticator 实现
• 安全边界：默认不做全局自动登录 filter，避免匿名访问时隐式建会话、放大 CSRF 和审计复杂度

扩展接口如下：

public interface PassiveSessionAuthenticator {
    String providerCode();
    Optional<PlatformPrincipal> authenticate(HttpServletRequest request);
}

约束如下：

• authenticate() 只负责验证外部被动会话并返回平台登录所需主体
• 是否允许启用该入口由 skillhub.auth.session-bootstrap.enabled 控制，默认 false
• 未启用时接口返回 403
• 启用但 provider 不受支持时返回 400
• 启用但请求中不存在有效外部会话时返回 401
• 成功时建立标准 Spring Security Session，并返回与 /api/v1/auth/me 一致的用户结构

3.4 Direct Authentication 扩展点

为兼容未来“前端收集用户名密码，后端调用企业 SSO / RPC 校验”的私有部署模式，开源版增加默认关闭的直连认证抽象：

public interface DirectAuthProvider {
    String providerCode();
    PlatformPrincipal authenticate(DirectAuthRequest request);
}

对应公共协议：

• POST /api/v1/auth/direct/login

约束如下：

• 开源版默认关闭，由 skillhub.auth.direct.enabled 控制
• 关闭时返回 403
• provider 不受支持时返回 400
• provider 认证失败时沿用 provider 自身的认证异常语义
• 成功时建立标准 Session，并返回与 /api/v1/auth/me 一致的用户结构
• 现有 /api/v1/auth/local/login 保持不变，兼容层只是新增可选入口

3.5 Spring Security 配置要点

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Login(oauth2 -> oauth2
                .userInfoEndpoint(info -> info
                    .userService(customOAuth2UserService))
                .successHandler(oAuth2SuccessHandler)
                .failureHandler(oAuth2FailureHandler)
            )
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED))
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .ignoringRequestMatchers("/api/v1/**"))
            // ...
        ;
    }
}

3.6 Provider 配置、启动协调和扩展边界

当前静态 descriptor source 只接受已配置且可唯一解析的 GitHub、GitLab 和标准 OIDC：

# application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: ${OAUTH2_GITHUB_CLIENT_ID}
            client-secret: ${OAUTH2_GITHUB_CLIENT_SECRET}
            scope: read:user,user:email
          # 二期扩展示例:
          # gitlab:
          #   client-id: ...
          #   authorization-grant-type: authorization_code
          # google:
          #   client-id: ...

应用启动时固定执行以下顺序：

1. 从唯一的受信 descriptor source 读取已启用配置。
2. 对每个 Provider 在 PostgreSQL 中执行 Authority compare-and-set pin。
3. 再次读取持久化状态。
4. 登录目录每次读取时再次以持久化状态过滤；只有状态为 READY 且 fingerprint 与 当前 descriptor 一致的 Provider 才进入 /api/v1/auth/providers 和 /api/v1/auth/methods。

配置缺失、placeholder、未知/歧义协议、Authority 无法唯一确定、未 pin 或 mismatch 都 fail closed。授权入口和 callback 在 Spring Security 发起上游重定向、Token 交换或 userinfo 请求前执行相同的持久化 readiness 检查；登录目录不会直接读取 OAuth2ClientProperties，其他 Pod 写入的 mismatch 也不会被旧的内存投影继续展示。

运维把全部 Pod 恢复为已 pin 的相同 Authority 后，由 SUPER_ADMIN 调用：

POST /api/v1/admin/identity-providers/{providerCode}/authority/recover

该操作不接受新 Authority 或 fingerprint，只能在数据库仍为 AUTHORITY_MISMATCH 且当前 受信 descriptor 的 fingerprint 等于已 pin 值时 compare-and-set 回 READY。成功变更 写入同一事务的 PROVIDER_AUTHORITY_RECOVERED 审计；重复调用返回 recovered=false, state=READY，不会伪造第二条恢复审计。配置仍指向新 Authority 时返回 冲突，必须等待后续独立的 Authority 迁移设计，不能用此接口改写 pin。

新增协议不能只添加 Spring registration 或在 OAuth user service 中加分支。必须按照 统一身份联邦设计 实现受信 descriptor、 协议 Adapter 和 conformance 测试；LDAP、DingTalk、CAS、SAML、SCIM 及动态 Provider Registry 不属于当前阶段。

4. 核心接口设计

public interface ExternalIdentityLoginService {
    IdentityLoginOutcome authenticate(
        ResolvedProviderHandle provider,
        ProviderAuthenticationResult result,
        IdentityLoginContext context
    );
}

ResolvedProviderHandle 只能由服务端 ClientRegistration 路由解析产生。 ProviderAuthenticationResult 不含 Provider code、Authority、平台 userId、角色、 Principal、Session、token、ticket、Cookie 或原始响应。核心内部按固定顺序执行：

Trusted descriptor
  → Authority Lock
  → IdentityAssertionFactory
  → Binding / Subject resolution
  → AccountLoginGuard
  → AccessPolicy
  → ProvisioningPolicy / email collision
  → ProfileSyncPolicy
  → PlatformPrincipalFactory
  → IdentityLoginOutcome

只有 IdentityLoginOutcome.Authenticated 可以到达既有 PlatformSessionService。当前 PlatformPrincipal 结构保持不变；Binding V2 和 profile source 使用 additive migration 及兼容列支持升级和回滚。

4.1 多 Provider 账号合并策略

同一个员工通过不同 OAuth Provider 登录时，可能产生多个 user_account。

当前策略：不自动合并，旧的手动合并流程也已临时隔离。旧流程把次账号 verification token 直接返回给主账号会话，不能分别证明两个账号的控制权，因此不能继续作为管理员或 用户合并入口。

• 当前阶段：不自动合并，每个 Provider 登录独立创建用户
• 多 Provider 上线时，再引入显式 Identity Link 和安全 Account Merge
• email、username、display name 或主账号会话拿到的 token 均不能证明次账号所有权
• 安全 Account Merge 必须要求主、次账号分别完成 fresh reauthentication
• 在安全流程上线前，/api/v1/account/merge/initiate、verify、confirm 对已认证请求 统一返回 503 Service Unavailable

合并操作规则：

• 合并操作写入审计日志
• 合并后原 user_account 标记为 MERGED，保留记录不物理删除
• 不提供按 email 自动合并；即使 Provider 声明 email 已验证，也不能替代对两个账号控制权 的分别证明。未来绑定/合并必须使用显式、可审计的重新认证流程。
• 旧 account_merge_request 记录保留用于审计和未来迁移，但不得通过 SQL 手工改为 VERIFIED/COMPLETED，也不得手工迁移身份、角色、membership、凭据或 Token
• 回滚到仍包含旧合并实现的镜像会重新暴露该安全问题；如必须回滚，应先在网关阻断 /api/v1/account/merge/*

未来安全流程的完整验收条件见 22-secure-account-merge-acceptance-design.md。

5. CLI 认证（OAuth Device Flow + 平台凭证）

CLI 主认证基线调整为 OAuth Device Flow。用户在 CLI 中发起授权，浏览器侧完成登录与确认，CLI 轮询后获取平台签发的凭证并访问 CLI API。

• 发起：CLI 请求 device code，展示 user_code 与验证地址
• 授权：用户在浏览器完成 GitHub OAuth 登录并确认绑定
• 轮询：CLI 使用 device_code 轮询授权结果
• 完成：服务端签发 CLI 可用凭证，CLI 持 Authorization: Bearer <token> 调用后续接口

API Token 仍保留，但定位从“CLI 唯一认证方式”调整为“平台通用凭证能力”：

• 用途：自动化脚本、兼容层调用、手工 Token 管理、后续系统集成
• 存储：只存 SHA-256 哈希，明文只展示一次
• 校验：从 Authorization: Bearer <token> 提取 → 哈希比对 → 加载关联用户 → 检查用户状态
• 失败闭合与身份优先级：共享认证过滤器只识别 Bearer scheme。有效 Bearer 覆盖已加载的 Web Session 身份；Bearer 为空、格式错误、未知、过期、已吊销、用户缺失或用户禁用时立即返回 401，即使存在有效 Session 也不得回退。缺少 Authorization 头或使用 Basic/其他非 Bearer scheme 时保留有效 Session；若无 Session，公共读接口按匿名访问，whoami 返回 401
• 作用域：skill:read, skill:publish, skill:delete, token:manage
• 拒绝原因：API Token 缺少作用域或不能访问某个接口时，403 响应返回本地化的安全原因和 requestId；其他授权失败仍返回通用信息，避免暴露内部异常

一期作用域说明（非最小权限）：一期 Token 作用域为粗粒度动作级别，不与 namespace 绑定。Token 继承用户的全部权限——如果用户是某个 namespace 的 MEMBER，则该用户的任何 Token（只要包含 skill:publish scope）都可以向该 namespace 发布技能。这是有意的一期简化，不满足最小权限原则。后续版本计划引入 namespace 级别的 Token 作用域限定（如 namespace:ai-team:skill:publish），或通过 api_token_scope 子表实现 Token 与 namespace 的绑定。

6. RBAC 授权判定

权限判定 = 平台角色权限（role → permission 查询） ∪ 命名空间角色（namespace_member.role）

一期即上线完整 RBAC，平台角色按最小权限拆分：

平台角色	职责
SUPER_ADMIN	全部权限，硬判定短路
SKILL_ADMIN	全局空间审核、提升审核、隐藏/恢复技能、撤回已发布版本
USER_ADMIN	准入审批、封禁/解封、角色分配（不可分配 SUPER_ADMIN）
AUDITOR	审计日志只读

• 命名空间权限仍由 namespace_member.role（OWNER / ADMIN / MEMBER）决定
• 一个用户可持有多个平台角色
• 普通用户无平台角色，仅通过 namespace 成员关系获得操作权限

判定逻辑：

1. 从 SecurityContext 获取当前用户
2. 检查用户状态（DISABLED → 拒绝所有操作）
3. 查询用户的平台角色（user_role_binding → role → role_permission）
4. SUPER_ADMIN 短路：直接通过所有权限检查
5. 如果涉及命名空间资源，查询用户在该命名空间的角色（namespace_member.role）
6. 检查命名空间状态（FROZEN → 拒绝写操作）
7. 合并平台权限 + 命名空间角色，判定是否满足

操作	所需权限	判定逻辑
发布技能包	skill:publish	普通用户要求是目标 namespace 成员；SUPER_ADMIN 可绕过成员校验并直发
提交已有版本进入审核	review:submit	owner 本人，或 namespace ADMIN / OWNER，或 SKILL_ADMIN / SUPER_ADMIN
管理技能（归档/版本管理）	skill:manage	namespace ADMIN 以上，或 owner 本人
提升到全局	skill:promote	namespace ADMIN 以上，或 owner 本人
审核技能发布	review:approve	namespace ADMIN / OWNER，或 SKILL_ADMIN / SUPER_ADMIN；提交人本人仅 SUPER_ADMIN 可审核自己的 review task
审核提升申请	promotion:approve	持有 SKILL_ADMIN / SUPER_ADMIN
隐藏/恢复技能	skill:manage	仅 SUPER_ADMIN
撤回已发布版本（YANK）	skill:manage	SKILL_ADMIN / SUPER_ADMIN
管理用户角色	user:manage	持有 USER_ADMIN / SUPER_ADMIN
审批用户准入	user:approve	持有 USER_ADMIN / SUPER_ADMIN
查看审计日志	audit:read	持有 AUDITOR / SUPER_ADMIN

权限主轴说明：

• namespace role 是权限主轴，namespace ADMIN 对空间内所有 skill 有完整管理权，不受 owner 限制
• owner_id 语义为"主要维护人"，owner 作为 MEMBER 时仅可管理自己创建的 skill
• 企业场景人员流动频繁，owner 离职后 namespace ADMIN 仍能完整管理所有技能

6.1 审核与提升 API 路径适用范围

API 路径	适用范围	权限要求
POST /api/v1/reviews/{id}/approve	技能发布审核	namespace ADMIN / OWNER，或 SKILL_ADMIN / SUPER_ADMIN
POST /api/v1/promotions/{id}/approve	提升到全局审核	SKILL_ADMIN / SUPER_ADMIN
GET /api/v1/admin/audit-logs	审计日志查询	AUDITOR / SUPER_ADMIN
PUT /api/v1/admin/users/{id}/roles	用户角色管理	USER_ADMIN / SUPER_ADMIN
POST /api/v1/admin/users/{id}/approve	用户准入审批	USER_ADMIN / SUPER_ADMIN

当前实现中，审核与提升都走统一 portal API；是否允许操作由服务层根据 namespace role 与 platform role 联合判定，而不是靠分叉路由表达。

7. Session 设计

• 存储：Spring Session + Redis（必须，多 Pod 环境刚需）
• 序列化：JSON
• 过期：默认 8 小时，Redis TTL 自动清理

7.1 Session 内容

Session 中存储以下字段：

• userId：平台用户 ID
• displayName：展示名
• oauthProvider：登录使用的 OAuth Provider
• currentNamespaceId：当前选中的命名空间（可选）
• platformRoles：平台角色列表（如 ["SKILL_ADMIN", "AUDITOR"]），登录时从 user_role_binding → role 查询写入
• roleVersion：角色版本号，用于缓存一致性

7.2 角色缓存一致性机制

平台角色变更需要即时生效（如撤销审核权限），不能等 Session 过期：

1. 每次请求时从 Session 读取 roleVersion
2. 与 Redis 中的 user:{userId}:roleVersion 比对
3. 版本一致 → 直接使用 Session 中的 platformRoles
4. 版本不一致 → 从数据库重新加载角色，更新 Session

管理员修改用户角色时，递增 Redis 中该用户的 roleVersion。

8. CSRF 防护

采用 Cookie-to-Header 模式：

• 后端设置 XSRF-TOKEN Cookie（HttpOnly=false）
• 前端从 Cookie 读取 Token，放入请求 Header X-XSRF-TOKEN
• 后端校验 Header 与 Cookie 是否一致
• CLI API（/api/v1/**）与兼容层（/api/v1/**）豁免 CSRF（使用 Bearer Token，无 Cookie）

9. 前端权限控制

9.1 /api/v1/auth/me 响应结构

{
  "code": 0,
  "msg": "获取成功",
  "data": {
    "userId": "usr_42",
    "displayName": "zhangsan",
    "email": "zhangsan@company.com",
    "avatarUrl": "https://...",
    "oauthProvider": "local",
    "canChangePassword": true,
    "platformRoles": ["SKILL_ADMIN", "AUDITOR"]
  },
  "timestamp": "2026-03-12T06:00:00Z",
  "requestId": "req-123"
}

前端平台级权限判定基于 platformRoles；是否展示修改密码入口和表单基于后端返回的 canChangePassword。后端通过 role_permission 表查询权限码。

统一约束：

• /api/v1/auth/me、/api/v1/auth/providers 等 JSON 响应必须统一使用 code/msg/data/timestamp/requestId 外层结构。
• /api/v1/auth/session/bootstrap 也必须遵守同一统一响应结构。
• msg 必须走 Spring Boot 标准 MessageSource i18n 机制。
• locale 必须通过请求上下文自动获取，不在 controller 中显式传递。
• 认证失败返回 401，但 JSON 外层结构仍保持一致，例如 {"code":401,"msg":"需要先登录","data":null,...}。

9.2 usePermission() Hook

function usePermission() {
  const { data: me } = useQuery({ queryKey: ['auth', 'me'], queryFn: fetchMe })

  const hasRole = (role: string) => me?.platformRoles.includes(role) ?? false
  const isSuperAdmin = () => hasRole('SUPER_ADMIN')
  const isSkillAdmin = () => hasRole('SKILL_ADMIN') || isSuperAdmin()
  const isUserAdmin = () => hasRole('USER_ADMIN') || isSuperAdmin()
  const isAuditor = () => hasRole('AUDITOR') || isSuperAdmin()

  return {
    isLoggedIn: !!me,
    isSuperAdmin,
    isSkillAdmin,
    isUserAdmin,
    isAuditor,

    // 命名空间角色判定
    getNamespaceRole: (slug: string) =>
      me?.namespaces.find(n => n.slug === slug)?.role,
    isNamespaceAdmin: (slug: string) =>
      ['OWNER', 'ADMIN'].includes(me?.namespaces.find(n => n.slug === slug)?.role ?? ''),
    isNamespaceMember: (slug: string) =>
      ['OWNER', 'ADMIN', 'MEMBER'].includes(me?.namespaces.find(n => n.slug === slug)?.role ?? ''),
  }
}

9.3 路由级守卫

在 TanStack Router beforeLoad 中判定：

路由	条件
/dashboard/*	已登录
/dashboard/namespaces/{slug}/reviews	已登录 + 该 namespace 的 ADMIN 以上
/admin/*	已登录 + 持有任一平台角色（SUPER_ADMIN / SKILL_ADMIN / USER_ADMIN / AUDITOR）

不满足条件时：未登录 → 重定向登录；已登录但无权限 → 显示 403 页面。

9.4 操作级控制

场景	判定逻辑	UI 行为
技能详情页"提交发布"按钮	isNamespaceMember(namespace)	非成员不显示
审核列表"通过/拒绝"按钮	团队空间：isNamespaceAdmin(namespace)；全局空间：isSkillAdmin()	无权限不显示
用户管理页	isUserAdmin()	无权限不显示
用户管理页"设为 SUPER_ADMIN"	isSuperAdmin()	仅超管可见
审计日志页	isAuditor()	无权限不显示
技能详情页"归档"按钮	isNamespaceAdmin(namespace) 或当前用户是 owner	否则不显示
命名空间"添加成员"按钮	isNamespaceAdmin(namespace)	非管理员不显示
收藏/评分按钮	isLoggedIn	未登录时点击提示登录

9.5 登录交互

前端登录按钮
    │
    ▼
window.location.href = '/oauth2/authorization/github'
    │
    ▼
(后端 OAuth2 流程，用户无感)
    │
    ▼
回调后重定向到前端 (如 /?login=success)
    │
    ▼
前端检测 URL 参数 → 调用 /api/v1/auth/me → 更新登录态

前端无需引入额外 OAuth 库，登录流程完全由后端 Spring Security 处理。前端只需：

• 调用 /api/v1/auth/providers 获取可用 Provider 列表，动态渲染登录按钮
• 处理登录后的重定向
• 通过 /api/v1/auth/me 检测登录状态

9.6 安全边界原则

• 前端权限控制是 UX 优化，不是安全边界
• 后端每个写操作接口独立校验权限，不信任前端判定
• 前端隐藏按钮 ≠ 安全，用户可以直接调 API，后端必须拦截

10. 权限矩阵（完整）

以下矩阵列出每个 API 接口的权限判定来源，作为后端实现的唯一参考。

10.1 Public API（匿名可访问）

接口	匿名	已登录	判定逻辑
GET /api/v1/skills（搜索）	仅 PUBLIC，且仅搜索 ACTIVE、非 hidden、已索引 skill	PUBLIC + NAMESPACE_ONLY（成员空间）+ PRIVATE（owner/admin）	SearchVisibilityScope + 搜索索引状态
GET /api/v1/skills/{ns}/{slug}	仅已发布且可见的 PUBLIC skill	同左，另加 owner 可读未发布 skill、namespace ADMIN / OWNER 可读 hidden	visibility + latest_version_id + hidden + namespace 成员关系
GET /api/v1/skills/{ns}/{slug}/versions	仅 PUBLISHED 版本	owner / namespace ADMIN / OWNER 可见全部五种状态	同上 + version status 过滤
GET /api/v1/skills/{ns}/{slug}/download	仅 PUBLIC、ACTIVE、非 hidden、命名空间未归档且目标版本可安装的 skill 支持匿名下载	已登录后按 visibility 判定；下载目标版本必须可安装	visibility + namespace status + SkillInstallability
GET /api/v1/skills/{ns}/{slug}/resolve	仅 PUBLIC、ACTIVE、非 hidden、命名空间未归档且目标版本可安装的 skill 可匿名	同上	visibility + namespace status + SkillInstallability
GET /api/v1/namespaces	全部	全部	无限制

10.2 Authenticated API

接口	所需权限	判定来源
POST /api/v1/skills/{ns}/{slug}/star	已登录	Session/Token
POST /api/v1/skills/{ns}/{slug}/rating	已登录	Session/Token
POST /api/v1/reviews	owner 本人，或 namespace ADMIN / OWNER，或 SKILL_ADMIN / SUPER_ADMIN	skill.owner_id / namespace_member.role / platform roles
POST .../versions/{ver}/withdraw-review	提交人本人	review_task.submitted_by
PUT /api/v1/skills/{ns}/{slug}/tags/{tag}	namespace ADMIN 以上 或 owner	namespace_member.role 或 skill.owner_id
POST /api/v1/skills/{ns}/{slug}/archive	namespace ADMIN 以上 或 owner	namespace_member.role 或 skill.owner_id
POST .../versions/{ver}/rerelease	namespace ADMIN 以上 或 owner；源版本必须 PUBLISHED	namespace_member.role 或 skill.owner_id + skill_version.status
DELETE .../versions/{ver}	namespace ADMIN 以上 或 owner（仅 DRAFT / REJECTED）	namespace_member.role 或 skill.owner_id + skill_version.status

10.3 CLI API

接口	凭证规则	授权与错误语义
GET /api/cli/v1/auth/whoami	有效 Web Session 或有效 Bearer Token	无有效身份返回 401；坏 Bearer 即使存在 Session 也返回 401
GET /api/cli/v1/skills/search	Session 可用；无 Session 时可匿名；提供 Bearer 时必须有效	匿名仅返回公开可安装 skill；有效 Bearer 覆盖 Session；坏 Bearer 返回 401，不得降级
GET /api/cli/v1/skills/{namespace}/{slug}/resolve	Session 可用；无 Session 时可匿名读取公开资源；提供 Bearer 时必须有效	有效 Bearer 覆盖 Session；坏 Bearer 返回 401；有效身份无资源权限返回 403
GET /api/cli/v1/skills/{namespace}/{slug}/download	Session 可用；无 Session 时可匿名下载公开资源；提供 Bearer 时必须有效	有效 Bearer 覆盖 Session；坏 Bearer 返回 401；有效身份无资源权限返回 403
GET /api/cli/v1/skills/{namespace}/{slug}/versions/{version}/download	Session 可用；无 Session 时可匿名下载公开资源；提供 Bearer 时必须有效	有效 Bearer 覆盖 Session；坏 Bearer 返回 401；有效身份无资源权限返回 403

Spring Security 先加载 Web Session 身份，共享 API token 过滤器随后只处理 Bearer scheme。有效 Bearer 会覆盖 Session，确保请求使用 token 的用户、角色与 scope；Bearer 为空、格式错误、未知、过期、已撤销、用户缺失或用户禁用时，过滤器清除当前身份并立即返回 401，不能回退到 Session 或匿名身份。完全缺少 Authorization 头或使用 Basic/其他非 Bearer scheme 时，过滤器不改变已有 Session；如果 Session 也不存在，公共读接口按匿名身份执行，而 whoami 返回 401。身份已验证但 token scope 或资源可见性不足时返回 403；服务端不向客户端区分 token 不存在、过期或已撤销。whoami.email 字段始终存在，但没有可用邮箱时值为 null。

10.4 Admin API

接口	所需平台角色	判定来源
POST /api/v1/admin/skills/{id}/hide	SUPER_ADMIN	user_role_binding → role_permission
POST /api/v1/admin/skills/{id}/unhide	SUPER_ADMIN	同上
POST /api/v1/admin/skills/versions/{versionId}/yank	SKILL_ADMIN / SUPER_ADMIN	同上
PUT /api/v1/admin/users/{id}/roles	USER_ADMIN / SUPER_ADMIN	同上，且 USER_ADMIN 不可分配 SUPER_ADMIN
POST /api/v1/admin/users/{id}/approve	USER_ADMIN / SUPER_ADMIN	同上
POST /api/v1/admin/users/{id}/ban	USER_ADMIN / SUPER_ADMIN	同上
GET /api/v1/admin/audit-logs	AUDITOR / SUPER_ADMIN	同上

10.5 Namespace API

接口	所需 namespace 角色	判定来源
POST /api/v1/namespaces/{slug}/members	该空间 ADMIN 以上	namespace_member.role
DELETE /api/v1/namespaces/{slug}/members/{userId}	该空间 ADMIN 以上	namespace_member.role
POST /api/v1/promotions	该空间 ADMIN 以上 或 owner	namespace_member.role 或 skill.owner_id

10.6 Compatibility API（Bearer Token 认证）

接口	所需凭证	额外判定
GET /api/v1/whoami	任意有效 Bearer Token	无
GET /api/v1/search	可选（匿名限 PUBLIC）	SearchVisibilityScope
GET /api/v1/resolve	可选（匿名仅限 PUBLIC、ACTIVE、非 hidden、命名空间未归档且目标版本可安装）	visibility + namespace status + SkillInstallability
GET /api/v1/download/{slug}/{version}	可选（匿名仅限 PUBLIC、ACTIVE、非 hidden、命名空间未归档且目标版本可安装）	visibility + namespace status + SkillInstallability
POST /api/v1/publish	Bearer Token + skill:publish	普通用户要求目标 namespace 成员；SUPER_ADMIN 可绕过（namespace 由 canonical slug 解析）