mxriana

Real-time end-to-end encrypted email for I2P/I2P+. Named after the Marianas Trench, the deepest part of the ocean.

Features

• End-to-end encryption using Ed25519 and X25519
• Real-time message delivery via WebSockets
• Designed specifically for I2P/I2P+ anonymous networking
• Client-side key generation and management
• Forward secrecy with ephemeral keys
• Encrypted attachment support with chunking
• No plaintext metadata storage on server

Prerequisites

• Crystal 1.18.2+
• libsodium
• PostgreSQL
• Redis
• I2P or I2P+ router running locally

Installation

Install dependencies

# Install Crystal
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Install libsodium
sudo apt-get install libsodium-dev  # Debian/Ubuntu
brew install libsodium              # macOS

# Install Redis
sudo apt-get install redis-server   # Debian/Ubuntu
brew install redis                  # macOS

# Install I2P or I2P+
# Follow instructions at https://geti2p.net or https://i2pplus.github.io

Build mxriana

# Clone repository
git clone <your-repo>
cd mxriana

# Install shards
shards install

# Build
crystal build src/mxriana.cr

# Or build optimized release
crystal build --release src/mxriana.cr

Configuration

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration. Key settings:

• PORT: Port for the web server (default: 3000)
• HOST: Bind address (default: 127.0.0.1)
• I2P_SAM_HOST / I2P_SAM_PORT: I2P SAM bridge connection
• JWT_SECRET: Change this to a secure random value in production

Running

Start Redis

redis-server

Start I2P Router

Ensure your I2P router is running with SAM enabled (default port 7656).

Configure I2P HTTP Server Tunnel

In your I2P router console:

1. Go to Hidden Services Manager
2. Create a new HTTP server tunnel
3. Point it to 127.0.0.1:3000 (or your configured HOST:PORT)
4. Note your .i2p address

Start mxriana

# Development
./mxriana

# Or with environment file
crystal run src/mxriana.cr

# Production
KEMAL_ENV=production ./mxriana

The server will start and be accessible via your I2P tunnel address.

Development

Run tests

crystal spec

Code formatting

crystal tool format

Linting

./bin/ameba

Architecture

• Client: Browser-based with WebCrypto for key management
• Server: Store-and-forward with real-time WebSocket push
• Transport: All traffic goes through I2P
• Crypto: Ed25519 (signatures), X25519 (key agreement), ChaCha20-Poly1305 (AEAD)

API Endpoints

• POST /api/register - Register new user with public keys
• POST /api/send - Send encrypted message
• GET /api/inbox - List messages (metadata only)
• GET /api/message/:id - Retrieve encrypted message
• POST /api/upload-chunk - Upload encrypted attachment chunk
• GET /api/chunk/:hash - Retrieve encrypted chunk
• DELETE /api/message/:id - Delete message
• WS /ws/:device_id - WebSocket for real-time notifications

Security Notes

• All message content is encrypted client-side
• Server never sees plaintext messages or keys
• Private keys never leave the browser
• Forward secrecy via ephemeral keys per message
• Metadata is minimized but not eliminated
• Traffic analysis protection relies on I2P

License

MIT

Contributing

Contributions welcome. Please ensure code is formatted and passes tests.