A Falsa Sensação de Segurança

Um padrão comum em tutoriais e templates iniciais do SvelteKit coloca a lógica de autenticação dentro de uma função de carregamento de layout. O layout raiz ou um layout de seção verifica se há uma sessão válida, redireciona usuários não autenticados para a página de login e anexa os dados do usuário ao objeto retornado. Os componentes de página recebem o usuário por meio de data.user. Tudo parece funcionar.

O problema é que nem sempre funciona. Funciona para a primeira navegação direta (hard navigation) a qualquer página naquele layout. Funciona quando você recarrega o navegador. Mas para navegações pelo lado do cliente dentro do mesmo layout, a função de carregamento do layout frequentemente não é reexecutada. Uma requisição não autenticada pode passar despercebida para uma função de carregamento no servidor que assume que a autenticação já foi verificada. O redirecionamento que deveria acontecer simplesmente não ocorre.

Isso não é um caso limite sutil. É o comportamento padrão do sistema de rastreamento de dependências do SvelteKit, funcionando exatamente como documentado e exatamente como projetado. As funções de carregamento só são reexecutadas quando suas entradas rastreadas mudam. Uma navegação de /app/posts para /app/analytics muda a URL, mas se a função de carregamento do layout do app não lê url.pathname e não tem a nova rota em seu conjunto de dependências, essa função de carregamento é ignorada. O carregamento da página é executado novamente do zero. O carregamento do layout reutiliza seu resultado anterior.

Se toda a sua lógica de autenticação vive na função de carregamento do layout, você tem uma vulnerabilidade real na sua aplicação e um bug difícil de reproduzir. Entender por que isso acontece e o que fazer a respeito é o tema deste artigo.

Todos os exemplos seguem a convenção da série: sem ORMs, sem clientes de banco de dados em funções de carregamento. Todo acesso a dados usa chamadas fetch simples para endpoints de API.

Por que Guards em Layouts Falham Silenciosamente

Para tornar a vulnerabilidade concreta, considere uma aplicação protegida simples. Há um layout do app em src/routes/app/+layout.server.ts. O desenvolvedor coloca uma verificação de autenticação lá. Qualquer rota sob /app é 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 }
}

Agora considere esta sequência de eventos:

O usuário navega diretamente para /app/posts. A função de carregamento do layout do app é executada. locals.user é válido. O redirecionamento não é acionado. A página carrega.
A sessão do usuário expira no servidor. locals.user será agora null em qualquer nova requisição ao servidor.
O usuário clica em um link para /app/analytics. O SvelteKit realiza uma navegação pelo lado do cliente.

No passo 3, o SvelteKit avalia quais funções de carregamento precisam ser reexecutadas. A função de carregamento do layout do app leu locals.user no passo 1, mas locals não é uma dependência rastreada. As entradas rastreadas são params, url, route e parent(). Nenhuma delas mudou de forma que o layout do app tenha registrado interesse. O SvelteKit ignora completamente o carregamento do layout do app e reutiliza o resultado do passo 1.

O carregamento da página para /app/analytics é executado, porque é uma nova página. Sua função de carregamento no servidor recebe o locals atual, onde locals.user é agora null. Se esse carregamento de página não tiver sua própria verificação de autenticação, ele é executado sem um usuário válido e retorna dados ao componente de página que agora não possui nenhuma sessão legítima por trás dele.

O layout mantém dados de autenticação obsoletos do passo 1. O componente de página renderiza com esse usuário obsoleto. A sessão é inválida, mas a interface não sabe disso.

O diagrama de sequência mostra claramente a lacuna. O carregamento do layout é ignorado durante a navegação pelo lado do cliente. O carregamento da página é executado, mas não tem guard. O objeto de usuário obsoleto do carregamento de layout anterior preenche a prop data.

Por que Funções de Carregamento Funcionam Dessa Forma

