docs: shorten guides and map repository filesHEADmain

1 files changed, 89 insertions, 109 deletions

diff --git a/docs/CHAT-OPENSSL-MIGRATION.txt b/docs/CHAT-OPENSSL-MIGRATION.txt
index 8c9ee28..4bb87fb 100644
--- a/docs/CHAT-OPENSSL-MIGRATION.txt
+++ b/docs/CHAT-OPENSSL-MIGRATION.txt
@@ -16,28 +16,33 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 OPENSSL BACKEND MIGRATION RECORD
 
-    Date: 2026-10-30. Historical backend migration record.
-    Scope at this checkpoint: a compatibility and dependency-security experiment.
-    The later messenger and packaged deployment are described separately in
-    CHAT-APPLICATION.txt and CHAT-PRODUCTION.txt. Tests use disposable identities.
+    Date: 2026-10-30. Historical compatibility/dependency-security experiment
+    using disposable identities. For the later messenger and packaged deployment,
+    see CHAT-APPLICATION.txt and CHAT-PRODUCTION.txt.
 
 DECISION AND FIXED ALGORITHMS
 
-    Retain Sequoia OpenPGP 2.4.2 and RFC 9980 ML-KEM-1024 + X448 encryption.
-    Retain ML-DSA-87 + Ed448 signatures, OpenPGP v6 keys, and AES-256 content
-    encryption. Change the cryptographic backend, not the algorithms or wire
-    protocol. Probe assertions reject an unexpected backend or key algorithms.
-
-    The previous Rust backend reached cx448 0.1.1 -> crypto-bigint 0.5.5 during
-    curve arithmetic. It also included rsa 0.9.10. See CHAT-SECURITY-REVIEW.txt
-    for the original reachability investigation. Neither RustSec issue was
-    ignored. No mathematical implementation was patched locally.
-
-    The current manifest enables only Sequoia's crypto-openssl feature. The
-    allow-experimental-crypto and allow-variable-time-crypto opt-ins are gone.
-    The resolved graph has no cx448, crypto-bigint, or rsa crate. This removes
-    those Rust backend dependencies; it does not prove that all side channels
-    are absent from a browser or that external C dependencies have no defects.
+    Retain Sequoia OpenPGP 2.4.2, RFC 9980 ML-KEM-1024 + X448 encryption,
+    ML-DSA-87 + Ed448 signatures, OpenPGP v6 keys, and AES-256 content encryption.
+    Only the backend changes; algorithms and wire protocol stay fixed.
+    Probe assertions reject unexpected backends or key algorithms.
+
+    Previous Rust curve arithmetic reached cx448 0.1.1 -> crypto-bigint 0.5.5;
+    the backend also included rsa 0.9.10. Neither RustSec issue was ignored;
+    no mathematical implementation was patched locally.
+    RUSTSEC-2026-0387 affected required X448/Ed448 curve arithmetic, not unused RSA.
+    Its fix requires crypto-bigint >=0.7.6; cx448 0.1.1 requires incompatible 0.5.
+    A lockfile update alone could not fix it. No practical browser key-extraction
+    exploit was demonstrated; functional tests do not prove constant-time behavior.
+    The closed probe used no RSA private operations, but that did not establish
+    unreachability through hostile imports or future application interfaces.
+        https://rustsec.org/advisories/RUSTSEC-2026-0387.html
+        https://rustsec.org/advisories/RUSTSEC-2023-0071.html
+
+    Only crypto-openssl is enabled. allow-experimental-crypto and
+    allow-variable-time-crypto are removed. The resolved graph has no cx448,
+    crypto-bigint, or rsa crate. Removing those dependencies does not prove
+    absence of browser side channels or external C defects.
 
 VERSIONS AND SOURCE PROVENANCE
 
@@ -55,36 +60,29 @@ VERSIONS AND SOURCE PROVENANCE
         https://github.com/openssl/openssl/releases/download/openssl-3.6.5/openssl-3.6.5.tar.gz
         SHA-256 a2157c2830efdec3788939b00c9b0638306d3f0bbb76dc4832ee503bb397df98
 
