fix(SEC-31,SEC-32): re-partition the API-key failure limiter on (peer, key id) with probe admission

The gRPC auth failure limiter partitioned on the key id parsed out of the
*unauthenticated* token and rejected with ResourceExhausted before VerifyAsync
ran. Key ids are not secret — they ride in every token and are listed on the
dashboard — so any network peer could send 10 garbage-secret requests per minute
and deny that key indefinitely: the legitimate holder's correct secret was
refused before it was ever checked, and the success-path Reset that would clear
the block sat behind the verification the block prevented (SEC-31). The tracked
map was also flushable — any `a_b_c`-shaped junk minted a fresh partition (the
`mxgw` literal was never compared), so ~4096 throwaway tokens evicted a blocked
entry and reset the window (SEC-32).

ApiKeyFailureLimiter moves from IsBlocked/RecordFailure/Reset(string peer) to a
partition-pair API: Check/RecordFailure/Reset(ApiKeyThrottlePartition) with an
ApiKeyThrottleDecision result. Two layers share one sliding window — a composite
(transport peer, key id) partition at ApiKeyFailureLimit, and a per-key-id
aggregate across all peers at the new ApiKeyFailureAggregateLimit (default 30)
that bounds a source-rotating sprayer. An over-limit state is now a valve rather
than a wall: one request per the new ApiKeyFailureProbeIntervalSeconds (default
5) is admitted through to the real verifier, so the correct secret always reaches
the constant-time compare and resets both layers. Guarantees preserved: guessing
stays bounded per window, and the failure path still spends no store read per
attempt.

SEC-32 rides the same change set: the interceptor validates token shape (literal
`mxgw` prefix, >= 3 non-empty `_` segments, key id <= 64 chars) before minting a
key-id partition, each transport peer may mint at most 32 of them before the
overflow collapses onto its fallback partition, and eviction prefers fully
expired windows and never drops an over-limit partition below a 2x transient
overshoot ceiling. Throttled attempts increment mxgateway.auth.throttled, tagged
stage=peer|aggregate only — /metrics is unauthenticated (open SEC-14), so no key
material may appear there.

Docs in the same commit: GatewayConfiguration limiter rows plus the two new keys,
the Authentication hot-path paragraph, the Authorization SEC-11 section, and the
limiter / SecurityOptions XML remarks (the old NAT rationale described the
defective keying). Tracking rows flipped to Done with a change-log entry.

Tests: new ApiKeyFailureLimiterTests (11) covering window pruning, composite vs
aggregate trip points, probe cadence, absolute-block mode, reset across both
layers, junk-spray eviction resistance, the per-peer cap, and expired-window
eviction preference; GatewayGrpcAuthorizationInterceptorTests gains the four
SEC-31 contract tests plus NonMxgwToken_FallsBackToTransportPeerPartition (20
total); GatewayOptionsValidatorTests covers both new keys including 0 as a
supported disable value (66 total).

src/ZB.MOM.WW.MxGateway.Tests/Configuration/GatewayOptionsValidatorTests.cs

@@ -794,6 +794,45 @@ public sealed class GatewayOptionsValidatorTests
         Assert.Contains(result.Failures!, f => f.Contains("ApiKeyFailureTrackedPeers"));
     }
 
