Skip to content

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

  1. El disco era local. backend/config/filesystems.php define el disco documents como local salvo que DOCUMENTS_DISK_DRIVER valga s3. Los archivos caían en storage/app/documents, dentro del contenedor Fargate.
  2. Nadie definía esa variable. Ni el módulo ecs de Terraform, ni los workflows, ni el Dockerfile. Solo backend/.env.example la mencionaba, con el valor local.
  3. La librería de S3 no estaba instalada. league/flysystem-aws-s3-v3 no figuraba en composer.json ni en vendor/ (solo flysystem-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.
  4. No había bucket. El único aws_s3_bucket del Terraform era el del estado. E5a decía "el bucket va a Terraform en la entrega de infra"; esa entrega nunca lo hizo.
  5. La documentación afirmaba lo contrario: E5a §2, el análisis funcional (02-datos-y-documentos, 2.5 punto 4), el comentario de filesystems.php y el de la migración de transaction_documents decían "S3 privado en Staging y producción".

Qué producía ​

  • Cada deploy destruye el contenedor. La fila de transaction_documents vive 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 404 DOCUMENT_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_count es 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:

ControlValor
Nombresoterex-<ambiente>-documents-<id de cuenta>. El id de cuenta evita que alguien ocupe el nombre (los de S3 son globales)
Acceso públicoBloqueado 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 reposoSSE-S3 (AES-256). Sin KMS a propósito: el task role necesitaría permisos de KMS y se pagaría cada request
TransporteLa política del bucket deniega todo lo que no sea TLS y TLS anterior a 1.2, para cualquier principal (un administrador incluido)
VersionadoPrendido, 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 cortadasLas 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ónprevent_destroy: un plan que quiera reemplazar o borrar el bucket se corta
EtiquetasPurpose=soportes-de-pago, DataClassification=pii

2. El backend entra por el task role, sin credenciales estáticas ​

  • Ni AWS_ACCESS_KEY_ID ni AWS_SECRET_ACCESS_KEY existen en ninguna variable de ECS, imagen ni secret. El SDK toma las credenciales del task role. config/filesystems.php no pasa key ni secret al 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:GetObject y s3:AbortMultipartUpload sobre bucket/*.
    • s3:ListBucket sobre el bucket. No es opcional: sin él, pedir un objeto que no existe devuelve 403 y no 404, y como el disco tiene throw => true, exists() revienta en 500 en lugar del 404 controlado DOCUMENT_FILE_MISSING.
    • Sin s3:DeleteObject ni s3: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_environment del módulo ecs, o sea web y queue): DOCUMENTS_DISK_DRIVER=s3, DOCUMENTS_BUCKET y AWS_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 path lo 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 controlado DOCUMENT_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_UNAVAILABLE y el detalle va solo al log. Subir y abrir un soporte atrapan las excepciones de Flysystem: con APP_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 del UPDATE del PDV: ese UPDATE retiene el candado de la fila de transactions hasta confirmar, y hacerlo antes de la subida frenaba un pay() 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 sin DeleteObject la 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 de demo:reseed (abajo). La lectura se hace antes de auditar TRANSACTION_DOCUMENT_VIEWED.

4. Orden de despliegue (importa) ​

Hay tres cosas que se pisan entre sí. Por eso el orden es este y no otro:

#PasoQuiénPor qué en este lugar
1Merge y deploy de la imagen con la librería, con el disco todavía localCarlosUna 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
2terraform apply de Staging, a manoCarlosCrea 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
3Un deploy másCarlosdeploy-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
4VerificaciónCarlosSubir, 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 = …:initial en la última revisión de la familia. Entre el paso 2 y el 3 no se lanza run-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.yml planea 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:verificar dice 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 usa pay()) también mira filas, una transacción ACCEPTED con 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 en pay(): cada fila sería un HeadObject, y es una decisión aparte. La medida es documentos:verificar, que se corre a demanda.
  • La app no puede borrar objetos, y algún código lo da por hecho. demo:reseed borra las filas de transaction_documents y trata de borrar cada archivo "best-effort" (el error se traga): en S3, sin DeleteObject, los objetos quedan huérfanos en el bucket aunque su fila se haya ido. Y el backup previo de demo:reseed --wipe-only escribe en el mismo bucket, bajo backups/, lo que el PutObject sí permite, y con datos personales: el JSON completo de transactions (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 toca backups/: 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:ListBucket que faltara convertiría el 404 controlado en un 500.
  • Una trampa de despliegue permanente mientras deploy-staging.yml renderice la task definition desde la última revisión de la familia: después de cada apply que toque ecs o waf se 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' de TransactionDocumentService::store(): el adaptador manda la ACL igual.
  • Plan B, solo de configuración y sin tocar código de la subida: en la rama s3 del disco documents de config/filesystems.php, 'options' => ['ACL' => 'bucket-owner-full-control']. El adaptador toma options.ACL antes que la visibilidad (hay un test que captura el PutObject y lo fija: sale private por defecto y bucket-owner-full-control con 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, sin apply.
  • Plan C, si ni eso: escribir con el cliente del SDK (Storage::disk(...)->getClient()->putObject(...)) y sin ACL, solo para el disco s3 (comentario de store()).
  • Un permiso que no está y se sospecha: s3:PutObjectAcl. El adaptador manda x-amz-acl en cada PutObject y 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 da AccessDenied aunque el simulador de IAM diga allowed para PutObject, es el primer sospechoso; agregarlo, acotado a bucket/*, 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 Lock ni 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.yml corre 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 primer apply allí.
  • Cualquier operador con transacciones:write en 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, sin DOCUMENTS_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ódulo ecs conserve las tres variables, el próximo terraform apply las 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 a s3. 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 ​

Documentación viva — se actualiza junto con el código, no es un anexo aparte.