polyproto-chat Extension Specification

Namespace: chat

Version: v1.0-alpha.1

Base Path: /.p2/chat/v1/

warning

The polyproto-chat specification document is in an early alpha phase. Please report any inconsistencies, missing or duplicate information, or other mistakes at our issue tracker.

Semantic versioning v2.0.0 is used to version this specification.

The polyproto-chat extension describes a polyproto application extension. The generic application use-case described by polyproto-chat is an instant-messenger (IM) for communities and other groups of individuals. The polyproto-chat IM offers both unencrypted and encrypted modes of communication for various degrees of secrecy, though anonymity is not a targeted use case. For reference, the polyproto-chat IM specification will be similar to the services currently offered by Revolt, Spacebar and–to some degree–Matrix. Like polyproto, polyproto-chat prioritizes user experience above all, only sacrificing ease-of-use where absolutely necessary to guarantee a safe, federated experience for the majority of users.

1. Dependencies

note

This dependency matrix may change at any point during polyproto-chat development, until a stable version has been reached.

polyproto-chat depends on the following other polyproto technologies:

Full name	Namespace	Version
polyproto-core	core	^=1.0.0-beta.2
polyproto-mls	mls	^=0.1.0-alpha.1
polyproto-auth	auth	^=0.1.0-alpha.1

2. Data types

2.1 Strings

polyproto-chat defines the String type as valid Unicode, encoded as UTF-8. String types must not start or end with unprintable characters. All Unicode characters with either White_Space or the Pattern_White_Space properties set to true are "unprintable characters" for purposes of this specification document.

info

Characters which have both these properties set to true also qualify as "unprintable".

2.2 Integers

note

Floating point numbers are not meant here.

Integer types must be encoded to and from JSON as integers and never as strings, no matter how large those integers are in size.

3. Data structures

JavaScript Object Notation (JSON)-based data structures are at the heart of polyproto-chat. These data structures are supposed to be easily parsed by conscious individuals and machines alike and are designed with encryption in mind from the very beginning. This chapter defines the shape and validation criteria for polyproto-chat data structures.

3.1 Spaces

Spaces are a major organizational unit in polyproto-chat. Spaces can be joined by actors through space discovery, an invitation code or an invitation URL, if available. Similar to files in a folder on a desktop computer, a space can contain an arbitrary amount of channels associated with this space.

Field Name	Data type	Description	Required?
id	String, ULID	A instance-unique ULID, uniquely identifying this object	x
displayName	String	Arbitrary display name, intended to be presented to actors	x
description	String	An optional description, informing actors what this space is about.
icon	String, URI	An optional space icon for this space.
ownerId	String	Federation ID of the actor currently designated as owner of this space.	x
createdAt	String, Date-Time	ISO8601 date and time in a particular time zone, signifying the point in time on which this space has been created.	x

3.2 Channels

TODO: Unfinished

Channels are containers for messages sent by actors. They store messages and their metadata as they get sent. Their data structure depends on whether the channel is encrypted or not.

Field Name	Data type	Description	Required?
id	String, ULID	A instance-unique ULID, uniquely identifying this object	x
encrypted	Boolean	Whether this channel is encrypted. The value of this field determines what formatting should be expected fort the structure in the data field. If the value is true, a String representing an encrypted ChannelData JSON structure should be expected in the data field. If false, a clear-text ChannelData JSON object is to be expected in the data field.	x
data	ChannelData or String	Depending on whether this channel is encrypted or not, the data field stores a plaintext ChannelData object or a string encoded representation of the encrypted ChannelData object. The server can–of course–not verify the contents of the encrypted string.	x

3.2.1 ChannelData Object

TODO: Unfinished

Field Name	Data type	Description	Required
parentId	String, ULID	ID of the channel that this channel is a child of, if applicable	x
type	String, Type Identifier	Type of this channel. The value of this field determines the structure to be expected in the data field.	x
name	String	The display name of this channel.	x
topic	String	A channel description or channel topic.
permissionSettings
position			x
rateLimit
icon

3.3 Permissions

3.3.1 Permission overrides

Permission overrides define category- and channel-specific exceptions to role-based permissions, which apply to an entire space.

tip

A very common use-case for permission overrides is to restrict access to space categories or channels. For example, one might create a channel category for space administrators and -moderators to privately discuss internal affairs.

Permission override JSON objects contain any number of sub-objects TODO: Unfinished

{
    "permission_overrides": {
        "chat.message.pin": {
            "01K6XDM8K8VSJ6N8D5A4AT52FW": "allow",
            "3FZ9JQ29C487N9QN0YSQP9Y16X": "allow",
            "61TMKQHHC4XSMXB2QPCXWTW6AY": "deny"
        },
        "chat.message.mention.all": {
            "3FZ9JQ29C487N9QN0YSQP9Y16X": "allow"
        },
        "org.example.extension.discombobulate": {
            "61TMKQHHC4XSMXB2QPCXWTW6AY": "allow"
        }
    }
}