@lenne.tech/nest-server 11.7.2 → 11.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.7.2",
+  "version": "11.8.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -93,6 +93,8 @@
     "@nestjs/swagger": "11.2.3",
     "@nestjs/terminus": "11.0.0",
     "@nestjs/websockets": "11.1.9",
+    "@tus/file-store": "2.0.0",
+    "@tus/server": "2.3.0",
     "apollo-server-core": "3.13.0",
     "bcrypt": "6.0.0",
     "better-auth": "1.4.8-beta.4",
@@ -167,6 +169,7 @@
     "ts-morph": "27.0.2",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
+    "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
     "vite": "7.3.0",

package/src/core/common/interfaces/server-options.interface.ts

@@ -1132,4 +1132,158 @@ export interface IServerOptions {
      */
     path?: string;
   };
+
+  /**
+   * TUS resumable upload configuration.
+   *
+   * Follows the "Enabled by Default" pattern - tus is automatically enabled
+   * without any configuration. Set `tus: false` to explicitly disable.
+   *
+   * Accepts:
+   * - `true` or `undefined`: Enable with defaults (enabled by default)
+   * - `false`: Disable TUS uploads
+   * - `{ ... }`: Enable with custom configuration
+   *
+   * @example
+   * ```typescript
+   * // Default: TUS enabled with all defaults (no config needed)
+   *
+   * // Disable TUS
+   * tus: false,
+   *
+   * // Custom configuration
+   * tus: {
+   *   maxSize: 100 * 1024 * 1024, // 100 MB
+   *   path: '/uploads',
+   * },
+   * ```
+   *
+   * @since 11.8.0
+   */
+  tus?: boolean | ITusConfig;
+}
+
+/**
+ * TUS Upload Configuration Interface
+ *
+ * Follows the "Enabled by Default" pattern - tus is automatically enabled
+ * without any configuration. Set `tus: false` to explicitly disable.
+ */
+export interface ITusConfig {
+  /**
+   * Additional allowed HTTP headers for TUS requests (beyond @tus/server defaults).
+   *
+   * Note: @tus/server already includes all TUS protocol headers:
+   * Authorization, Content-Type, Location, Tus-Extension, Tus-Max-Size,
+   * Tus-Resumable, Tus-Version, Upload-Concat, Upload-Defer-Length,
+   * Upload-Length, Upload-Metadata, Upload-Offset, X-HTTP-Method-Override,
+   * X-Requested-With, X-Forwarded-Host, X-Forwarded-Proto, Forwarded
+   *
+   * Use this only for project-specific custom headers.
+   *
+   * @default [] (no additional headers needed)
+   */
+  allowedHeaders?: string[];
+
+  /**
+   * Allowed MIME types for uploads.
+   * If undefined, all types are allowed.
+   * @default undefined (all types allowed)
+   */
+  allowedTypes?: string[];
+
+  /**
+   * Checksum extension configuration.
+   * Enables data integrity verification.
+   * @default true
+   */
+  checksum?: boolean;
+
+  /**
+   * Concatenation extension configuration.
+   * Allows parallel uploads that are merged.
+   * @default true
+   */
+  concatenation?: boolean;
+
+  /**
+   * Creation extension configuration.
+   * Allows creating new uploads via POST.
+   * @default true
+   */
+  creation?: boolean | ITusCreationConfig;
+
+  /**
+   * Creation With Upload extension configuration.
+   * Allows sending data in the initial POST request.
+   * @default true
+   */
+  creationWithUpload?: boolean;
+
+  /**
+   * Whether tus uploads are enabled.
+   * @default true (enabled by default)
+   */
+  enabled?: boolean;
+
+  /**
+   * Expiration extension configuration.
+   * Automatically cleans up incomplete uploads.
+   * @default { expiresIn: '24h' }
+   */
+  expiration?: boolean | ITusExpirationConfig;
+
+  /**
+   * Maximum upload size in bytes
+   * @default 50 * 1024 * 1024 * 1024 (50 GB)
+   */
+  maxSize?: number;
+
+  /**
+   * Base path for tus endpoints
+   * @default '/tus'
+   */
+  path?: string;
+
+  /**
+   * Termination extension configuration.
+   * Allows deleting uploads via DELETE.
+   * @default true
+   */
+  termination?: boolean;
+
+  /**
+   * Directory for temporary upload chunks.
+   * @default 'uploads/tus'
+   */
+  uploadDir?: string;
+}
+
+/**
+ * TUS Creation extension configuration
+ */
+export interface ITusCreationConfig {
+  /**
+   * Whether creation is enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * TUS Expiration extension configuration
+ */
+export interface ITusExpirationConfig {
+  /**
+   * Whether expiration is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Time until incomplete uploads expire
+   * Supports formats: '24h', '1d', '12h', etc.
+   * @default '24h'
+   */
+  expiresIn?: string;
 }

package/src/core/modules/auth/guards/roles.guard.ts

@@ -1,8 +1,12 @@
-import { ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
+import { ExecutionContext, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
+import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
+import { getConnectionToken } from '@nestjs/mongoose';
+import { Connection, Types } from 'mongoose';
+import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
+import { BetterAuthService } from '../../better-auth/better-auth.service';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
 import { InvalidTokenException } from '../exceptions/invalid-token.exception';
@@ -14,16 +18,305 @@ import { AuthGuard } from './auth.guard';
  * The RoleGuard is activated by the Role decorator. It checks whether the current user has at least one of the
  * specified roles or is logged in when the S_USER role is set.
  * If this is not the case, an UnauthorizedException is thrown.
+ *
+ * MULTI-TOKEN SUPPORT:
+ * This guard supports multiple authentication token types:
+ * 1. Legacy JWT tokens (Passport JWT strategy)
+ * 2. BetterAuth JWT tokens (verified via BetterAuth service)
+ * 3. BetterAuth session tokens (verified via database lookup)
+ *
+ * When Passport JWT validation fails, the guard falls back to BetterAuth verification:
+ * - First tries JWT verification if the JWT plugin is enabled
+ * - Then tries session token lookup via MongoDB
+ *
+ * This enables users who sign in via IAM (/iam/sign-in/email) to access all protected endpoints,
+ * regardless of whether they use JWT or session-based authentication.
  */
 @Injectable()
 export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
+  private readonly logger = new Logger(RolesGuard.name);
+  private betterAuthService: BetterAuthService | null = null;
+  private mongoConnection: Connection | null = null;
+  private servicesResolved = false;
+
   /**
-   * Integrate reflector
+   * Integrate reflector and moduleRef for lazy service resolution
    */
-  constructor(protected readonly reflector: Reflector) {
+  constructor(
+    protected readonly reflector: Reflector,
+    @Optional() private readonly moduleRef?: ModuleRef,
+  ) {
     super();
   }
 
+  /**
+   * Lazily resolve BetterAuth service and MongoDB connection
+   */
+  private resolveServices(): void {
+    if (this.servicesResolved || !this.moduleRef) {
+      return;
+    }
+
+    try {
+      this.betterAuthService = this.moduleRef.get(BetterAuthService, { strict: false });
+    } catch {
+      // BetterAuth not available - that's fine, we'll use Legacy JWT only
+    }
+
+    try {
+      // Get the Mongoose connection to query users directly
+      this.mongoConnection = this.moduleRef.get(getConnectionToken(), { strict: false });
+    } catch {
+      // MongoDB connection not available
+    }
+
+    this.servicesResolved = true;
+  }
+
+  /**
+   * Override canActivate to add BetterAuth JWT fallback
+   *
+   * Flow:
+   * 1. Try Passport JWT authentication (Legacy JWT)
+   * 2. If that fails, try BetterAuth JWT verification
+   * 3. If BetterAuth succeeds, load the user and proceed
+   */
+  override async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Resolve services lazily
+    this.resolveServices();
+
+    // First, try the parent canActivate (Passport JWT)
+    try {
+      const result = super.canActivate(context);
+      return isObservable(result) ? await firstValueFrom(result) : await result;
+    } catch (passportError) {
+      // Passport JWT validation failed - try BetterAuth token fallback (JWT or session)
+      if (!this.betterAuthService?.isEnabled()) {
+        // BetterAuth not available - rethrow original error
+        throw passportError;
+      }
+
+      // Try to verify the token via BetterAuth (JWT or session token)
+      const user = await this.verifyBetterAuthTokenFromContext(context);
+      if (!user) {
+        // BetterAuth verification also failed - rethrow original Passport error
+        throw passportError;
+      }
+
+      // BetterAuth token is valid - set the user on the request
+      const request = this.getRequest(context);
+      if (request) {
+        request.user = user;
+      }
+
+      // Now call handleRequest with the BetterAuth-authenticated user to check roles
+      this.handleRequest(null, user, null, context);
+
+      return true;
+    }
+  }
+
+  /**
+   * Verify BetterAuth token (JWT or session) and load the corresponding user
+   *
+   * This method tries multiple verification strategies:
+   * 1. BetterAuth JWT verification (if JWT plugin is enabled)
+   * 2. BetterAuth session token lookup (database lookup)
+   *
+   * @param context - ExecutionContext to extract request from
+   * @returns User object if verification succeeds, null otherwise
+   */
+  private async verifyBetterAuthTokenFromContext(context: ExecutionContext): Promise<any> {
+    if (!this.betterAuthService || !this.mongoConnection) {
+      return null;
+    }
+
+    try {
+      // Get the raw HTTP request from multiple possible sources
+      let authHeader: string | undefined;
+
+      // Try GraphQL context first
+      try {
+        const gqlContext = GqlExecutionContext.create(context);
+        const ctx = gqlContext.getContext();
+        if (ctx?.req?.headers) {
+          authHeader = ctx.req.headers.authorization || ctx.req.headers.Authorization;
+        }
+      } catch {
+        // GraphQL context not available
+      }
+
+      // Fallback to HTTP context
+      if (!authHeader) {
+        try {
+          const httpRequest = context.switchToHttp().getRequest();
+          if (httpRequest?.headers) {
+            authHeader = httpRequest.headers.authorization || httpRequest.headers.Authorization;
+          }
+        } catch {
+          // HTTP context not available
+        }
+      }
+
+      let token: string | undefined;
+
+      if (authHeader?.startsWith('Bearer ')) {
+        token = authHeader.substring(7);
+      } else if (authHeader?.startsWith('bearer ')) {
+        // Handle lowercase 'bearer' as well
+        token = authHeader.substring(7);
+      }
+
+      if (!token) {
+        return null;
+      }
+
+      // Strategy 1: Try JWT verification (if JWT plugin is enabled)
+      if (this.betterAuthService.isJwtEnabled()) {
+        try {
+          const payload = await this.betterAuthService.verifyJwtToken(token);
+          if (payload?.sub) {
+            const user = await this.loadUserFromPayload(payload);
+            if (user) {
+              return user;
+            }
+          }
+        } catch {
+          // JWT verification failed - try session token next
+        }
+      }
+
+      // Strategy 2: Try session token lookup (database lookup)
+      try {
+        const sessionResult = await this.betterAuthService.getSessionByToken(token);
+        if (sessionResult?.user) {
+          return this.loadUserFromSessionResult(sessionResult.user);
+        }
+      } catch {
+        // Session lookup failed
+      }
+
+      return null;
+    } catch (error) {
+      this.logger.debug(
+        `BetterAuth token fallback failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Load user from JWT payload using direct MongoDB query
+   *
+   * @param payload - JWT payload with sub (user ID or iamId)
+   * @returns User object with hasRole method
+   */
+  private async loadUserFromPayload(payload: { [key: string]: any; sub: string }): Promise<any> {
+    if (!this.mongoConnection) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.mongoConnection.collection('users');
+      let user: any = null;
+
+      // Try to find by MongoDB _id first
+      if (Types.ObjectId.isValid(payload.sub)) {
+        user = await usersCollection.findOne({ _id: new Types.ObjectId(payload.sub) });
+      }
+
+      // If not found, try by iamId
+      if (!user) {
+        user = await usersCollection.findOne({ iamId: payload.sub });
+      }
+
+      if (!user) {
+        return null;
+      }
+
+      // Convert MongoDB document to user-like object with hasRole method
+      const userObject = {
+        ...user,
+        _authenticatedViaBetterAuth: true,
+        // Add hasRole method for role checking
+        hasRole: (roles: string[]): boolean => {
+          if (!user.roles || !Array.isArray(user.roles)) {
+            return false;
+          }
+          return roles.some((role) => user.roles.includes(role));
+        },
+        id: user._id?.toString(),
+      };
+
+      return userObject;
+    } catch (error) {
+      this.logger.debug(
+        `Failed to load user from payload: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Load user from session result (from getSessionByToken)
+   *
+   * @param sessionUser - User object from session lookup
+   * @returns User object with hasRole method
+   */
+  private async loadUserFromSessionResult(sessionUser: any): Promise<any> {
+    if (!this.mongoConnection || !sessionUser) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.mongoConnection.collection('users');
+
+      // The sessionUser might have id (BetterAuth ID) or email
+      // We need to find the corresponding user in our users collection
+      let user: any = null;
+
+      // Try to find by email (most reliable)
+      if (sessionUser.email) {
+        user = await usersCollection.findOne({ email: sessionUser.email });
+      }
+
+      // If not found by email, try by iamId
+      if (!user && sessionUser.id) {
+        user = await usersCollection.findOne({ iamId: sessionUser.id });
+      }
+
+      // If still not found, try by _id (if the ID looks like a MongoDB ObjectId)
+      if (!user && sessionUser.id && Types.ObjectId.isValid(sessionUser.id)) {
+        user = await usersCollection.findOne({ _id: new Types.ObjectId(sessionUser.id) });
+      }
+
+      if (!user) {
+        return null;
+      }
+
+      // Convert MongoDB document to user-like object with hasRole method
+      const userObject = {
+        ...user,
+        _authenticatedViaBetterAuth: true,
+        // Add hasRole method for role checking
+        hasRole: (roles: string[]): boolean => {
+          if (!user.roles || !Array.isArray(user.roles)) {
+            return false;
+          }
+          return roles.some((role) => user.roles.includes(role));
+        },
+        id: user._id?.toString(),
+      };
+
+      return userObject;
+    } catch (error) {
+      this.logger.debug(
+        `Failed to load user from session: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
   /**
    * Handle request
    */
@@ -42,7 +335,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     }
 
     // Check roles
-    if (!roles || !roles.some(value => !!value)) {
+    if (!roles || !roles.some((value) => !!value)) {
       return user;
     }
 

package/src/core/modules/file/README.md

@@ -0,0 +1,165 @@
+# File Module
+
+File upload and download functionality with MongoDB GridFS storage.
+
+## Endpoints
+
+### Public Endpoints (via CoreFileController)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/files/id/:id` | Download file by ID |
+| GET | `/files/:filename` | Download file by filename |
+
+**Note:** These endpoints are public (`S_EVERYONE`) by default. Projects can restrict access by extending `CoreFileController`.
+
+### Admin Endpoints (project-specific)
+
+Projects typically add admin-only endpoints like:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/files/upload` | Upload file (multipart/form-data) |
+| GET | `/files/info/:id` | Get file metadata |
+| DELETE | `/files/:id` | Delete file |
+
+---
+
+## Usage in Projects
+
+### Basic Setup (Extend CoreFileController)
+
+```typescript
+// src/server/modules/file/file.controller.ts
+import { Controller } 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);
+  }
+
+  // Add admin-only endpoints here (upload, delete, etc.)
+}
+```
+
+### Restrict Download Access
+
+To require authentication for downloads, override the inherited methods:
+
+```typescript
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+
+  // Override to require authentication for ID-based download
+  @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);
+  }
+
+  // Override to require authentication for filename-based download
+  @Get(':filename')
+  @Roles(RoleEnum.S_USER)
+  override async getFile(@Param('filename') filename: string, @Res() res: Response) {
+    return super.getFile(filename, res);
+  }
+}
+```
+
+---
+
+## GraphQL Support
+
+File operations are also available via GraphQL through `CoreFileResolver`:
+
+```graphql
+# Query file by ID
+query {
+  file(id: "...") {
+    id
+    filename
+    contentType
+    length
+  }
+}
+
+# Query file by filename
+query {
+  fileByFilename(filename: "...") {
+    id
+    filename
+    contentType
+  }
+}
+
+# Upload file (via GraphQL Upload scalar)
+mutation {
+  uploadFile(file: Upload!) {
+    id
+    filename
+  }
+}
+
+# Delete file
+mutation {
+  deleteFile(filename: "...") {
+    id
+  }
+}
+```
+
+---
+
+## Integration with TUS
+
+Files uploaded via TUS are automatically stored in GridFS and can be accessed through the same endpoints:
+
+```bash
+# After TUS upload completes, download by ID
+GET /files/id/<gridfs-file-id>
+
+# Or by filename (if unique)
+GET /files/<original-filename>
+```
+
+**Recommendation:** Use ID-based downloads for TUS uploads as filenames may not be unique.
+
+---
+
+## GridFS Storage
+
+Files are stored in MongoDB GridFS with the following structure:
+
+**fs.files collection:**
+```json
+{
+  "_id": ObjectId,
+  "filename": "example.pdf",
+  "length": 1048576,
+  "uploadDate": ISODate,
+  "metadata": {
+    "contentType": "application/pdf",
+    "tusUploadId": "...",  // If uploaded via TUS
+    "uploadedAt": ISODate
+  }
+}
+```
+
+**fs.chunks collection:**
+- Binary file data split into 255KB chunks
+- Automatically managed by GridFS
+
+---
+
+## Related Documentation
+
+- [TUS Module](../tus/README.md) - Resumable upload protocol
+- [CoreFileService](./core-file.service.ts) - File service implementation

package/src/core/modules/file/core-file.controller.ts

@@ -17,7 +17,33 @@ export abstract class CoreFileController {
   protected constructor(protected fileService: CoreFileService) {}
 
   /**
-   * Download file
+   * Download file by ID
+   *
+   * More reliable than filename-based download as IDs are unique.
+   * Recommended for TUS uploads and when filename uniqueness cannot be guaranteed.
+   */
+  @Get('id/:id')
+  @Roles(RoleEnum.S_EVERYONE)
+  async getFileById(@Param('id') id: string, @Res() res: Response) {
+    if (!id) {
+      throw new BadRequestException('Missing file ID for download');
+    }
+
+    const file = await this.fileService.getFileInfo(id);
+    if (!file) {
+      throw new NotFoundException('File not found');
+    }
+    const filestream = await this.fileService.getFileStream(id);
+    res.header('Content-Type', file.contentType || 'application/octet-stream');
+    res.header('Content-Disposition', `attachment; filename=${file.filename}`);
+    return filestream.pipe(res);
+  }
+
+  /**
+   * Download file by filename
+   *
+   * Note: If multiple files have the same filename, only the first match is returned.
+   * For unique file access, use GET /files/id/:id instead.
    */
   @Get(':filename')
   @Roles(RoleEnum.S_EVERYONE)