= General concepts =

== Room membership ==
Users can enter and leave the room, as signalled by presence messages from the server (USER_ENTERED, USER_LEFT).

Users can join the room's conversation by sending a JOIN message.

Users can only leave the conversation if the server says they left the room.

(TBD: should users be able to declare that they're leaving, or kick each other out?)

== Sender keys ==
When a new user joins, she exchanges AES256 "sender keys" with existing members, encrypted under the "pairwise keys" from pairwise key agreements. This allows subsequent messages to be encrypted once with a sender key, instead of N times with pairwise keys.

Every time a message is encrypted or decrypted with a sender key, the key is updated as:

sender_key = HMAC-SHA256(prev_sender_key, member_list)

This provides forward secrecy and ensures new members can't decrypt messages prior to when they joined.

== Server order ==
All clients see the same message order from the server. All messages are sent to all users. Aside from the presence messages sent by the server, messages are sent by users.

All messages in a room have a unique sequence number (0, 1, ...). Sequence numbers are implicit, as the server may not be aware of them (e.g. XMPP MUC).

A new user synchronizes his view of sequence numbers via the QUERY / MEMBER_LIST messages (see below).

== Causal order ==
Every user-sent message specifies a "parent" sequence number which is the last message the user received before sending it. Note:
* If Alice sends messages (A,B) in a row, A will not be B's parent unless Alice waits till A is received back from the server.
* The parent of a message is different from the "previous" message in the server's ordering, e.g. in a "simultaneous send" case two messages will have the same parent.

Due to server ordering, the sender of message i must have seen all
messages from 0...i's parent. Thus, every user-sent message i has a membership set, determined by the JOIN / USER_LEFT messages from 0...i's parent.

== Transcript hashes ==
Every message specifies its parent's sequence number. Some messages also specify a transcript hash of that parent and all prior messages. The hash also covers the sender_key for each message (set to zeros for cleartext messages):

H(parent) = SHA256(sender_key[parent] || ciphertext[parent] || H(parent-1))

== Timing ==
Timing rules can trigger errors based on some assumed constants:

* MAX_RTT - this is the maximum time it should take for a sent message to arrive at all parties. If you send a message and haven't received it back within MAX_RTT, something is wrong.

* MAX_RTD - this is the maximum difference in time when a message arrives at all parties. If you receive a message which isn't a causal successor of a message you received more than MAX_RTD + MAX_RTT time ago, something is wrong.

* MAX_CONFIRM - this is the maximum time an existing member may spend after receiving a new user's JOIN message before sending a CONFIRM message in response. If the new user hasn't received CONFIRM messages from existing membership within 2*MAX_RTT + MAX_CONFIRM, something is wrong.

= Messages =

== Generic structures ==

=== Certificate ===
* The user's Curve25519 identity public key
* The user's Curve25519 ephemeral public key
* An Ed25519 signature from the identity key over the ephemeral key
(Ed25519 signatures can be produced from Curve25519 keys)

== Server messages ==

=== USER_ENTERED, USER_LEFT ===
* "Presence" messages sent in clear by the server to indicate a user has entered or left the room

== Cleartext messages from users ==

=== QUERY ===
* Contains a nonce
* Requests anyone to send a MEMBER_LIST

=== MEMBER_LIST ===
* Lists the sequence number and nonce of the QUERY it's responding to
* Lists the certificate for each member of its parent

=== JOIN ===
* Lists the certificate for the new member
* Contains CONFIRM messages for each member of its parent

== Encrypted messages ==

=== CONFIRM ===
* Encrypts-and-confirms an AES256 "sender key" from one member to another
* Uses pairwise TripleDH between sender and recipient keys, i.e.
HASH( DH(A_id, B_eph) || DH(A_eph, B_id) || DH(A_eph, B_eph) )
* Contains a transcript hash

=== DATA ===
* Encrypted under the sender's "sender key"
* Contains a transcript hash
* Ed25519 signature from the sender's ephemeral public key

= Algorithms =

== Nonblocking Join ==
On entering a room, a user sends a QUERY. She is present in the room but hasn't yet joined the conversation. Someone (or multiple parties) will respond with a MEMBER_LIST.

On receiving a MEMBER_LIST, a present user learns the room's membership and sequence numbers, and can keep track of the membership by observing subsequent JOIN / USER_LEFT messages.

To join a room, a present user sends a JOIN, including a CONFIRM for each member in its parent, and expects to receive a CONFIRM from each member shortly.

After sending the JOIN, the user considers herself part of the conversation and can send DATA messages and respond to QUERY messages. She responds to any subsequent JOINs with a CONFIRM. If the subsequent JOIN doesn't include a CONFIRM for the user (simultaneous join), then she expects to receive one shortly.

== Blocking Join ==
As above, except:
* A user is only added to group membership once all CONFIRMs from her JOIN, and any subsequent CONFIRMS (due to simultaneous join) have been responded to with CONFIRMs.
* In a simultaneous JOIN case, the JOINs are handled based on the server ordering (earliest first).

Example: Alice and Bob are existing members. Charlie and Dave send simultaneous JOINs, but the server places Charlie's first. Alice and Bob send CONFIRM messages to both Charlie and Dave. Charlie and Dave send CONFIRM messages to each other. Once Charlie receive Alice and Bob's CONFIRMs, he's part of the group and can send DATA. Once Dave receives Alice, Bob, and Charlie's CONFIRMs, he's part of the group and can send DATA.