Issue #10: implement worker process launcher

Verified with dotnet build src\\MxGateway.sln and dotnet test src\\MxGateway.sln.

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-process-design.md

@@ -360,6 +360,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.
@@ -589,6 +598,20 @@ 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.
+
 Recommended scopes:
 
 - `session:open`

gateway.md

@@ -47,6 +47,8 @@ Detailed follow-up docs:
   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.

src/MxGateway.Server/GatewayApplication.cs

@@ -3,6 +3,7 @@ using MxGateway.Server.Configuration;
 using MxGateway.Server.Diagnostics;
 using MxGateway.Server.Metrics;
 using MxGateway.Server.Security.Authentication;
+using MxGateway.Server.Workers;
 
 namespace MxGateway.Server;
 
@@ -27,6 +28,7 @@ public static class GatewayApplication
         builder.Services.AddSqliteAuthStore();
         builder.Services.AddHealthChecks();
         builder.Services.AddSingleton<GatewayMetrics>();
+        builder.Services.AddWorkerProcessLauncher();
 
         return builder;
     }

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/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
+}

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

@@ -0,0 +1,23 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ApiKeyVerificationResult(
+    bool Succeeded,
+    ApiKeyIdentity? Identity,
+    ApiKeyVerificationFailure Failure)
+{
+    public static ApiKeyVerificationResult Success(ApiKeyIdentity identity)
+    {
+        return new ApiKeyVerificationResult(
+            Succeeded: true,
+            Identity: identity,
+            Failure: ApiKeyVerificationFailure.None);
+    }
+
+    public static ApiKeyVerificationResult Fail(ApiKeyVerificationFailure failure)
+    {
+        return new ApiKeyVerificationResult(
+            Succeeded: false,
+            Identity: null,
+            Failure: failure);
+    }
+}

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

@@ -0,0 +1,57 @@
+using System.Security.Cryptography;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed class ApiKeyVerifier(
+    IApiKeyParser parser,
+    IApiKeySecretHasher hasher,
+    IApiKeyStore keyStore) : IApiKeyVerifier
+{
+    public async Task<ApiKeyVerificationResult> VerifyAsync(
+        string? authorizationHeader,
+        CancellationToken cancellationToken)
+    {
+        if (!parser.TryParseAuthorizationHeader(authorizationHeader, out ParsedApiKey? parsedKey)
+            || parsedKey is null)
+        {
+            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.MissingOrMalformedCredentials);
+        }
+
+        ApiKeyRecord? storedKey = await keyStore.FindByKeyIdAsync(parsedKey.KeyId, cancellationToken)
+            .ConfigureAwait(false);
+
+        if (storedKey is null)
+        {
+            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.KeyNotFound);
+        }
+
+        if (storedKey.RevokedUtc is not null)
+        {
+            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.KeyRevoked);
+        }
+
+        byte[] presentedHash;
+        try
+        {
+            presentedHash = hasher.HashSecret(parsedKey.Secret);
+        }
+        catch (ApiKeyPepperUnavailableException)
+        {
+            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.PepperUnavailable);
+        }
+
+        if (!CryptographicOperations.FixedTimeEquals(presentedHash, storedKey.SecretHash))
+        {
+            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.SecretMismatch);
+        }
+
+        await keyStore.MarkKeyUsedAsync(storedKey.KeyId, DateTimeOffset.UtcNow, cancellationToken)
+            .ConfigureAwait(false);
+
+        return ApiKeyVerificationResult.Success(new ApiKeyIdentity(
+            KeyId: storedKey.KeyId,
+            KeyPrefix: storedKey.KeyPrefix,
+            DisplayName: storedKey.DisplayName,
+            Scopes: storedKey.Scopes));
+    }
+}

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

