🔐 NowaraJS TOTP

Let's be honest: there are already packages like totp-generator that do this. I built this one mostly for myself—to learn how TOTP/HOTP actually works under the hood, and to have a lightweight alternative I fully understand.

Why this package?

No grand mission here. I wanted:

1. To learn how RFC 6238/4226 work in practice
2. A tiny footprint without pulling half of npm
3. Something I control for my own projects

If you're looking for battle-tested libraries, check out the established ones. If you want something small and readable, this might be for you.

📌 Table of Contents

• Features
• Installation
• Usage
• API Reference
• License
• Contact

✨ Features

• 🔐 RFC Compliant: Full RFC 6238 (TOTP) and RFC 4226 (HOTP) implementation.
• 📱 QR Code Ready: Generate OTPAuth URIs compatible with Google Authenticator, Authy, etc.
• 🔒 Crypto Secure: Uses Web Crypto API for truly random secret generation.
• 🛠️ Flexible: SHA-1, SHA-256, SHA-512 algorithms with 6-8 digit codes.
• 📦 Zero Dependencies: Pure TypeScript, tiny footprint.

🔧 Installation

bun add @nowarajs/totp @nowarajs/error

⚙️ Usage

Generate a TOTP Code

Use this when you need to generate a one-time password for the current time window.

import { totp, generateSecretBytes, base32Encode } from '@nowarajs/totp';

// Generate a cryptographically secure secret
const secret = generateSecretBytes(20);

// Generate the current TOTP code
const code = await totp(secret, {
    algorithm: 'SHA-1',
    digits: 6,
    period: 30
});

console.log('Your code:', code); // e.g., "847263"

Verify a User's Code

Use this to validate the code your user just entered. The window option handles clock drift gracefully.

import { verifyTotp } from '@nowarajs/totp';

const isValid = await verifyTotp(secret, userInputCode, {
    algorithm: 'SHA-1',
    digits: 6,
    period: 30,
    window: 1 // Accept codes from ±30 seconds
});

if (isValid) console.log('✅ Access granted');
else console.log('❌ Invalid code');

Generate a QR Code URI

Use this to let users scan a QR code with their authenticator app.

import { buildOtpAuthUri, generateSecretBytes, base32Encode } from '@nowarajs/totp';

const secret = generateSecretBytes(20);
const secretBase32 = base32Encode(secret);

const uri = buildOtpAuthUri({
    secretBase32,
    label: '[email protected]',
    issuer: 'MyApp',
    algorithm: 'SHA-1',
    digits: 6,
    period: 30
});

// Feed this URI to any QR code library
console.log(uri);
// otpauth://totp/[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=MyApp

HOTP (Counter-Based)

Use this when you need counter-based OTPs instead of time-based ones.

import { hotp } from '@nowarajs/totp';

const code = await hotp(secret, 123, {
    algorithm: 'SHA-1',
    digits: 6
});

📚 API Reference

Full docs: nowarajs.github.io/totp

⚖️ License

MIT - Feel free to use it.

📧 Contact

• Mail: [email protected]
• GitHub: NowaraJS