totp-turbo

A high-performance TypeScript library for generating Time-based One-Time Passwords (TOTP) using a Rust backend for cryptographic operations.

Features

• 🚀 High Performance: Rust-powered cryptographic operations via WebAssembly
• 🔒 Secure: RFC 6238 compliant TOTP implementation
• 📱 Cross-platform: Works in browsers and Node.js
• 🎯 Type-safe: Full TypeScript support with comprehensive type definitions
• ⚡ Fast: Sub-millisecond token generation
• 🔧 Flexible: Multiple algorithms (SHA1, SHA256, SHA512) and configurations

Installation

npm install totp-turbo

Quick Start

Object-based API (Recommended for repeated use)

import { TotpGenerator } from 'totp-turbo';

// Create a generator with your secret and configuration
const totp = new TotpGenerator({
  secret: 'JBSWY3DPEHPK3PXP',
  digits: 6,
  period: 30,
  algorithm: 'SHA1'
});

// Generate tokens anytime
const token = totp.generate();
console.log(`Current TOTP: ${token}`);

// Verify tokens
const isValid = totp.verify('123456');
console.log(`Token valid: ${isValid}`);

Direct static methods (For one-off generation)

import { Totp } from 'totp-turbo';

// Generate directly from secret
const token = Totp.generate('JBSWY3DPEHPK3PXP');
console.log(`Current TOTP: ${token}`);

// With custom options
const customToken = Totp.generate('JBSWY3DPEHPK3PXP', {
  digits: 8,
  algorithm: 'SHA512',
  period: 60
});

Configuration Options

interface TotpConfig {
  secret: string;                    // Base32 encoded secret
  digits?: number;                   // Token length 4-8 digits (default: 6)
  period?: number;                   // Time step in seconds (default: 30)
  algorithm?: 'SHA1' | 'SHA256' | 'SHA512'; // Hash algorithm (default: SHA1)
  skew?: number;                     // Clock skew tolerance (default: 1)
  explicitZeroPad?: boolean;         // Explicitly pad with zeros (default: true)
  timestamp?: number;                // Custom timestamp in milliseconds (default: current time)
}

API Reference

TotpGenerator Class

class TotpGenerator {
  constructor(config: TotpConfig);
  
  // Instance methods
  generate(): string;
  generateAt(timestamp: number): string;
  verify(token: string): boolean;
  verifyWithSkew(token: string, skew: number): boolean;
  generateUri(issuer: string, accountName: string): string;
  
  // Static utilities
  static generateSecret(): string;
  static parseUri(uri: string): TotpConfig;
}

Totp Static Class

class Totp {
  // Direct generation methods
  static generate(secret: string, options?: Partial<TotpConfig>): string;
  static generateAt(secret: string, timestamp: number, options?: Partial<TotpConfig>): string;
  static verify(secret: string, token: string, options?: Partial<TotpConfig>): boolean;
  static verifyWithSkew(secret: string, token: string, skew: number, options?: Partial<TotpConfig>): boolean;
  
  // Utility methods
  static generateSecret(): string;
  static parseUri(uri: string): TotpConfig;
  static createUri(secret: string, issuer: string, accountName: string, options?: Partial<TotpConfig>): string;
}

Examples

Google Authenticator Compatibility

// Generate a secret
const secret = TotpGenerator.generateSecret();

// Create QR code URI
const uri = totp.generateUri('MyApp', '[email protected]');
console.log(uri); // otpauth://totp/MyApp:[email protected]?secret=...

Different Algorithms and Periods

// SHA-512 with 8 digits
const token = Totp.generate('JBSWY3DPEHPK3PXP', {
  algorithm: 'SHA512',
  digits: 8
});

// 60-second period
const token60s = Totp.generate('JBSWY3DPEHPK3PXP', {
  period: 60
});

// Token for specific timestamp
const historicalToken = Totp.generate('JBSWY3DPEHPK3PXP', {
  timestamp: 1465324707000
});

Performance

• Token generation: < 1ms
• WASM module size: < 50KB gzipped
• Memory usage: < 1MB runtime footprint

Browser Compatibility

• Chrome 67+
• Firefox 61+
• Safari 11+
• Node.js 12+

License

MIT License

Contributing

We welcome contributions! Please see our contributing guidelines for details.