> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Gobernanza

> Gestiona los mapeos de PII de actores, lista los archivos de registros de auditoría y descarga objetos archivados, y vuelve a verificar la cadena de hash de auditoría a prueba de manipulaciones de Matcher.

La superficie de gobernanza de Matcher agrupa tres funciones bajo `/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.

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

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

## 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 omiten `displayName` y `email`. Filtra por un prefijo de ID de actor.

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

```json theme={null}
{
  "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 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`.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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"
}
```

### 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 restringido `deanonymize` la controla en lugar de una lectura simple.

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

### Seudonimiza

Reemplaza `displayName` 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`.

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

### Elimina un mapeo

Elimina el mapeo de forma permanente. Responde `204 No Content`.

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

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

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

```bash theme={null}
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"
```

```json theme={null}
{
  "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, 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.

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

```json theme={null}
{
  "downloadUrl": "https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...",
  "expiresAt": "2026-02-05T13:00:00Z",
  "checksum": "sha256:abc123def456..."
}
```

<Warning>El manejador de descarga confirma la propiedad del tenant, pero no verifica `COMPLETE`. Prefirma la `archiveKey` almacenada. Un archivo recibe esa clave y su suma de verificación cuando alcanza `UPLOADED`, antes de `COMPLETE`. Trata `GET /v1/governance/archives/{id}/download` como una ruta directa a la clave del objeto, no como prueba de que el archivado se completó. Si necesitas solo archivos completados, selecciona los IDs desde el endpoint de listado.</Warning>

<Warning>La disponibilidad de los archivos depende del backend de almacenamiento compatible con S3 configurado y de la política de ciclo de vida. Confirma cualquier requisito de restauración con el propietario de ese despliegue de almacenamiento antes de depender de una URL de descarga.</Warning>

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

```bash theme={null}
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"
```

```json theme={null}
{
  "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` 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ímite `maxRecords`, 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.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?fromSeq=1&maxRecords=10000" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "intact": true,
  "fromSeq": 1,
  "verifiedCount": 1024,
  "truncated": false
}
```

El campo `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

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

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

## Códigos de respuesta

***

| Estado | Significado                                                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Datos de mapeo, archivo o auditoría devueltos                                                                                       |
| `204`  | Mapeo de actor seudonimizado o eliminado                                                                                            |
| `400`  | Entrada inválida en el nivel de aplicación (falta displayName/email o una fecha inválida)                                           |
| `403`  | Falta el nivel de permiso requerido (por ejemplo, `deanonymize` para PII de un solo registro)                                       |
| `404`  | Mapeo de actor, archivo o registro de auditoría no encontrado                                                                       |
| `422`  | Falló la validación de solicitud o esquema (por ejemplo, formato de correo electrónico inválido o un valor de consulta restringido) |