Repository navigation
Releases
Releases · MBombeck/healthlog-push
v1.0.3
Added
- The GitHub release carries SLSA v1.0 provenance for the Linux binaries and
SHA256SUMS,
healthlog-push_vX.Y.Z.intoto.jsonl, signed by the SLSA generic generator (v2.1.0). It checks with
slsa-verifier verify-artifact. The image signature, its SBOM and its provenance, and what the deployment
role verifies, do not change. - Two gauges on the local metrics listener:
hlp_instances{tier}(probation, standard, suspended, revoked)
andhlp_bindings{state}(provisional, active, soft_invalid), the same sums as theinstancesand
bindingsblocks ofadmin stats. Every label of the closed sets is present on every scrape, zero
included, and the values pass through the same coarse snapshot as the other metrics. An operator can now
chart registrations and binding states without polling the admin socket. - Operational counters about the relay's own work, every label from a closed set fixed in the code:
hlp_apns_sends_total{kind}(alert, silent_sync, silent_wake for the relay's challenge push, la_start,
la_update, la_end),hlp_delivery_latency_seconds(a histogram without labels from acceptance to Apple's
answer, six buckets from 0.1 s to 5 s),hlp_apns_rejections_total{reason}(Apple's reason codes, anything
unknown asother),hlp_liveactivity_priority_total{priority},hlp_push_retries_total{answer},
hlp_queue_depth,hlp_silent_budget_refused_total{kind}(sync, wake),
hlp_deliveries_by_key_slot_total{slot}(current, next, emergency, unpinned),
hlp_registrations_rejected_total{reason}(no_invite, bad_signature, rate_limited) and
hlp_rate_limited_total{surface}. Nothing describes an instance beyond the existing counts, and the values
pass through the same coarse snapshot. docs/transparency.mdlists every metric the relay exposes, with its labels and the reason it exists, and
states how long the hosted relay's monitoring keeps them. A test fails when the code registers a metric the
table does not list, and another when a series carries a label or a value outside the fixed allowlist.
Changed
- The privacy notice (now version 1.2; the consent text version stays
2026-11-21) states that Hetzner
Online GmbH hosts the relay as a processor under a data processing agreement (Art. 28 GDPR), concluded on
2026-11-22. Until now it said only that such an agreement was available. - The README is reorganised around what the relay is, how the privacy works, what the operator can see,
the hosted relay, self-hosting, verifying a release and security. The limits, the identity keys and the
verification commands are unchanged. docs/release-verification.mddescribes how the build pipeline is protected as it is: every action pinned
to a commit, with the SLSA generator as the one tag-pinned exception and the reason for it, the tag
ruleset, and why GitHub's immutable releases stay off.SECURITY.mdgains the same in short and a section
on verifying a release.- Only the first job of the release workflow names the
releaseenvironment, which accepts onlyv*
tags; every other job depends on that job. The environment has no required reviewer. - The hardening statement, the key ceremony and the Ansible examples no longer name the server model, the
exact reboot time, an example host name or the layout of the secret store. - golangci-lint also runs
contextcheckandunparam. The admin socket listener and the shutdown derive
their contexts from the process context; queued sends keep their own context on purpose, because they
outlive the request that queued them.
Image: ghcr.io/mbombeck/healthlog-push:v1.0.3
Digest: sha256:adcfcd9bbda9bc18ca6917491079f87417b54ea1ac00d94e8a67fc7e0e73bb10
v1.0.2
Security
admin recovery --fromread the export from any path the relay process could open; through the admin
socket that is root on the host anyway, but the reader now accepts only a file inside the export directory
(HLP_EXPORT_DIR), as a relative name or an absolute path under it, throughos.Root, so..and
symbolic links cannot leave it. Code scanning alertgo/path-injectionis closed by this change, not
suppressed. The import at start readsregistry.jsonfrom the same directory as before.
Changed
- Live Activity pushes go to Apple with
apns-priority: 10only for the end and for a start or update whose
statusisdueoroverdue; every other state (pending,snoozed,taken,skipped) goes with 5.
iOS grants each device an hourly budget of priority 10 Live Activity pushes and may throttle beyond it,
and priority 5 does not count against it, so routine changes no longer use up the budget a due dose
needs. The relay decides from the checked content state; nothing in the API changes. - A
410from Apple whosetimestamplies before the UTC day the binding was made or renewed (with 10
minutes of tolerance) no longer deletes the binding. Apple confirmed the old registration gone, and the
device has registered the token again since. The item answers200 soft_invalidwithreason
Unregistered, the binding is marked, and the same answer on a later day deletes it. A410without a
timestamp, or one at or after the binding day, deletes as before.
Added
- Delivery traces: for a push to a development build, Apple returns
apns-unique-id. The relay keeps it
with the item result in memory for 72 hours (at most 50,000 traces, keyed by instance id andref), and
admin delivery <instance-id> <ref>shows it, so one lost push can be looked up in Apple's delivery log.
Traces are never stored, exported, logged or counted; production pushes have none. The retention is in
docs/privacy.md(now version 1.1; the consent text version stays2026-11-21) and
docs/operations.md. - A third identity key for the hosted relay,
emergency(dcrihMfqGY7srT95DZrVP7sKA-IS3oJPPhOVbbqTvBU), inkeys/push.healthlog.dev.jsonand the
README. It is kept offline, apart fromcurrentandnext, never deployed, and promoted only if both are
lost;docs/key-ceremony.mdhas the procedure. The relay keeps signing withcurrent. docs/transparency.md: authority requests (none so far), how a request is handled, and a dated feed of
deprecations and key rotations. Identity key rotations are announced there at least 7 days ahead. Linked
from the README, the privacy notice and the threat model.- Tests for the provider token path (
FileTokens), which had none, for the Live Activity priorities, the
410 timestamp and the delivery traces.
Documentation
- The threat model states as an accepted limit that the silent intake sync goes out at once after a dose
is recorded, so Apple and the relay can see that time: preventing a double dose is chosen over hiding it. - The privacy notice (1.1), the terms (1.1, terms version unchanged) and the README state the operator's
commitment: the relay only carries what a registered server sends to its own bound devices, and the
operator never sends anything through it. - The README lists the hosted identity keys once; the second, stale table is gone.
- The README no longer repeats what the relay sees; it points to
docs/privacy.md, the single source.
The test vectors (spec/vectors/v1.json) are unchanged.
Image: ghcr.io/mbombeck/healthlog-push:v1.0.2
Digest: sha256:4831ad443bb5f46c0dbc8074d5a232c763d8aa8dde4e04e121638e153fff9352
v1.0.1
Security
- A new store no longer starts with open registration. Until the first
admin registrationcommand, a fresh
relay accepted registrations from anyone for as long as it took the operator to close it. The relay now
takes its mode fromHLP_REGISTRATION_MODE(invitewhen unset, alsoclosedoropen), stores it and
only then accepts requests. A mode stored withadmin registrationwins over the variable, so a restart
never reopens what an operator closed. A value other thanopen,inviteorclosedstops the relay at
start. - AppArmor profiles for both containers in
deploy/apparmor/: the relay reads only its own secrets, writes only
/data,/acme,/exportand the refresh marker and has no capability; the signer has no network and
writes only the provider token. They are opt-in throughHLP_APPARMOR_RELAYandHLP_APPARMOR_SIGNER
(Docker'sdocker-defaultotherwise); the Ansible role takeshealthlog_push_apparmor_relayand
healthlog_push_apparmor_signer, installs the profiles of the release with
healthlog_push_apparmor_install, refuses a profile the kernel has not loaded in enforce mode, and checks
after the start that each container runs under its profile.
Changed
- The SLSA provenance is now SLSA v1 (
slsaprovenance1), signed by the reusable workflow
.github/workflows/provenance.ymlwith GitHub'sattest-build-provenanceand stored as a Sigstore bundle
next to the signature and the SBOM. cosign 3 verifies all three without format flags. The provenance of
v1.0.0 came from the SLSA generator in the older.attformat, which cosign 3 finds only with
--new-bundle-format=false; docs/release-verification.md has the commands for both. - The Ansible role verifies the provenance with the new identity and type and pins cosign v3.1.4 with the
SHA-256 of the amd64 and arm64 binaries in its defaults. Releases before v1.0.1 do not pass the new
provenance step; deploy them with the role of their own tag. HLP_REGISTRATION_MODEis passed by the compose file (defaultinvite) and rendered by the role from
healthlog_push_registration_mode.
Updating
- A store on which no mode was ever set (the relay answered
openwithout having stored it) now starts in
invite. To keep accepting registrations from anyone, runadmin registration openonce.
Image: ghcr.io/mbombeck/healthlog-push:v1.0.1
Digest: sha256:d34605307d3e5cd1ba2de671fdf3ac14913853a122ccdc6b2acdab8413fa77d2
v1.0.0
First release.
Added
- One binary with the subcommands
relay,signer,admin,keygen,healthcheckandversion. - Relay API: instance registration with proof of possession, key rotation and deletion
(/v1/instances), device bindings with a device-signed statement (/v1/bindings), conflict resolution
by a challenge push (/v1/bindings/challenge), the direct opt-out and self-read for the app
(/v1/bindings/self), the Live Activity consent (/v1/bindings/liveactivity) and its direct withdrawal
(/v1/bindings/self/liveactivity), batched pushes of up to 50 items (/v1/push), envelope receipt counts
(/v1/receipts) and the instance status (/v1/status). - Ed25519 request signatures with a 300-second window, nonce replay protection and refusal of time stamps
from before the relay started; every/v1response,/healthzand/versionsigned with the relay
identity key (hl-relay-resp-v2) and bound to the request method, path and nonce. - Fixed APNs payload templates for alert, silent and Live Activity start, update and end; envelopes are checked for version,
suite, class and exact length and never opened. Envelopes exist for alert and silent only; the Live
Activity class byte0x03is reserved and the vectors carry no envelope of that class. - Direct opt-out with a device-only return: the pair stays blocked against the instance, and only a later
bind statement by the same binding key with a higherseq, signed after the opt-out and after the relay
start, lifts the block. The binding key that opted out is pinned to the token for 365 days (bucket
optout_pins): while the token is unbound, a binding with any other key, also by a newly registered
instance, is409 binding_conflictwith a challenge push that only the device can answer. - Live Activity start and update over the relay (
activity.eventstart,updateorend,endwhen
absent), only with the device's second, separate Live Activity consent: signed by the binding key
(hl-la-consent-v1), passed on by the instance withPOST /v1/bindings/liveactivity, dropped by it with
DELETE /v1/bindings/liveactivity, withdrawn by the device directly with
DELETE /v1/bindings/self/liveactivity(hl-la-withdraw-v1). The consent version and day are stored with
the binding, returned by the self-read (liveActivityConsentVersion,liveActivityConsentDay) and kept on
a rebind by the same key to the same instance. Without it a start or update answers
403 liveactivity_consent_required. - A closed content state for start and update, forwarded in the clear:
status(pending,due,
overdue,snoozed,taken,skipped),countdownTarget(0or one day back to two days ahead of the
relay clock),isOverdue,confirmed,pendingConfirmandtimeFormatRaw(AUTO,H12,H24), all
required and nothing else; a start names the fixed attributes typeHealthLogDoseAttributeswith
{"v":1}and a fixed localized alert. A start is signed over the push-to-start token (hl-la-start-v1, at
most 30 days old); an update or end over the update token (hl-activity-v1, at most 12 hours old). - Live Activity limits: 12 starts per device and day, 12 updates per activity and hour and 48 per day
(429 device_quota, scopeactivity), 12 ends per device and day. Metrics
hlp_bindings_total{result="liveactivity_consent"}and{result="liveactivity_consent_withdrawn"}. - Fixed shapes, with vectors, for the
DATA_CHANGED,HEALTHKIT_CATCH_UPandSECURITY_ALERTplaintexts
(spec/envelope.md, "Types with a fixed shape"). - Signer process without network access that holds the APNs key and writes an ES256 provider token to a
shared tmpfs every 30 minutes, or on request at most every 20 minutes. - Per-instance, per-device, per-tier and relay-wide limits, registration limits by IPv4 address and IPv6
/64 and /48 (salted daily, in memory), a connection limiter, a fair in-memory send queue with admission
control and idempotency by(instance, ref)for 10 minutes. - Token-failure circuit breaker: when more than 30 % of at least 20 sends to established bindings in five
minutes fail with a token error, from at least three instances, no binding is deleted or marked until
Apple accepts again. - Only
Unregisteredfrom Apple deletes a binding;BadDeviceTokenandDeviceTokenNotForTopicmark it
soft-invalid and delete it on a second hit on another day. - Handling of Apple's provider token errors and throttling: refresh on an expired token, a 20-minute pause
on too many token updates, a full stop on a rejected renewed token, per-device back-off on
TooManyRequests, and a relay-wide 15-minute silent pause when Apple throttles more than 2 % of sends. - bbolt storage with day and week granularity only, token MACs instead of tokens, retention and pruning,
a consistency check at start and daily, a daily registry export (healthlog-push-registry-v2: instances
with tier and reason, opt-out blocks, opt-out pins and token blocks) signed with the relay identity key
(hl-relay-export-v1), automatic recovery from a damaged or missing database with a 14-day recovery
window, and MAC key rotation with a previous key. - Probation tier with automatic promotion after seven days, a delivered push and no anomaly; automatic
device limit raise for quiet, well-used standard instances. - Operator commands over a unix socket:
stats,instance,pause,resume,registration,invite,
notice,suspend,unsuspend,revoke,block-token,unblock-token,limits,recovery,
export,breaker,status-fileandsuspects. - Usage statistics as counts only (completed days and weeks) in
admin statsand ashlp_usage_*metrics. /healthzwithstatus,db_writable,apns_recent,breakeranddelivery, the last derived from the
receipt counts instances report.statusdepends only on the relay's own facts.- JSON logging with a closed set of keys and no instance ids, tokens or addresses; HTTP server error lines
counted and discarded. Metrics without instance labels on127.0.0.1:9464, refreshed hourly while fewer
than 20 instances are active. - TLS 1.3 with certificates from Let's Encrypt over TLS-ALPN-01, or certificate files.
- Privacy notice and terms served at
/privacyand/terms, and/.well-known/security.txt(RFC 9116). - Compose file with two hardened containers and an Ansible deployment that verifies the cosign signature and
SLSA provenance before starting a digest-pinned image, gates on health and rolls back. - Release workflow with multi-arch images, keyless signatures, SBOM attestation, SLSA provenance and signed
checksums for static binaries. - Protocol specification and test vectors under
spec/, fuzz targets for every parser, structural tests
for logging, address handling, cryptography imports, payload templates and deletion paths.
Security
- Response signatures (
hl-relay-resp-v2) cover host, method, raw path with query, nonce, status and body
hash.HL-Nonceis mandatory on every/v1request, registration and the app's direct calls included;
without it the relay answers400 nonce_required. Clients take retry hints only from the signed body,
capped at one day, and refuse response bodies over 256 KiB; the relay never sends more than 64 KiB. - Instance requests are checked for a known instance and a valid time stamp from the headers before the
body is read. The signature is always verified; the per-instance budget for failed signatures only limits
how often failures are counted, so forged requests can no longer lock an instance out. POSTandDELETEmust declareContent-Length(411 length_required); bodies above 128 KiB are
refused before reading, bodies in flight are capped at 32 MiB in total (503 overloaded), HTTP/2
connections allow 16 concurrent streams, and the relay container runs withGOMEMLIMIT=220MiB.- The app endpoints verify first and charge only failed attempts to the global bucket; verified calls are
limited per device token (10, refilling 10 per hour,429 device_quota). Junk traffic can no longer block
a device's opt-out. - The breaker counts only sends to bindings that have had an accepted push and opens only with failures from
at least three instances. A soft-invalid binding gets one probe push per day. Over its invalid-token budget
an instance gets no pushes to provisional or soft-invalid bindings for 24 hours. - Receipts count only for
standardinstances, at most once per 45 minutes each, withacceptedcapped at
what the relay accepted for that instance in the last three days. - TLS 1.2 is offered only to a handshake whose only ALPN protocol is
acme-tls/1. - During a recovery window the global registration caps are ten times higher instead of lifted; per-address
caps still apply. Only instances from the export keep their tier; any other key registers in probation. - The challenge answer checks that the instance is still active and applies its binding quotas; a binding
made through a challenge counts againstnewBindingsPerDay. Challenges are limited to one per token,
instance and day, so one instance cannot use up the challenge of another. - The seven-day direct replacement of a silent binding with a new key is allowed only to the instance that
holds the binding; every other instance needs the challenge. - The registry export is signed and checked on import: signature, host, and every instance inside the
closed sets (UUIDv4 id, 32-byte key, known tier and reason, device limit 1 to 150). Anything else fails the
whole import, and the relay does not start. An unsigned export is never written. - Suspension and revocation live in the instance record (tier, reason, reason day) and expire after 365 days;
there is no separate denylist. A revoked instance cannot be suspended, and a revocation is one
transaction. - The stored opt-out block hol...