or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authenticator.mdconfiguration.mdhotp.mdindex.mdpresets.mdtotp.md
tile.json

tessl/npm-otplib

HMAC-based (HOTP) and Time-based (TOTP) One-Time Password library compatible with Google Authenticator

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/otplib@12.0.x

To install, run

npx @tessl/cli install tessl/npm-otplib@12.0.0

index.mddocs/

OTPLib

OTPLib is a comprehensive JavaScript One-Time Password (OTP) library implementing both HOTP (RFC 4226) and TOTP (RFC 6238) algorithms. It provides secure authentication solutions compatible with Google Authenticator and other standard authenticator applications, supporting both Node.js and browser environments with full TypeScript definitions.

Package Information

  • Package Name: otplib
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install otplib

Core Imports

import { authenticator, totp, hotp } from "otplib";

For CommonJS:

const { authenticator, totp, hotp } = require("otplib");

For browser environments:

<script src="https://unpkg.com/@otplib/preset-browser@^12.0.0/buffer.js"></script>
<script src="https://unpkg.com/@otplib/preset-browser@^12.0.0/index.js"></script>
<script>
  // window.otplib.authenticator, window.otplib.hotp, window.otplib.totp
</script>

Basic Usage

import { authenticator, totp, hotp } from "otplib";

// Authenticator (TOTP with Base32 secrets - Google Authenticator compatible)
const secret = authenticator.generateSecret();
const token = authenticator.generate(secret);
const isValid = authenticator.check(token, secret);

// TOTP (Time-based)
const totpToken = totp.generate("your-secret-key");
const isTotpValid = totp.check(totpToken, "your-secret-key");

// HOTP (Counter-based)
const hotpToken = hotp.generate("your-secret-key", 0);
const isHotpValid = hotp.check(hotpToken, "your-secret-key", 0);

Architecture

OTPLib is built with a modular architecture:

  • Core Classes: Base HOTP, TOTP, and Authenticator implementations with full customization options
  • Preset Packages: Pre-configured instances optimized for different environments (Node.js, browser, v11 compatibility)
  • Plugin System: Pluggable crypto and base32 libraries for different platforms
  • Type Safety: Full TypeScript support with generic types preserving option configurations
  • RFC Compliance: Tested against RFC 4226 and RFC 6238 test vectors

Capabilities

Authenticator (Google Authenticator Compatible)

TOTP-based authenticator with Base32 secret encoding, fully compatible with Google Authenticator and similar apps. Handles secret generation, QR code URI creation, and token verification.

class Authenticator {
  generate(secret: string): string;
  check(token: string, secret: string): boolean;
  verify(opts: { token: string; secret: string }): boolean;
  generateSecret(numberOfBytes?: number): string;
  keyuri(accountName: string, issuer: string, secret: string): string;
}

const authenticator: Authenticator;

Authenticator

TOTP (Time-based One-Time Password)

Time-based OTP implementation following RFC 6238. Generates tokens based on current time with configurable time steps and validation windows.

class TOTP {
  generate(secret: string): string;
  check(token: string, secret: string): boolean;
  verify(opts: { token: string; secret: string }): boolean;
  checkDelta(token: string, secret: string): number | null;
  timeRemaining(): number;
  timeUsed(): number;
  keyuri(accountName: string, issuer: string, secret: string): string;
}

const totp: TOTP;

TOTP

HOTP (HMAC-based One-Time Password)

Counter-based OTP implementation following RFC 4226. Generates tokens using an incrementing counter value with configurable digits and algorithms.

class HOTP {
  generate(secret: string, counter: number): string;
  check(token: string, secret: string, counter: number): boolean;
  verify(opts: { token: string; secret: string; counter: number }): boolean;
  keyuri(accountName: string, issuer: string, secret: string, counter: number): string;
}

const hotp: HOTP;

HOTP

Configuration and Options

Comprehensive configuration system allowing customization of algorithms, token length, time windows, encoding, and crypto implementations.

interface HOTPOptions {
  algorithm: 'sha1' | 'sha256' | 'sha512';
  digits: number;
  encoding: 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8';
}

interface TOTPOptions extends HOTPOptions {
  epoch: number;
  step: number;
  window: number | [number, number];
}

interface AuthenticatorOptions extends TOTPOptions {
  // Additional Base32 encoding/decoding options
}

Configuration

Environment Presets

Different preset packages optimized for specific environments with appropriate crypto and base32 implementations.

// Node.js (default)
import { authenticator, totp, hotp } from "otplib";

// Browser
import { authenticator, totp, hotp } from "@otplib/preset-browser";

// v11 Compatibility
import { authenticator, totp, hotp } from "@otplib/preset-v11";

Environment Presets

Types

type SecretKey = string;
type Base32SecretKey = string;
type HexString = string;

enum HashAlgorithms {
  SHA1 = 'sha1',
  SHA256 = 'sha256',
  SHA512 = 'sha512'
}

enum KeyEncodings {
  ASCII = 'ascii',
  BASE64 = 'base64',
  HEX = 'hex',
  LATIN1 = 'latin1',
  UTF8 = 'utf8'
}

interface OTPOptions {
  [key: string]: unknown;
}