The second factor is just an HMAC of the clock

otpauth://totp/Acme%20Bank:ada@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Acme%20Bank&algorithm=SHA1&digits=6&period=30

  scheme     otpauth://
  type       totp             (or hotp, for counter-based)
  label      Issuer:account   URL-encoded; shown in the app's list
  secret     base32, no padding, no spaces      <- the only part that is secret
  issuer     repeated as a parameter; apps prefer this over the label prefix
  algorithm  SHA1 | SHA256 | SHA512   many apps silently assume SHA1
  digits     6 | 8                    8 is rare; test your apps before choosing it
  period     seconds per step, 30 by default

import { Router } from "express";
import { newSecret, base32Decode, totp } from "../totp";
import { encrypt, decrypt } from "../crypto/envelope";
import { hashRecoveryCode, newRecoveryCodes } from "../recovery";

const router = Router();

// STEP 1-3 — provision a PENDING secret. Nothing about the account changes yet.
router.post("/2fa/setup", requireSession, async (req, res) => {
  const user = req.user;

  if (user.totpStatus === "active") {
    // Re-enrolling replaces a working factor: make them prove they still hold it.
    return res.status(409).json({ error: "2fa_already_enabled" });
  }

  const secret = newSecret();                       // base32, from a CSPRNG

  await db.totpEnrolment.upsert({
    userId: user.id,
    // Encrypted with a key from your KMS — see the note below.
    secretCiphertext: await encrypt(secret, { aad: `totp:${user.id}` }),
    status: "pending",
    createdAt: new Date(),
    expiresAt: new Date(Date.now() + 10 * 60_000),  // provisioning window
  });

  const label = encodeURIComponent(`Acme:${user.email}`);
  const uri =
    `otpauth://totp/${label}` +
    `?secret=${secret}&issuer=Acme&algorithm=SHA1&digits=6&period=30`;

  // The secret leaves the server exactly once, to the session that asked for it.
  res.json({ uri, secret, expiresIn: 600 });
});

// STEP 6-8 — the user proves the app works. Only now does the factor go live.
router.post("/2fa/confirm", requireSession, async (req, res) => {
  const user = req.user;
  const code = String(req.body.code ?? "").replace(/\s/g, "");

  if (!/^\d{6}$/.test(code)) {
    return res.status(400).json({ error: "invalid_code_format" });
  }
  if (!(await rateLimit.allow(`2fa:confirm:${user.id}`, { max: 10, windowSec: 300 }))) {
    return res.status(429).json({ error: "too_many_attempts" });
  }

  const row = await db.totpEnrolment.find({ userId: user.id, status: "pending" });
  if (!row || row.expiresAt < new Date()) {
    return res.status(400).json({ error: "setup_expired" });   // restart step 1
  }

  const secret = base32Decode(await decrypt(row.secretCiphertext, { aad: `totp:${user.id}` }));

  // Verification proper — drift window and replay guard live here (section 07).
  const match = verifyTotp(secret, code, { window: 1, lastUsedStep: row.lastUsedStep });
  if (!match.ok) {
    return res.status(400).json({ error: "code_did_not_match" });
  }

  const recovery = newRecoveryCodes(10);

  await db.transaction(async (tx) => {
    await tx.totpEnrolment.update(row.id, {
      status: "active",
      lastUsedStep: match.step,          // burn this step immediately
      activatedAt: new Date(),
    });
    await tx.recoveryCodes.replaceAll(
      user.id,
      await Promise.all(recovery.map(hashRecoveryCode)),
    );
  });

  // Tell the human out of band. If they did not do this, they need to know now.
  await mail.send(user.email, "twoFactorEnabled", { at: new Date(), ip: req.ip });

  // Shown exactly once, and never retrievable again.
  res.json({ recoveryCodes: recovery });
});

// ---------- half one: the password ----------
router.post("/login", async (req, res) => {
  const { email, password } = req.body;

  const user = await db.user.findByEmail(email);

  // Always run the hash comparison, even when the user does not exist, so the
  // response time does not reveal which emails are registered.
  const ok = await argon2.verify(user?.passwordHash ?? DUMMY_HASH, password);
  if (!user || !ok) {
    return res.status(401).json({ error: "invalid_credentials" });
  }

  if (user.totpStatus !== "active") {
    return issueSession(res, user);        // no second factor: done
  }

  // A deliberately weak token: proves step one, authorises nothing else.
  const mfaToken = await mfaTokens.create({
    userId: user.id,
    ttlSec: 300,                            // five minutes, not a session lifetime
    singleUse: true,
    boundTo: { ip: req.ip, userAgent: req.get("user-agent") },
  });

  res.json({ mfaRequired: true, mfaToken, methods: ["totp", "recovery"] });
});

