Rate Limiting & Encryption

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { APP_GUARD } from '@nestjs/core';
import { ThrottlerGuard, ThrottlerModule, seconds } from '@nestjs/throttler';
import { BooksController, ReviewsController } from './books.controller.js';

@Module({
  imports: [
    ConfigModule.forRoot({ ignoreEnvFile: true, isGlobal: true }),
    ThrottlerModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        throttlers: [
          { name: 'short', ttl: seconds(1), limit: config.get<number>('THROTTLE_SHORT_LIMIT', 3) },
          { name: 'long', ttl: seconds(60), limit: config.get<number>('THROTTLE_LONG_LIMIT', 5) },
        ],
        errorMessage: 'Slow down: too many requests',
      }),
    }),
  ],
  controllers: [BooksController, ReviewsController],
  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
})
export class RateLimitingModule {}

curl -i http://localhost:3000/books

HTTP/1.1 200 OK
X-RateLimit-Limit-short: 3
X-RateLimit-Remaining-short: 2
X-RateLimit-Reset-short: 1
X-RateLimit-Limit-long: 5
X-RateLimit-Remaining-long: 4
X-RateLimit-Reset-long: 60

HTTP/1.1 429 Too Many Requests
Retry-After-short: 1

{ "statusCode": 429, "message": "Slow down: too many requests" }

import { Body, Controller, Get, Post } from '@nestjs/common';
import { SkipThrottle, Throttle } from '@nestjs/throttler';

@Controller('books')
export class BooksController {
  // Uses every named limit from the module (short + long).
  @Get()
  findAll() {
    return [{ id: 1, title: 'Dune' }];
  }

  // Overrides only the "short" limit: 2 requests per 10 seconds.
  @Throttle({ short: { limit: 2, ttl: 10_000 } })
  @Post('search')
  search(@Body() body: { q: string }) {
    return { q: body.q, hits: 1 };
  }

  // Skips both named throttlers. A bare @SkipThrottle() only skips the one named "default".
  @SkipThrottle({ short: true, long: true })
  @Get('health')
  health() {
    return { status: 'ok' };
  }
}

// Skips both throttlers on the class, except that "long" is switched back on for one route.
@SkipThrottle({ short: true, long: true })
@Controller('reviews')
export class ReviewsController {
  @SkipThrottle({ long: false })
  @Get()
  findAll() {
    return [];
  }

  @Get('latest')
  latest() {
    return [];
  }
}

import { Body, Controller, Module, Post } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { Throttle, ThrottlerGuard, ThrottlerModule, minutes, seconds } from '@nestjs/throttler';

@Controller('auth')
class AuthController {
  // 2 attempts per minute; after that the caller is blocked for 15 minutes.
  @Throttle({ default: { limit: 2, ttl: seconds(60), blockDuration: minutes(15) } })
  @Post('login')
  login(@Body() body: { email: string }) {
    return { ok: true, email: body.email };
  }
}

