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);
+}
@@ -0,0 +1,47 @@
+namespace ZB.MOM.WW.Auth.Abstractions.Ldap;
+
+public enum LdapTransport { Ldaps, StartTls, None }
+
+public sealed record LdapOptions
+{
+    public bool Enabled { get; init; } = true;
+    public string Server { get; init; } = "localhost";
+    public int Port { get; init; } = 3893;
+    public LdapTransport Transport { get; init; } = LdapTransport.Ldaps;
+    public bool AllowInsecure { get; init; }
+    public string SearchBase { get; init; } = "";
+    public string ServiceAccountDn { get; init; } = "";
+    public string ServiceAccountPassword { get; init; } = "";
+    public string UserNameAttribute { get; init; } = "cn";
+    public string DisplayNameAttribute { get; init; } = "cn";
+    public string GroupAttribute { get; init; } = "memberOf";
+    public int ConnectionTimeoutMs { get; init; } = 10_000;
+}
+
+public enum LdapAuthFailure { BadCredentials, UserNotFound, AmbiguousUser, GroupLookupFailed, ServiceAccountBindFailed, Disabled }
+
+public sealed record LdapAuthResult(bool Succeeded, string Username, string DisplayName, IReadOnlyList<string> Groups, LdapAuthFailure? Failure)
+{
+    public static LdapAuthResult Success(string username, string displayName, IReadOnlyList<string> groups) => new(true, username, displayName, groups, null);
+    public static LdapAuthResult Fail(LdapAuthFailure failure) => new(false, "", "", Array.Empty<string>(), failure);
+}
+
+public interface ILdapAuthService
+{
+    /// <summary>
+    /// Authenticates <paramref name="username"/> against the directory by bind-then-search and
+    /// returns the outcome, including the resolved display name and group memberships on success.
+    /// </summary>
+    /// <param name="username">The login name to authenticate.</param>
+    /// <param name="password">The credential to bind with.</param>
+    /// <param name="ct">A token to request cancellation of the operation.</param>
+    /// <returns>The authentication result.</returns>
+    /// <remarks>
+    /// The cancellation token is observed at entry only. Implementations backed by synchronous
+    /// LDAP clients cannot abort an in-flight bind or search once it has been dispatched, so full
+    /// cooperative cancellation is not guaranteed mid-call: a request that has already reached the
+    /// directory will run to completion (subject to the configured connection timeout) even if the
+    /// token is cancelled.
+    /// </remarks>
+    Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct);
+}
@@ -0,0 +1,27 @@
+namespace ZB.MOM.WW.Auth.Abstractions.Roles;
+
+public enum CanonicalRole { Viewer, Operator, Engineer, Designer, Deployer, Administrator }
+
+public sealed record GroupRoleMapping<TRole>(IReadOnlyList<TRole> Roles, object? Scope);
+
+/// <summary>
+/// Maps a user's directory group memberships to a set of roles (typically
+/// <see cref="CanonicalRole"/>) plus an opaque scope payload.
+/// </summary>
+/// <typeparam name="TRole">The role vocabulary, e.g. <see cref="CanonicalRole"/>.</typeparam>
+/// <remarks>
+/// This library ships only the contract. Concrete canonical→native mappers are provided
+/// per-consumer (config-backed for OtOpcUa/mxaccessgw, DB/delegate-backed for ScadaBridge),
+/// because the backing store and the canonical→native role/permission expansion stay per-project
+/// (see <c>scadaproj/components/auth/GAPS.md</c>, gaps C1/C2). No default implementation is shipped here.
+/// </remarks>
+public interface IGroupRoleMapper<TRole>
+{
+    /// <summary>
+    /// Maps the supplied <paramref name="groups"/> to the roles and scope they grant.
+    /// </summary>
+    /// <param name="groups">The user's directory group memberships.</param>
+    /// <param name="ct">A token to request cancellation of the operation.</param>
+    /// <returns>The roles granted and an opaque scope payload.</returns>
+    Task<GroupRoleMapping<TRole>> MapAsync(IReadOnlyList<string> groups, CancellationToken ct);
+}
@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <IsPackable>true</IsPackable>
+    <PackageId>ZB.MOM.WW.Auth.Abstractions</PackageId>
+    <Authors>ZB.MOM.WW</Authors>
+    <Description>Auth contracts and canonical roles for the ZB.MOM.WW SCADA family.</Description>
+    <PackageProjectUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</PackageProjectUrl>
+    <RepositoryUrl>https://gitea.dohertylan.com/dohertj2/zb-mom-ww-auth</RepositoryUrl>
+  </PropertyGroup>
+
+</Project>