Chat Notifications Implementation Proposal

[AndreaDiazCorreia]

Problem Statement

Push and background notifications currently only work for Mostro-originated events (order updates, timeout detection, cancellations). Chat messages between users (P2P) and between users and admins (disputes) do not generate any notifications — not in background, not in foreground (outside the chat screen), and not via FCM when the app is killed.

Current Architecture

How notifications work today

Mostro daemon → publishes kind 1059 event (p=tradeKey) to relay
                          ↓
Push server monitors relays → matches p tag to registered tradeKey
                          ↓
Sends silent FCM notification (no content, no data to Google)
                          ↓
App wakes → background service fetches from relay
                          ↓
_decryptAndProcessEvent() → mostroUnWrap(tradeKey) → MostroMessage
                          ↓
Local notification displayed with localized text

Three message types and their encryption

Type	Encryption	p tag	Unwrap method	Inner format
Mostro events	NIP-59 full (Rumor→Seal→GiftWrap)	tradeKey.public	mostroUnWrap(tradeKey)	[{action, id, payload}]
P2P chat	NIP-59 simplified (Inner→GiftWrap)	sharedKey.public	p2pUnwrap(sharedKey)	Plain text in kind 1
Admin/dispute chat	NIP-59 full (Rumor→Seal→GiftWrap)	tradeKey.public	mostroUnWrap(tradeKey)	{dm: {action: "send-dm", payload: {text_message}}}

What fails and why

P2P Chat

Layer	Status	Detail
Background subscriptions	OK	SubscriptionType.chat filters with sharedKey.public are transferred to background service
Events arrive	OK	kind 1059 with p=sharedKey.public matches the subscription filter
Background decryption	FAILS	_decryptAndProcessEvent() matches sessions by tradeKey.public == event.recipient — never matches sharedKey.public
Local notification	FAILS	Even if decrypted, pipeline expects MostroMessage JSON array format, not plain text
Push/FCM (app killed)	MISSING	Push server only has tradeKey registered, doesn't know about sharedKey
In-app notification	MISSING	Chat events only processed by ChatRoomNotifier when that screen is open

Admin/Dispute Chat

Layer	Status	Detail
Background subscriptions	OK	Falls into SubscriptionType.orders filter (same tradeKey.public)
Events arrive	OK	p=tradeKey.public matches the orders subscription
Background decryption	OK	mostroUnWrap(tradeKey) works (same path as Mostro events)
Message parsing	FAILS	Pipeline expects MostroMessage with standard actions, but receives {dm: {...}} format
Push/FCM (app killed)	OK	Push server monitors relays for tradeKey — admin events match
In-app notification	MISSING	Events only processed by DisputeChatNotifier when dispute screen is open

Key Finding: Shared Keys Are Available in Background

The background notification service loads sessions via _loadSessionsFromDatabase(), which:

1. Initializes KeyManager from secure storage
2. Re-derives tradeKey from masterKey + keyIndex
3. Restores peer.publicKey from stored session data
4. Setting session.peer automatically computes sharedKey = ECDH(tradeKey.private, peer.publicKey)

Therefore, sharedKey can be recomputed in the background isolate. This is not a blocker.

Proposed Implementation

Layer 1: Background Notifications (app minimized)

Modify _decryptAndProcessEvent() in background_notification_service.dart to handle all three message types:

Kind 1059 event arrives in background service
    │
    ├─ Step 1: Try match by tradeKey.public (existing path)
    │   ├─ Match found → mostroUnWrap(tradeKey)
    │   │   ├─ Parse as MostroMessage array → Mostro event (existing flow)
    │   │   └─ Parse as {dm: {...}} format → Admin chat message (NEW)
    │   └─ No match → continue
    │
    └─ Step 2: Try match by sharedKey.public (NEW path)
        ├─ Match found → p2pUnwrap(sharedKey) → P2P chat message (NEW)
        └─ No match → discard event

Notification display:

• Privacy-first: Show "New message in your trade" without revealing content
• Optional preview: Could be a user setting to show message preview (future)
• Localized templates for all three languages (en, es, it)

Files to modify

