@lenne.tech/nest-server 11.31.2 → 11.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.31.2",
+  "version": "11.32.0",
   "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",
@@ -23,20 +23,21 @@
     "build:dev": "pnpm run build",
     "c": "pnpm run check",
     "check": "node scripts/check.mjs",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
-    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
-    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
+    "spectaql:sync": "node extras/update-spectaql-version.mjs",
     "cf": "pnpm run check:fix",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
     "docs:bootstrap": "node extras/update-spectaql-version.mjs && node scripts/run-spectaql.mjs",
     "docs:ci": "ts-node ./scripts/init-server.ts && pnpm run docs:bootstrap && compodoc -p tsconfig.json",
-    "format": "oxfmt --write src/",
-    "format:check": "oxfmt --check src/",
-    "lint": "oxlint --ignore-path .oxlintignore src/ tests/",
-    "lint:fix": "oxlint --fix --fix-suggestions --ignore-path .oxlintignore src/ tests/",
+    "format": "oxfmt --write src/ scripts/",
+    "format:check": "oxfmt --check src/ scripts/",
+    "lint": "oxlint --ignore-path .oxlintignore src/ tests/ scripts/",
+    "lint:fix": "oxlint --fix --fix-suggestions --ignore-path .oxlintignore src/ tests/ scripts/",
     "prestart:prod": "pnpm run build",
     "reinit": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm install && pnpm run lint && pnpm run test:e2e && pnpm run test:ci && pnpm run build",
     "reinit:clean": "rimraf pnpm-lock.yaml && rimraf node_modules && pnpm store prune && pnpm install && pnpm run test:e2e && pnpm run build",
@@ -65,6 +66,7 @@
     "vitest:unit:cov": "vitest run --coverage --config vitest.config.ts",
     "test:unit:watch": "vitest --config vitest.config.ts",
     "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",
     "test:cleanup": "find tests -type f \\( -name '*.txt' -o -name '*.bin' \\) -not -name '.gitkeep' -delete && echo 'Test artifacts cleaned up'",
     "watch": "npm-watch"
   },
@@ -84,7 +86,7 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@better-auth/passkey": "1.6.23",
-    "@getbrevo/brevo": "3.0.4",
+    "@getbrevo/brevo": "6.0.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/apollo": "13.4.2",
     "@nestjs/common": "11.1.28",
@@ -98,7 +100,7 @@
     "@nestjs/swagger": "11.4.6",
     "@nestjs/terminus": "11.1.1",
     "@tus/file-store": "2.1.0",
-    "@tus/server": "2.4.1",
+    "@tus/server": "2.4.2",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "better-auth": "1.6.23",
@@ -116,11 +118,11 @@
     "graphql-upload": "15.0.2",
     "graphql-ws": "6.1.0",
     "jose": "6.2.3",
-    "js-sha256": "0.11.1",
+    "js-sha256": "0.12.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.2.0",
-    "mongoose": "9.7.4",
+    "mongodb": "7.5.0",
+    "mongoose": "9.8.0",
     "multer": "2.2.0",
     "node-mailjet": "6.0.11",
     "nodemailer": "9.0.3",
@@ -140,7 +142,7 @@
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.1.28",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.15.43",
+    "@swc/core": "1.15.46",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",

package/src/config.env.ts

@@ -20,6 +20,7 @@ import { IServerOptions } from './core/common/interfaces/server-options.interfac
 // which is purely cosmetic and carries promotional content. Warnings (`⚠`) for genuine
 // misconfiguration still surface.
 dotenv.config({ quiet: true });
+
 const config: { [env: string]: IServerOptions } = {
   // ===========================================================================
   // CI environment
@@ -141,6 +142,10 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: false,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-ci',
     },
+    hub: {
+      collectors: { queries: { warnMs: 1 } },
+      mailbox: { mode: 'capture' },
+    },
     permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
@@ -260,6 +265,14 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: false,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-dev',
     },
