ios_client

AGENTS.md

@@ -0,0 +1,42 @@
+# 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:
+
+```bash
+.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:
+
+```bash
+.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.