Module P-6·22 min read

12-factor app config, Helmet security headers, express-rate-limit, CORS, HTTPS enforcement, secure cookie flags, and secrets management patterns.

Module P-6 — Configuration, Security Hardening, and Rate Limiting

Q: What is the Twelve-Factor App methodology's rule regarding configuration management?

Store configuration strictly in the environment, never in the source code. — The 12-factor approach dictates that any value that changes between environments (dev, staging, prod) or any credential should be stored in environment variables, never hardcoded in source control.

Q: Why is it dangerous to simply use `app.use(cors())` without passing any options in a production environment?

It allows requests from absolutely any origin, potentially exposing your API to malicious sites. — Using `cors()` with no arguments configures the server to accept cross-origin requests from *any* domain (`*`). In production, you must explicitly specify an allowed origins list.

Q: When storing a refresh token in a cookie, which flag is responsible for ensuring that malicious JavaScript (XSS) cannot read the token?

`httpOnly` — The `httpOnly` flag instructs the browser that the cookie should not be accessible via `document.cookie` or other JavaScript APIs, preventing XSS attacks from stealing the token.

What this module covers: An API that works on your machine is not a production API. This module covers the 12-factor approach to configuration so secrets never end up in source control, the HTTP security headers that close the most common attack vectors, CORS configured correctly so browsers can reach your API, rate limiting that stops brute-force attacks, and the secure cookie flags that protect tokens from XSS. These are not optional polish — they are the baseline that separates hobby projects from production systems.

12-Factor Configuration: No Secrets in Code

The Twelve-Factor App methodology's rule on configuration: store config in the environment, never in the code. Every value that changes between environments (dev, staging, production) is configuration. Every credential is configuration.

bash

# Wrong — committing a secret, even if you delete it later, it's in git history
const DB_URL = 'postgresql://admin:supersecret@prod-db:5432/myapp';

# Right — read from the environment
const DB_URL = process.env.DATABASE_URL;

dotenv for local development

bash

npm install dotenv

bash

# .env — never commit this file
DATABASE_URL=postgresql://localhost:5432/myapp_dev
JWT_ACCESS_SECRET=local-dev-secret-at-least-32-characters-long
JWT_REFRESH_SECRET=local-refresh-secret-also-32-characters-long
PORT=3000
NODE_ENV=development
REDIS_URL=redis://localhost:6379

bash

# .env.example — commit this file, no real values
DATABASE_URL=postgresql://localhost:5432/myapp_dev
JWT_ACCESS_SECRET=generate-with-node-e-crypto-randomBytes-64-hex
JWT_REFRESH_SECRET=generate-with-node-e-crypto-randomBytes-64-hex
PORT=3000
NODE_ENV=development
REDIS_URL=redis://localhost:6379

bash

# .gitignore — must include
.env
.env.local
.env.*.local

Load dotenv once, at the very start of your application:

typescript

// src/index.ts — first line before any other imports
import 'dotenv/config';

// or equivalently:
import dotenv from 'dotenv';
dotenv.config();

Config validation with Zod

Raw process.env is untyped — every value is string | undefined. Validate it at startup so the app fails fast with a clear error instead of silently failing later:

typescript

// src/config/env.ts
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_ACCESS_SECRET: z.string().min(32, 'JWT_ACCESS_SECRET must be at least 32 characters'),
  JWT_REFRESH_SECRET: z.string().min(32, 'JWT_REFRESH_SECRET must be at least 32 characters'),
  JWT_ACCESS_EXPIRY: z.string().default('15m'),
  JWT_REFRESH_EXPIRY: z.string().default('7d'),
  REDIS_URL: z.string().url().optional(),
  CORS_ORIGIN: z.string().default('http://localhost:5173'),
  RATE_LIMIT_WINDOW_MS: z.coerce.number().default(15 * 60 * 1000), // 15 min
  RATE_LIMIT_MAX: z.coerce.number().default(100),
});

// Parse immediately — if invalid, throw with clear error message and exit
const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('❌ Invalid environment configuration:');
  console.error(parsed.error.format());
  process.exit(1);
}

export const env = parsed.data;
// env.PORT is number, not string | undefined
// env.DATABASE_URL is string, not string | undefined

Import env instead of process.env everywhere:

typescript

// Before
const port = parseInt(process.env.PORT ?? '3000');

// After
import { env } from './config/env.js';
const port = env.PORT; // already a number

Helmet: HTTP Security Headers

Helmet sets HTTP response headers that tell browsers how to handle your content safely. It prevents a class of attacks that have nothing to do with your application logic.

bash

npm install helmet

typescript

import helmet from 'helmet';

app.use(helmet());

That one line sets these headers (among others):

