docs(e2ee): add Argon2id table, canonicalization spec (JCS), and Mermaid diagrams for key flows

Author: OneFineStarstuff

DESIGN-E2EE.md

@@ -16,6 +16,13 @@ Owner: Kyaw
 - Out of scope initial: traffic analysis resistance; plaintext content scanning; hardware tamper beyond platform enclaves.
 
 ## 3. Cryptographic Primitives and Libraries
+
+### 3.1 Argon2id Parameters (desktop vs mobile)
+- Desktop/Web: m=64 MiB, t=3, p=1 — balances user-perceived latency with robust GPU/ASIC resistance for key wrapping. Typical derivation latency ~200–500 ms on contemporary laptops.
+- Mobile: m=32 MiB, t=3, p=1 — reduces memory pressure and thermal impact while keeping meaningful resistance. Target latency ~300–700 ms depending on device class.
+- Salt length: 16 bytes (random per vault). Output length: 32 bytes (KEK).
+- Rationale: Memory-hardness is the dominant cost lever; t=3 provides reasonable compute amplification without excessive energy draw on battery devices.
+
 - Ed25519 (signing) for identities and devices.
 - X25519 (ECDH) for key agreement; sealed boxes for key wrapping (HPKE-ready abstraction).
 - Messaging: Signal/Double Ratchet via libsignal-client (WASM) for 1:1/small groups.
@@ -47,6 +54,12 @@ Transitions:
 - Group sender keys: per-room sender key rotated on membership change and every 7 days; per-recipient key wraps.
 
 ## 6. File Encryption and Sharing
+See also Mermaid diagrams in docs/diagrams for provisioning, file-share, and rekey flows.
+
+### 5.1 Canonicalization (signatures & tokens)
+- Manifest signing: Canonical JSON per RFC 8785 (JSON Canonicalization Scheme, JCS). Remove the `sig` field before canonicalization; sign the result with device Ed25519. Verification recomputes canonical JSON and verifies the signature.
+- PASETO payload normalization: When computing or verifying detached request signatures or audit hashes, canonicalize the JSON payload using the same JCS rules and sort header fields if applicable. Avoid including transient fields (e.g., `iat` skew-adjusted values) in hash commitments.
+
 ### 6.1 Streaming Encryption
 - Per-file random DEK (256-bit).
 - Chunk size 512KB–2MB (adaptive). Max single-object size: 5 GB (resumable uploads).
@@ -67,7 +80,7 @@ chunks:
     blake3: <hex>
   - ...
 key_wraps: omitted in manifest; stored adjacent by object_id
-sig: ed25519(signing_device_pubkey, canonical_json(manifest_without_sig))
+sig: ed25519(signing_device_pubkey, JCS(manifest_without_sig))
 ```
 
 ### 6.3 DEK Sharing

docs/diagrams/file-share.mmd

@@ -0,0 +1,19 @@
+sequenceDiagram
+    autonumber
+    participant C as Client
+    participant O as Object Store
+    participant S as Server
+
+    C->>C: Generate DEK
+    loop Encrypt chunks
+        C->>C: nonce_i = HKDF(DEK, "file-chunk"||i)[0..12]
+        C->>C: c_i = AES-GCM(plaintext_i, nonce_i)
+        C->>C: blake3_i = BLAKE3(c_i)
+    end
+    C->>C: blake3_file = BLAKE3(c_*) ; manifest+sig
+    C->>O: PUT chunks + manifest (ciphertext only)
+    par share DEK
+        C->>S: POST key_wrap(device_pkX, sealed_box(DEK))
+    and for each recipient
+        C->>S: POST key_wrap(device_pkY, sealed_box(DEK))
+    end

docs/diagrams/provisioning.mmd

@@ -0,0 +1,13 @@
+sequenceDiagram
+    autonumber
+    participant ND as New Device
+    participant TD as Trusted Device
+    participant S as Server
+
+    ND->>ND: Generate Ed25519_sign_D, X25519_D, nonce N, ts
+    ND->>TD: Display QR: base64url(JSON{device_pubkeys, N, ts, sig=Sign_D(N||ts)})
+    TD->>TD: Compute SAS = hash(identity_pub, device_pubkeys, N, ts) -> 7 emojis
+    ND-->>TD: Human verifies SAS matches
+    TD->>S: POST /devices/attest(attestation=Sign_T{identity_pub, device_pubkeys, N, ts})
+    S-->>TD: 200 OK
+    S-->>ND: WS event device-verified

docs/diagrams/rekey.mmd

@@ -0,0 +1,11 @@
+sequenceDiagram
+    autonumber
+    participant A as Admin
+    participant S as Server
+    participant C as Clients (room)
+
+    A->>S: Update membership
+    S-->>C: WS membership-change
+    C->>C: Rotate sender key; rewrap DEKs
+    C->>S: POST new wraps
+    S-->>C: Ack; old wraps invalidated