diff options
Diffstat (limited to 'docs/CHAT-DESIGN.txt')
| -rw-r--r-- | docs/CHAT-DESIGN.txt | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/CHAT-DESIGN.txt b/docs/CHAT-DESIGN.txt new file mode 100644 index 0000000..7b2a14f --- /dev/null +++ b/docs/CHAT-DESIGN.txt @@ -0,0 +1,120 @@ +Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai> + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. + + +PRIVATE CHAT DESIGN AND LIMITATIONS + + Status: planned application; only the cryptographic compatibility probe + currently exists. This document is a specification, not a completion claim. + Work remains on feature/private-chat. Nothing is deployed to production. + +USER EXPERIENCE + + Entry offers CREATE NEW CHAT and OPEN CHAT FILE. Creation asks for a display + name and password, generates a dedicated identity locally, and downloads one + protected file. The user must reopen that file before sending a first message. + Returning users select the file locally and unlock it with its password. + Usernames are labels; cryptographic identities determine access. + + Show authenticated total, sent, and received message counts. Let the user + select N recent messages, including zero, and page backwards for older ones. + Sending never requires an updated identity file. Scope is text only between + each visitor and Doan, with no public directory, attachments, or group chats. + + Intended host: https://chat.doan.luuduct.ai/ with API under /api/ on the same + origin. It is not configured or deployed yet. The feature branch adds Message + Me links below the name in the home-page box and after Services in navigation. + +CRYPTOGRAPHY AND FILES + + Fixed encryption: RFC 9980 ML-KEM-1024 + X448 with OpenPGP v6 keys. + Test signing profile: ML-DSA-87 + Ed448. Dedicated application identities must + remain separate from Doan's canonical RSA identity. Advise users not to reuse + chat identities elsewhere; exported keys cannot be technically restricted to + this application alone. Future authentication signatures must bind to the + application, origin, conversation, operation, fresh nonce, and expiry. + + The intended chat file contains versioned recovery and identity data, server + identity, and a pinned owner public-key fingerprint. Its exact protected file + format is not finalized. The compatibility probe protects OpenPGP secret-key + material; it does not implement the proposed complete chat-file envelope. + Private keys and passwords must never be uploaded to the server or placed + in a URL, log, analytics event, crash report, or application browser storage. + + Both participants need access to their own stored conversation. The browser + signs and encrypts each message for both participants. The plaintext payload + binds the conversation, sender, unique message ID, and protocol version. + Display names can travel inside encrypted conversation details. + +STATE AND LIMITS + + No intentional persistent browser chat state: no cookies, localStorage, + sessionStorage, IndexedDB, service workers, analytics, or third-party requests. + Keep keys, passwords, session credentials, and loaded history in memory only. + Serve chat content with Cache-Control: no-store. Reload, close, and leave + require the file and password again. Clear references and zero mutable secret + buffers where possible; JavaScript strings and browser/OS copies are not + reliably erasable. Test page restoration and back/forward navigation. + + The downloaded identity file is the intentional persistent client artifact. + Browsers and operating systems may retain memory, swap, crash dumps, download + records, or restored pages. The application cannot promise literally zero + traces. The current browser probe checks only its own limited test behavior. + + The VPS necessarily retains ciphertext, public-key associations, message IDs, + ordering, counts, and authentication state. Connection addresses, timing, and + ciphertext sizes are visible while serving requests. Avoid retaining these + in application/access logs. Storage and encrypted backups require consistent + database snapshots and a tested recovery procedure before actual chat use. + + The private file is a credential. A lost file/password has no username-based + recovery. A copied unlocked identity enables impersonation and historical + decryption. Rotation can protect future use but cannot undo historical + ciphertext or key copies. Static OpenPGP does not automatically provide + forward secrecy. Compromise of a shared owner key can affect every + conversation encrypted to that key. + + The browser trusts served code, including WASM and generated JavaScript. + A compromised server, dependency, extension, browser, or OS may expose keys + or plaintext. A pinned key does not defeat a malicious application update + or solve first-visit trust. A separate origin limits ordinary cross-origin + access, not shared-host compromise or every cross-site attack. + +LIBREJS AND LICENSING + + First-party code is AGPL-3.0-or-later. Third-party licenses and notices remain + accurate. Required legal comments are the exception to the no-comments rule. + Supply machine-readable JS licensing and corresponding Rust/WASM/JS source. + Test actual LibreJS recognition, generated bindings, workers, and WASM before + displaying GNU LibreJS-compliant. The compatibility harness makes no such + claim and is not a public chat application. + + Intended badge: yellow, GNU LibreJS-compliant, linked to + https://www.gnu.org/software/librejs/ . Hover and keyboard focus explain: + + LibreJS compliance concerns software freedom, not a guarantee of privacy + or security. Review the source code, dependencies, and scripts delivered + to your browser. Server-delivered code can change between visits; free + software can still track users or behave maliciously. + +REMAINING RELIABILITY WORK + + Resolve the blocking review in CHAT-SECURITY-REVIEW.txt. Then implement and + test file creation/import, recovery confirmation, signed one-use challenges, + authorization, encrypted sends/replies, replay rejection, N=0 and pagination, + authenticated counters, quotas, rate limits, hostile file and packet limits, + plaintext-only display, session expiry, explicit lock, reload/restoration, + no network leakage, no persistent application storage, and complete backup + restoration. No application is ready merely because its crypto test passes. |