11.23.0: Performance and security hardening — depth-aware process() pipeline, SafeModel type guard for mainDbModel, getNativeCollection/getNativeConnection escape hatches

Author: kaihaase

.claude/agent-memory/lt-dev-npm-package-maintainer/MEMORY.md

@@ -10,9 +10,14 @@
 - `@getbrevo/brevo` 3.x → 5.x: Complete API redesign (TransactionalEmailsApi, SendSmtpEmail, TransactionalEmailsApiApiKeys removed). Would require rewriting `src/core/common/services/brevo.service.ts`. See `blocking-updates.md` for details.
 - `graphql-upload` 15.x → 17.x: Extension changed from `.js` to `.mjs`. Import paths in `src/core.module.ts`, `src/core/modules/file/core-file.resolver.ts`, `src/server/modules/file/file.resolver.ts`, and `src/types/graphql-upload.d.ts` would all need updating.
 - `vite` 7.x → 8.x + `vite-plugin-node` 7.x → 8.x: Both must update together. vite-plugin-node@8.0.0 peerDep requires `vite: '^8.0.0'`. Blocked together.
-- `better-auth` + `@better-auth/passkey` 1.5.5 → 1.5.6: `@better-auth/core@1.5.6/dist/instrumentation/tracer.mjs` directly imports `@opentelemetry/api` (SpanStatusCode, trace) — causes "Cannot find package '@opentelemetry/api'" errors across 38+ test files. Verified on 2026-04-04. Do NOT update until better-auth resolves this dep or we add @opentelemetry/api as a dev dep.
+- `better-auth` + `@better-auth/passkey` 1.5.5 → 1.6.0: `@better-auth/core@1.6.0/dist/instrumentation/tracer.mjs` still directly imports `@opentelemetry/api` — causes "Cannot find package '@opentelemetry/api'" errors across 38+ test files. Verified on 2026-04-07. Do NOT update until better-auth resolves this dep or we add @opentelemetry/api as a dev dep. NOTE: 1.5.6 AND 1.6.0 both have this issue.
 - `typescript` 5.x → 6.x: TypeScript 6.0.2 released 2026-03-23 (very new). Ecosystem readiness unknown — skip until NestJS/tools explicitly support it.
 
+### Categorization Fix (Fixed 2026-04-07)
+- `supertest` and `@types/supertest` moved from `devDependencies` to `dependencies`.
+  Reason: `src/test/test.helper.ts` (exported via `src/index.ts`) imports `supertest` at runtime.
+  Consuming projects would get runtime errors without it in `dependencies`.
+
 ### Critical Categorization Issue (Fixed in 2026-03-11)
 - `ts-morph` was incorrectly in `devDependencies` but is IMPORTED in `src/core/modules/permissions/permissions-scanner.ts`. Moved to `dependencies`.
 
@@ -21,17 +26,18 @@
 - `mongoose@9.4.1` bundles `~mongodb@7.1.x` (same as 9.3.x), so current mongodb@7.1.1 is still compatible.
 - mongodb@7.1.1 is still the latest in the 7.x line — no update needed there.
 
-### Overrides Status (updated 2026-04-04)
-- minimatch overrides: updated to latest versions (3.1.5, 9.0.9, 10.2.5)
-- `rollup@>=4.0.0 <4.60.1` → `4.60.1` override: still needed (4.60.1 is current latest)
+### Overrides Status (updated 2026-04-07)
+- minimatch overrides: at latest versions (3.1.5, 9.0.9, 10.2.5) — still needed
+- `rollup@>=4.0.0 <4.60.1` → `4.60.1` override: **REMOVED 2026-04-07** — vite@7.3.2 now pulls rollup@4.60.1 directly, override was redundant
 - `ajv` overrides still needed
