@lenne.tech/nest-server 11.34.0 → 11.35.0

package/src/core.module.ts

@@ -8,6 +8,10 @@ import graphqlUploadExpress = require('graphql-upload/graphqlUploadExpress.js');
 import mongoose from 'mongoose';
 
 import { merge } from './core/common/helpers/config.helper';
+import {
+  buildRequestContextAwareExecute,
+  buildRequestContextAwareSubscribe,
+} from './core/common/helpers/graphql-ws-context.helper';
 import { CheckResponseInterceptor } from './core/common/interceptors/check-response.interceptor';
 import { CheckSecurityInterceptor } from './core/common/interceptors/check-security.interceptor';
 import { ResponseModelInterceptor } from './core/common/interceptors/response-model.interceptor';
@@ -31,6 +35,7 @@ import { mongooseIdPlugin } from './core/common/plugins/mongoose-id.plugin';
 import { mongooseAuditFieldsPlugin } from './core/common/plugins/mongoose-audit-fields.plugin';
 import { mongoosePasswordPlugin } from './core/common/plugins/mongoose-password.plugin';
 import { mongooseRoleGuardPlugin } from './core/common/plugins/mongoose-role-guard.plugin';
+import { mongooseSystemRolePlugin } from './core/common/plugins/mongoose-system-role.plugin';
 import { mongooseTenantPlugin } from './core/common/plugins/mongoose-tenant.plugin';
 import { ConfigService } from './core/common/services/config.service';
 import { CoreCronJobsInitializer } from './core/common/services/core-cron-jobs.initializer';
@@ -46,7 +51,7 @@ import { CoreBetterAuthUserMapper } from './core/modules/better-auth/core-better
 import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-auth.module';
 import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
-import { applyFileRoles } from './core/modules/file/file-roles.helper';
+import { applyFileRoles, warnOnPresignedDownloadsWithRestrictedRoles } from './core/modules/file/file-roles.helper';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 import { CoreHubModule } from './core/modules/hub/core-hub.module';
 import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config.helper';
