--- a/mod_web_push/README.markdown Sat Jun 08 23:06:44 2019 +0200
+++ b/mod_web_push/README.markdown Sun Jun 09 22:02:24 2019 +0200
@@ -14,7 +14,8 @@
:::
This is an implementation of the server bits of [XEP-XXXX: Web Push].
-It allows clients to register a "push server" which is notified about new
+
+It allows web clients to register a "push server" which is notified about new
messages while the user is offline, disconnected or the session is hibernated
by [mod_smacks].
@@ -22,6 +23,37 @@
This module is heavily based on [mod_cloud_notify].
+Details
+=======
+
+[Push API](https://w3c.github.io/push-api/) is a specification by the W3C that
+is essentially the same principle as Mobile OS vendors' Push notification
+systems. It is implemented by most browsers vendors except Safari on iOS
+(mobile).
+
+For more information, see:
+- https://developer.mozilla.org/en-US/docs/Web/API/Push_API
+- https://developers.google.com/web/ilt/pwa/introduction-to-push-notifications
+
+Compared to [XEP-0357: Push Notifications], Web Push doesn't need an App
+Server.
+
+The general flow for subscription is:
+- XMPP server generate ECDH keypair, publishes public key
+- XMPP client generates an ECDH keypair
+- XMPP client fetches server public key
+- XMPP client subscribes to browser Push server using the Web Push API, and
+ gets back an HTTP endpoint
+- XMPP client enables Push notifications telling the server the HTTP endpoint,
+ and its public key
+
+The flow for notifications is as follow:
+- XMPP server receives an _important_[^1] message
+- XMPP server generates something something JWT + signature with ECDH key
+- XMPP server can optionally include payload encrypted for the client
+- XMPP server initiates HTTP POST request to the Push server
+- Push server sends notification to web browser
+
Configuration
=============
@@ -43,3 +75,5 @@
=============
Configured in-band by supporting clients.
+
+[^1]: As defined in mod_cloud_notify, or mod_csi_simple.