TOTP Libraries Showdown: otplib vs speakeasy vs authenticator

Implementing Two-Factor Authentication (2FA) is a standard requirement for modern web applications. While the underlying math (RFC 6238 and RFC 4226) is the same for everyone, the developer experience, maintenance status, and API design of the libraries wrapping these algorithms vary significantly. Let's dig into how otplib, speakeasy, and authenticator handle the real-world tasks of generating secrets, creating QR codes, and verifying tokens.

🛠️ Installation and Setup: Modular vs Monolithic

The way you bring these libraries into your project sets the tone for your codebase.

otplib is designed with modularity in mind. You don't have to import the whole kitchen sink if you only need TOTP. This helps with tree-shaking in bundled environments and keeps your dependencies clear.

// otplib: Import only what you need
import { authenticator } from 'otplib';
// Or for more control:
// import { totp } from 'otplib/core';

speakeasy is a monolithic package. You import the entire library, which includes TOTP, HOTP, and helper functions for QR codes and base32 encoding all in one go.

// speakeasy: Import the whole package
const speakeasy = require('speakeasy');

authenticator follows a similar monolithic approach to speakeasy, exporting a single main object that handles all operations.

// authenticator: Import the main export
const authenticator = require('authenticator');

🔑 Generating Secrets and QR Codes

A critical part of 2FA setup is generating a shared secret and presenting it to the user via a QR code. This is where the differences in "batteries-included" features become obvious.

speakeasy shines here because it includes a helper to generate the otpauth:// URL string directly, which is exactly what QR code libraries (like qrcode) need. It feels very complete out of the box.

// speakeasy: Generate secret and URL in one go
const secret = speakeasy.generateSecret({
  name: "MyApp (user@example.com)",
  issuer: "MyApp",
  length: 20
});

// secret.otpsauth_url contains the ready-to-use QR string
console.log(secret.otpauth_url);

otplib takes a more decoupled approach. It generates the secret, but you must manually construct the otpauth:// URL string yourself before passing it to a QR code generator. This adds a few lines of code but gives you full control over the URL format.

// otplib: Generate secret, then build URL manually
const secret = authenticator.generateSecret();
const otpauth = authenticator.keyuri(
  "user@example.com", 
  "MyApp", 
  secret
);

// Pass 'otpauth' string to your QR library
console.log(otpauth);

authenticator provides a method to generate the key, but like otplib, it often requires you to manually format the URI string for QR code generation, lacking the direct otpauth_url property convenience found in speakeasy.

// authenticator: Generate key and format URI
const key = authenticator.generateKey("MyApp", "user@example.com");
// You must manually construct the otpauth:// URI string here
const uri = `otpauth://totp/MyApp:user@example.com?secret=${key}&issuer=MyApp`;

✅ Verifying Tokens: The Critical Path

When a user logs in, you must verify the 6-digit code they entered. All three libraries do this, but their API signatures and default behaviors differ slightly.

otplib uses a clean, async-friendly API. It throws an error if the token is invalid (depending on configuration) or returns a boolean. It handles time-window checking (allowing for slight clock drift) elegantly.

// otplib: Verify with built-in window handling
const token = "123456";
const secret = "...user's secret...";

const isValid = authenticator.verify({
  token: token,
  secret: secret,
  window: 1 // Checks previous and next token too
});

if (isValid) {
  console.log("Login successful");
}

speakeasy returns a boolean directly. It is straightforward but requires you to ensure you are passing the correct options for time-step and window, or it might be too strict.

// speakeasy: Verify returns true/false
const tokenValid = speakeasy.totp.verify({
  secret: "...user's secret...",
  encoding: "base32",
  token: "123456",
  window: 1
});

if (tokenValid) {
  console.log("Login successful");
}

authenticator also provides a verification method, but its API can feel slightly less intuitive regarding option passing compared to the explicit object patterns of the others.

// authenticator: Verify token
const isValid = authenticator.verifyToken(
  "...user's secret...",
  "123456"
);
// Note: Check docs for specific window/drift configuration options
if (isValid) {
  console.log("Login successful");
}

📦 TypeScript and Modern Development

For modern frontend and full-stack teams, TypeScript support is not a luxury; it is a requirement.

otplib is written in TypeScript. This means you get perfect type safety, auto-completion, and interface definitions out of the box. There is no need to install separate @types packages.

// otplib: Full TypeScript support
import { authenticator } from 'otplib';

const secret: string = authenticator.generateSecret();
// Your IDE knows exactly what methods are available

speakeasy is written in older JavaScript. While community-maintained type definitions (@types/speakeasy) exist, they can sometimes lag behind or miss nuanced edge cases. You are relying on the community to keep the types accurate.

// speakeasy: Requires @types/speakeasy
import * as speakeasy from 'speakeasy';
// Types are available but not native to the package

authenticator generally lacks robust, official TypeScript definitions. Using it in a strict TypeScript project often requires writing your own declaration files or disabling strict checks, which increases technical debt.

🚨 Maintenance and Security Trust

Security libraries live or die by their maintenance schedule. If a vulnerability is found in the underlying algorithm implementation or a dependency, you need a maintainer who will patch it quickly.

• otplib: Currently the most active. It receives regular updates, has clear issue tracking, and is built with modern standards. It is the recommended choice for new projects.
• speakeasy: Has a long history and is widely used, but it has experienced long periods of inactivity in the past. While still functional, relying on it for new high-security applications carries a risk that future issues might not be addressed promptly.
• authenticator: Shows the least amount of recent activity and community engagement. In the security world, a quiet repository is often a red flag. It is difficult to recommend this for production systems where accountability is key.

📊 Summary Comparison

💡 The Final Verdict

If you are building something today, otplib is the clear winner. Its native TypeScript support, modular design, and active maintenance make it the most professional choice. The minor inconvenience of manually constructing the QR code URL is a small price to pay for the security and DX benefits.

Use speakeasy only if you are stuck maintaining an older codebase that already uses it, or if the built-in QR URL generator is a absolute deal-breaker and you cannot add a small utility function to replicate it.

Avoid authenticator for new projects. The lack of momentum and weaker ecosystem support makes it a risky foundation for authentication features.