# Segurança

## Transporte e acesso

- HTTPS é obrigatório em produção.
- A API deverá exigir autenticação antes de expor operações protegidas.
- Rate limiting deve ser aplicado de acordo com o risco e o consumidor.
- Contas, credenciais e serviços devem seguir o princípio do menor privilégio.

## Segredos e tokens

- Segredos pertencem somente ao `.env` ou a um gerenciador seguro de segredos.
- O arquivo `.env` nunca deve ser versionado.
- Access tokens, refresh tokens, client secrets, senhas e chaves de API nunca devem ser registrados em logs.
- Valores de exemplo devem ser vazios ou claramente fictícios.
- Os casts `encrypted` de `BlingConnection` protegem os tokens no banco e `$hidden` os remove da serialização. A `APP_KEY` deve ser preservada em armazenamento seguro: perdê-la impede a leitura dos tokens existentes. Nunca regenere a chave de um ambiente com dados criptografados sem planejar a rotação.

## Entrada e dados

- Toda entrada externa deve ser validada.
- Dados sensíveis devem ser minimizados e protegidos em repouso.
- Operações de banco destrutivas não podem ser executadas em bases com dados existentes.
- Backups devem ser periódicos, protegidos e ter restauração testada.

## Auditoria e integrações

- Eventos relevantes devem gerar logs de auditoria sem segredos.
- Nesta base, `IntegrationLog` fornece somente persistência; não há captura HTTP nem sanitização automática de payloads. Nunca grave requests, responses ou exceções brutas. A futura camada de auditoria deve selecionar campos permitidos e remover credenciais antes de persistir dados, endpoints e mensagens de erro.
- Operações externas devem ser rastreáveis por solicitação.
- Idempotência e proteção contra duplicidade são obrigatórias antes da criação real de Ordens de Serviço.
- Uma Ordem de Serviço exige confirmação explícita antes do envio ao Bling.

## Manutenção

- Dependências devem ser atualizadas de forma controlada e acompanhadas por testes.
- Alertas de segurança devem ser avaliados e corrigidos conforme severidade e exposição.
- Alterações sensíveis devem receber revisão antes do merge.

- A entrada de clientes de IA é estruturada e validada; ela não aceita payload bruto do Bling nem autoriza envio automático.
- Respostas para IA não expõem mensagem original, payload interno, logs completos, tokens, `Authorization` ou `client_secret`.
- Conteúdo fornecido à IA é não confiável e não pode alterar instruções, confirmar uma OS ou autorizar ações externas. Structured Outputs complementam, mas não substituem, validação no backend. A chave OpenAI é segredo e nunca é registrada.
- O canal ChatGPT exige Bearer API key dedicada, comparação resistente a timing attacks, HTTPS em produção e rate limit. Essa chave, `Authorization`, payloads e mensagens completas nunca são logados.
- Todas as rotas operacionais de criação, preparação, alteração, consulta, confirmação, cancelamento e busca exigem autenticação; OAuth callback e health permanecem públicos. Não existe rota pública alternativa para confirmar uma OS. A idempotência de preparação usa chave por canal, constraint única e recuperação após colisão de concorrência.
- A Idempotency-Key externa do ChatGPT é transformada em hash determinístico antes de persistência. A chave literal não é armazenada em banco, logs, respostas ou exceções; a constraint única continua sendo a barreira final de idempotência.

- O instalador só pode ser usado antes do marcador de instalação existir. As rotas administrativas exigem sessão e perfil administrativo. Configurações operacionais usam allowlist e mantêm backup do arquivo de ambiente sem incluir valores sensíveis em logs. Atualizações não executam comandos arbitrários ou `git pull`.

- O painel administrativo exige perfil administrativo, reautenticação para ações sensíveis e never registra segredos. Backups completos incluem `.env` e dump de banco exclusivamente em armazenamento privado; nunca ficam em `public`.