+    /// <summary>Verifies a negative per-key aggregate failure limit fails validation.</summary>
+    [Fact]
+    public void Validate_Fails_WhenApiKeyFailureAggregateLimitNegative()
+    {
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(
+            null,
+            WithSecurity(new SecurityOptions { ApiKeyFailureAggregateLimit = -1 }));
+        Assert.True(result.Failed);
+        Assert.Contains(result.Failures!, f => f.Contains("ApiKeyFailureAggregateLimit"));
+    }
+
+    /// <summary>Verifies a negative probe interval fails validation.</summary>
+    [Fact]
+    public void Validate_Fails_WhenApiKeyFailureProbeIntervalSecondsNegative()
+    {
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(
+            null,
+            WithSecurity(new SecurityOptions { ApiKeyFailureProbeIntervalSeconds = -1 }));
+        Assert.True(result.Failed);
+        Assert.Contains(result.Failures!, f => f.Contains("ApiKeyFailureProbeIntervalSeconds"));
+    }
+
+    /// <summary>
+    /// Zero is a supported (documented) value for both new limiter knobs: it disables the aggregate
+    /// layer and probe admission respectively, so validation must accept it.
+    /// </summary>
+    [Fact]
+    public void Validate_Succeeds_WhenAggregateLimitAndProbeIntervalAreZero()
+    {
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(
+            null,
+            WithSecurity(new SecurityOptions
+            {
+                ApiKeyFailureAggregateLimit = 0,
+                ApiKeyFailureProbeIntervalSeconds = 0,
+            }));
+        Assert.True(result.Succeeded);
+    }
+
     private static GatewayOptions WithWorkerAndProtocol(WorkerOptions worker, ProtocolOptions protocol)
     {
         GatewayOptions source = ValidOptions();

src/ZB.MOM.WW.MxGateway.Tests/Security/Authorization/ApiKeyFailureLimiterTests.cs

@@ -0,0 +1,265 @@
+using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+using ZB.MOM.WW.MxGateway.Tests.TestSupport;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Security.Authorization;
+
+/// <summary>
+/// Unit tests for the two-layer API-key failure limiter (SEC-31 / SEC-32): composite
+/// <c>(transport peer, key id)</c> partitions, the cross-peer per-key-id aggregate, probe
+/// admission, the per-peer key-id partition cap, and the eviction preference order.
+/// </summary>
+public sealed class ApiKeyFailureLimiterTests
+{
+    private static readonly TimeSpan Window = TimeSpan.FromSeconds(60);
+    private static readonly TimeSpan ProbeInterval = TimeSpan.FromSeconds(5);
+
+    /// <summary>A partition below the failure limit is admitted without consulting a probe slot.</summary>
+    [Fact]
+    public void Check_BelowLimit_Allows()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3);
+        ApiKeyThrottlePartition partition = new("ipv4:10.0.0.1:1", "victim");
+
+        limiter.RecordFailure(partition);
+        limiter.RecordFailure(partition);
+
+        Assert.Equal(ApiKeyThrottleDecision.Allowed, limiter.Check(partition));
+    }
+
+    /// <summary>Reaching the limit inside the window throttles the composite partition.</summary>
+    [Fact]
+    public void Check_AtLimit_ThrottlesCompositePartition()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3);
+        ApiKeyThrottlePartition partition = new("ipv4:10.0.0.1:1", "victim");
+
+        RecordFailures(limiter, partition, 3);
+
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(partition));
+    }
+
+    /// <summary>Failures older than the sliding window are pruned, releasing the throttle.</summary>
+    [Fact]
+    public void Window_PrunesExpiredFailures_ReleasesThrottle()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3);
+        ApiKeyThrottlePartition partition = new("ipv4:10.0.0.1:1", "victim");
+
+        RecordFailures(limiter, partition, 3);
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(partition));
+
+        clock.Advance(Window + TimeSpan.FromSeconds(1));
+
+        Assert.Equal(ApiKeyThrottleDecision.Allowed, limiter.Check(partition));
+    }
+
+    /// <summary>
+    /// The composite partition binds a throttle to the failing address: the same key id presented
+    /// from a different transport peer is unaffected. This is the structural half of the SEC-31 fix.
+    /// </summary>
+    [Fact]
+    public void CompositePartition_ThrottleDoesNotFollowKeyIdToAnotherPeer()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, aggregateLimit: 1000);
+
+        RecordFailures(limiter, new ApiKeyThrottlePartition("ipv4:10.0.0.1:1", "victim"), 3);
+
+        Assert.Equal(
+            ApiKeyThrottleDecision.ThrottledByPeer,
+            limiter.Check(new ApiKeyThrottlePartition("ipv4:10.0.0.1:1", "victim")));
+        Assert.Equal(
+            ApiKeyThrottleDecision.Allowed,
+            limiter.Check(new ApiKeyThrottlePartition("ipv4:10.0.0.2:1", "victim")));
+    }
+
+    /// <summary>
+    /// Failures for one key id spread across many peers trip the per-key aggregate layer, so a
+    /// rotating-source sprayer is still bounded even though no single composite partition trips.
+    /// </summary>
+    [Fact]
+    public void AggregateLayer_TripsAcrossDistinctPeers()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 100, aggregateLimit: 5);
+
+        for (int peer = 0; peer < 5; peer++)
+        {
+            limiter.RecordFailure(new ApiKeyThrottlePartition($"ipv4:10.0.0.{peer}:1", "victim"));
+        }
+
+        Assert.Equal(
+            ApiKeyThrottleDecision.ThrottledByAggregate,
+            limiter.Check(new ApiKeyThrottlePartition("ipv4:10.0.9.9:1", "victim")));
+
+        // The aggregate is per key id: an unrelated key from the same fresh peer is untouched.
+        Assert.Equal(
+            ApiKeyThrottleDecision.Allowed,
+            limiter.Check(new ApiKeyThrottlePartition("ipv4:10.0.9.9:1", "other-key")));
+    }
+
+    /// <summary>
+    /// A throttled partition is a valve, not a wall: exactly one request per probe interval is
+    /// admitted to the real verifier, so the holder of the correct secret can always get through.
+    /// </summary>
+    [Fact]
+    public void ProbeAdmission_AdmitsOneRequestPerInterval()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3);
+        ApiKeyThrottlePartition partition = new("ipv4:10.0.0.1:1", "victim");
+
+        RecordFailures(limiter, partition, 3);
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(partition));
+
+        clock.Advance(ProbeInterval);
+        Assert.Equal(ApiKeyThrottleDecision.ProbeAdmitted, limiter.Check(partition));
+
+        // The granted slot is consumed: the next request inside the same interval is throttled.
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(partition));
+
+        clock.Advance(ProbeInterval);
+        Assert.Equal(ApiKeyThrottleDecision.ProbeAdmitted, limiter.Check(partition));
+    }
+
+    /// <summary>A zero probe interval restores absolute blocking (documented as not recommended).</summary>
+    [Fact]
+    public void ProbeIntervalZero_BlocksAbsolutely()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, probeInterval: TimeSpan.Zero);
+        ApiKeyThrottlePartition partition = new("ipv4:10.0.0.1:1", "victim");
+
+        RecordFailures(limiter, partition, 3);
+
+        // Well past several probe intervals but still inside the failure window: no slot opens.
+        clock.Advance(ProbeInterval + ProbeInterval + ProbeInterval);
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(partition));
+    }
+
+    /// <summary>A successful verification clears both the composite partition and the key aggregate.</summary>
+    [Fact]
+    public void Reset_ClearsCompositeAndAggregateLayers()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, aggregateLimit: 5);
+        ApiKeyThrottlePartition partition = new("ipv4:10.0.0.1:1", "victim");
+
+        RecordFailures(limiter, partition, 3);
+        for (int peer = 1; peer < 3; peer++)
+        {
+            limiter.RecordFailure(new ApiKeyThrottlePartition($"ipv4:10.0.1.{peer}:1", "victim"));
+        }
+
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(partition));
+
+        limiter.Reset(partition);
+
+        Assert.Equal(ApiKeyThrottleDecision.Allowed, limiter.Check(partition));
+        Assert.Equal(0, limiter.TrackedAggregateCount);
+        Assert.Equal(
+            ApiKeyThrottleDecision.Allowed,
+            limiter.Check(new ApiKeyThrottlePartition("ipv4:10.0.9.9:1", "victim")));
+    }
+
+    /// <summary>
+    /// SEC-32: a spray of unique junk partitions (junk tokens resolve to the sender's fallback
+    /// partition, one per address) must not evict a partition that is currently throttled — the
+    /// LRU cap bounds memory, it must not be a reset button for the block.
+    /// </summary>
+    [Fact]
+    public void JunkTokenSpray_DoesNotEvictBlockedEntry()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, maxPartitions: 8);
+        ApiKeyThrottlePartition blocked = new("ipv4:10.0.0.1:1", "victim");
+
+        RecordFailures(limiter, blocked, 3);
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(blocked));
+
+        for (int i = 0; i < 16; i++)
+        {
+            clock.Advance(TimeSpan.FromMilliseconds(1));
+            limiter.RecordFailure(new ApiKeyThrottlePartition($"ipv4:10.9.{i / 256}.{i % 256}:1", KeyId: null));
+        }
+
+        Assert.True(limiter.IsTracked(blocked));
+        Assert.Equal(ApiKeyThrottleDecision.ThrottledByPeer, limiter.Check(blocked));
+    }
+
+    /// <summary>
+    /// SEC-32: one address may mint at most <see cref="ApiKeyFailureLimiter.MaxKeyIdPartitionsPerPeer"/>
+    /// key-id partitions; the overflow collapses into that address's fallback partition, which then
+    /// throttles the address wholesale instead of letting the spray mint unbounded state.
+    /// </summary>
+    [Fact]
+    public void UniqueMxgwKeyIdSpray_FromOnePeer_CollapsesAtPerPeerCap()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, maxPartitions: 4096);
+        const string peer = "ipv4:10.0.0.1:1";
+
+        for (int i = 0; i < 1000; i++)
+        {
+            limiter.RecordFailure(new ApiKeyThrottlePartition(peer, $"key{i}"));
+        }
+
+        Assert.True(
+            limiter.TrackedPartitionCount <= ApiKeyFailureLimiter.MaxKeyIdPartitionsPerPeer + 1,
+            $"expected at most {ApiKeyFailureLimiter.MaxKeyIdPartitionsPerPeer + 1} partitions, saw {limiter.TrackedPartitionCount}");
+        Assert.Equal(
+            ApiKeyThrottleDecision.ThrottledByPeer,
+            limiter.Check(new ApiKeyThrottlePartition(peer, "key999")));
+    }
+
+    /// <summary>
+    /// SEC-32 eviction preference: with the map at capacity a new failure evicts an entry whose
+    /// window has fully expired rather than an entry that is still counting.
+    /// </summary>
+    [Fact]
+    public void Eviction_PrefersExpiredWindows()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, maxPartitions: 2);
+        ApiKeyThrottlePartition expired = new("ipv4:10.0.0.1:1", KeyId: null);
+        ApiKeyThrottlePartition active = new("ipv4:10.0.0.2:1", KeyId: null);
+        ApiKeyThrottlePartition arriving = new("ipv4:10.0.0.3:1", KeyId: null);
+
+        limiter.RecordFailure(expired);
+        clock.Advance(Window + TimeSpan.FromSeconds(1));
+        limiter.RecordFailure(active);
+        limiter.RecordFailure(arriving);
+
+        Assert.Equal(2, limiter.TrackedPartitionCount);
+        Assert.False(limiter.IsTracked(expired));
+        Assert.True(limiter.IsTracked(active));
+        Assert.True(limiter.IsTracked(arriving));
+    }
+
+    private static void RecordFailures(ApiKeyFailureLimiter limiter, ApiKeyThrottlePartition partition, int count)
+    {
+        for (int i = 0; i < count; i++)
+        {
+            limiter.RecordFailure(partition);
+        }
+    }
+
+    private static ApiKeyFailureLimiter CreateLimiter(
+        TimeProvider clock,
+        int limit,
+        int aggregateLimit = 0,
+        int maxPartitions = 1024,
+        TimeSpan? probeInterval = null)
+    {
+        return new ApiKeyFailureLimiter(
+            limit,
+            Window,
+            maxPartitions,
+            aggregateLimit,
+            probeInterval ?? ProbeInterval,
+            clock);
+    }
+}

