matrix-server-isenguard 0.1.1__tar.gz

matrix_server_isenguard-0.1.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: matrix-server-isenguard
+Version: 0.1.1
+Summary: Add your description here
+Requires-Python: >=3.13
+Requires-Dist: matrix-synapse>=1.148.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: fhirclient>=4.0.0

matrix_server_isenguard-0.1.1/README.md

@@ -0,0 +1,75 @@
+# Isenguard - FHIR plugins for Matrix Synapse
+
+## Development
+
+### Docker startup
+Start the 3 Matrix servers:
+``` bash
+uv run demo/start.sh
+```
+
+They are named:
+* `localhost:8080`
+* `localhost:8081`
+* `localhost:8082`
+
+At first time setup, it will generate https certificates the servers need to federate.
+
+You have to use exactly those names as homeserver when you register/login with your matrix client.  
+
+For federation, they are named:
+* `localhost:8480`
+* `localhost:8481`
+* `localhost:8482`
+
+If you want to invite a user from a different server, use the following syntax: `@some_user:localhost:8480`
+
+
+
+### Server lifecycle
+
+Start 3 federating demo servers:
+``` bash
+uv run demo/start.sh
+```
+ 
+Stop the servers:
+``` bash
+uv run demo/stop.sh
+```
+
+Delete all demo server data:
+``` bash
+uv run demo/clean.sh
+```
+
+
+### Development REST Services
+
+The repository includes a flask server that mimics a REST API for the federation whitelist.
+Start it by calling `flask --debug --app rest_services.app run`
+
+The server will be available at `http://localhost:5000` with the followind APIs:
+
+* `GET /federation/whitelist` : returns the current whitelist as JSON. It reads the whitelist from a file named
+                                `server_whitelist.json` in the project root, so you can edit it locally.
+
+
+## Testing
+
+Tests use the synapse test suite, so you must have synapse installed not from pypi, but from git:
+Clone the synapse repository and install it in editable mode one directory up, to avoid VCS conflicts (we didn't want 
+to create a git submodule):
+
+```bash
+git clone --depth=1 https://github.com/element-hq/synapse.git ../synapse
+uv pip install -e ../synapse
+```
+
+
+Then you can use the tst suite:
+
+
+```bash
+uv run pytest
+```

