Solid WebPushSubscription2022

1. Introduction

This section is non-normative.

The Solid Notifications Protocol describes a general pattern by which agents can be notified when a Solid Resource changes.

This document describes a Solid Notifications subscription type that makes use of the Push API for Web Push notifications in Progressive Web Applications (PWAs).

This specification is for:

• Resource server developers who wish to enable clients, i.e., PWAs, to listen for updates to particular resources.

• Application developers who wish to implement a client, i.e., a PWA, to listen for updates to particular resources.

1.1. Terminology

This section is non-normative.

This document uses terminology from the [SOLID-NOTIFICATIONS] protocol, including "Notification Subscription API". The document uses terms from the [WEBSUB] specification, including "topic".

Note: Let the predicate topic be an rdfs:subClassOf of as:object?

The document further uses terms from [PUSH-API] specification, including "push endpoint", "push service" and "authentication secret". It also uses terms from [OAUTH-2.0] specification, including "authorization server" and "access token". In addition, the document uses terms from the [WEBARCH] specification, including "information resource".

This document uses the following terms as defined below:

subscription service

A subscription service is a service, which handles and manages subscriptions for resources stored on the corresponding Solid Storage.

The subscription service is identified by a URI. Dereferencing this URI yields the subscription service’s representation, a discription of the service. By this representation, information may be provided such as Notification Subscription APIs where subscriptions can be submitted for the service to process.

browser messaging service

Refers to the implementation of a "push service" [PUSH-API] in a browser.

1.2. Overview

The following diagram shows the high-level interactions involved in this flow. How a client retrieves an access token is outside the scope of this document.

• Discovery: The subscriber discovers from the storage metadata a suitable subscription service. It further discovers from the subscription service's representation a suitable Notification Subscription API to submit subscription requests to and the vapidPublicKey of the subscription service.
• Establish Subscription: The subscriber subscribes to the browser messaging service to receive Web Push notifications using the vapidPublicKey of the subscription service. In return, the subscriber retrieves the endpoint, auth and p256dh values. A corresponding subscription is submitted to the Notification Subscription API. The subscription service authenticates the subscriber with the Authorization Server, checks authorization of the subscriber and registers the subscription.
• Deliver Notifications: The subscription service issues Push notifications to the browser messaging serivce which in turn delivers the Push notification to the subscriber. For each notification, the subscription service checks the authorization of the subscriber with the Authorization Server.
• Cancel Subscription: When the subscriber chooses not to receive Web Push notifications anymore, it unsubscribes from the browser messaging service. Additionally, it sends an unsubscription request to the subscription service.

2. WebPushSubscription2022 Type

This specification defines the WebPushSubscription2022 type for use with Solid Notifications subscriptions. The URI of the subscription type is <http://www.w3.org/ns/solid/notification#WebPushSubscription2022>.

A WebPushSubscription2022 API MUST conform to the Solid Notifications Protocol.

A WebPushSubscription2022 API SHOULD support the Solid Notifications Features.

Note: Let the class WebPushSubscription2022 be an rdfs:subClassOf of as:Follow?

The WebPushSubscription2022 type defines the following properties:

vapidPublicKey

The vapidPublicKey property indicates the notification server’s public key as defined by [RFC8292], which can be used by the client for the Voluntary Application Server Identification (VAPID).

%% : object %% :: The object property indicates the information resource which the client would like to receive notifications about. %% The value of source property MUST be a URI, using the https scheme, and identifying an information resource.

%% Note: Let the predicate topic be an rdfs:subClassOf of as:object?

%% Issue(62):

endpoint

The endpoint property indicates the "Push Endpoint" as defined in the [PUSH-API] specification.

keys

The keys property indicates a "cryptographic keys object" that has the properties of auth and p256dh.

auth

The auth property indicates the "authentication secret" as defined in the [RFC8291] specifications.

p256dh

