La Falsa Sensación de Seguridad

Un patrón común en tutoriales y plantillas de inicio de SvelteKit coloca la lógica de autenticación dentro de una función load de un layout. El layout raíz o un layout de sección verifica si hay una sesión válida, redirige a los usuarios no autenticados a la página de inicio de sesión y adjunta los datos del usuario al objeto retornado. Los componentes de página reciben al usuario a través de data.user. Todo parece funcionar.

El problema es que no siempre funciona. Funciona para la primera navegación completa a cualquier página en ese layout. Funciona cuando se recarga el navegador. Pero para las navegaciones del lado del cliente dentro del mismo layout, la función load del layout frecuentemente no se vuelve a ejecutar. Una solicitud no autenticada puede pasar a una función load del servidor que asume que la autenticación ya fue verificada. La redirección que se suponía debía ejecutarse simplemente no lo hace.

Esto no es un caso extremo sutil. Es el comportamiento predeterminado del sistema de rastreo de dependencias de SvelteKit, que opera exactamente como está documentado y exactamente como fue diseñado. Las funciones load solo se vuelven a ejecutar cuando sus entradas rastreadas cambian. Una navegación de /app/posts a /app/analytics cambia la URL, pero si la función load del layout de la aplicación no lee url.pathname y no tiene la nueva ruta en su conjunto de dependencias, esa función load es omitida. La carga de la página se ejecuta de nuevo. La carga del layout reutiliza su resultado anterior.

Si toda tu lógica de autenticación vive en la función load del layout, tienes una vulnerabilidad real en tu aplicación y un error difícil de reproducir. Entender por qué ocurre esto y qué hacer al respecto es el tema de este artículo.

Todos los ejemplos siguen la convención de la serie: sin ORMs, sin clientes de base de datos en funciones load. Todo acceso a datos usa llamadas fetch simples a endpoints de API.

Por Qué los Guards de Layout Fallan Silenciosamente

Para hacer concreta la vulnerabilidad, considera una aplicación protegida simple. Hay un layout de la aplicación en src/routes/app/+layout.server.ts. El desarrollador coloca una verificación de autenticación allí. Cualquier ruta bajo /app está protegida.

// src/routes/app/+layout.server.ts
// A layout guard that appears to protect all routes under /app.
// The guard works correctly on initial hard navigation.
// It does NOT reliably fire during client-side navigation.

import type { LayoutServerLoad } from './$types'
import { redirect } from '@sveltejs/kit'

export const load: LayoutServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	return { user: locals.user }
}

Ahora considera esta secuencia de eventos:

El usuario navega directamente a /app/posts. La carga del layout de la aplicación se ejecuta. locals.user es válido. La redirección no se dispara. La página carga.
La sesión del usuario expira en el servidor. locals.user ahora será null en cualquier nueva solicitud al servidor.
El usuario hace clic en un enlace hacia /app/analytics. SvelteKit realiza una navegación del lado del cliente.

En el paso 3, SvelteKit evalúa qué funciones load necesitan volver a ejecutarse. La función load del layout de la aplicación leyó locals.user en el paso 1, pero locals no es una dependencia rastreada. Las entradas rastreadas son params, url, route y parent(). Ninguna de ellas cambió de una manera en que el layout de la aplicación haya registrado interés. SvelteKit omite completamente la carga del layout de la aplicación y reutiliza el resultado del paso 1.

La carga de la página para /app/analytics sí se ejecuta, porque es una página nueva. Su función load del servidor recibe los locals actuales, donde locals.user ahora es null. Si esa carga de página no tiene su propia verificación de autenticación, se ejecuta sin un usuario válido y retorna datos al componente de página que ahora no tiene ninguna sesión legítima detrás.

El layout mantiene datos de autenticación obsoletos del paso 1. El componente de página se renderiza con ese usuario obsoleto. La sesión es inválida, pero la UI no lo sabe.

El diagrama de secuencia muestra la brecha claramente. La carga del layout se omite durante la navegación del lado del cliente. La carga de la página se ejecuta pero no tiene guard. El objeto de usuario obsoleto de la carga anterior del layout llena la prop data.

Por Qué las Funciones Load Funcionan de Esta Manera

El comportamiento es intencional. El rastreo de dependencias de SvelteKit existe para hacer rápida la navegación del lado del cliente. Si cada carga de layout se volviera a ejecutar en cada navegación, las aplicaciones serían lentas. La navegación de /app/posts a /app/analytics comparte el mismo layout raíz y el layout de la aplicación. Esos layouts cargan la estructura de navegación, los datos del perfil del usuario y la configuración del sitio. Volver a obtener todo eso en cada clic anularía el propósito del enrutamiento del lado del cliente.

