refatoração de segurança e logs
This commit is contained in:
parent
6873b87a85
commit
663a8d5bf2
12 changed files with 362 additions and 37 deletions
150
.agent
Normal file
150
.agent
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
# arquivo: .agent
|
||||
# Agente de desenvolvimento para o projeto e-li.nps
|
||||
#
|
||||
# Projeto:
|
||||
# Widget NPS embutível via 1 arquivo JS + API em Go.
|
||||
# Foco em robustez, segurança, tipagem consistente, observabilidade
|
||||
# e operação simples em ambientes reais (Docker / Proxy / Produção).
|
||||
|
||||
agent_name: "quero_nps"
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Descrição do projeto (fonte de verdade)
|
||||
# -------------------------------------------------------------------
|
||||
project_description:
|
||||
- "Widget NPS carregado via 1 arquivo JavaScript (e-li.nps.js)."
|
||||
- "API HTTP escrita em Go."
|
||||
- "PostgreSQL como banco de dados."
|
||||
- "Painel administrativo opcional protegido por senha."
|
||||
- "Uso por aplicações externas via <script>."
|
||||
- "Fail-closed: se a API falhar, o widget não abre."
|
||||
- "CORS liberado para uso amplo."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Stack
|
||||
# -------------------------------------------------------------------
|
||||
project_stack:
|
||||
backend: "Go 1.22+"
|
||||
database: "PostgreSQL 14+"
|
||||
widget: "JavaScript puro (arquivo único)"
|
||||
frontend_internal:
|
||||
- "HTML server-side"
|
||||
- "HTMX (opcional, apenas se já estiver presente no painel)"
|
||||
optional_logic_layer:
|
||||
- "Go → WebAssembly (WASM), apenas se adotado explicitamente no projeto"
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Regras gerais
|
||||
# -------------------------------------------------------------------
|
||||
rules:
|
||||
- "Respeitar fielmente o comportamento descrito no README.md."
|
||||
- "Não alterar contratos públicos do widget sem versionamento."
|
||||
- "Evitar mudanças que quebrem widgets já embedados em clientes."
|
||||
- "Mudanças que impactem desenvolvedores OU usuários DEVEM ser documentadas."
|
||||
- "Código deve ser previsível, explícito e fácil de auditar."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Linguagem, nomes e comentários
|
||||
# -------------------------------------------------------------------
|
||||
naming_and_language:
|
||||
- "Nomes de variáveis, funções e arquivos preferencialmente em português."
|
||||
- "Nomes orientados ao domínio NPS (ex: `registrarPedido`, `finalizarResposta`)."
|
||||
- "Comentários SEMPRE em português."
|
||||
- "Comentários devem explicar regras de negócio e decisões técnicas."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Contratos e tipagens
|
||||
# -------------------------------------------------------------------
|
||||
typing_and_contracts:
|
||||
- "Contratos de API devem ser explícitos e estáveis."
|
||||
- "Campos-chave das regras de exibição: produto + inquilino_codigo + usuario_codigo."
|
||||
- "Normalizações técnicas NÃO alteram valores exibidos ao usuário."
|
||||
- "Tipagens JS/TS são auxiliares e não substituem validação no backend."
|
||||
- "Validação SEMPRE no servidor."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Widget JavaScript
|
||||
# -------------------------------------------------------------------
|
||||
widget_policy:
|
||||
- "Widget deve ser carregado via um único <script>."
|
||||
- "Nenhuma dependência externa no cliente."
|
||||
- "Cache controlado exclusivamente pelo servidor via ETag."
|
||||
- "Browser sempre revalida o JS."
|
||||
- "Se a API falhar, o widget NÃO deve abrir (fail-closed)."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Backend Go
|
||||
# -------------------------------------------------------------------
|
||||
backend_policy:
|
||||
- "Servidor Go é a autoridade de regras e persistência."
|
||||
- "Tabelas criadas automaticamente por produto: nps_{produto}."
|
||||
- "Normalização de produto SOMENTE para uso técnico."
|
||||
- "Nunca usar dados não normalizados em SQL."
|
||||
- "Painel só habilita se SENHA_PAINEL estiver definida."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Segurança: prevenção de SQL Injection (OBRIGATÓRIO)
|
||||
# -------------------------------------------------------------------
|
||||
sql_injection_prevention:
|
||||
- "NUNCA concatenar SQL com entrada do usuário."
|
||||
- "Usar queries parametrizadas SEMPRE."
|
||||
- "Identificadores dinâmicos SOMENTE via normalização + regex + allowlist."
|
||||
- "Regex obrigatória: ^[a-z_][a-z0-9_]*$."
|
||||
- "ORDER BY dinâmico apenas com colunas previamente definidas."
|
||||
- "Toda decisão dinâmica de SQL deve ser comentada."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Observabilidade e logs (OBRIGATÓRIO)
|
||||
# -------------------------------------------------------------------
|
||||
logging_policy:
|
||||
- "Registrar logs relevantes em toda a aplicação."
|
||||
- "Logar: inicialização, rotas, chamadas de API, banco e erros."
|
||||
- "Registrar tempo de execução das requisições."
|
||||
- "Incluir IP real do usuário quando disponível."
|
||||
- "Evitar log excessivo ou redundante."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Proteção de segredos nos logs (CRÍTICO)
|
||||
# -------------------------------------------------------------------
|
||||
secrets_policy:
|
||||
- "NUNCA logar senhas, tokens, cookies, Authorization, secrets ou DSN."
|
||||
- "Campos sensíveis devem ser omitidos ou mascarados."
|
||||
- "Na dúvida, NÃO LOGAR."
|
||||
- "Usar '[REDACTED]' quando necessário."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Proxy e IP real
|
||||
# -------------------------------------------------------------------
|
||||
proxy_policy:
|
||||
- "Respeitar X-Forwarded-For e X-Real-IP."
|
||||
- "Uso de middleware RealIP é obrigatório."
|
||||
- "Persistir IP real para auditoria."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# README.md — regra OBRIGATÓRIA
|
||||
# -------------------------------------------------------------------
|
||||
readme_policy:
|
||||
- "O README.md é a fonte de verdade operacional do projeto."
|
||||
- "SE a mudança for IMPORTANTE para o DESENVOLVEDOR, atualizar o README.md."
|
||||
- "SE a mudança for IMPORTANTE para o USUÁRIO, atualizar o README.md."
|
||||
- "Considera-se mudança importante:"
|
||||
- "– alteração de API, contrato ou payload"
|
||||
- "– mudança no widget ou forma de embed"
|
||||
- "– cache, ETag ou comportamento de atualização"
|
||||
- "– variáveis de ambiente"
|
||||
- "– segurança, CORS, autenticação ou painel"
|
||||
- "– forma de rodar, build ou deploy"
|
||||
- "O README deve explicar o impacto da mudança e como usar o novo comportamento."
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# Checklist final
|
||||
# -------------------------------------------------------------------
|
||||
checklist:
|
||||
- "[ ] Compatível com widgets já publicados"
|
||||
- "[ ] SQL 100% parametrizado"
|
||||
- "[ ] Identificadores normalizados e validados"
|
||||
- "[ ] Logs relevantes presentes"
|
||||
- "[ ] Nenhum segredo em logs"
|
||||
- "[ ] Cache do JS controlado por ETag"
|
||||
- "[ ] README.md atualizado se a mudança impacta dev ou usuário"
|
||||
- "[ ] Fluxo principal testado manualmente"
|
||||
Loading…
Add table
Add a link
Reference in a new issue