The p256dh property indicates the elliptic curve Diffie-Hellman (ECDH) public key as defined by [RFC8291].

A client establishes a subscription using the WebPushSubscription2022 type by sending an authenticated subscription request to the subscriptions service’s Notification Subscription API retrieved via [SOLID-NOTIFICATIONS] discovery. The client sends a HTTP POST request with a request body to the appropriate subscription resource’s Notification Subscription API. Required information in the request are type, topic, endpoint, keys with auth and p256dh.

If the subscription has been created successfully, the server responds to a client’s subscription request with HTTP status code 201 Created

2.1. Subscription Example

This section is non-normative.

An example POST request using a DPoP bound access token is below:

POST /subscribe/
Authorization: DPoP <token>
DPoP: <proof>
Content-Type: text/turtle

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix as: <https://www.w3.org/ns/activitystreams#> .
@prefix push: <https://purl.org/solid-web-push/vocab#> .
@prefix notify: <https://www.w3.org/ns/solid/notification#> .

<>  a notify:WebPushSubscription2022;
    notify:topic <https://uvdsl.solid.aifb.kit.edu/inbox/>;
    push:endpoint <https://fcm.googleapis.com/fcm/send/ezblK6NIv80:APA91bHrjqImGaqs5-kcIZ_zO72HVDHGfnrzi9xwJvSsHD3qu4js1nQfHvcjf1Fjgo3mpxBqMkFcqPdiaRPFXnYSkEf9yz78m9FFBaWzwIvmaQ8M1-2vxaAO3S-ha2jf7ALLqRP92Y9z>;
    push:keys   [
        push:auth "Z51Yn6DRglyzR6SpDYHkqw"^^xsd:base64Binary;
        push:p256dh "BNocq-WqQufNxY5NtFWz-ckbLoCprrHT74ALR-DXcpCoKmqV2cVflQ6ibyas-vJBMWMLeSDPdRBbJhcc0lDmJ5g"^^xsd:base64Binary
                ] .

A successful response will have a HTTP status code of 201 Created and no (meaningful) response body.

The Notification Subscription API, in our example /subscribe/, where the POST request is submitted to, is discovered from the subscription service's representation:

# available at <https://solid.aifb.kit.edu/web-push/service>
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix dc: <http://purl.org/dc/terms/>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix as: <https://www.w3.org/ns/activitystreams#>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix push: <https://purl.org/solid-web-push/vocab#>.
            
<> a as:Profile;
    rdfs:label "The profile of the Solid Web Push Service"@en;
    as:summary "The described resource is a Service called Solid Web Push. To subscribe to the service, post the subscription to the provided URI. The subscription must indicate which resource the subscriber whishes to receive updates on.";
    dc:creator <https://uvdsl.solid.aifb.kit.edu/profile/card#me>;
    as:describes <#web-push> .

<#web-push> a as:Service;
    as:name "Solid Web Push"@en;
    rdfs:label "Solid Web Push Service"@en;
    ldp:inbox <https://solid.aifb.kit.edu/web-push/subscribe/>; 
    push:vapidPublicKey "BAOxV1U1Hj5npToInct2VhhYpJkL0GmHqc-ADbHu7O8Z2CJNkqSzc8BfCStWbTKq_yT9B6g6kYjyEHrAEpVuqww"^^xsd:base64Binary.

Note: The representation includes the Notification Subscription API where subscriptions can be submitted via POST using ldp:inbox. Currently, it is not yet specified by [SOLID-NOTIFICATIONS] how the subscription service is modelled. To this end, the example is my suggestion.

For Unsubscription,

Note: When there is a decision reached, there will be an example included.

3. Authentication and Authorization

As described by the Solid Notifications Protocol section on Authorization, the WebPush subscription API requires authorization and follows the guidance of the Solid Protocol sections on Authentication and Authorization [SOLID-PROTOCOL].

It is beyond the scope of this document to describe how a client fetches an access token. Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications [SOLID-OIDC].