gen-totp

Generate TOTP

Time-based One-Time Password (TOTP) is an algorithm that generates a one-time password based on the current time. TOTP is an extension of the HMAC-based One-Time Password (HOTP) algorithm and is standardized in RFC 6238. For more details, see Wikipedia.

Table of Contents

• Generate TOTP
  • Table of Contents
  • Installation
  • Usage
    • Basic Usage
    • Customizing OTP Length
  • Options
  • Key Format and Encoding
  • Documentation
  • Contributing

Installation

You can install gen-totp via npm or yarn:

npm install gen-totp
# or
yarn add gen-totp

Usage

Basic Usage

import genTOTP from 'gen-totp';

const otp = genTOTP('test-key');
// Returns a 6-digit OTP by default
console.log(otp);

Customizing OTP Length

import genTOTP from 'gen-totp';

const otp = genTOTP('test-key', { digits: 4 });
// Returns a 4-digit OTP
console.log(otp);

Options

The genTOTP function accepts two parameters:

• key: A string containing the base32-encoded secret key. It can include numbers, uppercase letters, _, and -.
• options: An optional object to customize the OTP generation. The available options are detailed in the table below:

Option	Type	Default	Description
digits	number	6	The number of digits in the generated OTP.
period	number	30	The time period (in seconds) after which a new OTP is generated.
algorithm	string	'SHA-1'	The hashing algorithm used to generate the OTP. Supported algorithms include:
			- SHA-1
			- SHA-224
			- SHA-256
			- SHA-384
			- SHA-512
			- SHA3-224
			- SHA3-256
			- SHA3-384
			- SHA3-512
			For more details, refer to the JsSHA documentation.

Key Format and Encoding

When providing a key to the genTOTP function, you can use different encodings specified by the encoding option:

• UTF-8 Encoding (default):

  • Any valid UTF-8 string can be used as the key
  • Supports alphabetic characters (A-Z, a-z), numeric characters (0-9), special characters, and Unicode characters including emoji

• Hex Encoding :

  • The key should be a valid hexadecimal string
  • Only characters 0-9 and a-f (case insensitive) are allowed

• Base32 Encoding :

  • The key should be a valid base32 string according to RFC 4648
  • Only uppercase letters A-Z and digits 2-7 are allowed
  • Padding with '=' is optional Example of valid keys:

• UTF-8: mySecureKey123! , secretKey你好 , emojiKey😊🔑
• Hex: deadbeef1234 , 01a2b3c4d5e6f7
• Base32: JBSWY3DPEHPK3PXP , GEZDGNBVGY3TQOJQ

Documentation

For more detailed documentation, visit the Official Documentation .

Contributing

Contributions are welcome! If you have any bug reports, suggestions, or feature requests, please open an issue on GitHub.

To contribute:

• Fork the repository
• Create a new feature branch ( git checkout -b feature/new-feature )
• Commit your changes ( git commit -m 'Add new feature' )
• Push to the branch ( git push origin feature/new-feature )
• Create a new Pull Request Make sure to follow the Contributor Covenant Code of Conduct when participating in the project.

Changelog

2.0.7 (2025-05-21)

Bug Fixes

• 🐛 resolve issues (2957ff8)
• package.json (b41a0aa)