-- `undici@>=7.0.0 <7.24.7` → `7.24.7` override: updated from 7.24.3. @compodoc/compodoc>cheerio requires `^7.12.0` — still needed in 7.x range
-- `srvx@<0.11.15` → `0.11.15` override: updated from 0.11.13. @tus/server 2.3.0 requires `~0.8.2` — still needed
-- `handlebars@>=4.0.0 <4.7.9` → `4.7.9` override: @compodoc/compodoc requires `^4.7.8` — still needed for safety
+- `undici@>=7.0.0 <7.24.7` → `7.24.7` override: still needed. @compodoc/compodoc>cheerio requires `^7.12.0` — still needed in 7.x range
+- `srvx@<0.11.15` → `0.11.15` override: still needed. @tus/server 2.3.0 requires `~0.8.2` — still needed
+- `handlebars@>=4.0.0 <4.7.9` → `4.7.9` override: still needed for safety
 - `brace-expansion`, `picomatch`, `kysely` overrides: still needed (at latest)
-- `path-to-regexp@>=8.0.0 <8.4.2` → `8.4.2` override: updated from 8.4.1 (new patch)
+- `path-to-regexp@>=8.0.0 <8.4.2` → `8.4.2` override: still needed
 - `lodash@>=4.0.0 <4.18.0` → `4.18.1` override: @nestjs/graphql pins lodash@4.17.23 which has CVE. 4.18.1 is now the latest lodash.
-- `defu@<=6.1.4` → `6.1.6` override: still needed (6.1.6 is current latest)
+- `defu@<=6.1.4` → `6.1.6` override: **UPDATED 2026-04-07** to `defu@<=6.1.6` → `6.1.7` (6.1.7 is now the latest)
+- `vite@>=7.0.0 <=7.3.1` + `vite@>=7.1.0 <=7.3.1` duplicate overrides: **CONSOLIDATED 2026-04-07** to single `vite@>=7.0.0 <7.3.2` → `7.3.2`. Direct vite dep is now at 7.3.2.
 - **REMOVED 2026-04-03**: `file-type@>=13.0.0 <21.3.2` → all nestjs packages now at 11.1.17 with file-type 21.3.2 natively
 - **REMOVED 2026-04-03**: `yauzl@<3.2.1` → @swc/cli 0.8.1 bundles yauzl 3.2.1 directly
 - **REMOVED 2026-04-03**: `flatted@<=3.4.1` → @vitest/ui 4.1.2 requires `^3.4.2` already

.claude/rules/configurable-features.md

@@ -214,6 +214,7 @@ This pattern is currently applied to:
 | Secret Fields Removal | `security.secretFields` | Array | `['password', 'verificationToken', ...]` |
 | Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `CoreTenantGuard.invalidateUser(userId)` / `invalidateAll()` |
 | BetterAuth Tenant Skip | `betterAuth.skipTenantCheck` | Explicit Boolean | `true` (default). When `true` and no `X-Tenant-Id` header is sent, IAM endpoints (controller + resolver) skip `CoreTenantGuard` tenant validation. When header IS present, normal membership validation runs regardless. Set `false` for tenant-aware auth scenarios (subdomain-based, invite links, SSO per tenant) |
+| Debug Process Input | `debugProcessInput` | Explicit Boolean | `false` (default). When `true`, logs a debug message when `prepareInput()` changes the input type during `process()`. Has performance cost due to `JSON.stringify` on every `process()` call — enable only for debugging |
 
 ## Module Override Pattern (via `ICoreModuleOverrides`)
 

CLAUDE.md

@@ -167,8 +167,66 @@ Detailed documentation in `.claude/rules/`:
 | `package-management.md` | Fixed package versions only - no `^`, `~`, or ranges |
 | `framework-compatibility.md` | Maintenance obligations for FRAMEWORK-API.md, shipped docs, cross-repo dependencies |
 
