namespace StellaOps.Audit.ReplayToken;

/// <summary>
/// Result of token verification including expiration check.
/// </summary>
public enum ReplayTokenVerificationResult
{
    /// <summary>Token is valid and not expired.</summary>
    Valid = 0,

    /// <summary>Token hash does not match the inputs (tampered or different inputs).</summary>
    Invalid = 1,

    /// <summary>Token has expired.</summary>
    Expired = 2
}

/// <summary>
/// Generates deterministic replay tokens for audit and reproducibility.
/// </summary>
public interface IReplayTokenGenerator
{
    /// <summary>
    /// Generates a replay token from the given inputs without expiration (v1.0).
    /// </summary>
    /// <param name="request">The inputs to hash.</param>
    /// <returns>A deterministic replay token.</returns>
    ReplayToken Generate(ReplayTokenRequest request);

    /// <summary>
    /// Generates a replay token from the given inputs with expiration (v2.0).
    /// </summary>
    /// <param name="request">The inputs to hash.</param>
    /// <param name="expiration">How long the token is valid. If null, uses ReplayToken.DefaultExpiration.</param>
    /// <returns>A deterministic replay token with expiration.</returns>
    ReplayToken GenerateWithExpiration(ReplayTokenRequest request, TimeSpan? expiration = null);

    /// <summary>
    /// Verifies that inputs match a previously generated token (does not check expiration).
    /// </summary>
    bool Verify(ReplayToken token, ReplayTokenRequest request);

    /// <summary>
    /// Verifies that inputs match a previously generated token and checks expiration.
    /// </summary>
    /// <param name="token">The token to verify.</param>
    /// <param name="request">The inputs to verify against.</param>
    /// <returns>The verification result including expiration check.</returns>
    ReplayTokenVerificationResult VerifyWithExpiration(ReplayToken token, ReplayTokenRequest request);
}