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.
references/safety-guide.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Safety guide
These scripts hold a **Synapse server-admin token**. A bad command is visible homeserver-wide and a few are not reversible. Read this once before running anything new.
## Pre-flight checklist
Before any state-changing command:
1. **Confirm the homeserver URL** in `~/.config/matrix/config.json` — the wrong host with the right script wipes the wrong server.
2. **Confirm the user/room/space ID** you typed. Matrix IDs are similar; copy/paste them and read them back.
3. **Run any read-only script first** to verify the target exists:
- `uv run …/synapse-user-rooms.py '@user:server'`
- `uv run …/synapse-room-member-flow.py '!room:server'`
4. For destructive operations, **dry-run by hand**: print the planned action to stdout (`echo`, `python3 -c 'print(…)'`) and ask the operator to confirm before invoking the script.
## Per-script risks
### `synapse-deactivate-user.py`
- Calls `POST /_synapse/admin/v1/deactivate/{user_id}`.
- The user **cannot log in again**, all access tokens are revoked, the user is **left from every joined room**.
- With `--erase`, message bodies are also redacted (GDPR right-to-erasure).
- Not reversible without a database operation by a homeserver operator.
- The script prints the user's profile + joined rooms before and after, and refuses to run non-interactively without `--yes`.
### `synapse-migrate-room.py`
The hardening pipeline is **partially irreversible**:
| Step | Reversible? |
|------|-------------|
| Add to space | yes — remove the `m.space.child` event |
| Force-join the caller | yes — leave the room |
| Promote to PL 100 | yes — restored at the end of the pipeline |
| Switch `public` → `restricted` | yes — change `m.room.join_rules` back |
| Enable encryption | **no** — Megolm cannot be turned off |
The room version must be > 9 for `restricted` joins; otherwise the script prints a red ❌ for that step. Switching to `restricted` removes discoverability for users not in the parent space.
Like `synapse-deactivate-user.py`, the script reads the room's current state, prints the steps it would take — marking the encryption step as one that cannot be undone — and then asks. `--yes` skips the question and is required without a terminal. The question comes before the first write, so aborting leaves the room untouched.
### `synapse-make-admin.py` / `synapse-join-room.py`
- Only works while *some* existing admin is still in the room (Synapse refuses otherwise).
- If the original owner has already left, the room is **unrecoverable** through this tool — Synapse explicitly forbids re-creating admin from outside.
- **Taking admin in a non-public room you are not a member of: `make-admin` first, then join as yourself.** `synapse-join-room.py` (`POST /v1/join`) fails with `M_FORBIDDEN … not in room` there, because for a room that is not public Synapse sends the invite as the calling server admin, who would have to be in the room. `synapse-make-admin.py` succeeds (prints `{}`): Synapse writes the power-level change and then the invite *as the highest-ranked local user who is joined*, so the target gets that user's level (100 only if that user has 100) and an invite. Accept the invite through the Client-Server API with your own token (`POST /_matrix/client/v3/rooms/{room_id}/join`), then read `m.room.power_levels` before any write that needs a level — the `{}` response is the same for an already-joined, a public and an invited user, and re-running the call cannot raise the level above that local user's.
### `synapse-search.py`
- Read-only on the API. Risk is **misinterpretation**: only **unencrypted** messages are indexed. An empty result on an E2EE room means "search saw nothing", not "the user did not say anything". Use Element / a real client when you need plaintext from an encrypted room.
### `synapse-fetch-rooms.py`
- Read-only, but the resulting `rooms.json` contains user IDs, room names, power levels and join policies for **every** indexed room.
- **Never commit it** — the skill's `.gitignore` does not cover the working directory the script is run in.
- Treat the file the same as the admin token.
## Token hygiene
- The admin token is equivalent to root on the homeserver. Store it only in `~/.config/matrix/config.json` (or a secret manager that writes that file at startup).
- Rotate it after onboarding/offboarding any user who had file-system access to a host that ran these scripts.
- If you publish a Docker image (e.g. the graph dashboard from `room-graph-pipeline.md`), pass the token via `--secret`, never via `ENV` or build args.
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: 471k | 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: 471k | 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: 471k | 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 |