fix(web): handle SSO session expiry behind Cloudflare Access and other proxies

[nitrobass24]

Builds on #1380

Summary

Testing PR #1380 behind a Cloudflare Access tunnel (qui2.nitrobass24.com) confirmed the Firefox network error detection works, but revealed additional issues specifically when Cloudflare Access returns 401 responses with Content-Type: text/html instead of blocking at the network level. This required several incremental fixes:

1. HTML response recovery for login requests

Extended ssoSafeFetch to also trigger SSO recovery on HTML responses (not just network errors), with bypassGuard for /api/auth/login so the first login attempt always triggers recovery instead of being blocked by a stale guard.

2. Timestamp-based guard cooldown

The sessionStorage recovery guard persisted across page loads, blocking recovery after SSO re-authentication completed. Added a 10-second timestamp cooldown that auto-clears the guard on fresh page loads while still preventing rapid navigation loops.

3. Service worker cache clearing

The PWA service worker serves the cached SPA shell for navigation requests, bypassing the SSO proxy entirely. Before recovery navigation, all SW caches are now cleared so the request falls through to the network. (Unregistering the SW entirely was tried but broke Cloudflare Access's auth flow.)

4. Service worker navigateFallbackDenylist

The root cause of the final issue: Cloudflare Access redirects to /cdn-cgi/access/authorized?nonce=... after authentication, but the SW intercepted this path and failed with FetchEvent.respondWith received an error: TypeError: Load failed. Added /cdn-cgi/ and /.well-known/ to the denylist so SSO callback paths bypass the service worker.

5. SSO recovery toast

With stacked auth (SSO + app login), the first login attempt is consumed by SSO re-authentication. A toast ("SSO session refreshed. Please sign in again.") now appears on the login page after recovery so users understand why they need to enter credentials again.

Test plan

• Tested end-to-end behind Cloudflare Access tunnel with expired sessions in Safari
• Verify behavior with Pangolin SSO proxy
• Verify no regression for non-SSO deployments

Summary by CodeRabbit

• Documentation

  • Added guidance on SSO proxy and CORS configuration for API requests
  • Added OIDC configuration recommendations for SSO proxy environments

• Bug Fixes

  • Enhanced authentication error detection and recovery mechanisms
  • Improved handling of network and CORS failures during login flows

• New Features

  • Added user notification when SSO session recovery completes

[coderabbitai]

Walkthrough

Adds documentation on SSO proxy and CORS behavior, implements robust SSO error detection and recovery mechanisms with session guards and cooldown timing, displays a recovery notification in the Login page, and expands the PWA service worker configuration to exclude SSO/well-known paths from fallback routing.

Changes

Cohort / File(s)	Summary
Documentation documentation/docs/advanced/sso-proxy-cors.md, documentation/docs/configuration/oidc.md	New SSO proxy and CORS guidance page added; OIDC configuration updated to reference SSO proxy documentation and proxy-side CORS configuration.
SSO Recovery Logic web/src/lib/api.ts	Added SSO recovery guards (SSO_RECOVERY_GUARD_KEY, SSO_RECOVERY_TS_KEY, SSO_RECOVERY_COOLDOWN_MS) with cooldown timing; expanded error detection for network and HTML-response errors; introduced asynchronous attemptSSORecoveryNavigation with cache clearing; updated ssoSafeFetch to detect login requests and trigger recovery navigation on network/HTML errors.
Login UI web/src/pages/Login.tsx	Added React effect to detect SSO recovery marker in sessionStorage and display informational toast message on mount.
PWA Configuration web/vite.config.ts	Expanded navigateFallbackDenylist in Vite PWA Workbox config to include /cdn-cgi and /.well-known paths alongside existing /api and /proxy exclusions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(auth): recover cleanly behind upstream SSO #1142: Implements matching SSO-aware fetch and recovery changes with backend CORS allowance for X-Requested-With header.

Suggested labels

auth, bugfix

Poem

🐰 When SSO proxy guards its gate,
Our fetch attempts to navigate—
With guards and cooldown, clear the way,
A toast appears: "Try once more, okay!" 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main objective of the changeset: handling SSO session expiry behind proxies like Cloudflare Access, which is the central theme across all modified files.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

web/src/lib/api.ts (4)

193-201: "cors" and "request failed" substring matches are overly broad.

Line 198: normalized.includes("cors") would match any error message containing the substring "cors" (e.g., hypothetical messages about "discourse" or other unrelated terms). Line 201: "request failed" is similarly generic and could match many non-SSO errors.

Since the guard prevents infinite loops, the blast radius is limited to a single unnecessary recovery navigation. Still, tightening these checks would reduce false positives.

Suggested tightening

-  return normalized.includes("networkerror") ||
-    normalized.includes("network error") ||
-    normalized.includes("failed to fetch") ||
-    normalized.includes("cors request did not succeed") ||
-    normalized.includes("cors") ||
-    normalized.includes("load failed") ||
-    normalized.includes("network request failed") ||
-    normalized.includes("request failed")
+  return normalized.includes("networkerror") ||
+    normalized.includes("network error") ||
+    normalized.includes("failed to fetch") ||
+    normalized.includes("cors request did not succeed") ||
+    normalized.includes("cors error") ||
+    normalized.includes("load failed") ||
+    normalized.includes("network request failed")

---

224-290: Consider using the Content-Type header alone rather than reading the body stream for ambiguous responses.

The body-sniffing heuristic (reading up to 1KB) is clever, but it adds complexity and latency for edge cases where Content-Type is missing. In practice, SSO proxies that return HTML almost always set text/html in the content type. The existing isSSOHTMLResponse check at Line 225 handles that path.

The body-reading fallback (Lines 247–289) mainly catches responses with no Content-Type header at all. If you want to keep it, the implementation looks correct — the clone() + stream reader + finally cleanup is well-structured.

---

346-384: Never-resolving promise on navigation is intentional but worth a brief inline comment.

Lines 363 and 373 return new Promise<Response>(() => {}) to suspend the caller while the page navigates. This is a known pattern, but a terse comment would help future readers understand why the promise intentionally never resolves.

Suggested comment

      if (await attemptSSORecoveryNavigation({ bypassGuard: isLoginRequest })) {
+        // Page is navigating away; return a pending promise to halt further processing.
        return new Promise<Response>(() => {})
      }

---

182-182: Minor formatting nit: missing spaces before ? in ternary expressions.

Line 182 and Line 187 have tightly packed ternaries (e.g., "name" in error? String(...) and error instanceof Error? error.message: typeof error === "string"? error: ""). These are syntactically valid but hard to scan.

Suggested formatting

-  const maybeName = typeof error === "object" && error !== null && "name" in error? String((error as { name?: unknown }).name): ""
+  const maybeName = typeof error === "object" && error !== null && "name" in error ? String((error as { name?: unknown }).name) : ""
...
-  const msg = error instanceof Error? error.message: typeof error === "string"? error: ""
+  const msg = error instanceof Error ? error.message : typeof error === "string" ? error : ""

---

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