Governança

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.

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.

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

{
  "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.

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"
  }'

{
  "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.

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.

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.

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

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.

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"

{
  "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.

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

{
  "downloadUrl": "https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...",
  "expiresAt": "2026-02-05T13:00:00Z",
  "checksum": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
}

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.

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"

{
  "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.

curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?maxRecords=10000" \
  -H "Authorization: Bearer $TOKEN"

{
  "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

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

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

Visão geral

Guias

Console

Operações

Mapeamentos de ator

Listar mapeamentos de ator

Fazer upsert de um mapeamento de ator

Obter um mapeamento de ator (desanonimizar)

Pseudonimizar

Excluir um mapeamento

Arquivos

Listar arquivos

Baixar um arquivo

Logs de auditoria

Listar logs de auditoria

Verificar a cadeia de auditoria

Obter um log de auditoria

Códigos de resposta

​Mapeamentos de ator

​Listar mapeamentos de ator

​Fazer upsert de um mapeamento de ator

​Obter um mapeamento de ator (desanonimizar)

​Pseudonimizar

​Excluir um mapeamento

​Arquivos

​Listar arquivos

​Baixar um arquivo

​Logs de auditoria

​Listar logs de auditoria

​Verificar a cadeia de auditoria

​Obter um log de auditoria

​Códigos de resposta

Mapeamentos de ator

Listar mapeamentos de ator

Fazer upsert de um mapeamento de ator

Obter um mapeamento de ator (desanonimizar)

Pseudonimizar

Excluir um mapeamento

Arquivos

Listar arquivos

Baixar um arquivo

Logs de auditoria

Listar logs de auditoria

Verificar a cadeia de auditoria

Obter um log de auditoria

Códigos de resposta