request-auth Specification

Purpose

TBD - created by archiving change add-request-auth-replay-guard. Update Purpose after archive.

Requirements

Requirement: HMAC 签名校验

mjava 基座 SHALL 提供可配置的 HMAC-SHA256 请求签名校验机制。当 mjava.auth.enabled=true 时，所有非豁免请求 MUST 通过签名校验才能进入业务 Controller。

Scenario: 合法签名请求通过

WHEN 请求携带完整四个 Header（X-MJ-Key / X-MJ-Timestamp / X-MJ-Nonce / X-MJ-Signature）
AND 签名 = HMAC-SHA256(secret, timestamp + "\n" + nonce + "\n" + method + "\n" + path + "\n" + bodyHash)
THEN 请求被放行到 Controller
AND MDC 写入 authKey 字段供日志追溯

Scenario: 签名不匹配

WHEN 计算出的签名与 Header 中 X-MJ-Signature 不一致
THEN 返回 403 { code: "AUTH_SIGNATURE_INVALID" }
AND 响应 message 不包含期望签名值（避免泄露线索）
AND 审计日志记录 authKey + path + latencyMs

Scenario: Header 缺失

WHEN 四个必备 Header 中任一缺失
THEN 返回 401 { code: "AUTH_HEADER_MISSING" }
AND 响应不说明具体缺失哪个

Requirement: 豁免机制

本能力 SHALL 支持三级豁免策略，优先级从上到下：全局开关 > 路径豁免 > 注解豁免。

Scenario: 全局关闭

WHEN mjava.auth.enabled=false
THEN 所有请求跳过鉴权，行为等同于 enable 前的裸奔状态

Scenario: 路径豁免

WHEN 请求路径匹配 mjava.auth.exempt-paths 列表中任一 Ant 风格模式
THEN 跳过签名校验
AND 典型清单：/actuator/**（健康检查）、/api/*/callback/**（第三方 webhook）

Scenario: 注解豁免

WHEN 目标 Controller 方法或其类带 @NoAuth 注解
THEN 签名校验跳过
AND 注解识别发生在 HandlerInterceptor.preHandle（能访问到 HandlerMethod）

Requirement: 密钥配置

secret MUST 通过环境变量注入，禁止硬编码。enabled=true 但 secret 为空时 MUST 拒绝启动或拒绝请求。

Scenario: secret 未配置

WHEN mjava.auth.enabled=true 但 mjava.auth.secret 为空或未设置
THEN 启动时打 ERROR 日志
AND 所有受保护请求返回 503 { code: "AUTH_CONFIG_MISSING" }

Scenario: secret 从环境变量读取

WHEN application.yml 中 secret: ${AUTH_SECRET}
AND 部署环境设置 AUTH_SECRET 变量
THEN 启动时成功加载，后续请求按此密钥校验