MFA/2FA One-Time Password (OTP) Library

A simple, lightweight library for generating and verifying one-time passwords supporting TOTP, HOTP, and YubiKey OTP.

Documentation

https://gibme-npm.github.io/mfa/

Installation

npm install @gibme/mfa

or

yarn add @gibme/mfa

Requirements

• Node.js >= 22

Usage

Import everything from the main entry point, or use subpath imports for tree-shaking:

// Full import
import { Secret, TOTP, HOTP, YubiKeyOTP } from '@gibme/mfa';

// Subpath imports
import Secret from '@gibme/mfa/secret';
import TOTP from '@gibme/mfa/totp';
import HOTP from '@gibme/mfa/hotp';
import YubiKeyOTP from '@gibme/mfa/yubikey';

Secret

The seed used with TOTP and HOTP one-time passwords. Generates a cryptographically random 20-byte secret by default.

Generate

import { Secret } from '@gibme/mfa';

const secret = new Secret();

console.log(secret.toString()); // base32-encoded string

Restore from Existing Seed

import { Secret } from '@gibme/mfa';

const secret = new Secret('ZK26SHUWGERAHUOTQMV7V3YMWIX4XUWS');

Custom Size

import { Secret } from '@gibme/mfa';

const secret = new Secret({ size: 32 });

TOTP

Time-based One-Time Password. The OTP is derived from the current time and a configurable period (default: 30 seconds). Compatible with authenticator apps such as Google Authenticator, Authy, and 1Password.

Generate

import { TOTP } from '@gibme/mfa';

const [token, secret] = TOTP.generate();

console.log(token);             // e.g. "482901"
console.log(secret.toString()); // base32 secret for storage

Generate with Existing Secret

import { TOTP, Secret } from '@gibme/mfa';

const secret = new Secret('ZK26SHUWGERAHUOTQMV7V3YMWIX4XUWS');
const [token] = TOTP.generate({ secret });

Verify

import { TOTP } from '@gibme/mfa';

const [success, delta] = TOTP.verify(token, { secret });

if (!success) {
    throw new Error('Invalid OTP code supplied');
}

Generate OTPAuth URI

Generate a URI for provisioning authenticator apps:

import { TOTP } from '@gibme/mfa';

const uri = TOTP.toString({
    secret,
    issuer: 'My App',
    label: 'user@example.com'
});
// otpauth://totp/user%40example.com?secret=...&issuer=My%20App&algorithm=SHA1&digits=6&period=30

Generate QR Code URL

import { TOTP } from '@gibme/mfa';

const qrUrl = TOTP.toQRCodeURL({
    secret,
    issuer: 'My App',
    label: 'user@example.com'
});

Configuration Options

Option	Type	Default	Description
secret	Secret | string	Random	The shared secret
period	number	30	Time step in seconds
digits	6 | 8	6	OTP digit count
algorithm	DigestAlgorithm	SHA1	Hash algorithm (SHA1, SHA256, SHA512)
window	number	1	Verification tolerance window
issuer	string	''	Issuer name for authenticator apps
label	string	'TOTP Authenticator'	Account label for authenticator apps
timestamp	Date | number	Date.now()	Time reference for OTP calculation

HOTP

HMAC-based One-Time Password. OTPs are generated based on a counter value that must be incremented after each use.

Generate

import { HOTP } from '@gibme/mfa';

const [token, secret] = HOTP.generate({ counter: 0 });

Verify

import { HOTP } from '@gibme/mfa';

const [success, delta] = HOTP.verify(token, { secret, counter: 0 });

if (!success) {
    throw new Error('Invalid OTP code supplied');
}

Generate OTPAuth URI

import { HOTP } from '@gibme/mfa';

const uri = HOTP.toString({
    secret,
    issuer: 'My App',
    label: 'user@example.com',
    counter: 0
});

Generate QR Code URL

import { HOTP } from '@gibme/mfa';

const qrUrl = HOTP.toQRCodeURL({
    secret,
    issuer: 'My App',
    label: 'user@example.com'
});

Configuration Options

Option	Type	Default	Description
secret	Secret | string	Random	The shared secret
counter	number	0	HMAC counter value
digits	6 | 8	6	OTP digit count
algorithm	DigestAlgorithm	SHA1	Hash algorithm (SHA1, SHA256, SHA512)
window	number	1	Verification tolerance window
issuer	string	''	Issuer name for authenticator apps
label	string	'HOTP Authenticator'	Account label for authenticator apps

YubiKey OTP

Verify YubiKey one-time passwords against the Yubico validation servers.

To obtain a YubiKey API key, visit the Yubico API key signup page.

Verify

import { YubiKeyOTP } from '@gibme/mfa';

const response = await YubiKeyOTP.verify(otp, {
    clientId: 12345,
    apiKey: 'yourapikey'
});

if (!response.valid) {
    throw new Error('Invalid OTP code supplied');
}

console.log(response.deviceId);       // YubiKey device identifier
console.log(response.signatureValid); // Server signature verification
console.log(response.status);         // Validation status code

Configuration Options

Option	Type	Default	Description
clientId	number | string	Required	Yubico API client ID
apiKey	string	Required	Yubico API key
serviceUrl	string	'https://api.yubico.com/wsapi/2.0/verify'	Validation server URL

Validation Status Codes

Status	Description
OK	OTP is valid
BAD_OTP	OTP is invalid format
REPLAYED_OTP	OTP has already been used
BAD_SIGNATURE	HMAC signature verification failed
MISSING_PARAMETER	Required parameter missing from request
NO_SUCH_CLIENT	Client ID does not exist
OPERATION_NOT_ALLOWED	Client ID not authorized for this operation
BACKEND_ERROR	Unexpected server error
NOT_ENOUGH_ANSWERS	Insufficient validation server responses
REPLAYED_REQUEST	Request with this nonce was already seen

License

MIT