diff --git a/changelog.d/13227.feature b/changelog.d/13227.feature new file mode 100644 index 000000000000..377297cfcd89 --- /dev/null +++ b/changelog.d/13227.feature @@ -0,0 +1 @@ +Add a module callback for unbinding a 3PID. diff --git a/docs/modules/third_party_rules_callbacks.md b/docs/modules/third_party_rules_callbacks.md index e1a5b6524fb4..76428f5e4371 100644 --- a/docs/modules/third_party_rules_callbacks.md +++ b/docs/modules/third_party_rules_callbacks.md @@ -265,6 +265,33 @@ server_. If multiple modules implement this callback, Synapse runs them all in order. +### `unbind_threepid` + +_First introduced in Synapse v1.74.0_ + +```python +async def unbind_threepid( + user_id: str, medium: str, address: str, identity_server: str +) -> Tuple[bool, bool]: +``` + +Called before a threepid association is removed. + +The module is given the Matrix ID of the user to which an association is to be removed, +as well as the medium (`email` or `msisdn`), address of the third-party identifier and +the identity server where the threepid was successfully registered. + +A module can hence do its own custom unbinding, if for example it did also registered a custom +binding logic with `on_threepid_bind`. + +It should return a tuple of 2 booleans: +- first one should be `True` on a success calling the identity server, otherwise `False` if +the identity server doesn't support unbinding (or no identity server found to contact). +- second one should be `True` if unbind needs to stop there. In this case no other module +unbind will be called, and the default unbind made to the IS that was used on bind will also be +skipped. In any case the mapping will be removed from the Synapse 3pid remote table, +except if an Exception was raised at some point. + ## Example The example below is a module that implements the third-party rules callback diff --git a/synapse/events/third_party_rules.py b/synapse/events/third_party_rules.py index 72ab69689887..80303116975c 100644 --- a/synapse/events/third_party_rules.py +++ b/synapse/events/third_party_rules.py @@ -45,6 +45,7 @@ ON_PROFILE_UPDATE_CALLBACK = Callable[[str, ProfileInfo, bool, bool], Awaitable] ON_USER_DEACTIVATION_STATUS_CHANGED_CALLBACK = Callable[[str, bool, bool], Awaitable] ON_THREEPID_BIND_CALLBACK = Callable[[str, str, str], Awaitable] +UNBIND_THREEPID_CALLBACK = Callable[[str, str, str, str], Awaitable[Tuple[bool, bool]]] def load_legacy_third_party_event_rules(hs: "HomeServer") -> None: @@ -174,6 +175,7 @@ def __init__(self, hs: "HomeServer"): ON_USER_DEACTIVATION_STATUS_CHANGED_CALLBACK ] = [] self._on_threepid_bind_callbacks: List[ON_THREEPID_BIND_CALLBACK] = [] + self._unbind_threepid_callbacks: List[UNBIND_THREEPID_CALLBACK] = [] def register_third_party_rules_callbacks( self, @@ -193,6 +195,7 @@ def register_third_party_rules_callbacks( ON_USER_DEACTIVATION_STATUS_CHANGED_CALLBACK ] = None, on_threepid_bind: Optional[ON_THREEPID_BIND_CALLBACK] = None, + unbind_threepid: Optional[UNBIND_THREEPID_CALLBACK] = None, ) -> None: """Register callbacks from modules for each hook.""" if check_event_allowed is not None: @@ -230,6 +233,9 @@ def register_third_party_rules_callbacks( if on_threepid_bind is not None: self._on_threepid_bind_callbacks.append(on_threepid_bind) + if unbind_threepid is not None: + self._unbind_threepid_callbacks.append(unbind_threepid) + async def check_event_allowed( self, event: EventBase, context: EventContext ) -> Tuple[bool, Optional[dict]]: @@ -523,3 +529,41 @@ async def on_threepid_bind(self, user_id: str, medium: str, address: str) -> Non logger.exception( "Failed to run module API callback %s: %s", callback, e ) + + async def unbind_threepid( + self, user_id: str, medium: str, address: str, identity_server: str + ) -> Tuple[bool, bool]: + """Called before a threepid association is removed. + + Note that this callback is called before an association is deleted on the + local homeserver. + + Args: + user_id: the user being associated with the threepid. + medium: the threepid's medium. + address: the threepid's address. + identity_server: the identity server where the threepid was successfully registered. + + Returns: + A tuple of 2 booleans reporting if a changed happened for the first, and if unbind + needs to stop there for the second (True value). In this case no other module unbind will be + called, and the default unbind made to the IS that was used on bind will also be skipped. + In any case the mapping will be removed from the Synapse 3pid remote table, except if an Exception + was raised at some point. + """ + + global_changed = False + for callback in self._unbind_threepid_callbacks: + try: + (changed, stop) = await callback( + user_id, medium, address, identity_server + ) + global_changed |= changed + if stop: + return global_changed, True + except Exception as e: + logger.exception( + "Failed to run module API callback %s: %s", callback, e + ) + + return global_changed, False diff --git a/synapse/handlers/identity.py b/synapse/handlers/identity.py index 848e46eb9ba6..3257b8d0db55 100644 --- a/synapse/handlers/identity.py +++ b/synapse/handlers/identity.py @@ -275,49 +275,64 @@ async def try_unbind_threepid_with_id_server( server doesn't support unbinding """ - if not valid_id_server_location(id_server): - raise SynapseError( - 400, - "id_server must be a valid hostname with optional port and path components", - ) + medium = threepid["medium"] + address = threepid["address"] - url = "https://%s/_matrix/identity/v2/3pid/unbind" % (id_server,) - url_bytes = b"/_matrix/identity/v2/3pid/unbind" - - content = { - "mxid": mxid, - "threepid": {"medium": threepid["medium"], "address": threepid["address"]}, - } - - # we abuse the federation http client to sign the request, but we have to send it - # using the normal http client since we don't want the SRV lookup and want normal - # 'browser-like' HTTPS. - auth_headers = self.federation_http_client.build_auth_headers( - destination=None, - method=b"POST", - url_bytes=url_bytes, - content=content, - destination_is=id_server.encode("ascii"), + (changed, stop,) = await self.hs.get_third_party_event_rules().unbind_threepid( + mxid, medium, address, id_server ) - headers = {b"Authorization": auth_headers} - try: - # Use the blacklisting http client as this call is only to identity servers - # provided by a client - await self.blacklisting_http_client.post_json_get_json( - url, content, headers + # If a module wants to take over unbind it will return stop = True, + # in this case we should just purge the table from the 3pid record + if not stop: + if not valid_id_server_location(id_server): + raise SynapseError( + 400, + "id_server must be a valid hostname with optional port and path components", + ) + + url = "https://%s/_matrix/identity/v2/3pid/unbind" % (id_server,) + url_bytes = b"/_matrix/identity/v2/3pid/unbind" + + content = { + "mxid": mxid, + "threepid": { + "medium": threepid["medium"], + "address": threepid["address"], + }, + } + + # we abuse the federation http client to sign the request, but we have to send it + # using the normal http client since we don't want the SRV lookup and want normal + # 'browser-like' HTTPS. + auth_headers = self.federation_http_client.build_auth_headers( + destination=None, + method=b"POST", + url_bytes=url_bytes, + content=content, + destination_is=id_server.encode("ascii"), ) - changed = True - except HttpResponseException as e: - changed = False - if e.code in (400, 404, 501): - # The remote server probably doesn't support unbinding (yet) - logger.warning("Received %d response while unbinding threepid", e.code) - else: - logger.error("Failed to unbind threepid on identity server: %s", e) - raise SynapseError(500, "Failed to contact identity server") - except RequestTimedOutError: - raise SynapseError(500, "Timed out contacting identity server") + headers = {b"Authorization": auth_headers} + + try: + # Use the blacklisting http client as this call is only to identity servers + # provided by a client + await self.blacklisting_http_client.post_json_get_json( + url, content, headers + ) + changed &= True + except HttpResponseException as e: + changed &= False + if e.code in (400, 404, 501): + # The remote server probably doesn't support unbinding (yet) + logger.warning( + "Received %d response while unbinding threepid", e.code + ) + else: + logger.error("Failed to unbind threepid on identity server: %s", e) + raise SynapseError(500, "Failed to contact identity server") + except RequestTimedOutError: + raise SynapseError(500, "Timed out contacting identity server") await self.store.remove_user_bound_threepid( user_id=mxid, diff --git a/synapse/module_api/__init__.py b/synapse/module_api/__init__.py index 0092a03c59a7..53506f69d37c 100644 --- a/synapse/module_api/__init__.py +++ b/synapse/module_api/__init__.py @@ -68,6 +68,7 @@ ON_PROFILE_UPDATE_CALLBACK, ON_THREEPID_BIND_CALLBACK, ON_USER_DEACTIVATION_STATUS_CHANGED_CALLBACK, + UNBIND_THREEPID_CALLBACK, ) from synapse.handlers.account_data import ON_ACCOUNT_DATA_UPDATED_CALLBACK from synapse.handlers.account_validity import ( @@ -319,6 +320,7 @@ def register_third_party_rules_callbacks( ON_USER_DEACTIVATION_STATUS_CHANGED_CALLBACK ] = None, on_threepid_bind: Optional[ON_THREEPID_BIND_CALLBACK] = None, + unbind_threepid: Optional[UNBIND_THREEPID_CALLBACK] = None, ) -> None: """Registers callbacks for third party event rules capabilities. @@ -335,6 +337,7 @@ def register_third_party_rules_callbacks( on_profile_update=on_profile_update, on_user_deactivation_status_changed=on_user_deactivation_status_changed, on_threepid_bind=on_threepid_bind, + unbind_threepid=unbind_threepid, ) def register_presence_router_callbacks( diff --git a/tests/rest/client/test_third_party_rules.py b/tests/rest/client/test_third_party_rules.py index 3325d43a2fa4..f6e9b4ea20b8 100644 --- a/tests/rest/client/test_third_party_rules.py +++ b/tests/rest/client/test_third_party_rules.py @@ -15,6 +15,7 @@ from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Union from unittest.mock import Mock +from twisted.internet import defer from twisted.test.proto_helpers import MemoryReactor from synapse.api.constants import EventTypes, LoginType, Membership @@ -931,3 +932,62 @@ def test_on_threepid_bind(self) -> None: # Check that the mock was called with the right parameters self.assertEqual(args, (user_id, "email", "foo@example.com")) + + def test_unbind_threepid(self) -> None: + """Tests that the unbind_threepid module callback is called correctly before + removing a 3PID mapping. + """ + + # Register an admin user. + self.register_user("admin", "password", admin=True) + admin_tok = self.login("admin", "password") + + # Also register a normal user we can modify. + user_id = self.register_user("user", "password") + + # Add a 3PID to the user. + channel = self.make_request( + "PUT", + "/_synapse/admin/v2/users/%s" % user_id, + { + "threepids": [ + { + "medium": "email", + "address": "foo@example.com", + }, + ], + }, + access_token=admin_tok, + ) + self.assertEqual(channel.code, 200, channel.json_body) + + # Add the mapping to the remote 3pid assoc table + defer.ensureDeferred( + self.hs.get_module_api().store_remote_3pid_association( + user_id, "email", "foo@example.com", "identityserver.org" + ) + ) + + # Register a mocked callback with stop = True since we don't want to actually + # call identityserver.org + threepid_unbind_mock = Mock(return_value=make_awaitable((True, True))) + third_party_rules = self.hs.get_third_party_event_rules() + third_party_rules._unbind_threepid_callbacks.append(threepid_unbind_mock) + + # Deactivate the account, this should remove the 3pid mapping + # and call the module handler. + channel = self.make_request( + "POST", + "/_synapse/admin/v1/deactivate/%s" % user_id, + access_token=admin_tok, + ) + self.assertEqual(channel.code, 200, channel.json_body) + + # Check that the mock was called once. + threepid_unbind_mock.assert_called_once() + args = threepid_unbind_mock.call_args[0] + + # Check that the mock was called with the right parameters + self.assertEqual( + args, (user_id, "email", "foo@example.com", "identityserver.org") + )