repository·main·Indexed 25 days ago
https://github.com/yeojz/otplibA TypeScript-first library for implementing HOTP (RFC 4226) and TOTP (Authenticator) protocols. It supports multiple runtimes including Node.js, Bun, Deno, and Browsers via a flexible plugin system for crypto and Base32 encoding. The library provides a functional API, a class-based API, and a CLI tool (otplib-cli) for encrypted secret storage and stateless scripting.
The benchmark suite monitors several critical performance areas to ensure the library remains lightweight and fast:
verify() with and without window look-ahead (tolerance).constantTimeEqual, counterToBytes, dynamicTruncate, and truncateDigits.generateTOTP / generateHOTP helpers and roundtrips.All generate() and verify() functions are now async by default. If you require synchronous behavior, you must use the Sync variants (e.g., generateSync).
// v12 (synchronous)
const token = authenticator.generate(secret);
// v13 (async)
const token = await generate({ secret });
// v13 (sync)
const token = generateSync({ secret });Use the @otplib/plugin-crypto-noble plugin in the following scenarios:
@noble/hashes library.crypto.otplib provides the following core capabilities:
@otplib/plugin-crypto-node, @otplib/plugin-crypto-web, or custom implementations).To avoid try/catch blocks when handling potential errors (like SecretTooShortError), use wrapResult for synchronous functions or wrapResultAsync for asynchronous functions. These return an OTPResult object where you can check the ok property.
// Synchronous Example
import { wrapResult, generateSync, OTPError } from "otplib";
const safeGenerate = wrapResult(generateSync);
const result = safeGenerate({ secret: "too-short" });
if (result.ok) {
console.log("Token:", result.value);
} else {
console.error("Failed:", result.error.message);
}
// Asynchronous Example
import { wrapResultAsync, verify } from "otplib";
const safeVerify = wrapResultAsync(verify);
const result = await safeVerify({
token: "123456",
secret: "GEZDGNBVGY3TQOJQGEZDGNBVGY",
});
if (result.ok) {
if (result.value.valid) {
console.log("Valid!");
}
} else {
console.error("Verification failed:", result.error);
}The fuzz testing suite in otplib validates several critical properties to ensure library reliability and security:
decode(encode(x)) always returns x.TokenFormatError instead of internal errors like TypeError or RangeError.By default, otplib treats string secrets as Base32 encoded (per RFC 4648) because that is what authenticator apps and OTPAuth URIs expect.
This plugin allows you to bypass the Base32 requirement by providing a plugin that converts raw strings (like passphrases, hex, or base64) directly into bytes.
Important Notes:
Base32DecodeError or Base32EncodeError. The actual cause of the error is available in the error's cause property.otplib is a stateless library and does not track which tokens have already been verified. You must implement protection in your application logic:
While the adapter provides a synchronous-looking API, there are important constraints to be aware of:
authenticator, totp, and hotp singleton instances and their classes. It does not export specific utility functions that were previously imported directly from otplib/core or other internal paths in v12.crypto module to work seamlessly.It is important to distinguish between Hooks and Plugins in otplib:
| Aspect | Plugins | Hooks |
| :--- | :--- |
| Purpose | Swap infrastructure (crypto backend, Base32 lib) | Customise OTP behaviour (token format) |
| Scope | Affects HMAC computation or secret encoding | Affects token encoding and validation only |
| Examples | plugin-crypto-node, plugin-base32-scure | Steam Guard encoding, custom alphabets |
| Required | Yes (crypto plugin is mandatory) | No (defaults to RFC 4226 numeric encoding) |
The @otplib/uri package works with the standard otpauth:// URI format used for provisioning OTP accounts (often via QR codes).
Format:
otpauth://TYPE/LABEL?PARAMETERS
totp or hotpissuer:account or just accountsecret, issuer, algorithm, digits, period/counterExample:
otpauth://totp/GitHub:user@example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY&issuer=GitHub