@bi-analytics/arness-back 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ Formato basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y
 
 ## [Sin publicar]
 
+### Agregado
+- **Última LTS de Node** (ADR 0015): `init.sh` compara `.nvmrc` con la última LTS de `nodejs.org` y advierte `toolchain.node-lts` si hay un major más nuevo; sin red lo omite. `NODE_LTS_VERSION` fija la LTS de referencia (`off` desactiva). Playbook `update-node-lts.md`: el agente analiza el impacto, lo presenta y actualiza solo con aprobación humana. AGENTS.md §0 y §16, agente `lider` y pistas de `doctor`.
+- **Endurecimiento de la autenticación** (ADR 0017), sin dependencias nuevas:
+  - plantillas `templates/security/` (`LoginAttemptLimiter`, `securityHeaders()`, `sessionClaims` / `isSessionExpired` y `SecurityModule`) y `templates/config/auth.ts` (`parseAuthConfig`, bloque `auth` de la configuración), con specs;
+  - límite de intentos por IP en `/auth/login` y `/monitor/login` (`429 TOO_MANY_ATTEMPTS` con `Retry-After`);
+  - vida máxima de la sesión con `auth_time` (`401 SESSION_EXPIRED`);
+  - cabeceras de seguridad en toda respuesta;
+  - variables `AUTH_LOGIN_MAX_ATTEMPTS`, `AUTH_LOGIN_WINDOW_SECONDS`, `AUTH_SESSION_MAX_AGE_SECONDS` y `HTTP_TRUST_PROXY_HOPS`;
+  - `init.sh`: `security.headers`, `security.trust-proxy`, `security.login-rate-limit`, y `security.session-max-age`; tres novedades de seguridad en `doctor`;
+  - `auth.e2e-spec.ts` exige que la cookie del monitor y el refresh token no sirvan como `Bearer`.
+
+### Cambiado
+- El monitor comparte el límite de intentos del login: `templates/monitor/monitor.controller.ts` y `templates/e2e/monitor.e2e-spec.ts` usan `LoginAttemptLimiter`.
+- `arness sync` solo anuncia las novedades hasta la versión que instala (antes también mostraba las de versiones posteriores presentes en el catálogo).
+- **Evolutivo con hora y responsable** (ADR 0016): cada entrada de `docs/EVOLUTIVO.md` lleva fecha, hora y zona de Bogotá (`AAAA-MM-DD HH:mm -0500`) y el responsable (`git config user.name`). Plantilla, AGENTS.md §12, `new-endpoint`, `review.md`, `revisor` y `nest-base`.
+
+### Para proyectos existentes
+- `init.sh` puede mostrar la advertencia nueva `toolchain.node-lts`. No rompe nada: el agente propone el análisis y solo actualiza Node si lo apruebas. Si no, queda en `docs/PENDIENTES.md`.
+- Las entradas existentes de `docs/EVOLUTIVO.md` no se reescriben: el formato nuevo aplica desde la siguiente entrega. Verifica que cada persona tenga `git config user.name`.
+- **Seguridad:** `init.sh` mostrará `security.*` nuevos como advertencias y `pnpm arness doctor` los lista con sus pasos. Ninguna impide arrancar: los secretos actuales siguen sirviendo. Al adoptar la vida máxima de la sesión, los usuarios con un refresh token anterior deberán volver a iniciar sesión. Detrás de Azure App Service, define `HTTP_TRUST_PROXY_HOPS=1`. Avisa a frontend de `429 TOO_MANY_ATTEMPTS` y `401 SESSION_EXPIRED`.
+
 ## [0.2.0] - 2026-10-23
 
 ### Cambiado

package/bin/arness.mjs

