@lenne.tech/nest-server 11.21.2 → 11.22.0

package/migration-guides/11.21.2-to-11.21.3.md

@@ -0,0 +1,175 @@
+# Migration Guide: 11.21.2 → 11.21.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | System role early-returns in CoreTenantGuard, S_NO_ONE defense-in-depth, account collection indices, TestHelper download cookie auth |
+| **Bugfixes** | CoreTenantGuard: class-level roles no longer shadow method-level system roles; admin bypass log level changed to `debug` |
+| **Migration Effort** | < 5 minutes |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.21.3
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+No code changes required. The bugfix and new features are fully backward compatible.
+
+---
+
+## What's New in 11.21.3
+
+### 1. CoreTenantGuard: System Role Early-Returns (Bugfix)
+
+**Affects:** Projects with `multiTenancy` enabled that use class-level `@Roles()` combined with method-level system roles.
+
+**Problem:** When a controller class had `@Roles(ADMIN)` and a method had `@Roles(S_USER)`, the guard merged both into `[S_USER, ADMIN]`, then filtered out system roles — leaving `checkableRoles = [ADMIN]`. This blocked non-admin users even though the method explicitly allowed any authenticated user.
+
+**Fix:** `CoreTenantGuard` now checks system roles (S_EVERYONE → S_USER → S_VERIFIED) **before** filtering to real roles. If a system role grants access, the guard returns immediately without requiring real role checks.
+
+```typescript
+// This pattern now works correctly:
+@Roles(RoleEnum.ADMIN)    // Class: admin can always access
+@Controller('users')
+class UserController {
+
+  @Get('profile')
+  @Roles(RoleEnum.S_USER)  // Method: any authenticated user can access
+  getProfile() { ... }     // Previously: blocked non-admin users ❌
+                            // Now: any authenticated user passes ✅
+}
+```
+
+**Role resolution semantics:**
+
+| Role Type | Resolution | Example |
+|-----------|-----------|---------|
+| System roles (S_EVERYONE, S_USER, S_VERIFIED) | Method takes precedence | Class `S_EVERYONE` + Method `S_USER` → `S_USER` applies |
+| Real roles (ADMIN, hierarchy, custom) | OR/merged (class extends method) | Class `ADMIN` + Method `'editor'` → ADMIN or editor |
+
+**Tenant header behavior with system roles:**
+
+| System Role | No Header | Header Present |
+|-------------|-----------|----------------|
+| S_EVERYONE | Pass (public) | Pass + optional tenant context enrichment |
+| S_USER | Pass if authenticated | Pass if member (403 if not a member); admin bypass applies |
+| S_VERIFIED | Pass if verified | Pass if verified member (403 if not a member); admin bypass applies |
+
+Admin users with `adminBypass: true` (default) always pass tenant membership checks, even when a system role early-return handles the request.
+
+### 2. Admin Bypass Log Level Changed to `debug`
+
+Admin bypass log messages (`Admin bypass: user X accessing tenant Y`) have been downgraded from `log` to `debug` level. This reduces log noise in production. To see admin bypass activity, enable debug-level logging for the `CoreTenantGuard` context.
+
+### 3. S_NO_ONE Defense-in-Depth
+
+`CoreTenantGuard` now explicitly checks for `S_NO_ONE` and throws `ForbiddenException` — previously it relied solely on `RolesGuard`/`BetterAuthRolesGuard` catching `S_NO_ONE` upstream. This adds defense-in-depth for custom guard chain configurations.
+
+### 4. TestHelper: Cookie Auth for Download Methods
+
+**Affects:** Projects using `TestHelper.download()` or `TestHelper.downloadBuffer()` in tests.
+
+The download methods now support cookie-based authentication via a new `TestDownloadOptions` interface:
+
+```typescript
+// String form (backward compatible)
+await testHelper.download('/files/id/abc', jwtToken);
+
+// Options object with JWT token
+await testHelper.download('/files/id/abc', { token: jwtToken });
+
+// Options object with cookie-based session auth
+await testHelper.download('/files/id/abc', { cookies: sessionToken });
+
+// Both simultaneously (like rest())
+await testHelper.download('/files/id/abc', {
+  cookies: sessionToken,
+  token: jwtToken,
+});
+```
+
+The same options apply to `downloadBuffer()`.
+
+### 5. Performance: Account Collection Indices
+
+New MongoDB indices are automatically created on application startup (via `onModuleInit`) for the `account` collection:
+
+- `{ userId: 1 }` — accelerates `$lookup` joins in `getMigrationStatus()` and session lookups
+- `{ providerId: 1, userId: 1 }` — accelerates credential account filtering
+
+**No manual action required** — indices are created idempotently (no-op if they already exist). The indices significantly improve `betterAuthMigrationStatus` query performance (up to 97% faster in test environments).
+
+### 6. Documentation: System Role OR Semantics
+
+`docs/REQUEST-LIFECYCLE.md` has been updated with:
+- Clarified OR semantics for system roles in `CoreTenantGuard`
+- Corrected `S_VERIFIED` check logic (now includes `verifiedAt`)
+- Added notes that `S_CREATOR` and `S_SELF` are object-level checks (handled by interceptors, not guards)
+
+---
+
+## Compatibility Notes
+
+### Existing Patterns — No Changes Needed
+
+| Pattern | Status |
+|---------|--------|
+| Class `@Roles(ADMIN)` + Method `@Roles(S_EVERYONE)` | ✅ Works as before |
+| Class `@Roles(ADMIN)` + Method `@Roles(S_USER)` | ✅ Works as before (and now also correct in CoreTenantGuard) |
+| Class `@Roles(ADMIN)` + Method `@Roles(ADMIN)` | ✅ Works as before |
+| Class `@Roles(ADMIN)` + no method `@Roles()` | ✅ Class fallback applies |
+| `download(url, token)` string form | ✅ Backward compatible |
+| `@SkipTenantCheck()` decorator | ✅ Works as before |
+| BetterAuth auto-skip (`skipTenantCheck`) | ✅ Works as before |
+
+### Edge Case: Class S_EVERYONE + Method S_USER
+
+Previously, class `@Roles(S_EVERYONE)` combined with method `@Roles(S_USER)` resulted in public access (S_EVERYONE overrode S_USER). Now, the method-level `S_USER` takes precedence — the endpoint requires authentication.
+
+This edge case is unlikely in practice (class-level S_EVERYONE with method-level S_USER contradicts intent), but if you intentionally relied on this behavior, add `S_EVERYONE` to the method:
+
+```typescript
+// Before: S_EVERYONE on class made this endpoint public
+@Roles(RoleEnum.S_USER)
+getProfile() { ... }
+
+// After: If you want it public, be explicit on the method
+@Roles(RoleEnum.S_EVERYONE)
+getProfile() { ... }
+```
+
+---
+
+## Module Documentation
+
+### Tenant Module
+
+- **README:** [src/core/modules/tenant/README.md](../src/core/modules/tenant/README.md) — New "System Roles as OR Alternatives" section, updated Tenant Context Rule and @SkipTenantCheck documentation
+- **Integration Checklist:** [src/core/modules/tenant/INTEGRATION-CHECKLIST.md](../src/core/modules/tenant/INTEGRATION-CHECKLIST.md)
+- **Key Files:**
+  - `core-tenant.guard.ts` — System role early-returns, hybrid role resolution, S_NO_ONE defense-in-depth, admin bypass audit log (debug level)
+  - `core-tenant.helpers.ts` — Updated JSDoc for `mergeRolesMetadata`, `isSystemRole`
+
+### TestHelper
+
+- **README:** [src/test/README.md](../src/test/README.md) — New download/downloadBuffer section with cookie auth examples
+- **Key Files:**
+  - `test.helper.ts` — `TestDownloadOptions` interface, cookie auth for downloads
+
+---
+
+## References
+
+- [Request Lifecycle Documentation](../docs/REQUEST-LIFECYCLE.md) — Updated system role semantics
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/migration-guides/11.21.x-to-11.22.0.md

