logos-messaging/chat_proto
1
0
Fork 0
mirror of https://github.com/logos-messaging/chat_proto.git synced 2026-01-02 21:13:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

separated conversation requirements from spec

Browse Source
This commit is contained in:
Jazz Turner-Baggs 2025-07-08 18:32:17 -07:00
parent 9ee46738a9
commit 00e2c87c46
No known key found for this signature in database
2 changed files with 157 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
specs/<PROTO>.md Normal file
View File

@ -0,0 +1,119 @@
---
title: <PROTO>>
name: A private decentralized messaging protocol for multiple usecases.
category: Standards Track
status: raw
tags: chat
editor: Jazz Alyxzander<jazz@status.im>
contributors:
---
# Abstract
This specification defines a modular communication protocol designed to provide a privacy focused approach to common messaging patterns. The protocol employs a lean root layer that defers to independent sub-protocols for defining communication behavior, with versioning as a first-class concept for handling protocol evolution.
# Background / Rationale / Motivation
Traditionally communication protocols face several critical challenges as they grow.
Different communication scenarios have vastly different requirements. A protocol optimized for high-volume public broadcasts performs poorly for intimate encrypted conversations, and vice versa. Monolithic protocols cannot optimize for these diverse use cases simultaneously.
Once widely deployed, communication protocols become difficult to modify. Even minor changes can break compatibility across clients, leading to protocol stagnation and eventually ossification.
When decentralized protocols do attempt to evolve, versioning becomes a complex negotiation problem. Clients must maintain backward compatibility with multiple protocol versions, leading to bloated implementations and coupling which increases complexity.
At each stage protocols become increasingly difficult to modify, which slows down forward progress.
A preferred approach would be to practice resiliency at the protocol level by focusing on versioning from the beginning.
# Theory / Semantics
This protocol is a lean coordination layer which provides the backbone for smaller independent "Conversation" sub-protocols. Conversation protocols completely define a pathway for communication. This root protocol provides common functionality to support a wide array of communication use cases.
```mermaid
flowchart TD
P(%PROTO) --> C1(Conversation)
P --> C2(Conversation)
P --> C3(....)
style C3 fill:#FFFFFF,stroke:#,stroke-width:1px,stroke-dasharray: 5 1
```
This protocol is intentionally light, as the work is deferred to the actual conversation protocols.
## Versioning
Incompatible versions of a conversation protocol result in distinct conversationTypes (E.g. PrivateV1 vs PrivateV3). Individual conversationTypes can implement functionality to migrate participants to a conversation. By making this a conversationType issue, different use cases can choose a system that works for them.
## Conversations
Conversations can be created permissionlessly within the %PROTO, as there is no required registration. Developers are free to use any given conversation type as long as all intended participants support it.
ConversationTypes MUST adhere to the [Conversations](./conversations.md) specification in order to maintain compatibility, however network adoption is not q requirement.
## Default Inbox
There exists a circular dependency in initializing a Conversation. Conversations require an established conversation to send an invitation, yet at the beginning no channel exists between contacts.
To resolve this all clients MUST implement a default [Inbox](./inbox.md) to receive initial messages. The default inbox allows clients to discover new conversations asynchronously without prior coordination. By listening in a static location.
The default inbox MUST be configured with the parameters:
- **inbox_addr:** `client_address`
- **discriminator:** "default"
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.
## Envelopes
As clients can support multiple sub-protocols simultaneously, a mechanism is required to determine how decode messages.
All payloads sent MUST be deterministically decodable. Deterministic decoding means that clients can always classify a envelope as 1 of 3 states: Readable, BadlyFormed, Addressed to someone else. To support this %PROTO uses an Envelope to link encrypted payloads with the information required to process them. As this payload is sent in the clear the payloads cannot contain any identifiable information.
### Conversation Hinting
Conversation_ids are sufficient to allow clients to lookup the required encryption parameters and decrypt a message. However this would leak Conversation metadata. Instead a hint is used which allows clients to check if this message is of interest.
Messages with an unknown hint can be safely disregarded.
ConversationHints are computed by using a salted hash of the `conversationId`. specifically defined as `lowercase_hex(blake2s(conversation_id))`
[TODO: Should conversations define their own hinting?]
## Wire Format Specification / Syntax
The wire format is specified using protocol buffers v3.
```protobuf
message UmbraEnvelopeV1 {
string conversation_hint = 1;
uint32 salt = 2;
EncryptedBytes encrypted_bytes = 10;
}
```
## Implementation Suggestions (optional)
### User level Conversations
A ConversationType defines how to send and receive messages. Developer SHOULD mask the conversationType from users. Developers should use an independent identifier in their apps for user-level "conversations" so that the protocols can update freely.
## (Further Optional Sections)
## Security/Privacy Considerations
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 inherit the privacy and security properties of the ConversationType used to send them. Please refer to the corresponding specifications when analyzing properties.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References
A list of references.

