Skip to content

Releases

v1.0.3

Choose a tag to compare

@github-actions github-actions released this 22 Nov 16:30
4c9b569

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)
    and hlp_bindings{state} (provisional, active, soft_invalid), the same sums as the instances and
    bindings blocks of admin 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 as other), 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.md lists 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.md describes 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.md gains the same in short and a section
    on verifying a release.
  • Only the first job of the release workflow names the release environment, which accepts only v*
    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 contextcheck and unparam. 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

Choose a tag to compare

@github-actions github-actions released this 22 Nov 10:40

Security

  • admin recovery --from read 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, through os.Root, so .. and
    symbolic links cannot leave it. Code scanning alert go/path-injection is closed by this change, not
    suppressed. The import at start reads registry.json from the same directory as before.

Changed

  • Live Activity pushes go to Apple with apns-priority: 10 only for the end and for a start or update whose
    status is due or overdue; 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 410 from Apple whose timestamp lies 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 answers 200 soft_invalid with reason
    Unregistered, the binding is marked, and the same answer on a later day deletes it. A 410 without 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 and ref), 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 stays 2026-11-21) and
    docs/operations.md.
  • A third identity key for the hosted relay, emergency (dcrihMfqGY7srT95DZrVP7sKA-IS3oJPPhOVbbqTvBU), in keys/push.healthlog.dev.json and the
    README. It is kept offline, apart from current and next, never deployed, and promoted only if both are
    lost; docs/key-ceremony.md has the procedure. The relay keeps signing with current.
  • 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

Choose a tag to compare

@github-actions github-actions released this 21 Nov 19:29

Security

  • A new store no longer starts with open registration. Until the first admin registration command, a fresh
    relay accepted registrations from anyone for as long as it took the operator to close it. The relay now
    takes its mode from HLP_REGISTRATION_MODE (invite when unset, also closed or open), stores it and
    only then accepts requests. A mode stored with admin registration wins over the variable, so a restart
    never reopens what an operator closed. A value other than open, invite or closed stops the relay at
    start.
  • AppArmor profiles for both containers in deploy/apparmor/: the relay reads only its own secrets, writes only
    /data, /acme, /export and the refresh marker and has no capability; the signer has no network and
    writes only the provider token. They are opt-in through HLP_APPARMOR_RELAY and HLP_APPARMOR_SIGNER
    (Docker's docker-default otherwise); the Ansible role takes healthlog_push_apparmor_relay and
    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.yml with GitHub's attest-build-provenance and 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 .att format, 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_MODE is passed by the compose file (default invite) and rendered by the role from
    healthlog_push_registration_mode.

Updating

  • A store on which no mode was ever set (the relay answered open without having stored it) now starts in
    invite. To keep accepting registrations from anyone, run admin registration open once.

Image: ghcr.io/mbombeck/healthlog-push:v1.0.1

Digest: sha256:d34605307d3e5cd1ba2de671fdf3ac14913853a122ccdc6b2acdab8413fa77d2

v1.0.0

Choose a tag to compare

@github-actions github-actions released this 21 Nov 18:24

First release.

Added

  • One binary with the subcommands relay, signer, admin, keygen, healthcheck and version.
  • 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 /v1 response, /healthz and /version signed 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 byte 0x03 is 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 higher seq, 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, is 409 binding_conflict with a challenge push that only the device can answer.
  • Live Activity start and update over the relay (activity.event start, update or end, end when
    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 with POST /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 (0 or one day back to two days ahead of the
    relay clock), isOverdue, confirmed, pendingConfirm and timeFormatRaw (AUTO, H12, H24), all
    required and nothing else; a start names the fixed attributes type HealthLogDoseAttributes with
    {"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, scope activity), 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_UP and SECURITY_ALERT plaintexts
    (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 Unregistered from Apple deletes a binding; BadDeviceToken and DeviceTokenNotForTopic mark 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-file and suspects.
  • Usage statistics as counts only (completed days and weeks) in admin stats and as hlp_usage_* metrics.
  • /healthz with status, db_writable, apns_recent, breaker and delivery, the last derived from the
    receipt counts instances report. status depends 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 on 127.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 /privacy and /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-Nonce is mandatory on every /v1 request, registration and the app's direct calls included;
    without it the relay answers 400 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.
  • POST and DELETE must declare Content-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 with GOMEMLIMIT=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 standard instances, at most once per 45 minutes each, with accepted capped 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 against newBindingsPerDay. 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...
Read more