10 files changed, 114 insertions, 9 deletions

diff --git a/docs/client-server/howto.rst b/docs/client-server/howto.rst
index c02ea8d897..ec941edddd 100644
--- a/docs/client-server/howto.rst
+++ b/docs/client-server/howto.rst
@@ -24,7 +24,7 @@ If you already have an account, you must **login** into it.
 
 `Try out the fiddle`__
 
-.. __: http://jsfiddle.net/4q2jyxng/
+.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/register_login
 
 Registration
 ------------
@@ -87,7 +87,7 @@ user and **send a message** to that room.
 
 `Try out the fiddle`__
 
-.. __: http://jsfiddle.net/zL3zto9g/
+.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/create_room_send_msg
 
 Creating a room
 ---------------
@@ -137,7 +137,7 @@ join a room **via a room alias** if one was set up.
 
 `Try out the fiddle`__
 
-.. __: http://jsfiddle.net/7fhotf1b/
+.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/room_memberships
 
 Inviting a user to a room
 -------------------------
@@ -183,7 +183,7 @@ of getting events, depending on what the client already knows.
 
 `Try out the fiddle`__
 
-.. __: http://jsfiddle.net/vw11mg37/
+.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/event_stream
 
 Getting all state
 -----------------
@@ -633,4 +633,4 @@ application.
 
 `Try out the fiddle`__
 
-.. __: http://jsfiddle.net/uztL3yme/
+.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/example_app
diff --git a/docs/model/presence.rst b/docs/client-server/model/presence.rst
index 7e54505364..7e54505364 100644
--- a/docs/model/presence.rst
+++ b/docs/client-server/model/presence.rst
diff --git a/docs/model/profiles.rst b/docs/client-server/model/profiles.rst
index f7d6bd5679..f7d6bd5679 100644
--- a/docs/model/profiles.rst
+++ b/docs/client-server/model/profiles.rst
diff --git a/docs/model/protocol_examples.rst b/docs/client-server/model/protocol_examples.rst
index 61a599b432..61a599b432 100644
--- a/docs/model/protocol_examples.rst
+++ b/docs/client-server/model/protocol_examples.rst
diff --git a/docs/model/room-join-workflow.rst b/docs/client-server/model/room-join-workflow.rst
index c321a64fab..c321a64fab 100644
--- a/docs/model/room-join-workflow.rst
+++ b/docs/client-server/model/room-join-workflow.rst
diff --git a/docs/model/rooms.rst b/docs/client-server/model/rooms.rst
index 0007e48e30..0007e48e30 100644
--- a/docs/model/rooms.rst
+++ b/docs/client-server/model/rooms.rst
diff --git a/docs/model/terminology.rst b/docs/client-server/model/terminology.rst
index cc6e6760ac..cc6e6760ac 100644
--- a/docs/model/terminology.rst
+++ b/docs/client-server/model/terminology.rst
diff --git a/docs/model/third-party-id.rst b/docs/client-server/model/third-party-id.rst
index 1f8138ddf7..1f8138ddf7 100644
--- a/docs/model/third-party-id.rst
+++ b/docs/client-server/model/third-party-id.rst
diff --git a/docs/human-id-rules.rst b/docs/human-id-rules.rst
new file mode 100644
index 0000000000..3a1ff39892
--- /dev/null
+++ b/docs/human-id-rules.rst
@@ -0,0 +1,79 @@
+This document outlines the format for human-readable IDs within matrix.
+
+Overview
+--------
+UTF-8 is quickly becoming the standard character encoding set on the web. As
+such, Matrix requires that all strings MUST be encoded as UTF-8. However,
+using Unicode as the character set for human-readable IDs is troublesome. There
+are many different characters which appear identical to each other, but would
+identify different users. In addition, there are non-printable characters which
+cannot be rendered by the end-user. This opens up a security vulnerability with
+phishing/spoofing of IDs, commonly known as a homograph attack.
+
+Web browers encountered this problem when International Domain Names were
+introduced. A variety of checks were put in place in order to protect users. If
+an address failed the check, the raw punycode would be displayed to disambiguate
+the address. Similar checks are performed by home servers in Matrix. However, 
+Matrix does not use punycode representations, and so does not show raw punycode 
+on a failed check. Instead, home servers must outright reject these misleading 
+IDs.
+
+Types of human-readable IDs
+---------------------------
+There are two main human-readable IDs in question:
+
+- Room aliases
+- User IDs
+ 
+Room aliases look like ``#localpart:domain``. These aliases point to opaque
+non human-readable room IDs. These pointers can change, so there is already an
+issue present with the same ID pointing to a different destination at a later
+date.
+
+User IDs look like ``@localpart:domain``. These represent actual end-users, and
+unlike room aliases, there is no layer of indirection. This presents a much
+greater concern with homograph attacks. 
+
+Checks
+------
+- Similar to web browsers.
+- blacklisted chars (e.g. non-printable characters)
+- mix of language sets from 'preferred' language not allowed. 
+- Language sets from CLDR dataset.
+- Treated in segments (localpart, domain)
+- Additional restrictions for ease of processing IDs.
+   - Room alias localparts MUST NOT have ``#`` or ``:``.
+   - User ID localparts MUST NOT have ``@`` or ``:``.
+
+Rejecting
+---------
+- Home servers MUST reject room aliases which do not pass the check, both on 
+  GETs and PUTs.
+- Home servers MUST reject user ID localparts which do not pass the check, both
+  on creation and on events.
+- Any home server whose domain does not pass this check, MUST use their punycode
+  domain name instead of the IDN, to prevent other home servers rejecting you.
+- Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing 
+  due to homograph attacks, and failing due to including ``:`` s, etc)
+- Error message MAY go into further information about which characters were
+  rejected and why.
+- Error message SHOULD contain a ``failed_keys`` key which contains an array
+  of strings which represent the keys which failed the check e.g::
+  
+    failed_keys: [ user_id, room_alias ]
+  
+Other considerations
+--------------------
+- Basic security: Informational key on the event attached by HS to say "unsafe 
+  ID". Problem: clients can just ignore it, and since it will appear only very
+  rarely, easy to forget when implementing clients.
+- Moderate security: Requires client handshake. Forces clients to implement
+  a check, else they cannot communicate with the misleading ID. However, this is
+  extra overhead in both client implementations and round-trips.
+- High security: Outright rejection of the ID at the point of creation / 
+  receiving event. Point of creation rejection is preferable to avoid the ID
+  entering the system in the first place. However, malicious HSes can just allow
+  the ID. Hence, other home servers must reject them if they see them in events.
+  Client never sees the problem ID, provided the HS is correctly implemented.
+- High security decided; client doesn't need to worry about it, no additional
+  protocol complexity aside from rejection of an event.
\ No newline at end of file
diff --git a/docs/specification.rst b/docs/specification.rst
index acfe47605d..b06f14f8c9 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -1182,16 +1182,16 @@ This event is sent by the caller when they wish to establish a call.
     - ``type`` : "string" - The type of session description, in this case 'offer'
     - ``sdp`` : "string" - The SDP text of the session description
 
