Anti-padrões de segurança em APIs

Checklist preventivo aplicado às APIs do monorepo. Cada item é uma armadilha clássica de segurança em REST com a forma de mitigação adotada por padrão na Fábrica.

1. Não colocar segredos em URL sem mascarar logs

• Tokens em path vazam facilmente para logs de aplicação, proxies, APM e histórico.
• Se a URL precisar carregar um token de uso único, o log operacional deve registrar apenas a rota sanitizada.

2. Não expor DTO interno como resposta pública

• DTO persistido costuma conter campos administrativos ou dados pessoais que não pertencem à interface pública.
• Links públicos devem projetar explicitamente o payload retornável.

3. Não usar fallback implícito para claims sensíveis de JWT

• Claims como CPF precisam de um nome canônico único.
• sub ?? cpf ou padrões equivalentes geram ambiguidade e risco de associar dados ao identificador errado.

4. Não transformar falha de autenticação em anonimato silencioso

• Fluxo anônimo só é aceitável quando a requisição realmente não trouxe credencial.
• Se Authorization foi enviado e a validação falhou, a resposta deve ser erro e o evento deve ser tratado como falha de autenticação.

5. Não revelar existência de recurso multi-tenant

• Quando o recurso pertence a um usuário específico, a consulta deve combinar identificador do recurso e identificador do dono.
• O retorno deve ser 404 tanto para "não existe" quanto para "existe, mas é de outro usuário".

6. Contrato de erro deve refletir o framework real

• Se a API usa createError nativo do Nitro/H3, isso precisa estar explícito na documentação e nos testes.
• Não documente um envelope de erro diferente daquele que o cliente realmente recebe.

Quando considerar um envelope híbrido

• Exigência formal de padronização de erro em todos os apps.
• Necessidade de uniformidade cross-app para SDKs ou gateways.
• Geração OpenAPI/cliente prejudicada pelo formato nativo do framework.