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

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

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

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.

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

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": "sha256:abc123def456..."
}

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.

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.

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.

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

curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?fromSeq=1&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 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

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)

Visão geral

Guias

Matcher UI

Servidor MCP

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