@@ -319,7 +319,7 @@ function cmdSync(opts) {
     for (const rel of removed) showDiff(root, rel, null);
   }
   const incoming = parseNovelties(next.get(NOVELTIES)?.content.toString('utf8')).filter(
-    (n) => compareVersions(n.since, manifest.version) > 0,
+    (n) => compareVersions(n.since, manifest.version) > 0 && compareVersions(n.since, PKG.version) <= 0,
   );
   if (incoming.length) {
     log(`\nNovedades desde ${manifest.version} (no se activan solas; detalle y pasos: arness doctor):`);
@@ -393,7 +393,7 @@ const DOCTOR_HINTS = {
   git: 'Usa un repo git propio; si hay secretos versionados, sácalos del índice (git rm --cached) y rota las credenciales.',
   package: 'Repo fuente del paquete: revisa bin/, CHANGELOG.md y docs/adr/.',
   install: 'Instala o actualiza el paquete (README de @bi-analytics/arness-back) y ejecuta arness sync.',
-  toolchain: 'Skill nest-base §1 y §4: .nvmrc, packageManager, lockfile y scripts.',
+  toolchain: 'Skill nest-base §1 y §4: .nvmrc, packageManager, lockfile y scripts. Nueva LTS de Node: harness/playbooks/update-node-lts.md (análisis y aprobación humana).',
   structure: 'AGENTS.md §4 y skill nest-base §4–§5. Adóptalo cuando convenga; no bloquea.',
   sql: 'AGENTS.md §6: SQL solo en *.sql.ts y sin escrituras.',
   docs: 'AGENTS.md §12: copia harness/skills/nest-base/templates/docs/ (EVOLUTIVO.md solo avance; PENDIENTES.md lo abierto).',

package/harness/AGENTS.md

@@ -15,6 +15,7 @@ Por defecto **los hallazgos son advertencias** (`⚠`, exit 0): el proyecto sigu
 - Si el usuario pide corregir algo: **máximo 3 intentos**; después vuelve a informar.
 - Nunca modifiques `init.sh`, reglas de ESLint ni tests, ni silencies chequeos en `harness/arness.config.json`, para que pasen. Silenciar un chequeo es decisión humana y lleva motivo.
 - Opciones: `--strict`, `--json` (salida para máquinas), `--quick` (sin lint, build, tests ni health), `--e2e`, `--no-health` e `--install`. `pnpm arness doctor` resume, sin modificar nada, las **novedades por adoptar** de cada versión (seguridad, recomendadas y opcionales, con sus pasos) y el resto de los hallazgos.
+- **Nueva LTS de Node (`toolchain.node-lts`):** `init.sh` compara `.nvmrc` con la última LTS publicada (sin red, lo omite). Si hay una más nueva, **no actualices por tu cuenta**: analiza el impacto con `harness/playbooks/update-node-lts.md`, preséntale el análisis al humano y actualiza solo con su aprobación explícita. Si no aprueba, va a `docs/PENDIENTES.md`.
 - **Después de `pnpm arness sync`:** ejecuta `pnpm arness doctor` e **informa** al humano las novedades por adoptar. No las implementes si no son parte de la tarea; adoptar o declinar una novedad es decisión humana (declinar va con motivo en `harness/arness.config.json` → `declined`).
 - Al terminar una tarea, `./harness/init.sh` debe terminar en 0 y sin advertencias nuevas respecto al inicio.
 
@@ -119,7 +120,8 @@ Un reporte es `GET /api/v1/<modulo>/<segmento>` y vive en una carpeta con estos
 ## 8. Autenticación
 
 - **Sin usuarios en BD:** `POST /api/v1/auth/login` recibe `{ password }` y lo compara en tiempo constante con `ACCESS_TOKEN`. Devuelve un access token y un refresh token.
-- **Refresh:** `POST /api/v1/auth/refresh` emite un par nuevo.
+- **Refresh:** `POST /api/v1/auth/refresh` emite un par nuevo con el mismo `auth_time` del login: ninguna sesión dura más de `AUTH_SESSION_MAX_AGE_SECONDS` (`401 SESSION_EXPIRED`).
+- **Límite de intentos:** `/auth/login` y `/monitor/login` comparten `LoginAttemptLimiter` (por IP, en memoria, sin Redis): `429 TOO_MANY_ATTEMPTS` con `Retry-After`.
 - **Tokens:** secretos distintos para access y refresh, y el claim `type` se valida.
 - **Guard global:** `JwtAuthGuard` protege todo; `@Public()` **solo** en `login`, `refresh` y `health`.
 - **Monitor:** no es `@Public()`. `JwtAuthGuard` omite las rutas marcadas con `@MonitorRoute()` y las protege `MonitorSessionGuard` con su cookie de sesión (§10). El resto de la API solo acepta `Bearer`.
@@ -132,6 +134,7 @@ Un reporte es `GET /api/v1/<modulo>/<segmento>` y vive en una carpeta con estos
 - **Éxito:** `{ data, meta? }`. `meta` (`pagination` y `filters`) solo cuando el endpoint pagina o filtra.
 - **Error:** `{ error: { code, message, details?, requestId, path, timestamp } }` con el status HTTP correcto.
 - Los errores de PostgreSQL nunca se exponen tal cual.
+- **Cabeceras de seguridad:** `securityHeaders()` en toda respuesta (CSP, `nosniff`, `X-Frame-Options`, `no-store`, HSTS) y sin `X-Powered-By`, sin helmet.
 - **CORS:** allowlist por entorno en `CORS_ORIGINS` (orígenes exactos, `https://` salvo `localhost`). Nunca `*`, `origin: true` ni reflejar el origen de la petición; sin `credentials`. Métodos `GET`, `POST` y `OPTIONS`.
 - **Ejemplos, tabla de códigos y CORS:** `harness/reference/contrato-http.md`.
 
@@ -157,7 +160,7 @@ Crear o cambiar un endpoint actualiza, **en el mismo cambio**:
 Cambiar `.columns.ts`, los filtros o el envelope es un **cambio de contrato**: actualiza `FRONT.md` y sube la versión de la clave de caché.
 
 **Documentación del proyecto (`docs/`)**, plantillas en `harness/skills/nest-base/templates/docs/`:
-- **`docs/EVOLUTIVO.md`**: toda entrega (endpoint, módulo, conexión, widget del monitor, cambio de contrato) agrega **en el mismo cambio** una entrada al final: fecha, cliente/módulo, qué se entregó en lenguaje de negocio y referencia. **Solo avance:** nunca pendientes, bloqueos, stoppers ni riesgos. Las entradas anteriores no se reescriben.
+- **`docs/EVOLUTIVO.md`**: toda entrega (endpoint, módulo, conexión, widget del monitor, cambio de contrato) agrega **en el mismo cambio** una entrada al final: fecha y hora de Bogotá (`TZ=America/Bogota date '+%Y-%m-%d %H:%M %z'`), cliente/módulo, **responsable** (`git config user.name` de quien trabaja en ese momento; si está vacío, pregúntalo y nunca pongas el nombre del agente), qué se entregó en lenguaje de negocio y referencia. **Solo avance:** nunca pendientes, bloqueos, stoppers ni riesgos. Las entradas anteriores no se reescriben.
 - **`docs/PENDIENTES.md`**: lo que quedó abierto (pendientes, bloqueos, recomendaciones, deuda técnica, advertencias de `init.sh` sin corregir), con fecha, contexto y tipo. Al resolverse pasa a *Resueltos*.
 - **`docs/TECNICO.md`**: arquitectura, módulos, conexiones (sin credenciales), variables propias, despliegue y enlace a las decisiones. Se actualiza cuando cambian.
 - `FRONT.md` sigue en la raíz.
@@ -215,6 +218,7 @@ Ante ambigüedad de negocio o datos, **pregunta**. No inventes columnas, tablas
 | Crear un módulo o cliente | `harness/playbooks/new-module.md` |
 | Agregar una conexión de BD | `harness/playbooks/add-database.md` |
 | Agregar un widget al monitor | `harness/playbooks/new-monitor-widget.md` |
+| Actualizar Node a la última LTS | `harness/playbooks/update-node-lts.md` |
 | Revisar un cambio | `harness/playbooks/review.md` |
 | Variables de entorno | `harness/reference/configuracion.md` |
 | Envelope, errores, auth, CORS, health, monitor | `harness/reference/contrato-http.md` |

package/harness/agents/lider.md

@@ -22,6 +22,7 @@ Sigues `AGENTS.md` y las decisiones `Aceptada` de `harness/decisiones/`. **No es
      - Si no existe, o su estado es `TERMINADO`, créalo o reinícialo desde `harness/reference/progress-plantilla.md`.
      - Si está `EN CURSO` o `BLOQUEADO`, muéstrale al humano el resumen y pregúntale si retomar ese trabajo o empezar uno nuevo.
    - Registra el resultado de `init.sh` en `harness/progress.md` (exit y número de advertencias).
+   - Si aparece `toolchain.node-lts`, avísale al humano que hay una LTS de Node más nueva y ofrécele el análisis de `harness/playbooks/update-node-lts.md`. No se actualiza sin su aprobación explícita.
    - Si el harness se acaba de actualizar (`arness sync`), ejecuta `pnpm arness doctor` y muéstrale al humano las novedades por adoptar. No las conviertas en tareas salvo que el humano lo pida.
 2. **Contexto:** lee `harness/decisiones/README.md` y las decisiones relevantes.
 3. **Contrato:** para endpoints, confirma con el humano todo lo de AGENTS.md §15.1 **antes** de delegar. No supongas columnas, tablas ni reglas de negocio.

package/harness/agents/revisor.md

@@ -34,7 +34,7 @@ Comprueba que:
 2. Recorre el checklist de `harness/playbooks/review.md`.
 3. Verifica tú mismo: `pnpm lint:check`, `pnpm test` y `pnpm build`. Al final del ciclo de una tarea, ejecuta `./harness/init.sh --json` y compáralo con la línea base registrada en `harness/progress.md`: una advertencia **nueva** causada por el cambio es `BLOQUEANTE`; las que ya existían no lo son.
 4. Contrasta el resultado con los criterios de aceptación del encargo.
-5. Verifica que `docs/EVOLUTIVO.md` tiene la entrada de la entrega y **solo** avance: un pendiente, bloqueo o riesgo ahí es `IMPORTANTE` y se mueve a `docs/PENDIENTES.md`.
+5. Verifica que `docs/EVOLUTIVO.md` tiene la entrada de la entrega, con fecha, hora y zona de Bogotá y el responsable, y **solo** avance: un pendiente, bloqueo o riesgo ahí es `IMPORTANTE` y se mueve a `docs/PENDIENTES.md`.
 
 ## Reglas
 

package/harness/init.sh

@@ -22,6 +22,8 @@
 # Variables opcionales:
 #   HEALTH_URL          URL del health (default http://localhost:$PORT/health)
 #   HEALTH_TIMEOUT_S    Segundos de espera al arrancar la app (default 30)
+#   NODE_LTS_VERSION    Última LTS de Node con la que se compara .nvmrc (default: se consulta
+#                       nodejs.org; sin red se omite). "off" desactiva la comparación
 #
 # Salida: 0 = operativo (puede haber advertencias) · 1 = fallo crítico o --strict con hallazgos · 2 = uso incorrecto
 
@@ -307,10 +309,12 @@ elif [ ! -f package.json ]; then
 else
   section "Toolchain"
 
+  want=''
+  [ -f .nvmrc ] && want="$(tr -d '[:space:]v' < .nvmrc)"
   if command -v node >/dev/null 2>&1; then
     node_v="$(node -v)"
     if [ -f .nvmrc ]; then
-      want="$(tr -d '[:space:]v' < .nvmrc)"; have="${node_v#v}"
+      have="${node_v#v}"
       if [ "${want%%.*}" = "${have%%.*}" ]; then ok "Node $node_v (esperado v$want por .nvmrc)"
       else issue toolchain.node "Node $node_v no coincide con .nvmrc (v$want)"; fi
     else
@@ -320,6 +324,30 @@ else
     issue toolchain.node "Node no está instalado"
   fi
 
+  # Última LTS publicada en nodejs.org. Sin red se omite: nunca bloquea por conectividad.
+  case "${want%%.*}" in ''|*[!0-9]*) ;; *)
+    if [ "${NODE_LTS_VERSION:-}" = off ]; then
+      info "Comparación con la última LTS de Node desactivada (NODE_LTS_VERSION=off)"
+    else
+      lts="${NODE_LTS_VERSION:-$(curl -s -m 5 https://nodejs.org/dist/index.json 2>/dev/null | node -e '
+        let s = ""; process.stdin.on("data", (d) => (s += d)).on("end", () => {
+          try { const r = JSON.parse(s).find((x) => x.lts); if (r) console.log(r.version); } catch {}
+        })' 2>/dev/null)}"
+      lts="${lts#v}"
+      case "${lts%%.*}" in
+        ''|*[!0-9]*) info "No se pudo consultar la última LTS de Node (sin red o respuesta inválida): se omite" ;;
+        *)
+          if [ "${want%%.*}" -lt "${lts%%.*}" ]; then
+            issue toolchain.node-lts "Hay una LTS de Node más nueva: v$lts (.nvmrc fija v$want). No la actualices sin aprobación: analízala con $H/playbooks/update-node-lts.md y preséntale el análisis al humano"
+          elif [ "${want%%.*}" -eq "${lts%%.*}" ] && [ "$want" != "$lts" ]; then
+            info "Node v$lts es la última versión de la LTS v${lts%%.*}; .nvmrc fija v$want (actualizarla dentro de la misma LTS es opcional)"
+          else
+            ok ".nvmrc está en la última LTS de Node (v$lts)"
+          fi ;;
+      esac
+    fi ;;
+  esac
+
   if command -v pnpm >/dev/null 2>&1; then ok "pnpm $(pnpm -v)"
   else issue toolchain.pnpm "pnpm no está instalado"; fi
 
@@ -529,6 +557,25 @@ EOF
     issue security.cors-open ".env.example: CORS_ORIGINS no admite comodines"
   fi
 
+  # Endurecimiento de auth (ADR 0017): cabeceras, límite de intentos y vida de la sesión.
+  has_ts() { grep -rq --include='*.ts' --exclude='*.spec.ts' "$1" "$2" 2>/dev/null; }
+  if [ -f src/main.ts ]; then
+    if grep -q 'securityHeaders' src/main.ts; then ok "Cabeceras de seguridad registradas en src/main.ts"
+    else issue security.headers "src/main.ts no registra securityHeaders() (contrato-http.md, Cabeceras de seguridad)"; fi
+    if grep -qE "trust proxy['\"][[:space:]]*,[[:space:]]*true" src/main.ts; then
+      issue security.trust-proxy "src/main.ts confía en cualquier proxy (trust proxy = true): usa HTTP_TRUST_PROXY_HOPS (contrato-http.md, Límite de intentos)"
+    fi
+  fi
+  if [ -d src/common/auth ]; then
+    if has_ts LoginAttemptLimiter src/common/auth; then ok "Límite de intentos en /auth/login"
+    else issue security.login-rate-limit "/auth/login no usa LoginAttemptLimiter (contrato-http.md, Límite de intentos)"; fi
+    if has_ts isSessionExpired src/common/auth; then ok "Vida máxima de la sesión en /auth/refresh"
+    else issue security.session-max-age "/auth/refresh no limita la vida de la sesión con auth_time (contrato-http.md, Vida máxima de la sesión)"; fi
+  fi
+  if [ -d src/common/monitor ] && ! has_ts LoginAttemptLimiter src/common/monitor; then
+    issue security.login-rate-limit "/monitor/login no usa LoginAttemptLimiter (contrato-http.md, Monitor)"
+  fi
+
   if [ -d src/common/monitor ]; then
     mon_ctrl="$(grep -rl --include='*.controller.ts' '@Controller' src/common/monitor 2>/dev/null)"
     if [ -z "$mon_ctrl" ] || grep -L 'MonitorSessionGuard' $mon_ctrl | grep -q .; then

