| 1 | # 🤖 Eleven Messenger |
| 2 | |
| 3 | A small, self-hostable messenger — DMs and group chats, no logins, no passwords, |
| 4 | just secret invite links. Messages are **end-to-end encrypted**: the server only |
| 5 | ever sees ciphertext, so a stolen database or server snapshot exposes no message |
| 6 | content. (It does see metadata — screen names and who shares a thread with whom; |
| 7 | see Trade-offs.) |
| 8 | |
| 9 | > **`lchat`** is the engine — the Go binary + CLI, and the name used throughout |
| 10 | > this repo. **Eleven Messenger** is the product built on it (the web client plus |
| 11 | > the native iOS/macOS apps). |
| 12 | |
| 13 | ## How the encryption works |
| 14 | |
| 15 | - Each person has their own **keypair** (ECDH P-256), generated in the browser on |
| 16 | first join. The public key lives in the roster; the private key never leaves the |
| 17 | device (it ships, encrypted, only via an "add a device" link). |
| 18 | - Every **thread** — a DM (2 people) or a group (N) — has its own **AES-GCM key**, |
| 19 | wrapped to each member's public key (ECIES). Only members can unwrap it. |
| 20 | - Content shared with everyone (e.g. profile photos) uses one **per-instance key**, |
| 21 | wrapped to each member the same way — so even that reaches the server only as a |
| 22 | blob it can't open. |
| 23 | - The browser encrypts every message (including the sender's screen name) before |
| 24 | sending, and decrypts on receipt. The server stores and relays only opaque blobs |
| 25 | plus key material it can't open. |
| 26 | - An invite link carries a one-time secret in its `#fragment` (e.g. |
| 27 | `/join/<name>#<secret>`) used to bootstrap the joiner's keys — never sent to the |
| 28 | server. The **admin token authorises roster management only; it is not a |
| 29 | decryption key.** Even a full copy of the database reveals no message content. |
| 30 | |
| 31 | **Trade-offs (inherent to this model):** |
| 32 | |
| 33 | - Membership is the boundary, enforced cryptographically: to read a thread you |
| 34 | must be one of its members (hold its wrapped key). |
| 35 | - Removing a member stops the server delivering new messages to them, but doesn't |
| 36 | claw back a key they already hold (no forward secrecy on leave). |
| 37 | - If a member loses their device with no backup/add-device link, their key |
| 38 | material — and the threads only they could decrypt — is gone. |
| 39 | - **Metadata is not encrypted.** The server can't read message content, but the |
| 40 | roster stores each member's screen name in clear (separate from the encrypted |
| 41 | copy carried inside each message), and the server necessarily knows who shares |
| 42 | a thread with whom in order to route messages. So a server compromise reveals |
| 43 | the social graph and names — just not what anyone said. |
| 44 | - **Unsending leaves a dated marker.** Deleting a message really deletes the |
| 45 | ciphertext, but the server keeps a small tombstone row — which thread, which |
| 46 | message id, when — so members' devices that were offline at the time still |
| 47 | learn to drop their local copy. The tombstone holds no content and no key |
| 48 | material, but it is a durable record *that* a deletion happened (the server |
| 49 | transiently knew that anyway — it performed the delete). |
| 50 | - **Key distribution trusts the server.** Public keys are handed out by the |
| 51 | server's roster and aren't yet verified out of band (no safety-number check). |
| 52 | A *passive* compromise — a stolen database — can't use that (the content |
| 53 | guarantee above holds), but an *active* malicious server could substitute a |
| 54 | public key to intercept *new* conversations. Out-of-band key verification is |
| 55 | planned to close this. |
| 56 | - **A bot is a member whose "device" is a machine you choose.** Adding a bot |
| 57 | (see `agent/`) to a thread hands that thread's key to the machine the bot |
| 58 | runs on — so whoever controls that machine holds the key to those |
| 59 | conversations, exactly as if they were a member. Threads without a bot are |
| 60 | untouched. Crucially, the bot doesn't have to live on the chat server: it's a |
| 61 | pure outbound client (it dials the instance and the model API; nothing ever |
| 62 | dials it — no open ports), so you can run it on any machine you already |
| 63 | trust — a home server behind your router, or a box on a private network |
| 64 | whose only way out is to your instance and the model API. Run it there and a |
| 65 | fully compromised chat server still yields nothing: the keys are on a |
| 66 | machine an attacker can't even reach. |
| 67 | |
| 68 | ## Run it |
| 69 | |
| 70 | ```sh |
| 71 | go run . # listens on :1747, creates lchat.db |
| 72 | ``` |
| 73 | |
| 74 | On first start it prints an **admin link** containing your admin token — |
| 75 | open it once and keep it secret: |
| 76 | |
| 77 | ``` |
| 78 | Admin link (open once, keep it secret): |
| 79 | http://localhost:1747/admin#token=... |
| 80 | ``` |
| 81 | |
| 82 | Flags / env: |
| 83 | |
| 84 | - `-addr :1747` — listen address |
| 85 | - `-db lchat.db` — database file path |
| 86 | - `-reset-admin` — generate and print a fresh admin token |
| 87 | - `LCHAT_ADMIN_TOKEN=...` — set a fixed admin token instead of a generated one |
| 88 | |
| 89 | ## Build a single binary |
| 90 | |
| 91 | The frontend and the SQLite engine are compiled in (pure-Go SQLite, no cgo), |
| 92 | so deployment is one file: |
| 93 | |
| 94 | ```sh |
| 95 | go build -o lchat . # native |
| 96 | GOOS=linux GOARCH=amd64 go build -o lchat . # cross-compile for a Linux box |
| 97 | ``` |
| 98 | |
| 99 | See **[Deploy](#deploy)** for how to run it in production — a self-hosted router |
| 100 | (the default), a single instance behind your own reverse proxy, Docker, or |
| 101 | another platform. |
| 102 | |
| 103 | ## Native iOS & macOS app |
| 104 | |
| 105 | There's a native SwiftUI client in [`ios/`](ios/README.md) that runs on |
| 106 | iPhone/iPad and on macOS via **Mac Catalyst** (same target, same code, same |
| 107 | end-to-end encryption contract). The `.xcodeproj` is generated by |
| 108 | [`xcodegen`](https://github.com/yonaskolb/XcodeGen), not committed. |
| 109 | |
| 110 | You can build both variants from the command line **without launching Xcode** |
| 111 | (handy for CI or a quick compile check) — `CODE_SIGNING_ALLOWED=NO` skips the |
| 112 | need for a signing team: |
| 113 | |
| 114 | ```sh |
| 115 | cd ios |
| 116 | xcodegen generate # writes LChat.xcodeproj from project.yml |
| 117 | |
| 118 | # iOS (compiles against the Simulator SDK — no device or signing needed): |
| 119 | xcodebuild -project LChat.xcodeproj -scheme LChat \ |
| 120 | -destination 'generic/platform=iOS Simulator' \ |
| 121 | -derivedDataPath build CODE_SIGNING_ALLOWED=NO build |
| 122 | |
| 123 | # macOS (Mac Catalyst — a native build that doesn't touch the iOS Simulator): |
| 124 | xcodebuild -project LChat.xcodeproj -scheme LChat \ |
| 125 | -destination 'platform=macOS,variant=Mac Catalyst' \ |
| 126 | -derivedDataPath build CODE_SIGNING_ALLOWED=NO build |
| 127 | ``` |
| 128 | |
| 129 | `-derivedDataPath build` keeps the products inside the repo (under the |
| 130 | gitignored `ios/build/`) instead of a hashed folder buried in |
| 131 | `~/Library/Developer/Xcode/DerivedData/`. The built apps land at: |
| 132 | |
| 133 | - `ios/build/Build/Products/Debug-iphonesimulator/LChat.app` |
| 134 | - `ios/build/Build/Products/Debug-maccatalyst/LChat.app` ← the runnable Mac app |
| 135 | |
| 136 | That Mac path is still a mouthful, so symlink it somewhere handy and launch it |
| 137 | (the `LChat-*.app` symlink names are gitignored): |
| 138 | |
| 139 | ```sh |
| 140 | ln -sfn build/Build/Products/Debug-maccatalyst/LChat.app LChat-mac.app |
| 141 | open LChat-mac.app # runs the Mac (Catalyst) build |
| 142 | ``` |
| 143 | |
| 144 | A successful build ends in `** BUILD SUCCEEDED **`. If a Simulator destination |
| 145 | can't be resolved (e.g. an out-of-date CoreSimulator), target the SDK directly |
| 146 | instead: `-sdk iphonesimulator` in place of the `-destination` flag. See |
| 147 | [`ios/README.md`](ios/README.md) for signing, running on a device, and how the |
| 148 | client maps to the server. |
| 149 | |
| 150 | ## Deploy |
| 151 | |
| 152 | lchat is a single static binary that keeps all its state in one SQLite file and |
| 153 | speaks WebSockets on `/ws`. Deploying it anywhere is the same three things: run |
| 154 | the binary, give it a **persistent path for the database** (`LCHAT_DB`), and put |
| 155 | it behind **HTTPS** — required in production, since the invite token travels to |
| 156 | the server and the fragment-key model assumes an encrypted transport. SQLite has |
| 157 | a single writer, so run **one instance per database** (scale by adding instances, |
| 158 | not replicas of one). |
| 159 | |
| 160 | ### Self-hosted router (recommended) |
| 161 | |
| 162 | How we run it, and the default for hosting **one or many** chats: a single box |
| 163 | runs lchat's own built-in TLS router, and each chat is a fully-isolated instance |
| 164 | on its own subdomain, database, and admin token — automatic Let's Encrypt certs, |
| 165 | no external reverse proxy, no container platform. One line installs the latest |
| 166 | stable release (sha256-verified; amd64 or arm64) and bootstraps the box: |
| 167 | |
| 168 | ```sh |
| 169 | # on a fresh box (Ubuntu/Debian; inbound 80 + 443 open): |
| 170 | curl -fsSL https://github.com/elevenmessenger/releases/releases/download/server/install.sh | sudo bash |
| 171 | |
| 172 | # add a chat — point its DNS A record at the box first; the TLS cert issues |
| 173 | # automatically, and the printed setup link makes you the admin: |
| 174 | lchat add-instance chat.example.com |
| 175 | ``` |
| 176 | |
| 177 | Add as many chats as you like; each is isolated. The box then **keeps itself up |
| 178 | to date** from the signed stable release channel — hourly checks, per-instance |
| 179 | health check, automatic rollback — and each chat's admin picks a channel |
| 180 | (stable / beta / edge) in their admin panel. The full guide (backups, bots, |
| 181 | honest limitations) is **[docs/self-hosting.md](docs/self-hosting.md)**, |
| 182 | published as the README of the public |
| 183 | [releases repo](https://github.com/elevenmessenger/releases). |
| 184 | |
| 185 | Deploying your **own builds** instead (development, forks): build, stage, then |
| 186 | roll out — zero-downtime, health-checked, auto-rollback; pin canaries so the |
| 187 | auto-updater leaves them alone: |
| 188 | |
| 189 | ```sh |
| 190 | ./deploy/build-linux.sh # builds + stamps a version id |
| 191 | scp lchat-linux-amd64 root@box:/opt/lchat/incoming/lchat-upload |
| 192 | ssh root@box /opt/lchat/lchat stage --file /opt/lchat/incoming/lchat-upload |
| 193 | ssh root@box /opt/lchat/lchat deploy chat.example.com --version <ver> --pin # canary, held |
| 194 | ssh root@box /opt/lchat/lchat deploy --all --version <ver> # the whole fleet |
| 195 | ssh root@box /opt/lchat/lchat rollback chat.example.com # step back |
| 196 | ``` |
| 197 | |
| 198 | The full design — routing, supervision (systemd), releases + auto-update, |
| 199 | backups, and hardening — is in |
| 200 | **[docs/instance-router.md](docs/instance-router.md)** and |
| 201 | **[docs/server-releases.md](docs/server-releases.md)**. |
| 202 | |
| 203 | ### A single instance behind your own reverse proxy |
| 204 | |
| 205 | The minimal path for one chat, if you'd rather run your own proxy: build, copy up, |
| 206 | and terminate TLS with Caddy or nginx. |
| 207 | |
| 208 | ```sh |
| 209 | GOOS=linux GOARCH=amd64 go build -o lchat . |
| 210 | scp lchat you@server:/srv/lchat/ |
| 211 | LCHAT_DB=/srv/lchat/lchat.db ADDR=:1747 ./lchat # via a systemd unit in practice |
| 212 | ``` |
| 213 | |
| 214 | Then proxy `https://chat.example.com` → `127.0.0.1:1747` (Caddy gets you TLS in |
| 215 | two lines). |
| 216 | |
| 217 | ### Docker |
| 218 | |
| 219 | The repo ships a `Dockerfile`: a fully static binary in a distroless image |
| 220 | (~2MB of image around the binary, no shell), running as a **non-root** user. |
| 221 | Runtime config is env vars: |
| 222 | |
| 223 | - `LCHAT_DB` — SQLite path; point it at the persistent volume (`/data/lchat.db`) |
| 224 | - `LCHAT_ADMIN_TOKEN` — admin token |
| 225 | - `ADDR` — listen address (defaults to `:1747`, matching the exposed port) |
| 226 | |
| 227 | > **Gotcha (learned the hard way):** the env var is `LCHAT_ADMIN_TOKEN`, *not* |
| 228 | > `ADMIN_TOKEN`. Some container platforms auto-provision their own secret for a |
| 229 | > bare `ADMIN_TOKEN` ("referenced in code") and inject that, silently overriding |
| 230 | > whatever you set. The `LCHAT_` prefix dodges that. |
| 231 | |
| 232 | ```sh |
| 233 | # 1. Build, and generate a URL-safe admin token (it goes in a URL #fragment): |
| 234 | docker build -t lchat . |
| 235 | TOKEN=$(openssl rand -base64 32 | tr -d '\n' | tr '+/' '-_' | tr -d '=') |
| 236 | |
| 237 | # 2. Run with a named volume for the database: |
| 238 | docker run -d --name lchat --restart unless-stopped \ |
| 239 | -p 127.0.0.1:1747:1747 \ |
| 240 | -v lchat-data:/data \ |
| 241 | -e LCHAT_DB=/data/lchat.db -e "LCHAT_ADMIN_TOKEN=$TOKEN" \ |
| 242 | lchat |
| 243 | # Your admin URL is then: https://group.example.com/admin#token=$TOKEN |
| 244 | ``` |
| 245 | |
| 246 | Then terminate TLS in front of it exactly as in the reverse-proxy section |
| 247 | above (`https://group.example.com` → `127.0.0.1:1747`; make sure the proxy |
| 248 | passes the `/ws` WebSocket upgrade). |
| 249 | |
| 250 | The container runs as uid 65532, and `/data` in the image is owned by that |
| 251 | user — a **named volume** (as above) inherits the ownership on first use. If |
| 252 | you'd rather **bind-mount** a host directory, chown it first |
| 253 | (`chown 65532:65532 /srv/lchat-data`). Keep the service at a **single |
| 254 | replica** — SQLite has one writer. |
| 255 | |
| 256 | **Updating later (no data loss):** rebuild and recreate the container; the |
| 257 | volume (messages, invites, push subscriptions, VAPID keys, group name) |
| 258 | survives. Only deleting the *volume* wipes data. |
| 259 | |
| 260 | ### Other platforms (Fly.io, Render, Railway, Heroku, …) |
| 261 | |
| 262 | Each of these should be trivial — it's the same single static binary plus a |
| 263 | persistent volume — but **none is tested yet**, so treat the below as the recipe, |
| 264 | not a proven path. Any host that runs a binary (or the shipped `Dockerfile`) with a |
| 265 | persistent volume works the same way; the constraints are just the three from the |
| 266 | top of this section: |
| 267 | |
| 268 | - Attach a **persistent volume** and set `LCHAT_DB` to a path on it (e.g. |
| 269 | `/data/lchat.db`); the database must survive restarts and redeploys. |
| 270 | - Bind the port the platform gives you: `ADDR=:$PORT` (or the default `:1747`). |
| 271 | - Let the platform terminate **TLS** — and make sure it proxies the `/ws` |
| 272 | WebSocket upgrade (all of these do). |
| 273 | - Set a URL-safe `LCHAT_ADMIN_TOKEN`, and keep the service at **one instance** |
| 274 | (SQLite is single-writer — don't scale to multiple replicas). |
| 275 | |
| 276 | A tested, per-platform write-up (a `fly.toml`, a Render blueprint, an `app.json`) |
| 277 | would be a welcome contribution. |
| 278 | |
| 279 | ## Flow |
| 280 | |
| 281 | 1. **Admin** opens the admin link (roster management only — no decryption key) and |
| 282 | creates invites. Each invite → a secret link. |
| 283 | 2. **A guest** opens their link, picks a screen name, and joins — their browser |
| 284 | generates a keypair and registers its public key on the roster. |
| 285 | 3. Anyone can start a **DM** with another member or spin up a **group**; each |
| 286 | thread gets its own key, wrapped to its members. The instance is the trust |
| 287 | boundary (its roster), à la a private Slack/iMessage. |
| 288 | |
| 289 | ## Posting from a script (bots, cron, CI) |
| 290 | |
| 291 | You can post into a thread from outside the browser **without weakening the |
| 292 | encryption**. The trick: the encryption stays on *your* side, never the server's. |
| 293 | Each thread has its own AES key, wrapped to every member's keypair. So a script |
| 294 | posts as a real member: give it that user's **device token** (authorises the API) |
| 295 | and **private key** (unwraps the thread key), plus the **thread id**. The helper |
| 296 | fetches the thread's wrapped key, unwraps it locally, encrypts the message, and |
| 297 | hands the server only ciphertext — exactly like the browser does. |
| 298 | |
| 299 | ```sh |
| 300 | # text as an argument |
| 301 | tools/lchat-post.mjs --host https://group.example.com \ |
| 302 | --token "$TOKEN" --priv "$PRIV" --thread "$TID" "deploy finished ✅" |
| 303 | |
| 304 | # or pipe it in, with a custom screen name (config via env) |
| 305 | echo "build #42 passed" | tools/lchat-post.mjs --thread "$TID" --name CI |
| 306 | ``` |
| 307 | |
| 308 | Config can come from flags or `LCHAT_*` env vars (`LCHAT_HOST` / `LCHAT_TOKEN` / |
| 309 | `LCHAT_PRIV` / `LCHAT_THREAD`, and `LCHAT_NAME` for the screen name). The token |
| 310 | and private key come from a joined session (or an add-device link). The helper |
| 311 | reuses `web/static/crypto.js`, so its blobs are byte-for-byte what the browser |
| 312 | produces and render as ordinary chat messages. |
| 313 | |
| 314 | Under the hood it `POST`s to `/api/messages?token=…` with |
| 315 | `{"thread_id":"…","blob":"<ciphertext>"}`. The server checks the poster is a |
| 316 | member of that thread, then stores, broadcasts, and pushes it just like a |
| 317 | WebSocket `msg` frame — **it never sees the plaintext, the private key, or the |
| 318 | thread key.** Keep those on the calling host, never on the server, so the server |
| 319 | holds only ciphertext it can't open (the message-content guarantee above). |
| 320 | |
| 321 | ## Accessibility |
| 322 | |
| 323 | Eleven Messenger commits to **[WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/)** |
| 324 | across the web surfaces, and to the same bar on iOS/Mac via VoiceOver, Dynamic |
| 325 | Type, and Reduce Motion support. The full statement — what the commitment means |
| 326 | for UI changes, and where we honestly are today — is |
| 327 | **[docs/accessibility.md](docs/accessibility.md)**. |
| 328 | |
| 329 | ## Tests |
| 330 | |
| 331 | ```sh |
| 332 | go test ./... # backend: DB logic, HTTP handlers (httptest), router control plane |
| 333 | npm test # frontend logic in Node: crypto, ui/format, mini-apps, commands, |
| 334 | # invites, key backup, thread keys, messages |
| 335 | ``` |
| 336 | |
| 337 | The Go tests cover the invite lifecycle, admin auth, messages, push subscriptions, |
| 338 | the group name + HTTP handlers (auth gating, invite/messages flow, group-name |
| 339 | injection + HTML-escaping), and the self-hosted router / versioned-deploy control |
| 340 | plane. `npm test` runs the pure-logic frontend modules under Node — the E2EE |
| 341 | round-trip in `crypto.js`, plus `ui.js`/`format.js`, mini-apps, slash-commands, |
| 342 | invites, and key backup. Browser/DOM end-to-end (the chat UI, onboarding) isn't in |
| 343 | CI yet — exercise it against a throwaway instance. |
| 344 | |
| 345 | ## Layout |
| 346 | |
| 347 | ``` |
| 348 | main.go HTTP routing, handlers, admin bootstrap, //go:embed |
| 349 | db.go SQLite: config, invites, messages (ciphertext only) |
| 350 | hub.go WebSocket fan-out hub + message ingest |
| 351 | miniapps.go mini-apps: scheduled messages + per-thread encrypted state |
| 352 | push.go Web Push (self-hosted VAPID); apns.go = central APNs relay client |
| 353 | unfurl.go OpenGraph link previews (SSRF-guarded fetch + cache) |
| 354 | bootstrap.go, control.go, registry.go, router.go, versions.go, bot.go |
| 355 | self-hosted router: provision a box, add-instance / deploy / |
| 356 | rollback, the route registry, TLS front door, versioned deploys |
| 357 | web/pages/*.html chat / join / admin pages |
| 358 | web/static/crypto.js Web Crypto (encrypt/decrypt JSON + bytes, key wrap/unwrap) |
| 359 | web/static/shell.js chat page host: sidebar, thread list, WebSocket, keys, uploads |
| 360 | web/static/apps/*.js mini-app framework + apps, including the chat engine (chat.js) |
| 361 | web/static/*.js also join, admin, and pure ui/format helpers (unit-tested) |
| 362 | web/static/style.css styles |
| 363 | tools/lchat-post.mjs CLI to post an encrypted message from a script (see above) |
| 364 | docs/*.md design notes (router, threads/DMs, push relay, mini-apps, …) |
| 365 | ``` |
| 366 | |
| 367 | ## Licence |
| 368 | |
| 369 | [The Mozilla Public License, Version 2.0](LICENSE) — an OSI-approved, |
| 370 | file-level ("weak") copyleft licence: modifications to this code stay open |
| 371 | under the same terms, while a separate work that merely depends on it isn't |
| 372 | dragged open with it. |
| 373 | |
| 374 | This is an interim choice, not a final one. In the spirit of |
| 375 | [the Eleven Factors](https://11factor.org), the project's longer-term goal |
| 376 | is a purpose-drafted licence — provisionally named GAIEST, the *Generative |
| 377 | Artificial Intelligence Evolving Software Technology Licence* — that also |
| 378 | closes the copyleft gap for hosted/SaaS use and carries a real disclosure |
| 379 | requirement for AI-written material, once that draft has been through |
| 380 | proper legal review and an OSI submission. Until then, AI-authorship |
| 381 | marking is a **project convention**, not a licence condition — see |
| 382 | [docs/ai-markers.md](docs/ai-markers.md). |
| 383 | |
amadan