O comportamento é intencional. O rastreamento de dependências do SvelteKit existe para tornar a navegação pelo lado do cliente rápida. Se cada carregamento de layout fosse reexecutado a cada navegação, as aplicações seriam lentas. A navegação de /app/posts para /app/analytics compartilha o mesmo layout raiz e layout do app. Esses layouts carregam estrutura de navegação, dados do perfil do usuário e configuração do site. Refazer o fetch de tudo isso a cada clique derrotaria o propósito do roteamento pelo lado do cliente.

O sistema de rastreamento de dependências é documentado e as regras são precisas. Uma função de carregamento é reexecutada quando uma de suas entradas rastreadas muda: um parâmetro de rota que ela leu, uma propriedade de URL que ela acessou, ou uma dependência que ela declarou com depends(). O objeto locals não é uma dependência rastreada. Ler locals.user dentro de uma função de carregamento não registra uma dependência na sessão do usuário. Se a sessão mudar entre navegações, a função de carregamento não tem mecanismo para saber sobre isso.

Este é o comportamento correto para a maioria dos dados carregados pelo layout. Seria contraproducente o carregamento de navegação ser reexecutado toda vez que locals muda. O framework não tem como saber quais mudanças em locals são significativas para quais funções de carregamento. Ele deixa esse julgamento para você.

A solução não é trabalhar contra esse comportamento. É colocar a aplicação da autenticação em lugares que são executados de forma confiável, e entender o que cada posicionamento garante.

As Três Estratégias

Existem três lugares distintos onde a lógica de autenticação pode residir em uma aplicação SvelteKit. Cada um tem uma garantia de execução diferente, um escopo de proteção diferente e um caso de uso apropriado diferente.

Estratégia 1: O Hook Handle

O hook handle em src/hooks.server.ts é um interceptador que envolve cada requisição ao servidor. "Cada requisição ao servidor" significa o carregamento inicial da página, cada chamada de API e cada fetch interno que o SvelteKit faz para executar funções de carregamento no servidor durante a navegação pelo lado do cliente. O hook é executado antes de qualquer função de carregamento. Sua responsabilidade principal é preencher event.locals com dados de sessão validados.

Esta é a única estratégia que é incondicionalmente confiável. Por ser executada para cada requisição que chega ao servidor, ela não pode ser contornada por padrões de navegação pelo lado do 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)
}

Observe o uso de event.fetch em vez do fetch global. Dentro do hook handle, event.fetch manipula corretamente requisições de mesma origem, encaminha cookies e funciona em todos os ambientes. Usar o fetch global com uma URL http://localhost:5173 codificada diretamente é um erro comum que funciona no desenvolvimento local mas quebra em todos os outros ambientes — staging, produção, implantações em contêineres. Sempre use event.fetch para chamadas de API dentro do hook.

O hook preenche event.locals.user quando a sessão é válida. Deixa indefinido quando a sessão está ausente ou inválida. Cada função de carregamento que é executada dentro desta requisição pode ler event.locals.user com confiança de que reflete o estado atual da sessão no lado do servidor, porque o hook foi executado primeiro e a sessão foi verificada durante exatamente esta requisição.

Quando o SvelteKit realiza uma navegação pelo lado do cliente para /app/analytics, ele faz uma requisição ao servidor para executar o +page.server.ts para aquela rota. Essa requisição passa pelo hook handle. O hook valida a sessão novamente para esta requisição. locals.user é preciso no momento em que o carregamento da página é executado. Se a sessão expirou, locals.user é undefined para esta requisição, independentemente do que qualquer carregamento de layout anterior computou.

O hook trata do preenchimento. A aplicação é uma preocupação separada.

Estratégia 2: Guards em Funções de Carregamento no Nível de Página e de Layout

Colocar uma verificação de redirecionamento dentro de um +page.server.ts é confiável porque o carregamento da página é executado a cada navegação para aquela página específica, tanto direta quanto pelo lado do cliente. Toda vez que o usuário chega a /app/analytics, o carregamento da página de analytics é executado e verifica locals.user. Se a sessão expirou, a verificação detecta isso.

// 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
	}
}

A limitação é a repetição. Se a aplicação tem vinte rotas sob /app, cada uma precisa desse guard. Um desenvolvedor que adiciona uma nova rota e esquece o guard tem um endpoint desprotegido. Esta é a principal fraqueza da dependência exclusiva de guards no nível de página.

