> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Governança

> Gerencie mapeamentos de PII de ator, liste arquivos de log de auditoria e baixe objetos de arquivo, e reverifique a cadeia de hash de auditoria à prova de adulteração do Matcher.

A superfície de governança do Matcher agrupa três capacidades em `/v1/governance`:

* **Mapeamentos de ator**: vincula IDs de ator opacos a PII, com operações de pseudonimização e exclusão.
* **Arquivos**: lista arquivos de log de auditoria concluídos e baixa objetos de arquivo do armazenamento de objetos.
* **Logs de auditoria**: histórico imutável e encadeado por hash, com verificação de integridade somente leitura.

Com `AUTH_PROVIDER=plugin-auth` no modo multi-tenant, a identidade do tenant vem do JWT. O Matcher rejeita a inicialização quando `MULTI_TENANT_ENABLED=true` e `PLUGIN_AUTH_ENABLED=false`.

<Note>Toda rota de governança fica restrita ao tenant do chamador. As leituras de mapeamento de ator têm dois níveis de autorização: a listagem, que omite `displayName` e `email`, e a leitura de desanonimização de registro único. Essa separação mantém a resolução de identidade apartada do acesso de navegação.</Note>

## Mapeamentos de ator

***

Um mapeamento de ator vincula um `actorId` opaco (por exemplo, `user:550e8400-e29b-41d4-a716-446655440000`) a PII legível por humanos (`displayName`, `email`). Fora dos ambientes local, de desenvolvimento e de teste, defina `ACTOR_PII_ENCRYPTION_KEY` como uma chave de 32 bytes codificada em base64 antes de usar mapeamentos de ator. Se você deixar essa variável sem definição, o Matcher continua em execução. As operações de mapeamento que carregam PII (upsert, leitura de registro único e pseudonimização) então retornam um erro indicando que um criptografador é necessário. Os caminhos de listagem e exclusão, que não carregam PII, não precisam de criptografador. O Matcher nunca armazena PII de mapeamento em texto simples.

As linhas da listagem omitem os campos de PII do mapeamento (`displayName`, `email`) **por design**, mas retornam o próprio `actorId`. No upsert, o Matcher remove espaços em branco no início e no fim e rejeita IDs vazios, IDs compostos apenas por espaços em branco e IDs com mais de 255 caracteres. O Matcher não impõe um formato de ID opaco e não mascara o valor. Um `actorId` que em si contém PII, como um endereço de e-mail, aparece nas linhas da listagem com seu valor armazenado. A pseudonimização preserva esse valor. Use identificadores opacos se o acesso à listagem precisar ficar livre de PII.

A resposta do `PUT` e o `GET` de registro único retornam a identidade em texto simples. A permissão `deanonymize` controla apenas o `GET` de registro único. Apenas o acesso de escrita controla a resposta do `PUT`, que ecoa o registro armazenado completo, incluindo qualquer campo armazenado que o chamador não enviou. Trate o acesso de escrita a mapeamento de ator como revelador de PII. Os logs de auditoria podem reter o `actorId` bruto, que pode ser um endereço de e-mail.

### Listar mapeamentos de ator

Linhas paginadas por cursor que omitem `displayName` e `email`. Filtre por um prefixo de ID de ator.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings?actorId=user:&limit=25" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "actorId": "user:550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "limit": 25
}
```

Parâmetros de consulta: `actorId` (filtro de prefixo), `limit` (padrão 25, limitado a 100) e `cursor`.

### Fazer upsert de um mapeamento de ator

Cria ou atualiza a PII de um ID de ator. O `PUT` é idempotente. A mesma chamada cria o registro no primeiro uso e o atualiza depois disso. Informe pelo menos um entre `displayName` ou `email`.

```bash theme={null}
curl -X PUT "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "John Doe",
    "email": "john.doe@example.com"
  }'
```

```json theme={null}
{
  "actorId": "user:550e8400-e29b-41d4-a716-446655440000",
  "displayName": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}
```

### Obter um mapeamento de ator (desanonimizar)

Retorna a PII em texto simples para um único ID de ator. Esta **é** a primitiva de desanonimização, por isso a permissão mais restrita `deanonymize` a controla, em vez da leitura simples.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
```

### Pseudonimizar

Substitui o `displayName` e o `email` do mapeamento por `[REDACTED]`, preservando o registro e seu vínculo com o `actorId`. Isso remove a PII apenas do mapeamento. Os registros de auditoria imutáveis mantêm o `actorId` bruto da gravação original, e esse valor pode em si ser um endereço de e-mail. Os logs de auditoria históricos e os arquivos arquivados mantêm seus valores originais. Responde `204 No Content`.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}/pseudonymize" \
  -H "Authorization: Bearer $TOKEN"
```

### Excluir um mapeamento

Remove o mapeamento permanentemente. Responde `204 No Content`.

```bash theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
```

<Note>Pseudonimizar mantém o registro e remove sua PII. Excluir remove o registro por completo. Escolha pseudonimizar quando precisar reter o vínculo de auditoria, e excluir quando o próprio registro não deve persistir.</Note>

## Arquivos

***

O worker de arquivamento fica desligado por padrão (`ARCHIVAL_WORKER_ENABLED=false`). Quando você o habilita e configura o armazenamento de arquivamento, o worker comprime partições de log de auditoria envelhecidas e as move para o armazenamento de objetos. O Matcher registra as rotas de recuperação de arquivo sempre que o armazenamento de objetos de arquivamento está disponível, mesmo quando o worker fica desligado. O endpoint de listagem retorna arquivos concluídos. O endpoint de download emite URLs de duração limitada para objetos de arquivo.

### Listar arquivos

Paginado por offset. Filtre por intervalo de datas.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/archives?from=2024-01-01&to=2024-03-31&limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "partitionName": "audit_logs_2024_q1",
      "dateRangeStart": "2024-01-01T00:00:00Z",
      "dateRangeEnd": "2024-03-31T23:59:59Z",
      "rowCount": 150000,
      "compressedSizeBytes": 10485760,
      "storageClass": "GLACIER",
      "checksum": "sha256:abc123def456...",
      "status": "COMPLETE",
      "archivedAt": "2024-04-01T02:30:00Z"
    }
  ],
  "limit": 20,
  "hasMore": true
}
```

Parâmetros de consulta: `from`, `to` (`YYYY-MM-DD` ou RFC 3339), `limit` (1–200, padrão 20) e `offset`. O endpoint lista apenas arquivos `COMPLETE` e nunca exibe arquivos em andamento ou com falha.

### Baixar um arquivo

Retorna uma URL pré-assinada e o checksum para verificação de integridade.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/archives/{id}/download" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "downloadUrl": "https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...",
  "expiresAt": "2026-02-05T13:00:00Z",
  "checksum": "sha256:abc123def456..."
}
```

<Warning>O handler de download confirma a posse do tenant, mas não verifica `COMPLETE`. Ele pré-assina o `archiveKey` armazenado. Um arquivo recebe essa chave e seu checksum quando atinge `UPLOADED`, antes de `COMPLETE`. Trate `GET /v1/governance/archives/{id}/download` como um caminho direto de chave de objeto, não como prova de que o arquivamento foi concluído. Se você precisar apenas de arquivos concluídos, selecione os IDs a partir do endpoint de listagem.</Warning>

<Warning>A disponibilidade do arquivo depende do backend de armazenamento compatível com S3 configurado e da política de ciclo de vida. Confirme qualquer necessidade de restauração com o responsável por esse deploy de armazenamento antes de confiar em uma URL de download.</Warning>

## Logs de auditoria

***

Workflows de governança instrumentados gravam registros de auditoria imutáveis por tenant. O Matcher vincula cada registro a uma cadeia de hash SHA-256 à prova de adulteração (`recordHash` = `SHA-256(prevHash || canonical content)`), de modo que alterações inconsistentes ficam detectáveis. Use o endpoint de verificação abaixo para obter o veredito de integridade do lado do servidor.

### Listar logs de auditoria

Paginado por cursor, com filtros avançados.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs?actor=user@example.com&action=CREATE&entity_type=context&date_from=2025-01-01&date_to=2025-01-31&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "550e8400-e29b-41d4-a716-446655440001",
      "entityType": "reconciliation_context",
      "entityId": "550e8400-e29b-41d4-a716-446655440002",
      "action": "CREATE",
      "actorId": "user@example.com",
      "changes": { },
      "truncated": false,
      "originalSize": 0,
      "createdAt": "2025-01-15T10:30:00Z",
      "tenantSeq": 1,
      "recordHash": "dd3f8a09dda3a8fdcd1e5c54ef76a9168bbabbfd92ad1dd736400d03a3f8a585",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "hashVersion": 1
    }
  ],
  "limit": 20,
  "hasMore": false
}
```

Parâmetros de consulta: `actor`, `action`, `entity_type`, `date_from`, `date_to` (`YYYY-MM-DD` ou RFC 3339), `limit` (1–200, padrão 20) e `cursor`.

`actor` filtra pelo valor `actorId` do registro. Esse valor é o identificador de ator bruto da gravação original, um endereço de e-mail neste exemplo. Os registros de auditoria armazenam o identificador como está. Ele não precisa corresponder a um `actorId` de mapeamento de ator.

Quando um diff excede o limite de payload do outbox, `changes` carrega um envelope de marcador de truncamento em vez do diff completo, e `truncated` passa a `true`, com `originalSize` informando o tamanho em bytes anterior ao truncamento.

### Verificar a cadeia de auditoria

Reverifica se cada registro inspecionado se vincula ao anterior e corresponde ao seu hash armazenado. A verificação percorre um intervalo contíguo limitado por `maxRecords`, de modo que `intact` apenas vale para esse intervalo inspecionado. No endpoint HTTP, um `maxRecords` informado deve estar no intervalo de 1 a 10.000, e um valor fora dele retorna `422`. Quando você o omite, o Matcher usa o padrão de 10.000 registros.

`fromSeq` é um piso de verificação opcional (mínimo 1). Omita-o para começar na sequência 1. Um piso acima de 1 confia no `prevHash` armazenado daquele registro, de modo que a execução não cobre adulterações abaixo do piso. A verificação permanece estritamente somente leitura. Ela detecta adulterações e nunca altera um registro.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?fromSeq=1&maxRecords=10000" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "intact": true,
  "fromSeq": 1,
  "verifiedCount": 1024,
  "truncated": false
}
```

O campo `intact` é `true` quando todo o intervalo permanece sem interrupção. Quando a verificação encontra uma quebra, `firstBrokenSeq` informa o `tenantSeq` do primeiro registro com falha, e `verifiedCount` informa quantos registros se mantiveram íntegros antes dele. O campo `truncated` é `true` quando a cadeia tem mais registros do que o limite de inspeção `maxRecords` permitiu. A resposta ecoa o `fromSeq` efetivo. Após uma execução truncada, retome com `fromSeq = fromSeq + verifiedCount` para inspecionar o próximo intervalo.

### Obter um log de auditoria

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

<Note>Você também pode listar o histórico de uma entidade diretamente com `GET /v1/governance/entities/{entityType}/{entityId}/audit-logs` (paginado por cursor), o que é conveniente quando você já sabe qual entidade auditar.</Note>

## Códigos de resposta

***

| Status | Significado                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Dados de mapeamento, arquivo ou auditoria retornados                                                                       |
| `204`  | Mapeamento de ator pseudonimizado ou excluído                                                                              |
| `400`  | Entrada inválida no nível da aplicação (displayName/email ausente ou data inválida)                                        |
| `403`  | Nível de permissão exigido ausente (por exemplo, `deanonymize` para PII de registro único)                                 |
| `404`  | Mapeamento de ator, arquivo ou log de auditoria não encontrado                                                             |
| `422`  | Falha na validação de requisição/schema (por exemplo, formato de e-mail inválido ou valor de consulta fora das restrições) |