diff --git a/docs/specs/clients/notify/decrypted-notifications.md b/docs/specs/clients/notify/decrypted-notifications.md new file mode 100644 index 00000000..00550b37 --- /dev/null +++ b/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; +} + +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) \ No newline at end of file diff --git a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md new file mode 100644 index 00000000..4b8d196b --- /dev/null +++ b/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; + + // get notification metadata for a given request + public getMetadata(params: { topic: string }): Promise; +} + +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) \ No newline at end of file diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index 3c3328a1..dc3d9843 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string): Promise; + public abstract registerDeviceToken(token: string, enableEncrypted?: boolean = false): Promise; // ---------- Events ----------------------------------------------- // diff --git a/docs/specs/servers/push/background-service b/docs/specs/servers/push/background-service new file mode 100644 index 00000000..b85d9644 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 6dd03d24..143f2922 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -15,7 +15,7 @@ These are the default responses and are only different if otherwise specified. ``` { - "status": "OK" + "status": "OK" } ``` @@ -23,13 +23,13 @@ These are the default responses and are only different if otherwise specified. ``` { - "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 /clients +``` + +Request body: +```typescript { - "client_id": , - "type": , - "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 /clients/ ### Send Notification +This endpoint is called by the relay. + ``` POST /clients/ +``` + +- `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": "", - "flags": , - "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)