@growconnect/growtickets-nest 0.0.0-stage → 0.1.0

package/.env.example

@@ -0,0 +1,2 @@
+GROWTICKETS_URL=
+GROWTICKETS_API_KEY=

package/README.md

@@ -1,3 +1,414 @@
-# Temporary Holding Version
+# @growconnect/growtickets-nest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GrowTickets para **NestJS** (10, 11 y 12, con **Express o Fastify**), en dos mitades que no se necesitan entre sí:
+
+- **El proxy del portal**: guarda `GROWTICKETS_API_KEY`, firma quién reporta con la sesión del producto y reenvía a
+  `api/ingest` por una lista blanca de 9 rutas. Es el mismo contrato que `growtickets-laravel` y
+  `@growconnect/growtickets-next-server`: el front que ya tienes (`@growconnect/growtickets-ng`, `-next-react`,
+  `growtickets_flutter` o los componentes web) funciona encima sin cambiar nada.
+- **La seguridad del producto** (opcional, apagada por defecto): manda a la mesa de ayuda lo que ve pasar, **corta a
+  las IP que ella bloquee**, contesta la ruta de salud con la que sabe si el producto se cayó y reenvía la lista de
+  paquetes de tu front. Ver [Seguridad y disponibilidad](#seguridad-y-disponibilidad).
+
+No trae pantallas: Nest es tu backend y el portal lo pinta tu front.
+
+## Instalación
+
+```bash
+npm install @growconnect/growtickets-nest
+npx growtickets-nest init     # .env.example y .gitignore, e imprime los dos fragmentos de abajo
+```
+
+Necesita Node 18.18+ y, como `peerDependencies`, los `@nestjs/common` y `@nestjs/core` que ya tienes (10, 11 o 12),
+`reflect-metadata` y `rxjs`. Nest 12 sólo se publica como ESM y este paquete es CommonJS: tu app lo importa igual
+(`import { GrowTicketsModule } from '@growconnect/growtickets-nest'`), con **Node 20.19+ o 22.12+**, que son los que cargan
+ESM desde CommonJS. Pon en tu `.env` la dirección de tu GrowTickets y la clave de la pestaña «Claves de API» del proyecto:
+
+```dotenv
+GROWTICKETS_URL=https://…          # obligatoria: la dirección de la mesa de ayuda
+GROWTICKETS_API_KEY=gt_live_…
+```
+
+`GROWTICKETS_URL` **no tiene valor por defecto**: uno que no fuera la mesa de ayuda se llevaría la clave de quien olvide
+configurarla. Tiene que ser `https`, salvo un nombre que no sale de tu máquina o de pruebas (`localhost`, `*.localhost`,
+`*.test`, `127.0.0.1`), sin importar `NODE_ENV`.
+
+## Montarlo
+
+Son dos piezas. El módulo, en tu `AppModule`:
+
+```ts
+import { AuthGuard } from '@nestjs/passport';
+import { GrowTicketsModule } from '@growconnect/growtickets-nest';
+
+@Module({
+  imports: [
+    GrowTicketsModule.forRoot({
+      guards: [AuthGuard('jwt')],
+      resolveReporter: (req: Request & { user?: Usuario }) =>
+        req.user ? { id: String(req.user.id), name: req.user.nombre, email: req.user.email } : null,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Y una línea en `main.ts`, antes de `listen()`:
+
+```ts
+import { growTicketsMiddleware } from '@growconnect/growtickets-nest';
+
+const app = await NestFactory.create<NestExpressApplication>(AppModule);
+app.use(growTicketsMiddleware(app));
+app.useBodyParser('json', { limit: '256kb' });   // sólo con Express: su tope de serie es 100 KB
+await app.listen(3000);
+```
+
+El portal queda en **`/api/soporte`**, el `baseUrl` por defecto de todos los fronts, con sus 9 rutas y además
+`GET /api/soporte/unread` para el [lanzador del componente web](#el-componente-web-growtickets-launcher).
+`npx growtickets-nest check` avisa si falta alguna de las dos piezas.
+
+- **El middleware va en `main.ts` y no dentro del módulo** a propósito: un middleware de módulo (`consumer.apply()`)
+  sólo ve las rutas bajo el prefijo global, y se perderían la ruta de salud, el relevo del front y los escáneres que
+  piden `/.env`. Sin él el portal funciona igual; lo que falta es la seguridad.
+- **El tope de Express**: su parser de JSON corta en 100 KB y un mensaje largo del portal (el contrato admite 256 KB)
+  recibiría un 413 antes de llegar al proxy. Fastify trae 1 MB y no hace falta tocar nada.
+- **Con un prefijo global** (`app.setGlobalPrefix('api')`) el prefijo se suma: pasa `path: 'soporte'` para que siga en
+  `/api/soporte`. `path` acepta cualquier ruta (`'ayuda/portal'`), y el front se configura con esa.
+
+### `resolveReporter`: la única pieza que tienes que escribir
+
+Es obligatorio y sin valor por defecto — Nest no tiene un `auth()->user()` universal, así que la librería no puede
+adivinar cómo autentica tu producto. `null` responde 401 **sin llamar** a la ingesta. La identidad tiene que salir de
+la SESIÓN (`req.user`, que llenan los `guards`), nunca de los parámetros, la query o el cuerpo: el proxy borra
+`reporter`, `reporter_id`, `internal` y `external_user_id` de todo lo que llega del navegador y los repone desde aquí.
+
+- `guards` son los del producto, y corren antes de `resolveReporter` (`AuthGuard('jwt')`, el tuyo de sesión…). Si el
+  guard necesita providers de otro módulo, pásalo en `imports`.
+- Recibe la petición de Nest: la de Express o la de Fastify, la que ya usas en tus controladores.
+- El `id` tiene que ser ESTABLE: es lo único que ata a una persona con su historial.
+
+### Con `ConfigService`, o cualquier dependencia: `forRootAsync`
+
+```ts
+GrowTicketsModule.forRootAsync({
+  path: 'soporte',                    // la ruta, los guards y los imports van FUERA de la fábrica:
+  guards: [JwtAuthGuard],             // Nest los necesita al declarar el controlador
+  imports: [UsuariosModule],
+  inject: [UsuariosService, DataSource],
+  useFactory: (usuarios: UsuariosService, db: DataSource) => ({
+    resolveReporter: (req) => usuarios.comoReportante(req.user),
+    security: { checks: { database: () => db.query('select 1') } },
+  }),
+});
+```
+
+### El front en otro dominio: CORS y `allowedOrigins`
+
+Lo normal con Nest es que el front viva aparte (`app.tuproducto.co` contra `api.tuproducto.co`). El proxy tiene una
+valla anti-CSRF: todo `POST` exige `Content-Type: application/json` y, en **cualquier método**, si llega `Origin` o
+`Sec-Fetch-Site`, que sea del propio origen **o esté en `allowedOrigins`**. Pon ahí los mismos orígenes que en
+`app.enableCors()`; si no, el portal da 403. Vale también para `GET`: con la sesión en una cookie, un CORS que refleja
+cualquier origen (`origin: true` con `credentials: true`) dejaría a otro sitio leer los tickets de quien lo visite. El
+origen propio sale del `Host`, nunca de `X-Forwarded-Host`, que puede poner el cliente.
+
+```ts
+GrowTicketsModule.forRoot({ allowedOrigins: ['https://app.tuproducto.co'], resolveReporter });
+```
+
+### Límite por persona
+
+`throttle` (por defecto **120** peticiones por minuto y por persona, como en Laravel; `0` lo apaga). Va detrás de tu
+autenticación, así que cuenta por usuario y no por IP. Pasado el límite, 429 con `Retry-After: 60`. Vive en la memoria
+del proceso: con varios servidores, cada uno cuenta lo suyo.
+
+### El componente web: `<growtickets-launcher>`
+
+`growtickets-ng` también se compila como componentes web (`<growtickets-portal>`, `<growtickets-launcher>`) para páginas que no son
+Angular. Funcionan sobre este proxy con `base-url="/api/soporte"`. El lanzador, al cerrar el panel, pregunta a **`GET <base-url>/unread`**
+cuántas conversaciones siguen sin leer y corrige su insignia:
+
+- Contesta `{ "success": true, "data": { "count": 3 } }`, con los mismos `guards`, el mismo `resolveReporter` (sin sesión, 401) y el
+  mismo límite por persona que el portal. Pregunta siempre a la mesa de ayuda —justo acaba de leer— y nunca se guarda en caché.
+- Si la mesa de ayuda falla, es un 503 y no un «0»: la insignia se queda como estaba en vez de decir que no hay nada que leer.
+- El componente pide con `credentials: 'same-origin'`, sin `Authorization`: sirve cuando la página y la API comparten origen y la
+  sesión viaja en una cookie. Con un JWT y el front en otro dominio, usa `@growconnect/growtickets-ng` o `-next-react`, que van por
+  tu propio cliente HTTP.
+- La cifra inicial (`unread="2"`) la pinta tu servidor al servir la página: `GrowTicketsClient.sinLeer(reporter)`. Pregunta cada vez
+  y corta a los 2 segundos; si lo llamas en cada página, guárdalo un minuto como hace `growtickets-laravel`.
+
+### Lo que el proxy no deja pasar de la query
+
+La mesa de ayuda es PHP, y dos cosas de PHP harían que la identidad dejara de ser la de la sesión si el proxy reenviara
+la query a ciegas:
+
+- **El recorte de `max_input_vars`**: PHP lee hasta 1000 variables y descarta el resto en silencio. Por eso `reporter_id`
+  va **primero** en lo que se reenvía, y una query de más de 100 valores —el portal manda una decena— se rechaza con 403
+  sin llamar a la ingesta. La mesa de ayuda, además, rechaza una query que llega al tope.
+- **Las claves que PHP reescribe**: quita los espacios del principio, corta en un byte nulo y cambia `.` y ` ` por `_`,
+  así que `+internal`, `reporter.id` o `external.user.id` llegarían como `internal`, `reporter_id` y `external_user_id`.
+  Cada clave se compara con la identidad tal como la leerá PHP, y se borra.
+
+Las respuestas del proxy salen con `Cache-Control: private, no-store` y `X-Content-Type-Options: nosniff`.
+
+## Con qué versión escribe cada persona
+
+En cada llamada, el proxy le dice a la mesa de ayuda **qué versión es** y reenvía lo que dice el portal de sí mismo.
+Con eso, quien atiende ve en la ficha del ticket con qué librería y desde qué aparato escribe la persona, y en el
+catálogo de proyectos se avisa de «Librería desactualizada».
+
+| Cabecera | La pone | Contenido |
+|---|---|---|
+| `X-GrowTickets-Proxy` | Este paquete, **siempre** | `growtickets-nest/0.1.0` |
+| `X-GrowTickets-Client` | La librería del portal; el proxy la **reenvía** | base64url de un JSON corto: librería, versión, canal, sistema, modelo |
+
+`X-GrowTickets-Client` se reenvía sólo si parece lo que es (hasta 2 KB, sólo caracteres base64url) y es **la única
+cabecera del navegador que pasa**. Es información, nunca autorización. `X-GrowTickets-Proxy` también sale del cliente
+servidor a servidor y de la telemetría de seguridad.
+
+## Seguridad y disponibilidad
+
+Lo mismo que `growtickets-laravel` y `growtickets-next-server`, con el mismo protocolo: el producto **manda telemetría
+de seguridad** (intentos de login, 401/403/429, errores 5xx, escáneres que piden `/.env`), **corta con un 403 a las IP
+que la mesa de ayuda bloquee** y contesta una **ruta de salud firmada**. Está **apagada por defecto**: apagada no
+registra, no corta y no arranca ningún temporizador. La seguridad también hay que encenderla en GrowTickets, en la
+ficha del proyecto.
+
+### Variables de entorno
+
+| Variable | Por defecto | Qué hace |
+|---|---|---|
+| `GROWTICKETS_SECURITY` | apagada | `true` la enciende. Hace falta además `GROWTICKETS_API_KEY`. |
+| `GROWTICKETS_SECURITY_BLOCKING` | `true` | `false` sigue capturando pero nunca corta una petición. |
+| `GROWTICKETS_SECURITY_HEALTH_PATH` | `growtickets/health` | Dónde contesta la ruta de salud (sin barras en los extremos, sin el prefijo global). `off` la apaga. |
+| `GROWTICKETS_TRUSTED_PROXY_HOPS` | `1` | Cuántos proxies de confianza hay delante (1 = Railway; con Cloudflare delante de Railway, 2). `0` = sin proxy. |
+| `GROWTICKETS_FRONT_DEPS_TOKEN` | vacío | El token de build del front (ver [Dependencias de un front](#dependencias-de-un-front-que-vive-en-otro-repo)). Vacío = el relevo no existe. |
+| `GROWTICKETS_FRONT_DEPS_PATH` | `growtickets/front-deps` | Dónde recibe el relevo. `off` lo quita. |
+| `GROWTICKETS_SECURITY_DEPENDENCIES` | `true` | `false` apaga el relevo aunque tenga token. |
+
+Una variable mal escrita cae a su valor por defecto: la seguridad nunca lanza ni tumba una petición. Se leen al
+arrancar el proceso y en cada petición, no al compilar.
+
+### Qué hace el middleware de `main.ts`
+
+Corre **antes** que el router, los guards y el parser de cuerpo, en Express y en Fastify. Por petición:
+
+1. **La ruta de salud** se contesta ahí mismo: sólo a una petición firmada por la mesa de ayuda (HMAC-SHA256 de la
+   hora con tu clave de API, válida 5 minutos) y a todo lo demás un 404 corriente. Nunca se corta por IP ni se cuenta.
+   No revela versiones ni tablas.
+2. **Una IP bloqueada** recibe 403 (`{ "message": "Acceso bloqueado." }`, o texto si pide HTML) y no llega a tu app.
+3. **El relevo del front** (`POST /growtickets/front-deps`) se contesta ahí con el token de build.
+4. **Todo lo demás sigue**, y al terminar la respuesta se cuenta con su código real.
+
+Lo que se cuenta: el **tráfico** por minuto y por PLANTILLA de ruta (`GET /api/orders/[id]`, nunca la URL ni la query),
+con su reparto de códigos y su latencia; **`access.unauthorized` / `forbidden` / `rate_limited`** para 401, 403 y 429,
+también los que pone un `AuthGuard` tuyo; **`server.error`** para los 5xx; y **`request.probe`** para un 404 sin ruta
+contra una de las que sólo pide un escáner (`/.env`, `/wp-login.php`, `/actuator`…). La plantilla la anota un guard
+global que registra el módulo (`GrowTicketsRouteGuard`, que siempre deja pasar): un 404 que no casó con ninguna ruta
+va como `(sin ruta)`. Las rutas de salud de tu propio producto (`/health`, `/healthz`, `/up`, `/livez`, `/readyz`) no
+se cuentan, pero una IP bloqueada tampoco entra por ellas.
+
+### Las rutas de login
+
+```ts
+import { GrowTicketsLogin, GrowTicketsOnSuccess, GrowTicketsSecondFactor } from '@growconnect/growtickets-nest';
+
+@Post('auth/login')
+@GrowTicketsLogin({ identifier: 'email' })      // 401/422 = intento fallido, 2xx = entró
+login(@Body() dto: LoginDto) { … }
+
+@Post('auth/2fa')
+@GrowTicketsSecondFactor()                        // sus fallos son auth.second_factor_failed
+segundoFactor(@Body() dto: CodigoDto) { … }
+
+@Post('cuenta/clave')
+@GrowTicketsOnSuccess('account.password_changed') // el evento que cuenta un 2xx de esta ruta
+cambiarClave(@Body() dto: ClaveDto) { … }
+```
+
+El login se detecta por la RESPUESTA de la ruta, porque es lo único que ven todos los productos —también cuando la
+cuenta no existe, que es justo la señal del *credential stuffing*—. **Del cuerpo sólo se lee el campo `identifier`**, y
+sale hasheado (HMAC con una sal que sólo conocen tu servidor y la mesa de ayuda) y enmascarado (`a***@olivos.co`). Nunca
+se lee la contraseña. Un cuerpo de más de 16 KB no se toca. Si tu login falla con otro código (un `ValidationPipe` da
+400), pásalo: `@GrowTicketsLogin({ identifier: 'email', failureStatuses: [400, 401] })`.
+
+### Quién es el usuario
+
+```ts
+GrowTicketsModule.forRoot({ resolveReporter, security: { actor: (req) => req.user?.id } });
+```
+
+Se lee al terminar la respuesta, así que ve el `req.user` que dejó tu guard. Sin él, las peticiones se cuentan sin
+cuenta. Un id numérico viaja como `u:12`.
+
+### Lo que sólo tu producto sabe
+
+```ts
+constructor(private readonly security: GrowTicketsSecurity) {}
+
+this.security.track('auth.login_failed', { identifier: dto.email, request });
+this.security.track('custom.pago_rechazado', { actor: usuario.id, meta: { pasarela: 'x' } });
+```
+
+El tipo tiene que ser del catálogo del protocolo o `custom.<nombre>`; uno inventado se descarta. `meta` sólo lleva
+escalares. Apagada la seguridad, no hace nada; nunca lanza.
+
+### La ruta de salud
+
+No hay que montar nada: la contesta el middleware en `/growtickets/health` (o en `GROWTICKETS_SECURITY_HEALTH_PATH`).
+Agrega esa misma ruta al dominio en la pestaña «Disponibilidad». Dice «caído» si el servidor no responde y, si le das
+una comprobación de tu base, también cuando ésta no contesta:
+
+```ts
+security: { checks: { database: () => dataSource.query('select 1') } }   // con forRootAsync + inject
+```
+
+`false` o una excepción son un 503 que la mesa de ayuda cuenta como caída. Sin `checks` no se mira ninguna base.
+
+### Bloques de red
+
+Además de IP sueltas, GrowTickets puede cerrar un **país, una red (ASN) o las salidas de Tor**. Esos bloques son miles de
+rangos: se guardan ordenados en memoria y se consultan con una búsqueda binaria, sin coste apreciable por petición.
+Fallan abiertos igual que las IP sueltas.
+
+### Dependencias de un front que vive en otro repo
+
+Tu front (Angular…) tiene paquetes con fallos conocidos, pero tu servidor no los ve: están en otro repo. **El front no
+necesita ninguna clave de GrowTickets.** Su build manda la lista (sólo nombres y versiones) a tu servidor con un *token
+de build*, y la librería la reenvía a GrowTickets con la clave que ya tienes. Aparece en «Postura» como la lista de ese
+front, con su dominio.
+
+```dotenv
+# .env del servidor Nest
+GROWTICKETS_FRONT_DEPS_TOKEN=un-secreto-largo-y-solo-para-esto
+```
+
+En las variables del hosting que construye el front: el mismo `GROWTICKETS_FRONT_DEPS_TOKEN`,
+`GROWTICKETS_FRONT_DEPS_ENDPOINT=https://api.tuproducto.co/growtickets/front-deps` (y, opcional,
+`GROWTICKETS_ORIGIN=https://app.tuproducto.co`), y en su `package.json` `"postbuild": "growtickets-ng deps --soft"`.
+
+- **El token sólo sirve para esta ruta.** Si se filtra, lo peor que puede hacer quien lo tenga es falsear la lista de
+  paquetes de ese front: no puede leer nada, ni abrir tickets, ni tocar el monitor. Se rota cambiando el `.env`.
+- **Sin token, la ruta no existe.** Con otro token responde el 404 de siempre de tu app. La comparación es en tiempo
+  constante y hay un límite de 30 peticiones por minuto y por IP.
+- Funciona aunque `GROWTICKETS_SECURITY` esté apagada, como en Laravel: sólo necesita el token y la clave.
+- Respuestas que ve el build del front: `200` (`sent`, o `disabled` si la seguridad está apagada en el proyecto), `422`
+  (lista mal formada o rechazada), `501` (una central anterior), `502` (no se pudo reenviar; reintenta en el siguiente build).
+
+Las dependencias del **propio servidor Nest** se mandan desde CI con [`npx growtickets-nest deps`](#deps).
+
+### Límites (léelos antes de fiarte)
+
+- **Necesita un proceso Node que viva** (Railway, Docker, una máquina). Lo capturado y la lista de bloqueos están en
+  memoria y se envían cada minuto. En serverless cada invocación puede empezar de cero: la ruta de salud funciona, el
+  resto no es fiable.
+- **No es un cortafuegos.** Falla ABIERTO: sin lista descargada, con la mesa de ayuda caída o ante cualquier error de la
+  librería, la petición pasa. Un bloqueo se aplica en ~1 minuto.
+- **Varios servidores** detrás de un balanceador son varias instancias del mismo proyecto: cada uno descarga su lista y
+  manda sus lotes, y la mesa de ayuda los suma.
+- **La IP** sale de `X-Forwarded-For` contando `GROWTICKETS_TRUSTED_PROXY_HOPS` desde la DERECHA: lo que escribe el cliente
+  va a la izquierda y no cuenta. No depende del `trust proxy` de Express. Con un número equivocado todas las peticiones
+  parecen de la misma IP privada; la librería lo detecta y avisa a la mesa de ayuda (`no_trusted_proxies`).
+- **La dirección pública del producto** se aprende de las respuestas 2xx (con `X-Forwarded-Host`/`-Proto` detrás de un
+  proxy) y viaja con cada lote: de ahí sale la sugerencia de dominio en «Disponibilidad».
+- **Fastify** contesta 415 a un `POST` sin `Content-Type` antes de que llegue al proxy (el contrato pide 403). Sigue
+  rechazado; sólo cambia el código.
+- **Sin política de contenido (CSP)** en esta versión: Nest sirve JSON y el HTML lo sirve tu front. **Sin integridad de
+  archivos**: los despliegues de un producto Node son inmutables, y comparar archivos no aportaría nada.
+
+## CLI: `npx growtickets-nest`
+
+Sin dependencias propias.
+
+### `init [--dry-run]`
+
+Aborta si `package.json` no trae `@nestjs/core`. Crea o completa `.env.example` (la URL con su valor público, la clave
+vacía y `GROWTICKETS_SECURITY=` vacío) y `.gitignore` (un bloque marcado, idempotente). **Nunca toca `.env` ni ningún
+otro `.env*`**, no pide secretos y no usa la red. El módulo y `main.ts` son tus archivos: imprime los fragmentos y los
+deja ahí.
+
+### `check`
+
+De sólo lectura, para el CI del producto. Sale con 1 si `.gitignore` no cubre `.env` o si `.env.example` lleva en una
+`GROWTICKETS_*` un valor que parece un secreto (la clave o el token de build). Además **avisa** —sin cambiar el código de
+salida— de un montaje que no hará lo que se espera: el módulo sin `growTicketsMiddleware` en `main.ts`, Express sin
+subir el tope de JSON, o un prefijo global con la ruta de serie del portal.
+
+### `deps`
+
+`deps [--lockfile <ruta>] [--app <nombre>] [--origin <url>] [--dry-run]` manda a GrowTickets los **nombres y versiones**
+de tus paquetes npm, para que te avise en «Postura». Lee `package-lock.json`, `pnpm-lock.yaml` y `yarn.lock`. **Nunca
+viaja el archivo.** Pensado para CI, después de instalar; la clave necesita el alcance **Seguridad**. `--origin` (o
+`GROWTICKETS_ORIGIN`) distingue dos servidores con el mismo nombre. Sale con 1 si no puede enviar y con 0 si la mesa de
+ayuda aún no recibe dependencias o tiene la seguridad apagada: eso no debe frenar un despliegue.
+
+## Cliente servidor a servidor
+
+```ts
+constructor(private readonly growtickets: GrowTicketsClient) {}
+
+async avisarFalloDePago(usuario: Usuario) {
+  return this.growtickets.abrirTicket({ id: String(usuario.id), name: usuario.nombre }, { subject: 'El cobro falló' });
+}
+```
+
+Para un job, un cron o un webhook que abre un ticket sin nadie mirando una pantalla. **Lanza** si la mesa de ayuda
+responde `>= 400`, al revés que el proxy, que devuelve el código tal cual. También `tickets()`, `ticket()`,
+`responder()`, `configuracion()` y `sinLeer()`, que dice cuántas conversaciones tiene alguien sin leer (y lanza si no se
+pudo saber: nunca devuelve un cero que no es).
+
+## Dónde puede acabar un secreto, y qué lo impide
+
+| # | Vía de fuga | Barrera |
+|---|---|---|
+| 1 | La clave en el navegador | Nunca sale del servidor: el front habla con el proxy, que la pone en `X-Api-Key` |
+| 2 | Respuesta del proxy (cuerpo o cabeceras de la ingesta) | JSON re-serializado, `>= 500` sustituido por 503, sólo `content-type`/`cache-control` propios, la clave tapada por valor |
+| 3 | Mensajes de error | `toPublicError()` es la única salida hacia el navegador |
+| 4 | Registros | `redactByKey`/`redactByValue`, también con un logger inyectado |
+| 5 | Un `console.log` del objeto de configuración | `SecretValue` se imprime como `[redacted]` |
+| 6 | Una cabecera libre hacia la mesa de ayuda | Sólo `X-GrowTickets-Client`, validada |
+| 7 | La identidad falsificada desde el navegador | `reporter`/`reporter_id` se borran de cuerpo y query y salen de la sesión |
+| 8 | CSRF con la cookie de la víctima | `Origin`/`Sec-Fetch-Site` + `Content-Type: application/json` obligatorio en todo `POST` |
+| 9 | Tarball de npm | `files` en lista blanca + `scripts/audit-tarball.mjs` en `prepublishOnly` |
+| 10 | Commit del `.env` | `.gitignore` (lo escribe `init`, lo vigila `check`) |
+| 11 | Un valor por defecto de `GROWTICKETS_URL` que no es GrowTickets | No hay valor por defecto; `https` obligatorio salvo nombres locales |
+| 12 | La clave hacia un proxy de la red en claro | `https` sin depender de `NODE_ENV`, que en Nest casi nunca está |
+| 13 | El ticket de otra persona por el recorte de `max_input_vars` | `reporter_id` primero, tope de 100 valores, y la mesa de ayuda rechaza la query recortada |
+| 14 | Una línea falsa en tus registros (un `%0A` en la URL) | Los mensajes salen con los caracteres de control escapados y cortados a 500 |
+
+## Cadena de suministro: prácticas recomendadas
+
+- **Instala desde el lockfile**: `npm ci --ignore-scripts` en CI, y ejecuta a mano los scripts de los pocos paquetes que
+  de verdad los necesitan.
+- **Audita**: `npm audit --omit=dev` y `npx growtickets-nest deps` en el pipeline.
+- **Cuarentena para lo recién publicado**: una versión nueva no se adopta el día que sale (`npm config set min-release-age 7`
+  donde tu npm lo admita).
+- **2FA en tu cuenta de npm** y tokens de publicación de sólo ese paquete, con caducidad.
+- **Un SBOM por versión desplegada** (`npm sbom --sbom-format cyclonedx`) guardado con el artefacto.
+
+## Desarrollo
+
+```bash
+npm run verify          # lint, typecheck, pruebas, build, auditoría del tarball y publint
+npm run test:fixtures   # empaqueta el .tgz, lo instala en Nest 10 + Express, Nest 11 + Fastify y Nest 12 (ESM) con las dos, y los prueba de punta a punta (pide red)
+```
+
+Las pruebas de `test/nest` levantan una app de Nest de verdad con **cada plataforma**; las de `test/proxy` y
+`test/security` son las del núcleo.
+
+**El núcleo es una COPIA** del de `@growconnect/growtickets-next-server` (`packages/server/src` de `growtickets-next`,
+commit `8abdcaa`): `proxy/`, `security/`, `client/`, `errors/`, `logging/`, `config/` y `cli/deps.ts`, sin la CSP, sin el
+runtime edge y sin la comprobación de `NEXT_PUBLIC_*`. Lo de Nest vive en `src/nest/`. Tras la revisión de seguridad del
+2026-10-19 el núcleo además lleva aquí: `reporter_id` primero con `limitQuery` (100 valores) y `phpVariableName` en
+`handle-portal-request.ts`, la valla de origen en todos los métodos (`assertTrustedOrigin`), `safeLogText` en los
+registros y `GROWTICKETS_URL` obligatoria y `https` sin `NODE_ENV` en `config/env.schema.ts`; la dirección aprendida y el
+origen propio salen del `Host`. **Un arreglo del núcleo hay que
+hacerlo también allá** (y al revés): es el mismo contrato con la mesa de ayuda. La validación del entorno sin zod de
+`-next-server` 0.6.1 no se copió a propósito: aquí zod sigue haciendo falta para validar lo que devuelve
+`resolveReporter`, y no hay un bundle de edge que adelgazar.
+
+## Versiones
+
+- **0.1.0** — Primera versión: el proxy del portal (con `throttle`) y `GET unread` para el lanzador del componente web, la
+  seguridad (bloqueo de IP y de redes, sondeos, logins por decorador, ruta de salud firmada), el relevo de dependencias del
+  front, `GrowTicketsClient` (con `sinLeer()`) y el CLI (`init`, `check`, `deps`). Nest 10, 11 y 12, Express y Fastify.

package/bin/growtickets-nest.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Shim delgado: TODA la lógica vive en dist/cli/run.js (compilado de src/cli/run.ts), que se auto-
+// ejecuta al cargarse. .mjs y no .cjs a propósito: Node lo trata como ESM por la extensión sola,
+// sin depender del campo "type" del package.json — que aquí es "commonjs" para el resto del paquete.
+import '../dist/cli/run.js';

package/dist/cli/args.d.ts

@@ -0,0 +1,14 @@
+export interface ParsedArgs {
+    command: string | null;
+    dryRun: boolean;
+    /** `--lockfile <ruta>`: el archivo de bloqueo a leer en `deps`, en vez de buscarlo. */
+    lockfile: string | null;
+    /** `--app <nombre>`: cómo aparece el proyecto en el informe de `deps`. */
+    app: string | null;
+    /** `--origin <url>`: la dirección pública del producto, para que `deps` distinga este servidor de otro con el mismo nombre. */
+    origin: string | null;
+    /** Banderas que no se reconocen — `runCli` decide qué hacer con ellas, este archivo sólo las señala. */
+    unknown: string[];
+}
+/** Analizador de argumentos propio: son cuatro banderas, y así el CLI no arrastra ninguna dependencia. */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/cli/args.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+/** Analizador de argumentos propio: son cuatro banderas, y así el CLI no arrastra ninguna dependencia. */
+function parseArgs(argv) {
+    const [command = null, ...rest] = argv;
+    const result = { command, dryRun: false, lockfile: null, app: null, origin: null, unknown: [] };
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--dry-run')
+            result.dryRun = true;
+        else if (arg === '--lockfile' || arg === '--app' || arg === '--origin') {
+            const value = rest[++i];
+            if (value && !value.startsWith('--'))
+                result[arg === '--lockfile' ? 'lockfile' : arg === '--app' ? 'app' : 'origin'] = value;
+            else
+                result.unknown.push(`${arg} ${value ?? ''}`.trim());
+        }
+        else if (arg !== undefined)
+            result.unknown.push(arg);
+    }
+    return result;
+}

