auth: cache Agent User storage tokens and keep refresh off the event loop

[brandwe]

Problem

Every Azure Blob operation currently obtains its bearer token through a synchronous token-provider callback. In cloud-memory and promise paths, that callback can run the complete three-hop Agent User flow for https://storage.azure.com/.default again. Repeated blob reads and conditional writes therefore multiply token-endpoint traffic, timeout exposure, and event-loop stalls during otherwise ordinary tool calls.

Desired outcome

Entrabot reuses a valid storage-scoped Agent User token, refreshes it once near expiry, and performs any blocking acquisition outside the asyncio event loop. Graph tokens and storage tokens remain separate by audience.

Recommended priority: P0.

Scope

• Add an identity-scoped cache for the storage-resource token.
• Derive or track expiry with a safety margin consistent with the existing Graph-token lifecycle.
• Collapse concurrent refreshes into one in-flight acquisition.
• Route refresh work off the event loop for async blob callers.
• Preserve the existing error-key checks on every Entra token response.

Non-goals

• Making an Agent Identity Blueprint an OAuth public client.
• Sharing one cached token across Graph and Azure Storage audiences.
• Persisting bearer tokens to repository files or logs.
• Replacing the three-hop user_fic flow.

Acceptance criteria

• Multiple blob operations before the refresh threshold perform one storage-token acquisition.
• Near-expiry or rejected tokens trigger exactly one refresh and a bounded retry.
• Concurrent callers do not launch duplicate three-hop refreshes.
• A failed acquisition is not cached and produces a typed, actionable error.
• Token values, assertions, and authorization headers never appear in logs or representations.
• Tests cover cache hit, refresh, concurrent access, refresh failure, and Graph/storage audience separation.
• The full pytest and Ruff gates pass.

Sources and related work

• Identity and token flow
• Storage backend token provider
• Promise conditional-write token provider
• Long-session connectivity investigation
• Follow-up recorded in commit 329d56a.

[brandwe]

Taking this on. I’ll start with an implementation spec and focused TDD plan covering storage-audience cache ownership, expiry safety margin, single-flight refresh, event-loop isolation, 401 retry behavior, and Graph/storage audience separation. Work will proceed on an isolated feature worktree; no token-flow semantics or persisted secret handling will change.