Database-less OTP Verification

Common errors

• Error: Invalid key length

  cause The HMAC `key` argument passed to `createNewOTP` or `verifyOTP` is empty, null, or undefined, leading to an invalid key for the underlying `crypto.createHmac` function.
  fix Ensure a non-empty string or Buffer is provided for the `key` argument. It is highly recommended to use a strong, secret key via environment variables.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` syntax in an ES module (`.mjs` file or `type: "module"` in `package.json`) environment.
  fix Switch to ESM `import` statements (e.g., `import { createNewOTP } from 'otp-without-db';`) or ensure your file is treated as CommonJS (e.g., `.cjs` extension or `type: "commonjs"` in `package.json`).

Warnings

• gotcha This library explicitly relies on modern JavaScript features (Template literals, Default arguments, modern object literal). Using it with older Node.js versions might lead to syntax errors or unexpected behavior.
  Fix: Ensure your Node.js environment is up-to-date (Node.js 12+ is generally safe for these features).
• breaking The security of your OTP verification system critically depends on the secrecy and uniqueness of the `key` argument. If this key is compromised or is not unique per application/environment, your system is vulnerable.
  Fix: Always use a strong, randomly generated secret key stored securely (e.g., environment variables) and ensure it's not exposed publicly. Do not hardcode it in production code.
• gotcha The `expiresAfter` parameter in `createNewOTP` defines the OTP's validity period in minutes. Setting this too long can reduce security, while setting it too short can frustrate users.
  Fix: Carefully choose an appropriate expiration time based on your security requirements and user experience considerations, typically between 2 to 10 minutes.
• gotcha This library only handles the cryptographic verification of OTPs. You are responsible for generating the OTP itself (e.g., using `otp-generator`) and sending it to the user via SMS, email, or other channels.
  Fix: Integrate with an OTP generation library and an external messaging service (SMS provider, email API) to complete the OTP workflow.

Install

• npm install otp-without-db npm
• yarn add otp-without-db yarn
• pnpm add otp-without-db pnpm

Imports

• createNewOTP
  wrong:

  const createNewOTP = require('otp-without-db').createNewOTP;

  correct:

  import { createNewOTP } from 'otp-without-db';

  Used to generate the secure hash for an OTP. While CommonJS `require` works, ESM `import` is preferred in modern Node.js environments that support modern JavaScript features this library uses.
• verifyOTP
  wrong:

  const verifyOTP = require('otp-without-db').verifyOTP;

  correct:

  import { verifyOTP } from 'otp-without-db';

  Used to verify a user-provided OTP against a previously generated hash. Both ESM and CJS are supported, but ESM is generally recommended.
• otpTool
  wrong:

  const otpTool = require('otp-without-db');

  correct:

  import * as otpTool from 'otp-without-db';

  Wildcard import for accessing all exported functions. The library uses modern JavaScript features, making ESM imports the idiomatic choice in compatible environments.

Quickstart

Demonstrates the full workflow of generating an OTP hash, simulating user input, and verifying the OTP without a database, using `otp-generator` and `otp-without-db`.

import { createNewOTP, verifyOTP } from 'otp-without-db';
import otpGenerator from 'otp-generator';

// Ensure you have otp-generator installed: npm install otp-generator

const SECRET_KEY = process.env.OTP_SECRET_KEY ?? 'your-very-secret-key-that-you-must-change-in-production-!!!!';
const userIdentifier = "+15551234567"; // Can be phone number or email
const expiresInMinutes = 5;

// 1. Generate OTP (using an external library like otp-generator)
const otp = otpGenerator.generate(6, { upperCaseAlphabets: false, specialChars: false, lowerCaseAlphabets: false });
console.log(`Generated OTP: ${otp}`);

// 2. Create a secure hash to send to the user (and keep track of on your server, if needed for context)
// This hash implicitly contains the identifier, OTP, and expiration time.
const hash = createNewOTP(userIdentifier, otp, SECRET_KEY, expiresInMinutes);
console.log(`Generated Hash: ${hash}`);

// In a real application, you would now send 'otp' to the user via SMS/email and 'hash' back to the client.
// For demonstration, we simulate the user receiving and sending back the details.

// --- User verification step (e.g., in an API endpoint) ---
const userProvidedOTP = otp; // User enters this, received via SMS/email
const userProvidedHash = hash; // Client sends this back, received in step 2
const userProvidedIdentifier = userIdentifier; // Client sends this back

// 3. Verify the OTP hash
const isVerified = verifyOTP(userProvidedIdentifier, userProvidedOTP, userProvidedHash, SECRET_KEY);

if (isVerified) {
  console.log("OTP Verified Successfully!");
} else {
  console.log("OTP Verification Failed or Expired.");
}