namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;

/// <summary>Persists API keys and audit records for authentication and accounting.</summary>
public interface IApiKeyStore
{
    /// <summary>Retrieves an API key by ID regardless of revocation status.</summary>
    /// <param name="keyId">Identifier of the API key.</param>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken cancellationToken);

    /// <summary>Retrieves an active (non-revoked) API key by ID.</summary>
    /// <param name="keyId">Identifier of the API key.</param>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken cancellationToken);

    /// <summary>Records that an API key was used for auditing and tracking.</summary>
    /// <param name="keyId">Identifier of the API key.</param>
    /// <param name="usedUtc">Timestamp when the key was used in UTC.</param>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    Task MarkKeyUsedAsync(string keyId, DateTimeOffset usedUtc, CancellationToken cancellationToken);
}
