Add configuration for Matrix appservice registration file

Includes a function to print it out in YAML.

Currently requires Django configured.

docs/protocols.rst

@@ -105,3 +105,25 @@ the complex protocol related details. This library will then aim to abstract muc
 appservice gives or takes behind the same API as is provided for the other protocols.
 
 Currently support is being added, please visit back in future versions.
+
+NOTE! Current features also assume Django is configured, though this is likely to not be
+the case in the future.
+
+Appservice
+..........
+
+To generate the appservice registration file you must ensure you've added the relevant
+configuration (see :ref:`usage-configuration`), at minimum providing the following:
+
+* ``base_url``
+* ``matrix_config_function``
+
+Then launch a Django shell inside your project and run the following:
+
+::
+
+    from federation.protocols.matrix.appservice import print_registration_yaml
+    print_registration_yaml()
+
+This YAML needs to be registered with the linked Matrix homeserver as instructed in the
+relevant homeserver documentation.

docs/usage.rst

@@ -195,6 +195,8 @@ It must be installed separately.
 .. autofunction:: federation.hostmeta.django.generators.matrix_server_wellknown_view
 .. autofunction:: federation.hostmeta.django.generators.nodeinfo2_view
 
+.. _usage-configuration:
+
 Configuration
 .............
 
@@ -233,6 +235,15 @@ Some settings need to be set in Django settings. An example is below:
       "homeserver_base_url": "https://matrix.domain.tld",
       # Homeserver domain and port (not server domain)
       "homeserver_domain_with_port": "matrix.domain.tld:443",
+      # Appservice details
+      "appservice": {
+        # Unique ID to register with at the homeserver. Don't change this after creating.
+        "id": "uniqueid",
+        # Appservice user localpart (lowercase, should ideally start with _)
+        "sender_localpart": "_myawesomeapp",
+        # Secret token for communication
+        "token": "secret_token",
+      },
       # (Optional) location of identity server
       "identity_server_base_url": "https://id.domain.tld",
       # (Optional) other keys to include in the client well-known (must be a dictionary)

federation/protocols/matrix/appservice.py

@@ -0,0 +1,52 @@
+from typing import Dict
+
+import yaml
+
+from federation.utils.django import get_configuration
+from federation.utils.matrix import get_matrix_configuration
+
+
+def get_registration_config() -> Dict:
+    """
+    Get registration config.
+
+    Requires Django support currently.
+    """
+    config = get_configuration()
+    matrix_config = get_matrix_configuration()
+
+    if not matrix_config.get("appservice"):
+        raise Exception("No appservice configured")
+
+    return {
+        "id": matrix_config["appservice"]["id"],
+        "url": f"{config['base_url']}/matrix/appservice",
+        "as_token": matrix_config["appservice"]["token"],
+        "hs_token": matrix_config["appservice"]["token"],
+        "sender_localpart": matrix_config["appservice"]["sender_localpart"],
+        "namespaces": {
+            "users": [
+                {
+                    "exclusive": False,
+                    "regex": "@.*",
+                },
+            ],
+            "aliases": [
+                {
+                    "exclusive": False,
+                    "regex": "#.*",
+                }
+            ],
+            "rooms": [],
+        }
+    }
+
+
+def print_registration_yaml():
+    """
+    Print registration file details.
+
+    Requires Django support currently.
+    """
+    registration = get_registration_config()
+    print(yaml.safe_dump(registration))

federation/tests/django/settings.py

@@ -7,6 +7,7 @@ FEDERATION = {
     "get_object_function": "federation.tests.django.utils.get_object_function",
     "get_private_key_function": "federation.tests.django.utils.get_private_key",
     "get_profile_function": "federation.tests.django.utils.get_profile",
+    "matrix_config_function": "federation.tests.django.utils.matrix_config_func",
     "process_payload_function": "federation.tests.django.utils.process_payload",
     "search_path": "/search?q=",
     "tags_path": "/tag/:tag:/",

federation/tests/django/utils.py

@@ -1,3 +1,6 @@
+from typing import Dict
+
+# noinspection PyPackageRequirements
 from Crypto.PublicKey.RSA import RsaKey
 
 from federation.entities.base import Profile
@@ -27,5 +30,22 @@ def get_profile(fid=None, handle=None, guid=None, request=None):
     return dummy_profile()
 
 
+def matrix_config_func() -> Dict:
+    return {
+        "homeserver_base_url": "https://matrix.domain.tld",
+        "homeserver_domain_with_port": "matrix.domain.tld:443",
+        "appservice": {
+            "id": "uniqueid",
+            "sender_localpart": "_myawesomeapp",
+            "token": "secret_token",
+        },
+        "identity_server_base_url": "https://id.domain.tld",
+        "client_wellknown_other_keys": {
+            "org.foo.key" "barfoo",
+        },
+        "registration_shared_secret": "supersecretstring",
+    }
+
+
 def process_payload(request):
     return True

federation/tests/protocols/matrix/test_appservice.py

@@ -0,0 +1,34 @@
+from federation.protocols.matrix.appservice import get_registration_config, print_registration_yaml
+
+
+def test_get_registration():
+    config = get_registration_config()
+    assert config == {
+        "id": "uniqueid",
+        "url": "https://example.com/matrix/appservice",
+        "as_token": "secret_token",
+        "hs_token": "secret_token",
+        "sender_localpart": "_myawesomeapp",
+        "namespaces": {
+            "users": [
+                {
+                    "exclusive": False,
+                    "regex": "@.*",
+                },
+            ],
+            "aliases": [
+                {
+                    "exclusive": False,
+                    "regex": "#.*",
+                }
+            ],
+            "rooms": [],
+        }
+    }
+
+
+def test_print_registration_yaml():
+    """
+    Just execute and ensure doesn't crash.
+    """
+    print_registration_yaml()

federation/utils/matrix.py

@@ -1,7 +1,7 @@
 import hashlib
 import hmac
 import uuid
-from typing import Dict
+from typing import Dict, Optional
 
 import requests
 
@@ -26,6 +26,19 @@ def generate_dendrite_mac(shared_secret: str, username: str, password: str, admi
     return mac.hexdigest()
 
 
+def get_matrix_configuration() -> Optional[Dict]:
+    """
+    Return Matrix configuration.
+
+    Requires Django support currently.
+    """
+    try:
+        matrix_config_func = get_function_from_config("matrix_config_function")
+    except AttributeError:
+        raise AttributeError("Not configured for Matrix support")
+    return matrix_config_func()
+
+
 def register_dendrite_user(username: str) -> Dict:
     """
     Shared secret registration for Dendrite.
@@ -43,11 +56,7 @@ def register_dendrite_user(username: str) -> Dict:
             'device_id': 'randomdevice'
         }
     """
-    try:
-        matrix_config_func = get_function_from_config("matrix_config_function")
-    except AttributeError:
-        raise AttributeError("Not configured for Matrix support")
-    matrix_config = matrix_config_func()
+    matrix_config = get_matrix_configuration
 
     password = str(uuid.uuid4())
     mac = generate_dendrite_mac(

setup.py

@@ -40,6 +40,7 @@ setup(
         "python-dateutil>=2.4.0",
         "python-xrd>=0.1",
         "pytz",
+        "PyYAML",
         "requests>=2.8.0",
         "requests-http-signature-jaywink>=0.1.0.dev0",
     ],
@@ -59,5 +60,5 @@ setup(
         'Topic :: Internet',
         'Topic :: Software Development :: Libraries :: Python Modules',
     ],
-    keywords='federation diaspora activitypub federate fediverse social',
+    keywords='federation diaspora activitypub matrix protocols federate fediverse social',
 )