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 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 login y adjunta los datos del usuario al objeto retornado. Los componentes de página reciben el usuario a través de data.user. Todo parece funcionar.

El problema es que no siempre funciona. Funciona para la primera navegación dura hacia cualquier página en ese layout. Funciona cuando recargas 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 inadvertida 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 dispararse simplemente no ocurre.

Esto no es un caso límite sutil. Es el comportamiento predeterminado del sistema de seguimiento 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 app no lee url.pathname y no tiene la nueva ruta en su conjunto de dependencias, esa función load se omite. El load de página se ejecuta desde cero. El load 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 bug difícil de reproducir. Entender por qué sucede 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 utiliza llamadas fetch simples a endpoints de API.

Por Qué los Guards de Layout Fallan Silenciosamente

Para hacer la vulnerabilidad concreta, considera una aplicación protegida simple. Hay un layout de app en src/routes/app/+layout.server.ts. El desarrollador coloca una verificación de autenticación ahí. 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 de forma dura a /app/posts. El load del layout de app 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 a /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 app 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 app registró interés. SvelteKit omite el load del layout de app por completo y reutiliza el resultado del paso 1.

El load de página para /app/analytics sí se ejecuta, porque es una nueva página. Su función load del servidor recibe el locals actual, donde locals.user es ahora null. Si ese load 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. El load del layout se omite durante la navegación del lado del cliente. El load de página se ejecuta pero no tiene guard. El objeto de usuario obsoleto del load del layout anterior llena el prop data.

Por Qué las Funciones Load Funcionan de Esta Manera

El comportamiento es intencional. El seguimiento de dependencias de SvelteKit existe para hacer que la navegación del lado del cliente sea rápida. Si cada load 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 app. Esos layouts cargan la estructura de navegación, los datos del perfil de 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 seguimiento 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 a la 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 en la sesión del usuario. Si la sesión cambia entre navegaciones, la función load no tiene mecanismo para saberlo.

Este es el comportamiento correcto para la mayoría de los datos cargados por layouts. Sería contraproducente que el load de navegación se volviera a ejecutar cada vez que locals cambia. El framework no tiene forma de saber qué cambios en locals son significativos para qué funciones load. Esa decisión te la deja a ti.

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 manera confiable, y entender qué garantiza cada colocación.

Las Tres Estrategias

Hay tres lugares distintos donde puede vivir la lógica de autenticación 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 poblar 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 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)
}

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

El hook popula event.locals.user cuando la sesión es válida. Lo deja como undefined cuando la sesión falta o es inválida. Cada función load que se ejecute dentro de esta solicitud puede leer event.locals.user con la confianza 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 a /app/analytics, hace una solicitud al servidor para ejecutar el +page.server.ts para esa ruta. Esa solicitud pasa por el hook handle. El hook valida la sesión de forma fresca para esta solicitud. locals.user es preciso en el momento en que se ejecuta el load de página. Si la sesión expiró, locals.user es undefined para esta solicitud, independientemente de lo que haya calculado cualquier load de layout anterior.

El hook se encarga de la población. La aplicación es una preocupación 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 el load de página se ejecuta en cada navegación a esa página específica, tanto dura como del lado del cliente. Cada vez que el usuario llega a /app/analytics, el load 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 debilidad principal 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 manera 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 enfoque 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 verifican dos veces 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 el load del layout raíz obtuvo. Este patrón es común y no es inherentemente 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 específica al servidor. Si el load del layout raíz se ejecutó durante esta solicitud (ya sea porque esta es una navegación dura 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 son reconstruidos para la respuesta mediante el proceso de combinación. Si el layout raíz realmente se volvió a ejecutar depende de las mismas reglas de seguimiento de dependencias. Si no se volvió a ejecutar, parent() en el load de página retorna el output del layout previamente cacheado.

Esto significa que await parent() no garantiza datos de sesión frescos. Te da lo que sea que el framework computó para los datos del padre en esta solicitud. Para verificaciones de autenticación confiables dentro de los loads de página, leer locals.user directamente es el enfoque correcto. locals es poblado de forma fresca 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. El load inicial del layout podría enriquecer el objeto de usuario con permisos, preferencias o contexto de tenant que es costoso de recalcular. Pasarlo 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 logueado?), usa locals.user. Es más económico, 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 del hook y la capa de la función load. Entender exactamente qué es y cuándo está disponible previene confusión 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 popula. 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 podría leer locals antes de que el hook lo haya populado.

