Kecalek_python/CLAUDE.md

Encrypted Chat — Project Context

End-to-end encrypted chat with forward secrecy (X3DH + Double Ratchet, Signal Protocol). Server stores and relays opaque blobs — never sees plaintext. RSA retained for login only.

Files

File	Lines	Purpose
schema.sql	~172	MySQL schema (users, devices, signed_prekeys, one_time_prekeys, conversations, conversation_members, group_invitations, messages, message_recipients, message_reactions, group_sender_keys, message_reads, image_uploads, user_profiles)
db.py	~1500	MySQL CRUD — one connection per call, dictionary=True cursors, returns dicts. Includes profile CRUD, get_user_contacts(), update_conversation_creator(), get_conversation(). Phantom user CRUD + upgrade_phantom_user(). Invitation CRUD. Group avatar. Device CRUD. Per-device prekey/session management. Reactions CRUD (add_reaction, remove_reaction, get_reactions). Pins CRUD (pin_message, unpin_message, get_pinned_messages).
server.py	~2200	Asyncio TCP server, handler dispatch, rate limiting, real-time notifications via connected_clients dict. Profile + avatar handlers. Online/offline status push. Leave group, delete conversation, group invitations, group avatar handlers. Phantom user support. Graceful shutdown. 4 asyncio.Lock guards (H4 fix). Device registration + per-device key bundles + per-device notifications. SPK age reporting in get_prekey_count. Reactions, pins, pinned messages handlers. TCP keepalive (SO_KEEPALIVE) + dead writer cleanup. Streaming download (download_stream handler).
protocol.py	~114	Newline-delimited JSON protocol, ProtocolReader/ProtocolWriter, encode_binary/decode_binary (base64). Constants: VERSION, MAX_MESSAGE_BYTES, MAX_IMAGE_BYTES, MAX_FILE_BYTES, IMAGE_CHUNK_SIZE.
crypto_utils.py	~950	Ed25519, X25519, AES-256-GCM, HKDF, PBKDF2, X3DH, DoubleRatchet (with state snapshot/rollback), SenderKeyState (with state snapshot/rollback). RSA for login only. ECP1 password-based key encryption format (600k PBKDF2 iterations). Contact key verification: compute_fingerprint(), format_fingerprint(), compute_safety_number(), encode_verification_qr(), decode_verification_qr(). Message padding: pad_plaintext(), unpad_plaintext().
chat_core.py	~2850	ChatClient class — session management, X3DH/ratchet encryption, local key storage, reconnect, profiles, file sharing, leave group, delete conversation, invitations, group avatar. Multi-device: per-device sessions, device_id persistence, device bundle cache. SPK rotation (7-day) with grace period. Reactions, pins, forwarding methods. Contact key verification: TOFU registry, explicit verification, safety numbers, QR code verify. Used by CLI + GUI
client.py	~520	Interactive CLI client — reactions, pin, forward, pinned messages, verify contact, show fingerprint commands
gui_client.py	~3600	PyQt6 GUI — AsyncBridge QThread bridges asyncio <-> Qt signals, MainWindow, UserProfileDialog, VerificationDialog, connection indicator + auto-reconnect, online status, file sharing, leave group, unread badges, circular avatars in conv list, online green dot overlay, group invitations UI, delete conversation, group avatar support, message reactions (emoji badges), forwarding with dialog, pin/unpin with indicator, pinned messages list, @mentions autocomplete, contact verification indicators (conv list green checkmark, E2E label status, key change warning dialog)
ios_client/	~6200	Native iOS client (Swift/SwiftUI) — wire-compatible with Python server. 47 Swift files: CryptoKit crypto (AES-GCM, HKDF, Ed25519, X25519), pure Swift GF(2^255-19) field arithmetic for Ed→X conversion, Security.framework RSA-4096, Network.framework TCP+TLS, Signal Protocol (X3DH + Double Ratchet + Sender Keys), SwiftUI views. Uses project.yml (XcodeGen).

Architecture & Data Flow

Encryption: X3DH + Double Ratchet (Signal Protocol)

Keys per user:

• RSA-4096 — Login challenge-response only (server stores public key). Password-encrypted with ECP1 format (PBKDF2 600k iterations + AES-256-GCM).
• Identity Key (IK) — Ed25519 (signing) + converted to X25519 (for DH in X3DH). Password-encrypted with ECP1 format.
• Signed Pre-Key (SPK) — X25519, signed by IK, uploaded to server. Rotates every 7 days (M4). Previous SPK kept for grace period (in-flight X3DH).
• One-Time Pre-Keys (OPK) — X25519, consumed on X3DH initiation, auto-replenished when count < 20

DM flow:

1. Alice fetches Bob's per-device key bundles (IK, SPK per device, OPK per device) -> X3DH per device -> shared secret per device
2. Double Ratchet initialized from shared secret — one session per (user, device) pair
3. Each message: symmetric ratchet (HMAC chain) -> message key -> AES-256-GCM
4. Each reply direction change: DH ratchet (new X25519 keypair) -> new root + chain keys
5. Per-device ciphertext — each recipient device gets individually encrypted blob
6. Self-encrypted copy uses SELF_DEVICE_ID sentinel, readable by all own devices

Group flow (Sender Keys):

1. Each sender has own SenderKeyState per group
2. Sender key distributed to members via pairwise Double Ratchet (as control DM with _sender_key field)
3. Group messages: symmetric ratchet on sender key -> AES-256-GCM
4. Same ciphertext replicated to all recipients (efficient)

Contact Key Verification (Out-of-Band Trust)

Problem: Server stores identity keys but could MITM new sessions by substituting keys. Users need a way to verify keys out-of-band.

Design: Entirely client-side — zero server changes. Server already stores identity keys in users.identity_key (32B Ed25519) and returns them via get_user_info/get_key_bundle. Verification state is local-only (privacy by design — server never learns who verified whom).

Trust model:

First contact → TOFU (Trust On First Use) → "trusted" (key recorded)
                                           ↓
                              Out-of-band verify → "verified" (explicit confirmation)
                                           ↓
                              Key change detected → "changed" / "changed_verified" (WARNING)
                                           ↓
                              Accept new key → "trusted" (verification reset)

Verification methods:

