@servicelabsco/nestjs-utility-services 2.0.15 → 3.0.2

package/docs/upgrade-3.0-backward-compatibility.md

@@ -0,0 +1,223 @@
+# Upgrading to 3.x — backward compatibility and migration
+
+`@servicelabsco/nestjs-utility-services` **3.0.0** is a security and correctness major. Most
+breaks are **intentional and not reversible via a global flag**. This guide maps each area that
+typically breaks consuming Finnoto apps, what changed, how to migrate, and where a **temporary**
+escape hatch exists.
+
+Read this **before** bumping the package version or running pending migrations.
+
+---
+
+## Quick pre-flight checklist
+
+| Step | Action |
+| --- | --- |
+| Runtime | Move API and workers to **Node 24** (`engines: ^24.11.0`). |
+| Internal calls | Set `INTERNAL_SERVER_KEY` in env (see below). |
+| DB | Archive `sys_event_logs` / `sys_system_logs` if needed; schedule jsonb + refresh-token migrations. |
+| Integrations | Audit webhooks, email-template fetch hosts, PDF HTML URL storage, stored scripts. |
+| Auth | Expect stricter role checks and live session revocation after re-login. |
+| Mail | SES failures now fail jobs — monitor mail logs after deploy. |
+
+---
+
+## Breaker reference
+
+### 1. `INTERNAL_SERVER_KEY` required
+
+| | |
+| --- | --- |
+| **Why it hits us** | `InternalMiddleware` guards `internal/*`. The DB property `internal.server.key` is **ignored** unless you opt in. Missing env → internal service-to-service calls fail. |
+| **What changed** | Secret resolution: `INTERNAL_SERVER_KEY` env first; DB fallback only when `INTERNAL_SERVER_KEY_ALLOW_DB_FALLBACK=true`. Without either, `internal/*` returns an error. |
+| **Migrate (preferred)** | Set `INTERNAL_SERVER_KEY` in the API (and any caller) secret store. Rotate off the admin-editable DB row. |
+| **Temporary compat** | `INTERNAL_SERVER_KEY_ALLOW_DB_FALLBACK=true` restores legacy DB lookup. **Remove once env is set** — the DB row is mutable from the admin API. |
+
+```bash
+# Production (preferred)
+INTERNAL_SERVER_KEY=<long-random-secret>
+
+# Transitional only
+INTERNAL_SERVER_KEY_ALLOW_DB_FALLBACK=true
+```
+
+**Files:** `src/auth/middlewares/internal.middleware.ts`, `src/app.module.ts` (`internal/*` routes).
+
+---
+
+### 2. SSRF guard on `RemoteRequestService`
+
+| | |
+| --- | --- |
+| **Why it hits us** | Slack, Zoho, Amazon, FCM, webhooks, and email-template HTTP fetch go through `RemoteRequestService`. Public HTTPS still works. **Loopback, RFC1918, link-local, and cloud metadata IPs are blocked** unless explicitly allowed. |
+| **What changed** | `assertSafeRequestUrl` on initial URL and redirect hops. `sendThroughAxios` throws `OperationException`. **`getRawResponse` never throws** — blocked URL → `{ success: false, data: { error: … } }` (easy to miss in logs). |
+| **Silent failure paths** | Callers using `getRawResponse` without checking `success`. Watch **`email.template.host.server`** (and similar sys properties) and tenant webhooks aimed at private IPs. MCP loopback uses `fetch`, not this service. |
+| **Migrate** | Point integrations at public URLs, **or** pass `allowInternal: true` on that specific request (options or `RemoteRequestConfigDto`). |
+| **Temporary compat** | **No global disable.** Per-request `allowInternal: true` only — deliberate opt-in per integration. |
+
+```typescript
+// Example: intentional call to an internal webhook on a private host
+await remoteRequestService.getRawResponse(
+    { method: 'POST', url: 'http://10.0.0.5/hook', data: payload, allowInternal: true },
+    sourceConfig,
+);
+
+// Always check getRawResponse results
+const res = await remoteRequestService.getRawResponse(options, source);
+if (!res?.success) {
+    // was silently ignored before when URL was blocked
+}
+```
+
+**Files:** `src/platformUtility/services/remote.request.service.ts`, `src/platformUtility/dtos/remote.request.config.dto.ts`.
+
+---
+
+### 3. PDF HTML URLs (public by default, optional private)
+
+| | |
+| --- | --- |
+| **Why it hits us** | If you opted into `{ private: true }` on `PdfService.getHtmlUrl` / `uploadHtml`, the object is **`ACL: private`** and the returned URL is a **presigned GET** that expires after TTL. Anything storing that URL as durable state breaks after TTL. |
+| **What changed (3.0.0)** | 3.0.0 briefly defaulted to private + presigned. **Current default restores legacy behaviour:** `public-read` ACL and a **permanent** object URL (same as pre-3.0 slabs). High-entropy object names remain (U-S6). |
+| **Migrate** | No change needed for typical callers — default matches old slabs. For sensitive documents, pass `{ private: true }` and store bucket + key, re-sign at read time. |
+| **Temporary compat** | Default is already public. Private mode: `{ private: true }` on `uploadHtml` / `getHtmlUrl` / `getUrl`. TTL when private: sys property `pdf.html.signed.url.ttl.seconds` (**900s** default). |
+| **Constructor** | Manual `new PdfService(...)` requires a 5th arg: `StorageService`. DI-wired apps are unaffected. |
+
+```typescript
+// Default — permanent public URL (legacy)
+await pdfService.getHtmlUrl('invoice', data, 'tmp/invoices');
+
+// Sensitive — private object + presigned URL for the Lambda
+await pdfService.getHtmlUrl('invoice', data, 'tmp/invoices', { private: true });
+```
+
+**Files:** `src/platformUtility/services/pdf.service.ts`, `src/platformUtility/interfaces/html.pdf.upload.options.interface.ts`.
+
+---
+
+### 4. Stored scripts — `fn.getService` / `fn.getEntity` / `fn.getJob`
+
+| | |
+| --- | --- |
+| **Why it hits us** | Code-fix scripts, report scripts, and business-rule eval sites that still call the old helpers **throw at runtime** (not at compile time). |
+| **What changed** | Removed from sandbox: `fn.getEntity`, `fn.getService`, `fn.getJob`, `fn.getServiceInstance`, `fn.getEntityInstance`. Replacement API returns plain data only (no host object escape). |
+| **Migrate** | |
+
+| Old | New |
+| --- | --- |
+| `fn.getService('hash').method()` | `fn.callService('hash', 'method', ...args)` |
+| `fn.getEntity('type').method()` | `fn.callEntity('type', 'method', ...args)` |
+| `fn.getJob('hash').dispatch(data)` | `fn.dispatchJob('hash', data, delay?)` → returns job id |
+| `fn.getServiceInstance(...)` | `fn.callService(...)` (business rules) |
+
+| **Temporary compat** | Legacy `fn.getEntity` / `fn.getService` / `fn.getJob` (and business-rule `getServiceInstance` / `getEntityInstance`) are restored via **remote handles** — method calls work as before; host objects stay on the host. Prefer `fn.call*` for new scripts. |
+
+**Files:** `src/system/libraries/code.evaluator.ts`, `process.script.execution.ts`, `business.rule.query.evaluator.ts`.
+
+---
+
+### 5. Auth fail-closed (`hasRoleIdentifier` and related)
+
+| | |
+| --- | --- |
+| **Why it hits us** | Listing overrides, data access, approval delegation, and similar paths using `AccessService.hasRoleIdentifier` (and related helpers) **deny when role/permission arrays are missing**. Previously `undefined !== -1` accidentally **granted** access. |
+| **What changed** | `has()` requires a real array containing the identifier. Non-admin `getUserObject()` omits role arrays — checks now correctly deny. `public` means **authenticated**, not anonymous. |
+| **Migrate** | Assign explicit roles/permissions on users. Use `public` only where any logged-in user should pass. Audit custom controllers that assumed “no roles = allow”. |
+| **Temporary compat** | **None** — privilege-escalation fix (FIN-246). |
+
+**Files:** `src/auth/services/access.service.ts`.
+
+---
+
+### 6. Revoked sessions reject (logout works)
+
+| | |
+| --- | --- |
+| **Why it hits us** | After logout or admin revoke, the access token now yields **`AccessException('This session has been revoked…')`** instead of continuing anonymously. |
+| **What changed** | Login mints `session_identifier` in JWT + DB row. `JwtMiddleware` validates via `AuthService.validateSession()`. Refresh reuse/revoke → `AccessException`. |
+| **Migrate** | Clients must treat 401/403 on revoked tokens as “force re-login”. No server-side toggle. |
+| **Legacy tokens** | JWTs issued **before** upgrade without `session_identifier` cannot be revoked until the user re-logins. |
+| **Temporary compat** | **None** — previous anonymous fall-through was the bug (FIN-245). |
+
+**Files:** `src/auth/middlewares/jwt.middleware.ts`, `src/auth/services/auth.service.ts`.
+
+---
+
+### 7. SES send now rejects
+
+| | |
+| --- | --- |
+| **Why it hits us** | Email jobs that depended on SES “succeeding” even when AWS rejected the send will **start failing for real**. Mail logs no longer get a fake success identifier. |
+| **What changed** | `ProcessSesMail` propagates SDK errors (aligned with SMTP and SES Raw). Previously: `console.log(err); return err` — looked like success. |
+| **Migrate** | Fix SES config (identity, sandbox, quotas). Handle rejection in job retry/alerts. |
+| **Temporary compat** | **None** — correctness fix. |
+
+**Files:** `src/platformUtility/libraries/process.ses.mail.ts`.
+
+---
+
+### 8. Database migrations
+
+| | |
+| --- | --- |
+| **Why it hits us** | Pending NU migrations on deploy can drop data, lock hot tables, or fail on restricted Postgres roles. |
+| **What changed** | |
+
+| Migration | Effect |
+| --- | --- |
+| `1779685411636` / `1779685411637` | **Drop** `sys_event_logs`, `sys_system_logs` — data gone; `down()` recreates empty shells only. |
+| `1780002352495` | **json → jsonb** on ~103 columns; `ACCESS EXCLUSIVE` locks; skips already-jsonb (re-runnable). |
+| `1779807657061` | Refresh tokens: plaintext → hash; needs **`pgcrypto`** (or PG11+ `sha256()`). |
+
+| **Migrate** | Archive log tables before migrate. Run jsonb in a **maintenance window**. Pre-create `CREATE EXTENSION IF NOT EXISTS pgcrypto` on locked-down DBs. |
+| **Temporary compat** | `MIGRATION_LOCK_TIMEOUT` (default `5s`) — increase e.g. `30s` for lock acquisition only. **No skip flags** for drops or pgcrypto. |
+
+```bash
+# Optional: jsonb migration lock wait
+MIGRATION_LOCK_TIMEOUT=30s
+```
+
+**Scripts:** `scripts/verify-jsonb-migration.ts`, `docs/migrations.md`.
+
+---
+
+## Escape hatches summary
+
+| Area | Temporary escape | Remove when |
+| --- | --- | --- |
+| Internal auth | `INTERNAL_SERVER_KEY_ALLOW_DB_FALLBACK=true` | `INTERNAL_SERVER_KEY` set in env |
+| SSRF | Per-request `allowInternal: true` | Integration uses public URL or approved internal route |
+| PDF URLs | Default public-read; `{ private: true }` for presigned | Sensitive docs use private mode |
+| Scripts | Legacy `fn.get*` restored via remote handles | New scripts can still use `fn.call*` |
+| Access checks | — | Roles assigned explicitly |
+| Sessions | — | Clients handle revoke as re-login |
+| SES | — | SES config fixed |
+| Migrations | `MIGRATION_LOCK_TIMEOUT` | Maintenance window complete |
+
+---
+
+## Other 3.0 breaks (see CHANGELOG)
+
+- **Node 24** required.
+- **`MAIL_ATTACHMENT_LOCAL_ROOT`** — local attachment reads restricted to this directory (default `os.tmpdir()`).
+- **CORS** — boot requires `CORS_ORIGINS` or `CORS_ALLOW_ANY_ORIGIN=true` (`src/config/cors.config.ts`).
+- **Sentry** — see [sentry-reporting.md](./sentry-reporting.md) for consumer wiring.
+- **Removed types/services** — `LoggerService`, `EventLogEntity`, `CommonJob` logging helpers, etc. (full list in `CHANGELOG.md`).
+
+---
+
+## Suggested upgrade order
+
+1. Deploy **env** changes (`INTERNAL_SERVER_KEY`, CORS, Node 24) without code bump — validate internal routes.
+2. Run **DB archive + migrations** in maintenance window.
+3. Bump **package** to 3.x; deploy API then workers.
+4. Smoke-test: internal token, one webhook, one PDF flow, one script, logout, one SES send.
+5. Remove transitional flags (`INTERNAL_SERVER_KEY_ALLOW_DB_FALLBACK`, per-call `allowInternal` where no longer needed).
+
+---
+
+## Related docs
+
+- [CHANGELOG.md](../CHANGELOG.md) — full breaking change list
+- [sentry-reporting.md](./sentry-reporting.md) — Sentry integration for consuming apps
+- [migrations.md](./migrations.md) — TypeORM migration workflow

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicelabsco/nestjs-utility-services",
-    "version": "2.0.15",
+    "version": "3.0.2",
     "description": "NestJS generic packages to support development",
     "author": "Hemant Kumar Sah <hemantanshu@gmail.com>",
     "license": "MIT",