// ---------- half two: the factor ----------
router.post("/login/2fa", async (req, res) => {
  const { mfaToken, code } = req.body;

  const pending = await mfaTokens.consume(mfaToken);   // single use, atomically
  if (!pending) {
    return res.status(401).json({ error: "mfa_token_invalid_or_expired" });
  }

  // Rate limit on the ACCOUNT, not just the IP: the attacker controls the IP.
  const allowed = await rateLimit.allow(`2fa:verify:${pending.userId}`, {
    max: 5,
    windowSec: 300,
  });
  if (!allowed) {
    await notify.suspiciousActivity(pending.userId);
    return res.status(429).json({ error: "too_many_attempts" });
  }

  const user = await db.user.find(pending.userId);
  const enrolment = await db.totpEnrolment.findActive(user.id);
  const secret = base32Decode(await decrypt(enrolment.secretCiphertext, {
    aad: `totp:${user.id}`,
  }));

  const result = verifyTotp(secret, code, {
    window: 1,
    lastUsedStep: enrolment.lastUsedStep,
  });

  if (!result.ok) {
    // A recovery code is the documented fallback — try it before failing.
    if (await recovery.consume(user.id, code)) {
      await mail.send(user.email, "recoveryCodeUsed", { ip: req.ip });
      return issueSession(res, user, { requirePasswordChange: false });
    }
    return res.status(401).json({ error: "invalid_code" });
  }

  // Burn the step so the same six digits cannot be replayed for the rest of
  // its window — by this request, or by anyone who watched it.
  await db.totpEnrolment.update(enrolment.id, { lastUsedStep: result.step });

  return issueSession(res, user);
});

import { timingSafeEqual } from "node:crypto";

/** Compare without leaking how many leading digits matched. */
function constantTimeEquals(a: string, b: string): boolean {
  const ba = Buffer.from(a, "utf8");
  const bb = Buffer.from(b, "utf8");
  if (ba.length !== bb.length) return false;   // length is not secret here
  return timingSafeEqual(ba, bb);
}

export type VerifyResult =
  | { ok: true; step: number; driftSteps: number }
  | { ok: false; reason: "no_match" | "replayed" };

export function verifyTotp(
  secret: Buffer,
  submitted: string,
  opts: { window?: number; lastUsedStep?: number; period?: number; digits?: number; now?: number },
): VerifyResult {
  const { window = 1, lastUsedStep = -1, period = 30, digits = 6, now = Date.now() } = opts;

  const code = submitted.replace(/\s/g, "");
  if (code.length !== digits || !/^\d+$/.test(code)) return { ok: false, reason: "no_match" };

  const current = Math.floor(now / 1000 / period);

  for (let drift = -window; drift <= window; drift++) {
    const step = current + drift;

    // Compare EVERY candidate: returning early on the first match leaks, via
    // timing, which step matched — and therefore the client's clock offset.
    if (!constantTimeEquals(hotp(secret, BigInt(step), digits), code)) continue;

    // The code is real. Has this step already been spent?
    if (step <= lastUsedStep) return { ok: false, reason: "replayed" };

    return { ok: true, step, driftSteps: drift };
  }

  return { ok: false, reason: "no_match" };
}

// The caller MUST persist result.step as lastUsedStep, in the same transaction
// that establishes the session. Verifying and recording in two separate steps
// leaves a race two concurrent requests can both win.

import { randomInt, createHash } from "node:crypto";
import argon2 from "argon2";

const ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // no I, O, 0, 1

/** Ten codes of 10 characters ≈ 50 bits each — unguessable, still typeable. */
export function newRecoveryCodes(count = 10): string[] {
  return Array.from({ length: count }, () => {
    let out = "";
    for (let i = 0; i < 10; i++) out += ALPHABET[randomInt(ALPHABET.length)];
    return `${out.slice(0, 5)}-${out.slice(5)}`;   // ABCDE-FGHIJ
  });
}

/**
 * Hash them. They are bearer credentials that fully replace the second factor,
 * so a database dump must not yield working ones.
 */
export function hashRecoveryCode(code: string) {
  return argon2.hash(normalise(code), { type: argon2.argon2id });
}

function normalise(code: string) {
  return code.toUpperCase().replace(/[\s-]/g, "");   // forgive formatting
}

/** Single use, and the check must not reveal which code was close. */
export async function consume(userId: string, submitted: string): Promise<boolean> {
  const candidate = normalise(submitted);
  if (candidate.length !== 10) return false;

  const rows = await db.recoveryCodes.findUnused(userId);

  for (const row of rows) {
    if (await argon2.verify(row.hash, candidate)) {
      // Mark used atomically — two concurrent requests must not both succeed.
      const claimed = await db.recoveryCodes.markUsedIfUnused(row.id);
      if (!claimed) return false;

      await mail.send(userId, "recoveryCodeUsed", { remaining: rows.length - 1 });
      return true;
    }
  }
  return false;
}

