Introduction

Document status: v0.1.2 — early draft. Implementation reference: construct-core v0.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

Document layout

Architecture Overview

Orientation chapter. This is the map of the whole system: how the cryptographic core (Message Encryption) and the Transport Layer fit together, and how Konstruct stays reachable as a network operator turns hostile. It is descriptive architecture — normative (RFC 2119) requirements live in the per-component chapters it points to. For the authoritative per-component build state, see Implementation Status.

Konstruct is a layered system with one invariant at the bottom and a ladder of reachability strategies above it. The invariant: end-to-end encryption is always on and never depends on any server (see Threat Model and Message Encryption). Everything above the crypto core exists to answer a single question — can this message reach its recipient? — as the network becomes more adversarial, degrading gracefully from a fast direct connection down to a device-to-device mesh that needs no network at all.

Design position

Four goals pull against one another. Konstruct takes a deliberate position rather than pretending to maximise all four at once:

The anonymity position is load-bearing enough to state precisely. Konstruct provides pseudonymity with no real-world anchor, not unlinkability against a global observer:

A mixnet (Sphinx packets, per-hop cover traffic) would add network-layer unlinkability at a large cost to usability and — being enumerable — to censorship-resistance itself. For Konstruct's users that tradeoff is not worth it; the sealed-sender ceiling is the accepted metadata boundary.

The layered model

Above the always-on cryptographic floor, the system is five layers plus an offline foundation. Each is a distinct concern with its own implementation; they are composed, not merged.

   always-on floor ─── E2EE (Double Ratchet · sealed sender)  ·  identity = public key (no PII)
   ══════════════════════════════════════════════════════════════════════════════════════
   ▲ outward path
   │  Transport        move bytes + obfuscation   (QUIC/H3 · veil-front HTTPS · H2 fallback)
   │  EntryDirectory   find a reachable, un-burned entry point
   │  RouteLayer       a single proxy hop that hides the user's IP from the server
   │  Overlay          location-independent addressing & discovery (route_id, DHT)
   │  Delivery         federation, store-and-forward, trust posture
   ▼
   Mesh floor          device-to-device with no network at all   (foundation)

route_id is the SHA-256 of the account's identity public key. Because it is derived from the key and carries no location, an account can move between servers (or onto a domestic island, or onto the mesh) and remain addressable — this is what makes zero-configuration re-homing and the offline mesh share one identity model.

Graceful degradation by network tier

The layers active at any moment depend on how hostile the network is. The same system reconfigures itself down the ladder:

Two properties of this table matter. First, obfuscation answers "can they tell what this is?", not "can this arrive at all?" — under an allowlist the censor drops a packet by destination before inspecting it, so the answer there is not a better disguise but an in-zone deployment that never needs to cross the border (in-country federation, a domestic-only overlay). Second, veil-front has no transport fallback beneath it; if its relay is blocked, reachability depends on the EntryDirectory layer having diverse entries, and ultimately on the mesh floor. The layers are coupled: finishing the transport is not the same as finishing censorship-resistance.

The offline mesh floor (design)

The lowest rung keeps two people messaging with no infrastructure at all — a total blackout or a fully sealed island. It is a parallel offline mini-stack that supplies its own addressing, routing, and store-carry-forward, and it carries opaque Konstruct end-to-end payloads — it does not replace the message crypto.

The design direction adopts Reticulum (a cryptographic networking stack that routes over any medium) as the overlay, for two reasons: its destination addressing is a hash of a public key, which maps directly onto Konstruct's route_id; and it is medium-agnostic, so "which radio" becomes a pluggable interface rather than a new routing engine.

Message security remains Konstruct's end-to-end layer; a mesh relay learns no more than an online sealed-sender relay does. This rung is analysis-stage: the gating questions are the Rust implementation path and cross-platform local interoperability, to be resolved by a laptop-first spike before any mobile work.

What the architecture does and does not provide

Consistent with Transport §6.6, stated for the whole system:

Provided: content confidentiality and integrity (E2EE, always on); no link between an account and a real-world person; sealed sender removing sender identity from sealed delivery requests; the user's IP hidden from the home server; the home server's IP hidden from the censor; and continued operation as the network degrades — including, by design, with no network.

Not provided: unlinkability of who-talks-to-whom against an adversary who observes both ends or correlates timing; recipient identity at the delivering node; connection metadata (times, sizes, IPs a relay itself sees). A single relay hop is IP-hiding, not anonymity, and Konstruct does not claim otherwise.

Where the detail lives

Threat Model

This chapter defines who Konstruct claims to protect against, who it explicitly does not, and the assumptions on which every later chapter rests. Read it before reading the rest — a security property only means something against a specific adversary class, and most disagreements about "is X secure" reduce to disagreements about which adversary the discussion has in mind.

Adversary classes (in scope)

Network adversary

Capabilities: full passive recording of traffic between any two endpoints; full active control of the network path (drop, inject, modify, reorder, replay); deep-packet inspection and traffic classification; observation across multiple vantage points (e.g. recording at both ISP and at a transit AS).

What Konstruct guarantees against this adversary:

• Plaintext confidentiality — recovered traffic decrypts to nothing more than ciphertext blobs and routing-shaped metadata.
• Tamper detection — any in-flight modification of a Double Ratchet ciphertext is rejected by AEAD.
• Forward secrecy — recording today does not enable decryption later if a long-term key is later compromised.
• Quantum-recording resistance — recording today does not enable decryption later by a quantum-equipped attacker, for sessions that used Suite 2 (PQXDH). Suite 1-only sessions are vulnerable in this scenario.

What Konstruct does not guarantee:

• That a sufficiently sophisticated network adversary cannot infer that communication is happening. The transport layer reduces this surface (VEIL, padding, cover traffic) but does not eliminate it.

Server adversary

Three sub-classes, treated together because the design is the same: honest-but-curious, malicious, fully compromised. Konstruct's server is blind to message content by construction — the same key material the client uses to decrypt simply is not on the server.

Sealed sender is deployed and on by default. Outgoing user traffic — messages, delivery receipts, call signalling, and the session-control handshake — is sealed: ordinary sealed sends use the dedicated SendSealedMessage RPC whose request carries only sealed_sender bytes plus an optional attempt id; transitional session-control paths may still carry Envelope.sealed_sender, but the outer sender, conversation id, and real content type are omitted. In both paths the client seals a server-issued sender certificate to the recipient's identity key, so only the recipient can recover who sent a message. A compromised server therefore cannot read sender_id from sealed traffic and cannot directly reconstruct the sender_id → recipient_id edge for a sealed message.

• Client policy (always-on in release builds): construct-ios Services/StealthPolicy.swift:42 (isEnabled), :71 (shouldUseSealedSender).
• Client transport: construct-ios Networking/gRPC/Services/MessagingServiceClient.swift:203-:225 (sendSealedMessage uses no outer Envelope, sender, conversation id, or content type).
• Legacy sealed control transport: construct-ios Networking/gRPC/Services/MessagingServiceClient.swift:35-:68, :269-:351; construct-server messaging-service/src/grpc.rs:333-:360.
• Sealed-inner construction: construct-ios Security/StealthSenderService.swift:400-:415 (ordinary traffic omits content_type; only structural sealed-sender exceptions are visible before decrypt).
• Server handling: construct-server messaging-service/src/grpc.rs:701-:750 (send_sealed_message deliberately does not extract an authenticated user id) and messaging-service/src/envelope.rs:140-:270 (dispatch_sealed_sender routes from SealedInner without a sender).

What the server can still see today (single-trusted-server alpha), even with sealed sender:

• The recipient identifier, delivery tag, token fields, payload size, and delivery timestamp of each sealed message. The sender is not in the SendSealedMessage request or the plaintext SealedInner; it is inside sender_cert_ciphertext.
• The pre-existing contact graph — contact relationships are stored to route message streams.
• Ciphertext size after padding and traffic timing/volume.
• Connection metadata at the network layer: the source IP address (unavoidable for packet routing), transport handshake characteristics, and session durations. The server does not store the raw IP — its anti-abuse rate-limit keys and logs use a salted one-way hash of the address (construct-utils/src/lib.rs:92 hash_client_ip, applied in construct-user-service/src/account.rs:140 and construct-auth-service/src/devices.rs:292). The honest limit: a salted hash of the small IPv4 address space is not perfectly anonymous against a party holding the salt — it removes the raw address from storage, it does not make the origin undiscoverable.
• The encrypted payload bytes (it must, in order to route them).

Anti-abuse tokens (Privacy Pass) accompany sealed sends. Server-side token enforcement (MSG_STEALTH_TOKEN_POLICY) currently runs in warn mode, not enforce — see Implementation Status.

Historical device adversary

Capability: after a session has been used for some period of time, obtain a snapshot of a participating device's state (key material at rest, session state, message history).

Konstruct guarantees:

• Past message confidentiality up to the moment of compromise (forward secrecy via the Double Ratchet's per-message key derivation and key eviction).
• Self-healing of future messages after at most one round-trip via the DH ratchet step — provided the attacker is no longer active in the network path.

Spam / Sybil adversary

Capability: automated mass registration; commodity GPU farms; disposable IP pools.

Konstruct deters this with a memory-hard proof of work at registration (Argon2id, see Cryptographic Primitives) and server-side rate limits. Full prevention of nation-state-resourced Sybil attacks is not a Konstruct goal — that would require identity verification, which is incompatible with privacy goals elsewhere in the design.

Out of scope (explicit non-goals)

Konstruct does not defend against:

• A live compromise of an unlocked device at the moment of decrypt. If the attacker has the running process, no end-to-end protocol can help.
• OS-, kernel-, or secure-enclave-level compromise of the host platform. Keys are stored using platform key stores (on iOS, the Keychain; crypto and Double-Ratchet session state that must survive a background/locked push-decrypt is gated kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly — construct-ios Security/KeychainManager.swift:21 cryptoKeyAccessible); if those primitives are broken, so is everything that relies on them.
• Hardware-level side channels (Spectre, power analysis, EM emanations). Software-level constant-time primitives (subtle crate, audited AEAD implementations) are used where they apply; this does not extend to physics.
• Coercion of the user. A protocol cannot stop a person from being forced to unlock their phone.

Security goals — formal statement

Trust assumptions

• Trusted today (would compromise security if breached): the local device's OS and key store; the bundled construct-core binary; the audited Rust cryptography crates listed in Cryptographic Primitives; the user's choice not to expose their device to an active attacker.
• Untrusted today: the network path; the server (for message content); other users (until they are explicitly added as contacts).
• Trust shrinks over time, by design: the federation roadmap is intended to remove the single-trusted-server assumption; the veil-front transport is intended to reduce reliance on the network not being adversarial.

The remainder of this specification proceeds from this threat model. A property described later as "secure" means "secure against the adversary classes above and no others".

Cryptographic Primitives

This chapter enumerates every cryptographic primitive that an interoperable Konstruct implementation MUST use, with concrete parameters, byte sizes, and crate-level references to the verified reference implementation. Three core suite identifiers are currently accepted by construct-core: Suite 1 (classical), Suite 2 (PQXDH hybrid KEM + optional hybrid signatures), and Suite 3 (sparse continuous ML-KEM-768 ratchet).

Keywords MUST, MUST NOT, SHOULD, MAY are per RFC 2119.

2.1 Suite identifiers

Each session is parameterised by a suite identifier. The suite is fixed at handshake time and MUST NOT change for the lifetime of the session.

The suite identifier appears in the WirePayload header (Chapter 5 §5.3) and MUST be checked by the receiver before any cryptographic operation; a mismatched suite MUST cause the message to be rejected. In the WirePayload header it is encoded as u16 little-endian (construct-core/src/wire_payload.rs:15, :106-:129). Signature prologues use their own explicitly-specified byte order (§2.2.2). The accepted IDs are defined in construct-core/src/crypto/suite_id.rs:22-:33.

2.2 Suite 1 — Classical (always active)

2.2.1 X25519 key agreement

• Curve: Curve25519 per RFC 7748.
• Crate: x25519-dalek 2.0 with the reusable_secrets and static_secrets features.
• Public key size: 32 bytes (Montgomery form, encoded little-endian).
• Private key size: 32 bytes (clamped scalar).
• DH operation: DH(a, B) = scalar_mult(a, B). Output: 32 bytes.
• Implementations MUST clamp scalars per RFC 7748 §5; the dalek crate does this internally.
• Implementations MUST validate that received public keys are not all-zero (which would force the DH output to zero). The reference inherits this check from dalek.

2.2.2 Ed25519 signatures

• Algorithm: Ed25519 per RFC 8032.
• Crate: ed25519-dalek 2.0 with the std and rand_core features.
• Public key size: 32 bytes.
• Private key (signing key) size: 32 bytes (seed) or 64 bytes (expanded). The reference uses the 32-byte seed form.
• Signature size: 64 bytes (R || S, each 32 bytes).
• Verification: Verify(VK, M, sig) → ok | error. The reference uses VerifyingKey::verify_strict where strict validation is required.
• An interoperable signer MUST sign the same canonical encoding of the signed artefact. Signed artefacts in this specification are:
  • X25519 signed prekey: Ed25519_Sign(SK_priv, b"KonstruktX3DH-v1" || [0x00, 0x01] || SPK_pub).
  • ML-KEM-768 signed prekey: Ed25519_Sign(SK_priv, b"KonstruktX3DH-v1" || [0x00, 0x10] || KEM_pub).
  • Hybrid identity binding: Ed25519_Sign(SK_priv, b"KonstruktHybridId-v1" || hybrid_identity_key).

spk_rotation_epoch is a freshness/replay field carried beside the prekey in the bundle; it is not part of the current prekey signature message. Server verification builds the prekey message in construct-server/key-service/src/core.rs:150-:179; the shared hybrid helper builds the same bytes in construct-server/crates/construct-crypto/src/pqc/hybrid.rs:55-:65.

2.2.3 ChaCha20-Poly1305 AEAD

• Algorithm: ChaCha20-Poly1305 per RFC 8439.
• Crate: chacha20poly1305 0.10 with the std and getrandom features.
• Key size: 32 bytes.
• Nonce size: 12 bytes. Each AEAD invocation in Konstruct uses a freshly random nonce (never a counter-derived nonce); see Chapter 5 §5.5.
• Tag size: 16 bytes (Poly1305).
• Associated Data: variable; the AD construction for Double Ratchet messages is specified in Chapter 5 §5.4.
• The plaintext input to the AEAD MUST be the PKCS#7-padded plaintext (§5.7), not the raw application bytes.

ChaCha20-Poly1305 is the AEAD for Double Ratchet message payloads. A second AEAD is used for media attachments (photos, video, files, voice messages): each attachment is encrypted client-side with AES-256-GCM under a fresh per-file 256-bit key, wire format nonce(12) || ciphertext || tag(16), before upload. The per-file key never reaches the media server — it travels end-to-end inside the (ChaCha20-Poly1305-sealed) message, so the server stores only an opaque encrypted blob. Reference: construct-ios Services/MediaUploadService.swift:83 (decryptMediaData, 32-byte AES-256-GCM key). AES-256-GCM here rides Apple/hardware-accelerated CryptoKit; the Double Ratchet deliberately stays on ChaCha20-Poly1305.

2.2.4 HKDF-SHA-256

• Algorithm: HKDF per RFC 5869, instantiated with SHA-256.
• Crate: hkdf 0.12.
• Several distinct HKDF invocations appear in the specification, each with a normative info byte string. Implementations MUST use the exact byte strings below.

The Double Ratchet root and chain KDFs are implemented in construct-core/src/crypto/suites/classic.rs:233-:257 and mirrored by the hybrid provider. The initial root normalisation is in construct-core/src/crypto/messaging/double_ratchet/messaging.rs:54-:59. The PQXDH and Suite 3 HKDF calls are in construct-core/src/crypto/messaging/double_ratchet/internals.rs:62-:99 and :280-:438.

2.2.5 PBKDF2 (password-based KDF)

• Algorithm: PBKDF2 per RFC 8018, HMAC-SHA-256 PRF.
• Crate: pbkdf2 0.12 with the simple feature.
• Iterations (reference default): 100 000 (construct-core/src/config.rs:117).
• Use site: master-key derivation for at-rest encryption of recovery artefacts. PBKDF2 is not used in the wire protocol, only in application-level key wrapping.

2.2.6 Argon2id (anti-spam PoW)

• Algorithm: Argon2id per RFC 9106.
• Crate: argon2 0.5.
• Version: V0x13 (Argon2 v1.3).
• Parameters (reference):
  • Memory cost m = 32 768 KiB
  • Iterations t = 2
  • Parallelism p = 1
• Use site: registration proof-of-work, in construct-core/src/pow.rs. The server issues a fresh PoW challenge per registration attempt; the client returns a nonce whose Argon2id hash satisfies a difficulty target.

2.3 Suite 2 — Post-quantum extension (opt-in)

Suite 2 inherits all of Suite 1, and adds a hybrid post-quantum KEM whose shared secret is mixed into the root key after the first DH ratchet step (the "deferred" application; see Chapter 4 §4.5).

2.3.1 ML-KEM-768 (Kyber-768)

• Algorithm: ML-KEM-768 per NIST FIPS 203.
• Crate: ml-kem 0.3.0 (feature-gated as post-quantum).
• Encapsulation key size: 1184 bytes.
• Ciphertext size: 1088 bytes.
• Decapsulation (secret) key size: 2400 bytes (expanded form, as exposed by ExpandedKeyEncoding in the ml-kem crate). The reference exports the expanded form because re-derivation from a 32-byte seed adds runtime cost; both are equivalent at the protocol level.
• Shared secret size: 32 bytes.
• Operations:
  • (ek, dk) = MlKem768::Generate()
  • (ct, ss) = MlKem768::Encapsulate(ek)
  • ss = MlKem768::Decapsulate(dk, ct)
• Implementations MUST use the FIPS-203 final variant, not the earlier Kyber-768-R3 draft variant. The reference crate ml-kem 0.3.0 implements FIPS 203 final.

2.3.2 Hybrid design

The combined session security is determined by:

SK_root = HKDF(salt = F, IKM = DH_combined,
               info = "Construct-X3DH-RootKey-v1", L = 32)
RK₁     = (root after first DH ratchet step)
RK₁'    = HKDF(salt = RK₁, IKM = kem_ss,
               info = "construct-pqxdh-v1", L = 32)

Because RK₁' depends on both DH_combined (classical) and kem_ss (post-quantum), an adversary MUST break both components to recover plaintext. Breaking only X25519 leaves kem_ss as a 32-byte unknown input to the KDF; breaking only ML-KEM-768 leaves DH_combined similarly. This is the standard hybrid-security argument and the reason Suite 2 is constructed as KEM alongside rather than instead of classical X3DH.

2.3.3 Signatures in Suite 2

Suite 2 keeps Ed25519 signatures as the mandatory classical authentication path and adds optional, capability-gated hybrid signatures using ML-DSA-65 (Dilithium-3) per NIST FIPS 204. Hybrid signatures do not replace Ed25519 in the current wire format; they are an additional attestation over the same prekey sign-message.

The hybrid signature public key format is:

hybrid_identity_key = ed25519_pk(32) || mldsa65_pk(1952)       -- 1984 B
hybrid_signature    = ed25519_sig(64) || mldsa65_sig(3309)     -- 3373 B

The stored hybrid signing secret is ed25519_seed(32) || mldsa65_seed(32) || mldsa65_pk(1952) (2016 B). The device binds that independent hybrid identity key to its existing Ed25519 identity with Ed25519("KonstruktHybridId-v1" || hybrid_identity_key). Prekey-level hybrid signatures cover "KonstruktX3DH-v1" || [0x00, suite_id] || public_key, where suite_id = 0x01 for the X25519 SPK and suite_id = 0x10 for the ML-KEM-768 SPK. Reference sizes and verification behaviour: construct-core/src/crypto/suites/hybrid.rs:1-:51, construct-server/shared/proto/services/key_service.proto:248-:270, and construct-ios Security/HybridBundleVerifier.swift:34-:120.

If a bundle lacks hybrid fields, a conforming client MUST continue to accept the Ed25519-only path. If the hybrid identity cross-signature is present and invalid, the bundle MUST be rejected. If the hybrid identity is authentic but a prekey-level hybrid signature is missing or invalid, the reference client degrades to the classical Ed25519 attestation path instead of hard-failing reachability (HybridBundleVerifier.swift:72-:109).

2.4 Suite 3 — Sparse continuous PQ ratchet

Suite 3 (0x0003) is a ratchet-level extension, not a new protobuf CryptoSuite bundle value. A new session may negotiate Suite 3 only when the fetched bundle advertises supports_pq_ratchet; the iOS client maps bundle crypto-suite values only to core suite 1 or 2 and derives suite 3 from that capability (construct-ios Networking/gRPC/Services/KeyServiceClient.swift:418-:430; construct-core/src/crypto/client_api.rs:1082-:1152).

At a configured cadence, the designated Suite 3 initiator attaches an ML-KEM-768 encapsulation key to outgoing messages. The peer encapsulates once and re-attaches the ciphertext until the initiator activates the epoch. Completed PQ epoch secrets are not mixed into the Double Ratchet root or chain keys; instead, the per-message key is:

MK_pq = HKDF(salt = pq_epoch_secret,
             IKM = MK_dr,
             info = "construct-pqr-msg-v1", L = 32)

pq_message_epoch = 0 means no PQ epoch has been mixed yet. Unknown or evicted non-zero epochs are a hard decrypt error, because silently skipping the mix would be a downgrade. The implemented state machine is in construct-core/src/crypto/messaging/double_ratchet/internals.rs:276-:438.

2.4.1 Cadence and retention

The counter advances inside the DH ratchet step (internals.rs:217), so the unit is a DH ratchet turn — a change of conversational direction — not a message and not elapsed time. A one-sided burst of a hundred messages performs no DH step and so makes no PQ progress; sixteen alternations do. The reference implementation has no time-based floor.

A pending field is attached by encrypt to every outgoing frame (messaging.rs:385), which includes control frames such as delivery receipts. A peer that only sends receipts therefore both advances the turn counter and carries the exchange forward, without the user replying.

Retention is a hard bound with a hard consequence. A message naming an epoch that has already been evicted is a decrypt error, by the same no-silent-downgrade rule as an unknown epoch. Implementations that tolerate deeper reordering than the reference MUST raise the retention count rather than relax the error.

2.4.2 Normative rules for the sparse exchange

1. Commit on success only. PQ processing of a received frame — EK ingestion, ciphertext completion, epoch promotion — MUST run only after the carrying message has authenticated and decrypted. A malformed or hostile PQ field MUST NOT alter session state, and the classical delivery of its carrier MUST be unaffected. By construction an EK/CT field always rides on a frame tagged with a pre-completion epoch, so decrypting the carrier never depends on the material it carries (internals.rs:352-:388).

2. Re-attach until implicitly acknowledged. There is no explicit acknowledgement frame. The initiator re-attaches its EK to every outgoing message until a matching ciphertext arrives; the responder re-attaches its ciphertext until a peer message tagged at or above the provisional epoch arrives — which proves the initiator decapsulated the same secret, because that tag was just used successfully to derive the message key. A dropped message therefore costs bandwidth, never a stuck exchange (internals.rs:449-:466).

3. One exchange in flight. A new proposal MUST NOT be started while one is pending; the cadence counter simply retries on the next turn.

4. ek_hash disambiguates re-proposals. After an unanswered proposal is abandoned, the same epoch number may be re-proposed with a fresh keypair. The 8-byte ek_hash accompanying a ciphertext identifies which encapsulation key it completes; a ciphertext whose hash does not match the pending keypair MUST be ignored, and the local proposal kept.

5. Epoch secrets are constant within an epoch. The reference derives every message key of an epoch from the same pq_epoch_secret; the post-quantum component does not ratchet between rekeys. Forward secrecy within an epoch is supplied by the classical Double Ratchet alone. See Appendix B for how this compares with other deployed designs.

2.5 Randomness

All key generation, ephemeral keypair generation, and AEAD nonces MUST be sourced from a cryptographically secure RNG. The reference uses rand::rngs::OsRng for classical primitives and a separately-seeded getrandom-backed RNG for the ml-kem crate's PQ operations (getrandom_pq feature).

Implementations MUST NOT use deterministic or counter-derived randomness for any of the values above. A failure of the OS RNG MUST cause the operation to abort, not to proceed with a weak source.

2.6 Key zeroization

All ephemeral and per-message keys MUST be zeroised before their memory is released:

The reference uses zeroize / zeroize::Zeroizing from the zeroize 1.7 crate for these. Long-term keys (IK_priv, SK_priv) are kept in platform-protected storage; they are not zeroised at runtime because they are needed across process lifetimes.

2.7 Constants summary

For ease of cross-reference, all normative byte constants used in this specification:

These constants MUST be byte-identical between conforming implementations. Changing any of them produces an instantly non-interoperable handshake or AEAD failure.

2.8 References

• Reference implementation (single source of truth for parameters above): construct-core/, particularly src/crypto/, src/pow.rs, and Cargo.toml.
• NIST FIPS 203 (ML-KEM): https://csrc.nist.gov/pubs/fips/203/final
• NIST FIPS 204 (ML-DSA): https://csrc.nist.gov/pubs/fips/204/final
• RFC 7748 (X25519): https://www.rfc-editor.org/rfc/rfc7748
• RFC 8032 (Ed25519): https://www.rfc-editor.org/rfc/rfc8032
• RFC 8439 (ChaCha20-Poly1305): https://www.rfc-editor.org/rfc/rfc8439
• RFC 5869 (HKDF): https://www.rfc-editor.org/rfc/rfc5869
• RFC 9106 (Argon2): https://www.rfc-editor.org/rfc/rfc9106

Identity & Key Hierarchy

This chapter specifies, for an interoperable Konstruct implementation, what keys exist, how long they live, where they are stored, and what each one is used for. The structure mirrors the Signal Protocol's X3DH / Double Ratchet decomposition into long-term, medium-term, and ephemeral key material, extended with a parallel set of post-quantum keys.

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this chapter are to be interpreted as described in RFC 2119.

3.1 Identity model

A Konstruct identity is a 36-character UUID issued by the registration service. It MUST be treated as opaque by the protocol — all cryptographic operations are bound to keys, not to the identifier.

An identity may have one or more active devices. All E2EE key material is device-scoped: the server stores public keys only, never private keys, and the key-service protobuf explicitly treats all keys as device-specific (construct-server/shared/proto/services/key_service.proto:17-:18). A device is uniquely identified by a 32-character hex string derived deterministically from its identity public key (see §3.4).

Implementations MUST NOT mix the two identifier spaces — using a device-id where a user-id is expected (or vice versa) breaks the Associated Data (AD) check in the Double Ratchet AEAD and causes permanent decryption failure. The reference implementation enforces this through distinct Rust types (ServerUserId, CryptoDeviceId).

3.2 Key inventory

A registered identity holds, at minimum, the following key material. All keys MUST be generated with cryptographically secure randomness; the reference uses rand::rngs::OsRng.

The X25519 and Ed25519 sizes are fixed by the underlying curves (Curve25519, Edwards25519). The ML-KEM-768 sizes are fixed by NIST FIPS 203 (public key 1184 bytes, ciphertext 1088 bytes, secret key 2400 bytes in expanded form as exposed by the ml-kem crate). The hybrid signature sizes come from the implemented Ed25519 + ML-DSA-65 format in construct-core/src/crypto/suites/hybrid.rs:1-:51.

3.3 Long-term keys

Identity key (IK)

The X25519 long-term key. It MUST be generated once at registration and never rotated for the lifetime of the identity. Rotating it constitutes destroying the identity.

The private half MUST be stored in the platform's secure key store under an "after-first-unlock" access class equivalent (iOS: kSecAttrAccessibleAfterFirstUnlock; Android: hardware-backed Keystore with equivalent flag). The public half is published in the registration bundle (§3.6) and is what other parties run X25519 against.

Signing key (SK)

A separate Ed25519 keypair used only to sign prekey bundles. It MUST NOT be reused for any other purpose. Like the IK, it is permanent and stored in the platform key store. The split between IK (key agreement) and SK (signatures) follows the Signal convention and lets each algorithm be replaced independently.

A Konstruct signature, where it appears in this specification, is the 64-byte EdDSA signature over the canonical encoding of the signed artefact, verified with ed25519_dalek::VerifyingKey::verify.

3.4 Device identifier

device_id is the stable device key identifier used for device inventory, safety-number UX, Key Transparency leaves, and session tie-breaks. It is derived from the device identity public key as:

device_id = LOWER_HEX(SHA-256(IK_pub))[0..32]

i.e. the lower-case hexadecimal SHA-256 of the 32-byte X25519 identity public key, truncated to 32 characters (construct-core/src/device_id.rs:16-:45). An interoperable implementation MUST produce the same value from the same IK_pub.

device_id is not the Double Ratchet AEAD sender/receiver identifier in current AD. AD version 3 uses the sender and receiver server UUIDs plus the session id (§5.4).

3.5 Medium-term keys: signed prekeys

X25519 signed prekey (SPK)

The SPK is an X25519 keypair generated at registration. The shipping client rotates its own SPK every 7 days and force-rotates around day 8 (construct-ios Services/Crypto/PreKeyRotationService.swift:29-:35). The Rust core's clean peer-freshness boundary is SPK_MAX_AGE_SECS = 30 * 24 * 3600 (construct-core/src/crypto/client_api.rs:61-:71). A bundle older than this boundary is stale for the clean session-init path; the reference also exposes an explicit degraded init_session_allowing_stale path that skips only the freshness check while still verifying signatures (construct-core/src/crypto/client_api.rs:358-:396).

The SPK carries a spk_rotation_epoch: u32. Each rotation increments this counter monotonically. The current prekey signature does not include the epoch; clients use the epoch and timestamp as freshness signals beside the signed key.

When the application rotates the SPK, it MUST upload the new (public-key, signature, epoch) tuple to the server and SHOULD retain the previous SPK private half briefly so in-flight first messages that referenced the old bundle can still decrypt.

The Ed25519 signature over the X25519 SPK is computed over:

b"KonstruktX3DH-v1" || [0x00, 0x01] || SPK_pub

ML-KEM-768 signed prekey (KEM-SPK)

An ML-KEM-768 encapsulation key serving the analogous role for the post-quantum extension. Lifetime, rotation cadence, clean-freshness boundary, and epoch are identical to the X25519 SPK. A bundle whose KEM-SPK is older than SPK_MAX_AGE_SECS is stale for the clean Suite 2 path.

The KEM-SPK Ed25519 signature is computed over:

b"KonstruktX3DH-v1" || [0x00, 0x10] || KEM_pub

The public protobuf field names still say kyber_*; those names are legacy. The deployed KEM variant is ML-KEM-768 (Kyber-768), not Kyber-1024. If the optional hybrid identity key is present, the bundle may also include ML-DSA-65 hybrid signatures over the same SPK and KEM-SPK sign-messages (§2.3.3).

3.6 Ephemeral / one-time prekeys

X25519 one-time prekeys (OPK)

A pool of single-use X25519 keypairs uploaded with the registration bundle. Each OPK has a u32 identifier; the X3DH initiator (Alice) selects one and the server marks it consumed.

