ADR-019: Los soportes de pago viven en un bucket S3 privado, no en el disco del contenedor
Date: 2026-10-06 Status: Accepted — decisión D3-1 (a) de Carlos (2026-10-05) del plan de ajustes v3 (2026-10-04-ajustes-v3-cliente-gt, entrega G1). Implementado en el branch feature/v3-soportes-persistentes y todavía no desplegado: el terraform apply y el orden del despliegue los corre Carlos, con el runbook de Staging. Pasa por la revisión de security antes del merge (el plan lo exige: es un bucket nuevo con identificaciones). Extends: el diseño de almacenamiento de E5a §2 (que ya decía "S3 privado" y nunca se construyó), ADR-008 y ADR-011 (qué documentos hay y quién los sube). Numeración: el plan lo nombra ADR-017 de forma provisoria; ese número y el 018 los tomaron, mientras tanto, el contrato C2P y la comisión C2P. Es el 019.
Context
Lo que se encontró (2026-10-04, al relevar RV3-07)
El cliente reportó que "la documentación cargada de un pago no permite visualizar" (RV3-07). La causa no era un permiso ni un bug del frontend: ningún soporte de pago se guardaba en un lugar persistente, y la documentación decía que sí.
- El disco era local.
backend/config/filesystems.phpdefine el discodocumentscomolocalsalvo queDOCUMENTS_DISK_DRIVERvalgas3. Los archivos caían enstorage/app/documents, dentro del contenedor Fargate. - Nadie definía esa variable. Ni el módulo
ecsde Terraform, ni los workflows, ni elDockerfile. Solobackend/.env.examplela mencionaba, con el valorlocal. - La librería de S3 no estaba instalada.
league/flysystem-aws-s3-v3no figuraba encomposer.jsonni envendor/(soloflysystem-local): aunque alguien hubiera puesto la variable, la app no habría podido usar S3 y todo acceso a un soporte habría dado 500. - No había bucket. El único
aws_s3_bucketdel Terraform era el del estado. E5a decía "el bucket va a Terraform en la entrega de infra"; esa entrega nunca lo hizo. - La documentación afirmaba lo contrario: E5a §2, el análisis funcional (
02-datos-y-documentos, 2.5 punto 4), el comentario defilesystems.phpy el de la migración detransaction_documentsdecían "S3 privado en Staging y producción".
Qué producía
- Cada deploy destruye el contenedor. La fila de
transaction_documentsvive en Aurora y sobrevivía; el archivo se iba con el contenedor. Staging se promovió 11 veces entre el 29/09 y el 04/10: todo soporte subido antes del último deploy quedó como fila sin archivo, y abrirlo da el 404DOCUMENT_FILE_MISSING. - La pantalla seguía diciendo "Completa": la completitud se calcula sobre filas (
Transaction::documentacionCompleta()), no sobre archivos. - Con más de una tarea el defecto aparece sin deploy: el archivo cae en el disco de la tarea que atendió la subida y lo pide otra.
web_max_countes 2 en Staging y 8 en Producción.
Lo que se guarda son identificaciones de personas migrantes y el respaldo contable de cada pago (2.5 del análisis funcional). Perderlos es perder el respaldo de un pago; un bucket mal armado sería, además, una filtración de datos personales. Es bloqueante para producción.
Decision
Los soportes de pago se guardan en un bucket S3 privado por ambiente, al que el backend entra con el task role de ECS y una política mínima. (D3-1, opción (a).)
1. Un bucket por ambiente, privado desde que nace
Módulo infra/terraform/modules/documents, usado por environments/staging y environments/production:
| Control | Valor |
|---|---|
| Nombre | soterex-<ambiente>-documents-<id de cuenta>. El id de cuenta evita que alguien ocupe el nombre (los de S3 son globales) |
| Acceso público | Bloqueado entero (los cuatro flags de public_access_block). ACLs deshabilitadas (BucketOwnerEnforced): el acceso lo deciden IAM y la política del bucket, nunca una ACL de objeto |
| Cifrado en reposo | SSE-S3 (AES-256). Sin KMS a propósito: el task role necesitaría permisos de KMS y se pagaría cada request |
| Transporte | La política del bucket deniega todo lo que no sea TLS y TLS anterior a 1.2, para cualquier principal (un administrador incluido) |
| Versionado | Prendido, como red de seguridad ante una sobrescritura accidental. Las versiones no vigentes expiran a los 90 días en Staging y 365 en Producción; el objeto vigente no expira nunca |
| Subidas cortadas | Las partes de una subida multipart incompleta se limpian a los 7 días (el SDK pasa a multipart desde 16 MB y el límite de la app es 20) |
| Destrucción | prevent_destroy: un plan que quiera reemplazar o borrar el bucket se corta |
| Etiquetas | Purpose=soportes-de-pago, DataClassification=pii |
2. El backend entra por el task role, sin credenciales estáticas
- Ni
AWS_ACCESS_KEY_IDniAWS_SECRET_ACCESS_KEYexisten en ninguna variable de ECS, imagen ni secret. El SDK toma las credenciales del task role.config/filesystems.phpno pasakeynisecretal disco: pasarlos fuerza credenciales estáticas y deja afuera el token de sesión, que es justo lo que traen las credenciales temporales (hay un test que lo demuestra). - La política del task role (la única que tiene ese rol: hasta G1 el código PHP no hablaba con ningún servicio de AWS):
s3:PutObject,s3:GetObjectys3:AbortMultipartUploadsobrebucket/*.s3:ListBucketsobre el bucket. No es opcional: sin él, pedir un objeto que no existe devuelve 403 y no 404, y como el disco tienethrow => true,exists()revienta en 500 en lugar del 404 controladoDOCUMENT_FILE_MISSING.- Sin
s3:DeleteObjectnis3:DeleteObjectVersion: un soporte no se borra. Esa ausencia es el control. Si algún día hace falta borrar (una orden legal, por ejemplo), se hace con credenciales de administración, no desde la app.
- Variables que recibe la aplicación (
common_environmentdel móduloecs, o sea web y queue):DOCUMENTS_DISK_DRIVER=s3,DOCUMENTS_BUCKETyAWS_DEFAULT_REGION.
3. El disco documents cambia de driver; el contrato con la app no cambia
- Sigue sin haber URLs directas ni prefirmadas (E5a §2). La descarga pasa siempre por
TransactionDocumentController::download(), que valida permiso y alcance por país y PDV y audita cada lectura. Por eso el bucket no necesita CORS ni ningún acceso público. - El
pathlo arma el servidor (transacciones/{transaction_id}/{tipo}-{uuid}.{ext}), nunca el usuario. - La fila guarda el nombre del disco (
documents), no el del driver. Al cambiar el driver a S3, las filas viejas buscan su archivo en el bucket, no lo encuentran y dan el 404 controladoDOCUMENT_FILE_MISSING. No hay migración de archivos porque no hay archivos que migrar: ya se perdieron. - El frontend distingue la causa (P3-5,
frontend/src/utils/soporteDocumento.ts): archivo que ya no está ("El archivo no está disponible. Un Supervisor o Admin puede volver a subirlo."), red o 413 ("No se pudo enviar el archivo: revisá la conexión o probá con uno más chico"), 5xx ("Error del servidor, avisá a soporte"), y un archivo de más de 20 MB o de otro tipo ni siquiera se envía. php artisan documentos:verificar [--detalle](solo lectura) cuenta las filas cuyo archivo no está en el disco y, con--detalle, las lista (ids, tipo, disco y fecha; nunca en la salida el nombre del archivo, la ruta ni el MTCN). No borra filas: un soporte no se borra, se vuelve a subir. «Sin archivo» cuenta solo el soporte vigente de cada (transacción, tipo): reemplazar inserta una fila nueva y deja la anterior (la tabla es inmutable), y esa fila vieja sin archivo se cuenta aparte como «reemplazada», para que reparar un soporte baje el número. En el log de errores (cuando un disco no se puede consultar) viaja el mensaje de la excepción, y el de S3 puede traer la clave del objeto (transacciones/<id>/<tipo>-<uuid>.<ext>: ids y un tipo de documento, nada personal), nunca el nombre original ni el MTCN.- Si el almacenamiento falla, el pedido da 503 con
DOCUMENT_STORAGE_UNAVAILABLEy el detalle va solo al log. Subir y abrir un soporte atrapan las excepciones de Flysystem: conAPP_DEBUG=true(todo ambiente que no es producción) un 500 le habría devuelto a cualquier usuario el mensaje del SDK, con el bucket (el id de la cuenta de AWS) y la clave del objeto. Y la subida corre en una transacción de base de datos: si S3 falla, no queda ni el PDV asignado a la transacción (un usuario de otro PDV no podría subir la Carta y la identificación que bloquean el pago, ADR-008) ni una fila sin archivo ni una auditoría de una subida que no ocurrió. Dentro de esa transacción el archivo y su fila se escriben antes delUPDATEdel PDV: eseUPDATEretiene el candado de la fila detransactionshasta confirmar, y hacerlo antes de la subida frenaba unpay()concurrente mientras se escribía el archivo (hasta 20 MB; ver la actualización G5 de ADR-011). El resto del pedido (permisos, alcance, el PDV que se fijaría y la validación del archivo) son lecturas y van antes de empezar. Un residuo inherente a mezclar S3 con una transacción de base de datos: si lo que falla es la auditoría después de que S3 guardó el archivo, la fila y el PDV se deshacen pero el objeto queda sin ninguna fila que lo referencie, y sinDeleteObjectla app no lo borra. Es inocuo (el bucket es privado y nada lo apunta) y se limpia a mano con credenciales de administración, como los dedemo:reseed(abajo). La lectura se hace antes de auditarTRANSACTION_DOCUMENT_VIEWED.
4. Orden de despliegue (importa)
Hay tres cosas que se pisan entre sí. Por eso el orden es este y no otro:
| # | Paso | Quién | Por qué en este lugar |
|---|---|---|---|
| 1 | Merge y deploy de la imagen con la librería, con el disco todavía local | Carlos | Una tarea con DOCUMENTS_DISK_DRIVER=s3 sobre una imagen sin la librería da 500 en todo acceso a un soporte. Sin la variable, la app sigue en local y no cambia nada visible |
| 2 | terraform apply de Staging, a mano | Carlos | Crea el bucket, adjunta la política al task role y re-registra las task definitions con las tres variables nuevas. El permiso rige apenas termina el apply |
| 3 | Un deploy más | Carlos | deploy-staging.yml arma la task definition nueva a partir de la última revisión de la familia, no de la que corre el servicio: recién este deploy toma las variables y la app pasa a S3 |
| 4 | Verificación | Carlos | Subir, forzar un redeploy y abrir; los controles del bucket con la CLI de AWS; el preflight de CORS; el smoke de subida |
Las trampas, todas con antecedente:
- El apply deja
image = …:initialen la última revisión de la familia. Entre el paso 2 y el 3 no se lanzarun-artisan-command.yml(usa la familia, o sea esa revisión) ni se hace nada que registre una revisión desde ahí. - Para el paso 3, lo más simple es re-correr el job de backend del deploy del paso 1. Hasta el 2026-10-04 no servía: los tags de ECR son inmutables y el tag es el SHA del commit, así que el deploy se cortaba antes de tocar ECS. Desde el PR #76 el push tolera el tag existente y sigue, y la task definition se renderiza de nuevo desde la última revisión de la familia, que ya trae las variables. Esa vía todavía no se usó en un caso real después del arreglo: la alternativa segura es un commit nuevo en
staging. Para volver atrás, un rerun no sirve (hereda de la última revisión, que es la de S3). - El apply puede repetir el incidente del CORS del 2026-10-02 (login roto): se corre desde la laptop leyendo el plan antes de aplicar, y se hace el preflight de CORS después. El workflow
terraform-apply.ymlplanea y aplica en el mismo job, sin una pausa en el medio para leer el plan (según su propio comentario, solo el Environment de Producción exige reviewers).
Los comandos exactos, qué tiene que decir el plan y cómo volver atrás están en el runbook de Staging y en infra/terraform/README.md (sección «Bucket de soportes de pago»).
Alternativas consideradas
- (b) EFS montado en las tareas Fargate. Persistiría y se compartiría entre tareas, pero suma costo y piezas que S3 no necesita (el sistema de archivos, los mount targets y su regla de red, permisos POSIX) y un punto de falla más para algo que S3 resuelve solo. Tampoco da versionado de objetos. Descartada.
- (c) Dejar el disco local hasta producción. Los soportes de Staging se pierden en cada deploy y se descarta toda la prueba de soportes del cliente (RV3-06/07); Producción arrancaría con un camino de almacenamiento que nunca se probó. Descartada.
- URLs prefirmadas de S3 en lugar de servir el archivo desde la app. Sacarían la validación de alcance por PDV y la auditoría de cada lectura (
TRANSACTION_DOCUMENT_VIEWED) del camino de la descarga, y el bucket necesitaría CORS. Descartada (ya lo estaba en E5a §2). - Access keys de un usuario IAM en las variables de ECS. Secretos estáticos que hay que rotar y que quedan en la task definition. Descartada: el task role entrega credenciales temporales y rota solo.
- SSE-KMS con una clave propia. Más control y auditoría de uso de la clave, a cambio de permisos de KMS en el task role y un costo por request. Diferida, no descartada: pasar a una clave propia es un cambio de un recurso del módulo y de su política, sin tocar el backend.
- Cifrado a nivel de aplicación sobre el contenido. Fuera de alcance; sigue anotado como pendiente en la pregunta abierta #7.
Consequences
Lo que se gana
- Un soporte subido sobrevive a un deploy y lo ven todas las tareas, sea cual sea la que atendió la subida.
- Una sobrescritura accidental de un objeto deja la versión anterior recuperable durante el plazo de retención de versiones (la ruta lleva un uuid, así que una subida normal nunca pisa nada).
- Ninguna credencial estática. El bucket no es alcanzable públicamente ni por una ACL ni por una política pública.
- Se mide el daño:
documentos:verificardice cuántos soportes quedaron sin archivo.
Lo que cuesta
- S3 pasa a ser parte del camino de Pago. Si S3 o IAM fallan, subir y abrir soportes dan 5xx ("Error del servidor, avisá a soporte") y no se pueden subir la Carta y las identificaciones, que bloquean confirmar un pago nuevo (ADR-008). Un pago que ya las tiene no se ve afectado por esto.
- Lo subido antes se pierde y no se recupera. Los soportes de Staging anteriores a este despliegue no existen más: las filas quedan y se vuelven a subir. Producción nunca se aplicó, así que ahí no hay nada que perder.
- "Completa" sigue calculándose sobre filas, y el chequeo que bloquea el pago también. Si un objeto desaparece por fuera de la app (borrado con credenciales de administración, por ejemplo), la pantalla sigue diciendo "completa". Y como
Transaction::faltanDocumentosPrePago()(la compuerta de ADR-008, que usapay()) también mira filas, una transacciónACCEPTEDcon la Carta y la identificación subidas antes de G1, con el archivo ya perdido, pasa esa compuerta y se puede pagar sin ningún soporte guardado. Hoy hay que cubrirlo a mano: el runbook pide volver a subir esos soportes antes de dejar que el cliente pague. No se agregó un chequeo por request ni enpay(): cada fila sería unHeadObject, y es una decisión aparte. La medida esdocumentos:verificar, que se corre a demanda. - La app no puede borrar objetos, y algún código lo da por hecho.
demo:reseedborra las filas detransaction_documentsy trata de borrar cada archivo "best-effort" (el error se traga): en S3, sinDeleteObject, los objetos quedan huérfanos en el bucket aunque su fila se haya ido. Y el backup previo dedemo:reseed --wipe-onlyescribe en el mismo bucket, bajobackups/, lo que elPutObjectsí permite, y con datos personales: el JSON completo detransactions(beneficiario, teléfono, fecha de nacimiento y el MTCN, que es la credencial de cobro), la auditoría y una copia de cada soporte. La clave de cada copia lleva solo el id del soporte y la extensión (…/files/<id>.<ext>), no el nombre original, que suele ser el de la persona: una clave aparece en listados, en CloudTrail y en logs de acceso. Ninguna regla de ciclo de vida tocabackups/: no se les puso plazo de expiración a propósito, porque en un bucket versionado expirar el objeto vigente solo deja una marca y la versión sigue 90 días más, y es una decisión de retención que no es de esta entrega. Limpiarlo es una tarea manual con credenciales de administración, versiones incluidas (el runbook de Staging lo avisa). - Un servicio más que mirar: costo de S3 (por GB y por request, bajo para este volumen) y un nuevo modo de falla por permisos. Un
s3:ListBucketque faltara convertiría el 404 controlado en un 500. - Una trampa de despliegue permanente mientras
deploy-staging.ymlrenderice la task definition desde la última revisión de la familia: después de cadaapplyque toqueecsowafse corre el preflight de CORS y el smoke de subida (P3-6, en el runbook).
Verificación pendiente: la ACL private sobre un bucket con ACLs deshabilitadas
El adaptador de Flysystem manda siempre x-amz-acl: private en el PutObject (se comprobó capturando el request: lo manda con o sin visibilidad explícita). Con BucketOwnerEnforced, S3 puede rechazar un PutObject que trae una ACL con AccessControlListNotSupported. Debería aceptarla (private equivale al control total del dueño), pero no se pudo probar contra un bucket real: se confirma con la primera subida en Staging (paso 4 del runbook).
- Si falla, no alcanza con sacar
'private'deTransactionDocumentService::store(): el adaptador manda la ACL igual. - Plan B, solo de configuración y sin tocar código de la subida: en la rama
s3del discodocumentsdeconfig/filesystems.php,'options' => ['ACL' => 'bucket-owner-full-control']. El adaptador tomaoptions.ACLantes que la visibilidad (hay un test que captura elPutObjecty lo fija: saleprivatepor defecto ybucket-owner-full-controlcon la opción), y esa es la ACL que AWS documenta como aceptada en un bucket con las ACL deshabilitadas. Es un cambio de una línea que se promueve con un deploy, sinapply. - Plan C, si ni eso: escribir con el cliente del SDK (
Storage::disk(...)->getClient()->putObject(...)) y sin ACL, solo para el discos3(comentario destore()). - Un permiso que no está y se sospecha:
s3:PutObjectAcl. El adaptador mandax-amz-aclen cadaPutObjecty la política mínima (G1.2 fija las acciones) no la trae. No se pudo confirmar contra AWS si S3 exige ese permiso para ese encabezado con las ACL deshabilitadas. Si la primera subida daAccessDeniedaunque el simulador de IAM digaallowedparaPutObject, es el primer sospechoso; agregarlo, acotado abucket/*, no abre nada (S3 rechaza cualquier ACL que no sea la del dueño). No se agregó por adelantado: ampliar permisos sin evidencia va contra la política mínima, y la prueba de humo lo detecta. - La alternativa de infraestructura, peor, es pasar el bucket a
BucketOwnerPreferred, que vuelve a habilitar las ACLs: se pierde el control de "ninguna ACL de objeto decide nada".
Lo que esto NO cubre
- No hay política de retención del objeto vigente: un soporte no expira nunca. Es una decisión, no un default neutro; falta acordarla con CIS-EC (pregunta abierta #7).
- No hay clave propia (CMK) ni cifrado a nivel de aplicación. SSE-S3 protege contra el acceso al disco, no contra credenciales comprometidas.
- No hay
Object Lockni réplica a otra región. El versionado es una red de seguridad ante una sobrescritura, no un archivo histórico (las versiones no vigentes expiran). - El módulo no configura registro de accesos del bucket (ni los logs de acceso de S3 ni eventos de datos de CloudTrail). Quién abrió un soporte lo dice la Auditoría de la app (
TRANSACTION_DOCUMENT_VIEWED); quién tocó el bucket por fuera de la app, no. Esa vía existe:run-artisan-command.ymlcorre un comando artisan de texto libre con el task role, que puede leer todos los soportes, y quien tenga credenciales de administración también. Queda como decisión explícita del checklist de Producción (production.md): se toma antes del primerapplyallí. - Cualquier operador con
transacciones:writeen su PDV sigue pudiendo descargar los soportes de ese PDV: es el alcance de ADR-011, no cambió.
Si se revierte
- Antes de que haya soportes reales en S3: registrar una revisión nueva de la task definition, copiada de la que corría antes del
apply(la que dejó el deploy del paso 1, sinDOCUMENTS_DISK_DRIVER), para que sea la última de la familia, y apuntar el servicio a ella. Apuntar el servicio a la revisión vieja no alcanza: el deploy siguiente renderiza desde la última revisión, que es la de S3. Y mientras el móduloecsconserve las tres variables, el próximoterraform applylas vuelve a registrar: para quedarse en disco local hay que sacarlas del módulo antes. Lo subido a S3 mientras tanto no se pierde, pero la app deja de verlo hasta volver as3. Con el disco local el defecto original vuelve: se pierden los soportes en cada deploy. Los comandos están en el runbook de Staging (Si algo falla: volver atrás). - No hay camino de vuelta para los datos: los archivos que estuvieron en el contenedor no son recuperables. Y el bucket no se borra: tiene
prevent_destroy, y desarmarlo a propósito exige sacar esa línea en un commit aparte y vaciarlo antes (versiones incluidas). - Cambiar de bucket o de ambiente exige copiar los objetos con las mismas claves (
transacciones/…): las filas guardan la ruta.
Referencias
- Plan:
2026-10-04-ajustes-v3-cliente-gt§4 G1 (RV3-06, RV3-07), §3.3 D3-1, P3-5, P3-6, P3-16 y R-3, R-4. - Diseño original y su nota de lo que no se hizo: E5a §2; 2.5 y 2.6 del análisis funcional.
- Infraestructura y comandos de verificación con la CLI de AWS:
infra/terraform/README.md("Bucket de soportes de pago"). - Runbook de despliegue, smoke de subida y
documentos:verificar: Staging. - El incidente que fija el orden: CORS roto tras un
terraform apply.

