Merge origin/main with local pending work and update AGENTS.md references

- Resolve 14 conflicts from popping local stash on top of origin's eed1e88 + 8d3352f doc-comment additions (11 mechanical, plus version.rs, DashboardAuthenticatorTests.cs, DashboardGalaxyProjector.cs) - Fix 4 test files that used AGENTS.md as the repo-root sentinel (now use CLAUDE.md, since AGENTS.md was removed in 4731ab5) - Redirect 10 doc citations from AGENTS.md to the matching gateway.md sections (Value Model, Status Model, Security, STA Worker Thread Model, gRPC Layer rule, cancellation rule) Verified: solution build clean, x86 worker build clean, 266/266 gateway tests passing, 121/121 worker tests passing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 14:13:33 -04:00
parent 8d3352f2c6
commit ddad573b75
101 changed files with 6053 additions and 621 deletions
@@ -1,135 +1,74 @@
-using System.Security.Claims;
+using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
 using MxGateway.Server.Configuration;
 using MxGateway.Server.Dashboard;
-using MxGateway.Server.Security.Authentication;
-using MxGateway.Server.Security.Authorization;

 namespace MxGateway.Tests.Gateway.Dashboard;

-/// <summary>
-/// Tests for dashboard authentication using API keys.
-/// </summary>
 public sealed class DashboardAuthenticatorTests
 {
-    /// <summary>
-    /// Verifies an admin-scoped key produces a valid cookie principal.
-    /// </summary>
    [Fact]
-    public async Task AuthenticateAsync_AdminKey_ReturnsCookiePrincipal()
+    public void EscapeLdapFilter_EscapesSpecialCharacters()
    {
-        FakeApiKeyVerifier verifier = new(SuccessWithScopes(GatewayScopes.Admin));
-        DashboardAuthenticator authenticator = CreateAuthenticator(verifier);
+        string escaped = DashboardAuthenticator.EscapeLdapFilter("a\\b*c(d)e\0f");

-        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
-            "mxgw_operator01_super-secret",
-            CancellationToken.None);
-
-        Assert.True(result.Succeeded);
-        Assert.NotNull(result.Principal);
-        Assert.Equal("operator01", result.Principal.FindFirst(ClaimTypes.NameIdentifier)?.Value);
-        Assert.Equal("Operator Key", result.Principal.FindFirst(ClaimTypes.Name)?.Value);
-        Assert.Contains(result.Principal.Claims, claim =>
-            claim.Type == DashboardAuthenticationDefaults.ScopeClaimType
-            && claim.Value == GatewayScopes.Admin);
-        Assert.Equal("Bearer mxgw_operator01_super-secret", verifier.LastAuthorizationHeader);
+        Assert.Equal("a\\5cb\\2ac\\28d\\29e\\00f", escaped);
    }

-    /// <summary>
-    /// Verifies a non-admin key fails authentication without exposing the API key.
-    /// </summary>
-    [Fact]
-    public async Task AuthenticateAsync_NonAdminKey_ReturnsFailureWithoutRawApiKey()
+    [Theory]
+    [InlineData("GwAdmin", true)]
+    [InlineData("gwadmin", true)]
+    [InlineData("ou=GwAdmin,ou=groups,dc=lmxopcua,dc=local", true)]
+    [InlineData("OtherGroup", false)]
+    public void IsMemberOfRequiredGroup_MatchesShortNameAndDistinguishedName(
+        string requiredGroup,
+        bool expected)
    {
-        DashboardAuthenticator authenticator = CreateAuthenticator(new FakeApiKeyVerifier(
-            SuccessWithScopes(GatewayScopes.EventsRead)));
+        string[] groups =
+        [
+            "ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local",
+            "ou=GwAdmin,ou=groups,dc=lmxopcua,dc=local"
+        ];
+
+        bool result = DashboardAuthenticator.IsMemberOfRequiredGroup(groups, requiredGroup);
+
+        Assert.Equal(expected, result);
+    }
+
+    [Fact]
+    public void ExtractFirstRdnValue_ReturnsLeadingRdnValue()
+    {
+        string result = DashboardAuthenticator.ExtractFirstRdnValue(
+            "CN=Gateway Admins,OU=Groups,DC=example,DC=com");
+
+        Assert.Equal("Gateway Admins", result);
+    }
+
+    [Fact]
+    public async Task AuthenticateAsync_LdapDisabled_ReturnsFailureWithoutRawCredentials()
+    {
+        DashboardAuthenticator authenticator = CreateAuthenticator(new GatewayOptions
+        {
+            Ldap = new LdapOptions
+            {
+                Enabled = false,
+            },
+        });

        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
-            "mxgw_operator01_super-secret",
+            "admin",
+            "admin123",
            CancellationToken.None);

        Assert.False(result.Succeeded);
        Assert.Null(result.Principal);
