Skip to content

Frontend Auth and Session

Ankit Upadhyay edited this page Jul 24, 2026 · 2 revisions

Frontend: Auth and Session

Client-side authentication on SuperTokens (supertokens-web-js), route protection, and org-scoped session hydration. Architecture context: Authentication and Identity. Part of Frontend Overview.

SuperTokens client

Auth runs in the browser via supertokens-web-js — the previous amazon-cognito-identity-js client was replaced wholesale by the SuperTokens migration (PR #1763, merged 2026-07-16). src/app/lib/authClient.ts owns SDK init: initAuthClient() is idempotent (no-op during SSR), derives the apiDomain from NEXT_PUBLIC_BASE_URL, and registers the recipes EmailPassword, EmailVerification, MultiFactorAuth, Passwordless, Session, ThirdParty, and TOTP. Initializing Session installs global fetch/XHR interceptors that attach the session cookie and transparently refresh expired sessions.

src/app/stores/authStore.ts bootstraps initAuthClient() on load and exposes signUp, confirmSignUp/verifyEmail, resendCode, signIn, checkSession, refreshSession, getValidSession, signout, forgotPassword, resetPassword, loadUserAttributes. signIn returns a SignInResult — OK, EMAIL_VERIFICATION_REQUIRED, or MFA_REQUIRED with the pending factors (totp | otp-email), which the store tracks as an mfaChallenge. The status union is 'idle' | 'checking' | 'authenticated' | 'unauthenticated' | 'signin-authenticated'; in-flight session checks are deduped. Developers additionally get "Continue with GitHub" via the SuperTokens ThirdParty recipe (features/auth/lib/githubOAuth.ts, inert unless NEXT_PUBLIC_AUTH_GITHUB_ENABLED is set, callback at /auth/callback).

Sign-out goes through src/app/hooks/useAuth.ts (hardSignOut → signout + clearSessionScopedStores + clears loaders).

Route protection

Auth is not enforced at the edge, so protection is client-side. This is UX only: the session lives in an httpOnly SuperTokens cookie (auto-refreshed by the SDK's interceptors — no tokens in localStorage), and the backend independently validates the session on every request via the provider-neutral requireWebAuth guard and enforces org-scoped RBAC server-side, so bypassing a client guard yields an empty UI shell, not data access.

  • ProtectedRoute (src/app/ui/layout/guards/ProtectedRoute.tsx) redirects unauthenticated users to /signin?next=…, writes a yc_auth_passed flag, and has a NEXT_PUBLIC_DISABLE_AUTH_GUARD localhost bypass.
  • DevRouteGuard requires role === 'developer' for /developers*, else redirects to /developers/signin.
  • SessionInitializer (src/app/ui/layout/SessionInitializer.tsx) runs checkSession() on mount and, when the primary org changes, hydrates all org-scoped stores with Promise.allSettled([...loadX({silent:true})]).

Auth UI

features/auth/pages/ — SignIn, SignUp, ForgotPassword, ResetPassword, VerifyEmail, and AuthCallback (OAuth callback), plus GithubSignInButton and shared AuthPages.css; OTP via ui/overlays/OtpModal. Route pages: (public)/signin, (public)/signup, (public)/forgot-password, (public)/reset-password, (public)/verify-email, (public)/auth (OAuth callback), and (public)/developers/signin (reuses SignIn with isDeveloper, redirectPath="/developers/home").

Related helpers: lib/postAuthRedirect.ts, lib/routePermissions.ts, lib/permissions.ts, hooks/usePermissions.ts, lib/resetSessionStores.ts.

Note on the migration

The provider-neutral SuperTokens migration landed via PR #1763 (merged 2026-07-16): web, mobile, and backend all authenticate through SuperTokens, with Cognito surviving only as a legacy grace-window verifier during cutover. Passkeys and the broader MFA rollout (Plans: Authentication) remain follow-ups under epic #1672.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally