diff --git a/changelogs/client_server/newsfragments/2985.clarification b/changelogs/client_server/newsfragments/2985.clarification new file mode 100644 index 000000000..d3c768e3b --- /dev/null +++ b/changelogs/client_server/newsfragments/2985.clarification @@ -0,0 +1 @@ +Correct examples of `client_secret` request body parameters so that they do not include invalid characters. diff --git a/changelogs/identity_service/newsfragments/3170.removal b/changelogs/identity_service/newsfragments/3170.removal new file mode 100644 index 000000000..c43ca64d7 --- /dev/null +++ b/changelogs/identity_service/newsfragments/3170.removal @@ -0,0 +1 @@ +The v1 identity service API has been removed in favour of the v2 API, as per [MSC2713](https://github.com/matrix-org/matrix-doc/pull/2713). \ No newline at end of file diff --git a/content/appendices.md b/content/appendices.md index 38bf6397d..67c41f98a 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -590,32 +590,6 @@ Event IDs and Room IDs are case-sensitive. They are not meant to be human-readable. They are intended to be treated as fully opaque strings by clients. -#### Group Identifiers - -Groups within Matrix are uniquely identified by their group ID. The -group ID is namespaced to the group server which hosts this group and -has the form: - - +localpart:domain - -The `localpart` of a group ID is an opaque identifier for that group. It -MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`, -`.`, `_`, `=`, `-`, and `/`. - -The `domain` of a group ID is the [server name](#server-name) of the -group server which hosts this group. - -The length of a group ID, including the `+` sigil and the domain, MUST -NOT exceed 255 characters. - -The complete grammar for a legal group ID is: - - group_id = "+" group_id_localpart ":" server_name - group_id_localpart = 1*group_id_char - group_id_char = DIGIT - / %x61-7A ; a-z - / "-" / "." / "=" / "_" / "/" - #### Room Aliases A room may have zero or more aliases. A room alias has the format: @@ -674,7 +648,6 @@ Examples of matrix.to URIs are: - Permalink by room alias: `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org` - User: `https://matrix.to/#/%40alice%3Aexample.org` -- Group: `https://matrix.to/#/%2Bexample%3Aexample.org` {{% boxes/note %}} Historically, clients have not produced URIs which are fully encoded. @@ -690,6 +663,16 @@ versions](/#room-versions). These slashes should normally be encoded when producing matrix.to URIs, however. {{% /boxes/note %}} +{{% boxes/note %}} + +In prior versions of this specification, a concept of "groups" were mentioned +to organize rooms. This functionality did not properly get introduced into +the specification and is subsequently replaced with "Spaces". Historical +matrix.to URIs pointing to groups might still exist: they take the form +`https://matrix.to/#/%2Bexample%3Aexample.org` (where the `+` sigil may or +may not be encoded). +{{% /boxes/note %}} + ##### Routing Room IDs are not routable on their own as there is no reliable domain to diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 3c208c759..07fe9d962 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -297,7 +297,7 @@ specify parameter values. The flow for this method is as follows: 6. If the `m.identity_server` property is present, extract the `base_url` value for use as the base URL of the identity server. Validation for this URL is done as in the step above, but using - `/_matrix/identity/api/v1` as the endpoint to connect to. If the + `/_matrix/identity/v2` as the endpoint to connect to. If the `m.identity_server` property is present, but does not have a `base_url` value, then `FAIL_PROMPT`. diff --git a/content/identity-service-api.md b/content/identity-service-api.md index ed5e8a0eb..cf0536aba 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -59,48 +59,48 @@ the keys `error` and `errcode` MUST always be present. Some standard error codes are below: -`M_NOT_FOUND` +`M_NOT_FOUND` The resource requested could not be located. -`M_MISSING_PARAMS` +`M_MISSING_PARAMS` The request was missing one or more parameters. -`M_INVALID_PARAM` +`M_INVALID_PARAM` The request contained one or more invalid parameters. -`M_SESSION_NOT_VALIDATED` +`M_SESSION_NOT_VALIDATED` The session has not been validated. -`M_NO_VALID_SESSION` +`M_NO_VALID_SESSION` A session could not be located for the given parameters. -`M_SESSION_EXPIRED` +`M_SESSION_EXPIRED` The session has expired and must be renewed. -`M_INVALID_EMAIL` +`M_INVALID_EMAIL` The email address provided was not valid. -`M_EMAIL_SEND_ERROR` +`M_EMAIL_SEND_ERROR` There was an error sending an email. Typically seen when attempting to verify ownership of a given email address. -`M_INVALID_ADDRESS` +`M_INVALID_ADDRESS` The provided third party address was not valid. -`M_SEND_ERROR` +`M_SEND_ERROR` There was an error sending a notification. Typically seen when attempting to verify ownership of a given third party address. -`M_UNRECOGNIZED` +`M_UNRECOGNIZED` The request contained an unrecognised value, such as an unknown token or medium. -`M_THREEPID_IN_USE` +`M_THREEPID_IN_USE` The third party identifier is already in use by another user. Typically this error will have an additional `mxid` property to indicate who owns the third party identifier. -`M_UNKNOWN` +`M_UNKNOWN` An unknown error has occurred. {{% http-api spec="identity" api="versions" %}} @@ -116,22 +116,6 @@ Matrix user identity, but not in the other direction (i.e. one should not be able to get all 3PIDs associated with a Matrix user ID, or get all 3PIDs associated with a 3PID). -## Version 1 API deprecation - -As described on each of the version 1 endpoints, the v1 API is -deprecated in favour of the v2 API described here. The major difference, -with the exception of a few isolated cases, is that the v2 API requires -authentication to ensure the user has given permission for the identity -server to operate on their data. - -The v1 API is planned to be removed from the specification in a future -version. - -Clients SHOULD attempt the v2 endpoints first, and if they receive a -`404`, `400`, or similar error they should try the v1 endpoint or fail -the operation. Clients are strongly encouraged to warn the user of the -risks in using the v1 API, if they are planning on using it. - ## Web browser clients It is realistic to expect that some clients will be written to be run @@ -149,12 +133,9 @@ recommended CORS headers to be returned by servers on all requests are: ## Authentication -Most `v2` endpoints in the Identity Service API require authentication +Most endpoints in the Identity Service API require authentication in order to ensure that the requesting user has accepted all relevant -policies and is otherwise permitted to make the request. The `v1` API -(currently deprecated) does not require this authentication, however -using `v1` is strongly discouraged as it will be removed in a future -release. +policies and is otherwise permitted to make the request. Identity Servers use a scheme similar to the Client-Server API's concept of access tokens to authenticate users. The access tokens provided by an @@ -204,8 +185,6 @@ has just accepted are appended to `m.accepted_terms`. ## Status check -{{% http-api spec="identity" api="ping" %}} - {{% http-api spec="identity" api="v2_ping" %}} ## Key management @@ -219,23 +198,14 @@ The identity server may also keep track of some short-term public-private keypairs, which may have different usage and lifetime characteristics than the service's long-term keys. -{{% http-api spec="identity" api="pubkey" %}} - {{% http-api spec="identity" api="v2_pubkey" %}} ## Association lookup -{{% http-api spec="identity" api="lookup" %}} - {{% http-api spec="identity" api="v2_lookup" %}} ### Client behaviour -{{% boxes/note %}} -This section only covers the v2 lookup endpoint. The v1 endpoint is -described in isolation above. -{{% /boxes/note %}} - Prior to performing a lookup clients SHOULD make a request to the `/hash_details` endpoint to determine what algorithms the server supports (described in more detail below). The client then uses this @@ -246,11 +216,6 @@ Clients MUST support at least the `sha256` algorithm. ### Server behaviour -{{% boxes/note %}} -This section only covers the v2 lookup endpoint. The v1 endpoint is -described in isolation above. -{{% /boxes/note %}} - Servers, upon receipt of a `/lookup` request, will compare the query against known bindings it has, hashing the identifiers it knows about as needed to verify exact matches to the request. @@ -400,20 +365,14 @@ through without modification. ### Email associations -{{% http-api spec="identity" api="email_associations" %}} - {{% http-api spec="identity" api="v2_email_associations" %}} ### Phone number associations -{{% http-api spec="identity" api="phone_associations" %}} - {{% http-api spec="identity" api="v2_phone_associations" %}} ### General -{{% http-api spec="identity" api="associations" %}} - {{% http-api spec="identity" api="v2_associations" %}} ## Invitation storage @@ -429,8 +388,6 @@ the Matrix user's homeserver via the endpoint. The request MUST be signed with a long-term private key for the identity server. -{{% http-api spec="identity" api="store_invite" %}} - {{% http-api spec="identity" api="v2_store_invite" %}} ## Ephemeral invitation signing @@ -440,6 +397,4 @@ identity server offers some crypto functionality to help in accepting invitations. This is less secure than the client doing it itself, but may be useful where this isn't possible. -{{% http-api spec="identity" api="invitation_signing" %}} - {{% http-api spec="identity" api="v2_invitation_signing" %}} diff --git a/content/proposals.md b/content/proposals.md index 28cb670c3..4a2367018 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -245,10 +245,13 @@ is as follows: 75% of the members of the Spec Core Team agree on its outcome, and all existing concerns have been resolved. - The FCP will then begin and last for 5 days, giving anyone else some - time to speak up before it concludes. On its conclusion, the - disposition of the FCP will be carried out. If sufficient reasoning - against the disposition is raised, the FCP can be cancelled and the - MSC will continue to evolve accordingly. + time to speak up before it concludes. If sufficient reasoning + against the disposition is provided, a member of the Spec Core Team can + raise a concern and block FCP from completing. This will not reset or + pause the 5 day FCP timer, but FCP will not conclude until all concerns have + been resolved. If sufficient change in the MSC is required to resolve those + concerns, FCP might be cancelled and reproposed. Once FCP has concluded, + the disposition of the FCP will be carried out. - Once the proposal has been accepted and merged, it is time to submit the actual change to the Specification that your proposal reasoned about. This is known as a spec PR. However in order for the spec PR @@ -259,7 +262,7 @@ is as follows: will warrant another MSC. Any minor, non-fundamental changes are allowed but **must** be documented in the original proposal document. This ensures that someone reading a proposal in the future - doesn't assume old information wasn't merged into the spec. + doesn't assume old information that wasn't merged into the spec. - Similar to the proposal PR, please sign off the spec PR as per the guidelines on [CONTRIBUTING.rst](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst). @@ -373,7 +376,7 @@ be merged without the Spec Core Team focusing on them specifically. ## Implementing a proposal -As part of the proposal process the spec core team will require evidence +As part of the proposal process the Spec Core Team will require evidence of the MSC working in order for it to move into FCP. This can usually be a branch/pull request to whichever implementation of choice that proves the MSC works in practice, though in some cases the MSC itself will be @@ -388,13 +391,11 @@ release, implementations are required to use the following process to ensure that the official Matrix namespace is not cluttered with development or testing data. -Note - -Unreleased implementations (including proofs-of-concept demonstrating +**Note:** Unreleased implementations (including proofs-of-concept demonstrating that a particular MSC works) do not have to follow this process. 1. Have an idea for a feature. -2. Implement the feature using unstable endpoints, vendor prefixes, and +1. Implement the feature using unstable endpoints, vendor prefixes, and unstable feature flags as appropriate. - When using unstable endpoints, they MUST include a vendor prefix. For example: @@ -429,22 +430,25 @@ that a particular MSC works) do not have to follow this process. - If at any point after early release, the idea changes in a backwards-incompatible way, the feature flag should also change so that implementations can adapt as needed. -3. In parallel, or ahead of implementation, open an MSC and solicit +1. In parallel, or ahead of implementation, open an MSC and solicit review per above. -4. Before FCP can be called, the Spec Core Team will require evidence +1. Before FCP can be called, the Spec Core Team will require evidence of the MSC working as proposed. A typical example of this is an implementation of the MSC, though the implementation does not need to be shipped anywhere and can therefore avoid the forwards/backwards compatibility concerns mentioned here. -5. The FCP process is completed, and assuming nothing is flagged the +1. The FCP process is completed, and assuming nothing is flagged the MSC lands. -6. A spec PR is written to incorporate the changes into Matrix. -7. A spec release happens. -8. Implementations switch to using stable prefixes (e.g.: `/r0`) if the - server supports the specification version released. If the server - doesn't advertise the specification version, but does have the - feature flag, unstable prefixes should still be used. -9. A transition period of about 2 months starts immediately after the +1. Implementations can now switch to using stable prefixes + (for example, for an endpoint, moving from + `/unstable/org.matrix.mscxxxx/frobnicate` + to `/v1/frobnicate`), assuming that the change + is backwards compatible with older implementations. In the rare occasion + where backwards compatibility is not possible without a new spec release, + implementations should continue to use unstable prefixes. +1. A spec PR is written to incorporate the changes into Matrix. +1. A spec release happens. +1. A transition period of about 2 months starts immediately after the spec release, before implementations start to encourage other implementations to switch to stable endpoints. For example, a server implementation should start asking client implementations to support @@ -463,9 +467,9 @@ com.example/new/endpoint`. In summary: -- Implementations MUST NOT use stable endpoints before the MSC is in - the spec. This includes NOT using stable endpoints in the period - between completion of FCP and release of the spec. passed. +- Implementations MUST NOT use stable endpoints before the MSC has + completed FCP. Once that has occurred, implementations are allowed + to use stable endpoints, but are not required to. - Implementations are able to ship features that are exposed to users by default before an MSC has been merged to the spec, provided they follow the process above. diff --git a/data-definitions/sas-emoji-v1-i18n/hu.json b/data-definitions/sas-emoji-v1-i18n/hu.json new file mode 100644 index 000000000..01d567306 --- /dev/null +++ b/data-definitions/sas-emoji-v1-i18n/hu.json @@ -0,0 +1,66 @@ +{ + "Pin": "Rajszeg", + "Folder": "Mappa", + "Headphones": "Fejhallgató", + "Anchor": "Horgony", + "Bell": "Harang", + "Trumpet": "Trombita", + "Guitar": "Gitár", + "Ball": "Labda", + "Trophy": "Trófea", + "Rocket": "Rakáta", + "Aeroplane": "Repülő", + "Bicycle": "Kerékpár", + "Train": "Vonat", + "Flag": "Zászló", + "Telephone": "Telefon", + "Hammer": "Kalapács", + "Key": "Kulcs", + "Lock": "Lakat", + "Scissors": "Olló", + "Paperclip": "Gémkapocs", + "Pencil": "Ceruza", + "Book": "Könyv", + "Light Bulb": "Égő", + "Gift": "Ajándék", + "Clock": "Óra", + "Hourglass": "Homokóra", + "Umbrella": "Esernyő", + "Thumbs Up": "Hüvelykujj fel", + "Santa": "Télapó", + "Spanner": "Csavarkulcs", + "Glasses": "Szemüveg", + "Hat": "Kalap", + "Robot": "Robot", + "Smiley": "Mosoly", + "Heart": "Szív", + "Cake": "Süti", + "Pizza": "Pizza", + "Corn": "Kukorica", + "Strawberry": "Eper", + "Apple": "Alma", + "Banana": "Banán", + "Fire": "Tűz", + "Cloud": "Felhő", + "Moon": "Hold", + "Globe": "Földgömb", + "Mushroom": "Gomba", + "Cactus": "Kaktusz", + "Tree": "Fa", + "Flower": "Virág", + "Butterfly": "Pillangó", + "Octopus": "Polip", + "Fish": "Hal", + "Turtle": "Teknős", + "Penguin": "Pingvin", + "Rooster": "Kakas", + "Panda": "Panda", + "Rabbit": "Nyúl", + "Elephant": "Elefánt", + "Pig": "Malac", + "Unicorn": "Egyszarvú", + "Horse": "Ló", + "Lion": "Oroszlán", + "Cat": "Macska", + "Dog": "Kutya" +} diff --git a/data-definitions/sas-emoji.json b/data-definitions/sas-emoji.json index 0b213d9db..f0eb702cf 100644 --- a/data-definitions/sas-emoji.json +++ b/data-definitions/sas-emoji.json @@ -16,6 +16,7 @@ "fi": "Koira", "fr": "Chien", "hr": "pas", + "hu": "Kutya", "it": "Cane", "ja": "犬", "nb_NO": "Hund", @@ -49,6 +50,7 @@ "fi": "Kissa", "fr": "Chat", "hr": "mačka", + "hu": "Macska", "it": "Gatto", "ja": "猫", "nb_NO": "Katt", @@ -82,6 +84,7 @@ "fi": "Leijona", "fr": "Lion", "hr": "lav", + "hu": "Oroszlán", "it": "Leone", "ja": "ライオン", "nb_NO": "Løve", @@ -115,6 +118,7 @@ "fi": "Hevonen", "fr": "Cheval", "hr": "konj", + "hu": "Ló", "it": "Cavallo", "ja": "馬", "nb_NO": "Hest", @@ -148,6 +152,7 @@ "fi": "Yksisarvinen", "fr": "Licorne", "hr": "jednorog", + "hu": "Egyszarvú", "it": "Unicorno", "ja": "ユニコーン", "nb_NO": "Enhjørning", @@ -181,6 +186,7 @@ "fi": "Sika", "fr": "Cochon", "hr": "svinja", + "hu": "Malac", "it": "Maiale", "ja": "ブタ", "nb_NO": "Gris", @@ -214,6 +220,7 @@ "fi": "Norsu", "fr": "Éléphant", "hr": "slon", + "hu": "Elefánt", "it": "Elefante", "ja": "ゾウ", "nb_NO": "Elefant", @@ -247,6 +254,7 @@ "fi": "Kani", "fr": "Lapin", "hr": "zec", + "hu": "Nyúl", "it": "Coniglio", "ja": "うさぎ", "nb_NO": "Kanin", @@ -280,6 +288,7 @@ "fi": "Panda", "fr": "Panda", "hr": "panda", + "hu": "Panda", "it": "Panda", "ja": "パンダ", "nb_NO": "Panda", @@ -313,6 +322,7 @@ "fi": "Kukko", "fr": "Coq", "hr": "kokot", + "hu": "Kakas", "it": "Gallo", "ja": "ニワトリ", "nb_NO": "Hane", @@ -346,6 +356,7 @@ "fi": "Pingviini", "fr": "Manchot", "hr": "pingvin", + "hu": "Pingvin", "it": "Pinguino", "ja": "ペンギン", "nb_NO": "Pingvin", @@ -379,6 +390,7 @@ "fi": "Kilpikonna", "fr": "Tortue", "hr": "kornjača", + "hu": "Teknős", "it": "Tartaruga", "ja": "亀", "nb_NO": "Skilpadde", @@ -412,6 +424,7 @@ "fi": "Kala", "fr": "Poisson", "hr": "riba", + "hu": "Hal", "it": "Pesce", "ja": "魚", "nb_NO": "Fisk", @@ -445,6 +458,7 @@ "fi": "Tursas", "fr": "Poulpe", "hr": "hobotnica", + "hu": "Polip", "it": "Polpo", "ja": "たこ", "nb_NO": "Blekksprut", @@ -478,6 +492,7 @@ "fi": "Perhonen", "fr": "Papillon", "hr": "leptir", + "hu": "Pillangó", "it": "Farfalla", "ja": "ちょうちょ", "nb_NO": "Sommerfugl", @@ -511,6 +526,7 @@ "fi": "Kukka", "fr": "Fleur", "hr": "svijet", + "hu": "Virág", "it": "Fiore", "ja": "花", "nb_NO": "Blomst", @@ -544,6 +560,7 @@ "fi": "Puu", "fr": "Arbre", "hr": "drvo", + "hu": "Fa", "it": "Albero", "ja": "木", "nb_NO": "Tre", @@ -577,6 +594,7 @@ "fi": "Kaktus", "fr": "Cactus", "hr": "kaktus", + "hu": "Kaktusz", "it": "Cactus", "ja": "サボテン", "nb_NO": "Kaktus", @@ -610,6 +628,7 @@ "fi": "Sieni", "fr": "Champignon", "hr": "gljiva", + "hu": "Gomba", "it": "Fungo", "ja": "きのこ", "nb_NO": "Sopp", @@ -643,6 +662,7 @@ "fi": "Maapallo", "fr": "Globe", "hr": "Globus", + "hu": "Földgömb", "it": "Globo", "ja": "地球", "nb_NO": "Globus", @@ -676,6 +696,7 @@ "fi": "Kuu", "fr": "Lune", "hr": "mjesec", + "hu": "Hold", "it": "Luna", "ja": "月", "nb_NO": "Måne", @@ -709,6 +730,7 @@ "fi": "Pilvi", "fr": "Nuage", "hr": "oblak", + "hu": "Felhő", "it": "Nuvola", "ja": "雲", "nb_NO": "Sky", @@ -742,6 +764,7 @@ "fi": "Tuli", "fr": "Feu", "hr": "vatra", + "hu": "Tűz", "it": "Fuoco", "ja": "炎", "nb_NO": "Flamme", @@ -775,6 +798,7 @@ "fi": "Banaani", "fr": "Banane", "hr": "banana", + "hu": "Banán", "it": "Banana", "ja": "バナナ", "nb_NO": "Banan", @@ -808,6 +832,7 @@ "fi": "Omena", "fr": "Pomme", "hr": "jabuka", + "hu": "Alma", "it": "Mela", "ja": "リンゴ", "nb_NO": "Eple", @@ -841,6 +866,7 @@ "fi": "Mansikka", "fr": "Fraise", "hr": "jagoda", + "hu": "Eper", "it": "Fragola", "ja": "いちご", "nb_NO": "Jordbær", @@ -874,6 +900,7 @@ "fi": "Maissi", "fr": "Maïs", "hr": "kukuruza", + "hu": "Kukorica", "it": "Mais", "ja": "とうもろこし", "nb_NO": "Mais", @@ -907,6 +934,7 @@ "fi": "Pizza", "fr": "Pizza", "hr": "pizza", + "hu": "Pizza", "it": "Pizza", "ja": "ピザ", "nb_NO": "Pizza", @@ -940,6 +968,7 @@ "fi": "Kakku", "fr": "Gâteau", "hr": "torta", + "hu": "Süti", "it": "Torta", "ja": "ケーキ", "nb_NO": "Kake", @@ -973,6 +1002,7 @@ "fi": "Sydän", "fr": "Cœur", "hr": "srca", + "hu": "Szív", "it": "Cuore", "ja": "ハート", "nb_NO": "Hjerte", @@ -1006,6 +1036,7 @@ "fi": "Hymynaama", "fr": "Sourire", "hr": "smajlića", + "hu": "Mosoly", "it": "Faccina sorridente", "ja": "スマイル", "nb_NO": "Smilefjes", @@ -1039,6 +1070,7 @@ "fi": "Robotti", "fr": "Robot", "hr": "robot", + "hu": "Robot", "it": "Robot", "ja": "ロボと", "nb_NO": "Robot", @@ -1072,6 +1104,7 @@ "fi": "Hattu", "fr": "Chapeau", "hr": "kapa", + "hu": "Kalap", "it": "Cappello", "ja": "帽子", "nb_NO": "Hatt", @@ -1105,6 +1138,7 @@ "fi": "Silmälasit", "fr": "Lunettes", "hr": "naočale", + "hu": "Szemüveg", "it": "Occhiali", "ja": "めがね", "nb_NO": "Briller", @@ -1138,6 +1172,7 @@ "fi": "Kiintoavain", "fr": "Clé à molette", "hr": "ključ", + "hu": "Csavarkulcs", "it": "Chiave inglese", "ja": "スパナ", "nb_NO": "Fastnøkkel", @@ -1171,6 +1206,7 @@ "fi": "Joulupukki", "fr": "Père Noël", "hr": "deda Mraz", + "hu": "Télapó", "it": "Babbo Natale", "ja": "サンタ", "nb_NO": "Julenisse", @@ -1204,6 +1240,7 @@ "fi": "Peukalo ylös", "fr": "Pouce en l’air", "hr": "palac gore", + "hu": "Hüvelykujj fel", "it": "Pollice alzato", "ja": "いいね", "nb_NO": "Tommel Opp", @@ -1237,6 +1274,7 @@ "fi": "Sateenvarjo", "fr": "Parapluie", "hr": "kišobran", + "hu": "Esernyő", "it": "Ombrello", "ja": "傘", "nb_NO": "Paraply", @@ -1270,6 +1308,7 @@ "fi": "Tiimalasi", "fr": "Sablier", "hr": "pješčani sat", + "hu": "Homokóra", "it": "Clessidra", "ja": "砂時計", "nb_NO": "Timeglass", @@ -1303,6 +1342,7 @@ "fi": "Pöytäkello", "fr": "Réveil", "hr": "sat", + "hu": "Óra", "it": "Orologio", "ja": "時計", "nb_NO": "Klokke", @@ -1336,6 +1376,7 @@ "fi": "Lahja", "fr": "Cadeau", "hr": "poklon", + "hu": "Ajándék", "it": "Regalo", "ja": "ギフト", "nb_NO": "Gave", @@ -1369,6 +1410,7 @@ "fi": "Hehkulamppu", "fr": "Ampoule", "hr": "žarulja", + "hu": "Égő", "it": "Lampadina", "ja": "電球", "nb_NO": "Lyspære", @@ -1402,6 +1444,7 @@ "fi": "Kirja", "fr": "Livre", "hr": "knjiga", + "hu": "Könyv", "it": "Libro", "ja": "本", "nb_NO": "Bok", @@ -1435,6 +1478,7 @@ "fi": "Lyijykynä", "fr": "Crayon", "hr": "olovka", + "hu": "Ceruza", "it": "Matita", "ja": "鉛筆", "nb_NO": "Blyant", @@ -1468,6 +1512,7 @@ "fi": "Paperiliitin", "fr": "Trombone", "hr": "spajalica", + "hu": "Gémkapocs", "it": "Graffetta", "ja": "クリップ", "nb_NO": "BInders", @@ -1501,6 +1546,7 @@ "fi": "Sakset", "fr": "Ciseaux", "hr": "škare", + "hu": "Olló", "it": "Forbici", "ja": "はさみ", "nb_NO": "Saks", @@ -1534,6 +1580,7 @@ "fi": "Lukko", "fr": "Cadenas", "hr": "zaključati", + "hu": "Lakat", "it": "Lucchetto", "ja": "錠前", "nb_NO": "Lås", @@ -1567,6 +1614,7 @@ "fi": "Avain", "fr": "Clé", "hr": "ključ", + "hu": "Kulcs", "it": "Chiave", "ja": "鍵", "nb_NO": "Nøkkel", @@ -1600,6 +1648,7 @@ "fi": "Vasara", "fr": "Marteau", "hr": "čekić", + "hu": "Kalapács", "it": "Martello", "ja": "金槌", "nb_NO": "Hammer", @@ -1633,6 +1682,7 @@ "fi": "Puhelin", "fr": "Téléphone", "hr": "telefon", + "hu": "Telefon", "it": "Telefono", "ja": "電話機", "nb_NO": "Telefon", @@ -1666,6 +1716,7 @@ "fi": "Lippu", "fr": "Drapeau", "hr": "zastava", + "hu": "Zászló", "it": "Bandiera", "ja": "旗", "nb_NO": "Flagg", @@ -1699,6 +1750,7 @@ "fi": "Juna", "fr": "Train", "hr": "vlak", + "hu": "Vonat", "it": "Treno", "ja": "電車", "nb_NO": "Tog", @@ -1732,6 +1784,7 @@ "fi": "Polkupyörä", "fr": "Vélo", "hr": "bicikl", + "hu": "Kerékpár", "it": "Bicicletta", "ja": "自転車", "nb_NO": "Sykkel", @@ -1765,6 +1818,7 @@ "fi": "Lentokone", "fr": "Avion", "hr": "avion", + "hu": "Repülő", "it": "Aeroplano", "ja": "飛行機", "nb_NO": "Fly", @@ -1798,6 +1852,7 @@ "fi": "Raketti", "fr": "Fusée", "hr": "raketa", + "hu": "Rakáta", "it": "Razzo", "ja": "ロケット", "nb_NO": "Rakett", @@ -1831,6 +1886,7 @@ "fi": "Palkinto", "fr": "Trophée", "hr": "trofej", + "hu": "Trófea", "it": "Trofeo", "ja": "トロフィー", "nb_NO": "Pokal", @@ -1864,6 +1920,7 @@ "fi": "Pallo", "fr": "Ballon", "hr": "lopta", + "hu": "Labda", "it": "Palla", "ja": "ボール", "nb_NO": "Ball", @@ -1897,6 +1954,7 @@ "fi": "Kitara", "fr": "Guitare", "hr": "gitara", + "hu": "Gitár", "it": "Chitarra", "ja": "ギター", "nb_NO": "Gitar", @@ -1930,6 +1988,7 @@ "fi": "Trumpetti", "fr": "Trompette", "hr": "truba", + "hu": "Trombita", "it": "Trombetta", "ja": "トランペット", "nb_NO": "Trompet", @@ -1963,6 +2022,7 @@ "fi": "Soittokello", "fr": "Cloche", "hr": "zvono", + "hu": "Harang", "it": "Campana", "ja": "ベル", "nb_NO": "Bjelle", @@ -1996,6 +2056,7 @@ "fi": "Ankkuri", "fr": "Ancre", "hr": "sidro", + "hu": "Horgony", "it": "Ancora", "ja": "いかり", "nb_NO": "Anker", @@ -2029,6 +2090,7 @@ "fi": "Kuulokkeet", "fr": "Casque audio", "hr": "slušalice", + "hu": "Fejhallgató", "it": "Cuffie", "ja": "ヘッドホン", "nb_NO": "Hodetelefoner", @@ -2062,6 +2124,7 @@ "fi": "Kansio", "fr": "Dossier", "hr": "mapu", + "hu": "Mappa", "it": "Cartella", "ja": "フォルダ", "nb_NO": "Mappe", @@ -2095,6 +2158,7 @@ "fi": "Nuppineula", "fr": "Punaise", "hr": "pribadača", + "hu": "Rajszeg", "it": "Puntina", "ja": "ピン", "nb_NO": "Tegnestift", diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index cea8538e5..9966015b0 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -139,7 +139,7 @@ paths: "id_server": "matrix.org", "id_access_token": "abc123_OpaqueString", "sid": "abc123987", - "client_secret": "d0n'tT3ll" + "client_secret": "d0nt-T3ll" } } responses: @@ -215,7 +215,7 @@ paths: required: ["client_secret", "sid"] example: { "sid": "abc123987", - "client_secret": "d0n'tT3ll" + "client_secret": "d0nt-T3ll" } responses: 200: @@ -233,6 +233,8 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/errors/rate_limited.yaml" + tags: + - User data "/account/3pid/bind": post: summary: Binds a 3PID to the user's account through an Identity Service. @@ -272,7 +274,7 @@ paths: "id_server": "example.org", "id_access_token": "abc123_OpaqueString", "sid": "abc123987", - "client_secret": "d0n'tT3ll" + "client_secret": "d0nt-T3ll" } responses: 200: diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index ec0470c39..ab66bdd9b 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -43,7 +43,7 @@ paths: This API requires the use of an application service access token (`as_token`) instead of a typical client's access_token. This API cannot be invoked by users who are not identified as application services. - operationId: updateAppserviceRoomDirectoryVsibility + operationId: updateAppserviceRoomDirectoryVisibility parameters: - in: path type: string diff --git a/data/api/identity/associations.yaml b/data/api/identity/associations.yaml deleted file mode 100644 index f2d09af1c..000000000 --- a/data/api/identity/associations.yaml +++ /dev/null @@ -1,302 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Establishing Associations API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/3pid/getValidated3pid": - get: - summary: Check whether ownership of a 3pid was validated. - description: |- - Determines if a given 3pid has been validated by a user. - operationId: getValidated3pid - deprecated: true - parameters: - - in: query - type: string - name: sid - description: The Session ID generated by the `requestToken` call. - required: true - x-example: 1234 - - in: query - type: string - name: client_secret - description: The client secret passed to the `requestToken` call. - required: true - x-example: monkeys_are_GREAT - responses: - 200: - description: Validation information for the session. - examples: - application/json: { - "medium": "email", - "validated_at": 1457622739026, - "address": "louise@bobs.burgers" - } - schema: - type: object - properties: - medium: - type: string - description: The medium type of the 3pid. - address: - type: string - description: The address of the 3pid being looked up. - validated_at: - type: integer - description: |- - Timestamp, in milliseconds, indicating the time that the 3pid - was validated. - required: ['medium', 'address', 'validated_at'] - 400: - description: |- - The session has not been validated. - - If the session has not been validated, then `errcode` will be - `M_SESSION_NOT_VALIDATED`. If the session has timed out, then - `errcode` will be `M_SESSION_EXPIRED`. - examples: - application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: - description: The Session ID or client secret were not found. - examples: - application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/3pid/bind": - post: - summary: Publish an association between a session and a Matrix user ID. - description: |- - Publish an association between a session and a Matrix user ID. - - Future calls to `/lookup` for any of the session\'s 3pids will return - this association. - - Note: for backwards compatibility with previous drafts of this - specification, the parameters may also be specified as - `application/x-form-www-urlencoded` data. However, this usage is - deprecated. - operationId: bind - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:matrix.org" - } - properties: - sid: - type: string - description: The Session ID generated by the `requestToken` call. - client_secret: - type: string - description: The client secret passed to the `requestToken` call. - mxid: - type: string - description: The Matrix user ID to associate with the 3pids. - required: ["sid", "client_secret", "mxid"] - responses: - 200: - description: The association was published. - examples: - application/json: { - "address": "louise@bobs.burgers", - "medium": "email", - "mxid": "@ears:matrix.org", - "not_before": 1428825849161, - "not_after": 4582425849161, - "ts": 1428825849161, - "signatures": { - "matrix.org": { - "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" - } - } - } - schema: - type: object - properties: - address: - type: string - description: The 3pid address of the user being looked up. - medium: - type: string - description: The medium type of the 3pid. - mxid: - type: string - description: The Matrix user ID associated with the 3pid. - not_before: - type: integer - description: A unix timestamp before which the association is not known to be valid. - not_after: - type: integer - description: A unix timestamp after which the association is not known to be valid. - ts: - type: integer - description: The unix timestamp at which the association was verified. - signatures: - type: object - description: |- - The signatures of the verifying identity servers which show that the - association should be trusted, if you trust the verifying identity - services. - $ref: "../../schemas/server-signatures.yaml" - required: - - address - - medium - - mxid - - not_before - - not_after - - ts - - signatures - 400: - description: |- - The association was not published. - - If the session has not been validated, then `errcode` will be - `M_SESSION_NOT_VALIDATED`. If the session has timed out, then - `errcode` will be `M_SESSION_EXPIRED`. - examples: - application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: - description: The Session ID or client secret were not found - examples: - application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/3pid/unbind": - post: - summary: Remove an association between a session and a Matrix user ID. - description: |- - Remove an association between a session and a Matrix user ID. - - Future calls to `/lookup` for any of the session's 3pids will not - return the removed association. - - The identity server should authenticate the request in one of two - ways: - - 1. The request is signed by the homeserver which controls the `user_id`. - 2. The request includes the `sid` and `client_secret` parameters, - as per `/3pid/bind`, which proves ownership of the 3PID. - - If this endpoint returns a JSON Matrix error, that error should be passed - through to the client requesting an unbind through a homeserver, if the - homeserver is acting on behalf of a client. - operationId: unbind - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:example.org", - "threepid": { - "medium": "email", - "address": "monkeys_have_ears@example.org" - } - } - properties: - sid: - type: string - description: The Session ID generated by the `requestToken` call. - client_secret: - type: string - description: The client secret passed to the `requestToken` call. - mxid: - type: string - description: The Matrix user ID to remove from the 3pids. - threepid: - type: object - title: 3PID - description: |- - The 3PID to remove. Must match the 3PID used to generate the session - if using `sid` and `client_secret` to authenticate this request. - properties: - medium: - type: string - description: |- - A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium - of the identifier to unbind. - address: - type: string - description: The 3PID address to remove. - required: ['medium', 'address'] - required: ["threepid", "mxid"] - responses: - 200: - description: The association was successfully removed. - examples: - application/json: {} - schema: - type: object - 400: - description: |- - If the response body is not a JSON Matrix error, the identity server - does not support unbinds. If a JSON Matrix error is in the response - body, the requesting party should respect the error. - 404: - description: |- - If the response body is not a JSON Matrix error, the identity server - does not support unbinds. If a JSON Matrix error is in the response - body, the requesting party should respect the error. - 403: - description: |- - The credentials supplied to authenticate the request were invalid. - This may also be returned if the identity server does not support - the chosen authentication method (such as blocking homeservers from - unbinding identifiers). - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Invalid homeserver signature" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 501: - description: |- - If the response body is not a JSON Matrix error, the identity server - does not support unbinds. If a JSON Matrix error is in the response - body, the requesting party should respect the error. diff --git a/data/api/identity/email_associations.yaml b/data/api/identity/email_associations.yaml deleted file mode 100644 index 6aa7bf4ac..000000000 --- a/data/api/identity/email_associations.yaml +++ /dev/null @@ -1,177 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Email Associations API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/validate/email/requestToken": - post: - summary: Request a token for validating an email address. - description: |- - Create a session for validating an email address. - - The identity server will send an email containing a token. If that - token is presented to the identity server in the future, it indicates - that that user was able to read the email for that email address, and - so we validate ownership of the email address. - - Note that homeservers offer APIs that proxy this API, adding - additional behaviour on top, for example, - `/register/email/requestToken` is designed specifically for use when - registering an account and therefore will inform the user if the email - address given is already registered on the server. - - Note: for backwards compatibility with previous drafts of this - specification, the parameters may also be specified as - `application/x-form-www-urlencoded` data. However, this usage is - deprecated. - operationId: emailRequestToken - deprecated: true - parameters: - - in: body - name: body - schema: - $ref: "definitions/request_email_validation.yaml" - responses: - 200: - description: Session created. - schema: - $ref: "definitions/sid.yaml" - 400: - description: | - An error ocurred. Some possible errors are: - - - `M_INVALID_EMAIL`: The email address provided was invalid. - - `M_EMAIL_SEND_ERROR`: The validation email could not be sent. - examples: - application/json: { - "errcode": "M_INVALID_EMAIL", - "error": "The email address is not valid" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/validate/email/submitToken": - post: - summary: Validate ownership of an email address. - description: |- - Validate ownership of an email address. - - If the three parameters are consistent with a set generated by a - `requestToken` call, ownership of the email address is considered to - have been validated. This does not publish any information publicly, or - associate the email address with any Matrix user ID. Specifically, - calls to `/lookup` will not show a binding. - - The identity server is free to match the token case-insensitively, or - carry out other mapping operations such as unicode - normalisation. Whether to do so is an implementation detail for the - identity server. Clients must always pass on the token without - modification. - - Note: for backwards compatibility with previous drafts of this - specification, the parameters may also be specified as - `application/x-form-www-urlencoded` data. However, this usage is - deprecated. - operationId: emailSubmitTokenPost - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } - properties: - sid: - type: string - description: The session ID, generated by the `requestToken` call. - client_secret: - type: string - description: The client secret that was supplied to the `requestToken` call. - token: - type: string - description: The token generated by the `requestToken` call and emailed to the user. - required: ["sid", "client_secret", "token"] - responses: - 200: - description: - The success of the validation. - examples: - application/json: { - "success": true - } - schema: - type: object - properties: - success: - type: boolean - description: Whether the validation was successful or not. - required: ['success'] - get: - summary: Validate ownership of an email address. - description: |- - Validate ownership of an email address. - - If the three parameters are consistent with a set generated by a - `requestToken` call, ownership of the email address is considered to - have been validated. This does not publish any information publicly, or - associate the email address with any Matrix user ID. Specifically, - calls to `/lookup` will not show a binding. - - Note that, in contrast with the POST version, this endpoint will be - used by end-users, and so the response should be human-readable. - operationId: emailSubmitTokenGet - deprecated: true - parameters: - - in: query - type: string - name: sid - required: true - description: The session ID, generated by the `requestToken` call. - x-example: 1234 - - in: query - type: string - name: client_secret - required: true - description: The client secret that was supplied to the `requestToken` call. - x-example: monkeys_are_GREAT - - in: query - type: string - name: token - required: true - description: The token generated by the `requestToken` call and emailed to the user. - x-example: atoken - responses: - 200: - description: Email address is validated. - "3xx": - description: |- - Email address is validated, and the `next_link` parameter was - provided to the `requestToken` call. The user must be redirected - to the URL provided by the `next_link` parameter. - "4xx": - description: - Validation failed. diff --git a/data/api/identity/invitation_signing.yaml b/data/api/identity/invitation_signing.yaml deleted file mode 100644 index a3d215f2e..000000000 --- a/data/api/identity/invitation_signing.yaml +++ /dev/null @@ -1,97 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Ephemeral Invitation Signing API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/sign-ed25519": - post: - summary: Sign invitation details - description: |- - Sign invitation details. - - The identity server will look up `token` which was stored in a call - to `store-invite`, and fetch the sender of the invite. - operationId: blindlySignStuff - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - example: { - "mxid": "@foo:bar.com", - "token": "sometoken", - "private_key": "base64encodedkey" - } - properties: - mxid: - type: string - description: The Matrix user ID of the user accepting the invitation. - token: - type: string - description: The token from the call to `store-invite`. - private_key: - type: string - description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64). - required: ["mxid", "token", "private_key"] - responses: - 200: - description: The signed JSON of the mxid, sender, and token. - schema: - type: object - properties: - mxid: - type: string - description: The Matrix user ID of the user accepting the invitation. - sender: - type: string - description: The Matrix user ID of the user who sent the invitation. - signatures: - type: object - description: The signature of the mxid, sender, and token. - $ref: "../../schemas/server-signatures.yaml" - token: - type: string - description: The token for the invitation. - required: ['mxid', 'sender', 'signatures', 'token'] - examples: - application/json: { - "mxid": "@foo:bar.com", - "sender": "@baz:bar.com", - "signatures": { - "my.id.server": { - "ed25519:0": "def987" - } - }, - "token": "abc123" - } - 404: - description: The token was not found. - examples: - application/json: { - "errcode": "M_UNRECOGNIZED", - "error": "Didn't recognize token" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" diff --git a/data/api/identity/lookup.yaml b/data/api/identity/lookup.yaml deleted file mode 100644 index 6163807e1..000000000 --- a/data/api/identity/lookup.yaml +++ /dev/null @@ -1,171 +0,0 @@ -# Copyright 2016 OpenMarket Ltd -# Copyright 2017 Kamax.io -# Copyright 2017 New Vector Ltd -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Lookup API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/lookup": - get: - summary: Look up the Matrix user ID for a 3pid. - description: Look up the Matrix user ID for a 3pid. - operationId: lookupUser - deprecated: true - parameters: - - in: query - type: string - name: medium - required: true - description: The medium type of the 3pid. See the [3PID Types](/appendices/#3pid-types) Appendix. - x-example: "email" - - in: query - type: string - name: address - required: true - description: The address of the 3pid being looked up. See the [3PID Types](/appendices/#3pid-types) Appendix. - x-example: "louise@bobs.burgers" - responses: - 200: - description: - The association for that 3pid, or an empty object if no association is known. - examples: - application/json: { - "address": "louise@bobs.burgers", - "medium": "email", - "mxid": "@ears:matrix.org", - "not_before": 1428825849161, - "not_after": 4582425849161, - "ts": 1428825849161, - "signatures": { - "matrix.org": { - "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" - } - } - } - schema: - type: object - properties: - address: - type: string - description: The 3pid address of the user being looked up, matching the address requested. - medium: - type: string - description: A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium requested. - mxid: - type: string - description: The Matrix user ID associated with the 3pid. - not_before: - type: integer - description: A unix timestamp before which the association is not known to be valid. - not_after: - type: integer - description: A unix timestamp after which the association is not known to be valid. - ts: - type: integer - description: The unix timestamp at which the association was verified. - signatures: - type: object - description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity servers. - $ref: "../../schemas/server-signatures.yaml" - required: - - address - - medium - - mxid - - not_before - - not_after - - ts - - signatures - "/bulk_lookup": - post: - summary: Lookup Matrix user IDs for a list of 3pids. - description: Lookup Matrix user IDs for a list of 3pids. - operationId: lookupUsers - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - example: { - "threepids": - [ - ["email","user@example.org"], - ["msisdn", "123456789"], - ["email","user2@example.org"] - ] - } - properties: - threepids: - type: array - items: - type: array - title: 3PID mappings - minItems: 2 - maxItems: 2 - items: - # TODO: Give real names to these values. Adding a `title` does not work. - #- type: 3PID Medium - #- type: 3PID Address - - type: string - - type: string - description: |- - An array of arrays containing the [3PID Types](/appendices/#3pid-types) with the `medium` - in first position and the `address` in second position. - required: - - "threepids" - responses: - 200: - description: A list of known 3PID mappings for the supplied 3PIDs. - examples: - application/json: { - "threepids": [ - ["email","user@example.org", "@bla:example.org"], - ["msisdn", "123456789", "@blah2:example.com"] - ] - } - schema: - type: object - properties: - threepids: - type: array - items: - type: array - title: 3PID mappings - minItems: 3 - maxItems: 3 - items: - # TODO: Give real names to these values. Adding a `title` does not work. - #- type: 3PID Medium - #- type: 3PID Address - #- type: Matrix User ID - - type: string - - type: string - - type: string - description: |- - An array of array containing the [3PID Types](/appendices/#3pid-types) with the `medium` - in first position, the `address` in second position and Matrix user - ID in third position. - required: - - "threepids" diff --git a/data/api/identity/phone_associations.yaml b/data/api/identity/phone_associations.yaml deleted file mode 100644 index 53d4132da..000000000 --- a/data/api/identity/phone_associations.yaml +++ /dev/null @@ -1,179 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Phone Number Associations API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/validate/msisdn/requestToken": - post: - summary: Request a token for validating a phone number. - description: |- - Create a session for validating a phone number. - - The identity server will send an SMS message containing a token. If - that token is presented to the identity server in the future, it - indicates that that user was able to read the SMS for that phone - number, and so we validate ownership of the phone number. - - Note that homeservers offer APIs that proxy this API, adding - additional behaviour on top, for example, - `/register/msisdn/requestToken` is designed specifically for use when - registering an account and therefore will inform the user if the phone - number given is already registered on the server. - - Note: for backwards compatibility with previous drafts of this - specification, the parameters may also be specified as - `application/x-form-www-urlencoded` data. However, this usage is - deprecated. - operationId: msisdnRequestToken - deprecated: true - parameters: - - in: body - name: body - schema: - $ref: "definitions/request_msisdn_validation.yaml" - responses: - 200: - description: Session created. - schema: - $ref: "definitions/sid.yaml" - 400: - description: | - An error ocurred. Some possible errors are: - - - `M_INVALID_ADDRESS`: The phone number provided was invalid. - - `M_SEND_ERROR`: The validation SMS could not be sent. - - `M_DESTINATION_REJECTED`: The identity server cannot deliver an - SMS to the provided country or region. - examples: - application/json: { - "errcode": "M_INVALID_ADDRESS", - "error": "The phone number is not valid" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/validate/msisdn/submitToken": - post: - summary: Validate ownership of a phone number. - description: |- - Validate ownership of a phone number. - - If the three parameters are consistent with a set generated by a - `requestToken` call, ownership of the phone number is considered to - have been validated. This does not publish any information publicly, or - associate the phone number address with any Matrix user - ID. Specifically, calls to `/lookup` will not show a binding. - - The identity server is free to match the token case-insensitively, or - carry out other mapping operations such as unicode - normalisation. Whether to do so is an implementation detail for the - identity server. Clients must always pass on the token without - modification. - - Note: for backwards compatibility with previous drafts of this - specification, the parameters may also be specified as - `application/x-form-www-urlencoded` data. However, this usage is - deprecated. - operationId: msisdnSubmitTokenPost - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } - properties: - sid: - type: string - description: The session ID, generated by the `requestToken` call. - client_secret: - type: string - description: The client secret that was supplied to the `requestToken` call. - token: - type: string - description: The token generated by the `requestToken` call and sent to the user. - required: ["sid", "client_secret", "token"] - responses: - 200: - description: - The success of the validation. - examples: - application/json: { - "success": true - } - schema: - type: object - properties: - success: - type: boolean - description: Whether the validation was successful or not. - required: ['success'] - get: - summary: Validate ownership of a phone number. - description: |- - Validate ownership of a phone number. - - If the three parameters are consistent with a set generated by a - `requestToken` call, ownership of the phone number address is - considered to have been validated. This does not publish any - information publicly, or associate the phone number with any Matrix - user ID. Specifically, calls to `/lookup` will not show a binding. - - Note that, in contrast with the POST version, this endpoint will be - used by end-users, and so the response should be human-readable. - operationId: msisdnSubmitTokenGet - deprecated: true - parameters: - - in: query - type: string - name: sid - required: true - description: The session ID, generated by the `requestToken` call. - x-example: 1234 - - in: query - type: string - name: client_secret - required: true - description: The client secret that was supplied to the `requestToken` call. - x-example: monkeys_are_GREAT - - in: query - type: string - name: token - required: true - description: The token generated by the `requestToken` call and sent to the user. - x-example: atoken - responses: - 200: - description: Phone number is validated. - "3xx": - description: |- - Phone number address is validated, and the `next_link` parameter - was provided to the `requestToken` call. The user must be - redirected to the URL provided by the `next_link` parameter. - "4xx": - description: - Validation failed. diff --git a/data/api/identity/ping.yaml b/data/api/identity/ping.yaml deleted file mode 100644 index d7249a772..000000000 --- a/data/api/identity/ping.yaml +++ /dev/null @@ -1,46 +0,0 @@ -# Copyright 2018 Kamax Sàrl -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -swagger: "2.0" -info: - title: "Matrix Identity Service Ping API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity -produces: - - application/json -paths: - "/api/v1": - get: - summary: Checks that an identity server is available at this API endpoint. - description: |- - Checks that an identity server is available at this API endpoint. - - To discover that an identity server is available at a specific URL, - this endpoint can be queried and will return an empty object. - - This is primarly used for auto-discovery and health check purposes - by entities acting as a client for the identity server. - operationId: ping - deprecated: true - responses: - 200: - description: An identity server is ready to serve requests. - examples: - application/json: {} - schema: - type: object diff --git a/data/api/identity/pubkey.yaml b/data/api/identity/pubkey.yaml deleted file mode 100644 index a585e7ecb..000000000 --- a/data/api/identity/pubkey.yaml +++ /dev/null @@ -1,129 +0,0 @@ -# Copyright 2016 OpenMarket Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Public Key API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/pubkey/{keyId}": - get: - summary: Get a public key. - description: |- - Get the public key for the passed key ID. - operationId: getPubKey - deprecated: true - parameters: - - in: path - type: string - name: keyId - required: true - description: |- - The ID of the key. This should take the form algorithm:identifier - where algorithm identifies the signing algorithm, and the identifier - is an opaque string. - x-example: "ed25519:0" - responses: - 200: - description: - The public key exists. - examples: - application/json: { - "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - } - schema: - type: object - properties: - public_key: - type: string - description: Unpadded Base64 encoded public key. - required: ['public_key'] - 404: - description: - The public key was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The public key was not found" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/pubkey/isvalid": - get: - summary: Check whether a long-term public key is valid. - description: |- - Check whether a long-term public key is valid. The response should always - be the same, provided the key exists. - operationId: isPubKeyValid - deprecated: true - parameters: - - in: query - type: string - name: public_key - required: true - description: |- - The unpadded base64-encoded public key to check. - x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - responses: - 200: - description: - The validity of the public key. - examples: - application/json: { - "valid": true - } - schema: - type: object - properties: - valid: - type: boolean - description: Whether the public key is recognised and is currently valid. - required: ['valid'] - "/pubkey/ephemeral/isvalid": - get: - summary: Check whether a short-term public key is valid. - description: |- - Check whether a short-term public key is valid. - operationId: isEphemeralPubKeyValid - deprecated: true - parameters: - - in: query - type: string - name: public_key - required: true - description: |- - The unpadded base64-encoded public key to check. - x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - responses: - 200: - description: - The validity of the public key. - examples: - application/json: { - "valid": true - } - schema: - type: object - properties: - valid: - type: boolean - description: Whether the public key is recognised and is currently valid. - required: ['valid'] diff --git a/data/api/identity/store_invite.yaml b/data/api/identity/store_invite.yaml deleted file mode 100644 index 20e408522..000000000 --- a/data/api/identity/store_invite.yaml +++ /dev/null @@ -1,161 +0,0 @@ -# Copyright 2018 New Vector Ltd -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -swagger: '2.0' -info: - title: "Matrix Identity Service Store Invitations API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/api/v1 -consumes: - - application/json -produces: - - application/json -paths: - "/store-invite": - post: - summary: Store pending invitations to a user's 3pid. - description: |- - Store pending invitations to a user's 3pid. - - In addition to the request parameters specified below, an arbitrary - number of other parameters may also be specified. These may be used in - the invite message generation described below. - - The service will generate a random token and an ephemeral key used for - accepting the invite. - - The service also generates a `display_name` for the inviter, which is - a redacted version of `address` which does not leak the full contents - of the `address`. - - The service records persistently all of the above information. - - It also generates an email containing all of this data, sent to the - `address` parameter, notifying them of the invitation. - - Also, the generated ephemeral public key will be listed as valid on - requests to `/_matrix/identity/api/v1/pubkey/ephemeral/isvalid`. - - Currently, invites may only be issued for 3pids of the `email` medium. - - Optional fields in the request should be populated to the best of the - server's ability. Identity servers may use these variables when notifying - the `address` of the pending invite for display purposes. - operationId: storeInvite - deprecated: true - parameters: - - in: body - name: body - schema: - type: object - properties: - medium: - type: string - description: The literal string `email`. - example: "email" - address: - type: string - description: The email address of the invited user. - example: "foo@example.com" - room_id: - type: string - description: The Matrix room ID to which the user is invited - example: "!something:example.org" - sender: - type: string - description: The Matrix user ID of the inviting user - example: "@bob:example.com" - room_alias: - type: string - description: |- - The Matrix room alias for the room to which the user is - invited. This should be retrieved from the `m.room.canonical_alias` - state event. - example: "#somewhere:exmaple.org" - room_avatar_url: - type: string - description: |- - The Content URI for the room to which the user is invited. This should - be retrieved from the `m.room.avatar` state event. - example: "mxc://example.org/s0meM3dia" - room_join_rules: - type: string - description: |- - The `join_rule` for the room to which the user is invited. This should - be retrieved from the `m.room.join_rules` state event. - example: "public" - room_name: - type: string - description: |- - The name of the room to which the user is invited. This should be retrieved - from the `m.room.name` state event. - example: "Bob's Emporium of Messages" - sender_display_name: - type: string - description: The display name of the user ID initiating the invite. - example: "Bob Smith" - sender_avatar_url: - type: string - description: The Content URI for the avatar of the user ID initiating the invite. - example: "mxc://example.org/an0th3rM3dia" - required: ["medium", "address", "room_id", "sender"] - responses: - 200: - description: The invitation was stored. - schema: - type: object - properties: - token: - type: string - description: | - The generated token. Must be a string consisting of the - characters `[0-9a-zA-Z.=_-]`. Its length must not exceed - 255 characters and it must not be empty. - public_keys: - type: array - description: | - A list of [server's long-term public key, generated ephemeral - public key]. - items: - type: string - display_name: - type: string - description: The generated (redacted) display_name. - required: ['token', 'public_keys', 'display_name'] - example: - application/json: { - "token": "sometoken", - "public_keys": [ - "serverpublickey", - "ephemeralpublickey" - ], - "display_name": "f...@b..." - } - 400: - description: | - An error has occured. - - If the 3pid is already bound to a Matrix user ID, the error code - will be `M_THREEPID_IN_USE`. If the medium is unsupported, the - error code will be `M_UNRECOGNIZED`. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Binding already known", - "mxid": "@alice:example.com" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" diff --git a/package-lock.json b/package-lock.json index 442a2aa40..5dce70c7d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -539,9 +539,9 @@ } }, "lodash": { - "version": "4.17.20", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz", - "integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA==", + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "dev": true }, "log-symbols": { diff --git a/proposals/1772-groups-as-rooms.md b/proposals/1772-groups-as-rooms.md new file mode 100644 index 000000000..1d431f841 --- /dev/null +++ b/proposals/1772-groups-as-rooms.md @@ -0,0 +1,427 @@ +# Proposal for Matrix "spaces" (formerly known as "groups as rooms (take 2)") + +This MSC, and related proposals, supercede +[MSC1215](https://github.com/matrix-org/matrix-doc/issues/1215). + +## Background and objectives + +Collecting rooms together into groups is useful for a number of +purposes. Examples include: + + * Allowing users to discover different rooms related to a particular topic: + for example "official matrix.org rooms". + * Allowing administrators to manage permissions across a number of rooms: for + example "a new employee has joined my company and needs access to all of our + rooms". + * Letting users classify their rooms: for example, separating "work" from + "personal" rooms. + +We refer to such collections of rooms as "spaces". + +Synapse and Element-Web currently implement an unspecced "groups" API (referred +to as "`/r0/groups`" in this document) which attempts to provide this +functionality (see +[MSC971](https://github.com/matrix-org/matrix-doc/issues/971)). However, +this is a complex API which has various problems (see +[appendix](#appendix-problems-with-the-r0groups-api)). + +This proposal suggests a new approach where spaces are themselves represented +by rooms, rather than a custom first-class entity. This requires minimal +server changes. + +The existing `/r0/groups` API would be deprecated in Synapse and remain +unspecified. + +## Proposal + +Each space is represented by its own room, known as a "space-room". The rooms +within the space are determined by state events within the space-room. + +Space-rooms are distinguished from regular messaging rooms by the presence of +a `'type': 'm.space'` property in the content of the `m.room.create` event. +The value of the `type` property uses the Standardised Identifier Grammar from +[MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758). This allows clients to offer slightly customised user experience +depending on the purpose of the room. Currently, no server-side behaviour is +expected to depend on this property. A `type` property on the `m.room.create` +event is used to ensure that a room cannot change between being a space-room +and a non-space room. For more information, see the "Rejected Alternatives" +section below. Additionally, no client behaviour is recommended for handling +unknown room types given the potential for legacy data: clients are free to +make their own decisions about hiding unknown room types from users, though +should note that a future conversation-like type (for example) might be +introduced and could be considered "unknown" by older versions of their client. + +As with regular rooms, public spaces are expected to have an alias, for example +`#foo:matrix.org`, which can be used to refer to the space. + +Space-rooms may have `m.room.name`, `m.room.avatar` and `m.room.topic` state +events in the same way as a normal room. + +Normal messages within a space-room are discouraged (but not blocked by the +server): user interfaces are not expected to have a way to enter or display +such messages. Space-rooms should be created with a power level for +`events_default` of 100, to prevent the rooms accidentally/maliciously +clogging up with messages from random members of the space. + +### Membership of spaces + +Users can be members of spaces (represented by `m.room.member` state events as +normal). The existing [`m.room.history_visibility` +mechanism](https://matrix.org/docs/spec/client_server/r0.6.1#room-history-visibility) +controls whether membership of the space is required to view the room list, +membership list, etc. "Public" or "community" spaces would be set to +`world_readable` to allow clients to see the directory of rooms within the +space by peeking into the space-room (thus avoiding the need to add +`m.room.member` events to the event graph within the room). + +Join rules, invites and 3PID invites work as for a normal room. In order for +clients to distinguish space invites from room invites, all invites must now +include the `m.room.create` event in their `invite_state` and `knock_state`. + +### Relationship between rooms and spaces + +The intention is that rooms and spaces form a hierarchy, which clients can use +to structure the user's room list into a tree view. The parent/child +relationship can be expressed in one of two ways: + + 1. The admins of a space can advertise rooms and subspaces for their space by + setting `m.space.child` state events. The `state_key` is the ID of a child + room or space, and the content must contain a `via` key which gives a list + of candidate servers that can be used to join the room. Something like: + + ```jsonc + // a child room + { + "type": "m.space.child", + "state_key": "!abcd:example.com", + "content": { + "via": ["example.com", "test.org"] + } + } + + // a child room with an ordering. + { + "type": "m.space.child", + "state_key": "!efgh:example.com", + "content": { + "via": ["example.com"], + "order": "abcd" + } + } + + // no longer a child room + { + "type": "m.space.child", + "state_key": "!jklm:example.com", + "content": {} + } + ``` + + Children where `via` is not present or invalid (not an array) are ignored. + + The `order` key is a string which is used to provide a default ordering of + siblings in the room list. (Rooms are sorted based on a lexicographic + ordering of the Unicode codepoints of the characters in `order` values. + Rooms with no `order` come last, in ascending numeric order of the + `origin_server_ts` of their `m.room.create` events, or ascending + lexicographic order of their `room_id`s in case of equal + `origin_server_ts`. `order`s which are not strings, or do not consist + solely of ascii characters in the range `\x20` (space) to `\x7E` (`~`), or + consist of more than 50 characters, are forbidden and the field should be + ignored if received.) + + 2. Separately, rooms can claim parents via the `m.space.parent` state + event. + + Similar to `m.space.child`, the `state_key` is the ID of the parent space, + and the content must contain a `via` key which gives a list of candidate + servers that can be used to join the parent. + + ```jsonc + { + "type": "m.space.parent", + "state_key": "!space:example.com", + "content": { + "via": ["example.com"], + "canonical": true + } + } + ``` + + Parents where `via` is not present or invalid (not an array) are ignored. + + `canonical` determines whether this is the main parent for the space. When + a user joins a room with a canonical parent, clients may switch to view the + room in the context of that space, peeking into it in order to find other + rooms and group them together. In practice, well behaved rooms should only + have one `canonical` parent, but given this is not enforced: if multiple + are present the client should select the one with the lowest room ID, as + determined via a lexicographic ordering of the Unicode code-points. + + To avoid abuse where a room admin falsely claims that a room is part of a + space that it should not be, clients could ignore such `m.space.parent` + events unless either (a) there is a corresponding `m.space.child` event in + the claimed parent, or (b) the sender of the `m.space.child` event has a + sufficient power-level to send such an `m.space.child` event in the + parent. (It is not necessarily required that that user currently be a + member of the parent room - only the `m.room.power_levels` event is + inspected.) [Checking the power-level rather than requiring an *actual* + `m.space.child` event in the parent allows for "secret" rooms (see below).] + + Where the parent space also claims a parent, clients can recursively peek + into the grandparent space, and so on. + +This structure means that rooms can end up appearing multiple times in the +room list hierarchy, given they can be children of multiple different spaces +(or have multiple parents in different spaces). + +In a typical hierarchy, we expect *both* parent->child and child->parent +relationships to exist, so that the space can be discovered from the room, and +vice versa. Occasions when the relationship only exists in one direction +include: + + * User-curated lists of rooms: in this case the space will not be listed as a + parent of the room. + + * "Secret" rooms: rooms where the admin does not want the room to be + advertised as part of a given space, but *does* want the room to form part + of the hierarchy of that space for those in the know. + +Cycles in the parent->child and child->parent relationships are *not* +permitted, but clients (and servers) should be aware that they may be +encountered, and MUST spot and break cycles rather than infinitely looping. + +### Suggested children + +Space admins can mark particular children of a space as "suggested". This +mainly serves as a hint to clients that that they can be displayed differently +(for example by showing them eagerly in the room list), though future +server-side interfaces (such as the summary API proposed in +[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946)) might also +make use of it. + +A suggested child is identified by a `"suggested": true` property in the +`m.space.child` event: + + +```jsonc +{ + "type": "m.space.child", + "state_key": "!abcd:example.com", + "content": { + "via": ["example.com", "test.org"], + "suggested": true + } +} +``` + +A child which is missing the `suggested` property is treated identically to a +child with `"suggested": false`. A suggested child may be a room or a subspace. + +### Extended "room invite state" + +The specification is currently vague about what room state should be available +to users that have been invited to a room, though the Federation API spec does +recommend that the `invite_room_state` sent over federation via [PUT +`/_matrix/federation/v2/invite`](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) +should include "the join rules, canonical alias, avatar, and name of the room". + +This MSC proposes adding `m.room.create` to that list, so that the recipient of +an invite can distinguish invites to spaces from other invites. + +## Future extensions + +The following sections are not blocking parts of this proposal, but are +included as a useful reference for how we imagine it will be extended in future. + +### Auto-joined children + +We could add an `auto_join` flag to `m.space.child` events to allow a space +admin to list the sub-spaces and rooms in that space which should be +automatically joined by members of that space. + +This would be distinct from a force-join: the user could subsequently part any +auto-joined room if they desire. + +Joining would be performed by the client. This could possibly be sped up by +using a summary API (such as that proposed in +[MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946)) to get a summary +of the spacetree to be joined, and then using a batch join API to join +whichever subset of it makes most sense for the client's UX. + +Obviously auto-joining can be a DoS vector, and we consider it to be antisocial +for a space to try to autojoin its members to more than 100 children (in total). + +Clients could display the auto-joined children in the room list whenever the +space appears in the list - thus helping users discover other rooms in a space +even if they're not joined to that space. For instance, if you join +`#matrix:matrix.org`, your client could show that room in the context of its +parent space, with that space's auto-joined children shown alongside it as +siblings. + +### Restricting access to the spaces membership list + +In the existing `/r0/groups` API, the group server has total control over the +visibility of group membership, as seen by a given querying user. In other +words, arbitrary users can see entirely different views of a group at the +server's discretion. + +Whilst this is very powerful for mapping arbitrary organisational structures +into Matrix, it may be overengineered. Instead, the common case is (we believe) +a space where some users are publicly visible as members, and others are not. + +One way of achieving this would be to create a separate space for the +private members - e.g. have `#foo:matrix.org` and `#foo-private:matrix.org`. +`#foo-private:matrix.org` is set up with `m.room.history_visibility` to not to +allow peeking; you have to be joined to see the members. + +It's worth noting that any member of a space can currently see who else is a +member of that space, which might pose privacy problems for sensitive spaces. +While the server itself will inevitably track the space membership in state +events, a future MSC could restrict the membership from being sent to clients. +This is essentially the same as +[matrix-doc#1653](https://github.com/matrix-org/matrix-doc/issues/1653). + +### Flair + +("Flair" is a term we use to describe a small badge which appears next to a +user's displayname to advertise their membership of a space.) + +The flair image for a group is given by the room avatar. (In future it might +preferable to use hand-crafted small resolution images: see +[matrix-doc#1778](https://github.com/matrix-org/matrix-doc/issues/1778). + +One way this might be implemented is: + + * User publishes the spaces they wish to announce on their profile + ([MSC1769](https://github.com/matrix-org/matrix-doc/issues/1769) + as an `m.flair` state event: it lists the spaces which they are advertising. + + * When a client wants to know the current flair for a set of users (i.e. + those which it is currently displaying in the timeline), it peeks the + profile rooms of those users. (Ideally there would be an API to support + peeking multiple rooms at once to facilitate this.) + + * The client must check that the user is *actually* a member of the advertised + spaces. Nominally it can do this by peeking the membership list of the + space; however for efficiency we could expose a dedicated Client-Server API + to do this check (and both servers and clients can cache the results fairly + aggressively.) + +## Related MSCs + + * [MSC2946](https://github.com/matrix-org/matrix-doc/issues/2946): Spaces + Summary API. + + * [MSC2962](https://github.com/matrix-org/matrix-doc/issues/2962): Managing + power levels via Spaces. + + * [MSC3083](https://github.com/matrix-org/matrix-doc/issues/3083): Restricting + room membership based on space membership. + + * [MSC2753](https://github.com/matrix-org/matrix-doc/issues/2753) for + effective peeking over the C/S API. + + * [MSC2444](https://github.com/matrix-org/matrix-doc/issues/2444) (or similar) + for effective peeking over Federation. + +## Security considerations + +None at present. + +## Potential issues + +* If the membership of a space would be large (for example: an organisation of + several thousand people), this membership has to be copied entirely into the + room, rather than querying/searching incrementally. + +* If the membership list is based on an external service such as LDAP, it is + hard to keep the space membership in sync with the LDAP directory. In + practice, it might be possible to do so via a nightly "synchronisation" job + which searches the LDAP directory, or via "AD auditing". + +* No allowance is made for exposing different 'views' of the membership list to + different querying users. (It may be possible to simulate this behaviour + using smaller spaces). + +* The requirement that `m.space.parent` links be ignored unless the sender has a + high PL in the parent room could lead to suprising effects where a parent + link suddenly ceases to take effect because a user loses their PL in the + parent room. This is mitigated in the general case by honouring the parent + link when there is a corresponding `m.space.child` event, however it remains + a problem for "secret" rooms. + +* The `via` servers listed in the `m.space.child` and `m.space.parent` events + could get out of date, and will need to be updated from time to time. This + remains an unsolved problem. + +## Rejected alternatives + +### Use a separate state event for type of room + +[MSC1840](https://github.com/matrix-org/matrix-doc/pull/1840) proposes the use +of a separate `m.room.type` state event to distinguish different room types. +This implies that rooms can dynamically switch between being a Space, and +being a regular non-Space room. That is not a usecase we consider useful, and +allowing it would impose significant complexity on client and server +implementations. Specifically, client and server implementations who store +spaces separately from rooms would have to support migrating back and forth +between them and dealing with the ambiguities of `room_id`s no longer pointing +to valid spaces, etc. + +### Use a different sigil/twigil for spaces + +Groups used + as a sigil to differentiate them from rooms (e.g. +matrix:matrix.org). +We considered doing similar for Spaces, e.g. a #+ twigil or reuse the + sigil, +but concluded that the resulting complexity and exoticism is not worth it. +This means that clients such as matrix.to have to peek into rooms to find out their +`type` before being able to display an appropriate UI, and users will not know +whether #matrix:matrix.org is a room or a space without using a client (e.g. if +reading an advert). It also means that if the client UI requires a space alias the +client will need to validate the entered data serverside. + +## Unstable prefix + +The following mapping will be used for identifiers in this MSC during +development: + +Proposed final identifier | Purpose | Development identifier +------------------------------- | ------- | ---- +`type` | property in `m.room.create` | `org.matrix.msc1772.type` +`m.space` | value of `type` in `m.room.create` | `org.matrix.msc1772.space` +`m.space.child` | event type | `org.matrix.msc1772.space.child` +`m.space.parent` | event type | `org.matrix.msc1772.space.parent` + +## History + + * This replaces [MSC1215](https://docs.google.com/document/d/1ZnAuA_zti-K2-RnheXII1F1-oyVziT4tJffdw1-SHrE). + * Other thoughts that led into this are [documented](https://docs.google.com/document/d/1hljmD-ytdCRL37t-D_LvGDA3a0_2MwowSPIiZRxcabs). + +## Appendix: problems with the `/r0/groups` API + +The existing `/r0/groups` API, as proposed in +[MSC971](https://github.com/matrix-org/matrix-doc/issues/971), has various +problems, including: + + * It is a large API surface to implement, maintain and spec - particularly for + all the different clients out there. + * Much of the API overlaps significantly with mechanisms we already have for + managing rooms: + * Tracking membership identity + * Tracking membership hierarchy + * Inviting/kicking/banning user + * Tracking key/value metadata + * There are membership management features which could benefit rooms which + would also benefit groups and vice versa (e.g. "auditorium mode") + * The current implementations on Riot Web/iOS/Android all suffer bugs and + issues which have been solved previously for rooms. + * no local-echo of invites + * failures to set group avatars + * ability to specify multiple admins + * It doesn't support pushing updates to clients (particularly for flair + membership): https://github.com/vector-im/riot-web/issues/5235 + * It doesn't support third-party invites. + * Groups could benefit from other features which already exist today for rooms + * e.g. Room Directories + * Groups are centralised, rather than being replicated across all + participating servers. diff --git a/proposals/3122-deprecate-starting-verifications-without-request.md b/proposals/3122-deprecate-starting-verifications-without-request.md new file mode 100644 index 000000000..9a00699bd --- /dev/null +++ b/proposals/3122-deprecate-starting-verifications-without-request.md @@ -0,0 +1,40 @@ +# MSC3122: Deprecate starting key verifications without requesting first + +Currently, the [Key verification +framework](https://spec.matrix.org/unstable/client-server-api/#key-verification-framework) +allows a device to begin a verification via to-device messages by sending an +`m.key.verification.start` event without first sending or receiving an +`m.key.verification.request` message. (The last sentence of the 5th paragraph +of the Key verification framework in the unstable spec, as of the time of +writing.) However, doing so does not provide a good user experience, and +allowing this adds unnecessary complexity to implementations. + +We propose to deprecate allowing this behaviour. + +Note that verifications in DMs do not allow this behaviour. Currently, Element +Web is the only client known to do this. + +## Proposal + +The ability to begin a key verification by sending an +`m.key.verification.start` event as a to-device event without a prior +`m.key.verification.request` is deprecated. New clients should not begin +verifications in this way, but will still need to accept verifications begun in +this way, until it is removed from the spec. + +## Potential issues + +None. + +## Alternatives + +We could do nothing and leave it in the spec. But we should clean up cruft when +possible. + +## Security considerations + +None. + +## Unstable prefix + +No unstable prefix is required since we are simply deprecating behaviour.