# Content Security Policy e headers

> Diretivas de CSP que o SDK precisa, relatórios de violação, headers monitorados e relação com o PCI DSS.

URL: https://docs.proteside.com/pt-BR/docs/integration/csp

Se o seu checkout usa Content Security Policy (CSP), ela precisa permitir o snippet do Proteside. O dashboard não gera
uma CSP para você: esta página lista o que o SDK usa de fato no navegador, para você incluir na política da loja.

## Diretivas necessárias
| Diretiva      | Valor                                                                 | Para quê                                                                   |
| ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `script-src`  | hash, nonce ou `'unsafe-inline'` para os `<script>` inline do snippet | Executar o bootstrapper, que inclui as regras inline quando a loja as tem. |
| `script-src`  | `https://cdn.proteside.com`                                           | Carregar o `shield.js`.                                                    |
| `connect-src` | `https://app.proteside.com`                                           | Buscar a configuração e enviar eventos.                                    |
| `connect-src` | `'self'`                                                              | Ler os headers de segurança da própria página (veja abaixo).               |
| `connect-src` | origens dos scripts externos da página (opcional)                     | Calcular o hash do conteúdo dos scripts de terceiros.                      |

Sem `connect-src` para `app.proteside.com`, o SDK carrega e roda, mas nenhum evento chega ao dashboard.

### Os scripts inline do snippet
O bootstrapper é inline e precisa continuar inline (veja [Instalação do snippet](https://docs.proteside.com/pt-BR/docs/integration/install)). Escolha uma forma
de autorizá-lo:

* **Hash** (`'sha256-…'`): autoriza exatamente aquele conteúdo. O hash muda quando o conteúdo do script muda: cada
  vez que você recola um snippet de versão nova e, se a loja tem regras inline, sempre que recola o snippet depois de
  mudar regras ou containers do Google Tag Manager, porque as regras inline ficam no mesmo script. Snippets antigos,
  com a configuração inline numa tag separada, precisam de um segundo hash para ela.
* **Nonce:** se o seu servidor já gera um nonce por resposta, acrescente o atributo `nonce` às tags `<script>` do
  snippet ao colá-lo no template. O snippet do dashboard não traz `nonce`.
* **`'unsafe-inline'`:** funciona, mas libera qualquer script inline e enfraquece a política. Não recomendado em
  páginas de pagamento.

A forma mais segura de obter o hash é deixar o navegador calcular: publique a CSP sem o hash (de preferência em modo
`Content-Security-Policy-Report-Only`), abra o checkout e veja a mensagem de violação no console. Ela informa o valor
`'sha256-…'` do script bloqueado. Para calcular localmente, use exatamente o conteúdo entre `<script>` e `</script>`,
sem quebra de linha no final:

```bash title="Calcular o hash do bootstrapper"
# bootstrapper.js = conteúdo entre <script> e </script>, copiado do snippet
printf '%s' "$(cat bootstrapper.js)" | openssl dgst -sha256 -binary | openssl base64
```

## Exemplo de header
Um exemplo para um checkout em `minhaloja.com.br` com Stripe. Adapte as outras origens à sua loja.

```http title="Header de resposta da página de checkout"
Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'sha256-BOOTSTRAPPER_HASH' https://cdn.proteside.com https://js.stripe.com;
  connect-src 'self' https://app.proteside.com https://api.stripe.com;
  frame-src https://js.stripe.com;
  img-src 'self' data:;
  style-src 'self';
  report-uri https://app.proteside.com/api/sdk/csp-report?key=pk_live_SUA_CHAVE;
  report-to proteside
Reporting-Endpoints: proteside="https://app.proteside.com/api/sdk/csp-report?key=pk_live_SUA_CHAVE"
```

O header real vai em uma única linha; as quebras acima são só para leitura. Se o seu snippet é do formato antigo, com
a configuração inline numa tag `<script>` separada, acrescente também o hash dessa tag.

> **Nota**
>
> Se você usa o [selo Proteside](https://docs.proteside.com/pt-BR/docs/integration/badge), acrescente `https://app.proteside.com` em `img-src`. O SDK em si não
> precisa de `style-src` nem de `img-src`.

## Relatórios de violação
O Proteside recebe relatórios de CSP no endereço abaixo. Ele não aparece em nenhuma tela do dashboard; use a sua chave
do SDK no parâmetro `key`:

```text
https://app.proteside.com/api/sdk/csp-report?key=pk_live_SUA_CHAVE
```

* Aceita os dois formatos: `report-uri` e `report-to` (Reporting API).
* O total aparece em **Saúde do SDK**, no card **Relatórios CSP (48 h)**.
* Uma violação de `script-src` ou `connect-src` para um host que **não** está no inventário de scripts da loja vira o
  alerta `CSP_VIOLATION`, com severidade baixa. Violações de outras diretivas só entram na contagem.

Para testar uma política nova sem quebrar o checkout, publique primeiro como `Content-Security-Policy-Report-Only`,
acompanhe os relatórios e depois troque para `Content-Security-Policy`.

## Headers de segurança monitorados
Para apoiar a detecção de mudanças em headers, o SDK lê os headers de segurança da página de pagamento a cada
carregamento e a cada `Proteside.pageChanged()`:

`Content-Security-Policy`, `Content-Security-Policy-Report-Only`, `Strict-Transport-Security`, `X-Frame-Options`,
`X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, `Cross-Origin-Opener-Policy`,
`Cross-Origin-Embedder-Policy`, `Cross-Origin-Resource-Policy`, `Access-Control-Allow-Origin` e `Set-Cookie` (este só
como "não legível no navegador").

O valor de cada header presente é enviado ao dashboard. Quando um valor muda, o dashboard cria o alerta
`HEADER_CHANGED`. Os headers aparecem em **Evidências PCI DSS**, na aba **Headers**.

> **Uma requisição GET extra por pageview**
>
> Para ler os headers, o SDK faz uma requisição `GET` adicional à URL da própria página. Se o seu checkout executa alguma ação ao receber um `GET` (criar pedido, reservar estoque, gerar
> cobrança), essa ação vai acontecer duas vezes. Garanta que o `GET` da página de pagamento não tenha efeitos
> colaterais.

## Subresource Integrity (SRI)
Não use o atributo `integrity` na tag do `shield.js`. A URL é mutável: o mesmo endereço recebe cada nova versão do
SDK, então o hash mudaria a cada publicação e o navegador passaria a recusar o script.

Como controle preventivo, restrinja `script-src` a `https://cdn.proteside.com` e autorize o bootstrapper inline por
hash ou nonce. O inventário do Proteside registra quais scripts da sua página usam `integrity` e `nonce`.

## Relação com o PCI DSS 4.0
| Requisito | O que pede                                                                                                                                               | Como o Proteside e a CSP ajudam                                                                                                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 6.4.3     | Gerenciar os scripts da página de pagamento executados no navegador: inventário com justificativa, autorização de cada script e garantia de integridade. | O SDK monta o inventário com hash do conteúdo; a autorização com justificativa é feita em **Scripts**; as regras bloqueiam scripts não autorizados. A CSP limita de onde scripts podem ser carregados. |
| 11.6.1    | Detectar e alertar mudanças não autorizadas nos headers HTTP e no conteúdo da página de pagamento, como recebidos pelo navegador.                        | O SDK lê os headers de segurança a cada pageview e detecta scripts novos ou modificados; o dashboard gera `HEADER_CHANGED`, `SCRIPT_INTEGRITY_MISMATCH` e os demais alertas.                           |

O Proteside gera evidências para esses requisitos em **Evidências PCI DSS**. A avaliação de conformidade continua
sendo do seu avaliador (QSA) ou do seu questionário de autoavaliação. Veja
[Evidências PCI DSS](https://docs.proteside.com/pt-BR/docs/guide/compliance). O contexto dos dois requisitos está em
[PCI DSS 6.4.3 e 11.6.1](https://proteside.com/solucao/conformidade-pci), no site.

## Próximos passos
* [Privacidade e LGPD](https://docs.proteside.com/pt-BR/docs/integration/privacy)
* [Solução de problemas](https://docs.proteside.com/pt-BR/docs/integration/troubleshooting)
