# Cofre para IA

> Piloto sintético publicado com API autenticada por Keycloak. Não envie credenciais reais para este domínio ou repositório.

O Cofre para IA permite que agentes peçam operações autorizadas a provedores sem receber o valor da credencial.

## Documentos

- [Arquitetura](docs/arquitetura.md): fronteira entre cliente, API, broker e OpenBao.
- [Contrato de API](/openapi.yaml): catálogo, invocação e recibo do piloto sintético.
- [Painel do piloto](docs/painel-piloto.md): login humano, execução e limites.

## Limites para agentes

- Use apenas a API publicada e identidades emitidas para sua organização.
- Descubra capacidades no catálogo. Execute somente operações listadas e autorizadas.
- IDs de conexão e de operação não concedem acesso por si mesmos.
- Nunca peça, imprima ou registre o valor de uma credencial.
- Não tente usar o serviço como proxy HTTP livre ou executor de comandos.
- Confirme efeitos e falhas pelo estado e pelo recibo da operação.

## Uso por um cliente de IA

1. Obtenha uma identidade de serviço e um grant para sua organização com o operador. O cliente autentica no Keycloak por OAuth 2.0 `client_credentials` com `private_key_jwt`. A chave privada fica no backend do cliente, fora do prompt e do navegador.
2. Com o bearer de curta duração, consulte `GET /v1/operations` e `GET /v1/connections`. O catálogo informa o que a identidade pode executar.
3. Para este piloto, envie `POST /v1/invocations` com `connectionId`, `operationId: list-records`, `purpose: test`, `input: {"limit": 1}` e um header `Idempotency-Key` único que siga o contrato OpenAPI.
4. Confira o `status` da resposta. Consulte `GET /v1/invocations/{id}` para o recibo. Trate `denied`, `failed` e `uncertain` como resultados diferentes; não repita automaticamente uma invocação incerta.

O contrato é HTTP e OpenAPI, sem dependência de um modelo de IA específico. O piloto executa somente a operação sintética `list-records`; ainda não há adaptador de provedor real nem cadastro público de credenciais.