+## Native MongoDB Driver — Security Rules
+
+### model.collection / model.db — BLOCKED
+
+Access to `this.mainDbModel.collection` and `this.mainDbModel.db` is blocked via TypeScript type (`SafeModel = Omit<Model, 'collection' | 'db'>`).
+For additionally injected models (`@InjectModel`): **NEVER** use `.collection.*` or `.db.*`.
+All Mongoose plugins (Tenant, Audit, RoleGuard, Password) are bypassed.
+
+**Use Mongoose Model methods instead:**
+
+| Forbidden | Allowed |
+|-----------|---------|
+| `collection.insertOne(doc)` | `Model.insertMany([doc])` |
+| `collection.bulkWrite(ops)` | `Model.bulkWrite(ops)` |
+| `collection.updateOne(f, u)` | `Model.updateOne(f, u)` |
+| `collection.updateMany(f, u)` | `Model.updateMany(f, u)` |
+| `collection.deleteOne(f)` | `Model.deleteOne(f)` |
+| `collection.deleteMany(f)` | `Model.deleteMany(f)` |
+| `collection.find(f)` | `Model.find(f)` or `Model.find(f).lean()` |
+| `collection.aggregate(p)` | `Model.aggregate(p)` |
+
+If native access is unavoidable: use `this.getNativeCollection(reason)` or `this.getNativeConnection(reason)` from CrudService.
+
+### connection.db.collection() — Use With Caution
+
+Allowed for:
+- Collections without Mongoose schema (OAuth, BetterAuth, MCP)
+- Read-only aggregations/counts on other collections
+- Admin operations (indexes, drops, backups)
+
+**NOT allowed for:**
+- Write operations on tenant-scoped collections → use Mongoose Model instead
+- CRUD on collections that have a Mongoose schema → use CrudService instead
+
+Details: [`docs/native-driver-security.md`](docs/native-driver-security.md)
+
+### CrudService process() Pipeline — Memory Considerations
+
+The `process()` pipeline (prepareInput → checkRights → serviceFunc → processFieldSelection → prepareOutput → checkRights) adds memory overhead per call through object cloning, Mongoose hydration, and populate operations. For typical API usage this is negligible, but it can become significant in:
+
+- **High-frequency operations** (e.g. monitor checks running every 10-60 seconds)
+- **Service cascades** (Service A → Service B → Service C, each going through process())
+- **Populate chains** (3-5 levels of nested population)
+
+**If a project experiences memory issues under high traffic**, check whether `process()` wrapping is the cause. Alternatives that preserve security:
+
+| Instead of | Use | Security |
+|-----------|-----|----------|
+| `CrudService.create(input)` | `Model.insertMany([input])` — triggers all Mongoose plugins | Tenant, Audit, RoleGuard, Password all active |
+| `CrudService.update(id, input)` | `Model.findByIdAndUpdate(id, input)` — triggers all Mongoose plugins | Tenant filter, Audit, RoleGuard all active |
+| `CrudService.updateForce(id, input)` | `Model.findByIdAndUpdate(id, { $set: input }).lean()` — for system-internal updates | Plugins active, no process() overhead |
+
+**NEVER** bypass Mongoose entirely via `collection.*` — see section above. The CheckSecurityInterceptor acts as a safety net on HTTP responses regardless of how data was written.
+
+Details: [`docs/process-performance-optimization.md`](docs/process-performance-optimization.md)
+
 ## In-Depth Documentation
 
 | File | Content |
 |------|---------|
 | [`docs/REQUEST-LIFECYCLE.md`](docs/REQUEST-LIFECYCLE.md) | Complete request lifecycle, security architecture, interceptor chain, decorator reference, CrudService pipeline, Safety Net, diagrams |
+| [`docs/native-driver-security.md`](docs/native-driver-security.md) | Native MongoDB Driver restrictions, secure alternatives, review checklist |
+| [`docs/process-performance-optimization.md`](docs/process-performance-optimization.md) | process() pipeline performance optimizations |

FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-04-04 (v11.22.1)
+> Auto-generated from source code on 2026-04-07 (v11.23.0)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()
@@ -21,6 +21,7 @@
   - `compression?`: `boolean | compression.CompressionOptions` — Whether to use the compression middleware package to enable gzip compression.
   - `cookies?`: `boolean` — Whether to use cookies for authentication handling
   - `cronJobs?`: `Record<string, string | false | 0 | CronJobConfigWithTimeZone<null, null> | C...` — Cron jobs configuration object with the name of the cron job function as key
+  - `debugProcessInput?`: `boolean` (default: `false`) — When true, logs a debug message when prepareInput() changes the input type during process().
   - `email?`: `{ defaultSender?: { email?: string; name?: string; }; mailjet?: MailjetOption...` — SMTP and template configuration for sending emails
   - `env?`: `string` — Environment
   - `errorCode?`: `IErrorCode` — Configuration for the error code module