El sistema de rastreo de dependencias está documentado y las reglas son precisas. Una función load se vuelve a ejecutar cuando uno de sus entradas rastreadas cambia: un parámetro de ruta que leyó, una propiedad de URL que accedió, o una dependencia que declaró con depends(). El objeto locals no es una dependencia rastreada. Leer locals.user dentro de una función load no registra una dependencia sobre la sesión del usuario. Si la sesión cambia entre navegaciones, la función load no tiene mecanismo para enterarse.

Este es el comportamiento correcto para la mayoría de los datos cargados en el layout. Sería contraproducente que la carga de navegación se volviera a ejecutar cada vez que locals cambia. El framework no tiene manera de saber qué cambios en locals son significativos para qué funciones load. Deja ese juicio a tu criterio.

La solución no es trabajar en contra de este comportamiento. Es colocar la aplicación de autenticación en lugares que se ejecuten de forma confiable, y entender qué garantiza cada ubicación.

Las Tres Estrategias

Hay tres lugares distintos donde la lógica de autenticación puede vivir en una aplicación SvelteKit. Cada uno tiene una garantía de ejecución diferente, un alcance de protección diferente y un caso de uso apropiado diferente.

Estrategia 1: El Hook Handle

El hook handle en src/hooks.server.ts es un interceptor que envuelve cada solicitud al servidor. "Cada solicitud al servidor" significa la carga inicial de la página, cada llamada a la API y cada fetch interno que SvelteKit realiza para ejecutar funciones load del servidor durante la navegación del lado del cliente. El hook se ejecuta antes que cualquier función load. Su responsabilidad principal es llenar event.locals con datos de sesión validados.

Esta es la única estrategia que es incondicionalmente confiable. Debido a que se ejecuta para cada solicitud que llega al servidor, no puede ser eludida por los patrones de navegación del lado del cliente.

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	const sessionId = event.cookies.get('sid')

	if (!sessionId) {
		// No session cookie. locals.user remains undefined.
		// Individual load functions decide how to handle this.
		return resolve(event)
	}

	const response = await event.fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	if (response.ok) {
		const { user } = await response.json()
		event.locals.user = user
	}

	return resolve(event)
}

Nótese el uso de event.fetch en lugar del fetch global. Dentro del hook handle, event.fetch maneja correctamente las solicitudes al mismo origen, reenvía cookies y funciona en todos los entornos. Usar el fetch global con una URL codificada como http://localhost:5173 es un error común que funciona en el desarrollo local pero se rompe en cualquier otro entorno — staging, producción, despliegues en contenedores. Siempre usa event.fetch para llamadas a la API dentro del hook.

El hook llena event.locals.user cuando la sesión es válida. Lo deja undefined cuando la sesión falta o es inválida. Cada función load que se ejecuta dentro de esta solicitud puede leer event.locals.user con la certeza de que refleja el estado actual de la sesión del lado del servidor, porque el hook se ejecutó primero y la sesión fue verificada durante esta misma solicitud.

Cuando SvelteKit realiza una navegación del lado del cliente hacia /app/analytics, hace una solicitud al servidor para ejecutar el +page.server.ts de esa ruta. Esa solicitud pasa por el hook handle. El hook valida la sesión de nuevo para esta solicitud. locals.user es preciso en el momento en que se ejecuta la carga de la página. Si la sesión expiró, locals.user es undefined para esta solicitud, independientemente de lo que cualquier carga anterior del layout haya calculado.

El hook se encarga de la población. La aplicación es una responsabilidad separada.

Estrategia 2: Guards en Funciones Load del Servidor a Nivel de Página y Layout

Colocar una verificación de redirección dentro de un +page.server.ts es confiable porque la carga de la página se ejecuta en cada navegación a esa página específica, tanto directa como del lado del cliente. Cada vez que el usuario llega a /app/analytics, la carga de la página de analytics se ejecuta y verifica locals.user. Si la sesión expiró, la verificación lo detecta.

// src/routes/app/analytics/+page.server.ts
// A page-level auth guard. Reliable for this specific route.
// Runs on every navigation to /app/analytics regardless of how the user arrived.

import type { PageServerLoad } from './$types'
import { redirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, url, fetch }) => {
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}

	const response = await fetch(`/api/analytics/dashboard?userId=${locals.user.id}`)

	return {
		analytics: response.ok ? await response.json() : null
	}
}

La limitación es la repetición. Si la aplicación tiene veinte rutas bajo /app, cada una necesita este guard. Un desarrollador que agrega una nueva ruta y olvida el guard tiene un endpoint desprotegido. Esta es la principal debilidad de depender exclusivamente de guards a nivel de página.

Los guards a nivel de layout en src/routes/app/+layout.server.ts proporcionan una cobertura más amplia, pero con la advertencia descrita en la sección del espacio del problema. Se ejecutan de forma confiable en la navegación inicial a cualquier ruta bajo /app. Pueden omitirse en navegaciones posteriores del lado del cliente dentro del mismo layout si ninguna dependencia rastreada cambió.

