Dedicated MAS API (#18520)

This introduces a dedicated API for MAS to consume. Companion PR on the
MAS side: element-hq/matrix-authentication-service#4801

This has a few advantages over the previous admin API:

- it works on workers (this will be documented once we stabilise MSC3861
as a whole)
 - it is more efficient because more focused
 - it propagates trace contexts from MAS
- it is only accessible to MAS (through the shared secret) and will let
us remove the weird hack that made this token 'admin' with a ghost
'@__oidc_admin:' user

The next MAS version should support it, but will be opt-in. The version
after that should use this new API by default

---------

Co-authored-by: Eric Eastwood <erice@element.io>

Author: sandhose

changelog.d/18520.misc

@@ -0,0 +1 @@
+Dedicated internal API for Matrix Authentication Service to Synapse communication.

synapse/_pydantic_compat.py

@@ -48,6 +48,7 @@
         conint,
         constr,
         parse_obj_as,
+        root_validator,
         validator,
     )
     from pydantic.v1.error_wrappers import ErrorWrapper
@@ -68,6 +69,7 @@
         conint,
         constr,
         parse_obj_as,
+        root_validator,
         validator,
     )
     from pydantic.error_wrappers import ErrorWrapper
@@ -92,4 +94,5 @@
     "StrictStr",
     "ValidationError",
     "validator",
+    "root_validator",
 )

synapse/api/auth/msc3861_delegated.py

@@ -369,6 +369,12 @@ async def _introspect_token(
     async def is_server_admin(self, requester: Requester) -> bool:
         return "urn:synapse:admin:*" in requester.scope
 
+    def _is_access_token_the_admin_token(self, token: str) -> bool:
+        admin_token = self._admin_token()
+        if admin_token is None:
+            return False
+        return token == admin_token
+
     async def get_user_by_req(
         self,
         request: SynapseRequest,
@@ -434,7 +440,7 @@ async def _wrapped_get_user_by_req(
             requester = await self.get_user_by_access_token(access_token, allow_expired)
 
         # Do not record requests from MAS using the virtual `__oidc_admin` user.
-        if access_token != self._admin_token():
+        if not self._is_access_token_the_admin_token(access_token):
             await self._record_request(request, requester)
 
         if not allow_guest and requester.is_guest:
@@ -470,13 +476,25 @@ async def get_user_by_req_experimental_feature(
 
             raise UnrecognizedRequestError(code=404)
 
+    def is_request_using_the_admin_token(self, request: SynapseRequest) -> bool:
+        """
+        Check if the request is using the admin token.
+
+        Args:
+            request: The request to check.
+
+        Returns:
+            True if the request is using the admin token, False otherwise.
+        """
+        access_token = self.get_access_token_from_request(request)
+        return self._is_access_token_the_admin_token(access_token)
+
     async def get_user_by_access_token(
         self,
         token: str,
         allow_expired: bool = False,
     ) -> Requester:
-        admin_token = self._admin_token()
-        if admin_token is not None and token == admin_token:
+        if self._is_access_token_the_admin_token(token):
             # XXX: This is a temporary solution so that the admin API can be called by
             # the OIDC provider. This will be removed once we have OIDC client
             # credentials grant support in matrix-authentication-service.

synapse/rest/synapse/client/__init__.py

@@ -30,6 +30,7 @@
 from synapse.rest.synapse.client.rendezvous import MSC4108RendezvousSessionResource
 from synapse.rest.synapse.client.sso_register import SsoRegisterResource
 from synapse.rest.synapse.client.unsubscribe import UnsubscribeResource
+from synapse.rest.synapse.mas import MasResource
 
 if TYPE_CHECKING:
     from synapse.server import HomeServer
@@ -60,6 +61,7 @@ def build_synapse_client_resource_tree(hs: "HomeServer") -> Mapping[str, Resourc
         from synapse.rest.synapse.client.jwks import JwksResource
 
         resources["/_synapse/jwks"] = JwksResource(hs)
+        resources["/_synapse/mas"] = MasResource(hs)
 
     # provider-specific SSO bits. Only load these if they are enabled, since they
     # rely on optional dependencies.

synapse/rest/synapse/mas/__init__.py

@@ -0,0 +1,71 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright (C) 2025 New Vector, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl_3.0.html>.
+#
+#
+
+
+import logging
+from typing import TYPE_CHECKING
+
+from twisted.web.resource import Resource
+
+from synapse.rest.synapse.mas.devices import (
+    MasDeleteDeviceResource,
+    MasSyncDevicesResource,
+    MasUpdateDeviceDisplayNameResource,
+    MasUpsertDeviceResource,
+)
+from synapse.rest.synapse.mas.users import (
+    MasAllowCrossSigningResetResource,
+    MasDeleteUserResource,
+    MasIsLocalpartAvailableResource,
+    MasProvisionUserResource,
+    MasQueryUserResource,
+    MasReactivateUserResource,
+    MasSetDisplayNameResource,
+    MasUnsetDisplayNameResource,
+)
+
+if TYPE_CHECKING:
+    from synapse.server import HomeServer
+
+
+logger = logging.getLogger(__name__)
+
+
+class MasResource(Resource):
+    """
+    Provides endpoints for MAS to manage user accounts and devices.
+
+    All endpoints are mounted under the path `/_synapse/mas/` and only work
+    using the MAS admin token.
+    """
+
+    def __init__(self, hs: "HomeServer"):
+        Resource.__init__(self)
+        self.putChild(b"query_user", MasQueryUserResource(hs))
+        self.putChild(b"provision_user", MasProvisionUserResource(hs))
+        self.putChild(b"is_localpart_available", MasIsLocalpartAvailableResource(hs))
+        self.putChild(b"delete_user", MasDeleteUserResource(hs))
+        self.putChild(b"upsert_device", MasUpsertDeviceResource(hs))
+        self.putChild(b"delete_device", MasDeleteDeviceResource(hs))
+        self.putChild(
+            b"update_device_display_name", MasUpdateDeviceDisplayNameResource(hs)
+        )
+        self.putChild(b"sync_devices", MasSyncDevicesResource(hs))
+        self.putChild(b"reactivate_user", MasReactivateUserResource(hs))
+        self.putChild(b"set_displayname", MasSetDisplayNameResource(hs))
+        self.putChild(b"unset_displayname", MasUnsetDisplayNameResource(hs))
+        self.putChild(
+            b"allow_cross_signing_reset", MasAllowCrossSigningResetResource(hs)
+        )

synapse/rest/synapse/mas/_base.py

@@ -0,0 +1,47 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright (C) 2025 New Vector, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl_3.0.html>.
+#
+#
+
+
+from typing import TYPE_CHECKING, cast
+
+from synapse.api.errors import SynapseError
+from synapse.http.server import DirectServeJsonResource
+
+if TYPE_CHECKING:
+    from synapse.app.generic_worker import GenericWorkerStore
+    from synapse.http.site import SynapseRequest
+    from synapse.server import HomeServer
+
+
+class MasBaseResource(DirectServeJsonResource):
+    def __init__(self, hs: "HomeServer"):
+        # Importing this module requires authlib, which is an optional
+        # dependency but required if msc3861 is enabled
+        from synapse.api.auth.msc3861_delegated import MSC3861DelegatedAuth
+
+        DirectServeJsonResource.__init__(self, extract_context=True)
+        auth = hs.get_auth()
+        assert isinstance(auth, MSC3861DelegatedAuth)
+        self.msc3861_auth = auth
+        self.store = cast("GenericWorkerStore", hs.get_datastores().main)
+        self.hostname = hs.hostname
+
+    def assert_request_is_from_mas(self, request: "SynapseRequest") -> None:
+        """Assert that the request is coming from MAS itself, not a regular user.
+
+        Throws a 403 if the request is not coming from MAS.
+        """
+        if not self.msc3861_auth.is_request_using_the_admin_token(request):
+            raise SynapseError(403, "This endpoint must only be called by MAS")