Issue #7: implement local api key admin cli

Verified with dotnet build src\\MxGateway.sln, dotnet test src\\MxGateway.Worker.Tests\\MxGateway.Worker.Tests.csproj -p:Platform=x86, and dotnet test src\\MxGateway.sln --no-build.

docs/gateway-process-design.md

@@ -631,6 +631,23 @@ 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.

docs/mxaccess-worker-instance-design.md

@@ -114,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

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/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/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/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/AuthStoreServiceCollectionExtensions.cs

@@ -7,9 +7,11 @@ public static class AuthStoreServiceCollectionExtensions
         services.AddSingleton<IApiKeyParser, ApiKeyParser>();
         services.AddSingleton<IApiKeySecretHasher, ApiKeySecretHasher>();
         services.AddSingleton<IApiKeyVerifier, ApiKeyVerifier>();
+        services.AddSingleton<ApiKeyAdminCliRunner>();
         services.AddSingleton<AuthSqliteConnectionFactory>();
         services.AddSingleton<IAuthStoreMigrator, SqliteAuthStoreMigrator>();
         services.AddSingleton<IApiKeyStore, SqliteApiKeyStore>();
+        services.AddSingleton<IApiKeyAdminStore, SqliteApiKeyAdminStore>();
         services.AddSingleton<IApiKeyAuditStore, SqliteApiKeyAuditStore>();
         services.AddHostedService<AuthStoreMigrationHostedService>();
 

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

@@ -0,0 +1,16 @@
+namespace MxGateway.Server.Security.Authentication;
+
+public interface IApiKeyAdminStore
+{
+    Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken);
+
+    Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken);
+
+    Task<bool> RevokeAsync(string keyId, DateTimeOffset revokedUtc, CancellationToken cancellationToken);
+
+    Task<bool> RotateAsync(
+        string keyId,
+        byte[] secretHash,
+        DateTimeOffset rotatedUtc,
+        CancellationToken cancellationToken);
+}

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

@@ -0,0 +1,116 @@
+using Microsoft.Data.Sqlite;
+
+namespace MxGateway.Server.Security.Authentication;
+
+public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyAdminStore
+{
+    public async Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken)
+    {
+        await using SqliteConnection connection = connectionFactory.CreateConnection();
+        await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            INSERT INTO api_keys (
+                key_id,
+                key_prefix,
+                secret_hash,
+                display_name,
+                scopes,
+                created_utc,
+                last_used_utc,
+                revoked_utc)
+            VALUES (
+                $key_id,
+                $key_prefix,
+                $secret_hash,
+                $display_name,
+                $scopes,
+                $created_utc,
+                NULL,
+                NULL);
+            """;
+        AddCreateParameters(command, request);
+
+        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+    {
+        await using SqliteConnection connection = connectionFactory.CreateConnection();
+        await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            SELECT key_id, key_prefix, secret_hash, display_name, scopes, created_utc, last_used_utc, revoked_utc
+            FROM api_keys
+            ORDER BY key_id;
+            """;
+
+        List<ApiKeyRecord> records = [];
+
+        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken)
+            .ConfigureAwait(false);
+
+        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
+        {
+            records.Add(ApiKeyRecordReader.Read(reader));
+        }
+
+        return records;
+    }
+
+    public async Task<bool> RevokeAsync(string keyId, DateTimeOffset revokedUtc, CancellationToken cancellationToken)
+    {
+        await using SqliteConnection connection = connectionFactory.CreateConnection();
+        await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            UPDATE api_keys
+            SET revoked_utc = $revoked_utc
+            WHERE key_id = $key_id AND revoked_utc IS NULL;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.AddWithValue("$revoked_utc", revokedUtc.ToString("O"));
+
+        int rows = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
+    public async Task<bool> RotateAsync(
+        string keyId,
+        byte[] secretHash,
+        DateTimeOffset rotatedUtc,
+        CancellationToken cancellationToken)
+    {
+        await using SqliteConnection connection = connectionFactory.CreateConnection();
+        await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = """
+            UPDATE api_keys
+            SET secret_hash = $secret_hash,
+                last_used_utc = NULL,
+                revoked_utc = NULL
+            WHERE key_id = $key_id;
+            """;
+        command.Parameters.AddWithValue("$key_id", keyId);
+        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = secretHash;
+
+        int rows = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+
+        return rows > 0;
+    }
+
+    private static void AddCreateParameters(SqliteCommand command, ApiKeyCreateRequest request)
+    {
+        command.Parameters.AddWithValue("$key_id", request.KeyId);
+        command.Parameters.AddWithValue("$key_prefix", request.KeyPrefix);
+        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = request.SecretHash;
+        command.Parameters.AddWithValue("$display_name", request.DisplayName);
+        command.Parameters.AddWithValue("$scopes", ApiKeyScopeSerializer.Serialize(request.Scopes));
+        command.Parameters.AddWithValue("$created_utc", request.CreatedUtc.ToString("O"));
+    }
+}

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

@@ -61,26 +61,6 @@ public sealed class SqliteApiKeyStore(AuthSqliteConnectionFactory connectionFact
             return null;
         }
 
-        return ReadApiKeyRecord(reader);
+        return ApiKeyRecordReader.Read(reader);
-    }
-
-    private static ApiKeyRecord ReadApiKeyRecord(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.Tests/Security/Authentication/ApiKeyAdminCliRunnerTests.cs

@@ -0,0 +1,242 @@
+using System.Text.Json;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using MxGateway.Server.Configuration;
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Tests.Security.Authentication;
+
+public sealed class ApiKeyAdminCliRunnerTests
+{
+    [Fact]
+    public async Task CreateKeyAsync_CreatesAuthenticatingKeyAndAudits()
+    {
+        await using ServiceProvider services = BuildServices(CreateTempDatabasePath());
+        ApiKeyAdminCliRunner runner = services.GetRequiredService<ApiKeyAdminCliRunner>();
+        StringWriter output = new();
+
+        await runner.RunAsync(
+            new ApiKeyAdminCommand(
+                Kind: ApiKeyAdminCommandKind.CreateKey,
+                Json: true,
+                SqlitePath: null,
+                Pepper: null,
+                KeyId: "operator01",
+                DisplayName: "Operator",
+                Scopes: new HashSet<string>(StringComparer.Ordinal) { "session:open", "events:read" }),
+            output,
+            CancellationToken.None);
+
+        string apiKey = ReadApiKey(output.ToString());
+
+        IApiKeyVerifier verifier = services.GetRequiredService<IApiKeyVerifier>();
+        ApiKeyVerificationResult verification = await verifier.VerifyAsync($"Bearer {apiKey}", CancellationToken.None);
+
+        Assert.True(verification.Succeeded);
+        Assert.NotNull(verification.Identity);
+        Assert.Equal("operator01", verification.Identity.KeyId);
+        Assert.Contains("session:open", verification.Identity.Scopes);
+
+        IReadOnlyList<ApiKeyAuditRecord> auditRecords = await services
+            .GetRequiredService<IApiKeyAuditStore>()
+            .ListRecentAsync(10, CancellationToken.None);
+
+        Assert.Contains(auditRecords, record => record.EventType == "create-key" && record.KeyId == "operator01");
+    }
+
+    [Fact]
+    public async Task ListKeysAsync_DoesNotPrintRawSecret()
+    {
+        await using ServiceProvider services = BuildServices(CreateTempDatabasePath());
+        ApiKeyAdminCliRunner runner = services.GetRequiredService<ApiKeyAdminCliRunner>();
+        string apiKey = await CreateKeyAsync(runner, "operator01");
+        StringWriter listOutput = new();
+
+        await runner.RunAsync(
+            new ApiKeyAdminCommand(
+                Kind: ApiKeyAdminCommandKind.ListKeys,
+                Json: true,
+                SqlitePath: null,
+                Pepper: null,
+                KeyId: null,
+                DisplayName: null,
+                Scopes: new HashSet<string>(StringComparer.Ordinal)),
+            listOutput,
+            CancellationToken.None);
+
+        string listJson = listOutput.ToString();
+
+        Assert.Contains("operator01", listJson, StringComparison.Ordinal);
+        Assert.DoesNotContain(apiKey, listJson, StringComparison.Ordinal);
+        Assert.DoesNotContain(ApiKeySecret(apiKey), listJson, StringComparison.Ordinal);
+        Assert.DoesNotContain("secret_hash", listJson, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task RevokeKeyAsync_RevokedKeyFailsVerificationAndAudits()
+    {
+        await using ServiceProvider services = BuildServices(CreateTempDatabasePath());
+        ApiKeyAdminCliRunner runner = services.GetRequiredService<ApiKeyAdminCliRunner>();
+        string apiKey = await CreateKeyAsync(runner, "operator01");
+
+        await runner.RunAsync(
+            new ApiKeyAdminCommand(
+                Kind: ApiKeyAdminCommandKind.RevokeKey,
+                Json: true,
+                SqlitePath: null,
+                Pepper: null,
+                KeyId: "operator01",
+                DisplayName: null,
+                Scopes: new HashSet<string>(StringComparer.Ordinal)),
+            TextWriter.Null,
+            CancellationToken.None);
+
+        ApiKeyVerificationResult verification = await services
+            .GetRequiredService<IApiKeyVerifier>()
+            .VerifyAsync($"Bearer {apiKey}", CancellationToken.None);
+
+        Assert.False(verification.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.KeyRevoked, verification.Failure);
+
+        IReadOnlyList<ApiKeyAuditRecord> auditRecords = await services
+            .GetRequiredService<IApiKeyAuditStore>()
+            .ListRecentAsync(10, CancellationToken.None);
+
+        Assert.Contains(auditRecords, record => record.EventType == "revoke-key" && record.KeyId == "operator01");
+    }
+
+    [Fact]
+    public async Task RotateKeyAsync_PrintsNewSecretOnceAndInvalidatesOldSecret()
+    {
+        await using ServiceProvider services = BuildServices(CreateTempDatabasePath());
+        ApiKeyAdminCliRunner runner = services.GetRequiredService<ApiKeyAdminCliRunner>();
+        string oldApiKey = await CreateKeyAsync(runner, "operator01");
+        StringWriter rotateOutput = new();
+
+        await runner.RunAsync(
+            new ApiKeyAdminCommand(
+                Kind: ApiKeyAdminCommandKind.RotateKey,
+                Json: true,
+                SqlitePath: null,
+                Pepper: null,
+                KeyId: "operator01",
+                DisplayName: null,
+                Scopes: new HashSet<string>(StringComparer.Ordinal)),
+            rotateOutput,
+            CancellationToken.None);
+
+        string rotateJson = rotateOutput.ToString();
+        string newApiKey = ReadApiKey(rotateJson);
+
+        Assert.NotEqual(oldApiKey, newApiKey);
+        Assert.Equal(1, CountOccurrences(rotateJson, newApiKey));
+
+        IApiKeyVerifier verifier = services.GetRequiredService<IApiKeyVerifier>();
+        ApiKeyVerificationResult oldVerification = await verifier.VerifyAsync($"Bearer {oldApiKey}", CancellationToken.None);
+        ApiKeyVerificationResult newVerification = await verifier.VerifyAsync($"Bearer {newApiKey}", CancellationToken.None);
+
+        Assert.False(oldVerification.Succeeded);
+        Assert.Equal(ApiKeyVerificationFailure.SecretMismatch, oldVerification.Failure);
+        Assert.True(newVerification.Succeeded);
+    }
+
+    [Fact]
+    public async Task CreateKeyAsync_PrintsRawSecretExactlyOnce()
+    {
+        await using ServiceProvider services = BuildServices(CreateTempDatabasePath());
+        ApiKeyAdminCliRunner runner = services.GetRequiredService<ApiKeyAdminCliRunner>();
+        StringWriter output = new();
+
+        await runner.RunAsync(
+            new ApiKeyAdminCommand(
+                Kind: ApiKeyAdminCommandKind.CreateKey,
+                Json: true,
+                SqlitePath: null,
+                Pepper: null,
+                KeyId: "operator01",
+                DisplayName: "Operator",
+                Scopes: new HashSet<string>(StringComparer.Ordinal)),
+            output,
+            CancellationToken.None);
+
+        string json = output.ToString();
+        string apiKey = ReadApiKey(json);
+
+        Assert.Equal(1, CountOccurrences(json, apiKey));
+        Assert.Equal(1, CountOccurrences(json, ApiKeySecret(apiKey)));
+    }
+
+    private static async Task<string> CreateKeyAsync(ApiKeyAdminCliRunner runner, string keyId)
+    {
+        StringWriter output = new();
+        await runner.RunAsync(
+            new ApiKeyAdminCommand(
+                Kind: ApiKeyAdminCommandKind.CreateKey,
+                Json: true,
+                SqlitePath: null,
+                Pepper: null,
+                KeyId: keyId,
+                DisplayName: "Operator",
+                Scopes: new HashSet<string>(StringComparer.Ordinal) { "session:open" }),
+            output,
+            CancellationToken.None);
+
+        return ReadApiKey(output.ToString());
+    }
+
+    private static ServiceProvider BuildServices(string databasePath)
+    {
+        IConfigurationRoot configuration = new ConfigurationBuilder()
+            .AddInMemoryCollection(
+                new Dictionary<string, string?>
+                {
+                    ["MxGateway:Authentication:SqlitePath"] = databasePath,
+                    ["MxGateway:ApiKeyPepper"] = "test-pepper"
+                })
+            .Build();
+
+        ServiceCollection services = new();
+        services.AddSingleton<IConfiguration>(configuration);
+        services.AddGatewayConfiguration();
+        services.AddSqliteAuthStore();
+
+        return services.BuildServiceProvider(validateScopes: true);
+    }
+
+    private static string CreateTempDatabasePath()
+    {
+        string directory = Path.Combine(Path.GetTempPath(), "mxgateway-auth-cli-tests", Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(directory);
+
+        return Path.Combine(directory, "gateway-auth.db");
+    }
+
+    private static string ReadApiKey(string json)
+    {
+        using JsonDocument document = JsonDocument.Parse(json);
+
+        return document.RootElement.GetProperty("ApiKey").GetString()
+            ?? throw new InvalidOperationException("API key was not present in command output.");
+    }
+
+    private static string ApiKeySecret(string apiKey)
+    {
+        string[] parts = apiKey.Split('_', 3);
+
+        return parts[2];
+    }
+
+    private static int CountOccurrences(string value, string pattern)
+    {
+        int count = 0;
+        int index = 0;
+
+        while ((index = value.IndexOf(pattern, index, StringComparison.Ordinal)) >= 0)
+        {
+            count++;
+            index += pattern.Length;
+        }
+
+        return count;
+    }
+}

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

@@ -0,0 +1,70 @@
+using MxGateway.Server.Security.Authentication;
+
+namespace MxGateway.Tests.Security.Authentication;
+
+public sealed class ApiKeyAdminCommandLineParserTests
+{
+    [Fact]
+    public void Parse_NonApiKeyCommand_ReturnsNotApiKeyCommand()
+    {
+        ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse(["--urls=http://localhost:5000"]);
+
+        Assert.False(result.IsApiKeyCommand);
+        Assert.Null(result.Command);
+    }
+
+    [Fact]
+    public void Parse_CreateKeyCommand_ReturnsOptions()
+    {
+        ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse(
+            [
+                "apikey",
+                "create-key",
+                "--key-id",
+                "operator01",
+                "--display-name",
+                "Operator",
+                "--scopes",
+                "session:open,events:read",
+                "--sqlite-path",
+                "auth.db",
+                "--pepper",
+                "pepper",
+                "--json"
+            ]);
+
+        Assert.True(result.IsApiKeyCommand);
+        Assert.Null(result.Error);
+        Assert.NotNull(result.Command);
+        Assert.Equal(ApiKeyAdminCommandKind.CreateKey, result.Command.Kind);
+        Assert.True(result.Command.Json);
+        Assert.Equal("operator01", result.Command.KeyId);
+        Assert.Equal("Operator", result.Command.DisplayName);
+        Assert.Equal("auth.db", result.Command.SqlitePath);
+        Assert.Equal("pepper", result.Command.Pepper);
+        Assert.Contains("session:open", result.Command.Scopes);
+        Assert.Contains("events:read", result.Command.Scopes);
+    }
+
+    [Fact]
+    public void Parse_CreateKeyWithoutDisplayName_ReturnsError()
+    {
+        ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse(
+            ["apikey", "create-key", "--key-id", "operator01"]);
+
+        Assert.True(result.IsApiKeyCommand);
+        Assert.Null(result.Command);
+        Assert.Contains("--display-name", result.Error, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Parse_KeyIdWithUnderscore_ReturnsError()
+    {
+        ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse(
+            ["apikey", "revoke-key", "--key-id", "operator_01"]);
+
+        Assert.True(result.IsApiKeyCommand);
+        Assert.Null(result.Command);
+        Assert.Contains("letters, numbers, periods, and hyphens", result.Error, StringComparison.Ordinal);
+    }
+}

src/MxGateway.Worker.Tests/Bootstrap/MemoryWorkerEnvironment.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Collections.Generic;
+using MxGateway.Worker.Bootstrap;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+internal sealed class MemoryWorkerEnvironment : IWorkerEnvironment
+{
+    private readonly Dictionary<string, string> _values = new();
+    private readonly Exception? _exception;
+
+    public MemoryWorkerEnvironment()
+    {
+    }
+
+    public MemoryWorkerEnvironment(Exception exception)
+    {
+        _exception = exception;
+    }
+
+    public void Set(string name, string value)
+    {
+        _values[name] = value;
+    }
+
+    public string? GetEnvironmentVariable(string name)
+    {
+        if (_exception is not null)
+        {
+            throw _exception;
+        }
+
+        return _values.TryGetValue(name, out string value)
+            ? value
+            : null;
+    }
+}

src/MxGateway.Worker.Tests/Bootstrap/MemoryWorkerLogEntry.cs

@@ -0,0 +1,22 @@
+using System.Collections.Generic;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+internal sealed class MemoryWorkerLogEntry
+{
+    public MemoryWorkerLogEntry(
+        string level,
+        string eventName,
+        IReadOnlyDictionary<string, object?> fields)
+    {
+        Level = level;
+        EventName = eventName;
+        Fields = fields;
+    }
+
+    public string Level { get; }
+
+    public string EventName { get; }
+
+    public IReadOnlyDictionary<string, object?> Fields { get; }
+}

src/MxGateway.Worker.Tests/Bootstrap/MemoryWorkerLogger.cs

@@ -0,0 +1,19 @@
+using System.Collections.Generic;
+using MxGateway.Worker.Bootstrap;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+internal sealed class MemoryWorkerLogger : IWorkerLogger
+{
+    public List<MemoryWorkerLogEntry> Entries { get; } = new();
+
+    public void Information(string eventName, IReadOnlyDictionary<string, object?> fields)
+    {
+        Entries.Add(new MemoryWorkerLogEntry("Information", eventName, WorkerLogRedactor.RedactFields(fields)));
+    }
+
+    public void Error(string eventName, IReadOnlyDictionary<string, object?> fields)
+    {
+        Entries.Add(new MemoryWorkerLogEntry("Error", eventName, WorkerLogRedactor.RedactFields(fields)));
+    }
+}

src/MxGateway.Worker.Tests/Bootstrap/WorkerApplicationTests.cs

@@ -0,0 +1,113 @@
+using System;
+using MxGateway.Contracts;
+using MxGateway.Worker.Bootstrap;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+public sealed class WorkerApplicationTests
+{
+    [Fact]
+    public void Run_WithValidBootstrapArguments_ReturnsSuccessAndLogsRedactedNonce()
+    {
+        MemoryWorkerEnvironment environment = CreateEnvironment("nonce-secret");
+        MemoryWorkerLogger logger = new();
+
+        int exitCode = MxGateway.Worker.WorkerApplication.Run(
+            ValidArgs(),
+            environment,
+            logger);
+
+        Assert.Equal((int)WorkerExitCode.Success, exitCode);
+        MemoryWorkerLogEntry entry = Assert.Single(logger.Entries);
+        Assert.Equal("Information", entry.Level);
+        Assert.Equal("WorkerBootstrapSucceeded", entry.EventName);
+        Assert.Equal("session-1", entry.Fields["session_id"]);
+        Assert.Equal("mxaccess-gateway-123-session-1", entry.Fields["pipe_name"]);
+        Assert.Equal(GatewayContractInfo.WorkerProtocolVersion, entry.Fields["protocol_version"]);
+        Assert.Equal("[redacted]", entry.Fields["nonce"]);
+    }
+
+    [Fact]
+    public void Run_WithMissingRequiredArguments_ReturnsInvalidArguments()
+    {
+        MemoryWorkerEnvironment environment = CreateEnvironment("nonce-secret");
+        MemoryWorkerLogger logger = new();
+
+        int exitCode = MxGateway.Worker.WorkerApplication.Run(
+            [],
+            environment,
+            logger);
+
+        Assert.Equal((int)WorkerExitCode.InvalidArguments, exitCode);
+        MemoryWorkerLogEntry entry = Assert.Single(logger.Entries);
+        Assert.Equal("Error", entry.Level);
+        Assert.Equal("WorkerBootstrapFailed", entry.EventName);
+        Assert.Equal(WorkerExitCode.InvalidArguments, entry.Fields["exit_code"]);
+    }
+
+    [Fact]
+    public void Run_WithInvalidProtocolVersion_ReturnsInvalidProtocolVersion()
+    {
+        MemoryWorkerEnvironment environment = CreateEnvironment("nonce-secret");
+        MemoryWorkerLogger logger = new();
+
+        int exitCode = MxGateway.Worker.WorkerApplication.Run(
+            ValidArgs(protocolVersion: "999"),
+            environment,
+            logger);
+
+        Assert.Equal((int)WorkerExitCode.InvalidProtocolVersion, exitCode);
+    }
+
+    [Fact]
+    public void Run_WithMissingNonce_ReturnsMissingNonce()
+    {
+        MemoryWorkerEnvironment environment = new();
+        MemoryWorkerLogger logger = new();
+
+        int exitCode = MxGateway.Worker.WorkerApplication.Run(
+            ValidArgs(),
+            environment,
+            logger);
+
+        Assert.Equal((int)WorkerExitCode.MissingNonce, exitCode);
+    }
+
+    [Fact]
+    public void Run_WithUnexpectedBootstrapFailure_ReturnsUnexpectedFailure()
+    {
+        MemoryWorkerEnvironment environment = new(new InvalidOperationException("environment failed"));
+        MemoryWorkerLogger logger = new();
+
+        int exitCode = MxGateway.Worker.WorkerApplication.Run(
+            ValidArgs(),
+            environment,
+            logger);
+
+        Assert.Equal((int)WorkerExitCode.UnexpectedFailure, exitCode);
+        MemoryWorkerLogEntry entry = Assert.Single(logger.Entries);
+        Assert.Equal("WorkerBootstrapUnexpectedFailure", entry.EventName);
+        Assert.Equal(WorkerExitCode.UnexpectedFailure, entry.Fields["exit_code"]);
+        Assert.Equal(typeof(InvalidOperationException).FullName, entry.Fields["exception_type"]);
+    }
+
+    private static string[] ValidArgs(string? protocolVersion = null)
+    {
+        return
+        [
+            "--session-id",
+            "session-1",
+            "--pipe-name",
+            "mxaccess-gateway-123-session-1",
+            "--protocol-version",
+            protocolVersion ?? GatewayContractInfo.WorkerProtocolVersion.ToString(),
+        ];
+    }
+
+    private static MemoryWorkerEnvironment CreateEnvironment(string nonce)
+    {
+        MemoryWorkerEnvironment environment = new();
+        environment.Set(WorkerOptions.NonceEnvironmentVariableName, nonce);
+        return environment;
+    }
+}

src/MxGateway.Worker.Tests/Bootstrap/WorkerConsoleLoggerTests.cs

@@ -0,0 +1,28 @@
+using System.Collections.Generic;
+using System.IO;
+using MxGateway.Worker.Bootstrap;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+public sealed class WorkerConsoleLoggerTests
+{
+    [Fact]
+    public void Information_RedactsNonceInStructuredOutput()
+    {
+        StringWriter writer = new();
+        WorkerConsoleLogger logger = new(writer);
+
+        logger.Information("WorkerBootstrapSucceeded", new Dictionary<string, object?>
+        {
+            ["session_id"] = "session-1",
+            ["nonce"] = "nonce-secret",
+        });
+
+        string output = writer.ToString();
+
+        Assert.Contains("event=WorkerBootstrapSucceeded", output);
+        Assert.Contains("session_id=session-1", output);
+        Assert.Contains("nonce=[redacted]", output);
+        Assert.DoesNotContain("nonce-secret", output);
+    }
+}

src/MxGateway.Worker.Tests/Bootstrap/WorkerLogRedactorTests.cs

@@ -0,0 +1,32 @@
+using System.Collections.Generic;
+using MxGateway.Worker.Bootstrap;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+public sealed class WorkerLogRedactorTests
+{
+    [Fact]
+    public void RedactFields_RedactsNonceSecretPasswordTokenCredentialAndApiKeyFields()
+    {
+        Dictionary<string, object?> fields = new()
+        {
+            ["nonce"] = "nonce-secret",
+            ["client_secret"] = "secret",
+            ["password"] = "password",
+            ["auth_token"] = "token",
+            ["credential_value"] = "credential",
+            ["api_key"] = "key",
+            ["session_id"] = "session-1",
+        };
+
+        Dictionary<string, object?> redacted = WorkerLogRedactor.RedactFields(fields);
+
+        Assert.Equal("[redacted]", redacted["nonce"]);
+        Assert.Equal("[redacted]", redacted["client_secret"]);
+        Assert.Equal("[redacted]", redacted["password"]);
+        Assert.Equal("[redacted]", redacted["auth_token"]);
+        Assert.Equal("[redacted]", redacted["credential_value"]);
+        Assert.Equal("[redacted]", redacted["api_key"]);
+        Assert.Equal("session-1", redacted["session_id"]);
+    }
+}

src/MxGateway.Worker.Tests/Bootstrap/WorkerOptionsParserTests.cs

@@ -0,0 +1,115 @@
+using MxGateway.Contracts;
+using MxGateway.Worker.Bootstrap;
+
+namespace MxGateway.Worker.Tests.Bootstrap;
+
+public sealed class WorkerOptionsParserTests
+{
+    [Fact]
+    public void Parse_WithAllRequiredInputs_ReturnsWorkerOptions()
+    {
+        WorkerOptionsParser parser = new(CreateEnvironment("nonce-secret"));
+
+        WorkerBootstrapResult result = parser.Parse(ValidArgs());
+
+        Assert.True(result.Succeeded);
+        Assert.Equal(WorkerExitCode.Success, result.ExitCode);
+        Assert.NotNull(result.Options);
+        Assert.Equal("session-1", result.Options.SessionId);
+        Assert.Equal("mxaccess-gateway-123-session-1", result.Options.PipeName);
+        Assert.Equal(GatewayContractInfo.WorkerProtocolVersion, result.Options.ProtocolVersion);
+        Assert.Equal("nonce-secret", result.Options.Nonce);
+    }
+
+    [Fact]
+    public void Parse_WithMissingSessionId_ReturnsInvalidArguments()
+    {
+        WorkerOptionsParser parser = new(CreateEnvironment("nonce-secret"));
+
+        WorkerBootstrapResult result = parser.Parse(
+        [
+            "--pipe-name",
+            "mxaccess-gateway-123-session-1",
+            "--protocol-version",
+            GatewayContractInfo.WorkerProtocolVersion.ToString(),
+        ]);
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(WorkerExitCode.InvalidArguments, result.ExitCode);
+        Assert.Contains(result.Errors, error => error.Contains("--session-id"));
+    }
+
+    [Fact]
+    public void Parse_WithUnknownOption_ReturnsInvalidArguments()
+    {
+        WorkerOptionsParser parser = new(CreateEnvironment("nonce-secret"));
+
+        WorkerBootstrapResult result = parser.Parse(
+        [
+            "--session-id",
+            "session-1",
+            "--pipe-name",
+            "mxaccess-gateway-123-session-1",
+            "--protocol-version",
+            GatewayContractInfo.WorkerProtocolVersion.ToString(),
+            "--unexpected",
+            "value",
+        ]);
+
+        Assert.Equal(WorkerExitCode.InvalidArguments, result.ExitCode);
+        Assert.Contains(result.Errors, error => error.Contains("Unknown option"));
+    }
+
+    [Fact]
+    public void Parse_WithNonNumericProtocolVersion_ReturnsInvalidProtocolVersion()
+    {
+        WorkerOptionsParser parser = new(CreateEnvironment("nonce-secret"));
+
+        WorkerBootstrapResult result = parser.Parse(ValidArgs(protocolVersion: "abc"));
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(WorkerExitCode.InvalidProtocolVersion, result.ExitCode);
+    }
+
+    [Fact]
+    public void Parse_WithUnsupportedProtocolVersion_ReturnsInvalidProtocolVersion()
+    {
+        WorkerOptionsParser parser = new(CreateEnvironment("nonce-secret"));
+
+        WorkerBootstrapResult result = parser.Parse(ValidArgs(protocolVersion: "999"));
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(WorkerExitCode.InvalidProtocolVersion, result.ExitCode);
+    }
+
+    [Fact]
+    public void Parse_WithMissingNonce_ReturnsMissingNonce()
+    {
+        WorkerOptionsParser parser = new(new MemoryWorkerEnvironment());
+
+        WorkerBootstrapResult result = parser.Parse(ValidArgs());
+
+        Assert.False(result.Succeeded);
+        Assert.Equal(WorkerExitCode.MissingNonce, result.ExitCode);
+    }
+
+    private static string[] ValidArgs(string? protocolVersion = null)
+    {
+        return
+        [
+            "--session-id",
+            "session-1",
+            "--pipe-name",
+            "mxaccess-gateway-123-session-1",
+            "--protocol-version",
+            protocolVersion ?? GatewayContractInfo.WorkerProtocolVersion.ToString(),
+        ];
+    }
+
+    private static MemoryWorkerEnvironment CreateEnvironment(string nonce)
+    {
+        MemoryWorkerEnvironment environment = new();
+        environment.Set(WorkerOptions.NonceEnvironmentVariableName, nonce);
+        return environment;
+    }
+}

src/MxGateway.Worker/Bootstrap/.gitkeep

@@ -1 +0,0 @@
-

src/MxGateway.Worker/Bootstrap/EnvironmentVariableWorkerEnvironment.cs

@@ -0,0 +1,11 @@
+using System;
+
+namespace MxGateway.Worker.Bootstrap;
+
+public sealed class EnvironmentVariableWorkerEnvironment : IWorkerEnvironment
+{
+    public string? GetEnvironmentVariable(string name)
+    {
+        return Environment.GetEnvironmentVariable(name);
+    }
+}

src/MxGateway.Worker/Bootstrap/IWorkerEnvironment.cs

@@ -0,0 +1,6 @@
+namespace MxGateway.Worker.Bootstrap;
+
+public interface IWorkerEnvironment
+{
+    string? GetEnvironmentVariable(string name);
+}

src/MxGateway.Worker/Bootstrap/IWorkerLogger.cs

@@ -0,0 +1,10 @@
+using System.Collections.Generic;
+
+namespace MxGateway.Worker.Bootstrap;
+
+public interface IWorkerLogger
+{
+    void Information(string eventName, IReadOnlyDictionary<string, object?> fields);
+
+    void Error(string eventName, IReadOnlyDictionary<string, object?> fields);
+}

src/MxGateway.Worker/Bootstrap/WorkerBootstrapResult.cs

@@ -0,0 +1,35 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace MxGateway.Worker.Bootstrap;
+
+public sealed class WorkerBootstrapResult
+{
+    private WorkerBootstrapResult(
+        WorkerExitCode exitCode,
+        WorkerOptions? options,
+        IReadOnlyList<string> errors)
+    {
+        ExitCode = exitCode;
+        Options = options;
+        Errors = errors;
+    }
+
+    public WorkerExitCode ExitCode { get; }
+
+    public WorkerOptions? Options { get; }
+
+    public IReadOnlyList<string> Errors { get; }
+
+    public bool Succeeded => ExitCode == WorkerExitCode.Success;
+
+    public static WorkerBootstrapResult Success(WorkerOptions options)
+    {
+        return new WorkerBootstrapResult(WorkerExitCode.Success, options, []);
+    }
+
+    public static WorkerBootstrapResult Failure(WorkerExitCode exitCode, IEnumerable<string> errors)
+    {
+        return new WorkerBootstrapResult(exitCode, null, errors.ToArray());
+    }
+}

src/MxGateway.Worker/Bootstrap/WorkerConsoleLogger.cs

@@ -0,0 +1,44 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+
+namespace MxGateway.Worker.Bootstrap;
+
+public sealed class WorkerConsoleLogger : IWorkerLogger
+{
+    private readonly TextWriter _writer;
+
+    public WorkerConsoleLogger(TextWriter writer)
+    {
+        _writer = writer ?? throw new ArgumentNullException(nameof(writer));
+    }
+
+    public void Information(string eventName, IReadOnlyDictionary<string, object?> fields)
+    {
+        Write("Information", eventName, fields);
+    }
+
+    public void Error(string eventName, IReadOnlyDictionary<string, object?> fields)
+    {
+        Write("Error", eventName, fields);
+    }
+
+    private void Write(
+        string level,
+        string eventName,
+        IReadOnlyDictionary<string, object?> fields)
+    {
+        Dictionary<string, object?> redactedFields = WorkerLogRedactor.RedactFields(fields);
+        string fieldText = string.Join(
+            " ",
+            redactedFields.Select(field => $"{field.Key}={FormatValue(field.Value)}"));
+
+        _writer.WriteLine($"level={level} event={eventName} {fieldText}".TrimEnd());
+    }
+
+    private static string FormatValue(object? value)
+    {
+        return value?.ToString() ?? string.Empty;
+    }
+}

src/MxGateway.Worker/Bootstrap/WorkerExitCode.cs

@@ -0,0 +1,10 @@
+namespace MxGateway.Worker.Bootstrap;
+
+public enum WorkerExitCode
+{
+    Success = 0,
+    UnexpectedFailure = 1,
+    InvalidArguments = 2,
+    InvalidProtocolVersion = 3,
+    MissingNonce = 4,
+}

src/MxGateway.Worker/Bootstrap/WorkerLogRedactor.cs

@@ -0,0 +1,50 @@
+using System;
+using System.Collections.Generic;
+
+namespace MxGateway.Worker.Bootstrap;
+
+public static class WorkerLogRedactor
+{
+    public const string RedactedValue = "[redacted]";
+
+    private static readonly string[] SensitiveFieldNameParts =
+    [
+        "nonce",
+        "secret",
+        "password",
+        "token",
+        "credential",
+        "apikey",
+        "api_key",
+    ];
+
+    public static Dictionary<string, object?> RedactFields(IReadOnlyDictionary<string, object?> fields)
+    {
+        Dictionary<string, object?> redactedFields = [];
+
+        foreach (KeyValuePair<string, object?> field in fields)
+        {
+            redactedFields[field.Key] = RedactValue(field.Key, field.Value);
+        }
+
+        return redactedFields;
+    }
+
+    public static object? RedactValue(string fieldName, object? value)
+    {
+        if (value is null)
+        {
+            return null;
+        }
+
+        foreach (string sensitiveFieldNamePart in SensitiveFieldNameParts)
+        {
+            if (fieldName.IndexOf(sensitiveFieldNamePart, StringComparison.OrdinalIgnoreCase) >= 0)
+            {
+                return RedactedValue;
+            }
+        }
+
+        return value;
+    }
+}

src/MxGateway.Worker/Bootstrap/WorkerOptions.cs

@@ -0,0 +1,26 @@
+namespace MxGateway.Worker.Bootstrap;
+
+public sealed class WorkerOptions
+{
+    public const string NonceEnvironmentVariableName = "MXGATEWAY_WORKER_NONCE";
+
+    public WorkerOptions(
+        string sessionId,
+        string pipeName,
+        uint protocolVersion,
+        string nonce)
+    {
+        SessionId = sessionId;
+        PipeName = pipeName;
+        ProtocolVersion = protocolVersion;
+        Nonce = nonce;
+    }
+
+    public string SessionId { get; }
+
+    public string PipeName { get; }
+
+    public uint ProtocolVersion { get; }
+
+    public string Nonce { get; }
+}

src/MxGateway.Worker/Bootstrap/WorkerOptionsParser.cs

@@ -0,0 +1,101 @@
+using System;
+using System.Collections.Generic;
+using MxGateway.Contracts;
+
+namespace MxGateway.Worker.Bootstrap;
+
+public sealed class WorkerOptionsParser
+{
+    private const string SessionIdOptionName = "--session-id";
+    private const string PipeNameOptionName = "--pipe-name";
+    private const string ProtocolVersionOptionName = "--protocol-version";
+
+    private readonly IWorkerEnvironment _environment;
+
+    public WorkerOptionsParser(IWorkerEnvironment environment)
+    {
+        _environment = environment ?? throw new ArgumentNullException(nameof(environment));
+    }
+
+    public WorkerBootstrapResult Parse(string[] args)
+    {
+        if (args is null)
+        {
+            throw new ArgumentNullException(nameof(args));
+        }
+
+        Dictionary<string, string> values = new(StringComparer.OrdinalIgnoreCase);
+        List<string> errors = [];
+
+        for (int index = 0; index < args.Length; index++)
+        {
+            string arg = args[index];
+            if (!IsKnownOption(arg))
+            {
+                errors.Add($"Unknown option '{arg}'.");
+                continue;
+            }
+
+            if (index + 1 >= args.Length || args[index + 1].StartsWith("--", StringComparison.Ordinal))
+            {
+                errors.Add($"Option '{arg}' requires a value.");
+                continue;
+            }
+
+            values[arg] = args[index + 1];
+            index++;
+        }
+
+        string? sessionId = ReadRequired(values, SessionIdOptionName, errors);
+        string? pipeName = ReadRequired(values, PipeNameOptionName, errors);
+        string? protocolVersionText = ReadRequired(values, ProtocolVersionOptionName, errors);
+
+        if (errors.Count > 0)
+        {
+            return WorkerBootstrapResult.Failure(WorkerExitCode.InvalidArguments, errors);
+        }
+
+        if (!uint.TryParse(protocolVersionText, out uint protocolVersion)
+            || protocolVersion != GatewayContractInfo.WorkerProtocolVersion)
+        {
+            return WorkerBootstrapResult.Failure(
+                WorkerExitCode.InvalidProtocolVersion,
+                [$"Unsupported protocol version '{protocolVersionText}'."]);
+        }
+
+        string? nonce = _environment.GetEnvironmentVariable(WorkerOptions.NonceEnvironmentVariableName);
+
+        if (string.IsNullOrWhiteSpace(nonce))
+        {
+            return WorkerBootstrapResult.Failure(
+                WorkerExitCode.MissingNonce,
+                ["Required worker nonce environment variable is missing."]);
+        }
+
+        return WorkerBootstrapResult.Success(new WorkerOptions(
+            sessionId!,
+            pipeName!,
+            protocolVersion,
+            nonce!));
+    }
+
+    private static string? ReadRequired(
+        IReadOnlyDictionary<string, string> values,
+        string optionName,
+        List<string> errors)
+    {
+        if (!values.TryGetValue(optionName, out string value)
+            || string.IsNullOrWhiteSpace(value))
+        {
+            errors.Add($"Required option '{optionName}' is missing.");
+            return null;
+        }
+
+        return value;
+    }
+
+    private static bool IsKnownOption(string optionName)
+    {
+        return optionName is SessionIdOptionName or PipeNameOptionName or ProtocolVersionOptionName;
+    }
+}

src/MxGateway.Worker/WorkerApplication.cs

@@ -1,16 +1,77 @@
 using System;
+using System.Collections.Generic;
+using MxGateway.Worker.Bootstrap;
 
 namespace MxGateway.Worker;
 
 public static class WorkerApplication
 {
     public static int Run(string[] args)
+    {
+        return Run(
+            args,
+            new EnvironmentVariableWorkerEnvironment(),
+            new WorkerConsoleLogger(Console.Error));
+    }
+
+    public static int Run(
+        string[] args,
+        IWorkerEnvironment environment,
+        IWorkerLogger logger)
     {
         if (args is null)
         {
             throw new ArgumentNullException(nameof(args));
         }
 
-        return 0;
+        if (environment is null)
+        {
+            throw new ArgumentNullException(nameof(environment));
+        }
+
+        if (logger is null)
+        {
+            throw new ArgumentNullException(nameof(logger));
+        }
+
+        try
+        {
+            WorkerOptionsParser parser = new(environment);
+            WorkerBootstrapResult result = parser.Parse(args);
+
+            if (!result.Succeeded)
+            {
+                logger.Error("WorkerBootstrapFailed", new Dictionary<string, object?>
+                {
+                    ["exit_code"] = result.ExitCode,
+                    ["errors"] = string.Join(";", result.Errors),
+                });
+
+                return (int)result.ExitCode;
+            }
+
+            WorkerOptions options = result.Options
+                ?? throw new InvalidOperationException("Successful bootstrap result did not include worker options.");
+
+            logger.Information("WorkerBootstrapSucceeded", new Dictionary<string, object?>
+            {
+                ["session_id"] = options.SessionId,
+                ["pipe_name"] = options.PipeName,
+                ["protocol_version"] = options.ProtocolVersion,
+                ["nonce"] = options.Nonce,
+            });
+
+            return (int)WorkerExitCode.Success;
+        }
+        catch (Exception exception)
+        {
+            logger.Error("WorkerBootstrapUnexpectedFailure", new Dictionary<string, object?>
+            {
+                ["exit_code"] = WorkerExitCode.UnexpectedFailure,
+                ["exception_type"] = exception.GetType().FullName,
+            });
+
+            return (int)WorkerExitCode.UnexpectedFailure;
+        }
     }
 }