Guards no nível de layout em src/routes/app/+layout.server.ts oferecem cobertura mais ampla, mas com a ressalva descrita na seção sobre o problema. Eles são executados de forma confiável na navegação inicial para qualquer rota sob /app. Eles podem ser ignorados em navegações subsequentes pelo lado do cliente dentro do mesmo layout se nenhuma dependência rastreada mudou.

A abordagem híbrida prática é usar ambos. O guard do layout fornece proteção ampla para a navegação inicial e uma primeira linha de defesa razoável. Os guards de página fornecem proteção confiável para navegações contínuas pelo lado do cliente dentro do mesmo layout, e eles fazem uma verificação dupla do estado da sessão para cada requisição ao servidor que manipulam.

Estratégia 3: Usando Dados do Pai para o Estado de Autenticação, com Ressalvas

Uma função de carregamento de página pode chamar await parent() para obter o objeto de usuário que o carregamento do layout raiz buscou. Esse padrão é comum e não é inerentemente errado, mas deve ser entendido com precisão.

// 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 }
}

Aqui está a limitação precisa: await parent() retorna dados que foram resolvidos durante esta requisição específica ao servidor. Se o carregamento do layout raiz foi executado durante esta requisição (seja porque esta é uma navegação direta ou porque as dependências rastreadas do layout raiz mudaram), os dados do usuário são frescos. Se o layout raiz foi ignorado para esta navegação pelo lado do cliente, os dados do usuário em parent() vêm da execução anterior.

Durante uma navegação pelo lado do cliente, o +page.server.ts é executado no servidor. No servidor, os dados do layout raiz são reconstruídos para a resposta por meio do processo de mesclagem. Se o layout raiz realmente foi reexecutado depende das mesmas regras de rastreamento de dependências. Se não foi reexecutado, parent() no carregamento da página retorna a saída do layout previamente cacheada.

Isso significa que await parent() não garante dados de sessão frescos. Ele fornece o que o framework computou para os dados do pai nesta requisição. Para verificações de autenticação confiáveis dentro de carregamentos de página, ler locals.user diretamente é a abordagem correta. locals é preenchido de forma fresca pelo hook handle para cada requisição. Está sempre atualizado.

// 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() é apropriado quando você precisa de dados do usuário que o layout computou, e onde essa computação é mais complexa do que o que está armazenado em locals. O carregamento inicial do layout pode enriquecer o objeto do usuário com permissões, preferências ou contexto de tenant que são custosos de recomputar. Passar isso por parent() é adequado, com o entendimento de que pode refletir uma requisição anterior se o layout foi ignorado.

Para a verificação binária de autenticação (o usuário está logado?), use locals.user. É mais barato, mais direto e sempre atual.

Como locals se Integra com Funções de Carregamento

O objeto locals é a principal ponte entre a camada de hooks e a camada de funções de carregamento. Entender exatamente o que ele é e quando está disponível evita confusão sobre por que alguns padrões funcionam e outros não.

locals é um objeto JavaScript simples anexado ao evento de requisição. Começa vazio. O hook handle o preenche. Toda função de carregamento no servidor que recebe o mesmo objeto de evento lê do mesmo locals. Ele tem escopo para uma única requisição HTTP. Duas requisições concorrentes têm objetos locals separados.

Todas as funções de carregamento no servidor dentro de uma única requisição compartilham o mesmo locals. O hook é executado primeiro, depois as funções de carregamento são executadas. Essa ordem é garantida. Não há condição de corrida onde uma função de carregamento poderia ler locals antes que o hook o tenha preenchido.

locals é tipado por meio de uma declaração em src/app.d.ts. Sem a declaração, o TypeScript não consegue saber quais 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 {}

Com essa declaração no lugar, o TypeScript sabe que locals.user é um objeto de usuário ou null, e irá solicitar que você trate ambos os casos. Uma função de carregamento que lê locals.user sem verificar null produzirá um erro de tipo se o código downstream tratar como não anulável. Este é o sistema de tipos impondo o padrão: sempre verifique 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
		}
	}
}