99
specs/conversations.md
View File

@ -9,7 +9,7 @@ contributors:
---
# Abstract
This specification outlines the base message structure for the Conversations protocol.
This specification outlines the requirements for defining a ConversationType
# Background / Rationale / Motivation
@ -21,83 +21,63 @@ The Conversations Protocol addresses this gap by defining a mechanism to establi
# Theory / Semantics
[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.
**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.
A Conversation is an instance of a particular ConversationType which contains the associated state such as membership, encryption parameters, names etc.
### ConversationIdentifiers
## Requirements
To be considered valid, every ConversationType specification is required to define the operation completely.
A Conversation instance MUST a conversation_id and the `conversation_id` MUST uniquely identify the conversation.
[TODO: Should more guidance be added later? e,g /<convo_type>/<version>/<ident>]
A ConversationType MUST define which encryption scheme is used
A ConversationType MUST define which Frames are used.
A ConversationType MUST define which encoding is used.
A ConversationType MUST define which content topics are valid places to receive messages.
A ConversationType MUST define how to generate conversation_ids
A ConversationType SHOULD define membership requirements and limitations.
A ConversationType SHOULD define privacy and security guarantees.
## Default Inbox
The default inbox allows clients to discover new conversations asynchronously without prior coordination. By listening in a static location
## ConversationType Identifiers
ConversationTypes are identified by the title of the specification. This allows developers to lookup the associated specification.
[TODO: This doesn't make any sense, as its been mentioned that new versions of a conversationType are distinct types. Which is it? ]
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.
E.g. inbox.md -> InboxV1
## Conversation Identifiers
conversation_ids allow for the efficient lookup of encryption state.
Care should be taken to ensure that conversation_ids do not conflict.
[TODO: Should more guidance be added later? e,g mandating a format to ensure uniqueness between conversationTypes -- /<convo_name>/<version>/<ident>]
[TODO: touch on the nuance of generating conversation_ids from participant lists?]
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.
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?]
ConversationTypes MUST define a section which defines all possible frames
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.
[TODO: Ratcheting Private Identifiers]
ConversationTypes SHOULD maintain a deterministic decoding tree.
## Wire Format Specification / Syntax
The wire format is specified using protocol buffers v3.
```protobuf
message UmbraEnvelopeV1 {
string conversation_hint = 1;
uint32 salt = 2;
EncryptedBytes encrypted_bytes = 10;
}
## Encryption
Conversation types are free to choose which ever encryption mechanism works best for their application.
[TODO: Expand on recomendations]
## Content Topics
Content topics are how ConversationTypes define where an how messages are discovered by participants.
When developing new ConversationTypes contributors should consider:
- Privacy impacts of the chosen topic policy.
- Channel binding and the impacts on message security.
```
## Implementation Suggestions (optional)
An optional *implementation suggestions* section may provide suggestions on how to approach implementation details, and,
@ -109,10 +89,7 @@ if available, point to existing implementations for reference.
## Security/Privacy Considerations
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.
This approach puts heavy requirements on ConversationTypes to build their own cryptography without providing much guidance. Finding mechanisms that provide safety while maintaining the flexibility should be prioritized in follow up work.
## Copyright