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

Disable CSP entirely — the straightforward choice when every response is application/json:

app.use(helmet({ contentSecurityPolicy: false }));

Or keep a minimal CSP as defense-in-depth for the HTML you didn't mean to serve — Express's default error handler, a stack trace leaking into a response, or a status/docs page mounted on the same origin can still render as HTML. A default-src 'none' policy costs nothing and blocks script execution if that ever happens:

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'none'"], // nothing is expected to load — there's no HTML to protect otherwise
      },
    },
    crossOriginEmbedderPolicy: false, // disable if serving assets to other origins
  })
);

If your service ever serves actual HTML (a server-rendered admin panel, a docs UI), that's when a real, scoped-down CSP — allowing exactly the scripts/styles/images that page needs — earns its keep.

---

CORS: Cross-Origin Resource Sharing

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

npm install cors
npm install -D @types/cors

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

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

The right way — explicit allow list:

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:

# 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.

npm install express-rate-limit

trust proxy: Telling Express Which Hop to Believe

express-rate-limit keys its counter off req.ip. Behind a load balancer or reverse proxy, the TCP connection Express actually sees always comes from that proxy — not the end client — so req.ip is not automatically trustworthy. There are two ways to get this wrong:

• Leave trust proxy unset. req.ip resolves to the load balancer's own address for every request. Every client on the internet collapses into one IP, and therefore one shared rate-limit bucket.
• Set trust proxy: true. Express now trusts the entire X-Forwarded-For chain and reads the left-most entry — which the client supplies. Send X-Forwarded-For: 1.2.3.4 yourself and req.ip becomes whatever you typed.

Rate limiting without trust proxy configured is like a bouncer checking IDs off a photo that anyone in line can hand him themselves — behind a load balancer, req.ip is whatever the client claims in X-Forwarded-For unless you tell Express which hop to actually trust.

The fix is to tell Express exactly how many hops to trust, so it reads the one entry your own infrastructure appended and ignores anything the client tried to prepend:

// src/app.ts — set this before any middleware that reads req.ip
// Trust exactly one hop: the load balancer/reverse proxy in front of this app.
app.set('trust proxy', 1);

If there are multiple proxies in the chain (CDN → load balancer → app), set the number to match, or pass the specific trusted IP ranges instead of a hop count.

Production story: On a payments gateway running behind an AWS ALB, express-rate-limit was rolled out specifically to stop brute-force login attempts — and brute-force attempts sailed straight through anyway. Every request Express saw arrived from the ALB's single internal IP, so the entire internet shared one 100-request-per-window bucket: legitimate traffic exhausted it constantly, and an actual attacker just had to stay under the same shared ceiling everyone else was drawing from too. The fix was app.set('trust proxy', 1), which made req.ip resolve to the correct forwarded-for hop — the real client — instead of the load balancer.

Global rate limit — apply to all routes:

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:

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:

// 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:

npm install rate-limit-redis ioredis

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),
  }),
});

---

Secure Cookie Flags

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

// 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:

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

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

CSRF Tokens for Non-Cookie Mutation Paths

sameSite: 'strict' blocks the classic CSRF attack — but only for requests that rely on the browser attaching the cookie automatically. Any mutating endpoint that authenticates a different way (a mobile client sending a bearer token in an Authorization header, a server-to-server call) sits outside sameSite's protection, because there's no cookie for the browser to withhold in the first place — a bearer token can't be attached by a cross-site page the way a cookie can.

The gap that actually matters: an endpoint that accepts both a bearer token and a cookie, a common pattern when the same API serves a web frontend and a mobile app. The cookie-authenticated path there still needs explicit CSRF protection — sameSite alone doesn't cover older browsers or proxies that strip the attribute.

The standard defense is a synchronizer token the frontend must read and echo back on every mutating request:

npm install csrf-csrf

// src/middleware/csrf.ts
import { doubleCsrf } from 'csrf-csrf';
import { env } from '../config/env.js';
 
export const { generateToken, doubleCsrfProtection } = doubleCsrf({
  getSecret: () => env.JWT_ACCESS_SECRET,
  cookieName: 'csrf-token',
  cookieOptions: { sameSite: 'strict', secure: env.NODE_ENV === 'production' },
});
 
// GET route the frontend calls once to obtain a token
router.get('/csrf-token', (req, res) => {
  res.json({ csrfToken: generateToken(req, res) });
});
 
// Apply to cookie-authenticated mutation routes only —
// bearer-token-only routes don't need it
router.post('/profile', doubleCsrfProtection, profileController.update);

An attacker's cross-site page can still trigger the cookie-carrying request, but it cannot read the token to include in the X-CSRF-Token header, so the request is rejected.

---

Additional Security Practices

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

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

Sanitise MongoDB/NoSQL injection (if using MongoDB):

npm install express-mongo-sanitize

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:

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:

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);

That's for the rare case where the app terminates TLS itself. The far more common need is the opposite: the app sits behind a TLS-terminating proxy and must reject or redirect any request that reaches it over plain HTTP — someone hits http://myapp.com directly, or the proxy is misconfigured. req.secure alone doesn't work here: it only reflects TLS on the app's own socket, which behind a proxy is always plain HTTP. Check the header the proxy sets instead:

// src/middleware/enforceHttps.ts
import { Request, Response, NextFunction } from 'express';
import { env } from '../config/env.js';
 
export function enforceHttps(req: Request, res: Response, next: NextFunction) {
  if (env.NODE_ENV !== 'production') return next();
 
  // req.secure reflects x-forwarded-proto too, but only once trust proxy
  // is configured (see the Rate Limiting section) — otherwise Express
  // ignores the header and this check always falls through to false.
  const isSecure = req.secure || req.headers['x-forwarded-proto'] === 'https';
 
  if (!isSecure) {
    return res.redirect(301, `https://${req.headers.host}${req.originalUrl}`);
  }
 
  next();
}

// src/app.ts — after trust proxy is set, before routes
app.set('trust proxy', 1);
app.use(enforceHttps);

---

Putting It Together: Security Middleware Stack

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

// 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.

---