~emersion/pushgarden

#pushgarden

A Web Push gateway to proprietary services such as Firebase Messaging (FCM) and Apple Push Notification service (APNs).

      ┌────────────┐             ┌─────────────┐
      │            │  Subscribe  │             │
      │   Android  ├────────────►│ Application │
      │ IRC client │             │   Server    │
      │            │             │             │
      │            │             │             │
      └────────────┘             └──────┬──────┘
             ▲                          │
             │                          │
        Push │                          │Push
notification │                          │notification
             │                          ▼
       ┌─────┴─────┐             ┌─────────────┐
       │           │             │             │
       │ Firebase  │◄────────────┤  pushgarden │
       │ Messaging │ Push        │             │
       │           │ notification│             │
       └───────────┘             └─────────────┘

Web Push is defined in RFC 8030, RFC 8291 and RFC 8292.

#Usage

The payloads delivered to Firebase and APNs are encrypted and need to be decrypted on the client side. The decryption process is very similar to the encryption process.

#Firebase

Go to your project settings in the Firebase console, select the "Service accounts" tab, and download the private key as a JSON file. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a path to this file, then start pushgarden.

#APNs

Sign in to the Apple Developer dashboard, select the "Certificates, IDs, & Profiles" tab, and download the certificate. Set the APPLE_CERTIFICATE environment variable to a path to the certificate converted to PKCS#12 (.p12 file extension) without a password, then start pushgarden.

#Stateless endpoint

For simple use-cases, a stateless push endpoint is available.

For Firebase: POST /firebase/<project-id>/push?token=<token>. The <project-id> is visible in the project settings. The per-device <token> can be obtained from the Firebase SDK.
For APNs: POST /apple/<app-id>/<env>/push?token=<token>. The <app-id> is visible in the Apple Developer dashboard. <env> is either "development" or "production".

pushgarden will send a Firebase or APNs message with the following data:

payload: contains the encrypted request body.
endpoint: contains the request path.
vapid_key: if the request was signed with a VAPID key, contains the public key.
state: contains the state query parameter sent in the request, if any.

#Stateful endpoint

Alternatively, the stateful endpoint can be used by creating a subscription. This unlocks additional features and improved security:

Multiplexing via the endpoint field.
A VAPID public key can be specified. Unsigned requests and requests signed with another VAPID key will be rejected.
The <token> is not disclosed to push notification senders.
The subscription can be deleted as needed.

Currently, only Firebase supports the stateful endpoint.

To create a new subscription, send a request to POST /firebase/<project-id>/subscribe?token=<token>. pushgarden will return a unique push endpoint in a Link response header, for instance:

Link: </firebase/example-560a6/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>; rel="urn:ietf:params:push"
Location: /firebase/example-560a6/subscription/LBhhw0OohO-Wl4Oi971UG

A POST request to the push endpoint will deliver a new Firebase message (as explained in the previous section). A DELETE request on the subscription endpoint will cancel the subscription.

#License

AGPLv3, see LICENSE.

refs