Sessions and Guards
How the signed-in user reaches loaders, actions, API handlers and components, and why guards don't replace authorization.
The session middleware reads the session once per request. Loaders, actions and handlers read it from the request context; components read the user's public fields from shared data.
This page is part of the Authentication documentation.
Guards Gate Navigation Only
apps/web/middleware/06.session.ts redirects by folder (pages/(app)/ needs a session, pages/auth/ refuses one) and marks those pages Cache-Control: private, no-store. That stops someone opening a page. It doesn't stop a request to an action or an API route: anyone can send one directly.
Every loader, action and handler that reads or changes a user's data checks the session itself, even inside pages/(app)/.
If the session can't be read (the database is down), public pages such as the marketing site and the pages/auth/ pages still render, signed out and marked private, no-store, and the error is logged. Pages under pages/(app)/ and every /api route answer 500: there an outage isn't a signed-out visitor.
Loaders and Actions
apps/web/pages/(app)/projects/index.server.ts
import { defineHandler, type InferProps } from 'void';import { requireSession } from '#/lib/session.server.ts';import { listProjects } from '#/lib/projects.service.ts'; // yoursexport type Props = InferProps<typeof loader>;export const loader = defineHandler(async (c) => { const { user } = requireSession({ c }); return { projects: await listProjects({ userId: user.id }) };});Helper (lib/session.server.ts) | Returns | Without a session |
|---|---|---|
requireSession({ c }) | { session, user } | Pages: redirect to sign-in with next. /api: 401 |
getSession({ c }) | { session, user } or null | null, for pages signed-out visitors can open too |
getNextPath(c) | the next query parameter if it's a safe same-site path, else the app home (APP_HOME_PATH) |
Take the user's id from the session, never from the request body or URL.
Sensitive Account Changes
Changing the email or password, linking or unlinking a sign-in method and signing out sessions need a fresh session: a sign-in from the last 10 minutes (FRESH_SESSION_MINUTES). An impersonation session never makes them. Better Auth's hooks refuse these endpoints (ACCOUNT_CHANGE_PATHS in packages/better-auth/src/fresh-session.ts, one list for both rules), over HTTP and from auth.api alike, with 403 SESSION_NOT_FRESH or 403. A name change stays allowed. Account deletion has its own rule (Deleting an Account).
A page action whose auth.api call has no path the hooks see (setPassword) checks first:
import { requireAccountChange } from '#/lib/account-change.server.ts';// 403 SESSION_NOT_FRESH or IMPERSONATED, else { session, user }const { user } = requireAccountChange({ c });Forms built for these changes map the code (useForm with throwOnError: false keeps the 403 in form.error). On SESSION_NOT_FRESH they offer to sign in again and come back: <SignInAgain href={signInAgainPath(authPaths.security)} /> (@kit/auth/shared, lib/auth-links.ts). It signs out first, since the sign-in page is for signed-out visitors.
API Routes
The same helpers work in routes/api/** handlers. requireSession answers 401 there instead of redirecting:
apps/web/routes/api/projects.ts
import { defineHandler } from 'void';import { requireSession } from '#/lib/session.server.ts';import { listProjects } from '#/lib/projects.service.ts'; // yoursexport const GET = defineHandler(async (c) => { const { user } = requireSession({ c }); return c.json(await listProjects({ userId: user.id }));});Components
import { useShared } from '@void/react';const { user } = useShared(); // null when signed outuser holds only id, name, email, image and emailVerified. Never put the session or other user fields into shared or page props: they're serialized into the page.
Signing In and Out from the Browser
Forms call Better Auth over HTTP through authClient, so its rate limits and origin checks apply:
import { authClient } from '@kit/better-auth/client';await authClient.signOut();window.location.reload(); // the middleware sees no session and redirectsDon't call getAuth().api.signIn* from page actions for user sign-in flows: server calls skip the rate limiter.
Suspended (Banned) Accounts
Better Auth's admin plugin refuses any new session to a user whose banned flag is set, whatever the sign-in method. Forms show the auth.errors.BANNED_USER message; a magic link or an OAuth callback lands on the sign-in page with ?error=BANNED_USER. Better Auth checks the flag only when a session is created, so whatever bans a user must also delete their sessions. The plugin's own /api/auth/admin/* endpoints always answer 404; the admin area uses them only from the server, after its own checks.
Adding a Page
- Signed-in only: put it under
apps/web/pages/(app)/.(app)is a route group, so it adds nothing to the URL. - Signed-out only (an auth flow): under
apps/web/pages/auth/. Add its path toauthPaths(config/auth-paths.ts) if code links or redirects to it. - Public: anywhere else. The middleware marks pages
private, no-storeonly for a signed-in visitor or a guarded folder; a public page with a token or user data in its URL setsCache-Control: private, no-storein its own loader, aspages/password-reset/index.server.tsdoes.
A new auth page follows the existing ones (pages/auth/sign-in.tsx):
apps/web/pages/auth/<name>.tsxand<name>.server.tsserve/auth/<name>;pages/auth/layout.tsxwraps it in the auth layout.- The loader returns
next: getNextPath(c)and passes it on in links and callbacks. headsets the title withgetServerTranslator({ c, namespace }).- It's a public page, so links use
LocalizedLinkand redirectslocalizedRedirect. - Its strings go in your namespace in
apps/web/messages/<locale>/(theapp_translations_*MCP tools), not the kit'sauthnamespace. See Managing Translations.
Moving a file is the only way to change who can open it. Guards are built from the files at build time, including [param], [...rest], .island and .dev/.prod pages.
Redirects After Sign-In
next survives sign-in, sign-up, email verification and password reset. Only same-site relative paths are followed (/dashboard?tab=a); anything else (https://evil.com, //evil.com) falls back to the app home. Better Auth callback URLs pointing off-site are rejected with 403 INVALID_CALLBACK_URL.
When next is an invitation's link (/invitation/<id>), sign-in and sign-up prefill the invited address, still editable (getInvitedEmail in apps/web/lib/invited-email.server.ts, passed as defaultEmail to the @kit/auth email forms). The address is read from the stored invitation, never from the URL, so it doesn't end up in request logs. It's only a hint: accepting checks the signed-in user's own verified address.