Kurs NestJS · Moduł 9: Deployment i infrastruktura

SSL/TLS i HTTPS Configuration - tarcza obronna Imperium

8 min czytania ·
W tej lekcji6

Legionisto cyberbezpieczeństwa! Hasło logującego się legionisty leci przez kawiarniane Wi-Fi jawnym tekstem, a obca strona po cichu wysyła żądania w jego imieniu. Architekt Vitruvius wie, że każda prowincja potrzebuje fortyfikacji: jak mury chroniły Rzym przed najeźdźcami, tak TLS i zabezpieczenia HTTP chronią aplikację NestJS przed atakami z sieci.

SSL (Secure Sockets Layer) i jego następca TLS (Transport Layer Security) to protokoły kryptograficzne zapewniające bezpieczną komunikację. SSL 2.0 i 3.0 są dziś zakazane jako niebezpieczne, a używa się TLS 1.2 i 1.3 - nazwa „certyfikat SSL” została z przyzwyczajenia. HTTPS to HTTP działający przez TLS, który szyfruje dane między klientem a serwerem. Zbudujemy cztery pierścienie murów, od transportu do aplikacji: TLS szyfruje drogę, Helmet ustawia nagłówki bezpieczeństwa, CORS decyduje, które strony mogą wołać API, a rate limiting liczy żądania klientów.

Generowanie certyfikatów SSL

Pierwszym krokiem jest pozyskanie certyfikatów. W środowisku deweloperskim możemy wygenerować certyfikaty samopodpisane, a na produkcji korzystamy z Let's Encrypt lub komercyjnych dostawców.

Certyfikaty deweloperskie (self-signed)

Skrypt wywołuje openssl przez execSync i zapisuje klucz oraz certyfikat w katalogu certs:

