git.stella-ops.org/src/__Libraries/StellaOps.Cryptography/CryptoProvider.cs

using System.Collections.Generic;

namespace StellaOps.Cryptography;

/// <summary>
/// High-level cryptographic capabilities supported by StellaOps providers.
/// </summary>
public enum CryptoCapability
{
    PasswordHashing,
    Signing,
    Verification,
    SymmetricEncryption,
    KeyDerivation,
    ContentHashing
}

/// <summary>
/// Identifies a stored key or certificate handle.
/// </summary>
public sealed record CryptoKeyReference(string KeyId, string? ProviderHint = null);

/// <summary>
/// Contract implemented by crypto providers (BCL, CryptoPro, OpenSSL, etc.).
/// </summary>
public interface ICryptoProvider
{
    string Name { get; }

    bool Supports(CryptoCapability capability, string algorithmId);

    IPasswordHasher GetPasswordHasher(string algorithmId);

    /// <summary>
    /// Retrieves a content hasher for the supplied algorithm.
    /// </summary>
    /// <param name="algorithmId">Hash algorithm identifier (e.g., SHA-256, GOST-R-34.11-2012-256).</param>
    /// <returns>Hasher instance.</returns>
    ICryptoHasher GetHasher(string algorithmId);

    /// <summary>
    /// Retrieves a signer for the supplied algorithm and key reference.
    /// </summary>
    /// <param name="algorithmId">Signing algorithm identifier (e.g., ES256).</param>
    /// <param name="keyReference">Key reference.</param>
    /// <returns>Signer instance.</returns>
    ICryptoSigner GetSigner(string algorithmId, CryptoKeyReference keyReference);

    /// <summary>
    /// Creates an ephemeral verifier from raw public key bytes (verification-only, no key persistence).
    /// Used for scenarios like DSSE verification where public keys are provided inline.
    /// </summary>
    /// <param name="algorithmId">Signing algorithm identifier (e.g., RS256, ES256).</param>
    /// <param name="publicKeyBytes">Public key in SubjectPublicKeyInfo format (DER-encoded).</param>
    /// <returns>Ephemeral signer instance (supports VerifyAsync only).</returns>
    ICryptoSigner CreateEphemeralVerifier(string algorithmId, ReadOnlySpan<byte> publicKeyBytes)
        => throw new NotSupportedException($"Provider '{Name}' does not support ephemeral verification.");

    /// <summary>
    /// Adds or replaces signing key material managed by this provider.
    /// </summary>
    /// <param name="signingKey">Key material descriptor.</param>
    void UpsertSigningKey(CryptoSigningKey signingKey);

    /// <summary>
    /// Removes signing key material by key identifier.
    /// </summary>
    /// <param name="keyId">Identifier to remove.</param>
    /// <returns><c>true</c> if the key was removed.</returns>
    bool RemoveSigningKey(string keyId);

    /// <summary>
    /// Lists signing key descriptors managed by this provider.
    /// </summary>
    IReadOnlyCollection<CryptoSigningKey> GetSigningKeys();
}

/// <summary>
/// Registry managing provider discovery and policy selection.
/// </summary>
public interface ICryptoProviderRegistry
{
    IReadOnlyCollection<ICryptoProvider> Providers { get; }

    bool TryResolve(string preferredProvider, out ICryptoProvider provider);

    ICryptoProvider ResolveOrThrow(CryptoCapability capability, string algorithmId);

    /// <summary>
    /// Resolves a signer for the supplied algorithm and key reference using registry policy.
    /// </summary>
    /// <param name="capability">Capability required (typically <see cref="CryptoCapability.Signing"/>).</param>
    /// <param name="algorithmId">Algorithm identifier.</param>
    /// <param name="keyReference">Key reference.</param>
    /// <param name="preferredProvider">Optional provider hint.</param>
    /// <returns>Resolved signer.</returns>
    CryptoSignerResolution ResolveSigner(
        CryptoCapability capability,
        string algorithmId,
        CryptoKeyReference keyReference,
        string? preferredProvider = null);

    /// <summary>
    /// Resolves a content hasher for the supplied algorithm using registry policy.
    /// </summary>
    /// <param name="algorithmId">Hash algorithm identifier (e.g., SHA-256, GOST-R-34.11-2012-256).</param>
    /// <param name="preferredProvider">Optional provider hint.</param>
    /// <returns>Resolved hasher with provider name.</returns>
    CryptoHasherResolution ResolveHasher(string algorithmId, string? preferredProvider = null);
}

public sealed record CryptoSignerResolution(ICryptoSigner Signer, string ProviderName);

public sealed record CryptoHasherResolution(ICryptoHasher Hasher, string ProviderName);

/// <summary>
/// Content hasher for computing cryptographic digests.
/// </summary>
public interface ICryptoHasher
{
    /// <summary>
    /// Algorithm identifier (e.g., SHA-256, GOST-R-34.11-2012-256).
    /// </summary>
    string AlgorithmId { get; }

    /// <summary>
    /// Computes the hash of the given data.
    /// </summary>
    byte[] ComputeHash(ReadOnlySpan<byte> data);

    /// <summary>
    /// Computes the hash and returns it as a lowercase hex string.
    /// </summary>
    string ComputeHashHex(ReadOnlySpan<byte> data);
}