Security Implementation Plan

Direction

Use Cisco MLS++ (mlspp) as the only end-to-end encryption protocol engine. Every secure conversation is an MLS group: direct chats, group chats, member changes, new devices, and key rotation all map to MLS group operations.

Current Repository Shape

Keep the module aligned with the rest of Reaktor: Gradle/KMP lives in the normal src/*Main layout, native code lives under cpp/, TypeScript lives under ts/, and generated Kotlin externals are produced through Karakum into ts/import.

reaktor-security/
  cpp/
    external/mlspp/
    external/json/
    external/googletest/
    rsec-mls-core/
    rsec-mls-capi/
    tests/native/
  src/
    commonMain/
    androidMain/
    iosMain/
    jsMain/
    jvmMain/
  ts/
    export/
    import/
    package.json
    karakum.config.json
  README.md
  THIRD_PARTY_LOCK.md

Hard Blocker

Durable MLS state snapshots are the first serious implementation blocker. The engine must prove that a process can create a group, persist encrypted state, restart, reload state, process the next message, and send the next message deterministically.

RsecMlsStateSnapshotV1 must cover:
  cipher suite
  group id and epoch
  public and private tree state
  transcript hash
  extensions
  epoch secrets and message ratchet state
  own leaf index
  identity private key references
  external and resumption PSKs
  pending proposals and cached update

Preferred path: keep a small audited patch against vendored MLS++ that adds State::export_snapshot() and State::import_snapshot(). That is easier to review than reconstructing state through derived-class access to protected internals.

Execution Phases

Task Backlog

Server Protocol Surface

Spring Boot/Postgres and Cloudflare Worker/D1/Durable Objects should implement the same client-visible protocol. The client SDK should not care which backend is deployed.

POST /security/devices/register
POST /security/key-packages
POST /security/key-packages/claim
POST /security/conversations
POST /security/conversations/{id}/messages
GET  /security/conversations/{id}/messages
GET  /security/welcomes
POST /security/welcomes/{id}/consume

All server-side authorization decisions that affect membership must produce client-verifiable policy proofs. Clients must reject server-added devices or members without valid Reaktor-auth-signed credentials and membership proofs.

P0 Completion Bar

• MLS++ native core is pinned and documented in THIRD_PARTY_LOCK.md.
• C ABI owns stable buffer/result/error behavior and does not leak C++ exceptions.
• Kotlin common and TypeScript APIs expose conversation operations only.
• Karakum generates Kotlin externals from reaktor-security/ts.
• Host C++ tests live under cpp/tests/native and pass through CTest.
• Gradle sync succeeds when reaktor is consumed from BestBuds and Manna composite builds.

Do Not Implement

• No Signal provider.
• No low-level crypto API for app developers.
• No raw key export API.
• No server-side decrypt API.
• No plaintext search.
• No metadata privacy claims beyond what the implementation actually provides.
• No silent plaintext fallback on Linux or Web.
• No unpinned MLS++ dependency.
• No JSON signatures for security-critical credentials or policy proofs.

References

1. Cisco MLS++
2. RFC 9420 - Messaging Layer Security
3. Emscripten
4. Android Keystore
5. Apple Keychain Services
6. Windows DPAPI CryptProtectData
7. Freedesktop Secret Service API
8. Web Crypto API
9. Cloudflare D1
10. Cloudflare Durable Objects