https://github.com/barrelmaker97/obscura-server
Minimalist, secure relay server for the Signal Protocol
https://github.com/barrelmaker97/obscura-server
Last synced: 4 months ago
JSON representation
Minimalist, secure relay server for the Signal Protocol
- Host: GitHub
- URL: https://github.com/barrelmaker97/obscura-server
- Owner: barrelmaker97
- License: gpl-3.0
- Created: 2025-06-29T17:02:18.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-02-12T22:51:11.000Z (4 months ago)
- Last Synced: 2026-02-13T08:10:59.530Z (4 months ago)
- Language: Rust
- Homepage:
- Size: 1.15 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Obscura Server
**Obscura Server** is a minimalist, secure relay server for the Signal Protocol. It facilitates end-to-end encrypted asynchronous messaging while maintaining a zero-knowledge architecture.
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/barrelmaker97/obscura-server/actions/workflows/ci.yml)
## Features
- **Zero-Knowledge Architecture**: The server stores opaque encrypted blobs. It cannot read message content or access private keys.
- **Signal Protocol Support**: Native support for PreKeys (Identity, Signed, One-Time) to enable X3DH key exchanges.
- **Asynchronous Delivery**: Stores encrypted messages until the recipient comes online to fetch them via WebSockets.
- **Encrypted Attachments**: Secure file uploads via S3-compatible storage with automated TTL-based expiry.
- **Strict Privacy Limits**: Automatic garbage collection of old messages and global inbox limits to prevent metadata buildup.
- **Observability Native**: Built-in support for Traces, Metrics, and Structured Logging via OTLP.
---
## Security & Privacy
### Threat Model
Obscura is designed to protect the **content** of communications even if the server is fully compromised.
- **What the Server Sees**:
- User IDs and Usernames.
- Public Keys (Identity, Signed PreKeys, One-Time PreKeys).
- Metadata: Message timestamps, sizes, and recipient/sender IDs.
- IP Addresses (unless connected via Tor/VPN).
- **What the Server CANNOT See**:
- Message plaintext (content).
- Attachment plaintext.
- Private keys (they never leave the client).
- **Non-Goals**: Obscura does not currently implement padding or mix-net techniques to protect against advanced traffic analysis or metadata correlation.
---
## Quick Start
### 1. Run with Docker Compose
A `docker-compose.yml` is provided for a complete local stack (Postgres + Valkey + MinIO + Server):
```bash
docker compose up -d
```
### 2. Interaction Example
Once the server is running on port `3000`, you can verify it's working:
```bash
# Check Health (Management Port 9090)
curl http://localhost:9090/readyz
# View OpenAPI Spec
curl http://localhost:3000/openapi.yaml
```
---
## Configuration
Obscura can be configured via command-line flags or environment variables. **Essential configurations** include:
| Option | Environment Variable | Default |
|--------|----------------------|---------|
| `--db-url` | `OBSCURA_DATABASE_URL` | `postgres://user:password@localhost/signal_server` |
| `--pubsub-url` | `OBSCURA_PUBSUB_URL` | `redis://localhost:6379` |
| `--jwt-secret` | `OBSCURA_AUTH_JWT_SECRET` | `change_me_in_production` |
| `--storage-bucket` | `OBSCURA_STORAGE_BUCKET` | `obscura-storage` |
See [**docs/CONFIGURATION.md**](./docs/CONFIGURATION.md) for the full list of over 50 configuration options.
---
## Development
### Prerequisites
- Rust 1.83+
- PostgreSQL 16+
- Valkey 8+ (or Redis)
- `protoc` (Protocol Buffers compiler)
### Running Locally
1. Start infrastructure: `docker compose up -d db minio valkey`
2. Run migrations and start:
```bash
export OBSCURA_DATABASE_URL=postgres://user:password@localhost/signal_server
export OBSCURA_PUBSUB_URL=redis://localhost:6379
export OBSCURA_AUTH_JWT_SECRET=test
export OBSCURA_STORAGE_BUCKET=test
cargo run
```
### Testing
```bash
cargo test
```
---
## Documentation
- **API Reference**: [openapi.yaml](./openapi.yaml)
- **Configuration Guide**: [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)
- **Release Process**: [docs/RELEASING.md](./docs/RELEASING.md)
- **System Architecture**: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
- **Design Docs**: [docs/design/](./docs/design/)
# License
Copyright (c) 2026 Nolan Cooper
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .