Add experimental PQ browser probe and document blocking timing review

3 files changed, 243 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.
diff --git a/docs/CHAT-SECURITY-REVIEW.txt b/docs/CHAT-SECURITY-REVIEW.txt
new file mode 100644
index 0000000..7de1d36
--- /dev/null
+++ b/docs/CHAT-SECURITY-REVIEW.txt
@@ -0,0 +1,119 @@
+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/>.
+
+
+CHAT CRYPTOGRAPHY SECURITY REVIEW
+
+    Date: 2026-10-30. Status: blocked for deployment and private-message use.
+    Branch: feature/private-chat. Production and main remain unchanged.
+
+FIXED REQUIREMENT
+
+    Encryption must remain RFC 9980 ML-KEM-1024 + X448 using v6 keys.
+    The compatibility probe pairs it with ML-DSA-87 + Ed448 signatures.
+    No fallback encryption profile is implemented or approved.
+
+TEST RESULTS
+
+    Sequoia OpenPGP 2.4.2 with its Rust backend generated password-protected v6
+    secret keys, serialized and reimported them, signed UTF-8 content, encrypted
+    to both participants, and decrypted successfully for both participants.
+    Wrong passwords, unexpected signers, and modified ciphertext were rejected.
+    The same probe passed in actual Chromium using Rust compiled to WASM.
+
+    Functional tests are not a cryptographic audit, constant-time analysis,
+    conformance certification, or demonstration that side channels are absent.
+    The test uses no user-supplied key files and does not provide chat service.
+
+RUSTSEC-2026-0387: REACHABLE DEPENDENCY
+
+    Sequoia 2.4.2's crypto-rust backend selects cx448 0.1.1 for both X448
+    and Ed448. cx448 depends on crypto-bigint 0.5.5.
+
+    Source paths within these exact published crates:
+
+        sequoia-openpgp/src/crypto/backend/rust/asymmetric.rs
+            x448_generate_key, x448_derive_public, x448_shared_point
+            ed448_generate_key, ed448_sign
+        cx448/src/x448.rs
+            PublicKey::from(&Secret), Secret::as_diffie_hellman
+        cx448/src/curve/montgomery.rs
+            Montgomery scalar multiplication and projective-to-affine conversion
+        cx448/src/field.rs
+            elliptic_curve::bigint and constant-modulus Montgomery representation
+        cx448/src/field/element.rs
+            field subtraction, multiplication, inversion
+        cx448/src/field/scalar.rs
+            scalar arithmetic using crypto-bigint integer operations
+
+    The flagged crate is part of the required curve arithmetic. It cannot be
+    dismissed as an unused RSA dependency. The advisory covers timing variation
+    in arithmetic intended to be constant-time and identifies >=0.7.6 as fixed.
+    cx448 0.1.1 requires the incompatible 0.5 series. Updating Cargo.lock alone
+    cannot satisfy that requirement with 0.7.6. Source changes or another backend
+    would require a separate review and tests; no local cryptographic patch has
+    been invented to bypass this gate.
+
+    This establishes a reachable affected dependency and prevents a claim of
+    unreachability. It does not prove practical key extraction from this WASM
+    binary on a particular browser/CPU. No such exploit has been demonstrated.
+    The hybrid construction's independent component may preserve protection
+    under some component failures; that is not grounds for ignoring the audit.
+
+    Advisory: https://rustsec.org/advisories/RUSTSEC-2026-0387.html
+
+RUSTSEC-2023-0071: RSA
+
+    Sequoia's crypto-rust feature also includes rsa 0.9.10. The probe generates
+    only the specified PQ identities and calls their corresponding primitives;
+    it does not generate an RSA key or exercise RSA private-key operations.
+
+    That observation applies only to this closed, generated-input probe. It is
+    not proof that a future importer, certificate verifier, authentication
+    endpoint, or decryption interface cannot be induced to use another algorithm.
+    The future application needs an explicit supported-algorithm policy and
+    hostile-input tests before any narrower exception could be assessed.
+
+    Advisory: https://rustsec.org/advisories/RUSTSEC-2023-0071.html
+
+BACKEND CHECK
+
+    In the installed Sequoia 2.4.2 source, the Nettle and Botan asymmetric
+    backends report these required composite algorithms unsupported. The OpenSSL
+    backend conditionally supports them, depending on the available OpenSSL
+    version/features. Its browser/WASM build has not been demonstrated here.
+    Native OpenSSL support alone would not satisfy client-side browser encryption.
+
+    The Rust backend requires allow-experimental-crypto and
+    allow-variable-time-crypto. These are explicit prototype build opt-ins,
+    not security approvals or claims that the selected operations are safe.
+
+OTHER AUDIT GATES
+
+    The new dependency graph also contains multiple crate versions. Its exact
+    graph is pinned in Cargo.lock. Duplicate bans have not been relaxed, and
+    no vulnerability advisory has been ignored. License permissions for Sequoia
+    and its dependencies must remain correctly attributed in generated notices.
+
+    The project check must audit the whole workspace. A root-package-only
+    cargo-deny invocation misses a workspace member that is not a dependency
+    of the root CLI. The branch changes that invocation to --workspace.
+
+NEXT GATE
+
+    Retain the fixed algorithms. Resolve the curve-backend dependency through
+    a reviewed upstream-compatible fix or demonstrate an acceptable alternative
+    backend in the browser. Repeat the native and browser tests, review imported
+    hostile inputs, and pass the full dependency audit before private-message use.
diff --git a/docs/POLICY.txt b/docs/POLICY.txt
index 592269b..e2cc4a9 100644
--- a/docs/POLICY.txt
+++ b/docs/POLICY.txt
@@ -73,3 +73,7 @@ PORTABILITY
     rejects mismatched production images. Development mode may fetch/build
     native images on an architecture mismatch. Container source and Rust
     source are public so new targets can be added without restoring an OS.
+
+    Generated third-party legal texts retain upstream whitespace and line endings.
+    .gitattributes exempts only THIRD-PARTY-LICENSES.html from whitespace errors;
+    first-party source checks remain strict. Workspace audits include every member.