@@ -183,7 +184,10 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 - `async findOne(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; }, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Find one item via filter
 - `async findOneForce(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model>` — Find one item via filter without checks or restrictions
 - `async findOneRaw(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model>` — Find one item via filter without checks, restrictions or preparations
-- `getModel()`: `MongooseModel<Document<Types.ObjectId, any, any, Record<string, any>, {}> & M...` — Get service model to process queries directly
+- `getModel()`: `MongooseModel<Document<Types.ObjectId, any, any, Record<string, any>, {}> & M...` — Get service model to process queries directly.
+- `getNativeCollection(reason: string)`: `Collection<Document>` — Get the native MongoDB Collection, bypassing all Mongoose plugins.
+- `getNativeConnection(reason: string)`: `Connection` — Get the Mongoose Connection (which provides access to the native MongoDB Db and MongoClient).
+- `validateNativeAccessReason(reason: string, method: string)`: `void`
 - `async read(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions)`: `Promise<Model | Model[]>` — CRUD alias for get or find
 - `async readForce(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions)`: `Promise<Model | Model[]>` — CRUD alias for getForce or findForce
 - `async readRaw(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions)`: `Promise<Model | Model[]>` — CRUD alias for getRaw or findRaw

docs/REQUEST-LIFECYCLE.md

@@ -863,15 +863,38 @@ The `process()` method in `ModuleService` is the **primary** way to handle CRUD
   +---------------------------------------------------------------+
 ```
 
+### Depth-Based Optimization (v11.23.0+)
+
+When `process()` is called from within another `process()` call (service cascades like A.create → B.create → C.create), steps 4–6 are **conditionally skipped** on inner calls to avoid redundant work:
+
+| Step | Depth 0 (outermost) | Depth > 0 (nested) |
+|------|---------------------|---------------------|
+| 1. prepareInput | Runs | Runs |
+| 2. checkRights (INPUT) | Runs | Runs |
+| 3. serviceFunc | Runs | Runs |
+| 4. processFieldSelection | Runs | **Skipped** (unless `populate` explicitly set) |
+| 5. prepareOutput (model mapping) | Runs | **Skipped** (secret removal still active) |
+| 6. checkRights (OUTPUT) | Runs | **Skipped** |
+
+**Security is maintained** because:
+1. Input authorization (step 2) always runs at every depth
+2. Output authorization (step 6) runs at the outermost call
+3. `CheckSecurityInterceptor` (Safety Net) runs on the final HTTP response
+
+**Important:** Code running at depth > 0 (cron jobs, queue consumers, event handlers outside the HTTP cycle) must NOT return data directly to external consumers without either an outer depth-0 `process()` call or manual `checkRights` — the output rights check is skipped at depth > 0.
+
+See [process() Performance Optimization](process-performance-optimization.md) for details.
+
 ### Key Options
 
 | Option | Type | Default | Effect |
 |--------|------|---------|--------|
 | `force` | boolean | `false` | Disables checkRights, checkRoles, removeSecrets, bypasses role guard plugin |
 | `raw` | boolean | `false` | Disables prepareInput and prepareOutput entirely |
 | `checkRights` | boolean | `true` | Enable/disable authorization checks |
-| `populate` | object | - | Field selection for population |
+| `populate` | object | - | Field selection for population (overrides nested skip) |
 | `currentUser` | object | from request | Override the current user |
+| `debugProcessInput` | boolean | `false` | Config flag: log when prepareInput changes the input type (performance cost) |
 
 ### Alternative: processResult()
 
@@ -883,7 +906,7 @@ const doc = await this.mainDbModel.findById(id).exec();
 return this.processResult(doc, serviceOptions);
 ```
 
-`processResult()` handles population and `prepareOutput()` only. Security is handled by the Safety Net (Mongoose plugins for input, interceptors for output).
+`processResult()` handles population and `prepareOutput()` only. It does **not** perform authorization checks (`checkRights`). Security is handled by the Safety Net (Mongoose plugins for input, interceptors for output). If called outside an HTTP request cycle (cron, queue), call `checkRights` manually before returning data to external consumers.
 
 ---