-        Assert.DoesNotContain("super-secret", result.FailureMessage, StringComparison.Ordinal);
+        Assert.DoesNotContain("admin123", result.FailureMessage, StringComparison.Ordinal);
    }

-    /// <summary>
-    /// Verifies that when admin scope is not required, any authenticated key is accepted.
-    /// </summary>
-    [Fact]
-    public async Task AuthenticateAsync_RequireAdminScopeFalse_AllowsAuthenticatedKey()
-    {
-        DashboardAuthenticator authenticator = CreateAuthenticator(
-            new FakeApiKeyVerifier(SuccessWithScopes(GatewayScopes.EventsRead)),
-            requireAdminScope: false);
-
-        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
-            "mxgw_operator01_secret",
-            CancellationToken.None);
-
-        Assert.True(result.Succeeded);
-        Assert.NotNull(result.Principal);
-    }
-
-    /// <summary>
-    /// Verifies an invalid key returns a generic failure message.
-    /// </summary>
-    [Fact]
-    public async Task AuthenticateAsync_InvalidKey_ReturnsGenericFailure()
-    {
-        DashboardAuthenticator authenticator = CreateAuthenticator(new FakeApiKeyVerifier(
-            ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.SecretMismatch)));
-
-        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
-            "mxgw_operator01_super-secret",
-            CancellationToken.None);
-
-        Assert.False(result.Succeeded);
-        Assert.DoesNotContain("super-secret", result.FailureMessage, StringComparison.Ordinal);
-    }
-
-    private static DashboardAuthenticator CreateAuthenticator(
-        IApiKeyVerifier verifier,
-        bool requireAdminScope = true)
+    private static DashboardAuthenticator CreateAuthenticator(GatewayOptions options)
    {
        return new DashboardAuthenticator(
-            verifier,
-            Options.Create(new GatewayOptions
-            {
-                Dashboard = new DashboardOptions
-                {
-                    RequireAdminScope = requireAdminScope
-                }
-            }));
-    }
-
-    private static ApiKeyVerificationResult SuccessWithScopes(params string[] scopes)
-    {
-        return ApiKeyVerificationResult.Success(new ApiKeyIdentity(
-            KeyId: "operator01",
-            KeyPrefix: "mxgw_operator01",
-            DisplayName: "Operator Key",
-            Scopes: new HashSet<string>(scopes, StringComparer.Ordinal)));
-    }
-
-    /// <summary>
-    /// Test implementation that records the authorization header for verification.
-    /// </summary>
-    private sealed class FakeApiKeyVerifier(ApiKeyVerificationResult result) : IApiKeyVerifier
-    {
-        /// <summary>
-        /// The authorization header that was last verified.
-        /// </summary>
-        public string? LastAuthorizationHeader { get; private set; }
-
-        /// <inheritdoc />
-        public Task<ApiKeyVerificationResult> VerifyAsync(
-            string? authorizationHeader,
-            CancellationToken cancellationToken)
-        {
-            LastAuthorizationHeader = authorizationHeader;
-
-            return Task.FromResult(result);
-        }
+            Options.Create(options),
+            NullLogger<DashboardAuthenticator>.Instance);
    }
 }
@@ -4,6 +4,8 @@ using MxGateway.Server.Configuration;
 using MxGateway.Server.Dashboard;
 using MxGateway.Server.Galaxy;
 using MxGateway.Server.Metrics;
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Security.Authorization;
 using MxGateway.Server.Sessions;
 using MxGateway.Server.Workers;