@@ -4,6 +4,9 @@ public static class AuthStoreServiceCollectionExtensions
 {
     public static IServiceCollection AddSqliteAuthStore(this IServiceCollection services)
     {
+        services.AddSingleton<IApiKeyParser, ApiKeyParser>();
+        services.AddSingleton<IApiKeySecretHasher, ApiKeySecretHasher>();
+        services.AddSingleton<IApiKeyVerifier, ApiKeyVerifier>();
         services.AddSingleton<AuthSqliteConnectionFactory>();
         services.AddSingleton<IAuthStoreMigrator, SqliteAuthStoreMigrator>();
         services.AddSingleton<IApiKeyStore, SqliteApiKeyStore>();

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

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public interface IApiKeyParser
+{
+    bool TryParseAuthorizationHeader(string? authorizationHeader, out ParsedApiKey? apiKey);
+}

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

@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public interface IApiKeySecretHasher
+{
+    byte[] HashSecret(string secret);
+}

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

@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public interface IApiKeyVerifier
+{
+    Task<ApiKeyVerificationResult> VerifyAsync(
+        string? authorizationHeader,
+        CancellationToken cancellationToken);
+}

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

@@ -0,0 +1,3 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed record ParsedApiKey(string KeyId, string Secret);

src/MxGateway.Server/Workers/IWorkerProcess.cs

@@ -0,0 +1,14 @@
+namespace MxGateway.Server.Workers;
+
+public interface IWorkerProcess : IDisposable
+{
+    int Id { get; }
+
+    bool HasExited { get; }
+
+    int? ExitCode { get; }
+
+    ValueTask WaitForExitAsync(CancellationToken cancellationToken);
+
+    void Kill(bool entireProcessTree);
+}

src/MxGateway.Server/Workers/IWorkerProcessFactory.cs

@@ -0,0 +1,8 @@
+using System.Diagnostics;
+
+namespace MxGateway.Server.Workers;
+
+public interface IWorkerProcessFactory
+{
+    IWorkerProcess Start(ProcessStartInfo startInfo);
+}

src/MxGateway.Server/Workers/IWorkerProcessLauncher.cs

@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Workers;
+
+public interface IWorkerProcessLauncher
+{
+    Task<WorkerProcessHandle> LaunchAsync(
+        WorkerProcessLaunchRequest request,
+        CancellationToken cancellationToken = default);
+}

src/MxGateway.Server/Workers/IWorkerStartupProbe.cs

@@ -0,0 +1,9 @@
+namespace MxGateway.Server.Workers;
+
+public interface IWorkerStartupProbe
+{
+    Task WaitUntilReadyAsync(
+        IWorkerProcess process,
+        WorkerProcessLaunchRequest request,
+        CancellationToken cancellationToken);
+}

src/MxGateway.Server/Workers/SystemWorkerProcess.cs

@@ -0,0 +1,27 @@
+using System.Diagnostics;
+
+namespace MxGateway.Server.Workers;
+
+internal sealed class SystemWorkerProcess(Process process) : IWorkerProcess
+{
+    public int Id => process.Id;
+
+    public bool HasExited => process.HasExited;
+
+    public int? ExitCode => process.HasExited ? process.ExitCode : null;
+
+    public async ValueTask WaitForExitAsync(CancellationToken cancellationToken)
+    {
+        await process.WaitForExitAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    public void Kill(bool entireProcessTree)
+    {
+        process.Kill(entireProcessTree);
+    }
+
+    public void Dispose()
+    {
+        process.Dispose();
+    }
+}

src/MxGateway.Server/Workers/SystemWorkerProcessFactory.cs

@@ -0,0 +1,22 @@
+using System.Diagnostics;
+
+namespace MxGateway.Server.Workers;
+
+public sealed class SystemWorkerProcessFactory : IWorkerProcessFactory
+{
+    public IWorkerProcess Start(ProcessStartInfo startInfo)
+    {
+        Process process = new()
+        {
+            StartInfo = startInfo,
+        };
+
+        if (!process.Start())
+        {
+            process.Dispose();
+            throw new InvalidOperationException("Worker process failed to start.");
+        }
+
+        return new SystemWorkerProcess(process);
+    }
+}

src/MxGateway.Server/Workers/WorkerExecutableValidator.cs

@@ -0,0 +1,80 @@
+using System.Buffers.Binary;
+using MxGateway.Server.Configuration;
+
+namespace MxGateway.Server.Workers;
+
+internal static class WorkerExecutableValidator
+{
+    private const ushort ImageFileMachineI386 = 0x014c;
+    private const ushort ImageFileMachineAmd64 = 0x8664;
+    private const int DosHeaderSignatureOffset = 0;
+    private const int PeHeaderOffsetPointer = 0x3c;
+    private const int PeSignatureSize = 4;
+    private const int MachineOffsetFromPeHeader = PeSignatureSize;
+    private const int MinimumHeaderSize = 0x40;
+
+    public static void Validate(
+        string executablePath,
+        WorkerArchitecture requiredArchitecture)
+    {
+        ushort machine = ReadMachineType(executablePath);
+        ushort expectedMachine = requiredArchitecture switch
+        {
+            WorkerArchitecture.X86 => ImageFileMachineI386,
+            WorkerArchitecture.X64 => ImageFileMachineAmd64,
+            _ => throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidExecutable,
+                "Worker executable required architecture is unsupported."),
+        };
+
+        if (machine != expectedMachine)
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidExecutable,
+                $"Worker executable architecture does not match required {requiredArchitecture} architecture.");
+        }
+    }
+
+    private static ushort ReadMachineType(string executablePath)
+    {
+        byte[] header = new byte[MinimumHeaderSize];
+        using FileStream stream = File.OpenRead(executablePath);
+        if (stream.Read(header) < header.Length)
+        {
+            throw InvalidExecutable("Worker executable is too small to contain a valid PE header.");
+        }
+
+        if (header[DosHeaderSignatureOffset] != 'M' || header[DosHeaderSignatureOffset + 1] != 'Z')
+        {
+            throw InvalidExecutable("Worker executable does not contain an MZ header.");
+        }
+
+        int peHeaderOffset = BinaryPrimitives.ReadInt32LittleEndian(header.AsSpan(PeHeaderOffsetPointer, sizeof(int)));
+        if (peHeaderOffset < MinimumHeaderSize)
+        {
+            throw InvalidExecutable("Worker executable PE header offset is invalid.");
+        }
+
+        byte[] peHeaderBytes = new byte[PeSignatureSize + sizeof(ushort)];
+        stream.Position = peHeaderOffset;
+        if (stream.Read(peHeaderBytes) < peHeaderBytes.Length)
+        {
+            throw InvalidExecutable("Worker executable PE header is missing.");
+        }
+
+        if (peHeaderBytes[0] != 'P' || peHeaderBytes[1] != 'E' || peHeaderBytes[2] != 0 || peHeaderBytes[3] != 0)
+        {
+            throw InvalidExecutable("Worker executable does not contain a PE header.");
+        }
+
+        return BinaryPrimitives.ReadUInt16LittleEndian(
+            peHeaderBytes.AsSpan(MachineOffsetFromPeHeader, sizeof(ushort)));
+    }
+
+    private static WorkerProcessLaunchException InvalidExecutable(string message)
+    {
+        return new WorkerProcessLaunchException(
+            WorkerProcessLaunchErrorCode.InvalidExecutable,
+            message);
+    }
+}

src/MxGateway.Server/Workers/WorkerProcessCommandLine.cs