@@ -8,7 +8,11 @@
     "main": "dist/index.js",
     "files": [
         "dist/**/*",
-        "*.md"
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE",
+        "docs/sentry-reporting.md",
+        "docs/upgrade-3.0-backward-compatibility.md"
     ],
     "types": "dist/index.d.ts",
     "scripts": {
@@ -19,6 +23,7 @@
         "start:debug": "nest start --debug --watch",
         "start:prod": "node dist/main",
         "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+        "lint:codebase": "ts-node --project scripts/tsconfig.json scripts/lint-codebase.ts",
         "test": "jest",
         "test:watch": "jest --watch",
         "test:cov": "jest --coverage",
@@ -31,13 +36,15 @@
         "m:c": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:create -d src/config/orm.config.ts",
         "m:rev": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:revert -d src/config/orm.config.ts",
         "runtime-check": "curl -s http://localhost:${SERVER_PORT:-4000}/health/runtime-check | jq . 2>/dev/null || curl -s http://localhost:${SERVER_PORT:-4000}/health/runtime-check",
+        "verify:publish": "node scripts/verify-publish-artifacts.js",
+        "prepublishOnly": "node scripts/verify-publish-artifacts.js",
         "save": "bash ./commit.sh"
     },
     "keywords": [
         "nestjs"
     ],
     "engines": {
-        "node": "^22.0.0 || ^24.11.0"
+        "node": "^24.11.0"
     },
     "publishConfig": {
         "access": "public"
@@ -68,6 +75,7 @@
         "@nestjs/typeorm": "^11.0.0",
         "@nestjs/websockets": "^11.0.0",
         "@sentry/core": "^10.34.0",
+        "@sentry/nestjs": "^10.34.0",
         "@sentry/node": "^10.34.0",
         "@socket.io/redis-adapter": "^8.2.1",
         "axios": "^1.7.9",
@@ -77,6 +85,7 @@
         "class-validator": "^0.15.1",
         "cron-parser": "^5.5.0",
         "date-fns": "^4.1.0",
+        "decimal.js": "^10.6.0",
         "dotenv": "^17.2.3",
         "exceljs": "^4.4.0",
         "express-http-context2": "^1.0.0",
@@ -85,7 +94,6 @@
         "helmet": "^8.1.0",
         "html-to-text": "^10.0.0",
         "ioredis": "^5.9.2",
-        "js-yaml": "^4.1.1",
         "mongodb": "^7.1.0",
         "nodemailer": "^8.0.2",
         "pg": "^8.17.1",
@@ -114,6 +122,7 @@
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-prettier": "^5.5.5",
         "jest": "^30.2.0",
+        "js-yaml": "^4.1.1",
         "prettier": "^3.8.0",
         "supertest": "^7.2.2",
         "ts-jest": "^29.4.6",

package/AGENTS.md

@@ -1,189 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
-
-## Repository nature
-
-This is a **publishable npm library** (`@servicelabsco/nestjs-utility-services`) that ships compiled output from `dist/` (`main: dist/index.js`). The `src/index.ts`-equivalent (see `dist/index.d.ts`) re-exports `auth`, `common`, `platformUtility`, `security`, `system`, and `worker.service`. Consuming apps install this package and import its modules/services/entities.
-
-It is also runnable as a **standalone NestJS app** (`main.ts` / `worker.ts`) for local development of the library itself — running migrations, exercising endpoints, validating wiring. Treat changes as library changes first: anything exported is part of the public API.
-
-## Common commands
-
-```bash
-yarn build                # nest build → dist/
-yarn start:dev            # watch mode standalone app (main.ts)
-yarn start:prod           # node dist/main
-yarn lint                 # eslint --fix on src/, apps/, libs/, test/
-yarn format               # prettier on src/ and test/
-yarn test                 # jest (rootDir=src, *.spec.ts)
-yarn test -- path/to/file.spec.ts          # run a single test file
-yarn test -- -t "matches test name"        # run tests by name
-yarn test:cov             # coverage → ../coverage
-yarn test:e2e             # jest --config ./test/jest-e2e.json (*.e2e-spec.ts)
-
-# Migrations (TypeORM, src/config/orm.config.ts)
-yarn m:g <name>           # generate from entity diff
-yarn m:c <name>           # create empty
-yarn m:r                  # run pending (ts-node, dev)
-yarn m:rd                 # run pending against compiled dist
-yarn m:rev                # revert last
-
-yarn runtime-check        # curl /health/runtime-check (cron-parser + cache sanity)
-yarn save                 # repo-specific commit helper (see commit.sh)
-```
-
-`yarn save` runs `commit.sh`: pulls, optionally builds, optionally runs `slnu syncClassess`, prettier-formats, then commits as `<JIRA-ID> #comment <message>` extracting the JIRA ID from the current branch name. The recent commit history follows this pattern — preserve it for any commits made through this script.
-
-## High-level architecture
-
-### Five top-level NestJS modules under `src/`
-
-- **`auth/`** — users, sessions, JWT, refresh tokens, social login, device tokens, role/permission assignment. Owns `JwtMiddleware`, `BasicAuthMiddleware`, `InternalMiddleware`, `RestrictedMiddleware`.
-- **`common/`** — framework-level base classes and utilities. The module itself is empty (`@Module({})`); its value is the exported classes. Most other modules and consumers extend these. **`CommonEntity`** (audit/who-columns, soft delete, `firstOrNew`, helpers — all postgres entities extend this), `CommonMongoEntity`, `CommonService`, `CommonSubscriber`, `CommonJob`, `CommonConsumer`, `CommonMapperJob`, `MigrationUtility` / `BaseMigrationUtility` / `ReverseMigrationUtility` (wrap TypeORM migrations), `Auth` (static accessor over express-http-context2 — `Auth.user()`, `Auth.check()`, `Auth.id()`, `Auth.login()`), exception classes (`OperationException`, `AccessException`, `FormException`, `MaintenanceException`, `NoLoggedUserException`, `SubscriptionException`), and pure helpers (`Hash`, `CustomCrypt`, `DateUtil`, `PlatformUtility`, `JsonEvaluator`, `EntityEvaluator`, `DatabaseEventEvaluator`, `GenericIndexParser`, `GenericShowParser`, `ReportBodyParser`, `DataManager`, `RecordManager`, `ListManager`, `ReportListManager`, `ReportDataManager`, `ClassMapper`, `CustomLogger`, `SeederUtility`).
-- **`platformUtility/`** — infra-adjacent services: `S3Service`, `SqsService`, `DynamoService`, `RedisService`, `CacheService` (Redis-backed), `QueueService` (BullMQ), `MailService` (with SMTP/SES variants in `libraries/`), `SmsService`, `FcmNotificationService`, `RemoteRequestService`, `AwsConfigService`, `AwsSecretService`, `SqlService`, `ZipService`, `MaintenanceService`, `AuditService`, `StartupService`, `ShutdownService`. Hosts `JobConsumer` (the BullMQ consumer), `MaintenanceMiddleware`, `TrimPipe`.
-- **`security/`** — registers security-related entities (TypeORM `forFeature`); module is otherwise pass-through.
-- **`system/`** — the bulk of the domain: ~70 entities for menus, roles, permissions, models, columns, relationships, properties, lookups, forms, reports, charts, scripts, scheduled events, mail/sms/whatsapp templates, document storage. Controllers (`BaseController`, `DataController`, `FormController`, `MenuController`, `PreferenceController`, `ReportController`, `UploadController`, `UserPreferenceController`), services for each domain area, jobs that drive recurring/material-view/code-fix/scheduled execution, subscribers that react to entity events, and a `SentryInterceptor`.
-
-### Module wiring convention — `es6.classes.ts`
-
-Every module folder has an `es6.classes.ts` that imports every controller/service/dto/entity/job/subscriber/middleware/library/consumer in that module and exports a single object with arrays. The module file then spreads those arrays into `@Module({ providers, controllers, exports, imports: [TypeOrmModule.forFeature(es6Classes.entities), ...] })`. **When adding a new class to a module, you must register it in that module's `es6.classes.ts` — otherwise it will not be wired into Nest's DI.** The `slnu syncClassess` step in `commit.sh` regenerates these files via libraries in `platformUtility/libraries/create.es6.*.ts` and `create.entity.constants.file.ts`; prefer running it instead of editing by hand when you've added several files.
-
-### `app.module.ts` composition
-
-Top-level wiring:
-- Three TypeORM connections: **`default`** (postgres write — `src/config/typeorm.config.ts`), **`read`** (postgres read replica — `src/config/read.typeorm.config.ts`), **`mongodb`** (`src/config/mongo.config.ts`).
-- BullMQ via `src/config/queue.config.ts`; queue name from `BULL_QUEUE_NAME`. `PlatformUtilityModule` registers consumers only when `BULL_QUEUE_WORKER=true` (otherwise `es6Classes.consumers = []`).
-- TerminusModule for `/health` (master + read replica + redis + filesystem checks in `health.check.controller.ts`; `/health/runtime-check` validates cron-parser v5 and cache round-trip).
-- Middleware order applied to all routes: `MaintenanceMiddleware` → `JwtMiddleware` → `BasicAuthMiddleware`. `RestrictedMiddleware` on `api/*` (rejects unauthenticated). `InternalMiddleware` on `internal/*` (validates `x-internal-token` against `internal.server.key` property, then logs in user id 2).
-
-### Entity / migration discovery
-
-Both `typeorm.config.ts` (write) and `mongo.config.ts` glob entities from **the current build dir AND `node_modules/@servicelabsco/**`**:
-
-```ts
-entities: [
-  join(__dirname, '/../**/**/*.entity.{ts,js}'),
-  join(__dirname, '..', '..', 'node_modules/@servicelabsco/**/*.entity.{ts,js}'),
-],
-```
-
-Mongo uses `*.mentity.{ts,js}` and `*.mongo.subscriber.{ts,js}`. Migrations are similarly merged from this repo's `src/migrations/` and any `@servicelabsco/*` package's `migrations/` dir. `migrationsTableName` is `sys_migrations`. **This means migrations from sibling packages run in this app's database** — be aware when generating new ones, and don't duplicate names across packages.
-
-A snake_case naming strategy (`typeorm-naming-strategies`) maps camelCase entity columns to snake_case in postgres. Postgres `bigint` (oid 20) and `decimal` (oid 1700) are auto-cast to JS `number`/`float` in `pg.types.setTypeParser`.
-
-### Worker vs API
-
-`main.ts` is the HTTP entrypoint (helmet, CORS, rate limit, compression, sentry, global ValidationPipe with `whitelist: true, transform: true`, optional graceful shutdown via `SERVER_COOL_DOWN_PERIOD`). `worker.ts` is the queue-worker entrypoint — same `AppModule`, no `listen()`, just `init()` + shutdown hooks; in this mode `BULL_QUEUE_WORKER=true` is required for consumers to register. `WorkerService.onModuleInit` calls `MaintenanceService.disableQueueIfRequired()` before processing starts.
-
-### Auth context
-
-Request-scoped user is stored via `express-http-context2` and accessed everywhere through the static `Auth` class (`src/common/libraries/auth.ts`). `JwtMiddleware` sets it from a Bearer token; `InternalMiddleware` sets it to user id 2 after validating the internal token. **Never inject the user from the request manually** — use `Auth.user()` / `Auth.id()` / `Auth.check()` so behavior is consistent with the rest of the codebase, and so it works in jobs/consumers that propagate the context.
-
-### Tests
-
-Jest config lives in `package.json` (`rootDir: src`, `testRegex: .*\\.spec\\.ts$`, `ts-jest`). E2E uses `test/jest-e2e.json` with `*.e2e-spec.ts`. Tests sit alongside source as `*.spec.ts` (e.g. `auth.service.spec.ts`, `cache.service.spec.ts`, `zip.service.spec.ts`, all of `common/libraries/`, all of `common/exceptions/`).
-
-## Conventions to follow
-
-- **4-space indent, single quotes, 150-char line width** (`.prettierrc`). Run `yarn format` before committing.
-- New entities extend `CommonEntity` (or `CommonMongoEntity` for mongo) — never `BaseEntity` directly. Filename suffix is `.entity.ts` (postgres) or `.mentity.ts` (mongo) — the loader globs depend on this.
-- New subscribers: filename `*.subscriber.ts` (postgres) or `*.mongo.subscriber.ts` (mongo).
-- New services extend `CommonService`. New jobs extend `CommonJob` / `CommonMapperJob`. New consumers extend `CommonConsumer`.
-- Throw the project's exception classes (`OperationException`, `AccessException`, etc.) rather than raw `HttpException` / `Error` — they integrate with the response shape and (where applicable) sentry.
-- Migrations: instantiate `MigrationUtility` (or `ReverseMigrationUtility`) in the generated migration class so the `up`/`down` semantics handle the reverse-migration flag correctly. Migration filenames follow `<timestamp>-<PascalCaseDescription>.ts`.
-- After adding files to a module, regenerate or update that module's `es6.classes.ts` so DI picks it up.
-- Library/exported public API: anything added under the five top-level modules is reachable by consumer apps via `@servicelabsco/nestjs-utility-services`. Avoid breaking renames/removals of exports without considering downstream impact, and rebuild (`yarn build`) before publishing.
-
-## File and class naming conventions
-
-These rules are not merely stylistic — the `slnu syncClassess` dev CLI walks every module subdirectory and emits `import { ClassName } from './${dir}/${file}'` for every file it finds. If a file does not export a named symbol matching its filename, the generated `es6.classes.ts` will not compile. Honour the conventions even when you think they don't matter.
-
-### Filename ↔ export name match
-
-The filename basename (dot-separated lowercase) maps to PascalCase + a suffix derived from the file's last segment:
-
-| Filename                         | Required named export             |
-|----------------------------------|-----------------------------------|
-| `aws.s3.service.ts`              | `AwsS3Service`                    |
-| `create.user.dto.ts`             | `CreateUserDto`                   |
-| `user.entity.ts`                 | `UserEntity`                      |
-| `object.ref.interface.ts`        | `ObjectRefInterface`              |
-| `scheduled.event.subscriber.ts`  | `ScheduledEventSubscriber`        |
-| `recurring.query.job.ts`         | `RecurringQueryJob`               |
-| `storage.constants.ts`           | `StorageConstants` (object — see below) |
-
-Single primary export per file. Helpers tightly coupled to the primary (e.g. `storage.upload.options.dto.ts` exports `StorageSseOptions` next to the primary `StorageUploadOptionsDto`) may co-locate, but **peer types must each live in their own file** — do not stuff multiple unrelated interfaces in one file.
-
-### Interfaces and types live in `interfaces/`, not `dtos/`
-
-`dtos/` is for class-based DTOs (often with `class-validator` decorators). Pure TypeScript `interface` / `type` declarations belong under a sibling `interfaces/` directory:
-
-```
-src/system/dtos/file.upload.dto.ts          # class FileUploadDto {}
-src/system/interfaces/object.ref.interface.ts   # interface ObjectRefInterface {}
-src/system/interfaces/storage.ref.interface.ts  # type StorageRefInterface = string | ObjectRefInterface
-```
-
-File suffix `.interface.ts`, type name suffix `Interface`. One type per file when types are peers.
-
-### Constants: single-bag object pattern
-
-Constants files are exempt from "one class per file" but still must match the filename↔export rule. Use a **named object export** (not `export = ...`, which breaks the dev CLI's named-import generation):
-
-```ts
-// src/system/constants/storage.constants.ts
-export const StorageConstants = {
-    ENGINE_S3: 's3',
-    ENGINE_R2: 'r2',
-};
-```
-
-Consumers: `import { StorageConstants } from '...'; StorageConstants.ENGINE_S3`.
-
-`src/config/source.hash.ts` uses the older `export = SourceHash` + `import SourceHash = require(...)` pattern — that's legacy. New constants files should use `export const Foo = {...}`.
-
-### No "bag of functions" files
-
-Do not create files (like the now-removed `sql.safety.ts`) whose only purpose is to `export function ...`. The convention is one class/object per file; bare functions don't fit it. Fold helpers into the class that owns the responsibility — e.g. SQL safety helpers (`isSafeOrderBy`, `escapeSqlString`, `detectSqlInjectionSignature`, `detectHighConfidenceInjection`) live as **instance methods** on `SqlService`.
-
-When the helper needs to be reached from a manually-instantiated (non-DI) class like `GenericIndexParser` or `GetReportQuery`, thread the owning service through the constructor:
-
-```ts
-new GenericIndexParser(query, this.sqlService).process();
-new GetReportQuery(this.report, this.sqlService).process(...);
-```
-
-### Prefer instance methods over static
-
-Service methods should be instance methods (`this.sqlService.isSafeOrderBy(x)`), not static (`SqlService.isSafeOrderBy(x)`). Instance methods give consistent DI/mocking semantics and stay testable via the injected instance. Reserve `static` for genuinely class-level concerns like factories or singletons.
-
-### Module wiring lives in `es6.classes.ts`, not inline in module files
-
-The dev CLI regenerates each module's `es6.classes.ts` from filesystem contents. Module files (`system.module.ts`, `platform.utility.module.ts`, etc.) should be minimal:
-
-```ts
-@Module({
-    imports: [TypeOrmModule.forFeature(es6Classes.entities), ...],
-    controllers: es6Classes.controllers,
-    providers: [...es6Classes.services, ...es6Classes.subscribers, ...es6Classes.jobs],
-    exports: [...es6Classes.services, ...es6Classes.jobs],
-})
-export class SystemModule {}
-```
-
-Avoid inline `{ provide: SOME_TOKEN, useFactory: ... }` provider blocks. If a service consumes a set of adapter classes, **inject the adapter classes directly** rather than introducing a DI token + factory:
-
-```ts
-// Good — wiring is automatic via es6Classes.services
-constructor(private readonly s3: AwsS3Service, private readonly r2: CloudflareR2Service) {
-    this.registry = new Map([[s3.engineId, s3], [r2.engineId, r2]]);
-}
-
-// Avoid — pulls bespoke wiring into the module file
-constructor(@Inject(STORAGE_ENGINE_ADAPTERS) adapters: CommonStorageService[]) { ... }
-```
-
-### Fixing CLI fallout
-
-If `slnu syncClassess` emits a broken import, the source file violates the naming convention — fix the source file (rename, add the missing export, move it to the right directory). Do not hand-edit `es6.classes.ts` as a permanent workaround; the next CLI run will overwrite your edit.