Skip to content

netresearch/matrix-skill / skills/matrix-communication

matrix-communication

Flagged

Use when communicating via Matrix chat, notifying teams, or managing E2EE. Triggers on #room:server references, Matrix URLs, and chat requests.

FileKindSize
README.mdmarkdown2.9 KB
SKILL.mdskill md6.7 KB
evals/evals.jsonconfig12.6 KB
references/agent-governance.mdmarkdown2.0 KB
references/api-reference.mdmarkdown7.3 KB
references/command-reference.mdmarkdown8.9 KB
references/e2ee-guide.mdmarkdown17.2 KB
references/hookshot-integration.mdmarkdown10.7 KB
references/messaging-guide.mdmarkdown13.8 KB
references/no-editorializing.mdmarkdown331 B
references/setup-guide.mdmarkdown11.1 KB
references/troubleshooting.mdmarkdown7.8 KB
scripts/_lib/__init__.pyscript3.6 KB
scripts/_lib/backup_mac.pyscript1.2 KB
scripts/_lib/config.pyscript4.6 KB
scripts/_lib/daemon_client.pyscript3.0 KB
scripts/_lib/deps.pyscript1.9 KB
scripts/_lib/downloads.pyscript1.1 KB
scripts/_lib/e2ee.pyscript13.2 KB
scripts/_lib/formatting.pyscript14.4 KB
scripts/_lib/http.pyscript4.8 KB
scripts/_lib/reactions.pyscript2.9 KB
scripts/_lib/roomlog.pyscript13.7 KB
scripts/_lib/rooms.pyscript15.5 KB
scripts/_lib/secret_input.pyscript2.0 KB
scripts/_lib/test_backup_mac.pyscript1.5 KB
scripts/_lib/test_config.pyscript7.1 KB
scripts/_lib/test_daemon_client.pyscript5.9 KB
scripts/_lib/test_downloads.pyscript2.3 KB
scripts/_lib/test_e2ee.pyscript14.3 KB
scripts/_lib/test_formatting.pyscript15.5 KB
scripts/_lib/test_http.pyscript4.1 KB
scripts/_lib/test_reactions.pyscript15.2 KB
scripts/_lib/test_roomlog.pyscript20.2 KB
scripts/_lib/test_rooms.pyscript13.7 KB
scripts/_lib/test_secret_input.pyscript2.2 KB
scripts/_lib/test_trust.pyscript8.3 KB
scripts/_lib/trust.pyscript5.3 KB
scripts/_lib/utils.pyscript1.7 KB
scripts/matrix-create-room.pyexecutablescript4.7 KB
scripts/matrix-doctor.pyexecutablescript22.2 KB
scripts/matrix-download-e2ee.pyexecutablescript7.7 KB
scripts/matrix-e2ee-setup.pyexecutablescript9.2 KB
scripts/matrix-e2ee-verify.pyexecutablescript29.2 KB
scripts/matrix-edit-e2ee.pyexecutablescript7.9 KB
scripts/matrix-edit.pyexecutablescript5.3 KB
scripts/matrix-fetch-keys.pyexecutablescript9.1 KB
scripts/matrix-invite.pyexecutablescript3.0 KB
scripts/matrix-key-backup.pyexecutablescript21.3 KB
scripts/matrix-power-level.pyexecutablescript7.0 KB
scripts/matrix-react.pyexecutablescript14.1 KB
scripts/matrix-read-e2ee.pyexecutablescript12.8 KB
scripts/matrix-read.pyexecutablescript4.7 KB
scripts/matrix-redact.pyexecutablescript5.0 KB
scripts/matrix-resolve.pyexecutablescript1.7 KB
scripts/matrix-rooms.pyexecutablescript3.8 KB
scripts/matrix-send-e2ee.pyexecutablescript19.4 KB
scripts/matrix-send.pyexecutablescript9.4 KB
scripts/matrix-watch.pyexecutablescript5.3 KB
scripts/matrix-watchd.pyexecutablescript23.5 KB
scripts/test_matrix_doctor.pyscript14.2 KB
scripts/test_matrix_read_e2ee.pyscript2.7 KB

