Kurs NestJS · Moduł 9: Deployment i infrastruktura
SSL/TLS i HTTPS Configuration - tarcza obronna Imperium
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. Helmet.js w aplikacji NestJS służy do:
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):