Synapsis/SWARM_CHAT.md

Swarm Chat

A real-time, end-to-end encrypted chat system built exclusively for the Synapsis Swarm network.

Features

• End-to-End Encryption: Messages are encrypted using recipient's public key
• Cross-Node Messaging: Chat with users on any Synapsis node
• Real-Time Delivery: Messages delivered instantly via swarm inbox
• Read Receipts: See when messages are delivered and read
• Typing Indicators: Know when someone is typing (coming soon)
• No ActivityPub Limitations: Built specifically for swarm, not constrained by AP spec

Architecture

Database Schema

chat_conversations: Tracks conversations between users

• Stores participant info and last message preview
• Unique constraint ensures one conversation per user pair

chat_messages: Individual encrypted messages

• Content encrypted with recipient's public key
• Swarm message ID for deduplication
• Delivery and read status tracking

chat_typing_indicators: Real-time typing status (future)

API Endpoints

POST /api/swarm/chat/send

• Send a message to any user (local or remote)
• Encrypts content with recipient's public key
• Delivers to remote nodes via swarm inbox

POST /api/swarm/chat/inbox

• Receives messages from other swarm nodes
• Validates and stores encrypted messages
• Updates conversation metadata

GET /api/swarm/chat/conversations

• Lists all conversations for current user
• Includes unread counts and last message preview

GET /api/swarm/chat/messages

• Fetches messages for a conversation
• Supports cursor-based pagination
• Returns encrypted content for client-side decryption

PATCH /api/swarm/chat/messages

• Marks messages as read
• Updates read receipts

Encryption

Messages are encrypted using RSA-OAEP with SHA-256:

1. Sending: Message encrypted with recipient's public key
2. Storage: Only encrypted content stored in database
3. Decryption: Client-side decryption using user's private key

This ensures true end-to-end encryption - even the server cannot read messages.

Usage

Starting a Chat

// Send a message to start a conversation
await fetch('/api/swarm/chat/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recipientHandle: 'user@remote.node',
    content: 'Hello!',
  }),
});

Receiving Messages

Messages are automatically received via the swarm inbox endpoint. The system:

1. Validates the sender and recipient
2. Checks for duplicate messages
3. Creates or updates the conversation
4. Stores the encrypted message
5. Returns success to the sender

Client-Side Decryption

import { decryptMessage } from '@/lib/swarm/chat-crypto';

// Decrypt a message using user's private key
const plaintext = decryptMessage(
  message.encryptedContent,
  userPrivateKey
);

Security Considerations

1. Private Key Storage: User private keys should be encrypted at rest
2. Key Derivation: Consider using password-based key derivation
3. Forward Secrecy: Future enhancement - implement Signal protocol
4. Message Signing: Verify sender authenticity with signatures
5. Rate Limiting: Prevent spam and abuse

Future Enhancements

• Group chats (multi-party encryption)
• Voice/video calls (WebRTC)
• File attachments (encrypted)
• Message reactions
• Message editing/deletion
• Typing indicators (real-time)
• Online/offline status
• Push notifications
• Desktop notifications
• Message search
• Conversation archiving
• Block/mute users
• Forward secrecy (Signal protocol)

Migration

Run the migration to create the chat tables:

npm run db:generate
npm run db:migrate

Testing

Test the chat system:

1. Create two accounts on different nodes
2. Navigate to /chat on one account
3. Click "New Chat" and enter the other user's handle
4. Send a message
5. Check the other account's /chat page

Differences from ActivityPub DMs

Traditional ActivityPub direct messages are just posts with limited visibility. Swarm Chat is superior:

• True E2E Encryption: Not possible with ActivityPub
• Real-Time: Direct delivery, no polling required
• Proper Chat UX: Conversations, read receipts, typing indicators
• Lightweight: No heavyweight ActivityPub overhead
• Swarm-Native: Built for the swarm, not retrofitted

Contributing

Contributions welcome! Priority areas:

• Client-side encryption implementation
• Real-time updates (WebSocket/SSE)
• Mobile-responsive UI improvements
• Group chat support