src/ZB.MOM.WW.MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs

@@ -22,6 +22,12 @@ namespace ZB.MOM.WW.MxGateway.Tests.Security.Authorization;
 
 public sealed class GatewayGrpcAuthorizationInterceptorTests
 {
+    private const string AttackerPeer = "ipv4:203.0.113.7:5000";
+    private const string HolderPeer = "ipv4:198.51.100.4:5000";
+
+    private static readonly TimeSpan FailureWindow = TimeSpan.FromMinutes(1);
+    private static readonly TimeSpan ProbeInterval = TimeSpan.FromSeconds(5);
+
     /// <summary>Verifies that missing API key returns unauthenticated status.</summary>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
@@ -359,21 +365,18 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
     }
 
     /// <summary>
-    /// Once a peer has exceeded the failure limit, the interceptor short-circuits with
-    /// <see cref="StatusCode.ResourceExhausted"/> BEFORE calling the verifier, so an online guessing
-    /// loop stops spending a store read per attempt. A verifier that always fails is used; after the
-    /// limit is reached the verifier is no longer invoked.
+    /// SEC-31: once an attacking peer has exceeded the failure limit for a key id, the interceptor
+    /// short-circuits with <see cref="StatusCode.ResourceExhausted"/> BEFORE calling the verifier, so
+    /// an online guessing loop stops spending a store read per attempt. The composite
+    /// <c>(peer, key id)</c> partition keeps that bound per attacking address.
     /// </summary>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
