SvelteKit Authentication Technical Reference

Critical Authentication Race Condition

Problem

Authentication works locally but fails in production with random logouts. Session cookies set during login don't arrive before SSR rendering completes.

Root Cause

Timing mismatch between cookie setting and server-side rendering:

• 0ms: SvelteKit starts rendering /dashboard on server
• 1ms: Server hook looks for session cookie - not present yet
• 2ms: Server renders "not authenticated" HTML
• 5ms: Browser receives "logged out" HTML
• 10ms: Login response completes, session cookie finally set
• 15ms: Client hydrates with server's "not authenticated" state

Solution

Use reactive patterns instead of imperative authentication checks:

// Reactive approach - works with SvelteKit's design
let sessionToken = $state($page.data.user?.token || null);

$effect(() => {
  if (sessionToken) {
    loadUserData(); // Runs whenever sessionToken changes
  } else {
    clearUserData();
  }
});

Production Cookie Configuration

Development vs Production Failure

Cookies work on http://localhost:3000 but fail with HTTPS in production due to missing security settings.

Production-Ready Cookie Settings

const isProduction = process.env.NODE_ENV === 'production';

event.cookies.set('session', sessionId, {
  path: '/',
  maxAge: 60 * 60 * 24 * 7,
  httpOnly: true,
  secure: isProduction, // HTTPS only in production
  sameSite: isProduction ? 'strict' : 'lax',
  domain: isProduction ? '.yourdomain.com' : undefined
});

Critical Domain Configuration

• Cookie set on api.example.com won't be sent to app.example.com
• Use .example.com (note leading dot) for subdomain sharing
• Production domain mismatch causes complete authentication failure

Resilient Server Hook Implementation

Fragile Pattern (Causes Random Logouts)

// DON'T USE - destroys sessions on any validation hiccup
if (sessionId) {
  const user = await validateSession(sessionId);
  if (user) {
    event.locals.user = user;
  } else {
    event.cookies.delete('session'); // Destroys sessions on network timeouts
    event.locals.user = null;
  }
}

Production-Resilient Pattern

// Survives network failures, database hiccups, backend 500 errors
if (sessionId) {
  try {
    const user = await validateSession(sessionId);
    if (user) {
      event.locals.user = user;
      event.locals.isAuthenticated = true;
    } else {
      // Session invalid - mark unauthenticated but keep cookie
      event.locals.user = null;
      event.locals.isAuthenticated = false;
    }
  } catch (error) {
    // Network/database error - assume unauthenticated but preserve session
    console.warn('Session validation failed:', error.message);
    event.locals.user = null;
    event.locals.isAuthenticated = false;
    // Cookie survives temporary failures
  }
}

Memory Leak Prevention

Session Storage Memory Leak

In-memory session storage kills production servers after 2-3 days of uptime.

Critical Warning: Never use MemoryStore in production

// This kills production servers
import session from 'express-session';
const store = new session.MemoryStore(); // Memory leak waiting to happen

Required Cleanup Strategy

// Cleanup job that must run
setInterval(async () => {
  await db.session.deleteMany({
    where: { expiresAt: { lt: new Date() } }
  });
}, 1000 * 60 * 60); // Every hour, delete expired sessions

Authentication Library Comparison

Solution	Production Ready	Time Investment	Maintenance Cost	Breaking Points
Auth.js (NextAuth)	Unreliable	2-4 hours	High	Session bugs, version conflicts, React assumptions
Lucia Auth	Dead Project	1-2 hours	Impossible	Deprecated March 2025, no security patches
Supabase Auth	Yes	30 minutes	Low	Vendor lock-in, limited customization
Firebase Auth	Yes	1-2 hours	Medium	Legacy patterns, client-centric model conflicts
Roll Your Own	Yes	3-6 hours	Medium	You own all bugs, full control

Auth.js Critical Issues

• Sessions expire randomly in production
• Version incompatibilities between SvelteKit upgrades
• Requires pinning to specific versions (SvelteKit 1.19.2 + Auth.js v4.20.8)
• Built for React patterns, not SvelteKit's server-first approach

Lucia Auth Deprecation Impact

• No updates after March 2025
• No security patches for discovered vulnerabilities
• Community scattering to other solutions
• Career risk for new projects

Common Production Failures

Entire User Base Logout After Deployment

Cause: JWT_SECRET changed or session database cleared during deployment
Emergency Fix: Rollback deployment
Prevention: Store JWT_SECRET in persistent environment variables

Mobile-Specific Session Expiration

Cause: Mobile browsers aggressively clear cookies during app switching
Solution: Use sameSite: 'lax' for cross-site functionality, test on actual iOS devices

