Skip to content

netresearch/matrix-skill / skills/matrix-administration

matrix-administration

Verified

Use when administering a Synapse / Matrix homeserver — list or snapshot all rooms, rate room health (public, unencrypted, orphaned), render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict + encrypt), deactivate Matrix users (with GDPR erase), find biggest rooms by DB size, audit where a user is admin or member, replay join/leave timelines, or search unencrypted history. Trigger on any '/_synapse/admin', server-wide room operation, Matrix user offboarding, or anything requiring a homeserver-admin token — even without 'admin API' in the prompt. Companion to matrix-communication.

scripts/_lib/admin_http.py

View on GitHub
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH

"""HTTP wrappers for the Synapse Admin API and Matrix Client-Server API.

Both admin endpoints (under ``/_synapse/admin``) and standard Matrix client
endpoints (under ``/_matrix/client/v3``) are reachable through the same HTTP
helpers.  Most helpers in this module accept an admin token; a few stubs are
provided for endpoints that require client-server semantics.

Stdlib only.
"""

from __future__ import annotations

import contextlib
import json
import socket
import urllib.error
import urllib.parse
import urllib.request

_ALLOWED_SCHEMES = frozenset({"http", "https"})


def _require_http_scheme(url: str) -> None:
    scheme = urllib.parse.urlparse(url).scheme
    if scheme not in _ALLOWED_SCHEMES:
        raise ValueError(
            f"Refusing to fetch URL with scheme {scheme!r}; only http/https allowed"
        )


def _origin(url: str) -> tuple:
    parts = urllib.parse.urlsplit(url)
    scheme = parts.scheme.lower()
    return (
        scheme,
        (parts.hostname or "").lower(),
        parts.port or (443 if scheme == "https" else 80),
    )


class _SameOriginAuthRedirectHandler(urllib.request.HTTPRedirectHandler):
    """Follow redirects, but send the Authorization header only to the same origin.

    urllib copies every request header onto the redirected request, so a
    redirect to another scheme, host or port would receive the access token.
    """

    def redirect_request(self, req, fp, code, msg, headers, newurl):
        new = super().redirect_request(req, fp, code, msg, headers, newurl)
        if new is not None and _origin(req.full_url) != _origin(newurl):
            new.remove_header("Authorization")
        return new


_OPENER = urllib.request.build_opener(_SameOriginAuthRedirectHandler)


@contextlib.contextmanager
def _prefer_ipv4():
    """Temporarily prefer IPv4 in DNS resolution (WSL2 workaround)."""
    original = socket.getaddrinfo

    def patched(*args, **kwargs):
        results = original(*args, **kwargs)
        return sorted(results, key=lambda r: r[0] != socket.AF_INET)

    socket.getaddrinfo = patched
    try:
        yield
    finally:
        socket.getaddrinfo = original


_DEFAULT_TIMEOUT = 60


def _do_request(req: urllib.request.Request) -> dict:
    """Execute a request and return parsed JSON response.

    The caller must have validated the URL scheme via
    ``_require_http_scheme`` before constructing ``req``.  A 60-second
    timeout is applied so a hung server does not freeze the script.
    """
    _require_http_scheme(req.full_url)
    # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
    with _OPENER.open(req, timeout=_DEFAULT_TIMEOUT) as response:
        body = response.read().decode()
        if not body:
            return {}
        return json.loads(body)


def _parse_http_error(e: urllib.error.HTTPError) -> dict:
    error_body = e.read().decode()
    try:
        parsed = json.loads(error_body)
        return {
            "error": parsed.get("error", error_body),
            "errcode": parsed.get("errcode"),
            "status": e.code,
        }
    except json.JSONDecodeError:
        return {"error": error_body, "errcode": str(e.code), "status": e.code}


def _request(url: str, method: str, token: str, data: dict | None) -> dict:
    _require_http_scheme(url)
    headers = {"Authorization": f"Bearer {token}"}
    body = None
    if data is not None:
        headers["Content-Type"] = "application/json"
        body = json.dumps(data).encode()

    req = urllib.request.Request(url, data=body, headers=headers, method=method)
    try:
        return _do_request(req)
    except urllib.error.HTTPError as e:
        return _parse_http_error(e)
    except OSError as e:
        if e.errno not in (101, 113):
            return {"error": str(e)}
        try:
            with _prefer_ipv4():
                req2 = urllib.request.Request(
                    url, data=body, headers=headers, method=method
                )
                return _do_request(req2)
        except urllib.error.HTTPError as e2:
            return _parse_http_error(e2)
        except OSError as e2:
            return {"error": str(e2)}


def admin_request(
    config: dict, method: str, endpoint: str, data: dict | None = None
) -> dict:
    """Call a Synapse Admin API endpoint.

    Args:
        config: Dict with ``homeserver`` and ``admin_token`` (or ``access_token``).
        method: HTTP method.
        endpoint: Admin path beginning with ``/v1/...`` or ``/v2/...``
            (the ``/_synapse/admin`` prefix is added automatically).
        data: JSON body, if any.

    Returns:
        Parsed JSON response, or a dict with ``error``/``errcode`` on failure.
    """
    token = config.get("admin_token") or config["access_token"]
    url = f"{config['homeserver']}/_synapse/admin{endpoint}"
    return _request(url, method, token, data)


def client_request(
    config: dict, method: str, endpoint: str, data: dict | None = None
) -> dict:
    """Call a Matrix Client-Server v3 endpoint with the admin token.

    Used for state events and other Matrix-spec calls that the admin token
    can perform (the admin user must be in the room).

    Args:
        config: Dict with ``homeserver`` and ``admin_token`` (or ``access_token``).
        method: HTTP method.
        endpoint: Path beginning with ``/`` (the ``/_matrix/client/v3`` prefix
            is added automatically).
        data: JSON body, if any.
    """
    token = config.get("admin_token") or config["access_token"]
    url = f"{config['homeserver']}/_matrix/client/v3{endpoint}"
    return _request(url, method, token, data)


def quote(value: str) -> str:
    """URL-encode a path segment (room IDs, user IDs, aliases)."""
    return urllib.parse.quote(value, safe="")
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall