Gobernanza - Lerian

La superficie de gobernanza de Matcher agrupa las tres capacidades orientadas al cumplimiento bajo /v1/governance: mapeos de actores (vinculan IDs de actores opacos con PII, con pseudonimización/borrado GDPR), archivos (descarga archivos de logs de auditoría completados desde almacenamiento en frío) y logs de auditoría (historial inmutable, encadenado por hash, que puedes volver a verificar de forma independiente). El inquilino siempre se resuelve desde el JWT — nunca desde una ruta o un cuerpo.

Cada ruta de gobernanza está delimitada al inquilino del llamante. Las lecturas de mapeos de actores se dividen en dos niveles de autorización: la lista sin PII frente a la lectura de des-anonimización de un solo registro, para que la resolución de identidad se mantenga separable del acceso de navegación.

Mapeos de actores

Un mapeo de actor vincula un actorId opaco (por ejemplo user:550e8400-e29b-41d4-a716-446655440000) con PII legible (displayName, email). Las filas de la lista son sin PII por diseño — solo el GET de un solo registro devuelve la identidad en texto claro.

Listar mapeos de actores

Filas paginadas por cursor, sin PII. Filtra por un prefijo de ID de actor.

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,
  "nextCursor": "",
  "hasMore": false
}

Parámetros de consulta: actorId (filtro por prefijo), limit (predeterminado 25, con tope de 100) y cursor.

Upsert de un mapeo de actor

Crea o actualiza la PII de un ID de actor. PUT es idempotente — la misma llamada crea el registro en el primer uso y lo actualiza a partir de entonces. Debes proporcionar al menos uno de displayName o 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"
}

Obtener un mapeo de actor (des-anonimizar)

Devuelve la PII en texto claro de un solo ID de actor. Esta es la primitiva de des-anonimización, por lo que está protegida por el permiso más restringido deanonymize en lugar de la lectura simple.

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

Reemplaza displayName y email con [REDACTED] mientras conserva el registro y su vínculo con actorId — la pista de auditoría permanece intacta pero la PII desaparece. Responde 204 No Content.

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

Eliminar (derecho al olvido)

Elimina permanentemente el mapeo para el derecho al olvido de GDPR. Responde 204 No Content.

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

Pseudonimizar mantiene el registro (con la PII depurada); eliminar lo borra por completo. Elige pseudonimizar cuando debas conservar el vínculo de auditoría, y eliminar cuando el propio registro no deba persistir.

Archivos

Cuando las particiones de logs de auditoría caducan, se comprimen y se mueven a almacenamiento de objetos. Los endpoints de archivos listan los archivos completados y emiten URLs de descarga con tiempo limitado.

Listar archivos

Paginados por offset. Filtra por rango de fechas.

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 o RFC 3339), limit (1–200, predeterminado 20) y offset. Solo se listan los archivos COMPLETE — los archivos en curso y fallidos nunca se exponen.

Descargar un archivo

Devuelve una URL prefirmada más el checksum para la verificación de integridad.

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

Los archivos en las clases de almacenamiento GLACIER o DEEP_ARCHIVE requieren una restauración antes de que la URL de descarga se resuelva. STANDARD, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING y GLACIER_IR son legibles de inmediato.

Logs de auditoría

Todo cambio relevante para la gobernanza se escribe en un log de auditoría inmutable, por inquilino. Cada registro se enlaza en una cadena de hash SHA-256 a prueba de manipulaciones (recordHash = SHA-256(prevHash || contenido canónico)), de modo que un cliente puede volver a verificar la integridad de forma independiente.

Listar logs de auditoría

Paginados por cursor, con filtros detallados.

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": 42,
      "recordHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "hashVersion": 1
    }
  ]
}

Parámetros de consulta: actor, action, entity_type, date_from, date_to (YYYY-MM-DD o RFC 3339), limit (1–200, predeterminado 20) y cursor. Cuando un diff excede el tope de payload del outbox, changes lleva un envoltorio con marcador de truncamiento en lugar del diff completo, y truncated pasa a true, con originalSize informando el tamaño en bytes previo al truncamiento.

Verificar la cadena de auditoría

Vuelve a verificar que cada registro inspeccionado se enlaza con el anterior y coincide con su hash almacenado. Es estrictamente de solo lectura — prueba la resistencia a manipulaciones, nunca modifica un registro.

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

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

intact es true cuando todo el tramo inspeccionado está intacto; si se encuentra una rotura, firstBrokenSeq informa el tenantSeq del primer registro que falla y verifiedCount informa cuántos se mantuvieron antes de él. truncated es true cuando la cadena contiene más registros de los que permitía el límite de inspección maxRecords.

Obtener un log de auditoría

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

También puedes listar el historial de una entidad directamente con GET /v1/governance/entities/{entityType}/{entityId}/audit-logs (paginado por cursor), lo cual resulta conveniente cuando ya conoces la entidad que estás auditando.

Códigos de respuesta

Estado	Significado
`200`	Datos de mapeo, archivo o auditoría devueltos
`204`	Mapeo de actor pseudonimizado o eliminado
`400`	Entrada inválida (falta displayName/email, fecha/paginación incorrecta)
`403`	Falta el nivel de permiso requerido (p. ej. `deanonymize` para PII de un solo registro)
`404`	Mapeo de actor, archivo o log de auditoría no encontrado
`422`	Campo mal formado (p. ej. formato de email inválido)

​Mapeos de actores

​Listar mapeos de actores

​Upsert de un mapeo de actor

​Obtener un mapeo de actor (des-anonimizar)

​Pseudonimizar (GDPR)

​Eliminar (derecho al olvido)

​Archivos

​Listar archivos

​Descargar un archivo

​Logs de auditoría

​Listar logs de auditoría

​Verificar la cadena de auditoría

​Obtener un log de auditoría

​Códigos de respuesta

Mapeos de actores

Listar mapeos de actores

Upsert de un mapeo de actor

Obtener un mapeo de actor (des-anonimizar)

Pseudonimizar (GDPR)

Eliminar (derecho al olvido)

Archivos

Listar archivos

Descargar un archivo

Logs de auditoría

Listar logs de auditoría

Verificar la cadena de auditoría

Obtener un log de auditoría

Códigos de respuesta