Push notification relay for self-hosted Beacon servers. Apple and Google only
let an app's publisher send it push notifications, so a self-hosted
beacon-server cannot reach
the Beacon mobile app directly. beacon-push is the small service the Beacon
project runs at https://push.meshcorebeacon.ca that does it for them. Every
server, the project's own included, sends its push alerts through it.
beacon-server ──HTTPS──> beacon-push ──APNs──> iPhone
└──FCM───> Android phone
- A server operator registers at
https://push.meshcorebeacon.ca/registerand gets a Push ID and a Push secret. - The operator turns push on in beacon-server's config
(
alerts.push.enabled,alerts.push.id, andBEACON_PUSH_SECRET). - The Beacon app gets a device handle from the relay that only works for that server, and gives the handle to the server.
- When an alert fires, beacon-server encrypts it for that device and sends it to the relay, which forwards it straight to Apple's push service (APNs) for an iPhone, or through Firebase Cloud Messaging (FCM) for Android.
The relay attributes every notification to the server that sent it, puts the server's registered name on it, rate-limits each server and device, and keeps usage records (server, time, device handle, size, a hash of the ciphertext) for 30 days to catch abuse. Notification contents are end-to-end encrypted between beacon-server and the app; the relay cannot read them.
Apple sees the notifications that go to iPhones and Google sees the ones that go to Android phones, each with its device token and the encrypted payload. Neither sees the other platform's traffic.
- A verified email address is always required. Each email can register up to two servers. Disposable email domains are refused.
- A public URL is optional. If given, the relay checks it daily (see Domain check); a server that passes gets the higher tier.
| Tier | Requires | Per minute | Per day |
|---|---|---|---|
| verified email | 30 | 500 | |
| verified | email and a passing domain check | 300 | 10,000 |
| custom | set by an admin | as set | as set |
Every device also has its own limits: 10 notifications a minute and 200 a day.
All bodies are JSON, at most 512 KiB (a bigger one gets 413 too_large).
Errors look like {"error": {"code": "...", "message": "..."}}. A 429
carries Retry-After in seconds.
Authenticate with Authorization: Bearer <push id>.<push secret>.
POST /v1/hello, at startup and then hourly:
{ "pushId": "inst_7f3k2m9qxa", "name": "Ottawa Mesh", "status": "active", "tier": "email",
"limits": { "perMinute": 30, "perDay": 500, "perDevicePerDay": 200 },
"url": "https://beacon.example.org", "domainVerified": false, "termsOutdated": false, "devices": 12 }status is active or suspended. A banned server gets 403 banned.
POST /v1/send, with 1 to 100 messages:
{ "messages": [ { "handle": "h_…", "ciphertext": "<base64>", "collapseKey": "4711", "ttlSeconds": 86400,
"id": "1234:9b2c…" } ] }ciphertextis standard base64, at most 2,048 bytes once decoded.collapseKeyis optional, up to 40 ofA-Z a-z 0-9 _ - . :. The relay prefixes it with the Push ID, so a server only ever collapses its own notifications.ttlSecondsdefaults to one day and can be at most 28 days (2,419,200).idis optional, up to 64 ofA-Z a-z 0-9 _ - . :, and makes a retry safe. It is scoped to the sending server, and the relay remembers each id's outcome for at least 24 hours (30 days in practice). Repeating an id that was sent answersokwith the earliermessageIdand sends and counts nothing, even if the handle has gone or the relay is paused since. Repeating an id whose send is still under way, or whose outcome is unknown because the relay stopped mid-send, answersrate_limitedwithretryAfterSeconds: 30; after 2 minutes such a send counts as failed, its quota is given back (with or without an id) and the next repeat sends again. Repeating an id whose send failed sends again. beacon-server uses<outbox row id>:<device session uuid>.
The relay sends up to 8 messages of a batch at once and starts no new one
after 10 seconds; each message's whole send to APNs or FCM, token refresh
included, is limited to 10 seconds, so the answer comes within about 20 seconds. Items not started in time answer rate_limited with
retryAfterSeconds: 5.
The answer has one result per message, in order:
{"results": [{"messageId": "m_…", "status": "ok"}, {"status": "rate_limited", "retryAfterSeconds": 42}]}.
retryAfterSeconds (whole seconds, at least 1) comes with every
rate_limited result and with a failed one caused by an APNs or FCM outage. The
response's Retry-After header carries the largest wait in the batch, for
servers that do not read the field.
| status | Meaning | What the server does |
|---|---|---|
ok |
Handed to APNs or FCM | Mark delivered |
rate_limited |
Not sent: over a limit, the device's push service is paused after an outage, not started before the batch deadline, or an id still in flight |
Hold until retryAfterSeconds (else Retry-After); not an attempt |
invalid_handle |
Unknown, revoked, another server's, or the push service no longer knows the handle's current token (APNs 410, BadDeviceToken or DeviceTokenNotForTopic; FCM UNREGISTERED) |
Delete the device |
too_large, invalid |
Refused: a bad item, a payload over APNs' 4 KB, or the push service refused the message (APNs 400, FCM 400 INVALID_ARGUMENT) | Done for this notice, never resend |
failed |
Transient: the push service unreachable or another error from it (such as APNs IdleTimeout), the relay's own APNs or FCM credentials refused, the app refreshed or registered the device again while it was being sent, or the relay could not record a send the push service accepted |
Retry later; counts an attempt |
APNs and FCM are paused separately: an outage of one never holds back the
other. When APNs answers 5xx or FCM answers 500 or 503, the relay stops
sending through that service for its Retry-After, at most a day. Without
one it pauses a minute, doubling with each new outage up to an hour, until a
send through it succeeds after the pause has ended. That item is failed and
every later item for the same service is rate_limited until the pause ends.
A 429 for a device makes that item rate_limited, for the Retry-After the
service gave (a minute if it gives none, at most a day), and later items for
the same device wait, without reaching the service, until the longest wait
asked for that device ends. A message counts against the daily quotas while
it is being sent and stays counted only if the push service accepts it.
When APNs refuses the relay's provider token as expired or invalid, the relay
signs a new one and tries once more. If that fails too, the item is failed
and the relay logs an error: its APNs key needs attention.
A suspended server gets 403 suspended for the whole batch, and a banned one
403 banned. A batch waiting behind another from the same server checks the
server's status and quotas again before it starts, and each message checks
them again before it goes out.
POST /v1/verify-domain runs the domain check now:
{"domainVerified": true} or {"domainVerified": false, "reason": "..."}.
POST /v1/handles with
{"pushId", "platform": "ios"|"android", "token", "apnsEnvironment"}
answers 200 with {"handle", "handleSecret"}.
- On iOS,
tokenis the APNs device token in hex (64 to 200 characters, either case; stored lower-case), andapnsEnvironmentissandboxfor a development build orproductionfor TestFlight and App Store builds. - On Android,
tokenis the FCM registration token, up to 4,096 ofA-Z a-z 0-9 _ - :, andapnsEnvironmentmust be left out.
The same token on the same server keeps its handle and gets a new secret. Errors:
400 bad_platform:platformis notiosorandroid.400 bad_apns_environment: iOS withoutsandboxorproduction, or Android with anapnsEnvironment.400 bad_token:tokenis missing or malformed for the platform.404 unknown_server: no server has that Push ID.403 server_unavailable: the server is suspended or banned.
PUT /v1/handles/{handle} with {"handleSecret", "token", "apnsEnvironment"}
moves the handle to a refreshed token, and on iOS to the given environment,
which is required there as on POST. It answers 204, 400 bad_token or
400 bad_apns_environment.
DELETE /v1/handles/{handle} with {"handleSecret"} stops the handle. It
answers 204.
On PUT and DELETE, an unknown or revoked handle or a wrong secret gets
404 unknown_handle. Each address may create 20 handles an hour and make 60
updates and deletes an hour; past that it gets 429 rate_limited with
Retry-After.
The same fields on both platforms:
{ "v": "1", "pushId": "inst_…", "serverName": "Ottawa Mesh", "messageId": "m_…", "ct": "<base64 ciphertext>" }Android gets them as the data of a data-only, high-priority FCM message. iOS
gets them as top-level keys of the APNs payload, next to a placeholder alert
(title: the server name, body: "New alert") with mutable-content: 1, so the
Notification Service Extension decrypts the message and replaces the text.
The APNs request has apns-push-type: alert, apns-priority: 10, an
apns-expiration from ttlSeconds, and the collapse key as
apns-collapse-id (hashed when the prefixed key is over 64 bytes).
The relay requests
GET <registered url>/.well-known/beacon-push?challenge=<random> over
https, from a public address only, with no redirects, and gives up after a few
seconds. beacon-server answers:
{ "pushId": "inst_…", "mac": "<hex HMAC-SHA256(key = SHA-256(push secret), \"beacon-push-challenge:\" + pushId + \":\" + challenge)>" }A match proves that the host at that URL holds the Push secret.
The project runs the official instance, and the Beacon app only accepts notifications from it. Forks that ship their own app, Apple team and Firebase project can run their own; there's no support for that beyond this README.
The image is ghcr.io/meshcore-beacon/beacon-push. Configuration comes from
the environment: see .env.example. It needs:
- a Firebase service-account key file, mounted read-only, for Android;
- an APNs auth key (
.p8) from the Apple Developer account, mounted read-only, with its key ID, the team ID and the app's bundle ID (PUSH_APNS_KEY,PUSH_APNS_KEY_ID,PUSH_APNS_TEAM_ID,PUSH_APNS_TOPIC), for iOS. The key works for both the sandbox and production environments; each handle says which one its device uses. A key that cannot be read stops the relay at startup; - an SMTP account for registration mail;
- a volume at
/datafor the SQLite database. Back it up daily withbeacon-push admin backup /data/backup-$(date +%F).db(from cron throughdocker exec) and copy the file off the box.
Put it behind a TLS proxy such as Caddy, with PUSH_TRUST_PROXY=true.
docker exec beacon-push beacon-push admin list
docker exec beacon-push beacon-push admin show <push id>
docker exec beacon-push beacon-push admin suspend <push id>
docker exec beacon-push beacon-push admin unsuspend <push id>
docker exec beacon-push beacon-push admin ban <push id>
docker exec beacon-push beacon-push admin set-quota <push id> <per minute> <per day>
docker exec beacon-push beacon-push admin backup /data/backup.db
A server that addresses too many live device handles that aren't its own (50 in an hour, or more than 20% of at least 100 live handles in an hour) is suspended automatically, and the admin address gets a mail. Handles that don't exist or are revoked don't count either way. So does every new registration, a lost domain verification, and an email-tier server reaching 1,000 devices.
PUSH_DEV_MODE=true PUSH_PUBLIC_URL=http://localhost:8080 PUSH_DATABASE_PATH=./dev.db go run ./cmd/beacon-push
Dev mode logs mail (including registration links) and pushes instead of sending them.
Checks before pushing: go build ./... && go vet ./... && go test ./... and
gofmt -l ..
See CONTRIBUTING.md. All contributors are welcome; please also read the Code of Conduct. To report a security issue, see SECURITY.md.