namespace StellaOps.Cryptography;

/// <summary>
/// Well-known HMAC purpose identifiers for compliance-aware cryptographic operations.
/// Components should request HMAC by PURPOSE, not by algorithm.
/// The platform resolves the correct algorithm based on the active compliance profile.
/// </summary>
public static class HmacPurpose
{
    /// <summary>
    /// DSSE envelope signing and message authentication codes.
    /// Default: HMAC-SHA256 (world/fips/kcmvp/eidas), HMAC-GOST3411 (gost), HMAC-SM3 (sm).
    /// </summary>
    public const string Signing = "signing";

    /// <summary>
    /// Token and URL authentication (e.g., signed URLs, ack tokens).
    /// Default: HMAC-SHA256 (world/fips/kcmvp/eidas), HMAC-GOST3411 (gost), HMAC-SM3 (sm).
    /// </summary>
    public const string Authentication = "auth";

    /// <summary>
    /// External webhook interoperability (third-party webhook receivers).
    /// Always HMAC-SHA256, regardless of compliance profile.
    /// Every use of this purpose MUST be documented with justification.
    /// </summary>
    public const string WebhookInterop = "webhook";

    /// <summary>
    /// All known HMAC purposes for validation.
    /// </summary>
    public static readonly IReadOnlyList<string> All = new[]
    {
        Signing,
        Authentication,
        WebhookInterop
    };

    /// <summary>
    /// Validates whether the given purpose is known.
    /// </summary>
    /// <param name="purpose">The purpose to validate.</param>
    /// <returns>True if the purpose is known; otherwise, false.</returns>
    public static bool IsKnown(string? purpose)
        => !string.IsNullOrWhiteSpace(purpose) && All.Contains(purpose);
}