enoch-next-two-factor-auth

enoch-next-two-factor-auth is a TypeScript library for generating and verifying One-Time Passwords (OTP) for two-factor authentication (2FA) in Next.js applications. This package is written in TypeScript for type safety and is designed to help developers seamlessly integrate 2FA functionality with Google Authenticator or similar TOTP-based applications. The library provides functions for generating QR codes, creating secrets, and verifying user-generated OTP tokens, ensuring a secure authentication process.

Table of Contents

• enoch-next-two-factor-auth
  • Table of Contents
  • Features
  • Installation
  • Usage
    • Generating a Secret
    • Generating an OTPAuth URL
    • Verifying OTP Tokens
  • API Reference
    • generateSecret(options: GenerateSecretOptions): GeneratedSecret
    • generateOtpauthUrl(options: GenerateOtpauthUrlOptions): string
    • verifyOTP(token: string, secret: string): boolean
  • Contributing
  • License

Features

• Generates secure, random secrets for use in TOTP-based 2FA.
• Generates QR codes compatible with Google Authenticator.
• Provides functions to verify OTP tokens from users.
• TypeScript support for type safety and developer productivity.
• Designed for easy integration with Next.js applications.

Installation

To install the package, use npm or yarn:

npm install enoch-next-two-factor-auth

or

yarn add enoch-next-two-factor-auth

Usage

Generating a Secret

Use the generateSecret function to create a random secret for a user. The secret can be used to generate a QR code that the user can scan with an authenticator app.

import { generateSecret } from "enoch-next-two-factor-auth";

const secret = generateSecret({
  length: 20,
  name: "MyApp",
  issuer: "MyCompany",
  otpauth_url: true,
});

console.log(secret.base32); // The secret key in Base32 encoding
console.log(secret.otpauth_url); // The otpauth URL for generating QR code

Generating an OTPAuth URL

To generate a QR code, use the generateOtpauthUrl function. This URL can be used with a QR code library to allow users to easily add their account to an authenticator app.

import { generateOtpauthUrl } from "enoch-next-two-factor-auth";

const otpauthUrl = generateOtpauthUrl({
  secret: "JBSWY3DPEHPK3PXP",
  label: "[email protected]",
  issuer: "MyCompany",
});

console.log(otpauthUrl); // The otpauth URL to generate the QR code

Verifying OTP Tokens

To verify an OTP token provided by a user, use the verifyOTP function.

import { verifyOTP } from "enoch-next-two-factor-auth";

const secret = "JBSWY3DPEHPK3PXP";
const token = "123456";

const isValid = verifyOTP(token, secret);

if (isValid) {
  console.log("OTP verified successfully");
} else {
  console.log("OTP verification failed");
}

API Reference

generateSecret(options: GenerateSecretOptions): GeneratedSecret

Generates a random secret that can be used for 2FA.

• options (optional):
  • length (number): Length of the secret in bytes. Default is 20 bytes.
  • name (string): The name of the service or app.
  • issuer (string): The issuer of the TOTP (usually the app name).
  • otpauth_url (boolean): Whether to generate an otpauth URL. Default is true.

Returns: An object containing the generated secret in various formats (ascii, hex, base32, and optionally otpauth_url).

generateOtpauthUrl(options: GenerateOtpauthUrlOptions): string

Generates an otpauth URL that can be used to create a QR code for an authenticator app.

• options:
  • secret (string): The shared secret key in Base32 format.
  • label (string): The account name or email.
  • issuer (string): The service or app name.
  • algorithm (string, optional): Hash algorithm (SHA1, SHA256, SHA512). Default is SHA1.
  • digits (number, optional): The number of digits for the OTP. Default is 6.
  • period (number, optional): The time step in seconds. Default is 30.

Returns: A string representing the otpauth URL.

verifyOTP(token: string, secret: string): boolean

Verifies the provided OTP token against the secret.

• token (string): The OTP token provided by the user.
• secret (string): The shared secret key in Base32 format.

Returns: A boolean indicating whether the OTP token is valid.

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you'd like to contribute to the project. Make sure to follow the code style and add relevant tests for any new features or bug fixes.

License

This project is licensed under the MIT License. See the LICENSE file for more details.