# Baseline de autenticacao, autorizacao e hardening

## Objetivo

Definir o baseline minimo de seguranca para o ecossistema separado em `cms/`, `api/` e `front-end/`, cobrindo sessao, papeis, autorizacao, CSRF, validacao, escaping, headers, rate limiting e auditoria.

## Fronteiras do ecossistema

- `cms/` e `cms/install/` sao superficies privadas e nao devem ser descobriveis publicamente.
- `api/` e a fronteira de dados entre CMS e `front-end/`, com contratos explicitamente versionados em `/api/v1`.
- `front-end/` e a unica superficie publica indexavel e deve tratar toda resposta da API como nao confiavel ate validacao e escaping.

## Sessao e autenticacao

### CMS administrativo

- Autenticacao stateful com sessao de servidor e cookie exclusivo do CMS.
- Cookie de sessao com `Secure`, `HttpOnly`, `SameSite=Strict`, `session.use_strict_mode=1` e rotacao de ID no login, elevacao de privilegio e reset de senha.
- Timeout absoluto de 8 horas e timeout por inatividade de 30 minutos.
- Logout deve invalidar sessao no servidor e expirar cookie no cliente.
- Senhas devem usar `password_hash()` com `PASSWORD_ARGON2ID` quando disponivel; fallback aceito apenas para `PASSWORD_BCRYPT`.
- Fluxos sensiveis exigem reautenticacao recente: alteracao de senha, troca de email, gerenciamento de papeis e exclusao logica/definitiva.

### API publica

- Endpoints publicos `GET` permanecem anonimos por padrao.
- Endpoints mutaveis futuros (`POST`, `PUT`, `PATCH`, `DELETE`) exigem autenticacao explicita; nao podem herdar sessao administrativa do CMS.
- Quando houver integracoes servidor-servidor, usar credenciais separadas por consumidor, com escopo e revogacao individual.
- Tokens ou credenciais de integracao devem expirar, ser rotacionaveis e nunca aparecer em HTML, bundle do frontend ou logs.

## Papeis e autorizacao

- RBAC minimo no CMS com os papeis `super_admin`, `editor` e `author`.
- `super_admin`: gestao de usuarios, papeis, configuracao global, cache, auditoria e operacoes destrutivas.
- `editor`: publica e despublica conteudo, gerencia taxonomias, media e menus, sem gerenciar usuarios ou configuracoes secretas.
- `author`: cria e edita somente o proprio conteudo em rascunho, sem publicar nem alterar configuracoes globais.
- Toda autorizacao deve ser deny-by-default; a ausencia de regra nega acesso.
- O backend deve checar permissao por acao de negocio, nao apenas por rota.
- Todo recurso mutavel precisa registrar ownership quando aplicavel para permitir controles do tipo "somente o autor".

## CSRF

- Toda operacao stateful do CMS protegida por token CSRF sincronizado por sessao.
- Tokens devem ser unicos por sessao, enviados fora de cookies e validados antes de qualquer mutacao.
- `SameSite=Strict` reduz superficie, mas nao substitui validacao de CSRF.
- Endpoints autenticados por token bearer nao usam CSRF; nesses casos o controle obrigatorio e autenticacao forte + CORS restrito.

## Validacao e escaping

- Toda entrada externa deve ser validada no boundary da camada HTTP antes de chegar a controller, query builder ou renderer.
- Validacao minima: tipo, obrigatoriedade, tamanho maximo, formato, allowlist de valores e normalizacao de encoding.
- Queries ao banco devem usar statements parametrizados; concatenacao de SQL com input do usuario e proibida.
- Saidas HTML do CMS e do frontend devem escapar por contexto: texto, atributo, URL e JSON embutido.
- Strings vindas do CMS para o frontend nao podem ser inseridas via `innerHTML` sem sanitizacao explicita.
- Mensagens de erro para clientes devem ser genericas; detalhes internos ficam apenas em logs/auditoria.

## Headers de seguranca

### CMS e instalador

