Merge branch '18-bsp-clients' into 'master'

Move BSP clients specs from wiki to this repo

Closes #18

See merge request !7

README.md

@@ -7,8 +7,24 @@ as well as text on
 ## Formal specifications in this repo
 
 - [Binary Data Format](BDF.md)
+
+### Bramble Protocols
+
 - [Bramble Handshake Protocol](protocols/BHP.md)
 - [Bramble QR Code Protocol](protocols/BQP.md)
 - [Bramble Rendezvous Protocol](protocols/BRP.md)
 - [Bramble Synchronisation Protocol](protocols/BSP.md)
 - [Bramble Transport Protocol](protocols/BTP.md)
+
+### Briar BSP Clients
+
+* [Transport Key Agreement Client](clients/Transport-Key-Agreement-Client.md)
+* [Transport Properties Client](clients/Transport-Properties-Client.md)
+* [Messaging Client](clients/Messaging-Client.md)
+* [Forum Client](clients/Forum-Client.md)
+* [Forum Sharing Client](clients/Forum-Sharing-Client.md)
+* [Blog Client](clients/Blog-Client.md)
+* [Blog Sharing Client](clients/Blog-Sharing-Client.md)
+* [Private Group Client](clients/Private-Group-Client.md)
+* [Private Group Sharing Client](clients/Private-Group-Sharing-Client.md)
+* [Introduction Client](clients/Introduction-Client.md)

clients/Blog-Client.md

+# Blog Client
+
+The blog client is a [BSP client](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md) that synchronises blog posts among groups of devices. It is used in conjunction with the [blog sharing client](blog sharing client).
+
+The creator of a blog is the only user who can post messages. Posts and comments from other blogs can be reblogged with optional comments.
+
+A blog may consist of posts imported from an RSS feed.
+
+### Identifier
+
+The client's identifier is `org.briarproject.briar.blog`. The major version is 0.
+
+### Groups
+
+Each blog is represented by a separate BSP group. The [group descriptor](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md#23-groups) is a [BDF list](https://code.briarproject.org/briar/briar-spec/blob/master/BDF.md) with two elements: `author` (list) and `rss` (boolean).
+
+`author` is a list with three elements: `formatVersion` (int), `nickname` (string) and `publicKey` (raw). This identifies the user who publishes the blog.
+
+`rss` indicates whether the blog contains an imported RSS feed or a user's personal blog. `nickname` is used as the blog's title. Posts are signed with the private key corresponding to `publicKey`.
+
+### Message types
+
+**0: POST** - A blog post. The message body is a BDF list with three elements: `messageType` (int), `text` (string), and `signature` (raw).
+
+The signature covers a BDF list with three elements: `groupId` (unique ID), `timestamp` (int), and `text` (string). The group ID and timestamp are taken from the message header. The public key from the group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/POST`.
+
+**1: COMMENT** - A pointer to a reblogged post or comment, with an optional comment. The message body is a BDF list with five elements: `messageType` (int), `comment` (string or null), `parentOriginalId` (unique ID), `parentId` (unique ID), and `signature` (raw).
+
+`parentOriginalId` is the ID of a post or comment in this blog or another blog. `parentId` is the ID of this comment's parent, which is a post, comment, wrapped post or wrapped comment in this blog, which had the ID `parentOriginalId` in the blog where the parent was originally posted.
+
+The signature covers a BDF list with five elements: `groupId` (unique ID), `timestamp` (int), `comment` (string or null), `parentOriginalId` (unique ID), and `parentId` (unique ID). The group ID and timestamp are taken from the message header. The public key from the group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/COMMENT`.
+
+**2: WRAPPED_POST** - A reblogged post from another blog. The message body is a BDF list with five elements: `messageType` (int), `copiedGroupDescriptor` (list), `copiedTimestamp` (int), `copiedText` (string), and `copiedSignature` (raw).
+
+`copiedGroupDescriptor` is the descriptor of the blog where this post was originally posted. `copiedTimestamp`, `copiedText` and `copiedSignature` are copied from the original post. The public key from the copied group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/POST`.
+
+The original group ID must be calculated, as it is covered by the signature. The original message ID must also be calculated, as it is referenced by comments.
+
+**3: WRAPPED_COMMENT** - A reblogged comment from another blog. The message body is a BDF list with eight elements: `messageType` (int), `copiedGroupDescriptor` (list), `copiedTimestamp` (int), `copiedComment` (string or null), `copiedParentOriginalId` (unique ID), `copiedParentId` (unique ID), `copiedSignature` (raw), and `parentId` (unique ID).
+
+`copiedGroupDescriptor` is the descriptor of the blog where this comment was originally posted. `copiedTimestamp`, `copiedComment`, `copiedParentOriginalId`, `copiedParentId` and `copiedSignature` are copied from the original comment. The public key from the copied group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/COMMENT`.
+
+The original group ID must be calculated, as it is covered by the signature. The original message ID must also be calculated, as it is referenced by comments.
+
+`parentId` is the ID of this comment's parent, which is a post, comment, wrapped post or wrapped comment in this blog, which had the ID `copiedParentOriginalId` in the blog where the parent was originally posted, and the ID `copiedParentId` in the blog where this comment was originally posted.
+
+### Validity policy
+
+* A post is valid if it is well-formed and has a valid signature.
+* A comment is valid if it is well-formed, has a valid signature, and references a valid message of any type in the same blog, with a matching original ID.
+* A wrapped post is valid if a valid post can be reconstructed from it.
+* A wrapped comment is valid if a valid comment can be reconstructed from it, and it references a valid message of any type in the same blog, with a matching original ID.
+
+### Storage policy
+
+* All messages are stored.
+
+### Sharing policy
+
+* All posts and comments are shared.
+* Wrapped posts and wrapped comments are not shared unless they are referenced by a post or comment.
+

clients/Blog-Sharing-Client.md

+# Blog Sharing Client
+
+The blog sharing client is a [BSP client](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md) that allows users to share blogs with their contacts, who may accept or decline the invitations. It is used in conjunction with the [blog client](blog client).
+
+### Identifier
+
+The client's identifier is `org.briarproject.briar.blog.sharing`. The major version is 0.
+
+### Groups
+
+The client uses a separate BSP group for communicating with each contact. The [group descriptor](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md#23-groups) is a [BDF list](https://code.briarproject.org/briar/briar-spec/blob/master/BDF.md) containing the unique IDs of the contacts' identities, sorted in ascending order as byte strings.
+
+### Roles
+
+All communication happens between two contacts, who have symmetrical roles.
+
+### Sessions
+
+The messages exchanged between two contacts referring to a given blog constitute a session. The blog's unique ID is used as the session ID.
+
+### Message types
+
+The protocol uses five message types.
+
+**0: INVITE** - Sent by either party to start or restart a session. The message body is a BDF list with four elements: `messageType` (int), `previousMessageId` (unique ID or null), `descriptor` (list), and `text` (string or null).
+
+`previousMessageId` is the ID of the previous message in this session, if any. `descriptor` is the [descriptor of the blog](Blog-Client#group-identifiers) being shared. The blog ID must be calculated from the descriptor, as it is used by subsequent messages in the session. `text` is an optional message from the inviter to the invitee explaining the invitation.
+
+The sender sets the blog's visibility to VISIBLE when sending an invite message.
+
+**1: ACCEPT** - Sent in response to an invite. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
+
+`previousMessageId` is the ID of the previous message in this session.
+
+The sender sets the blog's visibility to SHARED when sending an accept message. The recipient sets the blog's visibility to SHARED when receiving an accept message.
+
+**2: DECLINE** - Sent in response to an invite. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
+
+`previousMessageId` is the ID of the previous message in this session.
+
+The inviter sets the blog's visibility to INVISIBLE when receiving a decline message.
+
+**3: LEAVE** - Sent by either party when unsubscribing from the blog, if the blog's visibility is VISIBLE or SHARED. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
+
+`previousMessageId` is the ID of the previous message in this session.
+
+The sender sets the blog's visibility to INVISIBLE when sending a leave message. The recipient sets the blog's visibility to INVISIBLE when receiving a leave message.
+
+**4: ABORT** - Sent by either party when recieving a message that is valid but unexpected in the current state. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
+
+`previousMessageId` is the ID of the previous message in this session.
+
+The sender sets the blog's visibility to INVISIBLE when sending an abort message. The recipient sets the blog's visibility to INVISIBLE when receiving an abort message.
+
+### State machine
+
+![state-machine-4](/assets/clients/Blog-Sharing-Client/state-machine-4.png)
+
+[state-machine-4.odg](/assets/clients/Blog-Sharing-Client/state-machine-4.odg)
+
+Aborting from any state returns the session to the START state.
+
+### Validity policy
+
+* A message is valid if it is well-formed and its previous message (if any) is a valid message in the same session.
+
+### Storage policy
+
+* All messages are stored.
+
+### Sharing policy
+
+* All local messages are shared.
+

clients/Forum-Client.md

+# Forum Client
+
+The forum client is a [BSP client](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md) that synchronises forum posts among groups of devices. It is used in conjunction with the [forum sharing client](forum sharing client).
+
+Any user who subscribes to a forum can post messages. Posts are signed by their authors.
+
+### Identifier
+
+The client's identifier is `org.briarproject.briar.forum`. The major version is 0.
+
+### Groups
+
+Each forum is represented by a separate BSP group. The [group descriptor](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md#23-groups) is a [BDF list](https://code.briarproject.org/briar/briar-spec/blob/master/BDF.md) with two elements: `name` (string) and `salt` (raw). The salt is 32 random bytes, to prevent collisions between forums with the same name.
+
+### Message types
+
+**POST** - The message body is a BDF list with four elements: `parentId` (unique ID or null), `author` (list), `text` (string), and `signature` (raw).
+
+`parentId` is the optional ID of a post in the same forum to which this post replies. `author` is a list with three elements: `formatVersion` (int), `nickname` (string), and `publicKey` (raw). This identifies the author of the post.
+
+The signature covers a BDF list with five elements: `groupId` (unique ID), `timestamp` (int), `parentId` (unique ID or null), `author` (list), and `text` (string). The group ID and timestamp are taken from the message header. The public key from `author` is used to verify the signature. The signature label is `org.briarproject.briar.forum/POST`.
+
+### Validity policy
+
+* A post is valid if it is well-formed, has a valid signature, and its parent (if any) is valid.
+
+### Storage policy
+
+* All messages are stored.
+
+### Sharing policy
+
+* All messages are shared.
+