OTPAuth: Generate and Verify One-Time Passwords in JavaScript

OTPAuth is a JavaScript library for generating and validating time-based (TOTP) and counter-based (HOTP) one-time passwords.

It allows you to handle authenticator-app enrollment URIs, shared secrets, and code validation for two-factor authentication in browsers and server-side JavaScript.

Features

• Implements the HOTP and TOTP standards (RFC 4226 and RFC 6238).
• Supports SHA-1, SHA-2, and SHA-3 hashing algorithms.
• Generates random secrets with base32, hexadecimal, UTF-8, and Latin-1 representations.
• Accepts configurable validation windows for clock drift and counter offsets.
• Rejects previously accepted TOTP time steps using afterCounter.
• Calculates the milliseconds remaining before a TOTP code expires.

How To Use It

Browser Setup

Use the UMD build for a plain script tag. This example generates a temporary secret and displays one TOTP code.

Keep account secrets and code verification on the server for production use.

<output id="otp-code"></output>
<script src="https://cdn.jsdelivr.net/npm/otpauth/dist/otpauth.umd.min.js"></script>
<script>
  const totp = new OTPAuth.TOTP({
    issuer: "Example App",
    label: "[email protected]"
  });
  document.querySelector("#otp-code").textContent = totp.generate();
</script>

Browser ES Modules

<script type="module">
  import * as OTPAuth from "https://cdn.jsdelivr.net/npm/otpauth/dist/otpauth.esm.min.js";
  const token = new OTPAuth.TOTP().generate();
  console.log(token);
</script>

Install with npm

Use the npm package with Node.js or Bun.

npm install otpauth

import * as OTPAuth from "otpauth";
const totp = new OTPAuth.TOTP({
  issuer: "Example App",
  label: "[email protected]",
  secret: new OTPAuth.Secret({ size: 20 })
});
console.log(totp.generate());
console.log(totp.remaining()); // Milliseconds until the next code

Create an Authenticator Enrollment URI

Generate an account secret on the server and encode its otpauth:// URI as a QR code for an authenticator app.

import * as OTPAuth from "otpauth";
const secret = new OTPAuth.Secret({ size: 20 });
const totp = new OTPAuth.TOTP({
  issuer: "Example App",
  label: "[email protected]",
  secret
});
const enrollmentUri = totp.toString();
const manualEntryKey = secret.base32;

Validate TOTP Codes and Prevent Replay

On the server, load the account secret and last accepted time-step counter (null for the first attempt). Implement saveCounter as an atomic compare-and-set operation that returns true only after saving the new counter.

import * as OTPAuth from "otpauth";
async function verifyTOTP({ secret, token, lastCounter, saveCounter }) {
  const totp = new OTPAuth.TOTP({ secret });
  const timestamp = Date.now();
  const delta = totp.validate({
    token,
    timestamp,
    window: 1,
    afterCounter: lastCounter
  });
  if (delta === null) return false;
  const matchedCounter = totp.counter({ timestamp }) + delta;
  return saveCounter(lastCounter, matchedCounter);
}

Generate and Validate HOTP Codes

HOTP uses a counter shared by the generator and verifier. Advance the stored counter past the accepted value after successful verification.

import * as OTPAuth from "otpauth";
const hotp = new OTPAuth.HOTP({
  secret: new OTPAuth.Secret({ size: 20 }),
  counter: 0
});
const token = hotp.generate();
const delta = hotp.validate({ token, counter: hotp.counter, window: 1 });
if (delta !== null) {
  hotp.counter += delta + 1;
}

Public API Reference

TOTP and HOTP Constructors

Both constructors accept an optional configuration object. Their options are public instance properties, and base32 secret strings become OTPAuth.Secret instances. OTPAuth.TOTP.defaults and OTPAuth.HOTP.defaults expose the default values, including window: 1 for validation.

new OTPAuth.TOTP({ /* options */ });
new OTPAuth.HOTP({ /* options */ });

Shared Constructor Options and Properties

TOTP and HOTP-Specific Options

TOTP Instance Methods

TOTP Static Methods

HOTP Instance Methods

HOTP Static Methods

Secret Constructor, Properties, and Conversions

new OTPAuth.Secret() generates 20 random bytes by default. Specify size to change the length, or pass an ArrayBufferLike secret through buffer, which takes precedence over size. Use at least 16 bytes (128 bits) for authentication secrets.

const secret = new OTPAuth.Secret({ size: 20 });
const fromBuffer = new OTPAuth.Secret({ buffer: secret.bytes.slice().buffer });

URI Utilities and Library Version

Distribution Builds

Related Resources

• One-time Password Input With Vanilla JavaScript – otp-input.js
• Unstyled One-time Password Input In JavaScript – OTP Input
• Easy One Time Password Input In JavaScript – vanilla-otp.js