package/dist/cli/check.d.ts

@@ -0,0 +1,20 @@
+export interface CheckResult {
+    exitCode: number;
+    /** Lo que puede acabar con la clave en un repositorio: hace fallar el CI. */
+    issues: string[];
+    /** Cosas que no funcionarán como se espera pero no son una fuga: se avisan, no fallan. */
+    warnings: string[];
+    messages: string[];
+}
+/**
+ * De sólo lectura: nunca escribe nada, y por eso sirve para el CI del propio producto. Sale con 1 si
+ * encuentra una vía por la que la clave acabe versionada (un `.gitignore` que no cubre `.env`, un
+ * `.env.example` con un valor que parece un secreto). Avisa —sin cambiar el código de salida— de un
+ * montaje que no hará lo que se espera:
+ *
+ * - el módulo sin `app.use(growTicketsMiddleware(app))` en `main.ts`: sin él no se corta ninguna IP, no hay
+ *   ruta de salud y no se cuenta lo que no casó con ninguna ruta;
+ * - Express sin subir el tope de JSON: su parser corta en 100 KB y el contrato del portal es de 256 KB;
+ * - un prefijo global con la ruta de serie: el portal quedaría en `/api/api/soporte`.
+ */
+export declare function runCheck(cwd: string): CheckResult;

