feat(apikey): add --pepper-stdin and warn on --pepper (mxaccessgw#194)

--pepper on the command line lands in shell history and the process list.
Add --pepper-stdin (first stdin line), warn on stderr when --pepper is used,
and reject both together. Documented in GatewayProcessDesign.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 12:27:37 -05:00
parent be0d585f8c
commit 417b9e5a19
6 changed files with 119 additions and 9 deletions
+6 -3
View File
@@ -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 <value>` 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.
+7 -4
View File
@@ -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;
}
}
@@ -9,4 +9,5 @@ public sealed record ApiKeyAdminCommand(
string? DisplayName,
IReadOnlySet<string> Scopes,
ApiKeyConstraints Constraints,
DateTimeOffset? ExpiresUtc = null);
DateTimeOffset? ExpiresUtc = null,
bool PepperFromStdin = false);
@@ -26,6 +26,7 @@ public static class ApiKeyAdminCommandLineParser
Dictionary<string, List<string?>> 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)
@@ -0,0 +1,29 @@
namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
/// <summary>Resolves the optional pepper override for the <c>apikey</c> admin subcommand.</summary>
public static class ApiKeyAdminPepperResolver
{
/// <summary>
/// Returns the pepper to apply, or null to leave configuration (env var
/// <c>MxGateway__ApiKeyPepper</c> / secret source) untouched. A pepper passed via
/// <c>--pepper</c> works but is visible in shell history and the process list, so a warning
/// is written to <paramref name="error"/>; <c>--pepper-stdin</c> reads the first stdin line instead.
/// </summary>
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;
}
}
@@ -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!;
}
/// <summary>--pepper-stdin parses without a value and reads the pepper from stdin, with no warning.</summary>
[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());
}
/// <summary>--pepper still works but warns on stderr without echoing the secret.</summary>
[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());
}
/// <summary>No pepper option leaves configuration untouched and stays silent.</summary>
[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());
}
/// <summary>Supplying both pepper sources is rejected.</summary>
[Fact]
public void Parse_PepperAndPepperStdin_Fails()
{
ApiKeyAdminParseResult result = ApiKeyAdminCommandLineParser.Parse(
["apikey", "list-keys", "--pepper", "a", "--pepper-stdin"]);
Assert.NotNull(result.Error);
}
}