LEVEL 13 · LESSON 6 OF 12

Security and identity Core

Cryptography with @zudojs/crypto

Use @zudojs/crypto for random ids, tokens, hashes, HMAC, password hashing, AES-GCM encryption with key ids and constant-time checks, building reset tokens.

  • 55 min to read and try
  • You need: Cryptography with node:crypto, and the Data part of this course
  • You build: A password-reset flow that stores only token hashes, signed expiring download links for attachments, a key-ring vault for bank details, and unguessable public ids
Test yourself

BY THE END OF THIS LESSON YOU CAN

  • Pick the @zudojs/crypto function for a job: random value, token, hash, HMAC, password hash, encryption or signature
  • Issue and redeem password-reset tokens that are single-use, expire, and are stored only as hashes
  • Sign and verify expiring values bound to a purpose, with key ids for rotation
  • Encrypt data bound to its owner with AES-256-GCM, load keys safely and rotate them
  • Compare secrets in constant time, and test cryptographic code with known answers and every rejection path

Four shortcuts in one pull request

The Task API is about to get user accounts. A teammate opens a pull request with the first pieces: a "forgot password" link, links to download task attachments, and public ids for tasks. It works in every manual test. Here are the essential lines, and what an attacker does with each:

shortcuts.tsNode.js only
// 1. A reset token made from the user id and the time.
const issuedAt = Date.UTC(2026, 8, 24, 9, 15, 0, 412);
const resetToken = `u42-${issuedAt.toString(36)}`;

// The attacker asked for Ada's reset at 09:15:00 and tries every millisecond of that second.
const start = Date.UTC(2026, 8, 24, 9, 15, 0);
let tries = 0;
for (let ms = start; ms < start + 1000; ms++) {
  tries++;
  if (`u42-${ms.toString(36)}` === resetToken) break;
}
console.log(`reset token guessed in ${tries} tries`);

// 2. A download link that "signs" its data with base64.
const link = Buffer.from(JSON.stringify({ attachment: 7, user: "ada" })).toString("base64url");
const forged = Buffer.from(JSON.stringify({ attachment: 8, user: "ada" })).toString("base64url");
console.log("real link: /download?t=" + link);
console.log("forged:    /download?t=" + forged, "(accepted: nothing to check it against)");

// 3. Public ids that count.
const myInvoice = 1042;
console.log("my invoice:", myInvoice, "- so try", myInvoice - 1, "and", myInvoice + 1);

// 4. An API key compared with ===.
const apiKey = "7f3a9c2e";
const steps = (guess: string) => [...guess].findIndex((ch, i) => ch !== apiKey[i]) + 1 || guess.length;
console.log("steps for 0000…, 7f00…, 7f3a…:", steps("00000000"), steps("7f000000"), steps("7f3a0000"));
Output of npx tsx shortcuts.ts
reset token guessed in 413 tries
real link: /download?t=eyJhdHRhY2htZW50Ijo3LCJ1c2VyIjoiYWRhIn0
forged:    /download?t=eyJhdHRhY2htZW50Ijo4LCJ1c2VyIjoiYWRhIn0 (accepted: nothing to check it against)
my invoice: 1042 - so try 1041 and 1043
steps for 0000…, 7f00…, 7f3a…: 1 3 5
  • The reset token has no secret in it: a user id and a time the attacker roughly knows. 413 guesses take over Ada's account.
  • Base64 is an encoding, not a signature. Anyone can decode the link, change the attachment id, and encode it again.
  • Sequential ids tell a customer how many invoices you issue a day, and invite them to try the neighbours. If an authorization check is ever missing, the neighbours are one request away.
  • === stops at the first wrong character, so a longer comparison means a better guess. Over many requests an attacker can measure that (a timing attack, which you met in Cryptography with node:crypto).

That lesson taught the building blocks in node:crypto. @zudojs/crypto packages them with safe defaults and refusals built in: tokens with the right length and a prefix, token hashing for storage, password hashing with a cost floor, AES-GCM with a self-describing envelope, keys with ids and fingerprints, and constant-time comparisons. In this lesson you replace all four shortcuts, and build the three things the Task API needs next: password-reset tokens, signed download links, and encrypted bank details for paying out freelancers.

Terminal on your computer
npm install @zudojs/crypto

added 1 package, and audited 22 packages in 2s

found 0 vulnerabilities

Every function here needs Node.js, so run the examples on your computer with npx tsx file.ts. Almost all of them return a Promise: the package calls a crypto provider (by default NodeCryptoProvider) behind one interface, which keeps the same API possible over the browser's asynchronous Web Crypto.

Before you design a reset flow

REASON IT OUT

What must a password-reset token survive?

A user who forgot their password asks for a reset link by e-mail. Think about these before reading the code:

  • What must be true of the token so nobody can guess it? How long should it be?
  • Your database leaks next year. Can the attacker use the reset tokens in it?
  • The e-mail sits in an inbox for a week, or is forwarded. When should the link stop working?
  • The link is clicked twice, or an attacker replays it after the user used it. What happens?
  • Someone requests a reset for [email protected]. What does your API answer if that address has no account?
Show the reasoning

The token must be random, from a cryptographically secure generator, with enough bits that guessing is hopeless: 32 random bytes (256 bits). Nothing about the user or the time may go into it.

Store only a hash of the token. The link holds the token; the database holds sha256(token). A leaked table then contains nothing usable. A fast hash is fine here because the token has 256 random bits: unlike a password, there is nothing to guess.

It must expire, 15 minutes is common, and be single-use: delete it when it is redeemed, even if the redeem fails later. Issuing a new one should cancel older ones for the same user.

The answer must be the same whether or not the account exists ("if that address has an account, we sent a link"), or the reset form tells attackers which e-mails are registered. Rate-limit the endpoint too.

The map of @zudojs/crypto

Each job has one right tool. This table is the one to keep open while you work:

You need to…Use
make random bytes, numbers, codes or UUIDsrandomBytesSecure, randomInteger, randomNumericCode, randomFromAlphabet, randomUuid
make a token for a link, session or API keygenerateToken, generatePasswordResetToken, generateApiKey, generateOtp
store a token so a leak is harmlesshashToken, verifyTokenHash
fingerprint datasha256, hash
prove a value came from you and was not changedhmacSha256 + timingSafeEqualEncoded
store a passwordhashPassword, verifyPassword (scrypt)
store data you must read backencryptEnvelope, decryptEnvelope (AES-256-GCM)
let others verify without being able to signgenerateEd25519KeyPair, signString, verifyString
compare two secretstimingSafeEqualString, timingSafeEqualEncoded, timingSafeEqual

Random values and secure ids

How hard a random value is to guess is measured in bits of entropy: a value with n bits is one of 2n equally likely possibilities. Each character from an alphabet of A symbols adds log2(A) bits. The generators in @zudojs/crypto all use the operating system's secure random source:

random.tsNode.js only
import {
  generateApiKey, generateOtp, generatePasswordResetToken, generateToken,
  randomBytesSecure, randomFromAlphabet, randomInteger, randomUuid,
} from "@zudojs/crypto";

const bits = (length: number, alphabet: number) => Math.floor(length * Math.log2(alphabet));

const reset = await generatePasswordResetToken();
const apiKey = await generateApiKey();
const invoiceId = await generateToken({ bytes: 16, encoding: "hex", prefix: "inv_" });
const code = await generateOtp();
const invite = await randomFromAlphabet(10, "ABCDEFGHJKLMNPQRSTUVWXYZ23456789");
const uuid = await randomUuid();

console.log("reset token:", reset.slice(0, 6) + "…", reset.length, "chars,", 32 * 8, "bits");
console.log("API key:    ", apiKey.slice(0, 4) + "…", apiKey.length, "chars");
console.log("invoice id: ", /^inv_[0-9a-f]{32}$/.test(invoiceId), bits(32, 16), "bits");
console.log("login code: ", /^\d{6}$/.test(code), bits(6, 10), "bits");
console.log("invite code:", /^[A-HJ-NP-Z2-9]{10}$/.test(invite), bits(10, 32), "bits");
console.log("uuid v4:    ", /^[0-9a-f]{8}-[0-9a-f]{4}-4/.test(uuid), 122, "bits");
console.log("32 bytes:   ", (await randomBytesSecure(32)).length, "- a die roll:", [1, 2, 3, 4, 5, 6].includes(await randomInteger(1, 6)));
Output of npx tsx random.ts
reset token: reset_… 49 chars, 256 bits
API key:     lat_… 47 chars
invoice id:  true 128 bits
login code:  true 19 bits
invite code: true 50 bits
uuid v4:     true 122 bits
32 bytes:    32 - a die roll: true

What to use each for:

  • Tokens that grant access (reset links, sessions, API keys): 32 bytes. The prefix (reset_, lat_) is not secret; it tells you and your secret scanners what a leaked string is. generatePasswordResetToken, generateSessionToken, generateApiKey and friends pick the size and prefix for you.
  • Codes a person types: short, so only safe with an expiry and a limit on attempts. Six digits are 19 bits: an attacker with unlimited tries needs about 500,000 guesses on average; with 5 tries per code they have a 1 in 200,000 chance. randomFromAlphabet with no 0/O or 1/I avoids typing mistakes.
  • Public ids such as inv_…: 128 random bits make them unguessable, so a missing authorization check does not hand out neighbours. They are still not secrets, because ids appear in logs and URLs. Keep your serial primary key for joins and indexes, and add the random id as a unique column for everything outside the server.

NEVER MATH.RANDOM

A value made with Math.random(), Date.now(), a counter or a user id is not a secret, however it is mixed or hashed. If an attacker can work out the inputs, they can work out the token.

Hashes and HMACs

A hash fingerprints data; anyone can compute it. An HMAC is a fingerprint made with a secret key; only key holders can compute it, so a matching HMAC proves the data came from one of them and was not changed. Cryptographic code is checked against published test vectors, inputs with known correct outputs. Here are the standard vector for SHA-256 and test case 1 of RFC 4231 for HMAC-SHA256:

hashing.tsNode.js only
import { hash, hmacSha256, sha256 } from "@zudojs/crypto";

