flip_api.auth.trust_key_cache

In-process TTL cache for trust API-key → trust_id lookups.

authenticate_trust (auth/access_manager.py) defends against timing oracles by sweeping every hash-bearing trust row with hmac.compare_digest on each request. With 30/min /tasks/pending plus 30/min /trust/heartbeat per trust, that is an O(N) DB walk on every request in steady state — and the sweep duration leaks the trust count to a pre-auth probe.

This cache shortens the hot path to a single primary-key fetch + one constant-time compare. Verification still runs against the live row, so a deleted or soft-disabled trust falls through to the full sweep (which filters them out) and returns 401 normally; the cache cannot grant access that the database denies.

Invalidation: callers that commit a write to the trust table (register_trust, soft-disable when wired up, delete_trust) should call invalidate() after commit. Cross-process eviction is not provided — the 60-second TTL bounds the staleness window across Fargate tasks. The verify-against-the-live-row step is what makes this safe: stale entries cost an extra DB round-trip on the request that races a write, never an authentication bypass.

Attributes

`_TTL_SECONDS`
`_lock`
`_cache`

Functions

`lookup`(→ uuid.UUID \| None)	Return the cached trust id for this hash, or None if absent or expired.
`remember`(→ None)	Record that this hash resolved to this trust id; entry lasts for the TTL.
`invalidate`(→ None)	Drop every cache entry. Call after register/disable/delete commits.

Module Contents

flip_api.auth.trust_key_cache._TTL_SECONDS = 60

flip_api.auth.trust_key_cache._lock

flip_api.auth.trust_key_cache._cache: dict[str, tuple[uuid.UUID, float]]

flip_api.auth.trust_key_cache.lookup(api_key_hash: str) → uuid.UUID | None[source]

Return the cached trust id for this hash, or None if absent or expired.

Parameters:: api_key_hash (str) – SHA-256 hex digest of the candidate API key.
Returns:: Trust id last seen for this hash, or None.
Return type:: UUID | None

flip_api.auth.trust_key_cache.remember(api_key_hash: str, trust_id: uuid.UUID) → None[source]

Record that this hash resolved to this trust id; entry lasts for the TTL.

Parameters:

api_key_hash (str) – SHA-256 hex digest of the API key the request carried.
trust_id (UUID) – Primary key of the matching trust row.

flip_api.auth.trust_key_cache.invalidate() → None[source]: Drop every cache entry. Call after register/disable/delete commits.