oath-relay
Share a stateful HOTP token across devices from a single counter.
oath-relay is a tiny, dependency-free service that owns the counter for one
or more HOTP tokens and hands out the next code over HTTP. It exists because
HOTP is the one 2FA scheme that cannot be synced the way TOTP can.
HOTP = HMAC-SHA1(secret, counter)
TOTP = HMAC-SHA1(secret, floor(unixtime / 30))
TOTP is a pure function of the clock, so every device computes the same code from the same secret. HOTP is a function of a mutable counter: two clients holding the same secret advance independently and diverge permanently. There is no way to merge two counters. The only correct answer is one writer.
oath-relay is that writer.
Why not just use a password manager?
Bitwarden — and Vaultwarden, which is what this was built against — supports
TOTP only. Handed an otpauth://hotp/... URI it silently computes a TOTP from
the same secret, so the codes never match. Measured:
Bitwarden from an otpauth://hotp/ URI : 332512 (== the TOTP for that secret)
Real HOTP at counter 1 : 996554
Some services are HOTP-only. Cisco Duo, for instance, decides per tenant via a
use_totp flag in the enrolment response; when it is false, no TOTP client
will ever work.
Install
pipx install oath-relay # or: pip install oath-relay
Python 3.11+. No runtime dependencies outside the standard library.
Quick start
oath-relay init # writes ./oath-relay.toml (0600)
$EDITOR oath-relay.toml # add your tokens
oath-relay hash # generate auth.basic_password_hash
oath-relay serve # http://127.0.0.1:8790
curl -X POST -H 'Authorization: Bearer <token>' \
http://127.0.0.1:8790/api/tokens/my-token/next
# {"name":"my-token","type":"hotp","code":"755224","counter":0,"next_counter":1}
Or open http://127.0.0.1:8790/ in a browser and press the button.
Configuration
Static configuration (secrets) lives in TOML. Mutable state (counters) lives in a separate JSON file, so the state file is safe to back up and diff.
[server]
host = "127.0.0.1"
port = 8790
allow_peek = false
[state]
path = "./state/state.json"
[auth]
basic_user = "alice"
basic_password_hash = "scrypt$..." # from `oath-relay hash`
bearer_tokens = ["long-random-string"] # several allowed, for rotation
[[tokens]]
name = "example"
type = "hotp" # or "totp"
secret = "JBSWY3DPEHPK3PXP"
digits = 6
algorithm = "sha1" # sha1 | sha256 | sha512
counter_start = 0 # used only until the first code is issued
Environment overrides use OATH_RELAY_<SECTION>__<KEY>:
OATH_RELAY_SERVER__PORT=9000
OATH_RELAY_AUTH__BEARER_TOKENS=one,two
Config search order: ./oath-relay.toml, /config/config.toml,
/etc/oath-relay/config.toml. Override with --config PATH.
HTTP API
| Method | Path | Effect |
|---|---|---|
| GET | / |
HTML page, one button per token |
| GET | /healthz |
{"status":"ok"}, no auth |
| GET | /api/tokens |
Names, types and counters; never secrets |
| GET | /api/tokens/{name}/status |
Current counter, read-only |
| POST | /api/tokens/{name}/next |
Issues a code and advances the counter |
| POST | /api/tokens/{name}/resync |
Force a counter (recovery) |
| GET | /api/tokens/{name}/peek |
Code without advancing (opt-in, see below) |
POST .../next accepts no body and returns:
{"name": "example", "type": "hotp", "code": "755224", "counter": 0, "next_counter": 1}
TOTP tokens return remaining (seconds until rotation) instead of
next_counter, and never touch the state file.
POST .../resync takes {"counter": 42}. It is the recovery path for drift.
GET never mutates
This is deliberate and enforced by tests. Browser prefetch, link previews and crawlers all issue GETs; a counter that advances on a prefetch drifts silently. Only the two POST endpoints above change state.
CLI
oath-relay serve [--host H] [--port P] # run the server
oath-relay code NAME [-q] # print next code, consume counter
oath-relay peek NAME [-q] # print current code, do not consume
oath-relay list # tokens and their counters
oath-relay status NAME # counter only
oath-relay resync NAME COUNTER # force a counter
oath-relay hash [-p PASSWORD] # scrypt hash for basic auth
oath-relay init [PATH] [-f] # write a template config
code and serve share the same state file, so a local CLI call and an HTTP
call are serialised by the same flock.
Docker
docker build -t oath-relay:dev .
docker run --rm -p 127.0.0.1:8790:8790 \
-v "$PWD/config.toml:/config/config.toml:ro" \
-v "$PWD/state:/state" \
oath-relay:dev
docker/entrypoint.sh writes a template config on first run if none is
mounted. The container runs as a non-root user and declares /state as a
volume.
Threat model
Read this before exposing the service.
- A bearer token is a second factor. Anyone who can call
POST .../nextcan log in as you. Protect the endpoint as carefully as the secret itself: bind it to a private network, keep tokens long, rotate them. - With auth disabled the service is a credential printer. It warns at startup. Only acceptable on a host reachable by you alone.
peekdefeats the purpose of a counter. It returns the current code without advancing, which is useful for debugging and dangerous in production, because a code you generated but never used desynchronises you. It is off by default.- One writer per token. Point every device at this service. Do not also import the same secret into a phone authenticator: two writers is exactly the divergence this tool exists to prevent.
- Codes are not logged. Neither the secret nor any generated code is written to stdout or to the state file.
What this is not
- Not an identity provider. It does not authenticate users; it issues codes.
- Not a TOTP sync service. TOTP needs no server — compute it locally.
- Not a way to bypass someone else's 2FA. Use it for accounts you own.
Development
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest
ruff check src/ tests/ && ruff format --check src/ tests/
The test suite covers the RFC 4226 and RFC 6238 vectors, concurrent counter increments across processes, and the HTTP contract (including that GET never mutates).
To check a real enrolment secret, set OATH_RELAY_DUO_SECRET and
OATH_RELAY_DUO_CODES (comma separated, starting at counter 0) before running
pytest. The test is skipped when they are unset, so secrets never land in the
repository.
中文
oath-relay 解决的是 HOTP 不能同步的问题。
TOTP 是时间的纯函数,多端各自计算即可;HOTP 依赖一个可变的计数器,两端各持一份 secret 必然分叉,且无法合并。唯一正确的做法是只有一个写入者 —— 这个服务就是那个写入者。
Bitwarden / Vaultwarden 只支持 TOTP:喂给它 otpauth://hotp/...,它会拿同一个 secret
当 TOTP 算,码永远对不上。有些服务(例如 Duo 的某些租户)只认 HOTP。
用法见上文 Quick start。注意威胁模型:bearer token 等于你的第二因子,务必只绑内网。
License
MIT. See LICENSE.
Metadata
Release files for oath-relay 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oath_relay-0.1.0.tar.gz | 47.0 kB | Without provenance | Details for oath_relay-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oath_relay-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for oath_relay-0.1.0-py3-none-any.whl |
Total release size: 88.4 kB
Release files / oath_relay-0.1.0.tar.gz
| Download URL | oath_relay-0.1.0.tar.gz |
|---|---|
| Size | 47.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93a068aac029fabd2549dec28e483e43c3f2fc72d8313a3275a1113717c8c584
|
|
BLAKE2b-256 checksum How to use checksums |
9235419e02791795bec65c2459bb4c74688e48c82eb45abceff276032d86dff7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.8
|
Release files / oath_relay-0.1.0-py3-none-any.whl
| Download URL | oath_relay-0.1.0-py3-none-any.whl |
|---|---|
| Size | 41.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
429d9f4704c6fffadbb275b62378944600b732681f8769440b34d046aef199a8
|
|
BLAKE2b-256 checksum How to use checksums |
7ea67442c05bf7a3bd284d9c5728ea3ca682392526c221057602fb058ec1eba1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.8
|
Security for oath-relay 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.