MSC4170: 403 error responses for profile APIs

proposals/4170-profile-403.md

@@ -0,0 +1,99 @@
+# 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.
+
+Initially, [MSC1301] introduced a 403 `M_USER_NOT_PUBLIC` response to disallow
+profile look-up for users that the requester does not share a room with. This was
+implemented in Synapse[^1] behind a config flag but only for the client-server
+endpoints and with an error code of `M_FORBIDDEN`. As for the spec, while the
+[user directory] section received a note about similar room membership conditions,
+this behaviour didn't end up being documented at all for the profile endpoints.
+
+Later, 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
+client-server API.
+
+The current proposal aims to restore consistency among the profile endpoints
+by standardizing their 403 error response format and behaviour.
+
+
+## Proposal
+
+Homeservers MUST allow profile look-up for local users that either share a room
+with the requester or reside in a public room known to the homeserver. Homeservers
+MAY deny profile look-up for local users in all other cases. If they do, they MUST
+respond with 403 `M_FORBIDDEN` on all endpoints that retrieve profile information.
+
+Additionally, homeservers SHOULD query remote servers for profiles if requested.
+Homeservers MAY disable profile look-up over federation. If they do, requests to
+`GET /_matrix/federation/v1/query/profile` MUST be replied to with 403 `M_FORBIDDEN`.
+
+Whenever profile look-up is disabled, the server's response MUST be 403 `M_FORBIDDEN`
+regardless of whether or not the user exists.
+
+
+## Potential issues
+
+While Synapse already implements the behaviour that is proposed here, other
+homeservers might have to be adapted.
+
+
+## Alternatives
+
+None.
+
+
+## Security considerations
+
+None.
+
+
+## Unstable prefix
+
+None.
+
+
+## Dependencies
+
+None.
+
+
+[^1]: https://github.com/element-hq/synapse/commit/c0e0740bef0db661abce352afaf6c958e276f11d
+[^2]: https://github.com/matrix-org/synapse/pull/9203/files#diff-2f70c35b9dd342bfdaaed445847e0ccabbad63aa9a208d80d38fb248cbf57602L311
+
+[MSC1301]: https://docs.google.com/document/d/1G7JjyTuJlZHieuAflGFWmdKyNViGGLRTWON7AMl0wrM/edit
+[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
+[user directory]: https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3user_directorysearch