OTPAuth

OTPAuth is a zero-dependency-friendly One Time Password library implementing HMAC-based (HOTP, RFC 4226) and time-based (TOTP, RFC 6238) one-time passwords, the algorithms behind most two-factor authentication (2FA) and multi-factor authentication (MFA) flows. It runs across Node.js, Deno, Bun, and browsers via ESM, CommonJS, and UMD builds, and ships slim and bare variants so consumers can swap in their own HMAC implementation or drop the bundled crypto entirely.

The library covers the full lifecycle of an OTP credential: generating cryptographically secure secrets, producing and validating tokens with a configurable search window, computing time-to-expiry, and converting to and from the otpauth:// key URI format used by Google Authenticator and compatible apps (typically encoded as a QR code during enrollment). Its small, dependency-light surface and RFC-compliant defaults make it a common choice for adding 2FA to authentication systems without hand-rolling the underlying HMAC/counter math.

What You Get

• HOTP and TOTP classes with a shared config shape (issuer, label, algorithm, digits, secret) for generating and validating one-time passwords
• A Secret class that generates cryptographically secure random keys and converts between Base32, Hex, Latin-1, and UTF-8 encodings
• Token validation with a configurable search window to tolerate clock drift between client and server, returning a delta rather than a plain boolean
• URI.stringify/URI.parse for converting to and from the otpauth:// key URI format used by Google Authenticator and compatible apps
• Three build variants — full (bundled @noble/hashes crypto), slim (no bundled dependencies), and bare (bring-your-own HMAC function) — published as ESM, CommonJS, and UMD

Common Use Cases

• Adding TOTP-based two-factor authentication (2FA) to a login flow, with QR-code enrollment via the otpauth:// URI format
• Building an authenticator app or browser extension that generates rotating 6-digit codes for multiple accounts
• Implementing server-side HOTP/TOTP verification with a tolerance window to accept slightly out-of-sync client clocks
• Running one shared OTP implementation across a Node.js backend, a Deno/Bun service, and a browser-based client without swapping libraries

Under The Hood

Architecture — The library is organized as four small public classes (HOTP, TOTP, Secret, URI) exported from src/index.js, backed by an internal/ layer that isolates environment-specific and cryptographic concerns: internal/crypto/hmac-digest.js wraps HMAC computation (via the bundled @noble/hashes in the default build, or a caller-supplied function in the bare build), internal/crypto/random-bytes.js and internal/crypto/timing-safe-equal.js handle secure randomness and constant-time comparison, and internal/encoding/*.js provides Base32/Hex/Latin-1/UTF-8/uint codecs used by Secret and the token algorithms. TOTP is implemented as a thin wrapper that derives an HOTP counter from the current time and period, then delegates to HOTP’s generate/validate logic, keeping the RFC 4226 math in one place.

Tech Stack — Plain JavaScript (no TypeScript source; hand-written JSDoc types compiled to .d.ts/.d.cts via tsc), built with Rollup into ESM/CJS/UMD bundles for Node.js, Deno, Bun, and browsers. The only runtime dependency is @noble/hashes for HMAC/SHA implementations, and even that is optional in the slim/bare export variants. Tooling includes ESLint, Prettier, TypeDoc, and Mocha/Chai-based tests run across Node (ESM+CJS), Deno, Bun, and Playwright-driven browser engines (Chromium, Firefox, WebKit).

Code Quality — Test coverage is broad in surface (dedicated suites per runtime: node.test.mjs/.cjs, deno.test.mjs, bun.test.mjs, browser.test.mjs, quickjs.test.mjs, each with minified-build variants) though the actual assertions live in a single shared test/test.mjs. Source files are consistently documented with JSDoc typing every public method and property, class fields use Object.defineProperty to enforce immutability where appropriate (e.g. Secret.bytes), and the linting pipeline (eslint --max-warnings 0, strict tsc --noEmit against the JSDoc types) enforces a zero-warning, type-checked bar on every change.

API Design — The public API is deliberately narrow: constructors take a single options object with sensible RFC-aligned defaults (SHA1, 6 digits, 30s period), generate()/validate() are the only methods most consumers need, and toString()/URI.parse() round-trip cleanly with authenticator-app QR codes. Choosing between the full, slim, and bare builds via subpath exports (otpauth, otpauth/slim, otpauth/bare) is a deliberate, low-boilerplate way to control bundle size and crypto dependencies without changing calling code.