@lenne.tech/nest-server 11.28.0 → 11.28.1

package/migration-guides/11.28.0-to-11.28.1.md

@@ -0,0 +1,155 @@
+# Migration Guide: 11.28.0 → 11.28.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | Internal only — the `ejs` import in the BetterAuth email-verification service was normalized to the CommonJS style (`import ejs = require('ejs')`), silencing a static-analysis warning. No runtime behavior change. |
+| **New Features** | None |
+| **Maintenance** | Dependency housekeeping: 17 within-major package updates, 4 previously-undeclared runtime dependencies now declared explicitly, security overrides pruned 9 → 6. `pnpm audit` remains at **0 vulnerabilities**. |
+| **Migration Effort** | **0 minutes for npm-mode consumers** (`pnpm update`). **~2 minutes for vendor-mode consumers** — ensure 4 runtime dependencies are present (see below). |
+
+This is a **pure maintenance patch**. There is no API change, no configuration change, and no
+behavioral change. Every one of the framework's 1381 tests passes unchanged.
+
+---
+
+## Quick Migration (npm mode)
+
+No code changes required.
+
+```bash
+# Update the package
+pnpm add @lenne.tech/nest-server@11.28.1
+
+# Verify
+pnpm run build
+pnpm test
+```
+
+All transitive dependency changes resolve automatically. Nothing in your project needs to change.
+
+---
+
+## What Changed
+
+### 1. Framework dependency updates (all within NestJS 11)
+
+The MAJOR version still mirrors NestJS 11 — no NestJS major boundary was crossed. Notable updates:
+
+| Package | 11.28.0 | 11.28.1 | Note |
+|---------|---------|---------|------|
+| `@nestjs/common` / `core` / `platform-express` / `websockets` | 11.1.23 | 11.1.28 | NestJS 11 patch |
+| `mongoose` | 9.6.2 | 9.7.4 | Minor (mongodb stays 7.2.0 — coupled) |
+| `nodemailer` | 8.0.8 | 9.0.3 | **Major bump** — internal email transport (see Compatibility Notes) |
+| `multer` | 2.1.1 | 2.2.0 | Security (unhandled multipart DoS) |
+| `graphql-query-complexity` | 1.1.0 | 1.1.1 | Patch |
+
+Dev-only tooling was also refreshed (`vitest`/`@vitest/*` 4.1.7 → 4.1.10, `vite` 8.0.14 → 8.1.4,
+`oxlint` 1.66.0 → 1.74.0, `@swc/core` 1.15.40 → 1.15.43, `tsx` 4.22.3 → 4.23.1, plus `@types/*`).
+Dev-tooling changes have **zero** effect on consuming projects.
+
+### 2. Newly declared runtime dependencies (relevant for vendor mode)
+
+Four packages that the framework's shipped code **imports directly** were previously only resolved
+**transitively** (phantom dependencies), relying on pnpm hoisting. They are now declared explicitly
+and pinned to the exact versions that were already resolving — **this is a declaration change, not a
+version bump, so nothing new is installed for npm-mode consumers.**
+
+| Package | Version | Imported by | Reached transitively before via |
+|---------|---------|-------------|----------------------------------|
+| `cron` | 4.4.0 | `src/core/common/services/core-cron-jobs.service.ts` (`new CronJob`) | `@nestjs/schedule` |
+| `jose` | 6.2.1 | `src/core/modules/better-auth/core-better-auth.service.ts` (`importJWK`/`jwtVerify`) | `better-auth`, `@modelcontextprotocol/sdk` |
+| `ws` | 8.21.0 | `src/test/test.helper.ts` (`require('ws')`) | `@nestjs/graphql`, `@nestjs/apollo` |
+| `graphql-ws` | 6.0.8 | `src/test/test.helper.ts` (`createClient`) | `@nestjs/graphql`, `@nestjs/apollo` |
+
+Why this matters: relying on a transitive package means its presence and **version** are controlled
+by someone else's dependency tree. `ws` already resolved to two versions in the tree (`8.21.0` and
+a nested `7.5.11`); an explicit declaration removes the hoisting lottery.
+
+### 3. Security override cleanup (9 → 6)
+
+Three overrides in `pnpm-workspace.yaml` became genuine no-ops after the direct-dependency updates
+above and were removed (verified with `pnpm audit`, which stays at 0 vulnerabilities):
+
+| Removed override | Now resolved by |
+|------------------|-----------------|
+| `nodemailer@<9.0.1` | direct dependency is now `nodemailer@9.0.3` (the old override was silently patching a vulnerable `8.0.8` direct pin) |
+| `multer@<2.2.0` | `@nestjs/platform-express@11.1.28` now pins `multer@2.2.0` exactly |
+| `vite@>=8.0.0 <8.0.16` | all `vite` now resolves to `8.1.4` |
+
+Six overrides remain, each proven still load-bearing (removing them reintroduces a vulnerability):
+`ajv`, `picomatch`, `ws`, `uuid`, `@babel/core`, `js-yaml`. Each carries its CVE/GHSA rationale as
+an inline comment.
+
+---
+
+## Compatibility Notes
+
+- **npm-mode consumers:** Nothing to do. `pnpm update @lenne.tech/nest-server` is sufficient.
+- **`nodemailer` 8 → 9 (internal):** `nodemailer` is used internally by the framework's
+  `EmailService`/SMTP transport. Projects configure it declaratively through
+  `email.smtp` in `config.env.ts`, and those options are unchanged across the 8 → 9 boundary — all
+  email tests pass unmodified. If (and only if) your project constructs a **custom `nodemailer`
+  transport object directly** and passes it in, review the
+  [nodemailer 9 release notes](https://github.com/nodemailer/nodemailer/releases) for the transport
+  API. The declarative `email.smtp` path needs no changes.
+- **Projects without BetterAuth / cron / GraphQL subscriptions:** Unaffected — the newly declared
+  packages were already in your tree transitively.
+
+### Vendor-mode consumers (`src/core/` copied into your project)
+
+Vendor-mode projects do **not** install `@lenne.tech/nest-server` as an npm dependency, so they do
+not inherit its `dependencies`. After syncing this release into your vendored `src/core/`, make sure
+these four runtime packages exist in **your** `package.json` (pinned, per the fixed-version rule):
+
+```jsonc
+{
+  "dependencies": {
+    "cron": "4.4.0",          // required — imported by core-cron-jobs.service.ts
+    "jose": "6.2.1"           // required — imported by core-better-auth.service.ts
+    // ws / graphql-ws: required only if you use the exported TestHelper (src/test/test.helper.ts)
+    // in your own tests — most projects do:
+    // "graphql-ws": "6.0.8",
+    // "ws": "8.21.0"
+  }
+}
+```
+
+In practice these are almost always already present transitively (via `@nestjs/schedule`,
+`better-auth`, `@nestjs/graphql`). Declaring them explicitly protects you from a future transitive
+change silently removing them. The `lt-dev:nest-server-core-updater` agent surfaces this during a
+core sync.
+
+---
+
+## Troubleshooting
+
+### `Cannot find module 'jose'` / `'cron'` after a vendor-mode sync
+
+You copied the updated `src/core/` but did not add the runtime dependency. Add the package to your
+project's `package.json` (see the vendor-mode block above) and run `pnpm install`.
+
+### `pnpm audit` reports a vulnerability I thought an override covered
+
+The `nodemailer`, `multer`, and `vite` overrides were removed because the direct/transitive
+resolutions now land on fixed versions on their own. If your project maintains its **own**
+`pnpm-workspace.yaml` overrides (vendor mode or a monorepo root), re-verify with a with/without
+lockfile diff — do not blindly copy this repo's removals; your tree may still resolve a vulnerable
+version back into range.
+
+### Build tool (`nest build`) fails with a permission error after `pnpm install`
+
+Unrelated to your code — a known pnpm 11 hoisted-linker store-dedup artifact can drop the executable
+bit on `node_modules/.bin/nest`. This release deliberately keeps `@nestjs/cli` at `11.0.21` to avoid
+re-linking it. If you still hit it, `chmod +x node_modules/@nestjs/cli/bin/nest.js` restores it and
+survives subsequent installs.
+
+---
+
+## References
+
+- [Package Management Rules](../.claude/rules/package-management.md) — fixed-version policy, override target rules
+- [Migration Guide 11.27.7 → 11.28.0](./11.27.7-to-11.28.0.md) — previous release (the 401/403 policy + S_SELF/S_CREATOR ownership fixes)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.28.0",
+  "version": "11.28.1",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -84,41 +84,44 @@
     "@getbrevo/brevo": "3.0.1",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/apollo": "13.4.2",
-    "@nestjs/common": "11.1.23",
-    "@nestjs/core": "11.1.23",
+    "@nestjs/common": "11.1.28",
+    "@nestjs/core": "11.1.28",
     "@nestjs/graphql": "13.4.2",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.23",
+    "@nestjs/platform-express": "11.1.28",
     "@nestjs/schedule": "6.1.3",
     "@nestjs/swagger": "11.4.2",
     "@nestjs/terminus": "11.1.1",
-    "@nestjs/websockets": "11.1.23",
+    "@nestjs/websockets": "11.1.28",
     "@tus/file-store": "2.1.0",
     "@tus/server": "2.4.1",
-    "@types/supertest": "7.2.0",
+    "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "better-auth": "1.6.23",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
     "cookie-parser": "1.4.7",
+    "cron": "4.4.0",
     "dotenv": "17.4.2",
     "ejs": "5.0.2",
     "express": "5.2.1",
     "graphql": "16.14.0",
-    "graphql-query-complexity": "1.1.0",
+    "graphql-query-complexity": "1.1.1",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
+    "graphql-ws": "6.0.8",
+    "jose": "6.2.1",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.2.0",
-    "mongoose": "9.6.2",
-    "multer": "2.1.1",
+    "mongoose": "9.7.4",
+    "multer": "2.2.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "8.0.8",
+    "nodemailer": "9.0.3",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -126,26 +129,27 @@
     "rxjs": "7.8.2",
     "supertest": "7.2.2",
     "ts-morph": "27.0.2",
+    "ws": "8.21.0",
     "yuml-diagram": "1.2.0"
   },
   "devDependencies": {
     "@compodoc/compodoc": "1.2.1",
     "@nestjs/cli": "11.0.21",
     "@nestjs/schematics": "11.1.0",
-    "@nestjs/testing": "11.1.23",
+    "@nestjs/testing": "11.1.28",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.15.40",
+    "@swc/core": "1.15.43",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.24",
-    "@types/multer": "2.1.0",
+    "@types/multer": "2.2.0",
     "@types/node": "25.9.1",
-    "@types/nodemailer": "8.0.0",
+    "@types/nodemailer": "8.0.1",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.7",
-    "@vitest/ui": "4.1.7",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/ui": "4.1.10",
     "ansi-colors": "4.1.3",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
@@ -153,17 +157,17 @@
     "npm-watch": "0.13.0",
     "otpauth": "9.5.1",
     "oxfmt": "0.51.0",
-    "oxlint": "1.66.0",
+    "oxlint": "1.74.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
-    "tsx": "4.22.3",
+    "tsx": "4.23.1",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
-    "vite": "8.0.14",
+    "vite": "8.1.4",
     "vite-plugin-node": "8.0.0",
-    "vitest": "4.1.7"
+    "vitest": "4.1.10"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import * as ejs from 'ejs';
+import ejs = require('ejs');
 import * as fs from 'fs';
 import * as path from 'path';