Server

Overview

The MessageBox Server relays encrypted messages between peers over HTTP and WebSocket. It supports sending, receiving, and acknowledging messages in a secure, identity-key-based system.

It’s designed to be used with the MessageBoxClient, and can be extended by apps like PeerPayClient for use cases such as live payment notifications.

For production, run or select a MessageBox Server and configure clients with its HTTPS and WebSocket endpoints. The examples below use https://your-messagebox.example as a placeholder.

Endpoints

POST /sendMessage

Sends a message to a recipient's message box.

• Auth Required: Yes (sender must be authenticated)
• Request Body:

1{
2  "message": {
3    "recipient": "<recipientPublicKey>",
4    "messageBox": "payment_inbox",
5    "messageId": "xyz123",
6    "body": "{...}"
7  }
8}

• Behavior: o Validates recipient public key and message structure o Automatically creates a message box if it doesn’t exist o Inserts the message into the database o If the recipient is connected via WebSocket, the message is sent instantly

POST /listMessages

Lists messages for a specific message box belonging to the authenticated user.

• Auth Required: Yes
• Request Body:

1{
2  "messageBox": "payment_inbox"
3}
4•	Response:
5json
6Copy
7{
8  "status": "success",
9  "messages": [
10    {
11      "messageId": "xyz123",
12      "body": "{...}",
13      "sender": "<senderPublicKey>"
14    }
15  ]
16}

POST /acknowledgeMessage

Acknowledges (and deletes) a list of message IDs, confirming receipt.

• Auth Required: Yes
• Request Body:

1{
2  "messageIds": ["xyz123"]
3}

• Response:

1{
2  "status": "success"
3}

• Note: Acknowledged messages are deleted from the database. If no acknowledgment is received, the messages remain retrievable via /listMessages.

WebSocket Support

The server supports authenticated WebSocket connections using identity keys. When connected:

• Messages sent to a user are delivered instantly via WebSocket
• The client does not need to poll using /listMessages
• Delivered messages are still persisted in the database until acknowledged

Connection Flow:

1. The client opens a WebSocket connection to your MessageBox Server, for example wss://your-messagebox.example.

2. The client authenticates using a signature from its identity key (handled by MessageBoxClient)

3. Once authenticated, the server:

   • Subscribes the user to incoming messages
   • Delivers them in real time as they arrive

4. The client may choose to acknowledge each message to remove it from the server

Example Message Flow

1. Alice sends an encrypted message to Bob via /sendMessage
2. If Bob is connected via WebSocket, he receives the message instantly
3. If Bob is not connected, he can later call /listMessages to retrieve it
4. After successfully processing the message, Bob calls /acknowledgeMessage to delete it

Deployment Notes To run your own instance of MessageBox Server:

1. Clone the MessageBox server repository
2. Set the following environment variable: SERVER_PRIVATE_KEY=... This is the server’s private key used for cryptographic operations.
3. Configure your database (MySQL or other Knex compatible) via knexfile.js
4. Start the server using Node.js with your preferred process manager or Docker

Architecture Notes

• MessageBox uses knex for database access
• Messages are scoped by:
  • recipient identity key
  • messageBox type (e.g. payment_inbox, alerts, etc.)
• Message delivery via WebSocket is event-driven, allowing apps to build real-time systems on top of it

Next Steps

• Read the MessageBoxClient Guide to see how to connect and send/receive messages from the client side
• See the PeerPayClient Guide to understand how MessageBox is used for real-time payment coordination
• Deploy your own message box server!