El híbrido práctico es usar ambos. El guard del layout proporciona protección amplia para la navegación inicial y una primera línea de defensa razonable. Los guards de página proporcionan protección confiable para la navegación continua del lado del cliente dentro del mismo layout, y vuelven a verificar el estado de la sesión para cada solicitud al servidor que manejan.

Estrategia 3: Usar Datos del Padre para el Estado de Autenticación, con Advertencias

Una función load de página puede llamar a await parent() para obtener el objeto de usuario que la carga del layout raíz obtuvo. Este patrón es común y no es intrínsecamente incorrecto, pero debe entenderse con precisión.

// src/routes/app/profile/+page.server.ts
// Using parent() to access user data.

import type { PageServerLoad } from './$types'
import { redirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ parent, fetch }) => {
	// parent() returns the merged data from ancestor layout loads.
	// This DOES include the user from the root layout server load.
	const { user } = await parent()

	if (!user) {
		redirect(303, '/login')
	}

	// user.id is used to construct the fetch URL.
	const response = await fetch(`/api/users/${user.id}/profile`)
	return { profile: response.ok ? await response.json() : null }
}

Aquí está la limitación precisa: await parent() retorna datos que fueron resueltos durante esta solicitud al servidor específica. Si la carga del layout raíz se ejecutó durante esta solicitud (ya sea porque es una navegación directa o porque las dependencias rastreadas del layout raíz cambiaron), los datos del usuario son frescos. Si el layout raíz fue omitido para esta navegación del lado del cliente, los datos del usuario en parent() provienen de la ejecución anterior.

Durante una navegación del lado del cliente, el +page.server.ts se ejecuta en el servidor. En el servidor, los datos del layout raíz se reconstruyen para la respuesta a través del proceso de fusión. Si el layout raíz realmente se volvió a ejecutar depende de las mismas reglas de rastreo de dependencias. Si no se volvió a ejecutar, parent() en la carga de la página retorna la salida del layout previamente en caché.

Esto significa que await parent() no garantiza datos de sesión frescos. Te da lo que el framework calculó para los datos del padre en esta solicitud. Para verificaciones de autenticación confiables dentro de las cargas de página, leer locals.user directamente es el enfoque correcto. locals se llena de nuevo por el hook handle para cada solicitud. Siempre está actualizado.

// Preferred: read locals.user directly in page server loads for auth checks.
// locals is populated by the handle hook on every request without exception.

import type { PageServerLoad } from './$types'
import { redirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, url, fetch }) => {
	// locals.user reflects the session state at the time of THIS request.
	// The handle hook validated the session before this load function ran.
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}

	const response = await fetch(`/api/users/${locals.user.id}/profile`)
	return { profile: response.ok ? await response.json() : null }
}

await parent() es apropiado cuando necesitas datos del usuario que el layout calculó, y donde ese cálculo es más complejo que lo que está almacenado en locals. La carga inicial del layout podría enriquecer el objeto de usuario con permisos, preferencias o contexto de tenant que es costoso de recalcular. Pasar eso a través de parent() está bien, con el entendimiento de que puede reflejar una solicitud anterior si el layout fue omitido.

Para la verificación binaria de autenticación (¿está el usuario conectado?), usa locals.user. Es más barato, más directo y siempre está actualizado.

Cómo locals Se Integra con las Funciones Load

El objeto locals es el puente principal entre la capa de hooks y la capa de funciones load. Entender exactamente qué es y cuándo está disponible previene confusiones sobre por qué algunos patrones funcionan y otros no.

locals es un objeto JavaScript simple adjunto al evento de solicitud. Comienza vacío. El hook handle lo llena. Cada función load del servidor que recibe el mismo objeto de evento lee del mismo locals. Está limitado a una única solicitud HTTP. Dos solicitudes concurrentes tienen objetos locals separados.

Todas las funciones load del servidor dentro de una única solicitud comparten el mismo locals. El hook se ejecuta primero, luego se ejecutan las funciones load. Este orden está garantizado. No hay condición de carrera donde una función load pueda leer locals antes de que el hook lo haya llenado.

locals se tipifica a través de una declaración en src/app.d.ts. Sin la declaración, TypeScript no puede saber qué campos esperar:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: {
				id: string
				name: string
				email: string
				role: 'user' | 'editor' | 'admin'
			} | null
		}
	}
}

export {}

Con esta declaración en su lugar, TypeScript sabe que locals.user es un objeto de usuario o null, y te pedirá que manejes ambos casos. Una función load que lee locals.user sin verificar si es null producirá un error de tipo si el código posterior lo trata como no anulable. Esto es el sistema de tipos aplicando el patrón: siempre verificar antes de confiar.

// src/routes/app/+layout.server.ts
// TypeScript knows locals.user might be null.
// Failing to check before accessing user.id would be a type error.

import type { LayoutServerLoad } from './$types'
import { redirect } from '@sveltejs/kit'

export const load: LayoutServerLoad = async ({ locals, url }) => {
	// Without this check, TypeScript would complain: 'locals.user' is possibly null.
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}

	// After the null check, TypeScript narrows the type.
	// locals.user is now known to be non-null below this point.
	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			role: locals.user.role
		}
	}
}

