E2EE spec review: correctness fixes and clarifications

.gitignore

@@ -26,3 +26,4 @@ cli/where_cli_state.json
 *.swp
 *.txt
 *.log
+TODO_SPEC_UPDATES.md

AGENTS.md

@@ -44,7 +44,7 @@ Trust On First Use is NOT a bug; it's a choice (and accepted risk) of the
 current design.
 
 ### E2EE
-Uses a standard, bidirectional Double Ratchet protocol with X25519 ephemeral keys, HKDF-SHA-256 for ratcheting, and AES-256-GCM for encryption. See `docs/e2ee-location-sync.md` for the full protocol spec.
+Uses a standard, bidirectional Double Ratchet protocol with X25519 ephemeral keys, HKDF-SHA-256 for ratcheting, and ChaCha20-Poly1305 for encryption. See `docs/e2ee-location-sync.md` for the full protocol spec.
 
 ---
 

android/build.gradle.kts

@@ -61,8 +61,8 @@ android {
         applicationId = "net.af0.where"
         minSdk = 26
         targetSdk = 35
-        versionCode = 95
-        versionName = "2026.06.10.1"
+        versionCode = 96
+        versionName = "2026.06.12.1"
         manifestPlaceholders["MAPS_API_KEY"] = localProperties.getProperty("MAPS_API_KEY") ?: System.getenv("MAPS_API_KEY") ?: ""
     }
 

ios/Sources/Where/Info.plist

@@ -21,7 +21,7 @@
 	<key>CFBundleShortVersionString</key>
 	<string>$(MARKETING_VERSION)</string>
 	<key>CFBundleVersion</key>
-	<string>7</string>
+	<string>10</string>
 	<key>NSCameraUsageDescription</key>
 	<string>Where needs the camera to scan friend invite QR codes.</string>
 	<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>

ios/Where.xcodeproj/project.pbxproj

@@ -444,7 +444,7 @@
 				CODE_SIGN_ENTITLEMENTS = Sources/Where/Where.entitlements;
 				CODE_SIGN_IDENTITY = "Apple Distribution";
 				CODE_SIGN_STYLE = Manual;
