Time2fa

A comprehensive Node.js package that simplifies the implementation of One-Time Password (OTP) authentication using HMAC-based One-Time Password (HOTP) and Time-based One-Time Password (TOTP) algorithms.

Features

• Support both HOTP and TOTP algorithms
• Easy-to-use API for generating and verifying OTPs
• Customizable OTP length, counters and time window
• Supports various hashing algorithms (SHA-1, SHA-256, SHA-512)
• Compatible with popular OTP generators like Google Authenticator and Authy

Installation

Install the package using NPM:

npm i --save time2fa

Usage/Examples

TOTP

Generate key

// Import Totp
import { Totp } from "time2fa";

const key = Totp.generateKey({ issuer: "N0C", user: "johndoe@n0c.com" });

console.log(key);

// GenerateKey {
//   issuer: 'N0C',
//   user: 'johndoe@n0c.com',
//   config: { algo: 'sha1', digits: 6, period: 30, secretSize: 10 },
//   secret: 'ABCDEFGHIJKLMN12',
//   url: 'otpauth://totp/N0C:johndoe%40n0c.com?issuer=N0C&period=30&secret=ABCDEFGHIJKLMN12'
// }

Validate passcode

// Import Totp
import { Totp } from "time2fa";

const valid = Totp.validate({ passcode: "123456", secret: "ABCDEFGHIJKLMN12" });

console.log(valid);

// true || false

Generate passcodes

// Import Totp, and generateConfig for default configuration
import { Totp, generateConfig } from "time2fa";

const config = generateConfig();
const codes = Totp.generatePasscodes({ secret: "ABCDEFGHIJKLMN12" }, config);

console.log(codes);

// [ 123456 ]

QRCode generation

You must use an external library. For the example below we use qrcode.

// Import Totp and qrcode
import { Totp } from "time2fa";
import * as qrcode from "qrcode";

const key = Totp.generateKey({ issuer: "N0C", user: "johndoe@n0c.com" });

console.log(key);

// GenerateKey {
//   issuer: 'N0C',
//   user: 'johndoe@n0c.com',
//   config: { algo: 'sha1', digits: 6, period: 30, secretSize: 10 },
//   secret: 'ABCDEFGHIJKLMN12',
//   url: 'otpauth://totp/N0C:johndoe%40n0c.com?issuer=N0C&period=30&secret=ABCDEFGHIJKLMN12'
// }

qrcode.toDataURL(key.url, (err, url) => {
  console.log(url); // Returns a Data URI containing a representation of the QR Code image.
});

HOTP

Generate Passcode

// Import Hotp, and generateConfig for default configuration and generateSecret
import { Hotp, generateConfig, generateSecret } from "time2fa";

const config = generateConfig();
const secret = generateSecret();

const code = Hotp.generatePasscode({ secret, counter: 1 }, config);

console.log(code);

// 123456

Validate passcode

// Import Hotp
import { Hotp } from "time2fa";

const valid = Hotp.validate({
  passcode: "123456",
  secret: "ABCDEFGHIJKLMN12",
  counter: 1,
});

console.log(valid);

// true || false

Helpers

generateConfig()

Generate default configuration

// Import generateConfig
import { generateConfig } from "time2fa";

const config = generateConfig();

console.log(config);

// { algo: 'sha1', digits: 6, period: 30, secretSize: 10 }

generateSecret()

Only support base32 at the moment

// Import generateSecret
import { generateSecret } from "time2fa";

const secret = generateSecret();

console.log(secret);

// ABCDEFGHIJKLMN12

generateUrl()

// Import generateSecret
import { generateUrl } from "time2fa";

const url = generateUrl({
  issuer: "N0C",
  user: "johndoe@n0c.com",
  secret: "ABCDEFGHIJKLMN12",
});

console.log(url);

// otpauth://totp/N0C:johndoe%40n0c.com?issuer=N0C&period=30&secret=ABCDEFGHIJKLMN12

generateBackupCodes()

Backup code should only be used once

// Import generateBackupCodes
import { generateBackupCodes } from "time2fa";

const backupCodes = generateBackupCodes();

console.log(backupCodes);

// [
//   '810550', '236884',
//   '979342', '815504',
//   '835313', '529942',
//   '263100', '882025',
//   '204896', '516248'
// ]

Documentation

Functions

Helpers

generateConfig(config?: TotpConfig): ValidTotpConfig

generateSecret(secretSize: number = DEFAULT_TOTP_SECRET_SIZE): string

generateBackupCodes(numCodes = 10, codeLength = DEFAULT_TOTP_DIGITS): string[]

generateUrl(options: UrlOptions, config: ValidTotpConfig): string

Totp

Totp.generateKey(options: TotpOptions, config?: TotpConfig): GenerateKey

Totp.generatePasscodes(options: TotpCode, config: ValidTotpConfig): string[]

Totp.validate(options: TotpValidateOptions, config?: TotpConfig): boolean

Hotp

Hotp.generatePasscode(options: HotpCode, config: ValidTotpConfig): string

Hotp.validate(options: HotpValidateOptions, config?: TotpConfig): boolean

Interfaces / Parameters

TotpConfig

| Parameter | Type | default | Description | | :----------- | :----------- | :------ | --------------------------------------------- | | secretSize | number | 10 | Optional - Secret size | | period | number | 30 | Optional - Period of time | | digits | number | 6 | Optional- Code length | | algo | Algorithms | sha1 | Optional - 'sha1' | 'sha256' | 'sha512' |

ValidTotpConfig

| Parameter | Type | default | Description | | :----------- | :----------- | :------ | --------------------------------------------- | | secretSize | number | - | Required - Secret size | | period | number | - | Required - Period of time | | digits | number | - | Required- Code length | | algo | Algorithms | - | Required - 'sha1' | 'sha256' | 'sha512' |

TotpOptions

| Parameter | Type | default | Description | | :-------- | :------- | :------ | -------------------------- | | issuer | string | - | Required - Issuer name | | user | string | - | Required - Username |

UrlOptions

| Parameter | Type | default | Description | | :-------- | :------- | :------ | -------------------------- | | issuer | string | - | Required - Issuer name | | user | string | - | Required - Username | | secret | string | - | Required - Secret |

TotpCode

| Parameter | Type | default | Description | | :-------- | :------- | :------ | ----------------------------- | | secret | string | - | Required - Secret | | drift | number | 0 | Optional - Time tolerance |

TotpValidateOptions

| Parameter | Type | default | Description | | :--------- | :------- | :------ | --------------------------------------- | | passcode | string | - | Required - The passcode to validate | | secret | string | - | Required - Secret | | drift | number | 0 | Optional - Time tolerance |

HotpCode

| Parameter | Type | default | Description | | :-------- | :------- | :------ | ----------------------------------- | | secret | string | - | Required - Secret | | counter | number | - | Required - Custom counter value |

HotpValidateOptions

| Parameter | Type | default | Description | | :--------- | :------- | :------ | --------------------------------------- | | passcode | string | - | Required - The passcode to validate | | secret | string | - | Required - Secret | | counter | number | - | Required - Custom counter value |

Contributing

All PR's are welcome!

Running Tests

To run tests, run the following command

npm run test

License

MIT