@lenne.tech/nest-server 11.21.2 → 11.22.0

package/migration-guides/11.6.x-to-11.7.x.md

@@ -0,0 +1,394 @@
+# Migration Guide: 11.6.x → 11.7.x
+
+## TL;DR
+
+```bash
+npm install @lenne.tech/nest-server@11.7.x
+npm run build && npm test  # Done! No breaking changes.
+```
+
+**New in 11.7.x:** Simplified `CoreModule.forRoot(envConfig)` for IAM-only projects.
+
+---
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Simplified CoreModule signature, Legacy endpoint control, IAuthProvider interface, Migration status query, Bidirectional password sync |
+| **Bugfixes** | Improved module inheritance pattern for BetterAuth |
+| **Migration Effort** | ~5 minutes (package update only) |
+
+---
+
+## Choose Your Scenario
+
+| Scenario | Use When | CoreModule Signature | Path |
+|----------|----------|---------------------|------|
+| **Legacy Only** | Existing project, no BetterAuth needed | `CoreModule.forRoot(AuthService, AuthModule, envConfig)` | [Path A](#path-a-keep-legacy-auth-no-changes-required) |
+| **Legacy + IAM** | Existing project, migrating to BetterAuth | `CoreModule.forRoot(AuthService, AuthModule, envConfig)` | [Path B](#path-b-add-betterauth-migration-scenario) |
+| **IAM Only** | New project, BetterAuth from start | `CoreModule.forRoot(envConfig)` *(New!)* | [Path C](#path-c-new-project-with-iam-only) |
+
+---
+
+## Quick Migration (No Breaking Changes)
+
+Since there are no breaking changes, the migration is straightforward:
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.7.x
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+**Done!** All existing code continues to work without modifications.
+
+---
+
+## What's New in 11.7.x
+
+### 1. Simplified CoreModule Signature (IAM-Only)
+
+New single-parameter signature for projects that only use BetterAuth:
+
+```typescript
+// server.module.ts - NEW: IAM-only (recommended for new projects)
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),  // Simple! No AuthService/AuthModule needed
+    BetterAuthModule.forRoot({
+      config: envConfig.betterAuth,
+      fallbackSecrets: [envConfig.jwt?.secret],
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+**Benefits:**
+- No need to create AuthService or AuthModule for new projects
+- GraphQL subscriptions authenticate via BetterAuth sessions
+- Cleaner setup for modern projects
+
+**The 3-parameter signature is now `@deprecated` for new projects** but remains fully functional for existing projects during migration.
+
+### 2. Legacy Endpoint Control (`auth.legacyEndpoints`)
+
+New configuration option to disable legacy auth endpoints after BetterAuth migration:
+
+```typescript
+// config.env.ts
+{
+  auth: {
+    legacyEndpoints: {
+      enabled: true,    // Default: true
+      graphql: true,    // Control GraphQL endpoints separately
+      rest: true,       // Control REST endpoints separately
+    }
+  }
+}
+```
+
+When disabled, legacy endpoints return HTTP 410 Gone with `LegacyAuthDisabledException`.
+
+**Affected Endpoints:**
+- GraphQL: `signIn`, `signUp`, `logout`, `refreshToken`
+- REST: `POST /auth/signin`, `POST /auth/signup`, `GET /auth/logout`, `GET /auth/refresh-token`
+
+### 3. Bidirectional Password Synchronization
+
+Passwords are now synchronized between Legacy Auth and BetterAuth:
+
+| Direction | Flow | Password Storage |
+|-----------|------|------------------|
+| Legacy → IAM | User signs up via Legacy | `bcrypt(sha256(pw))` + `scrypt(sha256(pw))` |
+| IAM → Legacy | User signs up via BetterAuth | `scrypt(sha256(pw))` + `bcrypt(sha256(pw))` |
+
+**Requirement:** Inject `BetterAuthUserMapper` in your `UserService`:
+
+```typescript
+// user.service.ts
+constructor(
+  // ... other params ...
+  @Optional() private readonly betterAuthUserMapper?: BetterAuthUserMapper,
+) {
+  super(configService, emailService, mainDbModel, mainModelConstructor, { betterAuthUserMapper });
+}
+```
+
+### 4. IAuthProvider Interface
+
+New abstraction layer for authentication providers (preparation for future version):
+
+```typescript
+interface IAuthProvider {
+  decodeJwt(token: string): JwtPayload;
+  validateUser(payload: JwtPayload): Promise<any>;
+  signToken(user: any, expiresIn?: string): string;
+}
+```
+
+### 5. Migration Status Query
+
+GraphQL query for monitoring BetterAuth migration progress (admin only):
+
+```graphql
+query {
+  betterAuthMigrationStatus {
+    totalUsers
+    fullyMigratedUsers
+    pendingMigrationUsers
+    migrationPercentage
+    canDisableLegacyAuth
+    pendingUserEmails
+  }
+}
+```
+
+### 6. Deprecation Warnings
+
+JSDoc `@deprecated` comments added to legacy auth endpoints and the 3-parameter CoreModule signature.
+
+---
+
+## Detailed Migration Paths
+
+### Path A: Keep Legacy Auth (No Changes Required)
+
+If you're not using BetterAuth:
+
+```bash
+npm install @lenne.tech/nest-server@11.7.x
+npm run build && npm test
+```
+
+Your existing code continues to work unchanged.
+
+### Path B: Add BetterAuth (Migration Scenario)
+
+For existing projects adding BetterAuth alongside Legacy Auth:
+
+1. **Update Package**
+   ```bash
+   npm install @lenne.tech/nest-server@11.7.x
+   ```
+
+2. **Keep Existing CoreModule Signature**
+   ```typescript
+   // server.module.ts - Keep your existing setup
+   CoreModule.forRoot(AuthService, AuthModule.forRoot(envConfig.jwt), envConfig)
+   ```
+
+3. **Add BetterAuth Module**
+   Follow the [BetterAuth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+
+4. **Configure Legacy Endpoints**
+   ```typescript
+   // config.env.ts
+   auth: {
+     legacyEndpoints: { enabled: true }  // Keep during migration
+   }
+   ```
+
+5. **Monitor Migration Progress**
+   ```graphql
+   query { betterAuthMigrationStatus { migrationPercentage, canDisableLegacyAuth } }
+   ```
+
+6. **Disable Legacy When Ready**
+   ```typescript
+   auth: {
+     legacyEndpoints: { enabled: false }  // After all users migrated
+   }
+   ```
+
+### Path C: New Project with IAM Only
+
+For new projects starting fresh with BetterAuth:
+
+1. **Install Package**
+   ```bash
+   npm install @lenne.tech/nest-server@11.7.x
+   ```
+
+2. **Configure ServerModule**
+   ```typescript
+   // server.module.ts
+   @Module({
+     imports: [
+       CoreModule.forRoot(envConfig),  // Simplified! No AuthService/AuthModule needed
+       BetterAuthModule.forRoot({
+         config: envConfig.betterAuth,
+         fallbackSecrets: [envConfig.jwt?.secret],
+       }),
+       // ... other modules
+     ],
+   })
+   export class ServerModule {}
+   ```
+
+3. **Configure config.env.ts**
+   ```typescript
+   // config.env.ts
+   auth: {
+     legacyEndpoints: { enabled: false }  // Disable Legacy endpoints
+   },
+   betterAuth: {
+     jwt: {},       // Enable JWT tokens
+     twoFactor: {}, // Enable 2FA (optional)
+     passkey: {},   // Enable Passkeys (optional)
+   }
+   ```
+
+4. **Follow Integration Checklist**
+   See [BetterAuth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md) for required files.
+
+---
+
+## Compatibility Notes
+
+### Module Inheritance Pattern
+
+Projects extending `CoreAuthResolver` and `CoreAuthController` continue to work seamlessly. Common patterns observed:
+
+**Pattern 1: Override with authService call (common) - MUST call check method**
+```typescript
+@Resolver()
+export class AuthResolver extends CoreAuthResolver {
+  override async signIn(input: SignInInput, ...): Promise<Auth> {
+    this.checkLegacyGraphQLEnabled('signIn');  // Required!
+    return this.authService.signIn(input, ...);
+  }
+}
+```
+⚠️ **Important:** When overriding `signIn`, `signUp`, `logout`, or `refreshToken`, you MUST call the protected `checkLegacyGraphQLEnabled()` method. Otherwise, the `auth.legacyEndpoints.enabled: false` configuration will be ignored and legacy endpoints remain accessible.
+
+**Pattern 2: Simple extension (no overrides)**
+```typescript
+@Resolver()
+export class AuthResolver extends CoreAuthResolver {}
+```
+This pattern benefits from the new deprecation warnings in IDE.
+
+### Custom Role Enums
+
+Projects using custom role enums (e.g., `CompanyRoles`) instead of `RoleEnum` continue to work without changes.
+
+### Additional Auth Methods
+
+Custom methods like `loginAsCompany`, `getCurrentUser`, or `sendVerificationMail` are unaffected.
+
+---
+
+## Client Configuration
+
+New clients should hash passwords with SHA256 before sending:
+
+```typescript
+// auth-client.ts (Nuxt/Vue example)
+import { createAuthClient } from 'better-auth/vue';
+
+const baseClient = createAuthClient({
+  baseURL: import.meta.env.VITE_API_URL,
+  basePath: '/iam',  // Must match server config
+  plugins: [/* ... */],
+});
+
+// Wrap signIn/signUp to hash passwords
+export const authClient = {
+  ...baseClient,
+  signIn: {
+    ...baseClient.signIn,
+    email: async (params) => {
+      const hashedPassword = await sha256(params.password);
+      return baseClient.signIn.email({ ...params, password: hashedPassword });
+    },
+  },
+  // ... same for signUp, resetPassword, etc.
+};
+```
+
+The server accepts both plain and SHA256-hashed passwords but **new clients should always hash**.
+
+---
+
+## Troubleshooting
+
+### Build Errors
+
+If type errors occur related to `auth` configuration:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+npm run build
+```
+
+### Legacy Endpoints Return 410
+
+If legacy endpoints unexpectedly return 410 Gone:
+1. Check `config.auth.legacyEndpoints.enabled` is not `false`
+2. Remove the `auth` configuration block to use defaults
+
+### Tests Fail
+
+1. Ensure MongoDB is running
+2. Run with debug: `npm run test:e2e-doh`
+3. Check configuration matches test environment expectations
+
+### GraphQL Subscriptions in IAM-Only Mode
+
+GraphQL Subscriptions are fully supported in IAM-only mode. If authentication fails, check:
+1. Client sends `Authorization: Bearer <session-token>` in WebSocket connection params
+2. BetterAuth is configured: `betterAuth: { jwt: {} }` (JWT plugin enables token validation)
+3. Session is valid and not expired
+
+---
+
+## Version Comparison
+
+| Version | Feature | Status |
+|---------|---------|--------|
+| 11.6.x | BetterAuth module | Introduced |
+| 11.7.x | Simplified CoreModule signature | New |
+| 11.7.x | IAM-only GraphQL Subscriptions | New |
+| 11.7.x | Legacy endpoint control | New |
+| 11.7.x | Bidirectional password sync | New |
+| 11.7.x | IAuthProvider interface | New |
+| 11.7.x | Migration status query | New |
+| Future | BetterAuth default | Planned |
+
+---
+
+## Module Documentation
+
+For detailed information about affected modules, see:
+
+### Auth Module (Legacy Auth)
+
+- **Location:** `src/core/modules/auth/`
+- **Key Files:**
+  - `core-auth.resolver.ts` - GraphQL endpoints with deprecation warnings
+  - `core-auth.controller.ts` - REST endpoints with deprecation warnings
+  - `interfaces/auth-provider.interface.ts` - New IAuthProvider interface
+
+### BetterAuth Module (IAM)
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/modules/better-auth/`
+
+---
+
+## References
+
+- [Module Deprecation Roadmap](../.claude/rules/module-deprecation.md)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [BetterAuth README](../src/core/modules/better-auth/README.md)

package/migration-guides/11.7.x-to-11.8.x.md

@@ -0,0 +1,318 @@
+# Migration Guide: 11.7.x → 11.8.x
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | 1 (File download endpoint) |
+| **New Features** | 2 (TUS Module, CoreFileController) |
+| **Bugfixes** | None |
+| **Migration Effort** | ~10 minutes |
+
+---
+
+## Prerequisites
+
+### Node.js Version
+
+**Node.js >= 20.19.0 is required** for `@tus/server` support.
+
+```bash
+# Check your version
+node --version
+
+# Should output v20.19.0 or higher
+```
+
+### New Dependencies
+
+The following packages are automatically installed with nest-server 11.8.x:
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `@tus/server` | 2.3.0 | TUS protocol server implementation |
+| `@tus/file-store` | 2.0.0 | File storage backend for TUS uploads |
+
+These are production dependencies and will be installed automatically when updating nest-server.
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.8.x
+
+# Install new TUS dependencies (automatically included)
+npm install
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+**Important:** If your project uses file downloads, see [Breaking Changes](#breaking-changes) below.
+
+---
+
+## What's New in 11.8.x
+
+### 1. TUS Module (Resumable Uploads)
+
+TUS is **enabled by default** - no configuration required! The module provides resumable file uploads using the [tus.io](https://tus.io) protocol.
+
+**Endpoints (automatically available):**
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| OPTIONS | `/tus` | Get server capabilities |
+| POST | `/tus` | Create new upload |
+| HEAD | `/tus/:id` | Get upload status |
+| PATCH | `/tus/:id` | Continue upload |
+| DELETE | `/tus/:id` | Terminate upload |
+
+**Default Configuration:**
+```typescript
+{
+  enabled: true,
+  path: '/tus',
+  maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
+  expiration: { expiresIn: '24h' },
+}
+```
+
+> **Note:** `@tus/server` already includes all TUS protocol headers (Authorization, Content-Type, Tus-Resumable, Upload-Length, Upload-Metadata, Upload-Offset, etc.). The `allowedHeaders` option is only for project-specific custom headers.
+
+**Add custom headers (if needed):**
+```typescript
+// config.env.ts
+tus: {
+  allowedHeaders: ['X-Custom-Header'], // Only additional project-specific headers
+}
+```
+
+**Disable TUS (if needed):**
+```typescript
+// server.module.ts
+TusModule.forRoot({ config: false })
+```
+
+**Client Usage:**
+```typescript
+import { Upload } from 'tus-js-client';
+
+const upload = new Upload(file, {
+  endpoint: 'http://localhost:3000/tus',
+  metadata: { filename: file.name, filetype: file.type },
+  onSuccess: () => console.log('Upload complete!'),
+});
+upload.start();
+```
+
+### 2. CoreFileController (Public Download Endpoints)
+
+New abstract controller providing public file download endpoints:
+
+| Endpoint | Description | Permission |
+|----------|-------------|------------|
+| `GET /files/id/:id` | Download by ID | S_EVERYONE |
+| `GET /files/:filename` | Download by filename | S_EVERYONE |
+
+Projects extending `CoreFileController` automatically get these endpoints.
+
+---
+
+## Breaking Changes
+
+### Change 1: File Download Endpoint Pattern
+
+The file download by ID endpoint has changed from `/files/:id` to `/files/id/:id`.
+
+**Before (11.7.x):**
+```typescript
+// FileController with custom download endpoint
+@Get(':id')
+@Roles(RoleEnum.ADMIN)
+async getFile(@Param('id') id: string, @Res() res: Response) { }
+
+// Client usage
+GET /files/abc123  → Downloads file by ID (admin only)
+```
+
+**After (11.8.x):**
+```typescript
+// FileController extends CoreFileController
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+  // Inherited: GET /files/id/:id (public)
+  // Inherited: GET /files/:filename (public)
+}
+
+// Client usage
+GET /files/id/abc123  → Downloads file by ID (public)
+GET /files/example.pdf  → Downloads file by filename (public)
+```
+
+**Migration Steps:**
+
+1. **Update FileController** to extend `CoreFileController`:
+
+```typescript
+// src/server/modules/file/file.controller.ts
+import { Controller, Delete, Get, Param, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
+import { CoreFileController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+import { FileService } from './file.service';
+
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+
+  // Keep your admin-only endpoints (upload, info, delete)
+  @Post('upload')
+  @Roles(RoleEnum.ADMIN)
+  @UseInterceptors(FileInterceptor('file'))
+  async uploadFile(@UploadedFile() file: Express.Multer.File) { /* ... */ }
+
+  @Get('info/:id')
+  @Roles(RoleEnum.ADMIN)
+  async getFileInfo(@Param('id') id: string) { /* ... */ }
+
+  @Delete(':id')
+  @Roles(RoleEnum.ADMIN)
+  async deleteFile(@Param('id') id: string) { /* ... */ }
+
+  // REMOVE your old getFile() method - CoreFileController handles downloads
+}
+```
+
+2. **Update client-side download URLs:**
+
+```typescript
+// Before
+const downloadUrl = `/files/${fileId}`;
+
+// After
+const downloadUrl = `/files/id/${fileId}`;
+// Or by filename:
+const downloadUrl = `/files/${filename}`;
+```
+
+3. **Optional: Restrict download access** (if you need authentication):
+
+```typescript
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  // Override to require authentication
+  @Get('id/:id')
+  @Roles(RoleEnum.S_USER)  // Require logged-in user
+  override async getFileById(@Param('id') id: string, @Res() res: Response) {
+    return super.getFileById(id, res);
+  }
+
+  @Get(':filename')
+  @Roles(RoleEnum.S_USER)
+  override async getFile(@Param('filename') filename: string, @Res() res: Response) {
+    return super.getFile(filename, res);
+  }
+}
+```
+
+---
+
+## Compatibility Notes
+
+### Pattern: Custom FileController without CoreFileController
+
+If you want to keep the old behavior exactly:
+
+```typescript
+// This still works - don't extend CoreFileController
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController {
+  constructor(private readonly fileService: FileService) {}
+
+  @Get(':id')
+  @Roles(RoleEnum.ADMIN)
+  async getFile(@Param('id') id: string, @Res() res: Response) {
+    // Your existing implementation
+  }
+}
+```
+
+### Pattern: TUS with Authentication
+
+By default, TUS allows everyone to upload. To require authentication:
+
+```typescript
+// src/server/modules/tus/tus.controller.ts
+import { Controller } from '@nestjs/common';
+import { CoreTusController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+
+@Controller('tus')
+@Roles(RoleEnum.S_USER)  // Require logged-in user
+export class TusController extends CoreTusController {}
+
+// server.module.ts
+TusModule.forRoot({ controller: TusController })
+```
+
+---
+
+## Troubleshooting
+
+### Download returns 404 after migration
+
+**Cause:** Using old endpoint pattern `/files/:id` instead of `/files/id/:id`
+
+**Solution:** Update client to use `/files/id/:id` or `/files/:filename`
+
+### TUS uploads not working
+
+**Cause:** TUS might be disabled in config
+
+**Solution:** Check that `tus: false` is not set in your config. TUS is enabled by default.
+
+### TypeScript error: "must have an 'override' modifier"
+
+**Cause:** `fileService` in constructor needs `override` when extending CoreFileController
+
+**Solution:**
+```typescript
+// Add 'override' keyword
+constructor(protected override readonly fileService: FileService) {
+  super(fileService);
+}
+```
+
+---
+
+## Module Documentation
+
+### TUS Module
+
+- **README:** [src/core/modules/tus/README.md](../src/core/modules/tus/README.md)
+- **Integration Checklist:** [src/core/modules/tus/INTEGRATION-CHECKLIST.md](../src/core/modules/tus/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/server.module.ts`
+
+### File Module
+
+- **README:** [src/core/modules/file/README.md](../src/core/modules/file/README.md)
+- **Reference Implementation:** `src/server/modules/file/file.controller.ts`
+
+---
+
+## References
+
+- [TUS Protocol](https://tus.io/protocols/resumable-upload)
+- [tus-js-client](https://github.com/tus/tus-js-client)
+- [@tus/server](https://github.com/tus/tus-node-server)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)