baiyue-firstleg/common-security/AGENTS.md

Common Security 模块指引

职责边界

• 提供业务服务通用的 JWT 解码、认证过滤、Redis Access Token 会话校验、认证用户上下文及 401/403 JSON 响应。
• 角色、权限、租户成员关系由 iam/ 维护；本模块不实现 RBAC 管理业务。网关的 Reactive 安全链位于 gateway/。

快速索引

功能	入口
自动配置	src/main/java/com/baiyue/common/security/BaiyueSecurityAutoConfiguration.java、HmacJwtDecoderAutoConfiguration.java
JWT 过滤与声明映射	JwtAuthenticationFilter.java、JwtClaimsMapper.java
当前用户与认证对象	AuthenticatedUser.java、BaiyueJwtAuthenticationToken.java
Redis 会话校验	AccessTokenSessionValidator.java、RedisAccessTokenSessionValidator.java、RedisTokenKeys.java
401/403 响应	JsonAuthenticationEntryPoint.java、JsonAccessDeniedHandler.java
自动配置注册	src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
安全回归测试	src/test/java/com/baiyue/common/security/

修改与验证

• Token Claim、Redis Key 或认证对象变化必须同步检查 auth/、gateway/ 和所有业务服务。
• JsonAuthenticationEntryPoint 与 JsonAccessDeniedHandler 属于统一 HTTP 200 业务契约的例外：认证入口仍返回真实 401/403，供前端刷新 Token 和区分授权失败。
• 不降低服务端租户、会话或权限校验；密钥只从配置中心或环境变量读取。
• 从父目录运行 mvn -pl common-security -am test。