Chat Message – Concept

Status: CONCEPT · Erstellt April 2026 Übergeordnet: TOOL_chat_roadmap.md Verwandt: TOOL_chat_concept-peer-sync.md

Warum ein eigenes Konzept?

Die Message-Struktur ist die Grundlage für alles – Rendering, Sync, Export, Backup-Import und Migration. Dieses Konzept legt fest wie eine Nachricht aufgebaut ist, wie sie dargestellt wird, wie gelöschte Nachrichten behandelt werden, und wie alte Formate abwärtskompatibel migriert werden.

Message Format (v1)

1
{
2
  id:         String,   // UUID v4 – eindeutig, client-seitig generiert beim Senden
3
  senderId:   String,   // Peer-ID des Absenders
4
  receiverId: String,   // Peer-ID des Empfängers
5
  sentAt:     Number,   // Unix ms – gesetzt beim Senden
6
  editedAt:   Number,   // Unix ms – gesetzt beim Bearbeiten; null wenn nie bearbeitet
7
  type:       String,   // 'text' | erweiterbar: 'image', 'system', ...
8
  content:    String,   // Nachrichteninhalt (lokal im Klartext, über DataChannel E2EE)
9
  v:          Number,   // Message-Format-Version (aktuell: 1)
10
  meta: {
11
    receivedAt: Number, // Unix ms – gesetzt beim Empfang; null wenn noch nicht empfangen
12
    viewedAt:   Number, // Unix ms – gesetzt wenn Empfänger die Nachricht gesehen hat; null wenn ungesehen
13
    signature:  String, // Base64 – Ed25519 Signatur des Senders; null bei migrierten v0 Messages
14
    // erweiterbar
15
  }
16
}

Warum UUID v4? Eindeutig ohne Server, kein Koordinationsaufwand, kein Kollisionsrisiko.

Warum v? Ermöglicht spätere Migration beim Lesen aus localStorage, Backup-Import oder Peer-Sync – ohne dass alte Clients brechen.

Warum editedAt außerhalb von meta? Der Comparator braucht editedAt direkt um zu entscheiden ob eine eingehende Message neuer ist als die lokale. receivedAt, viewedAt und signature sind UI/Tracking/Crypto-Werte ohne direkte Sync-Relevanz – sie gehören in meta.

Hinweis zu signature: Migrierte v0 Messages haben keine Signatur – signature: null ist akzeptiert. Neue Messages ab v1.11.0 sind immer signiert. → Details: TOOL_chat_concept-crypto.md

Hinweis zu content: Lokal in localStorage liegt content im Klartext. At-rest Encryption via @xpulse/crypto ist eine mögliche zukünftige Erweiterung – bewusst offen gelassen.

Edit- und Lösch-Zeitbegrenzung

Bearbeiten und „Für alle löschen" ist nur innerhalb eines konfigurierbaren Zeitfensters ab sentAt möglich. Nach Ablauf sind diese Aktionen gesperrt. Konkrete Dauer: TBD (Referenz: WhatsApp 60h, Telegram 48h).

UI-Darstellung

Graveyard

Gelöschte Nachrichten werden nicht einfach entfernt – sie hinterlassen einen Grabstein. Der Graveyard hat zwei Aufgaben:

1. UI – beim Rendern: ID im Graveyard → ausgegraut „Nachricht gelöscht" anzeigen
2. Sync – verhindert dass gelöschte Nachrichten beim Sync wiederhergestellt werden

localStorage Key

1
xp_graveyard_{chatId}

Format

1
{
2
  [messageId]: deletedAt,   // Unix ms
3
  [messageId]: deletedAt,
4
  ...
5
}

Lösch-Modi

„Für mich löschen" → Message aus localStorage entfernen, ID in lokalen Graveyard → Kein Sync an Peer → Peer hat die Message noch → wiederherstellbar über Peer History ✅

„Für alle löschen" → Message aus localStorage entfernen, ID in lokalen Graveyard → sync:delete Event an Peer schicken (sofort wenn online, sonst gepuffert) → Peer legt ID ebenfalls in seinen Graveyard → Wiederherstellung nicht möglich ❌ – beide Seiten haben den Grabstein → Best-effort: wenn Peer offline ist und die Queue noch nicht abgearbeitet wurde, könnte er die Message theoretisch noch sehen – technisch nicht vermeidbar

