feat: guide signed-out, expired and wrong-account browsers from any API link
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
curlon Nov 16:api.paradev.comreturns 401 with no cookie and with an invalid session cookie, andapi.superset.shreturns 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.shorDomain=paradev.com, so an old superset.sh cookie never reachesapi.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.
getSessionreturns 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, orAccept: text/htmlfrom 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 getfallback, which is the route's existing 401.
- A browser page navigation (GET/HEAD with
- 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:
requireOrgMemberredirects 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):
requireOrgMemberand 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-accountis 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_expiredfor a stale cookie. - Sign-in page:
page.tsxis 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.
getConnectornow matches only own keys. Before,constructormatchedObject.- Copy is translated in all 18 locales, and
check:i18npasses.
Verification
- Stale vs no session:
signInRedirect.test.tstests a missing session and a stale session separately. The stale test fails on #9819 alone and passes now. - Navigation vs fetch/img:
requireOrgMember.test.tsandsignInRedirect.test.tscheck that a navigation redirects while fetch and<img>callers keep the 401. - Other tests:
proxy.test.tscovers stale web pages,connectorNameFromRedirect.test.tsthe connector name, andconnectors/index.test.tsthegetConnectorfix. apps/api263 pass, theapps/websuite passes, andtscis clean for api, web and shared. biome andcheck:i18npass.- 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: emptyand<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
constructorlookup 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.
- First pass: found the
- 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 bedest: 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.