# MÓDULO FINAL 30 — hardening final de produção, superfície administrativa e revisão de autorização/segredos

## Escopo fechado nesta rodada

Esta rodada endurece o **root real** do bundle já consolidado, sem refazer a arquitetura aprovada de:

- portal como entrada oficial;
- bridge público `/nvr`;
- NVR integrado sob subpath;
- gateway local com descoberta, gravação, catálogo, playback, snapshot, export, ao vivo local e remoto mediado;
- contrato central em MySQL/MariaDB.

## Mudanças operacionais efetivas

### 1. `/platform` — endpoints operacionais agora falham fechado

O boot principal do NVR passou a proteger explicitamente:

- `/livez`
- `/readyz`
- `/metrics`

Política aplicada:

- **CIDRs confiáveis** via `OPS_ENDPOINTS_ALLOWED_CIDRS`
- **token operacional explícito** via `OPS_ENDPOINTS_TOKEN`
- header canônico: `OPS_ENDPOINTS_TOKEN_HEADER` (default `X-Operations-Token`)

Observação:

- `/healthz` permanece disponível para healthcheck público/controlado do produto;
- `/metrics` deixa rastro de boundary com `X-NVR-Ops-Boundary: operational-endpoint` quando bloqueado.

### 2. `/platform` — contingência técnica local não fica exposta por padrão

As rotas:

- `/login-tecnico`
- `/entrar-tecnico`

agora exigem explicitamente:

- **allowlist administrativa** via `AUTH_TECHNICAL_LOGIN_ALLOWED_CIDRS`, ou
- **token técnico explícito** via `AUTH_TECHNICAL_LOGIN_TOKEN`

Header canônico:

- `AUTH_TECHNICAL_LOGIN_TOKEN_HEADER` (default `X-NVR-Technical-Token`)

Quando bloqueado, o runtime responde com:

- `403` controlado;
- `X-NVR-Auth-Boundary: technical-contingency`;
- `X-NVR-Auth-Mode: local-contingency`;
- `X-NVR-Fail-Closed: true`.

### 3. `gateway` — superfície web local endurecida

A interface local do gateway agora avalia:

- **CIDRs locais confiáveis** (`LOCAL_WEB_ALLOWED_CIDRS`)
- **CIDRs administrativos** (`LOCAL_WEB_ADMIN_ALLOWED_CIDRS`)
- **allowlist de Host** (`LOCAL_WEB_TRUSTED_HOSTS`)
- **token administrativo explícito** (`LOCAL_WEB_ADMIN_TOKEN`)

Header canônico do token:

- `LOCAL_WEB_ADMIN_TOKEN_HEADER` (default `X-Gateway-Admin-Token`)

#### Comportamento por superfície

Público operacional:

- `/livez`
- `/readyz`
- `/healthz`
- `/hdmi/healthz`

Administrativo:

- `/metrics`
- `/ui/operations`

Local controlado:

- `/`
- `/ui/live`
- `/ui/recordings`
- `/hdmi`
- `/ui/hdmi`
- `/api/media/*`

Se a origem/IP/Host não satisfizer a política, o gateway responde **fail-closed** com boundary explícito.

## Política de autorização consolidada

### Responsabilidade do aplicativo

O aplicativo agora é responsável por:

- validar ticket temporário, assinatura, expiração e escopo do launch oficial;
- bloquear login comum como substituto do fluxo oficial do portal;
- restringir a contingência técnica a CIDR confiável ou token explícito;
- restringir métricas e superfícies administrativas do gateway;
- redigir segredos sensíveis em logs e trilhas auditáveis quando aplicável;
- falhar fechado com status controlado, sem substituir bloqueio por `500`.

### Responsabilidade da infraestrutura

A infraestrutura permanece responsável por:

- emissão, armazenamento e rotação de `APP_KEY`, `CENTRAL_SHARED_SECRET`, `NVR_SHARED_SECRET`, `NVR_REMOTE_SIGNING_KEY`, `OPS_ENDPOINTS_TOKEN` e `LOCAL_WEB_ADMIN_TOKEN`;
- distribuição segura desses segredos por `EnvironmentFile`, secret manager, cofre ou mecanismo equivalente;
- firewall, reverse proxy, VPN, NAT e exposição externa do gateway local;
- allowlists de rede e governança de hosts confiáveis.

## Política de rotação / governança de segredos

1. gerar novo segredo fora do bundle;
2. propagar para portal e `/platform` quando o segredo for compartilhado pelo launch oficial;
3. validar handoff, emissão de ticket e consumo no ambiente de staging/produção;
4. promover a rotação em janela controlada;
5. revogar o segredo anterior na infraestrutura;
6. auditar emissão/uso/revogação nos logs operacionais do stack.

## Variáveis novas/alinhadas

### `/platform`

- `OPS_ENDPOINTS_ALLOWED_CIDRS`
- `OPS_ENDPOINTS_TOKEN`
- `OPS_ENDPOINTS_TOKEN_HEADER`
- `AUTH_TECHNICAL_LOGIN_ALLOWED_CIDRS`
- `AUTH_TECHNICAL_LOGIN_TOKEN`
- `AUTH_TECHNICAL_LOGIN_TOKEN_HEADER`
- `SECRETS_ROTATION_OWNER`
- `SECRETS_ROTATION_CHANNEL`

### `gateway`

- `LOCAL_WEB_ALLOWED_CIDRS`
- `LOCAL_WEB_ADMIN_ALLOWED_CIDRS`
- `LOCAL_WEB_TRUSTED_HOSTS`
- `LOCAL_WEB_ADMIN_TOKEN`
- `LOCAL_WEB_ADMIN_TOKEN_HEADER`

## Regressão adicionada

A regressão do bundle agora cobre:

- bloqueio da contingência técnica para IP público sem token;
- liberação controlada da contingência técnica com token explícito;
- bloqueio de `/metrics` fora da allowlist operacional;
- liberação controlada de `/metrics` com token explícito;
- verificação da política do gateway para LAN, token administrativo e trusted host.
