feat(cache): cache de CDN para /_serverFn + correções de rota privada e bypass

[JonasJesus42]

Contexto

Todos os sites TanStack servem HTML e /_serverFn com Cdn-Cache-Control: no-store, logo
Cf-Cache-Status: BYPASS: nenhuma requisição é servida pelo CDN, todas invocam o Worker.

O no-store está correto no caso geral. O Worker chaveia o cache por uma Request sintética que carrega
__seg/__cf_device/__cf_geo/__bot/__fetch/__abf (buildCacheKey), enquanto o CDN da Cloudflare
chaveia pela URL crua e ignora Vary além de Accept-Encoding. Deixar o CDN cachear por URL serviria HTML
de desktop para mobile, de uma região para outra, ou o render eager de um crawler para um humano.

Este PR faz três coisas: libera o CDN para /_serverFn (onde dá para fazer com segurança), fecha buracos de
classificação de rota que o no-store vinha mascarando, e deixa pronto — inativo — o material para
cachear HTML no CDN.

O que muda

1. /_serverFn no CDN (opt-in)

Inverte o problema: em vez de esperar que o CDN reproduza a chave, o cliente põe o segmento na URL
(?__cseg=<device>.<buildHash>), o que torna a chave do CDN equivalente à do Worker.

// worker-entry.ts
createDecoWorkerEntry(serverEntry, {
  cdnCacheControl: "serverfn-segment",
  buildSegment: (request) => ({ /* ... */ }),   // obrigatório
});

// src/start.ts
import { decoServerFnFetch } from "@decocms/tanstack/sdk/serverFnFetch";
export const startInstance = createStart(() => ({ serverFns: { fetch: decoServerFnFetch } }));

Default inalterado. O marcador é dica, não fonte de verdade — o Worker recalcula o segmento do próprio
request e só relaxa o no-store quando confere exatamente.

Portado de uma implementação que já roda em produção num site, com dois gaps fechados: aquela versão
verificava só o device, deixando bots (que executam JS, como Lighthouse/PageSpeed) e cohorts de A/B
envenenarem uma entrada compartilhada no CDN.

2. Endurecimento (independe do opt-in)

Estes valem mesmo sem ligar nada, e alguns são bugs reais em produção hoje:

• PRIVATE_PREFIX_RE tinha buracos graves. Era case-sensitive, ancorada na raiz e cobria uma lista curta,
  então /listadedesejos, /wishlist, /favoritos, /orders, /profile, /logout, /cadastro e rotas de
  troca/devolução caíam no default listing — público, 120s de edge. Idem /Checkout e /pt/checkout.
• hasOnlySafeCookies era fail-open: resposta com set-cookie cujos nomes não foram parseados era
  tratada como segura, isto é, cacheável.
• bypassPaths substituía os defaults em vez de somar, então um site que acrescentava um path perdia
  silenciosamente /deco/, /live/ e /.decofile.
• Todo bypass agora emite CDN-Cache-Control: no-store, garantido no ponto único de saída em vez de em
  doze call sites. Alguns deletavam o header, outros não, e vários ainda emitiam o Cache-Control público do
  perfil (public, s-maxage=900) na saída.
• Warn no boot quando falta buildSegment — sem ele o bypass de logado é inerte e usuário autenticado
  compartilha a entrada anônima.
• match-profile virou armadilha silenciosa: o JSDoc prometia segurança "sem buildSegment e
  deviceSpecificKeys: false", mas deviceSpecificKeys é true por default, então a condição é falsa em todo
  site. Agora é recusado com aviso em vez de cross-servir segmentos.

3. Configuração pelo site: livre para apertar, ruidosa para afrouxar

Como o Worker é a fonte de verdade da elegibilidade, um site pode marcar rotas como privadas à vontade e isso
chega ao CDN sozinho. Afrouxar é o que vaza dado, então ficou deliberadamente incômodo:

registerPrivatePaths(["/listadedesejos", "/trocas"]);   // só restringe; caminho seguro

• registerCachePattern continua vencendo os builtins, exceto que não consegue mais tornar pública uma
  rota privada (um pattern amplo do site capturava /checkout).
• setCacheProfile("private", { isPublic: true }) é recusado com aviso; allowPublicPrivateProfile() é a saída,
  e ela tem um nome que você precisa digitar.

4. Material para HTML no CDN — presente, não ativado

