From 0348720fd217d7114400ef91c2c9c4381c5d9ada Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 8 Sep 2020 16:24:52 +0100 Subject: [PATCH] Updated draft payload spec to stable --- docs/stable/6-payloads.md | 192 +++++++++++++++++++++++++++++--------- 1 file changed, 147 insertions(+), 45 deletions(-) diff --git a/docs/stable/6-payloads.md b/docs/stable/6-payloads.md index 1039abb..4ae1891 100644 --- a/docs/stable/6-payloads.md +++ b/docs/stable/6-payloads.md @@ -6,11 +6,11 @@ title: 6/PAYLOADS # 6/PAYLOADS -> Version: 0.3 +> Version: 0.6 > > Status: Stable > -> Authors: Adam Babik , Andrea Maria Piana , Oskar Thorén (alphabetical order) +> Authors: Adam Babik , Andrea Maria Piana , Oskar Thorén , Samuel Hawksby-Robinson (alphabetical order) ## Abstract @@ -34,12 +34,15 @@ as various clients created using different technologies. - [Payload](#payload-1) - [Content types](#content-types) - [Sticker content type](#sticker-content-type) + - [Image content type](#image-content-type) + - [Audio content type](#audio-content-type) - [Message types](#message-types) - [Clock vs Timestamp and message ordering](#clock-vs-timestamp-and-message-ordering) - [Chats](#chats) - [Contact Update](#contact-update) - [Payload](#payload-2) - [Contact update](#contact-update-1) + - [EmojiReaction](#emojireaction) - [SyncInstallationContact](#syncinstallationcontact) - [Payload](#payload-3) - [SyncInstallationPublicChat](#syncinstallationpublicchat) @@ -50,7 +53,7 @@ as various clients created using different technologies. - [Upgradability](#upgradability) - [Security Considerations](#security-considerations) - [Changelog](#changelog) - - [Version 0.3](#version-03) + - [Copyright](#copyright) ## Introduction @@ -62,36 +65,9 @@ The node wraps all payloads in a [protobuf record](https://developers.google.com record: ```protobuf -message ApplicationMetadataMessage { - bytes signature = 1; - bytes payload = 2; - - Type type = 3; - - enum Type { - UNKNOWN = 0; - CHAT_MESSAGE = 1; - CONTACT_UPDATE = 2; - MEMBERSHIP_UPDATE_MESSAGE = 3; - PAIR_INSTALLATION = 4; - SYNC_INSTALLATION = 5; - REQUEST_ADDRESS_FOR_TRANSACTION = 6; - ACCEPT_REQUEST_ADDRESS_FOR_TRANSACTION = 7; - DECLINE_REQUEST_ADDRESS_FOR_TRANSACTION = 8; - REQUEST_TRANSACTION = 9; - SEND_TRANSACTION = 10; - DECLINE_REQUEST_TRANSACTION = 11; - SYNC_INSTALLATION_CONTACT = 12; - SYNC_INSTALLATION_ACCOUNT = 13; - SYNC_INSTALLATION_PUBLIC_CHAT = 14; - CONTACT_CODE_ADVERTISEMENT = 15; - PUSH_NOTIFICATION_REGISTRATION = 16; - PUSH_NOTIFICATION_REGISTRATION_RESPONSE = 17; - PUSH_NOTIFICATION_QUERY = 18; - PUSH_NOTIFICATION_QUERY_RESPONSE = 19; - PUSH_NOTIFICATION_REQUEST = 20; - PUSH_NOTIFICATION_RESPONSE = 21; - } +message StatusProtocolMessage { + bytes signature = 4001; + bytes payload = 4002; } ``` @@ -99,8 +75,6 @@ message ApplicationMetadataMessage { The node needs the signature to validate authorship of the message, so that the message can be relayed to third parties. If a signature is not present, but an author is provided by a layer below, the message is not to be relayed to third parties, and it is considered plausibly deniable. -`payload` is the protobuf encoded content of the message, with the corresponding `type` set. - ## Encoding The node encodes the payload using [Protobuf](https://developers.google.com/protocol-buffers) @@ -131,7 +105,6 @@ message ChatMessage { // Chat id, this field is symmetric for public-chats and private group chats, // but asymmetric in case of one-to-ones, as the sender will use the chat-id // of the received, while the receiver will use the chat-id of the sender. - // Probably should be the concatenation of sender-pk & receiver-pk in alphabetical order string chat_id = 6; // The type of message (public/one-to-one/private-group-chat) @@ -141,15 +114,10 @@ message ChatMessage { oneof payload { StickerMessage sticker = 9; + ImageMessage image = 10; + AudioMessage audio = 11; } - enum MessageType { - UNKNOWN_MESSAGE_TYPE = 0; - ONE_TO_ONE = 1; - PUBLIC_GROUP = 2; - PRIVATE_GROUP = 3; - // Only local - SYSTEM_MESSAGE_PRIVATE_GROUP = 4;} enum ContentType { UNKNOWN_CONTENT_TYPE = 0; TEXT_PLAIN = 1; @@ -159,6 +127,8 @@ message ChatMessage { TRANSACTION_COMMAND = 5; // Only local SYSTEM_MESSAGE_CONTENT_PRIVATE_GROUP = 6; + IMAGE = 7; + AUDIO = 8; } } ``` @@ -175,7 +145,7 @@ message ChatMessage { | 6 | chat_id | `string` | The local ID of the chat the message is sent to | | 7 | message_type | `MessageType` | The type of message, different for one-to-one, public or group chats | | 8 | content_type | `ContentType` | The type of the content of the message | -| 9 | payload | `Sticker|nil` | The payload of the message based on the content type | +| 9 | payload | `Sticker` I `Image` I `Audio` I `nil` | The payload of the message based on the content type | #### Content types @@ -189,6 +159,8 @@ There are other content types that MAY be implemented by the client: * `STATUS` * `EMOJI` * `TRANSACTION_COMMAND` +* `IMAGE` +* `AUDIO` ##### Mentions @@ -211,9 +183,59 @@ message StickerMessage { } ``` +##### Image content type + +A `ChatMessage` with `IMAGE` `Content/Type` MUST also specify the `payload` of the image +and the `type`. + +Clients MUST sanitize the payload before accessing its content, in particular: +- Clients MUST choose a secure decoder +- Clients SHOULD strip metadata if present without parsing/decoding it +- Clients SHOULD NOT add metadata/exif when sending an image file for privacy and security reasons +- Clients MUST make sure that the transport layer constraints the size of the payload to limit they are able to handle securely + + +```protobuf +message ImageMessage { + bytes payload = 1; + ImageType type = 2; + enum ImageType { + UNKNOWN_IMAGE_TYPE = 0; + PNG = 1; + JPEG = 2; + WEBP = 3; + GIF = 4; + } +} +``` + +##### Audio content type + +A `ChatMessage` with `AUDIO` `Content/Type` MUST also specify the `payload` of the audio, +the `type` and the duration in milliseconds (`duration_ms`). + +Clients MUST sanitize the payload before accessing its content, in particular: +- Clients MUST choose a secure decoder +- Clients SHOULD strip metadata if present without parsing/decoding it +- Clients SHOULD NOT add metadata/exif when sending an audio file for privacy and security reasons +- Clients MUST make sure that the transport layer constraints the size of the payload to limit they are able to handle securely + +```protobuf +message AudioMessage { + bytes payload = 1; + AudioType type = 2; + uint64 duration_ms = 3; + enum AudioType { + UNKNOWN_AUDIO_TYPE = 0; + AAC = 1; + AMR = 2; + } +} +``` + #### Message types -A node requires message types to decide how to encrypt a particular message and what metadata needs to be attached when passing a message to the transport layer. For more on this, see [3/WHISPER-USAGE](3-whisper-usage.md) and [10/WAKU-USAGE](10-waku-usage.md). +A node requires message types to decide how to encrypt a particular message and what metadata needs to be attached when passing a message to the transport layer. For more on this, see [3/WHISPER-USAGE](./3-whisper-usage.md) and [10/WAKU-USAGE](./10-waku-usage.md). @@ -223,6 +245,17 @@ The following messages types MUST be supported: * `PUBLIC_GROUP` is a private message * `PRIVATE_GROUP` is a message to the private group. +```protobuf + enum MessageType { + UNKNOWN_MESSAGE_TYPE = 0; + ONE_TO_ONE = 1; + PUBLIC_GROUP = 2; + PRIVATE_GROUP = 3; + // Only local + SYSTEM_MESSAGE_PRIVATE_GROUP = 4; +} +``` + #### Clock vs Timestamp and message ordering If a user sends a new message before the messages sent while the user was offline are received, the new @@ -288,6 +321,52 @@ A client SHOULD send a `ContactUpdate` to all the contacts each time: A client SHOULD also periodically send a `ContactUpdate` to all the contacts, the interval is up to the client, the Status official client sends these updates every 48 hours. +### EmojiReaction + +`EmojiReaction`s represents a user's "reaction" to a specific chat message. For more information about the concept of +emoji reactions see [Facebook Reactions](https://en.wikipedia.org/wiki/Facebook_like_button#Use_on_Facebook). + +This specification RECOMMENDS that the UI/UX implementation of sending `EmojiReactions` requires only a single click +operation, as users have an expectation that emoji reactions are effortless and simple to perform. + +```protobuf +message EmojiReaction { + // clock Lamport timestamp of the chat message + uint64 clock = 1; + + // chat_id the ID of the chat the message belongs to, for query efficiency the chat_id is stored in the db even though the + // target message also stores the chat_id + string chat_id = 2; + + // message_id the ID of the target message that the user wishes to react to + string message_id = 3; + + // message_type is (somewhat confusingly) the ID of the type of chat the message belongs to + MessageType message_type = 4; + + // type the ID of the emoji the user wishes to react with + Type type = 5; + + enum Type { + UNKNOWN_EMOJI_REACTION_TYPE = 0; + LOVE = 1; + THUMBS_UP = 2; + THUMBS_DOWN = 3; + LAUGH = 4; + SAD = 5; + ANGRY = 6; + } + + // whether this is a retraction of a previously sent emoji + bool retracted = 6; +} +``` + +Clients MUST specify `clock`, `chat_id`, `message_id`, `type` and `message_type`. + +This specification RECOMMENDS that the UI/UX implementation of retracting an `EmojiReaction`s requires only a single +click operation, as users have an expectation that emoji reaction removals are effortless and simple to perform. + ### SyncInstallationContact The node uses `SyncInstallationContact` messages to synchronize in a best-effort the contacts to other devices. @@ -372,8 +451,31 @@ There are two ways to upgrade the protocol without breaking compatibility: ## Changelog +### Version 0.6 + +Release //TODO + +- Updated draft spec to stable status + +### Version 0.5 + +Released [August 25, 2020](https://github.com/status-im/specs/commit/968fafff23cdfc67589b34dd64015de29aaf41f0) + +- Added support for emoji reactions + +### Version 0.4 + +Released [July 16, 2020](https://github.com/status-im/specs/commit/ad45cd5fed3c0f79dfa472253a404f670dd47396) + +- Added support for images +- Added support for audio + ### Version 0.3 Released [May 22, 2020](https://github.com/status-im/specs/commit/664dd1c9df6ad409e4c007fefc8c8945b8d324e8) - Added language to include Waku in all relevant places + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).