@lenne.tech/nest-server 11.42.3 → 11.42.5

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

@@ -0,0 +1,232 @@
+import { Injectable, Logger, OnModuleInit, Optional, PayloadTooLargeException } from '@nestjs/common';
+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 type { NextFunction, Request, RequestHandler, Response } from 'express';
+
+/** The two parsers NestJS registers on every Express application */
+export type CoreBodyParserType = 'json' | 'urlencoded';
+
+/**
+ * The function names body-parser gives its middleware. NestJS identifies its own parser layers by
+ * exactly these names (`ExpressAdapter.isMiddlewareApplied()`), which is why a wrapper must keep them.
+ */
+const PARSER_NAMES: Record<CoreBodyParserType, string> = { json: 'jsonParser', urlencoded: 'urlencodedParser' };
+
+/** 1024-based, like the `bytes` package body-parser itself parses limits with */
+const UNIT_FACTORS: Record<string, number> = { b: 1, gb: 1024 ** 3, kb: 1024, mb: 1024 ** 2 };
+
+/** The router layer fields this initializer reads and writes (Express 5 / `router` 2.x) */
+interface ExpressLayer {
+  handle: RequestHandler;
+  slash?: boolean;
+}
+
+/**
+ * Convert a configured body limit into bytes.
+ *
+ * Returns `undefined` for anything that is not a positive size, so the caller can refuse it. The
+ * value is turned into a number HERE rather than handed to body-parser as a string, so the limit that
+ * is logged and the limit that is enforced cannot differ.
+ *
+ * @example parseBodyLimit('2mb') // 2097152
+ * @example parseBodyLimit(500000) // 500000
+ * @example parseBodyLimit('lots') // undefined
+ */
+export function parseBodyLimit(value: unknown): number | undefined {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value >= 1 ? Math.floor(value) : undefined;
+  }
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i.exec(value.trim());
+  if (!match) {
+    return undefined;
+  }
+  const bytes = Math.floor(Number(match[1]) * UNIT_FACTORS[(match[2] || 'b').toLowerCase()]);
+  return bytes >= 1 ? bytes : undefined;
+}
+
+/**
+ * Applies `ServerOptions.bodyParser` to the body parsers NestJS registered, and turns their 413 into
+ * an answer a caller can act on.
+ *
+ * WHY it swaps layers instead of calling `useBodyParser()`: NestJS registers its parsers inside
+ * `app.init()`, BEFORE any `onModuleInit` runs, and a parser appended afterwards would sit behind
+ * the routes. So the layers NestJS created are replaced in place — same position in the middleware
+ * chain, same options otherwise. Doing it during module init (rather than in `main.ts`) is what
+ * makes the limit hold under `Test.createTestingModule()`, which never runs `main.ts`.
+ *
+ * Unconfigured, the parsers are not replaced, only wrapped: their own limit and options stay, and a
+ * 413 they raise is answered with `ErrorCode.REQUEST_BODY_TOO_LARGE` plus size and limit instead of
+ * a bare "request entity too large", and logged as a warning that names the route and the config
+ * key. Without that line the first symptom of a too-small limit is a user whose save keeps failing.
+ *
+ * Registered as a CoreModule provider; consumers never interact with it.
+ */
+@Injectable()
+export class CoreBodyParserInitializer implements OnModuleInit {
+  protected readonly logger = new Logger(CoreBodyParserInitializer.name);
+
+  constructor(
+    @Optional() protected readonly httpAdapterHost?: HttpAdapterHost,
+    @Optional() protected readonly moduleRef?: ModuleRef,
+  ) {}
+
+  onModuleInit(): void {
+    const stack = this.getRouterStack();
+    if (!stack) {
+      // Fastify and non-HTTP contexts have no body-parser layers; there is nothing to adjust.
+      return;
+    }
+
+    const config = this.getConfig();
+    for (const type of ['json', 'urlencoded'] as const) {
+      const limit = this.resolveLimit(type, config?.[type]?.limit);
+      const layers = stack.filter((layer) => this.isGlobalParserLayer(layer, type));
+
+      if (limit !== undefined && !layers.length) {
+        this.logger.warn(
+          `bodyParser.${type}.limit is configured, but no global ${type} body parser is registered ` +
+            '(was the app created with `bodyParser: false`?) — the limit has no effect.',
+        );
+        continue;
+      }
+
+      for (const layer of layers) {
+        const parser = limit === undefined ? layer.handle : this.createParser(type, limit);
+        layer.handle = this.wrapParser(type, parser);
+      }
+
+      if (limit !== undefined) {
+        this.logger.log(`Body parser: ${type} limit set to ${limit} bytes`);
+      }
+    }
+  }
+
+  /**
+   * A parser equivalent to the one NestJS registers, with the configured limit.
+   *
+   * `extended: true` mirrors NestJS's URL-encoded default (nested objects via `qs`). `req.rawBody`
+   * is kept when the app was created with `rawBody: true`, because webhook signature checks read it
+   * and would otherwise fail on every request once a limit is configured.
+   */
+  protected createParser(type: CoreBodyParserType, limit: number): RequestHandler {
+    const verify = this.isRawBodyEnabled() ? captureRawBody : undefined;
+    return type === 'json' ? json({ limit, verify }) : urlencoded({ extended: true, limit, verify });
+  }
+
+  /** The configured `bodyParser` block, or `undefined` when the project did not set one */
+  protected getConfig(): IBodyParserConfig | undefined {
+    return ConfigService.getFastButReadOnly<IBodyParserConfig>('bodyParser');
+  }
+
+  /** The Express router stack, or `undefined` for a non-Express adapter */
+  protected getRouterStack(): ExpressLayer[] | undefined {
+    const app = this.httpAdapterHost?.httpAdapter?.getInstance?.();
+    if (typeof app?.use !== 'function' || typeof app?.set !== 'function') {
+      return undefined;
+    }
+    const stack = app.router?.stack;
+    return Array.isArray(stack) ? stack : undefined;
+  }
+
+  /**
+   * Whether a layer is a GLOBAL parser of this type.
+   *
+   * `slash` is how the Express 5 router marks `app.use(fn)` — mounted on `/` without an end. A
+   * path-scoped `app.use('/upload', json({ limit }))` is a project's deliberate exception for one
+   * path and is left alone, including its 413.
+   */
+  protected isGlobalParserLayer(layer: ExpressLayer | undefined, type: CoreBodyParserType): boolean {
+    return layer?.slash === true && typeof layer.handle === 'function' && layer.handle.name === PARSER_NAMES[type];
+  }
+
+  /**
+   * Whether the application was created with `rawBody: true`.
+   *
+   * `NestFactory.create()` hands its options to the container and nothing public exposes them, so
+   * they are read from the container `ModuleRef` carries. Under `Test.createTestingModule()` the
+   * options passed to `createNestApplication()` never reach the container — that is the caveat
+   * documented on `IServerOptions.bodyParser`.
+   */
+  protected isRawBodyEnabled(): boolean {
+    const container = (this.moduleRef as unknown as { container?: { contextOptions?: { rawBody?: boolean } } })
+      ?.container;
+    return container?.contextOptions?.rawBody === true;
+  }
+
+  /**
+   * The configured limit in bytes, or `undefined` when unset or invalid.
+   *
+   * An invalid value is refused rather than passed on: body-parser would throw at boot for some
+   * inputs and apply nonsense (a negative limit rejects every body) for others. The parser keeps the
+   * limit it has — never "no limit", since it runs before authentication.
+   */
+  protected resolveLimit(type: CoreBodyParserType, value: unknown): number | undefined {
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+    const limit = parseBodyLimit(value);
+    if (limit === undefined) {
+      this.logger.error(
+        `bodyParser.${type}.limit ${JSON.stringify(value)} is not a positive size (bytes, or e.g. '500kb' / '2mb') ` +
+          `— ignored, the ${type} body parser keeps the limit it has (100 kB unless set elsewhere).`,
+      );
+    }
+    return limit;
+  }
+
+  /**
+   * Answer a body-parser 413 with an error code, the size and the limit, and log it.
+   *
+   * Every other error (malformed JSON, unsupported charset, too many parameters) passes through
+   * unchanged, so NestJS answers it exactly as before.
+   */
+  protected translateError(type: CoreBodyParserType, error: unknown, req: Request): unknown {
+    const details = error as undefined | { length?: unknown; limit?: unknown; type?: unknown };
+    if (details?.type !== 'entity.too.large') {
+      return error;
+    }
+
+    // `length` is the declared Content-Length; a chunked body has none, and the byte count at which
+    // body-parser stopped reading says nothing about how large the body really was.
+    const length = typeof details.length === 'number' ? details.length : undefined;
+    const sizeText = length === undefined ? '' : `${length} bytes, `;
+    const path = String(req.originalUrl ?? req.url ?? '').split('?')[0];
+
+    this.logger.warn(
+      `413 ${req.method} ${path}: ${type} body ${length === undefined ? '' : `of ${length} bytes `}` +
+        `exceeds the limit of ${details.limit} bytes. If payloads of this size are legitimate here, ` +
+        `raise \`bodyParser.${type}.limit\` in the server options.`,
+    );
+    return new PayloadTooLargeException(
+      `${ErrorCode.REQUEST_BODY_TOO_LARGE} [${sizeText}limit ${details.limit} bytes]`,
+    );
+  }
+
+  /**
+   * Wrap a parser so its 413 is translated, keeping the name NestJS identifies the layer by.
+   *
+   * Wrapping an already wrapped parser is harmless: the outer wrapper receives the translated
+   * `PayloadTooLargeException`, which carries no body-parser `type`, and passes it on unchanged.
+   */
+  protected wrapParser(type: CoreBodyParserType, parser: RequestHandler): RequestHandler {
+    const wrapped = (req: Request, res: Response, next: NextFunction) =>
+      parser(req, res, (error?: unknown) => (error ? next(this.translateError(type, error, req)) : next()));
+    Object.defineProperty(wrapped, 'name', { value: PARSER_NAMES[type] });
+    return wrapped;
+  }
+}
+
+/** Same behaviour as the `verify` NestJS installs for `rawBody: true` */
+function captureRawBody(req: Request & { rawBody?: Buffer }, _res: Response, buffer: Buffer): void {
+  if (Buffer.isBuffer(buffer)) {
+    req.rawBody = buffer;
+  }
+}

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

