From 6a26668d72a12450852fa3d2be006ff17cd649bd Mon Sep 17 00:00:00 2001 From: Paul Hitt Date: Fri, 28 Aug 2026 09:27:09 -0400 Subject: [PATCH] Port the README rewrite the split raced past The third of three: this README was rewritten upstream after the split was cut, so the standalone repository still opened with 'Nothing here is an app yet' above the finished app - the exact staleness the rewrite existed to fix. Co-Authored-By: Claude Opus 5 --- README.md | 88 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index b362197..52f1b3c 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,55 @@ # Flamenet Messenger — Android -Nothing here is an app yet. This is the engine, and it is deliberately first. +The Android app, and the two libraries under it. -An Android client needs the protocol implemented a third time. That third +``` +engine/ the protocol: X3DH, Double Ratchet, sealed sender, safety numbers, + key transparency. Plain Kotlin/JVM — no Android in it at all. +client/ the relay transport: HTTP, auth, the §8 routes. +app/ the Compose app. +interop/ the cross-engine driver; not shipped. +``` + +`engine` and `client` are deliberately plain JVM libraries. The protocol has +nothing to do with Android, and keeping it off the platform means their tests +run anywhere a JVM does — no SDK, no emulator, no device, which is also what +lets them gate in CI on Linux: + +``` +./gradlew :engine:test :client:test +``` + +The app's own unit tests need the Android SDK but still no emulator +(Robolectric): + +``` +./gradlew :app:testDebugUnitTest +``` + +## Where it stands + +**[PARITY.md](PARITY.md) is the definition of done for this app — read that, +not this.** Every row there names the iOS file it came from so it can be +re-checked rather than trusted. Headlines as of 2026-08-28: messaging, groups, +attachments, voice notes, stories, calls, sealed sender, key transparency and +the encrypted vault are built and tested; a cross-platform round trip against +iOS was verified on 2026-08-26. + +⚠️ **This file said "Nothing here is an app yet" until 2026-08-28**, above a +tree containing the finished app — the README described the repository as it +was when the engine landed and nothing updated it as the app grew around it. If +a claim here ever disagrees with PARITY.md or with the tree, believe those, and +fix this. + +## Why the engine came first, and is held to the vectors + +An Android client needs the protocol implemented a third time, and the third implementation is the one that finds the places where the specification says less than the two existing engines quietly agreed on — but only if it is written against the spec and the published vectors rather than against a -reading of our own Swift and JavaScript. So the engine comes first, it is a -plain Kotlin/JVM library with no Android in it at all, and it is held to -`engine/test/vectors/protocol-v1.json` — the same file the other two engines -are checked against, read from that one location rather than copied here. - -``` -./gradlew :engine:test -``` - -No Android SDK, no emulator, no device. It runs anywhere a JVM does, which is -also what lets it run in CI on Linux. - -## What the engine covers today - -| Area | Spec | State | -|---|---|---| -| Safety numbers | §7 | **Done** — fingerprints and conversation ordering match the published vectors | -| Key transparency verification | §19 | **Done** — RFC 6962 leaf/node hashing, unbalanced split, bottom-up audit paths | -| Byte helpers | — | Unsigned comparison, constant-time equality | - -## What it does not cover - -Listed rather than left to be discovered, because a table of green ticks with -the hard parts quietly missing is worse than no table: - -| Area | Spec | State | -|---|---|---| -| X25519 / Ed25519 | §3 | Not started — needs a provider that works on both JVM and Android | -| X3DH key agreement | §4 | Not started | -| Double Ratchet | §6 | Not started | -| Sealed sender | §12 | Not started | -| ML-KEM-768 hybrid | §11 | Not started | -| ML-DSA-65 identities | §20 | Not started | -| Relay client | §8 | Not started | -| The app itself | — | Not started | - -Until those exist, Android is honestly marked "not started" on the website, and -a conversation gets the protocol's guarantees only when both ends are iOS. - -## Why the vectors matter more than the code +reading of our own Swift and JavaScript. So the engine is held to +`engine/test/vectors/protocol-v1.json`, the same file the other two engines are +checked against. Two implementations that agree may both be wrong in the same way, especially when one was written while reading the other. The audit-path ordering in §19 is