Generate and validate TOTP (time-based one-time passwords, RFC 6238) from Starlark, built on pquerna/otp. Pure computation β no network, no storage.
starpkg provides support for necessary local operations plus simple
abstractions over common online services, for ease of use. totp is a
local-capability module: it is self-contained two-factor-auth math (HMAC over
the time counter) with no I/O, so a script can mint a secret, render the
provisioning URI for an authenticator app, and verify the codes users type β
all without leaving the sandbox.
For the complete per-builtin reference β signatures, parameters, returns, errors, examples β and the configuration accessors, see docs/API.md.
go get github.com/starpkg/totpload("totp", "generate_code", "validate", "new_secret")
# Provision a new secret for a user
key = new_secret("StarPkg", "alice@example.com")
print(key.secret) # base32 secret to store
print(key.url) # otpauth://totp/... (render as a QR code for the user)
# Generate the current code, then validate what the user typed
# (allows Β±1 period of clock skew by default)
code = generate_code(key.secret)
if validate(user_input, key.secret):
print("authenticated")For deterministic results (e.g. tests), pass an explicit time:
code = generate_code(secret, time=1000000000)
validate(code, secret, time=1000000000) # => TrueTop-level builtins (load("totp", β¦)):
generate_code(secret, time=0, period=<cfg>, digits=<cfg>, algorithm="SHA1")β generate the current code forsecret; returns a string.validate(code, secret, time=0, period=<cfg>, digits=<cfg>, skew=1, algorithm="SHA1")β validatecode;skewallows Β± that many periods; returns a bool.new_secret(issuer, account_name, period=<cfg>, digits=<cfg>, algorithm="SHA1", secret_size=20)β mint a new secret; returnsstruct(secret, url)whereurlis anotpauth://provisioning URI.
digits must be 6 or 8; algorithm must be SHA1, SHA256, or SHA512.
See docs/API.md for the full signatures, return values, errors,
and examples of every builtin above, plus host-side time control
(NewModuleWithClock).
The module's options (default_period, default_digits, max_skew) are
configured via environment variables (TOTP_*) or per-option get_<key> /
set_<key> accessor builtins. default_period / default_digits serve as
defaults that each per-call period / digits keyword overrides. max_skew
is host-only (a read-only get_max_skew, no setter) β the ceiling on
validate's skew (replay) window that a script cannot raise, configured
host-side via TOTP_MAX_SKEW (default 1000). See the
Configuration section of docs/API.md for the full
option table, defaults, and accessors.
MIT