OTP Utility for Google Authenticator

Common errors

• TypeError: OTP is not a constructor

  cause Attempting to import the OTP class using CommonJS `require()` syntax or an incorrect named import with ESM.
  fix Use the correct ESM default import: `import OTP from 'otp';` Ensure your environment supports ESM modules (e.g., Node.js with `"type": "module"` in `package.json` or transpilation).

• UnhandledPromiseRejectionWarning: Promise { <pending> }

  cause Calling `otpInstance.totp()` or `otpInstance.hotp()` without awaiting the returned Promise.
  fix Always `await` the asynchronous OTP generation methods: `const code = await otpInstance.totp();`

• Error: Invalid secret length

  cause The provided secret, after base32 decoding, does not result in a key length of 64 or 128 bits, which are the supported `keySize` values.
  fix Ensure your secret (either a Buffer or Base32-encoded string) corresponds to a decoded length of 8 bytes (64 bits) or 16 bytes (128 bits). Adjust `keySize` option if using a non-default length.

• Error: Failed to parse OTP URL

  cause The string passed to `OTP.parse()` is not a valid `otpauth://` URL format or is malformed.
  fix Verify that the URL string conforms to the `otpauth://` scheme, including type, label, and parameters like `secret` and `issuer`.

Warnings

• breaking Version 1.0.0 introduced a significant TypeScript refactor, Buffer cleanup, and dependency removal. Users upgrading from pre-1.0.0 versions may encounter breaking changes related to import paths, module exports (ESM vs CJS), and how secrets (especially Buffer types) are handled.
  Fix: Review your import statements to ensure they align with ESM patterns (e.g., `import OTP from 'otp';`). Verify secret handling, ensuring it's a Base32 string or Buffer as expected by the new API.
• gotcha The `hotp()` and `totp()` methods return Promises. Forgetting to `await` their results will lead to unhandled promise rejections and incorrect OTP retrieval.
  Fix: Always use `await` when calling `otpInstance.hotp(counter)` or `otpInstance.totp()` within an `async` function, or handle the Promise using `.then()`.
• gotcha OTP secrets (keys) are highly sensitive. Improper storage (e.g., plaintext in code or insecure databases) or transmission (e.g., over unencrypted channels) can compromise the security of your two-factor authentication.
  Fix: Store secrets securely in environment variables, secret management services, or encrypted databases. Transmit them only over secure, encrypted connections (HTTPS/TLS).
• gotcha For HOTP, the counter (`hotp(counter)`) must be managed externally and reliably incremented for each use. If the counter is not correctly synchronized between the client and server, HOTP codes will consistently fail validation.
  Fix: Implement robust server-side storage and atomic incrementation for each user's HOTP counter. Never reset the counter unless absolutely necessary (e.g., re-provisioning).
• gotcha The `keySize` option for OTP generation (default 64) refers to the *bits* of the key after decoding, which means a 64-bit key or 128-bit key. Ensure your provided `secret` (when base32 decoded) matches the expected key length for robust security.
  Fix: Generate secrets that decode to 64-bit (8 bytes) or 128-bit (16 bytes) lengths. Typically, longer keys (e.g., 128-bit / 16 bytes base32 encoded) are recommended for stronger security.

Install

• npm install otp npm
• yarn add otp yarn
• pnpm add otp pnpm

Imports

• OTP
  wrong:

  const OTP = require('otp');

  correct:

  import OTP from 'otp';

  The primary OTP class is a default export. For TypeScript and modern Node.js, use ESM import. CommonJS `require` is generally incorrect for v1.0.0+.
• OTP.parse
  wrong:

  import { parse } from 'otp'; // parse is a static method of the OTP class

  correct:

  import OTP from 'otp';
  const options = OTP.parse('otpauth://...');

  OTP.parse is a static method of the default exported OTP class, not a named export. Ensure you import the OTP class first.
• OTP.reviveJSON
  wrong:

  import { reviveJSON } from 'otp'; // reviveJSON is a static method of the OTP class

  correct:

  import OTP from 'otp';
  const obj = JSON.parse(jsonString, OTP.reviveJSON);

  OTP.reviveJSON is a static method of the OTP class, used as a replacer function for `JSON.parse`. Import the OTP class first.

Quickstart

This quickstart demonstrates how to initialize the OTP class with a secret, generate both Time-Based One-Time Passwords (TOTP) and HMAC-Based One-Time Passwords (HOTP), generate Google Authenticator-compatible URLs, parse existing OTP URLs, and utilize the provided JSON reviver for object serialization.

import OTP from 'otp';

async function demonstrateOtp() {
  // Use a securely generated, base32-encoded secret.
  // For demonstration, a common test secret "JBSWY3DPEHPK3PXP" (Hello!) is used.
  const secret = 'JBSWY3DPEHPK3PXP'; // Replace with a strong, random secret in production

  console.log('Using Secret (Base32):', secret);

  // Initialize OTP with a secret and desired name
  const otpInstance = new OTP({
    name: 'MyOTPApp',
    secret: secret,
    codeLength: 6,
    timeSlice: 30, // Default is 30 seconds
  });

  // --- TOTP Demonstration ---
  console.log('\n--- TOTP ---');
  const currentTotpCode = await otpInstance.totp();
  console.log(`Current TOTP code (valid for ~30s): ${currentTotpCode}`);
  console.log('Google Authenticator URL (TOTP):', otpInstance.totpURL);

  // --- HOTP Demonstration ---
  console.log('\n--- HOTP ---');
  // For HOTP, the counter must be managed and incremented server-side
  const counter = 123;
  const hotpCode = await otpInstance.hotp(counter);
  console.log(`HOTP code for counter ${counter}: ${hotpCode}`);
  console.log('Google Authenticator URL (HOTP):', otpInstance.hotpURL);

  // --- Parsing an OTP URL ---
  console.log('\n--- URL Parsing ---');
  const exampleTotpUrl = otpInstance.totpURL; // Or any `otpauth://` URL
  const parsedOptions = OTP.parse(exampleTotpUrl);
  console.log('Parsed OTP options from URL:', parsedOptions);
  // Example: parsedOptions might contain { type: 'totp', label: 'MyOTPApp', secret: 'JBSWY3DPEHPK3PXP', ... }

  // --- Reviving an OTP object from JSON ---
  console.log('\n--- JSON Reviver ---');
  const stringifiedOtp = JSON.stringify(otpInstance);
  console.log('Stringified OTP object (truncated):', stringifiedOtp.substring(0, 100) + '...');
  const revivedOtp = JSON.parse(stringifiedOtp, OTP.reviveJSON);
  console.log('Revived OTP object secret matches original:', revivedOtp.secret === otpInstance.secret);
}

demonstrateOtp().catch(console.error);