-``m.call.candidate``
+``m.call.candidates``
 This event is sent by callers after sending an invite and by the callee after answering.
-Its purpose is to give the other party an additional ICE candidate to try using to
+Its purpose is to give the other party additional ICE candidates to try using to
 communicate.
 
   Required keys:
     - ``call_id`` : "string" - The ID of the call this event relates to
     - ``version`` : "integer" - The version of the VoIP specification this messages
                                 adheres to. his specification is version 0.
-    - ``candidate`` : "candidate object" - Object describing the candidate.
+    - ``candidates`` : "array of candidate objects" - Array of object describing the candidates.
 
 ``Candidate Object``
 
@@ -1249,7 +1249,33 @@ Or a rejected call:
                  <------- m.call.hangup
 
 Calls are negotiated according to the WebRTC specification.
- 
+
+
+Glare
+-----
+This specification aims to address the problem of two users calling each other
+at roughly the same time and their invites crossing on the wire. It is a far
+better experience for the users if their calls are connected if it is clear
+that their intention is to set up a call with one another.
+
+In Matrix, calls are to rooms rather than users (even if those rooms may only
+contain one other user) so we consider calls which are to the same room.
+
+The rules for dealing with such a situation are as follows:
+
+ - If an invite to a room is received whilst the client is preparing to send an
+   invite to the same room, the client should cancel its outgoing call and
+   instead automatically accept the incoming call on behalf of the user.
+ - If an invite to a room is received after the client has sent an invite to the
+   same room and is waiting for a response, the client should perform a
+   lexicographical comparison of the call IDs of the two calls and use the
+   lesser of the two calls, aborting the greater. If the incoming call is the
+   lesser, the client should accept this call on behalf of the user.
+
+The call setup should appear seamless to the user as if they had simply placed
+a call and the other party had accepted. Thusly, any media stream that had been
+setup for use on a call should be transferred and used for the call that
+replaces it.
  
 Profiles
 ========