wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Review comments

Browse source
This commit is contained in:
Daniel Wagner-Hall 2015-10-02 08:33:12 -05:00
parent 9cda004848
commit 9d8dc7971d
3 changed files with 80 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

12
event-schemas/examples/v1/m.room.member
View file

@ -4,11 +4,13 @@
"membership": "join", "membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid", "displayname": "Alice Margatroid",
"token": "pc98", "third_party_invite": {
"public_key": "abc123", "token": "pc98",
"key_validity_url": "https://magic.forest/verifykey", "public_key": "abc123",
"signature": "q1w2e3", "key_validity_url": "https://magic.forest/verifykey",
"sender": "@zun:zun.soft" "signature": "q1w2e3",
"sender": "@zun:zun.soft"
}
}, },
"state_key": "@alice:localhost", "state_key": "@alice:localhost",
"origin_server_ts": 1431961217939, "origin_server_ts": 1431961217939,

47
event-schemas/schema/v1/m.room.member
View file

@ -22,26 +22,33 @@
"type": ["string", "null"], "type": ["string", "null"],
"description": "The display name for this user, if any. This is added by the homeserver." "description": "The display name for this user, if any. This is added by the homeserver."
}, },
"token": { "third_party_invite": {
"type": "string", "type": "object",
"description": "A token which must be correctly signed, in order to join the room." "title": "invite",
}, "properties": {
"key_validity_url": { "token": {
"type": "string", "type": "string",
"description": "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'." "description": "A token which must be correctly signed, in order to join the room."
}, },
"public_key": { "key_validity_url": {
"type": "string", "type": "string",
"description": "A base64-encoded ed25519 key with which token must be signed." "description": "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
}, },
"signature": { "public_key": {
"type": "string", "type": "string",
"description": "A base64-encoded signature of token with public_key." "description": "A base64-encoded ed25519 key with which token must be signed."
}, },
"sender": { "signature": {
"type": "string", "type": "string",
"description": "The matrix user ID of the user who send the invite which is being used." "description": "A base64-encoded signature of token with public_key."
} },
"sender": {
"type": "string",
"description": "The matrix user ID of the user who send the invite which is being used."
}
},
"required": ["token", "key_validity_url", "public_key", "signature", "sender"]
}
}, },
"required": ["membership"] "required": ["membership"]
}, },

52
specification/modules/third_party_invites.rst
View file

@ -7,6 +7,22 @@ This module adds in support for inviting new members to a room where their
Matrix user ID is not known, instead addressing them by a third party identifier Matrix user ID is not known, instead addressing them by a third party identifier
such as an email address. such as an email address.
There are two flows here; one if a Matrix user ID is known for the third party
identifier, and one if not. Either way, the client calls /invite with the
details of the third party identifier.
The homeserver asks the identity server whether a Matrix user ID is known for
that identifier. If it is, an invite is simply issued for that user.
If it is not, the homeserver asks the identity server to record the details of
the invitation, and to notify the client of this pending invitation if it gets
a binding for this identifier in the future. The identity server returns to the
homeserver a token, as well as its public key.
If a client then tries to join the room in the future, it will be allowed to if
it presents both the token, and a signature of that token from the identity
server which can be verified with the public key.
Events Events
------ ------
@ -17,23 +33,47 @@ Client behaviour
A client asks a server to invite a user by their third party identifier. A client asks a server to invite a user by their third party identifier.
See the documentation for /invite for more information.
Server behaviour Server behaviour
---------------- ----------------
All homeservers MUST verify that sign(``token``, ``public_key``) = ``signature``. All homeservers MUST verify that sig(``token``, ``public_key``) = ``signature``.
If a client of the current homeserver is joining by an If a client of the current homeserver is joining by an
``m.room.third_party_invite``, that homesever MUST validate that the public ``m.room.third_party_invite``, that homesever MUST validate that the public
key used for signing is still valid, by checking ``key_validity_url``. key used for signing is still valid, by checking ``key_validity_url``. It does
this by making an HTTP GET request to ``key_validity_url``, with the querystring
?public_key=``public_key``. A JSON object will be returned, and the key is
considered valid if the object contains a key named ``valid`` whose value is
``true``. If this cannot be verified, the invitation must be rejected.
If a homeserver is joining a room for the first time because of an If a homeserver is joining a room for the first time because of an
``m.room.third_party_invite``, the server which is already participating in the ``m.room.third_party_invite``, the server which is already participating in the
room MUST validate that the public key used for signing is still valid, by room MUST validate that the public key used for signing is still valid, by
checking ``key_validity_url``. checking ``key_validity_url`` in the above described way.
No other homeservers may reject the joining of the room on the basis of No other homeservers may reject the joining of the room on the basis of
``key_validity_url``, this is so that all homeservers have a consistent view of ``key_validity_url``, this is so that all homeservers have a consistent view of
the room. the room. They may, however, indicate to their clients that a member's'
membership is questionable.
For example:
If room R has two participating homeservers, H1, H2
And user A on H1 invites a third party identifier to room R
H1 asks the identity server for a binding to a Matrix user ID, and has none,
so issues an ``m.room.third_party_invite`` event to the room.
When the third party user validates their identity, they are told about the
invite, and ask their homeserver, H3, to join the room.
H3 validates that sign(``token``, ``public_key``) = ``signature``, and may check
``key_validity_url``.
H3 then asks H1 to join it to the room. H1 *must* validate that
sign(``token``, ``public_key``) = ``signature`` *and* check ``key_validity_url``.
Having validated these things, H1 writes the join event to the room, and H3
begins participating in the room. H2 *must* accept this event.