Security and Middleware Documentation

This documentation explains the features and usage of Request Middleware Module: Located at src/common/request/middlewares

Overview

Complete NestJS Boilerplate implements a comprehensive security and middleware layer for HTTP request/response processing. All middleware is centrally managed through RequestMiddlewareModule and applied globally to all routes using the wildcard pattern {*wildcard}.

consumer
  .apply(
    RequestRequestIdMiddleware,      // 1. Request & Correlation IDs
    RequestHelmetMiddleware,         // 2. Security headers
    RequestBodyParserMiddleware,     // 3. Body parsing
    RequestCorsMiddleware,           // 4. CORS handling
    RequestUrlVersionMiddleware,     // 5. API version extraction
    RequestResponseTimeMiddleware,   // 6. Response time tracking
    RequestCustomLanguageMiddleware, // 7. Language detection
    RequestCompressionMiddleware     // 8. Response compression
  )
  .forRoutes('{*wildcard}');

Related Documents

• Authentication
• Authorization
• Configuration
• Environment

Table of Contents

• Overview
• Related Documents
• Authentication & Authorization
• Helmet
• Rate Limiting
• CORS
• Environment Protection
• Request & Correlation IDs
• Body Parser
• URL Versioning
• Custom Language
• Response Compression
• Response Time
• Request Timeout
• Decorators
  • @RequestTimeout
  • @RequestEnvProtected
  • @RequestIPAddress
  • @RequestUserAgent

Authentication & Authorization

Complete NestJS Boilerplate includes comprehensive authentication and authorization systems. See dedicated documentation:

• Authentication - JWT, OAuth, API Keys, sessions, password management
• Authorization - RBAC, policy abilities, user protection

Helmet

Applies protective HTTP headers using [Helmet][ref-helmet].

Implementation: RequestHelmetMiddleware

Usage: Automatically applied to all routes.

Rate Limiting

Prevents abuse using [Throttler][ref-throttler].

Implementation:

ThrottlerModule.forRootAsync({
  useFactory: (config: ConfigService) => ({
    throttlers: [{
      ttl: config.get<number>('request.throttle.ttlInMs'),
      limit: config.get<number>('request.throttle.limit'),
    }],
  }),
})

Skip Rate Limiting:

@SkipThrottle()
@Get('/unlimited')
async endpoint() {}

Configuration: See Configuration

CORS

Manages cross-origin resource sharing.

Implementation: RequestCorsMiddleware

Features:

• Dynamic origin validation
• Automatic credential handling
• Configurable methods and headers
• Preflight request support

Configuration: See Configuration

Environment Protection

Restricts endpoint access based on environment.

Implementation: RequestEnvGuard

Usage:

@RequestEnvProtected(EnumAppEnvironment.DEVELOPMENT)
@Get('/debug')
async debugEndpoint() {}

Configuration: See Configuration

Request & Correlation IDs

Generates unique identifiers for request tracking.

Implementation: RequestRequestIdMiddleware

Request Properties:

interface IRequestApp extends Request {
  id: string;            // UUID v7 request ID
  correlationId: string; // Correlation ID for distributed tracing
  __version: string;     // API version
  __language: string;    // Language preference
}

Body Parser

Parses request bodies based on content-type.

Implementation: RequestBodyParserMiddleware

Supported Content Types:

• application/json
• application/x-www-form-urlencoded
• text/*
• application/octet-stream
• multipart/form-data (skipped, handled by Multer)

Configuration: See Configuration

URL Versioning

Extracts API version from URLs.

Implementation: RequestUrlVersionMiddleware

URL Pattern:

/{globalPrefix}/{versionPrefix}{version}/resource
Example: /api/v1/users

Request Property:

req.__version  // Extracted version number

Configuration: See Configuration

Custom Language

Processes x-custom-lang header for internationalization.

Implementation: RequestCustomLanguageMiddleware

Usage:

# Request header
x-custom-lang: id

Request Property:

req.__language  // Validated language code

Configuration: See Configuration

Response Compression

Applies gzip/deflate compression using [compression][ref-compression].

Implementation: RequestCompressionMiddleware

Usage: Automatically applied to all responses.

Response Time

Measures request duration using [response-time][ref-response-time].

Implementation: RequestResponseTimeMiddleware

Header Example:

X-Response-Time: 123.456ms

Request Timeout

Prevents long-running requests.

Implementation: RequestTimeoutInterceptor

Global Registration:

app.useGlobalInterceptors(new RequestTimeoutInterceptor(configService, reflector));

Custom Timeout:

@RequestTimeout('60s')
@Get('/long-running')
async operation() {}

Supported Formats: [ms][ref-ms] format ('2s', '1m', '5h')

Configuration: See Configuration

Decorators

@RequestTimeout

Sets custom timeout for specific endpoints.

Signature:

RequestTimeout(seconds: ms.StringValue): MethodDecorator

Example:

@RequestTimeout('2m')
@Post('/process')
async processData() {}

@RequestEnvProtected

Restricts endpoint access based on environment.

Signature:

RequestEnvProtected(...envs: EnumAppEnvironment[]): MethodDecorator

Example:

@RequestEnvProtected(EnumAppEnvironment.DEVELOPMENT)
@Get('/admin/clear-cache')
async clearCache() {}

@RequestIPAddress

Extracts real client IP address from request using [nestjs-real-ip][ref-nestjs-real-ip].

Signature:

RequestIPAddress(): ParameterDecorator

Example:

@Get('/check-ip')
async checkIP(@RequestIPAddress() ip: string) {
  return { ip };
}

@RequestUserAgent

Parses User-Agent information using [ua-parser-js][ref-ua-parser-js].

Signature:

RequestUserAgent(): ParameterDecorator

Example:

@Get('/device-info')
async getDeviceInfo(@RequestUserAgent() userAgent: UAParser.IResult) {
  return {
    browser: userAgent.browser,
    os: userAgent.os,
    device: userAgent.device
  };
}

Response Structure:

interface IResult {
  browser: { name?: string; version?: string };
  os: { name?: string; version?: string };
  device: { model?: string; type?: string; vendor?: string };
  engine: { name?: string; version?: string };
  cpu: { architecture?: string };
}