feat(pusher): add validated onion delegation for v2 pings

- Load WELIST_PING_DELEGATION_FILE into a typed OnionDelegation
- Send the certificate only with v2 pings for onion hosts
- Validate the onion host, expiry and delegated key against
  BAL_SERVER_URL and SSL_KEY_PATH at startup; disable delegation
  with a warning on any mismatch
- Stop sending unsigned info/base_fee/version with v1 pings so
  v1 remains liveness-only
- Document v1/v2 metadata handling and onion delegation implications
- Add contrib/make_onion_delegation.py to issue certificates offline,
  with Ed25519 key validation and clean CLI error handling

docs/04_modules_detail.md

@@ -195,21 +195,34 @@ This is the async daemon that monitors the blockchain and pushes pending transac
 - The `WELIST_SERVER_URL` is validated via `is_valid_welist_url()` before sending (can be bypassed with `WELIST_SKIP_URL_VALIDATION=true`).
 - `WELIST_PING_SIG_VERSION` selects the signature scheme:
   - `1` (default): legacy concatenation of URL, chain, height, median time and
-    block hash. The WeTime service verifies it against `/.pub_key.pem`.
+    block hash. The WeTime service verifies it against `/.pub_key.pem`. The
+    signature authenticates liveness only: the pusher does not send `info`,
+    `base_fee` or `version`, and the service refreshes `last_update` without
+    persisting executor metadata. Use v2 when metadata must be published and
+    authenticated.
   - `2`: canonical JSON signed with the `WELIST-PING-V2\n` prefix. The pusher
     fetches `info`, `base_fee` and `version` from the local
     `/{chain}/info` endpoint and signs them together with the block metadata.
     The WeTime service discovers the public key from a DNSSEC-validated
     `_welist-key.<host>` TXT record or from a v3 onion address, so no HTTP
     callback is needed. The `url` is trimmed of trailing slashes to match the
-    service-side normalization; absent metadata is signed as `null`.
-- `bal-pusher.sh` sets `WELIST_PING_SIG_VERSION=2` for the development setup;
-  remove that line to fall back to the legacy scheme.
+    service-side normalization; absent metadata is signed as `null`. When
+    onion delegation is configured, the pusher verifies at startup that the
+    certificate is bound to the configured onion host, has not expired, and
+    delegates to the key at `SSL_KEY_PATH`.
+- `bal-pusher.sh` pins `WELIST_PING_SIG_VERSION=1` for the development setup:
+  a `localhost` URL cannot use DNSSEC, so the dev pusher uses the legacy
+  scheme verified against `/.pub_key.pem`. v2 requires a public DNS hostname
+  or a v3 onion address.
 - To publish the v2 public key, derive the base64 SubjectPublicKeyInfo DER:
   `openssl pkey -in private_key.pem -pubout -outform DER | base64 -w0` and
   publish it in a DNSSEC-signed TXT record named `_welist-key.<host>` with value
   `v=we1; alg=ed25519; key=<base64>`. A v3 onion URL needs no DNS record: its
-  Ed25519 identity key is embedded in the address.
+  Ed25519 identity key is embedded in the address, and the recommended setup
+  keeps that key offline while it certifies a dedicated ping key
+  (`WELIST_PING_DELEGATION_FILE`). See
+  [`10_dnssec_key_publishing.md`](10_dnssec_key_publishing.md) for the full
+  operator guide.
 
 ### ZMQ Timeout Handling
 - Uses `set_rcvtimeo(5000)` (5-second timeout).

docs/05_api_reference.md

@@ -168,13 +168,32 @@ scheme is selected with `WELIST_PING_SIG_VERSION`:
    `_welist-key.<host>` TXT record (`v=we1; alg=ed25519; key=<base64 SPKI DER>`)
    or from a v3 `.onion` address. No HTTP callback to `/.pub_key.pem` is made.
 
+For `.onion` URLs the pusher includes a `delegation` object when
+`WELIST_PING_DELEGATION_FILE` is set. The onion identity key signs that
+certificate offline; `SSL_KEY_PATH` is then the dedicated ping key, and the
+service verifies the certificate before checking the ping signature. The
+pusher validates the certificate at startup: `onion` must match the configured
+host, `valid_until` must be in the future, and `key` must match `SSL_KEY_PATH`.
+If the file is missing or malformed, or any check fails, the pusher logs a
+warning and sends no `delegation` object. It then signs with `SSL_KEY_PATH`
+directly, which works only when that key is the onion identity key.
+
 The `url` is trimmed of surrounding whitespace and trailing slashes, and the
 `chain` is lowercase, matching the service-side canonicalization.
 
+See [`10_dnssec_key_publishing.md`](10_dnssec_key_publishing.md) for the
+operator guide on publishing `_welist-key.<host>` and on onion delegation.
+
 ### Version 1 (legacy)
 
 1. Concatenates `url + chain + height + median_time + last_block_hash`.
 2. Signs that string with the Ed25519 private key.
-3. POSTs the fields plus the base64 signature to `{WELIST_SERVER_URL}/ping`.
+3. POSTs those five fields plus the base64 signature to
+   `{WELIST_SERVER_URL}/ping`. No `info`, `base_fee` or `version` is sent.
 4. The `welist` server verifies the signature with the public key served at
-   `GET /.pub_key.pem`; this scheme only refreshes `last_update`.
+   `GET /.pub_key.pem`.
+5. The v1 signature authenticates only liveness. The service refreshes
+   `last_update` for an accepted ping but does not persist executor metadata.
+   Because any metadata added to a v1 ping would be outside the signature, use
+   v2 when `info`, `base_fee` and `version` must be published and
+   authenticated.

docs/07_deployment_and_ops.md

@@ -70,6 +70,7 @@ the handler (including request body reading) exceeds the limit.
 | `WELIST_SERVER_URL` | `"https://welist.bitcoin-after.life"` | URL to POST signed stats to (validated against SSRF) |
 | `WELIST_SKIP_URL_VALIDATION` | `false` | Bypass SSRF URL validation (for testing only) |
 | `WELIST_PING_SIG_VERSION` | `1` | WeTime ping signature scheme: `1` (legacy) or `2` (canonical JSON) |
+| `WELIST_PING_DELEGATION_FILE` | unset | Onion only: JSON delegation certificate issued by the onion identity key |
 
 #### Per-Network Settings
 

docs/10_dnssec_key_publishing.md