-    Digests were checked against upstream GitHub release asset metadata. The
-    build script verifies each archive before extraction. Hash checking pins
-    these inputs; it is not a claim that upstream release signatures were
-    independently verified or that output is bit-for-bit reproducible across
-    hosts. Archives, SDK, libraries, and build products stay under ignored
-    .tools/ and target/. The native development library is supplied by the OS.
+    Digests match upstream GitHub release asset metadata; scripts verify them
+    before extraction. This pins inputs, without independently verifying release
+    signatures or proving cross-host bit-for-bit builds. Archives, SDK, libraries,
+    and build products stay under ignored .tools/ and target/. The OS supplies
+    the native development library.
 
 WHY WASI
 
-    The original Rust-backend proof used wasm32-unknown-unknown and generated
-    wasm-bindgen JavaScript. The OpenSSL proof uses a wasm32-wasip1 command
-    module and a small explicit browser WASI bridge. The Rust command calls
-    the same compatibility_probe function used by native tests.
-
-    The browser harness loads the new WASI binary directly, not old generated
-    glue. It requires the output to identify OpenSSL 3.6.5, preventing a stale
-    Rust-backend artifact from being accepted as evidence of OpenSSL support.
-    Old browser-build commands are historical and must not be reused here.
+    The Rust proof used wasm32-unknown-unknown and wasm-bindgen glue. OpenSSL uses
+    a wasm32-wasip1 command and explicit browser WASI bridge, calling the native
+    tests' compatibility_probe. The browser loads this binary directly and
+    requires output identifying OpenSSL 3.6.5; stale Rust-backend artifacts cannot
+    count as OpenSSL evidence. Do not reuse historical browser-build commands.
 
 BUILD CONFIGURATION AND BOUNDARIES
 
-    infra/chat/openssl-wasi.conf adds a build target inheriting BASE_unix with
-    little-endian and 32-bit bignum configuration. It changes configuration,
-    not OpenSSL's cryptographic source routines. C code is compiled at -O2.
-    No third-party rand.patch, unconditional entropy-success patch, or custom
-    random-number generator is applied. A SHA-256 comparison of all 5889 original
-    regular files against the downloaded OpenSSL archive found no changed or
-    missing originals after the build; only the separate target configuration
-    was added. OpenSSL 3.6.5 already supports WASI
-    getentropy in providers/implementations/rands/seeding/rand_unix.c.
+    infra/chat/openssl-wasi.conf adds a BASE_unix target with little-endian,
+    32-bit bignums; cryptographic routines are unchanged. C uses -O2. No rand.patch,
+    unconditional entropy-success patch, or custom RNG is applied. SHA-256 checks
+    of all 5889 original regular files against the downloaded archive found none
+    changed or missing after build; only the target configuration was added.
+    OpenSSL 3.6.5 supports WASI getentropy in
+    providers/implementations/rands/seeding/rand_unix.c.
 
     Configure selects --with-rand-seed=getrandom. WASI libc's entropy request
     reaches wasi_snapshot_preview1.random_get. The browser bridge services it
@@ -92,28 +90,23 @@ BUILD CONFIGURATION AND BOUNDARIES
     bytes. There is no Math.random, fixed seed, or success-on-failure fallback.
     The negative test replaces that API with a failure and requires rejection.
 
-    Build options disable assembly, async operations, automatic config loading,
+    Static builds disable assembly, async operations, automatic config loading,
     DSO/modules, POSIX I/O, secure-memory arenas, shared libraries, sockets,
