fix(auth): recover from a failed OAuth callback instead of wedging

[interacsean]

Scope

This PR fixes app-shell's own logic error around failed OAuth callbacks. The upstream defects it interacts with — the auth client cleaning the callback URL only on success, and its replaceState({}, …) clobbering router history state — are deliberately not worked around here; they are filed as auth-public-client#139 (present since 0.3.0, verified against published tarballs).

The bug (ours)

attemptAutoLogin read the URL to decide whether a callback was in progress. Because upstream leaves ?code= / ?error= in place on every failure path, any failed callback made that check permanently true:

1. Session dies → autoLogin redirects to the IdP
2. IdP answers ?error=access_denied (or the exchange throws — e.g. a clobbered PKCE verifier)
3. The URL still looks like a callback → auto-login never fires again
4. App sits on guardComponent forever; reloading replays the same failing callback

The URL was the wrong signal. The check means "is an exchange in flight", and the callback-status machinery (createCallbackStatusManager) already tracks exactly that.

The fix

Gate auto-login on the callback's settled status, not the URL. The URL stays authoritative only while the status is "idle" — this client claims the exchange itself whenever it is constructed on a callback URL, so "idle" means nobody is handling those parameters and redirecting away from them would be unsafe.

And make sure it cannot loop instead. Un-wedging auto-login naively turns every failed callback into an infinite full-page redirect cycle (each attempt is a fresh page load, so nothing in memory can break it). Three guards:

• An explicit server refusal becomes a terminal "denied" status — bouncing back would ask the same question and get the same answer. The error stays on useAuth().error; the docs now show a guard that renders it with a retry.
• A recoverable failure gets one retry per tab, counted in sessionStorage (page loads reset memory). Unreadable storage counts as exhausted — looping is the worse failure, and such a browser can't complete the flow anyway.
• Outcomes are classified from the resulting auth state, not resolve-vs-throw: the server-error branch and a state mismatch both return normally after recording the error, so settlement alone misclassifies them — and a denial that arrives as a throw (the error branch touches IndexedDB first, which can reject) must still be terminal.

What this deliberately does not do

• No URL cleanup. The stale parameters remain in the address bar after a failure until upstream#139 lands. app-shell no longer misbehaves because of them, but reimplementing the library's cleanup in a consumer was the wrong layer — an earlier revision of this PR did exactly that (including history.state preservation) and has been backed out.
• No browser proof. The example apps don't wire auth at all (createAuthClient appears nowhere under examples/). The behavioural evidence is the mutation-tested unit suite below; end-to-end confirmation needs a consuming app driving a real IdP denial.

Testing

Six new tests. Every clause of the change is load-bearing under mutation — each row was verified by injecting that regression and watching the named tests fail (all green when restored):

Mutation	Killed by
revert gate to the URL check (main's behaviour)	resumes auto-login; settled-callback-drives-auto-login
drop the "denied" clause	3 tests (denial, throwing denial, budget)
remove the retry ceiling	budget-spent test
classify by resolve/throw instead of auth state	throwing-denial; budget-spent
drop the idle && narrowing	resumes auto-login; settled-callback

The original four also fail wholesale against origin/main's auth-context.tsx. build / type-check / lint / fmt:check pass; 1585 tests pass.

References

• Upstream: auth-public-client#139
• Sibling bump that raises exposure (teardown → auto-login became the primary recovery path): fix(auth): end sessions the server has rejected (auth-public-client ^0.6.0) #467
• The PKCE-verifier race whose "Missing session data" symptom this recovers from is being handled separately.

🤖 Generated with Claude Code

[interacsean]

/review

[github-actions]

✅ Code Review completed successfully!

Code review complete for PR #468 (fix/auth/callback-error-dead-end). No inline review comments were needed — the implementation is sound with no High or Medium issues. The only finding is a Low-severity note that the "denied" callback status is sticky within a client lifetime, which is acceptable per the PR's stated design. Verdict: Approve.

[github-actions]

Code Metrics Report

	main (41ae0e3)	#468 (594eaa9)	+/-
Coverage	90.1%	90.4%	+0.2%
Test Execution Time	2m5s	1m59s	-6s

Details

  |                     | main (41ae0e3) | #468 (594eaa9) |  +/-  |
  |---------------------|----------------|----------------|-------|
+ | Coverage            |          90.1% |          90.4% | +0.2% |
  |   Files             |            152 |            152 |     0 |
  |   Lines             |           5201 |           5228 |   +27 |
+ |   Covered           |           4690 |           4727 |   +37 |
+ | Test Execution Time |           2m5s |          1m59s |   -6s |

Code coverage of files in pull request scope (85.9% → 95.7%)

Files	Coverage	+/-	Status
packages/core/src/contexts/auth-context.tsx	95.7%	+9.7%	modified

---

Reported by octocov