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

public interface IApiKeyAdminStore
{
    /// <summary>
    /// Creates a new API key asynchronously.
    /// </summary>
    /// <param name="request">API key creation request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Completed task.</returns>
    Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken);

    /// <summary>
    /// Lists all API keys asynchronously.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of API key records.</returns>
    Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken);

    /// <summary>
    /// Revokes an API key asynchronously.
    /// </summary>
    /// <param name="keyId">Key identifier.</param>
    /// <param name="revokedUtc">Revocation timestamp.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if revoked; otherwise false.</returns>
    Task<bool> RevokeAsync(string keyId, DateTimeOffset revokedUtc, CancellationToken cancellationToken);

    /// <summary>
    /// Rotates an API key secret asynchronously.
    /// </summary>
    /// <param name="keyId">Key identifier.</param>
    /// <param name="secretHash">New secret hash.</param>
    /// <param name="rotatedUtc">Rotation timestamp.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if rotated; otherwise false.</returns>
    Task<bool> RotateAsync(
        string keyId,
        byte[] secretHash,
        DateTimeOffset rotatedUtc,
        CancellationToken cancellationToken);

    /// <summary>
    /// Permanently deletes an API key, but only if it is already revoked. Active keys are
    /// untouched (returns false) so an admin cannot delete a working credential without
    /// first revoking it — that preserves the audit trail and forces the revoke event to
    /// land in the audit log before the row disappears.
    /// </summary>
    /// <param name="keyId">Key identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if a revoked key was deleted; false if the key is missing or active.</returns>
    Task<bool> DeleteAsync(string keyId, CancellationToken cancellationToken);
}