If the OPK pool drops below an implementation-defined threshold (the reference uses 20), the client MUST upload fresh OPKs. Running out of OPKs falls back to a 3-DH handshake without the OPK component, which has reduced forward secrecy (the protocol's BS-3 open issue — see Implementation Status).

ML-KEM-768 one-time prekeys (KEM-OPK)

A pool of single-use ML-KEM-768 encapsulation keys serving the same purpose for the post-quantum extension. The server SHOULD maintain the KEM-OPK pool with the same threshold logic as classical OPKs.

Absence of a KEM-OPK does not abort Suite 2 by itself: the initiator may encapsulate to the KEM-SPK and set kyber_otpk_id = 0. What is forbidden is silently downgrading to Suite 1 when the Suite 2 KEM-SPK or ML-KEM contribution is unavailable or invalid.

3.7 Per-session keys (Double Ratchet)

Once X3DH completes (Chapter 4), the session state machine maintains:

The Double Ratchet operations on these are specified in Chapter 5. Suite 3 state is persisted inside the CFE session-state payload as CfePqRatchetStateV1 (construct-core/src/cfe/types.rs:330-:418). Per-message keys MUST be zeroed immediately after AEAD decrypt; the reference uses zeroize::Zeroizing.

3.8 Key storage at rest

The reference implementation stores keys with the following access classes; an interoperable implementation SHOULD provide an equivalent guarantee on its platform:

The session blob currently stores dh_ratchet_private in cleartext within the platform-protected blob. Adding an additional encryption-at-rest layer is open work tracked as SEC-009 in the implementation status.

3.9 Public key bundle (wire format)

The directory bundle is a protobuf PreKeyBundle, not a packed binary struct. Protobuf owns scalar encoding on the service boundary; the canonical byte strings that are signed are specified separately in §3.5 and §2.3.3. The fields a responder publishes are:

PreKeyBundle ::=
    registration_id                  : u32
    identity_key                     : bytes      -- X25519 IK public
    signed_pre_key                   : bytes      -- X25519 SPK public
    signed_pre_key_id                : u32
    signed_pre_key_signature         : bytes      -- Ed25519 over SPK sign-message
    one_time_pre_key                 : optional bytes
    one_time_pre_key_id              : optional u32
    crypto_suite                     : CryptoSuite
    generated_at                     : int64
    spk_uploaded_at                  : int64
    spk_rotation_epoch               : u32

    -- Suite 2 PQXDH extension; proto names are legacy `kyber_*`.
    kyber_pre_key                    : optional bytes  -- ML-KEM-768 KEM-SPK
    kyber_pre_key_id                 : optional u32
    kyber_pre_key_signature          : optional bytes  -- Ed25519 over KEM sign-message
    kyber_one_time_pre_key           : optional bytes  -- ML-KEM-768 KEM-OPK
    kyber_one_time_pre_key_id        : optional u32
    kyber_spk_uploaded_at            : optional int64
    kyber_spk_rotation_epoch         : optional u32

    -- Server / transparency / PQ signature extensions.
    bundle_signature                 : bytes
    hybrid_identity_key              : optional bytes  -- 1984 B
    hybrid_identity_signature        : optional bytes  -- 64 B Ed25519 cross-signature
    signed_pre_key_hybrid_signature  : optional bytes  -- 3373 B
    kyber_pre_key_hybrid_signature   : optional bytes  -- 3373 B
    supports_pq_ratchet              : bool            -- Suite 3 capability

The current schema is in construct-server/shared/proto/services/key_service.proto:175-:270. supports_pq_ratchet is a capability flag: it allows a new session to negotiate core Suite 3, but it is not itself a protobuf CryptoSuite value.

A bundle consumer MUST verify the SPK signature against the published Ed25519 verifying key before performing any DH against the SPK. A bundle that fails signature verification MUST be rejected; the handshake MUST NOT proceed.

3.10 Key rotation summary

These rotation invariants are what give the protocol its forward secrecy and post-compromise security properties (Chapters 1 and 5).

Session Handshake (X3DH + PQXDH)

This chapter specifies the cryptographic handshake that establishes a new Konstruct session between two identities. The classical part (X3DH) follows the Signal Protocol X3DH whitepaper with concrete parameters listed in §4.1. The post-quantum extension (PQXDH) layers an ML-KEM-768 KEM on top of X3DH such that the resulting session is secure if either the classical or the post-quantum component holds.

Keywords MUST, MUST NOT, SHOULD, MAY are per RFC 2119.

4.1 Notation and constants

The following protocol-level byte strings are fixed:

An interoperable implementation MUST use these exact byte values. Changing any of them produces incompatible sessions (the AEAD on the first message will fail).

4.2 Bundle publication (Bob)

Before any handshake can occur, Bob MUST have published a registration bundle to the directory. The bundle wire format is defined in §3.9.

Bob MUST:

1. Generate a fresh SPK and ML-KEM-768 KEM-SPK at registration; record the issue timestamp and spk_rotation_epoch = 0.
2. Sign the SPK as sig_SPK = Ed25519_Sign(SK_priv, b"KonstruktX3DH-v1" || [0x00, 0x01] || SPK_pub).
3. Sign the KEM-SPK as sig_KSPK = Ed25519_Sign(SK_priv, b"KonstruktX3DH-v1" || [0x00, 0x10] || KEM_pub).
4. Optionally publish the hybrid Ed25519 + ML-DSA-65 identity and hybrid prekey signatures described in §2.3.3.
5. Upload (IK_pub, SK_pub, SPK_pub, sig_SPK, epoch, OPKs, KEM-SPK, sig_KSPK, KEM-OPKs, capability flags) to the directory.
6. Rotate the SPK and KEM-SPK weekly in the shipping client; the clean peer-side freshness limit is 30 days (SPK_MAX_AGE_SECS, §3.5).

4.3 X3DH (Suite 1) — initiator path

Alice MUST perform the following steps to initiate a session with Bob.

Step 1: Fetch and validate the bundle

Alice fetches Bob's bundle from the directory. She MUST then:

1. Verify sig_SPK over the SPK sign-message (b"KonstruktX3DH-v1" || [0x00, 0x01] || SPK_pub) using SK_pub. If verification fails, abort.
2. Verify that SPK_age = now − SPK_issued_at ≤ SPK_MAX_AGE_SECS (30 days for the clean path). A stale SPK MUST cause the normal clean init path to abort; implementations may expose an explicit degraded/at-risk path that skips only freshness validation while still verifying signatures.
3. If the bundle contains one or more OPKs, select exactly one and record its opk_id (for Bob to consume).
4. (Suite 2 only) Verify sig_KSPK and KEM-SPK freshness identically. If Suite 2 is requested and the KEM-SPK is missing or stale, abort (SEC-002). The protocol MUST NOT silently downgrade from Suite 2 to Suite 1.
5. If hybrid identity/signature fields are present, verify the cross-signature and hybrid prekey signatures as specified in §2.3.3. Absence of hybrid fields is not a failure.

Step 2: Generate ephemerals

Alice generates a fresh X25519 ephemeral keypair EK_A.

Step 3: Compute DH outputs

The four (or three, if no OPK) DH outputs are:

DH1 = DH(IK_A_priv, SPK_B_pub)
DH2 = DH(EK_A_priv, IK_B_pub)
DH3 = DH(EK_A_priv, SPK_B_pub)
DH4 = DH(EK_A_priv, OPK_B_pub)        — omitted if no OPK

The order matters; an implementation that concatenates them in a different order produces a different root key and is non-interoperable.

DH_combined = DH1 || DH2 || DH3 || DH4

In Suite 1 the length of DH_combined is either 128 bytes (4-DH) or 96 bytes (3-DH fallback). The 3-DH fallback path is functional but has reduced forward secrecy and is tracked as the open issue BS-3; implementations SHOULD warn when it is taken.

Step 4: Derive the root key

SK_root = KDF(salt = F, IKM = DH_combined,
              info = b"Construct-X3DH-RootKey-v1", L = 32)

SK_root is the initial Double Ratchet root key (RK₀). Implementations MUST zeroise DH_combined and the individual DH_n slices after this step.

Step 5: Initialise the Double Ratchet sending state

The initiator immediately performs the first DH ratchet step (see §5.6) using SK_root and Bob's SPK_pub as the initial remote DH key. The result is RK₁ plus a new sending chain key CK_s₀.

Step 6: Encrypt and send the first message

Alice encrypts her first plaintext under the message key returned by KDF_CK(CK_s₀) (§5.2). The wire-format envelope MUST contain:

FirstMessageEnvelope (Suite 1) ::=
    suite_id          : u16 = 0x0001
    ek_pub            : [u8; 32]      -- Alice's X25519 ephemeral pub
    opk_id            : Option<u32>   -- which of Bob's OPKs was used
    message_number    : u32 = 0
    dh_pub            : [u8; 32]      -- Alice's first ratchet DH pub
    prev_chain_length : u32 = 0
    nonce             : [u8; 12]
    ciphertext        : Bytes
    aead_tag          : [u8; 16]

Field ordering and sizes are normative for interoperability. The nonce is generated by the AEAD implementation (chacha20poly1305 0.10).

4.4 X3DH (Suite 1) — responder path

Bob first learns about the session by receiving Alice's first message. He MUST:

1. Look up his own IK_priv, SPK_priv (at the epoch indicated by the bundle Alice consumed), and OPK_priv[opk_id] from his key store.

2. Compute the same four DH outputs:

   DH1 = DH(SPK_B_priv, IK_A_pub)
   DH2 = DH(IK_B_priv,  EK_A_pub)
   DH3 = DH(SPK_B_priv, EK_A_pub)
   DH4 = DH(OPK_B_priv, EK_A_pub)        — when opk_id is present
   

   Note: subscripts swap to maintain DH(IK_A_priv, SPK_B_pub) = DH(SPK_B_priv, IK_A_pub) (X25519 is symmetric).

3. Derive SK_root with the same KDF call as the initiator.

4. Initialise the Double Ratchet receiving state, then run the first ratchet step using EK_A_pub from the envelope as the initial remote DH key.

5. AEAD-decrypt the ciphertext (with AD as defined in §5.4). If decrypt fails, abort and surface a clear error (the reference returns Crypto::AeadVerifyFailed rather than silently dropping).

6. MUST delete the consumed OPK_priv[opk_id] so it cannot be reused (this is the source of forward secrecy contributed by the OPK).

If both Alice and Bob initiate concurrently (each fetched the other's bundle simultaneously), the tie-break rule is:

The party whose device_id is lexicographically greater wins the INITIATOR role and proceeds; the other party MUST discard its half-built state and accept the winner's first message as RESPONDER.

The reference implements this in orchestration/session_lifecycle.rs.

4.5 PQXDH (Suite 2) — post-quantum extension

Suite 2 augments Suite 1 with an ML-KEM-768 shared secret. The addition is deferred: the ML-KEM shared secret is mixed in after the first DH ratchet step, not into the initial root-key derivation. This design lets the same KEM_priv be safely paired with multiple incoming sessions and matches the construct-core implementation in src/crypto/pq_x3dh.rs.

Step P1: Initiator KEM encapsulation

After §4.3 Step 1 (bundle validation), Alice additionally selects Bob's KEM-SPK (or, if available, a KEM-OPK) and calls:

(KEM_pub_ct, kem_ss) = MlKem768::Encapsulate(KEM_pub_B)

KEM_pub_ct is the 1088-byte ciphertext. kem_ss is the 32-byte post-quantum shared secret. The classical X3DH proceeds in parallel and produces SK_root exactly as in §4.3.

Step P2: First message includes the KEM ciphertext

The Suite 2 envelope additionally carries:

+ kem_ct          : [u8; 1088]    -- ML-KEM-768 ciphertext
+ kyber_opk_id    : Option<u32>   -- which ML-KEM-768 KEM-OPK was consumed
+ kem_len         : u16 = 1088    -- defensive length tag

The classical part of the envelope is unchanged.

Step P3: Initiator caches kem_ss until the first ratchet completes

Alice MUST persist kem_ss to durable storage before sending the first message. The reference uses RustPQContributions, a CFE-backed store exported under the legacy name KyberSessionState (msg_type = 0x21), to survive an app crash between "first message sent" and "PQ contribution applied" (construct-core/src/orchestration/pq_contribution.rs:200-:217, :360-:385).

Step P4: Responder KEM decapsulation

Bob, after performing classical X3DH (§4.4) and the first DH ratchet step, calls:

kem_ss = MlKem768::Decapsulate(KEM_priv_B, kem_ct)

He MUST then immediately persist kem_ss through the same contribution store until it has been applied and the session state has been persisted.

Step P5: Apply the PQ contribution at RK₁

After the first Double Ratchet DH step has produced RK₁ (the post- first-ratchet root key), both sides MUST update:

RK₁' = KDF(salt = RK₁, IKM = kem_ss,
           info = b"construct-pqxdh-v1", L = 32)

and re-derive any sending chain key that was already computed from RK₁. From this point onward the session is secured under both the classical X25519 contribution and the PQ ML-KEM-768 contribution.

The deferred-mix design ensures the responder applies the PQ strengthening at the same logical state as the initiator (after the first DH step), which is required for the chains to stay in sync.

Step P6: Zeroise kem_ss

Once RK₁' is computed and persisted, kem_ss MUST be zeroised. The PQ contribution store removes the entry from the Keychain at this point.

4.6 Suite 3 negotiation boundary

Suite 3 is negotiated from the supports_pq_ratchet capability in the prekey bundle, not from the protobuf crypto_suite enum. New clients map bundle crypto-suite values to core Suite 1 or Suite 2; a Suite 3 session is selected only when both sides support the sparse continuous PQ ratchet. The first message then carries suite_id = 0x0003 in WirePayload and every Suite 3 frame includes the additional PQ section specified in Chapter 5 §5.3.

The initial X3DH/PQXDH handshake still follows the Suite 1 / Suite 2 rules above. Suite 3 is the continuing ratchet layer after session establishment.

4.7 Failure modes and recovery

4.8 Reference

• Classical X3DH: construct-core/src/crypto/handshake/x3dh.rs
• PQXDH KEM: construct-core/src/crypto/pq_x3dh.rs
• Session initiation orchestration: construct-core/src/orchestration/session_lifecycle.rs
• PQ contribution store: construct-core/src/orchestration/pq_contribution.rs

The cryptographic test vectors that an interoperable implementation should reproduce are in construct-core/tests/handshake_vectors.rs (to be expanded in v0.2 of this specification with a published vector set).

Message Encryption (Double Ratchet)

Once a session is established by the handshake of Chapter 4, every subsequent message is encrypted under the Double Ratchet algorithm of Perrin and Marlinspike. This chapter specifies Konstruct's variant: state variables, the symmetric and DH ratchet steps, the AEAD framing and Associated Data, and the DoS guards that an interoperable implementation MUST enforce.

Keywords MUST, MUST NOT, SHOULD, MAY are per RFC 2119.

5.1 Session state

Each party maintains the following state per session. All values are zeroised on session destruction; MK and intermediate chain-key material MUST be zeroised immediately after use.

The reference implementation packs these into SessionState in construct-core/src/crypto/messaging/double_ratchet/.

5.2 KDF helpers

Two distinct HKDF-SHA-256 instances are used:

KDF_RK(rk, dh_out) -> (rk', ck')
    = HKDF-SHA-256(salt = rk, IKM = dh_out,
                   info = b"Double-Ratchet-Root-Key-Expansion", L = 64)
    -> (output[0..32], output[32..64])

KDF_CK(ck) -> (mk, ck')
    = HKDF-SHA-256(salt = ck, IKM = empty,
                   info = b"Double-Ratchet-Chain-Key-Expansion", L = 64)
    -> (output[0..32], output[32..64])

KDF_RK mixes a new DH output into the root key and emits a fresh chain key. KDF_CK advances a chain key one step and emits a single message key. The initial X3DH root key is first normalised for the Double Ratchet with HKDF(salt = [0xFE; 32], IKM = x3dh_root, info = b"InitialRootKey", L = 32).

5.3 Wire format (WirePayload header)

Every encrypted message on the wire is preceded by a fixed-layout binary header followed by AEAD-protected ciphertext.

WirePayload (header, 52 bytes fixed + variable extension fields) ::=
    message_number      : u32  little-endian         (4 B)
    dh_public_key       : [u8; 32]                   (32 B)
    otpk_id             : u32  little-endian         (4 B)  -- 0 if N/A
    kyber_otpk_id       : u32  little-endian         (4 B)  -- 0 if N/A
    kem_len             : u16  little-endian         (2 B)
    prev_chain_length   : u32  little-endian         (4 B)
    suite_id            : u16  little-endian         (2 B)
    -- followed by kem_ct (kem_len bytes; absent when kem_len = 0)
    -- followed by Suite 3 PQ section when suite_id = 0x0003
    -- followed by AEAD framing (nonce || ciphertext || tag)

HEADER_SIZE = 52 bytes is fixed by the reference (sum of the field sizes above, construct-core/src/wire_payload.rs:22-:36). The variable KEM ciphertext follows the header when kem_len > 0; for Suite 2 first messages the reference value is 1088 bytes. The pack/unpack routines are wire_payload::pack / wire_payload::unpack; deviating from the ordering or endianness produces non-interoperable frames.

Suite 3 adds a PQ section between kem_ct and the AEAD frame:

Suite3PqSection ::=
    pq_message_epoch : u32 little-endian
    field_type       : u8     -- 0 none, 1 EK proposal, 2 CT completion

field_type = 1:
    field_epoch      : u32 little-endian
    ek_len           : u16 little-endian
    ek               : bytes  -- ML-KEM-768 public key, normally 1184 B

field_type = 2:
    field_epoch      : u32 little-endian
    ek_hash          : [u8; 8]
    ct_len           : u16 little-endian
    ct               : bytes  -- ML-KEM-768 ciphertext, normally 1088 B

pq_message_epoch is always present for Suite 3, even when field_type = 0. It is always 0 and no PQ section is encoded for Suite 1 and Suite 2 frames. Reference layout: construct-core/src/wire_payload.rs:76-:129 and :220-:264.

The AEAD output (nonce || ciphertext || tag) uses:

5.4 Associated Data construction (AD)

The AEAD MUST be called with an Associated Data buffer that binds the ciphertext to its session, parties, ratchet position, and protocol version. The current format is AD version 3, defined as:

AD_v3 ::=
    ad_version          : u8 = 3                     (1 B)
    sender_user_id      : utf-8 bytes (36 chars)     (36 B for UUID)
    receiver_user_id    : utf-8 bytes (36 chars)     (36 B for UUID)
    session_id          : [u8; 16]                   (16 B; decoded from 32 lowercase hex chars)
    dh_public_key       : [u8; 32]                   (32 B)
    message_number      : u32 big-endian             (4 B)
    pq_message_epoch    : u32 big-endian             (4 B; Suite 3 only)

Total length for canonical 36-character UUIDs: 125 bytes for Suite 1/2, 129 bytes for Suite 3. The session id is derived as HKDF(salt = x3dh_root, IKM = b"construct-session-id", info = b"Construct-SessionID-v2\x00" || min_user_id || 0x00 || max_user_id, L = 16) and stored as hex (construct-core/src/crypto/messaging/double_ratchet/mod.rs:204-:227). The reference constructs encryption AD in construct-core/src/crypto/messaging/double_ratchet/messaging.rs:307-:332 and decryption AD in internals.rs:533-:554.

Order is normative. Each direction of a session computes its own AD — ENCRYPT uses (local_user_id_sender, contact_id_receiver); DECRYPT uses (contact_id_sender, local_user_id_receiver), with the field positions swapped so the AD on each side matches:

ENCRYPT side (Alice → Bob):
    AD = 0x03 || alice_user_id || bob_user_id || session_id || ...

DECRYPT side (Bob receiving from Alice):
    AD = 0x03 || alice_user_id || bob_user_id || session_id || ...

i.e. the "sender_id" position is always populated with the sender's user-id regardless of which side is computing AD. A mismatch (e.g. using device_id (32-char hex) instead of user_id (36-char UUID)) produces an AD length difference and instant AEAD failure.

5.4.1 AD migration (v2 → v3)

The previous version AD_VERSION_PREV = 2 uses the same fields as v3, including the 16-byte session id; it differs by the leading version byte. A receiver MUST attempt decryption first with AD_VERSION = 3; if AEAD verification fails, the receiver MUST retry once with AD_VERSION = 2 before treating the message as undecryptable. For Suite 3, both attempts include pq_message_epoch in AD. This fallback path is purely for in-flight v2 messages during the migration window and SHOULD be removed in a future protocol revision (SEC-006).

5.5 Encryption (RatchetEncrypt)

RatchetEncrypt(state, plaintext, peer_id):
    1. padded = pkcs7_pad(plaintext, 255)        -- §5.7
    2. (mk_dr, CKs') = KDF_CK(state.CKs)
    3. state.CKs = CKs'
    4. pq_epoch = state.current_pq_epoch if state.suite_id = 3 else 0
    5. mk = mix_pq_message_key(mk_dr, pq_epoch)
    6. message_number = state.Ns
    7. state.Ns += 1
    8. header = {
           message_number  = message_number,
           dh_public_key   = state.DHs.pub,
           prev_chain_length = state.PN,
           suite_id        = state.suite_id,
           kem_len         = 0,                -- non-handshake messages
           otpk_id         = 0,
           kyber_otpk_id   = 0,
       }
    9. ad = build_ad(AD_VERSION_3, state.local_user_id,
                     peer_id, state.session_id,
                     state.DHs.pub, message_number,
                     pq_epoch if state.suite_id = 3)
   10. (nonce, ct, tag) = AEAD-Encrypt(key = mk,
                                       plaintext = padded,
                                       associated_data = ad)
   11. zeroise(mk_dr, mk)
   12. return wire_payload::pack(header, kem_ct = None,
                                 sealed_box = nonce || ct || tag,
                                 pq_message_epoch = pq_epoch,
                                 pq_ratchet_field = pending Suite 3 field, if any)

The reference uses chacha20poly1305 0.10 for AEAD. The nonce is a fresh 12-byte random per message; it is part of the AEAD output and MUST be transmitted alongside the ciphertext.

For Suite 3, mix_pq_message_key returns the Double Ratchet message key unchanged when pq_epoch = 0. For any non-zero epoch it derives HKDF(salt = pq_epoch_secret, IKM = mk_dr, info = b"construct-pqr-msg-v1", L = 32) and rejects the message if that epoch secret is unavailable (construct-core/src/crypto/messaging/double_ratchet/internals.rs:415-:440).

5.6 DH ratchet step

A DH ratchet step occurs when an incoming message carries a dh_public_key the receiver has not seen before (i.e. the peer rotated their sending keypair). The step is:

DHRatchetStep(state, peer_dh_pub):
    1. state.PN = state.Ns
    2. state.Ns = 0
    3. state.Nr = 0
    4. state.DHr = peer_dh_pub
    5. dh_out = DH(state.DHs.priv, state.DHr)
    6. (state.RK, state.CKr) = KDF_RK(state.RK, dh_out)
    7. state.DHs = X25519::generate()
    8. dh_out = DH(state.DHs.priv, state.DHr)
    9. (state.RK, state.CKs) = KDF_RK(state.RK, dh_out)
   10. zeroise(dh_out)

This performs two KDF_RK invocations: one to derive the receiving chain key (matching the peer's just-completed sending chain) and one to derive the new sending chain key (after rotating the local DH keypair). The order is normative; reversing it produces incompatible chain alignment.

5.7 PKCS#7 padding (length-hiding)

Plaintext MUST be padded to a multiple of 255 bytes using PKCS#7 before AEAD-encryption. The padding length byte is itself part of the plaintext (verified during unpad). This hides the exact application plaintext length from a network observer, leaving only the bucket size (multiple of 255).

The reference implements unpad in construct-core/src/traffic_protection/padding.rs using XOR-based constant-time validation: diff |= byte ^ expected aggregated across the padding region, then checked against zero. A non-constant-time unpad would leak padding length through timing.

5.8 Decryption (RatchetDecrypt)

RatchetDecrypt(state, wire_bytes, peer_id):
    1. (header, kem_ct, framing) = wire_payload::unpack(wire_bytes)

    -- §5.8.1 DoS guards (MUST be enforced)
    2. If header.message_number > state.Nr + MAX_MESSAGE_JUMP:
           reject as DoS attempt
    3. skipped = header.message_number - state.Nr
       If skipped > MAX_SKIPPED_MESSAGES:
           reject as DoS attempt

    -- §5.8.2 DH ratchet check
    4. If header.dh_public_key != state.DHr:
           SkipChainKeysUntil(state, header.prev_chain_length)
           DHRatchetStep(state, header.dh_public_key)

    -- §5.8.3 Message key lookup
    5. SkipChainKeysUntil(state, header.message_number)
    6. (mk_dr, CKr') = KDF_CK(state.CKr)
    7. state.CKr = CKr'
    8. state.Nr += 1

    -- §5.8.4 AEAD decrypt with fallback
    9. mk = mix_pq_message_key(mk_dr, header.pq_message_epoch)
   10. ad = build_ad(AD_VERSION_3, peer_id, state.local_user_id,
                     state.session_id, header.dh_public_key,
                     header.message_number,
                     header.pq_message_epoch if state.suite_id = 3)
   11. try:
           padded = AEAD-Decrypt(key = mk, ciphertext = framing,
                                 associated_data = ad)
       except AeadVerifyFailed:
           ad_v2 = build_ad(AD_VERSION_PREV, ...)    -- §5.4.1
           padded = AEAD-Decrypt(..., associated_data = ad_v2)
   12. commit Suite 3 PQ field only after authenticated decrypt succeeds
   13. zeroise(mk_dr, mk)
   14. plaintext = pkcs7_unpad(padded)
   15. return plaintext

For Suite 3, a carried EK/CT field is processed only after the carrier message has authenticated and decrypted successfully. A well-formed but cryptographically unusable EK/CT field is ignored for PQ state and MUST NOT roll back already delivered classical plaintext; an invalid wire encoding is rejected by wire_payload::unpack, and an unknown non-zero pq_message_epoch is a decrypt error because it would otherwise skip the PQ mix.

5.8.1 Mandatory DoS guards

A message that violates any of these MUST be rejected without performing the AEAD operation. Otherwise an attacker can force the receiver to derive an arbitrary number of skipped message keys (CPU / memory DoS) by spoofing a header with a giant message_number.

5.8.2 Skipped message key cleanup

Skipped message keys (MKSKIPPED) MUST be expired:

• By count: oldest first when len(MKSKIPPED) > MAX_SKIPPED_MESSAGES.
• By age: any key older than MAX_SKIPPED_MESSAGE_AGE_SECONDS.
• By DH ratchet: keys belonging to a chain older than state.DHr − 2 ratchet steps SHOULD be evicted.

5.9 Self-healing (END_SESSION fallback)

If decryption of the first message of a session (message_number = 0, dh_ratchet step 0) fails, the receiver MAY trigger session healing before falling back to a full handshake. The healing protocol is out of scope of this chapter; see construct-core/src/orchestration/healing_queue.rs for the reference implementation. Constraints:

• Healing MUST be attempted at most 3 times per contact per 24-hour window.
• A successful healing MUST result in a session that satisfies all the security properties of a freshly negotiated session (forward secrecy, post-compromise security).
• If healing exhausts its retry budget, the receiver MUST send an END_SESSION control message and fall through to a full X3DH/PQXDH handshake from §4.

5.10 Security properties (informal)

The Double Ratchet, applied as above, provides:

• Forward secrecy: compromise of any state component at time t does not enable decryption of messages from time t − 1 or earlier, because the chain keys and message keys used then have been zeroised and the root key has been re-derived through irreversible KDF and DH operations.
• Post-compromise security: compromise of all secret state at time t, followed by no further active attack, leaves the attacker unable to decrypt messages from time t + Δ once a single DH ratchet step has completed (typically one round-trip).
• Replay resistance: a replayed ciphertext fails the AEAD check on the second receive (because mk has been zeroised) and also fails application-layer ACK dedup.

A formal proof against a specified adversary is not part of this specification. The reference implementation is intended to be amenable to formal verification (Kani / Prusti); that work is planned but not done.

5.11 References

• Specification: this chapter.
• Reference implementation:
  • construct-core/src/crypto/messaging/double_ratchet/
  • construct-core/src/wire_payload.rs
  • construct-core/src/traffic_protection/padding.rs
• Original design: Perrin & Marlinspike, The Double Ratchet Algorithm, https://signal.org/docs/specifications/doubleratchet/.

Transport Layer

This chapter specifies how Konstruct messages are carried from a client to the server and (currently) onward to the recipient. It defines the FFI binary envelope (CFE), the on-wire framing, the gRPC service surface, and the VEIL anti-censorship transport tier.

Keywords MUST, MUST NOT, SHOULD, MAY are per RFC 2119.

6.1 Layering overview

                Plaintext (application)
                       │
                       ▼
          ┌─ Konstruct cryptographic core (Rust)
          │     X3DH/PQXDH + Double Ratchet (Ch. 4-5)
          │     padding (PKCS#7 mod 255)
          │     WirePayload pack (§6.2)
          ▼
   AEAD ciphertext frames
          │
          ▼
   CFE binary envelope (§6.3) over UniFFI / JNI / direct C FFI
          │
          ▼
   gRPC bidirectional stream (§6.4) — HTTP/2 over TLS 1.3
          │
          ▼  (optional, when direct TLS is blocked)
   VEIL tier (§6.5) — veil-front  (obfs4 / WebTunnel retired)
          │
          ▼
   TCP / QUIC over the public internet

Layers below Konstruct (TLS 1.3, HTTP/2, TCP, QUIC) are standard and out of scope here.

A QUIC/HTTP-3 direct path is also in production as an alternative to the HTTP/2 path, selected by the client-side transport router with an HTTP/2 fallback. The current client calls it engine-QUIC and gates it through FeatureFlags.engineQuicExperimental, which defaults on; release builds use plain QUIC and force Salamander-style datagram obfuscation off (construct-ios Utilities/Constants.swift:414-:456, Networking/gRPC/GRPCChannelManager.swift:474-:535). The H3 path is implemented in construct-engine/src/transport/mod.rs:50-:113 and src/transport/connection.rs:60-:107; it is not yet specified normatively in this chapter (planned for a future revision).

6.2 Wire format (WirePayload)

Every encrypted Konstruct message crosses the wire as a WirePayload — a packed binary frame with the layout defined in §5.3. Restated for completeness:

Total fixed header size: 52 bytes (construct-core/src/wire_payload.rs:22-:36). All numeric fields in the fixed WirePayload header and Suite 3 PQ section are little-endian (construct-core/src/wire_payload.rs:106-:129, :220-:264).

A WirePayload is the unit of work the Double Ratchet produces and consumes. It MUST NOT carry plaintext routing fields outside of suite_id and the lengths needed to parse the envelope; metadata such as sender, recipient, timestamps, and conversation ids belongs in the transport-level wrapper, not in the WirePayload itself.

6.3 CFE — Construct Frame Encoding

When a WirePayload (or any other typed protocol message) crosses the FFI boundary between the Rust core and a platform binding (Swift, Kotlin), it MUST be wrapped in a CFE envelope. CFE eliminates the JSON parsing attack surface previously present at the FFI line.

6.3.1 Envelope layout

CFE envelope (16-byte header + payload) ::=
    magic        : [u8; 2]  = [0x43, 0x46]    -- "CF"
    version      : u8       = 0x01
    msg_type     : u8                          -- CfeMessageType enum tag
    flags        : u8                          -- reserved, MUST be 0
    reserved     : [u8; 3]  = [0x00; 3]
    payload_len  : u32 LE                      -- length of the MessagePack body
    crc32        : u32 LE                      -- CRC-32 over payload only
    payload      : [u8; payload_len]           -- MessagePack body

Header constants are defined in construct-core/src/cfe/envelope.rs: CFE_MAGIC = [0x43, 0x46], CFE_VERSION = 0x01, CFE_HEADER_LEN = 16, SUPPORTED_FLAGS_MASK = 0x00, and MAX_PAYLOAD_LEN = 256 * 1024 (:8-:25). The encoder writes the header in the order above and serialises the payload with rmp_serde::to_vec_named (:48-:65).

6.3.2 Required validations

A receiver of a CFE envelope MUST:

1. Verify the magic bytes match exactly. Mismatch → reject.
2. Verify the version is supported (currently only 0x01).
3. Verify the msg_type byte maps to a known CfeMessageType.
4. Verify flags == 0; flag constants exist in code, but v1 supports no flags (SUPPORTED_FLAGS_MASK = 0x00).
5. Verify the three reserved bytes are zero.
6. Decode payload_len as little-endian and reject values above the implementation cap (reference: 256 KiB).
7. Verify the buffer contains exactly enough bytes for the declared payload.
8. Verify crc32 matches recomputed CRC-32 over the payload bytes only (construct-core/src/cfe/envelope.rs:135-:147).
9. Decode the payload as MessagePack only if all checks above pass.

These checks are what make CFE strictly safer than the JSON predecessor: a malformed envelope is rejected before any deserialisation is attempted, and the bounded payload_len prevents unbounded allocation.

6.3.3 Message types

The msg_type byte selects the MessagePack schema for the payload. The reference defines 14 incoming and 28 outgoing message types covering events such as IncomingMessage, SessionStateChanged, Action::SendEncryptedMessage, etc. The enum is normative; new variants MUST be added with a new value, never by repurposing an existing one.

6.4 gRPC service surface

Konstruct uses gRPC over HTTP/2 over TLS 1.3 as the primary transport. The protobuf service definitions live in the konstruct-msg/construct-protos package (separate repository); the ones relevant to a client implementer are:

JWT-required RPCs MUST carry an authorization: Bearer <token> header and an x-user-id header. The reference adds them in an AuthInterceptor; an interoperable client implementation MUST do the same.

MessageStream carries WirePayload frames (§6.2) as bytes in the request/response stream. The server treats the byte field as opaque and routes by metadata fields outside the WirePayload.

SendSealedMessage carries a SealedSenderEnvelope and deliberately does not extract an authenticated user id; anti-abuse is enforced by per-IP rate limiting, Privacy Pass token redemption, and delivery-tag replay checks (construct-server/messaging-service/src/grpc.rs:701-:750, messaging-service/src/envelope.rs:139-:270). This is the transport entry point that removes the sender identity from the server-visible request for sealed sender (Chapter 8).

For key fetches, new clients MUST set consume_one_time_prekey explicitly. Legacy absence is interpreted as "consume" for wire compatibility, while non-session lookups should set it to false to avoid draining OPK pools (construct-server/shared/proto/services/key_service.proto:80-:103).

6.5 VEIL — anti-censorship transport tier

When the direct gRPC-over-TLS path is blocked, throttled, or fingerprinted by an adversarial network, the client MAY route through VEIL instead. VEIL is a pluggable transport tier with several backend strategies:

The VEIL coordinator (in construct-veil/src/veil/coordinator.rs) runs a happy-eyeballs probe race over the configured backends and keeps per-backend persistent quality scores in a small SQLite store. The winner is dispatched as the data plane; losers are cancelled.

6.5.1 Pluggable transport selection

A client MUST honour:

• An explicit user preference (VeilMode = .off | .auto | .on).
• A network-fingerprint hash that namespaces per-backend score caches (so that scores from network A do not pollute scores on network B).
• A per-backend MethodId (obfs4 = 0, webTunnel = 1, masque = 2, veilFront = 3). Method ids are normative on the Rust C FFI of construct-veil.

6.5.2 Constant-shape gate (veil-front)

For the veil-front backend, the relay MUST satisfy:

• Failed authentication MUST be routed to the cover application using the cover's own response timing and shape. There MUST NOT be a separate "tunnel rejected" code path with distinguishable timing.
• Frame-level length bucketing MUST be applied to the tunnel direction so that record-length distributions are bounded.
• veil_front_ticket_b64 MUST be supplied by the client; an empty ticket field MUST cause the veil-front method to be excluded from the probe race rather than silently downgraded.

The constant-shape requirement is the load-bearing property of veil-front; if a future deployment violates it, the wire becomes distinguishable from the cover application and the construction's purpose is defeated.

6.5.3 Connection ladder and graceful degradation

In VeilMode = .auto (the default) the client is direct-first: it attempts the plain gRPC/QUIC path first and escalates to VEIL only on a real connection failure. It MUST NOT pre-activate a relay purely because of coarse geography — a censored network that is momentarily reachable directly should use the direct path, and a relay is engaged only when the direct attempt actually fails.

The result is a ladder that degrades with the hostility of the network:

This is deliberately honest: obfuscation buys reachability against classification, not against an adversary who drops everything except an allowlist. See Architecture Overview for the tiered model. VEIL also is not a metadata-hiding layer on its own — it helps a connection blend in, but a network observer who already sees the connection can still infer timing and volume; sealed sender (Chapter 8) and padding (§5.7) are the metadata mechanisms, not VEIL.

6.6 Transport guarantees and non-guarantees

What the transport layer guarantees

What the transport layer does not guarantee

6.7 Configuration constants summary

6.8 References

• WirePayload: construct-core/src/wire_payload.rs
• CFE envelope: construct-core/src/cfe/envelope.rs, cfe/types.rs
• gRPC service definitions: konstruct-msg/construct-protos
• VEIL coordinator and FFI: konstruct-msg/construct-veil

Implementation Status

This chapter is the honest matrix of what the reference implementation in konstruct-msg/construct-core (and the surrounding repositories) actually does today, distinct from what this specification requires a fully-conforming implementation to do.

It is the chapter readers should consult before relying on Konstruct for any specific threat model. Every line is grounded in a source-tree reference so it can be re-verified independently.

7.1 Component matrix

7.2 Platform matrix

7.3 Open security issues

The table below lists residual risks that remain after the current code audit. It deliberately excludes items that have shipped since the older internal TODO list was written.

Items listed as "Out of scope" in Chapter 1 §1.2 are NOT on this list — they are not bugs, they are explicit non-goals.

7.4 Test coverage

The reference includes:

What is not covered today:

• Full product-level multi-device interoperability coverage across all sealed-sender, sender-sync, and Suite 3 cases.
• Multi-node (two-VPS) federation interoperability test — federation is implemented with contract-level tests, but the two-server integration test is outstanding.
• Formal verification (planned, not done).
• Adversarial / red-team testing by an external party.

7.5 Reproducibility

The reference is built from the commit indicated in the version metadata of the released artefact. To reproduce a build:

git clone https://github.com/konstruct-msg/construct-core
cd construct-core
# iOS staticlib:
./build_crypto_lib.sh --all     # see construct-ios repo for the wrapper
# Android shared library:
cd ../construct-android
./build_crypto_lib.sh --all

The Cargo.lock checked into the repository pins every transitive dependency, so two builds from the same commit will produce binaries that differ only in compiler-version-dependent ways (debug info, timestamp markers).

7.6 Versioning policy

This specification follows Semantic Versioning at the document level:

• MAJOR — a wire-incompatible protocol change.
• MINOR — a backwards-compatible normative addition (new field, new optional behaviour).
• PATCH — editorial corrections that do not change implementer obligations.

The implementation's own versioning is separate; see the construct-core Cargo.toml for the crate version.

7.7 References

• Open-issue tracker (internal): construct-core/TODO.md.
• Disclosure & contact: Disclosure.
• Document changelog: Changelog.

Metadata Privacy & Sealed Sender

End-to-end encryption hides what is said. This chapter specifies how Konstruct also reduces who says it to whom that a server can observe — and, just as importantly, states honestly what it does not hide. It builds on the Threat Model (server adversary) and the Message Encryption chapter.

8.1 Goal and non-goals

Goal. For all ordinary user traffic, remove the sender's identity from what any server stores or must read to route a message. A server should be able to deliver a message to its recipient without learning who sent it.

Non-goals. This is metadata minimisation, not network-layer unlinkability. Konstruct does not run a mixnet and does not claim to defeat an adversary who can watch both legs of a connection and correlate by timing and volume. See Architecture Overview for that boundary. The honest residual-metadata list is in §8.7 below.

8.2 The sealed envelope

The primary current stealth path for ordinary sealed sends is a SendSealedMessageRequest containing only a SealedSenderEnvelope plus an optional attempt id. There is no outer Envelope, no sender, no conversation_id, and no server-visible content type on that RPC (construct-server/shared/proto/services/messaging_service.proto:25-:30, :281-:289). A legacy authenticated Envelope.sealed_sender path exists for transitional session-control traffic; it still masks sender, conversation id, and real content type on the outer envelope, then enters the same dispatch_sealed_sender server path. Unauthenticated SendSealedMessage is the sender-hiding transport boundary for ordinary sealed sends.

The sealed structures are defined normatively in shared/proto/core/envelope.proto (message SealedSenderEnvelope, envelope.proto:365; SealedInner, envelope.proto:390).

SealedSenderEnvelope {          // visible to the home/entry server
  recipient_server : string     // federation destination domain (S2S routing)
  sealed_inner     : bytes      // opaque — the home server MUST NOT parse it
  forwarding_token : bytes      // HMAC-SHA256(server_secret, sealed_inner || timestamp)
  timestamp        : int64      // freshness; reject if > 5 min old
}

SealedInner {                   // read by the destination server
  recipient_user_id     : string   // needed to route to the recipient
  delivery_tag          : bytes    // random 32 B; server dedups for 24h
  sender_cert_ciphertext: bytes    // SenderCertificate sealed to recipient IK — server MUST NOT decrypt
  encrypted_payload     : bytes    // the Double Ratchet ciphertext (Chapter 5)
  content_type          : ContentType       // DEPRECATED; ignored by server
  priority              : MessagePriority   // DEPRECATED; ignored by server
  ttl                   : uint32            // DEPRECATED; ignored by server
  token_nonce           : bytes    // Privacy Pass (optional, §8.5)
  token_bytes           : bytes
  token_spend_id        : bytes    // optional logical-message spend id
}

content_type, priority, and ttl remain in SealedInner only for compatibility. They are server-visible metadata leaks and the server MUST NOT use them for routing, priority, notification text, or UI (construct-server/shared/proto/core/envelope.proto:386-:418). New normal sealed sends leave content_type at UNSPECIFIED = 0, which proto3 omits from the wire. The real application content type rides inside the encrypted payload, currently as KNST byte 5 on framed payloads. The client constrains this boundary with SealedEnvelopeType: .generic serialises to no content type, while only the two structural exceptions SESSION_RESET (21) and SESSION_RESET_INIT (24) may be declared before decryption (construct-ios Services/Messaging/ContentTypeRouting.swift:39-:82, :171-:197; Security/StealthSenderService.swift:393-:415).

What each party sees:

• Home / entry server: recipient_server plus an opaque sealed_inner blob and its forwarding_token. It routes by destination domain and forwards the blob without parsing it.
• Destination server: parses SealedInner. It learns the recipient, the delivery_tag (for replay suppression), optional Privacy Pass token fields, optional token_spend_id, and the opaque encrypted_payload size. For ordinary sealed traffic it does not learn the message kind; it can see only the deprecated/structural content_type exceptions if present. It does not learn the sender: the sender identity lives only inside sender_cert_ciphertext, which is encrypted to the recipient's identity key, and which the server "MUST NOT attempt to decrypt" (envelope.proto:398-:404).

On the single-server deployment shipping today the home and destination roles are the same process, so it sees the SealedInner fields above — but still never the sender.

On the client, the current no-outer-envelope path is construct-ios Networking/gRPC/Services/MessagingServiceClient.swift (SendSealedMessage) plus Security/StealthSenderService.swift (buildSealedInner). Server-side routing is construct-server/messaging-service/src/envelope.rs:139-:270: the federation hop forwards sealed_inner opaquely, while local delivery decodes only recipient_user_id, token fields, and delivery_tag.

8.3 Sender certificate and recipient verification

The recipient learns and verifies the sender from the SenderCertificate (envelope.proto:425) inside sender_cert_ciphertext:

SenderCertificate {
  sender_user_id      : string
  sender_domain       : string   // home server, for public-key lookup
  sender_identity_key : bytes    // X25519 (32 B) — must match the session
  sender_device_id    : string
  issued_at           : int64
  expires_at          : int64    // typically issued_at + 24h
  server_signature    : bytes    // Ed25519 by the sender's home server
}

The certificate is issued and signed by the sender's home server (identity-service) with the same Ed25519 key published at .well-known/konstruct. The signature covers the direct big-endian concatenation sender_user_id || sender_domain || sender_identity_key || sender_device_id || issued_at || expires_at — one canonical format, pinned in stealth-sealed-sender v2 Phase 3 (server identity-service::build_sender_cert_sign_payload; client construct-ios Security/StealthSenderService.swift buildCertPayload).

The recipient attests the sender through one of two levers, strongest first (SenderVouchBasis in StealthSenderService.swift):

1. KT lever (.kt): the certificate's sender_identity_key matches the recipient's locally stored, key-transparency-verified knownIdentityKey for that contact. No dependency on any fetched server key.
2. Signature lever (.signature): the certificate's Ed25519 signature validates against the sender's home-server public key (fetched or pinned). Used on first contact, before a local KT key exists.

Delivery is not gated on attestation. If neither lever vouches (missing or stale bundle key, expired cert), the message is still delivered and logged as UNVOUCHED with a reason — the Double Ratchet is the real authenticator, and an unvouched attestation triggers a bundle-key refresh so the next message re-vouches (MessageRouter.routeIncomingMessage, construct-ios). This is a deliberate availability-over-strictness choice: a key rotation must not silently drop mail.

8.4 Always-on scope, and the fail-closed invariant

Sealed sending is on by default in release builds — there is no user toggle to turn it off (construct-ios Services/StealthPolicy.swift:42 isEnabled, :71 shouldUseSealedSender). DEBUG builds keep a developer override for exercising the legacy identified path.

Invariant (fail-closed): while stealth is on, every in-scope application send is sealed or queued — it is never emitted identified. Identified sends are legal only when shouldUseSealedSender() is false or when the traffic class is deliberately excluded below. When sealing is temporarily impossible (recipient identity key not yet known, sender certificate unfetchable), the send does not fall back to an identified envelope; it throws StealthDowngradeBlocked and the message is held for a later retry (StealthSendRecovery.swift, ChunkedMessageDelivery.swift). This closes a server-influence deanonymisation vector: a server that could force identified sends by failing sealed ones could deanonymise on demand.

Traffic in scope (sealed):

• User messages (text, media, voice, files, replies) and edits.
• End-to-end delivery receipts — otherwise sender↔recipient timing correlation leaks even when bodies are sealed.
• Call signalling (SDP / ICE — see Transport).
• The session-control handshake: session_ready, the tie-break ping, SESSION_RESET_INIT, and END_SESSION. With all user traffic sealed, these directed control messages were the primary remaining cleartext sender → recipient signal, so they are sealed too (client Services/Session/SessionCoordinator.swift sendSessionControlCore, MessagingServiceClient.swift sendEndSession).

Traffic deliberately excluded (identified, by decision — the leak is low-value or the frequency/cost is high):

• End-to-end heartbeats (content_type = 13). Their real type is now inside the encrypted KNST frame rather than in a server-visible heartbeat content type, but they still use the identified send path (construct-ios Services/Messaging/OutboundSessionService.swift:187-:233).
• Multi-device internal sync (a user talking to their own devices).

8.5 Anti-abuse: Privacy Pass tokens

Removing the sender identity also removes the server's usual per-sender abuse lever. Konstruct restores one with Privacy Pass anonymous tokens: a sealed send MAY carry token_nonce + token_bytes and may carry token_spend_id for multi-envelope logical messages (envelope.proto:420-:444), a blind-signed single-use credential the sender spends from a local wallet. The token is itself sealed to the destination server's X25519 key so relay operators cannot read the spent token. The full construction — the VOPRF, issuance/redemption, and the verifiable-issuance DLEQ proof — is specified in Chapter 9.

Deployment status. Token enforcement is governed by MSG_STEALTH_TOKEN_POLICY, currently warn in production: tokens are issued, attached, and redemption-validated, but an absent or failed token does not block delivery — anti-abuse is degraded, anonymity is intact. enforce is deferred past 1.0 (see Implementation Status). Issuance is rate-limited with an age-tiered per-account cap.

Verifiable issuance (planned/partial). So that a malicious issuer cannot tag individual users via a per-user signing key, the issuer proves in zero knowledge that every token was signed with the same published key (batched Chaum–Pedersen DLEQ). The server half is implemented (construct-crypto/src/privacy_pass.rs) and the client pins the issuer key and verifies the proof; treat end-to-end verifiable-VOPRF as in progress until enforcement relies on it. Until then, sender-unlinkability against a malicious (as opposed to honest-but-curious) server is not claimed.

8.6 Connection-layer metadata: IP minimisation

Sealed sender hides application-layer identity; the network layer still exposes the connection's source IP address, which is unavoidable for packet routing. Konstruct minimises what is retained: the server never stores a raw client IP. Anti-abuse rate-limit keys and logs use a salted one-way hash of the address (construct-utils/src/lib.rs:92 hash_client_ip, applied in construct-user-service/src/account.rs:140 and construct-auth-service/src/devices.rs:292). Per-address anti-abuse granularity is preserved (same address → same tag); the raw address is not written to databases, rate-limit state, or logs, and no raw IP-to-account mapping is kept.

Honest limit: a salted hash of the small IPv4 address space is not perfectly anonymous against a party holding the salt — it removes the raw address from storage, it does not make the network origin undiscoverable. To keep the address off the path entirely, route through VEIL (Transport), a VPN, or Tor; the terminating endpoint still sees the apparent source address of the connection it accepts.

8.7 Residual metadata — what a server still sees

Even with sealed sender always on, a compromised destination server can still observe the following. This is the honest counterpart to §8.1.

8.8 References

• Wire structures: shared/proto/core/envelope.proto (SealedSenderEnvelope, SealedInner, SenderCertificate).
• Server: messaging-service/src/envelope.rs; construct-core/src/crypto/privacy_pass/; construct-utils/src/lib.rs (hash_client_ip).
• Client (construct-ios): Services/StealthPolicy.swift, Security/StealthSenderService.swift, Networking/gRPC/Services/MessagingServiceClient.swift, Services/Session/SessionCoordinator.swift, Security/StealthSendRecovery.swift.
• Design rationale (internal): construct-docs decisions/ — stealth-sealed-sender-v2-always-on, sealed-sender-anti-abuse-economics, sealed-sender-session-control-channel, stealth-heartbeat-exclusion, server-influence-minimization, stealth-phase-c-verifiable-voprf.

Anti-Abuse: Privacy Pass Tokens

Sealed sender (Chapter 8) removes the sender's identity from what a server can read. That also removes the server's usual per-sender abuse lever: it can no longer rate-limit "this account is flooding" because it does not know which account sent a sealed message. Konstruct restores an abuse lever without re-introducing an identity — anonymous, single-use Privacy Pass tokens. This chapter specifies the verifiable Oblivious Pseudo-Random Function (VOPRF) they are built on, the issuance and redemption flows, and — the security-critical part — the zero-knowledge proof that stops a malicious issuer from turning the tokens themselves into a de-anonymising tag.

9.1 Design requirement

A token must satisfy two properties at once:

• Unlinkable: the server that redeems a token cannot connect it to the issuance event that minted it, nor to the account that requested it.
• Unforgeable & one-time: only the server's secret issuer key can mint a valid token, and each token spends exactly once.

A blind VOPRF gives both: the client blinds its token material before issuance, so the issuer signs something it cannot read; the client then unblinds to a value only it holds; redemption re-derives and checks that value. Double-spend is caught by a server-side seen-set.

9.2 The VOPRF construction

• Group: Ristretto255; G = RISTRETTO_BASEPOINT_POINT. Points are 32-byte canonical compressed encodings; scalars are 32-byte canonical little-endian.
• Hash-to-group: H(x) = RistrettoPoint::from_hash(SHA-512(x)).
• Issuer secret: a scalar k; its public commitment is K = k·G (§9.5).

Let nonce be 32 random bytes chosen by the client, and r a random blinding scalar.

Client blind:     T = H(nonce);   B = r·T                    → send B
Server evaluate:  Z = k·B                                    → return Z (+ DLEQ proof, §9.5)
Client unblind:   N = r⁻¹·Z = k·T
Token:            token = HKDF-SHA512( compress(N) ‖ nonce, info="ConstructPP-v1" )[0..32]

The client stores (token, nonce) in a local wallet and later presents the pair when spending. At redemption the server recomputes the same value from nonce and its own k:

verify:  N' = k·H(nonce);   token' = HKDF-SHA512( compress(N') ‖ nonce, "ConstructPP-v1" );
         accept iff constant_time_eq(token, token')

Reference: redemption verify_token (construct-crypto/src/privacy_pass.rs:174); token derivation derive_token (:158); the k is from_bytes_mod_order-reduced identically on both sides (:174 comment) — a mismatch there issues fine but fails every redemption.

9.3 Issuance and issuance caps

Tokens are minted by identity-service issue_tokens (identity-service/src/main.rs:907). The request carries the blinded points Bᵢ; the response returns the evaluations Zᵢ = k·Bᵢ, the issuer commitment K (server_pubkey, proto field 2), the batched DLEQ proof (field 3), and issuer_key_version (field 4). Because the points are blinded, the issuer cannot read the token material it signs.

Anti-abuse at issuance is an age-tiered per-account hourly cap (effective_issuance_cap, identity-service/src/main.rs:65, applied :952): a young account (below TOKEN_ISSUANCE_MATURITY_HOURS, default 24 h) is capped at TOKEN_ISSUANCE_YOUNG_MAX_PER_HOUR (default 30); a matured account at TOKEN_ISSUANCE_MAX_PER_HOUR (default 120). An account-age lookup failure fails safe to the young cap. The client wallet tops up reactively toward the cap as it spends and bootstraps an initial batch at registration.

9.4 Redemption, double-spend, and policy

A sealed send MAY carry the spent token in SealedInner.token_nonce / SealedInner.token_bytes (Chapter 8 §8.2). The token bytes are themselves sealed to the destination server's X25519 key (open_sealed_token_bytes, construct-crypto/src/privacy_pass.rs:107; client seals with the key delivered over the authenticated GetSenderCertificateResponse), so a relay operator cannot read the spent token in transit.

The server redeems via redeem_token_checked (messaging-service/src/envelope.rs:208), which runs verify_token and a single-use check (a Redis seen-set keyed by the token, SET NX). Outcomes map to a typed TokenRejected error (envelope.rs:18) with a FAILED_PRECONDITION "privacy_pass:{label}" status (labels: missing_token / invalid_token / double_spent / decrypt_failed / …).

Enforcement is governed by MSG_STEALTH_TOKEN_POLICY (envelope.rs:192), a three-way switch:

The client's response to an enforce rejection is never to fall back to an identified send — it force-replenishes the wallet, rebuilds the sealed envelope with a fresh token, and retries the sealed path once (StealthSendRecovery.swift; the Chapter 8 §8.4 fail-closed invariant). A server that could force identified sends by rejecting tokens could otherwise deanonymise on demand.

9.5 Verifiable issuance — batched DLEQ

Blinding hides the token from an honest-but-curious issuer. It does not by itself stop a malicious issuer from a key-tagging attack: a compromised server could evaluate a targeted user under a unique per-user secret kᵤ while still publishing K = k·G, silently marking that user's tokens so they de-anonymise the sealed sender at redemption.

The defence is a batched Chaum–Pedersen DLEQ proof returned with each issuance: a non-interactive zero-knowledge proof that every Zᵢ was evaluated with the same scalar k whose commitment K = k·G is published. A per-user kᵤ produces a proof that fails, so the client rejects the tokens instead of unknowingly carrying a tag.

The commitment is published at /.well-known/construct-server as token_issuer_public (= K) and token_issuer_key_version. The client pins K per version and verifies each response's proof against the pinned K — it must not trust the server_pubkey echoed in the response as the commitment, which would defeat the purpose.

The transcript is a client-parity contract — iOS and Android reimplement verification byte-for-byte; any change is a flag-day break (bump the domain string). Full spec: construct-docs cryptocore/privacy-pass-dleq-v1.md; reference construct-crypto/src/privacy_pass.rs (DLEQ_DOMAIN:195, issuer_public_key:221, generate_dleq_proof:274, verify_dleq_proof:313).

• DOMAIN = "ConstructPP-DLEQ-v1" (ASCII, 19 bytes). Context tags: 0x00 seed, 0x01 coefficient, 0x02 nonce, 0x03 challenge.
• Hash-to-scalar: SHA-512 wide reduction over the concatenated byte-strings.

For a batch (Bᵢ, Zᵢ), i = 0..n, in request order:

Composites (prover and verifier, identical):
  seed = SHA512( DOMAIN ‖ 0x00 ‖ K ‖ (B_0‖Z_0) ‖ … ‖ (B_{n-1}‖Z_{n-1}) )
  d_i  = SHA512→scalar( DOMAIN ‖ 0x01 ‖ seed ‖ u32_be(i) ‖ B_i ‖ Z_i )
  M    = Σ_i d_i·B_i ,   Zc = Σ_i d_i·Z_i

Prove (server; needs k):
  t  = SHA512→scalar( DOMAIN ‖ 0x02 ‖ k ‖ M ‖ Zc )     // deterministic nonce
  c  = SHA512→scalar( DOMAIN ‖ 0x03 ‖ K ‖ M ‖ Zc ‖ t·G ‖ t·M )
  s  = t + c·k ;   proof = c ‖ s                        // 64 bytes

Verify (client / auditor):
  A1' = s·G − c·K ,   A2' = s·M − c·Zc
  c'  = SHA512→scalar( DOMAIN ‖ 0x03 ‖ K ‖ M ‖ Zc ‖ A1' ‖ A2' )
  accept iff c' == c   (constant-time)

The deterministic nonce t = H(DOMAIN ‖ 0x02 ‖ k ‖ M ‖ Zc) binds the secret k and the statement (M, Zc) (which never repeats across distinct batches), so no RNG is used and there is no nonce-reuse-leaks-k failure mode. A known-answer test vector pins the whole transcript (privacy_pass::tests::dleq_kat_vector; proof prefix a5fc4353…).

9.6 Status and honest limits

Claim boundary. Until token enforcement is on enforce and every client hard-verifies the DLEQ against a pinned commitment, Konstruct claims sender-unlinkability against an honest-but-curious server, not against a malicious/compromised one. The DLEQ machinery is what upgrades that claim; it is shipped on the server and verified on iOS, but the end-to-end guarantee is only load-bearing once enforce relies on it. Marketing and threat-model text must not over-claim past this line — see Threat Model.

9.7 References

• construct-crypto/src/privacy_pass.rs — VOPRF (verify_token:174, derive_token:158, open_sealed_token_bytes:107) and DLEQ (DLEQ_DOMAIN:195, issuer_public_key:221, generate_dleq_proof:274, verify_dleq_proof:313).
• identity-service/src/main.rs — issuance (issue_tokens:907) and caps (effective_issuance_cap:65).
• messaging-service/src/envelope.rs — redemption + policy (redeem_token_checked:208, TokenRejected:18, policy switch :192).
• Client (construct-ios): BlindTokenService, StealthSendRecovery.swift.
• Contract / rationale (construct-docs): cryptocore/privacy-pass-dleq-v1.md; decisions/stealth-phase-c-verifiable-voprf, sealed-sender-anti-abuse-economics.

Voice and Video Calls

Konstruct carries 1:1 real-time calls over WebRTC. This chapter specifies how call setup is protected by the same end-to-end cryptography as chat, and how the call media is encrypted between the two devices — and states honestly what the connectivity layer still exposes.

Status: audio 1:1 is implemented; video is wired through the call-entry UI but the media layer is not yet enabled (construct-ios Services/Calls/CallsFeature.swift:14, isVideoEnabled = false). Group calls / SFU are out of scope (Chapter 7).

10.1 Two planes: signalling and media

A WebRTC call has two data planes:

• the signalling plane — the SDP offer/answer that negotiates codecs and keys, and the ICE candidates that discover a network path;
• the media plane — the actual encrypted audio/video (SRTP).

Konstruct's property is that the signalling plane rides the existing end-to-end-encrypted message path, and because the media keys are agreed inside that signalling, the media plane is end-to-end encrypted between the two devices too.

10.2 Signalling over the E2EE path

SDP offers/answers and ICE candidates are not sent to the server in the clear. They are encrypted with the peer's Double Ratchet session (Chapter 5) as call-signal messages and are sealed like any other in-scope user traffic (Chapter 8) — so the server can read neither the SDP (which carries the DTLS fingerprints and ICE ufrag/pwd) nor the sender identity. On the ordinary message path, the real call content type (12) rides inside the encrypted KNST frame; SealedInner.content_type and the outer envelope remain UNSPECIFIED (construct-ios Services/Calls/CallManager.swift:1295-:1300). The client-side framing that carries the suite id and PQ ratchet fields for a call signal is CallSignalCrypto (Services/Calls/CallSignalCrypto.swift:87-:104); orchestration is in Services/Calls/CallManager.swift.

Two delivery routes exist, both E2EE:

• the message path — the first offer is typically delivered E2EE ahead of the answer (a backgrounded callee is woken by a PushKit VoIP token that carries no call content);
• a low-latency signal stream (SignalingService.Signal, opened via SignalingServiceClient) for real-time exchange once both peers are live. The server relays these frames without being able to decrypt them.

ICE candidate batching. ICE candidates are flushed in size-bounded batches to stay under the signalling rate limit and, critically, under the padded-frame size cap — Suite-3 PQ blobs per candidate can otherwise overflow a single frame and drop the whole batch, so the client splits a large flush into chunks (CallManager.swift, Shared_Proto_Signaling_V1_IceCandidate).

TURN credentials for relayed connectivity are fetched per call (SignalingServiceClient.getTurnCredentials).

10.3 Media encryption

Call media uses WebRTC's standard DTLS-SRTP. The DTLS handshake that establishes the SRTP keys authenticates itself with certificate fingerprints — and those fingerprints are exchanged inside the SDP, which travelled over the E2EE signalling channel above. An active network attacker therefore cannot substitute its own DTLS fingerprints (that would require forging an E2EE-authenticated SDP), so for a 1:1 call the media is end-to-end encrypted between the two devices. No application-layer media re-encryption (e.g. SFrame) is required for the two-party case; SFrame would only be needed for a future group/SFU topology where a server forwards media.

Neither the Konstruct server nor a TURN relay used for NAT traversal can decrypt the media: a TURN relay forwards only opaque SRTP.

10.4 What the connectivity layer still exposes

Honest counterpart to §10.1 — even with signalling sealed and media DTLS-SRTP-encrypted:

Because ICE reveals network addresses to establish direct connectivity, a privacy-maximising user who wants to hide their address from the peer or a relay should force TURN-relayed connectivity (so only the relay's address is shared with the peer) or route through a network-layer anonymiser; this is a connectivity/anonymity trade-off, not a content-confidentiality one.

10.5 References

• Client (construct-ios): Services/Calls/CallManager.swift, Services/Calls/CallSignalCrypto.swift, Services/Calls/WebRTCSession.swift, Services/Calls/CallsFeature.swift; Networking/gRPC/Services/SignalingServiceClient.swift.
• Protos: konstruct-msg/construct-protos signaling package (IceCandidate, Signal).
• Sealing of call signals: Chapter 8; message encryption: Chapter 5.
• Design detail (construct-docs): client/specs/CALLS_CLIENT_SPEC.md.

Account Recovery

Konstruct has no password and no email, so the usual "reset via email" path does not exist. Recovery is key-based and comes in two independent mechanisms with different goals: a 12-word BIP39 phrase that restores account access on a new device, and SLIP-39 social recovery that threshold-restores the identity vault itself. Both are implemented in the shared Rust core so every client behaves identically.

Throughout: the recovery secrets never leave the device to the server in the clear. The server can only ever hold a recovery public key — there is no plaintext key escrow.

11.1 BIP39 seed-phrase account recovery

11.1.1 Derivation

A recovery phrase is 12 BIP39 words = 128 bits of entropy. 12 (not 24) is deliberate: 128 bits already matches the Ed25519 security level that the derived key targets, so 24 words would add UX cost for no cryptographic gain (client/specs/ACCOUNT_RECOVERY_CLIENT_SPEC.md).

seed_phrase (12 BIP39 words)
   → mnemonic_to_seed()      -- PBKDF2, 2048 rounds, no passphrase → 64-byte seed
   → BIP32 derive m/44'/0'/0'/0/0
   → Ed25519 (recovery_private_key, recovery_public_key)   -- 32 B each

The core exposes generate_mnemonic, validate_mnemonic, mnemonic_to_seed, derive_recovery_keypair, and sign_recovery_challenge / verify_recovery_signature (construct-core BIP39/BIP32 + ed25519-dalek).

11.1.2 Setup and recovery flows

Recovery is optional and set up separately from registration (recommended UX: prompt after first registration):

1. Setup — the client derives the recovery keypair, signs "CONSTRUCT_RECOVERY_SETUP:{userId}:{timestamp}" with the recovery private key, and calls SetRecoveryKey with the recovery public key plus the signature. The server stores only the public key.
2. Recover (new device) — the user enters the 12 words (checksum validated locally first); the client re-derives the recovery keypair, signs a fresh challenge, generates new device identity keys, and calls RecoverAccount. The server verifies the signature against the stored recovery public key and re-associates the account (userId) with the new device.

11.1.3 What it restores — and what it does not

• Restores: access to the same account identifier (userId) on a new device, provided the user holds the 12 words.
• Does not restore: the previous device's Double Ratchet sessions or local message history. The new device registers fresh identity keys, so contacts observe an identity-key change and sessions re-establish (their clients surface this as expected). Recovery is account re-access, not a cryptographic clone of the lost device.
• Trust note: possession of the 12 words is sufficient to re-take the account. The phrase MUST be stored as carefully as any root credential; §11.2 exists precisely to remove the single-phrase single point of failure for users who want that.

11.2 SLIP-39 social recovery (vault)

Social recovery targets a different goal: threshold recovery of an identity vault key across several trustees or locations, so that no single share — and no single lost phrase — can either recover or deny recovery of the identity. Implemented in construct-core/src/crypto/social_recovery.rs.

11.2.1 Construction

1. A 32-byte vault_key protects the identity/backup bundle.
2. vault_key is split with Shamir Secret Sharing over GF(2⁸) into share_count shares requiring a threshold to reconstruct; both are in 2..=10 with threshold ≤ share_count (split_secret).
3. Each share (a 1-based index + 32 bytes + checksum) is encoded as a 28-word SLIP-39 mnemonic over a 1024-word wordlist (10 bits/word).
4. Recovery: the user supplies ≥ threshold mnemonics; the core validates each share checksum and reconstructs vault_key by Lagrange interpolation (combine_shares), then decrypts the bundle.

Because it is t-of-n, losing up to n − t shares still recovers, and gaining fewer than t shares reveals nothing about vault_key.

11.3 Privacy and trust properties

Honest limits: neither mechanism can help a user who loses all recovery material — there is no server-side backdoor by design. The BIP39 phrase is a bearer credential (whoever holds it can re-take the account), which is why social recovery is offered for users who prefer distributed trust over a single phrase.

11.4 References

• construct-core/src/crypto/social_recovery.rs — SLIP-39 Shamir split / combine, 28-word encoding.
• construct-core BIP39/BIP32 recovery-keypair derivation (generate_mnemonic, mnemonic_to_seed, derive_recovery_keypair, sign_recovery_challenge).
• client/specs/ACCOUNT_RECOVERY_CLIENT_SPEC.md — flows, RPC surface (SetRecoveryKey, RecoverAccount), derivation-path rationale.

Group Messaging (MLS)

Status: designed, core implemented, not a shipped feature. The cryptographic group engine exists in construct-core/src/group/ (built on OpenMLS), but there is no group-chat product surface in the shipping clients, and this chapter is not yet a normative interoperability specification. It documents the design and the current implementation boundary so the direction is on record; treat every statement as "designed / partial", not "in production". The 1:1 protocol (Chapters 4–5) is unaffected.

12.1 Why MLS rather than pairwise fan-out

The 1:1 protocol (Chapter 5) gives two-party forward secrecy and post-compromise security via the Double Ratchet. Extending that to groups by encrypting separately to each member (pairwise fan-out) costs O(n) per message and has no group-level post-compromise security. Konstruct's group design instead uses MLS — the Messaging Layer Security protocol, RFC 9420 — which maintains a shared group secret through a logarithmic-cost ratchet tree, so adding/removing a member and healing after a compromise are O(log n) operations.

12.2 Ciphersuite and library

• MLS ciphersuite: MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519 (construct-core/src/group/mod.rs) — DHKEM-X25519 for the ratchet-tree HPKE, AES-128-GCM as the group AEAD, SHA-256 as the hash, Ed25519 for signatures. This is a standard RFC 9420 ciphersuite; interoperability is a design goal.
• Implementation: the OpenMLS Rust library with the OpenMlsRustCrypto provider, wrapped by construct-core's group module. Konstruct does not re-implement the MLS state machine.

Post-quantum note: this ciphersuite is classical (X25519/Ed25519). A hybrid PQ MLS ciphersuite is future work and is not part of the current design.

12.3 Group state model

MLS advances a group through epochs. Membership changes and key updates are carried as Proposals that are applied by a Commit; a new member is bootstrapped with a Welcome message. The core surfaces exactly these concepts (construct-core/src/group/mls_error.rs: EpochMismatch, WelcomeError, CommitError):

• KeyPackage — a member publishes a signed key package (an X25519 HPKE init key + Ed25519 credential) that others use to add it.
• Welcome — joining material for a newly added member; processed via join_from_welcome.
• Commit — applies a batch of proposals and advances the epoch; a client whose local epoch is behind MUST pull pending commits before sending (EpochMismatch → "pull pending commits first").

The server orders and fans out these handshake messages but, as in the 1:1 case, cannot derive the group secret — it never holds the members' HPKE private keys.

12.4 Device store and persistence

OpenMLS persists all group state (ratchet-tree material, pending key packages, epoch secrets) through its StorageProvider. Konstruct uses one long-lived provider per device — MlsStore (construct-core/src/group/mls_store.rs) — rather than a throwaway provider per group, because a Welcome references key-package material that must already be in the same store that later loads the group by id. The whole store is exported for host-app persistence as a versioned CFE blob (CfeMlsStoreV1, msg_type = 0x44; CFE envelope per §6.3).

12.5 Implementation boundary

Until the interop spec and the shipping surface exist, a second implementation cannot target Konstruct groups from this document alone. That work is tracked as a future revision; see Implementation Status.

Key Transparency

Status: per-bundle inclusion proofs are live; split-view detection is not. The server does maintain an append-only Merkle log and returns a Signed Tree Head (STH) plus an inclusion proof inline with every pre-key bundle, and the client does verify both on receipt. What is missing is the transparency layer that makes KT meaningful against a malicious (not merely honest-but-curious) server: a publicly monitorable log endpoint, consistency checking over time, and STH gossip / third-party auditing. Until those exist, the STH is a self-signed commitment that catches a server which contradicts itself to you — not one that equivocates consistently across victims. This chapter records what is deployed, and the exact remaining boundary.

13.1 The problem it solves

End-to-end encryption authenticates messages to a key, but a client still has to trust that the identity key it fetched for a contact is really that contact's key. A malicious or compromised directory server could hand out a key it controls (a key-substitution / MITM attack). Fingerprint comparison ("safety numbers") defends against this but depends on users manually comparing out of band.

Key Transparency (KT) makes the directory accountable instead: every identity key the server ever vouches for is committed to a public, append-only log, and clients cryptographically verify that the key they were given is in that log and that the log has never been rewritten. A server that equivocates — showing one key to the victim and another to everyone else — is caught, because it cannot produce consistent proofs against a single published log.

13.2 Construction (RFC 6962)

Konstruct's log follows RFC 6962 §2 (the Certificate Transparency Merkle tree), reused for identity keys:

• Leaf. Each device registration appends a leaf hashing (device_id, identity_public_key) — kt_hash_leaf(device_id, identity_key_b64). A key rotation appends a new leaf rather than mutating the old one (db_ensure_leaf), so the log records the full history. The hybrid PQ identity key gets its own leaf kind (domain byte 0x02 vs 0x00 for the Ed25519 identity leaf) in the same tree, so both keys share one STH.
• Tree head. The Merkle Tree Hash (merkle_tree_hash / kt_compute_root) reduces all leaves to a single root. The server signs a Signed Tree Head (STH) = Ed25519("ConstructKT-v1" ‖ tree_size ‖ root_hash) with its bundle-signing key.
• Inclusion proof (RFC 6962 §2.1.3, kt_verify_inclusion): proves a specific (device_id, identity_key) leaf is present at a given index in a tree of a given size and root.
• Consistency proof (kt_verify_consistency): proves that a newer tree is an append-only extension of an older one — the log grew, and no earlier entry was altered or removed.

13.3 What is live today

The cryptographic machinery is deployed and exercised on every bundle fetch, not merely designed:

1. Server appends + proves inline. On each pre-key-bundle request the server ensures the device's leaf exists (idempotent; a changed key appends a rotation leaf), builds the inclusion proof against the whole tree, and signs the STH — build_kt_proof / build_hybrid_kt_proof (key-service/src/kt.rs). The append-only table is DB-enforced: migration 044 documents that UPDATE/DELETE are never granted on kt_leaves. The proof rides in the bundle response as KtInclusionProof.
2. Client verifies inclusion + STH signature. On receipt the client reconstructs the Merkle root from the inclusion proof and checks the STH Ed25519 signature against the server bundle key pinned from /.well-known/construct-server — KeyServiceClient → KeyTransparencyVerifier.verify / verifyHybrid. A key that is not a leaf under a validly signed STH fails verification.

A KT-verified key is the strongest sender-attestation lever used by sealed sender (the .kt lever, Chapter 8 §8.3): a sealed sender whose certificate key matches a locally KT-verified key is vouched without depending on any freshly fetched server key.

13.4 What is missing — the split-view gap

Everything below the crypto is the part that makes KT meaningful against a server that is actively malicious rather than honest-but-curious. None of it is deployed:

Why it is not done yet. These are infrastructure and trust-distribution problems, not missing crypto. Split-view detection needs someone to gossip with — either multiple independent nodes/witnesses or a client-to-client gossip channel; federation is only newly implemented and single-node in practice, so there is no second party to cross-check against. A monitorable log endpoint plus an auditor is a separate service (storage, a gossip protocol, or a CT-style witness). For 1.0 the immediate MITM story is covered by trust-on-first-use pinning, safety-number comparison, and the certificate-signature lever (Chapter 8).

Honest limit. Today's STH is a signed, non-repudiable commitment from the server to you. It catches a server that contradicts itself to you, and gives you a durable signed record — but not a server that equivocates consistently across victims. Closing that requires the monitor endpoint, in-practice consistency checking, and gossip/auditing above. See Implementation Status.

13.5 References

• key-service/src/kt.rs (server) — build_kt_proof, build_hybrid_kt_proof, db_ensure_leaf, generate_inclusion_proof, tree_head_signable; shared/migrations/044_key_transparency.sql (append-only log), 054_kt_hybrid_leaf.sql (hybrid leaf kind).
• construct-core/src/crypto/key_transparency.rs — kt_hash_leaf, kt_compute_root, kt_verify_inclusion, kt_verify_consistency, merkle_tree_hash (shared client/server algorithm).
• construct-ios Networking/gRPC/Services/KeyServiceClient.swift, Security/KeyTransparencyVerifier.swift — live client-side inclusion + STH verification.
• RFC 6962 — Certificate Transparency Merkle tree (the reused construction).
• Sender-attestation use of KT-verified keys: Chapter 8 §8.3.

Appendix A — Error Registry

This appendix is the canonical registry of every error that a conforming Konstruct client can observe, organised by the layer that produces it. Each entry cites the exact variant in construct-core (or, where noted, the sibling construct-veil crate) and records the condition that raises it.

Keywords MUST, MUST NOT, SHOULD, MAY are per RFC 2119.

A.1 Layered error model

Errors in Konstruct travel up a stack of progressively narrower surfaces. An error condition that originates deep inside the cryptographic core is converted at each layer boundary into a variant appropriate for the consumer at that layer:

   application (iOS / macOS / Android UI)
                  ▲
                  │   uniffi_bindings::CryptoError      (FFI surface, §A.2)
   ────────────── ┼ ───────────────────────────────────────────────
                  │   cfe::CfeError                     (envelope,  §A.3)
                  │   wire_payload::WirePayloadError    (framing,   §A.4)
                  │   traffic_protection::PaddingError  (padding,   §A.5)
                  │
                  │   error::CryptoError                (internal,  §A.6)
                  │   utils::ConstructError             (top-level, §A.7)
                  │   group::mls_error::MlsError        (groups,    §A.8)
                  ▲
   Rust core

The dividing line at "FFI surface" is normatively significant: only the variants in §A.2 cross the UniFFI / JNI boundary by name. All deeper error types are mapped into SessionInitializationFailed, EncryptionFailed, or DecryptionFailed with a human-readable message field. Application code MUST NOT attempt to parse those message strings — they are diagnostic only.

The transport tier (Chapter 6 §6.5) has its own error surface in the separate construct-veil crate; it is included as §A.9 for completeness but is informational rather than normative for the core protocol.

Wire-level errors (server → client) flow as standard gRPC status codes and are covered in §A.10.

A.1.1 Stability policy

A.2 FFI surface — CryptoError

The application-facing error type exposed across UniFFI / JNI. Defined in construct-core/src/uniffi_bindings.rs:30.

FFI-SPK-STALE is the only variant with structured data that applications MUST react to: it conveys the age_secs so that UI can report "peer hasn't been online for N days" without re-deriving the threshold.

A.3 CFE envelope errors — CfeError

Raised when parsing a CFE envelope at the FFI boundary. Defined in construct-core/src/cfe/error.rs. Every entry below is a parse-time or integrity failure and MUST cause the envelope to be rejected before its payload is deserialised.

CFE-CRC-MISMATCH, CFE-PAYLOAD-TOO-LARGE, and CFE-TRUNCATED are the load-bearing integrity errors: they MUST cause an immediate rejection without any attempt to deserialise the payload.

A.4 WirePayload framing — WirePayloadError

Raised by the WirePayload pack/unpack routines (Chapter 6 §6.2). Defined in construct-core/src/wire_payload.rs:288-:299.

A WirePayload that fails to parse MUST be dropped without affecting session state. The receiver MUST NOT advance its Double Ratchet on a malformed frame.

A.5 Padding errors — PaddingError

Raised by the PKCS#7-style padding helpers (Chapter 5 §5.7). Defined in construct-core/src/traffic_protection/padding.rs:21.

PAD-INVALID MUST be returned in constant time relative to the plaintext length, to avoid leaking padding information via a timing side channel.

A.6 Internal CryptoError

Defined in construct-core/src/error.rs. These variants are not exposed across the FFI surface; they are converted to one of the §A.2 variants at the boundary (From<error::CryptoError> for uniffi_bindings::CryptoError).

A.7 Top-level ConstructError

Defined in construct-core/src/utils/error.rs. This is the Result<T> type returned by most public functions in the core; it composes CryptoError via #[from].

A.8 MLS group errors — MlsError

Defined in construct-core/src/group/mls_error.rs. MLS itself is documented at protocol-spec level in a future revision (see Implementation Status §7.1); the errors are listed here so that current implementers know what to expect from the construct-core/src/group/ API surface.

A.9 VEIL transport errors (informational)

These errors are produced by the construct-veil crate, NOT the protocol core. They are not part of the normative protocol surface and MAY change between releases of construct-veil. They are documented here as a navigation aid for implementers wiring the anti-censorship tier.

A.9.1 Coordinator — CoordinatorError

(construct-veil/src/veil/coordinator.rs)

A.9.2 Obfuscator — ObfuscatorError

(construct-veil/src/veil/obfuscator.rs)

A.9.3 Probe failure classification — ProbeFailureReason

(construct-veil/src/veil/fsm/types.rs) — used by the scoring layer to bucket probe outcomes:

FingerprintBlocked · WebTunnelDecoyResponse · TlsCertProblem · ConnectionFailed · Timeout · Unknown.

The sibling enum TransportFailureKind covers steady-state transport degradation (after a probe has already won) and shares the same spelling for the network-observable categories.

A.9.4 Scoring — ScoringError

(construct-veil/src/veil/scoring.rs)

A.10 gRPC status codes (informational)

Server-to-client errors in the MessagingService / AuthService etc. use standard gRPC status codes. The conventions below are normative for a conforming Konstruct deployment:

A.10.1 Auth disposal rules (CRITICAL)

The client MUST distinguish "transport failure" from "server says you are not authenticated":

• On UNAUTHENTICATED (16) or PERMISSION_DENIED (7) — and only on those codes — the client MUST delete its device keys and trigger re-registration.
• On any other gRPC error (UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, etc.) the client MUST NOT touch device keys. These are transient failures.

The reference iOS interceptor implements this distinction in AuthInterceptor.swift; client implementations on other platforms MUST replicate it. Deleting device keys on a transient failure silently logs the user out and forces them through re-registration — this has been a recurring bug in early development; the rule above exists to prevent regressions.

A.11 Diagnostics & logging guidance

When surfacing any error from this registry to the user or to logs:

1. At the FFI surface (§A.2), the variant tag is the stable contract. Show or log it verbatim. Do not parse the message field for control flow.
2. Below the FFI surface (§A.6–A.8), the variant names are advisory only. Logs MAY include them for debugging but the application code SHOULD treat the §A.2 variant it eventually receives as the source of truth.
3. Wire integrity errors (§A.3 CFE-CRC-MISMATCH, §A.4 WP-*) SHOULD be counted as security-relevant log events. A sustained stream of these from a single peer indicates either a misbehaving client or an active attacker injecting bytes.
4. FFI-SPK-STALE is a user-facing condition, not an internal error. UIs SHOULD render it as "this person hasn't opened Konstruct in N days" rather than as a generic failure dialog.

A.12 References

• FFI surface: construct-core/src/uniffi_bindings.rs
• CFE envelope: construct-core/src/cfe/error.rs
• WirePayload framing: construct-core/src/wire_payload.rs
• Padding: construct-core/src/traffic_protection/padding.rs
• Internal crypto: construct-core/src/error.rs
• Top-level Result: construct-core/src/utils/error.rs
• MLS: construct-core/src/group/mls_error.rs
• VEIL coordinator: construct-veil/src/veil/coordinator.rs
• VEIL obfuscator: construct-veil/src/veil/obfuscator.rs
• VEIL probe FSM: construct-veil/src/veil/fsm/types.rs
• VEIL scoring: construct-veil/src/veil/scoring.rs
• gRPC status codes: https://grpc.io/docs/guides/status-codes/

Appendix B — Post-Quantum Designs in Other Deployed Messengers

This appendix situates Konstruct's post-quantum construction against the other post-quantum messaging designs that are publicly documented and deployed at scale. It exists because the design decisions in Chapter 2 §2.4 and Chapter 4 §4.5 are not novel in kind, and a reader should be able to see which parts are conventional and which are ours.

Claims about other systems are sourced from their published specifications and are dated; claims about Konstruct cite the reference implementation, as required by the editorial rule.

B.1 The shared shape

Every deployed design in this space, Konstruct included, follows the same two-part pattern:

1. A post-quantum KEM (ML-KEM-768 in all four systems below) is run alongside a classical Diffie–Hellman, never instead of it, and the two secrets are combined through a KDF so that an adversary must break both.
2. The classical Double Ratchet is left intact, and post-quantum material is layered on top of it rather than replacing its DH ratchet.

The differences are in when fresh KEM material is introduced after the handshake, and how the large KEM objects are carried.

B.2 Handshake-only versus continuing

Signal's PQXDH was the first at-scale deployment and deliberately covered only the initial handshake, which means it provided no post-quantum post-compromise security: a session that ran for months rested on a single KEM contribution made at its start. Apple's PQ3 and Signal's later SPQR both exist to close that gap, and Konstruct's Suite 3 addresses the same gap by the same reasoning.

Konstruct Suite 2 alone therefore sits at the PQXDH level. The continuing property requires Suite 3, which is negotiated separately (§2.4).

B.3 Rekey cadence

The three units are not comparable directly. Konstruct counts DH ratchet turns — changes of conversational direction — so a one-sided burst of any length makes no progress, while an alternating exchange rekeys after sixteen turns. Apple counts messages and additionally guarantees a floor in wall-clock time; Signal is bounded only by how fast chunks can be carried.

Konstruct is the only one of the three with no time-based floor. A conversation that alternates a few times a month rekeys at that rate, and one that never alternates does not rekey at all.

B.4 Carrying the KEM objects

ML-KEM-768 encapsulation keys are 1184 bytes and ciphertexts 1088 bytes, against 32 bytes for an X25519 public key. Each system resolves this differently:

• Apple PQ3 sends the key whole and accepts the cost, reporting that the PQ ratchet adds more than 2 KB to a message. The published rationale for rekeying only periodically is precisely that sending it with every message caused visible delivery delays on poor connectivity.
• Signal SPQR splits both objects into chunks protected by Reed–Solomon systematic erasure codes, spread across message headers: roughly 36 and 30 chunks for the two bulk phases, so that any sufficient subset reconstructs the object regardless of loss or reordering. The published design also splits the encapsulation key into a 64-byte seed-plus-hash phase and a bulk phase so the two directions can transmit in parallel.
• Konstruct Suite 3 sends each object whole in the frame's PQ section (Chapter 5 §5.3), and re-attaches it to every outgoing message until implicitly acknowledged (§2.4.2 rule 2). Loss is therefore recovered by repetition rather than by redundancy, at a cost of 1184 or 1088 bytes per outgoing message for the duration of an unacknowledged exchange.

B.5 Advancing without a reply

A rekey that needs a message in the opposite direction stalls in a one-sided conversation. Apple PQ3 addresses this explicitly by letting encrypted delivery receipts carry the ratchet forward, so a device that is merely online completes the exchange without the user replying.

Konstruct obtains the same property without a dedicated mechanism. Delivery receipts are ordinary session frames — they are encrypted through the same ratchet as any message (content type 14 inside the frame) — so they advance the DH ratchet turn counter on receipt and carry any pending PQ field on send (§2.4.1). A device that is online and acknowledging therefore keeps the exchange moving whether or not its user replies.

B.6 Granularity of the post-quantum guarantee

This is the sharpest difference and worth stating precisely.

Signal's SPQR carries its own symmetric chain inside the post-quantum component, so the post-quantum contribution ratchets between rekeys and the post-quantum half of forward secrecy has the same per-message granularity as the classical half.

Konstruct's Suite 3 derives every message key of an epoch from the same pq_epoch_secret (§2.4.2 rule 5). Within an epoch the post-quantum contribution is a constant. Forward secrecy at message granularity is supplied by the classical Double Ratchet, which is unmodified and continues to provide it; what is coarser is specifically the post-quantum component, whose granularity is the epoch rather than the message.

The practical reading: an adversary who obtains one epoch secret — and who can also break X25519 — recovers the messages of that epoch. Against an adversary who can break neither, or only one of the two, the guarantee is unchanged.

B.7 Group messaging

Konstruct's group path is MLS (Chapter 12). Post-quantum MLS cipher suites combining ML-KEM with traditional elliptic-curve KEMs are specified in an IETF draft (draft-ietf-mls-pq-ciphersuites) and are not adopted here; the group path is classical today.

Matrix, for comparison, uses Olm/Megolm and has no deployed post-quantum layer; its published direction is migration to MLS, which would inherit MLS's post-quantum cipher suites when those are adopted.

B.8 Formal analysis

Signal's SPQR implementation is machine-checked with Hax and F* for panic-freedom and field-arithmetic correctness, with ProVerif models of the protocol properties; the underlying construction was published at Eurocrypt 2025 and USENIX Security 2025. Apple's PQ3 received an independent mechanised analysis published at USENIX Security 2025.

Konstruct's construction has received no formal analysis. This is stated as a fact about the current state of the work, not as a deficiency claim about the construction.

B.9 Sources

• Signal — Signal Protocol and Post-Quantum Ratchets (2 October 2025)
• signalapp/SparsePostQuantumRatchet
• Apple Security Research — iMessage with PQ3 (2024)
• A Formal Analysis of Apple's iMessage PQ3 Protocol, USENIX Security 2025
• ML-KEM and Hybrid Cipher Suites for MLS, IETF draft
• Olm & Megolm — Matrix Specification

Disclosure & Contact

Reporting a security issue

Konstruct does not operate a security inbox. Use GitHub's private vulnerability reporting on any of the relevant repositories — your report will be visible only to maintainers until a fix is published.

• construct-core — cryptographic core
• construct-ios — iOS / macOS client
• construct-server — server-side
• construct-veil — anti-censorship transport
• construct-engine — QUIC engine
• construct-protocol — issues with this specification

The canonical disclosure metadata file (RFC 9116) is at konstruct.cc/.well-known/security.txt.

Scope

Cryptographic, transport, or implementation issues in any of the public repositories listed above are in scope.

Server infrastructure issues (denial-of-service, mis-configuration of the single deployment server) are out of scope while the project is in single-server alpha — the whole network depends on one trusted operator today, and infrastructure hardening is part of the federation roadmap rather than something a disclosure can usefully fix.

Project updates

Project updates and ad-hoc technical posts are at @maxeliseyev on X.

Changelog

The Konstruct Protocol Specification follows Semantic Versioning at the document level:

• MAJOR — a wire-incompatible protocol change.
• MINOR — a backwards-compatible normative addition (new field, new optional behaviour, new normative requirement that an existing implementation already satisfies).
• PATCH — editorial corrections that do not change implementer obligations.

v0.1.0 — unreleased

Initial public draft. The core protocol chapters and the introduction are present at full depth: RFC 2119 normative language, byte-level wire layouts, mathematical handshake notation (DH₁..DH₄, INITIATOR / RESPONDER role separation), and verified-against-code parameter values.

• Introduction — project scope, conventions, honest current status table.
• Threat Model — adversary classes (network, server, historical-device, spam/Sybil), explicit non-goals, trust assumptions.
• Cryptographic Primitives — Suite 1 (X25519, Ed25519, ChaCha20-Poly1305, HKDF-SHA-256, PBKDF2, Argon2id) and Suite 2 (adds ML-KEM-768, FIPS 203). Constants summary table, randomness rules, zeroization requirements.
• Identity & Key Hierarchy — six key types, sizes, rotation cadence, storage classes, registration bundle wire format.
• Session Handshake — X3DH initiator and responder paths with full math; PQXDH deferred contribution at RK₁; tie-break rule for concurrent initiation.
• Message Encryption — Double Ratchet state machine, KDF helpers, AD v3 layout (with v2 fallback), DH ratchet step, mandatory DoS guards, PKCS#7 padding (mod 255).
• Transport Layer — WirePayload binary header (52 B fixed + variable KEM), CFE envelope (16 B header + MessagePack), gRPC service surface, VEIL anti-censorship tier.
• Implementation Status — honest component matrix (what's implemented, what's stubbed, what's open security issue), platform support matrix, and open issue tracker.
• Appendix A — Error Registry — every error variant a conforming client can observe, organised by surface (FFI / CFE / WirePayload / padding / internal / MLS / VEIL / gRPC). Includes the auth-disposal rules that prevent accidental device-key deletion on transient transport failures.
• Disclosure & Contact — GitHub Security Advisories per repository; no email inbox.

Editorial decisions in this revision

• Konstruct (Latin) / Конструкт (Cyrillic) as the canonical brand spellings.
• NIST FIPS names for PQ algorithms (ML-KEM-768, ML-DSA-65), with the informal name (Kyber-768, Dilithium-3) in parentheses for first mention.
• Code-grounded claims — every algorithm and constant cites its source file in construct-core. The editorial rule for this repo is "code wins" (see AGENTS.md).
• No self-graded "security score" — replaced with a concrete open-issues table in Implementation Status.
• Federation, P2P, sealed sender, MLS — explicitly marked as not-yet-implemented rather than present-tense claims.

v0.1.1 — unreleased

• ML-DSA-65 hybrid signatures — status updated from "Not implemented" to "Implemented (optional, feature-gated)" in the component matrix. Server-side wire verification activated (construct-server e2e.rs:318), closing the last gap that kept PQ signatures decorative.

Known gaps for v0.2

• Published test vectors for the X3DH and Double Ratchet operations.
• MLS group-chat protocol (the code is in construct-core/src/group/ but not yet documented at protocol-spec level).
• Federation (server-to-server) protocol — currently single-server.
• Wire-format reference appendix with hex-dumped example handshakes.

Removed from this revision compared with the internal draft

Content from the internal whitepaper draft that did not meet the "verified against code" editorial bar was deferred rather than copied:

• Self-rated "security score 8.5 / 10 → 10/10" — no industry-standard rubric exists for such a score.
• "First messenger with formally verified Rust Signal Protocol implementation" — aspirational, not done.
• Some roadmap dates from the internal draft, which belong on the marketing site rather than in a normative specification.

v0.1.2 — unreleased

• New Architecture Overview chapter — an orientation map of the whole system: the always-on E2EE floor, the layered model (transport, entry discovery, route, overlay, delivery) and its offline mesh foundation, and how the system degrades gracefully across censorship tiers (free → DPI blacklist → national allowlist → blackout). Descriptive architecture; normative detail stays in the per-component chapters.

• Status reconciliation against current code. Several component statuses that were accurate at v0.1.0 have since shipped:

  • Federation (server-to-server) — "not implemented" → implemented (inbound + outbound sealed delivery, Ed25519-signed; multi-node interoperability test outstanding).
  • Sealed sender — "not implemented" → implemented (sealed path carries no sender_id at rest; enforced-default rollout in progress).
  • VEIL transport — veil-front is now the production obfuscation transport; obfs4 / WebTunnel are retired (were "deployed" / "proof-of-concept").
  • QUIC / HTTP-3 — recorded as the production engine-QUIC direct path with HTTP/2 fallback; not yet normatively specified.

  Federation and sealed sender, listed as v0.2 gaps under v0.1.1, are now implemented.

• Accuracy pass (2026-07-27) — code-verified corrections. Fixed claims that had drifted from the reference implementation:

  • Sealed sender / threat model — resolved a contradiction where Chapter 1 still said sealed sender was "not yet deployed" while Chapter 7 said "implemented". Sealed sender is on by default; the server-adversary section now states the server cannot read sender_id for sealed traffic, lists the true residual metadata, and cites the masking code (messaging-service/src/envelope.rs:38, StealthPolicy.swift:42, SessionCoordinator.swift / MessagingServiceClient.swift).
  • Session-control channel — documented that session_ready / ping / SESSION_RESET_INIT / END_SESSION are now sealed (fail-closed).
  • Client IP minimisation — new status entry: the server stores no raw IP, only a salted hash (construct-utils/src/lib.rs:92).
  • Privacy Pass enforcement — clarified it runs in warn, not enforce (deferred past 1.0).
  • Keychain accessibility — corrected WhenUnlockedThisDeviceOnly → AfterFirstUnlockThisDeviceOnly for crypto/session state (KeychainManager.swift:21).
  • Media AEAD — documented AES-256-GCM (per-file key, delivered E2E) for attachments, distinct from the Double Ratchet's ChaCha20-Poly1305 (MediaUploadService.swift:83).

• New Metadata Privacy & Sealed Sender chapter — the sealed-envelope wire structures (SealedSenderEnvelope, SealedInner, SenderCertificate from core/envelope.proto), what each server role sees vs. cannot, recipient-side sender verification (KT / signature vouching, unvouched-but-delivered), the always-on fail-closed invariant and sealed/excluded scope, Privacy Pass anti-abuse (warn status, verifiable-VOPRF in progress), IP minimisation, and an honest residual-metadata table. All claims code-cited.

• New Anti-Abuse: Privacy Pass Tokens chapter — the anonymous-token VOPRF over Ristretto255 (blind → evaluate → unblind → redeem, verify_token), age-tiered issuance caps, redemption + double-spend

  • the off/warn/enforce policy switch (production is warn), and the verifiable-issuance batched Chaum–Pedersen DLEQ (full transcript, malicious-issuer key-tagging defence, client key-pinning, KAT). Honest claim boundary: honest-but-curious today, malicious once enforce relies on the DLEQ. All claims code-cited.

• Chapter 6 (Transport) deepened + corrected. Fixed stale non-guarantee rows (sealed sender is on-by-default; obfs4 is retired, not an "in-progress fix"; raw IPs not persisted). New §6.5.3 — the direct-first .auto connection ladder and graceful degradation across censorship tiers, with the honest limit that obfuscation does not cross a national allowlist and VEIL is not itself a metadata-hiding layer.

• New Voice and Video Calls chapter — call signalling (SDP/ICE) rides the E2EE message path and is sealed; the real call type lives inside the encrypted KNST frame for ordinary sends. Media is WebRTC DTLS-SRTP keyed via that E2EE signalling, so a 1:1 call is end-to-end encrypted (no SFrame needed); audio shipped, video disabled; honest connectivity-metadata table (ICE address exchange, TURN).

• New Account Recovery chapter — BIP39 12-word account re-access (Ed25519 recovery keypair, server stores only the public key; restores account, not history) and SLIP-39 t-of-n social recovery of the identity vault (Shamir over GF(2⁸), 28-word mnemonics). No server-side key escrow. All claims code-cited.

• New Group Messaging (MLS) chapter (designed / partial) — the MLS group engine (OpenMLS, ciphersuite MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519, epoch/Commit/Welcome model, per-device CFE-persisted store). Clearly marked: core implemented, no shipping surface, not yet a normative interop spec.

• New Key Transparency chapter — RFC 6962-style append-only key log, Signed Tree Head, inclusion proofs, and the honest deployment boundary: per-bundle inclusion proofs are live, while public monitoring, consistency checking, and STH gossip remain open.

• Key Transparency status corrected (2026-07-27). A code audit found the earlier "server not yet publishing the log" claim was wrong: the server maintains an append-only Merkle log and returns a Signed Tree Head + inclusion proof inline with every pre-key bundle (key-service/src/kt.rs, migrations 044/054), and the client verifies inclusion + STH signature on receipt (KeyTransparencyVerifier). Chapter 13 and the Implementation Status KT row were rewritten to state what is live and to name the real remaining gap — no public monitor endpoint, no in-practice consistency checking, no STH gossip/auditor — i.e. the current STH catches a self-contradicting server but not one that equivocates consistently across victims (split view).

• Protocol-code audit (2026-08-26). Reconciled the public spec with construct-core, construct-server, and the iOS client on the protocol surfaces implementers need:

  • WirePayload and CFE byte layouts corrected to little-endian where the reference encodes little-endian; CFE CRC corrected to payload-only.
  • Suite 3 (PQ_RATCHET) documented as a separate, capability-negotiated sparse continuous ML-KEM-768 ratchet, with its WirePayload PQ section and message-key HKDF.
  • Double Ratchet KDF labels corrected (Double-Ratchet-*), AD v3 length corrected to 125 B for UUID sessions (129 B with Suite 3 epoch), and AD v2 fallback corrected to the same field layout with a different version byte.
  • Prekey signatures corrected from public_key || epoch to b"KonstruktX3DH-v1" || [0x00, suite_id] || public_key; SPK clean freshness corrected from 10 days to 30 days with explicit stale-tolerant degraded init.
  • Hybrid Ed25519 + ML-DSA-65 signatures updated from planned to implemented/capability-gated, including the hybrid identity cross-signature and 3373-byte signature format.
  • Sealed sender metadata updated: normal sealed traffic no longer exposes real content_type; SealedInner.content_type, priority, and ttl are deprecated server-visible compatibility fields, with only structural exceptions 21 and 24 allowed before decryption.

• Suite 3 operational parameters and prior-art comparison (2026-08-28). Read out of construct-core while answering how the classical and post-quantum halves combine end to end.

  • §2.4.1 adds the cadence and retention constants that the chapter previously described only as "a configured cadence": 16 DH-ratchet turns (clamped [4, 64]), 4 retained epoch secrets, unanswered proposals abandoned by age. The unit matters and was not stated: the counter advances inside the DH ratchet step, so a one-sided burst of any length makes no PQ progress. A pending field rides on every outgoing frame including delivery receipts, so an acknowledging peer carries the exchange forward without replying.
  • §2.4.2 adds five normative rules that were implemented but unwritten: commit-on-success (a malformed PQ field must not alter session state and must not affect its carrier's classical delivery), re-attach until implicitly acknowledged, one exchange in flight, ek_hash disambiguation of re-proposals, and the fact that the epoch secret is constant within an epoch.
  • New Appendix B compares the construction with Signal PQXDH, Signal's Triple Ratchet / SPQR (October 2025), Apple iMessage PQ3, and the MLS post-quantum cipher-suite drafts, on five axes: handshake-only versus continuing, rekey cadence, how the 1184/1088-byte KEM objects are carried, advancing without a reply, and the granularity of the post-quantum guarantee.
  • §7.3 records four open issues that comparison surfaced — PQR-1 (no wall-clock rekey floor), PQR-2 (epoch-granular post-quantum forward secrecy against message-granular classical), PQR-3 (KEM objects carried whole and re-attached per message), PQR-4 (epoch retention of 4 against a skipped-key tolerance of 1000).