crypto

node:crypto provides hashing, HMAC, random bytes, and ciphers for tokens, webhook verification, and encryption - use built-in APIs before adding npm crypto wrappers.

Recipe

import { createHmac, randomBytes, timingSafeEqual, randomUUID } from 'node:crypto';
 
const token = randomBytes(32).toString('base64url');
const id = randomUUID();
 
const sig = createHmac('sha256', secret).update(body).digest('hex');

When to reach for this:

• Signing Stripe/Twilio webhooks
• Generating session tokens and CSRF secrets
• Password hashing (prefer scrypt/argon2 via crypto or dedicated lib)
• TLS cert operations outside scope - use platform/KMS for keys

Working Example

import { createHmac, randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
import { promisify } from 'node:util';
 
const scryptAsync = promisify(scrypt);
 
export function signPayload(body: Buffer, secret: string): string {
  return createHmac('sha256', secret).update(body).digest('hex');
}
 
export function verifySignature(body: Buffer, secret: string, providedHex: string): boolean {
  const expected = Buffer.from(signPayload(body, secret), 'hex');
  const provided = Buffer.from(providedHex, 'hex');
  if (expected.length !== provided.length) return false;
  return timingSafeEqual(expected, provided);
}
 
export async function hashPassword(password: string, salt?: Buffer): Promise<{ salt: Buffer; hash: Buffer }> {
  const s = salt ?? randomBytes(16);
  const hash = (await scryptAsync(password, s, 64)) as Buffer;
  return { salt: s, hash };
}

import { webcrypto } from 'node:crypto';
 
const key = await webcrypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 },
  true,
  ['encrypt', 'decrypt'],
);

What this demonstrates:

• HMAC-SHA256 pattern for webhooks - compare with timingSafeEqual on digests
• scrypt via promisify for password storage with per-user salt
• Web Crypto subtle for AES-GCM when interoperating with browser crypto
• Never log secrets or full signatures in errors

Deep Dive

How It Works

• Hash (sha256) - one-way fingerprint - not for passwords alone.
• HMAC - keyed hash for integrity + authenticity of message.
• CSPRNG - randomBytes, randomUUID for tokens.
• scrypt/pbkdf2 - password stretching - tune cost params with hardware baseline.

Algorithm Pick

TypeScript Notes

import { createHash } from 'node:crypto';
 
export function sha256Hex(input: string): string {
  return createHash('sha256').update(input, 'utf8').digest('hex');
}

Gotchas

• SHA256 alone for passwords - too fast - brute force. Fix: scrypt/argon2 with salt.
• Timing compare on strings with === - leak. Fix: compare HMAC digests with timingSafeEqual.
• Reused IV/nonce in AES-GCM - catastrophic crypto failure. Fix: random 12-byte nonce per message.
• Hard-coded secrets in source - leak via repo. Fix: env/KMS + rotation.
• Math.random for tokens - predictable. Fix: randomBytes only.

Alternatives

FAQs

Related

• Buffer Security - secret handling
• Webhook Verification - HMAC webhooks
• Security Basics - broader posture
• Prototype Pollution - not crypto but security neighbor

External Related Links

• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Best Practices (GitHub) - Curated production best practices.
• NodeSource Blog & Resources - Enterprise Node.js performance and security content.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

49454e4f4d5f434e4f5904434556494d4345121f1356181a181c1a1d