package/harness/playbooks/new-endpoint.md

@@ -80,7 +80,7 @@ Agrega el endpoint, su conexión y el origen de datos.
 
 ### docs/
 
-- `docs/EVOLUTIVO.md`: agrega al final una entrada `## <fecha> · <cliente>/<modulo>` con lo entregado en lenguaje de negocio (qué reporte quedó disponible), el endpoint y la referencia. Solo avance.
+- `docs/EVOLUTIVO.md`: agrega al final una entrada `## <AAAA-MM-DD HH:mm -0500> · <cliente>/<modulo>` (hora de Bogotá) con el responsable (`git config user.name`), lo entregado en lenguaje de negocio (qué reporte quedó disponible), el endpoint y la referencia. Solo avance.
 - `docs/PENDIENTES.md`: lo que quedó abierto (por ejemplo, una vista que aún no existe en la BD o un filtro aplazado).
 
 ## 4. Cierre

package/harness/playbooks/review.md

@@ -10,6 +10,7 @@ Revisa el diff contra `AGENTS.md` y reporta cada hallazgo con archivo y línea,
 - [ ] Un endpoint nuevo sin guard JWT, o un `@Public()` fuera de `login`, `refresh` o `health`
 - [ ] CORS abierto: `enableCors()` sin opciones, `origin: true`, `'*'`, reflejar el `Origin`, `credentials: true`, o `CORS_ORIGINS` con comodín
 - [ ] El monitor sin `MonitorSessionGuard`, marcado `@Public()`, dentro de `/api/v1`, con `<script>`, o un widget que muestra secretos, SQL, errores crudos o datos de negocio
+- [ ] `/auth/login` o `/monitor/login` sin `LoginAttemptLimiter`, un refresh que extiende la sesión (no copia `auth_time`), `src/main.ts` sin `securityHeaders()` o con `trust proxy` en `true`
 - [ ] Tokens, contraseñas o secretos en logs, respuestas, código o commits
 - [ ] `pino-pretty` en `dependencies` (va en devDependencies) o `LOG_FORMAT=pretty` para producción
 - [ ] Cambios en `.env`, o `.env.local` incluido en el commit
@@ -33,7 +34,7 @@ Revisa el diff contra `AGENTS.md` y reporta cada hallazgo con archivo y línea,
 
 - [ ] Un spec por archivo, incluidos los casos HIT/MISS/BYPASS
 - [ ] Postman, `FRONT.md` y el README del módulo actualizados
-- [ ] Entrada nueva al final de `docs/EVOLUTIVO.md` (sin reescribir las anteriores) y lo abierto en `docs/PENDIENTES.md`
+- [ ] Entrada nueva al final de `docs/EVOLUTIVO.md` (sin reescribir las anteriores), con fecha, hora y zona de Bogotá y el responsable (`git config user.name`) y lo abierto en `docs/PENDIENTES.md`
 - [ ] `docs/EVOLUTIVO.md` no contiene pendientes, bloqueos, stoppers ni riesgos
 - [ ] Variables nuevas en `.env.example`, `.env.local`, la validación y `src/config/configuration.ts` (`AppConfig`)
 - [ ] `./harness/init.sh` termina en 0 sin advertencias nuevas; las preexistentes se reportan, no se corrigen fuera de alcance

package/harness/playbooks/update-node-lts.md

@@ -0,0 +1,46 @@
+# Playbook: actualizar Node a la última LTS
+
+Referencia: `AGENTS.md` §2 (Node.js en su última LTS) y §13.4. Se usa cuando `./harness/init.sh` reporta `toolchain.node-lts` o cuando el humano pide actualizar Node.
+
+**Actualizar Node es decisión humana.** El agente analiza, presenta y espera aprobación explícita. No cambia ningún archivo antes de esa aprobación, no instala Node por su cuenta y no convierte la advertencia en tarea si el humano no lo pide.
+
+## 1. Analizar (solo lectura)
+
+1. **Versiones:** la de `.nvmrc`, la de `node -v` y la última LTS:
+   ```bash
+   curl -s https://nodejs.org/dist/index.json \
+     | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s).find(x=>x.lts);console.log(r.version, r.lts)})'
+   ```
+2. **Soporte:** fin de soporte de la versión actual y de la nueva en `https://raw.githubusercontent.com/nodejs/Release/main/schedule.json` (campos `maintenance` y `end`).
+3. **Dónde está fijada la versión:** `.nvmrc`, `engines.node` de `package.json`, `FROM node:<major>-alpine` del `Dockerfile`, `azure-pipelines.yml` (`versionSpec` o lectura de `.nvmrc`) y `@types/node` en `devDependencies`. Lista cada archivo con su valor actual y el nuevo.
+4. **Compatibilidad:** `engines` de las dependencias directas en la versión instalada (`pnpm view <paquete>@<versión> engines`), empezando por `@nestjs/core`, `pg`, `ioredis` y `@types/node`. Marca cualquiera que no admita la nueva versión.
+5. **Cambios incompatibles de Node:** revisa las notas del release del nuevo major (`https://nodejs.org/en/blog`) y busca en `src/` y `test/` las APIs que se eliminan o cambian.
+6. **Entorno:** si `node -v` no es del nuevo major, el humano debe instalarlo (por ejemplo `nvm install --lts` o `fnm install --lts`) antes de verificar.
+
+## 2. Presentar al humano y pedir aprobación
+
+```
+Actualización de Node: v<actual> → v<nueva LTS> (<codename>)
+Soporte:        v<actual> en mantenimiento hasta <fecha>, fin <fecha> · v<nueva> soportada hasta <fecha>
+Archivos:       .nvmrc, package.json (engines), Dockerfile, azure-pipelines.yml
+Dependencias:   @types/node <actual> → <nueva> (requiere aprobación, AGENTS.md §13.4)
+Compatibilidad: <dependencias que admiten la nueva versión / las que no>
+Riesgos:        <APIs de Node afectadas en el código, o "ninguno detectado">
+Recomendación:  <actualizar ahora / esperar, y por qué>
+¿Apruebas la actualización? (sí / no)
+```
+
+No continúes sin un **sí** explícito. La aprobación cubre solo lo listado: si aparece otra dependencia que cambiar, vuelve a preguntar.
+
+## 3. Si el humano aprueba
+
+1. Actualiza `.nvmrc` (versión completa, ej. `v26.11.0`), `engines.node` (`>=<major>`), la imagen del `Dockerfile` y `azure-pipelines.yml` si fija la versión.
+2. Actualiza `@types/node` al nuevo major con `pnpm add -D @types/node@<major>` y conserva el lockfile en el mismo cambio.
+3. Verifica con el nuevo Node: `pnpm install --frozen-lockfile`, `./harness/init.sh` (sin `toolchain.node` ni `toolchain.node-lts`), `pnpm test:e2e` y, si hay Docker, `docker build .`.
+4. Actualiza la versión de Node en `docs/TECNICO.md`.
+5. Commit: `chore(node): upgrade to Node <major> LTS`.
+
+## 4. Si el humano no aprueba
+
+1. Registra en `docs/PENDIENTES.md` una entrada de tipo recomendación con la fecha, la versión propuesta, el motivo que dio el humano y la fecha de fin de soporte de la versión actual.
+2. No silencies `toolchain.node-lts` en `harness/arness.config.json`: la advertencia sigue visible para recordarlo. Silenciarla es decisión humana y lleva motivo.

package/harness/reference/configuracion.md

@@ -16,7 +16,7 @@ export function buildConfiguration(env: Env): AppConfig {
   return {
     app: { nodeEnv: text(env, 'NODE_ENV', 'development'), port: int(env, 'PORT', 3000) },
     databases: parseDatabases(env), // DATABASES=MAIN,REPORTS → { MAIN: { host, port, ... }, REPORTS: {...} }
-    auth: { accessToken: required(env, 'ACCESS_TOKEN'), jwt: { accessSecret: required(env, 'JWT_ACCESS_SECRET'), ... } },
+    auth: parseAuthConfig(env), // src/config/auth.ts: secretos, límite de intentos y vida de la sesión
     // cache, cors, monitor...
   };
 }
@@ -80,8 +80,15 @@ JWT_ACCESS_SECRET=change-me
 JWT_ACCESS_EXPIRES_IN=15m
 JWT_REFRESH_SECRET=change-me-too # distinto de JWT_ACCESS_SECRET
 JWT_REFRESH_EXPIRES_IN=7d
+AUTH_SESSION_MAX_AGE_SECONDS=43200   # vida máxima de la sesión aunque se refresque (60–2592000; default 12 h)
+AUTH_LOGIN_MAX_ATTEMPTS=5            # intentos fallidos por IP antes de bloquear el login (1–100)
+AUTH_LOGIN_WINDOW_SECONDS=900        # ventana del conteo y duración del bloqueo (1–86400)
+HTTP_TRUST_PROXY_HOPS=0              # proxies delante de la app (Azure App Service: 1); 0 = IP del socket
 ```
 
+- `src/config/auth.ts` (plantilla `templates/config/auth.ts`, `parseAuthConfig`) arma este bloque: los secretos son obligatorios y sin valor por defecto; el resto tiene default.
+- Límite de intentos, vida de la sesión y proxy: `contrato-http.md` (Autenticación).
+
 ## CORS
 
 ```dotenv

package/harness/reference/contrato-http.md

@@ -40,9 +40,10 @@ Siempre con el status HTTP correcto. `details` es opcional.
 | Status | `code` | Origen típico |
 |---|---|---|
 | 400 | `VALIDATION_ERROR` | DTO inválido |
