ADR-016: Los datos personales en bloque salen solo por el reporte de Cumplimiento
Date: 2026-10-02 Status: Accepted — decisión conservadora tomada en la revisión de la entrega B4 del plan de ajustes v2 (PR 1), sin consulta previa a Carlos. Se revierte con dos líneas (ver "Si se revierte"). Extends: ADR-011 (datos del pago) y la decisión P7 del plan v2 (el reporte de Cumplimiento tiene permiso propio). Numeración: es el 016 y no el 014 porque el plan reserva el 014 y el 015 para las entregas B6 y B7; los commits de B4 que dicen "ADR-014" se refieren a este documento.
Context
El reporte de Cumplimiento (B4) vuelca los datos personales de todos los beneficiarios de un país: nombre, fecha de nacimiento, nacionalidad, documento, teléfono, mail y dirección. Por eso tiene un permiso propio (reporte_cumplimiento, solo Admin), un tope de filas, un límite de descargas y una auditoría.
La revisión de B4 encontró que esa protección tenía un camino lateral: GET /transacciones (el listado) respondía con TransactionResource, que vuelca todas las columnas de la fila menos la comisión. Hasta 100 beneficiarios por página, con documento, dirección, teléfono, mail, cuenta bancaria y, desde B4.0, fecha de nacimiento y nacionalidad ya cargadas. Un Supervisor —lectura de Transacciones sobre todo su país y ningún acceso al reporte— podía paginar el listado y bajar lo mismo que el Excel que se restringió a Admin, sin dejar rastro en Auditoría. La pantalla de listado usa nueve campos; el resto viajaba sin que nadie lo mostrara.
La revisión encontró además que el límite de descargas del reporte (throttle:10,1,...) no hacía lo que decía. Se verificó con el router real:
- El
throttlede Laravel firma por$request->user(), y esta app no usa el guard de Laravel (el usuario viaja enattributes['api_user']): firma por IP. Detrás del balanceador, sin proxies de confianza configurados, esa IP es la del ALB: los 10 por minuto eran un único cupo compartido por todos los usuarios. - Laravel ordena
ThrottleRequestspor prioridad antes defirebase.authyapi.user. Ni siquiera un limiter con nombre ve aapi_user: esnull. Así queRateLimiter::for(...)por usuario tampoco sirve.
Decision
1. El listado es una lista blanca
GET /transacciones responde con TransactionListResource: Arr::only sobre un conjunto fijo de campos (id, mtcn, status, nombre y apellido, amount, país, PDV y las dos fechas). Es lo que muestra la tabla y nada más. Un campo nuevo de la transacción no aparece en el listado hasta que alguien lo agrega a TransactionListResource::CAMPOS.
Actualización G4.3 (ajustes v3, 2026-10-06): la lista blanca suma procesada_por, el texto de la columna «Procesada por» del Reporte individual (RV3-16): el mail de quien resolvió la transacción, «Soterex (API)» o «Sistema» si la canceló la integración o el vencimiento, y vacío si nadie la resolvió. Es un campo calculado y es dato del operador, no del beneficiario: la relación resolvedBy sigue sin viajar, sale solo ese texto. Se agregó a propósito, como pide esta regla. El Excel (GET /transacciones/export) lo trae como novena columna con el mismo valor, y no lo copia a la metadata de la auditoría de la exportación.
La ficha de una transacción (GET /transacciones/{id}) no cambia. Devuelve la fila completa a quien tiene lectura de Transacciones sobre ese país y PDV, como ya hacía con el documento: la pantalla de detalle la usa para el formulario de solo lectura, y quitarle datos a quien hoy los ve es una decisión de producto que no se tomó acá. Lo que cambia es que bajar los datos de muchas personas exige el reporte (permiso propio, auditado) o abrir las fichas de a una.
Actualización G4.5 (ajustes v3, 2026-10-06): la ficha suma el mismo procesada_por, con el mismo texto que el listado y el Excel. Sale en todas las respuestas que arma TransactionResource: la ficha, pagar, cancelar y PATCH /transacciones/{id}/datos-pago (esta última siempre vacía, porque solo opera sobre una ACCEPTED). La relación resolved_by no viaja. El alcance de la ficha no cambia: quien ya la veía ve quién la procesó, y nadie más.
2. Rate limit por usuario con un middleware propio
ThrottlePerUser (alias throttle.user, throttle.user:bucket,intentos,minutos) firma por el id del usuario y corre después de api.user porque no está en la lista de prioridades de Laravel. Sin usuario resuelto cae a la IP en vez de dejar pasar sin límite. Responde 429 en JSON con Retry-After. Lo usa el reporte de Cumplimiento (10 por minuto). /pago/buscar y /sso/docs-api-token siguen con el throttle por IP: tienen el mismo defecto, pero no son parte de B4 y no se tocaron.
3. El intento fuera de alcance se audita
Pedir el reporte de un país que no es del usuario responde 403 (igual para uno ajeno que para uno inexistente) y registra REPORT_EXPORT_DENIED con el usuario y el id pedido. La pantalla solo ofrece los países donde el usuario tiene el permiso, así que llegar ahí es un pedido armado a mano. Mismo patrón que ROLE_PERMISSION_ESCALATION_DENIED. El rate limit acota el volumen.
Consequences
- Quien tiene lectura de Transacciones ya no recibe los datos personales de 100 personas por página. La pantalla de Transacciones no cambia (usaba solo esos campos).
- Todo consumidor nuevo del listado que necesite otro campo lo agrega a la lista blanca a propósito, con la pregunta de por qué lo necesita a la vista.
- El límite de descargas ahora es del usuario: lo que descargan otros no le cuenta. Un token robado queda acotado a 10 por minuto.
- La ficha sigue exponiendo la fila completa dentro del alcance del usuario. Si se quisiera cerrar eso también (por ejemplo, datos personales solo para quien opera la transacción, como en la búsqueda de Pago), es un cambio de
TransactionResourcey de la pantalla de detalle, y hay que decidirlo con el cliente. trustProxies(para que$request->ip()sea la del cliente y no la del ALB) no se configuró: depende del CIDR del balanceador y de la infra. No afecta a este límite (va por usuario), pero sí a cualquierthrottlepor IP, a los logs y a los límites de OAuth.- El Excel ya no puede arrastrar texto libre de un usuario (2026-10-07, G9.2 del plan de ajustes v3). La columna 30 (Transaction Status-Additional Notes) sale siempre vacía y el reporte dejó de leer
audit_logs: antes llevaba el motivo que tipeaba quien cancelaba, que es texto libre y puede traer datos personales. El motivo sigue solo en Auditoría (solo Admin), con el evento Cambio de estado de transacción, y no sale en bloque por ningún reporte.
Si se revierte
- Listado: volver a
TransactionResource::collection(...)enTransactionController::index()y borrarTransactionListResourcey su test. - Límite: volver a
throttle:10,1,reporte-cumplimientoenroutes/api.php(queda por IP, compartido detrás del ALB).

