replay-guard Specification

Purpose

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

Requirements

Requirement: 时间窗校验

mjava 基座 SHALL 拒绝时间戳超出配置窗口的请求，以限制重放攻击的有效窗口。

Scenario: 时间戳在窗口内

WHEN X-MJ-Timestamp 与服务端当前时间差 ≤ mjava.auth.window（默认 300 秒）
THEN 进入后续 Nonce 与签名校验

Scenario: 时间戳超窗

WHEN 时间差 > window（无论提前还是滞后）
THEN 返回 401 { code: "AUTH_TIMESTAMP_OUT_OF_WINDOW" }
AND 审计日志记录 clientTimestamp 与 serverTimestamp 供排查

Requirement: Nonce 去重

mjava 基座 SHALL 通过 Nonce 缓存实现在时间窗内的一次性请求保证。同一 Nonce 在窗口期内只允许通过一次。

Scenario: 首次 Nonce 被接受

WHEN 请求携带之前未见过的 X-MJ-Nonce
THEN NonceCache.putIfAbsent(nonce) 成功
AND 请求进入签名校验

Scenario: Nonce 被重放

WHEN 请求携带之前已见过的 Nonce（仍在 TTL 内）
THEN NonceCache.putIfAbsent 返回 false
AND 返回 401 { code: "AUTH_NONCE_REPLAYED" }

Scenario: Nonce 缓存容量上限

WHEN NonceCache 达到 mjava.auth.nonce-cache-size 上限
THEN 按 LRU 策略淘汰最旧条目
AND 淘汰不影响未淘汰 Nonce 的判定正确性

Requirement: Nonce 缓存 TTL 设置

NonceCache 的 TTL MUST 略长于 mjava.auth.window，以避免边界时间戳被错误接受。

Scenario: TTL 等于窗口 + 30s

WHEN NonceCache 初始化
THEN TTL = mjava.auth.window + 30 秒
AND 例：window=300 → TTL=330

Requirement: 单实例内存限制声明

Phase 1 的 Nonce 去重 SHALL 在单 JVM 实例内生效；多实例部署时同一 Nonce 可能被两个实例各接受一次。这是已知限制，不在本 change 范围。

Scenario: 多实例部署告警

WHEN 生产部署判定需要多实例横向扩展
THEN 运维必须评估是否升级为分布式 Nonce（Redis），独立走新 change 提案
AND 本 change 的 NonceCache 配置 nonce-cache-size 建议单实例足够承载高峰 QPS × window 秒的组合