-| 401 | `UNAUTHORIZED` / `TOKEN_EXPIRED` / `INVALID_CREDENTIALS` | guard o login |
+| 401 | `UNAUTHORIZED` / `TOKEN_EXPIRED` / `INVALID_CREDENTIALS` / `SESSION_EXPIRED` | guard, login o refresh |
 | 403 | `FORBIDDEN` | — |
 | 404 | `NOT_FOUND` | ruta o recurso |
+| 429 | `TOO_MANY_ATTEMPTS` | login bloqueado por intentos fallidos (con `Retry-After`) |
 | 503 | `DATABASE_UNAVAILABLE` | pg: conexión rechazada, `08*`, `57P01` |
 | 504 | `QUERY_TIMEOUT` | pg: `57014` (statement_timeout) |
 | 500 | `INTERNAL_ERROR` | cualquier otro; sin stack ni SQL |
@@ -55,8 +56,38 @@ Siempre con el status HTTP correcto. `details` es opcional.
 | `POST /api/v1/auth/refresh` | `{ "refreshToken": "..." }` | `{ data: { accessToken, refreshToken, expiresIn } }` |
 
 - `password` se compara con `ACCESS_TOKEN` en tiempo constante: `crypto.timingSafeEqual` sobre el sha256 de ambos valores.
-- Los tokens usan secretos distintos; el claim `type` (`access` o `refresh`) se valida.
-- Los clientes envían `Authorization: Bearer <accessToken>`. Ante `401 TOKEN_EXPIRED`, llaman a `/auth/refresh` y reintentan una vez.
+- Los tokens usan secretos distintos; el claim `type` (`access` o `refresh`) se valida. Un token de otro tipo (`refresh`, o el `monitor` de la cookie) como `Bearer` → `401 UNAUTHORIZED`; un access token en `/auth/refresh` → `401 UNAUTHORIZED`.
+- Los clientes envían `Authorization: Bearer <accessToken>`. Ante `401 TOKEN_EXPIRED`, llaman a `/auth/refresh` y reintentan una vez. Ante `401 SESSION_EXPIRED` o `429`, vuelven al login.
+
+### Vida máxima de la sesión
+
+- `/auth/login` emite el par con el claim `auth_time` (segundos, hora del login). `/auth/refresh` **copia** el `auth_time` del refresh token al par nuevo: refrescar nunca extiende la sesión.
+- Si `ahora - auth_time >= AUTH_SESSION_MAX_AGE_SECONDS` (default 12 h), o el refresh token no trae `auth_time`, el refresh responde `401 SESSION_EXPIRED` y el cliente debe volver a `/auth/login`. Así, un refresh token robado deja de servir como mucho al cumplir esa edad.
+- Para cortar todas las sesiones de inmediato, se rota `JWT_REFRESH_SECRET` (y `JWT_ACCESS_SECRET` si hace falta).
+- Implementación de referencia: `templates/security/session-lifetime.ts` → `src/common/security/` (`sessionClaims`, `isSessionExpired`).
+
+### Límite de intentos
+
+- `/auth/login` y `/monitor/login` comparten `LoginAttemptLimiter` (`templates/security/login-attempts.ts` → `src/common/security/`, provisto por `SecurityModule`, global). Cuenta los intentos fallidos **por IP** (`req.ip`) en memoria.
+- Al llegar a `AUTH_LOGIN_MAX_ATTEMPTS` fallos (default 5) dentro de `AUTH_LOGIN_WINDOW_SECONDS` (default 900, contados desde el primer fallo), la IP queda bloqueada hasta que termina la ventana: responde `429 TOO_MANY_ATTEMPTS` con `Retry-After: <segundos>` **sin comparar la contraseña**. Un login correcto reinicia el contador.
+- Orden en el controller: `check(ip)` → si no está permitido, `429`; si la contraseña es incorrecta, `registerFailure(ip)` y `401 INVALID_CREDENTIALS`; si es correcta, `reset(ip)` y el par de tokens.
+- **IP real detrás de un proxy:** con `HTTP_TRUST_PROXY_HOPS=<n>` (Azure App Service o un gateway: `1`), `main.ts` llama a `app.set('trust proxy', n)` y `req.ip` sale de `X-Forwarded-For`. Con `0` (default) se usa la IP del socket. Nunca `true`: permitiría falsificar la IP con la cabecera.
+- El contador es **por instancia** y no depende de Redis: con varias réplicas, cada una cuenta aparte. El map tiene un tope de 10 000 IPs.
+
+## Cabeceras de seguridad
+
+`securityHeaders()` (`templates/security/security-headers.ts` → `src/common/security/`) se registra en `src/main.ts` con `app.use(...)` antes de las rutas, sin helmet. En toda respuesta:
+
+| Cabecera | Valor |
+|---|---|
+| `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'; base-uri 'none'` |
+| `X-Content-Type-Options` | `nosniff` |
+| `X-Frame-Options` | `DENY` |
+| `Referrer-Policy` | `no-referrer` |
+| `Strict-Transport-Security` | `max-age=31536000` |
+| `Cache-Control` | `no-store` (las respuestas llevan datos privados; la caché es la de Redis) |
+
+Además quita `X-Powered-By`. El monitor reemplaza la CSP por la suya (sección Monitor).
 
 ## CORS
 
@@ -130,7 +161,7 @@ Tablero de estado para el equipo, **fuera de `/api/v1`** y apagado por defecto.
 - **Render:** `react-dom/server` (`renderToStaticMarkup`) con `createElement`, sin JSX, sin hidratación, sin bundler y sin `<script>`. Estilos inline.
 - **Login:** la contraseña se compara con `ACCESS_TOKEN` en tiempo constante, igual que `/auth/login`. Al acertar se emite un JWT con `type: "monitor"` (firmado con `JWT_ACCESS_SECRET`, dura `MONITOR_SESSION_EXPIRES_IN`) en la cookie `arness_monitor`: `HttpOnly; Secure; SameSite=Strict; Path=/monitor; Max-Age=<duración>`. Un access token (`type: "access"`) no sirve como cookie ni la cookie sirve como `Bearer`.
 - **Guards:** el controller lleva `@MonitorRoute()`, que `JwtAuthGuard` omite, y `MonitorSessionGuard`, que exige la cookie salvo en los handlers `@MonitorLogin()` (formulario, login y logout). No es `@Public()`.
