Releases · netresearch/matrix-skill

26 Apr 04:58

v1.21.0

acc19d1

v1.21.0 Latest

Latest

Highlights

New skill: matrix-administration — a stdlib-only Python companion to the existing matrix-communication skill. Where matrix-communication talks to Matrix as a user (chat, E2EE), matrix-administration talks to a Synapse server as a server-admin: snapshot every room, rate room health, render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict joins + enable encryption), deactivate users (with optional GDPR --erase), find the biggest rooms by DB size, audit single-admin rooms, replay member-flow timelines, and search unencrypted history.

The skill ships zero homeserver-specific defaults — the homeserver URL, optional server-suffix filter, and "home" space IDs are all operator-supplied via ~/.config/matrix/config.json (the same file matrix-communication reads) or CLI flags.

What's new

`matrix-administration` skill (#27)

13 scripts:

Script	Purpose
`synapse-fetch-rooms.py`	Paginated snapshot of `/v1/rooms` + per-room state → `rooms.json`
`synapse-rate-rooms.py`	Health checks (public / unencrypted / orphaned), EN + DE phrasing
`synapse-graph.py`	`rooms.json` → Graphviz `.dot` + `.svg`, colour-coded by rating
`synapse-biggest-rooms.py`	Top-N rooms by Synapse-estimated DB size
`synapse-join-room.py`	Force-join a user via the admin API
`synapse-make-admin.py`	Promote a user to power-level 100
`synapse-add-to-space.py`	Send `m.space.child` linking a room into a space
`synapse-migrate-room.py`	One-shot hardening pipeline (add-to-space + restrict + encrypt + restore PL on exit / Ctrl-C)
`synapse-deactivate-user.py`	Destructive user deactivation, optional GDPR `--erase`
`synapse-user-admin-rooms.py`	Local: rooms where a user is PL 100, with co-admin count
`synapse-user-rooms.py`	Local: every room a user is a member of
`synapse-room-member-flow.py`	Chronological join/leave timeline
`synapse-search.py`	Unencrypted history search (E2EE rooms return nothing)

Plus four reference docs (synapse-admin-api.md, room-health-checks.md, room-graph-pipeline.md, safety-guide.md) and 10 evals.

No new dependencies — Python stdlib only. The skill works against any Synapse 1.x homeserver with the admin API enabled.

Release pipeline

The reusable release workflow now publishes 7 assets per release (up from 5), auto-discovered from plugin.json.skills:

matrix-communication-skill-v1.21.0.{tar.gz,zip}
matrix-administration-skill-v1.21.0.{tar.gz,zip} — new
matrix-communication-plugin-v1.21.0.{tar.gz,zip} (the whole plugin)
SHA256SUMS.txt

CI

ci: forward bump input from workflow_dispatch to reusable release workflow (#26) — releases triggered manually now respect the bump choice (patch/minor/major).

Safety notes

The matrix-administration skill holds a server-admin token. Read safety-guide.md before running anything new. In particular:

synapse-deactivate-user.py is irreversible without database intervention.
synapse-migrate-room.py enables encryption (one-way) and switches public rooms to restricted. Power-level changes are restored on exit, including on Ctrl-C / SIGTERM.
synapse-make-admin.py raises power-level 100 permanently — call it deliberately.
synapse-search.py cannot read end-to-end-encrypted messages — empty results ≠ no messages.
The generated rooms.json exposes user IDs and power levels for every indexed room. Never commit it.

Pull requests in this release

ci: forward bump input to reusable release workflow by @CybotTM in #26
feat(skills): add matrix-administration (Synapse Admin API) by @CybotTM in #27
chore: release v1.21.0 by @CybotTM in #28

Full changelog: v1.20.1...v1.21.0

Contributors

CybotTM

Assets 9

22 Apr 09:57

github-actions

v1.20.1

3e7bfb1

v1.20.1

Security fix

fix(security): validate URL scheme before urllib.urlopen (a3135ee). urllib accepts non-HTTP schemes like file:// and ftp://, which an Opengrep rule flagged as a potential SSRF/local-file-read vector. The call site now rejects anything outside http/https before opening the URL.

CI / infrastructure

Fixed the auto-merge-deps reusable workflow reference (it was pointed at a path that no longer exists), restoring Renovate auto-merge for this repo.

Full Changelog: v1.20.0...v1.20.1

Assets 7

16 Apr 11:01

github-actions

v1.20.0

23ca095

v1.20.0

What's new

This release adds media download support with full E2EE decryption — the missing piece for transferring images and files from Matrix chat to external systems like Jira.

Media metadata in JSON output

matrix-read-e2ee.py --json now includes media fields for image, file, video, and audio messages:

{
  "msgtype": "m.image",
  "body": "screenshot.png",
  "url": "mxc://server/media_id",
  "info": {"mimetype": "image/png", "size": 24571, "w": 948, "h": 211}
}

Previously these messages only showed {"body": "image.png", "msgtype": "m.image"} with no URL or metadata. E2EE decryption keys are intentionally excluded from the output — the download script handles decryption internally.

New: matrix-download-e2ee.py

Download and decrypt E2EE media by event ID:

matrix-download-e2ee.py helpdesk '$event_id' --output /tmp
# → /tmp/screenshot.png (valid PNG, fully decrypted)

Uses nio's crypto primitives for AES-CTR decryption of encrypted attachments. Filenames are sanitized against path traversal. Supports --filename override and --debug for troubleshooting.

End-to-end proof

The full Matrix-to-Jira pipeline now works in three commands:

matrix-read-e2ee.py → get event ID and mxc URL
matrix-download-e2ee.py → download and decrypt to local file
jira-attachment.py add → attach to Jira issue

Tested live: downloaded an E2EE-encrypted screenshot from #helpdesk, verified as valid PNG, and attached it to a Jira issue.

CI

Reusable harness-verify and eval-validate workflows from skill-repo-skill
Script paths now use ${CLAUDE_SKILL_DIR} for portable installation

Assets 7

01 Apr 09:11

CybotTM

v1.19.0

55e94a3

v1.19.0

Release v1.19.0

What's Changed

Curate evals to 25, improve SKILL.md coverage by @CybotTM in #21

Full Changelog: v1.17.2...v1.19.0

Contributors

CybotTM

Assets 7

29 Mar 20:22

CybotTM

v1.17.2

62c7b05

v1.17.2

Maintenance release fixing Python code quality issues and updating CI dependencies.

Resolved all ruff lint errors across the Python scripts, bringing the codebase in line with current ruff formatting standards. Updated actions/setup-python from v5.6.0 to v6.2.0 in the CI pipeline.

Full Changelog: v1.17.1...v1.17.2

Assets 7