fix(configuration-database): resolve ConfigurationDatabase-012 — store inbound-API keys as HMAC-SHA256 hashes

Inbound-API bearer credentials are no longer persisted in plaintext. ApiKey now
holds a KeyHash (peppered HMAC-SHA256); the key is shown once at creation and
only its hash is stored. Lookup and validation hash the presented candidate.
Cross-module: Commons (ApiKey, ApiKeyHasher), ConfigurationDatabase (mapping +
HashApiKeyValue migration), InboundAPI (ApiKeyValidator), ManagementService
(key creation), CentralUI (ApiKeys.razor). Existing keys must be re-issued.

src/ScadaLink.Commons/Entities/InboundApi/ApiKey.cs

@@ -1,15 +1,61 @@
+using ScadaLink.Commons.Types.InboundApi;
+
 namespace ScadaLink.Commons.Entities.InboundApi;
 
+/// <summary>
+/// An inbound-API bearer credential. Per ConfigurationDatabase-012 the plaintext key
+/// is never persisted: the entity stores only <see cref="KeyHash"/>, a deterministic
+/// keyed hash of the key (HMAC-SHA256 with a server-side pepper). The plaintext is
+/// generated at creation, shown to the operator exactly once, and then discarded.
+/// </summary>
 public class ApiKey
 {
     public int Id { get; set; }
     public string Name { get; set; }
-    public string KeyValue { get; set; }
+
+    /// <summary>
+    /// Deterministic keyed hash of the API key value. This is the only form of the
+    /// credential persisted; the plaintext key is never stored. Authentication hashes
+    /// the presented candidate with the same scheme and compares against this value.
+    /// </summary>
+    public string KeyHash { get; set; }
+
     public bool IsEnabled { get; set; }
 
+    /// <summary>
+    /// Creates an API key from a plaintext value, immediately hashing it with the
+    /// unpeppered default hasher (<see cref="ApiKeyHasher.Default"/>) so the entity
+    /// never holds the plaintext. Production code paths that have a configured pepper
+    /// should use <see cref="FromHash(string, string)"/> with a peppered hash instead.
+    /// </summary>
     public ApiKey(string name, string keyValue)
     {
         Name = name ?? throw new ArgumentNullException(nameof(name));
-        KeyValue = keyValue ?? throw new ArgumentNullException(nameof(keyValue));
+        if (keyValue is null) throw new ArgumentNullException(nameof(keyValue));
+        KeyHash = ApiKeyHasher.Default.Hash(keyValue);
+    }
+
+    /// <summary>
+    /// Parameterless constructor for the EF Core materializer. Application code uses
+    /// <see cref="ApiKey(string, string)"/> or <see cref="FromHash(string, string)"/>.
+    /// </summary>
+    private ApiKey()
+    {
+        Name = string.Empty;
+        KeyHash = string.Empty;
+    }
+
+    /// <summary>
+    /// Creates an API key from an already-computed key hash. Used by the creation
+    /// path, which generates a random key, hashes it with the configured (peppered)
+    /// <see cref="IApiKeyHasher"/>, and stores only the resulting hash.
+    /// </summary>
+    public static ApiKey FromHash(string name, string keyHash)
+    {
+        return new ApiKey
+        {
+            Name = name ?? throw new ArgumentNullException(nameof(name)),
+            KeyHash = keyHash ?? throw new ArgumentNullException(nameof(keyHash)),
+        };
     }
 }

src/ScadaLink.Commons/Types/InboundApi/ApiKeyHasher.cs

@@ -0,0 +1,92 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace ScadaLink.Commons.Types.InboundApi;
+
+/// <summary>
+/// Computes a deterministic, keyed hash of an inbound-API key value
+/// (ConfigurationDatabase-012). API keys are persisted as this hash, never as
+/// plaintext, so a configuration-database dump does not yield usable credentials.
+/// The hash is deterministic so authentication can still resolve a key by value.
+/// </summary>
+public interface IApiKeyHasher
+{
+    /// <summary>
+    /// Returns the keyed hash of <paramref name="apiKey"/> as a Base64 string.
+    /// The same input always produces the same output (deterministic), which keeps
+    /// the by-value lookup working.
+    /// </summary>
+    string Hash(string apiKey);
+}
+
+/// <summary>
+/// HMAC-SHA256 implementation of <see cref="IApiKeyHasher"/>. The HMAC key is a
+/// server-side <em>pepper</em> bound from configuration. A per-row random salt is
+/// intentionally NOT used: an API key is already a high-entropy random token, and a
+/// random salt would break the deterministic by-value lookup the authentication
+/// path relies on. The pepper instead binds every hash to this deployment, so a
+/// stolen database is useless without it.
+/// </summary>
+public sealed class ApiKeyHasher : IApiKeyHasher
+{
+    /// <summary>
+    /// Minimum accepted pepper length. A pepper shorter than this is treated as a
+    /// deployment misconfiguration and rejected — see <see cref="ApiKeyHasher(string)"/>.
+    /// </summary>
+    public const int MinimumPepperLength = 16;
+
+    private readonly byte[] _pepper;
+
+    /// <summary>
+    /// An unpeppered hasher (HMAC-SHA256 keyed with a fixed, empty-equivalent value).
+    /// It is still a one-way hash, but carries no deployment-specific binding. It
+    /// exists for tests and non-production wiring; production must construct an
+    /// <see cref="ApiKeyHasher"/> with a real pepper.
+    /// </summary>
+    public static ApiKeyHasher Default { get; } = new ApiKeyHasher();
+
+    private ApiKeyHasher()
+    {
+        // Fixed, deployment-independent key for the unpeppered default.
+        _pepper = Encoding.UTF8.GetBytes("ScadaLink.InboundApi.DefaultApiKeyHasher");
+    }
+
+    /// <summary>
+    /// Creates a hasher keyed with the given server-side pepper.
+    /// </summary>
+    /// <exception cref="ArgumentException">
+    /// Thrown if <paramref name="pepper"/> is null, blank, or shorter than
+    /// <see cref="MinimumPepperLength"/> — a missing or weak pepper is a deployment
+    /// misconfiguration and must fail loudly rather than degrade silently.
+    /// </exception>
+    public ApiKeyHasher(string pepper)
+    {
+        if (string.IsNullOrWhiteSpace(pepper))
+        {
+            throw new ArgumentException(
+                "The API-key HMAC pepper must be configured. Set a strong, random value " +
+                "in configuration (ScadaLink:InboundApi:ApiKeyPepper).",
+                nameof(pepper));
+        }
+
+        if (pepper.Trim().Length < MinimumPepperLength)
+        {
+            throw new ArgumentException(
+                $"The API-key HMAC pepper is too weak: it must be at least {MinimumPepperLength} " +
+                "characters. Use a strong, random value.",
+                nameof(pepper));
+        }
+
+        _pepper = Encoding.UTF8.GetBytes(pepper);
+    }
+
+    /// <inheritdoc />
+    public string Hash(string apiKey)
+    {
+        ArgumentNullException.ThrowIfNull(apiKey);
+
+        using var hmac = new HMACSHA256(_pepper);
+        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(apiKey));
+        return Convert.ToBase64String(hash);
+    }
+}