+    // Hub (operator cockpit) — OPTIONAL and enabled PER ENVIRONMENT (it is never on implicitly).
+    // `queries` (query profiler) and `mailbox` are opt-in; the whole thing stays ADMIN-gated.
+    // See src/core/modules/hub/README.md. In production it is off by default (see that block for how
+    // to enable it safely). Also toggleable via `NSC__HUB__*` env vars (see .env.example).
+    hub: {
+      collectors: { queries: true },
+      mailbox: { mode: 'capture' },
+    },
     permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
@@ -405,6 +418,10 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: false,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-e2e',
     },
+    hub: {
+      collectors: { queries: { warnMs: 1 } },
+      mailbox: { mode: 'capture' },
+    },
     permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
@@ -559,9 +576,14 @@ const config: { [env: string]: IServerOptions } = {
       modelDocumentation: true,
       uri: process.env.MONGODB_URI || 'mongodb://127.0.0.1/nest-server-local',
     },
-    permissions: {
-      role: false,
+    hub: {
+      collectors: { queries: true },
+      mailbox: { mode: 'capture' },
     },
+    // Authored intent: ADMIN-gated (reach it via the Hub's "Routes / Permissions" panel). The
+    // permissions-follows-hub invariant is enforced centrally by enforcePermissionsSecurity() below —
+    // e.g. if the Hub here is disabled, that pass flips this to a public localhost-only report.
+    permissions: true,
     port: Number(process.env.PORT) || 3000,
     security: {
       checkResponseInterceptor: {
@@ -665,6 +687,18 @@ const config: { [env: string]: IServerOptions } = {
       },
       enabled: true,
     },
+    // Hub (operator cockpit) is OFF in production by default (never enabled implicitly). To turn it
+    // on here — it stays ADMIN-gated — uncomment the block below. Note the production guard-rails:
+    //   - mailbox: NEVER 'capture' in production/staging (it suppresses real mail; it throws at
+    //     startup). Use `false`, or `{ mode: 'copy' }` if you want a redacted audit copy.
+    //   - collectors.queries: opt-in (it opts the MongoDB driver into command monitoring).
+    // The standalone permissions report follows the Hub (see enforcePermissionsSecurity below), so
+    // enabling the Hub also makes the ADMIN-gated "Routes / Permissions" panel available.
+    // See src/core/modules/hub/README.md; also configurable via NSC__HUB__* (see .env.example).
+    // hub: {
+    //   collectors: { queries: false },
+    //   mailbox: false,
+    // },
     ignoreSelectionsForPopulate: true,
     jwt: {
       refresh: {
@@ -716,6 +750,45 @@ const config: { [env: string]: IServerOptions } = {
   },
 };
 
+/**
+ * Enforce the permissions-report security invariant across every environment.
+ *
+ * The report is the full authorization map (every route + its required roles + `@Restricted` field
+ * rules) — a reconnaissance goldmine. The Hub does NOT need it (its "Routes / Permissions" panel
+ * reuses the scanner but degrades gracefully when the module is absent), so the rule is about the
+ * DANGEROUS direction: the report must never become a standalone, reachable surface.
+ *
+ * Derived per environment from THAT env's Hub state:
+ * - Hub OFF, non-`local` → report NOT registered (no in-app consumer → pure attack surface). This
+ *   makes the combination "non-local + Hub off + visible permissions" impossible to configure.
+ * - Hub OFF, `local`     → public (`role: false`) report allowed — frictionless, safe ONLY because
+ *   `local` is a non-reachable localhost env with no admin surface.
+ * - Hub ON               → left as authored (ADMIN when enabled, or off — the panel just degrades),
+ *   EXCEPT a public (`role: false`) report is forced back to ADMIN in every non-`local` stage.
+ *
+ * NOTE: runs on the statically-authored config; `NSC__HUB__*` / `NSC__PERMISSIONS__*` env overrides
+ * are applied afterwards by getEnvironmentConfig and take precedence.
+ */
+export function enforcePermissionsSecurity(cfg: { [env: string]: IServerOptions }): void {
+  for (const [envName, opts] of Object.entries(cfg)) {
+    const hub = opts.hub;
+    const hubOn =
+      hub === true || (typeof hub === 'object' && hub !== null && (hub as { enabled?: boolean }).enabled !== false);
+    const perms = opts.permissions;
+    const isPublic = typeof perms === 'object' && perms !== null && (perms as { role?: unknown }).role === false;
+
+    if (!hubOn) {
+      // Hub off: only a public localhost report (in `local`) is allowed; never register it elsewhere.
+      opts.permissions = envName === 'local' ? { role: false } : false;
+    } else if (envName !== 'local' && isPublic) {
+      // Reachable stage with the Hub on: the report must never be public — force the ADMIN gate.
+      opts.permissions = true;
+    }
+  }
+}
+
+enforcePermissionsSecurity(config);
+
 /**
  * Export config merged with other configs and environment variables as default
  */

package/src/core/common/helpers/logging.helper.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import { redactSensitiveText } from './logging.helper';
+
+describe('redactSensitiveText', () => {
+  it('redacts JWTs appearing anywhere in a line', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
+    const out = redactSensitiveText(`token issued: ${jwt} done`);
+
+    expect(out).not.toContain(jwt);
+    expect(out).toContain('token issued:');
+    expect(out).toContain('done');
+  });
+
+  it('redacts Authorization Bearer values', () => {
+    const out = redactSensitiveText('Authorization: Bearer abcdef1234567890secret');
+
+    expect(out).not.toContain('abcdef1234567890secret');
+    expect(out.toLowerCase()).toContain('authorization');
+  });
+
+  it('redacts key/value secrets regardless of separator or quoting', () => {
+    expect(redactSensitiveText('password=SuperSecret123')).not.toContain('SuperSecret123');
+    expect(redactSensitiveText('token: "abcd1234efgh"')).not.toContain('abcd1234efgh');
+    expect(redactSensitiveText("apiKey='pk_live_9999'")).not.toContain('pk_live_9999');
+    expect(redactSensitiveText('client_secret=verySecretValue')).not.toContain('verySecretValue');
+  });
+
+  it('redacts cookie headers', () => {
+    const out = redactSensitiveText('cookie: session=abc123; other=xyz789');
+
+    expect(out).not.toContain('abc123');
+    expect(out).not.toContain('xyz789');
+  });
+
+  it('redacts reset/verification tokens carried as a URL PATH segment (not key=value)', () => {
+    const link = 'https://app.example.com/verify/AbCdEf0123456789XyZtoken please click';
+    const out = redactSensitiveText(link);
+    expect(out).not.toContain('AbCdEf0123456789XyZtoken');
+    expect(out).toContain('/verify/');
+    // also for reset / set-password style links
+    expect(redactSensitiveText('/reset/SUPERSECRETVALUE1234567890')).not.toContain('SUPERSECRETVALUE1234567890');
+    expect(redactSensitiveText('/set-password/ZZZ1112223334445556667')).not.toContain('ZZZ1112223334445556667');
+  });
+
+  it('leaves harmless short path segments untouched', () => {
+    // Only long token-like segments (>= 16 chars) are masked — normal routes stay readable.
+    const text = 'GET /verify/email done';
+    expect(redactSensitiveText(text)).toBe(text);
+  });
+
+  it('leaves harmless text untouched', () => {
+    const text = 'User signed in successfully with id 507f1f77bcf86cd799439011';
+    expect(redactSensitiveText(text)).toBe(text);
+  });
+
+  it('handles empty / non-secret input without throwing', () => {
+    expect(redactSensitiveText('')).toBe('');
+    expect(redactSensitiveText('plain message')).toBe('plain message');
+  });
+});

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

@@ -132,3 +132,51 @@ export function maskToken(token: null | string | undefined): string {
   }
   return `${token.substring(0, 4)}...${token.substring(token.length - 4)}`;
 }
+
+/**
+ * Redacts secrets from a free-form log line.
+ *
+ * Composes the individual maskers above into a single regex-based pass for text where the sensitive
+ * value is not at a known position (log messages, error strings). Applied by the Hub log collector
+ * before truncation, so a truncation cut can never leak the prefix of a secret.
+ *
+ * Covers: JWTs anywhere in the line, `Authorization: Bearer …`, common `key=value` secrets
+ * (password/token/secret/apiKey/client_secret/refresh_token/…), and cookie headers.
+ *
+ * @param text - The log line to redact
+ * @returns The line with secret values replaced by masked placeholders
+ *
+ * @example
+ * redactSensitiveText('password=hunter2') // 'password=***'
+ */
+export function redactSensitiveText(text: string): string {
+  if (!text) {
+    return text;
+  }
+  return (
+    text
+      // JWTs anywhere in the line
+      .replace(/eyJ[\w-]{6,}\.[\w-]{6,}\.[\w-]{4,}/g, (match) => maskToken(match))
+      // reset/verification/invite tokens carried as a URL PATH segment (e.g. /verify/<token>,
+      // /reset/<token>) — these have no `key=value`, so the query-style rule below misses them.
+      .replace(
+        /(\/(?:verify|reset|confirm|activate|invite|magic-?link|set-password|change-email)\/)([A-Za-z0-9._~-]{16,})/gi,
+        (_m, prefix, token) => `${prefix}${maskToken(token)}`,
+      )
+      // authorization: Bearer xyz / Authorization=xyz
+      .replace(
+        /(authorization["']?\s*[:=]\s*["']?)(?:Bearer\s+)?([^\s"',;]+)/gi,
+        (_m, prefix, value) => `${prefix}${maskToken(value)}`,
+      )
+      // cookie headers (mask every value, keep names)
+      .replace(
+        /((?:^|[\s,;])cookie["']?\s*[:=]\s*)([^\n]+)/gi,
+        (_m, prefix, value) => `${prefix}${maskCookieHeader(value)}`,
+      )
+      // key/value secrets: password=..., token: "...", apiKey=..., secret=..., client_secret=..., refresh_token=...
+      .replace(
+        /((?:password|passwd|pwd|token|secret|api[-_]?key|client[-_]?secret|refresh[-_]?token|access[-_]?token|private[-_]?key)["']?\s*[:=]\s*["']?)([^\s"',;&}]+)/gi,
+        (_m, prefix, value) => `${prefix}${maskSensitive(value)}`,
+      )
+  );
+}

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

@@ -15,12 +15,18 @@
  * @see getBuildInfo
  */
 
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
 /** Default environment variable the build commit SHA is baked into. */
 export const DEFAULT_COMMIT_ENV = 'APP_VERSION_COMMIT';
 
 /** Defined value returned when no commit could be resolved. */
 export const UNKNOWN_COMMIT = 'unknown';
 
+/** Cached package.json version lookup (`null` = looked up and not found). */
+let cachedVersion: null | string | undefined;
+
 /**
  * Build identity of the running process.
  */
@@ -64,6 +70,45 @@ export function getBuildInfo(options: { commitEnvName?: string; env?: string; ve
   return {
     commit: getCommit(options.commitEnvName),
     env: options.env,
-    version: options.version || UNKNOWN_COMMIT,
+    version: options.version || getVersion(),
   };
 }
+
+/**
+ * Resolve the semantic version of the running app from its `package.json`.
+ *
+ * Reads the `version` field of the nearest `package.json` (searching up from the current working
+ * directory), cached after the first lookup. This is the deployed app's own version — in a consumer
+ * project that is the API's version, in this repo it is the framework version. Falls back to
+ * `'unknown'` when no `package.json` / version can be resolved.
+ *
+ * Prefer an explicit `IServerOptions.version` when set; this is the zero-config default.
+ */
+export function getVersion(): string {
+  if (cachedVersion !== undefined) {
+    return cachedVersion ?? UNKNOWN_COMMIT;
+  }
+  cachedVersion = null;
+  try {
+    // Walk up from cwd so a monorepo `projects/api` started from the repo root still resolves.
+    let dir = process.cwd();
+    for (let i = 0; i < 6; i++) {
+      const pkgPath = join(dir, 'package.json');
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };
+        if (typeof pkg.version === 'string' && pkg.version) {
+          cachedVersion = pkg.version;
+          break;
+        }
+      }
+      const parent = join(dir, '..');
+      if (parent === dir) {
+        break;
+      }
+      dir = parent;
+    }
+  } catch {
+    /* ignore — fall back to 'unknown' */
+  }
+  return cachedVersion ?? UNKNOWN_COMMIT;
+}