otp

otp is a Go library implementing both Time-based One-Time Passwords (TOTP, RFC 6238) and HMAC-based One-Time Passwords (HOTP, RFC 4226), the same algorithms used by Google Authenticator, GitHub, and most two-factor authentication apps. It handles key generation, QR code image creation for enrollment, and constant-time passcode validation, so applications can add TOTP/HOTP-based two-factor authentication without hand-rolling the cryptography.

The library exposes simple Generate/Validate/GenerateCode functions for the common Google-Authenticator-compatible case, along with *Custom variants that expose every RFC parameter (period, skew, digit count, hash algorithm, and even a Steam Guard-style encoder) for applications with non-standard requirements.

What You Get

• TOTP generation and validation (RFC 6238) with configurable period, skew, digit count, and hash algorithm
• HOTP generation and validation (RFC 4226) as the counter-based building block TOTP is layered on
• QR code image generation via Key.Image() for scannable enrollment in authenticator apps
• Support for SHA1, SHA256, SHA512, and MD5 HMAC algorithms, plus 6- and 8-digit codes
• A Steam Guard-compatible passcode encoder alongside the standard numeric encoder

Common Use Cases

• Adding two-factor authentication (2FA) login flows to a web or API backend
• Generating enrollment QR codes for users to scan with Google Authenticator, Authy, or similar apps
• Validating time-based passcodes server-side during login or sensitive-action confirmation
• Implementing custom OTP schemes (non-standard periods, digit counts, or algorithms) for internal tooling

Under The Hood

Architecture

The library is organized as flat, single-responsibility packages: the root otp package holds shared types (Key, Algorithm, Digits, Encoder) and the Key URL-parsing/generation logic in otp.go; the hotp subpackage implements the RFC 4226 primitive (GenerateCodeCustom, ValidateCustom) that both TOTP and HOTP callers rely on; the totp subpackage layers time-windowing (period/skew-based counter derivation) on top of hotp.GenerateCodeCustom/ValidateCustom, delegating all HMAC and truncation work downward rather than duplicating it — a clean two-layer composition where TOTP is effectively HOTP with a counter derived from time. A small internal package centralizes URL query encoding so both totp.Generate and hotp.Generate produce identical otpauth:// URI formatting, and a separate interop module (its own go.mod) isolates cross-implementation test vectors from the core library’s dependency graph. There is no runtime state and no dependency injection — all functions are pure given secret/counter/time inputs — so the one thing that would ripple everywhere is a change to Key’s URL-based internal representation, since both totp and hotp construct Key values through otp.NewKeyFromURL.

Tech Stack

go.mod declares the module at Go 1.12 with only two direct dependencies: a barcode-encoding library used for QR code image rendering, and a test-assertion library used only in tests. The cryptographic core relies entirely on the Go standard library — HMAC, SHA1/SHA256/SHA512, MD5, constant-time comparison, secure random generation, base32 encoding, and URL handling for the otpauth:// scheme. There is no web framework, ORM, or database, which fits a pure algorithm library with no runtime dependencies beyond the standard library and one small image-encoding package. CI runs the test suite across multiple architectures. There is no build tooling beyond the Go toolchain and no deployment target, since the project is consumed as an imported package rather than run as a service.

Code Quality

Test coverage exists at every layer — the root package, the totp subpackage, and the hotp subpackage each carry a dedicated test file, plus a separate interop test that cross-checks output against another OTP implementation’s test vectors, all using a test-assertion library for readable comparisons. Error handling is explicit and typed via sentinel errors rather than generic errors or panics, and passcode comparison uses a constant-time comparison specifically to avoid timing side-channel leaks — a security-conscious choice not every comparable library makes. Naming is idiomatic Go with exported doc comments throughout. There is no modern linter configuration present, and CI appears limited to running the test suite rather than static analysis, so quality enforcement here is test-driven rather than lint-driven.

What Makes It Unique

otp does not invent a new protocol — TOTP and HOTP are IETF standards, and the library’s value is a clean, dependency-light, spec-compliant Go implementation rather than a novel algorithmic contribution. Its most distinctive design choice is representing a Key as a parsed otpauth:// URL rather than a bespoke struct, so key generation, parsing, and serialization all round-trip through the exact URI format that Google Authenticator and compatible apps consume, making interop with third-party parsers close to free. It also supports an uncommon Steam Guard-style passcode alphabet alongside the standard numeric encoder, a niche feature most comparable OTP libraries omit entirely.