rename: prefix gateway projects/namespaces with ZB.MOM.WW + sln→slnx

Apply the ZB.MOM.WW. prefix to all gateway-side projects, folders, .csproj/.sln contents, C# namespaces, using directives, generated proto C# (csharp_namespace + checked-in generated files), InternalsVisibleTo attributes, project-name string literals (LoadProject, .sln lookups, worker exe paths, staticwebassets manifest), and the install/script/doc references that point at any of the above. Migrate the solution from .sln to .slnx via `dotnet sln migrate` and delete the old file. External-runtime identifiers are intentionally NOT prefixed so external configuration keeps working: - GatewayMetrics.cs MeterName ("MxGateway.Server") - DashboardAuthenticationDefaults Scheme/Policy ("MxGateway.Dashboard") - GatewayRequestLoggingMiddleware logger category ("MxGateway.Request") - StaRuntime thread name ("MxGateway.Worker.STA") - appsettings.json root section "MxGateway" + env-var prefix MxGateway__... and secret-name MxGateway:ApiKeyPepper - C:\ProgramData\MxGateway\ data dir paths Also fixes two tests that were not rename-related but became visible while validating the rename: - WorkerLiveMxAccessSmokeTests.ShutDownAsync: cancellation that the gateway service correctly maps to RpcException(Cancelled) per gRPC convention was being misclassified as a stream fault. Added a sibling catch on RpcException with StatusCode.Cancelled. - IntegrationTestEnvironment.ResolveRepositoryRoot: extracted IsRepositoryRoot and made it accept either a .git marker OR a .sln/.slnx next to src/ so the worker-exe walker works in non-git working copies. clients/proto/proto-inputs.json's protoRoot updated to point at src/ZB.MOM.WW.MxGateway.Contracts/Protos. Verified by `dotnet build` and a full `dotnet test` of the .slnx with MXGATEWAY_RUN_LIVE_{MXACCESS,LDAP,GALAXY}_TESTS=1: Tests: 472/472 pass Worker.Tests: 280/280 pass (4 dev-rig [Fact(Skip=...)] skipped) IntegrationTests: 18/18 pass Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-23 16:22:23 -04:00
parent 867bf18116
commit dc9c0c950c
491 changed files with 32854 additions and 8414 deletions
@@ -0,0 +1,165 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Server.Galaxy;
+using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+using ZB.MOM.WW.MxGateway.Server.Sessions;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public sealed class ConstraintEnforcer(
+    IGalaxyHierarchyCache cache,
+    IApiKeyAuditStore auditStore) : IConstraintEnforcer
+{
+    public Task<ConstraintFailure?> CheckReadTagAsync(
+        ApiKeyIdentity? identity,
+        string tagAddress,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyConstraints constraints = identity?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        if (!constraints.HasReadConstraints)
+        {
+            return Task.FromResult<ConstraintFailure?>(null);
+        }
+
+        return Task.FromResult(CheckReadTarget(constraints, tagAddress));
+    }
+
+    public Task<ConstraintFailure?> CheckReadHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyConstraints constraints = identity?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        if (!constraints.HasReadConstraints)
+        {
+            return Task.FromResult<ConstraintFailure?>(null);
+        }
+
+        if (!session.TryGetItemRegistration(serverHandle, itemHandle, out SessionItemRegistration registration))
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("item_handle", "Item handle is not registered in the constrained session."));
+        }
+
+        return Task.FromResult(CheckReadTarget(constraints, registration.TagAddress));
+    }
+
+    public Task<ConstraintFailure?> CheckWriteHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyConstraints constraints = identity?.EffectiveConstraints ?? ApiKeyConstraints.Empty;
+        if (!constraints.HasWriteConstraints)
+        {
+            return Task.FromResult<ConstraintFailure?>(null);
+        }
+
+        if (!session.TryGetItemRegistration(serverHandle, itemHandle, out SessionItemRegistration registration))
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("item_handle", "Item handle is not registered in the constrained session."));
+        }
+
+        GalaxyTagLookup? target = ResolveTarget(registration.TagAddress);
+        if (target is null)
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("tag_metadata", "Tag metadata is not available in the Galaxy hierarchy cache."));
+        }
+
+        if (!MatchesPathOrTag(target.ContainedPath, registration.TagAddress, constraints.WriteSubtrees, constraints.WriteTagGlobs))
+        {
+            return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("write_scope", "Tag is outside the API key write scope."));
+        }
+
+        if (constraints.MaxWriteClassification is { } maxClassification)
+        {
+            GalaxyAttribute? attribute = target.Attribute;
+            if (attribute is null)
+            {
+                return Task.FromResult<ConstraintFailure?>(new ConstraintFailure("max_write_classification", "Attribute security classification is not available."));
+            }
+
+            if (attribute.SecurityClassification > maxClassification)
+            {
+                return Task.FromResult<ConstraintFailure?>(new ConstraintFailure(
+                    "max_write_classification",
+                    $"Attribute security classification {attribute.SecurityClassification} exceeds allowed maximum {maxClassification}."));
+            }
+        }
+
+        return Task.FromResult<ConstraintFailure?>(null);
+    }
+
+    public async Task RecordDenialAsync(
+        ApiKeyIdentity? identity,
+        string commandKind,
+        string target,
+        ConstraintFailure failure,
+        CancellationToken cancellationToken)
+    {
+        await auditStore.AppendAsync(
+                new ApiKeyAuditEntry(
+                    KeyId: identity?.KeyId,
+                    EventType: "constraint-denied",
+                    RemoteAddress: null,
+                    Details: $"{commandKind}: {target}: {failure.ConstraintName}: {failure.Message}"),
+                cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    private ConstraintFailure? CheckReadTarget(
+        ApiKeyConstraints constraints,
+        string tagAddress)
+    {
+        GalaxyTagLookup? target = ResolveTarget(tagAddress);
+        if (target is null)
+        {
+            return new ConstraintFailure("tag_metadata", "Tag metadata is not available in the Galaxy hierarchy cache.");
+        }
+
+        if (!MatchesPathOrTag(target.ContainedPath, tagAddress, constraints.ReadSubtrees, constraints.ReadTagGlobs))
+        {
+            return new ConstraintFailure("read_scope", "Tag is outside the API key read scope.");
+        }
+
+        if (constraints.ReadAlarmOnly && target.Attribute is not { IsAlarm: true })
+        {
+            return new ConstraintFailure("read_alarm_only", "Tag is not an alarm-bearing attribute.");
+        }
+
+        if (constraints.ReadHistorizedOnly && target.Attribute is not { IsHistorized: true })
+        {
+            return new ConstraintFailure("read_historized_only", "Tag is not a historized attribute.");
+        }
+
+        return null;
+    }
+
+    private GalaxyTagLookup? ResolveTarget(string tagAddress)
+    {
+        GalaxyHierarchyCacheEntry entry = cache.Current;
+        return !string.IsNullOrWhiteSpace(tagAddress)
+            && entry.Index.TagsByAddress.TryGetValue(tagAddress, out GalaxyTagLookup? lookup)
+                ? lookup
+                : null;
+    }
+
+    private static bool MatchesPathOrTag(
+        string containedPath,
+        string tagAddress,
+        IReadOnlyList<string> subtreeGlobs,
+        IReadOnlyList<string> tagGlobs)
+    {
+        bool hasSubtreeConstraint = subtreeGlobs.Count > 0;
+        bool hasTagConstraint = tagGlobs.Count > 0;
+        if (!hasSubtreeConstraint && !hasTagConstraint)
+        {
+            return true;
+        }
+
+        return subtreeGlobs.Any(glob => GalaxyGlobMatcher.IsMatch(containedPath, glob))
+            || tagGlobs.Any(glob => GalaxyGlobMatcher.IsMatch(tagAddress, glob));
+    }
+}
@@ -0,0 +1,3 @@
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public sealed record ConstraintFailure(string ConstraintName, string Message);
@@ -0,0 +1,81 @@
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public sealed class GatewayGrpcAuthorizationInterceptor(
+    IApiKeyVerifier apiKeyVerifier,
+    GatewayGrpcScopeResolver scopeResolver,
+    IGatewayRequestIdentityAccessor identityAccessor,
+    IOptions<GatewayOptions> options) : Interceptor
+{
+    /// <inheritdoc />
+    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
+        TRequest request,
+        ServerCallContext context,
+        UnaryServerMethod<TRequest, TResponse> continuation)
+    {
+        ApiKeyIdentity? identity = await AuthenticateAndAuthorizeAsync(request, context).ConfigureAwait(false);
+        IDisposable? identityScope = identity is null ? null : identityAccessor.Push(identity);
+        using (identityScope)
+        {
+            return await continuation(request, context).ConfigureAwait(false);
+        }
+    }
+
+    /// <inheritdoc />
+    public override async Task ServerStreamingServerHandler<TRequest, TResponse>(
+        TRequest request,
+        IServerStreamWriter<TResponse> responseStream,
+        ServerCallContext context,
+        ServerStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        ApiKeyIdentity? identity = await AuthenticateAndAuthorizeAsync(request, context).ConfigureAwait(false);
+        IDisposable? identityScope = identity is null ? null : identityAccessor.Push(identity);
+        using (identityScope)
+        {
+            await continuation(request, responseStream, context).ConfigureAwait(false);
+        }
+    }
+
+    /// <summary>Authenticates the API key and authorizes the RPC call by required scope.</summary>
+    /// <typeparam name="TRequest">Request message type.</typeparam>
+    /// <param name="request">Request payload.</param>
+    /// <param name="context">RPC server call context.</param>
+    /// <returns>Authenticated API key identity, or null if authentication is disabled.</returns>
+    private async Task<ApiKeyIdentity?> AuthenticateAndAuthorizeAsync<TRequest>(
+        TRequest request,
+        ServerCallContext context)
+        where TRequest : class
+    {
+        if (options.Value.Authentication.Mode == AuthenticationMode.Disabled)
+        {
+            return null;
+        }
+
+        string? authorizationHeader = context.RequestHeaders.GetValue("authorization");
+        ApiKeyVerificationResult verificationResult = await apiKeyVerifier
+            .VerifyAsync(authorizationHeader, context.CancellationToken)
+            .ConfigureAwait(false);
+
+        if (!verificationResult.Succeeded || verificationResult.Identity is null)
+        {
+            throw new RpcException(new Status(
+                StatusCode.Unauthenticated,
+                "Missing or invalid API key."));
+        }
+
+        string requiredScope = scopeResolver.ResolveRequiredScope(request);
+        if (!verificationResult.Identity.Scopes.Contains(requiredScope))
+        {
+            throw new RpcException(new Status(
+                StatusCode.PermissionDenied,
+                $"API key is missing required scope '{requiredScope}'."));
+        }
+
+        return verificationResult.Identity;
+    }
+}
@@ -0,0 +1,56 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public sealed class GatewayGrpcScopeResolver
+{
+    /// <summary>
+    /// Resolves the required authorization scope for a gRPC request.
+    /// </summary>
+    /// <param name="request">The gRPC request.</param>
+    /// <returns>Required authorization scope.</returns>
+    public string ResolveRequiredScope(object request)
+    {
+        return request switch
+        {
+            OpenSessionRequest => GatewayScopes.SessionOpen,
+            CloseSessionRequest => GatewayScopes.SessionClose,
+            StreamEventsRequest => GatewayScopes.EventsRead,
+            MxCommandRequest commandRequest => ResolveCommandScope(commandRequest.Command?.Kind ?? MxCommandKind.Unspecified),
+            AcknowledgeAlarmRequest => GatewayScopes.InvokeWrite,
+            StreamAlarmsRequest => GatewayScopes.EventsRead,
+            TestConnectionRequest or
+            GetLastDeployTimeRequest or
+            DiscoverHierarchyRequest or
+            WatchDeployEventsRequest => GatewayScopes.MetadataRead,
+            _ => GatewayScopes.Admin
+        };
+    }
+
+    private static string ResolveCommandScope(MxCommandKind kind)
+    {
+        return kind switch
+        {
+            MxCommandKind.Write or
+            MxCommandKind.Write2 or
+            MxCommandKind.WriteBulk or
+            MxCommandKind.Write2Bulk => GatewayScopes.InvokeWrite,
+
+            MxCommandKind.WriteSecured or
+            MxCommandKind.WriteSecured2 or
+            MxCommandKind.WriteSecuredBulk or
+            MxCommandKind.WriteSecured2Bulk or
+            MxCommandKind.AuthenticateUser => GatewayScopes.InvokeSecure,
+
+            MxCommandKind.ArchestraUserToId or
+            MxCommandKind.GetSessionState or
+            MxCommandKind.GetWorkerInfo => GatewayScopes.MetadataRead,
+
+            MxCommandKind.DrainEvents => GatewayScopes.EventsRead,
+            MxCommandKind.ShutdownWorker => GatewayScopes.Admin,
+
+            _ => GatewayScopes.InvokeRead
+        };
+    }
+}
@@ -0,0 +1,43 @@
+using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public sealed class GatewayRequestIdentityAccessor : IGatewayRequestIdentityAccessor
+{
+    private readonly AsyncLocal<ApiKeyIdentity?> currentIdentity = new();
+
+    /// <summary>Gets the current request identity.</summary>
+    public ApiKeyIdentity? Current => currentIdentity.Value;
+
+    /// <summary>Sets the current identity and returns a scope that restores the previous identity.</summary>
+    /// <param name="identity">The identity to push.</param>
+    /// <returns>Disposable scope.</returns>
+    public IDisposable Push(ApiKeyIdentity identity)
+    {
+        ArgumentNullException.ThrowIfNull(identity);
+
+        ApiKeyIdentity? previousIdentity = currentIdentity.Value;
+        currentIdentity.Value = identity;
+
+        return new IdentityScope(this, previousIdentity);
+    }
+
+    private sealed class IdentityScope(
+        GatewayRequestIdentityAccessor accessor,
+        ApiKeyIdentity? previousIdentity) : IDisposable
+    {
+        private bool disposed;
+
+        /// <summary>Restores the previous identity.</summary>
+        public void Dispose()
+        {
+            if (disposed)
+            {
+                return;
+            }
+
+            accessor.currentIdentity.Value = previousIdentity;
+            disposed = true;
+        }
+    }
+}
@@ -0,0 +1,37 @@
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public static class GatewayScopes
+{
+    public const string SessionOpen = "session:open";
+    public const string SessionClose = "session:close";
+    public const string InvokeRead = "invoke:read";
+    public const string InvokeWrite = "invoke:write";
+    public const string InvokeSecure = "invoke:secure";
+    public const string EventsRead = "events:read";
+    public const string MetadataRead = "metadata:read";
+    public const string Admin = "admin";
+
+    /// <summary>
+    ///     The complete catalog of canonical scope strings the gateway authorization
+    ///     resolver recognizes. Key-creation paths (CLI and dashboard) validate requested
+    ///     scopes against this set so a typo or non-canonical name cannot persist a key
+    ///     whose scope strings the resolver never matches.
+    /// </summary>
+    public static readonly IReadOnlySet<string> All = new HashSet<string>(
+        [
+            SessionOpen,
+            SessionClose,
+            InvokeRead,
+            InvokeWrite,
+            InvokeSecure,
+            EventsRead,
+            MetadataRead,
+            Admin,
+        ],
+        System.StringComparer.Ordinal);
+
+    /// <summary>Determines whether the supplied scope string is a recognized canonical scope.</summary>
+    /// <param name="scope">Scope string to check.</param>
+    /// <returns><see langword="true"/> when the scope is canonical; otherwise <see langword="false"/>.</returns>
+    public static bool IsKnown(string scope) => All.Contains(scope);
+}
@@ -0,0 +1,35 @@
+using Grpc.Core.Interceptors;
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+/// <summary>
+/// Extension methods for configuring gRPC authorization services.
+/// </summary>
+public static class GrpcAuthorizationServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers gRPC authorization middleware and scope resolver.
+    /// </summary>
+    /// <param name="services">Service collection to register dependencies into.</param>
+    public static IServiceCollection AddGatewayGrpcAuthorization(this IServiceCollection services)
+    {
+        services.AddSingleton<GatewayGrpcScopeResolver>();
+        services.AddSingleton<IGatewayRequestIdentityAccessor, GatewayRequestIdentityAccessor>();
+        services.AddSingleton<IConstraintEnforcer, ConstraintEnforcer>();
+        services.AddSingleton<GatewayGrpcAuthorizationInterceptor>();
+        services
+            .AddOptions<global::Grpc.AspNetCore.Server.GrpcServiceOptions>()
+            .Configure<IConfiguration>((grpcOptions, configuration) =>
+            {
+                ProtocolOptions protocolOptions = new();
+                configuration.GetSection("MxGateway:Protocol").Bind(protocolOptions);
+                grpcOptions.MaxReceiveMessageSize = protocolOptions.MaxGrpcMessageBytes;
+                grpcOptions.MaxSendMessageSize = protocolOptions.MaxGrpcMessageBytes;
+            });
+        services.AddGrpc(options => options.Interceptors.Add<GatewayGrpcAuthorizationInterceptor>());
+
+        return services;
+    }
+}
@@ -0,0 +1,33 @@
+using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+using ZB.MOM.WW.MxGateway.Server.Sessions;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+public interface IConstraintEnforcer
+{
+    Task<ConstraintFailure?> CheckReadTagAsync(
+        ApiKeyIdentity? identity,
+        string tagAddress,
+        CancellationToken cancellationToken);
+
+    Task<ConstraintFailure?> CheckReadHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken);
+
+    Task<ConstraintFailure?> CheckWriteHandleAsync(
+        ApiKeyIdentity? identity,
+        GatewaySession session,
+        int serverHandle,
+        int itemHandle,
+        CancellationToken cancellationToken);
+
+    Task RecordDenialAsync(
+        ApiKeyIdentity? identity,
+        string commandKind,
+        string target,
+        ConstraintFailure failure,
+        CancellationToken cancellationToken);
+}
@@ -0,0 +1,14 @@
+using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+
+/// <summary>Provides scoped access to the current request's API key identity within a gRPC call context.</summary>
+public interface IGatewayRequestIdentityAccessor
+{
+    /// <summary>The API key identity of the current request, or null if not set.</summary>
+    ApiKeyIdentity? Current { get; }
+
+    /// <summary>Temporarily pushes an identity onto the scope stack, returning a handle to restore the previous state.</summary>
+    /// <param name="identity">API key identity to push.</param>
+    IDisposable Push(ApiKeyIdentity identity);
+}