Chat Crypto – Concept

Status: CONCEPT · Erstellt April 2026 Übergeordnet: TOOL_chat_roadmap.md Verwandt: TOOL_chat_concept-identity.md, TOOL_chat_concept-device.md Verwandt: TOOL_chat_concept-message.md, @xpulse/crypto

Grundsätze

Privacy First – kein Server sieht jemals Nachrichteninhalte. Vertrauen durch Verifikation – nicht durch Versprechen. Transparenz – was der Peer sieht ist dokumentiert und bewusst entschieden.

Warum ein eigenes Konzept?

Kryptographie zieht sich durch alle Teile von xPulse Chat – Identität, Nachrichten, Devices, Sync. Dieses Konzept legt fest:

Welche Schlüssel es gibt und wofür
Was der Peer sieht und was nicht
Wie Nachrichten verschlüsselt und signiert werden
Wie Verifikation funktioniert

Schlüssel-Übersicht

1 Pro User:
2   userId          = SHA-256(userPublicKey)   – öffentlich, stabil
3   userPublicKey   = öffentlich – Peers kennen ihn
4   userPrivateKey  = geheim – verlässt nie das Gerät
5  
6 Pro Gerät:
7   clientId        = SHA-256(clientPublicKey) – öffentlich, gerätegebunden
8   clientPublicKey = öffentlich – Peers kennen ihn
9   clientPrivateKey = geheim – verlässt nie das Gerät

Was der Peer sieht

1 Peer sieht:       userId          → wer du bist
2                   userPublicKey   → zum Verifizieren deiner Nachrichten
3  
4 Peer sieht NICHT: clientId        → welches Gerät
5                   clientPublicKey → Geräte-Detail
6                   privateKeys     → niemals
7                   Anzahl Geräte   → intern

Der userPublicKey ist by Design öffentlich – genau wie bei SSH. Jeder mit dem du chattest kennt ihn. Das ist gewollt und notwendig für E2EE Verifikation.

Nachrichten-Verschlüsselung (E2EE)

Nachrichten werden Ende-zu-Ende verschlüsselt über den WebRTC DataChannel.

1 Sender →
2   Nachricht mit AES-GCM verschlüsseln
3   Schlüssel = ECDH(senderPrivateKey, receiverPublicKey)
4   → verschlüsselte Nachricht über DataChannel
5  
6 Empfänger →
7   Schlüssel = ECDH(receiverPrivateKey, senderPublicKey)
8   → entschlüsseln → Klartext

Kein Server sieht jemals den Inhalt – die Verschlüsselung passiert ausschließlich zwischen den zwei Peers.

Message-Signing

Jede Nachricht wird mit dem userPrivateKey des Senders signiert. Der Empfänger verifiziert mit dem userPublicKey des Senders.

1 Sender →
2   Nachricht erstellen
3   Signatur = sign(message, userPrivateKey)
4   → { ...message, signature } über DataChannel
5  
6 Empfänger →
7   verify(message, signature, senderPublicKey)
8   OK  → Nachricht ist authentisch ✅
9   NOK → Nachricht verwerfen ❌

Was Message-Signing verhindert:

Niemand kann Nachrichten fälschen – nicht mal ein Man-in-the-Middle
Nachträglich veränderte Nachrichten werden erkannt
Beim Sync: importierte Messages können auf Echtheit geprüft werden

signature in der Message-Struktur:

1 meta: {
2   receivedAt: Number,
3   viewedAt:   Number,
4   signature:  String,   // Base64 – Signatur der Nachricht
5 }

Verifikation beim Sync

Beim Sync kommen Messages vom Peer – der Comparator prüft die Signatur bevor eine Message gemergt wird:

1 Message kommt rein →
2   signature vorhanden? →
3     verify(message, signature, senderPublicKey) →
4       OK  → normal weiter (Graveyard, Duplikat, Merge)
5       NOK → Message verwerfen, warn loggen
6   keine signature (v0 migriert) →
7     akzeptieren – Migration hat keine Signaturen

Schlüssel-Austausch beim Pairing

Beim Chat-Pairing und Device-Pairing tauschen beide Peers ihre userPublicKeys aus:

1 Pairing →
2   A sendet userPublicKey → B speichert für A
3   B sendet userPublicKey → A speichert für B
4   → beide können ab jetzt Nachrichten verschlüsseln + verifizieren

