OTP

A small, focused HOTP, TOTP, and otpauth:// library for JavaScript and TypeScript.

pnpm add @gottheflag/otp

import { TOTP } from "@gottheflag/otp";

const secret = new TextEncoder().encode("development-secret");

const otp = new TOTP({
	secret,
	account: "alice@example.com",
	issuer: "Example",
});

try {
	console.log(otp.generate());
} finally {
	otp.destroy();
	secret.fill(0);
}

Secret formats and ownership

The representation and ownership are explicit:

• string in the class API = canonical Base64. It is decoded into bytes owned by the OTP instance because JavaScript strings cannot be securely borrowed or wiped.
• Uint8Array in the class API = raw bytes, borrowed by reference with no persistent copy. The caller owns the buffer and is responsible for wiping it.
• Standard otpauth:// URI secrets = Base32. A valid parsed OTP instance owns the single decoded byte buffer.

destroy() is idempotent. It wipes secret bytes owned by the OTP instance and releases borrowed byte references without modifying caller-owned memory. After destruction, secret-dependent operations such as generate(), serialization, and reading/replacing secret throw.

For authenticator-style input, prefer parsing the full URI:

import { OTP } from "@gottheflag/otp";

const otp = OTP.parse(uri);

if (otp.valid) {
	try {
		console.log(otp.generate());
	} finally {
		otp.destroy();
	}
} else {
	console.log(otp.diagnostics);
}

Documentation

The documentation is a single self-contained static page at docs/index.html. It has no build step, dependencies, external assets, analytics, or runtime network requests, so it can be opened directly from disk or served by GitHub Pages.

Development

pnpm playground
pnpm check

The playground is intentionally small: paste an otpauth:// URI, generate with current time or a fixed Unix timestamp, inspect diagnostics, and use the built-in RFC 6238 sanity result to catch regressions quickly.

Security

OTP secrets are credentials. Do not log real secrets or full secret-bearing otpauth:// URIs.

For sensitive code, prefer Uint8Array so your application controls the secret buffer lifetime explicitly. Wipe caller-owned bytes when you are finished with them, and call destroy() on OTP instances that own decoded secret material.

JavaScript cannot guarantee perfect secure-memory erasure, but the package avoids unnecessary persistent byte copies and wipes buffers it owns when explicitly destroyed.

See SECURITY.md for private vulnerability reporting.

License

Apache-2.0