totp-js

Security-hardened TOTP/2FA library for JavaScript and TypeScript

RFC 6238 (TOTP) and RFC 4226 (HOTP) compliant. Zero runtime dependencies. Built-in replay protection. Constant-time verification. Works with Node.js 18+.

Documentation | npm | API Reference

---

Why totp-js?

Most TOTP libraries give you the basics — generate a code, verify it. But production 2FA needs more:

• Replay protection — prevent the same code from being used twice
• Constant-time verification — prevent timing attacks that leak information
• Secure defaults — preset configurations so you don't need to be a cryptography expert
• Zero dependencies — no supply chain risk for your authentication layer

totp-js is the TypeScript counterpart to totp-impl (Java), sharing the same security-first API design.

Install

# npm
npm install @authcraft/totp-js

# yarn
yarn add @authcraft/totp-js

# pnpm
pnpm add @authcraft/totp-js

Quick Start

import { TOTP, generateSecret } from '@authcraft/totp-js';

// Generate a secret for the user
const secret = generateSecret();

// Create a TOTP instance
const totp = TOTP.defaultInstance();

// Generate a code
const code = totp.generate(secret);
console.log(code); // "482915"

// Verify a code
const isValid = totp.verify(secret, code);
console.log(isValid); // true

Replay Protection

Prevent the same OTP from being used twice within its validity window:

import { TOTP, generateSecret, InMemoryReplayGuard } from '@authcraft/totp-js';

const guard = InMemoryReplayGuard.withDefaultRetention();
const totp = TOTP.create({ replayGuard: guard });
const secret = generateSecret();

const code = totp.generate(secret);

// First verification — passes
totp.verify(secret, code, 'user-123'); // true

// Same code, same user — blocked!
totp.verify(secret, code, 'user-123'); // false (replay detected)

// Don't forget to clean up when done
guard.destroy();

QR Code URI

Generate otpauth:// URIs for QR code scanning with Google Authenticator, Authy, etc.:

import { buildOtpauthUri, generateSecret } from '@authcraft/totp-js';

const secret = generateSecret();
const uri = buildOtpauthUri(secret, 'user@example.com', 'MyApp');
// otpauth://totp/MyApp%3Auser%40example.com?secret=...&issuer=MyApp&algorithm=SHA1&digits=6&period=30

Configuration

Preset Configurations

import { TOTP, defaultConfig, sha256Config, highSecurityConfig } from '@authcraft/totp-js';

// Default: SHA1, 6 digits, 30s period, drift ±1
const standard = TOTP.create({ ...defaultConfig() });

// SHA-256: recommended for new deployments
const sha256 = TOTP.create({ ...sha256Config() });

// High security: SHA-512, 8 digits
const highSec = TOTP.create({ ...highSecurityConfig() });

Custom Configuration

import { TOTP, Algorithm } from '@authcraft/totp-js';

const totp = TOTP.create({
  algorithm: Algorithm.SHA256,
  digits: 8,
  period: 60,        // 60-second window
  allowedDrift: 2,   // accept codes ±2 periods
});

Configuration Constraints

Parameter	Min	Max	Default
period	15s	120s	30s
digits	6	8	6
allowedDrift	0	5	1

Detailed Verification

Get more context about verification results:

const result = totp.verifyWithDetails(secret, code);
console.log(result);
// { valid: true, timeOffset: 0, message: 'Valid' }
// { valid: false, timeOffset: 0, message: 'Invalid code' }
// { valid: false, timeOffset: 1, message: 'Code already used' }

Framework Integration

Express.js

import express from 'express';
import { TOTP, generateSecret, InMemoryReplayGuard, buildOtpauthUri } from '@authcraft/totp-js';

const app = express();
app.use(express.json());

const guard = InMemoryReplayGuard.withDefaultRetention();
const totp = TOTP.create({ replayGuard: guard });

// Setup 2FA for a user
app.post('/2fa/setup', (req, res) => {
  const secret = generateSecret();
  const uri = buildOtpauthUri(secret, req.body.email, 'MyApp');
  // Store secret in your database
  res.json({ secret, qrUri: uri });
});

