Fix FwLite OAuth: stop wiping refresh-token cache on transient errors

[myieye]

Resolves #2306 — root-cause analysis lives there. This PR fixes all three client-side causes:

• Transient/unknown errors during silent refresh no longer wipe the MSAL account (only MsalUiRequired / multiple_matching_tokens log out), and a still-valid access token survives a transient refresh failure instead of being discarded.
• GetAuth is serialized (semaphore + double-check) so concurrent force-refreshes can''t trip rolling-RT replay detection; Logout takes the same lock so an in-flight refresh can''t sign the user back in; auth events publish after the lock is released.
• FwLiteWeb''s MSAL cache moved to a stable per-user location with a one-time migration off the Platform.Bible-versioned binary directory.

Supporting change: IsSignedIn (local-only cache read) lets sync/status report a new Offline error code instead of a misleading not-logged-in state.

Verified end-to-end with FW_LITE_CHAOS=true and a 30s token lifetime: 50/50 forced refreshes stayed signed in; reverting cause 1 logged the user out by poll #10. The remaining known logout cause (production cert rotation) is #2332.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors OAuthClient to add semaphore-guarded concurrency control and explicit MSAL error classification, preventing transient failures from permanently wiping cached credentials. It introduces IsSignedIn() to distinguish offline users from unauthenticated ones, adds a new Offline sync status, and updates downstream consumers to report accurate error states.

Changes

OAuth Client Refactoring & Error Handling

Layer / File(s)	Summary
OAuthClient concurrency primitives and authentication flow refactoring backend/FwLite/FwLiteShared/Auth/OAuthClient.cs	OAuthClient adds _authSemaphore for serialized GetAuth/Logout access; removes LexboxProjectService constructor dependency; introduces internal test-seam constructor; refactors GetAuth to synchronize token acquisition with expiry re-check and failure classification; rewrites Logout to acquire lock, clear cache, and publish events outside the critical section; documents IsSignedIn as local-cache-only; refactors CreateHttpClient to use object initializer for BaseAddress.
Silent auth failure classification logic backend/FwLite/FwLiteShared/Auth/OAuthClient.cs	Defines SilentAuthFailureOutcome enum (RemoveAccount, KeepCachedCredentials) and ClassifySilentAuthFailure switch mapping MSAL exceptions to removal or retention decisions; MsalUiRequiredException and multiple_matching_tokens_detected error code trigger removal; transient/server-side failures (HTTP errors, MSAL service errors, cancellation) trigger retention; adds virtual AcquireTokenSilentAsync test seam.
OAuthClient error classification unit tests backend/FwLite/FwLiteShared.Tests/Auth/OAuthClientFailureClassifierTests.cs	OAuthClientFailureClassifierTests verifies ClassifySilentAuthFailure behavior: MsalUiRequiredException and multiple_matching_tokens_detected error code result in RemoveAccount; transient/server-side exceptions (HTTP errors, MSAL service errors, cancellation) result in KeepCachedCredentials.
OAuthClient sign-in and silent refresh integration tests backend/FwLite/FwLiteShared.Tests/Auth/OAuthClientIsSignedInTests.cs, backend/FwLite/FwLiteShared.Tests/Auth/OAuthClientSilentRefreshTests.cs	OAuthClientIsSignedInTests verify IsSignedIn() returns true/false based on account presence. OAuthClientSilentRefreshTests verify GetAuth() across scenarios: transient errors keep cached account with no event; invalid_grant removes account and publishes event; cancellation keeps account; expired/near-expiry tokens follow expiry-window semantics; Logout blocks on same semaphore as in-flight GetAuth and stays locked out after completion. Includes TestableOAuthClient subclass and AuthenticationResult helpers.
Sync status enum expansion backend/LexCore/Sync/SyncStatus.cs, frontend/viewer/src/lib/dotnet-types/generated-types/LexCore/Sync/ProjectSyncStatusErrorCode.ts	ProjectSyncStatusErrorCode enum adds new Offline member (between NotLoggedIn and Unknown) to distinguish signed-in-but-unreachable users from unauthenticated users in JSON and frontend representations.
Downstream consumer integration backend/FwLite/FwLiteShared/Sync/SyncService.cs, backend/FwLite/FwLiteShared/Projects/LexboxProjectService.cs	SyncService.ExecuteSync and LexboxProjectService.GetLexboxSyncStatus/AwaitLexboxSyncFinished now call IsSignedIn() when HTTP client creation fails to distinguish offline-but-signed-in (maps to Offline status and internet-check message) from not-logged-in (maps to NotLoggedIn status and auth-failure message).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• sillsdev/languageforge-lexbox#1521: Modifies OAuthClient logout and AuthenticationChangedEvent event-publish flow with overlapping semaphore/lock semantics.
• sillsdev/languageforge-lexbox#1759: Depends on OAuthClient.IsSignedIn() for sync dialog/status logic that this PR refactors and adds comprehensive test coverage for.

