@bi-analytics/arness-back 0.0.0-stage → 0.3.0

package/harness/playbooks/add-database.md

@@ -0,0 +1,16 @@
+# Playbook: agregar una conexión de BD
+
+Referencia: `AGENTS.md` §6 y §13.
+
+1. **Confirmar con el humano:** el nombre lógico de la conexión (UPPER_SNAKE, ej. `REPORTS`) y qué módulos la usarán. Nunca pidas ni escribas credenciales reales en el código ni en el chat.
+2. Agrega el nombre a `DATABASES` y el bloque de variables `DB_<NOMBRE>_*` en:
+   - `.env.example`, con valores de ejemplo;
+   - `.env.local`, con valores locales de desarrollo.
+   - **No toques `.env`.**
+3. Verifica que la validación de `src/config/` exige las variables de cada nombre listado en `DATABASES`, y que `parseDatabases` de `src/config/configuration.ts` arma su bloque en `AppConfig.databases`. Normalmente no requiere cambios de código, porque ambas son dinámicas. Nunca leas `DB_<NOMBRE>_*` con `process.env` fuera de `src/config/`.
+4. En los repositories que la usen, inyecta el pool con `@Inject(getPoolToken('<NOMBRE>'))`.
+5. Confirma que `/health` reporta la nueva conexión.
+6. Documenta la conexión en el `README.md` de cada módulo que la use y en la tabla de conexiones de `docs/TECNICO.md` (solo nombre lógico y origen, nunca credenciales), y agrega una entrada en `docs/EVOLUTIVO.md`.
+7. Corre `./harness/init.sh`.
+
+Recuerda que el usuario de BD debe ser de solo lectura. El pool fuerza `default_transaction_read_only = on` como segunda barrera, no como única.

package/harness/playbooks/new-endpoint.md

