@ebizzone/totp v1.0.0

@ebizzone/totp

A modern and minimal TOTP (Time-based One-Time Password) library for Node.js, browsers, and edge environments.

🔁 This is yet another TOTP library — rewritten from the ground up because most existing libraries are outdated and have not been maintained in over 3 years.

Why this library?

• ✅ Written in modern TypeScript
• ✅ Uses async/await and Web Crypto API
• ✅ Avoids deprecated APIs like new Buffer()
• ✅ Works seamlessly in Node.js, browsers, and edge runtimes (like Cloudflare Workers)
• ✅ Auto-detects environment: uses Node.js crypto or falls back to WebCrypto
• ✅ No external library dependencies — built to be lightweight and portable

Installation

npm install @ebizzone/totp

Usage

import { createTotp, generateTotp, verifyTotp } from '@ebizzone/totp';

createTotp(options: Partial<TotpParameter>, useSubtle = false): Promise<TotpResult>

Generates a new TOTP secret and returns the key in multiple formats and a URI compatible with authenticator apps.

Parameters

options Fields

Returns

Promise<TotpResult>

type TotpResult = {
  base32: string;
  hex: string;
  base64: string;
  uri: string; // otpauth:// URI
};

generateTotp(secret: string, options?: Partial<TotpParameter>, useSubtle = false): Promise<string>

Generates a TOTP code from a given secret and options.

Parameters

options Fields

Returns

Promise<string> — The generated TOTP code, e.g. "123456"

verifyTotp(secret: string, otp: string, window = 1, options?: Partial<TotpParameter>, useSubtle = false): Promise<boolean>

Verifies if a given TOTP code is valid within a specified time window.

Parameters

options Fields

Returns

Promise<boolean> — true if the OTP is valid, false otherwise

Example

const secret = await createTotp({
  issuer: 'MyApp',
  account: 'user@example.com'
});

const otp = await generateTotp(secret.base32);

const isValid = await verifyTotp(secret.base32, otp);

console.log({ otp, isValid });

📷 Note: This library does not provide any QR code generation.
You can use any QR code library (e.g. qrcode) to convert the uri field into a scannable QR code for use with authenticator apps.

Recommended Settings for Authenticator Apps

To ensure compatibility with popular TOTP apps such as Google Authenticator, Authy, Microsoft Authenticator, and 1Password, it's recommended to use the following options:

These values are used by default in this library, so you only need to change them if you have a specific use case.

Environment Support

All functions auto-detect the runtime:

You can also force usage of WebCrypto with useSubtle = true.

License

MIT