@lenne.tech/nest-server 11.21.2 → 11.21.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.21.2",
+  "version": "11.21.3",
   "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",

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -1019,32 +1019,36 @@ export class CoreBetterAuthUserMapper {
       const migrationPercentage = totalUsers > 0 ? Math.round((fullyMigratedUsers / totalUsers) * 100 * 100) / 100 : 0;
 
       // Get emails of pending users (limit to 100)
-      const pendingUsers = await usersCollection
-        .aggregate([
-          {
-            $lookup: {
-              as: 'accounts',
-              foreignField: 'userId',
-              from: 'account',
-              localField: '_id',
-            },
-          },
-          {
-            $match: {
-              $or: [
-                { iamId: { $exists: false } },
-                { iamId: null },
-                {
-                  $and: [{ iamId: { $exists: true, $ne: null } }, { 'accounts.providerId': { $ne: 'credential' } }],
-                },
-              ],
-            },
-          },
-          { $limit: 100 },
-          { $project: { email: 1 } },
-        ])
+      // Two-phase approach: first get users without iamId (no $lookup needed),
+      // then check users with iamId but missing credential account
+      const usersWithoutIamId = await usersCollection
+        .find({ $or: [{ iamId: { $exists: false } }, { iamId: null }] })
+        .limit(100)
+        .project({ email: 1 })
         .toArray();
-      const pendingUserEmails = pendingUsers.map((u) => u.email).filter(Boolean);
+
+      const remaining = 100 - usersWithoutIamId.length;
+      let usersWithIamButNoAccount: { email?: string }[] = [];
+      if (remaining > 0) {
+        usersWithIamButNoAccount = await usersCollection
+          .aggregate([
+            { $match: { iamId: { $exists: true, $ne: null } } },
+            {
+              $lookup: {
+                as: 'accounts',
+                foreignField: 'userId',
+                from: 'account',
+                localField: '_id',
+              },
+            },
+            { $match: { 'accounts.providerId': { $ne: 'credential' } } },
+            { $limit: remaining },
+            { $project: { email: 1 } },
+          ])
+          .toArray();
+      }
+
+      const pendingUserEmails = [...usersWithoutIamId, ...usersWithIamButNoAccount].map((u) => u.email).filter(Boolean);
 
       // Can disable legacy auth only if ALL users are fully migrated
       const canDisableLegacyAuth = totalUsers > 0 && fullyMigratedUsers === totalUsers;

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -88,15 +88,19 @@ export class CoreBetterAuthService implements OnModuleInit {
     try {
       const db = this.connection.db;
 
-      // Session collection: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
-      await db.collection('session').createIndex({ token: 1 });
-      await db.collection('session').createIndex({ userId: 1, expiresAt: 1 });
-
-      // Users collection: iamId lookup (mapSessionUser uses $or with email and iamId)
-      // email is typically already indexed by Mongoose schema, but iamId may not be
-      await db.collection('users').createIndex({ iamId: 1 }, { sparse: true });
-
-      this.logger.debug('Performance indices ensured on session and users collections');
+      // All indices are idempotent (no-op if already exists) and independent — run in parallel
+      await Promise.all([
+        // Session: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
+        db.collection('session').createIndex({ token: 1 }),
+        db.collection('session').createIndex({ userId: 1, expiresAt: 1 }),
+        // Users: iamId lookup (mapSessionUser uses $or with email and iamId)
+        db.collection('users').createIndex({ iamId: 1 }, { sparse: true }),
+        // Account: userId lookup ($lookup in getMigrationStatus) and providerId filtering
+        db.collection('account').createIndex({ userId: 1 }),
+        db.collection('account').createIndex({ providerId: 1, userId: 1 }),
+      ]);
+
+      this.logger.debug('Performance indices ensured on session, users, and account collections');
     } catch (error) {
       // Non-fatal: indices improve performance but are not required for correctness
       this.logger.warn(`Could not create performance indices: ${error instanceof Error ? error.message : 'unknown'}`);

package/src/core/modules/tenant/INTEGRATION-CHECKLIST.md

@@ -121,7 +121,18 @@ Normal (non-hierarchy) roles also work:
 async viewAuditLog(...) { ... }
 ```
 
-### 8. Skip Tenant Check for Non-Tenant Endpoints
+### 8. System Roles as OR Alternatives
+
+System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives **before** real role checks in `CoreTenantGuard`. If a system role grants access, real roles in the same `@Roles()` are alternatives, not requirements.
+
+When `X-Tenant-Id` header is present and a system role grants access:
+
+- `S_EVERYONE`: public — membership is optionally enriched but never blocks
+- `S_USER`/`S_VERIFIED`: membership is validated (403 if not a member; admin bypass applies)
+
+`@SkipTenantCheck()` suppresses membership validation for `S_USER`/`S_VERIFIED` paths — authentication/verification is still enforced, but no membership check runs even with a header present.
+
+### 9. Skip Tenant Check for Non-Tenant Endpoints
 
 Use `@SkipTenantCheck()` for endpoints that intentionally work without tenant context:
 
@@ -133,7 +144,7 @@ import { SkipTenantCheck, Roles, RoleEnum } from '@lenne.tech/nest-server';
 async listMyTenants() { ... }
 ```
 
-### 9. BetterAuth (IAM) Coexistence
+### 10. BetterAuth (IAM) Coexistence
 
 When both `multiTenancy` and `betterAuth` are active, IAM endpoints (sign-in, sign-up, session, etc.)
 automatically skip tenant validation when no `X-Tenant-Id` header is sent (`betterAuth.skipTenantCheck: true`, default).

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

@@ -138,9 +138,33 @@ Roles not in `roleHierarchy` use exact match — no higher role can compensate:
 async auditLog(@CurrentTenant() tenantId: string) { ... }
 ```
 
+### System Roles as OR Alternatives
+
+When `@Roles()` includes system roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`), `CoreTenantGuard` checks them **before** real roles in priority order. If a system role is satisfied, access is granted immediately — real roles in the same decorator are OR alternatives, not additional requirements.
+
+```typescript
+@Roles(RoleEnum.ADMIN)    // Class: admin can always access all methods
+@Controller('users')
+class UserController {
+  @Roles(RoleEnum.S_USER)  // Method: any authenticated user (extends class ADMIN via OR)
+  getProfile() { ... }     // → admin OR authenticated user can access
+
+  @Roles(RoleEnum.S_EVERYONE) // Method: public endpoint (extends class ADMIN via OR)
+  getPublicInfo() { ... }     // → anyone can access
+}
+```
+
+**Method-level system roles take precedence** for the system role check. Class `@Roles(S_EVERYONE)` does not make a method `@Roles(S_USER)` endpoint public — the method's `S_USER` applies.
+
+| System Role | No Header             | Header Present                                     |
+| ----------- | --------------------- | -------------------------------------------------- |
+| S_EVERYONE  | Pass (public)         | Pass + optional tenant context enrichment          |
+| S_USER      | Pass if authenticated | Pass if authenticated member; admin bypass applies |
+| S_VERIFIED  | Pass if verified      | Pass if verified member; admin bypass applies      |
+
 ### Tenant Context Rule
 
-**When a tenant header is present:** Only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass).
+**When a tenant header is present:** For real role checks, only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass). For system role checks (`S_USER`, `S_VERIFIED`), membership is validated to set tenant context (`tenantId`, `tenantRole`), but access depends on membership existence, not role level.
 
 **When no tenant header:** `user.roles` is checked instead. Hierarchy roles use level comparison, normal roles use exact match.
 
@@ -161,6 +185,7 @@ async listMyTenants() { ... }
 ```
 
 Note: `@SkipTenantCheck()` with hierarchy roles still checks `user.roles` (no tenant context).
+It also suppresses tenant membership validation for `S_USER`/`S_VERIFIED` system role paths — when set, these roles still enforce authentication/verification but skip the membership check even when a tenant header is present.
 
 ### Admin Bypass
 

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/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