12 KiB
Impl: Corrigir guarda de mesma origem do CSRF em campanha
Status: aprovado Atualizado em: 2026-08-25 Issue: #913 Intenção: docs/plans/corrigir-guarda-mesma-origem-campanha.md Appetite restante: herdado — ~0,5 dia de engenharia; sem migration, sem collection, sem UI
Leitura da intenção
- Outcome:
POST /campanha/municipios/pledge-estimated-votes(e toda mutation JSON de/campanha) volta a funcionar atrás do túnel Cloudflare: hojeisSameOriginRequestcomparaOrigin: https://jorgesolla1313.com.brcontrarequest.urlcru (http://localhost:3000/...atrás do cloudflared) e responde 403"Requisição inválida."antes de parsear o corpo. O autosave das células precisa voltar a gravar em produção, mantendo o CSRF de mesma origem intacto. - O que NÃO negociar: (1) rejeição de cross-origin permanece fail-closed — nada de aceitar qualquer origem; (2) a guarda continua estrutural no
campaignJsonMutationRoute(nenhuma rota ganha linha própria de origem); (3) zero regressão emcampaignInviteOrigin.ts, nas rotas de convite/WebAuthn/calendário que o usam, e nos contratos de resposta dos dois consumidores diretos deisSameOriginRequest(ai-transcribe403{error},social-feed/sync403{ok:false}); (4) dev/test local em qualquer porta (worktrees 3100+) e esquema segue aprovando requisições do próprio app. - O que reavaliar: questão aberta assumida na intenção — a fonte da origem esperada são os headers
x-forwarded-*com fallbackNEXT_PUBLIC_SITE_URL. Fechada pela leitura do código:getCampaignInviteBaseURLJÁ implementa exatamente essa política (headers só para autoridades locais em dev/test; origem canônica de config em produção, HTTPS DNS público ou throw) — a decisão é reuso, não reimplementação.
Abordagem recomendada
flowchart TD
A["POST com header Origin"] -->|"ausente"| OK["seguir (parse/handler)"]
A -->|"presente"| B{"origin ==<br/>request.url?"}
B -->|sim| OK
B -->|nao| C{"origin == origem resolvida<br/>getCampaignInviteBaseURL<br/>(headers + env)"}
C -->|sim| OK
C -->|"throw ou mismatch"| R["403 Requisição inválida."]
Opções consideradas: A | B | C
- A) Reconstruir inline a origem cliente-visível (
x-forwarded-proto+x-forwarded-host ?? host, fallbackrequest.url) com parser próprio dentro desameOriginRequest.ts. - B) Estender
isSameOriginRequestpara uma união aditiva de bases: aprova seOrigincasa com a origem derequest.url(base legada, comportamento atual preservado) ou com a origem resolvida porgetCampaignInviteBaseURL({ requestOrigin, forwardedHost: x-forwarded-host ?? host, forwardedProto }), capturando throw como "base indisponível". - C) Comparar apenas host/autoridade (precedente WebAuthn,
campaignWebAuthnConfig.ts:26–49).
Recomendação: B — porque reusa o módulo dono da política de origem (parsing com rejeição de vírgulas/CRLF/credenciais/portas já testado em tests/int/campaignInvite.int.spec.ts; "edit the owner, don't twin"), fecha o buraco exato do túnel (produção ignora headers spoofáveis para nomes públicos e compara contra NEXT_PUBLIC_SITE_URL, que exige HTTPS DNS público ou falha fechada) e é superconjunto estrito do comportamento atual: nenhuma requisição que passava antes passa a ser rejeitada, logo os 16 consumidores (14 rotas via wrapper + ai-transcribe + social-feed/sync) herdam a correção sem risco de falso-negativo. Assinatura síncrona boolean preservada — nenhum call site muda.
Rejeitadas: A — twina validação de headers que campaignInviteOrigin já possui, confia em x-forwarded-host client-controlável também em produção (só não explorável porque custom headers exigem CORS preflight — argumento sutil demais para um guard de segurança) e adiciona ~30 linhas novas de casos de borda; C — host-only tolera divergência http↔https (cloudflared termina TLS na edge) e troca o contrato de origem da guarda por autoridade, mudança de política que a intenção não pede. Também rejeitado por anti-goal: patchear as 14 rotas individualmente (espalhar lógica) e relaxar a comparação (aceitar qualquer origem).
Componentes / mudanças
isSameOriginRequest(src/utilities/sameOriginRequest.ts, editado): nova semântica união —Originausente →true; senãonew URL(origin).origin === new URL(request.url).origin(legado, verbatim) OU=== new URL(getCampaignInviteBaseURL({ requestOrigin: origin, forwardedHost: request.headers.get('x-forwarded-host') ?? request.headers.get('host'), forwardedProto: request.headers.get('x-forwarded-proto') })).origin, comtry/catchem torno da resolução (throw ⇒ base descartada, decide o legado);Originnão-parseável ⇒false. Ganhaimport 'server-only'(transitivamente server-only pelo novo import; alias de teste já existe emvitest.unit.config.mts). Doc comment reescrito: documenta as classes de consumidor e a política duas-bases (direta vs atrás-de-proxy).tests/unit/sameOriginRequest.unit.spec.ts(novo — o módulo nunca teve spec próprio; cobertura vinha só via wrapper): matriz comvi.stubEnv+vi.unstubAllEnvs()(unit NÃO carrega.env.test). Casos: Origin ausente→true; Origin==request.url→true; tracer do túnel —new Request('http://localhost:3000/campanha/x')+Origin: https://jorgesolla1313.com.br+x-forwarded-proto: https/x-forwarded-host: jorgesolla1313.com.br+NODE_ENV=production+NEXT_PUBLIC_SITE_URL=https://jorgesolla1313.com.br→true; mesmo tracer comOrigin: https://evil.example→false; produção SEMNEXT_PUBLIC_SITE_URL→false (fail-closed);x-forwarded-host: 'localhost:3000,evil.example'encadeado →decide base legada sem crash; Origin'null'/inválido →false; dev TLS diretoRequest('https://localhost:3443')+Origin igual →true (cobre aceite #3).tests/unit/campaignJsonMutationRoute.unit.spec.ts: intacto e verde — seus dois testes de origem continuam válidos sob a união (cross-originevil.examplenão casa com nenhuma base; Origin==request.url casa na legada). Não "consertar" esses testes: eles são o pin da base legada.- Migration: sem migration
- Access / Consent: N/A
- UI: N/A (Impeccable A)
Fases verificáveis
- Tracer / server — spec novo RED com o caso-túnel (falha no código atual:
request.urlinterno ≠ Origin público); implementar a união emsameOriginRequest.tsaté GREEN com a matriz completa; rodar os testes do wrapper confirmando que os existentes ficam verdes sem edição. Verificação operacional (leitura, não código): confirmar queNEXT_PUBLIC_SITE_URLestá exportado no runtime de produção (~/stack/teqo-1313.env) — sem ele a base canônica descarta-se silenciosamente (catch) e o sintoma persiste apesar do deploy verde. - Gates —
pnpm gate:fast; cascata completa antes do PR (tsc --noEmit && pnpm lint && pnpm format:check && pnpm exec knip && pnpm check:cycles && pnpm test && pnpm build— knip garante que o import novo não órfã nada); smoke e2e local do autosave alvo provando que o fluxo segue gravando em dev direto; push viapnpm push.
Rabbit holes / Não escopo (engenharia)
- Tocar em
campaignInviteOrigin.ts,campaignWebAuthnConfig.tsou no envelope/respostas decampaignJsonMutationRoute.ts— o precedente host-vs-origin do WebAuthn tem comentário próprio explicando por que diverge; não unificar. - Plugar
allowLocalTLSna guarda: a normalizaçãohttps://localhost→httpfora de produção é política vigente (nenhum call site hoje passaallowLocalTLS:true); o aceite "com TLS" fica coberto pela base legada (request.urlreflete o esquema real do acesso direto). Plumbing novo de env para TLS local é especulação. - Harness e2e de túnel (cloudflared local): caro e frágil; a matriz unit cobre a lógica, e a prova final é o smoke manual pós-deploy com
curl -H 'Origin: https://jorgesolla1313.com.br' -X POST .../pledge-estimated-votesesperando 400 (passou da guarda, corpo inválido) em vez de 403. - Mudar os contratos
{error}/{ok:false}das duas rotas diretas, nem moversocial-feed/sync/ai-transcribepara o wrapper (allowlist da convenção tem razão declarada própria). - Registrar pin novo: nenhum arquivo top-level novo em
utilities/— estendemos osameOriginRequest.tsjá pineado (codebaseConventions.unit.spec.ts), então o teste de convenção não precisa de edição.
Riscos e mitigação
NEXT_PUBLIC_SITE_URLausente/incorreto no runtime de produção → base canônica lança/difere, catch descarta, legado decide, e o 403 do túnel persiste silenciosamente. Mitigação: fase 1 verifica o env do stack; smoke curl pós-deploy valida o outcome #1 de verdade (deploy verde ≠ bug corrigido neste caso).- Falso-positivo adicional (aceitar mais que antes): a única base nova em produção é a origem canônica de config, validada como HTTPS DNS público e imune a headers do cliente; em dev/test a resolução aceita valores a mais, mas não é superfície de ataque. Superconjunto estrito ⇒ impossível regressar negativo nos consumidores existentes.
- Vazamento de
vi.stubEnv('NODE_ENV')entre testes do spec novo →afterEach(vi.unstubAllEnvs)e casos independentes; NODE_ENV stubado só dentro dositdo túnel/fail-closed. - Valores encadeados
x-forwarded-host: a, b(proxy duplo): chegam à guarda e são rejeitados pelo parser reusado ⇒ caem na base legada/config — comportamento fixado por caso de teste, sem parser paralelo.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: autosave atrás do túnel sem "Requisição inválida."; cross-origin segue 403; dev/test localhost ±TLS e portas de worktree aprovam; zero regressão em
campaignInviteOrigin.tse suas rotas consumidoras - Invariantes AGENTS/engineering-standards: editou o dono (
sameOriginRequest.ts) em vez de gemelar parsing; identificadores em inglês, copy pt-BR existente intacta; sem migration/push:false;server-onlyonde virou módulo de servidor; nenhum URL público alterado - Testes de domínio previstos: unit novo da matriz de origem (túnel/cross-origin/fail-closed/encadeado/TLS-local/dev-porta-diferente) + spec do wrapper intacto como pin da base legada; convenção-test de POST routes e pin top-level passam sem edição
Triage pós-entrega (capture-review-debts, 2026-08-25)
Já resolvido na sessão (não reabrir)
- Relaxamento dev-only (Origin localhost em porta ≠ request.url aprovado em dev/test): documentado no doc comment do módulo e pinado pelo teste "approves a dev request whose local Origin differs from the request URL port" (
tests/unit/sameOriginRequest.unit.spec.ts). - Gaps de cobertura apontados pelos revisores (isolamento do pin da base legada, caso dev porta-diferente, nome do teste de header encadeado): aplicados na sessão.
Adiado com gatilho
- S3 — extração da tripla
x-forwarded-host ?? host/x-forwarded-proto/requestOrigin: 2 call sites (campaignInviteOrigin.tsesameOriginRequest.ts). Extrair quando surgir o 3º call site da política de origem proxy-aware ou quando a política ganhar parâmetro novo (ex.:allowLocalTLS) — aí são 2 pontos a manter em sincronia.
Explicitamente fora
- S2 — rename
campaignInviteOrigin.ts(o módulo virou a política de origem proxy-aware do app, nome diz "invite"): rename de pureza, score ≤2 — não desbloqueia reuso real. - S4 — wraps defensivos (
new URL(getCampaignInviteBaseURL(...))no-op hoje; catch da base legada inalcançável na prática): decisão mantida, defesa barata. - K1 — knip quebrado localmente (pré-existente em main;
Error loading src/payload.config.tsserver-only guard; CI verde): fora do escopo desta entrega — registrar como Issue separada se o humano pedir. - K2 —
pnpm test:e2e -- <spec> -g <pattern>(o--repassado faz o playwright tratar-gcomo filtro posicional; workaround:node_modules/.bin/playwright test ...direto): pré-existente, fora do escopo — registrar se o humano pedir.