-    public async Task UnaryServerHandler_ExceedsFailureLimit_ShortCircuitsBeforeVerify()
+    public async Task BruteForceBound_StillEnforcedPerAttackingPeer()
     {
         CountingFailureVerifier verifier = new(Failure(ApiKeyFailure.SecretMismatch));
-        ApiKeyFailureLimiter limiter = new(
-            limit: 3,
-            window: TimeSpan.FromMinutes(1),
-            maxPeers: 16,
-            clock: TimeProvider.System);
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3);
         GatewayGrpcAuthorizationInterceptor interceptor = CreateInterceptor(
             verifier,
             new GatewayRequestIdentityAccessor(),
@@ -385,7 +388,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
             RpcException failure = await Assert.ThrowsAsync<RpcException>(
                 () => interceptor.UnaryServerHandler(
                     new OpenSessionRequest(),
-                    ContextWithAuthorization("Bearer mxgw_operator01_bad-secret"),
+                    ContextWithAuthorization("Bearer mxgw_operator01_bad-secret", AttackerPeer),
                     (_, _) => Task.FromResult(new OpenSessionReply())));
             Assert.Equal(StatusCode.Unauthenticated, failure.StatusCode);
         }
@@ -396,13 +399,219 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
         RpcException throttled = await Assert.ThrowsAsync<RpcException>(
             () => interceptor.UnaryServerHandler(
                 new OpenSessionRequest(),
-                ContextWithAuthorization("Bearer mxgw_operator01_bad-secret"),
+                ContextWithAuthorization("Bearer mxgw_operator01_bad-secret", AttackerPeer),
                 (_, _) => Task.FromResult(new OpenSessionReply())));
 
         Assert.Equal(StatusCode.ResourceExhausted, throttled.StatusCode);
         Assert.Equal(3, verifier.CallCount);
     }
 
