Configuration and Options

/**
 * Get or set instance options
 */
options: Partial<OptionsType>;

/**
 * Reset options to library defaults
 */
resetOptions(): void;

/**
 * Get complete options with defaults applied
 * @returns Readonly options object with all defaults filled
 */
allOptions(): Readonly<OptionsType>;

import { authenticator, totp, hotp } from "otplib";

// View current options
console.log(authenticator.options);

// Set specific options
authenticator.options = { digits: 8 };
totp.options = { step: 60, window: 2 };
hotp.options = { algorithm: 'sha256' };

// Get complete configuration
const fullConfig = authenticator.allOptions();
console.log(fullConfig); // All options with defaults

// Reset to defaults
authenticator.resetOptions();

interface HOTPOptions {
  /** HMAC algorithm: 'sha1', 'sha256', or 'sha512' */
  algorithm: 'sha1' | 'sha256' | 'sha512';
  /** Number of digits in generated tokens (typically 6 or 8) */
  digits: number;
  /** Encoding of the secret key */
  encoding: 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8';
  /** Function to create HMAC digest */
  createDigest: CreateDigest;
  /** Function to format secret into HMAC key */
  createHmacKey: CreateHmacKey;
  /** Pre-computed digest for advanced use cases */
  digest?: string;
}

// Default HOTP options
const defaultHOTPOptions = {
  algorithm: 'sha1',
  digits: 6,
  encoding: 'ascii'
};

import { hotp } from "otplib";

// Standard configuration
hotp.options = {
  algorithm: 'sha1',
  digits: 6,
  encoding: 'ascii'
};

// High security configuration
hotp.options = {
  algorithm: 'sha256',
  digits: 8,
  encoding: 'hex'
};

// Custom digest (advanced)
hotp.options = {
  digest: 'precomputed-hex-digest'
};

interface TOTPOptions extends HOTPOptions {
  /** Starting time in milliseconds since JavaScript epoch */
  epoch: number;
  /** Time step in seconds */
  step: number;
  /** Time window tolerance: number or [past, future] */
  window: number | [number, number];
}

// Default TOTP options
const defaultTOTPOptions = {
  ...defaultHOTPOptions,
  epoch: Date.now(),
  step: 30,
  window: 0
};

import { totp } from "otplib";

// Standard Google Authenticator compatible
totp.options = {
  algorithm: 'sha1',
  digits: 6,
  step: 30,
  window: 1,
  encoding: 'ascii'
};

// Custom time configuration
totp.options = {
  step: 60,        // 1-minute tokens
  window: [2, 1],  // 2 past, 1 future window
  epoch: Date.now() // Current time base
};

// High frequency tokens
totp.options = {
  step: 15,        // 15-second tokens
  window: 0        // No tolerance
};

interface AuthenticatorOptions extends TOTPOptions {
  /** Function to encode secrets to Base32 */
  keyEncoder: KeyEncoder;
  /** Function to decode Base32 secrets */
  keyDecoder: KeyDecoder;
  /** Function to generate random bytes */
  createRandomBytes: CreateRandomBytes;
}

// Default Authenticator options
const defaultAuthenticatorOptions = {
  ...defaultTOTPOptions,
  encoding: 'hex' // Different from TOTP default
};

import { authenticator } from "otplib";

// Standard Google Authenticator
authenticator.options = {
  algorithm: 'sha1',
  digits: 6,
  step: 30,
  window: 1,
  encoding: 'hex'
};

// Custom authenticator setup
authenticator.options = {
  digits: 8,       // 8-digit tokens
  step: 60,        // 1-minute validity
  algorithm: 'sha256'
};

// Window configuration options
type WindowOption = number | [number, number];

// Symmetric window (same past and future tolerance)
const symmetricWindow: WindowOption = 1; // ±1 time step

// Asymmetric window (different past and future tolerance)
const asymmetricWindow: WindowOption = [2, 1]; // 2 past, 1 future

// No tolerance
const noWindow: WindowOption = 0;

