phederation-client 0.1.1__tar.gz

phederation_client-0.1.1/CONTRIBUTING

@@ -0,0 +1,4 @@
+# Ordered alphabetically by account name. Corresponding developers are marked with *
+
+Username; Years of contribution; Contact person
+https://codeberg.org/feldie; 2026-; *

phederation_client-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 https://codeberg.org/feldie (see also CONTRIBUTING file)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phederation_client-0.1.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: phederation-client
+Version: 0.1.1
+Summary: Phederation implementation of an ActivityPub client. Can be used to connect to an ActivityPub server in the fediverse. This is the core library for the Phederation server software.
+Author: Felix Dietrich
+License-Expression: MIT
+Project-URL: Homepage, https://codeberg.org/feldie/phederation-client
+Project-URL: Issues, https://codeberg.org/feldie/phederation-client/-/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+License-File: CONTRIBUTING
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: build>=1.4.0
+Requires-Dist: coverage>=7.10.7
+Requires-Dist: fastapi[standard]==0.136.3
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings[yaml]>=2.10.1
+Requires-Dist: pydeps>=3.0.1
+Requires-Dist: pytest>=9.0.1
+Requires-Dist: pytest-asyncio>=1.1.0
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: python-json-logger>=4.0.0
+Requires-Dist: python-keycloak>=5.8.1
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: toml>=0.10.2
+Requires-Dist: twine>=6.2.0
+Requires-Dist: types-urllib3>=1.26.25.14
+Requires-Dist: urllib3<2,>=1.21.1
+Dynamic: license-file
+
+A python implementation of an ActivityPub client.
+
+This is the core library for the phederation software (https://codeberg.org/feldie/phederation), which implements an entire ActivityPub server architecture. The client library implements the models and utility methods for ActivityPub, and the ActivityPubClient class that can be used to interact with the server software.
+
+Requirements
+============
+ - Linux environment (tested on Mint/Ubuntu)
+ - Python (3.12+)
+
+Installation
+============
+
+If you want to build ActivityPub clients, you can use the software as a library.
+
+1) Clone the repository
+
+.. code-block:: sh
+
+   git clone https://codeberg.org/feldie/phederation-client.git phederation-client
+
+
+2) Navigate to the root folder of the "phederation-client" repository, then set up a python environment with uv, e.g.:
+
+.. code-block:: sh
+
+   cd phederation-client
+   uv sync
+

phederation_client-0.1.1/README.rst

@@ -0,0 +1,28 @@
+A python implementation of an ActivityPub client.
+
+This is the core library for the phederation software (https://codeberg.org/feldie/phederation), which implements an entire ActivityPub server architecture. The client library implements the models and utility methods for ActivityPub, and the ActivityPubClient class that can be used to interact with the server software.
+
+Requirements
+============
+ - Linux environment (tested on Mint/Ubuntu)
+ - Python (3.12+)
+
+Installation
+============
+
+If you want to build ActivityPub clients, you can use the software as a library.
+
+1) Clone the repository
+
+.. code-block:: sh
+
+   git clone https://codeberg.org/feldie/phederation-client.git phederation-client
+
+
+2) Navigate to the root folder of the "phederation-client" repository, then set up a python environment with uv, e.g.:
+
+.. code-block:: sh
+
+   cd phederation-client
+   uv sync
+

phederation_client-0.1.1/phederation/client/__init__.py

@@ -0,0 +1,4 @@
+from .client import ActivityPubClient
+from .resolver import Resolver
+
+__all__ = ["ActivityPubClient", "Resolver"]

phederation_client-0.1.1/phederation/client/client.py

