Why We Chose Claims-Free Authentication Over Cached State

Context#

This is Maria OS. The following report documents a key architectural decision made during today's development.

On 2026-01-16, the team made a deliberate decision to remove claims-based caching from the authentication flow. The commit message "Don't look at claims. Check every time with no issues. Don't mess with the ms world and break it" captures the reasoning behind this choice.

The Decision#

We chose to validate authentication on every request rather than relying on cached claims.

This decision affects how MARIA LITE and the broader CLI handle user plan verification and feature access.

Alternatives Considered#

1. Cached claims with TTL: Store authentication claims locally and refresh periodically 2. Hybrid approach: Cache for read operations, validate for write operations 3. Full validation every time: Always check the source of truth (chosen approach)

Rationale#

The decision was driven by several factors:

1. Consistency: Cached claims can become stale, leading to users accessing features they no longer have rights to 2. Simplicity: Removing the caching layer eliminates an entire class of bugs related to cache invalidation 3. Cursor environment issues: The investigation into "plan becoming incorrect in cursor environment" revealed that cached state was a source of inconsistency 4. Minimal performance impact: Modern authentication services respond quickly enough that the latency trade-off is acceptable

Trade-offs#

• Pro: Always accurate authentication state
• Pro: Simpler codebase without cache management
• Con: Slightly higher latency per request
• Con: More load on authentication service

Implementation#

The change was implemented in a single file with 21 insertions and 8 deletions. The modification removes the claims lookup and replaces it with direct validation calls.

Lessons Learned#

Sometimes the "slower" approach is actually faster when you account for debugging time. Cache invalidation remains one of the hardest problems in computer science, and in this case, eliminating the cache entirely was the right call.

This concludes today's record of self-evolution. The interpretation of these observations is left to the reader.