O estreitamento de tipo após a verificação de null não é cosmético. Significa que toda referência downstream a locals.user abaixo do guard é garantida pelo sistema de tipos como não nula. O TypeScript detectará qualquer tentativa de acessar o usuário sem uma verificação prévia.

Construindo um Utilitário requireLogin() com getRequestEvent()

O padrão repetido de verificar locals.user e chamar redirect(303, '/login') em dezenas de funções de carregamento é fricção. Cada nova rota precisa do mesmo boilerplate. Se a URL de login mudar, cada arquivo precisa ser atualizado. Se você quiser adicionar limitação de taxa ou logging para falhas de autenticação, você atualiza dezenas de arquivos.

O SvelteKit fornece getRequestEvent() de $app/server para resolver exatamente esse problema. Ele retorna o RequestEvent atual de qualquer função no lado do servidor que está sendo executada dentro do contexto de uma requisição. Isso significa que você pode escrever uma função utilitária que lê locals e chama redirect sem precisar que o evento seja passado como argumento. Qualquer função de carregamento no servidor pode chamar o utilitário sem passar o objeto de evento pela cadeia de chamadas.

// 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
}

Com esses utilitários no lugar, uma função de carregamento protegida se torna:

// 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
	}
}

Observe que o objeto event não é passado para requireLogin(). A função chama getRequestEvent() internamente para recuperá-lo. Isso remove o acoplamento entre a interface da função utilitária e a forma do evento de carregamento do SvelteKit. O utilitário também pode ser chamado de funções auxiliares aninhadas, desde que essas funções estejam sendo executadas dentro do mesmo contexto de requisição ao servidor.

O utilitário baseado em função (role) funciona da mesma forma:

// 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
	}
}

Escopo e limitações do getRequestEvent()

getRequestEvent() está disponível a partir do SvelteKit 2.20.0. Funciona dentro de contextos de requisição exclusivos do servidor: hooks.server.ts, +page.server.ts, +layout.server.ts, rotas de API +server.ts, e qualquer função chamada a partir desses contextos dentro do mesmo ciclo de vida de requisição.

Não funciona em funções de carregamento universais (+page.ts / +layout.ts). Funções de carregamento universais não são um contexto suportado independentemente de estarem sendo executadas no servidor durante SSR — elas não são módulos exclusivos do servidor, portanto getRequestEvent() não está disponível para elas. Também não funciona no momento de inicialização do módulo, durante o build, ou em qualquer código que é executado fora de uma requisição ativa.

Se getRequestEvent() for chamado fora de um contexto de requisição válido, ele lança um erro claro em vez de retornar um evento obsoleto ou indefinido. Isso torna o uso indevido óbvio em vez de silencioso.

Uma ressalva adicional: em ambientes que não suportam AsyncLocalStorage, getRequestEvent() deve ser chamado de forma síncrona, ou seja, não após um await. A maioria dos runtimes de servidor modernos (Node.js, Deno, Bun, Cloudflare Workers) suporta AsyncLocalStorage, então na prática essa restrição raramente se aplica. Mas se você estiver visando um ambiente de implantação incomum, chame getRequestEvent() no topo da função antes de qualquer 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.

A regra geral: getRequestEvent() é seguro em qualquer lugar onde o framework começou a tratar uma requisição HTTP específica e ainda não enviou a resposta final.

Quando Usar Hooks vs Guards em Funções de Carregamento

As duas camadas servem a propósitos diferentes. Usá-las corretamente significa colocar cada preocupação na camada que é adequada para ela, sem duplicar lógica nas duas.

O hook handle é para preenchimento, não para aplicação. Seu trabalho é pegar a requisição HTTP bruta, extrair o identificador de sessão, validá-lo e anexar o usuário resultante a locals. Isso deve acontecer para cada requisição, sem exceção. O hook não redireciona usuários não autenticados. Ele simplesmente reflete o estado honesto da sessão em locals.

