@lenne.tech/nest-server 11.31.1 → 11.31.3

package/docs/REQUEST-LIFECYCLE.md

@@ -213,6 +213,7 @@ JWT-based authentication for existing projects:
 | **Health Check Module** | `GET /health` + GraphQL `healthCheck` query |
 | **Error Code Module** | Centralized error registry with unique IDs |
 | **Permissions Report** | Interactive HTML dashboard, JSON, and Markdown reports |
+| **Hub (Operator Cockpit)** | Build-free ADMIN-gated dashboard at `/hub` (config-gated per environment). Adds an optional HTTP trace middleware (registered by `CoreHubModule.configure()` only when traces are enabled), a chaining `Logger.overrideLogger()` delegate for the log buffer, an optional `EmailService` capture hook (`HUB_EMAIL_CAPTURE` token) for the mailbox, and — when the query profiler is enabled — opts the MongoDB driver into `monitorCommands` from `core.module.ts`. See `src/core/modules/hub/README.md`. |
 | **System Setup Module** | Initial admin creation for fresh deployments |
 | **Cron Jobs** | `CoreCronJobsService` with timezone/UTC offset support |
 | **Model Documentation** | Auto-generated model docs via `ModelDocService` |

package/migration-guides/11.31.1-to-11.31.2.md

@@ -0,0 +1,127 @@
+# Migration Guide: 11.31.1 → 11.31.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None (one behavior change for admins — see below) |
+| **New Features** | Admin cross-user conversation listing (`?all=true`), creator attribution (`createdByUser`) |
+| **Bugfixes** | Non-admins can list their own AI conversations again (was HTTP 403 / GraphQL "Access denied") |
+| **Migration Effort** | None for most projects — no code changes required |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm update @lenne.tech/nest-server@11.31.2
+
+# Verify
+pnpm run build && pnpm test
+```
+
+No configuration changes are required. Everything below is automatic (the
+bugfix) or opt-in (the two new features).
+
+---
+
+## What's New in 11.31.2
+
+### 1. Non-admins can list their own AI conversations again (bugfix)
+
+`GET /ai/conversations` and the GraphQL `findAiConversations` query returned
+`403` / "Access denied" for every non-admin user, so their own conversations
+never loaded. The list endpoints passed the per-document roles
+`[ADMIN, S_CREATOR, S_SELF]`, which a LIST operation can never satisfy (there is
+no single object to check ownership against), so non-admins were rejected before
+ownership scoping ran.
+
+Both endpoints now authorize the list with `S_USER` and scope the result to the
+caller via a server-side `createdBy` filter plus the model's `securityCheck`.
+Cross-user isolation is unchanged — a non-admin still only ever sees their own
+conversations. **No action required**; it simply works after the update.
+
+### 2. Admins can opt in to a cross-user view (`?all=true`)
+
+By default every user — **admins included** — now receives only their own
+conversations. An admin can list every user's conversations on demand:
+
+```bash
+# REST
+GET /ai/conversations?all=true
+```
+
+```graphql
+# GraphQL
+query { findAiConversations(all: true) { id title createdBy createdByUser } }
+```
+
+The flag is ignored for non-admins, so it can never widen a regular user's
+scope. Results are ordered newest-first.
+
+### 3. Creator attribution in the admin cross-user view (`createdByUser`)
+
+In the admin cross-user view (`all: true`) each conversation additionally
+carries a resolved `createdByUser` object so the list is attributable to a named
+user:
+
+```jsonc
+{
+  "id": "…",
+  "title": "…",
+  "createdBy": "665f…",                // owner user id (always present)
+  "createdByUser": {                    // only in the admin all-view
+    "id": "665f…",
+    "email": "user@example.com",
+    "firstName": "…",
+    "lastName": "…",
+    "username": "…"
+  }
+}
+```
+
+On a normal own-only fetch `createdByUser` is left unset (the owner is the
+caller, so no lookup is needed).
+
+---
+
+## Behavior Change (admins only)
+
+Before 11.31.2, `GET /ai/conversations` returned **all** users' conversations
+for an admin by default. It now returns the **admin's own** conversations by
+default, matching every other role. If your admin UI relied on the unscoped
+list, request the cross-user view explicitly with `?all=true` (REST) or
+`all: true` (GraphQL). Non-admin behavior is unchanged.
+
+---
+
+## Compatibility Notes
+
+- `getConversation` / `deleteConversation` (single-object operations) are
+  unchanged — they still use `[ADMIN, S_CREATOR, S_SELF]`, which is correct
+  because a single loaded object exists to check ownership against.
+- Projects that extend `CoreAiConversationService` and override its constructor
+  must forward the new `@InjectConnection()` parameter to `super(...)` (used to
+  resolve creators for the admin view). Projects that do not subclass the
+  service are unaffected.
+
+---
+
+## Module Documentation
+
+### AI Module
+
+- **README:** [src/core/modules/ai/README.md](../src/core/modules/ai/README.md)
+- **Integration Checklist:** [src/core/modules/ai/INTEGRATION-CHECKLIST.md](../src/core/modules/ai/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/modules/ai/`
+- **Key Files:**
+  - `core-ai.controller.ts` / `core-ai.resolver.ts` — list endpoints delegate to the shared service method
+  - `services/core-ai-conversation.service.ts` — `findForCurrentUser()` (shared owner-scoped list + admin all-scope + creator attribution)
+  - `models/core-ai-conversation.model.ts` — `createdByUser` field, ownership `securityCheck`
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/migration-guides/11.31.2-to-11.31.3.md

