documentation(push): Document the push flow and why the proxy is necessary

Signed-off-by: Joas Schilling <coding@schilljs.com>

docs/push-v2.md

@@ -1,5 +1,55 @@
 # Push notifications as a Nextcloud client device
 
+## Introduction
+
+> Why is push-notifications.nextcloud.com necessary?
+
+The Nextcloud mobile apps from the Google Playstore and Apple App Store are signed with Nextcloud developer keys or certificates.
+Push notifications sent to those devices need to be signed with a generated push key or certificate from the same developer account.
+The keys and certificates can not be shipped with the Nextcloud server as otherwise everyone would have our developer key and could manipulate releases or push to any random Nextcloud device.
+The Firebase Cloud Messaging (Google) and Apple Push Notification Service are not made for something like a federated project like Nextcloud and still assume there is a single entity behind them like with all the other services.
+
+So we created the push proxy push-notifications.nextcloud.com to protect our users and their data.
+We took some extra efforts and reduced the available information to a bare minimum for each of the sections.
+
+* Nextcloud server
+  - Knowledge:
+    + user public and private key (generated by Nextcloud server)
+    + device identifier (generated by Nextcloud server)
+    + device public key (generated by mobile device)
+    + push-token-hash (generated by mobile device)
+  - Actions
+    + Encrypts the content of the push notifications with `device public key`.
+    + Signs it with the `user private key`.
+    + Sends the notifications with `push-token-hash` to the proxy.
+
+* Push proxy (push-notifications.nextcloud.com)
+  - Knowledge:
+    + user public key (generated by Nextcloud server, send by mobile device)
+    + device identifier (generated by Nextcloud server, send by mobile device)
+    + push token (generated by mobile device)
+    + Google and Apple Developer certificate (generated by Nextcloud)
+  - Actions:
+    + Verifies the signature of the push notification with `user public key` (based on `device identifier`).
+    + Signs the notification with Google or Apple Developer certificate.
+    + Forwards to Firebase Cloud Messaging (Google) or Apple Push Notification Service.
+
+* Firebase Cloud Messaging (Google) and Apple Push Notification Service
+  - Knowledge:
+    + Google and Apple Developer certificate (generated by Nextcloud)
+    + push token (generated by mobile device)
+  - Actions:
+    + Verifies the developer certificate.
+    + Forwards the notification to the mobile client.
+    + *Note:* Since the notification comes from the Push proxy, Google and Apple don't even know the Nextcloud server sending the notification.
+
+* Mobile device
+  - Knowledge:
+    + device public and private key (generated by mobile device)
+    + user public key (generated by mobile device)
+  - Actions:
+    + Verifies the signature with `user public key` to make sure the notification is from a known Nextcloud server and account.
+    + Decrypts the notification with `device private key`.
 
 
 ## Checking the capabilities of the Nextcloud server