Module internal_auth_cache 

TTL-bounded caching for platform-plane validation. Short-lived positive (and brief negative) caching for platform-plane authentication.

CachingInternalAuthenticator wraps any InternalAuthenticator with an in-memory, TTL-bounded cache. It exists because a remote validation backend (e.g. the Kubernetes TokenReview API) performs a live round-trip on every call — untenable on a hot gRPC/HTTP path where the same projected credential is presented on back-to-back requests (cpt-cf-adr-platform-plane-auth, decision 5).

Semantics

• Successful validations are cached for up to ttl, clamped to the credential’s own remaining validity when it is a JWT carrying an exp claim (see [jwt_exp_claim]) — a token with two seconds left is never cached for the full configured ttl.
• Rejections (InternalAuthNError::InvalidToken) are cached for a short, fixed [NEGATIVE_CACHE_TTL] so a caller presenting no valid credential cannot drive one backend round-trip per request, while a token that becomes valid moments later is re-checked quickly.
• Backend failures (InternalAuthNError::Unavailable, Other) are never cached: a transient outage is re-evaluated on the next call.
• Concurrent misses for the same token are serialized behind a per-token lock (single-flight), so a burst of calls carrying the same credential collapses into one backend round-trip instead of N.
• The cache key is a SHA-256 digest of the token, so no map here holds the credential itself and an entry costs the same whatever the token’s length. A cryptographic digest rather than a fast hash because the input is a credential: a collision would let one token answer for another.
• The cache holds at most [MAX_CACHE_ENTRIES] distinct tokens. When full, a single sweep reclaims any expired entries first (amortizing across the inserts it makes room for); only if nothing is reclaimable — a burst of distinct, individually-valid credentials — does it evict the entry expiring soonest, rather than growing unbounded.

Structs

CachingInternalAuthenticator

Wraps an InternalAuthenticator with a short-lived cache of both successful and rejected validations.

InvalidCacheTtl

ttl passed to CachingInternalAuthenticator::new was zero or exceeded MAX_TOKEN_REVIEW_CACHE_TTL.

Constants

DEFAULT_AUTHENTICATION_TIMEOUT

Default deadline for the whole InternalAuthenticator::authenticate call, overridable per instance with CachingInternalAuthenticator::with_authentication_timeout.

DEFAULT_TOKEN_REVIEW_CACHE_TTL

Default time-to-live for a cached successful validation.

MAX_CACHE_ENTRIES

Maximum number of distinct tokens held at once, bounding memory even under a sustained burst of distinct, individually-valid credentials (which TTL expiry alone never reclaims). Generous enough for realistic fleets of Kubernetes ServiceAccounts calling through a single authenticator instance.

MAX_TOKEN_REVIEW_CACHE_TTL

Upper bound accepted by CachingInternalAuthenticator::new. Caps how long a revoked or expired token can keep validating from cache, so a misconfiguration cannot widen the revocation window unboundedly.