El estrechamiento de tipo después de la verificación de null no es cosmético. Significa que cada referencia posterior a locals.user debajo del guard está garantizada por el sistema de tipos como no nula. TypeScript detectará cualquier intento de acceder al usuario sin una verificación previa.

Construyendo una Utilidad requireLogin() con getRequestEvent()

El patrón repetido de verificar locals.user y llamar a redirect(303, '/login') a través de docenas de funciones load es una fricción. Cada nueva ruta necesita el mismo código repetitivo. Si la URL de inicio de sesión cambia, cada archivo necesita actualizarse. Si quieres agregar limitación de velocidad o registro a los fallos de autenticación, actualizas docenas de archivos.

SvelteKit proporciona getRequestEvent() desde $app/server para resolver exactamente este problema. Retorna el RequestEvent actual desde cualquier función del lado del servidor que se esté ejecutando dentro del contexto de una solicitud. Esto significa que puedes escribir una función utilitaria que lea locals y llame a redirect sin necesitar que el evento se pase como argumento. Cualquier función load del servidor puede llamar a la utilidad sin necesitar pasar el objeto de evento a través de la cadena de llamadas.

// src/lib/server/auth.ts
// Reusable auth utilities using getRequestEvent().
// Call these from any server load function or server-side helper.

import { getRequestEvent } from '$app/server'
import { redirect, error } from '@sveltejs/kit'

/**
 * Requires the current request to have an authenticated user.
 * Redirects to /login with a returnTo parameter if not.
 * Returns the validated user object on success.
 */
export function requireLogin() {
	const event = getRequestEvent()
	const user = event.locals.user

	if (!user) {
		const returnTo = encodeURIComponent(event.url.pathname + event.url.search)
		redirect(303, `/login?returnTo=${returnTo}`)
	}

	return user
}

/**
 * Requires the current request to have an authenticated user with a specific role.
 * Redirects to /login if not authenticated.
 * Throws a 403 error if authenticated but lacks the required role.
 */
export function requireRole(role: 'editor' | 'admin') {
	const user = requireLogin()

	if (user.role !== role) {
		error(403, `This page requires the ${role} role.`)
	}

	return user
}

/**
 * Returns the current user without requiring authentication.
 * Returns null if not authenticated.
 * Use this for pages that adapt their content based on auth state
 * but do not require it.
 */
export function getOptionalUser() {
	const event = getRequestEvent()
	return event.locals.user
}

Con estas utilidades en su lugar, una función load protegida se convierte en:

// src/routes/app/posts/+page.server.ts
// Before: 6 lines of boilerplate per protected route.
// After: one function call.

import type { PageServerLoad } from './$types'
import { requireLogin } from '$lib/server/auth'

export const load: PageServerLoad = async ({ url, fetch }) => {
	const user = requireLogin()
	// If not logged in, requireLogin() calls redirect() and never returns.
	// Execution only reaches here with a valid, non-null user.

	const status = url.searchParams.get('status') ?? 'published'
	const page = Number(url.searchParams.get('page') ?? '1')

	const response = await fetch(`/api/users/${user.id}/posts?status=${status}&page=${page}`)

	return {
		posts: response.ok ? await response.json() : [],
		currentStatus: status,
		currentPage: page
	}
}

Nótese que el objeto event no se pasa a requireLogin(). La función llama a getRequestEvent() internamente para recuperarlo. Esto elimina el acoplamiento entre la interfaz de la función utilitaria y la forma del evento load de SvelteKit. La utilidad también puede ser llamada desde funciones auxiliares anidadas, siempre que esas funciones se ejecuten dentro del mismo contexto de solicitud al servidor.

La utilidad basada en roles funciona de la misma manera:

// src/routes/admin/users/+page.server.ts

import type { PageServerLoad } from './$types'
import { requireRole } from '$lib/server/auth'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ url, fetch }) => {
	// requireRole() calls requireLogin() internally.
	// If not logged in: redirects to /login.
	// If logged in but not admin: throws 403.
	// If admin: returns the admin user.
	const adminUser = requireRole('admin')

	const page = Number(url.searchParams.get('page') ?? '1')
	const response = await fetch(`/api/admin/users?page=${page}&perPage=25`)

	if (!response.ok) {
		error(500, 'Failed to load user list')
	}

	const { users, total } = await response.json()

	return {
		users,
		currentPage: page,
		total,
		adminName: adminUser.name
	}
}

Alcance y limitaciones de getRequestEvent()

getRequestEvent() está disponible desde SvelteKit 2.20.0. Funciona dentro de contextos de solicitud exclusivos del servidor: hooks.server.ts, +page.server.ts, +layout.server.ts, rutas de API +server.ts, y cualquier función llamada desde esos contextos dentro del mismo ciclo de vida de solicitud.

