Ende-zu-Ende, Anfang bis Ende 🔐🤖
  • Rust 66.8%
  • Nix 22.7%
  • Python 9.9%
  • Dockerfile 0.6%
Find a file
2026-11-16 13:48:53 +01:00
docs feat: Brücke mit Medien — Avatar, Bilder empfangen und senden 2026-11-16 13:13:05 +01:00
e2e feat: Brücke mit Medien — Avatar, Bilder empfangen und senden 2026-11-16 13:13:05 +01:00
examples feat: Brücke mit Medien — Avatar, Bilder empfangen und senden 2026-11-16 13:13:05 +01:00
messung/sqlite-nfs test(messung): SQLite (WAL) auf NFSv4.2 als NixOS-VM-Test 2026-11-15 19:15:58 +01:00
src feat: Brücke mit Medien — Avatar, Bilder empfangen und senden 2026-11-16 13:13:05 +01:00
.env.example feat: Brücke mit Medien — Avatar, Bilder empfangen und senden 2026-11-16 13:13:05 +01:00
.gitignore Merge branch 'feat/12-raumverwaltung' into dev 2026-11-16 11:06:24 +01:00
Cargo.lock chore: Version 0.4.0, pemmikan 2026-11-16 13:48:51 +01:00
Cargo.toml chore: Version 0.4.0, pemmikan 2026-11-16 13:48:51 +01:00
CHANGELOG.md chore(release): v0.4.0 2026-11-16 13:48:51 +01:00
CLAUDE.md docs: pemmikan, README (Brückenmodus, Verifizierung), cliff.toml, CLAUDE.md-Stub 2026-11-16 00:35:01 +01:00
cliff.toml docs: pemmikan, README (Brückenmodus, Verifizierung), cliff.toml, CLAUDE.md-Stub 2026-11-16 00:35:01 +01:00
compose.example.yml feat: Gerüst botkern mit Store-Wächter, Echo-Modul und VM-Abnahme 2026-11-15 20:18:53 +01:00
Dockerfile feat: Gerüst botkern mit Store-Wächter, Echo-Modul und VM-Abnahme 2026-11-15 20:18:53 +01:00
flake.lock feat: Gerüst botkern mit Store-Wächter, Echo-Modul und VM-Abnahme 2026-11-15 20:18:53 +01:00
flake.nix chore: Version 0.4.0, pemmikan 2026-11-16 13:48:51 +01:00
LICENSE docs: Lizenz MIT 2026-11-15 20:23:21 +01:00
pemmikan.md chore: Version 0.4.0, pemmikan 2026-11-16 13:48:51 +01:00
README.md feat: Kern antwortet auf ping mit pong, immer und überall 2026-11-16 12:13:12 +01:00

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; !echo ist 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.lock im 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 in messung/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_USERS legt 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 mit pong, in jedem Raum und in beiden Betriebsarten.
  • Verifizierung: botkern cross-signing richtet 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

  1. 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>
    
  2. Umgebung nach .env.example zur Laufzeit befüllen und botkern run starten. Container: nix build .#image (oder Dockerfile), Beispiel in compose.example.yml.
  3. Einmalig mit gestopptem Bot botkern cross-signing ausführen, das Passwort nur zur Laufzeit in MATRIX_PASSWORD. Danach lässt sich der Bot in Element verifizieren.
  4. Direkt danach, ebenfalls bei gestopptem Bot, den Wiederherstellungsschlüssel anlegen und getrennt vom Store aufbewahren: botkern recovery-key | <secret-store-insert>.
  5. 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.