project.linkedcorp.net/docs/SEGURIDAD-Y-CALIDAD.md

Seguridad y Calidad — project.linkedcorp.net

Copia ajustada de la plantilla del grupo (project-md-templates/SEGURIDAD-Y-CALIDAD.md). Léela antes de escribir código de una nueva funcionalidad y úsala como checklist antes de mergear.

Diferencia con la plantilla original: la plantilla asume multi-empresa (empresaId por tenant). Este proyecto es de una sola empresa (single-company), así que el "aislamiento" que aplica aquí no es entre empresas sino entre usuarios y su alcance por rol: qué proyectos/ actividades puede ver o tocar cada rol (ver tabla de roles en SPEC.md).

Regla de oro: la seguridad primero; luego, cero duplicación; luego, facilidad de revisión y de extender.

---

1. Seguridad (NO negociable)

1.1 Alcance por rol (equivalente al aislamiento multi-tenant)

• NUNCA confíes en un userId/role que venga en el body/query. El usuario y su rol salen SIEMPRE del token (req.currentUser), nunca del body.
• Reglas de alcance por rol (ver SPEC.md):
  • Colaborador: solo puede ver/actualizar actividades y subtareas donde es responsible_user_id, y comentar en los proyectos donde es miembro.
  • Coordinador/Líder: solo puede crear/editar proyectos donde es owner_user_id o miembro (project_members), y las actividades de esos proyectos.
  • Jefe de TI y Administrador: sin restricción de alcance.
  • Consultor: solo lectura en todo, ningún endpoint de escritura le responde 2xx.
• Antes de update/delete/get by id de un recurso, verificar que el usuario tiene alcance sobre ese recurso (por rol + pertenencia al proyecto) y responder 404 si no corresponde (no 403, para no revelar existencia a quien no debería ni saber que existe).
• Los IDs relacionados que llegan en el body (projectId, activityId, dependsOnActivityId, etc.) deben validarse: que existan y que el usuario tenga alcance sobre ellos antes de usarlos.

1.2 Autenticación y autorización

• Toda ruta no pública pasa por middleware de auth (backend/src/middleware/auth.js).
• Revalida en CADA request que la cuenta siga activa (users.is_active). Un JWT válido por firma NO basta: desactivar un usuario debe cortarle el acceso al instante, no cuando expire el token.
• La autorización del frontend es solo UX (ocultar botones/menús); el backend re-verifica rol y alcance en cada endpoint. El usuario en localStorage es manipulable.

1.3 Secretos

• Contraseñas: bcrypt (cost ≥ 12). Nunca en logs ni respuestas.
• .env fuera de git. El arranque del backend debe abortar en producción si JWT_SECRET o las credenciales de BD son valores por defecto/vacíos.
• No exponer rutas absolutas del filesystem del servidor en respuestas de API.

1.4 Entrada y datos

• SQL siempre parametrizado (placeholders ?). Nunca concatenar entrada del usuario. Las cláusulas IN (...) dinámicas se arman con placeholders, no con el valor.
• Nombres de columna/orden dinámicos SOLO desde una whitelist del servidor, jamás desde el query string tal cual.
• Uploads (attachments): validar tamaño y MIME por whitelist. El nombre/ruta del archivo lo genera el servidor (evita path traversal); nunca usar el nombre que manda el cliente como ruta.
• Fechas: validar coherencia (due_date >= start_date, etc.) en el servicio, no solo en el frontend.

1.5 Errores, logs y límites

• Los 5xx ocultan el detalle al cliente en producción.
• Rate limiting en POST /api/auth/login.
• Sirviendo la SPA: CSP (helmet) — script-src 'self' (sin inline), style-src 'self' 'unsafe-inline', img-src 'self' data: blob:, object-src 'none'.
• La SPA de producción recibe CSP desde frontend/public/serve.json (el servidor serve copia ese archivo al build); el backend usa Helmet en /api. En Vite dev no se aplica el header del servidor serve, para permitir el módulo de recarga de React. El logo de empresa solo admite PNG/JPG/WEBP comprobados por firma y se entrega con nosniff.

1.6 Frontend / caché

• El JWT en localStorage es un trade-off aceptado; mantener CSP y sanitización.
• Si en el futuro se agrega caché offline, purgarla en logout y en 401.

---

2. Cero duplicación (procesos, flujos y funciones)

• Un helper vive en un solo lugar. Antes de escribir una función, buscar si ya existe.
• Helpers compartidos en backend/src/utils/ (fechas, cálculo de progress_pct, cálculo de estado de vencimiento 🟢/🟡/🔴) y frontend/src/services/lib (formateadores, fmtDate, roleLabel).
• El patrón CRUD repetido (listar/buscar/crear/editar/borrar) se abstrae en un hook reutilizable en el frontend (useAsync/useCrud); loading/try-catch/ContentDialog de error, en un solo lugar.
• Una sola capa de API en el frontend (src/services/api.js con api.get/post/put/delete).

---

3. Orden, revisión y facilidad de extender

• Arquitectura backend por módulo: routes → controller → service → repository → db. Un módulo nuevo replica esa forma (ver projects/activities como plantilla).
• Un archivo, una responsabilidad. Si un service crece mucho o mezcla temas, partirlo.
• Sin código muerto.
• Convención única de respuestas: { success, data, error } en todos los endpoints; listados con { items, total } dentro de data.
• El cálculo de progress_pct (actividad y proyecto) vive en un solo lugar (activities/service.js y projects/service.js), nunca duplicado en el frontend como fuente de verdad — el frontend solo muestra el valor que devuelve la API.

---

4. Checklist antes de mergear / desplegar

Seguridad

• ¿El usuario/rol sale del token, no del body?
• ¿update/delete/get-by-id verifican alcance por rol (404 si no corresponde)?
• ¿La ruta tiene el middleware de auth/rol correcto? ¿Se revalida is_active?
• ¿SQL parametrizado (incl. IN)? ¿MIME/tamaño validados en adjuntos?
• ¿Secretos fuera de respuestas/logs? ¿5xx sin datos internos?

Calidad

• ¿Reutilicé helpers existentes en vez de duplicar?
• ¿Borré el código muerto que este cambio deja atrás?
• ¿El archivo/módulo sigue el patrón y no se volvió inmanejable?

Verificación

• Build/backend arrancan sin errores; smoke test del flujo tocado en dev.
• Migraciones idempotentes; respaldo antes de aplicarlas en producción (cuando exista deploy).