Os guards em funções de carregamento são para aplicação. Eles leem de locals e decidem o que fazer com o que encontram. Uma rota protegida redireciona. Uma rota que se adapta ao estado de autenticação renderiza de forma diferente com base em se locals.user está presente. Uma rota totalmente pública ignora locals.user. A escolha é feita por função de carregamento.

Essa separação tem um benefício concreto: o custo de validação da sessão é pago exatamente uma vez por requisição, no hook, independentemente de quantas funções de carregamento são executadas durante o ciclo de vida dessa requisição. Se você colocar a validação de sessão em cada função de carregamento em vez do hook, cada função de carregamento protegida que é executada para uma requisição faz sua própria chamada de validação de sessão. Uma hierarquia de layout de três níveis poderia fazer três chamadas de validação para um único carregamento de página, todas retornando o mesmo 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)

As verificações de autenticação em funções de carregamento são baratas. Elas leem um valor já na memória e ou chamam redirect ou continuam. A operação custosa é a validação da sessão, e o hook garante que aconteça apenas uma vez.

A questão de se proteger no nível do layout, no nível da página ou em ambos se resume aos requisitos de segurança da sua aplicação:

Para aplicações onde o próprio layout retorna dados sensíveis (o perfil de um usuário administrador, uma configuração específica de tenant), o carregamento do layout deve ter um guard. Esses dados não devem ser retornados para requisições não autenticadas. Use o guard do layout para este caso mesmo sabendo que pode ser ignorado em navegações pelo lado do cliente, porque:

Em navegações pelo lado do cliente, o carregamento no servidor da página é executado e seu guard é acionado.
Os dados sensíveis do layout estão cacheados da execução anterior. Se a sessão era válida então, os dados foram produzidos legitimamente.
Se a sessão expirou e o carregamento no servidor da página detecta isso e redireciona, os dados do layout em cache nunca são enviados ao navegador em uma nova resposta.

Para aplicações onde o carregamento da página busca dados que requerem um usuário válido (construindo uma URL com locals.user.id, por exemplo), o carregamento da página deve ter um guard. Ele não pode prosseguir sem um usuário válido. O guard da página não é opcional aqui independentemente do que o layout faz.

A abordagem recomendada para a maioria das aplicações:

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.

Exemplo Prático: Uma Aplicação Protegida com Aplicação de Papéis

O exemplo completo a seguir mostra as três camadas funcionando juntas: o hook popula locals, o layout da aplicação fornece uma guarda leve para sua própria saída sensível, e os carregamentos de páginas individuais usam requireLogin() e requireRole() para aplicação precisa.

Declaração da aplicação

// 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 {}

O 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)
}

Os utilitários de autenticação

// 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
}

O layout da seção da aplicação

// 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
		}
	}
}

Uma página protegida padrão

// 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
	}
}

Uma 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)
	}
}

Uma página pública que se adapta ao estado de autenticação

// 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
	}
}

O componente de layout da aplicação

<!-- 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>

A visibilidade do link de administrador é uma guarda de UI, não um mecanismo de controle de acesso. O componente lê data.user.role e mostra ou oculta o link de administrador de acordo. Isso não protege as rotas de administrador. Se um usuário com um papel não-administrador navegar diretamente para /app/admin/users, o carregamento do servidor de página chama requireRole('admin'), que chama requireLogin() e depois verifica o papel, redirecionando ou lançando um 403 dependendo do estado de autenticação. A UI apenas evita exibir um link que falharia imediatamente.

Essa distinção entre guardas de UI e guardas de rota se aplica universalmente. Ocultar um botão, link ou seção com base no papel é um comportamento adequado do lado do cliente. Isso melhora a experiência do usuário. Não é controle de acesso. O controle de acesso acontece no servidor, na função de carregamento, onde o locals.user validado pelo servidor está disponível.

Erros Comuns e Anti-Padrões

Depender exclusivamente de guardas de carregamento de layout sem 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 dados de layout como estado de autenticação 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() : [] }
}

Redirecionar em vez de retornar um 403 para falhas de autorização

// 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.')
	}

	// ...
}