@@ -0,0 +1,560 @@
+# DNSSEC-authenticated WeTime pings (v2)
+
+This document explains how to publish the Ed25519 public key used by the
+`bal-pusher` v2 WeTime ping and how to verify that the record is usable.
+
+In v2 the WeTime service discovers the executor public key from:
+
+- a DNSSEC-validated TXT record at `_welist-key.<host>`, or
+- the Ed25519 identity key embedded in a v3 `.onion` address, or a dedicated
+  ping key delegated by that identity key.
+
+This guide covers the DNS TXT record. Onion authentication needs no DNS record
+and should use delegation so the onion identity key stays offline (see
+[Onion URLs](#onion-urls)). For local development no record is needed either
+(see [Local development](#local-development)).
+
+All values below use `we.example.com` as a placeholder for the hostname in
+`BAL_SERVER_URL`. Replace it with your real executor hostname.
+
+---
+
+## 1. Choose the hostname
+
+Use the public hostname that clients use to reach your executor:
+
+```text
+BAL_SERVER_URL=https://we.example.com
+```
+
+The DNS key is published at:
+
+```text
+_welist-key.we.example.com
+```
+
+Rules:
+
+- Use a DNS hostname, not an IP address. The service rejects v2 pings whose URL
+  host is an IP address with `v2 DNS lookup requires a hostname`.
+- Use the host only: no scheme, port, path, or trailing slash.
+- The record must exist at exactly `_welist-key.<host>`. CNAME answers are
+  rejected by the service.
+
+---
+
+## 2. Generate or confirm the Ed25519 key pair
+
+The pusher signs with the private key at `SSL_KEY_PATH`. The TXT record must
+contain the matching public key.
+
+> **The pusher and the bal-server use two separate settings.** `SSL_KEY_PATH`
+> is the private key used for signing; `BAL_SERVER_PUB_KEY_PATH` is the public
+> key served at `/.pub_key.pem` and used by the legacy v1 scheme (and by the
+> check in section 7). Configure both with the same key pair.
+
+If you already have a key pair for the executor, reuse it. Do not generate a
+new pair for `SSL_KEY_PATH` alone: the legacy v1 signature is verified against
+`/.pub_key.pem`, so a split pair breaks v1 authentication and makes the
+section 7 check fail.
+
+> **Onion hosts:** do not point `SSL_KEY_PATH` at the onion identity key. Use a
+> separate ping key and issue a delegation certificate (see
+> [Onion URLs](#onion-urls)). The identity key is only needed offline, once, to
+> sign that certificate.
+
+If you do not have a key pair yet:
+
+```bash
+openssl genpkey -algorithm ED25519 -out private_key.pem
+openssl pkey -in private_key.pem -pubout -out public_key.pem
+chmod 600 private_key.pem
+```
+
+Then point both settings at the new pair and restart `bal-server` and
+`bal-pusher`:
+
+```bash
+export SSL_KEY_PATH="/absolute/path/to/private_key.pem"
+export BAL_SERVER_PUB_KEY_PATH="/absolute/path/to/public_key.pem"
+```
+
+Keep `private_key.pem` private and outside version control. The TXT record only
+contains the public key.
+
+---
+
+## 3. Build the TXT value
+
+Derive the base64 SubjectPublicKeyInfo (SPKI) DER from the private key:
+
+```bash
+KEY=$(openssl pkey -in private_key.pem -pubout -outform DER | base64 -w0)
+echo "v=we1; alg=ed25519; key=$KEY"
+```
+
+On platforms where `base64 -w0` is unavailable (for example macOS):
+
+```bash
+KEY=$(openssl pkey -in private_key.pem -pubout -outform DER | base64 | tr -d '\n')
+echo "v=we1; alg=ed25519; key=$KEY"
+```
+
+The value has this form:
+
+```text
+v=we1; alg=ed25519; key=MCowBQYDK2VwAyEA...
+```
+
+Notes:
+
+- `key` is the base64 of the **full SPKI DER**, not a hash and not the PEM text.
+  It is the same base64 body that appears in `public_key.pem`.
+- Use standard base64 (`+`, `/`, `=` padding), not base64url.
+- Ed25519 SPKI DER is 44 bytes, so the base64 value is about 60 characters and
+  the whole TXT string is about 90 characters. It fits in a single TXT string.
+- If a DNS provider splits the value into multiple quoted strings, that is
+  acceptable: the resolver concatenates TXT chunks before parsing.
+
+---
+
+## 4. Enable DNSSEC
+
+The service validates DNSSEC and **fails closed**. An unsigned or bogus answer
+is rejected; there is no unauthenticated fallback.
+
+Enabling DNSSEC normally requires two steps:
+
+1. Enable DNSSEC signing for the zone at the DNS provider.
+2. Publish the provider's **DS record** at the registrar or parent zone.
+
+The whole chain from the root to the zone that contains
+`_welist-key.we.example.com` must be signed.
+
+### Verify DNSSEC
+
+```bash
+dig +short DS example.com
+dig +dnssec DNSKEY example.com
+dig +dnssec TXT _welist-key.we.example.com
+```
+
+Look for `RRSIG` records in the answers. A validating resolver also sets the
+`ad` flag:
+
+```text
+;; flags: qr rd ra ad; QUERY: 1, ANSWER: 2, ...
+```
+
+If `dig` does not show `ad`, your local resolver may not validate. Use a
+validating tool instead:
+
+```bash
+delv TXT _welist-key.we.example.com
+```
+
+or:
+
+```bash
+kdig +dnssec TXT _welist-key.we.example.com
+```
+
+### Resolver used by the WeTime service
+
+The service performs its own validation with a built-in root trust anchor. The
+upstream resolver only needs to return DNSSEC records.
+
+If the service host uses a stub resolver that strips DNSSEC data, point it at a
+DNSSEC-capable resolver:
+
+```bash
+export WELIST_DNS_NAMESERVERS=1.1.1.1,9.9.9.9
+```
+
+`WELIST_DNS_NAMESERVERS` replaces the system resolver configuration; each entry
+is an `IP` or `IP:PORT` (default port 53).
+
+You can also point at a custom trust anchor file:
+
+```bash
+export WELIST_DNSSEC_TRUST_ANCHOR=/path/to/root.key
+```
+
+### Local development
+
+DNSSEC cannot authenticate `localhost` or an IP address. For local development
+use the legacy scheme and let the service verify the published public key:
+
+- Keep `WELIST_PING_SIG_VERSION` unset (or `1`), so the pusher signs with
+  `SSL_KEY_PATH` and the service verifies against `GET /.pub_key.pem`.
+- Start the service with `WELIST_ALLOW_LEGACY_PING=true` and, for loopback or
+  private addresses, `WELIST_ALLOW_LOCALHOST_PING=true`.
+
+No TXT record and no DNSSEC setup are required in this case.
+
+---
+
+## 5. Publish the TXT record
+
+| Field | Value |
+|-------|-------|
+| Name | `_welist-key.we.example.com` |
+| Type | `TXT` |
+| Value | `v=we1; alg=ed25519; key=<base64 SPKI DER>` |
+| TTL | `300` to `3600` seconds |
+
+The WeTime service caches DNS keys for the TXT TTL, clamped to 60–86400
+seconds. A TTL of `300`–`3600` keeps rotation reasonably fast.
+
+### BIND / generic zone file
+
+```zone
+_welist-key.we.example.com. 3600 IN TXT "v=we1; alg=ed25519; key=MCowBQYDK2VwAyEA..."
+```
+
+Reload or re-sign the zone after adding the record. If you use inline signing,
+the record is signed automatically. If you sign offline, re-run your signing
+step and publish the new signed zone.
+
+### Cloudflare
+
+1. Enable DNSSEC in the Cloudflare dashboard.
+2. Add the DS record shown by Cloudflare at your registrar.
+3. Create the TXT record:
+
+- Type: `TXT`
+- Name: `_welist-key.we` (Cloudflare appends the zone name)
+- Content: `v=we1; alg=ed25519; key=MCowBQYDK2VwAyEA...`
+- TTL: `Auto` or `1h`
+
+Cloudflare proxying applies to HTTP records, not TXT. The TXT record is served
+directly, so DNSSEC validation works normally.
+
+### Route 53
+
+1. Enable DNSSEC signing for the hosted zone.
+2. Add the resulting DS record at the registrar or parent zone.
+3. Create the record:
+
+- Record name: `_welist-key.we.example.com`
+- Record type: `TXT`
+- Value: `"v=we1; alg=ed25519; key=MCowBQYDK2VwAyEA..."`
+- TTL: `3600`
+
+Route 53 may split long TXT values into quoted chunks. That is supported.
+
+### Important
+
+- Do not create a CNAME for `_welist-key`. The service rejects CNAME answers.
+- Do not put the private key, a hash, or PEM headers in the TXT value.
+- If you need to host the record in another zone, use a proper DNSSEC-signed
+  delegation (NS + DS), not a CNAME.
+
+---
+
+## 6. Configure the pusher
+
+Set these variables in the pusher environment (for local development,
+`bal-pusher.sh`):
+
+```bash
+export SSL_KEY_PATH="/absolute/path/to/private_key.pem"
+export BAL_SERVER_URL="https://we.example.com"
+export WELIST_PING_SIG_VERSION=2
+```
+
+- `SSL_KEY_PATH` must point to the private key matching the published TXT key.
+- `BAL_SERVER_URL` must be the public DNS hostname. The pusher normalizes it by
+  trimming whitespace and trailing slashes before signing.
+- `WELIST_PING_SIG_VERSION=2` activates the canonical JSON signature. Leaving it
+  unset (or `1`) keeps the legacy v1 scheme, which the service rejects unless
+  `WELIST_ALLOW_LEGACY_PING=true`.
+
+For onion hosts, also configure the delegation certificate (see
+[Onion URLs](#onion-urls)):
+
+```bash
+export SSL_KEY_PATH="/absolute/path/to/ping_private_key.pem"
+export WELIST_PING_DELEGATION_FILE="/absolute/path/to/onion-delegation.json"
+export BAL_SERVER_URL="http://<address>.onion"
+```
+
+- `SSL_KEY_PATH` is the **dedicated ping key**, not the onion identity key.
+- `WELIST_PING_DELEGATION_FILE` is optional. When set, its JSON certificate is
+  sent only with onion pings. The pusher validates it at startup: `onion` must
+  match `BAL_SERVER_URL`, `valid_until` must be in the future, and `key` must
+  match `SSL_KEY_PATH`. If the file is missing or malformed, or any check
+  fails, it logs a warning and disables delegation, then signs with
+  `SSL_KEY_PATH` directly. That fallback works only when `SSL_KEY_PATH` is the
+  onion identity key; otherwise the service rejects the pings until the
+  certificate or key is corrected.
+
+Restart the pusher after changing the key or environment.
+
+With v2, the pusher also fetches `info`, `base_fee`, and `version` from the
+local `/{chain}/info` endpoint and signs those values. If the fetch fails, the
+fields are signed as `null`; the ping is still valid. Metadata is also signed
+as `null` when it fails validation:
+
+- `info` longer than 4096 bytes, or empty;
+- `version` longer than 64 bytes, or empty;
+- `base_fee` negative.
+
+For `.onion` URLs the pusher skips the fetch entirely (it cannot reach its own
+onion address without a Tor proxy), so those fields are always `null`.
+
+---
+
+## 7. Verify the published key
+
+Query the record and extract the `key=` field (this also joins TXT chunks and
+drops the quotes the resolver adds):
+
+```bash
+dig +short TXT _welist-key.we.example.com | tr -d '" ' | sed 's/^.*key=//'
+```
+
+Compare it with the local public key:
+
+```bash
+openssl pkey -in private_key.pem -pubout -outform DER | base64 -w0
+```
+
+The two commands must print the same base64 string.
+
+Optionally check that the legacy `/.pub_key.pem` endpoint serves the same key:
+
+```bash
+curl -s https://we.example.com/.pub_key.pem \
+  | openssl pkey -pubin -outform DER \
+  | base64 -w0
+```
+
+This third check is only meaningful when `BAL_SERVER_PUB_KEY_PATH` and
+`SSL_KEY_PATH` reference the same key pair, which is the recommended setup. The
+endpoint serves whatever `BAL_SERVER_PUB_KEY_PATH` points at; if the two
+settings use different pairs, compare the TXT record with `SSL_KEY_PATH` only.
+
+---
+
+## 8. Test a v2 ping
+
+Wait for the next block, or restart the pusher. With trace logging enabled you
+should see:
+
+```text
+canonical message to be sent: WELIST-PING-V2\n{"base_fee":...
+Report to welist(...) status=200 body="ok"
+```
+
+The WeTime service should log `PING ADDED` and refresh the executor's
+`last_update`. After a valid v2 ping, signed `info`, `base_fee`, and `version`
+values are persisted.
+
+A response of `"ko"` means the signature was rejected. Check the service logs
+for the specific `PING REJECTED` reason.
+
+---
+
+## 9. Key rotation
+
+Multiple TXT records are supported and any one of them can verify a signature.
+To rotate without downtime:
+
+1. Publish the new public key as an additional TXT record.
+2. Switch `SSL_KEY_PATH` to the new private key and restart the pusher.
+3. Wait at least the old TXT TTL, and no more than the 86400-second cache cap.
+4. Remove the old TXT record.
+
+The service stores a key only after it verifies a signature, so an invalid DNS
+answer cannot poison the cache. A refreshed TXT answer replaces the cached v2
+keys for that host.
+
+---
+
+## 10. Troubleshooting
+
+| Service log | Cause | Fix |
+|-------------|-------|-----|
+| `no TXT records` | Wrong record name or not propagated | Query `_welist-key.<host>` exactly |
+| `zone is not DNSSEC-signed` | DNSSEC not enabled or DS missing | Enable DNSSEC and publish the DS record |
+| `DNSSEC validation failed` | Expired/bogus signatures, clock skew, broken chain | Check with `delv` or a DNSSEC debugger |
+| `DNSSEC status is indeterminate` | Upstream resolver strips DNSSEC data | Set `WELIST_DNS_NAMESERVERS` to a capable resolver |
+| `dns unavailable` | Resolver unreachable or invalid configuration | Check `WELIST_DNS_NAMESERVERS` and `WELIST_DNSSEC_TRUST_ANCHOR` |
+| `CNAME answers are not accepted` | `_welist-key` is an alias | Publish a real TXT record |
+| `malformed record` | Wrong version, algorithm, or syntax | Use `v=we1; alg=ed25519; key=...` |
+| `invalid key` | Not a base64 Ed25519 SPKI DER | Regenerate with the `openssl` command above |
+| `v2 DNS lookup requires a hostname` | `BAL_SERVER_URL` uses an IP address | Use a DNS hostname |
+| `invalid v2 signature` | Key mismatch or non-canonical URL | Ensure the TXT key matches `SSL_KEY_PATH` and the URL has no trailing slash |
+| `invalid onion delegation` | Certificate signature does not verify against the onion identity key | Re-issue the certificate with the correct onion key; do not edit `key`/`valid_until` after signing |
+| `delegation does not match the ping onion host` | `onion` field differs from `BAL_SERVER_URL` | Re-issue the certificate for the exact host |
+| `delegation expired` | `valid_until` is in the past | Re-issue the certificate and restart the pusher |
+| `delegation is only supported for onion hosts` | `delegation` sent with a DNS URL | Unset `WELIST_PING_DELEGATION_FILE` for DNS hosts |
+| `legacy ping disabled` | v1 ping sent while the service requires v2 | Set `WELIST_PING_SIG_VERSION=2` (or enable legacy on the service) |
+
+Useful diagnostics:
+
+```bash
+dig +dnssec TXT _welist-key.we.example.com
+delv TXT _welist-key.we.example.com
+dig +trace +dnssec TXT _welist-key.we.example.com
+```
+
+---
+
+## Onion URLs
+
+A v3 `.onion` address embeds the service's Ed25519 identity key, so no TXT
+record is needed. The recommended design keeps that identity key **offline** and
+delegates ping signing to a dedicated, rotatable key:
+
+- `ping_private_key.pem` (`SSL_KEY_PATH`) signs every v2 ping.
+- The onion identity key signs a delegation certificate once.
+- Each onion ping carries the certificate in a `delegation` object.
+- The WeTime service verifies the certificate against the onion address, then
+  verifies the ping signature with the delegated key.
+
+Without a `delegation` object the service still accepts pings signed directly by
+the onion identity key. That fallback exists for compatibility; it requires the
+identity key to be online and should not be used for new deployments.
+
+The ping `url` must itself use the `.onion` host. The `onion_url` database field
+is display-only and does not affect authentication.
+
+### Certificate format
+
+The request carries:
+
+```json
+{
+  "onion": "<address>.onion",
+  "key": "<base64 SPKI DER of the delegated Ed25519 key>",
+  "valid_until": 1767225600,
+  "signature": "<base64 Ed25519 signature by the onion identity key>"
+}
+```
+
+The identity signature covers exactly:
+
+```text
+WELIST-PING-DELEGATION-V1\n{"key":"...","onion":"...","valid_until":1767225600}
+```
+
+Rules enforced by the service:
+
+- `onion` must exactly equal the ping URL host (lowercase, no trailing dot).
+- `valid_until` is a Unix timestamp in seconds and must be in the future.
+- `key` must be a valid Ed25519 SubjectPublicKeyInfo DER in standard base64.
+- The identity signature must verify against the key embedded in the onion
+  address.
+- A present but invalid, expired, or mismatched certificate is rejected; the
+  service does not fall back to the identity key.
+- `delegation` is rejected on non-onion hosts.
+
+### Issue the certificate
+
+Create a dedicated ping key pair:
+
+```bash
+openssl genpkey -algorithm ED25519 -out ping_private_key.pem
+chmod 600 ping_private_key.pem
+```
+
+Use the bundled helper with your onion key. It accepts either a Tor
+`hs_ed25519_secret_key` file or a standard PKCS#8 PEM Ed25519 key:
+
+```bash
+export ONION="<address>.onion"
+export ONION_KEY="/var/lib/tor/hidden_service/hs_ed25519_secret_key"
+
+contrib/make_onion_delegation.py \
+  --onion "$ONION" \
+  --identity-key "$ONION_KEY" \
+  --ping-key /etc/bal/ping_private_key.pem \
+  --days 365 \
+  --out /etc/bal/onion-delegation.json
+```
+
+For Tor-format keys the helper needs Python `cryptography` and `pynacl`:
+
+```bash
+pip install cryptography pynacl
+```
+
+If the onion identity key is a PKCS#8 PEM file, point `--identity-key` at it and
+`pynacl` is not needed. Run this step on a machine that holds the identity key
+(ideally offline), then copy only `onion-delegation.json` and
+`ping_private_key.pem` to the executor. The certificate contains public data;
+the ping private key must remain secret.
+
+### Configure the pusher
+
+```bash
+export SSL_KEY_PATH="/etc/bal/ping_private_key.pem"
+export WELIST_PING_DELEGATION_FILE="/etc/bal/onion-delegation.json"
+export BAL_SERVER_URL="http://<address>.onion"
+export WELIST_PING_SIG_VERSION=2
+```
+
+The pusher sends `delegation` only when `BAL_SERVER_URL` is an `.onion` host. It
+validates the certificate at startup against the onion host, its expiry, and
+`SSL_KEY_PATH`. If the file is missing or malformed, or validation fails,
+delegation is disabled and the pusher signs with `SSL_KEY_PATH` directly; that
+works only when `SSL_KEY_PATH` is the onion identity key.
+
+For local development, the `WELIST_ALLOW_LOCALHOST_PING` and legacy v1 notes
+above still apply; delegation itself needs no network access.
+
+### Rotation
+
+1. Generate a new `ping_private_key.pem`.
+2. Re-run `contrib/make_onion_delegation.py` with the new key and a new
+   `valid_until`.
+3. Replace `onion-delegation.json` and `SSL_KEY_PATH` on the executor.
+4. Restart the pusher.
+
+The onion address does not change, and the identity key stays offline. There is
+no DNS cache to wait for; the service checks the certificate on every ping.
+
+### Security notes
+
+- Delegation limits the blast radius: a compromised online ping key forges
+  pings only until rotation, not the onion service identity.
+- A long `valid_until` increases the impact of a leaked delegated key. Prefer
+  one year or less and rotate before expiry.
+- The onion identity key should never be copied to the executor.
+
+### Metadata for onion pings
+
+The pusher cannot fetch its own `.onion` endpoint without a Tor proxy, so
+`info`, `base_fee`, and `version` are signed as `null` for onion pings.
+
+With `WELIST_PING_SIG_VERSION=1` the pusher sends no metadata at all. The v1
+signature covers only the legacy liveness concatenation (`url`, `chain`,
+`height`, `median_time`, `last_block_hash`), and the WeTime service refreshes
+`last_update` without persisting `info`, `base_fee`, or `version`. Unsigned
+metadata is therefore not published. Use v2 when executor metadata must be
+authenticated and stored.
+
+---
+
+## Minimal checklist
+
+- [ ] Ed25519 key pair generated; `private_key.pem` is `chmod 600`.
+- [ ] `SSL_KEY_PATH` and `BAL_SERVER_PUB_KEY_PATH` use the same key pair.
+- [ ] TXT value built from `openssl pkey ... -outform DER | base64 -w0`.
+- [ ] TXT record `_welist-key.<host>` published, not a CNAME.
+- [ ] Zone DNSSEC-signed and DS published at the registrar.
+- [ ] `dig +dnssec` / `delv` shows a validated answer.
+- [ ] `BAL_SERVER_URL` is the public DNS hostname.
+- [ ] `WELIST_PING_SIG_VERSION=2` is set.
+- [ ] Pusher restarted and reports `body="ok"`.
+
+For onion hosts, replace the TXT/DNSSEC items with:
+
+- [ ] A dedicated `ping_private_key.pem` exists and is `chmod 600`.
+- [ ] `onion-delegation.json` was issued offline by the onion identity key.
+- [ ] `SSL_KEY_PATH` points at the delegated ping key, not the identity key.
+- [ ] `WELIST_PING_DELEGATION_FILE` points at the certificate.
+- [ ] `valid_until` is in the future and rotation is scheduled.
+- [ ] Pusher restarted and reports `body="ok"`.

docs/INDEX.md

@@ -8,6 +8,7 @@
 - **I am a security auditor** → Go straight to [`08_security_audit.md`](08_security_audit.md)
 - **I am deploying or operating this software** → Check [`07_deployment_and_ops.md`](07_deployment_and_ops.md)
 - **I need to integrate with the API** → Reference [`05_api_reference.md`](05_api_reference.md)
+- **I need to publish the v2 WeTime public key or delegate onion ping signing** → Follow [`10_dnssec_key_publishing.md`](10_dnssec_key_publishing.md)
 - **I need to understand the database** → Use [`06_database_schema.md`](06_database_schema.md)
 - **I need to understand Bitcoin concepts** → See [`02_glossary_and_bitcoin_domain.md`](02_glossary_and_bitcoin_domain.md)
 - **I need source code references or external links** → Check [`09_references_and_links.md`](09_references_and_links.md)
@@ -25,6 +26,7 @@
 | 7 | [`07_deployment_and_ops.md`](07_deployment_and_ops.md) | Environment variables, systemd, nginx, scripts, Tor, installation |
 | 8 | [`08_security_audit.md`](08_security_audit.md) | Threat model, vulnerability assessment, hardening recommendations |
 | 9 | [`09_references_and_links.md`](09_references_and_links.md) | Source code links, Cargo dependencies, existing file mapping |
+| 10 | [`10_dnssec_key_publishing.md`](10_dnssec_key_publishing.md) | Publishing the v2 WeTime key via DNSSEC TXT, v3 onion identity, or delegated onion ping key |
 
 ---