• lib/features/notifications/services/background_notification_service.dart — add sharedKey matching + p2pUnwrap path + DM format detection
• lib/features/notifications/utils/notification_data_extractor.dart — add chat message extraction (P2P and admin DM)
• lib/features/notifications/utils/notification_message_mapper.dart — add/verify chat notification templates
• lib/l10n/intl_*.arb — add localization keys if needed

Layer 2: In-App Notifications (foreground, outside chat screen)

When the user is in the app but not viewing the specific chat screen, show a toast/badge notification.

Approach: In the SubscriptionManager event processing, when a chat event arrives:

1. Check if the corresponding ChatRoomNotifier for that order is active
2. If NOT active → trigger in-app notification via NotificationsNotifier
3. If active → do nothing (chat screen handles it directly)

This avoids duplicate processing and leverages the existing temporary notification system (showTemporary()).

Files to modify

• lib/features/subscriptions/subscription_manager.dart — add chat event notification logic
• lib/features/notifications/notifiers/notifications_notifier.dart — may need new methods for chat notifications

Layer 3: Push/FCM (app killed or suspended)

P2P Chat: Sender-triggered notification

When User A sends a chat message to User B:

1. Publish encrypted event to relay (existing)
2. Call push server: POST /api/notify {trade_pubkey: peer.publicKey} (NEW)

This works because:

• User A already knows session.peer.publicKey (the counterparty's trade pubkey)
• The push server already has User B's tradeKey → FCM token mapping
• No new data is revealed to the push server — it already knows the trade pubkey
• No message content is transmitted — it's just a "wake up" signal
• The push server doesn't learn any relationship between User A and User B

Why this is better than registering sharedKey:

• No additional pubkey registration needed
• Push server doesn't learn the sharedKey ↔ tradeKey relationship
• Simpler server-side implementation (just a notify endpoint)
• Same privacy guarantees as existing Mostro event notifications

Admin/Dispute Chat: Already works

Admin events already use tradeKey.public as the p tag. Since the push server monitors relays for registered trade pubkeys, these events should already trigger FCM wake-ups. The only gap is Layer 1 (background notification processing), which is addressed above.

Push server changes needed

New endpoint:

POST /api/notify
{
  "trade_pubkey": "<64-char hex>"  // The recipient's trade pubkey
}

Response: 200 OK (notification queued) or 404 (pubkey not registered)

This endpoint simply sends a silent FCM notification to the device registered for that trade pubkey. No content, no metadata beyond what the server already has.

Files to modify

• lib/services/push_notification_service.dart — add notifyPeer(String tradePubkey) method
• lib/features/chat/notifiers/chat_room_notifier.dart — call notifyPeer() after publishing message
• lib/features/disputes/notifiers/dispute_chat_notifier.dart — call notifyPeer() after publishing message (if admin push isn't already handled by relay monitoring)
• Push server — add /api/notify endpoint

Implementation Order

1. Layer 1 (Background) — Highest impact. Users already have the app minimized during trades. Subscriptions and events already work; only the notification processing pipeline needs changes.

2. Layer 2 (In-app) — Medium impact. Improves UX when navigating away from chat during an active trade.

3. Layer 3 (Push/FCM) — Requires server-side changes. Important for when the app is completely killed, but Layer 1 covers the common "app minimized" case.

Privacy Considerations

• No message content ever leaves the device unencrypted
• FCM only receives empty/silent notifications (no data payload)
• Push server only knows tradeKey → device token mapping (already existing)
• The /api/notify endpoint doesn't reveal sender identity to the push server
• Shared keys are never registered or transmitted to any server
• All decryption happens locally on-device
• Compatible with future Phase 5 encrypted token registration (ECDH + ChaCha20-Poly1305)

Open Questions

1. Notification content: Should chat notifications show a message preview or just "New message in your trade"? Privacy vs UX tradeoff (could be a user setting).
2. Rate limiting: Should the /api/notify endpoint have rate limiting to prevent abuse?
3. Batching: If multiple chat messages arrive quickly, should notifications be batched or show individually?
4. Admin notification trigger: Does the push server's relay monitoring already cover admin DMs, or does the admin/Mostro also need to call /api/notify?

[Catrya]

I agree with the ideas, they seem good to me. Regarding the questions, I think it would be good to start by just putting the notification: "You have a new message", and then it can be improved to show the sender and the content.