@@ -200,17 +202,27 @@ public sealed class DashboardSnapshotServiceTests
            LastQueriedAt = DateTimeOffset.Parse("2026-04-28T11:30:00Z"),
            LastSuccessAt = DateTimeOffset.Parse("2026-04-28T11:30:00Z"),
            LastDeployTime = DateTimeOffset.Parse("2026-04-28T09:00:00Z"),
-            Hierarchy =
-            [
-                new GalaxyHierarchyRow { GobjectId = 1, TagName = "Pump_001", BrowseName = "Pump_001", CategoryId = 10, IsArea = false, TemplateChain = ["$Pump"] },
-                new GalaxyHierarchyRow { GobjectId = 2, TagName = "Pump_002", BrowseName = "Pump_002", CategoryId = 10, IsArea = false, TemplateChain = ["$Pump"] },
-                new GalaxyHierarchyRow { GobjectId = 3, TagName = "Area_A", BrowseName = "Area_A", CategoryId = 13, IsArea = true, TemplateChain = ["$Area"] },
-            ],
-            Attributes =
-            [
-                new GalaxyAttributeRow { GobjectId = 1, AttributeName = "Speed", IsHistorized = true },
-                new GalaxyAttributeRow { GobjectId = 1, AttributeName = "Status", IsAlarm = true },
-            ],
+            DashboardSummary = new DashboardGalaxySummary(
+                DashboardGalaxyStatus.Healthy,
+                LastQueriedAt: DateTimeOffset.Parse("2026-04-28T11:30:00Z"),
+                LastSuccessAt: DateTimeOffset.Parse("2026-04-28T11:30:00Z"),
+                LastDeployTime: DateTimeOffset.Parse("2026-04-28T09:00:00Z"),
+                LastError: null,
+                ObjectCount: 3,
+                AreaCount: 1,
+                AttributeCount: 2,
+                HistorizedAttributeCount: 1,
+                AlarmAttributeCount: 1,
+                TopTemplates:
+                [
+                    new DashboardGalaxyTemplateUsage("$Pump", 2),
+                    new DashboardGalaxyTemplateUsage("$Area", 1),
+                ],
+                ObjectCategories:
+                [
+                    new DashboardGalaxyCategoryCount(10, "UserDefined", 2),
+                    new DashboardGalaxyCategoryCount(13, "Area", 1),
+                ]),
            ObjectCount = 3,
            AreaCount = 1,
            AttributeCount = 2,
@@ -238,6 +250,101 @@ public sealed class DashboardSnapshotServiceTests
    /// <summary>
    /// Verifies snapshot watcher cancels cleanly when subscriber cancels.
    /// </summary>
