Generate TOTP

!npm downloads

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:

``bash
npm install gen-totp


or


yarn add gen-totp
`

Usage

$3

`typescript
import genTOTP from 'gen-totp';

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

$3


`ts
import genTOTP from 'gen-totp';

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

Options & API


The genTOTP function accepts a key and an optional options object. By default the key is treated as UTF-8 text; use the encoding option to specify hex or base32 when needed.

1. key: The secret key (default treated as UTF-8). To change how the key is interpreted set options.encoding to one of: utf8 (default), hex, base32.
2. options: An optional object to customize 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 encodings


genTOTP accepts keys in three encodings (default utf8):

- utf8 (default): any UTF-8 string (letters, numbers, symbols, emoji).
- hex: accepts 0-9 and a-f (case-insensitive). Invalid input throws Invalid hex character in key.
- base32: RFC-4648 base32 (A–Z and 2–7). Padding = is stripped; invalid characters throw Invalid base32 character: .

Examples:

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



Deterministic testing & timestamp units


genTOTP accepts an optional third argument timestamp in unix milliseconds for deterministic outputs (used heavily in tests). Example:

`ts
genTOTP('my-secret', { digits: 6, period: 30 }, Date.parse('2021-01-01T00:00:00Z'))
`

Input validation & verification defaults


- encoding: 'hex' will validate that the key contains only hex characters and throw Invalid hex character in key when invalid.
- period must be a positive number; otherwise Invalid period; must be a positive number is thrown.
- digits must be an integer between 1 and 10; otherwise Invalid digits; must be an integer between 1 and 10 is thrown.

Verification defaults:

- verifyTOTP default window = 1 (checks previous/current/next period).
- verifyHOTP default window = 10 and returns { newCounter } on success or null on failure.

See src/index.ts for exact behavior and error messages.

Features


- genTOTP(key, options?, timestamp?) — generate TOTP (default: period=30, digits=6, algorithm='SHA-1', encoding='utf8'). timestamp is unix milliseconds for deterministic output.
- verifyTOTP(key, token, options?, timestamp?) — verify a TOTP; returns true|false. Default verification window = 1.
- genHOTP(key, counter, options?) — generate HOTP given a counter.
- verifyHOTP(key, token, counter, options?) — verify HOTP; returns { newCounter } on success or null on failure. Default window = 10.
- base32ToHex(input) — RFC-4648-like base32 decoder used internally; throws Invalid base32 character: on invalid input.
- bytesToBase32(bytes) — encode raw bytes to base32 (used by generateSecretKey).
- generateSecretKey(length = 20) — generate a cryptographically-secure base32 secret (default 20 bytes → 32 base32 chars).
- generateOtpAuthUri(key, { accountName, issuer, ... }) — build an otpauth://totp/... URI for QR codes; requires a valid base32 key and throws Invalid base32 key for otpauth URI for invalid input.
- Supported algorithms: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 (see FixedLengthVariantType).
- Key encodings: utf8 (default), hex (validated; throws Invalid hex character in key), base32 (uppercased, = padding stripped).
- Exports: default export is genTOTP; named exports include base32ToHex, bytesToBase32, genHOTP, verifyHOTP, verifyTOTP, generateSecretKey, generateOtpAuthUri`.

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:

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