// scripts/generate-dev-cert.ts
import { execSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';

// Katalog liczony od katalogu projektu - w modułach ES nie ma __dirname
const certsDir = path.join(process.cwd(), 'certs');

// Tworzenie katalogu na certyfikaty
if (!fs.existsSync(certsDir)) {
  fs.mkdirSync(certsDir, { recursive: true });
}

// Generowanie klucza prywatnego i certyfikatu z nazwami w subjectAltName
execSync(`openssl req -x509 -newkey rsa:4096 \
  -keyout ${certsDir}/key.pem \
  -out ${certsDir}/cert.pem \
  -days 365 -nodes \
  -subj "/C=PL/ST=Roma/L=Roma/O=Imperium/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"`);

console.log('Certyfikaty deweloperskie wygenerowane w katalogu certs/');

-nodes zostawia klucz bez hasła (OpenSSL 3 nazywa tę opcję -noenc, ale stara nazwa działa też w LibreSSL na macOS). -addext dopisuje nazwy w polu subjectAltName: przeglądarki od lat ignorują samo CN, więc certyfikat bez niego odrzucą. Katalog liczymy od process.cwd(), bo nowy projekt NestJS 12 jest modułem ES, w którym __dirname nie istnieje.

Konfiguracja HTTPS w NestJS

NestFactory.create() przyjmuje httpsOptions z kluczem i certyfikatem:

// src/main.ts - uruchomienie serwera z HTTPS
import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { AppModule } from './app.module';
import * as fs from 'node:fs';
import * as path from 'node:path';

async function bootstrap() {
  const isProduction = process.env.NODE_ENV === 'production';

  // Opcje HTTPS - certyfikaty SSL
  const httpsOptions = isProduction
    ? {
        key: fs.readFileSync(process.env.SSL_KEY_PATH),
        cert: fs.readFileSync(process.env.SSL_CERT_PATH),
        ca: fs.readFileSync(process.env.SSL_CA_PATH), // Chain certyfikatów
      }
    : {
        key: fs.readFileSync(path.join(process.cwd(), 'certs', 'key.pem')),
        cert: fs.readFileSync(path.join(process.cwd(), 'certs', 'cert.pem')),
      };

  const app = await NestFactory.create<NestExpressApplication>(AppModule, { httpsOptions });

  // Za reverse proxy: ufaj nagłówkom X-Forwarded-* od pierwszego pośrednika
  app.set('trust proxy', 1);

  // Wymuszenie przekierowania HTTP -> HTTPS
  if (isProduction) {
    app.use((req, res, next) => {
      if (!req.secure) {
        // Adres z konfiguracji, a nie z nagłówka Host, który ustawia klient
        return res.redirect(301, `https://${process.env.PUBLIC_HOST}${req.originalUrl}`);
      }
      next();
    });
  }

  await app.listen(process.env.PORT || 3000);
}
bootstrap();

TLS kończy się albo w samym Node.js (httpsOptions), albo w reverse proxy, które przekazuje ruch zwykłym HTTP z nagłówkiem X-Forwarded-Proto. trust proxy każe Expressowi ufać temu nagłówkowi, więc req.secure działa w obu modelach. Pierwsza wersja sprawdzała sam nagłówek, a bez proxy go nie ma - każde żądanie dostawało przekierowanie i powstawała pętla. Adres docelowy bierzemy z konfiguracji, bo nagłówek Host ustawia klient.

Helmet.js - nagłówki bezpieczeństwa HTTP

Helmet to jak hełm centuriona - chroni głowę, czyli nagłówki HTTP, przed najczęstszymi atakami:

// src/main.ts - konfiguracja Helmet
import helmet from 'helmet';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Podstawowa konfiguracja Helmet - wystarcza większości API:
  // app.use(helmet());

  // Zaawansowana konfiguracja Helmet (zamiast podstawowej)
  app.use(helmet({
    // Content-Security-Policy - kontroluje skąd ładowane są zasoby
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'"],
        styleSrc: ["'self'", "'unsafe-inline'", 'https://fonts.googleapis.com'],
        fontSrc: ["'self'", 'https://fonts.gstatic.com'],
        imgSrc: ["'self'", 'data:', 'https:'],
        connectSrc: ["'self'", ...(process.env.API_URL ? [process.env.API_URL] : [])],
        frameSrc: ["'none'"],
        objectSrc: ["'none'"],
      },
    },
    // Strict-Transport-Security - wymusza HTTPS
    strictTransportSecurity: {
      maxAge: 31536000, // 1 rok
      includeSubDomains: true,
      preload: true,
    },
    // X-Frame-Options - zapobiega clickjacking
    xFrameOptions: { action: 'deny' },
    // X-Content-Type-Options - zapobiega MIME sniffing
    xContentTypeOptions: true,
    // Referrer-Policy
    referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
  }));
}

Nazwy opcji pochodzą z Helmet 8; dawne hsts, frameguard i noSniff to przestarzałe aliasy. Z scriptSrc zniknęło 'unsafe-inline', które wyłączało ochronę CSP przed XSS. preload wpisuje domenę na listę HSTS w przeglądarkach i trudno to cofnąć, więc włączaj go świadomie. Od NestJS 12.1 te same domyślne nagłówki ustawia wbudowane app.useSecurityHeaders().

CORS dla produkcji

CORS (Cross-Origin Resource Sharing) kontroluje, które domeny mogą komunikować się z naszym API. To jak lista zaufanych ambasadorów Imperium:

// src/main.ts - produkcyjna konfiguracja CORS
import { CorsOptions } from '@nestjs/common/interfaces/external/cors-options.interface';

const corsOptions: CorsOptions = {
  origin: (origin, callback) => {
    const allowedOrigins = process.env.CORS_ORIGINS?.split(',') || [];

    // Pozwól na requesty bez origin (mobile, Postman)
    if (!origin) return callback(null, true);

    if (allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      // false = brak nagłówków CORS; przeglądarka sama zablokuje odpowiedź
      callback(null, false);
    }
  },
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
  exposedHeaders: ['X-Total-Count', 'X-Page-Count'],
  credentials: true,
  maxAge: 86400, // Cache preflight na 24h (Chromium skraca do 2h)
};

app.enableCors(corsOptions);

Obca domena dostaje po prostu brak nagłówków CORS; pierwsza wersja zwracała błąd, co kończyło się odpowiedzią 500 i śmieciami w logach. CORS chroni tylko użytkowników przeglądarek - Postman czy aplikacja mobilna go ignorują, więc nie zastąpi autoryzacji.