@@ -0,0 +1,88 @@
+# Playbook: crear un endpoint (reporte)
+
+Referencia de reglas: `AGENTS.md` §5 (patrón), §6 (BD), §7 (caché), §9 (contrato), §12 (documentación).
+
+## 0. Confirmar el contrato (antes de escribir código)
+
+Presenta esto al humano y espera su confirmación:
+
+```
+Endpoint:     GET /api/v1/<modulo>/<segmento>
+Ubicación:    src/modules/<cliente>/<modulo>/<endpoint>/
+Conexión BD:  <NOMBRE>   Origen: <schema.tabla | vista>
+Columnas:     <col1: tipo>, <col2: tipo>, ...
+Filtros:      <nombre: tipo, obligatorio|opcional, default>
+Paginación:   sí|no  (pageSize default N, máx M)
+Orden:        <columnas permitidas>, default <col DESC>
+Caché TTL:    <segundos>
+```
+
+Si falta información, pregunta. No inventes columnas, tablas ni reglas.
+
+## 1. Archivos, en este orden
+
+1. `<endpoint>.columns.ts`: `export const X_COLUMNS = Object.freeze([...] as const)`.
+2. `<endpoint>.entity.ts`: el tipo de la fila, derivado de las columnas.
+3. `<endpoint>-query.dto.ts`: los params HTTP con `class-validator` (`@IsOptional`, `@IsDateString`, `@IsInt`, `@Min`, `@Max`, `@IsIn`).
+4. `<endpoint>-filters.dto.ts`: los filtros normalizados (fechas como `Date`, defaults aplicados, `page`/`pageSize` resueltos).
+5. `<endpoint>.sql.ts`: funciones puras `buildXQuery(filters): { text: string; values: unknown[] }` y, si pagina, `buildXCountQuery(filters)`. Todo valor va como `$n`, y el ORDER BY sale de una allowlist de `columns.ts`.
+6. `<endpoint>.repository.ts`: el token `X_REPOSITORY`, la interfaz `XRepository` y la clase `PgXRepository`, que inyecta el pool de la conexión nombrada.
+7. `<endpoint>.service.ts`: Cache-Aside con `CacheService`, y retorna `{ data, meta? }` junto al estado de caché.
+8. `<endpoint>.controller.ts`: `@Get('<segmento>')`, recibe el DTO, lo convierte en filtros, llama al service y fija `X-Cache`.
+9. Registrar controller, service y provider del repository (`{ provide: X_REPOSITORY, useClass: PgXRepository }`) en `<modulo>.module.ts`.
+
+Aplica la regla de agrupación (más de 2 archivos del mismo tipo en una carpeta → carpeta por tipo). `init.sh` verifica que el endpoint tenga todos estos archivos y los specs de la sección 2.
+
+## 2. Tests
+
+- `*.sql.spec.ts`: valida `text` y `values` para cada combinación de filtros, y que ningún valor aparezca interpolado en `text`.
+- `*.service.spec.ts`: HIT, MISS, BYPASS (caché lanza error o está deshabilitada), con y sin paginación.
+- `*.controller.spec.ts`: delega al service y fija `X-Cache`.
+- `*.repository.spec.ts`: con pool mockeado, verifica que ejecuta el SQL del builder y mapea las filas.
+- `*-query.dto.spec.ts`: casos válidos e inválidos.
+- E2E en `test/`: 401 sin token, 200 con token y envelope correcto, 400 con filtro inválido.
+
+## 3. Documentación
+
+### Postman
+
+Agrega la request en `postman/arness-back.postman_collection.json`, dentro de la carpeta `<cliente>/<modulo>`:
+- `GET {{baseUrl}}/api/v1/<modulo>/<segmento>?param=ejemplo`
+- Auth: heredada de la colección (`Bearer {{accessToken}}`)
+- Sin descripciones largas.
+
+### FRONT.md
+
+Agrega una sección con esta plantilla:
+
+````markdown
+### <Nombre legible del reporte>
+
+`GET /api/v1/<modulo>/<segmento>` · requiere `Authorization: Bearer <accessToken>`
+
+Qué devuelve: <una frase>.
+
+| Parámetro | Tipo | Obligatorio | Ejemplo |
+|---|---|---|---|
+| desde | fecha ISO | sí | 2026-01-01 |
+| page | número | no (default 1) | 1 |
+
+```json
+{ "data": [{ "col1": "…", "col2": 0 }], "meta": { "pagination": { "page": 1, "pageSize": 50, "total": 120, "totalPages": 3 } } }
+```
+
+**Consumo recomendado:** <paginar con pageSize ≤ N | traer completo>; <filtros a enviar siempre>; ante `401 TOKEN_EXPIRED`, llamar a `/auth/refresh` y reintentar una vez; datos cacheados en servidor por <TTL>, así que no hace falta hacer polling más frecuente.
+````
+
+### README del módulo
+
+Agrega el endpoint, su conexión y el origen de datos.
+
+### docs/
+
+- `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
+
+Corre `./harness/init.sh` y revisa el Definition of Done de `AGENTS.md` §15.

package/harness/playbooks/new-module.md

@@ -0,0 +1,21 @@
+# Playbook: crear un módulo o cliente
+
+Referencia: `AGENTS.md` §4 y §5.
+
+1. **Confirmar con el humano:** nombre del cliente (carpeta de primer nivel), nombre del módulo, segmento base de la URL y conexión de BD por defecto.
+2. **Cliente nuevo:** crea `src/modules/<cliente>/`. Si se quiere agrupar sus módulos, agrega `<cliente>.module.ts` que los importe, y regístralo en `app.module.ts`.
+3. **Módulo nuevo:** crea `src/modules/<cliente>/<modulo>/` con:
+   - `<modulo>.module.ts`: `@Module({ controllers: [], providers: [] })`, sin imports de otros módulos de negocio. El código del módulo solo importa de su propia carpeta, de `src/common/` y de `src/config/` (ESLint lo verifica).
+   - `README.md` con esta plantilla:
+     ```markdown
+     # <Módulo>
+     Propósito: <una frase>.
+     Conexión BD: <NOMBRE>.
+     | Endpoint | Origen de datos | Caché TTL |
+     |---|---|---|
+     ```
+4. Registra el módulo en su padre (el módulo del cliente o `app.module.ts`).
+5. Crea la carpeta `<cliente>/<modulo>` en la colección de Postman y un encabezado `## <Módulo>` en `FRONT.md`.
+6. Agrega endpoints con `new-endpoint.md`.
+7. Agrega el módulo a la tabla de módulos de `docs/TECNICO.md` y una entrada en `docs/EVOLUTIVO.md` (solo avance; lo abierto va a `docs/PENDIENTES.md`).
+8. Corre `./harness/init.sh`.

package/harness/playbooks/new-monitor-widget.md

