hapi/relay/README.md

hapi-push-relay

The official HAPI push relay forwards end-to-end encrypted notifications from self-hosted hubs to APNs (iOS) and Firebase Cloud Messaging (Android).

Why it exists

Official apps belong to the maintainer's Apple team and Firebase project. The relay holds their sending credentials centrally. Users install the app, pair a current hub, and allow notifications; they do not need an Apple developer account, a Firebase project, or a service-account key.

Android hubs default to HAPI_ANDROID_PUSH=auto: an existing FCM_SERVICE_ACCOUNT_PATH keeps direct FCM; otherwise they use the relay. iOS defaults to HAPI_IOS_PUSH=relay; developers can choose direct apns. Push relay delivery is independent of the hub's --relay network tunnel.

Threat model and privacy

The relay sees ciphertext only. The notification content is encrypted by the hub with AES-256-GCM under a per-device key that only the hub and the device know. The relay, Apple and Google forward opaque bytes; the iOS Notification Service Extension decrypts locally on the device (mutable-content: 1 with a fixed placeholder alert of "HAPI / New activity" that the extension rewrites). Android decrypts in its FCM service before posting a local notification. What the relay can observe is metadata: the platform and device token, the connecting hub/proxy IP, request timing, and envelope size. It does not persist payloads in a database or log them. It does retain token/IP rate-limit state in bounded process memory, and log lines carry a platform-scoped token hash (first 12 hex chars of SHA-256), the outcome and duration. The hash can correlate events for a device; it is not complete anonymization. Container/proxy log retention depends on deployment settings, not this service's in-memory storage policy.

No client authentication, by design. Possession of a device token is the capability to submit a push, not to forge its contents. Device tokens are unguessable. Someone who obtains one can consume its rate-limit budget and trigger iOS generic alerts, but cannot encrypt valid content without the AES key. Android drops undecryptable messages; iOS keeps its generic placeholder. Requiring accounts would force self-hosters to register with the relay, which is exactly what HAPI avoids. Mitigations instead:

• per-device-token rate limit: 30 pushes/minute (token bucket, burst 30)
• per-client-IP rate limit: 300 pushes/minute (token bucket, burst 300)
• envelope size cap: 3200 bytes (base64 as transmitted), plus a 64 KB cap on the whole request body
• rate-limit state is in-memory and bounded (LRU-pruned), no persistence; entries have no fixed expiry and may remain until eviction or restart

API

POST /v1/push

{
    "platform": "ios",
    "token": "<hex APNs device token>",
    "envelope": "<standard base64, ≤ 3200 bytes>",
    "collapseId": "optional, truncated to 64 bytes",
    "priority": 10
}

priority is optional (5 or 10, default 10). collapseId is optional and becomes apns-collapse-id for iOS; it is ignored for Android.

The relay forwards to POST /3/device/<token> over HTTP/2 with an ES256 provider-token JWT (cached, re-signed after 45 minutes), apns-push-type: alert, apns-expiration: 0, and the body:

{"aps":{"mutable-content":1,"alert":{"title":"HAPI","body":"New activity"},"sound":"default"},"hapi":{"v":1,"e":"<envelope>"}}

For Android use platform: "android" and an opaque, case-sensitive FCM token (non-empty printable ASCII, at most 4096 bytes). The envelope and priority fields have the same format. The relay calls FCM HTTP v1 for its configured project, using cached OAuth credentials and the following data-only message:

{"message":{"token":"<FCM token>","data":{"hapi_v":"1","hapi_e":"<envelope>"},"android":{"priority":"HIGH","restricted_package_name":"run.hapi.companion"}}}

Priority 5 maps to NORMAL, 10 to HIGH. No notification or collapse_key is sent: Android must run the local decrypt/notification code, and FCM's four-collapse-key limit cannot represent arbitrary session IDs. The app coalesces displayed notifications locally. FCM's existing default TTL is retained. The relay does not queue or automatically retry sends.

Responses:

Status	Body	Meaning
200	{"ok":true}	accepted by APNs/FCM (not a device delivery receipt)
400	{"ok":false,"code":"bad_request"}	malformed request (plus a short message)
410	{"ok":false,"code":"unregistered"}	confirmed invalid token (APNs or FCM) — hub should drop this token
413	{"ok":false,"code":"too_large"}	envelope over 3200 bytes
429	{"ok":false,"code":"rate_limited"}	relay or provider rate limit hit — retry later
501	{"ok":false,"code":"unsupported_platform"}	requested platform has no configured provider
502	{"ok":false,"code":"upstream"}	provider/auth/network failure, including Firebase project mismatch

GET /health

{"status":"ok","service":"hapi-push-relay","version":"<version>"}

Running

From the repo root:

bun install
RELAY_APNS_KEY_P8_PATH=/path/AuthKey_XXXXXXXXXX.p8 \
RELAY_APNS_KEY_ID=XXXXXXXXXX \
RELAY_APNS_TEAM_ID=YYYYYYYYYY \
RELAY_APNS_BUNDLE_ID=run.hapi.app \
bun run relay/src/index.ts