+    /// <summary>
+    /// SEC-31 (the lockout inversion): an attacker who floods failures for a victim's key id from its
+    /// own address must not deny that key to the legitimate holder. The holder presents the correct
+    /// secret from a different transport peer and authenticates on the first attempt — the verifier
+    /// is reached and the RPC succeeds.
+    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Fact]
+    public async Task AttackerSpamOnVictimKeyId_FromDifferentPeer_DoesNotBlockLegitimateHolderPresentingCorrectSecret()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, aggregateLimit: 30);
+        GatewayGrpcAuthorizationInterceptor attacked = CreateInterceptor(
+            new CountingFailureVerifier(Failure(ApiKeyFailure.SecretMismatch)),
+            new GatewayRequestIdentityAccessor(),
+            failureLimiter: limiter);
+
+        // Flood the victim's key id from the attacker's address until that partition is throttled.
+        StatusCode lastAttackerStatus = StatusCode.OK;
+        for (int attempt = 0; attempt < 6; attempt++)
+        {
+            RpcException failure = await Assert.ThrowsAsync<RpcException>(
+                () => attacked.UnaryServerHandler(
+                    new OpenSessionRequest(),
+                    ContextWithAuthorization("Bearer mxgw_operator01_guess", AttackerPeer),
+                    (_, _) => Task.FromResult(new OpenSessionReply())));
+            lastAttackerStatus = failure.StatusCode;
+        }
+
+        Assert.Equal(StatusCode.ResourceExhausted, lastAttackerStatus);
+
+        // The legitimate holder, on a different address, is verified and admitted immediately.
+        FakeApiKeyVerifier holderVerifier = new(SuccessWithScopes(GatewayScopes.SessionOpen));
+        GatewayGrpcAuthorizationInterceptor holder = CreateInterceptor(
+            holderVerifier,
+            new GatewayRequestIdentityAccessor(),
+            failureLimiter: limiter);
+
+        OpenSessionReply reply = await holder.UnaryServerHandler(
+            new OpenSessionRequest(),
+            ContextWithAuthorization("Bearer mxgw_operator01_correct", HolderPeer),
+            (_, _) => Task.FromResult(new OpenSessionReply { SessionId = "session-1" }));
+
+        Assert.True(holderVerifier.WasCalled);
+        Assert.Equal("session-1", reply.SessionId);
+    }
+
+    /// <summary>
+    /// SEC-31 layer 2: failures for one key id sprayed across more distinct peers than
+    /// <c>ApiKeyFailureAggregateLimit</c> put that key id into probe mode globally, so a
+    /// rotating-source attacker gets at most one verifier call per probe interval.
+    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Fact]
+    public async Task AggregateSpray_AcrossManyPeers_TripsPerKeyProbeMode()
+    {
+        CountingFailureVerifier verifier = new(Failure(ApiKeyFailure.SecretMismatch));
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 100, aggregateLimit: 5);
+        GatewayGrpcAuthorizationInterceptor interceptor = CreateInterceptor(
+            verifier,
+            new GatewayRequestIdentityAccessor(),
+            failureLimiter: limiter);
+
+        for (int peer = 0; peer < 5; peer++)
+        {
+            await Assert.ThrowsAsync<RpcException>(
+                () => interceptor.UnaryServerHandler(
+                    new OpenSessionRequest(),
+                    ContextWithAuthorization("Bearer mxgw_operator01_guess", $"ipv4:10.9.0.{peer}:5000"),
+                    (_, _) => Task.FromResult(new OpenSessionReply())));
+        }
+
+        Assert.Equal(5, verifier.CallCount);
+
+        // A never-seen peer is now probe-limited: no composite failures of its own, but the key id's
+        // aggregate is tripped, so the request never reaches the verifier.
+        RpcException throttled = await Assert.ThrowsAsync<RpcException>(
+            () => interceptor.UnaryServerHandler(
+                new OpenSessionRequest(),
+                ContextWithAuthorization("Bearer mxgw_operator01_guess", "ipv4:10.9.1.1:5000"),
+                (_, _) => Task.FromResult(new OpenSessionReply())));
+
+        Assert.Equal(StatusCode.ResourceExhausted, throttled.StatusCode);
+        Assert.Equal(5, verifier.CallCount);
+
+        // One probe slot opens per interval, and it is consumed by the first arrival.
+        clock.Advance(ProbeInterval);
+
+        RpcException probed = await Assert.ThrowsAsync<RpcException>(
+            () => interceptor.UnaryServerHandler(
+                new OpenSessionRequest(),
+                ContextWithAuthorization("Bearer mxgw_operator01_guess", "ipv4:10.9.1.2:5000"),
+                (_, _) => Task.FromResult(new OpenSessionReply())));
+
+        Assert.Equal(StatusCode.Unauthenticated, probed.StatusCode);
+        Assert.Equal(6, verifier.CallCount);
+
+        RpcException throttledAgain = await Assert.ThrowsAsync<RpcException>(
+            () => interceptor.UnaryServerHandler(
+                new OpenSessionRequest(),
+                ContextWithAuthorization("Bearer mxgw_operator01_guess", "ipv4:10.9.1.3:5000"),
+                (_, _) => Task.FromResult(new OpenSessionReply())));
+
+        Assert.Equal(StatusCode.ResourceExhausted, throttledAgain.StatusCode);
+        Assert.Equal(6, verifier.CallCount);
+    }
+
+    /// <summary>
+    /// SEC-31: the success-reset path stays reachable while throttled. A throttled partition admits
+    /// one probe per interval; the correct secret rides that slot, authenticates, and fully clears
+    /// both limiter layers, so the next wrong attempt is <see cref="StatusCode.Unauthenticated"/>
+    /// rather than <see cref="StatusCode.ResourceExhausted"/>.
+    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Fact]
+    public async Task CorrectSecret_DuringProbeMode_AuthenticatesViaProbeSlotAndResets()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 3, aggregateLimit: 30);
+        GatewayGrpcAuthorizationInterceptor failing = CreateInterceptor(
+            new FakeApiKeyVerifier(Failure(ApiKeyFailure.SecretMismatch)),
+            new GatewayRequestIdentityAccessor(),
+            failureLimiter: limiter);
+        FakeApiKeyVerifier holderVerifier = new(SuccessWithScopes(GatewayScopes.SessionOpen));
+        GatewayGrpcAuthorizationInterceptor succeeding = CreateInterceptor(
+            holderVerifier,
+            new GatewayRequestIdentityAccessor(),
+            failureLimiter: limiter);
+
+        for (int attempt = 0; attempt < 3; attempt++)
+        {
+            await Assert.ThrowsAsync<RpcException>(
+                () => failing.UnaryServerHandler(
+                    new OpenSessionRequest(),
+                    ContextWithAuthorization("Bearer mxgw_operator01_bad", HolderPeer),
+                    (_, _) => Task.FromResult(new OpenSessionReply())));
+        }
+
+        RpcException throttled = await Assert.ThrowsAsync<RpcException>(
+            () => failing.UnaryServerHandler(
+                new OpenSessionRequest(),
+                ContextWithAuthorization("Bearer mxgw_operator01_bad", HolderPeer),
+                (_, _) => Task.FromResult(new OpenSessionReply())));
+        Assert.Equal(StatusCode.ResourceExhausted, throttled.StatusCode);
+
+        clock.Advance(ProbeInterval);
+
+        OpenSessionReply reply = await succeeding.UnaryServerHandler(
+            new OpenSessionRequest(),
+            ContextWithAuthorization("Bearer mxgw_operator01_correct", HolderPeer),
+            (_, _) => Task.FromResult(new OpenSessionReply { SessionId = "session-1" }));
+
+        Assert.True(holderVerifier.WasCalled);
+        Assert.Equal("session-1", reply.SessionId);
+
+        RpcException afterReset = await Assert.ThrowsAsync<RpcException>(
+            () => failing.UnaryServerHandler(
+                new OpenSessionRequest(),
+                ContextWithAuthorization("Bearer mxgw_operator01_bad", HolderPeer),
+                (_, _) => Task.FromResult(new OpenSessionReply())));
+
+        Assert.Equal(StatusCode.Unauthenticated, afterReset.StatusCode);
+    }
+
+    /// <summary>
+    /// SEC-32: only a validly shaped <c>mxgw_&lt;keyId&gt;_&lt;secret&gt;</c> token mints a key-id
+    /// partition. Junk tokens of varied shapes all collapse onto the sender's transport-peer fallback
+    /// partition, so a spray cannot mint one tracked entry per invented token.
+    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    [Fact]
+    public async Task NonMxgwToken_FallsBackToTransportPeerPartition()
+    {
+        ManualTimeProvider clock = new(DateTimeOffset.UnixEpoch);
+        ApiKeyFailureLimiter limiter = CreateLimiter(clock, limit: 1000);
+        GatewayGrpcAuthorizationInterceptor interceptor = CreateInterceptor(
+            new FakeApiKeyVerifier(Failure(ApiKeyFailure.MissingOrMalformed)),
+            new GatewayRequestIdentityAccessor(),
+            failureLimiter: limiter);
+
+        string[] junkTokens =
+        [
+            "Bearer garbage",
+            "Bearer a_b_c",
+            "Bearer notmxgw_operator01_secret",
+            "Bearer MXGW_operator01_secret",
+            "Bearer mxgw__secret",
+            "Bearer mxgw_operator01_",
+            "Bearer mxgw_" + new string('k', 65) + "_secret",
+            "Bearer mxgw_onlytwo",
+        ];
+
+        foreach (string token in junkTokens)
+        {
+            await Assert.ThrowsAsync<RpcException>(
+                () => interceptor.UnaryServerHandler(
+                    new OpenSessionRequest(),
+                    ContextWithAuthorization(token, AttackerPeer),
+                    (_, _) => Task.FromResult(new OpenSessionReply())));
+        }
+
+        Assert.Equal(1, limiter.TrackedPartitionCount);
+        Assert.True(limiter.IsTracked(new ApiKeyThrottlePartition(AttackerPeer, KeyId: null)));
+    }
+
     /// <summary>
     /// A successful verification resets the peer's failure counter, so accumulated failures
     /// from a fat-fingered secret do not lock out a client that subsequently authenticates.