@@ -0,0 +1,31 @@
+# Playbook: agregar un widget al monitor
+
+Referencia: `AGENTS.md` §10 y §13, y `harness/reference/contrato-http.md` (Monitor). El monitor ya existe en `src/common/monitor/` (skill `nest-base`).
+
+## 0. Confirmar con el humano
+
+```
+Widget:      <id-kebab>  ·  Título: <texto corto>  ·  Orden: <número>
+Muestra:     <qué cifra o estado técnico>  ·  Desglose: <sí/no, por qué>
+Origen:      <de dónde sale el dato: Nest, pool, caché, process>
+Costo:       <consultas o llamadas por carga de página>
+```
+
+**Qué puede mostrar:** conteos, estados (`up`/`down`), versiones, uptime, tamaños de pool y latencias agregadas.
+**Qué nunca muestra:** secretos o variables de entorno, SQL, mensajes de error de PostgreSQL o Redis, hosts o usuarios de BD, y datos de negocio (filas, montos, nombres de clientes). Si el humano pide algo de esta lista, detente: requiere una decisión en `harness/decisiones/`.
+
+## 1. Implementar
+
+1. Crea `src/common/monitor/widgets/<id>.widget.ts`: una clase `@Injectable()` que implementa `MonitorWidget` (`id`, `title`, `order`, `collect(): Promise<MonitorValue>`).
+2. `collect()` debe ser barato y de solo lectura: sin escrituras, sin SQL de negocio y sin depender de Redis. Si necesita la BD, usa una consulta técnica en un `*.sql.ts` y el repository de `common/`; si falla, deja que lance: el monitor lo muestra como "No disponible" y registra solo el tipo de error.
+3. Regístrala en `src/common/monitor/monitor.module.ts`, agregándola al arreglo `WIDGETS`. El multi-provider `MONITOR_WIDGETS` la recoge sola.
+4. `src/common/` no importa de `src/modules/`. Si el dato es de un módulo de negocio, no va al monitor base: regístralo como decisión.
+
+## 2. Tests
+
+- `<id>.widget.spec.ts`: el valor y el desglose esperados, y que un error del origen se propaga (no se traga ni se formatea).
+- Si cambia el HTML, ajusta `test/monitor.e2e-spec.ts` para que siga comprobando que no hay `<script>` y que un widget con error no rompe la página.
+
+## 3. Cierre
+
+Agrega una entrada en `docs/EVOLUTIVO.md` (qué muestra ahora el monitor). Corre `./harness/init.sh` y revisa el checklist de `harness/playbooks/review.md` (un widget con datos sensibles es bloqueante).

package/harness/playbooks/review.md

@@ -0,0 +1,41 @@
+# Playbook: revisar un cambio
+
+Revisa el diff contra `AGENTS.md` y reporta cada hallazgo con archivo y línea, del más grave al menos grave.
+
+## Bloqueantes
+
+- [ ] SQL fuera de `*.sql.ts`, o valores concatenados o interpolados en SQL
+- [ ] `ORDER BY` o nombres de columna que no salen de una allowlist
+- [ ] Cualquier escritura, DDL o migración
+- [ ] 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
+- [ ] `process.env` fuera de `src/config/` en código nuevo (salvo tests), o un secreto con valor por defecto en `configuration.ts`
+- [ ] Una dependencia nueva sin aprobación
+- [ ] La API falla si Redis está caído o deshabilitado
+- [ ] Se editó la base del harness (`AGENTS.md`, puentes o playbooks) en lugar de registrar la decisión en `harness/decisiones/`
+- [ ] El cambio contradice una decisión `Aceptada` de `harness/decisiones/`, o toma una decisión nueva sin registrarla
+- [ ] `./harness/init.sh` termina en 1 (crítico, `--strict` o `required`), o el cambio agrega advertencias nuevas respecto a la línea base
+- [ ] Se silenció un chequeo en `harness/arness.config.json` sin aprobación humana o sin motivo
+
+## Contrato y arquitectura
+
+- [ ] Estructura del endpoint según §5, y regla de agrupación (más de 2 archivos del mismo tipo en una carpeta)
+- [ ] Fronteras: `common/` no importa de `modules/` y ningún módulo importa de otro módulo o cliente
+- [ ] El service depende de la interfaz del repository, no de `pg`
+- [ ] Envelope `{ data, meta? }` y errores `{ error: {...} }` con el status correcto
+- [ ] Si cambió `.columns.ts` o los filtros, `FRONT.md` está actualizado y la versión de la clave de caché subió
+
+## Completitud
+
+- [ ] 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), 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
+- [ ] Código en inglés, docs en español, commit con formato Conventional Commits

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