No funciona en funciones load universales (+page.ts / +layout.ts). Las funciones load universales no son un contexto soportado independientemente de si resultan estar ejecutándose en el servidor durante SSR — no son módulos exclusivos del servidor, por lo que getRequestEvent() no está disponible para ellas. Tampoco funciona en el momento de inicialización del módulo, durante la construcción, ni en ningún código que se ejecute fuera de una solicitud activa.

Si se llama a getRequestEvent() fuera de un contexto de solicitud válido, lanza un error claro en lugar de retornar un evento obsoleto o undefined. Esto hace que el uso incorrecto sea obvio en vez de silencioso.

Una advertencia adicional: en entornos que no soportan AsyncLocalStorage, getRequestEvent() debe llamarse de forma síncrona, es decir, no después de un await. La mayoría de los runtimes de servidor modernos (Node.js, Deno, Bun, Cloudflare Workers) soportan AsyncLocalStorage, por lo que en la práctica esta restricción rara vez aplica. Pero si apuntas a un entorno de despliegue inusual, llama a getRequestEvent() al inicio de la función antes de cualquier await.

// This would throw at build time or in a module that initializes outside a request.
// getRequestEvent() is safe to call, but call it where you know a request is active.

// Safe: inside a load function, hook, or function called from those.
export const load: PageServerLoad = async () => {
	const user = requireLogin() // calls getRequestEvent() inside a request context. Safe.
	return { user }
}

// Unsafe: at module top level, which runs during server initialization.
// const user = requireLogin() // Would throw. No request context at this point.

La regla general: getRequestEvent() es seguro en cualquier lugar donde el framework haya comenzado a manejar una solicitud HTTP específica y aún no haya enviado la respuesta final.

Cuándo Usar Hooks vs Guards en Funciones Load

Las dos capas sirven propósitos diferentes. Usarlas correctamente significa colocar cada responsabilidad en la capa que es adecuada para ella, sin duplicar lógica en ambas.

El hook handle es para población, no para aplicación. Su trabajo es tomar la solicitud HTTP sin procesar, extraer el identificador de sesión, validarlo y adjuntar el usuario resultante a locals. Esto debe ocurrir para cada solicitud, sin excepción. El hook no redirige a usuarios no autenticados. Simplemente refleja el estado honesto de la sesión en locals.

Los guards en funciones load son para la aplicación. Leen desde locals y deciden qué hacer con lo que encuentran. Una ruta protegida redirige. Una ruta que se adapta al estado de autenticación renderiza diferente basándose en si locals.user está presente. Una ruta que es completamente pública ignora locals.user. La decisión se toma por función load.

Esta separación tiene un beneficio concreto: el costo de validación de sesión se paga exactamente una vez por solicitud, en el hook, independientemente de cuántas funciones load se ejecuten durante el ciclo de vida de esa solicitud. Si en cambio colocas la validación de sesión en cada función load, cada función load protegida que se ejecuta para una solicitud hace su propia llamada de validación de sesión. Una jerarquía de layout de tres niveles podría hacer tres llamadas de validación para una sola carga de página, todas retornando el mismo resultado.

Request to /app/analytics:

  hooks.server.ts: handle()       One session validation call.   locals.user populated.
  +layout.server.ts: load()       Reads locals.user.             Skipped or runs auth check.
  +layout.server.ts: load()       Reads locals.user.             Runs auth check.
  +page.server.ts: load()         Reads locals.user.             Runs auth check.

  Total session validation calls: 1 (in the hook)
  Auth checks in load functions:  2 or 3 (redirect or continue based on locals)

Las verificaciones de autenticación en las funciones load son económicas. Leen un valor ya en memoria y ya sea llaman a redirect o continúan. La operación costosa es la validación de sesión, y el hook garantiza que ocurra solo una vez.

La cuestión de si hacer el guard a nivel de layout, a nivel de página o en ambos depende de los requisitos de seguridad de tu aplicación:

Para aplicaciones donde el layout mismo retorna datos sensibles (el perfil de un usuario administrador, una configuración específica de tenant), la carga del layout debe tener un guard. Esos datos no deben retornarse para solicitudes no autenticadas. Usa el guard del layout para este caso aunque sepas que puede omitirse en navegaciones del lado del cliente, porque:

En navegaciones del lado del cliente, la carga del servidor de la página se ejecuta y su guard se dispara.
Los datos sensibles del layout están en caché de la ejecución anterior. Si la sesión era válida entonces, los datos fueron producidos legítimamente.
Si la sesión expiró y la carga del servidor de la página lo detecta y redirige, los datos del layout en caché nunca se envían al navegador en una nueva respuesta.

Para aplicaciones donde la carga de la página obtiene datos que requieren un usuario válido (construir una URL con locals.user.id, por ejemplo), la carga de la página debe tener un guard. No puede proceder sin un usuario válido. El guard de la página no es opcional aquí independientemente de lo que haga el layout.

El enfoque recomendado para la mayoría de las aplicaciones:

