docs(pusher): document v2 onion delegation and legacy ping defaults

- Correct WELIST_ALLOW_LEGACY_PING: legacy pings are accepted by default,
  the flag only disables them.
- Describe onion delegation: v2-only inclusion, service-side host
  normalization, strict expiry check, deployment order and rollback.
- Warn that disabled delegation rejects onion pings when SSL_KEY_PATH is
  the dedicated ping key.
- Document certificate lifetime and revocation limits, offline master
  key requirements, helper --days bounds, and a delegation verification
  checklist.
- Fix the bal-pusher.sh comment about the service-side defaults.
This commit is contained in:
2026-11-09 00:15:00 -04:00
parent 4af1ca8220
commit 78e4f72255
4 changed files with 127 additions and 42 deletions

View File

@@ -204,12 +204,15 @@ This is the async daemon that monitors the blockchain and pushes pending transac
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`. 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`.
`_welist-key.<host>` TXT record, from a v3 onion address, or from a ping key
delegated by that onion identity key, 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`. When onion delegation
is configured, the pusher sends the certificate only with v2 pings and
verifies at startup that it is bound to the configured onion host, has not
expired, and delegates to the key at `SSL_KEY_PATH`. If that check fails the
pusher disables delegation and signs directly, which the service rejects
unless `SSL_KEY_PATH` is the onion identity key.
- `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