@lenne.tech/nest-server 11.21.2 → 11.22.0

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -47,6 +47,10 @@ interface CachedTenantIds {
  * - Plugin level: Safety net — ForbiddenException when tenantId-schema accessed without context
  *
  * Role check semantics:
+ * - System roles are OR alternatives, checked in order before real roles:
+ *   S_EVERYONE → immediate pass; S_USER → pass if authenticated; S_VERIFIED → pass if verified
+ * - When a system role grants access and X-Tenant-Id header is present, membership is still
+ *   validated to set tenant context (tenantId + tenantRole) on the request.
  * - Hierarchy roles (in roleHierarchy config): level comparison — higher includes lower
  * - Normal roles (not in roleHierarchy): exact match — no compensation by higher role
  * - Tenant context (header present): checks against membership.role only (user.roles ignored)
@@ -61,9 +65,13 @@ interface CachedTenantIds {
  * Flow:
  * 1. Config check: multiTenancy enabled?
  * 2. Parse header (X-Tenant-Id, max 128 chars, trimmed)
- * 3. @SkipTenantCheck → role check against user.roles, no tenant context
- * 4. Read @Roles() metadata, filter out system roles
- * 5. BetterAuth auto-skip (betterAuth.skipTenantCheck config + no header) → skip, no tenant context
+ * 3. Read @Roles() metadata (method + class level)
+ * 4. System role early-exit checks (OR alternatives):
+ *    S_EVERYONE → pass immediately
+ *    S_USER → pass if authenticated (+ optional membership check when header present)
+ *    S_VERIFIED → pass if user is verified (+ optional membership check when header present)
+ * 5. @SkipTenantCheck → role check against user.roles, no tenant context
+ * 6. BetterAuth auto-skip (betterAuth.skipTenantCheck config + no header) → skip, no tenant context
  *
  * HEADER PRESENT:
  *   - System ADMIN (adminBypass: true) → set req.tenantId + isAdminBypass
@@ -184,24 +192,111 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     const headerTenantId =
       rawHeader && typeof rawHeader === 'string' && rawHeader.length <= 128 ? rawHeader.trim() : undefined;
 
-    // Read @Roles() metadata and filter to non-system roles
+    // Two role sets for different purposes:
+    //
+    // 1. systemCheckRoles (method-takes-precedence): Used for system role early-returns.
+    //    Method-level system roles override class-level ones to prevent e.g. class @Roles(S_EVERYONE)
+    //    from making a method @Roles(S_USER) endpoint public.
+    //
+    // 2. roles (OR/merged): Used for real role checks (checkableRoles).
+    //    Class-level roles serve as a base that method-level roles extend.
+    //    E.g., class @Roles(ADMIN) + method @Roles('editor') → both are alternatives.
+    //
+    // S_EVERYONE check — access is always granted; no authentication or membership required.
+    //
+    // Header handling for S_EVERYONE:
+    //   - No header → return true immediately (no tenant context needed)
+    //   - Header present + authenticated user that IS a member → optionally enrich with tenant
+    //     context (sets request.tenantId/tenantRole) so downstream consumers can use it.
+    //     Access is NOT blocked if user is not a member — S_EVERYONE means public access.
     const rolesMetadata = this.reflector.getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
     const roles = mergeRolesMetadata(rolesMetadata);
+    const methodRoles: string[] = rolesMetadata[0] ?? [];
+    const systemCheckRoles = methodRoles.length > 0 ? methodRoles : roles;
+
+    // Defense-in-depth: S_NO_ONE is normally caught by RolesGuard/BetterAuthRolesGuard upstream,
+    // but guard it here too in case CoreTenantGuard runs standalone (e.g., custom guard chains).
+    if (roles.includes(RoleEnum.S_NO_ONE)) {
+      throw new ForbiddenException('Access denied');
+    }
+
+    const sEveryoneGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_EVERYONE);
+    if (sEveryoneGrantsAccess) {
+      // Optionally enrich with tenant context when header is present and user is an active member.
+      // Never block access — S_EVERYONE endpoints are always public.
+      if (headerTenantId && request.user?.id) {
+        const membership = await this.findMembershipCached(request.user.id, headerTenantId);
+        if (membership) {
+          request.tenantId = headerTenantId;
+          request.tenantRole = membership.role as string;
+        }
+      }
+      return true;
+    }
 
     const user = request.user;
     const adminBypass = config.adminBypass !== false;
     const isAdmin = adminBypass && user?.roles?.includes(RoleEnum.ADMIN);
 
-    // Filter to checkable (non-system) roles only when needed (avoids array allocation on fast paths)
-    const hasNonSystemRoles = roles.some((r) => !isSystemRole(r));
-    const checkableRoles = hasNonSystemRoles ? roles.filter((r) => !isSystemRole(r)) : [];
-    const minRequiredLevel = checkableRoles.length > 0 ? getMinRequiredLevel(checkableRoles) : undefined;
-
-    // @SkipTenantCheck decorator → no tenant context, but role check against user.roles
+    // Read @SkipTenantCheck early — it suppresses tenant membership validation for system roles too.
+    // When set, S_USER and S_VERIFIED still enforce authentication/verification, but no membership
+    // check is performed even when a tenant header is present.
     const hasSkipDecorator = this.reflector.getAllAndOverride<boolean>(SKIP_TENANT_CHECK_KEY, [
       context.getHandler(),
       context.getClass(),
     ]);
+
+    // S_USER check — any authenticated user satisfies this system role.
+    //
+    // OR semantics: if S_USER is in the active role set, a logged-in user gets through.
+    // Real roles in the same @Roles() are ignored when S_USER is satisfied (they are alternatives).
+    // Example: @Roles(S_USER, 'owner') → a plain logged-in user passes (owner is an alternative, not required).
+    //
+    // Tenant header behavior: when X-Tenant-Id is present and @SkipTenantCheck is NOT set,
+    // membership is validated so that tenant context (tenantId, tenantRole) is set on the request.
+    // A non-member will still get 403 when a tenant header is provided (unless @SkipTenantCheck).
+    const sUserGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_USER);
+    if (sUserGrantsAccess) {
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+      if (headerTenantId && !hasSkipDecorator) {
+        return this.handleSystemRoleWithTenantHeader(user, headerTenantId, request, isAdmin);
+      }
+      return true;
+    }
+
+    // S_VERIFIED check — any verified authenticated user satisfies this system role.
+    //
+    // A user is considered verified when any of these properties is truthy:
+    //   user.verified, user.verifiedAt, user.emailVerified
+    //
+    // Tenant header behavior: same as S_USER — membership is validated when header is present
+    // (unless @SkipTenantCheck is set).
+    const sVerifiedGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_VERIFIED);
+    if (sVerifiedGrantsAccess) {
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+      const isVerified = !!(user.verified || user.verifiedAt || user.emailVerified);
+      if (!isVerified) {
+        throw new ForbiddenException('Verification required');
+      }
+      if (headerTenantId && !hasSkipDecorator) {
+        return this.handleSystemRoleWithTenantHeader(user, headerTenantId, request, isAdmin);
+      }
+      return true;
+    }
+
+    // Extract checkable (non-system) roles from the merged set.
+    // System roles that grant access (S_EVERYONE, S_USER, S_VERIFIED) have been
+    // early-returned above. Remaining system roles (S_SELF, S_CREATOR) are object-level
+    // and handled by interceptors.
+    const checkableRoles = roles.filter((r: string) => !isSystemRole(r));
+
+    const minRequiredLevel = checkableRoles.length > 0 ? getMinRequiredLevel(checkableRoles) : undefined;
+
+    // @SkipTenantCheck decorator → no tenant context, but role check against user.roles
     if (hasSkipDecorator) {
       return this.skipWithUserRoleCheck(checkableRoles, user, isAdmin);
     }
