@lenne.tech/nest-server 11.21.3 → 11.22.1

package/migration-guides/11.16.x-to-11.17.0.md

@@ -0,0 +1,130 @@
+# Migration Guide: 11.16.x → 11.17.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Permissions Report Module, Configurable endpoint path |
+| **Bugfixes** | None |
+| **Migration Effort** | < 5 minutes (optional feature) |
+
+---
+
+## Quick Migration (No Breaking Changes)
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.17.0
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+---
+
+## What's New in 11.17.0
+
+### 1. Permissions Report Module
+
+A development tool that scans your project for `@Roles`, `@Restricted`, and `securityCheck()` usage, generating an interactive HTML dashboard at runtime.
+
+**Setup (optional):**
+
+```typescript
+// config.env.ts - local/development only
+permissions: true,
+```
+
+This adds the following endpoints to your server:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/permissions` | Interactive HTML dashboard |
+| `GET` | `/permissions/json` | JSON report with stats |
+| `GET` | `/permissions/markdown` | Markdown report |
+| `POST` | `/permissions/rescan` | Force rescan |
+
+**Features:**
+- Lazy scanning (only on first request)
+- File watcher auto-invalidates cache on `.ts` file changes
+- Coverage metrics (endpoint coverage, security coverage)
+- Warning detection (missing `@Roles`, `@Restricted`, `securityCheck()`)
+- Role-based access control (admin-only by default)
+
+**Advanced configuration:**
+
+```typescript
+// Custom role
+permissions: { role: 'S_EVERYONE' },
+
+// No authentication
+permissions: { role: false },
+
+// Custom endpoint path
+permissions: { path: 'admin/permissions' },
+
+// Explicitly disabled
+permissions: { enabled: false },
+```
+
+### 2. Standalone Permissions Scanner
+
+The scanning logic has been extracted into `permissions-scanner.ts` as a standalone module with no NestJS dependencies. This enables:
+
+- The `lt server permissions` CLI command to use the same scanner via dynamic import
+- External tools to import `scanPermissions()` directly from `@lenne.tech/nest-server`
+
+```typescript
+import { scanPermissions, findProjectRoot } from '@lenne.tech/nest-server';
+
+const projectRoot = findProjectRoot();
+const report = scanPermissions(projectRoot, {
+  log: (msg) => console.log(msg),
+  warn: (msg) => console.warn(msg),
+});
+```
+
+---
+
+## Detailed Migration Steps
+
+### Step 1: Update Package
+
+```bash
+npm install @lenne.tech/nest-server@11.17.0
+```
+
+### Step 2: Adopt New Features (Optional)
+
+Add `permissions: true` to your `config.env.ts` in local/development environments. See the [Permissions README](../src/core/modules/permissions/README.md) for details.
+
+---
+
+## Compatibility Notes
+
+- The permissions module is entirely opt-in. Existing projects are unaffected.
+- The `lt server permissions` CLI command now requires `@lenne.tech/nest-server >= 11.17.0` in the target project.
+
+---
+
+## Module Documentation
+
+### Permissions Report
+
+- **README:** [src/core/modules/permissions/README.md](../src/core/modules/permissions/README.md)
+- **Integration Checklist:** [src/core/modules/permissions/INTEGRATION-CHECKLIST.md](../src/core/modules/permissions/INTEGRATION-CHECKLIST.md)
+- **Key Files:**
+  - `permissions-scanner.ts` - Standalone AST scanning (shared with CLI)
+  - `core-permissions.service.ts` - Caching, file watching, HTML generation
+  - `core-permissions.controller.ts` - REST endpoints
+  - `core-permissions.module.ts` - DynamicModule with forRoot()
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/migration-guides/11.17.x-to-11.18.0.md

@@ -0,0 +1,393 @@
+# Migration Guide: 11.17.x → 11.18.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None (NestJS patch update `11.1.13` → `11.1.16` requires matching versions) |
+| **New Features** | Safety Net Architecture: automatic security without CrudService.process() |
+| **Dependency Updates** | NestJS 11.1.16, apollo-server-core removed (−151 packages), 21 packages updated |
+| **Migration Effort** | ~5 minutes (update NestJS packages + verify) |
+
+---
+
+## Quick Migration
+
+All Safety Net features are **enabled by default** and fully backward compatible. No code changes required.
+
+However, 11.18.0 updates NestJS core packages to `11.1.16`. Projects **must** update their NestJS packages to match, otherwise pnpm will install duplicate copies with incompatible TypeScript types (e.g. `Types have separate declarations of a private property 'logger'`).
+
+```bash
+# 1. Update nest-server
+pnpm add @lenne.tech/nest-server@11.18.0
+
+# 2. Update NestJS packages to match (required!)
+pnpm add @nestjs/common@11.1.16 @nestjs/core@11.1.16 @nestjs/platform-express@11.1.16
+pnpm add -D @nestjs/testing@11.1.16
+
+# 3. Verify build
+pnpm run build
+
+# 4. Run tests
+pnpm test
+```
+
+> **Why?** `@lenne.tech/nest-server` declares NestJS packages in `dependencies` with exact versions. If your project uses a different patch version, pnpm creates duplicate installations which TypeScript treats as incompatible types.
+
+---
+
+## What's New in 11.18.0
+
+### Safety Net Architecture
+
+Previously, security guarantees (password hashing, role protection, secret removal, field filtering) only worked when using `CrudService.process()`. Developers bypassing `process()` with direct Mongoose calls (`this.mainDbModel.findOne()`, `.aggregate()`, etc.) could accidentally expose sensitive data or store plaintext passwords.
+
+**11.18.0 introduces automatic security at the framework level**, ensuring protection works regardless of how data is accessed or written.
+
+### 1. Mongoose Password Hashing Plugin
+
+Automatically hashes passwords on all write operations (`save`, `findOneAndUpdate`, `updateOne`, `updateMany`).
+
+- Detects already-hashed values (BCrypt pattern) to prevent double-hashing
+- Supports SHA256 pre-hashing (matching the existing `prepareInput` behavior)
+- Configurable skip patterns for sentinel values (e.g. `!LOCKED:REQUIRES_PASSWORD_RESET`)
+
+```typescript
+// config.env.ts - enabled by default, examples for customization:
+
+// Default: enabled
+security: {
+  mongoosePasswordPlugin: true,
+}
+
+// With skip patterns for sentinel values
+security: {
+  mongoosePasswordPlugin: {
+    skipPatterns: ['^!LOCKED:'],
+  },
+}
+
+// Disable entirely
+security: {
+  mongoosePasswordPlugin: false,
+}
+```
+
+### 2. Mongoose Role Guard Plugin
+
+Prevents unauthorized users from escalating roles via direct database operations. Only users with ADMIN role (or configured allowed roles) can assign roles to other users.
+
+- Uses `RequestContext` (AsyncLocalStorage) to access the current user
+- System operations without request context (e.g. migrations, seeds) are allowed through
+- No-user requests (e.g. `signUp`) are allowed through (`currentUser` is `undefined`)
+- Configurable for custom role hierarchies
+- Programmatic bypass via `RequestContext.runWithBypassRoleGuard()` for authorized service code
+
+```typescript
+// config.env.ts - enabled by default, examples for customization:
+
+// Default: only ADMIN can assign roles
+security: {
+  mongooseRoleGuardPlugin: true,
+}
+
+// Allow additional roles to assign roles
+security: {
+  mongooseRoleGuardPlugin: {
+    allowedRoles: ['ORGA', 'COMPANY_ADMIN'],
+  },
+}
+
+// Programmatic bypass for authorized service operations (e.g. HR_MANAGER creating users with roles):
+import { RequestContext } from '@lenne.tech/nest-server';
+
+await RequestContext.runWithBypassRoleGuard(async () => {
+  await this.mainDbModel.findByIdAndUpdate(userId, { roles: ['EMPLOYEE'] });
+});
+
+// Also works with CrudService.process() via force: true (automatically bypasses the plugin)
+```
+
+### 3. Mongoose Audit Fields Plugin
+
+Automatically sets `createdBy` and `updatedBy` fields on save/update operations using the current user from `RequestContext`.
+
+```typescript
+// config.env.ts - enabled by default
+
+// Disable if not needed
+security: {
+  mongooseAuditFieldsPlugin: false,
+}
+```
+
+### 4. ResponseModelInterceptor
+
+Auto-converts plain objects and Mongoose documents into model instances with `securityCheck()` and correct constructor metadata. This ensures `@Restricted` field filtering and `securityCheck()` work even when `CrudService.process()` is bypassed.
+
+**Model class resolution order:**
+1. Explicit `@ResponseModel(ModelClass)` decorator (for REST)
+2. GraphQL `TypeMetadataStorage` lookup (automatic for `@Query`/`@Mutation` return types)
+3. Swagger `@ApiOkResponse` / `@ApiCreatedResponse` type (automatic for REST)
+4. No conversion (existing interceptors work as before)
+
+Results are cached per route handler for zero-cost subsequent lookups.
+
+```typescript
+// config.env.ts - enabled by default
+
+// Enable with debug warnings (logs when auto-conversion happens)
+security: {
+  responseModelInterceptor: { debug: true },
+}
+
+// Disable entirely
+security: {
+  responseModelInterceptor: false,
+}
+```
+
+**For REST controllers**, you can use the `@ResponseModel()` decorator to explicitly specify the model class:
+
+```typescript
+import { ResponseModel } from '@lenne.tech/nest-server';
+
+@ResponseModel(User)
+@Get(':id')
+async getUser(@Param('id') id: string): Promise<User> {
+  // Even if this returns a plain object, the interceptor will convert it
+  return this.mainDbModel.findById(id).exec();
+}
+```
+
+### 5. TranslateResponseInterceptor
+
+Automatically applies `_translations` to response objects based on the `Accept-Language` header. Ensures translations work even when `CrudService.process()` is bypassed.
+
+- Includes early bailout: skips recursive traversal when no `_translations` are present
+- Zero overhead for non-translated responses
+
+```typescript
+// config.env.ts - enabled by default
+
+// Disable entirely
+security: {
+  translateResponseInterceptor: false,
+}
+```
+
+### 6. Fallback Secret Removal
+
+`CheckSecurityInterceptor` now includes a configurable fallback that removes known secret fields from all responses, regardless of whether the response is a model instance.
+
+```typescript
+// config.env.ts - enabled by default
+
+// Default secret fields
+security: {
+  secretFields: ['password', 'verificationToken', 'passwordResetToken', 'refreshTokens', 'tempTokens'],
+}
+
+// Custom secret fields
+security: {
+  secretFields: ['password', 'apiKey', 'internalToken'],
+}
+```
+
+### 7. RequestContext Service
+
+New `RequestContext` service using Node.js `AsyncLocalStorage` provides the current user and request language in any context — including Mongoose hooks — without dependency injection.
+
+```typescript
+import { RequestContext } from '@lenne.tech/nest-server';
+
+// In any service, helper, or Mongoose hook:
+const currentUser = RequestContext.getCurrentUser();
+const language = RequestContext.getLanguage();
+```
+
+### 8. ModelRegistry Service
+
+Central registry mapping Mongoose model names to CoreModel classes. Auto-populated when `ModuleService` is constructed. Used internally by `ResponseModelInterceptor`.
+
+```typescript
+import { ModelRegistry } from '@lenne.tech/nest-server';
+
+// Lookup a model class by Mongoose model name
+const UserClass = ModelRegistry.getModelClass('User');
+```
+
+### 9. ModuleService Helper Methods
+
+Two new helper methods for services that use direct Mongoose queries:
+
+```typescript
+// processResult(): Simplified post-processing (population + prepareOutput)
+const doc = await this.mainDbModel.findById(id).exec();
+return this.processResult(doc, serviceOptions);
+
+// applyTranslationInput(): Translation-aware input processing
+const oldDoc = await this.mainDbModel.findById(id).lean();
+input = this.applyTranslationInput(input, oldDoc, serviceOptions.language);
+```
+
+---
+
+## Configuration Reference
+
+All new features follow the "enabled by default, opt-out via `false`" pattern:
+
+| Config Path | Type | Default | Description |
+|-------------|------|---------|-------------|
+| `security.mongoosePasswordPlugin` | `boolean \| { skipPatterns }` | `true` | Auto password hashing |
+| `security.mongooseRoleGuardPlugin` | `boolean \| { allowedRoles }` | `true` | Role escalation prevention |
+| `security.mongooseAuditFieldsPlugin` | `boolean` | `true` | Auto createdBy/updatedBy |
+| `security.responseModelInterceptor` | `boolean \| { debug }` | `true` | Plain→Model auto-conversion |
+| `security.translateResponseInterceptor` | `boolean` | `true` | Auto translation application |
+| `security.secretFields` | `string[]` | `['password', ...]` | Global secret field removal |
+| `security.checkSecurityInterceptor.removeSecretFields` | `boolean` | `true` | Fallback secret removal |
+| `security.checkSecurityInterceptor.secretFields` | `string[]` | `['password', ...]` | Interceptor-specific secret fields |
+
+---
+
+## Compatibility Notes
+
+### Existing CrudService Usage
+
+**No changes required.** All existing code using `CrudService.process()` continues to work exactly as before. The Safety Net is purely additive — it catches cases that previously had no protection.
+
+### Double-Hashing Prevention
+
+The password plugin detects already-hashed values using BCrypt pattern matching (`/^\$2[aby]\$\d+\$/`). If `CrudService.process()` already hashes a password via `prepareInput()`, the plugin will skip it. No double-hashing occurs.
+
+### Double-Mapping Prevention
+
+The `ResponseModelInterceptor` checks `instanceof` and the `_objectAlreadyCheckedForRestrictions` flag. If `CrudService.process()` already mapped and checked an object, the interceptor skips it. No duplicate processing.
+
+### Direct Mongoose Usage (Advanced)
+
+Projects that intentionally use direct Mongoose calls now get automatic security for free. For best results:
+
+- **Output:** Return plain documents — the `ResponseModelInterceptor` handles conversion
+- **Input:** Passwords are hashed automatically, roles are protected automatically
+- **Audit fields:** `createdBy`/`updatedBy` are set automatically when `RequestContext` is available
+- **Translations:** Use `this.applyTranslationInput()` before writes, responses are translated automatically
+
+### Performance
+
+K6 benchmarks (10 VUs, 30s) show negligible overhead:
+
+| Operation | Overhead vs Baseline |
+|-----------|---------------------|
+| signUp (bcrypt) | < 1% |
+| signIn (bcrypt) | < 1% |
+| getUser | ~2% (< 0.1ms absolute) |
+| updateUser | ~7% (< 0.2ms absolute) |
+| REST getUser | ~14% (~5ms absolute) |
+| **Total throughput** | **-1.6%** |
+
+---
+
+## Troubleshooting
+
+### Sentinel password values are being hashed
+
+If your application uses sentinel values for password locking (e.g. `!LOCKED:REQUIRES_PASSWORD_RESET`), configure skip patterns:
+
+```typescript
+security: {
+  mongoosePasswordPlugin: {
+    skipPatterns: ['^!LOCKED:'],
+  },
+}
+```
+
+### Roles are empty after creating users in a service
+
+The Role Guard Plugin blocks role assignments from non-admin users. This affects services where a logged-in non-admin user creates other users with roles (e.g. HR systems, team management).
+
+**Option A: Programmatic bypass** (for specific service operations):
+```typescript
+import { RequestContext } from '@lenne.tech/nest-server';
+
+// Wrap the operation — current user context is preserved
+await RequestContext.runWithBypassRoleGuard(async () => {
+  await this.mainDbModel.create({ email, roles: ['EMPLOYEE'] });
+});
+```
+
+**Option B: CrudService force mode** (bypasses role guard automatically):
+```typescript
+return this.process(
+  async () => this.mainDbModel.findByIdAndUpdate(id, { roles }),
+  { serviceOptions, force: true },
+);
+```
+
+**Option C: Config-based** (permanently allow specific roles to assign roles):
+```typescript
+security: {
+  mongooseRoleGuardPlugin: {
+    allowedRoles: ['ORGA', 'HR_MANAGER'],
+  },
+}
+```
+
+> **Note:** `signUp` without a logged-in user is NOT affected — when no `currentUser` exists, the plugin allows role changes.
+
+### ResponseModelInterceptor not converting REST responses
+
+For REST controllers, the interceptor resolves model types via Swagger metadata or the `@ResponseModel()` decorator. If neither is present, no auto-conversion occurs. Add the decorator explicitly:
+
+```typescript
+@ResponseModel(User)
+@Get(':id')
+async getUser(@Param('id') id: string): Promise<User> { ... }
+```
+
+### Debug: Which responses are being auto-converted?
+
+Enable debug mode to see warnings when the interceptor converts plain objects:
+
+```typescript
+security: {
+  responseModelInterceptor: { debug: true },
+}
+```
+
+---
+
+## New Exports
+
+The following new exports are available from `@lenne.tech/nest-server`:
+
+```typescript
+// Decorators
+export { ResponseModel } from '@lenne.tech/nest-server';
+
+// Interceptors
+export { ResponseModelInterceptor } from '@lenne.tech/nest-server';
+export { TranslateResponseInterceptor } from '@lenne.tech/nest-server';
+
+// Plugins
+export { mongoosePasswordPlugin } from '@lenne.tech/nest-server';
+export { mongooseRoleGuardPlugin } from '@lenne.tech/nest-server';
+export { mongooseAuditFieldsPlugin } from '@lenne.tech/nest-server';
+
+// Services
+export { ModelRegistry } from '@lenne.tech/nest-server';
+export { RequestContext } from '@lenne.tech/nest-server';
+
+// Middleware
+export { RequestContextMiddleware } from '@lenne.tech/nest-server';
+
+// Helpers
+export { resolveResponseModelClass } from '@lenne.tech/nest-server';
+```
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [Configurable Features Pattern](../.claude/rules/configurable-features.md)

package/migration-guides/11.18.x-to-11.19.0.md

@@ -0,0 +1,151 @@
+# Migration Guide: 11.18.x → 11.19.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | REST controller path prefix `api/` removed from ErrorCode and SystemSetup endpoints |
+| **New Features** | None |
+| **Bugfixes** | None |
+| **Migration Effort** | Minimal (~2 minutes) - update proxy config and/or hardcoded fetch URLs |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.19.0
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+---
+
+## Breaking Changes
+
+### 1. REST Endpoint Paths Changed (Removed `api/` Prefix)
+
+The `api/` prefix has been removed from two controller route paths to avoid conflicts with the Nuxt frontend proxy, which uses `/api/...` to forward requests to the backend.
+
+**Affected endpoints:**
+
+| Before | After |
+|--------|-------|
+| `GET /api/i18n/errors/:locale` | `GET /i18n/errors/:locale` |
+| `GET /api/i18n/errors/codes` | `GET /i18n/errors/codes` |
+| `GET /api/system-setup/status` | `GET /system-setup/status` |
+| `POST /api/system-setup/init` | `POST /system-setup/init` |
+
+**Why:** The Nuxt frontend proxy intercepts all `/api/...` requests and forwards them to the backend. When backend controllers also use `/api/...` as a route prefix, the paths conflict and cause issues with CORS and cookies during local development.
+
+All other controllers (`auth`, `iam`, `files`, `tus`, `users`, etc.) already used paths without the `api/` prefix and are unaffected.
+
+---
+
+## Detailed Migration Steps
+
+### Step 1: Update Package
+
+```bash
+npm install @lenne.tech/nest-server@11.19.0
+```
+
+### Step 2: Update Custom Controllers (If Applicable)
+
+If your project has a custom controller extending `CoreErrorCodeController` or `CoreSystemSetupController`, update the `@Controller()` decorator:
+
+**ErrorCode Controller:**
+
+```typescript
+// Before
+@Controller('api/i18n/errors')
+export class ErrorCodeController { ... }
+
+// After
+@Controller('i18n/errors')
+export class ErrorCodeController { ... }
+```
+
+**SystemSetup Controller:**
+
+```typescript
+// Before
+@Controller('api/system-setup')
+export class SystemSetupController extends CoreSystemSetupController { ... }
+
+// After
+@Controller('system-setup')
+export class SystemSetupController extends CoreSystemSetupController { ... }
+```
+
+### Step 3: Update Frontend Fetch Calls
+
+If your frontend makes direct fetch calls to these endpoints (without the Nuxt proxy), update the URLs:
+
+```typescript
+// Before
+const status = await fetch('/api/system-setup/status');
+const errors = await fetch('/api/i18n/errors/de');
+
+// After (direct backend calls)
+const status = await fetch('/system-setup/status');
+const errors = await fetch('/i18n/errors/de');
+
+// If using Nuxt proxy (no change needed - proxy maps /api/* automatically)
+const status = await fetch('/api/system-setup/status'); // proxy strips /api/
+```
+
+### Step 4: Update Reverse Proxy / Nginx Config (If Applicable)
+
+If your deployment uses a reverse proxy with explicit route rules for these endpoints, update accordingly.
+
+---
+
+## Compatibility Notes
+
+- **Nuxt proxy users:** If your Nuxt frontend uses the `/api/...` proxy (default in nuxt-extensions), no frontend changes are needed. The proxy strips the `/api/` prefix before forwarding to the backend.
+- **Direct API consumers:** Any client calling the backend directly (e.g., mobile apps, scripts, Postman collections) must update the endpoint URLs.
+- **Other endpoints unaffected:** `auth`, `iam`, `files`, `tus`, `users`, `avatar`, `health-check`, and `permissions` endpoints remain unchanged.
+
+---
+
+## Troubleshooting
+
+### Endpoints return 404 after update
+
+**Cause:** Still using the old `/api/...` paths.
+
+**Solution:** Remove the `api/` prefix from the endpoint URL:
+- `/api/i18n/errors/de` → `/i18n/errors/de`
+- `/api/system-setup/status` → `/system-setup/status`
+
+### Custom ErrorCode controller not working
+
+**Cause:** Custom controller still uses `@Controller('api/i18n/errors')`.
+
+**Solution:** Update the decorator to `@Controller('i18n/errors')`.
+
+---
+
+## Module Documentation
+
+### ErrorCode Module
+
+- **README:** [src/core/modules/error-code/](../src/core/modules/error-code/)
+- **Integration Checklist:** [INTEGRATION-CHECKLIST.md](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md)
+
+### System Setup Module
+
+- **README:** [src/core/modules/system-setup/README.md](../src/core/modules/system-setup/README.md)
+- **Integration Checklist:** [INTEGRATION-CHECKLIST.md](../src/core/modules/system-setup/INTEGRATION-CHECKLIST.md)
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)