@@ -253,6 +258,12 @@ export class CoreModule implements NestModule {
       if (config.security?.mongooseRoleGuardPlugin !== false) {
         connection.plugin(mongooseRoleGuardPlugin);
       }
+      // Refuse to store system roles (s_*) in a roles array. Deliberately NOT configurable and
+      // registered independently of the role guard above: that one decides WHO may change roles
+      // (and can be switched off), this one decides WHICH values may exist at all. A stored
+      // 's_self' satisfies every S_SELF check on arbitrary users, so there is no configuration
+      // under which writing one is legitimate.
+      connection.plugin(mongooseSystemRolePlugin);
       // Add audit fields plugin (enabled by default, opt-out via config)
       if (config.security?.mongooseAuditFieldsPlugin !== false) {
         connection.plugin(mongooseAuditFieldsPlugin);
@@ -273,6 +284,11 @@ export class CoreModule implements NestModule {
     // function and opt out of this; see applyFileRoles() for why.
     applyFileRoles(config.file);
 
+    // Presigned downloads hand out a bearer URL that ignores roles after it is issued, so pairing
+    // them with a restricted downloadRoles is usually an oversight. Warn rather than fail — the
+    // combination has legitimate uses, it just should not be reached by accident.
+    warnOnPresignedDownloadsWithRestrictedRoles(config.s3, config.file);
+
     // Check secrets
     const jwtConfig = config.jwt;
     if (jwtConfig?.secret && jwtConfig.secret && jwtConfig.refresh && jwtConfig.refresh.secret === jwtConfig.secret) {
@@ -593,6 +609,21 @@ export class CoreModule implements NestModule {
             cors,
             installSubscriptionHandlers: true,
             subscriptions: {
+              // WEBSOCKET REQUEST CONTEXT. `GqlSubscriptionService` destructures `execute` /
+              // `subscribe` from its own options and hands them to BOTH WS transports, so these two
+              // are the only place where a whole WS operation is reachable as one call. They must sit
+              // INSIDE `subscriptions`: `ApolloDriver.start()` forwards only
+              // `{ schema, path, context, ...options.subscriptions }`, so a top-level pair is
+              // silently dropped.
+              //
+              // Without them a WS operation runs with NO `RequestContext` at all — no Express
+              // middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a
+              // subscription context — and `mongooseTenantPlugin` reads "no context" as "system
+              // operation, no filter". A tenant-scoped read while delivering a subscription message
+              // therefore returned EVERY tenant's rows, with the plugin's safety net unable to
+              // notice. HTTP does not pass through these (Apollo runs its own pipeline).
+              execute: buildRequestContextAwareExecute(),
+              subscribe: buildRequestContextAwareSubscribe(),
               'graphql-ws': {
                 context: ({ extra }) => extra,
                 onConnect: async (context: Context<any, any>) => {
@@ -688,6 +719,21 @@ export class CoreModule implements NestModule {
             cors,
             installSubscriptionHandlers: true,
             subscriptions: {
+              // WEBSOCKET REQUEST CONTEXT. `GqlSubscriptionService` destructures `execute` /
+              // `subscribe` from its own options and hands them to BOTH WS transports, so these two
+              // are the only place where a whole WS operation is reachable as one call. They must sit
+              // INSIDE `subscriptions`: `ApolloDriver.start()` forwards only
+              // `{ schema, path, context, ...options.subscriptions }`, so a top-level pair is
+              // silently dropped.
+              //
+              // Without them a WS operation runs with NO `RequestContext` at all — no Express
+              // middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a
+              // subscription context — and `mongooseTenantPlugin` reads "no context" as "system
+              // operation, no filter". A tenant-scoped read while delivering a subscription message
+              // therefore returned EVERY tenant's rows, with the plugin's safety net unable to
+              // notice. HTTP does not pass through these (Apollo runs its own pipeline).
+              execute: buildRequestContextAwareExecute(),
+              subscribe: buildRequestContextAwareSubscribe(),
               'graphql-ws': {
                 context: ({ extra }) => extra,
                 onConnect: async (context: Context<any, any>) => {
@@ -800,6 +846,21 @@ export class CoreModule implements NestModule {
             cors,
             installSubscriptionHandlers: true,
             subscriptions: {
+              // WEBSOCKET REQUEST CONTEXT. `GqlSubscriptionService` destructures `execute` /
+              // `subscribe` from its own options and hands them to BOTH WS transports, so these two
+              // are the only place where a whole WS operation is reachable as one call. They must sit
+              // INSIDE `subscriptions`: `ApolloDriver.start()` forwards only
+              // `{ schema, path, context, ...options.subscriptions }`, so a top-level pair is
+              // silently dropped.
+              //
+              // Without them a WS operation runs with NO `RequestContext` at all — no Express
+              // middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a
+              // subscription context — and `mongooseTenantPlugin` reads "no context" as "system
+              // operation, no filter". A tenant-scoped read while delivering a subscription message
+              // therefore returned EVERY tenant's rows, with the plugin's safety net unable to
+              // notice. HTTP does not pass through these (Apollo runs its own pipeline).
+              execute: buildRequestContextAwareExecute(),
+              subscribe: buildRequestContextAwareSubscribe(),
               'graphql-ws': {
                 context: ({ extra }) => extra,
                 onConnect: async (context: Context<any, any>) => {

package/src/index.ts

@@ -81,6 +81,7 @@ export * from './core/common/plugins/mongoose-id.plugin';
 export * from './core/common/plugins/mongoose-audit-fields.plugin';
 export * from './core/common/plugins/mongoose-password.plugin';
 export * from './core/common/plugins/mongoose-role-guard.plugin';
+export * from './core/common/plugins/mongoose-system-role.plugin';
 export * from './core/common/plugins/mongoose-tenant.plugin';
 export * from './core/common/scalars/any.scalar';
 export * from './core/common/scalars/date-timestamp.scalar';
@@ -176,6 +177,7 @@ export * from './core/modules/file/core-file-info.model';
 export * from './core/modules/file/core-file.controller';
 export * from './core/modules/file/core-file.resolver';
 export * from './core/modules/file/core-file.service';
+export * from './core/modules/file/file-access.helper';
 export * from './core/modules/file/file-roles.helper';
 export * from './core/modules/file/file-storage.helper';
 export * from './core/modules/file/filesystem-file.helper';
@@ -236,6 +238,7 @@ export * from './core/modules/tenant/core-tenant-member.model';
 export * from './core/modules/tenant/core-tenant.decorators';
 export * from './core/modules/tenant/core-tenant.enums';
 export * from './core/modules/tenant/core-tenant.guard';
+export * from './core/modules/tenant/core-role-scope.registry';
 export * from './core/modules/tenant/core-tenant.helpers';
 export * from './core/modules/tenant/core-tenant.module';
 export * from './core/modules/tenant/core-tenant.service';

package/src/server/modules/file/file.service.ts

@@ -98,12 +98,28 @@ export class FileService extends CoreFileService {
    * See `src/core/modules/file/README.md` § Access control, and
    * `tests/file-ownership.e2e-spec.ts` for the end-to-end contract test.
    */
+  /**
+   * NOTE FOR CONSUMERS: since 11.35.0 you may not need any of this.
+   *
+   * `file.access: 'owner'` is exactly the rule below, shipped by the framework — including the parts
+   * that are easy to get wrong (fail closed without a user, require the owner field to be PRESENT,
+   * cover the by-name branch, refuse a listing) and including the metadata stamping, which this project
+   * does by hand in `AvatarController`. `'tenant'` is the same rule against
+   * `metadata.tenantId` and the validated `RequestContext` tenant.
+   *
+   * This override stays because the reference server has to EXERCISE the seam — a rule that lives only
+   * in a preset proves the preset works, never that the inheritance point a consuming project extends
+   * still does. Keep it here; in your own project, prefer the preset unless your rights are something
+   * the framework cannot guess (an explicit read right, a case assignment, a published flag).
+   */
   protected override async checkRights(
     input: any,
     options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): Promise<boolean> {
-    // Writes, list queries and forced (system) calls stay on the coarse role gate.
-    if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
+    // Forced (system) calls and WRITES stay on the coarse role gate. Writes deliberately so: an
+    // upload has no owner to compare against yet — `AvatarController` records `metadata.ownerId` as
+    // it writes — so the only meaningful gate there is `file.uploadRoles`.
+    if (options?.force || options?.checkInputType === 'file' || options?.checkInputType === 'files') {
       return true;
     }
 
@@ -111,6 +127,33 @@ export class FileService extends CoreFileService {
       return true;
     }
 
+    // A LISTING cannot be narrowed by this hook, so it is refused rather than waved through.
+    //
+    // The hook is asked ONCE for the whole query, not once per row, so there is no answer here that
+    // means "…but only their own files". Returning `true` — which this rule used to do, and which is
+    // therefore the shape projects copied — hands a non-admin a full inventory of every upload the
+    // moment a project surfaces `findFileInfo()`: `CoreFileInfo` carries `filename`, `length`,
+    // `uploadDate` and the `id`, and for medical data the filename frequently IS the content.
+    //
+    // A project that wants "my files" FORCES the constraint server-side and passes `force: true`:
+    //
+    //   this.fileService.findFileInfo(
+    //     { filterQuery: { 'metadata.ownerId': String(currentUser.id) } },
+    //     { force: true },
+    //   );
+    //
+    // Note what that is NOT: it does not inspect the caller's `filterArgs` to check whether they are
+    // already narrowed. `filterArgs` is CLIENT-CONTROLLED, so approving a filter shape means
+    // validating attacker input — and any such check is one filter shape away from being wrong.
+    // Override the filter; never approve it. See tests/file-ownership.e2e-spec.ts.
+    // Explicit, even though falling through would ALSO deny: with `checkInputType: 'filterArgs'` the
+    // `input` is a FilterArgs object, so the by-name raw lookup below answers null and the comparison
+    // fails. That is an accident of the fall-through, not a decision — it would flip the moment a
+    // project's own raw lookup behaved differently for a non-string input. Say it outright instead.
+    if (options.checkInputType === 'filterArgs') {
+      return false;
+    }
+
     // The RAW document on purpose: the public getFileInfo() runs prepareOutput(), which
     // strips `metadata` — the very field this decision rests on.
     const raw =

package/src/test/test.helper.ts

@@ -92,6 +92,16 @@ export interface TestGraphQLOptions {
    */
   cookies?: Record<string, string> | string;
 
+  /**
+   * Additional `connectionParams` for a SUBSCRIPTION handshake.
+   *
+   * Merged on top of the `Authorization` entry derived from `token`. A WebSocket carries no HTTP
+   * headers per operation, so anything the server reads from a header on the HTTP path — the tenant
+   * header above all — has to travel here instead. Without this a tenant-scoped subscription could
+   * not be tested at all.
+   */
+  connectionParams?: Record<string, string>;
+
   /**
    * Count of subscription messages, specifies how many messages are to be received on subscription
    */
@@ -788,10 +798,13 @@ export class TestHelper {
     }
 
     // Prepare subscription
-    let connectionParams;
+    let connectionParams: Record<string, string> | undefined;
     if (options?.token) {
       connectionParams = { Authorization: `Bearer ${options?.token}` };
     }
+    if (options?.connectionParams) {
+      connectionParams = { ...connectionParams, ...options.connectionParams };
+    }
 
     // Init client
     if (options.log) {
@@ -800,10 +813,27 @@ export class TestHelper {
     const client = createClient({ connectionParams, url: this.subscriptionUrl, webSocketImpl: ws });
     const messages: any[] = [];
     let unsubscribe: () => void;
+    let rejectSubscription: (reason: unknown) => void;
+
     const onNext = (message) => {
       if (options.log) {
         console.info('Subscription message', JSON.stringify(message, null, 2));
       }
+
+      // A REFUSED subscription arrives as a `next` message carrying `errors`, not through the
+      // transport's `error` callback: when a guard throws, graphql's `subscribe()` returns an
+      // ExecutionResult instead of an async iterable, and graphql-ws emits that as one payload
+      // followed by `complete`. Projecting only `data[name]` therefore turned "you may not subscribe
+      // to this" into an indistinguishable `undefined`/`null` message — so a test asserting that an
+      // unauthorized subscriber gets nothing passed just as well when the gate was wide open.
+      // Rejecting makes the refusal observable, which is what the caller actually experiences.
+      if (message?.errors?.length) {
+        const detail = message.errors.map((error: any) => error?.message ?? String(error)).join('; ');
+        rejectSubscription?.(new Error(`Subscription "${graphql.name}" failed: ${detail}`));
+        unsubscribe?.();
+        return;
+      }
+
       messages.push(message?.data?.[graphql.name]);
       if (messages.length <= options.countOfSubscriptionMessages) {
         unsubscribe();
@@ -811,16 +841,29 @@ export class TestHelper {
     };
 
     // Subscribe
-    await new Promise((resolve, reject) => {
-      unsubscribe = client.subscribe(
-        { query },
-        {
-          complete: resolve as any,
-          error: reject,
-          next: onNext,
-        },
-      );
-    });
+    //
+    // Disposed in `finally`, including on the refusal path: without it the client keeps its socket
+    // (and graphql-ws its reconnect timer) open past the end of the test, which surfaces later as a
+    // hanging process or as an error attributed to whichever test happened to run next.
+    try {
+      await new Promise((resolve, reject) => {
+        rejectSubscription = reject;
+        unsubscribe = client.subscribe(
+          { query },
+          {
+            complete: resolve as any,
+            error: reject,
+            next: onNext,
+          },
+        );
+      });
+    } finally {
+      try {
+        await client.dispose?.();
+      } catch {
+        // Already closing — nothing to clean up, and a teardown error must not mask the result.
+      }
+    }
 
     // Return subscribed messages
     return messages;