Rate Limiting z @nestjs/throttler

Rate limiting to strażnicy przy bramach, którzy liczą, ile osób wchodzi w danym czasie:

// src/app.module.ts - konfiguracja ThrottlerModule
import { Module } from '@nestjs/common';
import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
import { APP_GUARD } from '@nestjs/core';

@Module({
  imports: [
    ThrottlerModule.forRoot([
      {
        name: 'short',  // Krótkoterminowy limit
        ttl: 1000,      // 1 sekunda
        limit: 3,       // Max 3 requesty na sekundę
      },
      {
        name: 'medium', // Średni limit
        ttl: 10000,     // 10 sekund
        limit: 20,      // Max 20 requestów na 10 sekund
      },
      {
        name: 'long',   // Długoterminowy limit
        ttl: 60000,     // 1 minuta
        limit: 100,     // Max 100 requestów na minutę
      },
    ]),
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: ThrottlerGuard,
    },
  ],
})
export class AppModule {}

ttl podajemy w milisekundach, a wszystkie trzy limity obowiązują jednocześnie. Throttler chroni przed brute force i nadużyciami API, ale nie przed prawdziwym DDoS, który zatyka łącze, zanim ruch dotrze do Node.js. Za proxy ustaw trust proxy, a przy kilku instancjach użyj wspólnego magazynu w Redisie.

Dekoratory zmieniają limity dla pojedynczych endpointów:

// Wyłączenie rate limitingu dla konkretnych endpointów
import { SkipThrottle, Throttle } from '@nestjs/throttler';

@Controller('legions')
export class LegionsController {
  @SkipThrottle({ short: true, medium: true, long: true }) // Bez limitu dla health check
  @Get('health')
  healthCheck() {
    return { status: 'ok' };
  }

  @Throttle({ short: { ttl: 1000, limit: 1 } }) // Surowszy limit
  @Post('login')
  login() {
    // Logowanie z ograniczeniem 1 req/s
  }
}

Przy nazwanych limitach @SkipThrottle() bez argumentów nie wyłącza żadnego z nich - w teście health check dostał 429 po trzech żądaniach, dlatego podajemy nazwy. @Throttle zmienia tylko short; medium i long nadal działają.

Ochrona CSRF

CSRF (Cross-Site Request Forgery) to atak, w którym złośliwa strona wykonuje żądania w imieniu zalogowanego użytkownika. Dotyczy logowania ciasteczkami; token JWT w nagłówku Authorization przeglądarka sama nie dołącza. Starsze projekty chroniły się pakietem csurf:

// src/main.ts - ochrona CSRF z csurf (pakiet przestarzały, tylko dla starych projektów)
import csurf from 'csurf';
import cookieParser from 'cookie-parser';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // csurf z opcją cookie wymaga wcześniej cookie-parser
  app.use(cookieParser());

  // CSRF protection (dla aplikacji z sesją/cookies)
  app.use(csurf({
    cookie: {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'strict',
    },
  }));

  // Middleware ustawiający CSRF token w odpowiedzi
  app.use((req, res, next) => {
    res.cookie('XSRF-TOKEN', req.csrfToken(), {
      httpOnly: false, // Frontend musi móc odczytać
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'strict',
    });
    next();
  });
}

csurf jest zarchiwizowany i oznaczony jako przestarzały. Wymaga też cookie-parser przed sobą - bez niego w teście każde żądanie kończyło się błędem 500. NestJS 12.1 ma ochronę wbudowaną:

// src/main.ts - wbudowana ochrona CSRF (NestJS 12.1+)
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableCsrfProtection({
    // Frontend z innej domeny, który może wysyłać POST-y z ciasteczkami
    trustedOrigins: ['https://admin.imperium.rome'],
  });

  await app.listen(3000);
}

enableCsrfProtection() sprawdza nagłówek Sec-Fetch-Site, który przeglądarki dołączają do żądań. W teście POST z obcej strony dostał 403, a GET, żądania bez nagłówków przeglądarki i zaufane domeny przeszły. Tokeny, np. z pakietu csrf-csrf, dokumentacja NestJS zostawia dla bardzo starych przeglądarek.

