-
Notifications
You must be signed in to change notification settings - Fork 384
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
Relates to matrix-org/matrix-spec#1867 Signed-off-by: Johannes Marbach <[email protected]>
- Loading branch information
Showing
1 changed file
with
133 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,133 @@ | ||
| # MSC4170: 403 error responses for profile APIs | ||
|
|
||
| Matrix currently defines the following [client-server APIs] for profile look-ups: | ||
|
|
||
| - [`GET /_matrix/client/v3/profile/{userId}`] | ||
| - [`GET /_matrix/client/v3/profile/{userId}/avatar_url`] | ||
| - [`GET /_matrix/client/v3/profile/{userId}/displayname`] | ||
|
|
||
| These endpoints also support look-up over federation via the accompanying | ||
| [server-server API]: | ||
|
|
||
| - [`GET /_matrix/federation/v1/query/profile`] | ||
|
|
||
| Each of these endpoints has a documented 404 response for the case that no profile | ||
| information is available. | ||
|
|
||
| > 404 There is no profile information for this user or this user does not exist. | ||
| > | ||
| > 404 There is no avatar URL for this user or this user does not exist. | ||
| > | ||
| > 404 There is no display name for this user or this user does not exist. | ||
| > | ||
| > 404 The user does not exist or does not have a profile. | ||
| However, `GET /_matrix/client/v3/profile/{userId}` additionally reserves a 403 | ||
| status code that is not available on the other endpoints and can be used to deny | ||
| profile look-ups. | ||
|
|
||
| > 403 The server is unwilling to disclose whether the user exists and/or has profile information. | ||
| Unfortunately, the concrete semantics of when to respond with 403 are not fully | ||
| spelled out in the spec and understanding prior proposals' intention requires some | ||
| archeology (see the history section below). | ||
|
|
||
| The current proposal aims to restore consistency among the profile endpoints | ||
| by standardizing their 403 error response format and behaviour. | ||
|
|
||
|
|
||
| ## Proposal | ||
|
|
||
| For the endpoints in the client-server API | ||
|
|
||
| - [`GET /_matrix/client/v3/profile/{userId}`] | ||
| - [`GET /_matrix/client/v3/profile/{userId}/avatar_url`] | ||
| - [`GET /_matrix/client/v3/profile/{userId}/displayname`] | ||
|
|
||
| homeservers MUST at a minimum allow profile look-up for users that either share a room | ||
| with the requester or reside in a public room known to the homeserver (i.e, the same | ||
| requirements as [`POST /_matrix/client/v3/user_directory/search`])[^3]. In all other | ||
| cases, homeservers MAY deny profile look-up by responding with 403 `M_FORBIDDEN`. | ||
|
|
||
| If a remote user is queried through the client-server endpoints and the query is not | ||
| denied per the preceding paragraph, homeservers SHOULD query the remote server for the | ||
| user's profile information. | ||
|
|
||
| Homeservers MAY deny profile look-up over federation by responding with 403 `M_FORBIDDEN` | ||
| to [`GET /_matrix/federation/v1/query/profile`]. To be clear: there is no requirement to return | ||
| profiles of users in public or shared rooms over the federation API. | ||
|
|
||
| Homeservers MAY choose whether to respond with 403 or 404 when the requested user does | ||
| not exist. If the server denies profile look-up in all but the required cases, 403 is | ||
| RECOMMENDED. | ||
|
|
||
|
|
||
| ## Potential issues | ||
|
|
||
| Synapse already complies with this proposal in its default configuration. However, | ||
| its `limit_profile_requests_to_users_who_share_rooms` config setting is only partially | ||
| compatible with this proposal because it disallows profile look-up for users in public | ||
| rooms that the requester does not share a room with. This inconsistency would need to | ||
| be fixed if this proposal is accepted into the spec. | ||
|
|
||
|
|
||
| ## Alternatives | ||
|
|
||
| None. | ||
|
|
||
|
|
||
| ## Security considerations | ||
|
|
||
| This proposal allows server administrators to lock down profile look-ups via the | ||
| client-server API for all situations except those in which the profile information | ||
| is already available to the requester via room membership. This complements the | ||
| existing ability to deny profile look-ups on the server-server API and, if configured | ||
| accordingly, increases privacy for users. | ||
|
|
||
|
|
||
| ## History | ||
|
|
||
| In [2017], the user directory API, [`POST /_matrix/client/v3/user_directory/search`], | ||
| which closely relates to the profile APIs, was introduced into the spec. Since its | ||
| inception, it contained the requirement for servers to consider (at least) users from | ||
| shared and public rooms in the search. | ||
|
|
||
| Later, [MSC1301] proposed a 403 `M_USER_NOT_PUBLIC` response on all four profile | ||
| endpoints to optionally disallow profile look-up for users that the requester does | ||
| not share a room with. This MSC was never accepted, but in 2019 | ||
| was partially implemented by Synapse[^1]: it was only implemented for the client-server | ||
| endpoints, and an error code of `M_FORBIDDEN` was used rather than `M_USER_NOT_PUBLIC`. | ||
|
|
||
| In 2021, Synapse implemented[^2] a switchable feature to disable profile look-up | ||
| over federation via a 403 `M_FORBIDDEN` response. [MSC3550] picked up on this | ||
| feature and introduced this response type in the spec though only on the | ||
| `GET /_matrix/client/v3/profile/{userId}` endpoint in the client-server API. | ||
|
|
||
|
|
||
| ## Unstable prefix | ||
|
|
||
| None because this proposal only affects HTTP status codes and Matrix error codes. | ||
|
|
||
|
|
||
| ## Dependencies | ||
|
|
||
| None. | ||
|
|
||
|
|
||
| [^1]: https://github.com/element-hq/synapse/commit/c0e0740bef0db661abce352afaf6c958e276f11d | ||
| [^2]: https://github.com/matrix-org/synapse/pull/9203/files#diff-2f70c35b9dd342bfdaaed445847e0ccabbad63aa9a208d80d38fb248cbf57602L311 | ||
| [^3]: As stated in https://github.com/matrix-org/matrix-spec/issues/633, the spec currently | ||
| doesn't clearly define what a public room is. This proposal does not aim to solve this | ||
| problem and instead only requires that the user directory and profile APIs use the same | ||
| definition. | ||
|
|
||
| [`GET /_matrix/client/v3/profile/{userId}`]: https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv3profileuserid | ||
| [`GET /_matrix/client/v3/profile/{userId}/avatar_url`]: https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv3profileuseridavatar_url | ||
| [`GET /_matrix/client/v3/profile/{userId}/displayname`]: https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv3profileuseriddisplayname | ||
| [`GET /_matrix/federation/v1/query/profile`]: https://spec.matrix.org/v1.11/server-server-api/#get_matrixfederationv1queryprofile | ||
| [`POST /_matrix/client/v3/user_directory/search`]: https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3user_directorysearch | ||
| [2017]: https://github.com/matrix-org/matrix-spec-proposals/pull/1096/files#diff-332ce28a7277b9375050644632f99c0e606acb751adc54c64c5faabf981ac7edR35 | ||
| [MSC1301]: https://github.com/matrix-org/matrix-spec-proposals/issues/1301 | ||
| [MSC3550]: https://github.com/matrix-org/matrix-spec-proposals/pull/3550 | ||
| [client-server APIs]: https://spec.matrix.org/v1.11/client-server-api/#profiles | ||
| [server-server API]: https://spec.matrix.org/v1.11/server-server-api/#get_matrixfederationv1queryprofile |