import { totp, authenticator } from "otplib";

// Allow 1 time step in either direction (±30 seconds by default)
totp.options = { window: 1 };

// Allow more past tolerance than future (common for login systems)
totp.options = { window: [3, 1] }; // 90 seconds past, 30 seconds future

// Strict validation (no time tolerance)
authenticator.options = { window: 0 };

// High tolerance for unreliable networks
totp.options = { window: [5, 2] }; // 150 seconds past, 60 seconds future

type HashAlgorithm = 'sha1' | 'sha256' | 'sha512';

// Algorithm characteristics:
// - sha1: Fastest, most compatible, adequate security
// - sha256: Balanced security and performance
// - sha512: Highest security, slower

import { hotp, totp, authenticator } from "otplib";

// Standard compatibility (Google Authenticator)
authenticator.options = { algorithm: 'sha1' };

// Enhanced security
totp.options = { algorithm: 'sha256' };

// Maximum security
hotp.options = { algorithm: 'sha512' };

type KeyEncoding = 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8';

// Encoding use cases:
// - ascii: Plain text secrets
// - hex: Hexadecimal encoded secrets
// - base64: Base64 encoded secrets
// - utf8: Unicode text secrets
// - latin1: Binary data as Latin-1

import { totp } from "otplib";

// Plain text secrets
totp.options = { encoding: 'ascii' };
const token1 = totp.generate("my-secret-key");

// Hex-encoded secrets
totp.options = { encoding: 'hex' };
const token2 = totp.generate("6d792d7365637265742d6b6579");

// Base64-encoded secrets
totp.options = { encoding: 'base64' };
const token3 = totp.generate("bXktc2VjcmV0LWtleQ==");

/**
 * Create new instance with custom default options
 * @param defaultOptions - Options to use as defaults
 * @returns New instance with custom defaults
 */
create(defaultOptions?: Partial<OptionsType>): InstanceType;

import { totp, hotp, authenticator } from "otplib";

// Create high-security TOTP instance
const secureTOTP = totp.create({
  algorithm: 'sha256',
  digits: 8,
  step: 15,
  window: 0
});

// Create legacy HOTP instance
const legacyHOTP = hotp.create({
  algorithm: 'sha1',
  digits: 6,
  encoding: 'ascii'
});

// Create custom authenticator
const customAuth = authenticator.create({
  digits: 8,
  step: 60
});

// Original instances unchanged
console.log(totp.allOptions().digits); // Still 6
console.log(secureTOTP.allOptions().digits); // 8

import { authenticator } from "otplib";

authenticator.options = {
  algorithm: 'sha1',
  digits: 6,
  step: 30,
  window: 1,
  encoding: 'hex'
};

import { totp } from "otplib";

totp.options = {
  algorithm: 'sha256',
  digits: 8,
  step: 15,      // Shorter validity
  window: 0,     // No time tolerance
  encoding: 'hex'
};

import { authenticator } from "otplib";

authenticator.options = {
  window: [5, 2],  // Large time tolerance
  step: 30
};

import { totp } from "otplib";

totp.options = {
  algorithm: 'sha512',
  digits: 8,
  step: 60,       // 1-minute tokens
  window: [1, 0], // Only allow past tokens
  encoding: 'base64'
};

interface CreateDigest {
  (algorithm: string, key: string, data: string): string;
}

interface CreateHmacKey {
  (algorithm: string, secret: string, encoding: string): string;
}

interface CreateRandomBytes {
  (size: number, encoding: string): string;
}

interface KeyEncoder {
  (secret: string, encoding: string): string;
}

interface KeyDecoder {
  (secret: string, encoding: string): string;
}

enum HashAlgorithms {
  SHA1 = 'sha1',
  SHA256 = 'sha256',
  SHA512 = 'sha512'
}

enum KeyEncodings {
  ASCII = 'ascii',
  BASE64 = 'base64',
  HEX = 'hex',
  LATIN1 = 'latin1',
  UTF8 = 'utf8'
}