# Segurança

O Agente roda na máquina do cliente com acesso ao certificado da empresa. Esta página descreve o que ele protege, como, e o que fica sob responsabilidade de quem opera.

## O que nunca sai da máquina

| Item | Onde fica | Quem acessa |
| --- | --- | --- |
| Chave privada do certificado | No arquivo `.pfx` informado, no token A3 ou no repositório do Windows. | Só o processo do Agente, na hora de assinar ou de abrir o TLS com a SEFAZ. Nunca é copiada, exportada ou transmitida. |
| Senha do PFX / PIN do token | Cofre de senhas do sistema operacional. Sem cofre (Linux headless): arquivo com permissão restrita ao usuário. | Só o Agente. Nunca em log, nunca na configuração, nunca no painel. |
| Notas off-line e numeração | `nfce/nfce.db`, `nfce/notas/*.json.gz`, backups. | O Agente; o servidor recebe cada nota na sincronização. |

O que **trafega** para o Brasil NFe: metadados públicos do certificado (titular, emissor, validade, thumbprint, certificado público em Base64), assinaturas prontas, respostas da SEFAZ, a telemetria de status (versão, plataforma, nome da máquina, série, contadores da fila) e as notas off-line (JSON + XML assinado). Nada disso permite assinar em nome da empresa fora do Agente.

O que o **pacote fiscal off-line** contém: as regras fiscais da NFC-e (montagem/assinatura do XML, QR Code, DANFE), schemas e tabelas. **Não** contém senhas, tokens, integrações nem o painel. A configuração fiscal da empresa que ele recebe tem os campos secretos removidos (senha do certificado, código de pareamento, token da API, segredos de integração); o CSC fica porque o QR Code exige.

## O código de pareamento como credencial

- É uma **credencial de portador**: quem o apresenta ao Brasil NFe fala como aquela empresa. Guarde como senha; nunca o coloque no PDV nem em páginas web (o PDV não precisa dele: ele fala com a API local, e a API local é quem apresenta o código ao servidor).
- **Revogável** no painel a qualquer momento, com efeito imediato (o Agente é derrubado). Gerar um novo código também invalida o anterior.
- **Uma conexão por empresa**: uma segunda instância com o mesmo código derruba a primeira ("substituído"). Se você vir esse estado sem ter instalado outro Agente, **revogue o código** e investigue.
- O `UserToken` da API **nunca** passa pelo Agente nem pelo navegador: ao encaminhar uma NFC-e online, o Agente chama um endpoint autenticado pelo código de pareamento e é o servidor que usa o token da empresa por dentro.

## Assinatura: limites e auditoria

- O Agente assina no padrão exigido pela SEFAZ apenas o que o servidor (ou o pacote fiscal off-line) monta; ele não monta documentos por conta própria.
- Há limites de tamanho e quantidade por lote de assinatura, para que um código vazado não transforme o Agente num "oráculo" de assinatura ilimitado.
- **Auditoria local** em `audit.db`: data/hora, empresa, certificado, hash do dado assinado, tamanho e latência, por item. Só metadados. Use para investigar qualquer suspeita de uso indevido.
- O pacote off-line pede assinaturas ao Agente com **autorização de uso único**, válida só para a empresa e a nota em curso.

## Conexões de rede

| Conexão | Proteção |
| --- | --- |
| Agente ⇄ Brasil NFe | Sempre TLS (`wss://`/`https://`), autenticado pelo código de pareamento. |
| Agente → SEFAZ (mTLS) | Só endereços oficiais das SEFAZ; certificado do servidor validado contra as raízes do sistema + ICP-Brasil embutidas. Proxy só por túnel, com TLS ponta a ponta. |
| PDV → Agente (API local) | HTTP em `127.0.0.1:9155` por padrão. Navegadores só das origens autorizadas (CORS + checagem de `Origin`, 403 fora da lista). Sem origem configurada, nenhuma página web chama. |
| Operações internas (assinatura para o pacote fiscal, correção de nota) | Só dentro da própria máquina, com autorização de uso único; recusam chamadas de navegador. |

Ao expor a API local na rede (`--bind 0.0.0.0`, servidor de loja), restrinja a porta no firewall à rede interna dos caixas. A API local não tem autenticação própria: ela confia na rede em que está exposta e nas origens autorizadas para navegadores.

## Pacote fiscal e atualizações assinados

- O pacote fiscal e cada release do Agente são **assinados digitalmente** pelo Brasil NFe; a chave de verificação está embutida no Agente.
- O Agente recusa pacote sem assinatura válida, com arquivo faltando ou com hash divergente, faz um autoteste antes de ativar e instala na pasta de dados do usuário. A versão anterior fica para rollback.
- Atualização do Agente: hash do instalador + assinatura verificados antes de aplicar. Instalações `.deb`/`.rpm` não se autoatualizam (o gerenciador de pacotes é a cadeia de confiança).
- A assinatura de código **Authenticode** do instalador Windows (SmartScreen) está em implantação; até lá, confira o SHA-256 exibido na página de download.

## Console remoto

O painel executa no Agente uma **lista fechada** de comandos (`status`, `notas`, `nota`, `config`, `update`), sempre no escopo da empresa da conexão. Não há execução de shell nem de código arbitrário. Parear e remover pareamentos só é possível na máquina.

## Dados no disco

- Pasta de dados por usuário (`%APPDATA%\br.com.brasilnfe.agent\` ou `~/.local/share/br.com.brasilnfe.agent/`). No Linux headless, o segredo do certificado fica em arquivo com permissão restrita ao usuário.
- O DANFE não é guardado (é regenerado do XML).
- Backups do banco em `Documentos\BrasilNFe Agente\backup-nfce` (Windows) ou `nfce/backup`. Se a pasta Documentos sincroniza com OneDrive/Drive, os backups também sincronizam: leve isso em conta na política de dados da empresa (contêm as notas emitidas off-line, sem nenhum segredo).
- Nada é apagado do banco; arquivos por nota de notas transmitidas há mais de 90 dias são removidos.

## Recomendações operacionais

1. **Uma conta de usuário dedicada** para o serviço em servidores (systemd `User=`), e o `pair` feito com essa conta.
2. **Relógio certo** na máquina (NTP): TLS com a SEFAZ e a data de emissão das notas dependem disso.
3. **Firewall**: saída 443 para `api.brasilnfe.com.br` e SEFAZ; entrada na porta da API local só da rede dos caixas, se exposta.
4. **Perdeu a máquina ou suspeita de vazamento**: revogue o código no painel imediatamente e gere outro; troque a senha do certificado se ele estava em arquivo.
5. **Certificado vencendo**: a validade aparece na lista de empresas; renove antes.
6. **Mantenha a atualização automática ligada** (padrão). Ela é assinada e corrige problemas sem visita à loja.
7. **Monitore a fila off-line**: o alerta de 12 h (tela, log, painel) indica nota que não conseguiu subir; o prazo legal da contingência off-line é de 24 h na maioria das UFs.
8. **Não compartilhe** o código de pareamento com o fornecedor do PDV: ele não é necessário para a integração.