Der userPublicKey wird lokal gespeichert:

1 xpulse_chat_{userId}_peer_{peerId}_public_key

localStorage – Crypto Keys

1 // User-Keypair
2 xpulse_identity_{userId}_public_key      ← öffentlich
3 xpulse_identity_{userId}_private_key     ← AES-GCM verschlüsselt mit PBKDF2(pw + salt)
4 xpulse_identity_{userId}_salt            ← Salt für PBKDF2
5  
6 // Client-Keypair
7 xpulse_identity_client_public_key        ← öffentlich
8 xpulse_identity_client_private_key       ← AES-GCM verschlüsselt
9  
10 // Bekannte Peer Public Keys
11 xpulse_chat_{userId}_peer_{peerId}_public_key  ← Peer's userPublicKey

Algorithmen

Zweck	Algorithmus	Hinweis
Keypair Generierung	Ed25519 (Fallback: ECDSA P-256)	Identity + Signing
Schlüsselaustausch	ECDH	Nachrichten-Verschlüsselung
Nachrichten-Verschlüsselung	AES-GCM	via `@xpulse/crypto`
Schlüsselableitung	PBKDF2	Passwort → Encryption Key
Hashing	SHA-256	userId + clientId Ableitung
Signing	Ed25519 (Fallback: ECDSA P-256)	Message-Signatur

Offene Punkte

Thema	Stand
Key-Rotation – Keypair erneuern ohne userId zu ändern	TBD – komplex, später
Peer Public Key Verifikation out-of-band (z.B. QR-Vergleich)	TBD – Nice-to-have

1	Pro User:
2	userId = SHA-256(userPublicKey) – öffentlich, stabil
3	userPublicKey = öffentlich – Peers kennen ihn
4	userPrivateKey = geheim – verlässt nie das Gerät
5
6	Pro Gerät:
7	clientId = SHA-256(clientPublicKey) – öffentlich, gerätegebunden
8	clientPublicKey = öffentlich – Peers kennen ihn
9	clientPrivateKey = geheim – verlässt nie das Gerät

1	Peer sieht: userId → wer du bist
2	userPublicKey → zum Verifizieren deiner Nachrichten
3
4	Peer sieht NICHT: clientId → welches Gerät
5	clientPublicKey → Geräte-Detail
6	privateKeys → niemals
7	Anzahl Geräte → intern

1	Sender →
2	Nachricht mit AES-GCM verschlüsseln
3	Schlüssel = ECDH(senderPrivateKey, receiverPublicKey)
4	→ verschlüsselte Nachricht über DataChannel
5
6	Empfänger →
7	Schlüssel = ECDH(receiverPrivateKey, senderPublicKey)
8	→ entschlüsseln → Klartext

1	Sender →
2	Nachricht erstellen
3	Signatur = sign(message, userPrivateKey)
4	→ { ...message, signature } über DataChannel
5
6	Empfänger →
7	verify(message, signature, senderPublicKey)
8	OK → Nachricht ist authentisch ✅
9	NOK → Nachricht verwerfen ❌

1	meta: {
2	receivedAt: Number,
3	viewedAt: Number,
4	signature: String, // Base64 – Signatur der Nachricht
5	}

1	Message kommt rein →
2	signature vorhanden? →
3	verify(message, signature, senderPublicKey) →
4	OK → normal weiter (Graveyard, Duplikat, Merge)
5	NOK → Message verwerfen, warn loggen
6	keine signature (v0 migriert) →
7	akzeptieren – Migration hat keine Signaturen

1	Pairing →
2	A sendet userPublicKey → B speichert für A
3	B sendet userPublicKey → A speichert für B
4	→ beide können ab jetzt Nachrichten verschlüsseln + verifizieren

1	// User-Keypair
2	xpulse_identity_{userId}_public_key ← öffentlich
3	xpulse_identity_{userId}_private_key ← AES-GCM verschlüsselt mit PBKDF2(pw + salt)
4	xpulse_identity_{userId}_salt ← Salt für PBKDF2
5
6	// Client-Keypair
7	xpulse_identity_client_public_key ← öffentlich
8	xpulse_identity_client_private_key ← AES-GCM verschlüsselt
9
10	// Bekannte Peer Public Keys
11	xpulse_chat_{userId}_peer_{peerId}_public_key ← Peer's userPublicKey