#moon_otp

• HOTP — HMAC-based one-time passwords, RFC 4226
• TOTP — time-based one-time passwords, RFC 6238
• HMAC — keyed hashing, RFC 2104, over SHA-1 / SHA-256 / SHA-512
• SHA-1 / SHA-256 / SHA-512 — FIPS 180-4 hash implementations
• Base32 — RFC 4648, standard and Extended Hex alphabets
• otpauth:// URIs — build and parse the de-facto authenticator format
• Steam Guard — five-character Steam mobile authenticator codes
• Recovery codes — one-time backup codes for account recovery
• HOTP resync — counter resynchronization per RFC 4226 §7.4
• Secure secret generation — backed by the platform CSPRNG
• A small command line tool for enrollment and code generation

#Install

moon add 1726914517-spec/moon_otp

///|
import {
  "1726914517-spec/moon_otp",
}

#Library usage

#TOTP (the common case)

///|
/// Generate a new shared secret and enroll a user.
let secret = generate_secret() // 20 random bytes

///|
let otp = {
  issuer: "Acme Corp",
  account: "alice@example.com",
  secret,
  algorithm: Sha1,
  digits: 6,
  period: 30,
}

///|
let uri = otpauth_uri(otp) // QR-code content for an authenticator app

///|
/// Produce the code for the current time, and verify a user-submitted code
/// with one step of clock drift tolerance.
let current = totp_now(Sha1, secret)

///|
let valid = current == submitted_code ||
  totp(Sha1, secret, now_seconds - 30) == submitted_code ||
  totp(Sha1, secret, now_seconds + 30) == submitted_code

///|
/// The same drift-tolerant check is provided directly:
let ok = totp_verify(Sha1, secret, submitted_code)

#HOTP

let key = @utf8.encode("12345678901234567890")
hotp(Sha1, key, 0UL) // "755224"
hotp(Sha1, key, 1UL) // "287082"

#TOTP with SHA-256/SHA-512 and 8 digits

totp(Sha256, key256, 1111111109UL, digits=8) // "68084774"
totp(Sha512, key512, 1234567890UL, digits=8) // "93441116"

#Parsing an otpauth URI

///|
let otp = parse_otpauth_uri(uri)

///|
let code = totp_now(
  otp.algorithm,
  otp.secret,
  digits=otp.digits,
  period=otp.period,
)

#Steam Guard and recovery codes

///|
let steam_code = steam_guard_now(secret) // e.g. "YHBCW"

///|
let recovery = generate_recovery_codes() // 10 codes like "PJKP-Y94J"

#HOTP counter resynchronization (RFC 4226 §7.4)

///|
/// Client drifted ahead: it submitted codes for counters 2 and 3.
match hotp_resync(Sha1, key, server_counter, code1, code2, window=5) {
  Some(new_counter) => // persist new_counter
  None => // reject
}

#CLI

moon run cmd/main -- gen --issuer GitHub --account alice

Secret (Base32): 2WEXWAJKI3EFXMXBI3NE2BIAIHE2UNGV
otpauth URI:    otpauth://totp/GitHub:alice?secret=...&issuer=GitHub&algorithm=SHA1&digits=6&period=30
Current code:   832873

# Current TOTP with seconds remaining in the step
moon run cmd/main -- now --secret 2WEXWAJKI3EFXMXBI3NE2BIAIHE2UNGV

# HOTP at a specific counter
moon run cmd/main -- hotp --secret GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ --counter 0

# Build an otpauth URI from an existing secret
moon run cmd/main -- uri --secret <base32> --issuer GitHub --account alice --algorithm SHA256

# Steam Guard code
moon run cmd/main -- steam --secret <base32>

# One-time recovery codes
moon run cmd/main -- recovery --count 10

# Verify a code (exit 0 on success, 1 on failure)
moon run cmd/main -- verify --secret <base32> --code 123456 --window 1

#Testing

moon test

• FIPS 180-4 / NIST vectors for all three hashes (empty, "abc", two-block)
• HMAC vectors from RFC 2202 (SHA-1) and RFC 4231 (SHA-256/512)
• The full HOTP Appendix D sequence (counters 0–9)
• The complete TOTP Appendix B table for SHA-1/256/512, including the 8-digit values
• Base32 RFC 4648 vectors and strict padding validation
• otpauth URI round trips for both TOTP and HOTP, and malformed-URI errors
• Steam Guard format, recovery codes and HOTP resynchronization
• Drift-tolerant totp_verify, input validation and secret generation

#Project layout

moon_otp/
├── base32.mbt        RFC 4648 Base32
├── sha1.mbt          SHA-1
├── sha256.mbt        SHA-256
├── sha512.mbt        SHA-512
├── digest.mbt        HashAlgorithm dispatch
├── hmac.mbt          HMAC (RFC 2104)
├── hotp.mbt          HOTP (RFC 4226) + resync
├── totp.mbt          TOTP (RFC 6238)
├── steam.mbt         Steam Guard codes
├── recovery.mbt      One-time recovery codes
├── secret.mbt        CSPRNG-backed secret generation
├── otpauth.mbt       otpauth:// URI build/parse (TOTP + HOTP)
└── cmd/main/         Command line tool

#Relation to existing packages

• Q30399/moonvault is a broad password-hashing/crypto suite. Its published 0.1.0 covers TOTP generation/verification and URI building (with no HOTP function); its unreleased main branch adds HOTP, but totp_now and totp_verify pass a hardcoded timestamp 0 and never read the clock. moon_otp provides the missing, correct pieces:
  • otpauth:// URI parsing — moonvault only builds URIs (without algorithm/digits/period parameters or percent encoding);
  • a command line tool with gen/now/hotp/uri;
  • correct current-time TOTP with a configurable drift window;
  • RFC-verified HOTP and the complete RFC vector suites (HOTP Appendix D, TOTP Appendix B across SHA-1/256/512).
• cc06b/mooncry is a broad, zero-dependency cryptographic primitives library (hashes, AEAD, KDFs, asymmetric and post-quantum algorithms, ...). Its OTP surface is generation only — hotp/totp plus SHA-256/512 variants — with no Base32, no otpauth:// build or parse, no current-time/verify APIs, no Steam Guard, recovery codes, resynchronization, or CLI. moon_otp is a dedicated, end-to-end OTP solution covering enrollment (secret generation + otpauth), distribution (CLI) and verification.
• Tigls/mb-hmac provides HMAC; moon_otp uses its own HMAC because the OTP layer requires all three hash algorithms and tight control of block sizes.
• yyjeqhc/base32 and Lfan-ke/basex provide Base32; moon_otp includes its own decoder to validate OTP secrets without an extra dependency.

#License