sp-rtk-portal-protocol 0.9.0__tar.gz

sp_rtk_portal_protocol-0.9.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: sp-rtk-portal-protocol
+Version: 0.9.0
+Summary: Agent-to-Portal protocol shared by sp-rtk-portal and sp-rtk-base's Portal agent
+Keywords: rtk,gnss,base-station,dpop,jws,ed25519,tunnel
+Author: John Roden
+Author-email: John Roden <rodenj@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Dist: cryptography>=42
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/rodenj1/sp-rtk-portal/tree/main/protocol
+Project-URL: Repository, https://github.com/rodenj1/sp-rtk-portal
+Project-URL: Issues, https://github.com/rodenj1/sp-rtk-portal/issues
+Project-URL: Used by, https://github.com/rodenj1/sp-rtk-base
+Description-Content-Type: text/markdown
+
+# sp-rtk-portal-protocol
+
+The agent-to-Portal protocol, published from the `sp-rtk-portal` repo so the Portal and sp-rtk-base's Portal agent share one definition: message shapes, request signing and verification, tunnel framing, and the protocol version.
+
+## What's in it
+
+- `PROTOCOL_VERSION` (an integer, starting at 1, independent of either side's release version) and `VERSION_HEADER` (`SP-RTK-Protocol-Version`), sent on every agent request. Additive changes don't bump it: both sides ignore fields they don't know.
+- **Request proofs** (`proof.py`). The agent's Ed25519 **base key** (`BaseKey`) signs every request with a DPoP-style JWS (RFC 9449), sent as `Authorization: Signature <proof>`: header `{"typ": "dpop+jwt", "alg": "EdDSA", "jwk": <public key>}`, claims `htm`, `htu` (URL without query), `iat` (seconds), `jti`, `bh` (base64url SHA-256 of the body, when there is one) and optional `nonce`. `verify_proof` checks the signature, the request it was made for, the body and that `iat` is within 60 s; `ReplayCache` refuses a `jti` seen before. The Portal identifies a base by the key's RFC 7638 thumbprint and stores only the public key.
+- **Message shapes** (`messages.py`): frozen dataclasses with `to_json()` / `from_json()`. `from_json` ignores unknown fields and raises `MessageError` for a missing or mistyped one.
+  - Claim (RFC 8628): `POST /agent/claims` with `ClaimStart` → `ClaimStarted`; `POST /agent/claims/token` with `ClaimToken` → `Claimed`, or HTTP 400 `ErrorReply` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`, `invalid_grant`). Both requests are signed with the new key, so only the key that started a Claim can collect it.
+  - Polls and Check-ins (a Claimed base, signed with its key): `POST /agent/poll` with `Poll(state)` → `PollReply(config, metered, notices)`; `POST /agent/check-in` with `CheckIn(software_version, doorbell, lan_addresses, paused)` (`paused` from 0.9; `None` from older agents) → `CheckInReply(config, metered, notices)`. `config` is the revisioned `AgentConfig` block (poll intervals, Check-in interval, Doorbell host and port, tunnel URL, tunnel timeouts; the agent applies it only on a new revision). An unknown key gets 401 `ErrorReply("unclaimed")`.
+  - Release (a local Un-claim, signed with the base key): `POST /agent/release` with `Release()` → `Released(base_id)`, or 401 `unclaimed` if the Portal already forgot the key. Best effort: the agent wipes its key either way.
+  - An agent below the Portal's minimum protocol version gets HTTP 426 `UpgradeRequired(min_version, message)` on any request.
+  - Messages may nest messages, lists of them and optional (`X | None`) fields.
+  - A refused proof is HTTP 401 `ErrorReply("invalid_proof")`.
+  - A Wake: `PollReply.wake` carries a one-time nonce (and nothing else).
+  - `PollReply.sessions`: the base's live Remote sessions (`LiveSession(who, since, shared)`), for its local Portal page. `Poll.state` is `paused` while remote access is paused on site; a paused agent ignores Wakes.
+- **Doorbell** (`doorbell.py`). UDP packets between a base and a Doorbell server: a keepalive signed by the base key (`keepalive`, `read_keepalive`, `verify_keepalive`; 109 bytes) and a ring carrying a Wake's nonce, authenticated with the base's ring key (`ring`, `open_ring`, `new_ring_key`); both refused more than 60 s from now. `DOORBELL_INTERVAL` (20 s) and `DOORBELL_JITTER` (5 s). `CheckInReply.doorbell_heard` and `.ring_key` tell the agent the Portal hears its keepalives and give it the ring key. The Doorbell server's HTTPS interface on the Portal: `KEEPALIVES_PATH` (`KeepalivesReport` → `KeepalivesReply`) and `RINGS_PATH` (→ `Rings`); see the Portal README.
+- **Tunnel** (`tunnel.py`). The agent opens `wss://<Portal host>/agent/tunnel` with a GET signed for `https://<Portal host>/agent/tunnel` (`signed_url`) whose proof's `nonce` claim echoes the Wake. Each binary websocket message is one frame: a type byte, a big-endian 4-byte stream id, then the payload. Types: `NEW` (1, no payload ever: a stream never names a destination), `DATA` (2, 1..64 KiB), `CLOSE` (3), `PING`/`PONG` (4/5, stream 0), `PAUSE`/`RESUME` (6/7, flow control). An unknown type, a payload where none belongs, or a `NEW` from the agent raises `FrameError`, and the receiver closes the whole tunnel. `Tunnel` is one end of it (independent of the websocket library: give it a `send` coroutine and `feed` it each message); only the Portal end opens streams (`open_stream()` -> `Stream` with `read`/`write`/`close`).
+
+The package version (`pyproject.toml`) is bumped on every change, so a pinned consumer can tell which shapes it has.
+
+It is published to PyPI, and sp-rtk-base depends on it from there:
+
+```toml
+[project]
+dependencies = ["sp-rtk-portal-protocol>=0.9.0,<1"]
+```
+
+Raise the lower bound when the agent needs newer shapes. The Portal uses this directory directly, as a uv workspace member.
+
+For local development of both sides at once, point sp-rtk-base at a checkout next to it with `[tool.uv.sources] sp-rtk-portal-protocol = { path = "../sp-rtk-portal/protocol", editable = true }`, and don't commit that.
+
+## Releasing
+
+`.github/workflows/protocol-release.yml` publishes this package to PyPI when a `protocol-v<version>` tag is pushed. It checks the tag against `version` in this `pyproject.toml`, runs these tests on Python 3.10 to 3.13, builds with `uv build`, runs `twine check`, then uploads with PyPI Trusted Publishing (OIDC, no token). Portal image tags (`v*`) and protocol tags don't trigger each other's workflow.
+
+Once, before the first release:
+
+1. On pypi.org, under Your account > Publishing > Add a new pending publisher > GitHub, enter:
+   - PyPI project name: `sp-rtk-portal-protocol`
+   - Owner: `rodenj1`
+   - Repository name: `sp-rtk-portal`
+   - Workflow name: `protocol-release.yml`
+   - Environment name: `pypi`
+2. On GitHub, in the sp-rtk-portal repo's Settings > Environments, create an environment named `pypi` (optionally with required reviewers, to approve each upload).
+
+   GitHub offers environments in a private repo only on a paid plan (Pro, Team or Enterprise). If Settings has no Environments page, leave the environment name blank in step 1, and delete the `environment:` block from the workflow's `publish-pypi` job.
+
+Each release:
+
+1. Bump `version` in this `pyproject.toml` on `main` (PyPI never accepts the same version twice).
+2. Tag that commit and push the tag:
+
+   ```sh
+   git tag protocol-v0.9.0
+   git push origin protocol-v0.9.0
+   ```
+
+3. Once it's on PyPI, raise sp-rtk-base's lower bound if the agent needs the new version, then run `uv lock` there.
+
+To rerun a failed release for an existing tag, run the workflow by hand (Actions > protocol-release > Run workflow) with the tag.

sp_rtk_portal_protocol-0.9.0/README.md

@@ -0,0 +1,62 @@
+# sp-rtk-portal-protocol
+
+The agent-to-Portal protocol, published from the `sp-rtk-portal` repo so the Portal and sp-rtk-base's Portal agent share one definition: message shapes, request signing and verification, tunnel framing, and the protocol version.
+
+## What's in it
+
+- `PROTOCOL_VERSION` (an integer, starting at 1, independent of either side's release version) and `VERSION_HEADER` (`SP-RTK-Protocol-Version`), sent on every agent request. Additive changes don't bump it: both sides ignore fields they don't know.
+- **Request proofs** (`proof.py`). The agent's Ed25519 **base key** (`BaseKey`) signs every request with a DPoP-style JWS (RFC 9449), sent as `Authorization: Signature <proof>`: header `{"typ": "dpop+jwt", "alg": "EdDSA", "jwk": <public key>}`, claims `htm`, `htu` (URL without query), `iat` (seconds), `jti`, `bh` (base64url SHA-256 of the body, when there is one) and optional `nonce`. `verify_proof` checks the signature, the request it was made for, the body and that `iat` is within 60 s; `ReplayCache` refuses a `jti` seen before. The Portal identifies a base by the key's RFC 7638 thumbprint and stores only the public key.
+- **Message shapes** (`messages.py`): frozen dataclasses with `to_json()` / `from_json()`. `from_json` ignores unknown fields and raises `MessageError` for a missing or mistyped one.
+  - Claim (RFC 8628): `POST /agent/claims` with `ClaimStart` → `ClaimStarted`; `POST /agent/claims/token` with `ClaimToken` → `Claimed`, or HTTP 400 `ErrorReply` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`, `invalid_grant`). Both requests are signed with the new key, so only the key that started a Claim can collect it.
+  - Polls and Check-ins (a Claimed base, signed with its key): `POST /agent/poll` with `Poll(state)` → `PollReply(config, metered, notices)`; `POST /agent/check-in` with `CheckIn(software_version, doorbell, lan_addresses, paused)` (`paused` from 0.9; `None` from older agents) → `CheckInReply(config, metered, notices)`. `config` is the revisioned `AgentConfig` block (poll intervals, Check-in interval, Doorbell host and port, tunnel URL, tunnel timeouts; the agent applies it only on a new revision). An unknown key gets 401 `ErrorReply("unclaimed")`.
+  - Release (a local Un-claim, signed with the base key): `POST /agent/release` with `Release()` → `Released(base_id)`, or 401 `unclaimed` if the Portal already forgot the key. Best effort: the agent wipes its key either way.
+  - An agent below the Portal's minimum protocol version gets HTTP 426 `UpgradeRequired(min_version, message)` on any request.
+  - Messages may nest messages, lists of them and optional (`X | None`) fields.
+  - A refused proof is HTTP 401 `ErrorReply("invalid_proof")`.
+  - A Wake: `PollReply.wake` carries a one-time nonce (and nothing else).
+  - `PollReply.sessions`: the base's live Remote sessions (`LiveSession(who, since, shared)`), for its local Portal page. `Poll.state` is `paused` while remote access is paused on site; a paused agent ignores Wakes.
+- **Doorbell** (`doorbell.py`). UDP packets between a base and a Doorbell server: a keepalive signed by the base key (`keepalive`, `read_keepalive`, `verify_keepalive`; 109 bytes) and a ring carrying a Wake's nonce, authenticated with the base's ring key (`ring`, `open_ring`, `new_ring_key`); both refused more than 60 s from now. `DOORBELL_INTERVAL` (20 s) and `DOORBELL_JITTER` (5 s). `CheckInReply.doorbell_heard` and `.ring_key` tell the agent the Portal hears its keepalives and give it the ring key. The Doorbell server's HTTPS interface on the Portal: `KEEPALIVES_PATH` (`KeepalivesReport` → `KeepalivesReply`) and `RINGS_PATH` (→ `Rings`); see the Portal README.
+- **Tunnel** (`tunnel.py`). The agent opens `wss://<Portal host>/agent/tunnel` with a GET signed for `https://<Portal host>/agent/tunnel` (`signed_url`) whose proof's `nonce` claim echoes the Wake. Each binary websocket message is one frame: a type byte, a big-endian 4-byte stream id, then the payload. Types: `NEW` (1, no payload ever: a stream never names a destination), `DATA` (2, 1..64 KiB), `CLOSE` (3), `PING`/`PONG` (4/5, stream 0), `PAUSE`/`RESUME` (6/7, flow control). An unknown type, a payload where none belongs, or a `NEW` from the agent raises `FrameError`, and the receiver closes the whole tunnel. `Tunnel` is one end of it (independent of the websocket library: give it a `send` coroutine and `feed` it each message); only the Portal end opens streams (`open_stream()` -> `Stream` with `read`/`write`/`close`).
+
+The package version (`pyproject.toml`) is bumped on every change, so a pinned consumer can tell which shapes it has.
+
+It is published to PyPI, and sp-rtk-base depends on it from there:
+
+```toml
+[project]
+dependencies = ["sp-rtk-portal-protocol>=0.9.0,<1"]
+```
+
+Raise the lower bound when the agent needs newer shapes. The Portal uses this directory directly, as a uv workspace member.
+
+For local development of both sides at once, point sp-rtk-base at a checkout next to it with `[tool.uv.sources] sp-rtk-portal-protocol = { path = "../sp-rtk-portal/protocol", editable = true }`, and don't commit that.
+
+## Releasing
+
+`.github/workflows/protocol-release.yml` publishes this package to PyPI when a `protocol-v<version>` tag is pushed. It checks the tag against `version` in this `pyproject.toml`, runs these tests on Python 3.10 to 3.13, builds with `uv build`, runs `twine check`, then uploads with PyPI Trusted Publishing (OIDC, no token). Portal image tags (`v*`) and protocol tags don't trigger each other's workflow.
+
+Once, before the first release:
+
+1. On pypi.org, under Your account > Publishing > Add a new pending publisher > GitHub, enter:
+   - PyPI project name: `sp-rtk-portal-protocol`
+   - Owner: `rodenj1`
+   - Repository name: `sp-rtk-portal`
+   - Workflow name: `protocol-release.yml`
+   - Environment name: `pypi`
+2. On GitHub, in the sp-rtk-portal repo's Settings > Environments, create an environment named `pypi` (optionally with required reviewers, to approve each upload).
+
+   GitHub offers environments in a private repo only on a paid plan (Pro, Team or Enterprise). If Settings has no Environments page, leave the environment name blank in step 1, and delete the `environment:` block from the workflow's `publish-pypi` job.
+
+Each release:
+
+1. Bump `version` in this `pyproject.toml` on `main` (PyPI never accepts the same version twice).
+2. Tag that commit and push the tag:
+
+   ```sh
+   git tag protocol-v0.9.0
+   git push origin protocol-v0.9.0
+   ```
+
+3. Once it's on PyPI, raise sp-rtk-base's lower bound if the agent needs the new version, then run `uv lock` there.
+
+To rerun a failed release for an existing tag, run the workflow by hand (Actions > protocol-release > Run workflow) with the tag.

sp_rtk_portal_protocol-0.9.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sp-rtk-portal-protocol"
+version = "0.9.0"
+description = "Agent-to-Portal protocol shared by sp-rtk-portal and sp-rtk-base's Portal agent"
+readme = "README.md"
+authors = [{ name = "John Roden", email = "rodenj@gmail.com" }]
+license = "MIT"
+# sp-rtk-base supports Python 3.10, so this package must too.
+requires-python = ">=3.10"
+keywords = ["rtk", "gnss", "base-station", "dpop", "jws", "ed25519", "tunnel"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+dependencies = ["cryptography>=42"]
+
+[project.urls]
+Homepage = "https://github.com/rodenj1/sp-rtk-portal/tree/main/protocol"
+Repository = "https://github.com/rodenj1/sp-rtk-portal"
+Issues = "https://github.com/rodenj1/sp-rtk-portal/issues"
+"Used by" = "https://github.com/rodenj1/sp-rtk-base"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.13"]
+build-backend = "uv_build"
+
+[tool.ruff]
+extend = "../pyproject.toml"
+# sp-rtk-base still runs on Python 3.10.
+target-version = "py310"

sp_rtk_portal_protocol-0.9.0/src/sp_rtk_portal_protocol/__init__.py

@@ -0,0 +1,125 @@
+"""The agent-to-Portal protocol shared by sp-rtk-portal and sp-rtk-base."""
+
+from sp_rtk_portal_protocol import doorbell
+from sp_rtk_portal_protocol.doorbell import (
+    DOORBELL_INTERVAL,
+    DOORBELL_JITTER,
+    DoorbellError,
+    HeardKeepalive,
+    KeepalivesReply,
+    KeepalivesReport,
+    Ring,
+    Rings,
+)
+from sp_rtk_portal_protocol.messages import (
+    CHECK_IN_PATH,
+    CLAIM_TOKEN_PATH,
+    CLAIMS_PATH,
+    DOORBELL_IGNORED,
+    DOORBELL_OFF,
+    DOORBELL_OK,
+    DOORBELL_UNAVAILABLE,
+    POLL_PATH,
+    RELEASE_PATH,
+    TUNNEL_PATH,
+    AgentConfig,
+    CheckIn,
+    CheckInReply,
+    Claimed,
+    ClaimStart,
+    ClaimStarted,
+    ClaimToken,
+    ErrorReply,
+    LanAddress,
+    LiveSession,
+    Message,
+    MessageError,
+    Notice,
+    Poll,
+    PollReply,
+    Release,
+    Released,
+    UpgradeRequired,
+)
+from sp_rtk_portal_protocol.proof import (
+    AUTHORIZATION_SCHEME,
+    MAX_CLOCK_SKEW,
+    BaseKey,
+    ProofError,
+    ReplayCache,
+    VerifiedProof,
+    jwk_thumbprint,
+    proof_from_authorization,
+    request_url,
+    verify_proof,
+)
+from sp_rtk_portal_protocol.tunnel import (
+    FrameError,
+    Stream,
+    StreamClosed,
+    Tunnel,
+    TunnelClosed,
+)
+from sp_rtk_portal_protocol.version import (
+    PROTOCOL_VERSION,
+    VERSION_HEADER,
+    version_from_header,
+)
+
+__all__ = [
+    "AUTHORIZATION_SCHEME",
+    "CHECK_IN_PATH",
+    "CLAIMS_PATH",
+    "CLAIM_TOKEN_PATH",
+    "DOORBELL_IGNORED",
+    "DOORBELL_INTERVAL",
+    "DOORBELL_JITTER",
+    "DOORBELL_OFF",
+    "DOORBELL_OK",
+    "DOORBELL_UNAVAILABLE",
+    "MAX_CLOCK_SKEW",
+    "POLL_PATH",
+    "PROTOCOL_VERSION",
+    "RELEASE_PATH",
+    "TUNNEL_PATH",
+    "VERSION_HEADER",
+    "AgentConfig",
+    "BaseKey",
+    "CheckIn",
+    "CheckInReply",
+    "ClaimStart",
+    "ClaimStarted",
+    "ClaimToken",
+    "Claimed",
+    "DoorbellError",
+    "ErrorReply",
+    "FrameError",
+    "HeardKeepalive",
+    "KeepalivesReply",
+    "KeepalivesReport",
+    "LanAddress",
+    "LiveSession",
+    "Message",
+    "MessageError",
+    "Notice",
+    "Poll",
+    "PollReply",
+    "ProofError",
+    "Release",
+    "Released",
+    "ReplayCache",
+    "Ring",
+    "Rings",
+    "Stream",
+    "StreamClosed",
+    "Tunnel",
+    "TunnelClosed",
+    "UpgradeRequired",
+    "VerifiedProof",
+    "doorbell",
+    "jwk_thumbprint",
+    "proof_from_authorization",
+    "request_url",
+    "verify_proof",
+    "version_from_header",
+]

sp_rtk_portal_protocol-0.9.0/src/sp_rtk_portal_protocol/doorbell.py

@@ -0,0 +1,233 @@
+"""The Doorbell (ADR 0002): UDP packets between a base and a Doorbell server,
+and the HTTPS interface the Doorbell server uses on the Portal.
+
+A base whose agent config names a usable Doorbell host sends a **keepalive**
+to it every :data:`DOORBELL_INTERVAL` seconds (± :data:`DOORBELL_JITTER`),
+from one UDP socket, which holds a return path open through its router. To
+Wake the base the Portal hands the Doorbell server a **ring**, which it sends
+back down that path. Packets are binary, big-endian:
+
+- keepalive (109 bytes): ``MAGIC`` (4) | kind 1 | time (8, Unix seconds) |
+  key thumbprint (32, the raw SHA-256 behind the RFC 7638 thumbprint) |
+  Ed25519 signature by the base key over everything before it (64).
+- ring: ``MAGIC`` (4) | kind 2 | time (8) | nonce length (1) | nonce (ASCII,
+  the Wake's one-time nonce) | HMAC-SHA256 over everything before it with the
+  base's **ring key** (32).
+
+The ring key is a per-base secret the Portal gives the agent in each
+Check-in reply (over HTTPS). A ring carries only a Wake's nonce: the agent
+then opens its tunnel exactly as for a polled Wake, echoing the nonce in a
+request signed by its base key, so even a forged ring could only cause a
+refused tunnel attempt. Both packets are refused more than
+:data:`~sp_rtk_portal_protocol.proof.MAX_CLOCK_SKEW` away from now.
+
+The Doorbell server holds no keys. It relays each keepalive it receives, with
+the address and port it came from, to :data:`KEEPALIVES_PATH`; the Portal
+checks the signature, records the sign of life and remembers the return
+path. It collects rings from :data:`RINGS_PATH` (a long poll) and sends each
+packet to the address and port given. Both requests carry
+``Authorization: Bearer <the Doorbell token>``.
+"""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import hashlib
+import hmac
+import secrets
+import struct
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from sp_rtk_portal_protocol.messages import Message
+from sp_rtk_portal_protocol.proof import MAX_CLOCK_SKEW, BaseKey
+
+DOORBELL_INTERVAL = 20
+"""Seconds between a base's keepalives (before jitter)."""
+DOORBELL_JITTER = 5
+"""Each gap is ``DOORBELL_INTERVAL`` ± up to this many seconds."""
+
+MAGIC = b"SPDB"
+KEEPALIVE = 1
+RING = 2
+
+_HEAD = struct.Struct(">4sBQ")  # magic, kind, time
+_SIGNATURE = 64
+_THUMBPRINT = 32
+_MAC = 32
+KEEPALIVE_SIZE = _HEAD.size + _THUMBPRINT + _SIGNATURE
+MAX_NONCE = 255
+
+KEEPALIVES_PATH = "/doorbell/keepalives"
+"""POST (Doorbell server -> Portal): :class:`KeepalivesReport` ->
+:class:`KeepalivesReply`."""
+RINGS_PATH = "/doorbell/rings"
+"""GET ``?wait=<seconds>`` (Doorbell server -> Portal), a long poll: ->
+:class:`Rings` as soon as there are any, or empty after ``wait``."""
+
+KEEPALIVE_OK = "ok"
+KEEPALIVE_UNKNOWN = "unknown"
+"""No Claimed base has this key."""
+KEEPALIVE_INVALID = "invalid"
+"""Not a keepalive, a bad signature, or too old or new."""
+
+
+class DoorbellError(ValueError):
+    """A packet that must be ignored. The message says why (for logs)."""
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _unb64(text: str) -> bytes:
+    try:
+        return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+    except (ValueError, TypeError) as exc:
+        raise DoorbellError("not base64url") from exc
+
+
+def encode_packet(packet: bytes) -> str:
+    """A packet as the HTTPS interface carries it (base64url, no padding)."""
+    return _b64(packet)
+
+
+def decode_packet(text: str) -> bytes:
+    return _unb64(text)
+
+
+def _when(at: int) -> datetime:
+    try:
+        return datetime.fromtimestamp(at, tz=timezone.utc)
+    except (ValueError, OverflowError, OSError) as exc:
+        raise DoorbellError("packet time is out of range") from exc
+
+
+def _check_time(at: int, now: datetime) -> datetime:
+    when = _when(at)
+    if abs(now - when) > MAX_CLOCK_SKEW:
+        raise DoorbellError("packet time is too far from now")
+    return when
+
+
+# --- Keepalives ------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Keepalive:
+    thumbprint: str
+    """The base key's RFC 7638 thumbprint (find the base by it)."""
+    at: datetime
+    """When the base sent it (its clock)."""
+
+
+def keepalive(key: BaseKey, *, now: datetime) -> bytes:
+    """A keepalive signed by the base key."""
+    body = _HEAD.pack(MAGIC, KEEPALIVE, int(now.timestamp())) + _unb64(key.thumbprint)
+    return body + key.sign(body)
+
+
+def _split_keepalive(packet: bytes) -> tuple[bytes, Keepalive, bytes]:
+    if len(packet) != KEEPALIVE_SIZE:
+        raise DoorbellError("not a keepalive")
+    magic, kind, at = _HEAD.unpack_from(packet)
+    if magic != MAGIC or kind != KEEPALIVE:
+        raise DoorbellError("not a keepalive")
+    body = packet[:-_SIGNATURE]
+    thumbprint = _b64(body[_HEAD.size :])
+    return body, Keepalive(thumbprint, _when(at)), packet[-_SIGNATURE:]
+
+
+def read_keepalive(packet: bytes) -> Keepalive:
+    """The keepalive's claims, NOT verified: only to look the base up."""
+    return _split_keepalive(packet)[1]
+
+
+def verify_keepalive(packet: bytes, jwk: dict[str, Any], *, now: datetime) -> Keepalive:
+    """The keepalive, if the base key ``jwk`` signed it recently."""
+    body, heard, signature = _split_keepalive(packet)
+    try:
+        public = Ed25519PublicKey.from_public_bytes(_unb64(str(jwk.get("x", ""))))
+        public.verify(signature, body)
+    except (InvalidSignature, ValueError) as exc:
+        raise DoorbellError("bad signature") from exc
+    _check_time(int(heard.at.timestamp()), now)
+    return heard
+
+
+# --- Rings ----------------------------------------------------------------
+
+
+def new_ring_key() -> str:
+    """A fresh ring key (256 bits, base64url)."""
+    return _b64(secrets.token_bytes(32))
+
+
+def ring(ring_key: str, nonce: str, *, now: datetime) -> bytes:
+    """A ring carrying a Wake's ``nonce``, for the holder of ``ring_key``."""
+    raw = nonce.encode("ascii")
+    if not 0 < len(raw) <= MAX_NONCE:
+        raise ValueError("nonce must be 1..255 ASCII characters")
+    body = _HEAD.pack(MAGIC, RING, int(now.timestamp())) + bytes([len(raw)]) + raw
+    return body + hmac.new(_unb64(ring_key), body, hashlib.sha256).digest()
+
+
+def open_ring(ring_key: str, packet: bytes, *, now: datetime) -> str:
+    """The nonce a genuine, recent ring carries."""
+    if len(packet) < _HEAD.size + 1 + 1 + _MAC:
+        raise DoorbellError("not a ring")
+    magic, kind, at = _HEAD.unpack_from(packet)
+    length = packet[_HEAD.size]
+    if magic != MAGIC or kind != RING or len(packet) != _HEAD.size + 1 + length + _MAC:
+        raise DoorbellError("not a ring")
+    body, mac = packet[:-_MAC], packet[-_MAC:]
+    expected = hmac.new(_unb64(ring_key), body, hashlib.sha256).digest()
+    if not hmac.compare_digest(mac, expected):
+        raise DoorbellError("bad ring signature")
+    _check_time(at, now)
+    try:
+        return body[_HEAD.size + 1 :].decode("ascii")
+    except UnicodeDecodeError as exc:
+        raise DoorbellError("not a ring") from exc
+
+
+# --- The Doorbell server's HTTPS interface -------------------------------------
+
+
+@dataclass(frozen=True)
+class HeardKeepalive(Message):
+    packet: str
+    """The datagram, base64url (:func:`encode_packet`)."""
+    address: str
+    """The source IP it came from (the base's router)."""
+    port: int
+
+
+@dataclass(frozen=True)
+class KeepalivesReport(Message):
+    keepalives: list[HeardKeepalive] = dataclasses.field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class KeepalivesReply(Message):
+    results: list[str] = dataclasses.field(default_factory=list)
+    """One per reported keepalive, in order: ``KEEPALIVE_*``."""
+
+
+@dataclass(frozen=True)
+class Ring(Message):
+    address: str
+    port: int
+    packet: str
+    """Send this datagram (base64url) to ``address``:``port``, from the
+    socket the keepalives arrived on."""
+
+
+@dataclass(frozen=True)
+class Rings(Message):
+    rings: list[Ring] = dataclasses.field(default_factory=list)