# Implementación de Seguridad - Sistema de Inventario Forestal Guatemala

## Resumen

Este documento describe la implementación completa del sistema de seguridad y manejo de archivos para el SIF-GT V1.0, cumpliendo con los requisitos 4.3, 4.4 y 4.5 del sistema.

## Funcionalidades Implementadas

### 1. Validación de Tipos y Tamaños de Archivos PDF

**Archivo:** `api/utils/FileValidator.php`

**Características:**
- Validación de tipos MIME permitidos (application/pdf, application/x-pdf)
- Verificación de extensiones de archivo (.pdf únicamente)
- Validación de tamaño de archivo (1KB mínimo, 5MB máximo)
- Verificación de magic bytes para confirmar que es un PDF válido
- Validación de nombres de archivo seguros
- Detección de caracteres peligrosos en nombres

**Métodos principales:**
```php
FileValidator::validateUpload($file)          // Validación completa
FileValidator::generateSecureFileName()       // Nombres seguros
FileValidator::validateUploadDirectory()      // Validación de directorios
```

### 2. Sistema de Almacenamiento Seguro de Documentos

**Archivo:** `api/utils/SecureFileManager.php`

**Características:**
- Almacenamiento en directorio protegido (`uploads/documents/`)
- Generación automática de nombres únicos y seguros
- Verificación de espacio de almacenamiento disponible
- Establecimiento de permisos seguros (0640)
- Creación automática de archivos de protección (.htaccess, index.php)
- Limpieza de archivos huérfanos

**Métodos principales:**
```php
$fileManager->uploadFile()      // Subida segura
$fileManager->serveFile()       // Descarga controlada
$fileManager->deleteFile()      // Eliminación segura
$fileManager->cleanOrphanedFiles() // Limpieza automática
```

### 3. Validación de Permisos para Descarga de Documentos

**Implementación por roles:**
- **Administrador:** Acceso completo a todos los documentos
- **Regente:** Acceso a documentos de sus proyectos
- **Técnico de Campo:** Sin acceso a documentos

**Verificaciones de seguridad:**
- Autenticación JWT válida
- Verificación de rol de usuario
- Validación de permisos por proyecto
- Sanitización de nombres de archivo
- Verificación de existencia y tipo de archivo
- Headers seguros para descarga

### 4. Headers de Seguridad en .htaccess

**Archivo:** `.htaccess`

**Headers implementados:**
```apache
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: [política completa]
Permissions-Policy: [política restrictiva]
```

**Protecciones adicionales:**
- Bloqueo de patrones de ataque SQL injection y XSS
- Prevención de listado de directorios
- Protección de archivos sensibles
- Compresión y cache optimizado
- Redirección segura para React Router

### 5. Sistema de Logs para Auditoría de Accesos

**Archivo:** `api/utils/SecurityLogger.php`

**Tipos de logs:**
- **file_access:** Subida, descarga, eliminación de archivos
- **auth:** Intentos de autenticación exitosos y fallidos
- **security:** Violaciones de seguridad y actividad sospechosa
- **system:** Errores del sistema y eventos importantes

**Características:**
- Rotación automática de logs (10MB máximo por archivo)
- Retención configurable (30 días por defecto)
- Captura de IP real del cliente
- Información detallada de contexto
- Niveles de severidad (low, medium, high, critical)

**Métodos principales:**
```php
SecurityLogger::logFileAccess()         // Acceso a archivos
SecurityLogger::logAuthAttempt()        // Intentos de login
SecurityLogger::logSecurityViolation()  // Violaciones de seguridad
SecurityLogger::getSecurityStats()      // Estadísticas de seguridad
```

## Estructura de Directorios Protegidos

```
uploads/
├── .htaccess                    # Protección general
├── index.php                   # Prevención listado
└── documents/
    ├── .htaccess               # Protección específica PDFs
    ├── index.php               # Prevención listado
    └── [archivos_pdf]          # Documentos almacenados

logs/
├── .htaccess                   # Protección logs
├── file_access_YYYY-MM-DD.log  # Logs de acceso a archivos
├── auth_YYYY-MM-DD.log         # Logs de autenticación
├── security_YYYY-MM-DD.log     # Logs de seguridad
└── system_YYYY-MM-DD.log       # Logs del sistema

api/config/
├── .htaccess                   # Protección configuración
├── database.php                # Configuración BD
└── config.php                  # Configuración general
```

## API de Seguridad

**Endpoints disponibles (solo Administradores):**

### GET /api/security/stats
Obtiene estadísticas de seguridad del sistema.

**Respuesta:**
```json
{
  "success": true,
  "data": {
    "auth_attempts": 150,
    "failed_auth": 5,
    "file_accesses": 89,
    "security_violations": 2,
    "unique_ips": ["192.168.1.1", "10.0.0.1"],
    "top_violations": {
      "unauthorized_access": 1,
      "invalid_file": 1
    }
  }
}
```