Zeitbegrenzung: „Für alle löschen" ist nur innerhalb des konfigurierten Zeitfensters ab sentAt möglich (gleiche Grenze wie Edit).

Pending Delete Queue

Wenn der Peer beim „Für alle löschen" offline ist:

1
xp_pending_delete_{chatId}: [
2
  { id: messageId, requestedAt: timestamp },
3
  ...
4
]

Beim nächsten Connect: Queue abarbeiten → sync:delete schicken → Queue leeren. Ist requestedAt außerhalb des Zeitlimits → still aus Queue entfernen, Peer behält die Message.

Wiederherstellung

Wenn der Peer online ist und Nachrichten hat die im lokalen Graveyard stehen (nur „für mich gelöscht"), kann der User aktiv entscheiden diese wiederherzustellen. Im Chat Info Panel wird angezeigt wie viele Nachrichten wiederherstellbar wären – nur sichtbar wenn Peer online ist.

Wiederherstellung = betroffene IDs aus dem Graveyard entfernen → beim nächsten sync() werden sie normal gemergt.

Nicht wiederherstellbar: Messages die mit „Für alle löschen" entfernt wurden – der Peer hat den Grabstein ebenfalls, Sync ignoriert sie auf beiden Seiten.

Graveyard wächst unbegrenzt – UUIDs + Timestamps sind klein, kein Cleanup nötig.

Migration – Abwärtskompatibilität

Altes Message Format v0 (vor v1.11.0)

1
// localStorage: chats[chatId][n]
2
{ ts, text, mine }

Mapping v0 → v1

migrateV0() – im Converter

migrateV0() lebt im ChatConverter – nicht im localStorage-Layer. Der Converter ist der universelle Eingangs-Normalizer: egal woher die Daten kommen (localStorage, Backup-Import, Peer-Sync), raus kommt immer sauberes v1. Der Rest der Pipeline bekommt nie eine v0 Message zu sehen.

1
localStorage laden  →  ChatConverter → migrateV0() wenn nötig
2
Backup importieren  →  ChatConverter → migrateV0() wenn nötig
3
Sync empfangen      →  ChatConverter → migrateV0() wenn nötig

Fehlendes v oder v === 0 → Migration:

1
function migrateV0(msg, ownId, peerId) {
2
  return {
3
    id:         crypto.randomUUID(),
4
    senderId:   msg.mine ? ownId : peerId,
5
    receiverId: msg.mine ? peerId : ownId,
6
    sentAt:     msg.ts,
7
    editedAt:   null,
8
    type:       'text',
9
    content:    msg.text,
10
    v:          1,
11
    meta: {
12
      receivedAt: msg.ts,
13
      viewedAt:   null
14
    }
15
  };
16
}

Die migrierten Messages werden direkt nach dem Laden zurück in localStorage geschrieben – Migration wird nur einmalig durchgeführt.

Comparator – Fallback für migrierte Messages

Da beim Migrieren neue UUIDs generiert werden, haben beide Peers nach der Migration unterschiedliche IDs für dieselben Nachrichten. Ein reiner ID-Vergleich würde migrierte Messages als „neu" behandeln und doppelt einfügen.

Daher: Fallback-Vergleich via content + sentAt für Messages ohne gemeinsame ID-Basis:

1
Message kommt rein →
2
  v === 1, ID-Match lokal        → normaler ID-Vergleich (Graveyard, Duplikat, Merge)
3
  v === 1, kein lokaler ID-Match →
4
    Fallback: content + sentAt vergleichen
5
    Match gefunden  → Duplikat; lokale Message mit eingehender ID aktualisieren
6
    Kein Match      → mergen

Nach der ersten erfolgreichen Sync-Runde sind alle Messages auf beiden Seiten mit echten UUIDs versehen – der Fallback greift danach nicht mehr. Der Übergangsmechanismus ist einmalig und selbstheilend.

Offene Punkte