Milestone 2.2.1 — Auth Cache: Bloom Filter + In-Process LRU (Performance Critical Path)

Status: Completed
Goal: 2.2 — Auth performance cache
Phase: 2 — Single Provider End-to-End
Estimated effort: 3–4 days
ADR: ADR-0028 — Auth cache design

Why This Milestone Exists

The Phase 1 proxy makes a synchronous gRPC call to the auth service on every protected request. That call has a 50ms budget and in practice takes 2–10ms under normal load — already a large share of the 20ms proxy overhead budget.

The solution is a two-tier in-process cache in front of the gRPC call:

Tier 1 — Invalid-token bloom: Probabilistic set of recently rejected token hashes. Test==true skips the LRU and calls gRPC (false positives fall through; valid tokens are never added to the bloom).

Tier 2 — Claims LRU: Bounded cache of validated claims. On hit, gRPC is skipped. TTL is min(30s, token.expires_at - now - 5s).

Revocation lag: Without pub/sub, a revoked token may be served from LRU for up to 30 seconds (LRUMaxTTL). Goal 2.2’s “revoke ≤5s” exit gate requires 2.2.2 (ADR-0029).

Non-Goals

• RedisBloom / distributed LRU
• Negative entry cache beyond the invalid-token bloom
• Pub/sub revocation (2.2.2)
• Agent validation cache
• Meeting the 5s revoke exit gate in this milestone alone

Branch

feature/m2-2-1-auth-cache-bloom

PR Title

feat(proxy): auth cache — bloom filter + in-process LRU for token validation (m2.2.1)

Deliverables

1. packages/authcache

CachingValidator with bloom of invalids, claims LRU, TokenHash, and synchronous Invalidate(tokenHash).

2. Metrics (packages/metrics)

ibex_proxy_auth_cache_hits_total{tier="lru"}
ibex_proxy_auth_cache_misses_total{tier="lru"|"bloom"}
ibex_proxy_auth_cache_lru_size
ibex_proxy_auth_cache_lru_evictions_total
ibex_proxy_auth_cache_bloom_fp_total

3. Proxy wire-up

Config IBEX_AUTH_CACHE_*, decorator in setupAuthClients, X-IBEX-Auth-Cached: true on LRU hits.

Testing Requirements

• TestCachingValidator_LRUHit / LRUTTLExpiry / Invalidate / BloomFalsePositive / UpstreamDown_FailsClosed
• BenchmarkCachingValidator_LRUHit (local <100µs target; not a CI hard gate)
• Proxy adapter + middleware header coverage

Acceptance Criteria

• LRU hit path requires zero network calls
• LRU miss falls through to gRPC
• Invalidate removes token from LRU synchronously
• Cache metrics exported via packages/metrics
• Bloom FP rate 0.1% documented; FP path tested
• Token hash (not raw token) is the cache key
• ADR-0028 written and indexed
• Docs state revoke lag bound = 30s until 2.2.2