console.log(await sha256("abc"));
const result = await hash("abc", { algorithm: "sha512", encoding: "base64url" });
console.log(result.algorithm, result.digest.length, "bytes,", result.encoded.length, "chars");

const key = new Uint8Array(20).fill(0x0b);
const mac = await hmacSha256("Hi There", key);
console.log(mac === "b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7");

try {
  await hmacSha256("Hi There", new TextEncoder().encode("secret"));
} catch (error) {
  console.log((error as Error).name, "-", (error as Error).message);
}
Output of npx tsx hashing.ts
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
sha512 64 bytes, 86 chars
true
CryptoError - HMAC key must be at least 16 bytes, received 6.

The last call shows a safety rule in the package: an HMAC key shorter than 16 bytes is refused. A six-letter "secret" can be guessed offline from one signed value. Use 32 random bytes, stored as base64 in an environment variable, as below.

Comparing secrets

Every comparison of a secret-dependent value that an attacker can repeat (signatures, API keys, HMACs) must take the same time whatever the input. The package has three constant-time helpers:

compare.tsNode.js only
import { timingSafeEqual, timingSafeEqualEncoded, timingSafeEqualString } from "@zudojs/crypto";

console.log(timingSafeEqualString("lat_7f3a9c", "lat_7f3a9c"), timingSafeEqualString("lat_7f3a9c", "lat_7f3a9d"));
console.log("different lengths:", timingSafeEqualString("lat_7f3a9c", "lat_7f"));
console.log("hex, any case:", timingSafeEqualEncoded("7F3A9C", "7f3a9c", "hex"));
console.log("not valid base64url:", timingSafeEqualEncoded("a*c", "abc", "base64url"));
console.log("bytes:", timingSafeEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])));
Output of npx tsx compare.ts
true false
different lengths: false
hex, any case: true
not valid base64url: false
bytes: true

Unlike Node's own timingSafeEqual, these never throw on different lengths or broken input; they return false. timingSafeEqualEncoded decodes both sides first, so two spellings of the same bytes (upper- and lower-case hex) are equal. You do not need them to look up a token's hash in a database: the attacker cannot choose what the hash of their guess starts with, so the lookup's timing tells them nothing.

Build: password-reset tokens

Now the reset flow from the questions above. The store keeps rows by token hash, as a database table with a unique token_hash column would. The clock is passed in, so tests can move time:

password-resets.ts
import { generatePasswordResetToken, hashToken, TOKEN_PREFIX, TOKEN_TTL } from "@zudojs/crypto";

export interface Clock {
  now(): number;
}

interface ResetRow {
  readonly userId: string;
  readonly tokenHash: string;
  readonly expiresAt: number;
}

export class PasswordResets {
  private readonly rows = new Map<string, ResetRow>();

  constructor(
    private readonly clock: Clock,
    private readonly ttlMs: number = TOKEN_TTL.PASSWORD_RESET_MS,
  ) {}

  /** Returns the token for the e-mail link. Only its hash is kept. */
  async issue(userId: string): Promise<string> {
    for (const [tokenHash, row] of this.rows) {
      if (row.userId === userId) this.rows.delete(tokenHash);
    }
    const token = await generatePasswordResetToken();
    const tokenHash = await hashToken(token);
    this.rows.set(tokenHash, { userId, tokenHash, expiresAt: this.clock.now() + this.ttlMs });
    return token;
  }

  /** The user id for a valid token, or null. A token works at most once. */
  async redeem(token: string): Promise<string | null> {
    if (!token.startsWith(TOKEN_PREFIX.PASSWORD_RESET) || token.length > 128) return null;
    const tokenHash = await hashToken(token);
    const row = this.rows.get(tokenHash);
    if (!row) return null;
    this.rows.delete(tokenHash);
    return row.expiresAt > this.clock.now() ? row.userId : null;
  }

  storedRows(): readonly ResetRow[] {
    return [...this.rows.values()];
  }
}
  • issue deletes the user's older tokens first: only the newest e-mail works.
  • redeem refuses anything that does not look like a reset token before hashing it, and caps the length, so garbage never costs a hash.
  • The row is deleted before the expiry check. An expired token cannot be tried again, and a valid one works once.
  • TOKEN_TTL.PASSWORD_RESET_MS is 15 minutes.
reset-flow.tsNode.js only
import { PasswordResets } from "./password-resets.js";

let now = Date.UTC(2026, 8, 24, 9, 0);
const resets = new PasswordResets({ now: () => now });

const users = new Map([["[email protected]", "u-ada"]]);
async function requestReset(email: string): Promise<string> {
  const userId = users.get(email.trim().toLowerCase());
  if (userId) {
    const token = await resets.issue(userId);
    console.log(`  (e-mail to ${email}: https://tasks.example.com/reset?token=${token.slice(0, 6)}…)`);
  }
  return "If that address has an account, we sent a reset link.";
}

console.log(await requestReset("[email protected]"));
console.log(await requestReset("[email protected]"));

