/v1/governance:
- Mapeos de actores: vinculan IDs de actor opacos con PII, con operaciones de seudonimización y eliminación.
- Archivos: listan los archivos completados de registros de auditoría y descargan objetos archivados desde el almacenamiento de objetos.
- Registros de auditoría: historial inmutable encadenado por hash, con una verificación de integridad de solo lectura.
AUTH_PROVIDER=plugin-auth en modo multi-tenant, la identidad del tenant proviene del JWT. Matcher rechaza el inicio cuando MULTI_TENANT_ENABLED=true y PLUGIN_AUTH_ENABLED=false.
Toda ruta de gobernanza permanece dentro del tenant del llamador. Las lecturas de mapeos de actores tienen dos niveles de autorización: el listado, que omite
displayName y email, y la lectura de de-anonimización de un solo registro. Esta separación mantiene la resolución de identidad aparte del acceso de exploración.Mapeos de actores
Un mapeo de actor vincula un
actorId opaco (por ejemplo, user:550e8400-e29b-41d4-a716-446655440000) con PII legible por humanos (displayName, email). Fuera de los entornos local, de desarrollo y de prueba, establece ACTOR_PII_ENCRYPTION_KEY con una clave de 32 bytes codificada en base64 antes de usar los mapeos de actores. Si la dejas sin definir, Matcher sigue funcionando. Las operaciones de mapeo que llevan PII (upsert, lectura de un solo registro y seudonimización) entonces devuelven un error de encriptador obligatorio. Las rutas de listado y eliminación, que no llevan PII, no necesitan un encriptador. Matcher nunca almacena la PII de los mapeos en texto plano.
Las filas del listado omiten los campos de PII del mapeo (displayName, email) por diseño, pero sí devuelven el propio actorId. En el upsert, Matcher recorta los espacios en blanco iniciales y finales, y rechaza IDs vacíos o compuestos solo por espacios en blanco, así como IDs de más de 255 caracteres. Matcher no impone un formato de ID opaco ni oculta el valor. Un actorId que en sí mismo contiene PII, como una dirección de correo electrónico, aparece en las filas del listado con su valor almacenado. La seudonimización conserva ese valor. Usa identificadores opacos si el acceso al listado debe permanecer libre de PII.
La respuesta de PUT y el GET de un solo registro devuelven la identidad en texto plano. El permiso deanonymize controla solo el GET de un solo registro. El acceso de escritura por sí solo controla la respuesta de PUT, que refleja el registro almacenado completo, incluido cualquier campo almacenado que el llamador no haya enviado. Trata el acceso de escritura a mapeos de actores como revelador de PII. Los registros de auditoría pueden conservar el actorId sin procesar, que puede ser una dirección de correo electrónico.
Lista los mapeos de actores
Filas paginadas por cursor que omitendisplayName y email. Filtra por un prefijo de ID de actor.
actorId (filtro de prefijo), limit (25 de forma predeterminada, con un máximo de 100) y cursor.
Crea o actualiza 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 después. Proporciona al menos uno de displayName o email.
Obtén un mapeo de actor (de-anonimizar)
Devuelve la PII en texto plano de un único ID de actor. Esta es la operación primitiva de de-anonimización, por lo que el permiso más restringidodeanonymize la controla en lugar de una lectura simple.
Seudonimiza
ReemplazadisplayName y email del mapeo con [REDACTED], conservando el registro y su vínculo de actorId. Esto elimina la PII solo del mapeo. Los registros de auditoría inmutables conservan el actorId sin procesar de la escritura original, y ese valor puede ser en sí mismo una dirección de correo electrónico. Los registros de auditoría históricos y los archivos archivados conservan sus valores originales. Responde 204 No Content.
Elimina un mapeo
Elimina el mapeo de forma permanente. Responde204 No Content.
Seudonimizar conserva el registro y elimina su PII. Eliminar borra el registro por completo. Elige seudonimizar cuando debas conservar el vínculo de auditoría, y eliminar cuando el registro en sí no deba persistir.
Archivos
El worker de archivado permanece apagado de forma predeterminada (
ARCHIVAL_WORKER_ENABLED=false). Cuando lo habilitas y configuras el almacenamiento de archivado, el worker comprime las particiones de registros de auditoría que envejecen y las mueve al almacenamiento de objetos. Matcher registra las rutas de recuperación de archivos siempre que el almacenamiento de objetos de archivado esté disponible, incluso cuando el worker permanece apagado. El endpoint de listado devuelve los archivos completados. El endpoint de descarga emite URLs de tiempo limitado para los objetos archivados.
Lista los archivos
Paginado por desplazamiento. Filtra por rango de fechas.from, to (YYYY-MM-DD o RFC 3339), limit (1–200, 20 de forma predeterminada) y offset. El endpoint lista solo los archivos COMPLETE y nunca muestra archivos en curso o fallidos.
Descarga un archivo
Devuelve una URL prefirmada junto con la suma de verificación para la verificación de integridad.Registros de auditoría
Los workflows de gobernanza instrumentados escriben registros de auditoría inmutables por tenant. Matcher vincula cada registro en una cadena de hash SHA-256 a prueba de manipulaciones (
recordHash = SHA-256(prevHash || canonical content)), de modo que los cambios inconsistentes se pueden detectar. Usa el endpoint de verificación que se muestra abajo para obtener el veredicto de integridad del lado del servidor.
Lista los registros de auditoría
Paginado por cursor, con filtros completos.actor, action, entity_type, date_from, date_to (YYYY-MM-DD o RFC 3339), limit (1–200, 20 de forma predeterminada) y cursor.
actor filtra por el valor actorId del registro. Ese valor es el identificador de actor sin procesar de la escritura original, una dirección de correo electrónico en este ejemplo. Los registros de auditoría almacenan el identificador tal cual. No tiene que coincidir con el actorId de un mapeo de actor.
Cuando una diferencia supera el límite de payload del outbox, changes lleva un envoltorio marcador de truncamiento en lugar de la diferencia completa, y truncated pasa a true, mientras originalSize indica el tamaño en bytes antes del truncamiento.
Verifica la cadena de auditoría
Vuelve a verificar que cada registro inspeccionado se vincule con el anterior y coincida con su hash almacenado. La verificación recorre un tramo contiguo con un límitemaxRecords, por lo que intact solo da fe de ese tramo inspeccionado. En el endpoint HTTP, un maxRecords proporcionado debe estar en el rango 1–10,000, y un valor fuera de ese rango devuelve 422. Cuando lo omites, Matcher usa el valor predeterminado de 10,000 registros.
fromSeq es un piso de verificación opcional (mínimo 1). Omítelo para empezar en la secuencia 1. Un piso superior a 1 confía en el prevHash almacenado de ese registro, por lo que la ejecución no cubre manipulaciones por debajo del piso. La verificación permanece estrictamente de solo lectura. Detecta manipulaciones y nunca modifica un registro.
intact es true cuando todo el tramo permanece intacto. Cuando la verificación encuentra una ruptura, firstBrokenSeq indica el tenantSeq del primer registro que falla, y verifiedCount indica cuántos registros se mantuvieron íntegros antes de ese punto. El campo truncated es true cuando la cadena contiene más registros de los que permitió el límite de inspección maxRecords. La respuesta refleja el fromSeq efectivo. Después de una ejecución truncada, retoma con fromSeq = fromSeq + verifiedCount para inspeccionar el siguiente tramo.
Obtén un registro de auditoría
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 útil cuando ya conoces la entidad que quieres auditar.