# Autenticação e autorização por papéis

**Categoria:** Segurança & Confiabilidade  
**Guia(s) de referência:** HTTP + Web APIs + Arquitetura Limpa  

## Prompt completo

```text
Atue como **Security Engineer Sênior com experiência em aplicações Web**. Use o guia **“HTTP + Web APIs + Arquitetura Limpa”** como contrato técnico/conceitual principal para esta tarefa. Não trate o guia como decoração: use sua terminologia, critérios de decisão, limites e checklist durante o diagnóstico, a implementação e a revisão final.

## 1. Contexto do projeto
Estou trabalhando em uma aplicação real na qual preciso **adicionar login, sessão e controle de acesso para perfis distintos**.

Considere como exemplo de ambiente inicial:
- Aplicação em produção ou em homologação, com código existente que deve ser preservado quando não fizer parte do escopo.
- Equipe pequena/média, manutenção contínua e necessidade de facilitar futuras alterações.
- Controle de versão Git, revisão antes de merge e necessidade de uma solução testável.
- Quando houver interface Web, considerar desktop e mobile, navegação por teclado e feedback claro ao usuário.

Antes de sugerir código, identifique o que ainda precisa ser confirmado sobre linguagem, framework, versões, persistência, integrações, modelo de execução e restrições do ambiente. Não suponha detalhes que alterem a solução.

## 2. Objetivo
O objetivo desta tarefa é **separar autenticação, autorização, sessão, auditoria e UX de acesso negado com princípio do menor privilégio**.

Transforme esse objetivo em critérios observáveis de conclusão. Separe:
1. comportamento que deve existir;
2. comportamento atual que deve ser preservado;
3. responsabilidades que serão alteradas;
4. responsabilidades que devem permanecer fora do escopo.

## 3. Stack tecnológica
Use somente tecnologias confirmadas no contexto do projeto. Antes de implementar:
- liste linguagem, framework, runtime e versões relevantes;
- identifique banco de dados, APIs, bibliotecas e gerenciador de pacotes envolvidos;
- confirme se existe pipeline de build/testes;
- destaque qualquer incompatibilidade ou informação ausente que seja realmente bloqueadora.

Se eu não fornecer uma versão importante, não invente uma. Trabalhe com abstrações até que a versão seja conhecida.

## 4. Arquitetura e guidelines
- Preserve a arquitetura existente quando ela for coerente e não estiver no escopo da mudança.
- Prefira baixo acoplamento, alta coesão, responsabilidades explícitas e dependências direcionadas para abstrações quando isso trouxer benefício real.
- Evite overengineering, camadas sem função concreta, generalizações especulativas e padrões aplicados apenas pelo nome.
- Diferencie regra de negócio, orquestração de caso de uso, adaptação de dados e detalhes de infraestrutura.
- Mantenha nomes orientados ao domínio e interfaces pequenas.

## 5. Requisitos funcionais mínimos
1. Descreva o fluxo principal do início ao fim.
2. Defina entradas, validações e saídas esperadas.
3. Identifique estados de sucesso, vazio, carregamento, erro e indisponibilidade quando aplicáveis.
4. Defina persistência/efeitos colaterais e quando eles acontecem.
5. Garanta que ações repetidas, concorrentes ou parcialmente concluídas tenham comportamento conhecido.

## 6. Casos extremos e tratamento de erros
Considere pelo menos:
- dados ausentes, inválidos, duplicados ou fora dos limites;
- falhas de rede, timeout e indisponibilidade de dependência externa;
- resposta parcial ou formato inesperado;
- concorrência, repetição de ação e reentrada quando aplicável;
- perda de estado, recarregamento e recuperação;
- mensagens de erro úteis ao usuário sem vazar detalhes sensíveis.

Não use `try/catch` genérico como substituto de modelagem de falhas. Explique onde o erro deve ser tratado e onde deve apenas ser propagado.

## 7. Segurança e privacidade
- Não exponha segredos, tokens, credenciais ou dados sensíveis em código cliente, logs ou exemplos.
- Valide autorização no lado confiável da aplicação; não confunda esconder UI com controle de acesso.
- Valide entrada no limite apropriado e preserve integridade dos dados.
- Avalie riscos de injeção, XSS, CSRF, CORS, upload, armazenamento local e logs somente quando forem relevantes ao fluxo.

## 8. UX e acessibilidade (quando houver interface)
- Use semântica nativa antes de ARIA customizada.
- Garanta labels, nomes acessíveis, foco visível e operação por teclado.
- Não comunique estado apenas por cor ou ícone.
- Forneça feedback textual para erro, sucesso, carregamento e operações demoradas.
- Respeite responsividade e alvos de toque em mobile.

## 9. Performance e manutenção
- Otimize apenas depois de identificar custo real ou risco previsível.
- Evite consultas/chamadas duplicadas, listeners sem cleanup, renderizações desnecessárias e dependências redundantes.
- Centralize configuração e tokens que precisem variar.
- Prefira mudanças pequenas que possam ser revisadas e revertidas com segurança.

## 10. Testes
Proponha testes em função do risco:
- testes unitários para regras puras;
- integração para fronteiras com banco, filesystem, rede ou framework;
- contrato para integrações relevantes;
- E2E somente para fluxos críticos que precisam validar a composição completa.

Inclua casos felizes, limites, falhas e regressões do comportamento que motivou a tarefa.

## 11. Restrições
- Não altere arquivos ou módulos fora do escopo sem justificar dependência real.
- Não introduza biblioteca nova se o recurso já existe de forma adequada no projeto/plataforma.
- Não quebre contratos públicos existentes sem plano de migração.
- Não invente nomes de APIs/classes/atributos.
- Não remova testes para fazer a implementação “passar”.
- Não faça refatoração cosmética grande junto com mudança funcional arriscada.

## 12. Formato da resposta esperada
Entregue nesta ordem:
1. **Diagnóstico:** requisito, ambiente, riscos e informações confirmadas.
2. **Seções do guia usadas:** indique quais partes do guia sustentam a solução.
3. **Solução escolhida:** explique por que é a menor solução sustentável e quais alternativas foram descartadas.
4. **Plano de alteração:** arquivos/componentes afetados e ordem recomendada.
5. **Implementação:** código ou patch completo, sem pseudocódigo quando houver contexto suficiente.
6. **Testes:** casos e comandos necessários.
7. **Checklist final:** semântica, acessibilidade, segurança, manutenção, compatibilidade e regressões.
8. **Pendências reais:** somente dúvidas que impedem concluir com segurança.

## 13. Processo obrigatório da IA
1. Diagnostique antes de codificar.
2. Aponte explicitamente as seções do guia que serão utilizadas.
3. Escolha a solução mais simples que preserve comportamento, semântica, acessibilidade, segurança e manutenção.
4. Não invente APIs, classes ou capacidades da stack.
5. Implemente em passos pequenos e revisáveis.
6. Revise o resultado pelo checklist do guia e pelos critérios desta tarefa.
7. Se detectar conflito entre o pedido e uma restrição técnica, explique o conflito e ofereça a alternativa compatível.

## 14. Dados que eu fornecerei junto com este prompt
**Contexto:** informe o tipo de aplicação, stack, versões, estrutura atual, onde está o código relevante, como os dados são persistidos e quem usa o fluxo.

**Objetivo:** descreva o comportamento observável desejado, o problema atual, entradas, saídas e critérios de sucesso.

**Restrições:** diga o que não pode mudar, navegadores/OS suportados, limites de dependências, segurança, prazo, compatibilidade, padrão arquitetural e requisitos de dados.

### Exemplo de preenchimento
**Contexto:** “Aplicação Web interna em JavaScript ES Modules, Bootstrap 5.3.8 via arquivos locais, API REST existente e banco PostgreSQL no backend. O módulo atual fica em `src/modulos/atendimento` e já possui testes de integração. É usado em desktop e tablet.”

**Objetivo:** “Ao salvar uma alteração, quero validar os dados, persistir apenas uma vez, atualizar a interface sem reload e mostrar feedback de sucesso ou erro. A mudança deve ser fácil de testar e não pode afetar os demais módulos.”

**Restrições:** “Não adicionar framework novo, não alterar o contrato atual da API, manter compatibilidade com os navegadores definidos pelo projeto, preservar navegação por teclado e não expor mensagens internas do servidor ao usuário.”

```