-- **Rate limiting:** cuando el harness incorpore límite de intentos para `/auth/login`, el login del monitor lo comparte.
+- **Límite de intentos:** comparte `LoginAttemptLimiter` con `/auth/login` (sección Autenticación). Bloqueado → `429` con `Retry-After` y el formulario con "Demasiados intentos", sin cookie.
 - **Cabeceras en toda respuesta:** `Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`, `Cache-Control: no-store`, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff` y `Referrer-Policy: no-referrer`.
 - **Widgets:** `MonitorWidget { id; title; order; collect(): Promise<MonitorValue> }`, registrados en el multi-provider `MONITOR_WIDGETS` de `MonitorModule`. Un widget que lanza o tarda más de 2 s se muestra como "No disponible"; el log registra solo el tipo de error, nunca su mensaje.
 - **Widget base `endpoints-total`:** cuenta las rutas HTTP con `DiscoveryService` y `MetadataScanner`, excluye `monitor`, `health` y `auth`, y desglosa por el primer segmento de la ruta (el módulo).

package/harness/reference/novedades.json

@@ -46,7 +46,7 @@
       "paths": ["src/common/monitor"],
       "approval": "react y react-dom (aprobadas en AGENTS.md §2 solo para el monitor); registra la adopción en harness/decisiones/ si el proyecto aún no las usa.",
       "steps": [
-        "Copia harness/skills/nest-base/templates/monitor/ a src/common/monitor/ y registra MonitorModule.",
+        "Copia harness/skills/nest-base/templates/monitor/ a src/common/monitor/ y registra MonitorModule. Requiere SecurityModule (templates/security/), que comparte el límite de intentos del login.",
         "Excluye monitor del prefijo global y haz que JwtAuthGuard omita IS_MONITOR_ROUTE_KEY.",
         "Agrega MONITOR_ENABLED=false y MONITOR_SESSION_EXPIRES_IN=15m a .env.example y .env.local."
       ],
@@ -102,6 +102,57 @@
       ],
       "adr": "0011",
       "reference": "harness/AGENTS.md §12"
+    },
+    {
+      "id": "login-rate-limit",
+      "since": "0.3.0",
+      "type": "seguridad",
+      "title": "Límite de intentos en /auth/login y /monitor/login",
+      "why": "Toda la API se protege con una contraseña compartida: sin límite se puede adivinar por fuerza bruta.",
+      "checks": ["security.login-rate-limit", "security.trust-proxy"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Copia harness/skills/nest-base/templates/security/ a src/common/security/ y registra SecurityModule en app.module.ts. Copia también templates/config/auth.ts (y su spec) y usa auth: parseAuthConfig(env) en configuration.ts.",
+        "En el login: check(req.ip) → 429 TOO_MANY_ATTEMPTS con Retry-After; contraseña incorrecta → registerFailure(req.ip); correcta → reset(req.ip). Copia también templates/monitor/monitor.controller.ts si usas el monitor.",
+        "Agrega AUTH_LOGIN_MAX_ATTEMPTS, AUTH_LOGIN_WINDOW_SECONDS y HTTP_TRUST_PROXY_HOPS (1 detrás de Azure App Service) y, en main.ts, app.set(\"trust proxy\", hops) solo si hops > 0.",
+        "Avisa a frontend: ante 429 se espera lo que indica Retry-After (FRONT.md)."
+      ],
+      "adr": "0017",
+      "reference": "harness/reference/contrato-http.md (Autenticación › Límite de intentos)"
+    },
+    {
+      "id": "session-max-age",
+      "since": "0.3.0",
+      "type": "seguridad",
+      "title": "Vida máxima de la sesión en /auth/refresh",
+      "why": "Cada refresh entregaba un par nuevo sin límite: un refresh token robado servía indefinidamente.",
+      "checks": ["security.session-max-age"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Con src/common/security/ ya copiado, firma el par con sessionClaims(authTime): el login usa nowInSeconds() y el refresh copia el auth_time del refresh token.",
+        "En el refresh, si isSessionExpired(payload, sessionMaxAgeSeconds) responde 401 SESSION_EXPIRED.",
+        "Agrega AUTH_SESSION_MAX_AGE_SECONDS=43200 a .env.example y .env.local, y avisa a frontend: ante 401 SESSION_EXPIRED vuelve al login. Los refresh tokens emitidos antes no traen auth_time y exigirán un login nuevo."
+      ],
+      "adr": "0017",
+      "reference": "harness/reference/contrato-http.md (Autenticación › Vida máxima de la sesión)"
+    },
+    {
+      "id": "security-headers",
+      "since": "0.3.0",
+      "type": "seguridad",
+      "title": "Cabeceras de seguridad en toda respuesta",
+      "why": "Sin CSP, nosniff, X-Frame-Options ni no-store, el navegador puede interpretar o guardar en caché respuestas con datos privados.",
+      "checks": ["security.headers"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Con src/common/security/ ya copiado, agrega app.use(securityHeaders()) en src/main.ts antes de registrar las rutas.",
+        "Verifica en test/ que una respuesta de la API trae las cabeceras y no trae X-Powered-By."
+      ],
+      "adr": "0017",
+      "reference": "harness/reference/contrato-http.md (Cabeceras de seguridad)"
     }
   ]
 }

package/harness/skills/nest-base/SKILL.md

@@ -118,29 +118,30 @@ Implementa cada pieza con su spec. Sin lógica de negocio y sin módulos de ejem
 
 | Ruta | Contenido mínimo |
 |---|---|
-| `src/main.ts` | Logger pino (`bufferLogs`), prefijo `api/v1` excluyendo `health` y `monitor` (`{ exclude: ['health', 'monitor', 'monitor/{*path}'] }`, o la sintaxis de rutas de la versión de Nest), `ValidationPipe({ whitelist, forbidNonWhitelisted, transform })`, `app.enableCors(buildCorsOptions(...))` con los valores validados de config, `enableShutdownHooks`, puerto desde `ConfigService` (`app.port`), nunca de `process.env` |
+| `src/main.ts` | Logger pino (`bufferLogs`), prefijo `api/v1` excluyendo `health` y `monitor` (`{ exclude: ['health', 'monitor', 'monitor/{*path}'] }`, o la sintaxis de rutas de la versión de Nest), `ValidationPipe({ whitelist, forbidNonWhitelisted, transform })`, `app.enableCors(buildCorsOptions(...))` con los valores validados de config, `app.use(securityHeaders())` antes de las rutas, `app.set('trust proxy', hops)` solo si `app.trustProxyHops > 0` (`NestExpressApplication`), `enableShutdownHooks`, puerto desde `ConfigService` (`app.port`), nunca de `process.env` |
 | `src/app.module.ts` | Importa config, logging, database, cache, auth, health; registra el guard JWT global y el filtro de errores |
-| `src/config/` | `ConfigModule` global con `envFilePath: ['.env.local', '.env']`, `validate` y `load: [configuration]`; validación con class-validator que falla al arrancar, incluida la validación dinámica de `DB_<NOMBRE>_*` por cada nombre en `DATABASES`. `configuration.ts` y `configuration.spec.ts` desde `templates/config/`: **único lugar que lee `process.env`**, exporta `AppConfig` y no da valor por defecto a ningún secreto. `cors.ts` y `cors.spec.ts` desde `templates/cors/`: la validación y `configuration.ts` llaman a `parseCorsOrigins` y `parseCorsMaxAge`, así que la app no arranca sin `CORS_ORIGINS` o con `*`. El resto del código consume `ConfigService<AppConfig, true>` |
+| `src/config/` | `ConfigModule` global con `envFilePath: ['.env.local', '.env']`, `validate` y `load: [configuration]`; validación con class-validator que falla al arrancar, incluida la validación dinámica de `DB_<NOMBRE>_*` por cada nombre en `DATABASES`. `configuration.ts` y `configuration.spec.ts` desde `templates/config/`: **único lugar que lee `process.env`**, exporta `AppConfig` y no da valor por defecto a ningún secreto. `auth.ts` y `auth.spec.ts` desde `templates/config/`: `configuration.ts` llama a `parseAuthConfig` (secretos obligatorios, límite de intentos y vida de la sesión). `cors.ts` y `cors.spec.ts` desde `templates/cors/`: la validación y `configuration.ts` llaman a `parseCorsOrigins` y `parseCorsMaxAge`, así que la app no arranca sin `CORS_ORIGINS` o con `*`. El resto del código consume `ConfigService<AppConfig, true>` |
 | `src/common/database/` | `DatabaseModule` dinámico: un `Pool` por nombre, `getPoolToken(name)`, sesión con `default_transaction_read_only=on` y `statement_timeout`, cierre en shutdown |
 | `src/common/cache/` | `CacheService` sobre ioredis (`lazyConnect`, `enableOfflineQueue: false`, `commandTimeout`, reintentos con backoff). No lanza nunca y devuelve `HIT` / `MISS` / `BYPASS`. Hash estable de filtros (claves ordenadas → sha256). Con `CACHE_ENABLED=false` no conecta |
-| `src/common/auth/` | `POST auth/login` y `POST auth/refresh` (`@Public()`), `timingSafeEqual` sobre sha256 de ambos valores, secretos distintos y claim `type`, `JwtAuthGuard` como `APP_GUARD`. El guard omite las rutas con `@Public()` y con `IS_MONITOR_ROUTE_KEY` (`@MonitorRoute()`, de `src/common/monitor/monitor.decorators.ts`) |
+| `src/common/security/` | Copia `templates/security/` completo (con sus specs) y registra `SecurityModule` (global) en `app.module.ts`: `LoginAttemptLimiter`, `securityHeaders()` y `sessionClaims` / `isSessionExpired` (contrato-http.md, Autenticación y Cabeceras de seguridad) |
+| `src/common/auth/` | `POST auth/login` y `POST auth/refresh` (`@Public()`), `timingSafeEqual` sobre sha256 de ambos valores, secretos distintos y claim `type`, `JwtAuthGuard` como `APP_GUARD`. Login con `LoginAttemptLimiter` por `req.ip` (`429 TOO_MANY_ATTEMPTS` con `Retry-After`). El par lleva `auth_time` (`sessionClaims`): el login lo fija y el refresh lo copia; `isSessionExpired` → `401 SESSION_EXPIRED`. El guard omite las rutas con `@Public()` y con `IS_MONITOR_ROUTE_KEY` (`@MonitorRoute()`, de `src/common/monitor/monitor.decorators.ts`) |
 | `src/common/http/` | Tipos `{ data, meta? }`, filtro global de errores `{ error: { code, message, details?, requestId, path, timestamp } }`. Errores de pg: `57014` → 504 `QUERY_TIMEOUT`; errores de conexión o `08*` / `57P01` → 503 `DATABASE_UNAVAILABLE` |
 | `src/common/logging/` | `logger-options.ts` y su spec desde `templates/logging/`; `LoggerModule.forRootAsync` con `buildLoggerParams(config.get('logging', { infer: true }))`. JSON por defecto, `pretty` en desarrollo con `LOG_FORMAT`, `genReqId` desde `X-Request-Id` seguro o UUID y devuelto en la respuesta, `redact` de authorization, cookies, password, tokens y secretos |
 | `src/common/health/` | `GET /health` público con terminus. Indicadores `db_<nombre en minúsculas>` por conexión y `cache` con estado `up` / `down` / `disabled`; la caché nunca vuelve el health a 503 |
 | `src/common/monitor/` | Copia `templates/monitor/` completo (con sus specs) y registra `MonitorModule` en `app.module.ts`. `GET /monitor` fuera de `/api/v1`, `404` si `MONITOR_ENABLED` no es `true`, login con `ACCESS_TOKEN` y cookie de sesión, cabeceras CSP sin scripts, widget base `endpoints-total` (contrato-http.md, Monitor) |
-| `test/` | `auth.e2e-spec.ts` (login OK, login inválido, refresh, 401 sin token), `health.e2e-spec.ts` (pools y Redis mockeados con `overrideProvider`), y `cors.e2e-spec.ts` y `monitor.e2e-spec.ts` desde `templates/e2e/` |
+| `test/` | `auth.e2e-spec.ts` (login OK, login inválido, refresh, 401 sin token, `429` con `Retry-After` tras `AUTH_LOGIN_MAX_ATTEMPTS` fallos, `401 SESSION_EXPIRED` al refrescar pasada la vida máxima, refresh token y token del monitor como `Bearer` → 401, access token en `/auth/refresh` → 401, cabeceras de seguridad y sin `X-Powered-By`), `health.e2e-spec.ts` (pools y Redis mockeados con `overrideProvider`), y `cors.e2e-spec.ts` y `monitor.e2e-spec.ts` desde `templates/e2e/` |
 
 ### Archivos de soporte
 
-- **`.env.example` y `.env.local`:** las mismas claves. Incluyen `NODE_ENV=development`, `PORT=3000`, `DATABASES=MAIN`, `DB_MAIN_*`, `ACCESS_TOKEN=example123`, `JWT_*`, `CACHE_*`, `REDIS_URL`, `LOG_LEVEL`, `LOG_FORMAT` (`json` en `.env.example`, `pretty` en `.env.local`), `CORS_ORIGINS=http://localhost:4200`, `CORS_MAX_AGE_SECONDS=600`, `MONITOR_ENABLED=false` y `MONITOR_SESSION_EXPIRES_IN=15m`. En `.env.example` todos los secretos llevan valores de ejemplo. **No crees ni toques `.env`.**
+- **`.env.example` y `.env.local`:** las mismas claves. Incluyen `NODE_ENV=development`, `PORT=3000`, `DATABASES=MAIN`, `DB_MAIN_*`, `ACCESS_TOKEN=example123`, `JWT_*`, `AUTH_SESSION_MAX_AGE_SECONDS=43200`, `AUTH_LOGIN_MAX_ATTEMPTS=5`, `AUTH_LOGIN_WINDOW_SECONDS=900`, `HTTP_TRUST_PROXY_HOPS=0`, `CACHE_*`, `REDIS_URL`, `LOG_LEVEL`, `LOG_FORMAT` (`json` en `.env.example`, `pretty` en `.env.local`), `CORS_ORIGINS=http://localhost:4200`, `CORS_MAX_AGE_SECONDS=600`, `MONITOR_ENABLED=false` y `MONITOR_SESSION_EXPIRES_IN=15m`. En `.env.example` todos los secretos llevan valores de ejemplo. **No crees ni toques `.env`.**
 - **`postman/arness-back.postman_collection.json`** (formato v2.1): variables `baseUrl`, `accessToken` y `refreshToken`, y auth Bearer heredada. Carpeta `Auth` con Login (su script de test guarda los tokens) y Refresh, más la request `Health`. Agrega también `postman/local.postman_environment.json` con `baseUrl=http://localhost:3000`.
 - **`FRONT.md`:**