@@ -238,7 +333,7 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
         const requiredRole = checkableRoles.length > 0 ? checkableRoles.join(',') : 'none';
         // Sanitize control characters to prevent log injection
         const safeTenantId = headerTenantId.replace(/[\r\n\t]/g, '_');
-        this.logger.log(`Admin bypass: user ${user.id} accessing tenant ${safeTenantId} (required: ${requiredRole})`);
+        this.logger.debug(`Admin bypass: user ${user.id} accessing tenant ${safeTenantId} (required: ${requiredRole})`);
         return true;
       }
 
@@ -465,6 +560,42 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     }
   }
 
+  /**
+   * Validate tenant membership for a request that was granted access via a system role
+   * (S_USER or S_VERIFIED). When a tenant header is present, the user must be an active member
+   * of that tenant — unless the user is an admin with adminBypass enabled.
+   *
+   * On success, sets request.tenantId and request.tenantRole for downstream consumers.
+   *
+   * @param user - The authenticated request user
+   * @param headerTenantId - The validated, non-empty tenant ID from the request header
+   * @param request - The HTTP/GraphQL request object
+   * @param isAdmin - Whether the user has admin bypass privileges
+   */
+  private async handleSystemRoleWithTenantHeader(
+    user: any,
+    headerTenantId: string,
+    request: any,
+    isAdmin: boolean,
+  ): Promise<true> {
+    // Admin bypass: same behavior as the HEADER PRESENT admin path below
+    if (isAdmin) {
+      request.tenantId = headerTenantId;
+      request.isAdminBypass = true;
+      const safeTenantId = headerTenantId.replace(/[\r\n\t]/g, '_');
+      this.logger.debug(`Admin bypass (system-role path): user ${user.id} accessing tenant ${safeTenantId}`);
+      return true;
+    }
+
+    const membership = await this.findMembershipCached(user.id, headerTenantId);
+    if (!membership) {
+      throw new ForbiddenException('Not a member of this tenant');
+    }
+    request.tenantId = headerTenantId;
+    request.tenantRole = membership.role as string;
+    return true;
+  }
+
   /**
    * Skip tenant validation but still check non-system roles against user.roles.
    * Shared by @SkipTenantCheck decorator path and BetterAuth auto-skip path.

package/src/core/modules/tenant/core-tenant.helpers.ts

@@ -5,7 +5,10 @@ const SYSTEM_ROLE_PREFIX = 's_';
 
 /**
  * Merge handler-level and class-level @Roles() metadata arrays into a single flat array.
- * Used by RolesGuard, BetterAuthRolesGuard, and CoreTenantGuard to avoid code duplication.
+ * Used by RolesGuard, BetterAuthRolesGuard, and CoreTenantGuard.
+ *
+ * OR semantics: class-level roles serve as a base that method-level roles extend.
+ * Example: class @Roles(ADMIN) + method @Roles(S_USER) → [S_USER, ADMIN] — both are alternatives.
  *
  * @param meta - Two-element tuple [handlerRoles, classRoles] from Reflector.getAll or Reflect.getMetadata
  */
