diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CHAT-APPLICATION.txt | 94 | ||||
| -rw-r--r-- | docs/CONFIGURATION.txt | 142 | ||||
| -rw-r--r-- | docs/GIT-HISTORY.txt | 85 | ||||
| -rw-r--r-- | docs/OPERATIONS.txt | 4 | ||||
| -rw-r--r-- | docs/POLICY.txt | 9 |
5 files changed, 320 insertions, 14 deletions
diff --git a/docs/CHAT-APPLICATION.txt b/docs/CHAT-APPLICATION.txt index 2a06649..7e58051 100644 --- a/docs/CHAT-APPLICATION.txt +++ b/docs/CHAT-APPLICATION.txt @@ -37,7 +37,11 @@ WHAT EXISTS and inbox; the canonical RSA OpenPGP key is not used for chat encryption. History defaults to zero messages. Authenticated counters show total, sent, - and received messages. Load 0 to 50 recent messages, then page backwards. + and received messages. Choose 0 to N recent messages, where N is the current + conversation total, or page backwards for older messages. Counts refresh when + the history input is focused, history is requested, or a send is acknowledged. + Large selections are fetched and verified in batches of at most 50; that is + a per-request resource bound, not a user-visible 50-message selection limit. Reload, lock, or leaving clears the application's in-memory references and visible messages. A separate authenticated session expires after 30 minutes. There is no automatic background polling, notification, or remote logout. @@ -63,6 +67,8 @@ LOCAL PREREQUISITES AND COMMANDS .env, creating it privately if necessary. It refuses to overwrite an existing setup token. The root .env.example lists both settings. Never commit .env. Existing SearXNG settings stay in the same file. No crate has its own .env. + CHAT_BIND and public navigation now use the shared root configuration loader; + see CONFIGURATION.txt for the documented deployment keys. For subsequent Rust-only edits, sh infra/chat/build-browser.sh reuses the previously built, hash-verified OpenSSL/SDK inputs. Rebuild OpenSSL itself @@ -73,15 +79,16 @@ LOCAL PREREQUISITES AND COMMANDS cargo stack chat - Open: - - http://127.0.0.1:9080/#setup + Open http://127.0.0.1:9080/ and choose OWNER SETUP, labeled for the owner + only. The direct http://127.0.0.1:9080/#setup link also works. Read CHAT_SETUP_TOKEN from your root .env locally and paste it into the owner setup form. Choose an owner display name and a strong unique password. Save the downloaded file, reopen it, and unlock it. That establishes the owner public identity. The setup token stops authorizing setup once an owner exists. - It does not become an owner login or a key recovery mechanism. Never publish + It does not become an owner login or a key recovery mechanism. OWNER SETUP + stays visible; once an owner exists, it explains how to open the existing + owner file or reset after loss instead of silently replacing the key. Never publish the owner private file or its password. Keep both in your private KeePassXC database, along with a separately protected backup of that database. @@ -97,6 +104,52 @@ LOCAL PREREQUISITES AND COMMANDS operational review, and a main-branch merge remain separate work. Do not expose this experimental development service through a public proxy. +OWNER FILE LOSS AND BACKEND RESET + + A setup token grants registration permission. It cannot recover the private + key inside a lost owner file. If that file and its backups are gone, existing + messages cannot be decrypted with a newly generated identity. The reset below + intentionally starts a fresh chat service and clears all stored messages, + encrypted profiles, conversations, counters, and the owner registration. + It preserves the root .env and any previously exported backup archives. + It does not claim forensic erasure of backups, snapshots, or OS copies. + + 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. + + Read the current public fingerprint, even if you have lost the private file: + + cargo stack chat --owner-fingerprint + + Stop the chat server with Control-C in its terminal, then explicitly pass + that full fingerprint to the destructive reset command: + + 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 + development process launched before the lock was added. Online snapshots and + reading the public owner fingerprint remain available while chat is running. + + Restart: + + cargo stack chat + + Choose OWNER SETUP and use the existing CHAT_SETUP_TOKEN from the same root + .env to generate, save, and reopen a fresh owner file. Back that file and its + password up in KeePassXC. Visitors must create fresh chat files too: their + previous files pin the former owner key and are correctly rejected after + replacement. A reset cannot prove continuity with the lost key. + + If an old owner file is found later, an old encrypted backup may still allow + recovering its original conversations in an isolated restored installation. + The reset does not remove existing exported archives, and it never substitutes + a new key into old ciphertext or old visitor files. + FILE AND MESSAGE CRYPTOGRAPHY OpenPGP v6, ML-KEM-1024 + X448 encryption, ML-DSA-87 + Ed448 signatures, @@ -178,7 +231,7 @@ AUTHENTICATION AND STORAGE Send retries are deliberate; messages are not automatically resent. Limits: 8192 UTF-8 bytes per text, 16384 bytes per signed payload, 65536 base64 - characters per stored ciphertext, 50 history rows per request, 1000 visitor + characters per stored ciphertext, 50 history rows per API request, 1000 visitor identities, 10000 messages per conversation, and a one-billion-character total message-ciphertext budget. At most 60 authentication challenges per global minute window, 128 pending challenges, 256 active sessions, and four @@ -187,7 +240,8 @@ AUTHENTICATION AND STORAGE protection against determined traffic, account creation, CPU, or disk attacks. Public-key and profile storage, indexes, journals, and backups add overhead to the ciphertext budget. Monitor actual disk use. No public abuse controls, - deletion UI, rotation UI, blocklist, or password-change UI are implemented. + deletion UI, in-place key rotation UI, blocklist, or password-change UI are + implemented. Lost-owner recovery uses the explicit backend reset above. BROWSER STATE AND LIMITATIONS @@ -263,6 +317,20 @@ BACKUP, EXPORT, AND RESTORE archive. Deleting a message locally or losing a file does not delete stored ciphertext, old exports, or other participants' copies. +INTERFACE AND SITE STYLE + + The interface follows web/styles.css and the previous www/message.html and + www/form.css from the parent of e373f15, the commit that removed the original + Message Me form. It reuses the red ASCII logo, 80-column desktop width, + black/white light and dark themes, blue links, green prompts/actions, ASCII + form frames, and bracketed controls. Licensing links retain the main site's + amber and muted green accents. The LibreJS badge stays yellow with its + keyboard-accessible warning. Small screens keep readable form controls and + fit the ASCII rules to the available width instead of shrinking all text. + Scrolling belongs to the root viewport at the screen edge; the logo has no + inner scroll container. JavaScript licenses sit below the LibreJS badge. + No remote fonts, images, or additional scripts are required. + LICENSES, SOURCE, AND VERIFICATION Portable root CLI builds now also need a musl C compiler because consistent @@ -305,7 +373,9 @@ LICENSES, SOURCE, AND VERIFICATION 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 do not initialize your real owner identity or touch production. + 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. LibreJS verification uses the Mozilla-distributed GNU LibreJS 7.21.1 in Playwright Firefox 157.0, without whitelisting the application. The full chat @@ -326,9 +396,13 @@ LICENSES, SOURCE, AND VERIFICATION The crypto browser probe fails closed without browser CSPRNG entropy and on unknown WASI imports. The application browser test uses real WASI/OpenSSL cryptography, protected file downloads and reopen, incorrect passwords, - signed sends/replies, safe text display, counts, zero-history, pagination, + signed sends/replies, safe text display, counts, zero-history, loading all + 54 fixture messages through 50+4 batches, pagination, lost-response retry deduplication, reload, explicit lock, origin rejection, - live database snapshot restoration with both original identity files, in-flight + 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. Native tests cover authorization, challenge reuse, expiry, locked sessions, diff --git a/docs/CONFIGURATION.txt b/docs/CONFIGURATION.txt new file mode 100644 index 0000000..9660e20 --- /dev/null +++ b/docs/CONFIGURATION.txt @@ -0,0 +1,142 @@ +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/>. + +CENTRAL CONFIGURATION + + Each installation has one root .env for deployment settings and secrets. + The published .env.example documents every supported setting with public + defaults, private placeholders, and comments. Hostnames are public information; + this arrangement centralizes configuration, not secrecy or access control. + Public values remain visible in generated pages, DNS, certificates, and URLs. + + Existing installations keep their configured secrets and settings. Missing + public defaults are appended to the same .env by cargo stack config, service + initialization, or chat initialization. No second environment file is created. + The example is also the shared Rust configuration library's default source, + so missing public settings remain compatible with older exports. + +PUBLIC SETTINGS + + BASE_DOMAIN + Root web/WKD domain. www aliases are derived from each configured host. + + SITE_HOST, GIT_HOST, SEARCH_HOST, WKD_HOST, CHAT_HOST + Fully qualified DNS names without schemes, paths, or ports. The first + four configure production Caddy routing. CHAT_HOST supplies the intended + public chat link; production chat routing remains unimplemented on this + experimental feature branch. + + HTTP_PORT, HTTPS_PORT + Production Caddy listener and Podman published ports. HTTPS also publishes + UDP for HTTP/3. Defaults are 80 and 443. Generated HTTPS links include a + nonstandard HTTPS port when configured. Ordinary public certificate + validation still needs the CA's standard external validation ports or an + appropriate alternative certificate/routing arrangement. Setting ports + alone does not configure DNS, firewall rules, or external port forwarding. + + LOCAL_HTTP_PORT + Local Caddy HTTP port on 127.0.0.1. HTTPS host port is this value plus one. + Local Caddy still listens on container ports 80/443. --port overrides the + local port for that invocation. Existing installation/project names and + image state remain in var/state.json; an explicit .env local port takes + precedence over the previously saved port. + + CGIT_UPSTREAM, SEARXNG_UPSTREAM + Proxy connection targets such as cgit:8080 and searxng:8080. These are + addresses, not upstream bind settings. The bundled images' internal 8080 + listeners and health checks remain image contracts. Changing a target + to another host/port requires an actual service at that address. + + CHAT_BIND, CHAT_ORIGIN + Chat socket and exact browser origin. Default: 127.0.0.1:9080 and + http://127.0.0.1:9080. The experimental server requires loopback and an + exact HTTP origin match. --bind overrides CHAT_BIND for testing. + Identity files pin their origin; editing these values does not migrate + encrypted identities or grant access on another origin. + + BACKUP_RECIPIENT, BACKUP_PUBLIC_KEY + Public OpenPGP fingerprint and project-relative public key path used for + encrypted exports. --recipient and --key override them. The secret GnuPG + key and revocation certificate remain outside the project. + +PRIVATE SETTINGS + + SEARXNG_SECRET + Generated on first stack initialization. Existing values are preserved. + + CHAT_SETUP_TOKEN + Generated by cargo stack chat --init. Used only to authorize first owner + registration, including a fresh registration after an explicit backend + reset. It cannot recover a lost owner private key. + +RENDER AND APPLY + + Edit .env locally. Never commit or publish it. Inspect the commented example + for exact keys. Hostnames, ports, socket addresses, fingerprints, and paths + are validated before use. Diagnostic formatting never dumps the config map. + Invalid environment-file syntax is reported without echoing its raw contents. + + Render public deployment files without starting services: + + cargo stack config + cargo stack config --production + + Outputs are var/local/ or var/production/: + + Caddyfile + cgitrc + web/ + + infra/Caddyfile, infra/Caddyfile.local, infra/containers/cgit/cgitrc, and the + first-party website HTML are templates using {{PUBLIC_KEY}} placeholders. + Do not run Caddy directly on an unrendered template. Podman mounts the generated + files. Public host/origin changes reach Caddy routes, www redirects, website + links, the cgit clone prefix, and the chat page's navigation. Local rendering + uses /git and /search paths and the configured local chat origin. + + To apply changes to the existing services: + + cargo stack up --local + + Production uses its prebuilt management command and images: + + ./bin/stack up --production + + Rendered website files can be read by an already running file server, while + listeners, container environment, and loaded Caddy configuration require the + service update above. Restart the local chat server with cargo stack chat to + load its new bind, origin, or public navigation settings. Reopen your identity + file afterward, as with any chat restart. + +PUBLICATION AND LIMITS + + The shared stack-config crate uses an explicit public allowlist for template + substitution. A {{CHAT_SETUP_TOKEN}} or other private/unknown placeholder + causes an error rather than publishing its value. Generated public pages and + proxy configuration never receive a full environment dump. Each container + still receives only the environment keys listed for that service; Caddy uses + rendered public configuration and does not need the .env or private tokens. + + The root .env, runtime files, local render outputs, exports, and tool caches + remain ignored by Git. Source templates, the commented example, validated + defaults, and this configuration implementation are public. Full encrypted + backups include the single .env; source-only releases do not include it. + + Personal content and attribution remain source content: copyright headers, + author names, canonical contact information, public key material/WKD hashes, + project repository metadata, and GNU license links. Changing a deployment + hostname does not create a new email identity or regenerate WKD keys. + Image digests, source hashes, and fixed crypto/protocol/resource bounds remain + reviewed reproducible code/configuration rather than private deployment knobs. diff --git a/docs/GIT-HISTORY.txt b/docs/GIT-HISTORY.txt new file mode 100644 index 0000000..2dfc335 --- /dev/null +++ b/docs/GIT-HISTORY.txt @@ -0,0 +1,85 @@ +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/>. + +GIT IDENTITY AND SIGNATURE REWRITE + + Requested to replace the historical ops <ops@localhost> identity with + Doan Luu Duc Tai <doan@luuduct.ai> and sign the history with the canonical + RSA-2048 key 3346AA3150F8F16828BB0D14F8C66DF77AFECEA6. + + Ten historical author identities and their corresponding committer identities + were corrected. All 27 commits reachable from main and feature/private-chat + at the time of the rewrite were recreated and signed because rewritten + parents change descendant commit IDs. Every new signature was verified. + + Every corresponding tree, message, original author timestamp/time zone, and + original committer timestamp/time zone was preserved. Merge topology was + preserved. Signature creation times reflect the new signing operation. + main's file tree is unchanged. Configuration/chat development stays on + feature/private-chat; rewriting metadata does not deploy that code to main. + + Remote updates use an atomic push and exact force-with-lease expectations + for both branches, preventing overwrite of an unexpected remote update. + Existing objects and reflogs may still contain old IDs: this is an authorship + correction, not a claim of private-data removal or historical erasure. + +EXISTING CLONES + + The active development checkout is already aligned. Other clones must fetch + the new history instead of using an ordinary pull across divergent histories. + Preserve local-only commits and working changes first. A fresh development + clone is also possible; keep private .env and runtime data out of Git. + + For an existing clone with no local-only commits: + + git fetch origin + git switch main + git reset --keep origin/main + + For a feature checkout, use feature/private-chat in the final two commands. + --keep refuses updates that would overwrite conflicting working changes. + Do not blindly reset a clone with independent local work; use the mapping + below to identify the corresponding rewritten base before rebasing that work. + Git changes do not remove or replace ignored .env or var/ data. + +ORIGINAL TO REWRITTEN COMMITS + + 47fcc566884d7078c153cdce9fb62399fcca5d9e c4b2f892a1c6508360a683c90e8c4d596c521336 + 37d5e4a152df67d247349d2ed289bf65859ead53 020d3454cad6619bf25c6ecb0a293502f40364bd + 8a327a41cdce40933b977f7c6662929488bcf83e 64a1b484abb96c91da9aa23e0e45576749f6cdfe + 3a8956f9cb85184ae2b8202d7a733124a0d3f95f 9599590f67c24f70c400b967d162095c63f6af61 + 2f5c323be4a44b80cf9e39d51210776146a77cbd 1632c88ba08c62966c1f0b1578741d8af007e6fd + 118ba081389cfd80b38c9c691fd6d75f6497dcb5 274e70679b83bcac3dee3599bd9389a3332462ec + 38aa5d1f2a8dfc8ea97c0fdce8feae7e37795533 5317fa43b79e4251fcbcff2b4f1243a961ac00fe + 902cfd395fb03d6147813560ac5fcd7146702a1d 463c6f48a06730c29f89b2f376e68dc805df5cc9 + e373f154dbeacc5a0e83b4ec73c3aa316239c029 5386a63bfb2f14cab99874e7c414e1a418b01f67 + 006a1e94075e90fccfe248cd66bf7d0586a86279 84960925108eb2b5950d4c299b15b18893e0c0d0 + 19a0280d7dabd4ca637d8070cc7d3691a0e85bd1 909dce458d4bbef6710c2b4a67cd906902bb7f3f + c06e29dae4bb290fd2849f69da1bfa940c5a8222 5bed750baa5d782427e98550d34124f569e2fff8 + 714866be200b882be437375006180456284bab1c 9c7dd654512b8f51af15d50dd75a515566723be7 + 9f070f7ad0952c61b4ee66d2a01ff1bdf7ade0a8 cad7ab1e1ab1dde8ff4ba349cd5b1a05bbd32b05 + faaac8558431c80a6b8fbcf2c8f17f16d8602ab6 1386bd16b0fd796314d9ad70aede0946bd5c46bd + 92bf96961c09d7df6b1bfea72eb8a107bcf9e221 d546193ee543a5b1a0a097d0a7deca76e81b7de2 + 0a0cdc0c44dd8b4fb44d8a859962c40c593e98eb f196233257d247c94550cf822b91bc3c9d8a7f8f + 1206813d47e8602f08cbeaf27e73453e089e7c52 834a21a7cadce64889856a2a7521440a1519e244 + d611c869eb12e7fff5754be31775f82200ec958b b46ece18a424eaea3f396ddae7e45e91d1c0e742 + 436e217c7858888702d2b6d9e655597ccadb7281 f196c27faf265cd14d8d7accf58e87b4df3c8a91 + 7a0ce2805258e8ac061202904379692d53d5dc95 cf2f0e8c6752c401f152a8e534ba166839d4307e + 774074bb2bbd3bc07f7094cdce0935eca7520725 a0057b13fa4b6bed8aee3132001e79a245efabc8 + 143880db086c617b843340ca7023a879507761f8 0a4da3b86eb69f0f09b802a55e36fa9cf1bbf38c + 556eaa133e9cfe7f4c8e542708119fdfd311357e e6b350a1d48ca0490b7a3447bb8d0a4235514b76 + b7374fe09306c495131cf3673addb76a1dcf017d 3034705b6679bff1802c4180b7b4711b94fed7f9 + be16d00a8a4750028073e018ab2c58d54af192c4 c3b361c45ac8dd898d5c83a161abed5fc138b6c0 + 28a772cab50b1064e317aedbe4689aea286b1ec4 6933ec28be3dac0dc17cd634c663db3b4818caad diff --git a/docs/OPERATIONS.txt b/docs/OPERATIONS.txt index 826c4cf..2cf4693 100644 --- a/docs/OPERATIONS.txt +++ b/docs/OPERATIONS.txt @@ -218,7 +218,9 @@ SET UP A NEW PRODUCTION HOST Point public A records to the new IPv4 address, and AAAA records only to a working new IPv6 address. Remove stale AAAA records. Public hostnames are - listed in infra/Caddyfile. Update canonical hosts there if changing domains. + configured in the root .env. Edit those values and reapply the service + configuration; infra/Caddyfile is now a public rendering template. + See CONFIGURATION.txt for all keys and the render-only commands. Keep the www aliases and openpgpkey names pointing to the canonical hosts. Start production: diff --git a/docs/POLICY.txt b/docs/POLICY.txt index 4c8d0bd..f662dd4 100644 --- a/docs/POLICY.txt +++ b/docs/POLICY.txt @@ -30,10 +30,13 @@ PROJECT CONVENTIONS documentation. The generated HTML license page is an explicit exception. Rust documentation attributes provide crate metadata without comments. - Keep configured secrets only in the root .env. Never commit .env or var/. + Keep deployment overrides and configured secrets in the single root .env. + Never commit .env or var/. Only the root .env.example is published; environment variants and nested - examples are ignored. .env.example lists required keys with placeholders. Public hostnames, - public GPG keys, paths, configuration, and source belong in Git. + examples are ignored. The commented .env.example publishes supported public + defaults and private placeholders. Public GPG keys, paths, templates, shared + configuration logic, and source belong in Git. Actual public hostnames remain + visible in rendered pages; .env centralization is not an access boundary. TLS account/certificate private keys, databases, and other generated private state are persistent data in var/data, not .env configuration. The GPG secret key and revocation certificate remain outside this project. |