# Verifica (JohnnyDevIT) — certificação de conteúdo de sites (protocolo VSP1)

> Verifica certifica que o conteúdo servido por um domínio é o publicado pelo dono. O dono publica uma chave Ed25519 num TXT `_vsp.<domínio>` (como o DKIM), assina fora do servidor um manifesto com o SHA-256 de cada arquivo (e a "superfície executável" das páginas dinâmicas), o hash do manifesto é registrado na blockchain VERA (testnet), e um monitor compara o site no ar com a última versão assinada a cada 10 minutos.

Este arquivo é a especificação para agentes de IA que vão integrar o Verifica num projeto. Página para pessoas: https://johnnydevit.cloud/verifica/instrucoes

## Regras para o agente

- NUNCA coloque a chave privada (`VSP_KEY`, formato `vsp1_...`, ou o arquivo `vsp-chave-*.json`) no código, em commits, em logs ou em mensagens. Ela vai só como segredo do deploy (GitHub Secrets, variável de ambiente do servidor de CI etc.).
- Quem gera e guarda a chave é o dono, no painel: https://johnnydevit.cloud/verifica/painel (login por código no e-mail; a chave fica cifrada no navegador com a frase-senha do dono). Peça ao dono para copiar a chave no painel; não tente gerar chave em nome dele.
- O TXT do DNS é publicado pelo dono no provedor de DNS. O agente informa o valor exato; não invente o valor.
- Assine exatamente os arquivos que estarão no ar. Se o build muda depois da assinatura, o site fica "alterado" (vermelho).
- Toda nova versão do site exige nova assinatura. Integre o passo ao pipeline de deploy.

## Integração recomendada (pipeline de deploy)

1. O dono já registrou o domínio no painel (TXT publicado + "Conferir DNS e registrar esta chave").
2. O dono copiou a chave no painel e a gravou como segredo `VSP_KEY` no CI.
3. Baixe o comando (só precisa de Python 3.8+, sem dependências):
   `curl -fsSLo vsp-publish.py https://johnnydevit.cloud/verifica/static/vsp-publish.py`
   (ou copie o arquivo para o repositório)
4. Site estático — rode DEPOIS do build e ANTES de enviar os arquivos:
   `python3 vsp-publish.py --domain DOMINIO --dir ./dist`
   Isso grava `./dist/.well-known/vsp.json`; envie a pasta inteira em seguida.
5. Páginas dinâmicas (SSR) — rode DEPOIS do deploy (o comando lê as páginas no ar):
   `python3 vsp-publish.py --domain DOMINIO --page /login --page /conta --out CAMINHO_NO_SERVIDOR/.well-known/vsp.json`
   O vsp.json precisa ser servido em `https://DOMINIO/.well-known/vsp.json`.
6. Opções: `--base /subpasta/` (arquivos de --dir ficam numa subpasta do site); `--key-file vsp-chave-DOMINIO.json` (em vez de VSP_KEY); `--dir` e `--page` podem ser usados juntos (página em modo código vence o arquivo de mesmo caminho).
7. Verifique: `curl -s -X POST -H 'content-type: application/json' -d '{"domain":"DOMINIO"}' https://johnnydevit.cloud/verifica/api/check` → `check.status` deve ser `ok`.

Exemplo GitHub Actions:

```yaml
- name: Certificar versão no Verifica
  env:
    VSP_KEY: ${{ secrets.VSP_KEY }}
  run: |
    curl -fsSLo vsp-publish.py https://johnnydevit.cloud/verifica/static/vsp-publish.py
    python3 vsp-publish.py --domain exemplo.com.br --dir ./dist
```

## Registro DNS

- Nome: `_vsp.<domínio>` — Tipo: TXT
- Valor: `v=VSP1; k=ed25519; p=<chave pública Ed25519, 32 bytes, base64 padrão>`
- Exatamente um registro `v=VSP1` por nome. Os resolvedores Cloudflare e Google precisam concordar (propagação).
- DNSSEC é recomendado (exibido como "DNSSEC ativo").

## Manifesto VSP1

String JSON assinada byte a byte (Ed25519 sobre os bytes UTF-8 da string, sem canonicalização posterior):

```json
{"v":"VSP1","domain":"exemplo.com.br","issued_at":1792415939,"prev":null,
 "files":{"/index.html":"<sha256 hex>","/app.js":"<sha256 hex>"},
 "pages":{"/conta":{"csp":"<CSP normalizada ou null>","code":["<item>", "..."]}}}
```

- `issued_at`: unix time, no máximo 24 h no passado e 10 min no futuro.
- `prev`: `manifest_sha` da última versão registrada (null na primeira). Obtenha em `GET /api/site/<domínio>` → `versions[0].manifest_sha`. Impede repetir versões antigas.
- `files` (modo exato): caminho URL → SHA-256 hex do corpo servido. Caminhos começam com `/`, sem `..`, `?`, `#`, `//` ou barra final. `/x/index.html` é buscado como `/x/`. `/.well-known/vsp.json` não entra.
- `pages` (modo código, opcional): caminho → superfície executável, obtida com `POST /api/surface`. Os itens de `code` vêm ordenados e sem repetição.
- Total de 1 a 500 itens (files + pages); até 25 MB por arquivo.

Superfície executável (modo código) — o que o monitor compara numa página dinâmica:
- `script:<url>` (script externo) e `inline:<tipo>:<sha256>` (script embutido executável);
- `chunk:<static/chunks/...js>` (módulos pedidos pelo payload do Next.js);
- `on:<tag>:<atributo>:<sha256>` (handlers inline) e `jsurl:<tag>:<atributo>:<sha256>` (URLs javascript:);
- `frame:<url>`, `form:<action> <method>`, `object:<tag>:<url>`, `link:<rel>:<url>` (stylesheet/modulepreload), `base:<href>`, `meta:<http-equiv>:<conteúdo>`;
- `csp`: cabeçalho Content-Security-Policy com nonces trocados por `'nonce'`.
Ignorados (dados): texto, `<script type="application/json">`, `application/ld+json`, payload `self.__next_f.push([n,"..."])`.

## vsp.json (servido pelo site)

`https://<domínio>/.well-known/vsp.json` = resposta `vsp_json` do publish:
`{"v":"VSP1","domain":...,"manifest":"<string assinada>","sig":"<base64>","anchor":{"chain":"vera-testnet-1","tx":...,"block":...},"verify":"https://johnnydevit.cloud/verifica/s/<domínio>"}`

## API (base https://johnnydevit.cloud/verifica/api, JSON, POST exige content-type application/json)

- `GET /site/<domínio>` → registro público: chave, versões (com `manifest_sha`), última verificação. 404 se não registrado.
- `GET /vsp/<domínio>` → vsp.json da última versão.
- `GET /sites` → domínios registrados e status.
- `POST /dns {"domain"}` → chave encontrada no TXT (diagnóstico).
- `POST /register {"domain","public_key"}` → registra/atualiza a chave do domínio; exige que o TXT traga exatamente essa chave. Ancora na blockchain.
- `POST /surface {"domain","path"}` → `{"surface":{...},"assets":{"/caminho":"sha256"}}` da página no ar (só domínios registrados). Inclua `assets` em `files`.
- `POST /publish {"domain","manifest","sig"}` → registra a versão; resposta traz `seq`, `block`, `tx_hash`, `vsp_json`, `verify_url`. Erros 400 explicam o motivo (assinatura, prev, prazo, formato).
- `POST /check {"domain"}` → verifica agora (1 vez por minuto por domínio).
- `GET /badge/<domínio>.svg` → selo (cache 60 s).
Limites: 30 registros/publicações por hora por IP; 60 leituras de superfície por hora por IP.

## Status do monitor

- `ok` — tudo confere.
- `altered` — arquivo mudado/ausente ou código novo em página dinâmica sem assinatura.
- `dns` — TXT com outra chave ou ausente.
- `incomplete` — arquivos conferem, vsp.json ausente ou desatualizado.
- `unreachable` — site inacessível.
- `pending` — sem versão publicada ou ainda não verificado.

## Chave

- Ed25519. Formato `VSP_KEY`: `vsp1_` + base64url sem padding do PKCS#8 DER (48 bytes; os 32 últimos são a semente).
- Arquivo de chave: `{"type":"vsp1-key","domain":...,"public_key":"<base64>","private_key_pkcs8":"<base64>","created_at":...}`.
- Troca de chave: o dono gera outra no painel, publica o TXT novo e registra. A troca fica na blockchain e a página pública avisa por 72 h. Chaves antigas deixam de publicar.

## Selo

```html
<a href="https://johnnydevit.cloud/verifica/s/DOMINIO" target="_blank" rel="noopener"><img src="https://johnnydevit.cloud/verifica/badge/DOMINIO.svg" alt="Verificado pelo Verifica" height="22"></a>
```
O selo é atalho para a verificação pública, não a prova em si.

## Limitações

- Rede de testes (VERA SmartChain testnet); serviço em MVP.
- Conteúdo de terceiros é verificado só pelo endereço.
- O monitor não acessa áreas com login.
- Certifica autenticidade do conteúdo, não a idoneidade do dono.