start-auth

TanStack Start — Authentication

CRITICAL GOTCHA (READ BEFORE ANYTHING)

beforeLoad + redirect() protects the UI, NOT your data.

Server functions and server routes are API endpoints reachable independently of whichever route renders the calling component. A beforeLoad guard keeps a user off a screen, but the underlying createServerFn handler can still be called directly (crafted request, replayed RPC). Authorization MUST be enforced inside the server-function handler or its middleware — that is the security boundary. beforeLoad is route UX only.

Route beforeLoad guard  → UX: keep users out of screens they can't use
Server-fn middleware    → SECURITY: the real data/API boundary — enforce auth HERE

→ data-boundary.md is mandatory reading before writing any auth code.

---

Agent Workflow (MANDATORY)

Before ANY implementation, spawn in parallel:

1. fuse-ai-pilot:explore-codebase — find src/routes/_authed*, src/server/, existing session code
2. fuse-ai-pilot:research-expert — verify Start auth API via Context7 /websites/tanstack_start_framework_react
3. mcp__context7__query-docs — confirm useSession, createMiddleware, getRequest signatures

After implementation, run fuse-ai-pilot:sniper, then consider fuse-security:auth-audit.

---

Overview

Concern	Primitive
Route UX	beforeLoad + redirect({ to: '/login' }) in an _authed layout route
Data authorization	authMiddleware on every private createServerFn (the real boundary)
Sessions	useSession<T>() (sealed cookie) OR manual __Host- cookie via getRequest/setResponseHeader
CSRF	createCsrfMiddleware() (auto for server fns) + Origin check for sibling subdomains

---

Critical Rules

1. Authorize in the handler — every server fn touching private data carries authMiddleware; never rely on beforeLoad.
2. Never a GET that mutates — mutations use POST/PUT/DELETE so SameSite=Lax protects them.
3. Read env/cookies per request — process.env.SECRET inside the handler, NEVER at module scope (leaks to bundle; undefined on edge).
4. Rotate sessions on privilege change — revoke old + issue new on login/logout/password/role change.
5. Defeat enumeration & timing — identical responses for unknown vs known accounts; constant-time password compare.

---

Auth Approaches (official)

The official authentication guide lists Clerk, WorkOS, Better Auth, and Auth.js as supported options, plus fully DIY. This skill ships the DIY server-primitive templates (portable, no vendor lock-in), which the official guide documents in depth. For a managed library (Auth.js, Better Auth, Clerk, WorkOS), install it and follow ITS current docs / the better-auth skill — do NOT assume a Start adapter API without verifying it, and note there is no first-party start-authjs example in the TanStack repo (the real DIY examples are start-basic-auth and start-supabase-basic).

---

Reference Guide

Concepts

Topic	Reference	Load when
Data boundary	data-boundary.md	ALWAYS first — where auth is actually enforced
Route protection	route-protection.md	Building the _authed layout + RBAC redirects
Sessions & cookies	sessions-cookies.md	Issuing/reading sessions, cookie flags
Hardening	hardening.md	CSRF, rate limiting, OAuth state/PKCE, timing

Templates

Template	When to Use
authed-middleware.md	_authed layout + authMiddleware + protected server fn
session-and-csrf.md	Cookie session helpers + global CSRF/origin middleware + login
oauth-pkce.md	OAuth authorization-code flow with state + PKCE

---

Best Practices

DO

• Centralize session lookup in authMiddleware so every handler gets a typed session
• Use __Host- prefixed, HttpOnly, Secure, SameSite=Lax cookies
• Verify Origin on non-GET requests against your app origin

DON'T

• Treat beforeLoad as the security boundary
• Read process.env at module top level
• Vary response/status/timing between existing and non-existing accounts