Kompletna konfiguracja bezpieczeństwa

Middleware z Helmet można też podpiąć w module:

// src/security/security.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { ThrottlerModule } from '@nestjs/throttler';
import helmet from 'helmet';

@Module({
  imports: [
    ThrottlerModule.forRoot([
      { name: 'short', ttl: 1000, limit: 3 },
      { name: 'long', ttl: 60000, limit: 100 },
    ]),
  ],
})
export class SecurityModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(
        helmet(),
        helmet.contentSecurityPolicy({
          directives: {
            defaultSrc: ["'self'"],
            scriptSrc: ["'self'"],
          },
        }),
      )
      .forRoutes('*');
  }
}

helmet() ustawia już domyślne CSP, a drugie wywołanie je nadpisuje - wystarczyłoby jedno z opcją contentSecurityPolicy.

Bezpieczeństwo to nie jednorazowe zadanie, a ciągły proces - jak obrona murów, która wymagała stałej czujności strażników. Każda warstwa (TLS, Helmet, CORS, rate limiting, CSRF) dodaje kolejny mur. Polecam Ci zaczynać od domyślnych ustawień Helmet i dokładać wyjątki dopiero wtedy, gdy coś przestaje działać. W następnej lekcji zbudujemy pipeline CI/CD, który sprawdzi te mury przy każdym wdrożeniu.

Pamiętaj: jeden mur nigdy nie wystarcza - Imperium broni się pierścieniami, od drogi po bramę.

Kod do tej lekcji: src/security-config.ts
// SSL/TLS i HTTPS Configuration - Tarcza Obronna Imperium
import { NestFactory } from '@nestjs/core';
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
import { APP_GUARD } from '@nestjs/core';
import helmet from 'helmet';
import * as fs from 'fs';

// 1. HTTPS Configuration
async function bootstrap() {
  const httpsOptions = {
    key: fs.readFileSync(process.env.SSL_KEY_PATH),
    cert: fs.readFileSync(process.env.SSL_CERT_PATH),
  };

  // TODO: Utworz aplikacje z httpsOptions
  // const app = await NestFactory.create(AppModule, { httpsOptions });

  // 2. Helmet - naglowki bezpieczenstwa
  // app.use(helmet({
  //   contentSecurityPolicy: {
  //     directives: {
  //       defaultSrc: ["'self'"],
  //       scriptSrc: ["'self'"],
  //     },
  //   },
  //   hsts: { maxAge: 31536000, includeSubDomains: true },
  //   frameguard: { action: 'deny' },
  // }));

  // 3. CORS dla produkcji
  // app.enableCors({
  //   origin: process.env.CORS_ORIGINS?.split(','),
  //   methods: ['GET', 'POST', 'PUT', 'DELETE'],
  //   credentials: true,
  // });
}

// 4. Rate Limiting z @nestjs/throttler
@Module({
  imports: [
    ThrottlerModule.forRoot([
      { name: 'short', ttl: 1000, limit: 3 },
      { name: 'long', ttl: 60000, limit: 100 },
    ]),
  ],
  providers: [
    { provide: APP_GUARD, useClass: ThrottlerGuard },
  ],
})
export class SecurityModule {}

// TODO: Dodaj Helmet middleware w SecurityModule
// TODO: Skonfiguruj CORS z lista dozwolonych domen
// TODO: Dodaj CSRF protection dla endpointow z cookies

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Helmet.js w aplikacji NestJS służy do:

  2. 2. @nestjs/throttler w NestJS służy do:

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Zaimplementuj SecurityModule z ThrottlerModule, Helmet middleware i konfiguracją CORS dla produkcji

  • Układanie w pionie

    Uporządkuj warstwy zabezpieczeń aplikacji NestJS od najniższej (transport) do najwyższej (aplikacja):

  1. PytanieRola Helmet.js w NestJS
  2. PytanieCel @nestjs/throttler
  3. Zadanie z kodemPraktyka: Konfiguracja zabezpieczeń HTTPS
  4. PytanieNagłówek HSTS
  5. Ułóż w kolejnościKolejność warstw bezpieczeństwa HTTP

Przydatne artykuły