Laravel Sanctum statefulApi força verificação de CSRF e quebra SPAs desacopladas com HTTP 419

[!NOTE] Resumo Executivo (DEV-2026-135): Ao configurar o Laravel 11/12 para servir uma SPA React em localhost, requisições de login falhavam com HTTP 419 misterioso. Descobrimos que o método statefulApi ativa validação de CSRF para origens locais mesmo quando a SPA utiliza autenticação por Bearer Token.


🚨 O Desafio Técnico / Contexto

O frontend Vite chamava POST /api/auth/login via proxy e recebia HTTP 419. Como a aplicação React armazena e envia Bearer Token via header Authorization e não mantém sessão por cookies, o middleware EnsureFrontendRequestsAreStateful exigia um token CSRF inexistente.


💡 Principais Lições Aprendidas & Descobertas

  • 💡 O método statefulApi() no bootstrap/app.php injeta o middleware de verificação de CSRF em rotas de API para domínios listados em SANCTUM_STATEFUL_DOMAINS.
  • 💡 SPAs desacopladas que usam Personal Access Tokens (Bearer Token) não devem usar statefulApi(), pois não realizam o handshake com /sanctum/csrf-cookie.
  • 💡 A correção consiste em remover statefulApi(), configurar validateCsrfTokens(except: [‘api/*’]) e publicar o config/cors.php liberando origens do dev server.

🛠️ Especificação Técnica & Código-Chave

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->validateCsrfTokens(except: ['api/*']);
    $middleware->api(prepend: [
        \Illuminate\Http\Middleware\HandleCors::class,
    ]);
})

📈 Impacto no Ecossistema & Valor Prático

Eliminação imediata do erro HTTP 419 e garantia de autenticação Bearer pura e sem atrito no ciclo de desenvolvimento local e produção.

  • Projetos Relacionados: 00-ZapDisparador
  • Registro de Origem: _data/daily.dev-22.yml

Publicado originalmente como parte do Diário de Desenvolvimento 2026 do ecossistema Artes do Sul & Araguaci.