fix(auth): restore native sessions after WebView restart

[paveezheng]

Summary

Restore a native dashboard session after a fresh WKWebView launch by performing one bounded refresh through the local auth relay when persisted refresh credentials exist.

Scope

• CLI (src/)
• Dashboard (dashboard/)
• macOS app (TokenTrackerBar/)
• Windows app (TokenTrackerWin/)
• Docs / CI / config

Checklist

• npm test passes
• New user-facing strings go through dashboard/src/content/copy.csv (no new user-facing strings)
• Commits follow conventional style (fix:)
• PR description explains why, not just what

---

Risk layer addendum — expand if this PR touches any trigger below

Risk layer triggers

• Public exposure / share links / unauthenticated access
• Auth / session / token handling
• Cross-endpoint invariants or shared logic
• External gateway / environment constraints

Rules / invariants

• An already valid session must not trigger a refresh request.
• A fresh native WebView may recover once through the local auth relay’s persisted refresh-token fallback.
• Only an empty user state or 401/403 is recoverable; network/server failures must not become refresh loops.
• An unmounted auth provider must not issue a delayed refresh.

Boundary matrix (list at least 3)

Boundary	Expected behavior
Existing valid user	Return user immediately; no refresh
Empty initial WebView session	Preserve the OAuth callback retry, then refresh once and re-read user
401 / 403 response	Refresh immediately once, then re-read user
5xx / network failure	Preserve failure; do not refresh
Provider disposed during startup	Stop before retry/refresh

Public exposure checklist (if applicable)

• Not applicable

Codex review context — fill when requesting @codex review

• Delta since last Codex review: Added bounded native session recovery helper and five regression cases.
• Intended behavior / invariants: Restore a persisted native session after a new WebView starts without broadening refresh behavior or creating retry loops.
• Edge cases covered: Existing session, empty WebView session, 401 recovery, network failure, disposed provider.
• Tests run (command + result):
  • npm test — 2,432 passed, 0 failed, 2 skipped
  • npm --prefix dashboard exec vitest run src/contexts/__tests__/InsforgeAuthContext.test.jsx — 6 passed
  • Dashboard lint and production build — passed
  • Xcode-beta Debug build, signing, and launch verification — passed

Most likely regression surface

Native OAuth callback timing and signed-out dashboard startup behavior.

Verification method (choose at least one)

• Automated regression tests
• Dashboard production build
• Native Xcode-beta build and launch verification

Uncovered scope

No automated real-Google-account reboot test; this still needs one manual verification on macOS 27 after merging.

Summary by CodeRabbit

• Bug Fixes
  • Improved session restoration when reopening the app in an embedded browser.
  • Users are less likely to be signed out when session cookies are temporarily unavailable.
  • Added recovery for expired authentication sessions while preserving genuine network errors.
  • Prevented session recovery from continuing after the authentication provider is closed.
• Tests
  • Added coverage for session reuse, recovery, authentication errors, network failures, and cancellation scenarios.

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6a98b581-fb3d-4090-be16-1e8e3532e154

📥 Commits

Reviewing files that changed from the base of the PR and between cd6f360 and 477f693.

📒 Files selected for processing (3)

• dashboard/src/contexts/InsforgeAuthContext.jsx
• dashboard/src/lib/insforge-session-recovery.mjs
• test/insforge-session-recovery.test.js

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The authentication context now uses restoreInsforgeUser to recover sessions after embedded-browser relaunches. The helper handles OAuth settlement, activity checks, refresh attempts, error classification, and post-refresh user lookup. Tests cover recovery, cancellation, and error paths.

Changes

Insforge session recovery

Layer / File(s)	Summary
Implement and validate session recovery dashboard/src/lib/insforge-session-recovery.mjs, test/insforge-session-recovery.test.js	Adds restoreInsforgeUser with session lookup, optional delay, activity checks, one-time refresh, retry handling, and error preservation. Tests cover valid sessions, recoverable 401 responses, network failures, and disposed providers.
Integrate recovery into session loading dashboard/src/contexts/InsforgeAuthContext.jsx	The session-loading effect calls restoreInsforgeUser and removes the previous inline delayed retry.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 477f6

This change adds bounded native session recovery after a fresh WebView launch while preserving existing-session and failure behavior. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: xiufengsun

Sequence Diagram(s)

sequenceDiagram
  participant InsforgeAuthContext
  participant restoreInsforgeUser
  participant client.auth
  InsforgeAuthContext->>restoreInsforgeUser: Restore the current user
  restoreInsforgeUser->>client.auth: Get current user
  client.auth-->>restoreInsforgeUser: Return user or auth error
  restoreInsforgeUser->>client.auth: Refresh session when recovery is allowed
  client.auth-->>restoreInsforgeUser: Return refreshed session
  restoreInsforgeUser->>client.auth: Get current user again
  client.auth-->>restoreInsforgeUser: Return recovered user
  restoreInsforgeUser-->>InsforgeAuthContext: Return session result

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: restoring native authentication sessions after a WebView restart.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Your free Security trial is over. An organization admin can activate billing to continue.

---

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.}