Skip to content

Latest commit

Β 

History

125 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

MVP β€” Work in Progress. Core features are under active development, APIs may change, and you will hit bugs. Not yet audited β€” do not use for sensitive production data.

What is Marble

Marble is an E2EE messenger with a Go backend and a Tauri/React client.

Design goals: client sovereignty, server agnosticism, and ephemeral server storage. The server never sees plaintext or your MasterKey. Offline messages are stored encrypted and purged after the recipient ACKs. A local-only vault (Saved Messages) never leaves the device.

  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚                        MARBLE CLIENT (Tauri)                     β”‚
  β”‚                                                                  β”‚
  β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
  β”‚   β”‚   Account 1      β”‚  β”‚   Account 2      β”‚  β”‚ Offline Vaultβ”‚   β”‚
  β”‚   β”‚ (β†’ Server A)     β”‚  β”‚ (β†’ Server B)     β”‚  β”‚ (local-only, β”‚   β”‚
  β”‚   β”‚  E2EE            β”‚  β”‚  E2EE            β”‚  β”‚  never syncs)β”‚   β”‚
  β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
  β”‚           β”‚                     β”‚                                β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
              β”‚ E2EE                β”‚ E2EE
              β”‚ Curve25519/OpenPGP  β”‚ Curve25519/OpenPGP
              β–Ό                     β–Ό
     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
     β”‚  MARBLE SERVER A β”‚  β”‚  MARBLE SERVER B β”‚   ... any server
     β”‚  Go + Postgres   β”‚  β”‚  Go + Postgres   β”‚       (self-hostable)
     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  • Multi-tenant: One client holds multiple accounts, each bound to a different server. Strict isolation per cryptographic domain.
  • Server-agnostic: Any Marble server speaks the same WS/REST protocol. No vendor lock-in.
  • Offline vault: Saved Messages is a local SQLite session β€” encrypted at rest, never transmitted.
  • Deterministic errors: Client uses Result<T, AppError> (Go/Rust-style) instead of try/catch.

Technology Stack

Layer Choice
Server Go net/http + httprouter, PostgreSQL, gorilla/websocket, golang-jwt/jwt/v5, ProtonMail/gopenpgp/v3, knadh/koanf (YAML config), uber-go/zap
Client TypeScript, React 19, Vite, Tailwind CSS 4, Zustand, openpgp (Curve25519), jwt-decode, framer-motion, lucide-react
Native Tauri 2, plugins: sql (SQLite), keyring-api, fs, http, clipboard-manager, opener
DB Server: PostgreSQL Β· Client: SQLite (per-account, AES-GCM encrypted)

Cryptography

Marble has not been externally audited. The model below is the intended design β€” review enc/ and src/logic/enc/ before trusting it.

Local data is encrypted with AES-GCM-256. Network payloads are E2EE with OpenPGP Curve25519. Key derivation uses Argon2 (512-bit output).

MasterKey Lifecycle

          [ Master Phrase ]  (shown once at signup, then wiped)
                    β”‚
                    β–Ό  Argon2 β†’ 512-bit (64 bytes)
                    β”‚
          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  split in half
          β”‚                    β”‚
          β–Ό                    β–Ό
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   β”‚  Local Hash  β”‚     β”‚ Server Hash  │──► sent to server, re-hashed & stored
   β”‚ (MasterKey)  β”‚     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    used for login + JWT issuance
   β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜
          β”‚
          β”œβ”€β”€β”€β”€β–Ί encrypts ──► [ SQLite DB (AES-GCM, per-record) ]
          β”‚
          β–Ό (encrypted at rest by)
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   β”‚ Wrapping Key β”‚ ◄── derived ───  β”‚ Daily Passphrase / OS Keyring β”‚
   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

   Recovery: re-enter Master Phrase β†’ Argon2 β†’ same MasterKey β†’ vault unlocks
   Daily unlock: Passphrase/Keyring β†’ Wrapping Key β†’ decrypts stored MasterKey
  • Threat model: Server stores only hash(ServerHash) and never sees MasterKey or plaintext. It does see account metadata (displayId, session membership, message timing/counts) and temporarily holds offline ciphertext.
  • What is E2EE today: Message content is OpenPGP-encrypted client-side before actv send. Everything else (counts, session_last_seq, avatars) is not.
  • Daily auth: OS Keychain or a short passphrase derives a Wrapping Key that decrypts the at-rest MasterKey β€” so you don't retype the Master Phrase every launch.