+    [Fact]
+    public void GetSnapshot_DoesNotSynchronouslyListApiKeys()
+    {
+        using GatewayMetrics metrics = new();
+        CountingApiKeyAdminStore apiKeyAdminStore = new();
+        DashboardSnapshotService service = CreateService(
+            new SessionRegistry(),
+            metrics,
+            apiKeyAdminStore: apiKeyAdminStore);
+
+        DashboardSnapshot snapshot = service.GetSnapshot();
+
+        Assert.Empty(snapshot.ApiKeys);
+        Assert.Equal(0, apiKeyAdminStore.ListCount);
+    }
+
+    [Fact]
+    public async Task WatchSnapshotsAsync_RefreshesApiKeySummariesBeforeSnapshot()
+    {
+        using GatewayMetrics metrics = new();
+        CountingApiKeyAdminStore apiKeyAdminStore = new(
+            new ApiKeyRecord(
+                KeyId: "operator01",
+                KeyPrefix: "mxgw_operator01",
+                SecretHash: [1, 2, 3],
+                DisplayName: "Operator",
+                Scopes: new HashSet<string>([GatewayScopes.MetadataRead], StringComparer.Ordinal),
+                Constraints: ApiKeyConstraints.Empty with
+                {
+                    BrowseSubtrees = ["Area1/*"],
+                },
+                CreatedUtc: DateTimeOffset.Parse("2026-04-28T12:00:00Z"),
+                LastUsedUtc: null,
+                RevokedUtc: null));
+        DashboardSnapshotService service = CreateService(
+            new SessionRegistry(),
+            metrics,
+            apiKeyAdminStore: apiKeyAdminStore);
+        using CancellationTokenSource cancellation = new(TimeSpan.FromSeconds(2));
+        await using IAsyncEnumerator<DashboardSnapshot> enumerator = service
+            .WatchSnapshotsAsync(cancellation.Token)
+            .GetAsyncEnumerator(cancellation.Token);
+
+        Assert.True(await enumerator.MoveNextAsync());
+        DashboardSnapshot snapshot = enumerator.Current;
+
+        DashboardApiKeySummary key = Assert.Single(snapshot.ApiKeys);
+        Assert.Equal("operator01", key.KeyId);
+        Assert.Equal(["Area1/*"], key.Constraints.BrowseSubtrees);
+        Assert.Equal(1, apiKeyAdminStore.ListCount);
+    }
+
+    [Fact]
+    public async Task WatchSnapshotsAsync_WhenApiKeyRefreshFails_ReusesPreviousSummaries()
+    {
+        using GatewayMetrics metrics = new();
+        SequencedApiKeyAdminStore apiKeyAdminStore = new(
+            new ApiKeyRecord(
+                KeyId: "operator01",
+                KeyPrefix: "mxgw_operator01",
+                SecretHash: [1, 2, 3],
+                DisplayName: "Operator",
+                Scopes: new HashSet<string>([GatewayScopes.MetadataRead], StringComparer.Ordinal),
+                Constraints: ApiKeyConstraints.Empty,
+                CreatedUtc: DateTimeOffset.Parse("2026-04-28T12:00:00Z"),
+                LastUsedUtc: null,
+                RevokedUtc: null));
+        DashboardSnapshotService service = CreateService(
+            new SessionRegistry(),
+            metrics,
+            new GatewayOptions
+            {
+                Dashboard = new DashboardOptions
+                {
+                    SnapshotIntervalMilliseconds = 1,
+                },
+            },
+            apiKeyAdminStore: apiKeyAdminStore);
+        using CancellationTokenSource cancellation = new(TimeSpan.FromSeconds(2));
+        await using IAsyncEnumerator<DashboardSnapshot> enumerator = service
+            .WatchSnapshotsAsync(cancellation.Token)
+            .GetAsyncEnumerator(cancellation.Token);
+
+        Assert.True(await enumerator.MoveNextAsync());
+        DashboardSnapshot first = enumerator.Current;
+        apiKeyAdminStore.FailNext = true;
+
+        Assert.True(await enumerator.MoveNextAsync());
+        DashboardSnapshot second = enumerator.Current;
+
+        Assert.Equal("operator01", Assert.Single(first.ApiKeys).KeyId);
+        Assert.Equal("operator01", Assert.Single(second.ApiKeys).KeyId);
+        Assert.Equal(2, apiKeyAdminStore.ListCount);
+    }
+
    [Fact]
    public async Task WatchSnapshotsAsync_WhenSubscriberCancels_DisposesCleanly()
    {
@@ -268,7 +375,8 @@ public sealed class DashboardSnapshotServiceTests
        SessionRegistry registry,
        GatewayMetrics metrics,
        GatewayOptions? options = null,
-        IGalaxyHierarchyCache? galaxyHierarchyCache = null)
+        IGalaxyHierarchyCache? galaxyHierarchyCache = null,
+        IApiKeyAdminStore? apiKeyAdminStore = null)
    {
        GatewayOptions resolvedOptions = options ?? new GatewayOptions
        {
@@ -284,6 +392,7 @@ public sealed class DashboardSnapshotServiceTests
            metrics,
            configurationProvider,
            galaxyHierarchyCache ?? new StubGalaxyHierarchyCache(GalaxyHierarchyCacheEntry.Empty),
+            apiKeyAdminStore ?? new FakeApiKeyAdminStore(),
            Options.Create(resolvedOptions));
    }

@@ -309,6 +418,64 @@ public sealed class DashboardSnapshotServiceTests
        public Task WaitForFirstLoadAsync(CancellationToken cancellationToken) => Task.CompletedTask;
    }

