netresearch/matrix-skill / skills/matrix-administration
matrix-administration
VerifiedUse 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="")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |