> ## 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 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 append-only e encadeado por hash, com verificação de integridade somente leitura.

> [!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.

## 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`). O Matcher criptografa `displayName` e `email` antes de armazená-los e nunca os armazena 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.

O `GET` de registro único retorna a identidade em texto simples e exige a permissão `deanonymize`. 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.

## Arquivos

***

Quando a Lerian habilita o arquivamento de auditoria no seu ambiente, o Matcher exporta para o armazenamento de objetos cada partição mensal de log de auditoria mais antiga que o período de retenção definido pela Lerian. Ele verifica a exportação e depois remove a partição do banco.

### 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_01",
      "dateRangeStart": "2024-01-01T00:00:00Z",
      "dateRangeEnd": "2024-02-01T00:00:00Z",
      "rowCount": 150000,
      "compressedSizeBytes": 10485760,
      "storageClass": "GLACIER",
      "checksum": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
      "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 mostra arquivos em andamento ou com falha. `checksum` é o SHA-256 em hexadecimal do conteúdo JSONL descomprimido, então descomprima um arquivo baixado antes de calcular o hash.

### 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": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
}
```

> [!NOTE]
>
> Para baixar apenas arquivos concluídos, pegue os IDs de arquivo do endpoint de listagem, que retorna apenas arquivos `COMPLETE`.

## Logs de auditoria

***

O Matcher registra as mudanças de configuração e as resoluções de exceções como registros de auditoria append-only por tenant. Ele vincula cada registro a uma cadeia de hash SHA-256 (`recordHash` = `SHA-256(prevHash || canonical content)`). Use o endpoint de verificação abaixo para obter o veredito de integridade.

### 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": "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 é grande demais para ser mantido inteiro, `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 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.

Por padrão, a verificação começa na menor sequência armazenada. Para começar em um registro posterior, envie o `fromSeq` opcional: o primeiro `tenantSeq` a inspecionar, um inteiro igual ou maior que 1. Quando o primeiro registro que a verificação lê não é a sequência 1, a verificação confia no vínculo armazenado desse registro. Ela não verifica os registros anteriores a ele. A verificação permanece estritamente somente leitura.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?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 sempre traz `fromSeq`, o `tenantSeq` em que a verificação começou.

### 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.

## 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) |
| `503` | O armazenamento de arquivos está indisponível |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.