docs: strip task-tracking IDs from code comments and fill missing XML docs
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m16s
ci / java (push) Successful in 2m5s
ci / portable (push) Failing after 5m9s

Tracking IDs are review bookkeeping that rots in shipped source; the rationale they tagged is kept. Comment-only change (CommentChecker 458 -> 16 false positives).
This commit is contained in:
Joseph Doherty
2026-10-07 15:34:32 -04:00
parent f2e0861709
commit f40409a688
115 changed files with 549 additions and 411 deletions
@@ -238,6 +238,7 @@ public sealed class ApiKeyAdminCommandLineParserTests
/// Verifies an empty tag segment is rejected rather than dropped: a stray comma must not
/// silently persist a grant the operator did not write.
/// </summary>
/// <param name="tags">The raw dashboard tag list containing an empty segment.</param>
[Theory]
[InlineData("team-a,,team-b")]
[InlineData("team-a, ")]
@@ -100,7 +100,7 @@ public sealed class CachingApiKeyVerifierTests
}
/// <summary>
/// SEC-34 window 3: an <see cref="IApiKeyCacheInvalidator.Invalidate"/> that lands while a
/// Window 3: an <see cref="IApiKeyCacheInvalidator.Invalidate"/> that lands while a
/// verification is in flight in the inner library must discard that verification's repopulation,
/// so the very next request re-verifies (revoke takes effect immediately, not after the TTL).
/// </summary>
@@ -4,7 +4,7 @@ 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
/// Unit tests for the two-layer API-key failure limiter: 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>
@@ -58,7 +58,7 @@ public sealed class ApiKeyFailureLimiterTests
/// <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.
/// from a different transport peer is unaffected. This is the structural half of the per-address throttle.
/// </summary>
[Fact]
public void CompositePartition_ThrottleDoesNotFollowKeyIdToAnotherPeer()
@@ -102,7 +102,7 @@ public sealed class ApiKeyFailureLimiterTests
}
/// <summary>
/// SEC-38: a valid key id still feeds and consults its cross-peer aggregate when each
/// A valid key id still feeds and consults its cross-peer aggregate when each
/// attacking peer has exhausted its 32 dedicated key-id partitions and therefore records
/// the peer layer through the fallback bucket.
/// </summary>
@@ -372,7 +372,7 @@ public sealed class ApiKeyFailureLimiterTests
}
/// <summary>
/// SEC-39: a request with no effective key id does not own the peer's shared fallback
/// A request with no effective key id does not own the peer's shared fallback
/// partition. Resetting after such a request must leave other fallback failures tracked.
/// </summary>
[Fact]
@@ -395,7 +395,7 @@ public sealed class ApiKeyFailureLimiterTests
}
/// <summary>
/// SEC-32: a spray of unique junk partitions (junk tokens resolve to the sender's fallback
/// 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>
@@ -420,7 +420,7 @@ public sealed class ApiKeyFailureLimiterTests
}
/// <summary>
/// SEC-32: one address may mint at most <see cref="ApiKeyFailureLimiter.MaxKeyIdPartitionsPerPeer"/>
/// 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>
@@ -445,7 +445,7 @@ public sealed class ApiKeyFailureLimiterTests
}
/// <summary>
/// SEC-32 eviction preference: with the map at capacity a new failure evicts an entry whose
/// 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]
@@ -32,8 +32,8 @@ public sealed class GatewayBrowseScopeProviderTests
/// <summary>
/// An authenticated key with no BrowseSubtrees constraint is legitimately unscoped: the
/// empty list is what the library reads as "no scoping". This is the state GWC-38 required
/// to stay distinguishable from an absent identity, so it is asserted alongside its
/// empty list is what the library reads as "no scoping". This is the state that must
/// stay distinguishable from an absent identity, so it is asserted alongside its
/// denying twin below rather than left implicit.
/// </summary>
[Fact]
@@ -49,7 +49,7 @@ public sealed class GatewayBrowseScopeProviderTests
}
/// <summary>
/// GWC-38: with API-key authentication enabled, an absent ambient identity means the
/// With API-key authentication enabled, an absent ambient identity means the
/// interceptor-ordering invariant is broken — the request's browse scope cannot be
/// established. The provider must DENY rather than resolve to the full hierarchy, because
/// a silently-unscoped browse is an invisible authorization bypass. The status code is
@@ -365,7 +365,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
}
/// <summary>
/// SEC-31: once an attacking peer has exceeded the failure limit for a key id, the interceptor
/// 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.
@@ -407,7 +407,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
}
/// <summary>
/// SEC-31 (the lockout inversion): an attacker who floods failures for a victim's key id from its
/// 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.
@@ -454,7 +454,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
}
/// <summary>
/// SEC-31 layer 2: failures for one key id sprayed across more distinct peers than
/// 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>
@@ -515,7 +515,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
}
/// <summary>
/// SEC-31: the success-reset path stays reachable while throttled. A throttled partition admits
/// 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"/>.
@@ -572,7 +572,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
}
/// <summary>
/// SEC-32: only a validly shaped <c>mxgw_&lt;keyId&gt;_&lt;secret&gt;</c> token mints a key-id
/// 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>