package cn.novalon.manage.gateway.service;

import org.springframework.http.server.reactive.ServerHttpRequest;

/**
 * 请求签名服务接口
 * 
 * 文件定义：提供API请求签名生成和验证功能
 * 涉及业务：API安全防护，防止请求篡改和重放攻击
 * 算法：HMAC-SHA256签名算法
 * 
 * @author 张翔
 * @date 2026-03-26
 */
public interface SignatureService {

    /**
     * 生成请求签名
     * 
     * @param method HTTP方法
     * @param path 请求路径
     * @param query 查询参数
     * @param body 请求体
     * @param timestamp 时间戳
     * @param nonce 随机数
     * @param secret 密钥
     * @return 签名字符串
     */
    String generateSignature(
            String method, 
            String path, 
            String query, 
            String body, 
            long timestamp, 
            String nonce, 
            String secret);

    /**
     * 验证请求签名
     * 
     * @param request HTTP请求
     * @param secret 密钥
     * @return 验证结果
     */
    boolean verifySignature(ServerHttpRequest request, String secret);

    /**
     * 检查时间戳是否有效
     * 
     * @param timestamp 时间戳（毫秒）
     * @param maxAgeMinutes 最大有效期（分钟）
     * @return 是否有效
     */
    boolean isTimestampValid(long timestamp, int maxAgeMinutes);

    /**
     * 检查nonce是否已使用（防重放攻击）
     * 
     * @param nonce 随机数
     * @return 是否已使用
     */
    boolean isNonceUsed(String nonce);

    /**
     * 记录nonce为已使用
     * 
     * @param nonce 随机数
     */
    void recordNonce(String nonce);

    /**
     * 清理过期的nonce记录
     */
    void cleanupExpiredNonces();
}
