hashtree CHK chunking for large crash reports

.gitignore

@@ -25,3 +25,6 @@ node_modules/
 # Test vectors
 test-vectors/node_modules/
 test-vectors/package-lock.json
+
+# Beads (local issue tracking)
+.beads/

AGENTS.md

@@ -125,6 +125,65 @@ id = sha256(json([0, pubkey, created_at, kind, tags, content]))
 
 Returns lowercase hex string (64 characters).
 
+## Lessons Learned
+
+### CHK Encryption Compatibility (Critical)
+
+**Problem**: All SDKs implemented CHK (Content Hash Key) encryption differently from the Rust reference implementation, causing complete decryption failure.
+
+**Root Cause**: Each SDK used its own interpretation of "encrypt with content hash":
+- Some used AES-256-CBC with random IV
+- Others omitted HKDF key derivation
+- Ciphertext format varied (IV position, tag handling)
+
+**The Correct Algorithm** (must match `hashtree-core` exactly):
+
+```
+1. content_hash = SHA256(plaintext)
+2. key = HKDF-SHA256(
+     ikm: content_hash,
+     salt: "hashtree-chk",
+     info: "encryption-key",
+     length: 32
+   )
+3. ciphertext = AES-256-GCM(
+     key: key,
+     nonce: 12 zero bytes,
+     plaintext: data
+   )
+4. output = [ciphertext][16-byte auth tag]
+```
+
+**Why each component matters**:
+
+| Component | Purpose | If Wrong |
+|-----------|---------|----------|
+| HKDF | Derives encryption key from content hash | Key mismatch → decryption fails |
+| Salt `"hashtree-chk"` | Domain separation | Different key → decryption fails |
+| Info `"encryption-key"` | Key purpose binding | Different key → decryption fails |
+| Zero nonce | Safe for CHK (same key = same content) | Different ciphertext → verification fails |
+| AES-GCM | Authenticated encryption | Different algorithm → decryption fails |
+
+**Why zero nonce is safe**: CHK is convergent encryption - the same plaintext always produces the same key. Since the key is deterministic, using a random nonce would make ciphertext non-deterministic, breaking content-addressable storage. Zero nonce is safe because the key is never reused with different content.
+
+**Verification checklist for new implementations**:
+1. Generate test vector in Rust: `cargo test chunking -- --nocapture`
+2. Encrypt same plaintext in your SDK
+3. Compare: content hash, derived key, ciphertext must be byte-identical
+4. Decrypt Rust ciphertext in your SDK (and vice versa)
+
+**Platform-specific libraries**:
+
+| Platform | HKDF | AES-GCM |
+|----------|------|---------|
+| Rust | `hashtree-core` | (built-in) |
+| Dart | `pointycastle` HKDFKeyDerivator | `pointycastle` GCMBlockCipher |
+| Kotlin | Manual HMAC-SHA256 | `javax.crypto` AES/GCM/NoPadding |
+| Go | `golang.org/x/crypto/hkdf` | `crypto/cipher` NewGCM |
+| Python | `cryptography` HKDF | `cryptography` AESGCM |
+| TypeScript (Node) | `crypto` hkdfSync | `crypto` aes-256-gcm |
+| TypeScript (RN) | `@noble/hashes/hkdf` | `@noble/ciphers/aes` gcm |
+
 ## Testing
 
 ### Unit Tests

README.md

@@ -34,27 +34,19 @@ Crash → Cache locally → App restart → Show consent dialog → User approve
 
 All SDKs use the same default relay list, chosen for reliability:
 
-| Relay | Max Event Size | Max WebSocket | Notes |
-|-------|----------------|---------------|-------|
-| `wss://relay.damus.io` | 64 KB | 128 KB | strfry defaults |
-| `wss://relay.primal.net` | 64 KB | 128 KB | strfry defaults |
-| `wss://nos.lol` | 128 KB | 128 KB | Fallback relay |
+| Relay | Notes |
+|-------|-------|
+| `wss://relay.damus.io` | strfry defaults |
+| `wss://relay.primal.net` | strfry defaults |
+| `wss://nos.lol` | Fallback relay |
 
-**Note:** Most relays use strfry defaults (64 KB event size, 128 KB websocket payload). The practical limit for crash reports is ~60 KB to allow for gift-wrap envelope overhead.
+**Note:** Most relays enforce a 64 KB event size limit (strfry default). Keep compressed payloads under **60 KB** to allow for gift-wrap envelope overhead.
 
 You can override these defaults via the `relays` configuration option in each SDK.
 
 ## Size Limits & Compression
 
