modern-totp/README.md

Modern TypeScript TOTP generator and verifier (RFC 6238)

# Modern TOTP Generator & Validator

A simple utility to generate **One-Time Passwords (OTPs)** and **OTP Auth URLs** for applications like Google Authenticator, Authy, and Microsoft Authenticator.
Supports **TOTP** (Time-based OTP) with configurable parameters and **QR code generation**.


## 📦 Installation

```bash
npm install modern-totp
```

## 🚀 Usage

### 1. ES Module (import)

```javascript
import { generateOtp, generateOtpAuthUrl } from 'modern-totp';
import QRCode from 'qrcode';

// Generate an OTP
const otp = generateOtp('JBSWY3DPEHPK3PXP'); // secret
console.log('Generated OTP:', otp);

// Generate OTP Auth URL
const otpAuthUrl = generateOtpAuthUrl(
  'JBSWY3DPEHPK3PXP', // secret
  'user@example.com', // account
  'MyApp'             // issuer
);
console.log('OTP Auth URL:', otpAuthUrl);

// Generate QR Code
QRCode.toDataURL(otpAuthUrl, (err, imageUrl) => {
  if (err) throw err;
  console.log('QR Code Data URL:', imageUrl);
});
```

### 2. CommonJS (require)

```javascript
const { generateOtp, generateOtpAuthUrl } = require('modern-totp');
const QRCode = require('qrcode');

// Generate an OTP
const otp = generateOtp('JBSWY3DPEHPK3PXP'); // secret
console.log('Generated OTP:', otp);

// Generate OTP Auth URL
const otpAuthUrl = generateOtpAuthUrl(
  'JBSWY3DPEHPK3PXP', // secret
  'user@example.com', // account
  'MyApp'             // issuer
);
console.log('OTP Auth URL:', otpAuthUrl);

// Generate QR Code
QRCode.toDataURL(otpAuthUrl, (err, imageUrl) => {
  if (err) throw err;
  console.log('QR Code Data URL:', imageUrl);
});
```

## 📖 API Reference

### `generateOtp(secret: string, digits?: number, period?: number, algorithm?: string): string`

Generates a **time-based OTP**.

* **`secret`**: Base32 encoded secret key.
* **`digits`**: OTP length (default: `6`).
* **`period`**: Validity in seconds (default: `30`).
* **`algorithm`**: Hash algorithm (`SHA1`, `SHA256`, `SHA512`).

### `generateOtpAuthUrl(secret: string, account: string, issuer: string, algorithm?: string, digits?: number, period?: number): string`

Generates an **otpauth://** URL for TOTP apps.

* **`secret`**: Base32 encoded secret.
* **`account`**: User account identifier (email, username, etc.).
* **`issuer`**: App or service name.
* **`algorithm`**: `SHA1`, `SHA256`, or `SHA512` (default: `SHA1`).
* **`digits`**: OTP length (default: `6`).
* **`period`**: Validity in seconds (default: `30`).

## 🔹 Example Output

```
Generated OTP: 482193
OTP Auth URL: otpauth://totp/MyApp:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp&algorithm=SHA1&digits=6&period=30
QR Code Data URL: data:image/png;base64,iVBORw0...
```

## 📌 Notes

* The **OTP Auth URL** can be scanned in Google Authenticator, Authy, or any TOTP-compatible app.
* Use the `qrcode` package to generate QR codes for easier setup.
* Keep your secret key safe — anyone with it can generate valid OTPs.