oath-relay 0.1.0__tar.gz

oath_relay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peng Ding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oath_relay-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: oath-relay
+Version: 0.1.0
+Summary: Share a stateful HOTP token across devices from one counter
+Author: Peng Ding
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Oaklight/oath-relay
+Project-URL: Issues, https://github.com/Oaklight/oath-relay/issues
+Keywords: hotp,totp,otp,2fa,oath,duo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# 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
+
+```bash
+pipx install oath-relay          # or: pip install oath-relay
+```
+
+Python 3.11+. No runtime dependencies outside the standard library.
+
+## Quick start
+
+```bash
+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
+```
+
+```bash
+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.
+
+```toml
+[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>`:
+
+```bash
+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:
+
+```json
+{"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
+
+```bash
+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
+
+```bash
+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 .../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
+
+```bash
+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](LICENSE).

oath_relay-0.1.0/README.md

@@ -0,0 +1,215 @@
+# 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
+
+```bash
+pipx install oath-relay          # or: pip install oath-relay
+```
+
+Python 3.11+. No runtime dependencies outside the standard library.
+
+## Quick start
+
+```bash
+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
+```
+
+```bash
+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.
+
+```toml
+[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>`:
+
+```bash
+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:
+
+```json
+{"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
+
+```bash
+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
+
+```bash
+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 .../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
+
+```bash
+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](LICENSE).

oath_relay-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oath-relay"
+dynamic = ["version"]
+description = "Share a stateful HOTP token across devices from one counter"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Peng Ding" }]
+keywords = ["hotp", "totp", "otp", "2fa", "oath", "duo"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.11", "build"]
+
+[project.scripts]
+oath-relay = "oath_relay.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Oaklight/oath-relay"
+Issues = "https://github.com/Oaklight/oath-relay/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "oath_relay.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.zerodep]
+vendor-dir = "src/oath_relay/_vendor"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+exclude = ["src/oath_relay/_vendor"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+ignore = ["E501"]

oath_relay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oath_relay-0.1.0/src/oath_relay/__init__.py

@@ -0,0 +1,5 @@
+"""oath-relay: share a stateful HOTP token across devices from one counter."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

oath_relay-0.1.0/src/oath_relay/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())