Add optional cross-process coordination for OAuth token refreshes #211

Summary

Add optional shared cross-process coordination for OAuth token refreshes. Requested by @KomanRudden as a follow-up to PR #210.

Rationale

PR #210 reads persisted session tokens before refreshing an expired access token. This lets a worker adopt tokens that another worker has already saved. It does not coordinate simultaneous refreshes.

TokenManager uses an instance RLock, which only coordinates threads using that instance. Two processes can read the same token snapshot, refresh concurrently, and overwrite the saved token snapshot. The current behavior relies on Kinde's refresh-token rotation overlap period.

Shared cross-process refresh coordination is explicitly outside the scope of PR #210.

Required changes

• Define an optional coordination interface backed by shared infrastructure, such as Redis. Do not treat the instance RLock as a cross-process lock.
• Scope coordination to the stored session and its storage namespace.
• Acquire coordination before refreshing, then reload persisted tokens inside the coordinated section.
• If another worker has already saved a valid access token, adopt it without another refresh request. Otherwise, refresh with the latest persisted refresh token.
• Keep refresh and persistence coordinated so a concurrent or stale writer cannot overwrite a newer token snapshot. Account for lock lease expiry if the backend uses leases.
• Define bounded wait, failure, and worker-crash recovery behavior.
• Document configuration, backend requirements, and the remaining behavior when coordination is not configured.
• Keep token values out of logs.

Affected areas

• kinde_sdk/auth/token_manager.py: persisted-token adoption and refresh flow.
• kinde_sdk/auth/user_session.py: session loading and refreshed-token persistence.
• kinde_sdk/core/storage/storage_manager.py: storage integration and coordination interface.
• testv2/testv2_auth/test_token_refresh.py: refresh and persistence regression coverage.

Acceptance criteria

• A deterministic concurrent-worker test shows that two workers refreshing the same expired session do not both refresh the same token snapshot.
• A waiting worker adopts the tokens saved by the worker that completed the refresh.
• A stale writer cannot overwrite newer persisted tokens.
• Different sessions can refresh independently.
• Tests cover coordination timeout, backend failure, worker failure, and lease expiry where applicable.
• Existing single-process behavior remains compatible when coordination is not configured.
• Documentation clearly separates persisted-token adoption from cross-process synchronization.

References

• PR: fix(auth): make token refresh and session restore work #210
• Review discussion and follow-up request: fix(auth): make token refresh and session restore work #210 (comment)