crypto — Cryptography

Secure hashing, HMACs, random data, UUIDs, and encryption in Node.js — the crypto built-in module.

What it is, in plain English: The crypto module provides cryptographic functionality in Node.js. Use crypto.randomBytes() for cryptographically secure random data. Use crypto.randomUUID() for UUIDs. createHash() creates MD5, SHA-1, SHA-256 hashes. createHmac() creates signed hashes for API authentication. For passwords specifically, use scrypt or bcrypt (from npm) — never plain SHA hashes.

Where this bites you

An HMAC signs exact bytes. A webhook receiver that parses the JSON body and then calls JSON.stringify() to check the signature is hashing different bytes: spacing, key order and number formatting can all change in the round trip. Every genuine request then fails verification, and the usual "fix" (turning verification off) is far worse than the bug.

import { createHmac, timingSafeEqual } from "crypto";

function verifyHMAC(received, payload, secret) {
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

const SECRET = "my-secret";
// what the sender actually sent, byte for byte (note the spaces):
const rawBody   = '{"event": "push", "repo": "codex"}';
const signature = createHmac("sha256", SECRET).update(rawBody).digest("hex");

// receiver: parse first, then re-serialise to check the signature
const parsed = JSON.parse(rawBody);
console.log(verifyHMAC(signature, JSON.stringify(parsed), SECRET));
console.log(JSON.stringify(parsed));
// false
// {"event":"push","repo":"codex"}      <- not the bytes that were signed

Secure random data and hashing

Never use Math.random() for security. It's not cryptographically secure. Always use crypto.randomBytes() or crypto.randomUUID() for anything security-related.

Secure random data

import { randomBytes, randomUUID, randomInt } from "crypto";

// Random bytes (for tokens, salts, keys):
const token = randomBytes(32).toString("hex");   // 64-char hex string
const salt  = randomBytes(16).toString("base64"); // 24-char base64 string

console.log("Token:", token);  // "a3f8c2..."
console.log("Salt:",  salt);

// UUID — universally unique identifier (v4):
const id = randomUUID();
console.log("UUID:", id);  // "110e8400-e29b-41d4-a716-446655440000"

// Random integer in range [min, max):
const roll = randomInt(1, 7);  // dice: 1-6
console.log("Dice:", roll);

Hashing — one-way fingerprinting

import { createHash } from "crypto";

// SHA-256 hash of a string:
function sha256(data) {
  return createHash("sha256").update(data, "utf-8").digest("hex");
}

console.log(sha256("hello"));  // "2cf24dba..." (always same for same input)
console.log(sha256("hello"));  // same
console.log(sha256("Hello"));  // completely different — case sensitive!

// SHA-256 of a file:
import { readFileSync } from "fs";
const fileHash = createHash("sha256")
  .update(readFileSync("document.pdf"))
  .digest("hex");
// Use to verify file integrity (checksums)

// Common hash algorithms:
// sha256  — most common, 256-bit output ✓
// sha512  — stronger, 512-bit output ✓
// sha1    — deprecated, collision-prone ✗
// md5     — broken for security, ok for checksums ✗

HMAC — signed hashes for authentication

import { createHmac, timingSafeEqual } from "crypto";

// HMAC = Hash + Secret Key → verifiable signature
const SECRET  = process.env.WEBHOOK_SECRET ?? "my-secret";
const payload = JSON.stringify({ event: "push", repo: "codex" });

// Sign:
const signature = createHmac("sha256", SECRET)
  .update(payload)
  .digest("hex");

console.log("Signature:", signature);

// Verify (ALWAYS use timingSafeEqual — prevents timing attacks):
function verifyHMAC(received, payload, secret) {
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);  // constant-time comparison
}

console.log(verifyHMAC(signature, payload, SECRET));  // true

The verifyHMAC() above is correct. What matters is what you pass to it: the raw request body, exactly as it arrived, before any parsing. With a framework, that means asking for the raw body on webhook routes (for example express.raw({ type: "application/json" })). Verify first, then parse:

import { createHmac, timingSafeEqual } from "crypto";

function verifyHMAC(received, payload, secret) {
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

const SECRET = "my-secret";
const rawBody   = '{"event": "push", "repo": "codex"}';
const signature = createHmac("sha256", SECRET).update(rawBody).digest("hex");

// receiver: verify the RAW bytes first, parse only after they check out
if (verifyHMAC(signature, rawBody, SECRET)) {
  const event = JSON.parse(rawBody);
  console.log("verified:", event.event);
}
// verified: push

Try It Yourself

// crypto module — Node.js cryptography
// import { randomBytes, randomUUID, createHash, createHmac, timingSafeEqual } from "crypto";

// ─── RANDOM DATA ──────────────────────────────────────────────────────────────
// NEVER use Math.random() for security — it's not cryptographically secure!

// Secure random bytes:
// const bytes = randomBytes(32);
// console.log(bytes.toString("hex"));    // 64 hex chars
// console.log(bytes.toString("base64")); // 44 base64 chars

// Random UUID (version 4):
// console.log(randomUUID()); // "110e8400-e29b-41d4-a716-446655440000"

// Simulate (in browser without crypto module):
const mockUUID = () => "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
  const r = Math.random() * 16 | 0;
  return (c === "x" ? r : (r & 0x3 | 0x8)).toString(16);
});

// ─── HASHING ─────────────────────────────────────────────────────────────────
// Hashing is ONE-WAY — you can't recover the original from the hash