@@ -22,7 +25,8 @@ export function getRoleHierarchy(): Record<string, number> {
 
 /**
  * Check if a role is a system role (S_USER, S_EVERYONE, etc.).
- * System roles are handled by RolesGuard, not CoreTenantGuard.
+ * System roles are checked by RolesGuard/BetterAuthRolesGuard for authentication
+ * and by CoreTenantGuard as OR alternatives before real role checks.
  */
 export function isSystemRole(role: string): boolean {
   return role.startsWith(SYSTEM_ROLE_PREFIX);

package/src/core.module.ts

@@ -12,7 +12,7 @@ import { CheckResponseInterceptor } from './core/common/interceptors/check-respo
 import { CheckSecurityInterceptor } from './core/common/interceptors/check-security.interceptor';
 import { ResponseModelInterceptor } from './core/common/interceptors/response-model.interceptor';
 import { TranslateResponseInterceptor } from './core/common/interceptors/translate-response.interceptor';
-import { IServerOptions } from './core/common/interfaces/server-options.interface';
+import { ICoreModuleOverrides, IServerOptions } from './core/common/interfaces/server-options.interface';
 import { RequestContextMiddleware } from './core/common/middleware/request-context.middleware';
 import { MapAndValidatePipe } from './core/common/pipes/map-and-validate.pipe';
 import { ComplexityPlugin } from './core/common/plugins/complexity.plugin';
@@ -95,6 +95,12 @@ export class CoreModule implements NestModule {
    *
    * ```typescript
    * CoreModule.forRoot(envConfig)
+   *
+   * // With module overrides (custom controllers/resolvers/services)
+   * CoreModule.forRoot(envConfig, {
+   *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+   *   betterAuth: { resolver: BetterAuthResolver },
+   * })
    * ```
    *
    * Use this for new projects that only use BetterAuth (IAM) for authentication.
@@ -109,6 +115,11 @@ export class CoreModule implements NestModule {
    *
    * ```typescript
    * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig)
+   *
+   * // With module overrides
+   * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+   *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+   * })
    * ```
    *
    * @deprecated This 3-parameter signature is deprecated for new projects.
@@ -127,22 +138,36 @@ export class CoreModule implements NestModule {
    *
    * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
    */
-  static forRoot(options: Partial<IServerOptions>): DynamicModule;
+  static forRoot(options: Partial<IServerOptions>, overrides?: ICoreModuleOverrides): DynamicModule;
   /**
    * @deprecated Use the single-parameter signature `CoreModule.forRoot(envConfig)` for new projects.
    * This 3-parameter signature is for existing projects during migration to IAM.
    */
-  static forRoot(AuthService: any, AuthModule: any, options: Partial<IServerOptions>): DynamicModule;
+  static forRoot(
+    AuthService: any,
+    AuthModule: any,
+    options: Partial<IServerOptions>,
+    overrides?: ICoreModuleOverrides,
+  ): DynamicModule;
   static forRoot(
     authServiceOrOptions: any,
     authModuleOrUndefined?: any,
     optionsOrUndefined?: Partial<IServerOptions>,
+    overridesOrUndefined?: ICoreModuleOverrides,
   ): DynamicModule {
-    // Detect which signature was used
-    const isIamOnlyMode = authModuleOrUndefined === undefined && optionsOrUndefined === undefined;
+    // Detect which signature was used:
+    // IAM-only: forRoot(config, overrides?) — first arg is a plain object (config)
+    // Legacy:   forRoot(AuthService, AuthModule, config, overrides?) — first arg is a class (function)
+    const isIamOnlyMode = typeof authServiceOrOptions !== 'function';
     const AuthService = isIamOnlyMode ? null : authServiceOrOptions;
     const AuthModule = isIamOnlyMode ? null : authModuleOrUndefined;
     const options: Partial<IServerOptions> = isIamOnlyMode ? authServiceOrOptions : optionsOrUndefined;
+    // For IAM-only mode: overrides is the 2nd param; for legacy mode: it's the 4th param.
+    // The cast is safe: the public overloads guarantee the 2nd arg is ICoreModuleOverrides | undefined
+    // in IAM-only mode (typeof first arg !== 'function'), never a DynamicModule (AuthModule).
+    const overrides: ICoreModuleOverrides | undefined = isIamOnlyMode
+      ? (authModuleOrUndefined as ICoreModuleOverrides | undefined)
+      : overridesOrUndefined;
 
     // Process config
     let cors = {};
@@ -316,11 +341,21 @@ export class CoreModule implements NestModule {
     const errorCodeConfig = config.errorCode;
     const isErrorCodeAutoRegister = errorCodeConfig?.autoRegister !== false;
 
+    if (!isErrorCodeAutoRegister && (overrides?.errorCode?.controller || overrides?.errorCode?.service)) {
+      console.warn(
+        'CoreModule: errorCode overrides are ignored because errorCode.autoRegister is false. ' +
+          'Either remove autoRegister: false or pass controller/service to your own ErrorCodeModule.forRoot() call.',
+      );
+    }
+
     if (isErrorCodeAutoRegister) {
       // Always use forRoot() - it registers the controller and handles configuration
+      // Overrides take precedence over config for controller/service
       imports.push(
         ErrorCodeModule.forRoot({
           additionalErrorRegistry: errorCodeConfig?.additionalErrorRegistry,
+          controller: overrides?.errorCode?.controller,
+          service: overrides?.errorCode?.service,
         }),
       );
     }
@@ -357,24 +392,31 @@ export class CoreModule implements NestModule {
     // autoRegister: false means the project imports its own BetterAuthModule separately
     const isAutoRegisterDisabled = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === false;
 
-    // Extract custom controller/resolver from config (Pattern 2: Config-based)
+    // Extract custom controller/resolver: overrides take precedence over config fields
     const configController = typeof betterAuthConfig === 'object' ? betterAuthConfig?.controller : undefined;
     const configResolver = typeof betterAuthConfig === 'object' ? betterAuthConfig?.resolver : undefined;
 
+    if (isAutoRegisterDisabled && (overrides?.betterAuth?.controller || overrides?.betterAuth?.resolver)) {
+      console.warn(
+        'CoreModule: betterAuth overrides are ignored because betterAuth.autoRegister is false. ' +
+          'Either remove autoRegister: false or pass controller/resolver to your own BetterAuthModule.forRoot() call.',
+      );
+    }
+
     if (isBetterAuthEnabled) {
       if ((isIamOnlyMode && !isAutoRegisterDisabled) || isAutoRegister) {
         imports.push(
           CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
-            // Pass custom controller/resolver from config (Pattern 2)
-            controller: configController,
+            // Overrides take precedence over config fields (backward compatible)
+            controller: overrides?.betterAuth?.controller || configController,
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
             // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
             // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
             registerRolesGuardGlobally: isIamOnlyMode,
-            // Pass custom resolver from config (Pattern 2)
-            resolver: configResolver,
+            // Overrides take precedence over config fields (backward compatible)
+            resolver: overrides?.betterAuth?.resolver || configResolver,
             // Pass server-level URLs for Passkey auto-detection
             // When env: 'local', defaults are: baseUrl=localhost:3000, appUrl=localhost:3001
             serverAppUrl: config.appUrl,

package/src/server/server.module.ts

@@ -7,7 +7,6 @@ import { Any } from '../core/common/scalars/any.scalar';
 import { DateScalar } from '../core/common/scalars/date.scalar';
 import { JSON } from '../core/common/scalars/json.scalar';
 import { CoreAuthService } from '../core/modules/auth/services/core-auth.service';
-import { ErrorCodeModule } from '../core/modules/error-code/error-code.module';
 import { TusModule } from '../core/modules/tus';
 import { CronJobs } from './common/services/cron-jobs.service';
 import { AuthController } from './modules/auth/auth.controller';
@@ -35,7 +34,13 @@ import { ServerController } from './server.controller';
   imports: [
     // Include CoreModule for standard processes
     // Note: BetterAuthModule is imported manually below (autoRegister defaults to false)
-    CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig),
+    // ErrorCodeModule is auto-registered by CoreModule with overrides for custom controller/service
+    CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+      errorCode: {
+        controller: ErrorCodeController,
+        service: ErrorCodeService,
+      },
+    }),
 
     // Include cron job handling
     ScheduleModule.forRoot(),
@@ -49,13 +54,6 @@ import { ServerController } from './server.controller';
     // This allows project-specific customization via BetterAuthResolver
     BetterAuthModule.forRoot({}),
 
-    // Include ErrorCodeModule with project-specific error codes
-    // Uses Core ErrorCodeModule.forRoot() with custom service and controller
-    ErrorCodeModule.forRoot({
-      controller: ErrorCodeController,
-      service: ErrorCodeService,
-    }),
-
     // Include FileModule for file handling
     FileModule,
 

package/src/test/README.md

@@ -174,6 +174,53 @@ await testHelper.rest('/protected-endpoint', {
 });
 ```
 
+## File Download Testing (`testHelper.download()` / `testHelper.downloadBuffer()`)
+
+### `download(url, tokenOrOptions?)`
+
+Download a file and return the response with a `data` string property for content comparison.
+
+```typescript
+// No authentication
+const res = await testHelper.download('/files/id/abc123');
+expect(res.statusCode).toEqual(200);
+expect(res.data).toEqual('file content');
+```
+
+### `downloadBuffer(url, tokenOrOptions?)`
+
+Download a file and return a `Buffer` for binary comparison or saving.
+
+```typescript
+const buffer = await testHelper.downloadBuffer('/files/id/abc123', jwtToken);
+await fs.promises.writeFile('/tmp/downloaded.bin', buffer);
+```
+
+### TestDownloadOptions
+
+The second parameter accepts either a plain token string or a `TestDownloadOptions` object:
+
+| Option    | Type     | Description                                                   |
+| --------- | -------- | ------------------------------------------------------------- |
+| `token`   | `string` | Bearer token via Authorization header (JWT)                   |
+| `cookies` | `string` | Plain session token, converted via `buildBetterAuthCookies()` |
+
+Both can be used simultaneously — `token` sets the Authorization header while `cookies` sets the Cookie header.
+
+```typescript
+// String form (backward compatible) — sets Authorization: bearer <token>
+await testHelper.download('/files/id/abc123', jwtToken);
+
+// Options object with JWT token
+await testHelper.download('/files/id/abc123', { token: jwtToken });
+
+// Options object with cookie-based session auth
+await testHelper.download('/files/id/abc123', { cookies: sessionToken });
+
+// Both simultaneously
+await testHelper.download('/files/id/abc123', { cookies: sessionToken, token: jwtToken });
+```
+
 ## GraphQL Testing (`testHelper.graphQl()`)
 
 ```typescript

package/src/test/test.helper.ts

@@ -154,6 +154,25 @@ export interface TestRestOptions {
   token?: string;
 }
 
+/**
+ * Options for download/downloadBuffer requests
+ */
+export interface TestDownloadOptions {
+  /**
+   * Cookie-based authentication. Pass a plain session token string
+   * which is converted via buildBetterAuthCookies() to all relevant cookie names
+   * (iam.session_token, token).
+   */
+  cookies?: string;
+
+  /**
+   * Bearer token via Authorization header (JWT authentication).
+   * Can be used simultaneously with `cookies` — token sets the Authorization header
+   * while cookies sets the Cookie header.
+   */
+  token?: string;
+}
+
 /**
  * Test helper
  */
@@ -176,13 +195,28 @@ export class TestHelper {
   /**
    * Download file from URL
    * To compare content data via string comparison
+   * @param url - URL to download from
+   * @param tokenOrOptions - Bearer token string, or {@link TestDownloadOptions} with `cookies` and/or `token`
    * @return Superagent response with additional data field containing the content of the file
    */
-  download(url: string, token?: string): Promise<any> {
+  download(url: string, tokenOrOptions?: string | TestDownloadOptions): Promise<any> {
     return new Promise((resolve, reject) => {
       const request = supertest((this.app as INestApplication).getHttpServer()).get(url);
-      if (token) {
-        request.set('Authorization', `bearer ${token}`);
+      if (typeof tokenOrOptions === 'string') {
+        request.set('Authorization', `bearer ${tokenOrOptions}`);
+      } else if (tokenOrOptions) {
+        if (tokenOrOptions.cookies) {
+          const cookieRecord = TestHelper.buildBetterAuthCookies(tokenOrOptions.cookies);
+          request.set(
+            'Cookie',
+            Object.entries(cookieRecord)
+              .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+              .join('; '),
+          );
+        }
+        if (tokenOrOptions.token) {
+          request.set('Authorization', `bearer ${tokenOrOptions.token}`);
+        }
       }
       let data = '';
       request
@@ -207,12 +241,27 @@ export class TestHelper {
   /**
    * Download file from URL and get buffer
    * To compare content data via buffer comparison and with the possibility to save the file
+   * @param url - URL to download from
+   * @param tokenOrOptions - Bearer token string, or {@link TestDownloadOptions} with `cookies` and/or `token`
    */
-  downloadBuffer(url: string, token?: string): Promise<Buffer> {
+  downloadBuffer(url: string, tokenOrOptions?: string | TestDownloadOptions): Promise<Buffer> {
     return new Promise((resolve, reject) => {
       const request = supertest(this.app.getHttpServer()).get(url);
-      if (token) {
-        request.set('Authorization', `bearer ${token}`);
+      if (typeof tokenOrOptions === 'string') {
+        request.set('Authorization', `bearer ${tokenOrOptions}`);
+      } else if (tokenOrOptions) {
+        if (tokenOrOptions.cookies) {
+          const cookieRecord = TestHelper.buildBetterAuthCookies(tokenOrOptions.cookies);
+          request.set(
+            'Cookie',
+            Object.entries(cookieRecord)
+              .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+              .join('; '),
+          );
+        }
+        if (tokenOrOptions.token) {
+          request.set('Authorization', `bearer ${tokenOrOptions.token}`);
+        }
       }
 
       // Array to store the data chunks