+    private class FakeApiKeyAdminStore : IApiKeyAdminStore
+    {
+        public Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken)
+        {
+            return Task.CompletedTask;
+        }
+
+        public virtual Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        {
+            return Task.FromResult<IReadOnlyList<ApiKeyRecord>>([]);
+        }
+
+        public Task<bool> RevokeAsync(
+            string keyId,
+            DateTimeOffset revokedUtc,
+            CancellationToken cancellationToken)
+        {
+            return Task.FromResult(false);
+        }
+
+        public Task<bool> RotateAsync(
+            string keyId,
+            byte[] secretHash,
+            DateTimeOffset rotatedUtc,
+            CancellationToken cancellationToken)
+        {
+            return Task.FromResult(false);
+        }
+    }
+
+    private class CountingApiKeyAdminStore(params ApiKeyRecord[] records) : FakeApiKeyAdminStore
+    {
+        public int ListCount { get; protected set; }
+
+        public override Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        {
+            ListCount++;
+            return Task.FromResult<IReadOnlyList<ApiKeyRecord>>(records);
+        }
+    }
+
+    private sealed class SequencedApiKeyAdminStore(ApiKeyRecord record) : CountingApiKeyAdminStore(record)
+    {
+        public bool FailNext { get; set; }
+
+        public override Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        {
+            if (FailNext)
+            {
+                FailNext = false;
+                ListCount++;
+                throw new InvalidOperationException("Simulated SQLite failure.");
+            }
+
+            return base.ListAsync(cancellationToken);
+        }
+    }
+
    private static GatewaySession CreateSession(
        string sessionId,
        string? clientIdentity,
@@ -1,4 +1,5 @@
 using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
@@ -54,6 +55,20 @@ public sealed class GatewayApplicationTests
    }

    /// <summary>Verifies that Build does not map dashboard routes when the dashboard is disabled.</summary>
+    [Fact]
+    public void Build_WhenDashboardEnabled_DashboardRoutesAllowAnonymousAccess()
+    {
+        WebApplication app = GatewayApplication.Build([]);
+        IReadOnlyList<RouteEndpoint> endpoints = GetRouteEndpoints(app)
+            .Where(endpoint => endpoint.RoutePattern.RawText?.StartsWith(
+                "/dashboard",
+                StringComparison.Ordinal) == true)
+            .ToArray();
+
+        Assert.NotEmpty(endpoints);
+        Assert.DoesNotContain(endpoints, endpoint => endpoint.Metadata.GetMetadata<IAuthorizeData>() is not null);
+    }
+
    [Fact]
    public void Build_WhenDashboardDisabled_DoesNotMapDashboardRoutes()
    {
@@ -89,6 +104,14 @@ public sealed class GatewayApplicationTests
        "MxGateway:Dashboard:PathBase",
        "dashboard",
        "MxGateway:Dashboard:PathBase must start with '/'.")]
+    [InlineData(
+        "MxGateway:Ldap:RequiredGroup",
+        "",
+        "MxGateway:Ldap:RequiredGroup is required when LDAP login is enabled.")]
+    [InlineData(
+        "MxGateway:Ldap:AllowInsecureLdap",
+        "false",
+        "MxGateway:Ldap:AllowInsecureLdap must be true when UseTls is false.")]
    public async Task StartAsync_InvalidGatewayConfiguration_FailsStartup(
        string key,
        string value,
@@ -8,6 +8,7 @@ using MxGateway.Contracts.Proto;
 using MxGateway.Server.Configuration;
 using MxGateway.Server.Grpc;
 using MxGateway.Server.Metrics;
+using MxGateway.Server.Security.Authentication;
 using MxGateway.Server.Security.Authorization;
 using MxGateway.Server.Sessions;
 using MxGateway.Server.Workers;
@@ -178,6 +179,7 @@ public sealed class GatewayEndToEndFakeWorkerSmokeTests
            Service = new MxAccessGatewayService(
                sessionManager,
                new GatewayRequestIdentityAccessor(),
+                new AllowAllConstraintEnforcer(),
                new MxAccessGrpcRequestValidator(),
                mapper,
                eventStreamService,
@@ -529,4 +531,33 @@ public sealed class GatewayEndToEndFakeWorkerSmokeTests
            throw new NotSupportedException();
        }
    }
