Initial commit: scadaproj umbrella — sister-project index, auth component normalization (design + GAPS), and the built ZB.MOM.WW.Auth shared library (0.1.0, flattened in).

2026-06-01 03:59:23 -04:00
commit 37e23cf9f2
73 changed files with 6836 additions and 0 deletions
@@ -0,0 +1,69 @@
+namespace ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+
+public sealed record ApiKeyOptions
+{
+    public string TokenPrefix { get; init; } = "mxgw";
+    public string PepperSecretName { get; init; } = "";
+    public string SqlitePath { get; init; } = "";
+    public bool RunMigrationsOnStartup { get; init; } = true;
+}
+
+public enum ApiKeyFailure { MissingOrMalformed, KeyNotFound, KeyRevoked, PepperUnavailable, SecretMismatch }
+
+public sealed record ApiKeyIdentity(string KeyId, string DisplayName, IReadOnlySet<string> Scopes, object? Constraints);
+
+public sealed record ApiKeyVerification(bool Succeeded, ApiKeyIdentity? Identity, ApiKeyFailure? Failure);
+
+public interface IApiKeyVerifier
+{
+    Task<ApiKeyVerification> VerifyAsync(string authorizationHeader, CancellationToken ct);
+}
+
+/// <remarks>
+/// As a positional record, <see cref="SecretHash"/> (<c>byte[]</c>) participates in equality
+/// BY REFERENCE. Two records whose <c>SecretHash</c> arrays contain identical bytes are NOT
+/// considered equal by <see cref="object.Equals(object?)"/>. Callers must not rely on value
+/// equality for <see cref="SecretHash"/>; use <see cref="System.MemoryExtensions.SequenceEqual{T}"/>
+/// or similar for content comparison.
+/// </remarks>
+public sealed record ApiKeyRecord(
+    string KeyId, string KeyPrefix, byte[] SecretHash, string DisplayName,
+    IReadOnlySet<string> Scopes, string? ConstraintsJson,
+    DateTimeOffset CreatedUtc, DateTimeOffset? LastUsedUtc, DateTimeOffset? RevokedUtc);
+
+public interface IApiKeyStore
+{
+    Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken ct);
+    Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken ct);
+    Task MarkUsedAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct);
+}
+
+public sealed record ApiKeyAuditEntry(string? KeyId, string EventType, string? RemoteAddress, DateTimeOffset CreatedUtc, string? Details);
+
+/// <summary>
+/// Hash-free projection of an API-key record, safe to enumerate and surface to admins.
+/// Deliberately omits <c>SecretHash</c> so that listing keys can never leak secret material.
+/// </summary>
+public sealed record ApiKeyListItem(
+    string KeyId, string KeyPrefix, string DisplayName, IReadOnlySet<string> Scopes,
+    string? ConstraintsJson, DateTimeOffset CreatedUtc, DateTimeOffset? LastUsedUtc, DateTimeOffset? RevokedUtc);
+
+public interface IApiKeyAdminStore
+{
+    Task CreateAsync(ApiKeyRecord record, CancellationToken ct);
+    Task<bool> RevokeAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct);
+    Task<bool> RotateAsync(string keyId, byte[] newSecretHash, CancellationToken ct);
+    Task<bool> DeleteAsync(string keyId, CancellationToken ct);
+
+    /// <summary>
+    /// Enumerates all API keys as hash-free <see cref="ApiKeyListItem"/> projections, newest first.
+    /// The secret hash is never selected, so callers cannot use this to recover secret material.
+    /// </summary>
+    Task<IReadOnlyList<ApiKeyListItem>> ListAsync(CancellationToken ct);
+}
+
+public interface IApiKeyAuditStore
+{
+    Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken ct);
+    Task<IReadOnlyList<ApiKeyAuditEntry>> ListRecentAsync(int limit, CancellationToken ct);
+}