# Arquitectura Técnica y Seguridad del Módulo

Este documento describe los principios de arquitectura, seguridad y rendimiento aplicados en el módulo.

---

## 1. Volcado SQL en PHP Puro (Sin `mysqldump`)

### El Problema
La mayoría de hostings compartidos (como BanaHosting, Hostinger, Siteground) bloquean las funciones de ejecución del sistema operativo:
`exec()`, `shell_exec()`, `system()`, `passthru()`. Además, la ruta a `mysqldump` suele ser inaccesible o restringida por open_basedir.

### La Solución Implementada
El motor `generarVolcadoSQL(PDO $pdo, $fh)`:
1. Establece aislamiento de transacción consistente (`START TRANSACTION WITH CONSISTENT SNAPSHOT`).
2. Obtiene la estructura de cada tabla con `SHOW CREATE TABLE`.
3. Lee los registros usando consultas no bufferizadas (`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY = false`) para **no saturar la memoria RAM** de PHP, incluso con cientos de miles de registros.
4. Exporta columnas binarias en formato hexadecimal (`0x...`) para evitar corrupción de codificación UTF-8.
5. Agrupa los valores en bloques `INSERT INTO ... VALUES (...), (...);` de 200 filas para que la posterior importación sea ultrarrápida.
6. Ajusta `time_zone = '+00:00'` para exportar marcas de tiempo estándar UTC independientes del servidor.

---

## 2. Motor de Restauración por Flujo (Streaming Parser)

### El Problema
Los archivos SQL pueden pesar 20 MB o más. Ejecutar `$pdo->exec(file_get_contents('dump.sql'))` suele fallar por `memory_limit` o por exceder `max_allowed_packet`. Además, partir por `;` directamente rompe registros que contienen punto y coma dentro de texto (ej. observaciones o bitácora).

### La Solución Implementada
La función `restaurarDesdeSQL(PDO $pdo, string $rutaArchivoSQL)`:
* Lee el archivo línea por línea con `fgets()`.
* Utiliza una máquina de estados para detectar si un carácter `;` está dentro de comillas (`'...'`, `"..."`), comentarios (`--`, `#`, `/* ... */`) o si es el delimitador real de la consulta.
* Cierra los cursores no bufferizados tras cada ejecución (`closeCursor()`).
* Desactiva temporalmente la revisión de claves foráneas (`SET FOREIGN_KEY_CHECKS = 0;`) y la reactiva al finalizar en un bloque `finally`.

---

## 3. Seguridad Contra Ataques de "Zip Slip" y Carga de Archivos

Al descomprimir archivos ZIP en el servidor, existe el riesgo de que un atacante manipule los nombres internos dentro del ZIP (ejemplo: `../../index.php`) para sobrescribir archivos del sistema.

### Medidas de Blindaje:
1. **Sanitización Estricta de Rutas:**
   * Se evalúa cada entrada con `basename($nombre)` y se descartan rutas que contengan `../` o `..\`.
2. **Lista Blanca de Extensiones:**
   * En restauración de fotos: solo se admiten `jpg`, `jpeg`, `png`, `webp`, `gif`.
   * En restauración completa: solo se admiten imágenes, documentos (`pdf`, `svg`), configuraciones (`json`) y base de datos (`sql`).
   * **Archivos ejecutables (`.php`, `.phtml`, `.exe`, `.sh`, `.htaccess`) son descartados y nunca extraídos.**
3. **Protección CSRF:**
   * Todas las peticiones POST requieren un token generado criptográficamente (`bin2hex(random_bytes(32))`) y validado con `hash_equals()`.
4. **Verificación de Superadministrador en Base de Datos:**
   * No se confía solo en variables de sesión modificables; se consulta el `id` real en la tabla `usuarios`.
5. **Barrera de Confirmación Activa:**
   * El usuario debe escribir explícitamente la palabra **`RESTAURAR`** en mayúsculas para ejecutar la operación.

---

## 4. Concurrencia y Rendimiento

* **`session_write_close()`:** Antes de iniciar la compresión ZIP o el volcado SQL, se cierra la sesión PHP para no bloquear las solicitudes de otros usuarios o de otras pestañas en el mismo navegador mientras dura la descarga o restauración.
* **Archivos Temporales Auto-Eliminables:** Se registran con `register_shutdown_function()` para asegurar que se borren del servidor incluso si el usuario cancela la descarga a mitad de camino.