hooks.server.ts:         Validate session. Populate locals.user. Never redirect.
+layout.server.ts:       Guard if the layout itself returns sensitive data.
                         Otherwise, skip the guard and let page loads handle it.
+page.server.ts:         Guard every protected page. Use requireLogin() or a
                         direct locals.user check. This is the reliable layer.

Ejemplo Práctico: Una Aplicación Protegida con Control de Roles

El siguiente ejemplo completo muestra las tres capas trabajando juntas: el hook popula locals, el layout de la aplicación proporciona una guarda ligera para su propio output sensible, y las cargas de páginas individuales usan requireLogin() y requireRole() para un control preciso.

Declaración de la app

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: {
				id: string
				name: string
				email: string
				role: 'user' | 'editor' | 'admin'
				avatarUrl: string
			} | null
		}
	}
}

export {}

El hook handle

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	const sessionId = event.cookies.get('sid')

	if (!sessionId) {
		return resolve(event)
	}

	const response = await event.fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	if (response.ok) {
		const { user } = await response.json()
		event.locals.user = user
	}

	return resolve(event)
}

Las utilidades de autenticación

// src/lib/server/auth.ts

import { getRequestEvent } from '$app/server'
import { redirect, error } from '@sveltejs/kit'

export function requireLogin() {
	const event = getRequestEvent()

	if (!event.locals.user) {
		const returnTo = encodeURIComponent(event.url.pathname + event.url.search)
		redirect(303, `/login?returnTo=${returnTo}`)
	}

	return event.locals.user
}

export function requireRole(role: 'editor' | 'admin') {
	const user = requireLogin()

	if (user.role !== role) {
		error(403, `Access requires the ${role} role.`)
	}

	return user
}

export function getOptionalUser() {
	return getRequestEvent().locals.user
}

El layout de la sección de la app

// src/routes/app/+layout.server.ts
// Guards the layout's own output (the user nav data).
// Also provides a first line of defense on initial hard navigation.

import type { LayoutServerLoad } from './$types'
import { redirect } from '@sveltejs/kit'

export const load: LayoutServerLoad = async ({ locals, url }) => {
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}

	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			avatarUrl: locals.user.avatarUrl,
			role: locals.user.role
		}
	}
}

Una página protegida estándar

// src/routes/app/posts/+page.server.ts
// Page-level guard using the requireLogin() utility.
// Reliable on every navigation: hard and client-side.

import type { PageServerLoad } from './$types'
import { requireLogin } from '$lib/server/auth'

export const load: PageServerLoad = async ({ url, fetch }) => {
	const user = requireLogin()

	const status = url.searchParams.get('status') ?? 'published'
	const page = Number(url.searchParams.get('page') ?? '1')

	const response = await fetch(
		`/api/users/${user.id}/posts?status=${status}&page=${page}&perPage=20`
	)

	return {
		posts: response.ok ? await response.json() : [],
		currentPage: page,
		currentStatus: status
	}
}

Una página solo para administradores

// src/routes/app/admin/users/+page.server.ts

import type { PageServerLoad } from './$types'
import { requireRole } from '$lib/server/auth'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ url, fetch }) => {
	requireRole('admin')

	const page = Number(url.searchParams.get('page') ?? '1')

	const response = await fetch(`/api/admin/users?page=${page}&perPage=25`)

	if (!response.ok) {
		error(500, 'Failed to load users')
	}

	const { users, total } = await response.json()

	return {
		users,
		currentPage: page,
		total,
		totalPages: Math.ceil(total / 25)
	}
}

Una página pública que se adapta al estado de autenticación

// src/routes/blog/[slug]/+page.server.ts
// Public route. No guard. Adapts its output based on whether
// a user is logged in, using getOptionalUser().

import type { PageServerLoad } from './$types'
import { getOptionalUser } from '$lib/server/auth'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, fetch }) => {
	const user = getOptionalUser()

	const postPromise = fetch(`/api/blog/posts/${params.slug}`)
	const historyPromise = user
		? fetch(`/api/users/${user.id}/reading-history/check?slug=${params.slug}`)
		: Promise.resolve(null)

	const [postResponse, historyResponse] = await Promise.all([postPromise, historyPromise])

	if (!postResponse.ok) {
		error(404, 'Post not found')
	}

	const post = await postResponse.json()
	const hasReadBefore = historyResponse?.ok ? (await historyResponse.json()).hasRead : false

	return {
		post,
		isAuthenticated: user !== null,
		hasReadBefore
	}
}

El componente del layout de la app

<!-- src/routes/app/+layout.svelte -->

<script lang="ts">
	import type { LayoutProps } from './$types'

	let { data, children }: LayoutProps = $props()

	const initials = $derived(
		data.user.name
			.split(' ')
			.map((part: string) => part[0])
			.join('')
			.toUpperCase()
			.slice(0, 2)
	)
</script>