+
+    private sealed class AllowAllConstraintEnforcer : IConstraintEnforcer
+    {
+        public Task<ConstraintFailure?> CheckReadTagAsync(
+            ApiKeyIdentity? identity,
+            string tagAddress,
+            CancellationToken cancellationToken) => Task.FromResult<ConstraintFailure?>(null);
+
+        public Task<ConstraintFailure?> CheckReadHandleAsync(
+            ApiKeyIdentity? identity,
+            GatewaySession session,
+            int serverHandle,
+            int itemHandle,
+            CancellationToken cancellationToken) => Task.FromResult<ConstraintFailure?>(null);
+
+        public Task<ConstraintFailure?> CheckWriteHandleAsync(
+            ApiKeyIdentity? identity,
+            GatewaySession session,
+            int serverHandle,
+            int itemHandle,
+            CancellationToken cancellationToken) => Task.FromResult<ConstraintFailure?>(null);
+
+        public Task RecordDenialAsync(
+            ApiKeyIdentity? identity,
+            string commandKind,
+            string target,
+            ConstraintFailure failure,
+            CancellationToken cancellationToken) => Task.CompletedTask;
+    }
 }
@@ -237,6 +237,7 @@ public sealed class MxAccessGatewayServiceTests
        return new MxAccessGatewayService(
            sessionManager,
            identityAccessor ?? new GatewayRequestIdentityAccessor(),
+            new AllowAllConstraintEnforcer(),
            new MxAccessGrpcRequestValidator(),
            new MxAccessGrpcMapper(),
            new FakeEventStreamService(sessionManager),
@@ -445,6 +446,35 @@ public sealed class MxAccessGatewayServiceTests
        }
    }

+    private sealed class AllowAllConstraintEnforcer : IConstraintEnforcer
+    {
+        public Task<ConstraintFailure?> CheckReadTagAsync(
+            ApiKeyIdentity? identity,
+            string tagAddress,
+            CancellationToken cancellationToken) => Task.FromResult<ConstraintFailure?>(null);
+
+        public Task<ConstraintFailure?> CheckReadHandleAsync(
+            ApiKeyIdentity? identity,
+            GatewaySession session,
+            int serverHandle,
+            int itemHandle,
+            CancellationToken cancellationToken) => Task.FromResult<ConstraintFailure?>(null);
+
+        public Task<ConstraintFailure?> CheckWriteHandleAsync(
+            ApiKeyIdentity? identity,
+            GatewaySession session,
+            int serverHandle,
+            int itemHandle,
+            CancellationToken cancellationToken) => Task.FromResult<ConstraintFailure?>(null);
+
+        public Task RecordDenialAsync(
+            ApiKeyIdentity? identity,
+            string commandKind,
+            string target,
+            ConstraintFailure failure,
+            CancellationToken cancellationToken) => Task.CompletedTask;
+    }
+
    private sealed class FakeWorkerClient(int processId) : IWorkerClient
    {
        /// <inheritdoc />
@@ -34,6 +34,21 @@ public sealed class SessionManagerTests
    }

    /// <summary>Verifies that opening a session generates a correlation ID from the client name and session ID.</summary>
+    [Fact]
+    public async Task OpenSessionAsync_SetsInitialDefaultLease()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.Parse("2026-04-29T10:00:00Z"));
+        GatewayOptions options = CreateOptions(defaultLeaseSeconds: 1800);
+        SessionManager manager = CreateManager(
+            new FakeSessionWorkerClientFactory(new FakeWorkerClient()),
+            options: options,
+            timeProvider: clock);
+
+        GatewaySession session = await manager.OpenSessionAsync(CreateOpenRequest(), "client-1", CancellationToken.None);
+
+        Assert.Equal(clock.GetUtcNow() + TimeSpan.FromMinutes(30), session.LeaseExpiresAt);
+    }
+
    [Fact]
    public async Task OpenSessionAsync_GeneratesClientCorrelationIdFromClientNameAndSessionId()
    {
@@ -82,6 +97,32 @@ public sealed class SessionManagerTests
    }

    /// <summary>Verifies that bulk subscribe forwards the command and returns subscription results.</summary>
