From cc0badaaa1eb187e9c173871441e8d9e6fbfc9d5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 18:19:35 -0600 Subject: [PATCH 1/8] Fix all naming cases of "identity service" Fixes https://github.com/matrix-org/matrix-doc/issues/1396 Includes some "homeserver" fixes too. This commit does not include historical documentation or notes. --- api/client-server/administrative_contact.yaml | 14 ++++---- api/client-server/create_room.yaml | 12 +++---- .../wellknown/identity_server.yaml | 6 ++-- api/client-server/registration.yaml | 16 ++++----- api/client-server/third_party_membership.yaml | 16 ++++----- api/client-server/wellknown.yaml | 2 +- api/server-server/third_party_invite.yaml | 18 +++++----- changelogs/client_server.rst | 2 +- meta/documentation_style.rst | 16 ++++----- meta/releasing_a_spec.md | 4 +-- specification/client_server_api.rst | 14 ++++---- specification/index.rst | 4 +-- specification/modules/third_party_invites.rst | 36 +++++++++---------- specification/server_server_api.rst | 20 +++++------ 14 files changed, 90 insertions(+), 90 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 5699a884..0f01363f 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -35,7 +35,7 @@ paths: associated with the user's account. This is *not* the same as the list of third party identifiers bound to - the user's Matrix ID in Identity Servers. + the user's Matrix ID in Identity Services. Identifiers in this list may be used by the homeserver as, for example, identifiers that it will accept to reset the user's account password. @@ -106,13 +106,13 @@ paths: properties: client_secret: type: string - description: The client secret used in the session with the Identity Server. + description: The client secret used in the session with the Identity Service. id_server: type: string - description: The Identity Server to use. + description: The Identity Service to use. sid: type: string - description: The session identifier given by the Identity Server. + description: The session identifier given by the Identity Service. required: ["client_secret", "id_server", "sid"] bind: type: boolean @@ -138,11 +138,11 @@ paths: schema: type: object 403: - description: The credentials could not be verified with the identity server. + description: The credentials could not be verified with the identity service. examples: application/json: { "errcode": "M_THREEPID_AUTH_FAILED", - "error": "The third party credentials could not be verified by the identity server." + "error": "The third party credentials could not be verified by the identity service." } schema: "$ref": "definitions/errors/error.yaml" @@ -243,7 +243,7 @@ paths: description: |- Proxies the identity service API ``validate/msisdn/requestToken``, but first checks that the given phone number is **not** already associated - with an account on this Home Server. This API should be used to request + with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index ac0c3b16..a0b1deaf 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -41,7 +41,7 @@ paths: 0. A default ``m.room.power_levels`` event, giving the room creator (and not other members) permission to send state events. Overridden by the ``power_level_content_override`` parameter. - + 1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``, ``m.room.history_visibility``, and ``m.room.guest_access`` state events. @@ -59,13 +59,13 @@ paths: ======================== ============== ====================== ================ ========= Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other ======================== ============== ====================== ================ ========= - ``private_chat`` ``invite`` ``shared`` ``can_join`` + ``private_chat`` ``invite`` ``shared`` ``can_join`` ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. - ``public_chat`` ``public`` ``shared`` ``forbidden`` + ``public_chat`` ``public`` ``shared`` ``forbidden`` ======================== ============== ====================== ================ ========= The server will create a ``m.room.create`` event in the room with the - requesting user as the creator, alongside other keys provided in the + requesting user as the creator, alongside other keys provided in the ``creation_content``. operationId: createRoom security: @@ -138,7 +138,7 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity server which should be used for third party identifier lookups. + description: The hostname+port of the identity service which should be used for third party identifier lookups. medium: type: string # TODO: Link to identity service spec when it eixsts @@ -196,7 +196,7 @@ paths: If unspecified, the server should use the ``visibility`` to determine which preset to use. A visbility of ``public`` equates to a preset of - ``public_chat`` and ``private`` visibility equates to a preset of + ``public_chat`` and ``private`` visibility equates to a preset of ``private_chat``. is_direct: type: boolean diff --git a/api/client-server/definitions/wellknown/identity_server.yaml b/api/client-server/definitions/wellknown/identity_server.yaml index a8f7c31c..d3399615 100644 --- a/api/client-server/definitions/wellknown/identity_server.yaml +++ b/api/client-server/definitions/wellknown/identity_server.yaml @@ -11,14 +11,14 @@ # 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. -title: Identity Server Information +title: Identity Service Information description: |- - Used by clients to discover identity server information. + Used by clients to discover identity service information. type: object properties: base_url: type: string - description: The base URL for the identity server for client-server connections. + description: The base URL for the identity service for client-server connections. example: https://identity.example.com required: - base_url diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 324abbff..c020402e 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -92,7 +92,7 @@ paths: type: boolean description: |- If true, the server binds the email used for authentication to - the Matrix ID with the ID Server. + the Matrix ID with the identity service. example: false username: type: string @@ -251,7 +251,7 @@ paths: instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the homeserver in question. - * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server + * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity service that is not trusted by this homeserver. examples: application/json: { @@ -307,12 +307,12 @@ paths: Part of the request was invalid. This may include one of the following error codes: * ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server. - However, if the home server has the ability to send SMS message, it is recommended that the server + However, if the homeserver has the ability to send SMS message, it is recommended that the server instead send an SMS message to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given phone number - has an account on the Home Server in question. - * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server - that is not trusted by this Home Server. + has an account on the homeserver in question. + * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity service + that is not trusted by this homeserver. examples: application/json: { "errcode": "M_THREEPID_IN_USE", @@ -375,7 +375,7 @@ paths: description: |- Proxies the identity service API ``validate/email/requestToken``, but first checks that the given email address **is** associated with an account - on this Home Server. This API should be used to request + on this homeserver. This API should be used to request validation tokens when authenticating for the `account/password` endpoint. This API's parameters and response are identical to that of the HS API |/register/email/requestToken|_ except that @@ -437,7 +437,7 @@ paths: description: |- Proxies the identity service API ``validate/msisdn/requestToken``, but first checks that the given phone number **is** associated with an account - on this Home Server. This API should be used to request + on this homeserver. This API should be used to request validation tokens when authenticating for the `account/password` endpoint. This API's parameters and response are identical to that of the HS API |/register/msisdn/requestToken|_ except that diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index 66c14c4d..a4d66a80 100644 --- a/api/client-server/third_party_membership.yaml +++ b/api/client-server/third_party_membership.yaml @@ -36,7 +36,7 @@ paths: *Note that there are two forms of this API, which are documented separately. This version of the API does not require that the inviter know the Matrix identifier of the invitee, and instead relies on third party identifiers. - The homeserver uses an identity server to perform the mapping from + The homeserver uses an identity service to perform the mapping from third party identifier to a Matrix identifier. The other is documented in the* `joining rooms section`_. @@ -47,31 +47,31 @@ paths: Only users currently in a particular room can invite other users to join that room. - If the identity server did know the Matrix user identifier for the + If the identity service did know the Matrix user identifier for the third party identifier, the homeserver will append a ``m.room.member`` event to the room. - If the identity server does not know a Matrix user identifier for the + If the identity service does not know a Matrix user identifier for the passed third party identifier, the homeserver will issue an invitation which can be accepted upon providing proof of ownership of the third - party identifier. This is achieved by the identity server generating a + party identifier. This is achieved by the identity service generating a token, which it gives to the inviting homeserver. The homeserver will add an ``m.room.third_party_invite`` event into the graph for the room, containing that token. When the invitee binds the invited third party identifier to a Matrix - user ID, the identity server will give the user a list of pending + user ID, the identity service will give the user a list of pending invitations, each containing: - The room ID to which they were invited - The token given to the homeserver - - A signature of the token, signed with the identity server's private key + - A signature of the token, signed with the identity service's private key - The matrix user ID who invited them to the room - If a token is requested from the identity server, the homeserver will + If a token is requested from the identity service, the homeserver will append a ``m.room.third_party_invite`` event to the room. .. _joining rooms section: `invite-by-user-id-endpoint`_ @@ -98,7 +98,7 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity server which should be used for third party identifier lookups. + description: The hostname+port of the identity service which should be used for third party identifier lookups. medium: type: string # TODO: Link to identity service spec when it eixsts diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml index 24e190f9..b2695c43 100644 --- a/api/client-server/wellknown.yaml +++ b/api/client-server/wellknown.yaml @@ -54,7 +54,7 @@ paths: description: Information about the homeserver to connect to. "$ref": "definitions/wellknown/homeserver.yaml" m.identity_server: - description: Optional. Information about the identity server to connect to. + description: Optional. Information about the identity service to connect to. "$ref": "definitions/wellknown/identity_server.yaml" additionalProperties: description: Application-dependent keys using Java package naming convention. diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 9def527d..3a33f2ea 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -200,9 +200,9 @@ paths: Notifies the server that a third party identifier has been bound to one of its users. description: |- - Used by Identity Servers to notify the homeserver that one of its users + Used by Identity Services to notify the homeserver that one of its users has bound a third party identifier successfully, including any pending - room invites the Identity Server has been made aware of. + room invites the Identity Service has been made aware of. operationId: onBindThirdPartyIdentifier parameters: - in: body @@ -262,9 +262,9 @@ paths: # also make sure it isn't lying about anything, like the key version signed: type: object - title: Identity Server Signatures + title: Identity Service Signatures description: |- - Signature from the Identity Server using a long-term private + Signature from the Identity Service using a long-term private key. properties: mxid: @@ -280,14 +280,14 @@ paths: example: "Hello World" signatures: type: object - title: Identity Server Signature + title: Identity Service Signature description: |- - The signature from the identity server. The ``string`` key - is the identity server's domain name, such as vector.im + The signature from the identity service. The ``string`` key + is the identity service's domain name, such as vector.im additionalProperties: type: object - title: Identity Server Domain Signature - description: The signature for the identity server. + title: Identity Service Domain Signature + description: The signature for the identity service. properties: "ed25519:0": type: string diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index d2ef7f2d..6053cbd5 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -76,7 +76,7 @@ r0.3.0 - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation - spec and update the JSON of the request sent by the identity server upon 3PID + spec and update the JSON of the request sent by the identity service upon 3PID binding (`#997 `_) - Fix "membership" property on third-party invite upgrade example diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index c6bb62bf..a659921b 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -69,10 +69,10 @@ have English as their first language. Prefer British English (colour, -ise) to American English. The word "homeserver" is spelt thus (rather than "home server", "Homeserver", -or (argh) "Home Server"). However, an identity server is two words. +or (argh) "Home Server"). However, an identity service is two words. -.. Rationale: "homeserver" distinguishes from a "home server" which is a server - you have at home. "Identity server" is clear, whereas "identityserver" is +.. Rationale: "homeserver" distinguishes from a "home server" which is a server + you have at home. "Identity Service" is clear, whereas "identityservice" is horrible. Lists should: @@ -91,9 +91,9 @@ When writing OpenAPI specifications for the API endpoints, follow these rules: * ``description``: a longer description of the behaviour of this API, written in complete sentences. Use multiple paragraphs if necessary. - - Example: - + + Example: + This API sends an event to the room. The server must ensure that the user has permission to post events to this room. @@ -106,7 +106,7 @@ When writing OpenAPI specifications for the API endpoints, follow these rules: The description is also the place to define default values for optional properties. Use the wording "Defaults to X [if unspecified]." - - Some descriptions start with the word "Optional" to explicitly mark optional + + Some descriptions start with the word "Optional" to explicitly mark optional properties and parameters. This is redundant. Instead, use the ``required`` property to mark those that are required. diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index ac3d21fa..2d9cd34e 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -1,7 +1,7 @@ # How to release a specification There are several specifications that belong to matrix, such as the client-server -specification, server-server specification, and identity server specification. Each +specification, server-server specification, and identity service specification. Each of these gets released independently of each other with their own version numbers. Once a specification is ready for release, a branch should be created to track the @@ -34,7 +34,7 @@ The remainder of the process is as follows: ### Creating a release for a brand-new specification Some specifications may not have ever had a release, and therefore need a bit more work -to become ready. +to become ready. 1. Activate your Python 3 virtual environment. 1. Having checked out the new release branch, navigate your way over to `./changelogs`. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 549474af..ec4e1baf 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -145,7 +145,7 @@ Some requests have unique error codes: Sent when a threepid given to an API cannot be used because no record matching the threepid was found. :``M_SERVER_NOT_TRUSTED``: - The client's request used a third party server, eg. ID server, that this server does not trust. + The client's request used a third party server, eg. identity service, that this server does not trust. :``M_UNSUPPORTED_ROOM_VERSION``: The client's request to create a room used a room version that the server does not support. @@ -257,7 +257,7 @@ specify parameter values. The flow for this method is as follows: points to a valid homeserver. f. If the ``m.identity_server`` property is present, extract the - ``base_url`` value for use as the base URL of the identity server. + ``base_url`` value for use as the base URL of the identity service. 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 ``m.identity_server`` property is present, but does not have a @@ -685,7 +685,7 @@ the auth code. Homeservers can choose any path for the ``redirect URI``. Once the OAuth flow has completed, the client retries the request with the session only, as above. -Email-based (identity server) +Email-based (identity service) <<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: ``m.login.email.identity`` @@ -705,9 +705,9 @@ To use this authentication type, clients should submit an auth dict as follows: "type": "m.login.email.identity", "threepidCreds": [ { - "sid": "", - "client_secret": "", - "id_server": "" + "sid": "", + "client_secret": "", + "id_server": "" } ], "session": "" @@ -995,7 +995,7 @@ Adding Account Administrative Contact Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A homeserver may keep some contact information for administrative use. -This is independent of any information kept by any Identity Servers. +This is independent of any information kept by any Identity Services. {{administrative_contact_cs_http_api}} diff --git a/specification/index.rst b/specification/index.rst index 36c89958..481469cd 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -107,7 +107,7 @@ The functionality that Matrix provides includes: - Managing user accounts (registration, login, logout) - Use of 3rd Party IDs (3PIDs) such as email addresses, phone numbers, Facebook accounts to authenticate, identify and discover users on Matrix. -- Trusted federation of Identity servers for: +- Trusted federation of Identity Services for: + Publishing user public keys for PKI + Mapping of 3PIDs to Matrix IDs @@ -386,7 +386,7 @@ network accounts and phone numbers to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the user IDs of their contacts. In order to ensure that the mapping from 3PID to user ID is genuine, a globally -federated cluster of trusted "Identity Servers" (IS) are used to verify the 3PID +federated cluster of trusted "Identity Services" (IS) are used to verify the 3PID and persist and replicate the mappings. Usage of an IS is not required in order for a client application to be part of diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 248b9ba9..9d9827d1 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -24,14 +24,14 @@ 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 +The homeserver asks the identity service 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 +- If it is not, the homeserver asks the identity service to record the details of the invitation, and to notify the invitee's homeserver of this pending invitation if it gets - a binding for this identifier in the future. The identity server returns a token + a binding for this identifier in the future. The identity service returns a token and public key to the inviting homeserver. When the invitee's homeserver receives the notification of the binding, it @@ -57,7 +57,7 @@ Server behaviour ---------------- Upon receipt of an ``/invite``, the server is expected to look up the third party -identifier with the provided identity server. If the lookup yields a result for +identifier with the provided identity service. If the lookup yields a result for a Matrix User ID then the normal invite process can be initiated. This process ends up looking like this: @@ -87,7 +87,7 @@ ends up looking like this: However, if the lookup does not yield a bound User ID, the homeserver must store -the invite on the identity server and emit a valid ``m.room.third_party_invite`` +the invite on the identity service and emit a valid ``m.room.third_party_invite`` event to the room. This process ends up looking like this: :: @@ -125,7 +125,7 @@ All homeservers MUST verify the signature in the event's ``content.third_party_invite.signed`` object. The third party user will then need to verify their identity, which results in -a call from the Identity Server to the homeserver that bound the third party +a call from the Identity Service to the homeserver that bound the third party identifier to a user. The homeserver then exchanges the ``m.room.third_party_invite`` event in the room for a complete ``m.room.member`` event for ``membership: invite`` for the user that has bound the third party identifier. @@ -142,7 +142,7 @@ the room. They may, however, indicate to their clients that a member's membership is questionable. For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, and an -identity server IS, the full sequence for a third party invite would look like +identity service IS, the full sequence for a third party invite would look like the following. This diagram assumes H1 and H2 are residents of the room while H3 is attempting to join. @@ -207,15 +207,15 @@ H3 is attempting to join. Note that when H1 sends the ``m.room.member`` event to H2 and H3 it does not have to block on either server's receipt of the event. Likewise, H1 may complete the ``/exchange_third_party_invite/:roomId`` request at the same time as sending -the ``m.room.member`` event to H2 and H3. Additionally, H3 may complete the +the ``m.room.member`` event to H2 and H3. Additionally, H3 may complete the ``/3pid/onbind`` request it got from IS at any time - the completion is not shown in the diagram. H1 MUST verify the request from H3 to ensure the ``signed`` property is correct as well as the ``key_validity_url`` as still being valid. This is done by making -a request to the `Identity Server /isvalid`_ endpoint, using the provided URL +a request to the `Identity Service /isvalid`_ endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided -URL must match the Identity Server specification. +URL must match the Identity Service specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. @@ -236,22 +236,22 @@ ID and a third party identifier is hard. In particular, being able to look up all third party identifiers from a matrix user ID (and accordingly, being able to link each third party identifier) should be avoided wherever possible. To this end, the third party identifier is not put in any event, rather an -opaque display name provided by the identity server is put into the events. +opaque display name provided by the identity service is put into the events. Clients should not remember or display third party identifiers from invites, other than for the use of the inviter themself. -Homeservers are not required to trust any particular identity server(s). It is -generally a client's responsibility to decide which identity servers it trusts, -not a homeserver's. Accordingly, this API takes identity servers as input from +Homeservers are not required to trust any particular identity service(s). It is +generally a client's responsibility to decide which identity services it trusts, +not a homeserver's. Accordingly, this API takes identity services as input from end users, and doesn't have any specific trusted set. It is possible some -homeservers may want to supply defaults, or reject some identity servers for -*its* users, but no homeserver is allowed to dictate which identity servers +homeservers may want to supply defaults, or reject some identity services for +*its* users, but no homeserver is allowed to dictate which identity services *other* homeservers' users trust. There is some risk of denial of service attacks by flooding homeservers or -identity servers with many requests, or much state to store. Defending against +identity services with many requests, or much state to store. Defending against these is left to the implementer's discretion. -.. _`Identity Server /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid +.. _`Identity Service /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 36d7d5d4..8aa038ea 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -844,35 +844,35 @@ When an user wants to invite another user in a room but doesn't know the Matrix ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number). -This identifier and its bindings to Matrix IDs are verified by an identity server +This identifier and its bindings to Matrix IDs are verified by an identity service implementing the `Identity Service API`_. Cases where an association exists for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the third-party identifier is already bound to a Matrix ID, a lookup request -on the identity server will return it. The invite is then processed by the inviting +on the identity service will return it. The invite is then processed by the inviting homeserver as a standard ``m.room.member`` invite event. This is the simplest case. Cases where an association doesn't exist for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the third-party identifier isn't bound to any Matrix ID, the inviting -homeserver will request the identity server to store an invite for this identifier +homeserver will request the identity service to store an invite for this identifier and to deliver it to whoever binds it to its Matrix ID. It will also send a ``m.room.third_party_invite`` event in the room to specify a display name, a token -and public keys the identity server provided as a response to the invite storage +and public keys the identity service provided as a response to the invite storage request. When a third-party identifier with pending invites gets bound to a Matrix ID, -the identity server will send a POST request to the ID's homeserver as described +the identity service will send a POST request to the ID's homeserver as described in the `Invitation Storage`_ section of the Identity Service API. -The following process applies for each invite sent by the identity server: +The following process applies for each invite sent by the identity service: The invited homeserver will create a ``m.room.member`` invite event containing a special ``third_party_invite`` section containing the token and a signed object, -both provided by the identity server. +both provided by the identity service. If the invited homeserver is in the room the invite came from, it can auth the event and send it. @@ -894,14 +894,14 @@ server. To do so, it will fetch from the room's state events the ``m.room.third_party_invite`` event for which the state key matches with the value for the ``token`` key in the ``third_party_invite`` object from the ``m.room.member`` event's content to fetch the -public keys initially delivered by the identity server that stored the invite. +public keys initially delivered by the identity service that stored the invite. It will then use these keys to verify that the ``signed`` object (in the ``third_party_invite`` object from the ``m.room.member`` event's content) was -signed by the same identity server. +signed by the same identity service. Since this ``signed`` object can only be delivered once in the POST request -emitted by the identity server upon binding between the third-party identifier +emitted by the identity service upon binding between the third-party identifier and the Matrix ID, and contains the invited user's Matrix ID and the token delivered when the invite was stored, this verification will prove that the ``m.room.member`` invite event comes from the user owning the invited third-party From ec248b436f81db78c27da497fbe048a4e68f2ee6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 14:47:06 -0600 Subject: [PATCH 2/8] Identity Service is lowercase --- api/client-server/administrative_contact.yaml | 8 ++++---- api/client-server/registration.yaml | 4 ++-- api/identity/invitation_signing.yaml | 2 +- api/identity/ping.yaml | 10 +++++----- api/server-server/third_party_invite.yaml | 6 +++--- meta/documentation_style.rst | 2 +- specification/client_server_api.rst | 2 +- specification/identity_service_api.rst | 2 +- specification/index.rst | 4 ++-- specification/modules/third_party_invites.rst | 8 ++++---- specification/server_server_api.rst | 6 +++--- 11 files changed, 27 insertions(+), 27 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 0f01363f..52b62f11 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -35,7 +35,7 @@ paths: associated with the user's account. This is *not* the same as the list of third party identifiers bound to - the user's Matrix ID in Identity Services. + the user's Matrix ID in identity services. Identifiers in this list may be used by the homeserver as, for example, identifiers that it will accept to reset the user's account password. @@ -106,13 +106,13 @@ paths: properties: client_secret: type: string - description: The client secret used in the session with the Identity Service. + description: The client secret used in the session with the identity service. id_server: type: string - description: The Identity Service to use. + description: The identity service to use. sid: type: string - description: The session identifier given by the Identity Service. + description: The session identifier given by the identity service. required: ["client_secret", "id_server", "sid"] bind: type: boolean diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c020402e..23edbe6d 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -206,7 +206,7 @@ paths: description: |- Proxies the identity service API ``validate/email/requestToken``, but first checks that the given email address is not already associated - with an account on this homeserver. See the Identity Service API for + with an account on this homeserver. See the identity service API for further information. operationId: requestTokenToRegisterEmail parameters: @@ -266,7 +266,7 @@ paths: description: |- Proxies the identity service API ``validate/msisdn/requestToken``, but first checks that the given phone number is not already associated - with an account on this homeserver. See the Identity Service API for + with an account on this homeserver. See the identity service API for further information. operationId: requestTokenToRegisterMSISDN parameters: diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 0b76a773..6478423f 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -87,7 +87,7 @@ paths: } 404: description: The token was not found. - examples: + examples: application/json: { "errcode": "M_UNRECOGNIZED", "error": "Didn't recognize token" diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index 2788d9d3..abe33909 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -26,19 +26,19 @@ produces: paths: "/api/v1": get: - summary: Checks that an Identity Service is available at this API endpoint. + summary: Checks that an identity service is available at this API endpoint. description: |- - Checks that an Identity Service is available at this API endpoint. + Checks that an identity service is available at this API endpoint. - To discover that an Identity Service is available at a specific URL, + To discover that an identity service 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 Service. + by entities acting as a client for the identity service. operationId: ping responses: 200: - description: An Identity Service is ready to serve requests. + description: An identity service is ready to serve requests. examples: application/json: {} schema: diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 3a33f2ea..51f6669e 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -200,9 +200,9 @@ paths: Notifies the server that a third party identifier has been bound to one of its users. description: |- - Used by Identity Services to notify the homeserver that one of its users + Used by identity services to notify the homeserver that one of its users has bound a third party identifier successfully, including any pending - room invites the Identity Service has been made aware of. + room invites the identity service has been made aware of. operationId: onBindThirdPartyIdentifier parameters: - in: body @@ -264,7 +264,7 @@ paths: type: object title: Identity Service Signatures description: |- - Signature from the Identity Service using a long-term private + Signature from the identity service using a long-term private key. properties: mxid: diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index a659921b..5d55a7e2 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -72,7 +72,7 @@ The word "homeserver" is spelt thus (rather than "home server", "Homeserver", or (argh) "Home Server"). However, an identity service is two words. .. Rationale: "homeserver" distinguishes from a "home server" which is a server - you have at home. "Identity Service" is clear, whereas "identityservice" is + you have at home. "identity service" is clear, whereas "identityservice" is horrible. Lists should: diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index ec4e1baf..2894f48e 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -995,7 +995,7 @@ Adding Account Administrative Contact Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A homeserver may keep some contact information for administrative use. -This is independent of any information kept by any Identity Services. +This is independent of any information kept by any identity services. {{administrative_contact_cs_http_api}} diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 33627f70..2b8bb4e2 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -140,7 +140,7 @@ Some standard error codes are below: third party identifier. :``M_UNKNOWN``: - An unknown error has occurred. + An unknown error has occurred. Privacy ------- diff --git a/specification/index.rst b/specification/index.rst index 481469cd..21cd6dfe 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -107,7 +107,7 @@ The functionality that Matrix provides includes: - Managing user accounts (registration, login, logout) - Use of 3rd Party IDs (3PIDs) such as email addresses, phone numbers, Facebook accounts to authenticate, identify and discover users on Matrix. -- Trusted federation of Identity Services for: +- Trusted federation of identity services for: + Publishing user public keys for PKI + Mapping of 3PIDs to Matrix IDs @@ -386,7 +386,7 @@ network accounts and phone numbers to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the user IDs of their contacts. In order to ensure that the mapping from 3PID to user ID is genuine, a globally -federated cluster of trusted "Identity Services" (IS) are used to verify the 3PID +federated cluster of trusted "identity services" (IS) are used to verify the 3PID and persist and replicate the mappings. Usage of an IS is not required in order for a client application to be part of diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 9d9827d1..905ffa61 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -125,7 +125,7 @@ All homeservers MUST verify the signature in the event's ``content.third_party_invite.signed`` object. The third party user will then need to verify their identity, which results in -a call from the Identity Service to the homeserver that bound the third party +a call from the identity service to the homeserver that bound the third party identifier to a user. The homeserver then exchanges the ``m.room.third_party_invite`` event in the room for a complete ``m.room.member`` event for ``membership: invite`` for the user that has bound the third party identifier. @@ -213,9 +213,9 @@ in the diagram. H1 MUST verify the request from H3 to ensure the ``signed`` property is correct as well as the ``key_validity_url`` as still being valid. This is done by making -a request to the `Identity Service /isvalid`_ endpoint, using the provided URL +a request to the `identity service /isvalid`_ endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided -URL must match the Identity Service specification. +URL must match the identity service specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. @@ -254,4 +254,4 @@ these is left to the implementer's discretion. -.. _`Identity Service /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid +.. _`identity service /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 8aa038ea..67b9c6d2 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -845,7 +845,7 @@ ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number). This identifier and its bindings to Matrix IDs are verified by an identity service -implementing the `Identity Service API`_. +implementing the `identity service API`_. Cases where an association exists for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -866,7 +866,7 @@ request. When a third-party identifier with pending invites gets bound to a Matrix ID, the identity service will send a POST request to the ID's homeserver as described -in the `Invitation Storage`_ section of the Identity Service API. +in the `Invitation Storage`_ section of the identity service API. The following process applies for each invite sent by the identity service: @@ -1193,7 +1193,7 @@ Example code .. _/query/directory: #get-matrix-federation-v1-query-directory .. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage -.. _`Identity Service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html +.. _`identity service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html .. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json From 7ac76fa27ce61fc64ed53db83041500f177787d7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:03:48 -0600 Subject: [PATCH 3/8] Actually we're going with "identity server" afterall --- api/client-server/administrative_contact.yaml | 24 +++++------ api/client-server/create_room.yaml | 4 +- .../wellknown/identity_server.yaml | 6 +-- api/client-server/registration.yaml | 26 ++++++------ api/client-server/third_party_membership.yaml | 18 ++++----- api/client-server/wellknown.yaml | 2 +- api/identity/associations.yaml | 4 +- .../definitions/request_email_validation.yaml | 2 +- .../request_msisdn_validation.yaml | 2 +- api/identity/email_associations.yaml | 6 +-- api/identity/invitation_signing.yaml | 4 +- api/identity/lookup.yaml | 4 +- api/identity/phone_associations.yaml | 8 ++-- api/identity/ping.yaml | 12 +++--- api/identity/pubkey.yaml | 2 +- api/identity/store_invite.yaml | 2 +- api/server-server/third_party_invite.yaml | 18 ++++----- changelogs/client_server.rst | 2 +- ...entity_service.rst => identity_server.rst} | 0 .../newsfragments/.gitignore | 0 .../pyproject.toml | 12 +++--- meta/documentation_style.rst | 4 +- meta/releasing_a_spec.md | 2 +- scripts/gendoc.py | 4 +- .../templating/matrix_templates/sections.py | 8 ++-- scripts/templating/matrix_templates/units.py | 2 +- specification/client_server_api.rst | 14 +++---- ...ervice_api.rst => identity_server_api.rst} | 40 +++++++++---------- specification/index.rst | 4 +- specification/modules/third_party_invites.rst | 34 ++++++++-------- specification/server_server_api.rst | 28 ++++++------- specification/targets.yaml | 6 +-- 32 files changed, 152 insertions(+), 152 deletions(-) rename changelogs/{identity_service.rst => identity_server.rst} (100%) rename changelogs/{identity_service => identity_server}/newsfragments/.gitignore (100%) rename changelogs/{identity_service => identity_server}/pyproject.toml (92%) rename specification/{identity_service_api.rst => identity_server_api.rst} (87%) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 52b62f11..8079e49c 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -35,7 +35,7 @@ paths: associated with the user's account. This is *not* the same as the list of third party identifiers bound to - the user's Matrix ID in identity services. + the user's Matrix ID in identity servers. Identifiers in this list may be used by the homeserver as, for example, identifiers that it will accept to reset the user's account password. @@ -77,7 +77,7 @@ paths: format: int64 description: |- The timestamp, in milliseconds, when the identifier was - validated by the identity service. + validated by the identity server. added_at: type: integer format: int64 @@ -106,13 +106,13 @@ paths: properties: client_secret: type: string - description: The client secret used in the session with the identity service. + description: The client secret used in the session with the identity server. id_server: type: string - description: The identity service to use. + description: The identity server to use. sid: type: string - description: The session identifier given by the identity service. + description: The session identifier given by the identity server. required: ["client_secret", "id_server", "sid"] bind: type: boolean @@ -138,11 +138,11 @@ paths: schema: type: object 403: - description: The credentials could not be verified with the identity service. + description: The credentials could not be verified with the identity server. examples: application/json: { "errcode": "M_THREEPID_AUTH_FAILED", - "error": "The third party credentials could not be verified by the identity service." + "error": "The third party credentials could not be verified by the identity server." } schema: "$ref": "definitions/errors/error.yaml" @@ -153,7 +153,7 @@ paths: summary: Deletes a third party identifier from the user's account description: |- Removes a third party identifier from the user's account. This might not - cause an unbind of the identifier from the identity service. + cause an unbind of the identifier from the identity server. operationId: delete3pidFromAccount security: - accessToken: [] @@ -187,7 +187,7 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - Proxies the identity service API ``validate/email/requestToken``, but + Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's @@ -206,7 +206,7 @@ paths: id_server: type: string description: |- - The hostname of the identity service to communicate with. May + The hostname of the identity server to communicate with. May optionally include a port. example: "id.example.com" required: ['id_server'] @@ -241,7 +241,7 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - Proxies the identity service API ``validate/msisdn/requestToken``, but + Proxies the identity server API ``validate/msisdn/requestToken``, but first checks that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's @@ -260,7 +260,7 @@ paths: id_server: type: string description: |- - The hostname of the identity service to communicate with. May + The hostname of the identity server to communicate with. May optionally include a port. example: "id.example.com" required: ['id_server'] diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index a0b1deaf..29eedb8e 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -138,10 +138,10 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity service which should be used for third party identifier lookups. + description: The hostname+port of the identity server which should be used for third party identifier lookups. medium: type: string - # TODO: Link to identity service spec when it eixsts + # TODO: Link to identity server spec when it eixsts description: The kind of address being passed in the address field, for example ``email``. address: type: string diff --git a/api/client-server/definitions/wellknown/identity_server.yaml b/api/client-server/definitions/wellknown/identity_server.yaml index d3399615..a8f7c31c 100644 --- a/api/client-server/definitions/wellknown/identity_server.yaml +++ b/api/client-server/definitions/wellknown/identity_server.yaml @@ -11,14 +11,14 @@ # 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. -title: Identity Service Information +title: Identity Server Information description: |- - Used by clients to discover identity service information. + Used by clients to discover identity server information. type: object properties: base_url: type: string - description: The base URL for the identity service for client-server connections. + description: The base URL for the identity server for client-server connections. example: https://identity.example.com required: - base_url diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 23edbe6d..f3a21aab 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -92,7 +92,7 @@ paths: type: boolean description: |- If true, the server binds the email used for authentication to - the Matrix ID with the identity service. + the Matrix ID with the identity server. example: false username: type: string @@ -204,9 +204,9 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - Proxies the identity service API ``validate/email/requestToken``, but + Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated - with an account on this homeserver. See the identity service API for + with an account on this homeserver. See the identity server API for further information. operationId: requestTokenToRegisterEmail parameters: @@ -221,7 +221,7 @@ paths: id_server: type: string description: |- - The hostname of the identity service to communicate with. May + The hostname of the identity server to communicate with. May optionally include a port. example: "id.example.com" required: ['id_server'] @@ -251,7 +251,7 @@ paths: instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the homeserver in question. - * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity service + * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server that is not trusted by this homeserver. examples: application/json: { @@ -264,9 +264,9 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - Proxies the identity service API ``validate/msisdn/requestToken``, but + Proxies the identity server API ``validate/msisdn/requestToken``, but first checks that the given phone number is not already associated - with an account on this homeserver. See the identity service API for + with an account on this homeserver. See the identity server API for further information. operationId: requestTokenToRegisterMSISDN parameters: @@ -281,7 +281,7 @@ paths: id_server: type: string description: |- - The hostname of the identity service to communicate with. May + The hostname of the identity server to communicate with. May optionally include a port. example: "id.example.com" required: ['id_server'] @@ -311,7 +311,7 @@ paths: instead send an SMS message to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given phone number has an account on the homeserver in question. - * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity service + * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server that is not trusted by this homeserver. examples: application/json: { @@ -373,7 +373,7 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- - Proxies the identity service API ``validate/email/requestToken``, but + Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address **is** associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the @@ -400,7 +400,7 @@ paths: id_server: type: string description: |- - The hostname of the identity service to communicate with. May + The hostname of the identity server to communicate with. May optionally include a port. example: "id.example.com" required: ['id_server'] @@ -435,7 +435,7 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. description: |- - Proxies the identity service API ``validate/msisdn/requestToken``, but + Proxies the identity server API ``validate/msisdn/requestToken``, but first checks that the given phone number **is** associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the @@ -462,7 +462,7 @@ paths: id_server: type: string description: |- - The hostname of the identity service to communicate with. May + The hostname of the identity server to communicate with. May optionally include a port. example: "id.example.com" required: ['id_server'] diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index a4d66a80..7921da0b 100644 --- a/api/client-server/third_party_membership.yaml +++ b/api/client-server/third_party_membership.yaml @@ -36,7 +36,7 @@ paths: *Note that there are two forms of this API, which are documented separately. This version of the API does not require that the inviter know the Matrix identifier of the invitee, and instead relies on third party identifiers. - The homeserver uses an identity service to perform the mapping from + The homeserver uses an identity server to perform the mapping from third party identifier to a Matrix identifier. The other is documented in the* `joining rooms section`_. @@ -47,31 +47,31 @@ paths: Only users currently in a particular room can invite other users to join that room. - If the identity service did know the Matrix user identifier for the + If the identity server did know the Matrix user identifier for the third party identifier, the homeserver will append a ``m.room.member`` event to the room. - If the identity service does not know a Matrix user identifier for the + If the identity server does not know a Matrix user identifier for the passed third party identifier, the homeserver will issue an invitation which can be accepted upon providing proof of ownership of the third - party identifier. This is achieved by the identity service generating a + party identifier. This is achieved by the identity server generating a token, which it gives to the inviting homeserver. The homeserver will add an ``m.room.third_party_invite`` event into the graph for the room, containing that token. When the invitee binds the invited third party identifier to a Matrix - user ID, the identity service will give the user a list of pending + user ID, the identity server will give the user a list of pending invitations, each containing: - The room ID to which they were invited - The token given to the homeserver - - A signature of the token, signed with the identity service's private key + - A signature of the token, signed with the identity server's private key - The matrix user ID who invited them to the room - If a token is requested from the identity service, the homeserver will + If a token is requested from the identity server, the homeserver will append a ``m.room.third_party_invite`` event to the room. .. _joining rooms section: `invite-by-user-id-endpoint`_ @@ -98,10 +98,10 @@ paths: properties: id_server: type: string - description: The hostname+port of the identity service which should be used for third party identifier lookups. + description: The hostname+port of the identity server which should be used for third party identifier lookups. medium: type: string - # TODO: Link to identity service spec when it eixsts + # TODO: Link to identity server spec when it eixsts description: The kind of address being passed in the address field, for example ``email``. address: type: string diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml index b2695c43..24e190f9 100644 --- a/api/client-server/wellknown.yaml +++ b/api/client-server/wellknown.yaml @@ -54,7 +54,7 @@ paths: description: Information about the homeserver to connect to. "$ref": "definitions/wellknown/homeserver.yaml" m.identity_server: - description: Optional. Information about the identity service to connect to. + description: Optional. Information about the identity server to connect to. "$ref": "definitions/wellknown/identity_server.yaml" additionalProperties: description: Application-dependent keys using Java package naming convention. diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index a400bf95..a500b87d 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Establishing Associations API" + title: "Matrix Identity Server Establishing Associations API" version: "1.0.0" host: localhost:8090 schemes: @@ -166,7 +166,7 @@ paths: signatures: type: object description: |- - The signatures of the verifying identity services which show that the + 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" diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 805cd123..197ea6be 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -33,7 +33,7 @@ properties: is a number greater than the most recent one which it has seen, scoped to that ``email`` + ``client_secret`` pair. This is to avoid repeatedly sending the same email in the case of request - retries between the POSTing user and the identity service. + retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. example: 1 diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index f8e37d39..1d6dc82b 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -41,7 +41,7 @@ properties: scoped to that ``country`` + ``phone_number`` + ``client_secret`` triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the - identity service. The client should increment this value if + identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent. example: 1 next_link: diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index eb6bc117..92534461 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Email Associations API" + title: "Matrix Identity Server Email Associations API" version: "1.0.0" host: localhost:8090 schemes: @@ -30,8 +30,8 @@ paths: description: |- Create a session for validating an email address. - The identity service will send an email containing a token. If that - token is presented to the identity service in the future, it indicates + 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. diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 6478423f..8950be29 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Ephemeral Invitation Signing API" + title: "Matrix Identity Server Ephemeral Invitation Signing API" version: "1.0.0" host: localhost:8090 schemes: @@ -30,7 +30,7 @@ paths: description: |- Sign invitation details. - The identity service will look up ``token`` which was stored in a call + 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 parameters: diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 1870a31f..ba814d5f 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -16,7 +16,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Lookup API" + title: "Matrix Identity Server Lookup API" version: "1.0.0" host: localhost:8090 schemes: @@ -86,7 +86,7 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + 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 diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index cc5933a8..558046e1 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Phone Number Associations API" + title: "Matrix Identity Server Phone Number Associations API" version: "1.0.0" host: localhost:8090 schemes: @@ -30,8 +30,8 @@ paths: description: |- Create a session for validating a phone number. - The identity service will send an SMS message containing a token. If - that token is presented to the identity service in the future, it + 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. @@ -62,7 +62,7 @@ paths: - ``M_INVALID_ADDRESS``: The phone number provided was invalid. - ``M_SEND_ERROR``: The validation SMS could not be sent. - - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an + - ``M_DESTINATION_REJECTED``: The identity server cannot deliver an SMS to the provided country or region. examples: application/json: { diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index abe33909..b2317cc9 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -15,7 +15,7 @@ swagger: "2.0" info: - title: "Matrix Identity Service Ping API" + title: "Matrix Identity Server Ping API" version: "1.0.0" host: localhost:8090 schemes: @@ -26,19 +26,19 @@ produces: paths: "/api/v1": get: - summary: Checks that an identity service is available at this API endpoint. + summary: Checks that an identity server is available at this API endpoint. description: |- - Checks that an identity service is available at this API endpoint. + Checks that an identity server is available at this API endpoint. - To discover that an identity service is available at a specific URL, + 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 service. + by entities acting as a client for the identity server. operationId: ping responses: 200: - description: An identity service is ready to serve requests. + description: An identity server is ready to serve requests. examples: application/json: {} schema: diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index e657c61c..92bdace6 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Public Key API" + title: "Matrix Identity Server Public Key API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 89d437a4..b1f9d802 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Service Store Invitations API" + title: "Matrix Identity Server Store Invitations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 51f6669e..2185a9cd 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -200,9 +200,9 @@ paths: Notifies the server that a third party identifier has been bound to one of its users. description: |- - Used by identity services to notify the homeserver that one of its users + Used by identity servers to notify the homeserver that one of its users has bound a third party identifier successfully, including any pending - room invites the identity service has been made aware of. + room invites the identity server has been made aware of. operationId: onBindThirdPartyIdentifier parameters: - in: body @@ -262,9 +262,9 @@ paths: # also make sure it isn't lying about anything, like the key version signed: type: object - title: Identity Service Signatures + title: Identity Server Signatures description: |- - Signature from the identity service using a long-term private + Signature from the identity server using a long-term private key. properties: mxid: @@ -280,14 +280,14 @@ paths: example: "Hello World" signatures: type: object - title: Identity Service Signature + title: Identity Server Signature description: |- - The signature from the identity service. The ``string`` key - is the identity service's domain name, such as vector.im + The signature from the identity server. The ``string`` key + is the identity server's domain name, such as vector.im additionalProperties: type: object - title: Identity Service Domain Signature - description: The signature for the identity service. + title: Identity Server Domain Signature + description: The signature for the identity server. properties: "ed25519:0": type: string diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 6053cbd5..d2ef7f2d 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -76,7 +76,7 @@ r0.3.0 - Spec clarifications: - Add endpoints and logic for invites and third-party invites to the federation - spec and update the JSON of the request sent by the identity service upon 3PID + spec and update the JSON of the request sent by the identity server upon 3PID binding (`#997 `_) - Fix "membership" property on third-party invite upgrade example diff --git a/changelogs/identity_service.rst b/changelogs/identity_server.rst similarity index 100% rename from changelogs/identity_service.rst rename to changelogs/identity_server.rst diff --git a/changelogs/identity_service/newsfragments/.gitignore b/changelogs/identity_server/newsfragments/.gitignore similarity index 100% rename from changelogs/identity_service/newsfragments/.gitignore rename to changelogs/identity_server/newsfragments/.gitignore diff --git a/changelogs/identity_service/pyproject.toml b/changelogs/identity_server/pyproject.toml similarity index 92% rename from changelogs/identity_service/pyproject.toml rename to changelogs/identity_server/pyproject.toml index 7a64eb0b..b5b8877b 100644 --- a/changelogs/identity_service/pyproject.toml +++ b/changelogs/identity_server/pyproject.toml @@ -1,29 +1,29 @@ [tool.towncrier] - filename = "../identity_service.rst" + filename = "../identity_server.rst" directory = "newsfragments" issue_format = "`#{issue} `_" title_format = "{version}" - + [[tool.towncrier.type]] directory = "breaking" name = "Breaking Changes" showcontent = true - + [[tool.towncrier.type]] directory = "deprecation" name = "Deprecations" showcontent = true - + [[tool.towncrier.type]] directory = "new" name = "New Endpoints" showcontent = true - + [[tool.towncrier.type]] directory = "feature" name = "Backwards Compatible Changes" showcontent = true - + [[tool.towncrier.type]] directory = "clarification" name = "Spec Clarifications" diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 5d55a7e2..95bb6412 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -69,10 +69,10 @@ have English as their first language. Prefer British English (colour, -ise) to American English. The word "homeserver" is spelt thus (rather than "home server", "Homeserver", -or (argh) "Home Server"). However, an identity service is two words. +or (argh) "Home Server"). However, an identity server is two words. .. Rationale: "homeserver" distinguishes from a "home server" which is a server - you have at home. "identity service" is clear, whereas "identityservice" is + you have at home. "identity server" is clear, whereas "identityservice" is horrible. Lists should: diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index 2d9cd34e..cbcb03d9 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -1,7 +1,7 @@ # How to release a specification There are several specifications that belong to matrix, such as the client-server -specification, server-server specification, and identity service specification. Each +specification, server-server specification, and identity server specification. Each of these gets released independently of each other with their own version numbers. Once a specification is ready for release, a branch should be created to track the diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 72659bb8..91b58849 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -527,7 +527,7 @@ if __name__ == '__main__': ) parser.add_argument( "--identity_release", "-i", action="store", default="unstable", - help="The identity service release tag to generate, e.g. r1.2" + help="The identity server release tag to generate, e.g. r1.2" ) parser.add_argument( "--list_targets", action="store_true", @@ -547,7 +547,7 @@ if __name__ == '__main__': substitutions = { "%CLIENT_RELEASE_LABEL%": args.client_release, - # we hardcode the major versions. This ends up in the example + # we hardcode the major versions. This ends up in the example # API URLs. When we have released a new major version, we'll # have to bump them. "%CLIENT_MAJOR_VERSION%": "r0", diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index f4c015c7..33317e0c 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -31,15 +31,15 @@ class MatrixSections(Sections): def render_client_server_changelog(self): changelogs = self.units.get("changelogs") return changelogs["client_server"] - + # TODO: We should make this a generic variable instead of having to add functions all the time. def render_push_gateway_changelog(self): changelogs = self.units.get("changelogs") return changelogs["push_gateway"] - def render_identity_service_changelog(self): + def render_identity_server_changelog(self): changelogs = self.units.get("changelogs") - return changelogs["identity_service"] + return changelogs["identity_server"] def render_server_server_changelog(self): changelogs = self.units.get("changelogs") @@ -226,4 +226,4 @@ class MatrixSections(Sections): definition=swagger_def['definition'], examples=swagger_def['examples'], title_kind=subtitle_title_char) - return rendered \ No newline at end of file + return rendered diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 11a9d441..48a11c7f 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -773,7 +773,7 @@ class MatrixUnits(Units): as_ver, "Privileged server plugins", ), TypeTableRow( - "`Identity Service API `_", + "`Identity Server API `_", "unstable", "Mapping of third party IDs to Matrix IDs", ), TypeTableRow( diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 2894f48e..3fb15105 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -145,7 +145,7 @@ Some requests have unique error codes: Sent when a threepid given to an API cannot be used because no record matching the threepid was found. :``M_SERVER_NOT_TRUSTED``: - The client's request used a third party server, eg. identity service, that this server does not trust. + The client's request used a third party server, eg. identity server, that this server does not trust. :``M_UNSUPPORTED_ROOM_VERSION``: The client's request to create a room used a room version that the server does not support. @@ -257,7 +257,7 @@ specify parameter values. The flow for this method is as follows: points to a valid homeserver. f. If the ``m.identity_server`` property is present, extract the - ``base_url`` value for use as the base URL of the identity service. + ``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 ``m.identity_server`` property is present, but does not have a @@ -685,7 +685,7 @@ the auth code. Homeservers can choose any path for the ``redirect URI``. Once the OAuth flow has completed, the client retries the request with the session only, as above. -Email-based (identity service) +Email-based (identity server) <<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: ``m.login.email.identity`` @@ -705,9 +705,9 @@ To use this authentication type, clients should submit an auth dict as follows: "type": "m.login.email.identity", "threepidCreds": [ { - "sid": "", - "client_secret": "", - "id_server": "" + "sid": "", + "client_secret": "", + "id_server": "" } ], "session": "" @@ -995,7 +995,7 @@ Adding Account Administrative Contact Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A homeserver may keep some contact information for administrative use. -This is independent of any information kept by any identity services. +This is independent of any information kept by any identity servers. {{administrative_contact_cs_http_api}} diff --git a/specification/identity_service_api.rst b/specification/identity_server_api.rst similarity index 87% rename from specification/identity_service_api.rst rename to specification/identity_server_api.rst index 2b8bb4e2..e236fe0b 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_server_api.rst @@ -15,7 +15,7 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -Identity Service API +Identity Server API ==================== {{unstable_warning_block_IDENTITY_RELEASE_LABEL}} @@ -23,7 +23,7 @@ Identity Service API The Matrix client-server and server-server APIs are largely expressed in Matrix user identifiers. From time to time, it is useful to refer to users by other ("third-party") identifiers, or "3pid"s, e.g. their email address or phone -number. This identity service specification describes how mappings between +number. This identity server specification describes how mappings between third-party identifiers and Matrix user identifiers can be established, validated, and used. This description technically may apply to any 3pid, but in practice has only been applied specifically to email addresses and phone numbers. @@ -35,14 +35,14 @@ Changelog --------- .. topic:: Version: %IDENTITY_RELEASE_LABEL% -{{identity_service_changelog}} +{{identity_server_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. For the full historical changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_server.rst Other versions of this specification @@ -50,25 +50,25 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: -- `HEAD `_: Includes all changes since the latest versioned release. +- `HEAD `_: Includes all changes since the latest versioned release. General principles ------------------ -The purpose of an identity service is to validate, store, and answer questions +The purpose of an identity server is to validate, store, and answer questions about the identities of users. In particular, it stores associations of the form "identifier X represents the same user as identifier Y", where identities may exist on different systems (such as email addresses, phone numbers, Matrix user IDs, etc). -The identity service has some private-public keypairs. When asked about an +The identity server has some private-public keypairs. When asked about an association, it will sign details of the association with its private key. Clients may validate the assertions about associations by verifying the signature -with the public key of the identity service. +with the public key of the identity server. -In general, identity services are treated as reliable oracles. They do not +In general, identity servers are treated as reliable oracles. They do not necessarily provide evidence that they have validated associations, but claim to -have done so. Establishing the trustworthiness of an individual identity service +have done so. Establishing the trustworthiness of an individual identity server is left as an exercise for the client. 3PID types are described in `3PID Types`_ Appendix. @@ -76,7 +76,7 @@ is left as an exercise for the client. API standards ------------- -The mandatory baseline for identity service communication in Matrix is exchanging +The mandatory baseline for identity server communication in Matrix is exchanging JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls use a Content-Type of ``application/json``. In addition, strings MUST be encoded as UTF-8. @@ -145,7 +145,7 @@ Some standard error codes are below: Privacy ------- -Identity is a privacy-sensitive issue. While the identity service exists to +Identity is a privacy-sensitive issue. While the identity server exists to provide identity information, access should be restricted to avoid leaking potentially sensitive data. In particular, being able to construct large-scale connections between identities should be avoided. To this end, in general APIs @@ -157,7 +157,7 @@ Web browser clients ------------------- It is realistic to expect that some clients will be written to be run within a web -browser or similar environment. In these cases, the identity service should respond to +browser or similar environment. In these cases, the identity server should respond to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all requests. @@ -177,17 +177,17 @@ Status check Key management -------------- -An identity service has some long-term public-private keypairs. These are named +An identity server has some long-term public-private keypairs. These are named in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an association, the standard `Signing JSON`_ algorithm applies. -.. TODO: Actually allow identity services to revoke all keys +.. TODO: Actually allow identity servers to revoke all keys See: https://github.com/matrix-org/matrix-doc/issues/1633 -.. In the event of key compromise, the identity service may revoke any of its keys. +.. In the event of key compromise, the identity server may revoke any of its keys. An HTTP API is offered to get public keys, and check whether a particular key is valid. -The identity service may also keep track of some short-term public-private +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. @@ -241,14 +241,14 @@ General Invitation storage ------------------ -An identity service can store pending invitations to a user's 3pid, which will +An identity server can store pending invitations to a user's 3pid, which will be retrieved and can be either notified on or look up when the 3pid is associated with a Matrix user ID. At a later point, if the owner of that particular 3pid binds it with a Matrix user -ID, the identity service will attempt to make an HTTP POST to the Matrix user's +ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a -long-term private key for the identity service. +long-term private key for the identity server. {{store_invite_is_http_api}} diff --git a/specification/index.rst b/specification/index.rst index 21cd6dfe..5e86e90b 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -107,7 +107,7 @@ The functionality that Matrix provides includes: - Managing user accounts (registration, login, logout) - Use of 3rd Party IDs (3PIDs) such as email addresses, phone numbers, Facebook accounts to authenticate, identify and discover users on Matrix. -- Trusted federation of identity services for: +- Trusted federation of identity servers for: + Publishing user public keys for PKI + Mapping of 3PIDs to Matrix IDs @@ -386,7 +386,7 @@ network accounts and phone numbers to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the user IDs of their contacts. In order to ensure that the mapping from 3PID to user ID is genuine, a globally -federated cluster of trusted "identity services" (IS) are used to verify the 3PID +federated cluster of trusted "identity servers" (IS) are used to verify the 3PID and persist and replicate the mappings. Usage of an IS is not required in order for a client application to be part of diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 905ffa61..700f4cdb 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -24,14 +24,14 @@ 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 service whether a Matrix user ID is known for +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 service to record the details of +- If it is not, the homeserver asks the identity server to record the details of the invitation, and to notify the invitee's homeserver of this pending invitation if it gets - a binding for this identifier in the future. The identity service returns a token + a binding for this identifier in the future. The identity server returns a token and public key to the inviting homeserver. When the invitee's homeserver receives the notification of the binding, it @@ -57,7 +57,7 @@ Server behaviour ---------------- Upon receipt of an ``/invite``, the server is expected to look up the third party -identifier with the provided identity service. If the lookup yields a result for +identifier with the provided identity server. If the lookup yields a result for a Matrix User ID then the normal invite process can be initiated. This process ends up looking like this: @@ -87,7 +87,7 @@ ends up looking like this: However, if the lookup does not yield a bound User ID, the homeserver must store -the invite on the identity service and emit a valid ``m.room.third_party_invite`` +the invite on the identity server and emit a valid ``m.room.third_party_invite`` event to the room. This process ends up looking like this: :: @@ -125,7 +125,7 @@ All homeservers MUST verify the signature in the event's ``content.third_party_invite.signed`` object. The third party user will then need to verify their identity, which results in -a call from the identity service to the homeserver that bound the third party +a call from the identity server to the homeserver that bound the third party identifier to a user. The homeserver then exchanges the ``m.room.third_party_invite`` event in the room for a complete ``m.room.member`` event for ``membership: invite`` for the user that has bound the third party identifier. @@ -142,7 +142,7 @@ the room. They may, however, indicate to their clients that a member's membership is questionable. For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, and an -identity service IS, the full sequence for a third party invite would look like +identity server IS, the full sequence for a third party invite would look like the following. This diagram assumes H1 and H2 are residents of the room while H3 is attempting to join. @@ -213,9 +213,9 @@ in the diagram. H1 MUST verify the request from H3 to ensure the ``signed`` property is correct as well as the ``key_validity_url`` as still being valid. This is done by making -a request to the `identity service /isvalid`_ endpoint, using the provided URL +a request to the `identity server /isvalid`_ endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided -URL must match the identity service specification. +URL must match the identity server specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. @@ -236,22 +236,22 @@ ID and a third party identifier is hard. In particular, being able to look up all third party identifiers from a matrix user ID (and accordingly, being able to link each third party identifier) should be avoided wherever possible. To this end, the third party identifier is not put in any event, rather an -opaque display name provided by the identity service is put into the events. +opaque display name provided by the identity server is put into the events. Clients should not remember or display third party identifiers from invites, other than for the use of the inviter themself. -Homeservers are not required to trust any particular identity service(s). It is -generally a client's responsibility to decide which identity services it trusts, -not a homeserver's. Accordingly, this API takes identity services as input from +Homeservers are not required to trust any particular identity server(s). It is +generally a client's responsibility to decide which identity servers it trusts, +not a homeserver's. Accordingly, this API takes identity servers as input from end users, and doesn't have any specific trusted set. It is possible some -homeservers may want to supply defaults, or reject some identity services for -*its* users, but no homeserver is allowed to dictate which identity services +homeservers may want to supply defaults, or reject some identity servers for +*its* users, but no homeserver is allowed to dictate which identity servers *other* homeservers' users trust. There is some risk of denial of service attacks by flooding homeservers or -identity services with many requests, or much state to store. Defending against +identity servers with many requests, or much state to store. Defending against these is left to the implementer's discretion. -.. _`identity service /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid +.. _`identity server /isvalid`: ../identity_server/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 67b9c6d2..19181514 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -844,35 +844,35 @@ When an user wants to invite another user in a room but doesn't know the Matrix ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number). -This identifier and its bindings to Matrix IDs are verified by an identity service -implementing the `identity service API`_. +This identifier and its bindings to Matrix IDs are verified by an identity server +implementing the `identity server API`_. Cases where an association exists for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the third-party identifier is already bound to a Matrix ID, a lookup request -on the identity service will return it. The invite is then processed by the inviting +on the identity server will return it. The invite is then processed by the inviting homeserver as a standard ``m.room.member`` invite event. This is the simplest case. Cases where an association doesn't exist for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the third-party identifier isn't bound to any Matrix ID, the inviting -homeserver will request the identity service to store an invite for this identifier +homeserver will request the identity server to store an invite for this identifier and to deliver it to whoever binds it to its Matrix ID. It will also send a ``m.room.third_party_invite`` event in the room to specify a display name, a token -and public keys the identity service provided as a response to the invite storage +and public keys the identity server provided as a response to the invite storage request. When a third-party identifier with pending invites gets bound to a Matrix ID, -the identity service will send a POST request to the ID's homeserver as described -in the `Invitation Storage`_ section of the identity service API. +the identity server will send a POST request to the ID's homeserver as described +in the `Invitation Storage`_ section of the identity server API. -The following process applies for each invite sent by the identity service: +The following process applies for each invite sent by the identity server: The invited homeserver will create a ``m.room.member`` invite event containing a special ``third_party_invite`` section containing the token and a signed object, -both provided by the identity service. +both provided by the identity server. If the invited homeserver is in the room the invite came from, it can auth the event and send it. @@ -894,14 +894,14 @@ server. To do so, it will fetch from the room's state events the ``m.room.third_party_invite`` event for which the state key matches with the value for the ``token`` key in the ``third_party_invite`` object from the ``m.room.member`` event's content to fetch the -public keys initially delivered by the identity service that stored the invite. +public keys initially delivered by the identity server that stored the invite. It will then use these keys to verify that the ``signed`` object (in the ``third_party_invite`` object from the ``m.room.member`` event's content) was -signed by the same identity service. +signed by the same identity server. Since this ``signed`` object can only be delivered once in the POST request -emitted by the identity service upon binding between the third-party identifier +emitted by the identity server upon binding between the third-party identifier and the Matrix ID, and contains the invited user's Matrix ID and the token delivered when the invite was stored, this verification will prove that the ``m.room.member`` invite event comes from the user owning the invited third-party @@ -1192,8 +1192,8 @@ Example code .. |/query/directory| replace:: ``/query/directory`` .. _/query/directory: #get-matrix-federation-v1-query-directory -.. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage -.. _`identity service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html +.. _`Invitation storage`: ../identity_server/%IDENTITY_RELEASE_LABEL%.html#invitation-storage +.. _`identity server API`: ../identity_server/%IDENTITY_RELEASE_LABEL%.html .. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json diff --git a/specification/targets.yaml b/specification/targets.yaml index a2eb5cdd..bdf0179f 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -18,10 +18,10 @@ targets: files: - server_server_api.rst version_label: "%SERVER_RELEASE_LABEL%" - identity_service: + identity_server: files: - - identity_service_api.rst - version_label: unstable + - identity_server_api.rst + version_label: "%IDENTITY_RELEASE_LABEL%" push_gateway: files: - push_gateway.rst From c94f3619b7a7545486cc3a0b7ffaf8bfdacd63f9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:09:18 -0600 Subject: [PATCH 4/8] Missed a rogue case of identity server --- meta/documentation_style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 95bb6412..2f6c9b16 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -72,7 +72,7 @@ The word "homeserver" is spelt thus (rather than "home server", "Homeserver", or (argh) "Home Server"). However, an identity server is two words. .. Rationale: "homeserver" distinguishes from a "home server" which is a server - you have at home. "identity server" is clear, whereas "identityservice" is + you have at home. "identity server" is clear, whereas "identityserver" is horrible. Lists should: From 7d34995ece2e057fbcb75b4a559a88f043b85095 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:35:32 -0600 Subject: [PATCH 5/8] It's actually an "identity server implementing the Identity Service API" Also add a note about appservices being special. --- api/client-server/administrative_contact.yaml | 4 ++-- api/client-server/create_room.yaml | 2 +- api/client-server/registration.yaml | 12 ++++++------ api/client-server/third_party_membership.yaml | 2 +- api/identity/associations.yaml | 2 +- api/identity/email_associations.yaml | 2 +- api/identity/invitation_signing.yaml | 2 +- api/identity/lookup.yaml | 2 +- api/identity/phone_associations.yaml | 2 +- api/identity/ping.yaml | 2 +- api/identity/pubkey.yaml | 2 +- api/identity/store_invite.yaml | 2 +- .../{identity_server.rst => identity_service.rst} | 0 .../newsfragments/.gitignore | 0 .../pyproject.toml | 2 +- meta/documentation_style.rst | 4 ++++ meta/releasing_a_spec.md | 2 +- scripts/gendoc.py | 2 +- scripts/templating/matrix_templates/sections.py | 4 ++-- scripts/templating/matrix_templates/units.py | 2 +- ...ntity_server_api.rst => identity_service_api.rst} | 8 ++++---- specification/modules/third_party_invites.rst | 4 ++-- specification/server_server_api.rst | 8 ++++---- specification/targets.yaml | 4 ++-- 24 files changed, 40 insertions(+), 36 deletions(-) rename changelogs/{identity_server.rst => identity_service.rst} (100%) rename changelogs/{identity_server => identity_service}/newsfragments/.gitignore (100%) rename changelogs/{identity_server => identity_service}/pyproject.toml (95%) rename specification/{identity_server_api.rst => identity_service_api.rst} (97%) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 8079e49c..98e997f2 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -187,7 +187,7 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - Proxies the identity server API ``validate/email/requestToken``, but + Proxies the Identity Service API ``validate/email/requestToken``, but first checks that the given email address is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's @@ -241,7 +241,7 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - Proxies the identity server API ``validate/msisdn/requestToken``, but + Proxies the Identity Service API ``validate/msisdn/requestToken``, but first checks that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 29eedb8e..d361d973 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -141,7 +141,7 @@ paths: description: The hostname+port of the identity server which should be used for third party identifier lookups. medium: type: string - # TODO: Link to identity server spec when it eixsts + # TODO: Link to Identity Service spec when it eixsts description: The kind of address being passed in the address field, for example ``email``. address: type: string diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index f3a21aab..e2d35d2c 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -204,9 +204,9 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - Proxies the identity server API ``validate/email/requestToken``, but + Proxies the Identity Service API ``validate/email/requestToken``, but first checks that the given email address is not already associated - with an account on this homeserver. See the identity server API for + with an account on this homeserver. See the Identity Service API for further information. operationId: requestTokenToRegisterEmail parameters: @@ -264,9 +264,9 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - Proxies the identity server API ``validate/msisdn/requestToken``, but + Proxies the Identity Service API ``validate/msisdn/requestToken``, but first checks that the given phone number is not already associated - with an account on this homeserver. See the identity server API for + with an account on this homeserver. See the Identity Service API for further information. operationId: requestTokenToRegisterMSISDN parameters: @@ -373,7 +373,7 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- - Proxies the identity server API ``validate/email/requestToken``, but + Proxies the Identity Service API ``validate/email/requestToken``, but first checks that the given email address **is** associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the @@ -435,7 +435,7 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. description: |- - Proxies the identity server API ``validate/msisdn/requestToken``, but + Proxies the Identity Service API ``validate/msisdn/requestToken``, but first checks that the given phone number **is** associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index 7921da0b..077e1f6a 100644 --- a/api/client-server/third_party_membership.yaml +++ b/api/client-server/third_party_membership.yaml @@ -101,7 +101,7 @@ paths: description: The hostname+port of the identity server which should be used for third party identifier lookups. medium: type: string - # TODO: Link to identity server spec when it eixsts + # TODO: Link to Identity Service spec when it eixsts description: The kind of address being passed in the address field, for example ``email``. address: type: string diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index a500b87d..edd43f5d 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Establishing Associations API" + title: "Matrix Identity Service Establishing Associations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 92534461..19faf29a 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Email Associations API" + title: "Matrix Identity Service Email Associations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 8950be29..4e10e2b5 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Ephemeral Invitation Signing API" + title: "Matrix Identity Service Ephemeral Invitation Signing API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index ba814d5f..fd50f94b 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -16,7 +16,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Lookup API" + title: "Matrix Identity Service Lookup API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index 558046e1..a327ab6f 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Phone Number Associations API" + title: "Matrix Identity Service Phone Number Associations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index b2317cc9..05e12a87 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -15,7 +15,7 @@ swagger: "2.0" info: - title: "Matrix Identity Server Ping API" + title: "Matrix Identity Service Ping API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 92bdace6..e657c61c 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Public Key API" + title: "Matrix Identity Service Public Key API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index b1f9d802..89d437a4 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Store Invitations API" + title: "Matrix Identity Service Store Invitations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/changelogs/identity_server.rst b/changelogs/identity_service.rst similarity index 100% rename from changelogs/identity_server.rst rename to changelogs/identity_service.rst diff --git a/changelogs/identity_server/newsfragments/.gitignore b/changelogs/identity_service/newsfragments/.gitignore similarity index 100% rename from changelogs/identity_server/newsfragments/.gitignore rename to changelogs/identity_service/newsfragments/.gitignore diff --git a/changelogs/identity_server/pyproject.toml b/changelogs/identity_service/pyproject.toml similarity index 95% rename from changelogs/identity_server/pyproject.toml rename to changelogs/identity_service/pyproject.toml index b5b8877b..a7fe582d 100644 --- a/changelogs/identity_server/pyproject.toml +++ b/changelogs/identity_service/pyproject.toml @@ -1,5 +1,5 @@ [tool.towncrier] - filename = "../identity_server.rst" + filename = "../identity_service.rst" directory = "newsfragments" issue_format = "`#{issue} `_" title_format = "{version}" diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 2f6c9b16..e59ad229 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -71,6 +71,10 @@ Prefer British English (colour, -ise) to American English. The word "homeserver" is spelt thus (rather than "home server", "Homeserver", or (argh) "Home Server"). However, an identity server is two words. +An "identity server" (spelt thus) implements the Identity Service API (also spelt +thus). However, "Application Services" (spelt thus) implement the Application Service +API. Application Services should not be called "appservices" in documentation. + .. Rationale: "homeserver" distinguishes from a "home server" which is a server you have at home. "identity server" is clear, whereas "identityserver" is horrible. diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index cbcb03d9..2d9cd34e 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -1,7 +1,7 @@ # How to release a specification There are several specifications that belong to matrix, such as the client-server -specification, server-server specification, and identity server specification. Each +specification, server-server specification, and identity service specification. Each of these gets released independently of each other with their own version numbers. Once a specification is ready for release, a branch should be created to track the diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 91b58849..8310ad58 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -527,7 +527,7 @@ if __name__ == '__main__': ) parser.add_argument( "--identity_release", "-i", action="store", default="unstable", - help="The identity server release tag to generate, e.g. r1.2" + help="The identity service release tag to generate, e.g. r1.2" ) parser.add_argument( "--list_targets", action="store_true", diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 33317e0c..185970c9 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -37,9 +37,9 @@ class MatrixSections(Sections): changelogs = self.units.get("changelogs") return changelogs["push_gateway"] - def render_identity_server_changelog(self): + def render_identity_service_changelog(self): changelogs = self.units.get("changelogs") - return changelogs["identity_server"] + return changelogs["identity_service"] def render_server_server_changelog(self): changelogs = self.units.get("changelogs") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 48a11c7f..11a9d441 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -773,7 +773,7 @@ class MatrixUnits(Units): as_ver, "Privileged server plugins", ), TypeTableRow( - "`Identity Server API `_", + "`Identity Service API `_", "unstable", "Mapping of third party IDs to Matrix IDs", ), TypeTableRow( diff --git a/specification/identity_server_api.rst b/specification/identity_service_api.rst similarity index 97% rename from specification/identity_server_api.rst rename to specification/identity_service_api.rst index e236fe0b..2980797f 100644 --- a/specification/identity_server_api.rst +++ b/specification/identity_service_api.rst @@ -15,7 +15,7 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -Identity Server API +Identity Service API ==================== {{unstable_warning_block_IDENTITY_RELEASE_LABEL}} @@ -35,14 +35,14 @@ Changelog --------- .. topic:: Version: %IDENTITY_RELEASE_LABEL% -{{identity_server_changelog}} +{{identity_service_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. For the full historical changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_server.rst +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst Other versions of this specification @@ -50,7 +50,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: -- `HEAD `_: Includes all changes since the latest versioned release. +- `HEAD `_: Includes all changes since the latest versioned release. General principles ------------------ diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 700f4cdb..9a939143 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -215,7 +215,7 @@ H1 MUST verify the request from H3 to ensure the ``signed`` property is correct as well as the ``key_validity_url`` as still being valid. This is done by making a request to the `identity server /isvalid`_ endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided -URL must match the identity server specification. +URL must match the identity service specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. @@ -254,4 +254,4 @@ these is left to the implementer's discretion. -.. _`identity server /isvalid`: ../identity_server/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid +.. _`identity server /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 19181514..36d7d5d4 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -845,7 +845,7 @@ ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number). This identifier and its bindings to Matrix IDs are verified by an identity server -implementing the `identity server API`_. +implementing the `Identity Service API`_. Cases where an association exists for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -866,7 +866,7 @@ request. When a third-party identifier with pending invites gets bound to a Matrix ID, the identity server will send a POST request to the ID's homeserver as described -in the `Invitation Storage`_ section of the identity server API. +in the `Invitation Storage`_ section of the Identity Service API. The following process applies for each invite sent by the identity server: @@ -1192,8 +1192,8 @@ Example code .. |/query/directory| replace:: ``/query/directory`` .. _/query/directory: #get-matrix-federation-v1-query-directory -.. _`Invitation storage`: ../identity_server/%IDENTITY_RELEASE_LABEL%.html#invitation-storage -.. _`identity server API`: ../identity_server/%IDENTITY_RELEASE_LABEL%.html +.. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage +.. _`Identity Service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html .. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json diff --git a/specification/targets.yaml b/specification/targets.yaml index bdf0179f..93e1b8a6 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -18,9 +18,9 @@ targets: files: - server_server_api.rst version_label: "%SERVER_RELEASE_LABEL%" - identity_server: + identity_service: files: - - identity_server_api.rst + - identity_service_api.rst version_label: "%IDENTITY_RELEASE_LABEL%" push_gateway: files: From 2af09655ce94f45a68199f105b8359e30a58e027 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:44:23 -0600 Subject: [PATCH 6/8] Fix the stragglers --- api/identity/definitions/request_email_validation.yaml | 2 +- api/identity/definitions/request_msisdn_validation.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 197ea6be..fa160760 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -41,6 +41,6 @@ properties: type: string description: |- Optional. When the validation is completed, the identity - service will redirect the user to this URL. + server will redirect the user to this URL. example: "https://example.org/congratulations.html" required: ["client_secret", "email", "send_attempt"] diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index 1d6dc82b..ab3dee4a 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -48,6 +48,6 @@ properties: type: string description: |- Optional. When the validation is completed, the identity - service will redirect the user to this URL. + server will redirect the user to this URL. example: "https://example.org/congratulations.html" required: ["client_secret", "country", "phone_number", "send_attempt"] From 218b86d6e8c6502fa8ccf286358aa1304d282ee9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:48:41 -0600 Subject: [PATCH 7/8] Hopefully the last one --- specification/modules/third_party_invites.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 9a939143..df71d215 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -215,7 +215,7 @@ H1 MUST verify the request from H3 to ensure the ``signed`` property is correct as well as the ``key_validity_url`` as still being valid. This is done by making a request to the `identity server /isvalid`_ endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided -URL must match the identity service specification. +URL must match the Identity Service Specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. From f3825c582795c3dc35fab4cafcc047f8d6c52f88 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:55:07 -0600 Subject: [PATCH 8/8] A couple more stragglers --- specification/identity_service_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 2980797f..793e8dc8 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -23,7 +23,7 @@ Identity Service API The Matrix client-server and server-server APIs are largely expressed in Matrix user identifiers. From time to time, it is useful to refer to users by other ("third-party") identifiers, or "3pid"s, e.g. their email address or phone -number. This identity server specification describes how mappings between +number. This Identity Service Specification describes how mappings between third-party identifiers and Matrix user identifiers can be established, validated, and used. This description technically may apply to any 3pid, but in practice has only been applied specifically to email addresses and phone numbers. @@ -256,7 +256,7 @@ Ephemeral invitation signing ---------------------------- To aid clients who may not be able to perform crypto themselves, the identity -service offers some crypto functionality to help in accepting invitations. +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.