diff --git a/docs/GatewayProcessDesign.md b/docs/GatewayProcessDesign.md index d4dfabcb..d8dc4f28 100644 --- a/docs/GatewayProcessDesign.md +++ b/docs/GatewayProcessDesign.md @@ -804,9 +804,12 @@ ZB.MOM.WW.MxGateway.Server apikey revoke-key --key-id operator01 ZB.MOM.WW.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 +The subcommands accept `--sqlite-path`, `--pepper`, `--pepper-stdin`, and `--json`. +`--pepper-stdin` reads the first line of standard input and `--pepper ` takes it +from the command line; either sets the local `MxGateway:ApiKeyPepper` configuration value +for the command process (they are mutually exclusive). `--pepper` leaves the pepper in shell +history and the process list, so the command prints a warning to stderr — prefer +`--pepper-stdin`, the `MxGateway__ApiKeyPepper` environment variable, or 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. diff --git a/src/ZB.MOM.WW.MxGateway.Server/Program.cs b/src/ZB.MOM.WW.MxGateway.Server/Program.cs index 6b5dcaa9..f7878776 100644 --- a/src/ZB.MOM.WW.MxGateway.Server/Program.cs +++ b/src/ZB.MOM.WW.MxGateway.Server/Program.cs @@ -12,7 +12,10 @@ if (apiKeyAdminCommand.IsApiKeyCommand) } WebApplicationBuilder builder = GatewayApplication.CreateBuilder([]); - ApplyApiKeyAdminOverrides(builder.Configuration, apiKeyAdminCommand.Command); + ApplyApiKeyAdminOverrides( + builder.Configuration, + apiKeyAdminCommand.Command, + ApiKeyAdminPepperResolver.Resolve(apiKeyAdminCommand.Command, Console.In, Console.Error)); await using WebApplication cliApp = builder.Build(); await using AsyncServiceScope scope = cliApp.Services.CreateAsyncScope(); @@ -27,16 +30,16 @@ app.Run(); return 0; -static void ApplyApiKeyAdminOverrides(IConfiguration configuration, ApiKeyAdminCommand command) +static void ApplyApiKeyAdminOverrides(IConfiguration configuration, ApiKeyAdminCommand command, string? pepper) { if (!string.IsNullOrWhiteSpace(command.SqlitePath)) { configuration[$"{GatewayOptions.SectionName}:Authentication:SqlitePath"] = command.SqlitePath; } - if (!string.IsNullOrWhiteSpace(command.Pepper)) + if (!string.IsNullOrWhiteSpace(pepper)) { - configuration["MxGateway:ApiKeyPepper"] = command.Pepper; + configuration["MxGateway:ApiKeyPepper"] = pepper; } } diff --git a/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommand.cs b/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommand.cs index 46c6f2d4..a3cbcb31 100644 --- a/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommand.cs +++ b/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommand.cs @@ -9,4 +9,5 @@ public sealed record ApiKeyAdminCommand( string? DisplayName, IReadOnlySet Scopes, ApiKeyConstraints Constraints, - DateTimeOffset? ExpiresUtc = null); + DateTimeOffset? ExpiresUtc = null, + bool PepperFromStdin = false); diff --git a/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs b/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs index 607efd69..8f04524a 100644 --- a/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs +++ b/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs @@ -26,6 +26,7 @@ public static class ApiKeyAdminCommandLineParser Dictionary> options = new(StringComparer.OrdinalIgnoreCase); bool json = false; + bool pepperFromStdin = false; for (int index = 2; index < args.Count; index++) { @@ -36,6 +37,13 @@ public static class ApiKeyAdminCommandLineParser continue; } + // --pepper-stdin keeps the pepper out of the process list and shell history (R21-O17). + if (string.Equals(arg, "--pepper-stdin", StringComparison.OrdinalIgnoreCase)) + { + pepperFromStdin = true; + continue; + } + if (!arg.StartsWith("--", StringComparison.Ordinal)) { return ApiKeyAdminParseResult.Fail($"Unexpected argument '{arg}'."); @@ -93,6 +101,11 @@ public static class ApiKeyAdminCommandLineParser return ApiKeyAdminParseResult.Fail(exception.Message); } + if (pepperFromStdin && GetOption(options, "pepper") is not null) + { + return ApiKeyAdminParseResult.Fail("Specify either --pepper or --pepper-stdin, not both."); + } + string? validationError = Validate(kind, keyId, displayName); if (validationError is not null) { @@ -114,7 +127,8 @@ public static class ApiKeyAdminCommandLineParser DisplayName: displayName, Scopes: scopes, Constraints: constraints, - ExpiresUtc: expiresUtc)); + ExpiresUtc: expiresUtc, + PepperFromStdin: pepperFromStdin)); } private static bool TryParseKind(string value, out ApiKeyAdminCommandKind kind) diff --git a/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminPepperResolver.cs b/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminPepperResolver.cs new file mode 100644 index 00000000..0346a573 --- /dev/null +++ b/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminPepperResolver.cs @@ -0,0 +1,29 @@ +namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication; + +/// Resolves the optional pepper override for the apikey admin subcommand. +public static class ApiKeyAdminPepperResolver +{ + /// + /// Returns the pepper to apply, or null to leave configuration (env var + /// MxGateway__ApiKeyPepper / secret source) untouched. A pepper passed via + /// --pepper works but is visible in shell history and the process list, so a warning + /// is written to ; --pepper-stdin reads the first stdin line instead. + /// + public static string? Resolve(ApiKeyAdminCommand command, TextReader input, TextWriter error) + { + if (command.PepperFromStdin) + { + string? line = input.ReadLine(); + return string.IsNullOrWhiteSpace(line) ? null : line.Trim(); + } + + if (!string.IsNullOrWhiteSpace(command.Pepper)) + { + error.WriteLine( + "warning: --pepper exposes the pepper in shell history and the process list; " + + "prefer --pepper-stdin or the MxGateway__ApiKeyPepper environment variable."); + } + + return command.Pepper; + } +} diff --git a/src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeyAdminPepperResolverTests.cs b/src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeyAdminPepperResolverTests.cs new file mode 100644 index 00000000..6fbbe2ad --- /dev/null +++ b/src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeyAdminPepperResolverTests.cs @@ -0,0 +1,60 @@ +using ZB.MOM.WW.MxGateway.Server.Security.Authentication; + +namespace ZB.MOM.WW.MxGateway.Tests.Security.Authentication; + +public sealed class ApiKeyAdminPepperResolverTests +{ + private static ApiKeyAdminCommand Parse(params string[] extra) + { + ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse(["apikey", "list-keys", .. extra]); + Assert.Null(result.Error); + return result.Command!; + } + + /// --pepper-stdin parses without a value and reads the pepper from stdin, with no warning. + [Fact] + public void Resolve_PepperStdin_ReadsFirstLine_NoWarning() + { + ApiKeyAdminCommand command = Parse("--pepper-stdin"); + StringWriter error = new(); + + string? pepper = ApiKeyAdminPepperResolver.Resolve(command, new StringReader("s3cret\nignored\n"), error); + + Assert.True(command.PepperFromStdin); + Assert.Null(command.Pepper); + Assert.Equal("s3cret", pepper); + Assert.Equal(string.Empty, error.ToString()); + } + + /// --pepper still works but warns on stderr without echoing the secret. + [Fact] + public void Resolve_PepperFlag_WarnsWithoutEchoingSecret() + { + ApiKeyAdminCommand command = Parse("--pepper", "s3cret"); + StringWriter error = new(); + + string? pepper = ApiKeyAdminPepperResolver.Resolve(command, new StringReader(string.Empty), error); + + Assert.Equal("s3cret", pepper); + Assert.Contains("--pepper-stdin", error.ToString()); + Assert.DoesNotContain("s3cret", error.ToString()); + } + + /// No pepper option leaves configuration untouched and stays silent. + [Fact] + public void Resolve_NoPepper_ReturnsNull_Silent() + { + StringWriter error = new(); + Assert.Null(ApiKeyAdminPepperResolver.Resolve(Parse(), new StringReader("x"), error)); + Assert.Equal(string.Empty, error.ToString()); + } + + /// Supplying both pepper sources is rejected. + [Fact] + public void Parse_PepperAndPepperStdin_Fails() + { + ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse( + ["apikey", "list-keys", "--pepper", "a", "--pepper-stdin"]); + Assert.NotNull(result.Error); + } +}