@@ -226,6 +226,27 @@ function normalizeBetterAuthConfig(config: boolean | IBetterAuth | undefined): I
   return config;
 }
 
+/**
+ * The secret Better-Auth actually signs with, for the NestJS layer (controller cookie helper,
+ * API middleware, CoreBetterAuthService) to sign its cookies with the same value.
+ *
+ * `createBetterAuthInstance` resolves it as `betterAuth.secret` → first fallback of at least 32
+ * characters → auto-generated. Only the instance knows the generated one; without it the cookie
+ * went out unsigned and every native Better-Auth endpoint (`/iam/token`, MCP authorize, passkey,
+ * 2FA) rejected the session with 401.
+ */
+function resolveSigningSecret(
+  authInstance: BetterAuthInstance | null,
+  config: IBetterAuth,
+  fallbackSecrets?: (string | undefined)[],
+): string | undefined {
+  return (
+    (authInstance as null | { options?: { secret?: string } })?.options?.secret ||
+    config.secret ||
+    fallbackSecrets?.find((s) => s && s.length >= 32)
+  );
+}
+
 /**
  * CoreBetterAuthModule provides integration with the better-auth authentication framework.
  *
@@ -698,8 +719,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             // Store a config copy with the resolved secret so that consumers
             // (CoreBetterAuthService, CoreBetterAuthController) can sign cookies.
             // The original config object may be frozen (from ConfigService), so we
-            // create a shallow copy with the resolved fallback secret applied.
-            const resolvedSecret = config.secret || fallbackSecrets?.find((s) => s && s.length >= 32);
+            // create a shallow copy with the resolved (fallback or generated) secret applied.
+            const resolvedSecret = resolveSigningSecret(this.authInstance, config, fallbackSecrets);
             this.currentConfig =
               resolvedSecret && resolvedSecret !== config.secret ? { ...config, secret: resolvedSecret } : config;
 
@@ -1068,8 +1089,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             this.resolvedCookieDomain = result?.cookieDomain;
 
             // Store a config copy with the resolved secret (same as first forRoot variant)
-            const fallbacks = options?.fallbackSecrets;
-            const resolvedSecret2 = config.secret || fallbacks?.find((s) => s && s.length >= 32);
+            const resolvedSecret2 = resolveSigningSecret(this.authInstance, config, options?.fallbackSecrets);
             this.currentConfig =
               resolvedSecret2 && resolvedSecret2 !== config.secret ? { ...config, secret: resolvedSecret2 } : config;
 

package/src/core/modules/error-code/error-codes.ts

@@ -435,6 +435,15 @@ export const LtnsErrors = {
     },
   },
 
+  REQUEST_BODY_TOO_LARGE: {
+    code: 'LTNS_0304',
+    message: 'Request body too large',
+    translations: {
+      de: 'Die gesendeten Daten sind zu groß und wurden nicht verarbeitet.',
+      en: 'The submitted data is too large and was not processed.',
+    },
+  },
+
   // =====================================================
   // Resource Errors (LTNS_0400-LTNS_0499)
   // =====================================================

package/src/core.module.ts

@@ -48,6 +48,7 @@ import { mongooseRoleGuardPlugin } from './core/common/plugins/mongoose-role-gua
 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 { CoreBodyParserInitializer } from './core/common/services/core-body-parser.initializer';
 import { CoreCronJobsInitializer } from './core/common/services/core-cron-jobs.initializer';
 import { CoreRedisService } from './core/common/services/core-redis.service';
 import { CoreS3Service } from './core/common/services/core-s3.service';
@@ -324,6 +325,9 @@ export class CoreModule implements NestModule {
       },
 
       // Core Services
+      // Applies `bodyParser` limits and answers a body-parser 413 with an error code. Swaps the
+      // parser layers NestJS registered in place, during module init — see the initializer.
+      CoreBodyParserInitializer,
       CoreCronJobsInitializer,
       // Audits the file endpoints the project actually REGISTERED. applyFileRoles() above can only
       // reach the base-class members; a subclass that re-declares one keeps its own @Roles() and the

package/src/test/README.md

@@ -243,4 +243,82 @@ const result = await testHelper.graphQl(
 );
 ```
 
-See `TestGraphQLConfig` and `TestGraphQLOptions` interfaces in `test.helper.ts` for full configuration options.
+See `TestGraphQLConfig` and `TestGraphQLOptions` interfaces in `test.helper.ts` for full configuration options.
+
+## MCP Testing (`testHelper.mcp()` / `testHelper.mcpSession()`)
+
+An MCP client reaches the same services as REST and GraphQL through its own door: the MCP server of the AI module
+(`/ai/mcp`, enabled with `ai.mcp` in `config.env.ts`) has its own role filter, its own sessions, and reports a refused
+or failing tool as a result with `isError: true` instead of an HTTP error. A project that enables MCP therefore tests
+its tools over MCP too, next to its API tests.
+
+The transport answers requests as an SSE stream. These helpers handle the stream, the session header and the
+handshake, so a test reads results directly.
+
+### `mcpSession(options?)`
+
+Opens a session the way every MCP client does (`initialize`, then `notifications/initialized`) for the user of `token`
+or `cookies`:
+
+```typescript
+const session = await testHelper.mcpSession({ token: userToken });
+
+// tools/list — filtered by the user's roles
+const names = (await session.listTools()).map((tool) => tool.name);
+expect(names).toContain('find_users');
+
+// tools/call — `json` is the first text content parsed as JSON (the tool's own result)
+const result = await session.callTool('find_users', { query: '@test.com' });
+expect(result.isError).toBeFalsy();
+expect(result.json.data.length).toBeGreaterThan(0);
+
+// A tool outside the user's roles is refused, not run
+const refused = await session.callTool('delete_user', { id });
+expect(refused.isError).toBe(true);
+
+// Any other JSON-RPC request; returns the whole message, protocol errors included
+const reply = await session.request('prompts/list');
+
+// End the session server-side
+await session.close();
+```
+
+| Member                               | Description                                                              |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| `sessionId`                          | `mcp-session-id` the server assigned                                     |
+| `initializeResult`                   | Result of `initialize` (`serverInfo`, `capabilities`, `protocolVersion`) |
+| `listTools()`                        | `tools/list`, returns the tools array                                    |
+| `callTool(name, args?)`              | `tools/call`, returns the `CallToolResult` plus `json`                   |
+| `request(method, params?, options?)` | Any request in the session, returns the JSON-RPC message                 |
+| `close()`                            | `DELETE` with the session id                                             |
+
+### `mcp(message, options?)`
+
+Sends a single JSON-RPC message and returns `{ message, response, sessionId }`. Use it for the HTTP-level cases a
+session hides:
+
+```typescript
+// No token → 401
+await testHelper.mcp({ id: 1, method: 'initialize', params: {} }, { statusCode: 401 });
+
+// Another user's session id → 404 (not 403: confirming the id exists would be an oracle)
+await testHelper.mcp(
+  { id: 2, method: 'tools/list' },
+  { sessionId: adminSession.sessionId, statusCode: 404, token: userToken },
+);
+```
+
+### TestMcpOptions
+
+| Option             | Type                               | Default                         | Description                                     |
+| ------------------ | ---------------------------------- | ------------------------------- | ----------------------------------------------- |
+| `token`            | `string`                           | -                               | Bearer token, the same one `rest()` takes       |
+| `cookies`          | `string \| Record<string, string>` | -                               | Cookie authentication, same modes as `rest()`   |
+| `sessionId`        | `string`                           | -                               | `mcp-session-id` header (`mcp()` only)          |
+| `statusCode`       | `number`                           | `200`, `202` for a notification | Expected HTTP status (`mcp()` only)             |
+| `path`             | `string`                           | `'/ai/mcp'`                     | Endpoint, for a project with its own MCP module |
+| `headers`          | `Record<string, string>`           | -                               | Additional headers                              |
+| `log` / `logError` | `boolean`                          | `false`                         | Same as `rest()`                                |
+
+`mcpSession()` additionally takes `clientInfo` and `protocolVersion` for the `initialize` request.
+`TestHelper.parseMcpMessage(response)` is the parser behind both, for tests that send requests themselves.