// 1. Ask the server for options. The challenge MUST be server-generated,
//    random, single-use, and remembered for the verification step.
const options = await fetch("/webauthn/register/options", { method: "POST" })
  .then((r) => r.json());

// 2. The browser prompts; the authenticator generates a keypair and signs.
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: base64urlToBuffer(options.challenge),
    rp: { id: "acme.com", name: "Acme" },   // must match the page's origin
    user: {
      id: base64urlToBuffer(options.userId), // opaque; NOT an email or a counter
      name: "ada@example.com",
      displayName: "Ada Lovelace",
    },
    pubKeyCredParams: [
      { type: "public-key", alg: -7 },      // ES256 — universally supported
      { type: "public-key", alg: -257 },    // RS256 — older Windows Hello
    ],
    authenticatorSelection: {
      residentKey: "preferred",             // "preferred" ⇒ a discoverable passkey
      userVerification: "preferred",        // PIN or biometric, not just presence
    },
    timeout: 60_000,
    excludeCredentials: options.existing,   // stop double-registering one key
  },
});

// 3. Send the attestation back. The server stores the PUBLIC key only.
await fetch("/webauthn/register/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(serialiseCredential(credential)),
});

import {
  generateAuthenticationOptions,
  verifyAuthenticationResponse,
} from "@simplewebauthn/server";

const rpID = "acme.com";
const origin = "https://acme.com";

router.post("/webauthn/login/options", async (req, res) => {
  const options = await generateAuthenticationOptions({
    rpID,
    userVerification: "preferred",
  });

  // The challenge is the anti-replay device: store it against this attempt and
  // delete it after one use.
  await challenges.put(req.sessionID, options.challenge, { ttlSec: 120 });
  res.json(options);
});

router.post("/webauthn/login/verify", async (req, res) => {
  const expectedChallenge = await challenges.take(req.sessionID); // single use
  if (!expectedChallenge) return res.status(400).json({ error: "no_challenge" });

  const stored = await db.credentials.findById(req.body.id);
  if (!stored) return res.status(400).json({ error: "unknown_credential" });

  const verification = await verifyAuthenticationResponse({
    response: req.body,
    expectedChallenge,
    expectedOrigin: origin,   // ← the phishing defence, in one field
    expectedRPID: rpID,
    credential: {
      id: stored.id,
      publicKey: stored.publicKey,
      counter: stored.counter,
    },
    requireUserVerification: true,
  });

  if (!verification.verified) return res.status(401).json({ error: "bad_assertion" });

  // A counter that went backwards means the credential was cloned. Hardware
  // keys increment it; many phone-based passkeys always report 0 — treat 0 as
  // "not supported", and any decrease as an incident.
  const next = verification.authenticationInfo.newCounter;
  if (stored.counter > 0 && next <= stored.counter) {
    await security.flagPossibleClone(stored.userId, stored.id);
    return res.status(401).json({ error: "counter_regression" });
  }
  await db.credentials.updateCounter(stored.id, next);

  return issueSession(res, stored.userId);
});

import { randomInt } from "node:crypto";

export async function startPushChallenge(userId: string, req: Request) {
  // Number matching: the browser shows a number, the phone offers three.
  // Tapping "approve" is no longer possible without seeing the login screen.
  const answer = String(randomInt(10, 100));            // two digits
  const decoys = [String(randomInt(10, 100)), String(randomInt(10, 100))];

  const challenge = await pushChallenges.create({
    userId,
    answer,
    choices: shuffle([answer, ...decoys]),
    ttlSec: 120,
    attemptsAllowed: 1,                                  // one wrong tap ends it
    context: {                                           // shown on the phone
      ip: req.ip,
      approxLocation: await geo.city(req.ip),
      app: "Acme Web",
      at: new Date(),
    },
  });

  // Throttle HARD. Fatigue attacks are a volume attack; volume is the signal.
  const recent = await pushChallenges.countRecent(userId, { windowSec: 600 });
  if (recent > 3) {
    await security.lockPush(userId, { minutes: 30 });
    await mail.send(userId, "suspiciousPushVolume", { ip: req.ip });
    throw new TooManyChallenges();
  }

  return { challengeId: challenge.id, displayNumber: answer };  // shown in the BROWSER
}

export async function resolvePushChallenge(challengeId: string, tapped: string) {
  const c = await pushChallenges.consume(challengeId);   // single use
  if (!c) return { ok: false, reason: "expired" };

  if (tapped !== c.answer) {
    await security.recordFailedApproval(c.userId);       // a wrong tap is a signal
    return { ok: false, reason: "wrong_number" };
  }
  return { ok: true, userId: c.userId };
}