fix(THU-580): cache Better Auth session so app boots offline

[raivieiraadriano92]

Closes THU-580.

Better Auth's useSession needs a /get-session round-trip to populate data. Offline at boot that fetch fails, data stays null, and useAuthGate redirects authenticated routes to /waitlist — the user is stuck on the login screen until they reconnect.

Cache the last successful session payload in localStorage and seed client.\$store.atoms.session on auth-client creation. useAuthQuery.onError preserves non-null data on non-401 errors, so the cached value survives the failing offline fetch. Better Auth's own online listener replaces it with fresh server data as soon as the network returns. Cache is cleared on 401 and on clearLocalData (logout / wipe).

---

Note

Medium Risk
Touches auth boot path and stores richer profile data in localStorage alongside the token; invalidation on 401/logout/wipe and expiry checks limit stale-session risk.

Overview
Fixes offline startup for users who already have a bearer token: the last successful session is stored in localStorage and used to seed Better Auth’s session atom before /get-session runs, so protected routes are not treated as logged-out when the network is down.

session-cache adds read/write/clear plus isCachedSessionValid (future session.expiresAt only). hydrateSessionFromCache runs when the auth client is created (token + valid cache required); subscribeSessionCachePersist mirrors atom updates that include both user and session, with unsubscribe on client swap.

The cache is cleared on 401, clearLocalData, and cross-tab token rotation (before reload) so stale or wrong-user data is not reused offline.

^{Reviewed by Cursor Bugbot for commit df5b928. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Semgrep Security Scan

No security issues found.

[github-actions]

Preview environment destroyed 🧹

Stack preview-pr-954 and its Cloudflare subdomain have been cleaned up.

[github-actions]

PR Metrics

Metric	Value
Lines changed (prod code)	+174 / -1
JS bundle size (gzipped)	🟢 776.2 KB → 776.4 KB (+222 B, +0.0%)
Test coverage	🟢 77.39% → 77.45% (+0.1%)
Performance (preview)	Preview not ready — Render deploy may have timed out
Accessibility	—
Best Practices	—
SEO	—

Updated Mon, 06 Jul 2026 20:04:26 GMT · run #2198

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit beab0c6. Configure here.}

[github-actions]

🔭 thunder-deep-review (advisory)

Complements the other bots — surfaces only what they did not flag. Never approves, never requests changes, never gates merge.
_{head: df5b928bb810 · mode: single · deferred 2 item(s) already reported by other bots (best-effort dedup)}

[github-actions]

📐 Convention — Reaching into Better Auth's $store.atoms.session internals

Both the seed and the persist subscription poke client.$store.atoms.session directly rather than going through Better Auth's public useSession/getSession surface. The tests even cast fake clients through as unknown to satisfy the shape, which is a hint that this path isn't well-typed for us. This is the same class of fragility we already flag for the powersync-web-internal alias — if a Better Auth upgrade renames or restructures the atom store, this breaks silently with no TypeScript error and the offline-boot feature just quietly stops working. Could we add a comment pinning the Better Auth version this shape was verified against, so an upgrade prompts a re-check?