134 lines
6.2 KiB
Markdown
134 lines
6.2 KiB
Markdown
# 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
|