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.

Copyright (C) 2021 The pushgarden Contributors