namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Security;

/// <summary>
/// Read-side projection of one inbound API key, as surfaced by the management seam.
/// Hash-free by construction — the secret is never carried here; it is shown ONCE at
/// creation via <see cref="InboundApiKeyCreated"/>.
/// </summary>
/// <param name="KeyId">Stable key identifier (the middle segment of the token).</param>
/// <param name="Name">Operator-facing display name.</param>
/// <param name="Enabled">True while the key is active (not revoked/disabled).</param>
/// <param name="Methods">The API-method names this key is scoped to call, sorted ordinally.</param>
/// <param name="CreatedUtc">When the key was created.</param>
/// <param name="LastUsedUtc">When the key last authenticated a request, if ever.</param>
public sealed record InboundApiKeyInfo(
    string KeyId,
    string Name,
    bool Enabled,
    IReadOnlyList<string> Methods,
    DateTimeOffset CreatedUtc,
    DateTimeOffset? LastUsedUtc);

/// <summary>
/// Result of creating a key. <see cref="Token"/> is the assembled bearer token
/// (<c>sbk_&lt;keyId&gt;_&lt;secret&gt;</c>) and is the ONLY moment the secret is available —
/// it is never retrievable afterwards.
/// </summary>
/// <param name="KeyId">The new key's identifier.</param>
/// <param name="Token">The bearer token, shown once.</param>
public sealed record InboundApiKeyCreated(string KeyId, string Token);

/// <summary>
/// App-facing management seam for inbound API keys. This is the single shared path CLI
/// and CentralUI use to create / list / enable / disable / delete inbound keys and edit
/// their method-scopes. The interface lives in Commons and is deliberately free of any
/// dependency on the underlying auth library, so consumers depend only on this contract.
/// </summary>
/// <remarks>
/// Mutating operations (<see cref="CreateAsync"/>, <see cref="SetEnabledAsync"/>,
/// <see cref="SetMethodsAsync"/>, <see cref="DeleteAsync"/>) may <b>throw</b> on
/// store-level or configuration failures (e.g. an unavailable pepper) rather than
/// exclusively signalling failure via their <c>bool</c> return — callers must handle
/// exceptions in addition to checking the return value.
/// </remarks>
public interface IInboundApiKeyAdmin
{
    /// <summary>Creates a new key scoped to <paramref name="methods"/> and returns its
    /// identifier plus the bearer token (shown once).</summary>
    Task<InboundApiKeyCreated> CreateAsync(
        string name, IReadOnlyCollection<string> methods, CancellationToken ct = default);

    /// <summary>Lists all inbound keys (hash-free projection).</summary>
    Task<IReadOnlyList<InboundApiKeyInfo>> ListAsync(CancellationToken ct = default);

    /// <summary>Enables or disables a key without changing its secret. Returns false if
    /// the key does not exist.</summary>
    Task<bool> SetEnabledAsync(string keyId, bool enabled, CancellationToken ct = default);

    /// <summary>Replaces the method-scope set on a key without changing its secret.
    /// Returns false if the key does not exist.</summary>
    Task<bool> SetMethodsAsync(
        string keyId, IReadOnlyCollection<string> methods, CancellationToken ct = default);

    /// <summary>Removes a key (revoke-then-delete). Returns false if the key could not be
    /// deleted.</summary>
    Task<bool> DeleteAsync(string keyId, CancellationToken ct = default);

    /// <summary>Returns the method-scope set for a key, or an empty list if not found.</summary>
    /// <remarks>Enumerates the full key list (O(n)); intended for admin-scale use, not hot paths.</remarks>
    Task<IReadOnlyList<string>> GetMethodsForKeyAsync(string keyId, CancellationToken ct = default);

    /// <summary>Returns the identifiers of all keys whose scopes contain
    /// <paramref name="methodName"/>.</summary>
    /// <remarks>Enumerates the full key list (O(n)); intended for admin-scale use, not hot paths.</remarks>
    Task<IReadOnlyList<string>> GetKeysForMethodAsync(string methodName, CancellationToken ct = default);
}