0
Fork 0
mirror of https://github.com/TanStack/router.git synced 2026-11-16 19:38:07 +00:00
router/docs/start/framework/react/guide/authentication-overview.md
Tanner Linsley 3526194849
docs(skills): address 8 agent failure modes from user feedback (#7314)
* docs(skills): address 8 agent failure modes from external feedback

Adds new start-core/auth-server-primitives skill (sessions, cookies,
OAuth+PKCE, password-reset enumeration defense, CSRF, rate limiting,
session rotation) and updates 8 existing skills + matching docs to fix
patterns where agents produce insecure or wrong-framework output.

Skill changes:
- new: start-core/auth-server-primitives (server half of auth)
- router-core/auth-and-guards: route guard != RPC guard
- start-core/server-functions: wrong import path, RPC auth required,
  Cache-Control public is a cross-tenant leak, wrong-framework patterns
- start-core/middleware: wrong import path, sendContext shape vs access
  (3-layer wrong/still-wrong/correct), authMiddleware framing
- start-core/execution-model: file markers (server-only/client-only),
  module-level process.env is undefined under Worker SSR
- start-core/deployment: cloudflare env-at-request-time
- router-core/ssr: wrong file structures (next.js, react-router-dom)
- router-core/type-safety: wrong-framework imports + structures

Docs updated to mirror each skill change so source-of-truth and the
intent-indexed skill stay in sync. New authentication-server-primitives
guide is the long-form companion to the new skill.

intent validate: 30 skill files pass (was 29).

* ci: apply automated fixes

* docs(skills): address coderabbit review feedback

- Fix internal docs links to use correct relative paths instead of an
  absolute /start/latest/... URL and missing one ../ segment
- Remove blank line inside auth-and-guards blockquote (markdownlint MD028)
- Restore overload pattern in type-safety ValidateNavigateOptions and
  ValidateRedirectOptions examples; the casts I had introduced stripped
  generic context and contradicted the skill's own no-cast rule
- Add db.sessions.revokeAllForUser before create in login rotation
  snippets so the example matches the prose
- Soften useServerFn guidance: it's required only when the server
  function throws redirect/notFound; plain-data calls work directly and
  via useMutation/useQuery

* ci: apply automated fixes

* docs(skills): compress type-safety to stay under 500-line cap

Prettier's autofix expanded my single-line overload signatures across
multiple lines, pushing the file over the 500-line limit. Drop the
redundant fetchOrRedirect example (same pattern as useDelayedNavigate)
and describe ValidateRedirectOptions usage in prose instead.

* docs(skills): CSRF origin check should compare full origin, not host alone

Comparing only new URL(origin).host against APP_HOST silently accepts a
mismatched scheme — http://example.com would pass a check meant for
https://example.com. Compare the full origin (scheme + host + port)
against APP_ORIGIN instead. Same fix in skill and docs.

* docs(skills): make useDelayedNavigate callback truly return void

The callback returned the result of setTimeout (a timer handle), not
void as the public overload's return type implied. Wrap in a block so
the example matches the declared return type.

Skipped the related nitpick to add a separate redirect example — the
existing prose already describes the same overload pattern, and a
duplicate example would push the file close to the 500-line cap that
prettier autofix has been bumping us against.

* docs(skills): fix two real bugs in auth-server-primitives examples

1. Cookie parser truncated values containing '='. Signed cookies, JWTs,
   and base64-padded values all use '='. Use indexOf to split on the
   FIRST '=' only.

2. Login example short-circuited verifyPasswordHash on user-not-found,
   contradicting the prose's "same time, same error" claim — the
   no-user branch returned instantly while wrong-password spent ~100ms
   hashing, leaking account existence over the wire. Always verify
   against a hash; use a precomputed DUMMY_PASSWORD_HASH when the user
   is missing, then combine with the user-exists bit for the final ok.

Same fixes in the SKILL.md and the docs companion.

* docs(skills): address manuel's review on react-specific guides

- middleware.md, server-functions.md: drop cross-framework <framework>
  placeholders; this is the React-specific guide, just say
  @tanstack/react-start
- execution-model.md: drop the same trailing line about solid-start /
  vue-start paths
- hosting.md: remove the Cloudflare env-handling subsection — the
  general per-request rule lives in environment-variables.md and
  doesn't need to be repeated under a specific host
- environment-variables.md: mention the cloudflare:workers env binding
  as the canonical Cloudflare way to read env (including module scope),
  per Manuel's link to the Cloudflare docs
- deployment skill: same upgrade — show the cloudflare:workers env
  pattern alongside the per-request handler approach

* docs(skills): drop redundant server-only marker in session example

The file already imports from @tanstack/react-start/server, which is
on import protection's default client-deny specifier list. The
side-effect marker is redundant — drop it. Same fix in skill and docs.

* docs(skills): drop wrong-import-path mistakes — TS already catches them

Manuel pointed out that TypeScript catches both common wrong paths:
'@tanstack/react-router' has no exported member createServerFn /
createMiddleware, and '@tanstack/start' is "Cannot find module". Skill
space is precious; the items don't earn their slot if tsc handles them.

Removed:
- Common Mistake "Wrong import path" from server-functions and
  middleware skills (renumbered the remaining mistakes)
- The matching top-of-file CRITICAL line in both skills
- The "Import path" callouts in the middleware and server-functions
  docs

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-05-02 23:11:30 -06:00

8.5 KiB

id title
authentication-overview Authentication

Authentication vs Authorization

  • Authentication: Who is this user? (Login/logout, identity verification)
  • Authorization: What can this user do? (Permissions, roles, access control)

Architecture Overview

Full-Stack Authentication Model

Server-Side (Secure)

  • Session storage and validation
  • User credential verification
  • Database operations
  • Token generation/verification
  • Protected API endpoints

Client-Side (Public)

  • Authentication state management
  • Route protection logic
  • Login/logout user interface
  • Redirect handling

Isomorphic (Both)

  • Route loaders checking auth state
  • Shared validation logic
  • User profile data access

Session Management Patterns

HTTP-Only Cookies (Recommended)

  • Most secure approach - not accessible via JavaScript
  • Automatic browser handling
  • Built-in CSRF protection with sameSite
  • Best for traditional web applications

JWT Tokens

  • Stateless authentication
  • Good for API-first applications
  • Requires careful handling to avoid XSS vulnerabilities
  • Consider refresh token rotation

Server-Side Sessions

  • Centralized session control
  • Easy to revoke sessions
  • Requires session storage (database, Redis)
  • Good for applications requiring immediate session control

Route Protection Architecture

Layout Route Pattern (Recommended)

  • Protect entire route subtrees with parent layout routes
  • Centralized authentication logic
  • Automatic protection for all child routes
  • Clean separation of authenticated vs public routes

Component-Level Protection

  • Conditional rendering within components
  • More granular control over UI states
  • Good for mixed public/private content on same route
  • Requires careful handling to prevent layout shifts

Server Function Guards

  • Server-side validation before executing sensitive operations
  • Works alongside route-level protection
  • Essential for API security regardless of client-side protection

State Management Patterns

Server-Driven State (Recommended)

  • Authentication state sourced from server on each request
  • Always up-to-date with server state
  • Works seamlessly with SSR
  • Best security - server is source of truth

Context-Based State

  • Client-side authentication state management
  • Good for third-party auth providers (Auth0, Firebase)
  • Requires careful synchronization with server state
  • Consider for highly interactive client-first applications

Hybrid Approach

  • Initial state from server, client-side updates
  • Balance between security and UX
  • Periodic server-side validation

Authentication Options

🏢 Partner Solutions

🛠️ DIY Authentication

Build your own authentication system using TanStack Start's server functions and session management. Start with the Authentication Server Primitives guide — it covers session cookies (HttpOnly/Secure/SameSite/__Host-), session lookup as middleware, OAuth state + PKCE, password-reset enumeration defense, CSRF, rate limiting, and session rotation, with the WRONG/CORRECT patterns that catch the common mistakes.

  • Full Control: Complete customization over authentication flow
  • Server Primitives: Sessions, OAuth, CSRF, rate limiting — see Authentication Server Primitives
  • Session Management: HTTP-only cookies via setResponseHeader, read with getRequestHeader
  • Type Safety: End-to-end type safety for authentication state

🌐 Other Excellent Options

Open Source & Community Solutions:

  • Better Auth - Modern, TypeScript-first authentication library
  • Auth.js (formerly NextAuth.js) - Popular authentication library for React

Hosted Services:

  • Supabase Auth - Open source Firebase alternative with built-in auth
  • Auth0 - Established authentication platform with extensive features
  • Firebase Auth - Google's authentication service

Partner Solutions

WorkOS - Enterprise Authentication

WorkOS logo
  • Single Sign-On (SSO) - SAML, OIDC, and OAuth integrations
  • Directory Sync - SCIM provisioning with Active Directory and Google Workspace
  • Multi-factor Authentication - Enterprise-grade security options
  • Compliance Ready - SOC 2, GDPR, and CCPA compliant

Visit WorkOS → | View example →

Clerk - Complete Authentication Platform

Clerk logo
  • Ready-to-use UI Components - Sign-in, sign-up, user profile, and organization management
  • Social Logins - Google, GitHub, Discord, and 20+ providers
  • Multi-factor Authentication - SMS, TOTP, and backup codes
  • Organizations & Teams - Built-in support for team-based applications

Visit Clerk → | Sign up free → | View example →

Examples

Partner Solutions:

DIY Implementations:

Client-Side Examples:

Architecture Decision Guide

Choosing an Authentication Approach

Partner Solutions:

  • Focus on your core business logic
  • Enterprise features (SSO, compliance)
  • Managed security and updates
  • Pre-built UI components

OSS Solutions:

  • Community-driven development
  • Specific customizations
  • Self-hosted solutions
  • Avoid vendor lock-in

DIY Implementation:

  • Complete control over the auth flow
  • Custom security requirements
  • Specific business logic needs
  • Full ownership of authentication data

Security Considerations

  • Use HTTPS in production
  • Use HTTP-only cookies when possible
  • Validate all inputs on the server
  • Keep secrets in server-only functions
  • Implement rate limiting for auth endpoints
  • Use CSRF protection for form submissions

Next Steps

Resources

Implementation Guides:

Foundation Concepts:

Step-by-Step Tutorials: