# Boas práticas

> Regras obrigatórias de segurança, o checklist para Agents e o "faça / não faça" do OonCore.

A segurança da Central é aplicada no backend. O frontend pode ocultar ou exibir ações, mas não é a fonte de decisão.

## Regras obrigatórias

- Toda operação sensível valida usuário autenticado.
- Toda alteração de dados valida permissão.
- Toda ação de integração valida permissão e contexto.
- Nunca confie em `tenantId`, `appId`, perfil ou roles enviados livremente pelo frontend.
- Segredos vêm de variáveis de ambiente, de [core.secrets](/docs/capabilities/segredos) ou de cofre equivalente.
- Logs não expõem tokens, senhas, app keys ou dados sensíveis desnecessários.

## Checklist antes de concluir uma alteração

- [ ] Existe validação de entrada?
- [ ] Existe validação de permissão no backend?
- [ ] Existe tratamento de erro com `code`?
- [ ] A operação gera rastreabilidade?
- [ ] Algum segredo foi colocado no código?
- [ ] Algum dado sensível foi exposto no frontend?
- [ ] O comportamento funciona para múltiplos usuários e múltiplos apps?

## Faça

- Use o Core antes de criar código novo.
- Modele o domínio com clareza.
- Prefira configuração e metadata.
- Escreva validações explícitas.
- Mantenha regras críticas no backend.
- Use esteiras para processos com status.
- Registre erros de forma operacional.
- Mantenha compatibilidade com a atualização dos pacotes.
- Atualize `.ooncore/` com `npm run ooncore:docs`.

## Não faça

> [!DANGER]
> - Não recrie CRUD, autenticação ou shell.
> - Não duplique RBAC no frontend.
> - Não crie um frontend inteiro se um override resolve.
> - Não chame APIs externas direto de qualquer lugar — use rota e serviço do App.
> - Não hardcode tenant, app, usuário, URL sensível ou segredo.
> - Não coloque regra crítica apenas no frontend.
> - Não ignore logs e rastreabilidade.
> - Não edite `.ooncore/` manualmente.

## Dados sensíveis

| Recurso | O que faz | O que **não** faz |
|---|---|---|
| `sensitiveBody` | Omite corpo de entrada e resposta no requestLog | Não cifra banco, não mascara console/URL/headers/auditoria |
| Auditoria do CRUD | Registra mutações em `ControleAlteracao` | Não é trilha imutável de todas as tentativas |
| `audit` em rota | Captura dados da resposta | Não deve receber credenciais |
| `core.secrets` | Cifra valores em repouso (AES-256-GCM) | Não é sandbox: o callback pode vazar o valor |

## Frontend

- PDF/HTML de usuário: prévia em `<iframe sandbox="" srcDoc={html} />`.
- Nada de bearer em `localStorage`; o Core usa cookie/sessão.
- Nenhuma variável `VITE_*` com segredo — tudo que está no bundle é público.

Fonte: https://sdk.oonapps.com/docs/seguranca/boas-praticas