feat: guide signed-out, expired and wrong-account browsers from any API link

Merged
KI
37m ago
+1450-315

Follow-up to SUPER-3480. Stacked on #9819. Merge that first. This PR targets #9819's branch, so the diff shows only the follow-up.

Why

After the paradev.com move, a customer hit {"error":"Unauthorized"} again on Ahrefs Connect. Their browser had been signed in on superset.sh, so someone had to tell them to sign in again on app.paradev.com.

What I found:

  • #9819 is not merged. Production still returns a bare 401 to every browser without a valid session. Checked with curl on Nov 16: api.paradev.com returns 401 with no cookie and with an invalid session cookie, and api.superset.sh returns 401 with an invalid cookie. That alone is why it happened again.
  • A stale cross-domain session looks the same as no session. Cookies are Domain=superset.sh or Domain=paradev.com, so an old superset.sh cookie never reaches api.paradev.com. #9819 already redirects that case to sign-in.
  • An expired or revoked session on the same domain sends a cookie that no longer resolves. getSession returns null, so #9819 redirects it too. The sign-in page still said only "Welcome back. Sign in to continue to Paradev": no plugin, and no hint that the session had expired.

So the redirect itself already covers the stale case once #9819 ships. This PR makes the interstitial explain itself, and adds a regression test for the stale case.

What

General rule: a person who opens an API URL without a valid session goes to sign-in, then back. Programmatic callers keep their 401.

  • apps/api/src/lib/signInRedirect.ts (new): unauthenticatedResponse(request, fallback).
    • A browser page navigation (GET/HEAD with Sec-Fetch-Dest: document, or Accept: text/html from browsers without fetch metadata) gets a 302 to <web>/sign-in?redirect=<original URL>.
    • The web host is on the request's own root domain, so the cookie set there is sent back to the API.
    • When the browser sent a better-auth session cookie that no longer resolves, the redirect adds reason=session_expired.
    • Fetch/XHR, <img>, CLI, desktop and curl get fallback, which is the route's existing 401.
  • Adopted in every session-checked browser route on the API:
    • requireOrgMember, which covers all 8 connect/install routes: connectors, GitHub, Google, Linear, Notion, Sentry, Slack, Teams
    • task and project file downloads
    • the Linear image proxy (an <img> still gets a 401; opening it in a tab goes to sign-in)
    • the Slack link route, which had its own redirect to the configured web URL and now uses signInUrl
    • Every other API route uses bearer tokens or signatures, or is a webhook or job (checked).
  • Behaviour change vs #9819: requireOrgMember redirects only navigations. A non-browser caller gets the original JSON 401 back. No caller in desktop, CLI, mobile or host-service fetches these routes.
  • Wrong account (signed in, but not in the link's org): requireOrgMember and the Slack link route send a page navigation to /auth/switch-account?redirect=<link> on the link's root domain. Other callers still get the 403.
    • The page shows the signed-in email and, for connect links, the connector name. It never shows the org's name, so nothing about an org leaks to a non-member.
    • Sign in with another account signs out, then goes through sign-in back to the link. If sign-out fails, the page stays and shows an error.
    • If the viewer is a member of the link's organizationId (signed in with the right account, or linked here by someone), the page sends them straight on to the link with no sign-out.
    • /auth/switch-account is retained in the domain move, so it stays on the host whose cookie the API sees.
  • Web proxy: the page-route sign-in redirect also adds reason=session_expired for a stale cookie.
  • Sign-in page: page.tsx is now a server component that reads the params once.
    • A connect link on our API names the connector. The name comes from the registry, never from the URL: Sign in to connect Ahrefs.
    • Copy depends on state: "This browser is not signed in to Paradev…", or "Your Paradev session in this browser has expired. Sign in again to continue[ to Ahrefs]."
    • Any other sign-in is unchanged.
  • getConnector now matches only own keys. Before, constructor matched Object.
  • Copy is translated in all 18 locales, and check:i18n passes.

Verification

  • Stale vs no session: signInRedirect.test.ts tests a missing session and a stale session separately. The stale test fails on #9819 alone and passes now.
  • Navigation vs fetch/img: requireOrgMember.test.ts and signInRedirect.test.ts check that a navigation redirects while fetch and <img> callers keep the 401.
  • Other tests: proxy.test.ts covers stale web pages, connectorNameFromRedirect.test.ts the connector name, and connectors/index.test.ts the getConnector fix.
  • apps/api 263 pass, the apps/web suite passes, and tsc is clean for api, web and shared. biome and check:i18n pass.
  • General case on the dev stack:
    • a task file URL with no session → sign-in
    • the same URL with a stale cookie → "session expired"
    • a web page (/settings) with a stale cookie → reason=session_expired
    • curl, Sec-Fetch-Dest: empty and <img> callers → unchanged 401
  • Connect flow end to end, in headless Chrome with a fresh profile:
    • no cookie → interstitial (a)
    • a real revoked session: sign in, sign out, then replay the old cookie → interstitial (b) with reason=session_expired
    • "Sign in" → back to the connect route → app.ahrefs.com/web/oauth/authorize
  • Wrong account on the dev stack, as a second user outside the dev org:
    • connect link → switch-account page ("Use another account to connect Ahrefs", the user's email)
    • Sign in with another account → "Sign in to connect Ahrefs" → sign in as a member → app.ahrefs.com/web/oauth/authorize
    • a member opening the switch page goes straight to the link (307)
    • fetch → the unchanged 403 JSON
  • Independent review subagents:
    • First pass: found the constructor lookup bug, a Turkish grammar nit and a double read of the search params. All fixed.
    • Second pass, on the general change: found the Slack link route bypassing the helper. Fixed.
    • Third pass, on switch-account: found no leaks, no open redirect and no forced sign-out without a click. It flagged that a failed sign-out still navigated away, that the page didn't verify membership, and that the Slack route needed the same switch. All three are fixed.
  • Not tested: Ahrefs consent and token exchange, which need a paid Ahrefs account. Also unchanged by this PR.

Evidence page with production before and dev after screenshots: https://app.superset.sh/page/super-3480-follow-up-stale-sessions-after-the-para-djjfhx. The original investigation is at https://app.superset.sh/page/super-3480-ahrefs-connect-shows-unauthorized-vawdbt.

Not in scope

  • <a download> links (which may be dest: empty) still get the 401. Saving a sign-in page as the download would be worse.
  • For up to 5 minutes, better-auth's cookie cache still treats a just-revoked session as signed in. This is by design.

Summary by CodeRabbit

  • New Features
    • Added clearer sign-in and account-switch flows for integration links, including guidance when the current account lacks organization access.
    • Sign-in redirects now preserve the requested destination and can indicate when a browser session has expired.
    • Added translated authentication messages across supported languages.
  • Bug Fixes
    • Improved handling of unauthenticated and wrong-account requests, with browser navigation directing users to the appropriate page while API callers retain error responses.
    • Corrected connector lookups for names that match inherited object properties.