Skip to main content

oath-relay

PyPI Python License Dependencies

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.

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.10+. No runtime dependencies.

Quick start

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.

Configuration

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.

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

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.

Threat model

Read this before exposing the service.

  • A bearer token is a second factor. Anyone who can call 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.
  • With auth disabled the service is a credential printer. It warns at startup. Only acceptable on a host reachable by you alone.
  • 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.
  • 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.

License

MIT. See LICENSE.

Metadata

Release files for oath-relay 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oath-relay 0.2.0
File Size Uploaded Provenance Actions
oath_relay-0.2.0.tar.gz 51.5 kB Without provenance Details for oath_relay-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oath-relay 0.2.0
File Interpreter ABI Platform Actions
oath_relay-0.2.0-py3-none-any.whl Python 3 none any Details for oath_relay-0.2.0-py3-none-any.whl

Total release size: 98.1 kB

Release files / oath_relay-0.2.0.tar.gz

Download URL oath_relay-0.2.0.tar.gz
Size 51.5 kB
Tags Source
SHA-256 checksum
How to use checksums
828df4acdd1cf32d91e5ac0555dcbcc1f3897db5c4ba52c76a396e58d9e58410
BLAKE2b-256 checksum
How to use checksums
ce69ec03888a1e73453ffabefc4a2be631f956e69ec003e4c44c595bef887a96
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.2.0-py3-none-any.whl

Download URL oath_relay-0.2.0-py3-none-any.whl
Size 46.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebeb1abc07007b1b46c9ee9a7dad6c1f999d8ac1f3b8f2274997066d66a34f7a
BLAKE2b-256 checksum
How to use checksums
8108903301a62aae206d78d23d135cdaea9127a25451980a4095e884151a8c4c
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.2.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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page