# Política HTTP e limites do host

Configurar cabeçalhos, CSP, origens e publicação sem confundi-los com as permissões do runtime.

Veja versões, mudanças e requisitos em [Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/).


<span id="dos-controles-con-responsabilidades-distintas"></span>

<span class="section-anchor" id="section-1"></span>

## Dois controles com responsabilidades diferentes

`security` em `wu.config.json` define a política HTTP que o WU serve e que o build exporta para outros hosts. Os `grants` de cada app fazem parte da autoridade que o host entrega ao runtime. Um cabeçalho CSP não substitui o contrato de capacidades, e um grant não autoriza, por si só, o navegador a carregar uma origem bloqueada pela CSP.

<span id="configuración"></span>

<span class="section-anchor" id="section-2"></span>

## Configuração

```json
{
  "security": {
    "enabled": true,
    "csp": "",
    "frame_options": "DENY",
    "referrer_policy": "strict-origin-when-cross-origin",
    "nosniff": true,
    "app_origins": ["https://apps.example.com"],
    "connect_origins": ["https://api.example.com"],
    "wasm": false
  }
}
```

Os domínios do exemplo são marcadores de posição. A política deve descrever as origens que a aplicação realmente usa.

| Campo | Efeito |
| --- | --- |
| `enabled` | Ativa ou desativa o conjunto de cabeçalhos |
| `csp` | Política gerada, literal, `report-only` ou `off` |
| `frame_options` | `X-Frame-Options`; padrão `DENY` |
| `referrer_policy` | Política de referência |
| `permissions_policy` | Capacidades do navegador por Permissions-Policy |
| `hsts` | Strict-Transport-Security; útil ao servir por TLS |
| `nosniff` | `X-Content-Type-Options: nosniff` |
| `corsOrigin` ou `cors` | Origem CORS; `cors` também aceita um objeto com `origin` |
| `app_origins` | Origens de bundles: script e conexões |
| `connect_origins` | Origens de API: conexões |
| `wasm` | Permite a compilação WASM na CSP gerada |

O parser também contempla grafias camelCase para vários campos, como `appOrigins`, `connectOrigins`, `frameOptions` e `wasmUnsafeEval`. Para CORS, há uma exceção importante: `cors_origin` é o nome interno da estrutura, mas o JSON aceita `corsOrigin` ou `cors`, não essa grafia snake_case.

<span id="convenciones-de-valores"></span>

<span class="section-anchor" id="section-3"></span>

## Convenções de valores

Para os campos de cabeçalho de texto, uma string vazia deixa a decisão para o WU e `off` suprime esse cabeçalho. `csp: "report-only"` gera uma política equivalente no cabeçalho de relatório; o navegador informa violações sem bloqueá-las por essa política. Uma string CSP literal é usada como está.

A geração analisa os scripts inline do documento final e calcula hashes. Ela precisa ser executada após qualquer inserção de catálogo ou import map. Introduzir um handler HTML como `onclick` tem um tratamento diferente de um script com hash; os diagnósticos apontam incompatibilidades. Manter eventos em módulos e estilos em folhas evita depender de exceções do HTML.

Na 1.2.0, hashes CSP são calculados por página e normalizam quebras CRLF. `security.upgradeInsecureRequests` controla a promoção para HTTPS. O build preserva o `_headers` do shell, aplica cache imutável a arquivos com hash e valida valores contra injeção de cabeçalhos. Verifique a política realmente enviada pelo hosting com `wu doctor --url`.

<span class="section-anchor" id="section-4"></span>

## CORS

`Access-Control-Allow-Origin` não é emitido por padrão. Para servir microapps da mesma origem, não é necessário habilitar `*`. Quando a topologia exige uma origem diferente, configure o valor concreto e revise também a CSP, as credenciais e a política do destino.

A opção `cors` de uma regra de proxy pertence a essa regra. Não é idêntica a `security.corsOrigin`, que governa as respostas do servidor de produção.

<span id="archivos-publicables"></span>

<span class="section-anchor" id="section-5"></span>

## Arquivos publicáveis

A segurança de rotas decodifica escapes antes de verificar segmentos e rejeita traversal, controles, barras invertidas e caminhos absolutos. O filtro de arquivos bloqueia dotfiles e extensões ou nomes considerados sensíveis. `.well-known` é uma exceção deliberada porque contém documentos públicos de protocolo.

O build e `doctor` revisam áreas publicáveis, mas o lugar correto de uma credencial continua sendo o backend ou seu ambiente. Se uma aplicação precisar de um token privado, não deve incorporá-lo às fontes ou a `public/`, mesmo que um nome específico não apareça na lista de bloqueios.

O servidor de desenvolvimento aplica sua própria política de Host, CORS, HMR e acesso a arquivos, incluindo sourcemaps, módulos e imports com query. Configure túneis em `dev.allowedHosts`; apenas `VITE_*` e `WU_*` de `.env` chegam ao navegador. Consulte [desenvolvimento](/pt/docs/cli/development/) para migrar esses comportamentos.

<span class="section-anchor" id="section-6"></span>

## Sentinel

A instância do sentinel está desativada em `wu dev` e é instanciada com seus valores padrão em `wu serve`. Há código para classificar solicitações e publicar rotas de protocolo ACP. A existência desses módulos não comprova proteção universal contra automação nem substitui o controle de acesso do produto.

CLI `1.2.0` aceita `manifest: "define"` em cada app e `security.frameOrigins` para iframes remotos. As origens de frames entram apenas em `frame-src`; não habilitam scripts ou conexões do host. O filtro de navegação de catálogos não bloqueia leitura por fetch. Veja [apps remotas](/pt/docs/framework/remote-apps/) e [build](/pt/docs/cli/build/).

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-7"></span>

## Referência de implementação

- `wu-cli/src/config/config.zig`
- `wu-cli/src/runtime/security.zig`
- `wu-cli/src/runtime/project_fs.zig`
- `wu-cli/src/runtime/allowed_hosts.zig`
- `wu-cli/src/runtime/dev/env.zig`
- `wu-cli/tests/dev-security.test.cjs`
- `wu-cli/tests/doctor-policy.test.cjs`