@@ -0,0 +1,224 @@
+# Migration Guide: 11.21.x → 11.22.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `ICoreModuleOverrides` — dedicated parameter for customizing core module components; npm package now includes `CLAUDE.md`, `.claude/rules/`, `docs/`, and `migration-guides/` for AI-assisted development |
+| **Bugfixes** | Prevents duplicate controller registration when extending ErrorCodeModule |
+| **Migration Effort** | ~5 minutes (optional, backward compatible) |
+
+---
+
+## Quick Migration (No Breaking Changes)
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.22.0
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+No code changes required. All existing patterns continue to work.
+
+---
+
+## What's New in 11.22.0
+
+### 1. Module Override Parameter (`ICoreModuleOverrides`)
+
+`CoreModule.forRoot()` now accepts an optional second parameter for replacing default controllers,
+resolvers, or services of auto-registered core modules.
+
+This solves the duplicate controller registration problem that occurred when projects called
+`ErrorCodeModule.forRoot()` or `CoreBetterAuthModule.forRoot()` separately alongside CoreModule's
+auto-registration.
+
+**Before (caused duplicate routes):**
+
+```typescript
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),
+    // ❌ This caused duplicate controller registration because CoreModule
+    //    already called ErrorCodeModule.forRoot() internally
+    ErrorCodeModule.forRoot({
+      controller: ErrorCodeController,
+      service: ErrorCodeService,
+    }),
+  ],
+})
+export class ServerModule {}
+```
+
+**After (single registration, clean):**
+
+```typescript
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig, {
+      errorCode: {
+        controller: ErrorCodeController,
+        service: ErrorCodeService,
+      },
+    }),
+  ],
+})
+export class ServerModule {}
+```
+
+### Available Override Fields
+
+| Module | Fields | Description |
+|--------|--------|-------------|
+| `errorCode` | `controller`, `service` | Custom error code endpoint and/or service |
+| `betterAuth` | `controller`, `resolver` | Custom IAM REST controller and/or GraphQL resolver |
+
+### Legacy Mode (3-parameter signature)
+
+```typescript
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+  errorCode: {
+    controller: ErrorCodeController,
+    service: ErrorCodeService,
+  },
+  betterAuth: {
+    resolver: BetterAuthResolver,
+  },
+})
+```
+
+### 2. Framework Documentation in npm Package
+
+The npm package now includes `CLAUDE.md`, `.claude/rules/`, `docs/`, and `migration-guides/`.
+This enables AI-assisted development tools (like Claude Code) to read the framework's
+architecture documentation, configuration interfaces, and integration checklists directly
+from `node_modules/@lenne.tech/nest-server/`.
+
+**For AI-assisted development:** Add this to your project's `CLAUDE.md`:
+
+```markdown
+## Framework: @lenne.tech/nest-server
+When working with framework features, read source and docs from:
+node_modules/@lenne.tech/nest-server/CLAUDE.md
+node_modules/@lenne.tech/nest-server/src/core/common/interfaces/server-options.interface.ts
+node_modules/@lenne.tech/nest-server/src/core/modules/*/INTEGRATION-CHECKLIST.md
+```
+
+---
+
+## Recommended Migration
+
+While not required, migrating to the overrides pattern is recommended to prevent potential
+duplicate controller registration issues.
+
+### Step 1: Move ErrorCodeModule customization to overrides
+
+If your project has a separate `ErrorCodeModule.forRoot()` call:
+
+**Before:**
+```typescript
+imports: [
+  CoreModule.forRoot(envConfig),
+  ErrorCodeModule.forRoot({
+    controller: ErrorCodeController,
+    service: ErrorCodeService,
+  }),
+]
+```
+
+**After:**
+```typescript
+imports: [
+  CoreModule.forRoot(envConfig, {
+    errorCode: {
+      controller: ErrorCodeController,
+      service: ErrorCodeService,
+    },
+  }),
+  // Remove the separate ErrorCodeModule.forRoot() call
+]
+```
+
+### Step 2: Move BetterAuth customization to overrides (optional)
+
+If your project uses `betterAuth.controller` or `betterAuth.resolver` in config:
+
+**Before:**
+```typescript
+// config.env.ts
+betterAuth: {
+  controller: BetterAuthController,
+  resolver: BetterAuthResolver,
+}
+```
+
+**After:**
+```typescript
+// config.env.ts — remove controller/resolver from betterAuth config
+betterAuth: { /* ... other config ... */ }
+
+// server.module.ts
+CoreModule.forRoot(envConfig, {
+  betterAuth: {
+    controller: BetterAuthController,
+    resolver: BetterAuthResolver,
+  },
+})
+```
+
+Both approaches work — the overrides parameter takes precedence. The config fields remain
+for backward compatibility.
+
+### Step 3: Acknowledge deprecation warnings (no action required)
+
+The `betterAuth.controller` and `betterAuth.resolver` fields in the config interface are now
+marked as `@deprecated`. TypeScript will show strikethrough/warnings when these fields are used.
+
+**No action required** — the fields still work. But when you have time, move them to the
+`overrides` parameter (Step 2 above) to silence the warnings. This keeps class references
+(code) separate from environment configuration (strings/numbers).
+
+---
+
+## Deprecations
+
+| Field | Deprecated Since | Replacement | Removal |
+|-------|-----------------|-------------|---------|
+| `betterAuth.controller` | 11.22.0 | `CoreModule.forRoot(config, { betterAuth: { controller } })` | Not planned (backward compatible) |
+| `betterAuth.resolver` | 11.22.0 | `CoreModule.forRoot(config, { betterAuth: { resolver } })` | Not planned (backward compatible) |
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| `CoreModule.forRoot(envConfig)` without overrides | ✅ Works unchanged |
+| `betterAuth.controller`/`resolver` in config | ✅ Works, overrides take precedence |
+| `errorCode.autoRegister: false` + separate import | ✅ Works unchanged |
+| `betterAuth.autoRegister: false` + separate import | ✅ Works unchanged |
+| Separate `ErrorCodeModule.forRoot()` alongside CoreModule | ⚠️ Still works but causes duplicate controllers — use overrides instead. If your project already had this pattern, the duplicate registration still occurs but is harmless at runtime (NestJS deduplicates providers). The recommended migration is to use the overrides parameter. |
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Duplicate route handlers after update | Move `ErrorCodeModule.forRoot()` to `CoreModule.forRoot()` overrides parameter |
+| TypeScript error on overrides parameter | Ensure `@lenne.tech/nest-server@11.22.0` is installed |
+| Custom ErrorCode controller not registered | Check that `errorCode.autoRegister` is not set to `false` when using overrides |
+
+---
+
+## Module Documentation
+
+- [ErrorCode INTEGRATION-CHECKLIST](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md)
+- [BetterAuth CUSTOMIZATION](../src/core/modules/better-auth/CUSTOMIZATION.md)
+- [Configurable Features](../.claude/rules/configurable-features.md)

package/migration-guides/11.3.x-to-11.4.x.md

@@ -0,0 +1,233 @@
+# Migration Guide: 11.3.x → 11.4.x
+
+## TL;DR
+
+**Not using `@nodepit/migrate-state-store-mongodb`?**
+```bash
+npm install @lenne.tech/nest-server@11.4.x
+npm run build && npm test  # Done! No breaking changes.
+```
+
+**Using `@nodepit/migrate-state-store-mongodb`?** Follow the migration steps below to switch to the built-in system.
+
+---
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None (backward compatible) |
+| **New Features** | Built-in migration CLI, MongoStateStore, helper functions |
+| **Bugfixes** | Various MapAndValidatePipe improvements (11.4.2-11.4.5) |
+| **Migration Effort** | ~5 min (no @nodepit) / ~15 min (with @nodepit migration) |
+
+---
+
+## Prerequisites
+
+### ts-node (Required for TypeScript migrations)
+
+```bash
+npm install --save-dev ts-node
+```
+
+---
+
+## What's New in 11.4.x
+
+### 1. Built-in Migration CLI
+
+No external `migrate` package required - CLI included in nest-server:
+
+```bash
+npx migrate --help
+```
+
+### 2. Migration Helper Functions
+
+```typescript
+import { getDb, uploadFileToGridFS, createMigrationStore } from '@lenne.tech/nest-server';
+
+const db = await getDb('mongodb://localhost/mydb');
+const fileId = await uploadFileToGridFS('mongodb://localhost/mydb', './assets/logo.png');
+```
+
+### 3. MongoStateStore
+
+Drop-in replacement for `@nodepit/migrate-state-store-mongodb` with MongoDB 7.x support and cluster locking.
+
+### 4. S_VERIFIED System Role (11.4.8)
+
+New system role for checking user verification status:
+
+```typescript
+@Roles(RoleEnum.S_VERIFIED)  // Requires verified user
+async someMethod() { }
+```
+
+Checks: `user.verified || user.verifiedAt || user.emailVerified`
+
+---
+
+## Migration from @nodepit
+
+### Step 1: Remove Old Packages
+
+```bash
+npm uninstall migrate @nodepit/migrate-state-store-mongodb ts-migrate-mongoose
+```
+
+### Step 2: Update nest-server
+
+```bash
+npm install @lenne.tech/nest-server@11.4.x
+```
+
+### Step 3: Update `migrations-utils/migrate.js`
+
+**Before:**
+```javascript
+import config from '../src/config.env';
+const { MongoStateStore } = require('@nodepit/migrate-state-store-mongodb');
+
+module.exports = class MyMongoStateStore extends MongoStateStore {
+  constructor() {
+    super({ uri: config.mongoose.uri, collectionName: 'migrations' });
+  }
+};
+```
+
+**After:**
+```javascript
+const { createMigrationStore } = require('@lenne.tech/nest-server');
+const config = require('../src/config.env');
+
+module.exports = createMigrationStore(
+  config.default.mongoose.uri,
+  'migrations'
+);
+```
+
+### Step 4: Update `migrations-utils/db.ts`
+
+**Before:**
+```typescript
+import { GridFSBucket, MongoClient, ObjectId } from 'mongodb';
+import config from '../src/config.env';
+
+const MONGO_URL = config.mongoose.uri;
+
+export const getDb = async () => {
+  const client: MongoClient = await MongoClient.connect(MONGO_URL);
+  return client.db();
+};
+
+export const uploadFile = async (relativePath, options?) => {
+  // ... custom implementation
+};
+```
+
+**After:**
+```typescript
+/**
+ * Legacy compatibility layer - allows existing migrations to work unchanged
+ */
+import {
+  createMigrationStore,
+  getDb as nestServerGetDb,
+  uploadFileToGridFS,
+} from '@lenne.tech/nest-server';
+import config from '../src/config.env';
+
+export { createMigrationStore, uploadFileToGridFS };
+
+// Wrapper: existing migrations call getDb() without parameters
+export const getDb = async () => nestServerGetDb(config.mongoose.uri);
+```
+
+### Step 5: Delete Obsolete Files
+
+```bash
+rm migrations-utils/template.ts migrations-utils/ts-compiler.js
+```
+
+### Step 6: Update package.json Scripts
+
+**Key changes:**
+- Command (`up`, `down`, `create`) comes **first**, then options
+- Use nest-server paths for template and compiler
+
+```json
+{
+  "scripts": {
+    "migrate:create": "f() { migrate create \"$1\" --template-file ./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/templates/migration-project.template.ts --migrations-dir ./migrations --compiler ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js; }; f",
+    "migrate:up": "migrate up --store ./migrations-utils/migrate.js --migrations-dir ./migrations --compiler ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js",
+    "migrate:down": "migrate down --store ./migrations-utils/migrate.js --migrations-dir ./migrations --compiler ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js",
+    "migrate:list": "migrate list --store ./migrations-utils/migrate.js --migrations-dir ./migrations --compiler ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+  }
+}
+```
+
+**Environment-specific scripts (optional):**
+```json
+{
+  "migrate:develop:up": "NODE_ENV=develop migrate up --store ./migrations-utils/migrate.js --migrations-dir ./migrations --compiler ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js",
+  "migrate:prod:up": "NODE_ENV=production migrate up --store ./migrations-utils/migrate.js --migrations-dir ./migrations --compiler ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+}
+```
+
+### Step 7: Verify
+
+```bash
+npm install
+npm run migrate:list        # Should show existing migrations
+npm run migrate:create test # Should create new migration
+rm migrations/*-test.ts     # Clean up
+npm run build && npm test
+```
+
+---
+
+## Compatibility Notes
+
+| What | Status |
+|------|--------|
+| Existing migration files | ✅ Unchanged |
+| Migration state in MongoDB | ✅ Same format, no data loss |
+| Projects without @nodepit | ✅ No action needed |
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `migrate` command not found | Use `npx migrate` or ensure nest-server is installed |
+| `ts-node is required` | `npm install --save-dev ts-node` |
+| `Cannot find module '../src/config.env'` | Use `require('../src/config.env')` and access `config.default.mongoose.uri` |
+| Migrations run on multiple nodes | Add lock collection: `createMigrationStore(uri, 'migrations', 'migration_lock')` |
+
+---
+
+## File Structure After Migration
+
+```
+migrations-utils/
+├── migrate.js    # Required (7 lines) - uses createMigrationStore
+└── db.ts         # Optional (5 lines) - compatibility wrapper for old migrations
+```
+
+**Deleted:** `template.ts`, `ts-compiler.js` (now provided by nest-server)
+
+---
+
+## Module Documentation
+
+- **README:** [src/core/modules/migrate/README.md](../src/core/modules/migrate/README.md)
+- **@nodepit Migration:** [src/core/modules/migrate/MIGRATION_FROM_NODEPIT.md](../src/core/modules/migrate/MIGRATION_FROM_NODEPIT.md)
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)