-    C stdio, thread pools, threads, and interactive console UI. They avoid
-    unsupported host capabilities and use static libraries. Disabling the
-    secure-memory arena means ordinary WASM linear memory is used; it does not
-    establish secure erasure, locked pages, or protection from delivered JS.
-    Disabling C stdio does not disable the Rust command's captured output.
-
-    _WASI_EMULATED_GETPID and libwasi-emulated-getpid supply the SDK's process-ID
-    emulation. getuid/geteuid/getgid/getegid map to getpagesize, following the
-    common WASI port configuration: the browser module has no real OS user IDs
-    or privilege boundary. These values are not used as randomness or identity
-    credentials. This is an explicit portability assumption, not a general
-    POSIX security emulation layer.
-
-    Rust bindings use the SDK's libclang and WASI sysroot with target
-    wasm32-wasip1 and -fvisibility=default. Without explicit visibility, the
-    initial bindgen attempt omitted function declarations. Rust's bundled WASI
-    libc search path precedes the SDK libraries: reversing that order initially
-    failed to link __wasi_init_tp. The SDK library path remains available for
-    the emulated-getpid archive. These failures were toolchain integration
-    issues; no generated cryptographic bindings were manually edited.
+    C stdio, thread pools, threads, and interactive console UI to avoid unsupported
+    capabilities. Ordinary WASM linear memory provides no secure-erasure,
+    locked-page, or delivered-JS protection. Rust output remains captured.
+
+    _WASI_EMULATED_GETPID and libwasi-emulated-getpid supply SDK process-ID emulation.
+    getuid/geteuid/getgid/getegid map to getpagesize, following common WASI port
+    configuration. The browser module has no real OS user IDs or privilege boundary.
+    These values supply neither randomness nor identity credentials. This portability
+    assumption does not emulate general POSIX security.
+
+    Bindings use SDK libclang/WASI sysroot, target wasm32-wasip1, and
+    -fvisibility=default; without explicit visibility, bindgen omitted declarations.
+    Rust's bundled WASI libc precedes SDK libraries; reversed order failed to link
+    __wasi_init_tp. SDK libraries remain available for emulated-getpid. These were
+    toolchain integration failures; generated cryptographic bindings were not edited.
 
 BROWSER CAPABILITIES
 
@@ -123,11 +116,9 @@ BROWSER CAPABILITIES
     Listed filesystem/network operations return NOTCAPABLE or BADF. Unknown
     imports fail before instantiation. Standard output is capped at 65536 chars.
 
-    Those capability denials protect against accidentally connecting the WASI
-    module to host storage or networking. They do not isolate it from malicious
-    JavaScript delivered by the same server. Memory, clocks, randomness, and
-    imported bridge functions remain part of the trusted browser environment.
-    A test deadline closes Chromium after 120 seconds if execution stalls.
+    Denials prevent accidental host storage/network access, not malicious JS from
+    the same server. Memory, clocks, randomness, and bridge imports remain trusted.
+    The test closes Chromium after 120 seconds if execution stalls.
 
 VERIFICATION
 
@@ -144,25 +135,20 @@ VERIFICATION
     A modified module requesting an unknown host import is also rejected before
     instantiation. These negative tests require the expected failure reason.
 
-    The harness also observes no external requests, cookies, localStorage,
-    sessionStorage, IndexedDB databases, or service-worker registrations.
-    Its HTTP responses carry Cache-Control: no-store. This establishes only
-    this probe's behavior, not that browsers/OSes cannot retain memory, caches,
-    crash dumps, swap, or restored state. A complete chat session does not exist.
-
-    The native tests, WASI build, and browser test are separate checks. A native
-    pass cannot stand in for browser execution. A functional pass and a clean
-    vulnerability scan cannot stand in for a cryptographic or side-channel audit.
+    The harness observed no external requests, cookies, localStorage,
+    sessionStorage, IndexedDB databases, or service-worker registrations; responses
+    carry Cache-Control: no-store. This concerns only the probe. Browsers/OSes can
+    retain memory, caches, crash dumps, swap, and restored state. No complete chat
+    session existed at this checkpoint. Native tests, WASI build, and browser
+    execution are separate gates; functional tests and scans are not cryptographic
+    or side-channel audits.
 
 DEPENDENCY POLICY REVIEW
 
-    The RustSec database reports no advisories for the current resolved graph.
-    No advisory ignore was added. Bans on wildcards, unknown Git/registry sources,
-    and unreviewed duplicate versions remain enabled. The following existing
-    upstream API generations cannot be unified merely by cargo update. Duplicate
-    exceptions match only the exact older version; other versions remain subject
-    to the duplicate ban. All these packages still undergo advisory and license
-    checks. Cargo.lock pins both sides of each pair.
+    RustSec reports no advisories for this resolved graph; no ignore was added.
+    Bans on wildcards, unknown Git/registry sources, and unreviewed duplicates remain.
+    cargo update cannot unify these upstream API generations. Exceptions match only
+    exact older versions; advisory/license checks still apply. Cargo.lock pins both sides:
 
         block-buffer 0.10.4 vs 0.12.1
         crypto-common 0.1.7 vs 0.2.2
@@ -196,23 +182,20 @@ DEPENDENCY POLICY REVIEW
             macros and other dependencies use syn 3. Changing that would require
             upstream migration or unrelated dependency downgrades.
 
-    The only new license allowance is ISC, scoped to libloading, a bindgen/clang
-    dependency. GNU-compatible third-party licenses remain correctly attributed.
-    cargo-about generates notices for the complete workspace. The static OpenSSL
-    C library and SDK are not Rust crates; their original licenses and sources
-    must accompany any distributed browser artifact as appropriate. Source
-    OpenSSL LICENSE.txt is Apache-2.0. Do not treat the Rust notice page alone
-    as complete documentation of external C/toolchain distribution obligations.
+    The only new license allowance is ISC for bindgen/clang's libloading.
+    GNU-compatible licenses retain attribution; cargo-about covers the workspace.
+    OpenSSL C and SDK are outside Cargo. Distributed browser artifacts must carry
+    their original licenses/sources as required. OpenSSL LICENSE.txt is Apache-2.0.
+    Rust notices alone do not cover external C/toolchain distribution obligations.
 
 EXTERNAL LIBRARY MAINTENANCE
 
-    cargo-deny does not audit the externally built OpenSSL C archive or SDK.
-    Review OpenSSL's release/advisory pages separately and rebuild when needed:
+    cargo-deny excludes external OpenSSL C and SDK. Review separately; rebuild as needed:
         https://openssl-library.org/news/timeline/
         https://openssl-library.org/news/vulnerabilities-3.6/
-    OpenSSL 3.6.5 is the tested security-patch release dated 2026-09-29. A green
-    Rust audit is not a lifetime security guarantee for this pinned C version.
-    Choose and document a supported update policy before production deployment.
+    Tested OpenSSL 3.6.5 is the 2026-09-29 security-patch release. A Rust audit
+    does not guarantee this pinned C version's future security. Document a supported
+    update policy before production deployment.
 
 REPRODUCE FROM THE STACK ROOT
 
@@ -229,12 +212,10 @@ REPRODUCE FROM THE STACK ROOT
         PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto
         cargo stack check
 
-    The build script pins archive versions and hashes, configures static OpenSSL,
-    installs it under .tools/openssl-wasi, builds the Rust WASI command, and prints
-    its SHA-256. It does not download/use an unverified precompiled OpenSSL binary.
-    It may reuse already extracted sources; use a fresh ignored tools/build tree
-    when independently verifying the source archive rather than trusting a
-    previously modified extraction. Downloads and test artifacts are not secrets.
+    The script pins versions/hashes, builds static OpenSSL under .tools/openssl-wasi,
+    builds the Rust WASI command, and prints its SHA-256. It uses no unverified
+    precompiled OpenSSL. Extracted sources may be reused; independent verification
+    needs a fresh ignored tools/build tree. Downloads/test artifacts are not secrets.
 
     Build logs and complete dependency trees are local ignored diagnostics in
     .tools/chat-openssl-*.log and .tools/chat-openssl-duplicates.txt. The native
@@ -246,9 +227,8 @@ REMAINING WORK
         7fba6b96377619ef41f056d4027c4409107372e9300b2dd69be865e72892df79
     This is a diagnostic identifier, not a cross-host reproducibility promise.
 
-    This removes the specific Rust-backend dependency blocker and demonstrates
-    the fixed algorithms in a browser. It is not a complete messaging service,
-    audit of OpenSSL/WASI/JIT timing behavior, LibreJS certification, or proof
-    against malicious delivery. The file format, authentication, server/database,
-    quotas, hostile-input handling, pagination/counts, backup recovery, complete
-    session lifecycle, and browser-state tests still need implementation.
+    This checkpoint removed the Rust-backend blocker and demonstrated fixed
+    algorithms in-browser. It was not a complete messenger, OpenSSL/WASI/JIT timing
+    audit, LibreJS certification, or proof against malicious delivery. File format,
+    authentication, server/database, quotas, hostile-input handling, pagination/counts,
+    recovery, session lifecycle, and browser-state tests remained to implement.