// Verify 2FA code
app.post('/2fa/verify', (req, res) => {
  const { userId, code, secret } = req.body;
  const isValid = totp.verify(secret, code, userId);
  res.json({ valid: isValid });
});

Next.js API Route

// app/api/2fa/verify/route.ts
import { NextResponse } from 'next/server';
import { TOTP, InMemoryReplayGuard } from '@authcraft/totp-js';

const guard = InMemoryReplayGuard.withDefaultRetention();
const totp = TOTP.create({ replayGuard: guard });

export async function POST(request: Request) {
  const { secret, code, userId } = await request.json();
  const isValid = totp.verify(secret, code, userId);
  return NextResponse.json({ valid: isValid });
}

NestJS

import { Injectable } from '@nestjs/common';
import { TOTP, generateSecret, InMemoryReplayGuard, buildOtpauthUri } from '@authcraft/totp-js';

@Injectable()
export class TwoFactorService {
  private readonly totp: TOTP;
  private readonly guard: InMemoryReplayGuard;

  constructor() {
    this.guard = InMemoryReplayGuard.withDefaultRetention();
    this.totp = TOTP.create({ replayGuard: this.guard });
  }

  setup(email: string) {
    const secret = generateSecret();
    const uri = buildOtpauthUri(secret, email, 'MyApp');
    return { secret, qrUri: uri };
  }

  verify(secret: string, code: string, userId: string): boolean {
    return this.totp.verify(secret, code, userId);
  }
}

Fastify

import Fastify from 'fastify';
import { TOTP, generateSecret, InMemoryReplayGuard } from '@authcraft/totp-js';

const app = Fastify();
const guard = InMemoryReplayGuard.withDefaultRetention();
const totp = TOTP.create({ replayGuard: guard });

app.post('/2fa/verify', async (request, reply) => {
  const { secret, code, userId } = request.body as any;
  const isValid = totp.verify(secret, code, userId);
  return { valid: isValid };
});

Secret Generation

import { generateSecret, generateRawSecret, isValidSecret, Algorithm } from '@authcraft/totp-js';

// Default (SHA1, 20 bytes)
const secret = generateSecret();

// Algorithm-appropriate size
const sha256Secret = generateSecret(Algorithm.SHA256); // 32 bytes
const sha512Secret = generateSecret(Algorithm.SHA512); // 64 bytes

// Raw bytes for custom encoding
const rawBytes = generateRawSecret(32);

// Validate existing secrets
isValidSecret(secret); // true
isValidSecret('abc');   // false (too short)

API Reference

TOTP

Method	Description
TOTP.create(options?)	Create with custom options
TOTP.defaultInstance()	Create with defaults (SHA1, 6 digits, 30s)
generate(secret)	Generate code for current time
generateAt(secret, timestamp)	Generate code for specific timestamp (ms)
generateForCounter(secret, counter)	Generate code for specific counter
verify(secret, code, userId?)	Verify code (with optional replay guard)
verifyWithDetails(secret, code, userId?)	Verify with detailed result
getCurrentCounter()	Get current time counter
getSecondsRemaining()	Seconds until next code

Configuration

Preset	Algorithm	Digits	Period	Drift
defaultConfig()	SHA-1	6	30s	±1
sha256Config()	SHA-256	6	30s	±1
highSecurityConfig()	SHA-512	8	30s	±1

Algorithm Support

Algorithm	Key Size	Recommended For
SHA-1	20 bytes	Legacy compatibility (Google Authenticator default)
SHA-256	32 bytes	New deployments (recommended)
SHA-512	64 bytes	Maximum security

Security Features

• Constant-time comparison using crypto.timingSafeEqual() — prevents timing attacks
• Replay protection via InMemoryReplayGuard — prevents code reuse
• Secret validation — enforces minimum 128-bit entropy (16 bytes)
• No sensitive data in errors — error messages never contain secrets or codes
• Zero runtime dependencies — minimized attack surface

Building from Source

git clone https://github.com/Pratiyush/totp-js.git
cd totp-js
npm install
npm run build
npm test

Links

• Documentation — GitHub Pages with interactive demo
• npm — npm install @authcraft/totp-js
• GitHub — Source code, issues, PRs
• totp-impl — Java counterpart (Maven Central)

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — Pratiyush Kumar Singh