@@ -0,0 +1,30 @@
+namespace MxGateway.Server.Workers;
+
+public sealed class WorkerProcessCommandLine
+{
+    public WorkerProcessCommandLine(
+        string executablePath,
+        IReadOnlyList<string> arguments)
+    {
+        ExecutablePath = executablePath;
+        Arguments = arguments;
+    }
+
+    public string ExecutablePath { get; }
+
+    public IReadOnlyList<string> Arguments { get; }
+
+    public override string ToString()
+    {
+        return string.Join(
+            " ",
+            new[] { Quote(ExecutablePath) }.Concat(Arguments.Select(Quote)));
+    }
+
+    private static string Quote(string value)
+    {
+        return value.Contains(' ', StringComparison.Ordinal)
+            ? $"\"{value}\""
+            : value;
+    }
+}

src/MxGateway.Server/Workers/WorkerProcessHandle.cs

@@ -0,0 +1,28 @@
+namespace MxGateway.Server.Workers;
+
+public sealed class WorkerProcessHandle : IDisposable
+{
+    public WorkerProcessHandle(
+        IWorkerProcess process,
+        WorkerProcessCommandLine commandLine,
+        DateTimeOffset launchedAt)
+    {
+        Process = process;
+        ProcessId = process.Id;
+        CommandLine = commandLine;
+        LaunchedAt = launchedAt;
+    }
+
+    public IWorkerProcess Process { get; }
+
+    public int ProcessId { get; }
+
+    public WorkerProcessCommandLine CommandLine { get; }
+
+    public DateTimeOffset LaunchedAt { get; }
+
+    public void Dispose()
+    {
+        Process.Dispose();
+    }
+}

src/MxGateway.Server/Workers/WorkerProcessLaunchErrorCode.cs

@@ -0,0 +1,13 @@
+namespace MxGateway.Server.Workers;
+
+public enum WorkerProcessLaunchErrorCode
+{
+    Unknown = 0,
+    InvalidRequest = 1,
+    ExecutableNotFound = 2,
+    InvalidExecutable = 3,
+    InvalidWorkingDirectory = 4,
+    StartFailed = 5,
+    StartupTimeout = 6,
+    StartupFailed = 7,
+}

src/MxGateway.Server/Workers/WorkerProcessLaunchException.cs

@@ -0,0 +1,23 @@
+namespace MxGateway.Server.Workers;
+
+public sealed class WorkerProcessLaunchException : Exception
+{
+    public WorkerProcessLaunchException(
+        WorkerProcessLaunchErrorCode errorCode,
+        string message)
+        : base(message)
+    {
+        ErrorCode = errorCode;
+    }
+
+    public WorkerProcessLaunchException(
+        WorkerProcessLaunchErrorCode errorCode,
+        string message,
+        Exception innerException)
+        : base(message, innerException)
+    {
+        ErrorCode = errorCode;
+    }
+
+    public WorkerProcessLaunchErrorCode ErrorCode { get; }
+}

src/MxGateway.Server/Workers/WorkerProcessLaunchRequest.cs

@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Workers;
+
+public sealed record WorkerProcessLaunchRequest(
+    string SessionId,
+    string PipeName,
+    uint ProtocolVersion,
+    string Nonce,
+    IDisposable? PipeReservation = null);

src/MxGateway.Server/Workers/WorkerProcessLauncher.cs