O utilitário requireRole() codifica esse padrão automaticamente. Usá-lo significa que a verificação nunca é escrita incorretamente à mão.

Colocar a validação de sessão dentro das funções de carregamento em vez do 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 }
}

Considerações de Desempenho e Escalabilidade

A validação de sessão é tipicamente a operação mais custosa na pilha de autenticação: uma chamada de rede a um banco de dados ou armazenamento de sessão, uma verificação de token, uma consulta ao cache. Fazê-la uma única vez no hook e passar o resultado por locals mantém o custo fixo independentemente da complexidade da rota. Uma aplicação com uma hierarquia de layout de dez níveis ainda faz uma única chamada de validação de sessão por requisição.

O utilitário requireLogin() lê de locals sem fazer chamadas de rede adicionais. É uma leitura síncrona de memória mais um redirect() opcional. O custo é negligenciável.

Para aplicações de alto tráfego, a chamada de validação de sessão no hook pode se tornar um gargalo. Mitigações comuns incluem o uso de um token autocontido e assinado (JWT com expiração curta) que pode ser verificado criptograficamente sem uma chamada de rede, e o cache de sessões validadas em memória ou em um armazenamento rápido como Redis com um TTL curto. A implementação do hook permanece a mesma: extrair o identificador, validá-lo, anexar o resultado a locals. A implementação da validação muda de uma chamada ao banco de dados para uma verificação criptográfica ou consulta ao cache.

A guarda de layout serve como saída antecipada para toda a subárvore de funções de carregamento. Se +layout.server.ts redireciona um usuário não autenticado, nenhuma das funções de carregamento de página nessa seção é executada. Este é o benefício de desempenho das guardas no nível de layout que as guardas apenas no nível de página não fornecem: para navegações diretas iniciais, a guarda de layout impede que funções de carregamento downstream sejam executadas. Para navegações do lado do cliente onde o layout é ignorado, a guarda de carregamento de página captura a falha no nível da página.

Para rotas com múltiplas camadas de verificações de permissão (autenticado E editor E tenant validado), considere construir um utilitário composto em vez de encadear chamadas separadas. Cada chamada requireRole() é barata, mas compô-las em um único utilitário melhora a legibilidade e torna o requisito completo de permissão explícito à primeira vista:

// 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
}

Esses compostos documentam os requisitos de acesso no nível do utilitário em vez de duplicar a lógica em funções de carregamento. Quando os requisitos de acesso mudam, você atualiza em um único lugar.

O Que Vem a Seguir

Este é o artigo final da série de Carregamento de Dados do SvelteKit. A série cobriu o ciclo de vida completo dos dados do servidor em uma aplicação SvelteKit: como as funções de carregamento são estruturadas, como os dados fluem pela hierarquia de layout, como requisições e respostas são controladas, como as funções de carregamento decidem quando reexecutar, e como a autenticação se integra a cada camada da pilha.

Veja Também

Erros e Redirecionamentos em Funções de Carregamento — o artigo anterior desta série, cobrindo error() e redirect() em detalhes, incluindo a armadilha do try/catch que silenciosamente desabilita as guardas de rota
Reexecutando Funções de Carregamento e Rastreamento de Dependências — explica exatamente quando as funções de carregamento de layout reexecutam e quando são ignoradas, que é o mecanismo que torna as guardas exclusivas de layout não confiáveis
Usando Dados do Pai em Funções de Carregamento — cobre a mecânica de parent() em detalhes, incluindo o que ela retorna e por que não é uma fonte confiável do estado de autenticação atual nos carregamentos de servidor de página
Cookies e Cabeçalhos no Carregamento do Servidor — cobre a leitura de cookies de sessão em funções de carregamento e a API setHeaders() para controlar o comportamento de cache em páginas autenticadas
Documentação de Hooks do SvelteKit — referência oficial para o hook handle, handleServerError, e o tipo completo RequestEvent incluindo o campo locals
Documentação de getRequestEvent() do SvelteKit — referência oficial para getRequestEvent(), incluindo seus requisitos de contexto e propriedades disponíveis