[SPECS]Decrypted web3wallet notifications

docs/specs/clients/notify/decrypted-notifications.md

@@ -0,0 +1,22 @@
+# Decrypted Notifications
+
+The below class introduces the general way of handling notify notifications received by a wallet. This should be handled in the background service where the implementation details differs on each platform.
+
+```typescript
+abstract class DecryptedNotification {
+    // decrypt encrypted request
+    public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise<NotifyMessage>;
+}
+
+type NotifyMessage = {
+    id: string,
+    type: string,
+    title: string,
+    body: string,
+    icon: string,
+    url: string,
+}
+```
+
+Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `tag` and only display push notifications for the following methods:
+- Notify: `wc_notifyMessage` (4002)

docs/specs/meta-clients/web3wallet/decrypted-notifications.md

@@ -0,0 +1,31 @@
+# Decrypted Notifications
+
+The below class introduces the general way of handling decrypted notifications notifications (Sign, Auth) received by a wallet. This should be handled in the background service where the implementation details differs on each platform.
+
+```typescript
+abstract class DecryptedNotification {
+    // decrypt encrypted request
+    public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise<RpcRequest>;
+
+    // get notification metadata for a given request
+    public getMetadata(params: { topic: string }): Promise<Metadata>;
+}
+
+type RpcRequest = {
+    id: string,
+    jsonrpc: string,
+    method: string,
+    params: string,
+}
+
+type Metadata = {
+    name: string,
+    description: string,
+    url: string,
+    icons: string[],
+}
+```
+
+Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `tag` and only display push notifications for the following methods:
+- Sign: `wc_sessionPropose` (1100), `wc_sessionRequest` (1108)
+- Auth: `wc_authRequest` (3000)

docs/specs/meta-clients/web3wallet/sdk-api.md

@@ -71,7 +71,7 @@ class Web3Wallet {
   public abstract getPendingAuthRequests(): Promise<Record<number, PendingRequest>>;
 
   // register device token for Push server (BOTH)
-  public abstract registerDeviceToken(token: string): Promise<void>;
+  public abstract registerDeviceToken(token: string, enableEncrypted?: boolean = false): Promise<void>;
 
   // ---------- Events ----------------------------------------------- //
 

docs/specs/servers/push/background-service

@@ -0,0 +1,6 @@
+### Background Service
+
+Each platform is responsible for handling decrypted notifications in background services received by a wallet where the implementation details differ on each platforms. The background service decides based on tag the type of notification to handle.
+
+- [Notify Notifications](docs/specs/clients/notify/decrypted-notifications.md)
+- [Web3Wallet Notifications](docs/specs/meta-clients/web3wallet/decrypted-notifications.md)

docs/specs/servers/push/spec.md

@@ -15,21 +15,21 @@ These are the default responses and are only different if otherwise specified.
 
 ```
 {
-    "status": "OK"
+  "status": "OK"
 }
 ```
 
 ### Unsuccessful Response
 
 ```
 {
-    "status": "FAILED",
-    "errors": [
-        { "name": "", description": "" }
-    ]
-    "fields": [
-        { "field": "type", "description": "", "location": "" }
-    ]
+  "status": "FAILED",
+  "errors": [
+    { "name": "", description": "" }
+  ]
+  "fields": [
+    { "field": "type", "description": "", "location": "" }
+  ]
 }
 ```
 
@@ -58,17 +58,31 @@ OK, push-server v0.1.0
 
 ```
 POST <PUSH_SERVER_URL>/clients
+```
+
+Request body:
+```typescript
 {
-    "client_id": <CLIENT_ID>,
-    "type": <TYPE>,
-    "token": <DEVICE_TOKEN>
+  // The Client's ID from the Relay pairing.
+  client_id: string,
+
+  // The push service to use.
+  type: "apns" | "apns-sandbox" | "fcm" | "noop",
+
+  // The device's token for the push service.
+  token: string,
+
+  // See below
+  always_raw?: boolean,
 }
 ```
 
-- `CLIENT_ID`: The Client's ID from the Relay pairing.
-- `TYPE`: The push service to use e.g. APNS, FCM. This will be validated against the supported types on the Push
-  Server's side.
-- `DEVICE_TOKEN`: The device's token for the push service e.g. FCM, APNS.
+- `always_raw` - forces sending raw notifications, defaults to `false`
+  - When set to `true`, the push notification will contain, as custom data, `topic`, `tag`, and `message` from the request payload in [Send Notifications](#send-notification) section.
+  - When set to `false`, cleartext notifications will be sent for certain messages based on `tag`, but all other messages will contain, as custom data, `payload.topic` and `payload.blob` from the request payload in [Send Notifications](#send-notification) section. Cleartext messages:
+    - Sign API `wc_sessionPropose` (tag: 1100) and `wc_sessionRequest` (tag: 1108)
+      - title: Signature required
+      - body: You have a message to sign
 
 ### Unregister Client
 
@@ -80,27 +94,53 @@ DELETE <PUSH_SERVER_URL>/clients/<CLIENT_ID>
 
 ### Send Notification
 
+This endpoint is called by the relay.
+
 ```
 POST <PUSH_SERVER_URL>/clients/<CLIENT_ID>
+```
+
+- `CLIENT_ID` - This is used to map to the device token
+
+Headers:
+- `X-Ed25519-Timestamp` - timestamp of the signature
+- `X-Ed25519-Signature` - hex encoded ed25519 signature of `format!("{}.{}.{}", timestamp, body.len(), body)` where `body` is the request body
+
+Request body:
+```typescript
 {
-    "id": "0000-0000-0000-0000"
-    "payload": {
-      "topic": "<topic>",
-      "flags": <flags>,
-      "blob": "<blob>"
-    }
-```
-
-- `CLIENT_ID`: This is used to map to the device token
-- `id`: This is generated by the Relay to prevent duplicate notifications
-- `payload`: A string with 3 values encoded and split with a `:` as a delimiter.
-  - `topic`: This is used by the SDKs to decrypt encrypted payloads on the client side
-  - `flags`: an integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below
-    ```
-    Encrypted  = 1 << 0
-    Sign       = 1 << 1
-    Auth       = 1 << 2
-    Chat       = 1 << 3
-    Notify     = 1 << 4
-    ```
-  - `blob`: If the payload is encrypted this is just the encrypted blob, when this is cleartext it should be base64 encoded. The blob should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message)
+  // Topic of the message. This is used by the SDKs to decrypt encrypted payloads on the client side
+  topic: string,
+
+  // Tag of the message.
+  tag: number,
+
+  // The relay message.
+  message: string,
+
+  // ==== Legacy fields ====
+
+  // Unique ID for deduplication purposes
+  id: string,
+
+  payload: {
+    // Same as `topic` above
+    topic: string,
+
+    // See below
+    flags: number,
+
+    // See below
+    blob: string,
+  }
+```
+
+- `flags`: An integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below
+  ```
+  Encrypted  = 1 << 0
+  Sign       = 1 << 1
+  Auth       = 1 << 2
+  Chat       = 1 << 3
+  Notify     = 1 << 4
+  ```
+- `blob`: If the flags specify encrypted, then this is just the relay message. If not encrypted, this is base64 encoded cleartext and should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message)