-Crash reports are subject to relay message size limits (see [NIP-11](https://github.com/nostr-protocol/nips/blob/master/11.md) `max_message_length`).
-
-| Relay Limit | Compatibility |
-|-------------|---------------|
-| 64 KB | ~99% of relays |
-| 128 KB | ~90% of relays |
-| 512 KB+ | Major relays only |
-
-**Practical limit:** Keep compressed payloads under **60 KB** for universal delivery (allows ~500 bytes for gift-wrap envelope overhead).
+Crash reports are subject to relay message size limits (see [NIP-11](https://github.com/nostr-protocol/nips/blob/master/11.md) `max_message_length`). Most relays enforce a **64 KB** limit.
 
 | Payload Size | Behavior |
 |--------------|----------|
@@ -85,7 +77,7 @@ Gzip typically achieves **70-90% reduction** on stack traces due to their repeti
 | 50 KB | ~5-10 KB | ~80-90% |
 | 200 KB | ~20-40 KB | ~80-85% |
 
-With gzip compression (70-90% reduction), most crash reports fit well within the 64 KB strfry default limit. For maximum compatibility, keep compressed payloads under 60 KB.
+With gzip compression, most crash reports fit well within the 64 KB limit.
 
 ## Nostr Protocol
 
@@ -102,27 +94,64 @@ Per NIP-17, rumors (kind 14) must include:
 - `id` - SHA256 hash of `[0, pubkey, created_at, kind, tags, content]`
 - `sig: ""` - Empty string (not omitted)
 
-Some clients (e.g., 0xchat) reject messages missing these fields.
-
 ## Shared Test Vectors
 
 The [`test-vectors/`](test-vectors/) directory contains JSON test cases for NIP-17. All platform implementations should validate against these vectors.
 
 ## Symbolication
 
-Release builds typically use code obfuscation/minification, producing stack traces with mangled names and memory addresses instead of readable function names and line numbers.
+The Rust receiver includes built-in symbolication for 7 platforms:
+
+| Platform | Mapping File | Notes |
+|----------|--------------|-------|
+| Android | `mapping.txt` | ProGuard/R8 with full line-range support |
+| Electron/JS | `*.js.map` | Source map v3 |
+| Flutter | `*.symbols` | Via `flutter symbolize` or direct parsing |
+| Rust | Backtrace | Debug builds include source locations |
+| Go | Goroutine stacks | Symbol tables usually embedded |
+| Python | Tracebacks | Source file mapping |
+| React Native | `*.bundle.map` | Hermes bytecode + JS source maps |
+
+### CLI Usage
+
+```bash
+# Symbolicate a stack trace
+bugstr symbolicate --platform android --input crash.txt --mappings ./mappings \
+  --app-id com.example.app --version 1.0.0
+
+# Output formats: pretty (default) or json
+bugstr symbolicate --platform android --input crash.txt --format json
+```
+
+### Web API
 
-**Current status:** Symbolication tooling is not yet implemented. Crash reports contain raw stack traces as captured.
+```bash
+# Start server with symbolication enabled
+bugstr serve --mappings ./mappings
+
+# POST to symbolicate endpoint
+curl -X POST http://localhost:3000/api/symbolicate \
+  -H "Content-Type: application/json" \
+  -d '{"platform":"android","stack_trace":"...","app_id":"com.example","version":"1.0.0"}'
+```
 
-**Planned approach:**
-- Store mapping files (ProGuard, dSYM, sourcemaps) locally or in your CI
-- Use platform-specific tools to symbolicate:
-  - **Android**: `retrace` with ProGuard mapping
-  - **iOS/macOS**: `atos` or `symbolicatecrash` with dSYM
-  - **JavaScript**: Source map support in browser devtools
-  - **Flutter**: `flutter symbolize` with app symbols
+### Mapping File Organization
+
+```
+mappings/
+  android/
+    com.example.app/
+      1.0.0/mapping.txt
+      1.1.0/mapping.txt
+  electron/
+    my-app/
+      1.0.0/main.js.map
+  flutter/
+    com.example.app/
+      1.0.0/app.android-arm64.symbols
+```
 
-Contributions welcome for automated symbolication in the receiver CLI/WebUI.
+The receiver automatically falls back to the newest available version if an exact version match isn't found.
 
 ## Contributing