@@ -0,0 +1,135 @@
+# Migration Guide: 11.31.2 → 11.31.3
+
+## Overview
+
+| Category | Effort | Required? |
+|----------|--------|-----------|
+| **New Feature** | Opt-in | No — purely additive |
+| Breaking Changes | None | — |
+| Config Changes | Optional | Only if you enable the Hub |
+
+This release adds the **Hub** — a build-free, ADMIN-gated operator cockpit served directly by the
+framework at `/hub`. It is **disabled by default** and must be switched on per environment, so
+existing projects are unaffected until they opt in. No code changes are required to update.
+
+It also includes a **security patch**: three moderate `axios` advisories (recursion DoS + prototype
+pollution, transitive via the Brevo and Mailjet mail SDKs) are closed by pinning `axios` to `1.18.1`.
+Nothing to do on your side — just update.
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm update @lenne.tech/nest-server
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+Nothing else is required — the Hub stays dormant (every `/hub` route answers 404) until you add a
+`hub` block to a config environment.
+
+## What's New in 11.31.3
+
+### Hub — admin area / operator cockpit
+
+A dependency-free dashboard of runtime information and admin tools, rendered as server-side HTML +
+a vanilla-JS SPA (no React, no build step), so it works identically in npm- and vendor-mode.
+
+**16 panels:** Dashboard, Diagnostics, Logs, Request Traces, Query Performance, Cron Jobs, Database,
+Models/ERD, Migrations, Files (GridFS), Config (secrets masked), Auth Migration (Legacy→IAM), Error
+Codes, Email Preview, Mailbox, AI. Each has a `*.json` sidecar (the stable data contract) the client
+polls; optional sources degrade to an "unavailable" state instead of erroring.
+
+**3 runtime collectors** (in-memory ring buffers, per-app-instance, parallel-test-safe):
+- **Logs** — a chaining `Logger.overrideLogger()` delegate (no main.ts change), secrets redacted.
+- **Traces** — an Express middleware bound only when the collector is enabled (zero cost otherwise).
+- **Queries** — MongoDB driver command monitoring; records value-free query SHAPES (N+1 templates),
+  never values. Enabling it opts the driver into `monitorCommands`.
+
+**Built-in Mailbox** — a Mailpit-style capture of outgoing mail hooked into `EmailService`. In
+`mode: 'capture'` mail is recorded and NOT sent (dev/test); in `mode: 'copy'` it is sent AND a copy
+is recorded (with tokens/links redacted in the stored copy). `capture` throws at startup in
+`production`/`staging` so it can never silently swallow real mail.
+
+**Admin actions** (opt-out via `hub.actions: false`) — migrations run/rollback, GridFS file delete,
+cron start/stop/trigger, collector-buffer clear, test mail. Every mutating request requires the
+`X-Hub-Request: 1` header (CSRF defense) and destructive ones a server-validated type-to-confirm
+keyword; each writes a `[HUB-ACTION] <action> by user <id>` audit line.
+
+#### Enable it
+
+The Hub is **never enabled implicitly** — switch it on per environment in `config.env.ts`:
+
+```typescript
+// config.env.ts (development / local)
+hub: {
+  collectors: { queries: true },   // opt-in query profiler
+  mailbox: { mode: 'capture' },    // capture outgoing mail locally (Mailpit replacement)
+},
+
+// production — usually omit `hub` entirely. If you do want it (still ADMIN-gated),
+// never use mailbox capture mode there:
+// hub: { mailbox: false },
+```
+
+Boolean shorthand `hub: true` enables it at `/hub`, admin-only, with default collectors. See
+`IHubConfig` for every option. Env-var equivalents exist via `NSC__HUB__*` (see `.env.example`).
+
+Then sign in as a user with `RoleEnum.ADMIN` and open `/hub`. The shell is self-sufficient: if you
+are not authenticated it shows a login form that posts to `loginEndpoint` (default
+`/iam/sign-in/email`), so an admin can sign in directly at the API without the frontend. In a
+fullstack setup, a cross-subdomain session cookie from the app login already authenticates `/hub`.
+
+#### Customization (optional)
+
+Replace any Hub controller/service with a project subclass via `CoreModule.forRoot`:
+
+```typescript
+CoreModule.forRoot(envConfig, {
+  hub: {
+    controller: MyHubController,           // extends CoreHubController
+    actionsController: MyHubActionsController, // extends CoreHubActionsController
+    service: MyHubService,                 // extends CoreHubService
+    htmlService: MyHubHtmlService,         // extends CoreHubHtmlService
+    actionsService: MyHubActionsService,   // extends CoreHubActionsService
+  },
+});
+```
+
+## Breaking Changes
+
+None. The Hub is opt-in and disabled by default.
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Projects that never set `hub` | Unaffected | Every `/hub` route answers 404 |
+| Custom `EmailService` subclass | Compatible | The mailbox capture hook is injected optionally (`@Optional()`) — absent when the Hub/mailbox is off, so there is zero cost and no behavior change |
+| No auth system enabled | ⚠️ Action required | The Hub relies on the app-wide `RolesGuard`/`BetterAuthRolesGuard` to enforce `@Roles(ADMIN)`. With BetterAuth and legacy auth both disabled, no guard runs and the gate is inert — keep an auth module enabled or leave the Hub disabled |
+| `queries` collector enabled | Compatible | Opts the MongoDB driver into `monitorCommands` from `core.module.ts` when the consumer has not set it |
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `/hub` → 404 everywhere | `hub` is not set in that environment's config block — add `hub: true` (or an options object) |
+| Startup error mentioning mailbox `capture` | `mailbox.mode: 'capture'` is forbidden in `production`/`staging` — use `copy` or disable the mailbox there |
+| Query panel empty | The queries collector is opt-in — set `hub.collectors.queries: true` |
+| Cron panel empty | Import `ScheduleModule.forRoot()` in your ServerModule |
+| Hub reachable without login | You disabled all auth systems, so no roles guard runs — see the Compatibility note above |
+
+## Module Documentation
+
+- `src/core/modules/hub/README.md` — full panel/action/collector/security reference
+- `src/core/modules/hub/INTEGRATION-CHECKLIST.md` — config-only setup + common mistakes
+- `.claude/rules/configurable-features.md` — Hub row in the configurable-features table
+
+## References
+
+- Configurable-features pattern: `.claude/rules/configurable-features.md`
+- Request lifecycle (middleware + logger override + email hook): `docs/REQUEST-LIFECYCLE.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.31.1",
+  "version": "11.31.3",
   "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,9 +23,9 @@
     "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 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 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 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",
     "cf": "pnpm run check:fix",
@@ -65,6 +65,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"
   },

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;
+}

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

@@ -18,6 +18,7 @@ import * as SMTPTransport from 'nodemailer/lib/smtp-transport';
 import type * as StreamTransport from 'nodemailer/lib/stream-transport';
 
 import { Falsy } from '../types/falsy.type';
+import { IHubConfig } from '../../modules/hub/interfaces/hub-config.interface';
 import { IPermissions } from '../../modules/permissions/interfaces/permissions.interface';
 import { CronJobConfigWithTimeZone } from './cron-job-config-with-time-zone.interface';
 import { CronJobConfigWithUtcOffset } from './cron-job-config-with-utc-offset.interface';
@@ -1847,6 +1848,24 @@ export interface IServerOptions {
    */
   hostname?: string;
 
+  /**
+   * Hub admin area (operator cockpit).
+   *
+   * A build-free, ADMIN-gated dashboard of runtime information and admin tools (dashboard,
+   * diagnostics, logs, request traces, query profiler, migrations, DB stats, models/ERD, files,
+   * cron jobs, error codes, masked config, auth-migration progress, email preview, built-in mailbox,
+   * AI panel).
+   *
+   * Follows "presence implies enabled" — but is NEVER enabled implicitly. It must be switched on per
+   * environment (here or via `NSC__HUB__*`); no environment inherits it.
+   * - `true` / `{}`: enabled at `/hub`, admin-only, default collectors (logs + traces on, queries off)
+   * - `{ path: 'admin/hub', collectors: { queries: true } }`: custom path + query profiling
+   * - `{ enabled: false }` / `undefined`: disabled — every Hub route answers 404
+   *
+   * @default undefined (disabled)
+   */
+  hub?: boolean | IHubConfig;
+
   /**
    * Ignore selections in fieldSelection
    * [ConfigService must be integrated in ModuleService]
@@ -3312,4 +3331,31 @@ export interface ICoreModuleOverrides {
     controller?: Type<any>;
     service?: Type<any>;
   };
+
+  /**
+   * Override Hub controllers and/or services with project-specific subclasses.
+   *
+   * - `actionsController` must extend `CoreHubActionsController`
+   * - `actionsService` must extend `CoreHubActionsService`
+   * - `controller` must extend `CoreHubController`
+   * - `htmlService` must extend `CoreHubHtmlService`
+   * - `service` must extend `CoreHubService`
+   *
+   * @example
+   * ```typescript
+   * {
+   *   hub: {
+   *     service: MyHubService,
+   *     htmlService: MyHubHtmlService,
+   *   },
+   * }
+   * ```
+   */
+  hub?: {
+    actionsController?: Type<any>;
+    actionsService?: Type<any>;
+    controller?: Type<any>;
+    htmlService?: Type<any>;
+    service?: Type<any>;
+  };
 }