@lenne.tech/nest-server 11.43.2 → 12.0.0

package/src/core/common/scalars/upload.scalar.ts

@@ -0,0 +1,23 @@
+import type { GraphQLScalarType } from 'graphql';
+import GraphQLUploadScalar from 'graphql-upload/GraphQLUpload.js';
+
+/**
+ * The GraphQL `Upload` scalar for multipart file uploads — import it from `@lenne.tech/nest-server`,
+ * not from `graphql-upload`.
+ *
+ * The scalar accepts a value only if it is `instanceof Upload` of ITS copy of graphql-upload, and the
+ * `Upload` instances come from the multipart middleware `CoreModule` installs, i.e. from THIS package's
+ * copy. A resolver that imports the scalar from the project's own graphql-upload therefore works only
+ * while both resolve to the same version; with two copies every upload is refused as invalid. And the
+ * import path itself is not stable across graphql-upload majors (15: `GraphQLUpload.js`, 16+:
+ * `GraphQLUpload.mjs`). Importing it from here keeps scalar and middleware one copy and leaves the
+ * path to the framework.
+ *
+ * The path is a CONTRACT with the lt CLI: its generator checks whether `common/scalars/upload.scalar` exists in
+ * the framework root (`dist/core/` in npm mode, `src/core/` vendored) and only then writes
+ * `import { GraphQLUpload } from '<framework>'` for a File/FileInfo input; otherwise it falls back to
+ * `import GraphQLUpload = require('graphql-upload/GraphQLUpload.js')`. Moving or renaming this file, or dropping
+ * the re-export from `src/index.ts`, silently sends every newly generated resolver back to the project's own
+ * graphql-upload copy. Pinned by `tests/unit/upload-scalar-contract.spec.ts`.
+ */
+export const GraphQLUpload: GraphQLScalarType = GraphQLUploadScalar;

package/src/core/common/services/brevo.service.ts

@@ -1,9 +1,35 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
 
-import type { Brevo, BrevoClient } from '@getbrevo/brevo';
+import { ConfigService } from './config.service.js';
 
-import { ConfigService } from './config.service';
+/**
+ * The SDK as the lazy `import()` in {@link BrevoService.getClient} resolves it.
+ *
+ * Derived from the import EXPRESSION on purpose: TypeScript types an `import()` the way it is emitted —
+ * the ESM build under `module: nodenext` (this repo; a native `import()`), the CJS build under
+ * `module: commonjs` (a vendor project's tsconfig; rewritten to `require()`). A plain `import type`
+ * resolves this file's own format instead, and `BrevoClient` has private members, so one build's class
+ * is not assignable to the other's: whichever fixed choice is written breaks the other configuration.
+ */
+const loadBrevoSdk = () => import('@getbrevo/brevo');
+type BrevoClient = InstanceType<Awaited<ReturnType<typeof loadBrevoSdk>>['BrevoClient']>;
+type SendTransacEmailRequest = Parameters<BrevoClient['transactionalEmails']['sendTransacEmail']>[0];
+
+/**
+ * The part of the Brevo SDK client `BrevoService` calls — the return type of the overridable
+ * {@link BrevoService.getClient}.
+ *
+ * Structural on purpose. The SDK's `BrevoClient` class differs between its CJS and ESM builds, and
+ * which one the lazy import loads depends on the consumer's `module` setting, so neither can be named
+ * in this package's declarations (TS2883 under `module: commonjs`). Either build's client satisfies
+ * this, and so does a test double.
+ */
+export interface IBrevoSdkClient {
+  transactionalEmails: {
+    sendTransacEmail(request: object): Promise<unknown>;
+  };
+}
 
 /**
  * Brevo service to send transactional emails
@@ -59,7 +85,7 @@ export class BrevoService {
       }
 
       // Prepare data
-      const request: Brevo.SendTransacEmailRequest = {
+      const request: SendTransacEmailRequest = {
         headers: this.buildIdempotencyHeaders(),
         // The public signature keeps the wider `object` so existing callers stay source-compatible;
         // the SDK narrowed its own field to an index-signature type in v6.
@@ -103,7 +129,7 @@ export class BrevoService {
       }
 
       // Prepare data
-      const request: Brevo.SendTransacEmailRequest = {
+      const request: SendTransacEmailRequest = {
         headers: this.buildIdempotencyHeaders(),
         htmlContent: html,
         params: options?.params,
@@ -172,9 +198,9 @@ export class BrevoService {
    *
    * @returns The memoised SDK client
    */
-  protected async getClient(): Promise<BrevoClient> {
+  protected async getClient(): Promise<IBrevoSdkClient> {
     if (!this.client) {
-      const { BrevoClient: BrevoClientCtor } = await import('@getbrevo/brevo');
+      const { BrevoClient: BrevoClientCtor } = await loadBrevoSdk();
       this.client = new BrevoClientCtor({
         apiKey: this.brevoConfig.apiKey,
         // The SDK defaults to 2 retries honouring `Retry-After` with a 60 s cap PER attempt, and to

package/src/core/common/services/config.service.ts

@@ -1,14 +1,13 @@
-import { cloneDeep } from 'lodash';
-import _ = require('lodash');
+import _ from 'lodash';
 import { BehaviorSubject, firstValueFrom } from 'rxjs';
 import { filter, map } from 'rxjs/operators';
 
-import { merge } from '../helpers/config.helper';
+import { merge } from '../helpers/config.helper.js';
 // Import from the clone.helper LEAF, never from input.helper: input.helper imports
 // restricted.decorator, which reaches back here via core-tenant.helpers — that cycle is what the
 // extraction removed. See clone.helper's docblock.
-import { clone, deepFreeze } from '../helpers/clone.helper';
-import { IServerOptions } from '../interfaces/server-options.interface';
+import { clone, deepFreeze } from '../helpers/clone.helper.js';
+import { IServerOptions } from '../interfaces/server-options.interface.js';
 
 /**
  * Config service can be used as provider (after initialization in CoreModule.forRoot)
@@ -61,6 +60,11 @@ export class ConfigService {
 
   /**
    * Create config service or return singleton instance if exists
+   *
+   * `warn: true` prints the whole merged configuration when this is a second construction — a debugging
+   * aid, and an opt-in since 12.0.0 like it always was for `setConfig()` / `mergeConfig()`. As the default it
+   * wrote every secret in the config (JWT and Better-Auth secrets, database and Redis URIs, API keys) to
+   * stdout whenever `CoreModule.forRoot()` ran a second time in one process: tests, scripts, a second app.
    */
   constructor(
     configObject?: Partial<IServerOptions> & { [key: string]: any },
@@ -68,7 +72,7 @@ export class ConfigService {
   ) {
     const config = {
       reInit: false,
-      warn: true,
+      warn: false,
       ...options,
     };
 
@@ -78,7 +82,7 @@ export class ConfigService {
     // Init subject handling
     if (!isInitialized) {
       ConfigService._configSubject$.subscribe((value) => {
-        ConfigService._frozenConfigSubject$.next(deepFreeze(cloneDeep(value)));
+        ConfigService._frozenConfigSubject$.next(deepFreeze(_.cloneDeep(value)));
       });
     }
 
@@ -271,7 +275,7 @@ export class ConfigService {
 
     // Merge config
     const activity = isInitialized ? 'merged' : 'initialized';
-    const merged = merge(ConfigService._configSubject$.getValue() || {}, cloneDeep(configData));
+    const merged = merge(ConfigService._configSubject$.getValue() || {}, _.cloneDeep(configData));
     ConfigService._configSubject$.next(merged);
 
     // Warn if requested
@@ -307,7 +311,7 @@ export class ConfigService {
     // Merge property
     const current = ConfigService._configSubject$.getValue() || {};
     if (typeof value === 'object') {
-      current[key] = merge(current[key], cloneDeep(value));
+      current[key] = merge(current[key], _.cloneDeep(value));
     } else {
       current[key] = value;
     }

package/src/core/common/services/core-body-parser.initializer.ts

@@ -2,9 +2,9 @@ import { Injectable, Logger, OnModuleInit, Optional, PayloadTooLargeException }
 import { HttpAdapterHost, ModuleRef } from '@nestjs/core';
 import { json, urlencoded } from 'express';
 
-import { ErrorCode } from '../../modules/error-code/error-codes';
-import { IBodyParserConfig } from '../interfaces/server-options.interface';
-import { ConfigService } from './config.service';
+import { ErrorCode } from '../../modules/error-code/error-codes.js';
+import { IBodyParserConfig } from '../interfaces/server-options.interface.js';
+import { ConfigService } from './config.service.js';
 
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 

package/src/core/common/services/core-cron-jobs.initializer.ts

@@ -1,9 +1,9 @@
 import { Injectable, OnApplicationShutdown, OnModuleInit, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
-import { Connection } from 'mongoose';
+import type { Connection } from 'mongoose';
 
-import { setCronJobsInfrastructure } from './core-cron-jobs.registry';
-import { CoreRedisService } from './core-redis.service';
+import { setCronJobsInfrastructure } from './core-cron-jobs.registry.js';
+import { CoreRedisService } from './core-redis.service.js';
 
 /**
  * Populates the cron-jobs infrastructure registry at bootstrap so that

package/src/core/common/services/core-cron-jobs.registry.ts

@@ -16,7 +16,7 @@
  * so a registration that happens after the service was constructed still takes effect.
  */
 
-import type { CoreRedisService } from './core-redis.service';
+import type { CoreRedisService } from './core-redis.service.js';
 import type { Connection } from 'mongoose';
 
 export interface CronJobsInfrastructure {

package/src/core/common/services/core-cron-jobs.service.ts

@@ -1,16 +1,26 @@
-import { OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
+import { Logger, OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
 import { CronExpression, SchedulerRegistry } from '@nestjs/schedule';
 import { CronJob } from 'cron';
 
-import { CronJobConfigWithTimeZone } from '../interfaces/cron-job-config-with-time-zone.interface';
-import { CronJobConfigWithUtcOffset } from '../interfaces/cron-job-config-with-utc-offset.interface';
-import { Falsy } from '../types/falsy.type';
-import { getCronJobsInfrastructure } from './core-cron-jobs.registry';
+import { CronJobConfigWithTimeZone } from '../interfaces/cron-job-config-with-time-zone.interface.js';
+import { CronJobConfigWithUtcOffset } from '../interfaces/cron-job-config-with-utc-offset.interface.js';
+import { Falsy } from '../types/falsy.type.js';
+import { getCronJobsInfrastructure } from './core-cron-jobs.registry.js';
 
-import type { CoreRedisService } from './core-redis.service';
+import type { CoreRedisService } from './core-redis.service.js';
 import type { Redis } from 'ioredis';
 import type { Connection } from 'mongoose';
 
+/**
+ * One logger for every cron message, through Nest's logger so levels, JSON mode and a project's custom logger apply.
+ * Module-level rather than a class member on purpose: a project `CronJobs extends CoreCronJobs` that declares its
+ * own `logger` field (a common shape) would otherwise stop compiling.
+ */
+const cronLogger = new Logger('CronJobs');
+
+const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+const errorStack = (error: unknown): string | undefined => (error instanceof Error ? error.stack : undefined);
+
 /**
  * Collection holding the per-tick cron leases.
  *
@@ -137,7 +147,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
    */
   async onApplicationBootstrap(): Promise<void> {
     if (this.config.log) {
-      console.info('Init CronJobs after application bootstrap');
+      cronLogger.log('Init CronJobs after application bootstrap');
     }
     await this.initCronJobs();
   }
@@ -154,7 +164,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     const results = await Promise.allSettled([this.bullWorker?.close(), this.bullQueue?.close()]);
     for (const result of results) {
       if (result.status === 'rejected') {
-        console.error('BullMQ shutdown failed', result.reason);
+        cronLogger.error(`BullMQ shutdown failed: ${errorMessage(result.reason)}`, errorStack(result.reason));
       }
     }
     this.bullWorker = undefined;
@@ -217,7 +227,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
       // check if cron job exists
       if (!this[name]) {
         if (this.config.log) {
-          console.info(`Missing cron job function ${name}`);
+          cronLogger.warn(`Missing cron job function ${name}`);
         }
         continue;
       }
@@ -232,7 +242,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
           bullScheduled.add(name);
           continue;
         }
-        console.debug(
+        cronLogger.debug(
           `CronJob ${name} cannot be expressed as BullMQ scheduler (${
             typeof config.cronTime === 'string' ? 'utcOffset is set' : 'cronTime is a Date'
           }), falling back to a local timer with lease`,
@@ -285,7 +295,10 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
         // DUPLICATE run, and treating an unreachable Redis as "someone else won" would
         // instead stop every scheduled job on every replica — a silent, fleet-wide outage
         // of all cron work, which is the worse failure of the two.
-        console.error(`Cron lease for ${leaseKey} failed on Redis, running the tick anyway`, e);
+        cronLogger.error(
+          `Cron lease for ${leaseKey} failed on Redis, running the tick anyway: ${errorMessage(e)}`,
+          errorStack(e),
+        );
         return true;
       }
     }
@@ -311,7 +324,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
         this.logSkippedTick(leaseKey);
         return false;
       }
-      console.error(`Cron lease for ${leaseKey} failed, running the tick anyway`, e);
+      cronLogger.error(`Cron lease for ${leaseKey} failed, running the tick anyway: ${errorMessage(e)}`, errorStack(e));
       return true;
     }
   }
@@ -328,7 +341,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
         .createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 })
         .then(() => undefined)
         .catch((e) => {
-          console.error('Could not create TTL index on cron lock collection', e);
+          cronLogger.error(`Could not create TTL index on cron lock collection: ${errorMessage(e)}`, errorStack(e));
         });
     }
     return this.leaseIndexReady;
@@ -386,10 +399,10 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     let bullmq: any;
     try {
       bullmq = await this.importBullMq();
-    } catch {
-      console.warn(
-        'Redis is configured but the optional peer dependency "bullmq" is not installed — cron jobs fall back to ' +
-          'per-tick MongoDB leases. Run: pnpm add bullmq',
+    } catch (error) {
+      cronLogger.warn(
+        `Redis is configured but the optional peer dependency "bullmq" could not be loaded (${errorMessage(error)}) — ` +
+          'cron jobs fall back to per-tick MongoDB leases. If it is missing: pnpm add bullmq',
       );
       return false;
     }
@@ -432,7 +445,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     // promise from run() and takes the fetch loop down with it — after which no replica runs
     // any job again. A transient error must stay transient.
     this.bullWorker.on('error', (error: Error) => {
-      console.error(`BullMQ cron worker error: ${error.message}`);
+      cronLogger.error(`BullMQ cron worker error: ${error.message}`, error.stack);
     });
 
     return true;
@@ -454,14 +467,14 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     if (!running()) {
       return;
     }
-    console.info(`Waiting up to ${timeoutMs}ms for ${running()} running cron job(s) to finish`);
+    cronLogger.log(`Waiting up to ${timeoutMs}ms for ${running()} running cron job(s) to finish`);
 
     while (running() && Date.now() < deadline) {
       await new Promise((resolve) => setTimeout(resolve, 100));
     }
 
     if (running()) {
-      console.warn(`${running()} cron job(s) still running after ${timeoutMs}ms — shutting down anyway`);
+      cronLogger.warn(`${running()} cron job(s) still running after ${timeoutMs}ms — shutting down anyway`);
     }
   }
 
@@ -489,12 +502,12 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
       for (const scheduler of await this.bullQueue.getJobSchedulers()) {
         if (scheduler?.key && known.has(scheduler.key) && !active.has(scheduler.key)) {
           await this.bullQueue.removeJobScheduler(scheduler.key);
-          console.info(`CronJob scheduler ${scheduler.key} removed — no longer configured`);
+          cronLogger.log(`CronJob scheduler ${scheduler.key} removed — no longer configured`);
         }
       }
     } catch (error) {
       // Reconciliation is housekeeping: a failure here must not stop the jobs from starting.
-      console.warn('Failed to reconcile BullMQ job schedulers', error);
+      cronLogger.warn(`Failed to reconcile BullMQ job schedulers: ${errorMessage(error)}`);
     }
   }
 
@@ -510,7 +523,9 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
       return;
     }
     this.bullWorker.concurrency = Math.max(1, Object.keys(this.jobConfigs).length);
-    this.bullWorker.run().catch((e: unknown) => console.error('BullMQ cron worker stopped', e));
+    this.bullWorker
+      .run()
+      .catch((e: unknown) => cronLogger.error(`BullMQ cron worker stopped: ${errorMessage(e)}`, errorStack(e)));
   }
 
   /**
@@ -518,7 +533,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
    */
   protected logSkippedTick(leaseKey: string): void {
     if (this.config.log) {
-      console.debug(`CronJob tick ${leaseKey} skipped, lease held by another replica`);
+      cronLogger.debug(`CronJob tick ${leaseKey} skipped, lease held by another replica`);
     }
   }
 
@@ -564,7 +579,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     }
 
     if (this.config.log) {
-      console.info(`CronJob ${name} initialized with "${config.cronTime}" (BullMQ scheduler)`);
+      cronLogger.log(`CronJob ${name} initialized with "${config.cronTime}" (BullMQ scheduler)`);
     }
   }
 
@@ -616,7 +631,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     ref.job = job;
     this.schedulerRegistry.addCronJob(name, job);
     if (this.config.log && this.schedulerRegistry.getCronJob(name)) {
-      console.info(`CronJob ${name} initialized with "${config.cronTime}"`);
+      cronLogger.log(`CronJob ${name} initialized with "${config.cronTime}"`);
     }
   }
 
@@ -636,7 +651,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
    */
   protected runInitTick(name: string): void {
     this.runDistributedTick(name, 'init').catch((e) => {
-      console.error(`CronJob ${name} failed on its startup run`, e);
+      cronLogger.error(`CronJob ${name} failed on its startup run: ${errorMessage(e)}`, errorStack(e));
     });
   }
 
@@ -649,7 +664,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
     if (!config) {
       // Returning quietly here is how a mis-timed BullMQ delivery got recorded as a
       // successful, completed tick. The guard stays, but it no longer stays silent.
-      console.warn(`CronJob tick for "${name}" dropped — no registered config`);
+      cronLogger.warn(`CronJob tick for "${name}" dropped — no registered config`);
       return;
     }
 
@@ -680,7 +695,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
       if (config.throwException) {
         throw e;
       } else {
-        console.error(e);
+        cronLogger.error(`CronJob ${name} failed: ${errorMessage(e)}`, errorStack(e));
       }
     }
 
@@ -696,7 +711,7 @@ export abstract class CoreCronJobs implements OnApplicationBootstrap, OnApplicat
       return;
     }
     this.dedupWarned = true;
-    console.warn(
+    cronLogger.warn(
       'Cron job deduplication is inactive: neither a Redis service nor a Mongoose connection was passed to ' +
         'CoreCronJobs. Every replica runs every tick.',
     );

package/src/core/common/services/core-redis-pubsub.ts

@@ -1,7 +1,7 @@
 import { Logger, OnModuleDestroy } from '@nestjs/common';
 import { PubSubEngine } from 'graphql-subscriptions';
 
-import type { CoreRedisService } from './core-redis.service';
+import type { CoreRedisService } from './core-redis.service.js';
 import type { Redis } from 'ioredis';
 
 /**

package/src/core/common/services/core-redis.service.ts

@@ -1,9 +1,9 @@
 import { Injectable, Logger, OnApplicationShutdown, OnModuleInit } from '@nestjs/common';
 
-import { getProjectSlug } from '../helpers/project-name.helper';
-import { ConfigService } from './config.service';
+import { getProjectSlug } from '../helpers/project-name.helper.js';
+import { ConfigService } from './config.service.js';
 
-import type { IRedisConfig } from '../interfaces/server-options.interface';
+import type { IRedisConfig } from '../interfaces/server-options.interface.js';
 import type { Redis, RedisOptions } from 'ioredis';
 
 /**

package/src/core/common/services/core-s3.service.ts

@@ -1,10 +1,10 @@
 import { Injectable, Logger, OnApplicationShutdown, OnModuleInit } from '@nestjs/common';
 import { PassThrough } from 'stream';
 
-import { buildContentDisposition } from '../helpers/content-disposition.helper';
-import { ConfigService } from './config.service';
+import { buildContentDisposition } from '../helpers/content-disposition.helper.js';
+import { ConfigService } from './config.service.js';
 
-import type { IS3Config } from '../interfaces/server-options.interface';
+import type { IS3Config } from '../interfaces/server-options.interface.js';
 import type { S3Client } from '@aws-sdk/client-s3';
 import type { Readable } from 'stream';
 
@@ -194,6 +194,20 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
     this.client = new this.sdk.S3Client({
       ...(endpoint ? { endpoint } : {}),
       forcePathStyle,
+      // Without a logger the SDK writes some warnings straight to `console` — "An error was encountered in
+      // a non-retryable streaming request." on every failed or aborted upload stream — outside the app's
+      // log levels and format. Warnings go through this service's logger instead. Everything else stays
+      // silent, exactly as with the SDK's default NoOpLogger: `info` would add one line per request, and
+      // `error` reports every failed command — including the expected 404 of an existence check, which this
+      // service already turns into a result or a meaningful error of its own.
+      logger: {
+        debug: () => undefined,
+        error: () => undefined,
+        info: () => undefined,
+        trace: () => undefined,
+        warn: (...content: unknown[]) =>
+          this.logger.warn(content.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')),
+      },
       region,
       // Fall back to the SDK default credential chain when no keys are configured
       ...(accessKeyId && secretAccessKey ? { credentials: { accessKeyId, secretAccessKey } } : {}),

package/src/core/common/services/core-tenant-context.registry.ts

@@ -16,7 +16,7 @@
  * returns `true` without deciding anything. This registry is what lets the WebSocket path ask the
  * same question through the same membership logic and cache.
  */
-import type { IRequestContext } from './request-context.service';
+import type { IRequestContext } from './request-context.service.js';
 
 /** The tenant-relevant slice of a request context — everything the Mongoose tenant plugin reads. */
 export type ResolvedTenantContext = Pick<IRequestContext, 'isAdminBypass' | 'tenantId' | 'tenantIds' | 'tenantRole'>;
@@ -28,6 +28,18 @@ export interface TenantContextResolver {
    *   validated against an active membership before it is returned
    */
   resolve(user: { id: string; roles?: string[] } | undefined, headerTenantId?: string): Promise<ResolvedTenantContext>;
+
+  /**
+   * The narrower answer `CoreTenantGuard` gives an `@Roles(S_EVERYONE)` route: a tenant only from an
+   * ACTIVE membership in the tenant the header names (in an active tenant) — no admin bypass, and no
+   * fallback to every membership when no tenant is named. For an HTTP route that authenticates its
+   * caller itself, after the guards ran without a user (the MCP endpoint and its OAuth access token),
+   * so that route scopes the request exactly as the guard would have.
+   *
+   * Optional because the interface is public. A caller finding it absent establishes no tenant, which
+   * leaves the plugin's safety net to refuse tenant-scoped reads.
+   */
+  resolveMembership?(user: { id: string; roles?: string[] }, headerTenantId?: string): Promise<ResolvedTenantContext>;
 }
 
 let resolver: TenantContextResolver | undefined;

package/src/core/common/services/core-trust-proxy.initializer.ts

@@ -1,8 +1,8 @@
 import { Injectable, Logger, OnApplicationBootstrap, OnModuleInit, Optional } from '@nestjs/common';
 import { HttpAdapterHost } from '@nestjs/core';
 
-import { IServerOptions } from '../interfaces/server-options.interface';
-import { ConfigService } from './config.service';
+import { IServerOptions } from '../interfaces/server-options.interface.js';
+import { ConfigService } from './config.service.js';
 
 /** Express setting name — the string Express itself keys the compiled trust function off */
 const TRUST_PROXY = 'trust proxy';

package/src/core/common/services/crud.service.ts

@@ -12,16 +12,16 @@ import {
   Types,
 } from 'mongoose';
 
-import { FilterArgs } from '../args/filter.args';
-import { getStringIds } from '../helpers/db.helper';
-import { convertFilterArgsToQuery } from '../helpers/filter.helper';
-import { mergePlain, prepareServiceOptionsForCreate } from '../helpers/input.helper';
-import { ServiceOptions } from '../interfaces/service-options.interface';
-import { CoreModel } from '../models/core-model.model';
-import { PaginationInfo } from '../models/pagination-info.model';
-import { PlainObject } from '../types/plain-object.type';
-import { ConfigService } from './config.service';
-import { ModuleService } from './module.service';
+import { FilterArgs } from '../args/filter.args.js';
+import { getStringIds } from '../helpers/db.helper.js';
+import { convertFilterArgsToQuery } from '../helpers/filter.helper.js';
+import { mergePlain, prepareServiceOptionsForCreate } from '../helpers/input.helper.js';
+import { ServiceOptions } from '../interfaces/service-options.interface.js';
+import { CoreModel } from '../models/core-model.model.js';
+import { PaginationInfo } from '../models/pagination-info.model.js';
+import { PlainObject } from '../types/plain-object.type.js';
+import { ConfigService } from './config.service.js';
+import { ModuleService } from './module.service.js';
 
 export abstract class CrudService<
   Model extends CoreModel = any,

package/src/core/common/services/email.service.ts

@@ -1,15 +1,16 @@
 import { createHash } from 'crypto';
 import { Inject, Injectable, Logger, OnModuleDestroy, Optional } from '@nestjs/common';
-import nodemailer = require('nodemailer');
-import { Attachment } from 'nodemailer/lib/mailer';
-
-import { isImpossibleSmtpTlsCombination } from '../helpers/config.helper';
-import { isNonEmptyString, isTrue, returnFalse } from '../helpers/input.helper';
-import { MailTransportOptions } from '../interfaces/server-options.interface';
-import { HUB_EMAIL_CAPTURE } from '../../modules/hub/hub.constants';
-import { ConfigService } from './config.service';
-import { TemplateService } from './template.service';
-import type { IHubEmailCapture } from '../../modules/hub/interfaces/hub-config.interface';
+import { createTransport } from 'nodemailer';
+import type { Transporter } from 'nodemailer';
+import type { Attachment } from 'nodemailer/lib/mailer';
+
+import { isImpossibleSmtpTlsCombination } from '../helpers/config.helper.js';
+import { isNonEmptyString, isTrue, returnFalse } from '../helpers/input.helper.js';
+import { MailTransportOptions } from '../interfaces/server-options.interface.js';
+import { HUB_EMAIL_CAPTURE } from '../../modules/hub/hub.constants.js';
+import { ConfigService } from './config.service.js';
+import { TemplateService } from './template.service.js';
+import type { IHubEmailCapture } from '../../modules/hub/interfaces/hub-config.interface.js';
 
 /**
  * Email service
@@ -20,7 +21,7 @@ export class EmailService implements OnModuleDestroy {
    * Cached transporter to avoid creating new SMTP connections per email.
    * Reused as long as the SMTP config hasn't changed.
    */
-  private cachedTransporter: nodemailer.Transporter | null = null;
+  private cachedTransporter: Transporter | null = null;
   private cachedSmtpConfig: string | null = null;
 
   protected readonly emailServiceLogger = new Logger(EmailService.name);
@@ -185,7 +186,7 @@ export class EmailService implements OnModuleDestroy {
     // Use hash instead of raw JSON to avoid keeping credentials as a string in memory
     const smtpKey = createHash('sha256').update(JSON.stringify(smtp)).digest('hex');
     if (!this.cachedTransporter || this.cachedSmtpConfig !== smtpKey) {
-      this.cachedTransporter = nodemailer.createTransport(smtp);
+      this.cachedTransporter = createTransport(smtp);
       this.cachedSmtpConfig = smtpKey;
     }
 

package/src/core/common/services/mailjet.service.ts

@@ -1,7 +1,15 @@
 import { HttpException, Injectable } from '@nestjs/common';
-const Mailjet = require('node-mailjet');
+import type { Client } from 'node-mailjet';
+import MailjetDefault from 'node-mailjet';
 
-import { ConfigService } from './config.service';
+import { ConfigService } from './config.service.js';
+
+/**
+ * node-mailjet's declarations say `export default Mailjet`, while its CommonJS build exports the class itself (no
+ * `.default`). At runtime both module systems hand the class to a default import; only TypeScript's ESM view types it
+ * as the module object. `Mailjet` extends `Client` without changing the constructor, so this is the honest type.
+ */
+const Mailjet = MailjetDefault as unknown as typeof Client;
 
 /**
  * Mailjet service

package/src/core/common/services/model-doc.service.ts

@@ -1,8 +1,8 @@
 import { Injectable, OnApplicationBootstrap } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
-import fs = require('fs');
-import { Connection } from 'mongoose';
-import YumlDiagram = require('yuml-diagram');
+import * as fs from 'fs';
+import type { Connection } from 'mongoose';
+import YumlDiagram from 'yuml-diagram';
 
 /**
  * Schema config for yUml creation

package/src/core/common/services/model-registry.service.ts

@@ -1,4 +1,4 @@
-import { CoreModel } from '../models/core-model.model';
+import { CoreModel } from '../models/core-model.model.js';
 
 /**
  * Central registry mapping Mongoose model names to CoreModel classes.