The push gateway is the Cloudflare Worker in infra/push-gateway. It
holds the APNs key and the Firebase service account, and turns deliveries signed by an environment
into pushes to a phone. It stores nothing: there is no database to provision or back up.
Push notifications explains who it trusts and why.
A gateway serves the app builds its keys can push to. An APNs key belongs to one Apple team and a Firebase service account to one project, so a gateway goes with one build of the mobile app, and building your own app means running your own gateway. This repository names no gateway. The maintainers' gateway serves only their builds, and its address is not here.
cd infra/push-gateway
cp .dev.vars.example .dev.vars # then fill it in
vp run dev- Wrap JSON values in
.dev.varsin single quotes. Double quotes with escapes do not parse. UNATTESTED_APP_IDSlets simulators and emulators register, since neither can attest.cf devreads only the secretscloudflare.config.tsdeclares, so a new setting is declared there before.dev.varscan supply it.- Local
workerdhas no HTTP/2 client, so APNs deliveries fail locally. FCM works. Test APNs against a deployed gateway.
Point a dev server at it with ONICODE_PUSH_GATEWAY_URLS=http://localhost:<port> and a dev build of
the mobile app with ONICODE_PUSH_GATEWAY_URL set to the same origin. Plain http is accepted for
localhost only.
The gateway takes its app ids, Apple team, and hostname from the same repository-root .env the
mobile build reads (.env.example), so the two cannot disagree. It serves
iOS when ONICODE_APPLE_TEAM_ID is set and Android when ONICODE_ANDROID_GOOGLE_SERVICES_FILE
is.
-
Collect the keys for the platforms you ship:
- iOS. Turn on Push Notifications and App Attest for the App ID, and create an APNs auth
key (
.p8) in the Apple developer account. One key covers every app of the team. - Android. Create a Firebase project, add an Android app with your package name, and
download its
google-services.json. Create a service account whose only permission iscloudmessaging.messages.createand download a JSON key for it. Note the SHA-256 of each certificate that signs a release: your upload key's fromkeytool -list -v -keystore <file>, and Play's from App integrity when Play App Signing re-signs the app.
- iOS. Turn on Push Notifications and App Attest for the App ID, and create an APNs auth
key (
-
Set
ONICODE_PUSH_GATEWAY_URLin.envto anhttpsorigin on a zone in your Cloudflare account. The deploy creates the DNS record and certificate for it. -
Write the secrets to a JSON file kept outside the repository:
Secret Value PUSH_SEALING_KEYS{"current":"k1","keys":{"k1":"<base64>"}}, each key fromopenssl rand -base64 32APNS_KEY_IDThe APNs auth key's id APNS_PRIVATE_KEYThat key's .p8contentsANDROID_APPS[{"packageName":"…","signingCertificateDigests":["<64 hex>"]}], the digests in lowercase without colonsFCM_SERVICE_ACCOUNTThe service account's JSON key The file's top level maps each name to a string, so the JSON values go in as strings. Leave out the secrets of a platform you do not ship. Keep a copy of the sealing key: without it every device has to register again.
-
vp exec cf auth loginonce, thenvp run deploy --secrets-file <file>frominfra/push-gateway. A deploy keeps the secrets the Worker already has, so later ones are plainvp run deployuntil a secret changes. -
Rebuild the mobile app, which now names the gateway, and put the same origin on the list of each environment that should deliver through it,
ONICODE_PUSH_GATEWAY_URLS. Set in.envwhen you build the desktop app or the server, it is baked in and every install of that build has it. A machine can also set it itself, inservice.envfor a background service. An environment refuses devices registered with a gateway that is not on its list; several origins are separated by commas.
Both of the gateway's callers are programs, not browsers. Bot Fight Mode challenges them, and on
the free plan it cannot be skipped for one hostname, so put the gateway on a zone that has it off.
workersDev and previewUrls stay off so the custom domain is the only way in.
ANDROID_BOOT_POLICY is verified by default. locked also admits a locked bootloader running a
user-signed OS, and any admits unlocked devices; either weakens the proof that your app
holds the key.
Add a key under a new id and make it current. Keep the old key in keys until everything it
sealed has expired, which takes 180 days, then remove it. Removing a key early signs every device
out of push until its app next opens.
vp exec cf workers secrets update PUSH_DISABLED --worker <name> --text true refuses every request.
vp exec cf workers secrets delete PUSH_DISABLED --worker <name> resumes. Devices and environments
keep their tokens, so nothing needs to register again.