otpauth

by hectorm

1.2Kstars

64forks

10watchers

Updated 8 months ago

About

A versatile One Time Password (HOTP/TOTP) library for Node.js, Deno, Bun, and browsers enabling secure multi-factor authentication implementations.

One Time Password (HOTP/TOTP) library for Node.js, Deno, Bun and browsers.

Primary Use Case

This library is used to generate and validate HMAC-Based One-Time Passwords (HOTP) and Time-Based One-Time Passwords (TOTP) for multi-factor authentication (MFA) or two-factor authentication (2FA) systems. Developers building authentication systems or enhancing password security in web or server applications would use this tool to integrate secure OTP mechanisms.

Key Features

Supports HOTP and TOTP algorithms as per RFC 4226 and RFC 6238
Compatible with Node.js, Deno, Bun, and browsers
Generates cryptographically secure random secrets
Validates OTP tokens with configurable time windows to handle clock drift
Supports multiple HMAC algorithms including SHA1, SHA256, SHA512, and SHA3 variants
Provides utilities to get token counters, remaining validity time, and URI generation for Google Authenticator
Includes security recommendations and best practices for OTP usage

Installation

Install via npm: npm install otpauth
Import the library in your project: import * as OTPAuth from "otpauth"
Use the library in Node.js, Deno, Bun, or browser environments

Usage

>_ import * as OTPAuth from "otpauth";

Imports the OTPAuth library for use in your application.

>_ let totp = new OTPAuth.TOTP({ issuer: "ACME", label: "Alice", algorithm: "SHA1", digits: 6, period: 30, secret: "US3WHSG7X5KAPV27VANWKQHF3SH3HULL" });

Creates a new TOTP object configured with issuer, label, algorithm, digits, period, and secret.

>_ let secret = new OTPAuth.Secret({ size: 20 });

Generates a cryptographically secure random secret of 20 bytes.

>_ let token = totp.generate();

Generates the current OTP token as a string.

>_ let delta = totp.validate({ token, window: 1 });

Validates a given token within a time window to account for clock drift, returning the token delta or null if invalid.

>_ let counter = totp.counter();

Retrieves the current counter value representing the number of intervals since the Unix epoch.

>_ let remaining = totp.remaining();

Returns the remaining milliseconds until the current token expires.

>_ let uri = totp.toString();

Converts the TOTP configuration to a Google Authenticator-compatible key URI format.

>_ const OTPAuth = await import("otpauth");

Loads the OTPAuth library dynamically in a browser console environment.

Security Frameworks

Initial Access

Credential Access

Defense Evasion

Persistence

Impact

Usage Insights

Integrate OTPAuth into authentication flows to enforce strong MFA, reducing risk of credential compromise.
Use the library to simulate MFA bypass attempts during purple team exercises to improve detection capabilities.
Develop automated tests in CI/CD pipelines to validate OTP implementation correctness and prevent regressions.
Combine with identity management solutions to streamline secure onboarding and offboarding processes.
Leverage configurable time windows and multiple HMAC algorithms to balance usability and security in diverse environments.