diff --git a/specs/conversations.md b/specs/conversations.md index 171557b..5257279 100644 --- a/specs/conversations.md +++ b/specs/conversations.md @@ -7,58 +7,73 @@ tags: chat editor: Jazz Alyxzander contributors: --- -## Abstract +# Abstract This specification outlines the base message structure for the Conversations protocol. -## Background / Rationale / Motivation +# Background / Rationale / Motivation Modern communication systems require a reliable and flexible way to establish and manage conversations between participants. While simple message-passing protocols exist, they lack the ability to manage state across a stream of messages. -The Conversations Protocol addresses this gap by providing a clear and standardized way for participants to initiate, conversations in decentralized environments. +The Conversations Protocol addresses this gap by defining a mechanism to establish long term communication sessions in decentralized environments. +# Theory / Semantics -## Theory / Semantics - -[TODO: remove this link, by sumamrizing and embedding in the spec so its standalone] +[TODO: remove this link, by summarizing and embedding in the spec so its standalone] This is a lightweight framework for defining Conversation micro-protocols. The high level Conversations approach outlined [here](https://forum.vac.dev/t/chatsdk-conversations/509). The intention is to provide the minimal building blocks for a wide range of micro-protocols, while allowing ConversationTypes to remain as flexible as possible. +At a high level this Protocol defines what a ConversationType is, it's requirements, and a mechanism for initializing Conversations with others. -### Conversations -A conversation is responsible for defining its encryption, encoding, and message types which are necessary for operation. +**Frame**: + +## Conversations +A ConversationType is a specification which defines a method for clients to communicate. +Each ConversationType defines its own encryption, encoding, and message types which are necessary for operation. A ConversationType MUST define which content topics are valid places to receive messages. A ConversationType MUST define which encryption scheme is used A ConversationType MUST define which Frames are valid. - Clients MUST be able to decode frames deterministically. - A ConversationType SHOULD define membership requirements and limitations. -Every Conversation instance MUST have a conversation_id. +A Conversation is an instance of a particular ConversationType which contains the associated state such as membership, encryption parameters, names etc. + +### ConversationIdentifiers + +A Conversation instance MUST a conversationd_id and the `conversation_id` MUST uniquely identify the conversation. +[TODO: Should more guidance be added later? e,g ///] -**Decoding** -Clients determine how to decode a byte sequence by the `conversation_id`. - -[TODO: Should we add more guidance later? e,g ///] -`conversation_id's` must be uniquely identify which encryption state to. As there may be many ConversationTypes defined, specifications should be mindful of conflicts. - -Clients only accepts envelopes with known `conversation_id's`. All others can be discarded as there is insufficient information to properly decrypt/decode the messages. +## Default Inbox +The default inbox allows clients to discover new conversations asynchronously without prior coordination. By listening in a static location -**Framing** -To maintain a deterministic decoding tree, all frames on the wire MUST be wrapped with a `UmbraEnvelope`. -This provides a common type for all frames. - -Underneath UmbraEnvelope, ConversationTypes are free to wrap frames as desired, however it is recommended to use `EncryptedFrame` to ensure clients can decode messages regardless of software version. +To achieve this all clients MUST implement a default Inbox with `inbox_address = HASH(client_address)`. [TODO: Define hash here, or embed as part of the Inbox spec] +See [Inbox](./inbox.md) for more information. -**Conversation Hinting** +As the clients address is directly linked to the content_topic there is some metadata leakage, and this pathway SHOULD only be used as a last resort. + +## Framing +To disambiguate between different logical layers, payload types sent by a Conversation are referred to as `Frames`. + +Conversations are free to determine which frames are needed for their specific use cases, with these caveats: +- The outer most frame MUST be wrapped in an UmbraEnvelope. +- All frames MUST be able to be decoded deterministically. [TODO: Unambiguously a better choice?] + +Deterministic decoding means that clients can always classify a envelope as 1 of 3 states: Readable, BadlyFormed, Addressed to someone else. + + +### Conversation Hinting [TODO: Needs lots of work] + +UmbraEnvelopes enable deterministic decoding by containing a reference to the conversation which this message belongs. Clients only accepts envelopes with known `conversation_hints's`. All others can be discarded as there is insufficient information to properly decrypt/decode the messages. + + Conversation identifiers (conversation_id) have the potential to leak sensitive metadata if exposed in cleartext. Frames sharing the same conversation_id could allow observers to infer social graph relationships, user activity patterns, or conversation linkage, depending on how conversation_id values are used by the specific ConversationType. To mitigate this risk and provide a safer default for Conversation implementors, conversation_id values SHOULD be obscured in a way that prevents observers from linking frames belonging to the same conversation. @@ -67,12 +82,6 @@ To mitigate this risk and provide a safer default for Conversation implementors, -### Default Inbox -To provide a baseline for interaction, clients need a method to receive initial frames/invites. To achieve this all clients MUST implement a default Inbox with `inbox_address = HASH(client_address)`. [TODO: Define hash here, or embed as part of the Inbox spec] - -See [Inbox](./inbox.md) for more information. - - ## Wire Format Specification / Syntax The wire format is specified using protocol buffers v3. @@ -99,8 +108,10 @@ if available, point to existing implementations for reference. ## Security/Privacy Considerations -[TODO: cover Conversation_id -> Message Types ] +Messages sent to the default inbox are linkable to an client (as it is derived from the clients address). This means that if a target client address is known to an observer, they can determine if any messages were sent to the target using the default inbox. In this case the Envelopes contain no sender information, so this does not leak social graph information. + +Messages sent via different pathways would have their own privacy guarantees. ## Copyright