+    [Fact]
+    public async Task InvokeAsync_WhenSessionReady_RefreshesLease()
+    {
+        GatewaySession session = new(
+            "session-lease-refresh",
+            "mxaccess",
+            "mxaccess-gateway-1-session-lease-refresh",
+            "nonce",
+            "client-1",
+            "test-session",
+            "client-correlation-1",
+            TimeSpan.FromSeconds(30),
+            TimeSpan.FromSeconds(5),
+            TimeSpan.FromSeconds(5),
+            TimeSpan.FromMinutes(30),
+            DateTimeOffset.UtcNow - TimeSpan.FromHours(1));
+        session.AttachWorkerClient(new FakeWorkerClient());
+        session.MarkReady();
+        DateTimeOffset? initialLease = session.LeaseExpiresAt;
+
+        await session.InvokeAsync(CreateCommand(MxCommandKind.Ping), CancellationToken.None);
+
+        Assert.True(session.LeaseExpiresAt > initialLease);
+        Assert.True(session.LeaseExpiresAt > DateTimeOffset.UtcNow);
+    }
+
    [Fact]
    public async Task GatewaySessionSubscribeBulkAsync_ForwardsOneBulkCommandAndReturnsResults()
    {
@@ -322,6 +363,23 @@ public sealed class SessionManagerTests
    }

    /// <summary>Verifies that shutdown closes all registered sessions.</summary>
+    [Fact]
+    public async Task CloseExpiredLeasesAsync_DoesNotCloseActiveEventSubscriber()
+    {
+        FakeWorkerClient workerClient = new();
+        SessionManager manager = CreateManager(new FakeSessionWorkerClientFactory(workerClient));
+        GatewaySession session = await manager.OpenSessionAsync(CreateOpenRequest(), "client-1", CancellationToken.None);
+        DateTimeOffset now = DateTimeOffset.UtcNow;
+        session.ExtendLease(now.AddSeconds(-1));
+        using IDisposable eventSubscriber = session.AttachEventSubscriber(allowMultipleSubscribers: false);
+
+        int closedCount = await manager.CloseExpiredLeasesAsync(now, CancellationToken.None);
+
+        Assert.Equal(0, closedCount);
+        Assert.Equal(SessionState.Ready, session.State);
+        Assert.Equal(0, workerClient.ShutdownCount);
+    }
+
    [Fact]
    public async Task ShutdownAsync_ClosesAllRegisteredSessions()
    {
@@ -353,16 +411,20 @@ public sealed class SessionManagerTests
        ISessionWorkerClientFactory factory,
        ISessionRegistry? registry = null,
        GatewayMetrics? metrics = null,
-        GatewayOptions? options = null)
+        GatewayOptions? options = null,
+        TimeProvider? timeProvider = null)
    {
        return new SessionManager(
            registry ?? new SessionRegistry(),
            factory,
            Options.Create(options ?? CreateOptions()),
-            metrics ?? new GatewayMetrics());
+            metrics ?? new GatewayMetrics(),
+            timeProvider);
    }

-    private static GatewayOptions CreateOptions(int maxSessions = 64)
+    private static GatewayOptions CreateOptions(
+        int maxSessions = 64,
+        int defaultLeaseSeconds = 1800)
    {
        return new GatewayOptions
        {
@@ -370,6 +432,7 @@ public sealed class SessionManagerTests
            {
                DefaultCommandTimeoutSeconds = 30,
                MaxSessions = maxSessions,
+                DefaultLeaseSeconds = defaultLeaseSeconds,
            },
            Worker = new WorkerOptions
            {
@@ -586,4 +649,11 @@ public sealed class SessionManagerTests
            ShutdownReleased.TrySetResult();
        }
    }
+
+    private sealed class ManualTimeProvider(DateTimeOffset start) : TimeProvider
+    {
+        private DateTimeOffset _now = start;
+
+        public override DateTimeOffset GetUtcNow() => _now;
+    }
 }
@@ -143,6 +143,36 @@ public sealed class WorkerClientTests
    }

    /// <summary>Verifies that the read loop faults the client when the pipe disconnects.</summary>