Subdomain Authentication Failure

Cause: Cookie domain mismatch
Fix: Set cookie domain to .yourdomain.com for subdomain sharing

API Routes Accessible Without Authentication

Critical Security Issue: Frontend-only auth checks allow direct API access
Required Fix: Server-side auth validation on every protected route

// In every API route
if (!event.locals.isAuthenticated) {
  throw error(401, 'Unauthorized');
}

Roll-Your-Own Implementation Guide

Minimal Session Authentication

// lib/auth.js - ~50 lines of bulletproof auth
import bcrypt from 'bcryptjs';
import crypto from 'crypto';

export async function createSession(userId) {
  const sessionId = crypto.randomBytes(32).toString('hex');
  
  await db.session.create({
    data: {
      id: sessionId,
      userId: userId,
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
    }
  });
  
  return sessionId;
}

export async function validateSession(sessionId) {
  const session = await db.session.findFirst({
    where: { 
      id: sessionId,
      expiresAt: { gt: new Date() } // Critical expiration check
    },
    include: { user: true }
  });
  
  return session?.user || null;
}

OAuth Integration Pattern

// routes/auth/google/+server.js
export async function GET({ url, cookies }) {
  const code = url.searchParams.get('code');
  const googleUser = await exchangeCodeForUser(code);
  const user = await findOrCreateUser(googleUser);
  const sessionId = await createSession(user.id);
  
  cookies.set('session', sessionId, {
    path: '/',
    httpOnly: true,
    secure: true,
    maxAge: 60 * 60 * 24 * 7
  });
  
  throw redirect(303, '/dashboard');
}

Adapter-Specific Issues

Static Adapter Authentication Failure

Problem: adapter-static doesn't run server hooks, breaking all authentication
Solution: Use adapter-auto, adapter-node, or adapter-vercel for dynamic auth
Warning: CI configurations often default to static adapters for "performance optimization"

Adapter Auto-Detection Failures

Issue: adapter-auto sometimes picks wrong adapter in production
Solution: Explicitly specify adapter instead of trusting auto-detection

Critical Security Requirements

Session Validation Checks

Always verify session expiration:

const session = await db.session.findFirst({
  where: {
    id: sessionId,
    expiresAt: { gt: new Date() } // This check is critical
  }
});

JWT Secret Management

• Store in environment variables, never hardcode
• Consistent across deployments to prevent mass logouts
• Secret changes invalidate all existing sessions

CORS and Preflight Handling

Browser authentication requires:

• Proper CORS middleware for OPTIONS requests
• credentials: 'include' for cookie-based auth
• Correct preflight request handling

Performance and Monitoring

Session Cleanup Strategy

Required for database session storage:

• Hourly cleanup of expired sessions
• Background job that doesn't block application
• Monitoring for cleanup job failures

Production Monitoring Points

• Login success/failure rates
• Session duration analytics
• Authentication timing metrics
• Random logout frequency tracking

Development Environment Issues

Windows-Specific Problems

• Path length limits (260 characters) break session storage
• WSL2 filesystem weirdness affects cookie handling
• Docker networking conflicts between Windows/Linux containers
• Most Windows developers switch to Mac/Linux for authentication work

Hydration Mismatch Prevention

Use SvelteKit's universal load functions:

// +layout.server.js - Single source of truth
export async function load({ locals }) {
  return {
    user: locals.user,
    isAuthenticated: locals.isAuthenticated
  };
}

Resource Requirements

Time Investment Comparison

• Auth.js setup: 2-4 hours, high ongoing maintenance
• Roll-your-own: 3-6 hours initial, medium maintenance
• Supabase: 30 minutes setup, low maintenance but vendor lock-in

Expertise Requirements

• Understanding of HTTP cookies and sessions
• Knowledge of OWASP security guidelines
• Experience with production debugging
• Familiarity with SvelteKit's server-first architecture

Infrastructure Dependencies

• Database for session storage (avoid in-memory)
• Background job system for cleanup
• Production monitoring for auth failures
• Error tracking for session issues

Breaking Points and Failure Modes

At Scale Issues

• Session table grows indefinitely without cleanup
• Database connection pool exhaustion during login spikes
• Memory leaks from in-memory session storage
• Cookie storage limits affecting large session data

Security Failure Scenarios

• Session fixation attacks without proper session regeneration
• XSS attacks accessing non-httpOnly cookies
• CSRF attacks without proper token validation
• Session hijacking over non-HTTPS connections

Framework Compatibility Risks

• SvelteKit version upgrades breaking auth library compatibility
• Adapter changes affecting server hook execution
• Node.js version updates breaking cryptographic libraries
• Third-party library deprecation (like Lucia Auth)