@@ -411,11 +620,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
     [Fact]
     public async Task UnaryServerHandler_SuccessResetsFailureCounter()
     {
-        ApiKeyFailureLimiter limiter = new(
-            limit: 3,
-            window: TimeSpan.FromMinutes(1),
-            maxPeers: 16,
-            clock: TimeProvider.System);
+        ApiKeyFailureLimiter limiter = CreateLimiter(new ManualTimeProvider(DateTimeOffset.UnixEpoch), limit: 3);
 
         // Two failures against the same key id, then a success (which resets), then two more
         // failures — without the reset the fifth attempt would be blocked at the limit of 3.
@@ -487,11 +692,23 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
                     Mode = authenticationMode
                 }
             }),
-            failureLimiter ?? new ApiKeyFailureLimiter(
-                limit: 1000,
-                window: TimeSpan.FromMinutes(1),
-                maxPeers: 1000,
-                clock: TimeProvider.System));
+            failureLimiter ?? CreateLimiter(TimeProvider.System, limit: 1000),
+            new GatewayMetrics());
+    }
+
+    private static ApiKeyFailureLimiter CreateLimiter(
+        TimeProvider clock,
+        int limit,
+        int aggregateLimit = 0,
+        int maxPartitions = 1024)
+    {
+        return new ApiKeyFailureLimiter(
+            limit,
+            FailureWindow,
+            maxPartitions,
+            aggregateLimit,
+            ProbeInterval,
+            clock);
     }
 
     private static ApiKeyVerification SuccessWithScopes(params string[] scopes)
