namespace StellaOps.Cryptography;

/// <summary>
/// Well-known hash purpose identifiers for compliance-aware cryptographic operations.
/// Components should request hashing by PURPOSE, not by algorithm.
/// The platform resolves the correct algorithm based on the active compliance profile.
/// </summary>
public static class HashPurpose
{
    /// <summary>
    /// Graph content-addressing (richgraph-v1).
    /// Default: BLAKE3-256 (world), SHA-256 (fips), GOST3411-2012-256 (gost), SM3 (sm).
    /// </summary>
    public const string Graph = "graph";

    /// <summary>
    /// Symbol identification (SymbolID, CodeID).
    /// Default: SHA-256 (world/fips/kcmvp/eidas), GOST3411-2012-256 (gost), SM3 (sm).
    /// </summary>
    public const string Symbol = "symbol";

    /// <summary>
    /// Content/file hashing for integrity verification.
    /// Default: SHA-256 (world/fips/kcmvp/eidas), GOST3411-2012-256 (gost), SM3 (sm).
    /// </summary>
    public const string Content = "content";

    /// <summary>
    /// Merkle tree node hashing.
    /// Default: SHA-256 (world/fips/kcmvp/eidas), GOST3411-2012-256 (gost), SM3 (sm).
    /// </summary>
    public const string Merkle = "merkle";

    /// <summary>
    /// DSSE payload digest for attestations.
    /// Default: SHA-256 (world/fips/kcmvp/eidas), GOST3411-2012-256 (gost), SM3 (sm).
    /// </summary>
    public const string Attestation = "attestation";

    /// <summary>
    /// External interoperability (third-party tools like cosign, rekor).
    /// Always SHA-256, regardless of compliance profile.
    /// Every use of this purpose MUST be documented with justification.
    /// </summary>
    public const string Interop = "interop";

    /// <summary>
    /// Password/secret derivation.
    /// Default: Argon2id (world/gost/sm/kcmvp/eidas), PBKDF2-SHA256 (fips).
    /// </summary>
    public const string Secret = "secret";

    /// <summary>
    /// All known hash purposes for validation.
    /// </summary>
    public static readonly IReadOnlyList<string> All = new[]
    {
        Graph,
        Symbol,
        Content,
        Merkle,
        Attestation,
        Interop,
        Secret
    };

    /// <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);
}