package/dist/cli/check.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCheck = runCheck;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const env_example_1 = require("./env-example");
+const SOURCE_ROOTS = ['src', 'apps', 'libs'];
+const SCAN_EXTENSIONS = new Set(['.ts', '.js', '.mts', '.cts', '.mjs', '.cjs']);
+/** Un escaneo SUPERFICIAL: hasta 8 niveles bajo cada raíz, sin entrar en node_modules/dist/.git. */
+const MAX_DEPTH = 8;
+const SKIPPED_DIRS = new Set(['node_modules', 'dist', '.git', 'coverage']);
+const USES_MODULE = /\bGrowTicketsModule\s*\.\s*forRoot(?:Async)?\s*\(/;
+const USES_MIDDLEWARE = /\bgrowTicketsMiddleware\s*\(/;
+const USES_FASTIFY = /\bFastifyAdapter\b/;
+const RAISES_JSON_LIMIT = /useBodyParser\s*\(\s*['"]json['"][^)]*limit/;
+const GLOBAL_PREFIX = /\bsetGlobalPrefix\s*\(\s*['"`]\/?([^'"`]+)['"`]/;
+/**
+ * De sólo lectura: nunca escribe nada, y por eso sirve para el CI del propio producto. Sale con 1 si
+ * encuentra una vía por la que la clave acabe versionada (un `.gitignore` que no cubre `.env`, un
+ * `.env.example` con un valor que parece un secreto). Avisa —sin cambiar el código de salida— de un
+ * montaje que no hará lo que se espera:
+ *
+ * - el módulo sin `app.use(growTicketsMiddleware(app))` en `main.ts`: sin él no se corta ninguna IP, no hay
+ *   ruta de salud y no se cuenta lo que no casó con ninguna ruta;
+ * - Express sin subir el tope de JSON: su parser corta en 100 KB y el contrato del portal es de 256 KB;
+ * - un prefijo global con la ruta de serie: el portal quedaría en `/api/api/soporte`.
+ */
+function runCheck(cwd) {
+    const issues = [...checkGitignore(cwd), ...checkEnvExample(cwd)];
+    const warnings = checkWiring(cwd);
+    return {
+        exitCode: issues.length > 0 ? 1 : 0,
+        issues,
+        warnings,
+        messages: [
+            ...(issues.length > 0
+                ? ['✗ growtickets-nest check encontró problemas:', ...issues.map((issue) => `  - ${issue}`)]
+                : ['✓ growtickets-nest check: nada que reportar.']),
+            ...(warnings.length > 0 ? ['', '⚠ Avisos (no hacen fallar el check):', ...warnings.map((warning) => `  - ${warning}`)] : []),
+        ],
+    };
+}
+function checkWiring(cwd) {
+    let usaModulo = false;
+    let usaMiddleware = false;
+    let usaFastify = false;
+    let subeTope = false;
+    let prefijo = null;
+    let rutaPropia = false;
+    for (const root of SOURCE_ROOTS) {
+        walk((0, node_path_1.join)(cwd, root), 0, (_path, content) => {
+            usaModulo ||= USES_MODULE.test(content);
+            usaMiddleware ||= USES_MIDDLEWARE.test(content);
+            usaFastify ||= USES_FASTIFY.test(content);
+            subeTope ||= RAISES_JSON_LIMIT.test(content);
+            prefijo ??= GLOBAL_PREFIX.exec(content)?.[1] ?? null;
+            rutaPropia ||= passesPath(content);
+        });
+    }
+    if (!usaModulo)
+        return [];
+    const warnings = [];
+    if (!usaMiddleware) {
+        warnings.push('GrowTicketsModule está montado pero no hay app.use(growTicketsMiddleware(app)) en main.ts: sin él la seguridad no corta IP bloqueadas, no contesta la ruta de salud ni cuenta los sondeos.');
+    }
+    if (!usaFastify && !subeTope) {
+        warnings.push("Con Express, el parser de JSON corta en 100 KB y un mensaje largo del portal (hasta 256 KB) recibiría un 413. Añade en main.ts: app.useBodyParser('json', { limit: '256kb' }).");
+    }
+    if (prefijo !== null && !rutaPropia) {
+        warnings.push(`Hay un prefijo global (setGlobalPrefix('${prefijo}')) y el portal usa la ruta de serie: quedará en /${prefijo}/api/soporte. Pasa path: 'soporte' a GrowTicketsModule.forRoot() si tu front lo espera en /${prefijo}/soporte.`);
+    }
+    return warnings;
+}
+/** ¿La llamada a `forRoot`/`forRootAsync` le da su propia `path`? Se mira el trozo de texto justo después de la llamada. */
+function passesPath(content) {
+    const inicio = content.search(USES_MODULE);
+    return inicio >= 0 && /\bpath\s*:/.test(content.slice(inicio, inicio + 800));
+}
+function walk(dir, depth, onFile) {
+    if (depth > MAX_DEPTH || !(0, node_fs_1.existsSync)(dir))
+        return;
+    for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+        if (SKIPPED_DIRS.has(entry.name))
+            continue;
+        const full = (0, node_path_1.join)(dir, entry.name);
+        if (entry.isDirectory())
+            walk(full, depth + 1, onFile);
+        else if (SCAN_EXTENSIONS.has((0, node_path_1.extname)(entry.name)) && !entry.name.endsWith('.d.ts'))
+            onFile(full, (0, node_fs_1.readFileSync)(full, 'utf8'));
+    }
+}
+function checkGitignore(cwd) {
+    const path = (0, node_path_1.join)(cwd, '.gitignore');
+    if (!(0, node_fs_1.existsSync)(path))
+        return ['.gitignore no existe: nada impide que .env se termine versionando.'];
+    const lines = (0, node_fs_1.readFileSync)(path, 'utf8').split('\n').map((line) => line.trim());
+    const cubre = lines.some((line) => line === '.env' || line === '.env*' || line === '.env.*' || line === '/.env');
+    return cubre ? [] : ['.gitignore no cubre .env.'];
+}
+/**
+ * Sólo mira las claves `GROWTICKETS_*`: un `.env.example` de un producto real trae más variables
+ * suyas con valores de ejemplo legítimos, y esta comprobación es sobre los SECRETOS de GrowTickets (la
+ * clave de API y el token de build del front), no una auditoría genérica de higiene de variables de entorno.
+ */
+function checkEnvExample(cwd) {
+    const path = (0, node_path_1.join)(cwd, '.env.example');
+    if (!(0, node_fs_1.existsSync)(path))
+        return [];
+    const issues = [];
+    for (const line of (0, node_fs_1.readFileSync)(path, 'utf8').split('\n')) {
+        const match = /^(GROWTICKETS_[A-Z0-9_]*)=(.*)$/.exec(line.trim());
+        if (!match || !match[1])
+            continue;
+        const key = match[1];
+        const value = match[2] ?? '';
+        const allowed = value === '' || env_example_1.PUBLIC_KEYS.includes(key);
+        if (!allowed)
+            issues.push(`.env.example: ${key} lleva un valor y no es una variable pública — ¿se coló un secreto?`);
+    }
+    return issues;
+}

package/dist/cli/deps.d.ts

@@ -0,0 +1,38 @@
+export interface DepPackage {
+    name: string;
+    version: string;
+    dev: boolean;
+}
+export interface DepsOptions {
+    lockfile: string | null;
+    app: string | null;
+    /** La dirección pública del producto (`--origin`); sin ella se mira `GROWTICKETS_ORIGIN`, y sin ninguna no se manda. */
+    origin?: string | null;
+    dryRun: boolean;
+}
+export interface DepsOutcome {
+    exitCode: number;
+    output: string;
+}
+/**
+ * `growtickets-nest deps [--lockfile <ruta>] [--app <nombre>] [--origin <url>] [--dry-run]`
+ *
+ * Manda a la mesa de ayuda los NOMBRES y VERSIONES de los paquetes npm del proyecto, para que ella —que sí consulta
+ * las bases de vulnerabilidades— avise en la pestaña «Postura» cuando uno tiene un fallo conocido. Nunca viaja el
+ * archivo: de cada paquete sólo `name`, `version` y si es de desarrollo. Está pensado para CI, después de instalar,
+ * y sirve a cualquier proyecto de Node —un front de Angular o React incluido—, no sólo a los de Nest.
+ *
+ * Lee `package-lock.json` (v1, v2 y v3), `pnpm-lock.yaml` y `yarn.lock` clásico. Yarn y pnpm no dicen qué paquetes
+ * son de desarrollo, así que van todos como de producción: se prefiere un aviso de más a uno de menos.
+ *
+ * Con `--origin` (o `GROWTICKETS_ORIGIN`) viaja también la dirección pública del producto: es lo que distingue dos servidores
+ * con el mismo nombre de aplicación, que sin ella la mesa de ayuda vería como una sola lista. Un comando de CI no sirve
+ * peticiones y no la aprende solo, así que se la das tú; si no la das, no se manda y la lista queda donde estaba.
+ *
+ * Necesita `GROWTICKETS_API_KEY` y, si no es la de serie, `GROWTICKETS_URL`. Sale con 1 si no puede enviar y con 0
+ * si la mesa de ayuda no recibe dependencias todavía (una central anterior) o tiene la seguridad apagada: eso no es
+ * un fallo del proyecto y no debe frenar un despliegue.
+ */
+export declare function runDeps(cwd: string, options: DepsOptions, env: Record<string, string | undefined>, fetchImpl?: typeof fetch): Promise<DepsOutcome>;
+/** Los paquetes de un archivo de bloqueo, con los de producción primero. Un archivo ilegible da una lista vacía. */
+export declare function readLockfile(archivo: string): DepPackage[];