1. Safety numbers — 60-digit number (12 groups × 5 digits), deterministic for each pair (lower user_id's fingerprint first). Both users see the same number — compare in person or over trusted channel.
2. QR codes — Encode 0x01 + uid_len + uid + identity_key (70 bytes). One user shows QR, other scans → automatic verification.
3. Fingerprints — Per-user 30-digit number (6 groups × 5 digits). Visual comparison.

Algorithm (Signal NumericFingerprint compatible):

• Fingerprint: SHA-512 iterated 5200× on version(2B) + identity_key(32B) + user_id(UTF-8), truncated to 32 bytes
• Display: int(bytes[i*5:(i+1)*5], big-endian) % 100000, zero-padded to 5 digits

Local storage (encrypted with _local_key, AES-256-GCM):

• known_identity_keys.bin — TOFU registry: {user_id → {identity_key hex, first_seen, last_seen}}
• verified_contacts.bin — Explicit verification: {user_id → {identity_key hex, verified_at, method}}

Tamper resistance: Oba soubory jsou šifrovány AES-256-GCM (klíč odvozen z identity key přes HKDF). Na rozdíl od session/sender key souborů (které mají plaintext migration fallback kvůli zpětné kompatibilitě) verifikační soubory nemají žádný plaintext fallback — pokud dešifrování selže, vrátí se prázdný dict. Útočník s přístupem k disku (ale bez znalosti hesla/identity key) tedy nemůže:

• Podvrhnout falešný "verified" status (injekce do verified_contacts.bin)
• Potlačit TOFU key-change warning (injekce do known_identity_keys.bin)
• Nejhorší případ při manipulaci = verifikace se resetuje (prázdný stav), nikdy se nepřijme podvržená hodnota

Threat model:

• DNS únos / podvržený server (existující kontakt): TOFU detekuje key change → warning dialog. Útočník nemůže tiše podvrhnout klíč.
• DNS únos / podvržený server (první kontakt): TOFU věří prvnímu klíči — MITM úspěšný. Obrana: out-of-band verifikace safety number přes jiný kanál (telefon, osobně). Pokud se čísla neshodnou → odhaleno.
• Kompromitovaný reálný server: Server podmění klíč v get_key_bundle → TOFU detekuje změnu (stejné jako DNS únos). Server neví kdo je verified (stav je lokální) → nemůže cíleně obejít.
• Disk access bez hesla: Verifikační soubory šifrovány AES-256-GCM, žádný plaintext fallback → nelze podvrhnout. Viz tamper resistance výše.
• TLS je první linie obrany: S platným certifikátem DNS únos nestačí. Bez TLS / s TLS_INSECURE je MITM triviální. Verifikace kontaktů je druhá linie — chrání i při kompromitovaném serveru.

Data flow:

1. _get_user_info() calls check_identity_key() → records TOFU or detects change
2. Key change → _key_change_cb fires → GUI shows warning dialog
3. User opens VerificationDialog → sees safety number + QR → marks verified
4. _rebuild_conv_list() queries get_verification_status() → shows green checkmark for verified DMs
5. E2E label in chat header shows "Verified" (green) or "Encrypted" (muted)

QR code encoding detail:

• Raw binary payload (0x01 + uid_len + uid + identity_key) je před vložením do QR zakódován jako base64 (ASCII-safe)
• Důvod: QR čtečky (pyzbar/zbar) re-kódují binární data přes UTF-8 → byty > 127 se zkomolí
• Při skenování se base64 dekóduje zpět na raw bytes → decode_verification_qr()
• iOS implementace musí použít stejný base64 wrapper (viz iOS spec níže)

Self-verification exclusion:

• Vlastní user_id se nikdy nezobrazuje jako "unverified" — TOFU registr neobsahuje vlastní klíč (ten je na disku)
• GUI: security section v UserProfileDialog se nezobrazuje pro vlastní profil, verified badge v group info přeskakuje vlastní uid

Protocol

Newline-delimited JSON over TCP (optional TLS). Fields: type, status, data, request_id. Binary data encoded as base64 via encode_binary()/decode_binary().

Request/response pattern: Client sends {"type": "...", "request_id": "uuid", ...}, server responds with same request_id. Notifications (push) have no request_id.

Server notifications (push to connected clients)

• new_message — per-recipient ciphertext included
• messages_read — conversation_id + user_id + message_ids
• message_deleted — message_id + conversation_id
• conversation_created — conversation_id, name, created_by, members[] (pushed to added members)
• member_added — conversation_id, user_id, username, email (pushed to all members except requester)
• member_removed — conversation_id, user_id (pushed to removed member + remaining members)
• group_invitation — conversation_id, conversation_name, invited_by, invited_by_username (pushed to invited user)
• conversation_renamed — conversation_id, name, renamed_by (pushed to all members except renamer)
• session_reset — from_user_id, from_device_id (pushed to peer when session reset requested)
• message_reacted — message_id, conversation_id, user_id, username, reaction, action (pushed to members)
• message_pinned — message_id, conversation_id, user_id, username (pushed to members)
• message_unpinned — message_id, conversation_id, user_id, username (pushed to members)
• user_online — user_id (pushed to contacts when user connects)
• user_offline — user_id (pushed to contacts when user's last connection drops)
• online_users — user_ids[] (sent to user on login — list of currently online contacts)

DB Schema (schema.sql)

users: id, username, email (UNIQUE), rsa_public_key (TEXT), identity_key (BLOB 32B Ed25519), created_at
devices: id, user_id FK, device_name (nullable), created_at, last_seen_at
signed_prekeys: id, user_id FK, device_id (nullable), public_key (BLOB 32B), signature (BLOB 64B), created_at
one_time_prekeys: id, user_id FK, device_id (nullable), public_key (BLOB 32B)
conversations: id, created_at, name (nullable), created_by (nullable), avatar_file (nullable)
conversation_members: conversation_id + user_id (composite PK), joined_at
group_invitations: id, conversation_id FK, user_id FK, invited_by FK, created_at, UNIQUE(conversation_id, user_id)
messages: id, conversation_id FK, sender_id FK, sender_device_id (nullable), ratchet_header (BLOB JSON),
          x3dh_header (BLOB JSON nullable), sender_chain_id (BLOB nullable), sender_chain_n (INT nullable),
          created_at, deleted_at, image_file_id, pinned_at (nullable), pinned_by (nullable)
message_recipients: message_id + user_id + device_id (composite PK), encrypted_content (BLOB), nonce (BLOB),
                    ratchet_header (BLOB nullable), x3dh_header (BLOB nullable)
message_reactions: id, message_id FK, user_id FK, reaction VARCHAR(32), created_at, UNIQUE(message_id, user_id, reaction)
group_sender_keys: conversation_id + sender_id + device_id (composite PK), chain_id (BLOB 32B), created_at
message_reads: message_id + user_id (composite PK), read_at
image_uploads: file_id (PK), conversation_id FK, uploader_id FK, file_size, completed, created_at
user_profiles: user_id (PK FK), phone, phone_visible, email_visible, location, location_visible, avatar_file, updated_at

Constant: SELF_DEVICE_ID = "00000000-0000-0000-0000-000000000000" — sentinel for self-encrypted copies and legacy rows.

Index: messages(conversation_id, created_at) for query performance.

Server Protocol — All Message Types

Pre-login (no session required)

Type	Handler	Purpose
register	handle_register_start	Start registration (username, email, public_key, identity_key)
register_confirm	handle_register_confirm	Confirm with 6-digit code
login_start	handle_login_start	Get RSA challenge
login_finish	handle_login_finish	Respond with RSA signature -> session. Client sends client_version, server returns server_version in response. Also sends online_users and user_online notifications.
get_user_info	handle_get_user_info	Get user info + identity_key (by email or user_id)
pairing_start	handle_pairing_start	New device starts pairing (gets 8-digit code)
pairing_poll	handle_pairing_poll	New device polls for key payload

Post-login (session required)

Type	Handler	Purpose
upload_prekeys	handle_upload_prekeys	Upload SPK + batch of OPKs (server verifies SPK signature)
get_key_bundle	handle_get_key_bundle	Fetch key bundle for X3DH (consumes one OPK)
get_prekey_count	handle_get_prekey_count	Check remaining OPK count + SPK age (spk_created_at) for rotation
ensure_prekeys	handle_ensure_prekeys	Combined get_prekey_count + upload_prekeys in single round-trip. Returns count + spk_created_at + upload status.
create_conversation	handle_create_conversation	Create conversation — DMs auto-add both; groups add creator only + create invitations for others
find_conversation	handle_find_conversation	Find existing DM by email
add_member	handle_add_member	Create invitation for user to join group (was: direct add)
remove_member	handle_remove_member	Remove member (creator only)
leave_group	handle_leave_group	Voluntarily leave a group (transfers creator if needed, blocks DM leave)
rename_conversation	handle_rename_conversation	Rename group conversation (creator only, max 100 chars), pushes conversation_renamed to members
delete_conversation	handle_delete_conversation	Delete conversation — DMs: remove self; groups: creator-only, removes all members + files
accept_invitation	handle_accept_invitation	Accept pending group invitation → add to members, notify others
decline_invitation	handle_decline_invitation	Decline pending group invitation
list_invitations	handle_list_invitations	List user's pending invitations (with conv name + inviter username)
list_conversations	handle_list_conversations	List all user's conversations (includes avatar_file)
send_message	handle_send_message	Send encrypted message (ratchet_header + recipients[])
get_messages	handle_get_messages	Get messages (returns per-user ciphertext, JOINs message_recipients). Supports after_ts for incremental sync. ROW_NUMBER dedup when both device-specific and SELF_DEVICE_ID rows exist.
mark_read	handle_mark_read	Mark messages as read
delete_message	handle_delete_message	Soft-delete message (sender only)
rotate_keys	handle_rotate_keys	Rotate RSA login key, disconnect other sessions
pairing_claim	handle_pairing_claim	Authorized device claims pairing code
pairing_send	handle_pairing_send	Authorized device sends encrypted key payload
upload_image_start/chunk/end	Image/file upload	Chunked encrypted upload (256KB chunks). file_type param: "image" (5MB limit) or "file" (50MB limit).
download_image	handle_download_image	Legacy chunked download with offset (one chunk per request, 2 DB queries per chunk)
download_stream	handle_download_stream	Streaming download: single request → server sends all chunks with same request_id + incremental seq. One DB auth check via _validate_download(), no per-chunk round-trip. Response fields: file_id, data (base64), offset, seq, done, total_size.
get_profile	handle_get_profile	Get user profile (respects visibility for other users)
update_profile	handle_update_profile	Update own profile (phone, location, visibility toggles)
update_avatar	handle_update_avatar	Upload user avatar (base64, max 2MB, JPEG/PNG)
get_avatar	handle_get_avatar	Download user's avatar
update_group_avatar	handle_update_group_avatar	Upload group avatar (base64, max 2MB, JPEG/PNG, creator only)
get_group_avatar	handle_get_group_avatar	Download group avatar
get_deleted_since	handle_get_deleted_since	Get message IDs deleted since a given timestamp (for incremental sync)
reencrypt_messages	handle_reencrypt_messages	Batch upsert message history with self-key (max 500/request, for device pairing + received msg self-encryption)
list_devices	handle_list_devices	List all devices for current user
remove_device	handle_remove_device	Remove a device (not current device)
session_reset	handle_session_reset	Notify peer to reset corrupted Double Ratchet session (push session_reset to peer)
react_message	handle_react_message	Add/remove emoji reaction on a message. Push message_reacted to members.
pin_message	handle_pin_message	Pin/unpin a message. Push message_pinned/message_unpinned to members.
get_pinned_messages	handle_get_pinned_messages	Get list of pinned messages for a conversation.

Key Classes & Functions

crypto_utils.py

Password-based key encryption (ECP1 format):

• PBKDF2_ITERATIONS = 600_000 — OWASP 2023 compliant
• _encrypt_private_key(raw_bytes, password) -> bytes — PBKDF2-HMAC-SHA256 + AES-256-GCM. Format: _ECP1_MAGIC(4) + salt(16) + nonce(12) + ciphertext_with_tag
• _decrypt_private_key(data, password) -> bytes — Detects ECP1 magic prefix, derives key, decrypts

RSA (login only): generate_rsa_keypair(), serialize_private_key() (ECP1 with password, PEM without), serialize_public_key(), load_private_key() (auto-detects ECP1 vs legacy PEM), load_public_key(), rsa_sign(), rsa_verify()

AES-256-GCM: aes_encrypt(plaintext, key=None) -> (key, nonce, ct, tag), aes_decrypt(key, nonce, ct, tag) -> plaintext

Ed25519: generate_identity_keypair(), serialize_ed25519_private() (ECP1 with password, 32-byte raw without), serialize_ed25519_private_raw(), serialize_ed25519_public(), load_ed25519_private() (auto-detects ECP1 vs legacy PEM vs raw), load_ed25519_public(), ed25519_sign(), ed25519_verify()

X25519: generate_x25519_keypair(), serialize_x25519_private(), serialize_x25519_public(), load_x25519_private(), load_x25519_public(), x25519_dh()

Key conversion: ed25519_private_to_x25519() (SHA-512 + clamp), ed25519_public_to_x25519() (Montgomery u-coordinate)

HKDF: hkdf_derive(), kdf_rk(root_key, dh_output) -> (new_root_key, chain_key), kdf_ck(chain_key) -> (new_chain_key, message_key)

X3DH: generate_signed_prekey(identity_private) -> {private, public, signature, id}, generate_one_time_prekeys(count=50) -> [{private, public, id}], x3dh_initiate(ik_private_ed, ik_public_remote_ed, spk_remote, spk_signature, opk_remote?) -> (shared_secret, ek_priv, ek_pub), x3dh_respond(ik_private_ed, spk_private, ik_remote_ed, ek_remote, opk_private?) -> shared_secret

DoubleRatchet class:

• init_alice(shared_secret, bob_spk_pub) — initiator, performs first DH ratchet
• init_bob(shared_secret, spk_pair) — responder, waits for first message
• encrypt(plaintext) -> {header: {dh_pub, n, pn}, ciphertext, nonce} — AAD = serialized header
• decrypt(header_dict, ciphertext, nonce) — handles DH ratchet step if new dh_pub, skipped messages. State snapshot/rollback on failure (M9): _snapshot() captures all mutable state before modifications, _restore() rolls back on any exception.
• _snapshot() -> dict / _restore(snap) — Snapshot: dh_pair, dh_remote, root_key, send/recv chain keys, counters, skipped dict. Used internally by decrypt().
• export_state() -> bytes / import_state(data) -> DoubleRatchet — JSON serialization

SenderKeyState class:

• __init__(sender_key=None) — generates random 32B key if None
• encrypt(plaintext) -> {chain_id, n, ciphertext, nonce} — AAD = chain_id + message number
• decrypt(chain_id_hex, n, ciphertext, nonce) — fast-forwards chain if needed. State snapshot/rollback on failure (M9): snapshots chain_key, n, _known_keys before fast-forward, restores on exception.
• export_key() -> bytes — for distribution to group members
• from_key(exported_key) -> SenderKeyState — receiver initializes from exported key
• export_state() / import_state() — full state persistence

Contact Key Verification:

• FINGERPRINT_VERSION = 0 — version byte for fingerprint algorithm
• compute_fingerprint(user_id, identity_key_bytes, iterations=5200) -> bytes — iterated SHA-512, truncated to 32 bytes. Matches Signal's NumericFingerprint.
• format_fingerprint(fp_bytes) -> str — 32 bytes → 6 groups of 5 digits (30 digits), 2 lines
• compute_safety_number(my_uid, my_ik, their_uid, their_ik) -> str — 60 digits (12 groups of 5), deterministic ordering (lower uid first), 3 lines of 4 groups
• encode_verification_qr(user_id, identity_key_bytes) -> bytes — 0x01 + uid_len(1B) + uid(UTF-8) + ik(32B)
• decode_verification_qr(data) -> (user_id, identity_key_bytes) — inverse of encode

Message Padding:

• _PAD_MAGIC = b"\x01" — prefix byte distinguishing padded from legacy unpadded messages
• _PAD_BUCKETS = [64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536] — target sizes
• pad_plaintext(plaintext) -> bytes — Pad to nearest bucket. Format: 0x01 + plaintext + random_padding + pad_length(4B big-endian).
• unpad_plaintext(data) -> bytes — Remove padding. Legacy unpadded messages (starting with {) returned unchanged.

chat_core.py

Local key storage (~/.encrypted_chat/{email}/):

private.pem / public.pem                              — RSA (login, ECP1 format when password-encrypted)
identity_private.bin / identity_public.bin             — Ed25519 (ECP1 format when password-encrypted, 32B raw otherwise)
device_id.txt                                          — This device's UUID
spk_private.bin / spk_id.txt                           — Current signed prekey (AES-256-GCM via local_key)
prev_spk_private.bin / prev_spk_id.txt                 — Previous SPK for grace period (AES-256-GCM via local_key)
opk_private/{opk_id}.bin                               — One-time prekeys (AES-256-GCM via local_key)
login_lockout.json                                     — Brute-force lockout state (failed_attempts, locked_until)
sessions/{user_id}_{device_id}.bin                     — Double Ratchet states (per peer device)
sender_keys/{conv_id}.bin                              — Own sender key states
sender_keys_recv/{conv_id}_{sender_id}_{device_id}.bin — Received sender keys (per sender device)
known_identity_keys.bin                                — TOFU registry: {user_id -> {identity_key hex, first_seen, last_seen}}
verified_contacts.bin                                  — Explicit verification: {user_id -> {identity_key hex, verified_at, method}}

Storage functions: save_keys(), load_keys(), _save_identity_keys(), _load_identity_keys(), _save_spk(local_key=), _load_spk(local_key=), _save_prev_spk(local_key=), _load_prev_spk(local_key=), _save_opk_private(local_key=), _load_opk_private(local_key=), _delete_opk_private(), _save_session(), _load_session(), _save_sender_key_state(), _load_sender_key_state(), _save_recv_sender_key(), _load_recv_sender_key(), _save_known_identity_keys(), _load_known_identity_keys(), _save_verified_contacts(), _load_verified_contacts()

Lockout functions: _check_lockout(email) -> float, _record_failed_attempt(email), _clear_lockout(email). Constants: _LOCKOUT_BASE_SECONDS=2, _LOCKOUT_MAX_SECONDS=300.

ChatClient attributes:

• private_key / public_key — RSA (login)
• identity_private / identity_public — Ed25519
• spk_private / spk_id — Current SPK
• _prev_spk_private / _prev_spk_id — Previous SPK for grace period (M4)
• opk_privates: dict[str, X25519PrivateKey] — OPK private keys by ID
• device_id: str | None — this device's UUID (persisted to disk)
• sessions: dict[str, DoubleRatchet] — "user_id:device_id" -> ratchet (per peer device)
• sender_key_states: dict[str, SenderKeyState] — conv_id -> own sender key
• recv_sender_keys: dict[str, SenderKeyState] — "conv_id:sender_id:device_id" -> their key
• _device_bundle_cache: dict[str, tuple[float, list]] — user_id -> (timestamp, device_bundles) with 5-min TTL
• _pending_self_encrypt: list[dict] — queue of received messages to self-encrypt for multi-device access
• _user_cache: dict[str, dict] — user_id -> {identity_key, username, email, identity_key_status}
• connected: bool — current connection state
• _known_identity_keys: dict — TOFU registry (user_id -> {identity_key hex, first_seen, last_seen})
• _verified_contacts: dict — explicit verification (user_id -> {identity_key hex, verified_at, method})
• _key_change_cb: Callable | None — callback fired on identity key change (GUI wires to warning dialog)

Key methods:

• register() — Generates RSA + Ed25519, sends to server
• confirm_registration() — Confirms code, uploads prekeys (SPK + 50 OPKs)
• login() — Loads keys from disk (including prev_spk for grace period), RSA challenge-response, auto _ensure_prekeys()
• _ensure_prekeys() — Checks OPK count AND SPK age. Replenishes OPKs if < 20, rotates SPK if >= 7 days old (M4). Saves old SPK as grace period before generating new one.
• _get_device_bundles(peer_user_id) — Fetches per-device key bundles with 5-min TTL cache
• _get_or_create_session(peer_user_id, peer_device_id, bundle) — Loads from memory/disk or creates via X3DH, keyed by "user:device"
• _process_x3dh_header(sender_id, x3dh_header, sender_device_id, spk_override?) — Bob side of X3DH. spk_override param allows using previous SPK for grace period (M4).
• send_message(conv_id, text, members, reply_to?) — Routes to _send_dm or _send_group_message
• _send_dm() — Per-device Double Ratchet (encrypts for each of recipient's devices), self-encrypted copy with SELF_DEVICE_ID
• _send_group_message() — Sender Keys, distributes key if new (per-device)
• _distribute_sender_key() — Sends sender key as control message via per-device pairwise ratchet, includes sender_device_id
• _decrypt_dm() — Handles X3DH header for new sessions, returns None for control messages. On X3DH decrypt failure, retries with previous SPK (M4 grace period).
• _decrypt_group() — Uses received sender key chain
• decrypt_notification() — Returns None for control messages (sender key distribution)
• get_messages() — Cache-first with incremental sync (after_ts). Decrypts new messages, self-encrypts received messages for multi-device, syncs deletions via get_deleted_since. Returns merged cache + new messages.
• _build_messages_from_cache() — Builds sorted message list from cache dict
• _queue_self_encrypt() / _flush_self_encrypt() — Queue and upload self-encrypted copies of received messages
• authorize_device() — Exports RSA + Ed25519 only (simplified for multi-device — no session/sender key transfer)
• pairing_wait() — Imports RSA + identity key from paired device (new device generates own SPK + OPKs on login)
• reconnect() — Closes connection, re-establishes TCP + RSA login using in-memory keys
• get_profile(user_id?) — Gets user profile from server
• update_profile(**fields) — Updates own profile (phone, location, visibility)
• update_avatar(image_data) — Uploads avatar
• get_avatar(user_id) — Downloads avatar bytes
• send_file(conv_id, file_path, members, reply_to?) — Encrypt + chunked upload + send message with file payload
• download_file(file_id, file_info) — Chunked download + AES-GCM decrypt
• leave_group(conv_id) — Leave group, clean up local sender keys
• rename_conversation(conv_id, name) — Rename group (creator only)
• delete_conversation(conv_id) — Delete conversation, clean up local sender keys
• accept_invitation(conv_id) — Accept group invitation
• decline_invitation(conv_id) — Decline group invitation
• list_invitations() — Fetch pending invitations
• update_group_avatar(conv_id, image_data) — Upload group avatar
• get_group_avatar(conv_id) — Download group avatar
• search_messages(conv_id, query) — Search decrypted message cache (client-side only)
• reset_session(peer_user_id, peer_device_id?) — Delete local session + notify peer via server
• handle_session_reset_notification(from_user_id, from_device_id?) — Handle incoming session reset
• _load_verification_stores() — Load TOFU + verified contacts from disk (called on login/registration/pairing)
• check_identity_key(user_id, ik_bytes) -> str — TOFU check, returns "new"/"trusted"/"verified"/"changed"/"changed_verified"
• verify_contact(user_id, ik_bytes, method) — Mark contact as explicitly verified
• unverify_contact(user_id) — Remove explicit verification
• accept_key_change(user_id, new_ik_bytes) — Accept changed key, remove old verification
• get_verification_status(user_id) -> str — Returns "verified"/"trusted"/"unverified"
• get_safety_number(peer_user_id) -> str — Formatted 60-digit safety number
• get_my_fingerprint() -> str — Formatted 30-digit own fingerprint
• get_peer_fingerprint(peer_user_id) -> str — Formatted 30-digit peer fingerprint
• get_verification_qr_data() -> bytes — QR code payload for own identity
• verify_qr_code(qr_data) -> (ok, user_id, message) — Decode + verify scanned QR code

gui_client.py

AsyncBridge (QThread): Runs asyncio event loop, schedule(coro) queues coroutines, pyqtSignals emit results back to Qt main thread.

Key signals: login_result, conversations_loaded, messages_loaded, message_sent, new_notification, messages_read_notification, message_deleted_notification, conversation_updated, connection_state_changed, profile_loaded, profile_updated, avatar_loaded, online_status_changed, online_users_loaded, file_sent, file_downloaded, group_left, conversation_deleted, invitations_loaded, invitation_result, invitation_received, group_avatar_loaded, group_avatar_updated, session_reset_notification, key_change_warning

MainWindow: Dark theme (Catppuccin Mocha), conversation list with circular avatars + online green dot overlay + unread count badges + verification checkmark, message bubbles with colored left border, context menu (reply, delete, view image, download file), image thumbnails via QTextDocument resources (thumb://{file_id}), file cards with download links (file://{file_id}), connection indicator dot (green/red/orange), profile button, attach menu (Image/File), Leave Group button in group info, delete conversation button (trash icon in header), group avatar display + change in group info dialog, invitation list (amber border) above conversation list with right-click accept/decline. E2E label clickable → opens VerificationDialog. Key change warning dialog on identity key change.

UserProfileDialog: View (read-only) and edit (own profile) modes. Fields: avatar (circular crop), username, email, phone, location, visibility toggles. Avatar upload/download. Security section (viewing others): verification status + fingerprint. Opened from "My Profile" button or user info button in group info dialog.

VerificationDialog: Frameless dialog for contact verification. Shows: peer name, verification status, safety number (monospace), QR code image, both fingerprints. Buttons: "Mark as Verified" / "Remove Verification" / "Scan QR Code" (via pyzbar). QR generation via qrcode library.

Avatar system in conversation list:

• _avatar_cache: dict[str, QPixmap] — user avatars by user_id
• _group_avatar_cache: dict[str, QPixmap] — group avatars by conv_id
• _avatar_requested: set[str] / _group_avatar_requested: set[str] — dedup download requests
• _make_circular_avatar(pixmap, size=32) — QPainter circular crop
• _make_default_avatar(username, size=32) — colored circle with initial letter (deterministic color from username hash)
• _add_online_dot(avatar) — green dot overlay bottom-right
• _get_conv_avatar(conv) — returns QIcon (DM: user avatar + online dot; group: group avatar or default)
• Periodic refresh every 2 minutes via _refresh_timer / _on_periodic_refresh()

Important Implementation Details

X3DH Header Caching

When _get_or_create_session() creates a new session via X3DH, it attaches the X3DH header as ratchet._x3dh_header. The next _send_dm() reads and deletes it. This ensures the X3DH header is only sent with the first message.

Self-Encryption for DMs

Sender uses derive_self_encryption_key(identity_private) to encrypt their own copy of sent messages with a static AES key. Uses SELF_DEVICE_ID sentinel so all own devices can read it. This allows reading own sent messages when fetching history from any device. Received messages are also self-encrypted after decryption (via _pending_self_encrypt queue + _flush_self_encrypt()), creating SELF_DEVICE_ID copies so other devices of the same user can read them. batch_reencrypt_messages() uses INSERT ON DUPLICATE KEY UPDATE (upsert) to handle both cases.

Sender Key Distribution as Control Messages

Sender keys are distributed via normal send_message protocol (per-device pairwise ratchet). The payload contains _sender_key: {conv_id, key, sender_device_id} field. On decryption, _decrypt_dm() detects this field, stores the sender key keyed by "conv_id:sender_id:sender_device_id", and returns None (not shown to user).

Group Messages: Dummy Ratchet Header

Group messages use {"dh_pub": "00"*32, "n": 0, "pn": 0} as ratchet_header because the server requires it, but groups use sender keys instead of Double Ratchet.

Multi-Device Architecture

Each device has independent Double Ratchet sessions. Sessions are keyed by "peer_user_id:peer_device_id". When sending a DM, the client fetches per-device key bundles via _get_device_bundles() and encrypts separately for each device. The server registers devices at login (handle_login_finish), assigns device IDs, and routes notifications with device_entries arrays (one entry per recipient device). Device IDs are persisted to ~/.encrypted_chat/{email}/device_id.txt. Old session files ({user_id}.bin) are automatically migrated to {user_id}_{device_id}.bin on first load.

Server Session Model

connected_clients: dict[str, list[ProtocolWriter]] — one user can have multiple connections (multi-device). writer_device_map: dict[int, str] maps id(writer) to device_id. Notifications are pushed to all connections except the sender's current one.

Device Registration

On login_finish, server checks for device_id in the request. If present and valid (belongs to user), reuses it. Otherwise creates a new device. Device ID returned in response and stored on client disk. list_devices and remove_device handlers for device management.

Simplified Pairing (Multi-Device)

authorize_device() only exports RSA + identity key (no sessions/sender keys). New device generates its own SPK + OPKs on first login, creates independent sessions via X3DH. Old messages readable via self-encryption (shared identity key). reencrypt_history() still runs to ensure all messages have self-encrypted copies.

Real-time Conversation Notifications

handle_create_conversation, handle_add_member, handle_remove_member, handle_leave_group, handle_delete_conversation, handle_accept_invitation push notifications to affected members via connected_clients. Types: conversation_created, member_added, member_removed, group_invitation. GUI handles these via conversation_updated signal -> refreshes conversation list.

Connection State + Auto-Reconnect + TCP Keepalive

ChatClient.connected flag tracks TCP connection state. _background_listener sets connected = False when server closes connection and fails all pending futures with ConnectionError (prevents send_and_recv from hanging forever). send_and_recv has a 30s timeout via asyncio.wait_for and catches ConnectionError/TimeoutError. reconnect() re-establishes TCP + RSA challenge-response using in-memory keys (no password needed, includes device_id). GUI _notification_loop detects listener death -> triggers _auto_reconnect with exponential backoff (1s->2s->4s->...->30s). Connection indicator dot: green (connected), red (disconnected), orange (reconnecting).

TCP Keepalive (OS-level): Both server and client enable SO_KEEPALIVE on the TCP socket with TCP_KEEPIDLE=25s, TCP_KEEPINTVL=10s, TCP_KEEPCNT=3. After 25s of idle the OS sends probe packets every 10s; if 3 probes go unanswered (25+3×10 = 55s) the OS marks the connection dead → read_message() returns None → auto-reconnect triggers. This prevents silent connection death through NAT/firewalls.

Dead writer cleanup: _notify_users() and _notify_users_individual() in server.py check w.is_closing() before sending and catch exceptions on send. Failed writers are removed from connected_clients via _remove_dead_writer() instead of being silently ignored. This ensures stale connections don't accumulate and block notification delivery.

iOS implementation: NWProtocolTCP.Options — set keepaliveIdle = 25, keepaliveInterval = 10, keepaliveCount = 3 and pass to NWParameters(tls:tcp:). No application-level ping/pong — connection is maintained purely via OS-level TCP keepalive. On NWConnection.stateUpdateHandler receiving .failed or .waiting, trigger reconnect with exponential backoff.

Server Per-Message Error Handling

Server dispatch loop wraps each handler call in individual try/except. Handler crashes return "Internal server error" response instead of killing the entire connection. Errors logged with exc_info=True for full tracebacks. GUI _do_send_message/_do_find_or_create_and_send catch exceptions and emit error signal (prevents silent hang when send fails).

Online/Offline Status

• db.get_user_contacts(user_id) returns all user IDs sharing at least one conversation
• On login (handle_login_finish): server sends online_users list to new user + user_online to all contacts (only if user was fully offline before)
• On disconnect (handle_client finally block): if last connection drops, server sends user_offline to all contacts
• _background_listener routes user_online, user_offline, online_users to notification queue
• GUI: _online_users: set[str] tracks online users, green dot overlay on circular avatar in DM conversation list + green circle emoji in group info member list

Leave Group

• handle_leave_group in server.py: validates membership, blocks DM leave (len<=2 and no name), transfers creator to first remaining member if creator leaves, removes member, notifies remaining via member_removed
• ChatClient.leave_group(): sends request, cleans up local sender key states on success
• GUI: red "Leave Group" button in group info dialog, confirmation dialog, resets view on success

Delete Conversation

• DMs: Any member can delete. Only removes the deleting user from conversation_members. If both users delete, 0 members remain → conversation + files cleaned up.
• Groups: Only the creator (admin) can delete. Removes ALL members, cleans up .enc files from disk, deletes conversation via CASCADE.
• Server notifies remaining members via member_removed push.
• GUI: trash icon button in conversation header. Visible for DMs always, for groups only when user is creator.
• chat_core.py: cleans up local sender key states after successful delete.

Group Invitations

• Flow: create_conversation (group) or add_member → creates invitation → pushes group_invitation notification → invitee sees in invitation list → Accept (adds to members, notifies) / Decline (deletes invitation)
• DMs are unaffected: create_conversation for DMs still auto-adds both members
• DB: group_invitations table with UNIQUE(conversation_id, user_id) to prevent duplicates
• Server: handle_accept_invitation verifies invitation exists, adds member, deletes invitation, notifies existing members via member_added. handle_decline_invitation just deletes.
• GUI: inv_list QListWidget (max 120px, amber border) above conv_list. Right-click → Accept/Decline. invitation_received signal triggers refresh + notification banner.
• Routing fix (IMPORTANT): group_invitation must be in the notification types list in chat_core.py:_background_listener (~line 304). Without it, invitations get routed to _response_queue and the GUI never sees them.

Group Avatars

• Stored as files in UPLOAD_DIR/avatars/group_{conv_id}.{ext} (PNG or JPEG detected from magic bytes)
• conversations.avatar_file column stores the filename
• list_conversations response includes avatar_file so GUI knows which groups have avatars
• GUI: _group_avatar_cache dict, _get_conv_avatar() returns group avatar icon or default letter circle
• Group Info dialog shows 64px circular avatar + "Change Avatar" button (creator only)
• Periodic refresh every 2 minutes re-downloads all known group avatars

File Sharing

• Reuses image upload/download infrastructure (upload_image_start/chunk/end, download_stream/download_image)
• Chunk size: IMAGE_CHUNK_SIZE = 262144 (256 KiB). MAX_MESSAGE_BYTES = 1048576 (1 MiB) — StreamReader limit raised to accommodate base64-encoded 256KB chunks.
• upload_image_start accepts optional file_type param: "image" (MAX_IMAGE_BYTES=5MB) or "file" (MAX_FILE_BYTES=50MB)
• ChatClient.send_file(): reads raw file, AES-256-GCM encrypts, pipelined upload (256KB chunks), sends message with file field in payload ({file_id, aes_key, iv, filename, size, mime_type})
• Download: _stream_download() (preferred) sends single download_stream request, server streams all chunks back in sequence with same request_id. Fallback to _legacy_download() (per-chunk download_image) for older servers.
• Media cache: Decrypted files cached in ~/.encrypted_chat/{email}/media_cache/{file_id}.bin (chmod 0o600). Cache-first: checked before any server call. Populated by both sender (after upload) and receiver (after download).
• GUI: attach button is dropdown menu (Image / File), file messages render as styled cards with paperclip icon (transparent background, border) and clickable download link (file://{file_id}), context menu "Download file" option. image_download_failed signal clears pending state on failure.
• Files stored as .enc in UPLOAD_DIR, same as images

Unread Count Badges

• _unread_counts: dict[str, int] replaces old _unread_convs: set
• _on_notification() increments count per conversation
• _on_conv_selected() clears count for selected conversation
• Display: (3) Username with bold font, instead of old ● Username

User Profiles

user_profiles table separated from users (clean separation, users = auth only). Default profile created on registration (db.create_default_profile). Visibility rules applied server-side in db.get_user_profile(viewer_id). Avatars stored as files in UPLOAD_DIR/avatars/{user_id}.{ext} (not in DB). Format detection from magic bytes (PNG header vs default JPEG). UserProfileDialog shows circular cropped avatar (QPainter).

Prekey Replenishment + SPK Rotation

After login, _ensure_prekeys() is called as a background task. Checks two things:

1. OPK count — if < 20, generates and uploads a new batch of 50
2. SPK age — server returns spk_created_at in get_prekey_count response. If SPK is >= 7 days old (SPK_ROTATION_DAYS), triggers rotation: saves current SPK as prev_spk_private.bin/prev_spk_id.txt (grace period), generates new SPK, uploads to server.

Password-Based Key Encryption (ECP1 Format) — M3

Private keys (RSA, Ed25519) are encrypted with a custom envelope instead of BestAvailableEncryption:

• Key derivation: PBKDF2-HMAC-SHA256 with 600,000 iterations (OWASP 2023 compliant)
• Encryption: AES-256-GCM with the derived key, magic bytes as AAD
• Format: _ECP1_MAGIC("ECP1", 4B) + salt(16B) + nonce(12B) + ciphertext_with_tag(N+16B)
• Backward compatibility: load_private_key() and load_ed25519_private() detect ECP1 magic prefix. If absent, fall back to legacy PEM parsing (old BestAvailableEncryption format). On next save, files are re-encrypted in ECP1 format.
• Functions: _encrypt_private_key(), _decrypt_private_key() in crypto_utils.py
• Applied to: serialize_private_key() (RSA), serialize_ed25519_private() (Ed25519)

SPK Rotation (7-Day Cycle) — M4

Signed Pre-Keys rotate periodically to limit exposure from a compromised SPK:

• Rotation interval: SPK_ROTATION_DAYS = 7 (constant in chat_core.py)
• Trigger: _ensure_prekeys() checks spk_created_at from get_prekey_count response. If age >= 7 days, calls _generate_and_upload_prekeys().
• Grace period: Before generating a new SPK, the current one is saved as prev_spk_private.bin / prev_spk_id.txt. Loaded on login into _prev_spk_private / _prev_spk_id.
• Fallback on decrypt: When _decrypt_dm() processes an X3DH header and decryption fails with the current SPK, it retries with the previous SPK via _process_x3dh_header(..., spk_override=self._prev_spk_private). This handles in-flight X3DH initiated before rotation.
• Server side: get_signed_prekey() in db.py returns created_at column. handle_get_prekey_count includes spk_created_at (ISO format) in response.
• Server SPK replacement: store_signed_prekey() deletes old SPK and inserts new one — only one active SPK per device on server.

Ratchet State Rollback on Decrypt Failure — M9

Both DoubleRatchet.decrypt() and SenderKeyState.decrypt() modify internal state (chain keys, counters, DH keys) before attempting AES-GCM decryption. If decryption fails (corrupted data, wrong key, AAD mismatch), the state would be permanently corrupted.

DoubleRatchet fix:

• _snapshot() captures all mutable fields: dh_pair, dh_remote, root_key, send_chain_key, recv_chain_key, send_n, recv_n, prev_send_n, skipped dict (shallow copy)
• decrypt() takes snapshot before any state modification, wraps the entire DH ratchet + chain advance + AES-GCM decrypt in try/except, calls _restore() on failure
• Special case: skipped message decryption (no state modification needed) — if AES-GCM fails, the popped key is restored to skipped dict

SenderKeyState fix:

• Before fast-forwarding the chain, snapshots chain_key, n, _known_keys (shallow copy)
• On any exception during fast-forward or AES-GCM decrypt, all three are restored

Message Reactions

• ALLOWED_REACTIONS = {"thumbsup", "heart", "laugh", "surprised", "sad", "thumbsdown"} in db.py
• message_reactions table with UNIQUE(message_id, user_id, reaction) — one reaction type per user per message
• handle_react_message: validates UUID, reaction, membership. Adds/removes reaction. Pushes message_reacted to all members.
• get_messages response includes reactions: [{user_id, reaction, created_at}] per message (batch query via db.get_reactions())
• GUI: React submenu in context menu with toggle (add if not present, remove if already reacted). Badges below message text showing emoji + count, highlighted border if own reaction. Real-time update via _on_reaction_notification.
• Forwarding uses forwarded_from metadata in plaintext payload — no new server protocol needed, just client convention.

Pinned Messages

• messages.pinned_at (DATETIME) and messages.pinned_by (CHAR(36)) columns
• handle_pin_message: validates UUID, membership, pins/unpins. Pushes message_pinned/message_unpinned.
• handle_get_pinned_messages: returns pinned message metadata for a conversation
• get_messages response includes pinned_at and pinned_by per message
• GUI: Pin/Unpin in context menu, pin emoji in message header, "Pinned" button in chat header opens dialog with scrollable list (double-click scrolls to message in chat)

@Mentions

• Client-side only — no server-side handling or special notifications
• GUI MentionCompleter: popup QListWidget shown when @ detected at cursor, filters conversation members by prefix, inserts @username on selection
• Rendering: re.sub(r'@(\w+)', ...) highlights mentions in blue bold (#89b4fa)
• Triggered from _on_input_changed() -> _check_mention_trigger()

Contact Key Verification (Safety Numbers / Fingerprints / QR Codes)

• Zero server changes — entirely client-side. Server already stores identity keys in users.identity_key.
• TOFU (Trust On First Use): known_identity_keys.bin stores first-seen identity key per user. Encrypted with _local_key (AES-256-GCM). Loaded on login/registration/pairing.
• Explicit verification: verified_contacts.bin stores verified contacts with method + timestamp. Encrypted with _local_key.
• Fingerprint algorithm: Iterated SHA-512 (5200 iterations), seed = version(2B) + identity_key(32B) + user_id(UTF-8). Each iteration: SHA-512(prev + identity_key). Output: first 32 bytes → 6 groups of 5 zero-padded digits.
• Safety number: Both users' fingerprints concatenated (lower user_id first → deterministic ordering). 64 bytes → 12 groups of 5 digits, displayed as 3 lines of 4 groups. Both sides see the same number.
• QR code format: 0x01 + uid_len(1B) + uid(UTF-8) + identity_key(32B). Generated via qrcode library, decoded via pyzbar (optional).
• Identity key status: check_identity_key() returns "new" | "trusted" | "verified" | "changed" | "changed_verified". Called from _get_user_info(), result stored in _user_cache as identity_key_status.
• Key change callback: _key_change_cb(user_id, username, old_key_hex, was_verified) fires on key change. GUI wires to key_change_warning signal → warning dialog.
• GUI indicators: Green checkmark badge in conversation list for verified DMs (ROLE_VERIFIED data role, painted by ConversationDelegate). E2E label in chat header shows "Verified" (green) or "Encrypted" (muted) — clickable → opens VerificationDialog. Green checkmark next to verified members in group info. Security section in UserProfileDialog showing fingerprint + status.
• VerificationDialog: Frameless dialog showing safety number (monospace), QR code, both fingerprints, verification status. Buttons: "Mark as Verified" / "Remove Verification" / "Scan QR Code".
• CLI: Option 20 (Verify contact) — show safety number + mark verified. Option 21 (Show my fingerprint).
• Tamper resistance: _load_known_identity_keys() a _load_verified_contacts() nemají plaintext migration fallback (na rozdíl od sessions/sender keys). Soubory nikdy neexistovaly v nešifrované podobě — feature přidána po implementaci lokálního šifrování. Pokud útočník s přístupem k disku nahradí šifrovaný soubor plaintextovým JSONem, _decrypt_local() selže a load vrátí {} (prázdný stav). Útočník nemůže podvrhnout falešný verified status ani potlačit key-change warning.
• iOS implementation spec (pro implementaci v ios_client/):

Položka	Specifikace
Fingerprint algoritmus	SHA-512 iterated 5200×. Seed = version(2B big-endian, hodnota 0) + identity_key(32B) + user_id(UTF-8). Každá iterace: SHA-512(prev_result + identity_key). Výstup: prvních 32 bytes.
Fingerprint display	6 skupin × 5 číslic: UInt64(bytes[i*5..<i*5+5], bigEndian) % 100000, zero-padded. Formát: "XXXXX XXXXX XXXXX\nXXXXX XXXXX XXXXX".
Safety number	Fingerprint obou stran. Nižší user_id (String comparison) → jeho fingerprint první. Concatenate 32B + 32B = 64B. Display: 12 skupin × 5 číslic, "XXXXX XXXXX XXXXX XXXXX\nXXXXX XXXXX XXXXX XXXXX\nXXXXX XXXXX XXXXX XXXXX".
QR binary payload	0x01 + uid_len(1B) + uid(UTF-8) + identity_key(32B). Celkem ~70 bytes.
QR encoding	Binary payload → base64 encode → vložit jako string do QR. Důvod: QR čtečky zkomolí raw binary (UTF-8 re-encoding).
QR decoding	Přečtený string z QR → base64 decode → decode_verification_qr() parsuje binary payload.
QR generování	CoreImage.CIFilter(name: "CIQRCodeGenerator") s base64 stringem.
QR skenování	AVCaptureMetadataOutput s metadataObjectTypes: [.qr]. Výsledek: string → base64 decode → verify.
TOFU storage	Keychain nebo šifrovaný soubor. JSON schema: {"version": 1, "keys": {"<user_id>": {"identity_key": "<hex>", "first_seen": "ISO8601", "last_seen": "ISO8601"}}}
Verified storage	Keychain nebo šifrovaný soubor. JSON schema: {"version": 1, "contacts": {"<user_id>": {"identity_key": "<hex>", "verified_at": "ISO8601", "method": "safety_number|qr_code|manual"}}}
Šifrování storage	AES-256-GCM klíčem z HKDF(identity_key, salt="local_storage_key", info="encrypted_chat_local"). Žádný plaintext fallback — pokud decrypt selže, vrátit prázdný dict.
Identity key status	checkIdentityKey(userId, ikBytes) → "new" | "trusted" | "verified" | "changed" | "changed_verified". Volat při každém getUserInfo().
Self exclusion	Vlastní user_id nikdy nezobrazovat jako unverified — přeskočit v conv listu i group info.
UI: Conversation list	Zelená fajfka (SF Symbol checkmark.seal.fill) vedle jména pro verified DM kontakty.
UI: Chat header	"Verified" (zelená) nebo "Encrypted" (šedá) pod jménem. Tap → otevře VerificationView.
UI: VerificationView	Safety number (monospace), QR kód (CIQRCodeGenerator), oba fingerprints, status. Tlačítka: "Mark as Verified" / "Remove Verification" / "Scan QR Code".
UI: Key change alert	.alert() s textem "Identity key for [name] has changed!" + "Accept" / "View Details".
UI: Group info	Zelená fajfka vedle verified členů (ne u sebe).
Cross-platform test	Python klient a iOS klient musí pro stejný pár (user_id_A, ik_A, user_id_B, ik_B) vypočítat identický safety number. QR vygenerovaný na jedné platformě musí být čitelný na druhé.

iOS: TCP Keepalive + Optimistic Send + Cache-First spec:

Položka	Specifikace
TCP Keepalive	NWProtocolTCP.Options() → keepaliveIdle = 25, keepaliveInterval = 10, keepaliveCount = 3 → předat do NWParameters(tls:tcp:). Žádný app-level ping/pong. Při .failed/.waiting → reconnect s exponenciálním backoffem (1→2→4→...→30s).
Optimistic send	Po tapnutí Send: (1) vytvořit Message(isOptimistic: true, id: tempUUID, text: text, sender: me), (2) přidat do messages array + zobrazit v UI + scroll to bottom, (3) async sendMessage() → při úspěchu nahradit optimistickou zprávu potvrzenou (match přes text+sender, nové message_id+created_at ze serveru), při chybě odstranit z UI + alert.
Cache-first loading	Při otevření konverzace: (1) okamžitě getCachedMessages(convId) → zobrazit z lokálního úložiště, (2) async getMessages(convId, afterTs:) → doplnit nové zprávy. Uživatel vidí zprávy okamžitě, server sync na pozadí.
Fetch dedup	inflightFetches: Set<String> — pokud pro convId už běží fetch, nový nespouštět. Zabraňuje duplicitním requestům při rychlém přepínání.
Dead writer	Server-side: _remove_dead_writer() automaticky odstraní mrtvé writery. iOS klient nemusí nic speciálního.
[PUSH] log	Server loguje [PUSH] msg=... targets=[uid(Nw)] — N = počet writerů per příjemce. Pro debug pokud zprávy nedorazí.

iOS: Media Transfer spec (v0.8.5):

Položka	Specifikace
Protokol verze	VERSION = "0.8.5", MIN_CLIENT_VERSION = "0.8.5". Server odmítá klienty starší než 0.8.5 — client_version v login_finish requestu musí být >= 0.8.5.
Chunk size	IMAGE_CHUNK_SIZE = 262144 (256 KiB). Platí pro upload i download. Starý 32KB chunk size je nekompatibilní — server čte/píše v 256KB blocích.
Buffer limit	MAX_MESSAGE_BYTES = 1_048_576 (1 MiB). NWConnection musí zvládnout přijmout JSON zprávu do 1 MiB (base64-encoded 256KB chunk ≈ 341KB + JSON overhead ≈ 343KB, bezpečně pod limitem). Pokud NWConnection parsuje po newline, nastavit buffer >= 1 MiB.
Upload flow	Beze změny — pipelined upload_image_start → N × upload_image_chunk (256KB, base64) → upload_image_end. Chunk size větší = méně chunků (5MB obrázek = ~20 chunků místo 160).
Download	iOS používá výhradně legacy download_image per-chunk (jeden request na chunk, offset inkrementuje po len(chunk)). download_stream existuje na serveru, ale iOS ho nepoužívá — actor-based architektura způsobovala 60s timeouty.
Sender media cache	Po úspěšném upload_image_end cachovat dešifrovaný obrázek/soubor lokálně: {cacheDir}/media_cache/{file_id}.bin. Sender pak při kliknutí na vlastní obrázek nemusí stahovat ze serveru — okamžité zobrazení.
Receiver media cache	Po úspěšném download + decrypt cachovat výsledek na disk: {cacheDir}/media_cache/{file_id}.bin. Další zobrazení = okamžité z cache, žádný server call.
Cache kontrola	Před zahájením downloadu vždy zkontrolovat FileManager.default.fileExists(atPath: cachePath). Pokud soubor existuje, vrátit Data(contentsOf:) bez server volání.
Download failure handling	Pokud download selže (timeout, error, disconnection), vyčistit pending stav (UI nesmí zůstat zablokované). Další kliknutí na obrázek musí spustit nový download.
Timeout	Upload chunk future: 30s per chunk. Download (legacy per-chunk): 30s per chunk.
Šifrování souborů	Beze změny: AES-256-GCM. Upload: aes_encrypt(raw_data) → (key, iv, ct, tag), upload ct + tag. Download: stáhnout encrypted blob, ct = blob[:-16], tag = blob[-16:], aes_decrypt(key, iv, ct, tag). Klíč a IV v message payloadu (image.aes_key, image.iv, base64).

iOS: Send Queue & Background Upload (v0.8.5+):

Položka	Specifikace
Architektura	Priority-based send queue uvnitř ChatClient actoru. Text zprávy (priority 0) se prokládají mezi upload chunky (priority 1). UI input je vždy aktivní — isSending se nenastavuje na true.
Optimistický thumbnail	Před enqueuováním uploadu se vytvoří lokální JPEG thumbnail (max 6KB, progresivní snižování kvality 0.4→0.3→0.2→0.15, fallback 80×80px). Thumbnail se uloží na Message.optimisticThumbnail a zobrazí se okamžitě s upload spinnerem.
Text interleaving	Po každém chunk response se zkontroluje fronta — pokud čeká textová zpráva, odešle se před dalším chunkem.
Upload failure	Při selhání uploadu se pokračuje dalšími položkami ve frontě. Uživatel dostane info o chybě, ale následné zprávy se odešlou normálně.
Android TODO	Send queue je implementován pouze v iOS. Android potřebuje port — viz ARCHITECTURE.md v Android projektu.

Rate Limits

• Per-IP+email window (60s): register 3/min, login 10/min, send_message 20/min
• Per-connection: 20 req/s — upload_image_chunk is exempt (a single 5MB image needs ~20 chunks in rapid succession; the upload subsystem has its own guards: per-user upload cap, per-user rate limit on upload_image_start, and file-size validation)
• Per-IP: max 10 connections, global max 200
• Pairing: TTL 120s, max 90 poll attempts, pairing_start 10/min, pairing_poll 120/min, client polls every 2s

GUI Font Handling (IMPORTANT)

All widget stylesheet font-size declarations use pt (not px). Using px in Qt stylesheets sets pixelSize and leaves pointSize=-1, which causes QFont::setPointSize: Point size <= 0 warnings on Windows. Conversion: pt ~= px * 0.75 at 96 DPI. HTML styles inside QTextBrowser (_render_single_message_html) still use px — that's fine, QTextBrowser uses its own HTML renderer. Bold fonts for list items use _bold_font() helper + item.setData(FontRole) to avoid the same issue.

Phantom Users (Anti User-Enumeration)

• When a user creates a conversation with an unregistered email, the server creates a "phantom" user with rsa_public_key = 'PHANTOM' marker
• Phantom users have real crypto keys (Ed25519 IK, X25519 SPK + 5 OPKs) so X3DH works on the client side
• handle_find_conversation and handle_create_conversation create phantoms instead of returning "User not found"
• handle_send_message skips phantom recipients when storing message_recipients — only sender's self-encrypted copy is saved
• phantom_user_ids: set[str] in-memory cache loaded at startup from DB, updated on create/delete
• On registration (handle_register_confirm): if email belongs to a phantom, the phantom is upgraded in-place via db.upgrade_phantom_user() — preserves user_id and all FK references (invitations, conversation_members). Phantom's server-generated prekeys are deleted (real user uploads own).
• handle_create_conversation (groups) and handle_add_member create invitations for phantom users too. Push notifications only sent to non-phantom users. When phantom registers and logs in, they see pending invitations.
• Messages sent to phantom users are NOT stored and NOT recoverable after registration — this is by design (prevents user enumeration, sender sees own messages via self-encryption)
• DB functions: db.create_phantom_user(email), db.is_phantom_user(user_id), db.delete_phantom_user(user_id), db.upgrade_phantom_user(phantom_id, username, rsa_public_key_pem, identity_key), db.get_all_phantom_user_ids()

Logout/Login Fix

• _is_logout flag in MainWindow prevents closeEvent() from calling bridge.stop() which killed the asyncio loop
• On logout: set _is_logout = True, call bridge.logout(), then close()
• closeEvent() only calls bridge.stop() if not self._is_logout
• This allows main() to re-create the login/main windows after logout

Server Graceful Shutdown

• SIGINT handler force-closes all writers in connected_clients before the asyncio server context manager exits
• Without this, async with server: waited forever for handle_client loops to finish

Version Negotiation

• VERSION = "0.8.4" constant in protocol.py (shared between client and server)
• MIN_CLIENT_VERSION = "0.8.3" — server rejects clients older than this
• Client sends client_version in login_finish request (both login() and reconnect())
• Server logs client_version, returns server_version in login_finish response
• Server startup log includes version: "Encrypted chat server v0.8.4 listening on ..."
• iOS client (0.8.3) stays compatible — new notification types (message_reacted, message_pinned, message_unpinned) and payload fields (reactions, pinned_at, forwarded_from) are ignored by older clients

Privacy Overlay (Lock Screen)

Anti-forensic privacy feature for PyQt GUI client:

• Immediate overlay: On QEvent.Type.ActivationChange (window loses focus), dark overlay (rgba(30,30,46,245)) with lock icon covers entire window. Protects against Alt+Tab thumbnails, screen sharing, shoulder surfing.
• Timed lock: After _LOCK_TIMEOUT_MS (30s) unfocused, overlay transitions to locked state — requires password to dismiss.
• Password verification: _on_unlock_attempt() reads identity_private.bin from disk and calls _decrypt_private_key(data, password) (ECP1 format: PBKDF2-600k + AES-256-GCM). Successful decryption = correct password.
• Lock capability detection: _lock_capable flag checks if identity key file starts with b"ECP1". If key is not password-encrypted (legacy/no-password), lock timer never fires (overlay still works as visual privacy screen).
• Toggle: Ctrl+Shift+P enables/disables the feature (default: enabled).
• Notification handling during lock: _show_tray_notification() checks self._privacy_locked — tray toasts continue while locked. _on_notification() increments unread counts and skips mark_read while locked.
• Components: _privacy_overlay (QWidget), _lock_input (QLineEdit password), _lock_error (QLabel), _lock_timer (QTimer single-shot), _lock_hint (QLabel status text).

Secure Deletion (Anti-Forensic Wipe)

_secure_delete(path) helper in both chat_core.py and server.py:

• Opens file with r+b, overwrites entire content with os.urandom(size), calls f.flush() + os.fsync(f.fileno()), then p.unlink().
• Fallback: if overwrite fails (permissions, etc.), falls back to standard p.unlink(missing_ok=True).
• Applied to (chat_core.py): _delete_opk_private(), _delete_session_file(), session migration cleanup, sender key migration cleanup, message cache migration (plaintext JSON → encrypted).
• Applied to (server.py): Conversation delete (all .enc+.tmp), message delete (.enc), oversized upload chunk cleanup (.tmp), incomplete/invalid upload end (.tmp), stale upload periodic cleanup (.enc+.tmp).

Metadata Privacy

Four measures to minimize metadata leakage:

• Message Padding: pad_plaintext()/unpad_plaintext() in crypto_utils.py. Plaintext padded to nearest bucket size (64B..64KB) before encryption. Format: 0x01 + plaintext + random + length(4B). Legacy unpadded messages (prefix {) auto-detected by unpad_plaintext(). Applied on all 6 send paths + 2 decrypt paths in chat_core.py.
• Log Sanitization: _who(session) returns u=XXXXXXXX d=YYYYYYYY (truncated user_id + device_id). Group names, recipient counts, emails, and usernames removed from all server log lines (register, login, DM create, invite, rename, send_message).
• Metadata Retention: db.cleanup_old_reads(days) and db.cleanup_old_reactions(days) delete old interaction data in batches. Default METADATA_RETENTION_DAYS=90. Runs every ~1 hour (every 30th cycle of _periodic_cleanup). cleanup_old_reads joins on messages.created_at to only delete reads for old messages. get_unread_counts(max_age_days) excludes messages older than retention window — prevents phantom unreads after read cleanup. Indexes: idx_reads_read_at on message_reads.read_at, idx_reactions_created_at on message_reactions.created_at.
• Sender Chain Minimization: For new group messages, sender_chain_id/sender_chain_n stored in per-recipient message_recipients.ratchet_header instead of messages table. Removes persistent sender correlation from message-level DB rows. Server verifies group-only context (dummy dh_pub all-zeros) before extracting chain data from per-recipient header — prevents DM injection. Self-copy entries (sender's user_id == session["user_id"]) are skipped during chain_meta injection. _validate_header now accepts {"self": true} for per-recipient ratchet_header (fixes self-copy storage in DB). handle_get_messages extracts from both locations (backward compat). Push notifications still include chain data for live decrypt.
• Architectural limitation (known): Server still stores messages.sender_id and message_recipients.user_id — the communication graph (who talks to whom, when) remains visible to the server. Full metadata hiding (e.g. Signal's Sealed Sender, onion routing) is a fundamentally different architecture requiring sender anonymity at the protocol level. Current metadata privacy measures reduce unnecessary metadata exposure (message length, log PII, interaction history retention, group chain correlation) but do not hide the communication graph itself.

Conventions

• Server handlers: handle_<type>(msg, session, writer) — registered in dispatch table in handle_client()
• DB functions: one get_connection() per call, cursor(dictionary=True), returns dicts
• Binary data: always base64 in protocol (encode_binary/decode_binary)
• GUI signals: bridge emits pyqtSignal, MainWindow connects in _connect_signals()
• Error responses: {"status": "error", "data": {"message": "..."}}
• Notification decrypt returning None = control message, skip silently
• GUI stylesheet font sizes: always pt, never px (see Font Handling section above)
• File sharing reuses image upload infrastructure with file_type parameter
• Avatar files stored in UPLOAD_DIR/avatars/ — user: {user_id}.{ext}, group: group_{conv_id}.{ext}

Aktuální stav práce

✅ Dokončeno (tato session)

• iOS client (Swift/SwiftUI) — Full native iOS port in ios_client/ (47 files, ~6200 lines). Wire-compatible with Python server. Crypto layer: CryptoKit (AES-GCM, HKDF, Ed25519, X25519), pure Swift GF(2^255-19) for Ed→X conversion, Security.framework RSA-4096, ECP1 key encryption (PBKDF2 600k + AES-GCM). Protocol: Network.framework TCP+TLS, newline-delimited JSON. Core: ChatClient actor (1644 lines) with X3DH, Double Ratchet, Sender Keys, per-device sessions, SPK rotation. UI: SwiftUI views (login/register, conversation list, chat with message bubbles, group info, profile, search). Server-side RSA PSS compatibility fix: PSS.MAX_LENGTH → PSS.AUTO in rsa_verify() to accept both Python (max salt) and iOS (hash-length salt) signatures.

• Logout/login bug fix — _is_logout flag prevents bridge.stop() on logout

• Hover text readability — color: #cdd6f4; added to QListWidget::item:hover

• File card background — background:transparent; border:1px solid #45475a

• Delete conversations — full stack (db, server, chat_core, gui), DMs + groups (creator-only), file cleanup from disk

• Group invitation system — full stack (schema, db, server, chat_core, gui), create/accept/decline, real-time notification, invitation list UI

• Circular avatars in conversation list — QPainter circular crop, default letter avatars, online green dot overlay

• Group avatar support — upload/download, display in group info dialog, "Change Avatar" button (creator only)

• Server graceful shutdown — force-close connected clients on SIGINT

• Profile dialog avatar circular crop — QPainter in UserProfileDialog._on_avatar_loaded

• Periodic refresh timer — 2-minute QTimer re-downloads avatars + invitations

• Group invitation notification fix — group_invitation added to _background_listener notification types

• Delete button in conversation header — trash icon for DMs always, groups creator-only

• File cleanup on conversation delete — db.get_conversation_file_ids() + unlink .enc files

• Removed right-click "Delete conversation" from conversation list context menu

• README.md updated

• H4 Race conditions fix — 4 asyncio.Lock guards (_clients_lock, _conn_lock, _pairing_lock, _uploads_lock) pro všechny sdílené mutable struktury v server.py. _notify_users() + _notify_users_individual() helpery. Rate limit memory cleanup v periodic task. Všechny I/O operace mimo kritické sekce.

• Unread counts pro offline uživatele — db.get_unread_counts() dotaz přes message_reads + message_recipients, server vrací unread_count v list_conversations, GUI populuje _unread_counts ze serverových dat (max z server vs local). Opravuje bug kdy offline uživatel po přihlášení neviděl nepřečtené zprávy.

• C6 Path traversal fix — _UUID_RE regex + _valid_file_id(), _safe_upload_path(), _safe_avatar_path() helpery v server.py. UUID validace v handle_upload_image_start, handle_download_image. is_relative_to() guard ve všech path konstrukcích: upload start/end, download, delete_message file cleanup, delete_conversation file cleanup, _cleanup_uploads, get/update avatar, get/update group avatar. Celkem 10 guardovaných míst.

• C3+H1+M13 Lokální šifrování + permissions — derive_local_storage_key() v crypto_utils.py (HKDF z identity key, odlišný salt/info od self-encryption key). _encrypt_local()/_decrypt_local() helpery v chat_core.py (AES-256-GCM, formát: nonce(12)+tag(16)+ct). _save_session/_load_session, _save_sender_key_state/_load_sender_key_state, _save_recv_sender_key/_load_recv_sender_key — volitelný local_key parametr, při nastavení šifruje/dešifruje, chmod 0o600 na soubory. ChatClient._local_key derivováno při login/registraci/pairingu. Transparentní migrace: pokud dešifrování selže, zkusí plaintext a re-uloží šifrovaně. os.chmod(d, 0o700) na všechny mkdir() v get_key_dir, opk_private, sessions, sender_keys, sender_keys_recv, message_cache. os.chmod(p, 0o600) na plaintext fallback message cache.

• H7 Avatar path traversal — _safe_avatar_path() guard na handle_get_avatar, handle_get_group_avatar + defense-in-depth na handle_update_avatar, handle_update_group_avatar.

• Multi-device support (per-device sessions) — devices table, device_id columns on prekeys/messages/recipients/sender_keys. Server: device registration at login, writer_device_map, per-device key bundles (device_bundles array), per-device notification routing (device_entries), list_devices/remove_device handlers. Client: device_id persistence, sessions keyed by "user_id:device_id", _get_device_bundles() with 5-min TTL cache, per-device encryption in _send_dm/send_image/send_file/_distribute_sender_key, sender_device_id in decrypt routing, decrypt_notification() handles device_entries format. Pairing simplified: only RSA + identity key transfer, new device generates own SPK + OPKs. Migration: old session files auto-migrated, backward compat with old clients/servers. H12 OPK race condition fixed (SELECT FOR UPDATE).

• Connection resilience fixes — _background_listener fails all pending futures with ConnectionError on disconnect (prevents hang). send_and_recv has 30s timeout + catches ConnectionError. Server dispatch has per-message try/except (handler crash no longer kills connection). GUI _do_send_message/_do_find_or_create_and_send catch exceptions and emit error signal.

• DB transaction fix — db.get_key_bundles_for_user() had "Transaction already in progress" error because mysql-connector starts implicit transactions. Fixed with conn.commit() before conn.start_transaction().

• H5+H6 Protocol error handling — decode_binary() catches binascii.Error → ValueError. parse_message() catches JSONDecodeError/UnicodeDecodeError → ValueError. Server dispatch already handles ValueError from read_message() gracefully.

• H3+H13 Anti-enumeration — handle_register_start returns same "ok" response for existing email (no "Email already in use" leak). handle_login_start returns fake challenge for non-existent email. handle_login_finish returns generic "Invalid credentials" for all failure cases. get_user_info moved behind auth barrier (requires login).

• H8 Password memory cleanup — register(), login(), pairing_wait() convert password to bytearray, zero out in finally block after key derivation.

• H10 Image validation — _safe_load_image() helper validates size (<10MB) and dimensions (<8192px) before QImage.fromData(). Applied to all 6 image loading locations in gui_client.py.

• H11 Filename sanitization — _safe_filename() helper strips path components via os.path.basename(). Applied to save dialogs and image dialog title.

• C1+C2+C5 DoS hardening — C1: LimitOverrunError now drains buffer and raises ValueError (server sends error response instead of silent disconnect; memory already protected by limit= on StreamReader). C2: MAX_SENDER_KEY_SKIP reduced from 1000 to 256 (matches DoubleRatchet MAX_SKIP). C5: handle_upload_image_end validates received_bytes == file_size before completing upload. M12 (upload end size validation) also fixed by C5.

• M2+M8+M10+M11 Security hardening batch — M2: SenderKeyState HKDF salt changed from b"" to b"\x00" * 32 (matches X3DH convention). M8: _valid_file_id() renamed to _valid_uuid(), UUID validation added to all handlers accepting client-provided conv_id, user_id, message_id, device_id. M10: handle_mark_read caps message_ids to 500 (prevents slow SQL DoS). M11: handle_pairing_start generates poll_token (secrets.token_hex(16)), handle_pairing_poll requires and validates it via secrets.compare_digest() — prevents unauthorized poll/payload extraction.

• H2+H14 TLS hardening — TLS_INSECURE a TLS_AUTOGEN nyní vyžadují ENVIRONMENT=dev (RuntimeError bez toho). Warning log na serveru i klientovi když TLS vypnuté. C4 (OPK file permissions) bylo již opraveno v C3+H1+M13 batchi.

• Online dot fix + sorting — Fixed timing issue where online_users signal processed before conv list populated. _rebuild_conv_list() sorts: favorites first → online DMs → rest alphabetically.

• Favorites system — Right-click context menu on conversation list → Add/Remove from favorites. Star indicator (★). Persisted to favorites.json in user key directory.

• Group renaming — Full stack: db.update_conversation_name(), handle_rename_conversation (server, creator-only, max 100 chars), rename_conversation() (chat_core), "Rename" button in group info dialog (GUI), conversation_renamed push notification to all members.

• M3+M4+M9 Security hardening — M3: PBKDF2 600k iterations (_encrypt_private_key/_decrypt_private_key s ECP1 formátem, backward compat pro PEM). M4: SPK rotace každých 7 dní, spk_created_at v get_prekey_count, grace period s prev_spk_private.bin, fallback v _process_x3dh_header/_decrypt_dm. M9: _snapshot()/_restore() v DoubleRatchet.decrypt(), snapshot/restore v SenderKeyState.decrypt().

• Phantom invitation fix — Phantom users now receive group invitations. handle_create_conversation and handle_add_member create invitations for phantoms (no push notification). handle_register_confirm upgrades phantom in-place via db.upgrade_phantom_user() (preserves user_id + FK references). handle_add_member creates phantom for unregistered emails (same as create_conversation). After registration, user sees pending invitations on login.

• Message Search — Client-side search through decrypted message cache. ChatClient.search_messages() searches local cache. GUI: collapsible search bar (Ctrl+F) with prev/next navigation, match count, yellow/orange highlighting in message HTML. Escape closes search. Search button in chat header.

• Session Recovery — session_reset protocol message + handle_session_reset server handler. ChatClient.reset_session() deletes local session + notifies peer. Peer handles session_reset notification by deleting their session. Next message auto-creates new session via X3DH. GUI: "Reset session with sender" context menu on undecryptable messages, status bar notification on incoming reset.

• L8 Phantom user DB inflation fix — _valid_email() helper validates email format before phantom creation in handle_find_conversation, handle_create_conversation, handle_add_member. db.cleanup_stale_phantoms(30) deletes phantom users older than 30 days with no active conversations with real users. Runs in _periodic_cleanup every 10 minutes, refreshes in-memory phantom_user_ids cache.

• M6 TOCTOU race fix — db.remove_conversation_member_atomic() returns bool (True if row existed). Used in handle_remove_member (checks return value, returns error if already removed) and handle_leave_group. Defense-in-depth: pre-checks remain for user-friendly errors, atomic operation prevents double-removal.

• Local-first messages + multi-device received messages fix — Self-encrypted copies for received messages (not just sent). batch_reencrypt_messages() changed to INSERT ON DUPLICATE KEY UPDATE (upsert) — allows creating SELF_DEVICE_ID rows for received messages. Server-side Python dedup in handle_get_messages (prefers device-specific over SELF_DEVICE_ID). after_ts parameter for incremental sync. get_deleted_since protocol + handler for deletion sync. _pending_self_encrypt queue + _flush_self_encrypt() for background self-encryption of received notifications via asyncio.ensure_future().

• Detailed server logging — _who(session) helper for consistent log formatting. 25+ tagged log lines: [CONN], [LOGIN], [REGISTER], [MSG], [FETCH], [READ], [UPLOAD], [DOWNLOAD], [CONV], [INVITE], [LEAVE], [RENAME], [DELETE], [AVATAR], [PREKEYS], [X3DH], [ROTATE], [DEVICE], [REENCRYPT], [SESSION], [MEMBER], [LIST], [ERROR].

• Version bump to 0.8.4 — VERSION = "0.8.4", MIN_CLIENT_VERSION = "0.8.3" in protocol.py. Server rejects clients older than 0.8.3. iOS client (0.8.3) still works — new notification types and payload fields are silently ignored.

• Message Reactions — Emoji reactions on messages (thumbsup, heart, laugh, surprised, sad, thumbsdown). message_reactions DB table. db.add_reaction()/db.remove_reaction()/db.get_reactions(). Server: handle_react_message + message_reacted push notification. get_messages response includes reactions array per message. GUI: reaction submenu in context menu, toggle (add/remove), emoji badges below messages (grouped by reaction, highlighted if own), real-time updates via notification. CLI: option 16.

• Message Forwarding — Forward messages to other conversations. ChatClient.forward_message() sends as normal send_message with forwarded_from metadata field ({sender, conversation_id, message_id}). No new server endpoint needed. GUI: "Forward" in context menu, conversation picker dialog, "Forwarded from" header with blue left border in message rendering. CLI: option 19.

• Pinned Messages — Pin/unpin messages in conversations. messages.pinned_at/pinned_by columns. db.pin_message()/db.unpin_message()/db.get_pinned_messages(). Server: handle_pin_message + handle_get_pinned_messages + message_pinned/message_unpinned push notifications. GUI: "Pin"/"Unpin" in context menu, pin emoji indicator in message header, "Pinned" button in header opens dialog with list (double-click scrolls to message), real-time updates. CLI: options 17-18.

• @Mentions — @username highlighting in messages. Client-side only (no server-side handling). GUI: MentionCompleter popup autocomplete activated when typing @ in message input, filters current conversation members, inserts @username on selection. Message rendering: @word patterns highlighted in blue bold (#89b4fa). CLI: visible as plain @username text.

• Drag & Drop souborů/obrázků — Přetažení souboru na chat oblast (message input nebo message area) automaticky odešle. Obrázky (.png, .jpg, .jpeg, .gif, .bmp, .webp) se posílají přes send_image, ostatní přes send_file. Vizuální feedback: modrý dashed border při drag-over. Drop je aktivní pouze když je vybraná konverzace (drop_enabled flag na MessageInput, current_conv_id check v event filteru na message_area).

• Registration prekey upload fix — _ensure_prekeys() now detects missing SPK on server (empty spk_created_at) and forces upload with need_new_spk=True. Previously, registration uploaded prekeys before login (no session → server rejected with "Not logged in"), and the login flow only uploaded OPKs without SPK. Also added warning log in _generate_and_upload_prekeys() when upload fails.

• Message sender identification fix — _render_single_message_html() now uses sender_id (user_id UUID) instead of sender (username) for is_me detection. Fixes incorrect message alignment when two users share the same display name.

• Privacy Overlay (lock screen) — Anti-forensic privacy feature (PyQt only). On window deactivation: immediate dark overlay with lock icon hides all chat content (protects against Alt+Tab thumbnails, screen sharing, shoulder surfing). After 30 seconds unfocused: locks and requires login password to unlock (verified by decrypting identity key from disk via ECP1/PBKDF2-600k). Ctrl+Shift+P toggles on/off. Tray notifications continue working while locked. Messages arriving during lock are counted as unread and NOT marked as read until user unlocks. _lock_capable flag auto-detects if identity key is password-encrypted (ECP1 format) — lock requires password only when available.

• Secure Deletion (anti-forensic wipe) — _secure_delete(path) helper overwrites file with os.urandom() + fsync before unlink. Applied to all sensitive file deletions: OPK private keys, session files (reset + migration), received sender key migration, message cache migration (plaintext JSON cleanup) in chat_core.py; .enc and .tmp files on conversation delete, message delete, oversized upload cleanup, incomplete upload cleanup, stale upload periodic cleanup in server.py. Fallback to standard unlink if overwrite fails.

• UI redesign (Signal/Telegram look) — theme.py theme systém (ThemeColors dataclass, DARK_THEME Catppuccin Mocha, LIGHT_THEME Signal-inspired, ThemeManager singleton s persistence + live switching). Widget-based message bubbles (MessageBubble QFrame s QPainter rounded rect). ConversationDelegate (custom painting: avatar, name, preview, timestamp, unread badge). Redesigned chat header (avatar, name, status, action buttons). Pill-shaped input (auto-resize, 2-line min). Tabbed login (Login/Register/Link Device). Frameless dialogs (_make_frameless). Theme toggle (sun/moon) v settings.

• Reakce/piny persistentní v cache — ChatClient.update_message_in_cache() synchronně aktualizuje pole zprávy v šifrovaném message cache na disku. Volá se při přidání/odebrání reakce, pin/unpin (z kontextového menu i z push notifikací). Opravuje bug kdy reakce a piny mizely po přepnutí konverzace a návratu (incremental sync nenačítal stará data ze serveru).

• Context menu fallback na zprávách — MessageBubble context menu policy změněna z CustomContextMenu na DefaultContextMenu. S CustomContextMenu Qt emitoval nepřipojený signál místo volání contextMenuEvent() override — kontext menu se neukázalo. Event filter zůstává jako primární handler, contextMenuEvent je fallback.

• Forward obrázků a souborů — forward_message() v chat_core.py přeposílá kompletní image/file metadata (file_id, AES klíč, IV, thumbnail, filename, size). Dříve se posílal jen textový popis [Forwarded image: ...]. Šifrovaný soubor je na serveru, stačí přeposlat metadata.

• Delete message okamžitý — Smazání zprávy se projeví lokálně ihned (bez čekání na reload). Server posílá message_deleted notifikaci jen ostatním, ne odesílateli — opraveno lokálním označením zprávy jako smazané + uložením do cache + re-renderem před odesláním na server.

• Frameless confirmation dialogy — _confirm_dialog() helper nahrazuje QMessageBox.question() — frameless dialog bez systémové lišty, s červeným "Delete" tlačítkem. Aplikováno na Delete Message a Reset Session dialogy.

• Reakce — explicitní barva textu — Reaction badge QLabel nyní má explicitní color: {t.text_primary} aby byl text viditelný v obou režimech (předtím spoléhal na CSS dědičnost).

• SPK/OPK encryption + brute-force lockout — SPK/OPK private keys now encrypted with AES-256-GCM via _local_key (derived from identity key via HKDF). Transparent migration from plaintext. Client-side brute-force lockout: exponential backoff min(2^N, 300) seconds after N failed password attempts. Lockout state in login_lockout.json. Applied to ChatClient.login() and GUI privacy overlay unlock (_on_unlock_attempt). _clear_lockout() on success.

• Contact Key Verification — Signal-style safety numbers, fingerprints, QR codes. TOFU key tracking (known_identity_keys.bin) + explicit verification (verified_contacts.bin), both encrypted with _local_key. crypto_utils.py: compute_fingerprint() (iterated SHA-512, 5200x), format_fingerprint() (30 digits), compute_safety_number() (60 digits, symmetric), encode_verification_qr()/decode_verification_qr(). chat_core.py: check_identity_key() (TOFU with "new"/"trusted"/"verified"/"changed"/"changed_verified"), verify_contact(), unverify_contact(), accept_key_change(), get_verification_status(), get_safety_number(), get_my_fingerprint(), get_peer_fingerprint(), get_verification_qr_data(), verify_qr_code(). GUI: VerificationDialog (safety number, QR code, fingerprints, verify/unverify buttons, QR scan), green checkmark in conversation list for verified DMs (ROLE_VERIFIED), E2E label clickable with verification status, key change warning dialog, security section in UserProfileDialog, verified badge in group info member list. CLI: options 20 (verify contact) and 21 (show fingerprint). Zero server changes.

• Metadata Privacy (Ochrana metadat) — Čtyři opatření pro minimalizaci metadat: (A) Message Padding — pad_plaintext()/unpad_plaintext() v crypto_utils.py. Bucketed padding (64/128/256/512/1K/2K/4K/8K/16K/32K/64K). Formát: 0x01 + plaintext + random_padding + pad_length(4B). Prefix 0x01 rozliší od legacy JSON (začíná {). Aplikováno na všech 6 send cest v chat_core.py (send_message, distribute_sender_key, forward_message, send_image, send_file, reencrypt_history) + unpad na 2 decrypt cestách (_decrypt_dm, _decrypt_group). (B) Log Sanitizace — _who() vrací u=XXXXXXXX d=YYYYYYYY místo username (email) [device]. Group names a recipient counts odstraněny z logů. (C) Metadata Retention — db.cleanup_old_reads()/db.cleanup_old_reactions() mažou záznamy starší N dní (default METADATA_RETENTION_DAYS=90). Batch delete (10k/iterace). Spouští se v _periodic_cleanup() každé 2 minuty. (D) Sender Chain Přesun — sender_chain_id/sender_chain_n se pro nové group zprávy ukládají do message_recipients.ratchet_header místo messages tabulky. Server handle_get_messages extrahuje z obou míst (backward compat). Notifikace stále posílají chain data pro live decrypt.

• TCP Keepalive + Dead Writer Cleanup — Oprava tichého umírání TCP spojení přes NAT/firewall, které způsobovalo nedoručení push notifikací (zprávy se zobrazily až po manuálním vstupu do konverzace). (A) Server + klient nastavují SO_KEEPALIVE s TCP_KEEPIDLE=25s, TCP_KEEPINTVL=10s, TCP_KEEPCNT=3 na TCP socketu — OS posílá probe pakety a po 55s bez odpovědi označí spojení jako mrtvé. (B) _notify_users()/_notify_users_individual() v server.py kontrolují w.is_closing() před odesláním, při selhání logují a odstraňují mrtvý writer z connected_clients přes nový _remove_dead_writer() helper (dříve except Exception: pass tiše spolkl chybu). (C) ProtocolWriter.is_closing() nový helper v protocol.py.

• Optimistic Message Send — Zpráva se zobrazí v UI okamžitě po stisknutí Send (bez čekání na server). _on_send() v gui_client.py vytvoří optimistický payload s _optimistic: True a přidá ho do current_messages + UI. Po server response _on_message_sent_payload() najde optimistickou zprávu (match přes text+sender) a nahradí ji potvrzenou verzí (s message_id, created_at). Při chybě odeslání _on_message_sent() optimistickou zprávu odstraní z UI a zobrazí error.

• Cache-First Message Loading — Při přepnutí konverzace se okamžitě zobrazí zprávy z lokálního cache (disk), server fetch běží na pozadí. chat_core.get_cached_messages(conv_id) čte z message_cache bez server callu. _on_conv_selected() volá get_cached_messages() synchronně → zobrazí → poté bridge.load_messages() async doplní nové. Fetch deduplication: _messages_inflight set v AsyncBridge zabraňuje duplicitním fetchům stejné konverzace.

• Notification Push Logging — Server loguje [PUSH] msg=... conv=... targets=[uid(Nw)] s počtem writerů per příjemce. _notify_users_individual() loguje warning při selhání doručení s user_id a chybou.

• Image/File Transfer Performance Overhaul — Drastické zrychlení downloadu obrázků a souborů: (A) Chunk size zvětšen z 32KB na 256KB (8× méně chunků, méně JSON/base64 overhead). (B) MAX_MESSAGE_BYTES zvětšen z 64KB na 1MB (nutné pro větší chunky). (C) Nový download_stream handler na serveru — jedna DB autorizace, pak server streamuje všechny chunky bez čekání na per-chunk request (dříve 2 DB queries × N chunků). Klient sbírá stream chunky přes asyncio.Queue v _background_listener. (D) Fallback na legacy download_image pro starší servery. (E) image_download_failed signál v GUI — _pending_image_download se vyčistí při selhání (dříve zůstal navždy a blokoval další downloads). (F) Sender cache: obrázek se cachuje lokálně po uploadu (media_cache/{file_id}.bin), sender vidí obrázek okamžitě bez server round-trip.

🐛 Známé bugy a problémy

• Sender Key Redistribution (High Priority): New group member can't decrypt old messages. On add_member, existing members should re-create and redistribute sender keys.
• Pomalé přepínání konverzací (High Priority): ✅ OPRAVENO — cache-first loading + fetch deduplication. Server round-trip už jen na pozadí pro sync nových zpráv.
• Database Connection Pooling: ✅ OPRAVENO — MySQLConnectionPool(pool_size=10).
• Duplicate FETCH after send (GUI): ✅ OPRAVENO — send_message vrací payload lokálně, GUI appenduje bez re-fetch.
• Group delete confirmation message is generic ✅ OPRAVENO — frameless dialog s kontextovým textem.
• Reakce a piny mizely po přepnutí konverzace: ✅ OPRAVENO — update_message_in_cache() ukládá na disk.
• Forward obrázku/souboru posílal jen text: ✅ OPRAVENO — přeposílá kompletní image/file metadata.
• Delete message se neprojevil okamžitě: ✅ OPRAVENO — lokální smazání + cache update před serverovým voláním.
• Delete/Reset dialogy měly systémovou lištu: ✅ OPRAVENO — frameless _confirm_dialog().

⏭️ Další kroky (TODO)

Bezpečnostní opravy (priorita dle auditu)

1. C6 (CRITICAL): Path traversal přes file_id — handle_upload_image_start vytváří soubor UPLOAD_DIR / f"{file_id}.tmp" bez validace. Útočník může ../../... a zapisovat/mazat mimo UPLOAD_DIR. Řešení: validovat UUID formát, ověřit path.resolve().is_relative_to(UPLOAD_DIR.resolve()).
2. H12 (HIGH): OPK race condition v db.get_key_bundle() ✅ OPRAVENO (součást multi-device — SELECT FOR UPDATE v consume_one_time_prekey + get_key_bundle)
3. H3+H13: User enumeration — get_user_info dostupné bez auth, vrací identity_key pro libovolný email. register_start/login_start vrací jednoznačné chyby. Řešení: auth pro get_user_info, generické odpovědi pro register/login.
4. H2+H14: TLS hardening ✅ OPRAVENO — TLS_INSECURE a TLS_AUTOGEN vyžadují ENVIRONMENT=dev. Warning log při vypnutém TLS.
5. C1+C2+C5 ✅ OPRAVENO — DoS vektory (LimitOverrunError → ValueError, MAX_SENDER_KEY_SKIP 256, upload completeness check)
6. C3+C4+H1 — Šifrování dat na disku (message cache, sessions, OPK permissions, chmod 0o700 pro adresáře)
7. H5+H6 — Error handling v protokolu (base64, JSON)
8. H7 — Path traversal v avatar souborech (resolved_path.is_relative_to())
9. M11 (MEDIUM): Pairing poll DoS ✅ OPRAVENO — poll_token binding (secrets.token_hex(16) + secrets.compare_digest)
10. M12: Upload end bez validace velikosti ✅ OPRAVENO (součást C5 fixu — handle_upload_image_end validuje received_bytes == file_size)
11. L8: Phantom user DB inflation ✅ OPRAVENO — email validace + periodic cleanup stale phantoms (30 dní)
12. Version negotiation — VERSION = "0.8" v protocol.py, klient posílá client_version při loginu, server loguje a vrací server_version

Před nasazením do produkce (checklist)

1. TLS certifikáty — Získat certifikát (Let's Encrypt / vlastní CA). Nastavit TLS_ENABLED=true, TLS_CERT_FILE, TLS_KEY_FILE v .env. Ověřit že TLS_INSECURE a TLS_AUTOGEN NEJSOU nastavené (vyžadují ENVIRONMENT=dev). Na klientovi nastavit TLS_ENABLED=true a případně TLS_CA_FILE pokud vlastní CA.
2. Email validace — Zapnout _valid_email() kontrolu v handle_find_conversation, handle_create_conversation, handle_add_member (kód existuje v server.py, volání zakomentována). Teď vypnuto protože dev prostředí používá emaily bez @.
3. MySQL TLS — Přidat SSL parametry do db.get_connection() (ssl_ca, ssl_cert, ssl_key) pokud DB běží na jiném stroji.
4. Connection pooling — Nahradit get_connection() za mysql.connector.pooling.MySQLConnectionPool(pool_size=10).
5. SMTP — Nastavit reálný SMTP server pro registrační kódy (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM).
6. UPLOAD_DIR — Ověřit že UPLOAD_DIR je na persistentním disku s dostatkem místa, správnými právy (0o700).
7. Rate limity — Přezkoumat limity pro produkční zátěž (registrace 3/min, login 10/min, send_message 20/min, max 10 spojení/IP).
8. Packaging — Zabalit klienta (pyinstaller / cx_Freeze) pro distribuci. Po zabalení zvážit auto-update mechanismus a get_version endpoint.
9. Penetrační testy — Provést před ostrým nasazením (viz sekce níže).
10. Backup — Nastavit pravidelný backup MySQL databáze + UPLOAD_DIR.

Penetrační testy

• Naplánovat a provést manuální penetrační testy zaměřené na:
  • Path traversal (file_id, avatar_file)
  • DoS vektory (readuntil, sender key fast-forward, upload flooding)
  • Race conditions (OPK reuse, membership TOCTOU)
  • User enumeration (register, login, get_user_info)
  • TLS downgrade / MITM bez TLS
  • Pairing session hijacking
  • Memory exhaustion (rate_limits, phantom users, message_ids)
• Vytvořit testovací skripty pro automatizované security testy
• Zdokumentovat výsledky a opravit nalezené problémy

Ke zvážení

• Auto-update klientů — distribuce aktualizovaných souborů klientům před login/registrací. Řešit až po kompilaci/packagingu (pyinstaller apod.). Mechanismus: server verze check → klient stáhne nové soubory → restart.
• Server version check endpoint — po packagingu mít jednoduchý endpoint (např. get_version), který vrací min/aktuální podporovanou verzi klienta + URL/metadata pro update; klient může před loginem ověřit kompatibilitu a nabídnout update. Vhodné i pro postupné vypínání starých klientů.

Monetizace — plán

Princip: Oddělený platební server (KYC/AML compliant) od chat serveru (anonymní). Platba generuje jednorázový premium kód, chat server zná jen "user_id aktivoval kód". Žádný přímý link platba↔chat identita.

Architektura:

Platební server (Stripe/Paddle):  zákazník → platba → vygeneruje premium_code
    sdílí jen: premium_code (jednorázový string)
Chat server:                      user_id → aktivuje premium_code → premium do data X

• Platební server neví jaký user_id kód použil
• Chat server neví kdo kód koupil
• AML splněno na platební straně, privacy zachováno na chat straně

Free vs Premium tier:

	Free	Premium
Konverzace	5	neomezeno
Soubory	10 MB	50 MB
Zařízení	1	5
Message retention	30 dní	neomezeno
Skupiny	max 10 členů	neomezeno

Implementace (chat server):

• Tabulka premium_codes(code VARCHAR(64) PK, plan ENUM('premium_30','premium_365'), created_at, redeemed_by CHAR(36) nullable FK, redeemed_at nullable)
• Tabulka user_plans(user_id PK FK, plan ENUM('free','premium'), expires_at DATETIME nullable, message_retention_days INT DEFAULT 30)
• Sloupec messages.expires_at (nullable DATETIME) — NULL = neomezená retence
• Handler redeem_code — validuje kód, aktivuje plán, nastaví expires_at
• handle_send_message — kontroluje limity (konverzace, velikost)
• Periodic cleanup: DELETE FROM messages WHERE expires_at IS NOT NULL AND expires_at < NOW() + CASCADE + .enc smazání
• Retence podle konverzace: pokud alespoň jeden člen premium → vyšší retence
• Klient: indikace expirace zpráv, upozornění na limity, "Upgrade" tlačítko

Implementace (platební server — oddělený deployment):

• Jednoduchý web (Flask/FastAPI) s Stripe Checkout
• Generuje premium_code, uloží do sdílené DB nebo pošle přes API
• AML/KYC řeší Stripe (PCI DSS, SCA, reporting)

Další revenue streams:

• Enterprise/B2B licence — self-hosted deployment, LDAP/SSO, admin dashboard, SLA. Faktura na IČO.
• Šifrovaný cloud backup — export/import historie šifrované uživatelským heslem (nezávisle na retenci)

Funkční vylepšení

1. Sender Key Redistribution — on add_member, redistribute sender keys to all members including new one
2. Device Linking fix ✅ — replaced with true multi-device (per-device sessions, simplified pairing)
3. SPK Rotation ✅ — periodic rotation with grace period (implemented in M4 fix)
4. Typing Indicators (budoucí) — typing_start/typing_stop protocol + GUI indicator (3s timeout, debounce)
5. CLI support ✅ — profiles, file sharing, invitations, leave/rename/delete, search, devices in client.py
6. Message search ✅ — client-side search through decrypted cache, Ctrl+F toggle, highlight + navigation
7. Session Recovery ✅ — session_reset protocol, auto-recreate via X3DH on next message
8. Connection Pooling ✅ — MySQLConnectionPool(pool_size=10), lazy init, DB_POOL_SIZE env var. conn.close() vrací do poolu.
9. Version negotiation ✅ — VERSION = "0.8.4" in protocol.py, client sends client_version at login, server rejects clients < MIN_CLIENT_VERSION
10. Delivery Receipts — message_delivered notifikace po přijetí na zařízení (1 fajfka = odesláno, 2 fajfky = doručeno, modré = přečteno). Nová tabulka message_deliveries nebo rozšíření message_reads.
11. Reakce na zprávy (Message Reactions) ✅ — emoji reakce na zprávy. Tabulka message_reactions. Push notifikace message_reacted. GUI: emoji badges pod zprávou, submenu v kontext menu.
12. Přeposílání zpráv (Message Forwarding) ✅ — kontext menu "Forward", výběr konverzace, odeslání s forwarded_from metadatem. GUI: "Forwarded from" header.
13. Připnuté zprávy (Pinned Messages) ✅ — messages.pinned_at/pinned_by sloupce. pin_message/unpin_message/get_pinned_messages protokol. GUI: pin ikona + dialog s připnutými zprávami.
14. Zmínky (@mentions) ✅ — parsování @username v textu, autocomplete při psaní @, zvýraznění zmínek v modré. Klient-side only (bez server notifikací).
15. Contact Key Verification ✅ — Signal-style safety numbers (60 digits, symmetric), fingerprints (30 digits), QR codes. TOFU key tracking + explicit verification. GUI: VerificationDialog, green checkmark v conv listu, E2E label status, key change warning. CLI: options 20+21. Zero server changes.

Message Loading + Send Optimalizace (✅ částečně implementováno)

Implementováno:

1. ✅ Cache-first zobrazení (gui_client.py: _on_conv_selected()):

   • chat_core.get_cached_messages(conv_id) čte zprávy z lokálního disku (message_cache), žádný server call
   • _on_conv_selected() volá get_cached_messages() → okamžitě zobrazí v UI → poté bridge.load_messages() async syncne se serverem na pozadí
   • Výsledek: zprávy se zobrazí okamžitě při kliknutí na konverzaci

2. ✅ Fetch deduplication (gui_client.py: AsyncBridge._messages_inflight):

   • _messages_inflight: set[str] — pokud pro conv_id už běží server fetch, nový se neprovede
   • Eliminuje duplicitní round-tripy (dříve stejná konverzace fetchována 4× za sebou)

3. ✅ Optimistic message send (gui_client.py: _on_send()):

   • Zpráva se zobrazí v UI okamžitě po stisknutí Send (optimistický payload s _optimistic: True)
   • Server potvrzení na pozadí → _on_message_sent_payload() nahradí optimistickou zprávu potvrzenou
   • Při chybě → _on_message_sent() odstraní optimistickou zprávu + zobrazí error

Aktuální flow:

_on_conv_selected() [gui_client.py]
  ├─ get_cached_messages() → zobrazit OKAMŽITĚ z disku
  └─ bridge.load_messages() → ASYNC na pozadí:
      └─ chat_core.get_messages(conv_id)
          ├─ send_and_recv("get_messages", after_ts=...)
          ├─ send_and_recv("get_deleted_since", ...)
          └─ mark_conversation_read(conv_id)
          → messages_loaded signal → aktualizovat UI pokud nové zprávy

_on_send() [gui_client.py]
  ├─ Optimistický payload → zobrazit OKAMŽITĚ v UI
  └─ bridge.send_message() → ASYNC na pozadí:
      └─ chat_core.send_message() → šifrování + server
          → message_sent_payload signal → nahradit optimistickou zprávu

TODO (zbývající optimalizace):

• TTL cache (5s) — skip server fetch pokud nedávno syncováno
• Skip get_deleted_since při 0 nových zpráv
• Skip mark_conversation_read při 0 nepřečtených
• Debounce přepínání konverzací (150ms timer)

Optimalizace serveru

1. DB Connection Pooling ✅ — viz bod 8 výše.
2. Oprava duplicitních FETCH v GUI ✅ — send_message vrací payload lokálně, GUI appenduje bez re-fetch. Dedup guard v _on_notification.
3. Batch prekey replenishment ✅ — ensure_prekeys handler na serveru (get_prekey_count + upload v jednom roundtripu). _generate_and_upload_prekeys_batch() v chat_core.
4. Server-side message count ✅ — get_messages response obsahuje total_count. db.count_messages() funkce.
5. Prepared statements / query cache — pro často opakované dotazy (get_messages, list_conversations) připravit prepared statements.
6. WebSocket upgrade — dlouhodobě nahradit raw TCP za WebSocket pro lepší kompatibilitu s firewally, load balancery, a web klienty.

Mobilní push notifikace (budoucí — iOS + Android)

• Tabulka push_tokens(user_id, device_id, platform ENUM('ios','android'), token, created_at)
• Server: při new_message pokud cílový uživatel nemá aktivní TCP spojení → odeslat přes APNs (iOS) / FCM (Android)
• Obsah push: jen "Nová zpráva od X" (E2EE = server nezná plaintext)
• iOS: UserNotifications framework, registrace tokenu při loginu, didReceiveRemoteNotification
• Android: Firebase Cloud Messaging, FirebaseMessagingService
• Server-side: aioapns (Python APNs library) + firebase-admin (FCM SDK)

Bezpečnostní audit (Security Audit)

Kompletní audit provedený přes všechny soubory projektu. Nálezy seřazené podle závažnosti.

🔴 CRITICAL — Okamžitě řešit před nasazením

C1. readuntil() bez limitu → memory exhaustion (protocol.py:62) ✅ OPRAVENO

ProtocolReader.read_message() volá readuntil(b"\n"), které načte CELOU zprávu do paměti PŘED kontrolou velikosti. Útočník pošle gigabyty dat bez newline → server spadne na out-of-memory.

line = await self._reader.readuntil(b"\n")  # buffers everything first!
if len(line) > MAX_MESSAGE_BYTES:            # too late

Řešení: Implementovat framing s hlavičkou obsahující velikost zprávy, nebo použít readuntil() s limit parametrem (asyncio StreamReader nemá nativně — nutno obalit vlastním čtením po částech).

C2. SenderKeyState — neomezený fast-forward DoS (crypto_utils.py:642-645) ✅ OPRAVENO

Při dešifrování skupinové zprávy s libovolně vysokým n se smyčka while self.n <= n provede milionkrát — derivuje milion klíčů, spotřebuje stovky MB RAM.

while self.n <= n:
    self.chain_key, mk = kdf_ck(self.chain_key)
    self._known_keys[self.n] = mk  # unbounded dict growth
    self.n += 1

Řešení: Přidat MAX_FORWARD_SKIP limit (např. 1000) — stejně jako Double Ratchet má MAX_SKIP=256.

C3. Dešifrované zprávy uložené jako plaintext na disku (chat_core.py:222-239)

Message cache v ~/.encrypted_chat/{email}/message_cache/{conv_id}.json obsahuje plný obsah dešifrovaných zpráv v nešifrovaném JSONu. Bez nastavení chmod 0o600. Kdokoliv s přístupem k disku přečte kompletní historii. Řešení: Šifrovat cache klíčem odvozeným z identity key + nastavit chmod 0o600 na soubory.

C4. OPK private keys bez file permissions (chat_core.py:153-156) ✅ OPRAVENO

OPK privátní klíče se ukládají bez os.chmod(0o600). RSA klíče (řádek 87) a identity key (řádek 121) mají chmod — OPK ne. Na sdílených systémech může jiný uživatel přečíst ephemeral klíče. Opraveno: Součást C3+H1+M13 fixu — _save_opk_private() nyní volá os.chmod(path, 0o600) + os.chmod(dir, 0o700).

C5. Chunked upload nevaliduje celkovou velikost (server.py:1138-1142) ✅ OPRAVENO

handle_upload_image_chunk akumuluje received_bytes ale nekontroluje limit. Útočník deklaruje file_size=5MB, pak posílá chunky donekonečna → disk exhaustion.

upload["received_bytes"] += len(raw)  # no check against file_size!

Řešení: Přidat if upload["received_bytes"] > upload["file_size"]: reject.

🟠 HIGH — Řešit před production nasazením

H1. Session + sender key soubory nešifrované na disku (chat_core.py:176-215)

Double Ratchet session state (DH privátní klíče, root key, chain keys) a sender key state se ukládají jako plaintext hex JSON v sessions/ a sender_keys/. Bez šifrování, bez chmod 0o600. Kompromitace disku = dešifrování celé historie. Řešení: Šifrovat state klíčem z identity key, nastavit chmod 0o600.

H2. TLS vypnuté ve výchozím stavu (chat_core.py:274-291, server.py) ✅ OPRAVENO (hardening)

TLS_ENABLED je defaultně false. Bez TLS jdou po síti RSA challenge-response, session tokeny a metadata v plaintextu. TLS_INSECURE=true vypíná certificate verification → MITM. Opraveno: TLS_INSECURE a TLS_AUTOGEN nyní vyžadují ENVIRONMENT=dev — v produkci RuntimeError. Warning log při vypnutém TLS na serveru i klientovi. TLS_ENABLED zůstává default false (uživatel nemá certifikát), ale po nasazení Let's Encrypt stačí flip na true.

H3. User enumeration přes registraci (server.py:182-189)

Registrace vrací "Email already in use" pro existující uživatele vs. tiché vytvoření phantoma pro neexistující. Útočník může enumerovat platné emaily. Řešení: Vrátit generickou odpověď "Check your email for verification code" i když email existuje.

H4. Race conditions v in-memory strukturách (server.py: multiple) ✅ OPRAVENO

connected_clients dict, phantom_user_ids set, pairing_sessions dict — čteny a zapisovány z více concurrent koroutin bez synchronizace. Asyncio je single-threaded, ale yieldy uvnitř handlerů (await) mohou způsobit nekonzistentní stav. Opraveno: 4 asyncio.Lock guards: _clients_lock (connected_clients, phantom_user_ids), _conn_lock (connection_counts, current_connections, rate_limits), _pairing_lock (pairing_sessions, pending_registrations), _uploads_lock (pending_uploads). Helper funkce _notify_users() / _notify_users_individual() — snapshot under lock, send outside. Rate limit memory cleanup v periodic task. Žádný handler nedrží dva locky současně → deadlock impossible.

H5. base64 decode bez error handling (protocol.py:14-16, server.py + chat_core.py)

decode_binary() volá base64.b64decode() bez try-except. Nevalidní base64 od klienta → unhandled binascii.Error → handler crash. Mnoho callsites v server.py (řádky 357, 378, 783) nemá catch. Řešení: Obalit decode_binary() try-except, nebo validovat base64 vstup před dekódováním.

H6. JSON parsing bez exception handling (protocol.py:48-50)

parse_message() volá json.loads() bez try-catch. Malformovaný JSON = neošetřený JSONDecodeError. Server handler catch (řádek 1399) to odchytí, ale není to explicitní. Řešení: Obalit json.loads() v parse_message() try-except s explicitní chybovou zprávou.

H7. Path traversal v avatar souborech (server.py:1265, 1318)

avatar_file ze serveru (z DB) se přímo joinuje s UPLOAD_DIR / "avatars" bez validace. Pokud DB obsahuje ../../etc/passwd, server přečte libovolný soubor. Řešení: Přidat resolved_path.resolve().is_relative_to(UPLOAD_DIR) check.

H8. Heslo v paměti jako Python string (chat_core.py, gui_client.py)

Python stringy jsou immutable — nelze je bezpečně vymazat z paměti. Heslo zůstává v paměti dokud garbage collector neuklidí. Memory dump = plaintext heslo. Řešení: Použít bytearray (mutable), po použití přepsat nulami: pwd[:] = b'\x00' * len(pwd).

H9. Self-encryption key je statický a deterministický (chat_core.py:904+, crypto_utils.py:224-233)

derive_self_encryption_key(identity_private) produkuje vždy stejný klíč. Kompromitace identity klíče = dešifrování všech vlastních kopií zpráv navždy. Žádná forward secrecy pro self-copies. Poznámka: Toto je by-design (nutné pro cross-device čtení), ale je to architektonické omezení.

H10. Malicious image data → QImage crash (gui_client.py)

QImage.fromData(data) zpracovává nevalidované binární data. Speciálně vytvořený obrázek může způsobit crash, memory exhaustion, nebo v extrémním případě RCE přes Qt image codec. Řešení: Validovat velikost dat před parsováním, limit na max rozlišení.

H11. Filename z serveru v save dialogu (gui_client.py:2389, 2460)

Server-controlled filename se předává jako default do QFileDialog.getSaveFileName(). Pokud server pošle "../../../.bashrc", dialog to navrhne. Řešení: Sanitizovat filename — odstranit ../, \, absolutní cesty. Použít jen os.path.basename().

🟡 MEDIUM — Zvážit pro hardening

M1. Inconsistentní Ed25519 serializace (crypto_utils.py:99-102)

Bez hesla: 32 raw bytes. S heslem: PEM PKCS8 (~302 bytes). Dva různé formáty mohou způsobit problém při migraci nebo obnově klíčů. Poznámka: M3 fix částečně řeší — s heslem je nyní ECP1 formát (ne PEM), ale load_ed25519_private() stále detekuje 3 formáty (ECP1, PEM, raw). Legacy PEM soubory se automaticky migrují při dalším uložení.

M2. Prázdný salt v SenderKeyState HKDF (crypto_utils.py:610) ✅ OPRAVENO

hkdf_derive(sender_key, salt=b"", ...) — RFC 5869 doporučuje nenulový salt. X3DH správně používá b"\x00" * 32. Opraveno: Změněno salt=b"" → salt=b"\x00" * 32 aby odpovídalo X3DH konvenci.

M3. PBKDF2 iterace pod doporučeným minimem (crypto_utils.py) ✅ OPRAVENO

BestAvailableEncryption používá ~100k iterací PBKDF2. OWASP 2023 doporučuje 480k+. Opraveno: Nahrazeno vlastním _encrypt_private_key/_decrypt_private_key s PBKDF2-HMAC-SHA256 (600k iterací) + AES-256-GCM. ECP1 formát (magic prefix) s backward compat pro staré PEM soubory. Aplikováno na RSA (serialize_private_key/load_private_key) i Ed25519 (serialize_ed25519_private/load_ed25519_private).

M4. SPK bez replay protection a bez rotace (server.py:360-368) ✅ OPRAVENO

Stejný SPK lze nahrát opakovaně. Žádný nonce/timestamp v podpisu. SPK se nikdy nerotuje → kompromitovaný SPK = trvalé dešifrování nových sessions. Opraveno: SPK rotace každých 7 dní (SPK_ROTATION_DAYS). Server vrací spk_created_at v handle_get_prekey_count. _ensure_prekeys() kontroluje stáří SPK a rotuje pokud >= 7 dní. Předchozí SPK uložen jako grace period (prev_spk_private.bin/prev_spk_id.txt) pro in-flight X3DH. _process_x3dh_header přijímá spk_override, _decrypt_dm retry s předchozím SPK při selhání dešifrování.

M5. Rate limit unbounded memory (server.py:73-83) ✅ OPRAVENO (součást H4 fixu)

Staré záznamy se nikdy nečistí pokud klíč přestane být aktivní → útočník vytvoří miliony klíčů → memory leak. Opraveno: _cleanup_rate_limits() v periodic cleanup (každých 10 min) maže stale entries z rate_limits i connection_counts.

M6. TOCTOU race v membership checks (db.py) ✅ OPRAVENO

is_conversation_member() → remove_conversation_member() — mezi kontrolou a akcí může jiný klient stav změnit. Opraveno: db.remove_conversation_member_atomic() vrací bool (True pokud řádek existoval). Použito v handle_remove_member a handle_leave_group.

M7. MySQL spojení bez TLS (db.py:20-28)

get_connection() nepředává SSL parametry. Na vzdáleném serveru jdou credentials v plaintextu.

M8. Chybějící validace UUID formátu (server.py: throughout) ✅ OPRAVENO

conv_id, user_id — kontrola jen na neprázdnost, ne na formát UUID v4. Opraveno: _valid_file_id() přejmenováno na _valid_uuid(). UUID validace přidána do všech handlerů přijímajících klientem poskytnuté conv_id, user_id, message_id, device_id.

M9. Ratchet state corruption recovery (chat_core.py:1088-1104) ✅ OPRAVENO

Pokud decrypt() změní chain keys ale selže na AAD verification, backup/restore mechanismus funguje, ale pokud backup selže (out-of-memory), stav zůstane corrupted. Opraveno: DoubleRatchet.decrypt() nyní snapshotuje stav přes _snapshot()/_restore() a rollbackuje při jakékoliv výjimce (včetně skipped message key restore). SenderKeyState.decrypt() stejně snapshotuje chain_key, n, _known_keys před fast-forward a rollbackuje při selhání.

M10. Chybějící validace velikosti message_ids listu (db.py:641-646) ✅ OPRAVENO

Klient může poslat tisíce message_ids v jednom požadavku → pomalý SQL dotaz, DoS. Opraveno: handle_mark_read nyní odmítá požadavky s více než 500 message_ids.

🟢 LOW — Dobrá praxe, nízké riziko

• L1. Hex string keys v skipped messages dict — timing side-channel po úspěšné autentikaci (crypto_utils.py:425)
• L2. RatchetHeader serializace redundantně konvertuje typy (crypto_utils.py:394-405)
• L3. notif_label.setText() bezpečné proti XSS (Qt neinterpretuje HTML v setText), ale křehké — přepnutí na setHtml() by to rozbilo (gui_client.py:1524, 2259)
• L4. SQL column interpolation v update_user_profile — whitelist chrání, ale pattern je nebezpečný při kopírování (db.py:818-822)
• L5. Chybějící TLS cipher suite hardening — Python defaulty jsou rozumné, ale ne explicitně nastavené (protocol.py)
• L6. Temporary pairing key není bezpečně vymazán z paměti (chat_core.py:581)
• L7. _user_cache ukládá public identity keys indefinitely — memory leak pro hodně kontaktů

Druhý bezpečnostní review (zaměření na návrh, DB, komunikaci, lokální tmp/cache)

C6. Path traversal → libovolný zápis/smazání souborů přes file_id (server.py)

handle_upload_image_start vytváří soubor UPLOAD_DIR / f"{file_id}.tmp" bez validace file_id. Útočník může poslat ../../... a zapisovat mimo UPLOAD_DIR. Následné rename, cleanup, delete_message a delete_conversation pak mohou mazat libovolné soubory. Řešení: Striktně validovat file_id (UUID hex/kanonický formát), odmítnout cokoliv s /, \, ... Ověřit path.resolve().is_relative_to(UPLOAD_DIR.resolve()). Ideálně ukládat do podadresářů podle hash/UUID.

H12. OPK race condition — reuse one-time pre-keys (db.py) ✅ OPRAVENO

V db.get_key_bundle() se OPK vybírá SELECT → DELETE bez transakčního zámku. Při souběhu může být stejný OPK vydán vícekrát → porušení bezpečnostních předpokladů X3DH. Opraveno: consume_one_time_prekey() a get_key_bundle() nyní používají SELECT ... FOR UPDATE + DELETE v jedné transakci (součást multi-device implementace).

H13. Neautentizované get_user_info + identity key exfiltrace (server.py)

get_user_info je dostupné bez přihlášení a vrací username, email a identity_key pro libovolný email/user_id. Umožňuje enumeraci uživatelů a sběr metadata/klíčů. Řešení: Vyžadovat auth, nebo omezit na "kontakty v konverzaci".

H14. TLS_INSECURE umožňuje MITM i v produkci (chat_core.py, server.py) ✅ OPRAVENO

TLS_INSECURE=true vypíná verifikaci certifikátu → útočník může podvrhnout key bundle. Přímo ohrožuje E2EE integritu. Opraveno: TLS_INSECURE vyžaduje ENVIRONMENT=dev, jinak RuntimeError. Součást H2 fixu.

M11. Pairing poll DoS — neautentizovaný přístup k payload (server.py) ✅ OPRAVENO

Kdokoli s 8-místným kódem může pollovat a "vyzvednout" payload (smazán po vyzvednutí). I když je šifrovaný, jde o snadný DoS (reálnému zařízení pairing selže). Opraveno: handle_pairing_start generuje poll_token (secrets.token_hex(16)), vrací klientovi. handle_pairing_poll vyžaduje poll_token a porovnává přes secrets.compare_digest(). Klient ukládá token v pairing_start() a posílá v pairing_wait().

M12. Upload end bez validace received_bytes == file_size (server.py) ✅ OPRAVENO

upload_image_end neověřuje, že received_bytes == file_size. Může zůstat nedokončený/nevalidní soubor. Řešení: Kontrola délky před complete_image_upload.

M13. Klíčové adresáře bez chmod 700 (chat_core.py)

get_key_dir a podadresáře (sessions, sender_keys, opk_private) se vytvářejí bez explicitních práv; spoléhá se na umask. Řešení: Po mkdir vždy chmod 0o700 pro adresář, 0o600 pro soubory.

L8. Phantom users — DB inflation (server.py, db.py) ✅ OPRAVENO

find_conversation vytváří phantom usery pro libovolné emaily. I s rate limit lze DB časem nafouknout. Opraveno: _valid_email() validace před vytvořením phantomu. db.cleanup_stale_phantoms(30) v periodic cleanup — maže phantomy starší 30 dní bez aktivních konverzací s reálnými uživateli.

Bezpečnostní matice (souhrn)

Soubor	CRITICAL	HIGH	MEDIUM	LOW
protocol.py	1 (C1)	2 (H5, H6)	0	1 (L5)
crypto_utils.py	1 (C2)	0	3 (M1-M3)	2 (L1, L2)
server.py	2 (C5, C6)	3 (H3, H7, H13)	4 (M4, M8, M11, M12)	0
chat_core.py	2 (C3, C4)	4 (H1, H2/H14, H8, H9)	2 (M9, M13)	1 (L6)
gui_client.py	0	2 (H10, H11)	0	2 (L3, L7)
db.py	0	1 (H12)	3 (M6, M7, M10)	2 (L4, L8)
Celkem	6	12	12	8
Opraveno	6 (C1, C2, C3, C4, C5, C6)	11 (H1, H2, H3, H4, H5, H6, H7, H8, H10, H11, H12, H13, H14)	11 (M2, M3, M4, M5, M6, M8, M9, M10, M11, M12, M13)	1 (L8)
Zbývá	0	1	1	7

Doporučené pořadí oprav (aktualizováno)

1. C6 ✅ — Path traversal přes file_id — DONE (UUID validace + is_relative_to)
2. C1 + C2 + C5 ✅ — DoS vektory — DONE (LimitOverrunError → ValueError, MAX_SENDER_KEY_SKIP 256, upload completeness check)
3. H12 ✅ — OPK race condition — DONE (SELECT FOR UPDATE, součást multi-device)
4. C3 + H1 + H7 + M13 ✅ — Šifrování dat na disku + file/dir permissions + avatar path traversal — DONE
5. H2/H14 ✅ — TLS hardening (TLS_INSECURE + TLS_AUTOGEN vyžadují ENVIRONMENT=dev, warning log) — DONE
6. H5 + H6 ✅ — Error handling v protokolu (base64, JSON) — DONE
7. H3 + H13 ✅ — User enumeration (generické odpovědi, auth pro get_user_info) — DONE
8. H4 ✅ — Race conditions (asyncio.Lock) — DONE
9. H8 + H10 + H11 ✅ — Paměť hesel, image parsing, filename sanitizace — DONE
10. M2 + M8 + M10 + M11 ✅ — Hardening batch (HKDF salt, UUID validace, message_ids cap, pairing poll token) — DONE
11. M3, M4, M9 ✅ — PBKDF2 600k iterations, SPK rotace 7 dní s grace period, ratchet state rollback — DONE
12. M1, M6, M7 — Remaining hardening (Ed25519 serialization, TOCTOU ✅, MySQL TLS)
13. Penetrační testy — manuální + automatizované security testy

Důležitá rozhodnutí a kontext

• Invitations replace direct add for groups: handle_add_member and handle_create_conversation (for groups) now create invitations instead of directly adding members. DMs still auto-add both users. This was a design decision to give users control over joining groups.
• Group delete = total destruction: When creator deletes a group, ALL members are removed and the conversation is fully deleted. This is different from "leave group" which only removes the leaving user.
• DM delete is per-user: Deleting a DM only removes the deleting user. The other user still sees the conversation until they also delete it.
• Avatar caching in GUI is pixmap-based: _avatar_cache and _group_avatar_cache store QPixmap objects, not raw bytes. The _on_avatar_for_conv_list and _on_group_avatar_for_conv_list signals convert bytes → QImage → QPixmap on receipt.
• No context menu on conversation list anymore: Delete was the only action. Now handled by header buttons. conv_list.setContextMenuPolicy(DefaultContextMenu).

Environment Variables

See README.md for full list. Key: SERVER_HOST, SERVER_PORT, MYSQL_*, TLS_*, SMTP_*, LOG_LEVEL, MAX_INPUT_CHARS, UPLOAD_DIR, MAX_IMAGE_BYTES, MAX_FILE_BYTES, MAX_MESSAGE_BYTES, METADATA_RETENTION_DAYS (default 90).

Commands & Workflow

• Start server: python server.py
• Start GUI client: python gui_client.py
• Start CLI client: python client.py
• Environment: .env file in project root (loaded by dotenv)
• Dependencies: PyQt6, mysql-connector-python, cryptography, Pillow (for image sharing), python-dotenv
• Check syntax: python3 -m py_compile <file>.py
• All files on both server AND client side: crypto_utils.py, protocol.py, chat_core.py, gui_client.py (or client.py)