@Module({
  imports: [
    ThrottlerModule.forRoot({
      throttlers: [{ ttl: seconds(60), limit: 100 }],
      // never throttle the load balancer's probe
      ignoreUserAgents: [/^kube-probe\//],
      // or skip based on anything in the request
      skipIf: (context) => context.switchToHttp().getRequest().headers['x-internal'] === '1',
    }),
  ],
  controllers: [AuthController],
  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
})
export class LoginRateLimitModule {}

import { Injectable } from '@nestjs/common';
import { ThrottlerGuard } from '@nestjs/throttler';

@Injectable()
export class ThrottlerByUserGuard extends ThrottlerGuard {
  // Track authenticated users by id and everyone else by IP address.
  // With "trust proxy" configured, req.ip is already the real client address.
  protected async getTracker(req: Record<string, any>): Promise<string> {
    return req.user?.id ? `user:${req.user.id}` : req.ip;
  }
}

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

const ALGORITHM = 'aes-256-gcm';
const IV_LENGTH = 12; // 96-bit nonce, the size GCM is designed for
const TAG_LENGTH = 16;

@Injectable()
export class EncryptionService {
  private readonly key: Buffer;

  constructor(config: ConfigService) {
    // ENCRYPTION_KEY: 64 hex characters, generated with `openssl rand -hex 32`
    this.key = Buffer.from(config.getOrThrow<string>('ENCRYPTION_KEY'), 'hex');
    if (this.key.length !== 32) {
      throw new Error('ENCRYPTION_KEY must be 32 bytes (64 hex characters)');
    }
  }

  /** Returns base64(iv || ciphertext || authTag). */
  encrypt(plaintext: string): string {
    const iv = randomBytes(IV_LENGTH); // a fresh nonce for every message
    const cipher = createCipheriv(ALGORITHM, this.key, iv, { authTagLength: TAG_LENGTH });
    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
    return Buffer.concat([iv, ciphertext, cipher.getAuthTag()]).toString('base64');
  }

  decrypt(payload: string): string {
    const data = Buffer.from(payload, 'base64');
    if (data.length < IV_LENGTH + TAG_LENGTH) throw new Error('Invalid payload');
    const iv = data.subarray(0, IV_LENGTH);
    const tag = data.subarray(data.length - TAG_LENGTH);
    const ciphertext = data.subarray(IV_LENGTH, data.length - TAG_LENGTH);
    const decipher = createDecipheriv(ALGORITHM, this.key, iv, { authTagLength: TAG_LENGTH });
    decipher.setAuthTag(tag);
    // final() throws "Unsupported state or unable to authenticate data" if anything was altered
    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
  }
}

openssl rand -hex 32   # prints 64 hex characters: store as ENCRYPTION_KEY in the secret store

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { Argon2Hasher, BcryptHasher } from './bcrypt-argon2.service.js';
import { EncryptionService } from './encryption.service.js';
import { ScryptPasswordHasher } from './password-hasher.service.js';

@Module({
  imports: [ConfigModule.forRoot({ ignoreEnvFile: true, isGlobal: true })],
  providers: [EncryptionService, ScryptPasswordHasher, BcryptHasher, Argon2Hasher],
  exports: [EncryptionService, ScryptPasswordHasher, BcryptHasher, Argon2Hasher],
})
export class EncryptionModule {}

import { Injectable } from '@nestjs/common';
import { randomBytes, scrypt, timingSafeEqual, ScryptOptions } from 'node:crypto';

// OWASP-recommended scrypt parameters: N=2^17, r=8, p=1 (about 128 MiB per hash)
const PARAMS = { N: 2 ** 17, r: 8, p: 1, maxmem: 256 * 1024 * 1024 } satisfies ScryptOptions;
const KEY_LENGTH = 64;

const scryptAsync = (password: string, salt: Buffer, keylen: number, options: ScryptOptions) =>
  new Promise<Buffer>((resolve, reject) =>
    scrypt(password.normalize('NFKC'), salt, keylen, options, (err, key) => (err ? reject(err) : resolve(key))),
  );

@Injectable()
export class ScryptPasswordHasher {
  /** Returns `scrypt$N$r$p$salt$hash` so the parameters travel with the hash. */
  async hash(password: string): Promise<string> {
    const salt = randomBytes(16);
    const derived = await scryptAsync(password, salt, KEY_LENGTH, PARAMS);
    return ['scrypt', PARAMS.N, PARAMS.r, PARAMS.p, salt.toString('base64'), derived.toString('base64')].join('$');
  }

  async verify(password: string, stored: string): Promise<boolean> {
    const [scheme, n, r, p, salt, hash] = stored.split('$');
    if (scheme !== 'scrypt' || !salt || !hash) return false;
    const expected = Buffer.from(hash, 'base64');
    const derived = await scryptAsync(password, Buffer.from(salt, 'base64'), expected.length, {
      N: Number(n), r: Number(r), p: Number(p), maxmem: PARAMS.maxmem,
    });
    return timingSafeEqual(derived, expected); // constant-time comparison
  }
}

npm i argon2 bcrypt
npm i -D @types/bcrypt

import { Injectable } from '@nestjs/common';
import * as argon2 from 'argon2';
import * as bcrypt from 'bcrypt';

@Injectable()
export class BcryptHasher {
  hash(password: string): Promise<string> {
    return bcrypt.hash(password, 12); // cost factor 12; only the first 72 bytes are used
  }
  verify(password: string, hash: string): Promise<boolean> {
    return bcrypt.compare(password, hash);
  }
}

@Injectable()
export class Argon2Hasher {
  hash(password: string): Promise<string> {
    // argon2id is the default type; options are tuned per the OWASP cheat sheet
    return argon2.hash(password, { type: argon2.argon2id, memoryCost: 19456, timeCost: 2, parallelism: 1 });
  }
  verify(password: string, hash: string): Promise<boolean> {
    return argon2.verify(hash, password);
  }
  needsRehash(hash: string): boolean {
    return argon2.needsRehash(hash, { memoryCost: 19456, timeCost: 2, parallelism: 1 });
  }
}