# Interface: eventos de auditoria

Taxonomia e schema dos eventos de auditoria, para quem vai construir um consumidor (SIEM,
dashboard). Implementação: [`src/emcp_bus/audit/models.py`](../../src/emcp_bus/audit/models.py),
[`audit/events.py`](../../src/emcp_bus/audit/events.py),
[`audit/sink.py`](../../src/emcp_bus/audit/sink.py),
[`audit/correlation.py`](../../src/emcp_bus/audit/correlation.py). Ver
[`AS-BUILT.md`](../AS-BUILT.md#auditoria-correlação-e-observabilidade-ep-08).

## Sink

`JSONLFileAuditSink` grava um objeto JSON por linha, append-only, em `EMCP_AUDIT_LOG_PATH`
(padrão `/tmp/emcp-audit.jsonl`). Um consumidor de produção substituiria isso por um sink
durável (Postgres, fila) — ver `../Production-Recommendations.md`; o schema do `EventEnvelope`
abaixo não mudaria.

## `EventEnvelope`

```json
{
  "event_id": "3f9a...",
  "event_type": "tool_call_denied",
  "category": "grl",
  "timestamp": "2026-09-14T12:00:00Z",
  "client_id": "sales-read-agent",
  "profile_name": "Sales.Read",
  "tool": "finance.payment.execute",
  "reason_code": "NOT_IN_ENTITLEMENT",
  "decision_id": "...",
  "policy_decision_id": "...",
  "entitlement_version": "...",
  "policy_version": "a1b2c3d4e5f6",
  "mcp_request_id": "...",
  "trace_id": "...",
  "payload": {}
}
```

Campos de correlação (`decision_id`, `policy_decision_id`, `entitlement_version`,
`policy_version`, `mcp_request_id`, `trace_id`) são de primeira classe, nunca escondidos dentro
de `payload` — um consumidor pode fazer join entre eventos e entre eventos e spans OTel sem
parsear `payload`.

## Taxonomia (`category`)

Adotada da referência Agent Platform OCI (`docs/adr/ADR-022-referencia-hoshikawa-agent-platform-oci.md`)
em vez de uma taxonomia própria:

| Categoria | Significado | Exemplos de `event_type` |
|---|---|---|
| `ic` | Interação de Cliente / negócio-jornada — a chamada progrediu normalmente | `client_authenticated`, `tool_call_allowed`, `agent_turn_completed`, `nba_recalculated` |
| `noc` | Operacional/erro — falha de disponibilidade, não uma decisão de política | `pdp_unavailable`, `backend_credential_unavailable` |
| `grl` | Guardrail/governança — uma fronteira de entitlement/política foi aplicada ou testada | `tool_call_denied`, `tools_list_filtered`, `tool_call_require_approval`, `approval_granted`, `bypass_attempt_detected`, `journey_ended_after_denial` |

Cada `event_type` fixa sua própria categoria na fábrica que o cria (`audit/events.py`) — nunca é
uma decisão do call site.

## Sanitização (nunca opcional)

Qualquer chave de `payload`, em qualquer nível de aninhamento, cujo nome (lowercased) contenha
`token`, `secret`, `password`, `authorization` ou `credential` tem seu valor substituído por
`sha256:<hex>` — nunca um valor real de segredo chega a um sink. Isso roda em
`EventEnvelope.model_post_init`, então vale para toda via de construção, inclusive
desserialização a partir de um sink existente.

## `event_type` disponíveis

| `event_type` | Categoria | Emitido quando |
|---|---|---|
| `client_authenticated` | ic | Um `tools/list` com token válido resolveu um client conhecido. |
| `tools_list_filtered` | grl | Um `tools/list` retornou (inclui contagem `allowed`/`total`). |
| `tool_call_allowed` | ic | Um `tools/call` foi executado com sucesso. |
| `tool_call_denied` | grl | Qualquer negação de `tools/call` (com `reason_code`). |
| `tool_call_require_approval` | grl | Uma tentativa gerou/encontrou um `ApprovalRequest` pendente. |
| `approval_granted` | grl | Um approver concedeu uma aprovação (`ApprovalService.grant`). |
| `pdp_unavailable` | noc | O OPA não respondeu a uma consulta de `tools/call`. |
| `backend_credential_unavailable` | noc | A credencial de saída para um backend não pôde ser obtida. |
| `bypass_attempt_detected` | grl | Uma requisição alcançou um domain server sem a credencial de saída do Gateway (EP-05-T07). |
| `nba_recalculated` | ic | O Orchestrator recalculou a NBA após um DENY do Gateway (nunca reexecuta a ação negada). |
| `agent_turn_completed` | ic | Um turno do agente de exemplo terminou — inclui `tools_attempted`/`tools_denied` (uma tool negada aqui é o guardrail funcionando, não um bug). |
| `journey_ended_after_denial` | grl | Nenhuma offering sobreviveu a um DENY — a jornada termina, sem tentativa direta ao Fabric. |

## Construindo um consumidor

Um SIEM/dashboard deveria: ler o JSONL (ou o sink de produção equivalente), indexar por
`decision_id`/`mcp_request_id`/`trace_id` para reconstrução ponta a ponta, e tratar qualquer
evento `category: "grl"` como um sinal de guardrail (não necessariamente um incidente — negação
correta é o sistema funcionando), e `category: "noc"` como sinal de disponibilidade.