-  - flujo de auth (login, uso del Bearer, refresh ante `401 TOKEN_EXPIRED`);
+  - flujo de auth (login, uso del Bearer, refresh ante `401 TOKEN_EXPIRED`, volver al login ante `401 SESSION_EXPIRED`, y ante `429` esperar lo que indica `Retry-After`);
   - envelope `{ data, meta? }` y formato de error;
   - significado de `X-Cache`;
   - CORS: el origen del frontend debe estar en `CORS_ORIGINS` de cada entorno (pedirlo al backend);
   - endpoints de Auth con su consumo recomendado.
-- **`docs/`:** copia `templates/docs/` (`TECNICO.md`, `EVOLUTIVO.md` y `PENDIENTES.md`). Completa en `TECNICO.md` lo que ya se sabe (cliente, conexión `MAIN`, entornos) y deja en `EVOLUTIVO.md` la entrada "Base del proyecto" con la fecha de hoy. Los pendientes del reporte final (§7) van a `PENDIENTES.md`.
+- **`docs/`:** copia `templates/docs/` (`TECNICO.md`, `EVOLUTIVO.md` y `PENDIENTES.md`). Completa en `TECNICO.md` lo que ya se sabe (cliente, conexión `MAIN`, entornos) y deja en `EVOLUTIVO.md` la entrada "Base del proyecto" con la fecha y hora de Bogotá y el responsable (formato de la plantilla). Los pendientes del reporte final (§7) van a `PENDIENTES.md`.
 - **`Dockerfile`:** multi-stage con `node:<major-lts>-alpine`, `corepack enable`, `pnpm install --frozen-lockfile`, build y una imagen final solo con `dist/` y las dependencias de producción; usuario no root y `HEALTHCHECK` sobre `/health`.
 - **`azure-pipelines.yml`:** Node desde `.nvmrc`, `corepack enable`, `pnpm install --frozen-lockfile`, `lint:check`, `format:check`, `build`, `test` y `docker build`.
 

package/harness/skills/nest-base/templates/config/auth.spec.ts

@@ -0,0 +1,32 @@
+// Plantilla del harness → src/config/auth.spec.ts
+import { parseAuthConfig } from './auth';
+
+const base = {
+  ACCESS_TOKEN: 'example123',
+  JWT_ACCESS_SECRET: 'access-secret',
+  JWT_REFRESH_SECRET: 'refresh-secret',
+};
+
+describe('parseAuthConfig', () => {
+  it('applies non-sensitive defaults', () => {
+    const auth = parseAuthConfig(base);
+    expect(auth.jwt).toEqual({
+      accessSecret: 'access-secret',
+      accessExpiresIn: '15m',
+      refreshSecret: 'refresh-secret',
+      refreshExpiresIn: '7d',
+    });
+    expect(auth.login).toEqual({ maxAttempts: 5, windowSeconds: 900 });
+    expect(auth.sessionMaxAgeSeconds).toBe(43200);
+  });
+
+  it.each([
+    [{ ACCESS_TOKEN: undefined }, /ACCESS_TOKEN is required/],
+    [{ JWT_REFRESH_SECRET: ' ' }, /JWT_REFRESH_SECRET is required/],
+    [{ AUTH_LOGIN_MAX_ATTEMPTS: '0' }, /AUTH_LOGIN_MAX_ATTEMPTS must be an integer/],
+    [{ AUTH_LOGIN_WINDOW_SECONDS: 'abc' }, /AUTH_LOGIN_WINDOW_SECONDS must be an integer/],
+    [{ AUTH_SESSION_MAX_AGE_SECONDS: '30' }, /AUTH_SESSION_MAX_AGE_SECONDS must be an integer/],
+  ])('rejects %p', (overrides, message) => {
+    expect(() => parseAuthConfig({ ...base, ...overrides })).toThrow(message);
+  });
+});

package/harness/skills/nest-base/templates/config/auth.ts