<div class="app-shell">
	<nav class="app-nav">
		<a href="/app" class="app-brand">Hackpile</a>

		<ul class="app-nav-links">
			<li><a href="/app/posts">Posts</a></li>
			<li><a href="/app/analytics">Analytics</a></li>
			{#if data.user.role === 'admin'}
				<li><a href="/app/admin/users">Admin</a></li>
			{/if}
		</ul>

		<div class="app-user">
			{#if data.user.avatarUrl}
				<img src={data.user.avatarUrl} alt={data.user.name} class="user-avatar" />
			{:else}
				<span class="user-initials" aria-label={data.user.name}>{initials}</span>
			{/if}
			<span class="user-name">{data.user.name}</span>
		</div>
	</nav>

	<main class="app-content">
		{@render children()}
	</main>
</div>

La visibilidad del enlace de administración es una guarda de UI, no un mecanismo de control de acceso. El componente lee data.user.role y muestra u oculta el enlace de administración según corresponda. Esto no protege las rutas de administración. Si un usuario con un rol no administrador navega directamente a /app/admin/users, la carga del servidor de la página llama a requireRole('admin'), que llama a requireLogin() y luego verifica el rol, y redirige o lanza un 403 dependiendo del estado de autenticación. La UI simplemente evita mostrar un enlace que fallaría de inmediato.

Esta distinción entre guardas de UI y guardas de rutas se aplica universalmente. Ocultar un botón, enlace o sección basándose en el rol es un comportamiento apropiado del lado del cliente. Mejora la experiencia del usuario. No es control de acceso. El control de acceso ocurre en el servidor, en la función de carga, donde el locals.user validado por el servidor está disponible.

Errores Comunes y Anti-Patrones

Depender exclusivamente de guardas de carga en layouts sin guardas de página

// Avoid: a layout that provides all auth protection,
// with page loads that assume authentication was verified.

// src/routes/app/+layout.server.ts
export const load: LayoutServerLoad = async ({ locals, url }) => {
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}
	return { user: locals.user }
}

// src/routes/app/analytics/+page.server.ts
// No guard here. Assumes the layout protected us. Vulnerable on
// client-side navigations if the session expires mid-session.
export const load: PageServerLoad = async ({ locals, fetch }) => {
	// locals.user might be null here on a client-side navigation
	// where the layout load was skipped. This line would throw.
	const response = await fetch(`/api/analytics/${locals.user!.id}/summary`)
	return { analytics: await response.json() }
}

// Preferred: page loads use requireLogin() (or a direct locals check)
// to enforce auth regardless of what the layout did.

export const load: PageServerLoad = async ({ fetch }) => {
	const user = requireLogin()

	const response = await fetch(`/api/analytics/${user.id}/summary`)
	return { analytics: response.ok ? await response.json() : null }
}

Tratar los datos del layout como estado de autenticación autoritativo

// Avoid: reading auth state from parent() and treating it as reliable
// for security decisions within a server load.

export const load: PageServerLoad = async ({ parent, fetch }) => {
	const { user } = await parent()

	// parent() may return cached layout data from a previous run.
	// Do not make security decisions based on this value alone.
	if (!user) {
		redirect(303, '/login')
	}

	// ...
}

// Preferred: use locals.user for security decisions.
// Use parent() data only for values the layout computed that are
// more complex than what locals contains (enriched permissions, etc.).

export const load: PageServerLoad = async ({ locals, parent, fetch }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	// parent() can be used for enriched data from the layout, not for
	// the auth check itself.
	const { tenantConfig } = await parent()

	const response = await fetch(`/api/${tenantConfig.apiPrefix}/posts`)
	return { posts: response.ok ? await response.json() : [] }
}

Redirigir en lugar de retornar un 403 ante fallos de autorización

// Avoid: sending an authenticated user to /login when they lack permission.
// The user IS logged in. Sending them to login implies their session is broken.
// They will log in successfully and be redirected back to the same forbidden page.

export const load: PageServerLoad = async ({ locals, url }) => {
	if (!locals.user || locals.user.role !== 'admin') {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}
	// ...
}

// Preferred: separate the authentication check from the authorization check.
// Unauthenticated users go to /login. Authenticated non-admins get a 403.

export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	if (locals.user.role !== 'admin') {
		error(403, 'This page requires administrator access.')
	}

	// ...
}

La utilidad requireRole() codifica este patrón automáticamente. Usarla significa que la verificación nunca se escribe incorrectamente a mano.

Poner la validación de sesión dentro de las funciones de carga en lugar del hook

// Avoid: each load function that needs auth makes its own session call.
// A three-level route hierarchy makes up to three validation calls per request.

// src/routes/+layout.server.ts
export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('sid')
	const response = await fetch('/api/session/validate', {
		/* ... */
	})
	const user = response.ok ? (await response.json()).user : null
	return { user }
}

