@lenne.tech/nest-server 11.21.1 → 11.21.3

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