- Rust 66.8%
- Nix 22.7%
- Python 9.9%
- Dockerfile 0.6%
| docs | ||
| e2e | ||
| examples | ||
| messung/sqlite-nfs | ||
| src | ||
| .env.example | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| cliff.toml | ||
| compose.example.yml | ||
| Dockerfile | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| pemmikan.md | ||
| README.md | ||
botkern
Ende-zu-Ende, Anfang bis Ende 🔐🤖
Wiederverwendbarer Kern für Matrix-Bots auf matrix-rust-sdk (vodozemac) mit E2EE. Zwei Betriebsarten:
- Brückenmodus (
BOTKERN_BRIDGE_SOCKET): botkern übernimmt Verbindung und Verschlüsselung und reicht entschlüsselte Ereignisse über einen lokalen Unix-Socket an genau einen Bot in beliebiger Sprache weiter. Der Bot schickt Aufträge zurück: senden, bearbeiten, reagieren, redigieren, Räume anlegen und Mitglieder verwalten (docs/bridge-protocol.md, Protokoll v1). - Eingebaut: Rust-Module auf dem Kern;
!echoist das Beispielmodul.
Eigenschaften
- E2EE mit persistentem, verschlüsseltem SQLite-Krypto-Store. Ein Neustart behält das Gerät und die Krypto-Identität.
- Genau ein Schreiber: Vor dem Öffnen des Stores nimmt der Bot einen exklusiven fcntl-Lock auf
botkern.lockim Store-Verzeichnis (Wächter). Eine zweite Instanz wartet. Der Store darf auf zentralem NFSv4.2 liegen, Container können den Node wechseln. Die Messungen dazu stehen inmessung/sqlite-nfs/und in den Issues #3–#5. - Konfiguration nur über Umgebungsvariablen, siehe
.env.example. Fehlende Werte brechen den Start ab. Secrets erscheinen nie in Logs, URLs oder Pfaden. - Rechte:
BOTKERN_ALLOWED_USERSlegt fest, wer den Bot einladen darf, im eingebauten Modus auch, wer Befehle geben darf. Im Brückenmodus prüft der Bot die Rechte selbst. - Lebenszeichen: Auf
ping(oder!ping) antwortet jeder botkern-Bot mitpong, in jedem Raum und in beiden Betriebsarten. - Verifizierung:
botkern cross-signingrichtet einmalig die Bot-Identität ein. Danach nimmt der Bot Emoji-Verifizierungen erlaubter Nutzer an: Er schreibt die Emojis ins Log, bei Anfragen aus einem Raum zusätzlich in den Raum, und bestätigt automatisch.
Betrieb
- Bot-Konto anlegen, dann einmalig einloggen. Das Token geht nur auf stdout und nur in eine Pipe, also direkt in den Secret-Store. Die Geräte-ID geht auf stderr.
MATRIX_HOMESERVER=… MATRIX_USER_ID=… MATRIX_PASSWORD=… botkern login | <secret-store-insert> - Umgebung nach
.env.examplezur Laufzeit befüllen undbotkern runstarten. Container:nix build .#image(oderDockerfile), Beispiel incompose.example.yml. - Einmalig mit gestopptem Bot
botkern cross-signingausführen, das Passwort nur zur Laufzeit inMATRIX_PASSWORD. Danach lässt sich der Bot in Element verifizieren. - Direkt danach, ebenfalls bei gestopptem Bot, den Wiederherstellungsschlüssel anlegen und getrennt vom Store aufbewahren:
botkern recovery-key | <secret-store-insert>. - Node-Wechsel: Bei sauberem Stopp (SIGTERM) übernimmt die nächste Instanz nach wenigen Sekunden. Nach einem Absturz oder einer Netztrennung übernimmt sie erst nach Ablauf der NFS-Lease, gemessen etwa 90–100 s.
Notfall
Alle Notfall-Befehle laufen nur bei gestopptem Bot (läuft er noch, brechen sie sofort ab) und brauchen das Passwort zur Laufzeit in MATRIX_PASSWORD. Secrets gehen nur auf stdout und nur in eine Pipe.
| Lage | Befehl | Wirkung |
|---|---|---|
| Token geleakt | botkern rotate-token | <secret-store-insert> |
neues Token für dasselbe Gerät, gleiche Krypto-Identität; alle anderen Tokens und Geräte des Kontos werden widerrufen |
| Store verloren, Schlüssel vorhanden | botkern login, leeren Store, dann botkern recover mit MATRIX_RECOVERY_KEY |
neues Gerät wird mit der bisherigen Identität signiert, Nutzer müssen nicht neu verifizieren; das verlorene Gerät wird widerrufen |
| Store und Schlüssel verloren | botkern reset-identity |
neue Identität, Nutzer verifizieren den Bot neu; danach botkern recovery-key |
Widerruf heißt: Das Passwort wird neu gesetzt (MATRIX_NEW_PASSWORD oder das bisherige). Dabei löscht der Server alle anderen Geräte und Tokens des Bot-Kontos. Ein Login mit derselben Geräte-ID allein lässt alte Tokens gültig, und /logout würde das Gerät samt Schlüsseln löschen. Scheitert der Widerruf bei rotate-token, ist das neue Token trotzdem ausgegeben; der Exit-Code ist dann nicht 0.
Entwicklung
nix develop # Rust 1.96, Build-Werkzeuge, gitleaks
cargo test && cargo clippy --all-targets -- -D warnings
nix build .#e2e # Abnahme in VMs: Synapse, NFSv4.2, zwei Bot-Nodes
nix build .#e2e-verify # nur Cross-Signing, Emoji-Verifizierung und Notfall
Die Abnahme prüft Echo im verschlüsselten Raum, den Neustart ohne neues Gerät, den sauberen Node-Wechsel, den Wächter (zweite Instanz wartet), die Übernahme nach einem harten Absturz, den Brückenmodus mit einem Python-Test-Bot (Antworten, Reaktionen, Edit, Redaktion, Raumverwaltung, Versionsvertrag) sowie Cross-Signing und Emoji-Verifizierung und den Notfall-Zugang: Rotation (altes Token abgewiesen), Wiederherstellung nach Store-Verlust (Bot bleibt verifiziert), neue Identität mit erneuter Verifizierung.
Lizenz
MIT, siehe LICENSE.