function sha256(data) {
  // Browser Web Crypto API equivalent:
  // const encoder = new TextEncoder();
  // const buffer = await crypto.subtle.digest("SHA-256", encoder.encode(data));
  // return Array.from(new Uint8Array(buffer)).map(b=>b.toString(16).padStart(2,"0")).join("");

// Simple demo (NOT a real hash — just for illustration):
  let hash = 5381;
  for (let i = 0; i < data.length; i++) hash = (hash * 33 ^ data.charCodeAt(i)) >>> 0;
  return hash.toString(16).padStart(8, "0");
}

console.log("sha256('hello'):", sha256("hello"));
console.log("sha256('hello'):", sha256("hello"));  // same input → same output
console.log("sha256('Hello'):", sha256("Hello"));  // different case → different hash
console.log("sha256('hello!'):", sha256("hello!")); // one char different → completely different

// ─── NODE.JS CODE PATTERNS ───────────────────────────────────────────────────
const CRYPTO_EXAMPLES = `
// Random token (for password reset, API keys):
const token = randomBytes(32).toString("hex");  // 64-char hex string

// SHA-256 hash:
const hash = createHash("sha256").update("data").digest("hex");

// HMAC (signed hash — for webhooks, tokens):
const sig = createHmac("sha256", secretKey).update(payload).digest("hex");

// Verify HMAC safely (prevents timing attacks):
const isValid = timingSafeEqual(Buffer.from(received, "hex"), Buffer.from(expected, "hex"));

// UUID:
const id = randomUUID();  // "550e8400-e29b-41d4-a716-446655440000"

// Password hashing (use scrypt or bcrypt — NEVER plain sha256 for passwords):
const { key } = await scrypt(password, salt, 64);  // 64-byte key
`;

console.log("Node.js crypto patterns:");
console.log(CRYPTO_EXAMPLES.trim());

Password hashing and symmetric encryption

Password hashing with scrypt

// NEVER store passwords as plain SHA hashes — use scrypt or bcrypt
// scrypt is built into Node.js (bcrypt requires npm install)

import { scrypt, randomBytes, timingSafeEqual } from "crypto";
import { promisify } from "util";
const scryptAsync = promisify(scrypt);

const SALT_LEN  = 32;
const KEY_LEN   = 64;

async function hashPassword(password) {
  const salt = randomBytes(SALT_LEN);
  const key  = await scryptAsync(password, salt, KEY_LEN);
  return `${salt.toString("hex")}:${key.toString("hex")}`;
}

async function verifyPassword(password, stored) {
  const [saltHex, keyHex] = stored.split(":");
  const salt = Buffer.from(saltHex, "hex");
  const key  = await scryptAsync(password, salt, KEY_LEN);
  return timingSafeEqual(key, Buffer.from(keyHex, "hex"));
}

const stored = await hashPassword("my_password");
console.log("Stored:", stored);
console.log("Valid:", await verifyPassword("my_password",  stored));  // true
console.log("Invalid:", await verifyPassword("wrong_pass", stored)); // false

AES-256-GCM symmetric encryption

import { createCipheriv, createDecipheriv, randomBytes } from "crypto";

const ALGORITHM = "aes-256-gcm";
const KEY_LEN   = 32;  // 256 bits

function encrypt(plaintext, key) {
  const iv         = randomBytes(12);  // 96-bit IV for GCM
  const cipher     = createCipheriv(ALGORITHM, key, iv);
  const encrypted  = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
  const authTag    = cipher.getAuthTag();  // GCM authentication tag
  return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`;
}

function decrypt(ciphertext, key) {
  const [ivHex, tagHex, dataHex] = ciphertext.split(":");
  const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(ivHex, "hex"));
  decipher.setAuthTag(Buffer.from(tagHex, "hex"));
  return Buffer.concat([decipher.update(Buffer.from(dataHex, "hex")), decipher.final()]).toString("utf8");
}

const key       = randomBytes(KEY_LEN);
const encrypted = encrypt("Secret message", key);
const decrypted = decrypt(encrypted, key);
console.log("Encrypted:", encrypted);
console.log("Decrypted:", decrypted);  // "Secret message"

Web Crypto API compatibility and spec

// Node.js 15+ has webcrypto compatible API (browser-compatible):
const { subtle } = globalThis.crypto;  // or: import { webcrypto } from "crypto"

// SHA-256 via Web Crypto (browser AND Node.js):
async function sha256WebCrypto(data) {
  const encoded = new TextEncoder().encode(data);
  const buffer  = await subtle.digest("SHA-256", encoded);
  return Array.from(new Uint8Array(buffer))
    .map(b => b.toString(16).padStart(2, "0")).join("");
}

// AES-GCM key generation and encryption via Web Crypto:
const key = await subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
const iv  = globalThis.crypto.getRandomValues(new Uint8Array(12));
const enc = await subtle.encrypt({ name: "AES-GCM", iv }, key,
  new TextEncoder().encode("secret"));

// Key derivation — PBKDF2 (for password-based keys):
const baseKey = await subtle.importKey("raw", new TextEncoder().encode(password),
  { name: "PBKDF2" }, false, ["deriveKey"]);
const derivedKey = await subtle.deriveKey(
  { name: "PBKDF2", salt, iterations: 100000, hash: "SHA-256" },
  baseKey, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]
);

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.