korvali mail.js Documentation

⚙️ Architecture & Overview

mail.js is a real-time messaging engine that connects directly to custom WebSocket servers. It utilizes Public Key Identity mapping for session management and message routing, IndexedDB local storage, multi-server pool fallback, and client-side anti-spam rate limiting.

💻 How to Use Korvali Mail Interface (UI Guide)

STEP 1Configure Account & Public Key Setup
Click the floating ⚙️ Settings button to configure your identity:
- Enter your handle/username (e.g. alice).
- Your Public Key acts as your unique identity across all WebSocket sessions.
- Enter trusted server WebSocket URLs (1 URL per line, e.g. wss://server1.korvali.net).
- Backup / Restore: Export or import your identity JSON backup to preserve your public key across browsers.
STEP 2Composing New Messages
Click the floating ✍️ Compose button:
- Specify recipient Handle and Recipient Public Key.
- Fill in Subject and Payload, then click Send Message.
- The server matches the recipient's public key to route the packet and responds with {"success": true}.

📡 Mandatory Custom Server Requirements

1. Protocol & Transport
The server must accept full-duplex WebSocket connections over ws:// (development) or wss:// (secure production).
2. Connection Handshake (`INIT`) & Public Key Mapping
Upon connection, mail.js sends an initial auth frame (type: "INIT") containing publicKey and handle. The server MUST map the active WebSocket socket to this `publicKey` for message dispatch and routing.
3. Delivery Confirmation (`{"success": true}`)
When receiving a MAIL_SEND packet, the target server MUST send back a JSON frame containing "success": true within 5 seconds to confirm relay.

📄 JSON Protocol Specification

1. Handshake Initialization Frame (Client → Server):

{
  "type": "INIT",
  "publicKey": "pk-8f3a9b1c-4d2e-4f5a-9b1c-8f3a9b1c4d2e", // Identity & Session Key
  "handle": "alice", // Username without domain
  "token": "optional_auth_token"
}

2. Outgoing Mail Payload (Client → Server):

{
  "type": "MAIL_SEND",
  "from": "alice@korvali",
  "senderPublicKey": "pk-8f3a9b1c-4d2e-4f5a-9b1c-8f3a9b1c4d2e",
  "to": "bob",
  "recipientPublicKey": "pk-9e2b1a0c-3f4d-5e6a-8b0c-9e2b1a0c3f4d",
  "subject": "Hello World",
  "body": "Message payload content.",
  "timestamp": 1700000000000
}

3. Server Delivery Acknowledgement (Server → Client):

{
  "success": true,
  "message": "Mail delivered successfully."
}

4. Incoming Mail Payload (Server → Client):

{
  "from": "bob@korvali",
  "senderPublicKey": "pk-9e2b1a0c-3f4d-5e6a-8b0c-9e2b1a0c3f4d",
  "subject": "Re: Hello World",
  "body": "Received loud and clear!",
  "timestamp": 1700000000000
}