@@ -0,0 +1,111 @@
+# Referencia: variables de entorno
+
+Parte de la base del harness (AGENTS.md §6 a §10). Todas las variables:
+- se declaran en `.env.example` con valores de ejemplo y en `.env.local` con valores locales;
+- se validan en `src/config/` al arrancar.
+
+`.env` nunca lo toca un agente. Si falta una variable requerida, la app falla al arrancar con un mensaje claro.
+
+## Dónde se leen las variables
+
+`process.env` se lee **solo** en `src/config/configuration.ts` (plantilla `harness/skills/nest-base/templates/config/`). Ese archivo agrupa las variables por tema y convierte sus tipos; el resto del código recibe la configuración ya tipada.
+
+```typescript
+// src/config/configuration.ts (extracto)
+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: parseAuthConfig(env), // src/config/auth.ts: secretos, límite de intentos y vida de la sesión
+    // cache, cors, monitor...
+  };
+}
+export default (): AppConfig => buildConfiguration(process.env);
+```
+
+- **Registro:** `ConfigModule.forRoot({ isGlobal: true, envFilePath: ['.env.local', '.env'], validate, load: [configuration] })`. La validación (class-validator) revisa las variables crudas; `configuration.ts` solo agrupa y convierte.
+- **Consumo:** `ConfigService<AppConfig, true>` con rutas tipadas, por ejemplo `config.get('cache.enabled', { infer: true })`. También en `main.ts` (`app.get(ConfigService)`): ni siquiera el puerto se lee de `process.env`.
+- **Secretos sin valor por defecto** (`ACCESS_TOKEN`, `JWT_*_SECRET`, `DB_*_PASSWORD`): si faltan, la app no arranca. El error nombra la variable, nunca su valor. Los defaults son solo para valores no sensibles.
+- **Tests:** los specs y `test/` pueden preparar `process.env`; `buildConfiguration(env)` es una función pura que se prueba con un objeto propio.
+- **Verificación:** ESLint (`configBoundaries` de `eslint.boundaries.mjs`, regla `no-restricted-properties`) e `init.sh` (`env.process-env`, `env.configuration-file`, `env.eslint`).
+
+**Agregar una variable** es, en el mismo cambio: `.env.example` + `.env.local` + validación + `configuration.ts` (y su tipo `AppConfig`) + esta referencia.
+
+## App
+
+```dotenv
+NODE_ENV=development             # development | test | production (default development)
+PORT=3000
+LOG_LEVEL=info                   # en desarrollo se recomienda debug
+LOG_FORMAT=json                  # json (default, producción) | pretty (solo desarrollo local)
+```
+
+- `LOG_FORMAT=pretty` requiere `pino-pretty` en devDependencies y no se acepta con `NODE_ENV=production`. `.env.local` usa `pretty`; `.env.example` documenta `json`.
+
+## Bases de datos (conexiones nombradas)
+
+```dotenv
+DATABASES=MAIN,REPORTS          # una sola BD: DATABASES=MAIN
+
+DB_MAIN_HOST=localhost
+DB_MAIN_PORT=5432
+DB_MAIN_NAME=analytics
+DB_MAIN_USER=readonly_user
+DB_MAIN_PASSWORD=change-me
+DB_MAIN_SSL=false
+DB_MAIN_POOL_MAX=10
+DB_MAIN_STATEMENT_TIMEOUT_MS=30000
+
+DB_REPORTS_HOST=...             # mismo bloque por cada nombre en DATABASES
+```
+
+- `common/database` crea un `Pool` por nombre y lo expone con `getPoolToken('<NOMBRE>')`.
+- Requeridas por conexión: `HOST`, `PORT`, `NAME`, `USER` y `PASSWORD`. `init.sh` las verifica en `.env.example`.
+
+## Caché
+
+```dotenv
+CACHE_ENABLED=true
+REDIS_URL=redis://localhost:6379
+CACHE_DEFAULT_TTL_SECONDS=300
+CACHE_KEY_PREFIX=arness
+CACHE_OP_TIMEOUT_MS=200
+```
+
+## Autenticación
+
+```dotenv
+ACCESS_TOKEN=example123          # contraseña compartida para /auth/login
+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
+CORS_ORIGINS=http://localhost:4200,https://reportes.example.com   # obligatoria; orígenes exactos separados por comas
+CORS_MAX_AGE_SECONDS=600                                           # opcional; caché del preflight (0–86400)
+```
+
+- `CORS_ORIGINS` es **obligatoria**: sin ella la app no arranca. No admite `*` ni comodines, solo orígenes (`esquema://host[:puerto]`, sin ruta), y exige `https://` salvo `localhost`, `127.0.0.1` y `[::1]`.
+- Cada entorno define su lista (desarrollo, QA, producción). `init.sh` verifica que `.env.example` la define y que no lleva `*`.
+
+## Monitor
+
+```dotenv
+MONITOR_ENABLED=false             # true para habilitar GET /monitor; con false responde 404
+MONITOR_SESSION_EXPIRES_IN=15m    # duración de la cookie de sesión del monitor
+```
+
+- Por defecto `false`. Habilítalo solo donde el equipo lo necesite; en producción requiere aprobación.
+- El login usa `ACCESS_TOKEN` y la sesión se firma con `JWT_ACCESS_SECRET`: no hay secretos nuevos.
+- Si existe `src/common/monitor/`, `init.sh` verifica que `.env.example` define ambas variables.

