diff options
Diffstat (limited to 'docs/CHAT-PRODUCTION.txt')
| -rw-r--r-- | docs/CHAT-PRODUCTION.txt | 183 |
1 files changed, 78 insertions, 105 deletions
diff --git a/docs/CHAT-PRODUCTION.txt b/docs/CHAT-PRODUCTION.txt index 03f5ba4..fdb48a6 100644 --- a/docs/CHAT-PRODUCTION.txt +++ b/docs/CHAT-PRODUCTION.txt @@ -16,70 +16,57 @@ along with this program. If not, see <https://www.gnu.org/licenses/>. PRODUCTION CHAT INTEGRATION - Implemented on main. - Building and testing a release does not activate the VPS. This is experimental software without an - independent cryptographic or application security audit. Read the limitations - in CHAT-APPLICATION.txt before using it for private conversations. - - Four services run through rootless Podman: Caddy, cgit, SearXNG, and chat. - The release contains statically linked x86_64 GNU/Linux management and chat - binaries, the WASM browser module, exact corresponding sources, and saved - native container images. The chat image starts FROM scratch: no compiler, - shell, package manager, or first-party Python. Its root filesystem is read - only, capabilities are dropped, and only its private data directory is writable. - - Caddy terminates HTTPS at CHAT_HOST and redirects www.CHAT_HOST while keeping - the requested path. CHAT_UPSTREAM defaults to chat:8080 on the private - container network. Chat publishes no host ports. Production publishes only - the gateway HTTP and TCP/UDP HTTPS ports. Existing host SSH policy is separate. - - The gateway supplies an explicit external origin selected from root .env. - The server accepts that exact HTTPS origin or the dedicated local gateway - origin. Forwarded client headers never select the trusted origin. Origin - checks supplement cryptographic authentication; they are not authentication. + Implemented on main. Builds/tests do not activate the VPS. Experimental; + no independent cryptographic or application security audit. Read + CHAT-APPLICATION.txt limitations before private use. + + Rootless Podman runs Caddy, cgit, SearXNG, and chat. Releases contain static + x86_64 GNU/Linux management/chat binaries, browser WASM, exact corresponding + sources, and native images. Chat starts FROM scratch: no compiler, shell, + package manager, or first-party Python. Root filesystem is read-only; + capabilities are dropped; only private data is writable. + + Caddy serves HTTPS at CHAT_HOST and redirects www.CHAT_HOST, preserving paths. + CHAT_UPSTREAM defaults to private chat:8080. Chat publishes no host ports; + only gateway HTTP and TCP/UDP HTTPS are published. Host SSH policy is separate. + + Root .env selects the explicit external origin. Chat accepts exactly that + HTTPS origin or the dedicated local gateway origin. Forwarded client headers + cannot select it. Origin checks supplement cryptographic authentication. BUILD ON THE WORKSTATION - Current releases require an x86_64 GNU/Linux build host and matching target. - Use the pinned Rust toolchain, Podman, Git, GnuPG, a GCC-compatible C compiler, - Linux UAPI headers, libclang, pkg-config, make, Perl, curl, tar, Node >=22.18.0, - and npm. Native - workspace checks need OpenSSL 3.5+ development libraries. Browser testing - additionally needs the pinned Playwright, Chromium, and Firefox. These tools remain - on the workstation; production does not need Cargo or a compiler. + Build host and target must be x86_64 GNU/Linux. Requires pinned Rust, Podman, + Git, GnuPG, GCC-compatible C compiler, Linux UAPI headers, libclang, pkg-config, + make, Perl, curl, tar, Node >=22.18.0, npm, and OpenSSL 3.5+ development libraries. + Browser tests also need pinned Playwright, Chromium, and Firefox. Workstation + tools stay local; production needs neither Cargo nor compiler. cargo stack release - This first builds/checks TypeScript, then runs formatting, strict Clippy, - all workspace tests, rustdoc, cargo-deny, - and cargo-about. It then builds static native binaries, the WASI module, - corresponding sources, the chat/cgit images, and the complete image export. - THIRD-PARTY-LICENSES.html is regenerated from the full workspace before - packaging. Check the archive checksum and test recovery before deployment. + Runs TypeScript build/checks, formatting, strict Clippy, workspace tests, + rustdoc, cargo-deny, and cargo-about. Builds static binaries, WASI, exact + sources, chat/cgit images, and complete image export. Regenerates workspace + THIRD-PARTY-LICENSES.html. Verify archive checksum and recovery before deployment. infra/chat/build-native.sh verifies OpenSSL 3.6.5's original source archive: a2157c2830efdec3788939b00c9b0638306d3f0bbb76dc4832ee503bb397df98 It verifies Alpine musl-dev 1.2.6-r3 headers: 310b51cff12e1d5ce5f135c558a82e2550427da5465bbd16c9ff9b05e63ee3d9 - Sources come from the official OpenSSL GitHub release and Alpine CDN. The - compiler uses isolated musl/GCC built-in headers plus host Linux UAPI headers; - glibc headers are excluded. OpenSSL is static, has no dynamic providers, and - seeds its RNG through getrandom. The native cryptographic compatibility probe - must pass after the build. WASI uses its separately verified SDK and OpenSSL - build recorded in CHAT-OPENSSL-MIGRATION.txt. No crypto algorithm was changed. - - Cached inputs live only under .tools/. Rebuild OpenSSL when its version, - source, or build flags change. An OpenSSL update requires reviewing upstream - security notices, updating every affected URL/hash, native and WASI rebuilds, - rerunning both browsers and cargo-deny, regenerating notices and exact source, - and repeating release recovery. Never approve a dependency advisory merely - to make the build pass. cargo-deny does not audit C/OpenSSL advisories. - - The source download includes first-party code, Cargo-vendored dependencies, - and unmodified OpenSSL source. Toolchain/sysroot development inputs are not - bundled as application sources. Saved images preserve the tested runtime. - An ARM host needs a separately supported native release; do not copy these - x86_64 binaries there and assume they will work. + Sources: official OpenSSL GitHub release and Alpine CDN. Compilation uses + isolated musl/GCC built-in and host Linux UAPI headers, excluding glibc. + Static OpenSSL has no dynamic providers and seeds through getrandom. The + native compatibility probe must pass. WASI uses separately verified SDK/OpenSSL + inputs in CHAT-OPENSSL-MIGRATION.txt. Cryptographic algorithms stay fixed. + + Inputs cache under .tools/. Version/source/flag changes require an OpenSSL + rebuild. Updates require upstream advisory review, every affected URL/hash, + native/WASI rebuilds, both browsers, cargo-deny, regenerated notices/sources, + and release recovery. Never waive advisories to pass. cargo-deny excludes C/OpenSSL. + + Source downloads include first-party code, Cargo-vendored dependencies, and + unmodified OpenSSL, excluding development toolchain/sysroot inputs. Saved + images preserve tested runtime. ARM requires a separately supported native release. LOCAL MODES AND ORIGIN BINDING @@ -98,36 +85,31 @@ LOCAL MODES AND ORIGIN BINDING https://CHAT_HOST/ with the configured HTTPS_PORT var/data/chat - These are distinct browser origins and require separate identity files. The - direct process and production deliberately use the same relative database - name on their respective machines. Do not switch an installation containing - valuable identities between direct development and production. Use a fresh - restored release directory for integration tests. Rebuild the release after - edits to refresh the packaged browser, server, sources, notices, and image. + Distinct origins require separate identity files. Direct development and + production share a relative database path on separate machines; do not switch + valuable installations between them. Integration tests need a fresh restored + release. Rebuild after edits to refresh browser, server, sources, notices, and image. - The single root .env holds public hostnames, ports, upstreams, backup settings, - SEARXNG_SECRET, and CHAT_SETUP_TOKEN. The example is public; actual .env is - ignored and never included in public releases or source downloads. Caddy keys - and chat databases are generated private runtime state under var/data. - Initialization preserves configured values and generates missing secrets. + One root .env holds hostnames, ports, upstreams, backups, SEARXNG_SECRET, and + CHAT_SETUP_TOKEN. Only the example is public; releases/source downloads exclude + actual .env. Caddy keys/chat databases stay under var/data. Initialization + preserves configured values and generates missing secrets. DEPLOY AND CREATE THE REAL OWNER FILE - Use the release upload/activation instructions in OPERATIONS.txt. Extract - the new prebuilt management binary into var/incoming/bootstrap and invoke - it with --root pointing at the current installation. Use the management - binary from that verified release so activation understands its service - schema. It verifies the archive and installs packaged chat artifacts before - starting services. + Follow OPERATIONS.txt. Extract the verified release's new management binary + into var/incoming/bootstrap; invoke with --root set to the current installation. + The new binary understands its release schema, verifies the archive, and + installs chat artifacts before startup. The host needs rootless Podman prerequisites, user linger, low-port permission, DNS A/AAAA records for CHAT_HOST and www.CHAT_HOST, and the normal 80/443 firewall rules. Caddy obtains and renews public certificates automatically. Public certificate validation requires standard reachable ACME ports. The systemd user service runs ./bin/stack up --production at boot and - ./bin/stack down on stop. Podman restart policies restart failed containers. - Neither mechanism compiles code or requests a registry pull for a complete - release on the matching architecture. Check all four services after activation: + ./bin/stack down on stop. Podman restarts + failed containers. Complete matching-architecture releases need no compilation + or registry pull. Check all four services after activation: ./bin/stack status @@ -136,57 +118,48 @@ DEPLOY AND CREATE THE REAL OWNER FILE The displayed limitations are CHAT-APPLICATION.txt. Chat has its own origin; the main website remains JavaScript-free. Its Message Me links lead to chat. - In the browser on the production HTTPS origin, choose OWNER SETUP. Read the - setup token from the production root .env locally; never publish it or send it - through chat. Choose a unique owner-file password, save the downloaded file, - reopen it, and unlock it. Store that file and password in KeePassXC and keep - a protected backup of the database. The setup token cannot replace this file. - Never copy a development owner file and silently change its pinned origin. + At the production HTTPS origin, choose OWNER SETUP. Read the root .env token + locally; never publish or send it through chat. Choose a unique password; + save, reopen, and unlock the downloaded owner file. Keep file/password in + KeePassXC with a protected database backup. The token cannot replace the file. + Never silently change a development file's pinned origin. BACKUP, RESTORE, AND KEY LOSS A complete encrypted application export: ./bin/stack backup --include-images - Download the .gpg and .sha256 files off the VPS. A backup on the same VPS is - vulnerable to loss of that VPS. Existing configured backup recipients apply. - This export includes the single .env, consistent SQLite snapshots for chat - and chat-local, Caddy certificate state, repositories, static binaries, WASM, - sources, and exact container images. SQLite uses its online backup API; chat - is left unpaused so a pending writer cannot block snapshot completion. - The database contains ciphertext and public keys, plus the metadata described - in CHAT-APPLICATION.txt. The owner private file and GnuPG secret key are not - server data; back them up separately. + Copy .gpg and .sha256 off the VPS; local backups cannot survive VPS loss. + Configured recipients apply. Export includes one .env, online SQLite snapshots + for chat/chat-local, Caddy certificates, repositories, static binaries, WASM, + sources, and exact images. Chat stays unpaused so pending writers can complete. + Database contents are ciphertext/public keys and CHAT-APPLICATION.txt metadata. + Owner private file and GnuPG secret key need separate backups. Restore to a new directory, verify, then explicitly start production mode: ./bin/stack restore /path/export.tar.gz.gpg /path/stack-restored cd /path/stack-restored ./bin/stack up --production - Restore defaults to local mode and changes container project names to avoid - accidentally replacing another installation. up --production selects the - production database and HTTPS origin again. Keep the same hostname/origin, - point DNS at the replacement host, and use unchanged owner/visitor files and - passwords. A new IP does not change an origin. A changed hostname or HTTPS - port does. Do not expose two restored copies simultaneously under one origin. - Server restart invalidates sessions; reopening identity files authenticates - again. Historical ciphertext and counters persist across restart and recovery. + Restore defaults to local mode with fresh project names, avoiding replacement + of another installation. up --production reselects production database/origin. + Keep hostname/origin, repoint DNS, and use unchanged identity files/passwords. + IP changes preserve origin; hostname/HTTPS-port changes do not. Never expose + two restored copies under one origin. Restart invalidates sessions; reopening + files authenticates again. Historical ciphertext/counters persist. - Losing the owner private file cannot be repaired by CHAT_SETUP_TOKEN. If its - backups are also lost, reset deliberately deletes every stored conversation - and message. It does not decrypt or recover anything. This backend operation - has no HTTP endpoint and requires filesystem/Podman access: + CHAT_SETUP_TOKEN cannot recover a lost private file. If backups are also lost, + reset deletes every conversation/message; it decrypts and recovers nothing. + Reset has no HTTP endpoint and requires filesystem/Podman access: ./bin/stack chat --owner-fingerprint ./bin/stack down ./bin/stack chat --reset-owner PASTE_CURRENT_OWNER_FINGERPRINT_HERE ./bin/stack up --production - A running server holds a filesystem lock; reset refuses until it stops. The - full fingerprint must match. Root .env and previous exports are preserved. - Create a new production owner file afterward. Old visitor files reject its - changed pinned owner key and need a new chat identity. A reset does not erase - copies already present in exports or external snapshots. + Reset requires a stopped server and matching full fingerprint. Root .env and + exports survive. Create a new production owner file; old visitor files reject + its changed key and need fresh identities. Exports/external snapshots are not erased. VERIFICATION |