Suggested reviewers

• hahn-kev
• rmunn

Poem

🐰 A semaphore guards the token gate,
No more does a blip sign you out of your fate,
Classify each error with logic so clear,
Transient troubles won't make you disappear!
Offline or lost—now we know which is which,
One PR to fix them all—quite the switch! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: fixing OAuth to prevent wiping refresh-token cache on transient errors, which is the primary focus of all changes in the PR.
Description check	✅ Passed	The description is directly related to the changeset, explaining the three client-side causes being fixed and the supporting changes for the Offline error code.
Linked Issues check	✅ Passed	The PR directly addresses all three client-side root causes from #2306: (1) transient errors no longer wipe MSAL cache [OAuthClient.cs refactor], (2) concurrency control via SemaphoreSlim prevents replay detection [OAuthClient.cs + tests], (3) MSAL cache relocation to stable per-user location [mentioned in description], plus supporting IsSignedIn feature [OAuthClient.cs + tests + SyncStatus.cs].
Out of Scope Changes check	✅ Passed	All changes are scoped to the stated objectives: test classes for new auth behaviors, OAuthClient refactoring, LexboxProjectService and SyncService updates to use IsSignedIn, SyncStatus enum addition, and generated TypeScript types. No unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/fix-fwlite-auth-logout

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Jun 10, 2026, 3:19 PM

[github-actions]

UI unit Tests

  1 files   62 suites   31s ⏱️
186 tests 186 ✅ 0 💤 0 ❌
258 runs  258 ✅ 0 💤 0 ❌

Results for commit 09ae216.

♻️ This comment has been updated with latest results.

[github-actions]

C# FwHeadless Unit Tests

48 tests   48 ✅  16s ⏱️
 5 suites   0 💤
 1 files     0 ❌

Results for commit 09ae216.

♻️ This comment has been updated with latest results.

[github-actions]

C# Unit Tests

165 tests   165 ✅  19s ⏱️
 23 suites    0 💤
  1 files      0 ❌

Results for commit 09ae216.

♻️ This comment has been updated with latest results.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/FwLite/FwLiteShared/Auth/OAuthClient.cs`:
- Around line 224-226: The current _logger.LogWarning call in OAuthClient.cs
includes raw usernames and HomeAccountId identifiers via string.Join over
accounts which leaks PII; change the log to avoid raw identifiers by logging
only the count of cached accounts or redacted identifiers (e.g., account index
or hashed/partial redaction) instead of a full username or HomeAccountId.
Specifically update the _logger.LogWarning invocation (the call that passes 'e'
and the "Silent token acquisition..." message and the
string.Join(accounts.Select(...))) to replace string.Join(...) with either
accounts.Count() or a safe projection like accounts.Select((a,i) =>
$"account#{i}") or a redacted substring/hash, ensuring no full usernames or
HomeAccountId.Identifier values are emitted. Ensure formatting and exception
parameter 'e' remain unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 41983a8c-d5ba-473b-8343-1f64734a65c7

📥 Commits

Reviewing files that changed from the base of the PR and between 4ccd57f and 09ae216.

📒 Files selected for processing (8)

• backend/FwLite/FwLiteShared.Tests/Auth/OAuthClientFailureClassifierTests.cs
• backend/FwLite/FwLiteShared.Tests/Auth/OAuthClientIsSignedInTests.cs
• backend/FwLite/FwLiteShared.Tests/Auth/OAuthClientSilentRefreshTests.cs
• backend/FwLite/FwLiteShared/Auth/OAuthClient.cs
• backend/FwLite/FwLiteShared/Projects/LexboxProjectService.cs
• backend/FwLite/FwLiteShared/Sync/SyncService.cs
• backend/LexCore/Sync/SyncStatus.cs
• frontend/viewer/src/lib/dotnet-types/generated-types/LexCore/Sync/ProjectSyncStatusErrorCode.ts

[hahn-kev]

Looks good to me! I tested it out, I was still logged in, and had no trouble logging out and logging back in again.