ran
English

TOTP

Time-based One-Time Password generator implementing RFC 6238 standard. Used to generate dynamic verification codes, commonly used in two-factor authentication (2FA) scenarios.

API

TOTP.generate

Generate a time-based one-time password.

Return

Argument Description Type
Object Returns an object containing OTP and expiry { otp: string, expires: number }
otp Generated one-time password string string
expires Timestamp (milliseconds) when OTP expires number

Parameters

Parameter Description Type Default
key Base32 encoded secret key string string Required
options Optional configuration Options See below

Options

Parameter Description Type Default
digits Number of digits in OTP number 6
algorithm Hash algorithm 'SHA-1' | 'SHA-224' | 'SHA-256' | 'SHA-384' | 'SHA-512' | 'SHA3-224' | 'SHA3-256' | 'SHA3-384' | 'SHA3-512' 'SHA-1'
period Time window period (seconds) number 30
timestamp Timestamp (milliseconds) for generating OTP number Date.now()

Example

Basic Usage

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP'; // Base32 encoded secret key
const result = TOTP.generate(secret);

console.log(result.otp); // e.g.: '341128'
console.log(result.expires); // e.g.: 1465324730000 (timestamp)

Custom Digits

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { digits: 8 });

console.log(result.otp); // e.g.: '43341128' (8 digits)

Custom Time Period

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { period: 60 }); // 60 second period

console.log(result.otp);
console.log(result.expires);

Using Different Hash Algorithm

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { algorithm: 'SHA-512' });

console.log(result.otp);

Generate OTP with Specific Timestamp

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const timestamp = 1465324707000; // Timestamp for 2016-06-08
const result = TOTP.generate(secret, { timestamp });

console.log(result.otp); // OTP generated based on specified timestamp

Combining Multiple Options

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, {
  digits: 8,
  algorithm: 'SHA-256',
  period: 60,
});

console.log(result.otp);
console.log(result.expires);

Notes

  1. Key Format: The key must be a Base32 encoded string. If the key contains invalid characters, it will throw an error 'Invalid base32 character in key'.

  2. Time Synchronization: TOTP relies on time synchronization. Ensure that client and server times are synchronized, otherwise verification may fail.

  3. Expiry Time: expires returns the timestamp when the current time window ends. During verification, a time window tolerance is usually allowed (e.g., ±1 period).

  4. Security: Keys should be stored securely and not hardcoded in code. It is recommended to use environment variables or a secure key management system.