chore: import DH V2 D5.6.4 production baseline

2026-09-05 10:12:35 -03:00
commit 82213e72f5
757 changed files with 84218 additions and 0 deletions
@@ -0,0 +1,79 @@
+# DH Inspección V2 — Fase A2
+
+## Versión
+
+```text
+v0.2.1 · Fase A2 · Autenticación y sesiones
+```
+
+La leyenda se muestra en el footer del frontend. El health de la API también
+informa `version: 0.2.1` y `phase: A2`.
+
+## Endpoints
+
+```text
+POST /api/v3/auth/login
+POST /api/v3/auth/refresh
+POST /api/v3/auth/logout
+GET  /api/v3/auth/me
+POST /api/v3/auth/change-password
+```
+
+`GET /api/v3/health` continúa siendo el único endpoint público sin datos de
+negocio.
+
+## Seguridad
+
+- passwords con Argon2id;
+- respuesta genérica para credenciales inválidas;
+- 5 intentos fallidos y 15 minutos de bloqueo por defecto;
+- rate limiting por IP;
+- access token JWT HS256 corto;
+- refresh token opaco, rotativo y persistido únicamente como HMAC-SHA256;
+- cookies `HttpOnly`, `Secure` y `SameSite=Strict`;
+- defensa CSRF de doble envío para operaciones mutables con cookies;
+- validación estricta del origen web configurado;
+- sesiones revocables y detección de reutilización;
+- sanitización de passwords, hashes, tokens, cookies y secretos en auditoría;
+- `X-Request-ID` en respuestas y eventos de auditoría.
+
+El navegador no utiliza `localStorage` ni `sessionStorage` para tokens.
+
+## Migración A2
+
+```text
+PhaseA2SessionSecurityIndexes1786548005000
+```
+
+Agrega índices para `users.locked_until` y
+`auth_sessions.replaced_by_session_id`. No elimina ni transforma datos A1.
+
+## Primer administrador
+
+La CLI `npm run bootstrap:admin`:
+
+- funciona únicamente en una terminal interactiva;
+- oculta la contraseña mientras se escribe;
+- exige entre 12 y 128 caracteres;
+- evita crear un segundo administrador por bootstrap;
+- usa una transacción y un advisory lock para impedir ejecuciones simultáneas;
+- asigna el rol `admin` sembrado en A1;
+- registra el evento `SYSTEM_BOOTSTRAP_ADMIN_CREATED`;
+- nunca imprime la contraseña ni su hash.
+
+## Variables nuevas
+
+```text
+WEB_ORIGIN
+JWT_ACCESS_SECRET
+REFRESH_TOKEN_PEPPER
+ACCESS_TOKEN_TTL_SECONDS
+REFRESH_TOKEN_TTL_SECONDS
+AUTH_MAX_LOGIN_ATTEMPTS
+AUTH_LOCKOUT_SECONDS
+ACCESS_COOKIE_NAME
+REFRESH_COOKIE_NAME
+CSRF_COOKIE_NAME
+```
+
+Los dos secretos deben ser diferentes y tener al menos 64 caracteres.