Introduction

Document status: v0.4.0 — draft, unreleased (see the Changelog). Implementation reference: construct-core 0.48.x (see Implementation Status). Document license: CC BY 4.0 · Reference implementation: Apache-2.0.

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 mandatory hybrid post-quantum handshake (PQXDH v2): an ML-KEM-1024 (NIST FIPS 203) secret enters the initial root key beside the X25519 outputs, so every message — the first included — is protected by both.

• Sessions that renew by sending: a device keeps a few previous states, and an unreadable message is answered with a decryption error naming the state it was written on. There is no reset message to forge, replay or ration.

• A sparse continuous post-quantum ratchet (Suite 4) that adds new ML-KEM-768 contributions after session establishment, one derived key per message since construct-core 0.24.0 (§2.4).

  Post-quantum protection covers the content of one-to-one messages and attachments, who sent a sealed one-to-one message, and the key exchange of calls. Server signatures, device authentication, groups and Privacy Pass are still classical; Threat Model — Post-quantum coverage lists every layer.

• 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

Document layout