@@ -0,0 +1,80 @@
+// Plantilla del harness → src/config/auth.ts (AGENTS.md §8, harness/reference/configuracion.md "Autenticación").
+// Auth block of AppConfig: secrets (required, no default), login attempt limit and session max age.
+// Errors name the variable, never its value.
+
+export const AUTH_DEFAULT_LOGIN_MAX_ATTEMPTS = 5;
+export const AUTH_DEFAULT_LOGIN_WINDOW_SECONDS = 900;
+export const AUTH_DEFAULT_SESSION_MAX_AGE_SECONDS = 43200;
+
+export interface AuthConfig {
+  accessToken: string;
+  jwt: {
+    accessSecret: string;
+    accessExpiresIn: string;
+    refreshSecret: string;
+    refreshExpiresIn: string;
+  };
+  login: { maxAttempts: number; windowSeconds: number };
+  sessionMaxAgeSeconds: number;
+}
+
+type Env = Record<string, string | undefined>;
+
+function required(env: Env, name: string): string {
+  const value = env[name];
+  if (value === undefined || value.trim() === '') {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+function intInRange(env: Env, name: string, fallback: number, min: number, max: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim() === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+function text(env: Env, name: string, fallback: string): string {
+  const value = env[name];
+  return value === undefined || value.trim() === '' ? fallback : value.trim();
+}
+
+/** Pure: reads and validates the auth block. */
+export function parseAuthConfig(env: Env): AuthConfig {
+  return {
+    accessToken: required(env, 'ACCESS_TOKEN'),
+    jwt: {
+      accessSecret: required(env, 'JWT_ACCESS_SECRET'),
+      accessExpiresIn: text(env, 'JWT_ACCESS_EXPIRES_IN', '15m'),
+      refreshSecret: required(env, 'JWT_REFRESH_SECRET'),
+      refreshExpiresIn: text(env, 'JWT_REFRESH_EXPIRES_IN', '7d'),
+    },
+    login: {
+      maxAttempts: intInRange(
+        env,
+        'AUTH_LOGIN_MAX_ATTEMPTS',
+        AUTH_DEFAULT_LOGIN_MAX_ATTEMPTS,
+        1,
+        100,
+      ),
+      windowSeconds: intInRange(
+        env,
+        'AUTH_LOGIN_WINDOW_SECONDS',
+        AUTH_DEFAULT_LOGIN_WINDOW_SECONDS,
+        1,
+        86400,
+      ),
+    },
+    sessionMaxAgeSeconds: intInRange(
+      env,
+      'AUTH_SESSION_MAX_AGE_SECONDS',
+      AUTH_DEFAULT_SESSION_MAX_AGE_SECONDS,
+      60,
+      2592000,
+    ),
+  };
+}

package/harness/skills/nest-base/templates/config/configuration.spec.ts

@@ -16,7 +16,7 @@ const base: Env = {
 describe('buildConfiguration', () => {
   it('groups variables by topic and applies non-sensitive defaults', () => {
     const config = buildConfiguration(base);
-    expect(config.app).toEqual({ nodeEnv: 'development', port: 3000 });
+    expect(config.app).toEqual({ nodeEnv: 'development', port: 3000, trustProxyHops: 0 });
     expect(config.logging).toEqual({ level: 'info', format: 'json' });
     expect(config.databases.MAIN).toEqual({
       host: 'localhost',
@@ -78,6 +78,7 @@ describe('buildConfiguration', () => {
     ['PORT', 'abc', /integer/],
     ['MONITOR_ENABLED', 'yes', /true or false/],
     ['LOG_FORMAT', 'xml', /json or pretty/],
+    ['HTTP_TRUST_PROXY_HOPS', '11', /between 0 and 10/],
   ])('rejects %s=%p', (name, value, message) => {
     expect(() => buildConfiguration({ ...base, [name]: value })).toThrow(message);
   });

package/harness/skills/nest-base/templates/config/configuration.ts

@@ -3,6 +3,7 @@
 // through ConfigService<AppConfig, true>. Variables are validated at startup (env validation in
 // src/config/); this file only groups them and converts their types.
 import { type LogFormat, parseLogFormat } from '../common/logging/logger-options';
+import { type AuthConfig, parseAuthConfig } from './auth';
 import { parseCorsMaxAge, parseCorsOrigins } from './cors';
 
 export type Env = Record<string, string | undefined>;
@@ -19,7 +20,7 @@ export interface DatabaseConfig {
 }
 
 export interface AppConfig {
-  app: { nodeEnv: string; port: number };
+  app: { nodeEnv: string; port: number; trustProxyHops: number };
   logging: { level: string; format: LogFormat };
   databases: Record<string, DatabaseConfig>;
   cache: {
@@ -29,15 +30,7 @@ export interface AppConfig {
     keyPrefix: string;
     opTimeoutMs: number;
   };
-  auth: {
-    accessToken: string;
-    jwt: {
-      accessSecret: string;
-      accessExpiresIn: string;
-      refreshSecret: string;
-      refreshExpiresIn: string;
-    };
-  };
+  auth: AuthConfig;
   cors: { origins: string[]; maxAgeSeconds: number };
   monitor: { enabled: boolean; sessionExpiresIn: string };
 }
@@ -101,12 +94,21 @@ export function parseDatabases(env: Env): Record<string, DatabaseConfig> {
   );
 }
 
+/** Proxies in front of the app (Azure App Service, gateway): 0 = connect directly, use the socket IP. */
+export function trustProxyHops(env: Env): number {
+  const hops = int(env, 'HTTP_TRUST_PROXY_HOPS', 0);
+  if (hops < 0 || hops > 10) {
+    throw new Error('HTTP_TRUST_PROXY_HOPS must be an integer between 0 and 10');
+  }
+  return hops;
+}
+
 /** Pure: builds the configuration from an env object (tests pass their own). */
 export function buildConfiguration(env: Env): AppConfig {
   const cacheEnabled = bool(env, 'CACHE_ENABLED', false);
   const nodeEnv = text(env, 'NODE_ENV', 'development');
   return {
-    app: { nodeEnv, port: int(env, 'PORT', 3000) },
+    app: { nodeEnv, port: int(env, 'PORT', 3000), trustProxyHops: trustProxyHops(env) },
     logging: {
       level: text(env, 'LOG_LEVEL', 'info'),
       format: parseLogFormat(env.LOG_FORMAT, nodeEnv),
@@ -119,15 +121,7 @@ export function buildConfiguration(env: Env): AppConfig {
       keyPrefix: text(env, 'CACHE_KEY_PREFIX', 'arness'),
       opTimeoutMs: int(env, 'CACHE_OP_TIMEOUT_MS', 200),
     },
-    auth: {
-      accessToken: required(env, 'ACCESS_TOKEN'),
-      jwt: {
-        accessSecret: required(env, 'JWT_ACCESS_SECRET'),
-        accessExpiresIn: text(env, 'JWT_ACCESS_EXPIRES_IN', '15m'),
-        refreshSecret: required(env, 'JWT_REFRESH_SECRET'),
-        refreshExpiresIn: text(env, 'JWT_REFRESH_EXPIRES_IN', '7d'),
-      },
-    },
+    auth: parseAuthConfig(env),
     cors: {
       origins: parseCorsOrigins(env.CORS_ORIGINS),
       maxAgeSeconds: parseCorsMaxAge(env.CORS_MAX_AGE_SECONDS),

package/harness/skills/nest-base/templates/docs/EVOLUTIVO.md

@@ -8,15 +8,20 @@ Trazabilidad de lo que se ha entregado en el proyecto, en orden cronológico. Ca
 Formato de cada entrada (lenguaje entendible para negocio):
 
 ```markdown
-## AAAA-MM-DD · <cliente>/<módulo>
+## AAAA-MM-DD HH:mm -0500 · <cliente>/<módulo>
 
+- **Responsable:** <nombre de quien hizo la entrega>.
 - **Entregado:** <qué se puede hacer ahora, en una o dos frases>.
 - **Detalle técnico:** <endpoint, conexión, widget o cambio de contrato>.
 - **Referencia:** <commit, PR o tag>.
 ```
 
-## AAAA-MM-DD · Base del proyecto
+- **Fecha y hora:** hora de Bogotá, Colombia (UTC-5), del momento en que se registra la entrega: `TZ=America/Bogota date '+%Y-%m-%d %H:%M %z'`.
+- **Responsable:** la persona que trabaja en ese momento, según `git config user.name`. Si está vacío, se le pregunta; nunca se pone el nombre de un agente.
 
+## AAAA-MM-DD HH:mm -0500 · Base del proyecto
+
+- **Responsable:** <git config user.name>.
 - **Entregado:** base del backend lista para agregar reportes: autenticación, salud del servicio y caché.
 - **Detalle técnico:** proyecto NestJS creado con la skill `nest-base` del harness.
 - **Referencia:** <commit inicial>.

package/harness/skills/nest-base/templates/e2e/monitor.e2e-spec.ts

@@ -7,6 +7,7 @@ import { App } from 'supertest/types';
 import { MonitorModule } from '../src/common/monitor/monitor.module';
 import { MONITOR_WIDGETS, MonitorWidget } from '../src/common/monitor/monitor-widget.interface';
 import { EndpointsTotalWidget } from '../src/common/monitor/widgets/endpoints-total.widget';
+import { SecurityModule } from '../src/common/security/security.module';
 
 @Controller('cartera')
 class CarteraController {
@@ -42,9 +43,11 @@ async function createApp(enabled: boolean): Promise<INestApplication<App>> {
             MONITOR_SESSION_EXPIRES_IN: '15m',
             ACCESS_TOKEN: 'example123',
             JWT_ACCESS_SECRET: 'e2e-access-secret-with-enough-length',
+            auth: { login: { maxAttempts: 3, windowSeconds: 60 } },
           }),
         ],
       }),
+      SecurityModule,
       MonitorModule,
     ],
     controllers: [CarteraController, HealthController],
@@ -125,6 +128,20 @@ describe('Monitor (e2e)', () => {
     expect(String(res.headers['set-cookie'])).toContain('arness_monitor=; Max-Age=0');
   });
 
+  it('answers 429 with Retry-After after too many wrong passwords, even with the right one', async () => {
+    const limited = await createApp(true);
+    const attempt = (password: string): request.Test =>
+      request(limited.getHttpServer()).post('/monitor/login').type('form').send({ password });
+    for (let i = 0; i < 3; i += 1) expect((await attempt('wrong')).status).toBe(401);
+
+    const res = await attempt('example123');
+    expect(res.status).toBe(429);
+    expect(Number(res.headers['retry-after'])).toBeGreaterThan(0);
+    expect(res.headers['set-cookie']).toBeUndefined();
+    expect(res.text).toContain('Demasiados intentos');
+    await limited.close();
+  });
+
   it('answers 404 when MONITOR_ENABLED=false', async () => {
     const disabled = await createApp(false);
     await request(disabled.getHttpServer()).get('/monitor').expect(404);

package/harness/skills/nest-base/templates/monitor/monitor.controller.ts

@@ -1,6 +1,7 @@
 // Plantilla del harness → src/common/monitor/monitor.controller.ts
-import { Body, Controller, Get, Post, Res, UseFilters, UseGuards } from '@nestjs/common';
-import type { Response } from 'express';
+import { Body, Controller, Get, Post, Req, Res, UseFilters, UseGuards } from '@nestjs/common';
+import type { Request, Response } from 'express';
+import { LoginAttemptLimiter } from '../security/login-attempts';
 import {
   MONITOR_HOME_URL,
   MONITOR_LOGIN_URL,
@@ -28,6 +29,7 @@ export class MonitorController {
   constructor(
     private readonly monitor: MonitorService,
     private readonly session: MonitorSessionService,
+    private readonly attempts: LoginAttemptLimiter,
   ) {}
 
   @Get()
@@ -43,11 +45,30 @@ export class MonitorController {
 
   @MonitorLogin()
   @Post('login')
-  async login(@Body() body: MonitorLoginDto, @Res() res: Response): Promise<void> {
+  async login(
+    @Body() body: MonitorLoginDto,
+    @Req() req: Request,
+    @Res() res: Response,
+  ): Promise<void> {
+    // Same limiter as /auth/login (contrato-http.md, Límite de intentos).
+    const client = req.ip ?? 'unknown';
+    const status = this.attempts.check(client);
+    if (!status.allowed) {
+      const minutes = Math.ceil(status.retryAfterSeconds / 60);
+      res.setHeader('Retry-After', String(status.retryAfterSeconds));
+      sendHtml(
+        res,
+        429,
+        renderLoginPage(`Demasiados intentos. Intenta de nuevo en ${minutes} min.`),
+      );
+      return;
+    }
     if (!this.session.verifyPassword(body.password)) {
+      this.attempts.registerFailure(client);
       sendHtml(res, 401, renderLoginPage('Contraseña incorrecta'));
       return;
     }
+    this.attempts.reset(client);
     res
       .set(MONITOR_SECURITY_HEADERS)
       .setHeader('Set-Cookie', await this.session.createSessionCookie());

package/harness/skills/nest-base/templates/security/login-attempts.spec.ts

@@ -0,0 +1,48 @@
+// Plantilla del harness → src/common/security/login-attempts.spec.ts
+import { LoginAttemptLimiter } from './login-attempts';
+
+describe('LoginAttemptLimiter', () => {
+  let now: number;
+  const limiter = (maxTrackedClients?: number): LoginAttemptLimiter =>
+    new LoginAttemptLimiter({ maxAttempts: 3, windowSeconds: 60, maxTrackedClients }, () => now);
+
+  beforeEach(() => {
+    now = 1_000_000;
+  });
+
+  it('blocks a client after maxAttempts failures until the window ends', () => {
+    const attempts = limiter();
+    expect(attempts.registerFailure('10.0.0.1')).toEqual({ allowed: true, retryAfterSeconds: 0 });
+    attempts.registerFailure('10.0.0.1');
+    expect(attempts.registerFailure('10.0.0.1')).toEqual({ allowed: false, retryAfterSeconds: 60 });
+
+    now += 59_500;
+    expect(attempts.check('10.0.0.1')).toEqual({ allowed: false, retryAfterSeconds: 1 });
+
+    now += 500;
+    expect(attempts.check('10.0.0.1')).toEqual({ allowed: true, retryAfterSeconds: 0 });
+  });
+
+  it('counts each client separately', () => {
+    const attempts = limiter();
+    for (let i = 0; i < 3; i += 1) attempts.registerFailure('10.0.0.1');
+    expect(attempts.check('10.0.0.1').allowed).toBe(false);
+    expect(attempts.check('10.0.0.2').allowed).toBe(true);
+  });
+
+  it('a successful login resets the counter', () => {
+    const attempts = limiter();
+    attempts.registerFailure('10.0.0.1');
+    attempts.registerFailure('10.0.0.1');
+    attempts.reset('10.0.0.1');
+    expect(attempts.registerFailure('10.0.0.1').allowed).toBe(true);
+  });
+
+  it('never tracks more than maxTrackedClients', () => {
+    const attempts = limiter(2);
+    for (let i = 0; i < 3; i += 1) attempts.registerFailure('10.0.0.1');
+    attempts.registerFailure('10.0.0.2');
+    attempts.registerFailure('10.0.0.3');
+    expect(attempts.check('10.0.0.1').allowed).toBe(true);
+  });
+});

package/harness/skills/nest-base/templates/security/login-attempts.ts

@@ -0,0 +1,90 @@
+// Plantilla del harness → src/common/security/login-attempts.ts (AGENTS.md §8, contrato-http.md "Límite de intentos").
+// Counts failed logins per client in memory: one counter per instance, never depends on Redis.
+// /auth/login and /monitor/login share it.
+
+export interface LoginAttemptOptions {
+  maxAttempts: number;
+  windowSeconds: number;
+  /** Upper bound of tracked clients, so an attacker cannot grow the map without limit. */
+  maxTrackedClients?: number;
+}
+
+export interface LoginAttemptStatus {
+  allowed: boolean;
+  /** Seconds until the client can try again (0 when allowed). Goes to the Retry-After header. */
+  retryAfterSeconds: number;
+}
+
+interface Failures {
+  count: number;
+  resetAt: number;
+}
+
+const DEFAULT_MAX_TRACKED_CLIENTS = 10000;
+
+export class LoginAttemptLimiter {
+  private readonly failures = new Map<string, Failures>();
+  private readonly maxTrackedClients: number;
+
+  constructor(
+    private readonly options: LoginAttemptOptions,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.maxTrackedClients = options.maxTrackedClients ?? DEFAULT_MAX_TRACKED_CLIENTS;
+  }
+
+  /** Call before comparing the password: a blocked client gets 429 without checking it. */
+  check(client: string): LoginAttemptStatus {
+    const entry = this.current(client);
+    if (!entry || entry.count < this.options.maxAttempts) {
+      return { allowed: true, retryAfterSeconds: 0 };
+    }
+    return { allowed: false, retryAfterSeconds: this.secondsUntil(entry.resetAt) };
+  }
+
+  /** Call after a wrong password. The window starts at the first failure. */
+  registerFailure(client: string): LoginAttemptStatus {
+    const entry = this.current(client);
+    if (entry) {
+      entry.count += 1;
+    } else {
+      this.makeRoom();
+      this.failures.set(client, {
+        count: 1,
+        resetAt: this.now() + this.options.windowSeconds * 1000,
+      });
+    }
+    return this.check(client);
+  }
+
+  /** Call after a successful login. */
+  reset(client: string): void {
+    this.failures.delete(client);
+  }
+
+  private current(client: string): Failures | undefined {
+    const entry = this.failures.get(client);
+    if (entry && entry.resetAt <= this.now()) {
+      this.failures.delete(client);
+      return undefined;
+    }
+    return entry;
+  }
+
+  private makeRoom(): void {
+    if (this.failures.size < this.maxTrackedClients) return;
+    const now = this.now();
+    for (const [client, entry] of this.failures) {
+      if (entry.resetAt <= now) this.failures.delete(client);
+    }
+    // Still full: drop the oldest entry (Map keeps insertion order).
+    if (this.failures.size >= this.maxTrackedClients) {
+      const oldest = this.failures.keys().next().value;
+      if (oldest !== undefined) this.failures.delete(oldest);
+    }
+  }
+
+  private secondsUntil(timestamp: number): number {
+    return Math.max(1, Math.ceil((timestamp - this.now()) / 1000));
+  }
+}

package/harness/skills/nest-base/templates/security/security-headers.spec.ts

@@ -0,0 +1,27 @@
+// Plantilla del harness → src/common/security/security-headers.spec.ts
+import express from 'express';
+import request from 'supertest';
+import { API_SECURITY_HEADERS, securityHeaders } from './security-headers';
+
+describe('securityHeaders', () => {
+  const app = express();
+  app.use(securityHeaders());
+  app.get('/api/v1/ping', (_req, res) => {
+    res.json({ data: 'pong' });
+  });
+
+  it('sends every security header and hides X-Powered-By', async () => {
+    const res = await request(app).get('/api/v1/ping');
+    expect(res.status).toBe(200);
+    for (const [name, value] of Object.entries(API_SECURITY_HEADERS)) {
+      expect(res.headers[name.toLowerCase()]).toBe(value);
+    }
+    expect(res.headers['x-powered-by']).toBeUndefined();
+  });
+
+  it('also covers responses that are not handled by a route', async () => {
+    const res = await request(app).get('/missing');
+    expect(res.status).toBe(404);
+    expect(res.headers['x-frame-options']).toBe('DENY');
+  });
+});

package/harness/skills/nest-base/templates/security/security-headers.ts

@@ -0,0 +1,21 @@
+// Plantilla del harness → src/common/security/security-headers.ts (AGENTS.md §9, contrato-http.md "Cabeceras de seguridad").
+// Security headers for every response, without helmet. The monitor overwrites the CSP with its own.
+import type { NextFunction, Request, Response } from 'express';
+
+export const API_SECURITY_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  'Content-Security-Policy': "default-src 'none'; frame-ancestors 'none'; base-uri 'none'",
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Referrer-Policy': 'no-referrer',
+  'Strict-Transport-Security': 'max-age=31536000',
+  'Cache-Control': 'no-store',
+});
+
+/** Express middleware: app.use(securityHeaders()) in src/main.ts, before any route. */
+export function securityHeaders(): (req: Request, res: Response, next: NextFunction) => void {
+  return (_req, res, next) => {
+    res.removeHeader('X-Powered-By');
+    res.set(API_SECURITY_HEADERS);
+    next();
+  };
+}

package/harness/skills/nest-base/templates/security/security.module.ts

@@ -0,0 +1,20 @@
+// Plantilla del harness → src/common/security/security.module.ts
+// Global: AuthController and MonitorController inject the same LoginAttemptLimiter.
+import { Global, Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { AppConfig } from '../../config/configuration';
+import { LoginAttemptLimiter } from './login-attempts';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: LoginAttemptLimiter,
+      useFactory: (config: ConfigService<AppConfig, true>): LoginAttemptLimiter =>
+        new LoginAttemptLimiter(config.get('auth.login', { infer: true })),
+      inject: [ConfigService],
+    },
+  ],
+  exports: [LoginAttemptLimiter],
+})
+export class SecurityModule {}

package/harness/skills/nest-base/templates/security/session-lifetime.spec.ts

@@ -0,0 +1,21 @@
+// Plantilla del harness → src/common/security/session-lifetime.spec.ts
+import { AUTH_TIME_CLAIM, isSessionExpired, nowInSeconds, sessionClaims } from './session-lifetime';
+
+describe('session lifetime', () => {
+  const maxAge = 3600;
+
+  it('keeps the session alive until it reaches the max age', () => {
+    const claims = sessionClaims(1000);
+    expect(claims).toEqual({ [AUTH_TIME_CLAIM]: 1000 });
+    expect(isSessionExpired(claims, maxAge, 1000 + maxAge - 1)).toBe(false);
+    expect(isSessionExpired(claims, maxAge, 1000 + maxAge)).toBe(true);
+  });
+
+  it('treats tokens without auth_time as expired', () => {
+    expect(isSessionExpired({}, maxAge, 1000)).toBe(true);
+  });
+
+  it('converts milliseconds to JWT seconds', () => {
+    expect(nowInSeconds(1_700_000_000_999)).toBe(1_700_000_000);
+  });
+});

package/harness/skills/nest-base/templates/security/session-lifetime.ts

@@ -0,0 +1,28 @@
+// Plantilla del harness → src/common/security/session-lifetime.ts (AGENTS.md §8, contrato-http.md "Autenticación").
+// A session starts at /auth/login and lasts at most AUTH_SESSION_MAX_AGE_SECONDS, however many
+// times it is refreshed: a stolen refresh token stops working when the session reaches that age.
+
+/** Claim with the login time (seconds since epoch). The refresh copies it into the new pair. */
+export const AUTH_TIME_CLAIM = 'auth_time';
+
+export interface SessionClaims {
+  [AUTH_TIME_CLAIM]?: number;
+}
+
+/** Current time in seconds, as JWT iat/exp. */
+export const nowInSeconds = (now: number = Date.now()): number => Math.floor(now / 1000);
+
+/** Claims for a new pair: login starts a session; refresh keeps the original auth_time. */
+export function sessionClaims(authTime: number): Required<SessionClaims> {
+  return { [AUTH_TIME_CLAIM]: authTime };
+}
+
+/** True if the refresh must be rejected with 401 SESSION_EXPIRED. Tokens without auth_time count as expired. */
+export function isSessionExpired(
+  claims: SessionClaims,
+  maxAgeSeconds: number,
+  now: number = nowInSeconds(),
+): boolean {
+  const authTime = claims[AUTH_TIME_CLAIM];
+  return typeof authTime !== 'number' || now - authTime >= maxAgeSeconds;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bi-analytics/arness-back",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Harness de agentes IA (Claude Code, Codex, Gemini CLI, Cursor) para backends NestJS de analítica",
   "repository": {
     "type": "git",