// src/routes/app/+layout.server.ts
export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	// Validates the same session again. Same network call. Same result.
	const sessionId = cookies.get('sid')
	const response = await fetch('/api/session/validate', {
		/* ... */
	})
	const user = response.ok ? (await response.json()).user : null
	if (!user) redirect(303, '/login')
	return { user }
}

// Preferred: validate once in the hook, read from locals in every load function.
// Zero redundant session calls. locals.user is current for the entire request.

// hooks.server.ts validates once.
// Load functions read locals.user.

export const load: LayoutServerLoad = async ({ locals }) => {
	if (!locals.user) redirect(303, '/login')
	return { user: locals.user }
}

Consideraciones de Rendimiento y Escalabilidad

La validación de sesión es típicamente la operación más costosa en el stack de autenticación: una llamada de red a una base de datos o almacén de sesiones, una verificación de token, una búsqueda en caché. Hacerlo una vez en el hook y pasar el resultado a través de locals mantiene el costo constante independientemente de la complejidad de la ruta. Una aplicación con una jerarquía de layouts de diez niveles sigue haciendo una sola llamada de validación de sesión por solicitud.

La utilidad requireLogin() lee desde locals sin realizar llamadas de red adicionales. Es una lectura sincrónica en memoria más un redirect() opcional. El costo es insignificante.

Para aplicaciones de alto tráfico, la llamada de validación de sesión en el hook puede convertirse en un cuello de botella. Las mitigaciones comunes incluyen el uso de un token autocontenido y firmado (JWT con una expiración corta) que puede verificarse criptográficamente sin una llamada de red, y el almacenamiento en caché de sesiones validadas en memoria o en un almacén rápido como Redis con un TTL corto. La implementación del hook permanece igual: extraer el identificador, validarlo, adjuntar el resultado a locals. La implementación de la validación cambia de una llamada a base de datos a una verificación criptográfica o una búsqueda en caché.

La guarda del layout sirve como una salida temprana para todo el subárbol de funciones de carga. Si +layout.server.ts redirige a un usuario no autenticado, ninguna de las funciones de carga de página en esa sección se ejecuta. Este es el beneficio de rendimiento de las guardas a nivel de layout que las guardas a nivel de página por sí solas no proporcionan: para navegaciones duras iniciales, la guarda del layout evita que se ejecuten las funciones de carga posteriores. Para navegaciones del lado del cliente donde el layout se omite, la guarda de carga de página captura el fallo a nivel de página.

Para rutas con múltiples capas de verificaciones de permisos (autenticado Y editor Y tenant validado), considera construir una utilidad compuesta en lugar de encadenar llamadas separadas. Cada llamada a requireRole() es económica, pero componerlas en una sola utilidad mejora la legibilidad y hace que el requisito completo de permisos sea explícito de un vistazo:

// src/lib/server/auth.ts — extended utilities

export function requireEditorAccess() {
	const user = requireLogin()

	if (user.role !== 'editor' && user.role !== 'admin') {
		error(403, 'Editor access required.')
	}

	return user
}

export function requireAdminOrSelf(targetUserId: string) {
	const user = requireLogin()

	if (user.id !== targetUserId && user.role !== 'admin') {
		error(403, 'You can only access your own data.')
	}

	return user
}

Estos composites documentan los requisitos de acceso a nivel de utilidad en lugar de duplicar la lógica en las funciones de carga. Cuando los requisitos de acceso cambian, se actualiza en un solo lugar.

Qué Sigue

Este es el artículo final de la serie SvelteKit Data Loading. La serie ha cubierto el ciclo de vida completo de los datos del servidor en una aplicación SvelteKit: cómo se estructuran las funciones de carga, cómo fluyen los datos a través de la jerarquía de layouts, cómo se controlan las solicitudes y respuestas, cómo las funciones de carga deciden cuándo volver a ejecutarse, y cómo la autenticación se integra con cada capa del stack.

Ver También

Errores y Redirecciones en Funciones de Carga — el artículo anterior de esta serie, que cubre error() y redirect() en detalle, incluyendo la trampa del try/catch que deshabilita silenciosamente las guardas de rutas
Volver a Ejecutar Funciones de Carga y Seguimiento de Dependencias — explica exactamente cuándo se vuelven a ejecutar las funciones de carga del layout y cuándo se omiten, que es el mecanismo que hace que las guardas solo en layouts sean poco confiables
Usar Datos del Padre en Funciones de Carga — cubre la mecánica de parent() en detalle, incluyendo qué retorna y por qué no es una fuente confiable del estado de autenticación actual en cargas de servidor de página
Cookies y Headers en Carga del Servidor — cubre la lectura de cookies de sesión en funciones de carga y la API setHeaders() para controlar el comportamiento de caché en páginas autenticadas
Documentación de Hooks de SvelteKit — referencia oficial para el hook handle, handleServerError, y el tipo completo RequestEvent incluyendo el campo locals
Documentación de getRequestEvent() de SvelteKit — referencia oficial para getRequestEvent() incluyendo sus requisitos de contexto y propiedades disponibles