Add experimental PQ browser probe and document blocking timing review

1 files changed, 66 insertions, 0 deletions

diff --git a/crates/chat-crypto/README.txt b/crates/chat-crypto/README.txt
new file mode 100644
index 0000000..ba78cea
--- /dev/null
+++ b/crates/chat-crypto/README.txt
@@ -0,0 +1,66 @@
+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 COMPATIBILITY PROBE
+
+    Experimental, local-only work on feature/private-chat. This is a
+    cryptographic compatibility test, not a messaging application. Do not use
+    it for private conversations or real identities. It creates temporary
+    identities in memory and discards them; it does not create user chat files.
+
+    Fixed encryption: RFC 9980 ML-KEM-1024 + X448, OpenPGP v6.
+    Tested signing: ML-DSA-87 + Ed448, OpenPGP v6.
+    No algorithm substitution or security-advisory ignore is permitted.
+
+    See ../../docs/CHAT-SECURITY-REVIEW.txt for the blocking dependency review,
+    and ../../docs/CHAT-DESIGN.txt for the intended application and limitations.
+
+REPRODUCE THE NATIVE TEST
+
+        cargo test --locked -p stack-chat-crypto
+        cargo clippy --locked -p stack-chat-crypto --all-targets
+
+REPRODUCE THE BROWSER TEST
+
+    From the stack root, install development-only tools under .tools:
+
+        rustup target add wasm32-unknown-unknown
+        cargo install --locked --version 0.2.130 wasm-bindgen-cli --root .tools
+        npm install --prefix .tools/browser --save-exact playwright@1.64.1
+        PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" .tools/browser/node_modules/.bin/playwright install chromium
+
+    Build and bind the Rust module, then run it in actual Chromium:
+
+        cargo build --locked --release -p stack-chat-crypto --target wasm32-unknown-unknown
+        .tools/bin/wasm-bindgen --target web --out-dir .tools/chat-proof target/wasm32-unknown-unknown/release/stack_chat_crypto.wasm
+        PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node crates/chat-crypto/tests/browser.mjs
+
+    The harness serves only a blank test document and the generated JS/WASM on
+    an ephemeral loopback port. It checks the actual browser cryptographic
+    result and verifies that the probe creates no cookies, web storage, or
+    IndexedDB databases and sends no requests to external hosts.
+
+    This does not establish the storage or network behavior of a future chat
+    application, which has not been built yet. LibreJS acceptance has not been
+    tested; there is no public application or compliance badge for this probe.
+    The test password is a public fixture, not a real configured secret.
+
+AUDIT
+
+        .tools/bin/cargo-deny --workspace --all-features check
+
+    This audit is intentionally blocking. Consult the security review rather
+    than trusting a functional round trip as evidence of production security.