+    [Fact]
+    public async Task ReadLoop_WhenClientFaults_KillsOwnedWorkerProcess()
+    {
+        await using PipePair pipePair = await PipePair.CreateAsync();
+        FakeWorkerProcess process = new();
+        await using WorkerClient client = CreateClient(
+            pipePair,
+            new WorkerClientOptions
+            {
+                EventChannelCapacity = 1,
+                HeartbeatGrace = TimeSpan.FromSeconds(30),
+                HeartbeatCheckInterval = TimeSpan.FromSeconds(30),
+            },
+            processHandle: CreateProcessHandle(process));
+        await CompleteHandshakeAsync(client, pipePair);
+
+        await pipePair.WorkerWriter.WriteAsync(
+            CreateEventEnvelope(sequence: 11, MxEventFamily.OnDataChange));
+        await pipePair.WorkerWriter.WriteAsync(
+            CreateEventEnvelope(sequence: 12, MxEventFamily.OnDataChange));
+
+        await WaitUntilAsync(
+            () => client.State == WorkerClientState.Faulted,
+            TestTimeout);
+
+        Assert.Equal(1, process.KillCount);
+        Assert.True(process.KillEntireProcessTree);
+        Assert.True(process.HasExited);
+    }
+
    [Fact]
    public async Task ReadLoop_WhenPipeDisconnects_FaultsClient()
    {
@@ -200,6 +230,20 @@ public sealed class WorkerClientTests
    }

    /// <summary>Verifies that the read loop updates the last heartbeat and worker process when a heartbeat arrives.</summary>
+    [Fact]
+    public async Task DisposeAsync_WhenOwnedWorkerStillRuns_KillsProcessBeforeDisposing()
+    {
+        await using PipePair pipePair = await PipePair.CreateAsync();
+        FakeWorkerProcess process = new();
+        WorkerClient client = CreateClient(pipePair, processHandle: CreateProcessHandle(process));
+
+        await client.DisposeAsync().AsTask().WaitAsync(TestTimeout);
+
+        Assert.Equal(1, process.KillCount);
+        Assert.True(process.KillEntireProcessTree);
+        Assert.True(process.Disposed);
+    }
+
    [Fact]
    public async Task ReadLoop_WhenHeartbeatArrives_UpdatesLastHeartbeatAndWorkerProcess()
    {
@@ -243,18 +287,28 @@ public sealed class WorkerClientTests
    private static WorkerClient CreateClient(
        PipePair pipePair,
        WorkerClientOptions? options = null,
-        GatewayMetrics? metrics = null)
+        GatewayMetrics? metrics = null,
+        WorkerProcessHandle? processHandle = null)
    {
        WorkerFrameProtocolOptions frameOptions = new(SessionId);
        WorkerClientConnection connection = new(
            SessionId,
            Nonce,
            pipePair.GatewayStream,
-            frameOptions);
+            frameOptions,
+            processHandle);

        return new WorkerClient(connection, options, metrics);
    }

+    private static WorkerProcessHandle CreateProcessHandle(FakeWorkerProcess process)
+    {
+        return new WorkerProcessHandle(
+            process,
+            new WorkerProcessCommandLine("MxGateway.Worker.exe", []),
+            DateTimeOffset.UtcNow);
+    }
+
    private static async Task CompleteHandshakeAsync(
        WorkerClient client,
        PipePair pipePair)
@@ -454,4 +508,40 @@ public sealed class WorkerClientTests
            await GatewayStream.DisposeAsync();
        }
    }
+
+    private sealed class FakeWorkerProcess : IWorkerProcess
+    {
+        private readonly TaskCompletionSource _exited = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        public int Id { get; } = WorkerProcessId;
+
+        public bool HasExited { get; private set; }
+
+        public int? ExitCode { get; private set; }
+
+        public int KillCount { get; private set; }
+
+        public bool KillEntireProcessTree { get; private set; }
+
+        public bool Disposed { get; private set; }
+
+        public ValueTask WaitForExitAsync(CancellationToken cancellationToken)
+        {
+            return new ValueTask(_exited.Task.WaitAsync(cancellationToken));
+        }
+
+        public void Kill(bool entireProcessTree)
+        {
+            KillCount++;
+            KillEntireProcessTree = entireProcessTree;
+            HasExited = true;
+            ExitCode = -1;
+            _exited.TrySetResult();
+        }
+
+        public void Dispose()
+        {
+            Disposed = true;
+        }
+    }
 }