Building 2FA Systems: Crypto Engines vs. QR Generators

Implementing Two-Factor Authentication (2FA) in a Node.js application requires two distinct technical capabilities: generating and validating cryptographic tokens (TOTP/HOTP) and creating QR codes for users to scan with their authenticator apps. The packages speakeasy, otplib, notp, node-2fa, and authenticator address the cryptography, while qrcode handles the visual encoding. Understanding the difference between low-level crypto engines and high-level wrappers is key to building a secure, maintainable system.

🔐 Core Cryptography: Modular vs. Monolithic

The heart of 2FA is the algorithm that generates the 6-digit code. You have three main architectural choices here: a modular modern system (otplib), a comprehensive classic system (speakeasy), or a minimal legacy system (notp).

otplib is built for modern JavaScript. It splits functionality into small, interchangeable plugins. You import exactly what you need (e.g., just the TOTP logic), which helps keep your bundle size down and makes testing easier. It also has first-class TypeScript definitions.

// otplib: Modular import
import { authenticator } from 'otplib';

// Configure options globally or per call
authenticator.options = { step: 30, digits: 6 };

const secret = authenticator.generateSecret();
const token = authenticator.generate(secret);
const isValid = authenticator.verify({ token, secret });

speakeasy is the industry workhorse. It provides a single, large object with methods for every possible variation (TOTP, HOTP, counter-based). It is less modular but extremely stable and widely trusted in production environments for years.

// speakeasy: Comprehensive single import
import speakeasy from 'speakeasy';

const secret = speakeasy.generateSecret({ name: "MyApp" });
const token = speakeasy.totp({
  secret: secret.base32,
  encoding: 'base32',
  step: 30
});

const isValid = speakeasy.totp.verify({
  secret: secret.base32,
  encoding: 'base32',
  token: token,
  window: 1
});

notp is the minimal option. It does one thing and nothing else. It lacks the helper functions for generating secrets or creating URIs that the others have, meaning you often have to write more boilerplate code yourself.

// notp: Minimalist approach
import notp from 'notp';

// You must manage your own secret generation externally
const secret = "JBSWY3DPEHPK3PXP"; 
const token = notp.totp.gen(secret);

const verification = notp.totp.verify(token, secret, { window: 1 });
// verification returns null if invalid, or an object if valid

🧩 Abstraction Levels: Wrappers vs. Direct Control

Some packages try to make life easier by wrapping the crypto logic into a single "setup" function. This trades flexibility for speed.

node-2fa is a wrapper designed to get you running in seconds. It handles secret generation, URI creation, and verification in one go. However, if you need to change the algorithm (e.g., from SHA1 to SHA256) or adjust the time step dynamically, you might hit its limits.

// node-2fa: High-level wrapper
import { generateSecret, generateAuthenticatorUrl, verifyToken } from 'node-2fa';

// Generates secret and URL in one step
const { secret, url } = generateAuthenticatorUrl({ 
  name: "MyApp", 
  account: "user@example.com" 
});

const isValid = verifyToken(secret, userInputToken);

authenticator follows a similar pattern, offering a simplified interface for common tasks. It is useful for basic implementations but, like node-2fa, you should check its update history before relying on it for high-security contexts, as wrappers can sometimes lag behind core security patches.

// authenticator: Simplified interface
import authenticator from 'authenticator';

// Generate a secret key
const secret = authenticator.generateKey();

// Generate a token
const token = authenticator.generateToken(secret);

// Verify a token
const isValid = authenticator.verifyToken(secret, token);

In contrast, speakeasy and otplib force you to be explicit. You must generate the secret, build the URI string yourself (or use their helpers), and pass every parameter to the verify function. This verbosity is a feature, not a bug—it prevents hidden magic from causing security gaps.

📱 Generating the Provisioning URI

To let a user scan a code, you must create a specific URL format (otpauth://...). The lower-level libraries give you the tools to build this; the wrappers often do it for you.

speakeasy includes a dedicated helper to build this URL correctly, ensuring all parameters (issuer, algorithm, digits) are encoded properly.

// speakeasy: Built-in URI generator
const otpauthUrl = speakeasy.otpauthURL({
  secret: secret.base32,
  label: "MyApp:user@example.com",
  issuer: "MyApp",
  algorithm: 'SHA1',
  digits: 6,
  period: 30
});
// Returns: otpauth://totp/MyApp:user@example.com?secret=...

otplib expects you to construct the URL or use a plugin, giving you full control over the string format if you need custom parameters.

// otplib: Manual or plugin-based URI construction
import { urlencoder } from 'otplib-plugin-urlencoder';
// Or manually construct:
const label = encodeURIComponent("MyApp:user@example.com");
const secret = encodeURIComponent(mySecret);
const otpauthUrl = `otpauth://totp/${label}?secret=${secret}&issuer=MyApp`;

node-2fa hides this entirely, returning the URL as part of its setup object.

// node-2fa: URL returned automatically
const { url } = generateAuthenticatorUrl({ name: "MyApp", account: "user" });
// You get the string ready to use immediately

🖼️ Rendering the QR Code

Once you have the otpauth URL from any of the crypto libraries, you need to turn it into an image. This is where qrcode comes in. It is the standard for this task and works independently of which crypto library you chose.

qrcode can output to the terminal, a data URL (for web images), or SVG. It is robust and handles long strings well.

// qrcode: Generating a Data URL for web display
import QRCode from 'qrcode';

async function generateQRImage(otpauthUrl) {
  try {
    // Returns a 'data:image/png;base64,...' string
    const imageUrl = await QRCode.toDataURL(otpauthUrl);
    return imageUrl;
  } catch (err) {
    console.error('Failed to generate QR', err);
  }
}

// Usage with speakeasy output
const qrImage = await generateQRImage(otpauthUrl);
// <img src="${qrImage}" />

You can also render directly to the console for CLI tools:

// qrcode: Terminal output
import QRCode from 'qrcode';

QRCode.toString(otpauthUrl, { type: 'terminal' }, (err, code) => {
  console.log(code);
  // Prints an ASCII art QR code to the console
});

⚠️ Deprecation and Maintenance Warning

When selecting a crypto library, maintenance is a security feature.

• notp: While functional, it has seen very little activity in recent years. For new projects, avoid notp unless you have a specific constraint requiring its minimal footprint. The lack of recent updates means it might not reflect the latest best practices or environment compatibility fixes.
• authenticator and node-2fa: These are convenient, but always verify their GitHub repositories for recent commits. If a wrapper hasn't been updated in over a year, prefer speakeasy or otplib directly, as they have larger communities auditing the core logic.
• speakeasy and otplib: Both are actively maintained and trusted. speakeasy has a longer track record; otplib has a more modern codebase.

🏗️ Architectural Recommendation

For most professional applications, the best approach is to combine a robust crypto engine with the standard QR generator.

1. Select otplib if you are starting a new TypeScript project and value modularity and type safety.
2. Select speakeasy if you need a proven, "batteries-included" solution with extensive documentation and community examples.
3. Always use qrcode for the visual component, regardless of your crypto choice.

Avoid relying on high-level wrappers like node-2fa for critical infrastructure unless you have verified they meet your specific security policy requirements, as they can obscure important configuration details.

📊 Summary Comparison

💡 Final Thought

Security code should be clear, not magical. Using speakeasy or otplib alongside qrcode gives you full visibility into how tokens are generated and how URIs are constructed. This transparency makes it easier to audit your code, rotate secrets, and adapt to future security standards without being locked into a black-box wrapper.