# DIRECTRICES MAESTRAS DE INGENIERÍA Y SEGURIDAD (ANTIGRAVITY) > **Propósito del Sistema:** Este documento constituye la fuente de verdad arquitectónica y de seguridad para cualquier modelo de IA que opere en este proyecto. Todas las respuestas, refactorizaciones y generaciones de código deben cumplir estrictamente con estas reglas sin excepción. --- ## 1. Arquitectura Modular y Escalabilidad (Bajo Acoplamiento) * **Arquitectura Basada en Dominios/Features (Vertical Slicing):** Organiza el código por módulos funcionales independientes en lugar de capas horizontales gigantes. Si se debe modificar o ampliar una función, el cambio debe estar contenido en su propio módulo sin necesidad de explorar o alterar múltiples archivos externos. * **Principio de Responsabilidad Única (SRP):** Cada archivo, clase, componente o función debe tener una única responsabilidad clara y un motivo único para cambiar. * **Puntos de Entrada Únicos (Barrel Files / Interfaces):** Cada módulo debe exponer únicamente lo necesario a través de una interfaz clara, manteniendo su lógica interna encapsulada. * **Límite de Complejidad:** Ninguna función debe superar las 40-50 líneas de código ni tener más de 3 niveles de anidación (usar *Guard Clauses* / retornos tempranos). --- ## 2. Código Limpio, Tipado Fuerte y Plantillas (Contratos) * **Nomenclatura Semántica y Auto-descriptiva:** * Variables y propiedades: Sustantivos claros que indiquen qué contienen (`userAuthenticationToken`, `maxUploadSizeInBytes`). Prohibido usar abreviaturas ambiguas (`d`, `temp`, `val`, `obj`). * Funciones y métodos: Verbos de acción que describan exactamente qué hacen (`validateAndSanitizeUserInput()`, `encryptSensitivePayload()`). * Booleanos: Prefijos claros como `is`, `has`, `can`, `should` (`isSessionActive`, `hasValidMetadata`). * **Plantillas, Interfaces y Contratos Estrictos (DTOs / Schemas):** * Todo objeto, petición, respuesta o estructura de datos reutilizable **debe** tener una plantilla, interfaz o esquema base previamente declarado en un archivo de contratos/tipos del módulo. * Prohibido el uso de tipos dinámicos o comodines (`any`, `mixed`, objetos sin estructura definida). Toda función debe declarar explícitamente el tipo de sus parámetros de entrada y su valor de retorno. * **Documentación Estratégica (JSDoc / Docstrings):** * Toda función, clase, plantilla o interfaz debe incluir un bloque de documentación superior que explique: 1. **Qué hace** la función. 2. **Qué importancia o impacto tiene** dentro del flujo del sistema. 3. Parámetros esperados (`@param`), valor de retorno (`@returns`) y posibles errores que lanza (`@throws`). --- ## 3. Validación Doble Capa y Guards Robustos (Zero-Trust) * **Regla de Oro:** El Front-end valida para mejorar la experiencia de usuario (UX); el Back-end valida por seguridad e integridad. **Jamás confiar en el Front-end.** * **Flujo en Front-end (Pre-vuelo):** * Antes de emitir cualquier petición, validar formato, tipos de datos, longitudes mínimas/máximas, campos obligatorios y coherencia lógica. * Garantizar que el payload de la petición esté estrictamente estructurado según el contrato/plantilla del endpoint. * **Guards y Middlewares en Back-end (Barrera de Entrada):** * Ningún controlador o función que guarde datos o ejecute procesos de negocio puede iniciarse sin antes pasar por un **Guard de Autenticación/Autorización** y un **Middleware de Validación de Esquema**. * Si el payload incluye campos no declarados en la plantilla (Mass Assignment), el Guard debe rechazar la petición inmediatamente o purgar los campos intrusos antes de tocar la lógica de negocio. --- ## 4. Seguridad, Criptografía y Privacidad del Usuario * **Cero Hardcoding y Cero Secretos Expuestos:** * Prohibido escribir credenciales, claves privadas, tokens, URLs de conexión, sales criptográficas o valores de configuración estáticos directamente en el código. * Todo valor sensible o configurable debe inyectarse mediante variables de entorno (`.env`) validadas al iniciar la aplicación. * **Criptografía de Alto Rendimiento y Difícil Vulnerabilidad:** * **Contraseñas:** Uso exclusivo de algoritmos resistentes a GPU/ASIC como **Argon2id** (preferido) o **bcrypt** (factor de costo $\ge 12$). Prohibido MD5, SHA-1 o SHA-256 sin sal para contraseñas. * **Datos Sensibles en Reposo (PII):** Encriptación simétrica autenticada mediante **AES-256-GCM** o **ChaCha20-Poly1305**, utilizando vectores de inicialización (IV / Nonce) únicos por cada operación. * **Privacidad por Diseño:** Enmascarar o anonimizar datos personales antes de procesarlos en analíticas o vistas parciales. * **Prevención de Inyecciones y Ejecución de Scripts:** * **SQL / NoSQL Injection:** Uso obligatorio de consultas parametrizadas (Prepared Statements) u ORMs con parámetros vinculados. Prohibido concatenar o interpolar variables directamente en cadenas de consulta. * **XSS (Cross-Site Scripting) e Inyección de Texto:** Sanitizar y escapar toda entrada de texto en Back-end y Front-end. Implementar políticas estrictas de `Content-Security-Policy (CSP)` para bloquear la ejecución de scripts en línea o de orígenes no autorizados. --- ## 5. Diseño e Integridad Estricta de Base de Datos * **Tipado y Límites Estrictos de Columnas/Campos:** * Definir el tipo de dato exacto y el tamaño mínimo/máximo en el esquema de la base de datos (`VARCHAR(150)`, `INT UNSIGNED`, `UUID`, `TIMESTAMP`). * **Prohibición de Base64 en Campos de Texto:** Queda estrictamente prohibido almacenar archivos, imágenes o payloads pesados codificados en Base64 dentro de campos de texto (`VARCHAR`, `TEXT`, `JSON`). Esto degrada el rendimiento, infla el almacenamiento y genera vulnerabilidades de denegación de servicio (DoS). Los archivos deben ir a un almacenamiento de objetos (S3, disco seguro aislado) y en la base de datos solo se guarda la ruta/referencia validada y sus metadatos. * **Relaciones Sólidas y Sin Bloqueos (Deadlocks):** * Toda relación debe contar con claves foráneas (`FOREIGN KEY`) explícitas, índices en las columnas de búsqueda/unión (`INDEX`) y reglas claras de integridad referencial (`ON DELETE RESTRICT` o `CASCADE` según el dominio). * Las operaciones que modifiquen múltiples tablas deben ejecutarse dentro de **Transacciones Atómicas (ACID)** cortas y optimizadas para evitar bloqueos en el futuro. --- ## 6. Manejo Seguro de Archivos y Contenido Multimedia Tanto en Front-end (pre-validación) como en Back-end (validación definitiva en el Guard), todo archivo subido debe superar las siguientes pruebas antes de ser procesado o almacenado: 1. **Verificación de Peso:** Definir límites estrictos de tamaño mínimo (evitar archivos vacíos de $0\text{ bytes}$) y máximo según el tipo de archivo. 2. **Verificación Real del Tipo (Magic Bytes):** En Back-end, no confiar únicamente en la extensión del archivo (`.jpg`, `.pdf`) ni en el `Content-Type` de la cabecera HTTP. Validar la firma binaria real del archivo (*Magic Numbers*). 3. **Limpieza de Metadatos y Sanitización:** * Eliminar metadatos sensibles (como datos EXIF de geolocalización en imágenes) antes de guardar para proteger la privacidad del usuario. * Renombrar el archivo con un identificador único seguro (`UUIDv4` o hash) para evitar ataques de *Path Traversal* (ej. `../../script.sh`) o colisiones de nombres. * Almacenar fuera del directorio público de ejecución de scripts. --- ## 7. Registro de Errores (Logging) y Observabilidad * **Logs Estructurados y Claros:** * Registrar errores con contexto útil para depuración: `timestamp`, `nivel (ERROR, WARN, INFO)`, `módulo/archivo`, `código de error interno`, `trace_id` de la petición y mensaje descriptivo de la causa. * **Sanitización de Logs:** * **Nunca** imprimir en los logs contraseñas, tokens de sesión, claves de API, números de tarjetas o datos personales crudos. * **Respuestas Seguras al Cliente:** * El usuario final o el Front-end jamás deben recibir trazas de pila (*Stack Traces*), errores crudos de SQL o rutas internas del servidor. Devolver mensajes de error estandarizados, amigables y códigos HTTP semánticos (`400`, `401`, `403`, `422`, `500`). --- ## 8. Reglas de No-Destrucción para el Agente IA (Antigravity) Al generar, editar o refactorizar código en este proyecto, el modelo de IA debe acatar las siguientes restricciones operativas: 1. **Prohibido el Desarrollo Destructivo:** Nunca elimines funciones existentes, validaciones, comentarios importantes o lógica de negocio a menos que se solicite explícitamente y se haya verificado que ningún otro módulo depende de ello. 2. **Prohibido el Uso de Placeholders en Código Existente:** No reemplaces bloques de código funcional con comentarios perezosos como `// ... resto del código aquí` o `// implementar lógica después` si eso rompe el archivo actual. 3. **Retrocompatibilidad:** Si necesitas ampliar una función o plantilla existente, hazlo manteniendo la compatibilidad con los llamados actuales (por ejemplo, usando parámetros opcionales con valores por defecto seguros o creando una versión extendida bien documentada). 4. **Migraciones de Base de Datos Seguras:** Nunca generes comandos `DROP TABLE`, `TRUNCATE` o alteraciones destructivas de columnas en producción. Todo cambio estructural en la base de datos debe plantearse mediante migraciones incrementales y reversibles (`up` / `down`). 5. **Verificación Previa a la Acción:** Antes de proponer un cambio, identifica qué plantilla/interfaz rige los datos, qué Guard protege la ruta y cómo afecta al módulo actual, asegurando que la modificación sea limpia, aislada y libre de efectos secundarios.