diff --git a/ForumClient.markdown b/ForumClient.markdown deleted file mode 100644 index f06cf96..0000000 --- a/ForumClient.markdown +++ /dev/null @@ -1,64 +0,0 @@ -ForumClient is a [BSP client](BSP) that synchronises forum posts among groups of devices. Any subscriber to a forum can invite new subscribers, and any subscriber can post to the forum. Posts may be anonymous or signed. - -> Implementation note: We propose to use Ed25519 for signatures. - -### Channel identifiers - -ForumClient uses the following client identifer: -`859a 7be5 0dca 035b 64bd 6902 fb79 7097 795a f837 abbf 8c16 d750 b3c2 ccc1 86ea` - -Each forum has its own channel, and there is a single invitation channel shared by all forums. The [channel descriptor](BSP#channel-identifiers) for the invitation channel is an empty [BDF list](BDF). - -The descriptor for a forum channel is a list with two elements: `title` (string) and `salt` (raw). The salt is HASH_LEN random bytes, to prevent collisions between forums with the same title. - -### Message types - -**0: INVITATION** - The content is a list with three elements: `title` (string), `salt` (raw), and `note` (string or null). The channel identifier can be calculated from `title` and `salt`, as described above. `note` is an optional note from the inviter to the invitee. - -**1: RESPONSE** - The content is a list with three elements: `invitation_id` (raw), `decision` (boolean), and `note` (string or null). `invitation_id` is the identifier of an invitation created by the opposite peer. `decision` indicates whether the invitee wishes to subscribe. `note` is an optional note from the invitee to the inviter. - -**2: DEPARTURE** - The content is a list with one element: `invitation_id` (raw), which is the identifier of an invitation created by either peer. - -**3: POST** - The content is a list with three elements: `author` (list or null), `content` (list), and `signature` (raw or null). - -`author` is a list with two elements: `name` (string) and `public_key` (raw). - -`content` is a list with three elements: `parent_id` (raw or null), `subject` (string), `body` (string), and `attachments` (dictionary or null). `parent_id` is the identifier of a post to which this is a response. Each key in `attachments` is the name of an attachment, and the value is a list with two elements: `mime_type` (string) and `message_id` (raw). - -`signature` is a signature over a list with five elements: `channel_id` (raw), `salt` (raw), `timestamp` (int), `author` (list), and `content` (list). `channel_id`, `salt` and `timestamp` are taken from the [message header](BSP#message-format). `author` and `content` are described above. - -If `author` and `signature` are null, the post is anonymous. - -**4: ATTACHMENT** - The content is raw data. - -### Validity policy - -* An invitation or response must belong to the invitation channel. -* A post or attachment must belong to a forum channel. -* An invitation is valid if it is well-formed. -* A response is valid if it is well-formed and it references a valid invitation created by the opposite peer. -* A departure is valid if it is well-formed and it references a valid invitation created by either peer. -* A post is valid if it is well-formed, its parent (if any) is a valid post, and it is either anonymous or carries a valid signature. -* An attachment is always valid. - -Note that a post can be validated before its attachments have been received, and an attachment can be validated before it has been completely received. - -### Storage policy - -For the invitation channel: -* All local messages are stored. -* All remote messages are stored. - -For forum channels: -* Local messages are stored while the local peer subscribes to the forum. -* Remote messages are stored while the local peer subscribes to the forum. - -### Sharing policy - -For the invitation channel: -* Each local message is shared with one remote peer. -* Each remote message is shared with the remote peer that created it. - -For forum channels: -* Local messages are shared with all remote peers that subscribe to the forum. -* Remote messages are shared with all remote peers that subscribe to the forum. diff --git a/ForumClient.md b/ForumClient.md new file mode 100644 index 0000000..aee0b3d --- /dev/null +++ b/ForumClient.md @@ -0,0 +1,64 @@ +ForumClient is a [BSP client](BSP) that synchronises forum posts among groups of devices. Any subscriber to a forum can invite new subscribers, and any subscriber can post to the forum. Posts may be anonymous or signed. + +> Implementation note: We propose to use Ed25519 for signatures. + +### Group identifiers + +ForumClient uses the following client identifer: +`859a 7be5 0dca 035b 64bd 6902 fb79 7097 795a f837 abbf 8c16 d750 b3c2 ccc1 86ea` + +Each forum has its own group. The [group descriptor](BSP#group-identifiers) is a [BDF list](BDF) with two elements: `title` (string) and `salt` (raw). The salt is HASH_LEN random bytes, to prevent collisions between forums with the same title. + +For exchanging invitations, the client uses a separate group for each pair of contacts. The [group descriptor](BSP#group-identifiers) is a [BDF list](BDF) containing the unique IDs of the contacts' identities, sorted in ascending order as byte strings. + +### Message types + +**0: INVITATION** - The content is a BDF list with three elements: `title` (string), `salt` (raw), and `note` (string or null). The group identifier can be calculated from `title` and `salt`, as described above. `note` is an optional note from the inviter to the invitee. + +**1: RESPONSE** - The content is a BDF list with three elements: `invitation_id` (raw), `decision` (boolean), and `note` (string or null). `invitation_id` is the identifier of an invitation created by the opposite peer. `decision` indicates whether the invitee wishes to subscribe. `note` is an optional note from the invitee to the inviter. + +**2: DEPARTURE** - The content is a BDF list with one element: `invitation_id` (raw), which is the identifier of an invitation created by either peer. + +**3: POST** - The content is a BDF list with three elements: `author` (list or null), `content` (list), and `signature` (raw or null). + +`author` is a list with two elements: `name` (string) and `public_key` (raw). + +`content` is a list with three elements: `parent_id` (raw or null), `content_type` (string), `body` (raw), and `attachments` (dictionary or null). `parent_id` is the identifier of a post to which this is a response. Each key in `attachments` is the name of an attachment, and the value is a list with two elements: `content_type` (string) and `message_id` (raw). + +`signature` is a signature over a list with five elements: `group_id` (raw), `timestamp` (int), `author` (list), and `content` (list). `group_id` and `timestamp` are taken from the [message header](BSP#message-format). `author` and `content` are described above. + +If `author` and `signature` are null, the post is anonymous. + +**4: ATTACHMENT** - The content is raw data. + +### Validity policy + +* An invitation or response must belong to an invitation group. +* A post or attachment must belong to a forum group. +* An invitation is valid if it is well-formed. +* A response is valid if it is well-formed and it references a valid invitation created by the opposite peer. +* A departure is valid if it is well-formed and it references a valid invitation created by either peer. +* A post is valid if it is well-formed, its parent (if any) is a valid post, and it is either anonymous or carries a valid signature. +* An attachment is always valid. + +Note that a post can be validated before its attachments have been received, and an attachment can be validated before it has been completely received. + +### Storage policy + +For invitation groups: +* All local messages are stored. +* All remote messages are stored. + +For forum groups: +* All local messages are stored. +* All remote messages are stored. + +### Sharing policy + +For invitation groups: +* All local messages are shared. +* All remote messages are shared. + +For forum groups: +* All local messages are shared. +* All remote messages are shared.