scripts/_lib/e2ee.py

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

"""E2EE credential management for Matrix scripts.

All functions use ONLY stdlib - no nio dependencies here.
The actual E2EE functionality (using nio) is in the scripts themselves.
"""

import atexit
import contextlib
import errno
import fcntl
import json
import os
import time
from contextlib import contextmanager
from pathlib import Path


def private_dir(path: Path) -> Path:
    """Create ``path`` if needed and make it accessible to its owner only.

    The mode is applied on every call, not only on creation, so a directory an
    older version created with the default umask is tightened on first use.
    Everything below it - credentials, the nio store, decrypted room logs -
    is then out of reach of other local users whatever the files' own modes.
    """
    path.mkdir(mode=0o700, parents=True, exist_ok=True)
    # 0700 on a directory is owner-only; the execute bit is what lets the
    # owner enter it.
    # nosemgrep: python.lang.security.audit.insecure-file-permissions.insecure-file-permissions
    os.chmod(path, 0o700)
    return path


def write_private_file(path: Path, data: str) -> None:
    """Write ``data`` to ``path`` readable and writable by the owner only.

    The file is created with mode 0600 rather than chmod-ed after the write,
    an existing file is tightened before anything is written to it, and a
    symlink at ``path`` is refused instead of followed.
    """
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
    with os.fdopen(fd, "w", encoding="utf-8") as handle:
        os.fchmod(handle.fileno(), 0o600)
        handle.write(data)


def get_store_path() -> Path:
    """Get or create the E2EE key store directory.

    Uses XDG_DATA_HOME or falls back to ~/.local/share/matrix-skill/store.
    The ``matrix-skill`` directory and the store are owner-only (0700).
    """
    xdg_data = os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share")
    root = private_dir(Path(xdg_data) / "matrix-skill")
    return private_dir(root / "store")


def rooms_dir() -> Path:
    """Directory holding the per-room event logs and the room bundle.

    A sibling of the E2EE store rather than a child: nothing in here is
    device-scoped, and `--logout` must not carry a room's history away with the
    device it was recorded on.
    """
    return private_dir(get_store_path().parent / "rooms")


def verification_partner_allowed(sender, own_user_id, accept_from=()) -> bool:
    """Whether a verification event from ``sender`` may be answered.

    matrix-e2ee-verify.py confirms the short authentication string on its own
    side; the comparison is done by the person at the other device. That is
    sound for the account's own devices, where that person is the owner. For
    another user's device it would mark that device verified on the strength
    of a check only its owner made, so it is answered only for users named
    explicitly (``--accept-from``).
    """
    if not sender:
        return False
    return sender == own_user_id or sender in accept_from


def verification_emoji_path() -> Path:
    """Where matrix-e2ee-verify.py writes the emojis for an agent to poll."""
    return get_store_path().parent / "verification_emojis.txt"


def get_credentials_path() -> Path:
    """Get path for stored E2EE device credentials."""
    return get_store_path() / "credentials.json"


def load_credentials() -> dict | None:
    """Load stored device credentials if they exist.

    Returns:
        Dict with user_id, device_id, access_token, or None if not found
    """
    creds_path = get_credentials_path()
    if creds_path.exists():
        with open(creds_path) as f:
            return json.load(f)
    return None


def save_credentials(user_id: str, device_id: str, access_token: str):
    """Save device credentials for future use.

    The file is created with mode 0600 (see ``write_private_file``).
    """
    write_private_file(
        get_credentials_path(),
        json.dumps(
            {
                "user_id": user_id,
                "device_id": device_id,
                "access_token": access_token,
            },
            indent=2,
        ),
    )


LOCK_TIMEOUT = 30.0

