Merge remote-tracking branch 'origin/main' into agent-1/issue-16-implement-blazor-server-dashboard

Issue #19: gateway end-to-end smoke with fake worker

docs/Contracts.md

@@ -0,0 +1,46 @@
+# Protobuf Contracts
+
+The contracts project contains the public gRPC API and the gateway-to-worker
+IPC messages. The `.proto` files are the source of truth; generated C# files are
+recreated by the contracts project build.
+
+## Files
+
+`src/MxGateway.Contracts/Protos/mxaccess_gateway.proto` defines the public
+`MxAccessGateway` gRPC service, command payloads, command replies, event DTOs,
+`MxValue`, `MxArray`, and `MxStatusProxy`.
+
+`src/MxGateway.Contracts/Protos/mxaccess_worker.proto` defines the named-pipe
+worker IPC envelope and control messages. It imports
+`mxaccess_gateway.proto` so the worker and gateway use the same command, reply,
+event, value, and status shapes.
+
+Generated C# output is written to `src/MxGateway.Contracts/Generated/`. Do not
+hand-edit generated files.
+
+## Generation
+
+Run the contracts build to regenerate C# protobuf and gRPC code:
+
+```bash
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
+Run the focused contract tests after changing either `.proto` file:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter ProtobufContractRoundTripTests
+```
+
+The full solution build also regenerates the C# contracts before compiling
+gateway and test projects:
+
+```bash
+dotnet build src/MxGateway.sln
+```
+
+## Related Documentation
+
+- [Gateway Process Detailed Design](./gateway-process-design.md)
+- [MXAccess Worker Instance Detailed Design](./mxaccess-worker-instance-design.md)
+- [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)

docs/GatewayTesting.md

@@ -0,0 +1,58 @@
+# Gateway Testing
+
+Gateway tests run without installed MXAccess by using fake workers, fake
+transports, and in-process gRPC service fakes. Live MXAccess verification belongs
+in opt-in integration tests because it depends on installed COM components and
+provider state.
+
+## Fake Worker Harness
+
+`FakeWorkerHarness` in `src/MxGateway.Tests/Gateway/Workers/Fakes/` provides an
+in-process worker side for named-pipe IPC tests. It uses the same
+`WorkerFrameReader`, `WorkerFrameWriter`, and `WorkerEnvelope` contract as the
+gateway so tests exercise real frame validation and worker-client state changes.
+
+Use the harness when a gateway or session test needs worker behavior without
+starting `MxGateway.Worker.exe` or loading MXAccess COM. The harness scripts:
+
+- `WorkerHello` and `WorkerReady` startup,
+- command replies with matching correlation ids,
+- ordered `WorkerEvent` frames,
+- `WorkerFault` frames,
+- shutdown acknowledgements,
+- malformed protobuf payloads and oversized frame headers,
+- slow or hung workers by withholding a reply.
+
+Session-level tests can connect the harness to the pipe created by
+`SessionWorkerClientFactory` with `ConnectToGatewayPipeAsync`. Lower-level
+`WorkerClient` tests can use `CreateConnectedPairAsync` to create both pipe ends
+inside the test.
+
+`GatewayEndToEndFakeWorkerSmokeTests` composes the real gRPC service,
+`SessionManager`, `SessionWorkerClientFactory`, `WorkerClient`, and
+`EventStreamService` with a scripted fake worker launcher. The smoke test covers
+`OpenSession`, `Register`, `AddItem`, `Advise`, one streamed `OnDataChange`
+event, and `CloseSession` without loading MXAccess COM.
+
+## Focused Commands
+
+Run the fake worker tests after changing gateway worker IPC, session startup, or
+event streaming behavior:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~FakeWorkerHarnessTests
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~SessionWorkerClientFactoryFakeWorkerTests
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
+```
+
+Run the gateway test project after shared gateway test infrastructure changes:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj
+```
+
+## Related Documentation
+
+- [Gateway Process Design](./gateway-process-design.md)
+- [Worker Frame Protocol](./WorkerFrameProtocol.md)
+- [MXAccess Worker Instance Detailed Design](./mxaccess-worker-instance-design.md)

docs/WorkerFrameProtocol.md

@@ -0,0 +1,54 @@
+# Worker Frame Protocol
+
+The gateway uses the worker frame protocol to move `WorkerEnvelope` protobuf
+messages over a bidirectional named pipe. The frame layer is deliberately small:
+it handles message boundaries, size limits, protobuf parsing, and envelope
+validation before higher-level worker client code routes commands, replies,
+events, and faults.
+
+## Frame Format
+
+Each frame starts with a four-byte little-endian unsigned payload length,
+followed by the serialized `WorkerEnvelope` payload:
+
+```text
+uint32 little-endian payload_length
+payload_length bytes protobuf WorkerEnvelope
+```
+
+The reader rejects zero-length payloads and payloads larger than the configured
+maximum before allocating the payload buffer. The default maximum is 16 MiB,
+matching the gateway process design.
+
+## Envelope Validation
+
+`WorkerFrameReader` and `WorkerFrameWriter` validate each envelope against the
+owning session before returning or writing it:
+
+- `protocol_version` must match the configured worker protocol version,
+- `session_id` must match the owning gateway session,
+- the envelope must contain one typed `body` value.
+
+Protocol violations throw `WorkerFrameProtocolException` with a
+`WorkerFrameProtocolErrorCode` so callers can distinguish malformed frames,
+oversized frames, protocol version mismatches, and session mismatches.
+
+## Verification
+
+Run the focused tests after changing the frame protocol:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerFrameProtocolTests
+```
+
+Run the gateway build because the frame protocol is part of
+`MxGateway.Server`:
+
+```bash
+dotnet build src/MxGateway.Server/MxGateway.Server.csproj
+```
+
+## Related Documentation
+
+- [Gateway Process Detailed Design](./gateway-process-design.md)
+- [Protobuf Contracts](./Contracts.md)

docs/WorkerProcessLauncher.md

@@ -0,0 +1,62 @@
+# Worker Process Launcher
+
+The gateway uses `WorkerProcessLauncher` to validate and start one worker
+process for a gateway session. The launcher owns process start semantics only;
+pipe handshaking and `WorkerReady` validation remain part of the worker client
+startup path.
+
+## Launch Inputs
+
+`WorkerProcessLaunchRequest` carries the per-session bootstrap values:
+
+- `SessionId`,
+- `PipeName`,
+- `ProtocolVersion`,
+- `Nonce`,
+- optional `PipeReservation` cleanup handle.
+
+The launcher passes `SessionId`, `PipeName`, and `ProtocolVersion` as command
+line arguments:
+
+```text
+--session-id <sessionId> --pipe-name <pipeName> --protocol-version <version>
+```
+
+The launcher sets the nonce through the `MXGATEWAY_WORKER_NONCE` environment
+variable. The nonce is not included in `WorkerProcessCommandLine` so logs and
+diagnostics can report the launch command without exposing the secret.
+
+## Validation And Cleanup
+
+Before starting the process, the launcher validates that the configured worker
+path exists, has a `.exe` extension, contains a valid Windows Portable
+Executable header, and matches the configured `RequiredArchitecture`.
+
+After the process starts, `IWorkerStartupProbe` waits for startup readiness.
+The default probe only verifies that the worker did not exit immediately. The
+worker client replaces this probe when pipe connection, hello, and
+`WorkerReady` handling are implemented.
+
+If startup fails or exceeds `WorkerOptions.StartupTimeoutSeconds`, the launcher
+kills the worker process tree, disposes the process handle, disposes the
+optional pipe reservation, records a worker kill metric, and reports a
+`WorkerProcessLaunchException`.
+
+## Verification
+
+Run the focused launcher tests after changing process launch behavior:
+
+```bash
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerProcessLauncherTests
+```
+
+Run the gateway build because the launcher is part of `MxGateway.Server`:
+
+```bash
+dotnet build src/MxGateway.Server/MxGateway.Server.csproj
+```
+
+## Related Documentation
+
+- [Gateway Process Detailed Design](./gateway-process-design.md)
+- [Worker Frame Protocol](./WorkerFrameProtocol.md)

docs/gateway-dashboard-design.md

@@ -34,9 +34,13 @@ SignalR circuit. Bootstrap is sufficient for a basic dashboard.
 
 ## Hosting Model
 
-The dashboard is hosted by `MxGateway.Server` alongside the gRPC API.
+The dashboard is hosted by `MxGateway.Server` alongside the gRPC API. When
+`MxGateway:Dashboard:Enabled` is `true`, `MapGatewayDashboard()` maps the
+configured `Dashboard:PathBase` to the Blazor Server app and maps the login,
+logout, and access-denied HTTP endpoints beside it. When dashboard hosting is
+disabled, those routes are not mapped.
 
-Suggested endpoint layout:
+Endpoint layout:
 
 ```text
 /dashboard
@@ -45,7 +49,7 @@ Suggested endpoint layout:
 /dashboard/workers
 /dashboard/events
 /dashboard/settings
-/_blazor
+/dashboard/_blazor
 ```
 
 The app should redirect `/` to `/dashboard` only if the deployment wants the
@@ -59,9 +63,10 @@ MxGateway.Server
     Components/
       App.razor
       Routes.razor
+      DashboardPageBase.cs
+      DashboardDisplay.cs
       Layout/
         DashboardLayout.razor
-        NavMenu.razor
       Pages/
         DashboardHome.razor
         SessionsPage.razor
@@ -69,26 +74,21 @@ MxGateway.Server
         WorkersPage.razor
         EventsPage.razor
         SettingsPage.razor
-      Components/
+      Shared/
         MetricCard.razor
-        SessionTable.razor
-        WorkerTable.razor
-        EventRatePanel.razor
+        StatusBadge.razor
         FaultList.razor
-    Services/
-      DashboardSnapshotService.cs
-      DashboardUpdateHub.cs
-      DashboardAuthorization.cs
-    Models/
-      DashboardSnapshot.cs
-      SessionSummary.cs
-      WorkerSummary.cs
-      MetricSummary.cs
+    DashboardSnapshotService.cs
+    DashboardAuthorizationHandler.cs
+    DashboardAuthenticator.cs
+    DashboardSnapshot.cs
+    DashboardSessionSummary.cs
+    DashboardWorkerSummary.cs
+    DashboardMetricSummary.cs
 ```
 
-`DashboardUpdateHub` here means an internal application update service, not a
-separate public SignalR hub unless implementation proves one is needed. Blazor
-Server already uses SignalR for UI circuits.
+Blazor Server provides the SignalR circuit for UI updates. The implementation
+does not add a separate public dashboard hub.
 
 ## Dashboard Data Source
 
@@ -105,6 +105,12 @@ Do not let Razor components directly mutate gateway session or worker objects.
 Create a small read-only dashboard service that projects gateway state into
 plain DTOs.
 
+`GatewayMetrics.GetSnapshot()` is the metrics input for the first dashboard
+projection. It carries current session and worker gauges, command and event
+counters, queue depth, and fault totals. The dashboard reads that snapshot
+instead of reading raw `Meter` instruments because exporter configuration is an
+operations concern, not a UI dependency.
+
 Suggested service:
 
 ```csharp
@@ -131,7 +137,7 @@ gateway internals.
 
 Use Blazor Server component state updates for real-time dashboard refresh.
 
-Recommended pattern:
+Implemented pattern:
 
 1. Page/component subscribes to `WatchSnapshotsAsync`.
 2. Snapshot service emits updates from a bounded channel or timer.
@@ -141,10 +147,8 @@ Recommended pattern:
 
 Default update cadence:
 
-- immediate update on session create/close/fault,
-- immediate update on worker fault,
 - periodic metrics refresh every 1 second,
-- event-rate windows updated every 1 second.
+- event counters update on the next snapshot tick.
 
 Avoid pushing every MXAccess data-change event to the dashboard. Aggregate event
 counts and rates instead.
@@ -251,19 +255,18 @@ Do not show API key secrets or pepper values.
 
 ## Authentication And Authorization
 
-Dashboard access should use the same API-key authentication model as gRPC where
+Dashboard access uses the same API-key authentication model as gRPC where
 practical.
 
-Recommended v1 behavior:
+Implemented v1 behavior:
 
-- dashboard disabled by default unless configured,
 - when enabled, require API key auth,
 - require `admin` scope for dashboard access,
-- accept API key through a secure cookie established by a simple login form, or
-  through reverse-proxy/header configuration for local deployments,
-- do not put API keys in query strings.
+- accept API key through a secure cookie established by a simple login form,
+- do not put API keys in query strings,
+- validate anti-forgery tokens for login and logout posts.
 
-Simplest implementation path:
+The implementation path is:
 
 1. Add `/dashboard/login`.
 2. User submits API key over HTTPS.
@@ -275,6 +278,13 @@ Simplest implementation path:
 For local development, allow an explicit `Dashboard:AllowAnonymousLocalhost`
 option. It must default to false.
 
+`DashboardAuthenticator` keeps API-key validation outside UI components. It
+formats the submitted key as a bearer authorization header for
+`IApiKeyVerifier`, rejects non-admin keys when `Dashboard:RequireAdminScope` is
+enabled, and creates the dashboard cookie principal without storing raw API key
+material. `DashboardAuthorizationHandler` enforces the cookie, admin-scope, and
+explicit loopback bypass decisions for all protected dashboard routes.
+
 ## Configuration
 
 Suggested configuration:
@@ -308,7 +318,9 @@ Suggested configuration:
 
 ## Styling
 
-Use Bootstrap utility classes and a small local stylesheet.
+The dashboard serves Bootstrap 5.3.3 assets from
+`src/MxGateway.Server/wwwroot/lib/bootstrap/` and local layout/status styling
+from `src/MxGateway.Server/wwwroot/css/dashboard.css`.
 
 Recommended visual language:
 
@@ -349,16 +361,18 @@ Integration tests should verify:
 
 ## Initial Implementation Slice
 
-The first dashboard slice should implement:
+The first dashboard slice implements:
 
 1. Blazor Server hosting in `MxGateway.Server`.
-2. Bootstrap static assets.
+2. local Bootstrap static assets.
 3. dashboard configuration binding.
 4. dashboard auth using API key login and HTTP-only cookie.
 5. read-only `DashboardSnapshotService`.
 6. home page with metric cards.
-7. sessions page with active session table.
+7. sessions page with active session table and session details.
 8. workers page with worker table.
-9. 1-second realtime refresh through Blazor Server.
-10. redaction tests for secrets.
-
+9. events page with aggregate counters.
+10. settings page with redacted effective configuration.
+11. periodic realtime refresh through Blazor Server.
+12. route-mapping tests, disabled-dashboard tests, auth tests, and snapshot
+    projection/redaction tests.

docs/gateway-process-design.md

@@ -64,8 +64,8 @@ MxGateway.Server
   Configuration
   Grpc
     MxAccessGatewayService
-    RequestReplyMapper
-    EventMapper
+    MxAccessGrpcRequestValidator
+    MxAccessGrpcMapper
   Dashboard
     Pages
     Components
@@ -105,6 +105,15 @@ service MxAccessGateway {
 }
 ```
 
+`MxAccessGatewayService` implements these public RPCs in the gateway process.
+It validates public requests with `MxAccessGrpcRequestValidator`, delegates
+session lifecycle and command routing to `ISessionManager`, and maps worker
+command replies and events through `MxAccessGrpcMapper`. Session lookup,
+validation, and worker transport failures become gRPC status errors. MXAccess
+method replies that reached the worker remain `MxCommandReply` payloads so
+HRESULT values, status arrays, and method-specific reply fields survive
+transport boundaries.
+
 Add this later only after the command and event model is stable:
 
 ```protobuf
@@ -197,13 +206,23 @@ accounting and a clear fan-out policy.
 Behavior:
 
 1. Validate session id and authorize event access.
-2. Attach a stream cursor to the session event channel.
-3. Send events in worker sequence order.
-4. Stop on client cancellation, session close, or session fault.
-5. Emit a terminal status when the session faults if gRPC status alone cannot
+2. Attach the single active subscriber lease for the session.
+3. Read worker events into a bounded public stream queue.
+4. Send events in worker sequence order.
+5. Stop on client cancellation, session close, or session fault.
+6. Emit a terminal status when the session faults if gRPC status alone cannot
    preserve the required details.
 
-The gateway must not reorder events from one worker.
+`EventStreamService` owns subscriber tracking and public stream backpressure.
+The default policy allows one active subscriber per session. A second subscriber
+is rejected with `EventSubscriberAlreadyActive`. Stream cancellation releases
+the subscriber lease so a later stream can attach to the session.
+
+The gateway must not reorder events from one worker. `EventStreamService` writes
+mapped events to a bounded first-in, first-out queue and faults the session with
+`EventQueueOverflow` if the queue fills. The gateway does not synthesize
+`OperationComplete`; it forwards that family only when the worker reports a
+native MXAccess `OperationComplete` event.
 
 ## Web Dashboard
 
@@ -330,6 +349,20 @@ The worker remains authoritative for MXAccess handles. The gateway may keep a
 shadow state for diagnostics, but it must not invent, rewrite, or recycle
 MXAccess handles.
 
+`SessionManager` owns the current in-memory session registry. It allocates a
+session id, creates the worker pipe name and nonce, registers the session before
+worker startup, and removes the session if startup fails. A successful
+`OpenSession` attaches the ready `IWorkerClient` and transitions the session to
+`Ready`.
+
+Only `Ready` sessions accept command and event operations. `CloseSession` is
+idempotent for sessions still known to the registry: the first close shuts down
+the worker, and later closes return the final `Closed` state. Lease handling is
+exposed as a session hook so a monitor can close expired sessions without
+embedding lease policy in the worker client. Gateway shutdown walks the
+registry, closes each known session, and kills a worker if graceful shutdown
+fails.
+
 ## Worker Launch
 
 The gateway should launch the worker using explicit configuration:
@@ -360,6 +393,15 @@ Before launch, validate:
 - worker file version or product version is acceptable,
 - worker is expected to be x86.
 
+`WorkerProcessLauncher` implements the first validation layer now: it resolves
+the worker executable path, requires a `.exe`, validates the Windows Portable
+Executable header, and verifies the configured processor architecture. It passes
+only `--session-id`, `--pipe-name`, and `--protocol-version` on the command
+line. The per-session nonce is set through `MXGATEWAY_WORKER_NONCE` so the
+command line remains safe to log. Startup failures and startup timeouts kill and
+dispose the worker process and the pre-created pipe reservation before the
+session manager observes the failure.
+
 ## Worker IPC
 
 The gateway creates the pipe server before launching the worker.
@@ -402,7 +444,7 @@ session ids as protocol faults and close the session.
 
 `WorkerClient` is the gateway-side object that owns one worker connection.
 
-Suggested public shape:
+Current public shape:
 
 ```csharp
 public interface IWorkerClient : IAsyncDisposable
@@ -410,6 +452,7 @@ public interface IWorkerClient : IAsyncDisposable
     string SessionId { get; }
     int? ProcessId { get; }
     WorkerClientState State { get; }
+    DateTimeOffset LastHeartbeatAt { get; }
 
     Task StartAsync(CancellationToken cancellationToken);
     Task<WorkerCommandReply> InvokeAsync(
@@ -429,12 +472,17 @@ Internally it owns:
 - pipe stream,
 - read loop,
 - write loop,
-- bounded outbound command/control channel,
+- outbound command/control channel serialized by the write loop,
 - bounded inbound event channel,
 - pending command dictionary keyed by correlation id,
 - heartbeat monitor,
 - terminal fault source.
 
+`StartAsync` sends `GatewayHello`, verifies the `WorkerHello` protocol version
+and nonce, waits for `WorkerReady`, and only then exposes `Ready` state. The
+read loop starts after readiness so the handshake has a single owner for its
+ordered frames.
+
 ### Read Loop
 
 The read loop:
@@ -546,7 +594,8 @@ worker MXAccess event
   -> worker outbound event queue
   -> worker pipe writer
   -> gateway read loop
-  -> session event channel
+  -> worker client event queue
+  -> EventStreamService bounded stream queue
   -> gRPC StreamEvents
 ```
 
@@ -560,13 +609,15 @@ The gateway should record:
 
 Default backpressure policy for parity testing should be fail-fast:
 
-1. If the session event channel fills, fault the session.
+1. If the worker client event queue fills, fault the worker client.
+2. If the public stream queue fills, fault the gateway session.
 2. Preserve the overflow details in logs and metrics.
 3. Do not silently drop data-change events.
 
-Do not set a production event-rate target before measurement. Emit event rate,
-queue depth, stream send latency, and overflow metrics. Later production modes
-may support explicit coalescing by item handle as an opt-in behavior.
+Do not set a production event-rate target before measurement. `GatewayMetrics`
+records received event counts by family, queue depth, stream disconnects, and
+overflow counts. Later production modes may support explicit coalescing by item
+handle as an opt-in behavior.
 
 The gateway should not synthesize `OperationComplete` from write completion,
 command replies, ASB completion queues, or completion-only status frames. Forward
@@ -589,6 +640,39 @@ The gateway should split the key into a stable key id and secret component,
 load the key record by id, hash the presented secret, and compare using a
 constant-time comparison.
 
+`ApiKeyParser` accepts only `authorization: Bearer mxgw_<key-id>_<secret>`.
+Malformed headers fail before any database lookup. The parsed raw secret is
+kept only long enough for `ApiKeySecretHasher` to compute an HMAC-SHA256 hash
+using the configured `Authentication:PepperSecretName` lookup in application
+configuration. The raw secret is not stored in the auth database, identity
+model, logs, or verification result.
+
+`ApiKeyVerifier` loads the stored key record by key id, rejects revoked keys,
+hashes the presented secret, and compares the stored and presented hashes with
+`CryptographicOperations.FixedTimeEquals`. A successful verification returns an
+`ApiKeyIdentity` with key id, key prefix, display name, and scopes. Failure
+results distinguish malformed credentials, missing keys, revoked keys, missing
+pepper configuration, and hash mismatch for internal authorization handling.
+
+`GatewayGrpcAuthorizationInterceptor` enforces this authentication model for
+public gRPC calls. Missing, malformed, revoked, unknown, or mismatched keys fail
+with `Unauthenticated`. Authenticated calls missing the scope required by the
+RPC fail with `PermissionDenied`. The interceptor applies to unary calls and
+server-streaming calls and stores the authenticated `ApiKeyIdentity` in
+`IGatewayRequestIdentityAccessor` for the duration of the request handler.
+`Authentication:Mode` set to `Disabled` bypasses API-key verification for local
+development only.
+
+Dashboard authentication reuses the API-key verifier and scope model. The
+dashboard login endpoint accepts the key in a form post, checks `admin` scope
+when `Dashboard:RequireAdminScope` is enabled, and signs in with the
+`MxGateway.Dashboard` cookie scheme. The cookie is HTTP-only, secure, strict
+SameSite, and scoped with the `__Host-MxGatewayDashboard` name. Logout clears
+that cookie. Login and logout posts use anti-forgery validation, and dashboard
+API keys are not accepted in query strings. `Dashboard:AllowAnonymousLocalhost`
+allows only loopback requests to bypass the dashboard cookie requirement and
+defaults to `false`.
+
 Recommended scopes:
 
 - `session:open`
@@ -608,10 +692,44 @@ gRPC admin API. It should initialize the auth database, create keys, list keys
 without secrets, revoke keys, rotate keys, and print raw secrets only once at
 creation.
 
+`MxGateway.Server` exposes local API-key administration as an `apikey`
+subcommand before the web host starts:
+
+```bash
+MxGateway.Server apikey init-db --sqlite-path C:\ProgramData\MxGateway\gateway-auth.db
+MxGateway.Server apikey create-key --key-id operator01 --display-name Operator --scopes session:open,events:read
+MxGateway.Server apikey list-keys --json
+MxGateway.Server apikey revoke-key --key-id operator01
+MxGateway.Server apikey rotate-key --key-id operator01 --json
+```
+
+The subcommands accept `--sqlite-path`, `--pepper`, and `--json`. `--pepper`
+sets the local `MxGateway:ApiKeyPepper` configuration value for the command
+process; deployments should normally provide the pepper through the configured
+secret source. `create-key` and `rotate-key` print the full raw API key exactly
+once. `list-keys` never prints raw secrets or `secret_hash` values.
+
 SQLite auth storage should use startup migrations with a `schema_version` table.
 Migrations should run inside transactions and fail startup if the database
 schema is newer than the running binary understands.
 
+The v1 auth store uses `Microsoft.Data.Sqlite` and creates the
+`schema_version`, `api_keys`, and `api_key_audit` tables through
+`SqliteAuthStoreMigrator`. `AuthStoreMigrationHostedService` runs those
+migrations at gateway startup when API-key authentication and
+`Authentication:RunMigrationsOnStartup` are enabled. A database with a newer
+schema version fails startup instead of being modified by an older gateway
+binary.
+
+`IApiKeyStore` reads stored key records and exposes an active-key lookup that
+excludes rows with `revoked_utc` set. Hash verification belongs to the API-key
+hashing layer, but the store preserves the `secret_hash` bytes, display name,
+scopes, timestamps, and revocation state needed by that layer.
+
+`IApiKeyAuditStore` appends audit events to `api_key_audit` and returns recent
+events for diagnostics and future administrative tools. Audit records store key
+ids and event metadata only; they do not store raw API key secrets.
+
 Commands requiring authorization:
 
 - writes,
@@ -620,6 +738,20 @@ Commands requiring authorization:
 - worker shutdown diagnostics,
 - metadata queries if they expose sensitive plant structure.
 
+Current gRPC scope mapping:
+
+- `OpenSession` requires `session:open`.
+- `CloseSession` requires `session:close`.
+- `StreamEvents` and `DrainEvents` require `events:read`.
+- read-style MXAccess commands such as `Register`, `AddItem`, `Advise`, and
+  `Ping` require `invoke:read`.
+- `Write` and `Write2` require `invoke:write`.
+- `WriteSecured`, `WriteSecured2`, and `AuthenticateUser` require
+  `invoke:secure`.
+- metadata commands such as `ArchestrAUserToId`, `GetSessionState`, and
+  `GetWorkerInfo` require `metadata:read`.
+- `ShutdownWorker` requires `admin`.
+
 ### Worker IPC
 
 Named pipes should be local only. Pipe ACLs should restrict access to:
@@ -664,6 +796,26 @@ Metrics:
 
 Do not log credential values or full tag values by default.
 
+The gateway registers `GatewayMetrics` as the in-process metrics foundation.
+It emits .NET `Meter` instruments for collectors and keeps a
+`GatewayMetricsSnapshot` for dashboard projection. The snapshot exists because
+the dashboard needs current counters and queue depths without depending on a
+specific metrics exporter.
+
+HTTP request handling uses `UseGatewayRequestLoggingScope()` to attach common
+structured log fields when request metadata is present:
+
+- `SessionId`,
+- `ClientIdentity`,
+- `WorkerProcessId`,
+- `CorrelationId`,
+- `CommandMethod`.
+
+`GatewayLogRedactor` redacts API key secrets and command values before they are
+added to log state. Value logging remains opt-in and redacted by default so
+secured writes, authentication commands, and ordinary tag values do not leak
+through diagnostics.
+
 ## Configuration
 
 Suggested configuration shape:
@@ -710,6 +862,18 @@ Suggested configuration shape:
 
 Do not scatter connection or path constants through implementation code.
 
+`MxGateway.Server` binds this section to `GatewayOptions` at startup and
+registers validation with `ValidateOnStart()`. Startup fails before the gateway
+begins serving traffic when required authentication settings are missing,
+timeouts or queue sizes are not positive, dashboard settings are malformed, or
+the configured worker protocol version does not match the contract version.
+
+The gateway exposes read-only effective settings through
+`IGatewayConfigurationProvider`. This projection is for dashboard settings and
+diagnostics, so it redacts secret-related fields such as
+`Authentication:PepperSecretName` and does not include raw API keys or key
+material.
+
 ## Galaxy Repository Metadata
 
 Galaxy hierarchy and tag metadata can be discovered through SQL Server when
@@ -727,9 +891,17 @@ behavior unless an explicit non-parity backend is designed.
 Gateway tests should be able to run without installed MXAccess by using fake
 workers and fake transports.
 
+Use `FakeWorkerHarness` for tests that need real gateway-to-worker framing,
+handshake, command, event, fault, or malformed-protocol behavior without loading
+MXAccess COM. See [Gateway Testing](./GatewayTesting.md) for the harness scope
+and focused test commands.
+
 Focused tests:
 
 - session state transitions,
+- gRPC API-key authentication for unary and streaming calls,
+- gRPC scope mapping for sessions, invokes, events, metadata, and admin
+  commands,
 - worker startup failures,
 - protocol version mismatch,
 - malformed frame handling,

docs/implementation-plan-mxaccess-worker.md

@@ -189,6 +189,8 @@ Tests:
 
 Labels: `area:worker`, `type:feature`, `priority:p0`
 
+Status: implemented.
+
 Deliverables:
 
 - `Register`,
@@ -216,6 +218,8 @@ Live tests:
 
 Labels: `area:worker`, `type:feature`, `priority:p0`
 
+Status: implemented.
+
 Deliverables:
 
 - `AddItem`,
@@ -447,4 +451,3 @@ Acceptance criteria:
 
 - each public method has planned parity fixture or documented gap,
 - gateway results preserve HRESULT/status/value/event shape.
-

docs/mxaccess-worker-instance-design.md

@@ -26,6 +26,33 @@ Style guides:
 - [C# Style Guide](./style-guides/CSharpStyleGuide.md)
 - [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)
 
+## Build And Test
+
+Build the SDK-style worker project with the .NET SDK MSBuild entry point. The
+project targets .NET Framework 4.8, but the SDK resolver comes from the .NET SDK
+installation:
+
+```powershell
+dotnet msbuild src\MxGateway.Worker\MxGateway.Worker.csproj /restore /p:Configuration=Debug /p:Platform=x86
+```
+
+`docs/toolchain-links.md` records the Visual Studio MSBuild executable for
+classic .NET Framework and COM interop builds:
+
+```powershell
+& "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe" src\MxGateway.Worker\MxGateway.Worker.csproj /p:Configuration=Debug /p:Platform=x86
+```
+
+Run the worker tests with the same platform target:
+
+```powershell
+dotnet test src\MxGateway.Worker.Tests\MxGateway.Worker.Tests.csproj -p:Platform=x86
+```
+
+The only MXAccess interop reference belongs in `MxGateway.Worker`. Gateway and
+test projects may reference the worker project for metadata and scaffold tests,
+but they must not reference `ArchestrA.MXAccess.dll` directly.
+
 ## Responsibilities
 
 The worker owns:
@@ -87,6 +114,21 @@ Startup sequence:
 If validation fails before MXAccess creation, exit quickly with a non-zero exit
 code. If MXAccess creation fails, send `WorkerFault` when possible and exit.
 
+The bootstrap layer returns structured exit codes before it creates pipes,
+starts the STA, or touches MXAccess:
+
+| Exit code | Name | Meaning |
+|-----------|------|---------|
+| `0` | `Success` | Required bootstrap options are valid. |
+| `1` | `UnexpectedFailure` | A non-bootstrap exception reaches the process boundary. |
+| `2` | `InvalidArguments` | Required arguments are missing or unknown arguments are present. |
+| `3` | `InvalidProtocolVersion` | `--protocol-version` is not numeric or does not match the supported worker protocol. |
+| `4` | `MissingNonce` | `MXGATEWAY_WORKER_NONCE` is absent or empty. |
+
+Bootstrap logs use `WorkerConsoleLogger` key/value output. `WorkerLogRedactor`
+redacts fields whose names indicate nonce, secret, password, token,
+credential, or API key values before the message is written.
+
 ## Internal Components
 
 ```text
@@ -208,6 +250,17 @@ The loop should update a heartbeat timestamp after:
 - finishing a command,
 - processing an MXAccess event.
 
+`StaRuntime` implements this runtime boundary in the worker. It starts one
+background thread named `MxGateway.Worker.STA`, sets it to `ApartmentState.STA`,
+initializes COM through `StaComApartmentInitializer`, and runs
+`StaMessagePump`. Commands are scheduled through `InvokeAsync`; the command
+queue signals an `AutoResetEvent` so `MsgWaitForMultipleObjectsEx` can wake the
+STA without busy-waiting. `LastActivityUtc` records pump, command, startup, and
+shutdown activity so the future heartbeat/watchdog can report whether the STA
+is still responsive. Shutdown marks the runtime as closing, wakes the pump,
+rejects new commands, cancels queued work, uninitializes COM on the STA, and
+waits for the thread to exit.
+
 ## COM Creation
 
 The MXAccess analysis source at `C:\Users\dohertj2\Desktop\mxaccess` identifies
@@ -236,6 +289,16 @@ The worker should reference the interop assembly and instantiate
 `LMXProxyServerClass` on the dedicated STA thread. Keep the ProgID and assembly
 path configurable for diagnostics, but this COM class is the v1 default.
 
+`MxAccessStaSession` owns the initial COM creation path. It starts `StaRuntime`,
+creates `LMXProxyServerClass` through `MxAccessComObjectFactory` on the STA,
+attaches `MxAccessBaseEventSink`, and returns `WorkerReady` only after those
+steps succeed. `MxAccessSession` keeps the raw COM object private, records the
+STA managed thread id that created it, detaches the base event sink during
+disposal, and releases the COM reference on the STA. After creation,
+`MxAccessStaSession` owns a `StaCommandDispatcher` backed by
+`MxAccessCommandExecutor`; `DispatchAsync` queues contract commands back to the
+same STA instead of exposing the COM object to callers.
+
 Creation rules:
 
 - Create COM object only on the STA.
@@ -253,6 +316,11 @@ If COM creation fails, the worker should send a structured fault with:
 - worker process id,
 - session id.
 
+`WorkerPipeSession` maps startup exceptions from this path to
+`WorkerFaultCategory.MxaccessCreationFailed`, includes the captured HRESULT
+when the exception exposes one, and does not send `WorkerReady` after a failed
+COM creation attempt.
+
 ## Event Sink
 
 The worker must subscribe to every public MXAccess event family:
@@ -349,6 +417,40 @@ Diagnostics:
 Implement method-specific dispatch instead of a generic string method invoker.
 Parity tests need stable command-specific request and reply shapes.
 
+`MxAccessCommandExecutor` implements the first command pair:
+
+- `Register` calls `LMXProxyServerClass.Register` with the requested client
+  name and preserves the returned server handle in both `ReturnValue` and
+  `RegisterReply.ServerHandle`.
+- `Unregister` calls `LMXProxyServerClass.Unregister` with the requested server
+  handle. The reply has no method-specific payload because the public MXAccess
+  method returns `void`.
+
+Both commands set `Hresult` to `0` only after the COM call returns normally.
+COM exceptions flow through `StaCommandDispatcher`, which captures the thrown
+HRESULT and converts the reply to `ProtocolStatusCode.MxaccessFailure`.
+`MxAccessStaSession.GetRegisteredServerHandlesAsync` returns an STA-read
+snapshot of tracked server handles for diagnostics and future cleanup logic.
+
+`MxAccessCommandExecutor` also implements the item lifecycle commands:
+
+- `AddItem` calls `LMXProxyServerClass.AddItem` with the requested server
+  handle and item definition. It preserves the returned item handle in both
+  `ReturnValue` and `AddItemReply.ItemHandle`.
+- `AddItem2` calls `LMXProxyServerClass.AddItem2` with the requested server
+  handle, item definition, and context string. The context string is passed to
+  MXAccess exactly as received.
+- `RemoveItem` calls `LMXProxyServerClass.RemoveItem` with the requested server
+  handle and item handle. The reply has no method-specific payload because the
+  public MXAccess method returns `void`.
+
+The worker records item handles only after `AddItem` or `AddItem2` returns
+normally, and removes item handles only after `RemoveItem` returns normally.
+The registry does not prevalidate server or item handles, so invalid and
+cross-server handle behavior remains owned by MXAccess. COM exceptions continue
+through `StaCommandDispatcher`, which preserves the HRESULT and leaves
+diagnostic registry state unchanged for failed cleanup calls.
+
 ## Handle Registry
 
 The worker should track MXAccess state for diagnostics and cleanup, while still
@@ -369,6 +471,10 @@ Rules:
 
 - Do not invent handles.
 - Do not rewrite handles returned by MXAccess.
+- Record server handles only after `Register` succeeds.
+- Remove server handles only after `Unregister` succeeds.
+- Record item handles only after `AddItem` or `AddItem2` succeeds.
+- Remove item handles only after `RemoveItem` succeeds.
 - Preserve invalid-handle behavior from MXAccess.
 - Preserve cross-server handle behavior from MXAccess.
 - Use registry state for cleanup and diagnostics, not semantic correction.
@@ -612,6 +718,10 @@ Live MXAccess tests:
 
 Live tests should be opt-in and clearly marked because they depend on installed
 MXAccess COM and provider state.
+The worker test suite uses `MXGATEWAY_RUN_LIVE_MXACCESS_TESTS=1` for these
+tests. `AddItem` uses `TestChildObject.TestInt` by default and accepts an
+override through `MXGATEWAY_LIVE_MXACCESS_ITEM`; `AddItem2` uses the captured
+parity fixture shape `AddItem2("TestInt", "TestChildObject")`.
 
 ## Initial Implementation Slice
 

gateway.md

@@ -45,6 +45,10 @@ Detailed follow-up docs:
 - `docs/gateway-process-design.md` covers the .NET 10 gateway process,
   session manager, worker supervision, gRPC API, event streaming, fault model,
   security, observability, and test strategy.
+- `docs/WorkerFrameProtocol.md` covers the gateway-side named-pipe frame
+  reader/writer and `WorkerEnvelope` validation rules.
+- `docs/WorkerProcessLauncher.md` covers worker executable validation, process
+  launch arguments, nonce handling, and startup cleanup behavior.
 - `docs/mxaccess-worker-instance-design.md` covers each .NET Framework 4.8 x86
   MXAccess worker instance, including STA ownership, message pumping, COM
   lifetime, command dispatch, event sinks, conversion, and shutdown.
@@ -97,6 +101,31 @@ Responsibilities:
 
 The gateway must never instantiate or call MXAccess directly.
 
+The gateway observability foundation lives in `MxGateway.Server.Diagnostics`
+and `MxGateway.Server.Metrics`. Structured logging scopes carry session,
+worker, correlation, command, and client identity fields with redaction applied
+before values enter log state. `GatewayMetrics` exposes counters, gauges, and
+histograms through .NET `Meter` and a snapshot API that dashboard services can
+project without binding to a metrics exporter.
+`DashboardSnapshotService` projects sessions, workers, metrics, faults, and
+effective configuration into immutable DTOs for read-only dashboard rendering.
+The Blazor Server dashboard renders those snapshots at `/dashboard`,
+`/dashboard/sessions`, `/dashboard/workers`, `/dashboard/events`, and
+`/dashboard/settings`. Components subscribe to
+`IDashboardSnapshotService.WatchSnapshotsAsync()` and update on the configured
+snapshot interval without mutating session or worker state. The dashboard uses
+local Bootstrap CSS and JavaScript plus a small local stylesheet; it does not
+use a Blazor UI component library.
+
+Dashboard routes use the same API-key verifier as gRPC. `/dashboard/login`
+accepts the API key in a form body, validates the configured `admin` scope,
+and issues an HTTP-only secure cookie for subsequent dashboard requests.
+`/dashboard/logout` clears that cookie. Login and logout posts validate
+anti-forgery tokens, and API keys are never accepted through query strings.
+`Dashboard:AllowAnonymousLocalhost` can bypass the cookie requirement for
+loopback requests only when explicitly enabled. Setting
+`MxGateway:Dashboard:Enabled` to `false` leaves the dashboard routes unmapped.
+
 ### Worker Process
 
 Runtime:
@@ -507,11 +536,7 @@ Worker policy:
 
 - bounded outbound event channel,
 - never block MXAccess event handler on pipe writes,
-- if the outbound channel is full, apply configured policy:
-  - disconnect session,
-  - drop oldest low-priority data-change events,
-  - coalesce data changes by item handle,
-  - or block briefly then fault.
+- fail the worker session when the outbound channel is full.
 
 For full parity testing, default should be fail-fast rather than silent drop.
 For production high-rate telemetry, add explicit coalescing modes.
@@ -520,9 +545,15 @@ Gateway policy:
 
 - one event sequencer per session,
 - preserve per-session event order,
-- support multiple client event subscribers only if explicitly required,
-- apply backpressure from slow gRPC streams,
-- disconnect or coalesce according to client-selected mode.
+- allow one active client event subscriber per session,
+- reject a second subscriber with a clear session error,
+- use a bounded `EventStreamService` queue between worker events and gRPC
+  writes,
+- fault the session when the bounded stream queue overflows,
+- detach the subscriber when the stream is canceled.
+
+The gateway forwards only events reported by the worker. It does not synthesize
+`OperationComplete` from write completion, command replies, or status frames.
 
 ## Isolation And Fault Handling
 
@@ -555,9 +586,13 @@ Because each client owns one worker, a crash or leak affects only that session.
 External gateway:
 
 - use TLS for remote gRPC if crossing machine boundaries,
-- authenticate clients with Windows auth, mTLS, or a deployment-specific token,
-- authorize access to commands that can write, authenticate users, or alter
-  runtime state.
+- authenticate v1 gRPC clients with `authorization: Bearer
+  mxgw_<key-id>_<secret>` API-key metadata,
+- reject missing or invalid API keys with gRPC `Unauthenticated`,
+- reject valid keys that lack the required session, invoke, event, metadata, or
+  admin scope with gRPC `PermissionDenied`,
+- authorize access to commands that can write, authenticate users, expose
+  metadata, stream events, or alter runtime state.
 
 Internal worker IPC:
 
@@ -784,6 +819,12 @@ Core operations:
 - track worker state,
 - close or kill worker.
 
+The gateway implementation keeps sessions in an in-memory `SessionRegistry`
+keyed by session id. `SessionManager` owns the state machine, creates
+per-session pipe names and nonces, starts the worker through the worker-client
+factory, gates commands to `Ready` sessions, exposes lease-close hooks, and
+cleans up workers during gateway shutdown.
+
 State machine:
 
 ```text
@@ -831,6 +872,15 @@ The gRPC layer should be thin:
 Avoid embedding MXAccess-specific business logic in gRPC handlers. Keep the
 translation code testable.
 
+The gateway maps `MxAccessGateway` to `MxAccessGatewayService`. The service
+implements `OpenSession`, `CloseSession`, `Invoke`, and `StreamEvents` by
+validating public requests, delegating session work to `ISessionManager`, and
+using explicit mapper code for public-to-worker commands and worker replies.
+`StreamEvents` delegates subscriber ownership, ordering, and backpressure to
+`EventStreamService`. Missing sessions and transport failures return gRPC
+status errors; worker command replies preserve MXAccess HRESULT and status
+details in the public reply.
+
 ## C# Worker Versus C++ Worker
 
 Start with a C# .NET Framework 4.8 x86 worker.

src/MxGateway.Contracts/Generated/MxaccessGatewayGrpc.cs

@@ -0,0 +1,268 @@
+// <auto-generated>
+//     Generated by the protocol buffer compiler.  DO NOT EDIT!
+//     source: mxaccess_gateway.proto
+// </auto-generated>
+#pragma warning disable 0414, 1591, 8981, 0612
+#region Designer generated code
+
+using grpc = global::Grpc.Core;
+
+namespace MxGateway.Contracts.Proto {
+  /// <summary>
+  /// Public client API for MXAccess sessions hosted by the gateway.
+  /// </summary>
+  public static partial class MxAccessGateway
+  {
+    static readonly string __ServiceName = "mxaccess_gateway.v1.MxAccessGateway";
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static void __Helper_SerializeMessage(global::Google.Protobuf.IMessage message, grpc::SerializationContext context)
+    {
+      #if !GRPC_DISABLE_PROTOBUF_BUFFER_SERIALIZATION
+      if (message is global::Google.Protobuf.IBufferMessage)
+      {
+        context.SetPayloadLength(message.CalculateSize());
+        global::Google.Protobuf.MessageExtensions.WriteTo(message, context.GetBufferWriter());
+        context.Complete();
+        return;
+      }
+      #endif
+      context.Complete(global::Google.Protobuf.MessageExtensions.ToByteArray(message));
+    }
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static class __Helper_MessageCache<T>
+    {
+      public static readonly bool IsBufferMessage = global::System.Reflection.IntrospectionExtensions.GetTypeInfo(typeof(global::Google.Protobuf.IBufferMessage)).IsAssignableFrom(typeof(T));
+    }
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static T __Helper_DeserializeMessage<T>(grpc::DeserializationContext context, global::Google.Protobuf.MessageParser<T> parser) where T : global::Google.Protobuf.IMessage<T>
+    {
+      #if !GRPC_DISABLE_PROTOBUF_BUFFER_SERIALIZATION
+      if (__Helper_MessageCache<T>.IsBufferMessage)
+      {
+        return parser.ParseFrom(context.PayloadAsReadOnlySequence());
+      }
+      #endif
+      return parser.ParseFrom(context.PayloadAsNewBuffer());
+    }
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.OpenSessionRequest> __Marshaller_mxaccess_gateway_v1_OpenSessionRequest = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.OpenSessionRequest.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.OpenSessionReply> __Marshaller_mxaccess_gateway_v1_OpenSessionReply = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.OpenSessionReply.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.CloseSessionRequest> __Marshaller_mxaccess_gateway_v1_CloseSessionRequest = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.CloseSessionRequest.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.CloseSessionReply> __Marshaller_mxaccess_gateway_v1_CloseSessionReply = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.CloseSessionReply.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.MxCommandRequest> __Marshaller_mxaccess_gateway_v1_MxCommandRequest = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.MxCommandRequest.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.MxCommandReply> __Marshaller_mxaccess_gateway_v1_MxCommandReply = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.MxCommandReply.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.StreamEventsRequest> __Marshaller_mxaccess_gateway_v1_StreamEventsRequest = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.StreamEventsRequest.Parser));
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Marshaller<global::MxGateway.Contracts.Proto.MxEvent> __Marshaller_mxaccess_gateway_v1_MxEvent = grpc::Marshallers.Create(__Helper_SerializeMessage, context => __Helper_DeserializeMessage(context, global::MxGateway.Contracts.Proto.MxEvent.Parser));
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Method<global::MxGateway.Contracts.Proto.OpenSessionRequest, global::MxGateway.Contracts.Proto.OpenSessionReply> __Method_OpenSession = new grpc::Method<global::MxGateway.Contracts.Proto.OpenSessionRequest, global::MxGateway.Contracts.Proto.OpenSessionReply>(
+        grpc::MethodType.Unary,
+        __ServiceName,
+        "OpenSession",
+        __Marshaller_mxaccess_gateway_v1_OpenSessionRequest,
+        __Marshaller_mxaccess_gateway_v1_OpenSessionReply);
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Method<global::MxGateway.Contracts.Proto.CloseSessionRequest, global::MxGateway.Contracts.Proto.CloseSessionReply> __Method_CloseSession = new grpc::Method<global::MxGateway.Contracts.Proto.CloseSessionRequest, global::MxGateway.Contracts.Proto.CloseSessionReply>(
+        grpc::MethodType.Unary,
+        __ServiceName,
+        "CloseSession",
+        __Marshaller_mxaccess_gateway_v1_CloseSessionRequest,
+        __Marshaller_mxaccess_gateway_v1_CloseSessionReply);
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Method<global::MxGateway.Contracts.Proto.MxCommandRequest, global::MxGateway.Contracts.Proto.MxCommandReply> __Method_Invoke = new grpc::Method<global::MxGateway.Contracts.Proto.MxCommandRequest, global::MxGateway.Contracts.Proto.MxCommandReply>(
+        grpc::MethodType.Unary,
+        __ServiceName,
+        "Invoke",
+        __Marshaller_mxaccess_gateway_v1_MxCommandRequest,
+        __Marshaller_mxaccess_gateway_v1_MxCommandReply);
+
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    static readonly grpc::Method<global::MxGateway.Contracts.Proto.StreamEventsRequest, global::MxGateway.Contracts.Proto.MxEvent> __Method_StreamEvents = new grpc::Method<global::MxGateway.Contracts.Proto.StreamEventsRequest, global::MxGateway.Contracts.Proto.MxEvent>(
+        grpc::MethodType.ServerStreaming,
+        __ServiceName,
+        "StreamEvents",
+        __Marshaller_mxaccess_gateway_v1_StreamEventsRequest,
+        __Marshaller_mxaccess_gateway_v1_MxEvent);
+
+    /// <summary>Service descriptor</summary>
+    public static global::Google.Protobuf.Reflection.ServiceDescriptor Descriptor
+    {
+      get { return global::MxGateway.Contracts.Proto.MxaccessGatewayReflection.Descriptor.Services[0]; }
+    }
+
+    /// <summary>Base class for server-side implementations of MxAccessGateway</summary>
+    [grpc::BindServiceMethod(typeof(MxAccessGateway), "BindService")]
+    public abstract partial class MxAccessGatewayBase
+    {
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::System.Threading.Tasks.Task<global::MxGateway.Contracts.Proto.OpenSessionReply> OpenSession(global::MxGateway.Contracts.Proto.OpenSessionRequest request, grpc::ServerCallContext context)
+      {
+        throw new grpc::RpcException(new grpc::Status(grpc::StatusCode.Unimplemented, ""));
+      }
+
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::System.Threading.Tasks.Task<global::MxGateway.Contracts.Proto.CloseSessionReply> CloseSession(global::MxGateway.Contracts.Proto.CloseSessionRequest request, grpc::ServerCallContext context)
+      {
+        throw new grpc::RpcException(new grpc::Status(grpc::StatusCode.Unimplemented, ""));
+      }
+
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::System.Threading.Tasks.Task<global::MxGateway.Contracts.Proto.MxCommandReply> Invoke(global::MxGateway.Contracts.Proto.MxCommandRequest request, grpc::ServerCallContext context)
+      {
+        throw new grpc::RpcException(new grpc::Status(grpc::StatusCode.Unimplemented, ""));
+      }
+
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::System.Threading.Tasks.Task StreamEvents(global::MxGateway.Contracts.Proto.StreamEventsRequest request, grpc::IServerStreamWriter<global::MxGateway.Contracts.Proto.MxEvent> responseStream, grpc::ServerCallContext context)
+      {
+        throw new grpc::RpcException(new grpc::Status(grpc::StatusCode.Unimplemented, ""));
+      }
+
+    }
+
+    /// <summary>Client for MxAccessGateway</summary>
+    public partial class MxAccessGatewayClient : grpc::ClientBase<MxAccessGatewayClient>
+    {
+      /// <summary>Creates a new client for MxAccessGateway</summary>
+      /// <param name="channel">The channel to use to make remote calls.</param>
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public MxAccessGatewayClient(grpc::ChannelBase channel) : base(channel)
+      {
+      }
+      /// <summary>Creates a new client for MxAccessGateway that uses a custom <c>CallInvoker</c>.</summary>
+      /// <param name="callInvoker">The callInvoker to use to make remote calls.</param>
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public MxAccessGatewayClient(grpc::CallInvoker callInvoker) : base(callInvoker)
+      {
+      }
+      /// <summary>Protected parameterless constructor to allow creation of test doubles.</summary>
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      protected MxAccessGatewayClient() : base()
+      {
+      }
+      /// <summary>Protected constructor to allow creation of configured clients.</summary>
+      /// <param name="configuration">The client configuration.</param>
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      protected MxAccessGatewayClient(ClientBaseConfiguration configuration) : base(configuration)
+      {
+      }
+
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::MxGateway.Contracts.Proto.OpenSessionReply OpenSession(global::MxGateway.Contracts.Proto.OpenSessionRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return OpenSession(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::MxGateway.Contracts.Proto.OpenSessionReply OpenSession(global::MxGateway.Contracts.Proto.OpenSessionRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.BlockingUnaryCall(__Method_OpenSession, null, options, request);
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncUnaryCall<global::MxGateway.Contracts.Proto.OpenSessionReply> OpenSessionAsync(global::MxGateway.Contracts.Proto.OpenSessionRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return OpenSessionAsync(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncUnaryCall<global::MxGateway.Contracts.Proto.OpenSessionReply> OpenSessionAsync(global::MxGateway.Contracts.Proto.OpenSessionRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.AsyncUnaryCall(__Method_OpenSession, null, options, request);
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::MxGateway.Contracts.Proto.CloseSessionReply CloseSession(global::MxGateway.Contracts.Proto.CloseSessionRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return CloseSession(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::MxGateway.Contracts.Proto.CloseSessionReply CloseSession(global::MxGateway.Contracts.Proto.CloseSessionRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.BlockingUnaryCall(__Method_CloseSession, null, options, request);
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncUnaryCall<global::MxGateway.Contracts.Proto.CloseSessionReply> CloseSessionAsync(global::MxGateway.Contracts.Proto.CloseSessionRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return CloseSessionAsync(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncUnaryCall<global::MxGateway.Contracts.Proto.CloseSessionReply> CloseSessionAsync(global::MxGateway.Contracts.Proto.CloseSessionRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.AsyncUnaryCall(__Method_CloseSession, null, options, request);
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::MxGateway.Contracts.Proto.MxCommandReply Invoke(global::MxGateway.Contracts.Proto.MxCommandRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return Invoke(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual global::MxGateway.Contracts.Proto.MxCommandReply Invoke(global::MxGateway.Contracts.Proto.MxCommandRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.BlockingUnaryCall(__Method_Invoke, null, options, request);
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncUnaryCall<global::MxGateway.Contracts.Proto.MxCommandReply> InvokeAsync(global::MxGateway.Contracts.Proto.MxCommandRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return InvokeAsync(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncUnaryCall<global::MxGateway.Contracts.Proto.MxCommandReply> InvokeAsync(global::MxGateway.Contracts.Proto.MxCommandRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.AsyncUnaryCall(__Method_Invoke, null, options, request);
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncServerStreamingCall<global::MxGateway.Contracts.Proto.MxEvent> StreamEvents(global::MxGateway.Contracts.Proto.StreamEventsRequest request, grpc::Metadata headers = null, global::System.DateTime? deadline = null, global::System.Threading.CancellationToken cancellationToken = default(global::System.Threading.CancellationToken))
+      {
+        return StreamEvents(request, new grpc::CallOptions(headers, deadline, cancellationToken));
+      }
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      public virtual grpc::AsyncServerStreamingCall<global::MxGateway.Contracts.Proto.MxEvent> StreamEvents(global::MxGateway.Contracts.Proto.StreamEventsRequest request, grpc::CallOptions options)
+      {
+        return CallInvoker.AsyncServerStreamingCall(__Method_StreamEvents, null, options, request);
+      }
+      /// <summary>Creates a new instance of client from given <c>ClientBaseConfiguration</c>.</summary>
+      [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+      protected override MxAccessGatewayClient NewInstance(ClientBaseConfiguration configuration)
+      {
+        return new MxAccessGatewayClient(configuration);
+      }
+    }
+
+    /// <summary>Creates service definition that can be registered with a server</summary>
+    /// <param name="serviceImpl">An object implementing the server-side handling logic.</param>
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    public static grpc::ServerServiceDefinition BindService(MxAccessGatewayBase serviceImpl)
+    {
+      return grpc::ServerServiceDefinition.CreateBuilder()
+          .AddMethod(__Method_OpenSession, serviceImpl.OpenSession)
+          .AddMethod(__Method_CloseSession, serviceImpl.CloseSession)
+          .AddMethod(__Method_Invoke, serviceImpl.Invoke)
+          .AddMethod(__Method_StreamEvents, serviceImpl.StreamEvents).Build();
+    }
+
+    /// <summary>Register service method with a service binder with or without implementation. Useful when customizing the service binding logic.
+    /// Note: this method is part of an experimental API that can change or be removed without any prior notice.</summary>
+    /// <param name="serviceBinder">Service methods will be bound by calling <c>AddMethod</c> on this object.</param>
+    /// <param name="serviceImpl">An object implementing the server-side handling logic.</param>
+    [global::System.CodeDom.Compiler.GeneratedCode("grpc_csharp_plugin", null)]
+    public static void BindService(grpc::ServiceBinderBase serviceBinder, MxAccessGatewayBase serviceImpl)
+    {
+      serviceBinder.AddMethod(__Method_OpenSession, serviceImpl == null ? null : new grpc::UnaryServerMethod<global::MxGateway.Contracts.Proto.OpenSessionRequest, global::MxGateway.Contracts.Proto.OpenSessionReply>(serviceImpl.OpenSession));
+      serviceBinder.AddMethod(__Method_CloseSession, serviceImpl == null ? null : new grpc::UnaryServerMethod<global::MxGateway.Contracts.Proto.CloseSessionRequest, global::MxGateway.Contracts.Proto.CloseSessionReply>(serviceImpl.CloseSession));
+      serviceBinder.AddMethod(__Method_Invoke, serviceImpl == null ? null : new grpc::UnaryServerMethod<global::MxGateway.Contracts.Proto.MxCommandRequest, global::MxGateway.Contracts.Proto.MxCommandReply>(serviceImpl.Invoke));
+      serviceBinder.AddMethod(__Method_StreamEvents, serviceImpl == null ? null : new grpc::ServerStreamingServerMethod<global::MxGateway.Contracts.Proto.StreamEventsRequest, global::MxGateway.Contracts.Proto.MxEvent>(serviceImpl.StreamEvents));
+    }
+
+  }
+}
+#endregion

src/MxGateway.Contracts/MxGateway.Contracts.csproj

@@ -1,7 +1,23 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
+    <TargetFrameworks>net10.0;net48</TargetFrameworks>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Remove="Generated\**\*.cs" />
+    <Protobuf Include="Protos\mxaccess_gateway.proto" ProtoRoot="Protos" OutputDir="Generated" GrpcOutputDir="Generated" GrpcServices="Both" />
+    <Protobuf Include="Protos\mxaccess_worker.proto" ProtoRoot="Protos" OutputDir="Generated" GrpcServices="None" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Google.Protobuf" Version="3.34.1" />
+    <PackageReference Include="Grpc.Core.Api" Version="2.76.0" />
+    <PackageReference Include="Grpc.Tools" Version="2.80.0">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.2" />
+  </ItemGroup>
+
 </Project>

src/MxGateway.Contracts/Protos/mxaccess_gateway.proto

@@ -0,0 +1,521 @@
+syntax = "proto3";
+
+package mxaccess_gateway.v1;
+
+option csharp_namespace = "MxGateway.Contracts.Proto";
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
+// Public client API for MXAccess sessions hosted by the gateway.
+service MxAccessGateway {
+  rpc OpenSession(OpenSessionRequest) returns (OpenSessionReply);
+  rpc CloseSession(CloseSessionRequest) returns (CloseSessionReply);
+  rpc Invoke(MxCommandRequest) returns (MxCommandReply);
+  rpc StreamEvents(StreamEventsRequest) returns (stream MxEvent);
+}
+
+message OpenSessionRequest {
+  string requested_backend = 1;
+  string client_session_name = 2;
+  string client_correlation_id = 3;
+  google.protobuf.Duration command_timeout = 4;
+}
+
+message OpenSessionReply {
+  string session_id = 1;
+  string backend_name = 2;
+  int32 worker_process_id = 3;
+  uint32 worker_protocol_version = 4;
+  repeated string capabilities = 5;
+  google.protobuf.Duration default_command_timeout = 6;
+  ProtocolStatus protocol_status = 7;
+}
+
+message CloseSessionRequest {
+  string session_id = 1;
+  string client_correlation_id = 2;
+}
+
+message CloseSessionReply {
+  string session_id = 1;
+  SessionState final_state = 2;
+  ProtocolStatus protocol_status = 3;
+}
+
+message StreamEventsRequest {
+  string session_id = 1;
+  uint64 after_worker_sequence = 2;
+}
+
+message MxCommandRequest {
+  string session_id = 1;
+  string client_correlation_id = 2;
+  MxCommand command = 3;
+}
+
+message MxCommand {
+  MxCommandKind kind = 1;
+
+  oneof payload {
+    RegisterCommand register = 10;
+    UnregisterCommand unregister = 11;
+    AddItemCommand add_item = 12;
+    AddItem2Command add_item2 = 13;
+    RemoveItemCommand remove_item = 14;
+    AdviseCommand advise = 15;
+    UnAdviseCommand un_advise = 16;
+    AdviseSupervisoryCommand advise_supervisory = 17;
+    AddBufferedItemCommand add_buffered_item = 18;
+    SetBufferedUpdateIntervalCommand set_buffered_update_interval = 19;
+    SuspendCommand suspend = 20;
+    ActivateCommand activate = 21;
+    WriteCommand write = 22;
+    Write2Command write2 = 23;
+    WriteSecuredCommand write_secured = 24;
+    WriteSecured2Command write_secured2 = 25;
+    AuthenticateUserCommand authenticate_user = 26;
+    ArchestrAUserToIdCommand archestra_user_to_id = 27;
+    PingCommand ping = 100;
+    GetSessionStateCommand get_session_state = 101;
+    GetWorkerInfoCommand get_worker_info = 102;
+    DrainEventsCommand drain_events = 103;
+    ShutdownWorkerCommand shutdown_worker = 104;
+  }
+}
+
+enum MxCommandKind {
+  MX_COMMAND_KIND_UNSPECIFIED = 0;
+  MX_COMMAND_KIND_REGISTER = 1;
+  MX_COMMAND_KIND_UNREGISTER = 2;
+  MX_COMMAND_KIND_ADD_ITEM = 3;
+  MX_COMMAND_KIND_ADD_ITEM2 = 4;
+  MX_COMMAND_KIND_REMOVE_ITEM = 5;
+  MX_COMMAND_KIND_ADVISE = 6;
+  MX_COMMAND_KIND_UN_ADVISE = 7;
+  MX_COMMAND_KIND_ADVISE_SUPERVISORY = 8;
+  MX_COMMAND_KIND_ADD_BUFFERED_ITEM = 9;
+  MX_COMMAND_KIND_SET_BUFFERED_UPDATE_INTERVAL = 10;
+  MX_COMMAND_KIND_SUSPEND = 11;
+  MX_COMMAND_KIND_ACTIVATE = 12;
+  MX_COMMAND_KIND_WRITE = 13;
+  MX_COMMAND_KIND_WRITE2 = 14;
+  MX_COMMAND_KIND_WRITE_SECURED = 15;
+  MX_COMMAND_KIND_WRITE_SECURED2 = 16;
+  MX_COMMAND_KIND_AUTHENTICATE_USER = 17;
+  MX_COMMAND_KIND_ARCHESTRA_USER_TO_ID = 18;
+  MX_COMMAND_KIND_PING = 100;
+  MX_COMMAND_KIND_GET_SESSION_STATE = 101;
+  MX_COMMAND_KIND_GET_WORKER_INFO = 102;
+  MX_COMMAND_KIND_DRAIN_EVENTS = 103;
+  MX_COMMAND_KIND_SHUTDOWN_WORKER = 104;
+}
+
+message RegisterCommand {
+  string client_name = 1;
+}
+
+message UnregisterCommand {
+  int32 server_handle = 1;
+}
+
+message AddItemCommand {
+  int32 server_handle = 1;
+  string item_definition = 2;
+}
+
+message AddItem2Command {
+  int32 server_handle = 1;
+  string item_definition = 2;
+  string item_context = 3;
+}
+
+message RemoveItemCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+}
+
+message AdviseCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+}
+
+message UnAdviseCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+}
+
+message AdviseSupervisoryCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+}
+
+message AddBufferedItemCommand {
+  int32 server_handle = 1;
+  string item_definition = 2;
+  string item_context = 3;
+}
+
+message SetBufferedUpdateIntervalCommand {
+  int32 server_handle = 1;
+  int32 update_interval_milliseconds = 2;
+}
+
+message SuspendCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+}
+
+message ActivateCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+}
+
+message WriteCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+  MxValue value = 3;
+  int32 user_id = 4;
+}
+
+message Write2Command {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+  MxValue value = 3;
+  MxValue timestamp_value = 4;
+  int32 user_id = 5;
+}
+
+message WriteSecuredCommand {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+  int32 current_user_id = 3;
+  int32 verifier_user_id = 4;
+  // Credential-sensitive write value. Implementations must not log this field
+  // unless an explicit redacted value-logging path is enabled.
+  MxValue value = 5;
+}
+
+message WriteSecured2Command {
+  int32 server_handle = 1;
+  int32 item_handle = 2;
+  int32 current_user_id = 3;
+  int32 verifier_user_id = 4;
+  // Credential-sensitive write value. Implementations must not log this field
+  // unless an explicit redacted value-logging path is enabled.
+  MxValue value = 5;
+  MxValue timestamp_value = 6;
+}
+
+message AuthenticateUserCommand {
+  int32 server_handle = 1;
+  string verify_user = 2;
+  // Raw MXAccess credential. Implementations must keep this field out of logs,
+  // metrics labels, command lines, and diagnostics.
+  string verify_user_password = 3;
+}
+
+message ArchestrAUserToIdCommand {
+  int32 server_handle = 1;
+  string user_id_guid = 2;
+}
+
+message PingCommand {
+  string message = 1;
+}
+
+message GetSessionStateCommand {
+}
+
+message GetWorkerInfoCommand {
+}
+
+message DrainEventsCommand {
+  uint32 max_events = 1;
+}
+
+message ShutdownWorkerCommand {
+  google.protobuf.Duration grace_period = 1;
+}
+
+message MxCommandReply {
+  string session_id = 1;
+  string correlation_id = 2;
+  MxCommandKind kind = 3;
+  ProtocolStatus protocol_status = 4;
+  // HRESULT captured from MXAccess or a COM exception. This remains separate
+  // from gateway protocol status so MXAccess parity details are not hidden by
+  // transport failures.
+  optional int32 hresult = 5;
+  MxValue return_value = 6;
+  repeated MxStatusProxy statuses = 7;
+  string diagnostic_message = 8;
+
+  oneof payload {
+    RegisterReply register = 20;
+    AddItemReply add_item = 21;
+    AddItem2Reply add_item2 = 22;
+    AddBufferedItemReply add_buffered_item = 23;
+    SuspendReply suspend = 24;
+    ActivateReply activate = 25;
+    AuthenticateUserReply authenticate_user = 26;
+    ArchestrAUserToIdReply archestra_user_to_id = 27;
+    SessionStateReply session_state = 100;
+    WorkerInfoReply worker_info = 101;
+    DrainEventsReply drain_events = 102;
+  }
+}
+
+message RegisterReply {
+  int32 server_handle = 1;
+}
+
+message AddItemReply {
+  int32 item_handle = 1;
+}
+
+message AddItem2Reply {
+  int32 item_handle = 1;
+}
+
+message AddBufferedItemReply {
+  int32 item_handle = 1;
+}
+
+message SuspendReply {
+  MxStatusProxy status = 1;
+}
+
+message ActivateReply {
+  MxStatusProxy status = 1;
+}
+
+message AuthenticateUserReply {
+  int32 user_id = 1;
+}
+
+message ArchestrAUserToIdReply {
+  int32 user_id = 1;
+}
+
+message SessionStateReply {
+  SessionState state = 1;
+}
+
+message WorkerInfoReply {
+  int32 worker_process_id = 1;
+  string worker_version = 2;
+  string mxaccess_progid = 3;
+  string mxaccess_clsid = 4;
+}
+
+message DrainEventsReply {
+  repeated MxEvent events = 1;
+}
+
+message MxEvent {
+  MxEventFamily family = 1;
+  string session_id = 2;
+  int32 server_handle = 3;
+  int32 item_handle = 4;
+  MxValue value = 5;
+  int32 quality = 6;
+  google.protobuf.Timestamp source_timestamp = 7;
+  repeated MxStatusProxy statuses = 8;
+  uint64 worker_sequence = 9;
+  google.protobuf.Timestamp worker_timestamp = 10;
+  google.protobuf.Timestamp gateway_receive_timestamp = 11;
+  optional int32 hresult = 12;
+  string raw_status = 13;
+
+  oneof body {
+    OnDataChangeEvent on_data_change = 20;
+    OnWriteCompleteEvent on_write_complete = 21;
+    OperationCompleteEvent operation_complete = 22;
+    OnBufferedDataChangeEvent on_buffered_data_change = 23;
+  }
+}
+
+enum MxEventFamily {
+  MX_EVENT_FAMILY_UNSPECIFIED = 0;
+  MX_EVENT_FAMILY_ON_DATA_CHANGE = 1;
+  MX_EVENT_FAMILY_ON_WRITE_COMPLETE = 2;
+  MX_EVENT_FAMILY_OPERATION_COMPLETE = 3;
+  MX_EVENT_FAMILY_ON_BUFFERED_DATA_CHANGE = 4;
+}
+
+message OnDataChangeEvent {
+}
+
+message OnWriteCompleteEvent {
+}
+
+message OperationCompleteEvent {
+}
+
+message OnBufferedDataChangeEvent {
+  MxDataType data_type = 1;
+  MxArray quality_values = 2;
+  MxArray timestamp_values = 3;
+  int32 raw_data_type = 4;
+}
+
+message MxStatusProxy {
+  int32 success = 1;
+  MxStatusCategory category = 2;
+  MxStatusSource detected_by = 3;
+  int32 detail = 4;
+  int32 raw_category = 5;
+  int32 raw_detected_by = 6;
+  string diagnostic_text = 7;
+}
+
+enum MxStatusCategory {
+  MX_STATUS_CATEGORY_UNSPECIFIED = 0;
+  MX_STATUS_CATEGORY_UNKNOWN = 1;
+  MX_STATUS_CATEGORY_OK = 2;
+  MX_STATUS_CATEGORY_PENDING = 3;
+  MX_STATUS_CATEGORY_WARNING = 4;
+  MX_STATUS_CATEGORY_COMMUNICATION_ERROR = 5;
+  MX_STATUS_CATEGORY_CONFIGURATION_ERROR = 6;
+  MX_STATUS_CATEGORY_OPERATIONAL_ERROR = 7;
+  MX_STATUS_CATEGORY_SECURITY_ERROR = 8;
+  MX_STATUS_CATEGORY_SOFTWARE_ERROR = 9;
+  MX_STATUS_CATEGORY_OTHER_ERROR = 10;
+}
+
+enum MxStatusSource {
+  MX_STATUS_SOURCE_UNSPECIFIED = 0;
+  MX_STATUS_SOURCE_UNKNOWN = 1;
+  MX_STATUS_SOURCE_REQUESTING_LMX = 2;
+  MX_STATUS_SOURCE_RESPONDING_LMX = 3;
+  MX_STATUS_SOURCE_REQUESTING_NMX = 4;
+  MX_STATUS_SOURCE_RESPONDING_NMX = 5;
+  MX_STATUS_SOURCE_REQUESTING_AUTOMATION_OBJECT = 6;
+  MX_STATUS_SOURCE_RESPONDING_AUTOMATION_OBJECT = 7;
+}
+
+message MxValue {
+  MxDataType data_type = 1;
+  string variant_type = 2;
+  bool is_null = 3;
+  string raw_diagnostic = 4;
+  int32 raw_data_type = 5;
+
+  oneof kind {
+    bool bool_value = 10;
+    int32 int32_value = 11;
+    int64 int64_value = 12;
+    float float_value = 13;
+    double double_value = 14;
+    string string_value = 15;
+    google.protobuf.Timestamp timestamp_value = 16;
+    MxArray array_value = 17;
+    bytes raw_value = 18;
+  }
+}
+
+message MxArray {
+  MxDataType element_data_type = 1;
+  string variant_type = 2;
+  repeated uint32 dimensions = 3;
+  string raw_diagnostic = 4;
+  int32 raw_element_data_type = 5;
+
+  oneof values {
+    BoolArray bool_values = 10;
+    Int32Array int32_values = 11;
+    Int64Array int64_values = 12;
+    FloatArray float_values = 13;
+    DoubleArray double_values = 14;
+    StringArray string_values = 15;
+    TimestampArray timestamp_values = 16;
+    RawArray raw_values = 17;
+  }
+}
+
+message BoolArray {
+  repeated bool values = 1;
+}
+
+message Int32Array {
+  repeated int32 values = 1;
+}
+
+message Int64Array {
+  repeated int64 values = 1;
+}
+
+message FloatArray {
+  repeated float values = 1;
+}
+
+message DoubleArray {
+  repeated double values = 1;
+}
+
+message StringArray {
+  repeated string values = 1;
+}
+
+message TimestampArray {
+  repeated google.protobuf.Timestamp values = 1;
+}
+
+message RawArray {
+  repeated bytes values = 1;
+}
+
+enum MxDataType {
+  MX_DATA_TYPE_UNSPECIFIED = 0;
+  MX_DATA_TYPE_UNKNOWN = 1;
+  MX_DATA_TYPE_NO_DATA = 2;
+  MX_DATA_TYPE_BOOLEAN = 3;
+  MX_DATA_TYPE_INTEGER = 4;
+  MX_DATA_TYPE_FLOAT = 5;
+  MX_DATA_TYPE_DOUBLE = 6;
+  MX_DATA_TYPE_STRING = 7;
+  MX_DATA_TYPE_TIME = 8;
+  MX_DATA_TYPE_ELAPSED_TIME = 9;
+  MX_DATA_TYPE_REFERENCE_TYPE = 10;
+  MX_DATA_TYPE_STATUS_TYPE = 11;
+  MX_DATA_TYPE_ENUM = 12;
+  MX_DATA_TYPE_SECURITY_CLASSIFICATION_ENUM = 13;
+  MX_DATA_TYPE_DATA_QUALITY_TYPE = 14;
+  MX_DATA_TYPE_QUALIFIED_ENUM = 15;
+  MX_DATA_TYPE_QUALIFIED_STRUCT = 16;
+  MX_DATA_TYPE_INTERNATIONALIZED_STRING = 17;
+  MX_DATA_TYPE_BIG_STRING = 18;
+  MX_DATA_TYPE_END = 19;
+}
+
+message ProtocolStatus {
+  ProtocolStatusCode code = 1;
+  string message = 2;
+}
+
+enum ProtocolStatusCode {
+  PROTOCOL_STATUS_CODE_UNSPECIFIED = 0;
+  PROTOCOL_STATUS_CODE_OK = 1;
+  PROTOCOL_STATUS_CODE_INVALID_REQUEST = 2;
+  PROTOCOL_STATUS_CODE_SESSION_NOT_FOUND = 3;
+  PROTOCOL_STATUS_CODE_SESSION_NOT_READY = 4;
+  PROTOCOL_STATUS_CODE_WORKER_UNAVAILABLE = 5;
+  PROTOCOL_STATUS_CODE_TIMEOUT = 6;
+  PROTOCOL_STATUS_CODE_CANCELED = 7;
+  PROTOCOL_STATUS_CODE_PROTOCOL_VIOLATION = 8;
+  PROTOCOL_STATUS_CODE_MXACCESS_FAILURE = 9;
+}
+
+enum SessionState {
+  SESSION_STATE_UNSPECIFIED = 0;
+  SESSION_STATE_CREATING = 1;
+  SESSION_STATE_STARTING_WORKER = 2;
+  SESSION_STATE_WAITING_FOR_PIPE = 3;
+  SESSION_STATE_HANDSHAKING = 4;
+  SESSION_STATE_INITIALIZING_WORKER = 5;
+  SESSION_STATE_READY = 6;
+  SESSION_STATE_CLOSING = 7;
+  SESSION_STATE_CLOSED = 8;
+  SESSION_STATE_FAULTED = 9;
+}

src/MxGateway.Contracts/Protos/mxaccess_worker.proto

@@ -0,0 +1,125 @@
+syntax = "proto3";
+
+package mxaccess_worker.v1;
+
+option csharp_namespace = "MxGateway.Contracts.Proto";
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+import "mxaccess_gateway.proto";
+
+// Gateway-to-worker IPC envelope. Named-pipe framing prepends a little-endian
+// uint32 payload length to this protobuf payload.
+message WorkerEnvelope {
+  uint32 protocol_version = 1;
+  string session_id = 2;
+  uint64 sequence = 3;
+  string correlation_id = 4;
+
+  oneof body {
+    GatewayHello gateway_hello = 10;
+    WorkerHello worker_hello = 11;
+    WorkerReady worker_ready = 12;
+    WorkerCommand worker_command = 13;
+    WorkerCommandReply worker_command_reply = 14;
+    WorkerCancel worker_cancel = 15;
+    WorkerShutdown worker_shutdown = 16;
+    WorkerShutdownAck worker_shutdown_ack = 17;
+    WorkerEvent worker_event = 18;
+    WorkerHeartbeat worker_heartbeat = 19;
+    WorkerFault worker_fault = 20;
+  }
+}
+
+message GatewayHello {
+  uint32 supported_protocol_version = 1;
+  string nonce = 2;
+  string gateway_version = 3;
+}
+
+message WorkerHello {
+  uint32 protocol_version = 1;
+  string nonce = 2;
+  int32 worker_process_id = 3;
+  string worker_version = 4;
+}
+
+message WorkerReady {
+  int32 worker_process_id = 1;
+  string mxaccess_progid = 2;
+  string mxaccess_clsid = 3;
+  google.protobuf.Timestamp ready_timestamp = 4;
+}
+
+message WorkerCommand {
+  mxaccess_gateway.v1.MxCommand command = 1;
+  google.protobuf.Timestamp enqueue_timestamp = 2;
+}
+
+message WorkerCommandReply {
+  mxaccess_gateway.v1.MxCommandReply reply = 1;
+  google.protobuf.Timestamp completed_timestamp = 2;
+}
+
+message WorkerCancel {
+  string reason = 1;
+}
+
+message WorkerShutdown {
+  google.protobuf.Duration grace_period = 1;
+  string reason = 2;
+}
+
+message WorkerShutdownAck {
+  mxaccess_gateway.v1.ProtocolStatus status = 1;
+}
+
+message WorkerEvent {
+  mxaccess_gateway.v1.MxEvent event = 1;
+}
+
+message WorkerHeartbeat {
+  int32 worker_process_id = 1;
+  WorkerState state = 2;
+  google.protobuf.Timestamp last_sta_activity_timestamp = 3;
+  uint32 pending_command_count = 4;
+  uint32 outbound_event_queue_depth = 5;
+  uint64 last_event_sequence = 6;
+  string current_command_correlation_id = 7;
+}
+
+message WorkerFault {
+  WorkerFaultCategory category = 1;
+  string command_method = 2;
+  optional int32 hresult = 3;
+  string exception_type = 4;
+  string diagnostic_message = 5;
+  mxaccess_gateway.v1.ProtocolStatus protocol_status = 6;
+}
+
+enum WorkerState {
+  WORKER_STATE_UNSPECIFIED = 0;
+  WORKER_STATE_STARTING = 1;
+  WORKER_STATE_HANDSHAKING = 2;
+  WORKER_STATE_INITIALIZING_STA = 3;
+  WORKER_STATE_READY = 4;
+  WORKER_STATE_EXECUTING_COMMAND = 5;
+  WORKER_STATE_SHUTTING_DOWN = 6;
+  WORKER_STATE_STOPPED = 7;
+  WORKER_STATE_FAULTED = 8;
+}
+
+enum WorkerFaultCategory {
+  WORKER_FAULT_CATEGORY_UNSPECIFIED = 0;
+  WORKER_FAULT_CATEGORY_INVALID_ARGUMENTS = 1;
+  WORKER_FAULT_CATEGORY_GATEWAY_AUTHENTICATION_FAILED = 2;
+  WORKER_FAULT_CATEGORY_PROTOCOL_MISMATCH = 3;
+  WORKER_FAULT_CATEGORY_PROTOCOL_VIOLATION = 4;
+  WORKER_FAULT_CATEGORY_PIPE_DISCONNECTED = 5;
+  WORKER_FAULT_CATEGORY_MXACCESS_CREATION_FAILED = 6;
+  WORKER_FAULT_CATEGORY_MXACCESS_COMMAND_FAILED = 7;
+  WORKER_FAULT_CATEGORY_MXACCESS_EVENT_CONVERSION_FAILED = 8;
+  WORKER_FAULT_CATEGORY_STA_HUNG = 9;
+  WORKER_FAULT_CATEGORY_QUEUE_OVERFLOW = 10;
+  WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT = 11;
+}

src/MxGateway.Server/Configuration/AuthenticationMode.cs

@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Configuration;
+
+public enum AuthenticationMode
+{
+    ApiKey,
+    Disabled
+}

src/MxGateway.Server/Configuration/AuthenticationOptions.cs

@@ -0,0 +1,12 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class AuthenticationOptions
+{
+    public AuthenticationMode Mode { get; init; } = AuthenticationMode.ApiKey;
+
+    public string SqlitePath { get; init; } = @"C:\ProgramData\MxGateway\gateway-auth.db";
+
+    public string PepperSecretName { get; init; } = "MxGateway:ApiKeyPepper";
+
+    public bool RunMigrationsOnStartup { get; init; } = true;
+}

src/MxGateway.Server/Configuration/DashboardOptions.cs

@@ -0,0 +1,20 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class DashboardOptions
+{
+    public bool Enabled { get; init; } = true;
+
+    public string PathBase { get; init; } = "/dashboard";
+
+    public bool RequireAdminScope { get; init; } = true;
+
+    public bool AllowAnonymousLocalhost { get; init; }
+
+    public int SnapshotIntervalMilliseconds { get; init; } = 1_000;
+
+    public int RecentFaultLimit { get; init; } = 100;
+
+    public int RecentSessionLimit { get; init; } = 200;
+
+    public bool ShowTagValues { get; init; }
+}

src/MxGateway.Server/Configuration/EffectiveAuthenticationConfiguration.cs

@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveAuthenticationConfiguration(
+    string Mode,
+    string SqlitePath,
+    string PepperSecretName,
+    bool RunMigrationsOnStartup);

src/MxGateway.Server/Configuration/EffectiveDashboardConfiguration.cs

@@ -0,0 +1,11 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveDashboardConfiguration(
+    bool Enabled,
+    string PathBase,
+    bool RequireAdminScope,
+    bool AllowAnonymousLocalhost,
+    int SnapshotIntervalMilliseconds,
+    int RecentFaultLimit,
+    int RecentSessionLimit,
+    bool ShowTagValues);

src/MxGateway.Server/Configuration/EffectiveEventConfiguration.cs

@@ -0,0 +1,5 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveEventConfiguration(
+    int QueueCapacity,
+    string BackpressurePolicy);

src/MxGateway.Server/Configuration/EffectiveGatewayConfiguration.cs

@@ -0,0 +1,9 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveGatewayConfiguration(
+    EffectiveAuthenticationConfiguration Authentication,
+    EffectiveWorkerConfiguration Worker,
+    EffectiveSessionConfiguration Sessions,
+    EffectiveEventConfiguration Events,
+    EffectiveDashboardConfiguration Dashboard,
+    EffectiveProtocolConfiguration Protocol);

src/MxGateway.Server/Configuration/EffectiveProtocolConfiguration.cs

@@ -0,0 +1,3 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveProtocolConfiguration(uint WorkerProtocolVersion);

src/MxGateway.Server/Configuration/EffectiveSessionConfiguration.cs

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveSessionConfiguration(
+    int DefaultCommandTimeoutSeconds,
+    int MaxSessions,
+    bool AllowMultipleEventSubscribers);

src/MxGateway.Server/Configuration/EffectiveWorkerConfiguration.cs

@@ -0,0 +1,11 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveWorkerConfiguration(
+    string ExecutablePath,
+    string? WorkingDirectory,
+    string RequiredArchitecture,
+    int StartupTimeoutSeconds,
+    int ShutdownTimeoutSeconds,
+    int HeartbeatIntervalSeconds,
+    int HeartbeatGraceSeconds,
+    int MaxMessageBytes);

src/MxGateway.Server/Configuration/EventBackpressurePolicy.cs

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Configuration;
+
+public enum EventBackpressurePolicy
+{
+    FailFast
+}

src/MxGateway.Server/Configuration/EventOptions.cs

@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class EventOptions
+{
+    public int QueueCapacity { get; init; } = 10_000;
+
+    public EventBackpressurePolicy BackpressurePolicy { get; init; } = EventBackpressurePolicy.FailFast;
+}

src/MxGateway.Server/Configuration/GatewayConfigurationProvider.cs

@@ -0,0 +1,46 @@
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Configuration;
+
+public sealed class GatewayConfigurationProvider(IOptions<GatewayOptions> options) : IGatewayConfigurationProvider
+{
+    public const string RedactedValue = "[redacted]";
+
+    public EffectiveGatewayConfiguration GetEffectiveConfiguration()
+    {
+        GatewayOptions value = options.Value;
+
+        return new EffectiveGatewayConfiguration(
+            Authentication: new EffectiveAuthenticationConfiguration(
+                Mode: value.Authentication.Mode.ToString(),
+                SqlitePath: value.Authentication.SqlitePath,
+                PepperSecretName: RedactedValue,
+                RunMigrationsOnStartup: value.Authentication.RunMigrationsOnStartup),
+            Worker: new EffectiveWorkerConfiguration(
+                ExecutablePath: value.Worker.ExecutablePath,
+                WorkingDirectory: value.Worker.WorkingDirectory,
+                RequiredArchitecture: value.Worker.RequiredArchitecture.ToString(),
+                StartupTimeoutSeconds: value.Worker.StartupTimeoutSeconds,
+                ShutdownTimeoutSeconds: value.Worker.ShutdownTimeoutSeconds,
+                HeartbeatIntervalSeconds: value.Worker.HeartbeatIntervalSeconds,
+                HeartbeatGraceSeconds: value.Worker.HeartbeatGraceSeconds,
+                MaxMessageBytes: value.Worker.MaxMessageBytes),
+            Sessions: new EffectiveSessionConfiguration(
+                DefaultCommandTimeoutSeconds: value.Sessions.DefaultCommandTimeoutSeconds,
+                MaxSessions: value.Sessions.MaxSessions,
+                AllowMultipleEventSubscribers: value.Sessions.AllowMultipleEventSubscribers),
+            Events: new EffectiveEventConfiguration(
+                QueueCapacity: value.Events.QueueCapacity,
+                BackpressurePolicy: value.Events.BackpressurePolicy.ToString()),
+            Dashboard: new EffectiveDashboardConfiguration(
+                Enabled: value.Dashboard.Enabled,
+                PathBase: value.Dashboard.PathBase,
+                RequireAdminScope: value.Dashboard.RequireAdminScope,
+                AllowAnonymousLocalhost: value.Dashboard.AllowAnonymousLocalhost,
+                SnapshotIntervalMilliseconds: value.Dashboard.SnapshotIntervalMilliseconds,
+                RecentFaultLimit: value.Dashboard.RecentFaultLimit,
+                RecentSessionLimit: value.Dashboard.RecentSessionLimit,
+                ShowTagValues: value.Dashboard.ShowTagValues),
+            Protocol: new EffectiveProtocolConfiguration(value.Protocol.WorkerProtocolVersion));
+    }
+}

src/MxGateway.Server/Configuration/GatewayConfigurationServiceCollectionExtensions.cs

@@ -0,0 +1,19 @@
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Configuration;
+
+public static class GatewayConfigurationServiceCollectionExtensions
+{
+    public static IServiceCollection AddGatewayConfiguration(this IServiceCollection services)
+    {
+        services
+            .AddOptions<GatewayOptions>()
+            .BindConfiguration(GatewayOptions.SectionName)
+            .ValidateOnStart();
+
+        services.AddSingleton<IValidateOptions<GatewayOptions>, GatewayOptionsValidator>();
+        services.AddSingleton<IGatewayConfigurationProvider, GatewayConfigurationProvider>();
+
+        return services;
+    }
+}

src/MxGateway.Server/Configuration/GatewayOptions.cs

@@ -0,0 +1,18 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class GatewayOptions
+{
+    public const string SectionName = "MxGateway";
+
+    public AuthenticationOptions Authentication { get; init; } = new();
+
+    public WorkerOptions Worker { get; init; } = new();
+
+    public SessionOptions Sessions { get; init; } = new();
+
+    public EventOptions Events { get; init; } = new();
+
+    public DashboardOptions Dashboard { get; init; } = new();
+
+    public ProtocolOptions Protocol { get; init; } = new();
+}

src/MxGateway.Server/Configuration/GatewayOptionsValidator.cs

@@ -0,0 +1,210 @@
+using Microsoft.Extensions.Options;
+using MxGateway.Contracts;
+
+namespace MxGateway.Server.Configuration;
+
+public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
+{
+    private const int MinimumMaxMessageBytes = 1024;
+    private const int MaximumMaxMessageBytes = 256 * 1024 * 1024;
+
+    public ValidateOptionsResult Validate(string? name, GatewayOptions options)
+    {
+        List<string> failures = [];
+
+        ValidateAuthentication(options.Authentication, failures);
+        ValidateWorker(options.Worker, failures);
+        ValidateSessions(options.Sessions, failures);
+        ValidateEvents(options.Events, failures);
+        ValidateDashboard(options.Dashboard, failures);
+        ValidateProtocol(options.Protocol, failures);
+
+        return failures.Count == 0
+            ? ValidateOptionsResult.Success
+            : ValidateOptionsResult.Fail(failures);
+    }
+
+    private static void ValidateAuthentication(AuthenticationOptions options, List<string> failures)
+    {
+        if (!Enum.IsDefined(options.Mode))
+        {
+            failures.Add("MxGateway:Authentication:Mode must be a supported authentication mode.");
+            return;
+        }
+
+        if (options.Mode == AuthenticationMode.ApiKey)
+        {
+            AddIfBlank(
+                options.SqlitePath,
+                "MxGateway:Authentication:SqlitePath is required when API-key authentication is enabled.",
+                failures);
+            AddIfInvalidPath(
+                options.SqlitePath,
+                "MxGateway:Authentication:SqlitePath must be a valid filesystem path.",
+                failures);
+            AddIfBlank(
+                options.PepperSecretName,
+                "MxGateway:Authentication:PepperSecretName is required when API-key authentication is enabled.",
+                failures);
+        }
+    }
+
+    private static void ValidateWorker(WorkerOptions options, List<string> failures)
+    {
+        AddIfBlank(options.ExecutablePath, "MxGateway:Worker:ExecutablePath is required.", failures);
+        AddIfInvalidPath(
+            options.ExecutablePath,
+            "MxGateway:Worker:ExecutablePath must be a valid filesystem path.",
+            failures);
+
+        if (!string.IsNullOrWhiteSpace(options.ExecutablePath)
+            && !string.Equals(Path.GetExtension(options.ExecutablePath), ".exe", StringComparison.OrdinalIgnoreCase))
+        {
+            failures.Add("MxGateway:Worker:ExecutablePath must point to a .exe file.");
+        }
+
+        if (!string.IsNullOrWhiteSpace(options.WorkingDirectory))
+        {
+            AddIfInvalidPath(
+                options.WorkingDirectory,
+                "MxGateway:Worker:WorkingDirectory must be a valid filesystem path.",
+                failures);
+        }
+
+        if (!Enum.IsDefined(options.RequiredArchitecture))
+        {
+            failures.Add("MxGateway:Worker:RequiredArchitecture must be a supported worker architecture.");
+        }
+
+        AddIfNotPositive(
+            options.StartupTimeoutSeconds,
+            "MxGateway:Worker:StartupTimeoutSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(
+            options.ShutdownTimeoutSeconds,
+            "MxGateway:Worker:ShutdownTimeoutSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(
+            options.HeartbeatIntervalSeconds,
+            "MxGateway:Worker:HeartbeatIntervalSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(
+            options.HeartbeatGraceSeconds,
+            "MxGateway:Worker:HeartbeatGraceSeconds must be greater than zero.",
+            failures);
+
+        if (options.HeartbeatGraceSeconds < options.HeartbeatIntervalSeconds)
+        {
+            failures.Add(
+                "MxGateway:Worker:HeartbeatGraceSeconds must be greater than or equal to HeartbeatIntervalSeconds.");
+        }
+
+        if (options.MaxMessageBytes is < MinimumMaxMessageBytes or > MaximumMaxMessageBytes)
+        {
+            failures.Add(
+                $"MxGateway:Worker:MaxMessageBytes must be between {MinimumMaxMessageBytes} and {MaximumMaxMessageBytes}.");
+        }
+    }
+
+    private static void ValidateSessions(SessionOptions options, List<string> failures)
+    {
+        AddIfNotPositive(
+            options.DefaultCommandTimeoutSeconds,
+            "MxGateway:Sessions:DefaultCommandTimeoutSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(options.MaxSessions, "MxGateway:Sessions:MaxSessions must be greater than zero.", failures);
+    }
+
+    private static void ValidateEvents(EventOptions options, List<string> failures)
+    {
+        AddIfNotPositive(options.QueueCapacity, "MxGateway:Events:QueueCapacity must be greater than zero.", failures);
+
+        if (!Enum.IsDefined(options.BackpressurePolicy))
+        {
+            failures.Add("MxGateway:Events:BackpressurePolicy must be a supported backpressure policy.");
+        }
+    }
+
+    private static void ValidateDashboard(DashboardOptions options, List<string> failures)
+    {
+        if (options.Enabled)
+        {
+            AddIfBlank(options.PathBase, "MxGateway:Dashboard:PathBase is required when the dashboard is enabled.", failures);
+            if (!string.IsNullOrWhiteSpace(options.PathBase) && !options.PathBase.StartsWith('/'))
+            {
+                failures.Add("MxGateway:Dashboard:PathBase must start with '/'.");
+            }
+        }
+
+        AddIfNotPositive(
+            options.SnapshotIntervalMilliseconds,
+            "MxGateway:Dashboard:SnapshotIntervalMilliseconds must be greater than zero.",
+            failures);
+        AddIfNegative(
+            options.RecentFaultLimit,
+            "MxGateway:Dashboard:RecentFaultLimit must be greater than or equal to zero.",
+            failures);
+        AddIfNegative(
+            options.RecentSessionLimit,
+            "MxGateway:Dashboard:RecentSessionLimit must be greater than or equal to zero.",
+            failures);
+    }
+
+    private static void ValidateProtocol(ProtocolOptions options, List<string> failures)
+    {
+        if (options.WorkerProtocolVersion != GatewayContractInfo.WorkerProtocolVersion)
+        {
+            failures.Add(
+                $"MxGateway:Protocol:WorkerProtocolVersion must be {GatewayContractInfo.WorkerProtocolVersion}.");
+        }
+    }
+
+    private static void AddIfBlank(string? value, string message, List<string> failures)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            failures.Add(message);
+        }
+    }
+
+    private static void AddIfNotPositive(int value, string message, List<string> failures)
+    {
+        if (value <= 0)
+        {
+            failures.Add(message);
+        }
+    }
+
+    private static void AddIfNegative(int value, string message, List<string> failures)
+    {
+        if (value < 0)
+        {
+            failures.Add(message);
+        }
+    }
+
+    private static void AddIfInvalidPath(string? value, string message, List<string> failures)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return;
+        }
+
+        try
+        {
+            _ = Path.GetFullPath(value);
+        }
+        catch (ArgumentException)
+        {
+            failures.Add(message);
+        }
+        catch (NotSupportedException)
+        {
+            failures.Add(message);
+        }
+        catch (PathTooLongException)
+        {
+            failures.Add(message);
+        }
+    }
+}

src/MxGateway.Server/Configuration/IGatewayConfigurationProvider.cs

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Configuration;
+
+public interface IGatewayConfigurationProvider
+{
+    EffectiveGatewayConfiguration GetEffectiveConfiguration();
+}

src/MxGateway.Server/Configuration/ProtocolOptions.cs

@@ -0,0 +1,8 @@
+using MxGateway.Contracts;
+
+namespace MxGateway.Server.Configuration;
+
+public sealed class ProtocolOptions
+{
+    public uint WorkerProtocolVersion { get; init; } = GatewayContractInfo.WorkerProtocolVersion;
+}

src/MxGateway.Server/Configuration/SessionOptions.cs

@@ -0,0 +1,10 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class SessionOptions
+{
+    public int DefaultCommandTimeoutSeconds { get; init; } = 30;
+
+    public int MaxSessions { get; init; } = 64;
+
+    public bool AllowMultipleEventSubscribers { get; init; }
+}

src/MxGateway.Server/Configuration/WorkerArchitecture.cs

@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Configuration;
+
+public enum WorkerArchitecture
+{
+    X86,
+    X64
+}

src/MxGateway.Server/Configuration/WorkerOptions.cs

@@ -0,0 +1,21 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class WorkerOptions
+{
+    public string ExecutablePath { get; init; } =
+        @"src\MxGateway.Worker\bin\x86\Release\MxGateway.Worker.exe";
+
+    public string? WorkingDirectory { get; init; }
+
+    public WorkerArchitecture RequiredArchitecture { get; init; } = WorkerArchitecture.X86;
+
+    public int StartupTimeoutSeconds { get; init; } = 30;
+
+    public int ShutdownTimeoutSeconds { get; init; } = 10;
+
+    public int HeartbeatIntervalSeconds { get; init; } = 5;
+
+    public int HeartbeatGraceSeconds { get; init; } = 15;
+
+    public int MaxMessageBytes { get; init; } = 16 * 1024 * 1024;
+}

src/MxGateway.Server/Dashboard/Components/App.razor

@@ -0,0 +1,34 @@
+@inject IOptions<GatewayOptions> GatewayOptions
+
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <base href="@DashboardBaseHref" />
+    <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
+    <link rel="stylesheet" href="/css/dashboard.css" />
+    <HeadOutlet @rendermode="InteractiveServer" />
+</head>
+<body class="dashboard-body">
+    <Routes @rendermode="InteractiveServer" />
+    <script src="/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
+    <script src="_framework/blazor.web.js"></script>
+</body>
+</html>
+
+@code {
+    private string DashboardBaseHref
+    {
+        get
+        {
+            string pathBase = GatewayOptions.Value.Dashboard.PathBase.TrimEnd('/');
+            if (string.IsNullOrWhiteSpace(pathBase))
+            {
+                pathBase = "/dashboard";
+            }
+
+            return $"{pathBase}/";
+        }
+    }
+}

src/MxGateway.Server/Dashboard/Components/DashboardDisplay.cs

@@ -0,0 +1,30 @@
+namespace MxGateway.Server.Dashboard.Components;
+
+public static class DashboardDisplay
+{
+    public static string DateTime(DateTimeOffset? value)
+    {
+        return value.HasValue
+            ? value.Value.UtcDateTime.ToString("yyyy-MM-dd HH:mm:ss 'UTC'", System.Globalization.CultureInfo.InvariantCulture)
+            : "-";
+    }
+
+    public static string Duration(TimeSpan value)
+    {
+        return value.TotalDays >= 1
+            ? value.ToString(@"d\.hh\:mm\:ss", System.Globalization.CultureInfo.InvariantCulture)
+            : value.ToString(@"hh\:mm\:ss", System.Globalization.CultureInfo.InvariantCulture);
+    }
+
+    public static string Text(string? value)
+    {
+        return string.IsNullOrWhiteSpace(value) ? "-" : value;
+    }
+
+    public static long MetricValue(DashboardSnapshot snapshot, string name, string? dimension = null)
+    {
+        return snapshot.Metrics.FirstOrDefault(metric =>
+            string.Equals(metric.Name, name, StringComparison.Ordinal)
+            && string.Equals(metric.Dimension, dimension, StringComparison.Ordinal))?.Value ?? 0;
+    }
+}

src/MxGateway.Server/Dashboard/Components/DashboardPageBase.cs

@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Components;
+
+namespace MxGateway.Server.Dashboard.Components;
+
+public abstract class DashboardPageBase : ComponentBase, IAsyncDisposable
+{
+    private readonly CancellationTokenSource _disposeCancellation = new();
+    private Task? _watchTask;
+
+    [Inject]
+    protected IDashboardSnapshotService SnapshotService { get; set; } = null!;
+
+    protected DashboardSnapshot? Snapshot { get; private set; }
+
+    protected override void OnInitialized()
+    {
+        _watchTask = WatchSnapshotsAsync();
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await _disposeCancellation.CancelAsync().ConfigureAwait(false);
+        if (_watchTask is not null)
+        {
+            await _watchTask.ConfigureAwait(false);
+        }
+
+        _disposeCancellation.Dispose();
+        GC.SuppressFinalize(this);
+    }
+
+    private async Task WatchSnapshotsAsync()
+    {
+        try
+        {
+            await foreach (DashboardSnapshot snapshot in SnapshotService
+                .WatchSnapshotsAsync(_disposeCancellation.Token)
+                .ConfigureAwait(false))
+            {
+                Snapshot = snapshot;
+                await InvokeAsync(StateHasChanged).ConfigureAwait(false);
+            }
+        }
+        catch (OperationCanceledException) when (_disposeCancellation.IsCancellationRequested)
+        {
+        }
+    }
+}

src/MxGateway.Server/Dashboard/Components/Layout/DashboardLayout.razor

@@ -0,0 +1,53 @@
+@inherits LayoutComponentBase
+@inject IOptions<GatewayOptions> GatewayOptions
+
+<div class="dashboard-shell">
+    <nav class="navbar navbar-expand-lg bg-body border-bottom dashboard-navbar">
+        <div class="container-fluid">
+            <a class="navbar-brand" href="">MXAccess Gateway</a>
+            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#dashboardNav"
+                    aria-controls="dashboardNav" aria-expanded="false" aria-label="Toggle navigation">
+                <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="dashboardNav">
+                <ul class="navbar-nav me-auto mb-2 mb-lg-0">
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="" Match="NavLinkMatch.All">Overview</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="sessions">Sessions</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="workers">Workers</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="events">Events</NavLink>
+                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="settings">Settings</NavLink>
+                    </li>
+                </ul>
+                <form method="post" action="@DashboardPath("/logout")" class="d-flex">
+                    <AntiforgeryToken />
+                    <button class="btn btn-outline-secondary btn-sm" type="submit">Sign out</button>
+                </form>
+            </div>
+        </div>
+    </nav>
+    <main class="container-fluid dashboard-content">
+        @Body
+    </main>
+</div>
+
+@code {
+    private string DashboardPath(string relativePath)
+    {
+        string pathBase = GatewayOptions.Value.Dashboard.PathBase.TrimEnd('/');
+        if (string.IsNullOrWhiteSpace(pathBase))
+        {
+            pathBase = "/dashboard";
+        }
+
+        return $"{pathBase}{relativePath}";
+    }
+}

src/MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor

@@ -0,0 +1,37 @@
+@page "/"
+@inherits DashboardPageBase
+
+<PageTitle>MXAccess Gateway Dashboard</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading dashboard snapshot.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Overview</h1>
+            <div class="text-secondary">Generated @DashboardDisplay.DateTime(Snapshot.GeneratedAt)</div>
+        </div>
+        <StatusBadge Text="@Snapshot.GatewayStatus" />
+    </div>
+
+    <section class="metric-grid">
+        <MetricCard Label="Uptime" Value="@DashboardDisplay.Duration(Snapshot.GatewayUptime)" Detail="@Snapshot.GatewayVersion" />
+        <MetricCard Label="Open Sessions" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.sessions.open").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Workers Running" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.workers.running").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Event Queue Depth" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.queue.depth").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Commands Failed" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.commands.failed").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Events Received" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.received").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Faults" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.faults").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Queue Overflows" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.queues.overflows").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Recent Faults</h2>
+        </div>
+        <FaultList Faults="@Snapshot.Faults" />
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Pages/EventsPage.razor

@@ -0,0 +1,64 @@
+@page "/events"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Events</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading event diagnostics.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Events</h1>
+            <div class="text-secondary">Generated @DashboardDisplay.DateTime(Snapshot.GeneratedAt)</div>
+        </div>
+    </div>
+
+    <section class="metric-grid compact">
+        <MetricCard Label="Events Received" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.received").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Event Queue Depth" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.events.queue.depth").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Queue Overflows" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.queues.overflows").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+        <MetricCard Label="Stream Disconnects" Value="@DashboardDisplay.MetricValue(Snapshot, "mxgateway.grpc.streams.disconnected").ToString(System.Globalization.CultureInfo.InvariantCulture)" />
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Event Families</h2>
+        </div>
+        @if (EventFamilyMetrics.Count == 0)
+        {
+            <div class="empty-state">No event family counters recorded.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Family</th>
+                            <th scope="col">Count</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardMetricSummary metric in EventFamilyMetrics)
+                        {
+                            <tr>
+                                <td>@metric.Dimension</td>
+                                <td>@metric.Value</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}
+
+@code {
+    private IReadOnlyList<DashboardMetricSummary> EventFamilyMetrics => Snapshot?.Metrics
+        .Where(metric => metric.Name == "mxgateway.events.received" && metric.Dimension is not null)
+        .OrderBy(metric => metric.Dimension, StringComparer.OrdinalIgnoreCase)
+        .ToArray() ?? [];
+}

src/MxGateway.Server/Dashboard/Components/Pages/SessionDetailsPage.razor

@@ -0,0 +1,69 @@
+@page "/sessions/{SessionId}"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Session</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading session.</div>
+}
+else if (CurrentSession is null)
+{
+    <section class="dashboard-section">
+        <h1 class="h4 mb-3">Session Not Found</h1>
+        <p class="mb-0">The session is not present in the current snapshot.</p>
+    </section>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Session Details</h1>
+            <div class="text-secondary"><code>@CurrentSession.SessionId</code></div>
+        </div>
+        <StatusBadge Text="@CurrentSession.State.ToString()" />
+    </div>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Session</h2>
+        </div>
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Backend</th><td>@CurrentSession.BackendName</td></tr>
+                    <tr><th scope="row">Client identity</th><td>@DashboardDisplay.Text(CurrentSession.ClientIdentity)</td></tr>
+                    <tr><th scope="row">Client session</th><td>@DashboardDisplay.Text(CurrentSession.ClientSessionName)</td></tr>
+                    <tr><th scope="row">Client correlation</th><td>@DashboardDisplay.Text(CurrentSession.ClientCorrelationId)</td></tr>
+                    <tr><th scope="row">Opened</th><td>@DashboardDisplay.DateTime(CurrentSession.OpenedAt)</td></tr>
+                    <tr><th scope="row">Last activity</th><td>@DashboardDisplay.DateTime(CurrentSession.LastClientActivityAt)</td></tr>
+                    <tr><th scope="row">Lease expires</th><td>@DashboardDisplay.DateTime(CurrentSession.LeaseExpiresAt)</td></tr>
+                    <tr><th scope="row">Last fault</th><td>@DashboardDisplay.Text(CurrentSession.LastFault)</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Worker</h2>
+        </div>
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Process id</th><td>@(CurrentSession.WorkerProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")</td></tr>
+                    <tr><th scope="row">State</th><td><StatusBadge Text="@(CurrentSession.WorkerState?.ToString() ?? "-")" /></td></tr>
+                    <tr><th scope="row">Last heartbeat</th><td>@DashboardDisplay.DateTime(CurrentSession.LastWorkerHeartbeatAt)</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+}
+
+@code {
+    [Parameter]
+    public string SessionId { get; set; } = string.Empty;
+
+    private DashboardSessionSummary? CurrentSession => Snapshot?.Sessions.FirstOrDefault(session =>
+        string.Equals(session.SessionId, SessionId, StringComparison.Ordinal));
+}

src/MxGateway.Server/Dashboard/Components/Pages/SessionsPage.razor

@@ -0,0 +1,67 @@
+@page "/sessions"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Sessions</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading sessions.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Sessions</h1>
+            <div class="text-secondary">@Snapshot.Sessions.Count session rows</div>
+        </div>
+    </div>
+
+    <section class="dashboard-section">
+        @if (Snapshot.Sessions.Count == 0)
+        {
+            <div class="empty-state">No sessions are active or retained.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm align-middle dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Session</th>
+                            <th scope="col">State</th>
+                            <th scope="col">Client</th>
+                            <th scope="col">Backend</th>
+                            <th scope="col">Worker</th>
+                            <th scope="col">Opened</th>
+                            <th scope="col">Activity</th>
+                            <th scope="col">Heartbeat</th>
+                            <th scope="col">Fault</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardSessionSummary session in Snapshot.Sessions)
+                        {
+                            <tr>
+                                <td><NavLink href="@($"sessions/{Uri.EscapeDataString(session.SessionId)}")"><code>@session.SessionId</code></NavLink></td>
+                                <td><StatusBadge Text="@session.State.ToString()" /></td>
+                                <td>@DashboardDisplay.Text(session.ClientIdentity)</td>
+                                <td>@session.BackendName</td>
+                                <td>
+                                    @(session.WorkerProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")
+                                    @if (session.WorkerState is not null)
+                                    {
+                                        <span class="ms-1"><StatusBadge Text="@session.WorkerState.ToString()" /></span>
+                                    }
+                                </td>
+                                <td>@DashboardDisplay.DateTime(session.OpenedAt)</td>
+                                <td>@DashboardDisplay.DateTime(session.LastClientActivityAt)</td>
+                                <td>@DashboardDisplay.DateTime(session.LastWorkerHeartbeatAt)</td>
+                                <td>@DashboardDisplay.Text(session.LastFault)</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Pages/SettingsPage.razor

@@ -0,0 +1,47 @@
+@page "/settings"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Settings</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading settings.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Settings</h1>
+            <div class="text-secondary">Effective gateway configuration</div>
+        </div>
+    </div>
+
+    <section class="dashboard-section">
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Authentication mode</th><td>@Snapshot.Configuration.Authentication.Mode</td></tr>
+                    <tr><th scope="row">Auth database</th><td><code>@Snapshot.Configuration.Authentication.SqlitePath</code></td></tr>
+                    <tr><th scope="row">Pepper secret</th><td>@Snapshot.Configuration.Authentication.PepperSecretName</td></tr>
+                    <tr><th scope="row">Run migrations</th><td>@Snapshot.Configuration.Authentication.RunMigrationsOnStartup</td></tr>
+                    <tr><th scope="row">Worker executable</th><td><code>@Snapshot.Configuration.Worker.ExecutablePath</code></td></tr>
+                    <tr><th scope="row">Worker architecture</th><td>@Snapshot.Configuration.Worker.RequiredArchitecture</td></tr>
+                    <tr><th scope="row">Startup timeout</th><td>@Snapshot.Configuration.Worker.StartupTimeoutSeconds seconds</td></tr>
+                    <tr><th scope="row">Shutdown timeout</th><td>@Snapshot.Configuration.Worker.ShutdownTimeoutSeconds seconds</td></tr>
+                    <tr><th scope="row">Heartbeat grace</th><td>@Snapshot.Configuration.Worker.HeartbeatGraceSeconds seconds</td></tr>
+                    <tr><th scope="row">Default command timeout</th><td>@Snapshot.Configuration.Sessions.DefaultCommandTimeoutSeconds seconds</td></tr>
+                    <tr><th scope="row">Max sessions</th><td>@Snapshot.Configuration.Sessions.MaxSessions</td></tr>
+                    <tr><th scope="row">Event queue capacity</th><td>@Snapshot.Configuration.Events.QueueCapacity</td></tr>
+                    <tr><th scope="row">Backpressure policy</th><td>@Snapshot.Configuration.Events.BackpressurePolicy</td></tr>
+                    <tr><th scope="row">Dashboard enabled</th><td>@Snapshot.Configuration.Dashboard.Enabled</td></tr>
+                    <tr><th scope="row">Dashboard path</th><td>@Snapshot.Configuration.Dashboard.PathBase</td></tr>
+                    <tr><th scope="row">Require admin scope</th><td>@Snapshot.Configuration.Dashboard.RequireAdminScope</td></tr>
+                    <tr><th scope="row">Anonymous localhost</th><td>@Snapshot.Configuration.Dashboard.AllowAnonymousLocalhost</td></tr>
+                    <tr><th scope="row">Snapshot interval</th><td>@Snapshot.Configuration.Dashboard.SnapshotIntervalMilliseconds ms</td></tr>
+                    <tr><th scope="row">Show tag values</th><td>@Snapshot.Configuration.Dashboard.ShowTagValues</td></tr>
+                    <tr><th scope="row">Worker protocol</th><td>@Snapshot.Configuration.Protocol.WorkerProtocolVersion</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Pages/WorkersPage.razor

@@ -0,0 +1,53 @@
+@page "/workers"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Workers</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading workers.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Workers</h1>
+            <div class="text-secondary">@Snapshot.Workers.Count worker rows</div>
+        </div>
+    </div>
+
+    <section class="dashboard-section">
+        @if (Snapshot.Workers.Count == 0)
+        {
+            <div class="empty-state">No worker processes are attached.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm align-middle dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Process</th>
+                            <th scope="col">State</th>
+                            <th scope="col">Session</th>
+                            <th scope="col">Heartbeat</th>
+                            <th scope="col">Fault</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardWorkerSummary worker in Snapshot.Workers)
+                        {
+                            <tr>
+                                <td>@(worker.ProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")</td>
+                                <td><StatusBadge Text="@worker.State.ToString()" /></td>
+                                <td><NavLink href="@($"sessions/{Uri.EscapeDataString(worker.SessionId)}")"><code>@worker.SessionId</code></NavLink></td>
+                                <td>@DashboardDisplay.DateTime(worker.LastHeartbeatAt)</td>
+                                <td>@DashboardDisplay.Text(worker.LastFault)</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+}

src/MxGateway.Server/Dashboard/Components/Routes.razor

@@ -0,0 +1,15 @@
+<Router AppAssembly="@typeof(Routes).Assembly">
+    <Found Context="routeData">
+        <RouteView RouteData="@routeData" DefaultLayout="@typeof(DashboardLayout)" />
+        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
+    </Found>
+    <NotFound>
+        <LayoutView Layout="@typeof(DashboardLayout)">
+            <PageTitle>Dashboard - Not Found</PageTitle>
+            <section class="dashboard-section">
+                <h1 class="h4 mb-3">Not Found</h1>
+                <p class="mb-0">The requested dashboard page does not exist.</p>
+            </section>
+        </LayoutView>
+    </NotFound>
+</Router>

src/MxGateway.Server/Dashboard/Components/Shared/FaultList.razor

@@ -0,0 +1,39 @@
+@if (Faults.Count == 0)
+{
+    <div class="empty-state">No faults recorded.</div>
+}
+else
+{
+    <div class="table-responsive">
+        <table class="table table-sm align-middle dashboard-table">
+            <thead>
+                <tr>
+                    <th scope="col">Observed</th>
+                    <th scope="col">Source</th>
+                    <th scope="col">Session</th>
+                    <th scope="col">Worker</th>
+                    <th scope="col">State</th>
+                    <th scope="col">Message</th>
+                </tr>
+            </thead>
+            <tbody>
+                @foreach (DashboardFaultSummary fault in Faults)
+                {
+                    <tr>
+                        <td>@DashboardDisplay.DateTime(fault.ObservedAt)</td>
+                        <td>@fault.Source</td>
+                        <td><code>@DashboardDisplay.Text(fault.SessionId)</code></td>
+                        <td>@(fault.WorkerProcessId?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "-")</td>
+                        <td><StatusBadge Text="@fault.State" /></td>
+                        <td>@fault.Message</td>
+                    </tr>
+                }
+            </tbody>
+        </table>
+    </div>
+}
+
+@code {
+    [Parameter]
+    public IReadOnlyList<DashboardFaultSummary> Faults { get; set; } = [];
+}

src/MxGateway.Server/Dashboard/Components/Shared/MetricCard.razor

@@ -0,0 +1,21 @@
+<div class="card metric-card h-100">
+    <div class="card-body">
+        <div class="metric-label">@Label</div>
+        <div class="metric-value">@Value</div>
+        @if (!string.IsNullOrWhiteSpace(Detail))
+        {
+            <div class="metric-detail">@Detail</div>
+        }
+    </div>
+</div>
+
+@code {
+    [Parameter]
+    public string Label { get; set; } = string.Empty;
+
+    [Parameter]
+    public string Value { get; set; } = string.Empty;
+
+    [Parameter]
+    public string? Detail { get; set; }
+}

src/MxGateway.Server/Dashboard/Components/Shared/StatusBadge.razor

@@ -0,0 +1,15 @@
+<span class="badge @CssClass">@Text</span>
+
+@code {
+    [Parameter]
+    public string? Text { get; set; }
+
+    private string CssClass => Text switch
+    {
+        "Ready" or "Healthy" => "text-bg-success",
+        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing" => "text-bg-info",
+        "Closed" => "text-bg-secondary",
+        "Faulted" => "text-bg-danger",
+        _ => "text-bg-light text-dark border"
+    };
+}

src/MxGateway.Server/Dashboard/Components/_Imports.razor

@@ -0,0 +1,12 @@
+@using Microsoft.AspNetCore.Components.Authorization
+@using Microsoft.AspNetCore.Components.Forms
+@using Microsoft.AspNetCore.Components.Routing
+@using Microsoft.AspNetCore.Components.Web
+@using Microsoft.Extensions.Options
+@using MxGateway.Contracts.Proto
+@using MxGateway.Server.Configuration
+@using MxGateway.Server.Dashboard
+@using MxGateway.Server.Dashboard.Components.Layout
+@using MxGateway.Server.Dashboard.Components.Shared
+@using MxGateway.Server.Workers
+@using static Microsoft.AspNetCore.Components.Web.RenderMode

src/MxGateway.Server/Dashboard/DashboardAuthenticationDefaults.cs

@@ -0,0 +1,10 @@
+namespace MxGateway.Server.Dashboard;
+
+public static class DashboardAuthenticationDefaults
+{
+    public const string AuthenticationScheme = "MxGateway.Dashboard";
+    public const string AuthorizationPolicy = "MxGateway.Dashboard";
+    public const string ScopeClaimType = "scope";
+    public const string KeyPrefixClaimType = "mxgateway:key_prefix";
+    public const string CookieName = "__Host-MxGatewayDashboard";
+}

src/MxGateway.Server/Dashboard/DashboardAuthenticationResult.cs

@@ -0,0 +1,19 @@
+using System.Security.Claims;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardAuthenticationResult(
+    bool Succeeded,
+    ClaimsPrincipal? Principal,
+    string? FailureMessage)
+{
+    public static DashboardAuthenticationResult Success(ClaimsPrincipal principal)
+    {
+        return new DashboardAuthenticationResult(true, principal, null);
+    }
+
+    public static DashboardAuthenticationResult Fail(string failureMessage)
+    {
+        return new DashboardAuthenticationResult(false, null, failureMessage);
+    }
+}

src/MxGateway.Server/Dashboard/DashboardAuthenticator.cs

@@ -0,0 +1,81 @@
+using System.Security.Claims;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Security.Authorization;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed class DashboardAuthenticator(
+    IApiKeyVerifier apiKeyVerifier,
+    IOptions<GatewayOptions> options) : IDashboardAuthenticator
+{
+    private const string GenericFailureMessage = "The API key is invalid or is not authorized for dashboard access.";
+
+    public async Task<DashboardAuthenticationResult> AuthenticateAsync(
+        string? apiKey,
+        CancellationToken cancellationToken)
+    {
+        if (options.Value.Authentication.Mode == AuthenticationMode.Disabled)
+        {
+            return DashboardAuthenticationResult.Success(CreatePrincipal(new ApiKeyIdentity(
+                KeyId: "authentication-disabled",
+                KeyPrefix: "authentication-disabled",
+                DisplayName: "Authentication Disabled",
+                Scopes: new HashSet<string>([GatewayScopes.Admin], StringComparer.Ordinal))));
+        }
+
+        if (string.IsNullOrWhiteSpace(apiKey))
+        {
+            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
+        }
+
+        ApiKeyVerificationResult verificationResult = await apiKeyVerifier
+            .VerifyAsync(FormatAuthorizationHeader(apiKey), cancellationToken)
+            .ConfigureAwait(false);
+
+        if (!verificationResult.Succeeded || verificationResult.Identity is null)
+        {
+            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
+        }
+
+        if (options.Value.Dashboard.RequireAdminScope
+            && !verificationResult.Identity.Scopes.Contains(GatewayScopes.Admin))
+        {
+            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
+        }
+
+        return DashboardAuthenticationResult.Success(CreatePrincipal(verificationResult.Identity));
+    }
+
+    private static string FormatAuthorizationHeader(string apiKey)
+    {
+        string trimmedApiKey = apiKey.Trim();
+
+        return trimmedApiKey.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase)
+            ? trimmedApiKey
+            : $"Bearer {trimmedApiKey}";
+    }
+
+    private static ClaimsPrincipal CreatePrincipal(ApiKeyIdentity identity)
+    {
+        List<Claim> claims =
+        [
+            new Claim(ClaimTypes.NameIdentifier, identity.KeyId),
+            new Claim(ClaimTypes.Name, identity.DisplayName),
+            new Claim(DashboardAuthenticationDefaults.KeyPrefixClaimType, identity.KeyPrefix)
+        ];
+
+        claims.AddRange(identity.Scopes.Select(scope => new Claim(
+            DashboardAuthenticationDefaults.ScopeClaimType,
+            scope)));
+
+        ClaimsIdentity claimsIdentity = new(
+            claims,
+            DashboardAuthenticationDefaults.AuthenticationScheme,
+            ClaimTypes.Name,
+            DashboardAuthenticationDefaults.ScopeClaimType);
+
+        return new ClaimsPrincipal(claimsIdentity);
+    }
+}

src/MxGateway.Server/Dashboard/DashboardAuthorizationHandler.cs

@@ -0,0 +1,59 @@
+using System.Net;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authorization;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed class DashboardAuthorizationHandler(
+    IHttpContextAccessor httpContextAccessor,
+    IOptions<GatewayOptions> options) : AuthorizationHandler<DashboardAuthorizationRequirement>
+{
+    protected override Task HandleRequirementAsync(
+        AuthorizationHandlerContext context,
+        DashboardAuthorizationRequirement requirement)
+    {
+        GatewayOptions gatewayOptions = options.Value;
+
+        if (gatewayOptions.Authentication.Mode == AuthenticationMode.Disabled)
+        {
+            context.Succeed(requirement);
+
+            return Task.CompletedTask;
+        }
+
+        if (gatewayOptions.Dashboard.AllowAnonymousLocalhost && IsLoopbackRequest())
+        {
+            context.Succeed(requirement);
+
+            return Task.CompletedTask;
+        }
+
+        if (context.User.Identity?.IsAuthenticated != true)
+        {
+            return Task.CompletedTask;
+        }
+
+        if (!gatewayOptions.Dashboard.RequireAdminScope || HasAdminScope(context))
+        {
+            context.Succeed(requirement);
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private bool IsLoopbackRequest()
+    {
+        IPAddress? remoteAddress = httpContextAccessor.HttpContext?.Connection.RemoteIpAddress;
+
+        return remoteAddress is not null && IPAddress.IsLoopback(remoteAddress);
+    }
+
+    private static bool HasAdminScope(AuthorizationHandlerContext context)
+    {
+        return context.User.HasClaim(
+            DashboardAuthenticationDefaults.ScopeClaimType,
+            GatewayScopes.Admin);
+    }
+}

src/MxGateway.Server/Dashboard/DashboardAuthorizationRequirement.cs

@@ -0,0 +1,5 @@
+using Microsoft.AspNetCore.Authorization;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed class DashboardAuthorizationRequirement : IAuthorizationRequirement;

src/MxGateway.Server/Dashboard/DashboardEndpointRouteBuilderExtensions.cs

@@ -0,0 +1,197 @@
+using System.Text.Encodings.Web;
+using Microsoft.AspNetCore.Antiforgery;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Http.HttpResults;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Dashboard.Components;
+
+namespace MxGateway.Server.Dashboard;
+
+public static class DashboardEndpointRouteBuilderExtensions
+{
+    public static IEndpointRouteBuilder MapGatewayDashboard(this IEndpointRouteBuilder endpoints)
+    {
+        IConfiguration configuration = endpoints.ServiceProvider.GetRequiredService<IConfiguration>();
+        IConfigurationSection dashboardSection = configuration
+            .GetSection($"{GatewayOptions.SectionName}:Dashboard");
+
+        if (bool.TryParse(dashboardSection["Enabled"], out bool enabled) && !enabled)
+        {
+            return endpoints;
+        }
+
+        string pathBase = NormalizePathBase(dashboardSection["PathBase"] ?? new DashboardOptions().PathBase);
+        RouteGroupBuilder dashboard = endpoints.MapGroup(pathBase);
+
+        dashboard.MapGet(
+                "/login",
+                (HttpContext httpContext, IAntiforgery antiforgery) => GetLoginAsync(httpContext, antiforgery, pathBase))
+            .AllowAnonymous()
+            .WithName("DashboardLogin");
+
+        dashboard.MapPost(
+                "/login",
+                (HttpContext httpContext, IAntiforgery antiforgery, IDashboardAuthenticator authenticator) =>
+                    PostLoginAsync(httpContext, antiforgery, authenticator, pathBase))
+            .AllowAnonymous()
+            .WithName("DashboardLoginPost");
+
+        dashboard.MapPost(
+                "/logout",
+                (HttpContext httpContext, IAntiforgery antiforgery) => PostLogoutAsync(httpContext, antiforgery, pathBase))
+            .RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy)
+            .WithName("DashboardLogout");
+
+        dashboard.MapGet("/denied", () => Results.Content(
+                RenderPage("Access denied", "<p>The signed-in API key is not authorized for dashboard access.</p>"),
+                "text/html"))
+            .AllowAnonymous()
+            .WithName("DashboardAccessDenied");
+
+        dashboard.MapRazorComponents<App>()
+            .AddInteractiveServerRenderMode()
+            .RequireAuthorization(DashboardAuthenticationDefaults.AuthorizationPolicy);
+
+        return endpoints;
+    }
+
+    private static Task<ContentHttpResult> GetLoginAsync(
+        HttpContext httpContext,
+        IAntiforgery antiforgery,
+        string pathBase)
+    {
+        string returnUrl = SanitizeReturnUrl(
+            httpContext.Request.Query["returnUrl"].ToString(),
+            pathBase);
+
+        return Task.FromResult(TypedResults.Content(
+            RenderLoginPage(httpContext, antiforgery, returnUrl, pathBase, failureMessage: null),
+            "text/html"));
+    }
+
+    private static async Task<IResult> PostLoginAsync(
+        HttpContext httpContext,
+        IAntiforgery antiforgery,
+        IDashboardAuthenticator authenticator,
+        string pathBase)
+    {
+        await antiforgery.ValidateRequestAsync(httpContext).ConfigureAwait(false);
+
+        IFormCollection form = await httpContext.Request
+            .ReadFormAsync(httpContext.RequestAborted)
+            .ConfigureAwait(false);
+        string returnUrl = SanitizeReturnUrl(
+            form["returnUrl"].ToString(),
+            pathBase);
+
+        DashboardAuthenticationResult result = await authenticator
+            .AuthenticateAsync(form["apiKey"].ToString(), httpContext.RequestAborted)
+            .ConfigureAwait(false);
+
+        if (!result.Succeeded || result.Principal is null)
+        {
+            return TypedResults.Content(
+                RenderLoginPage(httpContext, antiforgery, returnUrl, pathBase, result.FailureMessage),
+                "text/html",
+                statusCode: StatusCodes.Status401Unauthorized);
+        }
+
+        await httpContext
+            .SignInAsync(DashboardAuthenticationDefaults.AuthenticationScheme, result.Principal)
+            .ConfigureAwait(false);
+
+        return Results.LocalRedirect(returnUrl);
+    }
+
+    private static async Task<IResult> PostLogoutAsync(
+        HttpContext httpContext,
+        IAntiforgery antiforgery,
+        string pathBase)
+    {
+        await antiforgery.ValidateRequestAsync(httpContext).ConfigureAwait(false);
+        await httpContext
+            .SignOutAsync(DashboardAuthenticationDefaults.AuthenticationScheme)
+            .ConfigureAwait(false);
+
+        return Results.LocalRedirect($"{pathBase}/login");
+    }
+
+    private static string RenderLoginPage(
+        HttpContext httpContext,
+        IAntiforgery antiforgery,
+        string returnUrl,
+        string pathBase,
+        string? failureMessage)
+    {
+        AntiforgeryTokenSet tokens = antiforgery.GetAndStoreTokens(httpContext);
+        string requestToken = tokens.RequestToken ?? string.Empty;
+        string alert = string.IsNullOrWhiteSpace(failureMessage)
+            ? string.Empty
+            : $"<p role=\"alert\">{HtmlEncoder.Default.Encode(failureMessage)}</p>";
+
+        string body = $"""
+            <section class="dashboard-login">
+                {alert}
+                <form method="post" action="{HtmlEncoder.Default.Encode(pathBase + "/login")}" class="card login-card">
+                    <div class="card-body">
+                        <input name="{tokens.FormFieldName}" type="hidden" value="{HtmlEncoder.Default.Encode(requestToken)}" />
+                        <input name="returnUrl" type="hidden" value="{HtmlEncoder.Default.Encode(returnUrl)}" />
+                        <div class="mb-3">
+                            <label for="apiKey" class="form-label">API key</label>
+                            <input id="apiKey" name="apiKey" type="password" autocomplete="off" class="form-control" />
+                        </div>
+                        <button type="submit" class="btn btn-primary">Sign in</button>
+                    </div>
+                </form>
+            </section>
+            """;
+
+        return RenderPage("Dashboard Sign In", body);
+    }
+
+    private static string RenderPage(string title, string body)
+    {
+        return $"""
+            <!doctype html>
+            <html lang="en">
+            <head>
+                <meta charset="utf-8" />
+                <meta name="viewport" content="width=device-width, initial-scale=1" />
+                <title>{HtmlEncoder.Default.Encode(title)}</title>
+                <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css" />
+                <link rel="stylesheet" href="/css/dashboard.css" />
+            </head>
+            <body class="dashboard-body">
+                <main class="container py-5">
+                    <h1 class="h3 mb-4">{HtmlEncoder.Default.Encode(title)}</h1>
+                    {body}
+                </main>
+                <script src="/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
+            </body>
+            </html>
+            """;
+    }
+
+    private static string NormalizePathBase(string pathBase)
+    {
+        string normalized = pathBase.TrimEnd('/');
+
+        return string.IsNullOrWhiteSpace(normalized) || !normalized.StartsWith("/", StringComparison.Ordinal)
+            ? "/dashboard"
+            : normalized;
+    }
+
+    private static string SanitizeReturnUrl(string? returnUrl, string pathBase)
+    {
+        if (string.IsNullOrWhiteSpace(returnUrl)
+            || !returnUrl.StartsWith("/", StringComparison.Ordinal)
+            || returnUrl.StartsWith("//", StringComparison.Ordinal)
+            || !returnUrl.StartsWith(pathBase, StringComparison.OrdinalIgnoreCase)
+            || Uri.TryCreate(returnUrl, UriKind.Absolute, out _))
+        {
+            return pathBase;
+        }
+
+        return returnUrl;
+    }
+}

src/MxGateway.Server/Dashboard/DashboardFaultSummary.cs

@@ -0,0 +1,9 @@
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardFaultSummary(
+    string Source,
+    string? SessionId,
+    int? WorkerProcessId,
+    string State,
+    string Message,
+    DateTimeOffset ObservedAt);

src/MxGateway.Server/Dashboard/DashboardMetricSummary.cs

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardMetricSummary(
+    string Name,
+    long Value,
+    string? Dimension = null);

src/MxGateway.Server/Dashboard/DashboardRedactor.cs

@@ -0,0 +1,34 @@
+using MxGateway.Server.Diagnostics;
+
+namespace MxGateway.Server.Dashboard;
+
+internal static class DashboardRedactor
+{
+    private static readonly string[] SensitiveTextMarkers =
+    [
+        "apikey",
+        "api_key",
+        "authorization",
+        "credential",
+        "password",
+        "secret",
+        "token",
+    ];
+
+    public static string? Redact(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return value;
+        }
+
+        if (value.Contains("mxgw_", StringComparison.OrdinalIgnoreCase))
+        {
+            return GatewayLogRedactor.RedactClientIdentity(value);
+        }
+
+        return SensitiveTextMarkers.Any(marker => value.Contains(marker, StringComparison.OrdinalIgnoreCase))
+            ? GatewayLogRedactor.RedactedValue
+            : value;
+    }
+}

src/MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs

@@ -0,0 +1,56 @@
+using Microsoft.AspNetCore.Authentication.Cookies;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+
+namespace MxGateway.Server.Dashboard;
+
+public static class DashboardServiceCollectionExtensions
+{
+    public static IServiceCollection AddGatewayDashboard(this IServiceCollection services)
+    {
+        services.AddSingleton<IDashboardSnapshotService, DashboardSnapshotService>();
+        services.AddSingleton<IDashboardAuthenticator, DashboardAuthenticator>();
+        services.AddHttpContextAccessor();
+        services.AddAntiforgery();
+        services.AddCascadingAuthenticationState();
+        services.AddRazorComponents()
+            .AddInteractiveServerComponents();
+        services
+            .AddAuthentication(DashboardAuthenticationDefaults.AuthenticationScheme)
+            .AddCookie(DashboardAuthenticationDefaults.AuthenticationScheme);
+        services.AddOptions<CookieAuthenticationOptions>(DashboardAuthenticationDefaults.AuthenticationScheme)
+            .Configure<IOptions<GatewayOptions>>(ConfigureCookieOptions);
+        services.AddAuthorization(options =>
+        {
+            options.AddPolicy(
+                DashboardAuthenticationDefaults.AuthorizationPolicy,
+                policy => policy.AddRequirements(new DashboardAuthorizationRequirement()));
+        });
+        services.AddSingleton<IAuthorizationHandler, DashboardAuthorizationHandler>();
+
+        return services;
+    }
+
+    private static void ConfigureCookieOptions(
+        CookieAuthenticationOptions cookieOptions,
+        IOptions<GatewayOptions> gatewayOptions)
+    {
+        string pathBase = gatewayOptions.Value.Dashboard.PathBase.TrimEnd('/');
+        if (string.IsNullOrWhiteSpace(pathBase))
+        {
+            pathBase = "/dashboard";
+        }
+
+        cookieOptions.Cookie.Name = DashboardAuthenticationDefaults.CookieName;
+        cookieOptions.Cookie.HttpOnly = true;
+        cookieOptions.Cookie.SecurePolicy = CookieSecurePolicy.Always;
+        cookieOptions.Cookie.SameSite = SameSiteMode.Strict;
+        cookieOptions.Cookie.Path = "/";
+        cookieOptions.LoginPath = $"{pathBase}/login";
+        cookieOptions.LogoutPath = $"{pathBase}/logout";
+        cookieOptions.AccessDeniedPath = $"{pathBase}/denied";
+        cookieOptions.ExpireTimeSpan = TimeSpan.FromHours(8);
+        cookieOptions.SlidingExpiration = true;
+    }
+}

src/MxGateway.Server/Dashboard/DashboardSessionSummary.cs

@@ -0,0 +1,19 @@
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardSessionSummary(
+    string SessionId,
+    string BackendName,
+    SessionState State,
+    string? ClientIdentity,
+    string? ClientSessionName,
+    string? ClientCorrelationId,
+    DateTimeOffset OpenedAt,
+    DateTimeOffset LastClientActivityAt,
+    DateTimeOffset? LeaseExpiresAt,
+    int? WorkerProcessId,
+    WorkerClientState? WorkerState,
+    DateTimeOffset? LastWorkerHeartbeatAt,
+    string? LastFault);

src/MxGateway.Server/Dashboard/DashboardSnapshot.cs

@@ -0,0 +1,15 @@
+using MxGateway.Server.Configuration;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardSnapshot(
+    DateTimeOffset GeneratedAt,
+    DateTimeOffset GatewayStartedAt,
+    TimeSpan GatewayUptime,
+    string GatewayStatus,
+    string GatewayVersion,
+    IReadOnlyList<DashboardSessionSummary> Sessions,
+    IReadOnlyList<DashboardWorkerSummary> Workers,
+    IReadOnlyList<DashboardMetricSummary> Metrics,
+    IReadOnlyList<DashboardFaultSummary> Faults,
+    EffectiveGatewayConfiguration Configuration);

src/MxGateway.Server/Dashboard/DashboardSnapshotService.cs

@@ -0,0 +1,196 @@
+using System.Runtime.CompilerServices;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Metrics;
+using MxGateway.Server.Sessions;
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed class DashboardSnapshotService : IDashboardSnapshotService
+{
+    private const string HealthyStatus = "Healthy";
+
+    private readonly ISessionRegistry _sessionRegistry;
+    private readonly GatewayMetrics _metrics;
+    private readonly IGatewayConfigurationProvider _configurationProvider;
+    private readonly TimeProvider _timeProvider;
+    private readonly DateTimeOffset _gatewayStartedAt;
+    private readonly TimeSpan _snapshotInterval;
+    private readonly int _recentFaultLimit;
+    private readonly int _recentSessionLimit;
+
+    public DashboardSnapshotService(
+        ISessionRegistry sessionRegistry,
+        GatewayMetrics metrics,
+        IGatewayConfigurationProvider configurationProvider,
+        IOptions<GatewayOptions> options,
+        TimeProvider? timeProvider = null)
+    {
+        _sessionRegistry = sessionRegistry ?? throw new ArgumentNullException(nameof(sessionRegistry));
+        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
+        _configurationProvider = configurationProvider ?? throw new ArgumentNullException(nameof(configurationProvider));
+        ArgumentNullException.ThrowIfNull(options);
+
+        _timeProvider = timeProvider ?? TimeProvider.System;
+        _gatewayStartedAt = _timeProvider.GetUtcNow();
+        _snapshotInterval = TimeSpan.FromMilliseconds(options.Value.Dashboard.SnapshotIntervalMilliseconds);
+        _recentFaultLimit = options.Value.Dashboard.RecentFaultLimit;
+        _recentSessionLimit = options.Value.Dashboard.RecentSessionLimit;
+    }
+
+    public DashboardSnapshot GetSnapshot()
+    {
+        DateTimeOffset generatedAt = _timeProvider.GetUtcNow();
+        IReadOnlyList<GatewaySession> sessions = _sessionRegistry.Snapshot()
+            .OrderByDescending(session => session.OpenedAt)
+            .ToArray();
+        IReadOnlyList<DashboardSessionSummary> sessionSummaries = sessions
+            .Take(ResolveLimit(_recentSessionLimit))
+            .Select(CreateSessionSummary)
+            .ToArray();
+        IReadOnlyList<DashboardWorkerSummary> workerSummaries = sessions
+            .Where(session => session.WorkerClient is not null)
+            .Select(CreateWorkerSummary)
+            .ToArray();
+        GatewayMetricsSnapshot metricsSnapshot = _metrics.GetSnapshot();
+
+        return new DashboardSnapshot(
+            GeneratedAt: generatedAt,
+            GatewayStartedAt: _gatewayStartedAt,
+            GatewayUptime: generatedAt - _gatewayStartedAt,
+            GatewayStatus: HealthyStatus,
+            GatewayVersion: typeof(DashboardSnapshotService).Assembly.GetName().Version?.ToString() ?? "unknown",
+            Sessions: sessionSummaries,
+            Workers: workerSummaries,
+            Metrics: CreateMetricSummaries(metricsSnapshot),
+            Faults: CreateFaultSummaries(sessions, generatedAt),
+            Configuration: _configurationProvider.GetEffectiveConfiguration());
+    }
+
+    public async IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        if (cancellationToken.IsCancellationRequested)
+        {
+            yield break;
+        }
+
+        yield return GetSnapshot();
+
+        using PeriodicTimer timer = new(_snapshotInterval, _timeProvider);
+        while (true)
+        {
+            bool hasNext;
+            try
+            {
+                hasNext = await timer.WaitForNextTickAsync(cancellationToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                yield break;
+            }
+
+            if (!hasNext)
+            {
+                yield break;
+            }
+
+            yield return GetSnapshot();
+        }
+    }
+
+    private static DashboardSessionSummary CreateSessionSummary(GatewaySession session)
+    {
+        IWorkerClient? workerClient = session.WorkerClient;
+
+        return new DashboardSessionSummary(
+            SessionId: session.SessionId,
+            BackendName: session.BackendName,
+            State: session.State,
+            ClientIdentity: DashboardRedactor.Redact(session.ClientIdentity),
+            ClientSessionName: DashboardRedactor.Redact(session.ClientSessionName),
+            ClientCorrelationId: DashboardRedactor.Redact(session.ClientCorrelationId),
+            OpenedAt: session.OpenedAt,
+            LastClientActivityAt: session.LastClientActivityAt,
+            LeaseExpiresAt: session.LeaseExpiresAt,
+            WorkerProcessId: workerClient?.ProcessId,
+            WorkerState: workerClient?.State,
+            LastWorkerHeartbeatAt: workerClient?.LastHeartbeatAt,
+            LastFault: DashboardRedactor.Redact(session.FinalFault));
+    }
+
+    private static DashboardWorkerSummary CreateWorkerSummary(GatewaySession session)
+    {
+        IWorkerClient workerClient = session.WorkerClient!;
+
+        return new DashboardWorkerSummary(
+            SessionId: session.SessionId,
+            ProcessId: workerClient.ProcessId,
+            State: workerClient.State,
+            LastHeartbeatAt: workerClient.LastHeartbeatAt,
+            LastFault: DashboardRedactor.Redact(session.FinalFault));
+    }
+
+    private static IReadOnlyList<DashboardMetricSummary> CreateMetricSummaries(GatewayMetricsSnapshot snapshot)
+    {
+        List<DashboardMetricSummary> metrics =
+        [
+            new("mxgateway.sessions.open", snapshot.OpenSessions),
+            new("mxgateway.workers.running", snapshot.WorkersRunning),
+            new("mxgateway.events.queue.depth", snapshot.EventQueueDepth),
+            new("mxgateway.sessions.opened", snapshot.SessionsOpened),
+            new("mxgateway.sessions.closed", snapshot.SessionsClosed),
+            new("mxgateway.commands.started", snapshot.CommandsStarted),
+            new("mxgateway.commands.succeeded", snapshot.CommandsSucceeded),
+            new("mxgateway.commands.failed", snapshot.CommandsFailed),
+            new("mxgateway.events.received", snapshot.EventsReceived),
+            new("mxgateway.queues.overflows", snapshot.QueueOverflows),
+            new("mxgateway.faults", snapshot.Faults),
+            new("mxgateway.workers.killed", snapshot.WorkerKills),
+            new("mxgateway.workers.exited", snapshot.WorkerExits),
+            new("mxgateway.heartbeats.failed", snapshot.HeartbeatFailures),
+            new("mxgateway.grpc.streams.disconnected", snapshot.StreamDisconnects),
+        ];
+
+        metrics.AddRange(snapshot.CommandFailuresByMethod
+            .OrderBy(entry => entry.Key, StringComparer.OrdinalIgnoreCase)
+            .Select(entry => new DashboardMetricSummary("mxgateway.commands.failed", entry.Value, entry.Key)));
+        metrics.AddRange(snapshot.EventsByFamily
+            .OrderBy(entry => entry.Key, StringComparer.OrdinalIgnoreCase)
+            .Select(entry => new DashboardMetricSummary("mxgateway.events.received", entry.Value, entry.Key)));
+
+        return metrics;
+    }
+
+    private IReadOnlyList<DashboardFaultSummary> CreateFaultSummaries(
+        IReadOnlyList<GatewaySession> sessions,
+        DateTimeOffset generatedAt)
+    {
+        return sessions
+            .Where(HasFault)
+            .Take(ResolveLimit(_recentFaultLimit))
+            .Select(session => new DashboardFaultSummary(
+                Source: session.WorkerClient?.State == WorkerClientState.Faulted ? "Worker" : "Session",
+                SessionId: session.SessionId,
+                WorkerProcessId: session.WorkerProcessId,
+                State: session.WorkerClient?.State == WorkerClientState.Faulted
+                    ? WorkerClientState.Faulted.ToString()
+                    : session.State.ToString(),
+                Message: DashboardRedactor.Redact(session.FinalFault) ?? "Faulted",
+                ObservedAt: generatedAt))
+            .ToArray();
+    }
+
+    private static bool HasFault(GatewaySession session)
+    {
+        return session.State == MxGateway.Contracts.Proto.SessionState.Faulted
+            || session.WorkerClient?.State == WorkerClientState.Faulted
+            || !string.IsNullOrWhiteSpace(session.FinalFault);
+    }
+
+    private static int ResolveLimit(int configuredLimit)
+    {
+        return configuredLimit < 0 ? 0 : configuredLimit;
+    }
+}

src/MxGateway.Server/Dashboard/DashboardWorkerSummary.cs

@@ -0,0 +1,10 @@
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Server.Dashboard;
+
+public sealed record DashboardWorkerSummary(
+    string SessionId,
+    int? ProcessId,
+    WorkerClientState State,
+    DateTimeOffset LastHeartbeatAt,
+    string? LastFault);

src/MxGateway.Server/Dashboard/IDashboardAuthenticator.cs

@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Dashboard;
+
+public interface IDashboardAuthenticator
+{
+    Task<DashboardAuthenticationResult> AuthenticateAsync(
+        string? apiKey,
+        CancellationToken cancellationToken);
+}

src/MxGateway.Server/Dashboard/IDashboardSnapshotService.cs

@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Dashboard;
+
+public interface IDashboardSnapshotService
+{
+    DashboardSnapshot GetSnapshot();
+
+    IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(CancellationToken cancellationToken);
+}

src/MxGateway.Server/Diagnostics/GatewayLogRedactor.cs

@@ -0,0 +1,78 @@
+namespace MxGateway.Server.Diagnostics;
+
+public static class GatewayLogRedactor
+{
+    public const string RedactedValue = "[redacted]";
+
+    private static readonly HashSet<string> SensitiveCommandMethods = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "AuthenticateUser",
+        "WriteSecured",
+        "WriteSecured2"
+    };
+
+    public static bool IsCredentialBearingCommand(string? commandMethod)
+    {
+        return commandMethod is not null
+            && SensitiveCommandMethods.Contains(commandMethod);
+    }
+
+    public static string? RedactApiKey(string? authorizationHeader)
+    {
+        if (string.IsNullOrWhiteSpace(authorizationHeader))
+        {
+            return authorizationHeader;
+        }
+
+        const string bearerPrefix = "Bearer ";
+        if (!authorizationHeader.StartsWith(bearerPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return RedactedValue;
+        }
+
+        string token = authorizationHeader[bearerPrefix.Length..].Trim();
+
+        if (!token.StartsWith("mxgw_", StringComparison.OrdinalIgnoreCase))
+        {
+            return $"{bearerPrefix}{RedactedValue}";
+        }
+
+        string[] tokenParts = token.Split('_', 3, StringSplitOptions.RemoveEmptyEntries);
+        if (tokenParts.Length < 2)
+        {
+            return $"{bearerPrefix}mxgw_{RedactedValue}";
+        }
+
+        return $"{bearerPrefix}mxgw_{tokenParts[1]}_{RedactedValue}";
+    }
+
+    public static string? RedactClientIdentity(string? clientIdentity)
+    {
+        if (string.IsNullOrWhiteSpace(clientIdentity))
+        {
+            return clientIdentity;
+        }
+
+        return clientIdentity.Contains("mxgw_", StringComparison.OrdinalIgnoreCase)
+            ? RedactApiKey(clientIdentity)
+            : clientIdentity;
+    }
+
+    public static object? RedactCommandValue(
+        string? commandMethod,
+        object? value,
+        bool valueLoggingEnabled = false)
+    {
+        if (value is null)
+        {
+            return null;
+        }
+
+        if (!valueLoggingEnabled || IsCredentialBearingCommand(commandMethod))
+        {
+            return RedactedValue;
+        }
+
+        return value;
+    }
+}

src/MxGateway.Server/Diagnostics/GatewayLogScope.cs

@@ -0,0 +1,33 @@
+namespace MxGateway.Server.Diagnostics;
+
+public sealed record GatewayLogScope(
+    string? SessionId = null,
+    int? WorkerProcessId = null,
+    ulong? CorrelationId = null,
+    string? CommandMethod = null,
+    string? ClientIdentity = null)
+{
+    public IReadOnlyDictionary<string, object?> ToDictionary()
+    {
+        Dictionary<string, object?> values = [];
+
+        AddIfPresent(values, "SessionId", SessionId);
+        AddIfPresent(values, "WorkerProcessId", WorkerProcessId);
+        AddIfPresent(values, "CorrelationId", CorrelationId);
+        AddIfPresent(values, "CommandMethod", CommandMethod);
+        AddIfPresent(values, "ClientIdentity", GatewayLogRedactor.RedactClientIdentity(ClientIdentity));
+
+        return values;
+    }
+
+    private static void AddIfPresent(
+        Dictionary<string, object?> values,
+        string key,
+        object? value)
+    {
+        if (value is not null)
+        {
+            values[key] = value;
+        }
+    }
+}

src/MxGateway.Server/Diagnostics/GatewayLoggerExtensions.cs

@@ -0,0 +1,16 @@
+using Microsoft.Extensions.Logging;
+
+namespace MxGateway.Server.Diagnostics;
+
+public static class GatewayLoggerExtensions
+{
+    public static IDisposable? BeginGatewayScope(
+        this ILogger logger,
+        GatewayLogScope scope)
+    {
+        ArgumentNullException.ThrowIfNull(logger);
+        ArgumentNullException.ThrowIfNull(scope);
+
+        return logger.BeginScope(scope.ToDictionary());
+    }
+}

src/MxGateway.Server/Diagnostics/GatewayRequestLoggingMiddlewareExtensions.cs

@@ -0,0 +1,57 @@
+using Microsoft.Extensions.Primitives;
+
+namespace MxGateway.Server.Diagnostics;
+
+public static class GatewayRequestLoggingMiddlewareExtensions
+{
+    public const string SessionIdHeaderName = "x-session-id";
+    public const string WorkerProcessIdHeaderName = "x-worker-process-id";
+    public const string CorrelationIdHeaderName = "x-correlation-id";
+    public const string CommandMethodHeaderName = "x-command-method";
+
+    public static IApplicationBuilder UseGatewayRequestLoggingScope(this IApplicationBuilder app)
+    {
+        ArgumentNullException.ThrowIfNull(app);
+
+        return app.Use(async (context, next) =>
+        {
+            ILogger logger = context.RequestServices
+                .GetRequiredService<ILoggerFactory>()
+                .CreateLogger("MxGateway.Request");
+
+            using IDisposable? scope = logger.BeginGatewayScope(new GatewayLogScope(
+                SessionId: ReadHeader(context, SessionIdHeaderName),
+                WorkerProcessId: ReadInt32Header(context, WorkerProcessIdHeaderName),
+                CorrelationId: ReadUInt64Header(context, CorrelationIdHeaderName),
+                CommandMethod: ReadHeader(context, CommandMethodHeaderName),
+                ClientIdentity: ReadHeader(context, "authorization")));
+
+            await next(context);
+        });
+    }
+
+    private static string? ReadHeader(HttpContext context, string headerName)
+    {
+        return context.Request.Headers.TryGetValue(headerName, out StringValues values)
+            ? values.ToString()
+            : null;
+    }
+
+    private static int? ReadInt32Header(HttpContext context, string headerName)
+    {
+        string? value = ReadHeader(context, headerName);
+
+        return int.TryParse(value, out int parsedValue)
+            ? parsedValue
+            : null;
+    }
+
+    private static ulong? ReadUInt64Header(HttpContext context, string headerName)
+    {
+        string? value = ReadHeader(context, headerName);
+
+        return ulong.TryParse(value, out ulong parsedValue)
+            ? parsedValue
+            : null;
+    }
+}

src/MxGateway.Server/GatewayApplication.cs

@@ -1,4 +1,13 @@
 using MxGateway.Contracts;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Dashboard;
+using MxGateway.Server.Diagnostics;
+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;
 
 namespace MxGateway.Server;
 
@@ -9,6 +18,11 @@ public static class GatewayApplication
         WebApplicationBuilder builder = CreateBuilder(args);
         WebApplication app = builder.Build();
 
+        app.UseGatewayRequestLoggingScope();
+        app.UseStaticFiles();
+        app.UseAuthentication();
+        app.UseAuthorization();
+        app.UseAntiforgery();
         app.MapGatewayEndpoints();
 
         return app;
@@ -18,7 +32,17 @@ public static class GatewayApplication
     {
         WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 
+        builder.Services.AddGatewayConfiguration();
+        builder.Services.AddSqliteAuthStore();
+        builder.Services.AddGatewayGrpcAuthorization();
         builder.Services.AddHealthChecks();
+        builder.Services.AddSingleton<GatewayMetrics>();
+        builder.Services.AddSingleton<MxAccessGrpcMapper>();
+        builder.Services.AddSingleton<MxAccessGrpcRequestValidator>();
+        builder.Services.AddSingleton<IEventStreamService, EventStreamService>();
+        builder.Services.AddWorkerProcessLauncher();
+        builder.Services.AddGatewaySessions();
+        builder.Services.AddGatewayDashboard();
 
         return builder;
     }
@@ -35,6 +59,9 @@ public static class GatewayApplication
                     WorkerProtocolVersion: GatewayContractInfo.WorkerProtocolVersion)))
             .WithName("LiveHealth");
 
+        endpoints.MapGrpcService<MxAccessGatewayService>();
+        endpoints.MapGatewayDashboard();
+
         return endpoints;
     }
 }

src/MxGateway.Server/Grpc/EventStreamService.cs

@@ -0,0 +1,140 @@
+using System.Runtime.CompilerServices;
+using System.Threading.Channels;
+using Microsoft.Extensions.Options;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Metrics;
+using MxGateway.Server.Sessions;
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Server.Grpc;
+
+public sealed class EventStreamService(
+    ISessionManager sessionManager,
+    IOptions<GatewayOptions> options,
+    MxAccessGrpcMapper mapper,
+    GatewayMetrics metrics,
+    ILogger<EventStreamService> logger) : IEventStreamService
+{
+    public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
+        StreamEventsRequest request,
+        [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        if (!sessionManager.TryGetSession(request.SessionId, out GatewaySession session))
+        {
+            throw new SessionManagerException(
+                SessionManagerErrorCode.SessionNotFound,
+                $"Session {request.SessionId} was not found.");
+        }
+
+        using IDisposable subscriber = session.AttachEventSubscriber(
+            options.Value.Sessions.AllowMultipleEventSubscribers);
+        using CancellationTokenSource streamCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+
+        int streamQueueDepth = 0;
+        Channel<MxEvent> eventQueue = Channel.CreateBounded<MxEvent>(
+            new BoundedChannelOptions(options.Value.Events.QueueCapacity)
+            {
+                SingleReader = true,
+                SingleWriter = true,
+                FullMode = BoundedChannelFullMode.Wait,
+                AllowSynchronousContinuations = false,
+            });
+        Task producerTask = ProduceEventsAsync(
+            session,
+            request.AfterWorkerSequence,
+            eventQueue.Writer,
+            () =>
+            {
+                int depth = Interlocked.Increment(ref streamQueueDepth);
+                metrics.SetEventQueueDepth(depth);
+            },
+            streamCts.Token);
+
+        try
+        {
+            await foreach (MxEvent mxEvent in eventQueue.Reader.ReadAllAsync(cancellationToken).ConfigureAwait(false))
+            {
+                int depth = Math.Max(0, Interlocked.Decrement(ref streamQueueDepth));
+                metrics.SetEventQueueDepth(depth);
+                yield return mxEvent;
+            }
+
+            await producerTask.ConfigureAwait(false);
+        }
+        finally
+        {
+            await streamCts.CancelAsync().ConfigureAwait(false);
+            subscriber.Dispose();
+            metrics.StreamDisconnected("Detached");
+
+            try
+            {
+                await producerTask.ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (streamCts.IsCancellationRequested)
+            {
+            }
+            catch (Exception exception)
+            {
+                logger.LogDebug(
+                    exception,
+                    "Event stream producer stopped for session {SessionId}.",
+                    request.SessionId);
+            }
+        }
+    }
+
+    private async Task ProduceEventsAsync(
+        GatewaySession session,
+        ulong afterWorkerSequence,
+        ChannelWriter<MxEvent> writer,
+        Action eventQueued,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            await foreach (WorkerEvent workerEvent in session
+                .ReadEventsAsync(cancellationToken)
+                .WithCancellation(cancellationToken)
+                .ConfigureAwait(false))
+            {
+                MxEvent publicEvent = mapper.MapEvent(workerEvent);
+                if (publicEvent.WorkerSequence <= afterWorkerSequence)
+                {
+                    continue;
+                }
+
+                if (!writer.TryWrite(publicEvent))
+                {
+                    string message = $"Session {session.SessionId} event stream queue overflowed.";
+                    session.MarkFaulted(message);
+                    metrics.QueueOverflow("grpc-event-stream");
+                    metrics.Fault(SessionManagerErrorCode.EventQueueOverflow.ToString());
+                    writer.TryComplete(new SessionManagerException(
+                        SessionManagerErrorCode.EventQueueOverflow,
+                        message));
+                    return;
+                }
+
+                eventQueued();
+            }
+
+            writer.TryComplete();
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            writer.TryComplete();
+        }
+        catch (Exception exception)
+        {
+            if (exception is WorkerClientException)
+            {
+                session.MarkFaulted(exception.Message);
+                metrics.Fault(WorkerClientErrorCode.WorkerFaulted.ToString());
+            }
+
+            writer.TryComplete(exception);
+        }
+    }
+}

src/MxGateway.Server/Grpc/IEventStreamService.cs

@@ -0,0 +1,10 @@
+using MxGateway.Contracts.Proto;
+
+namespace MxGateway.Server.Grpc;
+
+public interface IEventStreamService
+{
+    IAsyncEnumerable<MxEvent> StreamEventsAsync(
+        StreamEventsRequest request,
+        CancellationToken cancellationToken);
+}

src/MxGateway.Server/Grpc/MxAccessGatewayService.cs

@@ -0,0 +1,176 @@
+using Grpc.Core;
+using MxGateway.Contracts;
+using MxGateway.Contracts.Proto;
+using MxGateway.Server.Security.Authorization;
+using MxGateway.Server.Sessions;
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Server.Grpc;
+
+public sealed class MxAccessGatewayService(
+    ISessionManager sessionManager,
+    IGatewayRequestIdentityAccessor identityAccessor,
+    MxAccessGrpcRequestValidator requestValidator,
+    MxAccessGrpcMapper mapper,
+    IEventStreamService eventStreamService,
+    ILogger<MxAccessGatewayService> logger) : MxAccessGateway.MxAccessGatewayBase
+{
+    public override async Task<OpenSessionReply> OpenSession(
+        OpenSessionRequest request,
+        ServerCallContext context)
+    {
+        try
+        {
+            requestValidator.ValidateOpenSession(request);
+            GatewaySession session = await sessionManager
+                .OpenSessionAsync(
+                    SessionOpenRequest.FromContract(request),
+                    ResolveClientIdentity(),
+                    context.CancellationToken)
+                .ConfigureAwait(false);
+
+            OpenSessionReply reply = new()
+            {
+                SessionId = session.SessionId,
+                BackendName = session.BackendName,
+                WorkerProcessId = session.WorkerProcessId ?? 0,
+                WorkerProtocolVersion = GatewayContractInfo.WorkerProtocolVersion,
+                DefaultCommandTimeout = Google.Protobuf.WellKnownTypes.Duration.FromTimeSpan(session.CommandTimeout),
+                ProtocolStatus = MxAccessGrpcMapper.Ok(),
+            };
+            reply.Capabilities.Add("unary-open-session");
+            reply.Capabilities.Add("unary-close-session");
+            reply.Capabilities.Add("unary-invoke");
+            reply.Capabilities.Add("server-stream-events");
+
+            return reply;
+        }
+        catch (Exception exception) when (exception is not RpcException)
+        {
+            throw MapException(exception);
+        }
+    }
+
+    public override async Task<CloseSessionReply> CloseSession(
+        CloseSessionRequest request,
+        ServerCallContext context)
+    {
+        try
+        {
+            requestValidator.ValidateCloseSession(request);
+            SessionCloseResult result = await sessionManager
+                .CloseSessionAsync(request.SessionId, context.CancellationToken)
+                .ConfigureAwait(false);
+
+            return new CloseSessionReply
+            {
+                SessionId = result.SessionId,
+                FinalState = result.FinalState,
+                ProtocolStatus = MxAccessGrpcMapper.Ok(result.AlreadyClosed ? "Session was already closed." : "Session closed."),
+            };
+        }
+        catch (Exception exception) when (exception is not RpcException)
+        {
+            throw MapException(exception);
+        }
+    }
+
+    public override async Task<MxCommandReply> Invoke(
+        MxCommandRequest request,
+        ServerCallContext context)
+    {
+        try
+        {
+            requestValidator.ValidateInvoke(request);
+            WorkerCommand workerCommand = mapper.MapCommand(request);
+            WorkerCommandReply workerReply = await sessionManager
+                .InvokeAsync(request.SessionId, workerCommand, context.CancellationToken)
+                .ConfigureAwait(false);
+
+            return mapper.MapCommandReply(workerReply);
+        }
+        catch (Exception exception) when (exception is not RpcException)
+        {
+            throw MapException(exception);
+        }
+    }
+
+    public override async Task StreamEvents(
+        StreamEventsRequest request,
+        IServerStreamWriter<MxEvent> responseStream,
+        ServerCallContext context)
+    {
+        try
+        {
+            requestValidator.ValidateStreamEvents(request);
+            await foreach (MxEvent publicEvent in eventStreamService
+                .StreamEventsAsync(request, context.CancellationToken)
+                .WithCancellation(context.CancellationToken)
+                .ConfigureAwait(false))
+            {
+                await responseStream.WriteAsync(publicEvent).ConfigureAwait(false);
+            }
+        }
+        catch (Exception exception) when (exception is not RpcException)
+        {
+            throw MapException(exception);
+        }
+    }
+
+    private string? ResolveClientIdentity()
+    {
+        return identityAccessor.Current?.DisplayName ?? identityAccessor.Current?.KeyId;
+    }
+
+    private RpcException MapException(Exception exception)
+    {
+        if (exception is OperationCanceledException)
+        {
+            return new RpcException(new Status(StatusCode.Cancelled, "gRPC request was canceled."));
+        }
+
+        if (exception is SessionManagerException sessionException)
+        {
+            return MapSessionException(sessionException);
+        }
+
+        if (exception is WorkerClientException workerClientException)
+        {
+            return MapWorkerClientException(workerClientException);
+        }
+
+        logger.LogWarning(exception, "Public gRPC request failed.");
+        return new RpcException(new Status(StatusCode.Unavailable, "Gateway request failed before an MXAccess reply was available."));
+    }
+
+    private static RpcException MapSessionException(SessionManagerException exception)
+    {
+        StatusCode statusCode = exception.ErrorCode switch
+        {
+            SessionManagerErrorCode.SessionNotFound => StatusCode.NotFound,
+            SessionManagerErrorCode.SessionNotReady => StatusCode.FailedPrecondition,
+            SessionManagerErrorCode.EventSubscriberAlreadyActive => StatusCode.ResourceExhausted,
+            SessionManagerErrorCode.EventQueueOverflow => StatusCode.ResourceExhausted,
+            SessionManagerErrorCode.SessionLimitExceeded => StatusCode.ResourceExhausted,
+            SessionManagerErrorCode.OpenFailed => StatusCode.Unavailable,
+            SessionManagerErrorCode.CloseFailed => StatusCode.Unavailable,
+            _ => StatusCode.Unavailable,
+        };
+
+        return new RpcException(new Status(statusCode, exception.Message));
+    }
+
+    private static RpcException MapWorkerClientException(WorkerClientException exception)
+    {
+        StatusCode statusCode = exception.ErrorCode switch
+        {
+            WorkerClientErrorCode.CommandTimeout => StatusCode.DeadlineExceeded,
+            WorkerClientErrorCode.GatewayShutdown => StatusCode.Cancelled,
+            WorkerClientErrorCode.InvalidState => StatusCode.FailedPrecondition,
+            WorkerClientErrorCode.ProtocolViolation => StatusCode.Internal,
+            _ => StatusCode.Unavailable,
+        };
+
+        return new RpcException(new Status(statusCode, exception.Message));
+    }
+}

src/MxGateway.Server/Grpc/MxAccessGrpcMapper.cs

@@ -0,0 +1,124 @@
+using Google.Protobuf.WellKnownTypes;
+using MxGateway.Contracts.Proto;
+
+namespace MxGateway.Server.Grpc;
+
+public sealed class MxAccessGrpcMapper
+{
+    private readonly TimeProvider _timeProvider;
+
+    public MxAccessGrpcMapper(TimeProvider? timeProvider = null)
+    {
+        _timeProvider = timeProvider ?? TimeProvider.System;
+    }
+
+    public WorkerCommand MapCommand(MxCommandRequest request)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentNullException.ThrowIfNull(request.Command);
+
+        return new WorkerCommand
+        {
+            Command = request.Command.Clone(),
+            EnqueueTimestamp = Timestamp.FromDateTimeOffset(_timeProvider.GetUtcNow()),
+        };
+    }
+
+    public MxCommandReply MapCommandReply(WorkerCommandReply reply)
+    {
+        ArgumentNullException.ThrowIfNull(reply);
+
+        if (reply.Reply is null)
+        {
+            return new MxCommandReply
+            {
+                ProtocolStatus = ProtocolViolation("Worker command reply did not contain a public reply payload."),
+            };
+        }
+
+        return reply.Reply.Clone();
+    }
+
+    public MxEvent MapEvent(WorkerEvent workerEvent)
+    {
+        ArgumentNullException.ThrowIfNull(workerEvent);
+
+        return workerEvent.Event?.Clone() ?? new MxEvent
+        {
+            Family = MxEventFamily.Unspecified,
+            RawStatus = "Worker event did not contain a public event payload.",
+        };
+    }
+
+    public static ProtocolStatus Ok(string message = "OK")
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.Ok,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus InvalidRequest(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.InvalidRequest,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus SessionNotFound(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.SessionNotFound,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus SessionNotReady(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.SessionNotReady,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus WorkerUnavailable(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.WorkerUnavailable,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus Timeout(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.Timeout,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus Canceled(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.Canceled,
+            Message = message,
+        };
+    }
+
+    public static ProtocolStatus ProtocolViolation(string message)
+    {
+        return new ProtocolStatus
+        {
+            Code = ProtocolStatusCode.ProtocolViolation,
+            Message = message,
+        };
+    }
+}

src/MxGateway.Server/Grpc/MxAccessGrpcRequestValidator.cs

@@ -0,0 +1,101 @@
+using Grpc.Core;
+using MxGateway.Contracts.Proto;
+
+namespace MxGateway.Server.Grpc;
+
+public sealed class MxAccessGrpcRequestValidator
+{
+    public void ValidateOpenSession(OpenSessionRequest request)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        if (request.CommandTimeout is not null && request.CommandTimeout.ToTimeSpan() <= TimeSpan.Zero)
+        {
+            throw InvalidArgument("Command timeout must be greater than zero when provided.");
+        }
+    }
+
+    public void ValidateCloseSession(CloseSessionRequest request)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        RequireSessionId(request.SessionId);
+    }
+
+    public void ValidateStreamEvents(StreamEventsRequest request)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        RequireSessionId(request.SessionId);
+    }
+
+    public void ValidateInvoke(MxCommandRequest request)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        RequireSessionId(request.SessionId);
+
+        if (request.Command is null)
+        {
+            throw InvalidArgument("Invoke requires a command payload.");
+        }
+
+        if (request.Command.Kind is MxCommandKind.Unspecified)
+        {
+            throw InvalidArgument("Invoke requires a command kind.");
+        }
+
+        ValidateCommandPayload(request.Command);
+    }
+
+    private static void RequireSessionId(string sessionId)
+    {
+        if (string.IsNullOrWhiteSpace(sessionId))
+        {
+            throw InvalidArgument("Session id is required.");
+        }
+    }
+
+    private static void ValidateCommandPayload(MxCommand command)
+    {
+        MxCommand.PayloadOneofCase expectedPayload = ExpectedPayload(command.Kind);
+        if (command.PayloadCase != expectedPayload)
+        {
+            throw InvalidArgument(
+                $"Command kind {command.Kind} requires payload {expectedPayload} but received {command.PayloadCase}.");
+        }
+    }
+
+    private static MxCommand.PayloadOneofCase ExpectedPayload(MxCommandKind kind)
+    {
+        return kind switch
+        {
+            MxCommandKind.Register => MxCommand.PayloadOneofCase.Register,
+            MxCommandKind.Unregister => MxCommand.PayloadOneofCase.Unregister,
+            MxCommandKind.AddItem => MxCommand.PayloadOneofCase.AddItem,
+            MxCommandKind.AddItem2 => MxCommand.PayloadOneofCase.AddItem2,
+            MxCommandKind.RemoveItem => MxCommand.PayloadOneofCase.RemoveItem,
+            MxCommandKind.Advise => MxCommand.PayloadOneofCase.Advise,
+            MxCommandKind.UnAdvise => MxCommand.PayloadOneofCase.UnAdvise,
+            MxCommandKind.AdviseSupervisory => MxCommand.PayloadOneofCase.AdviseSupervisory,
+            MxCommandKind.AddBufferedItem => MxCommand.PayloadOneofCase.AddBufferedItem,
+            MxCommandKind.SetBufferedUpdateInterval => MxCommand.PayloadOneofCase.SetBufferedUpdateInterval,
+            MxCommandKind.Suspend => MxCommand.PayloadOneofCase.Suspend,
+            MxCommandKind.Activate => MxCommand.PayloadOneofCase.Activate,
+            MxCommandKind.Write => MxCommand.PayloadOneofCase.Write,
+            MxCommandKind.Write2 => MxCommand.PayloadOneofCase.Write2,
+            MxCommandKind.WriteSecured => MxCommand.PayloadOneofCase.WriteSecured,
+            MxCommandKind.WriteSecured2 => MxCommand.PayloadOneofCase.WriteSecured2,
+            MxCommandKind.AuthenticateUser => MxCommand.PayloadOneofCase.AuthenticateUser,
+            MxCommandKind.ArchestraUserToId => MxCommand.PayloadOneofCase.ArchestraUserToId,
+            MxCommandKind.Ping => MxCommand.PayloadOneofCase.Ping,
+            MxCommandKind.GetSessionState => MxCommand.PayloadOneofCase.GetSessionState,
+            MxCommandKind.GetWorkerInfo => MxCommand.PayloadOneofCase.GetWorkerInfo,
+            MxCommandKind.DrainEvents => MxCommand.PayloadOneofCase.DrainEvents,
+            MxCommandKind.ShutdownWorker => MxCommand.PayloadOneofCase.ShutdownWorker,
+            _ => MxCommand.PayloadOneofCase.None,
+        };
+    }
+
+    private static RpcException InvalidArgument(string detail)
+    {
+        return new RpcException(new Status(StatusCode.InvalidArgument, detail));
+    }
+}

src/MxGateway.Server/Metrics/GatewayMetrics.cs

@@ -0,0 +1,306 @@
+using System.Diagnostics.Metrics;
+
+namespace MxGateway.Server.Metrics;
+
+public sealed class GatewayMetrics : IDisposable
+{
+    public const string MeterName = "MxGateway.Server";
+
+    private readonly object _syncRoot = new();
+    private readonly Meter _meter;
+    private readonly Counter<long> _sessionsOpenedCounter;
+    private readonly Counter<long> _sessionsClosedCounter;
+    private readonly Counter<long> _commandsStartedCounter;
+    private readonly Counter<long> _commandsSucceededCounter;
+    private readonly Counter<long> _commandsFailedCounter;
+    private readonly Counter<long> _eventsReceivedCounter;
+    private readonly Counter<long> _queueOverflowsCounter;
+    private readonly Counter<long> _faultsCounter;
+    private readonly Counter<long> _workerKillsCounter;
+    private readonly Counter<long> _workerExitsCounter;
+    private readonly Counter<long> _heartbeatFailuresCounter;
+    private readonly Counter<long> _streamDisconnectsCounter;
+    private readonly Histogram<double> _workerStartupLatencyHistogram;
+    private readonly Histogram<double> _commandLatencyHistogram;
+    private readonly Histogram<double> _eventStreamSendLatencyHistogram;
+    private readonly Dictionary<string, long> _commandFailuresByMethod = new(StringComparer.OrdinalIgnoreCase);
+    private readonly Dictionary<string, long> _eventsByFamily = new(StringComparer.OrdinalIgnoreCase);
+
+    private int _openSessions;
+    private int _workersRunning;
+    private int _eventQueueDepth;
+    private long _sessionsOpened;
+    private long _sessionsClosed;
+    private long _commandsStarted;
+    private long _commandsSucceeded;
+    private long _commandsFailed;
+    private long _eventsReceived;
+    private long _queueOverflows;
+    private long _faults;
+    private long _workerKills;
+    private long _workerExits;
+    private long _heartbeatFailures;
+    private long _streamDisconnects;
+    private bool _disposed;
+
+    public GatewayMetrics()
+    {
+        _meter = new Meter(MeterName, typeof(GatewayMetrics).Assembly.GetName().Version?.ToString());
+        _sessionsOpenedCounter = _meter.CreateCounter<long>("mxgateway.sessions.opened");
+        _sessionsClosedCounter = _meter.CreateCounter<long>("mxgateway.sessions.closed");
+        _commandsStartedCounter = _meter.CreateCounter<long>("mxgateway.commands.started");
+        _commandsSucceededCounter = _meter.CreateCounter<long>("mxgateway.commands.succeeded");
+        _commandsFailedCounter = _meter.CreateCounter<long>("mxgateway.commands.failed");
+        _eventsReceivedCounter = _meter.CreateCounter<long>("mxgateway.events.received");
+        _queueOverflowsCounter = _meter.CreateCounter<long>("mxgateway.queues.overflows");
+        _faultsCounter = _meter.CreateCounter<long>("mxgateway.faults");
+        _workerKillsCounter = _meter.CreateCounter<long>("mxgateway.workers.killed");
+        _workerExitsCounter = _meter.CreateCounter<long>("mxgateway.workers.exited");
+        _heartbeatFailuresCounter = _meter.CreateCounter<long>("mxgateway.heartbeats.failed");
+        _streamDisconnectsCounter = _meter.CreateCounter<long>("mxgateway.grpc.streams.disconnected");
+        _workerStartupLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.workers.startup.duration", "ms");
+        _commandLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.commands.duration", "ms");
+        _eventStreamSendLatencyHistogram = _meter.CreateHistogram<double>("mxgateway.events.stream_send.duration", "ms");
+
+        _meter.CreateObservableGauge("mxgateway.sessions.open", GetOpenSessions);
+        _meter.CreateObservableGauge("mxgateway.workers.running", GetWorkersRunning);
+        _meter.CreateObservableGauge("mxgateway.events.queue.depth", GetEventQueueDepth);
+    }
+
+    public void SessionOpened()
+    {
+        lock (_syncRoot)
+        {
+            _openSessions++;
+            _sessionsOpened++;
+        }
+
+        _sessionsOpenedCounter.Add(1);
+    }
+
+    public void SessionClosed()
+    {
+        lock (_syncRoot)
+        {
+            if (_openSessions > 0)
+            {
+                _openSessions--;
+            }
+
+            _sessionsClosed++;
+        }
+
+        _sessionsClosedCounter.Add(1);
+    }
+
+    public void WorkerStarted(TimeSpan startupDuration)
+    {
+        lock (_syncRoot)
+        {
+            _workersRunning++;
+        }
+
+        _workerStartupLatencyHistogram.Record(startupDuration.TotalMilliseconds);
+    }
+
+    public void WorkerStopped(string reason)
+    {
+        lock (_syncRoot)
+        {
+            if (_workersRunning > 0)
+            {
+                _workersRunning--;
+            }
+
+            _workerExits++;
+        }
+
+        _workerExitsCounter.Add(1, new KeyValuePair<string, object?>("reason", reason));
+    }
+
+    public void WorkerKilled(string reason)
+    {
+        lock (_syncRoot)
+        {
+            _workerKills++;
+        }
+
+        _workerKillsCounter.Add(1, new KeyValuePair<string, object?>("reason", reason));
+    }
+
+    public void CommandStarted(string method)
+    {
+        lock (_syncRoot)
+        {
+            _commandsStarted++;
+        }
+
+        _commandsStartedCounter.Add(1, new KeyValuePair<string, object?>("method", method));
+    }
+
+    public void CommandSucceeded(string method, TimeSpan duration)
+    {
+        lock (_syncRoot)
+        {
+            _commandsSucceeded++;
+        }
+
+        KeyValuePair<string, object?> methodTag = new("method", method);
+        _commandsSucceededCounter.Add(1, methodTag);
+        _commandLatencyHistogram.Record(duration.TotalMilliseconds, methodTag);
+    }
+
+    public void CommandFailed(string method, string category, TimeSpan duration)
+    {
+        lock (_syncRoot)
+        {
+            _commandsFailed++;
+            Increment(_commandFailuresByMethod, method);
+        }
+
+        KeyValuePair<string, object?> methodTag = new("method", method);
+        KeyValuePair<string, object?> categoryTag = new("category", category);
+        _commandsFailedCounter.Add(1, methodTag, categoryTag);
+        _commandLatencyHistogram.Record(duration.TotalMilliseconds, methodTag, categoryTag);
+    }
+
+    public void EventReceived(string sessionId, string family)
+    {
+        lock (_syncRoot)
+        {
+            _eventsReceived++;
+            Increment(_eventsByFamily, family);
+        }
+
+        _eventsReceivedCounter.Add(
+            1,
+            new KeyValuePair<string, object?>("session_id", sessionId),
+            new KeyValuePair<string, object?>("family", family));
+    }
+
+    public void RecordEventStreamSend(string family, TimeSpan duration)
+    {
+        _eventStreamSendLatencyHistogram.Record(
+            duration.TotalMilliseconds,
+            new KeyValuePair<string, object?>("family", family));
+    }
+
+    public void SetEventQueueDepth(int depth)
+    {
+        if (depth < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(depth), depth, "Queue depth cannot be negative.");
+        }
+
+        lock (_syncRoot)
+        {
+            _eventQueueDepth = depth;
+        }
+    }
+
+    public void QueueOverflow(string queueName)
+    {
+        lock (_syncRoot)
+        {
+            _queueOverflows++;
+        }
+
+        _queueOverflowsCounter.Add(1, new KeyValuePair<string, object?>("queue", queueName));
+    }
+
+    public void Fault(string category)
+    {
+        lock (_syncRoot)
+        {
+            _faults++;
+        }
+
+        _faultsCounter.Add(1, new KeyValuePair<string, object?>("category", category));
+    }
+
+    public void HeartbeatFailed(string sessionId)
+    {
+        lock (_syncRoot)
+        {
+            _heartbeatFailures++;
+        }
+
+        _heartbeatFailuresCounter.Add(1, new KeyValuePair<string, object?>("session_id", sessionId));
+    }
+
+    public void StreamDisconnected(string reason)
+    {
+        lock (_syncRoot)
+        {
+            _streamDisconnects++;
+        }
+
+        _streamDisconnectsCounter.Add(1, new KeyValuePair<string, object?>("reason", reason));
+    }
+
+    public GatewayMetricsSnapshot GetSnapshot()
+    {
+        lock (_syncRoot)
+        {
+            return new GatewayMetricsSnapshot(
+                OpenSessions: _openSessions,
+                WorkersRunning: _workersRunning,
+                EventQueueDepth: _eventQueueDepth,
+                SessionsOpened: _sessionsOpened,
+                SessionsClosed: _sessionsClosed,
+                CommandsStarted: _commandsStarted,
+                CommandsSucceeded: _commandsSucceeded,
+                CommandsFailed: _commandsFailed,
+                EventsReceived: _eventsReceived,
+                QueueOverflows: _queueOverflows,
+                Faults: _faults,
+                WorkerKills: _workerKills,
+                WorkerExits: _workerExits,
+                HeartbeatFailures: _heartbeatFailures,
+                StreamDisconnects: _streamDisconnects,
+                CommandFailuresByMethod: new Dictionary<string, long>(_commandFailuresByMethod, StringComparer.OrdinalIgnoreCase),
+                EventsByFamily: new Dictionary<string, long>(_eventsByFamily, StringComparer.OrdinalIgnoreCase));
+        }
+    }
+
+    public void Dispose()
+    {
+        if (_disposed)
+        {
+            return;
+        }
+
+        _meter.Dispose();
+        _disposed = true;
+    }
+
+    private int GetOpenSessions()
+    {
+        lock (_syncRoot)
+        {
+            return _openSessions;
+        }
+    }
+
+    private int GetWorkersRunning()
+    {
+        lock (_syncRoot)
+        {
+            return _workersRunning;
+        }
+    }
+
+    private int GetEventQueueDepth()
+    {
+        lock (_syncRoot)
+        {
+            return _eventQueueDepth;
+        }
+    }
+
+    private static void Increment(Dictionary<string, long> values, string key)
+    {
+        values.TryGetValue(key, out long currentValue);
+        values[key] = currentValue + 1;
+    }
+}

src/MxGateway.Server/Metrics/GatewayMetricsSnapshot.cs

@@ -0,0 +1,20 @@
+namespace MxGateway.Server.Metrics;
+
+public sealed record GatewayMetricsSnapshot(
+    int OpenSessions,
+    int WorkersRunning,
+    int EventQueueDepth,
+    long SessionsOpened,
+    long SessionsClosed,
+    long CommandsStarted,
+    long CommandsSucceeded,
+    long CommandsFailed,
+    long EventsReceived,
+    long QueueOverflows,
+    long Faults,
+    long WorkerKills,
+    long WorkerExits,
+    long HeartbeatFailures,
+    long StreamDisconnects,
+    IReadOnlyDictionary<string, long> CommandFailuresByMethod,
+    IReadOnlyDictionary<string, long> EventsByFamily);

src/MxGateway.Server/MxGateway.Server.csproj

@@ -4,6 +4,11 @@
     <TargetFramework>net10.0</TargetFramework>
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="Grpc.AspNetCore" Version="2.76.0" />
+    <PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.7" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\MxGateway.Contracts\MxGateway.Contracts.csproj" />
   </ItemGroup>

src/MxGateway.Server/Program.cs

@@ -1,7 +1,43 @@
 using MxGateway.Server;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authentication;
 
-var app = GatewayApplication.Build(args);
+ApiKeyAdminParseResult apiKeyAdminCommand = ApiKeyAdminCommandLineParser.Parse(args);
+if (apiKeyAdminCommand.IsApiKeyCommand)
+{
+    if (apiKeyAdminCommand.Command is null)
+    {
+        await Console.Error.WriteLineAsync(apiKeyAdminCommand.Error);
+        return 2;
+    }
+
+    WebApplicationBuilder builder = GatewayApplication.CreateBuilder([]);
+    ApplyApiKeyAdminOverrides(builder.Configuration, apiKeyAdminCommand.Command);
+    await using WebApplication cliApp = builder.Build();
+    await using AsyncServiceScope scope = cliApp.Services.CreateAsyncScope();
+
+    ApiKeyAdminCliRunner runner = scope.ServiceProvider.GetRequiredService<ApiKeyAdminCliRunner>();
+
+    return await runner.RunAsync(apiKeyAdminCommand.Command, Console.Out, CancellationToken.None);
+}
+
+WebApplication app = GatewayApplication.Build(args);
 
 app.Run();
 
+return 0;
+
+static void ApplyApiKeyAdminOverrides(IConfiguration configuration, ApiKeyAdminCommand command)
+{
+    if (!string.IsNullOrWhiteSpace(command.SqlitePath))
+    {
+        configuration[$"{GatewayOptions.SectionName}:Authentication:SqlitePath"] = command.SqlitePath;
+    }
+
+    if (!string.IsNullOrWhiteSpace(command.Pepper))
+    {
+        configuration["MxGateway:ApiKeyPepper"] = command.Pepper;
+    }
+}
+
 public partial class Program;

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCliRunner.cs

@@ -0,0 +1,180 @@
+using System.Text.Json;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed class ApiKeyAdminCliRunner(
+    IAuthStoreMigrator migrator,
+    IApiKeyAdminStore adminStore,
+    IApiKeyAuditStore auditStore,
+    IApiKeySecretHasher hasher)
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        WriteIndented = true
+    };
+
+    public async Task<int> RunAsync(
+        ApiKeyAdminCommand command,
+        TextWriter output,
+        CancellationToken cancellationToken)
+    {
+        ApiKeyAdminOutput result = command.Kind switch
+        {
+            ApiKeyAdminCommandKind.InitDb => await InitDbAsync(cancellationToken).ConfigureAwait(false),
+            ApiKeyAdminCommandKind.CreateKey => await CreateKeyAsync(command, cancellationToken).ConfigureAwait(false),
+            ApiKeyAdminCommandKind.ListKeys => await ListKeysAsync(cancellationToken).ConfigureAwait(false),
+            ApiKeyAdminCommandKind.RevokeKey => await RevokeKeyAsync(command, cancellationToken).ConfigureAwait(false),
+            ApiKeyAdminCommandKind.RotateKey => await RotateKeyAsync(command, cancellationToken).ConfigureAwait(false),
+            _ => throw new InvalidOperationException($"Unsupported API key command '{command.Kind}'.")
+        };
+
+        await WriteOutputAsync(command, result, output).ConfigureAwait(false);
+
+        return 0;
+    }
+
+    private async Task<ApiKeyAdminOutput> InitDbAsync(CancellationToken cancellationToken)
+    {
+        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+        await AppendAuditAsync(null, "init-db", null, cancellationToken).ConfigureAwait(false);
+
+        return new ApiKeyAdminOutput("init-db", "initialized", null, []);
+    }
+
+    private async Task<ApiKeyAdminOutput> CreateKeyAsync(
+        ApiKeyAdminCommand command,
+        CancellationToken cancellationToken)
+    {
+        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+
+        string keyId = Required(command.KeyId);
+        string secret = ApiKeySecretGenerator.Generate();
+        string apiKey = FormatApiKey(keyId, secret);
+
+        await adminStore.CreateAsync(
+                new ApiKeyCreateRequest(
+                    KeyId: keyId,
+                    KeyPrefix: $"mxgw_{keyId}",
+                    SecretHash: hasher.HashSecret(secret),
+                    DisplayName: Required(command.DisplayName),
+                    Scopes: command.Scopes,
+                    CreatedUtc: DateTimeOffset.UtcNow),
+                cancellationToken)
+            .ConfigureAwait(false);
+        await AppendAuditAsync(keyId, "create-key", null, cancellationToken).ConfigureAwait(false);
+
+        return new ApiKeyAdminOutput("create-key", "created", apiKey, []);
+    }
+
+    private async Task<ApiKeyAdminOutput> ListKeysAsync(CancellationToken cancellationToken)
+    {
+        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+        IReadOnlyList<ApiKeyRecord> keys = await adminStore.ListAsync(cancellationToken).ConfigureAwait(false);
+        await AppendAuditAsync(null, "list-keys", null, cancellationToken).ConfigureAwait(false);
+
+        return new ApiKeyAdminOutput(
+            "list-keys",
+            "ok",
+            null,
+            keys.Select(ToListedKey).ToArray());
+    }
+
+    private async Task<ApiKeyAdminOutput> RevokeKeyAsync(
+        ApiKeyAdminCommand command,
+        CancellationToken cancellationToken)
+    {
+        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+
+        string keyId = Required(command.KeyId);
+        bool revoked = await adminStore.RevokeAsync(keyId, DateTimeOffset.UtcNow, cancellationToken)
+            .ConfigureAwait(false);
+
+        await AppendAuditAsync(keyId, "revoke-key", revoked ? "revoked" : "not-found-or-already-revoked", cancellationToken)
+            .ConfigureAwait(false);
+
+        return new ApiKeyAdminOutput("revoke-key", revoked ? "revoked" : "not-found-or-already-revoked", null, []);
+    }
+
+    private async Task<ApiKeyAdminOutput> RotateKeyAsync(
+        ApiKeyAdminCommand command,
+        CancellationToken cancellationToken)
+    {
+        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+
+        string keyId = Required(command.KeyId);
+        string secret = ApiKeySecretGenerator.Generate();
+        string apiKey = FormatApiKey(keyId, secret);
+
+        bool rotated = await adminStore.RotateAsync(keyId, hasher.HashSecret(secret), DateTimeOffset.UtcNow, cancellationToken)
+            .ConfigureAwait(false);
+
+        await AppendAuditAsync(keyId, "rotate-key", rotated ? "rotated" : "not-found", cancellationToken)
+            .ConfigureAwait(false);
+
+        return new ApiKeyAdminOutput("rotate-key", rotated ? "rotated" : "not-found", rotated ? apiKey : null, []);
+    }
+
+    private static async Task WriteOutputAsync(
+        ApiKeyAdminCommand command,
+        ApiKeyAdminOutput result,
+        TextWriter output)
+    {
+        if (command.Json)
+        {
+            await output.WriteLineAsync(JsonSerializer.Serialize(result, JsonOptions)).ConfigureAwait(false);
+            return;
+        }
+
+        await output.WriteLineAsync($"{result.Command}: {result.Status}").ConfigureAwait(false);
+
+        if (result.ApiKey is not null)
+        {
+            await output.WriteLineAsync($"API key: {result.ApiKey}").ConfigureAwait(false);
+        }
+
+        foreach (ApiKeyAdminListedKey key in result.Keys)
+        {
+            string revoked = key.RevokedUtc is null ? "active" : "revoked";
+            await output.WriteLineAsync($"{key.KeyId}\t{key.DisplayName}\t{revoked}\t{string.Join(',', key.Scopes)}")
+                .ConfigureAwait(false);
+        }
+    }
+
+    private async Task AppendAuditAsync(
+        string? keyId,
+        string eventType,
+        string? details,
+        CancellationToken cancellationToken)
+    {
+        await auditStore.AppendAsync(
+                new ApiKeyAuditEntry(
+                    KeyId: keyId,
+                    EventType: eventType,
+                    RemoteAddress: null,
+                    Details: details),
+                cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    private static ApiKeyAdminListedKey ToListedKey(ApiKeyRecord key)
+    {
+        return new ApiKeyAdminListedKey(
+            KeyId: key.KeyId,
+            KeyPrefix: key.KeyPrefix,
+            DisplayName: key.DisplayName,
+            Scopes: key.Scopes,
+            CreatedUtc: key.CreatedUtc,
+            LastUsedUtc: key.LastUsedUtc,
+            RevokedUtc: key.RevokedUtc);
+    }
+
+    private static string FormatApiKey(string keyId, string secret)
+    {
+        return $"mxgw_{keyId}_{secret}";
+    }
+
+    private static string Required(string? value)
+    {
+        return value ?? throw new InvalidOperationException("Required command value was not provided.");
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommand.cs

@@ -0,0 +1,10 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyAdminCommand(
+    ApiKeyAdminCommandKind Kind,
+    bool Json,
+    string? SqlitePath,
+    string? Pepper,
+    string? KeyId,
+    string? DisplayName,
+    IReadOnlySet<string> Scopes);

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommandKind.cs

@@ -0,0 +1,10 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public enum ApiKeyAdminCommandKind
+{
+    InitDb,
+    CreateKey,
+    ListKeys,
+    RevokeKey,
+    RotateKey
+}

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs

@@ -0,0 +1,159 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public static class ApiKeyAdminCommandLineParser
+{
+    public static ApiKeyAdminParseResult Parse(IReadOnlyList<string> args)
+    {
+        if (args.Count == 0 || !string.Equals(args[0], "apikey", StringComparison.OrdinalIgnoreCase))
+        {
+            return ApiKeyAdminParseResult.NotApiKeyCommand();
+        }
+
+        if (args.Count < 2)
+        {
+            return ApiKeyAdminParseResult.Fail("Missing apikey subcommand.");
+        }
+
+        if (!TryParseKind(args[1], out ApiKeyAdminCommandKind kind))
+        {
+            return ApiKeyAdminParseResult.Fail($"Unknown apikey subcommand '{args[1]}'.");
+        }
+
+        Dictionary<string, string?> options = new(StringComparer.OrdinalIgnoreCase);
+        bool json = false;
+
+        for (int index = 2; index < args.Count; index++)
+        {
+            string arg = args[index];
+            if (string.Equals(arg, "--json", StringComparison.OrdinalIgnoreCase))
+            {
+                json = true;
+                continue;
+            }
+
+            if (!arg.StartsWith("--", StringComparison.Ordinal))
+            {
+                return ApiKeyAdminParseResult.Fail($"Unexpected argument '{arg}'.");
+            }
+
+            string name = arg[2..];
+            string? value;
+
+            int equalsIndex = name.IndexOf('=', StringComparison.Ordinal);
+            if (equalsIndex >= 0)
+            {
+                value = name[(equalsIndex + 1)..];
+                name = name[..equalsIndex];
+            }
+            else
+            {
+                if (index + 1 >= args.Count || args[index + 1].StartsWith("--", StringComparison.Ordinal))
+                {
+                    return ApiKeyAdminParseResult.Fail($"Option '--{name}' requires a value.");
+                }
+
+                value = args[++index];
+            }
+
+            options[name] = value;
+        }
+
+        string? keyId = GetOption(options, "key-id");
+        string? displayName = GetOption(options, "display-name");
+        IReadOnlySet<string> scopes = ParseScopes(GetOption(options, "scopes"));
+
+        string? validationError = Validate(kind, keyId, displayName);
+        if (validationError is not null)
+        {
+            return ApiKeyAdminParseResult.Fail(validationError);
+        }
+
+        return ApiKeyAdminParseResult.Success(new ApiKeyAdminCommand(
+            Kind: kind,
+            Json: json,
+            SqlitePath: GetOption(options, "sqlite-path"),
+            Pepper: GetOption(options, "pepper"),
+            KeyId: keyId,
+            DisplayName: displayName,
+            Scopes: scopes));
+    }
+
+    private static bool TryParseKind(string value, out ApiKeyAdminCommandKind kind)
+    {
+        switch (value.ToLowerInvariant())
+        {
+            case "init-db":
+                kind = ApiKeyAdminCommandKind.InitDb;
+                return true;
+            case "create-key":
+                kind = ApiKeyAdminCommandKind.CreateKey;
+                return true;
+            case "list-keys":
+                kind = ApiKeyAdminCommandKind.ListKeys;
+                return true;
+            case "revoke-key":
+                kind = ApiKeyAdminCommandKind.RevokeKey;
+                return true;
+            case "rotate-key":
+                kind = ApiKeyAdminCommandKind.RotateKey;
+                return true;
+            default:
+                kind = default;
+                return false;
+        }
+    }
+
+    private static string? Validate(ApiKeyAdminCommandKind kind, string? keyId, string? displayName)
+    {
+        if (kind is ApiKeyAdminCommandKind.CreateKey or ApiKeyAdminCommandKind.RevokeKey or ApiKeyAdminCommandKind.RotateKey
+            && string.IsNullOrWhiteSpace(keyId))
+        {
+            return $"Subcommand '{KindName(kind)}' requires --key-id.";
+        }
+
+        if (!string.IsNullOrWhiteSpace(keyId) && !IsValidKeyId(keyId))
+        {
+            return "API key id may contain only letters, numbers, periods, and hyphens.";
+        }
+
+        if (kind == ApiKeyAdminCommandKind.CreateKey && string.IsNullOrWhiteSpace(displayName))
+        {
+            return "Subcommand 'create-key' requires --display-name.";
+        }
+
+        return null;
+    }
+
+    private static string KindName(ApiKeyAdminCommandKind kind)
+    {
+        return kind switch
+        {
+            ApiKeyAdminCommandKind.InitDb => "init-db",
+            ApiKeyAdminCommandKind.CreateKey => "create-key",
+            ApiKeyAdminCommandKind.ListKeys => "list-keys",
+            ApiKeyAdminCommandKind.RevokeKey => "revoke-key",
+            ApiKeyAdminCommandKind.RotateKey => "rotate-key",
+            _ => kind.ToString()
+        };
+    }
+
+    private static bool IsValidKeyId(string keyId)
+    {
+        return keyId.All(character =>
+            char.IsAsciiLetterOrDigit(character)
+            || character is '.' or '-');
+    }
+
+    private static string? GetOption(Dictionary<string, string?> options, string name)
+    {
+        return options.TryGetValue(name, out string? value) ? value : null;
+    }
+
+    private static IReadOnlySet<string> ParseScopes(string? scopes)
+    {
+        return new HashSet<string>(
+            (scopes ?? string.Empty)
+                .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries),
+            StringComparer.Ordinal);
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyAdminListedKey.cs

@@ -0,0 +1,10 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyAdminListedKey(
+    string KeyId,
+    string KeyPrefix,
+    string DisplayName,
+    IReadOnlySet<string> Scopes,
+    DateTimeOffset CreatedUtc,
+    DateTimeOffset? LastUsedUtc,
+    DateTimeOffset? RevokedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyAdminOutput.cs

@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyAdminOutput(
+    string Command,
+    string Status,
+    string? ApiKey,
+    IReadOnlyList<ApiKeyAdminListedKey> Keys);

src/MxGateway.Server/Security/Authentication/ApiKeyAdminParseResult.cs

@@ -0,0 +1,22 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyAdminParseResult(
+    bool IsApiKeyCommand,
+    ApiKeyAdminCommand? Command,
+    string? Error)
+{
+    public static ApiKeyAdminParseResult NotApiKeyCommand()
+    {
+        return new ApiKeyAdminParseResult(false, null, null);
+    }
+
+    public static ApiKeyAdminParseResult Success(ApiKeyAdminCommand command)
+    {
+        return new ApiKeyAdminParseResult(true, command, null);
+    }
+
+    public static ApiKeyAdminParseResult Fail(string error)
+    {
+        return new ApiKeyAdminParseResult(true, null, error);
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyAuditEntry.cs

@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyAuditEntry(
+    string? KeyId,
+    string EventType,
+    string? RemoteAddress,
+    string? Details);

src/MxGateway.Server/Security/Authentication/ApiKeyAuditRecord.cs

@@ -0,0 +1,9 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyAuditRecord(
+    long AuditId,
+    string? KeyId,
+    string EventType,
+    string? RemoteAddress,
+    DateTimeOffset CreatedUtc,
+    string? Details);

src/MxGateway.Server/Security/Authentication/ApiKeyCreateRequest.cs

@@ -0,0 +1,9 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyCreateRequest(
+    string KeyId,
+    string KeyPrefix,
+    byte[] SecretHash,
+    string DisplayName,
+    IReadOnlySet<string> Scopes,
+    DateTimeOffset CreatedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyIdentity.cs

@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyIdentity(
+    string KeyId,
+    string KeyPrefix,
+    string DisplayName,
+    IReadOnlySet<string> Scopes);

src/MxGateway.Server/Security/Authentication/ApiKeyParser.cs

@@ -0,0 +1,45 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed class ApiKeyParser : IApiKeyParser
+{
+    private const string BearerPrefix = "Bearer ";
+    private const string TokenPrefix = "mxgw_";
+
+    public bool TryParseAuthorizationHeader(string? authorizationHeader, out ParsedApiKey? apiKey)
+    {
+        apiKey = null;
+
+        if (string.IsNullOrWhiteSpace(authorizationHeader)
+            || !authorizationHeader.StartsWith(BearerPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        string token = authorizationHeader[BearerPrefix.Length..].Trim();
+
+        if (!token.StartsWith(TokenPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        string keyPayload = token[TokenPrefix.Length..];
+        int separatorIndex = keyPayload.IndexOf('_', StringComparison.Ordinal);
+
+        if (separatorIndex <= 0 || separatorIndex == keyPayload.Length - 1)
+        {
+            return false;
+        }
+
+        string keyId = keyPayload[..separatorIndex];
+        string secret = keyPayload[(separatorIndex + 1)..];
+
+        if (string.IsNullOrWhiteSpace(keyId) || string.IsNullOrWhiteSpace(secret))
+        {
+            return false;
+        }
+
+        apiKey = new ParsedApiKey(keyId, secret);
+
+        return true;
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyPepperUnavailableException.cs

@@ -0,0 +1,4 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed class ApiKeyPepperUnavailableException(string pepperSecretName)
+    : InvalidOperationException($"API key pepper secret '{pepperSecretName}' is not configured.");

src/MxGateway.Server/Security/Authentication/ApiKeyRecord.cs

@@ -0,0 +1,11 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyRecord(
+    string KeyId,
+    string KeyPrefix,
+    byte[] SecretHash,
+    string DisplayName,
+    IReadOnlySet<string> Scopes,
+    DateTimeOffset CreatedUtc,
+    DateTimeOffset? LastUsedUtc,
+    DateTimeOffset? RevokedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyRecordReader.cs

@@ -0,0 +1,26 @@
+using Microsoft.Data.Sqlite;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public static class ApiKeyRecordReader
+{
+    public static ApiKeyRecord Read(SqliteDataReader reader)
+    {
+        return new ApiKeyRecord(
+            KeyId: reader.GetString(0),
+            KeyPrefix: reader.GetString(1),
+            SecretHash: (byte[])reader["secret_hash"],
+            DisplayName: reader.GetString(3),
+            Scopes: ApiKeyScopeSerializer.Deserialize(reader.GetString(4)),
+            CreatedUtc: DateTimeOffset.Parse(reader.GetString(5), System.Globalization.CultureInfo.InvariantCulture),
+            LastUsedUtc: ReadNullableDateTimeOffset(reader, 6),
+            RevokedUtc: ReadNullableDateTimeOffset(reader, 7));
+    }
+
+    private static DateTimeOffset? ReadNullableDateTimeOffset(SqliteDataReader reader, int ordinal)
+    {
+        return reader.IsDBNull(ordinal)
+            ? null
+            : DateTimeOffset.Parse(reader.GetString(ordinal), System.Globalization.CultureInfo.InvariantCulture);
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyScopeSerializer.cs

@@ -0,0 +1,23 @@
+using System.Text.Json;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public static class ApiKeyScopeSerializer
+{
+    public static string Serialize(IReadOnlySet<string> scopes)
+    {
+        return JsonSerializer.Serialize(scopes.Order(StringComparer.Ordinal));
+    }
+
+    public static IReadOnlySet<string> Deserialize(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return new HashSet<string>(StringComparer.Ordinal);
+        }
+
+        string[]? scopes = JsonSerializer.Deserialize<string[]>(value);
+
+        return new HashSet<string>(scopes ?? [], StringComparer.Ordinal);
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeySecretGenerator.cs

@@ -0,0 +1,17 @@
+using System.Security.Cryptography;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public static class ApiKeySecretGenerator
+{
+    public static string Generate()
+    {
+        Span<byte> bytes = stackalloc byte[32];
+        RandomNumberGenerator.Fill(bytes);
+
+        return Convert.ToBase64String(bytes)
+            .TrimEnd('=')
+            .Replace('+', '-')
+            .Replace('/', '_');
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeySecretHasher.cs

@@ -0,0 +1,35 @@
+using System.Security.Cryptography;
+using System.Text;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed class ApiKeySecretHasher(
+    IConfiguration configuration,
+    IOptions<GatewayOptions> options) : IApiKeySecretHasher
+{
+    public byte[] HashSecret(string secret)
+    {
+        string pepper = GetPepper();
+        byte[] pepperBytes = Encoding.UTF8.GetBytes(pepper);
+        byte[] secretBytes = Encoding.UTF8.GetBytes(secret);
+
+        using HMACSHA256 hmac = new(pepperBytes);
+
+        return hmac.ComputeHash(secretBytes);
+    }
+
+    private string GetPepper()
+    {
+        string pepperSecretName = options.Value.Authentication.PepperSecretName;
+        string? pepper = configuration[pepperSecretName];
+
+        if (string.IsNullOrWhiteSpace(pepper))
+        {
+            throw new ApiKeyPepperUnavailableException(pepperSecretName);
+        }
+
+        return pepper;
+    }
+}

src/MxGateway.Server/Security/Authentication/ApiKeyVerificationFailure.cs

@@ -0,0 +1,11 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public enum ApiKeyVerificationFailure
+{
+    None,
+    MissingOrMalformedCredentials,
+    PepperUnavailable,
+    KeyNotFound,
+    KeyRevoked,
+    SecretMismatch
+}