encryption_diff.txt

diff --git a/crates/fula-client/src/encryption.rs b/crates/fula-client/src/encryption.rs
index d98e8ca..8f5e947 100644
--- a/crates/fula-client/src/encryption.rs
+++ b/crates/fula-client/src/encryption.rs
@@ -26,7 +26,7 @@ use fula_crypto::{
     },
     sharing::{ShareToken, AcceptedShare, ShareRecipient},
     rotation::{KeyRotationManager, WrappedKeyInfo},
-    wnfs_hamt::BlobBackend,
+    wnfs_hamt::{BlobBackend, BlobPutResult},
     sharded_hamt_forest::ShardedHamtPrivateForest,
     ChunkedEncoder, ChunkedFileMetadata, should_use_chunked,
     CryptoError,
@@ -388,8 +388,27 @@ impl BlobBackend for S3BlobBackend {
     /// Same retry policy as `get`. `put_object` is idempotent on v7 HAMT
     /// node keys — they are content-addressed (blake3 over the plaintext
     /// node), so re-uploading the same bytes at the same path is safe.
-    async fn put(&self, path: &str, bytes: Vec<u8>) -> fula_crypto::Result<()> {
+    ///
+    /// **Walkable-v8 (W.9.2 seam, W.9.3 self-verify):**
+    /// when `Config::walkable_v8_writer_enabled = true`, the master's
+    /// PUT-response ETag is parsed as a CID and locally re-verified
+    /// against `BLAKE3(ciphertext)` via
+    /// `walkable_v8::verify_etag_matches_ciphertext` before being
+    /// surfaced in [`BlobPutResult.cid`]. Mismatches soft-fail to `None`
+    /// (with a rate-limited `tracing::warn!`) so a compromised master
+    /// cannot redirect future offline walkers to attacker-controlled
+    /// IPFS bytes. When the flag is `false` (the default during the
+    /// v0.6.x rollout), the parse path is skipped entirely and `cid` is
+    /// always `None` — write semantics stay byte-identical to v0.5.
+    ///
+    /// Soft-fail rationale: the PUT itself succeeded, the chunk is stored
+    /// and pinned, only the offline-walk hint is missing; readers fall
+    /// back to the storage-key path. Hard-erroring on parse failure
+    /// would regress the v7 write path under any deploy where master's
+    /// etag format drifts.
+    async fn put(&self, path: &str, bytes: Vec<u8>) -> fula_crypto::Result<BlobPutResult> {
         let mut attempt: u32 = 0;
+        let walkable_v8 = self.inner.config().walkable_v8_writer_enabled;
         loop {
             attempt += 1;
             // Clone the body each attempt: reqwest consumes the body, and we
@@ -398,7 +417,26 @@ impl BlobBackend for S3BlobBackend {
             // negligible on the happy path too.
             let body = bytes.clone();
             match self.inner.put_object(&self.bucket, path, body).await {
-                Ok(_) => return Ok(()),
+                Ok(result) => {
+                    // The CID returned here is from the *successful* PUT
+                    // attempt — the loop only reaches this `Ok` arm on a
+                    // 200 response. Stale CIDs from prior retried attempts
+                    // never propagate.
+                    let cid = if walkable_v8 {
+                        crate::walkable_v8::verify_etag_matches_ciphertext(
+                            &result.etag,
+                            &bytes,
+                            &self.bucket,
+                            path,
+                        )
+                    } else {
+                        // Writer flag off — skip the parse entirely so write
+                        // semantics stay byte-identical to v0.5. Readers fall
+                        // through to the storage-key path.
+                        None
+                    };
+                    return Ok(BlobPutResult { cid });
+                }
                 Err(e)
                     if attempt < BLOB_BACKEND_MAX_ATTEMPTS
                         && crate::multipart::is_transient(&e) =>
@@ -437,11 +475,31 @@ impl BlobBackend for S3BlobBackend {
         Ok(result.inner.data.to_vec())
     }
 
-    async fn put(&self, path: &str, bytes: Vec<u8>) -> fula_crypto::Result<()> {
+    async fn put(&self, path: &str, bytes: Vec<u8>) -> fula_crypto::Result<BlobPutResult> {
+        // W.9.3: same self-verify gate as the non-wasm impl above. The
+        // wasm path has no retry loop so we clone the body up-front
+        // (the post-PUT verify needs the bytes; `put_object` consumes
+        // them) before dispatching.
+        let walkable_v8 = self.inner.config().walkable_v8_writer_enabled;
+        let body = if walkable_v8 { Some(bytes.clone()) } else { None };
+        let bucket = &self.bucket;
         self.inner
             .put_object(&self.bucket, path, bytes)
             .await
-            .map(|_| ())
+            .map(|result| {
+                let cid = if walkable_v8 {
+                    let cipher = body.as_deref().unwrap_or(&[]);
+                    crate::walkable_v8::verify_etag_matches_ciphertext(
+                        &result.etag,
+                        cipher,
+                        bucket,
+                        path,
+                    )
+                } else {
+                    None
+                };
+                BlobPutResult { cid }
+            })
             .map_err(client_err_to_crypto)
     }
 }
@@ -3604,6 +3662,11 @@ impl EncryptedClient {
         // migration gap where deferred-upload paths leave a bucket on
         // legacy=true plaintext until the next root commit.
         let lookup_h_hex = self.compute_bucket_lookup_h_hex(bucket);
+        // Walkable-v8 (W.9.3): hoist the writer flag above both the page
+        // loop and the dir-index commit so every Phase 1.5/1.6 PUT in
+        // this flush sees the same Config snapshot. Reading it once up
+        // front also avoids a per-PUT atomic read of the config field.
+        let walkable_v8 = self.inner.config().walkable_v8_writer_enabled;
         for page_id in dirty_pages.iter().copied() {
             let page = manifest_snapshot.pages.get_mut(&page_id)
                 .ok_or_else(|| ClientError::Encryption(
@@ -3630,6 +3693,18 @@ impl EncryptedClient {
             let envelope = EncryptedManifestPage::encrypt(page, &forest_dek, bucket)
                 .map_err(ClientError::Encryption)?;
             let blob = envelope.to_bytes().map_err(ClientError::Encryption)?;
+            // Walkable-v8 (W.9.3): pre-compute `BLAKE3(blob)` so the
+            // post-PUT self-verify can compare master's ETag-attested CID
+            // to a CID we computed locally (defense-in-depth against a
+            // compromised master attesting an attacker-chosen CID). Cheap
+            // ~1 GB/s SIMD hash; only computed when the writer flag is on
+            // so v0.5-default behaviour stays byte-identical. `walkable_v8`
+            // hoisted to flush-loop scope above so Phase 1.6 below sees it.
+            let expected_page_cid = if walkable_v8 {
+                Some(crate::walkable_v8::local_blake3_raw_cid(&blob))
+            } else {
+                None
+            };
             let page_key = derive_manifest_page_key(&forest_dek, bucket, &shard_salt, page_id);
             let metadata = ObjectMetadata::new()
                 .with_content_type("application/octet-stream")
@@ -3714,9 +3789,24 @@ impl EncryptedClient {
             ) {
                 tracing::warn!(%bucket, page_id, error = %e, "WAL append post-PUT PageWrote failed");
             }
+            // Walkable-v8 (W.9.3): stamp the CID hint into the new
+            // PageRef when the writer flag is on AND master's etag both
+            // parses as a CID and matches our locally-computed
+            // BLAKE3(blob). On any failure, falls back to `cid: None`
+            // — readers walk via the storage_key path. The hash was
+            // pre-computed before `Bytes::from(blob)` consumed the body.
+            let page_cid = match (walkable_v8, expected_page_cid, etag.as_deref()) {
+                (true, Some(expected), Some(et)) => {
+                    crate::walkable_v8::verify_etag_against_expected_cid(
+                        et, expected, bucket, &page_key,
+                    )
+                }
+                _ => None,
+            };
             manifest_snapshot.root.page_index.insert(page_id, PageRef {
                 etag,
                 seq: page.seq,
+                cid: page_cid,
             });
         }
 
@@ -3751,6 +3841,15 @@ impl EncryptedClient {
                 next_dir_seq,
             ).map_err(ClientError::Encryption)?;
             let blob = envelope.to_bytes().map_err(ClientError::Encryption)?;
+            // Walkable-v8 (W.9.3): pre-compute `BLAKE3(dir-index blob)` for
+            // post-PUT self-verify. Reuses the same per-flush gate value
+            // captured before Phase 1.5 above (every page in this flush
+            // shares the same Config.walkable_v8_writer_enabled snapshot).
+            let expected_dir_cid = if walkable_v8 {
+                Some(crate::walkable_v8::local_blake3_raw_cid(&blob))
+            } else {
+                None
+            };
             let dir_key = derive_dir_index_key(&forest_dek, bucket);
             let metadata = ObjectMetadata::new()
                 .with_content_type("application/octet-stream")
@@ -3818,8 +3917,18 @@ impl EncryptedClient {
             ) {
                 tracing::warn!(%bucket, error = %e, "WAL append post-PUT DirIndexWrote failed");
             }
+            // Walkable-v8 (W.9.3): stamp dir_index_cid via self-verify.
+            let dir_index_cid = match (walkable_v8, expected_dir_cid, new_dir_etag.as_deref()) {
+                (true, Some(expected), Some(et)) => {
+                    crate::walkable_v8::verify_etag_against_expected_cid(
+                        et, expected, bucket, &dir_key,
+                    )
+                }
+                _ => None,
+            };
             manifest_snapshot.root.dir_index_etag = new_dir_etag;
             manifest_snapshot.root.dir_index_seq = Some(next_dir_seq);
+            manifest_snapshot.root.dir_index_cid = dir_index_cid;
             Some(next_dir_seq)
         } else {
             None
@@ -4203,7 +4312,7 @@ impl EncryptedClient {
         // values for `If-Match` and converge with master's state.
         let mut root = root;
         for (page_id, etag, seq) in page_overrides {
-            root.page_index.insert(page_id, PageRef { etag, seq });
+            root.page_index.insert(page_id, PageRef { etag, seq, cid: None });
         }
         ShardManifestV7::from_root_and_pages(root, pages)
             .map_err(ClientError::Encryption)
@@ -4672,6 +4781,15 @@ impl EncryptedClient {
                     });
                 }
             };
+            // Walkable-v8 (W.9.3): mirror the flush_forest path's pre-PUT
+            // hash so the v1→v7 migration's freshly-written pages also
+            // carry CID hints when the writer flag is on.
+            let walkable_v8_mig = self.inner.config().walkable_v8_writer_enabled;
+            let expected_page_cid = if walkable_v8_mig {
+                Some(crate::walkable_v8::local_blake3_raw_cid(&blob))
+            } else {
+                None
+            };
             let page_key = derive_manifest_page_key(forest_dek, bucket, &shard_salt, page_id);
             // If-None-Match=*: migration uses a fresh random shard_salt, so each
             // page key is first-ever on this bucket. Any 412 here means another
@@ -4714,9 +4832,20 @@ impl EncryptedClient {
             ) {
                 tracing::warn!(%bucket, page_id, error = %e, "migration: WAL append post-PUT PageWrote failed");
             }
+            // Walkable-v8 (W.9.3): same self-verify pattern as the
+            // flush_forest path above.
+            let page_cid = match (walkable_v8_mig, expected_page_cid, etag.as_deref()) {
+                (true, Some(expected), Some(et)) => {
+                    crate::walkable_v8::verify_etag_against_expected_cid(
+                        et, expected, bucket, &page_key,
+                    )
+                }
+                _ => None,
+            };
             manifest_snapshot.root.page_index.insert(page_id, PageRef {
                 etag,
                 seq: page.seq,
+                cid: page_cid,
             });
         }
 
@@ -4752,6 +4881,15 @@ impl EncryptedClient {
                 });
             }
         };
+        // Walkable-v8 (W.9.3): mirror flush_forest's pre-PUT hash for
+        // the dir-index PUT so v1→v7 migrations also stamp dir_index_cid
+        // when the writer flag is on.
+        let walkable_v8_dir_mig = self.inner.config().walkable_v8_writer_enabled;
+        let expected_dir_index_cid = if walkable_v8_dir_mig {
+            Some(crate::walkable_v8::local_blake3_raw_cid(&dir_index_blob))
+        } else {
+            None
+        };
         let dir_index_key = derive_dir_index_key(forest_dek, bucket);
         // Unconditional overwrite is required: the dir-index key is stable
         // across migrations (no shard_salt in its derivation), so a legitimate
@@ -4790,8 +4928,23 @@ impl EncryptedClient {
         ) {
             tracing::warn!(%bucket, error = %e, "migration: WAL append post-PUT DirIndexWrote failed");
         }
+        // Walkable-v8 (W.9.3): stamp dir_index_cid via self-verify, same
+        // pattern as flush_forest's Phase 1.6 above.
+        let dir_index_cid_mig = match (
+            walkable_v8_dir_mig,
+            expected_dir_index_cid,
+            new_dir_index_etag.as_deref(),
+        ) {
+            (true, Some(expected), Some(et)) => {
+                crate::walkable_v8::verify_etag_against_expected_cid(
+                    et, expected, bucket, &dir_index_key,
+                )
+            }
+            _ => None,
+        };
         manifest_snapshot.root.dir_index_etag = new_dir_index_etag;
         manifest_snapshot.root.dir_index_seq = Some(dir_index_seq);
+        manifest_snapshot.root.dir_index_cid = dir_index_cid_mig;
 
         let manifest_seq: u64 = 1;
         let manifest_data = match EncryptedShardManifestV7::encrypt_v7(
@@ -5042,15 +5195,23 @@ impl EncryptedClient {
         let is_chunked_upload = should_use_chunked(data.len());
 
         // Check if we need chunked upload (for IPFS block size limit).
-        // Both branches return `(PutObjectResult, enc_metadata_json)` so
-        // the post-upload code below can stash the JSON onto the forest
-        // entry's `user_metadata`. That stash is the load-bearing change
-        // for offline / cold-start encrypted reads: the forest blob is
+        //
+        // Both branches return `(PutObjectResult, enc_metadata_json,
+        // Option<Cid>)`. The third element is walkable-v8 (W.9.3): the
+        // verified CID of the index/single object, which the caller
+        // stamps into `ForestFileEntry.storage_cid`.
+        //
+        // The `enc_metadata_json` stash is the load-bearing change for
+        // offline / cold-start encrypted reads: the forest blob is
         // AEAD-encrypted with `forest_dek` (derived from the user's
         // KEK), so the metadata travels privately, while making the
         // SDK self-sufficient when HTTP user-metadata headers are
         // unavailable (gateway path, warm-cache path).
-        let (result, enc_metadata_json): (PutObjectResult, String) = if is_chunked_upload {
+        let (result, enc_metadata_json, index_cid_opt): (
+            PutObjectResult,
+            String,
+            Option<cid::Cid>,
+        ) = if is_chunked_upload {
             // CHUNKED UPLOAD: Split into chunks under IPFS 1MB limit
             self.put_object_chunked_internal(
                 bucket,
@@ -5087,6 +5248,17 @@ impl EncryptedClient {
                 .with_metadata("x-fula-encrypted", "true")
                 .with_metadata("x-fula-encryption", &enc_metadata_str);
 
+            // Walkable-v8 (W.9.3): pre-compute `BLAKE3(ciphertext)` for
+            // post-PUT self-verify before `Bytes::from(ciphertext)`
+            // consumes the buffer. Skip when the flag is off so the
+            // hash isn't computed for v0.5-default writes.
+            let walkable_v8 = self.inner.config().walkable_v8_writer_enabled;
+            let expected_obj_cid = if walkable_v8 {
+                Some(crate::walkable_v8::local_blake3_raw_cid(&ciphertext))
+            } else {
+                None
+            };
+
             let put_result = if let Some(ref pinning) = self.pinning {
                 self.inner.put_object_with_metadata_and_pinning(
                     bucket,
@@ -5104,9 +5276,32 @@ impl EncryptedClient {
                     Some(metadata),
                 ).await?
             };
-            (put_result, enc_metadata_str)
+
+            // Walkable-v8 (W.9.3): verify and surface the CID for the
+            // caller to stamp into ForestFileEntry.storage_cid. None on
+            // any failure path — readers fall back to the storage_key
+            // path.
+            let cid = match (walkable_v8, expected_obj_cid) {
+                (true, Some(expected)) => crate::walkable_v8::verify_etag_against_expected_cid(
+                    &put_result.etag,
+                    expected,
+                    bucket,
+                    &storage_key,
+                ),
+                _ => None,
+            };
+            (put_result, enc_metadata_str, cid)
         };
 
+        // Walkable-v8 (W.9.3): stamp the index/single-object CID hint
+        // onto the forest entry BEFORE upsert. Offline readers walk
+        // ForestFileEntry → storage_cid → fetch via gateway race when
+        // master is down. None when the writer flag is off or
+        // self-verify failed; reads fall through to the storage_key
+        // path. Per-chunk hints are not surfaced — that needs a
+        // ChunkedFileMetadata wire-format extension (followup #32).
+        forest_entry.storage_cid = index_cid_opt;
+
         // Stash the encryption metadata onto the forest entry. The forest
         // blob is AEAD-encrypted with `forest_dek` (derived from user's
         // KEK), so the metadata is privacy-preserving — only the user
@@ -5248,6 +5443,14 @@ impl EncryptedClient {
     /// powers the offline / cold-start decrypt paths without leaking
     /// any plaintext (the JSON only travels inside the AEAD-encrypted
     /// forest blob).
+    /// Walkable-v8 (W.9.3): the third tuple element is the parsed CID
+    /// of the **index object** (the small JSON metadata blob master
+    /// returns the etag for at the bucket-key path), self-verified
+    /// against `BLAKE3(index_body)`. `Some(cid)` when the writer flag
+    /// is on and verification succeeds; `None` otherwise. Caller
+    /// stamps it into `ForestFileEntry.storage_cid`. Per-chunk CIDs
+    /// are NOT surfaced — that needs a `ChunkedFileMetadata` wire
+    /// format extension (followup task #32).
     async fn put_object_chunked_internal(
         &self,
         bucket: &str,
@@ -5257,7 +5460,7 @@ impl EncryptedClient {
         wrapped_dek: &EncryptedData,
         encrypted_meta: &EncryptedPrivateMetadata,
         kek_version: u32,
-    ) -> Result<(PutObjectResult, String)> {
+    ) -> Result<(PutObjectResult, String, Option<cid::Cid>)> {
         // Create chunked encoder with AAD binding chunks to storage key
         let aad_prefix = format!("fula:v4:chunk:{}", storage_key);
         let mut encoder = ChunkedEncoder::with_aad(dek.clone(), aad_prefix);
@@ -5356,7 +5559,18 @@ impl EncryptedClient {
             .with_metadata("x-fula-encrypted", "true")
             .with_metadata("x-fula-chunked", "true")
             .with_metadata("x-fula-encryption", &index_body);
-        
+
+        // Walkable-v8 (W.9.3): pre-compute `BLAKE3(index_body)` so the
+        // post-PUT self-verify can compare master's etag-attested CID
+        // against a CID we computed locally. Cheap; only when the
+        // writer flag is on.
+        let walkable_v8 = self.inner.config().walkable_v8_writer_enabled;
+        let expected_index_cid = if walkable_v8 {
+            Some(crate::walkable_v8::local_blake3_raw_cid(index_body.as_bytes()))
+        } else {
+            None
+        };
+
         // Upload index object. If this fails after all chunks were successfully
         // uploaded, we must compensate by deleting the chunks — otherwise the
         // upload is non-atomic and leaks storage.
@@ -5389,11 +5603,26 @@ impl EncryptedClient {
             }
         };
 
-        // Return both the upload result AND the JSON metadata the caller
-        // will stash on the forest entry. `index_body` IS the same JSON
-        // we just persisted as the index object's body and HTTP header
-        // — handing it back avoids the caller re-serializing.
-        Ok((result, index_body))
+        // Walkable-v8 (W.9.3): self-verify the index-object CID. Caller
+        // stamps it into `ForestFileEntry.storage_cid` so an offline
+        // reader can fetch this index blob via gateway race when master
+        // is down.
+        let index_cid = match (walkable_v8, expected_index_cid) {
+            (true, Some(expected)) => crate::walkable_v8::verify_etag_against_expected_cid(
+                &result.etag,
+                expected,
+                bucket,
+                storage_key,
+            ),
+            _ => None,
+        };
+
+        // Return the upload result, the JSON metadata the caller will
+        // stash on the forest entry, and the verified index-object CID.
+        // `index_body` IS the same JSON we just persisted as the index
+        // object's body and HTTP header — handing it back avoids the
+        // caller re-serializing.
+        Ok((result, index_body, index_cid))
     }
 
     /// Upload an object with resumable chunked encoding.
@@ -7724,6 +7953,10 @@ impl EncryptedClient {
             // H-2: entry is written under v4 AAD-bound encryption; reject
             // any later download that advertises a lower blob-format version.
             min_version: 4,
+            // Walkable-v8 (W.9.1b): chunk CID hint not stamped here yet.
+            // W.9.3 wires the writer to capture the CID from S3BlobBackend's
+            // PUT response and populate this field.
+            storage_cid: None,
         };
 
         let v7_forest_arc = {