package/harness/reference/contrato-http.md

@@ -0,0 +1,169 @@
+# Referencia: contrato HTTP
+
+Parte de la base del harness (AGENTS.md §8, §9 y §10).
+
+## Respuesta exitosa
+
+`meta` aparece **solo** cuando el endpoint pagina o filtra.
+
+```jsonc
+// Sin paginación ni filtros
+{ "data": [ /* filas */ ] }
+
+// Con paginación y/o filtros
+{
+  "data": [ /* filas */ ],
+  "meta": {
+    "pagination": { "page": 1, "pageSize": 50, "total": 1234, "totalPages": 25 },
+    "filters": { "desde": "2026-01-01", "regional": "ANT" }
+  }
+}
+```
+
+## Respuesta de error
+
+Siempre con el status HTTP correcto. `details` es opcional.
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "El parámetro 'desde' debe ser una fecha ISO",
+    "details": [{ "field": "desde", "issue": "isDateString" }],
+    "requestId": "b1f2c3...",
+    "path": "/api/v1/cartera/resumen",
+    "timestamp": "2026-09-25T14:00:00.000Z"
+  }
+}
+```
+
+| Status | `code` | Origen típico |
+|---|---|---|
+| 400 | `VALIDATION_ERROR` | DTO inválido |
+| 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 |
+
+## Autenticación
+
+| Endpoint | Body | Respuesta |
+|---|---|---|
+| `POST /api/v1/auth/login` | `{ "password": "..." }` | `{ data: { accessToken, refreshToken, expiresIn } }` |
+| `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. 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
+
+Allowlist por entorno: solo los orígenes de `CORS_ORIGINS` reciben `Access-Control-Allow-Origin`. Implementación de referencia: `harness/skills/nest-base/templates/cors/cors.ts` → `src/config/cors.ts`.
+
+| Opción de `app.enableCors()` | Valor |
+|---|---|
+| `origin` | función que acepta solo los orígenes exactos de `CORS_ORIGINS` (sin `Origin` → sin cabeceras CORS) |
+| `methods` | `GET, POST, OPTIONS` |
+| `allowedHeaders` | `Authorization, Content-Type, X-Request-Id` |
+| `exposedHeaders` | `X-Cache, X-Request-Id` |
+| `credentials` | `false` (la API usa `Bearer`, no cookies) |
+| `maxAge` | `CORS_MAX_AGE_SECONDS` (default 600) |
+| `optionsSuccessStatus` | `204` |
+
+- **Validación al arrancar** (`src/config/`): `CORS_ORIGINS` es obligatoria; se rechazan `*` y comodines, valores que no son un origen (`esquema://host[:puerto]`, sin ruta) y `http://` fuera de `localhost`, `127.0.0.1` o `[::1]`.
+- **Prohibido:** `enableCors()` sin opciones, `origin: true`, `origin: '*'`, reflejar el `Origin` recibido o `credentials: true`.
+- **Tests:** `src/config/cors.spec.ts` (parseo y validación) y `test/cors.e2e-spec.ts`: preflight permitido → `204` con `Access-Control-Allow-Origin`, métodos, cabeceras y `max-age`; preflight de un origen no permitido → sin `Access-Control-Allow-Origin`.
+- `init.sh` advierte si `.env.example` no define `CORS_ORIGINS` o lo define con `*`, y si `src/main.ts` no llama a `enableCors` o lo abre a cualquier origen.
+
+## Caché
+
+- Header `X-Cache: HIT | MISS | BYPASS` en toda respuesta cacheable.
+- Clave: `<prefix>:<cliente>:<modulo>:<endpoint>:v<version>:<hash-estable-de-filtros>`. El hash se calcula con sha256 sobre el JSON de los filtros con las claves ordenadas.
+
+## Logging
+
+- JSON estructurado (`nestjs-pino`). `requestId` desde `X-Request-Id` (si es seguro: `[A-Za-z0-9._-]`, máximo 128) o UUID generado, devuelto en la respuesta.
+- Por request: método, ruta, status, duración, resultado de caché y conexión de BD.
+- Redact: `authorization`, cookies (`cookie` y `set-cookie`), `password`, `accessToken`, `refreshToken`, `*_SECRET` y `*_PASSWORD`.
+- Plantilla: `harness/skills/nest-base/templates/logging/logger-options.ts` (`buildLoggerParams`, `parseLogFormat`, `REDACT_PATHS`).
+
+### Formato por entorno (`LOG_FORMAT`)
+
+| Entorno | `LOG_FORMAT` | Ejemplo |
+|---|---|---|
+| Producción, QA, CI (y por defecto) | `json` | `{"level":30,"requestId":"a1b2c3","req":{"method":"GET","url":"/api/v1/cartera/resumen"},"res":{"statusCode":200},"responseTime":42,"msg":"GET /api/v1/cartera/resumen 200 42ms"}` |
+| Desarrollo local | `pretty` | `10:21:03 INFO: [a1b2c3] GET /api/v1/cartera/resumen 200 42ms {"cache":"HIT"}` |
+
+- Ambos formatos llevan los mismos campos y la **misma redacción**: el formato legible nunca muestra secretos.
+- `pretty` usa `pino-pretty`, que es **devDependency**: la imagen de producción no lo incluye. Si se pide `pretty` y no está instalado, el logger vuelve a JSON.
+- La validación rechaza `LOG_FORMAT=pretty` con `NODE_ENV=production`, y cualquier valor distinto de `json` o `pretty`.
+- Los logs no incluyen el SQL ejecutado ni sus parámetros en ningún formato.
+
+## Health
+
+`GET /health` es público y usa terminus. Indicadores:
+- `db_<nombre en minúsculas>`, uno por conexión;
+- `cache`, con estado `up`, `down` o `disabled`.
+
+| Situación | Respuesta |
+|---|---|
+| Todas las BDs arriba | `200` |
+| Alguna BD caída | `503` |
+| Redis caído o deshabilitado | sigue en `200`; `cache: down / disabled` |
+
+`init.sh` consume este formato para informar qué base está caída.
+
+## Monitor
+
+Tablero de estado para el equipo, **fuera de `/api/v1`** y apagado por defecto. Implementación de referencia: `harness/skills/nest-base/templates/monitor/` → `src/common/monitor/`.
+
+| Ruta | Sesión | Respuesta |
+|---|---|---|
+| `GET /monitor` | cookie | HTML con los widgets; sin sesión → `303` a `/monitor/login` |
+| `GET /monitor/login` | — | formulario HTML (`password`) |
+| `POST /monitor/login` | — | correcta → `303` a `/monitor` y `Set-Cookie`; incorrecta → `401` con el formulario y sin cookie |
+| `POST /monitor/logout` | — | borra la cookie (`Max-Age=0`) y `303` a `/monitor/login` |
+
+- **Activación:** `MONITOR_ENABLED=true`. Con cualquier otro valor, todas las rutas responden `404`.
+- **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()`.
+- **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).
+- **Nunca se muestran:** secretos, variables de entorno, SQL, errores de PostgreSQL ni datos de negocio (filas, montos, nombres de clientes). Solo conteos y estados técnicos.
+- **Tests:** unit de servicio, página, sesión, guard y widget; e2e `test/monitor.e2e-spec.ts` (redirección sin cookie, `401` sin cookie con contraseña incorrecta, login y conteo correcto con controllers de prueba, widget con error que no rompe la página, sin `<script>`, `404` con `MONITOR_ENABLED=false`).