# Arquitetura do produto

O serviço separa quem pede uma operação de quem pode ler a credencial.

```mermaid
flowchart LR
  A[Agente ou app] -->|pede operação| API[API do produto]
  API -->|autoriza| B[Broker]
  B -->|lê path exato| V[OpenBao]
  B -->|executa adapter| P[Provedor]
  B -->|resposta filtrada| API
  API -->|resultado permitido| A
```

## Domínios

- **Controle:** organizações, usuários, identidades de serviço, conexões, operações, grants e auditoria.
- **Custódia:** OpenBao sob conta e host independentes, sem acesso administrativo pelo agente ou pela Central.
- **Execução:** broker sem endpoint de comando ou URL arbitrária. Cada adaptador é uma operação de produto versionada.
- **Integração:** API pública comum. A RCOUTO é um cliente comum e a Central é um consumidor autorizado.

## Invariantes de operação

1. A autenticação fixa a organização antes da consulta de conexão e credencial.
2. O grant vincula identidade, capacidade, recurso, versão e expiração.
3. O broker só lê a referência exata do segredo após autorização.
4. O adaptador trata timeouts, idempotência, escopo do provedor e saída permitida.
5. Logs, traces, analytics, respostas e erros não incluem material secreto.
6. O resultado guarda evidência e estado. Uma falha ambígua não vira sucesso.
7. Revogação local, revogação no provedor e destruição no OpenBao são operações distintas.

## Aceite antes do primeiro segredo real

- Conta administrativa e recuperação fora do alcance dos agentes.
- TLS, autenticação de serviço, políticas de menor privilégio e auditoria ativos.
- Backup cifrado fora do host e restauração ensaiada sem Bitwarden.
- Teste negativo entre duas organizações e contra operações sem grant.
- Teste de vazamento de segredo em resposta, log, erro e transcript.
- URL remota e operação real somente leitura validadas externamente.