CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-notp

Node One Time Password library, supports HOTP, TOTP and works with Google Authenticator

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

notp

Node One Time Password library that provides fast, zero-dependency implementations of HOTP (counter-based) and TOTP (time-based) one time password algorithms. Fully compliant with RFC 4226 and RFC 6238, and compatible with Google Authenticator and other OTP applications.

Package Information

  • Package Name: notp
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install notp

Core Imports

const notp = require('notp');

For ES modules:

import * as notp from 'notp';

Basic Usage

const notp = require('notp');

// Generate TOTP token (most common use case)
const secret = 'user_secret_key';
const token = notp.totp.gen(secret);
console.log('Current TOTP token:', token);

// Verify TOTP token
const userToken = '123456'; // Token from user's authenticator app
const verification = notp.totp.verify(userToken, secret);
if (verification) {
    console.log('Token valid, delta:', verification.delta);
} else {
    console.log('Token invalid');
}

// Generate HOTP token (counter-based)
const counter = 1;
const hotpToken = notp.hotp.gen(secret, { counter: counter });

// Verify HOTP token  
const hotpVerification = notp.hotp.verify(hotpToken, secret, { counter: counter });

Capabilities

HOTP Generation

Generate counter-based One Time Passwords following RFC 4226.

/**
 * Generate a counter based One Time Password
 * @param {string} key - Secret key for OTP generation (should be unique per user)
 * @param {Object} opt - Options object
 * @param {number} opt.counter - Counter value for HOTP generation (default: 0)
 * @returns {string} - 6-digit OTP token
 */
hotp.gen(key, opt)

Usage Example:

const notp = require('notp');

// Generate HOTP with counter
const secret = 'shared_secret_key';
const options = { counter: 5 };
const token = notp.hotp.gen(secret, options);
console.log('HOTP Token:', token); // e.g., "254676"

HOTP Verification

Verify counter-based One Time Passwords with configurable drift tolerance.

/**
 * Verify a counter based One Time Password
 * @param {string} token - The OTP token to verify
 * @param {string} key - Secret key used for verification  
 * @param {Object} opt - Options object
 * @param {number} opt.window - Allowable margin for counter drift (default: 50)
 * @param {number} opt.counter - Current counter value (default: 0)
 * @returns {Object|null} - Returns {delta: number} on success, null on failure
 */
hotp.verify(token, key, opt)

Usage Example:

const notp = require('notp');

const secret = 'shared_secret_key';
const userToken = '254676';
const options = { 
    counter: 5, 
    window: 10  // Check 10 positions forward/backward
};

const result = notp.hotp.verify(userToken, secret, options);
if (result) {
    console.log('Token valid, counter delta:', result.delta);
    // Update stored counter based on delta
} else {
    console.log('Token invalid');
}

TOTP Generation

Generate time-based One Time Passwords following RFC 6238.

/**
 * Generate a time based One Time Password
 * @param {string} key - Secret key for OTP generation (should be unique per user)
 * @param {Object} opt - Options object
 * @param {number} opt.time - Time step in seconds (default: 30)
 * @param {number} opt._t - Override current time (test environments only)
 * @returns {string} - 6-digit OTP token
 */
totp.gen(key, opt)

Usage Example:

const notp = require('notp');

// Generate TOTP with default 30-second time step
const secret = 'shared_secret_key';
const token = notp.totp.gen(secret);
console.log('Current TOTP token:', token);

// Generate TOTP with custom time step
const customToken = notp.totp.gen(secret, { time: 60 }); // 60-second intervals
console.log('TOTP with 60s intervals:', customToken);

TOTP Verification

Verify time-based One Time Passwords with configurable time drift tolerance.

/**
 * Verify a time based One Time Password
 * @param {string} token - The OTP token to verify
 * @param {string} key - Secret key used for verification
 * @param {Object} opt - Options object
 * @param {number} opt.window - Allowable margin for time drift (default: 6)
 * @param {number} opt.time - Time step in seconds (default: 30)
 * @param {number} opt._t - Override current time (test environments only)
 * @returns {Object|null} - Returns {delta: number} on success, null on failure
 */
totp.verify(token, key, opt)

Usage Example:

const notp = require('notp');

const secret = 'shared_secret_key';
const userToken = '123456'; // From user's authenticator app
const options = { 
    window: 2,  // Check 2 time steps forward/backward
    time: 30    // 30-second time steps
};

const result = notp.totp.verify(userToken, secret, options);
if (result) {
    console.log('Token valid, time delta:', result.delta);
} else {
    console.log('Token invalid or expired');
}

Types

HOTP Module

/**
 * HOTP (counter-based OTP) module
 */
const hotp = {
    gen: function(key, opt),
    verify: function(token, key, opt)
};

TOTP Module

/**
 * TOTP (time-based OTP) module  
 */
const totp = {
    gen: function(key, opt),
    verify: function(token, key, opt)
};

Options Objects

/**
 * HOTP options
 */
interface HOTPOptions {
    counter?: number;  // Counter value (default: 0)
    window?: number;   // Verification window (default: 50)
}

/**
 * TOTP options
 */
interface TOTPOptions {
    time?: number;     // Time step in seconds (default: 30)
    window?: number;   // Verification window (default: 6)
    _t?: number;       // Time override (test only)
}

/**
 * Verification result
 */
interface VerificationResult {
    delta: number;     // Counter/time step difference
}

Google Authenticator Integration

For Google Authenticator compatibility, secret keys must be base32 encoded. The notp library does not provide base32 encoding - use the separate thirty-two package:

const notp = require('notp');
const base32 = require('thirty-two');

// Encode secret for Google Authenticator
const secret = 'user_secret_key';
const encoded = base32.encode(secret);
const googleSecret = encoded.toString().replace(/=/g, ''); // Remove padding

// Generate QR code URI
const uri = `otpauth://totp/MyApp:user@example.com?secret=${googleSecret}&issuer=MyApp`;

// Generate token (same as normal usage)
const token = notp.totp.gen(secret);

Error Handling

The library throws errors in specific cases:

  • Time Override Error: Attempting to use _t option outside test environment (NODE_ENV !== 'test')
  • Invalid Parameters: Functions return null for invalid tokens rather than throwing exceptions
// Error handling example
try {
    const token = notp.totp.gen(secret, { _t: Date.now() }); // Throws in production
} catch (error) {
    console.error('Cannot override time in non-test environment');
}

// Verification returns null on failure
const result = notp.totp.verify('invalid', secret);
if (result === null) {
    console.log('Verification failed');
}

Security Considerations

  • Secret Keys: Keep secret keys secure and unique per user
  • Token Lifetime: TOTP tokens are time-sensitive (default 30 seconds)
  • Window Size: Balance security vs usability when setting verification windows
  • Counter Management: For HOTP, applications must track and increment counters
  • Replay Protection: Implement additional measures to prevent token reuse

Install with Tessl CLI

npx tessl i tessl/npm-notp

docs

index.md

tile.json