@lenne.tech/nest-server 11.21.3 → 11.22.1

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.22.0-to-11.22.1.md

@@ -0,0 +1,105 @@
+# Migration Guide: 11.22.0 → 11.22.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `FRAMEWORK-API.md` — auto-generated compact API reference shipped with npm package |
+| **Bugfixes** | Security override updates (minimatch, undici, srvx, path-to-regexp) |
+| **Dependency Updates** | NestJS 11.1.18, mongoose 9.4.1 |
+| **Migration Effort** | ~2 minutes (optional, backward compatible) |
+
+---
+
+## Quick Migration (No Breaking Changes)
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.22.1
+
+# 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.1
+
+### 1. FRAMEWORK-API.md — Auto-Generated API Reference
+
+The npm package now ships a compact, machine-readable API reference (`FRAMEWORK-API.md`) that is
+auto-generated from source code during `pnpm run build`. It contains:
+
+- `CoreModule.forRoot()` overload signatures
+- All configuration interfaces (`IServerOptions`, `IBetterAuth`, `IMultiTenancy`, etc.) with types and defaults
+- `ServiceOptions` interface
+- `CrudService` public method signatures
+- Core module listing with documentation status
+
+**For AI-assisted development:** Update your project's `CLAUDE.md` to reference this file:
+
+```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/FRAMEWORK-API.md
+node_modules/@lenne.tech/nest-server/src/core/modules/*/INTEGRATION-CHECKLIST.md
+```
+
+This enables AI tools to quickly understand the framework's complete API surface without
+reading every source file individually.
+
+### 2. Dependency Updates
+
+| Package | From | To | Type |
+|---------|------|----|------|
+| `@nestjs/common` | 11.1.17 | 11.1.18 | patch |
+| `@nestjs/core` | 11.1.17 | 11.1.18 | patch |
+| `@nestjs/platform-express` | 11.1.17 | 11.1.18 | patch |
+| `@nestjs/websockets` | 11.1.17 | 11.1.18 | patch |
+| `@nestjs/testing` (dev) | 11.1.17 | 11.1.18 | patch |
+| `mongoose` | 9.3.3 | 9.4.1 | minor |
+
+### 3. Security Override Updates
+
+Updated security overrides to latest patched versions:
+
+| Override | From | To |
+|----------|------|----|
+| `minimatch` | 3.1.4 / 9.0.7 / 10.2.4 | 3.1.5 / 9.0.9 / 10.2.5 |
+| `undici` | 7.24.3 | 7.24.7 |
+| `srvx` | 0.11.13 | 0.11.15 |
+| `path-to-regexp` | 8.4.1 | 8.4.2 |
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| All existing `CoreModule.forRoot()` patterns | Works unchanged |
+| `ICoreModuleOverrides` from 11.22.0 | Works unchanged |
+| mongoose queries and schemas | Compatible (9.4.1 is backward compatible) |
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `FRAMEWORK-API.md` not found in `node_modules` | Ensure `@lenne.tech/nest-server@11.22.1` is installed |
+| Override conflicts after update | Run `pnpm install` to apply updated lockfile |
+
+---
+
+## References
+
+- [FRAMEWORK-API.md](../FRAMEWORK-API.md) — The new API reference
+- [Framework Compatibility Rules](../.claude/rules/framework-compatibility.md) — Maintenance obligations
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)