@lenne.tech/nest-server 11.25.3 → 11.25.5

package/migration-guides/11.25.3-to-11.25.5.md

@@ -0,0 +1,273 @@
+# Migration Guide: 11.25.3 → 11.25.5
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | (1) `MODULE_NOT_FOUND` at runtime for `@nestjs/*/dist/*` subpath imports — affected `node dist/main.js`, the migrate CLI, and any vendor-mode consumer. Tests passed because Vite/Vitest uses a different resolver. (#541) <br> (2) BetterAuth `Invalid trustedOrigin format: /` when running tests via Vitest with env-var-based `trustedOrigins` — the framework's own e2e config now filters Vite's auto-injected `process.env.BASE_URL='/'`. **Affects only consumer projects that build `betterAuth.trustedOrigins` or top-level `baseUrl` from `process.env.BASE_URL`** — see "BASE_URL Pitfall" below. |
+| **Security** | (1) `postcss@<8.5.10` override (GHSA-qx2v-qp2m-jg93, XSS via unescaped `</style>` in CSS stringify output, transitive via `vite`). <br> (2) `axios@<1.16.0` override (extended from `<1.15.0`) covering multiple CVEs (SSRF via `NO_PROXY`, prototype pollution, header injection, CRLF injection in `form-data`, XSRF leakage, auth bypass, response tampering, no_proxy IP alias bypass, streamed upload/response bypass, `toFormData` DoS, null byte injection) — transitive via `@getbrevo/brevo` and `node-mailjet`. <br> (3) New `fast-uri@<3.1.2` override (GHSA-3vp4-mxqf-vmh4 host confusion + GHSA-q4mq-mw7v-xq57 path traversal) — transitive via `@compodoc/compodoc>@angular-devkit/*>ajv`. <br> (4) New `@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4` override (GHSA-7p7r-hpq8-6w8q prototype-pollution variable shadowing) — transitive via `@compodoc/compodoc>@babel/preset-env`. <br> All framework-internal — no consumer action needed. |
+| **Maintenance** | Refreshed runtime + dev dependencies. Notable: `vite` 7.3.2 → **8.0.11** (major) and `vite-plugin-node` 7.0.0 → **8.0.0** (major) coupled lockstep upgrade — all 1751 framework tests pass. `mongoose` 9.4.1 → 9.6.2, `better-auth` 1.5.5 → 1.6.10, `@nestjs/apollo` & `@nestjs/graphql` 13.2.5 → 13.4.0, `@tus/*`, `mongodb` 7.1.1 → 7.2.0, `graphql` 16.13.2 → 16.14.0, plus dev tools (oxlint, oxfmt, swc, vitest, @types/node). |
+| **Tooling** | `scripts/check-server-start.sh` now strips ANSI color escape sequences from the port-detection one-liner output, preventing `ERR_SOCKET_BAD_PORT` when running under workspace runners (lerna/nx). |
+| **Migration Effort** | None required — update the package, run install + tests. Read "BASE_URL Pitfall" below if you build `betterAuth.trustedOrigins` or `baseUrl` from `process.env.BASE_URL` in your own `config.env.ts`. |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm install @lenne.tech/nest-server@11.25.5
+
+# Verify
+pnpm run build
+pnpm test
+```
+
+No code changes required. All changes are backward compatible.
+
+---
+
+## Bug Fix: `.js` Suffix on `@nestjs/*/dist/*` Subpath Imports (#541)
+
+### Symptoms before the fix
+
+When the framework code was executed with **pure Node** (i.e. `node dist/main.js`, `pnpm run migrate:up`, vendor-mode consumers running their bundled core), Node aborted with:
+
+```
+Error: Cannot find module '.../node_modules/@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage'
+ELIFECYCLE  Command failed with exit code 1.
+```
+
+This affected:
+- **npm-mode consumers**: any boot path that triggered the late `require()` in `interceptor.helper.ts:73` (e.g. when `ResponseModelInterceptor` resolves a return type via reflection at request time).
+- **vendor-mode consumers**: every `pnpm run migrate:up` and every `node dist/main.js` from the second the project was integrated. Reproduces deterministically with `lt fullstack init --framework-mode vendor` and `lt fullstack convert-mode --to vendor` (see PR #541 reproducible steps).
+- **Tests passed regardless** because Vite/Vitest uses an `enhanced-resolve`-based resolver that auto-appends `.js`. The bug was therefore invisible in the framework's own test suite.
+
+### Root cause
+
+Several `@nestjs/*` packages declare an `exports` field of the form:
+
+```jsonc
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  }
+}
+```
+
+When `exports` is present, **Node honors the pattern literally** and does NOT auto-append `.js` for matched subpaths. The bare specifier
+`@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage` resolves to a literal path that does not exist on disk (only `.../type-metadata.storage.js` exists). Vite/Vitest implement the older "tryExtensions" heuristic, masking the issue in tests.
+
+### Fix
+
+All `@nestjs/*/dist/*` subpath imports in the framework now end with `.js`:
+
+| File | Before | After |
+|---|---|---|
+| `src/core/common/decorators/unified-field.decorator.ts` | `.../type-metadata.storage` | `.../type-metadata.storage.js` |
+| `src/core/common/decorators/unified-field.decorator.ts` | `.../schema-object-metadata.interface` | `.../schema-object-metadata.interface.js` (now `import type`) |
+| `src/core/common/helpers/interceptor.helper.ts` | `.../type-metadata.storage` (in `require()`) | `.../type-metadata.storage.js` |
+| `src/core/common/interfaces/server-options.interface.ts` | `@nestjs/jwt/dist/interfaces` | `@nestjs/jwt/dist/interfaces/index.js` (now `import type`) |
+| `src/core/common/interfaces/server-options.interface.ts` | `.../mongoose.health` | `.../mongoose.health.js` (now `import type`) |
+| `src/core/common/interfaces/server-options.interface.ts` | `.../disk-health-options.type` | `.../disk-health-options.type.js` (now `import type`) |
+| `src/core/modules/auth/guards/auth.guard.ts` | `@nestjs/passport/dist/options` | `@nestjs/passport/dist/options.js` |
+| `src/core/modules/auth/guards/auth.guard.ts` | `@nestjs/passport/dist/utils/memoize.util` | `@nestjs/passport/dist/utils/memoize.util.js` |
+| `src/core/modules/health-check/core-health-check.service.ts` | `.../mongoose.health` | `.../mongoose.health.js` (now `import type`) |
+| `src/core/modules/health-check/core-health-check.service.ts` | `.../disk-health-options.type` | `.../disk-health-options.type.js` (now `import type`) |
+
+Type-only imports were additionally promoted to `import type` for preventive hygiene once `verbatimModuleSyntax` is turned on.
+
+### Action required for consumers
+
+**None for npm-mode consumers** — `pnpm install` pulls the patched code. The next `pnpm run build` of the consumer project keeps the (already correct) generated `node_modules/@lenne.tech/nest-server/dist/...` output, but now subsequent runtime calls into those files no longer crash.
+
+**None for vendor-mode consumers either**, but the recommended sync flow is:
+
+```bash
+# Option 1 — re-run the lt CLI vendor-update from your monorepo root
+lt fullstack update
+
+# Option 2 — manually pull the patched paths into your vendored core
+#   (only the 5 files listed above need updating — see PR #541 diff)
+```
+
+Vendor-mode users who hit the original `Cannot find module ...type-metadata.storage` error will see it disappear immediately after the sync.
+
+---
+
+## Security: New & Extended Overrides
+
+The following entries were added or extended in `pnpm.overrides`:
+
+```jsonc
+{
+  "pnpm": {
+    "overrides": {
+      "axios@<1.16.0": "1.16.0",                                       // extended in 11.25.5 (was <1.15.0)
+      "fast-uri@<3.1.2": "3.1.2",                                       // new in 11.25.5
+      "@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4": "7.29.4", // new in 11.25.5
+      "postcss@<8.5.10": "8.5.12"                                       // added in 11.25.4
+    }
+  }
+}
+```
+
+| Override | Advisory / CVE | Transitive chain | Status |
+|---|---|---|---|
+| `axios@<1.16.0` | Multiple CVEs (SSRF via `NO_PROXY`, prototype pollution, header injection, CRLF in `form-data`, XSRF leakage, auth bypass, response tampering, no_proxy IP alias bypass, streamed upload/response bypass, `toFormData` DoS, null byte injection) | `@getbrevo/brevo`, `node-mailjet` | Extended in 11.25.5 — remove when both upstreams ship `axios>=1.16.0`. |
+| `fast-uri@<3.1.2` | GHSA-3vp4-mxqf-vmh4 (host confusion), GHSA-q4mq-mw7v-xq57 (path traversal) | `@compodoc/compodoc>@angular-devkit/schematics>@angular-devkit/core>ajv` | New in 11.25.5. |
+| `@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4` | GHSA-7p7r-hpq8-6w8q (prototype-pollution variable shadowing in generated code) | `@compodoc/compodoc>@babel/preset-env` | New in 11.25.5. |
+| `postcss@<8.5.10` | GHSA-qx2v-qp2m-jg93 (XSS via unescaped `</style>`) | `vite` | Added in 11.25.4. Remove when `vite` ships with `postcss>=8.5.10` natively. |
+
+All entries follow the project rule that override **targets must be fixed versions** (no `^`, `~`, `>=`). All are framework-internal — no consumer action needed.
+
+---
+
+## Bug Fix: BASE_URL Pitfall in `config.env.ts` (added in 11.25.5)
+
+### Symptom
+
+Tests fail in `beforeAll` with:
+
+```
+BetterAuth configuration invalid: Invalid trustedOrigin format: /
+BetterAuth configuration invalid: Invalid auto-detected trustedOrigin format: /; Invalid passkey origin format: /
+```
+
+### Root cause
+
+Vite injects `process.env.BASE_URL = '/'` (its asset base path default — see `vite/dist/node/chunks/node.js`, `env: { BASE_URL, MODE, DEV, PROD }`). This is **also true under Vitest**, because Vitest sits on Vite. As a result, any consumer config that derives URLs via:
+
+```typescript
+trustedOrigins: [process.env.BASE_URL || 'http://localhost:3000', ...] // BUG
+baseUrl: process.env.BASE_URL                                          // BUG
+```
+
+ends up with `'/'` instead of the fallback under Vitest, because `'/'` is truthy. BetterAuth's URL validation then rejects `'/'` and the entire test boot path fails.
+
+This was **never introduced by a specific Vite version** — Vite has had `BASE_URL='/'` injection for years. The bug only surfaces when consumers move from hardcoded URLs to env-var-driven URLs in their own `config.env.ts`.
+
+### Fix in your project's `config.env.ts`
+
+```typescript
+// trustedOrigins (e.g. in your betterAuth config)
+trustedOrigins: [
+  process.env.BASE_URL && process.env.BASE_URL !== '/' ? process.env.BASE_URL : 'http://localhost:3000',
+  process.env.APP_URL || 'http://localhost:3001',
+],
+
+// top-level baseUrl
+baseUrl: process.env.BASE_URL && process.env.BASE_URL !== '/' ? process.env.BASE_URL : undefined,
+```
+
+Note: `APP_URL`, `MODE` (other than the four Vite built-ins), `DEV`, `PROD` are **not** auto-injected as `'/'`, so they don't need the same guard. Only `BASE_URL` is affected.
+
+### Alternative (cleanest)
+
+Use a different env var name that doesn't collide with Vite's built-ins:
+
+```typescript
+trustedOrigins: [process.env.API_URL || 'http://localhost:3000', process.env.APP_URL || 'http://localhost:3001'],
+```
+
+Or use the framework's `NSC__` prefix for the merge mechanism (see `getEnvironmentObject()` in `core/common/helpers/config.helper.ts`):
+
+```bash
+# in .env
+NSC__BETTER_AUTH__TRUSTED_ORIGINS=http://localhost:3000,http://localhost:3001
+```
+
+---
+
+## Maintenance: Dependency Refresh
+
+| Package | 11.25.3 | 11.25.5 | Notes |
+|---|---|---|---|
+| `@apollo/server` | 5.5.0 | 5.5.1 | Patch — added 11.25.5. |
+| `better-auth` | 1.5.5 | **1.6.10** | Minor bump. `@better-auth/core@1.6.9` declared `@opentelemetry/api` as `peerDependenciesMeta.optional` (previously required and was the upgrade blocker). 1.6.10 is a patch on top. All 1751 framework tests pass; manual smoke-testing of auth flows (sign-in, passkey, 2FA) is recommended in your project before deploying. |
+| `@better-auth/passkey` | 1.5.5 | 1.6.10 | Lockstep with `better-auth`. |
+| `@nestjs/apollo` | 13.2.5 | 13.4.0 | Patch + minor — fixes upstream. |
+| `@nestjs/graphql` | 13.2.5 | 13.4.0 | Patch + minor — fixes upstream. |
+| `@nestjs/swagger` | 11.3.0 | 11.4.2 | Patch-level fixes upstream. |
+| `@tus/file-store` | 2.0.0 | 2.1.0 | Minor — fully backward compatible per upstream changelog. |
+| `@tus/server` | 2.3.0 | 2.4.1 | Lockstep with `@tus/file-store`. |
+| `graphql` | 16.13.2 | 16.14.0 | Minor — added 11.25.5. |
+| `mongodb` | 7.1.1 | 7.2.0 | Minor — added 11.25.5 (now in sync with `mongoose@9.6.x`). |
+| `mongoose` | 9.4.1 | 9.6.2 | Minor — bundled MongoDB driver now 7.2.x. |
+| `nodemailer` | 8.0.5 | 8.0.7 | Patch. |
+| `otpauth` | 9.5.0 | 9.5.1 | Patch. |
+| `vite` | 7.3.2 | **8.0.11** | **Major** — added 11.25.5. Coupled lockstep upgrade with `vite-plugin-node@8.0.0`. All 1751 framework tests pass; consumers using their own `vitest`/`vite-plugin-node` setups should verify compatibility. |
+| `vite-plugin-node` | 7.0.0 | **8.0.0** | **Major** — lockstep with `vite@8`. |
+| `vitest` | 4.1.4 | 4.1.5 | Patch (lockstep with `@vitest/coverage-v8` and `@vitest/ui`). |
+| `@swc/core` | 1.15.26 | 1.15.33 | Patch. |
+| `@types/node` | 25.6.0 | 25.6.2 | Patch — added 11.25.5. |
+| `oxfmt` | 0.45.0 | 0.48.0 | Minor — formatter, dev-only. |
+| `oxlint` | 1.60.0 | 1.63.0 | Minor — linter, dev-only. |
+| `pnpm` (packageManager) | 10.33.0 | 10.33.2 | Patch. |
+
+**Knowingly not updated** (with rationale):
+
+| Package | Current | Latest | Reason |
+|---|---|---|---|
+| `@getbrevo/brevo` | 3.0.1 | 5.0.4 | Major API redesign — separate PR. |
+| `graphql-upload` | 15.0.2 | 17.0.0 | ESM-only — would force ESM migration of multiple modules. |
+| `ts-morph` | 27.0.2 | 28.0.0 | `@compodoc/compodoc` peer-deps still pin `^27`. |
+| `typescript` | 5.9.3 | 6.0.3 | `@nestjs/cli@11.0.21` pins `typescript@5.9.3`; major upgrade would conflict. |
+
+---
+
+## Tooling: ANSI-Safe Port Detection in `check-server-start.sh`
+
+When `pnpm run check` runs under a workspace runner that wraps stdout with ANSI color codes (lerna, nx, turbo, certain CI environments), the inline Node one-liner that picks a free port can return output like:
+
+```
+\x1b[33m50604\x1b[39m
+```
+
+That string then enters `FREE_PORT` and crashes `net.Server#listen` with `ERR_SOCKET_BAD_PORT`. The script now strips ANSI escape sequences via `sed` (NOT via `tr -cd '0-9'`, which would corrupt the port digits because the escape codes contain digits themselves):
+
+```bash
+FREE_PORT=$(node -e "..." | sed $'s/\x1b\\[[0-9;]*m//g' | tr -d '[:space:]')
+```
+
+Defensive change — has no effect when no ANSI codes are present.
+
+---
+
+## Compatibility Notes
+
+- **API surface**: unchanged. All exports from `src/index.ts` keep the same shape.
+- **CoreModule.forRoot()**: unchanged.
+- **Mongoose plugins, decorators, interceptors, guards**: unchanged.
+- **Test contracts**: unchanged. `pnpm test` passes 1751 / 1751 cases on both `develop` HEAD and the new release.
+- **Override targets**: all fixed versions per `.claude/rules/package-management.md`.
+
+---
+
+## Troubleshooting
+
+**Q: After updating, `pnpm test` fails on tests that I had previously skipped because of the type-metadata.storage error.**
+A: Those tests should now pass. If they don't, ensure your `pnpm-lock.yaml` is in sync (`pnpm install`) and the patched files were actually pulled.
+
+**Q: Vendor-mode project still throws `Cannot find module ...type-metadata.storage` after I updated to 11.25.5.**
+A: Run `lt fullstack update` from your monorepo root, or manually re-sync the five files listed in the bug-fix section above. The `lt` CLI's `fullstack update` will detect the version bump and pull the new vendored core.
+
+**Q: My tests fail with `Invalid trustedOrigin format: /` or `Invalid passkey origin format: /` after switching `betterAuth.trustedOrigins` or `baseUrl` to `process.env.BASE_URL`.**
+A: See "BASE_URL Pitfall" above. Vite/Vitest auto-inject `process.env.BASE_URL='/'`, so the `||` fallback never fires. Filter against `'/'` explicitly, use a different env var name (e.g. `API_URL`), or use the `NSC__` prefix mechanism.
+
+**Q: `pnpm install` warns about unmet peer-deps for `typescript@^5.6.3 vs found 6.0.3`.**
+A: Harmless — this is by design. We are deliberately staying on `typescript@5.9.x` because TS 6.0 was just released and ecosystem peer-dep readiness is still in flux. The warning will go away when downstream packages widen their peer ranges.
+
+**Q: After running `pnpm run check` in a vendor-mode consumer, oxfmt complains about format issues in `src/core/core.module.ts` or `src/server/modules/file/file.controller.ts`.**
+A: This is a separate `lt CLI`-side issue (the convert-mode does not run a final `oxfmt --write` pass). Fix locally with `pnpm run format` and report against the `lenneTech/cli` repo.
+
+---
+
+## Related Documentation
+
+- **PR #541** — `fix(core): add .js suffix to @nestjs/*/dist/* subpath imports` (full diff and reproducible test plan)
+- [Previous migration guide](./11.25.0-to-11.25.3.md)
+- [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version policy for `package.json` and overrides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.25.3",
+  "version": "11.25.5",
   "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",
@@ -74,27 +74,27 @@
     "node": ">= 20"
   },
   "dependencies": {
-    "@apollo/server": "5.5.0",
+    "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@better-auth/passkey": "1.5.5",
+    "@better-auth/passkey": "1.6.10",
     "@getbrevo/brevo": "3.0.1",
-    "@nestjs/apollo": "13.2.5",
+    "@nestjs/apollo": "13.4.0",
     "@nestjs/common": "11.1.19",
     "@nestjs/core": "11.1.19",
-    "@nestjs/graphql": "13.2.5",
+    "@nestjs/graphql": "13.4.0",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
     "@nestjs/platform-express": "11.1.19",
     "@nestjs/schedule": "6.1.3",
-    "@nestjs/swagger": "11.3.0",
+    "@nestjs/swagger": "11.4.2",
     "@nestjs/terminus": "11.1.1",
     "@nestjs/websockets": "11.1.19",
-    "@tus/file-store": "2.0.0",
-    "@tus/server": "2.3.0",
+    "@tus/file-store": "2.1.0",
+    "@tus/server": "2.4.1",
     "@types/supertest": "7.2.0",
     "bcrypt": "6.0.0",
-    "better-auth": "1.5.5",
+    "better-auth": "1.6.10",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
@@ -102,18 +102,18 @@
     "dotenv": "17.4.2",
     "ejs": "5.0.2",
     "express": "5.2.1",
-    "graphql": "16.13.2",
+    "graphql": "16.14.0",
     "graphql-query-complexity": "1.1.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.1.1",
-    "mongoose": "9.4.1",
+    "mongodb": "7.2.0",
+    "mongoose": "9.6.2",
     "multer": "2.1.1",
     "node-mailjet": "6.0.11",
-    "nodemailer": "8.0.5",
+    "nodemailer": "8.0.7",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -129,26 +129,26 @@
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.1.19",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.15.26",
+    "@swc/core": "1.15.33",
     "@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/node": "25.6.0",
+    "@types/node": "25.6.2",
     "@types/nodemailer": "8.0.0",
     "@types/passport": "1.0.17",
-    "@vitest/coverage-v8": "4.1.4",
-    "@vitest/ui": "4.1.4",
+    "@vitest/coverage-v8": "4.1.5",
+    "@vitest/ui": "4.1.5",
     "ansi-colors": "4.1.3",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
-    "otpauth": "9.5.0",
-    "oxfmt": "0.45.0",
-    "oxlint": "1.60.0",
+    "otpauth": "9.5.1",
+    "oxfmt": "0.48.0",
+    "oxlint": "1.63.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
@@ -156,9 +156,9 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
-    "vite": "7.3.2",
-    "vite-plugin-node": "7.0.0",
-    "vitest": "4.1.4"
+    "vite": "8.0.11",
+    "vite-plugin-node": "8.0.0",
+    "vitest": "4.1.5"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -179,10 +179,12 @@
   "watch": {
     "build:dev": "src"
   },
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@10.33.2",
   "pnpm": {
     "//overrides": {
-      "axios@<1.15.0": "Security: SSRF via NO_PROXY bypass (GHSA-3p68-rc4w-qgx5) and unrestricted cloud metadata exfiltration (GHSA-fvcv-3m26-pcqx) - transitive via @getbrevo/brevo and node-mailjet. Remove when @getbrevo/brevo ships axios>=1.15.0",
+      "axios@<1.16.0": "Security: Multiple CVEs in axios <1.15.2 (SSRF via NO_PROXY, prototype pollution, header injection, CRLF injection in form-data, XSRF leakage, auth bypass, response tampering, no_proxy IP alias bypass, streamed upload/response bypass, toFormData DoS, null byte injection) - transitive via @getbrevo/brevo and node-mailjet. Remove when @getbrevo/brevo and node-mailjet ship axios>=1.16.0",
+      "fast-uri@<3.1.2": "Security: host confusion (GHSA-3vp4-mxqf-vmh4) and path traversal (GHSA-q4mq-mw7v-xq57) in fast-uri <3.1.2 - transitive via @compodoc/compodoc>@angular-devkit/schematics>@angular-devkit/core>ajv",
+      "@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4": "Security: prototype pollution-based variable shadowing (GHSA-7p7r-hpq8-6w8q) generates unsafe code - transitive via @compodoc/compodoc>@babel/preset-env",
       "minimatch@<3.1.5": "Security: RegExp DoS (GHSA-p8p7-x288-28g6) - transitive via @getbrevo/brevo>rewire>eslint",
       "minimatch@>=9.0.0 <9.0.9": "Security: RegExp DoS - transitive via @nestjs/cli>@swc/cli",
       "minimatch@>=10.0.0 <10.2.5": "Security: RegExp DoS - transitive via @nestjs/apollo>ts-morph>@ts-morph/common and nodemon",
@@ -200,10 +202,13 @@
       "lodash@>=4.0.0 <4.18.0": "Security: CVE in lodash@4.17.x - transitive via @nestjs/graphql. 4.18.1 is the latest patched version",
       "defu@<=6.1.6": "Security: prototype pollution via __proto__ key - transitive via better-auth",
       "follow-redirects@<=1.15.11": "Security: Custom Authentication Headers leak on cross-domain redirect (GHSA-r4q5-vmmm-2653) - transitive via axios>@getbrevo/brevo and axios>node-mailjet",
-      "uuid@<14.0.0": "Security: Missing buffer bounds check in v3/v5/v6 (GHSA-w5hq-g745-h8pq) - transitive via @compodoc/compodoc and @compodoc/compodoc>@compodoc/live-server>http-auth"
+      "uuid@<14.0.0": "Security: Missing buffer bounds check in v3/v5/v6 (GHSA-w5hq-g745-h8pq) - transitive via @compodoc/compodoc and @compodoc/compodoc>@compodoc/live-server>http-auth",
+      "postcss@<8.5.10": "Security: XSS via Unescaped </style> in CSS Stringify Output (GHSA-qx2v-qp2m-jg93) - transitive via vite. Remove when vite ships with postcss>=8.5.10"
     },
     "overrides": {
-      "axios@<1.15.0": "1.15.0",
+      "axios@<1.16.0": "1.16.0",
+      "fast-uri@<3.1.2": "3.1.2",
+      "@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4": "7.29.4",
       "minimatch@<3.1.5": "3.1.5",
       "minimatch@>=9.0.0 <9.0.9": "9.0.9",
       "minimatch@>=10.0.0 <10.2.5": "10.2.5",
@@ -221,7 +226,8 @@
       "lodash@>=4.0.0 <4.18.0": "4.18.1",
       "defu@<=6.1.6": "6.1.7",
       "follow-redirects@<=1.15.11": "1.16.0",
-      "uuid@<14.0.0": "14.0.0"
+      "uuid@<14.0.0": "14.0.0",
+      "postcss@<8.5.10": "8.5.12"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

package/src/config.env.ts

@@ -32,7 +32,12 @@ const config: { [env: string]: IServerOptions } = {
       // JWT enabled by default (zero-config)
       jwt: { enabled: true, expiresIn: '15m' },
       // Passkey auto-activated when URLs can be resolved (env: 'local' → localhost defaults)
-      passkey: { enabled: true, origin: 'http://localhost:3001', rpId: 'localhost', rpName: 'Nest Server Local' },
+      passkey: {
+        enabled: true,
+        origin: process.env.APP_URL || 'http://localhost:3001',
+        rpId: 'localhost',
+        rpName: 'Nest Server Local',
+      },
       rateLimit: { enabled: true, max: 100, windowSeconds: 60 },
       secret: process.env.BETTER_AUTH_SECRET || 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
       // Social providers disabled in local environment (no credentials)
@@ -42,7 +47,11 @@ const config: { [env: string]: IServerOptions } = {
         google: { clientId: '', clientSecret: '', enabled: false },
       },
       // Trusted origins for Passkey (localhost defaults)
-      trustedOrigins: ['http://localhost:3000', 'http://localhost:3001'],
+      // Filter BASE_URL against '/' because Vite/Vitest auto-inject process.env.BASE_URL='/' (asset base path default).
+      trustedOrigins: [
+        process.env.BASE_URL && process.env.BASE_URL !== '/' ? process.env.BASE_URL : 'http://localhost:3000',
+        process.env.APP_URL || 'http://localhost:3001',
+      ],
       // 2FA enabled for local testing
       twoFactor: { appName: 'Nest Server Local', enabled: true },
     },
@@ -124,7 +133,7 @@ const config: { [env: string]: IServerOptions } = {
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-ci',
     },
     permissions: true,
-    port: 3000,
+    port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
         checkObjectItself: false,
@@ -239,7 +248,7 @@ const config: { [env: string]: IServerOptions } = {
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-dev',
     },
     permissions: true,
-    port: 3000,
+    port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
         checkObjectItself: false,
@@ -277,7 +286,12 @@ const config: { [env: string]: IServerOptions } = {
       // JWT enabled by default (zero-config)
       jwt: { enabled: true, expiresIn: '15m' },
       // Passkey auto-activated when URLs can be resolved (env: 'local' → localhost defaults)
-      passkey: { enabled: true, origin: 'http://localhost:3001', rpId: 'localhost', rpName: 'Nest Server Local' },
+      passkey: {
+        enabled: true,
+        origin: process.env.APP_URL || 'http://localhost:3001',
+        rpId: 'localhost',
+        rpName: 'Nest Server Local',
+      },
       rateLimit: { enabled: true, max: 100, windowSeconds: 60 },
       secret: process.env.BETTER_AUTH_SECRET || 'BETTER_AUTH_SECRET_LOCAL_32_CHARS_M',
       // Social providers disabled in local environment (no credentials)
@@ -287,7 +301,11 @@ const config: { [env: string]: IServerOptions } = {
         google: { clientId: '', clientSecret: '', enabled: false },
       },
       // Trusted origins for Passkey (localhost defaults)
-      trustedOrigins: ['http://localhost:3000', 'http://localhost:3001'],
+      // Filter BASE_URL against '/' because Vite/Vitest auto-inject process.env.BASE_URL='/' (asset base path default).
+      trustedOrigins: [
+        process.env.BASE_URL && process.env.BASE_URL !== '/' ? process.env.BASE_URL : 'http://localhost:3000',
+        process.env.APP_URL || 'http://localhost:3001',
+      ],
       // 2FA enabled for local testing
       twoFactor: { appName: 'Nest Server Local', enabled: true },
     },
@@ -369,7 +387,7 @@ const config: { [env: string]: IServerOptions } = {
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-e2e',
     },
     permissions: true,
-    port: 3000,
+    port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
         checkObjectItself: false,
@@ -493,7 +511,7 @@ const config: { [env: string]: IServerOptions } = {
     permissions: {
       role: false,
     },
-    port: 3000,
+    port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
         checkObjectItself: false,
@@ -622,7 +640,7 @@ const config: { [env: string]: IServerOptions } = {
       // to prevent accidental connection to localhost (silent data-integrity risk).
       uri: process.env.MONGODB_URI,
     },
-    port: 3000,
+    port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
         checkObjectItself: false,

package/src/core/common/decorators/unified-field.decorator.ts

@@ -1,8 +1,8 @@
 import { Field, FieldOptions, HideField } from '@nestjs/graphql';
-import { TypeMetadataStorage } from '@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage';
+import { TypeMetadataStorage } from '@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage.js';
 import { Prop, PropOptions } from '@nestjs/mongoose';
 import { ApiHideProperty, ApiProperty, ApiPropertyOptions } from '@nestjs/swagger';
-import { EnumAllowedTypes } from '@nestjs/swagger/dist/interfaces/schema-object-metadata.interface';
+import type { EnumAllowedTypes } from '@nestjs/swagger/dist/interfaces/schema-object-metadata.interface.js';
 import { Type } from 'class-transformer';
 import {
   IsArray,

package/src/core/common/helpers/interceptor.helper.ts

@@ -70,7 +70,7 @@ function resolveFromGraphQlMetadata(context: ExecutionContext): (new (...args: a
     // @Query/@Mutation return types at runtime. This path has been stable since @nestjs/graphql v10.
     // Wrapped in try/catch so a path change in a future version degrades gracefully (returns null).
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { TypeMetadataStorage } = require('@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage');
+    const { TypeMetadataStorage } = require('@nestjs/graphql/dist/schema-builder/storages/type-metadata.storage.js');
 
     const handler = context.getHandler();
     const target = context.getClass();

package/src/core/common/interfaces/server-options.interface.ts

@@ -2,12 +2,12 @@ import { ApolloDriverConfig } from '@nestjs/apollo';
 import { Type } from '@nestjs/common';
 import { GqlModuleAsyncOptions } from '@nestjs/graphql';
 import { JwtModuleOptions } from '@nestjs/jwt';
-import { JwtSignOptions } from '@nestjs/jwt/dist/interfaces';
+import type { JwtSignOptions } from '@nestjs/jwt/dist/interfaces/index.js';
 import { MongooseModuleOptions } from '@nestjs/mongoose';
 import { ServeStaticOptions } from '@nestjs/platform-express/interfaces/serve-static-options.interface';
 import { CronExpression } from '@nestjs/schedule';
-import { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health';
-import { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type';
+import type { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health.js';
+import type { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type.js';
 import compression from 'compression';
 import { CollationOptions } from 'mongodb';
 import type * as JSONTransport from 'nodemailer/lib/json-transport';

package/src/core/modules/auth/guards/auth.guard.ts

@@ -2,8 +2,8 @@ import { CanActivate, ExecutionContext, Logger, mixin, Optional } from '@nestjs/
 import { ModuleRef } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
 import { AuthModuleOptions, Type } from '@nestjs/passport';
-import { defaultOptions } from '@nestjs/passport/dist/options';
-import { memoize } from '@nestjs/passport/dist/utils/memoize.util';
+import { defaultOptions } from '@nestjs/passport/dist/options.js';
+import { memoize } from '@nestjs/passport/dist/utils/memoize.util.js';
 import passport = require('passport');
 
 import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service';

package/src/core/modules/health-check/core-health-check.service.ts

@@ -6,8 +6,8 @@ import {
   MemoryHealthIndicator,
   MongooseHealthIndicator,
 } from '@nestjs/terminus';
-import { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health';
-import { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type';
+import type { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health.js';
+import type { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type.js';
 
 import { ConfigService } from '../../common/services/config.service';
 

package/src/core.module.ts

@@ -222,9 +222,9 @@ export class CoreModule implements NestModule {
               return connection;
             },
           },
-          uri: 'mongodb://localhost/nest-server-default',
+          uri: process.env.NSC__MONGOOSE__URI || 'mongodb://localhost/nest-server-default',
         },
-        port: 3000,
+        port: Number(process.env.PORT) || 3000,
       } as IServerOptions,
       options,
     );