Single-writer HOTP counter service: share a stateful HOTP token across devices without divergence
132
English | 中文
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.
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.
pipx install oath-relay # or: pip install oath-relay
Python 3.10+. No runtime dependencies.
oath-relay init # writes ./oath-relay.jsonc (0600)
$EDITOR oath-relay.jsonc # 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.
Static configuration (secrets) lives in JSONC — JSON with comments and trailing commas. Mutable state (counters) lives in a separate 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.jsonc, /config/config.jsonc,
/etc/oath-relay/config.jsonc. Override with --config PATH.
| 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.
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.
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.
Published as oaklight/oath-relay.
docker run -d --name oath-relay --restart always \
-p 127.0.0.1:8790:8790 \
-e PUID=$(id -u) -e PGID=$(id -g) \
-v "$PWD/config.jsonc:/config/config.jsonc:ro" \
-v "$PWD/state:/state" \
oaklight/oath-relay:latest
Or with Compose, which keeps the state volume explicit:
cp oath-relay.example.jsonc config.jsonc # then edit it, chmod 600
docker compose up -d
User and group. The container starts as root only long enough to honour
PUID/PGID, then drops privileges, so the state file is owned by you rather
than by an arbitrary image uid. Set PUID=$(id -u) PGID=$(id -g). Passing
--user instead also works: the drop is skipped and the process runs directly
as that user.
Persistence. /state holds the counters. It is declared as a volume and
bind-mounted to ./state by compose.yaml. Losing it means every HOTP token
is out of sync with its provider — back it up like a credential.
A config mounted from the host must be readable by PUID.
Read this before exposing the service.
POST .../next can log in as you. Protect the endpoint as carefully as the
secret itself: bind it to a private network, keep tokens long, rotate them.peek defeats 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.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.
This service holds second-factor secrets. See SECURITY.md for the threat model, what is in and out of scope, and how to report a vulnerability privately. Do not open a public issue for security problems.
MIT. See LICENSE.
Content type
Image
Digest
sha256:652c5375a…
Size
42.7 MB
Last updated
14 days ago
docker pull oaklight/oath-relay