Android-only startup (the service account must belong to the same Firebase project as the official app's google-services.json):

RELAY_FCM_SERVICE_ACCOUNT_PATH=/secrets/firebase-service-account.json \
bun run relay/src/index.ts

APNs and FCM are independently optional; configure at least one. A partial APNs configuration or unreadable/malformed configured key fails startup. Enable the Firebase Cloud Messaging HTTP v1 API and grant the relay's service account permission to send messages in that project. Never put the service-account JSON in the APK, repository, or user hub configuration.

Environment

Variable	Required	Default	Notes
RELAY_APNS_KEY_P8_PATH	for iOS	—	path to the APNs auth key (.p8, PKCS#8 PEM)
RELAY_APNS_KEY_ID	for iOS	—	key id from the Apple developer portal
RELAY_APNS_TEAM_ID	for iOS	—	Apple developer team id
RELAY_APNS_BUNDLE_ID	for iOS	—	iOS app bundle id (apns-topic)
RELAY_APNS_ENV	no	production	production or sandbox
RELAY_FCM_SERVICE_ACCOUNT_PATH	for Android	—	service-account JSON with project_id, client_email, private_key
RELAY_FCM_PACKAGE_NAME	no	run.hapi.companion	restrict FCM sends to this Android application ID
RELAY_PORT	no	8790	listen port
RELAY_TRUST_PROXY	no	off	1/true: rate-limit by first x-forwarded-for hop. Only behind a proxy that overwrites the header.

Deploying

Any container host works — the relay is a single stateless process (rate limits are in-memory, so run one instance, which is plenty: it only moves ~4 KB messages).

Use the prebuilt image ghcr.io/tiann/hapi-push-relay, available for Linux AMD64 and ARM64. The server needs only Docker and the provider keys/configuration; no HAPI source checkout or Bun installation is required.

docker pull ghcr.io/tiann/hapi-push-relay:latest
docker run -d --name hapi-push-relay --restart unless-stopped \
    -p 127.0.0.1:8790:8790 \
    -v /secrets/AuthKey_XXXXXXXXXX.p8:/keys/apns.p8:ro \
    -v /secrets/firebase-service-account.json:/keys/fcm.json:ro \
    -e RELAY_FCM_SERVICE_ACCOUNT_PATH=/keys/fcm.json \
    -e RELAY_APNS_KEY_P8_PATH=/keys/apns.p8 \
    -e RELAY_APNS_KEY_ID=XXXXXXXXXX \
    -e RELAY_APNS_TEAM_ID=YYYYYYYYYY \
    -e RELAY_APNS_BUNDLE_ID=run.hapi.app \
    -e RELAY_APNS_ENV=production \
    ghcr.io/tiann/hapi-push-relay:latest

The mounted .p8 and service-account files must be readable by the container's bun user (UID 1000). Use production for TestFlight/App Store and sandbox for development-signed apps. For a pinned deployment, replace latest with a published sha-<full-commit-sha> tag or image digest from the workflow output.

Terminate TLS in front of it (for example, Caddy on the same host) — hubs POST envelopes over the public internet. If the proxy overwrites X-Forwarded-For and is the only way in, set RELAY_TRUST_PROXY=1 so per-IP rate limiting sees real client IPs. The example exposes HTTP on host loopback only.

For deployment alongside tunwg on the same server, use the tunwg + Caddy + Push Compose example. It shares public TCP 443 and preserves client IPs for rate limiting.

Check readiness with curl -fsS http://127.0.0.1:8790/health. This checks the service, not provider authorization or device delivery. Verify an iOS and an Android notification using the official builds before releasing the hub and app updates. Deploy relay first, then hub, then Android. Watch logs for upstream/rate-limited results and monitor FCM quota usage in Google Cloud. FCM itself is no-cost, subject to project/device quotas; relay hosting and bandwidth are separate costs.

Publishing images

The Push Relay Image workflow runs the relay type check and tests, then builds both architectures. Pushes to main affecting relay/, the workflow, or its dependency/type-check inputs publish latest and sha-<full-commit-sha>. Pull requests build without publishing. To publish manually, run Actions → Push Relay Image → Run workflow on main; dispatches on other branches only validate and build.

Publishing uses the repository's GITHUB_TOKEN with packages: write; no registry credential needs to be added. After the first successful run, set the hapi-push-relay package visibility to Public in GitHub Packages so servers can pull without logging in. Forks publish under their own owner.

For local development, building from source remains available from the repo root:

docker build -t hapi-push-relay:local relay/

Pointing a hub at the relay

Both platforms default to https://push.hapi.run; override with HAPI_PUSH_RELAY_URL=https://push.example.com. The existing persisted key iosPushRelayUrl supplies this shared URL. Select HAPI_ANDROID_PUSH=relay to override local Firebase credentials, fcm for direct Android/Wear, or off to disable it. A configured but broken private Firebase account never falls back to the official project. Select HAPI_IOS_PUSH=apns for direct iOS delivery or off to disable iOS push.

The common hub client lives in hub/src/push-native/. Android relay delivery requires an upgraded phone client that registers pushKey; old phone and Wear clients continue to work with direct FCM. A hub selects one Android project/transport, so private-project builds and official-project builds cannot be mixed on that hub.

Implementation notes

• HTTP/2 to APNs uses Bun's node:http2 client — verified working on Bun 1.3.14 against a real node:http2 mock server (the test suite exercises the full wire shape, including collapse-id truncation and error mapping). The transport sits behind the ApnsClient interface in src/apns.ts so it can be swapped if a Bun upgrade ever regresses.
• The ES256 JWT signing (jose) is deliberately duplicated with the hub's APNs client: the relay must stay standalone and never import hub code.
• Run the tests with bun test from relay/, or bun run test:relay from the repo root.