@@ -511,9 +728,11 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
         return new ApiKeyVerification(Succeeded: false, Identity: null, Failure: failure);
     }
 
-    private static TestServerCallContext ContextWithAuthorization(string authorizationHeader)
+    private static TestServerCallContext ContextWithAuthorization(string authorizationHeader, string? peer = null)
     {
-        return new TestServerCallContext([new Metadata.Entry("authorization", authorizationHeader)]);
+        return new TestServerCallContext(
+            [new Metadata.Entry("authorization", authorizationHeader)],
+            peer: peer);
     }
 
     /// <summary>Records whether the gateway service ran past the interceptor for composition tests.</summary>

src/ZB.MOM.WW.MxGateway.Tests/TestSupport/TestServerCallContext.cs

@@ -8,20 +8,32 @@ namespace ZB.MOM.WW.MxGateway.Tests.TestSupport;
 /// </summary>
 public sealed class TestServerCallContext : ServerCallContext
 {
+    private const string DefaultPeer = "ipv4:127.0.0.1:5000";
+
     private readonly Metadata _requestHeaders;
     private readonly Metadata _responseTrailers = [];
     private readonly Dictionary<object, object> _userState = [];
     private readonly CancellationToken _cancellationToken;
+    private readonly string _peer;
     private Status _status;
     private WriteOptions? _writeOptions;
 
     /// <summary>Initializes the context with the supplied request headers and cancellation token.</summary>
     /// <param name="requestHeaders">Request headers visible to the service; defaults to empty.</param>
     /// <param name="cancellationToken">Cancellation token surfaced to the service.</param>
-    public TestServerCallContext(Metadata? requestHeaders = null, CancellationToken cancellationToken = default)
+    /// <param name="peer">
+    /// Transport peer address surfaced as <see cref="ServerCallContext.Peer"/>; defaults to a
+    /// loopback address. Tests that exercise per-peer partitioning (for example the API-key failure
+    /// limiter) pass distinct values to model separate network sources.
+    /// </param>
+    public TestServerCallContext(
+        Metadata? requestHeaders = null,
+        CancellationToken cancellationToken = default,
+        string? peer = null)
     {
         _requestHeaders = requestHeaders ?? [];
         _cancellationToken = cancellationToken;
+        _peer = peer ?? DefaultPeer;
     }
 
     /// <inheritdoc />
@@ -31,7 +43,7 @@ public sealed class TestServerCallContext : ServerCallContext
     protected override string HostCore => "localhost";
 
     /// <inheritdoc />
-    protected override string PeerCore => "ipv4:127.0.0.1:5000";
+    protected override string PeerCore => _peer;
 
     /// <inheritdoc />
     protected override DateTime DeadlineCore => DateTime.UtcNow.AddMinutes(1);