-				CURRENT_PROJECT_VERSION = 7;
+				CURRENT_PROJECT_VERSION = 10;
 				DEVELOPMENT_TEAM = 5PM2V9LTHC;
 				FRAMEWORK_SEARCH_PATHS = (
 					"$(inherited) $(SRCROOT)/../shared/build/XCFrameworks/$(CONFIGURATION:lower)",
@@ -457,7 +457,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 1.14;
+				MARKETING_VERSION = 1.15;
 				PRODUCT_BUNDLE_IDENTIFIER = net.af0.WhereApp;
 				PROVISIONING_PROFILE_SPECIFIER = "Where AppStore";
 				SDKROOT = iphoneos;
@@ -473,7 +473,7 @@
 				CODE_SIGN_ENTITLEMENTS = Sources/Where/Where.entitlements;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 7;
+				CURRENT_PROJECT_VERSION = 10;
 				FRAMEWORK_SEARCH_PATHS = (
 					"$(inherited) $(SRCROOT)/../shared/build/XCFrameworks/$(CONFIGURATION:lower)",
 					"\".\"",
@@ -485,7 +485,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 1.14;
+				MARKETING_VERSION = 1.15;
 				PRODUCT_BUNDLE_IDENTIFIER = net.af0.WhereApp;
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";

ios/project.yml

@@ -83,8 +83,8 @@ targets:
       FRAMEWORK_SEARCH_PATHS: $(inherited) $(SRCROOT)/../shared/build/XCFrameworks/$(CONFIGURATION:lower)
       CODE_SIGN_IDENTITY: Apple Development
       CODE_SIGN_STYLE: Automatic
-      MARKETING_VERSION: "1.14"
-      CURRENT_PROJECT_VERSION: 6
+      MARKETING_VERSION: "1.15"
+      CURRENT_PROJECT_VERSION: 9
 
   WhereTests:
     type: bundle.unit-test

shared/src/commonMain/kotlin/net/af0/where/e2ee/ProtocolConstants.kt

@@ -21,7 +21,6 @@ internal const val MAX_MESSAGES_PER_POLL = 500
 // accepted as lost; the session may need re-pairing if they contained DH keys.
 // At a 30-second poll interval, 5 retries = ~2.5 minutes before force-ACK.
 internal const val MAX_SILENT_DROP_RETRIES = 5
-internal const val MAX_GAP = 10000
 // Bound on the skipped-message-key cache. Sized to comfortably absorb a full
 // MAX_MESSAGES_PER_POLL backlog (500) with headroom; peer-influenceable but
 // bounded at ~60 bytes/entry ≈ 60 KB worst case.

shared/src/commonMain/kotlin/net/af0/where/e2ee/Ratchet.kt

@@ -6,8 +6,10 @@ package net.af0.where.e2ee
  * KDF_RK – DH ratchet step. Inputs the current root key as HKDF salt and a fresh DH output
  * as IKM. Produces 96 bytes: [new_root_key (32) || new_chain_key (32) || new_header_key (32)].
  *
- * KDF_CK – Symmetric chain step. A single HKDF-SHA-256 call producing 76 bytes:
- *   [new_chain_key (32) || message_key (32) || message_nonce (12)].
+ * KDF_CK – Symmetric chain step using HMAC-SHA-256:
+ *   message_key    = HMAC(chain_key, 0x01)
+ *   new_chain_key  = HMAC(chain_key, 0x02)
+ *   message_nonce  = HKDF-SHA-256(ikm=message_key, info="Where-v1-MsgNonce", length=12)
  *   The old chain key MUST be discarded immediately after this call.
  */
 

shared/src/commonMain/kotlin/net/af0/where/e2ee/Session.kt

@@ -184,7 +184,7 @@ object Session {
         }
 
         val stepsNeeded = seq - speculativeState.recvSeq
-        if (stepsNeeded > MAX_GAP + 1) {
+        if (stepsNeeded > MAX_SKIPPED_KEYS + 1) {
             throw ProtocolGapException("gap too large: stepsNeeded $stepsNeeded")
         }
 
@@ -256,24 +256,13 @@ object Session {
                 try {
                     aeadDecrypt(finalStep.messageKey, finalStep.messageNonce, message.ct, aad)
                 } catch (e: Exception) {
-                    // Decryption failure. We persist the ratcheted state if the header
-                    // authenticated, to prevent permanent DH desync (§5.5), AND cache the
-                    // message key for `seq` itself so that a later genuine copy of the same
-                    // message — e.g. the clean original after a malicious server bit-flipped
-                    // the first delivery — can still decrypt via the skipped-key cache path
-                    // instead of failing the recvSeq replay check.
-                    // (Deliberate deviation from spec §8.3.1(4); see spec note.)
-                    val seqCacheKey = remoteDhPub.toHex() + ":" + seq
-                    derivationSkippedKeys[seqCacheKey] =
-                        finalStep.messageKey + finalStep.messageNonce + longToBeBytes(now)
-                    if (derivationSkippedKeys.size > MAX_SKIPPED_KEYS) {
-                        val oldestKey = derivationSkippedKeys.keys.first()
-                        if (oldestKey != seqCacheKey) {
-                            derivationSkippedKeys[oldestKey]?.zeroize()
-                            derivationSkippedKeys.remove(oldestKey)
-                        }
-                    }
-
+                    // Body AEAD failed despite a valid header. Advance recvSeq and the chain
+                    // key to prevent permanent DH desync — without this, a server that drops
+                    // the message entirely and a server that delivers a corrupted copy would
+                    // have different effects on session state, breaking the ratchet.
+                    // The failed message's key is NOT cached: caching it would keep MK_n alive
+                    // for up to 7 days with no benefit, since a server willing to deliver a
+                    // corrupted copy can equally just drop the message.
                     val failedState =
                         speculativeState.deepCopy().copy(
                             recvChainKey = chainKey.copyOf(),
@@ -282,8 +271,6 @@ object Session {
                             needsRatchet = cleanState.needsRatchet || isNewDhEpoch,
                         )
                     // Wipe any speculative intermediate keys derived during this failed call.
-                    // The seq cache entry above is intentionally NOT in addedSkippedKeys —
-                    // failedState already holds a copy of it.
                     addedSkippedKeys.forEach { it.zeroize() }
                     chainKey.zeroize()
                     throw DecryptionExceptionWithState(failedState, e)

shared/src/commonTest/kotlin/net/af0/where/e2ee/ReceiveRatchetFailureTest.kt

@@ -1,8 +1,8 @@
 package net.af0.where.e2ee
 
 import kotlin.test.Test
-import kotlin.test.assertEquals
-import kotlin.test.assertIs
+import kotlin.test.assertFailsWith
+import kotlin.test.assertFalse
 import kotlin.test.assertTrue
 import kotlin.test.fail
 
@@ -12,17 +12,13 @@ class ReceiveRatchetFailureTest {
     }
 
     /**
-     * Issue #2: a malicious server bit-flips the body of a genuine message.
-     * The header still authenticates (header keys are secret), so decryptMessage
-     * advances the receive ratchet (per §5.5 — to prevent permanent DH desync).
-     * Without the seq-key cache, when the clean original later arrives in the
-     * same batch, it is `seq <= recvSeq` → ReplayException and permanently lost.
-     *
-     * This test exercises the within-batch case (Bob's pre-decrypted header is
-     * reused across both decryption attempts, matching E2eeProtocol.decryptBatch).
+     * A body-AEAD failure after a valid header must advance recvSeq and the chain key
+     * to prevent permanent DH desync (§8.3.1(4)). The failed message's key must NOT
+     * be cached — there is no robustness benefit to caching it, since a server willing
+     * to deliver a corrupted copy can equally just drop the message.
      */
     @Test
-    fun cleanCopyDecryptsAfterTamperedAdvanceCachesSeqKey() {
+    fun bodyFailAdvancesStateWithoutCachingSeqKey() {
         val (qr, aliceEkPriv) = KeyExchange.aliceCreateQrPayload("Alice")
         val (msg, bobSession) = KeyExchange.bobProcessQr(qr, "Bob")
         val aliceSession = KeyExchange.aliceProcessInit(msg, aliceEkPriv, qr.ekPub)
@@ -32,17 +28,13 @@ class ReceiveRatchetFailureTest {
             MessagePlaintext.Location(1.0, 2.0, 3.0, 4L),
         )
 
-        // Pre-decrypt the header once (matching the batch path). Both the
-        // tampered and the clean copy share the same envelope, so this header
-        // applies to both.
         val sessionAad = bobSession.aliceFp + bobSession.bobFp
         val header = try {
             Session.decryptHeader(bobSession.headerKey, original.envelope, sessionAad)
         } catch (_: Exception) {
             Session.decryptHeader(bobSession.nextHeaderKey, original.envelope, sessionAad)
         }
 
-        // Simulate a malicious server bit-flipping the body.
         val tampered = original.copy(
             ct = original.ct.copyOf().also { it[it.size - 1] = (it.last().toInt() xor 0xFF).toByte() },
         )
@@ -54,20 +46,18 @@ class ReceiveRatchetFailureTest {
             e.newState
         }
 
+        // recvSeq must advance so the ratchet state stays consistent.
         assertTrue(bobAfterFailure.recvSeq >= 1, "recvSeq should have advanced past the failed message")
 
-        // The clean original now arrives. The cached seq key must rescue it
-        // from the recvSeq replay rejection.
-        val (bobFinal, plaintext) = Session.decryptMessage(bobAfterFailure, original, header)
-        assertIs<MessagePlaintext.Location>(plaintext)
-        assertEquals(1.0, plaintext.lat)
-        assertEquals(2.0, plaintext.lng)
-        assertEquals(4L, plaintext.ts)
-
-        // Cache entry for this seq was consumed by the successful decryption.
-        assertTrue(
-            bobFinal.skippedMessageKeys.keys.none { it.endsWith(":${header.seq}") },
-            "seq=${header.seq} cache entry should have been consumed",
+        // The seq key must NOT be cached — the message is lost, equivalent to a drop.
+        assertFalse(
+            bobAfterFailure.skippedMessageKeys.keys.any { it.endsWith(":${header.seq}") },
+            "seq=${header.seq} key must not be cached after body-fail",
         )
+
+        // A subsequent attempt to decrypt the (uncorrupted) original is rejected as a replay.
+        assertFailsWith<ReplayException> {
+            Session.decryptMessage(bobAfterFailure, original, header)
+        }
     }
 }