matrix-org / matrix-org/matrix-spec

Push Notifications: Add Support for: VAPID / WebPush Subscriptions

Open
#1,752 0 comments 0 reactions 0 assignees View on GitHub
A-Push improvement
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

Problem:

Missing endpoint to retrieve public key to create VAPID subscription for WebPush

Context:

> The above diagram shows the flow of push notifications being sent to a handset where push notifications are submitted via the handset vendor, such as Apple’s APNS or Google’s GCM. This happens as follows:
>
> The client app signs in to a homeserver.
> The client app registers with its vendor’s Push Provider and obtains a routing token of some kind.
> The mobile app uses the Client/Server API to add a ‘pusher’, providing the URL of a specific Push Gateway which is configured for that application. It also provides the routing token it has acquired from the Push Provider.
> The homeserver starts sending HTTP requests to the Push Gateway using the supplied URL. The Push Gateway relays this notification to the Push Provider, passing the routing token along with any necessary private credentials the provider requires to send push notifications.

The Push Provider sends the notification to the device.

from: https://spec.matrix.org/v1.9/client-server-api/#push-notifications

The flow in the VAPID specification requires a endpoint to retrieve the server's public key:

> [4.1](https://www.rfc-editor.org/rfc/rfc8292.html#section-4.1). Creating a Restricted Push Message Subscription
>
> A user agent that wishes to create a restricted subscription includes
> the public key of the application server when requesting the creation
> of a push message subscription. This restricts use of the resulting
> subscription to application servers that are able to provide a valid
> JWT signed by the corresponding private key.
>
> The user agent then adds the public key to the request to create a
> push message subscription. The push message subscription request is
> extended to include a body. The body of the request is a JSON object
> as described in [[RFC7159](https://www.rfc-editor.org/rfc/rfc7159)]. The user agent adds a "vapid" member to
> this JSON object that contains a public key on the P-256 curve,
> encoded in the uncompressed form [[X9.62](https://www.rfc-editor.org/rfc/rfc8292.html#ref-X9.62)] and base64url encoded
> [[RFC7515](https://www.rfc-editor.org/rfc/rfc7515)]. The media type of the body is set to "application/
> webpush-options+json" (see [Section 6.3](https://www.rfc-editor.org/rfc/rfc8292.html#section-6.3) for registration of this media
> type).

https://www.rfc-editor.org/rfc/rfc8292.html#page-8

A public key is required by the browser to create a push subscription:
https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe#applicationserverkey
Matrix spec does not foresee a way to retrieve the public key from the server.

Proposal:

Introduce a public endpoint for key retrieval:

Request:
GET: /push/keys/public

Response: https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe#applicationserverkey

Contributor guide

Open the contributing guide

Research direction

Start with the Matrix Client-Server API push-notifications section and the proposed GET /push/keys/public endpoint, then read RFC 8292 and the linked PushManager documentation. Done requires a settled specification for the endpoint and its public-key response, including how it fits the VAPID subscription flow.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.