feat(auth): ScadaBridge re-pin Auth 0.1.3 + add IInboundApiKeyAdmin seam over library admin facade (re-arch C1, additive)

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Security/IInboundApiKeyAdmin.cs

@@ -0,0 +1,66 @@
+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>
+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>
+    Task<IReadOnlyList<string>> GetMethodsForKeyAsync(string keyId, CancellationToken ct = default);
+
+    /// <summary>Returns the identifiers of all keys whose scopes contain
+    /// <paramref name="methodName"/>.</summary>
+    Task<IReadOnlyList<string>> GetKeysForMethodAsync(string methodName, CancellationToken ct = default);
+}