@@ -0,0 +1,262 @@
+using System.Diagnostics;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Metrics;
+
+namespace MxGateway.Server.Workers;
+
+public sealed class WorkerProcessLauncher : IWorkerProcessLauncher
+{
+    public const string WorkerNonceEnvironmentVariableName = "MXGATEWAY_WORKER_NONCE";
+
+    private readonly IWorkerProcessFactory _processFactory;
+    private readonly IWorkerStartupProbe _startupProbe;
+    private readonly GatewayMetrics _metrics;
+    private readonly TimeProvider _timeProvider;
+    private readonly WorkerOptions _workerOptions;
+
+    public WorkerProcessLauncher(
+        IOptions<GatewayOptions> gatewayOptions,
+        IWorkerProcessFactory processFactory,
+        IWorkerStartupProbe startupProbe,
+        GatewayMetrics metrics,
+        TimeProvider? timeProvider = null)
+    {
+        ArgumentNullException.ThrowIfNull(gatewayOptions);
+        ArgumentNullException.ThrowIfNull(processFactory);
+        ArgumentNullException.ThrowIfNull(startupProbe);
+        ArgumentNullException.ThrowIfNull(metrics);
+
+        _workerOptions = gatewayOptions.Value.Worker;
+        _processFactory = processFactory;
+        _startupProbe = startupProbe;
+        _metrics = metrics;
+        _timeProvider = timeProvider ?? TimeProvider.System;
+    }
+
+    public async Task<WorkerProcessHandle> LaunchAsync(
+        WorkerProcessLaunchRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            return await LaunchCoreAsync(request, cancellationToken).ConfigureAwait(false);
+        }
+        catch
+        {
+            request.PipeReservation?.Dispose();
+            throw;
+        }
+    }
+
+    private async Task<WorkerProcessHandle> LaunchCoreAsync(
+        WorkerProcessLaunchRequest request,
+        CancellationToken cancellationToken)
+    {
+        ValidateRequest(request);
+
+        DateTimeOffset startedAt = _timeProvider.GetUtcNow();
+        ProcessStartInfo startInfo = CreateStartInfo(request, out WorkerProcessCommandLine commandLine);
+
+        IWorkerProcess process;
+        try
+        {
+            process = _processFactory.Start(startInfo);
+        }
+        catch (Exception exception) when (exception is not WorkerProcessLaunchException)
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.StartFailed,
+                "Worker process failed to start.",
+                exception);
+        }
+
+        try
+        {
+            using CancellationTokenSource startupTimeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            startupTimeout.CancelAfter(TimeSpan.FromSeconds(_workerOptions.StartupTimeoutSeconds));
+
+            await _startupProbe
+                .WaitUntilReadyAsync(process, request, startupTimeout.Token)
+                .ConfigureAwait(false);
+
+            _metrics.WorkerStarted(_timeProvider.GetUtcNow() - startedAt);
+
+            return new WorkerProcessHandle(process, commandLine, startedAt);
+        }
+        catch (OperationCanceledException exception) when (!cancellationToken.IsCancellationRequested)
+        {
+            KillAndDispose(process, "StartupTimeout");
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.StartupTimeout,
+                "Worker process did not complete startup before the configured timeout.",
+                exception);
+        }
+        catch (OperationCanceledException)
+        {
+            KillAndDispose(process, "LaunchCanceled");
+            throw;
+        }
+        catch (Exception exception) when (exception is not WorkerProcessLaunchException)
+        {
+            KillAndDispose(process, "StartupFailed");
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.StartupFailed,
+                "Worker process failed during startup.",
+                exception);
+        }
+        catch (WorkerProcessLaunchException)
+        {
+            KillAndDispose(process, "StartupFailed");
+            throw;
+        }
+    }
+
+    private ProcessStartInfo CreateStartInfo(
+        WorkerProcessLaunchRequest request,
+        out WorkerProcessCommandLine commandLine)
+    {
+        string executablePath = ResolveExecutablePath();
+        string workingDirectory = ResolveWorkingDirectory(executablePath);
+        string[] arguments =
+        [
+            "--session-id",
+            request.SessionId,
+            "--pipe-name",
+            request.PipeName,
+            "--protocol-version",
+            request.ProtocolVersion.ToString(System.Globalization.CultureInfo.InvariantCulture),
+        ];
+
+        ProcessStartInfo startInfo = new()
+        {
+            FileName = executablePath,
+            WorkingDirectory = workingDirectory,
+            UseShellExecute = false,
+            CreateNoWindow = true,
+            ErrorDialog = false,
+        };
+
+        foreach (string argument in arguments)
+        {
+            startInfo.ArgumentList.Add(argument);
+        }
+
+        startInfo.Environment[WorkerNonceEnvironmentVariableName] = request.Nonce;
+
+        commandLine = new WorkerProcessCommandLine(executablePath, arguments);
+
+        return startInfo;
+    }
+
+    private string ResolveExecutablePath()
+    {
+        string executablePath;
+        try
+        {
+            executablePath = Path.GetFullPath(_workerOptions.ExecutablePath);
+        }
+        catch (Exception exception) when (exception is ArgumentException or NotSupportedException or PathTooLongException)
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidExecutable,
+                "Worker executable path is not a valid filesystem path.",
+                exception);
+        }
+
+        if (!string.Equals(Path.GetExtension(executablePath), ".exe", StringComparison.OrdinalIgnoreCase))
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidExecutable,
+                "Worker executable path must point to a .exe file.");
+        }
+
+        if (!File.Exists(executablePath))
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.ExecutableNotFound,
+                "Worker executable does not exist.");
+        }
+
+        WorkerExecutableValidator.Validate(executablePath, _workerOptions.RequiredArchitecture);
+
+        return executablePath;
+    }
+
+    private string ResolveWorkingDirectory(string executablePath)
+    {
+        if (string.IsNullOrWhiteSpace(_workerOptions.WorkingDirectory))
+        {
+            return Path.GetDirectoryName(executablePath) ?? Environment.CurrentDirectory;
+        }
+
+        string workingDirectory;
+        try
+        {
+            workingDirectory = Path.GetFullPath(_workerOptions.WorkingDirectory);
+        }
+        catch (Exception exception) when (exception is ArgumentException or NotSupportedException or PathTooLongException)
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidWorkingDirectory,
+                "Worker working directory is not a valid filesystem path.",
+                exception);
+        }
+
+        if (!Directory.Exists(workingDirectory))
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidWorkingDirectory,
+                "Worker working directory does not exist.");
+        }
+
+        return workingDirectory;
+    }
+
+    private void KillAndDispose(IWorkerProcess process, string reason)
+    {
+        try
+        {
+            if (!process.HasExited)
+            {
+                process.Kill(entireProcessTree: true);
+                _metrics.WorkerKilled(reason);
+            }
+        }
+        finally
+        {
+            process.Dispose();
+        }
+    }
+
+    private static void ValidateRequest(WorkerProcessLaunchRequest request)
+    {
+        if (string.IsNullOrWhiteSpace(request.SessionId))
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidRequest,
+                "Worker launch requires a session id.");
+        }
+
+        if (string.IsNullOrWhiteSpace(request.PipeName))
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidRequest,
+                "Worker launch requires a pipe name.");
+        }
+
+        if (request.ProtocolVersion == 0)
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidRequest,
+                "Worker launch requires a non-zero protocol version.");
+        }
+
+        if (string.IsNullOrWhiteSpace(request.Nonce))
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.InvalidRequest,
+                "Worker launch requires a nonce.");
+        }
+    }
+}

src/MxGateway.Server/Workers/WorkerProcessStartedProbe.cs

@@ -0,0 +1,19 @@
+namespace MxGateway.Server.Workers;
+
+public sealed class WorkerProcessStartedProbe : IWorkerStartupProbe
+{
+    public Task WaitUntilReadyAsync(
+        IWorkerProcess process,
+        WorkerProcessLaunchRequest request,
+        CancellationToken cancellationToken)
+    {
+        if (process.HasExited)
+        {
+            throw new WorkerProcessLaunchException(
+                WorkerProcessLaunchErrorCode.StartupFailed,
+                $"Worker process exited before startup completed with exit code {process.ExitCode}.");
+        }
+
+        return Task.CompletedTask;
+    }
+}

