Skip to content
starpkgPublic

About

πŸ” Time-based one-time passwords (RFC 6238) for Starlark

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

13 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ”‘ totp β€” TOTP one-time passwords for Starlark

Go Reference codecov binary footprint

Generate and validate TOTP (time-based one-time passwords, RFC 6238) from Starlark, built on pquerna/otp. Pure computation β€” no network, no storage.

Overview

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.

Installation

go get github.com/starpkg/totp

Quickstart

load("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)   # => True

Starlark API at a glance

Top-level builtins (load("totp", …)):

  • generate_code(secret, time=0, period=<cfg>, digits=<cfg>, algorithm="SHA1") β€” generate the current code for secret; returns a string.
  • validate(code, secret, time=0, period=<cfg>, digits=<cfg>, skew=1, algorithm="SHA1") β€” validate code; skew allows Β± that many periods; returns a bool.
  • new_secret(issuer, account_name, period=<cfg>, digits=<cfg>, algorithm="SHA1", secret_size=20) β€” mint a new secret; returns struct(secret, url) where url is an otpauth:// 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).

Configuration

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.

License

MIT

About

πŸ” Time-based one-time passwords (RFC 6238) for Starlark

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages