Crypto, Passwords & Secrets

import * as crypto from 'node:crypto';
const { randomUUID, randomBytes, randomInt } = crypto;

console.log('uuid v4  ', randomUUID());
console.log('uuid v7  ', typeof crypto.randomUUIDv7 === 'function' ? crypto.randomUUIDv7() : '(needs Node.js 26)');
console.log('token    ', randomBytes(32).toString('base64url').length, 'chars of base64url');
console.log('pin      ', String(randomInt(0, 1_000_000)).padStart(6, '0'));

// Asynchronous form: the callback runs after the bytes are produced on the thread pool.
randomBytes(16, (err, buf) => {
  if (err) throw err;
  console.log('async    ', buf.length, 'bytes');
});

uuid v4   649f5468-…
uuid v7   01a10405-…
token     43 chars of base64url
pin       <six random digits>
async     16 bytes

node -p "crypto.randomBytes(32).toString('hex')"

import { createHash, hash, createHmac, timingSafeEqual } from 'node:crypto';
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';

// One-shot (stable since 25.5.0 / 24.13.1; added 21.7 / 20.12) and incremental forms agree.
const oneShot = hash('sha256', 'bookshelf');
const incremental = createHash('sha256').update('book').update('shelf').digest('hex');
console.log(oneShot.slice(0, 4) + '…' + oneShot.slice(-4), oneShot === incremental);
console.log(hash('sha256', 'bookshelf', 'base64url').length, 'chars as base64url');
// XOF functions take an output length (outputLength option, added in 24.4.0)
console.log(createHash('shake256', { outputLength: 8 }).update('bookshelf').digest().length, 'bytes of shake256');

// Hash a file as a stream
const h = createHash('sha256');
await pipeline(createReadStream(new URL(import.meta.url)), h);
const d = h.digest('hex');
console.log('file sha256', d.slice(0, 4) + '…' + d.slice(-4));

// HMAC with a key from the environment, verified in constant time
const key = Buffer.from(process.env.WEBHOOK_SECRET_HEX, 'hex');
const sign = (body) => createHmac('sha256', key).update(body).digest();
const body = JSON.stringify({ event: 'book.created', id: 7 });
const received = sign(body); // normally taken from a request header
const expected = sign(body);
console.log('hmac ok', received.length === expected.length && timingSafeEqual(received, expected));
console.log('hmac forged', timingSafeEqual(sign('{"event":"book.deleted"}'), expected));

c636…d0f5 true
43 chars as base64url
8 bytes of shake256
file sha256 9eb3…f382
hmac ok true
hmac forged false

import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

// 32 random bytes, hex-encoded in the environment. Generate one with:
//   node -p "crypto.randomBytes(32).toString('hex')"
const key = Buffer.from(process.env.DATA_KEY_HEX ?? '', 'hex');
if (key.length !== 32) throw new Error('DATA_KEY_HEX must be 64 hex characters (a 256-bit key)');

export function encrypt(plaintext, aad = '') {
  const iv = randomBytes(12); // 96-bit nonce: NEVER reuse an IV with the same key
  const cipher = createCipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
  cipher.setAAD(Buffer.from(aad));
  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
  const tag = cipher.getAuthTag();
  return Buffer.concat([iv, tag, ciphertext]).toString('base64url'); // iv | tag | ciphertext
}

export function decrypt(token, aad = '') {
  const raw = Buffer.from(token, 'base64url');
  const iv = raw.subarray(0, 12);
  const tag = raw.subarray(12, 28);
  const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
  decipher.setAAD(Buffer.from(aad));
  decipher.setAuthTag(tag); // required BEFORE final(); final() throws if anything was altered
  return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString('utf8');
}

if (import.meta.main) {
  const token = encrypt('library card 0042', 'user:7');
  console.log('token:', token.slice(0, 8) + '…' + token.slice(-4), `(${token.length} chars)`);
  console.log('roundtrip:', decrypt(token, 'user:7'));

  const tampered = Buffer.from(token, 'base64url');
  tampered[tampered.length - 1] ^= 1; // flip one bit of the ciphertext
  try { decrypt(tampered.toString('base64url'), 'user:7'); }
  catch (e) { console.log('tampered ciphertext ->', e.message); }
  try { decrypt(token, 'user:8'); }
  catch (e) { console.log('wrong AAD          ->', e.message); }
}

token: HTif…SVpt (60 chars)
roundtrip: library card 0042
tampered ciphertext -> Unsupported state or unable to authenticate data
wrong AAD          -> Unsupported state or unable to authenticate data

import * as crypto from 'node:crypto';
import { writeFileSync, readFileSync, mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const { generateKeyPairSync, sign, verify, createPrivateKey, createPublicKey, diffieHellman, hkdfSync } = crypto;

// 1. Ed25519 signatures: the algorithm argument must be null for Ed25519 (the hash is built in)
const { publicKey, privateKey } = generateKeyPairSync('ed25519');
const message = Buffer.from('release 1.4.0 of the Bookshelf CLI');
const signature = sign(null, message, privateKey);
console.log('signature bytes:', signature.length);
console.log('valid:', verify(null, message, publicKey, signature));
console.log('altered message:', verify(null, Buffer.from('release 1.4.1'), publicKey, signature));

// 2. Persist keys as PEM files (never print them, never commit them); the private key is encrypted
const dir = mkdtempSync(join(tmpdir(), 'keys-'));
const passphrase = process.env.KEY_PASSPHRASE;
writeFileSync(join(dir, 'signing.key'), privateKey.export({
  type: 'pkcs8', format: 'pem', cipher: 'aes-256-cbc', passphrase,
}), { mode: 0o600 });
writeFileSync(join(dir, 'signing.pub'), publicKey.export({ type: 'spki', format: 'pem' }));
const loaded = createPrivateKey({ key: readFileSync(join(dir, 'signing.key')), passphrase });
console.log('reloaded key verifies:', verify(null, message, createPublicKey(loaded), signature));
console.log('key types:', privateKey.asymmetricKeyType, privateKey.type, publicKey.type);

// 3. ECDSA with SHA-256: the hash is named explicitly; IEEE P1363 gives a fixed-size r||s signature
const ec = generateKeyPairSync('ec', { namedCurve: 'P-256' });
const ecSig = sign('sha256', message, { key: ec.privateKey, dsaEncoding: 'ieee-p1363' });
console.log('ecdsa p1363 length:', ecSig.length,
  verify('sha256', message, { key: ec.publicKey, dsaEncoding: 'ieee-p1363' }, ecSig));

// 4. Key agreement: X25519 shared secret, then HKDF to get a proper symmetric key
const alice = generateKeyPairSync('x25519');
const bob = generateKeyPairSync('x25519');
const s1 = diffieHellman({ privateKey: alice.privateKey, publicKey: bob.publicKey });
const s2 = diffieHellman({ privateKey: bob.privateKey, publicKey: alice.publicKey });
const k1 = Buffer.from(hkdfSync('sha256', s1, Buffer.alloc(0), 'bookshelf v1 session key', 32));
const k2 = Buffer.from(hkdfSync('sha256', s2, Buffer.alloc(0), 'bookshelf v1 session key', 32));
console.log('both sides derive the same key:', k1.equals(k2));

// 5. ML-DSA post-quantum signatures (added in 24.6.0, needs OpenSSL 3.5)
try {
  const pq = generateKeyPairSync('ml-dsa-65');
  const pqSig = sign(null, message, pq.privateKey);
  console.log('ml-dsa-65 signature bytes:', pqSig.length, verify(null, message, pq.publicKey, pqSig));
} catch (e) { console.log('ml-dsa-65 unavailable:', e.code ?? e.message); }

signature bytes: 64
valid: true
altered message: false
reloaded key verifies: true
key types: ed25519 private public
ecdsa p1363 length: 64 true
both sides derive the same key: true
ml-dsa-65 signature bytes: 3309 true

// No import needed: `crypto` is a global (Stability 2 - Stable), and so is `crypto.subtle`.
const { subtle } = globalThis.crypto;
const enc = new TextEncoder();
const hex = (buf) => Buffer.from(buf).toString('hex');

// Digest
const digest = await subtle.digest('SHA-256', enc.encode('bookshelf'));
console.log('sha-256:', hex(digest).slice(0, 4) + '…' + hex(digest).slice(-4));

// Random values and UUIDs
console.log(crypto.getRandomValues(new Uint8Array(8)).length, 'random bytes;', crypto.randomUUID().length, 'char uuid');

// AES-GCM: non-extractable key, 96-bit IV; the 16-byte tag is appended to the ciphertext
const aesKey = await subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
const iv = crypto.getRandomValues(new Uint8Array(12));
const sealed = await subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, enc.encode('library card 0042'));
console.log('sealed bytes:', sealed.byteLength, '(17 plaintext + 16 tag)');
console.log('opened:', new TextDecoder().decode(await subtle.decrypt({ name: 'AES-GCM', iv }, aesKey, sealed)));
try { await subtle.exportKey('raw', aesKey); } catch (e) { console.log('export of non-extractable key refused:', e instanceof DOMException); }

// Ed25519 signing
const { publicKey, privateKey } = await subtle.generateKey('Ed25519', false, ['sign', 'verify']);
const sig = await subtle.sign('Ed25519', privateKey, enc.encode('release 1.4.0'));
console.log('verify:', await subtle.verify('Ed25519', publicKey, sig, enc.encode('release 1.4.0')));

// HMAC
const hmacKey = await subtle.generateKey({ name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
const mac = await subtle.sign('HMAC', hmacKey, enc.encode('payload'));
console.log('hmac verify (constant time inside):', await subtle.verify('HMAC', hmacKey, mac, enc.encode('payload')));

// PBKDF2 through Web Crypto (importKey -> deriveBits)
const base = await subtle.importKey('raw', enc.encode(process.env.EXAMPLE_PASSWORD), 'PBKDF2', false, ['deriveBits']);
const bits = await subtle.deriveBits(
  { name: 'PBKDF2', hash: 'SHA-256', salt: crypto.getRandomValues(new Uint8Array(16)), iterations: 600_000 }, base, 256);
console.log('pbkdf2 bits:', bits.byteLength * 8);

// Interop with node:crypto KeyObjects
const { createSecretKey } = await import('node:crypto');
const ko = createSecretKey(crypto.getRandomValues(new Uint8Array(32)));
const ck = ko.toCryptoKey?.({ name: 'AES-GCM' }, true, ['encrypt']);
console.log('KeyObject -> CryptoKey:', ck ? ck.algorithm.name : '(toCryptoKey unavailable)');

sha-256: c636…d0f5
8 random bytes; 36 char uuid
sealed bytes: 33 (17 plaintext + 16 tag)
opened: library card 0042
export of non-extractable key refused: true
verify: true
hmac verify (constant time inside): true
pbkdf2 bits: 256
KeyObject -> CryptoKey: AES-GCM

import { hash, generateKeyPairSync, sign, verify, createPublicKey } from 'node:crypto';

// Canonical JSON: keys sorted recursively, so equal data always serialises to equal bytes.
const canonical = (v) => JSON.stringify(v, (_k, x) =>
  x && typeof x === 'object' && !Array.isArray(x)
    ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : 1)))
    : x);

// A fixed-order array (not an object) is hashed, so field boundaries are unambiguous.
const blockHash = ({ index, timestamp, prevHash, nonce, entries }) =>
  hash('sha256', JSON.stringify([index, timestamp, prevHash, nonce, canonical(entries)]));

const ZERO = '0'.repeat(64);

export function mine(index, prevHash, entries, difficulty, timestamp = Date.now()) {
  const target = '0'.repeat(difficulty); // difficulty = number of leading zero hex digits
  for (let nonce = 0; nonce < 50_000_000; nonce++) { // bounded: never spin forever
    const block = { index, timestamp, prevHash, nonce, entries };
    const h = blockHash(block);
    if (h.startsWith(target)) return { ...block, hash: h };
  }
  throw new Error('nonce space exhausted');
}

export function signEntry(payload, privateKey, publicKeyPem) {
  return { payload, publicKey: publicKeyPem, signature: sign(null, Buffer.from(canonical(payload)), privateKey).toString('base64') };
}

export function verifyChain(chain, difficulty) {
  for (let i = 0; i < chain.length; i++) {
    const b = chain[i];
    if (b.index !== i) return `block ${i}: wrong index`;
    if (b.prevHash !== (i === 0 ? ZERO : chain[i - 1].hash)) return `block ${i}: broken link`;
    if (blockHash(b) !== b.hash) return `block ${i}: contents do not match the stored hash`;
    if (!b.hash.startsWith('0'.repeat(difficulty))) return `block ${i}: proof of work missing`;
    for (const e of b.entries) {
      const ok = verify(null, Buffer.from(canonical(e.payload)), createPublicKey(e.publicKey), Buffer.from(e.signature, 'base64'));
      if (!ok) return `block ${i}: bad signature`;
    }
  }
  return 'valid';
}

if (import.meta.main) {
  const difficulty = 4;
  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
  const pem = publicKey.export({ type: 'spki', format: 'pem' });
  const entry = (n) => signEntry({ from: 'reader-1', book: `book-${n}`, action: 'borrow' }, privateKey, pem);

  const chain = [mine(0, ZERO, [], difficulty)];
  for (let n = 1; n <= 3; n++) chain.push(mine(n, chain.at(-1).hash, [entry(n)], difficulty));

  chain.forEach((b) => console.log(b.index, b.hash.slice(0, 10) + '…', 'nonce', b.nonce));
  console.log('intact chain:', verifyChain(chain, difficulty));

  chain[2].entries[0].payload.book = 'book-999'; // rewrite history
  console.log('edited entry:', verifyChain(chain, difficulty));

  chain[2].entries[0].payload.book = 'book-2';
  chain[2].prevHash = ZERO; // try to cut the link instead
  console.log('cut link:', verifyChain(chain, difficulty));
}

0 0000a19266… nonce 148277
1 0000fa45b3… nonce 187441
2 000028610d… nonce 27212
3 0000599d6b… nonce 51090
intact chain: valid
edited entry: block 2: contents do not match the stored hash
cut link: block 2: broken link