webpush-subscription-2022.bs

<pre class='metadata'>
Title: Solid WebPushSubscription2022
Boilerplate: issues-index no
Shortname: solid-webpush-subscription-2022
Level: 1
Status: CG-DRAFT
Group: solidcg
ED: https://solid.github.io/notifications/webpush-subscription-2022
Repository: https://github.com/solid/notifications
Inline Github Issues: title
Markup Shorthands: markdown yes
Max ToC Depth: 2
Editor: [Christoph Braun](https://github.com/uvdsl)
!Version: 0.1
Abstract:
  The [[!SOLID-NOTIFICATIONS inline]] defines a set of interaction patterns for agents to establish subscriptions to resources in a Solid Storage.

  This specification defines a subscription type that applies these patterns to the [[!PUSH-API inline]].
</pre>

<div class="note">
This darft is based on a submission for [Web Push Notifications from Solid Pods](https://uvdsl.solid.aifb.kit.edu/conf/2022/icwe/demo).
<ul>
<li>The submission's server-side (Pod-side) code can be found [here](https://github.com/uvdsl/solid-web-push).</li>
<li>The submission's client-side (PWA-side) code can be found [here](https://github.com/uvdsl/solid-web-pwa).</li>
</ul>
DISCLAIMER: The submission and its implementation may become obsolete with progression of this draft.
</div>

# Introduction # {#introduction}

*This section is non-normative.*

The [[!SOLID-NOTIFICATIONS inline]] 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 inline]] 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.

## Terminology ## {#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".

Issue(62):

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.

Issue(63):

Issue(36):

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


## Overview ## {#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.

<figure>
  <img src="webpush-subscription-2022-flow.mmd.svg" rel="schema:image" width="800">
  <figcaption property="schema:name">Solid WebPushSubscription2022 Flow</figcaption>
</figure>

<ul>
<li> 
**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*.
</li>
<li> 
**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.
</li>
<li>
**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*.
</li>
<li>
**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*.
</li>
</ul>

<div class="advisement"> 
<b>
It is not yet specified by [[!SOLID-NOTIFICATIONS]], how unsubscription works. Depends on #36. 
</b>
<ul>
<li>
Option (1): `as:Undo` via HTTP POST to Notification Subscription API.
</li>
<li>
Option (2): HTTP DELETE on a subscription.
</li>
</ul>
</div>

# WebPushSubscription2022 Type # {#subscription-type}

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

A WebPushSubscription2022 API MUST conform to the [Solid Notifications Protocol](https://solid.github.io/notifications/protocol#discovery).

A WebPushSubscription2022 API SHOULD support the [Solid Notifications Features](https://solid.github.io/notifications/protocol#notification-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` 

Issue(36):



## Subscription Example ## {#example}

*This section is non-normative.*

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

<div class=example>
```http
POST /subscribe/
Authorization: DPoP <token>
DPoP: <proof>
Content-Type: text/turtle
```
```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
                ] .
```
Example: POST request creating a `WebPushSubscription2022` subscription.
</div>
%% Note: TODO check data types of `auth` and `p256dh`.

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:
<div class=example>
```turtle
# 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.
```
Example: Representation of a *subscription service*.
</div>

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,

<div class="advisement"> 
<b>
It is not yet specified by [[!SOLID-NOTIFICATIONS]], how unsubscription works. Depends on #36. 
</b>
<ul>
<li>
Option (1): `as:Undo` via HTTP POST to Notification Subscription API.
</li>
<li>
Option (2): HTTP DELETE on a subscription.
</li>
</ul>
</div>

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


# Authentication and Authorization # {#auth}

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]].


<pre class=biblio>
{
    "SOLID-PROTOCOL": {
        "authors": [
            "Sarven Capadisli",
            "Tim Berners-Lee",
            "Ruben Verborgh",
            "Kjetil Kjernsmo"
        ],
        "href": "https://solidproject.org/TR/protocol",
        "title": "Solid Protocol",
        "publisher": "W3C Solid Community Group"
    },
    "SOLID-NOTIFICATIONS": {
        "authors": [
            "Aaron Coburn",
            "Sarven Capadisli"
        ],
        "href": "https://solid.github.io/notifications/protocol",
        "title": "Solid Notifications Protocol",
        "publisher": "W3C Solid Community Group"
    },
    "SOLID-OIDC": {
        "authors": [
            "Aaron Coburn",
            "elf Pavlik",
            "Dmitri Zagidulin"
        ],
        "href": "https://solid.github.io/solid-oidc",
        "title": "Solid-OIDC",
        "publisher": "W3C Solid Community Group"
    },
     "PUSH-API": {
        "authors": [
            "Peter Beverloo", 
            "Martin Thomson"
        ],
        "href": "https://www.w3.org/TR/push-api/",
        "title": "Push API",
        "publisher": "W3C Web Applications Working Group"
    },
    "OAUTH-2.0": {
        "authors": [
            "D. Hardt"
        ],
        "href": "https://www.ietf.org/rfc/rfc6749.txt",
        "title": "The OAuth 2.0 Authorization Framework",
        "publisher": "Internet Engineering Task Force (IETF)"
    },
    "WEBSUB": {
        "authors": [
          "Julien Genestoux", 
          "Aaron Parecki"
        ],
        "href": "https://www.w3.org/TR/websub/",
        "title": "WebSub",
        "publisher": "W3C Social Web Working Group"
    },
      "WEBARCH": {
        "authors": [
          "Ian Jacobs",
          "Norman Walsh"
        ],
        "href": "https://www.w3.org/TR/webarch/",
        "title": "Architecture of the World Wide Web, Volume One",
        "publisher": "W3C Technical Architecture Group"
    },
    "RFC8291": {
        "authors": [
          "M. Thomson"
        ],
        "href": "https://www.ietf.org/rfc/rfc8291.txt",
        "title": "Message Encryption for Web Push",
        "publisher": "Internet Engineering Task Force (IETF)"
    },
    "RFC8292": {
        "authors": [
          "M. Thomson",
          "P. Beverloo"
        ],
        "href": "https://www.ietf.org/rfc/rfc8292.txt",
        "title": "Voluntary Application Server Identification (VAPID) for Web Push",
        "publisher": "Internet Engineering Task Force (IETF)"
    }
}
</pre>