locals se tipifica mediante 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-nullable. Esto es el sistema de tipos reforzando 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 tipos 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-null. 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') en docenas de funciones load es una fricción. Cada nueva ruta necesita el mismo código repetitivo. Si la URL de login cambia, cada archivo necesita actualizarse. Si quieres agregar limitación de velocidad o logging 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 esté ejecutándose dentro del contexto de una solicitud. Esto significa que puedes escribir una función de utilidad 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 encadenar 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
	}
}

Nota 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 de utilidad y la forma del evento load de SvelteKit. La utilidad también puede ser llamada desde funciones helper anidadas, siempre que esas funciones se estén ejecutando 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 la 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 compilación, o en cualquier código que se ejecute fuera de una solicitud activa.

Si getRequestEvent() es llamado 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 lugar 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 estás apuntando 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 preocupación en la capa que le corresponde, sin duplicar lógica en ambas.

El hook handle es para poblar, no para aplicar. 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 de locals y deciden qué hacer con lo que encuentran. Una ruta protegida redirige. Una ruta que se adapta al estado de autenticación se renderiza de manera diferente según si locals.user está presente. Una ruta que es completamente pública ignora locals.user. La elección se hace 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 en el tiempo de vida de esa solicitud. Si pones la validación de sesión en cada función load en lugar del hook, 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 única 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 pregunta de si hacer el guard a nivel del layout, a nivel de la página o en ambos depende de los requisitos de seguridad de tu aplicación:

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

En navegaciones del lado del cliente, el load del servidor de la página se ejecuta y su guard se dispara.
Los datos sensibles del layout están cacheados 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 el load 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 el load de página obtiene datos que requieren un usuario válido (construir una URL con locals.user.id, por ejemplo), el load de página debe tener guard. No puede proceder sin un usuario válido. El guard de 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 Aplicación de Roles

El siguiente ejemplo completo muestra las tres capas trabajando en conjunto: el hook popula locals, el layout de la aplicación proporciona una guardia ligera para su propia salida sensible, y las cargas de páginas individuales usan requireLogin() y requireRole() para una aplicación precisa.

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 exclusiva 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 de 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 guardia de UI, no un mecanismo de control de acceso. El componente lee data.user.role y muestra u oculta el enlace de administración en consecuencia. Esto no protege las rutas de administración. Si un usuario con un rol no administrativo navega directamente a /app/admin/users, la carga del servidor de 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 guardias de UI y guardias de ruta aplica de forma universal. 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 guardias de carga de layout sin guardias 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 devolver 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 de forma incorrecta 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 la pila 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 estable independientemente de la complejidad de la ruta. Una aplicación con una jerarquía de layout de diez niveles sigue realizando una única llamada de validación de sesión por solicitud.

La utilidad requireLogin() lee desde locals sin realizar llamadas de red adicionales. Es una lectura de memoria sincrónica 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 firmado y autocontenido (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 la base de datos a una verificación criptográfica o búsqueda en caché.

La guardia de layout sirve como una salida anticipada 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 guardias a nivel de layout que las guardias a nivel de página por sí solas no proporcionan: para las navegaciones duras iniciales, la guardia de layout impide que las funciones de carga posteriores se ejecuten en absoluto. Para las navegaciones del lado del cliente donde el layout se omite, la guardia de carga de página captura el fallo a nivel de página.

Para rutas con múltiples capas de verificación de permisos (autenticado Y editor Y tenant-validado), considere crear una utilidad compuesta en lugar de encadenar llamadas separadas. Cada llamada a requireRole() es económica, pero componerlas en una única utilidad mejora la legibilidad y hace que el requisito de permiso completo 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 Carga de Datos en SvelteKit. 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 de la pila.

Ver También

Errores y Redirecciones en Funciones de Carga — el artículo anterior en esta serie, que cubre error() y redirect() en detalle, incluyendo la trampa del try/catch que silenciosamente deshabilita las guardias de ruta
Volver a Ejecutar Funciones de Carga y Seguimiento de Dependencias — explica exactamente cuándo las funciones de carga de layout vuelven a ejecutarse y cuándo se omiten, que es el mecanismo que hace que las guardias exclusivas de layout sean poco confiables
Uso de Datos del Padre en Funciones de Carga — cubre la mecánica de parent() en detalle, incluyendo qué devuelve y por qué no es una fuente confiable del estado de autenticación actual en las cargas del servidor de página
Cookies y Cabeceras en la 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