diff options
Diffstat (limited to 'docs/CHAT-APPLICATION.txt')
| -rw-r--r-- | docs/CHAT-APPLICATION.txt | 79 |
1 files changed, 56 insertions, 23 deletions
diff --git a/docs/CHAT-APPLICATION.txt b/docs/CHAT-APPLICATION.txt index 7e58051..28c576b 100644 --- a/docs/CHAT-APPLICATION.txt +++ b/docs/CHAT-APPLICATION.txt @@ -16,9 +16,10 @@ along with this program. If not, see <https://www.gnu.org/licenses/>. EXPERIMENTAL PRIVATE CHAT - Branch: feature/private-chat. This application is for local testing. - Production remains on main with its under-construction Message Me page. - No public chat service, TLS route, or new production identity was deployed. + Available on main. Direct development and a prebuilt Podman/HTTPS + deployment path are implemented. See CHAT-PRODUCTION.txt for the release, + production setup, and recovery procedure; feature work does not itself merge + main or activate the VPS. This is working experimental software, not an independently audited messenger. WHAT EXISTS @@ -28,6 +29,13 @@ WHAT EXISTS a capability-limited WASI host. Text is displayed through textContent. SearXNG and the other existing services are unchanged. + Startup shows an ASCII download bar, percentage, and received/total MiB + while fetching the cryptographic module. If its size is unavailable, it shows + received MiB. A 45-second gap without download progress aborts with a reload + instruction; slow transfers continue while bytes arrive. After download, + a separate status identifies the connection to chat. No browser cache or + storage was added. + Visitors choose CREATE NEW CHAT or OPEN CHAT FILE. Creation generates a purpose-specific identity locally and downloads its protected file. Reopening the exact downloaded file and entering its password is required before the @@ -49,7 +57,7 @@ WHAT EXISTS LOCAL PREREQUISITES AND COMMANDS - Start in the root of the stack repository on feature/private-chat. Native + Start in the root of the stack repository on main. Native development needs Rust, libclang, OpenSSL 3.5 or newer development libraries, a C compiler, pkg-config, make, Perl, curl, and tar. The checked configuration uses OpenSSL 3.6.5. The WASI build script currently targets an x86_64 GNU/Linux @@ -97,12 +105,11 @@ LOCAL PREREQUISITES AND COMMANDS Stop the development server with Control-C. A server restart invalidates all sessions but preserves identities, conversations, counts, and ciphertext. - The server currently refuses a non-loopback bind or an origin that does not - exactly match its development bind address. HTTP is allowed only for the - explicit loopback development origin. The intended production origin remains - https://chat.doan.luuduct.ai/. Production Podman packaging, TLS configuration, - operational review, and a main-branch merge remain separate work. Do not - expose this experimental development service through a public proxy. + The direct development server refuses a non-loopback bind or an origin that + does not exactly match its development bind address. Packaged production uses + a private container listener behind Caddy HTTPS, with an explicit external + CHAT_HOST/HTTPS_PORT origin. Forwarded request headers do not choose that + origin. Do not expose the direct development server through a public proxy. OWNER FILE LOSS AND BACKEND RESET @@ -116,9 +123,11 @@ OWNER FILE LOSS AND BACKEND RESET Run these commands locally at the stack root for the current development build. There is no reset operation in the HTTP API. Filesystem access to - the private chat directory is the administrative boundary. A future production - package must expose the same options through its prebuilt server binary; - do not install Rust on the VPS for these development commands. + the private chat directory is the administrative boundary. Production uses + ./bin/stack chat --owner-fingerprint and ./bin/stack chat --reset-owner + through an isolated maintenance container. Stop production with ./bin/stack + down first; restart with ./bin/stack up --production. No Rust is needed on + the VPS. See CHAT-PRODUCTION.txt before a destructive reset. Read the current public fingerprint, even if you have lost the private file: @@ -130,8 +139,8 @@ OWNER FILE LOSS AND BACKEND RESET cargo stack chat --reset-owner PASTE_CURRENT_OWNER_FINGERPRINT_HERE A fingerprint mismatch refuses without deleting data. The server and reset - process share a filesystem lock; reset also requires the loopback service - port to be free. This prevents resetting a running service, including a + process share a filesystem lock. Direct development additionally requires + the loopback service port to be free. This prevents resetting a running service, including a development process launched before the lock was added. Online snapshots and reading the public owner fingerprint remain available while chat is running. @@ -158,11 +167,24 @@ FILE AND MESSAGE CRYPTOGRAPHY a fixed purpose-only user ID. Names are not placed in public certificate IDs. The server rejects uploaded secret-key material and unsupported certificates. - The JSON identity file is an authenticated encrypted envelope. Its fixed - format identifier is authenticated as associated data: + New JSON identity files are indented and use an array of 80-character + Base64 ciphertext chunks; the final chunk may be shorter. JSON indentation, + quotes, and commas are additional to the ciphertext width. The reader joins + the chunks before Base64 decoding. No private fields become plaintext. + This is the application's own JSON envelope, not OpenPGP ASCII armor. + The new file-format identifier is authenticated as associated data: + + stack-chat-file/v2;argon2id-m65536-t3-p1;aes256-gcm + + Existing compact v1 files with one ciphertext string remain supported: stack-chat-file/v1;argon2id-m65536-t3-p1;aes256-gcm + v1 uses its original identifier as associated data. Changing a version label + or converting its field shape does not convert a file: the authentication tag + binds the version. No existing file needs rewriting; old readers do not support + new v2 exports. Cryptographic algorithms and KDF parameters are unchanged. + Argon2id version 0x13 uses 65536 KiB, three passes, one lane, and a 32-byte derived key. A fresh CSPRNG salt of 16 bytes and AES-256-GCM nonce of 12 bytes are generated for each file; the authentication tag is 16 bytes. These KDF @@ -287,7 +309,8 @@ BACKUP, EXPORT, AND RESTORE SQLite's online backup API for chat.sqlite. It does not copy a live SQLite file or journal with ordinary file-copy code. It can take a consistent chat snapshot while the local chat server runs. Existing Podman data still follows - the stack's previous pause/copy/resume process. A database snapshot is atomic + the stack's pause/copy/resume process; the chat container stays unpaused. + Separate snapshots cover both chat and chat-local. A snapshot is atomic for chat data; unrelated services do not share a global transaction with it. The backup includes the single root .env and must remain private/encrypted. @@ -339,6 +362,11 @@ LICENSES, SOURCE, AND VERIFICATION The local check used Alpine musl 1.2.6 headers with the host C compiler for the C object build and Rust's self-contained musl runtime for final linking. + The rendered dependency-license page is centralized on the main website at + https://doan.luuduct.ai/THIRD-PARTY-LICENSES.html. Chat links point there; its + previous local license-page URL redirects there. cgit keeps ordinary source + and raw-file views without a custom HTML renderer. + First-party software is GNU AGPL version 3 or later. Legal license headers are the exception to the no-comments convention. Documentation is plaintext. JavaScript has GNU LibreJS @license/@license-end markers and a linked @@ -368,14 +396,17 @@ LICENSES, SOURCE, AND VERIFICATION cargo stack check PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node crates/chat-crypto/tests/browser.mjs PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node crates/chat-server/tests/browser.mjs + PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node crates/chat-server/tests/progress.mjs Browser automation additionally needs Node, Playwright under .tools/browser, and its browser downloads under .tools/browsers. These are development tools excluded from releases. The fixtures use temporary isolated installation roots with one temporary .env each, and remove their private data on completion. They listen on loopback port 9081 by default (override with CHAT_TEST_PORT), - leaving the normal local preview on 9080 available. They do not initialize - your real owner identity or touch production. + leaving the normal local preview on 9080 available. The optional packaged + HTTPS variant is documented in CHAT-PRODUCTION.txt and retains its disposable + installation roots for inspection. Tests do not initialize the real owner + identity or touch the VPS. LibreJS verification uses the Mozilla-distributed GNU LibreJS 7.21.1 in Playwright Firefox 157.0, without whitelisting the application. The full chat @@ -402,9 +433,11 @@ LICENSES, SOURCE, AND VERIFICATION live database snapshot restoration with both original identity files, owner setup/access controls, refusing reset while running or with a mismatched fingerprint, successful backend reset and fresh registration, rejecting old - visitor key pins, in-flight - lock, back/forward restoration, and checks for plaintext persistence or private - credential uploads. + visitor key pins, in-flight lock, back/forward restoration, and checks for + plaintext persistence in the database/journals or private credential uploads. + The packaged variant additionally verifies certificate trust/hostname through + curl, restrictive export permissions, and full encrypted recovery with saved + images and no build directories inside the recovered installation. Native tests cover authorization, challenge reuse, expiry, locked sessions, quotas, idempotency, and SQLite snapshot recovery. See CHAT-DESIGN.txt and CHAT-OPENSSL-MIGRATION.txt for the design and historical backend review. |