Message Routing (Ephemeral Server)

  [ Sender ] ── E2EE ciphertext ──► [ WebSocket Server : /actv ]
                                            β”‚
                              Recipient state
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚                                               β”‚
               [ ONLINE ]                                      [ OFFLINE ]
                    β”‚                                               β”‚
                    β–Ό                                               β–Ό
            in-memory direct                               persist to Postgres
            routing (no DB I/O)                             (ciphertext only)
                    β”‚                                               β”‚
                    β–Ό                                               β”‚
              [ Recipient ] ◄──────── sync on reconnect β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                    β”‚
                    └── ACK (delivered) ──► [ Server PURGES row ]
  • Online: Routed in-memory, zero DB writes.
  • Offline: Persisted as ciphertext in message table.
  • On reconnect: Server syncs pending messages; client ACK triggers DELETE β€” honoring the ephemeral model.

Database Schema

  users ──1:1── pgp_profile
    β”‚ 1
    β”‚ n
    β”œβ”€β”€β”€ session (alpha_id, beta_id  CHECK alpha < beta, UNIQUE pair)
    β”‚      β”‚ 1
    β”‚      β”‚ n
    β”‚      └─── message (session_id, sender_id, seq, content, profile)
    β”‚
    └─── tokens (hash PK, user_id, expiry, scope, type)

See db/migrations/000001_init_schema.up.sql for the full DDL.


Getting Started

Prerequisites

  • Go 1.22+ Β· PostgreSQL 15+ Β· golang-migrate CLI Β· Node 20+ Β· Rust (for Tauri)

1. Server

# config
cp tmp/marble.yaml marble.yaml   # edit port, jwtSecret, db DSN, mailer
# env var used by Makefile:
export MARBLE_DB_DSN="postgres://user:pass@localhost:5432/marble?sslmode=disable"

# migrate
make -C db migrateUpAll        # or: migrate -path=db/migrations -database=$MARBLE_DB_DSN up

# run
go run .
# REST on :6280, WS on /actv, health on GET /

marble.yaml shape (see tmp/marble.yaml):

app:  { version: v0.1.3, env: Development }
api:
  port: 6280
  jwtSecret: "<32+ random bytes, base64>"
  env: Development
  limiter: { enabled: true, rps: 2, burst: 6, timeout: 2m }
  users:  { properties: [withActivation] }
  mailer: { enabled: false, smtp-host: localhost, smtp-port: 1025, ... }

2. Client

cd client/Marble
npm ci
npm run dev          # Vite on http://localhost:1420
# or full Tauri window:
npm run tauri dev
npm run build        # tsc && vite build

Tauri security is locked to csp: default-src 'self'; connect-src 'self' http: https: ws: wss: in src-tauri/tauri.conf.json.


Project Structure

Marble/
β”œβ”€β”€ app/                # server application
β”‚   β”œβ”€β”€ api/            # REST handlers, JWT, middlewares, routes
β”‚   β”œβ”€β”€ active/         # WS hub, in-memory store, message/session handlers
β”‚   β”œβ”€β”€ session/        # session + message persistence
β”‚   β”œβ”€β”€ users/          # users + tokens
β”‚   └── setup.go        # wiring (config, logger, db, api)
β”œβ”€β”€ config/             # koanf YAML loader
β”œβ”€β”€ db/                 # pg connection + migrations + Models aggregate
β”œβ”€β”€ enc/pgp/            # server-side OpenPGP helpers
β”œβ”€β”€ internal/           # helpers, loggy (zap), mailer, validator
β”œβ”€β”€ client/Marble/      # Tauri + React client
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ components/ # auth, chat, sidebar, settings
β”‚   β”‚   └── logic/      # enc, active (WS), auth, db (SQLite), messages, sessions, states
β”‚   └── src-tauri/      # Tauri Rust shell + tauri.conf.json
β”œβ”€β”€ tmp/marble.yaml     # example config
└── main.go             # entrypoint β†’ app.Main()

API Overview

Method Path Auth Notes
GET / β€” Health: {"status":"available"}
POST /auth/signup β€” Create account
POST /auth/login β€” Issue JWT + refresh token
POST /auth/refresh refresh Rotate tokens
PATCH /account/update JWT Update profile
DELETE /account/delete JWT Delete account
GET /actv JWT (WS) WebSocket β€” all realtime messaging

WS protocol: JSON { status, channel, token, body } β€” channels auth, message, session, user. See app/active/actTypes.go and client/Marble/src/logic/active/.


Roadmap

  • Audit Argon2id params + per-user salt, add pgx + context-aware queries, fix WS lifecycle (close/cancel, raise 4KB read limit)
  • E2EE coverage: encrypt session metadata, add key rotation
  • Offline reliability: retry + idempotent ACK, pagination for large sync
  • Tests: go test ./... + client unit tests for enc/ round-trips
  • CI: lint, test, and Tauri build on PR (currently release-only)

Licence

See LICENCE.


Built with care β€” contributions and sharp reviews welcome.