matrix-org / matrix-org/matrix-spec
Push Notifications: Add Support for: VAPID / WebPush Subscriptions
- 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
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