Header	What it does
`Content-Security-Policy`	Restricts which resources the browser can load — blocks inline script injection
`X-Frame-Options`	Prevents clickjacking (your page can't be embedded in an iframe)
`X-Content-Type-Options: nosniff`	Prevents MIME type sniffing — browser uses declared content type
`Strict-Transport-Security`	Forces HTTPS for future requests (HSTS)
`Referrer-Policy`	Controls how much URL info is sent in the `Referer` header
`X-Permitted-Cross-Domain-Policies`	Blocks Adobe Flash/Acrobat cross-domain requests

For APIs returning JSON, you can relax the CSP since there is no HTML to protect:

typescript

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'"],
        styleSrc: ["'self'"],
        imgSrc: ["'self'", 'data:', 'https:'],
      },
    },
    crossOriginEmbedderPolicy: false, // disable if serving assets to other origins
  })
);

Browsers block cross-origin requests by default. CORS is the mechanism that lets your API tell browsers which origins are allowed.

bash

npm install cors
npm install -D @types/cors

The wrong way — a development shortcut that leaks into production:

typescript

app.use(cors()); // allows ALL origins — never do this in production

The right way — explicit allow list:

typescript

import cors from 'cors';
import { env } from './config/env.js';

const allowedOrigins = env.CORS_ORIGIN.split(',').map(o => o.trim());

app.use(
  cors({
    origin: (origin, callback) => {
      // Allow requests with no origin (mobile apps, curl, Postman, server-to-server)
      if (!origin) return callback(null, true);

      if (allowedOrigins.includes(origin)) {
        callback(null, true);
      } else {
        callback(new Error(`Origin ${origin} not allowed by CORS`));
      }
    },
    credentials: true,           // allow cookies to be sent cross-origin
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
    exposedHeaders: ['X-Request-ID'],  // headers the browser can read
    maxAge: 86400,               // preflight cache: 24 hours
  })
);

In .env:

bash

# Development — your frontend dev server
CORS_ORIGIN=http://localhost:5173

# Production — comma-separated if multiple origins
CORS_ORIGIN=https://myapp.com,https://www.myapp.com

Preflight requests: Before sending a non-simple request (POST with JSON, any DELETE, any custom header), browsers send an OPTIONS preflight to ask permission. Helmet and the cors package handle this automatically. If you see OPTIONS requests failing, check that your CORS config allows the method and headers being used.

Rate Limiting

Without rate limiting, a single client can flood your auth endpoints with thousands of login attempts per second. Rate limiting is the first line of defense against brute force, credential stuffing, and denial-of-service.

bash

npm install express-rate-limit

Global rate limit — apply to all routes:

typescript

import rateLimit from 'express-rate-limit';
import { env } from './config/env.js';

export const globalLimiter = rateLimit({
  windowMs: env.RATE_LIMIT_WINDOW_MS,  // 15 minutes
  max: env.RATE_LIMIT_MAX,              // 100 requests per window
  standardHeaders: true,   // Return rate limit info in RateLimit-* headers
  legacyHeaders: false,     // Disable X-RateLimit-* headers
  message: { error: 'Too many requests, please try again later.' },
  handler: (req, res) => {
    res.status(429).json({ error: 'Too many requests, please try again later.' });
  },
});

Stricter limits for auth endpoints:

typescript

export const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 10,                     // only 10 login attempts per 15 min per IP
  skipSuccessfulRequests: true, // only count failed attempts
  message: { error: 'Too many login attempts. Try again in 15 minutes.' },
});

export const registerLimiter = rateLimit({
  windowMs: 60 * 60 * 1000,  // 1 hour
  max: 5,                      // 5 registrations per hour per IP
  message: { error: 'Too many accounts created. Try again in an hour.' },
});

Apply globally first, then stricter limits on specific routes:

typescript

// src/app.ts
app.use(globalLimiter);

// src/routes/auth.routes.ts
router.post('/login', authLimiter, authController.login);
router.post('/register', registerLimiter, authController.register);
router.post('/refresh', authLimiter, authController.refresh);

Rate limiting with Redis (for multi-server deployments):

The default in-memory store does not share state across processes. If you have two app servers, each has its own counter — a client gets 2× the allowed requests. Use Redis for a shared store:

bash

npm install rate-limit-redis ioredis

typescript

import RedisStore from 'rate-limit-redis';
import Redis from 'ioredis';
import { env } from './config/env.js';

const redis = new Redis(env.REDIS_URL);

export const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 10,
  store: new RedisStore({
    sendCommand: (...args: string[]) => redis.call(...args),
  }),
});

When storing refresh tokens in HTTP-only cookies (recommended over response body), these flags are non-negotiable:

typescript

// src/controllers/auth.controller.ts
import { env } from '../config/env.js';

const isProduction = env.NODE_ENV === 'production';

function setRefreshTokenCookie(res: Response, token: string) {
  res.cookie('refreshToken', token, {
    httpOnly: true,     // JS cannot read this cookie — XSS-proof
    secure: isProduction,  // HTTPS only in production
    sameSite: 'strict', // not sent on cross-site requests — CSRF protection
    maxAge: 7 * 24 * 60 * 60 * 1000,  // 7 days in ms
    path: '/auth',      // only sent to /auth/* routes — not every request
  });
}

