Governança

A superfície de governança do Matcher agrupa três capacidades sob /v1/governance: mapeamentos de atores (vinculam IDs de atores opacos a PII, com operações de pseudonimização e exclusão), arquivos (liste arquivos de logs de auditoria concluídos e baixe objetos de arquivos do armazenamento de objetos) e logs de auditoria (histórico imutável, encadeado por hash, com uma checagem 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. workos atualmente resolve requisições verificadas no tenant padrão configurado, então não o use para selecionar tenants.

Cada rota de governança é delimitada ao tenant do chamador. As leituras de mapeamentos de atores são divididas em dois níveis de autorização: a lista (que omite displayName e email) em comparação com a leitura de desanonimização de um único registro, para que a resolução de identidade permaneça separável do acesso de navegação.

Mapeamentos de atores

Um mapeamento de ator vincula um actorId opaco (por exemplo, user:550e8400-e29b-41d4-a716-446655440000) a PII legível (displayName, email). Fora dos ambientes local, desenvolvimento e teste, defina ACTOR_PII_ENCRYPTION_KEY com uma chave de 32 bytes codificada em base64 antes de usar mapeamentos de ator. Se ela não estiver definida, o Matcher continua em execução, mas operações de mapeamento que lidam com PII (upsert, leitura de um único registro e pseudonimização) retornam um erro de encryptor-required; os caminhos de lista e exclusão, livres de PII, não exigem um criptografador. A PII dos mapeamentos nunca é armazenada em texto aberto. As linhas da lista omitem os campos de PII do mapeamento (displayName, email) por design, mas retornam o próprio actorId. No upsert, o Matcher remove os espaços no início e no fim e rejeita IDs vazios, compostos apenas por espaços ou com mais de 255 caracteres. Ele não impõe um formato de ID opaco nem mascara o valor, então um actorId que contenha PII (como um endereço de e-mail) aparece nas linhas da lista com seu valor armazenado e é preservado pela pseudonimização; use identificadores opacos se o acesso à lista precisar permanecer livre de PII. A resposta do PUT e o GET de um único registro retornam a identidade em texto claro. Apenas o GET de um único registro é protegido pela permissão deanonymize: a resposta do PUT é protegida somente pelo acesso de escrita e retorna o registro armazenado completo, inclusive qualquer campo armazenado que o chamador não tenha enviado, então trate o acesso de escrita aos mapeamentos de atores como um acesso que revela PII. Os logs de auditoria podem manter o actorId bruto, inclusive quando ele é um endereço de e-mail.

Listar mapeamentos de atores

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 por prefixo), limit (padrão 25, limitado a 100) e cursor.

Upsert de um mapeamento de ator

Cria ou atualiza a PII de um ID de ator. PUT é idempotente — a mesma chamada cria o registro no primeiro uso e o atualiza a partir de então. Você deve fornecer ao 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 claro de um único ID de ator. Esta é a primitiva de desanonimização, por isso é protegida pela permissão mais restrita deanonymize em vez da leitura simples.

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

Pseudonimizar

Substitui displayName e email do mapeamento por [REDACTED] mantendo o registro e seu vínculo com actorId. Isso remove a PII apenas do mapeamento: os registros de auditoria imutáveis conservam o actorId bruto com o qual foram gravados (que pode ser um endereço de e-mail), então os logs de auditoria históricos e os arquivos arquivados não são redigidos. 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 permanentemente o mapeamento. 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 (com a PII removida); excluir o apaga por completo. Escolha pseudonimizar quando precisar reter o vínculo de auditoria, e excluir quando o próprio registro não deva persistir.

Arquivos

O worker de arquivamento vem desativado por padrão (ARCHIVAL_WORKER_ENABLED=false). Quando você o ativa e configura o armazenamento de arquivamento, as partições de logs de auditoria que expiram são comprimidas e movidas para o armazenamento de objetos. As rotas de recuperação de arquivos são registradas quando o armazenamento de objetos de arquivamento está disponível, independentemente de o worker estar habilitado. O endpoint de lista retorna arquivos concluídos; o de download emite URLs com tempo limitado para objetos de arquivos.

Listar arquivos

Paginados 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. Apenas os arquivos COMPLETE são listados — os arquivos em andamento e com falha nunca são expostos.

Baixar um arquivo

Retorna uma URL pré-assinada mais 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 propriedade do tenant, mas não verifica COMPLETE; ele pré-assina a archiveKey armazenada. Essa chave e seu checksum são atribuídos quando um arquivo chega a UPLOADED, antes de COMPLETE. Trate GET /v1/governance/archives/{id}/download como uma rota direta para a chave do objeto, não como prova de que o arquivamento foi concluído. Se você precisar somente de arquivos concluídos, selecione os IDs pelo endpoint de lista.

A disponibilidade do arquivo depende do backend de armazenamento compatível com S3 e da política de ciclo de vida configurados. Confirme qualquer requisito de restauração com o responsável por esse deployment de armazenamento antes de depender de uma URL de download.

Logs de auditoria

Fluxos de governança instrumentados gravam registros de auditoria imutáveis por tenant. Cada registro é encadeado em uma cadeia de hash SHA-256 que permite detectar adulterações (recordHash = SHA-256(prevHash || conteúdo canônico)), de modo que alterações inconsistentes são detectáveis. Use o endpoint de verificação abaixo para obter o veredito de integridade do lado do servidor.

Listar logs de auditoria

Paginados por cursor, com filtros detalhados.

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: o identificador de ator bruto capturado quando o registro foi gravado (um endereço de e-mail neste exemplo). Os registros de auditoria armazenam esse identificador como está; ele não precisa ser um actorId de mapeamento de atores. Quando um diff excede o limite de payload do outbox, changes carrega um envelope com 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 que cada registro inspecionado se encadeia ao anterior e corresponde ao seu hash armazenado. A verificação percorre um trecho contíguo desde o início da cadeia, limitado por maxRecords, então intact fala apenas desse trecho inspecionado. No endpoint HTTP, o maxRecords informado deve estar entre 1 e 10.000 (valores fora desse intervalo retornam 422); quando você o omite, o Matcher usa o padrão de 10.000 registros. A checagem é estritamente somente leitura: detecta adulterações, nunca altera um registro.

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

{
  "intact": true,
  "verifiedCount": 1024,
  "truncated": false
}

intact é true quando todo o trecho inspecionado está intacto; se uma quebra for encontrada, firstBrokenSeq informa o tenantSeq do primeiro registro que falha e verifiedCount informa quantos se mantiveram antes dele. truncated é true quando a cadeia contém mais registros do que o limite de inspeção maxRecords permitia.

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á conhece a entidade que está auditando.

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 (falta displayName/email ou a data é inválida)
`403`	Falta o nível de permissão necessário (por exemplo, `deanonymize` para PII de um único registro)
`404`	Mapeamento de ator, arquivo ou log de auditoria não encontrado
`422`	A validação da solicitação ou do esquema falhou (por exemplo, formato de email inválido ou um valor de consulta restrito)

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Mapeamentos de atores

Listar mapeamentos de atores

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 atores

​Listar mapeamentos de atores

​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 atores

Listar mapeamentos de atores

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