blocks-cli/scripts/cdn-rules.ts gera as Cache Rules derivadas das mesmas constantes do Worker
(SEGMENT_COOKIE, BOT_UA_SUBSTRINGS, DECO_MATCHERS_OVERRIDE_PARAM) — duas cópias mantidas à mão divergem,
e o modo de falhar é servir a resposta de um visitante para outro. Os testes fixam essa correspondência.

As regras não listam rotas privadas de propósito: o Worker já manda no-store nelas e a Cloudflare
respeita, então registerPrivatePaths() propaga sem mexer em regra.

POST /_cache/purge passa a purgar o CDN por hostname quando DECO_CF_ZONE_ID + DECO_CF_PURGE_TOKEN
existirem; inerte sem elas.

Validação

Testado end-to-end contra um site real buildado (não só unit): pacotes linkados, bun run build, worker no
wrangler dev, e navegação SPA dirigida por Chrome.

caso	Cdn-Cache-Control
GET /_serverFn com marcador correto (desktop e mobile)	public, max-age=1800 ✅
sem marcador	no-store
marcador de outro device (forjado)	no-store
build antigo	no-store
bot UA	no-store
cookie de login	no-store
cookie A/B	no-store
documento HTML	no-store

O valor liberado bate exatamente com o que a implementação de site produz em produção. No site, isso
substituiu ~230 linhas de shim por 6 linhas + um start.ts de 9.

Fase 0 conferida no worker real: /listadedesejos, /Checkout e /pt/minha-conta agora saem
private, no-store; antes eram listing público de 120s.

2046 testes passando, 63 novos. Typecheck limpo nos três pacotes.

As 2 falhas em draft preview (workerEntry.test.ts) e as 2 em nextjs/draftShell.test.ts são
pré-existentes nesta branch — confirmei com git stash que ocorrem idênticas sem estas mudanças.

O que NÃO está aqui

Cachear HTML no CDN. Não é mudança de header: exige aplicar as Cache Rules na zona, e falta validar que
cf.hostname.metadata funciona dentro de Cache Rules (a doc da Cloudflare confirma o campo nos motores de
regras, mas não afirma suporte em Cache Rules especificamente). O ganho ali também é mais estreito do que
parece — o Cache API do Worker já responde do mesmo edge; o CDN economizaria a invocação do Worker, não a
latência de rede. Vale medir custo de invocação antes de decidir.

🤖 Generated with Claude Code

---

Summary by cubic

Enables opt-in CDN caching for /_serverFn requests: the client attaches a device-plus-build segment to the URL, making the CDN's cache key match the Worker's. Sites keep no-store by default, the Worker re-verifies the marker and falls back on any mismatch (forged, stale, bot, logged-in, A/B), and HTML documents stay uncacheable — the initial navigation has no client hook.

Cache hardening

• PRIVATE_PREFIX_RE is now case-insensitive, matches behind a locale prefix, and covers wishlist, profile, orders, signup, logout, and returns — routes that previously fell through to the public listing profile.
• hasOnlySafeCookies fails closed: unparseable set-cookie names no longer count as safe.
• bypassPaths now always extends framework defaults instead of replacing them.
• The single response exit stamps no-store on every bypass and on any response missing the header (early returns), so nothing accidental goes public.
• match-profile is refused with a warning unless the cache key is exactly the raw URL.
• Non-public profiles can no longer be flipped public, a custom pattern cannot publicize a private path, and registerPrivatePaths() is the new safe way to add private routes.
• The VTEX middleware stops overwriting Cache-Control on every response and clears CDN-Cache-Control for logged-in or custom-pricing requests.

CDN rules and purge

• blocks-cli/scripts/cdn-rules.ts generates Cloudflare Cache Rules derived from the Worker's own constants (SEGMENT_COOKIE, BOT_UA_SUBSTRINGS, DECO_MATCHERS_OVERRIDE_PARAM) so the two cannot drift.
• The bypass and cache rules are mutually exclusive by expression, not order — Cloudflare is last-match-wins, and this removes the ordering trap.
• The sec-fetch-dest: empty bypass carves out /_serverFn, which is exactly the traffic this feature exists to cache.
• Rules apply only to hostnames opting in via deco_cdn_html metadata and skip private paths, which the Worker's no-store already covers.
• POST /_cache/purge also purges the CDN by hostname when DECO_CF_ZONE_ID and DECO_CF_PURGE_TOKEN are set.
• Boot warns when buildSegment is missing, since the logged-in bypass is inert without it.

^{Written for commit 8b53a3f. Summary will update on new commits.}

[JonasJesus42]

Correções do security review

Quatro apontamentos endereçados no 8b53a3f. O primeiro era um bug real meu.

1. As Cache Rules dependiam de first-match-wins — e a Cloudflare não é

A fase de cache é last-match-wins para ações não-terminantes como
set_cache_settings. A regra catch-all (cache: true) era superconjunto estrito da regra de bypass
(cache: false), então a sobrescrevia em toda request — deixando a lista de bypass inteira inerte,
incluindo a cláusula do cookie de auth que o próprio arquivo chama de "a mais importante". Um visitante logado
teria recebido a entrada anônima compartilhada, com o Worker nunca rodando: exatamente o caso que as regras
existem para impedir.

Pior: o teste "evaluates bypass before caching" codificava a mesma premissa errada e certificava o bug.

Agora as duas regras são mutuamente exclusivas por expressão (and not (<clauses>)), então a corretude não
depende mais de ordem nenhuma. O teste foi substituído por um de exclusão mútua — e verifiquei que ele
falha se a forma antiga for reintroduzida.

2. sec-fetch-dest: empty bypassaria justamente o tráfego que essa feature cacheia

Toda chamada /_serverFn é XHR e manda esse header. Uma vez corrigida a ordem, essa cláusula passaria a
bypassar exatamente o que o serverfn-segment existe para cachear — anulando a feature em silêncio. Adicionado
carve-out para paths de server-fn, espelhando o buildCacheKey, que os exclui do __fetch pelo mesmo motivo.

3. cdnCacheableServerFn agora falha fechado em geo

__cf_geo está na chave do Worker, não cabe no marcador e o CDN não reproduz. Na prática já era quase coberto
— com geo ligado o wrapper de buildSegment back-filla regionId, e qualquer regionId já anula o token —
mas o back-fill lê só cf.regionCode enquanto buildGeoCacheParam chaveia por country/region/city. Uma
request com país e sem region code escapava. Recusado de vez, igual ao que o branch match-profile quinze
linhas abaixo já fazia.

4. O comentário do exit point agora descreve o que o código faz

Ele afirmava "enforced here, at the single exit, so a future bypass branch can't forget it" enquanto só agia
em X-Cache: BYPASS. Branches que retornam antes do dressResponse (?asJson, ?renderJson, proxy,
redirects) não emitiam CDN-Cache-Control nenhum. Agora no-store é o default quando o header está ausente
— um early return só pode ser mais restritivo que a camada de cache, nunca acidentalmente público — e um valor
que o dressResponse já decidiu é preservado.

---

Nota sobre o veredito do review: os três findings foram classificados abaixo do limite de confiança porque
nenhum é explorável hoje — o cdn-rules.ts só imprime JSON, ninguém aplicou ruleset nenhum, e a ativação exige
dois passos manuais. Isso está correto como avaliação de vulnerabilidade. Mas "não é explorável hoje" não é
"não precisa consertar": o ruleset gerado é o controle de segurança quando for aplicado, e o teste errado
era o que enganaria o próximo leitor.

2588 testes, +4 novos. Typecheck limpo. As 4 falhas em draft preview seguem pré-existentes na branch.

[JonasJesus42]

Fechando em favor de PRs separados, conforme o review — eram duas coisas num PR só.

• fix(cache): private routes served from a public cache + bypass hardening #512 — fix(cache): rotas privadas em cache público + endurecimento de bypass. Não depende de nada, são bugs já em produção hoje, pode mergear direto.
• feat(tanstack): opt-in CDN caching for /_serverFn via a URL segment marker #513 — feat(tanstack): cache de CDN para /_serverFn. Depende do fix(cache): private routes served from a public cache + bypass hardening #512 (é a base da branch).

O gerador de Cache Rules saiu dos dois. O review apontou certo que em sites servidos por Workers não existe cache na frente, e que o caminho é o Workers Cache (cache: { enabled: true } no wrangler) em vez de Cache Rules na zona. Isso muda o desenho por completo — por worker em vez da zona compartilhada, config-as-code, versão do worker já na chave e Vary respeitado. Refaço a parte de HTML em cima disso, em PR próprio.

Os quatro fixes do security review que estavam no 8b53a3f seguem incluídos: dois deles (ordem das Cache Rules e carve-out do sec-fetch-dest) eram do gerador e saem junto com ele; o guard de geo no cdnCacheableServerFn está no #513 e o default de no-store no exit único está no #512.