export const login = asyncHandler(async (req, res) => {
  const result = await authService.login(req.body);
  setRefreshTokenCookie(res, result.refreshToken);
  res.json({ accessToken: result.accessToken, user: result.user });
});

export const refresh = asyncHandler(async (req, res) => {
  const refreshToken = req.cookies.refreshToken; // need cookie-parser
  if (!refreshToken) throw new UnauthorizedError('Refresh token required');
  const tokens = await authService.refresh(refreshToken);
  setRefreshTokenCookie(res, tokens.refreshToken);
  res.json({ accessToken: tokens.accessToken });
});

export const logout = asyncHandler(async (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (refreshToken) await authService.logout(refreshToken);
  res.clearCookie('refreshToken', { path: '/auth' });
  res.status(204).send();
});

Install cookie-parser to read cookies:

bash

npm install cookie-parser
npm install -D @types/cookie-parser

typescript

import cookieParser from 'cookie-parser';
app.use(cookieParser());

Flag	What it prevents
`httpOnly`	XSS — attacker's injected script can't read the token
`secure`	Token transmitted over cleartext HTTP
`sameSite: strict`	CSRF — browser doesn't send the cookie on cross-site requests
`path: '/auth'`	Token sent on every request, not just auth endpoints

Additional Security Practices

Disable the X-Powered-By header — don't advertise your stack:

typescript

app.disable('x-powered-by');
// Helmet does this automatically — don't need both

Sanitise MongoDB/NoSQL injection (if using MongoDB):

bash

npm install express-mongo-sanitize

typescript

import mongoSanitize from 'express-mongo-sanitize';
app.use(mongoSanitize()); // strips $ and . from req.body, req.query, req.params

Request size limits — prevent large payloads from exhausting memory:

typescript

app.use(express.json({ limit: '10kb' }));    // reject JSON bodies > 10kb
app.use(express.urlencoded({ limit: '10kb', extended: true }));

HTTPS in production — your app should run behind a TLS-terminating reverse proxy (nginx, Cloudflare, AWS ALB). The app itself typically serves HTTP internally. If you need HTTPS at the app level:

typescript

import https from 'https';
import fs from 'fs';

const httpsOptions = {
  key: fs.readFileSync('./certs/privkey.pem'),
  cert: fs.readFileSync('./certs/fullchain.pem'),
};

https.createServer(httpsOptions, app).listen(443);

Putting It Together: Security Middleware Stack

The order matters — helmet and rate limiters should run before routes:

typescript

// src/app.ts
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import cookieParser from 'cookie-parser';
import { globalLimiter } from './middleware/rateLimiter.js';
import { requestId } from './middleware/requestId.js';
import { errorHandler } from './middleware/errorHandler.js';

const app = express();

// Security — first
app.use(helmet());
app.use(cors(corsOptions));

// Parsing
app.use(express.json({ limit: '10kb' }));
app.use(express.urlencoded({ extended: true, limit: '10kb' }));
app.use(cookieParser());

// Rate limiting + request tracking
app.use(globalLimiter);
app.use(requestId);

// Routes
app.use('/auth', authRouter);
app.use('/users', usersRouter);
app.use('/posts', postsRouter);

// Error handler — last
app.use(errorHandler);

export default app;

Summary

12-factor config: all env-specific values in environment variables, validated with Zod at startup, never in code.
Helmet: one line that sets a dozen security headers — Content-Security-Policy, X-Frame-Options, HSTS, and more. Always use it.
CORS: explicit origin allow list from environment variables. Never cors() with no options in production.
Rate limiting: global limiter for all routes, stricter limiter on auth endpoints. Use Redis store when running multiple servers.
HTTP-only cookies: store refresh tokens in httpOnly; Secure; SameSite=Strict cookies with a scoped path — the trifecta that blocks XSS, HTTPS downgrade, and CSRF.
Request size limits: express.json({ limit: '10kb' }) prevents memory exhaustion from large payloads.

Next: connecting external services — Redis caching with the cache-aside pattern, sending email, uploading files to object storage, and making outbound HTTP requests to third-party APIs.

Knowledge Check

What is the Twelve-Factor App methodology's rule regarding configuration management?

Why is it dangerous to simply use app.use(cors()) without passing any options in a production environment?

When storing a refresh token in a cookie, which flag is responsible for ensuring that malicious JavaScript (XSS) cannot read the token?

Test your knowledge with more question sets

PreviousModule P-5: Testing Node.js Applications Next Module P-7: Connecting External Services and Caching

Discussion

Join the discussion

Loading comments...

Module P-6 — Configuration, Security Hardening, and Rate Limiting

12-Factor Configuration: No Secrets in Code

dotenv for local development

Config validation with Zod

Helmet: HTTP Security Headers

CORS: Cross-Origin Resource Sharing

Rate Limiting

Secure Cookie Flags

Additional Security Practices

Putting It Together: Security Middleware Stack

Summary

Test your knowledge with more question sets

Discussion