Introduction
Document status: v0.1.2 — early draft. Implementation reference:
construct-corev0.9.x (see Implementation Status). Document license: CC BY 4.0 · Reference implementation: MIT.
This document is the public technical specification of the Konstruct messenger protocol — what it does, how it does it, and where it provably falls short today.
It is written against the open-source reference implementation. Every
algorithmic claim in this document is verifiable by reading the cited
source file in the konstruct-msg/construct-core repository. If
something in the text does not match the code, the code wins and the
text is a bug — please open a security advisory.
Looking for a single-page read? → View the whole specification as one page (concatenated, searchable with Ctrl+F).
What Konstruct is
A messenger protocol built on the Signal Protocol design — X3DH handshake + Double Ratchet for ongoing messaging — extended with:
- A hybrid post-quantum KEM (ML-KEM-768, NIST FIPS 203) layered alongside the classical X25519 key exchange.
- A sparse continuous post-quantum ratchet (Suite 3) that can add new ML-KEM-768 contributions after session establishment.
- Metadata-minimising sealed sender, backed by Privacy Pass tokens for abuse resistance.
- A pluggable transport layer (VEIL) designed to keep the messenger reachable when the network operator is hostile.
- A binary FFI envelope (CFE) so the Rust crypto core can be shared unchanged across iOS, macOS, Android, and desktop clients without exposing a JSON parsing attack surface.
What this document is not
- Not a security audit. No third-party cryptographic audit has been performed at the time of writing. The text identifies known open issues but does not certify the absence of others.
- Not a marketing site. Public-facing positioning lives at konstruct.cc. This document is for implementers, auditors, and readers who want the protocol at the level of cryptographic detail needed to reason about it or build a compatible client.
- Not a full protocol RFC. This draft now includes the 1:1 wire formats and error registry, but federation and group messaging are still documented at status/design level rather than as complete independent interop specifications.
Conventions
This specification uses RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY) where it makes a normative requirement on an implementation. Descriptive prose uses ordinary English.
Code references take the form path/to/file.rs:LINE and point at the
public reference implementation
(construct-core).
Honest current status
| Area | Status |
|---|---|
| Cryptographic core (X3DH, Double Ratchet, hybrid PQ KEM, Suite 3 PQ ratchet) | Implemented and used in production by the iOS TestFlight build. |
| iOS / macOS client | Production-quality code, distributed via TestFlight beta. No public App Store release yet. |
| Android client | Phase 0 — Rust core cross-compiles and UniFFI bindings exist; no shipping Kotlin product surface yet. |
| Federation (server-to-server) | Implemented — inbound + outbound sealed delivery, Ed25519-signed. Multi-node interoperability test outstanding. |
| Sealed sender | Implemented and on by default — all in-scope outgoing user traffic (messages, receipts, call signalling, session-control handshake) is sealed and leaves no server-readable sender id in sealed delivery; identified-downgrade paths are fail-closed. Privacy Pass token enforcement runs in warn mode (not enforce). |
| MLS group chat | Core implemented and documented in Chapter 12 as design / partial; no shipping product surface and not yet a full normative interop spec. |
| QUIC / HTTP-3 transport | In production — engine-QUIC direct path, plain QUIC in release, with an HTTP/2 fallback. |
| VEIL veil-front (honest-front transport) | In production — the primary obfuscation transport for censored networks. |
| VEIL obfs4 / WebTunnel (legacy) | Retired — cut by active DPI in the target region; superseded by veil-front, standalone relay archived. |
| External security audit | Planned. Not yet performed. |
Document layout
| Chapter | Audience |
|---|---|
| Threat Model | Who Konstruct protects against, who it doesn't. Read first. |
| Cryptographic Primitives | Exact algorithm choices, key sizes, library versions. |
| Identity & Key Hierarchy | Long-term, medium-term, and per-session keys. |
| Session Handshake | X3DH and the post-quantum extension PQXDH. |
| Message Encryption | Double Ratchet, AEAD framing, associated data. |
| Transport Layer | gRPC over TLS, VEIL anti-censorship, CFE binary envelope. |
| Implementation Status | What works, what's open, what's planned. |