matrix_server_isenguard-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "matrix-server-isenguard"
+version = "0.1.1"
+description = "Add your description here"
+requires-python = ">=3.13"
+dependencies = [
+    "matrix-synapse>=1.148.0",
+    "aiohttp>=3.8.0",
+    "fhirclient>=4.0.0",
+]
+
+
+[dependency-groups]
+dev = [
+    "black",
+    "flask>=3.1.3",
+    "mkdocs>=1.6.1",
+    "mypy",
+    "pytest",
+    "pytest-asyncio>=1.3.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.uv]
+package = true

matrix_server_isenguard-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrix_server_isenguard-0.1.1/src/isenguard/__init__.py

@@ -0,0 +1,4 @@
+from .dynamic_federation_whitelist import DynamicFederationWhitelist
+from .user_search_fhir import UserSearchFHIR
+
+__all__ = ["DynamicFederationWhitelist", "UserSearchFHIR"]

matrix_server_isenguard-0.1.1/src/isenguard/auth.py

@@ -0,0 +1,83 @@
+"""Token providers for FHIR server authentication."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Optional, Protocol
+
+logger = logging.getLogger(__name__)
+
+
+class TokenProvider(Protocol):
+    """Returns the bearer token to send to the FHIR server."""
+
+    async def get_bearer_token(self) -> Optional[str]: ...
+    async def invalidate(self) -> None: ...
+
+
+class OAuthClientCredentialsProvider:
+    """Fetches and caches an id_token via OAuth2 client_credentials.
+
+    Concurrent refreshes are coalesced via an asyncio.Lock. The cached
+    token is refreshed once `now >= expires_at - safety_margin`.
+    """
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: str,
+        http_client,
+        safety_margin_seconds: int = 60,
+    ) -> None:
+        self._token_url = token_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope
+        self._http_client = http_client
+        self._safety_margin = safety_margin_seconds
+        self._token: Optional[str] = None
+        self._expires_at: float = 0.0
+        self._lock = asyncio.Lock()
+
+    async def get_bearer_token(self) -> Optional[str]:
+        if self._is_fresh():
+            return self._token
+        async with self._lock:
+            if self._is_fresh():
+                return self._token
+            await self._refresh()
+            return self._token
+
+    async def invalidate(self) -> None:
+        async with self._lock:
+            self._token = None
+            self._expires_at = 0.0
+
+    def _is_fresh(self) -> bool:
+        return bool(self._token) and time.monotonic() < self._expires_at - self._safety_margin
+
+    async def _refresh(self) -> None:
+        data = await self._http_client.post_urlencoded_get_json(
+            self._token_url,
+            args={
+                "grant_type": "client_credentials",
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+                "scope": self._scope,
+            },
+        )
+        if not isinstance(data, dict):
+            raise RuntimeError(
+                f"Unexpected token response type: {type(data).__name__}"
+            )
+        token = data.get("id_token")
+        if not token:
+            raise RuntimeError("OAuth token response missing 'id_token'")
+        expires_in = int(data.get("expires_in", 3600))
+        self._token = token
+        self._expires_at = time.monotonic() + expires_in
+        logger.info("Refreshed FHIR OAuth id_token (expires in %ss)", expires_in)

matrix_server_isenguard-0.1.1/src/isenguard/dynamic_federation_whitelist.py

@@ -0,0 +1,343 @@
+"""
+Dynamic Federation Whitelist Synapse Module
+
+This module controls federation by maintaining a whitelist of allowed servers
+that is periodically fetched from a remote REST API. Only servers on the
+whitelist are allowed to federate with this Synapse instance.
+"""
+
+import logging
+import re
+from typing import Any, Dict, List, Optional, Set
+from datetime import datetime
+from synapse.api.errors import HttpResponseException
+from synapse.module_api import ModuleApi
+from synapse.events import EventBase
+
+logger = logging.getLogger(__name__)
+
+
+# Conservative server-name grammar: lowercase letters, digits, dots, hyphens,
+# colons (for ports), brackets (for IPv6 literals).
+_SERVER_NAME_RE = re.compile(r"\A[a-z0-9.\-:\[\]]+\Z")
+
+
+def _is_valid_server_name(name: str) -> bool:
+    """Return True if `name` looks like a Matrix server name.
+
+    Defensive: rejects empty strings, whitespace, wildcards, control chars,
+    and anything else that wouldn't ever match a real sender domain.
+    """
+    if not name or len(name) > 255:
+        return False
+    return bool(_SERVER_NAME_RE.match(name))
+
+
+class DynamicFederationWhitelist:
+    """A Synapse module that maintains a dynamic whitelist of federation servers."""
+
+    def __init__(self, config: Dict[str, Any], api: ModuleApi):
+        """
+        Initialize the Dynamic Federation Whitelist module.
+
+        Args:
+            config: Module configuration from homeserver.yaml
+            api: Synapse ModuleApi instance
+        """
+        self.api = api
+        self.config = config
+        main_config = api._hs.config
+
+        # Get configuration parameters
+        self.whitelist_api_url = config.get("whitelist_api_url", "")
+        self.api_key = config.get("api_key", "")
+        self.update_interval = config.get("update_interval_minutes", 10)
+        self.timeout = config.get("timeout", 10)
+        self.enabled = config.get("enabled", True)
+        # Normalise the initial whitelist to lowercase; matrix server names are
+        # case-insensitive (RFC 1035 / Matrix spec) and we compare lowercase below.
+        self.initial_whitelist = {
+            s.lower() for s in (main_config.federation.federation_domain_whitelist or set())
+        }
+
+        # In-memory whitelist storage
+        self.whitelisted_servers: Set[str] = self.initial_whitelist.copy()
+        self.last_update: Optional[datetime] = None
+        self.last_fetch_success: bool = False
+
+        # Validate configuration
+        if self.enabled and not self.whitelist_api_url and not self.initial_whitelist:
+            logger.error("Neither Whitelist API URL nor initial_whitelist configured. Module will be disabled.")
+            self.enabled = False
+
+        if self.enabled and self.whitelist_api_url.startswith("http://"):
+            logger.warning(
+                "whitelist_api_url is configured with plain HTTP (%s) — the "
+                "API key will be transmitted in clear text. Use HTTPS in "
+                "production.",
+                self.whitelist_api_url,
+            )
+
+        # Register federation spam checker callbacks
+        if self.enabled:
+            # Register the should_drop_federated_event callback to control federation
+            api.register_spam_checker_callbacks(
+                should_drop_federated_event=self.should_drop_server_federation_event,
+                user_may_invite=self.user_may_invite,
+                federated_user_may_invite=self.federated_user_may_invite,
+            )
+
+            # Only start the update task if we have an API URL
+            if self.whitelist_api_url:
+                # Start the periodic update task
+                self.api.looping_background_call(
+                    self._update_whitelist,
+                    msec=self.update_interval * 60 * 1000,
+                    desc="Dynamic Federation Whitelist Update",
+                )
+
+                # Also, run an initial update immediately
+                self.api.run_as_background_process(
+                    "Initial Federation Whitelist Update",
+                    self._update_whitelist,
+                )
+
+                logger.info(
+                    f"Dynamic Federation Whitelist module initialized with API: {self.whitelist_api_url}, "
+                    f"update interval: {self.update_interval} minutes"
+                )
+            else:
+                logger.info(
+                    f"Dynamic Federation Whitelist module initialized with static whitelist: {self.whitelisted_servers}"
+                )
+        else:
+            logger.info("Dynamic Federation Whitelist module is disabled")
+
+    @staticmethod
+    def parse_config(config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Parse and validate the module configuration.
+
+        Args:
+            config: Raw configuration dictionary
+
+        Returns:
+            Parsed configuration dictionary
+        """
+        return {
+            "whitelist_api_url": config.get("whitelist_api_url", ""),
+            "api_key": config.get("api_key", ""),
+            "update_interval_minutes": config.get("update_interval_minutes", 10),
+            "timeout": config.get("timeout", 10),
+            "enabled": config.get("enabled", True),
+            "initial_whitelist": config.get("initial_whitelist", []),
+            "headers": config.get("additional_headers", {}),
+        }
+
+    async def should_drop_server_federation_event(self, event: EventBase) -> bool:
+        """
+        Check if a event's origin server name should be blocked based on whitelisted_servers.
+
+        Args:
+            event: event that comes in from other servers
+
+        Returns:
+            True if the event should be dropped, False otherwise.
+        """
+
+        # Check if the sender's server is whitelisted. The whitelist is stored
+        # lowercase; lowercase the origin too because Matrix server names are
+        # case-insensitive (RFC 1035, Matrix spec). NOTE: this approximates
+        # "origin server" via event.sender — federation signing makes that
+        # safe in practice, but a fully strict implementation would also
+        # check the PDU's signing origin.
+        try:
+            _, origin = event.sender.split(":", 1)
+        except (ValueError, AttributeError):
+            return True  # Drop if the sender format is invalid or missing
+        origin = origin.lower()
+        if origin not in self.whitelisted_servers:
+            logger.info("Blocking federation from non-whitelisted server: %s", origin)
+            return True
+
+        logger.debug("Federation from whitelisted server: %s", origin)
+        return False
+
+    async def user_may_invite(self, inviter_userid: str, invitee_userid: str, room_id: str) -> bool:
+        """Check if a local user is allowed to invite a user from another server."""
+
+        try:
+            _, remote_domain = invitee_userid.split(":", 1)
+        except (ValueError, AttributeError):
+            return True  # Allow if format is invalid (let Synapse handle it)
+
+        # If it's a local user, always allow
+        # TODO: maybe this could be denied too, if we were strict (or a config option?)
+        if self.api.is_mine(invitee_userid):
+            return True
+
+        if remote_domain.lower() not in self.whitelisted_servers:
+            logger.info("Blocking invite to non-whitelisted server: %s", remote_domain)
+            return False
+
+        return True
+
+    async def federated_user_may_invite(self, event: EventBase) -> bool:
+        """Check if a federated user is allowed to invite a local user."""
+
+        inviter_userid = event.sender
+        try:
+            _, remote_domain = inviter_userid.split(":", 1)
+        except (ValueError, AttributeError):
+            return True  # Allow if format is invalid (let Synapse handle it)
+
+        # If it's a local user, always allow (shouldn't happen for this callback)
+        # TODO: maybe this could be denied too, if we were strict (or a config option?)
+        if self.api.is_mine(inviter_userid):
+            return True
+
+        if remote_domain.lower() not in self.whitelisted_servers:
+            logger.info("Blocking invite from non-whitelisted server: %s", remote_domain)
+            return False
+
+        return True
+
+    async def _update_whitelist(self):
+        """
+        Fetch the current whitelist from the remote API and update the in-memory list.
+        """
+        try:
+            logger.info("Fetching federation whitelist from remote API...")
+
+            servers = await self._fetch_whitelist_from_api()
+
+            if servers is not None:
+                old_count = len(self.whitelisted_servers)
+
+                # Build the new set fully before assigning, so concurrent
+                # readers in should_drop_server_federation_event never see
+                # a half-updated state (without the initial whitelist merged in).
+                new_set: Set[str] = set(servers)
+                if self.initial_whitelist:
+                    new_set.update(self.initial_whitelist)
+                self.whitelisted_servers = new_set
+
+                self.last_update = datetime.now()
+                self.last_fetch_success = True
+
+                new_count = len(self.whitelisted_servers)
+                logger.info(
+                    "Federation whitelist updated: %d -> %d servers. Current whitelist: %s",
+                    old_count,
+                    new_count,
+                    sorted(self.whitelisted_servers),
+                )
+            else:
+                self.last_fetch_success = False
+                logger.warning(
+                    "Failed to fetch whitelist from remote API. "
+                    f"Keeping existing whitelist with {len(self.whitelisted_servers)} servers."
+                )
+
+        except Exception as e:
+            self.last_fetch_success = False
+            logger.error(f"Error updating federation whitelist: {e}")
+
+    async def _fetch_whitelist_from_api(self) -> Optional[List[str]]:
+        """
+        Fetch the whitelist from the remote REST API.
+
+        Returns:
+            List of whitelisted server names or None if request fails
+        """
+        # Convert headers to Synapse format (bytes -> List[bytes])
+        synapse_headers = {}
+        for k, v in self.config.get("headers", {}).items():
+            synapse_headers[k.encode("utf-8")] = [v.encode("utf-8")]
+
+        # Add API key if configured
+        if self.api_key:
+            synapse_headers[b"Authorization"] = [f"Bearer {self.api_key}".encode("utf-8")]
+
+        try:
+            data = await self.api.http_client.get_json(
+                self.whitelist_api_url,
+                headers=synapse_headers,
+            )
+
+            # Parse the response - expecting a list of server names
+            servers = []
+
+            # Handle different possible response formats
+            if isinstance(data, list):
+                # Direct list of servers
+                servers = data
+            elif isinstance(data, dict):
+                # Check for common field names
+                if "servers" in data:
+                    servers = data["servers"]
+                elif "whitelist" in data:
+                    servers = data["whitelist"]
+                elif "allowed" in data:
+                    servers = data["allowed"]
+                elif "domains" in data:
+                    servers = data["domains"]
+                else:
+                    logger.warning(
+                        f"Unexpected API response format: {list(data.keys())}"
+                    )
+                    return None
+            else:
+                logger.warning(f"Unexpected API response type: {type(data)}")
+                return None
+
+            # Validate that we got a list of plausible hostnames. Reject any
+            # entry containing whitespace, control characters, or characters
+            # outside the hostname grammar — a compromised whitelist API
+            # should not be able to inject arbitrary tokens that get matched
+            # against parsed sender domains downstream.
+            validated_servers: List[str] = []
+            for server in servers:
+                name: Optional[str] = None
+                if isinstance(server, str):
+                    name = server
+                elif isinstance(server, dict):
+                    name = (
+                        server.get("server")
+                        or server.get("domain")
+                        or server.get("name")
+                        or server.get("hostname")
+                    )
+                if not isinstance(name, str):
+                    continue
+                name = name.strip().lower()
+                if name and _is_valid_server_name(name):
+                    validated_servers.append(name)
+
+            logger.debug(
+                f"Fetched {len(validated_servers)} servers from remote API"
+            )
+            return validated_servers
+
+        except HttpResponseException as e:
+            logger.error(f"Remote API returned status {e.code} when fetching federation whitelist")
+            return None
+        except Exception as e:
+            logger.error(f"Error fetching federation whitelist: {e}")
+            return None
+
+
+def create_module(config: Dict[str, Any], api: ModuleApi) -> DynamicFederationWhitelist:
+    """
+    Factory function to create the module instance.
+
+    This is the entry point that Synapse will call to instantiate the module.
+
+    Args:
+        config: Module configuration from homeserver.yaml
+        api: Synapse ModuleApi instance
+
+    Returns:
+        Initialized DynamicFederationWhitelist instance
+    """
+    return DynamicFederationWhitelist(config, api)

matrix_server_isenguard-0.1.1/src/isenguard/mxid_uri.py

@@ -0,0 +1,70 @@
+"""Parse and validate Matrix user identifiers from various URI forms."""
+
+from __future__ import annotations
+
+import re
+
+# Matrix MXID grammar (https://spec.matrix.org/v1.10/appendices/#user-identifiers).
+# Localpart: lowercase ASCII letters, digits, and a small punctuation set.
+# Historical localparts include uppercase; we accept either to avoid
+# rejecting legacy directory entries, but otherwise stay strict.
+_LOCALPART_RE = re.compile(r"\A[a-zA-Z0-9._=/+\-]+\Z")
+
+# Server-part: hostname (or IP) with optional :port. ASCII only — dots,
+# hyphens, colons, brackets (IPv6), alphanumerics. No whitespace, no
+# control characters, no other special chars.
+_SERVER_RE = re.compile(r"\A[a-zA-Z0-9.\-:\[\]]+\Z")
+
+# matrix: URI scheme — user form ("u/") and historical alias ("user/").
+_MATRIX_URI_RE = re.compile(r"\Amatrix:(?:u|user)/([^:/?#]+):(.+)\Z")
+
+# Hard upper bound from the Matrix spec.
+_MXID_MAX_LEN = 255
+
+
+def parse_mxid(value: str | None) -> str | None:
+    """Normalise a string to a syntactically valid MXID '@localpart:server', or None.
+
+    Validates:
+      - non-empty localpart and server
+      - localpart against the Matrix grammar
+      - server against a conservative hostname/port grammar
+      - total length <= 255
+
+    Accepts the same surface forms as before:
+      - '@localpart:server'
+      - 'matrix:u/localpart:server'
+      - 'matrix:user/localpart:server'
+
+    Returns None for anything that fails validation, with no exceptions
+    propagated. Untrusted input (FHIR responses, URI fields) should always
+    flow through this function before being handed to Synapse.
+    """
+    if not value:
+        return None
+    s = value.strip()
+    if not s or len(s) > _MXID_MAX_LEN:
+        return None
+
+    if s.startswith("@"):
+        return _validated(s[1:])
+
+    m = _MATRIX_URI_RE.match(s)
+    if m:
+        return _validated(f"{m.group(1)}:{m.group(2)}")
+
+    return None
+
+
+def _validated(rest: str) -> str | None:
+    """Validate '<localpart>:<server>' and return '@<localpart>:<server>' or None."""
+    if ":" not in rest:
+        return None
+    localpart, server = rest.split(":", 1)
+    if not localpart or not server:
+        return None
+    if not _LOCALPART_RE.match(localpart):
+        return None
+    if not _SERVER_RE.match(server):
+        return None
+    return f"@{localpart}:{server}"