@lenne.tech/nest-server 11.26.3 → 11.27.1

package/migration-guides/11.26.3-to-11.27.0.md

@@ -0,0 +1,249 @@
+# Migration Guide: 11.26.3 → 11.27.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Build-identity helpers (`getCommit()` / `getBuildInfo()`); the running build's commit / version / environment is now surfaced in the `/health-check` response; new `IServerOptions.version` and `healthCheck.configs.build` options |
+| **Bugfixes** | None |
+| **Migration Effort** | 0 minutes (automatic) — the health check exposes the build identity on update. ~5 minutes optional to bake the real commit SHA into your image so it stops reporting `unknown` |
+
+This release makes the **running build identifiable at runtime**. App and API are
+typically deployed together but versioned independently, so a partial / stale
+rollout (one container older than the other) is otherwise hard to spot. The build
+**commit SHA** is the drift detector: bake the same CI commit into both images and
+compare them.
+
+---
+
+## Quick Migration
+
+No code changes required. The build indicator is added to `/health-check`
+automatically — the commit just reports `'unknown'` until you bake it into the
+image (see [Adopt the full drift detection](#adopt-the-full-drift-detection-optional)).
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.0
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's New in 11.27.0
+
+### 1. Build-identity helpers: `getCommit()` / `getBuildInfo()`
+
+Two pure helpers are now exported from `@lenne.tech/nest-server`. They give every
+project ONE canonical way to resolve which build is running, instead of re-reading
+`process.env` ad hoc.
+
+```typescript
+import { getBuildInfo, getCommit } from '@lenne.tech/nest-server';
+
+// Commit SHA the build was produced from. Reads process.env.APP_VERSION_COMMIT
+// (override the var name if you like), falling back to 'unknown' for local builds.
+getCommit();                 // → 'a1b2c3d…' or 'unknown'
+getCommit('MY_COMMIT_ENV');  // → reads a custom env var
+
+// Full build identity, ready to surface via a meta / info endpoint.
+getBuildInfo({ env: 'production', version: '1.4.0' });
+// → { commit: 'a1b2c3d…', env: 'production', version: '1.4.0' }
+```
+
+Also exported: `BuildInfo` (type), `DEFAULT_COMMIT_ENV` (`'APP_VERSION_COMMIT'`),
+`UNKNOWN_COMMIT` (`'unknown'`).
+
+### 2. Build identity in the `/health-check` response
+
+The core health check now includes a `build` indicator. It is **always** reported
+with status `up`, so it surfaces under `info`/`details` **without ever affecting
+the overall health status**. Ops and monitoring can detect a drifted / stale
+container, not just the admin UI.
+
+```jsonc
+// GET /health-check  (and the GraphQL `healthCheck` query)
+{
+  "status": "ok",
+  "info": {
+    "database": { "status": "up" },
+    "build": {
+      "status": "up",
+      "commit": "a1b2c3d4e5f6…",   // process.env.APP_VERSION_COMMIT, or "unknown"
+      "env": "production",          // from IServerOptions.env
+      "version": "1.4.0"            // from IServerOptions.version (see #3), or "unknown"
+    }
+  },
+  "details": { "database": { "status": "up" }, "build": { /* same */ } }
+}
+```
+
+Opt out (e.g. if you prefer to keep build info out of an unauthenticated probe):
+
+```typescript
+// config.env.ts
+healthCheck: {
+  configs: {
+    build: { enabled: false },
+  },
+}
+```
+
+### 3. New `IServerOptions.version` config field
+
+So the health-check build indicator can report your app version, set it from your
+`package.json` / `meta.json`:
+
+```typescript
+// config.env.ts
+import metaData = require('./meta.json');
+
+const base: Partial<IServerOptions> = {
+  env: envName,
+  version: metaData.version, // ← surfaced in /health-check build identity
+  // …
+};
+```
+
+Without it, the indicator reports `version: 'unknown'` — harmless, but less useful.
+
+### Adopt the full drift detection (optional)
+
+For the end-to-end "is App on the same build as API?" check, the commit must be
+baked into the image at build time and exposed publicly. The
+[nest-server-starter](https://github.com/lenneTech/nest-server-starter) reference
+implementation wires all three layers:
+
+1. **Image** — bake the commit at build time:
+   ```dockerfile
+   # In the runtime stage (the API reads it at runtime):
+   ARG APP_VERSION_COMMIT=unknown
+   ENV APP_VERSION_COMMIT=$APP_VERSION_COMMIT
+   ```
+2. **Build arg** — feed the CI commit SHA:
+   ```yaml
+   # docker-compose.yml
+   build:
+     args:
+       APP_VERSION_COMMIT: ${IMAGE_TAG:-unknown}   # IMAGE_TAG = CI_COMMIT_SHA
+   ```
+3. **Public endpoint** — the starter's `meta` module exposes `GET /meta`
+   (`S_EVERYONE`) returning `{ version, commit, environment, package, title }`,
+   so the frontend can read the API commit and compare it against its own.
+
+The contract end to end:
+
+```
+CI commit SHA → IMAGE_TAG (CI) → APP_VERSION_COMMIT build arg (compose)
+             → ENV in the image (Dockerfile) → getCommit() → /health-check + /meta
+```
+
+Versions (semver) are per-component and may legitimately differ — only the
+**commit** is compared. Local builds without CI report `unknown`, which clients
+use to suppress the drift warning.
+
+---
+
+## Breaking Changes
+
+None. All additions are backward compatible.
+
+---
+
+## Compatibility Notes
+
+- **Existing `/health-check` consumers:** The response gains one extra key
+  (`build`) under `info` and `details`. `status` is unchanged and the `build`
+  indicator can never flip the overall status to `error` (it always reports `up`).
+  Only consumers that assert the *exact* set of keys need updating; disable it via
+  `healthCheck.configs.build.enabled: false` if you must keep the old shape.
+- **GraphQL `healthCheck` query:** `info`/`details` are `JSON` scalars, so the new
+  `build` key flows through without any schema change.
+- **`IServerOptions`:** `version` and `healthCheck.configs.build` are new optional
+  fields. Existing configs compile unchanged.
+- **Commit resolution:** If you previously read `process.env.APP_VERSION_COMMIT`
+  yourself, you can switch to `getCommit()` for the identical result (with the
+  `'unknown'` fallback) — optional, not required.
+- **Vendor-mode consumers:** The same additions land in
+  `src/core/common/helpers/meta.helper.ts` and
+  `src/core/modules/health-check/core-health-check.service.ts`. Sync via the
+  vendored-core updater. No flatten-fix change required.
+
+---
+
+## Verifying
+
+```bash
+# Boot the API and read the health check
+pnpm start &
+curl -s http://localhost:3000/health-check | jq '.info.build'
+# → { "status": "up", "commit": "unknown", "env": "local", "version": "1.4.0" }
+
+# After a CI build that passes APP_VERSION_COMMIT, "commit" is the real SHA:
+APP_VERSION_COMMIT=$(git rev-parse HEAD) pnpm start &
+curl -s http://localhost:3000/health-check | jq '.info.build.commit'
+```
+
+A unit test for the helpers ships in `tests/unit/meta-helper.spec.ts`.
+
+---
+
+## Troubleshooting
+
+### `commit` is always `"unknown"`
+
+The build arg never reached the process. Check, in order:
+
+1. CI passes the commit SHA into the build (`IMAGE_TAG` / `APP_VERSION_COMMIT`).
+2. `docker-compose.yml` forwards it as a `build.args.APP_VERSION_COMMIT`.
+3. The **API** Dockerfile declares `ARG`/`ENV APP_VERSION_COMMIT` in the **runtime
+   stage** (the API reads it at runtime, not build time).
+4. For a frontend, the commit must be set **before** the bundler runs (e.g. Nuxt
+   freezes `runtimeConfig.public` at build time) — there the `ARG`/`ENV` belongs in
+   the **build stage**, not the runtime stage.
+
+### `version` is `"unknown"`
+
+Set `IServerOptions.version` (see [#3](#3-new-iserveroptionsversion-config-field)).
+The health check reads `config.version`; nothing else populates it.
+
+### I don't want build info on an unauthenticated endpoint
+
+`/health-check` is `S_EVERYONE` by design (probes need it). Disable just the build
+indicator with `healthCheck.configs.build.enabled: false`, or restrict the route
+in your project.
+
+---
+
+## Module Documentation
+
+### Core Common — build-identity helpers
+
+- **Helpers:** `src/core/common/helpers/meta.helper.ts` (`getCommit`, `getBuildInfo`, `BuildInfo`, `DEFAULT_COMMIT_ENV`, `UNKNOWN_COMMIT`)
+- **Unit tests:** `tests/unit/meta-helper.spec.ts`
+
+### Core Health Check
+
+- **Service:** `src/core/modules/health-check/core-health-check.service.ts` (build indicator)
+- **Controller / Resolver:** `src/core/modules/health-check/core-health-check.controller.ts`, `core-health-check.resolver.ts`
+- **Config:** `IServerOptions.healthCheck.configs.build` + `IServerOptions.version` in `src/core/common/interfaces/server-options.interface.ts`
+
+### Reference implementation (full drift detection)
+
+- **API meta module + Dockerfile build arg:** [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — `src/server/modules/meta/` exposes `GET /meta` with `commit`
+- **Frontend system page:** [nuxt-base-starter](https://github.com/lenneTech/nuxt-base-starter) — `/app/admin/system` compares App vs. API builds
+
+---
+
+## References
+
+- [Migration Guide 11.26.2 → 11.26.3](./11.26.2-to-11.26.3.md) — Previous release (OpenAPI enum `$ref` fix)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [nuxt-base-starter](https://github.com/lenneTech/nuxt-base-starter) (frontend drift detection)
+- [lt-monorepo](https://github.com/lenneTech/lt-monorepo) — `docker-compose.yml` + CI wiring for the `APP_VERSION_COMMIT` contract

package/migration-guides/11.27.0-to-11.27.1.md

@@ -0,0 +1,256 @@
+# Migration Guide: 11.27.0 → 11.27.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | None |
+| **Security** | Security maintenance pass: 7 new / refreshed `pnpm.overrides` entries forcing transitive dependencies onto CVE-patched versions — `ws`, `form-data`, `vite`, `hono`, `nodemailer`, `multer`, `js-yaml`. All framework-internal; consumer projects only need to mirror the entries if their own `pnpm audit` flags the same advisories. |
+| **Tooling** | New `scripts/check.mjs` — a quiet, report-driven wrapper around the `check` pipeline (audit + format + lint + test + build + server-start). Replaces the inline shell chain in `pnpm run check`; the original chain is preserved as `pnpm run check:raw`. Repo-internal only — not shipped via npm. |
+| **Migration Effort** | 0 minutes (automatic) — `pnpm update` is enough. ~5 minutes optional to mirror the security overrides into your own project's `package.json`. |
+
+This is a **maintenance release**. No source-code or config changes are required.
+The bulk of the work hardens transitive-dependency advisories that `pnpm audit`
+flagged on the framework after `npm`/`pnpm` resolved newer CVEs against 11.27.0's
+lockfile. A new in-repo wrapper around the `check` script trims runtime noise and
+auto-fixes every fixable format/lint finding.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.1
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Re-run audit to confirm advisories cleared
+pnpm audit
+```
+
+---
+
+## What's New in 11.27.1
+
+### 1. Security overrides refreshed
+
+`pnpm.overrides` in this repo's `package.json` gained / refreshed seven entries.
+Every override targets a **fixed version** (per `.claude/rules/package-management.md`
+override rules — no `>=` / `^` / `~`):
+
+| Package | Override | Advisory | Pulled in via |
+|---------|----------|----------|---------------|
+| `ws` (8.x) | `8.21.0` (was `8.20.1`) | Memory exhaustion DoS + uninitialized memory disclosure (`GHSA-96hv-2xvq-fx4p`) | `@nestjs/graphql` |
+| `ws` (7.x) | `7.5.11` *(new)* | Memory exhaustion DoS in `ws@7.x` (`GHSA-96hv-2xvq-fx4p`) | `@nestjs/graphql > subscriptions-transport-ws` |
+| `form-data` | `4.0.6` *(new)* | CRLF injection via unescaped multipart field names / filenames (`GHSA-hmw2-7cc7-3qxx`) | `@getbrevo/brevo > axios`, `node-mailjet > axios` |
+| `vite` | `8.0.16` *(new)* | `fs.deny` bypass on Windows alternate paths + file-read CVEs | `better-auth > vitest` |
+| `hono` | `4.12.25` *(new)* | Prototype pollution, `bodyLimit` / `Vary` bypass, JWT `NumericDate` (multiple CVEs `<4.12.25`) | `@nestjs/terminus > prisma > @prisma/dev` |
+| `nodemailer` | `9.0.1` *(new)* | Email / header-injection CVEs `<9.0.1` | direct dependency (forced major bump for transitive consumers — see note) |
+| `multer` | `2.2.0` *(new)* | Unhandled multipart errors / DoS `<2.2.0` | `@nestjs/platform-express` |
+| `js-yaml` | `4.2.0` *(new)* | Special-character handling / prototype pollution (patched in `4.2.0`; `4.1.2` was never published) | `@nestjs/swagger` |
+
+> **Why an override per package and not a direct upgrade?**
+> `pnpm.overrides` is the safest single-knob fix when the vulnerable copy comes
+> in transitively. Every entry uses the same `Pkg@<patched>` → `<patched>` selector
+> as the existing overrides, keeps the fix scoped to the vulnerable range, and is
+> documented in the `//overrides` comment block above the actual entries.
+
+#### Heads-up: `nodemailer` and `multer`
+
+The framework's **direct** `dependencies` still pin `nodemailer@8.0.8` and
+`multer@2.1.1` to preserve the historical lockfile reference. The overrides
+above force these onto `9.0.1` / `2.2.0` at install time. The framework's own
+`EmailService` and `multer*` file-helper usage was verified against the bumped
+versions — no API surface changes affect framework code.
+
+If your project uses `nodemailer` or `multer` directly:
+
+- **`nodemailer 8 → 9`** is a major bump (Node.js `>=18`, dropped legacy
+  `OAuth2` client constructor, `customCustomHeaders` / `customHeaders` casing
+  cleanup, `BURL`/`stub-transport` removals). Skim the
+  [nodemailer 9 release notes](https://github.com/nodemailer/nodemailer/releases)
+  if you call `nodemailer.createTransport` / `sendMail` from project code.
+- **`multer 1 → 2`** has been on `2.x` for two releases now; the `2.1 → 2.2`
+  jump is a patch-grade bump and needs no action.
+
+#### Why your project may still see CVEs after upgrading
+
+`pnpm.overrides` is **scoped to the package that declares it**. The framework's
+overrides do **not** propagate into consumer projects' lockfiles. If your own
+`pnpm audit` flags `ws / form-data / vite / hono / nodemailer / multer / js-yaml`,
+mirror the entries into your project's `package.json`:
+
+```jsonc
+// projects/api/package.json (or your project's package.json)
+"pnpm": {
+  "//overrides": {
+    "ws@>=8.0.0 <8.21.0": "Security: Memory exhaustion DoS + uninitialized memory disclosure (GHSA-96hv-2xvq-fx4p) - transitive via @nestjs/graphql",
+    "ws@>=7.0.0 <7.5.11": "Security: Memory exhaustion DoS in ws 7.x (GHSA-96hv-2xvq-fx4p) - transitive via @nestjs/graphql>subscriptions-transport-ws",
+    "form-data@<4.0.6": "Security: CRLF injection (GHSA-hmw2-7cc7-3qxx) - transitive via axios",
+    "vite@>=8.0.0 <8.0.16": "Security: fs.deny bypass on Windows + file-read CVEs - transitive via better-auth>vitest",
+    "hono@<4.12.25": "Security: multiple CVEs <4.12.25 - transitive via @nestjs/terminus>prisma>@prisma/dev",
+    "nodemailer@<9.0.1": "Security: email/header injection CVEs <9.0.1",
+    "multer@<2.2.0": "Security: unhandled multipart errors / DoS <2.2.0 - transitive via @nestjs/platform-express",
+    "js-yaml@<4.2.0": "Security: special-character handling / prototype pollution (patched 4.2.0; 4.1.2 unpublished) - transitive via @nestjs/swagger"
+  },
+  "overrides": {
+    "ws@>=8.0.0 <8.21.0": "8.21.0",
+    "ws@>=7.0.0 <7.5.11": "7.5.11",
+    "form-data@<4.0.6": "4.0.6",
+    "vite@>=8.0.0 <8.0.16": "8.0.16",
+    "hono@<4.12.25": "4.12.25",
+    "nodemailer@<9.0.1": "9.0.1",
+    "multer@<2.2.0": "2.2.0",
+    "js-yaml@<4.2.0": "4.2.0"
+  }
+}
+```
+
+After adding, run `pnpm install && pnpm audit && pnpm test`.
+
+### 2. New `scripts/check.mjs` wrapper (repo-internal)
+
+The `check` script now points at a Node-based wrapper:
+
+```diff
+- "check": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
++ "check": "node scripts/check.mjs",
++ "check:raw": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+```
+
+What changes when you run `pnpm run check`:
+
+- **One status line per running step** instead of streaming every tool's output
+  — the spinner shows the currently running step and elapsed time.
+- **Aborts on the first failing step** and prints the captured reason instead
+  of letting later steps spam the log.
+- **Auto-fixes every fixable finding** — `oxfmt` writes, `oxlint --fix` runs in
+  place. Only non-fixable lint errors remain and fail the run. Bypass with
+  `--no-fix` for a read-only gate.
+- **Final report** lists every executed step with key metrics (audit
+  vulnerabilities per severity, Vitest passed/failed/files, lint
+  errors/warnings, etc.).
+
+Available flags:
+
+| Flag | Purpose |
+|------|---------|
+| `--verbose` / `-v` | Stream the full tool output live (deep debugging) |
+| `--sequential` / `--seq` | Run projects one after another (default: parallel) |
+| `--no-fix` | Read-only gate — do not auto-fix format / lint |
+| `--project=<substr>` | Restrict to matching workspace projects (repeatable) |
+
+The original raw command remains available as `pnpm run check:raw` if you
+need the previous behaviour (CI logs, exact ordering, no auto-fix).
+
+> **Consumer impact:** None. `scripts/` is **not** part of the npm package's
+> `files` list (see `package.json` `files`: `dist`, `src`, `bin`, `CLAUDE.md`,
+> `FRAMEWORK-API.md`, `.claude/rules`, `docs`, `migration-guides`). The wrapper
+> is repo-internal tooling for framework development — but you may copy it
+> verbatim into your own project's `scripts/` directory if you want the same
+> behaviour for your `check` pipeline. It auto-discovers each workspace
+> project's `check` chain via `package.json`, so no further adaptation is
+> needed.
+
+---
+
+## Breaking Changes
+
+None.
+
+---
+
+## Compatibility Notes
+
+- **`IServerOptions` / `CoreModule.forRoot()`:** unchanged.
+- **`FRAMEWORK-API.md`:** regenerated for the new version stamp only — no API
+  surface differences vs. 11.27.0.
+- **`config.env.ts`:** no new fields, no deprecations.
+- **Vendor-mode consumers:** nothing to sync. The override changes live in
+  `package.json` at the **repo root**, which is excluded from
+  `convertCloneToVendored`. The `scripts/check.mjs` wrapper also lives outside
+  `src/core/`, so vendor projects keep their existing `check` setup.
+- **Custom controllers / resolvers extending Core* classes:** no impact —
+  no Core method signatures changed.
+- **Tests:** all 1751 framework tests pass against the new overrides.
+
+---
+
+## Verifying
+
+```bash
+# 1. Update + install
+pnpm add @lenne.tech/nest-server@11.27.1
+pnpm install
+
+# 2. Confirm advisories cleared (or only show unaffected residuals)
+pnpm audit
+
+# 3. Smoke-test the new check wrapper (only relevant in this repo)
+pnpm run check        # quiet, report-driven
+pnpm run check:raw    # original chain, full noise
+
+# 4. Tests + build
+pnpm test
+pnpm run build
+```
+
+---
+
+## Troubleshooting
+
+### `pnpm audit` in my consumer project still reports `ws` / `vite` / `nodemailer` ...
+
+Expected — `pnpm.overrides` is scoped to the declaring package. Mirror the
+entries listed under [Why your project may still see CVEs after upgrading](#why-your-project-may-still-see-cves-after-upgrading).
+
+### Tests fail with `nodemailer.createTransport is not a function` or similar
+
+You're calling a `nodemailer` API removed in v9 (the override forces `9.0.1`).
+Check the [v9 release notes](https://github.com/nodemailer/nodemailer/releases)
+and update the call site, or pin your project to `nodemailer@8.x` explicitly
+(*not* recommended — keeps the CVE open).
+
+### `pnpm run check` hangs or doesn't show output
+
+The wrapper hides per-step output by design. Re-run with `--verbose`:
+
+```bash
+pnpm run check -- --verbose
+# or
+node scripts/check.mjs --verbose
+```
+
+To restore the previous behaviour entirely, use `pnpm run check:raw`.
+
+### I want the old `check` behaviour back in CI
+
+Switch your CI job to invoke `pnpm run check:raw` — it is an exact preservation
+of the inline chain that was on `check` in 11.27.0.
+
+---
+
+## Module Documentation
+
+No module documentation changes in this release. Reference documentation:
+
+- **Package management rules:** [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version overrides only, never ranges
+- **Framework compatibility:** [`.claude/rules/framework-compatibility.md`](../.claude/rules/framework-compatibility.md) — what ships in the npm package
+
+---
+
+## References
+
+- [Migration Guide 11.26.3 → 11.27.0](./11.26.3-to-11.27.0.md) — Previous release (build identity in health check)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference implementation
+- [nodemailer v9 release notes](https://github.com/nodemailer/nodemailer/releases) — for projects calling `nodemailer` directly
+- [multer v2 changelog](https://github.com/expressjs/multer/releases) — for projects calling `multer` directly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.26.3",
+  "version": "11.27.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",
@@ -22,7 +22,8 @@
     "build:pack": "pnpm pack && echo 'use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package'",
     "build:dev": "pnpm run build",
     "c": "pnpm run check",
-    "check": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+    "check": "node scripts/check.mjs",
+    "check:raw": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
     "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
     "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
     "cf": "pnpm run check:fix",
@@ -200,13 +201,20 @@
       "path-to-regexp@>=8.0.0 <8.4.2": "Security: ReDoS (GHSA-rhx6-c78j-4q9w) - transitive via express>router",
       "kysely@>=0.26.0 <0.28.17": "Security: JSON-path traversal injection via unsanitized input (SQL injection) - transitive via better-auth>@better-auth/passkey>@better-auth/core",
       "@protobufjs/utf8@<=1.1.0": "Security: overlong UTF-8 decoding - transitive via @apollo/server>@apollo/usage-reporting-protobuf",
-      "ws@>=8.0.0 <8.20.1": "Security: Uninitialized memory disclosure (GHSA-58qx-3vcg-4xpx) - transitive via @nestjs/graphql",
+      "ws@>=8.0.0 <8.21.0": "Security: Memory exhaustion DoS + uninitialized memory disclosure (GHSA-96hv-2xvq-fx4p) - transitive via @nestjs/graphql",
+      "ws@>=7.0.0 <7.5.11": "Security: Memory exhaustion DoS in ws 7.x (GHSA-96hv-2xvq-fx4p) - transitive via @nestjs/graphql>subscriptions-transport-ws",
       "qs@>=6.11.1 <=6.15.1": "Security: remotely triggerable DoS in qs.stringify with comma-format arrays (GHSA-q8mj-m7cp-5q26) - transitive via @compodoc/compodoc>body-parser",
       "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",
-      "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"
+      "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",
+      "form-data@<4.0.6": "Security: CRLF injection via unescaped multipart field names/filenames (GHSA-hmw2-7cc7-3qxx) - transitive via @getbrevo/brevo>axios and node-mailjet>axios",
+      "vite@>=8.0.0 <8.0.16": "Security: fs.deny bypass on Windows alternate paths + file read CVEs - transitive via better-auth>vitest",
+      "hono@<4.12.25": "Security: multiple CVEs <4.12.25 (prototype pollution, bodyLimit/Vary bypass, JWT NumericDate) - transitive via @nestjs/terminus>prisma>@prisma/dev",
+      "nodemailer@<9.0.1": "Security: email/header injection CVEs <9.0.1 - direct dependency",
+      "multer@<2.2.0": "Security: unhandled multipart errors / DoS <2.2.0 - transitive via @nestjs/platform-express",
+      "js-yaml@<4.2.0": "Security: special-character handling / prototype pollution (patched in 4.2.0; 4.1.2 was never published) - transitive via @nestjs/swagger"
     },
     "overrides": {
       "axios@<1.16.0": "1.16.0",
@@ -226,13 +234,21 @@
       "path-to-regexp@>=8.0.0 <8.4.2": "8.4.2",
       "kysely@>=0.26.0 <0.28.17": "0.28.17",
       "@protobufjs/utf8@<=1.1.0": "1.1.1",
-      "ws@>=8.0.0 <8.20.1": "8.20.1",
+      "ws@>=8.0.0 <8.21.0": "8.21.0",
+      "ws@>=7.0.0 <7.5.11": "7.5.11",
       "qs@>=6.11.1 <=6.15.1": "6.15.2",
       "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",
-      "postcss@<8.5.10": "8.5.12"
+      "postcss@<8.5.10": "8.5.12",
+      "esbuild@>=0.17.0 <0.28.1": "0.28.1",
+      "form-data@<4.0.6": "4.0.6",
+      "vite@>=8.0.0 <8.0.16": "8.0.16",
+      "hono@<4.12.25": "4.12.25",
+      "nodemailer@<9.0.1": "9.0.1",
+      "multer@<2.2.0": "2.2.0",
+      "js-yaml@<4.2.0": "4.2.0"
     },
     "//peerDependencyRules": "allowedVersions: deps lag behind our newer majors (graphql-upload wants @types/express@^4, the deprecated apollo playground plugin wants @apollo/server@^4) — both work with our v5. ignoreMissing: browser-only vis-network peers pulled in transitively via yuml-diagram (server-side UML generation never renders, so these are not needed).",
     "peerDependencyRules": {

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

@@ -0,0 +1,69 @@
+/**
+ * Build identity helpers.
+ *
+ * A deployed image's exact build is identified by its git commit SHA, baked in
+ * at build time via an environment variable (default `APP_VERSION_COMMIT`, fed
+ * from the CI commit SHA — the same value typically used as the image tag).
+ *
+ * Unlike the semantic `version` (a rarely-bumped semver that may legitimately
+ * differ between an API and its frontend, since each is versioned independently)
+ * the commit SHA uniquely pins the exact running build. A frontend and backend
+ * deployed together bake the SAME commit, but each reads its own at runtime — so
+ * comparing them detects a drifted / stale container after a partial rollout.
+ *
+ * @see getCommit
+ * @see getBuildInfo
+ */
+
+/** 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';
+
+/**
+ * Build identity of the running process.
+ */
+export interface BuildInfo {
+  /** Git commit SHA the build was produced from, or `'unknown'`. */
+  commit: string;
+
+  /** Environment the process runs in (e.g. `'production'`), if provided. */
+  env?: string;
+
+  /** Semantic version of the build, or `'unknown'`. */
+  version?: string;
+}
+
+/**
+ * Resolve the git commit SHA the running build was produced from.
+ *
+ * Reads `process.env[envName]` (default `APP_VERSION_COMMIT`). Falls back to
+ * `'unknown'` so local / un-tagged builds still return a defined value — clients
+ * use `'unknown'` to suppress the "builds drifted" warning instead of comparing
+ * against an empty string.
+ *
+ * @param envName Name of the environment variable holding the commit SHA.
+ */
+export function getCommit(envName: string = DEFAULT_COMMIT_ENV): string {
+  return process.env[envName] || UNKNOWN_COMMIT;
+}
+
+/**
+ * Assemble the build identity of the running process.
+ *
+ * Combines the commit SHA (from the environment) with an optionally supplied
+ * `version` and `env`. Designed to be surfaced via a public meta / info endpoint
+ * and the health check so deployments can be compared at a glance.
+ *
+ * @param options.commitEnvName Override the env var the commit SHA is read from.
+ * @param options.env Environment label to include (e.g. from the config).
+ * @param options.version Semantic version to include (e.g. from package.json).
+ */
+export function getBuildInfo(options: { commitEnvName?: string; env?: string; version?: string } = {}): BuildInfo {
+  return {
+    commit: getCommit(options.commitEnvName),
+    env: options.env,
+    version: options.version || UNKNOWN_COMMIT,
+  };
+}