# How deep this process is inside store_lock(). flock is held per open file
# description, so a process taking it twice on two descriptors blocks on
# itself - which the daemon would do the moment it called a helper that locks.
_LOCK_DEPTH = 0


def store_lock_path():
    """The file whose flock stands for the right to open the E2EE store."""
    return get_store_path() / ".daemon.lock"


@contextmanager
def store_lock(timeout: float = LOCK_TIMEOUT):
    """Hold the exclusive right to open the E2EE store, or refuse.

    Two nio processes on one store corrupt it, and the corruption does not
    announce itself - it surfaces later as an undecryptable message or a store
    that no longer opens. The daemon holds this lock for its whole run; every
    direct path takes it too, so the collision becomes a wait and then a clear
    refusal instead of silent damage.

    Blocking rather than failing at once: a direct send that arrives during
    another command's couple of seconds should wait for it, not error. On
    timeout the holder's pid is named, because the useful next question is
    always "who has it".
    """
    global _LOCK_DEPTH

    if _LOCK_DEPTH:
        # Already ours. Re-entering is what happens when a locked command calls
        # a helper that locks; the alternative is a process deadlocking itself.
        _LOCK_DEPTH += 1
        try:
            yield
        finally:
            _LOCK_DEPTH -= 1
        return

    path = store_lock_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    deadline = time.monotonic() + timeout
    with open(path, "a+") as handle:
        locked = False
        try:
            while True:
                try:
                    fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
                    locked = True
                    break
                except OSError as exc:
                    if exc.errno not in (errno.EACCES, errno.EAGAIN):
                        raise
                    if time.monotonic() >= deadline:
                        handle.seek(0)
                        holder = handle.read().strip() or "unknown"
                        raise SystemExit(
                            f"Error: the E2EE store is held by pid {holder}.\n"
                            "\n"
                            "That is normally matrix-watchd. Commands that route through "
                            "it - send, react, redact, edit - work while it runs; this "
                            "one does not yet. Stop the daemon for the duration:\n"
                            "  matrix-watchd.py --stop && … && matrix-watchd.py --start"
                        ) from exc
                    time.sleep(0.2)

            handle.seek(0)
            handle.truncate()
            handle.write(str(os.getpid()))
            handle.flush()

            _LOCK_DEPTH = 1
            yield
        finally:
            _LOCK_DEPTH = 0
            if locked:
                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)


def explain_store_error(exc: Exception) -> str | None:
    """Diagnose a store that cannot be opened, or return None.

    A store written by one matrix-nio crypto backend cannot be read by the
    other: 0.25 serializes the olm account through libolm, 0.26 through
    vodozemac, and the two formats are not interchangeable. The failure surfaces
    as ``OlmAccountError: BAD_ACCOUNT_KEY``, which names a key, so the search
    goes to credentials.json, to the token, to the store path - none of which
    are wrong. Say what actually happened instead.

    Stdlib only, deliberately: this module must not import nio, so the exception
    is identified by type name and message rather than by class.
    """
    if "BAD_ACCOUNT_KEY" not in str(exc):
        return None
    if type(exc).__name__ not in ("OlmAccountError", "SessionError"):
        return None

    try:
        from importlib.metadata import version

        installed = version("matrix-nio")
    except Exception:  # noqa: BLE001  # diagnosis must not fail on a metadata lookup
        installed = "unknown"

    return (
        f"The E2EE store cannot be opened by the installed matrix-nio ({installed}).\n"
        "\n"
        "This is a backend mismatch, not a bad credential: matrix-nio 0.25 keeps "
        "the olm account in libolm's format and 0.26 in vodozemac's, and neither "
        "can read the other's. The store was written by the other one.\n"
        "\n"
        "The usual writer is a script copy from an OLDER skill version - a plugin\n"
        "cache directory or a stale checkout - whose unpinned dependency resolves\n"
        "the newest matrix-nio. Find and stop that source first (do NOT fall back\n"
        "to it as a workaround), or the store flips back after every re-setup.\n"
        "\n"
        "Run every script on the same pin. If the pin has moved, the store has to "
        "be recreated - it cannot be migrated:\n"
        "  matrix-e2ee-setup.py --logout && matrix-e2ee-setup.py\n"
        "  matrix-key-backup.py --import-keys\n"
        "  matrix-e2ee-verify.py --listen   # or --request DEVICE with a single Element session"
    )


def _hold_store_lock() -> None:
    """Take the store lock for the rest of this process.

    A CLI command opens the store once and exits; there is no point at which
    releasing early would help, and holding to the end is what stops a second
    process slipping in mid-run. The kernel releases it when the process ends,
    including when it is killed.
    """
    if _LOCK_DEPTH:
        return
    context = store_lock()
    context.__enter__()
    atexit.register(_release_held_lock, context)


def _release_held_lock(context) -> None:
    with contextlib.suppress(Exception):
        context.__exit__(None, None, None)


def restore_login_checked(client, user_id: str, device_id: str, access_token: str):
    """``client.restore_login`` that locks the store and explains what it cannot open.

    Takes the store lock before opening, and keeps it: these are one-shot
    commands, so "until the process exits" is exactly how long the store is in
    use, and the lock is released by the kernel when the last descriptor closes.
    Every path that opens the store therefore holds it, which is what makes
    exclusivity enforced rather than agreed.

    Takes the client as a parameter rather than importing nio, keeping this
    module stdlib-only.
    """
    _hold_store_lock()
    try:
        client.restore_login(
            user_id=user_id, device_id=device_id, access_token=access_token
        )
    except Exception as exc:
        hint = explain_store_error(exc)
        if hint is None:
            raise
        raise SystemExit(f"Error: {hint}") from exc


def store_files_for(user_id: str, device_id: str) -> list[Path]:
    """Every store file belonging to one device.

    nio names them ``{user_id}_{device_id}.<suffix>`` - the database plus the
    blacklisted/ignored/trusted device lists. The trailing dot matters: without
    it a device id that is a prefix of another would collect the other's files
    too.
    """
    prefix = f"{user_id}_{device_id}."
    return sorted(p for p in get_store_path().iterdir() if p.name.startswith(prefix))


def delete_credentials(
    purge_all: bool = False, lock_timeout: float = LOCK_TIMEOUT
) -> list[str]:
    """Remove the stored credentials and the store files of THAT device.

    Returns the names of the files removed, so the caller can say what it did.

    The store directory is shared by every device ever set up here. Globbing
    ``*.db`` and ``*_devices`` across it - which this did - means logging one
    device out destroys the megolm history of all the others. That happened:
    a logout of a broken device took a months-old 25 MB store with it, and only
    a server-side key backup made the rooms readable again.

    ``purge_all`` restores the old sweep for the case where you do want the
    directory emptied. ``backup_key.json`` is never touched either way; it is
    not device-scoped and re-importing keys depends on it.

    The files are removed under the store lock: deleting a store another
    process (the daemon, a send in progress) has open would leave that
    process writing into files that no longer exist. While the lock is held
    elsewhere this waits ``lock_timeout`` seconds and then refuses.
    """
    with store_lock(timeout=lock_timeout):
        return _delete_credentials_locked(purge_all)


def _delete_credentials_locked(purge_all: bool) -> list[str]:
    removed: list[str] = []
    creds = load_credentials()
    creds_path = get_credentials_path()

    if purge_all:
        store_path = get_store_path()
        targets = sorted([*store_path.glob("*.db"), *store_path.glob("*_devices")])
    elif creds and creds.get("user_id") and creds.get("device_id"):
        targets = store_files_for(creds["user_id"], creds["device_id"])
    else:
        # No credentials to scope by. Removing nothing beats removing everything.
        targets = []

    for path in targets:
        path.unlink()
        removed.append(path.name)

    if creds_path.exists():
        creds_path.unlink()
        removed.append(creds_path.name)

    return removed
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall