diff --git a/docs/README.md b/docs/README.md index 7f6809b..20d7809 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,3 +5,4 @@ Diese Dokumentation unterstützt dich bei der täglichen Nutzung von FEDEO. ## Einstieg - [Bedienung](./bedienung/README.md) +- [Kommunikationslösung auf Basis des Matrix-Standards](./kommunikationslösung-matrix.md) diff --git a/docs/kommunikationslösung-matrix.md b/docs/kommunikationslösung-matrix.md new file mode 100644 index 0000000..682c779 --- /dev/null +++ b/docs/kommunikationslösung-matrix.md @@ -0,0 +1,371 @@ +# Kommunikationslösung auf Basis des Matrix-Standards + +Dieser Entwurf beschreibt eine FEDEO-Kommunikationslösung für Chat, Anrufe und Videokonferenzen auf Basis des Matrix-Standards. Ziel ist eine souverän betreibbare Lösung, die Mandantenfähigkeit, Datenschutz, Rechteverwaltung und die bestehenden FEDEO-Workflows berücksichtigt. + +## Zielbild + +FEDEO erhält einen integrierten Kommunikationsbereich, der interne Zusammenarbeit und externe Kommunikation abdeckt: + +- Chat in Einzel-, Gruppen-, Projekt-, Vorgangs- und Kundenräumen +- Audioanrufe aus Direktchats, Gruppenräumen und Kontakten +- Videokonferenzen mit Bildschirmfreigabe und Einladungslinks +- Ende-zu-Ende-verschlüsselte private Kommunikation +- revisionsfähige Verknüpfung von relevanten Kommunikationsereignissen mit FEDEO-Objekten +- optional föderierte Kommunikation mit externen Matrix-Organisationen + +Matrix wird dabei nicht als isolierter Messenger betrieben, sondern als Kommunikationsschicht neben dem bestehenden FEDEO-Backend. + +## Empfohlene Architektur + +```text +Nutzerinnen und Nutzer + | + | FEDEO Web, Mobile App, optional Element Desktop/Mobile + v +FEDEO Frontend + | + | FEDEO API, SSO, Rechte, Objektkontext + v +FEDEO Backend + | + | Provisionierung, Webhooks, Audit-Metadaten + v +Matrix Homeserver + | + +-- PostgreSQL für Matrix-Daten + +-- Redis für Worker und Caches + +-- Medien-Repository für Anhänge + +-- TURN/STUN für direkte Medienverbindungen + +-- MatrixRTC / LiveKit SFU für Gruppenanrufe und Videokonferenzen +``` + +### Kernkomponenten + +| Komponente | Empfehlung | Aufgabe | +| --- | --- | --- | +| Matrix Homeserver | Synapse | Standardnaher, bewährter Homeserver mit guter Betriebsdokumentation | +| Matrix Client im FEDEO Web | Matrix JS SDK oder eingebetteter Element-Web-Ausschnitt | Chat, Raumliste, Nachrichten, Reaktionen, Anhänge | +| Mobile Integration | Matrix SDK über FEDEO Mobile oder Deep Link zu Element X | Pushfähige mobile Kommunikation | +| Identität | OIDC/SSO über FEDEO Auth, perspektivisch Matrix Authentication Service | Einheitlicher Login und zentrale Nutzerverwaltung | +| Audio/Video | MatrixRTC mit Element Call und LiveKit SFU | Moderne Anrufe und Videokonferenzen | +| NAT Traversal | coturn | STUN/TURN für stabile Medienverbindungen | +| Reverse Proxy | bestehender Traefik-Ansatz | TLS, Routing, `.well-known/matrix/*` | +| Administration | FEDEO Admin-Oberfläche plus Synapse Admin API | Nutzer, Räume, Richtlinien, Sperren | + +## Betriebsmodell + +Für FEDEO ist ein eigener Matrix-Homeserver pro Installation oder pro großer Betreiberinstanz sinnvoll. Der Matrix-Server sollte nicht öffentlich als offener Registrierungsserver betrieben werden. Nutzer werden ausschließlich durch FEDEO angelegt, aktualisiert und deaktiviert. + +Empfohlene Domains: + +- `app.example.com`: FEDEO Oberfläche +- `matrix.example.com`: Matrix Client-Server und Federation API +- `call.example.com`: Element Call / MatrixRTC +- `livekit.example.com`: LiveKit SFU +- `turn.example.com`: TURN/STUN + +Die öffentliche Matrix-Serverkennung kann trotzdem `example.com` lauten. Dafür werden `.well-known/matrix/client` und `.well-known/matrix/server` über Traefik ausgeliefert. + +## Mandantenmodell + +Matrix selbst ist raumbasiert, FEDEO ist mandantenbasiert. Deshalb sollte FEDEO die Mandantenlogik explizit auf Matrix-Räume und Spaces abbilden. + +### Räume und Spaces + +- Pro FEDEO-Mandant wird ein Matrix Space angelegt. +- Projekte, Vorgänge, Helpdesk-Konversationen, interne Teams und Kundenkontakte werden als Räume im Mandanten-Space geführt. +- Direkträume werden nutzerbezogen angelegt, aber über FEDEO mandantengebunden sichtbar gemacht. +- Externe Räume erhalten einen klaren Status, zum Beispiel `intern`, `extern`, `kunde`, `lieferant`. + +### Raumalias-Konvention + +Beispiele: + +- `#tenant--team:example.com` +- `#tenant--project-:example.com` +- `#tenant--ticket-:example.com` +- `#tenant--customer-:example.com` + +Interne technische IDs sollten nicht als sichtbarer Anzeigename genutzt werden. Nutzerinnen und Nutzer sehen sprechende Namen wie `Projekt: Website Relaunch` oder `Kunde: Muster GmbH`. + +## Rechte und Rollen + +FEDEO bleibt führend für Berechtigungen. Matrix übernimmt die technische Durchsetzung im Raum. + +| FEDEO-Rolle | Matrix-Abbildung | +| --- | --- | +| Mandantenadmin | Space-Admin und Raumadmin | +| Teamleitung | Moderatorin oder Moderator in Team- und Projekträumen | +| Mitarbeitende | Mitglied mit Schreibrechten | +| Externe Kontakte | Eingeschränkte Mitgliedschaft in ausgewählten Räumen | +| Automationen | Application-Service- oder Bot-Nutzer mit minimalen Rechten | + +Änderungen an Rollen, Teams oder Mandantenzugehörigkeiten lösen im FEDEO-Backend eine Synchronisation mit Matrix aus. Beim Entzug eines Zugriffs wird die Person aus den betroffenen Räumen entfernt. Bei Ende-zu-Ende-verschlüsselten Räumen muss zusätzlich berücksichtigt werden, dass bereits erhaltene Nachrichten auf Geräten verbleiben können. + +## Chat + +Der Chat wird als erste Ausbaustufe umgesetzt. + +### Funktionen + +- Direktnachrichten +- Gruppenräume +- Mandanten-, Team-, Projekt- und Vorgangsräume +- Datei- und Bildanhänge +- Erwähnungen, Reaktionen und Lesestatus +- Suche in nicht verschlüsselten Räumen über den Homeserver +- lokale Suche in verschlüsselten Räumen über Client-Indizes +- Verknüpfung von Nachrichten mit FEDEO-Objekten + +### Integration in FEDEO + +FEDEO sollte keine vollständige Kopie aller Nachrichten in der eigenen Datenbank speichern. Stattdessen speichert FEDEO nur Referenzen: + +- Matrix Raum-ID +- Matrix Event-ID +- FEDEO Objekt-Typ und Objekt-ID +- Zeitstempel +- beteiligter FEDEO-Nutzer +- optionale Vorschau, falls Datenschutzrichtlinie dies erlaubt + +So bleibt Matrix das Kommunikationssystem, während FEDEO nachvollziehen kann, welche Kommunikation zu welchem Objekt gehört. + +## Audioanrufe + +Einzelanrufe können direkt über Matrix-VoIP in Direktchats gestartet werden. Der FEDEO-Client zeigt dafür in Kontakt-, Kunden-, Mitarbeitenden- und Chatansichten einen Anruf-Button. + +### Anforderungen + +- WebRTC-Unterstützung im Browser +- STUN/TURN über coturn +- Geräteauswahl für Mikrofon und Lautsprecher +- Anrufbenachrichtigung im Web und mobil +- Statusanzeige `verfügbar`, `beschäftigt`, `im Anruf`, `abwesend` + +Für klassische Telefonie kann später ein SIP-Gateway ergänzt werden. Das sollte jedoch getrennt von der ersten Matrix-Einführung betrachtet werden, damit Chat und WebRTC-Kommunikation nicht durch Telefoniekomplexität ausgebremst werden. + +## Videokonferenzen + +Für Gruppenanrufe und Videokonferenzen wird MatrixRTC mit Element Call und LiveKit empfohlen. Matrix übernimmt dabei Raumzustand, Identität, Berechtigungen und Signalisierung; LiveKit übernimmt als SFU die effiziente Medienverteilung. + +### Funktionen + +- Videokonferenzen aus Matrix-Räumen +- spontane Besprechungen aus Projekten, Vorgängen oder Kundenakten +- Bildschirmfreigabe +- Einladungslink für externe Gäste +- Wartebereich für externe Gäste +- Moderationsrechte für Stummschalten, Entfernen und Raumverwaltung +- optionale Aufzeichnung erst in einer späteren, gesondert freizugebenden Ausbaustufe + +### Konfiguration + +Clients finden den MatrixRTC-Dienst über `.well-known/matrix/client`. Dort wird der LiveKit-JWT-Dienst als `org.matrix.msc4143.rtc_foci` angekündigt. Diese Datei muss öffentlich lesbar sein, als JSON ausgeliefert werden und CORS für Webclients erlauben. + +Beispiel: + +```json +{ + "m.homeserver": { + "base_url": "https://matrix.example.com" + }, + "org.matrix.msc4143.rtc_foci": [ + { + "type": "livekit", + "livekit_service_url": "https://call.example.com/livekit/jwt" + } + ] +} +``` + +## Authentifizierung und Nutzerverwaltung + +FEDEO sollte Identität und Lebenszyklus der Nutzer zentral steuern. + +### Empfohlener Ablauf + +1. Nutzer wird in FEDEO angelegt. +2. FEDEO erzeugt oder aktualisiert den Matrix-Nutzer. +3. FEDEO weist den Nutzer den passenden Spaces und Räumen zu. +4. Login erfolgt über FEDEO SSO/OIDC. +5. Deaktivierung in FEDEO deaktiviert auch den Matrix-Zugang und entfernt Raumzugriffe. + +Die Matrix User-ID sollte stabil und nicht personenbezogen änderungsanfällig sein: + +```text +@u_:example.com +``` + +Der Anzeigename kann weiterhin den echten Namen enthalten und bei Änderungen synchronisiert werden. + +## Datenschutz und Compliance + +Matrix erlaubt starke Datenschutzkonzepte, erfordert aber klare Betriebsregeln. + +### Empfehlungen + +- Ende-zu-Ende-Verschlüsselung für Direktnachrichten und vertrauliche Projekträume aktivieren. +- Nicht verschlüsselte Räume nur dort nutzen, wo serverseitige Suche, Archivierung oder Compliance-Funktionen ausdrücklich benötigt werden. +- Medienaufbewahrung mandantenweit konfigurierbar machen. +- Externe Gäste optisch klar kennzeichnen. +- Federation standardmäßig deaktivieren oder auf erlaubte Domains beschränken. +- Aufzeichnungen von Videokonferenzen nur mit expliziter Einwilligung und sichtbarem Status erlauben. +- Administrative Zugriffe protokollieren. +- Klare Löschfristen für Räume, Anhänge und Audit-Referenzen definieren. + +## Federation + +Matrix kann mit anderen Homeservern föderieren. Für FEDEO sollte Federation als kontrollierbare Option umgesetzt werden. + +### Betriebsmodi + +| Modus | Beschreibung | Empfehlung | +| --- | --- | --- | +| geschlossen | Keine Federation, nur interne Nutzer und explizite Gäste | Standard für kleine Installationen | +| allowlist | Federation nur mit freigegebenen Domains | Empfehlung für B2B-Kommunikation | +| offen | Federation mit beliebigen Matrix-Servern | Nur für bewusst öffentliche Communities | + +Für steuer-, kunden- und projektnahe Kommunikation ist `allowlist` der beste Zielmodus. + +## Brücken zu anderen Systemen + +Matrix unterstützt Brücken zu anderen Kommunikationsdiensten. Für FEDEO sind Brücken nützlich, sollten aber nicht zur ersten Produktstufe gehören. + +Mögliche spätere Erweiterungen: + +- E-Mail-Brücke für Helpdesk- oder Kundenkommunikation +- Slack- oder Teams-Brücke für externe Projektpartner +- WhatsApp- oder SMS-Brücke nur nach gesonderter Datenschutzprüfung +- SIP-Brücke für Telefonie + +Brücken müssen pro Mandant aktivierbar sein und brauchen klare Hinweise, welche Daten an externe Dienste fließen. + +## FEDEO-Produktoberfläche + +Die Kommunikation sollte in FEDEO an zwei Stellen sichtbar sein. + +### Globaler Kommunikationsbereich + +- Raumliste +- Direktnachrichten +- Suche +- Anrufe +- laufende Besprechungen +- Benachrichtigungen + +### Objektbezogene Kommunikation + +In Projekten, Kunden, Vorgängen, Helpdesk-Tickets und Dokumenten erscheint ein Kommunikations-Tab: + +- zugeordneter Raum +- relevante Nachrichtenreferenzen +- Start von Chat, Anruf oder Besprechung +- Teilnehmerverwaltung entsprechend FEDEO-Rechten + +So bleibt Kommunikation dort, wo die Arbeit stattfindet. + +## Backend-Integration + +Das FEDEO-Backend erhält ein Kommunikationsmodul mit folgenden Aufgaben: + +- Matrix-Nutzer provisionieren +- Spaces und Räume anlegen +- Raum-Mitgliedschaften synchronisieren +- Matrix-Event-Webhooks empfangen +- FEDEO-Objekte mit Matrix-Räumen verknüpfen +- Benachrichtigungseinstellungen verwalten +- Admin-Aktionen auditieren + +Technisch kann dies über Matrix Admin API, Client-Server API und Application Services erfolgen. Für Automationen empfiehlt sich ein eigener Application Service, weil er reservierte Nutzer- und Raum-Namensräume sauber verwalten kann. + +## Deployment-Erweiterung + +Der bestehende Docker-/Traefik-Ansatz kann um folgende Dienste erweitert werden: + +- `matrix-synapse` +- `matrix-db` oder gemeinsame PostgreSQL-Instanz mit getrennter Datenbank +- `redis` +- `coturn` +- `element-web` optional als Fallback-Client +- `element-call` +- `livekit` +- `matrix-rtc-jwt-service` + +Für produktive Installationen sollte Matrix eine eigene PostgreSQL-Datenbank erhalten. Medien sollten in S3-kompatiblen Speicher ausgelagert werden, damit große Anhänge und Konferenzartefakte nicht den Applikationsserver füllen. + +## Monitoring + +Wichtige Kennzahlen: + +- aktive Nutzerinnen und Nutzer +- Anzahl Räume pro Mandant +- Nachrichtenrate +- Medien-Speicherverbrauch +- Zustellverzögerung +- fehlgeschlagene Anrufe +- LiveKit Paketverlust, Latenz und Teilnehmerzahl +- TURN-Nutzung +- Federation-Fehler + +Logs von FEDEO, Synapse, LiveKit, coturn und Traefik sollten über eine gemeinsame Korrelation, zum Beispiel Request-ID oder Nutzer-ID, untersuchbar sein. + +## Risiken und Gegenmaßnahmen + +| Risiko | Gegenmaßnahme | +| --- | --- | +| Komplexität durch zwei Systeme | FEDEO bleibt führend für Nutzer, Rechte und Objektbezug | +| Datenschutz bei externen Räumen | Externe Kennzeichnung, Federation-Allowlist, Mandantenrichtlinien | +| E2EE erschwert Suche und Archivierung | Raumtyp bewusst wählen, lokale Suche, Metadatenreferenzen statt Vollkopie | +| Medienverbindungen scheitern in Firmennetzen | coturn sauber betreiben, UDP und TCP/TLS-Fallback anbieten | +| Betriebskosten durch Video | LiveKit skalierbar betreiben, Limits pro Mandant definieren | +| Gästezugriff wird unübersichtlich | Einladungslinks mit Ablaufdatum, Wartebereich, Moderationsrechte | + +## Umsetzung in Phasen + +### Phase 1: Fundament und Chat + +- Synapse mit PostgreSQL, Redis, Traefik und `.well-known` betreiben +- FEDEO-Nutzer zu Matrix synchronisieren +- Mandanten-Spaces und erste Teamräume anlegen +- Chat im FEDEO-Frontend integrieren +- Benachrichtigungen und Raumreferenzen speichern + +### Phase 2: Objektbezogene Kommunikation + +- Räume automatisch für Projekte, Vorgänge und Kunden anlegen +- Kommunikations-Tab in FEDEO-Objekten ergänzen +- Rechteänderungen aus FEDEO nach Matrix synchronisieren +- externe Gäste einladen und kennzeichnen + +### Phase 3: Audio und Video + +- coturn bereitstellen +- MatrixRTC, Element Call und LiveKit integrieren +- Anruf- und Videobuttons in Chat, Kontakten und Projekten ergänzen +- Gäste-Links und Wartebereich umsetzen + +### Phase 4: Compliance und Skalierung + +- Aufbewahrungsrichtlinien pro Mandant +- Monitoring und Admin-Dashboards +- Federation-Allowlist +- optionale Brücken +- optionale Aufzeichnung mit Einwilligungsworkflow + +## Offene Entscheidungen + +- Soll Federation initial deaktiviert oder direkt mit Allowlist ausgeliefert werden? +- Welche Räume müssen serverseitig durchsuchbar sein und bleiben deshalb unverschlüsselt? +- Sollen externe Gäste Matrix-Konten erhalten oder nur temporäre Konferenzzugänge? +- Wird Element als sichtbarer Fallback-Client angeboten oder soll alles primär in FEDEO stattfinden? +- Welche Mandantenlimits gelten für Speicher, Teilnehmerzahl und Videodauer? + +## Quellen und Standards + +- Matrix Specification: https://spec.matrix.org/ +- Matrix Application Services: https://matrix.org/docs/older/application-services/ +- Matrix Bridges: https://www.matrix.org/docs/communities/bridging/ +- Synapse Worker-Dokumentation: https://matrix-org.github.io/synapse/develop/workers.html +- Element Call Self-Hosting: https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md +- Element MatrixRTC Konfiguration: https://docs.element.io/latest/element-server-suite-pro/configuring-components/configuring-matrix-rtc/ +- LiveKit Self-Hosting: https://docs.livekit.io/transport/self-hosting/