src/MxGateway.Server/Workers/WorkerServiceCollectionExtensions.cs

@@ -0,0 +1,13 @@
+namespace MxGateway.Server.Workers;
+
+public static class WorkerServiceCollectionExtensions
+{
+    public static IServiceCollection AddWorkerProcessLauncher(this IServiceCollection services)
+    {
+        services.AddSingleton<IWorkerProcessFactory, SystemWorkerProcessFactory>();
+        services.AddSingleton<IWorkerStartupProbe, WorkerProcessStartedProbe>();
+        services.AddSingleton<IWorkerProcessLauncher, WorkerProcessLauncher>();
+
+        return services;
+    }
+}

src/MxGateway.Tests/Diagnostics/GatewayLogRedactorTests.cs

@@ -13,6 +13,15 @@ public sealed class GatewayLogRedactorTests
         Assert.DoesNotContain("super-secret", redacted);
     }
 
+    [Fact]
+    public void RedactApiKey_RemovesSecretContainingUnderscores()
+    {
+        string? redacted = GatewayLogRedactor.RedactApiKey("Bearer mxgw_operator01_super_secret_value");
+
+        Assert.Equal("Bearer mxgw_operator01_[redacted]", redacted);
+        Assert.DoesNotContain("super_secret_value", redacted);
+    }
+
     [Theory]
     [InlineData("AuthenticateUser")]
     [InlineData("WriteSecured")]

src/MxGateway.Tests/Gateway/Workers/WorkerProcessLauncherTests.cs

@@ -0,0 +1,307 @@
+using System.Diagnostics;
+using Microsoft.Extensions.Options;
+using MxGateway.Contracts;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Metrics;
+using MxGateway.Server.Workers;
+
+namespace MxGateway.Tests.Gateway.Workers;
+
+public sealed class WorkerProcessLauncherTests
+{
+    private const string SessionId = "session-1";
+    private const string PipeName = "mxaccess-gateway-123-session-1";
+    private const string Nonce = "super-secret-nonce";
+
+    [Fact]
+    public async Task LaunchAsync_WithValidWorker_StartsProcessWithBootstrapArgumentsAndNonceEnvironment()
+    {
+        using TestDirectory directory = TestDirectory.Create();
+        string executablePath = directory.CreateWorkerExecutable(machine: 0x014c);
+        FakeWorkerProcess process = new(processId: 1234);
+        FakePipeReservation pipeReservation = new();
+        FakeWorkerProcessFactory processFactory = new(process);
+        GatewayMetrics metrics = new();
+        WorkerProcessLauncher launcher = CreateLauncher(executablePath, processFactory, new SucceedingStartupProbe(), metrics);
+
+        using WorkerProcessHandle handle = await launcher.LaunchAsync(CreateRequest(pipeReservation));
+
+        Assert.Equal(1234, handle.ProcessId);
+        Assert.Same(process, handle.Process);
+        Assert.NotNull(processFactory.LastStartInfo);
+        Assert.Equal(Path.GetFullPath(executablePath), processFactory.LastStartInfo.FileName);
+        Assert.False(processFactory.LastStartInfo.UseShellExecute);
+        Assert.True(processFactory.LastStartInfo.CreateNoWindow);
+        Assert.Equal(
+            ["--session-id", SessionId, "--pipe-name", PipeName, "--protocol-version", "1"],
+            processFactory.LastStartInfo.ArgumentList);
+        Assert.Equal(Nonce, processFactory.LastStartInfo.Environment[WorkerProcessLauncher.WorkerNonceEnvironmentVariableName]);
+        Assert.DoesNotContain(Nonce, handle.CommandLine.ToString(), StringComparison.Ordinal);
+        Assert.DoesNotContain(Nonce, string.Join(" ", handle.CommandLine.Arguments), StringComparison.Ordinal);
+        Assert.False(pipeReservation.DisposeCalled);
+        Assert.Equal(1, metrics.GetSnapshot().WorkersRunning);
+    }
+
+    [Fact]
+    public async Task LaunchAsync_WhenStartupProbeFails_KillsAndDisposesWorker()
+    {
+        using TestDirectory directory = TestDirectory.Create();
+        string executablePath = directory.CreateWorkerExecutable(machine: 0x014c);
+        FakeWorkerProcess process = new(processId: 1234);
+        FakePipeReservation pipeReservation = new();
+        GatewayMetrics metrics = new();
+        WorkerProcessLauncher launcher = CreateLauncher(
+            executablePath,
+            new FakeWorkerProcessFactory(process),
+            new FailingStartupProbe(),
+            metrics);
+
+        WorkerProcessLaunchException exception =
+            await Assert.ThrowsAsync<WorkerProcessLaunchException>(
+                async () => await launcher.LaunchAsync(CreateRequest(pipeReservation)));
+
+        Assert.Equal(WorkerProcessLaunchErrorCode.StartupFailed, exception.ErrorCode);
+        Assert.True(process.KillCalled);
+        Assert.True(process.DisposeCalled);
+        Assert.True(pipeReservation.DisposeCalled);
+        Assert.Equal(1, metrics.GetSnapshot().WorkerKills);
+    }
+
+    [Fact]
+    public async Task LaunchAsync_WhenStartupTimesOut_KillsAndDisposesWorker()
+    {
+        using TestDirectory directory = TestDirectory.Create();
+        string executablePath = directory.CreateWorkerExecutable(machine: 0x014c);
+        FakeWorkerProcess process = new(processId: 1234);
+        GatewayMetrics metrics = new();
+        WorkerProcessLauncher launcher = CreateLauncher(
+            executablePath,
+            new FakeWorkerProcessFactory(process),
+            new WaitingStartupProbe(),
+            metrics,
+            startupTimeoutSeconds: 1);
+
+        WorkerProcessLaunchException exception =
+            await Assert.ThrowsAsync<WorkerProcessLaunchException>(
+                async () => await launcher.LaunchAsync(CreateRequest()));
+
+        Assert.Equal(WorkerProcessLaunchErrorCode.StartupTimeout, exception.ErrorCode);
+        Assert.True(process.KillCalled);
+        Assert.True(process.DisposeCalled);
+        Assert.Equal(1, metrics.GetSnapshot().WorkerKills);
+    }
+
+    [Fact]
+    public async Task LaunchAsync_WhenExecutableDoesNotExist_FailsBeforeStartingProcess()
+    {
+        using TestDirectory directory = TestDirectory.Create();
+        string executablePath = Path.Combine(directory.Path, "missing-worker.exe");
+        FakeWorkerProcessFactory processFactory = new(new FakeWorkerProcess(processId: 1234));
+        WorkerProcessLauncher launcher = CreateLauncher(executablePath, processFactory, new SucceedingStartupProbe());
+
+        WorkerProcessLaunchException exception =
+            await Assert.ThrowsAsync<WorkerProcessLaunchException>(
+                async () => await launcher.LaunchAsync(CreateRequest()));
+
+        Assert.Equal(WorkerProcessLaunchErrorCode.ExecutableNotFound, exception.ErrorCode);
+        Assert.Null(processFactory.LastStartInfo);
+    }
+
+    [Fact]
+    public async Task LaunchAsync_WhenExecutableArchitectureDoesNotMatch_FailsBeforeStartingProcess()
+    {
+        using TestDirectory directory = TestDirectory.Create();
+        string executablePath = directory.CreateWorkerExecutable(machine: 0x8664);
+        FakeWorkerProcessFactory processFactory = new(new FakeWorkerProcess(processId: 1234));
+        WorkerProcessLauncher launcher = CreateLauncher(executablePath, processFactory, new SucceedingStartupProbe());
+
+        WorkerProcessLaunchException exception =
+            await Assert.ThrowsAsync<WorkerProcessLaunchException>(
+                async () => await launcher.LaunchAsync(CreateRequest()));
+
+        Assert.Equal(WorkerProcessLaunchErrorCode.InvalidExecutable, exception.ErrorCode);
+        Assert.Null(processFactory.LastStartInfo);
+    }
+
+    [Fact]
+    public async Task LaunchAsync_WhenWorkerAlreadyExited_FailsAndDisposesWorkerWithoutKill()
+    {
+        using TestDirectory directory = TestDirectory.Create();
+        string executablePath = directory.CreateWorkerExecutable(machine: 0x014c);
+        FakeWorkerProcess process = new(processId: 1234)
+        {
+            HasExited = true,
+            ExitCode = 42,
+        };
+        WorkerProcessLauncher launcher = CreateLauncher(
+            executablePath,
+            new FakeWorkerProcessFactory(process),
+            new WorkerProcessStartedProbe());
+
+        WorkerProcessLaunchException exception =
+            await Assert.ThrowsAsync<WorkerProcessLaunchException>(
+                async () => await launcher.LaunchAsync(CreateRequest()));
+
+        Assert.Equal(WorkerProcessLaunchErrorCode.StartupFailed, exception.ErrorCode);
+        Assert.False(process.KillCalled);
+        Assert.True(process.DisposeCalled);
+    }
+
+    private static WorkerProcessLauncher CreateLauncher(
+        string executablePath,
+        IWorkerProcessFactory processFactory,
+        IWorkerStartupProbe startupProbe,
+        GatewayMetrics? metrics = null,
+        int startupTimeoutSeconds = 30)
+    {
+        GatewayOptions options = new()
+        {
+            Worker = new WorkerOptions
+            {
+                ExecutablePath = executablePath,
+                RequiredArchitecture = WorkerArchitecture.X86,
+                StartupTimeoutSeconds = startupTimeoutSeconds,
+            },
+        };
+
+        return new WorkerProcessLauncher(
+            Options.Create(options),
+            processFactory,
+            startupProbe,
+            metrics ?? new GatewayMetrics());
+    }
+
+    private static WorkerProcessLaunchRequest CreateRequest(IDisposable? pipeReservation = null)
+    {
+        return new WorkerProcessLaunchRequest(
+            SessionId,
+            PipeName,
+            GatewayContractInfo.WorkerProtocolVersion,
+            Nonce,
+            pipeReservation);
+    }
+
+    private sealed class FakeWorkerProcessFactory(IWorkerProcess process) : IWorkerProcessFactory
+    {
+        public ProcessStartInfo? LastStartInfo { get; private set; }
+
+        public IWorkerProcess Start(ProcessStartInfo startInfo)
+        {
+            LastStartInfo = startInfo;
+            return process;
+        }
+    }
+
+    private sealed class FakeWorkerProcess(int processId) : IWorkerProcess
+    {
+        public int Id { get; } = processId;
+
+        public bool HasExited { get; set; }
+
+        public int? ExitCode { get; set; }
+
+        public bool DisposeCalled { get; private set; }
+
+        public bool KillCalled { get; private set; }
+
+        public ValueTask WaitForExitAsync(CancellationToken cancellationToken)
+        {
+            return ValueTask.CompletedTask;
+        }
+
+        public void Kill(bool entireProcessTree)
+        {
+            Assert.True(entireProcessTree);
+            KillCalled = true;
+            HasExited = true;
+        }
+
+        public void Dispose()
+        {
+            DisposeCalled = true;
+        }
+    }
+
+    private sealed class SucceedingStartupProbe : IWorkerStartupProbe
+    {
+        public Task WaitUntilReadyAsync(
+            IWorkerProcess process,
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken)
+        {
+            return Task.CompletedTask;
+        }
+    }
+
+    private sealed class FailingStartupProbe : IWorkerStartupProbe
+    {
+        public Task WaitUntilReadyAsync(
+            IWorkerProcess process,
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken)
+        {
+            throw new InvalidOperationException("Fake worker startup failed.");
+        }
+    }
+
+    private sealed class WaitingStartupProbe : IWorkerStartupProbe
+    {
+        public async Task WaitUntilReadyAsync(
+            IWorkerProcess process,
+            WorkerProcessLaunchRequest request,
+            CancellationToken cancellationToken)
+        {
+            await Task.Delay(Timeout.InfiniteTimeSpan, cancellationToken);
+        }
+    }
+
+    private sealed class FakePipeReservation : IDisposable
+    {
+        public bool DisposeCalled { get; private set; }
+
+        public void Dispose()
+        {
+            DisposeCalled = true;
+        }
+    }
+
+    private sealed class TestDirectory : IDisposable
+    {
+        private TestDirectory(string path)
+        {
+            Path = path;
+        }
+
+        public string Path { get; }
+
+        public static TestDirectory Create()
+        {
+            string path = System.IO.Path.Combine(System.IO.Path.GetTempPath(), $"mxgateway-tests-{Guid.NewGuid():N}");
+            Directory.CreateDirectory(path);
+
+            return new TestDirectory(path);
+        }
+
+        public string CreateWorkerExecutable(ushort machine)
+        {
+            string path = System.IO.Path.Combine(Path, "MxGateway.Worker.exe");
+            byte[] bytes = new byte[0x100];
+            bytes[0] = (byte)'M';
+            bytes[1] = (byte)'Z';
+            BitConverter.GetBytes(0x80).CopyTo(bytes, 0x3c);
+            bytes[0x80] = (byte)'P';
+            bytes[0x81] = (byte)'E';
+            bytes[0x82] = 0;
+            bytes[0x83] = 0;
+            BitConverter.GetBytes(machine).CopyTo(bytes, 0x84);
+            File.WriteAllBytes(path, bytes);
+
+            return path;
+        }
+
+        public void Dispose()
+        {
+            Directory.Delete(Path, recursive: true);
+        }
+    }
+}

src/MxGateway.Tests/Security/Authentication/ApiKeyParserTests.cs

@@ -0,0 +1,38 @@
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Tests.Security.Authentication;
+
+public sealed class ApiKeyParserTests
+{
+    [Fact]
+    public void TryParseAuthorizationHeader_ValidBearerToken_ReturnsKeyIdAndSecret()
+    {
+        ApiKeyParser parser = new();
+
+        bool parsed = parser.TryParseAuthorizationHeader(
+            "Bearer mxgw_operator01_secret_value",
+            out ParsedApiKey? apiKey);
+
+        Assert.True(parsed);
+        Assert.NotNull(apiKey);
+        Assert.Equal("operator01", apiKey.KeyId);
+        Assert.Equal("secret_value", apiKey.Secret);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("mxgw_operator01_secret")]
+    [InlineData("Bearer not-a-gateway-key")]
+    [InlineData("Bearer mxgw__secret")]
+    [InlineData("Bearer mxgw_operator01_")]
+    public void TryParseAuthorizationHeader_MalformedToken_ReturnsFalse(string? authorizationHeader)
+    {
+        ApiKeyParser parser = new();
+
+        bool parsed = parser.TryParseAuthorizationHeader(authorizationHeader, out ParsedApiKey? apiKey);
+
+        Assert.False(parsed);
+        Assert.Null(apiKey);
+    }
+}

src/MxGateway.Tests/Security/Authentication/ApiKeySecretHasherTests.cs

@@ -0,0 +1,62 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Tests.Security.Authentication;
+
+public sealed class ApiKeySecretHasherTests
+{
+    [Fact]
+    public void HashSecret_SamePepperAndSecret_ReturnsSameHash()
+    {
+        ApiKeySecretHasher hasher = CreateHasher("pepper-one");
+
+        byte[] firstHash = hasher.HashSecret("raw-secret");
+        byte[] secondHash = hasher.HashSecret("raw-secret");
+
+        Assert.Equal(firstHash, secondHash);
+        Assert.NotEqual("raw-secret"u8.ToArray(), firstHash);
+    }
+
+    [Fact]
+    public void HashSecret_DifferentPepper_ReturnsDifferentHash()
+    {
+        byte[] firstHash = CreateHasher("pepper-one").HashSecret("raw-secret");
+        byte[] secondHash = CreateHasher("pepper-two").HashSecret("raw-secret");
+
+        Assert.NotEqual(firstHash, secondHash);
+    }
+
+    [Fact]
+    public void HashSecret_MissingPepper_Throws()
+    {
+        ApiKeySecretHasher hasher = CreateHasher(pepper: null);
+
+        Assert.Throws<ApiKeyPepperUnavailableException>(() => hasher.HashSecret("raw-secret"));
+    }
+
+    private static ApiKeySecretHasher CreateHasher(string? pepper)
+    {
+        Dictionary<string, string?> values = [];
+
+        if (pepper is not null)
+        {
+            values["TestPepper"] = pepper;
+        }
+
+        IConfigurationRoot configuration = new ConfigurationBuilder()
+            .AddInMemoryCollection(values)
+            .Build();
+
+        GatewayOptions options = new()
+        {
+            Authentication = new AuthenticationOptions
+            {
+                PepperSecretName = "TestPepper"
+            }
+        };
+
+        return new ApiKeySecretHasher(configuration, Options.Create(options));
+    }
+}

src/MxGateway.Tests/Security/Authentication/ApiKeyVerifierTests.cs

@@ -0,0 +1,193 @@
+using System.Text.Json;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Options;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Tests.Security.Authentication;
+
+public sealed class ApiKeyVerifierTests
+{
+    [Fact]
+    public async Task VerifyAsync_ValidKey_ReturnsIdentityAndScopes()
+    {
+        ApiKeySecretHasher hasher = CreateHasher("pepper");
+        FakeApiKeyStore store = new(CreateRecord(hasher, revokedUtc: null));
+        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            "Bearer mxgw_operator01_correct-secret",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        Assert.NotNull(result.Identity);
+        Assert.Equal("operator01", result.Identity.KeyId);
+        Assert.Equal("Operator Key", result.Identity.DisplayName);
+        Assert.Contains("session:open", result.Identity.Scopes);
+        Assert.Contains("events:read", result.Identity.Scopes);
+        Assert.True(store.MarkedUsed);
+    }
+
+    [Fact]
+    public async Task VerifyAsync_ValidKey_DoesNotExposeRawSecretInResult()
+    {
+        ApiKeySecretHasher hasher = CreateHasher("pepper");
+        FakeApiKeyStore store = new(CreateRecord(hasher, revokedUtc: null));
+        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            "Bearer mxgw_operator01_correct-secret",
+            CancellationToken.None);
+
+        string serialized = JsonSerializer.Serialize(result);
+
+        Assert.DoesNotContain("correct-secret", serialized, StringComparison.Ordinal);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("Bearer mxgw_operator01")]
+    [InlineData("Bearer wrong")]
+    public async Task VerifyAsync_MalformedKey_FailsUnauthenticated(string? authorizationHeader)
+    {
+        ApiKeyVerifier verifier = new(
+            new ApiKeyParser(),
+            CreateHasher("pepper"),
+            new FakeApiKeyStore(storedKey: null));
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            authorizationHeader,
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.MissingOrMalformedCredentials, result.Failure);
+    }
+
+    [Fact]
+    public async Task VerifyAsync_UnknownKey_Fails()
+    {
+        ApiKeyVerifier verifier = new(
+            new ApiKeyParser(),
+            CreateHasher("pepper"),
+            new FakeApiKeyStore(storedKey: null));
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            "Bearer mxgw_missing_secret",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.KeyNotFound, result.Failure);
+    }
+
+    [Fact]
+    public async Task VerifyAsync_WrongSecret_Fails()
+    {
+        ApiKeySecretHasher hasher = CreateHasher("pepper");
+        FakeApiKeyStore store = new(CreateRecord(hasher, revokedUtc: null));
+        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            "Bearer mxgw_operator01_wrong-secret",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.SecretMismatch, result.Failure);
+        Assert.False(store.MarkedUsed);
+    }
+
+    [Fact]
+    public async Task VerifyAsync_RevokedKey_Fails()
+    {
+        ApiKeySecretHasher hasher = CreateHasher("pepper");
+        FakeApiKeyStore store = new(CreateRecord(hasher, DateTimeOffset.UtcNow));
+        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            "Bearer mxgw_operator01_correct-secret",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.KeyRevoked, result.Failure);
+        Assert.False(store.MarkedUsed);
+    }
+
+    [Fact]
+    public async Task VerifyAsync_MissingPepper_Fails()
+    {
+        FakeApiKeyStore store = new(CreateRecord(CreateHasher("pepper"), revokedUtc: null));
+        ApiKeyVerifier verifier = new(new ApiKeyParser(), CreateHasher(pepper: null), store);
+
+        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+            "Bearer mxgw_operator01_correct-secret",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.PepperUnavailable, result.Failure);
+    }
+
+    private static ApiKeyRecord CreateRecord(ApiKeySecretHasher hasher, DateTimeOffset? revokedUtc)
+    {
+        return new ApiKeyRecord(
+            KeyId: "operator01",
+            KeyPrefix: "mxgw_operator01",
+            SecretHash: hasher.HashSecret("correct-secret"),
+            DisplayName: "Operator Key",
+            Scopes: new HashSet<string>(StringComparer.Ordinal)
+            {
+                "session:open",
+                "events:read"
+            },
+            CreatedUtc: DateTimeOffset.UtcNow,
+            LastUsedUtc: null,
+            RevokedUtc: revokedUtc);
+    }
+
+    private static ApiKeySecretHasher CreateHasher(string? pepper)
+    {
+        Dictionary<string, string?> values = [];
+
+        if (pepper is not null)
+        {
+            values["TestPepper"] = pepper;
+        }
+
+        IConfigurationRoot configuration = new ConfigurationBuilder()
+            .AddInMemoryCollection(values)
+            .Build();
+
+        GatewayOptions options = new()
+        {
+            Authentication = new AuthenticationOptions
+            {
+                PepperSecretName = "TestPepper"
+            }
+        };
+
+        return new ApiKeySecretHasher(configuration, Options.Create(options));
+    }
+
+    private sealed class FakeApiKeyStore(ApiKeyRecord? storedKey) : IApiKeyStore
+    {
+        public bool MarkedUsed { get; private set; }
+
+        public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken cancellationToken)
+        {
+            return Task.FromResult(storedKey?.KeyId == keyId ? storedKey : null);
+        }
+
+        public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken cancellationToken)
+        {
+            return Task.FromResult(
+                storedKey?.KeyId == keyId && storedKey.RevokedUtc is null
+                    ? storedKey
+                    : null);
+        }
+
+        public Task MarkKeyUsedAsync(string keyId, DateTimeOffset usedUtc, CancellationToken cancellationToken)
+        {
+            MarkedUsed = storedKey?.KeyId == keyId;
+
+            return Task.CompletedTask;
+        }
+    }
+}