### GET /api/security/audit
Realiza auditoría completa del sistema.

**Respuesta:**
```json
{
  "success": true,
  "data": {
    "timestamp": "2025-07-23 15:00:00",
    "directories": { /* estado directorios */ },
    "files": { /* estado archivos críticos */ },
    "permissions": { /* permisos PHP */ },
    "configuration": { /* configuración seguridad */ },
    "security_score": 95
  }
}
```

### POST /api/security/cleanup
Limpia archivos huérfanos y logs antiguos.

**Respuesta:**
```json
{
  "success": true,
  "data": {
    "orphaned_files": 3,
    "old_logs": "Logs antiguos eliminados",
    "errors": []
  }
}
```

## Configuración de Seguridad

### Validación de Archivos
```php
// Configuración en FileValidator.php
private static $allowedMimeTypes = [
    'application/pdf',
    'application/x-pdf'
];
private static $maxFileSize = 5 * 1024 * 1024; // 5MB
private static $minFileSize = 1024; // 1KB
```

### Almacenamiento Seguro
```php
// Configuración en SecureFileManager.php
private $maxStorageSize = 100 * 1024 * 1024; // 100MB total
private $allowedUsers = ['Administrador', 'Regente'];
```

### Logs de Seguridad
```php
// Configuración en SecurityLogger.php
private static $maxLogSize = 10 * 1024 * 1024; // 10MB
private static $maxLogFiles = 5; // 5 archivos por tipo
```

## Medidas de Seguridad Implementadas

### 1. Protección contra Ataques Comunes
- **SQL Injection:** Prepared statements en todas las consultas
- **XSS:** Headers de protección y sanitización de entrada
- **CSRF:** Validación de tokens JWT
- **Path Traversal:** Sanitización de nombres de archivo
- **File Upload Attacks:** Validación estricta de tipos y contenido

### 2. Autenticación y Autorización
- **JWT Tokens:** Autenticación stateless segura
- **Roles y Permisos:** Control granular de acceso
- **Sesiones Seguras:** Configuración de cookies seguras
- **Rate Limiting:** Protección contra ataques de fuerza bruta

### 3. Protección de Datos
- **Hashing de Contraseñas:** bcrypt con salt automático
- **Encriptación de Datos Sensibles:** OpenSSL para datos críticos
- **Validación de Entrada:** Sanitización de todos los inputs
- **Escape de Salida:** Prevención de inyección de código

### 4. Monitoreo y Auditoría
- **Logs Detallados:** Registro de todas las actividades críticas
- **Alertas de Seguridad:** Notificación de violaciones
- **Estadísticas de Uso:** Análisis de patrones de acceso
- **Auditoría Automática:** Verificación periódica del sistema

## Testing y Verificación

**Archivo de pruebas:** `test_security_implementation.php`

**Pruebas incluidas:**
1. Verificación de estructura de directorios
2. Validación de archivos de seguridad
3. Test de FileValidator
4. Test de SecurityLogger
5. Test de SecureFileManager
6. Verificación de headers de seguridad
7. Verificación de extensiones PHP
8. Configuración de seguridad PHP
9. Permisos de archivos
10. Resumen de implementación

## Mantenimiento y Actualizaciones

### Tareas Automáticas
- Rotación de logs cuando superan 10MB
- Limpieza de logs antiguos (>30 días)
- Eliminación de archivos huérfanos
- Verificación de integridad de archivos

### Tareas Manuales (Administrador)
- Revisión periódica de estadísticas de seguridad
- Auditoría completa del sistema
- Actualización de configuraciones de seguridad
- Análisis de logs de violaciones

## Cumplimiento de Requisitos

### Requisito 4.3 - Gestión de Documentos del Proyecto
✅ **Implementado:** Sistema completo de carga, almacenamiento y descarga segura de documentos PDF con validación de permisos por rol.

### Requisito 4.4 - Validación de Permisos
✅ **Implementado:** Control granular de acceso basado en roles (Administrador, Regente, Técnico) con validación de permisos para cada operación.

### Requisito 4.5 - Seguridad de Archivos
✅ **Implementado:** Validación completa de tipos de archivo, almacenamiento seguro, headers de seguridad y sistema de auditoría completo.

## Conclusión

La implementación de seguridad y manejo de archivos está completa y cumple con todos los requisitos especificados. El sistema proporciona:

- **Seguridad robusta** contra ataques comunes
- **Control de acceso granular** basado en roles
- **Auditoría completa** de todas las actividades
- **Mantenimiento automático** del sistema
- **Monitoreo continuo** de la seguridad

El sistema está listo para producción con todas las medidas de seguridad implementadas y probadas.