mjava-ai/openspec/changes/add-request-auth-replay-guard/tasks.md

1. 签名工具与 Nonce 缓存

• 1.1 新建 mjava/src/main/java/com/malk/utils/UtilSignature.java：HMAC-SHA256 静态方法 sign(secret, method, path, body, timestamp, nonce) → hex
• 1.2 新建 mjava/src/main/java/com/malk/core/NonceCache.java：封装 UtilToken.TimedCache，API 为 putIfAbsent(nonce) → boolean
• 1.3 单元测试：UtilSignatureTest 覆盖不同 method / 空 body / 中文 path
• 1.4 单元测试：NonceCacheTest 覆盖 TTL 过期 / LRU 淘汰 / 并发

2. 配置与注解

• 2.1 新建 com.malk.config.AuthConfigProperties（@ConfigurationProperties(prefix = "mjava.auth")）
• 2.2 新建 com.malk.config.AuthConfig（@Configuration，根据 enabled 与 secret 条件装配）
• 2.3 新建注解 com.malk.filter.NoAuth（@Target({METHOD, TYPE}) @Retention(RUNTIME)）
• 2.4 application.yml 补默认值 mjava.auth.enabled: false
• 2.5 各子模块 application-*.yml.example 示例 mjava.auth.* 占位

3. Filter + Interceptor 两层

• 3.1 新建 com.malk.filter.AuthFilter：Header 齐全 + 时间戳窗 + Nonce 去重；失败抛 McException 或直接写 McR.fail() 响应
• 3.2 注册 AuthFilter 到 WebConfiguration，顺序在 TraceIdFilter 之后、业务之前
• 3.3 新建 com.malk.filter.AuthInterceptor：preHandle 中签名校验 + @NoAuth 识别
• 3.4 注册 AuthInterceptor 到 WebMvcConfigurer，排除 exempt-paths
• 3.5 错误响应统一 McR 格式（见 design.md 错误码表）

4. 审计日志集成

• 4.1 AuthFilter / AuthInterceptor 失败路径打 WARN 日志，字段：authKey / failReason / clientIp / path / timestamp
• 4.2 成功路径向 MDC 写 authKey，TraceIdFilter 已有链路串联
• 4.3 logback-spring.xml pattern 追加 [%X{authKey:-}]

5. 参考客户端实现（文档侧）

• 5.1 Java 客户端签名示例（工具类形式，便于其他 Java 系统 copy）
• 5.2 Python 客户端签名示例（requests + hmac）
• 5.3 Node.js 客户端签名示例（node:crypto）
• 5.4 curl + openssl 命令行示例（方便临时调试）

6. 回归测试

• 6.1 AuthFilterTest：enabled/disabled 切换、Header 缺失、时间窗边界、Nonce 重放
• 6.2 AuthInterceptorTest：@NoAuth 方法级/类级、签名校验、exempt-paths
• 6.3 集成测试：mjava-mcli 开启后用签名客户端调一次 → 成功；改签名 → 403；改时间戳 → 401
• 6.4 mcli/shunfeng/guangming 保持 enabled: false 场景回归（零破坏验证）

7. 文档

• 7.1 /Users/malk/Desktop/Tech/claude/后端/mjava-baseline.md 新增 §13（或合并到 §6）"请求鉴权与防重放"章节，含签名协议与开关
• 7.2 README.md（本 change 完成后）：客户端签名接入指引
• 7.3 BACKLOG.md 更新专项状态

8. 验证

• 8.1 openspec validate add-request-auth-replay-guard --strict 通过
• 8.2 开启 enabled 后用 curl + openssl 跑通一次真实请求
• 8.3 Nonce 重放测试：同签名连发两次 → 第二次 401

9. 交付

• 9.1 PR 附签名协议示意图
• 9.2 走 /opsx:archive