* 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>
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 withgetRequestHeader - 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
- 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
- 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
- Partner solutions → Clerk or WorkOS
- DIY implementation → Authentication Guide
- Examples → Working implementations
Resources
Implementation Guides:
- Authentication Server Primitives — sessions, cookies, OAuth, CSRF, rate limiting (the server half)
- Authentication Patterns
- Router Authentication Guide
Foundation Concepts:
Step-by-Step Tutorials: