@suaveplan/otp - RFC 4226 (HOTP) + RFC 6238 (TOTP) + RFC 6287 (OCRA) + Google Authenticator Key URI Format + Base32 (RFC 4648 §6) + recovery codes + clock-drift detector — zero browser/Node deps

Summary

RFC 4226 (HOTP) + RFC 6238 (TOTP) + RFC 6287 (OCRA) + Google Authenticator Key URI Format + Base32 (RFC 4648 §6) + recovery codes + clock-drift detector — zero browser/Node deps.

Documentation tree

base32 — (no submodules)
- base32 — (no submodules)
drift — (no submodules)
- detect — (no submodules)
codes — Stable, registered error codes for @suaveplan/otp plus the typed OtpError base class. Every failure that crosses th…
zod-map — Translate Zod boundary failures into the most-specific OtpErrorCode. When a caller passes options that fail strict-mo…
hotp — (no submodules) - hotp.schema — Zod boundary schema for HotpOptions…
- encode-counter — Encode an HOTP counter as the 8-byte big-endian block required by RFC 4226 §5.1. bigint is the canonical input type b…
- hmac — Algorithm-routing HMAC façade for the OTP family. SHA-256 and SHA-512 route through @suaveplan/crypto-hash (the canon…
- hotp — (no submodules) - hotp.schema — Zod boundary schema for HotpOptions…
- hotp.schema — Zod boundary schema for HotpOptions. Strict-mode parsing rejects unknown keys (so silent typos in caller configuratio…
observability — (no submodules)
- metrics — (no submodules)
ocra — (no submodules) - ocra.schema — Zod boundary schema for OcraParams……
- encode-challenge — Encode the OCRA challenge into the 128-byte block required by RFC 6287 §5.1. Three challenge formats are supported: `QN…
- mutual-auth — RFC 6287 §7.1 mutual authentication helpers. Both sides compute OCRA over the concatenation of the client and server ch…
- ocra — (no submodules) - ocra.schema — Zod boundary schema for OcraParams……
- ocra.schema — Zod boundary schema for OcraParams — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- suite — Parse an OCRA suite string into a typed OcraSuite AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- verify-ocra — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
generate — Generate Crockford-base32 recovery codes — the printable single-use fallback the user prints / writes down when first e…
hash — Hash recovery codes with Argon2id for at-rest storage. Recovery codes are long-lived shared secrets — they must NOT be…
verify — Verify a user-supplied recovery code against a list of stored hashes. Constant-time over the full set — every entry is…
totp — (no submodules) - totp.schema — Zod boundary schemas for `TotpOptions…
- totp — (no submodules) - totp.schema — Zod boundary schemas for `TotpOptions…
- totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
- verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
format-uri — Build a canonical otpauth:// URI from an OtpUri value object. Round-trips with parseUri for every valid input. Pe…
parse-uri — Parse the otpauth:// Key URI Format used by Google Authenticator and every compatible authenticator app. Supports bot…
uri.schema — Zod boundary schemas for the OtpUri discriminated union. OtpTotpUriSchema and OtpHotpUriSchema cover the per-vari…

- [base32](./src/base32/base32.md) — _(no submodules)_- [drift](./src/drift/detect.md) — _(no submodules)_- [detect](./src/drift/detect.md) — _(no submodules)_- [codes](./src/errors/codes.md) — Stable, registered error codes for `@suaveplan/otp` plus the typed `OtpError` base class. Every failure that crosses th…

zod-map — Translate Zod boundary failures into the most-specific OtpErrorCode. When a caller passes options that fail strict-mo…
hotp — (no submodules)- hotp.schema — Zod boundary schema for HotpOptions…
- encode-counter — Encode an HOTP counter as the 8-byte big-endian block required by RFC 4226 §5.1. bigint is the canonical input type b…
- hmac — Algorithm-routing HMAC façade for the OTP family. SHA-256 and SHA-512 route through @suaveplan/crypto-hash (the canon…
- hotp — (no submodules)- hotp.schema — Zod boundary schema for HotpOptions…
- hotp.schema — Zod boundary schema for HotpOptions. Strict-mode parsing rejects unknown keys (so silent typos in caller configuratio…
observability — (no submodules)- metrics — (no submodules)- ocra — (no submodules)- ocra.schema — Zod boundary schema for OcraParams……
- encode-challenge — Encode the OCRA challenge into the 128-byte block required by RFC 6287 §5.1. Three challenge formats are supported: `QN…
- mutual-auth — RFC 6287 §7.1 mutual authentication helpers. Both sides compute OCRA over the concatenation of the client and server ch…
- ocra — (no submodules)- ocra.schema — Zod boundary schema for OcraParams……
- ocra.schema — Zod boundary schema for OcraParams — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- suite — Parse an OCRA suite string into a typed OcraSuite AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- verify-ocra — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
generate — Generate Crockford-base32 recovery codes — the printable single-use fallback the user prints / writes down when first e…
hash — Hash recovery codes with Argon2id for at-rest storage. Recovery codes are long-lived shared secrets — they must NOT be…
verify — Verify a user-supplied recovery code against a list of stored hashes. Constant-time over the full set — every entry is…
totp — (no submodules)- totp.schema — Zod boundary schemas for `TotpOptions…
- totp — (no submodules)- totp.schema — Zod boundary schemas for `TotpOptions…
- totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
- verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
format-uri — Build a canonical otpauth:// URI from an OtpUri value object. Round-trips with parseUri for every valid input. Pe…
parse-uri — Parse the otpauth:// Key URI Format used by Google Authenticator and every compatible authenticator app. Supports bot…
uri.schema — Zod boundary schemas for the OtpUri discriminated union. OtpTotpUriSchema and OtpHotpUriSchema cover the per-vari…
base32 — (no submodules)- drift — (no submodules)- detect — (no submodules)- codes — Stable, registered error codes for @suaveplan/otp plus the typed OtpError base class. Every failure that crosses th…
zod-map — Translate Zod boundary failures into the most-specific OtpErrorCode. When a caller passes options that fail strict-mo…
hotp — (no submodules)- hotp.schema — Zod boundary schema for HotpOptions…
- encode-counter — Encode an HOTP counter as the 8-byte big-endian block required by RFC 4226 §5.1. bigint is the canonical input type b…
- hmac — Algorithm-routing HMAC façade for the OTP family. SHA-256 and SHA-512 route through @suaveplan/crypto-hash (the canon…
- hotp — (no submodules)- hotp.schema — Zod boundary schema for HotpOptions…
- hotp.schema — Zod boundary schema for HotpOptions. Strict-mode parsing rejects unknown keys (so silent typos in caller configuratio…
observability — (no submodules)- metrics — (no submodules)- ocra — (no submodules)- ocra.schema — Zod boundary schema for OcraParams……
- encode-challenge — Encode the OCRA challenge into the 128-byte block required by RFC 6287 §5.1. Three challenge formats are supported: `QN…
- mutual-auth — RFC 6287 §7.1 mutual authentication helpers. Both sides compute OCRA over the concatenation of the client and server ch…
- ocra — (no submodules)- ocra.schema — Zod boundary schema for OcraParams……
- ocra.schema — Zod boundary schema for OcraParams — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- suite — Parse an OCRA suite string into a typed OcraSuite AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- verify-ocra — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
generate — Generate Crockford-base32 recovery codes — the printable single-use fallback the user prints / writes down when first e…
hash — Hash recovery codes with Argon2id for at-rest storage. Recovery codes are long-lived shared secrets — they must NOT be…
verify — Verify a user-supplied recovery code against a list of stored hashes. Constant-time over the full set — every entry is…
totp — (no submodules)- totp.schema — Zod boundary schemas for `TotpOptions…
- totp — (no submodules)- totp.schema — Zod boundary schemas for `TotpOptions…
- totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
- verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
format-uri — Build a canonical otpauth:// URI from an OtpUri value object. Round-trips with parseUri for every valid input. Pe…
parse-uri — Parse the otpauth:// Key URI Format used by Google Authenticator and every compatible authenticator app. Supports bot…
uri.schema — Zod boundary schemas for the OtpUri discriminated union. OtpTotpUriSchema and OtpHotpUriSchema cover the per-vari…
base32 — (no submodules)- drift — (no submodules)- detect — (no submodules)- codes — Stable, registered error codes for @suaveplan/otp plus the typed OtpError base class. Every failure that crosses th…
zod-map — Translate Zod boundary failures into the most-specific OtpErrorCode. When a caller passes options that fail strict-mo…
hotp — (no submodules)- hotp.schema — Zod boundary schema for HotpOptions…
- encode-counter — Encode an HOTP counter as the 8-byte big-endian block required by RFC 4226 §5.1. bigint is the canonical input type b…
- hmac — Algorithm-routing HMAC façade for the OTP family. SHA-256 and SHA-512 route through @suaveplan/crypto-hash (the canon…
- hotp — (no submodules)- hotp.schema — Zod boundary schema for HotpOptions…
- hotp.schema — Zod boundary schema for HotpOptions. Strict-mode parsing rejects unknown keys (so silent typos in caller configuratio…
observability — (no submodules)- metrics — (no submodules)- ocra — (no submodules)- ocra.schema — Zod boundary schema for OcraParams…
- encode-challenge — Encode the OCRA challenge into the 128-byte block required by RFC 6287 §5.1. Three challenge formats are supported: `QN…
- mutual-auth — RFC 6287 §7.1 mutual authentication helpers. Both sides compute OCRA over the concatenation of the client and server ch…
- ocra — (no submodules)- ocra.schema — Zod boundary schema for OcraParams…
- ocra.schema — Zod boundary schema for OcraParams — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- suite — Parse an OCRA suite string into a typed OcraSuite AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- verify-ocra — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
generate — Generate Crockford-base32 recovery codes — the printable single-use fallback the user prints / writes down when first e…
hash — Hash recovery codes with Argon2id for at-rest storage. Recovery codes are long-lived shared secrets — they must NOT be…
verify — Verify a user-supplied recovery code against a list of stored hashes. Constant-time over the full set — every entry is…
totp — (no submodules)- totp.schema — Zod boundary schemas for `TotpOptions…
- totp — (no submodules)- totp.schema — Zod boundary schemas for `TotpOptions…
- totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
- verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
format-uri — Build a canonical otpauth:// URI from an OtpUri value object. Round-trips with parseUri for every valid input. Pe…
parse-uri — Parse the otpauth:// Key URI Format used by Google Authenticator and every compatible authenticator app. Supports bot…
uri.schema — Zod boundary schemas for the OtpUri discriminated union. OtpTotpUriSchema and OtpHotpUriSchema cover the per-vari…
base32 — (no submodules)- drift — (no submodules) - detect — (no submodules)- codes — Stable, registered error codes for @suaveplan/otp plus the typed OtpError base class. Every failure that crosses th…
zod-map — Translate Zod boundary failures into the most-specific OtpErrorCode. When a caller passes options that fail strict-mo…
hotp — (no submodules) - encode-counter — Encode an HOTP counter as the 8-byte big-endian block required by RFC 4226 §5.1. bigint is the canonical input type b…
- hmac — Algorithm-routing HMAC façade for the OTP family. SHA-256 and SHA-512 route through @suaveplan/crypto-hash (the canon…
- hotp — (no submodules) - hotp.schema — Zod boundary schema for HotpOptions. Strict-mode parsing rejects unknown keys (so silent typos in caller configuratio…
observability — (no submodules) - metrics — (no submodules)- ocra — (no submodules) - encode-challenge — Encode the OCRA challenge into the 128-byte block required by RFC 6287 §5.1. Three challenge formats are supported: `QN…
- mutual-auth — RFC 6287 §7.1 mutual authentication helpers. Both sides compute OCRA over the concatenation of the client and server ch…
- ocra — (no submodules) - ocra.schema — Zod boundary schema for OcraParams — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- suite — Parse an OCRA suite string into a typed OcraSuite AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- verify-ocra — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
generate — Generate Crockford-base32 recovery codes — the printable single-use fallback the user prints / writes down when first e…
hash — Hash recovery codes with Argon2id for at-rest storage. Recovery codes are long-lived shared secrets — they must NOT be…
verify — Verify a user-supplied recovery code against a list of stored hashes. Constant-time over the full set — every entry is…
totp — (no submodules) - totp — (no submodules) - totp.schema — Zod boundary schemas for TotpOptions and TotpVerifyOptions. The TOTP schema covers algorithm / digits / period / t0…
- verify-many — Backup-aware TOTP verify. Used during rotation windows where an old and a new TOTP secret coexist — the user's authenti…
- verify — RFC 6238 §5.2 verify with drift window. Checks the supplied code against the current step and ±window neighbouring st…
format-uri — Build a canonical otpauth:// URI from an OtpUri value object. Round-trips with parseUri for every valid input. Pe…
parse-uri — Parse the otpauth:// Key URI Format used by Google Authenticator and every compatible authenticator app. Supports bot…
uri.schema — Zod boundary schemas for the OtpUri discriminated union. OtpTotpUriSchema and OtpHotpUriSchema cover the per-vari…

Install

bun add @suaveplan/otp

Subpath exports

Subpath	Surface
`@suaveplan/otp`	HOTP / TOTP / verify / verifyMany / detectDrift / recovery codes
`@suaveplan/otp/uri`	`parseUri`, `formatUri`, `OtpUri`, `OtpUriSchema`
`@suaveplan/otp/base32`	`base32Encode`, `base32Decode`
`@suaveplan/otp/ocra`	`ocra`, `parseOcraSuite`, `verifyOcra`, mutual-auth helpers
`@suaveplan/otp/errors`	`OTP_CODES`, `OtpError`, `OtpErrorCode`
`@suaveplan/otp/observability`	OTel instrument factories + recorders

Quick start

import { totp, verify } from "@suaveplan/otp";
import { base32Decode } from "@suaveplan/otp/base32";
import { parseUri } from "@suaveplan/otp/uri";

const u = parseUri("otpauth://totp/alice?secret=JBSWY3DPEHPK3PXP&issuer=Example");
const secret = base32Decode(u.secret);

const code = totp(secret);
const r = verify(code, secret);
// r === { valid: true, delta: 0 }

Modules

base32/base32.md — RFC 4648 §6 base32.
hotp/hotp.md — RFC 4226 HOTP.
hotp/encode-counter.md — 8-byte big-endian.
hotp/hmac.md — algorithm-routing HMAC.
hotp/hotp.schema.md — Zod boundary.
totp/totp.md — RFC 6238 TOTP.
totp/verify.md — drift-windowed verify.
totp/verify-many.md — backup-aware verify.
totp/totp.schema.md — Zod boundary.
uri/parse-uri.md — otpauth:// parser.
uri/format-uri.md — otpauth:// builder.
uri/uri.schema.md — Zod boundary.
ocra/ocra.md — RFC 6287 OCRA.
ocra/suite.md — suite-string parser.
ocra/encode-challenge.md — challenge block.
ocra/verify-ocra.md — constant-time verify.
ocra/mutual-auth.md — RFC §7.1 mutual auth.
ocra/ocra.schema.md — Zod boundary.
recovery/generate.md — Crockford codes.
recovery/hash.md — Argon2id-hashed at-rest form.
recovery/verify.md — constant-time verify.
drift/detect.md — clock-drift detector.
observability/metrics.md — OTel.
errors/codes.md — OTP_CODES / OtpError.
errors/zod-map.md — Zod → code mapper.

Standards

RFC 4226 — HOTP (counter-based).
RFC 6238 — TOTP (time-based).
RFC 6287 — OCRA (challenge-response).
RFC 4648 §6 — Base32.
Google Authenticator Key URI Format — otpauth:// scheme.

License

MIT

25 KiB Raw Blame History