@@ -0,0 +1,437 @@
+"""
+client.py
+Implements a client to interact with phederation instances.
+This is a quality-of-life service to demonstrate and ease new client implementations.
+It is also heavily used in testing all functionality of the main phederation (server) software.
+"""
+
+import asyncio
+import json
+from http import HTTPStatus
+from logging import Logger
+from typing import Any, BinaryIO, cast
+from urllib.parse import urlparse
+
+import httpx
+from fastapi import HTTPException, UploadFile
+from keycloak import KeycloakAuthenticationError, KeycloakOpenID, KeycloakPostError
+from pydantic import BaseModel, Field
+from pydantic.types import SecretStr
+
+from phederation.models import (
+    ActivityPubBaseWithId,
+    ActivityPubException,
+    APCreate,
+    APMigrate,
+    ApplicationRegistrationRequest,
+    CredentialApplication,
+    DeliveryError,
+    DeliveryResult,
+    NodeInfo,
+    ObjectId,
+    ResolverError,
+    ResolverResult,
+    UrlType,
+    UserError,
+    ValidCollection,
+    actor_id_from_username,
+    dereference,
+    object_from_type,
+)
+from phederation.models.activities import APActivity
+from phederation.models.actors import APActor
+from phederation.models.exceptions import DecodingError
+from phederation.models.objects import APDocument, APObject
+from phederation.models.proofs import to_sha256
+from phederation.models.settings import KeycloakSettings, PhedSettings
+from phederation.utils import urljoin
+from phederation.utils.logging import configure_logger
+from phederation.utils.serialization import to_json_string
+from phederation.utils.version import PHEDERATION_HEADERS
+
+from .resolver import Resolver
+
+
+class ActivityPubClient(BaseModel):
+    """
+    ActivityPubClient that can be used in client2server applications to easily setup and communicate with a phederation server using the activitypub protocol.
+
+    Applications can use the deliver and resolver methods and properties of an ActivityPubClient instance to deliver activities and to resolve information about instances and actors in the federation. The 'host_url' must be set to the server url, and the 'actor_id' must be set to the actor that is operating the client. This actor must be registered on the server.
+
+    Authentication is done through KeycloakSettings (stored in an .env file).
+    """
+
+    settings: PhedSettings = Field(default=..., description="The settings for the client-side phederation setup.")
+    instance_actor_id: ObjectId | None = Field(
+        default=None,
+        description="The id of the instance actor for the host instance. Must be a resolvable URL (as defined by ActivityPub), or None if it should be discovered from the host settings.",
+    )
+    keycloak_settings: KeycloakSettings | None = Field(description="Settings to reach the keycloak instance for user authentication (OAuth2).")
+    username: str | None = Field(default=None, description="Username of the actor to use for login")
+    password: SecretStr | None = Field(default=None, description="Password of the actor to use for login")
+    access_token: SecretStr | None = Field(default=None, description="Current access_token of the actor to use for authentication")
+    _initialized: bool = False
+
+    def initialize(self):
+        if not self._initialized:
+            self._resolver: Resolver = Resolver(settings=self.settings)
+            self._requests: httpx.AsyncClient = httpx.AsyncClient()
+            self._logger: Logger = configure_logger(__name__, prefix=self.settings.federation.logging_prefix + "_client")
+            if self.keycloak_settings is None:
+                self._logger.warning("Client does not have keycloak settings set. Will not be able to authenticate")
+                self._keycloak_openid = None
+            else:
+                keycloak_hostname = (
+                    self.keycloak_settings.keycloak_docker_hostname
+                    if self.keycloak_settings.keycloak_docker_hostname
+                    else self.keycloak_settings.keycloak_hostname
+                )
+                self._keycloak_openid: KeycloakOpenID | None = KeycloakOpenID(
+                    server_url=keycloak_hostname,
+                    realm_name=self.keycloak_settings.keycloak_realm,
+                    client_id=self.keycloak_settings.keycloak_client_id,
+                    client_secret_key=self.keycloak_settings.keycloak_client_secret.get_secret_value(),
+                    verify=True,
+                )
+        self._initialized = True
+
+    async def resolve_multiple(self, urls: list[ObjectId], resolve_endpoint: ObjectId | None):
+        """Tries to resolve multiple objects given by their id.
+        This will use the /resolve endpoint of the instance.
+        The objects in the list can be of different types.
+        The object ids must be for the instance connected to this client (because this is using the instance resolve endpoint)
+
+        Args:
+            urls (list[ObjectId]): Ids of objects to resolve.
+            resolve_endpoint: The endpoint on the instance where multiple objects can be resolved. Default None (uses '/resolve').
+
+        Returns:
+        list[APObject | DataIntegrityProof | NodeInfo]: list of resolved objects. If an object id cannot be resolved, it is not included. The list is not necessarily in the same order as the given urls, but the objects have their '.id' property set, so can be identified again.
+        """
+        # TODO: allow to resolve from multiple instance endpoints
+        # get resolve endpoint from instance
+        if not self._initialized:
+            raise ResolverError("Must initialize the client first")
+        if resolve_endpoint:
+            try:
+                headers = await self._headers(with_token=True)
+                urls_encoded = to_json_string(urls)
+                response = await self._requests.post(resolve_endpoint, headers=headers, content=urls_encoded)
+                result_bytes = await response.aread()
+                result_json = cast(list[dict[str, Any]], json.loads(result_bytes.decode(encoding="utf-8")))
+                result_objects = [object_from_type(obj_dict) for obj_dict in result_json]
+                result_objects_with_id = [obj for obj in result_objects if isinstance(obj, ActivityPubBaseWithId)]
+                return result_objects_with_id
+            except Exception as e:
+                raise ResolverError(f"Could not resolve from /resolve endpoint; error: {e}")
+        raise ResolverError(f"The instance does not have a /resolve endpoint")
+
+    @property
+    def actor_id(self):
+        """The id of the actor who is using this client.
+        A resolvable URL (as defined by ActivityPub), or None if no specific actor is using it."""
+        if self.username:
+            return actor_id_from_username(self.settings.domain.hostname, username=self.username)
+        else:
+            raise ValueError("Actor_id not available in ActivityPubClient: field 'username' is not set")
+
+    def authenticate_user(self, username: str, password: SecretStr, redirect_uri: str | None = None) -> SecretStr:
+        """
+        Authenticate the user using Keycloak and return an access token.
+        """
+        try:
+            if not self._keycloak_openid:
+                raise KeycloakAuthenticationError("Keycloak connection not initialized")
+            if not redirect_uri:
+                redirect_uri = self.settings.domain.hostname
+            token: dict[str, Any] | None = self._keycloak_openid.token(  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+                username, password.get_secret_value(), redirect_uri=redirect_uri
+            )
+            if not token:
+                raise KeycloakAuthenticationError("Unauthorized, token not available")
+            access_token = token.get("access_token", None)
+            if not isinstance(access_token, str):
+                raise KeycloakAuthenticationError("Unauthorized, access_token not available")
+            return SecretStr(access_token)
+        except KeycloakAuthenticationError as e:
+            self._logger.warning(f"Keycloak: login unsuccessful; KeycloakAuthenticationError error: {e}.")
+            raise HTTPException(
+                status_code=HTTPStatus.UNAUTHORIZED,
+                detail="Unauthorized",
+            )
+        except KeycloakPostError as e:
+            self._logger.warning(f"Keycloak: login unsuccessful; KeycloakPostError error: {e}.")
+            raise HTTPException(
+                status_code=HTTPStatus.BAD_REQUEST,
+                detail="POST/Client error",
+            )
+
+    def get_token(self) -> SecretStr | None:
+        if self.access_token:
+            return self.access_token
+        if not self._keycloak_openid or not self.username or not self.password:
+            token = None
+        else:
+            token = self.authenticate_user(username=self.username, password=self.password)
+            self.access_token = token
+        return token
+
+    async def deliver_to_url(
+        self, activity: APActivity, url: ObjectId, retry_count: int = 0, data: UploadFile | None = None, token: SecretStr | None = None
+    ) -> DeliveryResult:
+        """Deliver activity to a given url (e.g. inbox or outbox of actor).
+
+        Args:
+            activity (APActivity): to deliver.
+            url (str): url where the activity is to be delivered to.
+            retry_count (int, optional): how often the delivery has been tried already. Defaults to 0.
+            data (UploadFile, optional): data of a file to upload. Only used in c2s communication (i.e. by client apps).
+            token (str, optional): if this is set, the delivery will not use header signing and instead pass the Authorization: Bearer token.
+
+        Returns:
+            DeliveryResult: Result of delivery after retries.
+        """
+        parsed_url = urlparse(str(url))
+        domain = parsed_url.netloc
+        result = DeliveryResult()
+
+        try:
+            # Prepare headers with host
+            headers = PHEDERATION_HEADERS.copy()
+            headers["Host"] = domain
+
+            # Get key id of the actor sending this
+            actor_id = dereference(activity, key="actor")
+            if actor_id is None:
+                raise DeliveryError(f"No actor in activity found: {activity}")
+
+            # Add a content hash of the content of the activity.object
+            await activity.add_hash()
+
+            # Use standardized JSON serialization
+            activity_dict = activity.serialize()
+            body_json = to_json_string(activity_dict)
+
+            if data:
+                files: dict[str, tuple[None | str, str | BinaryIO, str]] = {
+                    "activity_form": (None, body_json, "application/json"),
+                    "file": (data.filename, data.file, data.content_type or "text/plain"),
+                }
+                _ = headers.pop("Content-Type")  # is going to be set by the AsyncClient to multipart
+            else:
+                files = {}
+
+            if token:
+                headers["Authorization"] = f"Bearer {token.get_secret_value()}"
+                headers["WWW-Authenticate"] = "Bearer"
+
+            # Make request with pre-serialized JSON or Files
+            async def post_files(url: str, client: httpx.AsyncClient):
+                return await client.post(url, files=files, headers=headers, timeout=self.settings.federation.delivery_timeout)
+
+            async def post_json(url: str, client: httpx.AsyncClient):
+                return await client.post(url, content=body_json, headers=headers, timeout=self.settings.federation.delivery_timeout)
+
+            post_action = post_files if data else post_json
+
+            try:
+                response = await post_action(url=url, client=self._requests)
+            except (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadTimeout) as e:
+                self._logger.debug(f"Error when connecting to url {url}: {type(e).__name__} {e}")
+                result.error_message = "Error when connecting to url."
+                result.status_code = HTTPStatus.CONTINUE
+                result.failed.append(url)
+                return result
+
+            response_headers: dict[str, str] = {h.lower(): response.headers[h] for h in response.headers.keys()}
+
+            if response.status_code in (HTTPStatus.OK, HTTPStatus.CREATED, HTTPStatus.ACCEPTED):
+                try:
+                    response_content: dict[str, Any] = cast(dict[str, Any], json.loads(response.content.decode("utf8")))
+                except json.JSONDecodeError as e:
+                    raise DecodingError(message=f"JSONDecodeError for response_content '{response.content}'.")
+
+                if "location" in response_headers:
+                    response_content["Location"] = response_headers["location"]
+                result.success.append(response_content)
+                result.status_code = response.status_code
+                return result
+
+            if (
+                response.status_code in (HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.GATEWAY_TIMEOUT)
+                and retry_count < self.settings.federation.max_retries
+            ):
+                # Calculate retry delay
+                retry_after = int(response_headers.get("retry-after", self.settings.federation.retry_delay))
+                self._logger.warning(
+                    f"Retry delivery of activity with id={activity.id} after waiting {retry_after} seconds. Retry_count: {retry_count + 1} / {self.settings.federation.max_retries}..."
+                )
+                await asyncio.sleep(retry_after)
+
+                # Retry delivery
+                return await self.deliver_to_url(activity=activity, url=url, retry_count=retry_count + 1)
+
+            self._logger.warning(
+                f"Delivery Error for activity type {activity.type}: url={url}, content={response.content}, headers={response_headers}"
+            )
+            result.failed.append(url)
+            result.status_code = response.status_code
+            result.error_message = str(response.content) if len(response.content) > 0 else "No response text received"
+
+        except json.JSONDecodeError as e:
+            self._logger.error(f"Delivery JSONDecodeError for url '{url}': {e}")
+            result.failed.append(url)
+            result.status_code = HTTPStatus.BAD_REQUEST
+            result.error_message = f"Delivery exception: cannot decode."
+        except ActivityPubException as e:
+            self._logger.error(f"Delivery ActivityPubException for url '{url}': {e.message}")
+            result.failed.append(url)
+            result.status_code = e.status_code
+            result.error_message = f"Delivery APException: {e.user_message or 'unknown'}"
+        except Exception as e:
+            self._logger.error(f"Delivery Exception for url '{url}': {type(e).__name__}, {str(e)}")
+            result.failed.append(url)
+            result.status_code = HTTPStatus.INTERNAL_SERVER_ERROR
+            result.error_message = f"Delivery exception: {type(e).__name__}, {str(e)}"
+
+        return result
+
+    async def deliver_file(self, file: BinaryIO, file_hash: str | None, media_type: str = "application/json", file_description: str = "A json file"):
+        file_to_send = UploadFile(filename=file.name, file=file)
+
+        create_activity = APCreate(actor=self.actor_id, object=APDocument(content=file_description, hash=file_hash, media_type=media_type))
+
+        token = self.get_token()
+        actor = await self.resolver.resolve(APActor, self.actor_id)
+        media_endpoint = actor.endpoints.upload_media if actor.endpoints else None
+        if not media_endpoint:
+            raise UserError("Actor does not have a media endpoint to send files to")
+        response = await self.deliver_to_url(url=media_endpoint, activity=create_activity, data=file_to_send, token=token)
+        return response
+
+    async def deliver_activity(self, activity: APActivity):
+        """Deliver activity to an actor's outbox.
+        This is the main method for client2server communication. Instead of signing the header (which would require access to the private key),
+        the client must send a token for authentication.
+
+        Args:
+            activity (APActivity): Activity to deliver.
+            actor_id (ObjectId): id of actor that is performing the activity.
+            token (str | None, optional): Authentication token, if available and necessary. Defaults to None.
+
+        Returns:
+            DeliveryResult: Result of the delivery to the outbox. Can contain the id of the created activity, if successful; or a failed result if an exception was raised.
+        """
+        token = self.get_token()
+
+        url = None
+        try:
+            # always hash the content
+            await activity.add_hash()
+
+            actor = await self.resolver.resolve(APActor, self.actor_id)
+            url = actor.outbox
+            return await self.deliver_to_url(activity=activity, url=actor.outbox, token=token)
+        except ActivityPubException as e:
+            self._logger.error(f"Failed to deliver to actor {self.actor_id} outbox at url {url}: '{e.message}'. Failing silently.")
+            return DeliveryResult(failed=[self.actor_id], error_message=e.user_message)
+        except Exception as e:
+            self._logger.error(f"Failed to deliver to actor {self.actor_id} outbox at url {url}: '{str(e)}'. Failing silently.")
+            return DeliveryResult(failed=[self.actor_id], error_message=str(e))
+
+    async def deliver_maintenance(self, activity: APActivity):
+        token = self.get_token()
+        obj = activity.object
+        if self.settings.media.create_file_hash and isinstance(obj, APObject):
+            obj.hash = to_sha256(obj.content or "")
+
+        maintenance_route = urljoin(self.settings.domain.admin_url, UrlType.Maintenance.value)
+        result = await self.deliver_to_url(activity, url=maintenance_route, token=token)
+        return result
+
+    async def resolve_nodeinfo(self) -> NodeInfo | None:
+        base_url = self.settings.domain.hostname
+        response = await self._requests.get(urljoin(base_url, "/.well-known/instanceinfo"))
+        nodeinfo = NodeInfo.deserialize(cast(dict[str, str], response.json()))
+        return nodeinfo
+
+    async def register_client(self, request: ApplicationRegistrationRequest) -> CredentialApplication:
+        url = urljoin(self.settings.domain.hostname, UrlType.Applications.value)
+        headers = await self._headers(with_token=False)
+        body_serialized = to_json_string(request.model_dump())
+        self._logger.info(f"Application registration request for client '{request.client_name}' at instance url {url}")
+        result = await self._requests.post(url=url, content=body_serialized, headers=headers)
+        result = result.raise_for_status()
+        application_dict = cast(dict[str, str], result.json())
+        application = CredentialApplication.model_validate(application_dict)
+        return application
+
+    async def create_account(
+        self,
+    ):
+        if not self.actor_id or not self.username:
+            raise DeliveryError("Could not create account, actor_id or username is not set")
+        actor_id = actor_id_from_username(self.settings.domain.hostname, username=self.username)
+        inbox_url = urljoin(actor_id, ValidCollection.Inbox.value)
+        outbox_url = urljoin(actor_id, ValidCollection.Outbox.value)
+        activity = APCreate(actor=self.actor_id, object=APActor(preferred_username=self.username, inbox=inbox_url, outbox=outbox_url))
+        url = urljoin(self.settings.domain.hostname, ValidCollection.Users.value)
+        headers = await self._headers(with_token=True)
+        body_serialized = to_json_string(activity.serialize())
+        self._logger.info(f"Sending user acount registration for user {self.username} to instance url {url}")
+        result = await self._requests.put(url=url, content=body_serialized, headers=headers)
+        return result
+
+    async def _headers(self, with_token: bool = True):
+        headers = PHEDERATION_HEADERS
+        headers["Host"] = self.settings.domain.hostname
+        if with_token:
+            token = self.get_token()
+            if token:
+                headers["Authorization"] = f"Bearer {token.get_secret_value()}"
+                headers["WWW-Authenticate"] = "Bearer"
+        return headers
+
+    @property
+    def resolver(self):
+        self.initialize()
+        return self._resolver
+
+    async def download_user_data(self):
+        if not self.username:
+            raise ResolverError("Username is not set in the client, cannot download user data")
+        # send the "assemble user data" command
+        create_userdata = APMigrate(actor=self.actor_id)
+        result = await self.deliver_activity(activity=create_userdata)
+        activity_id = result.get_success_id_or_raise()
+
+        # retrieve the activity to get the file url
+        token = self.get_token()
+        activity = await self.resolver.resolve(APActivity, activity_id, access_token=token)
+        file_descriptor_document = await self.resolver.resolve(APObject, activity.object)
+        file_urls = file_descriptor_document.url
+
+        if not file_urls:
+            response = ResolverResult(
+                content=file_descriptor_document.id, status_code=None, error_message="Url is not contained in the user data document"
+            )
+            raise ResolverError("Could not resolve any user data file urls", response=response)
+
+        # get the actor media endpoint and download the data
+        files: list[bytes] = []
+        for file_url in file_urls:
+            resolved_file = b"".join([line async for line in await self.resolver.resolve_media(file_id=file_url, access_token=token)])
+            files.append(resolved_file)
+        return files
+
+    async def user_migration_initialize(self, client_for_new_instance: "ActivityPubClient"):
+        activity = APMigrate(actor=self.actor_id, actor_to=client_for_new_instance.actor_id, object=None)
+        result = await self.deliver_activity(activity)
+        return result
+
+    async def user_migration_status(self, migration_activity_id: ObjectId):
+        token = self.get_token()
+        activity = await self.resolver.resolve(APActivity, migration_activity_id, access_token=token)
+        if activity.object:
+            obj = await self.resolver.resolve(APObject, activity.object, access_token=token)
+            return cast(APDocument, obj)