- Manter `X-Robots-Tag: noindex, nofollow, noarchive, nosnippet`.
- Manter `Cache-Control: no-store`, `Pragma: no-cache`, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff` e `Referrer-Policy: no-referrer`.
- Adicionar `Content-Security-Policy` minima para admin com `default-src 'self'`, negando `frame-ancestors` e restringindo `script-src`, `style-src`, `img-src` e `connect-src` ao necessario.
- Apos a instalacao inicial, invalidar a sessao temporaria do instalador e persistir um lock operacional para impedir reexecucao acidental do setup.
- O caminho administrativo configurado continua privado; somente a rota exata reservada deve responder fora de `404`, sempre com os mesmos headers privados.

### API

- Responder com `Content-Type: application/json; charset=utf-8`.
- Adicionar `X-Content-Type-Options: nosniff`.
- Adicionar `Referrer-Policy: no-referrer`.
- Adicionar `Cache-Control` coerente por rota: publico para leitura cacheavel, `no-store` para qualquer resposta autenticada ou sensivel.
- CORS deve ser allowlist por origem, metodos e headers; `*` nao e permitido se houver autenticacao.

### Frontend publico

- Definir `Content-Security-Policy` compativel com assets realmente usados.
- Definir `Referrer-Policy: strict-origin-when-cross-origin`.
- Definir `Permissions-Policy` negando recursos nao utilizados.

## Rate limiting e abuso

- Rate limiting deve existir no edge da API antes de controller.
- Baseline inicial:
  - leitura publica: 120 req/min por IP;
  - busca e filtros pesados: 30 req/min por IP;
  - login CMS: 5 tentativas/15 min por IP e por identificador;
  - operacoes mutaveis autenticadas: 60 req/min por sessao ou principal autenticado.
- Respostas limitadas retornam `429 Too Many Requests` com `Retry-After`.
- O contador deve considerar IP real trusted proxy-aware e chave secundaria por usuario/sessao quando houver autenticacao.
- Eventos repetidos de abuso entram na trilha de auditoria.

## Observabilidade operacional da API

- Toda requisicao da API deve carregar um `request id` unico; se o edge enviar `X-Request-Id`, a API o reutiliza, caso contrario gera um valor proprio.
- O `request id` deve retornar ao cliente em header e acompanhar logs tecnicos, auditoria, traces futuros e respostas de erro para correlacao rapida.
- Logs da API devem ser estruturados e no minimo registrar `timestamp UTC`, rota, metodo, status HTTP, latencia, IP resolvido, user agent, cache hit/miss, decisao de CORS e decisao de rate limiting.
- Eventos de falha operacional devem distinguir erro de aplicacao, timeout de dependencia, falha de serializacao e rejeicao por middleware para permitir alertas por classe.
- A API deve expor pelo menos um endpoint de `health` para liveness e um de `readiness` verificando dependencia critica de leitura, especialmente conexao com MySQL e storage de cache quando existir.
- O baseline minimo de metricas inclui volume por rota, latencia por percentil, taxa de erro `5xx`, taxa de `429`, disponibilidade dos health checks e saturacao de dependencias externas.
- Respostas `5xx` nao devem vazar stack trace ou segredos, mas precisam carregar `request id` para suporte e investigacao.
- Alertas iniciais devem cobrir aumento sustentado de `5xx`, explosao de `429`, degradacao de latencia e indisponibilidade de readiness.

## Trilha de auditoria

- A auditoria precisa ser append-only no nivel logico e imutavel para perfis nao administrativos.
- O detalhamento dos eventos, estados editoriais e governanca operacional do CMS fica normatizado em [docs/editorial-workflow.md](./editorial-workflow.md).
- Eventos obrigatorios:
  - login bem-sucedido e falho;
  - logout;
  - reset e troca de senha;
  - criacao, alteracao e revogacao de usuario/papel;
  - publicacao, despublicacao e exclusao de conteudo;
  - alteracao de configuracao, menus e taxonomias;
  - throttling, negacao por autorizacao e falhas de CSRF.
- Cada evento deve registrar timestamp UTC, actor, alvo, acao, resultado, IP, user agent e correlation/request id.
- Logs de auditoria nao substituem logs tecnicos; ambos precisam coexistir.

## Lacunas atuais observadas no repositorio

- `cms/install/index.php` e `cms/core/install/Installer.php` agora cobrem o bootstrap privado com CSRF, checks de ambiente, provisionamento MySQL e seed do primeiro `super_admin`.
- `cms/core/auth/Session.php` ja aplica parte do baseline de cookie, rotacao e expiracao de sessao.
- `api/src/middleware/Auth.php`, `api/src/middleware/RateLimit.php` e `api/src/middleware/CORS.php` ainda estao como stubs e nao implementam os controles descritos.
- A API ainda nao padroniza `request id`, health/readiness nem emissao de metricas/logs estruturados no boundary HTTP.
- Nao ha camada dedicada de autorizacao por papel/ownership nem trilha de auditoria persistente.
- O bootstrap privado do CMS ja envia `noindex`, `DENY`, `nosniff` e `no-store`, o que esta alinhado com o baseline da superficie administrativa.

## Ordem recomendada de implementacao

1. Consolidar middlewares compartilhados da API para `CORS`, headers e rate limiting.
2. Padronizar `request id`, logs estruturados, health/readiness e metricas minimas no boundary da API.
3. Introduzir autenticacao administrativa real e modelo de RBAC no `cms/`.
4. Adicionar CSRF e reautenticacao recente nos fluxos mutaveis do CMS.
5. Padronizar validacao de request e escaping por contexto nas saidas.
6. Criar armazenamento de auditoria e instrumentar eventos criticos.