const first = await resets.issue("u-ada");
const second = await resets.issue("u-ada");
console.log("stored:", resets.storedRows().map((r) => ({ user: r.userId, hashLength: r.tokenHash.length })));
console.log("the table contains the token?", resets.storedRows().some((r) => r.tokenHash.includes(second)));

console.log("older token:", await resets.redeem(first));
console.log("newest token:", await resets.redeem(second));
console.log("used again:", await resets.redeem(second));

const late = await resets.issue("u-ada");
now += 16 * 60 * 1000;
console.log("after 16 minutes:", await resets.redeem(late));
console.log("garbage:", await resets.redeem("'; DROP TABLE users; --"));
Output of npx tsx reset-flow.ts
  (e-mail to [email protected]: https://tasks.example.com/reset?token=reset_…)
If that address has an account, we sent a reset link.
If that address has an account, we sent a reset link.
stored: [ { user: 'u-ada', hashLength: 64 } ]
the table contains the token? false
older token: null
newest token: u-ada
used again: null
after 16 minutes: null
garbage: null

Both requests got the same answer; only the one with an account produced an e-mail. After two issues there is one row, holding a 64-character hash and no trace of the token. The older link was dead, the newest worked once, and the late one expired. After a successful reset, also call auth.logoutAll(userId) (from the next lesson): anyone who knew the old password loses their sessions.

Password hashing

Passwords are the opposite of tokens: people choose them, so they are guessable, and the hash must be slow. hashPassword uses scrypt and returns an object whose encoded string records the algorithm and its cost settings. Authentication wraps it for logins; here is what it does underneath:

passwords.tsNode.js only
import { decodePasswordHash, hashPassword, isValidPassword, PASSWORD_POLICY, verifyPassword } from "@zudojs/crypto";

const result = await hashPassword("correct horse battery staple");
console.log(result.encoded.split("$").slice(0, 5).join("$"), "…", result.encoded.length, "chars");
console.log(await verifyPassword("correct horse battery staple", result.encoded));
console.log(await verifyPassword("correct horse battery stapler", result.encoded));

const parts = decodePasswordHash(result.encoded);
console.log(parts.algorithm, parts.salt.length, "byte salt,", parts.hash.length, "byte hash");

for (const attempt of [() => hashPassword("pw", { cost: 1024 }), () => hashPassword("x".repeat(2000))]) {
  try {
    await attempt();
  } catch (error) {
    console.log((error as Error).name, "-", (error as Error).message);
  }
}
console.log("policy:", PASSWORD_POLICY, "short ok?", isValidPassword("abc"), "- hashPassword('abc') works:", (await hashPassword("abc")).encoded.startsWith("v1$"));
Output of npx tsx passwords.ts
v1$scrypt$16384$8$5 … 86 chars
true
false
scrypt 16 byte salt, 32 byte hash
CryptoError - scrypt cost for a new password hash must be at least 16384.
CryptoError - Password must not exceed 1024 characters.
policy: { MIN_LENGTH: 8, RECOMMENDED_MIN_LENGTH: 12, MAX_LENGTH: 1024 } short ok? false - hashPassword('abc') works: true

The package refuses a new hash cheaper than scrypt's cost 16384, and passwords over 1,024 characters (so nobody makes your server hash a 10 MB "password"). It does not refuse short passwords: hashPassword("abc") works. Your registration route enforces the policy with isValidPassword or a schema, as in the authentication lesson.

Encryption and key handling

The Task API pays freelancers for finished tasks, so it stores their bank account numbers, and must read them back to make transfers. Encryption with AES-256-GCM fits: a 32-byte key, a fresh 12-byte nonce (IV) per message, and an authentication tag that detects any change. encryptEnvelope returns one self-describing string, and aad (additional authenticated data) binds the ciphertext to its owner:

envelope.tsNode.js only
import { decryptEnvelope, encryptEnvelope, randomBytesSecure, utf8Decode, utf8Encode } from "@zudojs/crypto";

const key = await randomBytesSecure(32);
const owner = utf8Encode("freelancer:17");
const sealed = await encryptEnvelope(utf8Encode("0123456789 GTBank"), key, { aad: owner });

const [version, algorithm, iv, tag, ciphertext] = sealed.split(".");
console.log(version, algorithm, "iv", iv!.length, "tag", tag!.length, "ciphertext", ciphertext!.length, "chars");
console.log(utf8Decode(await decryptEnvelope(sealed, key, owner)));

const attempts: [string, () => Promise<Uint8Array>][] = [
  ["another owner", () => decryptEnvelope(sealed, key, utf8Encode("freelancer:18"))],
  ["no owner", () => decryptEnvelope(sealed, key)],
  ["wrong key", async () => decryptEnvelope(sealed, await randomBytesSecure(32), owner)],
  ["ciphertext changed", () => decryptEnvelope([version, algorithm, iv, tag, (ciphertext!.startsWith("A") ? "B" : "A") + ciphertext!.slice(1)].join("."), key, owner)],
  ["not an envelope", () => decryptEnvelope("v1.aes-256-gcm.abc", key, owner)],
];
for (const [label, attempt] of attempts) {
  try {
    await attempt();
    console.log(label, "-> decrypted?!");
  } catch (error) {
    const e = error as Error & { code?: string };
    console.log(label, "->", e.name, e.code, e.message);
  }
}
Output of npx tsx envelope.ts
v1 aes-256-gcm iv 16 tag 22 ciphertext 23 chars
0123456789 GTBank
another owner -> CryptoError ERR_CRYPTO_CIPHER Decryption failed.
no owner -> CryptoError ERR_CRYPTO_CIPHER Decryption failed.
wrong key -> CryptoError ERR_CRYPTO_CIPHER Decryption failed.
ciphertext changed -> CryptoError ERR_CRYPTO_CIPHER Decryption failed.
not an envelope -> CryptoError ERR_CRYPTO_CIPHER Invalid encrypted envelope.

The envelope carries a version (v1), the algorithm, the IV, the tag and the ciphertext. Copying the sealed value into another freelancer's row fails, because the AAD differs. Every failure is a CryptoError with code ERR_CRYPTO_CIPHER. Apart from the string that is not an envelope at all, they all say only "Decryption failed.": GCM never tells you why, it only guarantees you never get silently wrong data.

LET THE PACKAGE CHOOSE THE IV

The lower-level encrypt(plaintext, key, { iv }) accepts an IV you pass in. With the same key, a repeated IV lets an attacker recover plaintexts and forge tags, as the node:crypto lesson showed, so @zudojs/crypto 1.4.0 made it a refusal: passing an IV this process has already used under the same key throws a CryptoError instead of encrypting. The guard only remembers what this one process has seen, so it is a safety net, not a proof of uniqueness across a restart or a fleet of servers. Never pass iv yourself; the package generates a fresh one for every call, which never trips the guard.

Keys: load, name, rotate

A key is 32 random bytes that live in an environment variable or a secret manager, as base64. Load it once at start-up, and fail loudly if it is missing or the wrong size. createCryptoKey checks the size for the algorithm and gives the key a key id and a fingerprint (a hash of the key, safe to log). The file below is a small key ring: every sealed value starts with the id of the key that sealed it, so old values still open after you add a new key:

vault.ts
import {
  createCryptoKey, CryptoAlgorithm, decryptEnvelope, encryptEnvelope, fromBase64, utf8Decode, utf8Encode,
} from "@zudojs/crypto";
import type { CryptoKey } from "@zudojs/crypto";

export async function loadKey(keyId: string, base64: string | undefined): Promise<CryptoKey> {
  if (!base64) throw new Error(`Encryption key ${keyId} is not set`);
  return createCryptoKey(fromBase64(base64), { algorithm: CryptoAlgorithm.AES_256_GCM, keyId });
}

export class Vault {
  private readonly keys: ReadonlyMap<string, CryptoKey>;

  constructor(keys: readonly CryptoKey[], private readonly currentId: string) {
    this.keys = new Map(keys.map((key) => [key.keyId, key]));
    if (!this.keys.has(currentId)) throw new Error(`No key with id ${currentId}`);
  }

  async seal(plaintext: string, owner: string): Promise<string> {
    const key = this.keys.get(this.currentId)!;
    const envelope = await encryptEnvelope(utf8Encode(plaintext), key.bytes(), { aad: utf8Encode(owner) });
    return `${key.keyId}:${envelope}`;
  }

  async open(sealed: string, owner: string): Promise<string> {
    const at = sealed.indexOf(":");
    const key = this.keys.get(sealed.slice(0, at));
    if (at < 1 || !key) throw new Error("Unknown encryption key");
    return utf8Decode(await decryptEnvelope(sealed.slice(at + 1), key.bytes(), utf8Encode(owner)));
  }

  needsRotation(sealed: string): boolean {
    return !sealed.startsWith(`${this.currentId}:`);
  }
}
key-ring.tsNode.js only
import { randomBytesSecure, toBase64 } from "@zudojs/crypto";
import { loadKey, Vault } from "./vault.js";

// Demo only: invent the two keys. Your app reads PAYOUT_KEY_2026_03 and PAYOUT_KEY_2026_09 from the environment.
const env: Record<string, string | undefined> = {
  PAYOUT_KEY_2026_03: toBase64(await randomBytesSecure(32)),
  PAYOUT_KEY_2026_09: toBase64(await randomBytesSecure(32)),
  PAYOUT_KEY_BROKEN: "c2hvcnQ=",
};

const march = await loadKey("2026-03", env["PAYOUT_KEY_2026_03"]);
const september = await loadKey("2026-09", env["PAYOUT_KEY_2026_09"]);
console.log("key", september.keyId, september.length, "bits, fingerprint", /^[0-9a-f]{64}$/.test(september.fingerprint));
console.log("safe to log:", Object.keys(JSON.parse(JSON.stringify(september))).includes("bytes") ? "NO" : "yes, no key bytes");

for (const name of ["PAYOUT_KEY_BROKEN", "PAYOUT_KEY_MISSING"]) {
  try {
    await loadKey(name, env[name]);
  } catch (error) {
    console.log(name, "->", (error as Error).message);
  }
}

const oldVault = new Vault([march], "2026-03");
const stored = await oldVault.seal("0123456789 GTBank", "freelancer:17");

const vault = new Vault([march, september], "2026-09");
console.log("old value opens:", await vault.open(stored, "freelancer:17"), "- needs rotation:", vault.needsRotation(stored));
const rotated = await vault.seal(await vault.open(stored, "freelancer:17"), "freelancer:17");
console.log("rotated to", rotated.split(":")[0], "- needs rotation:", vault.needsRotation(rotated));
Output of npx tsx key-ring.ts
key 2026-09 256 bits, fingerprint true
safe to log: yes, no key bytes
PAYOUT_KEY_BROKEN -> Algorithm "aes-256-gcm" requires a 32-byte key, received 5 bytes.
PAYOUT_KEY_MISSING -> Encryption key PAYOUT_KEY_MISSING is not set
old value opens: 0123456789 GTBank - needs rotation: true
rotated to 2026-09 - needs rotation: false

The key's length is in bits (256), and serialising the key object as JSON leaves out its bytes, so a key that ends up in a log line by accident does not leak. Loading refuses a 5-byte key and a missing variable at start-up, long before the first payout.

Rotation then has four steps: add the new key and make it current (new values use it at once), keep the old key for reading, re-seal old values in a background job using needsRotation, and remove the old key only when nothing needs it. Cryptography for developers covers what to do when a key has leaked.

Build: signed download links

In the upload project, downloads went through the API. Sometimes you want a link that works on its own for a short time: in an e-mail, or in an <img> tag where the browser cannot send your login token. The link then carries its own proof: a signed value. It holds some data, an expiry and a purpose, and an HMAC over all of it with a key only the server has:

signed.ts
import { fromBase64Url, hmacSha256, timingSafeEqualEncoded, toBase64Url, utf8Decode, utf8Encode } from "@zudojs/crypto";

export interface SigningKeys {
  readonly current: string;
  readonly keys: Readonly<Record<string, Uint8Array>>;
}

type Data = Readonly<Record<string, string | number>>;
export type Verified =
  | { readonly ok: true; readonly data: Data }
  | { readonly ok: false; readonly reason: "malformed" | "unknown key" | "bad signature" | "wrong purpose" | "expired" };

export async function signValue(signing: SigningKeys, purpose: string, data: Data, expiresAt: number): Promise<string> {
  const payload = toBase64Url(utf8Encode(JSON.stringify({ purpose, data, expiresAt })));
  const kid = signing.current;
  const mac = await hmacSha256(`${kid}.${payload}`, signing.keys[kid]!, "base64url");
  return `${kid}.${payload}.${mac}`;
}

export async function verifyValue(signing: SigningKeys, purpose: string, value: string, now: number): Promise<Verified> {
  const parts = value.split(".");
  if (parts.length !== 3 || value.length > 2048) return { ok: false, reason: "malformed" };
  const [kid, payload, mac] = parts as [string, string, string];
  const key = signing.keys[kid];
  if (!key) return { ok: false, reason: "unknown key" };
  const expected = await hmacSha256(`${kid}.${payload}`, key, "base64url");
  if (!timingSafeEqualEncoded(mac, expected, "base64url")) return { ok: false, reason: "bad signature" };
  const claims = JSON.parse(utf8Decode(fromBase64Url(payload))) as { purpose: string; data: Data; expiresAt: number };
  if (claims.purpose !== purpose) return { ok: false, reason: "wrong purpose" };
  if (claims.expiresAt <= now) return { ok: false, reason: "expired" };
  return { ok: true, data: claims.data };
}

The order of the checks matters. The signature is checked before the payload is even parsed, so an attacker's JSON never reaches JSON.parse. The key id (kid) is inside the signed text, so it cannot be swapped for another. The purpose stops a value signed for one feature from being replayed in another: a download link is not an e-mail confirmation, even though both are signed with the same key.

signed-links.tsNode.js only
import { randomBytesSecure } from "@zudojs/crypto";
import { signValue, verifyValue } from "./signed.js";

const signing = { current: "k2", keys: { k1: await randomBytesSecure(32), k2: await randomBytesSecure(32) } };
const now = Date.UTC(2026, 8, 24, 9, 0);
const tenMinutes = 10 * 60 * 1000;

const sig = await signValue(signing, "attachment-download", { attachment: 7, user: "u-ada" }, now + tenMinutes);
console.log(`/attachments/7/download?sig=${sig.slice(0, 12)}…`);
console.log(await verifyValue(signing, "attachment-download", sig, now + 60_000));

const [kid, payload, mac] = sig.split(".") as [string, string, string];
const edited = Buffer.from(JSON.stringify({ purpose: "attachment-download", data: { attachment: 8, user: "u-ada" }, expiresAt: now + tenMinutes })).toString("base64url");
const oldKeyLink = await signValue({ ...signing, current: "k1" }, "attachment-download", { attachment: 7, user: "u-ada" }, now + tenMinutes);
const confirm = await signValue(signing, "email-confirmation", { user: "u-ada" }, now + tenMinutes);

const cases: [string, string, string, number][] = [
  ["attachment 8 instead", `${kid}.${edited}.${mac}`, "attachment-download", now],
  ["signed with k1", oldKeyLink, "attachment-download", now],
  ["k1 retired", oldKeyLink.replace(/^k1/, "k0"), "attachment-download", now],
  ["other purpose", confirm, "attachment-download", now],
  ["after 11 minutes", sig, "attachment-download", now + 11 * 60 * 1000],
  ["not a signed value", "hello", "attachment-download", now],
  ["mac cut short", `${kid}.${payload}.${mac.slice(0, 20)}`, "attachment-download", now],
];
for (const [label, value, purpose, at] of cases) {
  const result = await verifyValue(signing, purpose, value, at);
  console.log(label.padEnd(20), result.ok ? "ok" : result.reason);
}
Output of npx tsx signed-links.ts
/attachments/7/download?sig=k2.eyJwdXJwb…
{ ok: true, data: { attachment: 7, user: 'u-ada' } }
attachment 8 instead bad signature
signed with k1       ok
k1 retired           unknown key
other purpose        wrong purpose
after 11 minutes     expired
not a signed value   malformed
mac cut short        bad signature

Changing the attachment id broke the signature. A link signed with the older key k1 still works, because k1 is still in the ring for reading; rewriting its key id is caught as an unknown key. The e-mail confirmation value had a valid signature, but the wrong purpose. And ten minutes means ten minutes.

A signed link is a bearer token: whoever holds it can use it until it expires. Keep the lifetime short, put the user id inside so your route can still check the user may see the attachment, and never put secrets in the payload: it is signed, not encrypted, exactly like a JWT. (A JWT is this same idea with a standard format; authentication uses one for logins.)

When others must verify: signatures

An HMAC can only be checked by someone who has the key, and anyone who can check can also sign. When a partner or a customer must verify your data without being able to forge it (an exported receipt, a webhook you send, a licence file), use a public-key signature. @zudojs/crypto signs with Ed25519:

signatures.tsNode.js only
import { exportPrivateKeyPem, exportPublicKeyPem, generateEd25519KeyPair, signString, toBase64Url, verifyString } from "@zudojs/crypto";

const pair = generateEd25519KeyPair();
const privateKey = exportPrivateKeyPem(pair.privateKey); // keep secret, like any key
const publicKey = exportPublicKeyPem(pair.publicKey);    // publish this
const receipt = JSON.stringify({ invoice: "inv_5f2c", amount: "₦45,000", paidAt: "2026-09-24" });

const signature = await signString(receipt, privateKey);
console.log(signature.length, "byte signature:", toBase64Url(signature).length, "chars");
console.log(publicKey.split("\n")[0]);
console.log("genuine:", await verifyString(receipt, signature, publicKey));
console.log("amount changed:", await verifyString(receipt.replace("45,000", "4,500"), signature, publicKey));
Output of npx tsx signatures.ts
64 byte signature: 86 chars
-----BEGIN PUBLIC KEY-----
genuine: true
amount changed: false

The keys are exported as PEM text, the usual format for storing and publishing keys. signString and verifyString take keys as PEM text or bytes; their types do not accept the KeyObjects that generateEd25519KeyPair returns, so export first. You publish the public key; the private key never leaves your server. Cryptography for developers goes deeper into signatures, publishing keys and rotating them.

Failure cases and testing

Cryptographic code fails quietly: a wrong comparison still returns a boolean, and a weak token still looks random. Test behaviour you can check:

  • Known answers. Your HMAC and hash wrappers reproduce published vectors, like the RFC 4231 case above.
  • Round trips for every input shape: empty strings, emoji, ₦ signs, long text.
  • Every rejection path: each reason in verifyValue, each refusal in redeem. The signed-links example is that test.
  • Time: inject the clock, as PasswordResets does, so expiry is tested in microseconds instead of 15 minutes.
crypto.test.tsNode.js only
import { strict as assert } from "node:assert";
import { randomBytesSecure, utf8Encode } from "@zudojs/crypto";
import { PasswordResets } from "./password-resets.js";
import { signValue, verifyValue } from "./signed.js";
import { Vault, loadKey } from "./vault.js";

async function test(name: string, body: () => Promise<void>) {
  try {
    await body();
    console.log("PASS", name);
  } catch (error) {
    console.log("FAIL", name, "-", (error as Error).message.split("\n")[0]);
  }
}

await test("vault round-trips unusual text", async () => {
  const key = await loadKey("t1", Buffer.from(await randomBytesSecure(32)).toString("base64"));
  const vault = new Vault([key], "t1");
  for (const text of ["", "₦45,000 to Chidi 🎉", "x".repeat(10_000)]) {
    assert.equal(await vault.open(await vault.seal(text, "freelancer:1"), "freelancer:1"), text);
  }
});

await test("two seals of the same text differ", async () => {
  const vault = new Vault([await loadKey("t1", Buffer.from(await randomBytesSecure(32)).toString("base64"))], "t1");
  assert.notEqual(await vault.seal("same", "o"), await vault.seal("same", "o"));
});

await test("a reset token expires exactly at its ttl", async () => {
  let now = 0;
  const resets = new PasswordResets({ now: () => now }, 1_000);
  const token = await resets.issue("u-1");
  now = 1_000;
  assert.equal(await resets.redeem(token), null);
});

await test("a signed value is refused one millisecond after expiry", async () => {
  const signing = { current: "k1", keys: { k1: await randomBytesSecure(32) } };
  const value = await signValue(signing, "p", { id: 1 }, 5_000);
  assert.deepEqual(await verifyValue(signing, "p", value, 4_999), { ok: true, data: { id: 1 } });
  assert.deepEqual(await verifyValue(signing, "p", value, 5_000), { ok: false, reason: "expired" });
});

await test("utf8Encode counts bytes, not characters", async () => {
  const bytes = utf8Encode("₦").length;
  assert.equal(bytes, 1, `₦ is ${bytes} bytes, not 1`);
});
Output of npx tsx crypto.test.ts
PASS vault round-trips unusual text
PASS two seals of the same text differ
PASS a reset token expires exactly at its ttl
PASS a signed value is refused one millisecond after expiry
FAIL utf8Encode counts bytes, not characters - ₦ is 3 bytes, not 1

The last test fails on purpose: ₦ is one character but 3 bytes in UTF-8. Length limits on anything you hash, sign or encrypt are limits on bytes; checking characters instead is a classic off-by-a-lot bug.

In your Vitest suite, also check that production settings are the strong ones: that the reset TTL is TOKEN_TTL.PASSWORD_RESET_MS, and that the keys loaded at start-up are 256 bits.

Production concerns

  • Where keys live. Environment variables set by your platform or a secret manager, never Git. Separate keys per purpose (signing links, encrypting payouts) and per environment, so a leaked staging key opens nothing in production.
  • Logging. Log key ids and fingerprints, token prefixes and hashes, never keys, tokens, signatures or decrypted data. CryptoKey objects are safe to log; key.bytes() is not.
  • Errors at the edge. A CryptoError from decryptEnvelope has status 500, which is right for your own stored data. For values that come from a client (a signed link, a reset token), answer 400 or 401 with a generic message instead, as verifyValue and redeem do by returning results instead of throwing.
  • Dependency injection. createCryptoService() bundles the operations in one object you can register in the container and replace in tests.
  • Cost. Each password hash takes tens of milliseconds of CPU on Node's thread pool; hashes of tokens and HMACs take microseconds. Rate-limit login and reset endpoints, not link verification.
  • Clear buffers you are done with. wipe(bytes) fills a Uint8Array with zeros, shortening the time a key or password sits in memory after use.

Practice

TRY IT YOURSELF

Invite codes people can type

Team invites are read aloud and typed on phones. Write inviteCode() that returns 12 characters from an alphabet without 0, O, 1, I or L, formatted in groups of four (ABCD-EFGH-JKMN). How many bits of entropy does it have, and is that enough for a code that expires in 7 days and allows 10 attempts?

Write it in the editor, run it on your computer, then press Check and paste what it printed. Hints and the solution open up once you have checked your output.

TRY IT YOURSELF

E-mail confirmation links

Use signValue and verifyValue to build confirmationLink(userId, email) and confirm(sig, now). The link lasts 24 hours and must only work for confirmations. Show that a confirmation link cannot be used as a download link, and that a download link cannot confirm an e-mail.

Write it in the editor, run it on your computer, then press Check and paste what it printed. Hints and the solution open up once you have checked your output.

TRY IT YOURSELF

Rotate every stored value

Write rotateAll(vault, rows) that re-seals every row whose value needsRotation, and returns how many it changed. Rows look like { owner: "freelancer:17", sealed: "…" }. Run it twice and show the second run changes nothing.

Write it in the editor, run it on your computer, then press Check and paste what it printed. Hints and the solution open up once you have checked your output.

Summary

  • Secrets come from the secure generator: generateToken and its named variants (32 bytes, with a prefix), randomFromAlphabet for typed codes, random public ids next to your serial keys. Never Math.random, times or counters.
  • Store tokens as hashToken hashes. Reset tokens expire, work once, replace older ones, and the request endpoint answers the same for every address.
  • HMAC keys are at least 16 bytes (use 32). A signed value holds a key id, a purpose, an expiry and data, and is checked in that order: format, key, signature (in constant time), purpose, expiry.
  • hashPassword uses scrypt with a cost floor and a length cap, but no minimum length: enforce your policy yourself.
  • encryptEnvelope gives versioned AES-256-GCM with a fresh IV; bind values to their owner with aad. Never pass your own IV.
  • Load keys with createCryptoKey (size check, key id, loggable fingerprint), prefix stored values with the key id, and rotate with a key ring and an idempotent job.
  • Compare secrets with timingSafeEqualString or timingSafeEqualEncoded, which return false instead of throwing.

Next, authentication uses these building blocks through @zudojs/auth: password logins, JWTs, sessions and lockouts.

Test yourself

Five questions, picked at random from this lesson's question bank. Some ask you to choose an answer, some to predict what code prints, and some to write code and run it in the terminal. Get 4 of 5 right to pass. If you don't, read the explanations and try again: you get 5 different questions.