2e7b72307d
E2E encrypted chat (X3DH + Double Ratchet, Signal Protocol). Server: asyncio TCP + TLS, MySQL. Clients: PyQt6 GUI + CLI. Secrets (.env, TLS keys, Cloudflare token), runtime data and mobile clients (separate repos) are gitignored. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2.8 KiB
Repository Guidelines
Project Structure & Module Organization
The main Python modules live in the repository root. server.py contains the asyncio TCP server, request handlers, rate limiting, and upload flows. chat_core.py holds shared client logic, crypto workflows, and local key handling. client.py is the CLI, gui_client.py is the PyQt6 GUI, db.py is the MySQL layer, protocol.py defines the newline-delimited JSON protocol, and crypto_utils.py contains X3DH, Double Ratchet, Sender Keys, and local encryption helpers. Use schema.sql for a clean database bootstrap. Security and architecture notes are tracked in SECURITY_AUDIT.md, README.md, scaling.md, and CLAUDE.md. Put new test tooling under tests/. Treat zaloha/ as archive code, not an active source directory.
Build, Test, and Development Commands
Use the project virtualenv and MySQL schema:
.venv/bin/pip install -r requirements.txt
mysql -u <user> -p < schema.sql
.venv/bin/python server.py
.venv/bin/python client.py
.venv/bin/python gui_client.py
For quick validation, run:
.venv/bin/python -m py_compile server.py chat_core.py client.py gui_client.py db.py
.venv/bin/python tests/pentest_client.py --server-host <tls-host> --member-email ... --peer-email ... --outsider-email ...
There is no full pytest suite yet; current regression coverage is mainly protocol-level through tests/pentest_client.py.
Coding Style & Naming Conventions
Follow existing Python conventions: 4-space indentation, snake_case for functions and variables, PascalCase for classes, and type hints on new or changed code. Keep handlers non-blocking: DB, file, or SMTP work that can block should be moved behind async helpers or asyncio.to_thread(). Reuse central validation helpers instead of duplicating checks, and keep logs free of secrets, emails, or raw user-controlled text where possible.
Testing Guidelines
Add tests in tests/ with descriptive names. Prefer test_<feature>.py for focused checks and <scenario>_client.py for protocol or penetration probes. Every security fix should include a regression path that covers malformed input, authorization, replay, rate limiting, or multi-device behavior.
Commit & Pull Request Guidelines
Git history is not available in this workspace snapshot, so use short imperative commit messages. Conventional Commit style is preferred, for example fix: reject invalid ratchet headers. PRs should summarize behavior changes, mention schema or .env updates, link related issues, and include CLI or GUI evidence for user-visible changes.
Security & Configuration Tips
Do not commit .env, TLS private keys, uploaded files, or local key material from ~/.encrypted_chat/. When testing TLS, remember that 0.0.0.0 is a server bind address, not a valid client hostname. Use a host or IP that matches the certificate SAN or CN.