From 6b6c0ae939995a5297b373a272602b77bb890e04 Mon Sep 17 00:00:00 2001 From: "Ryan.K" <662346+RyanKung@users.noreply.github.com> Date: Tue, 21 Jul 2026 03:23:48 +0800 Subject: [PATCH 01/23] Add gateway webview and pending connection admission --- .gitignore | 3 + Cargo.lock | 176 ++- crates/core/src/dht/chord.rs | 18 +- crates/core/src/dht/chord_tests.rs | 4 +- crates/core/src/dht/stabilization.rs | 7 +- crates/core/src/dht/storage/mod.rs | 2 +- crates/core/src/dht/storage/repair.rs | 4 +- crates/core/src/dht/storage/sync.rs | 6 +- crates/core/src/dht/storage/tests.rs | 4 +- crates/core/src/dht/types.rs | 24 +- crates/core/src/error.rs | 55 +- crates/core/src/measure.rs | 24 +- crates/core/src/message/effects.rs | 6 + .../core/src/message/handlers/connection.rs | 92 +- crates/core/src/message/handlers/custom.rs | 4 +- crates/core/src/message/handlers/e2e.rs | 12 +- crates/core/src/message/handlers/mod.rs | 41 +- .../src/message/handlers/stabilization.rs | 10 +- crates/core/src/message/handlers/storage.rs | 50 +- crates/core/src/message/handlers/subring.rs | 8 +- crates/core/src/message/payload.rs | 4 +- crates/core/src/storage/memory.rs | 6 +- crates/core/src/storage/mod.rs | 11 +- crates/core/src/swarm/callback.rs | 91 +- crates/core/src/swarm/mod.rs | 24 +- crates/core/src/swarm/transport.rs | 536 +++++++-- crates/core/src/swarm/transport/tests.rs | 95 ++ crates/core/src/tests/default/mod.rs | 19 +- .../core/src/tests/default/test_chunk_e2e.rs | 14 + .../core/src/tests/default/test_connection.rs | 37 +- .../src/tests/default/test_message_handler.rs | 47 +- crates/core/src/tests/mod.rs | 7 +- crates/core/src/utils.rs | 6 +- crates/derive/src/lib.rs | 12 +- crates/node/src/processor/builder.rs | 4 +- crates/node/src/processor/config.rs | 4 +- crates/node/src/processor/mod.rs | 27 + .../node/src/processor/tests/test_config.rs | 8 +- .../node/src/processor/tests/test_network.rs | 33 +- crates/node/src/provider/browser/provider.rs | 4 +- crates/transport/src/connection_ref.rs | 11 +- crates/transport/src/connections/mod.rs | 20 +- crates/transport/src/core/callback.rs | 11 +- crates/transport/src/core/pool.rs | 7 +- crates/transport/src/core/transport.rs | 18 +- crates/transport/src/delivery.rs | 4 +- crates/transport/src/error.rs | 4 +- crates/transport/src/lib.rs | 8 - crates/transport/src/notifier.rs | 25 +- crates/transport/src/pool.rs | 4 +- crates/webview/Cargo.toml | 35 + crates/webview/src/browser.rs | 1006 ++++++++++++++++ crates/webview/src/cookie.rs | 225 ++++ crates/webview/src/cors.rs | 277 +++++ crates/webview/src/error.rs | 46 + crates/webview/src/header.rs | 218 ++++ crates/webview/src/lib.rs | 59 + crates/webview/src/render.rs | 169 +++ crates/webview/src/rewrite.rs | 677 +++++++++++ crates/webview/src/route.rs | 346 ++++++ crates/webview/src/transport.rs | 678 +++++++++++ crates/webview/src/types.rs | 216 ++++ crates/webview/src/url.rs | 156 +++ crates/webview/tests/browser_gateway.rs | 1056 +++++++++++++++++ crates/webview/tests/webview_flow.rs | 281 +++++ docker/cluster/Dockerfile | 1 + frontend/Cargo.lock | 196 ++- frontend/Cargo.toml | 4 + frontend/Trunk.toml | 1 + frontend/assets/webview-host.js | 182 +++ frontend/index.html | 5 +- frontend/rings-webview-service-worker.js | 422 +++++++ frontend/src/app.rs | 25 + frontend/src/app/actions.rs | 18 + frontend/src/browser_api.rs | 30 + frontend/src/controls.rs | 36 + frontend/src/controls/sidebar.rs | 18 +- frontend/src/lib.rs | 5 + frontend/src/node.rs | 18 + frontend/src/onion.rs | 40 +- frontend/src/styles/components.css | 334 ++++++ frontend/src/styles/dialogs.css | 24 +- frontend/src/styles/features.css | 62 +- frontend/src/styles/responsive.css | 51 + frontend/src/styles/theme/console.rs | 9 +- frontend/src/styles/theme/dialogs.rs | 10 +- frontend/src/styles/theme/topology.rs | 27 +- frontend/src/topology.rs | 147 ++- frontend/src/webview.rs | 932 +++++++++++++++ frontend/src/webview_ui.rs | 111 ++ frontend/src/workbench.rs | 10 +- 91 files changed, 9275 insertions(+), 539 deletions(-) create mode 100644 crates/webview/Cargo.toml create mode 100644 crates/webview/src/browser.rs create mode 100644 crates/webview/src/cookie.rs create mode 100644 crates/webview/src/cors.rs create mode 100644 crates/webview/src/error.rs create mode 100644 crates/webview/src/header.rs create mode 100644 crates/webview/src/lib.rs create mode 100644 crates/webview/src/render.rs create mode 100644 crates/webview/src/rewrite.rs create mode 100644 crates/webview/src/route.rs create mode 100644 crates/webview/src/transport.rs create mode 100644 crates/webview/src/types.rs create mode 100644 crates/webview/src/url.rs create mode 100644 crates/webview/tests/browser_gateway.rs create mode 100644 crates/webview/tests/webview_flow.rs create mode 100644 frontend/assets/webview-host.js create mode 100644 frontend/rings-webview-service-worker.js create mode 100644 frontend/src/webview.rs create mode 100644 frontend/src/webview_ui.rs diff --git a/.gitignore b/.gitignore index 5c78a733b..6892af0c0 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,9 @@ config*.yaml **/*.ipynb **/*.js **/*.mjs +!frontend/assets/webview-host.js +!frontend/rings-webview-service-worker.js +frontend/dist-e2e/ .ipynb_checkpoints # Local environment configuration .envrc diff --git a/Cargo.lock b/Cargo.lock index 21ed39eca..b5e0e33bc 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -861,9 +861,9 @@ dependencies = [ [[package]] name = "cfg-if" -version = "1.0.1" +version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9555578bc9e57714c812a1f84e4fc5b4d21fcb063490c624de019f7464c91268" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" [[package]] name = "cfg_aliases" @@ -1368,6 +1368,29 @@ dependencies = [ "subtle", ] +[[package]] +name = "cssparser" +version = "0.36.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dae61cf9c0abb83bd659dab65b7e4e38d8236824c85f0f804f173567bda257d2" +dependencies = [ + "cssparser-macros", + "dtoa-short", + "itoa", + "phf", + "smallvec", +] + +[[package]] +name = "cssparser-macros" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13b588ba4ac1a99f7f2964d24b3d896ddc6bf847ee3855dbd4366f058cfcd331" +dependencies = [ + "quote", + "syn 2.0.104", +] + [[package]] name = "ctr" version = "0.9.2" @@ -1660,6 +1683,21 @@ dependencies = [ "x509-parser", ] +[[package]] +name = "dtoa" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590" + +[[package]] +name = "dtoa-short" +version = "0.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd1511a7b6a56299bd043a9c167a6d2bfb37bf84a6dfceaba651168adfb43c87" +dependencies = [ + "dtoa", +] + [[package]] name = "ecdsa" version = "0.16.9" @@ -1761,6 +1799,15 @@ dependencies = [ "log", ] +[[package]] +name = "encoding_rs" +version = "0.8.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3" +dependencies = [ + "cfg-if", +] + [[package]] name = "enum-iterator" version = "2.3.0" @@ -2288,6 +2335,8 @@ version = "0.17.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" dependencies = [ + "allocator-api2", + "equivalent", "foldhash", ] @@ -3083,6 +3132,25 @@ version = "0.4.33" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" +[[package]] +name = "lol_html" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ae574a677ef0443a0bd3c291f0cab9d1e61a3ad85a1515e3cfc0bc720d5a48e" +dependencies = [ + "bitflags 2.13.0", + "cfg-if", + "cssparser", + "encoding_rs", + "foldhash", + "hashbrown 0.17.1", + "memchr", + "mime", + "precomputed-hash", + "selectors", + "thiserror 2.0.18", +] + [[package]] name = "lru-slab" version = "0.1.2" @@ -3142,9 +3210,9 @@ dependencies = [ [[package]] name = "memchr" -version = "2.7.5" +version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "32a282da65faaf38286cf3be983213fcf1d2e2a58700e808f83f4ea9a4804bc0" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" [[package]] name = "memmap2" @@ -3655,6 +3723,50 @@ dependencies = [ "indexmap", ] +[[package]] +name = "phf" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1562dc717473dbaa4c1f85a36410e03c047b2e7df7f45ee938fbef64ae7fadf" +dependencies = [ + "phf_macros", + "phf_shared 0.13.1", + "serde", +] + +[[package]] +name = "phf_codegen" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49aa7f9d80421bca176ca8dbfebe668cc7a2684708594ec9f3c0db0805d5d6e1" +dependencies = [ + "phf_generator", + "phf_shared 0.13.1", +] + +[[package]] +name = "phf_generator" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "135ace3a761e564ec88c03a77317a7c6b80bb7f7135ef2544dbe054243b89737" +dependencies = [ + "fastrand", + "phf_shared 0.13.1", +] + +[[package]] +name = "phf_macros" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "812f032b54b1e759ccd5f8b6677695d5268c588701effba24601f6932f8269ef" +dependencies = [ + "phf_generator", + "phf_shared 0.13.1", + "proc-macro2", + "quote", + "syn 2.0.104", +] + [[package]] name = "phf_shared" version = "0.11.3" @@ -3664,6 +3776,15 @@ dependencies = [ "siphasher", ] +[[package]] +name = "phf_shared" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e57fef6bc5981e38c2ce2d63bfa546861309f875b8a75f092d1d54ae2d64f266" +dependencies = [ + "siphasher", +] + [[package]] name = "pin-project" version = "1.1.10" @@ -4529,6 +4650,23 @@ dependencies = [ "webrtc", ] +[[package]] +name = "rings-webview" +version = "0.14.0" +dependencies = [ + "async-trait", + "futures", + "js-sys", + "lol_html", + "percent-encoding", + "serde", + "serde-wasm-bindgen", + "thiserror 1.0.69", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", +] + [[package]] name = "rkyv" version = "0.8.16" @@ -4754,6 +4892,25 @@ dependencies = [ "zeroize", ] +[[package]] +name = "selectors" +version = "0.37.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2cfaaa6035167f0e604e42723c7650d59ee269ef220d7bbe0565602c8a0173b9" +dependencies = [ + "bitflags 2.13.0", + "cssparser", + "derive_more", + "log", + "new_debug_unreachable", + "phf", + "phf_codegen", + "precomputed-hash", + "rustc-hash", + "servo_arc", + "smallvec", +] + [[package]] name = "self_cell" version = "1.2.0" @@ -4892,6 +5049,15 @@ dependencies = [ "serde", ] +[[package]] +name = "servo_arc" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "170fb83ab34de17dc69aa7c67482b22218ddb85da56546f9bd6b929e32a05930" +dependencies = [ + "stable_deref_trait", +] + [[package]] name = "sha1" version = "0.10.6" @@ -5129,7 +5295,7 @@ checksum = "bf776ba3fa74f83bf4b63c3dcbbf82173db2632ed8452cb2d891d33f459de70f" dependencies = [ "new_debug_unreachable", "parking_lot 0.12.4", - "phf_shared", + "phf_shared 0.11.3", "precomputed-hash", ] diff --git a/crates/core/src/dht/chord.rs b/crates/core/src/dht/chord.rs index eb16f1151..31fb41b0b 100644 --- a/crates/core/src/dht/chord.rs +++ b/crates/core/src/dht/chord.rs @@ -42,12 +42,12 @@ use crate::storage::MemStorage; /// `EntryStorage` is the type accepted by `PeerRing::new_with_storage`. /// It's used to store [Entry]s in a storage media provided by user. -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] pub type EntryStorage = Box>; /// `EntryStorage` is the type accepted by `PeerRing::new_with_storage`. /// It's used to store [Entry]s in a storage media provided by user. -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] pub type EntryStorage = Box + Send + Sync>; /// PeerRing is used to help a node interact with other nodes. @@ -584,8 +584,8 @@ impl PeerRing { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl ChordStorage for PeerRing { /// Look up an [`Entry`] by its ring key. /// Always finds resource by finger table, ignoring the local cache. @@ -644,8 +644,8 @@ impl ChordStorage for PeerRing } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl ChordStorageCache for PeerRing { /// Cache fetched `entry` locally. async fn local_cache_put(&self, entry: Entry) -> Result<()> { @@ -658,8 +658,8 @@ impl ChordStorageCache for PeerRing { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl CorrectChord for PeerRing { /// When Chord have a new successor, ask the new successor for successor list async fn update_successor(&self, did: impl LiveDid) -> Result { @@ -773,6 +773,6 @@ impl CorrectChord for PeerRing { } } -#[cfg(all(not(feature = "wasm"), test))] +#[cfg(all(not(all(feature = "wasm", target_family = "wasm")), test))] #[path = "chord_tests.rs"] mod tests; diff --git a/crates/core/src/dht/chord_tests.rs b/crates/core/src/dht/chord_tests.rs index a75598231..f239f01da 100644 --- a/crates/core/src/dht/chord_tests.rs +++ b/crates/core/src/dht/chord_tests.rs @@ -304,8 +304,8 @@ async fn test_correct_chord_impl() -> Result<()> { assert!(!assert_successor(n1, &n5.did)); #[allow(non_local_definitions)] - #[cfg_attr(feature = "wasm", async_trait(?Send))] - #[cfg_attr(not(feature = "wasm"), async_trait)] + #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] + #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl LiveDid for Did { async fn live(&self) -> bool { true diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs index 0ffe34740..916593c04 100644 --- a/crates/core/src/dht/stabilization.rs +++ b/crates/core/src/dht/stabilization.rs @@ -92,7 +92,8 @@ impl Stabilizer { /// Clean unavailable connections in transport. pub async fn clean_unavailable_connections(&self) -> Result<()> { - let conns = self.transport.get_connections(); + self.transport.expire_pending_connections().await?; + let conns = self.transport.admitted_connections(); for (did, conn) in conns.into_iter() { // Only terminal states are cleaned. `Disconnected` is transient: ICE @@ -199,7 +200,7 @@ impl Stabilizer { } } -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] mod stabilizer { use std::sync::Arc; use std::time::Duration; @@ -228,7 +229,7 @@ mod stabilizer { } } -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] mod stabilizer { use std::sync::Arc; use std::time::Duration; diff --git a/crates/core/src/dht/storage/mod.rs b/crates/core/src/dht/storage/mod.rs index 13002660f..1e0a86dd0 100644 --- a/crates/core/src/dht/storage/mod.rs +++ b/crates/core/src/dht/storage/mod.rs @@ -327,5 +327,5 @@ impl PeerRing { } } -#[cfg(all(not(feature = "wasm"), test))] +#[cfg(all(not(all(feature = "wasm", target_family = "wasm")), test))] mod tests; diff --git a/crates/core/src/dht/storage/repair.rs b/crates/core/src/dht/storage/repair.rs index 76ec85a6d..0dca04b39 100644 --- a/crates/core/src/dht/storage/repair.rs +++ b/crates/core/src/dht/storage/repair.rs @@ -222,8 +222,8 @@ impl PeerRing { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl ChordStorageRepair for PeerRing { async fn republish_local_entries(&self, redundancy: u16) -> Result { if redundancy <= 1 { diff --git a/crates/core/src/dht/storage/sync.rs b/crates/core/src/dht/storage/sync.rs index 451fcfd2d..41ecfd2a0 100644 --- a/crates/core/src/dht/storage/sync.rs +++ b/crates/core/src/dht/storage/sync.rs @@ -58,7 +58,7 @@ fn placed_entry_wire_cost(placed: &PlacedEntry) -> Result { serialized_wire_size(placed) } -#[cfg(all(test, not(feature = "wasm")))] +#[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))] pub(super) fn sync_entries_batch_wire_cost(data: &[PlacedEntry]) -> Result { let mut cost = sync_entries_fixed_wire_cost()?; for placed in data { @@ -111,8 +111,8 @@ pub(super) fn sync_entries_batches( Ok(batches) } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl ChordStorageSync for PeerRing { /// When the successor of a node is updated, it needs to check if there are /// `Entry`s that are no longer between current node and `new_successor`, diff --git a/crates/core/src/dht/storage/tests.rs b/crates/core/src/dht/storage/tests.rs index c222b78ec..24531bb69 100644 --- a/crates/core/src/dht/storage/tests.rs +++ b/crates/core/src/dht/storage/tests.rs @@ -160,8 +160,8 @@ fn placed_entries_by_key(entries: impl IntoIterator) -> BTre struct FailingGetStorageFixture; -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl KvStorageInterface for FailingGetStorageFixture { // Test-only fixture for the read-error boundary. Browser/localStorage // adapters are production storage implementations and are cfg-excluded here. diff --git a/crates/core/src/dht/types.rs b/crates/core/src/dht/types.rs index 361521159..52f0d6f89 100644 --- a/crates/core/src/dht/types.rs +++ b/crates/core/src/dht/types.rs @@ -62,8 +62,8 @@ pub trait Chord { /// Some methods return an `Action`. It's because the real storing node may not be this /// node. The outer should take the action to forward the request to the real storing /// node. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ChordStorage: Chord { /// Look up an [`Entry`] by its ring key. /// Always finds resource by DHT, ignoring the local cache. @@ -74,8 +74,8 @@ pub trait ChordStorage: Chord { } /// ChordStorageSync defines storage hand-off triggered by ownership changes. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ChordStorageSync: Chord { /// When the successor of a node is updated, it needs to check if there are /// `Entry`s that are no longer between current node and `new_successor`, @@ -104,8 +104,8 @@ pub trait ChordStorageSync: Chord { /// Repair never deletes local copies. It only republishes a known [`Entry`] as /// a join delivery to the current affine placement set so missing owners can /// regain a copy. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ChordStorageRepair: Chord { /// Republish every locally stored entry to its current affine owners. /// @@ -127,8 +127,8 @@ pub trait ChordStorageRepair: Chord { } /// ChordStorageCache defines the basic API for getting and setting DHT cache storage. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ChordStorageCache: Chord { /// Cache fetched resource locally. async fn local_cache_put(&self, entry: Entry) -> Result<()>; @@ -166,8 +166,8 @@ pub trait ChordStorageCache: Chord { /// - `topo_info` is a helper function to get the topological info of the chord. /// /// Some methods return an `Action`. The reason is the same as [Chord]. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait CorrectChord: Chord { /// Join Operation in the paper. /// @@ -222,7 +222,7 @@ pub trait CorrectChord: Chord { /// /// Implementors of this trait must also be convertible into a `Did` type using the `Into` trait, and /// must satisfy some additional constraints (see below). -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] #[async_trait(?Send)] pub trait LiveDid: Into + Clone { /// Necessary method, should return true if a wrapped did is live. @@ -233,7 +233,7 @@ pub trait LiveDid: Into + Clone { /// /// Implementors of this trait must also be convertible into a `Did` type using the `Into` trait, and /// must satisfy some additional constraints (see below). -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] #[async_trait] pub trait LiveDid: Into + Clone + Send + Sync { /// Necessary method, should return true if a wrapped did is live. diff --git a/crates/core/src/error.rs b/crates/core/src/error.rs index 2418a08f1..c8b0c2571 100644 --- a/crates/core/src/error.rs +++ b/crates/core/src/error.rs @@ -268,6 +268,17 @@ pub enum Error { #[error("Found existing transport when answer offer from remote node")] AlreadyConnected, + /// Pending WebRTC connection capacity {capacity} is exhausted + #[error("Pending WebRTC connection capacity {capacity} is exhausted")] + PendingConnectionCapacityExceeded { + /// Maximum number of concurrent pending peers. + capacity: usize, + }, + + /// Failed to access the swarm connection lifecycle state + #[error("Failed to access the swarm connection lifecycle state")] + SwarmConnectionLifecycleLock, + /// You should not connect to yourself #[error("You should not connect to yourself")] ShouldNotConnectSelf, @@ -369,7 +380,7 @@ pub enum Error { #[error("Invalid entry kind")] InvalidEntryKind, - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC new peer connection failed #[error("RTC new peer connection failed")] RTCPeerConnectionCreateFailed(#[source] webrtc::Error), @@ -378,22 +389,22 @@ pub enum Error { #[error("RTC peer_connection not establish")] RTCPeerConnectionNotEstablish, - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC peer_connection fail to create offer #[error("RTC peer_connection fail to create offer")] RTCPeerConnectionCreateOfferFailed(#[source] webrtc::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// RTC peer_connection fail to create offer #[error("RTC peer_connection fail to create offer")] RTCPeerConnectionCreateOfferFailed(String), - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC peer_connection fail to create answer #[error("RTC peer_connection fail to create answer")] RTCPeerConnectionCreateAnswerFailed(#[source] webrtc::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// RTC peer_connection fail to create answer #[error("RTC peer_connection fail to create answer")] RTCPeerConnectionCreateAnswerFailed(String), @@ -402,12 +413,12 @@ pub enum Error { #[error("DataChannel message size not match, {0} < {1}")] RTCDataChannelMessageIncomplete(usize, usize), - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// DataChannel send text message failed #[error("DataChannel send text message failed")] RTCDataChannelSendTextFailed(#[source] webrtc::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// DataChannel send text message failed, {0} #[error("DataChannel send text message failed, {0}")] RTCDataChannelSendTextFailed(String), @@ -420,37 +431,37 @@ pub enum Error { #[error("DataChannel state not open")] RTCDataChannelStateNotOpen, - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC peer_connection add ice candidate error #[error("RTC peer_connection add ice candidate error")] RTCPeerConnectionAddIceCandidateError(#[source] webrtc::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// RTC peer_connection add ice candidate error #[error("RTC peer_connection add ice candidate error")] RTCPeerConnectionAddIceCandidateError(String), - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC peer_connection set local description failed #[error("RTC peer_connection set local description failed")] RTCPeerConnectionSetLocalDescFailed(#[source] webrtc::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// RTC peer_connection set local description failed #[error("RTC peer_connection set local description failed")] RTCPeerConnectionSetLocalDescFailed(String), - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC peer_connection set remote description failed #[error("RTC peer_connection set remote description failed")] RTCPeerConnectionSetRemoteDescFailed(#[source] webrtc::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// RTC peer_connection set remote description failed #[error("RTC peer_connection set remote description failed")] RTCPeerConnectionSetRemoteDescFailed(String), - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// RTC peer_connection failed to close it #[error("RTC peer_connection failed to close it")] RTCPeerConnectionCloseFailed(#[source] webrtc::Error), @@ -507,7 +518,7 @@ pub enum Error { #[error("Only SEND message can reset destination")] ResetDestinationNeedSend, - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// IndexedDB error, {0} #[error("IndexedDB error, {0}")] IDBError(rexie::Error), @@ -516,7 +527,7 @@ pub enum Error { #[error("Invalid capacity value")] InvalidCapacity, - #[cfg(not(feature = "wasm"))] + #[cfg(not(all(feature = "wasm", target_family = "wasm")))] /// Sled error, {0} #[error("Sled error, {0}")] SledError(sled::Error), @@ -561,22 +572,22 @@ pub enum Error { #[error("Peer's negotiated max_message_size {0} is too small to carry even one chunk")] PeerMaxMessageSizeTooSmall(usize), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// Cannot get property {0} from JsValue #[error("Cannot get property {0} from JsValue")] FailedOnGetProperty(String), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// Cannot set property {0} from JsValue #[error("Cannot set property {0} from JsValue")] FailedOnSetProperty(String), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// Error on ser/der JsValue #[error("Error on ser/der JsValue")] SerdeWasmBindgenError(#[from] serde_wasm_bindgen::Error), - #[cfg(feature = "wasm")] + #[cfg(all(feature = "wasm", target_family = "wasm"))] /// Error create RTC connection: {0} #[error("Error create RTC connection: {0}")] CreateConnectionError(String), @@ -600,14 +611,14 @@ impl Error { } } -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] impl From for wasm_bindgen::JsValue { fn from(err: Error) -> Self { wasm_bindgen::JsValue::from_str(&err.to_string()) } } -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] impl From for Error { fn from(err: js_sys::Error) -> Self { Error::JsError(err.to_string().into()) diff --git a/crates/core/src/measure.rs b/crates/core/src/measure.rs index dedd7f079..2eb440d81 100644 --- a/crates/core/src/measure.rs +++ b/crates/core/src/measure.rs @@ -8,11 +8,11 @@ use async_trait::async_trait; use crate::dht::Did; /// Type of Measure, see [Measure]. -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] pub type MeasureImpl = Arc; /// Type of Measure, see [crate::measure::Measure]. -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] pub type MeasureImpl = Arc; /// The tag of counters in measure. @@ -216,8 +216,8 @@ pub fn order_peers_by_quality( /// `Measure` is used to assess the reliability of peers by counting their behaviour. /// It currently count the number of sent and received messages in a given period (1 hour). /// The method [Measure::incr] should be called in the proper places. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait Measure { /// `incr` increments the counter of the given peer. async fn incr(&self, did: Did, counter: MeasureCounter); @@ -226,8 +226,8 @@ pub trait Measure { } /// `BehaviourJudgement` classifies local evidence about a peer. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait BehaviourJudgement: Measure { /// Classify local peer quality for DHT connection scheduling. /// @@ -246,8 +246,8 @@ pub trait BehaviourJudgement: Measure { /// `ConnectBehaviour` trait offers a default implementation for the `good` method, providing a judgement /// based on a node's behavior in establishing connections. /// The "goodness" of a node is measured by comparing disconnection counts against a given threshold. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ConnectBehaviour: Measure { /// This asynchronous method returns a boolean indicating whether the node identified by `did` has a satisfactory connection behavior. async fn good(&self, did: Did) -> bool { @@ -266,8 +266,8 @@ pub trait ConnectBehaviour: Measure { /// `MessageSendBehaviour` trait provides a default implementation for the `good` method, judging a node's /// behavior based on its message sending capabilities. /// The "goodness" of a node is measured by comparing the sent and failed-to-send counts against a given threshold. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait MessageSendBehaviour: Measure { /// This asynchronous method returns a boolean indicating whether the node identified by `did` has a satisfactory message sending behavior. async fn good(&self, did: Did) -> bool { @@ -279,8 +279,8 @@ pub trait MessageSendBehaviour: Measure { /// `MessageRecvBehaviour` trait provides a default implementation for the `good` method, assessing a node's /// behavior based on its message receiving capabilities. /// The "goodness" of a node is measured by comparing the received and failed-to-receive counts against a given threshold. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait MessageRecvBehaviour: Measure { /// This asynchronous method returns a boolean indicating whether the node identified by `did` has a satisfactory message receiving behavior. async fn good(&self, did: Did) -> bool { diff --git a/crates/core/src/message/effects.rs b/crates/core/src/message/effects.rs index 98a5ea952..7c4bef5e6 100644 --- a/crates/core/src/message/effects.rs +++ b/crates/core/src/message/effects.rs @@ -451,6 +451,12 @@ impl<'handler> CoreEffectInterpreter<'handler> { ); match self.transport.connect(peer, callback).await { Ok(()) | Err(Error::AlreadyConnected) => Ok(()), + Err(Error::PendingConnectionCapacityExceeded { capacity }) => { + tracing::debug!( + "pending connection pool is full ({capacity}); skipping DHT candidate {peer}" + ); + Ok(()) + } Err(e) => Err(e), } } diff --git a/crates/core/src/message/handlers/connection.rs b/crates/core/src/message/handlers/connection.rs index e38acf5ce..8fb3b66f5 100644 --- a/crates/core/src/message/handlers/connection.rs +++ b/crates/core/src/message/handlers/connection.rs @@ -2,6 +2,7 @@ use async_trait::async_trait; use crate::dht::types::Chord; use crate::dht::types::CorrectChord; +use crate::dht::Did; use crate::dht::PeerRingAction; use crate::dht::TopoInfo; use crate::error::Error; @@ -21,9 +22,25 @@ use crate::message::HandleMsg; use crate::message::MessageHandler; use crate::message::MessagePayload; +fn confirmed_topology(info: &TopoInfo, is_active: impl Fn(Did) -> bool) -> TopoInfo { + TopoInfo { + successors: info + .successors + .iter() + .copied() + .filter(|peer| is_active(*peer)) + .collect(), + predecessor: info.predecessor.filter(|peer| is_active(*peer)), + } +} + +fn topology_has_confirmed_peer(info: &TopoInfo) -> bool { + info.predecessor.is_some() || !info.successors.is_empty() +} + /// QueryForTopoInfoSend is direct message -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &QueryForTopoInfoSend) -> Result<()> { let info: TopoInfo = TopoInfo::try_from(self.dht.as_ref())?; @@ -40,8 +57,8 @@ impl HandleMsg for MessageHandler { } /// Try join received node into DHT after received from TopoInfo. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, _ctx: &MessagePayload, msg: &QueryForTopoInfoReport) -> Result<()> { match msg.then { @@ -53,24 +70,30 @@ impl HandleMsg for MessageHandler { } } ::Then::Stabilization => { - // Establish stabilization-learned candidates first so the - // resulting Notify/Query actions can usually send immediately. + // Candidates begin as non-routable pending handshakes. Only + // peers whose data channel has opened may enter the DHT view. let candidates = msg .info .predecessor .into_iter() .chain(msg.info.successors.iter().copied()); self.connect_dht_peers(candidates).await?; - let ev = self.dht.stabilize(msg.info.clone())?; - self.handle_dht_events(&ev).await?; + + let confirmed = confirmed_topology(&msg.info, |peer| { + self.transport.get_connection(peer).is_some() + }); + if topology_has_confirmed_peer(&confirmed) { + let ev = self.dht.stabilize(confirmed)?; + self.handle_dht_events(&ev).await?; + } } } Ok(()) } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &ConnectNodeSend) -> Result<()> { if !self.transport.accepts_connection_offer(msg) { @@ -99,8 +122,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &ConnectNodeReport) -> Result<()> { if ctx.should_forward_from(self.dht.did) { @@ -114,8 +137,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &FindSuccessorSend) -> Result<()> { match self.dht.find_successor(msg.did)? { @@ -148,8 +171,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &FindSuccessorReport) -> Result<()> { if ctx.should_forward_from(self.dht.did) { @@ -160,8 +183,9 @@ impl HandleMsg for MessageHandler { match &msg.handler { FindSuccessorReportHandler::FixFingerTable { index } => { - self.dht.apply_fixed_finger(*index, msg.did)?; - if msg.reports_remote_successor(self.dht.did) { + if self.transport.get_connection(msg.did).is_some() { + self.dht.apply_fixed_finger(*index, msg.did)?; + } else if msg.reports_remote_successor(self.dht.did) { self.connect_dht_peer(msg.did).await?; } } @@ -175,7 +199,7 @@ impl HandleMsg for MessageHandler { } } -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] #[cfg(test)] pub mod tests { //! tests @@ -192,6 +216,24 @@ pub mod tests { use crate::tests::default::Node; use crate::tests::manually_establish_connection; + #[test] + fn topology_report_keeps_only_confirmed_peers() { + let active = SecretKey::random().address().into(); + let pending_successor = SecretKey::random().address().into(); + let pending_predecessor = SecretKey::random().address().into(); + let confirmed = confirmed_topology( + &TopoInfo { + successors: vec![active, pending_successor], + predecessor: Some(pending_predecessor), + }, + |peer| peer == active, + ); + + assert_eq!(confirmed.successors, vec![active]); + assert_eq!(confirmed.predecessor, None); + assert!(topology_has_confirmed_peer(&confirmed)); + } + // node1.key < node2.key < node3.key // // Firstly, we connect node1 to node2, node2 to node3. @@ -631,12 +673,16 @@ pub mod tests { node1.assert_transports(vec![]); node2.assert_transports(vec![]); - { + + wait_until("both sides to remove each other from DHT fingers", || { let finger1 = node1.dht().lock_finger()?.clone().clone_finger(); let finger2 = node2.dht().lock_finger()?.clone().clone_finger(); - assert!(finger1.into_iter().all(|x| x.is_none())); - assert!(finger2.into_iter().all(|x| x.is_none())); - } + Ok( + finger1.into_iter().all(|x| x.is_none()) + && finger2.into_iter().all(|x| x.is_none()), + ) + }) + .await?; Ok(()) } diff --git a/crates/core/src/message/handlers/custom.rs b/crates/core/src/message/handlers/custom.rs index f6dae8719..926ba4eda 100644 --- a/crates/core/src/message/handlers/custom.rs +++ b/crates/core/src/message/handlers/custom.rs @@ -20,8 +20,8 @@ pub(crate) fn custom_message_effects<'payload>( } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, _: &CustomMessage) -> Result<()> { self.run_effects(custom_message_effects(self.dht.did, ctx)) diff --git a/crates/core/src/message/handlers/e2e.rs b/crates/core/src/message/handlers/e2e.rs index e87533ac0..e3c191c67 100644 --- a/crates/core/src/message/handlers/e2e.rs +++ b/crates/core/src/message/handlers/e2e.rs @@ -50,8 +50,8 @@ fn e2e_handshake_response_effect<'payload>( .into()) } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &E2eHandshakeRequest) -> Result<()> { run_e2e_local_or_forward(self, ctx, || { @@ -66,8 +66,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &E2eHandshakeResponse) -> Result<()> { run_e2e_local_or_forward(self, ctx, || { @@ -78,8 +78,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &E2eStreamFrame) -> Result<()> { run_e2e_local_or_forward(self, ctx, || { diff --git a/crates/core/src/message/handlers/mod.rs b/crates/core/src/message/handlers/mod.rs index 5a6b37efd..ebefc06b2 100644 --- a/crates/core/src/message/handlers/mod.rs +++ b/crates/core/src/message/handlers/mod.rs @@ -47,8 +47,8 @@ pub struct MessageHandler { } /// Generic trait for handle message ,inspired by Actor-Model. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait HandleMsg { /// Message handler. async fn handle(&self, ctx: &MessagePayload, msg: &T) -> Result<()>; @@ -117,26 +117,23 @@ impl MessageHandler { } pub(crate) async fn leave_dht(&self, peer: Did) -> Result<()> { - if self - .transport - .get_and_check_connection(peer) - .await - .is_none() - { - let should_repair = self + let should_repair = self + .dht + .peer_may_share_storage_responsibility(peer, self.transport.storage_redundancy()) + .await?; + if self.transport.is_admitted_connection(peer) { + self.transport.disconnect(peer).await?; + } else { + self.dht.remove(peer)?; + } + if should_repair { + let repair = self .dht - .peer_may_share_storage_responsibility(peer, self.transport.storage_redundancy()) + .republish_local_entries(self.transport.storage_redundancy()) .await?; - self.dht.remove(peer)?; - if should_repair { - let repair = self - .dht - .republish_local_entries(self.transport.storage_redundancy()) - .await?; - self.run_effects(storage::storage_sync_effects(repair)?) - .await?; - } - }; + self.run_effects(storage::storage_sync_effects(repair)?) + .await?; + } Ok(()) } @@ -194,8 +191,8 @@ impl MessageHandler { Ok(()) } - #[cfg_attr(feature = "wasm", async_recursion(?Send))] - #[cfg_attr(not(feature = "wasm"), async_recursion)] + #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_recursion(?Send))] + #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_recursion)] pub(crate) async fn handle_dht_events(&self, act: &PeerRingAction) -> Result<()> { if matches!(act, PeerRingAction::MultiActions(_)) { let mut effects = Vec::new(); diff --git a/crates/core/src/message/handlers/stabilization.rs b/crates/core/src/message/handlers/stabilization.rs index 0aa9c0b03..e7b52424c 100644 --- a/crates/core/src/message/handlers/stabilization.rs +++ b/crates/core/src/message/handlers/stabilization.rs @@ -14,8 +14,8 @@ use crate::message::HandleMsg; use crate::message::MessageHandler; use crate::message::MessagePayload; -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &NotifyPredecessorSend) -> Result<()> { let predecessor = self.dht.notify(msg.did)?; @@ -34,8 +34,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, _ctx: &MessagePayload, msg: &NotifyPredecessorReport) -> Result<()> { self.run_effects([ConnectionFunctor::connect_dht_peer(msg.did).into()]) @@ -56,7 +56,7 @@ impl HandleMsg for MessageHandler { } } -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] #[cfg(test)] mod test { use std::sync::Arc; diff --git a/crates/core/src/message/handlers/storage.rs b/crates/core/src/message/handlers/storage.rs index 33fcfb8df..df06174ea 100644 --- a/crates/core/src/message/handlers/storage.rs +++ b/crates/core/src/message/handlers/storage.rs @@ -39,8 +39,8 @@ use crate::swarm::transport::SwarmTransport; use crate::swarm::Swarm; /// ChordStorageInterface should imply necessary method for DHT storage -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ChordStorageInterface { /// Fetch an entry from DHT storage. async fn storage_fetch(&self, entry_key: Did) -> Result<()>; @@ -55,8 +55,8 @@ pub trait ChordStorageInterface { } /// ChordStorageInterfaceCacheChecker defines the interface for checking the local cache of the DHT. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait ChordStorageInterfaceCacheChecker { /// Check the local cache of the DHT for a specific entry key. /// @@ -95,8 +95,8 @@ async fn repair_observed_storage_misses( } /// Execute storage fetch actions for the Swarm-facing storage API. -#[cfg_attr(feature = "wasm", async_recursion(?Send))] -#[cfg_attr(not(feature = "wasm"), async_recursion)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_recursion(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_recursion)] async fn handle_storage_fetch_act( transport: Arc, resource: Did, @@ -148,8 +148,8 @@ async fn handle_storage_fetch_act( } /// Execute storage store actions for the Swarm-facing storage API. -#[cfg_attr(feature = "wasm", async_recursion(?Send))] -#[cfg_attr(not(feature = "wasm"), async_recursion)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_recursion(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_recursion)] pub(super) async fn handle_storage_store_act( transport: Arc, act: PeerRingAction, @@ -231,8 +231,8 @@ pub(super) fn storage_sync_effects(act: PeerRingAction) -> Result Option { @@ -411,8 +411,8 @@ impl ChordStorageInterfaceCacheChecker for Swarm { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl ChordStorageInterface for Swarm { /// Fetch an entry. If it exists in local storage, copy it to the cache; /// otherwise query the responsible remote node. @@ -465,8 +465,8 @@ impl ChordStorageInterface for Swarm { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { /// Search Entry via successor /// If a Entry is storead local, it will response immediately.(See Chordstorageinterface::storage_fetch) @@ -481,8 +481,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &FoundEntry) -> Result<()> { if ctx.should_forward_from(self.dht.did) { @@ -515,16 +515,16 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle(&self, ctx: &MessagePayload, msg: &PlacedEntryOperation) -> Result<()> { handle_placed_entry_operation(self, ctx, msg).await } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { // received remote sync entry request async fn handle(&self, ctx: &MessagePayload, msg: &SyncEntriesWithSuccessor) -> Result<()> { @@ -546,8 +546,8 @@ impl HandleMsg for MessageHandler { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl HandleMsg for MessageHandler { async fn handle( &self, @@ -575,6 +575,6 @@ impl HandleMsg for MessageHandler { } } -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] #[cfg(test)] mod tests; diff --git a/crates/core/src/message/handlers/subring.rs b/crates/core/src/message/handlers/subring.rs index e9dd161a1..b64c7d517 100644 --- a/crates/core/src/message/handlers/subring.rs +++ b/crates/core/src/message/handlers/subring.rs @@ -9,15 +9,15 @@ use crate::prelude::entry::EntryOperation; use crate::swarm::Swarm; /// SubringInterface should imply necessary operator for DHT Subring -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait SubringInterface { /// join a subring async fn subring_join(&self, name: &str) -> Result<()>; } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl SubringInterface for Swarm { /// add did into current chord subring. /// send direct message with `JoinSubring` type, which will handled by `next` node. diff --git a/crates/core/src/message/payload.rs b/crates/core/src/message/payload.rs index 7421d250e..179a016df 100644 --- a/crates/core/src/message/payload.rs +++ b/crates/core/src/message/payload.rs @@ -285,8 +285,8 @@ impl Decoder for MessagePayload { } /// Trait of PayloadSender -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait PayloadSender { /// Get the session sk fn session_sk(&self) -> &SessionSk; diff --git a/crates/core/src/storage/memory.rs b/crates/core/src/storage/memory.rs index c10d30321..e8fe78605 100644 --- a/crates/core/src/storage/memory.rs +++ b/crates/core/src/storage/memory.rs @@ -23,8 +23,8 @@ where V: Clone } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl KvStorageInterface for MemStorage where V: Clone + Send + Sync { @@ -59,7 +59,7 @@ where V: Clone + Send + Sync } } -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] #[cfg(test)] mod tests { use super::*; diff --git a/crates/core/src/storage/mod.rs b/crates/core/src/storage/mod.rs index 019221056..fa5cec428 100644 --- a/crates/core/src/storage/mod.rs +++ b/crates/core/src/storage/mod.rs @@ -1,11 +1,14 @@ //! Module of MemStorage and PersistenceStorage -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] /// IndexedDB-backed storage for browser runtimes. pub mod idb; /// In-memory key value storage. pub mod memory; -#[cfg(all(not(feature = "wasm"), not(feature = "dummy")))] +#[cfg(all( + not(all(feature = "wasm", target_family = "wasm")), + not(feature = "dummy") +))] /// Sled-backed persistent storage for native runtimes. pub mod sled; @@ -15,8 +18,8 @@ use crate::error::Result; pub use crate::storage::memory::MemStorage; /// Key value storage interface -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait KvStorageInterface { /// Get a cache entry by `key`. async fn get(&self, key: &str) -> Result>; diff --git a/crates/core/src/swarm/callback.rs b/crates/core/src/swarm/callback.rs index 2ec32dd31..5d850c852 100644 --- a/crates/core/src/swarm/callback.rs +++ b/crates/core/src/swarm/callback.rs @@ -13,16 +13,17 @@ use crate::message::Message; use crate::message::MessageHandler; use crate::message::MessagePayload; use crate::message::MessageVerificationExt; +use crate::swarm::transport::PendingConnectionAttempt; use crate::swarm::transport::SwarmTransport; type CallbackError = Box; /// The [InnerSwarmCallback] will accept shared [SwarmCallback] trait object. -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] pub type SharedSwarmCallback = Arc; /// The [InnerSwarmCallback] will accept shared [SwarmCallback] trait object. -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] pub type SharedSwarmCallback = Arc; /// Used to notify the application of events that occur in the swarm. @@ -39,8 +40,8 @@ pub enum SwarmEvent { } /// Any object that implements this trait can be used as a callback for the swarm. -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] pub trait SwarmCallback { /// This method is invoked when a new message is received and before handling. async fn on_validate(&self, _payload: &MessagePayload) -> Result<(), CallbackError> { @@ -65,6 +66,7 @@ pub struct InnerSwarmCallback { message_handler: MessageHandler, callback: SharedSwarmCallback, reassembler: FuturesMutex, + pending_attempt: Option, } impl InnerSwarmCallback { @@ -77,9 +79,38 @@ impl InnerSwarmCallback { message_handler, callback, reassembler: FuturesMutex::new(reassembler), + pending_attempt: None, } } + /// Bind this callback to the pending handshake that created its transport. + pub(crate) fn with_pending_connection_attempt( + mut self, + pending_attempt: PendingConnectionAttempt, + ) -> Self { + self.pending_attempt = Some(pending_attempt); + self + } + + async fn admit_pending_connection(&self, did: Did) -> Result { + let Some(attempt) = self.pending_attempt else { + return Ok(false); + }; + if !self.transport.promote_pending_connection(attempt)? { + return Ok(false); + } + + self.transport.record_peer_connected(did).await; + self.message_handler.join_dht(did).await?; + self.callback + .on_event(&SwarmEvent::ConnectionStateChange { + peer: did, + state: WebrtcConnectionState::Connected, + }) + .await?; + Ok(true) + } + async fn handle_payload( &self, cid: &str, @@ -150,8 +181,8 @@ impl InnerSwarmCallback { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl TransportCallback for InnerSwarmCallback { async fn on_message(&self, cid: &str, msg: &[u8]) -> Result<(), CallbackError> { let peer = Did::from_str(cid).ok(); @@ -193,9 +224,22 @@ impl TransportCallback for InnerSwarmCallback { }; match s { - // `Failed` and `Closed` are terminal states, so we remove the peer - // from the DHT here. + // ICE `Connected` is not enough for routing: admission happens only + // after the data channel opens, because that is the first point at + // which payload transport is actually usable. + WebrtcConnectionState::Connected => {} + // `Failed` and `Closed` are terminal states. Pending handshakes are + // discarded without touching the DHT; active peers leave it. WebrtcConnectionState::Failed | WebrtcConnectionState::Closed => { + if let Some(attempt) = self.pending_attempt { + if self.transport.cancel_pending_connection(attempt).await? { + self.transport.record_peer_disconnected(did).await; + return Ok(()); + } + } + if !self.transport.is_admitted_connection(did) { + return Ok(()); + } self.transport.record_peer_disconnected(did).await; self.message_handler.leave_dht(did).await?; } @@ -212,9 +256,8 @@ impl TransportCallback for InnerSwarmCallback { _ => {} }; - // Should use the `on_data_channel_open` function to notify the Connected state. - // It prevents users from blocking the channel creation while - // waiting for data channel opening in send_message. + // Data-channel admission emits the application-level Connected event. + // Other state changes are passed through directly. if s != WebrtcConnectionState::Connected { self.callback .on_event(&SwarmEvent::ConnectionStateChange { @@ -233,18 +276,11 @@ impl TransportCallback for InnerSwarmCallback { return Ok(()); }; - self.transport.record_peer_connected(did).await; - self.message_handler.join_dht(did).await?; - - // Notify Connected state here instead of on_peer_connection_state_change. - // It prevents users from blocking the channel creation while - // waiting for data channel opening in send_message. - self.callback - .on_event(&SwarmEvent::ConnectionStateChange { - peer: did, - state: WebrtcConnectionState::Connected, - }) - .await + if !self.admit_pending_connection(did).await? && !self.transport.is_admitted_connection(did) + { + tracing::debug!("ignoring late data-channel open for {did}"); + } + Ok(()) } async fn on_data_channel_close(&self, cid: &str) -> Result<(), CallbackError> { @@ -258,6 +294,15 @@ impl TransportCallback for InnerSwarmCallback { // instead of waiting for the ICE state to reach `Failed`. This is the // graceful counterpart to a local `disconnect()`: the remote learns of // it promptly without relying on the transient `Disconnected` state. + if let Some(attempt) = self.pending_attempt { + if self.transport.cancel_pending_connection(attempt).await? { + self.transport.record_peer_disconnected(did).await; + return Ok(()); + } + } + if !self.transport.is_admitted_connection(did) { + return Ok(()); + } self.transport.record_peer_disconnected(did).await; self.message_handler.leave_dht(did).await?; Ok(()) diff --git a/crates/core/src/swarm/mod.rs b/crates/core/src/swarm/mod.rs index 0d5c8b897..a6b104597 100644 --- a/crates/core/src/swarm/mod.rs +++ b/crates/core/src/swarm/mod.rs @@ -128,9 +128,10 @@ impl Swarm { self.transport.disconnect(peer).await } - /// Connect a given Did. If the did is already connected, return directly, - /// else try prepare offer and establish connection by dht. - /// This function may returns a pending connection or connected connection. + /// Start a non-routable handshake with a peer. + /// + /// The peer becomes visible through the connection inspection APIs only + /// after its data channel opens and the swarm admits it to the DHT. pub async fn connect(&self, peer: Did) -> Result<()> { if peer == self.did() { return Err(Error::ShouldNotConnectSelf); @@ -143,7 +144,15 @@ impl Swarm { self.transport.send_message(msg, destination).await } - /// List peers and their connection status. + /// Send a message directly to an already connected peer, without a Chord lookup. + /// + /// This preserves an application protocol's explicit next-hop selection. Callers must + /// ensure the destination has an active direct transport connection. + pub async fn send_direct_message(&self, msg: Message, destination: Did) -> Result { + self.transport.send_direct_message(msg, destination).await + } + + /// List active, routable peers and their connection status. pub fn peers(&self) -> Vec { self.transport .get_connections() @@ -155,11 +164,16 @@ impl Swarm { .collect() } - /// List peer DIDs known to the transport. + /// List DIDs with active, routable transport connections. pub fn peer_dids(&self) -> Vec { self.transport.get_connection_ids() } + /// List DIDs whose direct WebRTC transport connection is active. + pub fn connected_peer_dids(&self) -> Vec { + self.transport.get_connection_ids() + } + /// Return local measurement counters for `peer`, if observed. pub async fn peer_measurement(&self, peer: Did) -> Option { self.transport.peer_measurement(peer).await diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs index 7b1f36498..a69aeca07 100644 --- a/crates/core/src/swarm/transport.rs +++ b/crates/core/src/swarm/transport.rs @@ -1,24 +1,31 @@ use std::collections::BTreeMap; use std::collections::BTreeSet; -use std::str::FromStr; use std::sync::Arc; use std::sync::Mutex; +use std::time::Duration; +use std::time::Instant; use async_trait::async_trait; use bytes::Bytes; use chrono::Utc; use rings_transport::connection_ref::ConnectionRef; -#[cfg(feature = "dummy")] +#[cfg(all(feature = "dummy", not(target_family = "wasm")))] pub use rings_transport::connections::DummyConnection as ConnectionOwner; -#[cfg(feature = "dummy")] +#[cfg(all(feature = "dummy", not(target_family = "wasm")))] pub use rings_transport::connections::DummyTransport as Transport; -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] pub use rings_transport::connections::WebSysWebrtcConnection as ConnectionOwner; -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] pub use rings_transport::connections::WebSysWebrtcTransport as Transport; -#[cfg(all(not(feature = "wasm"), not(feature = "dummy")))] +#[cfg(all( + not(all(feature = "wasm", target_family = "wasm")), + not(feature = "dummy") +))] use rings_transport::connections::WebrtcConnection as ConnectionOwner; -#[cfg(all(not(feature = "wasm"), not(feature = "dummy")))] +#[cfg(all( + not(all(feature = "wasm", target_family = "wasm")), + not(feature = "dummy") +))] use rings_transport::connections::WebrtcTransport as Transport; use rings_transport::core::transport::ConnectionInterface; use rings_transport::core::transport::TransportInterface; @@ -61,6 +68,106 @@ const STORAGE_LOOKUP_OBSERVATION_TTL_MS: i64 = 30_000; /// Maximum number of read-repair miss observation buckets retained per transport. pub(crate) const STORAGE_LOOKUP_OBSERVATION_CAPACITY: usize = 1024; +/// Maximum number of peers that may be handshaking before a data channel opens. +pub(crate) const DEFAULT_PENDING_CONNECTION_CAPACITY: usize = 32; + +const PENDING_CONNECTION_TIMEOUT: Duration = Duration::from_secs(15); + +/// Identifies one pending handshake for a peer. +/// +/// A peer can have a replacement handshake after a timeout. Callbacks carry +/// this token so a late callback from the replaced connection cannot promote +/// the newer handshake into the active routing set. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(crate) struct PendingConnectionAttempt { + peer: Did, + generation: u64, +} + +#[derive(Debug)] +struct PendingPeer { + generation: u64, + admitted_at: Instant, +} + +/// Bounded, non-routable handshakes owned by the swarm lifecycle. +/// +/// The pool deliberately has no DHT reference: a peer is visible to Chord +/// only after its data channel opens and the matching attempt is promoted. +struct PendingPeerPool { + next_generation: u64, + peers: BTreeMap, +} + +impl PendingPeerPool { + fn new() -> Self { + Self { + next_generation: 0, + peers: BTreeMap::new(), + } + } + + fn reserve(&mut self, peer: Did, now: Instant) -> Result { + if self.peers.contains_key(&peer) { + return Err(Error::AlreadyConnected); + } + if self.peers.len() >= MAX_PENDING { + return Err(Error::PendingConnectionCapacityExceeded { + capacity: MAX_PENDING, + }); + } + + self.next_generation = self.next_generation.wrapping_add(1); + let attempt = PendingConnectionAttempt { + peer, + generation: self.next_generation, + }; + self.peers.insert(peer, PendingPeer { + generation: attempt.generation, + admitted_at: now, + }); + Ok(attempt) + } + + fn contains(&self, peer: Did) -> bool { + self.peers.contains_key(&peer) + } + + fn remove(&mut self, attempt: PendingConnectionAttempt) -> bool { + let Some(peer) = self.peers.get(&attempt.peer) else { + return false; + }; + if peer.generation != attempt.generation { + return false; + } + self.peers.remove(&attempt.peer); + true + } + + fn expire(&mut self, now: Instant) -> Vec { + let expired = + self.peers + .iter() + .filter_map(|(peer, pending)| { + (now.duration_since(pending.admitted_at) >= PENDING_CONNECTION_TIMEOUT) + .then_some(PendingConnectionAttempt { + peer: *peer, + generation: pending.generation, + }) + }) + .collect::>(); + for attempt in &expired { + self.peers.remove(&attempt.peer); + } + expired + } + + #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))] + fn len(&self) -> usize { + self.peers.len() + } +} + // Invariant: after every successful observation-buffer mutation, // observations.len() <= STORAGE_LOOKUP_OBSERVATION_CAPACITY. // Invariant: after evict_storage_lookup_observations(observations, now), every @@ -77,6 +184,8 @@ pub struct SwarmTransport { storage_redundancy: u16, dht_virtual_nodes: u16, reassembly_limits: ReassemblyLimits, + pending_peers: Mutex>, + active_peers: Mutex>, storage_lookup_observations: Mutex, pending_storage_sync_acks: Mutex, measured_disconnects: Mutex>, @@ -199,7 +308,7 @@ async fn record_measurement(measure: Option, did: Did, counter: Mea /// the eventual peer-quality observation. This keeps delivery tracking confined /// to the send site: the status never propagates up through the swarm/node /// layers. -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) { wasm_bindgen_futures::spawn_local(async move { match fut.await { @@ -214,7 +323,7 @@ fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) { /// Drive a message's [DeliveryFuture] to completion on the runtime, recording /// the eventual peer-quality observation. -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) { tokio::spawn(async move { match fut.await { @@ -236,9 +345,9 @@ fn frame_chunk(session_sk: &SessionSk, did: Did, chunk: Chunk) -> Result /// The *tail* of a chunked message — every chunk after the first — yielded lazily. Boxed so the /// background task owns a concrete, nameable type (`Send` off the browser, where spawned tasks must /// be `Send`; single-threaded on it). -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] type ChunkTail = Box + Send>; -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] type ChunkTail = Box>; /// Drive the *tail* of a chunked send: the first chunk has already been accepted by the caller @@ -288,7 +397,7 @@ async fn run_chunked_send( /// Drive the tail of a chunked send on the runtime (one bounded task per large message). See /// [`run_chunked_send`]. -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] fn spawn_chunked_send( conn: SwarmConnection, tail: ChunkTail, @@ -309,7 +418,7 @@ fn spawn_chunked_send( /// Drive the tail of a chunked send on the runtime (one bounded task per large message). See /// [`run_chunked_send`]. -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] fn spawn_chunked_send( conn: SwarmConnection, tail: ChunkTail, @@ -349,6 +458,8 @@ impl SwarmTransport { storage_redundancy: settings.storage_redundancy, dht_virtual_nodes: settings.dht_virtual_nodes, reassembly_limits: settings.reassembly_limits, + pending_peers: Mutex::new(PendingPeerPool::new()), + active_peers: Mutex::new(BTreeSet::new()), storage_lookup_observations: Mutex::new(BTreeMap::new()), pending_storage_sync_acks: Mutex::new(BTreeMap::new()), measured_disconnects: Mutex::new(BTreeSet::new()), @@ -619,7 +730,7 @@ impl SwarmTransport { .collect()) } - #[cfg(all(test, not(feature = "wasm")))] + #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))] /// Test hook: make one observation bucket older than the freshness TTL. pub(crate) fn expire_storage_lookup_observation( &self, @@ -638,7 +749,7 @@ impl SwarmTransport { Ok(()) } - #[cfg(all(test, not(feature = "wasm")))] + #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))] /// Test hook: count retained observation buckets. pub(crate) fn storage_lookup_observation_count(&self) -> Result { let observations = self @@ -648,21 +759,22 @@ impl SwarmTransport { Ok(observations.len()) } - /// Create new connection that will be handled by swarm. - pub async fn new_connection(&self, peer: Did, callback: InnerSwarmCallback) -> Result<()> { - if peer == self.dht.did { - return Ok(()); - } + fn pending_peers( + &self, + ) -> Result>> + { + self.pending_peers + .lock() + .map_err(|_| Error::SwarmConnectionLifecycleLock) + } - let cid = peer.to_string(); - self.transport - .new_connection(&cid, Box::new(callback)) - .await - .map_err(Error::Transport) + fn active_peers(&self) -> Result>> { + self.active_peers + .lock() + .map_err(|_| Error::SwarmConnectionLifecycleLock) } - /// Get connection by did. - pub fn get_connection(&self, peer: Did) -> Option { + fn get_raw_connection(&self, peer: Did) -> Option { self.transport .connection(&peer.to_string()) .map(|conn| SwarmConnection { @@ -672,36 +784,212 @@ impl SwarmTransport { .ok() } - /// Get all connections in transport. - pub fn get_connections(&self) -> Vec<(Did, SwarmConnection)> { + fn is_pending_connection(&self, peer: Did) -> Result { + Ok(self.pending_peers()?.contains(peer)) + } + + /// Return whether `peer` completed a handshake and still owns a logical slot. + /// + /// Unlike [`Self::is_active_connection`], this remains true while a terminal + /// callback removes the peer, so lifecycle cleanup can evict it from the DHT + /// even after WebRTC reports `Closed`. + pub(crate) fn is_admitted_connection(&self, peer: Did) -> bool { + self.active_peers() + .map(|active| active.contains(&peer)) + .unwrap_or(false) + } + + /// Return whether `peer` completed its pending handshake and can route traffic. + /// + /// Data-channel open is the admission boundary. WebRTC may still report a + /// transient `Disconnected` state after admission, so only terminal states + /// make an admitted peer non-routable before its callback removes the slot. + pub(crate) fn is_active_connection(&self, peer: Did) -> bool { + self.is_admitted_connection(peer) + && self.get_raw_connection(peer).is_some_and(|connection| { + !matches!( + connection.webrtc_connection_state(), + WebrtcConnectionState::Failed | WebrtcConnectionState::Closed + ) + }) + } + + async fn reserve_pending_connection(&self, peer: Did) -> Result { + self.expire_pending_connections().await?; + if peer == self.dht.did { + return Err(Error::ShouldNotConnectSelf); + } + // A peer keeps its active slot through transient WebRTC state changes + // until its terminal callback removes it from the DHT. Do not admit a + // second pending handshake for that DID during this interval. + if self.is_admitted_connection(peer) { + return Err(Error::AlreadyConnected); + } + self.pending_peers()?.reserve(peer, Instant::now()) + } + + fn pending_attempt(&self, peer: Did) -> Result> { + let pending = self.pending_peers()?; + Ok(pending + .peers + .get(&peer) + .map(|pending| PendingConnectionAttempt { + peer, + generation: pending.generation, + })) + } + + pub(crate) fn promote_pending_connection( + &self, + attempt: PendingConnectionAttempt, + ) -> Result { + let mut pending = self.pending_peers()?; + if !pending.remove(attempt) { + return Ok(false); + } + drop(pending); + self.active_peers()?.insert(attempt.peer); + Ok(true) + } + + fn retire_pending_connection(&self, attempt: PendingConnectionAttempt) -> Result { + Ok(self.pending_peers()?.remove(attempt)) + } + + fn retire_active_connection(&self, peer: Did) -> Result { + Ok(self.active_peers()?.remove(&peer)) + } + + /// Cancel a current pending handshake and release its non-routable transport object. + pub(crate) async fn cancel_pending_connection( + &self, + attempt: PendingConnectionAttempt, + ) -> Result { + if !self.retire_pending_connection(attempt)? { + return Ok(false); + } self.transport - .connections() + .close_connection(&attempt.peer.to_string()) + .await + .map_err(Error::Transport)?; + Ok(true) + } + + async fn abandon_pending_connection(&self, attempt: PendingConnectionAttempt, operation: &str) { + if let Err(error) = self.cancel_pending_connection(attempt).await { + tracing::warn!( + "failed to cancel pending connection to {} after {operation}: {error}", + attempt.peer + ); + } + } + + /// Close pending handshakes whose data channel did not open before the deadline. + /// + /// These peers have never entered the DHT, so expiry only releases the + /// transport object; it deliberately performs no topology mutation. + pub(crate) async fn expire_pending_connections(&self) -> Result<()> { + let expired = self.pending_peers()?.expire(Instant::now()); + for attempt in expired { + tracing::warn!("pending connection to {} timed out", attempt.peer); + self.transport + .close_connection(&attempt.peer.to_string()) + .await + .map_err(Error::Transport)?; + } + Ok(()) + } + + /// Create a new non-routable transport connection and register its pending attempt. + async fn new_pending_connection( + &self, + attempt: PendingConnectionAttempt, + callback: InnerSwarmCallback, + ) -> Result<()> { + let cid = attempt.peer.to_string(); + if let Err(error) = self + .transport + .new_connection(&cid, Box::new(callback)) + .await + { + let _ = self.retire_pending_connection(attempt); + return Err(Error::Transport(error)); + } + Ok(()) + } + + /// Get an active, routable connection by DID. + /// + /// Pending and terminal physical transports are intentionally invisible here. + pub fn get_connection(&self, peer: Did) -> Option { + self.is_active_connection(peer) + .then(|| self.get_raw_connection(peer)) + .flatten() + } + + /// Get all active, routable transport connections. + pub fn get_connections(&self) -> Vec<(Did, SwarmConnection)> { + self.active_peer_ids() .into_iter() - .filter_map(|(k, v)| { - Did::from_str(&k).ok().map(|did| { - (did, SwarmConnection { - peer: did, - connection: v, - }) - }) + .filter_map(|peer| { + self.get_connection(peer) + .map(|connection| (peer, connection)) + }) + .collect() + } + + fn active_peer_ids(&self) -> Vec { + self.active_peers() + .map(|active| active.iter().copied().collect()) + .unwrap_or_default() + } + + /// Return admitted transports, including a terminal connection that still + /// needs lifecycle cleanup. This is deliberately internal: callers outside + /// the swarm only observe routable connections through [`Self::get_connections`]. + pub(crate) fn admitted_connections(&self) -> Vec<(Did, SwarmConnection)> { + self.active_peer_ids() + .into_iter() + .filter_map(|peer| { + self.get_raw_connection(peer) + .map(|connection| (peer, connection)) }) .collect() } - /// Get dids of all connections in transport. + /// Get DIDs of active, routable connections. pub fn get_connection_ids(&self) -> Vec { - self.transport - .connection_ids() + self.get_connections() .into_iter() - .filter_map(|k| Did::from_str(&k).ok()) + .map(|(peer, _)| peer) .collect() } - /// Disconnect a connection. There are three steps: - /// 1) remove from DHT; - /// 2) remove from Transport; - /// 3) close the connection; + #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))] + pub(crate) fn pending_connection_count(&self) -> Result { + Ok(self.pending_peers()?.len()) + } + + /// Disconnect a connection. + /// + /// Pending connections are never represented in the DHT, so cancelling one + /// only closes its transport object. Active connections leave the DHT before + /// the underlying WebRTC object is released. pub async fn disconnect(&self, peer: Did) -> Result<()> { + if let Some(attempt) = self.pending_attempt(peer)? { + self.cancel_pending_connection(attempt).await?; + return Ok(()); + } + + let was_active = self.retire_active_connection(peer)?; + if !was_active { + self.transport + .close_connection(&peer.to_string()) + .await + .map_err(Error::Transport)?; + return Ok(()); + } + tracing::info!("removing {peer} from DHT"); self.dht.remove(peer)?; self.transport @@ -713,24 +1001,32 @@ impl SwarmTransport { /// Connect a given Did. If the did is already connected, return Err, /// else try prepare offer and establish connection by dht. pub async fn connect(&self, peer: Did, callback: InnerSwarmCallback) -> Result<()> { - let offer_msg = match self.prepare_connection_offer(peer, callback).await { - Ok(offer_msg) => offer_msg, + let (attempt, offer_msg) = match self + .prepare_connection_offer_with_attempt(peer, callback) + .await + { + Ok(offer) => offer, Err(Error::AlreadyConnected) => return Err(Error::AlreadyConnected), Err(e) => { self.record_peer_message_send_failed(peer).await; return Err(e); } }; - self.send_message(Message::ConnectNodeSend(offer_msg), peer) - .await?; + if let Err(error) = self + .send_message(Message::ConnectNodeSend(offer_msg), peer) + .await + { + self.abandon_pending_connection(attempt, "sending connection offer") + .await; + return Err(error); + } Ok(()) } - /// Get connection by did and check if data channel is open. - /// This method will return None if the connection is not found. - /// This method will wait_for_data_channel_open. - /// If it's not ready in 8 seconds this method will close it and return None. - /// If it's ready in 8 seconds this method will return the connection. + /// Get an active connection by DID and verify that its data channel remains open. + /// This method will return None if the connection is not active. + /// It can wait for a transiently disconnected active connection to recover, + /// but pending handshakes never reach this path. /// See more information about [rings_transport::core::transport::WebrtcConnectionState]. /// See also method webrtc_wait_for_data_channel_open [rings_transport::core::transport::ConnectionInterface]. pub async fn get_and_check_connection(&self, peer: Did) -> Option { @@ -757,18 +1053,41 @@ impl SwarmTransport { peer: Did, callback: InnerSwarmCallback, ) -> Result { - if self.get_and_check_connection(peer).await.is_some() { - return Err(Error::AlreadyConnected); - }; + self.prepare_connection_offer_with_attempt(peer, callback) + .await + .map(|(_, offer)| offer) + } - self.new_connection(peer, callback).await?; - let conn = self - .transport - .connection(&peer.to_string()) - .map_err(Error::Transport)?; + async fn prepare_connection_offer_with_attempt( + &self, + peer: Did, + callback: InnerSwarmCallback, + ) -> Result<(PendingConnectionAttempt, ConnectNodeSend)> { + let attempt = self.reserve_pending_connection(peer).await?; + let callback = callback.with_pending_connection_attempt(attempt); + self.new_pending_connection(attempt, callback).await?; + let Some(conn) = self.get_raw_connection(peer) else { + self.abandon_pending_connection(attempt, "looking up the offer transport") + .await; + return Err(Error::SwarmMissTransport(peer)); + }; - let offer = conn.webrtc_create_offer().await.map_err(Error::Transport)?; - let offer_str = serde_json::to_string(&offer).map_err(|_| Error::SerializeToString)?; + let offer = match conn.connection.webrtc_create_offer().await { + Ok(offer) => offer, + Err(error) => { + self.abandon_pending_connection(attempt, "creating connection offer") + .await; + return Err(Error::Transport(error)); + } + }; + let offer_str = match serde_json::to_string(&offer) { + Ok(offer) => offer, + Err(_) => { + self.abandon_pending_connection(attempt, "serializing connection offer") + .await; + return Err(Error::SerializeToString); + } + }; let offer_msg = ConnectNodeSend { sdp: offer_str, network_id: self.network_id, @@ -776,7 +1095,7 @@ impl SwarmTransport { dht_virtual_nodes: self.dht_virtual_nodes, }; - Ok(offer_msg) + Ok((attempt, offer_msg)) } /// Answer the offer of remote connection. @@ -794,7 +1113,12 @@ impl SwarmTransport { let offer = serde_json::from_str(&offer_msg.sdp).map_err(Error::Deserialize)?; - if let Some(swarm_conn) = self.get_connection(peer) { + self.expire_pending_connections().await?; + if self.is_active_connection(peer) { + return Err(Error::AlreadyConnected); + } + + if let Some(swarm_conn) = self.get_raw_connection(peer) { // Solve the scenario of creating offers simultaneously. // // When both sides create_offer at the same time and trigger answer_offer of the other side, @@ -807,27 +1131,49 @@ impl SwarmTransport { // drop local offer and continue answer remote offer if self.dht.did > peer { // this connection will replaced by new connection created bellow - self.disconnect(peer).await?; + let pending = self.pending_attempt(peer)?; + if let Some(attempt) = pending { + self.cancel_pending_connection(attempt).await?; + } else { + self.transport + .close_connection(&peer.to_string()) + .await + .map_err(Error::Transport)?; + } } else { // ignore remote offer, and refuse to answer remote offer return Err(Error::AlreadyConnected); } - } else if self.get_and_check_connection(peer).await.is_some() { + } else { return Err(Error::AlreadyConnected); - }; - }; + } + } - self.new_connection(peer, callback).await?; - let conn = self - .transport - .connection(&peer.to_string()) - .map_err(Error::Transport)?; + let attempt = self.reserve_pending_connection(peer).await?; + let callback = callback.with_pending_connection_attempt(attempt); + self.new_pending_connection(attempt, callback).await?; + let Some(conn) = self.get_raw_connection(peer) else { + self.abandon_pending_connection(attempt, "looking up the answer transport") + .await; + return Err(Error::SwarmMissTransport(peer)); + }; - let answer = conn - .webrtc_answer_offer(offer) - .await - .map_err(Error::Transport)?; - let answer_str = serde_json::to_string(&answer).map_err(|_| Error::SerializeToString)?; + let answer = match conn.connection.webrtc_answer_offer(offer).await { + Ok(answer) => answer, + Err(error) => { + self.abandon_pending_connection(attempt, "creating connection answer") + .await; + return Err(Error::Transport(error)); + } + }; + let answer_str = match serde_json::to_string(&answer) { + Ok(answer) => answer, + Err(_) => { + self.abandon_pending_connection(attempt, "serializing connection answer") + .await; + return Err(Error::SerializeToString); + } + }; let answer_msg = ConnectNodeReport { sdp: answer_str, network_id: self.network_id, @@ -852,13 +1198,21 @@ impl SwarmTransport { let answer = serde_json::from_str(&answer_msg.sdp).map_err(Error::Deserialize)?; + if !self.is_pending_connection(peer)? { + return Err(Error::SwarmMissTransport(peer)); + } + let conn = self - .transport - .connection(&peer.to_string()) - .map_err(Error::Transport)?; - conn.webrtc_accept_answer(answer) - .await - .map_err(Error::Transport)?; + .get_raw_connection(peer) + .ok_or(Error::SwarmMissTransport(peer))?; + if let Err(error) = conn.connection.webrtc_accept_answer(answer).await { + let attempt = self.pending_attempt(peer)?; + if let Some(attempt) = attempt { + self.abandon_pending_connection(attempt, "accepting connection answer") + .await; + } + return Err(Error::Transport(error)); + } Ok(()) } @@ -883,8 +1237,8 @@ impl SwarmConnection { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl PayloadSender for SwarmTransport { fn session_sk(&self) -> &SessionSk { &self.session_sk @@ -979,8 +1333,8 @@ impl PayloadSender for SwarmTransport { } } -#[cfg_attr(feature = "wasm", async_trait(?Send))] -#[cfg_attr(not(feature = "wasm"), async_trait)] +#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)] impl LiveDid for SwarmConnection { async fn live(&self) -> bool { self.webrtc_connection_state() == WebrtcConnectionState::Connected @@ -993,5 +1347,5 @@ impl From for Did { } } -#[cfg(all(test, not(feature = "wasm")))] +#[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))] mod tests; diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs index c186c8754..9fe1d86fc 100644 --- a/crates/core/src/swarm/transport/tests.rs +++ b/crates/core/src/swarm/transport/tests.rs @@ -5,6 +5,7 @@ use std::sync::Mutex; use async_trait::async_trait; use super::*; +use crate::dht::successor::SuccessorReader; use crate::dht::VirtualNodeConfig; use crate::dht::DEFAULT_FINGER_TABLE_SIZE; use crate::dht::DEFAULT_STORAGE_VIRTUAL_POSITIONS_PER_OWNER; @@ -13,6 +14,8 @@ use crate::ecc::SecretKey; use crate::measure::BehaviourJudgement; use crate::measure::Measure; use crate::storage::MemStorage; +use crate::swarm::callback::InnerSwarmCallback; +use crate::swarm::callback::SwarmCallback; use crate::swarm::SwarmBuilder; #[derive(Default)] @@ -70,6 +73,11 @@ impl BehaviourJudgement for RecordingMeasure { } } +struct NoopSwarmCallback; + +#[async_trait] +impl SwarmCallback for NoopSwarmCallback {} + fn transport_with_measure(measure: MeasureImpl) -> Result { let key = SecretKey::random(); let session_sk = SessionSk::new_with_seckey(&key)?; @@ -132,6 +140,93 @@ fn swarm_builder_normalizes_virtual_nodes_before_protocol_advertisement() -> Res Ok(()) } +#[test] +fn pending_peer_pool_is_bounded_and_rejects_duplicate_peers() -> Result<()> { + let mut pool = PendingPeerPool::<2>::new(); + let now = Instant::now(); + let peer_a = SecretKey::random().address().into(); + let peer_b = SecretKey::random().address().into(); + let peer_c = SecretKey::random().address().into(); + + let attempt_a = pool.reserve(peer_a, now)?; + assert!(matches!( + pool.reserve(peer_a, now), + Err(Error::AlreadyConnected) + )); + let _attempt_b = pool.reserve(peer_b, now)?; + assert!(matches!( + pool.reserve(peer_c, now), + Err(Error::PendingConnectionCapacityExceeded { capacity: 2 }) + )); + assert_eq!(pool.len(), 2); + + assert!(pool.remove(attempt_a)); + assert_eq!(pool.len(), 1); + assert!(pool.reserve(peer_c, now).is_ok()); + Ok(()) +} + +#[test] +fn stale_pending_callback_cannot_remove_a_replacement_attempt() -> Result<()> { + let mut pool = PendingPeerPool::<1>::new(); + let now = Instant::now(); + let peer = SecretKey::random().address().into(); + + let old_attempt = pool.reserve(peer, now)?; + assert!(pool.remove(old_attempt)); + let current_attempt = pool.reserve(peer, now)?; + + assert!(!pool.remove(old_attempt)); + assert!(pool.contains(peer)); + assert!(pool.remove(current_attempt)); + Ok(()) +} + +#[test] +fn pending_peer_pool_expires_unopened_handshakes() -> Result<()> { + let mut pool = PendingPeerPool::<1>::new(); + let now = Instant::now(); + let peer = SecretKey::random().address().into(); + let attempt = pool.reserve(peer, now)?; + + let expired = pool.expire(now + PENDING_CONNECTION_TIMEOUT); + assert_eq!(expired, vec![attempt]); + assert_eq!(pool.len(), 0); + Ok(()) +} + +#[tokio::test] +async fn admitted_peer_cannot_be_replaced_by_a_pending_handshake() -> Result<()> { + let transport = transport_with_measure(Arc::new(RecordingMeasure::default()))?; + let peer = SecretKey::random().address().into(); + let attempt = transport.reserve_pending_connection(peer).await?; + + assert!(transport.promote_pending_connection(attempt)?); + assert!(matches!( + transport.reserve_pending_connection(peer).await, + Err(Error::AlreadyConnected) + )); + Ok(()) +} + +#[tokio::test] +async fn pending_offer_is_not_routable_or_visible_to_dht() -> Result<()> { + let transport = Arc::new(transport_with_measure(Arc::new( + RecordingMeasure::default(), + ))?); + let peer = SecretKey::random().address().into(); + let callback = InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback)); + + let _offer = transport.prepare_connection_offer(peer, callback).await?; + + assert!(transport.get_connection(peer).is_none()); + assert_eq!(transport.pending_connection_count()?, 1); + assert!(!transport.dht.successors().contains(&peer)?); + + transport.disconnect(peer).await?; + Ok(()) +} + #[test] fn connection_offer_protocol_mode_includes_storage_redundancy() -> Result<()> { let transport = transport_with_measure(Arc::new(RecordingMeasure::default()))?; diff --git a/crates/core/src/tests/default/mod.rs b/crates/core/src/tests/default/mod.rs index 636a279af..a76d15b04 100644 --- a/crates/core/src/tests/default/mod.rs +++ b/crates/core/src/tests/default/mod.rs @@ -71,15 +71,14 @@ impl Node { self.message_rx.lock().await.try_recv().ok() } - /// Whether any connection is still mid-handshake (`New`/`Connecting`) — i.e. its offer/answer - /// SDP exchange has not finished. Used to detect true quiescence without a wall clock. + /// Whether any connection is still mid-handshake. Used to detect true + /// quiescence without a wall clock. pub fn has_handshaking_connection(&self) -> bool { - self.swarm.transport.get_connections().iter().any(|(_, c)| { - matches!( - c.webrtc_connection_state(), - WebrtcConnectionState::New | WebrtcConnectionState::Connecting - ) - }) + self.swarm + .transport + .pending_connection_count() + .unwrap_or_default() + > 0 } pub fn did(&self) -> Did { @@ -325,8 +324,8 @@ pub async fn wait_for_msgs(nodes: impl IntoIterator) { drained }; let handshaking = || nodes.iter().any(|n| n.has_handshaking_connection()); - // A snapshot of every node's DHT. Reaching `Connected` fires `on_data_channel_open -> join_dht`, - // which mutates the DHT and emits more messages *after* the handshake finished — so true + // A snapshot of every node's DHT. Opening the data channel fires `join_dht`, which mutates the + // DHT and emits more messages *after* the ICE connection state reached `Connected` — so true // quiescence also requires the DHT to have stopped changing, not just the handshakes to be done. let snapshot = || { nodes diff --git a/crates/core/src/tests/default/test_chunk_e2e.rs b/crates/core/src/tests/default/test_chunk_e2e.rs index cb1ca9099..96acccf2e 100644 --- a/crates/core/src/tests/default/test_chunk_e2e.rs +++ b/crates/core/src/tests/default/test_chunk_e2e.rs @@ -4,10 +4,12 @@ //! just the pure `WireReserves::plan` decision. use rings_transport::connections::dummy_controlled; +use rings_transport::core::transport::WebrtcConnectionState; use crate::ecc::SecretKey; use crate::message::Message; use crate::tests::default::prepare_node; +use crate::tests::default::wait_for_connection_state; use crate::tests::manually_establish_connection; /// Read inbound messages on `node` until a `CustomMessage` arrives (skipping DHT bookkeeping), or @@ -29,6 +31,12 @@ async fn large_message_is_chunked_and_reassembled() { let node1 = prepare_node(key1).await; let node2 = prepare_node(key2).await; manually_establish_connection(&node1.swarm, &node2.swarm).await; + wait_for_connection_state(&node1, node2.did(), WebrtcConnectionState::Connected) + .await + .unwrap(); + wait_for_connection_state(&node2, node1.did(), WebrtcConnectionState::Connected) + .await + .unwrap(); // Force a small negotiated limit so the payload below must be chunked. Set it *after* the // handshake so the connect offer/answer themselves are unaffected. @@ -60,6 +68,12 @@ async fn negotiated_size_too_small_errors_without_partial_send() { let node1 = prepare_node(key1).await; let node2 = prepare_node(key2).await; manually_establish_connection(&node1.swarm, &node2.swarm).await; + wait_for_connection_state(&node1, node2.did(), WebrtcConnectionState::Connected) + .await + .unwrap(); + wait_for_connection_state(&node2, node1.did(), WebrtcConnectionState::Connected) + .await + .unwrap(); // Below `chunk_overhead + MIN_CHUNK_DATA`: no usable chunk size exists, so framing must reject // *before* any chunk is sent (the `None` is returned ahead of the send loop). diff --git a/crates/core/src/tests/default/test_connection.rs b/crates/core/src/tests/default/test_connection.rs index 80726feba..d204a0a4d 100644 --- a/crates/core/src/tests/default/test_connection.rs +++ b/crates/core/src/tests/default/test_connection.rs @@ -79,37 +79,12 @@ async fn test_handshake_on_both_sides(key1: SecretKey, key2: SecretKey, key3: Se _ = node1.swarm.connect(node2.did()).await; _ = node2.swarm.connect(node1.did()).await; - // Both sides have just initiated an outbound connection (offer created) but no answer has - // been exchanged yet, so neither has reached `Connected`. The exact pre-connected sub-state — - // `New` vs `Connecting` — depends on whether the peer's offer has already arrived and started - // ICE, which is webrtc-version/timing dependent; the invariant we assert is only that the glare - // handshake is still in progress. - let node1_to_node2 = node1 - .swarm - .transport - .get_connection(node2.did()) - .unwrap() - .webrtc_connection_state(); - assert!( - matches!( - node1_to_node2, - WebrtcConnectionState::New | WebrtcConnectionState::Connecting - ), - "swarm1 -> swarm2 should still be handshaking, got {node1_to_node2:?}", - ); - let node2_to_node1 = node2 - .swarm - .transport - .get_connection(node1.did()) - .unwrap() - .webrtc_connection_state(); - assert!( - matches!( - node2_to_node1, - WebrtcConnectionState::New | WebrtcConnectionState::Connecting - ), - "swarm2 -> swarm1 should still be handshaking, got {node2_to_node1:?}", - ); + // Both offers exist but neither handshake has been admitted. Pending peers + // must remain invisible to the public connection view. + assert!(node1.swarm.transport.get_connection(node2.did()).is_none()); + assert!(node2.swarm.transport.get_connection(node1.did()).is_none()); + assert_eq!(node1.swarm.transport.pending_connection_count().unwrap(), 1); + assert_eq!(node2.swarm.transport.pending_connection_count().unwrap(), 1); wait_for_msgs([&node1, &node2, &node3]).await; assert_no_more_msg([&node1, &node2, &node3]).await; diff --git a/crates/core/src/tests/default/test_message_handler.rs b/crates/core/src/tests/default/test_message_handler.rs index 7e8c2fc2f..827888231 100644 --- a/crates/core/src/tests/default/test_message_handler.rs +++ b/crates/core/src/tests/default/test_message_handler.rs @@ -37,6 +37,8 @@ use crate::tests::default::wait_for_msgs; use crate::tests::default::wait_for_predecessor; use crate::tests::default::wait_for_storage_entry; use crate::tests::default::wait_for_successor; +#[cfg(feature = "dummy")] +use crate::tests::default::Node; use crate::tests::manually_establish_connection; #[cfg(feature = "dummy")] @@ -45,6 +47,30 @@ struct NoopCallback; #[cfg(feature = "dummy")] impl SwarmCallback for NoopCallback {} +#[cfg(feature = "dummy")] +async fn drain_controlled_dummy_events() { + while dummy_controlled::pending() > 0 { + assert!(dummy_controlled::deliver(0).await); + tokio::task::yield_now().await; + } +} + +#[cfg(feature = "dummy")] +async fn drain_node_messages(nodes: &[&Node]) { + loop { + let mut drained = false; + for node in nodes { + while node.try_listen_once().await.is_some() { + drained = true; + } + } + if !drained { + return; + } + tokio::task::yield_now().await; + } +} + #[tokio::test] async fn test_handle_join() -> Result<()> { let key1 = SecretKey::random(); @@ -65,7 +91,7 @@ async fn test_handle_join() -> Result<()> { #[tokio::test] async fn test_join_dht_keeps_local_join_when_convergence_send_fails() -> Result<()> { dummy_controlled::enable(true); - dummy_controlled::set_max_message_size(0); + dummy_controlled::set_max_message_size(1); let key1 = SecretKey::random(); let key2 = SecretKey::random(); @@ -78,19 +104,15 @@ async fn test_join_dht_keeps_local_join_when_convergence_send_fails() -> Result< "controlled delivery should prevent automatic DataChannelOpen join" ); - dummy_controlled::enable(false); - dummy_controlled::set_max_message_size(1); - - let handler = MessageHandler::new(node1.swarm.transport.clone(), Arc::new(NoopCallback)); - let join_result = handler.join_dht(node2.did()).await; + drain_controlled_dummy_events().await; + dummy_controlled::enable(false); dummy_controlled::set_max_message_size(0); assert!( - join_result.is_ok(), - "join must not fail when follow-up convergence sends fail: {join_result:?}" + node1.dht().successors().list()?.contains(&node2.did()), + "local join must survive failed follow-up convergence sends" ); - assert!(node1.dht().successors().list()?.contains(&node2.did())); Ok(()) } @@ -106,8 +128,11 @@ async fn test_handle_dht_notify_remote_action_sends_predecessor_to_target() -> R let node3 = prepare_node(keys[2]).await; manually_establish_connection(&node1.swarm, &node2.swarm).await; - // Clear queued connection-open callbacks so this test exercises only the - // explicit handler action below, not automatic join/stabilization traffic. + drain_controlled_dummy_events().await; + drain_node_messages(&[&node1, &node2, &node3]).await; + + // Clear any empty controlled queue so this test exercises only the + // explicit handler action below. dummy_controlled::enable(false); let handler = MessageHandler::new(node1.swarm.transport.clone(), Arc::new(NoopCallback)); diff --git a/crates/core/src/tests/mod.rs b/crates/core/src/tests/mod.rs index ad004f3ca..4e338d974 100644 --- a/crates/core/src/tests/mod.rs +++ b/crates/core/src/tests/mod.rs @@ -1,9 +1,9 @@ use crate::swarm::Swarm; -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] pub mod wasm; -#[cfg(not(feature = "wasm"))] +#[cfg(not(all(feature = "wasm", target_family = "wasm")))] pub mod default; #[allow(dead_code)] @@ -22,7 +22,4 @@ pub async fn manually_establish_connection(swarm1: &Swarm, swarm2: &Swarm) { let offer = swarm1.create_offer(swarm2.did()).await.unwrap(); let answer = swarm2.answer_offer(offer).await.unwrap(); swarm1.accept_answer(answer).await.unwrap(); - - assert!(swarm1.transport.get_connection(swarm2.did()).is_some()); - assert!(swarm2.transport.get_connection(swarm1.did()).is_some()); } diff --git a/crates/core/src/utils.rs b/crates/core/src/utils.rs index 033d72d9d..8537e0f19 100644 --- a/crates/core/src/utils.rs +++ b/crates/core/src/utils.rs @@ -5,7 +5,7 @@ pub fn get_epoch_ms() -> u128 { Utc::now().timestamp_millis() as u128 } -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] /// Toolset for wasm pub mod js_value { use serde::de::DeserializeOwned; @@ -38,7 +38,7 @@ pub mod js_value { } } -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] /// Helpers for adapting JavaScript functions into async Rust callbacks. pub mod js_func { /// This macro will generate a wrapper for mapping a js_sys::Function with type fn(T, T, T, T) -> Promise<()> @@ -145,7 +145,7 @@ pub mod js_func { of!(of4, a: T0, b: T1, c: T2, d: T3); } -#[cfg(feature = "wasm")] +#[cfg(all(feature = "wasm", target_family = "wasm"))] /// Browser and worker utility functions for wasm runtimes. pub mod js_utils { use std::future::Future; diff --git a/crates/derive/src/lib.rs b/crates/derive/src/lib.rs index 938c1b770..23f93a737 100644 --- a/crates/derive/src/lib.rs +++ b/crates/derive/src/lib.rs @@ -23,10 +23,14 @@ pub fn wasm_export(attr: TokenStream, input: TokenStream) -> TokenStream { .into(); } #[cfg(feature = "wasm")] - return match wasm_bindgen_macro_support::expand(attr.into(), input.into()) { - Ok(tokens) => tokens.into(), - Err(diagnostic) => (quote! { #diagnostic }).into(), - }; + { + let input: proc_macro2::TokenStream = input.into(); + quote! { + #[cfg_attr(target_family = "wasm", wasm_bindgen::prelude::wasm_bindgen)] + #input + } + .into() + } #[cfg(not(feature = "wasm"))] return input; diff --git a/crates/node/src/processor/builder.rs b/crates/node/src/processor/builder.rs index 864457ebd..5d2981a86 100644 --- a/crates/node/src/processor/builder.rs +++ b/crates/node/src/processor/builder.rs @@ -142,7 +142,9 @@ impl ProcessorBuilder { /// Add a custom periodic registration task. pub fn registration_task(mut self, task: T) -> Self - where T: RegistrationTask + 'static { + where + T: RegistrationTask + 'static, + { self.registration_tasks.push(Arc::new(task)); self } diff --git a/crates/node/src/processor/config.rs b/crates/node/src/processor/config.rs index 48292952c..e41b4e164 100644 --- a/crates/node/src/processor/config.rs +++ b/crates/node/src/processor/config.rs @@ -495,7 +495,9 @@ impl Serialize for ProcessorConfig { impl<'de> serde::de::Deserialize<'de> for ProcessorConfig { fn deserialize(deserializer: D) -> core::result::Result - where D: serde::Deserializer<'de> { + where + D: serde::Deserializer<'de>, + { match ProcessorConfigSerialized::deserialize(deserializer) { Ok(ins) => { let cfg: ProcessorConfig = ins diff --git a/crates/node/src/processor/mod.rs b/crates/node/src/processor/mod.rs index d2b7eab80..fd91763fe 100644 --- a/crates/node/src/processor/mod.rs +++ b/crates/node/src/processor/mod.rs @@ -394,6 +394,21 @@ impl Processor { .map_err(Error::SendMessage) } + /// Send a custom message to an already connected peer without Chord routing. + /// + /// Protocols with their own authenticated hop selection, such as onion circuits, use this + /// to keep the core transport from replacing their selected next hop. + pub async fn send_direct_message(&self, destination: Did, msg: &[u8]) -> Result { + tracing::info!("send_direct_message, message size: {:?}", msg.len()); + + let msg = Message::custom(msg).map_err(Error::SendMessage)?; + + self.swarm + .send_direct_message(msg, destination) + .await + .map_err(Error::SendMessage) + } + /// Send an E2E handshake request to a DID. /// /// The negotiated key is the peer's account/identity secp256k1 key, not @@ -528,6 +543,18 @@ impl Processor { self.send_message(destination, &msg_bytes).await } + /// Send a namespaced envelope directly to an already connected peer. + /// + /// This bypasses Chord routing while retaining the normal custom-message envelope codec. + pub async fn send_direct_envelope( + &self, + destination: Did, + envelope: &crate::extension::ext::Envelope, + ) -> Result { + let msg_bytes = envelope.encode()?; + self.send_direct_message(destination, &msg_bytes).await + } + /// check local cache of dht pub async fn storage_check_cache(&self, entry_key: Did) -> Option { self.swarm.storage_check_cache(entry_key).await diff --git a/crates/node/src/processor/tests/test_config.rs b/crates/node/src/processor/tests/test_config.rs index 5e483eeb5..92b6613ab 100644 --- a/crates/node/src/processor/tests/test_config.rs +++ b/crates/node/src/processor/tests/test_config.rs @@ -300,10 +300,10 @@ fn default_onion_exit_config_uses_native_tcp_backed_services() { assert!(config.advertise_onion_exit); assert_eq!(config.onion_exit_services, default_onion_exit_services()); - assert_eq!(config.onion_exit_services, vec![ - OnionExitService::tcp(), - OnionExitService::https() - ]); + assert_eq!( + config.onion_exit_services, + vec![OnionExitService::tcp(), OnionExitService::https()] + ); } #[test] diff --git a/crates/node/src/processor/tests/test_network.rs b/crates/node/src/processor/tests/test_network.rs index a1acb69b3..b9cffcd04 100644 --- a/crates/node/src/processor/tests/test_network.rs +++ b/crates/node/src/processor/tests/test_network.rs @@ -118,6 +118,30 @@ async fn test_processor_handshake_msg() { assert!(matches!(got_msg1, Message::CustomMessage(_))); } +#[tokio::test] +async fn test_processor_direct_message_reaches_connected_peer() { + let _network_guard = network_test_guard().await; + let callback1 = test_callback(); + let callback2 = test_callback(); + let p1 = prepare_processor().await; + let p2 = prepare_processor().await; + + p1.swarm.set_callback(callback1.clone()).unwrap(); + p2.swarm.set_callback(callback2.clone()).unwrap(); + connect_processors(&p1, &p2, &callback1, &callback2).await; + + p1.send_direct_message(p2.did(), b"direct-message") + .await + .unwrap(); + + let received = wait_for_inbound_message( + &callback2, + |message| matches!(message, Message::CustomMessage(custom) if custom.0 == b"direct-message"), + ) + .await; + assert!(matches!(received, Message::CustomMessage(_))); +} + #[tokio::test] async fn peer_measurement_is_absent_without_measure_or_observation() { let unmeasured = prepare_processor_with_identity_key(SecretKey::random()).await; @@ -170,9 +194,12 @@ async fn provider_exposes_sent_and_received_peer_measurements() { assert!(provider_measurement.evidence.sent >= 1); let rpc_value = provider - .request(Method::PeerMeasurement, PeerMeasurementRequest { - did: p2.did().to_string(), - }) + .request( + Method::PeerMeasurement, + PeerMeasurementRequest { + did: p2.did().to_string(), + }, + ) .await .unwrap(); let rpc_measurement: PeerMeasurementResponse = serde_json::from_value(rpc_value).unwrap(); diff --git a/crates/node/src/provider/browser/provider.rs b/crates/node/src/provider/browser/provider.rs index 8496c223c..52a61efa8 100644 --- a/crates/node/src/provider/browser/provider.rs +++ b/crates/node/src/provider/browser/provider.rs @@ -126,7 +126,7 @@ impl BrowserOnionDirectoryReader { let local = self.processor.did(); self.processor .swarm - .peer_dids() + .connected_peer_dids() .into_iter() .filter(|did| *did != local) .collect() @@ -336,7 +336,7 @@ impl BrowserOnionProxy { }; let envelope = crate::extension::ext::Envelope::new(ONION_CIRCUIT_NAMESPACE.to_string(), payload); - if let Err(error) = p.send_envelope(to, &envelope).await { + if let Err(error) = p.send_direct_envelope(to, &envelope).await { runtime.cancel_request(id); return Err(JsValue::from(JsError::from(error))); } diff --git a/crates/transport/src/connection_ref.rs b/crates/transport/src/connection_ref.rs index e613090de..93b41c063 100644 --- a/crates/transport/src/connection_ref.rs +++ b/crates/transport/src/connection_ref.rs @@ -49,7 +49,7 @@ impl ConnectionRef { } } -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] #[async_trait(?Send)] impl ConnectionInterface for ConnectionRef where @@ -110,7 +110,7 @@ where } } -#[cfg(not(feature = "web-sys-webrtc"))] +#[cfg(not(all(feature = "web-sys-webrtc", target_family = "wasm")))] #[async_trait] impl ConnectionInterface for ConnectionRef where @@ -181,8 +181,11 @@ mod tests { #[derive(Debug)] struct Mock; - #[cfg_attr(feature = "web-sys-webrtc", async_trait(?Send))] - #[cfg_attr(not(feature = "web-sys-webrtc"), async_trait)] + #[cfg_attr(all(feature = "web-sys-webrtc", target_family = "wasm"), async_trait(?Send))] + #[cfg_attr( + not(all(feature = "web-sys-webrtc", target_family = "wasm")), + async_trait + )] impl ConnectionInterface for Mock { type Sdp = String; type Error = Error; diff --git a/crates/transport/src/connections/mod.rs b/crates/transport/src/connections/mod.rs index 8541b266b..6a1ad3741 100644 --- a/crates/transport/src/connections/mod.rs +++ b/crates/transport/src/connections/mod.rs @@ -2,24 +2,24 @@ //! Plus a `WebSysWebrtcConnection` for wasm environment. //! Also provide a `DummyConnection` for testing. -#[cfg(feature = "dummy")] +#[cfg(all(feature = "dummy", not(target_family = "wasm")))] mod dummy; -#[cfg(feature = "native-webrtc")] +#[cfg(all(feature = "native-webrtc", not(target_family = "wasm")))] mod native_webrtc; -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] mod web_sys_webrtc; -#[cfg(feature = "dummy")] +#[cfg(all(feature = "dummy", not(target_family = "wasm")))] pub use crate::connections::dummy::controlled as dummy_controlled; -#[cfg(feature = "dummy")] +#[cfg(all(feature = "dummy", not(target_family = "wasm")))] pub use crate::connections::dummy::DummyConnection; -#[cfg(feature = "dummy")] +#[cfg(all(feature = "dummy", not(target_family = "wasm")))] pub use crate::connections::dummy::DummyTransport; -#[cfg(feature = "native-webrtc")] +#[cfg(all(feature = "native-webrtc", not(target_family = "wasm")))] pub use crate::connections::native_webrtc::WebrtcConnection; -#[cfg(feature = "native-webrtc")] +#[cfg(all(feature = "native-webrtc", not(target_family = "wasm")))] pub use crate::connections::native_webrtc::WebrtcTransport; -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub use crate::connections::web_sys_webrtc::WebSysWebrtcConnection; -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub use crate::connections::web_sys_webrtc::WebSysWebrtcTransport; diff --git a/crates/transport/src/core/callback.rs b/crates/transport/src/core/callback.rs index 039e62e27..0b94b48fe 100644 --- a/crates/transport/src/core/callback.rs +++ b/crates/transport/src/core/callback.rs @@ -12,8 +12,11 @@ use crate::core::transport::WebrtcConnectionState; type CallbackError = Box; /// Any object that implements this trait can be used as a callback for the connection. -#[cfg_attr(feature = "web-sys-webrtc", async_trait(?Send))] -#[cfg_attr(not(feature = "web-sys-webrtc"), async_trait)] +#[cfg_attr(all(feature = "web-sys-webrtc", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr( + not(all(feature = "web-sys-webrtc", target_family = "wasm")), + async_trait +)] pub trait TransportCallback { /// Notify the data channel is open. async fn on_data_channel_open(&self, _cid: &str) -> Result<(), CallbackError> { @@ -46,11 +49,11 @@ pub trait TransportCallback { /// The `new_connection` method of /// [TransportInterface](super::transport::TransportInterface) trait will /// accept boxed [TransportCallback] trait object. -#[cfg(not(feature = "web-sys-webrtc"))] +#[cfg(not(all(feature = "web-sys-webrtc", target_family = "wasm")))] pub type BoxedTransportCallback = Box; /// The `new_connection` method of /// [TransportInterface](super::transport::TransportInterface) trait will /// accept boxed [TransportCallback] trait object. -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub type BoxedTransportCallback = Box; diff --git a/crates/transport/src/core/pool.rs b/crates/transport/src/core/pool.rs index a32366d2e..6608e0adc 100644 --- a/crates/transport/src/core/pool.rs +++ b/crates/transport/src/core/pool.rs @@ -109,9 +109,12 @@ impl RoundRobin for RoundRobinPool { /// Extends `RoundRobin` with functionality for asynchronous message transmission, leveraging the pooled /// resources for communication. It's adaptable to various messaging patterns and data types, specified /// by the generic `Message` associated type. -#[cfg_attr(any(feature = "web-sys-webrtc", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr(any(all(feature = "web-sys-webrtc", target_family = "wasm"), target_family = "wasm"), async_trait(?Send))] #[cfg_attr( - not(any(feature = "web-sys-webrtc", target_family = "wasm")), + not(any( + all(feature = "web-sys-webrtc", target_family = "wasm"), + target_family = "wasm" + )), async_trait )] pub trait MessageSenderPool: RoundRobin { diff --git a/crates/transport/src/core/transport.rs b/crates/transport/src/core/transport.rs index 0e766b43d..86c597420 100644 --- a/crates/transport/src/core/transport.rs +++ b/crates/transport/src/core/transport.rs @@ -83,8 +83,11 @@ pub fn effective_max_message_size(remote_sdp: &str) -> usize { /// The [ConnectionInterface] trait defines how to /// make webrtc ice handshake with a remote peer and then send data channel message to it. -#[cfg_attr(feature = "web-sys-webrtc", async_trait(?Send))] -#[cfg_attr(not(feature = "web-sys-webrtc"), async_trait)] +#[cfg_attr(all(feature = "web-sys-webrtc", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr( + not(all(feature = "web-sys-webrtc", target_family = "wasm")), + async_trait +)] pub trait ConnectionInterface { /// Sdp is used to expose local and remote session descriptions when handshaking. type Sdp: Serialize + DeserializeOwned; @@ -133,8 +136,11 @@ pub trait ConnectionInterface { /// This trait specifies how to management [ConnectionInterface] objects. /// Each platform must implement this trait for its own connection implementation. /// See [connections](crate::connections) module for examples. -#[cfg_attr(feature = "web-sys-webrtc", async_trait(?Send))] -#[cfg_attr(not(feature = "web-sys-webrtc"), async_trait)] +#[cfg_attr(all(feature = "web-sys-webrtc", target_family = "wasm"), async_trait(?Send))] +#[cfg_attr( + not(all(feature = "web-sys-webrtc", target_family = "wasm")), + async_trait +)] pub trait TransportInterface { /// The connection type that is created by this trait. type Connection: ConnectionInterface; @@ -170,12 +176,12 @@ pub trait TransportInterface { } /// Used to store a boxed [TransportInterface] trait object. -#[cfg(not(feature = "web-sys-webrtc"))] +#[cfg(not(all(feature = "web-sys-webrtc", target_family = "wasm")))] pub type BoxedTransport = Box + Send + Sync>; /// Used to store a boxed [TransportInterface] trait object. -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub type BoxedTransport = Box>; #[cfg(test)] diff --git a/crates/transport/src/delivery.rs b/crates/transport/src/delivery.rs index 9e885d99b..182fde8cb 100644 --- a/crates/transport/src/delivery.rs +++ b/crates/transport/src/delivery.rs @@ -25,9 +25,9 @@ use crate::error::Result; /// /// It is `Send` on native targets (so it can be spawned on a multi-threaded /// runtime) and `!Send` on wasm, matching the rest of the transport. -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub type DeliveryFuture = Pin>>>; /// A future resolving to the eventual fate of a sent message. -#[cfg(not(feature = "web-sys-webrtc"))] +#[cfg(not(all(feature = "web-sys-webrtc", target_family = "wasm")))] pub type DeliveryFuture = Pin> + Send>>; diff --git a/crates/transport/src/error.rs b/crates/transport/src/error.rs index 6aef5c768..1fa91d745 100644 --- a/crates/transport/src/error.rs +++ b/crates/transport/src/error.rs @@ -31,7 +31,7 @@ pub enum Error { #[error("WebRTC error: {0}")] Webrtc(#[from] webrtc::error::Error), - #[cfg(feature = "web-sys-webrtc")] + #[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] /// WebSysWebRTC error: {} #[error("WebSysWebRTC error: {}", dump_js_value(.0))] WebSysWebrtc(wasm_bindgen::JsValue), @@ -85,7 +85,7 @@ pub enum Error { RoundRobinPoolEmpty, } -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] fn dump_js_value(v: &wasm_bindgen::JsValue) -> String { let Ok(s) = js_sys::JSON::stringify(v) else { return "Failed to stringify Error(JsValue)".to_string(); diff --git a/crates/transport/src/lib.rs b/crates/transport/src/lib.rs index de26fe30d..db3a54e90 100644 --- a/crates/transport/src/lib.rs +++ b/crates/transport/src/lib.rs @@ -10,14 +10,6 @@ )] #![doc = include_str!("../README.md")] -#[cfg(all( - feature = "web-sys-webrtc", - any(feature = "dummy", feature = "native-webrtc") -))] -compile_error!( - "rings-transport feature `web-sys-webrtc` cannot be combined with native transport features" -); - pub mod callback; pub mod connection_ref; pub mod connections; diff --git a/crates/transport/src/notifier.rs b/crates/transport/src/notifier.rs index 28458ecad..a1112c607 100644 --- a/crates/transport/src/notifier.rs +++ b/crates/transport/src/notifier.rs @@ -40,13 +40,16 @@ impl Notifier { } /// Wake the notifier after the specified time. - #[cfg(not(any(feature = "web-sys-webrtc", feature = "native-webrtc")))] + #[cfg(not(any( + all(feature = "web-sys-webrtc", target_family = "wasm"), + all(feature = "native-webrtc", not(target_family = "wasm")) + )))] pub fn set_timeout(&self, seconds: u8) { self.set_timeout_ms(u64::from(seconds) * 1000); } /// Wake the notifier after the specified time. - #[cfg(feature = "native-webrtc")] + #[cfg(all(feature = "native-webrtc", not(target_family = "wasm")))] pub fn set_timeout(&self, seconds: u8) { let this = self.clone(); tokio::spawn(async move { @@ -56,7 +59,7 @@ impl Notifier { } /// Wake the notifier after the specified number of milliseconds. - #[cfg(feature = "native-webrtc")] + #[cfg(all(feature = "native-webrtc", not(target_family = "wasm")))] pub fn set_timeout_ms(&self, millis: u64) { let this = self.clone(); tokio::spawn(async move { @@ -66,19 +69,22 @@ impl Notifier { } /// Wake the notifier after the specified number of milliseconds. - #[cfg(not(any(feature = "web-sys-webrtc", feature = "native-webrtc")))] + #[cfg(not(any( + all(feature = "web-sys-webrtc", target_family = "wasm"), + all(feature = "native-webrtc", not(target_family = "wasm")) + )))] pub fn set_timeout_ms(&self, millis: u64) { native_timeout_scheduler::schedule_wake(self.clone(), millis); } /// Wake the notifier after the specified time. - #[cfg(feature = "web-sys-webrtc")] + #[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub fn set_timeout(&self, seconds: u8) { self.set_timeout_ms(u64::from(seconds) * 1000); } /// Wake the notifier after the specified number of milliseconds. - #[cfg(feature = "web-sys-webrtc")] + #[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] pub fn set_timeout_ms(&self, millis: u64) { use wasm_bindgen::JsCast; @@ -117,7 +123,10 @@ impl Future for Notifier { } } -#[cfg(not(any(feature = "web-sys-webrtc", feature = "native-webrtc")))] +#[cfg(not(any( + all(feature = "web-sys-webrtc", target_family = "wasm"), + all(feature = "native-webrtc", not(target_family = "wasm")) +)))] mod native_timeout_scheduler { use std::cmp::Ordering; use std::collections::BinaryHeap; @@ -301,7 +310,7 @@ mod native_timeout_scheduler { } // This is copied from utils module of rings-core crate. -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] mod js_utils { use wasm_bindgen::JsCast; use wasm_bindgen::JsValue; diff --git a/crates/transport/src/pool.rs b/crates/transport/src/pool.rs index 5a46e78e7..bea4b04d9 100644 --- a/crates/transport/src/pool.rs +++ b/crates/transport/src/pool.rs @@ -54,7 +54,7 @@ impl Pool { } } -#[cfg(not(feature = "web-sys-webrtc"))] +#[cfg(not(all(feature = "web-sys-webrtc", target_family = "wasm")))] impl Pool where C: ConnectionInterface + Send + Sync, @@ -103,7 +103,7 @@ where } } -#[cfg(feature = "web-sys-webrtc")] +#[cfg(all(feature = "web-sys-webrtc", target_family = "wasm"))] impl Pool where C: ConnectionInterface, diff --git a/crates/webview/Cargo.toml b/crates/webview/Cargo.toml new file mode 100644 index 000000000..fbd47fb1c --- /dev/null +++ b/crates/webview/Cargo.toml @@ -0,0 +1,35 @@ +[package] +name = "rings-webview" +description = "Reusable Rings webview gateway primitives for onion-backed browsing." +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +repository.workspace = true + +[features] +default = [] +browser = [ + "dep:js-sys", + "dep:serde-wasm-bindgen", + "dep:wasm-bindgen", + "dep:wasm-bindgen-futures", +] + +[dependencies] +async-trait = { workspace = true } +js-sys = { workspace = true, optional = true } +lol_html = "3" +percent-encoding = "2" +serde = { version = "1.0.136", features = ["derive"] } +serde-wasm-bindgen = { workspace = true, optional = true } +thiserror = "1" +url = { version = "2", features = ["serde"] } +wasm-bindgen = { workspace = true, optional = true } +wasm-bindgen-futures = { workspace = true, optional = true } + +[dev-dependencies] +futures = { version = "0.3.21", features = ["executor"] } + +[lints] +workspace = true diff --git a/crates/webview/src/browser.rs b/crates/webview/src/browser.rs new file mode 100644 index 000000000..1c8d5a130 --- /dev/null +++ b/crates/webview/src/browser.rs @@ -0,0 +1,1006 @@ +//! Browser-facing webview helpers. + +use url::Url; + +use crate::error::Result; +use crate::url::GatewayPrefix; + +/// JavaScript bootstrap template marker used by tests and consumers. +pub const BOOTSTRAP_MARKER: &str = "__ringsWebviewGateway"; + +/// Build a small runtime that routes browser-created URLs through the gateway prefix. +pub fn bootstrap_script(gateway_prefix: &str, document_url: &Url) -> String { + format!( + r#"(function() {{ + const prefix = {prefix:?}; + const targetBase = {target_base:?}; + const marker = "{marker}"; + const urlAttributes = new Set(["href", "src", "action", "poster", "data", "cite", "formaction", "manifest", "xlink:href"]); + const srcsetAttributes = new Set(["srcset", "imagesrcset"]); + const styleProxies = new WeakMap(); + if (globalThis[marker]) {{ + globalThis[marker].targetBase = targetBase; + return; + }} + const gatewayState = {{ targetBase }}; + globalThis[marker] = gatewayState; + function gatewayPathFromText(input) {{ + const text = String(input); + if (text.startsWith(prefix)) return text; + try {{ + const url = new URL(text); + if (globalThis.location?.origin && url.origin === globalThis.location.origin && url.pathname.startsWith(prefix)) {{ + return `${{url.pathname}}${{url.search}}${{url.hash}}`; + }} + }} catch (_error) {{}} + return undefined; + }} + function decodeGatewayTarget(input) {{ + const path = gatewayPathFromText(input); + if (!path?.startsWith(prefix)) return undefined; + const encoded = path.slice(prefix.length); + if (!encoded) return undefined; + try {{ + return decodeURIComponent(encoded); + }} catch (_error) {{ + return undefined; + }} + }} + function resolveTargetBase() {{ + const rawBase = globalThis.document?.querySelector?.("base[href]")?.getAttribute?.("href"); + if (!rawBase) return gatewayState.targetBase; + const decoded = decodeGatewayTarget(rawBase); + if (decoded) return decoded; + try {{ + return new URL(String(rawBase), gatewayState.targetBase).href; + }} catch (_error) {{ + return gatewayState.targetBase; + }} + }} + function isUnrewritableTarget(value) {{ + const lower = String(value).trim().toLowerCase(); + return !lower || ["javascript:", "mailto:", "tel:", "data:", "blob:", "about:"].some((scheme) => lower.startsWith(scheme)); + }} + function encodeTarget(input, base = resolveTargetBase()) {{ + const text = String(input); + if (isUnrewritableTarget(text)) return text; + const gatewayPath = gatewayPathFromText(text); + if (gatewayPath) return gatewayPath; + const url = new URL(text, base); + return prefix + encodeURIComponent(url.href); + }} + function requestShellNavigation(input) {{ + void input; + return false; + }} + function reportFormNavigation(message) {{ + try {{ + globalThis.__ringsWebviewDebugOverlay?.record?.("bootstrap", message); + }} catch (_error) {{}} + }} + function encodeUrlList(input, base) {{ + return String(input).trim().split(/\s+/).filter(Boolean).map((value) => encodeTarget(value, base)).join(" "); + }} + function encodeSrcset(input, base) {{ + return String(input).split(",").map((candidate) => {{ + const trimmed = candidate.trim(); + if (!trimmed) return ""; + const parts = trimmed.split(/\s+/, 2); + const rewritten = encodeTarget(parts[0], base); + return parts.length > 1 ? `${{rewritten}} ${{parts[1]}}` : rewritten; + }}).filter(Boolean).join(", "); + }} + function encodeCssText(input) {{ + const imports = String(input).replace(/(@import\s+)(['"])([^'"]+)\2/gi, function(match, importPrefix, quote, value) {{ + try {{ + return `${{importPrefix}}${{quote}}${{encodeTarget(value)}}${{quote}}`; + }} catch (_error) {{ + return match; + }} + }}); + return imports.replace(/url\(\s*(['"]?)(.*?)\1\s*\)/gi, function(match, quote, value) {{ + try {{ + const rewritten = encodeTarget(value); + const delimiter = quote || ""; + return `url(${{delimiter}}${{rewritten}}${{delimiter}})`; + }} catch (_error) {{ + return match; + }} + }}); + }} + function encodeRefreshText(input) {{ + return String(input).replace(/(\burl\s*=\s*)(['"]?)([^'"]+)\2/i, function(match, prefixText, quote, value) {{ + try {{ + const delimiter = quote || ""; + return `${{prefixText}}${{delimiter}}${{encodeTarget(value.trim())}}${{delimiter}}`; + }} catch (_error) {{ + return match; + }} + }}); + }} + function setRawAttribute(element, name, value) {{ + if (nativeSetAttribute) return nativeSetAttribute.call(element, name, value); + return element.setAttribute(name, value); + }} + function rewriteHtmlElement(element, base) {{ + const tagName = String(element.tagName || "").toLowerCase(); + for (const attribute of Array.from(element.attributes || [])) {{ + setRawAttribute(element, attribute.name, encodeElementAttribute(element, attribute.name, attribute.value, base)); + }} + if (tagName === "style") {{ + element.textContent = encodeCssText(element.textContent || ""); + }} + rewriteMetaRefreshElement(element); + }} + function rewriteHtmlTree(root, initialBase, maySetBase) {{ + let base = initialBase; + const elements = []; + if (root?.nodeType === 1) elements.push(root); + elements.push(...Array.from(root.querySelectorAll?.("*") || [])); + for (const element of elements) {{ + const tagName = String(element.tagName || "").toLowerCase(); + const baseHref = tagName === "base" ? element.getAttribute?.("href") : null; + rewriteHtmlElement(element, base); + if (maySetBase && baseHref != null) {{ + try {{ + base = new URL(baseHref, base).href; + maySetBase = false; + }} catch (_error) {{}} + }} + }} + }} + function injectSrcdocRuntime(root) {{ + const doc = globalThis.document; + if (!doc?.createElement) return; + const head = root.querySelector?.("head"); + let container = head || root; + let anchor = container.firstChild || null; + const existingBase = root.querySelector?.("base[href]"); + if (existingBase?.parentNode) {{ + container = existingBase.parentNode; + anchor = existingBase.nextSibling || null; + }} else {{ + const base = doc.createElement("base"); + setRawAttribute(base, "href", encodeTarget(resolveTargetBase())); + container.insertBefore?.(base, anchor); + anchor = base.nextSibling || null; + }} + const source = doc.querySelector?.("script[data-rings-webview-bootstrap]")?.textContent; + if (source) {{ + const script = doc.createElement("script"); + setRawAttribute(script, "data-rings-webview-bootstrap", ""); + script.textContent = source; + container.insertBefore?.(script, anchor); + }} + }} + function encodeSrcdoc(input) {{ + const doc = globalThis.document; + if (!doc?.createElement) return String(input); + const template = doc.createElement("template"); + setNativeInnerHtml(template, String(input)); + const root = template.content || template; + rewriteHtmlTree(root, resolveTargetBase(), true); + injectSrcdocRuntime(root); + return template.innerHTML; + }} + function encodeHtmlFragment(input) {{ + const doc = globalThis.document; + if (!doc?.createElement) return String(input); + const template = doc.createElement("template"); + setNativeInnerHtml(template, String(input)); + const root = template.content || template; + rewriteHtmlTree(root, resolveTargetBase(), !doc.querySelector?.("base[href]")); + return template.innerHTML; + }} + function encodeAttribute(name, value, base) {{ + const lower = String(name).toLowerCase(); + if (lower === "srcdoc") return encodeSrcdoc(value); + if (lower === "style") return encodeCssText(value); + if (lower === "ping") return encodeUrlList(value, base); + if (urlAttributes.has(lower)) return encodeTarget(value, base); + if (srcsetAttributes.has(lower)) return encodeSrcset(value, base); + return value; + }} + function isMetaRefreshElement(element) {{ + return String(element?.tagName || "").toLowerCase() === "meta" + && String(element.getAttribute?.("http-equiv") || "").trim().toLowerCase() === "refresh"; + }} + function encodeElementAttribute(element, name, value, base) {{ + if (String(name).toLowerCase() === "content" && isMetaRefreshElement(element)) {{ + return encodeRefreshText(value); + }} + return encodeAttribute(name, value, base); + }} + function rewriteMetaRefreshElement(element) {{ + if (!isMetaRefreshElement(element)) return; + const content = element.getAttribute?.("content"); + if (content != null) setRawAttribute(element, "content", encodeRefreshText(content)); + }} + function blockUnsupportedConstructor(name) {{ + const NativeConstructor = globalThis[name]; + if (!NativeConstructor) return; + const BlockedConstructor = function() {{ + throw new TypeError(`${{name}} is blocked by Rings WebView until gateway transport supports it`); + }}; + BlockedConstructor.prototype = NativeConstructor.prototype; + Object.setPrototypeOf?.(BlockedConstructor, NativeConstructor); + globalThis[name] = BlockedConstructor; + }} + function findPropertyDescriptor(proto, property) {{ + let current = proto; + while (current) {{ + const descriptor = Object.getOwnPropertyDescriptor(current, property); + if (descriptor) return descriptor; + current = Object.getPrototypeOf(current); + }} + return undefined; + }} + function patchUrlProperty(constructorName, property, attributeName) {{ + const proto = globalThis[constructorName]?.prototype; + if (!proto) return; + const descriptor = findPropertyDescriptor(proto, property); + if (!descriptor?.set) return; + Object.defineProperty(proto, property, {{ + ...descriptor, + set(value) {{ + return descriptor.set.call(this, encodeAttribute(attributeName || property, value)); + }} + }}); + }} + function patchUrlListProperty(constructorName, property) {{ + const proto = globalThis[constructorName]?.prototype; + if (!proto) return; + const descriptor = findPropertyDescriptor(proto, property); + if (!descriptor?.set) return; + Object.defineProperty(proto, property, {{ + ...descriptor, + set(value) {{ + return descriptor.set.call(this, encodeUrlList(value, resolveTargetBase())); + }} + }}); + }} + function patchHtmlProperty(property) {{ + const proto = globalThis.Element?.prototype; + if (!proto) return; + const descriptor = findPropertyDescriptor(proto, property); + if (!descriptor?.set) return; + Object.defineProperty(proto, property, {{ + ...descriptor, + set(value) {{ + const tagName = String(this.tagName || "").toLowerCase(); + const rewritten = property === "innerHTML" && tagName === "style" ? encodeCssText(value) : encodeHtmlFragment(value); + return descriptor.set.call(this, rewritten); + }} + }}); + }} + function isStyleNode(node) {{ + return String(node?.tagName || node?.parentElement?.tagName || "").toLowerCase() === "style"; + }} + function patchStyleTextContent() {{ + const proto = globalThis.Node?.prototype; + if (!proto) return; + const descriptor = findPropertyDescriptor(proto, "textContent"); + if (!descriptor?.set) return; + Object.defineProperty(proto, "textContent", {{ + ...descriptor, + set(value) {{ + return descriptor.set.call(this, isStyleNode(this) ? encodeCssText(value) : value); + }} + }}); + }} + function proxyStyle(style) {{ + if (!style || typeof Proxy === "undefined") return style; + const existing = styleProxies.get(style); + if (existing) return existing; + const proxy = new Proxy(style, {{ + get(target, property) {{ + const value = Reflect.get(target, property, target); + return typeof value === "function" ? value.bind(target) : value; + }}, + set(target, property, value) {{ + return Reflect.set(target, property, typeof value === "string" ? encodeCssText(value) : value, target); + }} + }}); + styleProxies.set(style, proxy); + return proxy; + }} + function patchStyleGetter(constructorName) {{ + const proto = globalThis[constructorName]?.prototype; + if (!proto) return; + const descriptor = findPropertyDescriptor(proto, "style"); + if (!descriptor?.get) return; + Object.defineProperty(proto, "style", {{ + ...descriptor, + get() {{ + return proxyStyle(descriptor.get.call(this)); + }} + }}); + }} + function patchCssTextMethod(constructorName, method) {{ + const proto = globalThis[constructorName]?.prototype; + const native = proto?.[method]; + if (typeof native !== "function") return; + proto[method] = function(css, ...rest) {{ + return native.call(this, encodeCssText(css), ...rest); + }}; + }} + function patchCssStyleDeclaration() {{ + const proto = globalThis.CSSStyleDeclaration?.prototype; + if (!proto) return; + const nativeSetProperty = proto.setProperty; + if (typeof nativeSetProperty === "function") {{ + proto.setProperty = function(name, value, priority) {{ + return nativeSetProperty.call(this, name, encodeCssText(value), priority); + }}; + }} + const descriptor = findPropertyDescriptor(proto, "cssText"); + if (descriptor?.set) {{ + Object.defineProperty(proto, "cssText", {{ + ...descriptor, + set(value) {{ + return descriptor.set.call(this, encodeCssText(value)); + }} + }}); + }} + }} + function patchMetaRefreshProperty(property) {{ + const proto = globalThis.HTMLMetaElement?.prototype; + if (!proto) return; + const descriptor = findPropertyDescriptor(proto, property); + if (!descriptor?.set) return; + Object.defineProperty(proto, property, {{ + ...descriptor, + set(value) {{ + if (property === "httpEquiv" && String(value).trim().toLowerCase() === "refresh") {{ + const content = this.getAttribute?.("content"); + if (content != null) setRawAttribute(this, "content", encodeRefreshText(content)); + }} + const rewritten = property === "content" && isMetaRefreshElement(this) ? encodeRefreshText(value) : value; + return descriptor.set.call(this, rewritten); + }} + }}); + }} + function patchWindowOpen() {{ + const nativeOpen = globalThis.open?.bind(globalThis); + if (!nativeOpen) return; + globalThis.open = function(url, target, features) {{ + const rewritten = url == null || url === "" ? url : encodeTarget(url); + return nativeOpen(rewritten, target, features); + }}; + }} + function patchLocationNavigation() {{ + const proto = globalThis.Location?.prototype; + if (!proto) return; + for (const method of ["assign", "replace"]) {{ + const native = proto[method]; + if (typeof native !== "function") continue; + proto[method] = function(url) {{ + if (requestShellNavigation(url)) return; + return native.call(this, encodeTarget(url)); + }}; + }} + const descriptor = findPropertyDescriptor(proto, "href"); + if (!descriptor?.set) return; + Object.defineProperty(proto, "href", {{ + ...descriptor, + set(value) {{ + if (requestShellNavigation(value)) return; + return descriptor.set.call(this, encodeTarget(value)); + }} + }}); + }} + function formTargetUrl(form, submitter) {{ + const action = submitter?.getAttribute?.("formaction") + || form.getAttribute?.("action") + || form.action; + const decoded = decodeGatewayTarget(action); + const target = decoded || new URL(String(action || ""), resolveTargetBase()).href; + const url = new URL(target); + if (url.protocol !== "http:" && url.protocol !== "https:") return undefined; + return url; + }} + function navigateGetForm(form, submitter) {{ + if (String(form?.method || "get").toUpperCase() !== "GET") {{ + reportFormNavigation("Skipped non-GET form submission"); + return false; + }} + const targetName = String(form?.target || "").trim().toLowerCase(); + if (targetName && targetName !== "_self") {{ + reportFormNavigation(`Skipped form submission targeting ${{targetName}}`); + return false; + }} + if (typeof globalThis.FormData !== "function") {{ + reportFormNavigation("FormData is unavailable for GET form submission"); + return false; + }} + try {{ + const target = formTargetUrl(form, submitter); + if (!target) {{ + reportFormNavigation("GET form target is not HTTP(S)"); + return false; + }} + const fields = new URLSearchParams(); + const data = submitter ? new FormData(form, submitter) : new FormData(form); + for (const [name, value] of data.entries()) {{ + fields.append(String(name), typeof value === "string" ? value : String(value?.name || "")); + }} + target.search = fields.toString(); + if (requestShellNavigation(target.href)) return true; + const location = globalThis.location; + if (typeof location?.assign !== "function") return false; + location.assign(encodeTarget(target.href)); + return true; + }} catch (error) {{ + reportFormNavigation(`GET form interception failed: ${{String(error)}}`); + return false; + }} + }} + function patchGetFormSubmission() {{ + const document = globalThis.document; + if (document?.addEventListener) {{ + const intercept = function(event, form, submitter) {{ + if (!navigateGetForm(form, submitter)) return false; + event.preventDefault(); + event.stopImmediatePropagation?.(); + return true; + }}; + document.addEventListener("keydown", function(event) {{ + if (event.defaultPrevented || event.isComposing || event.key !== "Enter") return; + const form = event.target?.closest?.("form"); + reportFormNavigation("Captured Enter for GET form submission"); + intercept(event, form, undefined); + }}, true); + document.addEventListener("click", function(event) {{ + if (event.defaultPrevented || (event.button != null && event.button !== 0)) return; + const submitter = event.target?.closest?.("button, input"); + if (!submitter) return; + const tagName = String(submitter.tagName || "").toLowerCase(); + const type = String(submitter.type || "").toLowerCase(); + const isSubmit = (tagName === "button" && (!type || type === "submit")) + || (tagName === "input" && (type === "submit" || type === "image")); + if (!isSubmit) return; + reportFormNavigation("Captured submit control click"); + intercept(event, submitter.form || submitter.closest?.("form"), submitter); + }}, true); + document.addEventListener("submit", function(event) {{ + const form = event.target; + if (!(form instanceof globalThis.HTMLFormElement)) return; + intercept(event, form, event.submitter); + }}, true); + }} + const proto = globalThis.HTMLFormElement?.prototype; + const nativeSubmit = proto?.submit; + if (typeof nativeSubmit === "function") {{ + proto.submit = function() {{ + if (navigateGetForm(this, undefined)) return; + return nativeSubmit.call(this); + }}; + }} + }} + const nativeInnerHtmlSetter = findPropertyDescriptor(globalThis.Element?.prototype, "innerHTML")?.set; + function setNativeInnerHtml(element, value) {{ + if (nativeInnerHtmlSetter) return nativeInnerHtmlSetter.call(element, value); + return element.innerHTML = value; + }} + const nativeFetch = globalThis.fetch?.bind(globalThis); + if (nativeFetch) {{ + globalThis.fetch = function(input, init) {{ + const next = input instanceof Request ? new Request(encodeTarget(input.url), input) : encodeTarget(input); + try {{ + const headers = new Headers(init?.headers || (input instanceof Request ? next.headers : undefined)); + headers.set("X-Rings-Webview-Kind", "fetch"); + return nativeFetch(next, {{ ...init, headers }}); + }} catch (_error) {{ + return nativeFetch(next, init); + }} + }}; + }} + const NativeXHR = globalThis.XMLHttpRequest; + if (NativeXHR) {{ + globalThis.XMLHttpRequest = function() {{ + const xhr = new NativeXHR(); + const open = xhr.open; + xhr.open = function(method, url, async, user, password) {{ + const result = open.call(xhr, method, encodeTarget(url), async, user, password); + try {{ + xhr.setRequestHeader("X-Rings-Webview-Kind", "xhr"); + }} catch (_error) {{}} + return result; + }}; + return xhr; + }}; + }} + blockUnsupportedConstructor("WebSocket"); + blockUnsupportedConstructor("EventSource"); + blockUnsupportedConstructor("Worker"); + blockUnsupportedConstructor("SharedWorker"); + if (globalThis.navigator?.sendBeacon) {{ + globalThis.navigator.sendBeacon = function() {{ + return false; + }}; + }} + const nativeSetAttribute = globalThis.Element?.prototype?.setAttribute; + if (nativeSetAttribute) {{ + globalThis.Element.prototype.setAttribute = function(name, value) {{ + const lower = String(name).toLowerCase(); + if (lower === "http-equiv" && String(value).trim().toLowerCase() === "refresh") {{ + const content = this.getAttribute?.("content"); + if (content != null) setRawAttribute(this, "content", encodeRefreshText(content)); + }} + return nativeSetAttribute.call(this, name, encodeElementAttribute(this, name, value)); + }}; + }} + const nativeSetAttributeNs = globalThis.Element?.prototype?.setAttributeNS; + if (nativeSetAttributeNs) {{ + globalThis.Element.prototype.setAttributeNS = function(namespace, name, value) {{ + return nativeSetAttributeNs.call(this, namespace, name, encodeElementAttribute(this, name, value)); + }}; + }} + patchHtmlProperty("innerHTML"); + patchHtmlProperty("outerHTML"); + const nativeInsertAdjacentHtml = globalThis.Element?.prototype?.insertAdjacentHTML; + if (nativeInsertAdjacentHtml) {{ + globalThis.Element.prototype.insertAdjacentHTML = function(position, html) {{ + return nativeInsertAdjacentHtml.call(this, position, encodeHtmlFragment(html)); + }}; + }} + patchStyleTextContent(); + const nativeDocumentWrite = globalThis.Document?.prototype?.write; + if (nativeDocumentWrite) {{ + globalThis.Document.prototype.write = function(...parts) {{ + return nativeDocumentWrite.call(this, encodeHtmlFragment(parts.join(""))); + }}; + }} + patchCssStyleDeclaration(); + patchMetaRefreshProperty("content"); + patchMetaRefreshProperty("httpEquiv"); + patchWindowOpen(); + patchLocationNavigation(); + patchGetFormSubmission(); + for (const constructorName of ["HTMLElement", "SVGElement", "CSSStyleRule", "CSSFontFaceRule", "CSSPageRule", "CSSKeyframeRule"]) {{ + patchStyleGetter(constructorName); + }} + for (const [constructorName, method] of [ + ["CSSStyleSheet", "insertRule"], + ["CSSStyleSheet", "replace"], + ["CSSStyleSheet", "replaceSync"], + ["CSSGroupingRule", "insertRule"], + ["CSSKeyframesRule", "appendRule"] + ]) {{ + patchCssTextMethod(constructorName, method); + }} + patchUrlProperty("HTMLAnchorElement", "href"); + patchUrlListProperty("HTMLAnchorElement", "ping"); + patchUrlProperty("HTMLAreaElement", "href"); + patchUrlListProperty("HTMLAreaElement", "ping"); + patchUrlProperty("HTMLBaseElement", "href"); + patchUrlProperty("HTMLImageElement", "src"); + patchUrlProperty("HTMLImageElement", "srcset"); + patchUrlProperty("HTMLScriptElement", "src"); + patchUrlProperty("HTMLIFrameElement", "src"); + patchUrlProperty("HTMLIFrameElement", "srcdoc"); + patchUrlProperty("HTMLLinkElement", "href"); + patchUrlProperty("HTMLFormElement", "action"); + patchUrlProperty("HTMLInputElement", "src"); + patchUrlProperty("HTMLInputElement", "formAction", "formaction"); + patchUrlProperty("HTMLButtonElement", "formAction", "formaction"); + patchUrlProperty("HTMLSourceElement", "src"); + patchUrlProperty("HTMLSourceElement", "srcset"); + patchUrlProperty("HTMLVideoElement", "poster"); + patchUrlProperty("HTMLVideoElement", "src"); + patchUrlProperty("HTMLAudioElement", "src"); + patchUrlProperty("HTMLEmbedElement", "src"); + patchUrlProperty("HTMLObjectElement", "data"); + gatewayState.prefix = prefix; +}})();"#, + prefix = gateway_prefix, + target_base = document_url.as_str(), + marker = BOOTSTRAP_MARKER, + ) +} + +/// Resolve a runtime URL the same way the bootstrap does and encode it for the gateway. +pub fn runtime_gateway_url( + gateway_prefix: &GatewayPrefix, + document_url: &Url, + input: &str, +) -> Result> { + gateway_prefix.rewrite_url_value(document_url, input) +} + +#[cfg(target_arch = "wasm32")] +mod wasm { + use async_trait::async_trait; + use js_sys::Function; + use js_sys::Promise; + use js_sys::Reflect; + use wasm_bindgen::JsCast; + use wasm_bindgen::JsValue; + use wasm_bindgen_futures::JsFuture; + + use crate::error::Result; + use crate::error::WebviewError; + use crate::transport::GatewayTransport; + use crate::types::GatewayRequest; + use crate::types::GatewayResponse; + + /// Browser adapter for JS objects that expose `request(url, request)`. + pub struct OnionProxyJsTransport { + proxy: JsValue, + } + + impl OnionProxyJsTransport { + /// Build a transport around an existing browser onion proxy object. + pub fn new(proxy: JsValue) -> Self { + Self { proxy } + } + } + + #[async_trait(?Send)] + impl GatewayTransport for OnionProxyJsTransport { + async fn send(&self, request: GatewayRequest) -> Result { + let method = Reflect::get(&self.proxy, &JsValue::from_str("request")) + .map_err(|error| WebviewError::Browser(format!("{error:?}")))? + .dyn_into::() + .map_err(|_| WebviewError::Browser("proxy.request is not callable".to_string()))?; + let request_value = serde_wasm_bindgen::to_value(&request) + .map_err(|error| WebviewError::Browser(error.to_string()))?; + let value = method + .call2( + &self.proxy, + &JsValue::from_str(request.target.as_str()), + &request_value, + ) + .map_err(|error| WebviewError::Browser(format!("{error:?}")))?; + let response = JsFuture::from(Promise::from(value)) + .await + .map_err(|error| WebviewError::Browser(format!("{error:?}")))?; + serde_wasm_bindgen::from_value(response) + .map_err(|error| WebviewError::Browser(error.to_string())) + } + } + + pub use OnionProxyJsTransport as JsOnionProxyTransport; +} + +#[cfg(target_arch = "wasm32")] +pub use wasm::JsOnionProxyTransport; + +#[cfg(test)] +mod tests { + use super::*; + use crate::error::WebviewError; + + #[test] + fn bootstrap_hooks_browser_network_entrypoints() -> Result<()> { + let document_url = Url::parse("https://example.test/docs/index.html")?; + let script = bootstrap_script("/webview/", &document_url); + + assert!(script.contains(BOOTSTRAP_MARKER)); + assert!(script.contains("targetBase")); + assert!(script.contains("https://example.test/docs/index.html")); + assert!(script.contains("globalThis.fetch")); + assert!(script.contains("X-Rings-Webview-Kind")); + assert!(script.contains("patchLocationNavigation")); + assert!(script.contains("resolveTargetBase")); + assert!(script.contains("XMLHttpRequest")); + assert!(script.contains("encodeSrcdoc")); + assert!(script.contains("HTMLIFrameElement")); + assert!(script.contains("blockUnsupportedConstructor")); + assert!(script.contains("WebSocket")); + assert!(script.contains("EventSource")); + assert!(script.contains("sendBeacon")); + assert!(script.contains("SharedWorker")); + assert!(script.contains("HTMLBaseElement")); + assert!(script.contains("setAttribute")); + assert!(script.contains("encodeURIComponent")); + Ok(()) + } + + #[test] + fn runtime_urls_resolve_against_target_document_not_gateway_location() -> Result<()> { + let prefix = GatewayPrefix::new("/webview/")?; + let document_url = Url::parse("https://example.test/docs/index.html")?; + + let fetch_url = runtime_gateway_url(&prefix, &document_url, "/api/data") + .and_then(|url| required_gateway_url(url, "/api/data"))?; + let xhr_url = runtime_gateway_url(&prefix, &document_url, "forms/submit") + .and_then(|url| required_gateway_url(url, "forms/submit"))?; + + assert_eq!( + prefix.decode_path(&fetch_url)?.as_url().as_str(), + "https://example.test/api/data" + ); + assert_eq!( + prefix.decode_path(&xhr_url)?.as_url().as_str(), + "https://example.test/docs/forms/submit" + ); + Ok(()) + } + + fn required_gateway_url(url: Option, input: &str) -> Result { + url.ok_or_else(|| WebviewError::InvalidGatewayUrl(input.to_string())) + } + + #[test] + fn bootstrap_executes_runtime_routing_in_javascript() -> Result<()> { + let document_url = Url::parse("https://example.test/docs/index.html")?; + let script = bootstrap_script("/webview/", &document_url); + let program = format!( + r#" +const calls = []; +function assert(condition, message) {{ + if (!condition) throw new Error(message); +}} +function assertThrows(operation, message) {{ + let threw = false; + try {{ + operation(); + }} catch (_error) {{ + threw = true; + }} + if (!threw) throw new Error(message); +}} +class Request {{ + constructor(input, init) {{ + this.url = String(input); + this.init = init; + }} +}} +globalThis.Request = Request; +globalThis.fetch = function(input, init) {{ + calls.push(["fetch", input instanceof Request ? input.url : String(input), init]); + return "fetch-result"; +}}; +class XMLHttpRequest {{ + open(method, url, async, user, password) {{ + calls.push(["xhr", method, url, async, user, password]); + return "xhr-result"; + }} +}} +globalThis.XMLHttpRequest = XMLHttpRequest; +class WebSocket {{ + constructor(url, protocols) {{ + calls.push(["websocket", url, protocols]); + }} +}} +globalThis.WebSocket = WebSocket; +class EventSource {{ + constructor(url, init) {{ + calls.push(["eventsource", url, init]); + }} +}} +globalThis.EventSource = EventSource; +class Worker {{ + constructor(url, options) {{ + calls.push(["worker", url, options]); + }} +}} +globalThis.Worker = Worker; +class SharedWorker {{ + constructor(url, options) {{ + calls.push(["sharedworker", url, options]); + }} +}} +globalThis.SharedWorker = SharedWorker; +Object.defineProperty(globalThis, "navigator", {{ + value: {{ + sendBeacon(url, data) {{ + calls.push(["beacon", url, data]); + return true; + }} + }}, + configurable: true +}}); +class Element {{ + setAttribute(name, value) {{ + calls.push(["attribute", name, value]); + }} +}} +globalThis.Element = Element; +class HTMLImageElement extends Element {{ + set src(value) {{ + calls.push(["property", "img.src", value]); + }} + set srcset(value) {{ + calls.push(["property", "img.srcset", value]); + }} +}} +globalThis.HTMLImageElement = HTMLImageElement; +const submitListeners = []; +Object.defineProperty(globalThis, "location", {{ + value: {{ + origin: "http://127.0.0.1:3000", + assign(url) {{ calls.push(["navigate", url]); }} + }}, + configurable: true +}}); +Object.defineProperty(globalThis, "parent", {{ + value: {{ + postMessage(message, targetOrigin) {{ calls.push(["shell-navigation", message, targetOrigin]); }} + }}, + configurable: true +}}); +Object.defineProperty(globalThis, "document", {{ + value: {{ + querySelector() {{ return null; }}, + addEventListener(type, listener, capture) {{ + if (type === "submit" && capture) submitListeners.push(listener); + }} + }}, + configurable: true +}}); +class HTMLFormElement extends Element {{ + constructor() {{ + super(); + this.method = "get"; + this.target = ""; + this.attributes = new Map(); + this.fields = []; + }} + getAttribute(name) {{ return this.attributes.get(name) || null; }} + setAttribute(name, value) {{ this.attributes.set(name, value); }} + submit() {{ calls.push(["native-form-submit"]); }} +}} +globalThis.HTMLFormElement = HTMLFormElement; +globalThis.FormData = class FormData {{ + constructor(form) {{ this.fields = form.fields; }} + entries() {{ return this.fields[Symbol.iterator](); }} +}}; +{script} +const gateway = (url) => "/webview/" + encodeURIComponent(url); +await fetch("/api/data"); +await fetch(new Request("forms/submit"), {{ method: "POST" }}); +const xhr = new globalThis.XMLHttpRequest(); +xhr.open("POST", "forms/x", true); +assertThrows(() => new globalThis.WebSocket("/socket"), "WebSocket was not blocked"); +assertThrows(() => new globalThis.EventSource("events"), "EventSource was not blocked"); +const beaconResult = navigator.sendBeacon("/beacon", "payload"); +assert(beaconResult === false, "sendBeacon was not blocked"); +assertThrows(() => new globalThis.Worker("worker.js"), "Worker was not blocked"); +assertThrows(() => new globalThis.SharedWorker("shared.js"), "SharedWorker was not blocked"); +const element = new Element(); +element.setAttribute("src", "image.png"); +element.setAttribute("srcset", "small.png 1x, /big.png 2x"); +element.setAttribute("aria-label", "unchanged"); +const image = new globalThis.HTMLImageElement(); +image.src = "property.png"; +image.srcset = "property-small.png 1x, /property-big.png 2x"; +const form = new globalThis.HTMLFormElement(); +form.setAttribute("action", gateway("https://example.test/docs/search?existing=1")); +form.fields = [["q", "test"]]; +const submitEvent = {{ + target: form, + submitter: null, + preventDefault() {{ this.prevented = true; }}, + stopImmediatePropagation() {{ this.stopped = true; }} +}}; +for (const listener of submitListeners) listener(submitEvent); +const actual = JSON.stringify(calls); +assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/api/data")), "fetch URL was not rewritten: " + actual); +assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/docs/forms/submit")), "Request URL was not rewritten: " + actual); +assert(calls.some((call) => call[0] === "xhr" && call[2] === gateway("https://example.test/docs/forms/x")), "XHR URL was not rewritten: " + actual); +assert(!calls.some((call) => ["websocket", "eventsource", "beacon", "worker", "sharedworker"].includes(call[0])), "unsupported native entrypoint was called: " + actual); +assert(calls.some((call) => call[0] === "attribute" && call[1] === "src" && call[2] === gateway("https://example.test/docs/image.png")), "setAttribute src was not rewritten: " + actual); +assert(calls.some((call) => call[0] === "attribute" && call[1] === "srcset" && call[2].includes(gateway("https://example.test/docs/small.png")) && call[2].includes(gateway("https://example.test/big.png"))), "setAttribute srcset was not rewritten: " + actual); +assert(calls.some((call) => call[0] === "attribute" && call[1] === "aria-label" && call[2] === "unchanged"), "non-URL attribute changed: " + actual); +assert(calls.some((call) => call[0] === "property" && call[1] === "img.src" && call[2] === gateway("https://example.test/docs/property.png")), "img.src property was not rewritten: " + actual); +assert(calls.some((call) => call[0] === "property" && call[1] === "img.srcset" && call[2].includes(gateway("https://example.test/docs/property-small.png")) && call[2].includes(gateway("https://example.test/property-big.png"))), "img.srcset property was not rewritten: " + actual); +assert(submitEvent.prevented && submitEvent.stopped, "GET form submission was not intercepted"); +assert(calls.some((call) => call[0] === "navigate" && call[1] === gateway("https://example.test/docs/search?q=test")), "GET form query did not use native gateway navigation: " + actual); +"#, + script = script + ); + + let output = std::process::Command::new("node") + .arg("--input-type=module") + .arg("-e") + .arg(program) + .output() + .map_err(|error| WebviewError::Browser(error.to_string()))?; + + if !output.status.success() { + return Err(WebviewError::Browser(format!( + "node bootstrap test failed: stdout={} stderr={}", + String::from_utf8_lossy(output.stdout.as_slice()), + String::from_utf8_lossy(output.stderr.as_slice()) + ))); + } + Ok(()) + } + + #[test] + fn bootstrap_runtime_urls_follow_rewritten_base_href() -> Result<()> { + let document_url = Url::parse("https://example.test/docs/index.html")?; + let script = bootstrap_script("/webview/", &document_url); + let program = format!( + r#" +const calls = []; +const gateway = (url) => "/webview/" + encodeURIComponent(url); +function assert(condition, message) {{ + if (!condition) throw new Error(message); +}} +Object.defineProperty(globalThis, "location", {{ + value: {{ + href: "http://127.0.0.1:3000/webview/" + encodeURIComponent("https://example.test/docs/index.html"), + origin: "http://127.0.0.1:3000" + }}, + configurable: true +}}); +Object.defineProperty(globalThis, "document", {{ + value: {{ + querySelector(selector) {{ + if (selector !== "base[href]") return null; + return {{ + getAttribute(name) {{ + return name === "href" ? gateway("https://example.test/assets/") : null; + }} + }}; + }} + }}, + configurable: true +}}); +class Request {{ + constructor(input) {{ + this.url = String(input); + }} +}} +globalThis.Request = Request; +globalThis.fetch = function(input, init) {{ + calls.push(["fetch", input instanceof Request ? input.url : String(input), init]); + return "fetch-result"; +}}; +class XMLHttpRequest {{ + open(method, url, async, user, password) {{ + calls.push(["xhr", method, url, async, user, password]); + }} +}} +globalThis.XMLHttpRequest = XMLHttpRequest; +class Element {{ + setAttribute(name, value) {{ + calls.push(["attribute", name, value]); + }} +}} +globalThis.Element = Element; +class HTMLImageElement extends Element {{ + set src(value) {{ + calls.push(["property", "img.src", value]); + }} +}} +globalThis.HTMLImageElement = HTMLImageElement; +{script} +await fetch("api/data"); +const xhr = new globalThis.XMLHttpRequest(); +xhr.open("POST", "forms/submit", true); +const element = new Element(); +element.setAttribute("src", "image.png"); +const image = new globalThis.HTMLImageElement(); +image.src = "property.png"; +const alreadyGateway = await fetch("http://127.0.0.1:3000" + gateway("https://example.test/kept")); +const actual = JSON.stringify(calls); +assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/assets/api/data")), "fetch did not use base href: " + actual); +assert(calls.some((call) => call[0] === "xhr" && call[2] === gateway("https://example.test/assets/forms/submit")), "XHR did not use base href: " + actual); +assert(calls.some((call) => call[0] === "attribute" && call[1] === "src" && call[2] === gateway("https://example.test/assets/image.png")), "setAttribute did not use base href: " + actual); +assert(calls.some((call) => call[0] === "property" && call[1] === "img.src" && call[2] === gateway("https://example.test/assets/property.png")), "property setter did not use base href: " + actual); +assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/kept")), "same-origin gateway URL was encoded again: " + actual); +"#, + script = script + ); + + let output = std::process::Command::new("node") + .arg("--input-type=module") + .arg("-e") + .arg(program) + .output() + .map_err(|error| WebviewError::Browser(error.to_string()))?; + + if !output.status.success() { + return Err(WebviewError::Browser(format!( + "node base href bootstrap test failed: stdout={} stderr={}", + String::from_utf8_lossy(output.stdout.as_slice()), + String::from_utf8_lossy(output.stderr.as_slice()) + ))); + } + Ok(()) + } +} diff --git a/crates/webview/src/cookie.rs b/crates/webview/src/cookie.rs new file mode 100644 index 000000000..b8e098f46 --- /dev/null +++ b/crates/webview/src/cookie.rs @@ -0,0 +1,225 @@ +use url::Url; + +use crate::error::Result; +use crate::error::WebviewError; + +#[derive(Clone, Debug, Eq, PartialEq)] +struct StoredCookie { + name: String, + value: String, + domain: String, + host_only: bool, + path: String, + secure: bool, +} + +/// Virtual cookie jar keyed by target origin/domain/path. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct CookieJar { + cookies: Vec, +} + +impl CookieJar { + /// Create an empty cookie jar. + pub fn new() -> Self { + Self::default() + } + + /// Store one upstream `Set-Cookie` header for `origin`. + pub fn store_set_cookie(&mut self, origin: &Url, set_cookie: &str) -> Result<()> { + let Some(host) = origin.host_str() else { + return Err(WebviewError::Cookie( + "cookie origin host is empty".to_string(), + )); + }; + let mut parts = set_cookie.split(';').map(str::trim); + let Some(name_value) = parts.next() else { + return Err(WebviewError::Cookie("empty Set-Cookie".to_string())); + }; + let Some((name, value)) = name_value.split_once('=') else { + return Err(WebviewError::Cookie(format!( + "invalid Set-Cookie pair {name_value:?}" + ))); + }; + let name = name.trim(); + if name.is_empty() { + return Err(WebviewError::Cookie("cookie name is empty".to_string())); + } + + let mut cookie = StoredCookie { + name: name.to_string(), + value: value.trim().to_string(), + domain: host.to_ascii_lowercase(), + host_only: true, + path: default_cookie_path(origin.path()), + secure: false, + }; + + for part in parts { + let lower = part.to_ascii_lowercase(); + if lower == "secure" { + cookie.secure = true; + continue; + } + if let Some((key, value)) = part.split_once('=') { + if key.eq_ignore_ascii_case("domain") { + return Ok(()); + } else if key.eq_ignore_ascii_case("path") { + let path = value.trim(); + cookie.path = if path.starts_with('/') { + path.to_string() + } else { + "/".to_string() + }; + } + } + } + + self.cookies.retain(|existing| { + !(existing.name == cookie.name + && existing.domain == cookie.domain + && existing.path == cookie.path) + }); + self.cookies.push(cookie); + Ok(()) + } + + /// Build a `Cookie` request header for `target`, if any jar entries match. + pub fn cookie_header(&self, target: &Url) -> Option { + let host = target.host_str()?.to_ascii_lowercase(); + let path = target.path(); + let secure_request = target.scheme() == "https"; + let pairs: Vec = self + .cookies + .iter() + .filter(|cookie| { + (!cookie.secure || secure_request) + && domain_matches(cookie, &host) + && path_matches(cookie.path.as_str(), path) + }) + .map(|cookie| format!("{}={}", cookie.name, cookie.value)) + .collect(); + if pairs.is_empty() { + None + } else { + Some(pairs.join("; ")) + } + } + + /// Return the number of cookies currently stored. + pub fn len(&self) -> usize { + self.cookies.len() + } + + /// Return true when no cookies are stored. + pub fn is_empty(&self) -> bool { + self.cookies.is_empty() + } +} + +fn domain_matches(cookie: &StoredCookie, host: &str) -> bool { + if cookie.host_only { + return cookie.domain == host; + } + host == cookie.domain || host.ends_with(format!(".{}", cookie.domain).as_str()) +} + +fn path_matches(cookie_path: &str, request_path: &str) -> bool { + if request_path == cookie_path { + return true; + } + let Some(rest) = request_path.strip_prefix(cookie_path) else { + return false; + }; + cookie_path.ends_with('/') || rest.starts_with('/') +} + +fn default_cookie_path(path: &str) -> String { + if !path.starts_with('/') { + return "/".to_string(); + } + let mut segments = path.rsplitn(2, '/'); + let _last = segments.next(); + let Some(prefix) = segments.next() else { + return "/".to_string(); + }; + if prefix.is_empty() { + "/".to_string() + } else { + format!("{prefix}/") + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn cookie_matching_respects_host_only_path_and_secure() -> Result<()> { + let mut jar = CookieJar::new(); + let origin = Url::parse("https://example.com/app/index.html")?; + jar.store_set_cookie(&origin, "sid=one; Path=/app; Secure; HttpOnly")?; + jar.store_set_cookie(&origin, "theme=dark; Path=/")?; + + let target = Url::parse("https://sub.example.com/app/page")?; + assert_eq!(jar.cookie_header(&target), None); + + let host_target = Url::parse("https://example.com/app/page")?; + assert_eq!( + jar.cookie_header(&host_target).as_deref(), + Some("sid=one; theme=dark") + ); + + let insecure = Url::parse("http://example.com/app/page")?; + assert_eq!(jar.cookie_header(&insecure).as_deref(), Some("theme=dark")); + Ok(()) + } + + #[test] + fn cookie_ignores_domain_attributes() -> Result<()> { + let mut jar = CookieJar::new(); + let origin = Url::parse("https://evil.example/set-cookie")?; + + jar.store_set_cookie(&origin, "sid=stolen; Domain=example.com; Path=/")?; + assert!(jar.is_empty()); + Ok(()) + } + + #[test] + fn cookie_ignores_registry_controlled_and_platform_domain_attributes() -> Result<()> { + let mut jar = CookieJar::new(); + let dot_com_origin = Url::parse("https://evil.com/set-cookie")?; + let dot_uk_origin = Url::parse("https://service.co.uk/set-cookie")?; + let github_origin = Url::parse("https://evil.github.io/set-cookie")?; + + jar.store_set_cookie(&dot_com_origin, "sid=stolen; Domain=com; Path=/")?; + jar.store_set_cookie(&dot_uk_origin, "sid=stolen; Domain=co.uk; Path=/")?; + jar.store_set_cookie(&github_origin, "sid=stolen; Domain=github.io; Path=/")?; + assert!(jar.is_empty()); + Ok(()) + } + + #[test] + fn cookie_ignores_registrable_domain_attributes_by_default() -> Result<()> { + let mut jar = CookieJar::new(); + let origin = Url::parse("https://app.example.co.uk/set-cookie")?; + + jar.store_set_cookie(&origin, "sid=one; Domain=example.co.uk; Path=/")?; + assert!(jar.is_empty()); + Ok(()) + } + + #[test] + fn cookie_path_matching_respects_segment_boundary() -> Result<()> { + let mut jar = CookieJar::new(); + let origin = Url::parse("https://example.com/app/index.html")?; + jar.store_set_cookie(&origin, "sid=one; Path=/app")?; + + let inside = Url::parse("https://example.com/app/page")?; + let sibling = Url::parse("https://example.com/application")?; + + assert_eq!(jar.cookie_header(&inside).as_deref(), Some("sid=one")); + assert_eq!(jar.cookie_header(&sibling), None); + Ok(()) + } +} diff --git a/crates/webview/src/cors.rs b/crates/webview/src/cors.rs new file mode 100644 index 000000000..1bd33e529 --- /dev/null +++ b/crates/webview/src/cors.rs @@ -0,0 +1,277 @@ +//! Virtual CORS policy for runtime requests that share the controlled gateway origin. + +use std::collections::BTreeSet; + +use crate::error::Result; +use crate::error::WebviewError; +use crate::types::GatewayCredentials; +use crate::types::GatewayHeader; +use crate::types::GatewayRequest; +use crate::types::GatewayResponse; + +/// Build an upstream CORS preflight request when `request` requires one. +pub fn preflight_request(request: &GatewayRequest) -> Result> { + if !request.is_cross_origin_runtime_request() || !requires_preflight(request) { + return Ok(None); + } + let source_origin = request.source_origin.clone().ok_or_else(|| { + WebviewError::Cors("cross-origin request has no trusted source origin".to_string()) + })?; + let mut preflight = GatewayRequest::new(request.target.clone(), "OPTIONS", request.kind) + .with_source_origin(source_origin) + .with_credentials(GatewayCredentials::Omit) + .with_header(GatewayHeader::new( + "Access-Control-Request-Method", + request.method.clone(), + )?); + let headers = non_safelisted_headers(request); + if !headers.is_empty() { + preflight = preflight.with_header(GatewayHeader::new( + "Access-Control-Request-Headers", + headers.into_iter().collect::>().join(", "), + )?); + } + Ok(Some(preflight)) +} + +/// Validate an upstream runtime response against the virtual source origin. +pub fn validate_response(request: &GatewayRequest, response: &GatewayResponse) -> Result<()> { + if !request.is_cross_origin_runtime_request() { + return Ok(()); + } + let source_origin = source_origin(request)?; + validate_allowed_origin(response, source_origin, request.credentials)?; + if request.credentials == GatewayCredentials::Include + && !header_has_token(response, "access-control-allow-credentials", "true") + { + return Err(WebviewError::Cors( + "credentialed response lacks Access-Control-Allow-Credentials: true".to_string(), + )); + } + Ok(()) +} + +/// Validate a CORS preflight response before forwarding the actual runtime request. +pub fn validate_preflight_response( + request: &GatewayRequest, + response: &GatewayResponse, +) -> Result<()> { + if !(200..300).contains(&response.status) { + return Err(WebviewError::Cors(format!( + "preflight returned HTTP {}", + response.status + ))); + } + let source_origin = source_origin(request)?; + validate_allowed_origin(response, source_origin, request.credentials)?; + let method_allowed = header_values(response, "access-control-allow-methods") + .flat_map(|value| value.split(',')) + .any(|value| value.trim().eq_ignore_ascii_case(request.method.as_str())); + if !method_allowed { + return Err(WebviewError::Cors(format!( + "preflight does not allow method {}", + request.method + ))); + } + let allowed_headers = header_values(response, "access-control-allow-headers") + .flat_map(|value| value.split(',')) + .map(|value| value.trim().to_ascii_lowercase()) + .collect::>(); + let requested_headers = non_safelisted_headers(request); + if !requested_headers.is_empty() + && !allowed_headers.contains("*") + && !requested_headers + .iter() + .all(|header| allowed_headers.contains(header)) + { + return Err(WebviewError::Cors( + "preflight does not allow every requested header".to_string(), + )); + } + if request.credentials == GatewayCredentials::Include + && !header_has_token(response, "access-control-allow-credentials", "true") + { + return Err(WebviewError::Cors( + "credentialed preflight lacks Access-Control-Allow-Credentials: true".to_string(), + )); + } + Ok(()) +} + +fn requires_preflight(request: &GatewayRequest) -> bool { + !is_safelisted_method(request.method.as_str()) || !non_safelisted_headers(request).is_empty() +} + +fn is_safelisted_method(method: &str) -> bool { + matches!(method, "GET" | "HEAD" | "POST") +} + +fn non_safelisted_headers(request: &GatewayRequest) -> BTreeSet { + request + .headers + .iter() + .filter(|header| !is_gateway_stripped_header(header.name.as_str())) + .filter(|header| !is_safelisted_header(header)) + .map(|header| header.name.to_ascii_lowercase()) + .collect() +} + +fn is_gateway_stripped_header(name: &str) -> bool { + let lower = name.to_ascii_lowercase(); + lower.starts_with("sec-") + || matches!( + lower.as_str(), + "accept-encoding" + | "connection" + | "content-length" + | "cookie" + | "expect" + | "host" + | "keep-alive" + | "origin" + | "proxy-authenticate" + | "proxy-authorization" + | "proxy-connection" + | "referer" + | "te" + | "trailer" + | "transfer-encoding" + | "upgrade" + | "via" + ) +} + +fn is_safelisted_header(header: &GatewayHeader) -> bool { + if matches!( + header.name.to_ascii_lowercase().as_str(), + "accept" | "accept-language" | "content-language" + ) { + return true; + } + if !header.name_eq("content-type") { + return false; + } + let content_type = header + .value + .split(';') + .next() + .unwrap_or_default() + .trim() + .to_ascii_lowercase(); + matches!( + content_type.as_str(), + "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" + ) +} + +fn source_origin(request: &GatewayRequest) -> Result { + request + .source_origin + .as_ref() + .map(|source| source.origin().ascii_serialization()) + .ok_or_else(|| { + WebviewError::Cors("cross-origin request has no trusted source origin".to_string()) + }) +} + +fn validate_allowed_origin( + response: &GatewayResponse, + source_origin: String, + credentials: GatewayCredentials, +) -> Result<()> { + let allowed = header_values(response, "access-control-allow-origin").any(|value| { + let value = value.trim(); + value == source_origin || (value == "*" && credentials != GatewayCredentials::Include) + }); + if allowed { + Ok(()) + } else { + Err(WebviewError::Cors(format!( + "response does not allow origin {source_origin}" + ))) + } +} + +fn header_values<'a>( + response: &'a GatewayResponse, + name: &'a str, +) -> impl Iterator { + response + .headers + .iter() + .filter(move |header| header.name_eq(name)) + .map(|header| header.value.as_str()) +} + +fn header_has_token(response: &GatewayResponse, name: &str, expected: &str) -> bool { + header_values(response, name).any(|value| value.trim().eq_ignore_ascii_case(expected)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::types::GatewayRequestKind; + use url::Url; + + fn request(credentials: GatewayCredentials) -> Result { + Ok(GatewayRequest::new( + Url::parse("https://api.example.test/data")?, + "PATCH", + GatewayRequestKind::Fetch, + ) + .with_source_origin(Url::parse("https://app.example.test/page")?) + .with_credentials(credentials) + .with_header(GatewayHeader::new("Origin", "http://127.0.0.1:8080")?) + .with_header(GatewayHeader::new("Sec-Fetch-Mode", "cors")?) + .with_header(GatewayHeader::new("X-Requested-With", "Rings")?)) + } + + #[test] + fn preflight_contains_virtual_origin_method_and_headers() -> Result<()> { + let request = request(GatewayCredentials::SameOrigin)?; + let preflight = preflight_request(&request)?.ok_or_else(|| { + WebviewError::Cors("expected cross-origin request to require preflight".to_string()) + })?; + + assert_eq!(preflight.method, "OPTIONS"); + assert_eq!(preflight.credentials, GatewayCredentials::Omit); + assert!(preflight.headers.iter().any(|header| header + .name_eq("access-control-request-method") + && header.value == "PATCH")); + assert!(preflight.headers.iter().any(|header| { + header.name_eq("access-control-request-headers") && header.value == "x-requested-with" + })); + Ok(()) + } + + #[test] + fn wildcard_response_is_denied_for_credentialed_runtime_requests() -> Result<()> { + let request = request(GatewayCredentials::Include)?; + let response = GatewayResponse::new( + 200, + vec![GatewayHeader::new("Access-Control-Allow-Origin", "*")?], + Vec::new(), + )?; + + assert!(matches!( + validate_response(&request, &response), + Err(WebviewError::Cors(_)) + )); + Ok(()) + } + + #[test] + fn exact_origin_and_credentials_allow_cross_origin_runtime_response() -> Result<()> { + let request = request(GatewayCredentials::Include)?; + let response = GatewayResponse::new( + 200, + vec![ + GatewayHeader::new("Access-Control-Allow-Origin", "https://app.example.test")?, + GatewayHeader::new("Access-Control-Allow-Credentials", "true")?, + ], + Vec::new(), + )?; + + validate_response(&request, &response) + } +} diff --git a/crates/webview/src/error.rs b/crates/webview/src/error.rs new file mode 100644 index 000000000..57b5e9b96 --- /dev/null +++ b/crates/webview/src/error.rs @@ -0,0 +1,46 @@ +use thiserror::Error; + +/// Result type used by the webview gateway. +pub type Result = std::result::Result; + +/// Errors raised while normalizing, rewriting, or forwarding gateway traffic. +#[derive(Debug, Error)] +pub enum WebviewError { + /// A gateway prefix is not a path prefix owned by the local application. + #[error("invalid gateway prefix {0:?}")] + InvalidGatewayPrefix(String), + /// A gateway URL did not contain an encoded target URL. + #[error("invalid gateway URL {0:?}")] + InvalidGatewayUrl(String), + /// Percent-decoding failed. + #[error("failed to decode gateway URL {0:?}")] + Decode(String), + /// Controlled-origin configuration is invalid. + #[error("invalid controlled origin {0:?}")] + InvalidControlledOrigin(String), + /// The target URL could not be parsed. + #[error("invalid target URL: {0}")] + Url(#[from] url::ParseError), + /// The target scheme is outside the gateway policy. + #[error("unsupported target URL scheme {0:?}")] + UnsupportedScheme(String), + /// Header validation or policy normalization failed. + #[error("header policy error: {0}")] + Header(String), + /// Cookie parsing or matching failed. + #[error("cookie policy error: {0}")] + Cookie(String), + /// A cross-origin runtime response did not satisfy the virtual CORS policy. + #[error("CORS policy error: {0}")] + Cors(String), + /// The pluggable transport failed. + #[error("gateway transport failed: {0}")] + Transport(String), + /// A gateway response could not be rendered as a page. + #[error("webview render failed: {0}")] + Render(String), + /// Browser integration failed. + #[cfg(feature = "browser")] + #[error("browser integration failed: {0}")] + Browser(String), +} diff --git a/crates/webview/src/header.rs b/crates/webview/src/header.rs new file mode 100644 index 000000000..b9b4e9877 --- /dev/null +++ b/crates/webview/src/header.rs @@ -0,0 +1,218 @@ +use url::Url; + +use crate::error::Result; +use crate::rewrite::rewrite_refresh_value; +use crate::types::GatewayHeader; +use crate::types::GatewayRequest; +use crate::types::GatewayResponse; +use crate::url::GatewayPrefix; + +const GATEWAY_CONTENT_SECURITY_POLICY: &str = "default-src 'self' data: blob:; base-uri 'self'; connect-src 'self'; font-src 'self' data:; form-action 'self'; frame-src 'self' data: blob:; img-src 'self' data: blob:; media-src 'self' data: blob:; object-src 'self'; script-src 'self' data: 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' blob:; style-src 'self' data: 'unsafe-inline'; worker-src 'none'"; + +/// Header policy for controlled webview documents. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct HeaderPolicy { + gateway_prefix: GatewayPrefix, +} + +impl HeaderPolicy { + /// Build a header policy that rewrites target redirects into `gateway_prefix`. + pub fn new(gateway_prefix: GatewayPrefix) -> Self { + Self { gateway_prefix } + } + + /// Normalize controlled-origin request headers before they reach a target transport. + pub fn normalize_request(&self, mut request: GatewayRequest) -> GatewayRequest { + request + .headers + .retain(|header| !should_strip_request_header(header.name.as_str())); + if let Some(source_origin) = request.source_origin.as_ref() { + request.headers.push(GatewayHeader { + name: "Origin".to_string(), + value: source_origin.origin().ascii_serialization(), + }); + } + request + } + + /// Normalize transport response headers for a proxied target URL. + pub fn normalize_response( + &self, + target: &Url, + response: GatewayResponse, + ) -> Result { + let mut headers = Vec::new(); + for header in response.headers { + if should_strip_response_header(header.name.as_str()) { + continue; + } + if header.name_eq("location") { + if let Some(location) = self + .gateway_prefix + .rewrite_url_value(target, header.value.as_str())? + { + headers.push(GatewayHeader::new(header.name, location)?); + } + continue; + } + if header.name_eq("refresh") { + headers.push(GatewayHeader::new( + header.name, + rewrite_refresh_value(header.value.as_str(), target, &self.gateway_prefix)?, + )?); + continue; + } + headers.push(header); + } + headers.push(GatewayHeader::new( + "Content-Security-Policy", + GATEWAY_CONTENT_SECURITY_POLICY, + )?); + GatewayResponse::new(response.status, headers, response.body) + } +} + +fn should_strip_request_header(name: &str) -> bool { + let lower = name.to_ascii_lowercase(); + lower.starts_with("sec-fetch-") + || matches!( + lower.as_str(), + "accept-encoding" + | "connection" + | "content-length" + | "cookie" + | "expect" + | "host" + | "keep-alive" + | "origin" + | "proxy-authenticate" + | "proxy-authorization" + | "proxy-connection" + | "referer" + | "te" + | "trailer" + | "transfer-encoding" + | "upgrade" + | "via" + ) +} + +fn should_strip_response_header(name: &str) -> bool { + const STRIPPED: &[&str] = &[ + "connection", + "keep-alive", + "proxy-authenticate", + "proxy-authorization", + "te", + "trailer", + "transfer-encoding", + "upgrade", + "content-security-policy", + "content-security-policy-report-only", + "x-frame-options", + "strict-transport-security", + "set-cookie", + ]; + STRIPPED + .iter() + .any(|candidate| name.eq_ignore_ascii_case(candidate)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::types::GatewayRequestKind; + + #[test] + fn redirect_location_rewrites_to_gateway_url() -> Result<()> { + let target = Url::parse("https://example.com/app/page")?; + let policy = HeaderPolicy::new(GatewayPrefix::new("/webview/")?); + let response = GatewayResponse::new( + 302, + vec![ + GatewayHeader::new("Location", "../login?next=1")?, + GatewayHeader::new("Content-Security-Policy", "default-src 'none'")?, + GatewayHeader::new("Content-Type", "text/html")?, + ], + Vec::new(), + )?; + + let normalized = policy.normalize_response(&target, response)?; + + assert_eq!(normalized.headers.len(), 3); + assert!(normalized + .headers + .iter() + .any(|header| { header.name_eq("location") && header.value.starts_with("/webview/") })); + assert!(normalized.headers.iter().any(|header| { + header.name_eq("content-security-policy") + && header.value == GATEWAY_CONTENT_SECURITY_POLICY + })); + Ok(()) + } + + #[test] + fn refresh_header_rewrites_to_gateway_url() -> Result<()> { + let target = Url::parse("https://example.com/app/page")?; + let policy = HeaderPolicy::new(GatewayPrefix::new("/webview/")?); + let response = GatewayResponse::new( + 200, + vec![GatewayHeader::new("Refresh", "0; URL='../login?next=1'")?], + Vec::new(), + )?; + + let normalized = policy.normalize_response(&target, response)?; + + let refresh = normalized + .headers + .iter() + .find(|header| header.name_eq("refresh")) + .ok_or_else(|| { + crate::error::WebviewError::Header("missing refresh header".to_string()) + })?; + assert!(refresh + .value + .contains("/webview/https%3A%2F%2Fexample%2Ecom%2Flogin%3Fnext%3D1")); + assert!(!refresh.value.contains("../login?next=1")); + Ok(()) + } + + #[test] + fn request_policy_strips_controlled_origin_and_hop_headers() -> Result<()> { + let target = Url::parse("https://example.com/app/page")?; + let policy = HeaderPolicy::new(GatewayPrefix::new("/webview/")?); + let request = GatewayRequest { + target, + method: "GET".to_string(), + headers: vec![ + GatewayHeader::new("Host", "127.0.0.1:3000")?, + GatewayHeader::new("Origin", "http://127.0.0.1:3000")?, + GatewayHeader::new("Referer", "http://127.0.0.1:3000/webview/x")?, + GatewayHeader::new("Sec-Fetch-Dest", "document")?, + GatewayHeader::new("Cookie", "caller=leak")?, + GatewayHeader::new("Accept", "text/html")?, + GatewayHeader::new("X-App-Trace", "kept")?, + ], + body: Vec::new(), + kind: GatewayRequestKind::Navigation, + source_origin: None, + credentials: crate::types::GatewayCredentials::SameOrigin, + }; + + let normalized = policy.normalize_request(request); + + assert!(normalized.headers.iter().all(|header| !matches!( + header.name.to_ascii_lowercase().as_str(), + "host" | "origin" | "referer" | "sec-fetch-dest" | "cookie" + ))); + assert!(normalized + .headers + .iter() + .any(|header| header.name_eq("accept") && header.value == "text/html")); + assert!(normalized + .headers + .iter() + .any(|header| header.name_eq("x-app-trace") && header.value == "kept")); + Ok(()) + } +} diff --git a/crates/webview/src/lib.rs b/crates/webview/src/lib.rs new file mode 100644 index 000000000..ba934b75d --- /dev/null +++ b/crates/webview/src/lib.rs @@ -0,0 +1,59 @@ +#![warn(missing_docs)] +//! Rings webview gateway primitives. +//! +//! This crate owns the reusable, UI-independent pieces required to serve remote +//! pages through a Rings-owned gateway route: target URL encoding, typed gateway +//! requests and responses, header policy, virtual cookies, response rewriting, +//! and a pluggable transport boundary. +//! +//! `browser` bootstrap hooks preserve ordinary page behavior, but a WebView host +//! must apply [`GatewayRoutePolicy`] before opening a browser connection. That +//! trusted boundary redirects navigation, rejects cross-target runtime reads, +//! and keeps direct remote traffic out of the browser network stack. + +/// Virtual cookie jar for target-origin cookies. +pub mod cookie; +/// Virtual CORS request and response policy. +pub mod cors; +/// Error and result types. +pub mod error; +/// Response header normalization policy. +pub mod header; +/// Render target pages into gateway-rewritten HTML. +pub mod render; +/// HTML and CSS rewriting helpers. +pub mod rewrite; +/// Host request routing policy for controlled webview origins. +pub mod route; +/// Pluggable gateway transport and policy wrapper. +pub mod transport; +/// Typed gateway request and response DTOs. +pub mod types; +/// Target URL encoding and gateway route helpers. +pub mod url; + +#[cfg(feature = "browser")] +pub mod browser; + +pub use cookie::CookieJar; +pub use cors::preflight_request; +pub use cors::validate_response; +pub use error::Result; +pub use error::WebviewError; +pub use header::HeaderPolicy; +pub use render::RenderedPage; +pub use render::WebviewRenderer; +pub use rewrite::RewriteContext; +pub use route::GatewayRoute; +pub use route::GatewayRoutePolicy; +pub use route::GatewayRouteRejection; +pub use transport::ConcurrentWebviewGateway; +pub use transport::GatewayTransport; +pub use transport::WebviewGateway; +pub use types::GatewayCredentials; +pub use types::GatewayHeader; +pub use types::GatewayRequest; +pub use types::GatewayRequestKind; +pub use types::GatewayResponse; +pub use url::GatewayPrefix; +pub use url::TargetUrl; diff --git a/crates/webview/src/render.rs b/crates/webview/src/render.rs new file mode 100644 index 000000000..cd817140b --- /dev/null +++ b/crates/webview/src/render.rs @@ -0,0 +1,169 @@ +//! Render target pages into gateway-rewritten HTML. + +use url::Url; + +use crate::error::Result; +use crate::error::WebviewError; +use crate::transport::GatewayTransport; +use crate::transport::WebviewGateway; +use crate::types::GatewayHeader; +use crate::types::GatewayRequest; +use crate::url::TargetUrl; + +/// A target page rendered through the webview gateway. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct RenderedPage { + /// Original target URL. + pub target: Url, + /// Controlled-origin URL that represents the target. + pub gateway_url: String, + /// Upstream status after gateway policy normalization. + pub status: u16, + /// Response headers after gateway policy normalization. + pub headers: Vec, + html: String, +} + +impl RenderedPage { + /// Borrow the rewritten HTML body suitable for a controlled renderer. + pub fn html(&self) -> &str { + &self.html + } + + /// Consume this page and return the rewritten HTML body. + pub fn into_html(self) -> String { + self.html + } +} + +/// Page renderer backed by a reusable gateway transport. +pub struct WebviewRenderer { + gateway: WebviewGateway, +} + +impl WebviewRenderer +where + T: GatewayTransport, +{ + /// Build a renderer around an existing gateway. + pub fn new(gateway: WebviewGateway) -> Self { + Self { gateway } + } + + /// Access the underlying gateway policy state. + pub fn gateway(&self) -> &WebviewGateway { + &self.gateway + } + + /// Mutably access the underlying gateway policy state. + pub fn gateway_mut(&mut self) -> &mut WebviewGateway { + &mut self.gateway + } + + /// Render a target page into gateway-rewritten HTML. + pub async fn render(&mut self, target: TargetUrl) -> Result { + let target = target.into_url(); + let gateway_url = self.gateway.prefix().encode(&target); + let response = self + .gateway + .send(GatewayRequest::navigation(target.clone())) + .await?; + let html = String::from_utf8(response.body).map_err(|error| { + WebviewError::Render(format!("HTML response is not UTF-8: {error}")) + })?; + Ok(RenderedPage { + target, + gateway_url, + status: response.status, + headers: response.headers, + html, + }) + } +} + +#[cfg(test)] +mod tests { + use std::cell::RefCell; + + use async_trait::async_trait; + + use super::*; + use crate::types::GatewayResponse; + use crate::GatewayPrefix; + + struct FixtureTransport { + requests: RefCell>, + } + + impl FixtureTransport { + fn new() -> Self { + Self { + requests: RefCell::new(Vec::new()), + } + } + } + + #[async_trait(?Send)] + impl GatewayTransport for FixtureTransport { + async fn send(&self, request: GatewayRequest) -> Result { + self.requests.borrow_mut().push(request); + GatewayResponse::new( + 200, + vec![ + GatewayHeader::new("Content-Type", "text/html; charset=utf-8")?, + GatewayHeader::new("Set-Cookie", "sid=fixture; Path=/docs; Secure")?, + GatewayHeader::new("Content-Security-Policy", "default-src 'none'")?, + ], + br#" + + + + + + + next + + +"# + .to_vec(), + ) + } + } + + #[test] + fn renderer_outputs_gateway_rewritten_html_page() -> Result<()> { + let gateway = + WebviewGateway::new(GatewayPrefix::new("/webview/")?, FixtureTransport::new()) + .with_bootstrap_script("globalThis.__ringsWebview = true;"); + let mut renderer = WebviewRenderer::new(gateway); + + let page = futures::executor::block_on( + renderer.render(TargetUrl::parse("https://example.test/docs/index.html")?), + )?; + + assert_eq!(page.status, 200); + assert!(page.gateway_url.starts_with("/webview/")); + assert!(page.html().contains("data-rings-webview-bootstrap")); + assert!(page + .html() + .contains("/webview/https%3A%2F%2Fexample%2Etest%2Fassets%2Fsite%2Ecss")); + assert!(page + .html() + .contains("/webview/https%3A%2F%2Fexample%2Etest%2Fdocs%2Fapp%2Ejs")); + assert!(page + .html() + .contains("/webview/https%3A%2F%2Fexample%2Etest%2Fnext")); + assert!(page + .html() + .contains("/webview/https%3A%2F%2Fexample%2Etest%2Fhero%2Epng")); + assert!(!page + .headers + .iter() + .any(|header| header.name_eq("set-cookie"))); + assert!(page.headers.iter().any(|header| { + header.name_eq("content-security-policy") && header.value.contains("connect-src 'self'") + })); + assert_eq!(renderer.gateway().cookies().len(), 1); + Ok(()) + } +} diff --git a/crates/webview/src/rewrite.rs b/crates/webview/src/rewrite.rs new file mode 100644 index 000000000..ba62a2768 --- /dev/null +++ b/crates/webview/src/rewrite.rs @@ -0,0 +1,677 @@ +use std::cell::Cell; +use std::cell::RefCell; +use std::error::Error; + +use lol_html::element; +use lol_html::end; +use lol_html::html_content::ContentType; +use lol_html::html_content::Element; +use lol_html::html_content::TextChunk; +use lol_html::rewrite_str; +use lol_html::text; +use lol_html::HandlerTypes; +use lol_html::RewriteStrSettings; +use url::Url; + +use crate::error::Result; +use crate::error::WebviewError; +use crate::url::GatewayPrefix; + +/// Context required to rewrite one target document or stylesheet. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct RewriteContext { + gateway_prefix: GatewayPrefix, + document_url: Url, + bootstrap_script: Option, +} + +impl RewriteContext { + /// Build a rewrite context for `document_url`. + pub fn new(gateway_prefix: GatewayPrefix, document_url: Url) -> Self { + Self { + gateway_prefix, + document_url, + bootstrap_script: None, + } + } + + /// Attach a bootstrap runtime script to inject into HTML documents. + pub fn with_bootstrap_script(mut self, script: impl Into) -> Self { + self.bootstrap_script = Some(script.into()); + self + } + + /// Rewrite one HTML document body. + pub fn rewrite_html(&self, html: &str) -> Result { + let bootstrap = self + .bootstrap_script + .as_ref() + .map(|script| bootstrap_tag(script)); + let injected = Cell::new(bootstrap.is_none()); + let html_state = HtmlRewriteState::new( + &self.gateway_prefix, + self.document_url.clone(), + self.bootstrap_script.as_deref(), + ); + let style_text = RefCell::new(String::new()); + rewrite_str( + html, + RewriteStrSettings::new() + .append_element_content_handler(element!("*", |element| { + rewrite_html_element(element, &html_state)?; + if !injected.get() { + if let Some(tag) = bootstrap.as_deref() { + if element.tag_name().eq_ignore_ascii_case("head") { + element.prepend(tag, ContentType::Html); + injected.set(true); + } else if element.tag_name().eq_ignore_ascii_case("script") { + element.before(tag, ContentType::Html); + injected.set(true); + } + } + } + Ok(()) + })) + .append_element_content_handler(text!("style", |text| { + rewrite_style_text(text, &html_state, &style_text)?; + Ok(()) + })) + .append_document_content_handler(end!(|end| { + if !injected.get() { + if let Some(tag) = bootstrap.as_deref() { + end.append(tag, ContentType::Html); + injected.set(true); + } + } + Ok(()) + })), + ) + .map_err(|error| WebviewError::Render(format!("HTML rewrite failed: {error}"))) + } + + /// Rewrite one CSS stylesheet body. + pub fn rewrite_css(&self, css: &str) -> Result { + let imports = rewrite_css_imports(css, self)?; + rewrite_css_urls(&imports, self) + } + + fn rewrite_url(&self, value: &str) -> Result> { + self.gateway_prefix + .rewrite_url_value(&self.document_url, value) + } +} + +struct HtmlRewriteState<'a> { + gateway_prefix: &'a GatewayPrefix, + current_base: RefCell, + base_href_seen: Cell, + bootstrap_script: Option<&'a str>, +} + +impl<'a> HtmlRewriteState<'a> { + fn new( + gateway_prefix: &'a GatewayPrefix, + document_url: Url, + bootstrap_script: Option<&'a str>, + ) -> Self { + Self { + gateway_prefix, + current_base: RefCell::new(document_url), + base_href_seen: Cell::new(false), + bootstrap_script, + } + } + + fn rewrite_url(&self, value: &str) -> Result> { + let base = self.current_base.borrow(); + self.gateway_prefix.rewrite_url_value(&base, value) + } + + fn rewrite_base_href(&self, value: &str) -> Result> { + let base = self.current_base.borrow().clone(); + let Some(target) = self.gateway_prefix.resolve_url_value(&base, value)? else { + return Ok(None); + }; + if !self.base_href_seen.get() { + self.current_base.replace(target.clone()); + self.base_href_seen.set(true); + } + Ok(Some(self.gateway_prefix.encode(&target))) + } + + fn rewrite_css(&self, css: &str) -> Result { + let base = self.current_base.borrow().clone(); + RewriteContext::new(self.gateway_prefix.clone(), base).rewrite_css(css) + } + + fn rewrite_srcdoc(&self, html: &str) -> Result { + let base = self.current_base.borrow().clone(); + let mut context = RewriteContext::new(self.gateway_prefix.clone(), base); + if let Some(script) = self.bootstrap_script { + context = context.with_bootstrap_script(script); + } + context.rewrite_html(decode_srcdoc_attribute_value(html).as_str()) + } + + fn rewrite_refresh(&self, value: &str) -> Result { + let base = self.current_base.borrow(); + rewrite_refresh_value(value, &base, self.gateway_prefix) + } +} + +fn rewrite_html_element( + element: &mut Element<'_, '_, H>, + state: &HtmlRewriteState<'_>, +) -> std::result::Result<(), Box> +where + H: HandlerTypes, +{ + let tag_name = element.tag_name(); + let is_base = tag_name.eq_ignore_ascii_case("base"); + let attributes: Vec<(String, String)> = element + .attributes() + .iter() + .map(|attribute| (attribute.name(), attribute.value())) + .collect(); + let is_meta_refresh = tag_name.eq_ignore_ascii_case("meta") + && attributes.iter().any(|(name, value)| { + name.eq_ignore_ascii_case("http-equiv") && value.trim().eq_ignore_ascii_case("refresh") + }); + for (name, value) in attributes { + let lower_name = name.to_ascii_lowercase(); + if is_base && lower_name == "href" { + if let Some(rewritten) = state.rewrite_base_href(value.as_str())? { + element.set_attribute(name.as_str(), rewritten.as_str())?; + } + } else if lower_name == "srcdoc" { + let rewritten = state.rewrite_srcdoc(value.as_str())?; + element.set_attribute(name.as_str(), rewritten.as_str())?; + } else if lower_name == "ping" { + let rewritten = rewrite_url_list_value(value.as_str(), state)?; + element.set_attribute(name.as_str(), rewritten.as_str())?; + } else if is_meta_refresh && lower_name == "content" { + let rewritten = state.rewrite_refresh(value.as_str())?; + element.set_attribute(name.as_str(), rewritten.as_str())?; + } else if is_url_attribute(lower_name.as_str()) { + if let Some(rewritten) = state.rewrite_url(value.as_str())? { + element.set_attribute(name.as_str(), rewritten.as_str())?; + } + } else if is_srcset_attribute(lower_name.as_str()) { + let rewritten = rewrite_srcset_value(value.as_str(), state)?; + element.set_attribute(name.as_str(), rewritten.as_str())?; + } else if lower_name == "style" { + let rewritten = state.rewrite_css(value.as_str())?; + element.set_attribute(name.as_str(), rewritten.as_str())?; + } + } + Ok(()) +} + +fn rewrite_style_text( + text: &mut TextChunk<'_>, + state: &HtmlRewriteState<'_>, + buffer: &RefCell, +) -> std::result::Result<(), Box> { + let mut buffered = buffer.borrow_mut(); + buffered.push_str(text.as_str()); + if !text.last_in_text_node() { + text.replace("", ContentType::Text); + return Ok(()); + } + + let css = std::mem::take(&mut *buffered); + drop(buffered); + let rewritten = state.rewrite_css(css.as_str())?; + text.replace(rewritten.as_str(), ContentType::Text); + Ok(()) +} + +fn is_url_attribute(name: &str) -> bool { + matches!( + name, + "href" + | "src" + | "action" + | "poster" + | "data" + | "cite" + | "formaction" + | "manifest" + | "xlink:href" + ) +} + +fn is_srcset_attribute(name: &str) -> bool { + matches!(name, "srcset" | "imagesrcset") +} + +fn rewrite_srcset_value(value: &str, state: &HtmlRewriteState<'_>) -> Result { + let mut out = Vec::new(); + for candidate in value.split(',') { + let trimmed = candidate.trim(); + if trimmed.is_empty() { + continue; + } + let mut parts = trimmed.splitn(2, char::is_whitespace); + let url = parts.next().unwrap_or_default(); + let descriptor = parts.next().unwrap_or_default().trim(); + let rewritten = state.rewrite_url(url)?.unwrap_or_else(|| url.to_string()); + if descriptor.is_empty() { + out.push(rewritten); + } else { + out.push(format!("{rewritten} {descriptor}")); + } + } + Ok(out.join(", ")) +} + +/// Rewrite a space-separated HTML URL list, such as an anchor `ping` value. +fn rewrite_url_list_value(value: &str, state: &HtmlRewriteState<'_>) -> Result { + let mut rewritten = Vec::new(); + for candidate in value.split_whitespace() { + rewritten.push( + state + .rewrite_url(candidate)? + .unwrap_or_else(|| candidate.to_string()), + ); + } + Ok(rewritten.join(" ")) +} + +fn rewrite_css_urls(input: &str, ctx: &RewriteContext) -> Result { + let mut output = String::with_capacity(input.len()); + let mut rest = input; + while let Some(index) = find_ascii_case_insensitive(rest, "url(") { + let (before, after_url) = split_at_checked(rest, index)?; + let (url_token, after_open) = split_at_checked(after_url, "url(".len())?; + output.push_str(before); + output.push_str(url_token); + let Some((raw_value, tail)) = after_open.split_once(')') else { + output.push_str(after_open); + return Ok(output); + }; + let (quote, value) = trim_css_url(raw_value); + if let Some(rewritten) = ctx.rewrite_url(value)? { + if let Some(quote) = quote { + output.push(quote); + output.push_str(rewritten.as_str()); + output.push(quote); + } else { + output.push_str(rewritten.as_str()); + } + } else { + output.push_str(raw_value); + } + output.push(')'); + rest = tail; + } + output.push_str(rest); + Ok(output) +} + +fn trim_css_url(raw_value: &str) -> (Option, &str) { + let trimmed = raw_value.trim(); + if let Some(value) = trimmed + .strip_prefix('"') + .and_then(|value| value.strip_suffix('"')) + { + (Some('"'), value) + } else if let Some(value) = trimmed + .strip_prefix('\'') + .and_then(|value| value.strip_suffix('\'')) + { + (Some('\''), value) + } else { + (None, trimmed) + } +} + +fn rewrite_css_imports(input: &str, ctx: &RewriteContext) -> Result { + let mut output = String::with_capacity(input.len()); + let mut rest = input; + while let Some(index) = find_ascii_case_insensitive(rest, "@import") { + let (before, after_import) = split_at_checked(rest, index)?; + let (import_token, after_token) = split_at_checked(after_import, "@import".len())?; + output.push_str(before); + output.push_str(import_token); + let whitespace_len = after_token + .bytes() + .take_while(u8::is_ascii_whitespace) + .count(); + let (whitespace, after_whitespace) = split_at_checked(after_token, whitespace_len)?; + output.push_str(whitespace); + let Some(quote) = after_whitespace + .chars() + .next() + .filter(|ch| matches!(ch, '"' | '\'')) + else { + rest = after_whitespace; + continue; + }; + let Some(after_quote) = after_whitespace.strip_prefix(quote) else { + output.push_str(after_whitespace); + return Ok(output); + }; + let Some((value, tail)) = after_quote.split_once(quote) else { + output.push(quote); + output.push_str(after_quote); + return Ok(output); + }; + output.push(quote); + if let Some(rewritten) = ctx.rewrite_url(value)? { + output.push_str(rewritten.as_str()); + } else { + output.push_str(value); + } + output.push(quote); + rest = tail; + } + output.push_str(rest); + Ok(output) +} + +/// Rewrite a Refresh header or meta refresh content value through the gateway. +pub(crate) fn rewrite_refresh_value( + value: &str, + base_url: &Url, + gateway_prefix: &GatewayPrefix, +) -> Result { + let Some(url_index) = find_refresh_url_key(value) else { + return Ok(value.to_string()); + }; + let (before_url, after_url) = split_at_checked(value, url_index)?; + let (url_token, after_token) = split_at_checked(after_url, "url".len())?; + let whitespace_len = after_token + .bytes() + .take_while(u8::is_ascii_whitespace) + .count(); + let (whitespace, after_whitespace) = split_at_checked(after_token, whitespace_len)?; + let Some(after_equals) = after_whitespace.strip_prefix('=') else { + return Ok(value.to_string()); + }; + let value_whitespace_len = after_equals + .bytes() + .take_while(u8::is_ascii_whitespace) + .count(); + let (value_whitespace, raw_target) = split_at_checked(after_equals, value_whitespace_len)?; + let (quote, target, suffix) = split_refresh_target(raw_target); + let Some(rewritten) = gateway_prefix.rewrite_url_value(base_url, target)? else { + return Ok(value.to_string()); + }; + + let mut output = String::with_capacity(value.len() + rewritten.len()); + output.push_str(before_url); + output.push_str(url_token); + output.push_str(whitespace); + output.push('='); + output.push_str(value_whitespace); + if let Some(quote) = quote { + output.push(quote); + output.push_str(rewritten.as_str()); + output.push(quote); + } else { + output.push_str(rewritten.as_str()); + } + output.push_str(suffix); + Ok(output) +} + +fn find_refresh_url_key(value: &str) -> Option { + let mut rest = value; + let mut offset = 0_usize; + while let Some(index) = find_ascii_case_insensitive(rest, "url") { + let absolute_index = offset.checked_add(index)?; + let after_url = rest.get(index.checked_add("url".len())?..)?; + let whitespace_len = after_url + .bytes() + .take_while(u8::is_ascii_whitespace) + .count(); + if after_url + .get(whitespace_len..) + .is_some_and(|tail| tail.starts_with('=')) + { + return Some(absolute_index); + } + let advance = index.checked_add("url".len())?; + rest = rest.get(advance..)?; + offset = offset.checked_add(advance)?; + } + None +} + +fn split_refresh_target(raw_target: &str) -> (Option, &str, &str) { + if let Some(quote) = raw_target + .chars() + .next() + .filter(|ch| matches!(ch, '"' | '\'')) + { + if let Some(after_quote) = raw_target.strip_prefix(quote) { + if let Some((target, suffix)) = after_quote.split_once(quote) { + return (Some(quote), target, suffix); + } + return (Some(quote), after_quote, ""); + } + } + + let target = raw_target.trim_end(); + let suffix = raw_target.get(target.len()..).unwrap_or_default(); + (None, target, suffix) +} + +fn decode_srcdoc_attribute_value(value: &str) -> String { + value + .replace(""", "\"") + .replace(""", "\"") + .replace(""", "\"") + .replace(""", "\"") + .replace("'", "'") + .replace("'", "'") + .replace("'", "'") + .replace("'", "'") + .replace("<", "<") + .replace(">", ">") + .replace("&", "&") +} + +fn find_ascii_case_insensitive(input: &str, pattern: &str) -> Option { + input + .to_ascii_lowercase() + .find(pattern.to_ascii_lowercase().as_str()) +} + +fn split_at_checked(input: &str, index: usize) -> Result<(&str, &str)> { + let Some(before) = input.get(..index) else { + return Err(WebviewError::Render(format!( + "invalid UTF-8 split boundary {index}" + ))); + }; + let Some(after) = input.get(index..) else { + return Err(WebviewError::Render(format!( + "invalid UTF-8 split boundary {index}" + ))); + }; + Ok((before, after)) +} + +fn bootstrap_tag(script: &str) -> String { + format!("") +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::url::GatewayPrefix; + use crate::url::TargetUrl; + + fn context() -> Result { + Ok(RewriteContext::new( + GatewayPrefix::new("/webview/")?, + TargetUrl::parse("https://example.com/app/page.html")?.into_url(), + )) + } + + #[test] + fn html_rewrites_relative_subresources_and_srcset() -> Result<()> { + let ctx = context()?; + let html = r#"
"#; + + let rewritten = ctx.rewrite_html(html)?; + + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Fnext%2Ehtml")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fimg%2Epng")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fsubmit")); + assert!(rewritten.contains("1x")); + assert!(rewritten.contains("2x")); + Ok(()) + } + + #[test] + fn css_rewrites_urls_and_imports() -> Result<()> { + let ctx = context()?; + let css = r#"@import "theme/base.css"; body { background: url('/assets/bg.png'); }"#; + + let rewritten = ctx.rewrite_css(css)?; + + assert!( + rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Ftheme%2Fbase%2Ecss") + ); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fassets%2Fbg%2Epng")); + Ok(()) + } + + #[test] + fn bootstrap_injects_before_page_scripts() -> Result<()> { + let ctx = context()?.with_bootstrap_script("globalThis.__ringsWebview = true;"); + + let rewritten = ctx.rewrite_html("")?; + + assert!(rewritten.contains("data-rings-webview-bootstrap")); + assert!(rewritten.contains("__ringsWebview")); + Ok(()) + } + + #[test] + fn html_rewrites_case_whitespace_unquoted_and_inline_style_urls() -> Result<()> { + let ctx = context()?; + let html = r#"
"#; + + let rewritten = ctx.rewrite_html(html)?; + + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Fnext%2Ehtml")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fimg%2Epng")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fsubmit")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Fbg%2Epng")); + Ok(()) + } + + #[test] + fn html_rewrites_style_element_urls() -> Result<()> { + let ctx = context()?; + let html = r#""#; + + let rewritten = ctx.rewrite_html(html)?; + + assert!( + rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Ftheme%2Fbase%2Ecss") + ); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fassets%2Fbg%2Epng")); + assert_absent(&rewritten, "@import \"theme/base.css\""); + assert_absent(&rewritten, "url(\"/assets/bg.png\")"); + Ok(()) + } + + #[test] + fn html_rewrites_anchor_ping_url_lists() -> Result<()> { + let ctx = context()?; + let html = + r#"next"#; + + let rewritten = ctx.rewrite_html(html)?; + + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Fping%2Fone")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fmetrics%2Eexample%2Fping%2Ftwo")); + assert_absent(&rewritten, "ping/one https://metrics.example/ping/two"); + Ok(()) + } + + #[test] + fn html_rewrites_srcdoc_document_urls() -> Result<()> { + let ctx = context()?.with_bootstrap_script("globalThis.__ringsWebview = true;"); + let html = r#""#; + + let rewritten = ctx.rewrite_html(html)?; + + assert!( + rewritten.contains("/webview/https%3A%2F%2Fexample%2Etest%2Fx%2Epng"), + "{rewritten}" + ); + assert!( + rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Fnext%2Ehtml"), + "{rewritten}" + ); + assert!(rewritten.contains("data-rings-webview-bootstrap")); + assert_absent(&rewritten, "https://example.test/x.png"); + assert_absent(&rewritten, "href=\"next.html\""); + Ok(()) + } + + #[test] + fn html_rewrites_meta_refresh_urls() -> Result<()> { + let ctx = context()?; + let html = r#""#; + + let rewritten = ctx.rewrite_html(html)?; + + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Flogin%3Fnext%3D1")); + assert_absent(&rewritten, "../login?next=1"); + Ok(()) + } + + #[test] + fn html_base_href_controls_following_relative_rewrites() -> Result<()> { + let ctx = context()?; + let html = r#""#; + + let rewritten = ctx.rewrite_html(html)?; + + for expected in [ + "https://example.com/assets/", + "https://example.com/assets/site.css", + "https://example.com/assets/hero.png", + "https://example.com/assets/photo.png", + "https://example.com/assets/app.js", + ] { + assert!(rewritten.contains( + GatewayPrefix::new("/webview/")? + .encode(&Url::parse(expected)?) + .as_str() + )); + } + assert_absent(&rewritten, "href=\"site.css\""); + assert_absent(&rewritten, "url(hero.png)"); + assert_absent(&rewritten, "src=\"photo.png\""); + Ok(()) + } + + #[test] + fn css_rewrites_case_whitespace_and_import_url_forms() -> Result<()> { + let ctx = context()?; + let css = r#"@IMPORT "theme/base.css"; @import url(extra.css); body { background: URL("/assets/bg.png"); }"#; + + let rewritten = ctx.rewrite_css(css)?; + + assert!( + rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Ftheme%2Fbase%2Ecss") + ); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fapp%2Fextra%2Ecss")); + assert!(rewritten.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fassets%2Fbg%2Epng")); + Ok(()) + } + + fn assert_absent(haystack: &str, needle: &str) { + assert!( + !haystack.contains(needle), + "unexpected substring {needle:?} in {haystack:?}" + ); + } +} diff --git a/crates/webview/src/route.rs b/crates/webview/src/route.rs new file mode 100644 index 000000000..54ba41b37 --- /dev/null +++ b/crates/webview/src/route.rs @@ -0,0 +1,346 @@ +//! Trusted host routing policy for a controlled webview origin. + +use url::Url; + +use crate::error::Result; +use crate::error::WebviewError; +use crate::types::GatewayRequestKind; +use crate::url::GatewayPrefix; +use crate::url::TargetUrl; + +/// A request-routing policy implemented by the WebView host, service worker, or equivalent. +/// +/// The host supplies `source_target` from its frame state, never from an untrusted page header. +/// Runtime requests retain that target so the transport layer can apply virtual CORS after the +/// request is forwarded through the controlled gateway origin. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct GatewayRoutePolicy { + controlled_origin: Url, + gateway_prefix: GatewayPrefix, +} + +impl GatewayRoutePolicy { + /// Build a policy for one Rings-controlled browser origin and gateway path prefix. + pub fn new(controlled_origin: Url, gateway_prefix: GatewayPrefix) -> Result { + if !is_controlled_origin(&controlled_origin) { + return Err(WebviewError::InvalidControlledOrigin( + controlled_origin.to_string(), + )); + } + Ok(Self { + controlled_origin, + gateway_prefix, + }) + } + + /// Return the controlled browser origin used to host gateway routes. + pub fn controlled_origin(&self) -> &Url { + &self.controlled_origin + } + + /// Return the gateway route prefix handled by this policy. + pub fn gateway_prefix(&self) -> &GatewayPrefix { + &self.gateway_prefix + } + + /// Build the controlled-origin URL that represents `target`. + pub fn gateway_url(&self, target: &Url) -> Result { + self.controlled_origin + .join(self.gateway_prefix.encode(target).as_str()) + .map_err(WebviewError::Url) + } + + /// Decide how a host must handle one browser request before the browser opens a connection. + /// + /// `source_target` is the target URL associated with the initiating frame. It is required for + /// fetch and XHR virtual CORS enforcement, but navigation and static subresources may cross + /// target origins. The host must treat an error as a rejection and never fall back to + /// `requested_url`. + pub fn route( + &self, + requested_url: &Url, + source_target: Option<&TargetUrl>, + kind: GatewayRequestKind, + ) -> Result { + if runtime_request_lacks_source_target(source_target, kind) { + return Ok(GatewayRoute::Reject( + GatewayRouteRejection::MissingRuntimeSourceTarget, + )); + } + if self.is_controlled_url(requested_url) && !self.is_gateway_url(requested_url) { + return Ok(GatewayRoute::AllowControlled); + } + let target = self.target_from_requested_url(requested_url, kind)?; + self.route_target(requested_url, target) + } + + fn target_from_requested_url( + &self, + requested_url: &Url, + kind: GatewayRequestKind, + ) -> Result { + if self.is_controlled_url(requested_url) { + let target = self.gateway_prefix.decode_path(requested_url.path())?; + let Some(form_query) = requested_url.query() else { + return Ok(target); + }; + if kind != GatewayRequestKind::Navigation { + return Err(WebviewError::InvalidGatewayUrl(requested_url.to_string())); + } + + // Native GET form submissions append fields to the gateway URL rather than to its + // percent-encoded target. Only a document navigation can use that representation. + let mut target_url = target.into_url(); + let target_query = target_url + .query() + .map(|query| format!("{query}&{form_query}")) + .unwrap_or_else(|| form_query.to_string()); + target_url.set_query(Some(&target_query)); + return TargetUrl::parse(target_url.as_str()); + } + TargetUrl::parse(requested_url.as_str()) + } + + fn route_target(&self, requested_url: &Url, target: TargetUrl) -> Result { + if self.is_controlled_url(requested_url) { + return Ok(GatewayRoute::Serve(target)); + } + Ok(GatewayRoute::Redirect(self.gateway_url(target.as_url())?)) + } + + fn is_controlled_url(&self, url: &Url) -> bool { + url.origin() == self.controlled_origin.origin() + } + + fn is_gateway_url(&self, url: &Url) -> bool { + url.path().starts_with(self.gateway_prefix.as_str()) + } +} + +/// A complete host action for one browser request. +#[derive(Clone, Debug, Eq, PartialEq)] +pub enum GatewayRoute { + /// Allow a Rings-owned shell or static asset to load without forwarding it upstream. + AllowControlled, + /// Serve a decoded target through the `GatewayTransport` boundary. + Serve(TargetUrl), + /// Redirect an external navigation or subresource to this controlled gateway URL. + Redirect(Url), + /// Reject the request before the browser can open a remote connection. + Reject(GatewayRouteRejection), +} + +/// The named reason a host must reject a browser request. +#[derive(Clone, Debug, Eq, PartialEq)] +pub enum GatewayRouteRejection { + /// The host did not provide a trusted initiating-frame target for fetch or XHR. + MissingRuntimeSourceTarget, +} + +fn is_controlled_origin(url: &Url) -> bool { + matches!(url.scheme(), "http" | "https") + && url.host_str().is_some() + && url.username().is_empty() + && url.password().is_none() + && url.path() == "/" + && url.query().is_none() + && url.fragment().is_none() +} + +fn runtime_request_lacks_source_target( + source_target: Option<&TargetUrl>, + kind: GatewayRequestKind, +) -> bool { + matches!(kind, GatewayRequestKind::Fetch | GatewayRequestKind::Xhr) && source_target.is_none() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn policy() -> Result { + GatewayRoutePolicy::new( + Url::parse("https://webview.rings.test/")?, + GatewayPrefix::new("/webview/")?, + ) + } + + #[test] + fn external_navigation_redirects_to_controlled_gateway_url() -> Result<()> { + let policy = policy()?; + let requested = Url::parse("https://example.test/docs/index.html")?; + + let route = policy.route(&requested, None, GatewayRequestKind::Navigation)?; + + assert_eq!( + route, + GatewayRoute::Redirect(Url::parse( + "https://webview.rings.test/webview/https%3A%2F%2Fexample%2Etest%2Fdocs%2Findex%2Ehtml" + )?) + ); + Ok(()) + } + + #[test] + fn controlled_gateway_url_decodes_to_target_transport_route() -> Result<()> { + let policy = policy()?; + let target = Url::parse("https://example.test/docs/index.html")?; + let requested = policy.gateway_url(&target)?; + + let route = policy.route(&requested, None, GatewayRequestKind::Navigation)?; + + assert_eq!( + route, + GatewayRoute::Serve(TargetUrl::parse(target.as_str())?) + ); + Ok(()) + } + + #[test] + fn navigation_form_query_is_merged_into_gateway_target() -> Result<()> { + let policy = policy()?; + let target = Url::parse("https://www.google.com/search?source=hp")?; + let mut requested = policy.gateway_url(&target)?; + requested.set_query(Some("q=test+query&hl=en")); + + let route = policy.route(&requested, None, GatewayRequestKind::Navigation)?; + + assert_eq!( + route, + GatewayRoute::Serve(TargetUrl::parse( + "https://www.google.com/search?source=hp&q=test+query&hl=en" + )?) + ); + Ok(()) + } + + #[test] + fn gateway_outer_query_is_rejected_for_non_navigation_requests() -> Result<()> { + let policy = policy()?; + let target = Url::parse("https://example.test/asset.css")?; + let mut requested = policy.gateway_url(&target)?; + requested.set_query(Some("cache_bust=1")); + + assert!(matches!( + policy.route(&requested, None, GatewayRequestKind::Subresource), + Err(WebviewError::InvalidGatewayUrl(_)) + )); + Ok(()) + } + + #[test] + fn cross_target_fetch_is_served_for_virtual_cors_evaluation() -> Result<()> { + let policy = policy()?; + let source = TargetUrl::parse("https://app.example.test/index.html")?; + let target = Url::parse("https://bank.example.test/account")?; + let requested = policy.gateway_url(&target)?; + + let route = policy.route(&requested, Some(&source), GatewayRequestKind::Fetch)?; + + assert_eq!( + route, + GatewayRoute::Serve(TargetUrl::parse(target.as_str())?) + ); + Ok(()) + } + + #[test] + fn cross_target_direct_fetch_is_redirected_through_the_gateway() -> Result<()> { + let policy = policy()?; + let source = TargetUrl::parse("https://app.example.test/index.html")?; + let requested = Url::parse("https://bank.example.test/account")?; + + let route = policy.route(&requested, Some(&source), GatewayRequestKind::Fetch)?; + + assert_eq!( + route, + GatewayRoute::Redirect(policy.gateway_url(&requested)?) + ); + Ok(()) + } + + #[test] + fn same_target_xhr_is_served_through_gateway() -> Result<()> { + let policy = policy()?; + let source = TargetUrl::parse("https://app.example.test/docs/index.html")?; + let target = Url::parse("https://app.example.test/api/data")?; + let requested = policy.gateway_url(&target)?; + + let route = policy.route(&requested, Some(&source), GatewayRequestKind::Xhr)?; + + assert_eq!( + route, + GatewayRoute::Serve(TargetUrl::parse(target.as_str())?) + ); + Ok(()) + } + + #[test] + fn runtime_requests_without_a_trusted_source_target_are_rejected() -> Result<()> { + let policy = policy()?; + let requested = Url::parse("https://app.example.test/api/data")?; + + let route = policy.route(&requested, None, GatewayRequestKind::Fetch)?; + + assert_eq!( + route, + GatewayRoute::Reject(GatewayRouteRejection::MissingRuntimeSourceTarget) + ); + Ok(()) + } + + #[test] + fn cross_target_subresources_redirect_without_granting_script_read_access() -> Result<()> { + let policy = policy()?; + let source = TargetUrl::parse("https://app.example.test/index.html")?; + let requested = Url::parse("https://cdn.example.test/site.css")?; + + let route = policy.route(&requested, Some(&source), GatewayRequestKind::Subresource)?; + + assert_eq!( + route, + GatewayRoute::Redirect(policy.gateway_url(&requested)?) + ); + Ok(()) + } + + #[test] + fn controlled_origin_configuration_excludes_paths_and_credentials() -> Result<()> { + for value in [ + "https://webview.rings.test/app", + "https://user@webview.rings.test/", + "file:///tmp/webview", + ] { + assert!(matches!( + GatewayRoutePolicy::new(Url::parse(value)?, GatewayPrefix::new("/webview/")?), + Err(WebviewError::InvalidControlledOrigin(_)) + )); + } + Ok(()) + } + + #[test] + fn controlled_shell_assets_remain_local() -> Result<()> { + let policy = policy()?; + let requested = Url::parse("https://webview.rings.test/assets/app.js")?; + + let route = policy.route(&requested, None, GatewayRequestKind::Subresource)?; + + assert_eq!(route, GatewayRoute::AllowControlled); + Ok(()) + } + + #[test] + fn runtime_requests_to_controlled_assets_still_require_a_trusted_source() -> Result<()> { + let policy = policy()?; + let requested = Url::parse("https://webview.rings.test/assets/app.js")?; + + let route = policy.route(&requested, None, GatewayRequestKind::Xhr)?; + + assert_eq!( + route, + GatewayRoute::Reject(GatewayRouteRejection::MissingRuntimeSourceTarget) + ); + Ok(()) + } +} diff --git a/crates/webview/src/transport.rs b/crates/webview/src/transport.rs new file mode 100644 index 000000000..fe7053b95 --- /dev/null +++ b/crates/webview/src/transport.rs @@ -0,0 +1,678 @@ +use std::sync::Mutex; + +use async_trait::async_trait; + +use crate::cookie::CookieJar; +use crate::cors; +use crate::error::Result; +use crate::header::HeaderPolicy; +use crate::rewrite::RewriteContext; +use crate::types::GatewayHeader; +use crate::types::GatewayRequest; +use crate::types::GatewayRequestKind; +use crate::types::GatewayResponse; +use crate::url::GatewayPrefix; + +/// Pluggable transport for normalized webview gateway requests. +#[async_trait(?Send)] +pub trait GatewayTransport { + /// Send `request` through the concrete transport and return a raw response. + async fn send(&self, request: GatewayRequest) -> Result; +} + +/// Policy wrapper that applies cookies, header policy, and body rewriting around a transport. +pub struct WebviewGateway { + policy: GatewayResponsePolicy, + transport: T, + cookies: CookieJar, +} + +/// A gateway that permits concurrent transport requests while sharing one virtual cookie jar. +/// +/// The cookie jar is locked only while a request is prepared and while upstream `Set-Cookie` +/// headers are committed. Network I/O and response rewriting run outside that lock, so one slow +/// upstream request cannot block unrelated page resources. +pub struct ConcurrentWebviewGateway { + policy: GatewayResponsePolicy, + transport: T, + cookies: Mutex, +} + +struct GatewayResponsePolicy { + prefix: GatewayPrefix, + header_policy: HeaderPolicy, + bootstrap_script: Option, +} + +enum BootstrapScript { + Static(String), + PerTarget(fn(&url::Url) -> String), +} + +impl GatewayResponsePolicy { + fn new(prefix: GatewayPrefix) -> Self { + Self { + header_policy: HeaderPolicy::new(prefix.clone()), + prefix, + bootstrap_script: None, + } + } + + fn prepare_request( + &self, + cookies: &CookieJar, + request: GatewayRequest, + ) -> Result { + let mut request = self.header_policy.normalize_request(request); + if request.allows_target_cookies() { + if let Some(cookie_header) = cookies.cookie_header(&request.target) { + request + .headers + .push(GatewayHeader::new("Cookie", cookie_header)?); + } + } + Ok(request) + } + + fn store_response_cookies( + &self, + cookies: &mut CookieJar, + target: &url::Url, + response: &GatewayResponse, + ) -> Result<()> { + for header in response + .headers + .iter() + .filter(|header| header.name_eq("set-cookie")) + { + cookies.store_set_cookie(target, header.value.as_str())?; + } + Ok(()) + } + + fn finish_response( + &self, + target: &url::Url, + response: GatewayResponse, + ) -> Result { + let mut response = self.header_policy.normalize_response(target, response)?; + response.body = self.rewrite_body(target, &response)?; + Ok(response) + } + + fn rewrite_body(&self, target: &url::Url, response: &GatewayResponse) -> Result> { + let Some(content_type) = response + .headers + .iter() + .find(|header| header.name_eq("content-type")) + .map(|header| header.value.to_ascii_lowercase()) + else { + return Ok(response.body.clone()); + }; + if !(content_type.contains("text/html") || content_type.contains("text/css")) { + return Ok(response.body.clone()); + } + let Ok(text) = std::str::from_utf8(response.body.as_slice()) else { + return Ok(response.body.clone()); + }; + let mut ctx = RewriteContext::new(self.prefix.clone(), target.clone()); + if let Some(script) = self.bootstrap_for(target) { + ctx = ctx.with_bootstrap_script(script); + } + let rewritten = if content_type.contains("text/html") { + ctx.rewrite_html(text)? + } else { + ctx.rewrite_css(text)? + }; + Ok(rewritten.into_bytes()) + } + + fn bootstrap_for(&self, target: &url::Url) -> Option { + match &self.bootstrap_script { + Some(BootstrapScript::Static(script)) => Some(script.clone()), + Some(BootstrapScript::PerTarget(build)) => Some(build(target)), + None => None, + } + } +} + +impl WebviewGateway +where + T: GatewayTransport, +{ + /// Build a webview gateway around `transport`. + pub fn new(prefix: GatewayPrefix, transport: T) -> Self { + Self { + policy: GatewayResponsePolicy::new(prefix), + transport, + cookies: CookieJar::new(), + } + } + + /// Return the controlled-origin gateway prefix. + pub fn prefix(&self) -> &GatewayPrefix { + &self.policy.prefix + } + + /// Attach a runtime bootstrap script that is injected into rendered HTML. + pub fn with_bootstrap_script(mut self, script: impl Into) -> Self { + self.policy.bootstrap_script = Some(BootstrapScript::Static(script.into())); + self + } + + /// Attach a runtime bootstrap factory evaluated for each rendered target page. + /// + /// Use this when the bootstrap resolves relative runtime URLs against the target document. + /// The factory is evaluated after the upstream response is received and before its HTML is + /// rewritten, so navigating between targets cannot retain an earlier page's base URL. + pub fn with_target_bootstrap(mut self, script: fn(&url::Url) -> String) -> Self { + self.policy.bootstrap_script = Some(BootstrapScript::PerTarget(script)); + self + } + + /// Access the virtual cookie jar. + pub fn cookies(&self) -> &CookieJar { + &self.cookies + } + + /// Send one request through the gateway policy stack. + pub async fn send(&mut self, request: GatewayRequest) -> Result { + let cors_request = request.clone(); + let preflight = cors::preflight_request(&request)?; + let request = self.policy.prepare_request(&self.cookies, request)?; + if let Some(preflight) = preflight { + let preflight = self.policy.header_policy.normalize_request(preflight); + let response = self.transport.send(preflight).await?; + cors::validate_preflight_response(&cors_request, &response)?; + } + let target = request.target.clone(); + let stores_cookies = request.allows_target_cookies(); + let response = self.transport.send(request).await?; + cors::validate_response(&cors_request, &response)?; + if stores_cookies { + self.policy + .store_response_cookies(&mut self.cookies, &target, &response)?; + } + self.policy.finish_response(&target, response) + } + + /// Build a typed request from a controlled-origin gateway path. + pub fn request_from_gateway_path( + &self, + path: &str, + kind: GatewayRequestKind, + ) -> Result { + let target = self.policy.prefix.decode_path(path)?.into_url(); + Ok(match kind { + GatewayRequestKind::Navigation => GatewayRequest::navigation(target), + GatewayRequestKind::Subresource => GatewayRequest::subresource(target), + GatewayRequestKind::Fetch => GatewayRequest::fetch(target, "GET"), + GatewayRequestKind::Xhr => GatewayRequest::xhr(target, "GET"), + }) + } + + /// Send one request addressed by a controlled-origin gateway path. + pub async fn send_gateway_path( + &mut self, + path: &str, + kind: GatewayRequestKind, + ) -> Result { + let request = self.request_from_gateway_path(path, kind)?; + self.send(request).await + } +} + +impl ConcurrentWebviewGateway +where + T: GatewayTransport, +{ + /// Build a concurrent webview gateway around `transport`. + pub fn new(prefix: GatewayPrefix, transport: T) -> Self { + Self { + policy: GatewayResponsePolicy::new(prefix), + transport, + cookies: Mutex::new(CookieJar::new()), + } + } + + /// Return the controlled-origin gateway prefix. + pub fn prefix(&self) -> &GatewayPrefix { + &self.policy.prefix + } + + /// Attach a runtime bootstrap script that is injected into rendered HTML. + pub fn with_bootstrap_script(mut self, script: impl Into) -> Self { + self.policy.bootstrap_script = Some(BootstrapScript::Static(script.into())); + self + } + + /// Attach a runtime bootstrap factory evaluated for each rendered target page. + pub fn with_target_bootstrap(mut self, script: fn(&url::Url) -> String) -> Self { + self.policy.bootstrap_script = Some(BootstrapScript::PerTarget(script)); + self + } + + /// Send one request without holding the virtual-cookie lock during upstream I/O. + pub async fn send(&self, request: GatewayRequest) -> Result { + let cors_request = request.clone(); + let preflight = cors::preflight_request(&request)?; + let request = { + let cookies = self.lock_cookies()?; + self.policy.prepare_request(&cookies, request)? + }; + if let Some(preflight) = preflight { + let preflight = self.policy.header_policy.normalize_request(preflight); + let response = self.transport.send(preflight).await?; + cors::validate_preflight_response(&cors_request, &response)?; + } + let target = request.target.clone(); + let stores_cookies = request.allows_target_cookies(); + let response = self.transport.send(request).await?; + cors::validate_response(&cors_request, &response)?; + if stores_cookies { + let mut cookies = self.lock_cookies()?; + self.policy + .store_response_cookies(&mut cookies, &target, &response)?; + } + self.policy.finish_response(&target, response) + } + + /// Build a typed request from a controlled-origin gateway path. + pub fn request_from_gateway_path( + &self, + path: &str, + kind: GatewayRequestKind, + ) -> Result { + let target = self.policy.prefix.decode_path(path)?.into_url(); + Ok(match kind { + GatewayRequestKind::Navigation => GatewayRequest::navigation(target), + GatewayRequestKind::Subresource => GatewayRequest::subresource(target), + GatewayRequestKind::Fetch => GatewayRequest::fetch(target, "GET"), + GatewayRequestKind::Xhr => GatewayRequest::xhr(target, "GET"), + }) + } + + /// Send one request addressed by a controlled-origin gateway path. + pub async fn send_gateway_path( + &self, + path: &str, + kind: GatewayRequestKind, + ) -> Result { + let request = self.request_from_gateway_path(path, kind)?; + self.send(request).await + } + + fn lock_cookies(&self) -> Result> { + self.cookies.lock().map_err(|_| { + crate::error::WebviewError::Cookie("virtual cookie jar lock is poisoned".to_string()) + }) + } +} + +#[cfg(test)] +mod tests { + use std::cell::RefCell; + use std::rc::Rc; + + use futures::channel::mpsc; + use futures::channel::oneshot; + use futures::executor::LocalPool; + use futures::stream::StreamExt; + use futures::task::LocalSpawnExt; + + use super::*; + use crate::types::GatewayCredentials; + use crate::types::GatewayRequest; + use crate::types::GatewayRequestKind; + use crate::url::TargetUrl; + use crate::WebviewError; + + struct StaticTransport; + + #[async_trait(?Send)] + impl GatewayTransport for StaticTransport { + async fn send(&self, request: GatewayRequest) -> Result { + assert!(request + .headers + .iter() + .all(|header| !header.name_eq("cookie"))); + GatewayResponse::new( + 200, + vec![ + GatewayHeader::new("Content-Type", "text/html")?, + GatewayHeader::new("Set-Cookie", "sid=one; Path=/")?, + ], + br#""#.to_vec(), + ) + } + } + + #[test] + fn gateway_rewrites_html_and_stores_cookies() -> Result<()> { + let target = TargetUrl::parse("https://example.com/index.html")?.into_url(); + let mut gateway = WebviewGateway::new(GatewayPrefix::new("/webview/")?, StaticTransport) + .with_bootstrap_script("globalThis.__rings = true;"); + let request = GatewayRequest { + target, + method: "GET".to_string(), + headers: Vec::new(), + body: Vec::new(), + kind: GatewayRequestKind::Navigation, + source_origin: None, + credentials: GatewayCredentials::SameOrigin, + }; + + let response = futures::executor::block_on(gateway.send(request))?; + let body = String::from_utf8(response.body) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + + assert!(body.contains("/webview/https%3A%2F%2Fexample%2Ecom%2Fasset%2Epng")); + assert!(body.contains("data-rings-webview-bootstrap")); + assert_eq!(gateway.cookies().len(), 1); + assert!(!response + .headers + .iter() + .any(|header| header.name_eq("set-cookie"))); + Ok(()) + } + + fn target_bootstrap(target: &url::Url) -> String { + format!("globalThis.__ringsTarget = {:?};", target.as_str()) + } + + #[test] + fn per_target_bootstrap_tracks_each_navigated_document() -> Result<()> { + let mut gateway = WebviewGateway::new(GatewayPrefix::new("/webview/")?, StaticTransport) + .with_target_bootstrap(target_bootstrap); + let first = TargetUrl::parse("https://one.example.test/first")?.into_url(); + let second = TargetUrl::parse("https://two.example.test/second")?.into_url(); + + let first = futures::executor::block_on(gateway.send(GatewayRequest::navigation(first)))?; + let second = futures::executor::block_on(gateway.send(GatewayRequest::navigation(second)))?; + let first_body = String::from_utf8(first.body) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let second_body = String::from_utf8(second.body) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + + assert!(first_body.contains("https://one.example.test/first")); + assert!(!first_body.contains("https://two.example.test/second")); + assert!(second_body.contains("https://two.example.test/second")); + assert!(!second_body.contains("https://one.example.test/first")); + Ok(()) + } + + struct DomainCookieTransport; + + #[async_trait(?Send)] + impl GatewayTransport for DomainCookieTransport { + async fn send(&self, _request: GatewayRequest) -> Result { + GatewayResponse::new( + 200, + vec![ + GatewayHeader::new("Content-Type", "text/html")?, + GatewayHeader::new("Set-Cookie", "sid=domain; Domain=example.com; Path=/")?, + ], + br#"

ok

"#.to_vec(), + ) + } + } + + #[test] + fn gateway_ignores_domain_cookie_without_failing_response() -> Result<()> { + let target = TargetUrl::parse("https://example.com/index.html")?.into_url(); + let mut gateway = + WebviewGateway::new(GatewayPrefix::new("/webview/")?, DomainCookieTransport); + + let response = + futures::executor::block_on(gateway.send(GatewayRequest::navigation(target)))?; + let body = String::from_utf8(response.body) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + + assert!(body.contains("

ok

")); + assert!(gateway.cookies().is_empty()); + assert!(!response + .headers + .iter() + .any(|header| header.name_eq("set-cookie"))); + Ok(()) + } + + struct RecordingTransport { + requests: std::cell::RefCell>, + } + + impl RecordingTransport { + fn new() -> Self { + Self { + requests: std::cell::RefCell::new(Vec::new()), + } + } + } + + #[async_trait(?Send)] + impl GatewayTransport for RecordingTransport { + async fn send(&self, request: GatewayRequest) -> Result { + self.requests.borrow_mut().push(request); + GatewayResponse::new( + 200, + vec![ + GatewayHeader::new("Content-Type", "application/json")?, + GatewayHeader::new("Set-Cookie", "sid=one; Path=/")?, + ], + br#"{}"#.to_vec(), + ) + } + } + + #[test] + fn gateway_replaces_caller_cookie_header_with_virtual_target_cookie() -> Result<()> { + let transport = RecordingTransport::new(); + let target = TargetUrl::parse("https://example.com/index.html")?.into_url(); + let fetch_target = TargetUrl::parse("https://example.com/api")?.into_url(); + let mut gateway = WebviewGateway::new(GatewayPrefix::new("/webview/")?, transport); + + futures::executor::block_on(gateway.send(GatewayRequest::navigation(target)))?; + futures::executor::block_on( + gateway.send( + GatewayRequest::fetch(fetch_target, "GET") + .with_header(GatewayHeader::new("Cookie", "caller=leak")?), + ), + )?; + + let requests = gateway.transport.requests.borrow(); + let second = requests + .get(1) + .ok_or_else(|| WebviewError::Transport("missing second request".to_string()))?; + let cookies: Vec<&str> = second + .headers + .iter() + .filter(|header| header.name_eq("cookie")) + .map(|header| header.value.as_str()) + .collect(); + + assert_eq!(cookies, vec!["sid=one"]); + Ok(()) + } + + #[test] + fn gateway_strips_controlled_origin_headers_before_transport() -> Result<()> { + let transport = RecordingTransport::new(); + let target = TargetUrl::parse("https://example.com/index.html")?.into_url(); + let mut gateway = WebviewGateway::new(GatewayPrefix::new("/webview/")?, transport); + + futures::executor::block_on( + gateway.send( + GatewayRequest::navigation(target) + .with_header(GatewayHeader::new("Host", "127.0.0.1:3000")?) + .with_header(GatewayHeader::new("Origin", "http://127.0.0.1:3000")?) + .with_header(GatewayHeader::new( + "Referer", + "http://127.0.0.1:3000/webview/target", + )?) + .with_header(GatewayHeader::new("Sec-Fetch-Dest", "document")?) + .with_header(GatewayHeader::new("Accept", "text/html")?), + ), + )?; + + let requests = gateway.transport.requests.borrow(); + let first = requests + .first() + .ok_or_else(|| WebviewError::Transport("missing first request".to_string()))?; + assert!(first.headers.iter().all(|header| { + !header.name_eq("host") + && !header.name_eq("origin") + && !header.name_eq("referer") + && !header.name_eq("sec-fetch-dest") + })); + assert!(first + .headers + .iter() + .any(|header| header.name_eq("accept") && header.value == "text/html")); + Ok(()) + } + + struct CorsRecordingTransport { + requests: std::cell::RefCell>, + } + + #[async_trait(?Send)] + impl GatewayTransport for CorsRecordingTransport { + async fn send(&self, request: GatewayRequest) -> Result { + let is_preflight = request.method == "OPTIONS"; + self.requests.borrow_mut().push(request); + let mut headers = vec![GatewayHeader::new( + "Access-Control-Allow-Origin", + "https://app.example.test", + )?]; + if is_preflight { + headers.push(GatewayHeader::new("Access-Control-Allow-Methods", "PATCH")?); + headers.push(GatewayHeader::new( + "Access-Control-Allow-Headers", + "x-requested-with", + )?); + } + GatewayResponse::new(200, headers, b"cors response".to_vec()) + } + } + + #[test] + fn gateway_forwards_cross_origin_runtime_requests_after_virtual_cors_preflight() -> Result<()> { + let target = TargetUrl::parse("https://api.example.test/data")?.into_url(); + let source = TargetUrl::parse("https://app.example.test/page")?.into_url(); + let transport = CorsRecordingTransport { + requests: std::cell::RefCell::new(Vec::new()), + }; + let mut gateway = WebviewGateway::new(GatewayPrefix::new("/webview/")?, transport); + let response = futures::executor::block_on( + gateway.send( + GatewayRequest::fetch(target, "PATCH") + .with_source_origin(source) + .with_header(GatewayHeader::new("X-Requested-With", "Rings")?), + ), + )?; + + assert_eq!(response.body, b"cors response"); + let requests = gateway.transport.requests.borrow(); + assert_eq!(requests.len(), 2); + let preflight = requests + .first() + .ok_or_else(|| WebviewError::Transport("missing CORS preflight".to_string()))?; + assert_eq!(preflight.method, "OPTIONS"); + assert!(preflight.headers.iter().any(|header| { + header.name_eq("origin") && header.value == "https://app.example.test" + })); + assert!(preflight.headers.iter().any(|header| { + header.name_eq("access-control-request-method") && header.value == "PATCH" + })); + let actual = requests + .get(1) + .ok_or_else(|| WebviewError::Transport("missing CORS runtime request".to_string()))?; + assert_eq!(actual.method, "PATCH"); + assert!(actual.headers.iter().any(|header| { + header.name_eq("origin") && header.value == "https://app.example.test" + })); + Ok(()) + } + + struct SlowFirstTransport { + started: mpsc::UnboundedSender, + release_slow_request: RefCell>>, + } + + #[async_trait(?Send)] + impl GatewayTransport for SlowFirstTransport { + async fn send(&self, request: GatewayRequest) -> Result { + let path = request.target.path().to_string(); + let _ = self.started.unbounded_send(path.clone()); + if path == "/slow" { + let receiver = self + .release_slow_request + .borrow_mut() + .take() + .ok_or_else(|| { + WebviewError::Transport("slow request was released twice".to_string()) + })?; + receiver.await.map_err(|_| { + WebviewError::Transport("slow request release channel was dropped".to_string()) + })?; + } + GatewayResponse::new( + 200, + vec![GatewayHeader::new("content-type", "text/plain")?], + path.into_bytes(), + ) + } + } + + #[test] + fn concurrent_gateway_allows_fast_resource_while_slow_resource_waits() -> Result<()> { + let (started_sender, mut started_receiver) = mpsc::unbounded(); + let (release_slow_sender, release_slow_receiver) = oneshot::channel(); + let gateway = Rc::new(ConcurrentWebviewGateway::new( + GatewayPrefix::new("/webview/")?, + SlowFirstTransport { + started: started_sender, + release_slow_request: RefCell::new(Some(release_slow_receiver)), + }, + )); + let slow = TargetUrl::parse("https://example.test/slow")?.into_url(); + let fast = TargetUrl::parse("https://example.test/fast")?.into_url(); + let (slow_result_sender, slow_result_receiver) = oneshot::channel(); + let (fast_result_sender, fast_result_receiver) = oneshot::channel(); + let mut pool = LocalPool::new(); + let spawner = pool.spawner(); + + let slow_gateway = Rc::clone(&gateway); + spawner + .spawn_local(async move { + let _ = slow_result_sender + .send(slow_gateway.send(GatewayRequest::navigation(slow)).await); + }) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + assert_eq!( + pool.run_until(started_receiver.next()), + Some("/slow".to_string()) + ); + + let fast_gateway = Rc::clone(&gateway); + spawner + .spawn_local(async move { + let _ = fast_result_sender + .send(fast_gateway.send(GatewayRequest::subresource(fast)).await); + }) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let fast_response = pool + .run_until(fast_result_receiver) + .map_err(|_| WebviewError::Transport("fast resource task was dropped".to_string()))??; + assert_eq!(fast_response.body, b"/fast"); + + release_slow_sender.send(()).map_err(|_| { + WebviewError::Transport("slow resource task stopped waiting unexpectedly".to_string()) + })?; + let slow_response = pool + .run_until(slow_result_receiver) + .map_err(|_| WebviewError::Transport("slow resource task was dropped".to_string()))??; + assert_eq!(slow_response.body, b"/slow"); + Ok(()) + } +} diff --git a/crates/webview/src/types.rs b/crates/webview/src/types.rs new file mode 100644 index 000000000..28ab4def9 --- /dev/null +++ b/crates/webview/src/types.rs @@ -0,0 +1,216 @@ +use serde::Deserialize; +use serde::Serialize; +use url::Url; + +use crate::error::Result; +use crate::error::WebviewError; + +/// One HTTP header passed through the gateway boundary. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub struct GatewayHeader { + /// Header name. + pub name: String, + /// Header value. + pub value: String, +} + +impl GatewayHeader { + /// Build a validated gateway header. + pub fn new(name: impl Into, value: impl Into) -> Result { + let name = name.into(); + if name.trim().is_empty() { + return Err(WebviewError::Header("header name is empty".to_string())); + } + if name.chars().any(|ch| ch.is_control()) { + return Err(WebviewError::Header(format!( + "header name {name:?} contains control characters" + ))); + } + let value = value.into(); + if value.chars().any(|ch| ch == '\r' || ch == '\n') { + return Err(WebviewError::Header(format!( + "header {name:?} value contains newline" + ))); + } + Ok(Self { name, value }) + } + + /// Return true when this header has `name`, ignoring ASCII case. + pub fn name_eq(&self, name: &str) -> bool { + self.name.eq_ignore_ascii_case(name) + } +} + +/// Browser request class that produced a gateway request. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub enum GatewayRequestKind { + /// Top-level document navigation. + Navigation, + /// Static page subresource such as image, stylesheet, or script. + Subresource, + /// Runtime `fetch` request. + Fetch, + /// Runtime `XMLHttpRequest`. + Xhr, +} + +/// Credential mode captured from a browser runtime request. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub enum GatewayCredentials { + /// Never attach or accept target cookies for this request. + Omit, + /// Attach target cookies only when the virtual source and target origins match. + SameOrigin, + /// Attach target cookies even for a permitted cross-origin request. + Include, +} + +/// Normalized request passed from the controlled origin to a gateway transport. +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +pub struct GatewayRequest { + /// Absolute target URL. + pub target: Url, + /// HTTP method. + pub method: String, + /// Request headers. + pub headers: Vec, + /// Request body bytes. + pub body: Vec, + /// Browser request class. + pub kind: GatewayRequestKind, + /// Trusted source document URL for runtime requests, when one exists. + /// + /// The gateway serializes only its origin upstream and uses it to apply virtual CORS and + /// credential rules. It must never be populated from an untrusted page header. + pub source_origin: Option, + /// Browser credential mode for this request. + pub credentials: GatewayCredentials, +} + +impl GatewayRequest { + /// Build a gateway request for `target`, `method`, and browser request `kind`. + pub fn new(target: Url, method: impl Into, kind: GatewayRequestKind) -> Self { + Self { + target, + method: method.into(), + headers: Vec::new(), + body: Vec::new(), + kind, + source_origin: None, + credentials: GatewayCredentials::SameOrigin, + } + } + + /// Build a GET navigation request for `target`. + pub fn navigation(target: Url) -> Self { + Self::new(target, "GET", GatewayRequestKind::Navigation) + } + + /// Build a GET subresource request for `target`. + pub fn subresource(target: Url) -> Self { + Self::new(target, "GET", GatewayRequestKind::Subresource) + } + + /// Build a runtime `fetch` request for `target`. + pub fn fetch(target: Url, method: impl Into) -> Self { + Self::new(target, method, GatewayRequestKind::Fetch) + } + + /// Build a runtime `XMLHttpRequest` request for `target`. + pub fn xhr(target: Url, method: impl Into) -> Self { + Self::new(target, method, GatewayRequestKind::Xhr) + } + + /// Attach a request header. + pub fn with_header(mut self, header: GatewayHeader) -> Self { + self.headers.push(header); + self + } + + /// Attach a request body. + pub fn with_body(mut self, body: impl Into>) -> Self { + self.body = body.into(); + self + } + + /// Attach the trusted virtual source document for a browser runtime request. + pub fn with_source_origin(mut self, source_origin: Url) -> Self { + self.source_origin = Some(source_origin); + self + } + + /// Set the credential mode captured from a browser runtime request. + pub fn with_credentials(mut self, credentials: GatewayCredentials) -> Self { + self.credentials = credentials; + self + } + + /// Return true when this runtime request crosses virtual target origins. + pub fn is_cross_origin_runtime_request(&self) -> bool { + matches!( + self.kind, + GatewayRequestKind::Fetch | GatewayRequestKind::Xhr + ) && self + .source_origin + .as_ref() + .is_some_and(|source| source.origin() != self.target.origin()) + } + + /// Return whether the gateway may attach or store target cookies for this request. + pub fn allows_target_cookies(&self) -> bool { + if !matches!( + self.kind, + GatewayRequestKind::Fetch | GatewayRequestKind::Xhr + ) { + return true; + } + match (self.source_origin.as_ref(), self.credentials) { + (_, GatewayCredentials::Omit) => false, + (_, GatewayCredentials::Include) => true, + (Some(source), GatewayCredentials::SameOrigin) => { + source.origin() == self.target.origin() + } + (None, GatewayCredentials::SameOrigin) => true, + } + } + + /// Return the path and query component used by HTTPS onion request adapters. + pub fn path_and_query(&self) -> String { + let mut out = self.target.path().to_string(); + if out.is_empty() { + out.push('/'); + } + if let Some(query) = self.target.query() { + out.push('?'); + out.push_str(query); + } + out + } +} + +/// Normalized response returned by a gateway transport. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub struct GatewayResponse { + /// HTTP status code. + pub status: u16, + /// Response headers after transport execution. + pub headers: Vec, + /// Response body bytes. + pub body: Vec, +} + +impl GatewayResponse { + /// Build a gateway response. + pub fn new(status: u16, headers: Vec, body: Vec) -> Result { + if !(100..=599).contains(&status) { + return Err(WebviewError::Header(format!( + "invalid response status {status}" + ))); + } + Ok(Self { + status, + headers, + body, + }) + } +} diff --git a/crates/webview/src/url.rs b/crates/webview/src/url.rs new file mode 100644 index 000000000..8a6d276d8 --- /dev/null +++ b/crates/webview/src/url.rs @@ -0,0 +1,156 @@ +use percent_encoding::percent_decode_str; +use percent_encoding::utf8_percent_encode; +use percent_encoding::NON_ALPHANUMERIC; +use serde::Deserialize; +use serde::Serialize; +use url::Url; + +use crate::error::Result; +use crate::error::WebviewError; + +/// Absolute target URL accepted by the gateway. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub struct TargetUrl { + inner: Url, +} + +impl TargetUrl { + /// Parse and validate an absolute HTTP(S) target URL. + pub fn parse(input: &str) -> Result { + let inner = Url::parse(input.trim())?; + match inner.scheme() { + "http" | "https" => Ok(Self { inner }), + scheme => Err(WebviewError::UnsupportedScheme(scheme.to_string())), + } + } + + /// Borrow the underlying URL. + pub fn as_url(&self) -> &Url { + &self.inner + } + + /// Consume this wrapper and return the URL. + pub fn into_url(self) -> Url { + self.inner + } +} + +/// Rings-owned route prefix used to serve controlled webview pages. +#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub struct GatewayPrefix { + prefix: String, +} + +impl GatewayPrefix { + /// Build a gateway prefix such as `/webview/`. + pub fn new(prefix: impl Into) -> Result { + let mut prefix = prefix.into(); + if !prefix.starts_with('/') || prefix.contains('?') || prefix.contains('#') { + return Err(WebviewError::InvalidGatewayPrefix(prefix)); + } + if !prefix.ends_with('/') { + prefix.push('/'); + } + Ok(Self { prefix }) + } + + /// Return the route prefix. + pub fn as_str(&self) -> &str { + &self.prefix + } + + /// Encode `target` into a local controlled-origin gateway URL. + pub fn encode(&self, target: &Url) -> String { + format!( + "{}{}", + self.prefix, + utf8_percent_encode(target.as_str(), NON_ALPHANUMERIC) + ) + } + + /// Decode the target URL embedded in a local gateway path. + pub fn decode_path(&self, path: &str) -> Result { + let Some(encoded) = path.strip_prefix(self.prefix.as_str()) else { + return Err(WebviewError::InvalidGatewayUrl(path.to_string())); + }; + if encoded.is_empty() { + return Err(WebviewError::InvalidGatewayUrl(path.to_string())); + } + let decoded = percent_decode_str(encoded) + .decode_utf8() + .map_err(|error| WebviewError::Decode(error.to_string()))?; + TargetUrl::parse(decoded.as_ref()) + } + + /// Resolve a page URL-bearing value against `document_url`. + pub fn resolve_url_value(&self, document_url: &Url, value: &str) -> Result> { + let trimmed = value.trim(); + if trimmed.is_empty() || is_unrewritable_url(trimmed) { + return Ok(None); + } + let target = document_url.join(trimmed)?; + match target.scheme() { + "http" | "https" => Ok(Some(target)), + _ => Ok(None), + } + } + + /// Resolve a page URL-bearing value against `document_url` and encode it for the gateway. + pub fn rewrite_url_value(&self, document_url: &Url, value: &str) -> Result> { + Ok(self + .resolve_url_value(document_url, value)? + .map(|target| self.encode(&target))) + } +} + +fn is_unrewritable_url(value: &str) -> bool { + let lower = value.to_ascii_lowercase(); + lower.starts_with("javascript:") + || lower.starts_with("mailto:") + || lower.starts_with("tel:") + || lower.starts_with("data:") + || lower.starts_with("blob:") + || lower.starts_with("about:") +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn gateway_url_round_trips_absolute_target() -> Result<()> { + let prefix = GatewayPrefix::new("/webview")?; + let target = TargetUrl::parse("https://example.com/a path/?q=1#section")?; + + let gateway_url = prefix.encode(target.as_url()); + let decoded = prefix.decode_path(&gateway_url)?; + + assert_eq!(decoded, target); + assert!(gateway_url.starts_with("/webview/")); + Ok(()) + } + + #[test] + fn gateway_rejects_non_http_targets() { + assert!(matches!( + TargetUrl::parse("file:///tmp/index.html"), + Err(WebviewError::UnsupportedScheme(_)) + )); + } + + #[test] + fn relative_url_rewrites_against_document_url() -> Result<()> { + let prefix = GatewayPrefix::new("/webview/")?; + let document = TargetUrl::parse("https://example.com/a/page.html")?; + + let rewritten = prefix + .rewrite_url_value(document.as_url(), "next.html?x=1")? + .ok_or_else(|| WebviewError::InvalidGatewayUrl("missing rewrite".to_string()))?; + + assert_eq!( + prefix.decode_path(&rewritten)?.as_url().as_str(), + "https://example.com/a/next.html?x=1" + ); + Ok(()) + } +} diff --git a/crates/webview/tests/browser_gateway.rs b/crates/webview/tests/browser_gateway.rs new file mode 100644 index 000000000..05d1932e9 --- /dev/null +++ b/crates/webview/tests/browser_gateway.rs @@ -0,0 +1,1056 @@ +//! Browser fixture coverage for the webview gateway. +#![cfg(feature = "browser")] + +use std::io::Read; +use std::io::Write; +use std::net::TcpListener; +use std::net::TcpStream; +use std::process::Command; +use std::sync::atomic::AtomicBool; +use std::sync::atomic::Ordering; +use std::sync::Arc; +use std::sync::Mutex; +use std::time::Duration; + +use async_trait::async_trait; +use rings_webview::browser::bootstrap_script; +use rings_webview::GatewayHeader; +use rings_webview::GatewayPrefix; +use rings_webview::GatewayRequest; +use rings_webview::GatewayRequestKind; +use rings_webview::GatewayResponse; +use rings_webview::GatewayTransport; +use rings_webview::Result; +use rings_webview::TargetUrl; +use rings_webview::WebviewError; +use rings_webview::WebviewGateway; + +#[derive(Clone, Default)] +struct FixtureLog { + requests: Arc>>, +} + +impl FixtureLog { + fn push(&self, request: GatewayRequest) { + if let Ok(mut requests) = self.requests.lock() { + requests.push(request); + } + } + + fn requests(&self) -> Result> { + self.requests + .lock() + .map(|requests| requests.clone()) + .map_err(|_| WebviewError::Transport("fixture log lock poisoned".to_string())) + } +} + +struct BrowserFixtureTransport { + log: FixtureLog, +} + +impl BrowserFixtureTransport { + fn new(log: FixtureLog) -> Self { + Self { log } + } +} + +#[async_trait(?Send)] +impl GatewayTransport for BrowserFixtureTransport { + async fn send(&self, request: GatewayRequest) -> Result { + let target = request.target.clone(); + self.log.push(request); + + match target.as_str() { + "https://example.test/docs/index.html" => response( + 200, + "text/html; charset=utf-8", + vec![ + GatewayHeader::new("Set-Cookie", "sid=browser; Path=/; Secure")?, + GatewayHeader::new("Content-Security-Policy", "default-src 'none'")?, + GatewayHeader::new("X-Frame-Options", "DENY")?, + ], + br##" + + + Rings WebView Fixture + + + + + +

Rings WebView Fixture

+ hero + base +
+
+

+

+

+
+ + +
+ + +"## + .to_vec(), + ), + "https://example.test/assets/site.css" => response( + 200, + "text/css; charset=utf-8", + Vec::new(), + b"@import \"inline-import.css\"; #title { color: rgb(1, 2, 3); }".to_vec(), + ), + "https://example.test/assets/inline-import.css" => response( + 200, + "text/css; charset=utf-8", + Vec::new(), + b"#imported-bg { width: 1px; height: 1px; background-image: url('inline-import-bg.png'); }" + .to_vec(), + ), + "https://example.test/assets/dynamic-import.css" => response( + 200, + "text/css; charset=utf-8", + Vec::new(), + b"#dynamic-import-bg { width: 1px; height: 1px; background-image: url('dynamic-import-bg.png'); }" + .to_vec(), + ), + "https://example.test/hero.png" + | "https://example.test/assets/dynamic.png" + | "https://example.test/assets/inline-bg.png" + | "https://example.test/assets/inline-image.png" + | "https://example.test/assets/inline-import-bg.png" + | "https://example.test/assets/srcdoc-image.png" + | "https://example.test/assets/srcdoc-attr-image.png" + | "https://example.test/assets/dynamic-html-image.png" + | "https://example.test/assets/dynamic-html-bg.png" + | "https://example.test/assets/adjacent-html-image.png" + | "https://example.test/assets/outer-html-image.png" + | "https://example.test/assets/dynamic-css-bg.png" + | "https://example.test/assets/dynamic-import-bg.png" + | "https://example.test/assets/dynamic-inline-style-bg.png" + | "https://example.test/assets/cssom-insert-bg.png" + | "https://example.test/assets/cssom-replace-bg.png" + | "https://example.test/assets/document-write-image.png" + | "https://example.test/assets/namespace-image.png" => { + response(200, "image/png", Vec::new(), ONE_PIXEL_PNG.to_vec()) + } + "https://example.test/api/data" => response( + 200, + "application/json", + Vec::new(), + br#"{"message":"fetch ok"}"#.to_vec(), + ), + "https://example.test/assets/runtime-base.json" => response( + 200, + "application/json", + Vec::new(), + br#"{"message":"base fetch ok"}"#.to_vec(), + ), + "https://example.test/assets/srcdoc-fetch.json" => response( + 200, + "application/json", + Vec::new(), + br#"{"message":"srcdoc fetch ok"}"#.to_vec(), + ), + "https://example.test/assets/forms/submit" => response( + 200, + "text/plain; charset=utf-8", + Vec::new(), + b"xhr ok".to_vec(), + ), + "https://example.test/assets/form-result.html?q=test" => response( + 200, + "text/html; charset=utf-8", + Vec::new(), + b"form result

test result

" + .to_vec(), + ), + "https://example.test/assets/ping-one" + | "https://example.test/assets/ping-two" => { + response(200, "text/plain; charset=utf-8", Vec::new(), Vec::new()) + } + "https://example.test/assets/ping-navigation.html" => response( + 200, + "text/html; charset=utf-8", + Vec::new(), + b"ping navigation".to_vec(), + ), + "https://example.test/assets/refresh-navigation.html" => response( + 200, + "text/html; charset=utf-8", + Vec::new(), + b"refresh navigation".to_vec(), + ), + "https://example.test/assets/window-open.html" => response( + 200, + "text/html; charset=utf-8", + Vec::new(), + b"window open".to_vec(), + ), + other => Err(WebviewError::Transport(format!( + "unexpected browser fixture request {other}" + ))), + } + } +} + +#[test] +fn playwright_browser_renders_gateway_fixture_without_direct_remote_requests() -> Result<()> { + let log = FixtureLog::default(); + let prefix = GatewayPrefix::new("/webview/")?; + let target = TargetUrl::parse("https://example.test/docs/index.html")?; + let bootstrap = bootstrap_script(prefix.as_str(), target.as_url()); + let gateway = WebviewGateway::new(prefix.clone(), BrowserFixtureTransport::new(log.clone())) + .with_bootstrap_script(bootstrap); + let server = BrowserFixtureServer::start(prefix.clone(), gateway)?; + let page_url = server.gateway_url(&prefix.encode(target.as_url())); + + run_playwright_fixture(page_url.as_str())?; + + let requests = log.requests()?; + assert_recorded_target( + &requests, + GatewayRequestKind::Navigation, + "GET", + target.as_url().as_str(), + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Subresource, + "GET", + "https://example.test/assets/site.css", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Subresource, + "GET", + "https://example.test/assets/inline-import.css", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Subresource, + "GET", + "https://example.test/hero.png", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Fetch, + "GET", + "https://example.test/api/data", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Fetch, + "GET", + "https://example.test/assets/runtime-base.json", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Xhr, + "POST", + "https://example.test/assets/forms/submit", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Navigation, + "GET", + "https://example.test/assets/form-result.html?q=test", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Subresource, + "GET", + "https://example.test/assets/dynamic.png", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Subresource, + "GET", + "https://example.test/assets/srcdoc-image.png", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Subresource, + "GET", + "https://example.test/assets/srcdoc-attr-image.png", + )?; + assert_recorded_target( + &requests, + GatewayRequestKind::Fetch, + "GET", + "https://example.test/assets/srcdoc-fetch.json", + )?; + for target in [ + "https://example.test/assets/dynamic-html-image.png", + "https://example.test/assets/dynamic-html-bg.png", + "https://example.test/assets/adjacent-html-image.png", + "https://example.test/assets/outer-html-image.png", + "https://example.test/assets/dynamic-css-bg.png", + "https://example.test/assets/dynamic-import.css", + "https://example.test/assets/dynamic-import-bg.png", + "https://example.test/assets/dynamic-inline-style-bg.png", + "https://example.test/assets/cssom-insert-bg.png", + "https://example.test/assets/cssom-replace-bg.png", + "https://example.test/assets/document-write-image.png", + "https://example.test/assets/namespace-image.png", + "https://example.test/assets/refresh-navigation.html", + ] { + assert_recorded_target(&requests, GatewayRequestKind::Subresource, "GET", target)?; + } + for target in [ + "https://example.test/assets/ping-one", + "https://example.test/assets/ping-two", + ] { + assert_recorded_target(&requests, GatewayRequestKind::Fetch, "POST", target)?; + } + for target in [ + "https://example.test/assets/ping-navigation.html", + "https://example.test/assets/window-open.html", + ] { + assert_recorded_target(&requests, GatewayRequestKind::Navigation, "GET", target)?; + } + assert!(requests.iter().all(|request| { + request.target.scheme() == "https" && request.target.host_str() == Some("example.test") + })); + assert!(requests + .iter() + .all(|request| request.headers.iter().all(|header| { + !header.name_eq("host") + && !header.name_eq("origin") + && !header.name_eq("referer") + && !header.name_eq("sec-fetch-dest") + && !header.name_eq("sec-fetch-mode") + && !header.name_eq("sec-fetch-site") + }))); + + server.stop()?; + Ok(()) +} + +struct BrowserFixtureServer { + addr: std::net::SocketAddr, + shutdown: Arc, + handle: Option>>, +} + +impl BrowserFixtureServer { + fn start( + prefix: GatewayPrefix, + gateway: WebviewGateway, + ) -> Result { + let listener = TcpListener::bind("127.0.0.1:0") + .map_err(|error| WebviewError::Transport(error.to_string()))?; + listener + .set_nonblocking(true) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let addr = listener + .local_addr() + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let shutdown = Arc::new(AtomicBool::new(false)); + let thread_shutdown = Arc::clone(&shutdown); + let gateway = Arc::new(Mutex::new(gateway)); + let handle = + std::thread::spawn(move || serve_gateway(listener, thread_shutdown, prefix, gateway)); + Ok(Self { + addr, + shutdown, + handle: Some(handle), + }) + } + + fn gateway_url(&self, gateway_path: &str) -> String { + format!("http://{}{}", self.addr, gateway_path) + } + + fn stop(mut self) -> Result<()> { + self.shutdown.store(true, Ordering::SeqCst); + let _ = TcpStream::connect(self.addr); + if let Some(handle) = self.handle.take() { + handle.join().map_err(|_| { + WebviewError::Transport("browser fixture server panicked".to_string()) + })??; + } + Ok(()) + } +} + +fn serve_gateway( + listener: TcpListener, + shutdown: Arc, + prefix: GatewayPrefix, + gateway: Arc>>, +) -> Result<()> { + while !shutdown.load(Ordering::SeqCst) { + match listener.accept() { + Ok((stream, _peer)) => { + let thread_prefix = prefix.clone(); + let thread_gateway = Arc::clone(&gateway); + std::thread::spawn(move || { + let mut stream = stream; + if let Err(error) = + handle_connection(&mut stream, &thread_prefix, &thread_gateway) + { + write_fixture_error(&mut stream, error); + } + }); + } + Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => { + std::thread::sleep(Duration::from_millis(5)); + } + Err(error) => return Err(WebviewError::Transport(error.to_string())), + } + } + Ok(()) +} + +fn handle_connection( + stream: &mut TcpStream, + prefix: &GatewayPrefix, + gateway: &Arc>>, +) -> Result<()> { + stream + .set_nonblocking(false) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let request = read_http_request(stream)?; + if !request.path.starts_with(prefix.as_str()) { + return write_http_response( + stream, + &GatewayResponse::new( + 404, + vec![GatewayHeader::new("Content-Type", "text/plain")?], + b"not found".to_vec(), + )?, + ); + } + + let kind = gateway_request_kind(&request); + let mut gateway = gateway.lock().map_err(|_| { + WebviewError::Transport("browser fixture gateway lock poisoned".to_string()) + })?; + let mut gateway_request = gateway.request_from_gateway_path(request.path.as_str(), kind)?; + gateway_request.method = request.method; + gateway_request.headers = request.headers; + gateway_request.body = request.body; + let response = futures::executor::block_on(gateway.send(gateway_request))?; + write_http_response(stream, &response) +} + +fn write_fixture_error(stream: &mut TcpStream, error: WebviewError) { + let body = format!("gateway fixture error: {error}"); + let Ok(content_type) = GatewayHeader::new("Content-Type", "text/plain") else { + return; + }; + let Ok(response) = GatewayResponse::new(500, vec![content_type], body.into_bytes()) else { + return; + }; + let _ = write_http_response(stream, &response); +} + +struct HttpRequest { + method: String, + path: String, + headers: Vec, + body: Vec, +} + +fn read_http_request(stream: &mut TcpStream) -> Result { + stream + .set_read_timeout(Some(Duration::from_secs(5))) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let mut buffer = Vec::new(); + let header_end = loop { + let mut chunk = [0_u8; 1024]; + let read = stream + .read(&mut chunk) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + if read == 0 { + return Err(WebviewError::Transport( + "connection closed before request headers".to_string(), + )); + } + let Some(bytes) = chunk.get(..read) else { + return Err(WebviewError::Transport("invalid read size".to_string())); + }; + buffer.extend_from_slice(bytes); + if let Some(index) = find_bytes(buffer.as_slice(), b"\r\n\r\n") { + break index; + } + }; + let body_start = header_end + .checked_add(4) + .ok_or_else(|| WebviewError::Transport("request header offset overflow".to_string()))?; + let header_bytes = buffer + .get(..header_end) + .ok_or_else(|| WebviewError::Transport("invalid request header slice".to_string()))?; + let header_text = std::str::from_utf8(header_bytes) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + let mut lines = header_text.split("\r\n"); + let request_line = lines + .next() + .ok_or_else(|| WebviewError::Transport("missing request line".to_string()))?; + let mut request_parts = request_line.split_whitespace(); + let method = request_parts + .next() + .ok_or_else(|| WebviewError::Transport("missing request method".to_string()))? + .to_string(); + let path = request_parts + .next() + .ok_or_else(|| WebviewError::Transport("missing request path".to_string()))? + .to_string(); + let mut headers = Vec::new(); + let mut content_length = 0_usize; + for line in lines { + let Some((name, value)) = line.split_once(':') else { + continue; + }; + let trimmed_value = value.trim(); + if name.eq_ignore_ascii_case("content-length") { + content_length = trimmed_value + .parse::() + .map_err(|error| WebviewError::Transport(error.to_string()))?; + } + headers.push(GatewayHeader::new(name, trimmed_value)?); + } + let total_len = body_start + .checked_add(content_length) + .ok_or_else(|| WebviewError::Transport("request body offset overflow".to_string()))?; + while buffer.len() < total_len { + let mut chunk = [0_u8; 1024]; + let read = stream + .read(&mut chunk) + .map_err(|error| WebviewError::Transport(error.to_string()))?; + if read == 0 { + return Err(WebviewError::Transport( + "connection closed before request body".to_string(), + )); + } + let Some(bytes) = chunk.get(..read) else { + return Err(WebviewError::Transport("invalid read size".to_string())); + }; + buffer.extend_from_slice(bytes); + } + let body = buffer + .get(body_start..total_len) + .ok_or_else(|| WebviewError::Transport("invalid request body slice".to_string()))? + .to_vec(); + Ok(HttpRequest { + method, + path, + headers, + body, + }) +} + +fn gateway_request_kind(request: &HttpRequest) -> GatewayRequestKind { + if header_value(&request.headers, "x-requested-with") + .is_some_and(|value| value.eq_ignore_ascii_case("XMLHttpRequest")) + { + return GatewayRequestKind::Xhr; + } + if let Some(kind) = header_value(&request.headers, "x-rings-webview-kind") { + return match kind { + "fetch" => GatewayRequestKind::Fetch, + "navigation" => GatewayRequestKind::Navigation, + _ => GatewayRequestKind::Subresource, + }; + } + if request.method != "GET" { + return GatewayRequestKind::Fetch; + } + match header_value(&request.headers, "sec-fetch-dest") { + Some("document") => GatewayRequestKind::Navigation, + _ => GatewayRequestKind::Subresource, + } +} + +fn write_http_response(stream: &mut TcpStream, response: &GatewayResponse) -> Result<()> { + let reason = match response.status { + 200 => "OK", + 404 => "Not Found", + 500 => "Internal Server Error", + _ => "OK", + }; + let mut head = format!( + "HTTP/1.1 {} {}\r\nContent-Length: {}\r\nConnection: close\r\n", + response.status, + reason, + response.body.len() + ); + for header in &response.headers { + head.push_str(header.name.as_str()); + head.push_str(": "); + head.push_str(header.value.as_str()); + head.push_str("\r\n"); + } + head.push_str("\r\n"); + stream + .write_all(head.as_bytes()) + .and_then(|_| stream.write_all(response.body.as_slice())) + .map_err(|error| WebviewError::Transport(error.to_string())) +} + +fn response( + status: u16, + content_type: &str, + extra_headers: Vec, + body: Vec, +) -> Result { + let mut headers = vec![GatewayHeader::new("Content-Type", content_type)?]; + headers.extend(extra_headers); + GatewayResponse::new(status, headers, body) +} + +fn run_playwright_fixture(page_url: &str) -> Result<()> { + if !playwright_available()? { + return Err(WebviewError::Browser( + "Playwright is not available to run browser fixture".to_string(), + )); + } + let program = format!( + r##" +const {{ chromium }} = require("playwright"); +const pageUrl = {page_url:?}; + +(async () => {{ + const browser = await chromium.launch({{ headless: true }}); + try {{ + const context = await browser.newContext(); + const page = await context.newPage(); + const requests = []; + const failures = []; + context.on("request", (request) => requests.push(request.url())); + context.on("requestfailed", (request) => failures.push(`${{request.url()}} ${{request.failure()?.errorText || ""}}`)); + await page.goto(pageUrl, {{ waitUntil: "domcontentloaded" }}); + try {{ + await page.waitForFunction(() => {{ + const srcdocFrame = document.querySelector("#dynamic-srcdoc"); + const srcdocDoc = srcdocFrame?.contentDocument; + const srcdocAttrFrame = document.querySelector("#dynamic-srcdoc-attr"); + const srcdocAttrDoc = srcdocAttrFrame?.contentDocument; + const documentWriteFrame = document.querySelector("#document-write-srcdoc"); + const documentWriteDoc = documentWriteFrame?.contentDocument; + const refreshFrame = document.querySelector("#refresh-navigation-srcdoc"); + const refreshDoc = refreshFrame?.contentDocument; + const hasGatewayBackground = (selector) => {{ + const element = document.querySelector(selector); + return Boolean(element && getComputedStyle(element).backgroundImage.includes("/webview/")); + }}; + return document.querySelector("#fetch-result")?.textContent === "fetch ok" + && document.querySelector("#base-fetch-result")?.textContent === "base fetch ok" + && document.querySelector("#xhr-result")?.textContent === "xhr ok" + && document.querySelector("#static-image")?.complete + && document.querySelector("#base-image")?.complete + && document.querySelector("#dynamic-image")?.complete + && srcdocDoc?.querySelector("#srcdoc-image")?.complete + && srcdocDoc?.body?.dataset?.srcdocFetch === "srcdoc fetch ok" + && !srcdocDoc?.body?.dataset?.srcdocError + && srcdocAttrDoc?.querySelector("#srcdoc-attr-image")?.complete + && document.querySelector("#dynamic-html-image")?.complete + && document.querySelector("#adjacent-html-image")?.complete + && document.querySelector("#outer-html-image")?.complete + && document.querySelector("#namespace-image")?.complete + && documentWriteDoc?.querySelector("#document-write-image")?.complete + && refreshDoc?.title === "refresh navigation" + && hasGatewayBackground("#dynamic-html-bg") + && hasGatewayBackground("#dynamic-css-bg") + && hasGatewayBackground("#dynamic-import-bg") + && hasGatewayBackground("#dynamic-inline-style-bg") + && hasGatewayBackground("#cssom-insert-bg") + && hasGatewayBackground("#cssom-replace-bg"); + }}, null, {{ timeout: 10000 }}); + }} catch (error) {{ + const diagnostic = await page.evaluate(() => {{ + const frameState = (selector) => {{ + const frame = document.querySelector(selector); + return {{ + url: frame?.contentWindow?.location?.href || "", + title: frame?.contentDocument?.title || "" + }}; + }}; + return {{ + fixtureError: document.body.dataset.fixtureError || "", + refresh: frameState("#refresh-navigation-srcdoc"), + namespaceImage: document.querySelector("#namespace-image")?.src || "" + }}; + }}); + throw new Error(`${{error.message}} fixture state=${{JSON.stringify(diagnostic)}}`); + }} + const pingOne = encodeURIComponent("https://example.test/assets/ping-one"); + const pingTwo = encodeURIComponent("https://example.test/assets/ping-two"); + const pingRequests = new Promise((resolve, reject) => {{ + const observed = new Set(); + const timeout = setTimeout(() => reject(new Error(`timed out waiting for gateway ping requests: ${{JSON.stringify([...observed])}}`)), 10000); + const observe = (request) => {{ + if (request.url().includes(pingOne)) observed.add(pingOne); + if (request.url().includes(pingTwo)) observed.add(pingTwo); + if (observed.size === 2) {{ + clearTimeout(timeout); + context.off("request", observe); + resolve(); + }} + }}; + context.on("request", observe); + }}); + const popupPromise = page.waitForEvent("popup"); + await page.locator("#dynamic-ping-link").click(); + const popup = await popupPromise; + await popup.waitForLoadState("domcontentloaded"); + await pingRequests; + const runtimeOpenPopupPromise = page.waitForEvent("popup"); + await page.locator("#runtime-open-button").click(); + const runtimeOpenPopup = await runtimeOpenPopupPromise; + await runtimeOpenPopup.waitForLoadState("domcontentloaded"); + const result = await page.evaluate(() => {{ + const title = document.querySelector("#title"); + const dynamicLink = document.querySelector("#dynamic-link"); + const staticImage = document.querySelector("#static-image"); + const baseImage = document.querySelector("#base-image"); + const dynamicImage = document.querySelector("#dynamic-image"); + const styleBg = document.querySelector("#style-bg"); + const importedBg = document.querySelector("#imported-bg"); + const srcdocFrame = document.querySelector("#dynamic-srcdoc"); + const srcdocDoc = srcdocFrame?.contentDocument; + const srcdocImage = srcdocDoc?.querySelector("#srcdoc-image"); + const srcdocAttrFrame = document.querySelector("#dynamic-srcdoc-attr"); + const srcdocAttrDoc = srcdocAttrFrame?.contentDocument; + const srcdocAttrImage = srcdocAttrDoc?.querySelector("#srcdoc-attr-image"); + const documentWriteFrame = document.querySelector("#document-write-srcdoc"); + const documentWriteImage = documentWriteFrame?.contentDocument?.querySelector("#document-write-image"); + const dynamicHtmlImage = document.querySelector("#dynamic-html-image"); + const adjacentHtmlImage = document.querySelector("#adjacent-html-image"); + const outerHtmlImage = document.querySelector("#outer-html-image"); + const dynamicPing = document.querySelector("#dynamic-ping-link"); + const namespaceImage = document.querySelector("#namespace-image"); + const refreshFrame = document.querySelector("#refresh-navigation-srcdoc"); + const backgroundImage = (selector) => {{ + const element = document.querySelector(selector); + return element ? getComputedStyle(element).backgroundImage : ""; + }}; + return {{ + titleText: title?.textContent, + titleColor: title ? getComputedStyle(title).color : "", + fetchText: document.querySelector("#fetch-result")?.textContent, + baseFetchText: document.querySelector("#base-fetch-result")?.textContent, + xhrText: document.querySelector("#xhr-result")?.textContent, + staticImageSrc: staticImage?.src, + staticImageComplete: Boolean(staticImage?.complete), + baseImageSrc: baseImage?.src, + baseImageComplete: Boolean(baseImage?.complete), + dynamicImageSrc: dynamicImage?.src, + dynamicImageComplete: Boolean(dynamicImage?.complete), + dynamicLinkHref: dynamicLink?.href, + styleBgImage: styleBg ? getComputedStyle(styleBg).backgroundImage : "", + importedBgImage: importedBg ? getComputedStyle(importedBg).backgroundImage : "", + dynamicHtmlImageSrc: dynamicHtmlImage?.src, + dynamicHtmlImageComplete: Boolean(dynamicHtmlImage?.complete), + adjacentHtmlImageSrc: adjacentHtmlImage?.src, + adjacentHtmlImageComplete: Boolean(adjacentHtmlImage?.complete), + outerHtmlImageSrc: outerHtmlImage?.src, + outerHtmlImageComplete: Boolean(outerHtmlImage?.complete), + documentWriteImageSrc: documentWriteImage?.src, + documentWriteImageComplete: Boolean(documentWriteImage?.complete), + dynamicHtmlBgImage: backgroundImage("#dynamic-html-bg"), + dynamicCssBgImage: backgroundImage("#dynamic-css-bg"), + dynamicImportBgImage: backgroundImage("#dynamic-import-bg"), + dynamicInlineStyleBgImage: backgroundImage("#dynamic-inline-style-bg"), + cssomInsertBgImage: backgroundImage("#cssom-insert-bg"), + cssomReplaceBgImage: backgroundImage("#cssom-replace-bg"), + dynamicPingHref: dynamicPing?.href, + dynamicPingValue: dynamicPing?.getAttribute("ping"), + namespaceImageSrc: namespaceImage?.src, + refreshFrameUrl: refreshFrame?.contentWindow?.location?.href || "", + srcdocImageSrc: srcdocImage?.src, + srcdocImageComplete: Boolean(srcdocImage?.complete), + srcdocFetchText: srcdocDoc?.body?.dataset?.srcdocFetch || "", + srcdocError: srcdocDoc?.body?.dataset?.srcdocError || "", + srcdocAttrImageSrc: srcdocAttrImage?.src, + srcdocAttrImageComplete: Boolean(srcdocAttrImage?.complete), + fixtureError: document.body.dataset.fixtureError || "" + }}; + }}); + await page.locator("#gateway-search-submit").click(); + const encodedFormTarget = encodeURIComponent("https://example.test/assets/form-result.html?q=test"); + await page.waitForFunction((target) => ( + document.title === "form result" + && document.querySelector("#form-result")?.textContent === "test result" + && location.href.endsWith(`/webview/${{target}}`) + ), encodedFormTarget); + const formResult = await page.evaluate(() => ({{ + text: document.querySelector("#form-result")?.textContent || "", + title: document.title, + url: location.href + }})); + if (formResult.title !== "form result" || formResult.text !== "test result") {{ + throw new Error(`GET form result did not render: ${{JSON.stringify(formResult)}}`); + }} + if (!formResult.url.endsWith(`/webview/${{encodedFormTarget}}`)) {{ + throw new Error(`GET form escaped its encoded gateway target: ${{JSON.stringify(formResult)}}`); + }} + const directRemoteRequests = requests.filter((url) => {{ + try {{ + return new URL(url).hostname === "example.test"; + }} catch (_error) {{ + return false; + }} + }}); + const failuresWithoutFavicon = failures.filter((failure) => !failure.includes("/favicon.ico")); + if (directRemoteRequests.length > 0) {{ + throw new Error(`direct remote requests escaped gateway: ${{directRemoteRequests.join(", ")}}`); + }} + if (failuresWithoutFavicon.length > 0) {{ + throw new Error(`browser request failures: ${{failuresWithoutFavicon.join(", ")}}`); + }} + if (result.fixtureError) {{ + throw new Error(`page fixture error: ${{result.fixtureError}}`); + }} + if (result.titleText !== "Rings WebView Fixture") {{ + throw new Error(`page title did not render: ${{JSON.stringify(result)}}`); + }} + if (result.titleColor !== "rgb(1, 2, 3)") {{ + throw new Error(`stylesheet did not apply: ${{JSON.stringify(result)}}`); + }} + if (result.fetchText !== "fetch ok" || result.xhrText !== "xhr ok") {{ + throw new Error(`dynamic requests did not complete: ${{JSON.stringify(result)}}`); + }} + if (result.baseFetchText !== "base fetch ok") {{ + throw new Error(`base-relative fetch did not complete: ${{JSON.stringify(result)}}`); + }} + if (result.srcdocError) {{ + throw new Error(`srcdoc fixture error: ${{result.srcdocError}} ${{JSON.stringify(result)}}`); + }} + if (result.srcdocFetchText !== "srcdoc fetch ok") {{ + throw new Error(`srcdoc fetch did not complete: ${{JSON.stringify(result)}}`); + }} + if (!result.staticImageSrc.includes("/webview/") || !result.baseImageSrc.includes("/webview/") || !result.dynamicImageSrc.includes("/webview/")) {{ + throw new Error(`image URLs did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.srcdocImageSrc.includes("/webview/") || !result.srcdocAttrImageSrc.includes("/webview/")) {{ + throw new Error(`srcdoc image URLs did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.dynamicHtmlImageSrc.includes("/webview/") || !result.adjacentHtmlImageSrc.includes("/webview/") || !result.outerHtmlImageSrc.includes("/webview/") || !result.documentWriteImageSrc.includes("/webview/")) {{ + throw new Error(`runtime HTML URLs did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.namespaceImageSrc.includes("/webview/")) {{ + throw new Error(`setAttributeNS URL did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.styleBgImage.includes("/webview/") || !result.importedBgImage.includes("/webview/")) {{ + throw new Error(`CSS URLs did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (![result.dynamicHtmlBgImage, result.dynamicCssBgImage, result.dynamicImportBgImage, result.dynamicInlineStyleBgImage, result.cssomInsertBgImage, result.cssomReplaceBgImage].every((value) => value.includes("/webview/"))) {{ + throw new Error(`runtime CSS URLs did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.dynamicLinkHref.includes("/webview/")) {{ + throw new Error(`dynamic link URL did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.dynamicPingHref.includes("/webview/") || !result.dynamicPingValue.includes("/webview/")) {{ + throw new Error(`dynamic ping URLs did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + if (!result.refreshFrameUrl.includes("/webview/")) {{ + throw new Error(`runtime refresh navigation did not stay on gateway: ${{JSON.stringify(result)}}`); + }} + }} finally {{ + await browser.close(); + }} +}})().catch(async (error) => {{ + console.error(error && error.stack ? error.stack : String(error)); + process.exit(1); +}}); +"## + ); + let output = Command::new("node") + .arg("-e") + .arg(program) + .output() + .map_err(|error| WebviewError::Browser(error.to_string()))?; + if !output.status.success() { + return Err(WebviewError::Browser(format!( + "Playwright browser fixture failed: stdout={} stderr={}", + String::from_utf8_lossy(output.stdout.as_slice()), + String::from_utf8_lossy(output.stderr.as_slice()) + ))); + } + Ok(()) +} + +fn playwright_available() -> Result { + let output = Command::new("node") + .arg("-e") + .arg("require.resolve('playwright')") + .output() + .map_err(|error| WebviewError::Browser(error.to_string()))?; + Ok(output.status.success()) +} + +fn assert_recorded_target( + requests: &[GatewayRequest], + kind: GatewayRequestKind, + method: &str, + target: &str, +) -> Result<()> { + let found = requests.iter().any(|request| { + request.kind == kind && request.method == method && request.target.as_str() == target + }); + if found { + Ok(()) + } else { + Err(WebviewError::Transport(format!( + "missing recorded {kind:?} {method} request to {target}" + ))) + } +} + +fn header_value<'a>(headers: &'a [GatewayHeader], name: &str) -> Option<&'a str> { + headers + .iter() + .find(|header| header.name_eq(name)) + .map(|header| header.value.as_str()) +} + +fn find_bytes(haystack: &[u8], needle: &[u8]) -> Option { + haystack + .windows(needle.len()) + .position(|window| window == needle) +} + +const ONE_PIXEL_PNG: &[u8] = &[ + 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, + 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, + 0x89, 0x00, 0x00, 0x00, 0x0a, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x00, 0x01, 0x00, 0x00, + 0x05, 0x00, 0x01, 0x0d, 0x0a, 0x2d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, + 0x42, 0x60, 0x82, +]; diff --git a/crates/webview/tests/webview_flow.rs b/crates/webview/tests/webview_flow.rs new file mode 100644 index 000000000..e1eb6071c --- /dev/null +++ b/crates/webview/tests/webview_flow.rs @@ -0,0 +1,281 @@ +//! End-to-end policy flow coverage for the webview gateway. +#![cfg(feature = "browser")] + +use std::cell::RefCell; +use std::rc::Rc; + +use async_trait::async_trait; +use rings_webview::browser::bootstrap_script; +use rings_webview::browser::runtime_gateway_url; +use rings_webview::browser::BOOTSTRAP_MARKER; +use rings_webview::GatewayHeader; +use rings_webview::GatewayPrefix; +use rings_webview::GatewayRequest; +use rings_webview::GatewayRequestKind; +use rings_webview::GatewayResponse; +use rings_webview::GatewayTransport; +use rings_webview::Result; +use rings_webview::TargetUrl; +use rings_webview::WebviewError; +use rings_webview::WebviewGateway; +use rings_webview::WebviewRenderer; +use url::Url; + +#[derive(Clone, Default)] +struct FixtureLog { + requests: Rc>>, +} + +impl FixtureLog { + fn push(&self, request: GatewayRequest) { + self.requests.borrow_mut().push(request); + } + + fn requests(&self) -> Vec { + self.requests.borrow().clone() + } +} + +struct FixtureTransport { + log: FixtureLog, +} + +impl FixtureTransport { + fn new(log: FixtureLog) -> Self { + Self { log } + } +} + +#[async_trait(?Send)] +impl GatewayTransport for FixtureTransport { + async fn send(&self, request: GatewayRequest) -> Result { + let target = request.target.clone(); + self.log.push(request); + + match target.as_str() { + "https://example.test/docs/index.html" => response( + 200, + "text/html; charset=utf-8", + vec![ + GatewayHeader::new("Set-Cookie", "sid=fixture; Path=/; Secure")?, + GatewayHeader::new("Content-Security-Policy", "default-src 'none'")?, + GatewayHeader::new("X-Frame-Options", "DENY")?, + ], + br#" + + + + + + + + + next + +
+ +"# + .to_vec(), + ), + "https://example.test/assets/site.css" => response( + 200, + "text/css; charset=utf-8", + Vec::new(), + br#"@import "theme.css"; body { background: url('/img/bg.png'); }"#.to_vec(), + ), + "https://example.test/api/data" => response( + 200, + "application/json", + Vec::new(), + br#"{"ok":true}"#.to_vec(), + ), + "https://example.test/docs/forms/submit" => { + response(204, "text/plain", Vec::new(), Vec::new()) + } + "https://example.test/assets/forms/submit" => { + response(204, "text/plain", Vec::new(), Vec::new()) + } + "https://example.test/redirect" => response( + 302, + "text/html", + vec![GatewayHeader::new("Location", "/login")?], + Vec::new(), + ), + other => Err(WebviewError::Transport(format!( + "unexpected fixture request {other}" + ))), + } + } +} + +#[test] +fn webview_gateway_renders_and_routes_page_flow() -> Result<()> { + let log = FixtureLog::default(); + let prefix = GatewayPrefix::new("/webview/")?; + let target = TargetUrl::parse("https://example.test/docs/index.html")?; + let bootstrap = bootstrap_script(prefix.as_str(), target.as_url()); + let gateway = WebviewGateway::new(prefix.clone(), FixtureTransport::new(log.clone())) + .with_bootstrap_script(bootstrap); + let mut renderer = WebviewRenderer::new(gateway); + + let page = futures::executor::block_on(renderer.render(target.clone()))?; + + assert_eq!(page.status, 200); + assert_eq!(page.gateway_url, prefix.encode(target.as_url())); + assert_contains(page.html(), "data-rings-webview-bootstrap"); + assert_contains(page.html(), BOOTSTRAP_MARKER); + assert_contains(page.html(), "targetBase"); + assert_contains(page.html(), target.as_url().as_str()); + assert_absent(page.html(), "href=\"/assets/site.css\""); + assert_absent(page.html(), "src=\"app.js\""); + assert_absent(page.html(), "href=\"../next\""); + assert_absent(page.html(), "action=\"forms/submit\""); + assert_absent(page.html(), "url(inline-bg.png)"); + assert_header_absent(&page.headers, "set-cookie"); + assert!(page.headers.iter().any(|header| { + header.name_eq("content-security-policy") && header.value.contains("connect-src 'self'") + })); + assert_header_absent(&page.headers, "x-frame-options"); + + let stylesheet = Url::parse("https://example.test/assets/site.css")?; + let script = Url::parse("https://example.test/assets/app.js")?; + let next = Url::parse("https://example.test/next")?; + let thumb = Url::parse("https://example.test/assets/thumb.png")?; + let hero = Url::parse("https://example.test/hero.png")?; + let submit = Url::parse("https://example.test/assets/forms/submit")?; + let inline_bg = Url::parse("https://example.test/assets/inline-bg.png")?; + let base = Url::parse("https://example.test/assets/")?; + for expected in [ + &stylesheet, + &script, + &next, + &thumb, + &hero, + &submit, + &inline_bg, + &base, + ] { + assert_contains(page.html(), prefix.encode(expected).as_str()); + } + + let css_path = prefix.encode(&stylesheet); + let css_response = futures::executor::block_on( + renderer + .gateway_mut() + .send_gateway_path(&css_path, GatewayRequestKind::Subresource), + )?; + let css = utf8_body(css_response)?; + assert_contains( + &css, + prefix + .encode(&Url::parse("https://example.test/assets/theme.css")?) + .as_str(), + ); + assert_contains( + &css, + prefix + .encode(&Url::parse("https://example.test/img/bg.png")?) + .as_str(), + ); + + let fetch_path = required_runtime_gateway_url(&prefix, target.as_url(), "/api/data")?; + assert!(fetch_path.starts_with(prefix.as_str())); + assert!(!fetch_path.starts_with("https://")); + let fetch_response = futures::executor::block_on( + renderer + .gateway_mut() + .send_gateway_path(&fetch_path, GatewayRequestKind::Fetch), + )?; + assert_eq!(utf8_body(fetch_response)?, r#"{"ok":true}"#); + + let runtime_base = Url::parse("https://example.test/assets/")?; + let xhr_path = required_runtime_gateway_url(&prefix, &runtime_base, "forms/submit")?; + let mut xhr_request = renderer + .gateway() + .request_from_gateway_path(&xhr_path, GatewayRequestKind::Xhr)?; + xhr_request.method = "POST".to_string(); + xhr_request.body = b"name=value".to_vec(); + let xhr_response = futures::executor::block_on(renderer.gateway_mut().send(xhr_request))?; + assert_eq!(xhr_response.status, 204); + + let redirect_path = prefix.encode(&Url::parse("https://example.test/redirect")?); + let redirect_response = futures::executor::block_on( + renderer + .gateway_mut() + .send_gateway_path(&redirect_path, GatewayRequestKind::Navigation), + )?; + assert_eq!(redirect_response.status, 302); + let location = header_value(&redirect_response.headers, "location") + .ok_or_else(|| WebviewError::Header("missing redirect location".to_string()))?; + assert_eq!( + prefix.decode_path(location)?.as_url().as_str(), + "https://example.test/login" + ); + + let requests = log.requests(); + assert!(requests.iter().all(|request| { + matches!(request.target.scheme(), "http" | "https") + && !request.target.as_str().starts_with(prefix.as_str()) + })); + assert!(requests.iter().any(|request| { + request.kind == GatewayRequestKind::Subresource + && request.target.as_str() == "https://example.test/assets/site.css" + })); + assert!(requests.iter().any(|request| { + request.kind == GatewayRequestKind::Fetch + && request.target.as_str() == "https://example.test/api/data" + && header_value(&request.headers, "cookie") == Some("sid=fixture") + })); + assert!(requests.iter().any(|request| { + request.kind == GatewayRequestKind::Xhr + && request.method == "POST" + && request.target.as_str() == "https://example.test/assets/forms/submit" + && request.body.as_slice() == b"name=value" + && header_value(&request.headers, "cookie") == Some("sid=fixture") + })); + + Ok(()) +} + +fn response( + status: u16, + content_type: &str, + extra_headers: Vec, + body: Vec, +) -> Result { + let mut headers = vec![GatewayHeader::new("Content-Type", content_type)?]; + headers.extend(extra_headers); + GatewayResponse::new(status, headers, body) +} + +fn required_runtime_gateway_url( + prefix: &GatewayPrefix, + document_url: &Url, + input: &str, +) -> Result { + runtime_gateway_url(prefix, document_url, input)? + .ok_or_else(|| WebviewError::InvalidGatewayUrl(input.to_string())) +} + +fn utf8_body(response: GatewayResponse) -> Result { + String::from_utf8(response.body).map_err(|error| WebviewError::Render(error.to_string())) +} + +fn header_value<'a>(headers: &'a [GatewayHeader], name: &str) -> Option<&'a str> { + headers + .iter() + .find(|header| header.name_eq(name)) + .map(|header| header.value.as_str()) +} + +fn assert_header_absent(headers: &[GatewayHeader], name: &str) { + assert!(header_value(headers, name).is_none(), "unexpected {name}"); +} + +fn assert_contains(haystack: &str, needle: &str) { + assert!(haystack.contains(needle), "missing {needle}"); +} + +fn assert_absent(haystack: &str, needle: &str) { + assert!(!haystack.contains(needle), "unexpected {needle}"); +} diff --git a/docker/cluster/Dockerfile b/docker/cluster/Dockerfile index a36c31dc8..22fa59f64 100644 --- a/docker/cluster/Dockerfile +++ b/docker/cluster/Dockerfile @@ -6,6 +6,7 @@ WORKDIR /src COPY Cargo.lock Cargo.toml README.md rust-toolchain.toml ./ COPY crates ./crates COPY examples ./examples +COPY third_party ./third_party RUN cargo build -p rings-node --bin rings --features node --no-default-features --release diff --git a/frontend/Cargo.lock b/frontend/Cargo.lock index 525cb1ba1..4774c96f1 100644 --- a/frontend/Cargo.lock +++ b/frontend/Cargo.lock @@ -135,7 +135,7 @@ version = "1.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" dependencies = [ - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -146,7 +146,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" dependencies = [ "anstyle", "once_cell_polyfill", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -474,7 +474,7 @@ dependencies = [ "bitflags 2.13.0", "cexpr", "clang-sys", - "itertools 0.10.5", + "itertools 0.12.1", "log", "prettyplease", "proc-macro2", @@ -1187,6 +1187,29 @@ dependencies = [ "subtle", ] +[[package]] +name = "cssparser" +version = "0.36.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dae61cf9c0abb83bd659dab65b7e4e38d8236824c85f0f804f173567bda257d2" +dependencies = [ + "cssparser-macros", + "dtoa-short", + "itoa", + "phf", + "smallvec", +] + +[[package]] +name = "cssparser-macros" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13b588ba4ac1a99f7f2964d24b3d896ddc6bf847ee3855dbd4366f058cfcd331" +dependencies = [ + "quote", + "syn 2.0.118", +] + [[package]] name = "ctr" version = "0.9.2" @@ -1414,6 +1437,21 @@ version = "0.15.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "77c90badedccf4105eca100756a0b1289e191f6fcbdadd3cee1d2f614f97da8f" +[[package]] +name = "dtoa" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590" + +[[package]] +name = "dtoa-short" +version = "0.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd1511a7b6a56299bd043a9c167a6d2bfb37bf84a6dfceaba651168adfb43c87" +dependencies = [ + "dtoa", +] + [[package]] name = "ecdsa" version = "0.16.9" @@ -1514,6 +1552,15 @@ dependencies = [ "log", ] +[[package]] +name = "encoding_rs" +version = "0.8.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3" +dependencies = [ + "cfg-if", +] + [[package]] name = "enum-iterator" version = "2.3.0" @@ -1568,7 +1615,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" dependencies = [ "libc", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -2334,6 +2381,8 @@ version = "0.17.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" dependencies = [ + "allocator-api2", + "equivalent", "foldhash", ] @@ -2754,7 +2803,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46" dependencies = [ "hermit-abi", "libc", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -3026,6 +3075,25 @@ version = "0.4.33" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" +[[package]] +name = "lol_html" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ae574a677ef0443a0bd3c291f0cab9d1e61a3ad85a1515e3cfc0bc720d5a48e" +dependencies = [ + "bitflags 2.13.0", + "cfg-if", + "cssparser", + "encoding_rs", + "foldhash", + "hashbrown 0.17.1", + "memchr", + "mime", + "precomputed-hash", + "selectors", + "thiserror 2.0.18", +] + [[package]] name = "lru-slab" version = "0.1.2" @@ -3101,6 +3169,12 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "mime" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a" + [[package]] name = "minicov" version = "0.3.8" @@ -3239,7 +3313,7 @@ version = "0.50.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" dependencies = [ - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -3478,6 +3552,50 @@ dependencies = [ "indexmap", ] +[[package]] +name = "phf" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1562dc717473dbaa4c1f85a36410e03c047b2e7df7f45ee938fbef64ae7fadf" +dependencies = [ + "phf_macros", + "phf_shared 0.13.1", + "serde", +] + +[[package]] +name = "phf_codegen" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49aa7f9d80421bca176ca8dbfebe668cc7a2684708594ec9f3c0db0805d5d6e1" +dependencies = [ + "phf_generator", + "phf_shared 0.13.1", +] + +[[package]] +name = "phf_generator" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "135ace3a761e564ec88c03a77317a7c6b80bb7f7135ef2544dbe054243b89737" +dependencies = [ + "fastrand", + "phf_shared 0.13.1", +] + +[[package]] +name = "phf_macros" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "812f032b54b1e759ccd5f8b6677695d5268c588701effba24601f6932f8269ef" +dependencies = [ + "phf_generator", + "phf_shared 0.13.1", + "proc-macro2", + "quote", + "syn 2.0.118", +] + [[package]] name = "phf_shared" version = "0.11.3" @@ -3487,6 +3605,15 @@ dependencies = [ "siphasher", ] +[[package]] +name = "phf_shared" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e57fef6bc5981e38c2ce2d63bfa546861309f875b8a75f092d1d54ae2d64f266" +dependencies = [ + "siphasher", +] + [[package]] name = "pin-project" version = "1.1.13" @@ -4202,14 +4329,17 @@ dependencies = [ name = "rings-frontend" version = "0.1.0" dependencies = [ + "async-trait", "base58", "base64 0.22.1", "futures", "gloo-timers 0.3.0", "js-sys", "rings-node", + "rings-webview", "serde", "serde_json", + "url", "wasm-bindgen", "wasm-bindgen-futures", "wasm-bindgen-test", @@ -4328,6 +4458,22 @@ dependencies = [ "web-sys", ] +[[package]] +name = "rings-webview" +version = "0.14.0" +dependencies = [ + "async-trait", + "js-sys", + "lol_html", + "percent-encoding", + "serde", + "serde-wasm-bindgen 0.6.5", + "thiserror 1.0.69", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", +] + [[package]] name = "rkyv" version = "0.8.16" @@ -4418,7 +4564,7 @@ dependencies = [ "errno", "libc", "linux-raw-sys 0.12.1", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -4506,6 +4652,25 @@ dependencies = [ "zeroize", ] +[[package]] +name = "selectors" +version = "0.37.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2cfaaa6035167f0e604e42723c7650d59ee269ef220d7bbe0565602c8a0173b9" +dependencies = [ + "bitflags 2.13.0", + "cssparser", + "derive_more", + "log", + "new_debug_unreachable", + "phf", + "phf_codegen", + "precomputed-hash", + "rustc-hash", + "servo_arc", + "smallvec", +] + [[package]] name = "self_cell" version = "1.2.2" @@ -4637,6 +4802,15 @@ dependencies = [ "serde", ] +[[package]] +name = "servo_arc" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "170fb83ab34de17dc69aa7c67482b22218ddb85da56546f9bd6b929e32a05930" +dependencies = [ + "stable_deref_trait", +] + [[package]] name = "sha1" version = "0.10.6" @@ -4777,7 +4951,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51" dependencies = [ "libc", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -4826,7 +5000,7 @@ checksum = "bf776ba3fa74f83bf4b63c3dcbbf82173db2632ed8452cb2d891d33f459de70f" dependencies = [ "new_debug_unreachable", "parking_lot", - "phf_shared", + "phf_shared 0.11.3", "precomputed-hash", ] @@ -4948,7 +5122,7 @@ dependencies = [ "getrandom 0.4.3", "once_cell", "rustix 1.1.4", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -5854,7 +6028,7 @@ version = "0.1.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" dependencies = [ - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] diff --git a/frontend/Cargo.toml b/frontend/Cargo.toml index b4ab01864..6feea96b0 100644 --- a/frontend/Cargo.toml +++ b/frontend/Cargo.toml @@ -13,12 +13,15 @@ publish = false [dependencies] base58 = "0.2" base64 = "0.22" +async-trait = "0.1" futures = "0.3" gloo-timers = { version = "0.3", features = ["futures"] } js-sys = "=0.3.98" rings-node = { path = "../crates/node", default-features = false, features = ["browser_default"] } +rings-webview = { path = "../crates/webview", features = ["browser"] } serde = { version = "1", features = ["derive"] } serde_json = "1" +url = "2" wasm-bindgen = "=0.2.121" wasm-bindgen-futures = "=0.4.71" web-sys = { version = "=0.3.98", features = [ @@ -30,6 +33,7 @@ web-sys = { version = "=0.3.98", features = [ "HtmlTextAreaElement", "InputEvent", "Location", + "SubmitEvent", "Url", "Window", ] } diff --git a/frontend/Trunk.toml b/frontend/Trunk.toml index f46a0b246..0ed44a76d 100644 --- a/frontend/Trunk.toml +++ b/frontend/Trunk.toml @@ -3,6 +3,7 @@ watch = [ "index.html", "src", "assets", + "rings-webview-service-worker.js", "Cargo.toml", "Trunk.toml", "extension-assets", diff --git a/frontend/assets/webview-host.js b/frontend/assets/webview-host.js new file mode 100644 index 000000000..035b22ff1 --- /dev/null +++ b/frontend/assets/webview-host.js @@ -0,0 +1,182 @@ +(() => { + "use strict"; + + const workerUrl = "/rings-webview-service-worker.js?gateway-host-protocol=3"; + let registrationPromise; + const debugEntries = []; + + function recordDebug(scope, message, level = "info", resource = undefined) { + const entry = { + at: new Date().toISOString(), + scope, + message, + level, + }; + if (resource) { + entry.resource = resource; + } + debugEntries.push(entry); + if (debugEntries.length > 200) { + debugEntries.splice(0, debugEntries.length - 200); + } + } + + function ensureServiceWorkerSupport() { + if (!navigator.serviceWorker) { + throw new Error("Service Worker is unavailable in this browser context"); + } + } + + function waitForController() { + if (navigator.serviceWorker.controller) { + return Promise.resolve(); + } + return new Promise((resolve, reject) => { + const timeout = globalThis.setTimeout(() => { + navigator.serviceWorker.removeEventListener("controllerchange", onChange); + reject(new Error("Service Worker did not take control of this page")); + }, 5_000); + function onChange() { + globalThis.clearTimeout(timeout); + navigator.serviceWorker.removeEventListener("controllerchange", onChange); + resolve(); + } + navigator.serviceWorker.addEventListener("controllerchange", onChange, { once: true }); + }); + } + + async function registration() { + ensureServiceWorkerSupport(); + if (!registrationPromise) { + registrationPromise = navigator.serviceWorker + .register(workerUrl, { scope: "/" }) + .then(async (activeRegistration) => { + await activeRegistration.update(); + return activeRegistration; + }); + } + return registrationPromise; + } + + async function ensureReady() { + const activeRegistration = await registration(); + await navigator.serviceWorker.ready; + await waitForController(); + recordDebug("popup", "Service Worker controls this popup"); + return activeRegistration; + } + + async function registerGatewayHost() { + const activeRegistration = await ensureReady(); + const worker = navigator.serviceWorker.controller || activeRegistration.active; + if (!worker) { + throw new Error("Service Worker has no active controller"); + } + await postWorkerMessage(worker, { type: "rings-webview-host-register" }); + recordDebug("host", "Registered the local Rings node as gateway host"); + } + + async function enableDebug() { + const activeRegistration = await ensureReady(); + const worker = navigator.serviceWorker.controller || activeRegistration.active; + if (!worker) { + throw new Error("Service Worker has no active controller"); + } + const acknowledged = await postWorkerMessage(worker, { type: "rings-webview-debug-register" }); + if (!acknowledged) { + recordDebug("popup", "Service Worker did not acknowledge debug registration; continuing"); + } + recordDebug("popup", "Registered popup debug listener"); + } + + function postWorkerMessage(worker, message) { + return new Promise((resolve) => { + const channel = new MessageChannel(); + const timeout = globalThis.setTimeout(() => { + channel.port1.close(); + resolve(false); + }, 500); + channel.port1.onmessage = (event) => { + globalThis.clearTimeout(timeout); + channel.port1.close(); + resolve(Boolean(event.data?.ok)); + }; + worker.postMessage(message, [channel.port2]); + }); + } + + function takeDebugEntries() { + return debugEntries.splice(0, debugEntries.length); + } + + function clearDebugEntries() { + debugEntries.splice(0, debugEntries.length); + } + + navigator.serviceWorker?.addEventListener("message", (event) => { + const message = event.data; + if (message?.type === "rings-webview-debug") { + recordDebug( + message.scope || "worker", + message.message || "unknown event", + message.level || "info", + message.resource, + ); + return; + } + if (message?.type === "rings-webview-gateway-host-query") { + const ready = typeof globalThis.RingsWebviewGateway?.handle === "function"; + event.ports?.[0]?.postMessage({ ready }); + const worker = navigator.serviceWorker.controller; + if (ready && worker) { + void postWorkerMessage(worker, { type: "rings-webview-host-register" }) + .then(() => recordDebug("host", "Restored the local Rings node gateway host")); + } + return; + } + if (message?.type !== "rings-webview-gateway-request") { + return; + } + const port = event.ports?.[0]; + if (!port) { + return; + } + const handler = globalThis.RingsWebviewGateway?.handle; + if (typeof handler !== "function") { + recordDebug("host", "Rejected request because the local node gateway is unavailable", "error"); + port.postMessage({ + ok: false, + status: 503, + error: "the local Rings node gateway is unavailable", + }); + return; + } + recordDebug("host", `Received ${message.request.kind} ${message.request.method} request`); + Promise.resolve(handler(message.request)) + .then((response) => { + if (response?.ok) { + recordDebug("host", `Returned gateway response ${response.status}`); + } else { + recordDebug("host", `Gateway response ${response?.status || 502}: ${response?.error || "unknown error"}`, "error"); + } + port.postMessage(response); + }) + .catch((error) => { + recordDebug("host", `Gateway handler failed: ${String(error)}`, "error"); + port.postMessage({ + ok: false, + status: 502, + error: String(error), + }); + }); + }); + + globalThis.RingsWebviewHost = Object.freeze({ + ensureReady, + registerGatewayHost, + enableDebug, + recordDebugEntry: recordDebug, + takeDebugEntries, + clearDebugEntries, + }); +})(); diff --git a/frontend/index.html b/frontend/index.html index 974deb65f..06330b23e 100644 --- a/frontend/index.html +++ b/frontend/index.html @@ -5,8 +5,11 @@ Rings - A P2P network for the sovereign age + - + + + diff --git a/frontend/rings-webview-service-worker.js b/frontend/rings-webview-service-worker.js new file mode 100644 index 000000000..73669b02d --- /dev/null +++ b/frontend/rings-webview-service-worker.js @@ -0,0 +1,422 @@ +"use strict"; + +const gatewayPrefix = "/webview/"; +const requestTimeoutMs = 30_000; +let gatewayHostClientId = null; +const debugClientIds = new Set(); +const debugHistory = []; +let nextRequestId = 1; + +self.addEventListener("install", (event) => { + event.waitUntil(self.skipWaiting()); +}); + +self.addEventListener("activate", (event) => { + event.waitUntil(self.clients.claim()); +}); + +self.addEventListener("message", (event) => { + const clientId = event.source?.id; + const reply = event.ports?.[0]; + if (event.data?.type === "rings-webview-host-register" && typeof clientId === "string" && clientId) { + updateGatewayHost(clientId); + void emitDebug("worker", "Updated local Rings node gateway host"); + reply?.postMessage({ ok: true }); + return; + } + if (event.data?.type === "rings-webview-debug-register" && typeof clientId === "string" && clientId) { + debugClientIds.add(clientId); + void self.clients.get(clientId).then(async (client) => { + for (const entry of debugHistory) { + client?.postMessage(entry); + } + await emitDebug("worker", "Registered popup debug client"); + }); + reply?.postMessage({ ok: true }); + return; + } + reply?.postMessage({ ok: false, error: "unsupported gateway registration" }); +}); + +self.addEventListener("fetch", (event) => { + const url = new URL(event.request.url); + if (url.origin !== self.location.origin || !url.pathname.startsWith(gatewayPrefix)) { + return; + } + event.respondWith(handleGatewayFetch(event)); +}); + +async function handleGatewayFetch(event) { + const requestId = nextRequestId; + nextRequestId += 1; + const startedAt = performance.now(); + const request = await serializeRequest(event); + await emitResourceDebug( + requestId, + request, + startedAt, + "intercepted", + `#${requestId} intercepted ${request.kind} ${request.method} ${requestedTarget(request.requested)} (mode=${event.request.mode}, destination=${event.request.destination || "none"})`, + ); + const host = await gatewayHostClient(); + if (!host) { + await emitResourceDebug( + requestId, + request, + startedAt, + "failed", + `#${requestId} rejected: no local gateway host`, + "error", + 503, + ); + return gatewayFailure(503, "Start a local Rings node before opening WebView."); + } + await emitResourceDebug( + requestId, + request, + startedAt, + "dispatched", + `#${requestId} dispatched to the local gateway host`, + ); + const response = await requestGatewayResponse(host, request); + if (!response?.ok) { + const status = response?.status || 502; + await emitResourceDebug( + requestId, + request, + startedAt, + "failed", + `#${requestId} gateway failure ${status}: ${response?.error || "unknown error"}`, + "error", + status, + ); + return gatewayFailure(response?.status || 502, response?.error || "gateway request failed"); + } + try { + const headers = new Headers(); + for (const header of response.headers || []) { + headers.append(header.name, header.value); + } + await emitResourceDebug( + requestId, + request, + startedAt, + "completed", + `#${requestId} returned ${response.status}`, + "info", + response.status, + ); + return new Response(responseMustNotHaveBody(response.status) ? null : response.body || null, { + status: response.status, + headers, + }); + } catch (error) { + await emitResourceDebug( + requestId, + request, + startedAt, + "failed", + `#${requestId} invalid gateway response: ${String(error)}`, + "error", + 502, + ); + return gatewayFailure(502, `invalid gateway response: ${String(error)}`); + } +} + +function responseMustNotHaveBody(status) { + return status === 204 || status === 205 || status === 304; +} + +async function emitResourceDebug(requestId, request, startedAt, phase, message, level = "info", status = undefined) { + const resource = { + requestId, + target: requestedTarget(request.requested), + method: request.method, + kind: request.kind, + phase, + durationMs: Math.max(0, Math.round(performance.now() - startedAt)), + }; + if (status !== undefined) { + resource.status = status; + } + await emitDebug("worker", message, level, resource); +} + +async function emitDebug(scope, message, level = "info", resource = undefined) { + const entry = { + type: "rings-webview-debug", + at: new Date().toISOString(), + scope, + message, + level, + }; + if (resource) { + entry.resource = resource; + } + debugHistory.push(entry); + if (debugHistory.length > 200) { + debugHistory.splice(0, debugHistory.length - 200); + } + const clients = await debugClients(); + await Promise.all( + clients.map((client) => client.postMessage(entry)), + ); +} + +async function debugClients() { + const clientsById = new Map(); + for (const clientId of debugClientIds) { + const client = await self.clients.get(clientId); + if (client) { + clientsById.set(client.id, client); + } else { + debugClientIds.delete(clientId); + } + } + const candidates = await self.clients.matchAll({ + type: "window", + includeUncontrolled: true, + }); + for (const client of candidates) { + if (isWebviewPopup(client.url)) { + debugClientIds.add(client.id); + clientsById.set(client.id, client); + } + } + return [...clientsById.values()]; +} + +function isWebviewPopup(url) { + try { + const parsed = new URL(url); + return parsed.hash.startsWith("#webview") || parsed.pathname.startsWith(gatewayPrefix); + } catch (_error) { + return false; + } +} + +function requestedTarget(url) { + const path = new URL(url).pathname; + const encoded = path.slice(gatewayPrefix.length); + try { + return encoded ? decodeURIComponent(encoded) : url; + } catch (_error) { + return url; + } +} + +async function gatewayHostClient() { + const registered = await registeredGatewayHostClient(); + if (registered) { + return registered; + } + const candidateClients = await self.clients.matchAll({ + type: "window", + includeUncontrolled: true, + }); + if (candidateClients.length === 0) { + return undefined; + } + const discovered = await Promise.all( + candidateClients.map(async (client) => ({ + client, + ready: await queryGatewayHost(client), + })), + ); + const host = discovered.find(({ ready }) => ready)?.client; + if (!host) { + return undefined; + } + updateGatewayHost(host.id); + return host; +} + +async function registeredGatewayHostClient() { + if (!gatewayHostClientId) { + return undefined; + } + const client = await self.clients.get(gatewayHostClientId); + if (!client) { + gatewayHostClientId = null; + } + return client; +} + +function updateGatewayHost(clientId) { + gatewayHostClientId = clientId; +} + +function queryGatewayHost(client) { + return new Promise((resolve) => { + const channel = new MessageChannel(); + const timeout = globalThis.setTimeout(() => { + channel.port1.close(); + resolve(false); + }, 500); + channel.port1.onmessage = (event) => { + globalThis.clearTimeout(timeout); + channel.port1.close(); + resolve(Boolean(event.data?.ready)); + }; + client.postMessage( + { type: "rings-webview-gateway-host-query" }, + [channel.port2], + ); + }); +} + +async function serializeRequest(event) { + const request = event.request; + const sourceTarget = await sourceTargetForClient(event.clientId); + const body = request.method === "GET" || request.method === "HEAD" + ? undefined + : await request.clone().arrayBuffer(); + return { + requested: request.url, + sourceTarget, + method: request.method, + credentials: request.credentials, + headers: [...request.headers] + .filter(([name]) => name.toLowerCase() !== "x-rings-webview-kind") + .map(([name, value]) => ({ name, value })), + body, + kind: requestKind(request), + }; +} + +async function sourceTargetForClient(clientId) { + if (!clientId) { + return undefined; + } + const client = await self.clients.get(clientId); + if (!client) { + return undefined; + } + const url = new URL(client.url); + if (url.origin !== self.location.origin || !url.pathname.startsWith(gatewayPrefix)) { + return undefined; + } + const encoded = url.pathname.slice(gatewayPrefix.length); + if (!encoded) { + return undefined; + } + try { + return decodeURIComponent(encoded); + } catch (_error) { + return undefined; + } +} + +function requestKind(request) { + const taggedKind = request.headers.get("x-rings-webview-kind"); + if (taggedKind === "fetch" || taggedKind === "xhr" || taggedKind === "navigation") { + return taggedKind; + } + if ( + request.mode === "navigate" + || request.destination === "document" + || request.destination === "iframe" + ) { + return "navigation"; + } + return "subresource"; +} + +function requestGatewayResponse(host, request) { + return new Promise((resolve) => { + const channel = new MessageChannel(); + const timeout = globalThis.setTimeout(() => { + channel.port1.close(); + resolve({ ok: false, status: 504, error: "local Rings node gateway timed out" }); + }, requestTimeoutMs); + channel.port1.onmessage = (event) => { + globalThis.clearTimeout(timeout); + channel.port1.close(); + resolve(event.data); + }; + host.postMessage( + { type: "rings-webview-gateway-request", request }, + [channel.port2], + ); + }); +} + +function gatewayFailure(status, message) { + return new Response(gatewayFailureDocument(status, message), { + status, + headers: { + "content-type": "text/html; charset=utf-8", + "cache-control": "no-store", + "referrer-policy": "no-referrer", + }, + }); +} + +function gatewayFailureDocument(status, message) { + const detail = JSON.stringify(String(message)).replace(/ + + +Rings gateway failure ${status} + +
+

Rings gateway failure ${status}

+ 

+  
Gateway events

+

+
+`;
+}
diff --git a/frontend/src/app.rs b/frontend/src/app.rs
index 17467c0fe..3192c0d5b 100644
--- a/frontend/src/app.rs
+++ b/frontend/src/app.rs
@@ -34,6 +34,8 @@ use crate::node::PeerView;
 use crate::styles;
 use crate::wallet::WalletAccount;
 use crate::wallet::WalletKind;
+use crate::webview;
+use crate::webview_ui;
 use crate::workbench;
 
 mod actions;
@@ -72,6 +74,7 @@ struct NodeState {
     storage_name: UseStateHandle,
     peers: UseStateHandle>,
     seed_url: UseStateHandle,
+    webview_ready: UseStateHandle,
 }
 
 struct LinkState {
@@ -184,6 +187,7 @@ fn use_node_state() -> NodeState {
             )
             .unwrap_or_default()
         }),
+        webview_ready: use_state(|| false),
     }
 }
 
@@ -488,6 +492,9 @@ fn use_shell_history(
 
 fn render_app(ctx: AppRenderContext<'_>) -> Html {
     let effective_page = effective_shell_page(ctx.shell, ctx.extension_mode);
+    if effective_page == ShellPage::Webview {
+        return html! {  };
+    }
     let navigate_page = navigate_page_callback(ctx.shell);
     let header = controls::app_header(effective_page, navigate_page.clone(), !ctx.extension_mode);
     if effective_page == ShellPage::Guide {
@@ -553,10 +560,23 @@ fn render_console_shell(ctx: AppRenderContext<'_>, header: Html) -> Html {
         true,
         ctx.extension_mode,
     );
+    let webview_control = (!ctx.extension_mode).then(|| {
+        let status = ctx.node.status.clone();
+        let ready = *ctx.node.webview_ready;
+        controls::webview_control(
+            ready,
+            Callback::from(move |_| {
+                if let Err(error) = webview::open_webview_popup() {
+                    status.set(format!("open webview: {error}"));
+                }
+            }),
+        )
+    });
     let control_sidebar = controls::control_sidebar(
         control_view(ctx.node),
         ctx.launch_actions,
         workbench_control,
+        webview_control,
         *ctx.shell.active_dialog,
         dialog_actions,
         ctx.shell.control_sidebar_collapsed.clone(),
@@ -725,6 +745,10 @@ fn routed_shell_route() -> Option {
             page: ShellPage::Console,
             dialog: ActiveDialog::None,
         }),
+        "webview" => Some(ShellRoute {
+            page: ShellPage::Webview,
+            dialog: ActiveDialog::None,
+        }),
         "node/settings" | "settings" => Some(ShellRoute {
             page: ShellPage::Console,
             dialog: ActiveDialog::Settings,
@@ -823,6 +847,7 @@ fn shell_route_fragment(page: ShellPage, dialog: ActiveDialog) -> Option<&'stati
     match (page, dialog) {
         (ShellPage::Guide, ActiveDialog::None) => None,
         (ShellPage::Console, ActiveDialog::None) => Some("node"),
+        (ShellPage::Webview, ActiveDialog::None) => Some("webview"),
         (_, ActiveDialog::Settings) => Some("node/settings"),
         (_, ActiveDialog::Workbench) => Some("node/workbench"),
     }
diff --git a/frontend/src/app/actions.rs b/frontend/src/app/actions.rs
index 83e8f66d1..248f8e2b7 100644
--- a/frontend/src/app/actions.rs
+++ b/frontend/src/app/actions.rs
@@ -27,6 +27,7 @@ use crate::peer_sync;
 use crate::wallet;
 use crate::wallet::WalletAccount;
 use crate::wallet::WalletKind;
+use crate::webview;
 
 #[derive(Clone)]
 struct StartAction {
@@ -46,6 +47,7 @@ struct StartAction {
     seed_url: UseStateHandle,
     custom_events: UseStateHandle>,
     active_dialog: UseStateHandle,
+    webview_ready: UseStateHandle,
 }
 
 struct StartRequest {
@@ -72,6 +74,7 @@ struct DisconnectAction {
     remote_answer: UseStateHandle,
     link_dialog_open: UseStateHandle,
     active_dialog: UseStateHandle,
+    webview_ready: UseStateHandle,
 }
 
 pub(super) fn launch_actions(
@@ -96,6 +99,7 @@ pub(super) fn launch_actions(
         stabilize_interval: node.stabilize_interval.clone(),
         storage_name: node.storage_name.clone(),
         seed_url: node.seed_url.clone(),
+        webview_ready: node.webview_ready.clone(),
         custom_events: custom_state.events.clone(),
         active_dialog: shell.active_dialog.clone(),
     }
@@ -114,6 +118,7 @@ pub(super) fn launch_actions(
         remote_answer: link.remote_answer.clone(),
         link_dialog_open: link.link_dialog_open.clone(),
         active_dialog: shell.active_dialog.clone(),
+        webview_ready: node.webview_ready.clone(),
     }
     .callback();
     LaunchActions {
@@ -130,6 +135,7 @@ impl StartAction {
             let request = action.request();
             let start_token = action.generation.bump();
             action.node_starting.set(true);
+            action.webview_ready.set(false);
             action
                 .status
                 .set(format!("connecting {}", request.kind.label()));
@@ -292,6 +298,15 @@ impl StartAction {
         self.did.set(my_did);
         self.wallet_account.set(Some(account));
         *self.node_ref.borrow_mut() = Some(built.clone());
+        let webview_ready = match webview::install_browser_gateway(built.webview.clone()) {
+            Ok(true) => webview::register_browser_gateway().await.is_ok(),
+            Ok(false) => false,
+            Err(error) => {
+                self.status.set(format!("webview gateway: {error}"));
+                false
+            }
+        };
+        self.webview_ready.set(webview_ready);
         super::clear_shell_dialog_route();
         self.active_dialog.set(ActiveDialog::None);
         self.node_starting.set(false);
@@ -432,11 +447,13 @@ impl DisconnectAction {
         let was_starting = *self.node_starting;
         let cleanup_token = self.generation.bump();
         let Some(node) = self.node_ref.borrow_mut().take() else {
+            webview::clear_browser_gateway();
             self.node_starting.set(false);
             self.status.set(offline_disconnect_message(was_starting));
             return;
         };
         let provider = node.provider.clone();
+        webview::clear_browser_gateway();
         self.clear_session();
         self.status.set("node disconnected".to_string());
         let status = self.status.clone();
@@ -453,6 +470,7 @@ impl DisconnectAction {
         self.did.set(String::new());
         self.wallet_account.set(None);
         self.node_starting.set(false);
+        self.webview_ready.set(false);
         self.peers.set(Vec::new());
         self.generated_offer.set(String::new());
         self.remote_offer.set(String::new());
diff --git a/frontend/src/browser_api.rs b/frontend/src/browser_api.rs
index 140e05b60..e1cc77e72 100644
--- a/frontend/src/browser_api.rs
+++ b/frontend/src/browser_api.rs
@@ -69,6 +69,36 @@ pub(crate) async fn open_debug_url(url: &str) -> Result<(), String> {
     }
 }
 
+/// Open the application-owned WebView shell in a named browser popup.
+///
+/// The caller supplies no remote target here: remote addresses are entered only inside the
+/// controlled shell and become `/webview/` paths before an iframe receives them.
+pub(crate) fn open_webview_popup() -> Result<(), String> {
+    let window = web_sys::window().ok_or_else(|| "window unavailable".to_string())?;
+    let location = window.location();
+    let mut url = location.origin().map_err(js_error_label)?;
+    url.push_str(location.pathname().map_err(js_error_label)?.as_str());
+    if let Ok(search) = location.search() {
+        url.push_str(search.as_str());
+    }
+    url.push_str("#webview");
+
+    let window_value: JsValue = window.into();
+    let open = js_method(&window_value, "open")?;
+    let opened = open
+        .call3(
+            &window_value,
+            &JsValue::from_str(url.as_str()),
+            &JsValue::from_str("rings-webview"),
+            &JsValue::from_str("popup=yes,width=1280,height=860,noopener"),
+        )
+        .map_err(js_error_label)?;
+    if opened.is_null() || opened.is_undefined() {
+        return Err("browser blocked the WebView popup".to_string());
+    }
+    Ok(())
+}
+
 async fn open_debug_url_with_extension_tabs(namespace: &str, url: &str) -> Result<(), String> {
     let extension_api =
         Reflect::get(&js_sys::global(), &JsValue::from_str(namespace)).map_err(js_error_label)?;
diff --git a/frontend/src/controls.rs b/frontend/src/controls.rs
index 62f64c6bd..0493107ee 100644
--- a/frontend/src/controls.rs
+++ b/frontend/src/controls.rs
@@ -25,6 +25,7 @@ const FIREFOX_EXTENSION_MANAGER_URL: &str = "about:debugging#/runtime/this-firef
 pub(crate) enum ShellPage {
     Guide,
     Console,
+    Webview,
 }
 
 impl ShellPage {
@@ -32,6 +33,7 @@ impl ShellPage {
         match self {
             Self::Guide => "Home",
             Self::Console => "Node",
+            Self::Webview => "WebView",
         }
     }
 }
@@ -71,6 +73,7 @@ enum UiIcon {
     Power,
     PowerOff,
     Terminal,
+    Globe,
     Sliders,
     PanelOpen,
     PanelClose,
@@ -98,6 +101,14 @@ fn ui_icon(icon: UiIcon) -> Html {
                 
             
         },
+        UiIcon::Globe => html! {
+            <>
+                
+                
+                
+                
+            
+        },
         UiIcon::Sliders => html! {
             <>
                 
@@ -174,6 +185,31 @@ pub(crate) struct SessionView<'a> {
     pub(crate) peers: &'a UseStateHandle>,
 }
 
+/// Render the Node-only entry point for the controlled browser WebView.
+pub(crate) fn webview_control(ready: bool, on_open: Callback) -> Html {
+    let title = if ready {
+        "Open WebView"
+    } else {
+        "WebView is available after the local node gateway is ready"
+    };
+    html! {
+        
+    }
+}
+
 struct SettingsDialogView<'a> {
     wallet_kind: WalletKind,
     actions: LaunchActions,
diff --git a/frontend/src/controls/sidebar.rs b/frontend/src/controls/sidebar.rs
index 66318c5af..bafb7a99e 100644
--- a/frontend/src/controls/sidebar.rs
+++ b/frontend/src/controls/sidebar.rs
@@ -51,6 +51,7 @@ pub(crate) fn control_sidebar(
     view: ControlView<'_>,
     actions: LaunchActions,
     workbench_control: Html,
+    webview_control: Option,
     active_dialog: ActiveDialog,
     dialog_actions: DialogActions,
     collapsed: UseStateHandle,
@@ -74,7 +75,14 @@ pub(crate) fn control_sidebar(
                 { sidebar_toggle_button(*collapsed, toggle_sidebar) }
             }
             if extension_mode || !*collapsed {
-                { sidebar_content(&derived, &actions, workbench_control, open_settings_dialog, on_copy_did.clone()) }
+                { sidebar_content(
+                    &derived,
+                    &actions,
+                    workbench_control,
+                    webview_control,
+                    open_settings_dialog,
+                    on_copy_did.clone(),
+                ) }
             }
             { settings_dialog_if_open(active_dialog, &view, actions, &derived, on_copy_did, close_settings_dialog) }
         
@@ -180,15 +188,17 @@ fn sidebar_content(
     derived: &ControlSidebarDerived,
     actions: &LaunchActions,
     workbench_control: Html,
+    webview_control: Option,
     open_settings_dialog: Callback,
     on_copy_did: Callback,
 ) -> Html {
     html! {
         

-            { command_panel_header() }
+            { command_panel_header(webview_control.is_some()) }
             

                 { node_action_button(derived, actions) }
                 { workbench_control }
+                { webview_control }
                 { settings_button(open_settings_dialog) }
             

             { rail_telemetry(derived, on_copy_did) }
@@ -196,14 +206,14 @@ fn sidebar_content(
     }
 }
 
-fn command_panel_header() -> Html {
+fn command_panel_header(has_webview: bool) -> Html {
     html! {
         

             

                 
{ "Control" }

                 
{ "Command deck" }

             

-            { "03" }
+            { if has_webview { "04" } else { "03" } }
         

     }
 }
diff --git a/frontend/src/lib.rs b/frontend/src/lib.rs
index c0f8e68e7..1fdff17d8 100644
--- a/frontend/src/lib.rs
+++ b/frontend/src/lib.rs
@@ -24,8 +24,13 @@ mod proof;
 mod styles;
 mod topology;
 mod wallet;
+pub mod webview;
+mod webview_ui;
 mod workbench;
 
+/// Browser Rings node API.
+pub use node::DemoNode;
+
 /// Mount the Yew app.
 pub fn run() {
     if extension::is_offscreen_document() {
diff --git a/frontend/src/node.rs b/frontend/src/node.rs
index bc5ba9d95..30f843e36 100644
--- a/frontend/src/node.rs
+++ b/frontend/src/node.rs
@@ -14,11 +14,14 @@ use rings_node::prelude::rings_core::storage::idb::IdbStorage;
 use rings_node::processor::ProcessorBuilder;
 use rings_node::processor::ProcessorConfig;
 use rings_node::provider::Provider;
+use rings_webview::Result as WebviewResult;
+use rings_webview::WebviewError;
 use wasm_bindgen::JsValue;
 use wasm_bindgen_futures::spawn_local;
 use wasm_bindgen_futures::JsFuture;
 
 use crate::wallet::WalletAccount;
+use crate::webview::WebviewNode;
 
 /// A browser Rings node with all demo protocols installed.
 #[derive(Clone)]
@@ -27,6 +30,8 @@ pub struct DemoNode {
     pub provider: Arc,
     /// SNARK behaviour and task store.
     pub snark: SNARKBehaviour,
+    /// Controlled webview gateway attached to this browser node when its host origin is HTTP(S).
+    pub webview: Option,
     listen_abort: AbortHandle,
 }
 
@@ -35,6 +40,16 @@ impl DemoNode {
     pub fn stop(&self) {
         self.listen_abort.abort();
     }
+
+    /// Return the controlled webview gateway attached to this browser node.
+    pub fn webview(&self) -> WebviewResult {
+        self.webview.clone().ok_or_else(|| {
+            WebviewError::Browser(
+                "webview requires an HTTP(S) frontend origin; it is unavailable in this host"
+                    .to_string(),
+            )
+        })
+    }
 }
 
 /// Peer entry rendered in the topology panel.
@@ -133,6 +148,8 @@ pub async fn build_node(
     snark
         .register(&provider)
         .map_err(|error| format!("register snark protocol: {error}"))?;
+    let webview = WebviewNode::for_current_window(provider.clone())
+        .map_err(|error| format!("initialize webview: {error}"))?;
 
     let (listen_abort, listen_registration) = AbortHandle::new_pair();
     spawn_local(async move {
@@ -142,6 +159,7 @@ pub async fn build_node(
     Ok(DemoNode {
         provider,
         snark,
+        webview,
         listen_abort,
     })
 }
diff --git a/frontend/src/onion.rs b/frontend/src/onion.rs
index f0aa3d04f..0749a3b43 100644
--- a/frontend/src/onion.rs
+++ b/frontend/src/onion.rs
@@ -70,8 +70,8 @@ pub(crate) struct OnionProxyResponse {
     pub(crate) status: u16,
     /// Response headers.
     pub(crate) headers: Vec<(String, String)>,
-    /// Lossy UTF-8 response body for the demo panel.
-    pub(crate) body: String,
+    /// Exact response body bytes returned by the onion exit.
+    pub(crate) body: Vec,
 }
 
 impl Default for OnionProxyOptions {
@@ -231,9 +231,14 @@ impl OnionProxyResponse {
             &JsValue::from_f64(f64::from(self.status)),
         )?;
         js_set(&object, "headers", &headers_js(&self.headers).into())?;
-        js_set(&object, "body", &body_js(self.body.as_bytes()).into())?;
+        js_set(&object, "body", &body_js(&self.body).into())?;
         Ok(object.into())
     }
+
+    /// Return a lossy UTF-8 representation for text-only UI output.
+    pub(crate) fn body_text(&self) -> String {
+        String::from_utf8_lossy(&self.body).into_owned()
+    }
 }
 
 /// Parse editable header lines from the WorkBench.
@@ -404,14 +409,14 @@ fn parse_route_exit_js(value: &JsValue) -> Result {
     js_string_field(value, "did")
 }
 
-fn parse_body_js(value: JsValue) -> Result {
+fn parse_body_js(value: JsValue) -> Result, String> {
     if let Some(body) = value.as_string() {
-        return Ok(body);
+        return Ok(body.into_bytes());
     }
     if let Ok(bytes) = value.clone().dyn_into::() {
         let mut body = vec![0; bytes.length() as usize];
         bytes.copy_to(body.as_mut_slice());
-        return Ok(String::from_utf8_lossy(&body).into_owned());
+        return Ok(body);
     }
     let array = Array::from(&value);
     let mut body = Vec::new();
@@ -424,7 +429,7 @@ fn parse_body_js(value: JsValue) -> Result {
         }
         body.push(byte as u8);
     }
-    Ok(String::from_utf8_lossy(&body).into_owned())
+    Ok(body)
 }
 
 fn headers_js(headers: &[(String, String)]) -> Array {
@@ -518,7 +523,22 @@ mod tests {
         let response = super::OnionProxyResponse {
             status: 200,
             headers: vec![("content-type".to_string(), "text/plain".to_string())],
-            body: "hello through onion".to_string(),
+            body: b"hello through onion".to_vec(),
+        };
+
+        let parsed = response
+            .to_js()
+            .and_then(|value| super::OnionProxyResponse::from_js(&value));
+
+        assert_eq!(parsed, Ok(response));
+    }
+
+    #[wasm_bindgen_test]
+    fn response_roundtrip_preserves_binary_body_bytes() {
+        let response = super::OnionProxyResponse {
+            status: 200,
+            headers: vec![("content-type".to_string(), "image/png".to_string())],
+            body: vec![0xff, 0x00, 0x80],
         };
 
         let parsed = response
@@ -538,8 +558,8 @@ mod tests {
             });
         assert_eq!(set_response, Ok(()));
 
-        let parsed =
-            super::OnionProxyResponse::from_js(&response.into()).map(|response| response.body);
+        let parsed = super::OnionProxyResponse::from_js(&response.into())
+            .map(|response| response.body_text());
 
         assert_eq!(parsed, Ok("hello through onion".to_string()));
     }
diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css
index 8b0e45843..faa607566 100644
--- a/frontend/src/styles/components.css
+++ b/frontend/src/styles/components.css
@@ -43,8 +43,14 @@
 }
 
 .debug-action-row button {
+  min-width: 0;
   min-height: 30px;
   padding: 5px 8px;
+  font-size: 0.7rem;
+  font-weight: 700;
+  line-height: 1.15;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 .field span,
@@ -567,6 +573,334 @@ code {
   color: var(--amber);
 }
 
+.webview-shell {
+  display: grid;
+  width: 100vw;
+  height: 100dvh;
+  min-height: 0;
+  grid-template-rows: auto minmax(0, 1fr);
+  background: #f3ead8;
+  color: #111827;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  overflow: hidden;
+}
+
+.webview-shell.debug-open {
+  grid-template-rows: auto minmax(0, 1fr) minmax(180px, 30dvh);
+}
+
+.webview-toolbar {
+  display: grid;
+  min-width: 0;
+  grid-template-columns: auto minmax(260px, 1fr) minmax(150px, 0.36fr) auto;
+  gap: 8px;
+  align-items: center;
+  padding: 9px 12px;
+  border-bottom: 1px solid #ddccb0;
+  background: #fffaf0;
+  box-shadow: 0 1px 2px rgba(112, 84, 48, 0.08);
+}
+
+.webview-brand,
+.webview-controls,
+.webview-address-form {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+}
+
+.webview-brand {
+  min-width: 150px;
+  gap: 7px;
+  color: #111827;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 0.82rem;
+  font-weight: 800;
+  white-space: nowrap;
+}
+
+.webview-brand img {
+  width: 26px;
+  height: 26px;
+  padding: 3px;
+  border-radius: 6px;
+  background: #111827;
+}
+
+.webview-controls {
+  gap: 5px;
+}
+
+.webview-icon-button,
+.webview-go-button {
+  display: grid;
+  width: 32px;
+  height: 32px;
+  min-width: 32px;
+  place-items: center;
+  padding: 0;
+  border: 1px solid #d9c5a6;
+  border-radius: 6px;
+  background: #fffaf0;
+  color: #374151;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 0.92rem;
+  font-weight: 800;
+  line-height: 1;
+}
+
+.webview-icon-button:hover:not(:disabled),
+.webview-go-button:hover {
+  border-color: #111827;
+  background: #111827;
+  color: #fff;
+}
+
+.webview-icon-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.42;
+}
+
+.webview-address-form {
+  display: grid;
+  min-width: 0;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 6px;
+}
+
+.webview-address-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+.webview-address {
+  width: 100%;
+  min-width: 0;
+  height: 32px;
+  padding: 5px 9px;
+  border: 1px solid #d9c5a6;
+  border-radius: 6px;
+  background: #fffdf8;
+  color: #111827;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 0.78rem;
+  line-height: 1.1;
+}
+
+.webview-address:focus {
+  border-color: #b42318;
+  outline: 3px solid rgba(180, 35, 24, 0.12);
+}
+
+.webview-status {
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  color: #6f6252;
+  font-size: 0.7rem;
+  font-weight: 650;
+  line-height: 1.2;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.webview-close-button {
+  color: #b42318;
+}
+
+.webview-debug-button,
+.webview-debug-clear,
+.webview-debug-tab {
+  min-height: 32px;
+  padding: 5px 9px;
+  border: 1px solid #d9c5a6;
+  border-radius: 6px;
+  background: #fffaf0;
+  color: #374151;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 0.68rem;
+  font-weight: 800;
+  line-height: 1;
+}
+
+.webview-debug-button:hover,
+.webview-debug-button.active,
+.webview-debug-clear:hover,
+.webview-debug-tab:hover,
+.webview-debug-tab.active {
+  border-color: #111827;
+  background: #111827;
+  color: #fff;
+}
+
+.webview-viewport {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+  background: #fffaf0;
+}
+
+.webview-frame {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  background: #fff;
+}
+
+.webview-debug-panel {
+  display: grid;
+  min-width: 0;
+  min-height: 0;
+  grid-template-rows: auto minmax(0, 1fr);
+  border-top: 1px solid #ddccb0;
+  background: #fffaf0;
+}
+
+.webview-debug-header {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 12px;
+  border-bottom: 1px solid #eadcc5;
+}
+
+.webview-debug-header .eyebrow {
+  margin: 0 0 1px;
+  color: #b42318;
+  font-size: 0.58rem;
+}
+
+.webview-debug-header h2 {
+  margin: 0;
+  color: #111827;
+  font-size: 0.82rem;
+  line-height: 1.1;
+}
+
+.webview-debug-tabs {
+  display: flex;
+  gap: 4px;
+  margin-left: auto;
+}
+
+.webview-debug-tab {
+  min-height: 26px;
+  padding: 4px 7px;
+  font-size: 0.62rem;
+}
+
+.webview-debug-log,
+.webview-debug-network {
+  min-width: 0;
+  min-height: 0;
+  padding: 7px 12px 10px;
+  overflow: auto;
+}
+
+.webview-debug-entry,
+.webview-debug-empty {
+  display: grid;
+  min-width: 0;
+  margin: 0;
+  padding: 3px 0;
+  grid-template-columns: 86px 66px minmax(0, 1fr);
+  gap: 8px;
+  border-bottom: 1px solid rgba(221, 204, 176, 0.48);
+  color: #4b5563;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 0.68rem;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+
+.webview-debug-entry time,
+.webview-debug-scope {
+  color: #82725f;
+}
+
+.webview-debug-scope {
+  font-weight: 800;
+  text-transform: uppercase;
+}
+
+.webview-debug-entry.error {
+  color: #b42318;
+}
+
+.webview-debug-empty {
+  display: block;
+  border-bottom: 0;
+  color: #82725f;
+}
+
+.webview-resource-row {
+  display: grid;
+  min-width: 710px;
+  padding: 4px 0;
+  grid-template-columns: 54px 62px 100px 92px minmax(260px, 1fr) 72px;
+  gap: 8px;
+  border-bottom: 1px solid rgba(221, 204, 176, 0.48);
+  color: #4b5563;
+  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+  font-size: 0.67rem;
+  line-height: 1.35;
+}
+
+.webview-resource-heading {
+  position: sticky;
+  top: -7px;
+  z-index: 1;
+  padding-top: 5px;
+  background: #fffaf0;
+  color: #82725f;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+
+.webview-resource-target {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.webview-resource-row.resource-failed {
+  color: #b42318;
+}
+
+.webview-resource-row.resource-completed span:nth-child(2) {
+  color: #247556;
+  font-weight: 800;
+}
+
+.webview-empty-state {
+  display: grid;
+  width: min(460px, calc(100% - 32px));
+  gap: 7px;
+  margin: 12vh auto 0;
+  padding: 18px;
+  border: 1px solid #ddccb0;
+  border-radius: 8px;
+  background: #fffaf0;
+  box-shadow: 0 1px 2px rgba(112, 84, 48, 0.08);
+}
+
+.webview-empty-state strong {
+  color: #111827;
+  font-size: 0.92rem;
+}
+
+.webview-empty-state span {
+  color: #6f6252;
+  font-size: 0.78rem;
+  line-height: 1.45;
+}
+
 .rail-telemetry {
   display: grid;
   min-height: 0;
diff --git a/frontend/src/styles/dialogs.css b/frontend/src/styles/dialogs.css
index a4362f453..090e96d33 100644
--- a/frontend/src/styles/dialogs.css
+++ b/frontend/src/styles/dialogs.css
@@ -16,14 +16,17 @@
   border: 0;
   border-radius: 0;
   padding: 0;
-  background:
-    linear-gradient(90deg, rgba(0, 229, 255, 0.06) 1px, transparent 1px),
-    linear-gradient(180deg, rgba(84, 255, 208, 0.045) 1px, transparent 1px),
-    rgba(0, 0, 0, 0.72);
-  background-size: 32px 32px, 32px 32px, auto;
+  background: rgba(17, 24, 39, 0.38);
   box-shadow: none;
 }
 
+.dialog-backdrop:hover,
+.dialog-backdrop:focus-visible {
+  background: rgba(17, 24, 39, 0.38);
+  border-color: transparent;
+  color: transparent;
+}
+
 .link-dialog {
   position: relative;
   z-index: 1;
@@ -44,8 +47,9 @@
 }
 
 .setup-dialog {
-  width: min(820px, calc(100vw - 48px));
-  height: min(480px, calc(100dvh - 48px));
+  width: 1120px;
+  max-width: calc(100vw - 48px);
+  height: min(680px, calc(100dvh - 48px));
   grid-template-rows: auto minmax(0, 1fr);
 }
 
@@ -79,14 +83,14 @@
   display: grid;
   min-width: 0;
   min-height: 100%;
-  grid-template-columns: minmax(210px, 0.72fr) minmax(280px, 1fr) minmax(220px, 0.82fr);
+  grid-template-columns: minmax(200px, 0.82fr) minmax(320px, 1.45fr) minmax(200px, 0.88fr);
   grid-template-rows: minmax(min-content, 1fr);
-  gap: 10px;
+  gap: 14px;
   align-items: stretch;
 }
 
 .setup-grid .node-control-group {
-  padding: 0 10px;
+  padding: 0 14px;
   overflow: hidden;
 }
 
diff --git a/frontend/src/styles/features.css b/frontend/src/styles/features.css
index b4f4d94e8..0602387e5 100644
--- a/frontend/src/styles/features.css
+++ b/frontend/src/styles/features.css
@@ -160,17 +160,46 @@
 }
 
 .topology .ring-node {
-  transition:
-    filter 120ms ease,
-    stroke-width 120ms ease;
   vector-effect: non-scaling-stroke;
 }
 
 .topology .topology-node.active .ring-node {
-  filter: drop-shadow(0 0 13px rgba(126, 239, 255, 0.78));
   stroke-width: 3;
 }
 
+.topology .active-node-halo {
+  fill: none;
+  stroke: rgba(126, 239, 255, 0.88);
+  stroke-width: 1.8;
+  vector-effect: non-scaling-stroke;
+}
+
+.topology .active-node-pointer {
+  stroke: rgba(126, 239, 255, 0.56);
+  stroke-width: 1.2;
+  vector-effect: non-scaling-stroke;
+}
+
+.topology .active-node-frame {
+  fill: rgba(255, 250, 240, 0.96);
+  stroke: rgba(126, 239, 255, 0.7);
+  stroke-width: 1;
+  vector-effect: non-scaling-stroke;
+}
+
+.topology .active-node-caption {
+  fill: #b42318;
+  font-size: 0.34rem;
+  font-weight: 900;
+}
+
+.topology .active-node-id {
+  fill: #231f1a;
+  font-size: 0.52rem;
+  font-weight: 700;
+  letter-spacing: 0;
+}
+
 .topology .scan {
   fill: none;
   stroke: rgba(0, 229, 255, 0.38);
@@ -200,31 +229,6 @@
   fill: rgba(126, 239, 255, 0.94);
 }
 
-.topology .active-node-pointer {
-  stroke: rgba(126, 239, 255, 0.52);
-  stroke-dasharray: 3 5;
-  stroke-linecap: round;
-  vector-effect: non-scaling-stroke;
-}
-
-.topology .active-node-frame {
-  fill: rgba(2, 9, 13, 0.82);
-  stroke: rgba(126, 239, 255, 0.48);
-  stroke-width: 1;
-  vector-effect: non-scaling-stroke;
-}
-
-.topology .active-node-id {
-  fill: var(--ink-strong);
-  font-size: 0.52rem;
-  font-weight: 800;
-  letter-spacing: 0;
-  paint-order: stroke;
-  stroke: rgba(2, 7, 10, 0.96);
-  stroke-linejoin: round;
-  stroke-width: 4px;
-}
-
 .topology .node-label,
 .topology .peer-index {
   fill: var(--blue);
diff --git a/frontend/src/styles/responsive.css b/frontend/src/styles/responsive.css
index 4add811d9..54c1d01a4 100644
--- a/frontend/src/styles/responsive.css
+++ b/frontend/src/styles/responsive.css
@@ -353,6 +353,57 @@
   }
 }
 
+@media (max-width: 780px) {
+  .webview-toolbar {
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    grid-template-areas:
+      "brand brand close"
+      "address address address"
+      "status status status";
+  }
+
+  .webview-brand {
+    grid-area: brand;
+  }
+
+  .webview-address-form {
+    grid-area: address;
+  }
+
+  .webview-status {
+    grid-area: status;
+  }
+
+  .webview-close-button {
+    grid-area: close;
+    justify-self: end;
+  }
+
+}
+
+@media (max-width: 520px) {
+  .webview-shell.debug-open {
+    grid-template-rows: auto minmax(0, 1fr) minmax(170px, 34dvh);
+  }
+
+  .webview-debug-header {
+    flex-wrap: wrap;
+    gap: 7px;
+  }
+
+  .webview-debug-tabs {
+    order: 3;
+    width: 100%;
+    margin-left: 0;
+  }
+
+  .webview-debug-entry {
+    grid-template-columns: 74px 54px minmax(0, 1fr);
+    gap: 6px;
+    font-size: 0.62rem;
+  }
+}
+
 @media (max-width: 520px) {
   h1 {
     font-size: 1rem;
diff --git a/frontend/src/styles/theme/console.rs b/frontend/src/styles/theme/console.rs
index 995e1462a..a535a7f35 100644
--- a/frontend/src/styles/theme/console.rs
+++ b/frontend/src/styles/theme/console.rs
@@ -104,6 +104,11 @@ fn append_console_header(css: &mut String, theme: Theme) {
 fn append_console_stage(css: &mut String) {
     rule(css, ".topology-shell .node-band", &[("background", "linear-gradient(90deg, rgba(180, 35, 24, 0.06), transparent 42%, rgba(15, 118, 110, 0.05)), rgba(255, 250, 240, 0.9)")]);
     rule(css, ".topology-shell .network-stage", &[("background", "linear-gradient(90deg, rgba(243, 234, 216, 0.44) 0%, rgba(243, 234, 216, 0.28) 46%, rgba(243, 234, 216, 0.08) 100%), linear-gradient(180deg, rgba(255, 250, 240, 0.3), rgba(255, 246, 230, 0.18)), url(\"assets/images/rings-market-hero.png\") center / cover no-repeat"), ("backdrop-filter", "blur(2px)")]);
+    rule(
+        css,
+        ".topology-shell .network-stage:has(.modal-shell)",
+        &[("backdrop-filter", "none")],
+    );
     rule(
         css,
         ".topology-shell.extension-mode",
@@ -131,7 +136,7 @@ fn append_console_controls(css: &mut String, theme: Theme) {
 fn append_form_controls(css: &mut String, theme: Theme) {
     rule(
         css,
-        ".topology-shell button:not(.header-nav-button)",
+        ".topology-shell button:not(.header-nav-button):not(.dialog-backdrop)",
         &[
             ("border-color", theme.line_strong),
             ("border-radius", "8px"),
@@ -142,7 +147,7 @@ fn append_form_controls(css: &mut String, theme: Theme) {
     );
     rule(
         css,
-        ".topology-shell button:not(.header-nav-button):hover",
+        ".topology-shell button:not(.header-nav-button):not(.dialog-backdrop):hover",
         &[
             ("border-color", "#111827"),
             ("background", "#111827"),
diff --git a/frontend/src/styles/theme/dialogs.rs b/frontend/src/styles/theme/dialogs.rs
index 41f8a120d..77dbafffc 100644
--- a/frontend/src/styles/theme/dialogs.rs
+++ b/frontend/src/styles/theme/dialogs.rs
@@ -1,7 +1,15 @@
 use super::{rule, Theme};
 
 pub(super) fn append(css: &mut String, theme: Theme) {
-    rule(css, ".topology-shell .dialog-backdrop", &[("background", "linear-gradient(90deg, rgba(122, 87, 46, 0.05) 1px, transparent 1px), linear-gradient(180deg, rgba(122, 87, 46, 0.045) 1px, transparent 1px), rgba(49, 39, 24, 0.36)")]);
+    rule(
+        css,
+        ".topology-shell .dialog-backdrop,.topology-shell .dialog-backdrop:hover,.topology-shell .dialog-backdrop:focus-visible",
+        &[
+            ("background", "rgba(17, 24, 39, 0.38)"),
+            ("border-color", "transparent"),
+            ("color", "transparent"),
+        ],
+    );
     rule(
         css,
         ".topology-shell .link-dialog",
diff --git a/frontend/src/styles/theme/topology.rs b/frontend/src/styles/theme/topology.rs
index 64f029d52..035817a4c 100644
--- a/frontend/src/styles/theme/topology.rs
+++ b/frontend/src/styles/theme/topology.rs
@@ -5,7 +5,7 @@ pub(super) fn append(css: &mut String, theme: Theme) {
     rule(css, ".topology-shell .topology,.topology-shell .chord-topology", &[("border-color", theme.line_strong), ("background", "radial-gradient(circle at 50% 50%, rgba(180, 35, 24, 0.05), transparent 18%), linear-gradient(90deg, rgba(122, 87, 46, 0.055) 1px, transparent 1px), linear-gradient(180deg, rgba(122, 87, 46, 0.045) 1px, transparent 1px), rgba(255, 246, 230, 0.34)"), ("background-size", "auto, 28px 28px, 28px 28px, auto"), ("box-shadow", "inset 0 0 34px rgba(112, 84, 48, 0.04)")]);
     rule(
         css,
-        ".topology-shell .topology .ring-peer-label text,.topology-shell .topology .active-node-id",
+        ".topology-shell .topology .ring-peer-label text",
         &[("stroke", "rgba(255, 250, 240, 0.92)")],
     );
 }
@@ -74,6 +74,31 @@ fn append_warm_topology_rules(css: &mut String, selector: &str, theme: Theme) {
         &format!("{selector} .local-node"),
         &[("fill", "#f6d8d2"), ("stroke", "rgba(180, 35, 24, 0.72)")],
     );
+    rule(
+        css,
+        &format!("{selector} .active-node-halo"),
+        &[("stroke", theme.accent)],
+    );
+    rule(
+        css,
+        &format!("{selector} .active-node-pointer"),
+        &[("stroke", theme.accent)],
+    );
+    rule(
+        css,
+        &format!("{selector} .active-node-frame"),
+        &[("fill", theme.panel), ("stroke", theme.line_strong)],
+    );
+    rule(
+        css,
+        &format!("{selector} .active-node-caption"),
+        &[("fill", theme.accent)],
+    );
+    rule(
+        css,
+        &format!("{selector} .active-node-id"),
+        &[("fill", theme.ink)],
+    );
     rule(css, &format!("{selector} .node-label,{selector} .peer-index,{selector} .local-id,{selector} .successor-label text"), &[("fill", theme.accent)]);
     rule(css, &format!("{selector} .node-id,{selector} .empty-node-label,{selector} .topology-count,{selector} .ring-zero,{selector} .core-sub,{selector} .core-hint"), &[("fill", theme.muted)]);
     rule(
diff --git a/frontend/src/topology.rs b/frontend/src/topology.rs
index f86d775fd..9e1c672bb 100644
--- a/frontend/src/topology.rs
+++ b/frontend/src/topology.rs
@@ -9,6 +9,9 @@ use crate::node::PeerView;
 const CHORD_ID_BYTES: usize = 20;
 const CHORD_ID_BITS: usize = CHORD_ID_BYTES * 8;
 const CHORD_HEX_CHARS: usize = CHORD_ID_BYTES * 2;
+const ACTIVE_DID_LINE_LENGTH: usize = 21;
+const ACTIVE_DID_LABEL_WIDTH: f64 = 176.0;
+const ACTIVE_DID_LABEL_HEIGHT: f64 = 42.0;
 
 pub(crate) fn view(did: &str, peers: &[PeerView]) -> Html {
     html! {
@@ -26,25 +29,18 @@ struct TopologyProps {
 fn topology_component(props: &TopologyProps) -> Html {
     let layout = TopologyLayout::new();
     let model = TopologyModel::new(&props.did, &props.peers);
-    let hovered_node = use_state(|| None::);
     let pinned_node = use_state(|| None::);
-    let active_did = (*pinned_node).clone().or_else(|| (*hovered_node).clone());
     let render = TopologyRenderState {
         layout,
         node_count: model.nodes.len(),
         show_remote_labels: model.nodes.len() <= 6,
-        active_did,
-        hovered_node: hovered_node.clone(),
+        active_did: (*pinned_node).clone(),
         pinned_node: pinned_node.clone(),
     };
     let clear_pinned = {
         let pinned_node = pinned_node.clone();
         Callback::from(move |_| pinned_node.set(None))
     };
-    let clear_hovered = {
-        let hovered_node = hovered_node.clone();
-        Callback::from(move |_| hovered_node.set(None))
-    };
     html! {
          Html {
             role="img"
             aria-label="inferred Chord identifier ring"
             onclick={clear_pinned}
-            onmouseleave={clear_hovered}
         >
             { topology_orbits(layout) }
             { topology_caption(layout, model.nodes.len()) }
@@ -114,7 +109,6 @@ struct TopologyRenderState {
     node_count: usize,
     show_remote_labels: bool,
     active_did: Option,
-    hovered_node: UseStateHandle>,
     pinned_node: UseStateHandle>,
 }
 
@@ -267,6 +261,7 @@ fn topology_node_group(render: &TopologyRenderState, index: usize, node: &ChordN
         render.layout.radius + 31.0,
         node.angle,
     );
+    let radius = node_radius(node, render.node_count);
     let active = render
         .active_did
         .as_ref()
@@ -279,33 +274,18 @@ fn topology_node_group(render: &TopologyRenderState, index: usize, node: &ChordN
     html! {
         
-            { format!("{} {}", node.state, node.did) }
-            
+            { active.then(|| html! {
+                
+            }) }
+            
             { node_index_label(node, index, render.node_count, x, y) }
             { node_did_label(node, render.show_remote_labels, label_x, label_y) }
         
     }
 }
 
-fn node_hover_callback(
-    hovered_node: &UseStateHandle>,
-    did: String,
-) -> Callback {
-    let hovered_node = hovered_node.clone();
-    Callback::from(move |_| hovered_node.set(Some(did.clone())))
-}
-
-fn clear_node_hover_callback(
-    hovered_node: &UseStateHandle>,
-) -> Callback {
-    let hovered_node = hovered_node.clone();
-    Callback::from(move |_| hovered_node.set(None))
-}
-
 fn pin_node_callback(
     pinned_node: &UseStateHandle>,
     did: String,
@@ -313,10 +293,18 @@ fn pin_node_callback(
     let pinned_node = pinned_node.clone();
     Callback::from(move |event: MouseEvent| {
         event.stop_propagation();
-        pinned_node.set(Some(did.clone()));
+        pinned_node.set(toggle_pinned_did(&pinned_node, &did));
     })
 }
 
+fn toggle_pinned_did(current: &Option, did: &str) -> Option {
+    if current.as_deref() == Some(did) {
+        None
+    } else {
+        Some(did.to_string())
+    }
+}
+
 fn node_index_label(node: &ChordNode, index: usize, node_count: usize, x: f64, y: f64) -> Html {
     if !node.is_local && node_count > 16 {
         return html! {};
@@ -354,6 +342,7 @@ fn active_node_overlay(render: &TopologyRenderState, nodes: &[ChordNode]) -> Htm
                 render.layout.center_x,
                 render.layout.center_y,
                 render.layout.radius,
+                render.node_count,
             )
         })
         .unwrap_or_else(|| html! {})
@@ -507,12 +496,12 @@ fn node_class(node: &ChordNode) -> &'static str {
 
 fn node_radius(node: &ChordNode, node_count: usize) -> f64 {
     if node.is_local {
-        return if node_count > 16 { 24.0 } else { 28.0 };
+        return if node_count > 16 { 14.0 } else { 18.0 };
     }
     match node_count {
-        0..=8 => 21.0,
-        9..=16 => 15.0,
-        _ => 10.0,
+        0..=8 => 16.0,
+        9..=16 => 12.0,
+        _ => 8.0,
     }
 }
 
@@ -699,40 +688,69 @@ fn ring_peer_label(
     }
 }
 
-fn active_node_label(node: &ChordNode, center_x: f64, center_y: f64, radius: f64) -> Html {
+fn active_node_label(
+    node: &ChordNode,
+    center_x: f64,
+    center_y: f64,
+    radius: f64,
+    node_count: usize,
+) -> Html {
     let (node_x, node_y) = polar_point(center_x, center_y, radius, node.angle);
-    let (raw_x, raw_y) = polar_point(center_x, center_y, radius + 64.0, node.angle);
-    let readout_width = (node.did.chars().count() as f64 * 5.2 + 20.0).clamp(180.0, 340.0);
-    let readout_x =
-        (raw_x - readout_width / 2.0).clamp(18.0, center_x * 2.0 - readout_width - 18.0);
-    let label_x = readout_x + readout_width / 2.0;
-    let label_y = raw_y.clamp(66.0, center_y * 2.0 - 62.0);
+    let node_radius = node_radius(node, node_count);
+    let label_above = node_y >= center_y;
+    let label_x = (node_x - ACTIVE_DID_LABEL_WIDTH / 2.0)
+        .clamp(8.0, center_x * 2.0 - ACTIVE_DID_LABEL_WIDTH - 8.0);
+    let preferred_y = if label_above {
+        node_y - node_radius - ACTIVE_DID_LABEL_HEIGHT - 12.0
+    } else {
+        node_y + node_radius + 12.0
+    };
+    let label_y = preferred_y.clamp(8.0, center_y * 2.0 - ACTIVE_DID_LABEL_HEIGHT - 8.0);
+    let pointer_y = if label_above {
+        label_y + ACTIVE_DID_LABEL_HEIGHT
+    } else {
+        label_y
+    };
+    let pointer_start_y = if label_above {
+        node_y - node_radius
+    } else {
+        node_y + node_radius
+    };
+    let pointer_x = node_x.clamp(label_x + 10.0, label_x + ACTIVE_DID_LABEL_WIDTH - 10.0);
+    let (first_line, second_line) = split_did_label(&node.did);
 
     html! {
         
             
             
+            
+                { "DID" }
+            
             
-                { node.did.clone() }
+                { first_line }
             
+            { (!second_line.is_empty()).then(|| html! {
+                
+                    { second_line }
+                
+            }) }
         
     }
 }
@@ -791,6 +809,12 @@ pub(crate) fn short_did(did: &str) -> String {
     format!("{prefix}...{suffix}")
 }
 
+fn split_did_label(did: &str) -> (String, String) {
+    let mut chars = did.chars();
+    let first_line: String = chars.by_ref().take(ACTIVE_DID_LINE_LENGTH).collect();
+    (first_line, chars.collect())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -835,6 +859,25 @@ mod tests {
         assert!(did_identifier("").is_none());
     }
 
+    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
+    #[cfg_attr(not(target_arch = "wasm32"), test)]
+    fn did_readout_preserves_the_full_identifier() {
+        let did = "0x0123456789abcdef0123456789abcdef01234567";
+        let (first_line, second_line) = split_did_label(did);
+
+        assert_eq!(first_line.chars().count(), ACTIVE_DID_LINE_LENGTH);
+        assert_eq!(format!("{first_line}{second_line}"), did);
+    }
+
+    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
+    #[cfg_attr(not(target_arch = "wasm32"), test)]
+    fn selected_node_click_toggles_the_readout() {
+        let did = "0x0123456789abcdef";
+
+        assert_eq!(toggle_pinned_did(&None, did), Some(did.to_string()));
+        assert_eq!(toggle_pinned_did(&Some(did.to_string()), did), None,);
+    }
+
     #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
     #[cfg_attr(not(target_arch = "wasm32"), test)]
     fn successor_edges_form_wrapped_cycle() {
diff --git a/frontend/src/webview.rs b/frontend/src/webview.rs
new file mode 100644
index 000000000..6ae57e12f
--- /dev/null
+++ b/frontend/src/webview.rs
@@ -0,0 +1,932 @@
+//! Frontend host adapter for the reusable Rings webview gateway.
+
+use std::cell::RefCell;
+use std::collections::VecDeque;
+use std::rc::Rc;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use futures::channel::oneshot;
+use js_sys::Array;
+use js_sys::Object;
+use js_sys::Promise;
+use js_sys::Reflect;
+use js_sys::Uint8Array;
+use rings_node::provider::Provider;
+use rings_webview::browser::bootstrap_script;
+use rings_webview::ConcurrentWebviewGateway;
+use rings_webview::GatewayCredentials;
+use rings_webview::GatewayHeader;
+use rings_webview::GatewayPrefix;
+use rings_webview::GatewayRequest;
+use rings_webview::GatewayRequestKind;
+use rings_webview::GatewayResponse;
+use rings_webview::GatewayRoute;
+use rings_webview::GatewayRoutePolicy;
+use rings_webview::GatewayRouteRejection;
+use rings_webview::GatewayTransport;
+use rings_webview::Result as WebviewResult;
+use rings_webview::TargetUrl;
+use rings_webview::WebviewError;
+use url::Url;
+use wasm_bindgen::closure::Closure;
+use wasm_bindgen::JsValue;
+use wasm_bindgen_futures::future_to_promise;
+
+use crate::onion;
+
+const GATEWAY_PREFIX: &str = "/webview/";
+const MAX_CONCURRENT_GATEWAY_REQUESTS: usize = 6;
+const WEBVIEW_DEBUG_OVERLAY: &str = r#"
+(() => {
+  "use strict";
+
+  const marker = "__ringsWebviewDebugOverlay";
+  if (globalThis[marker]?.mounted?.()) return;
+
+  const state = {
+    entries: [],
+    log: undefined,
+    network: undefined,
+    panel: undefined,
+    view: "log",
+  };
+  const maxEntries = 200;
+
+  function resourceLine(resource) {
+    const status = resource.status == null ? "pending" : String(resource.status);
+    return `#${resource.requestId} ${status} ${resource.kind} ${resource.method} ${resource.phase} ${resource.target} ${resource.durationMs} ms`;
+  }
+
+  function render() {
+    const container = state.view === "network" ? state.network : state.log;
+    if (!container) return;
+    container.replaceChildren();
+    const entries = state.view === "network"
+      ? [...new Map(state.entries.filter((entry) => entry.resource).map((entry) => [entry.resource.requestId, entry])).values()]
+      : state.entries;
+    if (entries.length === 0) {
+      const empty = document.createElement("p");
+      empty.textContent = "Waiting for gateway activity";
+      container.append(empty);
+      return;
+    }
+    for (const entry of entries) {
+      const row = document.createElement("p");
+      row.className = entry.level === "error" ? "error" : "";
+      const time = String(entry.at || "").split("T")[1]?.replace("Z", "").slice(0, 12) || "";
+      row.textContent = state.view === "network" && entry.resource
+        ? resourceLine(entry.resource)
+        : `${time} [${entry.scope || "worker"}] ${entry.message || "unknown event"}`;
+      container.append(row);
+    }
+    container.scrollTop = container.scrollHeight;
+  }
+
+  function record(scope, message, level = "info", resource = undefined) {
+    const entry = { at: new Date().toISOString(), scope, message, level };
+    if (resource) entry.resource = resource;
+    state.entries.push(entry);
+    if (state.entries.length > maxEntries) state.entries.splice(0, state.entries.length - maxEntries);
+    render();
+  }
+
+  function selectView(view) {
+    state.view = view;
+    state.log.hidden = view !== "log";
+    state.network.hidden = view !== "network";
+    state.panel.querySelector("[data-view=log]").dataset.active = String(view === "log");
+    state.panel.querySelector("[data-view=network]").dataset.active = String(view === "network");
+    render();
+  }
+
+  function mount() {
+    const host = document.createElement("div");
+    host.id = "rings-webview-debug-overlay";
+    const root = host.attachShadow({ mode: "open" });
+    root.innerHTML = `
+      
+      
+      
+      `;
+    const panel = root.getElementById("panel");
+    const toggle = root.getElementById("toggle");
+    const back = root.getElementById("back");
+    const forward = root.getElementById("forward");
+    const reload = root.getElementById("reload");
+    const log = root.getElementById("log");
+    const network = root.getElementById("network");
+    if (!panel || !toggle || !back || !forward || !reload || !log || !network) return;
+    state.panel = panel;
+    state.log = log;
+    state.network = network;
+    toggle.addEventListener("click", () => {
+      panel.hidden = !panel.hidden;
+      toggle.setAttribute("aria-expanded", String(!panel.hidden));
+      if (!panel.hidden) render();
+    });
+    back.addEventListener("click", () => history.back());
+    forward.addEventListener("click", () => history.forward());
+    reload.addEventListener("click", () => location.reload());
+    root.querySelector("[data-view=log]").addEventListener("click", () => selectView("log"));
+    root.querySelector("[data-view=network]").addEventListener("click", () => selectView("network"));
+    root.getElementById("clear").addEventListener("click", () => {
+      state.entries.splice(0, state.entries.length);
+      render();
+    });
+    document.documentElement.append(host);
+    record("overlay", "Debug listener ready");
+  }
+
+  globalThis[marker] = {
+    record,
+    mounted: () => Boolean(document.getElementById("rings-webview-debug-overlay")),
+  };
+  navigator.serviceWorker?.addEventListener("message", (event) => {
+    const entry = event.data;
+    if (entry?.type === "rings-webview-debug") {
+      record(entry.scope || "worker", entry.message || "unknown event", entry.level || "info", entry.resource);
+    }
+  });
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", mount, { once: true });
+  else mount();
+  navigator.serviceWorker?.ready.then((registration) => {
+    const worker = navigator.serviceWorker.controller || registration.active;
+    worker?.postMessage({ type: "rings-webview-debug-register" });
+  }).catch(() => record("overlay", "Service Worker debug listener unavailable", "error"));
+})();
+"#;
+
+thread_local! {
+    static BROWSER_GATEWAY: RefCell> = RefCell::new(None);
+}
+
+struct BrowserGatewayBinding {
+    // This closure must outlive every Service Worker request sent to the active node.
+    _handler: Closure Promise>,
+}
+
+/// Encode an HTTP(S) address into the application-controlled gateway path.
+pub(crate) fn controlled_gateway_path(input: &str) -> Result {
+    let target = TargetUrl::parse(input).map_err(|error| error.to_string())?;
+    let prefix = GatewayPrefix::new(GATEWAY_PREFIX).map_err(|error| error.to_string())?;
+    Ok(prefix.encode(target.as_url()))
+}
+
+/// Open the local WebView popup without ever passing it a remote URL.
+pub(crate) fn open_webview_popup() -> Result<(), String> {
+    crate::browser_api::open_webview_popup()
+}
+
+/// Install the current node as the only Service Worker gateway executor.
+pub(crate) fn install_browser_gateway(gateway: Option) -> Result {
+    clear_browser_gateway();
+    let Some(gateway) = gateway else {
+        return Ok(false);
+    };
+    let handler = Closure::wrap(Box::new(move |request: JsValue| {
+        let gateway = gateway.clone();
+        future_to_promise(async move {
+            Ok::(dispatch_browser_request(gateway, request).await)
+        })
+    }) as Box Promise>);
+    let bridge = Object::new();
+    crate::browser_api::js_set(&bridge, "handle", handler.as_ref())?;
+    Reflect::set(
+        &js_sys::global(),
+        &JsValue::from_str("RingsWebviewGateway"),
+        bridge.as_ref(),
+    )
+    .map_err(crate::browser_api::js_error_label)?;
+    BROWSER_GATEWAY.with(|slot| {
+        *slot.borrow_mut() = Some(BrowserGatewayBinding { _handler: handler });
+    });
+    Ok(true)
+}
+
+/// Remove the browser host binding when the local node stops.
+pub(crate) fn clear_browser_gateway() {
+    BROWSER_GATEWAY.with(|slot| {
+        *slot.borrow_mut() = None;
+    });
+    let _deleted =
+        Reflect::delete_property(&js_sys::global(), &JsValue::from_str("RingsWebviewGateway"));
+}
+
+/// Register the active application page as the Service Worker's gateway host.
+pub(crate) async fn register_browser_gateway() -> Result<(), String> {
+    let bridge = crate::browser_api::js_global_prop("RingsWebviewHost")?;
+    let registered = crate::browser_api::js_call0(&bridge, "registerGatewayHost")?;
+    let _ready = crate::browser_api::await_js(registered).await?;
+    Ok(())
+}
+
+/// Ensure that the popup is controlled by the same-origin Service Worker.
+pub(crate) async fn prepare_browser_gateway() -> Result<(), String> {
+    let bridge = crate::browser_api::js_global_prop("RingsWebviewHost")?;
+    let ready = crate::browser_api::js_call0(&bridge, "ensureReady")?;
+    let _ready = crate::browser_api::await_js(ready).await?;
+    let debug = crate::browser_api::js_call0(&bridge, "enableDebug")?;
+    let _debug = crate::browser_api::await_js(debug).await?;
+    Ok(())
+}
+
+async fn dispatch_browser_request(gateway: WebviewNode, request: JsValue) -> JsValue {
+    let request = match browser_host_request(&request) {
+        Ok(request) => request,
+        Err(error) => return browser_failure(400, error),
+    };
+    match gateway.handle(request).await {
+        Ok(WebviewHostOutcome::Response(response)) => browser_response(response),
+        Ok(WebviewHostOutcome::Redirect(location)) => browser_redirect(location.as_str()),
+        Ok(WebviewHostOutcome::AllowControlled) => browser_failure(
+            404,
+            "controlled asset is outside the gateway route".to_string(),
+        ),
+        Ok(WebviewHostOutcome::Reject(reason)) => {
+            browser_failure(403, format!("rejected: {reason:?}"))
+        }
+        Err(WebviewError::Cors(error)) => browser_failure(403, format!("CORS rejected: {error}")),
+        Err(error) => browser_failure(502, format!("gateway transport: {error}")),
+    }
+}
+
+fn browser_host_request(value: &JsValue) -> Result {
+    let requested = parse_target(
+        crate::browser_api::js_string_field(value, "requested")?,
+        "requested",
+    )?;
+    let source_target = optional_target(value, "sourceTarget")?;
+    let method = crate::browser_api::js_string_field(value, "method")?;
+    let headers = browser_headers(value)?;
+    let body = browser_body(value)?;
+    let credentials = browser_credentials(value)?;
+    let request = match crate::browser_api::js_string_field(value, "kind")?.as_str() {
+        "navigation" => Ok(WebviewHostRequest::navigation_with_payload(
+            requested, method, headers, body,
+        )),
+        "subresource" => Ok(WebviewHostRequest::subresource(
+            requested,
+            source_target,
+            method,
+            headers,
+            body,
+        )),
+        "fetch" => Ok(WebviewHostRequest::fetch(
+            requested,
+            source_target.ok_or_else(|| "fetch has no controlled source".to_string())?,
+            method,
+            headers,
+            body,
+        )),
+        "xhr" => Ok(WebviewHostRequest::xhr(
+            requested,
+            source_target.ok_or_else(|| "xhr has no controlled source".to_string())?,
+            method,
+            headers,
+            body,
+        )),
+        kind => Err(format!("unknown gateway request kind {kind}")),
+    }?;
+    Ok(request.with_credentials(credentials))
+}
+
+fn browser_credentials(value: &JsValue) -> Result {
+    let credentials = crate::browser_api::js_prop(value, "credentials")?;
+    if credentials.is_null() || credentials.is_undefined() {
+        return Ok(GatewayCredentials::SameOrigin);
+    }
+    match credentials
+        .as_string()
+        .ok_or_else(|| "credentials must be a string".to_string())?
+        .as_str()
+    {
+        "omit" => Ok(GatewayCredentials::Omit),
+        "same-origin" => Ok(GatewayCredentials::SameOrigin),
+        "include" => Ok(GatewayCredentials::Include),
+        value => Err(format!("unsupported request credentials mode {value}")),
+    }
+}
+
+fn parse_target(value: String, field: &str) -> Result {
+    TargetUrl::parse(value.as_str()).map_err(|error| format!("{field}: {error}"))
+}
+
+fn optional_target(value: &JsValue, field: &str) -> Result, String> {
+    let target = crate::browser_api::js_prop(value, field)?;
+    if target.is_null() || target.is_undefined() {
+        return Ok(None);
+    }
+    target
+        .as_string()
+        .map(|target| parse_target(target, field))
+        .transpose()
+}
+
+fn browser_headers(value: &JsValue) -> Result, String> {
+    let headers = crate::browser_api::js_prop(value, "headers")?;
+    if headers.is_null() || headers.is_undefined() {
+        return Ok(Vec::new());
+    }
+    if !Array::is_array(&headers) {
+        return Err("headers is not an array".to_string());
+    }
+    let headers = Array::from(&headers);
+    let mut result = Vec::with_capacity(headers.length() as usize);
+    for index in 0..headers.length() {
+        let header = headers.get(index);
+        let name = crate::browser_api::js_string_field(&header, "name")?;
+        let value = crate::browser_api::js_string_field(&header, "value")?;
+        result.push(GatewayHeader::new(name, value).map_err(|error| error.to_string())?);
+    }
+    Ok(result)
+}
+
+fn browser_body(value: &JsValue) -> Result, String> {
+    let body = crate::browser_api::js_prop(value, "body")?;
+    if body.is_null() || body.is_undefined() {
+        return Ok(Vec::new());
+    }
+    Ok(Uint8Array::new(&body).to_vec())
+}
+
+fn browser_response(response: GatewayResponse) -> JsValue {
+    let value = Object::new();
+    let headers = Array::new();
+    for header in response.headers {
+        let entry = Object::new();
+        let _name = crate::browser_api::js_set(&entry, "name", &JsValue::from_str(&header.name));
+        let _value = crate::browser_api::js_set(&entry, "value", &JsValue::from_str(&header.value));
+        headers.push(entry.as_ref());
+    }
+    let _ok = crate::browser_api::js_set(&value, "ok", &JsValue::TRUE);
+    let _status = crate::browser_api::js_set(
+        &value,
+        "status",
+        &JsValue::from_f64(f64::from(response.status)),
+    );
+    let _headers = crate::browser_api::js_set(&value, "headers", headers.as_ref());
+    let body = Uint8Array::from(response.body.as_slice());
+    let _body = crate::browser_api::js_set(&value, "body", body.as_ref());
+    value.into()
+}
+
+fn browser_redirect(location: &str) -> JsValue {
+    let value = Object::new();
+    let headers = Array::new();
+    let header = Object::new();
+    let _name = crate::browser_api::js_set(&header, "name", &JsValue::from_str("Location"));
+    let _value = crate::browser_api::js_set(&header, "value", &JsValue::from_str(location));
+    headers.push(header.as_ref());
+    let _ok = crate::browser_api::js_set(&value, "ok", &JsValue::TRUE);
+    let _status = crate::browser_api::js_set(&value, "status", &JsValue::from_f64(302.0));
+    let _headers = crate::browser_api::js_set(&value, "headers", headers.as_ref());
+    value.into()
+}
+
+fn browser_failure(status: u16, error: String) -> JsValue {
+    let value = Object::new();
+    let _ok = crate::browser_api::js_set(&value, "ok", &JsValue::FALSE);
+    let _status =
+        crate::browser_api::js_set(&value, "status", &JsValue::from_f64(f64::from(status)));
+    let _error = crate::browser_api::js_set(&value, "error", &JsValue::from_str(error.as_str()));
+    value.into()
+}
+
+/// A browser request captured by the Rings-controlled WebView host.
+#[derive(Clone, Debug)]
+pub struct WebviewHostRequest {
+    requested: TargetUrl,
+    source_target: Option,
+    method: String,
+    headers: Vec,
+    body: Vec,
+    kind: GatewayRequestKind,
+    credentials: GatewayCredentials,
+}
+
+impl WebviewHostRequest {
+    /// Build a document navigation request.
+    pub fn navigation(requested: TargetUrl) -> Self {
+        Self::navigation_with_payload(requested, "GET", Vec::new(), Vec::new())
+    }
+
+    /// Build a document navigation request while preserving its HTTP payload.
+    pub fn navigation_with_payload(
+        requested: TargetUrl,
+        method: impl Into,
+        headers: Vec,
+        body: Vec,
+    ) -> Self {
+        Self::new(
+            requested,
+            None,
+            method,
+            headers,
+            body,
+            GatewayRequestKind::Navigation,
+        )
+    }
+
+    /// Build a static subresource request with its captured HTTP payload.
+    pub fn subresource(
+        requested: TargetUrl,
+        source_target: Option,
+        method: impl Into,
+        headers: Vec,
+        body: Vec,
+    ) -> Self {
+        Self::new(
+            requested,
+            source_target,
+            method,
+            headers,
+            body,
+            GatewayRequestKind::Subresource,
+        )
+    }
+
+    /// Build a runtime fetch request with the trusted initiating page target.
+    pub fn fetch(
+        requested: TargetUrl,
+        source_target: TargetUrl,
+        method: impl Into,
+        headers: Vec,
+        body: Vec,
+    ) -> Self {
+        Self::runtime(
+            requested,
+            source_target,
+            method,
+            headers,
+            body,
+            GatewayRequestKind::Fetch,
+        )
+    }
+
+    /// Build a runtime XHR request with the trusted initiating page target.
+    pub fn xhr(
+        requested: TargetUrl,
+        source_target: TargetUrl,
+        method: impl Into,
+        headers: Vec,
+        body: Vec,
+    ) -> Self {
+        Self::runtime(
+            requested,
+            source_target,
+            method,
+            headers,
+            body,
+            GatewayRequestKind::Xhr,
+        )
+    }
+
+    fn new(
+        requested: TargetUrl,
+        source_target: Option,
+        method: impl Into,
+        headers: Vec,
+        body: Vec,
+        kind: GatewayRequestKind,
+    ) -> Self {
+        Self {
+            requested,
+            source_target,
+            method: method.into(),
+            headers,
+            body,
+            kind,
+            credentials: GatewayCredentials::SameOrigin,
+        }
+    }
+
+    fn runtime(
+        requested: TargetUrl,
+        source_target: TargetUrl,
+        method: impl Into,
+        headers: Vec,
+        body: Vec,
+        kind: GatewayRequestKind,
+    ) -> Self {
+        Self::new(requested, Some(source_target), method, headers, body, kind)
+    }
+
+    fn with_credentials(mut self, credentials: GatewayCredentials) -> Self {
+        self.credentials = credentials;
+        self
+    }
+
+    fn into_gateway_request(self, target: TargetUrl) -> GatewayRequest {
+        let source_origin = matches!(
+            self.kind,
+            GatewayRequestKind::Fetch | GatewayRequestKind::Xhr
+        )
+        .then(|| {
+            self.source_target
+                .as_ref()
+                .map(|source| source.as_url().clone())
+        })
+        .flatten();
+        GatewayRequest {
+            target: target.into_url(),
+            method: self.method,
+            headers: self.headers,
+            body: self.body,
+            kind: self.kind,
+            source_origin,
+            credentials: self.credentials,
+        }
+    }
+}
+
+/// The only actions a controlled WebView host may take for one captured request.
+#[derive(Debug)]
+pub enum WebviewHostOutcome {
+    /// Load an application-owned asset without proxying it.
+    AllowControlled,
+    /// Navigate to this controlled gateway URL before any remote connection is opened.
+    Redirect(Url),
+    /// Return a response that was fetched through the node's onion proxy transport.
+    Response(GatewayResponse),
+    /// Reject the request without falling back to the requested remote URL.
+    Reject(GatewayRouteRejection),
+}
+
+/// Per-node WebView gateway state.
+///
+/// Clones share one cookie jar and a bounded number of concurrent onion requests.
+#[derive(Clone)]
+pub struct WebviewNode {
+    host: Rc>,
+}
+
+impl WebviewNode {
+    /// Attach a WebView gateway when the current page has an HTTP(S) controlled origin.
+    pub fn for_current_window(provider: Arc) -> WebviewResult> {
+        let origin = web_sys::window()
+            .ok_or_else(|| WebviewError::Browser("browser window is unavailable".to_string()))?
+            .location()
+            .origin()
+            .map_err(|error| WebviewError::Browser(format!("read frontend origin: {error:?}")))?;
+        if !is_http_origin(&origin) {
+            return Ok(None);
+        }
+        let controlled_origin = TargetUrl::parse(&format!("{}/", origin.trim_end_matches('/')))
+            .map_err(|error| WebviewError::Browser(format!("parse frontend origin: {error}")))?;
+        Self::new(provider, controlled_origin).map(Some)
+    }
+
+    /// Handle a browser request after the host has captured it before connection dispatch.
+    pub async fn handle(&self, request: WebviewHostRequest) -> WebviewResult {
+        self.host.handle(request).await
+    }
+
+    fn new(provider: Arc, controlled_origin: TargetUrl) -> WebviewResult {
+        let prefix = GatewayPrefix::new(GATEWAY_PREFIX)?;
+        let policy = GatewayRoutePolicy::new(controlled_origin.into_url(), prefix.clone())?;
+        let gateway = ConcurrentWebviewGateway::new(prefix, OnionGatewayTransport { provider })
+            .with_target_bootstrap(webview_bootstrap);
+        Ok(Self {
+            host: Rc::new(WebviewGatewayHost {
+                policy,
+                gateway,
+                limiter: GatewayRequestLimiter::new(MAX_CONCURRENT_GATEWAY_REQUESTS),
+            }),
+        })
+    }
+}
+
+struct WebviewGatewayHost {
+    policy: GatewayRoutePolicy,
+    gateway: ConcurrentWebviewGateway,
+    limiter: GatewayRequestLimiter,
+}
+
+impl WebviewGatewayHost
+where
+    T: GatewayTransport,
+{
+    async fn handle(&self, request: WebviewHostRequest) -> WebviewResult {
+        match self.policy.route(
+            request.requested.as_url(),
+            request.source_target.as_ref(),
+            request.kind,
+        )? {
+            GatewayRoute::AllowControlled => Ok(WebviewHostOutcome::AllowControlled),
+            GatewayRoute::Redirect(location) => Ok(WebviewHostOutcome::Redirect(location)),
+            GatewayRoute::Serve(target) => {
+                let _permit = self.limiter.acquire().await;
+                self.gateway
+                    .send(request.into_gateway_request(target))
+                    .await
+                    .map(WebviewHostOutcome::Response)
+            }
+            GatewayRoute::Reject(reason) => Ok(WebviewHostOutcome::Reject(reason)),
+        }
+    }
+}
+
+#[derive(Clone)]
+struct GatewayRequestLimiter {
+    state: Rc>,
+}
+
+struct GatewayRequestLimiterState {
+    available: usize,
+    waiters: VecDeque>,
+}
+
+impl GatewayRequestLimiter {
+    fn new(maximum: usize) -> Self {
+        Self {
+            state: Rc::new(RefCell::new(GatewayRequestLimiterState {
+                available: maximum,
+                waiters: VecDeque::new(),
+            })),
+        }
+    }
+
+    async fn acquire(&self) -> GatewayRequestPermit {
+        let receiver = {
+            let mut state = self.state.borrow_mut();
+            if state.available > 0 {
+                state.available -= 1;
+                None
+            } else {
+                let (sender, receiver) = oneshot::channel();
+                state.waiters.push_back(sender);
+                Some(receiver)
+            }
+        };
+        if let Some(receiver) = receiver {
+            let _ = receiver.await;
+        }
+        GatewayRequestPermit {
+            limiter: self.clone(),
+        }
+    }
+
+    fn release(&self) {
+        let mut state = self.state.borrow_mut();
+        while let Some(waiter) = state.waiters.pop_front() {
+            if waiter.send(()).is_ok() {
+                return;
+            }
+        }
+        state.available += 1;
+    }
+}
+
+struct GatewayRequestPermit {
+    limiter: GatewayRequestLimiter,
+}
+
+impl Drop for GatewayRequestPermit {
+    fn drop(&mut self) {
+        self.limiter.release();
+    }
+}
+
+struct OnionGatewayTransport {
+    provider: Arc,
+}
+
+#[async_trait(?Send)]
+impl GatewayTransport for OnionGatewayTransport {
+    async fn send(&self, request: GatewayRequest) -> WebviewResult {
+        let response = onion::request(
+            &self.provider,
+            onion::OnionProxyHttpRequest {
+                url: request.target.to_string(),
+                method: request.method,
+                headers: request
+                    .headers
+                    .into_iter()
+                    .map(|header| (header.name, header.value))
+                    .collect(),
+                body: request.body,
+                options: onion::OnionProxyOptions::default(),
+            },
+        )
+        .await
+        .map_err(WebviewError::Transport)?;
+        let headers = response
+            .headers
+            .into_iter()
+            .map(|(name, value)| GatewayHeader::new(name, value))
+            .collect::>>()?;
+        GatewayResponse::new(response.status, headers, response.body)
+    }
+}
+
+fn webview_bootstrap(target: &Url) -> String {
+    format!(
+        "{}\n{WEBVIEW_DEBUG_OVERLAY}",
+        bootstrap_script(GATEWAY_PREFIX, target)
+    )
+}
+
+fn is_http_origin(origin: &str) -> bool {
+    origin.starts_with("http://") || origin.starts_with("https://")
+}
+
+#[cfg(test)]
+mod tests {
+    use std::cell::RefCell;
+    use std::rc::Rc;
+
+    use wasm_bindgen_test::wasm_bindgen_test;
+
+    use super::*;
+
+    type RecordedRequests = Rc>>;
+    type FixtureHost = WebviewGatewayHost;
+
+    struct FixtureTransport {
+        requests: RecordedRequests,
+    }
+
+    impl FixtureTransport {
+        fn new(requests: RecordedRequests) -> Self {
+            Self { requests }
+        }
+    }
+
+    #[async_trait(?Send)]
+    impl GatewayTransport for FixtureTransport {
+        async fn send(&self, request: GatewayRequest) -> WebviewResult {
+            self.requests.borrow_mut().push(request);
+            let request =
+                self.requests.borrow().last().cloned().ok_or_else(|| {
+                    WebviewError::Transport("missing fixture request".to_string())
+                })?;
+            let mut headers = vec![GatewayHeader::new("content-type", "text/html")?];
+            if let Some(source) = request.source_origin {
+                headers.push(GatewayHeader::new(
+                    "access-control-allow-origin",
+                    source.origin().ascii_serialization(),
+                )?);
+            }
+            GatewayResponse::new(200, headers, b"".to_vec())
+        }
+    }
+
+    fn fixture_host() -> WebviewResult<(FixtureHost, RecordedRequests)> {
+        let prefix = GatewayPrefix::new(GATEWAY_PREFIX)?;
+        let policy = GatewayRoutePolicy::new(
+            TargetUrl::parse("https://frontend.rings.test/")?.into_url(),
+            prefix.clone(),
+        )?;
+        let requests = Rc::new(RefCell::new(Vec::new()));
+        let host = WebviewGatewayHost {
+            policy,
+            gateway: ConcurrentWebviewGateway::new(prefix, FixtureTransport::new(requests.clone()))
+                .with_target_bootstrap(webview_bootstrap),
+            limiter: GatewayRequestLimiter::new(MAX_CONCURRENT_GATEWAY_REQUESTS),
+        };
+        Ok((host, requests))
+    }
+
+    #[wasm_bindgen_test]
+    fn browser_request_allows_source_free_subresources() -> WebviewResult<()> {
+        let value = Object::new();
+        crate::browser_api::js_set(
+            &value,
+            "requested",
+            &JsValue::from_str("https://static.example.test/site.css"),
+        )
+        .map_err(WebviewError::Browser)?;
+        crate::browser_api::js_set(&value, "method", &JsValue::from_str("GET"))
+            .map_err(WebviewError::Browser)?;
+        crate::browser_api::js_set(&value, "kind", &JsValue::from_str("subresource"))
+            .map_err(WebviewError::Browser)?;
+
+        let request = browser_host_request(&value.into()).map_err(WebviewError::Browser)?;
+
+        assert_eq!(request.kind, GatewayRequestKind::Subresource);
+        assert!(request.source_target.is_none());
+        Ok(())
+    }
+
+    #[wasm_bindgen_test]
+    fn host_redirects_then_serves_a_gateway_document_through_its_transport() -> WebviewResult<()> {
+        let (host, requests) = fixture_host()?;
+        let target = TargetUrl::parse("https://example.test/docs/index.html")?;
+        let headers = vec![GatewayHeader::new("accept", "text/html")?];
+        let body = vec![0x00, 0xff];
+        let redirect =
+            futures::executor::block_on(host.handle(WebviewHostRequest::navigation_with_payload(
+                target.clone(),
+                "POST",
+                headers.clone(),
+                body.clone(),
+            )))?;
+        let WebviewHostOutcome::Redirect(gateway_url) = redirect else {
+            return Err(WebviewError::Transport(
+                "navigation did not redirect to gateway".to_string(),
+            ));
+        };
+
+        let response =
+            futures::executor::block_on(host.handle(WebviewHostRequest::navigation_with_payload(
+                TargetUrl::parse(gateway_url.as_str())?,
+                "POST",
+                headers,
+                body,
+            )))?;
+        let WebviewHostOutcome::Response(response) = response else {
+            return Err(WebviewError::Transport(
+                "gateway document was not served".to_string(),
+            ));
+        };
+        let body = String::from_utf8(response.body)
+            .map_err(|error| WebviewError::Transport(error.to_string()))?;
+
+        assert!(body.contains("data-rings-webview-bootstrap"));
+        assert!(body.contains("/webview/https%3A%2F%2Fexample%2Etest%2Fasset%2Epng"));
+        assert_eq!(requests.borrow().len(), 1);
+        let sent_request = requests
+            .borrow()
+            .first()
+            .cloned()
+            .ok_or_else(|| WebviewError::Transport("missing gateway request".to_string()))?;
+        assert_eq!(sent_request.target.as_str(), target.as_url().as_str());
+        assert_eq!(sent_request.method, "POST");
+        assert_eq!(sent_request.body, vec![0x00, 0xff]);
+        assert_eq!(
+            sent_request.headers,
+            vec![GatewayHeader::new("accept", "text/html")?]
+        );
+        Ok(())
+    }
+
+    #[wasm_bindgen_test]
+    fn host_serves_cross_target_runtime_reads_when_upstream_allows_cors() -> WebviewResult<()> {
+        let (host, requests) = fixture_host()?;
+        let source = TargetUrl::parse("https://app.example.test/index.html")?;
+        let target = TargetUrl::parse("https://bank.example.test/account")?;
+
+        let outcome = futures::executor::block_on(host.handle(WebviewHostRequest::fetch(
+            target,
+            source.clone(),
+            "GET",
+            Vec::new(),
+            Vec::new(),
+        )))?;
+
+        assert!(matches!(outcome, WebviewHostOutcome::Response(_)));
+        let request =
+            requests.borrow().first().cloned().ok_or_else(|| {
+                WebviewError::Transport("missing cross-origin request".to_string())
+            })?;
+        assert_eq!(request.source_origin.as_ref(), Some(source.as_url()));
+        Ok(())
+    }
+
+    #[wasm_bindgen_test]
+    fn popup_addresses_only_produce_controlled_gateway_paths() -> WebviewResult<()> {
+        let path = controlled_gateway_path("https://example.test/docs/?q=1")
+            .map_err(WebviewError::Browser)?;
+
+        assert_eq!(
+            path,
+            "/webview/https%3A%2F%2Fexample%2Etest%2Fdocs%2F%3Fq%3D1"
+        );
+        assert!(controlled_gateway_path("file:///tmp/page.html").is_err());
+        Ok(())
+    }
+
+    #[wasm_bindgen_test]
+    fn http_origin_predicate_excludes_extension_and_file_hosts() {
+        assert!(is_http_origin("https://frontend.rings.test"));
+        assert!(is_http_origin("http://127.0.0.1:8080"));
+        assert!(!is_http_origin("chrome-extension://rings"));
+        assert!(!is_http_origin("null"));
+    }
+}
diff --git a/frontend/src/webview_ui.rs b/frontend/src/webview_ui.rs
new file mode 100644
index 000000000..cb4b11ffa
--- /dev/null
+++ b/frontend/src/webview_ui.rs
@@ -0,0 +1,111 @@
+//! Application-owned launch page for the controlled WebView.
+
+use wasm_bindgen::JsCast;
+use web_sys::HtmlInputElement;
+use web_sys::InputEvent;
+use web_sys::MouseEvent;
+use web_sys::SubmitEvent;
+use yew::prelude::*;
+
+use crate::styles;
+use crate::webview;
+
+const DEFAULT_TARGET: &str = "https://example.com/";
+
+/// Render the local launch page before the popup becomes a controlled document.
+#[function_component(WebviewShell)]
+pub(crate) fn webview_shell() -> Html {
+    let address = use_state(|| DEFAULT_TARGET.to_string());
+    let status = use_state(|| "Enter an HTTP(S) address".to_string());
+
+    let navigate = {
+        let address = address.clone();
+        let status = status.clone();
+        Callback::<()>::from(move |_| {
+            let requested = (*address).trim().to_string();
+            let path = match webview::controlled_gateway_path(requested.as_str()) {
+                Ok(path) => path,
+                Err(error) => {
+                    status.set(error);
+                    return;
+                }
+            };
+
+            status.set("Connecting through the local Rings gateway".to_string());
+            let status = status.clone();
+            wasm_bindgen_futures::spawn_local(async move {
+                match webview::prepare_browser_gateway().await {
+                    Ok(()) => {
+                        status.set("Request sent to the local Rings gateway".to_string());
+                        let Some(window) = web_sys::window() else {
+                            status.set("Unable to access the popup window".to_string());
+                            return;
+                        };
+                        if let Err(error) = window.location().set_href(path.as_str()) {
+                            let detail = error
+                                .as_string()
+                                .unwrap_or_else(|| "unknown browser error".to_string());
+                            status.set(format!("Unable to open controlled page: {detail}"));
+                        }
+                    }
+                    Err(error) => status.set(format!("gateway unavailable: {error}")),
+                }
+            });
+        })
+    };
+    let on_address = {
+        let address = address.clone();
+        Callback::from(move |event: InputEvent| {
+            if let Some(input) = event
+                .target()
+                .and_then(|target| target.dyn_into::().ok())
+            {
+                address.set(input.value());
+            }
+        })
+    };
+    let on_submit = {
+        let navigate = navigate.clone();
+        Callback::from(move |event: SubmitEvent| {
+            event.prevent_default();
+            navigate.emit(());
+        })
+    };
+    let on_close = Callback::from(move |_: MouseEvent| {
+        if let Some(window) = web_sys::window() {
+            let _closed = window.close();
+        }
+    });
+
+    html! {
+        

+            
+            

+                

+                    
+                    { "Rings WebView" }
+                

+                

+                    
+                    
+                    
+                

+                
{ (*status).clone() }

+                
+            

+            

+        

+    }
+}
diff --git a/frontend/src/workbench.rs b/frontend/src/workbench.rs
index a57f2bf03..8f755dda5 100644
--- a/frontend/src/workbench.rs
+++ b/frontend/src/workbench.rs
@@ -62,12 +62,8 @@ pub(crate) fn onion_proxy_panel(
     generation: GenerationClock,
     status: UseStateHandle,
 ) -> Html {
-    let on_route = onion_route_callback(
-        &state,
-        node_ref.clone(),
-        generation.clone(),
-        status.clone(),
-    );
+    let on_route =
+        onion_route_callback(&state, node_ref.clone(), generation.clone(), status.clone());
     let on_request = onion_request_callback(&state, node_ref, generation, status);
 
     html! {
@@ -268,7 +264,7 @@ fn spawn_onion_request(
                 outputs
                     .response_headers
                     .set(onion::format_headers(&response.headers));
-                outputs.response_body.set(response.body);
+                outputs.response_body.set(response.body_text());
                 outputs
                     .route_result
                     .set("request completed through onion HTTPS proxy".to_string());

From aa5d714d2fee467a235e568e15875197739108f7 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Tue, 21 Jul 2026 04:26:53 +0800
Subject: [PATCH 02/23] test browser onion webview flow

---
 crates/core/src/storage/idb.rs                |   4 +-
 crates/core/src/swarm/transport.rs            |  42 +-
 .../core/src/swarm/transport/storage_sync.rs  |   5 +-
 crates/core/src/swarm/transport/tests.rs      |   8 +-
 crates/core/src/utils.rs                      |  21 +
 crates/node/src/measure.rs                    |  13 +
 crates/node/src/provider/browser/provider.rs  |  18 +
 frontend/src/webview.rs                       |   3 +
 frontend/src/webview/onion_browser_tests.rs   | 478 ++++++++++++++++++
 9 files changed, 561 insertions(+), 31 deletions(-)
 create mode 100644 frontend/src/webview/onion_browser_tests.rs

diff --git a/crates/core/src/storage/idb.rs b/crates/core/src/storage/idb.rs
index 8dd5a3cd7..e38351a24 100644
--- a/crates/core/src/storage/idb.rs
+++ b/crates/core/src/storage/idb.rs
@@ -35,7 +35,7 @@ struct DataStruct {
 impl DataStruct {
     /// Create a `DataStruct` instance by key and data
     pub fn new(key: &str, data: T) -> Self {
-        let time_now = chrono::Utc::now().timestamp_millis();
+        let time_now = crate::utils::get_epoch_ms_i64();
         Self {
             key: key.to_owned(),
             last_visit_time: time_now,
@@ -54,7 +54,7 @@ pub(crate) fn next_visit_time_after(previous: i64, now: i64) -> i64 {
 }
 
 fn next_visit_time(previous: i64) -> i64 {
-    next_visit_time_after(previous, chrono::Utc::now().timestamp_millis())
+    next_visit_time_after(previous, crate::utils::get_epoch_ms_i64())
 }
 
 /// StorageInstance struct
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index a69aeca07..3cb51da5b 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -2,12 +2,9 @@ use std::collections::BTreeMap;
 use std::collections::BTreeSet;
 use std::sync::Arc;
 use std::sync::Mutex;
-use std::time::Duration;
-use std::time::Instant;
 
 use async_trait::async_trait;
 use bytes::Bytes;
-use chrono::Utc;
 use rings_transport::connection_ref::ConnectionRef;
 #[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 pub use rings_transport::connections::DummyConnection as ConnectionOwner;
@@ -61,6 +58,7 @@ use crate::message::MessagePayload;
 use crate::message::PayloadSender;
 use crate::session::SessionSk;
 use crate::swarm::callback::InnerSwarmCallback;
+use crate::utils::get_epoch_ms_i64;
 
 mod storage_sync;
 
@@ -71,7 +69,7 @@ pub(crate) const STORAGE_LOOKUP_OBSERVATION_CAPACITY: usize = 1024;
 /// Maximum number of peers that may be handshaking before a data channel opens.
 pub(crate) const DEFAULT_PENDING_CONNECTION_CAPACITY: usize = 32;
 
-const PENDING_CONNECTION_TIMEOUT: Duration = Duration::from_secs(15);
+const PENDING_CONNECTION_TIMEOUT_MS: i64 = 15_000;
 
 /// Identifies one pending handshake for a peer.
 ///
@@ -87,7 +85,7 @@ pub(crate) struct PendingConnectionAttempt {
 #[derive(Debug)]
 struct PendingPeer {
     generation: u64,
-    admitted_at: Instant,
+    admitted_at_ms: i64,
 }
 
 /// Bounded, non-routable handshakes owned by the swarm lifecycle.
@@ -107,7 +105,7 @@ impl PendingPeerPool {
         }
     }
 
-    fn reserve(&mut self, peer: Did, now: Instant) -> Result {
+    fn reserve(&mut self, peer: Did, now_ms: i64) -> Result {
         if self.peers.contains_key(&peer) {
             return Err(Error::AlreadyConnected);
         }
@@ -124,7 +122,7 @@ impl PendingPeerPool {
         };
         self.peers.insert(peer, PendingPeer {
             generation: attempt.generation,
-            admitted_at: now,
+            admitted_at_ms: now_ms,
         });
         Ok(attempt)
     }
@@ -144,18 +142,18 @@ impl PendingPeerPool {
         true
     }
 
-    fn expire(&mut self, now: Instant) -> Vec {
-        let expired =
-            self.peers
-                .iter()
-                .filter_map(|(peer, pending)| {
-                    (now.duration_since(pending.admitted_at) >= PENDING_CONNECTION_TIMEOUT)
-                        .then_some(PendingConnectionAttempt {
-                            peer: *peer,
-                            generation: pending.generation,
-                        })
-                })
-                .collect::>();
+    fn expire(&mut self, now_ms: i64) -> Vec {
+        let expired = self
+            .peers
+            .iter()
+            .filter_map(|(peer, pending)| {
+                (now_ms.saturating_sub(pending.admitted_at_ms) >= PENDING_CONNECTION_TIMEOUT_MS)
+                    .then_some(PendingConnectionAttempt {
+                        peer: *peer,
+                        generation: pending.generation,
+                    })
+            })
+            .collect::>();
         for attempt in &expired {
             self.peers.remove(&attempt.peer);
         }
@@ -253,7 +251,7 @@ struct StorageLookupObservation {
 }
 
 fn storage_lookup_observation_now_ms() -> i64 {
-    Utc::now().timestamp_millis()
+    get_epoch_ms_i64()
 }
 
 fn oldest_storage_lookup_observation_key(
@@ -825,7 +823,7 @@ impl SwarmTransport {
         if self.is_admitted_connection(peer) {
             return Err(Error::AlreadyConnected);
         }
-        self.pending_peers()?.reserve(peer, Instant::now())
+        self.pending_peers()?.reserve(peer, get_epoch_ms_i64())
     }
 
     fn pending_attempt(&self, peer: Did) -> Result> {
@@ -889,7 +887,7 @@ impl SwarmTransport {
     /// These peers have never entered the DHT, so expiry only releases the
     /// transport object; it deliberately performs no topology mutation.
     pub(crate) async fn expire_pending_connections(&self) -> Result<()> {
-        let expired = self.pending_peers()?.expire(Instant::now());
+        let expired = self.pending_peers()?.expire(get_epoch_ms_i64());
         for attempt in expired {
             tracing::warn!("pending connection to {} timed out", attempt.peer);
             self.transport
diff --git a/crates/core/src/swarm/transport/storage_sync.rs b/crates/core/src/swarm/transport/storage_sync.rs
index 0293b5377..fd50bf10a 100644
--- a/crates/core/src/swarm/transport/storage_sync.rs
+++ b/crates/core/src/swarm/transport/storage_sync.rs
@@ -1,7 +1,5 @@
 use std::collections::BTreeMap;
 
-use chrono::Utc;
-
 use super::SwarmTransport;
 use crate::dht::entry::PlacedEntry;
 use crate::dht::entry::SyncedEntryAck;
@@ -15,6 +13,7 @@ use crate::message::MessagePayload;
 use crate::message::PayloadSender;
 use crate::message::SyncEntriesWithSuccessor;
 use crate::message::SyncEntriesWithSuccessorReport;
+use crate::utils::get_epoch_ms_i64;
 
 const STORAGE_SYNC_ACK_CAPACITY: usize = 1024;
 
@@ -54,7 +53,7 @@ impl StorageSyncReceiverProof {
 }
 
 fn storage_sync_ack_now_ms() -> i64 {
-    Utc::now().timestamp_millis()
+    get_epoch_ms_i64()
 }
 
 fn expected_sync_acks(data: &[PlacedEntry]) -> Result> {
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index 9fe1d86fc..d6f352649 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -143,7 +143,7 @@ fn swarm_builder_normalizes_virtual_nodes_before_protocol_advertisement() -> Res
 #[test]
 fn pending_peer_pool_is_bounded_and_rejects_duplicate_peers() -> Result<()> {
     let mut pool = PendingPeerPool::<2>::new();
-    let now = Instant::now();
+    let now = 1_000;
     let peer_a = SecretKey::random().address().into();
     let peer_b = SecretKey::random().address().into();
     let peer_c = SecretKey::random().address().into();
@@ -169,7 +169,7 @@ fn pending_peer_pool_is_bounded_and_rejects_duplicate_peers() -> Result<()> {
 #[test]
 fn stale_pending_callback_cannot_remove_a_replacement_attempt() -> Result<()> {
     let mut pool = PendingPeerPool::<1>::new();
-    let now = Instant::now();
+    let now = 1_000;
     let peer = SecretKey::random().address().into();
 
     let old_attempt = pool.reserve(peer, now)?;
@@ -185,11 +185,11 @@ fn stale_pending_callback_cannot_remove_a_replacement_attempt() -> Result<()> {
 #[test]
 fn pending_peer_pool_expires_unopened_handshakes() -> Result<()> {
     let mut pool = PendingPeerPool::<1>::new();
-    let now = Instant::now();
+    let now = 1_000;
     let peer = SecretKey::random().address().into();
     let attempt = pool.reserve(peer, now)?;
 
-    let expired = pool.expire(now + PENDING_CONNECTION_TIMEOUT);
+    let expired = pool.expire(now + PENDING_CONNECTION_TIMEOUT_MS);
     assert_eq!(expired, vec![attempt]);
     assert_eq!(pool.len(), 0);
     Ok(())
diff --git a/crates/core/src/utils.rs b/crates/core/src/utils.rs
index 8537e0f19..398d351dc 100644
--- a/crates/core/src/utils.rs
+++ b/crates/core/src/utils.rs
@@ -1,10 +1,31 @@
 //! Utils for ring-core
+#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
 use chrono::Utc;
+
 /// Get local utc timestamp (millisecond)
+#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
 pub fn get_epoch_ms() -> u128 {
     Utc::now().timestamp_millis() as u128
 }
 
+/// Get local utc timestamp (millisecond)
+#[cfg(all(feature = "wasm", target_family = "wasm"))]
+pub fn get_epoch_ms() -> u128 {
+    let now = js_sys::Date::now();
+    if now.is_finite() && now > 0.0 {
+        now as u128
+    } else {
+        0
+    }
+}
+
+pub(crate) fn get_epoch_ms_i64() -> i64 {
+    match i64::try_from(get_epoch_ms()) {
+        Ok(value) => value,
+        Err(_) => i64::MAX,
+    }
+}
+
 #[cfg(all(feature = "wasm", target_family = "wasm"))]
 /// Toolset for wasm
 pub mod js_value {
diff --git a/crates/node/src/measure.rs b/crates/node/src/measure.rs
index 3ef779509..030e5d2cb 100644
--- a/crates/node/src/measure.rs
+++ b/crates/node/src/measure.rs
@@ -63,9 +63,22 @@ trait MeasureClock: Send + Sync {
 struct SystemMeasureClock;
 
 impl MeasureClock for SystemMeasureClock {
+    #[cfg(not(all(feature = "browser", target_family = "wasm")))]
     fn now(&self) -> DateTime {
         Utc::now()
     }
+
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
+    fn now(&self) -> DateTime {
+        let now = js_sys::Date::now();
+        if !now.is_finite() {
+            return DateTime::UNIX_EPOCH;
+        }
+        match DateTime::from_timestamp_millis(now as i64) {
+            Some(value) => value,
+            None => DateTime::UNIX_EPOCH,
+        }
+    }
 }
 
 #[derive(Debug)]
diff --git a/crates/node/src/provider/browser/provider.rs b/crates/node/src/provider/browser/provider.rs
index 52a61efa8..ca9281c19 100644
--- a/crates/node/src/provider/browser/provider.rs
+++ b/crates/node/src/provider/browser/provider.rs
@@ -506,6 +506,24 @@ impl Provider {
         })
     }
 
+    /// Install the browser HTTPS onion-exit protocol handler with an explicit target policy.
+    ///
+    /// This updates the local exit handler used by incoming onion HTTPS requests. Discovery still
+    /// comes from the provider's processor configuration, so nodes that should be routeable exits
+    /// must also be constructed with HTTPS onion-exit advertisement enabled.
+    pub fn install_onion_https_exit(
+        &self,
+        allowed_targets: Vec,
+        denied_targets: Vec,
+    ) -> Result<(), JsError> {
+        let policy = OnionExitPolicy::from_target_strings(allowed_targets, denied_targets)
+            .map_err(JsError::from)?;
+        policy.validate_targets().map_err(JsError::from)?;
+        self.install_onion_https_protocol(Some(policy))
+            .map(|_| ())
+            .map_err(JsError::from)
+    }
+
     /// Create new provider instance with serialized config (yaml/json)
     pub fn new_provider_with_serialized_config(config: String) -> js_sys::Promise {
         future_to_promise(async move {
diff --git a/frontend/src/webview.rs b/frontend/src/webview.rs
index 6ae57e12f..fa5484a93 100644
--- a/frontend/src/webview.rs
+++ b/frontend/src/webview.rs
@@ -930,3 +930,6 @@ mod tests {
         assert!(!is_http_origin("null"));
     }
 }
+
+#[cfg(all(test, target_arch = "wasm32"))]
+mod onion_browser_tests;
diff --git a/frontend/src/webview/onion_browser_tests.rs b/frontend/src/webview/onion_browser_tests.rs
new file mode 100644
index 000000000..4a250707b
--- /dev/null
+++ b/frontend/src/webview/onion_browser_tests.rs
@@ -0,0 +1,478 @@
+use std::sync::Arc;
+
+use js_sys::Object;
+use js_sys::Reflect;
+use rings_node::onion::OnionExitPolicy;
+use rings_node::prelude::rings_core::ecc::SecretKey;
+use rings_node::prelude::rings_core::prelude::uuid;
+use rings_node::prelude::rings_core::session::SessionSk;
+use rings_node::prelude::rings_core::storage::idb::IdbStorage;
+use rings_node::prelude::rings_core::utils::js_utils::window_sleep;
+use rings_node::processor::ProcessorBuilder;
+use rings_node::processor::ProcessorConfig;
+use rings_node::provider::Provider;
+use rings_webview::browser::BOOTSTRAP_MARKER;
+use rings_webview::GatewayHeader;
+use rings_webview::GatewayPrefix;
+use rings_webview::GatewayResponse;
+use rings_webview::Result as WebviewResult;
+use rings_webview::TargetUrl;
+use rings_webview::WebviewError;
+use serde::Deserialize;
+use url::Url;
+use wasm_bindgen::JsValue;
+use wasm_bindgen_futures::JsFuture;
+use wasm_bindgen_test::wasm_bindgen_test;
+
+use super::WebviewHostOutcome;
+use super::WebviewHostRequest;
+use super::WebviewNode;
+use super::GATEWAY_PREFIX;
+
+const TEST_DHT_FINGER_TABLE_SIZE: usize = 8;
+const TEST_NETWORK_ID: u32 = 665;
+const TEST_ICE_SERVERS: &str = "stun://stun.l.google.com:19302";
+const TEST_STABILIZE_INTERVAL_SECS: u64 = 3;
+const FIXTURE_AUTHORITY: &str = "fixture.rings.test:443";
+const FIXTURE_INDEX: &str = "https://fixture.rings.test/index.html";
+const FIXTURE_CSS: &str = "https://fixture.rings.test/site.css";
+const FIXTURE_API: &str = "https://fixture.rings.test/api/data";
+const FIXTURE_SUBMIT: &str = "https://fixture.rings.test/forms/submit";
+
+#[derive(Debug, Deserialize)]
+struct FetchCall {
+    url: String,
+    method: String,
+    body: String,
+}
+
+#[wasm_bindgen_test(async)]
+async fn webview_node_fetches_page_resources_through_browser_onion_exit() {
+    let installed = install_mock_exit_fetch();
+    assert!(installed.is_ok(), "install mock exit fetch: {installed:?}");
+
+    let result = run_browser_onion_webview_flow().await;
+    let restored = restore_mock_exit_fetch();
+
+    assert!(restored.is_ok(), "restore mock exit fetch: {restored:?}");
+    assert!(
+        result.is_ok(),
+        "browser onion WebView flow failed: {result:?}"
+    );
+}
+
+async fn run_browser_onion_webview_flow() -> WebviewResult<()> {
+    let storage_suffix = uuid::Uuid::new_v4().to_simple().to_string();
+    let client = browser_provider(
+        &format!("rings-webview-onion-client-{storage_suffix}"),
+        None,
+    )
+    .await?;
+    let exit = browser_provider(
+        &format!("rings-webview-onion-exit-{storage_suffix}"),
+        Some(FIXTURE_AUTHORITY),
+    )
+    .await?;
+    let _client_listener = client.listen();
+    let _exit_listener = exit.listen();
+    connect_browser_providers(&client, &exit).await?;
+    window_sleep(1_000).await.map_err(js_webview_error)?;
+
+    let node = WebviewNode::new(client, controlled_origin()?)?;
+    let index_target = TargetUrl::parse(FIXTURE_INDEX)?;
+    let index = retry_gateway_navigation(&node, &index_target).await?;
+    expect_status(&index, "index navigation", 200)?;
+    let index_body = utf8_body(index)?;
+    assert_contains(&index_body, "Rings Onion Fixture")?;
+    assert_contains(&index_body, BOOTSTRAP_MARKER)?;
+    assert_contains(&index_body, gateway_path(FIXTURE_CSS)?.as_str())?;
+    assert_contains(
+        &index_body,
+        gateway_path("https://fixture.rings.test/hero.png")?.as_str(),
+    )?;
+
+    let css = expect_response(
+        node.handle(WebviewHostRequest::subresource(
+            controlled_gateway_target(FIXTURE_CSS)?,
+            Some(index_target.clone()),
+            "GET",
+            Vec::new(),
+            Vec::new(),
+        ))
+        .await?,
+        "stylesheet subresource",
+    )?;
+    expect_status(&css, "stylesheet subresource", 200)?;
+    let css_body = utf8_body(css)?;
+    assert_contains(
+        &css_body,
+        gateway_path("https://fixture.rings.test/bg.png")?.as_str(),
+    )?;
+
+    let api = expect_response(
+        node.handle(WebviewHostRequest::fetch(
+            controlled_gateway_target(FIXTURE_API)?,
+            index_target.clone(),
+            "GET",
+            vec![GatewayHeader::new("accept", "application/json")?],
+            Vec::new(),
+        ))
+        .await?,
+        "runtime fetch",
+    )?;
+    expect_status(&api, "runtime fetch", 200)?;
+    assert_contains(&utf8_body(api)?, "through browser onion exit")?;
+
+    let submit = expect_response(
+        node.handle(WebviewHostRequest::xhr(
+            controlled_gateway_target(FIXTURE_SUBMIT)?,
+            index_target,
+            "POST",
+            vec![GatewayHeader::new("content-type", "text/plain")?],
+            b"name=value".to_vec(),
+        ))
+        .await?,
+        "runtime xhr",
+    )?;
+    expect_status(&submit, "runtime xhr", 200)?;
+    assert_contains(&utf8_body(submit)?, "name=value")?;
+
+    let calls = fetch_calls()?;
+    assert_fetch_call(&calls, FIXTURE_INDEX, "GET", None)?;
+    assert_fetch_call(&calls, FIXTURE_CSS, "GET", None)?;
+    assert_fetch_call(&calls, FIXTURE_API, "GET", None)?;
+    assert_fetch_call(&calls, FIXTURE_SUBMIT, "POST", Some("name=value"))?;
+    Ok(())
+}
+
+async fn browser_provider(
+    storage_name: &str,
+    exit_target: Option<&str>,
+) -> WebviewResult> {
+    let session_sk = SessionSk::new_with_seckey(&SecretKey::random()).map_err(|error| {
+        WebviewError::Transport(format!("build browser session key: {error:?}"))
+    })?;
+    let mut config = ProcessorConfig::new(
+        TEST_NETWORK_ID,
+        TEST_ICE_SERVERS.to_string(),
+        session_sk,
+        TEST_STABILIZE_INTERVAL_SECS,
+    );
+    if let Some(target) = exit_target {
+        let policy = OnionExitPolicy::from_target_strings(vec![target.to_string()], Vec::new())
+            .map_err(|error| WebviewError::Transport(format!("build exit policy: {error:?}")))?;
+        config = config.enable_https_onion_exit().onion_exit_policy(policy);
+    }
+    let storage = Box::new(
+        IdbStorage::new_with_cap_and_name(50_000, storage_name)
+            .await
+            .map_err(|error| WebviewError::Transport(format!("open idb storage: {error:?}")))?,
+    );
+    let processor = ProcessorBuilder::from_config(&config)
+        .map_err(|error| WebviewError::Transport(format!("build processor config: {error:?}")))?
+        .storage(storage)
+        .dht_finger_table_size(TEST_DHT_FINGER_TABLE_SIZE)
+        .build()
+        .map_err(|error| WebviewError::Transport(format!("build processor: {error:?}")))?;
+    let provider = Arc::new(Provider::from_processor(Arc::new(processor)));
+    provider
+        .set_backend()
+        .map_err(|error| WebviewError::Transport(format!("install backend: {error:?}")))?;
+    if let Some(target) = exit_target {
+        provider
+            .install_onion_https_exit(vec![target.to_string()], Vec::new())
+            .map_err(|error| {
+                WebviewError::Transport(format!("install onion HTTPS exit: {error:?}"))
+            })?;
+    }
+    Ok(provider)
+}
+
+async fn connect_browser_providers(
+    client: &Arc,
+    exit: &Arc,
+) -> WebviewResult<()> {
+    let offer = string_field(
+        &rpc(
+            client,
+            "createOffer",
+            object(&[("did", exit.address().as_str())]),
+        )
+        .await?,
+        "offer",
+    )?;
+    let answer = string_field(
+        &rpc(exit, "answerOffer", object(&[("offer", offer.as_str())])).await?,
+        "answer",
+    )?;
+    let _accepted = rpc(
+        client,
+        "acceptAnswer",
+        object(&[("answer", answer.as_str())]),
+    )
+    .await?;
+    Ok(())
+}
+
+async fn rpc(provider: &Arc, method: &str, params: JsValue) -> WebviewResult {
+    JsFuture::from(provider.request(method.to_string(), params))
+        .await
+        .map_err(js_webview_error)
+}
+
+fn object(pairs: &[(&str, &str)]) -> JsValue {
+    let object = Object::new();
+    for (key, value) in pairs {
+        let _set = Reflect::set(
+            object.as_ref(),
+            JsValue::from_str(key).as_ref(),
+            JsValue::from_str(value).as_ref(),
+        );
+    }
+    object.into()
+}
+
+fn string_field(value: &JsValue, field: &str) -> WebviewResult {
+    Reflect::get(value.as_ref(), JsValue::from_str(field).as_ref())
+        .map_err(js_webview_error)?
+        .as_string()
+        .ok_or_else(|| WebviewError::Browser(format!("missing string field {field:?}")))
+}
+
+async fn retry_gateway_navigation(
+    node: &WebviewNode,
+    target: &TargetUrl,
+) -> WebviewResult {
+    let mut last_error = None;
+    for _ in 0..60 {
+        match gateway_navigation(node, target).await {
+            Ok(response) => return Ok(response),
+            Err(error) => {
+                last_error = Some(error.to_string());
+                window_sleep(250).await.map_err(js_webview_error)?;
+            }
+        }
+    }
+    Err(WebviewError::Transport(format!(
+        "gateway navigation did not find a browser onion exit: {}",
+        last_error.unwrap_or_else(|| "no attempt was made".to_string())
+    )))
+}
+
+async fn gateway_navigation(
+    node: &WebviewNode,
+    target: &TargetUrl,
+) -> WebviewResult {
+    let redirect = node
+        .handle(WebviewHostRequest::navigation(target.clone()))
+        .await?;
+    let WebviewHostOutcome::Redirect(gateway_url) = redirect else {
+        return Err(WebviewError::Transport(
+            "external navigation did not redirect to the controlled gateway".to_string(),
+        ));
+    };
+    let served = node
+        .handle(WebviewHostRequest::navigation(TargetUrl::parse(
+            gateway_url.as_str(),
+        )?))
+        .await?;
+    expect_response(served, "gateway navigation")
+}
+
+fn expect_response(
+    outcome: WebviewHostOutcome,
+    context: &'static str,
+) -> WebviewResult {
+    match outcome {
+        WebviewHostOutcome::Response(response) => Ok(response),
+        other => Err(WebviewError::Transport(format!(
+            "{context} returned {other:?}, expected response"
+        ))),
+    }
+}
+
+fn expect_status(
+    response: &GatewayResponse,
+    context: &'static str,
+    expected: u16,
+) -> WebviewResult<()> {
+    if response.status == expected {
+        Ok(())
+    } else {
+        Err(WebviewError::Transport(format!(
+            "{context} returned status {}, expected {expected}",
+            response.status
+        )))
+    }
+}
+
+fn controlled_origin() -> WebviewResult {
+    let origin = web_sys::window()
+        .ok_or_else(|| WebviewError::Browser("missing browser window".to_string()))?
+        .location()
+        .origin()
+        .map_err(js_webview_error)?;
+    TargetUrl::parse(&format!("{}/", origin.trim_end_matches('/')))
+}
+
+fn controlled_gateway_target(target: &str) -> WebviewResult {
+    let origin = web_sys::window()
+        .ok_or_else(|| WebviewError::Browser("missing browser window".to_string()))?
+        .location()
+        .origin()
+        .map_err(js_webview_error)?;
+    let target = TargetUrl::parse(target)?;
+    let prefix = GatewayPrefix::new(GATEWAY_PREFIX)?;
+    TargetUrl::parse(&format!(
+        "{}{}",
+        origin.trim_end_matches('/'),
+        prefix.encode(target.as_url())
+    ))
+}
+
+fn gateway_path(target: &str) -> WebviewResult {
+    let target = Url::parse(target)?;
+    Ok(GatewayPrefix::new(GATEWAY_PREFIX)?.encode(&target))
+}
+
+fn utf8_body(response: GatewayResponse) -> WebviewResult {
+    String::from_utf8(response.body)
+        .map_err(|error| WebviewError::Transport(format!("response was not UTF-8: {error}")))
+}
+
+fn assert_contains(value: &str, expected: &str) -> WebviewResult<()> {
+    if value.contains(expected) {
+        Ok(())
+    } else {
+        Err(WebviewError::Transport(format!(
+            "expected {expected:?} inside {value:?}"
+        )))
+    }
+}
+
+fn assert_fetch_call(
+    calls: &[FetchCall],
+    url: &str,
+    method: &str,
+    body_fragment: Option<&str>,
+) -> WebviewResult<()> {
+    let expected = Url::parse(url)?;
+    if calls.iter().any(|call| {
+        urls_match(&call.url, &expected)
+            && call.method == method
+            && body_fragment.is_none_or(|fragment| call.body.contains(fragment))
+    }) {
+        Ok(())
+    } else {
+        Err(WebviewError::Transport(format!(
+            "missing exit fetch call {method} {url}; calls: {calls:?}"
+        )))
+    }
+}
+
+fn urls_match(actual: &str, expected: &Url) -> bool {
+    Url::parse(actual).is_ok_and(|actual| {
+        actual.scheme() == expected.scheme()
+            && actual.host_str() == expected.host_str()
+            && actual.port_or_known_default() == expected.port_or_known_default()
+            && actual.path() == expected.path()
+            && actual.query() == expected.query()
+    })
+}
+
+fn fetch_calls() -> WebviewResult> {
+    let text = js_sys::eval("JSON.stringify(globalThis.__ringsWebviewOnionFetchLog || [])")
+        .map_err(js_webview_error)?
+        .as_string()
+        .ok_or_else(|| WebviewError::Browser("fetch log was not a string".to_string()))?;
+    serde_json::from_str(text.as_str())
+        .map_err(|error| WebviewError::Transport(format!("parse fetch log: {error}")))
+}
+
+fn install_mock_exit_fetch() -> WebviewResult<()> {
+    js_sys::eval(
+        r#"
+(() => {
+  const original = globalThis.fetch;
+  globalThis.__ringsWebviewOriginalFetch = original;
+  globalThis.__ringsWebviewOnionFetchLog = [];
+  const decodeBody = (body) => {
+    if (!body) return "";
+    if (typeof body === "string") return body;
+    if (body instanceof Uint8Array) return new TextDecoder().decode(body);
+    if (body instanceof ArrayBuffer) return new TextDecoder().decode(body);
+    return String(body);
+  };
+  globalThis.fetch = async (input, init = {}) => {
+    const request = input instanceof Request ? input : undefined;
+    const url = String(request ? request.url : input);
+    const method = String(init.method || request?.method || "GET").toUpperCase();
+    const body = decodeBody(init.body);
+    globalThis.__ringsWebviewOnionFetchLog.push({ url, method, body });
+    const parsed = new URL(url);
+    let status = 200;
+    let contentType = "text/plain; charset=utf-8";
+    let responseBody = "";
+    if (parsed.origin !== "https://fixture.rings.test") {
+      status = 404;
+      responseBody = `unexpected fixture target ${url}`;
+    } else if (parsed.pathname === "/index.html") {
+      contentType = "text/html; charset=utf-8";
+      responseBody = `
+
+  
+    Rings Onion Fixture
+    
+  
+  
+    
Rings Onion Fixture

+    hero
+  
+`;
+    } else if (parsed.pathname === "/site.css") {
+      contentType = "text/css; charset=utf-8";
+      responseBody = `body { background-image: url("/bg.png"); }`;
+    } else if (parsed.pathname === "/api/data") {
+      contentType = "application/json";
+      responseBody = JSON.stringify({ message: "through browser onion exit" });
+    } else if (parsed.pathname === "/forms/submit") {
+      responseBody = `submitted:${body}`;
+    } else {
+      status = 404;
+      responseBody = `missing fixture path ${parsed.pathname}`;
+    }
+    return new Response(responseBody, {
+      status,
+      headers: {
+        "content-type": contentType,
+        "access-control-allow-origin": "*",
+        "access-control-expose-headers": "content-type,x-fixture",
+        "x-fixture": "rings-webview-onion"
+      }
+    });
+  };
+})();
+"#,
+    )
+    .map(|_| ())
+    .map_err(js_webview_error)
+}
+
+fn restore_mock_exit_fetch() -> WebviewResult<()> {
+    js_sys::eval(
+        r#"
+(() => {
+  if (globalThis.__ringsWebviewOriginalFetch) {
+    globalThis.fetch = globalThis.__ringsWebviewOriginalFetch;
+    delete globalThis.__ringsWebviewOriginalFetch;
+  }
+})();
+"#,
+    )
+    .map(|_| ())
+    .map_err(js_webview_error)
+}
+
+fn js_webview_error(error: JsValue) -> WebviewError {
+    WebviewError::Browser(format!("{error:?}"))
+}

From a3af9dea1e6db5d04ef6ec1f94def2bad97c2dcd Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Wed, 22 Jul 2026 03:43:19 +0800
Subject: [PATCH 03/23] Implement webview gateway diagnostics

---
 .gitignore                                    |   1 +
 crates/core/src/dht/stabilization.rs          | 408 +++++++++++--
 crates/core/src/swarm/callback.rs             |  66 +++
 crates/core/src/swarm/transport.rs            |  94 ++-
 crates/core/src/swarm/transport/tests.rs      |  66 ++-
 .../core/src/tests/default/test_connection.rs |  39 ++
 .../src/tests/default/test_stabilization.rs   |  80 +++
 crates/node/Cargo.toml                        |   2 +-
 crates/node/src/error.rs                      |   8 +
 crates/node/src/logging.rs                    |  14 +-
 crates/node/src/processor/mod.rs              |  37 +-
 .../node/src/processor/tests/test_network.rs  |  43 +-
 .../node/src/processor/tests/test_registry.rs |  36 ++
 crates/transport/src/callback.rs              |  27 +-
 crates/transport/src/connections/dummy/mod.rs | 106 +++-
 frontend/Cargo.lock                           |  13 +
 frontend/assets/webview-host.js               |  21 +-
 frontend/assets/webview-overlay.js            | 555 ++++++++++++++++++
 frontend/index.html                           |   3 +-
 frontend/rings-webview-service-worker.js      | 187 +++---
 frontend/src/browser_api.rs                   | 147 ++++-
 frontend/src/controls.rs                      |  43 +-
 frontend/src/extension.rs                     |   1 +
 frontend/src/onion.rs                         |  14 +-
 frontend/src/styles/components.css            | 312 ----------
 frontend/src/styles/responsive.css            |  51 --
 frontend/src/webview.rs                       | 441 ++++++++------
 frontend/src/webview_ui.rs                    | 104 +---
 28 files changed, 2076 insertions(+), 843 deletions(-)
 create mode 100644 frontend/assets/webview-overlay.js

diff --git a/.gitignore b/.gitignore
index 6892af0c0..01297626c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ config*.yaml
 **/*.js
 **/*.mjs
 !frontend/assets/webview-host.js
+!frontend/assets/webview-overlay.js
 !frontend/rings-webview-service-worker.js
 frontend/dist-e2e/
 .ipynb_checkpoints
diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index 916593c04..3c9db6757 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -1,16 +1,24 @@
 //! Stabilization run daemons to maintain dht.
 
+use std::future::Future;
 use std::sync::Arc;
+use std::time::Duration;
 
+use futures::future::FutureExt;
+use futures::pin_mut;
+use futures::select;
+use futures_timer::Delay;
 use rings_transport::core::transport::WebrtcConnectionState;
 
 use crate::dht::successor::SuccessorReader;
 use crate::dht::types::ChordStorageRepair;
 use crate::dht::types::CorrectChord;
 use crate::dht::Chord;
+use crate::dht::Did;
 use crate::dht::PeerRing;
 use crate::dht::PeerRingAction;
 use crate::dht::PeerRingRemoteAction;
+use crate::dht::TopoInfo;
 use crate::error::Error;
 use crate::error::Result;
 use crate::message::FindSuccessorReportHandler;
@@ -24,6 +32,8 @@ use crate::message::QueryForTopoInfoSend;
 use crate::message::SyncEntriesWithSuccessor;
 use crate::swarm::transport::SwarmTransport;
 
+const STABILIZATION_STEP_TIMEOUT: Duration = Duration::from_secs(30);
+
 /// The stabilization runner.
 #[derive(Clone)]
 pub struct Stabilizer {
@@ -40,54 +50,199 @@ impl Stabilizer {
 
     /// Run stabilization once.
     pub async fn stabilize(&self) -> Result<()> {
-        tracing::debug!("STABILIZATION notify_predecessor start");
-        if let Err(e) = self.notify_predecessor().await {
-            tracing::error!("[stabilize] Failed on notify predecessor {:?}", e);
-        }
-        tracing::debug!("STABILIZATION notify_predecessor end");
-        tracing::debug!("STABILIZATION fix_fingers start");
-        if let Err(e) = self.fix_fingers().await {
-            tracing::error!("[stabilize] Failed on fix_finger {:?}", e);
-        }
-        tracing::debug!("STABILIZATION fix_fingers end");
-        tracing::debug!("STABILIZATION clean_unavailable_connections start");
-        if let Err(e) = self.clean_unavailable_connections().await {
-            tracing::error!(
-                "[stabilize] Failed on clean unavailable connections {:?}",
-                e
-            );
-        }
-        tracing::debug!("STABILIZATION clean_unavailable_connections end");
+        self.stabilize_with_step_timeout(STABILIZATION_STEP_TIMEOUT)
+            .await
+    }
+
+    pub(crate) async fn stabilize_with_step_timeout(&self, timeout: Duration) -> Result<()> {
+        self.run_step("notify_predecessor", timeout, self.notify_predecessor())
+            .await;
+        self.run_step("fix_fingers", timeout, self.fix_fingers())
+            .await;
+        self.run_step(
+            "clean_unavailable_connections",
+            timeout,
+            self.clean_unavailable_connections(),
+        )
+        .await;
         // Default HMCC/Zave stabilization path. The pure operation is specified
         // as `CorrectStabilize` in tests/default/test_dht_convergence.rs.
-        tracing::debug!("STABILIZATION correct_stabilize start");
-        if let Err(e) = self.correct_stabilize().await {
-            tracing::error!("[stabilize] Failed on call correct stabilize {:?}", e);
-        }
-        tracing::debug!("STABILIZATION correct_stabilize end");
-        tracing::debug!("STABILIZATION repair_storage start");
-        if let Err(e) = self.repair_storage().await {
-            tracing::error!("[stabilize] Failed on repair storage {:?}", e);
-        }
-        tracing::debug!("STABILIZATION repair_storage end");
+        self.run_step("correct_stabilize", timeout, self.correct_stabilize())
+            .await;
+        self.run_step("repair_storage", timeout, self.repair_storage())
+            .await;
         Ok(())
     }
 
+    async fn run_step(&self, step: &'static str, timeout: Duration, future: F)
+    where
+        F: Future>,
+    {
+        tracing::debug!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            step,
+            timeout_ms = timeout.as_millis(),
+            "STABILIZATION step start"
+        );
+
+        let result = {
+            let future = future.fuse();
+            let timer = Delay::new(timeout).fuse();
+            pin_mut!(future, timer);
+
+            select! {
+                result = future => Some(result),
+                _ = timer => None,
+            }
+        };
+
+        match result {
+            Some(Ok(())) => {
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    step,
+                    "STABILIZATION step end"
+                );
+            }
+            Some(Err(e)) => {
+                tracing::error!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    step,
+                    error = ?e,
+                    "STABILIZATION step failed"
+                );
+            }
+            None => self.log_step_timeout(step, timeout),
+        }
+    }
+
+    fn log_step_timeout(&self, step: &'static str, timeout: Duration) {
+        let topology = TopoInfo::try_from(self.dht.as_ref()).ok();
+        let mut connections: Vec<(Did, WebrtcConnectionState)> = self
+            .transport
+            .admitted_connections()
+            .into_iter()
+            .map(|(did, conn)| (did, conn.webrtc_connection_state()))
+            .collect();
+        connections.sort_by_key(|(did, _)| *did);
+
+        tracing::warn!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            step,
+            timeout_ms = timeout.as_millis(),
+            reason = "stabilization_step_future_pending",
+            topology = ?topology,
+            connections = ?connections,
+            "STABILIZATION step timed out"
+        );
+    }
+
     async fn handle_storage_repair_action(&self, act: PeerRingAction) -> Result<()> {
-        for delivery in act.storage_sync_deliveries()? {
+        let deliveries = act.storage_sync_deliveries()?;
+        if deliveries.is_empty() {
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                "STABILIZATION storage repair has no deliveries"
+            );
+            return Ok(());
+        }
+
+        tracing::debug!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            deliveries = deliveries.len(),
+            "STABILIZATION storage repair deliveries prepared"
+        );
+
+        for delivery in deliveries {
             let msg = SyncEntriesWithSuccessor::from_delivery(delivery);
-            self.transport.send_storage_sync(msg).await?;
+            let purpose = msg.purpose;
+            let destination = msg.destination;
+            let destination_did = destination.did();
+            let entries = msg.data.len();
+            let next_hop = self
+                .dht
+                .next_hop_for_storage_sync(destination)
+                .ok()
+                .flatten();
+            let next_hop_state = next_hop
+                .and_then(|did| self.transport.get_connection(did))
+                .map(|conn| conn.webrtc_connection_state());
+
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                purpose = ?purpose,
+                destination = ?destination,
+                destination_did = %destination_did,
+                next_hop = ?next_hop,
+                next_hop_state = ?next_hop_state,
+                entries,
+                "STABILIZATION storage repair send start"
+            );
+
+            match self.transport.send_storage_sync(msg).await {
+                Ok(tx_id) => tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    tx_id = %tx_id,
+                    purpose = ?purpose,
+                    destination = ?destination,
+                    destination_did = %destination_did,
+                    next_hop = ?next_hop,
+                    entries,
+                    "STABILIZATION storage repair send complete"
+                ),
+                Err(e) => {
+                    tracing::error!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        purpose = ?purpose,
+                        destination = ?destination,
+                        destination_did = %destination_did,
+                        next_hop = ?next_hop,
+                        next_hop_state = ?next_hop_state,
+                        entries,
+                        error = ?e,
+                        "STABILIZATION storage repair send failed"
+                    );
+                    return Err(e);
+                }
+            }
         }
         Ok(())
     }
 
     /// Republish locally-held entries to their current affine owners.
     pub async fn repair_storage(&self) -> Result<()> {
+        tracing::debug!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            redundancy = self.transport.storage_redundancy(),
+            "STABILIZATION repair_storage republish start"
+        );
         let action = self
             .dht
             .republish_local_entries(self.transport.storage_redundancy())
             .await?;
-        self.handle_storage_repair_action(action).await
+        tracing::debug!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            action = ?action,
+            "STABILIZATION repair_storage republish action prepared"
+        );
+        self.handle_storage_repair_action(action).await?;
+        tracing::debug!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            "STABILIZATION repair_storage republish complete"
+        );
+        Ok(())
     }
 
     /// Clean unavailable connections in transport.
@@ -96,23 +251,58 @@ impl Stabilizer {
         let conns = self.transport.admitted_connections();
 
         for (did, conn) in conns.into_iter() {
+            let state = conn.webrtc_connection_state();
             // Only terminal states are cleaned. `Disconnected` is transient: ICE
             // can recover from it, so tearing it down here (the stabilizer runs
             // every few seconds) would kill connections during a brief blip
             // before WebRTC self-heals. This mirrors the swarm callback, which
             // also only leaves the DHT on `Failed`/`Closed`.
             if matches!(
-                conn.webrtc_connection_state(),
+                state,
                 WebrtcConnectionState::Failed | WebrtcConnectionState::Closed
             ) {
-                tracing::info!("STABILIZATION clean_unavailable_transports: {:?}", did);
+                tracing::info!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    peer = %did,
+                    state = ?state,
+                    "STABILIZATION clean_unavailable selected terminal transport"
+                );
                 let should_repair = self
                     .dht
                     .peer_may_share_storage_responsibility(did, self.transport.storage_redundancy())
                     .await?;
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    peer = %did,
+                    state = ?state,
+                    should_repair,
+                    "STABILIZATION clean_unavailable disconnect start"
+                );
                 self.transport.disconnect(did).await?;
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    peer = %did,
+                    state = ?state,
+                    should_repair,
+                    "STABILIZATION clean_unavailable disconnect complete"
+                );
                 if should_repair {
+                    tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        peer = %did,
+                        "STABILIZATION clean_unavailable repair start"
+                    );
                     self.repair_storage().await?;
+                    tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        peer = %did,
+                        "STABILIZATION clean_unavailable repair complete"
+                    );
                 }
             }
         }
@@ -130,13 +320,49 @@ impl Stabilizer {
         let msg = Message::NotifyPredecessorSend(NotifyPredecessorSend { did: self.dht.did });
         if self.dht.did != successor_min {
             for s in successor_list {
-                tracing::debug!("STABILIZATION notify_predecessor: {:?}", s);
                 let payload =
                     MessagePayload::new_send(msg.clone(), self.transport.session_sk(), s, s)?;
-                self.transport.send_payload(payload).await?;
+                let tx_id = payload.transaction.tx_id;
+                let target_state = self
+                    .transport
+                    .get_connection(s)
+                    .map(|conn| conn.webrtc_connection_state());
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    successor = %s,
+                    tx_id = %tx_id,
+                    target_state = ?target_state,
+                    "STABILIZATION notify_predecessor send start"
+                );
+                if let Err(e) = self.transport.send_payload(payload).await {
+                    tracing::error!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        successor = %s,
+                        tx_id = %tx_id,
+                        target_state = ?target_state,
+                        error = ?e,
+                        "STABILIZATION notify_predecessor send failed"
+                    );
+                    return Err(e);
+                }
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    successor = %s,
+                    tx_id = %tx_id,
+                    "STABILIZATION notify_predecessor send complete"
+                );
             }
             Ok(())
         } else {
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                successor = %successor_min,
+                "STABILIZATION notify_predecessor skip local successor"
+            );
             Ok(())
         }
     }
@@ -145,7 +371,14 @@ impl Stabilizer {
     async fn fix_fingers(&self) -> Result<()> {
         match self.dht.fix_fingers() {
             Ok(action) => match action {
-                PeerRingAction::None => Ok(()),
+                PeerRingAction::None => {
+                    tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        "STABILIZATION fix_fingers no remote action"
+                    );
+                    Ok(())
+                }
                 PeerRingAction::RemoteAction(
                     closest_predecessor,
                     PeerRingRemoteAction::FindSuccessorForFix {
@@ -153,7 +386,6 @@ impl Stabilizer {
                         index,
                     },
                 ) => {
-                    tracing::debug!("STABILIZATION fix_fingers: {:?}", finger_did);
                     let msg = Message::FindSuccessorSend(FindSuccessorSend {
                         did: finger_did,
                         then: FindSuccessorThen::Report(
@@ -167,7 +399,44 @@ impl Stabilizer {
                         closest_predecessor,
                         closest_predecessor,
                     )?;
-                    self.transport.send_payload(payload).await?;
+                    let tx_id = payload.transaction.tx_id;
+                    let next_hop_state = self
+                        .transport
+                        .get_connection(closest_predecessor)
+                        .map(|conn| conn.webrtc_connection_state());
+                    tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        next_hop = %closest_predecessor,
+                        next_hop_state = ?next_hop_state,
+                        finger_did = %finger_did,
+                        index,
+                        tx_id = %tx_id,
+                        "STABILIZATION fix_fingers send start"
+                    );
+                    if let Err(e) = self.transport.send_payload(payload).await {
+                        tracing::error!(
+                            target: "rings_core::dht::stabilization",
+                            local = %self.dht.did,
+                            next_hop = %closest_predecessor,
+                            next_hop_state = ?next_hop_state,
+                            finger_did = %finger_did,
+                            index,
+                            tx_id = %tx_id,
+                            error = ?e,
+                            "STABILIZATION fix_fingers send failed"
+                        );
+                        return Err(e);
+                    }
+                    tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        next_hop = %closest_predecessor,
+                        finger_did = %finger_did,
+                        index,
+                        tx_id = %tx_id,
+                        "STABILIZATION fix_fingers send complete"
+                    );
                     Ok(())
                 }
                 _ => {
@@ -184,17 +453,58 @@ impl Stabilizer {
 
     /// Call stabilization from correct chord implementation
     pub async fn correct_stabilize(&self) -> Result<()> {
-        if let PeerRingAction::RemoteAction(
-            next,
-            PeerRingRemoteAction::QueryForSuccessorListAndPred,
-        ) = self.dht.pre_stabilize()?
-        {
-            self.transport
-                .send_direct_message(
-                    Message::QueryForTopoInfoSend(QueryForTopoInfoSend::new_for_stab(next)),
-                    next,
-                )
-                .await?;
+        match self.dht.pre_stabilize()? {
+            PeerRingAction::RemoteAction(
+                next,
+                PeerRingRemoteAction::QueryForSuccessorListAndPred,
+            ) => {
+                let next_hop_state = self
+                    .transport
+                    .get_connection(next)
+                    .map(|conn| conn.webrtc_connection_state());
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    next = %next,
+                    next_hop_state = ?next_hop_state,
+                    "STABILIZATION correct_stabilize query start"
+                );
+                match self
+                    .transport
+                    .send_direct_message(
+                        Message::QueryForTopoInfoSend(QueryForTopoInfoSend::new_for_stab(next)),
+                        next,
+                    )
+                    .await
+                {
+                    Ok(tx_id) => tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        next = %next,
+                        tx_id = %tx_id,
+                        "STABILIZATION correct_stabilize query complete"
+                    ),
+                    Err(e) => {
+                        tracing::error!(
+                            target: "rings_core::dht::stabilization",
+                            local = %self.dht.did,
+                            next = %next,
+                            next_hop_state = ?next_hop_state,
+                            error = ?e,
+                            "STABILIZATION correct_stabilize query failed"
+                        );
+                        return Err(e);
+                    }
+                }
+            }
+            action => {
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    action = ?action,
+                    "STABILIZATION correct_stabilize no remote query"
+                );
+            }
         }
         Ok(())
     }
diff --git a/crates/core/src/swarm/callback.rs b/crates/core/src/swarm/callback.rs
index 5d850c852..f7d645705 100644
--- a/crates/core/src/swarm/callback.rs
+++ b/crates/core/src/swarm/callback.rs
@@ -96,6 +96,14 @@ impl InnerSwarmCallback {
         let Some(attempt) = self.pending_attempt else {
             return Ok(false);
         };
+        if attempt.peer() != did {
+            tracing::warn!(
+                "ignoring data-channel open for {did}; pending attempt belongs to {}",
+                attempt.peer()
+            );
+            self.transport.cancel_pending_connection(attempt).await?;
+            return Ok(false);
+        }
         if !self.transport.promote_pending_connection(attempt)? {
             return Ok(false);
         }
@@ -111,6 +119,37 @@ impl InnerSwarmCallback {
         Ok(true)
     }
 
+    fn is_local_did_event(&self, did: Did, operation: &str) -> bool {
+        if did != self.transport.dht.did {
+            return false;
+        }
+        tracing::warn!("ignoring {operation} for local DID {did}");
+        true
+    }
+
+    async fn cancel_mismatched_pending_connection(
+        &self,
+        did: Did,
+        operation: &str,
+    ) -> Result {
+        let Some(attempt) = self.pending_attempt else {
+            return Ok(false);
+        };
+        if attempt.peer() == did {
+            return Ok(false);
+        }
+        tracing::warn!(
+            "ignoring {operation} for {did}; pending attempt belongs to {}",
+            attempt.peer()
+        );
+        if self.transport.cancel_pending_connection(attempt).await? {
+            self.transport
+                .record_peer_disconnected(attempt.peer())
+                .await;
+        }
+        Ok(true)
+    }
+
     async fn handle_payload(
         &self,
         cid: &str,
@@ -222,6 +261,15 @@ impl TransportCallback for InnerSwarmCallback {
             tracing::warn!("on_peer_connection_state_change parse did failed: {}", cid);
             return Ok(());
         };
+        if self
+            .cancel_mismatched_pending_connection(did, "connection state change")
+            .await?
+        {
+            return Ok(());
+        }
+        if self.is_local_did_event(did, "connection state change") {
+            return Ok(());
+        }
 
         match s {
             // ICE `Connected` is not enough for routing: admission happens only
@@ -275,6 +323,15 @@ impl TransportCallback for InnerSwarmCallback {
             tracing::warn!("on_data_channel_open parse did failed: {}", cid);
             return Ok(());
         };
+        if self
+            .cancel_mismatched_pending_connection(did, "data-channel open")
+            .await?
+        {
+            return Ok(());
+        }
+        if self.is_local_did_event(did, "data-channel open") {
+            return Ok(());
+        }
 
         if !self.admit_pending_connection(did).await? && !self.transport.is_admitted_connection(did)
         {
@@ -288,6 +345,15 @@ impl TransportCallback for InnerSwarmCallback {
             tracing::warn!("on_data_channel_close parse did failed: {}", cid);
             return Ok(());
         };
+        if self
+            .cancel_mismatched_pending_connection(did, "data-channel close")
+            .await?
+        {
+            return Ok(());
+        }
+        if self.is_local_did_event(did, "data-channel close") {
+            return Ok(());
+        }
 
         // The data channel closing is a reliable signal that the peer is gone
         // (e.g. it closed the connection), so tear the connection down now
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index 3cb51da5b..f5999c728 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -2,9 +2,14 @@ use std::collections::BTreeMap;
 use std::collections::BTreeSet;
 use std::sync::Arc;
 use std::sync::Mutex;
+use std::time::Duration;
 
 use async_trait::async_trait;
 use bytes::Bytes;
+use futures::future::FutureExt;
+use futures::pin_mut;
+use futures::select;
+use futures_timer::Delay;
 use rings_transport::connection_ref::ConnectionRef;
 #[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 pub use rings_transport::connections::DummyConnection as ConnectionOwner;
@@ -69,7 +74,8 @@ pub(crate) const STORAGE_LOOKUP_OBSERVATION_CAPACITY: usize = 1024;
 /// Maximum number of peers that may be handshaking before a data channel opens.
 pub(crate) const DEFAULT_PENDING_CONNECTION_CAPACITY: usize = 32;
 
-const PENDING_CONNECTION_TIMEOUT_MS: i64 = 15_000;
+const PENDING_CONNECTION_TIMEOUT_MS: i64 = 180_000;
+const DATA_CHANNEL_OPEN_TIMEOUT: Duration = Duration::from_secs(8);
 
 /// Identifies one pending handshake for a peer.
 ///
@@ -82,6 +88,12 @@ pub(crate) struct PendingConnectionAttempt {
     generation: u64,
 }
 
+impl PendingConnectionAttempt {
+    pub(crate) fn peer(self) -> Did {
+        self.peer
+    }
+}
+
 #[derive(Debug)]
 struct PendingPeer {
     generation: u64,
@@ -120,10 +132,13 @@ impl PendingPeerPool {
             peer,
             generation: self.next_generation,
         };
-        self.peers.insert(peer, PendingPeer {
-            generation: attempt.generation,
-            admitted_at_ms: now_ms,
-        });
+        self.peers.insert(
+            peer,
+            PendingPeer {
+                generation: attempt.generation,
+                admitted_at_ms: now_ms,
+            },
+        );
         Ok(attempt)
     }
 
@@ -633,10 +648,13 @@ impl SwarmTransport {
         let now = storage_lookup_observation_now_ms();
         evict_storage_lookup_observations(&mut observations, now);
         reserve_storage_lookup_observation_slot(&mut observations);
-        observations.insert(key, StorageLookupObservation {
-            observed_at_ms: now,
-            misses: BTreeSet::new(),
-        });
+        observations.insert(
+            key,
+            StorageLookupObservation {
+                observed_at_ms: now,
+                misses: BTreeSet::new(),
+            },
+        );
         Ok(())
     }
 
@@ -1028,20 +1046,72 @@ impl SwarmTransport {
     /// See more information about [rings_transport::core::transport::WebrtcConnectionState].
     /// See also method webrtc_wait_for_data_channel_open [rings_transport::core::transport::ConnectionInterface].
     pub async fn get_and_check_connection(&self, peer: Did) -> Option {
+        self.get_and_check_connection_with_timeout(peer, DATA_CHANNEL_OPEN_TIMEOUT)
+            .await
+    }
+
+    pub(crate) async fn get_and_check_connection_with_timeout(
+        &self,
+        peer: Did,
+        wait_timeout: Duration,
+    ) -> Option {
         let conn = self.get_connection(peer)?;
 
-        if let Err(e) = conn.connection.webrtc_wait_for_data_channel_open().await {
+        let initial_state = conn.webrtc_connection_state();
+        tracing::debug!(
+            target: "rings_core::transport::data_channel",
+            local = %self.dht.did,
+            peer = %peer,
+            state = ?initial_state,
+            timeout_ms = wait_timeout.as_millis(),
+            "waiting for active connection data channel"
+        );
+
+        let failure = {
+            let wait_for_open = conn.connection.webrtc_wait_for_data_channel_open().fuse();
+            let timeout = Delay::new(wait_timeout).fuse();
+            pin_mut!(wait_for_open, timeout);
+
+            select! {
+                result = wait_for_open => result.err().map(|e| format!("transport_wait_failed: {e:?}")),
+                _ = timeout => Some("data_channel_open_wait_timeout".to_string()),
+            }
+        };
+
+        if let Some(reason) = failure {
+            let final_state = conn.webrtc_connection_state();
             tracing::warn!(
-                "[get_and_check_connection] connection {peer} data channel not open, will be dropped, reason: {e:?}"
+                target: "rings_core::transport::data_channel",
+                local = %self.dht.did,
+                peer = %peer,
+                initial_state = ?initial_state,
+                final_state = ?final_state,
+                timeout_ms = wait_timeout.as_millis(),
+                reason = %reason,
+                "[get_and_check_connection] connection data channel not open, will be dropped"
             );
 
             if let Err(e) = self.disconnect(peer).await {
-                tracing::error!("Failed on close connection {peer}: {e:?}");
+                tracing::error!(
+                    target: "rings_core::transport::data_channel",
+                    local = %self.dht.did,
+                    peer = %peer,
+                    reason = %reason,
+                    "failed to close connection after data-channel wait failure: {e:?}"
+                );
             }
 
             return None;
         };
 
+        tracing::debug!(
+            target: "rings_core::transport::data_channel",
+            local = %self.dht.did,
+            peer = %peer,
+            state = ?conn.webrtc_connection_state(),
+            "active connection data channel is open"
+        );
+
         Some(conn)
     }
 
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index d6f352649..1d4c4a89f 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -3,6 +3,7 @@ use std::sync::Arc;
 use std::sync::Mutex;
 
 use async_trait::async_trait;
+use rings_transport::core::callback::TransportCallback;
 
 use super::*;
 use crate::dht::successor::SuccessorReader;
@@ -227,6 +228,58 @@ async fn pending_offer_is_not_routable_or_visible_to_dht() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn local_did_lifecycle_callbacks_are_ignored() -> Result<()> {
+    let transport = Arc::new(transport_with_measure(Arc::new(
+        RecordingMeasure::default(),
+    ))?);
+    let callback = InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback));
+    let local_cid = transport.dht.did.to_string();
+
+    callback
+        .on_data_channel_open(&local_cid)
+        .await
+        .map_err(|error| Error::InvalidMessage(error.to_string()))?;
+    callback
+        .on_peer_connection_state_change(&local_cid, WebrtcConnectionState::Closed)
+        .await
+        .map_err(|error| Error::InvalidMessage(error.to_string()))?;
+    callback
+        .on_data_channel_close(&local_cid)
+        .await
+        .map_err(|error| Error::InvalidMessage(error.to_string()))?;
+
+    assert_eq!(transport.pending_connection_count()?, 0);
+    assert!(transport.get_connection(transport.dht.did).is_none());
+    Ok(())
+}
+
+#[tokio::test]
+async fn mismatched_pending_callback_cancels_attempt_without_admission() -> Result<()> {
+    let transport = Arc::new(transport_with_measure(Arc::new(
+        RecordingMeasure::default(),
+    ))?);
+    let peer = SecretKey::random().address().into();
+    let callback = InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback));
+    let (attempt, _offer) = transport
+        .prepare_connection_offer_with_attempt(peer, callback)
+        .await?;
+    let mismatched_callback =
+        InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback))
+            .with_pending_connection_attempt(attempt);
+    let local_cid = transport.dht.did.to_string();
+
+    mismatched_callback
+        .on_data_channel_open(&local_cid)
+        .await
+        .map_err(|error| Error::InvalidMessage(error.to_string()))?;
+
+    assert_eq!(transport.pending_connection_count()?, 0);
+    assert!(transport.get_connection(peer).is_none());
+    assert!(transport.get_connection(transport.dht.did).is_none());
+    Ok(())
+}
+
 #[test]
 fn connection_offer_protocol_mode_includes_storage_redundancy() -> Result<()> {
     let transport = transport_with_measure(Arc::new(RecordingMeasure::default()))?;
@@ -276,11 +329,14 @@ async fn disconnected_observation_is_once_per_connection_epoch() -> Result<()> {
     transport.record_peer_connected(peer).await;
     transport.record_peer_disconnected(peer).await;
 
-    assert_eq!(measure.snapshot_counters()?.as_slice(), &[
-        (peer, MeasureCounter::Disconnected),
-        (peer, MeasureCounter::Connect),
-        (peer, MeasureCounter::Disconnected),
-    ]);
+    assert_eq!(
+        measure.snapshot_counters()?.as_slice(),
+        &[
+            (peer, MeasureCounter::Disconnected),
+            (peer, MeasureCounter::Connect),
+            (peer, MeasureCounter::Disconnected),
+        ]
+    );
 
     Ok(())
 }
diff --git a/crates/core/src/tests/default/test_connection.rs b/crates/core/src/tests/default/test_connection.rs
index d204a0a4d..149e8aeca 100644
--- a/crates/core/src/tests/default/test_connection.rs
+++ b/crates/core/src/tests/default/test_connection.rs
@@ -1,5 +1,9 @@
+#[cfg(feature = "dummy")]
+use rings_transport::connections::dummy_controlled;
 use rings_transport::core::transport::WebrtcConnectionState;
 
+#[cfg(feature = "dummy")]
+use crate::dht::successor::SuccessorReader;
 use crate::ecc::tests::gen_ordered_keys;
 use crate::ecc::SecretKey;
 use crate::tests::default::assert_no_more_msg;
@@ -113,3 +117,38 @@ async fn test_handshake_on_both_sides(key1: SecretKey, key2: SecretKey, key3: Se
         WebrtcConnectionState::Connected,
     )
 }
+
+#[cfg(feature = "dummy")]
+#[tokio::test]
+async fn dummy_mismatched_data_channel_open_does_not_admit_peer() {
+    dummy_controlled::enable(true);
+
+    let keys = gen_ordered_keys(2);
+    let node1 = prepare_node(keys[0]).await;
+    let node2 = prepare_node(keys[1]).await;
+
+    let offer = node1.swarm.create_offer(node2.did()).await.unwrap();
+    assert!(node1.swarm.transport.get_connection(node2.did()).is_none());
+    assert_eq!(node1.swarm.transport.pending_connection_count().unwrap(), 1);
+
+    let answer = node2.swarm.answer_offer(offer).await.unwrap();
+    node1.swarm.accept_answer(answer).await.unwrap();
+
+    assert!(
+        dummy_controlled::deliver_next_data_channel_open_with_cid(node1.did().to_string()).await
+    );
+
+    assert_eq!(node1.swarm.transport.pending_connection_count().unwrap(), 0);
+    assert!(node1.swarm.transport.get_connection(node2.did()).is_none());
+    assert!(node1.swarm.transport.get_connection(node1.did()).is_none());
+    assert!(!node1
+        .dht()
+        .successors()
+        .list()
+        .unwrap()
+        .contains(&node2.did()));
+
+    _ = node1.swarm.disconnect(node2.did()).await;
+    _ = node2.swarm.disconnect(node1.did()).await;
+    dummy_controlled::enable(false);
+}
diff --git a/crates/core/src/tests/default/test_stabilization.rs b/crates/core/src/tests/default/test_stabilization.rs
index 66ca02d34..255f05698 100644
--- a/crates/core/src/tests/default/test_stabilization.rs
+++ b/crates/core/src/tests/default/test_stabilization.rs
@@ -3,6 +3,8 @@ use std::sync::Arc;
 use crate::dht::entry::Entry;
 use crate::dht::entry::EntryKind;
 use crate::ecc::SecretKey;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use crate::error::Error;
 use crate::error::Result;
 use crate::session::SessionSk;
 use crate::storage::MemStorage;
@@ -12,6 +14,30 @@ use crate::tests::default::wait_for_predecessor;
 use crate::tests::default::wait_for_successor;
 use crate::tests::default::Node;
 use crate::tests::manually_establish_connection;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use rings_transport::connections::dummy_controlled;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use tokio::time::timeout;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use tokio::time::Duration;
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+struct PendingDataChannelWaitGuard;
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+impl PendingDataChannelWaitGuard {
+    fn new() -> Self {
+        dummy_controlled::set_wait_for_data_channel_open_pending(true);
+        Self
+    }
+}
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+impl Drop for PendingDataChannelWaitGuard {
+    fn drop(&mut self) {
+        dummy_controlled::set_wait_for_data_channel_open_pending(false);
+    }
+}
 
 #[tokio::test]
 async fn test_stabilization_once() -> Result<()> {
@@ -37,6 +63,60 @@ async fn test_stabilization_once() -> Result<()> {
     Ok(())
 }
 
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+#[tokio::test]
+async fn get_and_check_connection_times_out_wedged_data_channel_wait() -> Result<()> {
+    let key1 = SecretKey::random();
+    let key2 = SecretKey::random();
+    let node1 = prepare_node(key1).await;
+    let node2 = prepare_node(key2).await;
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+
+    wait_for_successor(&node1, node2.did()).await?;
+
+    let _guard = PendingDataChannelWaitGuard::new();
+    let conn = timeout(
+        Duration::from_secs(1),
+        node1
+            .swarm
+            .transport
+            .get_and_check_connection_with_timeout(node2.did(), Duration::from_millis(20)),
+    )
+    .await
+    .map_err(|_| Error::PromiseStateTimeout)?;
+
+    assert!(conn.is_none());
+    Ok(())
+}
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+#[tokio::test]
+async fn stabilize_step_timeout_bounds_wedged_data_channel_wait() -> Result<()> {
+    let mut key1 = SecretKey::random();
+    let mut key2 = SecretKey::random();
+    if key1.address() < key2.address() {
+        (key1, key2) = (key2, key1)
+    }
+    let node1 = prepare_node(key1).await;
+    let node2 = prepare_node(key2).await;
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+
+    wait_for_successor(&node1, node2.did()).await?;
+
+    let _guard = PendingDataChannelWaitGuard::new();
+    timeout(
+        Duration::from_secs(1),
+        node1
+            .swarm
+            .stabilizer()
+            .stabilize_with_step_timeout(Duration::from_millis(20)),
+    )
+    .await
+    .map_err(|_| Error::PromiseStateTimeout)??;
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn stabilize_republishes_local_entries_to_missing_affine_owners() -> Result<()> {
     let key = SecretKey::random();
diff --git a/crates/node/Cargo.toml b/crates/node/Cargo.toml
index b91335835..427c50608 100644
--- a/crates/node/Cargo.toml
+++ b/crates/node/Cargo.toml
@@ -101,7 +101,7 @@ strum = "0.25.0"
 thiserror = "1"
 tracing = "0.1.37"
 tracing-log = "0.1.3"
-tracing-subscriber = { version = "0.3.15", features = ["ansi"] }
+tracing-subscriber = { version = "0.3.15", features = ["ansi", "env-filter"] }
 uuid = { version = "0.8.2" }
 
 # node
diff --git a/crates/node/src/error.rs b/crates/node/src/error.rs
index 20280ee8f..597ff67d3 100644
--- a/crates/node/src/error.rs
+++ b/crates/node/src/error.rs
@@ -144,6 +144,14 @@ pub enum Error {
     /// The node configuration is structurally invalid.
     #[error("Invalid configuration: {0}")]
     InvalidConfig(String) = 812,
+    /// A periodic registration heartbeat did not complete before its deadline.
+    #[error("{task} registration task timed out after {timeout:?}")]
+    RegistrationTimeout {
+        /// Stable task name.
+        task: &'static str,
+        /// Deadline used for this registration attempt.
+        timeout: std::time::Duration,
+    } = 813,
     /// Creating a file on disk failed.
     #[error("Create File Error: {0}")]
     CreateFileError(String) = 900,
diff --git a/crates/node/src/logging.rs b/crates/node/src/logging.rs
index 4977f9647..d76e1a53b 100644
--- a/crates/node/src/logging.rs
+++ b/crates/node/src/logging.rs
@@ -142,6 +142,7 @@ pub fn set_panic_hook() {
 pub mod node {
     use tracing_subscriber::filter;
     use tracing_subscriber::fmt;
+    use tracing_subscriber::EnvFilter;
     use tracing_subscriber::Layer;
 
     use super::*;
@@ -153,12 +154,23 @@ pub mod node {
 
         let subscriber = Registry::default();
         let level_filter = filter::LevelFilter::from_level(level.into());
+        let filter = match std::env::var("RINGS_LOG_FILTER") {
+            Ok(spec) if !spec.trim().is_empty() => EnvFilter::try_new(spec.trim())
+                .unwrap_or_else(|err| {
+                    eprintln!(
+                        "invalid RINGS_LOG_FILTER '{}': {}; falling back to {}",
+                        spec, err, level_filter
+                    );
+                    EnvFilter::new(level_filter.to_string())
+                }),
+            _ => EnvFilter::new(level_filter.to_string()),
+        };
 
         // Stderr
         let subscriber = subscriber.with(
             fmt::layer()
                 .with_writer(std::io::stderr)
-                .with_filter(level_filter),
+                .with_filter(filter),
         );
         // Enable log compatible layer to convert log record to tracing span.
         // We will ignore any errors that returned by this functions.
diff --git a/crates/node/src/processor/mod.rs b/crates/node/src/processor/mod.rs
index fd91763fe..726d35d8e 100644
--- a/crates/node/src/processor/mod.rs
+++ b/crates/node/src/processor/mod.rs
@@ -5,6 +5,9 @@ use std::sync::Arc;
 use std::time::Duration;
 
 use futures::future::join_all;
+use futures::future::select;
+use futures::future::Either;
+use futures::FutureExt;
 use rings_core::chunk::ReassemblyLimits;
 use rings_core::dht::Did;
 use rings_core::dht::EntryStorage;
@@ -89,6 +92,7 @@ pub use config::ProcessorConfigSerialized;
 
 const DHT_LOOKUP_CACHE_POLL_INTERVAL: Duration = Duration::from_millis(50);
 const DHT_LOOKUP_CACHE_POLL_ATTEMPTS: usize = 40;
+const MAX_REGISTRATION_ATTEMPT_TIMEOUT: Duration = Duration::from_secs(10);
 
 #[cfg(not(feature = "browser"))]
 async fn sleep_dht_lookup_poll_interval(interval: Duration) -> Result<()> {
@@ -105,6 +109,14 @@ async fn sleep_dht_lookup_poll_interval(interval: Duration) -> Result<()> {
     Ok(())
 }
 
+fn registration_attempt_timeout(interval: Duration) -> Duration {
+    if interval.is_zero() || interval > MAX_REGISTRATION_ATTEMPT_TIMEOUT {
+        MAX_REGISTRATION_ATTEMPT_TIMEOUT
+    } else {
+        interval
+    }
+}
+
 /// Processor for rings-node rpc server.
 ///
 /// Cloning shares the same node handle; publishes from any clone are serialized
@@ -323,9 +335,32 @@ impl Processor {
         directory::build_onion_proxy_route(self, proxy, target).await
     }
 
+    async fn run_registration_once_with_timeout(
+        &self,
+        task: &dyn RegistrationTask,
+        timeout: Duration,
+    ) -> Result<()> {
+        let context = self.registration_context();
+        let registration = task.register_once(&context).fuse();
+        let timeout_timer = sleep_registration_interval(timeout).fuse();
+        futures::pin_mut!(registration, timeout_timer);
+
+        match select(registration, timeout_timer).await {
+            Either::Left((result, _)) => result,
+            Either::Right((timer_result, _)) => {
+                timer_result?;
+                Err(Error::RegistrationTimeout {
+                    task: task.name(),
+                    timeout,
+                })
+            }
+        }
+    }
+
     async fn registration_task_daemon(&self, task: &dyn RegistrationTask) {
         loop {
-            if let Err(error) = task.register_once(&self.registration_context()).await {
+            let timeout = registration_attempt_timeout(task.interval());
+            if let Err(error) = self.run_registration_once_with_timeout(task, timeout).await {
                 tracing::warn!("Failed to run {} registration task: {error:?}", task.name());
             }
             if let Err(error) = sleep_registration_interval(task.interval()).await {
diff --git a/crates/node/src/processor/tests/test_network.rs b/crates/node/src/processor/tests/test_network.rs
index b9cffcd04..8c767fc52 100644
--- a/crates/node/src/processor/tests/test_network.rs
+++ b/crates/node/src/processor/tests/test_network.rs
@@ -59,12 +59,26 @@ async fn online_node_type_is_configurable() {
 
 #[tokio::test]
 async fn test_processor_create_offer() {
-    let peer_did = SecretKey::random().address().into();
-    let processor = prepare_processor().await;
-    processor.swarm.create_offer(peer_did).await.unwrap();
-    let conn_dids = processor.swarm.peers();
+    let _network_guard = network_test_guard().await;
+    let callback1 = test_callback();
+    let callback2 = test_callback();
+    let p1 = prepare_processor().await;
+    let p2 = prepare_processor().await;
+
+    p1.swarm.set_callback(callback1.clone()).unwrap();
+    p2.swarm.set_callback(callback2.clone()).unwrap();
+
+    let offer = p1.swarm.create_offer(p2.did()).await.unwrap();
+    assert!(p1.swarm.peers().is_empty());
+
+    let answer = p2.swarm.answer_offer(offer).await.unwrap();
+    p1.swarm.accept_answer(answer).await.unwrap();
+    wait_processors_connected(&p1, &p2, &callback1, &callback2).await;
+
+    let conn_dids = p1.swarm.peers();
     assert_eq!(conn_dids.len(), 1);
-    assert_eq!(conn_dids.first().unwrap().did, peer_did.to_string());
+    assert_eq!(conn_dids.first().unwrap().did, p2.did().to_string());
+    assert_eq!(conn_dids.first().unwrap().state, "Connected");
 }
 
 #[tokio::test]
@@ -83,15 +97,7 @@ async fn test_processor_handshake_msg() {
     let did2 = p2.did();
 
     let offer = p1.swarm.create_offer(p2.did()).await.unwrap();
-    assert_eq!(
-        p1.swarm
-            .peers()
-            .into_iter()
-            .find(|peer| peer.did == p2.did().to_string())
-            .unwrap()
-            .state,
-        "New"
-    );
+    assert!(p1.swarm.peers().is_empty());
 
     let answer = p2.swarm.answer_offer(offer).await.unwrap();
     p1.swarm.accept_answer(answer).await.unwrap();
@@ -194,12 +200,9 @@ async fn provider_exposes_sent_and_received_peer_measurements() {
     assert!(provider_measurement.evidence.sent >= 1);
 
     let rpc_value = provider
-        .request(
-            Method::PeerMeasurement,
-            PeerMeasurementRequest {
-                did: p2.did().to_string(),
-            },
-        )
+        .request(Method::PeerMeasurement, PeerMeasurementRequest {
+            did: p2.did().to_string(),
+        })
         .await
         .unwrap();
     let rpc_measurement: PeerMeasurementResponse = serde_json::from_value(rpc_value).unwrap();
diff --git a/crates/node/src/processor/tests/test_registry.rs b/crates/node/src/processor/tests/test_registry.rs
index 2d1e5e3ac..97891a9a7 100644
--- a/crates/node/src/processor/tests/test_registry.rs
+++ b/crates/node/src/processor/tests/test_registry.rs
@@ -1,6 +1,42 @@
 use super::common::*;
 use super::*;
 
+struct HangingRegistration;
+
+#[async_trait]
+impl RegistrationTask for HangingRegistration {
+    fn name(&self) -> &'static str {
+        "hanging-test"
+    }
+
+    fn interval(&self) -> Duration {
+        Duration::from_millis(20)
+    }
+
+    async fn register_once(&self, _context: &RegistrationContext<'_>) -> Result<()> {
+        futures::future::pending().await
+    }
+}
+
+#[tokio::test]
+async fn registration_attempt_timeout_returns_instead_of_hanging() -> Result<()> {
+    let processor = prepare_processor().await;
+    let task = HangingRegistration;
+    let timeout = Duration::from_millis(20);
+    let result = processor
+        .run_registration_once_with_timeout(&task, timeout)
+        .await;
+
+    assert!(matches!(
+        result,
+        Err(Error::RegistrationTimeout {
+            task: "hanging-test",
+            timeout: observed_timeout,
+        }) if observed_timeout == timeout
+    ));
+    Ok(())
+}
+
 #[tokio::test]
 async fn custom_registration_task_publishes_through_shared_dht_sink() -> Result<()> {
     let topic = "custom_registration_task";
diff --git a/crates/transport/src/callback.rs b/crates/transport/src/callback.rs
index 78e507391..e798d4215 100644
--- a/crates/transport/src/callback.rs
+++ b/crates/transport/src/callback.rs
@@ -31,16 +31,24 @@ impl InnerTransportCallback {
 
     /// Notify the data channel is open.
     pub async fn on_data_channel_open(&self) {
+        self.on_data_channel_open_with_cid(&self.cid).await;
+    }
+
+    pub(crate) async fn on_data_channel_open_with_cid(&self, cid: &str) {
         self.data_channel_state_notifier.wake();
-        if let Err(e) = self.callback.on_data_channel_open(&self.cid).await {
+        if let Err(e) = self.callback.on_data_channel_open(cid).await {
             tracing::error!("Callback on_data_channel_open failed: {e:?}");
         }
     }
 
     /// Notify the data channel is close.
     pub async fn on_data_channel_close(&self) {
+        self.on_data_channel_close_with_cid(&self.cid).await;
+    }
+
+    pub(crate) async fn on_data_channel_close_with_cid(&self, cid: &str) {
         self.data_channel_state_notifier.wake();
-        if let Err(e) = self.callback.on_data_channel_close(&self.cid).await {
+        if let Err(e) = self.callback.on_data_channel_close(cid).await {
             tracing::error!("Callback on_data_channel_close failed: {e:?}");
         }
     }
@@ -57,11 +65,16 @@ impl InnerTransportCallback {
 
     /// This method is invoked when the state of connection has changed.
     pub async fn on_peer_connection_state_change(&self, s: WebrtcConnectionState) {
-        if let Err(e) = self
-            .callback
-            .on_peer_connection_state_change(&self.cid, s)
-            .await
-        {
+        self.on_peer_connection_state_change_with_cid(&self.cid, s)
+            .await;
+    }
+
+    pub(crate) async fn on_peer_connection_state_change_with_cid(
+        &self,
+        cid: &str,
+        s: WebrtcConnectionState,
+    ) {
+        if let Err(e) = self.callback.on_peer_connection_state_change(cid, s).await {
             tracing::error!("Callback on_peer_connection_state_change failed: {e:?}");
         }
     }
diff --git a/crates/transport/src/connections/dummy/mod.rs b/crates/transport/src/connections/dummy/mod.rs
index 5063388e2..1b8f08b9a 100644
--- a/crates/transport/src/connections/dummy/mod.rs
+++ b/crates/transport/src/connections/dummy/mod.rs
@@ -64,6 +64,12 @@ thread_local! {
     /// through `do_send_payload` and exercise real reassembly. Thread-local for the same isolation
     /// reason as the controlled queue.
     static MAX_MESSAGE_SIZE: Cell = const { Cell::new(0) };
+    /// Test-only per-thread override for the next lifecycle callback's cid. This lets dummy tests
+    /// exercise malformed transport events without changing the production callback path.
+    static NEXT_CALLBACK_CID: RefCell> = const { RefCell::new(None) };
+    /// Test-only per-thread switch that makes `webrtc_wait_for_data_channel_open` stay pending.
+    /// This models a lifecycle notifier/callback wedge after a connection was already admitted.
+    static WAIT_FOR_DATA_CHANNEL_OPEN_PENDING: Cell = const { Cell::new(false) };
 }
 
 /// Test-only controlled delivery scheduler. When enabled (per thread), dummy
@@ -76,6 +82,8 @@ pub mod controlled {
     use super::CONTROLLED;
     use super::DELIVERY;
     use super::MAX_MESSAGE_SIZE;
+    use super::NEXT_CALLBACK_CID;
+    use super::WAIT_FOR_DATA_CHANNEL_OPEN_PENDING;
 
     /// Turn the controlled scheduler on/off for the current thread. Turning it
     /// off clears this thread's queue.
@@ -83,6 +91,10 @@ pub mod controlled {
         CONTROLLED.with(|c| c.set(on));
         if !on {
             DELIVERY.with(|q| q.borrow_mut().clear());
+            NEXT_CALLBACK_CID.with(|next| {
+                *next.borrow_mut() = None;
+            });
+            WAIT_FOR_DATA_CHANNEL_OPEN_PENDING.with(|pending| pending.set(false));
         }
     }
 
@@ -92,6 +104,21 @@ pub mod controlled {
         MAX_MESSAGE_SIZE.with(|m| m.set(n));
     }
 
+    /// Test hook: rewrite the next queued lifecycle callback to use `cid`.
+    ///
+    /// This applies only to peer-state and data-channel events delivered through
+    /// [`deliver`]. Message events keep their real connection id.
+    pub fn set_next_callback_cid(cid: impl Into) {
+        NEXT_CALLBACK_CID.with(|next| {
+            *next.borrow_mut() = Some(cid.into());
+        });
+    }
+
+    /// Test hook: force `webrtc_wait_for_data_channel_open` on this thread to never complete.
+    pub fn set_wait_for_data_channel_open_pending(on: bool) {
+        WAIT_FOR_DATA_CHANNEL_OPEN_PENDING.with(|pending| pending.set(on));
+    }
+
     /// Test hook: number of data-channel messages `send_message` has dispatched on this thread.
     /// Paired with [`reset_sent_count`] to assert that a failed send enqueued nothing.
     pub fn sent_count() -> usize {
@@ -113,24 +140,60 @@ pub mod controlled {
     /// index is out of range or the target connection is gone.
     pub async fn deliver(index: usize) -> bool {
         let entry = DELIVERY.with(|q| q.borrow_mut().remove(index));
-        let Some((rand_id, event)) = entry else {
+        let Some((rand_id, mut event)) = entry else {
             return false;
         };
         let Some(conn) = CONNS.get(&rand_id).map(|c| c.clone()) else {
             return false;
         };
+        if event.is_lifecycle_event() {
+            if let Some(cid) = NEXT_CALLBACK_CID.with(|next| next.borrow_mut().take()) {
+                event.set_callback_cid(cid);
+            }
+        }
         conn.handle_event(event).await;
         true
     }
+
+    /// Deliver the next queued data-channel-open event with a rewritten callback cid.
+    pub async fn deliver_next_data_channel_open_with_cid(cid: impl Into) -> bool {
+        let index = DELIVERY.with(|q| {
+            q.borrow()
+                .iter()
+                .position(|(_, event)| matches!(event, super::Event::DataChannelOpen(_)))
+        });
+        let Some(index) = index else {
+            return false;
+        };
+        set_next_callback_cid(cid);
+        deliver(index).await
+    }
 }
 
 enum Event {
-    PeerConnectionStateChange(WebrtcConnectionState),
-    DataChannelOpen,
-    DataChannelClose,
+    PeerConnectionStateChange(WebrtcConnectionState, Option),
+    DataChannelOpen(Option),
+    DataChannelClose(Option),
     Message(Bytes),
 }
 
+impl Event {
+    fn is_lifecycle_event(&self) -> bool {
+        !matches!(self, Self::Message(_))
+    }
+
+    fn set_callback_cid(&mut self, cid: String) {
+        match self {
+            Self::PeerConnectionStateChange(_, callback_cid)
+            | Self::DataChannelOpen(callback_cid)
+            | Self::DataChannelClose(callback_cid) => {
+                *callback_cid = Some(cid);
+            }
+            Self::Message(_) => {}
+        }
+    }
+}
+
 /// A dummy connection for local testing.
 /// Implements the [ConnectionInterface] trait with no real network.
 pub struct DummyConnection {
@@ -182,11 +245,29 @@ impl DummyConnection {
 
     async fn handle_event(&self, event: Event) {
         match event {
-            Event::PeerConnectionStateChange(state) => {
-                self.callback.on_peer_connection_state_change(state).await
+            Event::PeerConnectionStateChange(state, callback_cid) => {
+                if let Some(cid) = callback_cid {
+                    self.callback
+                        .on_peer_connection_state_change_with_cid(&cid, state)
+                        .await;
+                } else {
+                    self.callback.on_peer_connection_state_change(state).await;
+                }
+            }
+            Event::DataChannelOpen(callback_cid) => {
+                if let Some(cid) = callback_cid {
+                    self.callback.on_data_channel_open_with_cid(&cid).await;
+                } else {
+                    self.callback.on_data_channel_open().await;
+                }
+            }
+            Event::DataChannelClose(callback_cid) => {
+                if let Some(cid) = callback_cid {
+                    self.callback.on_data_channel_close_with_cid(&cid).await;
+                } else {
+                    self.callback.on_data_channel_close().await;
+                }
             }
-            Event::DataChannelOpen => self.callback.on_data_channel_open().await,
-            Event::DataChannelClose => self.callback.on_data_channel_close().await,
             Event::Message(data) => {
                 if SEND_MESSAGE_DELAY && !CONTROLLED.with(|c| c.get()) {
                     random_delay().await;
@@ -241,17 +322,17 @@ impl DummyConnection {
             *webrtc_connection_state = state;
         }
 
-        self.dispatch(Event::PeerConnectionStateChange(state));
+        self.dispatch(Event::PeerConnectionStateChange(state, None));
 
         if state == WebrtcConnectionState::Connected {
-            self.dispatch(Event::DataChannelOpen);
+            self.dispatch(Event::DataChannelOpen(None));
         }
 
         if matches!(
             state,
             WebrtcConnectionState::Closed | WebrtcConnectionState::Disconnected
         ) {
-            self.dispatch(Event::DataChannelClose);
+            self.dispatch(Event::DataChannelClose(None));
         }
     }
 }
@@ -342,6 +423,9 @@ impl ConnectionInterface for DummyConnection {
     }
 
     async fn webrtc_wait_for_data_channel_open(&self) -> Result<()> {
+        if WAIT_FOR_DATA_CHANNEL_OPEN_PENDING.with(|pending| pending.get()) {
+            std::future::pending::<()>().await;
+        }
         // Will pass if the state is connecting to prevent release connection in the `test_handshake_on_both_sides` test.
         // The connecting state means an offer is answered but not accepted by the other side.
         if matches!(
diff --git a/frontend/Cargo.lock b/frontend/Cargo.lock
index 4774c96f1..f57dd3477 100644
--- a/frontend/Cargo.lock
+++ b/frontend/Cargo.lock
@@ -3126,6 +3126,15 @@ dependencies = [
  "zerocopy-derive",
 ]
 
+[[package]]
+name = "matchers"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
+dependencies = [
+ "regex-automata",
+]
+
 [[package]]
 name = "memchr"
 version = "2.8.2"
@@ -5449,10 +5458,14 @@ version = "0.3.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
 dependencies = [
+ "matchers",
  "nu-ansi-term",
+ "once_cell",
+ "regex-automata",
  "sharded-slab",
  "smallvec",
  "thread_local",
+ "tracing",
  "tracing-core",
  "tracing-log 0.2.0",
 ]
diff --git a/frontend/assets/webview-host.js b/frontend/assets/webview-host.js
index 035b22ff1..83ea231fa 100644
--- a/frontend/assets/webview-host.js
+++ b/frontend/assets/webview-host.js
@@ -5,7 +5,7 @@
   let registrationPromise;
   const debugEntries = [];
 
-  function recordDebug(scope, message, level = "info", resource = undefined) {
+  function recordDebug(scope, message, level = "info", resource = undefined, broadcast = true, onion = undefined) {
     const entry = {
       at: new Date().toISOString(),
       scope,
@@ -15,10 +15,27 @@
     if (resource) {
       entry.resource = resource;
     }
+    if (onion) {
+      entry.onion = onion;
+    }
     debugEntries.push(entry);
     if (debugEntries.length > 200) {
       debugEntries.splice(0, debugEntries.length - 200);
     }
+    if (broadcast) {
+      broadcastDebugEntry(entry);
+    }
+  }
+
+  function broadcastDebugEntry(entry) {
+    const worker = navigator.serviceWorker?.controller;
+    if (!worker) {
+      return;
+    }
+    worker.postMessage({
+      type: "rings-webview-debug-entry",
+      entry,
+    });
   }
 
   function ensureServiceWorkerSupport() {
@@ -121,6 +138,8 @@
         message.message || "unknown event",
         message.level || "info",
         message.resource,
+        false,
+        message.onion,
       );
       return;
     }
diff --git a/frontend/assets/webview-overlay.js b/frontend/assets/webview-overlay.js
new file mode 100644
index 000000000..232f0dbf1
--- /dev/null
+++ b/frontend/assets/webview-overlay.js
@@ -0,0 +1,555 @@
+(() => {
+  "use strict";
+
+  const gatewayPrefix = "/webview/";
+  const marker = "__ringsWebviewDebugOverlay";
+  const hostId = "rings-webview-debug-overlay";
+  const defaultTarget = "https://example.com/";
+  const maxEntries = 200;
+
+  const state = {
+    entries: [],
+    log: undefined,
+    network: undefined,
+    onion: undefined,
+    panel: undefined,
+    view: "log",
+    levelFilter: "all",
+    textFilter: "",
+    originalBodyPaddingTop: undefined,
+    originalBodyPaddingBottom: undefined,
+  };
+
+  function isWebviewContext() {
+    return (
+      location.pathname.startsWith(gatewayPrefix)
+      || location.hash.startsWith("#webview")
+      || Boolean(document.querySelector("[data-rings-webview-default-target],[data-rings-webview-failure]"))
+    );
+  }
+
+  function initialTargetText() {
+    const configured = document.querySelector("[data-rings-webview-default-target]")?.dataset.ringsWebviewDefaultTarget;
+    if (configured) return configured;
+    if (!location.pathname.startsWith(gatewayPrefix)) return defaultTarget;
+    const encoded = location.pathname.slice(gatewayPrefix.length);
+    if (!encoded) return defaultTarget;
+    try {
+      return decodeURIComponent(encoded);
+    } catch (_error) {
+      return defaultTarget;
+    }
+  }
+
+  function resourceLine(resource) {
+    const status = resource.status == null ? "pending" : String(resource.status);
+    return `#${resource.requestId} ${status} ${resource.kind} ${resource.method} ${resource.phase} ${resource.target} ${resource.durationMs} ms`;
+  }
+
+  function onionLine(onion) {
+    const hops = Array.isArray(onion.hops) ? onion.hops.join(" ") : "";
+    return `${onion.target || ""} ${onion.service || ""} ${onion.phase || ""} ${onion.exit || ""} ${hops} ${onion.durationMs || ""}`;
+  }
+
+  function entryText(entry) {
+    return `${entry.at || ""} ${entry.scope || "worker"} ${entry.level || "info"} ${entry.message || ""} ${entry.resource ? resourceLine(entry.resource) : ""} ${entry.onion ? onionLine(entry.onion) : ""}`.toLowerCase();
+  }
+
+  function textMatches(entry) {
+    const needle = state.textFilter.trim().toLowerCase();
+    return !needle || entryText(entry).includes(needle);
+  }
+
+  function levelMatches(entry) {
+    return state.levelFilter === "all" || (entry.level || "info") === state.levelFilter;
+  }
+
+  function filteredLogEntries() {
+    return state.entries.filter((entry) => levelMatches(entry) && textMatches(entry));
+  }
+
+  function filteredNetworkEntries() {
+    return Array.from(
+      new Map(
+        state.entries
+          .filter((entry) => entry.resource && textMatches(entry))
+          .map((entry) => [entry.resource.requestId, entry]),
+      ).values(),
+    );
+  }
+
+  function filteredOnionEntries() {
+    return state.entries.filter((entry) => entry.onion && textMatches(entry));
+  }
+
+  function appendEmpty(container) {
+    const empty = document.createElement("p");
+    empty.textContent = state.entries.length === 0 ? "Waiting for gateway activity" : "No matching entries";
+    container.append(empty);
+  }
+
+  function appendLogRow(container, entry) {
+    const row = document.createElement("p");
+    row.className = entry.level === "error" ? "error" : entry.level === "warning" ? "warning" : "";
+    const time = String(entry.at || "").split("T")[1]?.replace("Z", "").slice(0, 12) || "";
+    row.textContent = `${time} ${(entry.level || "info").toUpperCase()} [${entry.scope || "worker"}] ${entry.message || "unknown event"}`;
+    container.append(row);
+  }
+
+  function appendNetworkHeader(container) {
+    const row = document.createElement("div");
+    row.className = "network-row heading";
+    for (const field of ["ID", "Status", "Kind", "Method", "Phase", "Time", "Target"]) {
+      const cell = document.createElement("span");
+      cell.textContent = field;
+      row.append(cell);
+    }
+    container.append(row);
+  }
+
+  function appendNetworkRow(container, entry) {
+    const resource = entry.resource;
+    if (!resource) return;
+    const row = document.createElement("div");
+    row.className = `network-row ${entry.level === "error" ? "error" : entry.level === "warning" ? "warning" : ""}`;
+    for (const field of [
+      `#${resource.requestId}`,
+      resource.status == null ? "pending" : String(resource.status),
+      resource.kind,
+      resource.method,
+      resource.phase,
+      `${resource.durationMs} ms`,
+      resource.target,
+    ]) {
+      const cell = document.createElement("span");
+      cell.textContent = field;
+      row.append(cell);
+    }
+    container.append(row);
+  }
+
+  function compactDid(value) {
+    const text = String(value || "");
+    return text.length > 18 ? `${text.slice(0, 10)}...${text.slice(-6)}` : text;
+  }
+
+  function appendOnionHeader(container) {
+    const row = document.createElement("div");
+    row.className = "onion-row heading";
+    for (const field of ["Phase", "Service", "Hops", "Exit", "Time", "Target"]) {
+      const cell = document.createElement("span");
+      cell.textContent = field;
+      row.append(cell);
+    }
+    container.append(row);
+  }
+
+  function appendOnionRow(container, entry) {
+    const onion = entry.onion;
+    if (!onion) return;
+    const hops = Array.isArray(onion.hops) ? onion.hops : [];
+    const row = document.createElement("div");
+    row.className = `onion-row ${entry.level === "error" ? "error" : entry.level === "warning" ? "warning" : ""}`;
+    for (const field of [
+      onion.phase || "route",
+      onion.service || "https",
+      hops.length ? hops.map(compactDid).join(" -> ") : onion.error || "none",
+      compactDid(onion.exit),
+      onion.durationMs == null ? "" : `${onion.durationMs} ms`,
+      onion.target || "",
+    ]) {
+      const cell = document.createElement("span");
+      cell.textContent = field;
+      row.append(cell);
+    }
+    container.append(row);
+  }
+
+  function render() {
+    const container = state.view === "network" ? state.network : state.view === "onion" ? state.onion : state.log;
+    if (!container) return;
+    container.replaceChildren();
+    const entries = state.view === "network" ? filteredNetworkEntries() : state.view === "onion" ? filteredOnionEntries() : filteredLogEntries();
+    if (entries.length === 0) {
+      appendEmpty(container);
+      return;
+    }
+    if (state.view === "network") appendNetworkHeader(container);
+    if (state.view === "onion") appendOnionHeader(container);
+    for (const entry of entries) {
+      if (state.view === "network") appendNetworkRow(container, entry);
+      else if (state.view === "onion") appendOnionRow(container, entry);
+      else appendLogRow(container, entry);
+    }
+    container.scrollTop = container.scrollHeight;
+  }
+
+  function record(scope, message, level = "info", resource = undefined, onion = undefined, at = undefined) {
+    const entry = { at: at || new Date().toISOString(), scope, message, level };
+    if (resource) entry.resource = resource;
+    if (onion) entry.onion = onion;
+    state.entries.push(entry);
+    if (state.entries.length > maxEntries) state.entries.splice(0, state.entries.length - maxEntries);
+    render();
+  }
+
+  function selectView(view) {
+    state.view = view;
+    state.log.hidden = view !== "log";
+    state.network.hidden = view !== "network";
+    state.onion.hidden = view !== "onion";
+    for (const tab of state.panel.querySelectorAll("[data-view]")) {
+      const active = tab.dataset.view === view;
+      tab.dataset.active = String(active);
+      tab.setAttribute("aria-selected", String(active));
+    }
+    render();
+  }
+
+  function normalizedTarget(input) {
+    let text = String(input || "").trim();
+    if (!text) throw new Error("Address is empty");
+    if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(text)) text = `https://${text}`;
+    const url = new URL(text);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error("Only HTTP(S) addresses can be opened");
+    }
+    return url.href;
+  }
+
+  function gatewayPath(input) {
+    return `${gatewayPrefix}${encodeURIComponent(normalizedTarget(input))}`;
+  }
+
+  function limitedText(value) {
+    const text = String(value);
+    return text.length > 1200 ? `${text.slice(0, 1200)}...` : text;
+  }
+
+  function formatConsoleValue(value) {
+    if (value instanceof Error) return limitedText(value.stack || value.message);
+    if (typeof value === "string") return limitedText(value);
+    try {
+      const json = JSON.stringify(value);
+      if (json !== undefined) return limitedText(json);
+    } catch (_error) {}
+    return limitedText(value);
+  }
+
+  function installConsoleCapture() {
+    const captureMarker = "__ringsWebviewConsoleCapture";
+    if (globalThis[captureMarker]) return;
+    globalThis[captureMarker] = true;
+    for (const method of ["error", "warn", "info", "log"]) {
+      const original = console[method]?.bind(console);
+      if (!original) continue;
+      console[method] = (...args) => {
+        const level = method === "error" ? "error" : method === "warn" ? "warning" : "info";
+        try {
+          record("console", args.map(formatConsoleValue).join(" "), level);
+        } catch (_error) {}
+        original(...args);
+      };
+    }
+    globalThis.addEventListener("error", (event) => {
+      record("page", event.error?.stack || event.message || "Uncaught page error", "error");
+    });
+    globalThis.addEventListener("unhandledrejection", (event) => {
+      record("page", `Unhandled rejection: ${formatConsoleValue(event.reason)}`, "error");
+    });
+  }
+
+  function applyBodySpacing() {
+    if (!document.body) return;
+    if (state.originalBodyPaddingTop === undefined) {
+      state.originalBodyPaddingTop = getComputedStyle(document.body).paddingTop || "0px";
+      state.originalBodyPaddingBottom = getComputedStyle(document.body).paddingBottom || "0px";
+      document.body.dataset.ringsWebviewToolbarReserved = "true";
+      document.body.style.paddingTop = `calc(${state.originalBodyPaddingTop} + 46px)`;
+      document.documentElement.style.scrollPaddingTop = "52px";
+    }
+    if (state.panel && !state.panel.hidden) {
+      document.body.style.paddingBottom = `calc(${state.originalBodyPaddingBottom} + min(300px, 45vh))`;
+    } else {
+      document.body.style.paddingBottom = state.originalBodyPaddingBottom;
+    }
+  }
+
+  async function prepareGatewayForNavigation() {
+    const host = globalThis.RingsWebviewHost;
+    if (!host || typeof host.ensureReady !== "function") return;
+    await host.ensureReady();
+    if (typeof host.enableDebug === "function") {
+      await host.enableDebug();
+    }
+  }
+
+  async function openAddress(address) {
+    let path;
+    try {
+      path = gatewayPath(address);
+    } catch (error) {
+      record("overlay", String(error), "error");
+      return;
+    }
+    record("overlay", "Connecting through the local Rings gateway");
+    try {
+      await prepareGatewayForNavigation();
+      record("overlay", "Request sent to the local Rings gateway");
+      location.href = path;
+    } catch (error) {
+      record("overlay", `gateway unavailable: ${String(error)}`, "error");
+    }
+  }
+
+  function requestDebugRegistration() {
+    const host = globalThis.RingsWebviewHost;
+    if (host && typeof host.enableDebug === "function") {
+      void host.enableDebug().catch((error) => record("overlay", `Debug listener unavailable: ${String(error)}`, "error"));
+      return;
+    }
+    void navigator.serviceWorker?.ready
+      .then((registration) => {
+        const worker = navigator.serviceWorker.controller || registration.active;
+        worker?.postMessage({ type: "rings-webview-debug-register" });
+      })
+      .catch(() => record("overlay", "Service Worker debug listener unavailable", "error"));
+  }
+
+  function isGatewayResponseDocument() {
+    return Boolean(
+      document.querySelector("[data-rings-webview-failure]")
+      || globalThis.__ringsWebviewGateway,
+    );
+  }
+
+  function maybeReloadColdGatewayFallback() {
+    if (!location.pathname.startsWith(gatewayPrefix) || isGatewayResponseDocument()) return;
+    const host = globalThis.RingsWebviewHost;
+    if (!host || typeof host.ensureReady !== "function") return;
+    const storageKey = `rings-webview-cold-reload:${location.href}`;
+    try {
+      if (sessionStorage.getItem(storageKey) === "true") {
+        record("overlay", "Gateway path loaded without a Service Worker response after retry", "warning");
+        return;
+      }
+      sessionStorage.setItem(storageKey, "true");
+    } catch (_error) {}
+    void host.ensureReady()
+      .then(() => {
+        if (isGatewayResponseDocument()) return;
+        record("overlay", "Reloading gateway path after Service Worker took control");
+        location.reload();
+      })
+      .catch((error) => record("overlay", `Service Worker controller unavailable: ${String(error)}`, "error"));
+  }
+
+  function setDebugOpen(open) {
+    if (!state.panel) return;
+    const toggle = state.panel.getRootNode().getElementById("toggle");
+    state.panel.hidden = !open;
+    toggle?.setAttribute("aria-expanded", String(open));
+    if (toggle) toggle.dataset.active = String(open);
+    applyBodySpacing();
+    if (open) render();
+  }
+
+  function appendFailureEntry() {
+    const failure = document.querySelector("[data-rings-webview-failure]");
+    if (!failure || failure.dataset.ringsWebviewFailureRecorded === "true") return;
+    failure.dataset.ringsWebviewFailureRecorded = "true";
+    const status = Number(failure.dataset.ringsWebviewFailureStatus || 0) || undefined;
+    const code = failure.dataset.ringsWebviewFailureCode || "gateway_request_failed";
+    const summary = failure.dataset.ringsWebviewFailureSummary || "Gateway request failed.";
+    const detail = failure.dataset.ringsWebviewFailureDetail || summary;
+    record(
+      "gateway",
+      `${code}: ${detail}`,
+      "error",
+      {
+        requestId: "failure",
+        target: initialTargetText(),
+        method: "GET",
+        kind: "navigation",
+        phase: "failed",
+        durationMs: 0,
+        status,
+      },
+    );
+    setDebugOpen(true);
+  }
+
+  function mount() {
+    if (!isWebviewContext()) return;
+    if (document.getElementById(hostId)) {
+      appendFailureEntry();
+      return;
+    }
+    const host = document.createElement("div");
+    host.id = hostId;
+    const root = host.attachShadow({ mode: "open" });
+    root.innerHTML = `
+      
+      
+      `;
+    const panel = root.getElementById("panel");
+    const toggle = root.getElementById("toggle");
+    const back = root.getElementById("back");
+    const forward = root.getElementById("forward");
+    const reload = root.getElementById("reload");
+    const addressForm = root.getElementById("address-form");
+    const address = root.getElementById("address");
+    const log = root.getElementById("log");
+    const network = root.getElementById("network");
+    const onion = root.getElementById("onion");
+    const levelFilter = root.getElementById("level-filter");
+    const textFilter = root.getElementById("text-filter");
+    const clear = root.getElementById("clear");
+    if (!panel || !toggle || !back || !forward || !reload || !addressForm || !address || !log || !network || !onion || !levelFilter || !textFilter || !clear) return;
+    state.panel = panel;
+    state.log = log;
+    state.network = network;
+    state.onion = onion;
+    address.value = initialTargetText();
+    toggle.addEventListener("click", () => setDebugOpen(panel.hidden));
+    back.addEventListener("click", () => history.back());
+    forward.addEventListener("click", () => history.forward());
+    reload.addEventListener("click", () => location.reload());
+    addressForm.addEventListener("submit", (event) => {
+      event.preventDefault();
+      void openAddress(address.value);
+    });
+    for (const tab of root.querySelectorAll("[data-view]")) {
+      tab.addEventListener("click", () => selectView(tab.dataset.view));
+    }
+    levelFilter.addEventListener("change", () => {
+      state.levelFilter = levelFilter.value || "all";
+      render();
+    });
+    textFilter.addEventListener("input", () => {
+      state.textFilter = textFilter.value || "";
+      render();
+    });
+    clear.addEventListener("click", () => {
+      state.entries.splice(0, state.entries.length);
+      render();
+    });
+    document.documentElement.append(host);
+    applyBodySpacing();
+    installConsoleCapture();
+    requestDebugRegistration();
+    record("overlay", "Debug listener ready");
+    appendFailureEntry();
+    maybeReloadColdGatewayFallback();
+  }
+
+  function onContextMaybeChanged() {
+    if (!isWebviewContext()) return;
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", mount, { once: true });
+    } else {
+      mount();
+    }
+  }
+
+  globalThis[marker] = {
+    installed: true,
+    mount: onContextMaybeChanged,
+    mounted: () => Boolean(document.getElementById(hostId)),
+    record,
+  };
+
+  navigator.serviceWorker?.addEventListener("message", (event) => {
+    const entry = event.data;
+    if (entry?.type === "rings-webview-debug") {
+      record(
+        entry.scope || "worker",
+        entry.message || "unknown event",
+        entry.level || "info",
+        entry.resource,
+        entry.onion,
+        entry.at,
+      );
+    }
+  });
+  globalThis.addEventListener("hashchange", onContextMaybeChanged);
+  onContextMaybeChanged();
+})();
diff --git a/frontend/index.html b/frontend/index.html
index 06330b23e..985babfb5 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -10,6 +10,7 @@
     
   
   
-    
+    
+    
   
 
diff --git a/frontend/rings-webview-service-worker.js b/frontend/rings-webview-service-worker.js
index 73669b02d..3954eb1f8 100644
--- a/frontend/rings-webview-service-worker.js
+++ b/frontend/rings-webview-service-worker.js
@@ -18,6 +18,19 @@ self.addEventListener("activate", (event) => {
 self.addEventListener("message", (event) => {
   const clientId = event.source?.id;
   const reply = event.ports?.[0];
+  if (event.data?.type === "rings-webview-debug-entry" && event.data.entry) {
+    const entry = event.data.entry;
+    void emitDebug(
+      entry.scope || "host",
+      entry.message || "unknown event",
+      entry.level || "info",
+      entry.resource,
+      entry.at,
+      entry.onion,
+    );
+    reply?.postMessage({ ok: true });
+    return;
+  }
   if (event.data?.type === "rings-webview-host-register" && typeof clientId === "string" && clientId) {
     updateGatewayHost(clientId);
     void emitDebug("worker", "Updated local Rings node gateway host");
@@ -69,7 +82,12 @@ async function handleGatewayFetch(event) {
       "error",
       503,
     );
-    return gatewayFailure(503, "Start a local Rings node before opening WebView.");
+    return gatewayFailure(
+      503,
+      "Start a local Rings node before opening WebView.",
+      "Local Rings node gateway is unavailable.",
+      "local_gateway_unavailable",
+    );
   }
   await emitResourceDebug(
     requestId,
@@ -90,7 +108,12 @@ async function handleGatewayFetch(event) {
       "error",
       status,
     );
-    return gatewayFailure(response?.status || 502, response?.error || "gateway request failed");
+    return gatewayFailure(
+      response?.status || 502,
+      response?.error || "gateway request failed",
+      response?.errorSummary,
+      response?.errorCode,
+    );
   }
   try {
     const headers = new Headers();
@@ -120,7 +143,12 @@ async function handleGatewayFetch(event) {
       "error",
       502,
     );
-    return gatewayFailure(502, `invalid gateway response: ${String(error)}`);
+    return gatewayFailure(
+      502,
+      `invalid gateway response: ${String(error)}`,
+      "The local gateway returned an invalid response.",
+      "invalid_gateway_response",
+    );
   }
 }
 
@@ -143,10 +171,10 @@ async function emitResourceDebug(requestId, request, startedAt, phase, message,
   await emitDebug("worker", message, level, resource);
 }
 
-async function emitDebug(scope, message, level = "info", resource = undefined) {
+async function emitDebug(scope, message, level = "info", resource = undefined, at = undefined, onion = undefined) {
   const entry = {
     type: "rings-webview-debug",
-    at: new Date().toISOString(),
+    at: at || new Date().toISOString(),
     scope,
     message,
     level,
@@ -154,6 +182,9 @@ async function emitDebug(scope, message, level = "info", resource = undefined) {
   if (resource) {
     entry.resource = resource;
   }
+  if (onion) {
+    entry.onion = onion;
+  }
   debugHistory.push(entry);
   if (debugHistory.length > 200) {
     debugHistory.splice(0, debugHistory.length - 200);
@@ -342,8 +373,13 @@ function requestGatewayResponse(host, request) {
   });
 }
 
-function gatewayFailure(status, message) {
-  return new Response(gatewayFailureDocument(status, message), {
+function gatewayFailure(status, message, summary = undefined, code = undefined) {
+  return new Response(gatewayFailureDocument(
+    status,
+    gatewayFailureSummary(message),
+    gatewayFailureReason(status, message, summary),
+    code || gatewayFailureCode(status),
+  ), {
     status,
     headers: {
       "content-type": "text/html; charset=utf-8",
@@ -353,70 +389,89 @@ function gatewayFailure(status, message) {
   });
 }
 
-function gatewayFailureDocument(status, message) {
-  const detail = JSON.stringify(String(message)).replace(/ line.trim())
+    .find(Boolean);
+  return firstLine || "gateway request failed";
+}
+
+function gatewayFailureReason(status, message, summary) {
+  const cleanSummary = String(summary || "").trim();
+  if (cleanSummary) return cleanSummary;
+  const detail = gatewayFailureSummary(message);
+  if (status === 503 && detail.includes("no live onion exit offers service \"https\"")) {
+    return "No live HTTPS onion exit is available.";
+  }
+  if (status === 503 && detail.includes("no live onion exit")) {
+    return "No live onion exit is available for this request.";
+  }
+  if (status === 503 && detail.includes("Start a local Rings node")) {
+    return "Local Rings node gateway is unavailable.";
+  }
+  if (status === 502) return "Gateway transport failed.";
+  return "Gateway request failed.";
+}
+
+function gatewayFailureCode(status) {
+  if (status === 400) return "invalid_webview_request";
+  if (status === 403) return "webview_request_rejected";
+  if (status === 404) return "controlled_asset_not_found";
+  if (status === 502) return "gateway_transport_failed";
+  if (status === 503) return "gateway_unavailable";
+  return "gateway_request_failed";
+}
+
+function gatewayFailureDocument(status, message, reason, code) {
+  const detail = escapeHtml(message);
+  const summary = escapeHtml(reason);
+  const reasonCode = escapeHtml(code);
+  const statusText = escapeHtml(status);
   return `
+
 
 
-Rings gateway failure ${status}
+Rings gateway failure ${statusText}
 
+
 

-  
Rings gateway failure ${status}

-  

-  
Gateway events

+  

+    
Rings gateway failure ${statusText}

+    
${reasonCode}${summary}

+  

 

-
-`;
+
+
+`;
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&")
+    .replace(//g, ">")
+    .replace(/"/g, """);
 }
diff --git a/frontend/src/browser_api.rs b/frontend/src/browser_api.rs
index e1cc77e72..7c6e8fd40 100644
--- a/frontend/src/browser_api.rs
+++ b/frontend/src/browser_api.rs
@@ -59,14 +59,32 @@ pub(crate) async fn copy_text_to_clipboard(value: String) -> Result<(), String>
     Ok(())
 }
 
-pub(crate) async fn open_debug_url(url: &str) -> Result<(), String> {
-    match open_debug_url_with_extension_tabs("browser", url).await {
-        Ok(()) => Ok(()),
-        Err(_) => match open_debug_url_with_extension_tabs("chrome", url).await {
-            Ok(()) => Ok(()),
-            Err(_) => open_debug_url_with_window(url),
-        },
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum DebugUrlOpenResult {
+    Opened,
+    CopiedInternalUrl,
+    ManualInternalUrl,
+}
+
+pub(crate) fn open_debug_url(url: &str) -> Result {
+    if open_debug_url_with_extension_tabs("browser", url).is_ok()
+        || open_debug_url_with_extension_tabs("chrome", url).is_ok()
+    {
+        return Ok(DebugUrlOpenResult::Opened);
+    }
+
+    // Browser-internal pages (`chrome://`, `about:`) are intentionally blocked from ordinary
+    // webpages. Avoid calling `window.open` for them, otherwise the user only sees a blocked
+    // navigation and the console records a misleading local-resource failure.
+    if is_browser_internal_url(url) {
+        return Ok(if copy_text_to_clipboard_start(url).is_ok() {
+            DebugUrlOpenResult::CopiedInternalUrl
+        } else {
+            DebugUrlOpenResult::ManualInternalUrl
+        });
     }
+
+    open_debug_url_with_window(url).map(|_| DebugUrlOpenResult::Opened)
 }
 
 /// Open the application-owned WebView shell in a named browser popup.
@@ -99,7 +117,7 @@ pub(crate) fn open_webview_popup() -> Result<(), String> {
     Ok(())
 }
 
-async fn open_debug_url_with_extension_tabs(namespace: &str, url: &str) -> Result<(), String> {
+fn open_debug_url_with_extension_tabs(namespace: &str, url: &str) -> Result<(), String> {
     let extension_api =
         Reflect::get(&js_sys::global(), &JsValue::from_str(namespace)).map_err(js_error_label)?;
     if extension_api.is_null() || extension_api.is_undefined() {
@@ -119,9 +137,7 @@ async fn open_debug_url_with_extension_tabs(namespace: &str, url: &str) -> Resul
     let opened = create
         .call1(&tabs, &options.into())
         .map_err(js_error_label)?;
-    if let Ok(promise) = opened.dyn_into::() {
-        JsFuture::from(promise).await.map_err(js_error_label)?;
-    }
+    observe_promise_rejection(opened);
     Ok(())
 }
 
@@ -148,6 +164,39 @@ fn open_debug_url_with_window(url: &str) -> Result<(), String> {
     Ok(())
 }
 
+fn is_browser_internal_url(url: &str) -> bool {
+    url.starts_with("chrome://") || url.starts_with("about:")
+}
+
+fn copy_text_to_clipboard_start(value: &str) -> Result<(), String> {
+    let navigator =
+        Reflect::get(&js_sys::global(), &JsValue::from_str("navigator")).map_err(js_error_label)?;
+    let clipboard =
+        Reflect::get(&navigator, &JsValue::from_str("clipboard")).map_err(js_error_label)?;
+    if clipboard.is_null() || clipboard.is_undefined() {
+        return Err("clipboard API unavailable".to_string());
+    }
+    let write_text = js_method(&clipboard, "writeText")?;
+    let result = write_text
+        .call1(&clipboard, &JsValue::from_str(value))
+        .map_err(js_error_label)?;
+    observe_promise_rejection(result);
+    Ok(())
+}
+
+fn observe_promise_rejection(value: JsValue) {
+    let Ok(promise) = value.dyn_into::() else {
+        return;
+    };
+    let promise: JsValue = promise.into();
+    let Ok(catch) = js_method(&promise, "catch") else {
+        return;
+    };
+    let handler =
+        wasm_bindgen::closure::Closure::once_into_js(|_error: JsValue| JsValue::UNDEFINED);
+    let _ = catch.call1(&promise, &handler);
+}
+
 pub(crate) async fn await_js(value: JsValue) -> Result {
     JsFuture::from(Promise::from(value))
         .await
@@ -249,5 +298,79 @@ pub(crate) fn js_set(object: &Object, name: &str, value: &JsValue) -> Result<(),
 }
 
 pub(crate) fn js_error_label(error: JsValue) -> String {
-    error.as_string().unwrap_or_else(|| format!("{error:?}"))
+    if let Some(message) = js_error_message(&error) {
+        return message;
+    }
+    if let Some(text) = error.as_string() {
+        return compact_js_error_text(&text);
+    }
+    compact_js_error_text(&format!("{error:?}"))
+}
+
+fn js_error_message(error: &JsValue) -> Option {
+    let message = string_property(error, "message")?;
+    let name = string_property(error, "name");
+    match name.as_deref() {
+        Some(name) if !name.is_empty() && name != "Error" && !message.starts_with(name) => {
+            Some(format!("{name}: {message}"))
+        }
+        _ => Some(message),
+    }
+}
+
+fn string_property(object: &JsValue, name: &str) -> Option {
+    Reflect::get(object, &JsValue::from_str(name))
+        .ok()
+        .and_then(|value| value.as_string())
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn compact_js_error_text(raw: &str) -> String {
+    let mut text = raw.trim();
+    if let Some(inner) = text
+        .strip_prefix("JsValue(")
+        .and_then(|value| value.strip_suffix(')'))
+    {
+        text = inner.trim();
+    }
+    text.lines()
+        .next()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("unknown JavaScript error")
+        .to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use js_sys::Error;
+    use wasm_bindgen_test::wasm_bindgen_test;
+
+    use super::*;
+
+    #[wasm_bindgen_test]
+    fn js_error_label_uses_error_message_without_stack() {
+        let error = Error::new("Onion route error: no live onion exit offers service \"https\"");
+
+        assert_eq!(
+            js_error_label(error.into()),
+            "Onion route error: no live onion exit offers service \"https\""
+        );
+    }
+
+    #[wasm_bindgen_test]
+    fn js_error_label_compacts_debug_fallback() {
+        assert_eq!(
+            compact_js_error_text("JsValue(Error: boom\n    at wasm-function[1])"),
+            "Error: boom"
+        );
+    }
+
+    #[wasm_bindgen_test]
+    fn browser_internal_debug_urls_are_detected() {
+        assert!(is_browser_internal_url("chrome://webrtc-internals/"));
+        assert!(is_browser_internal_url("about:webrtc"));
+        assert!(!is_browser_internal_url("https://example.test/"));
+    }
 }
diff --git a/frontend/src/controls.rs b/frontend/src/controls.rs
index 0493107ee..3406f8231 100644
--- a/frontend/src/controls.rs
+++ b/frontend/src/controls.rs
@@ -737,25 +737,38 @@ fn open_detected_debug_callback(
     status: UseStateHandle,
 ) -> Callback {
     Callback::from(move |_| {
-        let status = status.clone();
-        wasm_bindgen_futures::spawn_local(async move {
-            let browser = detect_browser();
-            let Some(url) = debug_url(browser, target) else {
+        let browser = detect_browser();
+        let Some(url) = debug_url(browser, target) else {
+            status.set(format!(
+                "cannot detect supported browser for {}",
+                target.label()
+            ));
+            return;
+        };
+        match extension::open_debug_url(url) {
+            Ok(extension::DebugUrlOpenResult::Opened) => {
+                status.set(format!("opened {} {}", browser.label(), target.label()));
+            }
+            Ok(extension::DebugUrlOpenResult::CopiedInternalUrl) => {
                 status.set(format!(
-                    "cannot detect supported browser for {}",
-                    target.label()
+                    "{} blocks direct {} links from webpages; URL copied, paste it into the address bar",
+                    browser.label(),
+                    target.label(),
                 ));
-                return;
-            };
-            match extension::open_debug_url(url).await {
-                Ok(()) => status.set(format!("opened {} {}", browser.label(), target.label())),
-                Err(error) => status.set(format!(
-                    "open {} {} failed: {error}",
+            }
+            Ok(extension::DebugUrlOpenResult::ManualInternalUrl) => {
+                status.set(format!(
+                    "{} blocks direct {} links from webpages; paste {url} into the address bar",
                     browser.label(),
-                    target.label()
-                )),
+                    target.label(),
+                ));
             }
-        });
+            Err(error) => status.set(format!(
+                "open {} {} failed: {error}",
+                browser.label(),
+                target.label()
+            )),
+        }
     })
 }
 
diff --git a/frontend/src/extension.rs b/frontend/src/extension.rs
index 50956134f..7aaba104c 100644
--- a/frontend/src/extension.rs
+++ b/frontend/src/extension.rs
@@ -27,6 +27,7 @@ use crate::browser_api::js_string_field;
 pub(crate) use crate::browser_api::load_setting;
 pub(crate) use crate::browser_api::open_debug_url;
 pub(crate) use crate::browser_api::save_setting;
+pub(crate) use crate::browser_api::DebugUrlOpenResult;
 use crate::custom;
 use crate::dweb;
 pub(crate) use crate::extension_bridge::apply_extension_snapshot;
diff --git a/frontend/src/onion.rs b/frontend/src/onion.rs
index 0749a3b43..778dc94ae 100644
--- a/frontend/src/onion.rs
+++ b/frontend/src/onion.rs
@@ -278,7 +278,12 @@ pub(crate) async fn route(
     let target_authority = target_authority(&request.url)?;
     let proxy = provider
         .onion_https_proxy(request.options.hop_count, request.options.allow_short_paths)
-        .map_err(|error| format!("create onion proxy failed: {error:?}"))?;
+        .map_err(|error| {
+            format!(
+                "create onion proxy failed: {}",
+                js_error_label(error.into())
+            )
+        })?;
     let value = JsFuture::from(proxy.route(target_authority))
         .await
         .map_err(|error| format!("build onion route failed: {}", js_error_label(error)))?;
@@ -293,7 +298,12 @@ pub(crate) async fn request(
     target_authority(&request.url)?;
     let proxy = provider
         .onion_https_proxy(request.options.hop_count, request.options.allow_short_paths)
-        .map_err(|error| format!("create onion proxy failed: {error:?}"))?;
+        .map_err(|error| {
+            format!(
+                "create onion proxy failed: {}",
+                js_error_label(error.into())
+            )
+        })?;
     let value = JsFuture::from(proxy.request(request.url.clone(), request.client_request_js()?))
         .await
         .map_err(|error| format!("onion proxy request failed: {}", js_error_label(error)))?;
diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css
index faa607566..0f9f86880 100644
--- a/frontend/src/styles/components.css
+++ b/frontend/src/styles/components.css
@@ -574,331 +574,19 @@ code {
 }
 
 .webview-shell {
-  display: grid;
   width: 100vw;
   height: 100dvh;
   min-height: 0;
-  grid-template-rows: auto minmax(0, 1fr);
   background: #f3ead8;
   color: #111827;
   font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   overflow: hidden;
 }
 
-.webview-shell.debug-open {
-  grid-template-rows: auto minmax(0, 1fr) minmax(180px, 30dvh);
-}
-
-.webview-toolbar {
-  display: grid;
-  min-width: 0;
-  grid-template-columns: auto minmax(260px, 1fr) minmax(150px, 0.36fr) auto;
-  gap: 8px;
-  align-items: center;
-  padding: 9px 12px;
-  border-bottom: 1px solid #ddccb0;
-  background: #fffaf0;
-  box-shadow: 0 1px 2px rgba(112, 84, 48, 0.08);
-}
-
-.webview-brand,
-.webview-controls,
-.webview-address-form {
-  display: flex;
-  min-width: 0;
-  align-items: center;
-}
-
-.webview-brand {
-  min-width: 150px;
-  gap: 7px;
-  color: #111827;
-  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 0.82rem;
-  font-weight: 800;
-  white-space: nowrap;
-}
-
-.webview-brand img {
-  width: 26px;
-  height: 26px;
-  padding: 3px;
-  border-radius: 6px;
-  background: #111827;
-}
-
-.webview-controls {
-  gap: 5px;
-}
-
-.webview-icon-button,
-.webview-go-button {
-  display: grid;
-  width: 32px;
-  height: 32px;
-  min-width: 32px;
-  place-items: center;
-  padding: 0;
-  border: 1px solid #d9c5a6;
-  border-radius: 6px;
-  background: #fffaf0;
-  color: #374151;
-  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 0.92rem;
-  font-weight: 800;
-  line-height: 1;
-}
-
-.webview-icon-button:hover:not(:disabled),
-.webview-go-button:hover {
-  border-color: #111827;
-  background: #111827;
-  color: #fff;
-}
-
-.webview-icon-button:disabled {
-  cursor: not-allowed;
-  opacity: 0.42;
-}
-
-.webview-address-form {
-  display: grid;
-  min-width: 0;
-  grid-template-columns: minmax(0, 1fr) auto;
-  gap: 6px;
-}
-
-.webview-address-label {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  overflow: hidden;
-  clip: rect(0 0 0 0);
-  white-space: nowrap;
-}
-
-.webview-address {
-  width: 100%;
-  min-width: 0;
-  height: 32px;
-  padding: 5px 9px;
-  border: 1px solid #d9c5a6;
-  border-radius: 6px;
-  background: #fffdf8;
-  color: #111827;
-  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 0.78rem;
-  line-height: 1.1;
-}
-
-.webview-address:focus {
-  border-color: #b42318;
-  outline: 3px solid rgba(180, 35, 24, 0.12);
-}
-
-.webview-status {
-  min-width: 0;
-  margin: 0;
-  overflow: hidden;
-  color: #6f6252;
-  font-size: 0.7rem;
-  font-weight: 650;
-  line-height: 1.2;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.webview-close-button {
-  color: #b42318;
-}
-
-.webview-debug-button,
-.webview-debug-clear,
-.webview-debug-tab {
-  min-height: 32px;
-  padding: 5px 9px;
-  border: 1px solid #d9c5a6;
-  border-radius: 6px;
-  background: #fffaf0;
-  color: #374151;
-  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 0.68rem;
-  font-weight: 800;
-  line-height: 1;
-}
-
-.webview-debug-button:hover,
-.webview-debug-button.active,
-.webview-debug-clear:hover,
-.webview-debug-tab:hover,
-.webview-debug-tab.active {
-  border-color: #111827;
-  background: #111827;
-  color: #fff;
-}
-
 .webview-viewport {
-  position: relative;
-  min-width: 0;
-  min-height: 0;
-  background: #fffaf0;
-}
-
-.webview-frame {
-  display: block;
   width: 100%;
   height: 100%;
-  border: 0;
-  background: #fff;
-}
-
-.webview-debug-panel {
-  display: grid;
-  min-width: 0;
-  min-height: 0;
-  grid-template-rows: auto minmax(0, 1fr);
-  border-top: 1px solid #ddccb0;
-  background: #fffaf0;
-}
-
-.webview-debug-header {
-  display: flex;
-  min-width: 0;
-  align-items: center;
-  justify-content: space-between;
-  gap: 12px;
-  padding: 8px 12px;
-  border-bottom: 1px solid #eadcc5;
-}
-
-.webview-debug-header .eyebrow {
-  margin: 0 0 1px;
-  color: #b42318;
-  font-size: 0.58rem;
-}
-
-.webview-debug-header h2 {
-  margin: 0;
-  color: #111827;
-  font-size: 0.82rem;
-  line-height: 1.1;
-}
-
-.webview-debug-tabs {
-  display: flex;
-  gap: 4px;
-  margin-left: auto;
-}
-
-.webview-debug-tab {
-  min-height: 26px;
-  padding: 4px 7px;
-  font-size: 0.62rem;
-}
-
-.webview-debug-log,
-.webview-debug-network {
-  min-width: 0;
-  min-height: 0;
-  padding: 7px 12px 10px;
-  overflow: auto;
-}
-
-.webview-debug-entry,
-.webview-debug-empty {
-  display: grid;
-  min-width: 0;
-  margin: 0;
-  padding: 3px 0;
-  grid-template-columns: 86px 66px minmax(0, 1fr);
-  gap: 8px;
-  border-bottom: 1px solid rgba(221, 204, 176, 0.48);
-  color: #4b5563;
-  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 0.68rem;
-  line-height: 1.35;
-  overflow-wrap: anywhere;
-}
-
-.webview-debug-entry time,
-.webview-debug-scope {
-  color: #82725f;
-}
-
-.webview-debug-scope {
-  font-weight: 800;
-  text-transform: uppercase;
-}
-
-.webview-debug-entry.error {
-  color: #b42318;
-}
-
-.webview-debug-empty {
-  display: block;
-  border-bottom: 0;
-  color: #82725f;
-}
-
-.webview-resource-row {
-  display: grid;
-  min-width: 710px;
-  padding: 4px 0;
-  grid-template-columns: 54px 62px 100px 92px minmax(260px, 1fr) 72px;
-  gap: 8px;
-  border-bottom: 1px solid rgba(221, 204, 176, 0.48);
-  color: #4b5563;
-  font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
-  font-size: 0.67rem;
-  line-height: 1.35;
-}
-
-.webview-resource-heading {
-  position: sticky;
-  top: -7px;
-  z-index: 1;
-  padding-top: 5px;
-  background: #fffaf0;
-  color: #82725f;
-  font-weight: 800;
-  text-transform: uppercase;
-}
-
-.webview-resource-target {
-  min-width: 0;
-  overflow-wrap: anywhere;
-}
-
-.webview-resource-row.resource-failed {
-  color: #b42318;
-}
-
-.webview-resource-row.resource-completed span:nth-child(2) {
-  color: #247556;
-  font-weight: 800;
-}
-
-.webview-empty-state {
-  display: grid;
-  width: min(460px, calc(100% - 32px));
-  gap: 7px;
-  margin: 12vh auto 0;
-  padding: 18px;
-  border: 1px solid #ddccb0;
-  border-radius: 8px;
   background: #fffaf0;
-  box-shadow: 0 1px 2px rgba(112, 84, 48, 0.08);
-}
-
-.webview-empty-state strong {
-  color: #111827;
-  font-size: 0.92rem;
-}
-
-.webview-empty-state span {
-  color: #6f6252;
-  font-size: 0.78rem;
-  line-height: 1.45;
 }
 
 .rail-telemetry {
diff --git a/frontend/src/styles/responsive.css b/frontend/src/styles/responsive.css
index 54c1d01a4..4add811d9 100644
--- a/frontend/src/styles/responsive.css
+++ b/frontend/src/styles/responsive.css
@@ -353,57 +353,6 @@
   }
 }
 
-@media (max-width: 780px) {
-  .webview-toolbar {
-    grid-template-columns: auto minmax(0, 1fr) auto;
-    grid-template-areas:
-      "brand brand close"
-      "address address address"
-      "status status status";
-  }
-
-  .webview-brand {
-    grid-area: brand;
-  }
-
-  .webview-address-form {
-    grid-area: address;
-  }
-
-  .webview-status {
-    grid-area: status;
-  }
-
-  .webview-close-button {
-    grid-area: close;
-    justify-self: end;
-  }
-
-}
-
-@media (max-width: 520px) {
-  .webview-shell.debug-open {
-    grid-template-rows: auto minmax(0, 1fr) minmax(170px, 34dvh);
-  }
-
-  .webview-debug-header {
-    flex-wrap: wrap;
-    gap: 7px;
-  }
-
-  .webview-debug-tabs {
-    order: 3;
-    width: 100%;
-    margin-left: 0;
-  }
-
-  .webview-debug-entry {
-    grid-template-columns: 74px 54px minmax(0, 1fr);
-    gap: 6px;
-    font-size: 0.62rem;
-  }
-}
-
 @media (max-width: 520px) {
   h1 {
     font-size: 1rem;
diff --git a/frontend/src/webview.rs b/frontend/src/webview.rs
index fa5484a93..b54800b33 100644
--- a/frontend/src/webview.rs
+++ b/frontend/src/webview.rs
@@ -37,148 +37,22 @@ use crate::onion;
 
 const GATEWAY_PREFIX: &str = "/webview/";
 const MAX_CONCURRENT_GATEWAY_REQUESTS: usize = 6;
-const WEBVIEW_DEBUG_OVERLAY: &str = r#"
+const WEBVIEW_OVERLAY_LOADER: &str = r#"
 (() => {
   "use strict";
 
   const marker = "__ringsWebviewDebugOverlay";
-  if (globalThis[marker]?.mounted?.()) return;
-
-  const state = {
-    entries: [],
-    log: undefined,
-    network: undefined,
-    panel: undefined,
-    view: "log",
-  };
-  const maxEntries = 200;
-
-  function resourceLine(resource) {
-    const status = resource.status == null ? "pending" : String(resource.status);
-    return `#${resource.requestId} ${status} ${resource.kind} ${resource.method} ${resource.phase} ${resource.target} ${resource.durationMs} ms`;
+  if (globalThis[marker]?.installed) {
+    globalThis[marker].mount?.();
+    return;
   }
+  if (document.querySelector("script[data-rings-webview-overlay-loader]")) return;
 
-  function render() {
-    const container = state.view === "network" ? state.network : state.log;
-    if (!container) return;
-    container.replaceChildren();
-    const entries = state.view === "network"
-      ? [...new Map(state.entries.filter((entry) => entry.resource).map((entry) => [entry.resource.requestId, entry])).values()]
-      : state.entries;
-    if (entries.length === 0) {
-      const empty = document.createElement("p");
-      empty.textContent = "Waiting for gateway activity";
-      container.append(empty);
-      return;
-    }
-    for (const entry of entries) {
-      const row = document.createElement("p");
-      row.className = entry.level === "error" ? "error" : "";
-      const time = String(entry.at || "").split("T")[1]?.replace("Z", "").slice(0, 12) || "";
-      row.textContent = state.view === "network" && entry.resource
-        ? resourceLine(entry.resource)
-        : `${time} [${entry.scope || "worker"}] ${entry.message || "unknown event"}`;
-      container.append(row);
-    }
-    container.scrollTop = container.scrollHeight;
-  }
-
-  function record(scope, message, level = "info", resource = undefined) {
-    const entry = { at: new Date().toISOString(), scope, message, level };
-    if (resource) entry.resource = resource;
-    state.entries.push(entry);
-    if (state.entries.length > maxEntries) state.entries.splice(0, state.entries.length - maxEntries);
-    render();
-  }
-
-  function selectView(view) {
-    state.view = view;
-    state.log.hidden = view !== "log";
-    state.network.hidden = view !== "network";
-    state.panel.querySelector("[data-view=log]").dataset.active = String(view === "log");
-    state.panel.querySelector("[data-view=network]").dataset.active = String(view === "network");
-    render();
-  }
-
-  function mount() {
-    const host = document.createElement("div");
-    host.id = "rings-webview-debug-overlay";
-    const root = host.attachShadow({ mode: "open" });
-    root.innerHTML = `
-      
-      
-      
-      `;
-    const panel = root.getElementById("panel");
-    const toggle = root.getElementById("toggle");
-    const back = root.getElementById("back");
-    const forward = root.getElementById("forward");
-    const reload = root.getElementById("reload");
-    const log = root.getElementById("log");
-    const network = root.getElementById("network");
-    if (!panel || !toggle || !back || !forward || !reload || !log || !network) return;
-    state.panel = panel;
-    state.log = log;
-    state.network = network;
-    toggle.addEventListener("click", () => {
-      panel.hidden = !panel.hidden;
-      toggle.setAttribute("aria-expanded", String(!panel.hidden));
-      if (!panel.hidden) render();
-    });
-    back.addEventListener("click", () => history.back());
-    forward.addEventListener("click", () => history.forward());
-    reload.addEventListener("click", () => location.reload());
-    root.querySelector("[data-view=log]").addEventListener("click", () => selectView("log"));
-    root.querySelector("[data-view=network]").addEventListener("click", () => selectView("network"));
-    root.getElementById("clear").addEventListener("click", () => {
-      state.entries.splice(0, state.entries.length);
-      render();
-    });
-    document.documentElement.append(host);
-    record("overlay", "Debug listener ready");
-  }
-
-  globalThis[marker] = {
-    record,
-    mounted: () => Boolean(document.getElementById("rings-webview-debug-overlay")),
-  };
-  navigator.serviceWorker?.addEventListener("message", (event) => {
-    const entry = event.data;
-    if (entry?.type === "rings-webview-debug") {
-      record(entry.scope || "worker", entry.message || "unknown event", entry.level || "info", entry.resource);
-    }
-  });
-  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", mount, { once: true });
-  else mount();
-  navigator.serviceWorker?.ready.then((registration) => {
-    const worker = navigator.serviceWorker.controller || registration.active;
-    worker?.postMessage({ type: "rings-webview-debug-register" });
-  }).catch(() => record("overlay", "Service Worker debug listener unavailable", "error"));
+  const script = document.createElement("script");
+  script.src = "/assets/webview-overlay.js";
+  script.async = false;
+  script.dataset.ringsWebviewOverlayLoader = "";
+  (document.head || document.documentElement).append(script);
 })();
 "#;
 
@@ -191,13 +65,6 @@ struct BrowserGatewayBinding {
     _handler: Closure Promise>,
 }
 
-/// Encode an HTTP(S) address into the application-controlled gateway path.
-pub(crate) fn controlled_gateway_path(input: &str) -> Result {
-    let target = TargetUrl::parse(input).map_err(|error| error.to_string())?;
-    let prefix = GatewayPrefix::new(GATEWAY_PREFIX).map_err(|error| error.to_string())?;
-    Ok(prefix.encode(target.as_url()))
-}
-
 /// Open the local WebView popup without ever passing it a remote URL.
 pub(crate) fn open_webview_popup() -> Result<(), String> {
     crate::browser_api::open_webview_popup()
@@ -246,16 +113,6 @@ pub(crate) async fn register_browser_gateway() -> Result<(), String> {
     Ok(())
 }
 
-/// Ensure that the popup is controlled by the same-origin Service Worker.
-pub(crate) async fn prepare_browser_gateway() -> Result<(), String> {
-    let bridge = crate::browser_api::js_global_prop("RingsWebviewHost")?;
-    let ready = crate::browser_api::js_call0(&bridge, "ensureReady")?;
-    let _ready = crate::browser_api::await_js(ready).await?;
-    let debug = crate::browser_api::js_call0(&bridge, "enableDebug")?;
-    let _debug = crate::browser_api::await_js(debug).await?;
-    Ok(())
-}
-
 async fn dispatch_browser_request(gateway: WebviewNode, request: JsValue) -> JsValue {
     let request = match browser_host_request(&request) {
         Ok(request) => request,
@@ -272,7 +129,7 @@ async fn dispatch_browser_request(gateway: WebviewNode, request: JsValue) -> JsV
             browser_failure(403, format!("rejected: {reason:?}"))
         }
         Err(WebviewError::Cors(error)) => browser_failure(403, format!("CORS rejected: {error}")),
-        Err(error) => browser_failure(502, format!("gateway transport: {error}")),
+        Err(error) => browser_transport_failure(error),
     }
 }
 
@@ -410,14 +267,117 @@ fn browser_redirect(location: &str) -> JsValue {
 }
 
 fn browser_failure(status: u16, error: String) -> JsValue {
+    browser_failure_with(
+        status,
+        default_failure_code(status),
+        default_failure_summary(status),
+        error,
+    )
+}
+
+fn browser_failure_with(
+    status: u16,
+    code: &'static str,
+    summary: &'static str,
+    error: String,
+) -> JsValue {
     let value = Object::new();
     let _ok = crate::browser_api::js_set(&value, "ok", &JsValue::FALSE);
     let _status =
         crate::browser_api::js_set(&value, "status", &JsValue::from_f64(f64::from(status)));
+    let _code = crate::browser_api::js_set(&value, "errorCode", &JsValue::from_str(code));
+    let _summary = crate::browser_api::js_set(&value, "errorSummary", &JsValue::from_str(summary));
     let _error = crate::browser_api::js_set(&value, "error", &JsValue::from_str(error.as_str()));
     value.into()
 }
 
+fn browser_transport_failure(error: WebviewError) -> JsValue {
+    let (failure, message) = match error {
+        WebviewError::Transport(message) => (
+            classify_transport_failure(&message),
+            format!("gateway transport failed: {message}"),
+        ),
+        other => (
+            BrowserFailureKind::GatewayTransport,
+            format!("gateway transport failed: {other}"),
+        ),
+    };
+    browser_failure_with(failure.status(), failure.code(), failure.summary(), message)
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum BrowserFailureKind {
+    GatewayTransport,
+    OnionExitUnavailable,
+    OnionRouteUnavailable,
+}
+
+impl BrowserFailureKind {
+    fn status(self) -> u16 {
+        match self {
+            Self::GatewayTransport => 502,
+            Self::OnionExitUnavailable | Self::OnionRouteUnavailable => 503,
+        }
+    }
+
+    fn code(self) -> &'static str {
+        match self {
+            Self::GatewayTransport => "gateway_transport_failed",
+            Self::OnionExitUnavailable => "onion_exit_unavailable",
+            Self::OnionRouteUnavailable => "onion_route_unavailable",
+        }
+    }
+
+    fn summary(self) -> &'static str {
+        match self {
+            Self::GatewayTransport => "Gateway transport failed.",
+            Self::OnionExitUnavailable => "No live HTTPS onion exit is available.",
+            Self::OnionRouteUnavailable => {
+                "No onion route is currently available for the requested target."
+            }
+        }
+    }
+}
+
+fn classify_transport_failure(message: &str) -> BrowserFailureKind {
+    if message.contains("no live onion exit offers service \"https\"") {
+        BrowserFailureKind::OnionExitUnavailable
+    } else if [
+        "no live onion exit",
+        "not enough relay candidates",
+        "no onion route has a permitted first hop",
+    ]
+    .iter()
+    .any(|needle| message.contains(needle))
+    {
+        BrowserFailureKind::OnionRouteUnavailable
+    } else {
+        BrowserFailureKind::GatewayTransport
+    }
+}
+
+fn default_failure_code(status: u16) -> &'static str {
+    match status {
+        400 => "invalid_webview_request",
+        403 => "webview_request_rejected",
+        404 => "controlled_asset_not_found",
+        502 => "gateway_transport_failed",
+        503 => "gateway_unavailable",
+        _ => "gateway_request_failed",
+    }
+}
+
+fn default_failure_summary(status: u16) -> &'static str {
+    match status {
+        400 => "Invalid WebView request.",
+        403 => "The WebView gateway rejected this request.",
+        404 => "The requested controlled asset was not found.",
+        502 => "Gateway transport failed.",
+        503 => "Gateway service is unavailable.",
+        _ => "Gateway request failed.",
+    }
+}
+
 /// A browser request captured by the Rings-controlled WebView host.
 #[derive(Clone, Debug)]
 pub struct WebviewHostRequest {
@@ -629,8 +589,7 @@ struct WebviewGatewayHost {
 }
 
 impl WebviewGatewayHost
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     async fn handle(&self, request: WebviewHostRequest) -> WebviewResult {
         match self.policy.route(
@@ -720,20 +679,27 @@ struct OnionGatewayTransport {
 #[async_trait(?Send)]
 impl GatewayTransport for OnionGatewayTransport {
     async fn send(&self, request: GatewayRequest) -> WebviewResult {
-        let response = onion::request(
-            &self.provider,
-            onion::OnionProxyHttpRequest {
-                url: request.target.to_string(),
-                method: request.method,
-                headers: request
-                    .headers
-                    .into_iter()
-                    .map(|header| (header.name, header.value))
-                    .collect(),
-                body: request.body,
-                options: onion::OnionProxyOptions::default(),
-            },
-        )
+        let options = onion::OnionProxyOptions::default();
+        if should_trace_onion_route(request.kind) {
+            trace_onion_route(
+                &self.provider,
+                request.target.as_str(),
+                request.kind,
+                options,
+            )
+            .await;
+        }
+        let response = onion::request(&self.provider, onion::OnionProxyHttpRequest {
+            url: request.target.to_string(),
+            method: request.method,
+            headers: request
+                .headers
+                .into_iter()
+                .map(|header| (header.name, header.value))
+                .collect(),
+            body: request.body,
+            options,
+        })
         .await
         .map_err(WebviewError::Transport)?;
         let headers = response
@@ -745,9 +711,108 @@ impl GatewayTransport for OnionGatewayTransport {
     }
 }
 
+fn should_trace_onion_route(kind: GatewayRequestKind) -> bool {
+    matches!(
+        kind,
+        GatewayRequestKind::Navigation | GatewayRequestKind::Fetch | GatewayRequestKind::Xhr
+    )
+}
+
+async fn trace_onion_route(
+    provider: &Arc,
+    target: &str,
+    kind: GatewayRequestKind,
+    options: onion::OnionProxyOptions,
+) {
+    let started = js_sys::Date::now();
+    let result = onion::route(provider, onion::OnionProxyRouteRequest {
+        url: target.to_string(),
+        options,
+    })
+    .await;
+    let duration = (js_sys::Date::now() - started).max(0.0).round();
+    match result {
+        Ok(route) => emit_onion_debug(
+            "route selected",
+            "info",
+            target,
+            kind,
+            Some(&route),
+            None,
+            duration,
+        ),
+        Err(error) => emit_onion_debug(
+            error.as_str(),
+            "error",
+            target,
+            kind,
+            None,
+            Some(error.as_str()),
+            duration,
+        ),
+    }
+}
+
+fn emit_onion_debug(
+    message: &str,
+    level: &str,
+    target: &str,
+    kind: GatewayRequestKind,
+    route: Option<&onion::OnionProxyRoute>,
+    error: Option<&str>,
+    duration_ms: f64,
+) {
+    let Ok(bridge) = crate::browser_api::js_global_prop("RingsWebviewHost") else {
+        return;
+    };
+    let Ok(record) = crate::browser_api::js_method(&bridge, "recordDebugEntry") else {
+        return;
+    };
+    let onion = Object::new();
+    let _ = crate::browser_api::js_set(&onion, "target", &JsValue::from_str(target));
+    let _ =
+        crate::browser_api::js_set(&onion, "kind", &JsValue::from_str(gateway_kind_label(kind)));
+    let _ = crate::browser_api::js_set(&onion, "durationMs", &JsValue::from_f64(duration_ms));
+    if let Some(route) = route {
+        let hops = Array::new();
+        for hop in route.hops.iter() {
+            hops.push(&JsValue::from_str(hop));
+        }
+        let _ = crate::browser_api::js_set(&onion, "phase", &JsValue::from_str("selected"));
+        let _ = crate::browser_api::js_set(&onion, "service", &JsValue::from_str(&route.service));
+        let _ = crate::browser_api::js_set(&onion, "exit", &JsValue::from_str(&route.exit));
+        let _ = crate::browser_api::js_set(&onion, "hops", &hops.into());
+    } else {
+        let _ = crate::browser_api::js_set(&onion, "phase", &JsValue::from_str("failed"));
+        let _ = crate::browser_api::js_set(&onion, "service", &JsValue::from_str("https"));
+        let _ = crate::browser_api::js_set(&onion, "hops", &Array::new().into());
+    }
+    if let Some(error) = error {
+        let _ = crate::browser_api::js_set(&onion, "error", &JsValue::from_str(error));
+    }
+
+    let args = Array::new();
+    args.push(&JsValue::from_str("onion"));
+    args.push(&JsValue::from_str(message));
+    args.push(&JsValue::from_str(level));
+    args.push(&JsValue::UNDEFINED);
+    args.push(&JsValue::from_bool(true));
+    args.push(onion.as_ref());
+    let _ = Reflect::apply(&record, &bridge, &args);
+}
+
+fn gateway_kind_label(kind: GatewayRequestKind) -> &'static str {
+    match kind {
+        GatewayRequestKind::Navigation => "navigation",
+        GatewayRequestKind::Subresource => "subresource",
+        GatewayRequestKind::Fetch => "fetch",
+        GatewayRequestKind::Xhr => "xhr",
+    }
+}
+
 fn webview_bootstrap(target: &Url) -> String {
     format!(
-        "{}\n{WEBVIEW_DEBUG_OVERLAY}",
+        "{}\n{WEBVIEW_OVERLAY_LOADER}",
         bootstrap_script(GATEWAY_PREFIX, target)
     )
 }
@@ -879,10 +944,10 @@ mod tests {
         assert_eq!(sent_request.target.as_str(), target.as_url().as_str());
         assert_eq!(sent_request.method, "POST");
         assert_eq!(sent_request.body, vec![0x00, 0xff]);
-        assert_eq!(
-            sent_request.headers,
-            vec![GatewayHeader::new("accept", "text/html")?]
-        );
+        assert_eq!(sent_request.headers, vec![GatewayHeader::new(
+            "accept",
+            "text/html"
+        )?]);
         Ok(())
     }
 
@@ -910,15 +975,31 @@ mod tests {
     }
 
     #[wasm_bindgen_test]
-    fn popup_addresses_only_produce_controlled_gateway_paths() -> WebviewResult<()> {
-        let path = controlled_gateway_path("https://example.test/docs/?q=1")
+    fn onion_route_unavailable_is_reported_without_wasm_stack() -> WebviewResult<()> {
+        let response = browser_transport_failure(WebviewError::Transport(
+            "onion proxy request failed: Onion route error: no live onion exit offers service \"https\""
+                .to_string(),
+        ));
+
+        let status = crate::browser_api::js_prop(&response, "status")
+            .map_err(WebviewError::Browser)?
+            .as_f64()
+            .ok_or_else(|| WebviewError::Browser("failure status was not numeric".to_string()))?;
+        let error = crate::browser_api::js_string_field(&response, "error")
+            .map_err(WebviewError::Browser)?;
+        let code = crate::browser_api::js_string_field(&response, "errorCode")
+            .map_err(WebviewError::Browser)?;
+        let summary = crate::browser_api::js_string_field(&response, "errorSummary")
             .map_err(WebviewError::Browser)?;
 
+        assert_eq!(status, 503.0);
+        assert_eq!(code, "onion_exit_unavailable");
+        assert_eq!(summary, "No live HTTPS onion exit is available.");
         assert_eq!(
-            path,
-            "/webview/https%3A%2F%2Fexample%2Etest%2Fdocs%2F%3Fq%3D1"
+            error,
+            "gateway transport failed: onion proxy request failed: Onion route error: no live onion exit offers service \"https\""
         );
-        assert!(controlled_gateway_path("file:///tmp/page.html").is_err());
+        assert!(!error.contains("wasm-function"));
         Ok(())
     }
 
diff --git a/frontend/src/webview_ui.rs b/frontend/src/webview_ui.rs
index cb4b11ffa..50cb787b5 100644
--- a/frontend/src/webview_ui.rs
+++ b/frontend/src/webview_ui.rs
@@ -1,110 +1,22 @@
-//! Application-owned launch page for the controlled WebView.
+//! Application-owned launch surface for the controlled WebView.
 
-use wasm_bindgen::JsCast;
-use web_sys::HtmlInputElement;
-use web_sys::InputEvent;
-use web_sys::MouseEvent;
-use web_sys::SubmitEvent;
 use yew::prelude::*;
 
 use crate::styles;
-use crate::webview;
 
 const DEFAULT_TARGET: &str = "https://example.com/";
 
-/// Render the local launch page before the popup becomes a controlled document.
+/// Render only the local page surface. The browser chrome and debug console are
+/// provided by `assets/webview-overlay.js` in every WebView document.
 #[function_component(WebviewShell)]
 pub(crate) fn webview_shell() -> Html {
-    let address = use_state(|| DEFAULT_TARGET.to_string());
-    let status = use_state(|| "Enter an HTTP(S) address".to_string());
-
-    let navigate = {
-        let address = address.clone();
-        let status = status.clone();
-        Callback::<()>::from(move |_| {
-            let requested = (*address).trim().to_string();
-            let path = match webview::controlled_gateway_path(requested.as_str()) {
-                Ok(path) => path,
-                Err(error) => {
-                    status.set(error);
-                    return;
-                }
-            };
-
-            status.set("Connecting through the local Rings gateway".to_string());
-            let status = status.clone();
-            wasm_bindgen_futures::spawn_local(async move {
-                match webview::prepare_browser_gateway().await {
-                    Ok(()) => {
-                        status.set("Request sent to the local Rings gateway".to_string());
-                        let Some(window) = web_sys::window() else {
-                            status.set("Unable to access the popup window".to_string());
-                            return;
-                        };
-                        if let Err(error) = window.location().set_href(path.as_str()) {
-                            let detail = error
-                                .as_string()
-                                .unwrap_or_else(|| "unknown browser error".to_string());
-                            status.set(format!("Unable to open controlled page: {detail}"));
-                        }
-                    }
-                    Err(error) => status.set(format!("gateway unavailable: {error}")),
-                }
-            });
-        })
-    };
-    let on_address = {
-        let address = address.clone();
-        Callback::from(move |event: InputEvent| {
-            if let Some(input) = event
-                .target()
-                .and_then(|target| target.dyn_into::().ok())
-            {
-                address.set(input.value());
-            }
-        })
-    };
-    let on_submit = {
-        let navigate = navigate.clone();
-        Callback::from(move |event: SubmitEvent| {
-            event.prevent_default();
-            navigate.emit(());
-        })
-    };
-    let on_close = Callback::from(move |_: MouseEvent| {
-        if let Some(window) = web_sys::window() {
-            let _closed = window.close();
-        }
-    });
-
     html! {
-        

+        

             
-            

-                

-                    
-                    { "Rings WebView" }
-                

-                

-                    
-                    
-                    
-                

-                
{ (*status).clone() }

-                
-            

             

         

     }

From 225c1731c97750673aab538208ac733e20fd56ab Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Wed, 22 Jul 2026 04:39:47 +0800
Subject: [PATCH 04/23] Fix DHT successor sync for browser joins

---
 .../core/src/message/handlers/connection.rs   | 276 ++++++++++++++----
 .../src/message/handlers/stabilization.rs     |  20 +-
 .../core/src/tests/default/test_connection.rs |  21 +-
 3 files changed, 249 insertions(+), 68 deletions(-)

diff --git a/crates/core/src/message/handlers/connection.rs b/crates/core/src/message/handlers/connection.rs
index 8fb3b66f5..78bdef44d 100644
--- a/crates/core/src/message/handlers/connection.rs
+++ b/crates/core/src/message/handlers/connection.rs
@@ -1,8 +1,11 @@
 use async_trait::async_trait;
 
+use crate::dht::successor::SuccessorReader;
 use crate::dht::types::Chord;
 use crate::dht::types::CorrectChord;
+use crate::dht::topology;
 use crate::dht::Did;
+use crate::dht::PeerRing;
 use crate::dht::PeerRingAction;
 use crate::dht::TopoInfo;
 use crate::error::Error;
@@ -38,6 +41,21 @@ fn topology_has_confirmed_peer(info: &TopoInfo) -> bool {
     info.predecessor.is_some() || !info.successors.is_empty()
 }
 
+fn connect_successor_hint(dht: &PeerRing, requester: Did, reported: Did) -> Result {
+    if reported != requester {
+        return Ok(reported);
+    }
+
+    let mut candidates = dht.successors().list()?;
+    candidates.push(dht.did);
+    candidates.retain(|candidate| *candidate != requester);
+
+    Ok(topology::successors(&candidates, requester, 1)
+        .into_iter()
+        .next()
+        .unwrap_or(reported))
+}
+
 /// QueryForTopoInfoSend is direct message
 #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
@@ -63,9 +81,11 @@ impl HandleMsg for MessageHandler {
     async fn handle(&self, _ctx: &MessagePayload, msg: &QueryForTopoInfoReport) -> Result<()> {
         match msg.then {
             ::Then::SyncSuccessor => {
-                for peer in msg.info.successors.iter() {
-                    if self.transport.get_connection(*peer).is_some() {
-                        self.join_dht(*peer).await?;
+                let successors = msg.info.successors.clone();
+                self.connect_dht_peers(successors.iter().copied()).await?;
+                for peer in successors {
+                    if self.transport.get_connection(peer).is_some() {
+                        self.join_dht(peer).await?;
                     }
                 }
             }
@@ -146,6 +166,14 @@ impl HandleMsg for MessageHandler {
                 if msg.accepts_local_successor(self.dht.did) {
                     match &msg.then {
                         FindSuccessorThen::Report(handler) => {
+                            let did = match handler {
+                                FindSuccessorReportHandler::Connect => connect_successor_hint(
+                                    self.dht.as_ref(),
+                                    ctx.relay.try_origin_sender()?,
+                                    did,
+                                )?,
+                                _ => did,
+                            };
                             self.run_effects([PayloadRelayFunctor::send_report_message(
                                 ctx,
                                 Message::FindSuccessorReport(FindSuccessorReport {
@@ -211,6 +239,7 @@ pub mod tests {
     use crate::ecc::tests::gen_ordered_keys;
     use crate::ecc::SecretKey;
     use crate::tests::default::assert_no_more_msg;
+    use crate::tests::default::gen_pure_dht;
     use crate::tests::default::prepare_node;
     use crate::tests::default::wait_for_msgs;
     use crate::tests::default::Node;
@@ -234,6 +263,27 @@ pub mod tests {
         assert!(topology_has_confirmed_peer(&confirmed));
     }
 
+    #[test]
+    fn connect_successor_hint_skips_requester_self_report() -> Result<()> {
+        let keys = gen_ordered_keys(4);
+        let local = keys[0].address().into();
+        let requester = keys[1].address().into();
+        let next = keys[2].address().into();
+        let tail = keys[3].address().into();
+        let dht = gen_pure_dht(local);
+
+        dht.join(next)?;
+        dht.join(tail)?;
+        dht.join(requester)?;
+
+        assert_eq!(dht.successors().list()?, vec![requester, next, tail]);
+        assert_eq!(
+            connect_successor_hint(&dht, requester, requester)?,
+            next
+        );
+        Ok(())
+    }
+
     // node1.key < node2.key < node3.key
     //
     // Firstly, we connect node1 to node2, node2 to node3.
@@ -379,26 +429,41 @@ pub mod tests {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before connect via DHT ===");
-        node1.assert_transports(vec![node2.did()]);
-        node2.assert_transports(vec![node1.did(), node3.did()]);
-        node3.assert_transports(vec![node2.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![node2.did(),]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node3.did(),
-            node1.did()
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
+        if node1.swarm.transport.get_connection(node3.did()).is_some() {
+            node1.assert_transports(vec![node2.did(), node3.did()]);
+            node2.assert_transports(vec![node1.did(), node3.did()]);
+            node3.assert_transports(vec![node1.did(), node2.did()]);
+            assert_eq!(node1.dht().successors().list()?, vec![
+                node2.did(),
+                node3.did()
+            ]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node3.did(),
+                node1.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![
+                node1.did(),
+                node2.did()
+            ]);
+        } else {
+            node1.assert_transports(vec![node2.did()]);
+            node2.assert_transports(vec![node1.did(), node3.did()]);
+            node3.assert_transports(vec![node2.did()]);
+            assert_eq!(node1.dht().successors().list()?, vec![node2.did(),]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node3.did(),
+                node1.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
+        }
 
         println!("=============================================");
         println!("||  now we connect node1 to node3 via DHT  ||");
         println!("=============================================");
 
-        // check node1 and node3 is not connected to each other
-        assert!(node1.swarm.transport.get_connection(node3.did()).is_none());
-        // node1's successor should be node2 now
-        assert_eq!(node1.dht().successors().max()?, node2.did());
-
-        node1.swarm.connect(node3.did()).await?;
+        if node1.swarm.transport.get_connection(node3.did()).is_none() {
+            node1.swarm.connect(node3.did()).await?;
+        }
         wait_for_msgs([&node1, &node2, &node3]).await;
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
@@ -452,26 +517,41 @@ pub mod tests {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before connect via DHT ===");
-        node1.assert_transports(vec![node2.did()]);
-        node2.assert_transports(vec![node1.did(), node3.did()]);
-        node3.assert_transports(vec![node2.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![node2.did()]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node1.did(),
-            node3.did()
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
+        if node1.swarm.transport.get_connection(node3.did()).is_some() {
+            node1.assert_transports(vec![node2.did(), node3.did()]);
+            node2.assert_transports(vec![node1.did(), node3.did()]);
+            node3.assert_transports(vec![node1.did(), node2.did()]);
+            assert_eq!(node1.dht().successors().list()?, vec![
+                node3.did(),
+                node2.did()
+            ]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node1.did(),
+                node3.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![
+                node2.did(),
+                node1.did()
+            ]);
+        } else {
+            node1.assert_transports(vec![node2.did()]);
+            node2.assert_transports(vec![node1.did(), node3.did()]);
+            node3.assert_transports(vec![node2.did()]);
+            assert_eq!(node1.dht().successors().list()?, vec![node2.did()]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node1.did(),
+                node3.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
+        }
 
         println!("=============================================");
         println!("||  now we connect node1 to node3 via DHT  ||");
         println!("=============================================");
 
-        // check node1 and node3 is not connected to each other
-        assert!(node1.swarm.transport.get_connection(node3.did()).is_none());
-        // node1's successor should be node2 now
-        assert_eq!(node1.dht().successors().max()?, node2.did());
-
-        node1.swarm.connect(node3.did()).await?;
+        if node1.swarm.transport.get_connection(node3.did()).is_none() {
+            node1.swarm.connect(node3.did()).await?;
+        }
         wait_for_msgs([&node1, &node2, &node3]).await;
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
@@ -518,23 +598,28 @@ pub mod tests {
         // Poll for convergence rather than sleeping a fixed amount: under the
         // release-LTO CI run with native WebRTC, 6s is not always enough and the
         // assertions below would flake. The expected final state is unchanged.
-        wait_until("node4 joined: DHT successors converged", || {
-            Ok(
-                node1.dht().successors().list()? == vec![node2.did(), node3.did(), node4.did()]
-                    && node2.dht().successors().list()?
-                        == vec![node3.did(), node4.did(), node1.did()]
-                    && node3.dht().successors().list()? == vec![node1.did(), node2.did()]
-                    && node4.dht().successors().list()? == vec![node1.did(), node2.did()],
-            )
-        })
+        wait_until_with_state(
+            "node4 joined: DHT successors converged",
+            || {
+                Ok(
+                    node1.dht().successors().list()? == vec![node2.did(), node3.did(), node4.did()]
+                        && node2.dht().successors().list()?
+                            == vec![node3.did(), node4.did(), node1.did()]
+                        && node3.dht().successors().list()?
+                            == vec![node4.did(), node1.did(), node2.did()]
+                        && node4.dht().successors().list()?
+                            == vec![node1.did(), node2.did(), node3.did()],
+                )
+            },
+            || describe_nodes([&node1, &node2, &node3, &node4]),
+        )
         .await?;
 
         println!("=== Check state before connect via DHT ===");
         node1.assert_transports(vec![node2.did(), node3.did(), node4.did()]);
         node2.assert_transports(vec![node3.did(), node4.did(), node1.did()]);
-        node3.assert_transports(vec![node1.did(), node2.did()]);
-        // node4 will connect node1 after connecting node2, because node2 notified node4 that node1 is its predecessor.
-        node4.assert_transports(vec![node1.did(), node2.did()]);
+        node3.assert_transports(vec![node4.did(), node1.did(), node2.did()]);
+        node4.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
         assert_eq!(node1.dht().successors().list()?, vec![
             node2.did(),
             node3.did(),
@@ -546,12 +631,14 @@ pub mod tests {
             node1.did(),
         ]);
         assert_eq!(node3.dht().successors().list()?, vec![
+            node4.did(),
             node1.did(),
             node2.did(),
         ]);
         assert_eq!(node4.dht().successors().list()?, vec![
             node1.did(),
             node2.did(),
+            node3.did(),
         ]);
 
         println!("========================================");
@@ -566,20 +653,27 @@ pub mod tests {
         );
         println!("==================================================");
 
-        node4.swarm.connect(node3.did()).await?;
+        if node4.swarm.transport.get_connection(node3.did()).is_none() {
+            node4.swarm.connect(node3.did()).await?;
+        }
         // Same as above: poll for the post-connect converged state instead of a
         // fixed 6s sleep so the test is robust under CI contention.
-        wait_until("node4 connected node3: DHT successors converged", || {
-            Ok(
-                node1.dht().successors().list()? == vec![node2.did(), node3.did(), node4.did()]
-                    && node2.dht().successors().list()?
-                        == vec![node3.did(), node4.did(), node1.did()]
-                    && node3.dht().successors().list()?
-                        == vec![node4.did(), node1.did(), node2.did()]
-                    && node4.dht().successors().list()?
-                        == vec![node1.did(), node2.did(), node3.did()],
-            )
-        })
+        wait_until_with_state(
+            "node4 connected node3: DHT successors converged",
+            || {
+                Ok(
+                    node1.dht().successors().list()?
+                        == vec![node2.did(), node3.did(), node4.did()]
+                        && node2.dht().successors().list()?
+                            == vec![node3.did(), node4.did(), node1.did()]
+                        && node3.dht().successors().list()?
+                            == vec![node4.did(), node1.did(), node2.did()]
+                        && node4.dht().successors().list()?
+                            == vec![node1.did(), node2.did(), node3.did()],
+                )
+            },
+            || describe_nodes([&node1, &node2, &node3, &node4]),
+        )
         .await?;
 
         println!("=== Check state after connect via DHT ===");
@@ -611,6 +705,42 @@ pub mod tests {
         Ok(())
     }
 
+    #[cfg(feature = "dummy")]
+    #[tokio::test]
+    async fn joining_between_bootstrap_and_successor_connects_successor_hint() -> Result<()> {
+        let keys = gen_ordered_keys(4);
+        let (node1, node2, node3) =
+            test_triple_ordered_nodes_connection(keys[0], keys[2], keys[3]).await?;
+        let joining = prepare_node(keys[1]).await;
+
+        manually_establish_connection(&joining.swarm, &node1.swarm).await;
+        wait_until("joining peer connects past bootstrap successor self-report", || {
+            Ok(joining
+                .swarm
+                .transport
+                .get_connection(node2.did())
+                .is_some())
+        })
+        .await?;
+
+        wait_for_msgs([&node1, &node2, &node3, &joining]).await;
+        assert_no_more_msg([&node1, &node2, &node3, &joining]).await;
+
+        joining.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
+        assert_eq!(node1.dht().successors().list()?, vec![
+            joining.did(),
+            node2.did(),
+            node3.did(),
+        ]);
+        assert_eq!(joining.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did(),
+            node1.did(),
+        ]);
+
+        Ok(())
+    }
+
     /// Poll `cond` every 200ms until it returns true, failing after ~60s.
     /// Used instead of fixed sleeps so the test is deterministic regardless of
     /// how long the WebRTC handshake/teardown takes on a given machine.
@@ -619,13 +749,43 @@ pub mod tests {
     /// ~200ms each, so on a host with many network interfaces (lots of
     /// candidate pairs) establishing the connection can legitimately take ~20s.
     async fn wait_until(msg: &str, mut cond: impl FnMut() -> Result) -> Result<()> {
+        wait_until_with_state(msg, &mut cond, String::new).await
+    }
+
+    async fn wait_until_with_state(
+        msg: &str,
+        mut cond: impl FnMut() -> Result,
+        state: impl Fn() -> String,
+    ) -> Result<()> {
         for _ in 0..300 {
             if cond()? {
                 return Ok(());
             }
             sleep(Duration::from_millis(200)).await;
         }
-        Err(Error::InvalidMessage(format!("timeout waiting for: {msg}")))
+        let state = state();
+        if state.is_empty() {
+            Err(Error::InvalidMessage(format!("timeout waiting for: {msg}")))
+        } else {
+            Err(Error::InvalidMessage(format!(
+                "timeout waiting for: {msg}\n{state}"
+            )))
+        }
+    }
+
+    fn describe_nodes<'a>(nodes: impl IntoIterator) -> String {
+        nodes
+            .into_iter()
+            .map(|node| {
+                format!(
+                    "{:?}: successors={:?}, transports={:?}",
+                    node.did(),
+                    node.dht().successors().list().unwrap_or_default(),
+                    node.swarm.transport.get_connection_ids(),
+                )
+            })
+            .collect::>()
+            .join("\n")
     }
 
     #[tokio::test]
diff --git a/crates/core/src/message/handlers/stabilization.rs b/crates/core/src/message/handlers/stabilization.rs
index e7b52424c..3801fc143 100644
--- a/crates/core/src/message/handlers/stabilization.rs
+++ b/crates/core/src/message/handlers/stabilization.rs
@@ -282,12 +282,18 @@ mod test {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before stabilization ===");
-        assert_eq!(node1.dht().successors().list()?, vec![node2.did()]);
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did()
+        ]);
         assert_eq!(node2.dht().successors().list()?, vec![
             node3.did(),
             node1.did()
         ]);
-        assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node1.did(),
+            node2.did()
+        ]);
         assert!(node1.dht().lock_predecessor()?.is_none());
         assert!(node2.dht().lock_predecessor()?.is_none());
         assert!(node3.dht().lock_predecessor()?.is_none());
@@ -371,12 +377,18 @@ mod test {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before stabilization ===");
-        assert_eq!(node1.dht().successors().list()?, vec![node2.did()]);
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node3.did(),
+            node2.did()
+        ]);
         assert_eq!(node2.dht().successors().list()?, vec![
             node1.did(),
             node3.did()
         ]);
-        assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node2.did(),
+            node1.did()
+        ]);
         assert!(node1.dht().lock_predecessor()?.is_none());
         assert!(node2.dht().lock_predecessor()?.is_none());
         assert!(node3.dht().lock_predecessor()?.is_none());
diff --git a/crates/core/src/tests/default/test_connection.rs b/crates/core/src/tests/default/test_connection.rs
index 149e8aeca..9d5b02261 100644
--- a/crates/core/src/tests/default/test_connection.rs
+++ b/crates/core/src/tests/default/test_connection.rs
@@ -77,18 +77,27 @@ async fn test_handshake_on_both_sides(key1: SecretKey, key2: SecretKey, key3: Se
         WebrtcConnectionState::Connected
     );
 
+    let direct_connection_already_synced =
+        node1.swarm.transport.get_connection(node2.did()).is_some()
+            && node2.swarm.transport.get_connection(node1.did()).is_some();
+
     // connect to each at same time
     // Node 1 -> Offer -> Node 2
     // Node 2 -> Offer -> Node 1
     _ = node1.swarm.connect(node2.did()).await;
     _ = node2.swarm.connect(node1.did()).await;
 
-    // Both offers exist but neither handshake has been admitted. Pending peers
-    // must remain invisible to the public connection view.
-    assert!(node1.swarm.transport.get_connection(node2.did()).is_none());
-    assert!(node2.swarm.transport.get_connection(node1.did()).is_none());
-    assert_eq!(node1.swarm.transport.pending_connection_count().unwrap(), 1);
-    assert_eq!(node2.swarm.transport.pending_connection_count().unwrap(), 1);
+    if direct_connection_already_synced {
+        assert_eq!(node1.swarm.transport.pending_connection_count().unwrap(), 0);
+        assert_eq!(node2.swarm.transport.pending_connection_count().unwrap(), 0);
+    } else {
+        // Both offers exist but neither handshake has been admitted. Pending
+        // peers must remain invisible to the public connection view.
+        assert!(node1.swarm.transport.get_connection(node2.did()).is_none());
+        assert!(node2.swarm.transport.get_connection(node1.did()).is_none());
+        assert_eq!(node1.swarm.transport.pending_connection_count().unwrap(), 1);
+        assert_eq!(node2.swarm.transport.pending_connection_count().unwrap(), 1);
+    }
 
     wait_for_msgs([&node1, &node2, &node3]).await;
     assert_no_more_msg([&node1, &node2, &node3]).await;

From 90ab44f85ac4fbecda93637404dc90df80c3a9d3 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Wed, 22 Jul 2026 05:08:11 +0800
Subject: [PATCH 05/23] Clean stale DHT topology peers

---
 crates/core/src/dht/stabilization.rs          | 299 ++++++++++++++----
 crates/core/src/swarm/transport.rs            |  39 ++-
 crates/core/src/swarm/transport/tests.rs      |  18 +-
 .../src/tests/default/test_stabilization.rs   | 151 +++++++++
 4 files changed, 443 insertions(+), 64 deletions(-)

diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index 3c9db6757..7c5505c81 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -1,5 +1,7 @@
 //! Stabilization run daemons to maintain dht.
 
+use std::collections::BTreeMap;
+use std::collections::BTreeSet;
 use std::future::Future;
 use std::sync::Arc;
 use std::time::Duration;
@@ -21,6 +23,8 @@ use crate::dht::PeerRingRemoteAction;
 use crate::dht::TopoInfo;
 use crate::error::Error;
 use crate::error::Result;
+use crate::measure::PeerMeasurement;
+use crate::measure::PeerQualityThresholds;
 use crate::message::FindSuccessorReportHandler;
 use crate::message::FindSuccessorSend;
 use crate::message::FindSuccessorThen;
@@ -31,8 +35,78 @@ use crate::message::PayloadSender;
 use crate::message::QueryForTopoInfoSend;
 use crate::message::SyncEntriesWithSuccessor;
 use crate::swarm::transport::SwarmTransport;
+use crate::utils::get_epoch_ms_i64;
 
 const STABILIZATION_STEP_TIMEOUT: Duration = Duration::from_secs(30);
+const DISCONNECTED_CONNECTION_GRACE_MS: i64 = 30_000;
+const DHT_TOPOLOGY_EVICTION_THRESHOLDS: PeerQualityThresholds =
+    PeerQualityThresholds::new(3, 10, 10);
+
+#[derive(Clone, Copy, Debug)]
+enum TopologyPeerRemovalReason {
+    NoAdmittedTransport,
+    MissingTransportObject,
+    TerminalTransport(WebrtcConnectionState),
+    DisconnectedGraceElapsed {
+        disconnected_for_ms: i64,
+        grace_ms: i64,
+    },
+    LocalFailureLimit(PeerMeasurement),
+}
+
+impl TopologyPeerRemovalReason {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::NoAdmittedTransport => "no_admitted_transport",
+            Self::MissingTransportObject => "missing_transport_object",
+            Self::TerminalTransport(_) => "terminal_transport",
+            Self::DisconnectedGraceElapsed { .. } => "disconnected_grace_elapsed",
+            Self::LocalFailureLimit(_) => "local_failure_limit",
+        }
+    }
+
+    const fn transport_state(self) -> Option {
+        match self {
+            Self::TerminalTransport(state) => Some(state),
+            _ => None,
+        }
+    }
+
+    const fn disconnected_for_ms(self) -> Option {
+        match self {
+            Self::DisconnectedGraceElapsed {
+                disconnected_for_ms,
+                ..
+            } => Some(disconnected_for_ms),
+            _ => None,
+        }
+    }
+
+    const fn disconnected_grace_ms(self) -> Option {
+        match self {
+            Self::DisconnectedGraceElapsed { grace_ms, .. } => Some(grace_ms),
+            _ => None,
+        }
+    }
+
+    const fn measurement(self) -> Option {
+        match self {
+            Self::LocalFailureLimit(measurement) => Some(measurement),
+            _ => None,
+        }
+    }
+
+    const fn should_disconnect_transport(self) -> bool {
+        !matches!(self, Self::NoAdmittedTransport)
+    }
+}
+
+const fn is_terminal_transport_state(state: WebrtcConnectionState) -> bool {
+    matches!(
+        state,
+        WebrtcConnectionState::Failed | WebrtcConnectionState::Closed
+    )
+}
 
 /// The stabilization runner.
 #[derive(Clone)]
@@ -248,65 +322,180 @@ impl Stabilizer {
     /// Clean unavailable connections in transport.
     pub async fn clean_unavailable_connections(&self) -> Result<()> {
         self.transport.expire_pending_connections().await?;
-        let conns = self.transport.admitted_connections();
-
-        for (did, conn) in conns.into_iter() {
-            let state = conn.webrtc_connection_state();
-            // Only terminal states are cleaned. `Disconnected` is transient: ICE
-            // can recover from it, so tearing it down here (the stabilizer runs
-            // every few seconds) would kill connections during a brief blip
-            // before WebRTC self-heals. This mirrors the swarm callback, which
-            // also only leaves the DHT on `Failed`/`Closed`.
-            if matches!(
-                state,
-                WebrtcConnectionState::Failed | WebrtcConnectionState::Closed
-            ) {
-                tracing::info!(
-                    target: "rings_core::dht::stabilization",
-                    local = %self.dht.did,
-                    peer = %did,
-                    state = ?state,
-                    "STABILIZATION clean_unavailable selected terminal transport"
-                );
-                let should_repair = self
-                    .dht
-                    .peer_may_share_storage_responsibility(did, self.transport.storage_redundancy())
-                    .await?;
-                tracing::debug!(
-                    target: "rings_core::dht::stabilization",
-                    local = %self.dht.did,
-                    peer = %did,
-                    state = ?state,
-                    should_repair,
-                    "STABILIZATION clean_unavailable disconnect start"
-                );
-                self.transport.disconnect(did).await?;
-                tracing::debug!(
-                    target: "rings_core::dht::stabilization",
-                    local = %self.dht.did,
-                    peer = %did,
-                    state = ?state,
-                    should_repair,
-                    "STABILIZATION clean_unavailable disconnect complete"
-                );
-                if should_repair {
-                    tracing::debug!(
-                        target: "rings_core::dht::stabilization",
-                        local = %self.dht.did,
-                        peer = %did,
-                        "STABILIZATION clean_unavailable repair start"
-                    );
-                    self.repair_storage().await?;
-                    tracing::debug!(
-                        target: "rings_core::dht::stabilization",
-                        local = %self.dht.did,
-                        peer = %did,
-                        "STABILIZATION clean_unavailable repair complete"
-                    );
+        let admitted_states = self.admitted_connection_states();
+        let topology_peers = self.dht_topology_peers()?;
+        let mut candidates = topology_peers;
+        candidates.extend(self.transport.admitted_connection_ids());
+        let now_ms = get_epoch_ms_i64();
+
+        for did in candidates {
+            let admitted = self.transport.is_admitted_connection(did);
+            let transport_state = admitted_states.get(&did).copied();
+            if let Some(reason) = self
+                .topology_peer_removal_reason(did, admitted, transport_state, now_ms)
+                .await
+            {
+                self.remove_unavailable_peer(did, reason).await?;
+            }
+        }
+
+        Ok(())
+    }
+
+    fn admitted_connection_states(&self) -> BTreeMap {
+        self.transport
+            .admitted_connections()
+            .into_iter()
+            .map(|(did, conn)| (did, conn.webrtc_connection_state()))
+            .collect()
+    }
+
+    fn dht_topology_peers(&self) -> Result> {
+        let mut peers = BTreeSet::new();
+
+        for did in self.dht.successors().list()? {
+            if did != self.dht.did {
+                peers.insert(did);
+            }
+        }
+
+        if let Some(predecessor) = *self.dht.lock_predecessor()? {
+            if predecessor != self.dht.did {
+                peers.insert(predecessor);
+            }
+        }
+
+        {
+            let finger = self.dht.lock_finger()?;
+            for did in finger.list().iter().flatten().copied() {
+                if did != self.dht.did {
+                    peers.insert(did);
+                }
+            }
+        }
+
+        Ok(peers)
+    }
+
+    async fn topology_peer_removal_reason(
+        &self,
+        did: Did,
+        admitted: bool,
+        transport_state: Option,
+        now_ms: i64,
+    ) -> Option {
+        if !admitted {
+            return Some(TopologyPeerRemovalReason::NoAdmittedTransport);
+        }
+
+        let Some(state) = transport_state else {
+            return Some(TopologyPeerRemovalReason::MissingTransportObject);
+        };
+
+        if is_terminal_transport_state(state) {
+            return Some(TopologyPeerRemovalReason::TerminalTransport(state));
+        }
+
+        if let Some(measurement) = self.transport.peer_measurement(did).await {
+            if measurement
+                .evidence
+                .reaches_failure_limit(DHT_TOPOLOGY_EVICTION_THRESHOLDS)
+            {
+                return Some(TopologyPeerRemovalReason::LocalFailureLimit(
+                    measurement,
+                ));
+            }
+        }
+
+        if matches!(state, WebrtcConnectionState::Disconnected) {
+            if let Some(disconnected_since_ms) = self.transport.peer_disconnected_since_ms(did) {
+                let disconnected_for_ms = now_ms.saturating_sub(disconnected_since_ms);
+                if disconnected_for_ms >= DISCONNECTED_CONNECTION_GRACE_MS {
+                    return Some(TopologyPeerRemovalReason::DisconnectedGraceElapsed {
+                        disconnected_for_ms,
+                        grace_ms: DISCONNECTED_CONNECTION_GRACE_MS,
+                    });
                 }
             }
         }
 
+        None
+    }
+
+    async fn remove_unavailable_peer(
+        &self,
+        did: Did,
+        reason: TopologyPeerRemovalReason,
+    ) -> Result<()> {
+        let should_repair = self
+            .dht
+            .peer_may_share_storage_responsibility(did, self.transport.storage_redundancy())
+            .await?;
+        tracing::info!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            peer = %did,
+            reason = reason.as_str(),
+            state = ?reason.transport_state(),
+            disconnected_for_ms = ?reason.disconnected_for_ms(),
+            disconnected_grace_ms = ?reason.disconnected_grace_ms(),
+            measurement = ?reason.measurement(),
+            should_repair,
+            "STABILIZATION clean_unavailable selected peer"
+        );
+
+        if reason.should_disconnect_transport() {
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %did,
+                reason = reason.as_str(),
+                "STABILIZATION clean_unavailable disconnect start"
+            );
+            self.transport.disconnect(did).await?;
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %did,
+                reason = reason.as_str(),
+                "STABILIZATION clean_unavailable disconnect complete"
+            );
+        } else {
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %did,
+                reason = reason.as_str(),
+                "STABILIZATION clean_unavailable topology remove start"
+            );
+            self.dht.remove(did)?;
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %did,
+                reason = reason.as_str(),
+                "STABILIZATION clean_unavailable topology remove complete"
+            );
+        }
+
+        if should_repair {
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %did,
+                reason = reason.as_str(),
+                "STABILIZATION clean_unavailable repair start"
+            );
+            self.repair_storage().await?;
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %did,
+                reason = reason.as_str(),
+                "STABILIZATION clean_unavailable repair complete"
+            );
+        }
+
         Ok(())
     }
 
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index f5999c728..4aa7b5e19 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -201,7 +201,7 @@ pub struct SwarmTransport {
     active_peers: Mutex>,
     storage_lookup_observations: Mutex,
     pending_storage_sync_acks: Mutex,
-    measured_disconnects: Mutex>,
+    measured_disconnects: Mutex>,
     measure: Option,
 }
 
@@ -475,7 +475,7 @@ impl SwarmTransport {
             active_peers: Mutex::new(BTreeSet::new()),
             storage_lookup_observations: Mutex::new(BTreeMap::new()),
             pending_storage_sync_acks: Mutex::new(BTreeMap::new()),
-            measured_disconnects: Mutex::new(BTreeSet::new()),
+            measured_disconnects: Mutex::new(BTreeMap::new()),
             measure,
         }
     }
@@ -536,8 +536,9 @@ impl SwarmTransport {
     /// Invariant: for one connection epoch, at most one `Disconnected` counter is
     /// recorded. `record_peer_connected` starts a new epoch by clearing the marker.
     pub(crate) async fn record_peer_disconnected(&self, peer: Did) {
+        let now_ms = get_epoch_ms_i64();
         let should_record = match self.measured_disconnects.lock() {
-            Ok(mut measured) => measured.insert(peer),
+            Ok(mut measured) => measured.insert(peer, now_ms).is_none(),
             Err(_) => {
                 tracing::warn!("Failed to update disconnect epoch for disconnected peer {peer}");
                 true
@@ -549,6 +550,14 @@ impl SwarmTransport {
         }
     }
 
+    /// Return the first time this peer left the usable connection epoch.
+    pub(crate) fn peer_disconnected_since_ms(&self, peer: Did) -> Option {
+        self.measured_disconnects
+            .lock()
+            .ok()
+            .and_then(|measured| measured.get(&peer).copied())
+    }
+
     /// Record that a payload from `peer` was accepted and verified by the swarm.
     pub(crate) async fn record_peer_message_received(&self, peer: Did) {
         self.record_peer_measurement(peer, MeasureCounter::Received)
@@ -973,6 +982,11 @@ impl SwarmTransport {
             .collect()
     }
 
+    /// Return admitted DIDs, even if their raw transport object has already gone away.
+    pub(crate) fn admitted_connection_ids(&self) -> Vec {
+        self.active_peer_ids()
+    }
+
     /// Get DIDs of active, routable connections.
     pub fn get_connection_ids(&self) -> Vec {
         self.get_connections()
@@ -1008,10 +1022,21 @@ impl SwarmTransport {
 
         tracing::info!("removing {peer} from DHT");
         self.dht.remove(peer)?;
-        self.transport
-            .close_connection(&peer.to_string())
-            .await
-            .map_err(|e| e.into())
+        self.close_connection_for_disconnect(peer).await
+    }
+
+    async fn close_connection_for_disconnect(&self, peer: Did) -> Result<()> {
+        match self.transport.close_connection(&peer.to_string()).await {
+            Ok(()) => Ok(()),
+            Err(rings_transport::error::Error::ConnectionNotFound(_)) => {
+                tracing::warn!(
+                    peer = %peer,
+                    "connection was already absent while disconnecting admitted peer"
+                );
+                Ok(())
+            }
+            Err(error) => Err(error.into()),
+        }
     }
 
     /// Connect a given Did. If the did is already connected, return Err,
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index 1d4c4a89f..6baeed548 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -52,8 +52,19 @@ impl Measure for RecordingMeasure {
         }
     }
 
-    async fn get_count(&self, _did: Did, _counter: MeasureCounter) -> u64 {
-        0
+    async fn get_count(&self, did: Did, counter: MeasureCounter) -> u64 {
+        match self.counters.lock() {
+            Ok(counters) => counters
+                .iter()
+                .filter(|(observed_did, observed_counter)| {
+                    *observed_did == did && *observed_counter == counter
+                })
+                .count() as u64,
+            Err(_) => {
+                tracing::error!("RecordingMeasure counters mutex is poisoned");
+                0
+            }
+        }
     }
 }
 
@@ -326,8 +337,11 @@ async fn disconnected_observation_is_once_per_connection_epoch() -> Result<()> {
 
     transport.record_peer_disconnected(peer).await;
     transport.record_peer_disconnected(peer).await;
+    assert!(transport.peer_disconnected_since_ms(peer).is_some());
     transport.record_peer_connected(peer).await;
+    assert!(transport.peer_disconnected_since_ms(peer).is_none());
     transport.record_peer_disconnected(peer).await;
+    assert!(transport.peer_disconnected_since_ms(peer).is_some());
 
     assert_eq!(
         measure.snapshot_counters()?.as_slice(),
diff --git a/crates/core/src/tests/default/test_stabilization.rs b/crates/core/src/tests/default/test_stabilization.rs
index 255f05698..43bb15b69 100644
--- a/crates/core/src/tests/default/test_stabilization.rs
+++ b/crates/core/src/tests/default/test_stabilization.rs
@@ -1,11 +1,24 @@
 use std::sync::Arc;
+use std::sync::Mutex;
+
+use async_trait::async_trait;
 
 use crate::dht::entry::Entry;
 use crate::dht::entry::EntryKind;
+use crate::dht::successor::SuccessorReader;
+use crate::dht::successor::SuccessorWriter;
+use crate::dht::Did;
 use crate::ecc::SecretKey;
 #[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 use crate::error::Error;
 use crate::error::Result;
+use crate::measure::BehaviourJudgement;
+use crate::measure::Measure;
+use crate::measure::MeasureCounter;
+use crate::measure::MeasureImpl;
+use crate::measure::PeerQuality;
+use crate::measure::PeerQualityEvidence;
+use crate::measure::PeerQualityThresholds;
 use crate::session::SessionSk;
 use crate::storage::MemStorage;
 use crate::swarm::SwarmBuilder;
@@ -21,6 +34,49 @@ use tokio::time::timeout;
 #[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 use tokio::time::Duration;
 
+#[derive(Default)]
+struct CountingMeasure {
+    counters: Mutex>,
+}
+
+#[async_trait]
+impl Measure for CountingMeasure {
+    async fn incr(&self, did: Did, counter: MeasureCounter) {
+        match self.counters.lock() {
+            Ok(mut counters) => counters.push((did, counter)),
+            Err(_) => tracing::error!("CountingMeasure counters mutex is poisoned"),
+        }
+    }
+
+    async fn get_count(&self, did: Did, counter: MeasureCounter) -> u64 {
+        match self.counters.lock() {
+            Ok(counters) => counters
+                .iter()
+                .filter(|(observed_did, observed_counter)| {
+                    *observed_did == did && *observed_counter == counter
+                })
+                .count() as u64,
+            Err(_) => {
+                tracing::error!("CountingMeasure counters mutex is poisoned");
+                0
+            }
+        }
+    }
+}
+
+#[async_trait]
+impl BehaviourJudgement for CountingMeasure {
+    async fn quality(&self, did: Did) -> PeerQuality {
+        PeerQualityEvidence::from_measure(self, did)
+            .await
+            .classify(PeerQualityThresholds::new(3, 10, 10))
+    }
+
+    async fn good(&self, did: Did) -> bool {
+        self.quality(did).await != PeerQuality::Degraded
+    }
+}
+
 #[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 struct PendingDataChannelWaitGuard;
 
@@ -39,6 +95,23 @@ impl Drop for PendingDataChannelWaitGuard {
     }
 }
 
+fn prepare_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result {
+    let session = SessionSk::new_with_seckey(&key)?;
+    let swarm = Arc::new(
+        SwarmBuilder::new(
+            0,
+            "stun://stun.l.google.com:19302",
+            Box::new(MemStorage::new()),
+            session,
+        )
+        .dht_finger_table_size(super::TEST_DHT_FINGER_TABLE_SIZE)
+        .dht_virtual_nodes(0)
+        .measure(measure)
+        .build(),
+    );
+    Ok(Node::new(swarm))
+}
+
 #[tokio::test]
 async fn test_stabilization_once() -> Result<()> {
     let mut key1 = SecretKey::random();
@@ -117,6 +190,84 @@ async fn stabilize_step_timeout_bounds_wedged_data_channel_wait() -> Result<()>
     Ok(())
 }
 
+#[tokio::test]
+async fn clean_unavailable_connections_removes_stale_topology_peer() -> Result<()> {
+    let node = prepare_node(SecretKey::random()).await;
+    let stale = SecretKey::random().address().into();
+
+    node.dht().successors().extend(&[stale])?;
+    *node.dht().lock_predecessor()? = Some(stale);
+    {
+        let dht = node.dht();
+        let mut finger = dht.lock_finger()?;
+        finger.set(0, stale);
+        finger.set(3, stale);
+    }
+
+    assert!(node.dht().successors().contains(&stale)?);
+    assert_eq!(*node.dht().lock_predecessor()?, Some(stale));
+    assert!(node.dht().lock_finger()?.contains(Some(stale)));
+    assert!(!node.swarm.transport.is_admitted_connection(stale));
+
+    node.swarm
+        .stabilizer()
+        .clean_unavailable_connections()
+        .await?;
+
+    assert!(!node.dht().successors().contains(&stale)?);
+    assert_eq!(*node.dht().lock_predecessor()?, None);
+    assert!(!node.dht().lock_finger()?.contains(Some(stale)));
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn clean_unavailable_connections_removes_degraded_admitted_peer() -> Result<()> {
+    let measure = Arc::new(CountingMeasure::default());
+    let measure_impl: MeasureImpl = measure.clone();
+    let node1 = prepare_node_with_measure(SecretKey::random(), measure_impl)?;
+    let node2 = prepare_node(SecretKey::random()).await;
+
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+    wait_for_successor(&node1, node2.did()).await?;
+
+    node1.dht().successors().extend(&[node2.did()])?;
+    *node1.dht().lock_predecessor()? = Some(node2.did());
+    {
+        let dht = node1.dht();
+        let mut finger = dht.lock_finger()?;
+        finger.set(0, node2.did());
+        finger.set(3, node2.did());
+    }
+
+    for _ in 0..10 {
+        node1
+            .swarm
+            .transport
+            .record_peer_message_send_failed(node2.did())
+            .await;
+    }
+    assert_eq!(
+        measure
+            .get_count(node2.did(), MeasureCounter::FailedToSend)
+            .await,
+        10
+    );
+
+    node1
+        .swarm
+        .stabilizer()
+        .clean_unavailable_connections()
+        .await?;
+
+    assert!(node1.swarm.transport.get_connection(node2.did()).is_none());
+    assert!(!node1.dht().successors().contains(&node2.did())?);
+    assert_eq!(*node1.dht().lock_predecessor()?, None);
+    assert!(!node1.dht().lock_finger()?.contains(Some(node2.did())));
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn stabilize_republishes_local_entries_to_missing_affine_owners() -> Result<()> {
     let key = SecretKey::random();

From a67741c350d8f7574120f2e1dea46acab7cb66d5 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Wed, 22 Jul 2026 05:10:07 +0800
Subject: [PATCH 06/23] Document DHT cleanup invariant

---
 crates/core/src/dht/stabilization.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index 7c5505c81..609677c59 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -320,6 +320,20 @@ impl Stabilizer {
     }
 
     /// Clean unavailable connections in transport.
+    ///
+    /// State relation:
+    /// - `TopologyPeer(n, p)` iff `p` appears in `n`'s successor list,
+    ///   predecessor slot, or finger table.
+    /// - `Routable(n, p)` iff `p` has an admitted local transport whose raw
+    ///   connection object is non-terminal.
+    /// - `Evictable(n, p)` iff `p` has no admitted transport, has no raw
+    ///   connection object, is terminal, stayed disconnected past grace, or has
+    ///   reached the local failure-evidence limit.
+    ///
+    /// Post: after this step returns `Ok`, every observed local
+    /// `TopologyPeer(n, p) ∪ AdmittedPeer(n, p)` that was `Evictable(n, p)` at
+    /// the step's snapshot time has been removed through `PeerRing::remove`, so
+    /// successor, predecessor, and finger state are cleaned together.
     pub async fn clean_unavailable_connections(&self) -> Result<()> {
         self.transport.expire_pending_connections().await?;
         let admitted_states = self.admitted_connection_states();

From 79b7f36ff58d30f200df64218f0ec8c929a02a47 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:14:00 +0800
Subject: [PATCH 07/23] Fix webview gateway review issues

---
 crates/core/src/chunk.rs                      | 617 +----------------
 crates/core/src/chunk/test.rs                 | 614 +++++++++++++++++
 crates/core/src/dht/entry.rs                  | 565 +--------------
 crates/core/src/dht/entry/tests.rs            | 560 +++++++++++++++
 crates/core/src/dht/stabilization.rs          |   8 +-
 .../core/src/message/handlers/connection.rs   |  27 +-
 .../src/message/handlers/stabilization.rs     |  87 ++-
 crates/core/src/swarm/transport.rs            | 650 +-----------------
 crates/core/src/swarm/transport/delivery.rs   | 155 +++++
 crates/core/src/swarm/transport/pending.rs    | 292 ++++++++
 .../src/swarm/transport/storage_lookup.rs     | 231 +++++++
 crates/core/src/swarm/transport/tests.rs      |  13 +-
 .../src/tests/default/test_dht_stateright.rs  | 594 +---------------
 .../test_dht_stateright/storage_model.rs      | 597 ++++++++++++++++
 .../src/tests/default/test_stabilization.rs   |  12 +-
 crates/core/src/utils.rs                      |   5 +-
 crates/node/src/logging.rs                    |   7 +-
 crates/node/src/processor/builder.rs          |   4 +-
 crates/node/src/processor/config.rs           |   4 +-
 .../node/src/processor/tests/test_config.rs   |   8 +-
 crates/webview/src/browser.rs                 | 338 +--------
 crates/webview/src/browser/tests.rs           | 335 +++++++++
 crates/webview/src/cors.rs                    |   3 +-
 crates/webview/src/error.rs                   |  59 ++
 crates/webview/src/lib.rs                     |   4 +-
 crates/webview/src/render.rs                  |   3 +-
 crates/webview/src/transport.rs               |   6 +-
 crates/webview/tests/browser_gateway.rs       | 287 +-------
 .../tests/browser_gateway/fixture_server.rs   | 286 ++++++++
 frontend/src/extension.rs                     |   8 +-
 frontend/src/onion.rs                         | 115 +++-
 frontend/src/webview.rs                       | 256 ++-----
 frontend/src/webview/tests.rs                 | 189 +++++
 frontend/src/workbench.rs                     |   8 +-
 34 files changed, 3631 insertions(+), 3316 deletions(-)
 create mode 100644 crates/core/src/chunk/test.rs
 create mode 100644 crates/core/src/dht/entry/tests.rs
 create mode 100644 crates/core/src/swarm/transport/delivery.rs
 create mode 100644 crates/core/src/swarm/transport/pending.rs
 create mode 100644 crates/core/src/swarm/transport/storage_lookup.rs
 create mode 100644 crates/core/src/tests/default/test_dht_stateright/storage_model.rs
 create mode 100644 crates/webview/src/browser/tests.rs
 create mode 100644 crates/webview/tests/browser_gateway/fixture_server.rs
 create mode 100644 frontend/src/webview/tests.rs

diff --git a/crates/core/src/chunk.rs b/crates/core/src/chunk.rs
index bdad7a3a1..cdf59f258 100644
--- a/crates/core/src/chunk.rs
+++ b/crates/core/src/chunk.rs
@@ -686,619 +686,4 @@ enum Rejected {
 }
 
 #[cfg(test)]
-mod test {
-    use super::*;
-
-    fn chunks_of(data: &Bytes, mtu: usize) -> Vec {
-        ChunkList::split(data, mtu).into()
-    }
-
-    /// Tiny limits so the admission rule can be exercised without giant synthetic payloads.
-    fn small_limits() -> ReassemblyLimits {
-        ReassemblyLimits {
-            max_pending_messages: 4,
-            max_chunk_data_len: 16,
-            max_message_bytes: 100,
-            max_chunks_per_message: 64,
-            max_total_buffered_cost: 256,
-            slot_overhead: 8,
-            max_completed_ids: 8,
-        }
-    }
-
-    #[test]
-    fn constrained_reassembly_limits_are_smaller_than_production() {
-        let production = ReassemblyLimits::production();
-        let constrained = ReassemblyLimits::constrained();
-
-        assert!(constrained.max_pending_messages < production.max_pending_messages);
-        assert!(constrained.max_message_bytes < production.max_message_bytes);
-        assert!(constrained.max_chunks_per_message < production.max_chunks_per_message);
-        assert!(constrained.max_total_buffered_cost < production.max_total_buffered_cost);
-        assert!(constrained.max_completed_ids < production.max_completed_ids);
-        assert_eq!(
-            constrained.max_chunk_data_len,
-            production.max_chunk_data_len
-        );
-    }
-
-    #[test]
-    fn test_data_chunks() {
-        let data = "helloworld".repeat(2).into();
-        let ret: Vec = ChunkList::split(&data, 32).into();
-        assert_eq!(ret.len(), 1);
-        assert_eq!(ret[ret.len() - 1].chunk, [0, 1]);
-
-        let data = "helloworld".repeat(1024).into();
-        let ret: Vec = ChunkList::split(&data, 32).into();
-        assert_eq!(ret.len(), 10 * 1024 / 32);
-        assert_eq!(ret[ret.len() - 1].chunk, [319, 320]);
-    }
-
-    #[test]
-    fn split_empty_yields_no_chunks() {
-        assert!(ChunkList::split(&Bytes::new(), 32).to_vec().is_empty());
-    }
-
-    #[test]
-    fn split_exact_multiple_all_full() {
-        let data: Bytes = vec![0u8; 64].into();
-        let chunks = ChunkList::split(&data, 32).to_vec();
-        assert_eq!(chunks.len(), 2);
-        assert!(chunks.iter().all(|c| c.data.len() == 32));
-        assert_eq!(chunks[0].chunk, [0, 2]);
-        assert_eq!(chunks[1].chunk, [1, 2]);
-    }
-
-    #[test]
-    fn split_non_multiple_last_is_remainder() {
-        let data: Bytes = vec![0u8; 70].into();
-        let chunks = ChunkList::split(&data, 32).to_vec();
-        assert_eq!(chunks.len(), 3);
-        assert_eq!(chunks[0].data.len(), 32);
-        assert_eq!(chunks[1].data.len(), 32);
-        assert_eq!(chunks[2].data.len(), 6);
-    }
-
-    #[test]
-    fn split_larger_than_data_is_single_chunk() {
-        let data: Bytes = vec![0u8; 10].into();
-        let chunks = ChunkList::split(&data, 1024).to_vec();
-        assert_eq!(chunks.len(), 1);
-        assert_eq!(chunks[0].chunk, [0, 1]);
-    }
-
-    #[test]
-    fn split_zero_size_is_clamped_to_one() {
-        let data: Bytes = vec![0u8; 4].into();
-        let chunks = ChunkList::split(&data, 0).to_vec();
-        assert_eq!(chunks.len(), 4);
-        assert!(chunks.iter().all(|c| c.data.len() == 1));
-    }
-
-    #[test]
-    fn split_chunks_share_one_message_id() {
-        let data: Bytes = vec![0u8; 100].into();
-        let chunks = ChunkList::split(&data, 32).to_vec();
-        let id = chunks[0].meta.id;
-        assert!(chunks.iter().all(|c| c.meta.id == id));
-    }
-
-    /// Cutting at any size and feeding the pieces back through the reassembler (in order) yields the
-    /// original bytes — across exact multiples, remainders, single-chunk, and one-byte cuts.
-    #[test]
-    fn split_then_reassemble_round_trips() {
-        for (len, size) in [
-            (1usize, 7usize),
-            (7, 7),
-            (8, 7),
-            (100, 7),
-            (1000, 64),
-            (5, 1),
-        ] {
-            let data: Bytes = (0..len).map(|i| i as u8).collect::>().into();
-            let mut r = MessageReassembler::new();
-            let mut out = None;
-            for c in ChunkList::split(&data, size) {
-                out = r.handle(c).or(out);
-            }
-            assert_eq!(out.unwrap(), data, "len={len} size={size}");
-        }
-    }
-
-    /// Test reserves with readable, distinct values (`whole < chunk`) so the two paths are easy to
-    /// tell apart in the assertions below.
-    fn reserves(whole: usize, chunk: usize, min_chunk_data: usize) -> WireReserves {
-        WireReserves {
-            whole,
-            chunk,
-            min_chunk_data,
-        }
-    }
-
-    #[test]
-    fn plan_whole_includes_whole_overhead() {
-        let r = reserves(10, 20, 1);
-        // Whole fits while payload + whole ≤ limit, up to and including the boundary.
-        assert_eq!(r.plan(0, 100), Some(Framing::Whole));
-        assert_eq!(r.plan(90, 100), Some(Framing::Whole));
-        // One past the boundary must chunk.
-        assert_eq!(r.plan(91, 100), Some(Framing::Chunked { chunk_size: 80 }));
-    }
-
-    /// The chunk size reserves the chunk overhead, so `chunk_size + chunk ≤ limit`: a wrapped chunk
-    /// can never exceed the negotiated limit.
-    #[test]
-    fn plan_chunk_size_reserves_overhead() {
-        let (limit, chunk_overhead) = (65536usize, 4096usize);
-        let Some(Framing::Chunked { chunk_size }) =
-            reserves(16, chunk_overhead, 16).plan(limit * 2, limit)
-        else {
-            panic!("expected chunked");
-        };
-        assert_eq!(chunk_size, limit - chunk_overhead);
-        assert!(chunk_size + chunk_overhead <= limit);
-    }
-
-    #[test]
-    fn plan_none_when_chunk_too_small() {
-        // A limit that cannot fit `chunk + min_chunk_data` is rejected outright, not split tiny.
-        assert_eq!(reserves(4, 10, 1).plan(100, 5), None); // below the overhead
-        assert_eq!(reserves(4, 10, 1).plan(100, 10), None); // == overhead, 0 data bytes
-                                                            // limit just clears chunk + min: the smallest *allowed* cut.
-        assert_eq!(
-            reserves(4, 10, 1).plan(100, 11),
-            Some(Framing::Chunked { chunk_size: 1 })
-        );
-        // a realistic floor: min_chunk_data = 8 needs limit ≥ chunk + 8.
-        assert_eq!(reserves(4, 10, 8).plan(100, 17), None); // 17 < 10 + 8
-        assert_eq!(
-            reserves(4, 10, 8).plan(100, 18),
-            Some(Framing::Chunked { chunk_size: 8 })
-        );
-    }
-
-    #[test]
-    fn plan_is_total_on_overflow() {
-        // `payload_len + whole` overflows usize; must not panic, and (not a whole fit) falls through
-        // to the chunked decision rather than wrapping around.
-        assert_eq!(
-            reserves(10, 20, 1).plan(usize::MAX, 100),
-            Some(Framing::Chunked { chunk_size: 80 })
-        );
-        // overflow with a too-small limit still yields None, not a panic.
-        assert_eq!(reserves(10, 20, 1).plan(usize::MAX, 10), None);
-    }
-
-    #[test]
-    fn reassembles_in_order() {
-        let data: Bytes = "helloworld".repeat(1024).into();
-        let mut r = MessageReassembler::new();
-        let chunks = chunks_of(&data, 32);
-        let mut out = None;
-        for c in chunks {
-            out = r.handle(c).or(out);
-        }
-        assert_eq!(out.unwrap(), data);
-        assert_eq!(r.pending_count(), 0, "completed message is forgotten");
-    }
-
-    #[test]
-    fn reassembles_out_of_order() {
-        let data: Bytes = "helloworld".repeat(64).into();
-        let mut chunks = chunks_of(&data, 32);
-        chunks.reverse();
-        let mut r = MessageReassembler::new();
-        let mut out = None;
-        for c in chunks {
-            out = r.handle(c).or(out);
-        }
-        assert_eq!(out.unwrap(), data);
-    }
-
-    #[test]
-    fn full_retransmit_after_completion_is_not_redelivered() {
-        // A message that completes, then is *fully* retransmitted within its TTL window, must not be
-        // delivered a second time — the completed id is tombstoned.
-        let data: Bytes = "helloworld".repeat(64).into();
-        let chunks = chunks_of(&data, 32);
-        assert!(chunks.len() > 1, "need a multi-chunk message for this test");
-
-        let mut r = MessageReassembler::new();
-        let mut first = None;
-        for c in chunks.clone() {
-            first = r.handle(c).or(first);
-        }
-        assert_eq!(first.unwrap(), data, "first assembly delivers once");
-        assert_eq!(r.pending_count(), 0);
-
-        // Replay every chunk of the same message; none should re-open a pending entry or re-deliver.
-        for c in chunks {
-            assert!(
-                r.handle(c).is_none(),
-                "a retransmit of an already-completed message must be dropped"
-            );
-        }
-        assert_eq!(
-            r.pending_count(),
-            0,
-            "no pending re-opened by the retransmit"
-        );
-    }
-
-    #[test]
-    fn duplicate_chunk_does_not_break_reassembly() {
-        // Regression: arrival order [0, 1, 0] used to dedup-before-sort and never complete.
-        let data: Bytes = "helloworld".repeat(8).into(); // > 32 bytes => 3 chunks
-        let chunks = chunks_of(&data, 32);
-        assert!(chunks.len() >= 2);
-        let mut r = MessageReassembler::new();
-
-        // Feed every chunk, re-feeding chunk 0 in the middle as a duplicate.
-        assert!(r.handle(chunks[0].clone()).is_none());
-        for c in &chunks[1..] {
-            let _ = r.handle(chunks[0].clone()); // duplicate of position 0, repeatedly
-            if let Some(out) = r.handle(c.clone()) {
-                assert_eq!(out, data);
-                assert_eq!(r.pending_count(), 0);
-                return;
-            }
-        }
-        panic!("message never completed despite all chunks arriving");
-    }
-
-    #[test]
-    fn interleaved_messages_are_isolated() {
-        let d1: Bytes = "hello".repeat(64).into();
-        let d2: Bytes = "world".repeat(64).into();
-        let c1 = chunks_of(&d1, 32);
-        let c2 = chunks_of(&d2, 32);
-        let mut r = MessageReassembler::new();
-
-        // interleave the two messages
-        let (mut o1, mut o2) = (None, None);
-        for pair in c1.iter().zip(c2.iter()) {
-            o1 = r.handle(pair.0.clone()).or(o1);
-            o2 = r.handle(pair.1.clone()).or(o2);
-        }
-        // drain any tail (lengths may differ)
-        for c in c1.iter().chain(c2.iter()) {
-            let out = r.handle(c.clone());
-            o1 = out.clone().filter(|b| *b == d1).or(o1);
-            o2 = out.filter(|b| *b == d2).or(o2);
-        }
-        assert_eq!(o1.unwrap(), d1);
-        assert_eq!(o2.unwrap(), d2);
-    }
-
-    #[test]
-    fn incomplete_message_stays_pending() {
-        let data: Bytes = "helloworld".repeat(64).into();
-        let chunks = chunks_of(&data, 32);
-        let mut r = MessageReassembler::new();
-        for c in &chunks[..chunks.len() - 1] {
-            assert!(r.handle(c.clone()).is_none());
-        }
-        assert_eq!(r.pending_count(), 1);
-        let out = r.handle(chunks.last().unwrap().clone());
-        assert_eq!(out.unwrap(), data);
-    }
-
-    #[test]
-    fn malformed_chunks_are_dropped() {
-        let mut r = MessageReassembler::new();
-        // total == 0
-        assert!(r
-            .handle(Chunk {
-                chunk: [0, 0],
-                data: Bytes::from_static(b"x"),
-                meta: ChunkMeta::default(),
-            })
-            .is_none());
-        // position >= total
-        assert!(r
-            .handle(Chunk {
-                chunk: [5, 3],
-                data: Bytes::from_static(b"x"),
-                meta: ChunkMeta::default(),
-            })
-            .is_none());
-        assert_eq!(r.pending_count(), 0);
-    }
-
-    #[test]
-    fn old_timestamp_is_dropped_without_panic() {
-        // ts_ms < TS_OFFSET_TOLERANCE_MS would underflow a plain `u128` subtraction (no panic with
-        // saturating arithmetic), and a chunk stamped at the epoch is already long expired — it must
-        // be dropped, not delivered, even though it is a complete `total == 1` message.
-        let mut r = MessageReassembler::new();
-        let out = r.handle(Chunk {
-            chunk: [0, 1],
-            data: Bytes::from_static(b"ok"),
-            meta: ChunkMeta {
-                id: Uuid::new_v4(),
-                ts_ms: 0,
-                ttl_ms: DEFAULT_TTL_MS,
-            },
-        });
-        assert!(out.is_none());
-        assert_eq!(r.pending_count(), 0);
-    }
-
-    #[test]
-    fn expired_single_chunk_is_not_delivered() {
-        // Regression: sweeping *other* pending entries before insertion let an already-expired
-        // `total == 1` chunk be delivered immediately. It must be rejected up front.
-        let mut r = MessageReassembler::new();
-        let now = get_epoch_ms();
-        let out = r.handle(Chunk {
-            chunk: [0, 1],
-            data: Bytes::from_static(b"x"),
-            meta: ChunkMeta {
-                id: Uuid::new_v4(),
-                ts_ms: now.saturating_sub(1000),
-                ttl_ms: 100, // expired 900ms ago
-            },
-        });
-        assert!(out.is_none());
-        assert_eq!(r.pending_count(), 0);
-    }
-
-    #[test]
-    fn oversize_chunk_data_is_rejected() {
-        let limits = small_limits();
-        let mut r = MessageReassembler::with_limits(limits);
-        let data: Bytes = vec![0u8; limits.max_chunk_data_len + 1].into();
-        let out = r.handle(Chunk {
-            chunk: [0, 1],
-            data,
-            meta: ChunkMeta::default(),
-        });
-        assert!(out.is_none());
-        assert_eq!(r.pending_count(), 0);
-        assert_eq!(r.buffered_cost, 0);
-    }
-
-    #[test]
-    fn buffered_cost_returns_to_zero_after_completion() {
-        let data: Bytes = "helloworld".repeat(100).into();
-        let mut r = MessageReassembler::new();
-        for c in ChunkList::split(&data, 32) {
-            r.handle(c);
-        }
-        assert_eq!(r.pending_count(), 0);
-        assert_eq!(r.buffered_cost, 0, "completing a message frees its budget");
-    }
-
-    /// A single id advertising a huge `total` and streaming distinct positions cannot grow without
-    /// bound: the per-message byte cap stops it.
-    #[test]
-    fn per_message_byte_cap_bounds_one_id() {
-        let limits = small_limits();
-        let mut r = MessageReassembler::with_limits(limits);
-        let meta = ChunkMeta::default();
-        let data: Bytes = vec![0u8; limits.max_chunk_data_len].into();
-        // Within the slot cap, but its data far exceeds the per-message byte cap so it never fills.
-        let total = limits.max_chunks_per_message;
-
-        let mut accepted = 0usize;
-        for position in 0..50 {
-            let before = r.pending.get(&meta.id).map(|p| p.slots.len()).unwrap_or(0);
-            r.handle(Chunk {
-                meta,
-                chunk: [position, total],
-                data: data.clone(),
-            });
-            let after = r.pending.get(&meta.id).map(|p| p.slots.len()).unwrap_or(0);
-            if after > before {
-                accepted += 1;
-            }
-        }
-
-        let pending = r.pending.get(&meta.id).expect("still pending");
-        assert!(
-            pending.data_bytes <= limits.max_message_bytes,
-            "per-message buffered data must stay within the cap"
-        );
-        assert!(
-            accepted < 50,
-            "the cap must reject some chunks, got {accepted}"
-        );
-        assert_eq!(
-            r.buffered_cost,
-            pending.cost(limits.slot_overhead),
-            "accounting stays exact"
-        );
-    }
-
-    /// Spreading the flood across many ids is bounded too: the global buffered-cost ceiling caps
-    /// total memory regardless of how many ids are used.
-    #[test]
-    fn global_cost_cap_bounds_total() {
-        let limits = small_limits();
-        let mut r = MessageReassembler::with_limits(limits);
-        // Each id contributes one slot of `max_chunk_data_len` data; keep them all pending.
-        for _ in 0..(limits.max_pending_messages * 4) {
-            r.handle(Chunk {
-                chunk: [0, 2],
-                data: vec![0u8; limits.max_chunk_data_len].into(),
-                meta: ChunkMeta::default(),
-            });
-        }
-        assert!(
-            r.buffered_cost <= limits.max_total_buffered_cost,
-            "global buffered cost {} exceeded cap {}",
-            r.buffered_cost,
-            limits.max_total_buffered_cost
-        );
-    }
-
-    #[test]
-    fn future_timestamp_is_dropped() {
-        let mut r = MessageReassembler::new();
-        let out = r.handle(Chunk {
-            chunk: [0, 1],
-            data: Bytes::from_static(b"x"),
-            meta: ChunkMeta {
-                id: Uuid::new_v4(),
-                ts_ms: get_epoch_ms() + 10 * TS_OFFSET_TOLERANCE_MS,
-                ttl_ms: DEFAULT_TTL_MS,
-            },
-        });
-        assert!(out.is_none());
-    }
-
-    #[test]
-    fn expired_partial_messages_are_evicted() {
-        let mut r = MessageReassembler::new();
-        let now = get_epoch_ms();
-        // a partial (1 of 2) message that is already expired
-        r.handle(Chunk {
-            chunk: [0, 2],
-            data: Bytes::from_static(b"x"),
-            meta: ChunkMeta {
-                id: Uuid::new_v4(),
-                ts_ms: now.saturating_sub(1000),
-                ttl_ms: 100,
-            },
-        });
-        // a fresh partial message triggers remove_expired, dropping the stale one
-        r.handle(Chunk {
-            chunk: [0, 2],
-            data: Bytes::from_static(b"y"),
-            meta: ChunkMeta {
-                id: Uuid::new_v4(),
-                ts_ms: now,
-                ttl_ms: DEFAULT_TTL_MS,
-            },
-        });
-        assert_eq!(r.pending_count(), 1, "only the fresh partial remains");
-    }
-
-    #[test]
-    fn pending_messages_are_capped() {
-        let limits = small_limits();
-        let mut r = MessageReassembler::with_limits(limits);
-        // each is the first of two chunks => stays pending
-        for _ in 0..(limits.max_pending_messages + 10) {
-            r.handle(Chunk {
-                chunk: [0, 2],
-                data: Bytes::from_static(b"x"),
-                meta: ChunkMeta::default(), // fresh id, fresh ts each time
-            });
-        }
-        assert_eq!(r.pending_count(), limits.max_pending_messages);
-    }
-
-    #[test]
-    fn round_trip_reordered_with_duplicates() {
-        let data: Bytes = "abcdefghij".repeat(500).into();
-        let mut chunks = chunks_of(&data, 64);
-        // reorder + inject duplicates mid-stream (not after the final chunk, which would just
-        // start a fresh, TTL-evicted pending entry — a late retransmit, not a reassembly bug).
-        chunks.reverse();
-        let dup = chunks[chunks.len() / 2].clone();
-        chunks.insert(1, dup.clone());
-        chunks.insert(chunks.len() / 3, dup);
-
-        let mut r = MessageReassembler::new();
-        let mut out = None;
-        for c in chunks {
-            out = r.handle(c).or(out);
-        }
-        assert_eq!(out.unwrap(), data);
-        assert_eq!(r.pending_count(), 0);
-    }
-
-    /// A forged `total` larger than the per-message slot cap is rejected before it can allocate a
-    /// huge slot map, even though each individual chunk's data is tiny.
-    #[test]
-    fn total_over_slot_cap_is_rejected() {
-        let limits = small_limits();
-        let mut r = MessageReassembler::with_limits(limits);
-        let out = r.handle(Chunk {
-            chunk: [0, limits.max_chunks_per_message + 1],
-            data: Bytes::from_static(b"x"),
-            meta: ChunkMeta::default(),
-        });
-        assert!(out.is_none());
-        assert_eq!(r.pending_count(), 0);
-        assert_eq!(r.buffered_cost, 0);
-    }
-
-    /// Two chunks sharing an id/total but from different transmissions (different `ts_ms`/`ttl_ms`)
-    /// must not be merged into one pending entry.
-    #[test]
-    fn mismatched_ts_or_ttl_for_same_id_is_rejected() {
-        let mut r = MessageReassembler::new();
-        let id = Uuid::new_v4();
-        let now = get_epoch_ms();
-        assert!(r
-            .handle(Chunk {
-                chunk: [0, 2],
-                data: Bytes::from_static(b"a"),
-                meta: ChunkMeta {
-                    id,
-                    ts_ms: now,
-                    ttl_ms: DEFAULT_TTL_MS
-                },
-            })
-            .is_none());
-        // Same id/total, different ts_ms → rejected (a chunk from another transmission).
-        let out = r.handle(Chunk {
-            chunk: [1, 2],
-            data: Bytes::from_static(b"b"),
-            meta: ChunkMeta {
-                id,
-                ts_ms: now + 1,
-                ttl_ms: DEFAULT_TTL_MS,
-            },
-        });
-        assert!(out.is_none(), "must not complete by mixing transmissions");
-        let p = r.pending.get(&id).expect("first chunk still pending");
-        assert_eq!(p.slots.len(), 1, "the mismatched chunk left no trace");
-    }
-
-    /// Once a completed message's TTL elapses, its tombstone is evicted by the real
-    /// `remove_expired_at` path (driven here by an injected clock, not by poking internal state),
-    /// and a fresh message reusing the same id is then accepted rather than suppressed.
-    #[test]
-    fn tombstone_expires_then_id_is_reusable() {
-        let mut r = MessageReassembler::new();
-        let id = Uuid::new_v4();
-        // A fixed base well above the future-skew tolerance, so timestamps are unambiguous.
-        let base = 1_000_000u128;
-        let ttl = 100u64;
-        let one_chunk = |label: &'static [u8], ts_ms: u128, ttl_ms: u64| Chunk {
-            chunk: [0, 1],
-            data: Bytes::from_static(label),
-            meta: ChunkMeta { id, ts_ms, ttl_ms },
-        };
-
-        // Complete a 1-chunk message at t = base; its tombstone expires at base + ttl.
-        let first = r.handle_at(one_chunk(b"first", base, ttl), base);
-        assert_eq!(first.as_deref(), Some(&b"first"[..]));
-        assert!(r.completed_ids.contains(&id), "tombstoned after completion");
-
-        // A full retransmit *within* the TTL window (t = base + ttl/2) is suppressed.
-        let dup = r.handle_at(one_chunk(b"first", base, ttl), base + (ttl as u128) / 2);
-        assert!(
-            dup.is_none(),
-            "post-completion retransmit suppressed within TTL"
-        );
-        assert!(
-            r.completed_ids.contains(&id),
-            "tombstone still live within TTL"
-        );
-
-        // Past the tombstone's expiry (t = base + ttl + 1), a brand-new message reusing the id is
-        // delivered: `remove_expired_at` evicts the now-expired tombstone before classify runs.
-        let later = base + ttl as u128 + 1;
-        let reused = r.handle_at(one_chunk(b"second", later, ttl), later);
-        assert_eq!(
-            reused.as_deref(),
-            Some(&b"second"[..]),
-            "id reusable after its tombstone expired via remove_expired_at"
-        );
-    }
-}
+mod test;
diff --git a/crates/core/src/chunk/test.rs b/crates/core/src/chunk/test.rs
new file mode 100644
index 000000000..ba6fef1d1
--- /dev/null
+++ b/crates/core/src/chunk/test.rs
@@ -0,0 +1,614 @@
+use super::*;
+
+fn chunks_of(data: &Bytes, mtu: usize) -> Vec {
+    ChunkList::split(data, mtu).into()
+}
+
+/// Tiny limits so the admission rule can be exercised without giant synthetic payloads.
+fn small_limits() -> ReassemblyLimits {
+    ReassemblyLimits {
+        max_pending_messages: 4,
+        max_chunk_data_len: 16,
+        max_message_bytes: 100,
+        max_chunks_per_message: 64,
+        max_total_buffered_cost: 256,
+        slot_overhead: 8,
+        max_completed_ids: 8,
+    }
+}
+
+#[test]
+fn constrained_reassembly_limits_are_smaller_than_production() {
+    let production = ReassemblyLimits::production();
+    let constrained = ReassemblyLimits::constrained();
+
+    assert!(constrained.max_pending_messages < production.max_pending_messages);
+    assert!(constrained.max_message_bytes < production.max_message_bytes);
+    assert!(constrained.max_chunks_per_message < production.max_chunks_per_message);
+    assert!(constrained.max_total_buffered_cost < production.max_total_buffered_cost);
+    assert!(constrained.max_completed_ids < production.max_completed_ids);
+    assert_eq!(
+        constrained.max_chunk_data_len,
+        production.max_chunk_data_len
+    );
+}
+
+#[test]
+fn test_data_chunks() {
+    let data = "helloworld".repeat(2).into();
+    let ret: Vec = ChunkList::split(&data, 32).into();
+    assert_eq!(ret.len(), 1);
+    assert_eq!(ret[ret.len() - 1].chunk, [0, 1]);
+
+    let data = "helloworld".repeat(1024).into();
+    let ret: Vec = ChunkList::split(&data, 32).into();
+    assert_eq!(ret.len(), 10 * 1024 / 32);
+    assert_eq!(ret[ret.len() - 1].chunk, [319, 320]);
+}
+
+#[test]
+fn split_empty_yields_no_chunks() {
+    assert!(ChunkList::split(&Bytes::new(), 32).to_vec().is_empty());
+}
+
+#[test]
+fn split_exact_multiple_all_full() {
+    let data: Bytes = vec![0u8; 64].into();
+    let chunks = ChunkList::split(&data, 32).to_vec();
+    assert_eq!(chunks.len(), 2);
+    assert!(chunks.iter().all(|c| c.data.len() == 32));
+    assert_eq!(chunks[0].chunk, [0, 2]);
+    assert_eq!(chunks[1].chunk, [1, 2]);
+}
+
+#[test]
+fn split_non_multiple_last_is_remainder() {
+    let data: Bytes = vec![0u8; 70].into();
+    let chunks = ChunkList::split(&data, 32).to_vec();
+    assert_eq!(chunks.len(), 3);
+    assert_eq!(chunks[0].data.len(), 32);
+    assert_eq!(chunks[1].data.len(), 32);
+    assert_eq!(chunks[2].data.len(), 6);
+}
+
+#[test]
+fn split_larger_than_data_is_single_chunk() {
+    let data: Bytes = vec![0u8; 10].into();
+    let chunks = ChunkList::split(&data, 1024).to_vec();
+    assert_eq!(chunks.len(), 1);
+    assert_eq!(chunks[0].chunk, [0, 1]);
+}
+
+#[test]
+fn split_zero_size_is_clamped_to_one() {
+    let data: Bytes = vec![0u8; 4].into();
+    let chunks = ChunkList::split(&data, 0).to_vec();
+    assert_eq!(chunks.len(), 4);
+    assert!(chunks.iter().all(|c| c.data.len() == 1));
+}
+
+#[test]
+fn split_chunks_share_one_message_id() {
+    let data: Bytes = vec![0u8; 100].into();
+    let chunks = ChunkList::split(&data, 32).to_vec();
+    let id = chunks[0].meta.id;
+    assert!(chunks.iter().all(|c| c.meta.id == id));
+}
+
+/// Cutting at any size and feeding the pieces back through the reassembler (in order) yields the
+/// original bytes — across exact multiples, remainders, single-chunk, and one-byte cuts.
+#[test]
+fn split_then_reassemble_round_trips() {
+    for (len, size) in [
+        (1usize, 7usize),
+        (7, 7),
+        (8, 7),
+        (100, 7),
+        (1000, 64),
+        (5, 1),
+    ] {
+        let data: Bytes = (0..len).map(|i| i as u8).collect::>().into();
+        let mut r = MessageReassembler::new();
+        let mut out = None;
+        for c in ChunkList::split(&data, size) {
+            out = r.handle(c).or(out);
+        }
+        assert_eq!(out.unwrap(), data, "len={len} size={size}");
+    }
+}
+
+/// Test reserves with readable, distinct values (`whole < chunk`) so the two paths are easy to
+/// tell apart in the assertions below.
+fn reserves(whole: usize, chunk: usize, min_chunk_data: usize) -> WireReserves {
+    WireReserves {
+        whole,
+        chunk,
+        min_chunk_data,
+    }
+}
+
+#[test]
+fn plan_whole_includes_whole_overhead() {
+    let r = reserves(10, 20, 1);
+    // Whole fits while payload + whole ≤ limit, up to and including the boundary.
+    assert_eq!(r.plan(0, 100), Some(Framing::Whole));
+    assert_eq!(r.plan(90, 100), Some(Framing::Whole));
+    // One past the boundary must chunk.
+    assert_eq!(r.plan(91, 100), Some(Framing::Chunked { chunk_size: 80 }));
+}
+
+/// The chunk size reserves the chunk overhead, so `chunk_size + chunk ≤ limit`: a wrapped chunk
+/// can never exceed the negotiated limit.
+#[test]
+fn plan_chunk_size_reserves_overhead() {
+    let (limit, chunk_overhead) = (65536usize, 4096usize);
+    let Some(Framing::Chunked { chunk_size }) =
+        reserves(16, chunk_overhead, 16).plan(limit * 2, limit)
+    else {
+        panic!("expected chunked");
+    };
+    assert_eq!(chunk_size, limit - chunk_overhead);
+    assert!(chunk_size + chunk_overhead <= limit);
+}
+
+#[test]
+fn plan_none_when_chunk_too_small() {
+    // A limit that cannot fit `chunk + min_chunk_data` is rejected outright, not split tiny.
+    assert_eq!(reserves(4, 10, 1).plan(100, 5), None); // below the overhead
+    assert_eq!(reserves(4, 10, 1).plan(100, 10), None); // == overhead, 0 data bytes
+                                                        // limit just clears chunk + min: the smallest *allowed* cut.
+    assert_eq!(
+        reserves(4, 10, 1).plan(100, 11),
+        Some(Framing::Chunked { chunk_size: 1 })
+    );
+    // a realistic floor: min_chunk_data = 8 needs limit ≥ chunk + 8.
+    assert_eq!(reserves(4, 10, 8).plan(100, 17), None); // 17 < 10 + 8
+    assert_eq!(
+        reserves(4, 10, 8).plan(100, 18),
+        Some(Framing::Chunked { chunk_size: 8 })
+    );
+}
+
+#[test]
+fn plan_is_total_on_overflow() {
+    // `payload_len + whole` overflows usize; must not panic, and (not a whole fit) falls through
+    // to the chunked decision rather than wrapping around.
+    assert_eq!(
+        reserves(10, 20, 1).plan(usize::MAX, 100),
+        Some(Framing::Chunked { chunk_size: 80 })
+    );
+    // overflow with a too-small limit still yields None, not a panic.
+    assert_eq!(reserves(10, 20, 1).plan(usize::MAX, 10), None);
+}
+
+#[test]
+fn reassembles_in_order() {
+    let data: Bytes = "helloworld".repeat(1024).into();
+    let mut r = MessageReassembler::new();
+    let chunks = chunks_of(&data, 32);
+    let mut out = None;
+    for c in chunks {
+        out = r.handle(c).or(out);
+    }
+    assert_eq!(out.unwrap(), data);
+    assert_eq!(r.pending_count(), 0, "completed message is forgotten");
+}
+
+#[test]
+fn reassembles_out_of_order() {
+    let data: Bytes = "helloworld".repeat(64).into();
+    let mut chunks = chunks_of(&data, 32);
+    chunks.reverse();
+    let mut r = MessageReassembler::new();
+    let mut out = None;
+    for c in chunks {
+        out = r.handle(c).or(out);
+    }
+    assert_eq!(out.unwrap(), data);
+}
+
+#[test]
+fn full_retransmit_after_completion_is_not_redelivered() {
+    // A message that completes, then is *fully* retransmitted within its TTL window, must not be
+    // delivered a second time — the completed id is tombstoned.
+    let data: Bytes = "helloworld".repeat(64).into();
+    let chunks = chunks_of(&data, 32);
+    assert!(chunks.len() > 1, "need a multi-chunk message for this test");
+
+    let mut r = MessageReassembler::new();
+    let mut first = None;
+    for c in chunks.clone() {
+        first = r.handle(c).or(first);
+    }
+    assert_eq!(first.unwrap(), data, "first assembly delivers once");
+    assert_eq!(r.pending_count(), 0);
+
+    // Replay every chunk of the same message; none should re-open a pending entry or re-deliver.
+    for c in chunks {
+        assert!(
+            r.handle(c).is_none(),
+            "a retransmit of an already-completed message must be dropped"
+        );
+    }
+    assert_eq!(
+        r.pending_count(),
+        0,
+        "no pending re-opened by the retransmit"
+    );
+}
+
+#[test]
+fn duplicate_chunk_does_not_break_reassembly() {
+    // Regression: arrival order [0, 1, 0] used to dedup-before-sort and never complete.
+    let data: Bytes = "helloworld".repeat(8).into(); // > 32 bytes => 3 chunks
+    let chunks = chunks_of(&data, 32);
+    assert!(chunks.len() >= 2);
+    let mut r = MessageReassembler::new();
+
+    // Feed every chunk, re-feeding chunk 0 in the middle as a duplicate.
+    assert!(r.handle(chunks[0].clone()).is_none());
+    for c in &chunks[1..] {
+        let _ = r.handle(chunks[0].clone()); // duplicate of position 0, repeatedly
+        if let Some(out) = r.handle(c.clone()) {
+            assert_eq!(out, data);
+            assert_eq!(r.pending_count(), 0);
+            return;
+        }
+    }
+    panic!("message never completed despite all chunks arriving");
+}
+
+#[test]
+fn interleaved_messages_are_isolated() {
+    let d1: Bytes = "hello".repeat(64).into();
+    let d2: Bytes = "world".repeat(64).into();
+    let c1 = chunks_of(&d1, 32);
+    let c2 = chunks_of(&d2, 32);
+    let mut r = MessageReassembler::new();
+
+    // interleave the two messages
+    let (mut o1, mut o2) = (None, None);
+    for pair in c1.iter().zip(c2.iter()) {
+        o1 = r.handle(pair.0.clone()).or(o1);
+        o2 = r.handle(pair.1.clone()).or(o2);
+    }
+    // drain any tail (lengths may differ)
+    for c in c1.iter().chain(c2.iter()) {
+        let out = r.handle(c.clone());
+        o1 = out.clone().filter(|b| *b == d1).or(o1);
+        o2 = out.filter(|b| *b == d2).or(o2);
+    }
+    assert_eq!(o1.unwrap(), d1);
+    assert_eq!(o2.unwrap(), d2);
+}
+
+#[test]
+fn incomplete_message_stays_pending() {
+    let data: Bytes = "helloworld".repeat(64).into();
+    let chunks = chunks_of(&data, 32);
+    let mut r = MessageReassembler::new();
+    for c in &chunks[..chunks.len() - 1] {
+        assert!(r.handle(c.clone()).is_none());
+    }
+    assert_eq!(r.pending_count(), 1);
+    let out = r.handle(chunks.last().unwrap().clone());
+    assert_eq!(out.unwrap(), data);
+}
+
+#[test]
+fn malformed_chunks_are_dropped() {
+    let mut r = MessageReassembler::new();
+    // total == 0
+    assert!(r
+        .handle(Chunk {
+            chunk: [0, 0],
+            data: Bytes::from_static(b"x"),
+            meta: ChunkMeta::default(),
+        })
+        .is_none());
+    // position >= total
+    assert!(r
+        .handle(Chunk {
+            chunk: [5, 3],
+            data: Bytes::from_static(b"x"),
+            meta: ChunkMeta::default(),
+        })
+        .is_none());
+    assert_eq!(r.pending_count(), 0);
+}
+
+#[test]
+fn old_timestamp_is_dropped_without_panic() {
+    // ts_ms < TS_OFFSET_TOLERANCE_MS would underflow a plain `u128` subtraction (no panic with
+    // saturating arithmetic), and a chunk stamped at the epoch is already long expired — it must
+    // be dropped, not delivered, even though it is a complete `total == 1` message.
+    let mut r = MessageReassembler::new();
+    let out = r.handle(Chunk {
+        chunk: [0, 1],
+        data: Bytes::from_static(b"ok"),
+        meta: ChunkMeta {
+            id: Uuid::new_v4(),
+            ts_ms: 0,
+            ttl_ms: DEFAULT_TTL_MS,
+        },
+    });
+    assert!(out.is_none());
+    assert_eq!(r.pending_count(), 0);
+}
+
+#[test]
+fn expired_single_chunk_is_not_delivered() {
+    // Regression: sweeping *other* pending entries before insertion let an already-expired
+    // `total == 1` chunk be delivered immediately. It must be rejected up front.
+    let mut r = MessageReassembler::new();
+    let now = get_epoch_ms();
+    let out = r.handle(Chunk {
+        chunk: [0, 1],
+        data: Bytes::from_static(b"x"),
+        meta: ChunkMeta {
+            id: Uuid::new_v4(),
+            ts_ms: now.saturating_sub(1000),
+            ttl_ms: 100, // expired 900ms ago
+        },
+    });
+    assert!(out.is_none());
+    assert_eq!(r.pending_count(), 0);
+}
+
+#[test]
+fn oversize_chunk_data_is_rejected() {
+    let limits = small_limits();
+    let mut r = MessageReassembler::with_limits(limits);
+    let data: Bytes = vec![0u8; limits.max_chunk_data_len + 1].into();
+    let out = r.handle(Chunk {
+        chunk: [0, 1],
+        data,
+        meta: ChunkMeta::default(),
+    });
+    assert!(out.is_none());
+    assert_eq!(r.pending_count(), 0);
+    assert_eq!(r.buffered_cost, 0);
+}
+
+#[test]
+fn buffered_cost_returns_to_zero_after_completion() {
+    let data: Bytes = "helloworld".repeat(100).into();
+    let mut r = MessageReassembler::new();
+    for c in ChunkList::split(&data, 32) {
+        r.handle(c);
+    }
+    assert_eq!(r.pending_count(), 0);
+    assert_eq!(r.buffered_cost, 0, "completing a message frees its budget");
+}
+
+/// A single id advertising a huge `total` and streaming distinct positions cannot grow without
+/// bound: the per-message byte cap stops it.
+#[test]
+fn per_message_byte_cap_bounds_one_id() {
+    let limits = small_limits();
+    let mut r = MessageReassembler::with_limits(limits);
+    let meta = ChunkMeta::default();
+    let data: Bytes = vec![0u8; limits.max_chunk_data_len].into();
+    // Within the slot cap, but its data far exceeds the per-message byte cap so it never fills.
+    let total = limits.max_chunks_per_message;
+
+    let mut accepted = 0usize;
+    for position in 0..50 {
+        let before = r.pending.get(&meta.id).map(|p| p.slots.len()).unwrap_or(0);
+        r.handle(Chunk {
+            meta,
+            chunk: [position, total],
+            data: data.clone(),
+        });
+        let after = r.pending.get(&meta.id).map(|p| p.slots.len()).unwrap_or(0);
+        if after > before {
+            accepted += 1;
+        }
+    }
+
+    let pending = r.pending.get(&meta.id).expect("still pending");
+    assert!(
+        pending.data_bytes <= limits.max_message_bytes,
+        "per-message buffered data must stay within the cap"
+    );
+    assert!(
+        accepted < 50,
+        "the cap must reject some chunks, got {accepted}"
+    );
+    assert_eq!(
+        r.buffered_cost,
+        pending.cost(limits.slot_overhead),
+        "accounting stays exact"
+    );
+}
+
+/// Spreading the flood across many ids is bounded too: the global buffered-cost ceiling caps
+/// total memory regardless of how many ids are used.
+#[test]
+fn global_cost_cap_bounds_total() {
+    let limits = small_limits();
+    let mut r = MessageReassembler::with_limits(limits);
+    // Each id contributes one slot of `max_chunk_data_len` data; keep them all pending.
+    for _ in 0..(limits.max_pending_messages * 4) {
+        r.handle(Chunk {
+            chunk: [0, 2],
+            data: vec![0u8; limits.max_chunk_data_len].into(),
+            meta: ChunkMeta::default(),
+        });
+    }
+    assert!(
+        r.buffered_cost <= limits.max_total_buffered_cost,
+        "global buffered cost {} exceeded cap {}",
+        r.buffered_cost,
+        limits.max_total_buffered_cost
+    );
+}
+
+#[test]
+fn future_timestamp_is_dropped() {
+    let mut r = MessageReassembler::new();
+    let out = r.handle(Chunk {
+        chunk: [0, 1],
+        data: Bytes::from_static(b"x"),
+        meta: ChunkMeta {
+            id: Uuid::new_v4(),
+            ts_ms: get_epoch_ms() + 10 * TS_OFFSET_TOLERANCE_MS,
+            ttl_ms: DEFAULT_TTL_MS,
+        },
+    });
+    assert!(out.is_none());
+}
+
+#[test]
+fn expired_partial_messages_are_evicted() {
+    let mut r = MessageReassembler::new();
+    let now = get_epoch_ms();
+    // a partial (1 of 2) message that is already expired
+    r.handle(Chunk {
+        chunk: [0, 2],
+        data: Bytes::from_static(b"x"),
+        meta: ChunkMeta {
+            id: Uuid::new_v4(),
+            ts_ms: now.saturating_sub(1000),
+            ttl_ms: 100,
+        },
+    });
+    // a fresh partial message triggers remove_expired, dropping the stale one
+    r.handle(Chunk {
+        chunk: [0, 2],
+        data: Bytes::from_static(b"y"),
+        meta: ChunkMeta {
+            id: Uuid::new_v4(),
+            ts_ms: now,
+            ttl_ms: DEFAULT_TTL_MS,
+        },
+    });
+    assert_eq!(r.pending_count(), 1, "only the fresh partial remains");
+}
+
+#[test]
+fn pending_messages_are_capped() {
+    let limits = small_limits();
+    let mut r = MessageReassembler::with_limits(limits);
+    // each is the first of two chunks => stays pending
+    for _ in 0..(limits.max_pending_messages + 10) {
+        r.handle(Chunk {
+            chunk: [0, 2],
+            data: Bytes::from_static(b"x"),
+            meta: ChunkMeta::default(), // fresh id, fresh ts each time
+        });
+    }
+    assert_eq!(r.pending_count(), limits.max_pending_messages);
+}
+
+#[test]
+fn round_trip_reordered_with_duplicates() {
+    let data: Bytes = "abcdefghij".repeat(500).into();
+    let mut chunks = chunks_of(&data, 64);
+    // reorder + inject duplicates mid-stream (not after the final chunk, which would just
+    // start a fresh, TTL-evicted pending entry — a late retransmit, not a reassembly bug).
+    chunks.reverse();
+    let dup = chunks[chunks.len() / 2].clone();
+    chunks.insert(1, dup.clone());
+    chunks.insert(chunks.len() / 3, dup);
+
+    let mut r = MessageReassembler::new();
+    let mut out = None;
+    for c in chunks {
+        out = r.handle(c).or(out);
+    }
+    assert_eq!(out.unwrap(), data);
+    assert_eq!(r.pending_count(), 0);
+}
+
+/// A forged `total` larger than the per-message slot cap is rejected before it can allocate a
+/// huge slot map, even though each individual chunk's data is tiny.
+#[test]
+fn total_over_slot_cap_is_rejected() {
+    let limits = small_limits();
+    let mut r = MessageReassembler::with_limits(limits);
+    let out = r.handle(Chunk {
+        chunk: [0, limits.max_chunks_per_message + 1],
+        data: Bytes::from_static(b"x"),
+        meta: ChunkMeta::default(),
+    });
+    assert!(out.is_none());
+    assert_eq!(r.pending_count(), 0);
+    assert_eq!(r.buffered_cost, 0);
+}
+
+/// Two chunks sharing an id/total but from different transmissions (different `ts_ms`/`ttl_ms`)
+/// must not be merged into one pending entry.
+#[test]
+fn mismatched_ts_or_ttl_for_same_id_is_rejected() {
+    let mut r = MessageReassembler::new();
+    let id = Uuid::new_v4();
+    let now = get_epoch_ms();
+    assert!(r
+        .handle(Chunk {
+            chunk: [0, 2],
+            data: Bytes::from_static(b"a"),
+            meta: ChunkMeta {
+                id,
+                ts_ms: now,
+                ttl_ms: DEFAULT_TTL_MS
+            },
+        })
+        .is_none());
+    // Same id/total, different ts_ms → rejected (a chunk from another transmission).
+    let out = r.handle(Chunk {
+        chunk: [1, 2],
+        data: Bytes::from_static(b"b"),
+        meta: ChunkMeta {
+            id,
+            ts_ms: now + 1,
+            ttl_ms: DEFAULT_TTL_MS,
+        },
+    });
+    assert!(out.is_none(), "must not complete by mixing transmissions");
+    let p = r.pending.get(&id).expect("first chunk still pending");
+    assert_eq!(p.slots.len(), 1, "the mismatched chunk left no trace");
+}
+
+/// Once a completed message's TTL elapses, its tombstone is evicted by the real
+/// `remove_expired_at` path (driven here by an injected clock, not by poking internal state),
+/// and a fresh message reusing the same id is then accepted rather than suppressed.
+#[test]
+fn tombstone_expires_then_id_is_reusable() {
+    let mut r = MessageReassembler::new();
+    let id = Uuid::new_v4();
+    // A fixed base well above the future-skew tolerance, so timestamps are unambiguous.
+    let base = 1_000_000u128;
+    let ttl = 100u64;
+    let one_chunk = |label: &'static [u8], ts_ms: u128, ttl_ms: u64| Chunk {
+        chunk: [0, 1],
+        data: Bytes::from_static(label),
+        meta: ChunkMeta { id, ts_ms, ttl_ms },
+    };
+
+    // Complete a 1-chunk message at t = base; its tombstone expires at base + ttl.
+    let first = r.handle_at(one_chunk(b"first", base, ttl), base);
+    assert_eq!(first.as_deref(), Some(&b"first"[..]));
+    assert!(r.completed_ids.contains(&id), "tombstoned after completion");
+
+    // A full retransmit *within* the TTL window (t = base + ttl/2) is suppressed.
+    let dup = r.handle_at(one_chunk(b"first", base, ttl), base + (ttl as u128) / 2);
+    assert!(
+        dup.is_none(),
+        "post-completion retransmit suppressed within TTL"
+    );
+    assert!(
+        r.completed_ids.contains(&id),
+        "tombstone still live within TTL"
+    );
+
+    // Past the tombstone's expiry (t = base + ttl + 1), a brand-new message reusing the id is
+    // delivered: `remove_expired_at` evicts the now-expired tombstone before classify runs.
+    let later = base + ttl as u128 + 1;
+    let reused = r.handle_at(one_chunk(b"second", later, ttl), later);
+    assert_eq!(
+        reused.as_deref(),
+        Some(&b"second"[..]),
+        "id reusable after its tombstone expired via remove_expired_at"
+    );
+}
diff --git a/crates/core/src/dht/entry.rs b/crates/core/src/dht/entry.rs
index 940040dd2..0d8242ff2 100644
--- a/crates/core/src/dht/entry.rs
+++ b/crates/core/src/dht/entry.rs
@@ -763,567 +763,4 @@ impl Entry {
 }
 
 #[cfg(test)]
-mod tests {
-    use num_bigint::BigUint;
-
-    use super::*;
-    use crate::algebra::assert_join_semilattice_laws;
-    use crate::algebra::assert_strong_eventual_consistency;
-    use crate::ecc::SecretKey;
-    use crate::message::Message;
-    use crate::session::SessionSk;
-
-    fn encoded(value: &str) -> Result {
-        value.to_string().encode()
-    }
-
-    fn data_entry(topic: &str, value: &str) -> Result {
-        (topic.to_string(), encoded(value)?).try_into()
-    }
-
-    fn data_entry_from_values(topic: &str, values: Vec) -> Result {
-        let data = values
-            .into_iter()
-            .map(|value| value.encode())
-            .collect::>>()?;
-        Ok(Entry::new(Entry::gen_did(topic)?, data, EntryKind::Data))
-    }
-
-    fn overflowing_data_entry(topic: &str, overflow: usize) -> Result<(Entry, usize)> {
-        let incoming_count = ENTRY_DATA_MAX_LEN + overflow;
-        let entry = data_entry_from_values(
-            topic,
-            (0..incoming_count)
-                .map(|i| format!("incoming{i}"))
-                .collect::>(),
-        )?;
-        Ok((entry, incoming_count))
-    }
-
-    fn decode_entry_data(entry: &Entry) -> Result> {
-        entry
-            .data
-            .iter()
-            .map(|item| item.decode())
-            .collect::>>()
-    }
-
-    fn assert_entry_keeps_recent_overflow(
-        entry: &Entry,
-        incoming_count: usize,
-        overflow: usize,
-    ) -> Result<()> {
-        assert_eq!(entry.data.len(), ENTRY_DATA_MAX_LEN);
-        let decoded = decode_entry_data(entry)?;
-        assert_eq!(decoded.first(), Some(&format!("incoming{overflow}")));
-        assert_eq!(
-            decoded.last(),
-            Some(&format!("incoming{}", incoming_count - 1))
-        );
-        Ok(())
-    }
-
-    fn subring_entry(name: &str) -> Result {
-        let creator = Entry::gen_did("creator")?;
-        Subring::new(name, creator)?.try_into()
-    }
-
-    fn actor() -> Did {
-        Did::from(42u32)
-    }
-
-    fn version(counter: u32) -> EntryVersion {
-        EntryVersion::new(
-            u128::from(counter),
-            Did::from(counter),
-            Did::from(counter.saturating_add(1000)),
-        )
-    }
-
-    fn data_delta(topic: &str, value: &str, counter: u32) -> Result {
-        data_entry(topic, value)?.stamp_delta(version(counter))
-    }
-
-    fn overwrite_delta(topic: &str, value: &str, counter: u32) -> Result {
-        data_entry(topic, value)?.stamp_overwrite(version(counter))
-    }
-
-    fn relay_delta(did: Did, value: &str, counter: u32) -> Result {
-        Entry::new(did, vec![encoded(value)?], EntryKind::RelayMessage)
-            .stamp_delta(version(counter))
-    }
-
-    #[test]
-    fn gset_satisfies_join_semilattice_laws() {
-        let mut a = GSet::new();
-        a.insert(Did::from(1u32));
-        let mut b = GSet::new();
-        b.insert(Did::from(2u32));
-        let mut ab = GSet::new();
-        ab.insert(Did::from(1u32));
-        ab.insert(Did::from(2u32));
-
-        assert_join_semilattice_laws(&[GSet::new(), a, b, ab]);
-    }
-
-    #[test]
-    fn data_topic_buffer_satisfies_join_semilattice_laws() -> Result<()> {
-        let carrier = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data)
-            .join(data_delta("topic", "a", 1)?)?
-            .join(data_delta("topic", "b", 2)?)?;
-        let tombstoned_a = carrier
-            .tombstone(data_delta("topic", "a", 1)?)?
-            .topic_buffer()?;
-        let samples = [
-            Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data).topic_buffer()?,
-            data_delta("topic", "a", 1)?.topic_buffer()?,
-            data_delta("topic", "b", 2)?.topic_buffer()?,
-            overwrite_delta("topic", "c", 3)?.topic_buffer()?,
-            tombstoned_a,
-        ];
-
-        assert_join_semilattice_laws(&samples);
-        Ok(())
-    }
-
-    #[test]
-    fn relay_message_set_satisfies_join_semilattice_laws() -> Result<()> {
-        let did = Did::from(10u32);
-        let a = Entry::new(did, vec![encoded("a")?], EntryKind::RelayMessage)
-            .stamp_delta(version(1))?
-            .relay_set()?;
-        let b = Entry::new(did, vec![encoded("b")?], EntryKind::RelayMessage)
-            .stamp_delta(version(2))?
-            .relay_set()?;
-        let ab = Entry::new(did, vec![], EntryKind::RelayMessage)
-            .join(relay_delta(did, "a", 1)?)?
-            .join(relay_delta(did, "b", 2)?)?;
-        let tombstoned_a = ab.tombstone(relay_delta(did, "a", 1)?)?.relay_set()?;
-
-        assert_join_semilattice_laws(&[RelayMessageSet::default(), a, b, tombstoned_a]);
-        Ok(())
-    }
-
-    #[test]
-    fn entry_join_is_strongly_eventually_consistent_for_data_deltas() -> Result<()> {
-        let base = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data);
-        let deltas = [
-            data_delta("topic", "a", 1)?,
-            data_delta("topic", "b", 2)?,
-            data_delta("topic", "a", 3)?,
-        ];
-
-        let forward = deltas
-            .iter()
-            .cloned()
-            .try_fold(base.clone(), |acc, delta| acc.join(delta))?;
-        let reverse = deltas
-            .iter()
-            .rev()
-            .cloned()
-            .try_fold(base.clone(), |acc, delta| acc.join(delta))?;
-        let duplicated = deltas
-            .iter()
-            .cloned()
-            .chain(deltas.iter().cloned())
-            .try_fold(base, |acc, delta| acc.join(delta))?;
-
-        assert_eq!(forward, reverse);
-        assert_eq!(forward, duplicated);
-        assert_eq!(decode_entry_data(&forward)?, vec![
-            String::from("b"),
-            String::from("a")
-        ]);
-        Ok(())
-    }
-
-    #[test]
-    fn generic_sec_witness_accepts_data_topic_buffer_deltas() -> Result<()> {
-        let base = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data).topic_buffer()?;
-        let deltas = vec![
-            data_delta("topic", "a", 1)?.topic_buffer()?,
-            data_delta("topic", "b", 2)?.topic_buffer()?,
-        ];
-
-        assert_strong_eventual_consistency(base, &deltas);
-        Ok(())
-    }
-
-    #[test]
-    fn storage_normalization_uses_lattice_top_n_order() -> Result<()> {
-        let incoming_count = ENTRY_DATA_MAX_LEN + 3;
-        let mut entry = data_entry_from_values(
-            "topic",
-            (0..incoming_count)
-                .map(|i| format!("incoming{i}"))
-                .collect::>(),
-        )?;
-        entry.crdt.dots = entry
-            .data
-            .iter()
-            .enumerate()
-            .map(|(index, _)| {
-                let counter = if index == 0 {
-                    10_000
-                } else {
-                    u32::try_from(index).map_err(|_| Error::EntryDotIndexOutOfBounds { index })?
-                };
-                EntryDot::for_index(version(counter), index)
-            })
-            .collect::>>()?;
-
-        let normalized = entry.try_into_storage_entry()?;
-        let decoded = decode_entry_data(&normalized)?;
-
-        assert_eq!(normalized.data.len(), ENTRY_DATA_MAX_LEN);
-        assert_eq!(normalized.data.len(), normalized.crdt.dots.len());
-        assert!(decoded.contains(&String::from("incoming0")));
-        assert!(!decoded.contains(&String::from("incoming1")));
-        assert!(!decoded.contains(&String::from("incoming2")));
-        assert!(!decoded.contains(&String::from("incoming3")));
-        Ok(())
-    }
-
-    #[test]
-    fn storage_normalization_realigns_legacy_mismatched_dots() -> Result<()> {
-        let mut entry = data_entry_from_values(
-            "topic",
-            (0..ENTRY_DATA_MAX_LEN + 2)
-                .map(|i| format!("legacy{i}"))
-                .collect::>(),
-        )?;
-        entry.crdt.dots = vec![EntryDot::for_index(version(10_000), 0)?];
-
-        let normalized = entry.try_into_storage_entry()?;
-
-        assert_eq!(normalized.data.len(), ENTRY_DATA_MAX_LEN);
-        assert_eq!(normalized.data.len(), normalized.crdt.dots.len());
-        Ok(())
-    }
-
-    #[test]
-    fn crdt_constructors_normalize_carrier_invariants() -> Result<()> {
-        let register = version(10);
-        let stale = encoded("stale")?;
-        let live = encoded("live")?;
-        let mut values = BTreeMap::new();
-        values.insert(stale.clone(), EntryDot::for_index(version(1), 0)?);
-        let live_dot = EntryDot::for_index(version(11), 0)?;
-        values.insert(live.clone(), live_dot);
-
-        let buffer = DataTopicBuffer::new(Some(register), values, BTreeSet::new());
-        assert_eq!(buffer.values.len(), 1);
-        assert!(buffer.values.contains_key(&live));
-
-        let relay = RelayMessageSet::new(buffer, BTreeSet::from([live_dot]));
-        assert!(relay.adds.values.is_empty());
-        assert!(relay.removes.contains(&live_dot));
-        Ok(())
-    }
-
-    #[test]
-    fn overwrite_register_tiebreaker_converges_for_same_timestamp_actor() -> Result<()> {
-        let did = Entry::gen_did("topic")?;
-        let issuer = actor();
-        let lower = Entry::new(did, vec![encoded("lower")?], EntryKind::Data)
-            .stamp_overwrite(EntryVersion::new(1, issuer, Did::from(1u32)))?;
-        let higher = Entry::new(did, vec![encoded("higher")?], EntryKind::Data)
-            .stamp_overwrite(EntryVersion::new(1, issuer, Did::from(2u32)))?;
-        let base = Entry::new(did, vec![], EntryKind::Data);
-
-        let forward = base.clone().join(lower.clone())?.join(higher.clone())?;
-        let reverse = base.join(higher)?.join(lower)?;
-
-        assert_eq!(forward, reverse);
-        assert_eq!(decode_entry_data(&forward)?, vec![String::from("higher")]);
-        Ok(())
-    }
-
-    #[test]
-    fn operation_digest_hashes_canonical_bytes_not_legacy_base58() -> Result<()> {
-        let entry = data_entry("topic", "value")?;
-        let digest = OperationDigest {
-            kind: entry.kind,
-            did: entry.did,
-            data: &entry.data,
-        };
-        let bytes = bincode::serialize(&digest).map_err(Error::BincodeSerialize)?;
-
-        let direct = Did::try_from(HashStr::from_bytes(&bytes))?;
-        let legacy_encoded = bytes.encode()?;
-        let legacy_base58 = Entry::gen_did(legacy_encoded.value())?;
-
-        assert_eq!(entry.operation_digest()?, direct);
-        assert_ne!(direct, legacy_base58);
-        Ok(())
-    }
-
-    #[test]
-    fn forwarded_overwrite_witness_is_not_reissued_after_local_floor() -> Result<()> {
-        let current = overwrite_delta("topic", "current", 10)?;
-        let stale_forwarded = overwrite_delta("topic", "stale", 1)?;
-
-        let updated = current.overwrite(stale_forwarded, actor())?;
-
-        assert_eq!(decode_entry_data(&updated)?, vec![String::from("current")]);
-        Ok(())
-    }
-
-    #[test]
-    fn overwrite_replaces_data_for_same_data_entry() -> Result<()> {
-        let entry = data_entry("topic", "old")?;
-        let other = data_entry("topic", "new")?;
-        let updated = entry.overwrite(other, actor())?;
-        assert_eq!(decode_entry_data(&updated)?, vec![String::from("new")]);
-        Ok(())
-    }
-
-    #[test]
-    fn overwrite_rejects_non_data_entry() -> Result<()> {
-        let entry = subring_entry("ring")?;
-        let other = entry.clone();
-
-        assert!(matches!(
-            entry.overwrite(other, actor()),
-            Err(Error::EntryNotOverwritable)
-        ));
-        Ok(())
-    }
-
-    #[test]
-    fn overwrite_rejects_kind_mismatch() -> Result<()> {
-        let entry = data_entry("topic", "old")?;
-        let mut other = entry.clone();
-        other.kind = EntryKind::RelayMessage;
-
-        assert!(matches!(
-            entry.overwrite(other, actor()),
-            Err(Error::EntryKindNotEqual)
-        ));
-        Ok(())
-    }
-
-    #[test]
-    fn overwrite_rejects_key_mismatch() -> Result<()> {
-        let entry = data_entry("topic-a", "old")?;
-        let other = data_entry("topic-b", "new")?;
-
-        assert!(matches!(
-            entry.overwrite(other, actor()),
-            Err(Error::EntryDidNotEqual)
-        ));
-        Ok(())
-    }
-
-    #[test]
-    fn overwrite_caps_payloads_larger_than_max_len() -> Result<()> {
-        let overflow = 3;
-        let (incoming, incoming_count) = overflowing_data_entry("topic", overflow)?;
-        let entry = data_entry("topic", "base")?;
-        let updated = entry.overwrite(incoming, actor())?;
-        assert_entry_keeps_recent_overflow(&updated, incoming_count, overflow)
-    }
-
-    #[test]
-    fn extend_appends_data_for_same_entry() -> Result<()> {
-        let entry = data_entry("topic", "first")?;
-        let other = data_entry("topic", "second")?;
-        let updated = entry.extend(other, actor())?;
-        assert_eq!(decode_entry_data(&updated)?, vec![
-            String::from("first"),
-            String::from("second")
-        ]);
-        Ok(())
-    }
-
-    #[test]
-    fn extend_trims_oldest_items_at_max_len() -> Result<()> {
-        let mut entry = data_entry("topic", "test0")?;
-        for i in 1..ENTRY_DATA_MAX_LEN {
-            let data = format!("test{i}");
-            let other = data_entry("topic", &data)?;
-            entry = entry.extend(other, actor())?;
-            assert_eq!(entry.data.len(), i + 1);
-        }
-
-        for i in ENTRY_DATA_MAX_LEN..ENTRY_DATA_MAX_LEN + 10 {
-            let data = format!("test{i}");
-            let other = data_entry("topic", &data)?;
-            entry = entry.extend(other, actor())?;
-            assert_eq!(entry.data.len(), ENTRY_DATA_MAX_LEN);
-            let decoded = decode_entry_data(&entry)?;
-            assert_eq!(
-                decoded.first(),
-                Some(&format!("test{}", i - ENTRY_DATA_MAX_LEN + 1))
-            );
-            assert_eq!(decoded.last(), Some(&data));
-        }
-        Ok(())
-    }
-
-    #[test]
-    fn extend_caps_incoming_payloads_larger_than_max_len() -> Result<()> {
-        let overflow = 3;
-        let (incoming, incoming_count) = overflowing_data_entry("topic", overflow)?;
-        let entry = data_entry("topic", "base")?;
-        let updated = entry.extend(incoming, actor())?;
-        assert_entry_keeps_recent_overflow(&updated, incoming_count, overflow)
-    }
-
-    #[test]
-    fn extend_rejects_non_data_entry() -> Result<()> {
-        let entry = subring_entry("ring")?;
-        let other = entry.clone();
-
-        assert!(matches!(
-            entry.extend(other, actor()),
-            Err(Error::EntryNotAppendable)
-        ));
-        Ok(())
-    }
-
-    #[test]
-    fn touch_moves_existing_items_to_end_once() -> Result<()> {
-        let entry = data_entry("topic", "a")?
-            .extend(data_entry("topic", "b")?, actor())?
-            .extend(data_entry("topic", "c")?, actor())?;
-        let touched = data_entry("topic", "b")?;
-        let updated = entry.touch(touched, actor())?;
-        assert_eq!(decode_entry_data(&updated)?, vec![
-            String::from("a"),
-            String::from("c"),
-            String::from("b")
-        ]);
-        Ok(())
-    }
-
-    #[test]
-    fn touch_trims_oldest_non_touched_items_at_max_len() -> Result<()> {
-        let mut entry = data_entry("topic", "test0")?;
-        for i in 1..ENTRY_DATA_MAX_LEN {
-            entry = entry.extend(data_entry("topic", &format!("test{i}"))?, actor())?;
-        }
-        let updated = entry.touch(data_entry("topic", "test0")?, actor())?;
-        assert_eq!(updated.data.len(), ENTRY_DATA_MAX_LEN);
-        let decoded = decode_entry_data(&updated)?;
-        assert_eq!(decoded.first(), Some(&String::from("test1")));
-        assert_eq!(decoded.last(), Some(&String::from("test0")));
-        Ok(())
-    }
-
-    #[test]
-    fn relay_tombstone_removes_observed_message_by_join() -> Result<()> {
-        let did = Did::from(30u32);
-        let first = relay_delta(did, "first", 1)?;
-        let second = relay_delta(did, "second", 2)?;
-        let carrier = Entry::new(did, vec![], EntryKind::RelayMessage)
-            .join(first.clone())?
-            .join(second.clone())?;
-
-        let removed = carrier.tombstone(first.clone())?;
-
-        assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
-        let joined_with_stale_add = removed.join(first)?;
-        assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
-            String::from("second")
-        ]);
-        Ok(())
-    }
-
-    #[test]
-    fn data_tombstone_removes_observed_payload_by_join() -> Result<()> {
-        let first = data_delta("topic", "first", 1)?;
-        let second = data_delta("topic", "second", 2)?;
-        let carrier = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data)
-            .join(first.clone())?
-            .join(second.clone())?;
-
-        let removed = carrier.tombstone(first.clone())?;
-
-        assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
-        let joined_with_stale_add = removed.join(first)?;
-        assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
-            String::from("second")
-        ]);
-        Ok(())
-    }
-
-    #[test]
-    fn tombstone_rejects_non_data_or_relay_entry() -> Result<()> {
-        let entry = subring_entry("ring")?;
-        let other = entry.clone();
-
-        assert!(matches!(
-            entry.tombstone(other),
-            Err(Error::EntryNotTombstonable)
-        ));
-        Ok(())
-    }
-
-    #[test]
-    fn touch_caps_incoming_payloads_larger_than_max_len() -> Result<()> {
-        let overflow = 3;
-        let (incoming, incoming_count) = overflowing_data_entry("topic", overflow)?;
-        let entry = data_entry("topic", "base")?;
-        let updated = entry.touch(incoming, actor())?;
-        assert_entry_keeps_recent_overflow(&updated, incoming_count, overflow)
-    }
-
-    #[test]
-    fn join_subring_adds_member_to_subring_entry() -> Result<()> {
-        let entry = subring_entry("ring")?;
-        let member = Entry::gen_did("member")?;
-        let updated = entry.join_subring(member)?;
-        let subring = Subring::try_from(updated)?;
-        assert_eq!(subring.finger.first(), Some(member));
-        Ok(())
-    }
-
-    #[test]
-    fn join_subring_rejects_non_subring_entry() -> Result<()> {
-        let entry = data_entry("topic", "value")?;
-        let member = Entry::gen_did("member")?;
-
-        assert!(matches!(
-            entry.join_subring(member),
-            Err(Error::EntryNotJoinable)
-        ));
-        Ok(())
-    }
-
-    #[test]
-    fn operation_default_entry_matches_operation_kind() -> Result<()> {
-        let target = data_entry("topic", "value")?;
-        let default = EntryOperation::Extend(target.clone()).gen_default_entry()?;
-        assert_eq!(default.did, target.did);
-        assert_eq!(default.kind, EntryKind::Data);
-        assert!(default.data.is_empty());
-        Ok(())
-    }
-
-    #[test]
-    fn message_payload_entry_key_targets_successor_of_signer() -> Result<()> {
-        let key = SecretKey::random();
-        let session = SessionSk::new_with_seckey(&key)?;
-        let signer: Did = key.address().into();
-        let payload =
-            MessagePayload::new_send(Message::custom(b"relay")?, &session, signer, signer)?;
-        let entry = Entry::try_from(payload)?;
-        let expected = BigUint::from(signer) + BigUint::from(1u16);
-        assert_eq!(entry.did, expected.into());
-        assert_eq!(entry.kind, EntryKind::RelayMessage);
-        Ok(())
-    }
-
-    #[test]
-    fn affine_preserves_payload_and_kind_while_rotating_keys() -> Result<()> {
-        let entry = data_entry("topic", "value")?;
-        let affined = entry.affine(3)?;
-        assert_eq!(affined.len(), 3);
-        for rotated in affined {
-            assert_eq!(rotated.data, entry.data);
-            assert_eq!(rotated.kind, entry.kind);
-        }
-        Ok(())
-    }
-}
+mod tests;
diff --git a/crates/core/src/dht/entry/tests.rs b/crates/core/src/dht/entry/tests.rs
new file mode 100644
index 000000000..22b318264
--- /dev/null
+++ b/crates/core/src/dht/entry/tests.rs
@@ -0,0 +1,560 @@
+use num_bigint::BigUint;
+
+use super::*;
+use crate::algebra::assert_join_semilattice_laws;
+use crate::algebra::assert_strong_eventual_consistency;
+use crate::ecc::SecretKey;
+use crate::message::Message;
+use crate::session::SessionSk;
+
+fn encoded(value: &str) -> Result {
+    value.to_string().encode()
+}
+
+fn data_entry(topic: &str, value: &str) -> Result {
+    (topic.to_string(), encoded(value)?).try_into()
+}
+
+fn data_entry_from_values(topic: &str, values: Vec) -> Result {
+    let data = values
+        .into_iter()
+        .map(|value| value.encode())
+        .collect::>>()?;
+    Ok(Entry::new(Entry::gen_did(topic)?, data, EntryKind::Data))
+}
+
+fn overflowing_data_entry(topic: &str, overflow: usize) -> Result<(Entry, usize)> {
+    let incoming_count = ENTRY_DATA_MAX_LEN + overflow;
+    let entry = data_entry_from_values(
+        topic,
+        (0..incoming_count)
+            .map(|i| format!("incoming{i}"))
+            .collect::>(),
+    )?;
+    Ok((entry, incoming_count))
+}
+
+fn decode_entry_data(entry: &Entry) -> Result> {
+    entry
+        .data
+        .iter()
+        .map(|item| item.decode())
+        .collect::>>()
+}
+
+fn assert_entry_keeps_recent_overflow(
+    entry: &Entry,
+    incoming_count: usize,
+    overflow: usize,
+) -> Result<()> {
+    assert_eq!(entry.data.len(), ENTRY_DATA_MAX_LEN);
+    let decoded = decode_entry_data(entry)?;
+    assert_eq!(decoded.first(), Some(&format!("incoming{overflow}")));
+    assert_eq!(
+        decoded.last(),
+        Some(&format!("incoming{}", incoming_count - 1))
+    );
+    Ok(())
+}
+
+fn subring_entry(name: &str) -> Result {
+    let creator = Entry::gen_did("creator")?;
+    Subring::new(name, creator)?.try_into()
+}
+
+fn actor() -> Did {
+    Did::from(42u32)
+}
+
+fn version(counter: u32) -> EntryVersion {
+    EntryVersion::new(
+        u128::from(counter),
+        Did::from(counter),
+        Did::from(counter.saturating_add(1000)),
+    )
+}
+
+fn data_delta(topic: &str, value: &str, counter: u32) -> Result {
+    data_entry(topic, value)?.stamp_delta(version(counter))
+}
+
+fn overwrite_delta(topic: &str, value: &str, counter: u32) -> Result {
+    data_entry(topic, value)?.stamp_overwrite(version(counter))
+}
+
+fn relay_delta(did: Did, value: &str, counter: u32) -> Result {
+    Entry::new(did, vec![encoded(value)?], EntryKind::RelayMessage).stamp_delta(version(counter))
+}
+
+#[test]
+fn gset_satisfies_join_semilattice_laws() {
+    let mut a = GSet::new();
+    a.insert(Did::from(1u32));
+    let mut b = GSet::new();
+    b.insert(Did::from(2u32));
+    let mut ab = GSet::new();
+    ab.insert(Did::from(1u32));
+    ab.insert(Did::from(2u32));
+
+    assert_join_semilattice_laws(&[GSet::new(), a, b, ab]);
+}
+
+#[test]
+fn data_topic_buffer_satisfies_join_semilattice_laws() -> Result<()> {
+    let carrier = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data)
+        .join(data_delta("topic", "a", 1)?)?
+        .join(data_delta("topic", "b", 2)?)?;
+    let tombstoned_a = carrier
+        .tombstone(data_delta("topic", "a", 1)?)?
+        .topic_buffer()?;
+    let samples = [
+        Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data).topic_buffer()?,
+        data_delta("topic", "a", 1)?.topic_buffer()?,
+        data_delta("topic", "b", 2)?.topic_buffer()?,
+        overwrite_delta("topic", "c", 3)?.topic_buffer()?,
+        tombstoned_a,
+    ];
+
+    assert_join_semilattice_laws(&samples);
+    Ok(())
+}
+
+#[test]
+fn relay_message_set_satisfies_join_semilattice_laws() -> Result<()> {
+    let did = Did::from(10u32);
+    let a = Entry::new(did, vec![encoded("a")?], EntryKind::RelayMessage)
+        .stamp_delta(version(1))?
+        .relay_set()?;
+    let b = Entry::new(did, vec![encoded("b")?], EntryKind::RelayMessage)
+        .stamp_delta(version(2))?
+        .relay_set()?;
+    let ab = Entry::new(did, vec![], EntryKind::RelayMessage)
+        .join(relay_delta(did, "a", 1)?)?
+        .join(relay_delta(did, "b", 2)?)?;
+    let tombstoned_a = ab.tombstone(relay_delta(did, "a", 1)?)?.relay_set()?;
+
+    assert_join_semilattice_laws(&[RelayMessageSet::default(), a, b, tombstoned_a]);
+    Ok(())
+}
+
+#[test]
+fn entry_join_is_strongly_eventually_consistent_for_data_deltas() -> Result<()> {
+    let base = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data);
+    let deltas = [
+        data_delta("topic", "a", 1)?,
+        data_delta("topic", "b", 2)?,
+        data_delta("topic", "a", 3)?,
+    ];
+
+    let forward = deltas
+        .iter()
+        .cloned()
+        .try_fold(base.clone(), |acc, delta| acc.join(delta))?;
+    let reverse = deltas
+        .iter()
+        .rev()
+        .cloned()
+        .try_fold(base.clone(), |acc, delta| acc.join(delta))?;
+    let duplicated = deltas
+        .iter()
+        .cloned()
+        .chain(deltas.iter().cloned())
+        .try_fold(base, |acc, delta| acc.join(delta))?;
+
+    assert_eq!(forward, reverse);
+    assert_eq!(forward, duplicated);
+    assert_eq!(decode_entry_data(&forward)?, vec![
+        String::from("b"),
+        String::from("a")
+    ]);
+    Ok(())
+}
+
+#[test]
+fn generic_sec_witness_accepts_data_topic_buffer_deltas() -> Result<()> {
+    let base = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data).topic_buffer()?;
+    let deltas = vec![
+        data_delta("topic", "a", 1)?.topic_buffer()?,
+        data_delta("topic", "b", 2)?.topic_buffer()?,
+    ];
+
+    assert_strong_eventual_consistency(base, &deltas);
+    Ok(())
+}
+
+#[test]
+fn storage_normalization_uses_lattice_top_n_order() -> Result<()> {
+    let incoming_count = ENTRY_DATA_MAX_LEN + 3;
+    let mut entry = data_entry_from_values(
+        "topic",
+        (0..incoming_count)
+            .map(|i| format!("incoming{i}"))
+            .collect::>(),
+    )?;
+    entry.crdt.dots = entry
+        .data
+        .iter()
+        .enumerate()
+        .map(|(index, _)| {
+            let counter = if index == 0 {
+                10_000
+            } else {
+                u32::try_from(index).map_err(|_| Error::EntryDotIndexOutOfBounds { index })?
+            };
+            EntryDot::for_index(version(counter), index)
+        })
+        .collect::>>()?;
+
+    let normalized = entry.try_into_storage_entry()?;
+    let decoded = decode_entry_data(&normalized)?;
+
+    assert_eq!(normalized.data.len(), ENTRY_DATA_MAX_LEN);
+    assert_eq!(normalized.data.len(), normalized.crdt.dots.len());
+    assert!(decoded.contains(&String::from("incoming0")));
+    assert!(!decoded.contains(&String::from("incoming1")));
+    assert!(!decoded.contains(&String::from("incoming2")));
+    assert!(!decoded.contains(&String::from("incoming3")));
+    Ok(())
+}
+
+#[test]
+fn storage_normalization_realigns_legacy_mismatched_dots() -> Result<()> {
+    let mut entry = data_entry_from_values(
+        "topic",
+        (0..ENTRY_DATA_MAX_LEN + 2)
+            .map(|i| format!("legacy{i}"))
+            .collect::>(),
+    )?;
+    entry.crdt.dots = vec![EntryDot::for_index(version(10_000), 0)?];
+
+    let normalized = entry.try_into_storage_entry()?;
+
+    assert_eq!(normalized.data.len(), ENTRY_DATA_MAX_LEN);
+    assert_eq!(normalized.data.len(), normalized.crdt.dots.len());
+    Ok(())
+}
+
+#[test]
+fn crdt_constructors_normalize_carrier_invariants() -> Result<()> {
+    let register = version(10);
+    let stale = encoded("stale")?;
+    let live = encoded("live")?;
+    let mut values = BTreeMap::new();
+    values.insert(stale.clone(), EntryDot::for_index(version(1), 0)?);
+    let live_dot = EntryDot::for_index(version(11), 0)?;
+    values.insert(live.clone(), live_dot);
+
+    let buffer = DataTopicBuffer::new(Some(register), values, BTreeSet::new());
+    assert_eq!(buffer.values.len(), 1);
+    assert!(buffer.values.contains_key(&live));
+
+    let relay = RelayMessageSet::new(buffer, BTreeSet::from([live_dot]));
+    assert!(relay.adds.values.is_empty());
+    assert!(relay.removes.contains(&live_dot));
+    Ok(())
+}
+
+#[test]
+fn overwrite_register_tiebreaker_converges_for_same_timestamp_actor() -> Result<()> {
+    let did = Entry::gen_did("topic")?;
+    let issuer = actor();
+    let lower = Entry::new(did, vec![encoded("lower")?], EntryKind::Data)
+        .stamp_overwrite(EntryVersion::new(1, issuer, Did::from(1u32)))?;
+    let higher = Entry::new(did, vec![encoded("higher")?], EntryKind::Data)
+        .stamp_overwrite(EntryVersion::new(1, issuer, Did::from(2u32)))?;
+    let base = Entry::new(did, vec![], EntryKind::Data);
+
+    let forward = base.clone().join(lower.clone())?.join(higher.clone())?;
+    let reverse = base.join(higher)?.join(lower)?;
+
+    assert_eq!(forward, reverse);
+    assert_eq!(decode_entry_data(&forward)?, vec![String::from("higher")]);
+    Ok(())
+}
+
+#[test]
+fn operation_digest_hashes_canonical_bytes_not_legacy_base58() -> Result<()> {
+    let entry = data_entry("topic", "value")?;
+    let digest = OperationDigest {
+        kind: entry.kind,
+        did: entry.did,
+        data: &entry.data,
+    };
+    let bytes = bincode::serialize(&digest).map_err(Error::BincodeSerialize)?;
+
+    let direct = Did::try_from(HashStr::from_bytes(&bytes))?;
+    let legacy_encoded = bytes.encode()?;
+    let legacy_base58 = Entry::gen_did(legacy_encoded.value())?;
+
+    assert_eq!(entry.operation_digest()?, direct);
+    assert_ne!(direct, legacy_base58);
+    Ok(())
+}
+
+#[test]
+fn forwarded_overwrite_witness_is_not_reissued_after_local_floor() -> Result<()> {
+    let current = overwrite_delta("topic", "current", 10)?;
+    let stale_forwarded = overwrite_delta("topic", "stale", 1)?;
+
+    let updated = current.overwrite(stale_forwarded, actor())?;
+
+    assert_eq!(decode_entry_data(&updated)?, vec![String::from("current")]);
+    Ok(())
+}
+
+#[test]
+fn overwrite_replaces_data_for_same_data_entry() -> Result<()> {
+    let entry = data_entry("topic", "old")?;
+    let other = data_entry("topic", "new")?;
+    let updated = entry.overwrite(other, actor())?;
+    assert_eq!(decode_entry_data(&updated)?, vec![String::from("new")]);
+    Ok(())
+}
+
+#[test]
+fn overwrite_rejects_non_data_entry() -> Result<()> {
+    let entry = subring_entry("ring")?;
+    let other = entry.clone();
+
+    assert!(matches!(
+        entry.overwrite(other, actor()),
+        Err(Error::EntryNotOverwritable)
+    ));
+    Ok(())
+}
+
+#[test]
+fn overwrite_rejects_kind_mismatch() -> Result<()> {
+    let entry = data_entry("topic", "old")?;
+    let mut other = entry.clone();
+    other.kind = EntryKind::RelayMessage;
+
+    assert!(matches!(
+        entry.overwrite(other, actor()),
+        Err(Error::EntryKindNotEqual)
+    ));
+    Ok(())
+}
+
+#[test]
+fn overwrite_rejects_key_mismatch() -> Result<()> {
+    let entry = data_entry("topic-a", "old")?;
+    let other = data_entry("topic-b", "new")?;
+
+    assert!(matches!(
+        entry.overwrite(other, actor()),
+        Err(Error::EntryDidNotEqual)
+    ));
+    Ok(())
+}
+
+#[test]
+fn overwrite_caps_payloads_larger_than_max_len() -> Result<()> {
+    let overflow = 3;
+    let (incoming, incoming_count) = overflowing_data_entry("topic", overflow)?;
+    let entry = data_entry("topic", "base")?;
+    let updated = entry.overwrite(incoming, actor())?;
+    assert_entry_keeps_recent_overflow(&updated, incoming_count, overflow)
+}
+
+#[test]
+fn extend_appends_data_for_same_entry() -> Result<()> {
+    let entry = data_entry("topic", "first")?;
+    let other = data_entry("topic", "second")?;
+    let updated = entry.extend(other, actor())?;
+    assert_eq!(decode_entry_data(&updated)?, vec![
+        String::from("first"),
+        String::from("second")
+    ]);
+    Ok(())
+}
+
+#[test]
+fn extend_trims_oldest_items_at_max_len() -> Result<()> {
+    let mut entry = data_entry("topic", "test0")?;
+    for i in 1..ENTRY_DATA_MAX_LEN {
+        let data = format!("test{i}");
+        let other = data_entry("topic", &data)?;
+        entry = entry.extend(other, actor())?;
+        assert_eq!(entry.data.len(), i + 1);
+    }
+
+    for i in ENTRY_DATA_MAX_LEN..ENTRY_DATA_MAX_LEN + 10 {
+        let data = format!("test{i}");
+        let other = data_entry("topic", &data)?;
+        entry = entry.extend(other, actor())?;
+        assert_eq!(entry.data.len(), ENTRY_DATA_MAX_LEN);
+        let decoded = decode_entry_data(&entry)?;
+        assert_eq!(
+            decoded.first(),
+            Some(&format!("test{}", i - ENTRY_DATA_MAX_LEN + 1))
+        );
+        assert_eq!(decoded.last(), Some(&data));
+    }
+    Ok(())
+}
+
+#[test]
+fn extend_caps_incoming_payloads_larger_than_max_len() -> Result<()> {
+    let overflow = 3;
+    let (incoming, incoming_count) = overflowing_data_entry("topic", overflow)?;
+    let entry = data_entry("topic", "base")?;
+    let updated = entry.extend(incoming, actor())?;
+    assert_entry_keeps_recent_overflow(&updated, incoming_count, overflow)
+}
+
+#[test]
+fn extend_rejects_non_data_entry() -> Result<()> {
+    let entry = subring_entry("ring")?;
+    let other = entry.clone();
+
+    assert!(matches!(
+        entry.extend(other, actor()),
+        Err(Error::EntryNotAppendable)
+    ));
+    Ok(())
+}
+
+#[test]
+fn touch_moves_existing_items_to_end_once() -> Result<()> {
+    let entry = data_entry("topic", "a")?
+        .extend(data_entry("topic", "b")?, actor())?
+        .extend(data_entry("topic", "c")?, actor())?;
+    let touched = data_entry("topic", "b")?;
+    let updated = entry.touch(touched, actor())?;
+    assert_eq!(decode_entry_data(&updated)?, vec![
+        String::from("a"),
+        String::from("c"),
+        String::from("b")
+    ]);
+    Ok(())
+}
+
+#[test]
+fn touch_trims_oldest_non_touched_items_at_max_len() -> Result<()> {
+    let mut entry = data_entry("topic", "test0")?;
+    for i in 1..ENTRY_DATA_MAX_LEN {
+        entry = entry.extend(data_entry("topic", &format!("test{i}"))?, actor())?;
+    }
+    let updated = entry.touch(data_entry("topic", "test0")?, actor())?;
+    assert_eq!(updated.data.len(), ENTRY_DATA_MAX_LEN);
+    let decoded = decode_entry_data(&updated)?;
+    assert_eq!(decoded.first(), Some(&String::from("test1")));
+    assert_eq!(decoded.last(), Some(&String::from("test0")));
+    Ok(())
+}
+
+#[test]
+fn relay_tombstone_removes_observed_message_by_join() -> Result<()> {
+    let did = Did::from(30u32);
+    let first = relay_delta(did, "first", 1)?;
+    let second = relay_delta(did, "second", 2)?;
+    let carrier = Entry::new(did, vec![], EntryKind::RelayMessage)
+        .join(first.clone())?
+        .join(second.clone())?;
+
+    let removed = carrier.tombstone(first.clone())?;
+
+    assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
+    let joined_with_stale_add = removed.join(first)?;
+    assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
+        String::from("second")
+    ]);
+    Ok(())
+}
+
+#[test]
+fn data_tombstone_removes_observed_payload_by_join() -> Result<()> {
+    let first = data_delta("topic", "first", 1)?;
+    let second = data_delta("topic", "second", 2)?;
+    let carrier = Entry::new(Entry::gen_did("topic")?, vec![], EntryKind::Data)
+        .join(first.clone())?
+        .join(second.clone())?;
+
+    let removed = carrier.tombstone(first.clone())?;
+
+    assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
+    let joined_with_stale_add = removed.join(first)?;
+    assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
+        String::from("second")
+    ]);
+    Ok(())
+}
+
+#[test]
+fn tombstone_rejects_non_data_or_relay_entry() -> Result<()> {
+    let entry = subring_entry("ring")?;
+    let other = entry.clone();
+
+    assert!(matches!(
+        entry.tombstone(other),
+        Err(Error::EntryNotTombstonable)
+    ));
+    Ok(())
+}
+
+#[test]
+fn touch_caps_incoming_payloads_larger_than_max_len() -> Result<()> {
+    let overflow = 3;
+    let (incoming, incoming_count) = overflowing_data_entry("topic", overflow)?;
+    let entry = data_entry("topic", "base")?;
+    let updated = entry.touch(incoming, actor())?;
+    assert_entry_keeps_recent_overflow(&updated, incoming_count, overflow)
+}
+
+#[test]
+fn join_subring_adds_member_to_subring_entry() -> Result<()> {
+    let entry = subring_entry("ring")?;
+    let member = Entry::gen_did("member")?;
+    let updated = entry.join_subring(member)?;
+    let subring = Subring::try_from(updated)?;
+    assert_eq!(subring.finger.first(), Some(member));
+    Ok(())
+}
+
+#[test]
+fn join_subring_rejects_non_subring_entry() -> Result<()> {
+    let entry = data_entry("topic", "value")?;
+    let member = Entry::gen_did("member")?;
+
+    assert!(matches!(
+        entry.join_subring(member),
+        Err(Error::EntryNotJoinable)
+    ));
+    Ok(())
+}
+
+#[test]
+fn operation_default_entry_matches_operation_kind() -> Result<()> {
+    let target = data_entry("topic", "value")?;
+    let default = EntryOperation::Extend(target.clone()).gen_default_entry()?;
+    assert_eq!(default.did, target.did);
+    assert_eq!(default.kind, EntryKind::Data);
+    assert!(default.data.is_empty());
+    Ok(())
+}
+
+#[test]
+fn message_payload_entry_key_targets_successor_of_signer() -> Result<()> {
+    let key = SecretKey::random();
+    let session = SessionSk::new_with_seckey(&key)?;
+    let signer: Did = key.address().into();
+    let payload = MessagePayload::new_send(Message::custom(b"relay")?, &session, signer, signer)?;
+    let entry = Entry::try_from(payload)?;
+    let expected = BigUint::from(signer) + BigUint::from(1u16);
+    assert_eq!(entry.did, expected.into());
+    assert_eq!(entry.kind, EntryKind::RelayMessage);
+    Ok(())
+}
+
+#[test]
+fn affine_preserves_payload_and_kind_while_rotating_keys() -> Result<()> {
+    let entry = data_entry("topic", "value")?;
+    let affined = entry.affine(3)?;
+    assert_eq!(affined.len(), 3);
+    for rotated in affined {
+        assert_eq!(rotated.data, entry.data);
+        assert_eq!(rotated.kind, entry.kind);
+    }
+    Ok(())
+}
diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index 609677c59..c82773822 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -149,9 +149,7 @@ impl Stabilizer {
     }
 
     async fn run_step(&self, step: &'static str, timeout: Duration, future: F)
-    where
-        F: Future>,
-    {
+    where F: Future> {
         tracing::debug!(
             target: "rings_core::dht::stabilization",
             local = %self.dht.did,
@@ -415,9 +413,7 @@ impl Stabilizer {
                 .evidence
                 .reaches_failure_limit(DHT_TOPOLOGY_EVICTION_THRESHOLDS)
             {
-                return Some(TopologyPeerRemovalReason::LocalFailureLimit(
-                    measurement,
-                ));
+                return Some(TopologyPeerRemovalReason::LocalFailureLimit(measurement));
             }
         }
 
diff --git a/crates/core/src/message/handlers/connection.rs b/crates/core/src/message/handlers/connection.rs
index 78bdef44d..201fe89fe 100644
--- a/crates/core/src/message/handlers/connection.rs
+++ b/crates/core/src/message/handlers/connection.rs
@@ -1,9 +1,9 @@
 use async_trait::async_trait;
 
 use crate::dht::successor::SuccessorReader;
+use crate::dht::topology;
 use crate::dht::types::Chord;
 use crate::dht::types::CorrectChord;
-use crate::dht::topology;
 use crate::dht::Did;
 use crate::dht::PeerRing;
 use crate::dht::PeerRingAction;
@@ -277,10 +277,7 @@ pub mod tests {
         dht.join(requester)?;
 
         assert_eq!(dht.successors().list()?, vec![requester, next, tail]);
-        assert_eq!(
-            connect_successor_hint(&dht, requester, requester)?,
-            next
-        );
+        assert_eq!(connect_successor_hint(&dht, requester, requester)?, next);
         Ok(())
     }
 
@@ -662,8 +659,7 @@ pub mod tests {
             "node4 connected node3: DHT successors converged",
             || {
                 Ok(
-                    node1.dht().successors().list()?
-                        == vec![node2.did(), node3.did(), node4.did()]
+                    node1.dht().successors().list()? == vec![node2.did(), node3.did(), node4.did()]
                         && node2.dht().successors().list()?
                             == vec![node3.did(), node4.did(), node1.did()]
                         && node3.dht().successors().list()?
@@ -714,13 +710,16 @@ pub mod tests {
         let joining = prepare_node(keys[1]).await;
 
         manually_establish_connection(&joining.swarm, &node1.swarm).await;
-        wait_until("joining peer connects past bootstrap successor self-report", || {
-            Ok(joining
-                .swarm
-                .transport
-                .get_connection(node2.did())
-                .is_some())
-        })
+        wait_until(
+            "joining peer connects past bootstrap successor self-report",
+            || {
+                Ok(joining
+                    .swarm
+                    .transport
+                    .get_connection(node2.did())
+                    .is_some())
+            },
+        )
         .await?;
 
         wait_for_msgs([&node1, &node2, &node3, &joining]).await;
diff --git a/crates/core/src/message/handlers/stabilization.rs b/crates/core/src/message/handlers/stabilization.rs
index 3801fc143..4aba3e4b5 100644
--- a/crates/core/src/message/handlers/stabilization.rs
+++ b/crates/core/src/message/handlers/stabilization.rs
@@ -2,6 +2,7 @@ use async_trait::async_trait;
 
 use crate::dht::Chord;
 use crate::dht::ChordStorageSync;
+use crate::error::Error;
 use crate::error::Result;
 use crate::message::effects::ConnectionFunctor;
 use crate::message::effects::PayloadRelayFunctor;
@@ -18,9 +19,16 @@ use crate::message::MessagePayload;
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
 impl HandleMsg for MessageHandler {
     async fn handle(&self, ctx: &MessagePayload, msg: &NotifyPredecessorSend) -> Result<()> {
-        let predecessor = self.dht.notify(msg.did)?;
+        if ctx.should_forward_from(self.dht.did) {
+            return self
+                .run_effects([PayloadRelayFunctor::forward_payload(ctx, None).into()])
+                .await;
+        }
+
+        let origin = self.admitted_notify_predecessor_origin(ctx, msg)?;
+        let predecessor = self.dht.notify(origin)?;
 
-        if predecessor != ctx.relay.try_origin_sender()? {
+        if predecessor != origin {
             return self
                 .run_effects([PayloadRelayFunctor::send_report_message(
                     ctx,
@@ -34,6 +42,28 @@ impl HandleMsg for MessageHandler {
     }
 }
 
+impl MessageHandler {
+    fn admitted_notify_predecessor_origin(
+        &self,
+        ctx: &MessagePayload,
+        msg: &NotifyPredecessorSend,
+    ) -> Result {
+        let origin = ctx.relay.try_origin_sender()?;
+        if msg.did != origin {
+            return Err(Error::InvalidMessage(format!(
+                "notify predecessor DID {} does not match relay origin {}",
+                msg.did, origin
+            )));
+        }
+        if !self.transport.is_admitted_connection(origin) {
+            return Err(Error::InvalidMessage(format!(
+                "notify predecessor origin {origin} is not an admitted connection"
+            )));
+        }
+        Ok(origin)
+    }
+}
+
 #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
 impl HandleMsg for MessageHandler {
@@ -90,11 +120,64 @@ mod test {
 
     impl SwarmCallback for NoopCallback {}
 
+    fn notify_context(origin: &SecretKey, destination: crate::dht::Did) -> Result {
+        let session = SessionSk::new_with_seckey(origin)?;
+        MessagePayload::new_send(
+            Message::custom(b"notify predecessor context")?,
+            &session,
+            destination,
+            destination,
+        )
+    }
+
     fn next_generated_key(keys: &mut impl Iterator) -> Result {
         keys.next()
             .ok_or_else(|| Error::InvalidMessage("expected generated key".to_string()))
     }
 
+    #[tokio::test]
+    async fn notify_predecessor_rejects_origin_mismatch_without_mutating_topology() -> Result<()> {
+        let node = prepare_node(SecretKey::random()).await;
+        let origin = SecretKey::random();
+        let spoofed = SecretKey::random().address().into();
+        let context = notify_context(&origin, node.did())?;
+        let handler = MessageHandler::new(node.swarm.transport.clone(), Arc::new(NoopCallback));
+
+        let result = handler
+            .handle(&context, &NotifyPredecessorSend { did: spoofed })
+            .await;
+
+        assert!(matches!(
+            result,
+            Err(Error::InvalidMessage(message))
+                if message.contains("does not match relay origin")
+        ));
+        assert_eq!(*node.dht().lock_predecessor()?, None);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn notify_predecessor_rejects_unadmitted_origin_without_mutating_topology() -> Result<()>
+    {
+        let node = prepare_node(SecretKey::random()).await;
+        let origin = SecretKey::random();
+        let origin_did = origin.address().into();
+        let context = notify_context(&origin, node.did())?;
+        let handler = MessageHandler::new(node.swarm.transport.clone(), Arc::new(NoopCallback));
+
+        let result = handler
+            .handle(&context, &NotifyPredecessorSend { did: origin_did })
+            .await;
+
+        assert!(matches!(
+            result,
+            Err(Error::InvalidMessage(message))
+                if message.contains("not an admitted connection")
+        ));
+        assert_eq!(*node.dht().lock_predecessor()?, None);
+        Ok(())
+    }
+
     #[tokio::test]
     async fn test_triple_nodes_stabilization_1_2_3() -> Result<()> {
         let keys = gen_ordered_keys(3);
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index 4aa7b5e19..f7d181855 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -37,13 +37,11 @@ use rings_transport::delivery::DeliveryFuture;
 use rings_transport::webrtc_config::WebrtcUdpPortRange;
 
 use self::storage_sync::StorageSyncAckMap;
-use crate::chunk::Chunk;
 use crate::chunk::ChunkList;
 use crate::chunk::Framing;
 use crate::chunk::ReassemblyLimits;
 use crate::chunk::WireReserves;
 use crate::consts::TRANSPORT_MAX_SIZE;
-use crate::dht::entry::PlacementMiss;
 use crate::dht::Did;
 use crate::dht::LiveDid;
 use crate::dht::PeerRing;
@@ -65,130 +63,26 @@ use crate::session::SessionSk;
 use crate::swarm::callback::InnerSwarmCallback;
 use crate::utils::get_epoch_ms_i64;
 
+mod delivery;
+mod pending;
+mod storage_lookup;
 mod storage_sync;
 
-const STORAGE_LOOKUP_OBSERVATION_TTL_MS: i64 = 30_000;
-/// Maximum number of read-repair miss observation buckets retained per transport.
-pub(crate) const STORAGE_LOOKUP_OBSERVATION_CAPACITY: usize = 1024;
-
-/// Maximum number of peers that may be handshaking before a data channel opens.
-pub(crate) const DEFAULT_PENDING_CONNECTION_CAPACITY: usize = 32;
+use self::delivery::frame_chunk;
+use self::delivery::record_measurement;
+use self::delivery::spawn_chunked_send;
+use self::delivery::spawn_delivery;
+pub(crate) use self::pending::PendingConnectionAttempt;
+use self::pending::PendingPeerPool;
+pub(crate) use self::pending::DEFAULT_PENDING_CONNECTION_CAPACITY;
+#[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
+use self::pending::PENDING_CONNECTION_TIMEOUT_MS;
+use self::storage_lookup::StorageLookupObservationMap;
+#[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
+pub(crate) use self::storage_lookup::STORAGE_LOOKUP_OBSERVATION_CAPACITY;
 
-const PENDING_CONNECTION_TIMEOUT_MS: i64 = 180_000;
 const DATA_CHANNEL_OPEN_TIMEOUT: Duration = Duration::from_secs(8);
 
-/// Identifies one pending handshake for a peer.
-///
-/// A peer can have a replacement handshake after a timeout. Callbacks carry
-/// this token so a late callback from the replaced connection cannot promote
-/// the newer handshake into the active routing set.
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub(crate) struct PendingConnectionAttempt {
-    peer: Did,
-    generation: u64,
-}
-
-impl PendingConnectionAttempt {
-    pub(crate) fn peer(self) -> Did {
-        self.peer
-    }
-}
-
-#[derive(Debug)]
-struct PendingPeer {
-    generation: u64,
-    admitted_at_ms: i64,
-}
-
-/// Bounded, non-routable handshakes owned by the swarm lifecycle.
-///
-/// The pool deliberately has no DHT reference: a peer is visible to Chord
-/// only after its data channel opens and the matching attempt is promoted.
-struct PendingPeerPool {
-    next_generation: u64,
-    peers: BTreeMap,
-}
-
-impl PendingPeerPool {
-    fn new() -> Self {
-        Self {
-            next_generation: 0,
-            peers: BTreeMap::new(),
-        }
-    }
-
-    fn reserve(&mut self, peer: Did, now_ms: i64) -> Result {
-        if self.peers.contains_key(&peer) {
-            return Err(Error::AlreadyConnected);
-        }
-        if self.peers.len() >= MAX_PENDING {
-            return Err(Error::PendingConnectionCapacityExceeded {
-                capacity: MAX_PENDING,
-            });
-        }
-
-        self.next_generation = self.next_generation.wrapping_add(1);
-        let attempt = PendingConnectionAttempt {
-            peer,
-            generation: self.next_generation,
-        };
-        self.peers.insert(
-            peer,
-            PendingPeer {
-                generation: attempt.generation,
-                admitted_at_ms: now_ms,
-            },
-        );
-        Ok(attempt)
-    }
-
-    fn contains(&self, peer: Did) -> bool {
-        self.peers.contains_key(&peer)
-    }
-
-    fn remove(&mut self, attempt: PendingConnectionAttempt) -> bool {
-        let Some(peer) = self.peers.get(&attempt.peer) else {
-            return false;
-        };
-        if peer.generation != attempt.generation {
-            return false;
-        }
-        self.peers.remove(&attempt.peer);
-        true
-    }
-
-    fn expire(&mut self, now_ms: i64) -> Vec {
-        let expired = self
-            .peers
-            .iter()
-            .filter_map(|(peer, pending)| {
-                (now_ms.saturating_sub(pending.admitted_at_ms) >= PENDING_CONNECTION_TIMEOUT_MS)
-                    .then_some(PendingConnectionAttempt {
-                        peer: *peer,
-                        generation: pending.generation,
-                    })
-            })
-            .collect::>();
-        for attempt in &expired {
-            self.peers.remove(&attempt.peer);
-        }
-        expired
-    }
-
-    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
-    fn len(&self) -> usize {
-        self.peers.len()
-    }
-}
-
-// Invariant: after every successful observation-buffer mutation,
-// observations.len() <= STORAGE_LOOKUP_OBSERVATION_CAPACITY.
-// Invariant: after evict_storage_lookup_observations(observations, now), every
-// retained bucket satisfies
-// now.saturating_sub(observed_at_ms) <= STORAGE_LOOKUP_OBSERVATION_TTL_MS. This
-// is the freshness witness required before PlacementMiss.owner drives read-repair.
-type StorageLookupObservationMap = BTreeMap;
-
 pub struct SwarmTransport {
     pub(crate) network_id: u32,
     transport: Transport,
@@ -254,202 +148,12 @@ impl SwarmWebrtcConfig {
     }
 }
 
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
-struct StorageLookupObservationKey {
-    resource: Did,
-    redundancy: u16,
-}
-
-struct StorageLookupObservation {
-    observed_at_ms: i64,
-    misses: BTreeSet,
-}
-
-fn storage_lookup_observation_now_ms() -> i64 {
-    get_epoch_ms_i64()
-}
-
-fn oldest_storage_lookup_observation_key(
-    observations: &StorageLookupObservationMap,
-) -> Option {
-    observations
-        .iter()
-        .min_by_key(|(key, observation)| (observation.observed_at_ms, **key))
-        .map(|(key, _)| *key)
-}
-
-// Post: observations.len() <= STORAGE_LOOKUP_OBSERVATION_CAPACITY.
-// Post: forall bucket in observations,
-// now_ms.saturating_sub(bucket.observed_at_ms) <= STORAGE_LOOKUP_OBSERVATION_TTL_MS.
-// Preservation: removing expired buckets and then oldest buckets cannot create
-// a stale bucket or increase the number of buckets.
-fn evict_storage_lookup_observations(observations: &mut StorageLookupObservationMap, now_ms: i64) {
-    observations.retain(|_, observation| {
-        now_ms.saturating_sub(observation.observed_at_ms) <= STORAGE_LOOKUP_OBSERVATION_TTL_MS
-    });
-
-    while observations.len() > STORAGE_LOOKUP_OBSERVATION_CAPACITY {
-        let Some(stale_key) = oldest_storage_lookup_observation_key(observations) else {
-            break;
-        };
-        observations.remove(&stale_key);
-    }
-}
-
-fn reserve_storage_lookup_observation_slot(observations: &mut StorageLookupObservationMap) {
-    while observations.len() >= STORAGE_LOOKUP_OBSERVATION_CAPACITY {
-        let Some(stale_key) = oldest_storage_lookup_observation_key(observations) else {
-            break;
-        };
-        observations.remove(&stale_key);
-    }
-}
-
 #[derive(Clone)]
 pub struct SwarmConnection {
     peer: Did,
     pub connection: ConnectionRef,
 }
 
-async fn record_measurement(measure: Option, did: Did, counter: MeasureCounter) {
-    if let Some(measure) = measure {
-        measure.incr(did, counter).await;
-    }
-}
-
-/// Drive a message's [DeliveryFuture] to completion on the runtime, recording
-/// the eventual peer-quality observation. This keeps delivery tracking confined
-/// to the send site: the status never propagates up through the swarm/node
-/// layers.
-#[cfg(all(feature = "wasm", target_family = "wasm"))]
-fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) {
-    wasm_bindgen_futures::spawn_local(async move {
-        match fut.await {
-            Ok(()) => record_measurement(measure, did, MeasureCounter::Sent).await,
-            Err(e) => {
-                tracing::warn!("Message to {did} was not delivered: {e}");
-                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-            }
-        }
-    });
-}
-
-/// Drive a message's [DeliveryFuture] to completion on the runtime, recording
-/// the eventual peer-quality observation.
-#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
-fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) {
-    tokio::spawn(async move {
-        match fut.await {
-            Ok(()) => record_measurement(measure, did, MeasureCounter::Sent).await,
-            Err(e) => {
-                tracing::warn!("Message to {did} was not delivered: {e}");
-                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-            }
-        }
-    });
-}
-
-/// Frame one chunk into the bytes a data-channel send carries: wrap it in a `MessagePayload`
-/// addressed to `did` and serialize it. Pure (the only failure is serialization).
-fn frame_chunk(session_sk: &SessionSk, did: Did, chunk: Chunk) -> Result {
-    MessagePayload::new_send(Message::Chunk(chunk), session_sk, did, did)?.to_bincode()
-}
-
-/// The *tail* of a chunked message — every chunk after the first — yielded lazily. Boxed so the
-/// background task owns a concrete, nameable type (`Send` off the browser, where spawned tasks must
-/// be `Send`; single-threaded on it).
-#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
-type ChunkTail = Box + Send>;
-#[cfg(all(feature = "wasm", target_family = "wasm"))]
-type ChunkTail = Box>;
-
-/// Drive the *tail* of a chunked send: the first chunk has already been accepted by the caller
-/// (`do_send_payload`), so wait for it to flush (backpressure), then frame, send, and await each
-/// remaining chunk in turn. One chunk is in flight at a time and no per-chunk task is spawned. A
-/// later frame/send failure aborts the rest; the receiver TTL-expires the partial message (chunks
-/// carry the message ttl), so no abort marker is needed. Fire-and-forget — the caller already
-/// learned whether the *first* chunk was accepted, matching the whole-message contract.
-async fn run_chunked_send(
-    conn: SwarmConnection,
-    tail: ChunkTail,
-    first_delivery: DeliveryFuture,
-    session_sk: SessionSk,
-    did: Did,
-    measure: Option,
-) {
-    if let Err(e) = first_delivery.await {
-        tracing::warn!("Chunked send to {did} stopped before the first chunk flushed: {e}");
-        record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-        return;
-    }
-    for chunk in tail {
-        let bytes = match frame_chunk(&session_sk, did, chunk) {
-            Ok(bytes) => bytes,
-            Err(e) => {
-                tracing::warn!("Chunked send to {did} aborted while framing a chunk: {e}");
-                return;
-            }
-        };
-        match conn.send_data(bytes).await {
-            Ok(delivery) => {
-                if let Err(e) = delivery.await {
-                    tracing::warn!("Chunked send to {did} stopped before flush: {e}");
-                    record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-                    return;
-                }
-            }
-            Err(e) => {
-                tracing::warn!("Chunked send to {did} stopped: {e}");
-                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-                return;
-            }
-        }
-    }
-    record_measurement(measure, did, MeasureCounter::Sent).await;
-}
-
-/// Drive the tail of a chunked send on the runtime (one bounded task per large message). See
-/// [`run_chunked_send`].
-#[cfg(all(feature = "wasm", target_family = "wasm"))]
-fn spawn_chunked_send(
-    conn: SwarmConnection,
-    tail: ChunkTail,
-    first_delivery: DeliveryFuture,
-    session_sk: SessionSk,
-    did: Did,
-    measure: Option,
-) {
-    wasm_bindgen_futures::spawn_local(run_chunked_send(
-        conn,
-        tail,
-        first_delivery,
-        session_sk,
-        did,
-        measure,
-    ));
-}
-
-/// Drive the tail of a chunked send on the runtime (one bounded task per large message). See
-/// [`run_chunked_send`].
-#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
-fn spawn_chunked_send(
-    conn: SwarmConnection,
-    tail: ChunkTail,
-    first_delivery: DeliveryFuture,
-    session_sk: SessionSk,
-    did: Did,
-    measure: Option,
-) {
-    tokio::spawn(run_chunked_send(
-        conn,
-        tail,
-        first_delivery,
-        session_sk,
-        did,
-        measure,
-    ));
-}
-
 impl SwarmTransport {
     pub(crate) fn new(
         network_id: u32,
@@ -625,327 +329,10 @@ impl SwarmTransport {
         }
     }
 
-    fn storage_lookup_observation_key(
-        &self,
-        resource: Did,
-        redundancy: u16,
-    ) -> Result {
-        self.ensure_storage_redundancy_value(redundancy)?;
-        Ok(StorageLookupObservationKey {
-            resource,
-            redundancy,
-        })
-    }
-
-    /// Start a fresh lookup round for `resource`.
-    ///
-    /// This replaces any previous miss observations for the same resource and
-    /// redundancy with an empty local-authorized bucket. Inbound FoundEntry
-    /// messages may only add misses to an existing bucket, so remote peers cannot
-    /// create a new redundancy mode.
-    ///
-    /// Post: if capacity permits one active lookup, a bucket exists for
-    /// `(resource, redundancy)` and contains no misses.
-    /// Preservation: eviction establishes the capacity and freshness invariants
-    /// before replacing the lookup-round bucket.
-    pub(crate) fn start_storage_lookup(&self, resource: Did, redundancy: u16) -> Result<()> {
-        let key = self.storage_lookup_observation_key(resource, redundancy)?;
-        let mut observations = self
-            .storage_lookup_observations
-            .lock()
-            .map_err(|_| Error::DHTSyncLockError)?;
-        let now = storage_lookup_observation_now_ms();
-        evict_storage_lookup_observations(&mut observations, now);
-        reserve_storage_lookup_observation_slot(&mut observations);
-        observations.insert(
-            key,
-            StorageLookupObservation {
-                observed_at_ms: now,
-                misses: BTreeSet::new(),
-            },
-        );
-        Ok(())
-    }
-
-    /// Validate that a storage lookup response belongs to a local lookup round.
-    ///
-    /// Post: `Ok(())` proves a fresh bucket exists for `(resource, redundancy)`.
-    pub(crate) fn ensure_storage_lookup_active(
-        &self,
-        resource: Did,
-        redundancy: u16,
-    ) -> Result<()> {
-        let key = self.storage_lookup_observation_key(resource, redundancy)?;
-        let mut observations = self
-            .storage_lookup_observations
-            .lock()
-            .map_err(|_| Error::DHTSyncLockError)?;
-        let now = storage_lookup_observation_now_ms();
-        evict_storage_lookup_observations(&mut observations, now);
-        if observations.contains_key(&key) {
-            Ok(())
-        } else {
-            Err(Error::InvalidMessage(
-                "storage lookup response has no active local lookup".to_string(),
-            ))
-        }
-    }
-
-    /// Buffer placement misses observed by an in-flight storage lookup.
-    ///
-    /// Post: retained observation buckets satisfy the capacity and freshness
-    /// invariants.
-    /// Post: the supplied misses are appended only to a bucket previously created
-    /// by [`Self::start_storage_lookup`].
-    pub(crate) fn observe_storage_misses(
-        &self,
-        resource: Did,
-        redundancy: u16,
-        misses: impl IntoIterator,
-    ) -> Result<()> {
-        let key = self.storage_lookup_observation_key(resource, redundancy)?;
-        let mut misses = misses.into_iter().peekable();
-        if misses.peek().is_none() {
-            return Ok(());
-        }
-        let mut observations = self
-            .storage_lookup_observations
-            .lock()
-            .map_err(|_| Error::DHTSyncLockError)?;
-        let now = storage_lookup_observation_now_ms();
-        evict_storage_lookup_observations(&mut observations, now);
-        let Some(observation) = observations.get_mut(&key) else {
-            return Err(Error::InvalidMessage(
-                "storage miss observation has no active local lookup".to_string(),
-            ));
-        };
-        observation.observed_at_ms = now;
-        observation.misses.extend(misses);
-        evict_storage_lookup_observations(&mut observations, now);
-        Ok(())
-    }
-
-    /// Drain fresh miss observations for a found entry.
-    ///
-    /// Post: returned misses come only from a bucket that survived freshness
-    /// eviction at this call's observation time.
-    /// Post: the bucket remains active with no buffered misses until TTL or a new
-    /// lookup round removes it.
-    /// Preservation: eviction before drain prevents stale owners from driving
-    /// late read-repair.
-    pub(crate) fn take_storage_misses(
-        &self,
-        resource: Did,
-        redundancy: u16,
-    ) -> Result> {
-        let key = self.storage_lookup_observation_key(resource, redundancy)?;
-        let mut observations = self
-            .storage_lookup_observations
-            .lock()
-            .map_err(|_| Error::DHTSyncLockError)?;
-        let now = storage_lookup_observation_now_ms();
-        evict_storage_lookup_observations(&mut observations, now);
-        let Some(observation) = observations.get_mut(&key) else {
-            return Err(Error::InvalidMessage(
-                "storage repair has no active local lookup".to_string(),
-            ));
-        };
-        Ok(std::mem::take(&mut observation.misses)
-            .into_iter()
-            .collect())
-    }
-
-    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
-    /// Test hook: make one observation bucket older than the freshness TTL.
-    pub(crate) fn expire_storage_lookup_observation(
-        &self,
-        resource: Did,
-        redundancy: u16,
-    ) -> Result<()> {
-        let key = self.storage_lookup_observation_key(resource, redundancy)?;
-        let mut observations = self
-            .storage_lookup_observations
-            .lock()
-            .map_err(|_| Error::DHTSyncLockError)?;
-        if let Some(observation) = observations.get_mut(&key) {
-            observation.observed_at_ms = storage_lookup_observation_now_ms()
-                .saturating_sub(STORAGE_LOOKUP_OBSERVATION_TTL_MS + 1);
-        }
-        Ok(())
-    }
-
-    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
-    /// Test hook: count retained observation buckets.
-    pub(crate) fn storage_lookup_observation_count(&self) -> Result {
-        let observations = self
-            .storage_lookup_observations
-            .lock()
-            .map_err(|_| Error::DHTSyncLockError)?;
-        Ok(observations.len())
-    }
-
-    fn pending_peers(
-        &self,
-    ) -> Result>>
-    {
-        self.pending_peers
-            .lock()
-            .map_err(|_| Error::SwarmConnectionLifecycleLock)
-    }
-
-    fn active_peers(&self) -> Result>> {
-        self.active_peers
-            .lock()
-            .map_err(|_| Error::SwarmConnectionLifecycleLock)
-    }
-
-    fn get_raw_connection(&self, peer: Did) -> Option {
-        self.transport
-            .connection(&peer.to_string())
-            .map(|conn| SwarmConnection {
-                peer,
-                connection: conn,
-            })
-            .ok()
-    }
-
-    fn is_pending_connection(&self, peer: Did) -> Result {
-        Ok(self.pending_peers()?.contains(peer))
-    }
-
-    /// Return whether `peer` completed a handshake and still owns a logical slot.
-    ///
-    /// Unlike [`Self::is_active_connection`], this remains true while a terminal
-    /// callback removes the peer, so lifecycle cleanup can evict it from the DHT
-    /// even after WebRTC reports `Closed`.
-    pub(crate) fn is_admitted_connection(&self, peer: Did) -> bool {
-        self.active_peers()
-            .map(|active| active.contains(&peer))
-            .unwrap_or(false)
-    }
-
-    /// Return whether `peer` completed its pending handshake and can route traffic.
-    ///
-    /// Data-channel open is the admission boundary. WebRTC may still report a
-    /// transient `Disconnected` state after admission, so only terminal states
-    /// make an admitted peer non-routable before its callback removes the slot.
-    pub(crate) fn is_active_connection(&self, peer: Did) -> bool {
-        self.is_admitted_connection(peer)
-            && self.get_raw_connection(peer).is_some_and(|connection| {
-                !matches!(
-                    connection.webrtc_connection_state(),
-                    WebrtcConnectionState::Failed | WebrtcConnectionState::Closed
-                )
-            })
-    }
-
-    async fn reserve_pending_connection(&self, peer: Did) -> Result {
-        self.expire_pending_connections().await?;
-        if peer == self.dht.did {
-            return Err(Error::ShouldNotConnectSelf);
-        }
-        // A peer keeps its active slot through transient WebRTC state changes
-        // until its terminal callback removes it from the DHT. Do not admit a
-        // second pending handshake for that DID during this interval.
-        if self.is_admitted_connection(peer) {
-            return Err(Error::AlreadyConnected);
-        }
-        self.pending_peers()?.reserve(peer, get_epoch_ms_i64())
-    }
-
-    fn pending_attempt(&self, peer: Did) -> Result> {
-        let pending = self.pending_peers()?;
-        Ok(pending
-            .peers
-            .get(&peer)
-            .map(|pending| PendingConnectionAttempt {
-                peer,
-                generation: pending.generation,
-            }))
-    }
-
-    pub(crate) fn promote_pending_connection(
-        &self,
-        attempt: PendingConnectionAttempt,
-    ) -> Result {
-        let mut pending = self.pending_peers()?;
-        if !pending.remove(attempt) {
-            return Ok(false);
-        }
-        drop(pending);
-        self.active_peers()?.insert(attempt.peer);
-        Ok(true)
-    }
-
-    fn retire_pending_connection(&self, attempt: PendingConnectionAttempt) -> Result {
-        Ok(self.pending_peers()?.remove(attempt))
-    }
-
-    fn retire_active_connection(&self, peer: Did) -> Result {
-        Ok(self.active_peers()?.remove(&peer))
-    }
-
-    /// Cancel a current pending handshake and release its non-routable transport object.
-    pub(crate) async fn cancel_pending_connection(
-        &self,
-        attempt: PendingConnectionAttempt,
-    ) -> Result {
-        if !self.retire_pending_connection(attempt)? {
-            return Ok(false);
-        }
-        self.transport
-            .close_connection(&attempt.peer.to_string())
-            .await
-            .map_err(Error::Transport)?;
-        Ok(true)
-    }
-
-    async fn abandon_pending_connection(&self, attempt: PendingConnectionAttempt, operation: &str) {
-        if let Err(error) = self.cancel_pending_connection(attempt).await {
-            tracing::warn!(
-                "failed to cancel pending connection to {} after {operation}: {error}",
-                attempt.peer
-            );
-        }
-    }
-
-    /// Close pending handshakes whose data channel did not open before the deadline.
-    ///
-    /// These peers have never entered the DHT, so expiry only releases the
-    /// transport object; it deliberately performs no topology mutation.
-    pub(crate) async fn expire_pending_connections(&self) -> Result<()> {
-        let expired = self.pending_peers()?.expire(get_epoch_ms_i64());
-        for attempt in expired {
-            tracing::warn!("pending connection to {} timed out", attempt.peer);
-            self.transport
-                .close_connection(&attempt.peer.to_string())
-                .await
-                .map_err(Error::Transport)?;
-        }
-        Ok(())
-    }
-
-    /// Create a new non-routable transport connection and register its pending attempt.
-    async fn new_pending_connection(
-        &self,
-        attempt: PendingConnectionAttempt,
-        callback: InnerSwarmCallback,
-    ) -> Result<()> {
-        let cid = attempt.peer.to_string();
-        if let Err(error) = self
-            .transport
-            .new_connection(&cid, Box::new(callback))
-            .await
-        {
-            let _ = self.retire_pending_connection(attempt);
-            return Err(Error::Transport(error));
-        }
-        Ok(())
-    }
-
     /// Get an active, routable connection by DID.
     ///
     /// Pending and terminal physical transports are intentionally invisible here.
+    /// Get an active, routable connection by DID.
     pub fn get_connection(&self, peer: Did) -> Option {
         self.is_active_connection(peer)
             .then(|| self.get_raw_connection(peer))
@@ -995,11 +382,6 @@ impl SwarmTransport {
             .collect()
     }
 
-    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
-    pub(crate) fn pending_connection_count(&self) -> Result {
-        Ok(self.pending_peers()?.len())
-    }
-
     /// Disconnect a connection.
     ///
     /// Pending connections are never represented in the DHT, so cancelling one
diff --git a/crates/core/src/swarm/transport/delivery.rs b/crates/core/src/swarm/transport/delivery.rs
new file mode 100644
index 000000000..d2e436e57
--- /dev/null
+++ b/crates/core/src/swarm/transport/delivery.rs
@@ -0,0 +1,155 @@
+use bytes::Bytes;
+use rings_transport::delivery::DeliveryFuture;
+
+use super::SwarmConnection;
+use crate::chunk::Chunk;
+use crate::dht::Did;
+use crate::error::Result;
+use crate::measure::MeasureCounter;
+use crate::measure::MeasureImpl;
+use crate::message::Message;
+use crate::message::MessagePayload;
+use crate::session::SessionSk;
+
+pub(super) async fn record_measurement(
+    measure: Option,
+    did: Did,
+    counter: MeasureCounter,
+) {
+    if let Some(measure) = measure {
+        measure.incr(did, counter).await;
+    }
+}
+
+/// Drive a message's [DeliveryFuture] to completion on the runtime, recording
+/// the eventual peer-quality observation. This keeps delivery tracking confined
+/// to the send site: the status never propagates up through the swarm/node
+/// layers.
+#[cfg(all(feature = "wasm", target_family = "wasm"))]
+pub(super) fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) {
+    wasm_bindgen_futures::spawn_local(async move {
+        match fut.await {
+            Ok(()) => record_measurement(measure, did, MeasureCounter::Sent).await,
+            Err(e) => {
+                tracing::warn!("Message to {did} was not delivered: {e}");
+                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+            }
+        }
+    });
+}
+
+/// Drive a message's [DeliveryFuture] to completion on the runtime, recording
+/// the eventual peer-quality observation.
+#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
+pub(super) fn spawn_delivery(fut: DeliveryFuture, did: Did, measure: Option) {
+    tokio::spawn(async move {
+        match fut.await {
+            Ok(()) => record_measurement(measure, did, MeasureCounter::Sent).await,
+            Err(e) => {
+                tracing::warn!("Message to {did} was not delivered: {e}");
+                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+            }
+        }
+    });
+}
+
+/// Frame one chunk into the bytes a data-channel send carries: wrap it in a `MessagePayload`
+/// addressed to `did` and serialize it. Pure (the only failure is serialization).
+pub(super) fn frame_chunk(session_sk: &SessionSk, did: Did, chunk: Chunk) -> Result {
+    MessagePayload::new_send(Message::Chunk(chunk), session_sk, did, did)?.to_bincode()
+}
+
+/// The *tail* of a chunked message — every chunk after the first — yielded lazily. Boxed so the
+/// background task owns a concrete, nameable type (`Send` off the browser, where spawned tasks must
+/// be `Send`; single-threaded on it).
+#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
+type ChunkTail = Box + Send>;
+#[cfg(all(feature = "wasm", target_family = "wasm"))]
+type ChunkTail = Box>;
+
+/// Drive the *tail* of a chunked send: the first chunk has already been accepted by the caller
+/// (`do_send_payload`), so wait for it to flush (backpressure), then frame, send, and await each
+/// remaining chunk in turn. One chunk is in flight at a time and no per-chunk task is spawned. A
+/// later frame/send failure aborts the rest; the receiver TTL-expires the partial message (chunks
+/// carry the message ttl), so no abort marker is needed. Fire-and-forget — the caller already
+/// learned whether the *first* chunk was accepted, matching the whole-message contract.
+async fn run_chunked_send(
+    conn: SwarmConnection,
+    tail: ChunkTail,
+    first_delivery: DeliveryFuture,
+    session_sk: SessionSk,
+    did: Did,
+    measure: Option,
+) {
+    if let Err(e) = first_delivery.await {
+        tracing::warn!("Chunked send to {did} stopped before the first chunk flushed: {e}");
+        record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+        return;
+    }
+    for chunk in tail {
+        let bytes = match frame_chunk(&session_sk, did, chunk) {
+            Ok(bytes) => bytes,
+            Err(e) => {
+                tracing::warn!("Chunked send to {did} aborted while framing a chunk: {e}");
+                return;
+            }
+        };
+        match conn.send_data(bytes).await {
+            Ok(delivery) => {
+                if let Err(e) = delivery.await {
+                    tracing::warn!("Chunked send to {did} stopped before flush: {e}");
+                    record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+                    return;
+                }
+            }
+            Err(e) => {
+                tracing::warn!("Chunked send to {did} stopped: {e}");
+                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+                return;
+            }
+        }
+    }
+    record_measurement(measure, did, MeasureCounter::Sent).await;
+}
+
+/// Drive the tail of a chunked send on the runtime (one bounded task per large message). See
+/// [`run_chunked_send`].
+#[cfg(all(feature = "wasm", target_family = "wasm"))]
+pub(super) fn spawn_chunked_send(
+    conn: SwarmConnection,
+    tail: ChunkTail,
+    first_delivery: DeliveryFuture,
+    session_sk: SessionSk,
+    did: Did,
+    measure: Option,
+) {
+    wasm_bindgen_futures::spawn_local(run_chunked_send(
+        conn,
+        tail,
+        first_delivery,
+        session_sk,
+        did,
+        measure,
+    ));
+}
+
+/// Drive the tail of a chunked send on the runtime (one bounded task per large message). See
+/// [`run_chunked_send`].
+#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
+pub(super) fn spawn_chunked_send(
+    conn: SwarmConnection,
+    tail: ChunkTail,
+    first_delivery: DeliveryFuture,
+    session_sk: SessionSk,
+    did: Did,
+    measure: Option,
+) {
+    tokio::spawn(run_chunked_send(
+        conn,
+        tail,
+        first_delivery,
+        session_sk,
+        did,
+        measure,
+    ));
+}
diff --git a/crates/core/src/swarm/transport/pending.rs b/crates/core/src/swarm/transport/pending.rs
new file mode 100644
index 000000000..bed59a01a
--- /dev/null
+++ b/crates/core/src/swarm/transport/pending.rs
@@ -0,0 +1,292 @@
+use std::collections::BTreeMap;
+use std::collections::BTreeSet;
+
+use rings_transport::core::transport::TransportInterface;
+use rings_transport::core::transport::WebrtcConnectionState;
+
+use super::SwarmConnection;
+use super::SwarmTransport;
+use crate::dht::Did;
+use crate::error::Error;
+use crate::error::Result;
+use crate::swarm::callback::InnerSwarmCallback;
+use crate::utils::get_epoch_ms_i64;
+
+/// Maximum number of peers that may be handshaking before a data channel opens.
+pub(crate) const DEFAULT_PENDING_CONNECTION_CAPACITY: usize = 32;
+
+pub(super) const PENDING_CONNECTION_TIMEOUT_MS: i64 = 180_000;
+
+/// Identifies one pending handshake for a peer.
+///
+/// A peer can have a replacement handshake after a timeout. Callbacks carry
+/// this token so a late callback from the replaced connection cannot promote
+/// the newer handshake into the active routing set.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) struct PendingConnectionAttempt {
+    pub(super) peer: Did,
+    pub(super) generation: u64,
+}
+
+impl PendingConnectionAttempt {
+    pub(crate) fn peer(self) -> Did {
+        self.peer
+    }
+}
+
+#[derive(Debug)]
+pub(super) struct PendingPeer {
+    generation: u64,
+    admitted_at_ms: i64,
+}
+
+/// Bounded, non-routable handshakes owned by the swarm lifecycle.
+///
+/// The pool deliberately has no DHT reference: a peer is visible to Chord
+/// only after its data channel opens and the matching attempt is promoted.
+pub(super) struct PendingPeerPool {
+    next_generation: u64,
+    peers: BTreeMap,
+}
+
+impl PendingPeerPool {
+    pub(super) fn new() -> Self {
+        Self {
+            next_generation: 0,
+            peers: BTreeMap::new(),
+        }
+    }
+
+    pub(super) fn reserve(&mut self, peer: Did, now_ms: i64) -> Result {
+        if self.peers.contains_key(&peer) {
+            return Err(Error::AlreadyConnected);
+        }
+        if self.peers.len() >= MAX_PENDING {
+            return Err(Error::PendingConnectionCapacityExceeded {
+                capacity: MAX_PENDING,
+            });
+        }
+
+        self.next_generation = self.next_generation.wrapping_add(1);
+        let attempt = PendingConnectionAttempt {
+            peer,
+            generation: self.next_generation,
+        };
+        self.peers.insert(peer, PendingPeer {
+            generation: attempt.generation,
+            admitted_at_ms: now_ms,
+        });
+        Ok(attempt)
+    }
+
+    pub(super) fn contains(&self, peer: Did) -> bool {
+        self.peers.contains_key(&peer)
+    }
+
+    pub(super) fn remove(&mut self, attempt: PendingConnectionAttempt) -> bool {
+        let Some(peer) = self.peers.get(&attempt.peer) else {
+            return false;
+        };
+        if peer.generation != attempt.generation {
+            return false;
+        }
+        self.peers.remove(&attempt.peer);
+        true
+    }
+
+    pub(super) fn expire(&mut self, now_ms: i64) -> Vec {
+        let expired = self
+            .peers
+            .iter()
+            .filter_map(|(peer, pending)| {
+                (now_ms.saturating_sub(pending.admitted_at_ms) >= PENDING_CONNECTION_TIMEOUT_MS)
+                    .then_some(PendingConnectionAttempt {
+                        peer: *peer,
+                        generation: pending.generation,
+                    })
+            })
+            .collect::>();
+        for attempt in &expired {
+            self.peers.remove(&attempt.peer);
+        }
+        expired
+    }
+
+    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
+    pub(super) fn len(&self) -> usize {
+        self.peers.len()
+    }
+}
+
+impl SwarmTransport {
+    fn pending_peers(
+        &self,
+    ) -> Result>>
+    {
+        self.pending_peers
+            .lock()
+            .map_err(|_| Error::SwarmConnectionLifecycleLock)
+    }
+
+    pub(super) fn active_peers(&self) -> Result>> {
+        self.active_peers
+            .lock()
+            .map_err(|_| Error::SwarmConnectionLifecycleLock)
+    }
+
+    pub(super) fn get_raw_connection(&self, peer: Did) -> Option {
+        self.transport
+            .connection(&peer.to_string())
+            .map(|conn| SwarmConnection {
+                peer,
+                connection: conn,
+            })
+            .ok()
+    }
+
+    pub(super) fn is_pending_connection(&self, peer: Did) -> Result {
+        Ok(self.pending_peers()?.contains(peer))
+    }
+
+    /// Return whether `peer` completed a handshake and still owns a logical slot.
+    ///
+    /// Unlike [`Self::is_active_connection`], this remains true while a terminal
+    /// callback removes the peer, so lifecycle cleanup can evict it from the DHT
+    /// even after WebRTC reports `Closed`.
+    pub(crate) fn is_admitted_connection(&self, peer: Did) -> bool {
+        self.active_peers()
+            .map(|active| active.contains(&peer))
+            .unwrap_or(false)
+    }
+
+    /// Return whether `peer` completed its pending handshake and can route traffic.
+    ///
+    /// Data-channel open is the admission boundary. WebRTC may still report a
+    /// transient `Disconnected` state after admission, so only terminal states
+    /// make an admitted peer non-routable before its callback removes the slot.
+    pub(crate) fn is_active_connection(&self, peer: Did) -> bool {
+        self.is_admitted_connection(peer)
+            && self.get_raw_connection(peer).is_some_and(|connection| {
+                !matches!(
+                    connection.webrtc_connection_state(),
+                    WebrtcConnectionState::Failed | WebrtcConnectionState::Closed
+                )
+            })
+    }
+
+    pub(super) async fn reserve_pending_connection(
+        &self,
+        peer: Did,
+    ) -> Result {
+        self.expire_pending_connections().await?;
+        if peer == self.dht.did {
+            return Err(Error::ShouldNotConnectSelf);
+        }
+        // A peer keeps its active slot through transient WebRTC state changes
+        // until its terminal callback removes it from the DHT. Do not admit a
+        // second pending handshake for that DID during this interval.
+        if self.is_admitted_connection(peer) {
+            return Err(Error::AlreadyConnected);
+        }
+        self.pending_peers()?.reserve(peer, get_epoch_ms_i64())
+    }
+
+    pub(super) fn pending_attempt(&self, peer: Did) -> Result> {
+        let pending = self.pending_peers()?;
+        Ok(pending
+            .peers
+            .get(&peer)
+            .map(|pending| PendingConnectionAttempt {
+                peer,
+                generation: pending.generation,
+            }))
+    }
+
+    pub(crate) fn promote_pending_connection(
+        &self,
+        attempt: PendingConnectionAttempt,
+    ) -> Result {
+        let mut pending = self.pending_peers()?;
+        if !pending.remove(attempt) {
+            return Ok(false);
+        }
+        drop(pending);
+        self.active_peers()?.insert(attempt.peer);
+        Ok(true)
+    }
+
+    fn retire_pending_connection(&self, attempt: PendingConnectionAttempt) -> Result {
+        Ok(self.pending_peers()?.remove(attempt))
+    }
+
+    pub(super) fn retire_active_connection(&self, peer: Did) -> Result {
+        Ok(self.active_peers()?.remove(&peer))
+    }
+
+    /// Cancel a current pending handshake and release its non-routable transport object.
+    pub(crate) async fn cancel_pending_connection(
+        &self,
+        attempt: PendingConnectionAttempt,
+    ) -> Result {
+        if !self.retire_pending_connection(attempt)? {
+            return Ok(false);
+        }
+        self.transport
+            .close_connection(&attempt.peer.to_string())
+            .await
+            .map_err(Error::Transport)?;
+        Ok(true)
+    }
+
+    pub(super) async fn abandon_pending_connection(
+        &self,
+        attempt: PendingConnectionAttempt,
+        operation: &str,
+    ) {
+        if let Err(error) = self.cancel_pending_connection(attempt).await {
+            tracing::warn!(
+                "failed to cancel pending connection to {} after {operation}: {error}",
+                attempt.peer
+            );
+        }
+    }
+
+    /// Close pending handshakes whose data channel did not open before the deadline.
+    ///
+    /// These peers have never entered the DHT, so expiry only releases the
+    /// transport object; it deliberately performs no topology mutation.
+    pub(crate) async fn expire_pending_connections(&self) -> Result<()> {
+        let expired = self.pending_peers()?.expire(get_epoch_ms_i64());
+        for attempt in expired {
+            tracing::warn!("pending connection to {} timed out", attempt.peer);
+            self.transport
+                .close_connection(&attempt.peer.to_string())
+                .await
+                .map_err(Error::Transport)?;
+        }
+        Ok(())
+    }
+
+    /// Create a new non-routable transport connection and register its pending attempt.
+    pub(super) async fn new_pending_connection(
+        &self,
+        attempt: PendingConnectionAttempt,
+        callback: InnerSwarmCallback,
+    ) -> Result<()> {
+        let cid = attempt.peer.to_string();
+        if let Err(error) = self
+            .transport
+            .new_connection(&cid, Box::new(callback))
+            .await
+        {
+            let _ = self.retire_pending_connection(attempt);
+            return Err(Error::Transport(error));
+        }
+        Ok(())
+    }
+
+    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
+    pub(crate) fn pending_connection_count(&self) -> Result {
+        Ok(self.pending_peers()?.len())
+    }
+}
diff --git a/crates/core/src/swarm/transport/storage_lookup.rs b/crates/core/src/swarm/transport/storage_lookup.rs
new file mode 100644
index 000000000..960c41b86
--- /dev/null
+++ b/crates/core/src/swarm/transport/storage_lookup.rs
@@ -0,0 +1,231 @@
+use std::collections::BTreeMap;
+use std::collections::BTreeSet;
+
+use super::SwarmTransport;
+use crate::dht::entry::PlacementMiss;
+use crate::dht::Did;
+use crate::error::Error;
+use crate::error::Result;
+use crate::utils::get_epoch_ms_i64;
+
+const STORAGE_LOOKUP_OBSERVATION_TTL_MS: i64 = 30_000;
+/// Maximum number of read-repair miss observation buckets retained per transport.
+pub(crate) const STORAGE_LOOKUP_OBSERVATION_CAPACITY: usize = 1024;
+
+// Invariant: after every successful observation-buffer mutation,
+// observations.len() <= STORAGE_LOOKUP_OBSERVATION_CAPACITY.
+// Invariant: after evict_storage_lookup_observations(observations, now), every
+// retained bucket satisfies
+// now.saturating_sub(observed_at_ms) <= STORAGE_LOOKUP_OBSERVATION_TTL_MS. This
+// is the freshness witness required before PlacementMiss.owner drives read-repair.
+pub(super) type StorageLookupObservationMap =
+    BTreeMap;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
+pub(super) struct StorageLookupObservationKey {
+    resource: Did,
+    redundancy: u16,
+}
+
+pub(super) struct StorageLookupObservation {
+    observed_at_ms: i64,
+    misses: BTreeSet,
+}
+
+fn storage_lookup_observation_now_ms() -> i64 {
+    get_epoch_ms_i64()
+}
+
+fn oldest_storage_lookup_observation_key(
+    observations: &StorageLookupObservationMap,
+) -> Option {
+    observations
+        .iter()
+        .min_by_key(|(key, observation)| (observation.observed_at_ms, **key))
+        .map(|(key, _)| *key)
+}
+
+// Post: observations.len() <= STORAGE_LOOKUP_OBSERVATION_CAPACITY.
+// Post: forall bucket in observations,
+// now_ms.saturating_sub(bucket.observed_at_ms) <= STORAGE_LOOKUP_OBSERVATION_TTL_MS.
+// Preservation: removing expired buckets and then oldest buckets cannot create
+// a stale bucket or increase the number of buckets.
+fn evict_storage_lookup_observations(observations: &mut StorageLookupObservationMap, now_ms: i64) {
+    observations.retain(|_, observation| {
+        now_ms.saturating_sub(observation.observed_at_ms) <= STORAGE_LOOKUP_OBSERVATION_TTL_MS
+    });
+
+    while observations.len() > STORAGE_LOOKUP_OBSERVATION_CAPACITY {
+        let Some(stale_key) = oldest_storage_lookup_observation_key(observations) else {
+            break;
+        };
+        observations.remove(&stale_key);
+    }
+}
+
+fn reserve_storage_lookup_observation_slot(observations: &mut StorageLookupObservationMap) {
+    while observations.len() >= STORAGE_LOOKUP_OBSERVATION_CAPACITY {
+        let Some(stale_key) = oldest_storage_lookup_observation_key(observations) else {
+            break;
+        };
+        observations.remove(&stale_key);
+    }
+}
+
+impl SwarmTransport {
+    fn storage_lookup_observation_key(
+        &self,
+        resource: Did,
+        redundancy: u16,
+    ) -> Result {
+        self.ensure_storage_redundancy_value(redundancy)?;
+        Ok(StorageLookupObservationKey {
+            resource,
+            redundancy,
+        })
+    }
+
+    /// Start a fresh lookup round for `resource`.
+    ///
+    /// This replaces any previous miss observations for the same resource and
+    /// redundancy with an empty local-authorized bucket. Inbound FoundEntry
+    /// messages may only add misses to an existing bucket, so remote peers cannot
+    /// create a new redundancy mode.
+    ///
+    /// Post: if capacity permits one active lookup, a bucket exists for
+    /// `(resource, redundancy)` and contains no misses.
+    /// Preservation: eviction establishes the capacity and freshness invariants
+    /// before replacing the lookup-round bucket.
+    pub(crate) fn start_storage_lookup(&self, resource: Did, redundancy: u16) -> Result<()> {
+        let key = self.storage_lookup_observation_key(resource, redundancy)?;
+        let mut observations = self
+            .storage_lookup_observations
+            .lock()
+            .map_err(|_| Error::DHTSyncLockError)?;
+        let now = storage_lookup_observation_now_ms();
+        evict_storage_lookup_observations(&mut observations, now);
+        reserve_storage_lookup_observation_slot(&mut observations);
+        observations.insert(key, StorageLookupObservation {
+            observed_at_ms: now,
+            misses: BTreeSet::new(),
+        });
+        Ok(())
+    }
+
+    /// Validate that a storage lookup response belongs to a local lookup round.
+    ///
+    /// Post: `Ok(())` proves a fresh bucket exists for `(resource, redundancy)`.
+    pub(crate) fn ensure_storage_lookup_active(
+        &self,
+        resource: Did,
+        redundancy: u16,
+    ) -> Result<()> {
+        let key = self.storage_lookup_observation_key(resource, redundancy)?;
+        let mut observations = self
+            .storage_lookup_observations
+            .lock()
+            .map_err(|_| Error::DHTSyncLockError)?;
+        let now = storage_lookup_observation_now_ms();
+        evict_storage_lookup_observations(&mut observations, now);
+        if observations.contains_key(&key) {
+            Ok(())
+        } else {
+            Err(Error::InvalidMessage(
+                "storage lookup response has no active local lookup".to_string(),
+            ))
+        }
+    }
+
+    /// Buffer placement misses observed by an in-flight storage lookup.
+    ///
+    /// Post: retained observation buckets satisfy the capacity and freshness
+    /// invariants.
+    /// Post: the supplied misses are appended only to a bucket previously created
+    /// by [`Self::start_storage_lookup`].
+    pub(crate) fn observe_storage_misses(
+        &self,
+        resource: Did,
+        redundancy: u16,
+        misses: impl IntoIterator,
+    ) -> Result<()> {
+        let key = self.storage_lookup_observation_key(resource, redundancy)?;
+        let mut misses = misses.into_iter().peekable();
+        if misses.peek().is_none() {
+            return Ok(());
+        }
+        let mut observations = self
+            .storage_lookup_observations
+            .lock()
+            .map_err(|_| Error::DHTSyncLockError)?;
+        let now = storage_lookup_observation_now_ms();
+        evict_storage_lookup_observations(&mut observations, now);
+        let Some(observation) = observations.get_mut(&key) else {
+            return Err(Error::InvalidMessage(
+                "storage miss observation has no active local lookup".to_string(),
+            ));
+        };
+        observation.observed_at_ms = now;
+        observation.misses.extend(misses);
+        evict_storage_lookup_observations(&mut observations, now);
+        Ok(())
+    }
+
+    /// Drain fresh miss observations for a found entry.
+    ///
+    /// Post: returned misses come only from a bucket that survived freshness
+    /// eviction at this call's observation time.
+    /// Post: the bucket remains active with no buffered misses until TTL or a new
+    /// lookup round removes it.
+    /// Preservation: eviction before drain prevents stale owners from driving
+    /// late read-repair.
+    pub(crate) fn take_storage_misses(
+        &self,
+        resource: Did,
+        redundancy: u16,
+    ) -> Result> {
+        let key = self.storage_lookup_observation_key(resource, redundancy)?;
+        let mut observations = self
+            .storage_lookup_observations
+            .lock()
+            .map_err(|_| Error::DHTSyncLockError)?;
+        let now = storage_lookup_observation_now_ms();
+        evict_storage_lookup_observations(&mut observations, now);
+        let Some(observation) = observations.get_mut(&key) else {
+            return Err(Error::InvalidMessage(
+                "storage repair has no active local lookup".to_string(),
+            ));
+        };
+        Ok(std::mem::take(&mut observation.misses)
+            .into_iter()
+            .collect())
+    }
+
+    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
+    /// Test hook: make one observation bucket older than the freshness TTL.
+    pub(crate) fn expire_storage_lookup_observation(
+        &self,
+        resource: Did,
+        redundancy: u16,
+    ) -> Result<()> {
+        let key = self.storage_lookup_observation_key(resource, redundancy)?;
+        let mut observations = self
+            .storage_lookup_observations
+            .lock()
+            .map_err(|_| Error::DHTSyncLockError)?;
+        if let Some(observation) = observations.get_mut(&key) {
+            observation.observed_at_ms = storage_lookup_observation_now_ms()
+                .saturating_sub(STORAGE_LOOKUP_OBSERVATION_TTL_MS + 1);
+        }
+        Ok(())
+    }
+
+    #[cfg(all(test, not(all(feature = "wasm", target_family = "wasm"))))]
+    /// Test hook: count retained observation buckets.
+    pub(crate) fn storage_lookup_observation_count(&self) -> Result {
+        let observations = self
+            .storage_lookup_observations
+            .lock()
+            .map_err(|_| Error::DHTSyncLockError)?;
+        Ok(observations.len())
+    }
+}
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index 6baeed548..0d6c2007c 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -343,14 +343,11 @@ async fn disconnected_observation_is_once_per_connection_epoch() -> Result<()> {
     transport.record_peer_disconnected(peer).await;
     assert!(transport.peer_disconnected_since_ms(peer).is_some());
 
-    assert_eq!(
-        measure.snapshot_counters()?.as_slice(),
-        &[
-            (peer, MeasureCounter::Disconnected),
-            (peer, MeasureCounter::Connect),
-            (peer, MeasureCounter::Disconnected),
-        ]
-    );
+    assert_eq!(measure.snapshot_counters()?.as_slice(), &[
+        (peer, MeasureCounter::Disconnected),
+        (peer, MeasureCounter::Connect),
+        (peer, MeasureCounter::Disconnected),
+    ]);
 
     Ok(())
 }
diff --git a/crates/core/src/tests/default/test_dht_stateright.rs b/crates/core/src/tests/default/test_dht_stateright.rs
index 4e9278558..00b54ccbd 100644
--- a/crates/core/src/tests/default/test_dht_stateright.rs
+++ b/crates/core/src/tests/default/test_dht_stateright.rs
@@ -35,7 +35,6 @@
 use std::borrow::Cow;
 use std::collections::BTreeSet;
 use std::hash::Hash;
-use std::hash::Hasher;
 
 use num_bigint::BigUint;
 use stateright::actor::model_timeout;
@@ -51,19 +50,11 @@ use stateright::Model;
 
 use super::test_dht_convergence::spec;
 use super::test_dht_convergence::K;
-use crate::algebra::JoinSemilattice;
-use crate::consts::ENTRY_DATA_MAX_LEN;
-use crate::dht::entry::Entry;
-use crate::dht::entry::EntryCrdt;
-use crate::dht::entry::EntryDot;
-use crate::dht::entry::EntryKind;
-use crate::dht::entry::EntryVersion;
 use crate::dht::successor::SuccessorReader;
 use crate::dht::successor::SuccessorWriter;
 use crate::dht::Chord;
 use crate::dht::Did;
 use crate::dht::PeerRing;
-use crate::message::Encoded;
 use crate::storage::MemStorage;
 
 /// A DID at `num/den` of the way round the ring — deterministic test positions.
@@ -544,592 +535,11 @@ fn discovery_model(all: Vec, rounds: u8) -> ActorModel bool {
-        if from == to {
-            return false;
-        }
-        self.side(from) == self.side(to)
-    }
-
-    fn side(self, node: usize) -> bool {
-        let shift = match u32::try_from(node) {
-            Ok(shift) => shift,
-            Err(_) => return false,
-        };
-        let Some(bit) = 1u8.checked_shl(shift) else {
-            return false;
-        };
-        self.0 & bit != 0
-    }
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
-enum StorageJoinCarrier {
-    DataBoundedTopN,
-    DataOverwriteReset,
-    RelayTombstone,
-}
-
-#[derive(Clone, Debug)]
-struct StorageJoinValue {
-    carrier: StorageJoinCarrier,
-    bits: u8,
-    entry: Entry,
-}
-
-impl StorageJoinValue {
-    fn new(carrier: StorageJoinCarrier, bits: u8, entry: Entry) -> Self {
-        match entry.try_into_storage_entry() {
-            Ok(entry) => Self {
-                carrier,
-                bits,
-                entry,
-            },
-            Err(error) => panic!("storage model entry must normalize: {error}"),
-        }
-    }
-
-    fn bottom_like(&self) -> Self {
-        storage_value_from_bits(self.carrier, 0)
-    }
-}
-
-impl PartialEq for StorageJoinValue {
-    fn eq(&self, other: &Self) -> bool {
-        self.carrier == other.carrier && self.bits == other.bits
-    }
-}
-
-impl Eq for StorageJoinValue {}
-
-impl Hash for StorageJoinValue {
-    fn hash(&self, state: &mut H) {
-        self.carrier.hash(state);
-        self.bits.hash(state);
-    }
-}
-
-impl Ord for StorageJoinValue {
-    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
-        self.carrier
-            .cmp(&other.carrier)
-            .then_with(|| self.bits.cmp(&other.bits))
-    }
-}
-
-impl PartialOrd for StorageJoinValue {
-    fn partial_cmp(&self, other: &Self) -> Option {
-        Some(self.cmp(other))
-    }
-}
-
-impl JoinSemilattice for StorageJoinValue {
-    fn join(self, other: Self) -> Self {
-        if self.carrier != other.carrier {
-            panic!("storage model joins only one carrier");
-        }
-        let carrier = self.carrier;
-        let bits = self.bits | other.bits;
-        let joined = storage_join_entry(self.entry, other.entry);
-        Self::new(carrier, bits, joined)
-    }
-}
-
-struct StorageJoinScenario {
-    name: &'static str,
-    initial: [StorageJoinValue; STORAGE_REPLICA_COUNT],
-}
-
-impl StorageJoinScenario {
-    fn bottom(&self) -> StorageJoinValue {
-        self.initial[0].bottom_like()
-    }
-
-    fn global_lub(&self) -> StorageJoinValue {
-        self.initial
-            .iter()
-            .cloned()
-            .fold(self.bottom(), JoinSemilattice::join)
-    }
-}
-
-fn storage_model_did(offset: u32) -> Did {
-    Did::from(10_000u32.saturating_add(offset))
-}
-
-fn storage_version(time: u128, actor: u32, operation: u32) -> EntryVersion {
-    EntryVersion::new(time, Did::from(actor), Did::from(operation))
-}
-
-fn storage_index(index: usize) -> u32 {
-    match u32::try_from(index) {
-        Ok(index) => index,
-        Err(_) => panic!("storage model index must fit in u32"),
-    }
-}
-
-fn storage_dot(version: EntryVersion, index: usize) -> EntryDot {
-    let index = storage_index(index);
-    EntryDot { version, index }
-}
-
-fn storage_encoded(label: &str) -> Encoded {
-    Encoded::from(label)
-}
-
-fn storage_join_entry(left: Entry, right: Entry) -> Entry {
-    let joined = match left.join(right) {
-        Ok(entry) => entry,
-        Err(error) => panic!("storage model joins only compatible entries: {error}"),
-    };
-    match joined.try_into_storage_entry() {
-        Ok(entry) => entry,
-        Err(error) => panic!("storage model join result must normalize: {error}"),
-    }
-}
-
-fn data_value_range(did: Did, label: &'static str, start_time: u128, count: usize) -> Entry {
-    let data = (0..count)
-        .map(|index| storage_encoded(&format!("{label}-{index}")))
-        .collect::>();
-    let dots = (0..count)
-        .map(|offset| {
-            let index = storage_index(offset);
-            let time = start_time.saturating_add(u128::from(index));
-            storage_dot(
-                storage_version(time, 1, 1_000u32.saturating_add(index)),
-                offset,
-            )
-        })
-        .collect::>();
-    Entry {
-        did,
-        data,
-        kind: EntryKind::Data,
-        crdt: EntryCrdt {
-            register: None,
-            dots,
-            tombstones: Vec::new(),
-        },
-    }
-}
-
-fn data_overwrite_value(did: Did, label: &'static str, version: EntryVersion) -> Entry {
-    Entry {
-        did,
-        data: vec![storage_encoded(label)],
-        kind: EntryKind::Data,
-        crdt: EntryCrdt {
-            register: Some(version),
-            dots: vec![storage_dot(version, 0)],
-            tombstones: Vec::new(),
-        },
-    }
-}
-
-fn relay_add_value(did: Did, label: &'static str, dot: EntryDot) -> Entry {
-    Entry {
-        did,
-        data: vec![storage_encoded(label)],
-        kind: EntryKind::RelayMessage,
-        crdt: EntryCrdt {
-            register: None,
-            dots: vec![dot],
-            tombstones: Vec::new(),
-        },
-    }
-}
-
-fn relay_remove_value(did: Did, dot: EntryDot) -> Entry {
-    Entry {
-        did,
-        data: Vec::new(),
-        kind: EntryKind::RelayMessage,
-        crdt: EntryCrdt {
-            register: None,
-            dots: Vec::new(),
-            tombstones: vec![dot],
-        },
-    }
-}
-
-fn storage_delta_entry(carrier: StorageJoinCarrier, bit: u8) -> Entry {
-    match carrier {
-        StorageJoinCarrier::DataBoundedTopN => data_value_range(
-            storage_model_did(1),
-            match bit {
-                0b001 => "low",
-                0b010 => "mid",
-                0b100 => "high",
-                _ => panic!("storage model delta bit must be singleton"),
-            },
-            match bit {
-                0b001 => 1,
-                0b010 => 1_000,
-                0b100 => 2_000,
-                _ => panic!("storage model delta bit must be singleton"),
-            },
-            ENTRY_DATA_MAX_LEN,
-        ),
-        StorageJoinCarrier::DataOverwriteReset => match bit {
-            0b001 => data_value_range(storage_model_did(2), "stale-a", 1, 3),
-            0b010 => {
-                data_overwrite_value(storage_model_did(2), "reset", storage_version(100, 2, 200))
-            }
-            0b100 => data_value_range(storage_model_did(2), "stale-c", 10, 3),
-            _ => panic!("storage model delta bit must be singleton"),
-        },
-        StorageJoinCarrier::RelayTombstone => {
-            let relay_a_dot = storage_dot(storage_version(1, 1, 10), 0);
-            let relay_b_dot = storage_dot(storage_version(2, 2, 20), 0);
-            match bit {
-                0b001 => relay_add_value(storage_model_did(3), "relay-a", relay_a_dot),
-                0b010 => relay_add_value(storage_model_did(3), "relay-b", relay_b_dot),
-                0b100 => relay_remove_value(storage_model_did(3), relay_a_dot),
-                _ => panic!("storage model delta bit must be singleton"),
-            }
-        }
-    }
-}
-
-fn storage_bottom_entry(carrier: StorageJoinCarrier) -> Entry {
-    let (did, kind) = match carrier {
-        StorageJoinCarrier::DataBoundedTopN => (storage_model_did(1), EntryKind::Data),
-        StorageJoinCarrier::DataOverwriteReset => (storage_model_did(2), EntryKind::Data),
-        StorageJoinCarrier::RelayTombstone => (storage_model_did(3), EntryKind::RelayMessage),
-    };
-    Entry::new(did, Vec::new(), kind)
-}
-
-fn storage_value_from_bits(carrier: StorageJoinCarrier, bits: u8) -> StorageJoinValue {
-    let mut entry = storage_bottom_entry(carrier);
-    for bit in [0b001, 0b010, 0b100] {
-        if bits & bit != 0 {
-            entry = storage_join_entry(entry, storage_delta_entry(carrier, bit));
-        }
-    }
-    StorageJoinValue::new(carrier, bits, entry)
-}
-
-fn storage_join_scenarios() -> Vec {
-    vec![
-        StorageJoinScenario {
-            name: "data bounded top-n",
-            initial: [
-                storage_value_from_bits(StorageJoinCarrier::DataBoundedTopN, 0b001),
-                storage_value_from_bits(StorageJoinCarrier::DataBoundedTopN, 0b010),
-                storage_value_from_bits(StorageJoinCarrier::DataBoundedTopN, 0b100),
-            ],
-        },
-        StorageJoinScenario {
-            name: "data overwrite reset floor",
-            initial: [
-                storage_value_from_bits(StorageJoinCarrier::DataOverwriteReset, 0b001),
-                storage_value_from_bits(StorageJoinCarrier::DataOverwriteReset, 0b010),
-                storage_value_from_bits(StorageJoinCarrier::DataOverwriteReset, 0b100),
-            ],
-        },
-        StorageJoinScenario {
-            name: "relay tombstone prevents resurrection",
-            initial: [
-                storage_value_from_bits(StorageJoinCarrier::RelayTombstone, 0b001),
-                storage_value_from_bits(StorageJoinCarrier::RelayTombstone, 0b010),
-                storage_value_from_bits(StorageJoinCarrier::RelayTombstone, 0b100),
-            ],
-        },
-    ]
-}
-
-fn storage_join_carriers() -> [StorageJoinCarrier; 3] {
-    [
-        StorageJoinCarrier::DataBoundedTopN,
-        StorageJoinCarrier::DataOverwriteReset,
-        StorageJoinCarrier::RelayTombstone,
-    ]
-}
-
-fn storage_value_by_bits(values: &[StorageJoinValue], bits: u8) -> &StorageJoinValue {
-    match values.get(usize::from(bits)) {
-        Some(value) => value,
-        None => panic!("storage model bitmask must be in the finite carrier"),
-    }
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
-enum StorageJoinPhase {
-    Partitioned,
-    Merged,
-}
-
-#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
-struct StorageJoinState {
-    partition: StoragePartition,
-    phase: StorageJoinPhase,
-    replicas: [StorageJoinValue; STORAGE_REPLICA_COUNT],
-}
-
-impl StorageJoinState {
-    fn initial(
-        partition: StoragePartition,
-        replicas: [StorageJoinValue; STORAGE_REPLICA_COUNT],
-    ) -> Self {
-        Self {
-            partition,
-            phase: StorageJoinPhase::Partitioned,
-            replicas,
-        }
-    }
-
-    fn topology_permits(&self, from: usize, to: usize) -> bool {
-        if from == to {
-            return false;
-        }
-        match self.phase {
-            StorageJoinPhase::Partitioned => self.partition.permits(from, to),
-            StorageJoinPhase::Merged => from < STORAGE_REPLICA_COUNT && to < STORAGE_REPLICA_COUNT,
-        }
-    }
-
-    fn transfer_current(&self, from: usize, to: usize) -> Option {
-        if !self.topology_permits(from, to) {
-            return None;
-        }
-        let value = self.replicas.get(from).cloned()?;
-        let mut next = self.clone();
-        let replica = next.replicas.get_mut(to)?;
-        *replica = replica.clone().join(value);
-        Some(next)
-    }
-
-    fn merge_partition(&self) -> Option {
-        if self.phase == StorageJoinPhase::Merged {
-            return None;
-        }
-        Some(Self {
-            phase: StorageJoinPhase::Merged,
-            ..self.clone()
-        })
-    }
-
-    fn successors(&self) -> Vec {
-        let mut next = Vec::new();
-        if let Some(merged) = self.merge_partition() {
-            next.push(merged);
-        }
-        for from in 0..STORAGE_REPLICA_COUNT {
-            for to in 0..STORAGE_REPLICA_COUNT {
-                if let Some(transferred) = self.transfer_current(from, to) {
-                    next.push(transferred);
-                }
-            }
-        }
-        next
-    }
-
-    fn is_quiescent_lub(&self, global_lub: &StorageJoinValue) -> bool {
-        self.replicas.iter().all(|value| value == global_lub)
-    }
-
-    fn transfer_all_current(&self) -> Self {
-        let mut state = self.clone();
-        for from in 0..STORAGE_REPLICA_COUNT {
-            for to in 0..STORAGE_REPLICA_COUNT {
-                if let Some(next) = state.transfer_current(from, to) {
-                    state = next;
-                }
-            }
-        }
-        state
-    }
-
-    fn drive_to_quiescent_lub(&self, global_lub: &StorageJoinValue) -> Self {
-        let mut state = self.clone();
-        for _ in 0..STORAGE_REPLICA_COUNT * 8 {
-            if state.is_quiescent_lub(global_lub) {
-                return state;
-            }
-            let next = state.transfer_all_current();
-            if next == state {
-                return next;
-            }
-            state = next;
-        }
-        state
-    }
-}
-
-fn reachable_storage_join_states(
-    partition: StoragePartition,
-    replicas: [StorageJoinValue; STORAGE_REPLICA_COUNT],
-) -> BTreeSet {
-    let mut seen = BTreeSet::new();
-    let mut frontier = vec![StorageJoinState::initial(partition, replicas)];
-    while let Some(state) = frontier.pop() {
-        if !seen.insert(state.clone()) {
-            continue;
-        }
-        for next in state.successors() {
-            if !seen.contains(&next) {
-                frontier.push(next);
-            }
-        }
-    }
-    seen
-}
-
-// ===================================================================
-// Stage 4: storage hand-off cleanup safety for one placement key.
-//
-// SCOPE: this is the #614 S2' cleanup model, not the storage convergence
-// theorem. Convergence is Stage 3's join-semilattice fact. This stage abstracts
-// exactly one placement key, the copy -> ack -> delete hand-off, and arbitrary
-// local writes over a finite representative value domain while a copy or ack is
-// in flight:
-//
-//   local(v) --SendCopy(v)--> copy_in_flight(v)
-//   copy_in_flight(v) --DeliverCopy--> successor(v) + ack_in_flight(v)
-//   local(v) --LocalWrite(w)--> local(w)
-//   ack_in_flight(v) --DeliverAckDelete--> delete local only if local == v
-//
-// Property checked below:
-//
-//   Always S2': local(k) is removed only if successor(k) contains the same
-//   value at the moment of removal.
-// ===================================================================
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
-enum StorageSyncStep {
-    SendCopy,
-    DeliverCopy,
-    LocalWrite(StorageValue),
-    DeliverAckDelete,
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
-enum StorageValue {
-    V0,
-    V1,
-    V2,
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
-struct StorageSyncState {
-    local: Option,
-    successor: Option,
-    copy_in_flight: Option,
-    ack_in_flight: Option,
-}
-
-impl StorageSyncState {
-    fn initial() -> Self {
-        Self {
-            local: Some(StorageValue::V0),
-            successor: None,
-            copy_in_flight: None,
-            ack_in_flight: None,
-        }
-    }
-
-    fn step(self, step: StorageSyncStep) -> Option {
-        match step {
-            StorageSyncStep::SendCopy => Some(Self {
-                copy_in_flight: Some(self.local?),
-                ..self
-            }),
-            StorageSyncStep::DeliverCopy => {
-                let copied = self.copy_in_flight?;
-                Some(Self {
-                    successor: Some(copied),
-                    copy_in_flight: None,
-                    ack_in_flight: Some(copied),
-                    ..self
-                })
-            }
-            StorageSyncStep::LocalWrite(value)
-                if self.copy_in_flight.is_some() || self.ack_in_flight.is_some() =>
-            {
-                Some(Self {
-                    local: Some(value),
-                    ..self
-                })
-            }
-            StorageSyncStep::DeliverAckDelete => {
-                let acked = self.ack_in_flight?;
-                let local = match self.local {
-                    Some(current) if current == acked => None,
-                    current => current,
-                };
-                Some(Self {
-                    local,
-                    ack_in_flight: None,
-                    ..self
-                })
-            }
-            _ => None,
-        }
-    }
-
-    fn removed_local_value(self, next: Self) -> Option {
-        match (self.local, next.local) {
-            (Some(removed), None) => Some(removed),
-            _ => None,
-        }
-    }
-}
+mod storage_model;
 
 #[cfg(test)]
 mod tests {
+    use super::storage_model::*;
     use super::*;
 
     /// Build a fully-converged DHT for `node` (the production join/notify path).
diff --git a/crates/core/src/tests/default/test_dht_stateright/storage_model.rs b/crates/core/src/tests/default/test_dht_stateright/storage_model.rs
new file mode 100644
index 000000000..92a567730
--- /dev/null
+++ b/crates/core/src/tests/default/test_dht_stateright/storage_model.rs
@@ -0,0 +1,597 @@
+use std::collections::BTreeSet;
+use std::hash::Hash;
+use std::hash::Hasher;
+
+use crate::algebra::JoinSemilattice;
+use crate::consts::ENTRY_DATA_MAX_LEN;
+use crate::dht::entry::Entry;
+use crate::dht::entry::EntryCrdt;
+use crate::dht::entry::EntryDot;
+use crate::dht::entry::EntryKind;
+use crate::dht::entry::EntryVersion;
+use crate::dht::Did;
+use crate::message::Encoded;
+
+// ===================================================================
+// Stage 3: storage CRDT SEC topology model.
+//
+// State variables:
+//   phase    in {Partitioned, Merged}
+//   replica  in StorageJoinValue^3
+//
+// Initial state:
+//   replicas start with independent local writes A, B, C.
+//   phase = Partitioned, where only same-side nodes may exchange state.
+//
+// Next-state relation:
+//   Transfer(from, to) applies replica[to] := replica[to] join replica[from]
+//   whenever the topology allows that edge.
+//   Merge changes phase from Partitioned to Merged, enabling every edge.
+//
+// Carrier safety:
+//   `storage_entry_join_satisfies_semilattice_laws` proves the real Entry
+//   carriers are join-semilattices over this finite domain. This topology
+//   model therefore does not duplicate the carrier <= LUB invariant; its
+//   distinct obligation is the liveness/closure step below.
+//
+// Liveness expectation under fair anti-entropy:
+//   from any reachable Merged state, repeated Transfer steps reach the single
+//   least upper bound at every replica.
+//
+// Refinement:
+//   An asynchronous send/deliver trace projects to this Transfer model because
+//   delivery is a pure join of a sender snapshot into the receiver. Message
+//   reordering and duplication are covered by the semilattice law checked
+//   below: join is commutative and idempotent.
+//
+// Quotient:
+//   `StorageJoinValue` hashes and compares only `(carrier, bits)` so BFS stays
+//   finite. The test `storage_entry_join_satisfies_semilattice_laws` is the
+//   refinement witness: for every finite carrier state, real Entry::join equals
+//   canonical(bits_a union bits_b). The topology model is therefore checked on
+//   the quotient, while carrier correctness is checked on the real entries.
+// ===================================================================
+
+pub(super) const STORAGE_REPLICA_COUNT: usize = 3;
+pub(super) const STORAGE_PARTITION_MASKS: [StoragePartition; STORAGE_REPLICA_COUNT] = [
+    StoragePartition(0b001),
+    StoragePartition(0b010),
+    StoragePartition(0b011),
+];
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub(super) struct StoragePartition(u8);
+
+impl StoragePartition {
+    fn permits(self, from: usize, to: usize) -> bool {
+        if from == to {
+            return false;
+        }
+        self.side(from) == self.side(to)
+    }
+
+    fn side(self, node: usize) -> bool {
+        let shift = match u32::try_from(node) {
+            Ok(shift) => shift,
+            Err(_) => return false,
+        };
+        let Some(bit) = 1u8.checked_shl(shift) else {
+            return false;
+        };
+        self.0 & bit != 0
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub(super) enum StorageJoinCarrier {
+    DataBoundedTopN,
+    DataOverwriteReset,
+    RelayTombstone,
+}
+
+#[derive(Clone, Debug)]
+pub(super) struct StorageJoinValue {
+    carrier: StorageJoinCarrier,
+    pub(super) bits: u8,
+    pub(super) entry: Entry,
+}
+
+impl StorageJoinValue {
+    fn new(carrier: StorageJoinCarrier, bits: u8, entry: Entry) -> Self {
+        match entry.try_into_storage_entry() {
+            Ok(entry) => Self {
+                carrier,
+                bits,
+                entry,
+            },
+            Err(error) => panic!("storage model entry must normalize: {error}"),
+        }
+    }
+
+    fn bottom_like(&self) -> Self {
+        storage_value_from_bits(self.carrier, 0)
+    }
+}
+
+impl PartialEq for StorageJoinValue {
+    fn eq(&self, other: &Self) -> bool {
+        self.carrier == other.carrier && self.bits == other.bits
+    }
+}
+
+impl Eq for StorageJoinValue {}
+
+impl Hash for StorageJoinValue {
+    fn hash(&self, state: &mut H) {
+        self.carrier.hash(state);
+        self.bits.hash(state);
+    }
+}
+
+impl Ord for StorageJoinValue {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        self.carrier
+            .cmp(&other.carrier)
+            .then_with(|| self.bits.cmp(&other.bits))
+    }
+}
+
+impl PartialOrd for StorageJoinValue {
+    fn partial_cmp(&self, other: &Self) -> Option {
+        Some(self.cmp(other))
+    }
+}
+
+impl JoinSemilattice for StorageJoinValue {
+    fn join(self, other: Self) -> Self {
+        if self.carrier != other.carrier {
+            panic!("storage model joins only one carrier");
+        }
+        let carrier = self.carrier;
+        let bits = self.bits | other.bits;
+        let joined = storage_join_entry(self.entry, other.entry);
+        Self::new(carrier, bits, joined)
+    }
+}
+
+pub(super) struct StorageJoinScenario {
+    pub(super) name: &'static str,
+    pub(super) initial: [StorageJoinValue; STORAGE_REPLICA_COUNT],
+}
+
+impl StorageJoinScenario {
+    fn bottom(&self) -> StorageJoinValue {
+        self.initial[0].bottom_like()
+    }
+
+    pub(super) fn global_lub(&self) -> StorageJoinValue {
+        self.initial
+            .iter()
+            .cloned()
+            .fold(self.bottom(), JoinSemilattice::join)
+    }
+}
+
+fn storage_model_did(offset: u32) -> Did {
+    Did::from(10_000u32.saturating_add(offset))
+}
+
+fn storage_version(time: u128, actor: u32, operation: u32) -> EntryVersion {
+    EntryVersion::new(time, Did::from(actor), Did::from(operation))
+}
+
+fn storage_index(index: usize) -> u32 {
+    match u32::try_from(index) {
+        Ok(index) => index,
+        Err(_) => panic!("storage model index must fit in u32"),
+    }
+}
+
+fn storage_dot(version: EntryVersion, index: usize) -> EntryDot {
+    let index = storage_index(index);
+    EntryDot { version, index }
+}
+
+fn storage_encoded(label: &str) -> Encoded {
+    Encoded::from(label)
+}
+
+pub(super) fn storage_join_entry(left: Entry, right: Entry) -> Entry {
+    let joined = match left.join(right) {
+        Ok(entry) => entry,
+        Err(error) => panic!("storage model joins only compatible entries: {error}"),
+    };
+    match joined.try_into_storage_entry() {
+        Ok(entry) => entry,
+        Err(error) => panic!("storage model join result must normalize: {error}"),
+    }
+}
+
+fn data_value_range(did: Did, label: &'static str, start_time: u128, count: usize) -> Entry {
+    let data = (0..count)
+        .map(|index| storage_encoded(&format!("{label}-{index}")))
+        .collect::>();
+    let dots = (0..count)
+        .map(|offset| {
+            let index = storage_index(offset);
+            let time = start_time.saturating_add(u128::from(index));
+            storage_dot(
+                storage_version(time, 1, 1_000u32.saturating_add(index)),
+                offset,
+            )
+        })
+        .collect::>();
+    Entry {
+        did,
+        data,
+        kind: EntryKind::Data,
+        crdt: EntryCrdt {
+            register: None,
+            dots,
+            tombstones: Vec::new(),
+        },
+    }
+}
+
+fn data_overwrite_value(did: Did, label: &'static str, version: EntryVersion) -> Entry {
+    Entry {
+        did,
+        data: vec![storage_encoded(label)],
+        kind: EntryKind::Data,
+        crdt: EntryCrdt {
+            register: Some(version),
+            dots: vec![storage_dot(version, 0)],
+            tombstones: Vec::new(),
+        },
+    }
+}
+
+fn relay_add_value(did: Did, label: &'static str, dot: EntryDot) -> Entry {
+    Entry {
+        did,
+        data: vec![storage_encoded(label)],
+        kind: EntryKind::RelayMessage,
+        crdt: EntryCrdt {
+            register: None,
+            dots: vec![dot],
+            tombstones: Vec::new(),
+        },
+    }
+}
+
+fn relay_remove_value(did: Did, dot: EntryDot) -> Entry {
+    Entry {
+        did,
+        data: Vec::new(),
+        kind: EntryKind::RelayMessage,
+        crdt: EntryCrdt {
+            register: None,
+            dots: Vec::new(),
+            tombstones: vec![dot],
+        },
+    }
+}
+
+fn storage_delta_entry(carrier: StorageJoinCarrier, bit: u8) -> Entry {
+    match carrier {
+        StorageJoinCarrier::DataBoundedTopN => data_value_range(
+            storage_model_did(1),
+            match bit {
+                0b001 => "low",
+                0b010 => "mid",
+                0b100 => "high",
+                _ => panic!("storage model delta bit must be singleton"),
+            },
+            match bit {
+                0b001 => 1,
+                0b010 => 1_000,
+                0b100 => 2_000,
+                _ => panic!("storage model delta bit must be singleton"),
+            },
+            ENTRY_DATA_MAX_LEN,
+        ),
+        StorageJoinCarrier::DataOverwriteReset => match bit {
+            0b001 => data_value_range(storage_model_did(2), "stale-a", 1, 3),
+            0b010 => {
+                data_overwrite_value(storage_model_did(2), "reset", storage_version(100, 2, 200))
+            }
+            0b100 => data_value_range(storage_model_did(2), "stale-c", 10, 3),
+            _ => panic!("storage model delta bit must be singleton"),
+        },
+        StorageJoinCarrier::RelayTombstone => {
+            let relay_a_dot = storage_dot(storage_version(1, 1, 10), 0);
+            let relay_b_dot = storage_dot(storage_version(2, 2, 20), 0);
+            match bit {
+                0b001 => relay_add_value(storage_model_did(3), "relay-a", relay_a_dot),
+                0b010 => relay_add_value(storage_model_did(3), "relay-b", relay_b_dot),
+                0b100 => relay_remove_value(storage_model_did(3), relay_a_dot),
+                _ => panic!("storage model delta bit must be singleton"),
+            }
+        }
+    }
+}
+
+fn storage_bottom_entry(carrier: StorageJoinCarrier) -> Entry {
+    let (did, kind) = match carrier {
+        StorageJoinCarrier::DataBoundedTopN => (storage_model_did(1), EntryKind::Data),
+        StorageJoinCarrier::DataOverwriteReset => (storage_model_did(2), EntryKind::Data),
+        StorageJoinCarrier::RelayTombstone => (storage_model_did(3), EntryKind::RelayMessage),
+    };
+    Entry::new(did, Vec::new(), kind)
+}
+
+pub(super) fn storage_value_from_bits(carrier: StorageJoinCarrier, bits: u8) -> StorageJoinValue {
+    let mut entry = storage_bottom_entry(carrier);
+    for bit in [0b001, 0b010, 0b100] {
+        if bits & bit != 0 {
+            entry = storage_join_entry(entry, storage_delta_entry(carrier, bit));
+        }
+    }
+    StorageJoinValue::new(carrier, bits, entry)
+}
+
+pub(super) fn storage_join_scenarios() -> Vec {
+    vec![
+        StorageJoinScenario {
+            name: "data bounded top-n",
+            initial: [
+                storage_value_from_bits(StorageJoinCarrier::DataBoundedTopN, 0b001),
+                storage_value_from_bits(StorageJoinCarrier::DataBoundedTopN, 0b010),
+                storage_value_from_bits(StorageJoinCarrier::DataBoundedTopN, 0b100),
+            ],
+        },
+        StorageJoinScenario {
+            name: "data overwrite reset floor",
+            initial: [
+                storage_value_from_bits(StorageJoinCarrier::DataOverwriteReset, 0b001),
+                storage_value_from_bits(StorageJoinCarrier::DataOverwriteReset, 0b010),
+                storage_value_from_bits(StorageJoinCarrier::DataOverwriteReset, 0b100),
+            ],
+        },
+        StorageJoinScenario {
+            name: "relay tombstone prevents resurrection",
+            initial: [
+                storage_value_from_bits(StorageJoinCarrier::RelayTombstone, 0b001),
+                storage_value_from_bits(StorageJoinCarrier::RelayTombstone, 0b010),
+                storage_value_from_bits(StorageJoinCarrier::RelayTombstone, 0b100),
+            ],
+        },
+    ]
+}
+
+pub(super) fn storage_join_carriers() -> [StorageJoinCarrier; 3] {
+    [
+        StorageJoinCarrier::DataBoundedTopN,
+        StorageJoinCarrier::DataOverwriteReset,
+        StorageJoinCarrier::RelayTombstone,
+    ]
+}
+
+pub(super) fn storage_value_by_bits(values: &[StorageJoinValue], bits: u8) -> &StorageJoinValue {
+    match values.get(usize::from(bits)) {
+        Some(value) => value,
+        None => panic!("storage model bitmask must be in the finite carrier"),
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub(super) enum StorageJoinPhase {
+    Partitioned,
+    Merged,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub(super) struct StorageJoinState {
+    partition: StoragePartition,
+    pub(super) phase: StorageJoinPhase,
+    replicas: [StorageJoinValue; STORAGE_REPLICA_COUNT],
+}
+
+impl StorageJoinState {
+    fn initial(
+        partition: StoragePartition,
+        replicas: [StorageJoinValue; STORAGE_REPLICA_COUNT],
+    ) -> Self {
+        Self {
+            partition,
+            phase: StorageJoinPhase::Partitioned,
+            replicas,
+        }
+    }
+
+    fn topology_permits(&self, from: usize, to: usize) -> bool {
+        if from == to {
+            return false;
+        }
+        match self.phase {
+            StorageJoinPhase::Partitioned => self.partition.permits(from, to),
+            StorageJoinPhase::Merged => from < STORAGE_REPLICA_COUNT && to < STORAGE_REPLICA_COUNT,
+        }
+    }
+
+    fn transfer_current(&self, from: usize, to: usize) -> Option {
+        if !self.topology_permits(from, to) {
+            return None;
+        }
+        let value = self.replicas.get(from).cloned()?;
+        let mut next = self.clone();
+        let replica = next.replicas.get_mut(to)?;
+        *replica = replica.clone().join(value);
+        Some(next)
+    }
+
+    fn merge_partition(&self) -> Option {
+        if self.phase == StorageJoinPhase::Merged {
+            return None;
+        }
+        Some(Self {
+            phase: StorageJoinPhase::Merged,
+            ..self.clone()
+        })
+    }
+
+    fn successors(&self) -> Vec {
+        let mut next = Vec::new();
+        if let Some(merged) = self.merge_partition() {
+            next.push(merged);
+        }
+        for from in 0..STORAGE_REPLICA_COUNT {
+            for to in 0..STORAGE_REPLICA_COUNT {
+                if let Some(transferred) = self.transfer_current(from, to) {
+                    next.push(transferred);
+                }
+            }
+        }
+        next
+    }
+
+    pub(super) fn is_quiescent_lub(&self, global_lub: &StorageJoinValue) -> bool {
+        self.replicas.iter().all(|value| value == global_lub)
+    }
+
+    fn transfer_all_current(&self) -> Self {
+        let mut state = self.clone();
+        for from in 0..STORAGE_REPLICA_COUNT {
+            for to in 0..STORAGE_REPLICA_COUNT {
+                if let Some(next) = state.transfer_current(from, to) {
+                    state = next;
+                }
+            }
+        }
+        state
+    }
+
+    pub(super) fn drive_to_quiescent_lub(&self, global_lub: &StorageJoinValue) -> Self {
+        let mut state = self.clone();
+        for _ in 0..STORAGE_REPLICA_COUNT * 8 {
+            if state.is_quiescent_lub(global_lub) {
+                return state;
+            }
+            let next = state.transfer_all_current();
+            if next == state {
+                return next;
+            }
+            state = next;
+        }
+        state
+    }
+}
+
+pub(super) fn reachable_storage_join_states(
+    partition: StoragePartition,
+    replicas: [StorageJoinValue; STORAGE_REPLICA_COUNT],
+) -> BTreeSet {
+    let mut seen = BTreeSet::new();
+    let mut frontier = vec![StorageJoinState::initial(partition, replicas)];
+    while let Some(state) = frontier.pop() {
+        if !seen.insert(state.clone()) {
+            continue;
+        }
+        for next in state.successors() {
+            if !seen.contains(&next) {
+                frontier.push(next);
+            }
+        }
+    }
+    seen
+}
+
+// ===================================================================
+// Stage 4: storage hand-off cleanup safety for one placement key.
+//
+// SCOPE: this is the #614 S2' cleanup model, not the storage convergence
+// theorem. Convergence is Stage 3's join-semilattice fact. This stage abstracts
+// exactly one placement key, the copy -> ack -> delete hand-off, and arbitrary
+// local writes over a finite representative value domain while a copy or ack is
+// in flight:
+//
+//   local(v) --SendCopy(v)--> copy_in_flight(v)
+//   copy_in_flight(v) --DeliverCopy--> successor(v) + ack_in_flight(v)
+//   local(v) --LocalWrite(w)--> local(w)
+//   ack_in_flight(v) --DeliverAckDelete--> delete local only if local == v
+//
+// Property checked below:
+//
+//   Always S2': local(k) is removed only if successor(k) contains the same
+//   value at the moment of removal.
+// ===================================================================
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
+pub(super) enum StorageSyncStep {
+    SendCopy,
+    DeliverCopy,
+    LocalWrite(StorageValue),
+    DeliverAckDelete,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
+pub(super) enum StorageValue {
+    V0,
+    V1,
+    V2,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
+pub(super) struct StorageSyncState {
+    local: Option,
+    pub(super) successor: Option,
+    copy_in_flight: Option,
+    ack_in_flight: Option,
+}
+
+impl StorageSyncState {
+    pub(super) fn initial() -> Self {
+        Self {
+            local: Some(StorageValue::V0),
+            successor: None,
+            copy_in_flight: None,
+            ack_in_flight: None,
+        }
+    }
+
+    pub(super) fn step(self, step: StorageSyncStep) -> Option {
+        match step {
+            StorageSyncStep::SendCopy => Some(Self {
+                copy_in_flight: Some(self.local?),
+                ..self
+            }),
+            StorageSyncStep::DeliverCopy => {
+                let copied = self.copy_in_flight?;
+                Some(Self {
+                    successor: Some(copied),
+                    copy_in_flight: None,
+                    ack_in_flight: Some(copied),
+                    ..self
+                })
+            }
+            StorageSyncStep::LocalWrite(value)
+                if self.copy_in_flight.is_some() || self.ack_in_flight.is_some() =>
+            {
+                Some(Self {
+                    local: Some(value),
+                    ..self
+                })
+            }
+            StorageSyncStep::DeliverAckDelete => {
+                let acked = self.ack_in_flight?;
+                let local = match self.local {
+                    Some(current) if current == acked => None,
+                    current => current,
+                };
+                Some(Self {
+                    local,
+                    ack_in_flight: None,
+                    ..self
+                })
+            }
+            _ => None,
+        }
+    }
+
+    pub(super) fn removed_local_value(self, next: Self) -> Option {
+        match (self.local, next.local) {
+            (Some(removed), None) => Some(removed),
+            _ => None,
+        }
+    }
+}
diff --git a/crates/core/src/tests/default/test_stabilization.rs b/crates/core/src/tests/default/test_stabilization.rs
index 43bb15b69..5edc6324b 100644
--- a/crates/core/src/tests/default/test_stabilization.rs
+++ b/crates/core/src/tests/default/test_stabilization.rs
@@ -2,6 +2,12 @@ use std::sync::Arc;
 use std::sync::Mutex;
 
 use async_trait::async_trait;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use rings_transport::connections::dummy_controlled;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use tokio::time::timeout;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use tokio::time::Duration;
 
 use crate::dht::entry::Entry;
 use crate::dht::entry::EntryKind;
@@ -27,12 +33,6 @@ use crate::tests::default::wait_for_predecessor;
 use crate::tests::default::wait_for_successor;
 use crate::tests::default::Node;
 use crate::tests::manually_establish_connection;
-#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
-use rings_transport::connections::dummy_controlled;
-#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
-use tokio::time::timeout;
-#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
-use tokio::time::Duration;
 
 #[derive(Default)]
 struct CountingMeasure {
diff --git a/crates/core/src/utils.rs b/crates/core/src/utils.rs
index 398d351dc..10f809c8a 100644
--- a/crates/core/src/utils.rs
+++ b/crates/core/src/utils.rs
@@ -20,10 +20,7 @@ pub fn get_epoch_ms() -> u128 {
 }
 
 pub(crate) fn get_epoch_ms_i64() -> i64 {
-    match i64::try_from(get_epoch_ms()) {
-        Ok(value) => value,
-        Err(_) => i64::MAX,
-    }
+    i64::try_from(get_epoch_ms()).unwrap_or(i64::MAX)
 }
 
 #[cfg(all(feature = "wasm", target_family = "wasm"))]
diff --git a/crates/node/src/logging.rs b/crates/node/src/logging.rs
index d76e1a53b..a5934c07f 100644
--- a/crates/node/src/logging.rs
+++ b/crates/node/src/logging.rs
@@ -155,14 +155,15 @@ pub mod node {
         let subscriber = Registry::default();
         let level_filter = filter::LevelFilter::from_level(level.into());
         let filter = match std::env::var("RINGS_LOG_FILTER") {
-            Ok(spec) if !spec.trim().is_empty() => EnvFilter::try_new(spec.trim())
-                .unwrap_or_else(|err| {
+            Ok(spec) if !spec.trim().is_empty() => {
+                EnvFilter::try_new(spec.trim()).unwrap_or_else(|err| {
                     eprintln!(
                         "invalid RINGS_LOG_FILTER '{}': {}; falling back to {}",
                         spec, err, level_filter
                     );
                     EnvFilter::new(level_filter.to_string())
-                }),
+                })
+            }
             _ => EnvFilter::new(level_filter.to_string()),
         };
 
diff --git a/crates/node/src/processor/builder.rs b/crates/node/src/processor/builder.rs
index 5d2981a86..864457ebd 100644
--- a/crates/node/src/processor/builder.rs
+++ b/crates/node/src/processor/builder.rs
@@ -142,9 +142,7 @@ impl ProcessorBuilder {
 
     /// Add a custom periodic registration task.
     pub fn registration_task(mut self, task: T) -> Self
-    where
-        T: RegistrationTask + 'static,
-    {
+    where T: RegistrationTask + 'static {
         self.registration_tasks.push(Arc::new(task));
         self
     }
diff --git a/crates/node/src/processor/config.rs b/crates/node/src/processor/config.rs
index e41b4e164..48292952c 100644
--- a/crates/node/src/processor/config.rs
+++ b/crates/node/src/processor/config.rs
@@ -495,9 +495,7 @@ impl Serialize for ProcessorConfig {
 
 impl<'de> serde::de::Deserialize<'de> for ProcessorConfig {
     fn deserialize(deserializer: D) -> core::result::Result
-    where
-        D: serde::Deserializer<'de>,
-    {
+    where D: serde::Deserializer<'de> {
         match ProcessorConfigSerialized::deserialize(deserializer) {
             Ok(ins) => {
                 let cfg: ProcessorConfig = ins
diff --git a/crates/node/src/processor/tests/test_config.rs b/crates/node/src/processor/tests/test_config.rs
index 92b6613ab..5e483eeb5 100644
--- a/crates/node/src/processor/tests/test_config.rs
+++ b/crates/node/src/processor/tests/test_config.rs
@@ -300,10 +300,10 @@ fn default_onion_exit_config_uses_native_tcp_backed_services() {
 
     assert!(config.advertise_onion_exit);
     assert_eq!(config.onion_exit_services, default_onion_exit_services());
-    assert_eq!(
-        config.onion_exit_services,
-        vec![OnionExitService::tcp(), OnionExitService::https()]
-    );
+    assert_eq!(config.onion_exit_services, vec![
+        OnionExitService::tcp(),
+        OnionExitService::https()
+    ]);
 }
 
 #[test]
diff --git a/crates/webview/src/browser.rs b/crates/webview/src/browser.rs
index 1c8d5a130..a06e66842 100644
--- a/crates/webview/src/browser.rs
+++ b/crates/webview/src/browser.rs
@@ -667,340 +667,4 @@ mod wasm {
 pub use wasm::JsOnionProxyTransport;
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::error::WebviewError;
-
-    #[test]
-    fn bootstrap_hooks_browser_network_entrypoints() -> Result<()> {
-        let document_url = Url::parse("https://example.test/docs/index.html")?;
-        let script = bootstrap_script("/webview/", &document_url);
-
-        assert!(script.contains(BOOTSTRAP_MARKER));
-        assert!(script.contains("targetBase"));
-        assert!(script.contains("https://example.test/docs/index.html"));
-        assert!(script.contains("globalThis.fetch"));
-        assert!(script.contains("X-Rings-Webview-Kind"));
-        assert!(script.contains("patchLocationNavigation"));
-        assert!(script.contains("resolveTargetBase"));
-        assert!(script.contains("XMLHttpRequest"));
-        assert!(script.contains("encodeSrcdoc"));
-        assert!(script.contains("HTMLIFrameElement"));
-        assert!(script.contains("blockUnsupportedConstructor"));
-        assert!(script.contains("WebSocket"));
-        assert!(script.contains("EventSource"));
-        assert!(script.contains("sendBeacon"));
-        assert!(script.contains("SharedWorker"));
-        assert!(script.contains("HTMLBaseElement"));
-        assert!(script.contains("setAttribute"));
-        assert!(script.contains("encodeURIComponent"));
-        Ok(())
-    }
-
-    #[test]
-    fn runtime_urls_resolve_against_target_document_not_gateway_location() -> Result<()> {
-        let prefix = GatewayPrefix::new("/webview/")?;
-        let document_url = Url::parse("https://example.test/docs/index.html")?;
-
-        let fetch_url = runtime_gateway_url(&prefix, &document_url, "/api/data")
-            .and_then(|url| required_gateway_url(url, "/api/data"))?;
-        let xhr_url = runtime_gateway_url(&prefix, &document_url, "forms/submit")
-            .and_then(|url| required_gateway_url(url, "forms/submit"))?;
-
-        assert_eq!(
-            prefix.decode_path(&fetch_url)?.as_url().as_str(),
-            "https://example.test/api/data"
-        );
-        assert_eq!(
-            prefix.decode_path(&xhr_url)?.as_url().as_str(),
-            "https://example.test/docs/forms/submit"
-        );
-        Ok(())
-    }
-
-    fn required_gateway_url(url: Option, input: &str) -> Result {
-        url.ok_or_else(|| WebviewError::InvalidGatewayUrl(input.to_string()))
-    }
-
-    #[test]
-    fn bootstrap_executes_runtime_routing_in_javascript() -> Result<()> {
-        let document_url = Url::parse("https://example.test/docs/index.html")?;
-        let script = bootstrap_script("/webview/", &document_url);
-        let program = format!(
-            r#"
-const calls = [];
-function assert(condition, message) {{
-  if (!condition) throw new Error(message);
-}}
-function assertThrows(operation, message) {{
-  let threw = false;
-  try {{
-    operation();
-  }} catch (_error) {{
-    threw = true;
-  }}
-  if (!threw) throw new Error(message);
-}}
-class Request {{
-  constructor(input, init) {{
-    this.url = String(input);
-    this.init = init;
-  }}
-}}
-globalThis.Request = Request;
-globalThis.fetch = function(input, init) {{
-  calls.push(["fetch", input instanceof Request ? input.url : String(input), init]);
-  return "fetch-result";
-}};
-class XMLHttpRequest {{
-  open(method, url, async, user, password) {{
-    calls.push(["xhr", method, url, async, user, password]);
-    return "xhr-result";
-  }}
-}}
-globalThis.XMLHttpRequest = XMLHttpRequest;
-class WebSocket {{
-  constructor(url, protocols) {{
-    calls.push(["websocket", url, protocols]);
-  }}
-}}
-globalThis.WebSocket = WebSocket;
-class EventSource {{
-  constructor(url, init) {{
-    calls.push(["eventsource", url, init]);
-  }}
-}}
-globalThis.EventSource = EventSource;
-class Worker {{
-  constructor(url, options) {{
-    calls.push(["worker", url, options]);
-  }}
-}}
-globalThis.Worker = Worker;
-class SharedWorker {{
-  constructor(url, options) {{
-    calls.push(["sharedworker", url, options]);
-  }}
-}}
-globalThis.SharedWorker = SharedWorker;
-Object.defineProperty(globalThis, "navigator", {{
-  value: {{
-    sendBeacon(url, data) {{
-      calls.push(["beacon", url, data]);
-      return true;
-    }}
-  }},
-  configurable: true
-}});
-class Element {{
-  setAttribute(name, value) {{
-    calls.push(["attribute", name, value]);
-  }}
-}}
-globalThis.Element = Element;
-class HTMLImageElement extends Element {{
-  set src(value) {{
-    calls.push(["property", "img.src", value]);
-  }}
-  set srcset(value) {{
-    calls.push(["property", "img.srcset", value]);
-  }}
-}}
-globalThis.HTMLImageElement = HTMLImageElement;
-const submitListeners = [];
-Object.defineProperty(globalThis, "location", {{
-  value: {{
-    origin: "http://127.0.0.1:3000",
-    assign(url) {{ calls.push(["navigate", url]); }}
-  }},
-  configurable: true
-}});
-Object.defineProperty(globalThis, "parent", {{
-  value: {{
-    postMessage(message, targetOrigin) {{ calls.push(["shell-navigation", message, targetOrigin]); }}
-  }},
-  configurable: true
-}});
-Object.defineProperty(globalThis, "document", {{
-  value: {{
-    querySelector() {{ return null; }},
-    addEventListener(type, listener, capture) {{
-      if (type === "submit" && capture) submitListeners.push(listener);
-    }}
-  }},
-  configurable: true
-}});
-class HTMLFormElement extends Element {{
-  constructor() {{
-    super();
-    this.method = "get";
-    this.target = "";
-    this.attributes = new Map();
-    this.fields = [];
-  }}
-  getAttribute(name) {{ return this.attributes.get(name) || null; }}
-  setAttribute(name, value) {{ this.attributes.set(name, value); }}
-  submit() {{ calls.push(["native-form-submit"]); }}
-}}
-globalThis.HTMLFormElement = HTMLFormElement;
-globalThis.FormData = class FormData {{
-  constructor(form) {{ this.fields = form.fields; }}
-  entries() {{ return this.fields[Symbol.iterator](); }}
-}};
-{script}
-const gateway = (url) => "/webview/" + encodeURIComponent(url);
-await fetch("/api/data");
-await fetch(new Request("forms/submit"), {{ method: "POST" }});
-const xhr = new globalThis.XMLHttpRequest();
-xhr.open("POST", "forms/x", true);
-assertThrows(() => new globalThis.WebSocket("/socket"), "WebSocket was not blocked");
-assertThrows(() => new globalThis.EventSource("events"), "EventSource was not blocked");
-const beaconResult = navigator.sendBeacon("/beacon", "payload");
-assert(beaconResult === false, "sendBeacon was not blocked");
-assertThrows(() => new globalThis.Worker("worker.js"), "Worker was not blocked");
-assertThrows(() => new globalThis.SharedWorker("shared.js"), "SharedWorker was not blocked");
-const element = new Element();
-element.setAttribute("src", "image.png");
-element.setAttribute("srcset", "small.png 1x, /big.png 2x");
-element.setAttribute("aria-label", "unchanged");
-const image = new globalThis.HTMLImageElement();
-image.src = "property.png";
-image.srcset = "property-small.png 1x, /property-big.png 2x";
-const form = new globalThis.HTMLFormElement();
-form.setAttribute("action", gateway("https://example.test/docs/search?existing=1"));
-form.fields = [["q", "test"]];
-const submitEvent = {{
-  target: form,
-  submitter: null,
-  preventDefault() {{ this.prevented = true; }},
-  stopImmediatePropagation() {{ this.stopped = true; }}
-}};
-for (const listener of submitListeners) listener(submitEvent);
-const actual = JSON.stringify(calls);
-assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/api/data")), "fetch URL was not rewritten: " + actual);
-assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/docs/forms/submit")), "Request URL was not rewritten: " + actual);
-assert(calls.some((call) => call[0] === "xhr" && call[2] === gateway("https://example.test/docs/forms/x")), "XHR URL was not rewritten: " + actual);
-assert(!calls.some((call) => ["websocket", "eventsource", "beacon", "worker", "sharedworker"].includes(call[0])), "unsupported native entrypoint was called: " + actual);
-assert(calls.some((call) => call[0] === "attribute" && call[1] === "src" && call[2] === gateway("https://example.test/docs/image.png")), "setAttribute src was not rewritten: " + actual);
-assert(calls.some((call) => call[0] === "attribute" && call[1] === "srcset" && call[2].includes(gateway("https://example.test/docs/small.png")) && call[2].includes(gateway("https://example.test/big.png"))), "setAttribute srcset was not rewritten: " + actual);
-assert(calls.some((call) => call[0] === "attribute" && call[1] === "aria-label" && call[2] === "unchanged"), "non-URL attribute changed: " + actual);
-assert(calls.some((call) => call[0] === "property" && call[1] === "img.src" && call[2] === gateway("https://example.test/docs/property.png")), "img.src property was not rewritten: " + actual);
-assert(calls.some((call) => call[0] === "property" && call[1] === "img.srcset" && call[2].includes(gateway("https://example.test/docs/property-small.png")) && call[2].includes(gateway("https://example.test/property-big.png"))), "img.srcset property was not rewritten: " + actual);
-assert(submitEvent.prevented && submitEvent.stopped, "GET form submission was not intercepted");
-assert(calls.some((call) => call[0] === "navigate" && call[1] === gateway("https://example.test/docs/search?q=test")), "GET form query did not use native gateway navigation: " + actual);
-"#,
-            script = script
-        );
-
-        let output = std::process::Command::new("node")
-            .arg("--input-type=module")
-            .arg("-e")
-            .arg(program)
-            .output()
-            .map_err(|error| WebviewError::Browser(error.to_string()))?;
-
-        if !output.status.success() {
-            return Err(WebviewError::Browser(format!(
-                "node bootstrap test failed: stdout={} stderr={}",
-                String::from_utf8_lossy(output.stdout.as_slice()),
-                String::from_utf8_lossy(output.stderr.as_slice())
-            )));
-        }
-        Ok(())
-    }
-
-    #[test]
-    fn bootstrap_runtime_urls_follow_rewritten_base_href() -> Result<()> {
-        let document_url = Url::parse("https://example.test/docs/index.html")?;
-        let script = bootstrap_script("/webview/", &document_url);
-        let program = format!(
-            r#"
-const calls = [];
-const gateway = (url) => "/webview/" + encodeURIComponent(url);
-function assert(condition, message) {{
-  if (!condition) throw new Error(message);
-}}
-Object.defineProperty(globalThis, "location", {{
-  value: {{
-    href: "http://127.0.0.1:3000/webview/" + encodeURIComponent("https://example.test/docs/index.html"),
-    origin: "http://127.0.0.1:3000"
-  }},
-  configurable: true
-}});
-Object.defineProperty(globalThis, "document", {{
-  value: {{
-    querySelector(selector) {{
-      if (selector !== "base[href]") return null;
-      return {{
-        getAttribute(name) {{
-          return name === "href" ? gateway("https://example.test/assets/") : null;
-        }}
-      }};
-    }}
-  }},
-  configurable: true
-}});
-class Request {{
-  constructor(input) {{
-    this.url = String(input);
-  }}
-}}
-globalThis.Request = Request;
-globalThis.fetch = function(input, init) {{
-  calls.push(["fetch", input instanceof Request ? input.url : String(input), init]);
-  return "fetch-result";
-}};
-class XMLHttpRequest {{
-  open(method, url, async, user, password) {{
-    calls.push(["xhr", method, url, async, user, password]);
-  }}
-}}
-globalThis.XMLHttpRequest = XMLHttpRequest;
-class Element {{
-  setAttribute(name, value) {{
-    calls.push(["attribute", name, value]);
-  }}
-}}
-globalThis.Element = Element;
-class HTMLImageElement extends Element {{
-  set src(value) {{
-    calls.push(["property", "img.src", value]);
-  }}
-}}
-globalThis.HTMLImageElement = HTMLImageElement;
-{script}
-await fetch("api/data");
-const xhr = new globalThis.XMLHttpRequest();
-xhr.open("POST", "forms/submit", true);
-const element = new Element();
-element.setAttribute("src", "image.png");
-const image = new globalThis.HTMLImageElement();
-image.src = "property.png";
-const alreadyGateway = await fetch("http://127.0.0.1:3000" + gateway("https://example.test/kept"));
-const actual = JSON.stringify(calls);
-assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/assets/api/data")), "fetch did not use base href: " + actual);
-assert(calls.some((call) => call[0] === "xhr" && call[2] === gateway("https://example.test/assets/forms/submit")), "XHR did not use base href: " + actual);
-assert(calls.some((call) => call[0] === "attribute" && call[1] === "src" && call[2] === gateway("https://example.test/assets/image.png")), "setAttribute did not use base href: " + actual);
-assert(calls.some((call) => call[0] === "property" && call[1] === "img.src" && call[2] === gateway("https://example.test/assets/property.png")), "property setter did not use base href: " + actual);
-assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/kept")), "same-origin gateway URL was encoded again: " + actual);
-"#,
-            script = script
-        );
-
-        let output = std::process::Command::new("node")
-            .arg("--input-type=module")
-            .arg("-e")
-            .arg(program)
-            .output()
-            .map_err(|error| WebviewError::Browser(error.to_string()))?;
-
-        if !output.status.success() {
-            return Err(WebviewError::Browser(format!(
-                "node base href bootstrap test failed: stdout={} stderr={}",
-                String::from_utf8_lossy(output.stdout.as_slice()),
-                String::from_utf8_lossy(output.stderr.as_slice())
-            )));
-        }
-        Ok(())
-    }
-}
+mod tests;
diff --git a/crates/webview/src/browser/tests.rs b/crates/webview/src/browser/tests.rs
new file mode 100644
index 000000000..ccfd08451
--- /dev/null
+++ b/crates/webview/src/browser/tests.rs
@@ -0,0 +1,335 @@
+use super::*;
+use crate::error::WebviewError;
+
+#[test]
+fn bootstrap_hooks_browser_network_entrypoints() -> Result<()> {
+    let document_url = Url::parse("https://example.test/docs/index.html")?;
+    let script = bootstrap_script("/webview/", &document_url);
+
+    assert!(script.contains(BOOTSTRAP_MARKER));
+    assert!(script.contains("targetBase"));
+    assert!(script.contains("https://example.test/docs/index.html"));
+    assert!(script.contains("globalThis.fetch"));
+    assert!(script.contains("X-Rings-Webview-Kind"));
+    assert!(script.contains("patchLocationNavigation"));
+    assert!(script.contains("resolveTargetBase"));
+    assert!(script.contains("XMLHttpRequest"));
+    assert!(script.contains("encodeSrcdoc"));
+    assert!(script.contains("HTMLIFrameElement"));
+    assert!(script.contains("blockUnsupportedConstructor"));
+    assert!(script.contains("WebSocket"));
+    assert!(script.contains("EventSource"));
+    assert!(script.contains("sendBeacon"));
+    assert!(script.contains("SharedWorker"));
+    assert!(script.contains("HTMLBaseElement"));
+    assert!(script.contains("setAttribute"));
+    assert!(script.contains("encodeURIComponent"));
+    Ok(())
+}
+
+#[test]
+fn runtime_urls_resolve_against_target_document_not_gateway_location() -> Result<()> {
+    let prefix = GatewayPrefix::new("/webview/")?;
+    let document_url = Url::parse("https://example.test/docs/index.html")?;
+
+    let fetch_url = runtime_gateway_url(&prefix, &document_url, "/api/data")
+        .and_then(|url| required_gateway_url(url, "/api/data"))?;
+    let xhr_url = runtime_gateway_url(&prefix, &document_url, "forms/submit")
+        .and_then(|url| required_gateway_url(url, "forms/submit"))?;
+
+    assert_eq!(
+        prefix.decode_path(&fetch_url)?.as_url().as_str(),
+        "https://example.test/api/data"
+    );
+    assert_eq!(
+        prefix.decode_path(&xhr_url)?.as_url().as_str(),
+        "https://example.test/docs/forms/submit"
+    );
+    Ok(())
+}
+
+fn required_gateway_url(url: Option, input: &str) -> Result {
+    url.ok_or_else(|| WebviewError::InvalidGatewayUrl(input.to_string()))
+}
+
+#[test]
+fn bootstrap_executes_runtime_routing_in_javascript() -> Result<()> {
+    let document_url = Url::parse("https://example.test/docs/index.html")?;
+    let script = bootstrap_script("/webview/", &document_url);
+    let program = format!(
+        r#"
+const calls = [];
+function assert(condition, message) {{
+  if (!condition) throw new Error(message);
+}}
+function assertThrows(operation, message) {{
+  let threw = false;
+  try {{
+operation();
+  }} catch (_error) {{
+threw = true;
+  }}
+  if (!threw) throw new Error(message);
+}}
+class Request {{
+  constructor(input, init) {{
+this.url = String(input);
+this.init = init;
+  }}
+}}
+globalThis.Request = Request;
+globalThis.fetch = function(input, init) {{
+  calls.push(["fetch", input instanceof Request ? input.url : String(input), init]);
+  return "fetch-result";
+}};
+class XMLHttpRequest {{
+  open(method, url, async, user, password) {{
+calls.push(["xhr", method, url, async, user, password]);
+return "xhr-result";
+  }}
+}}
+globalThis.XMLHttpRequest = XMLHttpRequest;
+class WebSocket {{
+  constructor(url, protocols) {{
+calls.push(["websocket", url, protocols]);
+  }}
+}}
+globalThis.WebSocket = WebSocket;
+class EventSource {{
+  constructor(url, init) {{
+calls.push(["eventsource", url, init]);
+  }}
+}}
+globalThis.EventSource = EventSource;
+class Worker {{
+  constructor(url, options) {{
+calls.push(["worker", url, options]);
+  }}
+}}
+globalThis.Worker = Worker;
+class SharedWorker {{
+  constructor(url, options) {{
+calls.push(["sharedworker", url, options]);
+  }}
+}}
+globalThis.SharedWorker = SharedWorker;
+Object.defineProperty(globalThis, "navigator", {{
+  value: {{
+sendBeacon(url, data) {{
+  calls.push(["beacon", url, data]);
+  return true;
+}}
+  }},
+  configurable: true
+}});
+class Element {{
+  setAttribute(name, value) {{
+calls.push(["attribute", name, value]);
+  }}
+}}
+globalThis.Element = Element;
+class HTMLImageElement extends Element {{
+  set src(value) {{
+calls.push(["property", "img.src", value]);
+  }}
+  set srcset(value) {{
+calls.push(["property", "img.srcset", value]);
+  }}
+}}
+globalThis.HTMLImageElement = HTMLImageElement;
+const submitListeners = [];
+Object.defineProperty(globalThis, "location", {{
+  value: {{
+origin: "http://127.0.0.1:3000",
+assign(url) {{ calls.push(["navigate", url]); }}
+  }},
+  configurable: true
+}});
+Object.defineProperty(globalThis, "parent", {{
+  value: {{
+postMessage(message, targetOrigin) {{ calls.push(["shell-navigation", message, targetOrigin]); }}
+  }},
+  configurable: true
+}});
+Object.defineProperty(globalThis, "document", {{
+  value: {{
+querySelector() {{ return null; }},
+addEventListener(type, listener, capture) {{
+  if (type === "submit" && capture) submitListeners.push(listener);
+}}
+  }},
+  configurable: true
+}});
+class HTMLFormElement extends Element {{
+  constructor() {{
+super();
+this.method = "get";
+this.target = "";
+this.attributes = new Map();
+this.fields = [];
+  }}
+  getAttribute(name) {{ return this.attributes.get(name) || null; }}
+  setAttribute(name, value) {{ this.attributes.set(name, value); }}
+  submit() {{ calls.push(["native-form-submit"]); }}
+}}
+globalThis.HTMLFormElement = HTMLFormElement;
+globalThis.FormData = class FormData {{
+  constructor(form) {{ this.fields = form.fields; }}
+  entries() {{ return this.fields[Symbol.iterator](); }}
+}};
+{script}
+const gateway = (url) => "/webview/" + encodeURIComponent(url);
+await fetch("/api/data");
+await fetch(new Request("forms/submit"), {{ method: "POST" }});
+const xhr = new globalThis.XMLHttpRequest();
+xhr.open("POST", "forms/x", true);
+assertThrows(() => new globalThis.WebSocket("/socket"), "WebSocket was not blocked");
+assertThrows(() => new globalThis.EventSource("events"), "EventSource was not blocked");
+const beaconResult = navigator.sendBeacon("/beacon", "payload");
+assert(beaconResult === false, "sendBeacon was not blocked");
+assertThrows(() => new globalThis.Worker("worker.js"), "Worker was not blocked");
+assertThrows(() => new globalThis.SharedWorker("shared.js"), "SharedWorker was not blocked");
+const element = new Element();
+element.setAttribute("src", "image.png");
+element.setAttribute("srcset", "small.png 1x, /big.png 2x");
+element.setAttribute("aria-label", "unchanged");
+const image = new globalThis.HTMLImageElement();
+image.src = "property.png";
+image.srcset = "property-small.png 1x, /property-big.png 2x";
+const form = new globalThis.HTMLFormElement();
+form.setAttribute("action", gateway("https://example.test/docs/search?existing=1"));
+form.fields = [["q", "test"]];
+const submitEvent = {{
+  target: form,
+  submitter: null,
+  preventDefault() {{ this.prevented = true; }},
+  stopImmediatePropagation() {{ this.stopped = true; }}
+}};
+for (const listener of submitListeners) listener(submitEvent);
+const actual = JSON.stringify(calls);
+assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/api/data")), "fetch URL was not rewritten: " + actual);
+assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/docs/forms/submit")), "Request URL was not rewritten: " + actual);
+assert(calls.some((call) => call[0] === "xhr" && call[2] === gateway("https://example.test/docs/forms/x")), "XHR URL was not rewritten: " + actual);
+assert(!calls.some((call) => ["websocket", "eventsource", "beacon", "worker", "sharedworker"].includes(call[0])), "unsupported native entrypoint was called: " + actual);
+assert(calls.some((call) => call[0] === "attribute" && call[1] === "src" && call[2] === gateway("https://example.test/docs/image.png")), "setAttribute src was not rewritten: " + actual);
+assert(calls.some((call) => call[0] === "attribute" && call[1] === "srcset" && call[2].includes(gateway("https://example.test/docs/small.png")) && call[2].includes(gateway("https://example.test/big.png"))), "setAttribute srcset was not rewritten: " + actual);
+assert(calls.some((call) => call[0] === "attribute" && call[1] === "aria-label" && call[2] === "unchanged"), "non-URL attribute changed: " + actual);
+assert(calls.some((call) => call[0] === "property" && call[1] === "img.src" && call[2] === gateway("https://example.test/docs/property.png")), "img.src property was not rewritten: " + actual);
+assert(calls.some((call) => call[0] === "property" && call[1] === "img.srcset" && call[2].includes(gateway("https://example.test/docs/property-small.png")) && call[2].includes(gateway("https://example.test/property-big.png"))), "img.srcset property was not rewritten: " + actual);
+assert(submitEvent.prevented && submitEvent.stopped, "GET form submission was not intercepted");
+assert(calls.some((call) => call[0] === "navigate" && call[1] === gateway("https://example.test/docs/search?q=test")), "GET form query did not use native gateway navigation: " + actual);
+"#,
+        script = script
+    );
+
+    let output = std::process::Command::new("node")
+        .arg("--input-type=module")
+        .arg("-e")
+        .arg(program)
+        .output()
+        .map_err(|error| WebviewError::Browser(error.to_string()))?;
+
+    if !output.status.success() {
+        return Err(WebviewError::Browser(format!(
+            "node bootstrap test failed: stdout={} stderr={}",
+            String::from_utf8_lossy(output.stdout.as_slice()),
+            String::from_utf8_lossy(output.stderr.as_slice())
+        )));
+    }
+    Ok(())
+}
+
+#[test]
+fn bootstrap_runtime_urls_follow_rewritten_base_href() -> Result<()> {
+    let document_url = Url::parse("https://example.test/docs/index.html")?;
+    let script = bootstrap_script("/webview/", &document_url);
+    let program = format!(
+        r#"
+const calls = [];
+const gateway = (url) => "/webview/" + encodeURIComponent(url);
+function assert(condition, message) {{
+  if (!condition) throw new Error(message);
+}}
+Object.defineProperty(globalThis, "location", {{
+  value: {{
+href: "http://127.0.0.1:3000/webview/" + encodeURIComponent("https://example.test/docs/index.html"),
+origin: "http://127.0.0.1:3000"
+  }},
+  configurable: true
+}});
+Object.defineProperty(globalThis, "document", {{
+  value: {{
+querySelector(selector) {{
+  if (selector !== "base[href]") return null;
+  return {{
+    getAttribute(name) {{
+      return name === "href" ? gateway("https://example.test/assets/") : null;
+    }}
+  }};
+}}
+  }},
+  configurable: true
+}});
+class Request {{
+  constructor(input) {{
+this.url = String(input);
+  }}
+}}
+globalThis.Request = Request;
+globalThis.fetch = function(input, init) {{
+  calls.push(["fetch", input instanceof Request ? input.url : String(input), init]);
+  return "fetch-result";
+}};
+class XMLHttpRequest {{
+  open(method, url, async, user, password) {{
+calls.push(["xhr", method, url, async, user, password]);
+  }}
+}}
+globalThis.XMLHttpRequest = XMLHttpRequest;
+class Element {{
+  setAttribute(name, value) {{
+calls.push(["attribute", name, value]);
+  }}
+}}
+globalThis.Element = Element;
+class HTMLImageElement extends Element {{
+  set src(value) {{
+calls.push(["property", "img.src", value]);
+  }}
+}}
+globalThis.HTMLImageElement = HTMLImageElement;
+{script}
+await fetch("api/data");
+const xhr = new globalThis.XMLHttpRequest();
+xhr.open("POST", "forms/submit", true);
+const element = new Element();
+element.setAttribute("src", "image.png");
+const image = new globalThis.HTMLImageElement();
+image.src = "property.png";
+const alreadyGateway = await fetch("http://127.0.0.1:3000" + gateway("https://example.test/kept"));
+const actual = JSON.stringify(calls);
+assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/assets/api/data")), "fetch did not use base href: " + actual);
+assert(calls.some((call) => call[0] === "xhr" && call[2] === gateway("https://example.test/assets/forms/submit")), "XHR did not use base href: " + actual);
+assert(calls.some((call) => call[0] === "attribute" && call[1] === "src" && call[2] === gateway("https://example.test/assets/image.png")), "setAttribute did not use base href: " + actual);
+assert(calls.some((call) => call[0] === "property" && call[1] === "img.src" && call[2] === gateway("https://example.test/assets/property.png")), "property setter did not use base href: " + actual);
+assert(calls.some((call) => call[0] === "fetch" && call[1] === gateway("https://example.test/kept")), "same-origin gateway URL was encoded again: " + actual);
+"#,
+        script = script
+    );
+
+    let output = std::process::Command::new("node")
+        .arg("--input-type=module")
+        .arg("-e")
+        .arg(program)
+        .output()
+        .map_err(|error| WebviewError::Browser(error.to_string()))?;
+
+    if !output.status.success() {
+        return Err(WebviewError::Browser(format!(
+            "node base href bootstrap test failed: stdout={} stderr={}",
+            String::from_utf8_lossy(output.stdout.as_slice()),
+            String::from_utf8_lossy(output.stderr.as_slice())
+        )));
+    }
+    Ok(())
+}
diff --git a/crates/webview/src/cors.rs b/crates/webview/src/cors.rs
index 1bd33e529..7db606c38 100644
--- a/crates/webview/src/cors.rs
+++ b/crates/webview/src/cors.rs
@@ -209,9 +209,10 @@ fn header_has_token(response: &GatewayResponse, name: &str, expected: &str) -> b
 
 #[cfg(test)]
 mod tests {
+    use url::Url;
+
     use super::*;
     use crate::types::GatewayRequestKind;
-    use url::Url;
 
     fn request(credentials: GatewayCredentials) -> Result {
         Ok(GatewayRequest::new(
diff --git a/crates/webview/src/error.rs b/crates/webview/src/error.rs
index 57b5e9b96..bc89f3f93 100644
--- a/crates/webview/src/error.rs
+++ b/crates/webview/src/error.rs
@@ -3,6 +3,62 @@ use thiserror::Error;
 /// Result type used by the webview gateway.
 pub type Result = std::result::Result;
 
+/// Stable browser-facing failure metadata for one gateway request.
+///
+/// This is the typed boundary between a transport adapter and browser UI. The
+/// gateway response can use `status`, `code`, and `summary` without parsing the
+/// human-readable `detail` message.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct GatewayFailure {
+    status: u16,
+    code: String,
+    summary: String,
+    detail: String,
+}
+
+impl GatewayFailure {
+    /// Build gateway failure metadata.
+    pub fn new(
+        status: u16,
+        code: impl Into,
+        summary: impl Into,
+        detail: impl Into,
+    ) -> Self {
+        Self {
+            status,
+            code: code.into(),
+            summary: summary.into(),
+            detail: detail.into(),
+        }
+    }
+
+    /// HTTP status to return from the controlled gateway route.
+    pub fn status(&self) -> u16 {
+        self.status
+    }
+
+    /// Stable machine-readable failure code.
+    pub fn code(&self) -> &str {
+        &self.code
+    }
+
+    /// Short user-facing failure summary.
+    pub fn summary(&self) -> &str {
+        &self.summary
+    }
+
+    /// Detailed diagnostic message for the debug console.
+    pub fn detail(&self) -> &str {
+        &self.detail
+    }
+}
+
+impl std::fmt::Display for GatewayFailure {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.detail)
+    }
+}
+
 /// Errors raised while normalizing, rewriting, or forwarding gateway traffic.
 #[derive(Debug, Error)]
 pub enum WebviewError {
@@ -33,6 +89,9 @@ pub enum WebviewError {
     /// A cross-origin runtime response did not satisfy the virtual CORS policy.
     #[error("CORS policy error: {0}")]
     Cors(String),
+    /// A transport adapter returned stable browser-facing failure metadata.
+    #[error("{0}")]
+    GatewayFailure(GatewayFailure),
     /// The pluggable transport failed.
     #[error("gateway transport failed: {0}")]
     Transport(String),
diff --git a/crates/webview/src/lib.rs b/crates/webview/src/lib.rs
index ba934b75d..ca035748d 100644
--- a/crates/webview/src/lib.rs
+++ b/crates/webview/src/lib.rs
@@ -1,4 +1,4 @@
-#![warn(missing_docs)]
+#![deny(missing_docs)]
 //! Rings webview gateway primitives.
 //!
 //! This crate owns the reusable, UI-independent pieces required to serve remote
@@ -32,12 +32,14 @@ pub mod types;
 /// Target URL encoding and gateway route helpers.
 pub mod url;
 
+/// Browser runtime bootstrap helpers.
 #[cfg(feature = "browser")]
 pub mod browser;
 
 pub use cookie::CookieJar;
 pub use cors::preflight_request;
 pub use cors::validate_response;
+pub use error::GatewayFailure;
 pub use error::Result;
 pub use error::WebviewError;
 pub use header::HeaderPolicy;
diff --git a/crates/webview/src/render.rs b/crates/webview/src/render.rs
index cd817140b..bae320d9d 100644
--- a/crates/webview/src/render.rs
+++ b/crates/webview/src/render.rs
@@ -42,8 +42,7 @@ pub struct WebviewRenderer {
 }
 
 impl WebviewRenderer
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     /// Build a renderer around an existing gateway.
     pub fn new(gateway: WebviewGateway) -> Self {
diff --git a/crates/webview/src/transport.rs b/crates/webview/src/transport.rs
index fe7053b95..e4032a573 100644
--- a/crates/webview/src/transport.rs
+++ b/crates/webview/src/transport.rs
@@ -137,8 +137,7 @@ impl GatewayResponsePolicy {
 }
 
 impl WebviewGateway
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     /// Build a webview gateway around `transport`.
     pub fn new(prefix: GatewayPrefix, transport: T) -> Self {
@@ -223,8 +222,7 @@ where
 }
 
 impl ConcurrentWebviewGateway
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     /// Build a concurrent webview gateway around `transport`.
     pub fn new(prefix: GatewayPrefix, transport: T) -> Self {
diff --git a/crates/webview/tests/browser_gateway.rs b/crates/webview/tests/browser_gateway.rs
index 05d1932e9..a3d03e8b7 100644
--- a/crates/webview/tests/browser_gateway.rs
+++ b/crates/webview/tests/browser_gateway.rs
@@ -1,16 +1,9 @@
 //! Browser fixture coverage for the webview gateway.
 #![cfg(feature = "browser")]
 
-use std::io::Read;
-use std::io::Write;
-use std::net::TcpListener;
-use std::net::TcpStream;
 use std::process::Command;
-use std::sync::atomic::AtomicBool;
-use std::sync::atomic::Ordering;
 use std::sync::Arc;
 use std::sync::Mutex;
-use std::time::Duration;
 
 use async_trait::async_trait;
 use rings_webview::browser::bootstrap_script;
@@ -25,6 +18,11 @@ use rings_webview::TargetUrl;
 use rings_webview::WebviewError;
 use rings_webview::WebviewGateway;
 
+#[path = "browser_gateway/fixture_server.rs"]
+mod fixture_server;
+
+use fixture_server::BrowserFixtureServer;
+
 #[derive(Clone, Default)]
 struct FixtureLog {
     requests: Arc>>,
@@ -462,268 +460,6 @@ fn playwright_browser_renders_gateway_fixture_without_direct_remote_requests() -
     Ok(())
 }
 
-struct BrowserFixtureServer {
-    addr: std::net::SocketAddr,
-    shutdown: Arc,
-    handle: Option>>,
-}
-
-impl BrowserFixtureServer {
-    fn start(
-        prefix: GatewayPrefix,
-        gateway: WebviewGateway,
-    ) -> Result {
-        let listener = TcpListener::bind("127.0.0.1:0")
-            .map_err(|error| WebviewError::Transport(error.to_string()))?;
-        listener
-            .set_nonblocking(true)
-            .map_err(|error| WebviewError::Transport(error.to_string()))?;
-        let addr = listener
-            .local_addr()
-            .map_err(|error| WebviewError::Transport(error.to_string()))?;
-        let shutdown = Arc::new(AtomicBool::new(false));
-        let thread_shutdown = Arc::clone(&shutdown);
-        let gateway = Arc::new(Mutex::new(gateway));
-        let handle =
-            std::thread::spawn(move || serve_gateway(listener, thread_shutdown, prefix, gateway));
-        Ok(Self {
-            addr,
-            shutdown,
-            handle: Some(handle),
-        })
-    }
-
-    fn gateway_url(&self, gateway_path: &str) -> String {
-        format!("http://{}{}", self.addr, gateway_path)
-    }
-
-    fn stop(mut self) -> Result<()> {
-        self.shutdown.store(true, Ordering::SeqCst);
-        let _ = TcpStream::connect(self.addr);
-        if let Some(handle) = self.handle.take() {
-            handle.join().map_err(|_| {
-                WebviewError::Transport("browser fixture server panicked".to_string())
-            })??;
-        }
-        Ok(())
-    }
-}
-
-fn serve_gateway(
-    listener: TcpListener,
-    shutdown: Arc,
-    prefix: GatewayPrefix,
-    gateway: Arc>>,
-) -> Result<()> {
-    while !shutdown.load(Ordering::SeqCst) {
-        match listener.accept() {
-            Ok((stream, _peer)) => {
-                let thread_prefix = prefix.clone();
-                let thread_gateway = Arc::clone(&gateway);
-                std::thread::spawn(move || {
-                    let mut stream = stream;
-                    if let Err(error) =
-                        handle_connection(&mut stream, &thread_prefix, &thread_gateway)
-                    {
-                        write_fixture_error(&mut stream, error);
-                    }
-                });
-            }
-            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
-                std::thread::sleep(Duration::from_millis(5));
-            }
-            Err(error) => return Err(WebviewError::Transport(error.to_string())),
-        }
-    }
-    Ok(())
-}
-
-fn handle_connection(
-    stream: &mut TcpStream,
-    prefix: &GatewayPrefix,
-    gateway: &Arc>>,
-) -> Result<()> {
-    stream
-        .set_nonblocking(false)
-        .map_err(|error| WebviewError::Transport(error.to_string()))?;
-    let request = read_http_request(stream)?;
-    if !request.path.starts_with(prefix.as_str()) {
-        return write_http_response(
-            stream,
-            &GatewayResponse::new(
-                404,
-                vec![GatewayHeader::new("Content-Type", "text/plain")?],
-                b"not found".to_vec(),
-            )?,
-        );
-    }
-
-    let kind = gateway_request_kind(&request);
-    let mut gateway = gateway.lock().map_err(|_| {
-        WebviewError::Transport("browser fixture gateway lock poisoned".to_string())
-    })?;
-    let mut gateway_request = gateway.request_from_gateway_path(request.path.as_str(), kind)?;
-    gateway_request.method = request.method;
-    gateway_request.headers = request.headers;
-    gateway_request.body = request.body;
-    let response = futures::executor::block_on(gateway.send(gateway_request))?;
-    write_http_response(stream, &response)
-}
-
-fn write_fixture_error(stream: &mut TcpStream, error: WebviewError) {
-    let body = format!("gateway fixture error: {error}");
-    let Ok(content_type) = GatewayHeader::new("Content-Type", "text/plain") else {
-        return;
-    };
-    let Ok(response) = GatewayResponse::new(500, vec![content_type], body.into_bytes()) else {
-        return;
-    };
-    let _ = write_http_response(stream, &response);
-}
-
-struct HttpRequest {
-    method: String,
-    path: String,
-    headers: Vec,
-    body: Vec,
-}
-
-fn read_http_request(stream: &mut TcpStream) -> Result {
-    stream
-        .set_read_timeout(Some(Duration::from_secs(5)))
-        .map_err(|error| WebviewError::Transport(error.to_string()))?;
-    let mut buffer = Vec::new();
-    let header_end = loop {
-        let mut chunk = [0_u8; 1024];
-        let read = stream
-            .read(&mut chunk)
-            .map_err(|error| WebviewError::Transport(error.to_string()))?;
-        if read == 0 {
-            return Err(WebviewError::Transport(
-                "connection closed before request headers".to_string(),
-            ));
-        }
-        let Some(bytes) = chunk.get(..read) else {
-            return Err(WebviewError::Transport("invalid read size".to_string()));
-        };
-        buffer.extend_from_slice(bytes);
-        if let Some(index) = find_bytes(buffer.as_slice(), b"\r\n\r\n") {
-            break index;
-        }
-    };
-    let body_start = header_end
-        .checked_add(4)
-        .ok_or_else(|| WebviewError::Transport("request header offset overflow".to_string()))?;
-    let header_bytes = buffer
-        .get(..header_end)
-        .ok_or_else(|| WebviewError::Transport("invalid request header slice".to_string()))?;
-    let header_text = std::str::from_utf8(header_bytes)
-        .map_err(|error| WebviewError::Transport(error.to_string()))?;
-    let mut lines = header_text.split("\r\n");
-    let request_line = lines
-        .next()
-        .ok_or_else(|| WebviewError::Transport("missing request line".to_string()))?;
-    let mut request_parts = request_line.split_whitespace();
-    let method = request_parts
-        .next()
-        .ok_or_else(|| WebviewError::Transport("missing request method".to_string()))?
-        .to_string();
-    let path = request_parts
-        .next()
-        .ok_or_else(|| WebviewError::Transport("missing request path".to_string()))?
-        .to_string();
-    let mut headers = Vec::new();
-    let mut content_length = 0_usize;
-    for line in lines {
-        let Some((name, value)) = line.split_once(':') else {
-            continue;
-        };
-        let trimmed_value = value.trim();
-        if name.eq_ignore_ascii_case("content-length") {
-            content_length = trimmed_value
-                .parse::()
-                .map_err(|error| WebviewError::Transport(error.to_string()))?;
-        }
-        headers.push(GatewayHeader::new(name, trimmed_value)?);
-    }
-    let total_len = body_start
-        .checked_add(content_length)
-        .ok_or_else(|| WebviewError::Transport("request body offset overflow".to_string()))?;
-    while buffer.len() < total_len {
-        let mut chunk = [0_u8; 1024];
-        let read = stream
-            .read(&mut chunk)
-            .map_err(|error| WebviewError::Transport(error.to_string()))?;
-        if read == 0 {
-            return Err(WebviewError::Transport(
-                "connection closed before request body".to_string(),
-            ));
-        }
-        let Some(bytes) = chunk.get(..read) else {
-            return Err(WebviewError::Transport("invalid read size".to_string()));
-        };
-        buffer.extend_from_slice(bytes);
-    }
-    let body = buffer
-        .get(body_start..total_len)
-        .ok_or_else(|| WebviewError::Transport("invalid request body slice".to_string()))?
-        .to_vec();
-    Ok(HttpRequest {
-        method,
-        path,
-        headers,
-        body,
-    })
-}
-
-fn gateway_request_kind(request: &HttpRequest) -> GatewayRequestKind {
-    if header_value(&request.headers, "x-requested-with")
-        .is_some_and(|value| value.eq_ignore_ascii_case("XMLHttpRequest"))
-    {
-        return GatewayRequestKind::Xhr;
-    }
-    if let Some(kind) = header_value(&request.headers, "x-rings-webview-kind") {
-        return match kind {
-            "fetch" => GatewayRequestKind::Fetch,
-            "navigation" => GatewayRequestKind::Navigation,
-            _ => GatewayRequestKind::Subresource,
-        };
-    }
-    if request.method != "GET" {
-        return GatewayRequestKind::Fetch;
-    }
-    match header_value(&request.headers, "sec-fetch-dest") {
-        Some("document") => GatewayRequestKind::Navigation,
-        _ => GatewayRequestKind::Subresource,
-    }
-}
-
-fn write_http_response(stream: &mut TcpStream, response: &GatewayResponse) -> Result<()> {
-    let reason = match response.status {
-        200 => "OK",
-        404 => "Not Found",
-        500 => "Internal Server Error",
-        _ => "OK",
-    };
-    let mut head = format!(
-        "HTTP/1.1 {} {}\r\nContent-Length: {}\r\nConnection: close\r\n",
-        response.status,
-        reason,
-        response.body.len()
-    );
-    for header in &response.headers {
-        head.push_str(header.name.as_str());
-        head.push_str(": ");
-        head.push_str(header.value.as_str());
-        head.push_str("\r\n");
-    }
-    head.push_str("\r\n");
-    stream
-        .write_all(head.as_bytes())
-        .and_then(|_| stream.write_all(response.body.as_slice()))
-        .map_err(|error| WebviewError::Transport(error.to_string()))
-}
-
 fn response(
     status: u16,
     content_type: &str,
@@ -1034,19 +770,6 @@ fn assert_recorded_target(
     }
 }
 
-fn header_value<'a>(headers: &'a [GatewayHeader], name: &str) -> Option<&'a str> {
-    headers
-        .iter()
-        .find(|header| header.name_eq(name))
-        .map(|header| header.value.as_str())
-}
-
-fn find_bytes(haystack: &[u8], needle: &[u8]) -> Option {
-    haystack
-        .windows(needle.len())
-        .position(|window| window == needle)
-}
-
 const ONE_PIXEL_PNG: &[u8] = &[
     0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
     0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4,
diff --git a/crates/webview/tests/browser_gateway/fixture_server.rs b/crates/webview/tests/browser_gateway/fixture_server.rs
new file mode 100644
index 000000000..cdbc06d9b
--- /dev/null
+++ b/crates/webview/tests/browser_gateway/fixture_server.rs
@@ -0,0 +1,286 @@
+use std::io::Read;
+use std::io::Write;
+use std::net::TcpListener;
+use std::net::TcpStream;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+
+use super::*;
+
+pub(super) struct BrowserFixtureServer {
+    addr: std::net::SocketAddr,
+    shutdown: Arc,
+    handle: Option>>,
+}
+
+impl BrowserFixtureServer {
+    pub(super) fn start(
+        prefix: GatewayPrefix,
+        gateway: WebviewGateway,
+    ) -> Result {
+        let listener = TcpListener::bind("127.0.0.1:0")
+            .map_err(|error| WebviewError::Transport(error.to_string()))?;
+        listener
+            .set_nonblocking(true)
+            .map_err(|error| WebviewError::Transport(error.to_string()))?;
+        let addr = listener
+            .local_addr()
+            .map_err(|error| WebviewError::Transport(error.to_string()))?;
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let thread_shutdown = Arc::clone(&shutdown);
+        let gateway = Arc::new(Mutex::new(gateway));
+        let handle =
+            std::thread::spawn(move || serve_gateway(listener, thread_shutdown, prefix, gateway));
+        Ok(Self {
+            addr,
+            shutdown,
+            handle: Some(handle),
+        })
+    }
+
+    pub(super) fn gateway_url(&self, gateway_path: &str) -> String {
+        format!("http://{}{}", self.addr, gateway_path)
+    }
+
+    pub(super) fn stop(mut self) -> Result<()> {
+        self.shutdown.store(true, Ordering::SeqCst);
+        let _ = TcpStream::connect(self.addr);
+        if let Some(handle) = self.handle.take() {
+            handle.join().map_err(|_| {
+                WebviewError::Transport("browser fixture server panicked".to_string())
+            })??;
+        }
+        Ok(())
+    }
+}
+
+fn serve_gateway(
+    listener: TcpListener,
+    shutdown: Arc,
+    prefix: GatewayPrefix,
+    gateway: Arc>>,
+) -> Result<()> {
+    while !shutdown.load(Ordering::SeqCst) {
+        match listener.accept() {
+            Ok((stream, _peer)) => {
+                let thread_prefix = prefix.clone();
+                let thread_gateway = Arc::clone(&gateway);
+                std::thread::spawn(move || {
+                    let mut stream = stream;
+                    if let Err(error) =
+                        handle_connection(&mut stream, &thread_prefix, &thread_gateway)
+                    {
+                        write_fixture_error(&mut stream, error);
+                    }
+                });
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                std::thread::sleep(Duration::from_millis(5));
+            }
+            Err(error) => return Err(WebviewError::Transport(error.to_string())),
+        }
+    }
+    Ok(())
+}
+
+fn handle_connection(
+    stream: &mut TcpStream,
+    prefix: &GatewayPrefix,
+    gateway: &Arc>>,
+) -> Result<()> {
+    stream
+        .set_nonblocking(false)
+        .map_err(|error| WebviewError::Transport(error.to_string()))?;
+    let request = read_http_request(stream)?;
+    if !request.path.starts_with(prefix.as_str()) {
+        return write_http_response(
+            stream,
+            &GatewayResponse::new(
+                404,
+                vec![GatewayHeader::new("Content-Type", "text/plain")?],
+                b"not found".to_vec(),
+            )?,
+        );
+    }
+
+    let kind = gateway_request_kind(&request);
+    let mut gateway = gateway.lock().map_err(|_| {
+        WebviewError::Transport("browser fixture gateway lock poisoned".to_string())
+    })?;
+    let mut gateway_request = gateway.request_from_gateway_path(request.path.as_str(), kind)?;
+    gateway_request.method = request.method;
+    gateway_request.headers = request.headers;
+    gateway_request.body = request.body;
+    let response = futures::executor::block_on(gateway.send(gateway_request))?;
+    write_http_response(stream, &response)
+}
+
+fn write_fixture_error(stream: &mut TcpStream, error: WebviewError) {
+    let body = format!("gateway fixture error: {error}");
+    let Ok(content_type) = GatewayHeader::new("Content-Type", "text/plain") else {
+        return;
+    };
+    let Ok(response) = GatewayResponse::new(500, vec![content_type], body.into_bytes()) else {
+        return;
+    };
+    let _ = write_http_response(stream, &response);
+}
+
+struct HttpRequest {
+    method: String,
+    path: String,
+    headers: Vec,
+    body: Vec,
+}
+
+fn read_http_request(stream: &mut TcpStream) -> Result {
+    stream
+        .set_read_timeout(Some(Duration::from_secs(5)))
+        .map_err(|error| WebviewError::Transport(error.to_string()))?;
+    let mut buffer = Vec::new();
+    let header_end = loop {
+        let mut chunk = [0_u8; 1024];
+        let read = stream
+            .read(&mut chunk)
+            .map_err(|error| WebviewError::Transport(error.to_string()))?;
+        if read == 0 {
+            return Err(WebviewError::Transport(
+                "connection closed before request headers".to_string(),
+            ));
+        }
+        let Some(bytes) = chunk.get(..read) else {
+            return Err(WebviewError::Transport("invalid read size".to_string()));
+        };
+        buffer.extend_from_slice(bytes);
+        if let Some(index) = find_bytes(buffer.as_slice(), b"\r\n\r\n") {
+            break index;
+        }
+    };
+    let body_start = header_end
+        .checked_add(4)
+        .ok_or_else(|| WebviewError::Transport("request header offset overflow".to_string()))?;
+    let header_bytes = buffer
+        .get(..header_end)
+        .ok_or_else(|| WebviewError::Transport("invalid request header slice".to_string()))?;
+    let header_text = std::str::from_utf8(header_bytes)
+        .map_err(|error| WebviewError::Transport(error.to_string()))?;
+    let mut lines = header_text.split("\r\n");
+    let request_line = lines
+        .next()
+        .ok_or_else(|| WebviewError::Transport("missing request line".to_string()))?;
+    let mut request_parts = request_line.split_whitespace();
+    let method = request_parts
+        .next()
+        .ok_or_else(|| WebviewError::Transport("missing request method".to_string()))?
+        .to_string();
+    let path = request_parts
+        .next()
+        .ok_or_else(|| WebviewError::Transport("missing request path".to_string()))?
+        .to_string();
+    let mut headers = Vec::new();
+    let mut content_length = 0_usize;
+    for line in lines {
+        let Some((name, value)) = line.split_once(':') else {
+            continue;
+        };
+        let trimmed_value = value.trim();
+        if name.eq_ignore_ascii_case("content-length") {
+            content_length = trimmed_value
+                .parse::()
+                .map_err(|error| WebviewError::Transport(error.to_string()))?;
+        }
+        headers.push(GatewayHeader::new(name, trimmed_value)?);
+    }
+    let total_len = body_start
+        .checked_add(content_length)
+        .ok_or_else(|| WebviewError::Transport("request body offset overflow".to_string()))?;
+    while buffer.len() < total_len {
+        let mut chunk = [0_u8; 1024];
+        let read = stream
+            .read(&mut chunk)
+            .map_err(|error| WebviewError::Transport(error.to_string()))?;
+        if read == 0 {
+            return Err(WebviewError::Transport(
+                "connection closed before request body".to_string(),
+            ));
+        }
+        let Some(bytes) = chunk.get(..read) else {
+            return Err(WebviewError::Transport("invalid read size".to_string()));
+        };
+        buffer.extend_from_slice(bytes);
+    }
+    let body = buffer
+        .get(body_start..total_len)
+        .ok_or_else(|| WebviewError::Transport("invalid request body slice".to_string()))?
+        .to_vec();
+    Ok(HttpRequest {
+        method,
+        path,
+        headers,
+        body,
+    })
+}
+
+fn gateway_request_kind(request: &HttpRequest) -> GatewayRequestKind {
+    if header_value(&request.headers, "x-requested-with")
+        .is_some_and(|value| value.eq_ignore_ascii_case("XMLHttpRequest"))
+    {
+        return GatewayRequestKind::Xhr;
+    }
+    if let Some(kind) = header_value(&request.headers, "x-rings-webview-kind") {
+        return match kind {
+            "fetch" => GatewayRequestKind::Fetch,
+            "navigation" => GatewayRequestKind::Navigation,
+            _ => GatewayRequestKind::Subresource,
+        };
+    }
+    if request.method != "GET" {
+        return GatewayRequestKind::Fetch;
+    }
+    match header_value(&request.headers, "sec-fetch-dest") {
+        Some("document") => GatewayRequestKind::Navigation,
+        _ => GatewayRequestKind::Subresource,
+    }
+}
+
+fn write_http_response(stream: &mut TcpStream, response: &GatewayResponse) -> Result<()> {
+    let reason = match response.status {
+        200 => "OK",
+        404 => "Not Found",
+        500 => "Internal Server Error",
+        _ => "OK",
+    };
+    let mut head = format!(
+        "HTTP/1.1 {} {}\r\nContent-Length: {}\r\nConnection: close\r\n",
+        response.status,
+        reason,
+        response.body.len()
+    );
+    for header in &response.headers {
+        head.push_str(header.name.as_str());
+        head.push_str(": ");
+        head.push_str(header.value.as_str());
+        head.push_str("\r\n");
+    }
+    head.push_str("\r\n");
+    stream
+        .write_all(head.as_bytes())
+        .and_then(|_| stream.write_all(response.body.as_slice()))
+        .map_err(|error| WebviewError::Transport(error.to_string()))
+}
+
+fn header_value<'a>(headers: &'a [GatewayHeader], name: &str) -> Option<&'a str> {
+    headers
+        .iter()
+        .find(|header| header.name_eq(name))
+        .map(|header| header.value.as_str())
+}
+
+fn find_bytes(haystack: &[u8], needle: &[u8]) -> Option {
+    haystack
+        .windows(needle.len())
+        .position(|window| window == needle)
+}
diff --git a/frontend/src/extension.rs b/frontend/src/extension.rs
index 7aaba104c..2ca58b233 100644
--- a/frontend/src/extension.rs
+++ b/frontend/src/extension.rs
@@ -572,7 +572,9 @@ async fn route_headless_onion_proxy(
 ) -> Result {
     let handle = headless_demo_node(&state)?;
     let request = onion::OnionProxyRouteRequest::from_js(message)?;
-    let route = onion::route(&handle.node.provider, request).await?;
+    let route = onion::route(&handle.node.provider, request)
+        .await
+        .map_err(|error| error.to_string())?;
     ensure_headless_generation_current(&state, handle.generation)?;
     route.to_js()
 }
@@ -583,7 +585,9 @@ async fn request_headless_onion_proxy(
 ) -> Result {
     let handle = headless_demo_node(&state)?;
     let request = onion::OnionProxyHttpRequest::from_js(message)?;
-    let response = onion::request(&handle.node.provider, request).await?;
+    let response = onion::request(&handle.node.provider, request)
+        .await
+        .map_err(|error| error.to_string())?;
     ensure_headless_generation_current(&state, handle.generation)?;
     response.to_js()
 }
diff --git a/frontend/src/onion.rs b/frontend/src/onion.rs
index 778dc94ae..4d19615e8 100644
--- a/frontend/src/onion.rs
+++ b/frontend/src/onion.rs
@@ -1,5 +1,6 @@
 //! Onion proxy helpers for the browser frontend.
 
+use std::fmt;
 use std::sync::Arc;
 
 use js_sys::Array;
@@ -74,6 +75,69 @@ pub(crate) struct OnionProxyResponse {
     pub(crate) body: Vec,
 }
 
+/// Stable class for onion proxy failures that cross the JS promise boundary.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum OnionProxyFailureKind {
+    /// The proxy failed before selecting a more specific route state.
+    Generic,
+    /// The route builder found no live exit for the requested HTTPS service.
+    ExitUnavailable,
+    /// The route builder found exits or relays, but no usable route.
+    RouteUnavailable,
+    /// The selected onion request did not complete before its deadline.
+    RequestTimedOut,
+}
+
+/// Onion proxy error with a stable failure class and a diagnostic message.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(crate) struct OnionProxyError {
+    kind: OnionProxyFailureKind,
+    message: String,
+}
+
+impl OnionProxyError {
+    /// Build a generic onion proxy error.
+    pub(crate) fn generic(message: impl Into) -> Self {
+        Self {
+            kind: OnionProxyFailureKind::Generic,
+            message: message.into(),
+        }
+    }
+
+    /// Build an onion proxy error whose kind is derived once at the JS boundary.
+    pub(crate) fn classified(message: impl Into) -> Self {
+        let message = message.into();
+        Self {
+            kind: classify_onion_proxy_failure(&message),
+            message,
+        }
+    }
+
+    /// Stable class for browser-facing failure handling.
+    pub(crate) fn kind(&self) -> OnionProxyFailureKind {
+        self.kind
+    }
+
+    /// Diagnostic message for logs and UI text.
+    pub(crate) fn message(&self) -> &str {
+        &self.message
+    }
+}
+
+impl fmt::Display for OnionProxyError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for OnionProxyError {}
+
+impl From for OnionProxyError {
+    fn from(message: String) -> Self {
+        Self::generic(message)
+    }
+}
+
 impl Default for OnionProxyOptions {
     fn default() -> Self {
         Self {
@@ -274,40 +338,71 @@ pub(crate) fn format_headers(headers: &[(String, String)]) -> String {
 pub(crate) async fn route(
     provider: &Arc,
     request: OnionProxyRouteRequest,
-) -> Result {
+) -> Result {
     let target_authority = target_authority(&request.url)?;
     let proxy = provider
         .onion_https_proxy(request.options.hop_count, request.options.allow_short_paths)
         .map_err(|error| {
-            format!(
+            OnionProxyError::generic(format!(
                 "create onion proxy failed: {}",
                 js_error_label(error.into())
-            )
+            ))
         })?;
     let value = JsFuture::from(proxy.route(target_authority))
         .await
-        .map_err(|error| format!("build onion route failed: {}", js_error_label(error)))?;
-    OnionProxyRoute::from_js(&value)
+        .map_err(|error| {
+            OnionProxyError::classified(format!(
+                "build onion route failed: {}",
+                js_error_label(error)
+            ))
+        })?;
+    OnionProxyRoute::from_js(&value).map_err(OnionProxyError::generic)
 }
 
 /// Send one HTTPS request through an onion proxy.
 pub(crate) async fn request(
     provider: &Arc,
     request: OnionProxyHttpRequest,
-) -> Result {
+) -> Result {
     target_authority(&request.url)?;
     let proxy = provider
         .onion_https_proxy(request.options.hop_count, request.options.allow_short_paths)
         .map_err(|error| {
-            format!(
+            OnionProxyError::generic(format!(
                 "create onion proxy failed: {}",
                 js_error_label(error.into())
-            )
+            ))
         })?;
     let value = JsFuture::from(proxy.request(request.url.clone(), request.client_request_js()?))
         .await
-        .map_err(|error| format!("onion proxy request failed: {}", js_error_label(error)))?;
-    OnionProxyResponse::from_js(&value)
+        .map_err(|error| {
+            OnionProxyError::classified(format!(
+                "onion proxy request failed: {}",
+                js_error_label(error)
+            ))
+        })?;
+    OnionProxyResponse::from_js(&value).map_err(OnionProxyError::generic)
+}
+
+fn classify_onion_proxy_failure(message: &str) -> OnionProxyFailureKind {
+    if message.contains("no live onion exit offers service \"https\"") {
+        OnionProxyFailureKind::ExitUnavailable
+    } else if [
+        "no live onion exit",
+        "not enough relay candidates",
+        "no onion route has a permitted first hop",
+    ]
+    .iter()
+    .any(|needle| message.contains(needle))
+    {
+        OnionProxyFailureKind::RouteUnavailable
+    } else if message.contains("onion HTTPS proxy request timed out")
+        || message.contains("browser HTTPS proxy request timed out")
+    {
+        OnionProxyFailureKind::RequestTimedOut
+    } else {
+        OnionProxyFailureKind::Generic
+    }
 }
 
 fn target_authority(url: &str) -> Result {
diff --git a/frontend/src/webview.rs b/frontend/src/webview.rs
index b54800b33..70c1dffd0 100644
--- a/frontend/src/webview.rs
+++ b/frontend/src/webview.rs
@@ -15,6 +15,7 @@ use js_sys::Uint8Array;
 use rings_node::provider::Provider;
 use rings_webview::browser::bootstrap_script;
 use rings_webview::ConcurrentWebviewGateway;
+use rings_webview::GatewayFailure;
 use rings_webview::GatewayCredentials;
 use rings_webview::GatewayHeader;
 use rings_webview::GatewayPrefix;
@@ -277,8 +278,8 @@ fn browser_failure(status: u16, error: String) -> JsValue {
 
 fn browser_failure_with(
     status: u16,
-    code: &'static str,
-    summary: &'static str,
+    code: &str,
+    summary: &str,
     error: String,
 ) -> JsValue {
     let value = Object::new();
@@ -292,17 +293,26 @@ fn browser_failure_with(
 }
 
 fn browser_transport_failure(error: WebviewError) -> JsValue {
-    let (failure, message) = match error {
-        WebviewError::Transport(message) => (
-            classify_transport_failure(&message),
+    match error {
+        WebviewError::GatewayFailure(failure) => browser_failure_with(
+            failure.status(),
+            failure.code(),
+            failure.summary(),
+            failure.detail().to_string(),
+        ),
+        WebviewError::Transport(message) => browser_failure_with(
+            BrowserFailureKind::GatewayTransport.status(),
+            BrowserFailureKind::GatewayTransport.code(),
+            BrowserFailureKind::GatewayTransport.summary(),
             format!("gateway transport failed: {message}"),
         ),
-        other => (
-            BrowserFailureKind::GatewayTransport,
+        other => browser_failure_with(
+            BrowserFailureKind::GatewayTransport.status(),
+            BrowserFailureKind::GatewayTransport.code(),
+            BrowserFailureKind::GatewayTransport.summary(),
             format!("gateway transport failed: {other}"),
         ),
-    };
-    browser_failure_with(failure.status(), failure.code(), failure.summary(), message)
+    }
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -310,6 +320,7 @@ enum BrowserFailureKind {
     GatewayTransport,
     OnionExitUnavailable,
     OnionRouteUnavailable,
+    OnionRequestTimedOut,
 }
 
 impl BrowserFailureKind {
@@ -317,6 +328,7 @@ impl BrowserFailureKind {
         match self {
             Self::GatewayTransport => 502,
             Self::OnionExitUnavailable | Self::OnionRouteUnavailable => 503,
+            Self::OnionRequestTimedOut => 504,
         }
     }
 
@@ -325,6 +337,7 @@ impl BrowserFailureKind {
             Self::GatewayTransport => "gateway_transport_failed",
             Self::OnionExitUnavailable => "onion_exit_unavailable",
             Self::OnionRouteUnavailable => "onion_route_unavailable",
+            Self::OnionRequestTimedOut => "onion_request_timed_out",
         }
     }
 
@@ -335,25 +348,24 @@ impl BrowserFailureKind {
             Self::OnionRouteUnavailable => {
                 "No onion route is currently available for the requested target."
             }
+            Self::OnionRequestTimedOut => "Onion HTTPS proxy request timed out.",
         }
     }
 }
 
-fn classify_transport_failure(message: &str) -> BrowserFailureKind {
-    if message.contains("no live onion exit offers service \"https\"") {
-        BrowserFailureKind::OnionExitUnavailable
-    } else if [
-        "no live onion exit",
-        "not enough relay candidates",
-        "no onion route has a permitted first hop",
-    ]
-    .iter()
-    .any(|needle| message.contains(needle))
-    {
-        BrowserFailureKind::OnionRouteUnavailable
-    } else {
-        BrowserFailureKind::GatewayTransport
-    }
+fn onion_gateway_failure(error: onion::OnionProxyError) -> WebviewError {
+    let failure = match error.kind() {
+        onion::OnionProxyFailureKind::Generic => BrowserFailureKind::GatewayTransport,
+        onion::OnionProxyFailureKind::ExitUnavailable => BrowserFailureKind::OnionExitUnavailable,
+        onion::OnionProxyFailureKind::RouteUnavailable => BrowserFailureKind::OnionRouteUnavailable,
+        onion::OnionProxyFailureKind::RequestTimedOut => BrowserFailureKind::OnionRequestTimedOut,
+    };
+    WebviewError::GatewayFailure(GatewayFailure::new(
+        failure.status(),
+        failure.code(),
+        failure.summary(),
+        format!("gateway transport failed: {}", error.message()),
+    ))
 }
 
 fn default_failure_code(status: u16) -> &'static str {
@@ -701,7 +713,7 @@ impl GatewayTransport for OnionGatewayTransport {
             options,
         })
         .await
-        .map_err(WebviewError::Transport)?;
+        .map_err(onion_gateway_failure)?;
         let headers = response
             .headers
             .into_iter()
@@ -742,12 +754,12 @@ async fn trace_onion_route(
             duration,
         ),
         Err(error) => emit_onion_debug(
-            error.as_str(),
+            error.message(),
             "error",
             target,
             kind,
             None,
-            Some(error.as_str()),
+            Some(error.message()),
             duration,
         ),
     }
@@ -822,195 +834,7 @@ fn is_http_origin(origin: &str) -> bool {
 }
 
 #[cfg(test)]
-mod tests {
-    use std::cell::RefCell;
-    use std::rc::Rc;
-
-    use wasm_bindgen_test::wasm_bindgen_test;
-
-    use super::*;
-
-    type RecordedRequests = Rc>>;
-    type FixtureHost = WebviewGatewayHost;
-
-    struct FixtureTransport {
-        requests: RecordedRequests,
-    }
-
-    impl FixtureTransport {
-        fn new(requests: RecordedRequests) -> Self {
-            Self { requests }
-        }
-    }
-
-    #[async_trait(?Send)]
-    impl GatewayTransport for FixtureTransport {
-        async fn send(&self, request: GatewayRequest) -> WebviewResult {
-            self.requests.borrow_mut().push(request);
-            let request =
-                self.requests.borrow().last().cloned().ok_or_else(|| {
-                    WebviewError::Transport("missing fixture request".to_string())
-                })?;
-            let mut headers = vec![GatewayHeader::new("content-type", "text/html")?];
-            if let Some(source) = request.source_origin {
-                headers.push(GatewayHeader::new(
-                    "access-control-allow-origin",
-                    source.origin().ascii_serialization(),
-                )?);
-            }
-            GatewayResponse::new(200, headers, b"".to_vec())
-        }
-    }
-
-    fn fixture_host() -> WebviewResult<(FixtureHost, RecordedRequests)> {
-        let prefix = GatewayPrefix::new(GATEWAY_PREFIX)?;
-        let policy = GatewayRoutePolicy::new(
-            TargetUrl::parse("https://frontend.rings.test/")?.into_url(),
-            prefix.clone(),
-        )?;
-        let requests = Rc::new(RefCell::new(Vec::new()));
-        let host = WebviewGatewayHost {
-            policy,
-            gateway: ConcurrentWebviewGateway::new(prefix, FixtureTransport::new(requests.clone()))
-                .with_target_bootstrap(webview_bootstrap),
-            limiter: GatewayRequestLimiter::new(MAX_CONCURRENT_GATEWAY_REQUESTS),
-        };
-        Ok((host, requests))
-    }
-
-    #[wasm_bindgen_test]
-    fn browser_request_allows_source_free_subresources() -> WebviewResult<()> {
-        let value = Object::new();
-        crate::browser_api::js_set(
-            &value,
-            "requested",
-            &JsValue::from_str("https://static.example.test/site.css"),
-        )
-        .map_err(WebviewError::Browser)?;
-        crate::browser_api::js_set(&value, "method", &JsValue::from_str("GET"))
-            .map_err(WebviewError::Browser)?;
-        crate::browser_api::js_set(&value, "kind", &JsValue::from_str("subresource"))
-            .map_err(WebviewError::Browser)?;
-
-        let request = browser_host_request(&value.into()).map_err(WebviewError::Browser)?;
-
-        assert_eq!(request.kind, GatewayRequestKind::Subresource);
-        assert!(request.source_target.is_none());
-        Ok(())
-    }
-
-    #[wasm_bindgen_test]
-    fn host_redirects_then_serves_a_gateway_document_through_its_transport() -> WebviewResult<()> {
-        let (host, requests) = fixture_host()?;
-        let target = TargetUrl::parse("https://example.test/docs/index.html")?;
-        let headers = vec![GatewayHeader::new("accept", "text/html")?];
-        let body = vec![0x00, 0xff];
-        let redirect =
-            futures::executor::block_on(host.handle(WebviewHostRequest::navigation_with_payload(
-                target.clone(),
-                "POST",
-                headers.clone(),
-                body.clone(),
-            )))?;
-        let WebviewHostOutcome::Redirect(gateway_url) = redirect else {
-            return Err(WebviewError::Transport(
-                "navigation did not redirect to gateway".to_string(),
-            ));
-        };
-
-        let response =
-            futures::executor::block_on(host.handle(WebviewHostRequest::navigation_with_payload(
-                TargetUrl::parse(gateway_url.as_str())?,
-                "POST",
-                headers,
-                body,
-            )))?;
-        let WebviewHostOutcome::Response(response) = response else {
-            return Err(WebviewError::Transport(
-                "gateway document was not served".to_string(),
-            ));
-        };
-        let body = String::from_utf8(response.body)
-            .map_err(|error| WebviewError::Transport(error.to_string()))?;
-
-        assert!(body.contains("data-rings-webview-bootstrap"));
-        assert!(body.contains("/webview/https%3A%2F%2Fexample%2Etest%2Fasset%2Epng"));
-        assert_eq!(requests.borrow().len(), 1);
-        let sent_request = requests
-            .borrow()
-            .first()
-            .cloned()
-            .ok_or_else(|| WebviewError::Transport("missing gateway request".to_string()))?;
-        assert_eq!(sent_request.target.as_str(), target.as_url().as_str());
-        assert_eq!(sent_request.method, "POST");
-        assert_eq!(sent_request.body, vec![0x00, 0xff]);
-        assert_eq!(sent_request.headers, vec![GatewayHeader::new(
-            "accept",
-            "text/html"
-        )?]);
-        Ok(())
-    }
-
-    #[wasm_bindgen_test]
-    fn host_serves_cross_target_runtime_reads_when_upstream_allows_cors() -> WebviewResult<()> {
-        let (host, requests) = fixture_host()?;
-        let source = TargetUrl::parse("https://app.example.test/index.html")?;
-        let target = TargetUrl::parse("https://bank.example.test/account")?;
-
-        let outcome = futures::executor::block_on(host.handle(WebviewHostRequest::fetch(
-            target,
-            source.clone(),
-            "GET",
-            Vec::new(),
-            Vec::new(),
-        )))?;
-
-        assert!(matches!(outcome, WebviewHostOutcome::Response(_)));
-        let request =
-            requests.borrow().first().cloned().ok_or_else(|| {
-                WebviewError::Transport("missing cross-origin request".to_string())
-            })?;
-        assert_eq!(request.source_origin.as_ref(), Some(source.as_url()));
-        Ok(())
-    }
-
-    #[wasm_bindgen_test]
-    fn onion_route_unavailable_is_reported_without_wasm_stack() -> WebviewResult<()> {
-        let response = browser_transport_failure(WebviewError::Transport(
-            "onion proxy request failed: Onion route error: no live onion exit offers service \"https\""
-                .to_string(),
-        ));
-
-        let status = crate::browser_api::js_prop(&response, "status")
-            .map_err(WebviewError::Browser)?
-            .as_f64()
-            .ok_or_else(|| WebviewError::Browser("failure status was not numeric".to_string()))?;
-        let error = crate::browser_api::js_string_field(&response, "error")
-            .map_err(WebviewError::Browser)?;
-        let code = crate::browser_api::js_string_field(&response, "errorCode")
-            .map_err(WebviewError::Browser)?;
-        let summary = crate::browser_api::js_string_field(&response, "errorSummary")
-            .map_err(WebviewError::Browser)?;
-
-        assert_eq!(status, 503.0);
-        assert_eq!(code, "onion_exit_unavailable");
-        assert_eq!(summary, "No live HTTPS onion exit is available.");
-        assert_eq!(
-            error,
-            "gateway transport failed: onion proxy request failed: Onion route error: no live onion exit offers service \"https\""
-        );
-        assert!(!error.contains("wasm-function"));
-        Ok(())
-    }
-
-    #[wasm_bindgen_test]
-    fn http_origin_predicate_excludes_extension_and_file_hosts() {
-        assert!(is_http_origin("https://frontend.rings.test"));
-        assert!(is_http_origin("http://127.0.0.1:8080"));
-        assert!(!is_http_origin("chrome-extension://rings"));
-        assert!(!is_http_origin("null"));
-    }
-}
+mod tests;
 
 #[cfg(all(test, target_arch = "wasm32"))]
 mod onion_browser_tests;
diff --git a/frontend/src/webview/tests.rs b/frontend/src/webview/tests.rs
new file mode 100644
index 000000000..d95c9024f
--- /dev/null
+++ b/frontend/src/webview/tests.rs
@@ -0,0 +1,189 @@
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use wasm_bindgen_test::wasm_bindgen_test;
+
+use super::*;
+
+type RecordedRequests = Rc>>;
+type FixtureHost = WebviewGatewayHost;
+
+struct FixtureTransport {
+    requests: RecordedRequests,
+}
+
+impl FixtureTransport {
+    fn new(requests: RecordedRequests) -> Self {
+        Self { requests }
+    }
+}
+
+#[async_trait(?Send)]
+impl GatewayTransport for FixtureTransport {
+    async fn send(&self, request: GatewayRequest) -> WebviewResult {
+        self.requests.borrow_mut().push(request);
+        let request =
+            self.requests.borrow().last().cloned().ok_or_else(|| {
+                WebviewError::Transport("missing fixture request".to_string())
+            })?;
+        let mut headers = vec![GatewayHeader::new("content-type", "text/html")?];
+        if let Some(source) = request.source_origin {
+            headers.push(GatewayHeader::new(
+                "access-control-allow-origin",
+                source.origin().ascii_serialization(),
+            )?);
+        }
+        GatewayResponse::new(200, headers, b"".to_vec())
+    }
+}
+
+fn fixture_host() -> WebviewResult<(FixtureHost, RecordedRequests)> {
+    let prefix = GatewayPrefix::new(GATEWAY_PREFIX)?;
+    let policy = GatewayRoutePolicy::new(
+        TargetUrl::parse("https://frontend.rings.test/")?.into_url(),
+        prefix.clone(),
+    )?;
+    let requests = Rc::new(RefCell::new(Vec::new()));
+    let host = WebviewGatewayHost {
+        policy,
+        gateway: ConcurrentWebviewGateway::new(prefix, FixtureTransport::new(requests.clone()))
+            .with_target_bootstrap(webview_bootstrap),
+        limiter: GatewayRequestLimiter::new(MAX_CONCURRENT_GATEWAY_REQUESTS),
+    };
+    Ok((host, requests))
+}
+
+#[wasm_bindgen_test]
+fn browser_request_allows_source_free_subresources() -> WebviewResult<()> {
+    let value = Object::new();
+    crate::browser_api::js_set(
+        &value,
+        "requested",
+        &JsValue::from_str("https://static.example.test/site.css"),
+    )
+    .map_err(WebviewError::Browser)?;
+    crate::browser_api::js_set(&value, "method", &JsValue::from_str("GET"))
+        .map_err(WebviewError::Browser)?;
+    crate::browser_api::js_set(&value, "kind", &JsValue::from_str("subresource"))
+        .map_err(WebviewError::Browser)?;
+
+    let request = browser_host_request(&value.into()).map_err(WebviewError::Browser)?;
+
+    assert_eq!(request.kind, GatewayRequestKind::Subresource);
+    assert!(request.source_target.is_none());
+    Ok(())
+}
+
+#[wasm_bindgen_test]
+fn host_redirects_then_serves_a_gateway_document_through_its_transport() -> WebviewResult<()> {
+    let (host, requests) = fixture_host()?;
+    let target = TargetUrl::parse("https://example.test/docs/index.html")?;
+    let headers = vec![GatewayHeader::new("accept", "text/html")?];
+    let body = vec![0x00, 0xff];
+    let redirect =
+        futures::executor::block_on(host.handle(WebviewHostRequest::navigation_with_payload(
+            target.clone(),
+            "POST",
+            headers.clone(),
+            body.clone(),
+        )))?;
+    let WebviewHostOutcome::Redirect(gateway_url) = redirect else {
+        return Err(WebviewError::Transport(
+            "navigation did not redirect to gateway".to_string(),
+        ));
+    };
+
+    let response =
+        futures::executor::block_on(host.handle(WebviewHostRequest::navigation_with_payload(
+            TargetUrl::parse(gateway_url.as_str())?,
+            "POST",
+            headers,
+            body,
+        )))?;
+    let WebviewHostOutcome::Response(response) = response else {
+        return Err(WebviewError::Transport(
+            "gateway document was not served".to_string(),
+        ));
+    };
+    let body = String::from_utf8(response.body)
+        .map_err(|error| WebviewError::Transport(error.to_string()))?;
+
+    assert!(body.contains("data-rings-webview-bootstrap"));
+    assert!(body.contains("/webview/https%3A%2F%2Fexample%2Etest%2Fasset%2Epng"));
+    assert_eq!(requests.borrow().len(), 1);
+    let sent_request = requests
+        .borrow()
+        .first()
+        .cloned()
+        .ok_or_else(|| WebviewError::Transport("missing gateway request".to_string()))?;
+    assert_eq!(sent_request.target.as_str(), target.as_url().as_str());
+    assert_eq!(sent_request.method, "POST");
+    assert_eq!(sent_request.body, vec![0x00, 0xff]);
+    assert_eq!(sent_request.headers, vec![GatewayHeader::new(
+        "accept",
+        "text/html"
+    )?]);
+    Ok(())
+}
+
+#[wasm_bindgen_test]
+fn host_serves_cross_target_runtime_reads_when_upstream_allows_cors() -> WebviewResult<()> {
+    let (host, requests) = fixture_host()?;
+    let source = TargetUrl::parse("https://app.example.test/index.html")?;
+    let target = TargetUrl::parse("https://bank.example.test/account")?;
+
+    let outcome = futures::executor::block_on(host.handle(WebviewHostRequest::fetch(
+        target,
+        source.clone(),
+        "GET",
+        Vec::new(),
+        Vec::new(),
+    )))?;
+
+    assert!(matches!(outcome, WebviewHostOutcome::Response(_)));
+    let request =
+        requests.borrow().first().cloned().ok_or_else(|| {
+            WebviewError::Transport("missing cross-origin request".to_string())
+        })?;
+    assert_eq!(request.source_origin.as_ref(), Some(source.as_url()));
+    Ok(())
+}
+
+#[wasm_bindgen_test]
+fn onion_route_unavailable_is_reported_without_wasm_stack() -> WebviewResult<()> {
+    let response = browser_transport_failure(onion_gateway_failure(
+        onion::OnionProxyError::classified(
+        "onion proxy request failed: Onion route error: no live onion exit offers service \"https\""
+            .to_string(),
+        ),
+    ));
+
+    let status = crate::browser_api::js_prop(&response, "status")
+        .map_err(WebviewError::Browser)?
+        .as_f64()
+        .ok_or_else(|| WebviewError::Browser("failure status was not numeric".to_string()))?;
+    let error = crate::browser_api::js_string_field(&response, "error")
+        .map_err(WebviewError::Browser)?;
+    let code = crate::browser_api::js_string_field(&response, "errorCode")
+        .map_err(WebviewError::Browser)?;
+    let summary = crate::browser_api::js_string_field(&response, "errorSummary")
+        .map_err(WebviewError::Browser)?;
+
+    assert_eq!(status, 503.0);
+    assert_eq!(code, "onion_exit_unavailable");
+    assert_eq!(summary, "No live HTTPS onion exit is available.");
+    assert_eq!(
+        error,
+        "gateway transport failed: onion proxy request failed: Onion route error: no live onion exit offers service \"https\""
+    );
+    assert!(!error.contains("wasm-function"));
+    Ok(())
+}
+
+#[wasm_bindgen_test]
+fn http_origin_predicate_excludes_extension_and_file_hosts() {
+    assert!(is_http_origin("https://frontend.rings.test"));
+    assert!(is_http_origin("http://127.0.0.1:8080"));
+    assert!(!is_http_origin("chrome-extension://rings"));
+    assert!(!is_http_origin("null"));
+}
\ No newline at end of file
diff --git a/frontend/src/workbench.rs b/frontend/src/workbench.rs
index 8f755dda5..d67f1504c 100644
--- a/frontend/src/workbench.rs
+++ b/frontend/src/workbench.rs
@@ -142,7 +142,9 @@ async fn build_onion_route(
         if let Some(bridge) = backend.bridge {
             extension::extension_onion_proxy_route(&bridge, request).await
         } else if let Some(node) = backend.node {
-            onion::route(&node.provider, request).await
+            onion::route(&node.provider, request)
+                .await
+                .map_err(|error| error.to_string())
         } else {
             Err("start the node first".to_string())
         }
@@ -289,7 +291,9 @@ async fn send_onion_request(
         if let Some(bridge) = backend.bridge {
             extension::extension_onion_proxy_request(&bridge, request).await
         } else if let Some(node) = backend.node {
-            onion::request(&node.provider, request).await
+            onion::request(&node.provider, request)
+                .await
+                .map_err(|error| error.to_string())
         } else {
             Err("start the node first".to_string())
         }

From 559e1d5e2d96bc218e04d56ca5eaf5e71a8d4738 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Wed, 22 Jul 2026 18:59:49 +0800
Subject: [PATCH 08/23] Address webview gateway review feedback

---
 crates/core/src/swarm/callback.rs             |  41 +++-
 crates/core/src/swarm/transport.rs            |   7 +-
 crates/core/src/swarm/transport/pending.rs    | 218 +++++++++++++++++-
 crates/core/src/swarm/transport/tests.rs      |  37 ++-
 frontend/rings-webview-service-worker.js      |  82 ++++++-
 .../scripts/test-webview-service-worker.mts   | 114 +++++++++
 frontend/src/app.rs                           |  14 +-
 frontend/src/controls.rs                      |   1 +
 frontend/src/controls/sidebar.rs              |  36 +--
 frontend/src/onion.rs                         |   5 +-
 frontend/src/webview.rs                       |  58 ++---
 frontend/src/webview/onion_browser_tests.rs   |  24 +-
 package.json                                  |   3 +-
 13 files changed, 539 insertions(+), 101 deletions(-)
 create mode 100644 frontend/scripts/test-webview-service-worker.mts

diff --git a/crates/core/src/swarm/callback.rs b/crates/core/src/swarm/callback.rs
index f7d645705..49da9c904 100644
--- a/crates/core/src/swarm/callback.rs
+++ b/crates/core/src/swarm/callback.rs
@@ -150,6 +150,27 @@ impl InnerSwarmCallback {
         Ok(true)
     }
 
+    async fn handle_pending_terminal_event(
+        &self,
+        did: Did,
+        operation: &str,
+    ) -> Result {
+        let Some(attempt) = self.pending_attempt else {
+            return Ok(false);
+        };
+        if self.transport.cancel_pending_connection(attempt).await? {
+            self.transport.record_peer_disconnected(did).await;
+            return Ok(true);
+        }
+        if self.transport.is_admitted_connection_attempt(attempt) {
+            return Ok(false);
+        }
+        tracing::debug!(
+            "ignoring late {operation} for {did}; pending attempt belongs to generation already superseded"
+        );
+        Ok(true)
+    }
+
     async fn handle_payload(
         &self,
         cid: &str,
@@ -279,11 +300,11 @@ impl TransportCallback for InnerSwarmCallback {
             // `Failed` and `Closed` are terminal states. Pending handshakes are
             // discarded without touching the DHT; active peers leave it.
             WebrtcConnectionState::Failed | WebrtcConnectionState::Closed => {
-                if let Some(attempt) = self.pending_attempt {
-                    if self.transport.cancel_pending_connection(attempt).await? {
-                        self.transport.record_peer_disconnected(did).await;
-                        return Ok(());
-                    }
+                if self
+                    .handle_pending_terminal_event(did, "connection terminal state")
+                    .await?
+                {
+                    return Ok(());
                 }
                 if !self.transport.is_admitted_connection(did) {
                     return Ok(());
@@ -360,11 +381,11 @@ impl TransportCallback for InnerSwarmCallback {
         // instead of waiting for the ICE state to reach `Failed`. This is the
         // graceful counterpart to a local `disconnect()`: the remote learns of
         // it promptly without relying on the transient `Disconnected` state.
-        if let Some(attempt) = self.pending_attempt {
-            if self.transport.cancel_pending_connection(attempt).await? {
-                self.transport.record_peer_disconnected(did).await;
-                return Ok(());
-            }
+        if self
+            .handle_pending_terminal_event(did, "data-channel close")
+            .await?
+        {
+            return Ok(());
         }
         if !self.transport.is_admitted_connection(did) {
             return Ok(());
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index f7d181855..af6b60273 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -1,5 +1,4 @@
 use std::collections::BTreeMap;
-use std::collections::BTreeSet;
 use std::sync::Arc;
 use std::sync::Mutex;
 use std::time::Duration;
@@ -92,7 +91,7 @@ pub struct SwarmTransport {
     dht_virtual_nodes: u16,
     reassembly_limits: ReassemblyLimits,
     pending_peers: Mutex>,
-    active_peers: Mutex>,
+    active_peers: Mutex>,
     storage_lookup_observations: Mutex,
     pending_storage_sync_acks: Mutex,
     measured_disconnects: Mutex>,
@@ -176,7 +175,7 @@ impl SwarmTransport {
             dht_virtual_nodes: settings.dht_virtual_nodes,
             reassembly_limits: settings.reassembly_limits,
             pending_peers: Mutex::new(PendingPeerPool::new()),
-            active_peers: Mutex::new(BTreeSet::new()),
+            active_peers: Mutex::new(BTreeMap::new()),
             storage_lookup_observations: Mutex::new(BTreeMap::new()),
             pending_storage_sync_acks: Mutex::new(BTreeMap::new()),
             measured_disconnects: Mutex::new(BTreeMap::new()),
@@ -352,7 +351,7 @@ impl SwarmTransport {
 
     fn active_peer_ids(&self) -> Vec {
         self.active_peers()
-            .map(|active| active.iter().copied().collect())
+            .map(|active| active.keys().copied().collect())
             .unwrap_or_default()
     }
 
diff --git a/crates/core/src/swarm/transport/pending.rs b/crates/core/src/swarm/transport/pending.rs
index bed59a01a..8ab1ff24f 100644
--- a/crates/core/src/swarm/transport/pending.rs
+++ b/crates/core/src/swarm/transport/pending.rs
@@ -1,5 +1,4 @@
 use std::collections::BTreeMap;
-use std::collections::BTreeSet;
 
 use rings_transport::core::transport::TransportInterface;
 use rings_transport::core::transport::WebrtcConnectionState;
@@ -72,10 +71,13 @@ impl PendingPeerPool {
             peer,
             generation: self.next_generation,
         };
-        self.peers.insert(peer, PendingPeer {
-            generation: attempt.generation,
-            admitted_at_ms: now_ms,
-        });
+        self.peers.insert(
+            peer,
+            PendingPeer {
+                generation: attempt.generation,
+                admitted_at_ms: now_ms,
+            },
+        );
         Ok(attempt)
     }
 
@@ -128,7 +130,7 @@ impl SwarmTransport {
             .map_err(|_| Error::SwarmConnectionLifecycleLock)
     }
 
-    pub(super) fn active_peers(&self) -> Result>> {
+    pub(super) fn active_peers(&self) -> Result>> {
         self.active_peers
             .lock()
             .map_err(|_| Error::SwarmConnectionLifecycleLock)
@@ -155,7 +157,17 @@ impl SwarmTransport {
     /// even after WebRTC reports `Closed`.
     pub(crate) fn is_admitted_connection(&self, peer: Did) -> bool {
         self.active_peers()
-            .map(|active| active.contains(&peer))
+            .map(|active| active.contains_key(&peer))
+            .unwrap_or(false)
+    }
+
+    /// Return whether `attempt` owns the current active slot for its peer.
+    ///
+    /// Invariant: a terminal callback may remove an active peer only when its
+    /// generation equals the generation admitted by data-channel open.
+    pub(crate) fn is_admitted_connection_attempt(&self, attempt: PendingConnectionAttempt) -> bool {
+        self.active_peers()
+            .map(|active| active.get(&attempt.peer).copied() == Some(attempt.generation))
             .unwrap_or(false)
     }
 
@@ -211,16 +223,20 @@ impl SwarmTransport {
             return Ok(false);
         }
         drop(pending);
-        self.active_peers()?.insert(attempt.peer);
+        self.active_peers()?
+            .insert(attempt.peer, attempt.generation);
         Ok(true)
     }
 
-    fn retire_pending_connection(&self, attempt: PendingConnectionAttempt) -> Result {
+    pub(super) fn retire_pending_connection(
+        &self,
+        attempt: PendingConnectionAttempt,
+    ) -> Result {
         Ok(self.pending_peers()?.remove(attempt))
     }
 
     pub(super) fn retire_active_connection(&self, peer: Did) -> Result {
-        Ok(self.active_peers()?.remove(&peer))
+        Ok(self.active_peers()?.remove(&peer).is_some())
     }
 
     /// Cancel a current pending handshake and release its non-routable transport object.
@@ -290,3 +306,185 @@ impl SwarmTransport {
         Ok(self.pending_peers()?.len())
     }
 }
+
+#[cfg(test)]
+mod lifecycle_model {
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum PeerLifecycle {
+        Absent,
+        Pending(u64),
+        Active(u64),
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum CallbackGeneration {
+        Current,
+        Previous,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    enum LifecycleAction {
+        Replacement,
+        Open(CallbackGeneration),
+        Close(CallbackGeneration),
+        Failed(CallbackGeneration),
+        Timeout,
+    }
+
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    struct LifecycleModel {
+        peer: PeerLifecycle,
+        next_generation: u64,
+        previous_generation: Option,
+        dht_member: bool,
+        transport_slot: bool,
+    }
+
+    impl Default for LifecycleModel {
+        fn default() -> Self {
+            Self {
+                peer: PeerLifecycle::Absent,
+                next_generation: 0,
+                previous_generation: None,
+                dht_member: false,
+                transport_slot: false,
+            }
+        }
+    }
+
+    impl LifecycleModel {
+        fn apply(mut self, action: LifecycleAction) -> Self {
+            match action {
+                LifecycleAction::Replacement => self.replace_pending(),
+                LifecycleAction::Open(callback) => self.open(callback),
+                LifecycleAction::Close(callback) | LifecycleAction::Failed(callback) => {
+                    self.terminal(callback)
+                }
+                LifecycleAction::Timeout => self.timeout(),
+            }
+            self
+        }
+
+        fn replace_pending(&mut self) {
+            if let PeerLifecycle::Active(_) = self.peer {
+                return;
+            }
+            self.remember_current_generation();
+            self.next_generation = self.next_generation.saturating_add(1);
+            self.peer = PeerLifecycle::Pending(self.next_generation);
+            self.dht_member = false;
+            self.transport_slot = true;
+        }
+
+        fn open(&mut self, callback: CallbackGeneration) {
+            let Some(callback_generation) = self.callback_generation(callback) else {
+                return;
+            };
+            if self.peer == PeerLifecycle::Pending(callback_generation) {
+                self.peer = PeerLifecycle::Active(callback_generation);
+                self.dht_member = true;
+                self.transport_slot = true;
+            }
+        }
+
+        fn terminal(&mut self, callback: CallbackGeneration) {
+            let Some(callback_generation) = self.callback_generation(callback) else {
+                return;
+            };
+            if self.generation_matches_live_slot(callback_generation) {
+                self.previous_generation = Some(callback_generation);
+                self.peer = PeerLifecycle::Absent;
+                self.dht_member = false;
+                self.transport_slot = false;
+            }
+        }
+
+        fn timeout(&mut self) {
+            if let PeerLifecycle::Pending(generation) = self.peer {
+                self.previous_generation = Some(generation);
+                self.peer = PeerLifecycle::Absent;
+                self.dht_member = false;
+                self.transport_slot = false;
+            }
+        }
+
+        fn callback_generation(self, callback: CallbackGeneration) -> Option {
+            match callback {
+                CallbackGeneration::Current => self.current_generation(),
+                CallbackGeneration::Previous => self.previous_generation,
+            }
+        }
+
+        fn current_generation(self) -> Option {
+            match self.peer {
+                PeerLifecycle::Absent => None,
+                PeerLifecycle::Pending(generation) | PeerLifecycle::Active(generation) => {
+                    Some(generation)
+                }
+            }
+        }
+
+        fn remember_current_generation(&mut self) {
+            if let Some(generation) = self.current_generation() {
+                self.previous_generation = Some(generation);
+            }
+        }
+
+        fn generation_matches_live_slot(self, generation: u64) -> bool {
+            matches!(
+                self.peer,
+                PeerLifecycle::Pending(current) | PeerLifecycle::Active(current) if current == generation
+            )
+        }
+
+        fn assert_invariants(self) {
+            // Invariant: Pending(g) is a physical transport slot only; it is not a Chord member.
+            if matches!(self.peer, PeerLifecycle::Pending(_)) {
+                assert!(
+                    !self.dht_member,
+                    "pending peers must never be routable: {self:?}"
+                );
+            }
+            assert_eq!(
+                self.dht_member,
+                matches!(self.peer, PeerLifecycle::Active(_)),
+                "only admitted active peers may appear in DHT membership: {self:?}"
+            );
+            assert_eq!(
+                self.transport_slot,
+                matches!(
+                    self.peer,
+                    PeerLifecycle::Pending(_) | PeerLifecycle::Active(_)
+                ),
+                "terminal and expiry transitions must remove the transport slot: {self:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn pending_admission_model_preserves_generation_and_routing_invariants() {
+        const MAX_DEPTH: usize = 4;
+        let actions = [
+            LifecycleAction::Replacement,
+            LifecycleAction::Open(CallbackGeneration::Current),
+            LifecycleAction::Open(CallbackGeneration::Previous),
+            LifecycleAction::Close(CallbackGeneration::Current),
+            LifecycleAction::Close(CallbackGeneration::Previous),
+            LifecycleAction::Failed(CallbackGeneration::Current),
+            LifecycleAction::Failed(CallbackGeneration::Previous),
+            LifecycleAction::Timeout,
+        ];
+
+        explore(LifecycleModel::default(), &actions, MAX_DEPTH);
+    }
+
+    fn explore(model: LifecycleModel, actions: &[LifecycleAction], remaining_depth: usize) {
+        model.assert_invariants();
+        if remaining_depth == 0 {
+            return;
+        }
+        for action in actions.iter().copied() {
+            explore(model.apply(action), actions, remaining_depth - 1);
+        }
+    }
+}
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index 0d6c2007c..98a9c1bc7 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -291,6 +291,30 @@ async fn mismatched_pending_callback_cancels_attempt_without_admission() -> Resu
     Ok(())
 }
 
+#[tokio::test]
+async fn late_terminal_callback_cannot_remove_replacement_active_slot() -> Result<()> {
+    let transport = Arc::new(transport_with_measure(Arc::new(
+        RecordingMeasure::default(),
+    ))?);
+    let peer = SecretKey::random().address().into();
+    let old_attempt = transport.reserve_pending_connection(peer).await?;
+    assert!(transport.retire_pending_connection(old_attempt)?);
+    let current_attempt = transport.reserve_pending_connection(peer).await?;
+    assert!(transport.promote_pending_connection(current_attempt)?);
+    let late_callback =
+        InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback))
+            .with_pending_connection_attempt(old_attempt);
+
+    late_callback
+        .on_peer_connection_state_change(&peer.to_string(), WebrtcConnectionState::Closed)
+        .await
+        .map_err(|error| Error::InvalidMessage(error.to_string()))?;
+
+    assert!(transport.is_admitted_connection_attempt(current_attempt));
+    assert_eq!(transport.admitted_connection_ids(), vec![peer]);
+    Ok(())
+}
+
 #[test]
 fn connection_offer_protocol_mode_includes_storage_redundancy() -> Result<()> {
     let transport = transport_with_measure(Arc::new(RecordingMeasure::default()))?;
@@ -343,11 +367,14 @@ async fn disconnected_observation_is_once_per_connection_epoch() -> Result<()> {
     transport.record_peer_disconnected(peer).await;
     assert!(transport.peer_disconnected_since_ms(peer).is_some());
 
-    assert_eq!(measure.snapshot_counters()?.as_slice(), &[
-        (peer, MeasureCounter::Disconnected),
-        (peer, MeasureCounter::Connect),
-        (peer, MeasureCounter::Disconnected),
-    ]);
+    assert_eq!(
+        measure.snapshot_counters()?.as_slice(),
+        &[
+            (peer, MeasureCounter::Disconnected),
+            (peer, MeasureCounter::Connect),
+            (peer, MeasureCounter::Disconnected),
+        ]
+    );
 
     Ok(())
 }
diff --git a/frontend/rings-webview-service-worker.js b/frontend/rings-webview-service-worker.js
index 3954eb1f8..8c196f169 100644
--- a/frontend/rings-webview-service-worker.js
+++ b/frontend/rings-webview-service-worker.js
@@ -63,7 +63,27 @@ async function handleGatewayFetch(event) {
   const requestId = nextRequestId;
   nextRequestId += 1;
   const startedAt = performance.now();
-  const request = await serializeRequest(event);
+  let request;
+  try {
+    request = await serializeRequest(event);
+  } catch (error) {
+    request = debugRequestForFailure(event.request);
+    await emitResourceDebug(
+      requestId,
+      request,
+      startedAt,
+      "failed",
+      `#${requestId} rejected malformed gateway request: ${errorMessage(error)}`,
+      "error",
+      400,
+    );
+    return gatewayFailure(
+      400,
+      errorMessage(error),
+      "Malformed Rings WebView gateway request.",
+      "invalid_gateway_request",
+    );
+  }
   await emitResourceDebug(
     requestId,
     request,
@@ -300,6 +320,7 @@ function queryGatewayHost(client) {
 async function serializeRequest(event) {
   const request = event.request;
   const sourceTarget = await sourceTargetForClient(event.clientId);
+  const kind = requestKind(request);
   const body = request.method === "GET" || request.method === "HEAD"
     ? undefined
     : await request.clone().arrayBuffer();
@@ -312,7 +333,19 @@ async function serializeRequest(event) {
       .filter(([name]) => name.toLowerCase() !== "x-rings-webview-kind")
       .map(([name, value]) => ({ name, value })),
     body,
-    kind: requestKind(request),
+    kind,
+  };
+}
+
+function debugRequestForFailure(request) {
+  return {
+    requested: request.url,
+    sourceTarget: undefined,
+    method: request.method || "GET",
+    credentials: request.credentials,
+    headers: [],
+    body: undefined,
+    kind: "invalid",
   };
 }
 
@@ -340,18 +373,49 @@ async function sourceTargetForClient(clientId) {
 }
 
 function requestKind(request) {
-  const taggedKind = request.headers.get("x-rings-webview-kind");
-  if (taggedKind === "fetch" || taggedKind === "xhr" || taggedKind === "navigation") {
-    return taggedKind;
+  if (isNavigationRequest(request)) {
+    return "navigation";
   }
-  if (
+  const taggedKind = runtimeKindTag(request);
+  if (isRuntimeReadableRequest(request)) {
+    return taggedKind || "fetch";
+  }
+  if (taggedKind) {
+    throw new Error(`X-Rings-Webview-Kind is only valid for runtime requests, got ${taggedKind}`);
+  }
+  return "subresource";
+}
+
+function isNavigationRequest(request) {
+  return (
     request.mode === "navigate"
     || request.destination === "document"
     || request.destination === "iframe"
-  ) {
-    return "navigation";
+  );
+}
+
+function isRuntimeReadableRequest(request) {
+  return !request.destination;
+}
+
+function runtimeKindTag(request) {
+  const rawKind = request.headers.get("x-rings-webview-kind");
+  if (rawKind == null) {
+    return undefined;
   }
-  return "subresource";
+  const values = rawKind.split(",").map((value) => value.trim()).filter(Boolean);
+  if (values.length !== 1 || !isRuntimeKind(values[0])) {
+    throw new Error(`invalid X-Rings-Webview-Kind: ${rawKind}`);
+  }
+  return values[0];
+}
+
+function isRuntimeKind(kind) {
+  return kind === "fetch" || kind === "xhr";
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
 }
 
 function requestGatewayResponse(host, request) {
diff --git a/frontend/scripts/test-webview-service-worker.mts b/frontend/scripts/test-webview-service-worker.mts
new file mode 100644
index 000000000..3efac9da2
--- /dev/null
+++ b/frontend/scripts/test-webview-service-worker.mts
@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * Runs unit checks for the Rings WebView service-worker request classifier.
+ */
+
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import vm from "node:vm";
+
+/**
+ * Minimal request shape consumed by the service worker's request-kind classifier.
+ */
+type RequestKindFixture = {
+  readonly headers: Headers;
+  readonly mode: string;
+  readonly destination: string;
+};
+
+/**
+ * Options used to build one request-kind fixture.
+ */
+type RequestKindFixtureOptions = {
+  readonly headers?: HeadersInit;
+  readonly mode?: string;
+  readonly destination?: string;
+};
+
+/**
+ * Service-worker symbols exported only inside this test VM.
+ */
+type ServiceWorkerTestApi = {
+  readonly requestKind: (request: RequestKindFixture) => string;
+};
+
+/**
+ * VM global shape needed to load the service worker without a browser.
+ */
+type ServiceWorkerTestContext = Record & {
+  self: {
+    readonly location: URL;
+    addEventListener: () => void;
+  };
+  __ringsWebviewServiceWorkerTest?: ServiceWorkerTestApi;
+};
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const projectRoot = frontendProjectRoot(scriptDir);
+const serviceWorkerPath = resolve(projectRoot, "rings-webview-service-worker.js");
+const serviceWorkerSource = await readFile(serviceWorkerPath, "utf8");
+const context: ServiceWorkerTestContext = {
+  console,
+  Headers,
+  URL,
+  Response,
+  performance,
+  setTimeout,
+  clearTimeout,
+  self: {
+    location: new URL("http://127.0.0.1:8080/"),
+    addEventListener() {},
+  },
+};
+context.globalThis = context;
+
+vm.runInNewContext(`${serviceWorkerSource}\nglobalThis.__ringsWebviewServiceWorkerTest = { requestKind };`, context, {
+  filename: serviceWorkerPath,
+});
+
+const serviceWorkerApi = context.__ringsWebviewServiceWorkerTest;
+assert(serviceWorkerApi, "service worker test API was not exported");
+const { requestKind } = serviceWorkerApi;
+
+/**
+ * Resolves the frontend project root from either source or generated script paths.
+ */
+function frontendProjectRoot(currentScriptDir: string): string {
+  const parentDir = dirname(currentScriptDir);
+  if (parentDir.endsWith("/.generated")) {
+    return resolve(parentDir, "..");
+  }
+  return resolve(currentScriptDir, "..");
+}
+
+/**
+ * Builds the minimum request object needed by `requestKind`.
+ */
+function request(options: RequestKindFixtureOptions = {}): RequestKindFixture {
+  return {
+    headers: new Headers(options.headers),
+    mode: options.mode ?? "cors",
+    destination: options.destination ?? "",
+  };
+}
+
+assert.equal(requestKind(request({ mode: "navigate", destination: "document" })), "navigation");
+assert.equal(requestKind(request({ destination: "style" })), "subresource");
+assert.equal(requestKind(request()), "fetch");
+assert.equal(requestKind(request({ headers: { "X-Rings-Webview-Kind": "fetch" } })), "fetch");
+assert.equal(requestKind(request({ headers: { "X-Rings-Webview-Kind": "xhr" } })), "xhr");
+assert.throws(
+  () => requestKind(request({ headers: { "X-Rings-Webview-Kind": "xhr, subresource" } })),
+  /invalid X-Rings-Webview-Kind/,
+);
+assert.throws(
+  () => requestKind(request({ headers: { "X-Rings-Webview-Kind": "subresource" } })),
+  /invalid X-Rings-Webview-Kind/,
+);
+assert.throws(
+  () => requestKind(request({ headers: { "X-Rings-Webview-Kind": "xhr, xhr" } })),
+  /invalid X-Rings-Webview-Kind/,
+);
diff --git a/frontend/src/app.rs b/frontend/src/app.rs
index 3192c0d5b..e39e1c856 100644
--- a/frontend/src/app.rs
+++ b/frontend/src/app.rs
@@ -575,12 +575,14 @@ fn render_console_shell(ctx: AppRenderContext<'_>, header: Html) -> Html {
     let control_sidebar = controls::control_sidebar(
         control_view(ctx.node),
         ctx.launch_actions,
-        workbench_control,
-        webview_control,
-        *ctx.shell.active_dialog,
-        dialog_actions,
-        ctx.shell.control_sidebar_collapsed.clone(),
-        ctx.extension_mode,
+        controls::ControlSidebarShell {
+            workbench_control,
+            webview_control,
+            active_dialog: *ctx.shell.active_dialog,
+            dialog_actions,
+            collapsed: ctx.shell.control_sidebar_collapsed.clone(),
+            extension_mode: ctx.extension_mode,
+        },
     );
     let shell_class = console_shell_class(ctx.extension_mode);
     html! {
diff --git a/frontend/src/controls.rs b/frontend/src/controls.rs
index 3406f8231..f90208fe3 100644
--- a/frontend/src/controls.rs
+++ b/frontend/src/controls.rs
@@ -15,6 +15,7 @@ use crate::wallet::WalletKind;
 
 mod sidebar;
 pub(crate) use sidebar::control_sidebar;
+pub(crate) use sidebar::ControlSidebarShell;
 
 const CHROME_WEBRTC_DEBUG_URL: &str = "chrome://webrtc-internals/";
 const FIREFOX_WEBRTC_DEBUG_URL: &str = "about:webrtc";
diff --git a/frontend/src/controls/sidebar.rs b/frontend/src/controls/sidebar.rs
index bafb7a99e..0bc347bcf 100644
--- a/frontend/src/controls/sidebar.rs
+++ b/frontend/src/controls/sidebar.rs
@@ -47,44 +47,48 @@ impl ControlSidebarDerived {
     }
 }
 
+pub(crate) struct ControlSidebarShell {
+    pub(crate) workbench_control: Html,
+    pub(crate) webview_control: Option,
+    pub(crate) active_dialog: ActiveDialog,
+    pub(crate) dialog_actions: DialogActions,
+    pub(crate) collapsed: UseStateHandle,
+    pub(crate) extension_mode: bool,
+}
+
 pub(crate) fn control_sidebar(
     view: ControlView<'_>,
     actions: LaunchActions,
-    workbench_control: Html,
-    webview_control: Option,
-    active_dialog: ActiveDialog,
-    dialog_actions: DialogActions,
-    collapsed: UseStateHandle,
-    extension_mode: bool,
+    shell: ControlSidebarShell,
 ) -> Html {
     let derived = ControlSidebarDerived::from_view(&view);
     let on_copy_did = copy_local_did_callback(view.did, view.status);
     let open_settings_dialog = {
-        let open_dialog = dialog_actions.open.clone();
+        let open_dialog = shell.dialog_actions.open.clone();
         Callback::from(move |_| open_dialog.emit(ActiveDialog::Settings))
     };
-    let close_settings_dialog = dialog_actions.close.clone();
+    let close_settings_dialog = shell.dialog_actions.close.clone();
     let toggle_sidebar = {
-        let collapsed = collapsed.clone();
+        let collapsed = shell.collapsed.clone();
         Callback::from(move |_| collapsed.set(!*collapsed))
     };
-    let sidebar_class = control_sidebar_class(extension_mode, *collapsed);
+    let sidebar_class = control_sidebar_class(shell.extension_mode, *shell.collapsed);
     html! {
         
     }
 }
diff --git a/frontend/src/onion.rs b/frontend/src/onion.rs
index 4d19615e8..394deda73 100644
--- a/frontend/src/onion.rs
+++ b/frontend/src/onion.rs
@@ -1,7 +1,6 @@
 //! Onion proxy helpers for the browser frontend.
 
 use std::fmt;
-use std::sync::Arc;
 
 use js_sys::Array;
 use js_sys::Object;
@@ -336,7 +335,7 @@ pub(crate) fn format_headers(headers: &[(String, String)]) -> String {
 
 /// Build a route through an HTTPS onion exit.
 pub(crate) async fn route(
-    provider: &Arc,
+    provider: &Provider,
     request: OnionProxyRouteRequest,
 ) -> Result {
     let target_authority = target_authority(&request.url)?;
@@ -361,7 +360,7 @@ pub(crate) async fn route(
 
 /// Send one HTTPS request through an onion proxy.
 pub(crate) async fn request(
-    provider: &Arc,
+    provider: &Provider,
     request: OnionProxyHttpRequest,
 ) -> Result {
     target_authority(&request.url)?;
diff --git a/frontend/src/webview.rs b/frontend/src/webview.rs
index 70c1dffd0..b6e26c847 100644
--- a/frontend/src/webview.rs
+++ b/frontend/src/webview.rs
@@ -15,8 +15,8 @@ use js_sys::Uint8Array;
 use rings_node::provider::Provider;
 use rings_webview::browser::bootstrap_script;
 use rings_webview::ConcurrentWebviewGateway;
-use rings_webview::GatewayFailure;
 use rings_webview::GatewayCredentials;
+use rings_webview::GatewayFailure;
 use rings_webview::GatewayHeader;
 use rings_webview::GatewayPrefix;
 use rings_webview::GatewayRequest;
@@ -58,7 +58,7 @@ const WEBVIEW_OVERLAY_LOADER: &str = r#"
 "#;
 
 thread_local! {
-    static BROWSER_GATEWAY: RefCell> = RefCell::new(None);
+    static BROWSER_GATEWAY: RefCell> = const { RefCell::new(None) };
 }
 
 struct BrowserGatewayBinding {
@@ -276,12 +276,7 @@ fn browser_failure(status: u16, error: String) -> JsValue {
     )
 }
 
-fn browser_failure_with(
-    status: u16,
-    code: &str,
-    summary: &str,
-    error: String,
-) -> JsValue {
+fn browser_failure_with(status: u16, code: &str, summary: &str, error: String) -> JsValue {
     let value = Object::new();
     let _ok = crate::browser_api::js_set(&value, "ok", &JsValue::FALSE);
     let _status =
@@ -571,7 +566,7 @@ impl WebviewNode {
         }
         let controlled_origin = TargetUrl::parse(&format!("{}/", origin.trim_end_matches('/')))
             .map_err(|error| WebviewError::Browser(format!("parse frontend origin: {error}")))?;
-        Self::new(provider, controlled_origin).map(Some)
+        Self::new(Rc::new((*provider).clone()), controlled_origin).map(Some)
     }
 
     /// Handle a browser request after the host has captured it before connection dispatch.
@@ -579,7 +574,7 @@ impl WebviewNode {
         self.host.handle(request).await
     }
 
-    fn new(provider: Arc, controlled_origin: TargetUrl) -> WebviewResult {
+    fn new(provider: Rc, controlled_origin: TargetUrl) -> WebviewResult {
         let prefix = GatewayPrefix::new(GATEWAY_PREFIX)?;
         let policy = GatewayRoutePolicy::new(controlled_origin.into_url(), prefix.clone())?;
         let gateway = ConcurrentWebviewGateway::new(prefix, OnionGatewayTransport { provider })
@@ -601,7 +596,8 @@ struct WebviewGatewayHost {
 }
 
 impl WebviewGatewayHost
-where T: GatewayTransport
+where
+    T: GatewayTransport,
 {
     async fn handle(&self, request: WebviewHostRequest) -> WebviewResult {
         match self.policy.route(
@@ -685,7 +681,7 @@ impl Drop for GatewayRequestPermit {
 }
 
 struct OnionGatewayTransport {
-    provider: Arc,
+    provider: Rc,
 }
 
 #[async_trait(?Send)]
@@ -701,17 +697,20 @@ impl GatewayTransport for OnionGatewayTransport {
             )
             .await;
         }
-        let response = onion::request(&self.provider, onion::OnionProxyHttpRequest {
-            url: request.target.to_string(),
-            method: request.method,
-            headers: request
-                .headers
-                .into_iter()
-                .map(|header| (header.name, header.value))
-                .collect(),
-            body: request.body,
-            options,
-        })
+        let response = onion::request(
+            &self.provider,
+            onion::OnionProxyHttpRequest {
+                url: request.target.to_string(),
+                method: request.method,
+                headers: request
+                    .headers
+                    .into_iter()
+                    .map(|header| (header.name, header.value))
+                    .collect(),
+                body: request.body,
+                options,
+            },
+        )
         .await
         .map_err(onion_gateway_failure)?;
         let headers = response
@@ -731,16 +730,19 @@ fn should_trace_onion_route(kind: GatewayRequestKind) -> bool {
 }
 
 async fn trace_onion_route(
-    provider: &Arc,
+    provider: &Provider,
     target: &str,
     kind: GatewayRequestKind,
     options: onion::OnionProxyOptions,
 ) {
     let started = js_sys::Date::now();
-    let result = onion::route(provider, onion::OnionProxyRouteRequest {
-        url: target.to_string(),
-        options,
-    })
+    let result = onion::route(
+        provider,
+        onion::OnionProxyRouteRequest {
+            url: target.to_string(),
+            options,
+        },
+    )
     .await;
     let duration = (js_sys::Date::now() - started).max(0.0).round();
     match result {
diff --git a/frontend/src/webview/onion_browser_tests.rs b/frontend/src/webview/onion_browser_tests.rs
index 4a250707b..6d21a2c33 100644
--- a/frontend/src/webview/onion_browser_tests.rs
+++ b/frontend/src/webview/onion_browser_tests.rs
@@ -1,4 +1,4 @@
-use std::sync::Arc;
+use std::rc::Rc;
 
 use js_sys::Object;
 use js_sys::Reflect;
@@ -8,6 +8,7 @@ use rings_node::prelude::rings_core::prelude::uuid;
 use rings_node::prelude::rings_core::session::SessionSk;
 use rings_node::prelude::rings_core::storage::idb::IdbStorage;
 use rings_node::prelude::rings_core::utils::js_utils::window_sleep;
+use rings_node::processor::Processor;
 use rings_node::processor::ProcessorBuilder;
 use rings_node::processor::ProcessorConfig;
 use rings_node::provider::Provider;
@@ -148,7 +149,7 @@ async fn run_browser_onion_webview_flow() -> WebviewResult<()> {
 async fn browser_provider(
     storage_name: &str,
     exit_target: Option<&str>,
-) -> WebviewResult> {
+) -> WebviewResult> {
     let session_sk = SessionSk::new_with_seckey(&SecretKey::random()).map_err(|error| {
         WebviewError::Transport(format!("build browser session key: {error:?}"))
     })?;
@@ -174,7 +175,7 @@ async fn browser_provider(
         .dht_finger_table_size(TEST_DHT_FINGER_TABLE_SIZE)
         .build()
         .map_err(|error| WebviewError::Transport(format!("build processor: {error:?}")))?;
-    let provider = Arc::new(Provider::from_processor(Arc::new(processor)));
+    let provider = Rc::new(provider_from_processor(processor));
     provider
         .set_backend()
         .map_err(|error| WebviewError::Transport(format!("install backend: {error:?}")))?;
@@ -188,10 +189,15 @@ async fn browser_provider(
     Ok(provider)
 }
 
-async fn connect_browser_providers(
-    client: &Arc,
-    exit: &Arc,
-) -> WebviewResult<()> {
+#[expect(
+    clippy::arc_with_non_send_sync,
+    reason = "Provider::from_processor requires Arc; this browser-only test stores Provider in Rc after the API boundary"
+)]
+fn provider_from_processor(processor: Processor) -> Provider {
+    Provider::from_processor(std::sync::Arc::new(processor))
+}
+
+async fn connect_browser_providers(client: &Provider, exit: &Provider) -> WebviewResult<()> {
     let offer = string_field(
         &rpc(
             client,
@@ -214,7 +220,7 @@ async fn connect_browser_providers(
     Ok(())
 }
 
-async fn rpc(provider: &Arc, method: &str, params: JsValue) -> WebviewResult {
+async fn rpc(provider: &Provider, method: &str, params: JsValue) -> WebviewResult {
     JsFuture::from(provider.request(method.to_string(), params))
         .await
         .map_err(js_webview_error)
@@ -233,7 +239,7 @@ fn object(pairs: &[(&str, &str)]) -> JsValue {
 }
 
 fn string_field(value: &JsValue, field: &str) -> WebviewResult {
-    Reflect::get(value.as_ref(), JsValue::from_str(field).as_ref())
+    Reflect::get(value, &JsValue::from_str(field))
         .map_err(js_webview_error)?
         .as_string()
         .ok_or_else(|| WebviewError::Browser(format!("missing string field {field:?}")))
diff --git a/package.json b/package.json
index bfe1d6d10..fa7149b86 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,8 @@
     "build:frontend-extension-scripts": "npm run check:frontend-extension-scripts && rm -rf frontend/.generated && tsc -p frontend/tsconfig.extension-assets.json && tsc -p frontend/tsconfig.scripts.json && node frontend/.generated/scripts/check-extension-docs.mjs",
     "build:frontend-web": "cd frontend && NO_COLOR=true trunk build --release",
     "package:frontend-extension": "npm run build:frontend-extension-scripts && cd frontend && NO_COLOR=true trunk build --release && cd .. && node frontend/.generated/scripts/package-extension.mjs",
-    "test:frontend-extension-wallet": "npm run package:frontend-extension && node frontend/.generated/scripts/test-extension-wallet-bridge.mjs"
+    "test:frontend-extension-wallet": "npm run package:frontend-extension && node frontend/.generated/scripts/test-extension-wallet-bridge.mjs",
+    "test:frontend-webview-service-worker": "node --experimental-strip-types frontend/scripts/test-webview-service-worker.mts"
   },
   "dependencies": {
     "circomlib": "^2.0.5"

From 4a41f4c1ea7a4531bfc929043bf026a53d63f127 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Thu, 23 Jul 2026 05:14:45 +0800
Subject: [PATCH 09/23] Harden webview cluster lifecycle

---
 .gitignore                                    |   4 +
 crates/core/src/algebra.rs                    |  23 +-
 crates/core/src/dht/did.rs                    |  15 +-
 crates/core/src/dht/entry/tests.rs            |  39 +-
 crates/core/src/dht/finger.rs                 |  55 ++-
 crates/core/src/dht/stabilization.rs          | 338 +++++++++++++++---
 crates/core/src/dht/storage/mod.rs            |  90 ++++-
 crates/core/src/dht/storage/repair.rs         |   9 +-
 crates/core/src/dht/storage/tests.rs          | 128 ++++++-
 crates/core/src/dht/topology.rs               |  46 +--
 .../core/src/ecc/elgamal/impls/secp256k1.rs   |  22 +-
 crates/core/src/ecc/elgamal/mod.rs            |  18 +-
 crates/core/src/ecc/mod.rs                    |  19 +-
 crates/core/src/ecc/types.rs                  |  12 +-
 crates/core/src/error.rs                      |  15 +
 crates/core/src/inspect.rs                    |   4 +-
 crates/core/src/lib.rs                        |   1 +
 crates/core/src/lifecycle.rs                  | 104 ++++++
 crates/core/src/measure.rs                    |   8 +-
 crates/core/src/message/effects.rs            |  18 +-
 crates/core/src/message/encoder.rs            |   4 +-
 .../core/src/message/handlers/connection.rs   | 334 +++++++++++------
 .../src/message/handlers/stabilization.rs     | 122 +++----
 crates/core/src/message/handlers/storage.rs   |   4 +-
 .../handlers/storage/tests/test_repair.rs     | 136 ++++---
 .../storage/tests/test_storage_sync_report.rs |  16 +-
 .../handlers/storage/tests/test_sync_ack.rs   |  22 ++
 .../storage/tests/test_sync_receive.rs        |  45 ++-
 crates/core/src/message/payload.rs            |  28 +-
 crates/core/src/message/protocols/relay.rs    |   4 +-
 crates/core/src/message/types.rs              |  27 ++
 crates/core/src/prelude.rs                    |   2 +
 crates/core/src/storage/idb.rs                |   3 +-
 crates/core/src/storage/memory.rs             |   9 +-
 crates/core/src/storage/sled.rs               |   7 +-
 crates/core/src/swarm/callback.rs             |   2 +
 crates/core/src/swarm/transport.rs            | 226 ++++++++++--
 crates/core/src/swarm/transport/delivery.rs   | 282 ++++++++++++++-
 crates/core/src/swarm/transport/liveness.rs   | 272 ++++++++++++++
 crates/core/src/swarm/transport/pending.rs    |  83 ++++-
 .../src/swarm/transport/storage_lookup.rs     |  11 +-
 .../core/src/swarm/transport/storage_sync.rs  |  49 ++-
 crates/core/src/swarm/transport/tests.rs      |   4 +-
 .../core/src/tests/default/test_chunk_e2e.rs  | 215 +++++++++++
 .../src/tests/default/test_stabilization.rs   | 144 +++++++-
 .../core/src/tests/wasm/test_idb_storage.rs   |  49 ++-
 crates/core/src/utils.rs                      |  19 +-
 crates/node/src/extension/protocols/echo.rs   |  11 +-
 crates/node/src/extension/protocols/relay.rs  | 103 ++++--
 crates/node/src/extension/snark/builder.rs    |  27 +-
 crates/node/src/extension/snark/protocol.rs   |  39 +-
 .../src/extension/transport/engine/mod.rs     |  53 ++-
 .../src/extension/transport/engine/tcp.rs     |  38 +-
 .../src/extension/transport/engine/udp.rs     |  26 +-
 crates/node/src/extension/transport/wt.rs     |  62 ++--
 crates/node/src/logging.rs                    |   6 +-
 crates/node/src/native/cli.rs                 |   5 +-
 crates/node/src/native/config.rs              |  16 +-
 crates/node/src/native/endpoint/mod.rs        |   3 +-
 crates/node/src/onion/circuit/shell.rs        |  22 +-
 .../circuit/tests/test_circuit_protocol.rs    |  23 +-
 crates/node/src/onion/https/mod.rs            |  15 +-
 .../src/onion/https/tests/test_https_proxy.rs |  17 +-
 crates/node/src/onion/replay.rs               |   3 +-
 .../onion/route/tests/test_route_selection.rs |  23 +-
 crates/node/src/onion/tcp/mod.rs              |  22 +-
 .../src/onion/tests/test_exit_registry.rs     |  15 +-
 crates/node/src/prelude.rs                    |   2 +
 crates/node/src/processor/builder.rs          |   4 +-
 crates/node/src/processor/config.rs           |   4 +-
 crates/node/src/processor/mod.rs              |  29 +-
 .../node/src/processor/tests/test_config.rs   |   8 +-
 .../node/src/processor/tests/test_network.rs  |  23 +-
 crates/node/src/provider/mod.rs               |   9 +
 crates/node/src/registration.rs               | 116 +++++-
 crates/node/src/tests/native/test_snark.rs    |  11 +-
 crates/node/src/tests/wasm/test_snark.rs      |  11 +-
 crates/node/src/util.rs                       |  12 +-
 crates/rpc/src/jsonrpc.rs                     |   4 +-
 crates/snark/src/circuit/bellman.rs           |   3 +-
 crates/snark/src/circuit/mod.rs               |  11 +-
 crates/snark/src/tests/native/test_snark.rs   |  48 ++-
 crates/snark/src/tests/native/test_wat.rs     |  11 +-
 crates/snark/src/witness/circom.rs            |  25 +-
 crates/transport/src/connections/dummy/mod.rs |  46 +++
 .../src/connections/native_webrtc/mod.rs      | 223 +++++++++++-
 .../src/connections/web_sys_webrtc/mod.rs     |  25 +-
 crates/transport/src/core/sdp.rs              |  45 ++-
 crates/transport/src/ice_server.rs            |  18 +-
 crates/webview/src/render.rs                  |   3 +-
 crates/webview/src/transport.rs               |   6 +-
 docker/cluster/Dockerfile                     |   2 +-
 docker/cluster/README.md                      |  18 +
 docker/cluster/rings-cluster-entrypoint.sh    |  68 +++-
 examples/native/src/main.rs                   |   7 +-
 examples/snark/bn256.rs                       |  19 +-
 examples/snark/src/lib.rs                     |  34 +-
 frontend/src/node.rs                          |  14 +-
 98 files changed, 3586 insertions(+), 889 deletions(-)
 create mode 100644 crates/core/src/lifecycle.rs
 create mode 100644 crates/core/src/swarm/transport/liveness.rs

diff --git a/.gitignore b/.gitignore
index 01297626c..321778b3d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,6 +23,10 @@ docs
 # Tests
 *.log
 
+# Local scripts are allowed in the worktree but should not be added accidentally.
+scripts/*
+!scripts/cargo-publish-crates.sh
+
 # OS related
 ### MacOS ###
 .DS_Store
diff --git a/crates/core/src/algebra.rs b/crates/core/src/algebra.rs
index 764ac2cdd..437e5f148 100644
--- a/crates/core/src/algebra.rs
+++ b/crates/core/src/algebra.rs
@@ -187,7 +187,8 @@ pub trait Field: CommutativeRing {
 ///
 /// Law: `a * Scalar::one() == a`.
 pub trait Module: AbelianGroup + Mul
-where Scalar: CommutativeRing
+where
+    Scalar: CommutativeRing,
 {
 }
 
@@ -199,7 +200,9 @@ where Scalar: CommutativeRing
 /// explain why the laws hold for the whole carrier.
 #[cfg(test)]
 pub fn assert_abelian_group_laws(values: &[T])
-where T: AbelianGroup + Clone + Eq + Debug {
+where
+    T: AbelianGroup + Clone + Eq + Debug,
+{
     for a in values {
         assert_eq!(a.clone() + T::zero(), *a);
         assert_eq!(T::zero() + a.clone(), *a);
@@ -228,7 +231,9 @@ where T: AbelianGroup + Clone + Eq + Debug {
 /// order, with any duplication.
 #[cfg(test)]
 pub fn assert_join_semilattice_laws(values: &[T])
-where T: JoinSemilattice + Clone + Eq + Debug {
+where
+    T: JoinSemilattice + Clone + Eq + Debug,
+{
     for a in values {
         assert_eq!(a.clone().join(a.clone()), *a);
 
@@ -251,7 +256,9 @@ where T: JoinSemilattice + Clone + Eq + Debug {
 /// bound for each schedule.
 #[cfg(test)]
 pub fn assert_strong_eventual_consistency(base: T, deltas: &[T])
-where T: JoinSemilattice + Clone + Eq + Debug {
+where
+    T: JoinSemilattice + Clone + Eq + Debug,
+{
     let forward = deltas
         .iter()
         .cloned()
@@ -280,7 +287,9 @@ where T: JoinSemilattice + Clone + Eq + Debug {
 /// distributivity on the same sample.
 #[cfg(test)]
 pub fn assert_commutative_ring_laws(values: &[T])
-where T: CommutativeRing + Clone + Eq + Debug {
+where
+    T: CommutativeRing + Clone + Eq + Debug,
+{
     assert_abelian_group_laws(values);
 
     for a in values {
@@ -312,7 +321,9 @@ where T: CommutativeRing + Clone + Eq + Debug {
 /// and every sampled non-zero value has a two-sided inverse.
 #[cfg(test)]
 pub fn assert_field_laws(values: &[T])
-where T: Field + Clone + Eq + Debug {
+where
+    T: Field + Clone + Eq + Debug,
+{
     assert_commutative_ring_laws(values);
     assert_ne!(T::zero(), T::one());
 
diff --git a/crates/core/src/dht/did.rs b/crates/core/src/dht/did.rs
index 369382d59..db4aaff01 100644
--- a/crates/core/src/dht/did.rs
+++ b/crates/core/src/dht/did.rs
@@ -604,12 +604,15 @@ mod tests {
         let did = Did::from(10u32);
         let affine_dids = did.rotate_affine(4)?;
         assert_eq!(affine_dids.len(), 4);
-        assert_eq!(affine_dids, vec![
-            did.rotate(0),
-            did.rotate(90),
-            did.rotate(180),
-            did.rotate(270)
-        ]);
+        assert_eq!(
+            affine_dids,
+            vec![
+                did.rotate(0),
+                did.rotate(90),
+                did.rotate(180),
+                did.rotate(270)
+            ]
+        );
         Ok(())
     }
 
diff --git a/crates/core/src/dht/entry/tests.rs b/crates/core/src/dht/entry/tests.rs
index 22b318264..9c9c51575 100644
--- a/crates/core/src/dht/entry/tests.rs
+++ b/crates/core/src/dht/entry/tests.rs
@@ -163,10 +163,10 @@ fn entry_join_is_strongly_eventually_consistent_for_data_deltas() -> Result<()>
 
     assert_eq!(forward, reverse);
     assert_eq!(forward, duplicated);
-    assert_eq!(decode_entry_data(&forward)?, vec![
-        String::from("b"),
-        String::from("a")
-    ]);
+    assert_eq!(
+        decode_entry_data(&forward)?,
+        vec![String::from("b"), String::from("a")]
+    );
     Ok(())
 }
 
@@ -362,10 +362,10 @@ fn extend_appends_data_for_same_entry() -> Result<()> {
     let entry = data_entry("topic", "first")?;
     let other = data_entry("topic", "second")?;
     let updated = entry.extend(other, actor())?;
-    assert_eq!(decode_entry_data(&updated)?, vec![
-        String::from("first"),
-        String::from("second")
-    ]);
+    assert_eq!(
+        decode_entry_data(&updated)?,
+        vec![String::from("first"), String::from("second")]
+    );
     Ok(())
 }
 
@@ -422,11 +422,10 @@ fn touch_moves_existing_items_to_end_once() -> Result<()> {
         .extend(data_entry("topic", "c")?, actor())?;
     let touched = data_entry("topic", "b")?;
     let updated = entry.touch(touched, actor())?;
-    assert_eq!(decode_entry_data(&updated)?, vec![
-        String::from("a"),
-        String::from("c"),
-        String::from("b")
-    ]);
+    assert_eq!(
+        decode_entry_data(&updated)?,
+        vec![String::from("a"), String::from("c"), String::from("b")]
+    );
     Ok(())
 }
 
@@ -457,9 +456,10 @@ fn relay_tombstone_removes_observed_message_by_join() -> Result<()> {
 
     assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
     let joined_with_stale_add = removed.join(first)?;
-    assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
-        String::from("second")
-    ]);
+    assert_eq!(
+        decode_entry_data(&joined_with_stale_add)?,
+        vec![String::from("second")]
+    );
     Ok(())
 }
 
@@ -475,9 +475,10 @@ fn data_tombstone_removes_observed_payload_by_join() -> Result<()> {
 
     assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
     let joined_with_stale_add = removed.join(first)?;
-    assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
-        String::from("second")
-    ]);
+    assert_eq!(
+        decode_entry_data(&joined_with_stale_add)?,
+        vec![String::from("second")]
+    );
     Ok(())
 }
 
diff --git a/crates/core/src/dht/finger.rs b/crates/core/src/dht/finger.rs
index 8ede88b56..4bde3cf5c 100644
--- a/crates/core/src/dht/finger.rs
+++ b/crates/core/src/dht/finger.rs
@@ -345,13 +345,10 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did1);
-        assert_eq!(table.finger, [
-            Some(did2),
-            Some(did2),
-            Some(did3),
-            Some(did4),
-            Some(did5),
-        ]);
+        assert_eq!(
+            table.finger,
+            [Some(did2), Some(did2), Some(did3), Some(did4), Some(did5),]
+        );
 
         // [did1, did2, did3, did4, did5] - did2 = [did1, did3, did3, did4, did5]
         table.reset_finger();
@@ -361,13 +358,10 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did2);
-        assert_eq!(table.finger, [
-            Some(did1),
-            Some(did3),
-            Some(did3),
-            Some(did4),
-            Some(did5),
-        ]);
+        assert_eq!(
+            table.finger,
+            [Some(did1), Some(did3), Some(did3), Some(did4), Some(did5),]
+        );
 
         // [did1, None, did3, did4, did5] - did1 = [None, None, did3, did4, did5]
         table.reset_finger();
@@ -376,13 +370,10 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did1);
-        assert_eq!(table.finger, [
-            None,
-            None,
-            Some(did3),
-            Some(did4),
-            Some(did5),
-        ]);
+        assert_eq!(
+            table.finger,
+            [None, None, Some(did3), Some(did4), Some(did5),]
+        );
 
         // [did1, None, did3, did4, did5] - did3 = [did1, None, did4, did4, did5]
         table.reset_finger();
@@ -391,13 +382,10 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did3);
-        assert_eq!(table.finger, [
-            Some(did1),
-            None,
-            Some(did4),
-            Some(did4),
-            Some(did5),
-        ]);
+        assert_eq!(
+            table.finger,
+            [Some(did1), None, Some(did4), Some(did4), Some(did5),]
+        );
 
         // [did1, did2, did3, did4, did5] - did5 = [did1, did2, did4, did4, None]
         table.reset_finger();
@@ -407,12 +395,9 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did5);
-        assert_eq!(table.finger, [
-            Some(did1),
-            Some(did2),
-            Some(did3),
-            Some(did4),
-            None
-        ]);
+        assert_eq!(
+            table.finger,
+            [Some(did1), Some(did2), Some(did3), Some(did4), None]
+        );
     }
 }
diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index c82773822..6c842f7b7 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -4,12 +4,12 @@ use std::collections::BTreeMap;
 use std::collections::BTreeSet;
 use std::future::Future;
 use std::sync::Arc;
+use std::sync::Mutex;
 use std::time::Duration;
 
 use futures::future::FutureExt;
 use futures::pin_mut;
 use futures::select;
-use futures_timer::Delay;
 use rings_transport::core::transport::WebrtcConnectionState;
 
 use crate::dht::successor::SuccessorReader;
@@ -20,9 +20,12 @@ use crate::dht::Did;
 use crate::dht::PeerRing;
 use crate::dht::PeerRingAction;
 use crate::dht::PeerRingRemoteAction;
+use crate::dht::StorageSyncDelivery;
+use crate::dht::StorageSyncDestination;
 use crate::dht::TopoInfo;
 use crate::error::Error;
 use crate::error::Result;
+use crate::lifecycle::StopToken;
 use crate::measure::PeerMeasurement;
 use crate::measure::PeerQualityThresholds;
 use crate::message::FindSuccessorReportHandler;
@@ -32,13 +35,18 @@ use crate::message::Message;
 use crate::message::MessagePayload;
 use crate::message::NotifyPredecessorSend;
 use crate::message::PayloadSender;
+use crate::message::PeerLivenessProbe;
 use crate::message::QueryForTopoInfoSend;
 use crate::message::SyncEntriesWithSuccessor;
 use crate::swarm::transport::SwarmTransport;
+use crate::swarm::transport::PEER_LIVENESS_IDLE_MS;
 use crate::utils::get_epoch_ms_i64;
+use crate::utils::sleep;
 
 const STABILIZATION_STEP_TIMEOUT: Duration = Duration::from_secs(30);
 const DISCONNECTED_CONNECTION_GRACE_MS: i64 = 30_000;
+pub(crate) const STORAGE_REPAIR_MAX_DELIVERIES_PER_STEP: usize = 64;
+pub(crate) const STORAGE_REPAIR_FRESH_CONNECTION_GRACE_MS: i64 = 30_000;
 const DHT_TOPOLOGY_EVICTION_THRESHOLDS: PeerQualityThresholds =
     PeerQualityThresholds::new(3, 10, 10);
 
@@ -51,9 +59,42 @@ enum TopologyPeerRemovalReason {
         disconnected_for_ms: i64,
         grace_ms: i64,
     },
+    UnansweredLivenessProbe {
+        unanswered_for_ms: i64,
+        timeout_ms: i64,
+    },
     LocalFailureLimit(PeerMeasurement),
 }
 
+#[derive(Clone, Copy, Debug)]
+enum StorageRepairDeferReason {
+    MissingNextHop,
+    NextHopNotAdmitted,
+    PhysicalOwnerNotAdmitted,
+    NextHopFresh { connected_for_ms: i64 },
+    PhysicalOwnerFresh { connected_for_ms: i64 },
+}
+
+impl StorageRepairDeferReason {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Self::MissingNextHop => "missing_next_hop",
+            Self::NextHopNotAdmitted => "next_hop_not_admitted",
+            Self::PhysicalOwnerNotAdmitted => "physical_owner_not_admitted",
+            Self::NextHopFresh { .. } => "next_hop_fresh",
+            Self::PhysicalOwnerFresh { .. } => "physical_owner_fresh",
+        }
+    }
+
+    const fn connected_for_ms(self) -> Option {
+        match self {
+            Self::NextHopFresh { connected_for_ms }
+            | Self::PhysicalOwnerFresh { connected_for_ms } => Some(connected_for_ms),
+            _ => None,
+        }
+    }
+}
+
 impl TopologyPeerRemovalReason {
     const fn as_str(self) -> &'static str {
         match self {
@@ -61,6 +102,7 @@ impl TopologyPeerRemovalReason {
             Self::MissingTransportObject => "missing_transport_object",
             Self::TerminalTransport(_) => "terminal_transport",
             Self::DisconnectedGraceElapsed { .. } => "disconnected_grace_elapsed",
+            Self::UnansweredLivenessProbe { .. } => "unanswered_liveness_probe",
             Self::LocalFailureLimit(_) => "local_failure_limit",
         }
     }
@@ -89,6 +131,22 @@ impl TopologyPeerRemovalReason {
         }
     }
 
+    const fn liveness_unanswered_for_ms(self) -> Option {
+        match self {
+            Self::UnansweredLivenessProbe {
+                unanswered_for_ms, ..
+            } => Some(unanswered_for_ms),
+            _ => None,
+        }
+    }
+
+    const fn liveness_timeout_ms(self) -> Option {
+        match self {
+            Self::UnansweredLivenessProbe { timeout_ms, .. } => Some(timeout_ms),
+            _ => None,
+        }
+    }
+
     const fn measurement(self) -> Option {
         match self {
             Self::LocalFailureLimit(measurement) => Some(measurement),
@@ -113,13 +171,18 @@ const fn is_terminal_transport_state(state: WebrtcConnectionState) -> bool {
 pub struct Stabilizer {
     transport: Arc,
     dht: Arc,
+    storage_repair_cursor: Arc>,
 }
 
 impl Stabilizer {
     /// Create a new stabilization runner.
     pub fn new(transport: Arc) -> Self {
         let dht = transport.dht.clone();
-        Self { transport, dht }
+        Self {
+            transport,
+            dht,
+            storage_repair_cursor: Arc::new(Mutex::new(0)),
+        }
     }
 
     /// Run stabilization once.
@@ -133,6 +196,8 @@ impl Stabilizer {
             .await;
         self.run_step("fix_fingers", timeout, self.fix_fingers())
             .await;
+        self.run_step("probe_peer_liveness", timeout, self.probe_peer_liveness())
+            .await;
         self.run_step(
             "clean_unavailable_connections",
             timeout,
@@ -149,7 +214,9 @@ impl Stabilizer {
     }
 
     async fn run_step(&self, step: &'static str, timeout: Duration, future: F)
-    where F: Future> {
+    where
+        F: Future>,
+    {
         tracing::debug!(
             target: "rings_core::dht::stabilization",
             local = %self.dht.did,
@@ -160,7 +227,7 @@ impl Stabilizer {
 
         let result = {
             let future = future.fuse();
-            let timer = Delay::new(timeout).fuse();
+            let timer = sleep(timeout).fuse();
             pin_mut!(future, timer);
 
             select! {
@@ -214,7 +281,7 @@ impl Stabilizer {
     }
 
     async fn handle_storage_repair_action(&self, act: PeerRingAction) -> Result<()> {
-        let deliveries = act.storage_sync_deliveries()?;
+        let deliveries = self.storage_repair_window(act.coalesced_storage_sync_deliveries()?);
         if deliveries.is_empty() {
             tracing::debug!(
                 target: "rings_core::dht::stabilization",
@@ -231,6 +298,9 @@ impl Stabilizer {
             "STABILIZATION storage repair deliveries prepared"
         );
 
+        let now_ms = get_epoch_ms_i64();
+        let mut sent = 0usize;
+        let mut deferred = 0usize;
         for delivery in deliveries {
             let msg = SyncEntriesWithSuccessor::from_delivery(delivery);
             let purpose = msg.purpose;
@@ -246,6 +316,25 @@ impl Stabilizer {
                 .and_then(|did| self.transport.get_connection(did))
                 .map(|conn| conn.webrtc_connection_state());
 
+            if let Some(reason) = self.storage_repair_defer_reason(destination, next_hop, now_ms)? {
+                deferred = deferred.saturating_add(1);
+                tracing::debug!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    purpose = ?purpose,
+                    destination = ?destination,
+                    destination_did = %destination_did,
+                    next_hop = ?next_hop,
+                    next_hop_state = ?next_hop_state,
+                    entries,
+                    reason = reason.as_str(),
+                    connected_for_ms = ?reason.connected_for_ms(),
+                    grace_ms = STORAGE_REPAIR_FRESH_CONNECTION_GRACE_MS,
+                    "STABILIZATION storage repair deferred"
+                );
+                continue;
+            }
+
             tracing::debug!(
                 target: "rings_core::dht::stabilization",
                 local = %self.dht.did,
@@ -268,7 +357,7 @@ impl Stabilizer {
                     destination_did = %destination_did,
                     next_hop = ?next_hop,
                     entries,
-                    "STABILIZATION storage repair send complete"
+                        "STABILIZATION storage repair send complete"
                 ),
                 Err(e) => {
                     tracing::error!(
@@ -286,10 +375,110 @@ impl Stabilizer {
                     return Err(e);
                 }
             }
+            sent = sent.saturating_add(1);
+        }
+
+        if deferred > 0 {
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                sent,
+                deferred,
+                "STABILIZATION storage repair deliveries finished with deferrals"
+            );
         }
         Ok(())
     }
 
+    fn storage_repair_window(
+        &self,
+        mut deliveries: Vec,
+    ) -> Vec {
+        let total = deliveries.len();
+        if total <= STORAGE_REPAIR_MAX_DELIVERIES_PER_STEP {
+            return deliveries;
+        }
+
+        let start = match self.storage_repair_cursor.lock() {
+            Ok(mut cursor) => {
+                let start = *cursor % total;
+                *cursor = (start + STORAGE_REPAIR_MAX_DELIVERIES_PER_STEP) % total;
+                start
+            }
+            Err(_) => {
+                tracing::warn!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    "STABILIZATION storage repair cursor lock failed"
+                );
+                0
+            }
+        };
+        deliveries.rotate_left(start);
+        deliveries.truncate(STORAGE_REPAIR_MAX_DELIVERIES_PER_STEP);
+        tracing::debug!(
+            target: "rings_core::dht::stabilization",
+            local = %self.dht.did,
+            total_deliveries = total,
+            selected_deliveries = deliveries.len(),
+            start,
+            "STABILIZATION storage repair delivery window selected"
+        );
+        deliveries
+    }
+
+    fn storage_repair_defer_reason(
+        &self,
+        destination: StorageSyncDestination,
+        next_hop: Option,
+        now_ms: i64,
+    ) -> Result> {
+        let Some(next_hop) = next_hop else {
+            return Ok(Some(StorageRepairDeferReason::MissingNextHop));
+        };
+        if !self.transport.is_admitted_connection(next_hop) {
+            return Ok(Some(StorageRepairDeferReason::NextHopNotAdmitted));
+        }
+        if let Some(connected_for_ms) = self.peer_connected_for_ms(next_hop, now_ms) {
+            if connected_for_ms < STORAGE_REPAIR_FRESH_CONNECTION_GRACE_MS {
+                return Ok(Some(StorageRepairDeferReason::NextHopFresh {
+                    connected_for_ms,
+                }));
+            }
+        }
+
+        if let Some(owner) = self.dht.observed_storage_sync_physical_owner(destination)? {
+            if !self.transport.is_admitted_connection(owner) {
+                return Ok(Some(StorageRepairDeferReason::PhysicalOwnerNotAdmitted));
+            }
+            if let Some(connected_for_ms) = self.peer_connected_for_ms(owner, now_ms) {
+                if connected_for_ms < STORAGE_REPAIR_FRESH_CONNECTION_GRACE_MS {
+                    return Ok(Some(StorageRepairDeferReason::PhysicalOwnerFresh {
+                        connected_for_ms,
+                    }));
+                }
+            }
+        }
+
+        Ok(None)
+    }
+
+    fn peer_connected_for_ms(&self, peer: Did, now_ms: i64) -> Option {
+        match self.transport.peer_connected_for_ms(peer, now_ms) {
+            Ok(age) => age,
+            Err(error) => {
+                tracing::warn!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    peer = %peer,
+                    error = %error,
+                    "STABILIZATION storage repair connection age check failed"
+                );
+                None
+            }
+        }
+    }
+
     /// Republish locally-held entries to their current affine owners.
     pub async fn repair_storage(&self) -> Result<()> {
         tracing::debug!(
@@ -302,10 +491,19 @@ impl Stabilizer {
             .dht
             .republish_local_entries(self.transport.storage_redundancy())
             .await?;
+        let (action_kind, action_count) = match &action {
+            PeerRingAction::None => ("None", 0),
+            PeerRingAction::Some(_) => ("Some", 1),
+            PeerRingAction::SomeEntry(_) => ("SomeEntry", 1),
+            PeerRingAction::EntryMisses(misses) => ("EntryMisses", misses.len()),
+            PeerRingAction::RemoteAction(_, _) => ("RemoteAction", 1),
+            PeerRingAction::MultiActions(actions) => ("MultiActions", actions.len()),
+        };
         tracing::debug!(
             target: "rings_core::dht::stabilization",
             local = %self.dht.did,
-            action = ?action,
+            action_kind,
+            action_count,
             "STABILIZATION repair_storage republish action prepared"
         );
         self.handle_storage_repair_action(action).await?;
@@ -417,6 +615,25 @@ impl Stabilizer {
             }
         }
 
+        match self.transport.peer_liveness_expiry(did, now_ms) {
+            Ok(Some(expiry)) => {
+                return Some(TopologyPeerRemovalReason::UnansweredLivenessProbe {
+                    unanswered_for_ms: expiry.unanswered_for_ms,
+                    timeout_ms: expiry.timeout_ms,
+                });
+            }
+            Ok(None) => {}
+            Err(error) => {
+                tracing::warn!(
+                    target: "rings_core::dht::stabilization",
+                    local = %self.dht.did,
+                    peer = %did,
+                    error = %error,
+                    "STABILIZATION clean_unavailable liveness state check failed"
+                );
+            }
+        }
+
         if matches!(state, WebrtcConnectionState::Disconnected) {
             if let Some(disconnected_since_ms) = self.transport.peer_disconnected_since_ms(did) {
                 let disconnected_for_ms = now_ms.saturating_sub(disconnected_since_ms);
@@ -449,6 +666,8 @@ impl Stabilizer {
             state = ?reason.transport_state(),
             disconnected_for_ms = ?reason.disconnected_for_ms(),
             disconnected_grace_ms = ?reason.disconnected_grace_ms(),
+            liveness_unanswered_for_ms = ?reason.liveness_unanswered_for_ms(),
+            liveness_timeout_ms = ?reason.liveness_timeout_ms(),
             measurement = ?reason.measurement(),
             should_repair,
             "STABILIZATION clean_unavailable selected peer"
@@ -509,6 +728,51 @@ impl Stabilizer {
         Ok(())
     }
 
+    async fn probe_peer_liveness(&self) -> Result<()> {
+        let now_ms = get_epoch_ms_i64();
+        let candidates = self.transport.liveness_probe_candidates(now_ms)?;
+        for peer in candidates {
+            let state = self
+                .transport
+                .get_connection(peer)
+                .map(|conn| conn.webrtc_connection_state());
+            let msg = Message::PeerLivenessProbe(PeerLivenessProbe { sent_at_ms: now_ms });
+            tracing::debug!(
+                target: "rings_core::dht::stabilization",
+                local = %self.dht.did,
+                peer = %peer,
+                state = ?state,
+                idle_ms = PEER_LIVENESS_IDLE_MS,
+                "STABILIZATION peer liveness probe send start"
+            );
+            match self.transport.send_direct_message(msg, peer).await {
+                Ok(tx_id) => {
+                    self.transport
+                        .record_peer_liveness_probe_sent(peer, now_ms)?;
+                    tracing::debug!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        peer = %peer,
+                        tx_id = %tx_id,
+                        "STABILIZATION peer liveness probe send complete"
+                    );
+                }
+                Err(error) => {
+                    self.transport.record_peer_message_send_failed(peer).await;
+                    tracing::warn!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        peer = %peer,
+                        state = ?state,
+                        error = ?error,
+                        "STABILIZATION peer liveness probe send failed"
+                    );
+                }
+            }
+        }
+        Ok(())
+    }
+
     /// Notify predecessor, this is a DHT operation.
     pub async fn notify_predecessor(&self) -> Result<()> {
         let (successor_min, successor_list) = {
@@ -709,60 +973,36 @@ impl Stabilizer {
     }
 }
 
-#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
 mod stabilizer {
     use std::sync::Arc;
     use std::time::Duration;
 
-    use futures::future::FutureExt;
-    use futures::pin_mut;
-    use futures::select;
-    use futures_timer::Delay;
-
     use super::*;
 
     impl Stabilizer {
         /// Run stabilization in a loop.
         pub async fn wait(self: Arc, interval: Duration) {
+            self.wait_with(interval, StopToken::never()).await;
+        }
+
+        /// Run stabilization until `stop` asks this loop to exit.
+        ///
+        /// The token is checked between ticks and before each stabilization run.
+        /// It intentionally does not cancel an in-flight stabilization future;
+        /// browser IndexedDB requests are not cancellation-safe.
+        pub async fn wait_with(self: Arc, interval: Duration, stop: StopToken) {
             loop {
-                let timeout = Delay::new(interval).fuse();
-                pin_mut!(timeout);
-                select! {
-                    _ = timeout => self
-                        .stabilize()
-                        .await
-                        .unwrap_or_else(|e| tracing::error!("failed to stabilize {:?}", e)),
+                if stop.should_stop() {
+                    return;
                 }
+                sleep(interval).await;
+                if stop.should_stop() {
+                    return;
+                }
+                self.stabilize()
+                    .await
+                    .unwrap_or_else(|e| tracing::error!("failed to stabilize {:?}", e));
             }
         }
     }
 }
-
-#[cfg(all(feature = "wasm", target_family = "wasm"))]
-mod stabilizer {
-    use std::sync::Arc;
-    use std::time::Duration;
-
-    use super::*;
-    use crate::poll;
-
-    impl Stabilizer {
-        /// Run stabilization in a loop.
-        pub async fn wait(self: Arc, interval: Duration) {
-            let millis = i32::try_from(interval.as_millis()).unwrap_or(i32::MAX);
-            let stabilizer = self;
-            poll!(
-                {
-                    let stabilizer = Arc::clone(&stabilizer);
-                    async move {
-                        stabilizer
-                            .stabilize()
-                            .await
-                            .unwrap_or_else(|e| tracing::error!("failed to stabilize {:?}", e));
-                    }
-                },
-                millis
-            );
-        }
-    }
-}
diff --git a/crates/core/src/dht/storage/mod.rs b/crates/core/src/dht/storage/mod.rs
index 1e0a86dd0..1435cd1b1 100644
--- a/crates/core/src/dht/storage/mod.rs
+++ b/crates/core/src/dht/storage/mod.rs
@@ -4,6 +4,7 @@
 //! storage-specific ownership on top of that topology: affine replica
 //! placement, storage virtual-node ownership, read repair, and sync hand-off.
 
+use std::collections::BTreeMap;
 use std::collections::BTreeSet;
 
 use serde::Deserialize;
@@ -120,6 +121,18 @@ pub(crate) struct StorageSyncDelivery {
 }
 
 impl StorageSyncDelivery {
+    fn from_parts(
+        purpose: StorageSyncPurpose,
+        destination: StorageSyncDestination,
+        data: Vec,
+    ) -> Self {
+        Self {
+            purpose,
+            destination,
+            data,
+        }
+    }
+
     fn from_route(
         purpose: StorageSyncPurpose,
         target: Did,
@@ -170,11 +183,14 @@ impl PeerRingAction {
         destination: StorageSyncDestination,
         data: Vec,
     ) -> Self {
-        Self::RemoteAction(destination.did(), RemoteAction::SyncEntriesWithSuccessor {
-            purpose,
-            route: destination.route(),
-            data,
-        })
+        Self::RemoteAction(
+            destination.did(),
+            RemoteAction::SyncEntriesWithSuccessor {
+                purpose,
+                route: destination.route(),
+                data,
+            },
+        )
     }
 
     /// Lower this action tree into storage-sync deliveries.
@@ -184,6 +200,33 @@ impl PeerRingAction {
         Ok(deliveries)
     }
 
+    /// Lower this action tree into storage-sync deliveries, merging delivery
+    /// leaves that share the same wire purpose and destination.
+    ///
+    /// Safety law: coalescing is restricted to identical `(purpose,
+    /// destination)` pairs. `PlacementKey` destinations therefore keep their
+    /// placement identity, and physical-owner batches still let the receiver
+    /// validate each placement independently before acking.
+    pub(crate) fn coalesced_storage_sync_deliveries(self) -> Result> {
+        let mut by_route =
+            BTreeMap::<(StorageSyncPurpose, StorageSyncDestination), Vec>::new();
+        for delivery in self.storage_sync_deliveries()? {
+            let (purpose, destination, data) = delivery.into_message_parts();
+            by_route
+                .entry((purpose, destination))
+                .or_default()
+                .extend(data);
+        }
+
+        let mut deliveries = Vec::new();
+        for ((purpose, destination), data) in by_route {
+            for batch in sync::sync_entries_batches(data, sync::SYNC_BATCH_MAX_BYTES)? {
+                deliveries.push(StorageSyncDelivery::from_parts(purpose, destination, batch));
+            }
+        }
+        Ok(deliveries)
+    }
+
     fn collect_storage_sync_deliveries(
         self,
         deliveries: &mut Vec,
@@ -302,6 +345,43 @@ impl PeerRing {
         }
     }
 
+    pub(crate) fn observed_storage_sync_physical_owner(
+        &self,
+        destination: StorageSyncDestination,
+    ) -> Result> {
+        // Pre: `destination` is the wire-level storage sync destination.
+        // Post: `Some(owner)` names the physical receiver currently observed by
+        // the local storage-routing model. Placement-key routes without a
+        // virtual owner do not expose a final physical owner locally, so only
+        // the next hop can be guarded at this boundary.
+        match destination {
+            StorageSyncDestination::PhysicalOwner(owner) => Ok(Some(owner)),
+            StorageSyncDestination::PlacementKey(key) => self.observed_storage_virtual_owner(key),
+        }
+    }
+
+    fn observed_physical_peer_registered(&self, peer: Did) -> Result {
+        let state = self.topology_state()?;
+        Ok(peer == state.local
+            || state.successors.contains(&peer)
+            || state.predecessor == Some(peer)
+            || state.fingers.into_iter().flatten().any(|did| did == peer))
+    }
+
+    pub(crate) fn storage_sync_route_still_permits(
+        &self,
+        destination: StorageSyncDestination,
+        next_hop: Did,
+    ) -> Result {
+        if let StorageSyncDestination::PhysicalOwner(owner) = destination {
+            if !self.observed_physical_peer_registered(owner)? {
+                return Ok(false);
+            }
+        }
+
+        Ok(self.next_hop_for_storage_sync(destination)? == Some(next_hop))
+    }
+
     fn next_hop_to_physical_owner(&self, owner: Did) -> Result> {
         if owner == self.did {
             return Ok(None);
diff --git a/crates/core/src/dht/storage/repair.rs b/crates/core/src/dht/storage/repair.rs
index 0dca04b39..44d6fae5d 100644
--- a/crates/core/src/dht/storage/repair.rs
+++ b/crates/core/src/dht/storage/repair.rs
@@ -169,11 +169,10 @@ impl PeerRing {
                     .await?;
                 Ok(PeerRingAction::None)
             }
-            StorageSyncTarget::Remote(destination) => {
-                Ok(PeerRingAction::sync_entries_for_repair(destination, vec![
-                    placed,
-                ]))
-            }
+            StorageSyncTarget::Remote(destination) => Ok(PeerRingAction::sync_entries_for_repair(
+                destination,
+                vec![placed],
+            )),
         }
     }
 
diff --git a/crates/core/src/dht/storage/tests.rs b/crates/core/src/dht/storage/tests.rs
index 24531bb69..f56e3fe63 100644
--- a/crates/core/src/dht/storage/tests.rs
+++ b/crates/core/src/dht/storage/tests.rs
@@ -158,6 +158,70 @@ fn placed_entries_by_key(entries: impl IntoIterator) -> BTre
         .collect()
 }
 
+#[test]
+fn coalesced_storage_sync_deliveries_merge_identical_physical_destinations() -> Result<()> {
+    let owner = Did::from(50u32);
+    let first = PlacedEntry::new(Did::from(100u32), data_entry(Did::from(10u32)));
+    let second = PlacedEntry::new(Did::from(120u32), data_entry(Did::from(20u32)));
+    let action = PeerRingAction::MultiActions(vec![
+        PeerRingAction::sync_entries_for_repair(
+            StorageSyncDestination::PhysicalOwner(owner),
+            vec![first.clone()],
+        ),
+        PeerRingAction::sync_entries_for_repair(
+            StorageSyncDestination::PhysicalOwner(owner),
+            vec![second.clone()],
+        ),
+    ]);
+
+    let deliveries = action.coalesced_storage_sync_deliveries()?;
+
+    assert_eq!(deliveries.len(), 1);
+    let (purpose, destination, data) = deliveries
+        .into_iter()
+        .next()
+        .expect("coalesced delivery")
+        .into_message_parts();
+    assert_eq!(purpose, StorageSyncPurpose::AdditiveRepair);
+    assert_eq!(destination, StorageSyncDestination::PhysicalOwner(owner));
+    assert_eq!(data, vec![first, second]);
+    Ok(())
+}
+
+#[test]
+fn coalesced_storage_sync_deliveries_keep_placement_destinations_separate() -> Result<()> {
+    let first_key = Did::from(100u32);
+    let second_key = Did::from(120u32);
+    let first = PlacedEntry::new(first_key, data_entry(Did::from(10u32)));
+    let second = PlacedEntry::new(second_key, data_entry(Did::from(20u32)));
+    let action = PeerRingAction::MultiActions(vec![
+        PeerRingAction::sync_entries_for_repair(
+            StorageSyncDestination::PlacementKey(first_key),
+            vec![first],
+        ),
+        PeerRingAction::sync_entries_for_repair(
+            StorageSyncDestination::PlacementKey(second_key),
+            vec![second],
+        ),
+    ]);
+
+    let deliveries = action.coalesced_storage_sync_deliveries()?;
+
+    assert_eq!(deliveries.len(), 2);
+    let destinations = deliveries
+        .into_iter()
+        .map(|delivery| delivery.into_message_parts().1)
+        .collect::>();
+    assert_eq!(
+        destinations,
+        vec![
+            StorageSyncDestination::PlacementKey(first_key),
+            StorageSyncDestination::PlacementKey(second_key),
+        ]
+    );
+    Ok(())
+}
+
 struct FailingGetStorageFixture;
 
 #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
@@ -365,6 +429,55 @@ async fn virtual_storage_sync_copies_entries_to_observed_virtual_owner() -> Resu
     Ok(())
 }
 
+#[test]
+fn virtual_storage_sync_route_is_cancelled_when_owner_leaves_topology() -> Result<()> {
+    let local = Did::from(1u32);
+    let remote = Did::from(2u32);
+    let node = PeerRing::new_with_storage_finger_table_size_and_virtual_nodes(
+        local,
+        3,
+        Box::new(MemStorage::new()),
+        8,
+        VirtualNodeConfig::new(7, 2),
+    );
+    let _ = node.join(remote)?;
+    let destination = StorageSyncDestination::PhysicalOwner(remote);
+
+    assert!(node.storage_sync_route_still_permits(destination, remote)?);
+
+    node.remove(remote)?;
+
+    assert!(!node.storage_sync_route_still_permits(destination, remote)?);
+    Ok(())
+}
+
+#[test]
+fn placement_key_destination_exposes_observed_virtual_owner() -> Result<()> {
+    let local = Did::from(1u32);
+    let remote = Did::from(2u32);
+    let node = PeerRing::new_with_storage_finger_table_size_and_virtual_nodes(
+        local,
+        3,
+        Box::new(MemStorage::new()),
+        8,
+        VirtualNodeConfig::new(7, 2),
+    );
+    let _ = node.join(remote)?;
+    let placement = first_virtual_position(&node, remote)?;
+
+    assert_eq!(
+        node.observed_storage_sync_physical_owner(StorageSyncDestination::PlacementKey(placement))?,
+        Some(remote)
+    );
+
+    node.remove(remote)?;
+
+    let owner_after_removal =
+        node.observed_storage_sync_physical_owner(StorageSyncDestination::PlacementKey(placement))?;
+    assert_ne!(owner_after_removal, Some(remote));
+    Ok(())
+}
+
 #[tokio::test]
 async fn sync_without_ack_retains_entry_for_next_handoff() -> Result<()> {
     let node_did = Did::from(0u32);
@@ -377,10 +490,10 @@ async fn sync_without_ack_retains_entry_for_next_handoff() -> Result<()> {
 
     let action = node.sync_entries_with_successor(new_successor).await?;
     let retried_action = node.sync_entries_with_successor(new_successor).await?;
-    let expected = vec![(new_successor, vec![PlacedEntry::new(
-        placement_key,
-        entry.clone(),
-    )])];
+    let expected = vec![(
+        new_successor,
+        vec![PlacedEntry::new(placement_key, entry.clone())],
+    )];
 
     assert_eq!(collect_sync_batches(action)?, expected);
     assert_eq!(collect_sync_batches(retried_action)?, expected);
@@ -770,9 +883,10 @@ async fn read_repair_targets_only_observed_missing_placements() -> Result<()> {
         .read_repair_entry(evidence.entry.clone(), &evidence.misses, 3)
         .await?;
 
-    assert_eq!(evidence.misses, vec![PlacementMiss::new(
-        first_key, node.did
-    )]);
+    assert_eq!(
+        evidence.misses,
+        vec![PlacementMiss::new(first_key, node.did)]
+    );
     assert_eq!(repair, PeerRingAction::None);
     assert_eq!(
         node.storage.get(&first_key.to_string()).await?,
diff --git a/crates/core/src/dht/topology.rs b/crates/core/src/dht/topology.rs
index be207ffee..a065fd628 100644
--- a/crates/core/src/dht/topology.rs
+++ b/crates/core/src/dht/topology.rs
@@ -527,19 +527,17 @@ mod tests {
         );
 
         assert_eq!(next.state.successors, vec![peer]);
-        assert_eq!(next.state.fingers, vec![
-            Some(peer),
-            Some(peer),
-            Some(peer),
-            Some(peer),
-            None
-        ]);
-        assert_eq!(next.actions, vec![
-            TopologyAction::FindSuccessorForConnect {
+        assert_eq!(
+            next.state.fingers,
+            vec![Some(peer), Some(peer), Some(peer), Some(peer), None]
+        );
+        assert_eq!(
+            next.actions,
+            vec![TopologyAction::FindSuccessorForConnect {
                 next: peer,
                 did: local
-            }
-        ]);
+            }]
+        );
     }
 
     #[test]
@@ -626,11 +624,14 @@ mod tests {
         );
 
         assert_eq!(next.state.fix_finger_index, 3);
-        assert_eq!(next.actions, vec![TopologyAction::FindSuccessorForFix {
-            next: next_hop,
-            did: Did::power_of_two(3),
-            index: 3
-        }]);
+        assert_eq!(
+            next.actions,
+            vec![TopologyAction::FindSuccessorForFix {
+                next: next_hop,
+                did: Did::power_of_two(3),
+                index: 3
+            }]
+        );
     }
 
     #[test]
@@ -651,11 +652,14 @@ mod tests {
         );
 
         assert_eq!(next.state.fix_finger_index, 3);
-        assert_eq!(next.actions, vec![TopologyAction::FindSuccessorForFix {
-            next: next_hop,
-            did: local + Did::power_of_two(3),
-            index: 3
-        }]);
+        assert_eq!(
+            next.actions,
+            vec![TopologyAction::FindSuccessorForFix {
+                next: next_hop,
+                did: local + Did::power_of_two(3),
+                index: 3
+            }]
+        );
     }
 
     #[test]
diff --git a/crates/core/src/ecc/elgamal/impls/secp256k1.rs b/crates/core/src/ecc/elgamal/impls/secp256k1.rs
index fb81bcf38..9a75b703c 100644
--- a/crates/core/src/ecc/elgamal/impls/secp256k1.rs
+++ b/crates/core/src/ecc/elgamal/impls/secp256k1.rs
@@ -398,10 +398,13 @@ pub fn encrypt_aead_with_rng(
     let associated_data = aead_associated_data(&encrypted_key, aad)?;
     let cipher = ChaCha20Poly1305::new(Key::from_slice(key.as_slice()));
     let ciphertext = cipher
-        .encrypt(Nonce::from_slice(&nonce), Payload {
-            msg: plaintext,
-            aad: associated_data.as_slice(),
-        })
+        .encrypt(
+            Nonce::from_slice(&nonce),
+            Payload {
+                msg: plaintext,
+                aad: associated_data.as_slice(),
+            },
+        )
         .map_err(|_| Error::MessageEncryptionFailed("AEAD seal failed".to_string()))?;
 
     Ok(AeadCiphertext {
@@ -430,10 +433,13 @@ pub fn decrypt_aead(
     let associated_data = aead_associated_data(&sealed.encrypted_key, aad)?;
     let cipher = ChaCha20Poly1305::new(Key::from_slice(key.as_slice()));
     cipher
-        .decrypt(Nonce::from_slice(&sealed.nonce), Payload {
-            msg: sealed.ciphertext.as_slice(),
-            aad: associated_data.as_slice(),
-        })
+        .decrypt(
+            Nonce::from_slice(&sealed.nonce),
+            Payload {
+                msg: sealed.ciphertext.as_slice(),
+                aad: associated_data.as_slice(),
+            },
+        )
         .map_err(|_| Error::MessageDecryptionFailed("AEAD open failed".to_string()))
 }
 
diff --git a/crates/core/src/ecc/elgamal/mod.rs b/crates/core/src/ecc/elgamal/mod.rs
index 93edcb98b..bf13c11a4 100644
--- a/crates/core/src/ecc/elgamal/mod.rs
+++ b/crates/core/src/ecc/elgamal/mod.rs
@@ -98,7 +98,8 @@ pub struct ElGamalKeyPair {
 pub struct ElGamal(PhantomData);
 
 impl ElGamalPublicKey
-where Element: CyclicModule
+where
+    Element: CyclicModule,
 {
     /// Build a public key from an existing group element.
     pub fn from_element(element: Element) -> Self {
@@ -117,7 +118,8 @@ where Element: CyclicModule
 }
 
 impl Clone for ElGamalPublicKey
-where Element: CyclicModule + Clone
+where
+    Element: CyclicModule + Clone,
 {
     fn clone(&self) -> Self {
         Self::from_element(self.element.clone())
@@ -125,7 +127,8 @@ where Element: CyclicModule + Clone
 }
 
 impl ElGamalSecretKey
-where Element: CyclicModule
+where
+    Element: CyclicModule,
 {
     /// Build a secret key from an existing scalar.
     pub fn from_scalar(scalar: Element::Scalar) -> Self {
@@ -159,7 +162,8 @@ where
 }
 
 impl ElGamalKeyPair
-where Element: CyclicModule
+where
+    Element: CyclicModule,
 {
     /// Borrow the public key.
     pub fn public_key(&self) -> &ElGamalPublicKey {
@@ -173,7 +177,8 @@ where Element: CyclicModule
 }
 
 impl ElGamalSecretKey
-where Element: CyclicModule
+where
+    Element: CyclicModule,
 {
     /// Generate a fresh non-zero ElGamal secret scalar from an explicit RNG.
     pub fn random_with_rng(rng: &mut impl RngCore) -> Self {
@@ -187,7 +192,8 @@ where Element: CyclicModule
 }
 
 impl ElGamalKeyPair
-where Element: CyclicModule
+where
+    Element: CyclicModule,
 {
     /// Generate a fresh ElGamal key pair from an explicit RNG.
     pub fn random_with_rng(rng: &mut impl RngCore) -> Self {
diff --git a/crates/core/src/ecc/mod.rs b/crates/core/src/ecc/mod.rs
index dbb062513..dd25a0535 100644
--- a/crates/core/src/ecc/mod.rs
+++ b/crates/core/src/ecc/mod.rs
@@ -210,7 +210,8 @@ impl From for PublicKey<33> {
 }
 
 impl From for HashStr
-where T: Into
+where
+    T: Into,
 {
     fn from(s: T) -> Self {
         let inputs = s.into();
@@ -251,21 +252,27 @@ impl<'de> serde::de::Visitor<'de> for SecretKeyVisitor {
         formatter.write_str("SecretKey deserializer")
     }
     fn visit_str(self, value: &str) -> std::result::Result
-    where E: serde::de::Error {
+    where
+        E: serde::de::Error,
+    {
         SecretKey::from_str(value).map_err(|e| serde::de::Error::custom(e))
     }
 }
 
 impl<'de> Deserialize<'de> for SecretKey {
     fn deserialize(deserializer: D) -> std::result::Result
-    where D: serde::Deserializer<'de> {
+    where
+        D: serde::Deserializer<'de>,
+    {
         deserializer.deserialize_str(SecretKeyVisitor)
     }
 }
 
 impl Serialize for SecretKey {
     fn serialize(&self, serializer: S) -> std::result::Result
-    where S: serde::Serializer {
+    where
+        S: serde::Serializer,
+    {
         serializer.serialize_str(self.to_string().as_str())
     }
 }
@@ -343,7 +350,9 @@ impl PublicKey<33> {
 
 /// Recover PublicKey from RawMessage using signature.
 pub fn recover(message: &[u8], signature: S) -> Result>
-where S: AsRef<[u8]> {
+where
+    S: AsRef<[u8]>,
+{
     let sig_bytes: SigBytes = signature.as_ref().try_into()?;
     let message_hash: [u8; 32] = keccak256(message);
     recover_hash(&message_hash, &sig_bytes)
diff --git a/crates/core/src/ecc/types.rs b/crates/core/src/ecc/types.rs
index a2e70f22b..c70f12e48 100644
--- a/crates/core/src/ecc/types.rs
+++ b/crates/core/src/ecc/types.rs
@@ -14,7 +14,9 @@ struct PublicKeyVisitor;
 // /// twist from https://docs.rs/libsecp256k1/latest/src/libsecp256k1/lib.rs.html#335-344
 impl Serialize for PublicKey {
     fn serialize(&self, serializer: S) -> std::result::Result
-    where S: serde::ser::Serializer {
+    where
+        S: serde::ser::Serializer,
+    {
         serializer.serialize_str(
             &base58_monero::encode_check(&self.0[..]).map_err(serde::ser::Error::custom)?,
         )
@@ -101,7 +103,9 @@ impl<'de, const SIZE: usize> serde::de::Visitor<'de> for PublicKeyVisitor
     }
 
     fn visit_str(self, value: &str) -> std::result::Result
-    where E: serde::de::Error {
+    where
+        E: serde::de::Error,
+    {
         let value =
             base58_monero::decode_check(value).map_err(|_| E::custom(Error::PublicKeyBadFormat))?;
         if SIZE == 33 {
@@ -114,7 +118,9 @@ impl<'de, const SIZE: usize> serde::de::Visitor<'de> for PublicKeyVisitor
 
 impl<'de, const SIZE: usize> Deserialize<'de> for PublicKey {
     fn deserialize(deserializer: D) -> std::result::Result
-    where D: serde::de::Deserializer<'de> {
+    where
+        D: serde::de::Deserializer<'de>,
+    {
         deserializer.deserialize_str(PublicKeyVisitor)
     }
 }
diff --git a/crates/core/src/error.rs b/crates/core/src/error.rs
index c8b0c2571..a5dd46aef 100644
--- a/crates/core/src/error.rs
+++ b/crates/core/src/error.rs
@@ -572,6 +572,21 @@ pub enum Error {
     #[error("Peer's negotiated max_message_size {0} is too small to carry even one chunk")]
     PeerMaxMessageSizeTooSmall(usize),
 
+    /// Timed out while waiting for the data-channel send queue to accept bytes
+    #[error(
+        "Timed out after {timeout_ms}ms waiting for data-channel send queue to accept {bytes} bytes for {peer} during {context}"
+    )]
+    DataChannelSendQueueTimeout {
+        /// Peer whose data-channel send queue did not accept the bytes.
+        peer: crate::dht::Did,
+        /// Timeout budget in milliseconds.
+        timeout_ms: u128,
+        /// Serialized bytes that were waiting to be accepted.
+        bytes: usize,
+        /// Send context used for diagnostics.
+        context: &'static str,
+    },
+
     #[cfg(all(feature = "wasm", target_family = "wasm"))]
     /// Cannot get property {0} from JsValue
     #[error("Cannot get property {0} from JsValue")]
diff --git a/crates/core/src/inspect.rs b/crates/core/src/inspect.rs
index 15f90470d..4058a82fe 100644
--- a/crates/core/src/inspect.rs
+++ b/crates/core/src/inspect.rs
@@ -122,7 +122,9 @@ impl StorageInspect {
 
 /// Compress equal adjacent iterator values into inclusive index ranges.
 pub fn compress_iter(iter: impl Iterator) -> Vec<(T, u64, u64)>
-where T: PartialEq {
+where
+    T: PartialEq,
+{
     let mut result = vec![];
     let mut start = 0u64;
     let mut count = 0u64;
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
index 31d74f2b2..9c42f618e 100644
--- a/crates/core/src/lib.rs
+++ b/crates/core/src/lib.rs
@@ -74,6 +74,7 @@ pub mod algebra;
 pub mod dht;
 pub mod ecc;
 pub mod error;
+pub mod lifecycle;
 pub mod macros;
 pub mod message;
 pub mod prelude;
diff --git a/crates/core/src/lifecycle.rs b/crates/core/src/lifecycle.rs
new file mode 100644
index 000000000..5b5db7116
--- /dev/null
+++ b/crates/core/src/lifecycle.rs
@@ -0,0 +1,104 @@
+//! Cooperative lifecycle primitives shared by native and browser runtimes.
+//!
+//! A [`StopSource`] is the authority that may request shutdown. A [`StopToken`]
+//! is the read-only capability handed to long-running loops. The model is
+//! intentionally monotonic: once a source requests stop, every token cloned from
+//! that source observes stop forever.
+
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+
+/// Authority that can request cooperative shutdown for one lifecycle scope.
+#[derive(Clone, Debug, Default)]
+pub struct StopSource {
+    requested: Arc,
+}
+
+impl StopSource {
+    /// Create a fresh lifecycle source in the running state.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Create a read-only token linked to this source.
+    pub fn token(&self) -> StopToken {
+        StopToken {
+            requested: self.requested.clone(),
+        }
+    }
+
+    /// Request shutdown for every token linked to this source.
+    ///
+    /// This operation is idempotent and monotonic; there is no resume state.
+    pub fn request_stop(&self) {
+        self.requested.store(true, Ordering::Release);
+    }
+
+    /// Return whether this source has requested shutdown.
+    pub fn is_stop_requested(&self) -> bool {
+        self.requested.load(Ordering::Acquire)
+    }
+}
+
+/// Read-only cooperative shutdown capability for long-running loops.
+#[derive(Clone, Debug, Default)]
+pub struct StopToken {
+    requested: Arc,
+}
+
+impl StopToken {
+    /// Create a token that is never stopped by an external source.
+    pub fn never() -> Self {
+        Self::default()
+    }
+
+    /// Return whether the owner has requested cooperative shutdown.
+    pub fn should_stop(&self) -> bool {
+        self.requested.load(Ordering::Acquire)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn stop_source_propagates_stop_to_existing_and_cloned_tokens() {
+        let source = StopSource::new();
+        let first = source.token();
+        let second = first.clone();
+
+        assert!(!first.should_stop());
+        assert!(!second.should_stop());
+        assert!(!source.is_stop_requested());
+
+        source.request_stop();
+
+        assert!(first.should_stop());
+        assert!(second.should_stop());
+        assert!(source.is_stop_requested());
+    }
+
+    #[test]
+    fn cloned_stop_source_controls_the_same_lifecycle_scope() {
+        let source = StopSource::new();
+        let cloned_source = source.clone();
+        let token = source.token();
+
+        cloned_source.request_stop();
+
+        assert!(token.should_stop());
+        assert!(source.is_stop_requested());
+    }
+
+    #[test]
+    fn never_token_is_independent_from_other_sources() {
+        let source = StopSource::new();
+        let token = StopToken::never();
+
+        source.request_stop();
+
+        assert!(!token.should_stop());
+    }
+}
diff --git a/crates/core/src/measure.rs b/crates/core/src/measure.rs
index 2eb440d81..7538d9125 100644
--- a/crates/core/src/measure.rs
+++ b/crates/core/src/measure.rs
@@ -114,7 +114,9 @@ impl PeerMeasurement {
     /// Returns `None` when no counter has ever been recorded for `did`; absence
     /// is distinct from an observed peer with non-zero counters.
     pub async fn from_measure(measure: &M, did: Did) -> Option
-    where M: Measure + ?Sized {
+    where
+        M: Measure + ?Sized,
+    {
         let evidence = PeerQualityEvidence::from_measure(measure, did).await;
         if evidence.is_unobserved() {
             return None;
@@ -146,7 +148,9 @@ impl PeerQualityEvidence {
 
     /// Read all counters for `did` from a measurement implementation.
     pub async fn from_measure(measure: &M, did: Did) -> Self
-    where M: Measure + ?Sized {
+    where
+        M: Measure + ?Sized,
+    {
         Self {
             connected: measure.get_count(did, MeasureCounter::Connect).await,
             disconnected: measure.get_count(did, MeasureCounter::Disconnected).await,
diff --git a/crates/core/src/message/effects.rs b/crates/core/src/message/effects.rs
index 7c4bef5e6..28b946752 100644
--- a/crates/core/src/message/effects.rs
+++ b/crates/core/src/message/effects.rs
@@ -271,12 +271,10 @@ impl From for PeerRingAction {
             DhtActionFunctor::FindSuccessorForConnect { next, did } => {
                 Self::RemoteAction(next, PeerRingRemoteAction::FindSuccessorForConnect(did))
             }
-            DhtActionFunctor::FindSuccessorForFix { next, did, index } => {
-                Self::RemoteAction(next, PeerRingRemoteAction::FindSuccessorForFix {
-                    did,
-                    index,
-                })
-            }
+            DhtActionFunctor::FindSuccessorForFix { next, did, index } => Self::RemoteAction(
+                next,
+                PeerRingRemoteAction::FindSuccessorForFix { did, index },
+            ),
             DhtActionFunctor::QueryForSuccessorList { successor } => {
                 Self::RemoteAction(successor, PeerRingRemoteAction::QueryForSuccessorList)
             }
@@ -726,10 +724,10 @@ mod tests {
         let index = 11;
 
         let effect = single_effect(lower_dht_action(
-            &PeerRingAction::RemoteAction(next, PeerRingRemoteAction::FindSuccessorForFix {
-                did: target,
-                index,
-            }),
+            &PeerRingAction::RemoteAction(
+                next,
+                PeerRingRemoteAction::FindSuccessorForFix { did: target, index },
+            ),
             |_| true,
         ))?;
 
diff --git a/crates/core/src/message/encoder.rs b/crates/core/src/message/encoder.rs
index 330531467..87e6b20e8 100644
--- a/crates/core/src/message/encoder.rs
+++ b/crates/core/src/message/encoder.rs
@@ -135,7 +135,9 @@ impl Encoded {
 
     /// Decode this value into a target type implementing [`Decoder`].
     pub fn decode(&self) -> Result
-    where T: Decoder {
+    where
+        T: Decoder,
+    {
         T::from_encoded(self)
     }
 }
diff --git a/crates/core/src/message/handlers/connection.rs b/crates/core/src/message/handlers/connection.rs
index 201fe89fe..9ad48e30c 100644
--- a/crates/core/src/message/handlers/connection.rs
+++ b/crates/core/src/message/handlers/connection.rs
@@ -16,6 +16,8 @@ use crate::message::types::ConnectNodeSend;
 use crate::message::types::FindSuccessorReport;
 use crate::message::types::FindSuccessorSend;
 use crate::message::types::Message;
+use crate::message::types::PeerLivenessProbe;
+use crate::message::types::PeerLivenessReport;
 use crate::message::types::QueryForTopoInfoReport;
 use crate::message::types::QueryForTopoInfoSend;
 use crate::message::types::Then;
@@ -56,6 +58,35 @@ fn connect_successor_hint(dht: &PeerRing, requester: Did, reported: Did) -> Resu
         .unwrap_or(reported))
 }
 
+/// PeerLivenessProbe is a direct overlay liveness probe.
+#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
+impl HandleMsg for MessageHandler {
+    async fn handle(&self, ctx: &MessagePayload, msg: &PeerLivenessProbe) -> Result<()> {
+        if ctx.should_forward_from(self.dht.did) {
+            return self
+                .run_effects([PayloadRelayFunctor::forward_payload(ctx, None).into()])
+                .await;
+        }
+
+        self.run_effects([PayloadRelayFunctor::send_report_message(
+            ctx,
+            Message::PeerLivenessReport(msg.resp()),
+        )
+        .into()])
+            .await
+    }
+}
+
+/// PeerLivenessReport is handled by the callback's verified-inbound liveness update.
+#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
+impl HandleMsg for MessageHandler {
+    async fn handle(&self, _ctx: &MessagePayload, _msg: &PeerLivenessReport) -> Result<()> {
+        Ok(())
+    }
+}
+
 /// QueryForTopoInfoSend is direct message
 #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
@@ -117,21 +148,66 @@ impl HandleMsg for MessageHandler {
 impl HandleMsg for MessageHandler {
     async fn handle(&self, ctx: &MessagePayload, msg: &ConnectNodeSend) -> Result<()> {
         if !self.transport.accepts_connection_offer(msg) {
+            tracing::warn!(
+                local = %self.dht.did,
+                tx_id = %ctx.transaction.tx_id,
+                origin = ?ctx.relay.try_origin_sender().ok(),
+                relay_destination = %ctx.relay.destination,
+                transaction_destination = %ctx.transaction.destination,
+                mode = ?msg.dht_protocol_mode(),
+                "CONNECT_NODE offer rejected by DHT protocol mismatch"
+            );
             return Ok(());
         }
 
         if ctx.should_forward_from(self.dht.did) {
+            tracing::info!(
+                local = %self.dht.did,
+                tx_id = %ctx.transaction.tx_id,
+                origin = ?ctx.relay.try_origin_sender().ok(),
+                next_hop = %ctx.relay.next_hop,
+                relay_destination = %ctx.relay.destination,
+                transaction_destination = %ctx.transaction.destination,
+                sdp_bytes = msg.sdp.len(),
+                "CONNECT_NODE offer forward"
+            );
             self.run_effects([PayloadRelayFunctor::forward_payload(ctx, None).into()])
                 .await
         } else {
-            let answer = self
+            let peer = ctx.relay.try_origin_sender()?;
+            tracing::info!(
+                local = %self.dht.did,
+                peer = %peer,
+                tx_id = %ctx.transaction.tx_id,
+                sdp_bytes = msg.sdp.len(),
+                "CONNECT_NODE offer answer start"
+            );
+            let answer = match self
                 .transport
-                .answer_remote_connection(
-                    ctx.relay.try_origin_sender()?,
-                    self.inner_callback(),
-                    msg,
-                )
-                .await?;
+                .answer_remote_connection(peer, self.inner_callback(), msg)
+                .await
+            {
+                Ok(answer) => {
+                    tracing::info!(
+                        local = %self.dht.did,
+                        peer = %peer,
+                        tx_id = %ctx.transaction.tx_id,
+                        sdp_bytes = answer.sdp.len(),
+                        "CONNECT_NODE offer answer complete"
+                    );
+                    answer
+                }
+                Err(error) => {
+                    tracing::warn!(
+                        local = %self.dht.did,
+                        peer = %peer,
+                        tx_id = %ctx.transaction.tx_id,
+                        error = ?error,
+                        "CONNECT_NODE offer answer failed"
+                    );
+                    return Err(error);
+                }
+            };
             self.run_effects([PayloadRelayFunctor::send_report_message(
                 ctx,
                 Message::ConnectNodeReport(answer),
@@ -147,12 +223,48 @@ impl HandleMsg for MessageHandler {
 impl HandleMsg for MessageHandler {
     async fn handle(&self, ctx: &MessagePayload, msg: &ConnectNodeReport) -> Result<()> {
         if ctx.should_forward_from(self.dht.did) {
+            tracing::info!(
+                local = %self.dht.did,
+                tx_id = %ctx.transaction.tx_id,
+                origin = ?ctx.relay.try_origin_sender().ok(),
+                next_hop = %ctx.relay.next_hop,
+                relay_destination = %ctx.relay.destination,
+                transaction_destination = %ctx.transaction.destination,
+                sdp_bytes = msg.sdp.len(),
+                "CONNECT_NODE answer forward"
+            );
             self.run_effects([PayloadRelayFunctor::forward_payload(ctx, None).into()])
                 .await
         } else {
-            self.transport
-                .accept_remote_connection(ctx.relay.try_origin_sender()?, msg)
-                .await
+            let peer = ctx.relay.try_origin_sender()?;
+            tracing::info!(
+                local = %self.dht.did,
+                peer = %peer,
+                tx_id = %ctx.transaction.tx_id,
+                sdp_bytes = msg.sdp.len(),
+                "CONNECT_NODE answer accept start"
+            );
+            match self.transport.accept_remote_connection(peer, msg).await {
+                Ok(()) => {
+                    tracing::info!(
+                        local = %self.dht.did,
+                        peer = %peer,
+                        tx_id = %ctx.transaction.tx_id,
+                        "CONNECT_NODE answer accept complete"
+                    );
+                    Ok(())
+                }
+                Err(error) => {
+                    tracing::warn!(
+                        local = %self.dht.did,
+                        peer = %peer,
+                        tx_id = %ctx.transaction.tx_id,
+                        error = ?error,
+                        "CONNECT_NODE answer accept failed"
+                    );
+                    Err(error)
+                }
+            }
         }
     }
 }
@@ -430,27 +542,27 @@ pub mod tests {
             node1.assert_transports(vec![node2.did(), node3.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node1.did(), node2.did()]);
-            assert_eq!(node1.dht().successors().list()?, vec![
-                node2.did(),
-                node3.did()
-            ]);
-            assert_eq!(node2.dht().successors().list()?, vec![
-                node3.did(),
-                node1.did()
-            ]);
-            assert_eq!(node3.dht().successors().list()?, vec![
-                node1.did(),
-                node2.did()
-            ]);
+            assert_eq!(
+                node1.dht().successors().list()?,
+                vec![node2.did(), node3.did()]
+            );
+            assert_eq!(
+                node2.dht().successors().list()?,
+                vec![node3.did(), node1.did()]
+            );
+            assert_eq!(
+                node3.dht().successors().list()?,
+                vec![node1.did(), node2.did()]
+            );
         } else {
             node1.assert_transports(vec![node2.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node2.did()]);
             assert_eq!(node1.dht().successors().list()?, vec![node2.did(),]);
-            assert_eq!(node2.dht().successors().list()?, vec![
-                node3.did(),
-                node1.did()
-            ]);
+            assert_eq!(
+                node2.dht().successors().list()?,
+                vec![node3.did(), node1.did()]
+            );
             assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
         }
 
@@ -468,18 +580,18 @@ pub mod tests {
         node1.assert_transports(vec![node2.did(), node3.did()]);
         node2.assert_transports(vec![node1.did(), node3.did()]);
         node3.assert_transports(vec![node1.did(), node2.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![
-            node2.did(),
-            node3.did()
-        ]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node3.did(),
-            node1.did()
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![
-            node1.did(),
-            node2.did()
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![node2.did(), node3.did()]
+        );
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node3.did(), node1.did()]
+        );
+        assert_eq!(
+            node3.dht().successors().list()?,
+            vec![node1.did(), node2.did()]
+        );
 
         Ok((node1, node2, node3))
     }
@@ -518,27 +630,27 @@ pub mod tests {
             node1.assert_transports(vec![node2.did(), node3.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node1.did(), node2.did()]);
-            assert_eq!(node1.dht().successors().list()?, vec![
-                node3.did(),
-                node2.did()
-            ]);
-            assert_eq!(node2.dht().successors().list()?, vec![
-                node1.did(),
-                node3.did()
-            ]);
-            assert_eq!(node3.dht().successors().list()?, vec![
-                node2.did(),
-                node1.did()
-            ]);
+            assert_eq!(
+                node1.dht().successors().list()?,
+                vec![node3.did(), node2.did()]
+            );
+            assert_eq!(
+                node2.dht().successors().list()?,
+                vec![node1.did(), node3.did()]
+            );
+            assert_eq!(
+                node3.dht().successors().list()?,
+                vec![node2.did(), node1.did()]
+            );
         } else {
             node1.assert_transports(vec![node2.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node2.did()]);
             assert_eq!(node1.dht().successors().list()?, vec![node2.did()]);
-            assert_eq!(node2.dht().successors().list()?, vec![
-                node1.did(),
-                node3.did()
-            ]);
+            assert_eq!(
+                node2.dht().successors().list()?,
+                vec![node1.did(), node3.did()]
+            );
             assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
         }
 
@@ -556,18 +668,18 @@ pub mod tests {
         node1.assert_transports(vec![node2.did(), node3.did()]);
         node2.assert_transports(vec![node1.did(), node3.did()]);
         node3.assert_transports(vec![node1.did(), node2.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![
-            node3.did(),
-            node2.did()
-        ]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node1.did(),
-            node3.did()
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![
-            node2.did(),
-            node1.did()
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![node3.did(), node2.did()]
+        );
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node1.did(), node3.did()]
+        );
+        assert_eq!(
+            node3.dht().successors().list()?,
+            vec![node2.did(), node1.did()]
+        );
 
         Ok((node1, node2, node3))
     }
@@ -617,26 +729,22 @@ pub mod tests {
         node2.assert_transports(vec![node3.did(), node4.did(), node1.did()]);
         node3.assert_transports(vec![node4.did(), node1.did(), node2.did()]);
         node4.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![
-            node2.did(),
-            node3.did(),
-            node4.did(),
-        ]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node3.did(),
-            node4.did(),
-            node1.did(),
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![
-            node4.did(),
-            node1.did(),
-            node2.did(),
-        ]);
-        assert_eq!(node4.dht().successors().list()?, vec![
-            node1.did(),
-            node2.did(),
-            node3.did(),
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![node2.did(), node3.did(), node4.did(),]
+        );
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node3.did(), node4.did(), node1.did(),]
+        );
+        assert_eq!(
+            node3.dht().successors().list()?,
+            vec![node4.did(), node1.did(), node2.did(),]
+        );
+        assert_eq!(
+            node4.dht().successors().list()?,
+            vec![node1.did(), node2.did(), node3.did(),]
+        );
 
         println!("========================================");
         println!("| test node4 connect node3 via dht     |");
@@ -677,26 +785,22 @@ pub mod tests {
         node2.assert_transports(vec![node3.did(), node4.did(), node1.did()]);
         node3.assert_transports(vec![node4.did(), node1.did(), node2.did()]);
         node4.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![
-            node2.did(),
-            node3.did(),
-            node4.did()
-        ]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node3.did(),
-            node4.did(),
-            node1.did(),
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![
-            node4.did(),
-            node1.did(),
-            node2.did(),
-        ]);
-        assert_eq!(node4.dht().successors().list()?, vec![
-            node1.did(),
-            node2.did(),
-            node3.did(),
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![node2.did(), node3.did(), node4.did()]
+        );
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node3.did(), node4.did(), node1.did(),]
+        );
+        assert_eq!(
+            node3.dht().successors().list()?,
+            vec![node4.did(), node1.did(), node2.did(),]
+        );
+        assert_eq!(
+            node4.dht().successors().list()?,
+            vec![node1.did(), node2.did(), node3.did(),]
+        );
 
         Ok(())
     }
@@ -726,16 +830,14 @@ pub mod tests {
         assert_no_more_msg([&node1, &node2, &node3, &joining]).await;
 
         joining.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
-        assert_eq!(node1.dht().successors().list()?, vec![
-            joining.did(),
-            node2.did(),
-            node3.did(),
-        ]);
-        assert_eq!(joining.dht().successors().list()?, vec![
-            node2.did(),
-            node3.did(),
-            node1.did(),
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![joining.did(), node2.did(), node3.did(),]
+        );
+        assert_eq!(
+            joining.dht().successors().list()?,
+            vec![node2.did(), node3.did(), node1.did(),]
+        );
 
         Ok(())
     }
diff --git a/crates/core/src/message/handlers/stabilization.rs b/crates/core/src/message/handlers/stabilization.rs
index 4aba3e4b5..0a14d2fb8 100644
--- a/crates/core/src/message/handlers/stabilization.rs
+++ b/crates/core/src/message/handlers/stabilization.rs
@@ -75,7 +75,7 @@ impl HandleMsg for MessageHandler {
             .dht
             .sync_entries_with_successor(msg.did)
             .await?
-            .storage_sync_deliveries()?;
+            .coalesced_storage_sync_deliveries()?;
         let effects = deliveries.into_iter().map(|delivery| {
             let msg = SyncEntriesWithSuccessor::from_delivery(delivery);
             StorageSyncFunctor::send_storage_sync(msg).into()
@@ -319,10 +319,10 @@ mod test {
                 ..
             }) => {
                 assert_eq!(purpose, StorageSyncPurpose::OwnershipHandoff);
-                assert_eq!(acks, vec![SyncedEntryAck::new(
-                    entry.did,
-                    stored_entry.clone()
-                )]);
+                assert_eq!(
+                    acks,
+                    vec![SyncedEntryAck::new(entry.did, stored_entry.clone())]
+                );
             }
             message => {
                 return Err(Error::InvalidMessage(format!(
@@ -365,18 +365,18 @@ mod test {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before stabilization ===");
-        assert_eq!(node1.dht().successors().list()?, vec![
-            node2.did(),
-            node3.did()
-        ]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node3.did(),
-            node1.did()
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![
-            node1.did(),
-            node2.did()
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![node2.did(), node3.did()]
+        );
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node3.did(), node1.did()]
+        );
+        assert_eq!(
+            node3.dht().successors().list()?,
+            vec![node1.did(), node2.did()]
+        );
         assert!(node1.dht().lock_predecessor()?.is_none());
         assert!(node2.dht().lock_predecessor()?.is_none());
         assert!(node3.dht().lock_predecessor()?.is_none());
@@ -394,10 +394,10 @@ mod test {
 
         println!("=== Check state after first stabilization ===");
         assert!(node1.dht().successors().list()?.contains(&node2.did()));
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node3.did(),
-            node1.did()
-        ]);
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node3.did(), node1.did()]
+        );
         assert!(node3.dht().successors().list()?.contains(&node2.did()));
 
         println!("==========================================");
@@ -413,18 +413,18 @@ mod test {
             assert_no_more_msg([&node1, &node2, &node3]).await;
 
             println!("=== Check state after stabilization ===");
-            assert_eq!(node1.dht().successors().list()?, vec![
-                node2.did(),
-                node3.did()
-            ]);
-            assert_eq!(node2.dht().successors().list()?, vec![
-                node3.did(),
-                node1.did()
-            ]);
-            assert_eq!(node3.dht().successors().list()?, vec![
-                node1.did(),
-                node2.did()
-            ]);
+            assert_eq!(
+                node1.dht().successors().list()?,
+                vec![node2.did(), node3.did()]
+            );
+            assert_eq!(
+                node2.dht().successors().list()?,
+                vec![node3.did(), node1.did()]
+            );
+            assert_eq!(
+                node3.dht().successors().list()?,
+                vec![node1.did(), node2.did()]
+            );
         }
 
         println!("=== Check predecessor after all stabilization ===");
@@ -460,18 +460,18 @@ mod test {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before stabilization ===");
-        assert_eq!(node1.dht().successors().list()?, vec![
-            node3.did(),
-            node2.did()
-        ]);
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node1.did(),
-            node3.did()
-        ]);
-        assert_eq!(node3.dht().successors().list()?, vec![
-            node2.did(),
-            node1.did()
-        ]);
+        assert_eq!(
+            node1.dht().successors().list()?,
+            vec![node3.did(), node2.did()]
+        );
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node1.did(), node3.did()]
+        );
+        assert_eq!(
+            node3.dht().successors().list()?,
+            vec![node2.did(), node1.did()]
+        );
         assert!(node1.dht().lock_predecessor()?.is_none());
         assert!(node2.dht().lock_predecessor()?.is_none());
         assert!(node3.dht().lock_predecessor()?.is_none());
@@ -489,10 +489,10 @@ mod test {
 
         println!("=== Check state after first stabilization ===");
         assert!(node1.dht().successors().list()?.contains(&node2.did()));
-        assert_eq!(node2.dht().successors().list()?, vec![
-            node1.did(),
-            node3.did()
-        ]);
+        assert_eq!(
+            node2.dht().successors().list()?,
+            vec![node1.did(), node3.did()]
+        );
         assert!(node3.dht().successors().list()?.contains(&node2.did()));
 
         println!("==========================================");
@@ -508,18 +508,18 @@ mod test {
             assert_no_more_msg([&node1, &node2, &node3]).await;
 
             println!("=== Check state after stabilization ===");
-            assert_eq!(node1.dht().successors().list()?, vec![
-                node3.did(),
-                node2.did()
-            ]);
-            assert_eq!(node2.dht().successors().list()?, vec![
-                node1.did(),
-                node3.did()
-            ]);
-            assert_eq!(node3.dht().successors().list()?, vec![
-                node2.did(),
-                node1.did()
-            ]);
+            assert_eq!(
+                node1.dht().successors().list()?,
+                vec![node3.did(), node2.did()]
+            );
+            assert_eq!(
+                node2.dht().successors().list()?,
+                vec![node1.did(), node3.did()]
+            );
+            assert_eq!(
+                node3.dht().successors().list()?,
+                vec![node2.did(), node1.did()]
+            );
         }
 
         println!("=== Check predecessor after all stabilization ===");
diff --git a/crates/core/src/message/handlers/storage.rs b/crates/core/src/message/handlers/storage.rs
index df06174ea..881e11f31 100644
--- a/crates/core/src/message/handlers/storage.rs
+++ b/crates/core/src/message/handlers/storage.rs
@@ -208,7 +208,7 @@ async fn run_storage_repair_transport_effects(
     transport: Arc,
     act: PeerRingAction,
 ) -> Result<()> {
-    for delivery in act.storage_sync_deliveries()? {
+    for delivery in act.coalesced_storage_sync_deliveries()? {
         let msg = SyncEntriesWithSuccessor::from_delivery(delivery);
         transport.send_storage_sync(msg).await?;
     }
@@ -221,7 +221,7 @@ async fn run_storage_repair_transport_effects(
 /// exactly; the transport interpreter chooses the storage route and records the
 /// ack capability at the effect boundary.
 pub(super) fn storage_sync_effects(act: PeerRingAction) -> Result>> {
-    act.storage_sync_deliveries()?
+    act.coalesced_storage_sync_deliveries()?
         .into_iter()
         .map(|delivery| {
             let msg = SyncEntriesWithSuccessor::from_delivery(delivery);
diff --git a/crates/core/src/message/handlers/storage/tests/test_repair.rs b/crates/core/src/message/handlers/storage/tests/test_repair.rs
index 0ab1df80c..67fad7495 100644
--- a/crates/core/src/message/handlers/storage/tests/test_repair.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_repair.rs
@@ -257,20 +257,26 @@ async fn found_entry_repairs_buffered_misses_only() -> Result<()> {
     node.swarm.transport.start_storage_lookup(entry.did, 2)?;
 
     handler
-        .handle(&context, &FoundEntry {
-            data: vec![],
-            misses: vec![PlacementMiss::new(placement_key, node.did())],
-            resource: entry.did,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![],
+                misses: vec![PlacementMiss::new(placement_key, node.did())],
+                resource: entry.did,
+                redundancy: 2,
+            },
+        )
         .await?;
     handler
-        .handle(&context, &FoundEntry {
-            data: vec![entry.clone()],
-            misses: vec![],
-            resource: entry.did,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![entry.clone()],
+                misses: vec![],
+                resource: entry.did,
+                redundancy: 2,
+            },
+        )
         .await?;
 
     assert_eq!(
@@ -314,12 +320,15 @@ async fn found_entry_rejects_multiple_entries() -> Result<()> {
     )?;
 
     let result = handler
-        .handle(&context, &FoundEntry {
-            data: vec![first, second],
-            misses: vec![],
-            resource,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![first, second],
+                misses: vec![],
+                resource,
+                redundancy: 2,
+            },
+        )
         .await;
 
     assert!(
@@ -356,12 +365,15 @@ async fn found_entry_rejects_redundancy_outside_local_protocol_mode() -> Result<
     node.swarm.transport.start_storage_lookup(resource, 2)?;
 
     let result = handler
-        .handle(&context, &FoundEntry {
-            data: vec![entry],
-            misses: vec![],
-            resource,
-            redundancy: 3,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![entry],
+                misses: vec![],
+                resource,
+                redundancy: 3,
+            },
+        )
         .await;
 
     assert!(matches!(
@@ -400,12 +412,15 @@ async fn found_entry_rejects_response_without_active_lookup() -> Result<()> {
     )?;
 
     let result = handler
-        .handle(&context, &FoundEntry {
-            data: vec![entry],
-            misses: vec![],
-            resource,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![entry],
+                misses: vec![],
+                resource,
+                redundancy: 2,
+            },
+        )
         .await;
 
     assert!(matches!(
@@ -442,12 +457,15 @@ async fn found_entry_rejects_resource_mismatch_without_cache_write() -> Result<(
     node.swarm.transport.start_storage_lookup(resource, 2)?;
 
     let result = handler
-        .handle(&context, &FoundEntry {
-            data: vec![entry.clone()],
-            misses: vec![],
-            resource,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![entry.clone()],
+                misses: vec![],
+                resource,
+                redundancy: 2,
+            },
+        )
         .await;
 
     assert!(matches!(
@@ -466,9 +484,11 @@ async fn storage_miss_observation_buffer_is_bounded() -> Result<()> {
         let resource = Did::from((index + 1) as u32);
         let placement = Did::from((index + 10_000) as u32);
         node.swarm.transport.start_storage_lookup(resource, 2)?;
-        node.swarm
-            .transport
-            .observe_storage_misses(resource, 2, [PlacementMiss::new(placement, node.did())])?;
+        node.swarm.transport.observe_storage_misses(
+            resource,
+            2,
+            [PlacementMiss::new(placement, node.did())],
+        )?;
     }
 
     assert!(
@@ -484,9 +504,11 @@ async fn storage_fetch_starts_fresh_observation_round() -> Result<()> {
     let resource = Did::from(10u32);
     let placement = Did::from(100u32);
     node.swarm.transport.start_storage_lookup(resource, 1)?;
-    node.swarm
-        .transport
-        .observe_storage_misses(resource, 1, [PlacementMiss::new(placement, node.did())])?;
+    node.swarm.transport.observe_storage_misses(
+        resource,
+        1,
+        [PlacementMiss::new(placement, node.did())],
+    )?;
 
     node.swarm.transport.start_storage_lookup(resource, 1)?;
     let misses = node.swarm.transport.take_storage_misses(resource, 1)?;
@@ -527,23 +549,29 @@ async fn expired_storage_response_does_not_update_cache_or_repair() -> Result<()
     node.swarm.transport.start_storage_lookup(entry.did, 2)?;
 
     handler
-        .handle(&context, &FoundEntry {
-            data: vec![],
-            misses: vec![PlacementMiss::new(placement_key, node.did())],
-            resource: entry.did,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![],
+                misses: vec![PlacementMiss::new(placement_key, node.did())],
+                resource: entry.did,
+                redundancy: 2,
+            },
+        )
         .await?;
     node.swarm
         .transport
         .expire_storage_lookup_observation(entry.did, 2)?;
     let result = handler
-        .handle(&context, &FoundEntry {
-            data: vec![entry.clone()],
-            misses: vec![],
-            resource: entry.did,
-            redundancy: 2,
-        })
+        .handle(
+            &context,
+            &FoundEntry {
+                data: vec![entry.clone()],
+                misses: vec![],
+                resource: entry.did,
+                redundancy: 2,
+            },
+        )
         .await;
 
     assert!(matches!(
diff --git a/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs b/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs
index 78c863861..99fb3e504 100644
--- a/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs
@@ -79,10 +79,10 @@ async fn sync_entries_handler_reports_persisted_entries() -> Result<()> {
     let payload = next_payload(&sender).await?;
     match payload.transaction.data::()? {
         Message::SyncEntriesWithSuccessorReport(report) => {
-            assert_eq!(report.acks, vec![SyncedEntryAck::new(
-                placement_key,
-                stored_entry.clone()
-            )]);
+            assert_eq!(
+                report.acks,
+                vec![SyncedEntryAck::new(placement_key, stored_entry.clone())]
+            );
         }
         message => {
             return Err(Error::InvalidMessage(format!(
@@ -120,10 +120,10 @@ async fn persist_synced_entries_returns_acks_for_owned_entries() -> Result<()> {
 
     let acks = persist_synced_entries(&handler, &sync_msg).await?;
 
-    assert_eq!(acks, vec![SyncedEntryAck::new(
-        placement_key,
-        stored_entry.clone()
-    )]);
+    assert_eq!(
+        acks,
+        vec![SyncedEntryAck::new(placement_key, stored_entry.clone())]
+    );
     assert_eq!(
         receiver
             .dht()
diff --git a/crates/core/src/message/handlers/storage/tests/test_sync_ack.rs b/crates/core/src/message/handlers/storage/tests/test_sync_ack.rs
index 86308bdeb..3d666c75a 100644
--- a/crates/core/src/message/handlers/storage/tests/test_sync_ack.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_sync_ack.rs
@@ -222,6 +222,28 @@ async fn additive_repair_sync_cannot_create_pending_cleanup_capability() -> Resu
     Ok(())
 }
 
+#[tokio::test]
+async fn send_storage_sync_applies_local_destination_without_transport_send() -> Result<()> {
+    let node = prepare_node(SecretKey::random()).await;
+    let entry = Entry::new(Did::from(100u32), vec![], EntryKind::Data);
+    let placement_key = entry.did;
+    let stored_entry = entry.clone().try_into_storage_entry()?;
+    let sync_msg = SyncEntriesWithSuccessor {
+        purpose: StorageSyncPurpose::AdditiveRepair,
+        destination: StorageSyncDestination::PhysicalOwner(node.did()),
+        data: vec![PlacedEntry::new(placement_key, entry)],
+    };
+
+    node.swarm.transport.send_storage_sync(sync_msg).await?;
+
+    assert_eq!(
+        node.dht().storage.get(&placement_key.to_string()).await?,
+        Some(stored_entry)
+    );
+    assert_no_more_msg([&node]).await;
+    Ok(())
+}
+
 #[tokio::test]
 async fn sync_entries_report_handler_rejects_wrong_physical_receiver() -> Result<()> {
     let sender = prepare_node(SecretKey::random()).await;
diff --git a/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs b/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs
index 79f342029..666c20c6f 100644
--- a/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs
@@ -85,11 +85,14 @@ async fn sync_entries_handler_stores_entry_at_placement_key() -> Result<()> {
     )?;
 
     handler
-        .handle(&context, &SyncEntriesWithSuccessor {
-            purpose: StorageSyncPurpose::OwnershipHandoff,
-            destination: StorageSyncDestination::PhysicalOwner(node.did()),
-            data: vec![PlacedEntry::new(placement_key, entry.clone())],
-        })
+        .handle(
+            &context,
+            &SyncEntriesWithSuccessor {
+                purpose: StorageSyncPurpose::OwnershipHandoff,
+                destination: StorageSyncDestination::PhysicalOwner(node.did()),
+                data: vec![PlacedEntry::new(placement_key, entry.clone())],
+            },
+        )
         .await?;
 
     assert_eq!(
@@ -125,11 +128,14 @@ async fn sync_entries_handler_caps_inbound_entry_payloads() -> Result<()> {
     )?;
 
     handler
-        .handle(&context, &SyncEntriesWithSuccessor {
-            purpose: StorageSyncPurpose::OwnershipHandoff,
-            destination: StorageSyncDestination::PhysicalOwner(node.did()),
-            data: vec![PlacedEntry::new(placement_key, entry)],
-        })
+        .handle(
+            &context,
+            &SyncEntriesWithSuccessor {
+                purpose: StorageSyncPurpose::OwnershipHandoff,
+                destination: StorageSyncDestination::PhysicalOwner(node.did()),
+                data: vec![PlacedEntry::new(placement_key, entry)],
+            },
+        )
         .await?;
 
     let stored = node
@@ -175,14 +181,17 @@ async fn sync_entries_handler_rejects_non_affine_placement_before_writing() -> R
     )?;
 
     let result = handler
-        .handle(&context, &SyncEntriesWithSuccessor {
-            purpose: StorageSyncPurpose::OwnershipHandoff,
-            destination: StorageSyncDestination::PhysicalOwner(node.did()),
-            data: vec![
-                PlacedEntry::new(valid_placement, valid_entry),
-                PlacedEntry::new(invalid_placement, invalid_entry),
-            ],
-        })
+        .handle(
+            &context,
+            &SyncEntriesWithSuccessor {
+                purpose: StorageSyncPurpose::OwnershipHandoff,
+                destination: StorageSyncDestination::PhysicalOwner(node.did()),
+                data: vec![
+                    PlacedEntry::new(valid_placement, valid_entry),
+                    PlacedEntry::new(invalid_placement, invalid_entry),
+                ],
+            },
+        )
         .await;
 
     assert!(matches!(result, Err(Error::InvalidMessage(_))));
diff --git a/crates/core/src/message/payload.rs b/crates/core/src/message/payload.rs
index 179a016df..c8289ef10 100644
--- a/crates/core/src/message/payload.rs
+++ b/crates/core/src/message/payload.rs
@@ -39,7 +39,9 @@ pub fn encode_data_gzip(data: &Bytes, level: u8) -> Result {
 
 /// Serializes the given data using JSON and compresses it with gzip using the specified compression level.
 pub fn gzip_data(data: &T, level: u8) -> Result
-where T: Serialize {
+where
+    T: Serialize,
+{
     let json_bytes = serde_json::to_vec(data).map_err(|_| Error::SerializeToString)?;
     encode_data_gzip(&json_bytes.into(), level)
 }
@@ -56,7 +58,9 @@ pub fn decode_gzip_data(data: &Bytes) -> Result {
 
 /// From gzip data to deserialized
 pub fn from_gzipped_data(data: &Bytes) -> Result
-where T: DeserializeOwned {
+where
+    T: DeserializeOwned,
+{
     let data = decode_gzip_data(data)?;
     let m = serde_json::from_slice(&data).map_err(Error::Deserialize)?;
     Ok(m)
@@ -171,7 +175,9 @@ impl Transaction {
 
     /// Deserializes the data field into a `T` instance.
     pub fn data(&self) -> Result
-    where T: DeserializeOwned {
+    where
+        T: DeserializeOwned,
+    {
         bincode::deserialize(&self.data).map_err(Error::BincodeDeserialize)
     }
 }
@@ -369,7 +375,9 @@ pub trait PayloadSender {
 
     /// Send a message to a specified destination.
     async fn send_message(&self, msg: T, destination: Did) -> Result
-    where T: Serialize + Send {
+    where
+        T: Serialize + Send,
+    {
         let next_hop = self.infer_next_hop(destination, None)?;
         self.send_message_by_hop(msg, destination, next_hop).await
     }
@@ -391,14 +399,18 @@ pub trait PayloadSender {
 
     /// Send a direct message to a specified destination.
     async fn send_direct_message(&self, msg: T, destination: Did) -> Result
-    where T: Serialize + Send {
+    where
+        T: Serialize + Send,
+    {
         self.send_message_by_hop(msg, destination, destination)
             .await
     }
 
     /// Send a report message to a specified destination.
     async fn send_report_message(&self, payload: &MessagePayload, msg: T) -> Result<()>
-    where T: Serialize + Send {
+    where
+        T: Serialize + Send,
+    {
         let policy = payload.transaction.report_return;
         // Keep this send-boundary check even though transaction verification
         // enforces the same authorization when the request is received.
@@ -475,7 +487,9 @@ pub mod test {
     }
 
     pub fn new_payload(data: T, next_hop: Did) -> MessagePayload
-    where T: Serialize + DeserializeOwned {
+    where
+        T: Serialize + DeserializeOwned,
+    {
         let key = SecretKey::random();
         let destination = SecretKey::random().address().into();
         let session_sk = SessionSk::new_with_seckey(&key).unwrap();
diff --git a/crates/core/src/message/protocols/relay.rs b/crates/core/src/message/protocols/relay.rs
index 39e20b1bb..640cf51eb 100644
--- a/crates/core/src/message/protocols/relay.rs
+++ b/crates/core/src/message/protocols/relay.rs
@@ -194,7 +194,9 @@ impl MessageRelay {
 const INFINITE_LOOP_TOLERANCE: usize = 3;
 
 fn has_infinite_loop(path: &[T]) -> bool
-where T: PartialEq {
+where
+    T: PartialEq,
+{
     // Invariant: a relay loop is witnessed by a non-empty suffix period P such
     // that the final path segment is P repeated INFINITE_LOOP_TOLERANCE times.
     for period in 1..=path.len() / INFINITE_LOOP_TOLERANCE {
diff --git a/crates/core/src/message/types.rs b/crates/core/src/message/types.rs
index 545dfdf94..225b4287c 100644
--- a/crates/core/src/message/types.rs
+++ b/crates/core/src/message/types.rs
@@ -170,6 +170,29 @@ pub struct NotifyPredecessorReport {
     pub did: Did,
 }
 
+/// Overlay liveness probe sent to an admitted peer.
+#[derive(Debug, Deserialize, Serialize, Copy, Clone)]
+pub struct PeerLivenessProbe {
+    /// Sender-local timestamp for logging and correlation.
+    pub sent_at_ms: i64,
+}
+
+/// Overlay liveness report sent in response to [`PeerLivenessProbe`].
+#[derive(Debug, Deserialize, Serialize, Copy, Clone)]
+pub struct PeerLivenessReport {
+    /// Sender-local timestamp copied from the probe.
+    pub sent_at_ms: i64,
+}
+
+impl PeerLivenessProbe {
+    /// Build a response that proves the receiver processed this probe.
+    pub const fn resp(self) -> PeerLivenessReport {
+        PeerLivenessReport {
+            sent_at_ms: self.sent_at_ms,
+        }
+    }
+}
+
 /// The reason of query successor's TopoInfo
 #[derive(Debug, Deserialize, Serialize, Copy, Clone)]
 pub enum QueryFor {
@@ -380,6 +403,10 @@ pub enum Message {
     NotifyPredecessorSend(NotifyPredecessorSend),
     /// Response of NotifyPredecessorSend
     NotifyPredecessorReport(NotifyPredecessorReport),
+    /// Overlay liveness probe.
+    PeerLivenessProbe(PeerLivenessProbe),
+    /// Overlay liveness probe response.
+    PeerLivenessReport(PeerLivenessReport),
     /// Remote message for searching an entry.
     SearchEntry(SearchEntry),
     /// Response when entries are found.
diff --git a/crates/core/src/prelude.rs b/crates/core/src/prelude.rs
index 81f67276e..4e556bf47 100644
--- a/crates/core/src/prelude.rs
+++ b/crates/core/src/prelude.rs
@@ -9,6 +9,8 @@ pub use url;
 pub use uuid;
 
 pub use crate::dht::entry;
+pub use crate::lifecycle::StopSource;
+pub use crate::lifecycle::StopToken;
 pub use crate::measure::PeerMeasurement;
 pub use crate::message;
 pub use crate::message::ChordStorageInterface;
diff --git a/crates/core/src/storage/idb.rs b/crates/core/src/storage/idb.rs
index e38351a24..8b1391f07 100644
--- a/crates/core/src/storage/idb.rs
+++ b/crates/core/src/storage/idb.rs
@@ -155,7 +155,8 @@ impl IdbStorage {
 
 #[async_trait(?Send)]
 impl KvStorageInterface for IdbStorage
-where V: DeserializeOwned + Serialize + Sized
+where
+    V: DeserializeOwned + Serialize + Sized,
 {
     async fn get(&self, key: &str) -> Result> {
         let (tx, store) = self.get_tx_store(TransactionMode::ReadWrite)?;
diff --git a/crates/core/src/storage/memory.rs b/crates/core/src/storage/memory.rs
index e8fe78605..e1d6764d1 100644
--- a/crates/core/src/storage/memory.rs
+++ b/crates/core/src/storage/memory.rs
@@ -7,13 +7,15 @@ use crate::storage::KvStorageInterface;
 /// In-memory storage implementation backed by a concurrent map.
 #[derive(Debug, Default)]
 pub struct MemStorage
-where V: Clone
+where
+    V: Clone,
 {
     table: DashMap,
 }
 
 impl MemStorage
-where V: Clone
+where
+    V: Clone,
 {
     /// Create an empty memory storage table.
     pub fn new() -> Self {
@@ -26,7 +28,8 @@ where V: Clone
 #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
 impl KvStorageInterface for MemStorage
-where V: Clone + Send + Sync
+where
+    V: Clone + Send + Sync,
 {
     async fn get(&self, key: &str) -> Result> {
         Ok(self.table.get(&key.to_string()).map(|v| v.value().clone()))
diff --git a/crates/core/src/storage/sled.rs b/crates/core/src/storage/sled.rs
index 846b74204..6cedd9dea 100644
--- a/crates/core/src/storage/sled.rs
+++ b/crates/core/src/storage/sled.rs
@@ -24,7 +24,9 @@ impl SledStorage {
     /// * cap: max_size in bytes
     /// * path: db file location
     pub async fn new_with_cap_and_path
(cap: u32, path: P) -> Result
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let db = sled::Config::new()
             .path(path.as_ref())
             .mode(sled::Mode::HighThroughput)
@@ -41,7 +43,8 @@ impl SledStorage {
 
 #[async_trait]
 impl KvStorageInterface for SledStorage
-where V: Serialize + DeserializeOwned + Sync
+where
+    V: Serialize + DeserializeOwned + Sync,
 {
     async fn get(&self, key: &str) -> Result> {
         let v = self.db.get(key).map_err(Error::SledError)?;
diff --git a/crates/core/src/swarm/callback.rs b/crates/core/src/swarm/callback.rs
index 49da9c904..d52b78bae 100644
--- a/crates/core/src/swarm/callback.rs
+++ b/crates/core/src/swarm/callback.rs
@@ -191,6 +191,8 @@ impl InnerSwarmCallback {
             Message::NotifyPredecessorReport(ref msg) => {
                 self.message_handler.handle(payload, msg).await
             }
+            Message::PeerLivenessProbe(ref msg) => self.message_handler.handle(payload, msg).await,
+            Message::PeerLivenessReport(ref msg) => self.message_handler.handle(payload, msg).await,
             Message::SearchEntry(ref msg) => self.message_handler.handle(payload, msg).await,
             Message::FoundEntry(ref msg) => self.message_handler.handle(payload, msg).await,
             Message::SyncEntriesWithSuccessor(ref msg) => {
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index af6b60273..611f39cfd 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -8,7 +8,6 @@ use bytes::Bytes;
 use futures::future::FutureExt;
 use futures::pin_mut;
 use futures::select;
-use futures_timer::Delay;
 use rings_transport::connection_ref::ConnectionRef;
 #[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 pub use rings_transport::connections::DummyConnection as ConnectionOwner;
@@ -61,16 +60,24 @@ use crate::message::PayloadSender;
 use crate::session::SessionSk;
 use crate::swarm::callback::InnerSwarmCallback;
 use crate::utils::get_epoch_ms_i64;
+use crate::utils::sleep;
 
 mod delivery;
+mod liveness;
 mod pending;
 mod storage_lookup;
 mod storage_sync;
 
 use self::delivery::frame_chunk;
 use self::delivery::record_measurement;
+use self::delivery::send_data_with_timeout;
 use self::delivery::spawn_chunked_send;
 use self::delivery::spawn_delivery;
+use self::delivery::ChunkSendPermit;
+use self::liveness::PeerLivenessMap;
+pub(crate) use self::liveness::PEER_LIVENESS_IDLE_MS;
+#[cfg(all(test, feature = "dummy", not(target_family = "wasm")))]
+pub(crate) use self::liveness::PEER_LIVENESS_TIMEOUT_MS;
 pub(crate) use self::pending::PendingConnectionAttempt;
 use self::pending::PendingPeerPool;
 pub(crate) use self::pending::DEFAULT_PENDING_CONNECTION_CAPACITY;
@@ -82,6 +89,38 @@ pub(crate) use self::storage_lookup::STORAGE_LOOKUP_OBSERVATION_CAPACITY;
 
 const DATA_CHANNEL_OPEN_TIMEOUT: Duration = Duration::from_secs(8);
 
+fn message_kind(message: &Message) -> &'static str {
+    match message {
+        Message::ConnectNodeSend(_) => "ConnectNodeSend",
+        Message::ConnectNodeReport(_) => "ConnectNodeReport",
+        Message::FindSuccessorSend(_) => "FindSuccessorSend",
+        Message::FindSuccessorReport(_) => "FindSuccessorReport",
+        Message::NotifyPredecessorSend(_) => "NotifyPredecessorSend",
+        Message::NotifyPredecessorReport(_) => "NotifyPredecessorReport",
+        Message::PeerLivenessProbe(_) => "PeerLivenessProbe",
+        Message::PeerLivenessReport(_) => "PeerLivenessReport",
+        Message::SearchEntry(_) => "SearchEntry",
+        Message::FoundEntry(_) => "FoundEntry",
+        Message::OperateEntry(_) => "OperateEntry",
+        Message::SyncEntriesWithSuccessor(_) => "SyncEntriesWithSuccessor",
+        Message::SyncEntriesWithSuccessorReport(_) => "SyncEntriesWithSuccessorReport",
+        Message::CustomMessage(_) => "CustomMessage",
+        Message::E2eHandshakeRequest(_) => "E2eHandshakeRequest",
+        Message::E2eHandshakeResponse(_) => "E2eHandshakeResponse",
+        Message::E2eStreamFrame(_) => "E2eStreamFrame",
+        Message::QueryForTopoInfoSend(_) => "QueryForTopoInfoSend",
+        Message::QueryForTopoInfoReport(_) => "QueryForTopoInfoReport",
+        Message::Chunk(_) => "Chunk",
+    }
+}
+
+fn payload_message_kind(payload: &MessagePayload) -> &'static str {
+    match payload.transaction.data::() {
+        Ok(message) => message_kind(&message),
+        Err(_) => "Unknown",
+    }
+}
+
 pub struct SwarmTransport {
     pub(crate) network_id: u32,
     transport: Transport,
@@ -92,6 +131,7 @@ pub struct SwarmTransport {
     reassembly_limits: ReassemblyLimits,
     pending_peers: Mutex>,
     active_peers: Mutex>,
+    peer_liveness: Mutex,
     storage_lookup_observations: Mutex,
     pending_storage_sync_acks: Mutex,
     measured_disconnects: Mutex>,
@@ -176,6 +216,7 @@ impl SwarmTransport {
             reassembly_limits: settings.reassembly_limits,
             pending_peers: Mutex::new(PendingPeerPool::new()),
             active_peers: Mutex::new(BTreeMap::new()),
+            peer_liveness: Mutex::new(PeerLivenessMap::new()),
             storage_lookup_observations: Mutex::new(BTreeMap::new()),
             pending_storage_sync_acks: Mutex::new(BTreeMap::new()),
             measured_disconnects: Mutex::new(BTreeMap::new()),
@@ -222,6 +263,7 @@ impl SwarmTransport {
 
     /// Record that `peer` reached an open data channel.
     pub(crate) async fn record_peer_connected(&self, peer: Did) {
+        self.mark_peer_liveness_connected(peer);
         match self.measured_disconnects.lock() {
             Ok(mut measured) => {
                 measured.remove(&peer);
@@ -263,6 +305,7 @@ impl SwarmTransport {
 
     /// Record that a payload from `peer` was accepted and verified by the swarm.
     pub(crate) async fn record_peer_message_received(&self, peer: Did) {
+        self.mark_peer_liveness_inbound(peer);
         self.record_peer_measurement(peer, MeasureCounter::Received)
             .await;
     }
@@ -434,13 +477,42 @@ impl SwarmTransport {
                 return Err(e);
             }
         };
-        if let Err(error) = self
+        let sdp_len = offer_msg.sdp.len();
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = attempt.generation,
+            sdp_bytes = sdp_len,
+            "connection offer send start"
+        );
+        match self
             .send_message(Message::ConnectNodeSend(offer_msg), peer)
             .await
         {
-            self.abandon_pending_connection(attempt, "sending connection offer")
-                .await;
-            return Err(error);
+            Ok(tx_id) => {
+                tracing::info!(
+                    target: "rings_core::swarm::transport::handshake",
+                    local = %self.dht.did,
+                    peer = %peer,
+                    generation = attempt.generation,
+                    tx_id = %tx_id,
+                    "connection offer send complete"
+                );
+            }
+            Err(error) => {
+                tracing::warn!(
+                    target: "rings_core::swarm::transport::handshake",
+                    local = %self.dht.did,
+                    peer = %peer,
+                    generation = attempt.generation,
+                    error = ?error,
+                    "connection offer send failed"
+                );
+                self.abandon_pending_connection(attempt, "sending connection offer")
+                    .await;
+                return Err(error);
+            }
         }
         Ok(())
     }
@@ -475,7 +547,7 @@ impl SwarmTransport {
 
         let failure = {
             let wait_for_open = conn.connection.webrtc_wait_for_data_channel_open().fuse();
-            let timeout = Delay::new(wait_timeout).fuse();
+            let timeout = sleep(wait_timeout).fuse();
             pin_mut!(wait_for_open, timeout);
 
             select! {
@@ -546,14 +618,39 @@ impl SwarmTransport {
             return Err(Error::SwarmMissTransport(peer));
         };
 
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = attempt.generation,
+            state = ?conn.webrtc_connection_state(),
+            "connection offer create start"
+        );
         let offer = match conn.connection.webrtc_create_offer().await {
             Ok(offer) => offer,
             Err(error) => {
+                tracing::warn!(
+                    target: "rings_core::swarm::transport::handshake",
+                    local = %self.dht.did,
+                    peer = %peer,
+                    generation = attempt.generation,
+                    error = ?error,
+                    "connection offer create failed"
+                );
                 self.abandon_pending_connection(attempt, "creating connection offer")
                     .await;
                 return Err(Error::Transport(error));
             }
         };
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = attempt.generation,
+            sdp_bytes = offer.len(),
+            state = ?conn.webrtc_connection_state(),
+            "connection offer create complete"
+        );
         let offer_str = match serde_json::to_string(&offer) {
             Ok(offer) => offer,
             Err(_) => {
@@ -585,7 +682,7 @@ impl SwarmTransport {
             ));
         }
 
-        let offer = serde_json::from_str(&offer_msg.sdp).map_err(Error::Deserialize)?;
+        let offer: String = serde_json::from_str(&offer_msg.sdp).map_err(Error::Deserialize)?;
 
         self.expire_pending_connections().await?;
         if self.is_active_connection(peer) {
@@ -632,14 +729,40 @@ impl SwarmTransport {
             return Err(Error::SwarmMissTransport(peer));
         };
 
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = attempt.generation,
+            offer_sdp_bytes = offer.len(),
+            state = ?conn.webrtc_connection_state(),
+            "connection answer create start"
+        );
         let answer = match conn.connection.webrtc_answer_offer(offer).await {
             Ok(answer) => answer,
             Err(error) => {
+                tracing::warn!(
+                    target: "rings_core::swarm::transport::handshake",
+                    local = %self.dht.did,
+                    peer = %peer,
+                    generation = attempt.generation,
+                    error = ?error,
+                    "connection answer create failed"
+                );
                 self.abandon_pending_connection(attempt, "creating connection answer")
                     .await;
                 return Err(Error::Transport(error));
             }
         };
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = attempt.generation,
+            answer_sdp_bytes = answer.len(),
+            state = ?conn.webrtc_connection_state(),
+            "connection answer create complete"
+        );
         let answer_str = match serde_json::to_string(&answer) {
             Ok(answer) => answer,
             Err(_) => {
@@ -670,7 +793,7 @@ impl SwarmTransport {
             ));
         }
 
-        let answer = serde_json::from_str(&answer_msg.sdp).map_err(Error::Deserialize)?;
+        let answer: String = serde_json::from_str(&answer_msg.sdp).map_err(Error::Deserialize)?;
 
         if !self.is_pending_connection(peer)? {
             return Err(Error::SwarmMissTransport(peer));
@@ -679,14 +802,39 @@ impl SwarmTransport {
         let conn = self
             .get_raw_connection(peer)
             .ok_or(Error::SwarmMissTransport(peer))?;
+        let attempt = self.pending_attempt(peer)?;
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = ?attempt.map(|attempt| attempt.generation),
+            answer_sdp_bytes = answer.len(),
+            state = ?conn.webrtc_connection_state(),
+            "connection answer accept start"
+        );
         if let Err(error) = conn.connection.webrtc_accept_answer(answer).await {
             let attempt = self.pending_attempt(peer)?;
             if let Some(attempt) = attempt {
                 self.abandon_pending_connection(attempt, "accepting connection answer")
                     .await;
             }
+            tracing::warn!(
+                target: "rings_core::swarm::transport::handshake",
+                local = %self.dht.did,
+                peer = %peer,
+                error = ?error,
+                "connection answer accept failed"
+            );
             return Err(Error::Transport(error));
         }
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = ?attempt.map(|attempt| attempt.generation),
+            state = ?conn.webrtc_connection_state(),
+            "connection answer accept complete"
+        );
 
         Ok(())
     }
@@ -735,33 +883,52 @@ impl PayloadSender for SwarmTransport {
             return Err(Error::SwarmMissDidInTable(did));
         };
 
-        tracing::debug!(
-            "Try send {:?}, to node {:?}",
-            payload.clone(),
-            payload.relay.next_hop,
-        );
-
+        let message_kind = payload_message_kind(&payload);
+        let tx_id = payload.transaction.tx_id;
+        let destination = payload.transaction.destination;
+        let relay_destination = payload.relay.destination;
+        let next_hop = payload.relay.next_hop;
         let data = payload.to_bincode()?;
         if data.len() > TRANSPORT_MAX_SIZE {
-            tracing::error!("Message is too large: {:?}", payload);
+            tracing::error!(
+                local = %self.dht.did,
+                next_hop = %next_hop,
+                destination = %destination,
+                relay_destination = %relay_destination,
+                tx_id = %tx_id,
+                message_kind,
+                bytes = data.len(),
+                max_bytes = TRANSPORT_MAX_SIZE,
+                "message payload is too large"
+            );
             return Err(Error::MessageTooLarge(data.len()));
         }
 
         // The chunk-vs-whole decision is the pure `WireReserves::plan`, against this connection's
         // negotiated `max_message_size`; this block is only the effectful shell carrying it out.
-        // `None` means the peer's limit is too small to carry even one useful chunk — a real failure
-        // we surface (before sending anything) rather than fragmenting into a flood of near-empty
-        // chunks. Both arms are **fire-and-forget**: `send_message` returns once the bytes are
-        // accepted into the send buffer, not once they flush — a whole message hands its
-        // `DeliveryFuture` to the runtime, and a chunked message is driven by one bounded background
-        // task (one chunk in flight; see `run_chunked_send`), so a large payload never blocks the
-        // caller's path while keeping memory and the runtime task count bounded.
+        // `None` means the peer's limit is too small to carry even one useful chunk. Send admission is
+        // bounded because a WebRTC data-channel queue under backpressure can otherwise leave this
+        // future pending until the caller's outer timeout fires without a transport-level reason.
         let Some(plan) = WireReserves::PRODUCTION.plan(data.len(), conn.max_message_size()) else {
             self.record_peer_message_send_failed(did).await;
             return Err(Error::PeerMaxMessageSizeTooSmall(conn.max_message_size()));
         };
+        tracing::debug!(
+            local = %self.dht.did,
+            next_hop = %next_hop,
+            destination = %destination,
+            relay_destination = %relay_destination,
+            tx_id = %tx_id,
+            message_kind,
+            bytes = data.len(),
+            max_message_size = conn.max_message_size(),
+            framing = ?plan,
+            "send payload start"
+        );
+        let chunk_send_permit = ChunkSendPermit::for_payload(self.dht.clone(), did, &payload);
         match plan {
-            Framing::Whole => match conn.send_data(data).await {
+            Framing::Whole => match send_data_with_timeout(&conn, data, did, "whole_message").await
+            {
                 Ok(delivery) => spawn_delivery(delivery, did, self.measure.clone()),
                 Err(e) => {
                     self.record_peer_message_send_failed(did).await;
@@ -777,7 +944,7 @@ impl PayloadSender for SwarmTransport {
                 let mut chunks = ChunkList::stream(data, chunk_size);
                 if let Some(first) = chunks.next() {
                     let first = frame_chunk(&self.session_sk, did, first)?;
-                    match conn.send_data(first).await {
+                    match send_data_with_timeout(&conn, first, did, "chunked_first").await {
                         Ok(first_delivery) => {
                             spawn_chunked_send(
                                 conn,
@@ -785,6 +952,7 @@ impl PayloadSender for SwarmTransport {
                                 first_delivery,
                                 self.session_sk.clone(),
                                 did,
+                                chunk_send_permit,
                                 self.measure.clone(),
                             );
                         }
@@ -798,9 +966,13 @@ impl PayloadSender for SwarmTransport {
         }
 
         tracing::debug!(
-            "Sent {:?}, to node {:?}",
-            payload.clone(),
-            payload.relay.next_hop,
+            local = %self.dht.did,
+            next_hop = %next_hop,
+            destination = %destination,
+            relay_destination = %relay_destination,
+            tx_id = %tx_id,
+            message_kind,
+            "send payload accepted"
         );
 
         Ok(())
diff --git a/crates/core/src/swarm/transport/delivery.rs b/crates/core/src/swarm/transport/delivery.rs
index d2e436e57..7e7afadb1 100644
--- a/crates/core/src/swarm/transport/delivery.rs
+++ b/crates/core/src/swarm/transport/delivery.rs
@@ -1,15 +1,145 @@
+use std::sync::Arc;
+use std::time::Duration;
+
 use bytes::Bytes;
+use futures::future::FutureExt;
+use futures::pin_mut;
+use futures::select;
+use rings_transport::core::transport::WebrtcConnectionState;
 use rings_transport::delivery::DeliveryFuture;
 
 use super::SwarmConnection;
 use crate::chunk::Chunk;
 use crate::dht::Did;
+use crate::dht::PeerRing;
+use crate::dht::StorageSyncDestination;
+use crate::error::Error;
 use crate::error::Result;
 use crate::measure::MeasureCounter;
 use crate::measure::MeasureImpl;
 use crate::message::Message;
 use crate::message::MessagePayload;
 use crate::session::SessionSk;
+use crate::utils::sleep;
+
+#[cfg(test)]
+pub(super) const DATA_CHANNEL_SEND_ACCEPT_TIMEOUT: Duration = Duration::from_millis(50);
+#[cfg(not(test))]
+pub(super) const DATA_CHANNEL_SEND_ACCEPT_TIMEOUT: Duration = Duration::from_secs(5);
+
+#[cfg(test)]
+const CHUNK_SEND_PERMIT_POLL_INTERVAL: Duration = Duration::from_millis(10);
+#[cfg(not(test))]
+const CHUNK_SEND_PERMIT_POLL_INTERVAL: Duration = Duration::from_millis(250);
+
+#[derive(Debug)]
+enum ChunkSendCancelReason {
+    TerminalConnectionState(WebrtcConnectionState),
+    RouteNoLongerPermitted,
+    RouteCheckFailed(Error),
+}
+
+impl ChunkSendCancelReason {
+    const fn as_str(&self) -> &'static str {
+        match self {
+            Self::TerminalConnectionState(_) => "terminal_connection_state",
+            Self::RouteNoLongerPermitted => "route_no_longer_permitted",
+            Self::RouteCheckFailed(_) => "route_check_failed",
+        }
+    }
+
+    const fn terminal_state(&self) -> Option {
+        match self {
+            Self::TerminalConnectionState(state) => Some(*state),
+            Self::RouteNoLongerPermitted | Self::RouteCheckFailed(_) => None,
+        }
+    }
+
+    const fn route_check_error(&self) -> Option<&Error> {
+        match self {
+            Self::RouteCheckFailed(error) => Some(error),
+            Self::TerminalConnectionState(_) | Self::RouteNoLongerPermitted => None,
+        }
+    }
+
+    const fn records_peer_failure(&self) -> bool {
+        matches!(self, Self::TerminalConnectionState(_))
+    }
+}
+
+enum ChunkSendProgress {
+    Ready(T),
+    Cancelled(ChunkSendCancelReason),
+}
+
+#[derive(Clone)]
+pub(super) enum ChunkSendPermit {
+    Always,
+    StorageSyncRoute {
+        dht: Arc,
+        destination: StorageSyncDestination,
+        next_hop: Did,
+    },
+}
+
+impl ChunkSendPermit {
+    pub(super) fn for_payload(dht: Arc, next_hop: Did, payload: &MessagePayload) -> Self {
+        match payload.transaction.data() {
+            Ok(Message::SyncEntriesWithSuccessor(msg)) => Self::StorageSyncRoute {
+                dht,
+                destination: msg.destination,
+                next_hop,
+            },
+            Ok(_) => Self::Always,
+            Err(error) => {
+                tracing::debug!(
+                    target: "rings_core::transport::chunked_send",
+                    next_hop = %next_hop,
+                    error = ?error,
+                    "chunked send route permit fell back to connection-only mode"
+                );
+                Self::Always
+            }
+        }
+    }
+
+    fn check(&self) -> std::result::Result<(), ChunkSendCancelReason> {
+        match self {
+            Self::Always => Ok(()),
+            Self::StorageSyncRoute {
+                dht,
+                destination,
+                next_hop,
+            } => match dht.storage_sync_route_still_permits(*destination, *next_hop) {
+                Ok(true) => Ok(()),
+                Ok(false) => Err(ChunkSendCancelReason::RouteNoLongerPermitted),
+                Err(error) => Err(ChunkSendCancelReason::RouteCheckFailed(error)),
+            },
+        }
+    }
+}
+
+pub(super) async fn send_data_with_timeout(
+    conn: &SwarmConnection,
+    data: Bytes,
+    did: Did,
+    context: &'static str,
+) -> Result {
+    let bytes = data.len();
+    let send = conn.send_data(data).fuse();
+    let timeout = sleep(DATA_CHANNEL_SEND_ACCEPT_TIMEOUT).fuse();
+    pin_mut!(send, timeout);
+
+    select! {
+        result = send => result,
+        _ = timeout => Err(Error::DataChannelSendQueueTimeout {
+            peer: did,
+            timeout_ms: DATA_CHANNEL_SEND_ACCEPT_TIMEOUT.as_millis(),
+            bytes,
+            context,
+        }),
+    }
+}
 
 pub(super) async fn record_measurement(
     measure: Option,
@@ -67,6 +197,109 @@ type ChunkTail = Box + Send>;
 #[cfg(all(feature = "wasm", target_family = "wasm"))]
 type ChunkTail = Box>;
 
+fn chunk_send_cancel_reason(
+    conn: &SwarmConnection,
+    permit: &ChunkSendPermit,
+) -> Option {
+    let state = conn.webrtc_connection_state();
+    if matches!(
+        state,
+        WebrtcConnectionState::Failed | WebrtcConnectionState::Closed
+    ) {
+        return Some(ChunkSendCancelReason::TerminalConnectionState(state));
+    }
+
+    permit.check().err()
+}
+
+fn log_chunk_send_cancel(did: Did, phase: &'static str, reason: &ChunkSendCancelReason) {
+    tracing::warn!(
+        target: "rings_core::transport::chunked_send",
+        peer = %did,
+        phase,
+        reason = reason.as_str(),
+        terminal_state = ?reason.terminal_state(),
+        route_check_error = ?reason.route_check_error(),
+        records_peer_failure = reason.records_peer_failure(),
+        "chunked send cancelled"
+    );
+}
+
+async fn record_cancel_measurement(
+    measure: Option,
+    did: Did,
+    reason: &ChunkSendCancelReason,
+) {
+    if reason.records_peer_failure() {
+        record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+    }
+}
+
+async fn await_delivery_or_cancel(
+    delivery: DeliveryFuture,
+    conn: &SwarmConnection,
+    permit: &ChunkSendPermit,
+    did: Did,
+    phase: &'static str,
+) -> ChunkSendProgress> {
+    let delivery = delivery.fuse();
+    pin_mut!(delivery);
+
+    loop {
+        if let Some(reason) = chunk_send_cancel_reason(conn, permit) {
+            log_chunk_send_cancel(did, phase, &reason);
+            return ChunkSendProgress::Cancelled(reason);
+        }
+
+        let poll = sleep(CHUNK_SEND_PERMIT_POLL_INTERVAL).fuse();
+        pin_mut!(poll);
+        select! {
+            result = delivery => {
+                if result.is_err() {
+                    if let Some(reason) = chunk_send_cancel_reason(conn, permit) {
+                        log_chunk_send_cancel(did, phase, &reason);
+                        return ChunkSendProgress::Cancelled(reason);
+                    }
+                }
+                return ChunkSendProgress::Ready(result.map_err(Error::Transport));
+            },
+            _ = poll => {}
+        }
+    }
+}
+
+async fn send_chunk_or_cancel(
+    conn: &SwarmConnection,
+    bytes: Bytes,
+    permit: &ChunkSendPermit,
+    did: Did,
+) -> ChunkSendProgress> {
+    let send = send_data_with_timeout(conn, bytes, did, "chunked_tail").fuse();
+    pin_mut!(send);
+
+    loop {
+        if let Some(reason) = chunk_send_cancel_reason(conn, permit) {
+            log_chunk_send_cancel(did, "send_chunk", &reason);
+            return ChunkSendProgress::Cancelled(reason);
+        }
+
+        let poll = sleep(CHUNK_SEND_PERMIT_POLL_INTERVAL).fuse();
+        pin_mut!(poll);
+        select! {
+            result = send => {
+                if result.is_err() {
+                    if let Some(reason) = chunk_send_cancel_reason(conn, permit) {
+                        log_chunk_send_cancel(did, "send_chunk", &reason);
+                        return ChunkSendProgress::Cancelled(reason);
+                    }
+                }
+                return ChunkSendProgress::Ready(result);
+            },
+            _ = poll => {}
+        }
+    }
+}
+
 /// Drive the *tail* of a chunked send: the first chunk has already been accepted by the caller
 /// (`do_send_payload`), so wait for it to flush (backpressure), then frame, send, and await each
 /// remaining chunk in turn. One chunk is in flight at a time and no per-chunk task is spawned. A
@@ -79,34 +312,53 @@ async fn run_chunked_send(
     first_delivery: DeliveryFuture,
     session_sk: SessionSk,
     did: Did,
+    permit: ChunkSendPermit,
     measure: Option,
 ) {
-    if let Err(e) = first_delivery.await {
-        tracing::warn!("Chunked send to {did} stopped before the first chunk flushed: {e}");
-        record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-        return;
+    match await_delivery_or_cancel(first_delivery, &conn, &permit, did, "first_delivery").await {
+        ChunkSendProgress::Ready(Ok(())) => {}
+        ChunkSendProgress::Ready(Err(e)) => {
+            tracing::warn!("Chunked send to {did} stopped before the first chunk flushed: {e}");
+            record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+            return;
+        }
+        ChunkSendProgress::Cancelled(reason) => {
+            record_cancel_measurement(measure, did, &reason).await;
+            return;
+        }
     }
     for chunk in tail {
         let bytes = match frame_chunk(&session_sk, did, chunk) {
             Ok(bytes) => bytes,
             Err(e) => {
                 tracing::warn!("Chunked send to {did} aborted while framing a chunk: {e}");
+                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
                 return;
             }
         };
-        match conn.send_data(bytes).await {
-            Ok(delivery) => {
-                if let Err(e) = delivery.await {
-                    tracing::warn!("Chunked send to {did} stopped before flush: {e}");
-                    record_measurement(measure, did, MeasureCounter::FailedToSend).await;
-                    return;
-                }
-            }
-            Err(e) => {
+        let delivery = match send_chunk_or_cancel(&conn, bytes, &permit, did).await {
+            ChunkSendProgress::Ready(Ok(delivery)) => delivery,
+            ChunkSendProgress::Ready(Err(e)) => {
                 tracing::warn!("Chunked send to {did} stopped: {e}");
                 record_measurement(measure, did, MeasureCounter::FailedToSend).await;
                 return;
             }
+            ChunkSendProgress::Cancelled(reason) => {
+                record_cancel_measurement(measure, did, &reason).await;
+                return;
+            }
+        };
+        match await_delivery_or_cancel(delivery, &conn, &permit, did, "chunk_delivery").await {
+            ChunkSendProgress::Ready(Ok(())) => {}
+            ChunkSendProgress::Ready(Err(e)) => {
+                tracing::warn!("Chunked send to {did} stopped before flush: {e}");
+                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+                return;
+            }
+            ChunkSendProgress::Cancelled(reason) => {
+                record_cancel_measurement(measure, did, &reason).await;
+                return;
+            }
         }
     }
     record_measurement(measure, did, MeasureCounter::Sent).await;
@@ -121,6 +373,7 @@ pub(super) fn spawn_chunked_send(
     first_delivery: DeliveryFuture,
     session_sk: SessionSk,
     did: Did,
+    permit: ChunkSendPermit,
     measure: Option,
 ) {
     wasm_bindgen_futures::spawn_local(run_chunked_send(
@@ -129,6 +382,7 @@ pub(super) fn spawn_chunked_send(
         first_delivery,
         session_sk,
         did,
+        permit,
         measure,
     ));
 }
@@ -142,6 +396,7 @@ pub(super) fn spawn_chunked_send(
     first_delivery: DeliveryFuture,
     session_sk: SessionSk,
     did: Did,
+    permit: ChunkSendPermit,
     measure: Option,
 ) {
     tokio::spawn(run_chunked_send(
@@ -150,6 +405,7 @@ pub(super) fn spawn_chunked_send(
         first_delivery,
         session_sk,
         did,
+        permit,
         measure,
     ));
 }
diff --git a/crates/core/src/swarm/transport/liveness.rs b/crates/core/src/swarm/transport/liveness.rs
new file mode 100644
index 000000000..63a872eda
--- /dev/null
+++ b/crates/core/src/swarm/transport/liveness.rs
@@ -0,0 +1,272 @@
+use std::collections::BTreeMap;
+use std::sync::MutexGuard;
+
+use crate::dht::Did;
+use crate::error::Error;
+use crate::error::Result;
+use crate::swarm::transport::SwarmTransport;
+use crate::utils::get_epoch_ms_i64;
+
+/// Idle interval after which an admitted peer needs an overlay liveness probe.
+pub(crate) const PEER_LIVENESS_IDLE_MS: i64 = 15_000;
+/// Maximum age of an unanswered liveness probe before the peer is evicted.
+pub(crate) const PEER_LIVENESS_TIMEOUT_MS: i64 = 45_000;
+
+#[derive(Clone, Copy, Debug)]
+struct PeerLiveness {
+    generation: u64,
+    connected_at_ms: i64,
+    last_inbound_ms: i64,
+    last_probe_ms: Option,
+    unanswered_probe_since_ms: Option,
+}
+
+impl PeerLiveness {
+    fn new(generation: u64, now_ms: i64) -> Self {
+        Self {
+            generation,
+            connected_at_ms: now_ms,
+            last_inbound_ms: now_ms,
+            last_probe_ms: None,
+            unanswered_probe_since_ms: None,
+        }
+    }
+
+    fn mark_inbound(&mut self, now_ms: i64) {
+        self.last_inbound_ms = now_ms;
+        self.unanswered_probe_since_ms = None;
+    }
+
+    fn should_probe(&self, now_ms: i64) -> bool {
+        now_ms.saturating_sub(self.last_inbound_ms) >= PEER_LIVENESS_IDLE_MS
+            && self
+                .last_probe_ms
+                .map(|last_probe_ms| now_ms.saturating_sub(last_probe_ms) >= PEER_LIVENESS_IDLE_MS)
+                .unwrap_or(true)
+    }
+
+    fn mark_probe_sent(&mut self, now_ms: i64) {
+        self.last_probe_ms = Some(now_ms);
+        self.unanswered_probe_since_ms.get_or_insert(now_ms);
+    }
+
+    fn expiry(&self, now_ms: i64) -> Option {
+        let unanswered_since_ms = self.unanswered_probe_since_ms?;
+        let unanswered_for_ms = now_ms.saturating_sub(unanswered_since_ms);
+        (unanswered_for_ms >= PEER_LIVENESS_TIMEOUT_MS).then_some(PeerLivenessExpiry {
+            unanswered_for_ms,
+            timeout_ms: PEER_LIVENESS_TIMEOUT_MS,
+        })
+    }
+
+    fn connected_for_ms(&self, now_ms: i64) -> i64 {
+        now_ms.saturating_sub(self.connected_at_ms)
+    }
+}
+
+/// Bounded-by-active-peers overlay liveness state.
+///
+/// Invariant: for every `(did, state)` in this map, `state.generation` is the
+/// active transport generation that admitted `did`. A new connection generation
+/// resets liveness, so late observations from an old connection cannot prove the
+/// new connection live.
+pub(super) struct PeerLivenessMap {
+    peers: BTreeMap,
+}
+
+impl PeerLivenessMap {
+    pub(super) fn new() -> Self {
+        Self {
+            peers: BTreeMap::new(),
+        }
+    }
+
+    fn mark_connected(&mut self, peer: Did, generation: u64, now_ms: i64) {
+        self.peers
+            .insert(peer, PeerLiveness::new(generation, now_ms));
+    }
+
+    fn mark_inbound(&mut self, peer: Did, generation: u64, now_ms: i64) {
+        match self.peers.get_mut(&peer) {
+            Some(liveness) if liveness.generation == generation => {
+                liveness.mark_inbound(now_ms);
+            }
+            _ => self.mark_connected(peer, generation, now_ms),
+        }
+    }
+
+    fn remove(&mut self, peer: Did) {
+        self.peers.remove(&peer);
+    }
+
+    fn retain_active(&mut self, active: &BTreeMap) {
+        self.peers.retain(|peer, liveness| {
+            active
+                .get(peer)
+                .is_some_and(|generation| *generation == liveness.generation)
+        });
+    }
+
+    fn probe_candidates(&mut self, active: &BTreeMap, now_ms: i64) -> Vec {
+        self.retain_active(active);
+        for (peer, generation) in active {
+            self.peers
+                .entry(*peer)
+                .or_insert_with(|| PeerLiveness::new(*generation, now_ms));
+        }
+
+        self.peers
+            .iter()
+            .filter_map(|(peer, liveness)| liveness.should_probe(now_ms).then_some(*peer))
+            .collect()
+    }
+
+    fn mark_probe_sent(&mut self, peer: Did, generation: u64, now_ms: i64) {
+        match self.peers.get_mut(&peer) {
+            Some(liveness) if liveness.generation == generation => {
+                liveness.mark_probe_sent(now_ms);
+            }
+            _ => {
+                let mut liveness = PeerLiveness::new(generation, now_ms);
+                liveness.mark_probe_sent(now_ms);
+                self.peers.insert(peer, liveness);
+            }
+        }
+    }
+
+    fn expiry(&self, peer: Did, generation: u64, now_ms: i64) -> Option {
+        let liveness = self.peers.get(&peer)?;
+        (liveness.generation == generation)
+            .then(|| liveness.expiry(now_ms))
+            .flatten()
+    }
+
+    fn connected_for_ms(&self, peer: Did, generation: u64, now_ms: i64) -> Option {
+        let liveness = self.peers.get(&peer)?;
+        (liveness.generation == generation).then(|| liveness.connected_for_ms(now_ms))
+    }
+
+    #[cfg(all(test, feature = "dummy", not(target_family = "wasm")))]
+    fn force_probe_sent_at(&mut self, peer: Did, generation: u64, sent_at_ms: i64) {
+        let mut liveness = PeerLiveness::new(generation, sent_at_ms);
+        liveness.mark_probe_sent(sent_at_ms);
+        self.peers.insert(peer, liveness);
+    }
+}
+
+/// Peer liveness expiry evidence.
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct PeerLivenessExpiry {
+    /// How long the probe has been unanswered.
+    pub(crate) unanswered_for_ms: i64,
+    /// Configured timeout for unanswered probes.
+    pub(crate) timeout_ms: i64,
+}
+
+impl SwarmTransport {
+    fn peer_liveness(&self) -> Result> {
+        self.peer_liveness
+            .lock()
+            .map_err(|_| Error::SwarmConnectionLifecycleLock)
+    }
+
+    fn active_generations(&self) -> Result> {
+        Ok(self.active_peers()?.clone())
+    }
+
+    fn active_generation(&self, peer: Did) -> Result> {
+        Ok(self.active_peers()?.get(&peer).copied())
+    }
+
+    pub(crate) fn mark_peer_liveness_connected(&self, peer: Did) {
+        let now_ms = get_epoch_ms_i64();
+        let generation = match self.active_generation(peer) {
+            Ok(Some(generation)) => generation,
+            Ok(None) => return,
+            Err(error) => {
+                tracing::warn!(
+                    "failed to read active generation for connected peer {peer}: {error}"
+                );
+                return;
+            }
+        };
+        if let Err(error) = self
+            .peer_liveness()
+            .map(|mut liveness| liveness.mark_connected(peer, generation, now_ms))
+        {
+            tracing::warn!("failed to mark liveness for connected peer {peer}: {error}");
+        }
+    }
+
+    pub(crate) fn mark_peer_liveness_inbound(&self, peer: Did) {
+        let now_ms = get_epoch_ms_i64();
+        let generation = match self.active_generation(peer) {
+            Ok(Some(generation)) => generation,
+            Ok(None) => return,
+            Err(error) => {
+                tracing::warn!("failed to read active generation for inbound peer {peer}: {error}");
+                return;
+            }
+        };
+        if let Err(error) = self
+            .peer_liveness()
+            .map(|mut liveness| liveness.mark_inbound(peer, generation, now_ms))
+        {
+            tracing::warn!("failed to mark liveness for inbound peer {peer}: {error}");
+        }
+    }
+
+    pub(crate) fn remove_peer_liveness(&self, peer: Did) -> Result<()> {
+        self.peer_liveness()?.remove(peer);
+        Ok(())
+    }
+
+    pub(crate) fn liveness_probe_candidates(&self, now_ms: i64) -> Result> {
+        let active = self.active_generations()?;
+        Ok(self.peer_liveness()?.probe_candidates(&active, now_ms))
+    }
+
+    pub(crate) fn record_peer_liveness_probe_sent(&self, peer: Did, now_ms: i64) -> Result<()> {
+        let Some(generation) = self.active_generation(peer)? else {
+            return Ok(());
+        };
+        self.peer_liveness()?
+            .mark_probe_sent(peer, generation, now_ms);
+        Ok(())
+    }
+
+    pub(crate) fn peer_liveness_expiry(
+        &self,
+        peer: Did,
+        now_ms: i64,
+    ) -> Result> {
+        let Some(generation) = self.active_generation(peer)? else {
+            return Ok(None);
+        };
+        Ok(self.peer_liveness()?.expiry(peer, generation, now_ms))
+    }
+
+    /// Return how long an admitted peer has owned its current active generation.
+    pub(crate) fn peer_connected_for_ms(&self, peer: Did, now_ms: i64) -> Result> {
+        let Some(generation) = self.active_generation(peer)? else {
+            return Ok(None);
+        };
+        Ok(self
+            .peer_liveness()?
+            .connected_for_ms(peer, generation, now_ms))
+    }
+
+    #[cfg(all(test, feature = "dummy", not(target_family = "wasm")))]
+    pub(crate) fn force_peer_liveness_probe_sent_at(
+        &self,
+        peer: Did,
+        sent_at_ms: i64,
+    ) -> Result<()> {
+        let Some(generation) = self.active_generation(peer)? else {
+            return Ok(());
+        };
+        self.peer_liveness()?
+            .force_probe_sent_at(peer, generation, sent_at_ms);
+        Ok(())
+    }
+}
diff --git a/crates/core/src/swarm/transport/pending.rs b/crates/core/src/swarm/transport/pending.rs
index 8ab1ff24f..787242d3e 100644
--- a/crates/core/src/swarm/transport/pending.rs
+++ b/crates/core/src/swarm/transport/pending.rs
@@ -39,6 +39,12 @@ pub(super) struct PendingPeer {
     admitted_at_ms: i64,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) struct ExpiredPendingPeer {
+    pub(super) attempt: PendingConnectionAttempt,
+    pub(super) age_ms: i64,
+}
+
 /// Bounded, non-routable handshakes owned by the swarm lifecycle.
 ///
 /// The pool deliberately has no DHT reference: a peer is visible to Chord
@@ -96,20 +102,23 @@ impl PendingPeerPool {
         true
     }
 
-    pub(super) fn expire(&mut self, now_ms: i64) -> Vec {
+    pub(super) fn expire(&mut self, now_ms: i64) -> Vec {
         let expired = self
             .peers
             .iter()
             .filter_map(|(peer, pending)| {
-                (now_ms.saturating_sub(pending.admitted_at_ms) >= PENDING_CONNECTION_TIMEOUT_MS)
-                    .then_some(PendingConnectionAttempt {
+                let age_ms = now_ms.saturating_sub(pending.admitted_at_ms);
+                (age_ms >= PENDING_CONNECTION_TIMEOUT_MS).then_some(ExpiredPendingPeer {
+                    attempt: PendingConnectionAttempt {
                         peer: *peer,
                         generation: pending.generation,
-                    })
+                    },
+                    age_ms,
+                })
             })
             .collect::>();
-        for attempt in &expired {
-            self.peers.remove(&attempt.peer);
+        for expired in &expired {
+            self.peers.remove(&expired.attempt.peer);
         }
         expired
     }
@@ -200,7 +209,16 @@ impl SwarmTransport {
         if self.is_admitted_connection(peer) {
             return Err(Error::AlreadyConnected);
         }
-        self.pending_peers()?.reserve(peer, get_epoch_ms_i64())
+        let attempt = self.pending_peers()?.reserve(peer, get_epoch_ms_i64())?;
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %peer,
+            generation = attempt.generation,
+            pending_timeout_ms = PENDING_CONNECTION_TIMEOUT_MS,
+            "pending connection reserved"
+        );
+        Ok(attempt)
     }
 
     pub(super) fn pending_attempt(&self, peer: Did) -> Result> {
@@ -225,6 +243,13 @@ impl SwarmTransport {
         drop(pending);
         self.active_peers()?
             .insert(attempt.peer, attempt.generation);
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %attempt.peer,
+            generation = attempt.generation,
+            "pending connection promoted"
+        );
         Ok(true)
     }
 
@@ -236,7 +261,11 @@ impl SwarmTransport {
     }
 
     pub(super) fn retire_active_connection(&self, peer: Did) -> Result {
-        Ok(self.active_peers()?.remove(&peer).is_some())
+        let removed = self.active_peers()?.remove(&peer).is_some();
+        if removed {
+            self.remove_peer_liveness(peer)?;
+        }
+        Ok(removed)
     }
 
     /// Cancel a current pending handshake and release its non-routable transport object.
@@ -247,6 +276,13 @@ impl SwarmTransport {
         if !self.retire_pending_connection(attempt)? {
             return Ok(false);
         }
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %attempt.peer,
+            generation = attempt.generation,
+            "pending connection cancelled"
+        );
         self.transport
             .close_connection(&attempt.peer.to_string())
             .await
@@ -273,8 +309,21 @@ impl SwarmTransport {
     /// transport object; it deliberately performs no topology mutation.
     pub(crate) async fn expire_pending_connections(&self) -> Result<()> {
         let expired = self.pending_peers()?.expire(get_epoch_ms_i64());
-        for attempt in expired {
-            tracing::warn!("pending connection to {} timed out", attempt.peer);
+        for expired in expired {
+            let attempt = expired.attempt;
+            let state = self
+                .get_raw_connection(attempt.peer)
+                .map(|conn| conn.webrtc_connection_state());
+            tracing::warn!(
+                target: "rings_core::swarm::transport::handshake",
+                local = %self.dht.did,
+                peer = %attempt.peer,
+                generation = attempt.generation,
+                age_ms = expired.age_ms,
+                timeout_ms = PENDING_CONNECTION_TIMEOUT_MS,
+                state = ?state,
+                "pending connection timed out before data-channel open"
+            );
             self.transport
                 .close_connection(&attempt.peer.to_string())
                 .await
@@ -290,6 +339,13 @@ impl SwarmTransport {
         callback: InnerSwarmCallback,
     ) -> Result<()> {
         let cid = attempt.peer.to_string();
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %attempt.peer,
+            generation = attempt.generation,
+            "creating pending transport connection"
+        );
         if let Err(error) = self
             .transport
             .new_connection(&cid, Box::new(callback))
@@ -298,6 +354,13 @@ impl SwarmTransport {
             let _ = self.retire_pending_connection(attempt);
             return Err(Error::Transport(error));
         }
+        tracing::info!(
+            target: "rings_core::swarm::transport::handshake",
+            local = %self.dht.did,
+            peer = %attempt.peer,
+            generation = attempt.generation,
+            "pending transport connection created"
+        );
         Ok(())
     }
 
diff --git a/crates/core/src/swarm/transport/storage_lookup.rs b/crates/core/src/swarm/transport/storage_lookup.rs
index 960c41b86..5f413eb35 100644
--- a/crates/core/src/swarm/transport/storage_lookup.rs
+++ b/crates/core/src/swarm/transport/storage_lookup.rs
@@ -105,10 +105,13 @@ impl SwarmTransport {
         let now = storage_lookup_observation_now_ms();
         evict_storage_lookup_observations(&mut observations, now);
         reserve_storage_lookup_observation_slot(&mut observations);
-        observations.insert(key, StorageLookupObservation {
-            observed_at_ms: now,
-            misses: BTreeSet::new(),
-        });
+        observations.insert(
+            key,
+            StorageLookupObservation {
+                observed_at_ms: now,
+                misses: BTreeSet::new(),
+            },
+        );
         Ok(())
     }
 
diff --git a/crates/core/src/swarm/transport/storage_sync.rs b/crates/core/src/swarm/transport/storage_sync.rs
index fd50bf10a..9d18c872f 100644
--- a/crates/core/src/swarm/transport/storage_sync.rs
+++ b/crates/core/src/swarm/transport/storage_sync.rs
@@ -4,6 +4,8 @@ use super::SwarmTransport;
 use crate::dht::entry::PlacedEntry;
 use crate::dht::entry::SyncedEntryAck;
 use crate::dht::Did;
+use crate::dht::PeerRingAction;
+use crate::dht::PeerRingRemoteAction;
 use crate::dht::StorageSyncDestination;
 use crate::dht::StorageSyncPurpose;
 use crate::error::Error;
@@ -86,6 +88,16 @@ fn validate_report_acks(
     Ok(())
 }
 
+fn storage_sync_destination_accepts_placement(
+    destination: StorageSyncDestination,
+    placement: Did,
+) -> bool {
+    match destination {
+        StorageSyncDestination::PhysicalOwner(_) => true,
+        StorageSyncDestination::PlacementKey(key) => key == placement,
+    }
+}
+
 // Post: pending.len() < STORAGE_SYNC_ACK_CAPACITY.
 // Preservation: evicting an old pending capability before inserting a new one
 // can only make that old report fail validation; it cannot make an unproven
@@ -104,6 +116,26 @@ fn evict_storage_sync_acks(pending: &mut StorageSyncAckMap) {
 }
 
 impl SwarmTransport {
+    async fn apply_local_storage_sync(&self, msg: &SyncEntriesWithSuccessor) -> Result<()> {
+        for placed in msg.data.iter() {
+            if !storage_sync_destination_accepts_placement(msg.destination, placed.key) {
+                continue;
+            }
+
+            match self.dht.find_storage_owner(placed.key)? {
+                PeerRingAction::Some(_) => {
+                    placed.validate_placement(self.storage_redundancy())?;
+                    self.dht
+                        .join_storage_entry(placed.key, placed.entry.clone())
+                        .await?;
+                }
+                PeerRingAction::RemoteAction(_, PeerRingRemoteAction::FindSuccessor(_)) => {}
+                action => return Err(Error::unexpected_peer_ring_action(action)),
+            }
+        }
+        Ok(())
+    }
+
     /// Record the exact ack capability created by an outbound storage-sync payload.
     ///
     /// Pre: `tx_id` is the transaction id of the payload whose message data is
@@ -210,15 +242,14 @@ impl SwarmTransport {
         msg: SyncEntriesWithSuccessor,
     ) -> Result {
         let destination = msg.destination.did();
-        let next_hop = self
-            .dht
-            .next_hop_for_storage_sync(msg.destination)?
-            .ok_or_else(|| {
-                Error::InvalidMessage(
-                    "storage sync destination resolves to local branch at send boundary"
-                        .to_string(),
-                )
-            })?;
+        let Some(next_hop) = self.dht.next_hop_for_storage_sync(msg.destination)? else {
+            self.apply_local_storage_sync(&msg).await?;
+            return Ok(uuid::Uuid::new_v4());
+        };
+        if next_hop == self.dht.did {
+            self.apply_local_storage_sync(&msg).await?;
+            return Ok(uuid::Uuid::new_v4());
+        }
         let payload = MessagePayload::new_send(
             Message::SyncEntriesWithSuccessor(msg.clone()),
             self.session_sk(),
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index 98a9c1bc7..4354e024f 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -202,7 +202,9 @@ fn pending_peer_pool_expires_unopened_handshakes() -> Result<()> {
     let attempt = pool.reserve(peer, now)?;
 
     let expired = pool.expire(now + PENDING_CONNECTION_TIMEOUT_MS);
-    assert_eq!(expired, vec![attempt]);
+    assert_eq!(expired.len(), 1);
+    assert_eq!(expired[0].attempt, attempt);
+    assert_eq!(expired[0].age_ms, PENDING_CONNECTION_TIMEOUT_MS);
     assert_eq!(pool.len(), 0);
     Ok(())
 }
diff --git a/crates/core/src/tests/default/test_chunk_e2e.rs b/crates/core/src/tests/default/test_chunk_e2e.rs
index 96acccf2e..8f830ebc3 100644
--- a/crates/core/src/tests/default/test_chunk_e2e.rs
+++ b/crates/core/src/tests/default/test_chunk_e2e.rs
@@ -3,15 +3,156 @@
 //! receiver reassembles the original message — exercising stream → wrap → send → reassemble, not
 //! just the pure `WireReserves::plan` decision.
 
+use std::sync::Arc;
+use std::sync::Mutex;
+
+use async_trait::async_trait;
 use rings_transport::connections::dummy_controlled;
 use rings_transport::core::transport::WebrtcConnectionState;
+use tokio::time::sleep;
+use tokio::time::Duration;
 
+use crate::dht::entry::Entry;
+use crate::dht::entry::EntryKind;
+use crate::dht::entry::PlacedEntry;
+use crate::dht::StorageSyncDestination;
+use crate::dht::StorageSyncPurpose;
 use crate::ecc::SecretKey;
+use crate::error::Result;
+use crate::measure::BehaviourJudgement;
+use crate::measure::Measure;
+use crate::measure::MeasureCounter;
+use crate::measure::MeasureImpl;
+use crate::measure::PeerQuality;
 use crate::message::Message;
+use crate::message::SyncEntriesWithSuccessor;
+use crate::session::SessionSk;
+use crate::storage::MemStorage;
+use crate::swarm::SwarmBuilder;
 use crate::tests::default::prepare_node;
 use crate::tests::default::wait_for_connection_state;
+use crate::tests::default::wait_for_msgs;
+use crate::tests::default::wait_for_successor;
+use crate::tests::default::Node;
 use crate::tests::manually_establish_connection;
 
+struct PendingSendGuard;
+
+impl PendingSendGuard {
+    fn new() -> Self {
+        dummy_controlled::set_send_message_pending(true);
+        Self
+    }
+}
+
+impl Drop for PendingSendGuard {
+    fn drop(&mut self) {
+        dummy_controlled::set_send_message_pending(false);
+    }
+}
+
+struct PendingAfterSentCountGuard;
+
+impl PendingAfterSentCountGuard {
+    fn new(threshold: usize) -> Self {
+        dummy_controlled::set_send_message_pending_after_sent_count(Some(threshold));
+        Self
+    }
+}
+
+impl Drop for PendingAfterSentCountGuard {
+    fn drop(&mut self) {
+        dummy_controlled::set_send_message_pending_after_sent_count(None);
+    }
+}
+
+struct MaxMessageSizeGuard;
+
+impl MaxMessageSizeGuard {
+    fn new(size: usize) -> Self {
+        dummy_controlled::set_max_message_size(size);
+        Self
+    }
+}
+
+impl Drop for MaxMessageSizeGuard {
+    fn drop(&mut self) {
+        dummy_controlled::set_max_message_size(0);
+    }
+}
+
+#[derive(Default)]
+struct CountingMeasure {
+    counters: Mutex>,
+}
+
+impl CountingMeasure {
+    fn count(&self, did: crate::dht::Did, counter: MeasureCounter) -> u64 {
+        match self.counters.lock() {
+            Ok(counters) => counters
+                .iter()
+                .filter(|(observed_did, observed_counter)| {
+                    *observed_did == did && *observed_counter == counter
+                })
+                .count() as u64,
+            Err(_) => 0,
+        }
+    }
+}
+
+#[async_trait]
+impl Measure for CountingMeasure {
+    async fn incr(&self, did: crate::dht::Did, counter: MeasureCounter) {
+        if let Ok(mut counters) = self.counters.lock() {
+            counters.push((did, counter));
+        }
+    }
+
+    async fn get_count(&self, did: crate::dht::Did, counter: MeasureCounter) -> u64 {
+        self.count(did, counter)
+    }
+}
+
+#[async_trait]
+impl BehaviourJudgement for CountingMeasure {
+    async fn quality(&self, _did: crate::dht::Did) -> PeerQuality {
+        PeerQuality::Unknown
+    }
+
+    async fn good(&self, _did: crate::dht::Did) -> bool {
+        true
+    }
+}
+
+fn prepare_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result {
+    let session = SessionSk::new_with_seckey(&key)?;
+    let swarm = Arc::new(
+        SwarmBuilder::new(
+            0,
+            "stun://stun.l.google.com:19302",
+            Box::new(MemStorage::new()),
+            session,
+        )
+        .dht_finger_table_size(super::TEST_DHT_FINGER_TABLE_SIZE)
+        .dht_virtual_nodes(0)
+        .measure(measure)
+        .build(),
+    );
+    Ok(Node::new(swarm))
+}
+
+fn large_storage_sync_entries() -> Result> {
+    let mut entries = Vec::new();
+    for index in 0..48 {
+        let topic = format!("chunked storage sync cancellation {index}");
+        let entry_did = Entry::gen_did(&topic)?;
+        let payload = format!("payload-{index}-{}", "x".repeat(512));
+        let entry = Entry::new(entry_did, vec![payload.into()], EntryKind::Data);
+        entries.push(PlacedEntry::new(entry_did, entry));
+    }
+    Ok(entries)
+}
+
 /// Read inbound messages on `node` until a `CustomMessage` arrives (skipping DHT bookkeeping), or
 /// give up after a bounded number of messages.
 async fn recv_custom(node: &crate::tests::default::Node) -> Option> {
@@ -61,6 +202,80 @@ async fn large_message_is_chunked_and_reassembled() {
     dummy_controlled::set_max_message_size(0);
 }
 
+#[tokio::test]
+async fn spawned_storage_sync_tail_cancelled_by_route_disappear_does_not_degrade_next_hop(
+) -> Result<()> {
+    let measure = Arc::new(CountingMeasure::default());
+    let measure_impl: MeasureImpl = measure.clone();
+    let node1 = prepare_node_with_measure(SecretKey::random(), measure_impl)?;
+    let node2 = prepare_node(SecretKey::random()).await;
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+    wait_for_connection_state(&node1, node2.did(), WebrtcConnectionState::Connected).await?;
+    wait_for_successor(&node1, node2.did()).await?;
+    wait_for_msgs([&node1, &node2]).await;
+
+    let _max_size = MaxMessageSizeGuard::new(8192);
+    dummy_controlled::reset_sent_count();
+    let _pending_after_first_chunk = PendingAfterSentCountGuard::new(1);
+    let msg = SyncEntriesWithSuccessor {
+        purpose: StorageSyncPurpose::AdditiveRepair,
+        destination: StorageSyncDestination::PhysicalOwner(node2.did()),
+        data: large_storage_sync_entries()?,
+    };
+
+    let failed_before = measure.count(node2.did(), MeasureCounter::FailedToSend);
+    node1.swarm.transport.send_storage_sync(msg).await?;
+    assert_eq!(
+        dummy_controlled::sent_count(),
+        1,
+        "the first chunk is accepted before the route is withdrawn"
+    );
+
+    node1.dht().remove(node2.did())?;
+    sleep(Duration::from_millis(600)).await;
+    assert_eq!(
+        dummy_controlled::sent_count(),
+        1,
+        "route cancellation must stop the spawned task before another chunk is dispatched"
+    );
+    assert_eq!(
+        measure.count(node2.did(), MeasureCounter::FailedToSend),
+        failed_before,
+        "route cancellation is stale topology, not next-hop transport failure"
+    );
+    Ok(())
+}
+
+#[tokio::test]
+async fn send_queue_backpressure_returns_transport_timeout() {
+    let key1 = SecretKey::random();
+    let key2 = SecretKey::random();
+    let node1 = prepare_node(key1).await;
+    let node2 = prepare_node(key2).await;
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+    wait_for_connection_state(&node1, node2.did(), WebrtcConnectionState::Connected)
+        .await
+        .unwrap();
+    wait_for_connection_state(&node2, node1.did(), WebrtcConnectionState::Connected)
+        .await
+        .unwrap();
+
+    let _guard = PendingSendGuard::new();
+    let err = node1
+        .swarm
+        .send_message(Message::custom(b"queue-blocked").unwrap(), node2.did())
+        .await
+        .expect_err("send admission should time out when the backend never accepts bytes");
+
+    assert!(
+        matches!(
+            err,
+            crate::error::Error::DataChannelSendQueueTimeout { peer, .. } if peer == node2.did()
+        ),
+        "expected DataChannelSendQueueTimeout, got {err:?}"
+    );
+}
+
 #[tokio::test]
 async fn negotiated_size_too_small_errors_without_partial_send() {
     let key1 = SecretKey::random();
diff --git a/crates/core/src/tests/default/test_stabilization.rs b/crates/core/src/tests/default/test_stabilization.rs
index 5edc6324b..eba4cbc3f 100644
--- a/crates/core/src/tests/default/test_stabilization.rs
+++ b/crates/core/src/tests/default/test_stabilization.rs
@@ -14,8 +14,8 @@ use crate::dht::entry::EntryKind;
 use crate::dht::successor::SuccessorReader;
 use crate::dht::successor::SuccessorWriter;
 use crate::dht::Did;
+use crate::dht::PeerRingAction;
 use crate::ecc::SecretKey;
-#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
 use crate::error::Error;
 use crate::error::Result;
 use crate::measure::BehaviourJudgement;
@@ -27,12 +27,17 @@ use crate::measure::PeerQualityEvidence;
 use crate::measure::PeerQualityThresholds;
 use crate::session::SessionSk;
 use crate::storage::MemStorage;
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+use crate::swarm::transport::PEER_LIVENESS_TIMEOUT_MS;
 use crate::swarm::SwarmBuilder;
+use crate::tests::default::assert_no_more_msg;
 use crate::tests::default::prepare_node;
+use crate::tests::default::wait_for_msgs;
 use crate::tests::default::wait_for_predecessor;
 use crate::tests::default::wait_for_successor;
 use crate::tests::default::Node;
 use crate::tests::manually_establish_connection;
+use crate::utils::get_epoch_ms_i64;
 
 #[derive(Default)]
 struct CountingMeasure {
@@ -95,6 +100,24 @@ impl Drop for PendingDataChannelWaitGuard {
     }
 }
 
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+struct DropMessagesGuard;
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+impl DropMessagesGuard {
+    fn new() -> Self {
+        dummy_controlled::set_drop_messages(true);
+        Self
+    }
+}
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+impl Drop for DropMessagesGuard {
+    fn drop(&mut self) {
+        dummy_controlled::set_drop_messages(false);
+    }
+}
+
 fn prepare_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result {
     let session = SessionSk::new_with_seckey(&key)?;
     let swarm = Arc::new(
@@ -112,6 +135,42 @@ fn prepare_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result Result {
+    let session = SessionSk::new_with_seckey(&key)?;
+    let swarm = Arc::new(
+        SwarmBuilder::new(
+            0,
+            "stun://stun.l.google.com:19302",
+            Box::new(MemStorage::new()),
+            session,
+        )
+        .dht_finger_table_size(super::TEST_DHT_FINGER_TABLE_SIZE)
+        .dht_storage_redundancy(2)
+        .dht_virtual_nodes(0)
+        .build(),
+    );
+    Ok(Node::new(swarm))
+}
+
+fn entry_with_remote_repair_placement(node: &Node) -> Result<(Entry, Did)> {
+    for attempt in 0..1024 {
+        let resource = Entry::gen_did(&format!("fresh repair candidate {attempt}"))?;
+        let entry = Entry::new(resource, vec![], EntryKind::Data);
+        for placement in entry.did.rotate_affine(2)? {
+            if matches!(
+                node.dht().find_storage_owner(placement)?,
+                PeerRingAction::RemoteAction(_, _)
+            ) {
+                return Ok((entry, placement));
+            }
+        }
+    }
+
+    Err(Error::InvalidMessage(
+        "could not sample remote repair placement".to_string(),
+    ))
+}
+
 #[tokio::test]
 async fn test_stabilization_once() -> Result<()> {
     let mut key1 = SecretKey::random();
@@ -190,6 +249,45 @@ async fn stabilize_step_timeout_bounds_wedged_data_channel_wait() -> Result<()>
     Ok(())
 }
 
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+#[tokio::test]
+async fn clean_unavailable_connections_removes_silent_connected_peer() -> Result<()> {
+    let node1 = prepare_node(SecretKey::random()).await;
+    let node2 = prepare_node(SecretKey::random()).await;
+
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+    wait_for_successor(&node1, node2.did()).await?;
+
+    node1.dht().successors().extend(&[node2.did()])?;
+    *node1.dht().lock_predecessor()? = Some(node2.did());
+    {
+        let dht = node1.dht();
+        let mut finger = dht.lock_finger()?;
+        finger.set(0, node2.did());
+        finger.set(3, node2.did());
+    }
+
+    let stale_probe_sent_at = get_epoch_ms_i64() - PEER_LIVENESS_TIMEOUT_MS - 1;
+    node1
+        .swarm
+        .transport
+        .force_peer_liveness_probe_sent_at(node2.did(), stale_probe_sent_at)?;
+
+    let _drop_messages = DropMessagesGuard::new();
+    node1
+        .swarm
+        .stabilizer()
+        .clean_unavailable_connections()
+        .await?;
+
+    assert!(node1.swarm.transport.get_connection(node2.did()).is_none());
+    assert!(!node1.dht().successors().contains(&node2.did())?);
+    assert_eq!(*node1.dht().lock_predecessor()?, None);
+    assert!(!node1.dht().lock_finger()?.contains(Some(node2.did())));
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn clean_unavailable_connections_removes_stale_topology_peer() -> Result<()> {
     let node = prepare_node(SecretKey::random()).await;
@@ -303,6 +401,50 @@ async fn stabilize_republishes_local_entries_to_missing_affine_owners() -> Resul
     Ok(())
 }
 
+#[tokio::test]
+async fn repair_storage_defers_sync_to_fresh_next_hop() -> Result<()> {
+    let mut key1 = SecretKey::random();
+    let mut key2 = SecretKey::random();
+    if key1.address() < key2.address() {
+        (key1, key2) = (key2, key1)
+    }
+    let node1 = prepare_repair_node(key1)?;
+    let node2 = prepare_repair_node(key2)?;
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+
+    wait_for_successor(&node1, node2.did()).await?;
+    wait_for_msgs([&node1, &node2]).await;
+    let connected_for_ms = node1
+        .swarm
+        .transport
+        .peer_connected_for_ms(node2.did(), get_epoch_ms_i64())?
+        .ok_or_else(|| Error::InvalidMessage("missing peer admission age".to_string()))?;
+    assert!(
+        connected_for_ms < 30_000,
+        "test must exercise a fresh connection; observed age {connected_for_ms}ms"
+    );
+
+    let (entry, remote_placement) = entry_with_remote_repair_placement(&node1)?;
+    node1
+        .dht()
+        .storage
+        .put(&entry.did.to_string(), &entry)
+        .await?;
+
+    node1.swarm.stabilizer().repair_storage().await?;
+
+    assert_no_more_msg([&node2]).await;
+    assert_eq!(
+        node2
+            .dht()
+            .storage
+            .get(&remote_placement.to_string())
+            .await?,
+        None
+    );
+    Ok(())
+}
+
 #[tokio::test]
 async fn test_stabilization() -> Result<()> {
     let mut key1 = SecretKey::random();
diff --git a/crates/core/src/tests/wasm/test_idb_storage.rs b/crates/core/src/tests/wasm/test_idb_storage.rs
index a78983bb3..19a5f62bb 100644
--- a/crates/core/src/tests/wasm/test_idb_storage.rs
+++ b/crates/core/src/tests/wasm/test_idb_storage.rs
@@ -24,7 +24,9 @@ async fn create_db_instance(cap: u32) -> IdbStorage {
 }
 
 async fn create_kv_db(cap: u32) -> Box>
-where V: DeserializeOwned + Serialize + Sized {
+where
+    V: DeserializeOwned + Serialize + Sized,
+{
     Box::new(create_db_instance(cap).await)
 }
 
@@ -190,27 +192,39 @@ async fn test_idb_prune() {
     let key4 = "4".to_string();
     let key5 = "5".to_string();
     instance
-        .put(&key1, &TestDataStruct {
-            content: "test1".to_owned(),
-        })
+        .put(
+            &key1,
+            &TestDataStruct {
+                content: "test1".to_owned(),
+            },
+        )
         .await
         .unwrap();
     instance
-        .put(&key2, &TestDataStruct {
-            content: "test2".to_owned(),
-        })
+        .put(
+            &key2,
+            &TestDataStruct {
+                content: "test2".to_owned(),
+            },
+        )
         .await
         .unwrap();
     instance
-        .put(&key3, &TestDataStruct {
-            content: "test3".to_owned(),
-        })
+        .put(
+            &key3,
+            &TestDataStruct {
+                content: "test3".to_owned(),
+            },
+        )
         .await
         .unwrap();
     instance
-        .put(&key4, &TestDataStruct {
-            content: "test4".to_owned(),
-        })
+        .put(
+            &key4,
+            &TestDataStruct {
+                content: "test4".to_owned(),
+            },
+        )
         .await
         .unwrap();
 
@@ -224,9 +238,12 @@ async fn test_idb_prune() {
     tracing::debug!("d2, {:?}", d2);
 
     instance
-        .put(&key5, &TestDataStruct {
-            content: "test5".to_owned(),
-        })
+        .put(
+            &key5,
+            &TestDataStruct {
+                content: "test5".to_owned(),
+            },
+        )
         .await
         .unwrap();
 
diff --git a/crates/core/src/utils.rs b/crates/core/src/utils.rs
index 10f809c8a..0698d6a2b 100644
--- a/crates/core/src/utils.rs
+++ b/crates/core/src/utils.rs
@@ -23,6 +23,21 @@ pub(crate) fn get_epoch_ms_i64() -> i64 {
     i64::try_from(get_epoch_ms()).unwrap_or(i64::MAX)
 }
 
+/// Sleep for `duration` on the active runtime.
+#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
+pub(crate) async fn sleep(duration: std::time::Duration) {
+    futures_timer::Delay::new(duration).await;
+}
+
+/// Sleep for `duration` on the JavaScript event loop.
+#[cfg(all(feature = "wasm", target_family = "wasm"))]
+pub(crate) async fn sleep(duration: std::time::Duration) {
+    let millis = i32::try_from(duration.as_millis()).unwrap_or(i32::MAX);
+    if let Err(error) = js_utils::window_sleep(millis).await {
+        tracing::error!("failed to wait for timeout: {:?}", error);
+    }
+}
+
 #[cfg(all(feature = "wasm", target_family = "wasm"))]
 /// Toolset for wasm
 pub mod js_value {
@@ -233,7 +248,9 @@ pub mod js_utils {
     }
 
     fn schedule_sleep(resolve: js_sys::Function, reject: js_sys::Function, schedule: F)
-    where F: FnOnce(&js_sys::Function) -> Result {
+    where
+        F: FnOnce(&js_sys::Function) -> Result,
+    {
         let func = Closure::once_into_js(move || {
             resolve_sleep(&resolve);
         });
diff --git a/crates/node/src/extension/protocols/echo.rs b/crates/node/src/extension/protocols/echo.rs
index 08a26c03c..81b323f30 100644
--- a/crates/node/src/extension/protocols/echo.rs
+++ b/crates/node/src/extension/protocols/echo.rs
@@ -71,10 +71,13 @@ impl Protocol for Echo {
 
     /// Pure. `step (Ctx n, Echoed{from,p}) = ((n+1), [Reply to=from p])`.
     fn step(&self, ctx: Ctx<'_, u64>, event: Echoed) -> Transition {
-        Transition::with(ctx.state + 1, vec![EchoEffect::Reply {
-            to: event.from,
-            payload: event.payload,
-        }])
+        Transition::with(
+            ctx.state + 1,
+            vec![EchoEffect::Reply {
+                to: event.from,
+                payload: event.payload,
+            }],
+        )
     }
 }
 
diff --git a/crates/node/src/extension/protocols/relay.rs b/crates/node/src/extension/protocols/relay.rs
index 747e48706..707b7a194 100644
--- a/crates/node/src/extension/protocols/relay.rs
+++ b/crates/node/src/extension/protocols/relay.rs
@@ -219,7 +219,8 @@ impl Relay {
 }
 
 impl Protocol for Relay
-where T: Clone + DeserializeOwned + Serialize + MaybeSend + 'static
+where
+    T: Clone + DeserializeOwned + Serialize + MaybeSend + 'static,
 {
     type State = RelayState;
     type Event = RelayEvent;
@@ -299,11 +300,14 @@ fn step_command(
             // A locally-accepted tunnel: we are the initiator.
             let key = SessionKey::new(peer, namespace, session, Initiator::Local);
             next.sessions.insert(key.clone());
-            Transition::with(next, vec![RelayEffect::OpenAccepted {
-                token,
-                key,
-                service,
-            }])
+            Transition::with(
+                next,
+                vec![RelayEffect::OpenAccepted {
+                    token,
+                    key,
+                    service,
+                }],
+            )
         }
         RelayCommand::Untrack {
             peer,
@@ -340,12 +344,15 @@ fn step_frame(
                     next.sessions.insert(key.clone());
                     Transition::with(next, vec![RelayEffect::Connect { key, target, kind }])
                 }
-                None => Transition::with(state.clone(), vec![RelayEffect::SendClose {
-                    to: from,
-                    session,
-                    // The peer opened it (unknown service); we did not.
-                    from_opener: false,
-                }]),
+                None => Transition::with(
+                    state.clone(),
+                    vec![RelayEffect::SendClose {
+                        to: from,
+                        session,
+                        // The peer opened it (unknown service); we did not.
+                        from_opener: false,
+                    }],
+                ),
             }
         }
         // Data/Shutdown/Close are guarded on the authoritative session set: the *reducer*
@@ -651,7 +658,9 @@ impl RelayHandle {
 /// scope's own namespace (provenance = self).
 #[cfg(any(feature = "node", feature = "browser"))]
 async fn register_service(scope: &Scope, name: String, target: T) -> crate::error::Result<()>
-where T: Serialize {
+where
+    T: Serialize,
+{
     let command = RelayCommand::RegisterService { name, target };
     let payload = bincode::serialize(&command).map_err(|_| crate::error::Error::EncodeError)?;
     scope.inject(Bytes::from(payload)).await
@@ -918,10 +927,14 @@ mod tests {
     #[test]
     fn register_service_via_self_command_then_open_connects() {
         let relay = Relay::tcp(HashMap::new());
-        let registered = step_command(&relay, &relay.init(), &RelayCommand::RegisterService {
-            name: "web".to_string(),
-            target: web_addr(),
-        });
+        let registered = step_command(
+            &relay,
+            &relay.init(),
+            &RelayCommand::RegisterService {
+                name: "web".to_string(),
+                target: web_addr(),
+            },
+        );
         assert!(registered.effects.is_empty());
         let t = step_frame(&relay, ®istered.state, peer_a(), &open(1, "web"));
         match t.effects.as_slice() {
@@ -935,11 +948,15 @@ mod tests {
         let relay = web_relay();
         // A client-side accept is fed back as `Accepted{token}`. The core mints the session id
         // (0 on fresh state, initiator Local) and replies OpenAccepted with that minted key.
-        let accepted = step_command(&relay, &relay.init(), &RelayCommand::Accepted {
-            token: 42,
-            peer: peer_a(),
-            service: "web".to_string(),
-        });
+        let accepted = step_command(
+            &relay,
+            &relay.init(),
+            &RelayCommand::Accepted {
+                token: 42,
+                peer: peer_a(),
+                service: "web".to_string(),
+            },
+        );
         let key = SessionKey::new(peer_a(), super::TCP, SessionId(0), Initiator::Local);
         match accepted.effects.as_slice() {
             [RelayEffect::OpenAccepted {
@@ -955,11 +972,15 @@ mod tests {
         }
         assert!(accepted.state.sessions.contains(&key));
 
-        let untracked = step_command(&relay, &accepted.state, &RelayCommand::Untrack {
-            peer: peer_a(),
-            session: SessionId(0),
-            initiator: Initiator::Local,
-        });
+        let untracked = step_command(
+            &relay,
+            &accepted.state,
+            &RelayCommand::Untrack {
+                peer: peer_a(),
+                session: SessionId(0),
+                initiator: Initiator::Local,
+            },
+        );
         assert!(untracked.effects.is_empty());
         assert!(!untracked.state.sessions.contains(&key));
     }
@@ -992,11 +1013,15 @@ mod tests {
         // and a locally-accepted (Local) session must be distinct keys.
         let relay = web_relay();
         let opened = step_frame(&relay, &relay.init(), peer_a(), &open(0, "web"));
-        let accepted = step_command(&relay, &opened.state, &RelayCommand::Accepted {
-            token: 1,
-            peer: peer_a(),
-            service: "web".to_string(),
-        });
+        let accepted = step_command(
+            &relay,
+            &opened.state,
+            &RelayCommand::Accepted {
+                token: 1,
+                peer: peer_a(),
+                service: "web".to_string(),
+            },
+        );
         let remote = SessionKey::new(peer_a(), super::TCP, SessionId(0), Initiator::Remote);
         let local = SessionKey::new(peer_a(), super::TCP, SessionId(0), Initiator::Local);
         assert_ne!(remote, local);
@@ -1074,9 +1099,10 @@ mod tests {
                     if model.contains(&key) {
                         assert!(t.effects.is_empty(), "duplicate Open must emit nothing");
                     } else {
-                        assert!(matches!(t.effects.as_slice(), [
-                            RelayEffect::Connect { .. }
-                        ]));
+                        assert!(matches!(
+                            t.effects.as_slice(),
+                            [RelayEffect::Connect { .. }]
+                        ));
                         model.insert(key.clone());
                     }
                     t
@@ -1086,9 +1112,10 @@ mod tests {
                     if model.contains(&key) {
                         assert!(t.effects.is_empty());
                     } else {
-                        assert!(matches!(t.effects.as_slice(), [
-                            RelayEffect::SendClose { .. }
-                        ]));
+                        assert!(matches!(
+                            t.effects.as_slice(),
+                            [RelayEffect::SendClose { .. }]
+                        ));
                     }
                     t
                 }
diff --git a/crates/node/src/extension/snark/builder.rs b/crates/node/src/extension/snark/builder.rs
index 0b33a06da..5722c4a5d 100644
--- a/crates/node/src/extension/snark/builder.rs
+++ b/crates/node/src/extension/snark/builder.rs
@@ -226,9 +226,12 @@ impl SNARKTaskBuilder {
                 let first = first_generated_circuit(&circuits)?;
                 let inputs = first.get_public_inputs()?;
                 let pp = SNARK::::gen_pp::(first.clone())?;
-                let snark = SNARK::::new(first, &pp, &inputs, &vec![
-                    ::Scalar::from(0),
-                ])?;
+                let snark = SNARK::::new(
+                    first,
+                    &pp,
+                    &inputs,
+                    &vec![::Scalar::from(0)],
+                )?;
 
                 SNARKProofTask::VastaPallas(SNARKGenerator {
                     pp: pp.into(),
@@ -256,9 +259,12 @@ impl SNARKTaskBuilder {
                 let first = first_generated_circuit(&circuits)?;
                 let inputs = first.get_public_inputs()?;
                 let pp = SNARK::::gen_pp::(first.clone())?;
-                let snark = SNARK::::new(first, &pp, &inputs, &vec![
-                    ::Scalar::from(0),
-                ])?;
+                let snark = SNARK::::new(
+                    first,
+                    &pp,
+                    &inputs,
+                    &vec![::Scalar::from(0)],
+                )?;
                 SNARKProofTask::PallasVasta(SNARKGenerator {
                     pp: pp.into(),
                     snark,
@@ -285,9 +291,12 @@ impl SNARKTaskBuilder {
                 let first = first_generated_circuit(&circuits)?;
                 let inputs = first.get_public_inputs()?;
                 let pp = SNARK::::gen_pp::(first.clone())?;
-                let snark = SNARK::::new(first, &pp, &inputs, &vec![
-                    ::Scalar::from(0),
-                ])?;
+                let snark = SNARK::::new(
+                    first,
+                    &pp,
+                    &inputs,
+                    &vec![::Scalar::from(0)],
+                )?;
                 SNARKProofTask::Bn256KZGGrumpkin(SNARKGenerator {
                     pp: pp.into(),
                     snark,
diff --git a/crates/node/src/extension/snark/protocol.rs b/crates/node/src/extension/snark/protocol.rs
index 0a07cea21..9337e461a 100644
--- a/crates/node/src/extension/snark/protocol.rs
+++ b/crates/node/src/extension/snark/protocol.rs
@@ -134,26 +134,33 @@ impl Protocol for SnarkProtocol {
                 task_id,
                 reply_to,
                 verify_task,
-            }) => Transition::with((), vec![SnarkEffect::SendTask {
-                to: reply_to,
-                msg: SNARKTaskMessage {
-                    task_id,
-                    task: SNARKTask::SNARKVerify(verify_task),
-                },
-            }]),
+            }) => Transition::with(
+                (),
+                vec![SnarkEffect::SendTask {
+                    to: reply_to,
+                    msg: SNARKTaskMessage {
+                        task_id,
+                        task: SNARKTask::SNARKVerify(verify_task),
+                    },
+                }],
+            ),
             SnarkEvent::Result(ComputeResult::Verified { .. }) => Transition::pure(()),
             SnarkEvent::Task { from, msg } => match msg.task {
-                SNARKTask::SNARKProof(task) => Transition::with((), vec![SnarkEffect::Prove {
-                    task_id: msg.task_id,
-                    reply_to: from,
-                    task,
-                }]),
-                SNARKTask::SNARKVerify(verify_task) => {
-                    Transition::with((), vec![SnarkEffect::Verify {
+                SNARKTask::SNARKProof(task) => Transition::with(
+                    (),
+                    vec![SnarkEffect::Prove {
+                        task_id: msg.task_id,
+                        reply_to: from,
+                        task,
+                    }],
+                ),
+                SNARKTask::SNARKVerify(verify_task) => Transition::with(
+                    (),
+                    vec![SnarkEffect::Verify {
                         task_id: msg.task_id,
                         verify_task,
-                    }])
-                }
+                    }],
+                ),
             },
         }
     }
diff --git a/crates/node/src/extension/transport/engine/mod.rs b/crates/node/src/extension/transport/engine/mod.rs
index 99d6856d0..43edef8fc 100644
--- a/crates/node/src/extension/transport/engine/mod.rs
+++ b/crates/node/src/extension/transport/engine/mod.rs
@@ -305,11 +305,15 @@ impl TransportSessions {
                 }
                 // Forward the first datagram that triggered this flow.
                 let from_opener = opened_by_us(&key);
-                let _ = send_frame(&scope, key.peer, Frame::Data {
-                    session: key.session,
-                    from_opener,
-                    bytes: first,
-                })
+                let _ = send_frame(
+                    &scope,
+                    key.peer,
+                    Frame::Data {
+                        session: key.session,
+                        from_opener,
+                        bytes: first,
+                    },
+                )
                 .await;
             }
         }
@@ -352,12 +356,15 @@ impl TransportSessions {
         let (outbound, outbound_rx) = mpsc::channel::(1024);
         let cancel = CancellationToken::new();
         let generation = self.generations.fetch_add(1, Ordering::Relaxed);
-        self.insert(key, SessionHandle {
-            outbound,
-            cancel: cancel.clone(),
-            src,
-            generation,
-        });
+        self.insert(
+            key,
+            SessionHandle {
+                outbound,
+                cancel: cancel.clone(),
+                src,
+                generation,
+            },
+        );
         (outbound_rx, cancel, generation)
     }
 
@@ -423,10 +430,14 @@ impl RelayTask {
             .close_if_current(&self.scope, &self.key, self.generation)
             .await
         {
-            let _ = send_frame(&self.scope, self.key.peer, Frame::Close {
-                session: self.key.session,
-                from_opener: opened_by_us(&self.key),
-            })
+            let _ = send_frame(
+                &self.scope,
+                self.key.peer,
+                Frame::Close {
+                    session: self.key.session,
+                    from_opener: opened_by_us(&self.key),
+                },
+            )
             .await;
         }
     }
@@ -439,10 +450,14 @@ fn opened_by_us(key: &SessionKey) -> bool {
 
 /// Send `Frame::Open` to the session's peer (client side, on a new local connection/flow).
 async fn open(scope: &Scope, key: &SessionKey, service: &str) -> Result<()> {
-    send_frame(scope, key.peer, Frame::Open {
-        session: key.session,
-        service: service.to_string(),
-    })
+    send_frame(
+        scope,
+        key.peer,
+        Frame::Open {
+            session: key.session,
+            service: service.to_string(),
+        },
+    )
     .await
 }
 
diff --git a/crates/node/src/extension/transport/engine/tcp.rs b/crates/node/src/extension/transport/engine/tcp.rs
index 03ccfe42a..5d45072b5 100644
--- a/crates/node/src/extension/transport/engine/tcp.rs
+++ b/crates/node/src/extension/transport/engine/tcp.rs
@@ -88,20 +88,28 @@ pub(super) async fn relay_tcp(task: RelayTask, stream: TcpStream) {
             loop {
                 match local_read.read(buf.as_mut_slice()).await {
                     Ok(0) => {
-                        let _ = send_frame(&scope, peer, Frame::Shutdown {
-                            session,
-                            from_opener,
-                        })
+                        let _ = send_frame(
+                            &scope,
+                            peer,
+                            Frame::Shutdown {
+                                session,
+                                from_opener,
+                            },
+                        )
                         .await;
                         break;
                     }
                     Ok(n) => {
                         let bytes = Bytes::copy_from_slice(buf.get(..n).unwrap_or_default());
-                        if send_frame(&scope, peer, Frame::Data {
-                            session,
-                            from_opener,
-                            bytes,
-                        })
+                        if send_frame(
+                            &scope,
+                            peer,
+                            Frame::Data {
+                                session,
+                                from_opener,
+                                bytes,
+                            },
+                        )
                         .await
                         .is_err()
                         {
@@ -148,10 +156,14 @@ pub(super) async fn relay_tcp(task: RelayTask, stream: TcpStream) {
     // reuse of the key) — which `Untrack`s it from the pure state. Only tell the peer if we
     // were still the current owner; a stale task must not Close the peer's reused session.
     if sessions.close_if_current(&scope, &key, generation).await {
-        let _ = send_frame(&scope, peer, Frame::Close {
-            session,
-            from_opener,
-        })
+        let _ = send_frame(
+            &scope,
+            peer,
+            Frame::Close {
+                session,
+                from_opener,
+            },
+        )
         .await;
     }
 }
diff --git a/crates/node/src/extension/transport/engine/udp.rs b/crates/node/src/extension/transport/engine/udp.rs
index 1ff4911fc..065aac698 100644
--- a/crates/node/src/extension/transport/engine/udp.rs
+++ b/crates/node/src/extension/transport/engine/udp.rs
@@ -49,11 +49,15 @@ impl TransportSessions {
                         let bytes = Bytes::copy_from_slice(buf.get(..n).unwrap_or_default());
                         match self.udp_flow(&src) {
                             Some(key) => {
-                                let _ = send_frame(&scope, key.peer, Frame::Data {
-                                    session: key.session,
-                                    from_opener: super::opened_by_us(&key),
-                                    bytes,
-                                })
+                                let _ = send_frame(
+                                    &scope,
+                                    key.peer,
+                                    Frame::Data {
+                                        session: key.session,
+                                        from_opener: super::opened_by_us(&key),
+                                        bytes,
+                                    },
+                                )
                                 .await;
                             }
                             None => {
@@ -126,10 +130,14 @@ pub(super) async fn relay_udp_connected(task: RelayTask, socket: UdpSocket) {
     }
     // Only tell the peer if we were still the current owner (stale task stays silent).
     if sessions.close_if_current(&scope, &key, generation).await {
-        let _ = send_frame(&scope, peer, Frame::Close {
-            session,
-            from_opener,
-        })
+        let _ = send_frame(
+            &scope,
+            peer,
+            Frame::Close {
+                session,
+                from_opener,
+            },
+        )
         .await;
     }
 }
diff --git a/crates/node/src/extension/transport/wt.rs b/crates/node/src/extension/transport/wt.rs
index 3975dd7f9..747da60c1 100644
--- a/crates/node/src/extension/transport/wt.rs
+++ b/crates/node/src/extension/transport/wt.rs
@@ -134,10 +134,14 @@ impl WtSessions {
                 // Drop the opening slot and tell the peer — but only if we are still its owner
                 // (a peer Close during the handshake already tore it down and told the peer).
                 if self.close_if_current(&scope, &key, generation).await {
-                    let _ = send_frame(&scope, key.peer, Frame::Close {
-                        session: key.session,
-                        from_opener: matches!(key.initiator, Initiator::Local),
-                    })
+                    let _ = send_frame(
+                        &scope,
+                        key.peer,
+                        Frame::Close {
+                            session: key.session,
+                            from_opener: matches!(key.initiator, Initiator::Local),
+                        },
+                    )
                     .await;
                 }
             }
@@ -203,10 +207,13 @@ impl WtSessions {
     /// generation. The mirror of native's pre-dial `register`.
     fn open_slot(&self, key: SessionKey) -> u64 {
         let generation = self.generations.fetch_add(1, Ordering::Relaxed);
-        self.insert(key, SessionHandle::Opening {
-            queue: Vec::new(),
-            generation,
-        });
+        self.insert(
+            key,
+            SessionHandle::Opening {
+                queue: Vec::new(),
+                generation,
+            },
+        );
         generation
     }
 
@@ -249,11 +256,14 @@ impl WtSessions {
                 }
             }
         }
-        map.insert(key.clone(), SessionHandle::Ready {
-            writer,
-            transport,
-            generation,
-        });
+        map.insert(
+            key.clone(),
+            SessionHandle::Ready {
+                writer,
+                transport,
+                generation,
+            },
+        );
         true
     }
 
@@ -320,11 +330,15 @@ impl WtSessions {
                     Err(_) => break,
                 };
                 let bytes = Bytes::from(Uint8Array::new(&value).to_vec());
-                if send_frame(&scope, peer, Frame::Data {
-                    session,
-                    from_opener,
-                    bytes,
-                })
+                if send_frame(
+                    &scope,
+                    peer,
+                    Frame::Data {
+                        session,
+                        from_opener,
+                        bytes,
+                    },
+                )
                 .await
                 .is_err()
                 {
@@ -334,10 +348,14 @@ impl WtSessions {
             // Generation-checked teardown: only Close the peer if we were still the current
             // owner, so a stale read loop never tears down a reopened session.
             if sessions.close_if_current(&scope, &key, generation).await {
-                let _ = send_frame(&scope, peer, Frame::Close {
-                    session,
-                    from_opener,
-                })
+                let _ = send_frame(
+                    &scope,
+                    peer,
+                    Frame::Close {
+                        session,
+                        from_opener,
+                    },
+                )
                 .await;
             }
         });
diff --git a/crates/node/src/logging.rs b/crates/node/src/logging.rs
index a5934c07f..8aac98ab0 100644
--- a/crates/node/src/logging.rs
+++ b/crates/node/src/logging.rs
@@ -68,7 +68,8 @@ pub struct PanicLocation {
 }
 
 impl<'a, T> From for PanicLocation
-where T: Into>
+where
+    T: Into>,
 {
     fn from(lo: T) -> Self {
         let lo: Location = lo.into();
@@ -89,7 +90,8 @@ pub struct PanicData<'a> {
 }
 
 impl<'a, T> From for PanicData<'a>
-where T: Into<&'a PanicHookInfo<'a>>
+where
+    T: Into<&'a PanicHookInfo<'a>>,
 {
     fn from(panic: T) -> PanicData<'a> {
         let panic = panic.into();
diff --git a/crates/node/src/native/cli.rs b/crates/node/src/native/cli.rs
index ed3a1983f..d640695de 100644
--- a/crates/node/src/native/cli.rs
+++ b/crates/node/src/native/cli.rs
@@ -186,10 +186,7 @@ impl Client {
     }
 
     /// Subscribes to the specified topic and returns a stream of messages published to the topic.
-    pub async fn subscribe_topic<'a, 'b>(
-        &'a self,
-        topic: String,
-    ) -> impl Stream + 'b
+    pub async fn subscribe_topic<'a, 'b>(&'a self, topic: String) -> impl Stream + 'b
     where
         'a: 'b,
     {
diff --git a/crates/node/src/native/config.rs b/crates/node/src/native/config.rs
index 1ab4a8746..fd305dd7d 100644
--- a/crates/node/src/native/config.rs
+++ b/crates/node/src/native/config.rs
@@ -49,7 +49,9 @@ pub const DEFAULT_STORAGE_CAPACITY: u32 = 200000000;
 
 /// Builds the default storage path under the user home directory.
 pub fn get_storage_location
(prefix: P, path: P) -> String
-where P: AsRef {
+where
+    P: AsRef,
+{
     let home_dir = env::var_os("HOME").map(PathBuf::from);
     let storage_path = match home_dir {
         Some(dir) => dir.join(prefix).join(path),
@@ -217,7 +219,9 @@ impl TryFrom for ProcessorConfig {
 impl Config {
     /// Creates a default native-node configuration using the supplied session key path.
     pub fn new
(session_sk: P) -> Self
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let session_sk = session_sk.as_ref().to_string_lossy().to_string();
         Self {
             network_id: DEFAULT_NETWORK_ID,
@@ -260,7 +264,9 @@ impl Config {
 
     /// Writes this configuration to a YAML file and returns the written path.
     pub fn write_fs
(&self, path: P) -> Result
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let path = expand_home(path)?;
         ensure_parent_dir(&path)?;
         let f =
@@ -274,7 +280,9 @@ impl Config {
 
     /// Reads a native-node configuration from a YAML file.
     pub fn read_fs
(path: P) -> Result
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let path = expand_home(path)?;
         tracing::debug!("Read config from: {:?}", path);
         let f = fs::File::open(path).map_err(|e| Error::OpenFileError(e.to_string()))?;
diff --git a/crates/node/src/native/endpoint/mod.rs b/crates/node/src/native/endpoint/mod.rs
index 4500fd189..7d035542a 100644
--- a/crates/node/src/native/endpoint/mod.rs
+++ b/crates/node/src/native/endpoint/mod.rs
@@ -22,7 +22,8 @@ use crate::processor::Processor;
 /// JSON-RPC state
 #[derive(Clone)]
 pub struct JsonRpcState
-where M: jsonrpc_core::Middleware>
+where
+    M: jsonrpc_core::Middleware>,
 {
     processor: Arc,
     io_handler: MetaIoHandler, M>,
diff --git a/crates/node/src/onion/circuit/shell.rs b/crates/node/src/onion/circuit/shell.rs
index 2d7d6925a..845804864 100644
--- a/crates/node/src/onion/circuit/shell.rs
+++ b/crates/node/src/onion/circuit/shell.rs
@@ -110,7 +110,8 @@ impl OnionCircuitShell {
 #[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
 #[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
 impl Interpret for OnionCircuitShell
-where H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static
+where
+    H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static,
 {
     type Effect = OnionCircuitEffect;
 
@@ -140,14 +141,17 @@ where H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static
                 payload,
             } => {
                 self.handler
-                    .handle_exit(scope, OnionCircuitExitFrame {
-                        from,
-                        circuit_id,
-                        return_peer,
-                        client,
-                        forward_nonce,
-                        payload,
-                    })
+                    .handle_exit(
+                        scope,
+                        OnionCircuitExitFrame {
+                            from,
+                            circuit_id,
+                            return_peer,
+                            client,
+                            forward_nonce,
+                            payload,
+                        },
+                    )
                     .await?;
                 Ok(Vec::new())
             }
diff --git a/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs b/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
index 2732576e4..6bfd6b121 100644
--- a/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
+++ b/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
@@ -421,17 +421,20 @@ fn expired_exit_layer_emits_no_exit_effect() {
     let state = OnionCircuitState::default();
     let circuit_id = OnionCircuitId::new([8; 16]);
 
-    let transition = reducer.apply(&state, OnionCircuitInput::ForwardReady {
-        from: client.account_did(),
-        received_at_ms: 100,
-        circuit_id,
-        layer: OnionForwardLayer::Exit {
-            client: OnionClientReturn::new(client.session_public_key()),
-            expires_at_ms: 100,
-            forward_nonce: OnionForwardNonce::new([9; 16]),
-            payload: test_payload("expired"),
+    let transition = reducer.apply(
+        &state,
+        OnionCircuitInput::ForwardReady {
+            from: client.account_did(),
+            received_at_ms: 100,
+            circuit_id,
+            layer: OnionForwardLayer::Exit {
+                client: OnionClientReturn::new(client.session_public_key()),
+                expires_at_ms: 100,
+                forward_nonce: OnionForwardNonce::new([9; 16]),
+                payload: test_payload("expired"),
+            },
         },
-    });
+    );
 
     assert_eq!(transition.state, state);
     assert!(transition.effects.is_empty());
diff --git a/crates/node/src/onion/https/mod.rs b/crates/node/src/onion/https/mod.rs
index 14177d506..d4fe7b415 100644
--- a/crates/node/src/onion/https/mod.rs
+++ b/crates/node/src/onion/https/mod.rs
@@ -218,12 +218,15 @@ impl OnionHttpsRuntime {
                 continue;
             }
             let (sender, receiver) = oneshot::channel();
-            pending.insert(id, PendingRequest {
-                expected_return_peer,
-                expected_exit,
-                return_id,
-                sender,
-            });
+            pending.insert(
+                id,
+                PendingRequest {
+                    expected_return_peer,
+                    expected_exit,
+                    return_id,
+                    sender,
+                },
+            );
             return Ok((id, receiver));
         }
         Err(Error::OnionRouteError(
diff --git a/crates/node/src/onion/https/tests/test_https_proxy.rs b/crates/node/src/onion/https/tests/test_https_proxy.rs
index e8beece2a..af93ce518 100644
--- a/crates/node/src/onion/https/tests/test_https_proxy.rs
+++ b/crates/node/src/onion/https/tests/test_https_proxy.rs
@@ -76,13 +76,16 @@ fn normalizes_empty_request_defaults() {
     let target = OnionProxyTarget::parse_authority("Example.COM:443").unwrap();
     let wire = client_request_with_default_path(&target, request, default_path().as_str()).unwrap();
 
-    assert_eq!(wire, OnionHttpsRequest {
-        target: "example.com:443".to_string(),
-        method: "GET".to_string(),
-        path: "/".to_string(),
-        headers: Vec::new(),
-        body: Vec::new(),
-    });
+    assert_eq!(
+        wire,
+        OnionHttpsRequest {
+            target: "example.com:443".to_string(),
+            method: "GET".to_string(),
+            path: "/".to_string(),
+            headers: Vec::new(),
+            body: Vec::new(),
+        }
+    );
 }
 
 #[test]
diff --git a/crates/node/src/onion/replay.rs b/crates/node/src/onion/replay.rs
index 541151398..ba0b1e2fc 100644
--- a/crates/node/src/onion/replay.rs
+++ b/crates/node/src/onion/replay.rs
@@ -76,7 +76,8 @@ impl Default for OnionReplayCache {
 }
 
 impl OnionReplayCache
-where K: Eq + Hash
+where
+    K: Eq + Hash,
 {
     #[cfg(test)]
     fn with_limits(max_entries: usize, ttl_ms: u128) -> Self {
diff --git a/crates/node/src/onion/route/tests/test_route_selection.rs b/crates/node/src/onion/route/tests/test_route_selection.rs
index 815ffc3d6..37f292d00 100644
--- a/crates/node/src/onion/route/tests/test_route_selection.rs
+++ b/crates/node/src/onion/route/tests/test_route_selection.rs
@@ -80,9 +80,12 @@ fn online_node_at(
     heartbeat_at_ms: u128,
     expires_at_ms: u128,
 ) -> CoreResult {
-    online_node_at_with_capabilities(session_sk, heartbeat_at_ms, expires_at_ms, vec![
-        ONION_RELAY_CAPABILITY.to_string(),
-    ])
+    online_node_at_with_capabilities(
+        session_sk,
+        heartbeat_at_ms,
+        expires_at_ms,
+        vec![ONION_RELAY_CAPABILITY.to_string()],
+    )
 }
 
 fn online_node_at_with_capabilities(
@@ -240,12 +243,14 @@ fn directory_candidates_reject_foreign_network_descriptors() -> Result<()> {
         test_dht_protocol(),
         50,
         route_request("web", 1, false)?.service_name(),
-        vec![
-            online_node_at_with_network_and_capabilities(&relay, 2, 20, 100, vec![
-                ONION_RELAY_CAPABILITY.to_string(),
-            ])
-            .map_err(Error::CoreError)?,
-        ],
+        vec![online_node_at_with_network_and_capabilities(
+            &relay,
+            2,
+            20,
+            100,
+            vec![ONION_RELAY_CAPABILITY.to_string()],
+        )
+        .map_err(Error::CoreError)?],
         vec![exit],
     );
 
diff --git a/crates/node/src/onion/tcp/mod.rs b/crates/node/src/onion/tcp/mod.rs
index 84b994728..63eac1e9c 100644
--- a/crates/node/src/onion/tcp/mod.rs
+++ b/crates/node/src/onion/tcp/mod.rs
@@ -130,11 +130,14 @@ impl NativeOnionCircuitHandle {
         let handler_session_sk = session_sk.clone();
         extensions.register(
             OnionCircuitProtocol::new(capabilities),
-            OnionCircuitShell::new(session_sk, NativeOnionCircuitHandler {
-                runtime: runtime.clone(),
-                https,
-                session_sk: handler_session_sk,
-            }),
+            OnionCircuitShell::new(
+                session_sk,
+                NativeOnionCircuitHandler {
+                    runtime: runtime.clone(),
+                    https,
+                    session_sk: handler_session_sk,
+                },
+            ),
         )?;
         Ok(Self {
             runtime,
@@ -273,9 +276,12 @@ impl OnionTcpRuntime {
                 return Err(error);
             }
         };
-        let open_payload = match encode_tcp_payload(&service, OnionTcpPayload::Open {
-            target: target.authority(),
-        }) {
+        let open_payload = match encode_tcp_payload(
+            &service,
+            OnionTcpPayload::Open {
+                target: target.authority(),
+            },
+        ) {
             Ok(payload) => payload,
             Err(error) => {
                 self.remove_client_stream(key);
diff --git a/crates/node/src/onion/tests/test_exit_registry.rs b/crates/node/src/onion/tests/test_exit_registry.rs
index 76addbf12..f055fa14c 100644
--- a/crates/node/src/onion/tests/test_exit_registry.rs
+++ b/crates/node/src/onion/tests/test_exit_registry.rs
@@ -59,10 +59,10 @@ fn signed_exit_for_session_at(
 
 #[test]
 fn default_exit_services_include_native_tcp_and_https() {
-    assert_eq!(default_onion_exit_services(), vec![
-        OnionExitService::tcp(),
-        OnionExitService::https()
-    ]);
+    assert_eq!(
+        default_onion_exit_services(),
+        vec![OnionExitService::tcp(), OnionExitService::https()]
+    );
     assert_eq!(https_onion_exit_services(), vec![OnionExitService::https()]);
 }
 
@@ -143,9 +143,10 @@ fn exit_policy_allow_list_controls_targets() -> Result<()> {
 
 #[test]
 fn exit_policy_wildcard_allows_all_targets_with_specific_denies() -> Result<()> {
-    let policy = OnionExitPolicy::from_target_strings(vec!["*:*".to_string()], vec![
-        "api.example.com:443".to_string(),
-    ])?;
+    let policy = OnionExitPolicy::from_target_strings(
+        vec!["*:*".to_string()],
+        vec!["api.example.com:443".to_string()],
+    )?;
     let google = OnionExitTarget::parse("google.com:443")?;
     let example = OnionExitTarget::parse("example.com:8443")?;
     let api = OnionExitTarget::parse("api.example.com:443")?;
diff --git a/crates/node/src/prelude.rs b/crates/node/src/prelude.rs
index b0d0e9f54..60cf74104 100644
--- a/crates/node/src/prelude.rs
+++ b/crates/node/src/prelude.rs
@@ -6,6 +6,8 @@ pub use rings_derive::wasm_export;
 pub use self::rings_core::chunk;
 pub use self::rings_core::dht::PeerRing;
 pub use self::rings_core::ecc::SecretKey;
+pub use self::rings_core::lifecycle::StopSource;
+pub use self::rings_core::lifecycle::StopToken;
 pub use self::rings_core::measure::PeerMeasurement;
 pub use self::rings_core::message::CustomMessage;
 pub use self::rings_core::message::Message;
diff --git a/crates/node/src/processor/builder.rs b/crates/node/src/processor/builder.rs
index 864457ebd..5d2981a86 100644
--- a/crates/node/src/processor/builder.rs
+++ b/crates/node/src/processor/builder.rs
@@ -142,7 +142,9 @@ impl ProcessorBuilder {
 
     /// Add a custom periodic registration task.
     pub fn registration_task(mut self, task: T) -> Self
-    where T: RegistrationTask + 'static {
+    where
+        T: RegistrationTask + 'static,
+    {
         self.registration_tasks.push(Arc::new(task));
         self
     }
diff --git a/crates/node/src/processor/config.rs b/crates/node/src/processor/config.rs
index 48292952c..e41b4e164 100644
--- a/crates/node/src/processor/config.rs
+++ b/crates/node/src/processor/config.rs
@@ -495,7 +495,9 @@ impl Serialize for ProcessorConfig {
 
 impl<'de> serde::de::Deserialize<'de> for ProcessorConfig {
     fn deserialize(deserializer: D) -> core::result::Result
-    where D: serde::Deserializer<'de> {
+    where
+        D: serde::Deserializer<'de>,
+    {
         match ProcessorConfigSerialized::deserialize(deserializer) {
             Ok(ins) => {
                 let cfg: ProcessorConfig = ins
diff --git a/crates/node/src/processor/mod.rs b/crates/node/src/processor/mod.rs
index 726d35d8e..58619a50a 100644
--- a/crates/node/src/processor/mod.rs
+++ b/crates/node/src/processor/mod.rs
@@ -14,6 +14,7 @@ use rings_core::dht::EntryStorage;
 use rings_core::dht::DEFAULT_FINGER_TABLE_SIZE;
 use rings_core::ecc::PublicKey;
 use rings_core::ecc::SecretKey;
+use rings_core::lifecycle::StopToken;
 use rings_core::measure::MeasureImpl;
 use rings_core::measure::PeerMeasurement;
 use rings_core::measure::PeerQuality;
@@ -357,12 +358,18 @@ impl Processor {
         }
     }
 
-    async fn registration_task_daemon(&self, task: &dyn RegistrationTask) {
+    async fn registration_task_daemon_with(&self, task: &dyn RegistrationTask, stop: StopToken) {
         loop {
+            if stop.should_stop() {
+                return;
+            }
             let timeout = registration_attempt_timeout(task.interval());
             if let Err(error) = self.run_registration_once_with_timeout(task, timeout).await {
                 tracing::warn!("Failed to run {} registration task: {error:?}", task.name());
             }
+            if stop.should_stop() {
+                return;
+            }
             if let Err(error) = sleep_registration_interval(task.interval()).await {
                 tracing::warn!(
                     "Stopping {} registration task after timer error: {error:?}",
@@ -373,11 +380,11 @@ impl Processor {
         }
     }
 
-    async fn registration_daemons(&self) {
+    async fn registration_daemons_with(&self, stop: StopToken) {
         join_all(
             self.registration_tasks
                 .iter()
-                .map(|task| self.registration_task_daemon(task.as_ref())),
+                .map(|task| self.registration_task_daemon_with(task.as_ref(), stop.clone())),
         )
         .await;
     }
@@ -386,14 +393,24 @@ impl Processor {
     ///
     /// This is a long-running task; do not await completion as a readiness signal.
     pub async fn listen(&self) {
+        self.listen_with(StopToken::never()).await;
+    }
+
+    /// Run stabilization and node registration tasks until `stop` asks them to exit.
+    ///
+    /// The shutdown is cooperative: it waits for the current stabilization or
+    /// registration operation to finish before returning. This avoids dropping
+    /// browser IndexedDB request futures while their JavaScript callbacks are
+    /// still pending.
+    pub async fn listen_with(&self, stop: StopToken) {
         let stabilizer = self.swarm.stabilizer();
         let stabilizer = Arc::new(stabilizer);
         if self.registration_tasks.is_empty() {
-            stabilizer.wait(self.stabilize_interval).await;
+            stabilizer.wait_with(self.stabilize_interval, stop).await;
         } else {
             let _ = futures::future::join(
-                stabilizer.wait(self.stabilize_interval),
-                self.registration_daemons(),
+                stabilizer.wait_with(self.stabilize_interval, stop.clone()),
+                self.registration_daemons_with(stop),
             )
             .await;
         }
diff --git a/crates/node/src/processor/tests/test_config.rs b/crates/node/src/processor/tests/test_config.rs
index 5e483eeb5..92b6613ab 100644
--- a/crates/node/src/processor/tests/test_config.rs
+++ b/crates/node/src/processor/tests/test_config.rs
@@ -300,10 +300,10 @@ fn default_onion_exit_config_uses_native_tcp_backed_services() {
 
     assert!(config.advertise_onion_exit);
     assert_eq!(config.onion_exit_services, default_onion_exit_services());
-    assert_eq!(config.onion_exit_services, vec![
-        OnionExitService::tcp(),
-        OnionExitService::https()
-    ]);
+    assert_eq!(
+        config.onion_exit_services,
+        vec![OnionExitService::tcp(), OnionExitService::https()]
+    );
 }
 
 #[test]
diff --git a/crates/node/src/processor/tests/test_network.rs b/crates/node/src/processor/tests/test_network.rs
index 8c767fc52..2eaf8c1a4 100644
--- a/crates/node/src/processor/tests/test_network.rs
+++ b/crates/node/src/processor/tests/test_network.rs
@@ -1,6 +1,20 @@
 use super::common::*;
 use super::*;
 
+#[tokio::test]
+async fn listen_with_pre_stopped_token_returns_before_first_tick() {
+    let processor = prepare_processor().await;
+    let stop = StopSource::new();
+    stop.request_stop();
+
+    tokio::time::timeout(
+        Duration::from_millis(100),
+        processor.listen_with(stop.token()),
+    )
+    .await
+    .expect("pre-stopped listen token should exit before the first stabilization tick");
+}
+
 #[tokio::test]
 async fn online_node_registry_lists_two_publishers_over_network() -> Result<()> {
     let _network_guard = network_test_guard().await;
@@ -200,9 +214,12 @@ async fn provider_exposes_sent_and_received_peer_measurements() {
     assert!(provider_measurement.evidence.sent >= 1);
 
     let rpc_value = provider
-        .request(Method::PeerMeasurement, PeerMeasurementRequest {
-            did: p2.did().to_string(),
-        })
+        .request(
+            Method::PeerMeasurement,
+            PeerMeasurementRequest {
+                did: p2.did().to_string(),
+            },
+        )
         .await
         .unwrap();
     let rpc_measurement: PeerMeasurementResponse = serde_json::from_value(rpc_value).unwrap();
diff --git a/crates/node/src/provider/mod.rs b/crates/node/src/provider/mod.rs
index 3c1200a99..34fd3e151 100644
--- a/crates/node/src/provider/mod.rs
+++ b/crates/node/src/provider/mod.rs
@@ -8,6 +8,8 @@ use std::sync::Mutex;
 
 use rings_core::dht::Did;
 use rings_core::dht::EntryStorage;
+#[cfg(feature = "node")]
+use rings_core::lifecycle::StopToken;
 use rings_core::measure::PeerMeasurement;
 use rings_core::session::SessionSkBuilder;
 use rings_core::storage::MemStorage;
@@ -288,6 +290,13 @@ impl Provider {
     pub async fn listen(&self) {
         self.processor.listen().await;
     }
+
+    /// Listen for messages until `stop` requests cooperative shutdown.
+    ///
+    /// This is a long-running task; do not await completion as a readiness signal.
+    pub async fn listen_with(&self, stop: StopToken) {
+        self.processor.listen_with(stop).await;
+    }
 }
 
 #[cfg(feature = "browser")]
diff --git a/crates/node/src/registration.rs b/crates/node/src/registration.rs
index 3c5f17078..43692ad8b 100644
--- a/crates/node/src/registration.rs
+++ b/crates/node/src/registration.rs
@@ -179,11 +179,7 @@ impl DhtRegistrationPublisher {
     ) -> Result<()> {
         let current_values = values.into_iter().collect::>();
         let mut published_values = self.published_values.lock().await;
-        let stale_values = published_values
-            .iter()
-            .filter(|published| !current_values.contains(*published))
-            .cloned()
-            .collect::>();
+        let stale_values = begin_registration_publish(&mut published_values, ¤t_values);
 
         for value in ¤t_values {
             context
@@ -198,11 +194,34 @@ impl DhtRegistrationPublisher {
                 .await?;
             published_values.remove(&stale_value);
         }
-        *published_values = current_values;
+        finish_registration_publish(&mut published_values, current_values);
         Ok(())
     }
 }
 
+fn begin_registration_publish(
+    published_values: &mut BTreeSet,
+    current_values: &BTreeSet,
+) -> Vec {
+    let stale_values = published_values
+        .iter()
+        .filter(|published| !current_values.contains(*published))
+        .cloned()
+        .collect::>();
+    // Invariant: every value whose touch may have reached storage is remembered
+    // before the first await. If the publish future is later cancelled by an
+    // attempt timeout, the next attempt can still tombstone the value.
+    published_values.extend(current_values.iter().cloned());
+    stale_values
+}
+
+fn finish_registration_publish(
+    published_values: &mut BTreeSet,
+    current_values: BTreeSet,
+) {
+    *published_values = current_values;
+}
+
 /// Periodic node-layer registration.
 #[cfg_attr(feature = "browser", async_trait(?Send))]
 #[cfg_attr(not(feature = "browser"), async_trait)]
@@ -343,3 +362,88 @@ impl RegistrationTask for OnlineNodeRegistration {
         self.publish_descriptor(context).await.map(|_| ())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeSet;
+
+    use rings_core::message::Encoded;
+
+    use super::*;
+
+    fn encoded(value: &str) -> Encoded {
+        value.into()
+    }
+
+    fn encoded_subset(mask: u8) -> BTreeSet {
+        ["a", "b", "c"]
+            .into_iter()
+            .enumerate()
+            .filter_map(|(bit, value)| (mask & (1 << bit) != 0).then(|| encoded(value)))
+            .collect()
+    }
+
+    #[test]
+    fn registration_publish_remembers_attempted_values_before_effects() {
+        let old = encoded("old");
+        let attempted = encoded("attempted");
+        let current = BTreeSet::from([attempted.clone()]);
+        let mut known = BTreeSet::from([old.clone()]);
+
+        let stale = begin_registration_publish(&mut known, ¤t);
+
+        assert_eq!(stale, vec![old.clone()]);
+        assert_eq!(known, BTreeSet::from([old, attempted]));
+    }
+
+    #[test]
+    fn registration_publish_retry_tombstones_values_from_cancelled_attempts() {
+        let old = encoded("old");
+        let cancelled = encoded("cancelled");
+        let replacement = encoded("replacement");
+        let mut known = BTreeSet::from([old.clone()]);
+
+        let cancelled_current = BTreeSet::from([cancelled.clone()]);
+        let _ = begin_registration_publish(&mut known, &cancelled_current);
+        let replacement_current = BTreeSet::from([replacement.clone()]);
+        let stale = begin_registration_publish(&mut known, &replacement_current);
+
+        assert_eq!(
+            stale.into_iter().collect::>(),
+            BTreeSet::from([old, cancelled])
+        );
+        assert!(known.contains(&replacement));
+        finish_registration_publish(&mut known, replacement_current.clone());
+        assert_eq!(known, replacement_current);
+    }
+
+    #[test]
+    fn registration_publish_begin_finish_preserve_known_set_law() {
+        for old_mask in 0..8 {
+            for current_mask in 0..8 {
+                for replacement_mask in 0..8 {
+                    let old = encoded_subset(old_mask);
+                    let current = encoded_subset(current_mask);
+                    let replacement = encoded_subset(replacement_mask);
+                    let mut known = old.clone();
+
+                    let _ = begin_registration_publish(&mut known, ¤t);
+                    let attempted = old.union(¤t).cloned().collect::>();
+                    assert_eq!(known, attempted);
+
+                    let stale = begin_registration_publish(&mut known, &replacement)
+                        .into_iter()
+                        .collect::>();
+                    let expected_stale = attempted
+                        .difference(&replacement)
+                        .cloned()
+                        .collect::>();
+                    assert_eq!(stale, expected_stale);
+
+                    finish_registration_publish(&mut known, replacement.clone());
+                    assert_eq!(known, replacement);
+                }
+            }
+        }
+    }
+}
diff --git a/crates/node/src/tests/native/test_snark.rs b/crates/node/src/tests/native/test_snark.rs
index 8980315d7..6effcd224 100644
--- a/crates/node/src/tests/native/test_snark.rs
+++ b/crates/node/src/tests/native/test_snark.rs
@@ -12,10 +12,13 @@ pub async fn test_gen_proof_and_verify() {
     .await
     .unwrap();
     type F = crate::extension::snark::Field;
-    let input: Input = vec![("step_in".to_string(), vec![
-        F::from_u64(4u64, SupportedPrimeField::Vesta),
-        F::from_u64(2u64, SupportedPrimeField::Vesta),
-    ])]
+    let input: Input = vec![(
+        "step_in".to_string(),
+        vec![
+            F::from_u64(4u64, SupportedPrimeField::Vesta),
+            F::from_u64(2u64, SupportedPrimeField::Vesta),
+        ],
+    )]
     .into();
     let circuits = snark_task_builder.gen_circuits(input, vec![], 5).unwrap();
     assert_eq!(circuits.len(), 5);
diff --git a/crates/node/src/tests/wasm/test_snark.rs b/crates/node/src/tests/wasm/test_snark.rs
index 74b06cf03..734999376 100644
--- a/crates/node/src/tests/wasm/test_snark.rs
+++ b/crates/node/src/tests/wasm/test_snark.rs
@@ -43,10 +43,13 @@ async fn test_send_snark_backend_message() {
     .await
     .unwrap();
     type F = crate::extension::snark::Field;
-    let input: Input = vec![("step_in".to_string(), vec![
-        F::from_u64(4u64, SupportedPrimeField::Vesta),
-        F::from_u64(2u64, SupportedPrimeField::Vesta),
-    ])]
+    let input: Input = vec![(
+        "step_in".to_string(),
+        vec![
+            F::from_u64(4u64, SupportedPrimeField::Vesta),
+            F::from_u64(2u64, SupportedPrimeField::Vesta),
+        ],
+    )]
     .into();
     console_log!("gen circuit");
     let circuits = snark_task_builder.gen_circuits(input, vec![], 5).unwrap();
diff --git a/crates/node/src/util.rs b/crates/node/src/util.rs
index c8b2756e0..0a98cbf37 100644
--- a/crates/node/src/util.rs
+++ b/crates/node/src/util.rs
@@ -74,7 +74,9 @@ pub fn build_version() -> String {
 /// Expand path with "~" to absolute path.
 #[cfg(feature = "node")]
 pub fn expand_home
(path: P) -> Result
-where P: AsRef {
+where
+    P: AsRef,
+{
     let Ok(stripped) = path.as_ref().strip_prefix("~") else {
         return Ok(path.as_ref().to_path_buf());
     };
@@ -91,7 +93,9 @@ where P: AsRef {
 /// Create parent directory of a path if not exists.
 #[cfg(feature = "node")]
 pub fn ensure_parent_dir
(path: P) -> Result<(), Error>
-where P: AsRef {
+where
+    P: AsRef,
+{
     let path = expand_home(path)?;
     let parent = path.parent().ok_or(Error::ParentDirError)?;
     if !parent.is_dir() {
@@ -116,7 +120,9 @@ pub mod loader {
     pub trait ResourceLoader {
         /// Load config from local file or remote url.
         async fn load(source: &str) -> anyhow::Result
-        where Self: Sized + DeserializeOwned {
+        where
+            Self: Sized + DeserializeOwned,
+        {
             let url = Url::parse(source).map_err(|e| anyhow::anyhow!("{}", e))?;
 
             if let Ok(path) = url.to_file_path() {
diff --git a/crates/rpc/src/jsonrpc.rs b/crates/rpc/src/jsonrpc.rs
index f9b8d3055..17fc0cfa8 100644
--- a/crates/rpc/src/jsonrpc.rs
+++ b/crates/rpc/src/jsonrpc.rs
@@ -47,7 +47,9 @@ impl Client {
 
     /// Sends a typed JSON-RPC request and decodes the typed response body.
     pub async fn call_method(&self, method: Method, req: &impl Serialize) -> Result
-    where T: DeserializeOwned {
+    where
+        T: DeserializeOwned,
+    {
         use jsonrpc_core::*;
 
         let params = serde_json::to_value(req)
diff --git a/crates/snark/src/circuit/bellman.rs b/crates/snark/src/circuit/bellman.rs
index 57f27b606..ff1c2b414 100644
--- a/crates/snark/src/circuit/bellman.rs
+++ b/crates/snark/src/circuit/bellman.rs
@@ -13,7 +13,8 @@ use crate::prelude::bellman::Variable;
 /// 
 /// aux bias and input map are removed
 impl bellman::Circuit for Circuit
-where E::Fr: ff::PrimeField
+where
+    E::Fr: ff::PrimeField,
 {
     //noinspection RsBorrowChecker
     fn synthesize>(self, cs: &mut CS) -> Result<(), SynthesisError> {
diff --git a/crates/snark/src/circuit/mod.rs b/crates/snark/src/circuit/mod.rs
index 0e5a25a48..db0d8933a 100644
--- a/crates/snark/src/circuit/mod.rs
+++ b/crates/snark/src/circuit/mod.rs
@@ -104,10 +104,13 @@ pub struct Circuit {
 }
 
 impl<'de, F> Deserialize<'de> for Circuit
-where F: PrimeField + Deserialize<'de>
+where
+    F: PrimeField + Deserialize<'de>,
 {
     fn deserialize(deserializer: D) -> core::result::Result
-    where D: Deserializer<'de> {
+    where
+        D: Deserializer<'de>,
+    {
         #[derive(Deserialize)]
         #[serde(bound(deserialize = "F: Deserialize<'de>"))]
         struct CircuitData {
@@ -144,7 +147,9 @@ impl WasmCircuitGenerator {
     /// Generate iterator circuit list
     /// Which iterate inputs and generate circuit
     pub fn gen_circuit(&self, input: Input, sanity_check: bool) -> Result>
-    where F: PrimeField {
+    where
+        F: PrimeField,
+    {
         let mut calc = self.calculator.borrow_mut();
         let witness: Vec = calc.calculate_witness::(input.to_vec(), sanity_check)?;
         Circuit::::try_new(self.r1cs.clone(), witness)
diff --git a/crates/snark/src/tests/native/test_snark.rs b/crates/snark/src/tests/native/test_snark.rs
index b50c524b5..5d4b71cef 100644
--- a/crates/snark/src/tests/native/test_snark.rs
+++ b/crates/snark/src/tests/native/test_snark.rs
@@ -89,10 +89,12 @@ pub async fn test_calcu_sha256_recursive_snark() -> Result<()> {
     print_mem_status(Some("after gen pp"));
     let first_recursive = first_circuit(&recursive_circuits)?;
     let first_public_inputs = first_recursive.get_public_inputs()?;
-    let mut rec_snark =
-        snark::SNARK::::new(first_recursive, &pp, &first_public_inputs, &vec![F2::from(
-            0,
-        )])?;
+    let mut rec_snark = snark::SNARK::::new(
+        first_recursive,
+        &pp,
+        &first_public_inputs,
+        &vec![F2::from(0)],
+    )?;
     print_mem_status(Some("after gen recursive snark"));
     for c in recursive_circuits {
         rec_snark.foldr(&pp, &c)?;
@@ -121,9 +123,12 @@ pub async fn test_calcu_sha256_recursive_snark() -> Result<()> {
         rec_snark.foldr(&pp, &c)?;
     }
     print_mem_status(Some("after foldr circuits"));
-    let (_z0, _) = rec_snark.verify(&pp, round + round2, &input_inner.clone(), &vec![F2::from(
-        0,
-    )])?;
+    let (_z0, _) = rec_snark.verify(
+        &pp,
+        round + round2,
+        &input_inner.clone(),
+        &vec![F2::from(0)],
+    )?;
     print_mem_status(Some("after verify"));
     Ok(())
 }
@@ -174,25 +179,32 @@ pub async fn test_calcu_bn256_recursive_snark_with_private_input() -> Result<()>
     let pp = snark::SNARK::::gen_pp::(circuit_0.clone())?;
     let first_recursive = first_circuit(&recursive_circuits)?;
     let first_public_inputs = first_recursive.get_public_inputs()?;
-    let mut rec_snark_iter =
-        snark::SNARK::::new(first_recursive, &pp, &first_public_inputs, vec![F2::from(
-            0,
-        )])?;
+    let mut rec_snark_iter = snark::SNARK::::new(
+        first_recursive,
+        &pp,
+        &first_public_inputs,
+        vec![F2::from(0)],
+    )?;
 
     for c in recursive_circuits {
         rec_snark_iter.foldr(&pp, &c)?;
     }
-    rec_snark_iter.verify(&pp, 3, &vec![F1::from(4u64), F1::from(2u64)], &vec![
-        F2::from(0),
-    ])?;
+    rec_snark_iter.verify(
+        &pp,
+        3,
+        &vec![F1::from(4u64), F1::from(2u64)],
+        &vec![F2::from(0)],
+    )?;
     println!("success on create recursive snark");
     let (pk, vk) = snark::SNARK::::compress_setup::(&pp)?;
 
     let compress_snark = rec_snark_iter.compress_prove::(&pp, &pk)?;
-    let ret = snark::SNARK::::compress_verify::(compress_snark, &vk, 3, &vec![
-        F1::from(4u64),
-        F1::from(2u64),
-    ]);
+    let ret = snark::SNARK::::compress_verify::(
+        compress_snark,
+        &vk,
+        3,
+        &vec![F1::from(4u64), F1::from(2u64)],
+    );
     assert!(ret.is_ok());
     Ok(())
 }
diff --git a/crates/snark/src/tests/native/test_wat.rs b/crates/snark/src/tests/native/test_wat.rs
index ec70595b6..1ff77de72 100644
--- a/crates/snark/src/tests/native/test_wat.rs
+++ b/crates/snark/src/tests/native/test_wat.rs
@@ -91,10 +91,13 @@ fn u256_from_vec_u32_rejects_invalid_word_count(
     };
 
     assert!(
-        matches!(error, Error::WitnessInvalidU256WordLength {
-            expected: 8,
-            actual: 3
-        }),
+        matches!(
+            error,
+            Error::WitnessInvalidU256WordLength {
+                expected: 8,
+                actual: 3
+            }
+        ),
         "{error:?}"
     );
     Ok(())
diff --git a/crates/snark/src/witness/circom.rs b/crates/snark/src/witness/circom.rs
index 4049713fe..a3e957b90 100644
--- a/crates/snark/src/witness/circom.rs
+++ b/crates/snark/src/witness/circom.rs
@@ -219,12 +219,15 @@ impl CircomBase for Wasm {
         hash_lsb: u32,
     ) -> Result<()> {
         let func = self.func("getSignalOffset32")?;
-        func.call(store, &[
-            p_sig_offset.into(),
-            component.into(),
-            hash_msb.into(),
-            hash_lsb.into(),
-        ])?;
+        func.call(
+            store,
+            &[
+                p_sig_offset.into(),
+                component.into(),
+                hash_msb.into(),
+                hash_lsb.into(),
+            ],
+        )?;
 
         Ok(())
     }
@@ -238,12 +241,10 @@ impl CircomBase for Wasm {
         p_val: u32,
     ) -> Result<()> {
         let func = self.func("setSignal")?;
-        func.call(store, &[
-            c_idx.into(),
-            component.into(),
-            signal.into(),
-            p_val.into(),
-        ])?;
+        func.call(
+            store,
+            &[c_idx.into(), component.into(), signal.into(), p_val.into()],
+        )?;
 
         Ok(())
     }
diff --git a/crates/transport/src/connections/dummy/mod.rs b/crates/transport/src/connections/dummy/mod.rs
index 1b8f08b9a..9436f1ded 100644
--- a/crates/transport/src/connections/dummy/mod.rs
+++ b/crates/transport/src/connections/dummy/mod.rs
@@ -70,6 +70,15 @@ thread_local! {
     /// Test-only per-thread switch that makes `webrtc_wait_for_data_channel_open` stay pending.
     /// This models a lifecycle notifier/callback wedge after a connection was already admitted.
     static WAIT_FOR_DATA_CHANNEL_OPEN_PENDING: Cell = const { Cell::new(false) };
+    /// Test-only per-thread switch that makes `send_message` stay pending after
+    /// the data channel is already open.
+    static SEND_MESSAGE_PENDING: Cell = const { Cell::new(false) };
+    /// Test-only per-thread threshold that makes `send_message` stay pending after
+    /// this many messages have already been dispatched.
+    static SEND_MESSAGE_PENDING_AFTER_SENT_COUNT: Cell> = const { Cell::new(None) };
+    /// Test-only per-thread switch that makes `send_message` report local success
+    /// without dispatching the message to the remote callback.
+    static DROP_MESSAGES: Cell = const { Cell::new(false) };
 }
 
 /// Test-only controlled delivery scheduler. When enabled (per thread), dummy
@@ -81,8 +90,11 @@ pub mod controlled {
     use super::CONNS;
     use super::CONTROLLED;
     use super::DELIVERY;
+    use super::DROP_MESSAGES;
     use super::MAX_MESSAGE_SIZE;
     use super::NEXT_CALLBACK_CID;
+    use super::SEND_MESSAGE_PENDING;
+    use super::SEND_MESSAGE_PENDING_AFTER_SENT_COUNT;
     use super::WAIT_FOR_DATA_CHANNEL_OPEN_PENDING;
 
     /// Turn the controlled scheduler on/off for the current thread. Turning it
@@ -95,6 +107,9 @@ pub mod controlled {
                 *next.borrow_mut() = None;
             });
             WAIT_FOR_DATA_CHANNEL_OPEN_PENDING.with(|pending| pending.set(false));
+            SEND_MESSAGE_PENDING.with(|pending| pending.set(false));
+            SEND_MESSAGE_PENDING_AFTER_SENT_COUNT.with(|threshold| threshold.set(None));
+            DROP_MESSAGES.with(|drop| drop.set(false));
         }
     }
 
@@ -119,6 +134,24 @@ pub mod controlled {
         WAIT_FOR_DATA_CHANNEL_OPEN_PENDING.with(|pending| pending.set(on));
     }
 
+    /// Test hook: force `send_message` to stay pending after the data channel is open.
+    pub fn set_send_message_pending(on: bool) {
+        SEND_MESSAGE_PENDING.with(|pending| pending.set(on));
+    }
+
+    /// Test hook: force `send_message` to stay pending once this thread has already dispatched
+    /// `threshold` messages. `None` disables the hook.
+    pub fn set_send_message_pending_after_sent_count(threshold: Option) {
+        SEND_MESSAGE_PENDING_AFTER_SENT_COUNT.with(|pending_after| pending_after.set(threshold));
+    }
+
+    /// Test hook: make dummy sends disappear while still returning a successful
+    /// local send. This models a silent remote failure where the local data
+    /// channel remains open and `Connected`.
+    pub fn set_drop_messages(on: bool) {
+        DROP_MESSAGES.with(|drop| drop.set(on));
+    }
+
     /// Test hook: number of data-channel messages `send_message` has dispatched on this thread.
     /// Paired with [`reset_sent_count`] to assert that a failed send enqueued nothing.
     pub fn sent_count() -> usize {
@@ -357,9 +390,22 @@ impl ConnectionInterface for DummyConnection {
 
     async fn send_message(&self, msg: TransportMessage) -> Result {
         self.webrtc_wait_for_data_channel_open().await?;
+        if SEND_MESSAGE_PENDING.with(|pending| pending.get())
+            || SEND_MESSAGE_PENDING_AFTER_SENT_COUNT.with(|threshold| {
+                threshold
+                    .get()
+                    .map(|count| SENT_COUNT.with(|sent| sent.get()) >= count)
+                    .unwrap_or(false)
+            })
+        {
+            std::future::pending::<()>().await;
+        }
         SENT_COUNT.with(|c| c.set(c.get() + 1));
 
         let data = bincode::serialize(&msg).map(Bytes::from)?;
+        if DROP_MESSAGES.with(|drop| drop.get()) {
+            return Ok(Box::pin(async { Ok(()) }));
+        }
         // The remote connection may have been torn down between the data
         // channel check and here (the dummy analogue of sending on a channel
         // that just closed). Mimic a real transport: fail gracefully instead of
diff --git a/crates/transport/src/connections/native_webrtc/mod.rs b/crates/transport/src/connections/native_webrtc/mod.rs
index 16fdda16b..1421ec2af 100644
--- a/crates/transport/src/connections/native_webrtc/mod.rs
+++ b/crates/transport/src/connections/native_webrtc/mod.rs
@@ -1,3 +1,4 @@
+use std::net::IpAddr;
 use std::sync::atomic::AtomicU64;
 use std::sync::atomic::AtomicUsize;
 use std::sync::atomic::Ordering;
@@ -6,6 +7,7 @@ use std::time::Duration;
 
 use async_trait::async_trait;
 use bytes::Bytes;
+use tokio::sync::mpsc;
 use tokio::sync::Mutex;
 use tokio_util::sync::CancellationToken;
 use webrtc::data_channel::data_channel_message::DataChannelMessage;
@@ -66,6 +68,101 @@ const DELIVERY_POLL_INTERVAL: Duration = Duration::from_millis(300);
 /// later message's bytes.
 type TrackedChannel = (Arc, Arc, Arc>);
 
+fn sdp_candidate_count(sdp: &str) -> usize {
+    sdp.lines()
+        .filter(|line| line.starts_with("a=candidate:"))
+        .count()
+}
+
+fn external_address_candidates(external_address: Option<&str>) -> Vec {
+    let Some(external_address) = external_address else {
+        return Vec::new();
+    };
+
+    let mut candidates = Vec::new();
+    for candidate in external_address.split(',') {
+        let candidate = candidate.trim();
+        if candidate.is_empty() || candidates.iter().any(|seen| seen == candidate) {
+            continue;
+        }
+        candidates.push(candidate.to_string());
+    }
+    candidates
+}
+
+fn is_loopback_address(candidate: &str) -> bool {
+    candidate
+        .parse::()
+        .map(|addr| addr.is_loopback())
+        .unwrap_or(false)
+}
+
+fn nat_1to1_host_candidates(candidates: &[String]) -> Vec {
+    candidates
+        .iter()
+        .filter(|candidate| !is_loopback_address(candidate))
+        .cloned()
+        .collect()
+}
+
+fn sdp_extra_host_candidates(candidates: &[String]) -> Vec {
+    candidates
+        .iter()
+        .filter(|candidate| is_loopback_address(candidate))
+        .cloned()
+        .collect()
+}
+
+fn duplicate_host_candidate_line(line: &str, extra_addresses: &[String]) -> Vec {
+    if !line.starts_with("a=candidate:") {
+        return Vec::new();
+    }
+
+    let fields = line.split_whitespace().collect::>();
+    if fields.len() < 8 || fields[6] != "typ" || fields[7] != "host" {
+        return Vec::new();
+    }
+
+    extra_addresses
+        .iter()
+        .filter(|candidate| candidate.as_str() != fields[4])
+        .map(|candidate| {
+            let mut duplicate = fields
+                .iter()
+                .map(|field| field.to_string())
+                .collect::>();
+            duplicate[4] = candidate.clone();
+            duplicate.join(" ")
+        })
+        .collect()
+}
+
+fn append_sdp_extra_host_candidates(sdp: String, extra_addresses: &[String]) -> String {
+    if extra_addresses.is_empty() {
+        return sdp;
+    }
+
+    let mut output = String::with_capacity(sdp.len());
+    for segment in sdp.split_inclusive('\n') {
+        output.push_str(segment);
+
+        let line = segment.trim_end_matches(['\r', '\n']);
+        let line_ending = if segment.ends_with("\r\n") {
+            "\r\n"
+        } else if segment.ends_with('\n') {
+            "\n"
+        } else {
+            ""
+        };
+        for duplicate in duplicate_host_candidate_line(line, extra_addresses) {
+            output.push_str(&duplicate);
+            output.push_str(line_ending);
+        }
+    }
+
+    output
+}
+
 /// Build the future that resolves once the message ending at `end_offset` on
 /// this channel has been flushed to the wire, or errors if the channel closes
 /// first. It re-checks on a timer, driving its own wake-ups.
@@ -131,6 +228,7 @@ pub struct WebrtcConnection {
     webrtc_data_channel: Arc>,
     webrtc_data_channel_state_notifier: Notifier,
     cancel_token: CancellationToken,
+    sdp_extra_host_candidates: Vec,
     /// Negotiated SCTP `max_message_size` (RFC 8841), parsed from the remote SDP at handshake.
     /// `0` means not yet negotiated. webrtc-rs exposes no getter, so we track it ourselves.
     remote_max_message_size: Arc,
@@ -150,18 +248,22 @@ impl WebrtcConnection {
         webrtc_conn: RTCPeerConnection,
         webrtc_data_channel: Arc>,
         webrtc_data_channel_state_notifier: Notifier,
+        sdp_extra_host_candidates: Vec,
     ) -> Self {
         Self {
             webrtc_conn,
             webrtc_data_channel,
             webrtc_data_channel_state_notifier,
             cancel_token: CancellationToken::new(),
+            sdp_extra_host_candidates,
             remote_max_message_size: Arc::new(AtomicUsize::new(0)),
         }
     }
 
-    async fn webrtc_gather(&self) -> Result {
-        let mut gathering_complete_promise = self.webrtc_conn.gathering_complete_promise().await;
+    async fn webrtc_gather(
+        &self,
+        mut gathering_complete_promise: mpsc::Receiver<()>,
+    ) -> Result {
         let gathering_complete_promise_with_timeout = tokio::time::timeout(
             std::time::Duration::from_secs(WEBRTC_GATHER_TIMEOUT.into()),
             gathering_complete_promise.recv(),
@@ -171,17 +273,40 @@ impl WebrtcConnection {
             _ = self.cancel_token.cancelled() => {
                 return Err(Error::WebrtcLocalSdpGenerationError("Local connection closed".to_string()))
             }
-            _ = gathering_complete_promise_with_timeout => {}
+            result = gathering_complete_promise_with_timeout => {
+                if result.is_err() {
+                    return Err(Error::WebrtcLocalSdpGenerationError(format!(
+                        "Webrtc gathering is not completed in {WEBRTC_GATHER_TIMEOUT} seconds"
+                    )));
+                }
+            }
         }
 
-        Ok(self
+        let sdp = self
             .webrtc_conn
             .local_description()
             .await
             .ok_or(Error::WebrtcLocalSdpGenerationError(
                 "Failed to get local description".to_string(),
             ))?
-            .sdp)
+            .sdp;
+        let sdp = append_sdp_extra_host_candidates(sdp, &self.sdp_extra_host_candidates);
+
+        let candidate_count = sdp_candidate_count(&sdp);
+        if candidate_count == 0 {
+            tracing::warn!(
+                sdp_bytes = sdp.len(),
+                "WebRTC local SDP has no ICE candidates after gathering"
+            );
+        } else {
+            tracing::debug!(
+                sdp_bytes = sdp.len(),
+                candidate_count,
+                "WebRTC ICE gathering complete"
+            );
+        }
+
+        Ok(sdp)
     }
 }
 
@@ -258,11 +383,12 @@ impl ConnectionInterface for WebrtcConnection {
 
     async fn webrtc_create_offer(&self) -> Result {
         let setting_offer = self.webrtc_conn.create_offer(None).await?;
+        let gathering_complete_promise = self.webrtc_conn.gathering_complete_promise().await;
         self.webrtc_conn
             .set_local_description(setting_offer.clone())
             .await?;
 
-        self.webrtc_gather().await
+        self.webrtc_gather(gathering_complete_promise).await
     }
 
     async fn webrtc_answer_offer(&self, offer: Self::Sdp) -> Result {
@@ -275,10 +401,11 @@ impl ConnectionInterface for WebrtcConnection {
         self.webrtc_conn.set_remote_description(offer).await?;
 
         let answer = self.webrtc_conn.create_answer(None).await?;
+        let gathering_complete_promise = self.webrtc_conn.gathering_complete_promise().await;
         self.webrtc_conn
             .set_local_description(answer.clone())
             .await?;
-        let local_sdp = self.webrtc_gather().await?;
+        let local_sdp = self.webrtc_gather(gathering_complete_promise).await?;
 
         self.remote_max_message_size
             .store(negotiated_max_message_size, Ordering::SeqCst);
@@ -359,13 +486,25 @@ impl TransportInterface for WebrtcTransport {
 
         let mut setting = webrtc::api::setting_engine::SettingEngine::default();
         set_udp_network_range(&mut setting, self.udp_port_range)?;
-        if let Some(ref addr) = self.external_address {
-            tracing::debug!("setting external ip {:?}", addr);
-            setting.set_nat_1to1_ips(vec![addr.to_string()], RTCIceCandidateType::Host);
+        let external_addresses = external_address_candidates(self.external_address.as_deref());
+        let nat_host_candidates = nat_1to1_host_candidates(&external_addresses);
+        let sdp_extra_host_candidates = sdp_extra_host_candidates(&external_addresses);
+        if nat_host_candidates.is_empty() {
             setting.set_ice_multicast_dns_mode(MulticastDnsMode::Disabled);
         } else {
+            tracing::debug!(
+                external_addresses = ?nat_host_candidates,
+                "setting external WebRTC host candidates"
+            );
+            setting.set_nat_1to1_ips(nat_host_candidates, RTCIceCandidateType::Host);
             setting.set_ice_multicast_dns_mode(MulticastDnsMode::Disabled);
         }
+        if !sdp_extra_host_candidates.is_empty() {
+            tracing::debug!(
+                extra_host_candidates = ?sdp_extra_host_candidates,
+                "will append SDP-only WebRTC host candidates"
+            );
+        }
 
         let webrtc_api = webrtc::api::APIBuilder::new()
             .with_setting_engine(setting)
@@ -392,16 +531,25 @@ impl TransportInterface for WebrtcTransport {
             let d_label = d.label();
             let d_id = d.id();
             tracing::debug!("New DataChannel {d_label} {d_id}");
-            // Open/close are detected on the channels we create (the pool, wired
-            // below); a received channel only carries inbound messages. Wiring
-            // open/close here too would fire on_data_channel_open twice (created
-            // + received) and churn join_dht.
+            // Open is admitted on channels we create (the pool, wired below).
+            // Close must also be observed on received channels: the answerer may
+            // never see close on its locally-created channels when the initiator's
+            // channels are the ones carrying traffic.
+            let on_close_inner_cb = data_channel_inner_cb.clone();
+            d.on_close(Box::new(move || {
+                let cb = on_close_inner_cb.clone();
+                Box::pin(async move {
+                    cb.on_data_channel_close().await;
+                })
+            }));
+
             let on_message_inner_cb = data_channel_inner_cb.clone();
             d.on_message(Box::new(move |msg: DataChannelMessage| {
                 tracing::debug!(
-                    "Received DataChannelMessage from {}: {:?}",
-                    on_message_inner_cb.cid,
-                    msg
+                    peer = %on_message_inner_cb.cid,
+                    is_string = msg.is_string,
+                    bytes = msg.data.len(),
+                    "Received DataChannelMessage"
                 );
 
                 let inner_cb = on_message_inner_cb.clone();
@@ -474,6 +622,7 @@ impl TransportInterface for WebrtcTransport {
             webrtc_conn,
             channel_pool,
             webrtc_data_channel_state_notifier,
+            sdp_extra_host_candidates,
         );
 
         self.pool.safely_insert(cid, conn)?;
@@ -561,4 +710,44 @@ mod tests {
 
         assert_eq!(transport.udp_port_range, Some(range));
     }
+
+    #[test]
+    fn external_address_candidates_split_trim_and_deduplicate() {
+        let candidates = external_address_candidates(Some(" 127.0.0.1, 192.168.215.2,127.0.0.1, "));
+
+        assert_eq!(
+            candidates,
+            vec!["127.0.0.1".to_string(), "192.168.215.2".to_string()]
+        );
+    }
+
+    #[test]
+    fn external_address_candidates_ignore_blank_config() {
+        assert!(external_address_candidates(Some("  ,  ")).is_empty());
+        assert!(external_address_candidates(None).is_empty());
+    }
+
+    #[test]
+    fn loopback_external_addresses_are_sdp_only_candidates() {
+        let candidates = vec!["127.0.0.1".to_string(), "192.168.215.2".to_string()];
+
+        assert_eq!(nat_1to1_host_candidates(&candidates), vec!["192.168.215.2"]);
+        assert_eq!(sdp_extra_host_candidates(&candidates), vec!["127.0.0.1"]);
+    }
+
+    #[test]
+    fn append_sdp_extra_host_candidates_duplicates_host_candidates() {
+        let sdp = "v=0\r\n\
+a=candidate:1 1 udp 2130706431 192.168.215.2 49160 typ host\r\n\
+a=end-of-candidates\r\n"
+            .to_string();
+
+        let rewritten = append_sdp_extra_host_candidates(sdp, &["127.0.0.1".to_string()]);
+
+        assert!(rewritten.contains(
+            "a=candidate:1 1 udp 2130706431 192.168.215.2 49160 typ host\r\n\
+a=candidate:1 1 udp 2130706431 127.0.0.1 49160 typ host\r\n"
+        ));
+        assert!(rewritten.ends_with("a=end-of-candidates\r\n"));
+    }
 }
diff --git a/crates/transport/src/connections/web_sys_webrtc/mod.rs b/crates/transport/src/connections/web_sys_webrtc/mod.rs
index c44efd9c5..f7544dd5a 100644
--- a/crates/transport/src/connections/web_sys_webrtc/mod.rs
+++ b/crates/transport/src/connections/web_sys_webrtc/mod.rs
@@ -387,10 +387,21 @@ impl TransportInterface for WebSysWebrtcTransport {
             let d = ev.channel();
             let d_label = d.label();
             tracing::debug!("New DataChannel {d_label}");
-            // Open/close are detected on the channels we create (the pool, wired
-            // below); a received channel only carries inbound messages. Wiring
-            // open/close here too would fire on_data_channel_open twice (created
-            // + received) and churn join_dht.
+            // Open is admitted on channels we create (the pool, wired below).
+            // Close must also be observed on received channels: the answerer may
+            // never see close on its locally-created channels when the initiator's
+            // channels are the ones carrying traffic.
+            let on_close_inner_cb = data_channel_inner_cb.clone();
+            let on_close = Box::new(move || {
+                let cb = on_close_inner_cb.clone();
+                spawn_local(async move {
+                    cb.on_data_channel_close().await;
+                });
+            });
+            let c = Closure::wrap(on_close as Box);
+            d.set_onclose(Some(c.as_ref().unchecked_ref()));
+            c.forget();
+
             let on_message_inner_cb = data_channel_inner_cb.clone();
             let on_message = Box::new(move |ev: MessageEvent| {
                 let data = ev.data();
@@ -425,9 +436,9 @@ impl TransportInterface for WebSysWebrtcTransport {
                     }
 
                     tracing::debug!(
-                        "Received DataChannelMessage from {}: {:?}",
-                        inner_cb.cid,
-                        data
+                        peer = %inner_cb.cid,
+                        bytes = msg.len(),
+                        "Received DataChannelMessage"
                     );
 
                     inner_cb.on_message(&msg.into()).await;
diff --git a/crates/transport/src/core/sdp.rs b/crates/transport/src/core/sdp.rs
index 0e00132f3..9ff50bc09 100644
--- a/crates/transport/src/core/sdp.rs
+++ b/crates/transport/src/core/sdp.rs
@@ -232,16 +232,19 @@ mod tests {
     #[test]
     fn lex_splits_type_and_value_and_drops_junk() {
         let lines: Vec = lex("v=0\r\na=sendrecv\r\n\r\nnonsense\r\n").collect();
-        assert_eq!(lines, vec![
-            Line {
-                kind: 'v',
-                value: "0"
-            },
-            Line {
-                kind: 'a',
-                value: "sendrecv"
-            },
-        ]);
+        assert_eq!(
+            lines,
+            vec![
+                Line {
+                    kind: 'v',
+                    value: "0"
+                },
+                Line {
+                    kind: 'a',
+                    value: "sendrecv"
+                },
+            ]
+        );
     }
 
     #[test]
@@ -269,20 +272,26 @@ mod tests {
                    a=max-message-size:65536\r\n";
         let ast = parse(sdp);
         // the pre-`m=` attribute is session-level (and `group:…` parses as a key:value pair)
-        assert_eq!(ast.session_attrs, vec![Attribute::Pair {
-            key: "group",
-            value: "BUNDLE 0"
-        }]);
+        assert_eq!(
+            ast.session_attrs,
+            vec![Attribute::Pair {
+                key: "group",
+                value: "BUNDLE 0"
+            }]
+        );
         // the post-`m=` attribute is media-level under the data-channel section
         assert_eq!(ast.media.len(), 1);
         assert_eq!(
             ast.media[0].media,
             "application 9 UDP/DTLS/SCTP webrtc-datachannel"
         );
-        assert_eq!(ast.media[0].attrs, vec![Attribute::Pair {
-            key: "max-message-size",
-            value: "65536"
-        }]);
+        assert_eq!(
+            ast.media[0].attrs,
+            vec![Attribute::Pair {
+                key: "max-message-size",
+                value: "65536"
+            }]
+        );
     }
 
     #[test]
diff --git a/crates/transport/src/ice_server.rs b/crates/transport/src/ice_server.rs
index 411614161..f0ebfb812 100644
--- a/crates/transport/src/ice_server.rs
+++ b/crates/transport/src/ice_server.rs
@@ -53,6 +53,11 @@ impl IceServer {
     feature = "web-sys-webrtc"
 ))]
 pub(crate) fn parse_ice_servers_or_warn(config: &str, transport: &str) -> Vec {
+    let config = config.trim();
+    if config.is_empty() {
+        return Vec::new();
+    }
+
     match IceServer::vec_from_str(config) {
         Ok(ice_servers) => ice_servers,
         Err(error) => {
@@ -112,7 +117,7 @@ impl FromStr for IceServer {
 mod test {
     use std::str::FromStr;
 
-    use super::IceServer;
+    use super::*;
 
     #[test]
     fn test_parsing() {
@@ -151,4 +156,15 @@ mod test {
         let parsed = IceServer::from_str("stun:///missing-host");
         assert!(parsed.is_err());
     }
+
+    #[cfg(any(
+        feature = "dummy",
+        feature = "native-webrtc",
+        feature = "web-sys-webrtc"
+    ))]
+    #[test]
+    fn blank_ice_server_config_means_no_servers() {
+        assert!(parse_ice_servers_or_warn("", "test").is_empty());
+        assert!(parse_ice_servers_or_warn("   ", "test").is_empty());
+    }
 }
diff --git a/crates/webview/src/render.rs b/crates/webview/src/render.rs
index bae320d9d..cd817140b 100644
--- a/crates/webview/src/render.rs
+++ b/crates/webview/src/render.rs
@@ -42,7 +42,8 @@ pub struct WebviewRenderer {
 }
 
 impl WebviewRenderer
-where T: GatewayTransport
+where
+    T: GatewayTransport,
 {
     /// Build a renderer around an existing gateway.
     pub fn new(gateway: WebviewGateway) -> Self {
diff --git a/crates/webview/src/transport.rs b/crates/webview/src/transport.rs
index e4032a573..fe7053b95 100644
--- a/crates/webview/src/transport.rs
+++ b/crates/webview/src/transport.rs
@@ -137,7 +137,8 @@ impl GatewayResponsePolicy {
 }
 
 impl WebviewGateway
-where T: GatewayTransport
+where
+    T: GatewayTransport,
 {
     /// Build a webview gateway around `transport`.
     pub fn new(prefix: GatewayPrefix, transport: T) -> Self {
@@ -222,7 +223,8 @@ where T: GatewayTransport
 }
 
 impl ConcurrentWebviewGateway
-where T: GatewayTransport
+where
+    T: GatewayTransport,
 {
     /// Build a concurrent webview gateway around `transport`.
     pub fn new(prefix: GatewayPrefix, transport: T) -> Self {
diff --git a/docker/cluster/Dockerfile b/docker/cluster/Dockerfile
index 22fa59f64..b73ea14bf 100644
--- a/docker/cluster/Dockerfile
+++ b/docker/cluster/Dockerfile
@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1.7
 
-FROM rust:1.94-trixie AS builder
+FROM rust:1.97-trixie AS builder
 
 WORKDIR /src
 COPY Cargo.lock Cargo.toml README.md rust-toolchain.toml ./
diff --git a/docker/cluster/README.md b/docker/cluster/README.md
index 8f0e98a98..2a41c36fe 100644
--- a/docker/cluster/README.md
+++ b/docker/cluster/README.md
@@ -18,6 +18,21 @@ docker run --rm \
   rings-node-cluster
 ```
 
+Run a browser-reachable cluster with one published JSON-RPC ingress and a fixed
+native WebRTC UDP range:
+
+```sh
+docker run --rm \
+  -e RINGS_NODE_COUNT=3 \
+  -e RINGS_ALLOW_RANDOM_KEYS=true \
+  -e RINGS_EXTERNAL_IP=127.0.0.1 \
+  -e RINGS_WEBRTC_UDP_PORT_MIN=49160 \
+  -e RINGS_WEBRTC_UDP_PORT_MAX=49220 \
+  -p 51000:51000/tcp \
+  -p 49160-49220:49160-49220/udp \
+  rings-node-cluster
+```
+
 Run with externally supplied keys:
 
 ```sh
@@ -48,6 +63,9 @@ Useful environment variables:
 - `RINGS_CLUSTER_DIR`: config, logs, storage, and session key directory; default `/var/lib/rings-cluster`
 - `RINGS_ICE_SERVERS`: ICE server list passed to every node; set it to an empty string to run without ICE servers
 - `RINGS_RUNTIME`: Tokio runtime flavor for each node process; default `current-thread`
+- `RINGS_EXTERNAL_IP`: optional native WebRTC NAT 1:1 IP advertised in ICE host candidates; default unset. For browser testing from the Docker host, use `127.0.0.1`.
+- `RINGS_EXTERNAL_IP_APPEND_CONTAINER_IP`: when `RINGS_EXTERNAL_IP` is set, also advertise the container IP so nodes inside the same container can still connect to each other; default `true`
+- `RINGS_WEBRTC_UDP_PORT_MIN` and `RINGS_WEBRTC_UDP_PORT_MAX`: optional fixed native WebRTC UDP port range; publish the same range with `/udp` when browser peers must establish data channels to non-ingress nodes
 - `RINGS_ADVERTISE_ONION_RELAY`: publish relay capability from every node; default `true`
 - `RINGS_ADVERTISE_ONION_EXIT`: publish exit descriptors from every node; default `true`
 - `RINGS_ONION_EXIT_SERVICES`: comma-separated `name:transport` services; default `tcp:tcp,https:tcp`
diff --git a/docker/cluster/rings-cluster-entrypoint.sh b/docker/cluster/rings-cluster-entrypoint.sh
index 45294b3b1..e24954ce3 100644
--- a/docker/cluster/rings-cluster-entrypoint.sh
+++ b/docker/cluster/rings-cluster-entrypoint.sh
@@ -21,6 +21,8 @@ READY_RETRIES="${RINGS_READY_RETRIES:-60}"
 READY_SLEEP_SECONDS="${RINGS_READY_SLEEP_SECONDS:-1}"
 LOG_LEVEL="${RINGS_LOG_LEVEL:-info}"
 RUNTIME="${RINGS_RUNTIME:-current-thread}"
+EXTERNAL_IP="${RINGS_EXTERNAL_IP:-}"
+APPEND_CONTAINER_EXTERNAL_IP="${RINGS_EXTERNAL_IP_APPEND_CONTAINER_IP:-true}"
 WEBRTC_UDP_PORT_MIN="${RINGS_WEBRTC_UDP_PORT_MIN:-}"
 WEBRTC_UDP_PORT_MAX="${RINGS_WEBRTC_UDP_PORT_MAX:-}"
 STORAGE_CAPACITY="${RINGS_STORAGE_CAPACITY:-200000000}"
@@ -79,6 +81,63 @@ yaml_quote() {
     printf "'%s'" "$value"
 }
 
+detect_container_ip() {
+    local ip=""
+    for ip in $(hostname -i 2>/dev/null || true); do
+        [[ -n "$ip" ]] || continue
+        [[ "$ip" != 127.* && "$ip" != "::1" ]] || continue
+        printf '%s' "$ip"
+        return 0
+    done
+}
+
+csv_contains_item() {
+    local csv="$1"
+    local needle="$2"
+    local item=""
+    local old_ifs="$IFS"
+    IFS=','
+    for item in $csv; do
+        item="$(trim "$item")"
+        if [[ "$item" == "$needle" ]]; then
+            IFS="$old_ifs"
+            return 0
+        fi
+    done
+    IFS="$old_ifs"
+    return 1
+}
+
+append_csv_unique() {
+    local csv="$1"
+    local item="$2"
+    [[ -n "$item" ]] || {
+        printf '%s' "$csv"
+        return 0
+    }
+    if csv_contains_item "$csv" "$item"; then
+        printf '%s' "$csv"
+    elif [[ -n "$csv" ]]; then
+        printf '%s,%s' "$csv" "$item"
+    else
+        printf '%s' "$item"
+    fi
+}
+
+external_ip_candidates() {
+    local candidates=""
+    local container_ip=""
+    candidates="$(trim "$EXTERNAL_IP")"
+    [[ -n "$candidates" ]] || return 0
+
+    if [[ "$APPEND_CONTAINER_EXTERNAL_IP" == "true" ]]; then
+        container_ip="$(detect_container_ip)"
+        candidates="$(append_csv_unique "$candidates" "$container_ip")"
+    fi
+
+    printf '%s' "$candidates"
+}
+
 canonical_onion_transport() {
     local raw="${1,,}"
     case "$raw" in
@@ -162,6 +221,7 @@ require_uint RINGS_READY_SLEEP_SECONDS "$READY_SLEEP_SECONDS"
 require_uint RINGS_STORAGE_CAPACITY "$STORAGE_CAPACITY"
 ADVERTISE_ONION_RELAY="$(bool_literal RINGS_ADVERTISE_ONION_RELAY "$ADVERTISE_ONION_RELAY")"
 ADVERTISE_ONION_EXIT="$(bool_literal RINGS_ADVERTISE_ONION_EXIT "$ADVERTISE_ONION_EXIT")"
+APPEND_CONTAINER_EXTERNAL_IP="$(bool_literal RINGS_EXTERNAL_IP_APPEND_CONTAINER_IP "$APPEND_CONTAINER_EXTERNAL_IP")"
 
 if (( NODE_COUNT < 1 )); then
     die "RINGS_NODE_COUNT must be at least 1"
@@ -288,6 +348,7 @@ write_config() {
     local storage_path="$6"
     local data_path="$storage_path/data"
     local measure_path="$storage_path/measure"
+    local external_ips=""
 
     {
         printf 'network_id: %s\n' "$NETWORK_ID"
@@ -317,7 +378,12 @@ write_config() {
             printf '  max_streams_per_circuit: 0\n'
             printf '  max_bytes_per_minute: 0\n'
         fi
-        printf 'external_ip: null\n'
+        external_ips="$(external_ip_candidates)"
+        if [[ -n "$external_ips" ]]; then
+            printf 'external_ip: %s\n' "$(yaml_quote "$external_ips")"
+        else
+            printf 'external_ip: null\n'
+        fi
         if [[ -n "$WEBRTC_UDP_PORT_MIN" || -n "$WEBRTC_UDP_PORT_MAX" ]]; then
             [[ -n "$WEBRTC_UDP_PORT_MIN" && -n "$WEBRTC_UDP_PORT_MAX" ]] \
                 || die "RINGS_WEBRTC_UDP_PORT_MIN and RINGS_WEBRTC_UDP_PORT_MAX must be set together"
diff --git a/examples/native/src/main.rs b/examples/native/src/main.rs
index 9ade475d8..265043202 100644
--- a/examples/native/src/main.rs
+++ b/examples/native/src/main.rs
@@ -72,9 +72,10 @@ async fn main() -> Result<(), Box> {
     println!("===> request ConnectPeerViaHttp api...");
     let resp: ConnectPeerViaHttpResponse = serde_json::from_value(
         provider
-            .request(Method::ConnectPeerViaHttp, ConnectPeerViaHttpRequest {
-                url: args.seed_url,
-            })
+            .request(
+                Method::ConnectPeerViaHttp,
+                ConnectPeerViaHttpRequest { url: args.seed_url },
+            )
             .await?,
     )?;
     println!("<=== ConnectPeerViaHttpResponse: {resp:?}");
diff --git a/examples/snark/bn256.rs b/examples/snark/bn256.rs
index 3443b36d8..d060067b8 100644
--- a/examples/snark/bn256.rs
+++ b/examples/snark/bn256.rs
@@ -66,18 +66,23 @@ async fn main() -> ExampleResult<()> {
     for c in recursive_circuits {
         rec_snark_iter.foldr(&pp, &c)?;
     }
-    rec_snark_iter.verify(&pp, 3, &vec![F1::from(4u64), F1::from(2u64)], &vec![
-        F2::from(0),
-    ])?;
+    rec_snark_iter.verify(
+        &pp,
+        3,
+        &vec![F1::from(4u64), F1::from(2u64)],
+        &vec![F2::from(0)],
+    )?;
     println!("success on create recursive snark");
     let (pk, vk) = snark::SNARK::::compress_setup::(&pp)?;
 
     let compress_snark = rec_snark_iter.compress_prove::(&pp, &pk)?;
     let compress_snark_ref = Rc::new(compress_snark);
-    snark::SNARK::::compress_verify::(compress_snark_ref, &vk, 3, &vec![
-        F1::from(4u64),
-        F1::from(2u64),
-    ])?;
+    snark::SNARK::::compress_verify::(
+        compress_snark_ref,
+        &vk,
+        3,
+        &vec![F1::from(4u64), F1::from(2u64)],
+    )?;
 
     Ok(())
 }
diff --git a/examples/snark/src/lib.rs b/examples/snark/src/lib.rs
index a82a1fd39..a4bd6a298 100644
--- a/examples/snark/src/lib.rs
+++ b/examples/snark/src/lib.rs
@@ -136,13 +136,17 @@ pub fn first_recursive_circuit(circuits: &[T]) -> ExampleResult<&T> {
 
 /// Public input used by the simple BN256 example.
 pub fn simple_bn256_initial_input() -> Input
-where F: PrimeField + From {
+where
+    F: PrimeField + From,
+{
     vec![("step_in".to_string(), vec![F::from(4u64), F::from(2u64)])].into()
 }
 
 /// Private inputs used by the simple BN256 recursive example.
 pub fn simple_bn256_private_inputs() -> Vec>
-where F: PrimeField + From {
+where
+    F: PrimeField + From,
+{
     vec![
         vec![("adder".to_string(), vec![F::from(1u64)])].into(),
         vec![("adder".to_string(), vec![F::from(42u64)])].into(),
@@ -204,13 +208,17 @@ pub async fn simple_bn256_one_step_prove_verify() -> ExampleResult<()> {
 
 /// Public input used by the Merkle-tree example.
 pub fn merkle_tree_initial_input() -> Input
-where F: PrimeField + From {
+where
+    F: PrimeField + From,
+{
     vec![("leaf".to_string(), vec![F::from(42u64)])].into()
 }
 
 /// Private path inputs used by the Merkle-tree example.
 pub fn merkle_tree_private_inputs() -> Vec>
-where F: PrimeField + From {
+where
+    F: PrimeField + From,
+{
     vec![
         vec![("path".to_string(), vec![F::from(1u64), F::from(0u64)])].into(),
         vec![("path".to_string(), vec![F::from(42u64), F::from(1u64)])].into(),
@@ -239,10 +247,13 @@ mod tests {
         let initial = simple_bn256_initial_input::();
         let private = simple_bn256_private_inputs::();
 
-        assert_eq!(initial.input.as_slice(), [("step_in".to_string(), vec![
-            Bn256TestField::from(4u64),
-            Bn256TestField::from(2u64)
-        ])]);
+        assert_eq!(
+            initial.input.as_slice(),
+            [(
+                "step_in".to_string(),
+                vec![Bn256TestField::from(4u64), Bn256TestField::from(2u64)]
+            )]
+        );
         assert_eq!(private.len(), 3);
         assert!(private
             .iter()
@@ -261,9 +272,10 @@ mod tests {
         let initial = merkle_tree_initial_input::();
         let private = merkle_tree_private_inputs::();
 
-        assert_eq!(initial.input.as_slice(), [("leaf".to_string(), vec![
-            MerkleTreeTestField::from(42u64)
-        ])]);
+        assert_eq!(
+            initial.input.as_slice(),
+            [("leaf".to_string(), vec![MerkleTreeTestField::from(42u64)])]
+        );
         assert_eq!(private.len(), 3);
         assert!(private.iter().all(
             |input| matches!(input.input.as_slice(), [(name, path)] if name == "path" && path.len() == 2)
diff --git a/frontend/src/node.rs b/frontend/src/node.rs
index 30f843e36..206ed545d 100644
--- a/frontend/src/node.rs
+++ b/frontend/src/node.rs
@@ -2,13 +2,12 @@
 
 use std::sync::Arc;
 
-use futures::future::AbortHandle;
-use futures::future::Abortable;
 use js_sys::Array;
 use js_sys::Object;
 use js_sys::Reflect;
 use js_sys::Uint8Array;
 use rings_node::extension::snark::SNARKBehaviour;
+use rings_node::prelude::StopSource;
 use rings_node::prelude::rings_core::session::SessionSkBuilder;
 use rings_node::prelude::rings_core::storage::idb::IdbStorage;
 use rings_node::processor::ProcessorBuilder;
@@ -32,13 +31,13 @@ pub struct DemoNode {
     pub snark: SNARKBehaviour,
     /// Controlled webview gateway attached to this browser node when its host origin is HTTP(S).
     pub webview: Option,
-    listen_abort: AbortHandle,
+    listen_stop: StopSource,
 }
 
 impl DemoNode {
     /// Stop the background listen/stabilize loop started for this demo node.
     pub fn stop(&self) {
-        self.listen_abort.abort();
+        self.listen_stop.request_stop();
     }
 
     /// Return the controlled webview gateway attached to this browser node.
@@ -151,16 +150,17 @@ pub async fn build_node(
     let webview = WebviewNode::for_current_window(provider.clone())
         .map_err(|error| format!("initialize webview: {error}"))?;
 
-    let (listen_abort, listen_registration) = AbortHandle::new_pair();
+    let listen_stop = StopSource::new();
+    let listen_token = listen_stop.token();
     spawn_local(async move {
-        let _result = Abortable::new(listening.listen(), listen_registration).await;
+        listening.listen_with(listen_token).await;
     });
 
     Ok(DemoNode {
         provider,
         snark,
         webview,
-        listen_abort,
+        listen_stop,
     })
 }
 

From ef2302aef7ef6a52862abc2dc82ae1c8645287d4 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Thu, 23 Jul 2026 18:40:24 +0800
Subject: [PATCH 10/23] Fix browser DHT liveness races

---
 .github/workflows/qaci.yml                    |   3 +
 crates/core/src/algebra.rs                    |  23 +-
 crates/core/src/dht/did.rs                    |  15 +-
 crates/core/src/dht/entry/tests.rs            |  39 ++--
 crates/core/src/dht/finger.rs                 |  55 +++--
 crates/core/src/dht/stabilization.rs          |   4 +-
 crates/core/src/dht/storage/mod.rs            |  13 +-
 crates/core/src/dht/storage/repair.rs         |   9 +-
 crates/core/src/dht/storage/tests.rs          |  26 +--
 crates/core/src/dht/topology.rs               |  46 ++--
 .../core/src/ecc/elgamal/impls/secp256k1.rs   |  22 +-
 crates/core/src/ecc/elgamal/mod.rs            |  18 +-
 crates/core/src/ecc/mod.rs                    |  19 +-
 crates/core/src/ecc/types.rs                  |  12 +-
 crates/core/src/inspect.rs                    |   4 +-
 crates/core/src/measure.rs                    |   8 +-
 crates/core/src/message/effects.rs            |  18 +-
 crates/core/src/message/encoder.rs            |   4 +-
 .../core/src/message/handlers/connection.rs   | 202 +++++++++---------
 .../src/message/handlers/stabilization.rs     | 120 +++++------
 .../handlers/storage/tests/test_repair.rs     | 136 +++++-------
 .../storage/tests/test_storage_sync_report.rs |  16 +-
 .../storage/tests/test_sync_receive.rs        |  45 ++--
 crates/core/src/message/payload.rs            |  28 +--
 crates/core/src/message/protocols/relay.rs    |   4 +-
 crates/core/src/storage/idb.rs                |   3 +-
 crates/core/src/storage/memory.rs             |   9 +-
 crates/core/src/storage/sled.rs               |   7 +-
 crates/core/src/swarm/transport.rs            |  33 ++-
 crates/core/src/swarm/transport/pending.rs    |  26 ++-
 .../src/swarm/transport/storage_lookup.rs     |  11 +-
 crates/core/src/swarm/transport/tests.rs      |  52 ++++-
 .../core/src/tests/wasm/test_idb_storage.rs   |  49 ++---
 crates/core/src/utils.rs                      |   4 +-
 crates/node/src/error.rs                      |   6 +-
 crates/node/src/extension/ext/interpret.rs    |   7 +-
 crates/node/src/extension/ext/mod.rs          |   8 +-
 crates/node/src/extension/ext/registry.rs     |  18 +-
 crates/node/src/extension/mod.rs              |   4 +-
 crates/node/src/extension/protocols/echo.rs   |  18 +-
 crates/node/src/extension/protocols/mod.rs    |   2 +-
 crates/node/src/extension/protocols/relay.rs  | 115 ++++------
 crates/node/src/extension/snark/builder.rs    |  27 +--
 crates/node/src/extension/snark/mod.rs        |   2 +-
 crates/node/src/extension/snark/protocol.rs   |  46 ++--
 .../src/extension/transport/engine/mod.rs     |  53 ++---
 .../src/extension/transport/engine/tcp.rs     |  38 ++--
 .../src/extension/transport/engine/udp.rs     |  26 +--
 crates/node/src/extension/transport/mod.rs    |   2 +-
 crates/node/src/extension/transport/wt.rs     |  62 ++----
 crates/node/src/logging.rs                    |  10 +-
 crates/node/src/measure.rs                    |   8 +-
 crates/node/src/native/cli.rs                 |   5 +-
 crates/node/src/native/config.rs              |  16 +-
 crates/node/src/native/endpoint/mod.rs        |   3 +-
 crates/node/src/onion/circuit/shell.rs        |  36 ++--
 .../circuit/tests/test_circuit_protocol.rs    |  30 +--
 crates/node/src/onion/directory.rs            |   7 +-
 crates/node/src/onion/https/mod.rs            |  75 +++----
 .../src/onion/https/tests/test_https_proxy.rs |  17 +-
 crates/node/src/onion/mod.rs                  |   6 +-
 crates/node/src/onion/replay.rs               |   3 +-
 .../onion/route/tests/test_route_selection.rs |  23 +-
 crates/node/src/onion/tcp/mod.rs              |  22 +-
 .../src/onion/tests/test_exit_registry.rs     |  15 +-
 crates/node/src/processor/builder.rs          |   6 +-
 crates/node/src/processor/config.rs           |   6 +-
 crates/node/src/processor/mod.rs              |  26 ++-
 .../node/src/processor/tests/test_config.rs   |   8 +-
 .../node/src/processor/tests/test_network.rs  |  24 ++-
 crates/node/src/provider/browser/provider.rs  |  46 +++-
 crates/node/src/provider/ffi.rs               |   4 +-
 crates/node/src/provider/mod.rs               |  28 +--
 crates/node/src/registration.rs               |  22 +-
 crates/node/src/rpc_dto.rs                    |  34 +--
 crates/node/src/rpc_impl.rs                   |  88 ++++----
 crates/node/src/tests/mod.rs                  |   2 +-
 crates/node/src/tests/native/test_snark.rs    |  11 +-
 crates/node/src/tests/wasm/test_browser.rs    |  12 ++
 crates/node/src/tests/wasm/test_processor.rs  |  12 +-
 crates/node/src/tests/wasm/test_snark.rs      |  11 +-
 crates/node/src/util.rs                       |  12 +-
 crates/rpc/src/jsonrpc.rs                     |   4 +-
 crates/rpc/src/protos/rings_node_handler.rs   |   4 +-
 crates/snark/src/circuit/bellman.rs           |   3 +-
 crates/snark/src/circuit/mod.rs               |  11 +-
 crates/snark/src/tests/native/test_snark.rs   |  48 ++---
 crates/snark/src/tests/native/test_wat.rs     |  11 +-
 crates/snark/src/witness/circom.rs            |  25 ++-
 crates/transport/src/connection_ref.rs        |  19 ++
 crates/transport/src/connections/dummy/mod.rs |  18 +-
 .../src/connections/native_webrtc/mod.rs      |  36 +++-
 .../src/connections/web_sys_webrtc/mod.rs     |   8 +-
 crates/transport/src/core/sdp.rs              |  45 ++--
 crates/transport/src/core/transport.rs        |   8 +
 crates/webview/src/render.rs                  |   3 +-
 crates/webview/src/transport.rs               |   6 +-
 examples/native/src/main.rs                   |   7 +-
 examples/snark/bn256.rs                       |  19 +-
 examples/snark/src/lib.rs                     |  34 +--
 .../scripts/test-webview-service-worker.mts   |   2 +-
 101 files changed, 1186 insertions(+), 1270 deletions(-)

diff --git a/.github/workflows/qaci.yml b/.github/workflows/qaci.yml
index b8f3d2c46..3a1c918fe 100644
--- a/.github/workflows/qaci.yml
+++ b/.github/workflows/qaci.yml
@@ -267,6 +267,9 @@ jobs:
             -D clippy::unimplemented \
             -D clippy::indexing_slicing
 
+      - name: Check node native with browser feature enabled
+        run: cargo check -p rings-node --all-features
+
       - name: Run clippy
         run: cargo clippy --all --tests -- -D warnings
 
diff --git a/crates/core/src/algebra.rs b/crates/core/src/algebra.rs
index 437e5f148..764ac2cdd 100644
--- a/crates/core/src/algebra.rs
+++ b/crates/core/src/algebra.rs
@@ -187,8 +187,7 @@ pub trait Field: CommutativeRing {
 ///
 /// Law: `a * Scalar::one() == a`.
 pub trait Module: AbelianGroup + Mul
-where
-    Scalar: CommutativeRing,
+where Scalar: CommutativeRing
 {
 }
 
@@ -200,9 +199,7 @@ where
 /// explain why the laws hold for the whole carrier.
 #[cfg(test)]
 pub fn assert_abelian_group_laws(values: &[T])
-where
-    T: AbelianGroup + Clone + Eq + Debug,
-{
+where T: AbelianGroup + Clone + Eq + Debug {
     for a in values {
         assert_eq!(a.clone() + T::zero(), *a);
         assert_eq!(T::zero() + a.clone(), *a);
@@ -231,9 +228,7 @@ where
 /// order, with any duplication.
 #[cfg(test)]
 pub fn assert_join_semilattice_laws(values: &[T])
-where
-    T: JoinSemilattice + Clone + Eq + Debug,
-{
+where T: JoinSemilattice + Clone + Eq + Debug {
     for a in values {
         assert_eq!(a.clone().join(a.clone()), *a);
 
@@ -256,9 +251,7 @@ where
 /// bound for each schedule.
 #[cfg(test)]
 pub fn assert_strong_eventual_consistency(base: T, deltas: &[T])
-where
-    T: JoinSemilattice + Clone + Eq + Debug,
-{
+where T: JoinSemilattice + Clone + Eq + Debug {
     let forward = deltas
         .iter()
         .cloned()
@@ -287,9 +280,7 @@ where
 /// distributivity on the same sample.
 #[cfg(test)]
 pub fn assert_commutative_ring_laws(values: &[T])
-where
-    T: CommutativeRing + Clone + Eq + Debug,
-{
+where T: CommutativeRing + Clone + Eq + Debug {
     assert_abelian_group_laws(values);
 
     for a in values {
@@ -321,9 +312,7 @@ where
 /// and every sampled non-zero value has a two-sided inverse.
 #[cfg(test)]
 pub fn assert_field_laws(values: &[T])
-where
-    T: Field + Clone + Eq + Debug,
-{
+where T: Field + Clone + Eq + Debug {
     assert_commutative_ring_laws(values);
     assert_ne!(T::zero(), T::one());
 
diff --git a/crates/core/src/dht/did.rs b/crates/core/src/dht/did.rs
index db4aaff01..369382d59 100644
--- a/crates/core/src/dht/did.rs
+++ b/crates/core/src/dht/did.rs
@@ -604,15 +604,12 @@ mod tests {
         let did = Did::from(10u32);
         let affine_dids = did.rotate_affine(4)?;
         assert_eq!(affine_dids.len(), 4);
-        assert_eq!(
-            affine_dids,
-            vec![
-                did.rotate(0),
-                did.rotate(90),
-                did.rotate(180),
-                did.rotate(270)
-            ]
-        );
+        assert_eq!(affine_dids, vec![
+            did.rotate(0),
+            did.rotate(90),
+            did.rotate(180),
+            did.rotate(270)
+        ]);
         Ok(())
     }
 
diff --git a/crates/core/src/dht/entry/tests.rs b/crates/core/src/dht/entry/tests.rs
index 9c9c51575..22b318264 100644
--- a/crates/core/src/dht/entry/tests.rs
+++ b/crates/core/src/dht/entry/tests.rs
@@ -163,10 +163,10 @@ fn entry_join_is_strongly_eventually_consistent_for_data_deltas() -> Result<()>
 
     assert_eq!(forward, reverse);
     assert_eq!(forward, duplicated);
-    assert_eq!(
-        decode_entry_data(&forward)?,
-        vec![String::from("b"), String::from("a")]
-    );
+    assert_eq!(decode_entry_data(&forward)?, vec![
+        String::from("b"),
+        String::from("a")
+    ]);
     Ok(())
 }
 
@@ -362,10 +362,10 @@ fn extend_appends_data_for_same_entry() -> Result<()> {
     let entry = data_entry("topic", "first")?;
     let other = data_entry("topic", "second")?;
     let updated = entry.extend(other, actor())?;
-    assert_eq!(
-        decode_entry_data(&updated)?,
-        vec![String::from("first"), String::from("second")]
-    );
+    assert_eq!(decode_entry_data(&updated)?, vec![
+        String::from("first"),
+        String::from("second")
+    ]);
     Ok(())
 }
 
@@ -422,10 +422,11 @@ fn touch_moves_existing_items_to_end_once() -> Result<()> {
         .extend(data_entry("topic", "c")?, actor())?;
     let touched = data_entry("topic", "b")?;
     let updated = entry.touch(touched, actor())?;
-    assert_eq!(
-        decode_entry_data(&updated)?,
-        vec![String::from("a"), String::from("c"), String::from("b")]
-    );
+    assert_eq!(decode_entry_data(&updated)?, vec![
+        String::from("a"),
+        String::from("c"),
+        String::from("b")
+    ]);
     Ok(())
 }
 
@@ -456,10 +457,9 @@ fn relay_tombstone_removes_observed_message_by_join() -> Result<()> {
 
     assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
     let joined_with_stale_add = removed.join(first)?;
-    assert_eq!(
-        decode_entry_data(&joined_with_stale_add)?,
-        vec![String::from("second")]
-    );
+    assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
+        String::from("second")
+    ]);
     Ok(())
 }
 
@@ -475,10 +475,9 @@ fn data_tombstone_removes_observed_payload_by_join() -> Result<()> {
 
     assert_eq!(decode_entry_data(&removed)?, vec![String::from("second")]);
     let joined_with_stale_add = removed.join(first)?;
-    assert_eq!(
-        decode_entry_data(&joined_with_stale_add)?,
-        vec![String::from("second")]
-    );
+    assert_eq!(decode_entry_data(&joined_with_stale_add)?, vec![
+        String::from("second")
+    ]);
     Ok(())
 }
 
diff --git a/crates/core/src/dht/finger.rs b/crates/core/src/dht/finger.rs
index 4bde3cf5c..8ede88b56 100644
--- a/crates/core/src/dht/finger.rs
+++ b/crates/core/src/dht/finger.rs
@@ -345,10 +345,13 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did1);
-        assert_eq!(
-            table.finger,
-            [Some(did2), Some(did2), Some(did3), Some(did4), Some(did5),]
-        );
+        assert_eq!(table.finger, [
+            Some(did2),
+            Some(did2),
+            Some(did3),
+            Some(did4),
+            Some(did5),
+        ]);
 
         // [did1, did2, did3, did4, did5] - did2 = [did1, did3, did3, did4, did5]
         table.reset_finger();
@@ -358,10 +361,13 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did2);
-        assert_eq!(
-            table.finger,
-            [Some(did1), Some(did3), Some(did3), Some(did4), Some(did5),]
-        );
+        assert_eq!(table.finger, [
+            Some(did1),
+            Some(did3),
+            Some(did3),
+            Some(did4),
+            Some(did5),
+        ]);
 
         // [did1, None, did3, did4, did5] - did1 = [None, None, did3, did4, did5]
         table.reset_finger();
@@ -370,10 +376,13 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did1);
-        assert_eq!(
-            table.finger,
-            [None, None, Some(did3), Some(did4), Some(did5),]
-        );
+        assert_eq!(table.finger, [
+            None,
+            None,
+            Some(did3),
+            Some(did4),
+            Some(did5),
+        ]);
 
         // [did1, None, did3, did4, did5] - did3 = [did1, None, did4, did4, did5]
         table.reset_finger();
@@ -382,10 +391,13 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did3);
-        assert_eq!(
-            table.finger,
-            [Some(did1), None, Some(did4), Some(did4), Some(did5),]
-        );
+        assert_eq!(table.finger, [
+            Some(did1),
+            None,
+            Some(did4),
+            Some(did4),
+            Some(did5),
+        ]);
 
         // [did1, did2, did3, did4, did5] - did5 = [did1, did2, did4, did4, None]
         table.reset_finger();
@@ -395,9 +407,12 @@ mod test {
         table.set(3, did4);
         table.set(4, did5);
         table.remove(did5);
-        assert_eq!(
-            table.finger,
-            [Some(did1), Some(did2), Some(did3), Some(did4), None]
-        );
+        assert_eq!(table.finger, [
+            Some(did1),
+            Some(did2),
+            Some(did3),
+            Some(did4),
+            None
+        ]);
     }
 }
diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index 6c842f7b7..c6d7ee825 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -214,9 +214,7 @@ impl Stabilizer {
     }
 
     async fn run_step(&self, step: &'static str, timeout: Duration, future: F)
-    where
-        F: Future>,
-    {
+    where F: Future> {
         tracing::debug!(
             target: "rings_core::dht::stabilization",
             local = %self.dht.did,
diff --git a/crates/core/src/dht/storage/mod.rs b/crates/core/src/dht/storage/mod.rs
index 1435cd1b1..9ed86d3f1 100644
--- a/crates/core/src/dht/storage/mod.rs
+++ b/crates/core/src/dht/storage/mod.rs
@@ -183,14 +183,11 @@ impl PeerRingAction {
         destination: StorageSyncDestination,
         data: Vec,
     ) -> Self {
-        Self::RemoteAction(
-            destination.did(),
-            RemoteAction::SyncEntriesWithSuccessor {
-                purpose,
-                route: destination.route(),
-                data,
-            },
-        )
+        Self::RemoteAction(destination.did(), RemoteAction::SyncEntriesWithSuccessor {
+            purpose,
+            route: destination.route(),
+            data,
+        })
     }
 
     /// Lower this action tree into storage-sync deliveries.
diff --git a/crates/core/src/dht/storage/repair.rs b/crates/core/src/dht/storage/repair.rs
index 44d6fae5d..0dca04b39 100644
--- a/crates/core/src/dht/storage/repair.rs
+++ b/crates/core/src/dht/storage/repair.rs
@@ -169,10 +169,11 @@ impl PeerRing {
                     .await?;
                 Ok(PeerRingAction::None)
             }
-            StorageSyncTarget::Remote(destination) => Ok(PeerRingAction::sync_entries_for_repair(
-                destination,
-                vec![placed],
-            )),
+            StorageSyncTarget::Remote(destination) => {
+                Ok(PeerRingAction::sync_entries_for_repair(destination, vec![
+                    placed,
+                ]))
+            }
         }
     }
 
diff --git a/crates/core/src/dht/storage/tests.rs b/crates/core/src/dht/storage/tests.rs
index f56e3fe63..6e454080d 100644
--- a/crates/core/src/dht/storage/tests.rs
+++ b/crates/core/src/dht/storage/tests.rs
@@ -212,13 +212,10 @@ fn coalesced_storage_sync_deliveries_keep_placement_destinations_separate() -> R
         .into_iter()
         .map(|delivery| delivery.into_message_parts().1)
         .collect::>();
-    assert_eq!(
-        destinations,
-        vec![
-            StorageSyncDestination::PlacementKey(first_key),
-            StorageSyncDestination::PlacementKey(second_key),
-        ]
-    );
+    assert_eq!(destinations, vec![
+        StorageSyncDestination::PlacementKey(first_key),
+        StorageSyncDestination::PlacementKey(second_key),
+    ]);
     Ok(())
 }
 
@@ -490,10 +487,10 @@ async fn sync_without_ack_retains_entry_for_next_handoff() -> Result<()> {
 
     let action = node.sync_entries_with_successor(new_successor).await?;
     let retried_action = node.sync_entries_with_successor(new_successor).await?;
-    let expected = vec![(
-        new_successor,
-        vec![PlacedEntry::new(placement_key, entry.clone())],
-    )];
+    let expected = vec![(new_successor, vec![PlacedEntry::new(
+        placement_key,
+        entry.clone(),
+    )])];
 
     assert_eq!(collect_sync_batches(action)?, expected);
     assert_eq!(collect_sync_batches(retried_action)?, expected);
@@ -883,10 +880,9 @@ async fn read_repair_targets_only_observed_missing_placements() -> Result<()> {
         .read_repair_entry(evidence.entry.clone(), &evidence.misses, 3)
         .await?;
 
-    assert_eq!(
-        evidence.misses,
-        vec![PlacementMiss::new(first_key, node.did)]
-    );
+    assert_eq!(evidence.misses, vec![PlacementMiss::new(
+        first_key, node.did
+    )]);
     assert_eq!(repair, PeerRingAction::None);
     assert_eq!(
         node.storage.get(&first_key.to_string()).await?,
diff --git a/crates/core/src/dht/topology.rs b/crates/core/src/dht/topology.rs
index a065fd628..be207ffee 100644
--- a/crates/core/src/dht/topology.rs
+++ b/crates/core/src/dht/topology.rs
@@ -527,17 +527,19 @@ mod tests {
         );
 
         assert_eq!(next.state.successors, vec![peer]);
-        assert_eq!(
-            next.state.fingers,
-            vec![Some(peer), Some(peer), Some(peer), Some(peer), None]
-        );
-        assert_eq!(
-            next.actions,
-            vec![TopologyAction::FindSuccessorForConnect {
+        assert_eq!(next.state.fingers, vec![
+            Some(peer),
+            Some(peer),
+            Some(peer),
+            Some(peer),
+            None
+        ]);
+        assert_eq!(next.actions, vec![
+            TopologyAction::FindSuccessorForConnect {
                 next: peer,
                 did: local
-            }]
-        );
+            }
+        ]);
     }
 
     #[test]
@@ -624,14 +626,11 @@ mod tests {
         );
 
         assert_eq!(next.state.fix_finger_index, 3);
-        assert_eq!(
-            next.actions,
-            vec![TopologyAction::FindSuccessorForFix {
-                next: next_hop,
-                did: Did::power_of_two(3),
-                index: 3
-            }]
-        );
+        assert_eq!(next.actions, vec![TopologyAction::FindSuccessorForFix {
+            next: next_hop,
+            did: Did::power_of_two(3),
+            index: 3
+        }]);
     }
 
     #[test]
@@ -652,14 +651,11 @@ mod tests {
         );
 
         assert_eq!(next.state.fix_finger_index, 3);
-        assert_eq!(
-            next.actions,
-            vec![TopologyAction::FindSuccessorForFix {
-                next: next_hop,
-                did: local + Did::power_of_two(3),
-                index: 3
-            }]
-        );
+        assert_eq!(next.actions, vec![TopologyAction::FindSuccessorForFix {
+            next: next_hop,
+            did: local + Did::power_of_two(3),
+            index: 3
+        }]);
     }
 
     #[test]
diff --git a/crates/core/src/ecc/elgamal/impls/secp256k1.rs b/crates/core/src/ecc/elgamal/impls/secp256k1.rs
index 9a75b703c..fb81bcf38 100644
--- a/crates/core/src/ecc/elgamal/impls/secp256k1.rs
+++ b/crates/core/src/ecc/elgamal/impls/secp256k1.rs
@@ -398,13 +398,10 @@ pub fn encrypt_aead_with_rng(
     let associated_data = aead_associated_data(&encrypted_key, aad)?;
     let cipher = ChaCha20Poly1305::new(Key::from_slice(key.as_slice()));
     let ciphertext = cipher
-        .encrypt(
-            Nonce::from_slice(&nonce),
-            Payload {
-                msg: plaintext,
-                aad: associated_data.as_slice(),
-            },
-        )
+        .encrypt(Nonce::from_slice(&nonce), Payload {
+            msg: plaintext,
+            aad: associated_data.as_slice(),
+        })
         .map_err(|_| Error::MessageEncryptionFailed("AEAD seal failed".to_string()))?;
 
     Ok(AeadCiphertext {
@@ -433,13 +430,10 @@ pub fn decrypt_aead(
     let associated_data = aead_associated_data(&sealed.encrypted_key, aad)?;
     let cipher = ChaCha20Poly1305::new(Key::from_slice(key.as_slice()));
     cipher
-        .decrypt(
-            Nonce::from_slice(&sealed.nonce),
-            Payload {
-                msg: sealed.ciphertext.as_slice(),
-                aad: associated_data.as_slice(),
-            },
-        )
+        .decrypt(Nonce::from_slice(&sealed.nonce), Payload {
+            msg: sealed.ciphertext.as_slice(),
+            aad: associated_data.as_slice(),
+        })
         .map_err(|_| Error::MessageDecryptionFailed("AEAD open failed".to_string()))
 }
 
diff --git a/crates/core/src/ecc/elgamal/mod.rs b/crates/core/src/ecc/elgamal/mod.rs
index bf13c11a4..93edcb98b 100644
--- a/crates/core/src/ecc/elgamal/mod.rs
+++ b/crates/core/src/ecc/elgamal/mod.rs
@@ -98,8 +98,7 @@ pub struct ElGamalKeyPair {
 pub struct ElGamal(PhantomData);
 
 impl ElGamalPublicKey
-where
-    Element: CyclicModule,
+where Element: CyclicModule
 {
     /// Build a public key from an existing group element.
     pub fn from_element(element: Element) -> Self {
@@ -118,8 +117,7 @@ where
 }
 
 impl Clone for ElGamalPublicKey
-where
-    Element: CyclicModule + Clone,
+where Element: CyclicModule + Clone
 {
     fn clone(&self) -> Self {
         Self::from_element(self.element.clone())
@@ -127,8 +125,7 @@ where
 }
 
 impl ElGamalSecretKey
-where
-    Element: CyclicModule,
+where Element: CyclicModule
 {
     /// Build a secret key from an existing scalar.
     pub fn from_scalar(scalar: Element::Scalar) -> Self {
@@ -162,8 +159,7 @@ where
 }
 
 impl ElGamalKeyPair
-where
-    Element: CyclicModule,
+where Element: CyclicModule
 {
     /// Borrow the public key.
     pub fn public_key(&self) -> &ElGamalPublicKey {
@@ -177,8 +173,7 @@ where
 }
 
 impl ElGamalSecretKey
-where
-    Element: CyclicModule,
+where Element: CyclicModule
 {
     /// Generate a fresh non-zero ElGamal secret scalar from an explicit RNG.
     pub fn random_with_rng(rng: &mut impl RngCore) -> Self {
@@ -192,8 +187,7 @@ where
 }
 
 impl ElGamalKeyPair
-where
-    Element: CyclicModule,
+where Element: CyclicModule
 {
     /// Generate a fresh ElGamal key pair from an explicit RNG.
     pub fn random_with_rng(rng: &mut impl RngCore) -> Self {
diff --git a/crates/core/src/ecc/mod.rs b/crates/core/src/ecc/mod.rs
index dd25a0535..dbb062513 100644
--- a/crates/core/src/ecc/mod.rs
+++ b/crates/core/src/ecc/mod.rs
@@ -210,8 +210,7 @@ impl From for PublicKey<33> {
 }
 
 impl From for HashStr
-where
-    T: Into,
+where T: Into
 {
     fn from(s: T) -> Self {
         let inputs = s.into();
@@ -252,27 +251,21 @@ impl<'de> serde::de::Visitor<'de> for SecretKeyVisitor {
         formatter.write_str("SecretKey deserializer")
     }
     fn visit_str(self, value: &str) -> std::result::Result
-    where
-        E: serde::de::Error,
-    {
+    where E: serde::de::Error {
         SecretKey::from_str(value).map_err(|e| serde::de::Error::custom(e))
     }
 }
 
 impl<'de> Deserialize<'de> for SecretKey {
     fn deserialize(deserializer: D) -> std::result::Result
-    where
-        D: serde::Deserializer<'de>,
-    {
+    where D: serde::Deserializer<'de> {
         deserializer.deserialize_str(SecretKeyVisitor)
     }
 }
 
 impl Serialize for SecretKey {
     fn serialize(&self, serializer: S) -> std::result::Result
-    where
-        S: serde::Serializer,
-    {
+    where S: serde::Serializer {
         serializer.serialize_str(self.to_string().as_str())
     }
 }
@@ -350,9 +343,7 @@ impl PublicKey<33> {
 
 /// Recover PublicKey from RawMessage using signature.
 pub fn recover(message: &[u8], signature: S) -> Result>
-where
-    S: AsRef<[u8]>,
-{
+where S: AsRef<[u8]> {
     let sig_bytes: SigBytes = signature.as_ref().try_into()?;
     let message_hash: [u8; 32] = keccak256(message);
     recover_hash(&message_hash, &sig_bytes)
diff --git a/crates/core/src/ecc/types.rs b/crates/core/src/ecc/types.rs
index c70f12e48..a2e70f22b 100644
--- a/crates/core/src/ecc/types.rs
+++ b/crates/core/src/ecc/types.rs
@@ -14,9 +14,7 @@ struct PublicKeyVisitor;
 // /// twist from https://docs.rs/libsecp256k1/latest/src/libsecp256k1/lib.rs.html#335-344
 impl Serialize for PublicKey {
     fn serialize(&self, serializer: S) -> std::result::Result
-    where
-        S: serde::ser::Serializer,
-    {
+    where S: serde::ser::Serializer {
         serializer.serialize_str(
             &base58_monero::encode_check(&self.0[..]).map_err(serde::ser::Error::custom)?,
         )
@@ -103,9 +101,7 @@ impl<'de, const SIZE: usize> serde::de::Visitor<'de> for PublicKeyVisitor
     }
 
     fn visit_str(self, value: &str) -> std::result::Result
-    where
-        E: serde::de::Error,
-    {
+    where E: serde::de::Error {
         let value =
             base58_monero::decode_check(value).map_err(|_| E::custom(Error::PublicKeyBadFormat))?;
         if SIZE == 33 {
@@ -118,9 +114,7 @@ impl<'de, const SIZE: usize> serde::de::Visitor<'de> for PublicKeyVisitor
 
 impl<'de, const SIZE: usize> Deserialize<'de> for PublicKey {
     fn deserialize(deserializer: D) -> std::result::Result
-    where
-        D: serde::de::Deserializer<'de>,
-    {
+    where D: serde::de::Deserializer<'de> {
         deserializer.deserialize_str(PublicKeyVisitor)
     }
 }
diff --git a/crates/core/src/inspect.rs b/crates/core/src/inspect.rs
index 4058a82fe..15f90470d 100644
--- a/crates/core/src/inspect.rs
+++ b/crates/core/src/inspect.rs
@@ -122,9 +122,7 @@ impl StorageInspect {
 
 /// Compress equal adjacent iterator values into inclusive index ranges.
 pub fn compress_iter(iter: impl Iterator) -> Vec<(T, u64, u64)>
-where
-    T: PartialEq,
-{
+where T: PartialEq {
     let mut result = vec![];
     let mut start = 0u64;
     let mut count = 0u64;
diff --git a/crates/core/src/measure.rs b/crates/core/src/measure.rs
index 7538d9125..2eb440d81 100644
--- a/crates/core/src/measure.rs
+++ b/crates/core/src/measure.rs
@@ -114,9 +114,7 @@ impl PeerMeasurement {
     /// Returns `None` when no counter has ever been recorded for `did`; absence
     /// is distinct from an observed peer with non-zero counters.
     pub async fn from_measure(measure: &M, did: Did) -> Option
-    where
-        M: Measure + ?Sized,
-    {
+    where M: Measure + ?Sized {
         let evidence = PeerQualityEvidence::from_measure(measure, did).await;
         if evidence.is_unobserved() {
             return None;
@@ -148,9 +146,7 @@ impl PeerQualityEvidence {
 
     /// Read all counters for `did` from a measurement implementation.
     pub async fn from_measure(measure: &M, did: Did) -> Self
-    where
-        M: Measure + ?Sized,
-    {
+    where M: Measure + ?Sized {
         Self {
             connected: measure.get_count(did, MeasureCounter::Connect).await,
             disconnected: measure.get_count(did, MeasureCounter::Disconnected).await,
diff --git a/crates/core/src/message/effects.rs b/crates/core/src/message/effects.rs
index 28b946752..7c4bef5e6 100644
--- a/crates/core/src/message/effects.rs
+++ b/crates/core/src/message/effects.rs
@@ -271,10 +271,12 @@ impl From for PeerRingAction {
             DhtActionFunctor::FindSuccessorForConnect { next, did } => {
                 Self::RemoteAction(next, PeerRingRemoteAction::FindSuccessorForConnect(did))
             }
-            DhtActionFunctor::FindSuccessorForFix { next, did, index } => Self::RemoteAction(
-                next,
-                PeerRingRemoteAction::FindSuccessorForFix { did, index },
-            ),
+            DhtActionFunctor::FindSuccessorForFix { next, did, index } => {
+                Self::RemoteAction(next, PeerRingRemoteAction::FindSuccessorForFix {
+                    did,
+                    index,
+                })
+            }
             DhtActionFunctor::QueryForSuccessorList { successor } => {
                 Self::RemoteAction(successor, PeerRingRemoteAction::QueryForSuccessorList)
             }
@@ -724,10 +726,10 @@ mod tests {
         let index = 11;
 
         let effect = single_effect(lower_dht_action(
-            &PeerRingAction::RemoteAction(
-                next,
-                PeerRingRemoteAction::FindSuccessorForFix { did: target, index },
-            ),
+            &PeerRingAction::RemoteAction(next, PeerRingRemoteAction::FindSuccessorForFix {
+                did: target,
+                index,
+            }),
             |_| true,
         ))?;
 
diff --git a/crates/core/src/message/encoder.rs b/crates/core/src/message/encoder.rs
index 87e6b20e8..330531467 100644
--- a/crates/core/src/message/encoder.rs
+++ b/crates/core/src/message/encoder.rs
@@ -135,9 +135,7 @@ impl Encoded {
 
     /// Decode this value into a target type implementing [`Decoder`].
     pub fn decode(&self) -> Result
-    where
-        T: Decoder,
-    {
+    where T: Decoder {
         T::from_encoded(self)
     }
 }
diff --git a/crates/core/src/message/handlers/connection.rs b/crates/core/src/message/handlers/connection.rs
index 9ad48e30c..91118538f 100644
--- a/crates/core/src/message/handlers/connection.rs
+++ b/crates/core/src/message/handlers/connection.rs
@@ -542,27 +542,27 @@ pub mod tests {
             node1.assert_transports(vec![node2.did(), node3.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node1.did(), node2.did()]);
-            assert_eq!(
-                node1.dht().successors().list()?,
-                vec![node2.did(), node3.did()]
-            );
-            assert_eq!(
-                node2.dht().successors().list()?,
-                vec![node3.did(), node1.did()]
-            );
-            assert_eq!(
-                node3.dht().successors().list()?,
-                vec![node1.did(), node2.did()]
-            );
+            assert_eq!(node1.dht().successors().list()?, vec![
+                node2.did(),
+                node3.did()
+            ]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node3.did(),
+                node1.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![
+                node1.did(),
+                node2.did()
+            ]);
         } else {
             node1.assert_transports(vec![node2.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node2.did()]);
             assert_eq!(node1.dht().successors().list()?, vec![node2.did(),]);
-            assert_eq!(
-                node2.dht().successors().list()?,
-                vec![node3.did(), node1.did()]
-            );
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node3.did(),
+                node1.did()
+            ]);
             assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
         }
 
@@ -580,18 +580,18 @@ pub mod tests {
         node1.assert_transports(vec![node2.did(), node3.did()]);
         node2.assert_transports(vec![node1.did(), node3.did()]);
         node3.assert_transports(vec![node1.did(), node2.did()]);
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![node2.did(), node3.did()]
-        );
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node3.did(), node1.did()]
-        );
-        assert_eq!(
-            node3.dht().successors().list()?,
-            vec![node1.did(), node2.did()]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did()
+        ]);
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node3.did(),
+            node1.did()
+        ]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node1.did(),
+            node2.did()
+        ]);
 
         Ok((node1, node2, node3))
     }
@@ -630,27 +630,27 @@ pub mod tests {
             node1.assert_transports(vec![node2.did(), node3.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node1.did(), node2.did()]);
-            assert_eq!(
-                node1.dht().successors().list()?,
-                vec![node3.did(), node2.did()]
-            );
-            assert_eq!(
-                node2.dht().successors().list()?,
-                vec![node1.did(), node3.did()]
-            );
-            assert_eq!(
-                node3.dht().successors().list()?,
-                vec![node2.did(), node1.did()]
-            );
+            assert_eq!(node1.dht().successors().list()?, vec![
+                node3.did(),
+                node2.did()
+            ]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node1.did(),
+                node3.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![
+                node2.did(),
+                node1.did()
+            ]);
         } else {
             node1.assert_transports(vec![node2.did()]);
             node2.assert_transports(vec![node1.did(), node3.did()]);
             node3.assert_transports(vec![node2.did()]);
             assert_eq!(node1.dht().successors().list()?, vec![node2.did()]);
-            assert_eq!(
-                node2.dht().successors().list()?,
-                vec![node1.did(), node3.did()]
-            );
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node1.did(),
+                node3.did()
+            ]);
             assert_eq!(node3.dht().successors().list()?, vec![node2.did()]);
         }
 
@@ -668,18 +668,18 @@ pub mod tests {
         node1.assert_transports(vec![node2.did(), node3.did()]);
         node2.assert_transports(vec![node1.did(), node3.did()]);
         node3.assert_transports(vec![node1.did(), node2.did()]);
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![node3.did(), node2.did()]
-        );
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node1.did(), node3.did()]
-        );
-        assert_eq!(
-            node3.dht().successors().list()?,
-            vec![node2.did(), node1.did()]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node3.did(),
+            node2.did()
+        ]);
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node1.did(),
+            node3.did()
+        ]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node2.did(),
+            node1.did()
+        ]);
 
         Ok((node1, node2, node3))
     }
@@ -729,22 +729,26 @@ pub mod tests {
         node2.assert_transports(vec![node3.did(), node4.did(), node1.did()]);
         node3.assert_transports(vec![node4.did(), node1.did(), node2.did()]);
         node4.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![node2.did(), node3.did(), node4.did(),]
-        );
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node3.did(), node4.did(), node1.did(),]
-        );
-        assert_eq!(
-            node3.dht().successors().list()?,
-            vec![node4.did(), node1.did(), node2.did(),]
-        );
-        assert_eq!(
-            node4.dht().successors().list()?,
-            vec![node1.did(), node2.did(), node3.did(),]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did(),
+            node4.did(),
+        ]);
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node3.did(),
+            node4.did(),
+            node1.did(),
+        ]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node4.did(),
+            node1.did(),
+            node2.did(),
+        ]);
+        assert_eq!(node4.dht().successors().list()?, vec![
+            node1.did(),
+            node2.did(),
+            node3.did(),
+        ]);
 
         println!("========================================");
         println!("| test node4 connect node3 via dht     |");
@@ -785,22 +789,26 @@ pub mod tests {
         node2.assert_transports(vec![node3.did(), node4.did(), node1.did()]);
         node3.assert_transports(vec![node4.did(), node1.did(), node2.did()]);
         node4.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![node2.did(), node3.did(), node4.did()]
-        );
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node3.did(), node4.did(), node1.did(),]
-        );
-        assert_eq!(
-            node3.dht().successors().list()?,
-            vec![node4.did(), node1.did(), node2.did(),]
-        );
-        assert_eq!(
-            node4.dht().successors().list()?,
-            vec![node1.did(), node2.did(), node3.did(),]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did(),
+            node4.did()
+        ]);
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node3.did(),
+            node4.did(),
+            node1.did(),
+        ]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node4.did(),
+            node1.did(),
+            node2.did(),
+        ]);
+        assert_eq!(node4.dht().successors().list()?, vec![
+            node1.did(),
+            node2.did(),
+            node3.did(),
+        ]);
 
         Ok(())
     }
@@ -830,14 +838,16 @@ pub mod tests {
         assert_no_more_msg([&node1, &node2, &node3, &joining]).await;
 
         joining.assert_transports(vec![node1.did(), node2.did(), node3.did()]);
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![joining.did(), node2.did(), node3.did(),]
-        );
-        assert_eq!(
-            joining.dht().successors().list()?,
-            vec![node2.did(), node3.did(), node1.did(),]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            joining.did(),
+            node2.did(),
+            node3.did(),
+        ]);
+        assert_eq!(joining.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did(),
+            node1.did(),
+        ]);
 
         Ok(())
     }
diff --git a/crates/core/src/message/handlers/stabilization.rs b/crates/core/src/message/handlers/stabilization.rs
index 0a14d2fb8..3857d9f73 100644
--- a/crates/core/src/message/handlers/stabilization.rs
+++ b/crates/core/src/message/handlers/stabilization.rs
@@ -319,10 +319,10 @@ mod test {
                 ..
             }) => {
                 assert_eq!(purpose, StorageSyncPurpose::OwnershipHandoff);
-                assert_eq!(
-                    acks,
-                    vec![SyncedEntryAck::new(entry.did, stored_entry.clone())]
-                );
+                assert_eq!(acks, vec![SyncedEntryAck::new(
+                    entry.did,
+                    stored_entry.clone()
+                )]);
             }
             message => {
                 return Err(Error::InvalidMessage(format!(
@@ -365,18 +365,18 @@ mod test {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before stabilization ===");
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![node2.did(), node3.did()]
-        );
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node3.did(), node1.did()]
-        );
-        assert_eq!(
-            node3.dht().successors().list()?,
-            vec![node1.did(), node2.did()]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node2.did(),
+            node3.did()
+        ]);
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node3.did(),
+            node1.did()
+        ]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node1.did(),
+            node2.did()
+        ]);
         assert!(node1.dht().lock_predecessor()?.is_none());
         assert!(node2.dht().lock_predecessor()?.is_none());
         assert!(node3.dht().lock_predecessor()?.is_none());
@@ -394,10 +394,10 @@ mod test {
 
         println!("=== Check state after first stabilization ===");
         assert!(node1.dht().successors().list()?.contains(&node2.did()));
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node3.did(), node1.did()]
-        );
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node3.did(),
+            node1.did()
+        ]);
         assert!(node3.dht().successors().list()?.contains(&node2.did()));
 
         println!("==========================================");
@@ -413,18 +413,18 @@ mod test {
             assert_no_more_msg([&node1, &node2, &node3]).await;
 
             println!("=== Check state after stabilization ===");
-            assert_eq!(
-                node1.dht().successors().list()?,
-                vec![node2.did(), node3.did()]
-            );
-            assert_eq!(
-                node2.dht().successors().list()?,
-                vec![node3.did(), node1.did()]
-            );
-            assert_eq!(
-                node3.dht().successors().list()?,
-                vec![node1.did(), node2.did()]
-            );
+            assert_eq!(node1.dht().successors().list()?, vec![
+                node2.did(),
+                node3.did()
+            ]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node3.did(),
+                node1.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![
+                node1.did(),
+                node2.did()
+            ]);
         }
 
         println!("=== Check predecessor after all stabilization ===");
@@ -460,18 +460,18 @@ mod test {
         assert_no_more_msg([&node1, &node2, &node3]).await;
 
         println!("=== Check state before stabilization ===");
-        assert_eq!(
-            node1.dht().successors().list()?,
-            vec![node3.did(), node2.did()]
-        );
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node1.did(), node3.did()]
-        );
-        assert_eq!(
-            node3.dht().successors().list()?,
-            vec![node2.did(), node1.did()]
-        );
+        assert_eq!(node1.dht().successors().list()?, vec![
+            node3.did(),
+            node2.did()
+        ]);
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node1.did(),
+            node3.did()
+        ]);
+        assert_eq!(node3.dht().successors().list()?, vec![
+            node2.did(),
+            node1.did()
+        ]);
         assert!(node1.dht().lock_predecessor()?.is_none());
         assert!(node2.dht().lock_predecessor()?.is_none());
         assert!(node3.dht().lock_predecessor()?.is_none());
@@ -489,10 +489,10 @@ mod test {
 
         println!("=== Check state after first stabilization ===");
         assert!(node1.dht().successors().list()?.contains(&node2.did()));
-        assert_eq!(
-            node2.dht().successors().list()?,
-            vec![node1.did(), node3.did()]
-        );
+        assert_eq!(node2.dht().successors().list()?, vec![
+            node1.did(),
+            node3.did()
+        ]);
         assert!(node3.dht().successors().list()?.contains(&node2.did()));
 
         println!("==========================================");
@@ -508,18 +508,18 @@ mod test {
             assert_no_more_msg([&node1, &node2, &node3]).await;
 
             println!("=== Check state after stabilization ===");
-            assert_eq!(
-                node1.dht().successors().list()?,
-                vec![node3.did(), node2.did()]
-            );
-            assert_eq!(
-                node2.dht().successors().list()?,
-                vec![node1.did(), node3.did()]
-            );
-            assert_eq!(
-                node3.dht().successors().list()?,
-                vec![node2.did(), node1.did()]
-            );
+            assert_eq!(node1.dht().successors().list()?, vec![
+                node3.did(),
+                node2.did()
+            ]);
+            assert_eq!(node2.dht().successors().list()?, vec![
+                node1.did(),
+                node3.did()
+            ]);
+            assert_eq!(node3.dht().successors().list()?, vec![
+                node2.did(),
+                node1.did()
+            ]);
         }
 
         println!("=== Check predecessor after all stabilization ===");
diff --git a/crates/core/src/message/handlers/storage/tests/test_repair.rs b/crates/core/src/message/handlers/storage/tests/test_repair.rs
index 67fad7495..0ab1df80c 100644
--- a/crates/core/src/message/handlers/storage/tests/test_repair.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_repair.rs
@@ -257,26 +257,20 @@ async fn found_entry_repairs_buffered_misses_only() -> Result<()> {
     node.swarm.transport.start_storage_lookup(entry.did, 2)?;
 
     handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![],
-                misses: vec![PlacementMiss::new(placement_key, node.did())],
-                resource: entry.did,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![],
+            misses: vec![PlacementMiss::new(placement_key, node.did())],
+            resource: entry.did,
+            redundancy: 2,
+        })
         .await?;
     handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![entry.clone()],
-                misses: vec![],
-                resource: entry.did,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![entry.clone()],
+            misses: vec![],
+            resource: entry.did,
+            redundancy: 2,
+        })
         .await?;
 
     assert_eq!(
@@ -320,15 +314,12 @@ async fn found_entry_rejects_multiple_entries() -> Result<()> {
     )?;
 
     let result = handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![first, second],
-                misses: vec![],
-                resource,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![first, second],
+            misses: vec![],
+            resource,
+            redundancy: 2,
+        })
         .await;
 
     assert!(
@@ -365,15 +356,12 @@ async fn found_entry_rejects_redundancy_outside_local_protocol_mode() -> Result<
     node.swarm.transport.start_storage_lookup(resource, 2)?;
 
     let result = handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![entry],
-                misses: vec![],
-                resource,
-                redundancy: 3,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![entry],
+            misses: vec![],
+            resource,
+            redundancy: 3,
+        })
         .await;
 
     assert!(matches!(
@@ -412,15 +400,12 @@ async fn found_entry_rejects_response_without_active_lookup() -> Result<()> {
     )?;
 
     let result = handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![entry],
-                misses: vec![],
-                resource,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![entry],
+            misses: vec![],
+            resource,
+            redundancy: 2,
+        })
         .await;
 
     assert!(matches!(
@@ -457,15 +442,12 @@ async fn found_entry_rejects_resource_mismatch_without_cache_write() -> Result<(
     node.swarm.transport.start_storage_lookup(resource, 2)?;
 
     let result = handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![entry.clone()],
-                misses: vec![],
-                resource,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![entry.clone()],
+            misses: vec![],
+            resource,
+            redundancy: 2,
+        })
         .await;
 
     assert!(matches!(
@@ -484,11 +466,9 @@ async fn storage_miss_observation_buffer_is_bounded() -> Result<()> {
         let resource = Did::from((index + 1) as u32);
         let placement = Did::from((index + 10_000) as u32);
         node.swarm.transport.start_storage_lookup(resource, 2)?;
-        node.swarm.transport.observe_storage_misses(
-            resource,
-            2,
-            [PlacementMiss::new(placement, node.did())],
-        )?;
+        node.swarm
+            .transport
+            .observe_storage_misses(resource, 2, [PlacementMiss::new(placement, node.did())])?;
     }
 
     assert!(
@@ -504,11 +484,9 @@ async fn storage_fetch_starts_fresh_observation_round() -> Result<()> {
     let resource = Did::from(10u32);
     let placement = Did::from(100u32);
     node.swarm.transport.start_storage_lookup(resource, 1)?;
-    node.swarm.transport.observe_storage_misses(
-        resource,
-        1,
-        [PlacementMiss::new(placement, node.did())],
-    )?;
+    node.swarm
+        .transport
+        .observe_storage_misses(resource, 1, [PlacementMiss::new(placement, node.did())])?;
 
     node.swarm.transport.start_storage_lookup(resource, 1)?;
     let misses = node.swarm.transport.take_storage_misses(resource, 1)?;
@@ -549,29 +527,23 @@ async fn expired_storage_response_does_not_update_cache_or_repair() -> Result<()
     node.swarm.transport.start_storage_lookup(entry.did, 2)?;
 
     handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![],
-                misses: vec![PlacementMiss::new(placement_key, node.did())],
-                resource: entry.did,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![],
+            misses: vec![PlacementMiss::new(placement_key, node.did())],
+            resource: entry.did,
+            redundancy: 2,
+        })
         .await?;
     node.swarm
         .transport
         .expire_storage_lookup_observation(entry.did, 2)?;
     let result = handler
-        .handle(
-            &context,
-            &FoundEntry {
-                data: vec![entry.clone()],
-                misses: vec![],
-                resource: entry.did,
-                redundancy: 2,
-            },
-        )
+        .handle(&context, &FoundEntry {
+            data: vec![entry.clone()],
+            misses: vec![],
+            resource: entry.did,
+            redundancy: 2,
+        })
         .await;
 
     assert!(matches!(
diff --git a/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs b/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs
index 99fb3e504..78c863861 100644
--- a/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_storage_sync_report.rs
@@ -79,10 +79,10 @@ async fn sync_entries_handler_reports_persisted_entries() -> Result<()> {
     let payload = next_payload(&sender).await?;
     match payload.transaction.data::()? {
         Message::SyncEntriesWithSuccessorReport(report) => {
-            assert_eq!(
-                report.acks,
-                vec![SyncedEntryAck::new(placement_key, stored_entry.clone())]
-            );
+            assert_eq!(report.acks, vec![SyncedEntryAck::new(
+                placement_key,
+                stored_entry.clone()
+            )]);
         }
         message => {
             return Err(Error::InvalidMessage(format!(
@@ -120,10 +120,10 @@ async fn persist_synced_entries_returns_acks_for_owned_entries() -> Result<()> {
 
     let acks = persist_synced_entries(&handler, &sync_msg).await?;
 
-    assert_eq!(
-        acks,
-        vec![SyncedEntryAck::new(placement_key, stored_entry.clone())]
-    );
+    assert_eq!(acks, vec![SyncedEntryAck::new(
+        placement_key,
+        stored_entry.clone()
+    )]);
     assert_eq!(
         receiver
             .dht()
diff --git a/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs b/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs
index 666c20c6f..79f342029 100644
--- a/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs
+++ b/crates/core/src/message/handlers/storage/tests/test_sync_receive.rs
@@ -85,14 +85,11 @@ async fn sync_entries_handler_stores_entry_at_placement_key() -> Result<()> {
     )?;
 
     handler
-        .handle(
-            &context,
-            &SyncEntriesWithSuccessor {
-                purpose: StorageSyncPurpose::OwnershipHandoff,
-                destination: StorageSyncDestination::PhysicalOwner(node.did()),
-                data: vec![PlacedEntry::new(placement_key, entry.clone())],
-            },
-        )
+        .handle(&context, &SyncEntriesWithSuccessor {
+            purpose: StorageSyncPurpose::OwnershipHandoff,
+            destination: StorageSyncDestination::PhysicalOwner(node.did()),
+            data: vec![PlacedEntry::new(placement_key, entry.clone())],
+        })
         .await?;
 
     assert_eq!(
@@ -128,14 +125,11 @@ async fn sync_entries_handler_caps_inbound_entry_payloads() -> Result<()> {
     )?;
 
     handler
-        .handle(
-            &context,
-            &SyncEntriesWithSuccessor {
-                purpose: StorageSyncPurpose::OwnershipHandoff,
-                destination: StorageSyncDestination::PhysicalOwner(node.did()),
-                data: vec![PlacedEntry::new(placement_key, entry)],
-            },
-        )
+        .handle(&context, &SyncEntriesWithSuccessor {
+            purpose: StorageSyncPurpose::OwnershipHandoff,
+            destination: StorageSyncDestination::PhysicalOwner(node.did()),
+            data: vec![PlacedEntry::new(placement_key, entry)],
+        })
         .await?;
 
     let stored = node
@@ -181,17 +175,14 @@ async fn sync_entries_handler_rejects_non_affine_placement_before_writing() -> R
     )?;
 
     let result = handler
-        .handle(
-            &context,
-            &SyncEntriesWithSuccessor {
-                purpose: StorageSyncPurpose::OwnershipHandoff,
-                destination: StorageSyncDestination::PhysicalOwner(node.did()),
-                data: vec![
-                    PlacedEntry::new(valid_placement, valid_entry),
-                    PlacedEntry::new(invalid_placement, invalid_entry),
-                ],
-            },
-        )
+        .handle(&context, &SyncEntriesWithSuccessor {
+            purpose: StorageSyncPurpose::OwnershipHandoff,
+            destination: StorageSyncDestination::PhysicalOwner(node.did()),
+            data: vec![
+                PlacedEntry::new(valid_placement, valid_entry),
+                PlacedEntry::new(invalid_placement, invalid_entry),
+            ],
+        })
         .await;
 
     assert!(matches!(result, Err(Error::InvalidMessage(_))));
diff --git a/crates/core/src/message/payload.rs b/crates/core/src/message/payload.rs
index c8289ef10..179a016df 100644
--- a/crates/core/src/message/payload.rs
+++ b/crates/core/src/message/payload.rs
@@ -39,9 +39,7 @@ pub fn encode_data_gzip(data: &Bytes, level: u8) -> Result {
 
 /// Serializes the given data using JSON and compresses it with gzip using the specified compression level.
 pub fn gzip_data(data: &T, level: u8) -> Result
-where
-    T: Serialize,
-{
+where T: Serialize {
     let json_bytes = serde_json::to_vec(data).map_err(|_| Error::SerializeToString)?;
     encode_data_gzip(&json_bytes.into(), level)
 }
@@ -58,9 +56,7 @@ pub fn decode_gzip_data(data: &Bytes) -> Result {
 
 /// From gzip data to deserialized
 pub fn from_gzipped_data(data: &Bytes) -> Result
-where
-    T: DeserializeOwned,
-{
+where T: DeserializeOwned {
     let data = decode_gzip_data(data)?;
     let m = serde_json::from_slice(&data).map_err(Error::Deserialize)?;
     Ok(m)
@@ -175,9 +171,7 @@ impl Transaction {
 
     /// Deserializes the data field into a `T` instance.
     pub fn data(&self) -> Result
-    where
-        T: DeserializeOwned,
-    {
+    where T: DeserializeOwned {
         bincode::deserialize(&self.data).map_err(Error::BincodeDeserialize)
     }
 }
@@ -375,9 +369,7 @@ pub trait PayloadSender {
 
     /// Send a message to a specified destination.
     async fn send_message(&self, msg: T, destination: Did) -> Result
-    where
-        T: Serialize + Send,
-    {
+    where T: Serialize + Send {
         let next_hop = self.infer_next_hop(destination, None)?;
         self.send_message_by_hop(msg, destination, next_hop).await
     }
@@ -399,18 +391,14 @@ pub trait PayloadSender {
 
     /// Send a direct message to a specified destination.
     async fn send_direct_message(&self, msg: T, destination: Did) -> Result
-    where
-        T: Serialize + Send,
-    {
+    where T: Serialize + Send {
         self.send_message_by_hop(msg, destination, destination)
             .await
     }
 
     /// Send a report message to a specified destination.
     async fn send_report_message(&self, payload: &MessagePayload, msg: T) -> Result<()>
-    where
-        T: Serialize + Send,
-    {
+    where T: Serialize + Send {
         let policy = payload.transaction.report_return;
         // Keep this send-boundary check even though transaction verification
         // enforces the same authorization when the request is received.
@@ -487,9 +475,7 @@ pub mod test {
     }
 
     pub fn new_payload(data: T, next_hop: Did) -> MessagePayload
-    where
-        T: Serialize + DeserializeOwned,
-    {
+    where T: Serialize + DeserializeOwned {
         let key = SecretKey::random();
         let destination = SecretKey::random().address().into();
         let session_sk = SessionSk::new_with_seckey(&key).unwrap();
diff --git a/crates/core/src/message/protocols/relay.rs b/crates/core/src/message/protocols/relay.rs
index 640cf51eb..39e20b1bb 100644
--- a/crates/core/src/message/protocols/relay.rs
+++ b/crates/core/src/message/protocols/relay.rs
@@ -194,9 +194,7 @@ impl MessageRelay {
 const INFINITE_LOOP_TOLERANCE: usize = 3;
 
 fn has_infinite_loop(path: &[T]) -> bool
-where
-    T: PartialEq,
-{
+where T: PartialEq {
     // Invariant: a relay loop is witnessed by a non-empty suffix period P such
     // that the final path segment is P repeated INFINITE_LOOP_TOLERANCE times.
     for period in 1..=path.len() / INFINITE_LOOP_TOLERANCE {
diff --git a/crates/core/src/storage/idb.rs b/crates/core/src/storage/idb.rs
index 8b1391f07..e38351a24 100644
--- a/crates/core/src/storage/idb.rs
+++ b/crates/core/src/storage/idb.rs
@@ -155,8 +155,7 @@ impl IdbStorage {
 
 #[async_trait(?Send)]
 impl KvStorageInterface for IdbStorage
-where
-    V: DeserializeOwned + Serialize + Sized,
+where V: DeserializeOwned + Serialize + Sized
 {
     async fn get(&self, key: &str) -> Result> {
         let (tx, store) = self.get_tx_store(TransactionMode::ReadWrite)?;
diff --git a/crates/core/src/storage/memory.rs b/crates/core/src/storage/memory.rs
index e1d6764d1..e8fe78605 100644
--- a/crates/core/src/storage/memory.rs
+++ b/crates/core/src/storage/memory.rs
@@ -7,15 +7,13 @@ use crate::storage::KvStorageInterface;
 /// In-memory storage implementation backed by a concurrent map.
 #[derive(Debug, Default)]
 pub struct MemStorage
-where
-    V: Clone,
+where V: Clone
 {
     table: DashMap,
 }
 
 impl MemStorage
-where
-    V: Clone,
+where V: Clone
 {
     /// Create an empty memory storage table.
     pub fn new() -> Self {
@@ -28,8 +26,7 @@ where
 #[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
 impl KvStorageInterface for MemStorage
-where
-    V: Clone + Send + Sync,
+where V: Clone + Send + Sync
 {
     async fn get(&self, key: &str) -> Result> {
         Ok(self.table.get(&key.to_string()).map(|v| v.value().clone()))
diff --git a/crates/core/src/storage/sled.rs b/crates/core/src/storage/sled.rs
index 6cedd9dea..846b74204 100644
--- a/crates/core/src/storage/sled.rs
+++ b/crates/core/src/storage/sled.rs
@@ -24,9 +24,7 @@ impl SledStorage {
     /// * cap: max_size in bytes
     /// * path: db file location
     pub async fn new_with_cap_and_path
(cap: u32, path: P) -> Result
-    where
-        P: AsRef,
-    {
+    where P: AsRef {
         let db = sled::Config::new()
             .path(path.as_ref())
             .mode(sled::Mode::HighThroughput)
@@ -43,8 +41,7 @@ impl SledStorage {
 
 #[async_trait]
 impl KvStorageInterface for SledStorage
-where
-    V: Serialize + DeserializeOwned + Sync,
+where V: Serialize + DeserializeOwned + Sync
 {
     async fn get(&self, key: &str) -> Result> {
         let v = self.db.get(key).map_err(Error::SledError)?;
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index 611f39cfd..221a6ad02 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -473,6 +473,16 @@ impl SwarmTransport {
             Ok(offer) => offer,
             Err(Error::AlreadyConnected) => return Err(Error::AlreadyConnected),
             Err(e) => {
+                if self.get_connection(peer).is_some() {
+                    tracing::info!(
+                        target: "rings_core::swarm::transport::handshake",
+                        local = %self.dht.did,
+                        peer = %peer,
+                        error = ?e,
+                        "connection request satisfied by concurrent handshake"
+                    );
+                    return Ok(());
+                }
                 self.record_peer_message_send_failed(peer).await;
                 return Err(e);
             }
@@ -511,6 +521,17 @@ impl SwarmTransport {
                 );
                 self.abandon_pending_connection(attempt, "sending connection offer")
                     .await;
+                if self.get_connection(peer).is_some() {
+                    tracing::info!(
+                        target: "rings_core::swarm::transport::handshake",
+                        local = %self.dht.did,
+                        peer = %peer,
+                        generation = attempt.generation,
+                        error = ?error,
+                        "connection offer send failure satisfied by concurrent handshake"
+                    );
+                    return Ok(());
+                }
                 return Err(error);
             }
         }
@@ -983,7 +1004,17 @@ impl PayloadSender for SwarmTransport {
 #[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
 impl LiveDid for SwarmConnection {
     async fn live(&self) -> bool {
-        self.webrtc_connection_state() == WebrtcConnectionState::Connected
+        match self.connection.data_channel_is_open() {
+            Ok(open) => open,
+            Err(error) => {
+                tracing::debug!(
+                    peer = %self.peer,
+                    error = ?error,
+                    "failed to inspect data-channel liveness"
+                );
+                false
+            }
+        }
     }
 }
 
diff --git a/crates/core/src/swarm/transport/pending.rs b/crates/core/src/swarm/transport/pending.rs
index 787242d3e..84997fe66 100644
--- a/crates/core/src/swarm/transport/pending.rs
+++ b/crates/core/src/swarm/transport/pending.rs
@@ -77,13 +77,10 @@ impl PendingPeerPool {
             peer,
             generation: self.next_generation,
         };
-        self.peers.insert(
-            peer,
-            PendingPeer {
-                generation: attempt.generation,
-                admitted_at_ms: now_ms,
-            },
-        );
+        self.peers.insert(peer, PendingPeer {
+            generation: attempt.generation,
+            admitted_at_ms: now_ms,
+        });
         Ok(attempt)
     }
 
@@ -433,7 +430,7 @@ mod lifecycle_model {
                 return;
             }
             self.remember_current_generation();
-            self.next_generation = self.next_generation.saturating_add(1);
+            self.next_generation = self.next_generation.wrapping_add(1);
             self.peer = PeerLifecycle::Pending(self.next_generation);
             self.dht_member = false;
             self.transport_slot = true;
@@ -541,6 +538,19 @@ mod lifecycle_model {
         explore(LifecycleModel::default(), &actions, MAX_DEPTH);
     }
 
+    #[test]
+    fn pending_admission_model_matches_wrapping_generation_boundary() {
+        let model = LifecycleModel {
+            next_generation: u64::MAX,
+            ..LifecycleModel::default()
+        }
+        .apply(LifecycleAction::Replacement);
+
+        assert_eq!(model.peer, PeerLifecycle::Pending(0));
+        assert_eq!(model.next_generation, 0);
+        model.assert_invariants();
+    }
+
     fn explore(model: LifecycleModel, actions: &[LifecycleAction], remaining_depth: usize) {
         model.assert_invariants();
         if remaining_depth == 0 {
diff --git a/crates/core/src/swarm/transport/storage_lookup.rs b/crates/core/src/swarm/transport/storage_lookup.rs
index 5f413eb35..960c41b86 100644
--- a/crates/core/src/swarm/transport/storage_lookup.rs
+++ b/crates/core/src/swarm/transport/storage_lookup.rs
@@ -105,13 +105,10 @@ impl SwarmTransport {
         let now = storage_lookup_observation_now_ms();
         evict_storage_lookup_observations(&mut observations, now);
         reserve_storage_lookup_observation_slot(&mut observations);
-        observations.insert(
-            key,
-            StorageLookupObservation {
-                observed_at_ms: now,
-                misses: BTreeSet::new(),
-            },
-        );
+        observations.insert(key, StorageLookupObservation {
+            observed_at_ms: now,
+            misses: BTreeSet::new(),
+        });
         Ok(())
     }
 
diff --git a/crates/core/src/swarm/transport/tests.rs b/crates/core/src/swarm/transport/tests.rs
index 4354e024f..9615f103e 100644
--- a/crates/core/src/swarm/transport/tests.rs
+++ b/crates/core/src/swarm/transport/tests.rs
@@ -241,6 +241,45 @@ async fn pending_offer_is_not_routable_or_visible_to_dht() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn data_channel_open_admits_successor_before_ice_connected() -> Result<()> {
+    let transport = Arc::new(transport_with_measure(Arc::new(
+        RecordingMeasure::default(),
+    ))?);
+    let peer = SecretKey::random().address().into();
+    let callback = InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback));
+    let (attempt, _offer) = transport
+        .prepare_connection_offer_with_attempt(peer, callback)
+        .await?;
+    let connection = transport
+        .get_raw_connection(peer)
+        .ok_or(Error::SwarmMissTransport(peer))?;
+
+    connection
+        .connection
+        .webrtc_answer_offer("remote-dummy-connection".to_string())
+        .await
+        .map_err(Error::Transport)?;
+    assert_eq!(
+        connection.webrtc_connection_state(),
+        WebrtcConnectionState::Connecting
+    );
+    assert!(connection.connection.data_channel_is_open()?);
+
+    let callback = InnerSwarmCallback::new(Arc::clone(&transport), Arc::new(NoopSwarmCallback))
+        .with_pending_connection_attempt(attempt);
+    callback
+        .on_data_channel_open(&peer.to_string())
+        .await
+        .map_err(|error| Error::InvalidMessage(error.to_string()))?;
+
+    assert!(transport.is_admitted_connection(peer));
+    assert!(transport.dht.successors().contains(&peer)?);
+
+    transport.disconnect(peer).await?;
+    Ok(())
+}
+
 #[tokio::test]
 async fn local_did_lifecycle_callbacks_are_ignored() -> Result<()> {
     let transport = Arc::new(transport_with_measure(Arc::new(
@@ -369,14 +408,11 @@ async fn disconnected_observation_is_once_per_connection_epoch() -> Result<()> {
     transport.record_peer_disconnected(peer).await;
     assert!(transport.peer_disconnected_since_ms(peer).is_some());
 
-    assert_eq!(
-        measure.snapshot_counters()?.as_slice(),
-        &[
-            (peer, MeasureCounter::Disconnected),
-            (peer, MeasureCounter::Connect),
-            (peer, MeasureCounter::Disconnected),
-        ]
-    );
+    assert_eq!(measure.snapshot_counters()?.as_slice(), &[
+        (peer, MeasureCounter::Disconnected),
+        (peer, MeasureCounter::Connect),
+        (peer, MeasureCounter::Disconnected),
+    ]);
 
     Ok(())
 }
diff --git a/crates/core/src/tests/wasm/test_idb_storage.rs b/crates/core/src/tests/wasm/test_idb_storage.rs
index 19a5f62bb..a78983bb3 100644
--- a/crates/core/src/tests/wasm/test_idb_storage.rs
+++ b/crates/core/src/tests/wasm/test_idb_storage.rs
@@ -24,9 +24,7 @@ async fn create_db_instance(cap: u32) -> IdbStorage {
 }
 
 async fn create_kv_db(cap: u32) -> Box>
-where
-    V: DeserializeOwned + Serialize + Sized,
-{
+where V: DeserializeOwned + Serialize + Sized {
     Box::new(create_db_instance(cap).await)
 }
 
@@ -192,39 +190,27 @@ async fn test_idb_prune() {
     let key4 = "4".to_string();
     let key5 = "5".to_string();
     instance
-        .put(
-            &key1,
-            &TestDataStruct {
-                content: "test1".to_owned(),
-            },
-        )
+        .put(&key1, &TestDataStruct {
+            content: "test1".to_owned(),
+        })
         .await
         .unwrap();
     instance
-        .put(
-            &key2,
-            &TestDataStruct {
-                content: "test2".to_owned(),
-            },
-        )
+        .put(&key2, &TestDataStruct {
+            content: "test2".to_owned(),
+        })
         .await
         .unwrap();
     instance
-        .put(
-            &key3,
-            &TestDataStruct {
-                content: "test3".to_owned(),
-            },
-        )
+        .put(&key3, &TestDataStruct {
+            content: "test3".to_owned(),
+        })
         .await
         .unwrap();
     instance
-        .put(
-            &key4,
-            &TestDataStruct {
-                content: "test4".to_owned(),
-            },
-        )
+        .put(&key4, &TestDataStruct {
+            content: "test4".to_owned(),
+        })
         .await
         .unwrap();
 
@@ -238,12 +224,9 @@ async fn test_idb_prune() {
     tracing::debug!("d2, {:?}", d2);
 
     instance
-        .put(
-            &key5,
-            &TestDataStruct {
-                content: "test5".to_owned(),
-            },
-        )
+        .put(&key5, &TestDataStruct {
+            content: "test5".to_owned(),
+        })
         .await
         .unwrap();
 
diff --git a/crates/core/src/utils.rs b/crates/core/src/utils.rs
index 0698d6a2b..a23ded85d 100644
--- a/crates/core/src/utils.rs
+++ b/crates/core/src/utils.rs
@@ -248,9 +248,7 @@ pub mod js_utils {
     }
 
     fn schedule_sleep(resolve: js_sys::Function, reject: js_sys::Function, schedule: F)
-    where
-        F: FnOnce(&js_sys::Function) -> Result,
-    {
+    where F: FnOnce(&js_sys::Function) -> Result {
         let func = Closure::once_into_js(move || {
             resolve_sleep(&resolve);
         });
diff --git a/crates/node/src/error.rs b/crates/node/src/error.rs
index 597ff67d3..ffaffaea9 100644
--- a/crates/node/src/error.rs
+++ b/crates/node/src/error.rs
@@ -211,11 +211,11 @@ pub enum Error {
     #[error("Wrong field, should be {0}")]
     SNARKWrongField(String) = 1403,
     /// Converting a JavaScript bigint into a prime-field element was out of range.
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     #[error("range error when covering js_sys::BigInt to PrimeField: {0}")]
     SNARKFFRangeError(String) = 1404,
     /// Converting a JavaScript bigint produced an empty representation.
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     #[error("Failed to load bigint to repr string, it's empty")]
     SNARKBigIntValueEmpty() = 1405,
     /// Loading a string as a prime-field element failed.
@@ -277,7 +277,7 @@ impl From for Error {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 impl From for wasm_bindgen::JsValue {
     fn from(err: Error) -> Self {
         wasm_bindgen::JsValue::from_str(&err.to_string())
diff --git a/crates/node/src/extension/ext/interpret.rs b/crates/node/src/extension/ext/interpret.rs
index 958442fe7..bb3c439f3 100644
--- a/crates/node/src/extension/ext/interpret.rs
+++ b/crates/node/src/extension/ext/interpret.rs
@@ -17,8 +17,11 @@ use crate::error::Result;
 /// namespace nor a remote `from`. A hard failure is an `Err`. Defined per-effect outcomes (e.g.
 /// "addressed no live session") are the extension's own concern and surfaced however it likes
 /// (its own return shapes / tests), not a core enum.
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 pub trait Interpret {
     /// The effect algebra this shell interprets — the same as its protocol's `Effect`.
     type Effect;
diff --git a/crates/node/src/extension/ext/mod.rs b/crates/node/src/extension/ext/mod.rs
index e6c65409e..462c38278 100644
--- a/crates/node/src/extension/ext/mod.rs
+++ b/crates/node/src/extension/ext/mod.rs
@@ -55,12 +55,12 @@ pub use registry::Scope;
 ///
 /// Lets the pure-core types be written once; the `Send`-ness divergence (browser futures
 /// are not `Send`) is confined here. `∀ T` on browser; `Send + Sync` elsewhere.
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 pub trait MaybeSend: Send + Sync {}
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 impl MaybeSend for T {}
 /// Auto-trait bound that is `Send + Sync` on native and empty on browser.
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub trait MaybeSend {}
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 impl MaybeSend for T {}
diff --git a/crates/node/src/extension/ext/registry.rs b/crates/node/src/extension/ext/registry.rs
index 92fa75e5e..cf7bd62ae 100644
--- a/crates/node/src/extension/ext/registry.rs
+++ b/crates/node/src/extension/ext/registry.rs
@@ -36,18 +36,21 @@ use crate::processor::Processor;
 const MAX_FIXPOINT_STEPS: u32 = 1024;
 
 /// Type-erased handler stored in the registry: native is `Send + Sync`, browser not.
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 pub(crate) type DynHandler = dyn Handler + Send + Sync;
 /// Type-erased handler stored in the registry.
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) type DynHandler = dyn Handler;
 
 type HandlerMap = RwLock>>;
 
 /// Erased, runtime-facing handler — the router-internal ABI. Implemented once, generically, by
 /// `Runner`; protocol authors never name it (they write `Protocol` + `Interpret`).
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 pub(crate) trait Handler {
     /// Decode → step (pure, committed) → run the protocol's effects, returning re-injected
     /// messages. `handle : (from, payload) → IO [Inbound]`.
@@ -188,8 +191,11 @@ struct Runner {
     state: Mutex,
 }
 
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 impl Handler for Runner
 where
     P: Protocol + MaybeSend + 'static,
diff --git a/crates/node/src/extension/mod.rs b/crates/node/src/extension/mod.rs
index fa8649a8c..24ec1c45c 100644
--- a/crates/node/src/extension/mod.rs
+++ b/crates/node/src/extension/mod.rs
@@ -38,8 +38,8 @@ impl Backend {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl SwarmCallback for Backend {
     async fn on_inbound(&self, payload: &MessagePayload) -> Result<(), Box> {
         let data: Message = payload.transaction.data()?;
diff --git a/crates/node/src/extension/protocols/echo.rs b/crates/node/src/extension/protocols/echo.rs
index 81b323f30..41685d435 100644
--- a/crates/node/src/extension/protocols/echo.rs
+++ b/crates/node/src/extension/protocols/echo.rs
@@ -71,13 +71,10 @@ impl Protocol for Echo {
 
     /// Pure. `step (Ctx n, Echoed{from,p}) = ((n+1), [Reply to=from p])`.
     fn step(&self, ctx: Ctx<'_, u64>, event: Echoed) -> Transition {
-        Transition::with(
-            ctx.state + 1,
-            vec![EchoEffect::Reply {
-                to: event.from,
-                payload: event.payload,
-            }],
-        )
+        Transition::with(ctx.state + 1, vec![EchoEffect::Reply {
+            to: event.from,
+            payload: event.payload,
+        }])
     }
 }
 
@@ -85,8 +82,11 @@ impl Protocol for Echo {
 #[derive(Default)]
 pub struct EchoShell;
 
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 impl Interpret for EchoShell {
     type Effect = EchoEffect;
 
diff --git a/crates/node/src/extension/protocols/mod.rs b/crates/node/src/extension/protocols/mod.rs
index cb57ec30e..39e02bd70 100644
--- a/crates/node/src/extension/protocols/mod.rs
+++ b/crates/node/src/extension/protocols/mod.rs
@@ -5,6 +5,6 @@
 //! platform (`NativeRelay` / `WtRelay`).
 
 pub mod echo;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub mod js;
 pub mod relay;
diff --git a/crates/node/src/extension/protocols/relay.rs b/crates/node/src/extension/protocols/relay.rs
index 707b7a194..5508749d8 100644
--- a/crates/node/src/extension/protocols/relay.rs
+++ b/crates/node/src/extension/protocols/relay.rs
@@ -219,8 +219,7 @@ impl Relay {
 }
 
 impl Protocol for Relay
-where
-    T: Clone + DeserializeOwned + Serialize + MaybeSend + 'static,
+where T: Clone + DeserializeOwned + Serialize + MaybeSend + 'static
 {
     type State = RelayState;
     type Event = RelayEvent;
@@ -300,14 +299,11 @@ fn step_command(
             // A locally-accepted tunnel: we are the initiator.
             let key = SessionKey::new(peer, namespace, session, Initiator::Local);
             next.sessions.insert(key.clone());
-            Transition::with(
-                next,
-                vec![RelayEffect::OpenAccepted {
-                    token,
-                    key,
-                    service,
-                }],
-            )
+            Transition::with(next, vec![RelayEffect::OpenAccepted {
+                token,
+                key,
+                service,
+            }])
         }
         RelayCommand::Untrack {
             peer,
@@ -344,15 +340,12 @@ fn step_frame(
                     next.sessions.insert(key.clone());
                     Transition::with(next, vec![RelayEffect::Connect { key, target, kind }])
                 }
-                None => Transition::with(
-                    state.clone(),
-                    vec![RelayEffect::SendClose {
-                        to: from,
-                        session,
-                        // The peer opened it (unknown service); we did not.
-                        from_opener: false,
-                    }],
-                ),
+                None => Transition::with(state.clone(), vec![RelayEffect::SendClose {
+                    to: from,
+                    session,
+                    // The peer opened it (unknown service); we did not.
+                    from_opener: false,
+                }]),
             }
         }
         // Data/Shutdown/Close are guarded on the authoritative session set: the *reducer*
@@ -485,12 +478,12 @@ impl Interpret for NativeRelay {
 // ── Browser interpreter (WebTransport) ────────────────────────────────────────────────
 
 /// Browser relay interpreter: runs [`RelayEffect`]s over the WebTransport engine it owns.
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) struct WtRelay {
     engine: Arc,
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 impl WtRelay {
     /// Build over a shared WebTransport engine.
     pub(crate) fn new(engine: Arc) -> Self {
@@ -498,7 +491,7 @@ impl WtRelay {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 #[async_trait::async_trait(?Send)]
 impl Interpret for WtRelay {
     type Effect = RelayEffect;
@@ -656,11 +649,9 @@ impl RelayHandle {
 
 /// Map a service `name` → `target` by self-injecting a `RegisterService` command into the
 /// scope's own namespace (provenance = self).
-#[cfg(any(feature = "node", feature = "browser"))]
+#[cfg(any(feature = "node", all(feature = "browser", target_family = "wasm")))]
 async fn register_service(scope: &Scope, name: String, target: T) -> crate::error::Result<()>
-where
-    T: Serialize,
-{
+where T: Serialize {
     let command = RelayCommand::RegisterService { name, target };
     let payload = bincode::serialize(&command).map_err(|_| crate::error::Error::EncodeError)?;
     scope.inject(Bytes::from(payload)).await
@@ -672,14 +663,14 @@ where
 /// Holds the two per-namespace scoped capabilities (`tcp` / `udp`). The browser relay is
 /// server-side only (no local listener), so this handle just registers services. See the
 /// native [`RelayHandle`].
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 #[derive(Clone)]
 pub struct RelayHandle {
     tcp: Scope,
     udp: Scope,
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 impl RelayHandle {
     /// Install the browser relay into an extension registry: register the TCP and UDP
     /// interpreters over a fresh, relay-owned WebTransport engine and return the client handle.
@@ -927,14 +918,10 @@ mod tests {
     #[test]
     fn register_service_via_self_command_then_open_connects() {
         let relay = Relay::tcp(HashMap::new());
-        let registered = step_command(
-            &relay,
-            &relay.init(),
-            &RelayCommand::RegisterService {
-                name: "web".to_string(),
-                target: web_addr(),
-            },
-        );
+        let registered = step_command(&relay, &relay.init(), &RelayCommand::RegisterService {
+            name: "web".to_string(),
+            target: web_addr(),
+        });
         assert!(registered.effects.is_empty());
         let t = step_frame(&relay, ®istered.state, peer_a(), &open(1, "web"));
         match t.effects.as_slice() {
@@ -948,15 +935,11 @@ mod tests {
         let relay = web_relay();
         // A client-side accept is fed back as `Accepted{token}`. The core mints the session id
         // (0 on fresh state, initiator Local) and replies OpenAccepted with that minted key.
-        let accepted = step_command(
-            &relay,
-            &relay.init(),
-            &RelayCommand::Accepted {
-                token: 42,
-                peer: peer_a(),
-                service: "web".to_string(),
-            },
-        );
+        let accepted = step_command(&relay, &relay.init(), &RelayCommand::Accepted {
+            token: 42,
+            peer: peer_a(),
+            service: "web".to_string(),
+        });
         let key = SessionKey::new(peer_a(), super::TCP, SessionId(0), Initiator::Local);
         match accepted.effects.as_slice() {
             [RelayEffect::OpenAccepted {
@@ -972,15 +955,11 @@ mod tests {
         }
         assert!(accepted.state.sessions.contains(&key));
 
-        let untracked = step_command(
-            &relay,
-            &accepted.state,
-            &RelayCommand::Untrack {
-                peer: peer_a(),
-                session: SessionId(0),
-                initiator: Initiator::Local,
-            },
-        );
+        let untracked = step_command(&relay, &accepted.state, &RelayCommand::Untrack {
+            peer: peer_a(),
+            session: SessionId(0),
+            initiator: Initiator::Local,
+        });
         assert!(untracked.effects.is_empty());
         assert!(!untracked.state.sessions.contains(&key));
     }
@@ -1013,15 +992,11 @@ mod tests {
         // and a locally-accepted (Local) session must be distinct keys.
         let relay = web_relay();
         let opened = step_frame(&relay, &relay.init(), peer_a(), &open(0, "web"));
-        let accepted = step_command(
-            &relay,
-            &opened.state,
-            &RelayCommand::Accepted {
-                token: 1,
-                peer: peer_a(),
-                service: "web".to_string(),
-            },
-        );
+        let accepted = step_command(&relay, &opened.state, &RelayCommand::Accepted {
+            token: 1,
+            peer: peer_a(),
+            service: "web".to_string(),
+        });
         let remote = SessionKey::new(peer_a(), super::TCP, SessionId(0), Initiator::Remote);
         let local = SessionKey::new(peer_a(), super::TCP, SessionId(0), Initiator::Local);
         assert_ne!(remote, local);
@@ -1099,10 +1074,9 @@ mod tests {
                     if model.contains(&key) {
                         assert!(t.effects.is_empty(), "duplicate Open must emit nothing");
                     } else {
-                        assert!(matches!(
-                            t.effects.as_slice(),
-                            [RelayEffect::Connect { .. }]
-                        ));
+                        assert!(matches!(t.effects.as_slice(), [
+                            RelayEffect::Connect { .. }
+                        ]));
                         model.insert(key.clone());
                     }
                     t
@@ -1112,10 +1086,9 @@ mod tests {
                     if model.contains(&key) {
                         assert!(t.effects.is_empty());
                     } else {
-                        assert!(matches!(
-                            t.effects.as_slice(),
-                            [RelayEffect::SendClose { .. }]
-                        ));
+                        assert!(matches!(t.effects.as_slice(), [
+                            RelayEffect::SendClose { .. }
+                        ]));
                     }
                     t
                 }
diff --git a/crates/node/src/extension/snark/builder.rs b/crates/node/src/extension/snark/builder.rs
index 5722c4a5d..0b33a06da 100644
--- a/crates/node/src/extension/snark/builder.rs
+++ b/crates/node/src/extension/snark/builder.rs
@@ -226,12 +226,9 @@ impl SNARKTaskBuilder {
                 let first = first_generated_circuit(&circuits)?;
                 let inputs = first.get_public_inputs()?;
                 let pp = SNARK::::gen_pp::(first.clone())?;
-                let snark = SNARK::::new(
-                    first,
-                    &pp,
-                    &inputs,
-                    &vec![::Scalar::from(0)],
-                )?;
+                let snark = SNARK::::new(first, &pp, &inputs, &vec![
+                    ::Scalar::from(0),
+                ])?;
 
                 SNARKProofTask::VastaPallas(SNARKGenerator {
                     pp: pp.into(),
@@ -259,12 +256,9 @@ impl SNARKTaskBuilder {
                 let first = first_generated_circuit(&circuits)?;
                 let inputs = first.get_public_inputs()?;
                 let pp = SNARK::::gen_pp::(first.clone())?;
-                let snark = SNARK::::new(
-                    first,
-                    &pp,
-                    &inputs,
-                    &vec![::Scalar::from(0)],
-                )?;
+                let snark = SNARK::::new(first, &pp, &inputs, &vec![
+                    ::Scalar::from(0),
+                ])?;
                 SNARKProofTask::PallasVasta(SNARKGenerator {
                     pp: pp.into(),
                     snark,
@@ -291,12 +285,9 @@ impl SNARKTaskBuilder {
                 let first = first_generated_circuit(&circuits)?;
                 let inputs = first.get_public_inputs()?;
                 let pp = SNARK::::gen_pp::(first.clone())?;
-                let snark = SNARK::::new(
-                    first,
-                    &pp,
-                    &inputs,
-                    &vec![::Scalar::from(0)],
-                )?;
+                let snark = SNARK::::new(first, &pp, &inputs, &vec![
+                    ::Scalar::from(0),
+                ])?;
                 SNARKProofTask::Bn256KZGGrumpkin(SNARKGenerator {
                     pp: pp.into(),
                     snark,
diff --git a/crates/node/src/extension/snark/mod.rs b/crates/node/src/extension/snark/mod.rs
index 1d714316c..ba5417a6c 100644
--- a/crates/node/src/extension/snark/mod.rs
+++ b/crates/node/src/extension/snark/mod.rs
@@ -35,7 +35,7 @@ type TaskId = uuid::Uuid;
 /// Namespace under which SNARK proof/verify tasks travel.
 pub const NAMESPACE: &str = "snark";
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub mod browser;
 mod builder;
 mod protocol;
diff --git a/crates/node/src/extension/snark/protocol.rs b/crates/node/src/extension/snark/protocol.rs
index 9337e461a..1d7dc73a3 100644
--- a/crates/node/src/extension/snark/protocol.rs
+++ b/crates/node/src/extension/snark/protocol.rs
@@ -134,33 +134,26 @@ impl Protocol for SnarkProtocol {
                 task_id,
                 reply_to,
                 verify_task,
-            }) => Transition::with(
-                (),
-                vec![SnarkEffect::SendTask {
-                    to: reply_to,
-                    msg: SNARKTaskMessage {
-                        task_id,
-                        task: SNARKTask::SNARKVerify(verify_task),
-                    },
-                }],
-            ),
+            }) => Transition::with((), vec![SnarkEffect::SendTask {
+                to: reply_to,
+                msg: SNARKTaskMessage {
+                    task_id,
+                    task: SNARKTask::SNARKVerify(verify_task),
+                },
+            }]),
             SnarkEvent::Result(ComputeResult::Verified { .. }) => Transition::pure(()),
             SnarkEvent::Task { from, msg } => match msg.task {
-                SNARKTask::SNARKProof(task) => Transition::with(
-                    (),
-                    vec![SnarkEffect::Prove {
-                        task_id: msg.task_id,
-                        reply_to: from,
-                        task,
-                    }],
-                ),
-                SNARKTask::SNARKVerify(verify_task) => Transition::with(
-                    (),
-                    vec![SnarkEffect::Verify {
+                SNARKTask::SNARKProof(task) => Transition::with((), vec![SnarkEffect::Prove {
+                    task_id: msg.task_id,
+                    reply_to: from,
+                    task,
+                }]),
+                SNARKTask::SNARKVerify(verify_task) => {
+                    Transition::with((), vec![SnarkEffect::Verify {
                         task_id: msg.task_id,
                         verify_task,
-                    }],
-                ),
+                    }])
+                }
             },
         }
     }
@@ -185,8 +178,11 @@ impl SnarkShell {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 impl Interpret for SnarkShell {
     type Effect = SnarkEffect;
 
diff --git a/crates/node/src/extension/transport/engine/mod.rs b/crates/node/src/extension/transport/engine/mod.rs
index 43edef8fc..99d6856d0 100644
--- a/crates/node/src/extension/transport/engine/mod.rs
+++ b/crates/node/src/extension/transport/engine/mod.rs
@@ -305,15 +305,11 @@ impl TransportSessions {
                 }
                 // Forward the first datagram that triggered this flow.
                 let from_opener = opened_by_us(&key);
-                let _ = send_frame(
-                    &scope,
-                    key.peer,
-                    Frame::Data {
-                        session: key.session,
-                        from_opener,
-                        bytes: first,
-                    },
-                )
+                let _ = send_frame(&scope, key.peer, Frame::Data {
+                    session: key.session,
+                    from_opener,
+                    bytes: first,
+                })
                 .await;
             }
         }
@@ -356,15 +352,12 @@ impl TransportSessions {
         let (outbound, outbound_rx) = mpsc::channel::(1024);
         let cancel = CancellationToken::new();
         let generation = self.generations.fetch_add(1, Ordering::Relaxed);
-        self.insert(
-            key,
-            SessionHandle {
-                outbound,
-                cancel: cancel.clone(),
-                src,
-                generation,
-            },
-        );
+        self.insert(key, SessionHandle {
+            outbound,
+            cancel: cancel.clone(),
+            src,
+            generation,
+        });
         (outbound_rx, cancel, generation)
     }
 
@@ -430,14 +423,10 @@ impl RelayTask {
             .close_if_current(&self.scope, &self.key, self.generation)
             .await
         {
-            let _ = send_frame(
-                &self.scope,
-                self.key.peer,
-                Frame::Close {
-                    session: self.key.session,
-                    from_opener: opened_by_us(&self.key),
-                },
-            )
+            let _ = send_frame(&self.scope, self.key.peer, Frame::Close {
+                session: self.key.session,
+                from_opener: opened_by_us(&self.key),
+            })
             .await;
         }
     }
@@ -450,14 +439,10 @@ fn opened_by_us(key: &SessionKey) -> bool {
 
 /// Send `Frame::Open` to the session's peer (client side, on a new local connection/flow).
 async fn open(scope: &Scope, key: &SessionKey, service: &str) -> Result<()> {
-    send_frame(
-        scope,
-        key.peer,
-        Frame::Open {
-            session: key.session,
-            service: service.to_string(),
-        },
-    )
+    send_frame(scope, key.peer, Frame::Open {
+        session: key.session,
+        service: service.to_string(),
+    })
     .await
 }
 
diff --git a/crates/node/src/extension/transport/engine/tcp.rs b/crates/node/src/extension/transport/engine/tcp.rs
index 5d45072b5..03ccfe42a 100644
--- a/crates/node/src/extension/transport/engine/tcp.rs
+++ b/crates/node/src/extension/transport/engine/tcp.rs
@@ -88,28 +88,20 @@ pub(super) async fn relay_tcp(task: RelayTask, stream: TcpStream) {
             loop {
                 match local_read.read(buf.as_mut_slice()).await {
                     Ok(0) => {
-                        let _ = send_frame(
-                            &scope,
-                            peer,
-                            Frame::Shutdown {
-                                session,
-                                from_opener,
-                            },
-                        )
+                        let _ = send_frame(&scope, peer, Frame::Shutdown {
+                            session,
+                            from_opener,
+                        })
                         .await;
                         break;
                     }
                     Ok(n) => {
                         let bytes = Bytes::copy_from_slice(buf.get(..n).unwrap_or_default());
-                        if send_frame(
-                            &scope,
-                            peer,
-                            Frame::Data {
-                                session,
-                                from_opener,
-                                bytes,
-                            },
-                        )
+                        if send_frame(&scope, peer, Frame::Data {
+                            session,
+                            from_opener,
+                            bytes,
+                        })
                         .await
                         .is_err()
                         {
@@ -156,14 +148,10 @@ pub(super) async fn relay_tcp(task: RelayTask, stream: TcpStream) {
     // reuse of the key) — which `Untrack`s it from the pure state. Only tell the peer if we
     // were still the current owner; a stale task must not Close the peer's reused session.
     if sessions.close_if_current(&scope, &key, generation).await {
-        let _ = send_frame(
-            &scope,
-            peer,
-            Frame::Close {
-                session,
-                from_opener,
-            },
-        )
+        let _ = send_frame(&scope, peer, Frame::Close {
+            session,
+            from_opener,
+        })
         .await;
     }
 }
diff --git a/crates/node/src/extension/transport/engine/udp.rs b/crates/node/src/extension/transport/engine/udp.rs
index 065aac698..1ff4911fc 100644
--- a/crates/node/src/extension/transport/engine/udp.rs
+++ b/crates/node/src/extension/transport/engine/udp.rs
@@ -49,15 +49,11 @@ impl TransportSessions {
                         let bytes = Bytes::copy_from_slice(buf.get(..n).unwrap_or_default());
                         match self.udp_flow(&src) {
                             Some(key) => {
-                                let _ = send_frame(
-                                    &scope,
-                                    key.peer,
-                                    Frame::Data {
-                                        session: key.session,
-                                        from_opener: super::opened_by_us(&key),
-                                        bytes,
-                                    },
-                                )
+                                let _ = send_frame(&scope, key.peer, Frame::Data {
+                                    session: key.session,
+                                    from_opener: super::opened_by_us(&key),
+                                    bytes,
+                                })
                                 .await;
                             }
                             None => {
@@ -130,14 +126,10 @@ pub(super) async fn relay_udp_connected(task: RelayTask, socket: UdpSocket) {
     }
     // Only tell the peer if we were still the current owner (stale task stays silent).
     if sessions.close_if_current(&scope, &key, generation).await {
-        let _ = send_frame(
-            &scope,
-            peer,
-            Frame::Close {
-                session,
-                from_opener,
-            },
-        )
+        let _ = send_frame(&scope, peer, Frame::Close {
+            session,
+            from_opener,
+        })
         .await;
     }
 }
diff --git a/crates/node/src/extension/transport/mod.rs b/crates/node/src/extension/transport/mod.rs
index f88e880df..093737033 100644
--- a/crates/node/src/extension/transport/mod.rs
+++ b/crates/node/src/extension/transport/mod.rs
@@ -56,7 +56,7 @@
 // API. Reachable in-crate by the relay extension only.
 #[cfg(feature = "node")]
 pub(crate) mod engine;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) mod wt;
 
 use bytes::Bytes;
diff --git a/crates/node/src/extension/transport/wt.rs b/crates/node/src/extension/transport/wt.rs
index 747da60c1..3975dd7f9 100644
--- a/crates/node/src/extension/transport/wt.rs
+++ b/crates/node/src/extension/transport/wt.rs
@@ -134,14 +134,10 @@ impl WtSessions {
                 // Drop the opening slot and tell the peer — but only if we are still its owner
                 // (a peer Close during the handshake already tore it down and told the peer).
                 if self.close_if_current(&scope, &key, generation).await {
-                    let _ = send_frame(
-                        &scope,
-                        key.peer,
-                        Frame::Close {
-                            session: key.session,
-                            from_opener: matches!(key.initiator, Initiator::Local),
-                        },
-                    )
+                    let _ = send_frame(&scope, key.peer, Frame::Close {
+                        session: key.session,
+                        from_opener: matches!(key.initiator, Initiator::Local),
+                    })
                     .await;
                 }
             }
@@ -207,13 +203,10 @@ impl WtSessions {
     /// generation. The mirror of native's pre-dial `register`.
     fn open_slot(&self, key: SessionKey) -> u64 {
         let generation = self.generations.fetch_add(1, Ordering::Relaxed);
-        self.insert(
-            key,
-            SessionHandle::Opening {
-                queue: Vec::new(),
-                generation,
-            },
-        );
+        self.insert(key, SessionHandle::Opening {
+            queue: Vec::new(),
+            generation,
+        });
         generation
     }
 
@@ -256,14 +249,11 @@ impl WtSessions {
                 }
             }
         }
-        map.insert(
-            key.clone(),
-            SessionHandle::Ready {
-                writer,
-                transport,
-                generation,
-            },
-        );
+        map.insert(key.clone(), SessionHandle::Ready {
+            writer,
+            transport,
+            generation,
+        });
         true
     }
 
@@ -330,15 +320,11 @@ impl WtSessions {
                     Err(_) => break,
                 };
                 let bytes = Bytes::from(Uint8Array::new(&value).to_vec());
-                if send_frame(
-                    &scope,
-                    peer,
-                    Frame::Data {
-                        session,
-                        from_opener,
-                        bytes,
-                    },
-                )
+                if send_frame(&scope, peer, Frame::Data {
+                    session,
+                    from_opener,
+                    bytes,
+                })
                 .await
                 .is_err()
                 {
@@ -348,14 +334,10 @@ impl WtSessions {
             // Generation-checked teardown: only Close the peer if we were still the current
             // owner, so a stale read loop never tears down a reopened session.
             if sessions.close_if_current(&scope, &key, generation).await {
-                let _ = send_frame(
-                    &scope,
-                    peer,
-                    Frame::Close {
-                        session,
-                        from_opener,
-                    },
-                )
+                let _ = send_frame(&scope, peer, Frame::Close {
+                    session,
+                    from_opener,
+                })
                 .await;
             }
         });
diff --git a/crates/node/src/logging.rs b/crates/node/src/logging.rs
index 8aac98ab0..63aec816c 100644
--- a/crates/node/src/logging.rs
+++ b/crates/node/src/logging.rs
@@ -10,7 +10,7 @@ use tracing_log::LogTracer;
 use tracing_subscriber::layer::SubscriberExt;
 use tracing_subscriber::Registry;
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub use self::browser::init_logging;
 #[cfg(feature = "node")]
 pub use self::node::init_logging;
@@ -68,8 +68,7 @@ pub struct PanicLocation {
 }
 
 impl<'a, T> From for PanicLocation
-where
-    T: Into>,
+where T: Into>
 {
     fn from(lo: T) -> Self {
         let lo: Location = lo.into();
@@ -90,8 +89,7 @@ pub struct PanicData<'a> {
 }
 
 impl<'a, T> From for PanicData<'a>
-where
-    T: Into<&'a PanicHookInfo<'a>>,
+where T: Into<&'a PanicHookInfo<'a>>
 {
     fn from(panic: T) -> PanicData<'a> {
         let panic = panic.into();
@@ -184,7 +182,7 @@ pub mod node {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 /// Browser console logging configuration.
 pub mod browser {
     use tracing_wasm::ConsoleConfig;
diff --git a/crates/node/src/measure.rs b/crates/node/src/measure.rs
index 030e5d2cb..f059648cd 100644
--- a/crates/node/src/measure.rs
+++ b/crates/node/src/measure.rs
@@ -35,12 +35,12 @@ pub(crate) const fn peer_quality_thresholds() -> PeerQualityThresholds {
 
 /// `MeasureStorage` is the type accepted by `PeriodicMeasure::new`.
 /// It's used to store counts in a storage media provided by user.
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub type MeasureStorage = Box>;
 
 /// `MeasureStorage` is the type accepted by `PeriodicMeasure::new`.
 /// It's used to store counts in a storage media provided by user.
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 pub type MeasureStorage = Box + Sync + Send>;
 
 /// `PeriodicMeasure` is used to assess the reliability of peers by counting their behaviour.
@@ -191,7 +191,7 @@ impl PeriodicMeasure {
 }
 
 #[cfg_attr(feature = "node", async_trait)]
-#[cfg_attr(feature = "browser", async_trait(?Send))]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
 impl Measure for PeriodicMeasure {
     /// `incr` increments the counter of the given peer.
     async fn incr(&self, did: Did, counter: MeasureCounter) {
@@ -230,7 +230,7 @@ impl Measure for PeriodicMeasure {
 }
 
 #[cfg_attr(feature = "node", async_trait)]
-#[cfg_attr(feature = "browser", async_trait(?Send))]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
 impl measure::BehaviourJudgement for PeriodicMeasure {
     async fn quality(&self, did: Did) -> PeerQuality {
         let thresholds = peer_quality_thresholds();
diff --git a/crates/node/src/native/cli.rs b/crates/node/src/native/cli.rs
index d640695de..ed3a1983f 100644
--- a/crates/node/src/native/cli.rs
+++ b/crates/node/src/native/cli.rs
@@ -186,7 +186,10 @@ impl Client {
     }
 
     /// Subscribes to the specified topic and returns a stream of messages published to the topic.
-    pub async fn subscribe_topic<'a, 'b>(&'a self, topic: String) -> impl Stream + 'b
+    pub async fn subscribe_topic<'a, 'b>(
+        &'a self,
+        topic: String,
+    ) -> impl Stream + 'b
     where
         'a: 'b,
     {
diff --git a/crates/node/src/native/config.rs b/crates/node/src/native/config.rs
index fd305dd7d..1ab4a8746 100644
--- a/crates/node/src/native/config.rs
+++ b/crates/node/src/native/config.rs
@@ -49,9 +49,7 @@ pub const DEFAULT_STORAGE_CAPACITY: u32 = 200000000;
 
 /// Builds the default storage path under the user home directory.
 pub fn get_storage_location
(prefix: P, path: P) -> String
-where
-    P: AsRef,
-{
+where P: AsRef {
     let home_dir = env::var_os("HOME").map(PathBuf::from);
     let storage_path = match home_dir {
         Some(dir) => dir.join(prefix).join(path),
@@ -219,9 +217,7 @@ impl TryFrom for ProcessorConfig {
 impl Config {
     /// Creates a default native-node configuration using the supplied session key path.
     pub fn new
(session_sk: P) -> Self
-    where
-        P: AsRef,
-    {
+    where P: AsRef {
         let session_sk = session_sk.as_ref().to_string_lossy().to_string();
         Self {
             network_id: DEFAULT_NETWORK_ID,
@@ -264,9 +260,7 @@ impl Config {
 
     /// Writes this configuration to a YAML file and returns the written path.
     pub fn write_fs
(&self, path: P) -> Result
-    where
-        P: AsRef,
-    {
+    where P: AsRef {
         let path = expand_home(path)?;
         ensure_parent_dir(&path)?;
         let f =
@@ -280,9 +274,7 @@ impl Config {
 
     /// Reads a native-node configuration from a YAML file.
     pub fn read_fs
(path: P) -> Result
-    where
-        P: AsRef,
-    {
+    where P: AsRef {
         let path = expand_home(path)?;
         tracing::debug!("Read config from: {:?}", path);
         let f = fs::File::open(path).map_err(|e| Error::OpenFileError(e.to_string()))?;
diff --git a/crates/node/src/native/endpoint/mod.rs b/crates/node/src/native/endpoint/mod.rs
index 7d035542a..4500fd189 100644
--- a/crates/node/src/native/endpoint/mod.rs
+++ b/crates/node/src/native/endpoint/mod.rs
@@ -22,8 +22,7 @@ use crate::processor::Processor;
 /// JSON-RPC state
 #[derive(Clone)]
 pub struct JsonRpcState
-where
-    M: jsonrpc_core::Middleware>,
+where M: jsonrpc_core::Middleware>
 {
     processor: Arc,
     io_handler: MetaIoHandler, M>,
diff --git a/crates/node/src/onion/circuit/shell.rs b/crates/node/src/onion/circuit/shell.rs
index 845804864..65d985cdf 100644
--- a/crates/node/src/onion/circuit/shell.rs
+++ b/crates/node/src/onion/circuit/shell.rs
@@ -107,11 +107,13 @@ impl OnionCircuitShell {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 impl Interpret for OnionCircuitShell
-where
-    H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static,
+where H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static
 {
     type Effect = OnionCircuitEffect;
 
@@ -141,17 +143,14 @@ where
                 payload,
             } => {
                 self.handler
-                    .handle_exit(
-                        scope,
-                        OnionCircuitExitFrame {
-                            from,
-                            circuit_id,
-                            return_peer,
-                            client,
-                            forward_nonce,
-                            payload,
-                        },
-                    )
+                    .handle_exit(scope, OnionCircuitExitFrame {
+                        from,
+                        circuit_id,
+                        return_peer,
+                        client,
+                        forward_nonce,
+                        payload,
+                    })
                     .await?;
                 Ok(Vec::new())
             }
@@ -189,8 +188,11 @@ pub struct OnionCircuitExitFrame {
 }
 
 /// Runtime-specific circuit handling.
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 pub trait OnionCircuitHandler {
     /// Handle a frame that reached this node as the exit.
     async fn handle_exit(&self, scope: &Scope, frame: OnionCircuitExitFrame) -> Result<()>;
diff --git a/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs b/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
index 6bfd6b121..f7494c1e6 100644
--- a/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
+++ b/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
@@ -140,8 +140,11 @@ impl RecordingHandler {
 }
 
 #[cfg(feature = "node")]
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 impl OnionCircuitHandler for RecordingHandler {
     async fn handle_exit(
         &self,
@@ -421,20 +424,17 @@ fn expired_exit_layer_emits_no_exit_effect() {
     let state = OnionCircuitState::default();
     let circuit_id = OnionCircuitId::new([8; 16]);
 
-    let transition = reducer.apply(
-        &state,
-        OnionCircuitInput::ForwardReady {
-            from: client.account_did(),
-            received_at_ms: 100,
-            circuit_id,
-            layer: OnionForwardLayer::Exit {
-                client: OnionClientReturn::new(client.session_public_key()),
-                expires_at_ms: 100,
-                forward_nonce: OnionForwardNonce::new([9; 16]),
-                payload: test_payload("expired"),
-            },
+    let transition = reducer.apply(&state, OnionCircuitInput::ForwardReady {
+        from: client.account_did(),
+        received_at_ms: 100,
+        circuit_id,
+        layer: OnionForwardLayer::Exit {
+            client: OnionClientReturn::new(client.session_public_key()),
+            expires_at_ms: 100,
+            forward_nonce: OnionForwardNonce::new([9; 16]),
+            payload: test_payload("expired"),
         },
-    );
+    });
 
     assert_eq!(transition.state, state);
     assert!(transition.effects.is_empty());
diff --git a/crates/node/src/onion/directory.rs b/crates/node/src/onion/directory.rs
index 65fc2648b..36590a094 100644
--- a/crates/node/src/onion/directory.rs
+++ b/crates/node/src/onion/directory.rs
@@ -21,8 +21,11 @@ use crate::onion::proxy::OnionProxyTarget;
 use crate::online::OnlineNodeDescriptor;
 
 /// Read-only directory effects required by onion route construction.
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 pub(crate) trait OnionDirectoryReader {
     /// Return the local DID that must not appear as a selected relay.
     fn local_did(&self) -> Did;
diff --git a/crates/node/src/onion/https/mod.rs b/crates/node/src/onion/https/mod.rs
index d4fe7b415..277df809d 100644
--- a/crates/node/src/onion/https/mod.rs
+++ b/crates/node/src/onion/https/mod.rs
@@ -1,4 +1,10 @@
-#![cfg_attr(all(feature = "node", not(feature = "browser")), allow(dead_code))]
+#![cfg_attr(
+    all(
+        feature = "node",
+        not(all(feature = "browser", target_family = "wasm"))
+    ),
+    allow(dead_code)
+)]
 //! HTTPS onion-exit request/response adapter.
 //!
 //! This protocol is intentionally application-layer HTTPS. Clients can send an HTTPS request
@@ -9,10 +15,10 @@
 //! headers, credentials policy, and extension host permissions still apply. A full arbitrary HTTPS
 //! exit must run in a browser-extension or native context that grants those fetch permissions.
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use std::cell::RefCell;
 use std::collections::HashMap;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use std::rc::Rc;
 use std::sync::Arc;
 use std::sync::Mutex;
@@ -21,35 +27,35 @@ use std::time::Duration;
 
 use bytes::Bytes;
 use futures::channel::oneshot;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use futures::future::Either;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use futures::FutureExt;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use js_sys::Function;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use js_sys::Object;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use js_sys::Promise;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use js_sys::Reflect;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use js_sys::Uint8Array;
 use rings_core::dht::Did;
 use rings_core::session::SessionSk;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use rings_core::utils::js_utils;
 use serde::Deserialize;
 use serde::Serialize;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use wasm_bindgen::closure::Closure;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use wasm_bindgen::JsCast;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use wasm_bindgen::JsValue;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use wasm_bindgen_futures::JsFuture;
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 use web_sys::AbortController;
 
 use crate::error::Error;
@@ -58,7 +64,7 @@ use crate::extension::ext::Scope;
 use crate::onion::circuit::send_backward;
 use crate::onion::circuit::OnionAuthenticatedPayload;
 use crate::onion::circuit::OnionCircuitExitFrame;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use crate::onion::circuit::OnionCircuitHandler;
 use crate::onion::circuit::OnionCircuitId;
 use crate::onion::circuit::OnionCircuitPayload;
@@ -80,7 +86,7 @@ use crate::onion::OnionRouteError;
 const DEFAULT_HTTPS_RESPONSE_BODY_LIMIT_BYTES: u64 = 8 * 1024 * 1024;
 #[cfg(feature = "node")]
 const HTTPS_EXIT_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 const HTTPS_EXIT_REQUEST_TIMEOUT_MS: i32 = 30_000;
 
 /// One HTTPS request executed by an HTTPS exit.
@@ -218,15 +224,12 @@ impl OnionHttpsRuntime {
                 continue;
             }
             let (sender, receiver) = oneshot::channel();
-            pending.insert(
-                id,
-                PendingRequest {
-                    expected_return_peer,
-                    expected_exit,
-                    return_id,
-                    sender,
-                },
-            );
+            pending.insert(id, PendingRequest {
+                expected_return_peer,
+                expected_exit,
+                return_id,
+                sender,
+            });
             return Ok((id, receiver));
         }
         Err(Error::OnionRouteError(
@@ -479,13 +482,13 @@ fn url_path(suffix: &str) -> String {
 }
 
 /// Browser handler for HTTPS onion circuits.
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) struct BrowserOnionCircuitHandler {
     https: Arc,
     session_sk: SessionSk,
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 impl BrowserOnionCircuitHandler {
     /// Create a browser circuit handler backed by the HTTPS runtime.
     pub(crate) fn new(https: Arc, session_sk: SessionSk) -> Self {
@@ -493,7 +496,7 @@ impl BrowserOnionCircuitHandler {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 #[async_trait::async_trait(?Send)]
 impl OnionCircuitHandler for BrowserOnionCircuitHandler {
     async fn handle_exit(&self, scope: &Scope, frame: OnionCircuitExitFrame) -> Result<()> {
@@ -610,7 +613,7 @@ async fn execute_https_request(
     native_fetch(url, request, max_body_bytes, runtime, policy).await
 }
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 async fn execute_https_request(
     url: &str,
     request: &OnionHttpsRequest,
@@ -707,7 +710,7 @@ async fn native_fetch_with_timeout(
     })
 }
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 async fn browser_fetch(
     url: &str,
     request: &OnionHttpsRequest,
@@ -763,7 +766,7 @@ async fn browser_fetch(
     }
 }
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 fn fetch_init(request: &OnionHttpsRequest, signal: &JsValue) -> Result {
     let init = Object::new();
     Reflect::set(
@@ -838,7 +841,7 @@ fn usize_to_u64(value: usize) -> Result {
     u64::try_from(value).map_err(|_| Error::InvalidData)
 }
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 fn collect_headers(response: &JsValue) -> Result> {
     let headers =
         Reflect::get(response, JsValue::from_str("headers").as_ref()).map_err(js_error)?;
@@ -881,7 +884,7 @@ fn reject_content_length_over_limit(
     Ok(())
 }
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 async fn response_body(
     response: &JsValue,
     max_body_bytes: u64,
@@ -976,7 +979,7 @@ fn default_path() -> String {
     "/".to_string()
 }
 
-#[cfg(all(not(feature = "node"), feature = "browser"))]
+#[cfg(all(not(feature = "node"), feature = "browser", target_family = "wasm"))]
 fn js_error(error: JsValue) -> Error {
     Error::JsError(format!("{error:?}"))
 }
diff --git a/crates/node/src/onion/https/tests/test_https_proxy.rs b/crates/node/src/onion/https/tests/test_https_proxy.rs
index af93ce518..e8beece2a 100644
--- a/crates/node/src/onion/https/tests/test_https_proxy.rs
+++ b/crates/node/src/onion/https/tests/test_https_proxy.rs
@@ -76,16 +76,13 @@ fn normalizes_empty_request_defaults() {
     let target = OnionProxyTarget::parse_authority("Example.COM:443").unwrap();
     let wire = client_request_with_default_path(&target, request, default_path().as_str()).unwrap();
 
-    assert_eq!(
-        wire,
-        OnionHttpsRequest {
-            target: "example.com:443".to_string(),
-            method: "GET".to_string(),
-            path: "/".to_string(),
-            headers: Vec::new(),
-            body: Vec::new(),
-        }
-    );
+    assert_eq!(wire, OnionHttpsRequest {
+        target: "example.com:443".to_string(),
+        method: "GET".to_string(),
+        path: "/".to_string(),
+        headers: Vec::new(),
+        body: Vec::new(),
+    });
 }
 
 #[test]
diff --git a/crates/node/src/onion/mod.rs b/crates/node/src/onion/mod.rs
index 12365149e..9cf69869a 100644
--- a/crates/node/src/onion/mod.rs
+++ b/crates/node/src/onion/mod.rs
@@ -42,7 +42,7 @@ pub mod circuit;
 pub(crate) mod directory;
 pub(crate) mod exit_accounting;
 mod failure;
-#[cfg(any(feature = "browser", feature = "node"))]
+#[cfg(any(feature = "node", all(feature = "browser", target_family = "wasm")))]
 pub mod https;
 pub mod proxy;
 pub(crate) mod replay;
@@ -860,8 +860,8 @@ impl OnionExitRegistration {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl RegistrationTask for OnionExitRegistration {
     fn name(&self) -> &'static str {
         "onion-exit"
diff --git a/crates/node/src/onion/replay.rs b/crates/node/src/onion/replay.rs
index ba0b1e2fc..541151398 100644
--- a/crates/node/src/onion/replay.rs
+++ b/crates/node/src/onion/replay.rs
@@ -76,8 +76,7 @@ impl Default for OnionReplayCache {
 }
 
 impl OnionReplayCache
-where
-    K: Eq + Hash,
+where K: Eq + Hash
 {
     #[cfg(test)]
     fn with_limits(max_entries: usize, ttl_ms: u128) -> Self {
diff --git a/crates/node/src/onion/route/tests/test_route_selection.rs b/crates/node/src/onion/route/tests/test_route_selection.rs
index 37f292d00..815ffc3d6 100644
--- a/crates/node/src/onion/route/tests/test_route_selection.rs
+++ b/crates/node/src/onion/route/tests/test_route_selection.rs
@@ -80,12 +80,9 @@ fn online_node_at(
     heartbeat_at_ms: u128,
     expires_at_ms: u128,
 ) -> CoreResult {
-    online_node_at_with_capabilities(
-        session_sk,
-        heartbeat_at_ms,
-        expires_at_ms,
-        vec![ONION_RELAY_CAPABILITY.to_string()],
-    )
+    online_node_at_with_capabilities(session_sk, heartbeat_at_ms, expires_at_ms, vec![
+        ONION_RELAY_CAPABILITY.to_string(),
+    ])
 }
 
 fn online_node_at_with_capabilities(
@@ -243,14 +240,12 @@ fn directory_candidates_reject_foreign_network_descriptors() -> Result<()> {
         test_dht_protocol(),
         50,
         route_request("web", 1, false)?.service_name(),
-        vec![online_node_at_with_network_and_capabilities(
-            &relay,
-            2,
-            20,
-            100,
-            vec![ONION_RELAY_CAPABILITY.to_string()],
-        )
-        .map_err(Error::CoreError)?],
+        vec![
+            online_node_at_with_network_and_capabilities(&relay, 2, 20, 100, vec![
+                ONION_RELAY_CAPABILITY.to_string(),
+            ])
+            .map_err(Error::CoreError)?,
+        ],
         vec![exit],
     );
 
diff --git a/crates/node/src/onion/tcp/mod.rs b/crates/node/src/onion/tcp/mod.rs
index 63eac1e9c..84b994728 100644
--- a/crates/node/src/onion/tcp/mod.rs
+++ b/crates/node/src/onion/tcp/mod.rs
@@ -130,14 +130,11 @@ impl NativeOnionCircuitHandle {
         let handler_session_sk = session_sk.clone();
         extensions.register(
             OnionCircuitProtocol::new(capabilities),
-            OnionCircuitShell::new(
-                session_sk,
-                NativeOnionCircuitHandler {
-                    runtime: runtime.clone(),
-                    https,
-                    session_sk: handler_session_sk,
-                },
-            ),
+            OnionCircuitShell::new(session_sk, NativeOnionCircuitHandler {
+                runtime: runtime.clone(),
+                https,
+                session_sk: handler_session_sk,
+            }),
         )?;
         Ok(Self {
             runtime,
@@ -276,12 +273,9 @@ impl OnionTcpRuntime {
                 return Err(error);
             }
         };
-        let open_payload = match encode_tcp_payload(
-            &service,
-            OnionTcpPayload::Open {
-                target: target.authority(),
-            },
-        ) {
+        let open_payload = match encode_tcp_payload(&service, OnionTcpPayload::Open {
+            target: target.authority(),
+        }) {
             Ok(payload) => payload,
             Err(error) => {
                 self.remove_client_stream(key);
diff --git a/crates/node/src/onion/tests/test_exit_registry.rs b/crates/node/src/onion/tests/test_exit_registry.rs
index f055fa14c..76addbf12 100644
--- a/crates/node/src/onion/tests/test_exit_registry.rs
+++ b/crates/node/src/onion/tests/test_exit_registry.rs
@@ -59,10 +59,10 @@ fn signed_exit_for_session_at(
 
 #[test]
 fn default_exit_services_include_native_tcp_and_https() {
-    assert_eq!(
-        default_onion_exit_services(),
-        vec![OnionExitService::tcp(), OnionExitService::https()]
-    );
+    assert_eq!(default_onion_exit_services(), vec![
+        OnionExitService::tcp(),
+        OnionExitService::https()
+    ]);
     assert_eq!(https_onion_exit_services(), vec![OnionExitService::https()]);
 }
 
@@ -143,10 +143,9 @@ fn exit_policy_allow_list_controls_targets() -> Result<()> {
 
 #[test]
 fn exit_policy_wildcard_allows_all_targets_with_specific_denies() -> Result<()> {
-    let policy = OnionExitPolicy::from_target_strings(
-        vec!["*:*".to_string()],
-        vec!["api.example.com:443".to_string()],
-    )?;
+    let policy = OnionExitPolicy::from_target_strings(vec!["*:*".to_string()], vec![
+        "api.example.com:443".to_string(),
+    ])?;
     let google = OnionExitTarget::parse("google.com:443")?;
     let example = OnionExitTarget::parse("example.com:8443")?;
     let api = OnionExitTarget::parse("api.example.com:443")?;
diff --git a/crates/node/src/processor/builder.rs b/crates/node/src/processor/builder.rs
index 5d2981a86..5a15227be 100644
--- a/crates/node/src/processor/builder.rs
+++ b/crates/node/src/processor/builder.rs
@@ -142,9 +142,7 @@ impl ProcessorBuilder {
 
     /// Add a custom periodic registration task.
     pub fn registration_task(mut self, task: T) -> Self
-    where
-        T: RegistrationTask + 'static,
-    {
+    where T: RegistrationTask + 'static {
         self.registration_tasks.push(Arc::new(task));
         self
     }
@@ -217,7 +215,7 @@ impl ProcessorBuilder {
             session_sk,
             stabilize_interval: self.stabilize_interval,
             online_node_registration,
-            #[cfg(feature = "browser")]
+            #[cfg(all(feature = "browser", target_family = "wasm"))]
             advertise_onion_relay: self.advertise_onion_relay,
             registration_tasks,
         })
diff --git a/crates/node/src/processor/config.rs b/crates/node/src/processor/config.rs
index e41b4e164..dcea574b7 100644
--- a/crates/node/src/processor/config.rs
+++ b/crates/node/src/processor/config.rs
@@ -140,7 +140,7 @@ impl ProcessorConfig {
     }
 
     /// Return the HTTPS onion-exit policy when this config advertises that service.
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     pub fn onion_https_exit_policy(&self) -> Option {
         (self.advertise_onion_exit
             && self
@@ -495,9 +495,7 @@ impl Serialize for ProcessorConfig {
 
 impl<'de> serde::de::Deserialize<'de> for ProcessorConfig {
     fn deserialize(deserializer: D) -> core::result::Result
-    where
-        D: serde::Deserializer<'de>,
-    {
+    where D: serde::Deserializer<'de> {
         match ProcessorConfigSerialized::deserialize(deserializer) {
             Ok(ins) => {
                 let cfg: ProcessorConfig = ins
diff --git a/crates/node/src/processor/mod.rs b/crates/node/src/processor/mod.rs
index 58619a50a..5c6268385 100644
--- a/crates/node/src/processor/mod.rs
+++ b/crates/node/src/processor/mod.rs
@@ -54,7 +54,7 @@ use crate::onion::https_onion_exit_services;
 use crate::onion::proxy::OnionProxyConfig;
 use crate::onion::proxy::OnionProxyRoute;
 use crate::onion::proxy::OnionProxyTarget;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use crate::onion::proxy::ONION_PROXY_HTTPS_SERVICE;
 use crate::onion::validate_onion_exit_registration_timing;
 use crate::onion::OnionExitDescriptor;
@@ -95,13 +95,13 @@ const DHT_LOOKUP_CACHE_POLL_INTERVAL: Duration = Duration::from_millis(50);
 const DHT_LOOKUP_CACHE_POLL_ATTEMPTS: usize = 40;
 const MAX_REGISTRATION_ATTEMPT_TIMEOUT: Duration = Duration::from_secs(10);
 
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 async fn sleep_dht_lookup_poll_interval(interval: Duration) -> Result<()> {
     futures_timer::Delay::new(interval).await;
     Ok(())
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 async fn sleep_dht_lookup_poll_interval(interval: Duration) -> Result<()> {
     let interval_ms = i32::try_from(interval.as_millis()).unwrap_or(i32::MAX);
     rings_core::utils::js_utils::window_sleep(interval_ms)
@@ -130,7 +130,7 @@ pub struct Processor {
     session_sk: SessionSk,
     stabilize_interval: Duration,
     online_node_registration: OnlineNodeRegistration,
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     advertise_onion_relay: bool,
     registration_tasks: Vec>,
 }
@@ -145,7 +145,7 @@ impl Processor {
         &self.session_sk
     }
 
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     pub(crate) fn advertise_onion_relay(&self) -> bool {
         self.advertise_onion_relay
     }
@@ -421,9 +421,14 @@ impl Processor {
     /// 1. PeerA has a connection with PeerB.
     /// 2. PeerC has a connection with PeerB.
     /// 3. PeerC can connect PeerA with PeerA's web3 address.
+    ///
+    /// This operation is idempotent: if topology convergence already produced
+    /// the direct connection, the requested connection is satisfied.
     pub async fn connect_with_did(&self, did: Did) -> Result<()> {
-        self.swarm.connect(did).await.map_err(Error::ConnectError)?;
-        Ok(())
+        match self.swarm.connect(did).await {
+            Ok(()) | Err(rings_core::error::Error::AlreadyConnected) => Ok(()),
+            Err(error) => Err(Error::ConnectError(error)),
+        }
     }
 
     /// Disconnect a peer with web3 did.
@@ -704,8 +709,11 @@ impl Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait::async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait::async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait::async_trait(?Send))]
+#[cfg_attr(
+    not(all(feature = "browser", target_family = "wasm")),
+    async_trait::async_trait
+)]
 impl OnionDirectoryReader for Processor {
     fn local_did(&self) -> Did {
         self.did()
diff --git a/crates/node/src/processor/tests/test_config.rs b/crates/node/src/processor/tests/test_config.rs
index 92b6613ab..5e483eeb5 100644
--- a/crates/node/src/processor/tests/test_config.rs
+++ b/crates/node/src/processor/tests/test_config.rs
@@ -300,10 +300,10 @@ fn default_onion_exit_config_uses_native_tcp_backed_services() {
 
     assert!(config.advertise_onion_exit);
     assert_eq!(config.onion_exit_services, default_onion_exit_services());
-    assert_eq!(
-        config.onion_exit_services,
-        vec![OnionExitService::tcp(), OnionExitService::https()]
-    );
+    assert_eq!(config.onion_exit_services, vec![
+        OnionExitService::tcp(),
+        OnionExitService::https()
+    ]);
 }
 
 #[test]
diff --git a/crates/node/src/processor/tests/test_network.rs b/crates/node/src/processor/tests/test_network.rs
index 2eaf8c1a4..e4eaa039e 100644
--- a/crates/node/src/processor/tests/test_network.rs
+++ b/crates/node/src/processor/tests/test_network.rs
@@ -15,6 +15,21 @@ async fn listen_with_pre_stopped_token_returns_before_first_tick() {
     .expect("pre-stopped listen token should exit before the first stabilization tick");
 }
 
+#[tokio::test]
+async fn provider_listen_with_pre_stopped_token_returns_before_first_tick() {
+    let processor = prepare_processor().await;
+    let provider = Provider::from_processor(Arc::new(processor));
+    let stop = StopSource::new();
+    stop.request_stop();
+
+    tokio::time::timeout(
+        Duration::from_millis(100),
+        provider.listen_with(stop.token()),
+    )
+    .await
+    .expect("pre-stopped provider listen token should exit before the first stabilization tick");
+}
+
 #[tokio::test]
 async fn online_node_registry_lists_two_publishers_over_network() -> Result<()> {
     let _network_guard = network_test_guard().await;
@@ -214,12 +229,9 @@ async fn provider_exposes_sent_and_received_peer_measurements() {
     assert!(provider_measurement.evidence.sent >= 1);
 
     let rpc_value = provider
-        .request(
-            Method::PeerMeasurement,
-            PeerMeasurementRequest {
-                did: p2.did().to_string(),
-            },
-        )
+        .request(Method::PeerMeasurement, PeerMeasurementRequest {
+            did: p2.did().to_string(),
+        })
         .await
         .unwrap();
     let rpc_measurement: PeerMeasurementResponse = serde_json::from_value(rpc_value).unwrap();
diff --git a/crates/node/src/provider/browser/provider.rs b/crates/node/src/provider/browser/provider.rs
index ca9281c19..b79a1526d 100644
--- a/crates/node/src/provider/browser/provider.rs
+++ b/crates/node/src/provider/browser/provider.rs
@@ -13,6 +13,7 @@ use js_sys;
 use js_sys::Uint8Array;
 use rings_core::dht::Did;
 use rings_core::ecc::PublicKey;
+use rings_core::lifecycle::StopSource;
 use rings_core::measure::PeerQuality;
 use rings_core::message::DhtProtocolMode;
 use rings_core::prelude::entry;
@@ -83,6 +84,34 @@ impl ProviderRef {
     }
 }
 
+/// Browser listener lifecycle handle returned by [`Provider::listen`].
+#[derive(Clone)]
+#[wasm_export]
+pub struct ProviderListener {
+    stop: StopSource,
+    task: js_sys::Promise,
+}
+
+#[wasm_export]
+impl ProviderListener {
+    /// Request cooperative shutdown for the listener task.
+    pub fn stop(&self) {
+        self.stop.request_stop();
+    }
+
+    /// Return whether shutdown was requested through this handle.
+    pub fn is_stopped(&self) -> bool {
+        self.stop.is_stop_requested()
+    }
+
+    /// Return the underlying listener task promise.
+    ///
+    /// It resolves only after [`ProviderListener::stop`] requests cooperative shutdown.
+    pub fn task(&self) -> js_sys::Promise {
+        self.task.clone()
+    }
+}
+
 /// Browser-compatible onion proxy handle.
 ///
 /// The proxy is target-agnostic: callers create it once with route-selection options, then send
@@ -612,17 +641,18 @@ impl Provider {
         })
     }
 
-    /// Start the long-running listener.
-    ///
-    /// The returned Promise is not a readiness barrier and does not resolve
-    /// during normal operation.
-    pub fn listen(&self) -> js_sys::Promise {
+    /// Start the long-running listener and return its lifecycle handle.
+    pub fn listen(&self) -> ProviderListener {
         let p = self.processor.clone();
+        let stop = StopSource::new();
+        let token = stop.token();
 
-        future_to_promise(async move {
-            p.listen().await;
+        let task = future_to_promise(async move {
+            p.listen_with(token).await;
             Ok(JsValue::null())
-        })
+        });
+
+        ProviderListener { stop, task }
     }
 
     /// connect peer with remote jsonrpc server url
diff --git a/crates/node/src/provider/ffi.rs b/crates/node/src/provider/ffi.rs
index 1bcc8ba06..bc645a978 100644
--- a/crates/node/src/provider/ffi.rs
+++ b/crates/node/src/provider/ffi.rs
@@ -102,8 +102,8 @@ impl FfiBackend {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl SwarmCallback for FfiBackend {
     async fn on_inbound(
         &self,
diff --git a/crates/node/src/provider/mod.rs b/crates/node/src/provider/mod.rs
index 34fd3e151..36b9df1c6 100644
--- a/crates/node/src/provider/mod.rs
+++ b/crates/node/src/provider/mod.rs
@@ -3,7 +3,7 @@
 use std::future::Future;
 use std::pin::Pin;
 use std::sync::Arc;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use std::sync::Mutex;
 
 use rings_core::dht::Did;
@@ -26,7 +26,7 @@ use crate::processor::Processor;
 use crate::processor::ProcessorBuilder;
 use crate::processor::ProcessorConfig;
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub mod browser;
 #[cfg(feature = "ffi")]
 pub mod ffi;
@@ -42,18 +42,18 @@ pub struct Provider {
     processor: Arc,
     handler: InternalRpcHandler,
     extensions: crate::extension::ext::Extensions,
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     onion_https_runtime: Arc>>>,
-    #[cfg(feature = "browser")]
+    #[cfg(all(feature = "browser", target_family = "wasm"))]
     onion_directory_endpoint: Arc>>,
 }
 
 /// Async signer, without Send required
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub type AsyncSigner = Box Pin>>>>;
 
 /// Async signer, use for non-wasm envirement, Send is necessary
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 pub type AsyncSigner = Box Pin> + Send>>>;
 
 /// Signer can be async and sync
@@ -74,9 +74,9 @@ impl Provider {
             processor,
             handler: InternalRpcHandler,
             extensions,
-            #[cfg(feature = "browser")]
+            #[cfg(all(feature = "browser", target_family = "wasm"))]
             onion_https_runtime: Arc::new(Mutex::new(None)),
-            #[cfg(feature = "browser")]
+            #[cfg(all(feature = "browser", target_family = "wasm"))]
             onion_directory_endpoint: Arc::new(Mutex::new(None)),
         }
     }
@@ -152,9 +152,9 @@ impl Provider {
             processor,
             handler: InternalRpcHandler,
             extensions,
-            #[cfg(feature = "browser")]
+            #[cfg(all(feature = "browser", target_family = "wasm"))]
             onion_https_runtime: Arc::new(Mutex::new(None)),
-            #[cfg(feature = "browser")]
+            #[cfg(all(feature = "browser", target_family = "wasm"))]
             onion_directory_endpoint: Arc::new(Mutex::new(None)),
         })
     }
@@ -254,14 +254,14 @@ impl Provider {
         params: serde_json::Value,
     ) -> Result {
         tracing::debug!("request {}", method);
-        #[cfg(feature = "browser")]
+        #[cfg(all(feature = "browser", target_family = "wasm"))]
         let onion_directory_endpoint = onion_directory_endpoint_from_rpc(method.as_str(), ¶ms);
         let result = self
             .handler
             .handle_request(self.processor.clone(), method, params)
             .await
             .map_err(Error::InternalRpcError)?;
-        #[cfg(feature = "browser")]
+        #[cfg(all(feature = "browser", target_family = "wasm"))]
         if let Some(endpoint) = onion_directory_endpoint {
             self.set_onion_directory_endpoint(Some(endpoint))?;
         }
@@ -299,7 +299,7 @@ impl Provider {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn onion_directory_endpoint_from_rpc(method: &str, params: &serde_json::Value) -> Option {
     if !matches!(method, "connectPeerViaHttp" | "ConnectPeerViaHttp") {
         return None;
@@ -312,7 +312,7 @@ fn onion_directory_endpoint_from_rpc(method: &str, params: &serde_json::Value) -
         .map(ToOwned::to_owned)
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 impl Provider {
     pub(crate) fn set_onion_directory_endpoint(&self, endpoint: Option) -> Result<()> {
         let mut slot = self
diff --git a/crates/node/src/registration.rs b/crates/node/src/registration.rs
index 43692ad8b..e5afa6170 100644
--- a/crates/node/src/registration.rs
+++ b/crates/node/src/registration.rs
@@ -48,11 +48,14 @@ pub(crate) fn default_online_node_type() -> OnlineNodeType {
     {
         OnlineNodeType::Ffi
     }
-    #[cfg(all(not(feature = "ffi"), feature = "browser"))]
+    #[cfg(all(not(feature = "ffi"), feature = "browser", target_family = "wasm"))]
     {
         OnlineNodeType::Browser
     }
-    #[cfg(all(not(feature = "ffi"), not(feature = "browser")))]
+    #[cfg(all(
+        not(feature = "ffi"),
+        not(all(feature = "browser", target_family = "wasm"))
+    ))]
     {
         OnlineNodeType::Native
     }
@@ -77,7 +80,7 @@ pub(crate) fn validate_online_node_registration_timing(
     Ok(())
 }
 
-#[cfg(not(feature = "browser"))]
+#[cfg(not(all(feature = "browser", target_family = "wasm")))]
 pub(crate) async fn sleep_registration_interval(interval: Duration) -> Result<()> {
     // Native timers are infallible; the Result keeps the daemon shape shared
     // with the wasm arm, where browser timer setup can fail.
@@ -85,7 +88,7 @@ pub(crate) async fn sleep_registration_interval(interval: Duration) -> Result<()
     Ok(())
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) async fn sleep_registration_interval(interval: Duration) -> Result<()> {
     let interval_ms = i32::try_from(interval.as_millis()).unwrap_or(i32::MAX);
     rings_core::utils::js_utils::window_sleep(interval_ms)
@@ -223,8 +226,8 @@ fn finish_registration_publish(
 }
 
 /// Periodic node-layer registration.
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 pub trait RegistrationTask: MaybeSend {
     /// Stable name used in logs.
     fn name(&self) -> &'static str;
@@ -347,8 +350,8 @@ impl OnlineNodeRegistration {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl RegistrationTask for OnlineNodeRegistration {
     fn name(&self) -> &'static str {
         "online-node"
@@ -379,7 +382,8 @@ mod tests {
         ["a", "b", "c"]
             .into_iter()
             .enumerate()
-            .filter_map(|(bit, value)| (mask & (1 << bit) != 0).then(|| encoded(value)))
+            .filter(|(bit, _value)| mask & (1 << bit) != 0)
+            .map(|(_bit, value)| encoded(value))
             .collect()
     }
 
diff --git a/crates/node/src/rpc_dto.rs b/crates/node/src/rpc_dto.rs
index 15318c33a..2f51e5211 100644
--- a/crates/node/src/rpc_dto.rs
+++ b/crates/node/src/rpc_dto.rs
@@ -1,17 +1,17 @@
 //! Conversions from node/core domain values to RPC wire DTOs.
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use std::str::FromStr;
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use rings_core::dht::Did;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use rings_core::ecc::PublicKey;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use rings_core::ecc::VerificationPublicKey;
 use rings_core::measure::PeerMeasurement;
 use rings_core::measure::PeerQualityEvidence;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use rings_core::message::MessageVerification;
 use rings_rpc::protos::rings_node::BuildOnionRouteResponse;
 use rings_rpc::protos::rings_node::OnionExitDescriptorInfo;
@@ -22,7 +22,7 @@ use rings_rpc::protos::rings_node::OnlineNodeDescriptorInfo;
 use rings_rpc::protos::rings_node::OnlineNodeTypeInfo;
 use rings_rpc::protos::rings_node::PeerMeasurementCountersInfo;
 use rings_rpc::protos::rings_node::PeerMeasurementInfo;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use serde::de::DeserializeOwned;
 use serde::Serialize;
 use serde_json::Value;
@@ -32,7 +32,7 @@ use crate::error::Result;
 use crate::onion::OnionExitDescriptor;
 use crate::onion::OnionExitPolicy;
 use crate::onion::OnionExitService;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 use crate::onion::OnionExitTarget;
 use crate::onion::OnionExitTransport;
 use crate::onion::OnionRoute;
@@ -43,12 +43,12 @@ fn json_value(value: impl Serialize) -> Result {
     serde_json::to_value(value).map_err(Error::SerdeJsonError)
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn from_json_value(value: Value) -> Result {
     serde_json::from_value(value).map_err(Error::SerdeJsonError)
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn did_from_string(value: &str) -> Result {
     Did::from_str(value).map_err(Error::CoreError)
 }
@@ -61,7 +61,7 @@ fn online_node_type_info(node_type: OnlineNodeType) -> OnlineNodeTypeInfo {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn online_node_type_from_info(node_type: OnlineNodeTypeInfo) -> OnlineNodeType {
     match node_type {
         OnlineNodeTypeInfo::Browser => OnlineNodeType::Browser,
@@ -114,7 +114,7 @@ fn onion_exit_transport_info(transport: OnionExitTransport) -> OnionExitTranspor
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn onion_exit_transport_from_info(transport: OnionExitTransportInfo) -> OnionExitTransport {
     match transport {
         OnionExitTransportInfo::Tcp => OnionExitTransport::Tcp,
@@ -132,7 +132,7 @@ fn onion_exit_service_info(service: OnionExitService) -> OnionExitServiceInfo {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn onion_exit_service_from_info(service: OnionExitServiceInfo) -> Result {
     OnionExitService::new(
         service.name.as_str(),
@@ -158,7 +158,7 @@ fn onion_exit_policy_info(policy: OnionExitPolicy) -> OnionExitPolicyInfo {
     }
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 fn onion_exit_policy_from_info(policy: OnionExitPolicyInfo) -> Result {
     Ok(OnionExitPolicy {
         allowed_targets: policy
@@ -205,7 +205,7 @@ pub(crate) fn onion_exit_descriptor_infos(
         .collect()
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) fn online_node_descriptor_from_info(
     descriptor: OnlineNodeDescriptorInfo,
 ) -> Result {
@@ -227,7 +227,7 @@ pub(crate) fn online_node_descriptor_from_info(
     })
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) fn online_node_descriptors_from_infos(
     descriptors: impl IntoIterator,
 ) -> Vec {
@@ -238,7 +238,7 @@ pub(crate) fn online_node_descriptors_from_infos(
         .collect()
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) fn onion_exit_descriptors_from_info(
     descriptor: OnionExitDescriptorInfo,
 ) -> Result> {
@@ -277,7 +277,7 @@ pub(crate) fn onion_exit_descriptors_from_info(
         .collect())
 }
 
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub(crate) fn onion_exit_descriptors_from_infos(
     descriptors: impl IntoIterator,
 ) -> Vec {
diff --git a/crates/node/src/rpc_impl.rs b/crates/node/src/rpc_impl.rs
index 7b862978d..70e63a288 100644
--- a/crates/node/src/rpc_impl.rs
+++ b/crates/node/src/rpc_impl.rs
@@ -27,8 +27,8 @@ use crate::error::Error as ServerError;
 use crate::processor::Processor;
 use crate::seed::Seed;
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(
         &self,
@@ -59,8 +59,8 @@ impl HandleRpc for Proces
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: ConnectWithDidRequest) -> Result {
         let did = s2d(&req.did)?;
@@ -69,8 +69,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: ConnectWithSeedRequest) -> Result {
         let seed: Seed = Seed::try_from(req)?;
@@ -100,8 +100,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, _req: ListPeersRequest) -> Result {
         let peers = self
@@ -114,8 +114,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: CreateOfferRequest) -> Result {
         let did = s2d(&req.did)?;
@@ -136,8 +136,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: AnswerOfferRequest) -> Result {
         if req.offer.is_empty() {
@@ -166,8 +166,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: AcceptAnswerRequest) -> Result {
         if req.answer.is_empty() {
@@ -188,8 +188,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: DisconnectRequest) -> Result {
         let did = s2d(&req.did)?;
@@ -198,8 +198,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(
         &self,
@@ -215,8 +215,8 @@ impl HandleRpc for Proces
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: SendE2eHandshakeRequest) -> Result {
         let destination = s2d(&req.destination_did)?;
@@ -227,8 +227,8 @@ impl HandleRpc for Processor
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: SendE2eMessageRequest) -> Result {
         let destination = s2d(&req.destination_did)?;
@@ -250,8 +250,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(
         &self,
@@ -266,8 +266,8 @@ impl HandleRpc for
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(
         &self,
@@ -295,8 +295,8 @@ impl HandleRpc for Proces
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: RegisterServiceRequest) -> Result {
         self.register_service(&req.name).await?;
@@ -304,8 +304,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: LookupServiceRequest) -> Result {
         let entry_key = Entry::gen_did(&req.name)
@@ -329,8 +329,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: LookupOnlineNodesRequest) -> Result {
         let nodes = self
@@ -343,8 +343,8 @@ impl HandleRpc for Processo
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: LookupOnionExitsRequest) -> Result {
         let exits = self
@@ -357,8 +357,8 @@ impl HandleRpc for Processor
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: BuildOnionRouteRequest) -> Result {
         let route = self
@@ -369,8 +369,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, _req: NodeInfoRequest) -> Result {
         self.get_node_info()
@@ -379,8 +379,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, req: PeerMeasurementRequest) -> Result {
         let did = s2d(&req.did)?;
@@ -392,8 +392,8 @@ impl HandleRpc for Processor {
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(
         &self,
@@ -405,8 +405,8 @@ impl HandleRpc for Pr
     }
 }
 
-#[cfg_attr(feature = "browser", async_trait(?Send))]
-#[cfg_attr(not(feature = "browser"), async_trait)]
+#[cfg_attr(all(feature = "browser", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "browser", target_family = "wasm")), async_trait)]
 impl HandleRpc for Processor {
     async fn handle_rpc(&self, _req: NodeDidRequest) -> Result {
         let did = self.did();
diff --git a/crates/node/src/tests/mod.rs b/crates/node/src/tests/mod.rs
index 899eb496b..af9444852 100644
--- a/crates/node/src/tests/mod.rs
+++ b/crates/node/src/tests/mod.rs
@@ -1,4 +1,4 @@
 #[cfg(feature = "node")]
 pub mod native;
-#[cfg(feature = "browser")]
+#[cfg(all(feature = "browser", target_family = "wasm"))]
 pub mod wasm;
diff --git a/crates/node/src/tests/native/test_snark.rs b/crates/node/src/tests/native/test_snark.rs
index 6effcd224..8980315d7 100644
--- a/crates/node/src/tests/native/test_snark.rs
+++ b/crates/node/src/tests/native/test_snark.rs
@@ -12,13 +12,10 @@ pub async fn test_gen_proof_and_verify() {
     .await
     .unwrap();
     type F = crate::extension::snark::Field;
-    let input: Input = vec![(
-        "step_in".to_string(),
-        vec![
-            F::from_u64(4u64, SupportedPrimeField::Vesta),
-            F::from_u64(2u64, SupportedPrimeField::Vesta),
-        ],
-    )]
+    let input: Input = vec![("step_in".to_string(), vec![
+        F::from_u64(4u64, SupportedPrimeField::Vesta),
+        F::from_u64(2u64, SupportedPrimeField::Vesta),
+    ])]
     .into();
     let circuits = snark_task_builder.gen_circuits(input, vec![], 5).unwrap();
     assert_eq!(circuits.len(), 5);
diff --git a/crates/node/src/tests/wasm/test_browser.rs b/crates/node/src/tests/wasm/test_browser.rs
index d915570bd..3d50884bc 100644
--- a/crates/node/src/tests/wasm/test_browser.rs
+++ b/crates/node/src/tests/wasm/test_browser.rs
@@ -42,6 +42,18 @@ async fn test_two_provider_connect_and_list() {
     assert_eq!(peers.len(), 0);
 }
 
+#[wasm_bindgen_test]
+async fn test_provider_listener_handle_requests_stop() {
+    let provider = new_provider().await;
+
+    let listener = provider.listen();
+    assert!(!listener.is_stopped());
+
+    listener.stop();
+    assert!(listener.is_stopped());
+    utils::js_utils::window_sleep(10).await.unwrap();
+}
+
 #[wasm_bindgen_test]
 async fn test_send_backend_message() {
     let provider1 = new_provider().await;
diff --git a/crates/node/src/tests/wasm/test_processor.rs b/crates/node/src/tests/wasm/test_processor.rs
index 1a9e936d0..dd31084eb 100644
--- a/crates/node/src/tests/wasm/test_processor.rs
+++ b/crates/node/src/tests/wasm/test_processor.rs
@@ -50,16 +50,22 @@ impl SwarmCallback for SwarmCallbackStruct {
 /// itself and fail with `SwarmMissDidInTable`.
 async fn wait_for_dht_successor(p: &Processor, did: Did) {
     let did = did.to_string();
+    let mut last_inspect = None;
     for _ in 0..100 {
-        let successors = p.swarm.inspect().await.dht.successors;
-        if successors.iter().any(|s| s == &did) {
+        let inspect = p.swarm.inspect().await;
+        if inspect.dht.successors.iter().any(|s| s == &did) {
             return;
         }
+        last_inspect = Some(inspect);
         fluvio_wasm_timer::Delay::new(Duration::from_millis(200))
             .await
             .unwrap();
     }
-    panic!("timeout waiting for {did} to appear in DHT successors");
+    panic!(
+        "timeout waiting for {did} to appear in DHT successors; peers={:?}, dht={:?}",
+        last_inspect.as_ref().map(|inspect| &inspect.peers),
+        last_inspect.as_ref().map(|inspect| &inspect.dht),
+    );
 }
 
 async fn create_connection(p1: &Processor, p2: &Processor) {
diff --git a/crates/node/src/tests/wasm/test_snark.rs b/crates/node/src/tests/wasm/test_snark.rs
index 734999376..74b06cf03 100644
--- a/crates/node/src/tests/wasm/test_snark.rs
+++ b/crates/node/src/tests/wasm/test_snark.rs
@@ -43,13 +43,10 @@ async fn test_send_snark_backend_message() {
     .await
     .unwrap();
     type F = crate::extension::snark::Field;
-    let input: Input = vec![(
-        "step_in".to_string(),
-        vec![
-            F::from_u64(4u64, SupportedPrimeField::Vesta),
-            F::from_u64(2u64, SupportedPrimeField::Vesta),
-        ],
-    )]
+    let input: Input = vec![("step_in".to_string(), vec![
+        F::from_u64(4u64, SupportedPrimeField::Vesta),
+        F::from_u64(2u64, SupportedPrimeField::Vesta),
+    ])]
     .into();
     console_log!("gen circuit");
     let circuits = snark_task_builder.gen_circuits(input, vec![], 5).unwrap();
diff --git a/crates/node/src/util.rs b/crates/node/src/util.rs
index 0a98cbf37..c8b2756e0 100644
--- a/crates/node/src/util.rs
+++ b/crates/node/src/util.rs
@@ -74,9 +74,7 @@ pub fn build_version() -> String {
 /// Expand path with "~" to absolute path.
 #[cfg(feature = "node")]
 pub fn expand_home
(path: P) -> Result
-where
-    P: AsRef,
-{
+where P: AsRef {
     let Ok(stripped) = path.as_ref().strip_prefix("~") else {
         return Ok(path.as_ref().to_path_buf());
     };
@@ -93,9 +91,7 @@ where
 /// Create parent directory of a path if not exists.
 #[cfg(feature = "node")]
 pub fn ensure_parent_dir
(path: P) -> Result<(), Error>
-where
-    P: AsRef,
-{
+where P: AsRef {
     let path = expand_home(path)?;
     let parent = path.parent().ok_or(Error::ParentDirError)?;
     if !parent.is_dir() {
@@ -120,9 +116,7 @@ pub mod loader {
     pub trait ResourceLoader {
         /// Load config from local file or remote url.
         async fn load(source: &str) -> anyhow::Result
-        where
-            Self: Sized + DeserializeOwned,
-        {
+        where Self: Sized + DeserializeOwned {
             let url = Url::parse(source).map_err(|e| anyhow::anyhow!("{}", e))?;
 
             if let Ok(path) = url.to_file_path() {
diff --git a/crates/rpc/src/jsonrpc.rs b/crates/rpc/src/jsonrpc.rs
index 17fc0cfa8..f9b8d3055 100644
--- a/crates/rpc/src/jsonrpc.rs
+++ b/crates/rpc/src/jsonrpc.rs
@@ -47,9 +47,7 @@ impl Client {
 
     /// Sends a typed JSON-RPC request and decodes the typed response body.
     pub async fn call_method(&self, method: Method, req: &impl Serialize) -> Result
-    where
-        T: DeserializeOwned,
-    {
+    where T: DeserializeOwned {
         use jsonrpc_core::*;
 
         let params = serde_json::to_value(req)
diff --git a/crates/rpc/src/protos/rings_node_handler.rs b/crates/rpc/src/protos/rings_node_handler.rs
index 5c8115266..7c2864d2b 100644
--- a/crates/rpc/src/protos/rings_node_handler.rs
+++ b/crates/rpc/src/protos/rings_node_handler.rs
@@ -9,8 +9,8 @@ use super::rings_node::*;
 use crate::method::Method;
 
 /// Used for processor to match rpc request and response.
-#[cfg_attr(feature = "wasm", async_trait(?Send))]
-#[cfg_attr(not(feature = "wasm"), async_trait)]
+#[cfg_attr(all(feature = "wasm", target_family = "wasm"), async_trait(?Send))]
+#[cfg_attr(not(all(feature = "wasm", target_family = "wasm")), async_trait)]
 pub trait HandleRpc {
     /// Handle rpc request and return response.
     async fn handle_rpc(&self, req: Req) -> Result;
diff --git a/crates/snark/src/circuit/bellman.rs b/crates/snark/src/circuit/bellman.rs
index ff1c2b414..57f27b606 100644
--- a/crates/snark/src/circuit/bellman.rs
+++ b/crates/snark/src/circuit/bellman.rs
@@ -13,8 +13,7 @@ use crate::prelude::bellman::Variable;
 /// 
 /// aux bias and input map are removed
 impl bellman::Circuit for Circuit
-where
-    E::Fr: ff::PrimeField,
+where E::Fr: ff::PrimeField
 {
     //noinspection RsBorrowChecker
     fn synthesize>(self, cs: &mut CS) -> Result<(), SynthesisError> {
diff --git a/crates/snark/src/circuit/mod.rs b/crates/snark/src/circuit/mod.rs
index db0d8933a..0e5a25a48 100644
--- a/crates/snark/src/circuit/mod.rs
+++ b/crates/snark/src/circuit/mod.rs
@@ -104,13 +104,10 @@ pub struct Circuit {
 }
 
 impl<'de, F> Deserialize<'de> for Circuit
-where
-    F: PrimeField + Deserialize<'de>,
+where F: PrimeField + Deserialize<'de>
 {
     fn deserialize(deserializer: D) -> core::result::Result
-    where
-        D: Deserializer<'de>,
-    {
+    where D: Deserializer<'de> {
         #[derive(Deserialize)]
         #[serde(bound(deserialize = "F: Deserialize<'de>"))]
         struct CircuitData {
@@ -147,9 +144,7 @@ impl WasmCircuitGenerator {
     /// Generate iterator circuit list
     /// Which iterate inputs and generate circuit
     pub fn gen_circuit(&self, input: Input, sanity_check: bool) -> Result>
-    where
-        F: PrimeField,
-    {
+    where F: PrimeField {
         let mut calc = self.calculator.borrow_mut();
         let witness: Vec = calc.calculate_witness::(input.to_vec(), sanity_check)?;
         Circuit::::try_new(self.r1cs.clone(), witness)
diff --git a/crates/snark/src/tests/native/test_snark.rs b/crates/snark/src/tests/native/test_snark.rs
index 5d4b71cef..b50c524b5 100644
--- a/crates/snark/src/tests/native/test_snark.rs
+++ b/crates/snark/src/tests/native/test_snark.rs
@@ -89,12 +89,10 @@ pub async fn test_calcu_sha256_recursive_snark() -> Result<()> {
     print_mem_status(Some("after gen pp"));
     let first_recursive = first_circuit(&recursive_circuits)?;
     let first_public_inputs = first_recursive.get_public_inputs()?;
-    let mut rec_snark = snark::SNARK::::new(
-        first_recursive,
-        &pp,
-        &first_public_inputs,
-        &vec![F2::from(0)],
-    )?;
+    let mut rec_snark =
+        snark::SNARK::::new(first_recursive, &pp, &first_public_inputs, &vec![F2::from(
+            0,
+        )])?;
     print_mem_status(Some("after gen recursive snark"));
     for c in recursive_circuits {
         rec_snark.foldr(&pp, &c)?;
@@ -123,12 +121,9 @@ pub async fn test_calcu_sha256_recursive_snark() -> Result<()> {
         rec_snark.foldr(&pp, &c)?;
     }
     print_mem_status(Some("after foldr circuits"));
-    let (_z0, _) = rec_snark.verify(
-        &pp,
-        round + round2,
-        &input_inner.clone(),
-        &vec![F2::from(0)],
-    )?;
+    let (_z0, _) = rec_snark.verify(&pp, round + round2, &input_inner.clone(), &vec![F2::from(
+        0,
+    )])?;
     print_mem_status(Some("after verify"));
     Ok(())
 }
@@ -179,32 +174,25 @@ pub async fn test_calcu_bn256_recursive_snark_with_private_input() -> Result<()>
     let pp = snark::SNARK::::gen_pp::(circuit_0.clone())?;
     let first_recursive = first_circuit(&recursive_circuits)?;
     let first_public_inputs = first_recursive.get_public_inputs()?;
-    let mut rec_snark_iter = snark::SNARK::::new(
-        first_recursive,
-        &pp,
-        &first_public_inputs,
-        vec![F2::from(0)],
-    )?;
+    let mut rec_snark_iter =
+        snark::SNARK::::new(first_recursive, &pp, &first_public_inputs, vec![F2::from(
+            0,
+        )])?;
 
     for c in recursive_circuits {
         rec_snark_iter.foldr(&pp, &c)?;
     }
-    rec_snark_iter.verify(
-        &pp,
-        3,
-        &vec![F1::from(4u64), F1::from(2u64)],
-        &vec![F2::from(0)],
-    )?;
+    rec_snark_iter.verify(&pp, 3, &vec![F1::from(4u64), F1::from(2u64)], &vec![
+        F2::from(0),
+    ])?;
     println!("success on create recursive snark");
     let (pk, vk) = snark::SNARK::::compress_setup::(&pp)?;
 
     let compress_snark = rec_snark_iter.compress_prove::(&pp, &pk)?;
-    let ret = snark::SNARK::::compress_verify::(
-        compress_snark,
-        &vk,
-        3,
-        &vec![F1::from(4u64), F1::from(2u64)],
-    );
+    let ret = snark::SNARK::::compress_verify::(compress_snark, &vk, 3, &vec![
+        F1::from(4u64),
+        F1::from(2u64),
+    ]);
     assert!(ret.is_ok());
     Ok(())
 }
diff --git a/crates/snark/src/tests/native/test_wat.rs b/crates/snark/src/tests/native/test_wat.rs
index 1ff77de72..ec70595b6 100644
--- a/crates/snark/src/tests/native/test_wat.rs
+++ b/crates/snark/src/tests/native/test_wat.rs
@@ -91,13 +91,10 @@ fn u256_from_vec_u32_rejects_invalid_word_count(
     };
 
     assert!(
-        matches!(
-            error,
-            Error::WitnessInvalidU256WordLength {
-                expected: 8,
-                actual: 3
-            }
-        ),
+        matches!(error, Error::WitnessInvalidU256WordLength {
+            expected: 8,
+            actual: 3
+        }),
         "{error:?}"
     );
     Ok(())
diff --git a/crates/snark/src/witness/circom.rs b/crates/snark/src/witness/circom.rs
index a3e957b90..4049713fe 100644
--- a/crates/snark/src/witness/circom.rs
+++ b/crates/snark/src/witness/circom.rs
@@ -219,15 +219,12 @@ impl CircomBase for Wasm {
         hash_lsb: u32,
     ) -> Result<()> {
         let func = self.func("getSignalOffset32")?;
-        func.call(
-            store,
-            &[
-                p_sig_offset.into(),
-                component.into(),
-                hash_msb.into(),
-                hash_lsb.into(),
-            ],
-        )?;
+        func.call(store, &[
+            p_sig_offset.into(),
+            component.into(),
+            hash_msb.into(),
+            hash_lsb.into(),
+        ])?;
 
         Ok(())
     }
@@ -241,10 +238,12 @@ impl CircomBase for Wasm {
         p_val: u32,
     ) -> Result<()> {
         let func = self.func("setSignal")?;
-        func.call(
-            store,
-            &[c_idx.into(), component.into(), signal.into(), p_val.into()],
-        )?;
+        func.call(store, &[
+            c_idx.into(),
+            component.into(),
+            signal.into(),
+            p_val.into(),
+        ])?;
 
         Ok(())
     }
diff --git a/crates/transport/src/connection_ref.rs b/crates/transport/src/connection_ref.rs
index 93b41c063..ebafed973 100644
--- a/crates/transport/src/connection_ref.rs
+++ b/crates/transport/src/connection_ref.rs
@@ -69,6 +69,14 @@ where
             .unwrap_or(WebrtcConnectionState::Closed)
     }
 
+    fn data_channel_is_open(&self) -> Result {
+        match self.upgrade() {
+            Ok(c) => c.data_channel_is_open(),
+            Err(Error::ConnectionReleased(_)) => Ok(false),
+            Err(error) => Err(error),
+        }
+    }
+
     // On a released reference this reports the interop default rather than an error, by deliberate
     // design: `ConnectionInterface::max_message_size` returns `usize` (it feeds the framing
     // planner), and threading a `Result` through it and every backend for this one edge would add
@@ -130,6 +138,14 @@ where
             .unwrap_or(WebrtcConnectionState::Closed)
     }
 
+    fn data_channel_is_open(&self) -> Result {
+        match self.upgrade() {
+            Ok(c) => c.data_channel_is_open(),
+            Err(Error::ConnectionReleased(_)) => Ok(false),
+            Err(error) => Err(error),
+        }
+    }
+
     // On a released reference this reports the interop default rather than an error, by deliberate
     // design: `ConnectionInterface::max_message_size` returns `usize` (it feeds the framing
     // planner), and threading a `Result` through it and every backend for this one edge would add
@@ -200,6 +216,9 @@ mod tests {
         fn webrtc_connection_state(&self) -> WebrtcConnectionState {
             unreachable!()
         }
+        fn data_channel_is_open(&self) -> Result {
+            unreachable!()
+        }
         async fn get_stats(&self) -> Vec {
             unreachable!()
         }
diff --git a/crates/transport/src/connections/dummy/mod.rs b/crates/transport/src/connections/dummy/mod.rs
index 9436f1ded..054bd9b0c 100644
--- a/crates/transport/src/connections/dummy/mod.rs
+++ b/crates/transport/src/connections/dummy/mod.rs
@@ -428,6 +428,17 @@ impl ConnectionInterface for DummyConnection {
         *self.connection_state()
     }
 
+    fn data_channel_is_open(&self) -> Result {
+        // Dummy handshakes use `Connecting` for the interval after an offer is
+        // answered but before the opposite side has accepted the answer. Tests
+        // can deliver a data-channel-open callback in that interval to model
+        // browser timing where SCTP opens before ICE reaches `Connected`.
+        Ok(matches!(
+            self.webrtc_connection_state(),
+            WebrtcConnectionState::Connected | WebrtcConnectionState::Connecting
+        ))
+    }
+
     fn max_message_size(&self) -> usize {
         match MAX_MESSAGE_SIZE.with(|m| m.get()) {
             0 => MAX_DATA_CHANNEL_MESSAGE_SIZE,
@@ -472,12 +483,7 @@ impl ConnectionInterface for DummyConnection {
         if WAIT_FOR_DATA_CHANNEL_OPEN_PENDING.with(|pending| pending.get()) {
             std::future::pending::<()>().await;
         }
-        // Will pass if the state is connecting to prevent release connection in the `test_handshake_on_both_sides` test.
-        // The connecting state means an offer is answered but not accepted by the other side.
-        if matches!(
-            self.webrtc_connection_state(),
-            WebrtcConnectionState::Connected | WebrtcConnectionState::Connecting
-        ) {
+        if self.data_channel_is_open()? {
             Ok(())
         } else {
             Err(Error::DataChannelOpen(
diff --git a/crates/transport/src/connections/native_webrtc/mod.rs b/crates/transport/src/connections/native_webrtc/mod.rs
index 1421ec2af..7c672222b 100644
--- a/crates/transport/src/connections/native_webrtc/mod.rs
+++ b/crates/transport/src/connections/native_webrtc/mod.rs
@@ -119,20 +119,30 @@ fn duplicate_host_candidate_line(line: &str, extra_addresses: &[String]) -> Vec<
     }
 
     let fields = line.split_whitespace().collect::>();
-    if fields.len() < 8 || fields[6] != "typ" || fields[7] != "host" {
+    let Some(address) = fields.get(4) else {
+        return Vec::new();
+    };
+    let Some(candidate_type_marker) = fields.get(6) else {
+        return Vec::new();
+    };
+    let Some(candidate_type) = fields.get(7) else {
+        return Vec::new();
+    };
+    if *candidate_type_marker != "typ" || *candidate_type != "host" {
         return Vec::new();
     }
 
     extra_addresses
         .iter()
-        .filter(|candidate| candidate.as_str() != fields[4])
-        .map(|candidate| {
+        .filter(|candidate| candidate.as_str() != *address)
+        .filter_map(|candidate| {
             let mut duplicate = fields
                 .iter()
                 .map(|field| field.to_string())
                 .collect::>();
-            duplicate[4] = candidate.clone();
-            duplicate.join(" ")
+            let address_slot = duplicate.get_mut(4)?;
+            *address_slot = candidate.clone();
+            Some(duplicate.join(" "))
         })
         .collect()
 }
@@ -372,6 +382,10 @@ impl ConnectionInterface for WebrtcConnection {
         self.webrtc_conn.connection_state().into()
     }
 
+    fn data_channel_is_open(&self) -> Result {
+        self.webrtc_data_channel.all_ready()
+    }
+
     fn max_message_size(&self) -> usize {
         // The value negotiated from the remote SDP at handshake; `0` = not yet negotiated, so
         // fall back to the interop default.
@@ -434,7 +448,7 @@ impl ConnectionInterface for WebrtcConnection {
             return Err(Error::DataChannelOpen("Connection unavailable".to_string()));
         }
 
-        if self.webrtc_data_channel.all_ready()? {
+        if self.data_channel_is_open()? {
             return Ok(());
         }
 
@@ -442,7 +456,7 @@ impl ConnectionInterface for WebrtcConnection {
             .set_timeout(WEBRTC_WAIT_FOR_DATA_CHANNEL_OPEN_TIMEOUT);
         self.webrtc_data_channel_state_notifier.clone().await;
 
-        if self.webrtc_data_channel.all_ready()? {
+        if self.data_channel_is_open()? {
             return Ok(());
         } else {
             return Err(Error::DataChannelOpen(format!(
@@ -715,10 +729,10 @@ mod tests {
     fn external_address_candidates_split_trim_and_deduplicate() {
         let candidates = external_address_candidates(Some(" 127.0.0.1, 192.168.215.2,127.0.0.1, "));
 
-        assert_eq!(
-            candidates,
-            vec!["127.0.0.1".to_string(), "192.168.215.2".to_string()]
-        );
+        assert_eq!(candidates, vec![
+            "127.0.0.1".to_string(),
+            "192.168.215.2".to_string()
+        ]);
     }
 
     #[test]
diff --git a/crates/transport/src/connections/web_sys_webrtc/mod.rs b/crates/transport/src/connections/web_sys_webrtc/mod.rs
index f7544dd5a..626a3b77e 100644
--- a/crates/transport/src/connections/web_sys_webrtc/mod.rs
+++ b/crates/transport/src/connections/web_sys_webrtc/mod.rs
@@ -219,6 +219,10 @@ impl ConnectionInterface for WebSysWebrtcConnection {
         self.webrtc_conn.connection_state().into()
     }
 
+    fn data_channel_is_open(&self) -> Result {
+        self.webrtc_data_channel.all_ready()
+    }
+
     fn max_message_size(&self) -> usize {
         // The value negotiated from the remote SDP at handshake; `0` = not yet negotiated, so
         // fall back to the interop default. Same parsing as native (consistent behaviour).
@@ -316,7 +320,7 @@ impl ConnectionInterface for WebSysWebrtcConnection {
             return Err(Error::DataChannelOpen("Connection unavailable".to_string()));
         }
 
-        if self.webrtc_data_channel.all_ready()? {
+        if self.data_channel_is_open()? {
             return Ok(());
         }
 
@@ -324,7 +328,7 @@ impl ConnectionInterface for WebSysWebrtcConnection {
             .set_timeout(WEBRTC_WAIT_FOR_DATA_CHANNEL_OPEN_TIMEOUT);
         self.webrtc_data_channel_state_notifier.clone().await;
 
-        if self.webrtc_data_channel.all_ready()? {
+        if self.data_channel_is_open()? {
             return Ok(());
         } else {
             return Err(Error::DataChannelOpen(format!(
diff --git a/crates/transport/src/core/sdp.rs b/crates/transport/src/core/sdp.rs
index 9ff50bc09..0e00132f3 100644
--- a/crates/transport/src/core/sdp.rs
+++ b/crates/transport/src/core/sdp.rs
@@ -232,19 +232,16 @@ mod tests {
     #[test]
     fn lex_splits_type_and_value_and_drops_junk() {
         let lines: Vec = lex("v=0\r\na=sendrecv\r\n\r\nnonsense\r\n").collect();
-        assert_eq!(
-            lines,
-            vec![
-                Line {
-                    kind: 'v',
-                    value: "0"
-                },
-                Line {
-                    kind: 'a',
-                    value: "sendrecv"
-                },
-            ]
-        );
+        assert_eq!(lines, vec![
+            Line {
+                kind: 'v',
+                value: "0"
+            },
+            Line {
+                kind: 'a',
+                value: "sendrecv"
+            },
+        ]);
     }
 
     #[test]
@@ -272,26 +269,20 @@ mod tests {
                    a=max-message-size:65536\r\n";
         let ast = parse(sdp);
         // the pre-`m=` attribute is session-level (and `group:…` parses as a key:value pair)
-        assert_eq!(
-            ast.session_attrs,
-            vec![Attribute::Pair {
-                key: "group",
-                value: "BUNDLE 0"
-            }]
-        );
+        assert_eq!(ast.session_attrs, vec![Attribute::Pair {
+            key: "group",
+            value: "BUNDLE 0"
+        }]);
         // the post-`m=` attribute is media-level under the data-channel section
         assert_eq!(ast.media.len(), 1);
         assert_eq!(
             ast.media[0].media,
             "application 9 UDP/DTLS/SCTP webrtc-datachannel"
         );
-        assert_eq!(
-            ast.media[0].attrs,
-            vec![Attribute::Pair {
-                key: "max-message-size",
-                value: "65536"
-            }]
-        );
+        assert_eq!(ast.media[0].attrs, vec![Attribute::Pair {
+            key: "max-message-size",
+            value: "65536"
+        }]);
     }
 
     #[test]
diff --git a/crates/transport/src/core/transport.rs b/crates/transport/src/core/transport.rs
index 86c597420..529865c6d 100644
--- a/crates/transport/src/core/transport.rs
+++ b/crates/transport/src/core/transport.rs
@@ -107,6 +107,14 @@ pub trait ConnectionInterface {
     /// Get current webrtc connection state.
     fn webrtc_connection_state(&self) -> WebrtcConnectionState;
 
+    /// Return whether every data channel used by this connection is currently open.
+    ///
+    /// This is the routability predicate. ICE may still report `Connecting`
+    /// when the SCTP data channels have already opened, so callers that need to
+    /// decide whether payload transport is usable should check this method
+    /// rather than requiring [`WebrtcConnectionState::Connected`].
+    fn data_channel_is_open(&self) -> Result;
+
     /// The maximum size, in bytes, of one message this connection can send — the channel's
     /// negotiated SCTP / data-channel `max_message_size`, capped at
     /// [`MAX_DATA_CHANNEL_MESSAGE_SIZE`] for cross-peer interop. A caller must keep every sent
diff --git a/crates/webview/src/render.rs b/crates/webview/src/render.rs
index cd817140b..bae320d9d 100644
--- a/crates/webview/src/render.rs
+++ b/crates/webview/src/render.rs
@@ -42,8 +42,7 @@ pub struct WebviewRenderer {
 }
 
 impl WebviewRenderer
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     /// Build a renderer around an existing gateway.
     pub fn new(gateway: WebviewGateway) -> Self {
diff --git a/crates/webview/src/transport.rs b/crates/webview/src/transport.rs
index fe7053b95..e4032a573 100644
--- a/crates/webview/src/transport.rs
+++ b/crates/webview/src/transport.rs
@@ -137,8 +137,7 @@ impl GatewayResponsePolicy {
 }
 
 impl WebviewGateway
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     /// Build a webview gateway around `transport`.
     pub fn new(prefix: GatewayPrefix, transport: T) -> Self {
@@ -223,8 +222,7 @@ where
 }
 
 impl ConcurrentWebviewGateway
-where
-    T: GatewayTransport,
+where T: GatewayTransport
 {
     /// Build a concurrent webview gateway around `transport`.
     pub fn new(prefix: GatewayPrefix, transport: T) -> Self {
diff --git a/examples/native/src/main.rs b/examples/native/src/main.rs
index 265043202..9ade475d8 100644
--- a/examples/native/src/main.rs
+++ b/examples/native/src/main.rs
@@ -72,10 +72,9 @@ async fn main() -> Result<(), Box> {
     println!("===> request ConnectPeerViaHttp api...");
     let resp: ConnectPeerViaHttpResponse = serde_json::from_value(
         provider
-            .request(
-                Method::ConnectPeerViaHttp,
-                ConnectPeerViaHttpRequest { url: args.seed_url },
-            )
+            .request(Method::ConnectPeerViaHttp, ConnectPeerViaHttpRequest {
+                url: args.seed_url,
+            })
             .await?,
     )?;
     println!("<=== ConnectPeerViaHttpResponse: {resp:?}");
diff --git a/examples/snark/bn256.rs b/examples/snark/bn256.rs
index d060067b8..3443b36d8 100644
--- a/examples/snark/bn256.rs
+++ b/examples/snark/bn256.rs
@@ -66,23 +66,18 @@ async fn main() -> ExampleResult<()> {
     for c in recursive_circuits {
         rec_snark_iter.foldr(&pp, &c)?;
     }
-    rec_snark_iter.verify(
-        &pp,
-        3,
-        &vec![F1::from(4u64), F1::from(2u64)],
-        &vec![F2::from(0)],
-    )?;
+    rec_snark_iter.verify(&pp, 3, &vec![F1::from(4u64), F1::from(2u64)], &vec![
+        F2::from(0),
+    ])?;
     println!("success on create recursive snark");
     let (pk, vk) = snark::SNARK::::compress_setup::(&pp)?;
 
     let compress_snark = rec_snark_iter.compress_prove::(&pp, &pk)?;
     let compress_snark_ref = Rc::new(compress_snark);
-    snark::SNARK::::compress_verify::(
-        compress_snark_ref,
-        &vk,
-        3,
-        &vec![F1::from(4u64), F1::from(2u64)],
-    )?;
+    snark::SNARK::::compress_verify::(compress_snark_ref, &vk, 3, &vec![
+        F1::from(4u64),
+        F1::from(2u64),
+    ])?;
 
     Ok(())
 }
diff --git a/examples/snark/src/lib.rs b/examples/snark/src/lib.rs
index a4bd6a298..a82a1fd39 100644
--- a/examples/snark/src/lib.rs
+++ b/examples/snark/src/lib.rs
@@ -136,17 +136,13 @@ pub fn first_recursive_circuit(circuits: &[T]) -> ExampleResult<&T> {
 
 /// Public input used by the simple BN256 example.
 pub fn simple_bn256_initial_input() -> Input
-where
-    F: PrimeField + From,
-{
+where F: PrimeField + From {
     vec![("step_in".to_string(), vec![F::from(4u64), F::from(2u64)])].into()
 }
 
 /// Private inputs used by the simple BN256 recursive example.
 pub fn simple_bn256_private_inputs() -> Vec>
-where
-    F: PrimeField + From,
-{
+where F: PrimeField + From {
     vec![
         vec![("adder".to_string(), vec![F::from(1u64)])].into(),
         vec![("adder".to_string(), vec![F::from(42u64)])].into(),
@@ -208,17 +204,13 @@ pub async fn simple_bn256_one_step_prove_verify() -> ExampleResult<()> {
 
 /// Public input used by the Merkle-tree example.
 pub fn merkle_tree_initial_input() -> Input
-where
-    F: PrimeField + From,
-{
+where F: PrimeField + From {
     vec![("leaf".to_string(), vec![F::from(42u64)])].into()
 }
 
 /// Private path inputs used by the Merkle-tree example.
 pub fn merkle_tree_private_inputs() -> Vec>
-where
-    F: PrimeField + From,
-{
+where F: PrimeField + From {
     vec![
         vec![("path".to_string(), vec![F::from(1u64), F::from(0u64)])].into(),
         vec![("path".to_string(), vec![F::from(42u64), F::from(1u64)])].into(),
@@ -247,13 +239,10 @@ mod tests {
         let initial = simple_bn256_initial_input::();
         let private = simple_bn256_private_inputs::();
 
-        assert_eq!(
-            initial.input.as_slice(),
-            [(
-                "step_in".to_string(),
-                vec![Bn256TestField::from(4u64), Bn256TestField::from(2u64)]
-            )]
-        );
+        assert_eq!(initial.input.as_slice(), [("step_in".to_string(), vec![
+            Bn256TestField::from(4u64),
+            Bn256TestField::from(2u64)
+        ])]);
         assert_eq!(private.len(), 3);
         assert!(private
             .iter()
@@ -272,10 +261,9 @@ mod tests {
         let initial = merkle_tree_initial_input::();
         let private = merkle_tree_private_inputs::();
 
-        assert_eq!(
-            initial.input.as_slice(),
-            [("leaf".to_string(), vec![MerkleTreeTestField::from(42u64)])]
-        );
+        assert_eq!(initial.input.as_slice(), [("leaf".to_string(), vec![
+            MerkleTreeTestField::from(42u64)
+        ])]);
         assert_eq!(private.len(), 3);
         assert!(private.iter().all(
             |input| matches!(input.input.as_slice(), [(name, path)] if name == "path" && path.len() == 2)
diff --git a/frontend/scripts/test-webview-service-worker.mts b/frontend/scripts/test-webview-service-worker.mts
index 3efac9da2..f74167a8d 100644
--- a/frontend/scripts/test-webview-service-worker.mts
+++ b/frontend/scripts/test-webview-service-worker.mts
@@ -63,7 +63,7 @@ const context: ServiceWorkerTestContext = {
     addEventListener() {},
   },
 };
-context.globalThis = context;
+context["globalThis"] = context;
 
 vm.runInNewContext(`${serviceWorkerSource}\nglobalThis.__ringsWebviewServiceWorkerTest = { requestKind };`, context, {
   filename: serviceWorkerPath,

From e4c48f08485176a5b0e6d02472598b09a449e966 Mon Sep 17 00:00:00 2001
From: "Ryan.K" <662346+RyanKung@users.noreply.github.com>
Date: Mon, 27 Jul 2026 01:41:59 +0800
Subject: [PATCH 11/23] Prepare webview gateway 1.0.0

---
 Cargo.lock                                    |  20 +-
 Cargo.toml                                    |  14 +-
 crates/core/src/dht/stabilization.rs          |  25 ++-
 crates/core/src/error.rs                      |  12 ++
 crates/core/src/swarm/transport.rs            |   8 +-
 crates/core/src/swarm/transport/delivery.rs   |   4 +-
 crates/core/src/swarm/transport/liveness.rs   |  16 ++
 .../core/src/tests/default/test_chunk_e2e.rs  |  10 +-
 .../src/tests/default/test_stabilization.rs   | 129 +++++++++++--
 crates/node/bin/rings.rs                      |   2 +-
 crates/node/src/error.rs                      |   8 +
 crates/node/src/native/config.rs              |  22 ++-
 crates/node/src/onion/circuit/shell.rs        |  22 ++-
 .../circuit/tests/test_circuit_protocol.rs    |  23 ++-
 crates/node/src/onion/https/mod.rs            |  15 +-
 .../src/onion/https/tests/test_https_proxy.rs |  17 +-
 crates/node/src/onion/mod.rs                  |   8 +-
 crates/node/src/onion/replay.rs               |   3 +-
 .../onion/route/tests/test_route_selection.rs |  23 ++-
 crates/node/src/onion/tcp/mod.rs              |  22 ++-
 .../src/onion/tests/test_exit_registry.rs     |  15 +-
 crates/node/src/processor/builder.rs          |   4 +-
 crates/node/src/processor/config.rs           |   4 +-
 crates/node/src/processor/mod.rs              |   2 +-
 .../node/src/processor/tests/test_config.rs   |  10 +-
 .../node/src/processor/tests/test_network.rs  |   9 +-
 .../node/src/processor/tests/test_registry.rs | 119 ++++++++++++
 crates/node/src/provider/browser/provider.rs  | 132 ++++++++-----
 crates/node/src/registration.rs               | 105 +++++++++--
 crates/webview/src/browser.rs                 |  30 +++
 crates/webview/src/header.rs                  |  44 +++++
 crates/webview/tests/browser_gateway.rs       |  25 ++-
 .../tests/browser_gateway/fixture_server.rs   |  19 ++
 docker/cluster/Dockerfile                     |   4 +-
 docker/cluster/README.md                      |   1 +
 docker/cluster/rings-cluster-entrypoint.sh    |   4 +-
 frontend/Cargo.lock                           |  16 +-
 frontend/Cargo.toml                           |   2 +-
 frontend/assets/webview-host.js               |   2 +-
 frontend/assets/webview-overlay.js            |  93 +++++++--
 frontend/rings-webview-service-worker.js      |  81 +++++++-
 .../scripts/test-extension-wallet-bridge.mts  |   2 +-
 frontend/scripts/test-webview-overlay.mts     | 177 ++++++++++++++++++
 .../scripts/test-webview-service-worker.mts   |  83 +++++++-
 frontend/src/app.rs                           |  44 ++++-
 frontend/src/browser_api.rs                   |   7 +-
 frontend/src/node.rs                          |  36 +---
 frontend/src/webview.rs                       |   3 +-
 frontend/src/webview/onion_browser_tests.rs   |   2 +-
 frontend/src/webview/tests.rs                 |  14 +-
 package-lock.json                             |   4 +-
 package.json                                  |   5 +-
 52 files changed, 1244 insertions(+), 257 deletions(-)
 create mode 100644 frontend/scripts/test-webview-overlay.mts

diff --git a/Cargo.lock b/Cargo.lock
index b5e0e33bc..ca8c7c32d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4409,7 +4409,7 @@ dependencies = [
 
 [[package]]
 name = "rings-core"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "ark-bls12-381",
  "ark-ec",
@@ -4482,7 +4482,7 @@ dependencies = [
 
 [[package]]
 name = "rings-derive"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -4492,7 +4492,7 @@ dependencies = [
 
 [[package]]
 name = "rings-native-example"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "base64 0.13.1",
@@ -4506,7 +4506,7 @@ dependencies = [
 
 [[package]]
 name = "rings-node"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "anyhow",
  "arrayref",
@@ -4565,7 +4565,7 @@ dependencies = [
 
 [[package]]
 name = "rings-relay-example"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "rings-core",
  "rings-node",
@@ -4574,7 +4574,7 @@ dependencies = [
 
 [[package]]
 name = "rings-rpc"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "base64 0.13.1",
@@ -4590,7 +4590,7 @@ dependencies = [
 
 [[package]]
 name = "rings-snark"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "bellpepper-core",
  "byteorder",
@@ -4618,7 +4618,7 @@ dependencies = [
 
 [[package]]
 name = "rings-snark-example"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "rings-snark",
  "tokio",
@@ -4626,7 +4626,7 @@ dependencies = [
 
 [[package]]
 name = "rings-transport"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "bincode",
@@ -4652,7 +4652,7 @@ dependencies = [
 
 [[package]]
 name = "rings-webview"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "futures",
diff --git a/Cargo.toml b/Cargo.toml
index 95e47f5e7..c26855f31 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ members = ["crates/*", "examples/native", "examples/relay", "examples/snark"]
 exclude = ["third_party/proc-macro-error2"]
 
 [workspace.package]
-version = "0.14.0"
+version = "1.0.0"
 edition = "2021"
 license = "GPL-3.0"
 authors = ["RND "]
@@ -14,12 +14,12 @@ repository = "https://github.com/RingsNetwork/rings"
 async-trait = "0.1.77"
 js-sys = "0.3.98"
 jsonrpc-core = "18.0.0"
-rings-core = { path = "crates/core", version = "0.14.0", default-features = false }
-rings-derive = { path = "crates/derive", version = "0.14.0", default-features = false }
-rings-node = { path = "crates/node", version = "0.14.0" }
-rings-rpc = { path = "crates/rpc", version = "0.14.0", default-features = false }
-rings-snark = { path = "crates/snark", version = "0.14.0", default-features = false }
-rings-transport = { path = "crates/transport", version = "0.14.0" }
+rings-core = { path = "crates/core", version = "1.0.0", default-features = false }
+rings-derive = { path = "crates/derive", version = "1.0.0", default-features = false }
+rings-node = { path = "crates/node", version = "1.0.0" }
+rings-rpc = { path = "crates/rpc", version = "1.0.0", default-features = false }
+rings-snark = { path = "crates/snark", version = "1.0.0", default-features = false }
+rings-transport = { path = "crates/transport", version = "1.0.0" }
 serde-wasm-bindgen = "0.6.5"
 wasm-bindgen = "0.2.121"
 wasm-bindgen-futures = "0.4.71"
diff --git a/crates/core/src/dht/stabilization.rs b/crates/core/src/dht/stabilization.rs
index c6d7ee825..d80436351 100644
--- a/crates/core/src/dht/stabilization.rs
+++ b/crates/core/src/dht/stabilization.rs
@@ -214,7 +214,9 @@ impl Stabilizer {
     }
 
     async fn run_step(&self, step: &'static str, timeout: Duration, future: F)
-    where F: Future> {
+    where
+        F: Future>,
+    {
         tracing::debug!(
             target: "rings_core::dht::stabilization",
             local = %self.dht.did,
@@ -357,6 +359,22 @@ impl Stabilizer {
                     entries,
                         "STABILIZATION storage repair send complete"
                 ),
+                Err(e) if e.is_data_channel_backpressure() => {
+                    deferred = deferred.saturating_add(1);
+                    tracing::warn!(
+                        target: "rings_core::dht::stabilization",
+                        local = %self.dht.did,
+                        purpose = ?purpose,
+                        destination = ?destination,
+                        destination_did = %destination_did,
+                        next_hop = ?next_hop,
+                        next_hop_state = ?next_hop_state,
+                        entries,
+                        error = ?e,
+                        "STABILIZATION storage repair deferred by data-channel backpressure"
+                    );
+                    continue;
+                }
                 Err(e) => {
                     tracing::error!(
                         target: "rings_core::dht::stabilization",
@@ -756,13 +774,16 @@ impl Stabilizer {
                     );
                 }
                 Err(error) => {
-                    self.transport.record_peer_message_send_failed(peer).await;
+                    if error.records_peer_send_failure() {
+                        self.transport.record_peer_message_send_failed(peer).await;
+                    }
                     tracing::warn!(
                         target: "rings_core::dht::stabilization",
                         local = %self.dht.did,
                         peer = %peer,
                         state = ?state,
                         error = ?error,
+                        records_peer_failure = error.records_peer_send_failure(),
                         "STABILIZATION peer liveness probe send failed"
                     );
                 }
diff --git a/crates/core/src/error.rs b/crates/core/src/error.rs
index a5dd46aef..ce7c8bf62 100644
--- a/crates/core/src/error.rs
+++ b/crates/core/src/error.rs
@@ -624,6 +624,18 @@ impl Error {
     pub(crate) fn unexpected_peer_ring_action(action: crate::dht::PeerRingAction) -> Self {
         Self::PeerRingUnexpectedAction(Box::new(action))
     }
+
+    /// True when a send failed because the local data-channel write queue did not accept bytes
+    /// before the bounded admission timeout. This is a local backpressure signal, not evidence
+    /// that the remote peer is unreachable or malicious.
+    pub(crate) const fn is_data_channel_backpressure(&self) -> bool {
+        matches!(self, Self::DataChannelSendQueueTimeout { .. })
+    }
+
+    /// Whether this error should degrade peer quality through `FailedToSend`.
+    pub(crate) const fn records_peer_send_failure(&self) -> bool {
+        !self.is_data_channel_backpressure()
+    }
 }
 
 #[cfg(all(feature = "wasm", target_family = "wasm"))]
diff --git a/crates/core/src/swarm/transport.rs b/crates/core/src/swarm/transport.rs
index 221a6ad02..91eacb6f3 100644
--- a/crates/core/src/swarm/transport.rs
+++ b/crates/core/src/swarm/transport.rs
@@ -952,7 +952,9 @@ impl PayloadSender for SwarmTransport {
             {
                 Ok(delivery) => spawn_delivery(delivery, did, self.measure.clone()),
                 Err(e) => {
-                    self.record_peer_message_send_failed(did).await;
+                    if e.records_peer_send_failure() {
+                        self.record_peer_message_send_failed(did).await;
+                    }
                     return Err(e);
                 }
             },
@@ -978,7 +980,9 @@ impl PayloadSender for SwarmTransport {
                             );
                         }
                         Err(e) => {
-                            self.record_peer_message_send_failed(did).await;
+                            if e.records_peer_send_failure() {
+                                self.record_peer_message_send_failed(did).await;
+                            }
                             return Err(e);
                         }
                     }
diff --git a/crates/core/src/swarm/transport/delivery.rs b/crates/core/src/swarm/transport/delivery.rs
index 7e7afadb1..73176ed2b 100644
--- a/crates/core/src/swarm/transport/delivery.rs
+++ b/crates/core/src/swarm/transport/delivery.rs
@@ -340,7 +340,9 @@ async fn run_chunked_send(
             ChunkSendProgress::Ready(Ok(delivery)) => delivery,
             ChunkSendProgress::Ready(Err(e)) => {
                 tracing::warn!("Chunked send to {did} stopped: {e}");
-                record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+                if e.records_peer_send_failure() {
+                    record_measurement(measure, did, MeasureCounter::FailedToSend).await;
+                }
                 return;
             }
             ChunkSendProgress::Cancelled(reason) => {
diff --git a/crates/core/src/swarm/transport/liveness.rs b/crates/core/src/swarm/transport/liveness.rs
index 63a872eda..fcfc7e7be 100644
--- a/crates/core/src/swarm/transport/liveness.rs
+++ b/crates/core/src/swarm/transport/liveness.rs
@@ -152,6 +152,12 @@ impl PeerLivenessMap {
         liveness.mark_probe_sent(sent_at_ms);
         self.peers.insert(peer, liveness);
     }
+
+    #[cfg(all(test, feature = "dummy", not(target_family = "wasm")))]
+    fn force_connected_at(&mut self, peer: Did, generation: u64, connected_at_ms: i64) {
+        self.peers
+            .insert(peer, PeerLiveness::new(generation, connected_at_ms));
+    }
 }
 
 /// Peer liveness expiry evidence.
@@ -269,4 +275,14 @@ impl SwarmTransport {
             .force_probe_sent_at(peer, generation, sent_at_ms);
         Ok(())
     }
+
+    #[cfg(all(test, feature = "dummy", not(target_family = "wasm")))]
+    pub(crate) fn force_peer_connected_at(&self, peer: Did, connected_at_ms: i64) -> Result<()> {
+        let Some(generation) = self.active_generation(peer)? else {
+            return Ok(());
+        };
+        self.peer_liveness()?
+            .force_connected_at(peer, generation, connected_at_ms);
+        Ok(())
+    }
 }
diff --git a/crates/core/src/tests/default/test_chunk_e2e.rs b/crates/core/src/tests/default/test_chunk_e2e.rs
index 8f830ebc3..56c295de7 100644
--- a/crates/core/src/tests/default/test_chunk_e2e.rs
+++ b/crates/core/src/tests/default/test_chunk_e2e.rs
@@ -248,9 +248,11 @@ async fn spawned_storage_sync_tail_cancelled_by_route_disappear_does_not_degrade
 
 #[tokio::test]
 async fn send_queue_backpressure_returns_transport_timeout() {
+    let measure = Arc::new(CountingMeasure::default());
+    let measure_impl: MeasureImpl = measure.clone();
     let key1 = SecretKey::random();
     let key2 = SecretKey::random();
-    let node1 = prepare_node(key1).await;
+    let node1 = prepare_node_with_measure(key1, measure_impl).unwrap();
     let node2 = prepare_node(key2).await;
     manually_establish_connection(&node1.swarm, &node2.swarm).await;
     wait_for_connection_state(&node1, node2.did(), WebrtcConnectionState::Connected)
@@ -260,6 +262,7 @@ async fn send_queue_backpressure_returns_transport_timeout() {
         .await
         .unwrap();
 
+    let failed_before = measure.count(node2.did(), MeasureCounter::FailedToSend);
     let _guard = PendingSendGuard::new();
     let err = node1
         .swarm
@@ -274,6 +277,11 @@ async fn send_queue_backpressure_returns_transport_timeout() {
         ),
         "expected DataChannelSendQueueTimeout, got {err:?}"
     );
+    assert_eq!(
+        measure.count(node2.did(), MeasureCounter::FailedToSend),
+        failed_before,
+        "data-channel queue backpressure is local admission pressure, not peer failure"
+    );
 }
 
 #[tokio::test]
diff --git a/crates/core/src/tests/default/test_stabilization.rs b/crates/core/src/tests/default/test_stabilization.rs
index eba4cbc3f..be65e10e3 100644
--- a/crates/core/src/tests/default/test_stabilization.rs
+++ b/crates/core/src/tests/default/test_stabilization.rs
@@ -118,6 +118,24 @@ impl Drop for DropMessagesGuard {
     }
 }
 
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+struct PendingSendGuard;
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+impl PendingSendGuard {
+    fn new() -> Self {
+        dummy_controlled::set_send_message_pending(true);
+        Self
+    }
+}
+
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+impl Drop for PendingSendGuard {
+    fn drop(&mut self) {
+        dummy_controlled::set_send_message_pending(false);
+    }
+}
+
 fn prepare_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result {
     let session = SessionSk::new_with_seckey(&key)?;
     let swarm = Arc::new(
@@ -136,19 +154,31 @@ fn prepare_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result Result {
+    prepare_repair_node_with_optional_measure(key, None)
+}
+
+fn prepare_repair_node_with_measure(key: SecretKey, measure: MeasureImpl) -> Result {
+    prepare_repair_node_with_optional_measure(key, Some(measure))
+}
+
+fn prepare_repair_node_with_optional_measure(
+    key: SecretKey,
+    measure: Option,
+) -> Result {
     let session = SessionSk::new_with_seckey(&key)?;
-    let swarm = Arc::new(
-        SwarmBuilder::new(
-            0,
-            "stun://stun.l.google.com:19302",
-            Box::new(MemStorage::new()),
-            session,
-        )
-        .dht_finger_table_size(super::TEST_DHT_FINGER_TABLE_SIZE)
-        .dht_storage_redundancy(2)
-        .dht_virtual_nodes(0)
-        .build(),
-    );
+    let mut builder = SwarmBuilder::new(
+        0,
+        "stun://stun.l.google.com:19302",
+        Box::new(MemStorage::new()),
+        session,
+    )
+    .dht_finger_table_size(super::TEST_DHT_FINGER_TABLE_SIZE)
+    .dht_storage_redundancy(2)
+    .dht_virtual_nodes(0);
+    if let Some(measure) = measure {
+        builder = builder.measure(measure);
+    }
+    let swarm = Arc::new(builder.build());
     Ok(Node::new(swarm))
 }
 
@@ -445,6 +475,81 @@ async fn repair_storage_defers_sync_to_fresh_next_hop() -> Result<()> {
     Ok(())
 }
 
+#[cfg(all(feature = "dummy", not(target_family = "wasm")))]
+#[tokio::test]
+async fn repair_storage_backpressure_defers_without_degrading_or_removing_peer() -> Result<()> {
+    let measure = Arc::new(CountingMeasure::default());
+    let measure_impl: MeasureImpl = measure.clone();
+    let mut key1 = SecretKey::random();
+    let mut key2 = SecretKey::random();
+    if key1.address() < key2.address() {
+        (key1, key2) = (key2, key1)
+    }
+    let node1 = prepare_repair_node_with_measure(key1, measure_impl)?;
+    let node2 = prepare_repair_node(key2)?;
+    manually_establish_connection(&node1.swarm, &node2.swarm).await;
+
+    wait_for_successor(&node1, node2.did()).await?;
+    wait_for_msgs([&node1, &node2]).await;
+    node1
+        .swarm
+        .transport
+        .force_peer_connected_at(node2.did(), get_epoch_ms_i64() - 31_000)?;
+
+    node1.dht().successors().extend(&[node2.did()])?;
+    *node1.dht().lock_predecessor()? = Some(node2.did());
+    {
+        let dht = node1.dht();
+        let mut finger = dht.lock_finger()?;
+        finger.set(0, node2.did());
+        finger.set(3, node2.did());
+    }
+
+    let (entry, remote_placement) = entry_with_remote_repair_placement(&node1)?;
+    node1
+        .dht()
+        .storage
+        .put(&entry.did.to_string(), &entry)
+        .await?;
+
+    let _pending_send = PendingSendGuard::new();
+    node1.swarm.stabilizer().repair_storage().await?;
+
+    assert_no_more_msg([&node2]).await;
+    assert_eq!(
+        node2
+            .dht()
+            .storage
+            .get(&remote_placement.to_string())
+            .await?,
+        None
+    );
+    assert_eq!(
+        measure
+            .get_count(node2.did(), MeasureCounter::FailedToSend)
+            .await,
+        0
+    );
+
+    node1
+        .swarm
+        .stabilizer()
+        .clean_unavailable_connections()
+        .await?;
+
+    assert!(node1.swarm.transport.get_connection(node2.did()).is_some());
+    assert!(node1.dht().successors().contains(&node2.did())?);
+    assert_eq!(*node1.dht().lock_predecessor()?, Some(node2.did()));
+    assert!(node1.dht().lock_finger()?.contains(Some(node2.did())));
+    assert_eq!(
+        measure
+            .get_count(node2.did(), MeasureCounter::FailedToSend)
+            .await,
+        0
+    );
+    Ok(())
+}
+
 #[tokio::test]
 async fn test_stabilization() -> Result<()> {
     let mut key1 = SecretKey::random();
diff --git a/crates/node/bin/rings.rs b/crates/node/bin/rings.rs
index 876e82cde..1d8d6c823 100644
--- a/crates/node/bin/rings.rs
+++ b/crates/node/bin/rings.rs
@@ -223,7 +223,7 @@ struct RunCommand {
 
     #[arg(
         long,
-        help = "Stabilization interval in seconds. If not provided, use stabilize_interval in config file or 3",
+        help = "Stabilization interval in seconds. If not provided, use stabilize_interval in config file or 15",
         env
     )]
     pub stabilize_interval: Option,
diff --git a/crates/node/src/error.rs b/crates/node/src/error.rs
index ffaffaea9..dbf517e52 100644
--- a/crates/node/src/error.rs
+++ b/crates/node/src/error.rs
@@ -152,6 +152,14 @@ pub enum Error {
         /// Deadline used for this registration attempt.
         timeout: std::time::Duration,
     } = 813,
+    /// Opening browser IndexedDB-backed provider storage failed.
+    #[error("Open browser storage \"{name}\" failed: {source}")]
+    BrowserStorageOpen {
+        /// IndexedDB database and object-store name requested by the browser provider.
+        name: String,
+        /// Storage backend error returned while opening the database.
+        source: rings_core::error::Error,
+    } = 814,
     /// Creating a file on disk failed.
     #[error("Create File Error: {0}")]
     CreateFileError(String) = 900,
diff --git a/crates/node/src/native/config.rs b/crates/node/src/native/config.rs
index 1ab4a8746..6702c0e74 100644
--- a/crates/node/src/native/config.rs
+++ b/crates/node/src/native/config.rs
@@ -43,13 +43,15 @@ pub const DEFAULT_ENDPOINT_URL: &str = "http://127.0.0.1:50000";
 /// Default WebRTC ICE server list.
 pub const DEFAULT_ICE_SERVERS: &str = "stun://stun.l.google.com:19302";
 /// Default Chord stabilization interval in seconds.
-pub const DEFAULT_STABILIZE_INTERVAL: u64 = 3;
+pub const DEFAULT_STABILIZE_INTERVAL: u64 = 15;
 /// Default storage capacity in bytes for native storage backends.
 pub const DEFAULT_STORAGE_CAPACITY: u32 = 200000000;
 
 /// Builds the default storage path under the user home directory.
 pub fn get_storage_location
(prefix: P, path: P) -> String
-where P: AsRef {
+where
+    P: AsRef,
+{
     let home_dir = env::var_os("HOME").map(PathBuf::from);
     let storage_path = match home_dir {
         Some(dir) => dir.join(prefix).join(path),
@@ -217,7 +219,9 @@ impl TryFrom for ProcessorConfig {
 impl Config {
     /// Creates a default native-node configuration using the supplied session key path.
     pub fn new
(session_sk: P) -> Self
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let session_sk = session_sk.as_ref().to_string_lossy().to_string();
         Self {
             network_id: DEFAULT_NETWORK_ID,
@@ -260,7 +264,9 @@ impl Config {
 
     /// Writes this configuration to a YAML file and returns the written path.
     pub fn write_fs
(&self, path: P) -> Result
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let path = expand_home(path)?;
         ensure_parent_dir(&path)?;
         let f =
@@ -274,7 +280,9 @@ impl Config {
 
     /// Reads a native-node configuration from a YAML file.
     pub fn read_fs
(path: P) -> Result
-    where P: AsRef {
+    where
+        P: AsRef,
+    {
         let path = expand_home(path)?;
         tracing::debug!("Read config from: {:?}", path);
         let f = fs::File::open(path).map_err(|e| Error::OpenFileError(e.to_string()))?;
@@ -327,7 +335,7 @@ internal_api_port: 50000
 external_api_addr: 127.0.0.1:50001
 endpoint_url: http://127.0.0.1:50000
 ice_servers: stun://stun.l.google.com:19302
-stabilize_interval: 3
+stabilize_interval: 15
 external_ip: null
 webrtc_udp_port_min: null
 webrtc_udp_port_max: null
@@ -374,7 +382,7 @@ internal_api_port: 50000
 external_api_addr: 127.0.0.1:50001
 endpoint_url: http://127.0.0.1:50000
 ice_servers: stun://stun.l.google.com:19302
-stabilize_interval: 3
+stabilize_interval: 15
 dht_virtual_nodes: 0
 external_ip: null
 webrtc_udp_port_min: null
diff --git a/crates/node/src/onion/circuit/shell.rs b/crates/node/src/onion/circuit/shell.rs
index 65d985cdf..3dc14ebb8 100644
--- a/crates/node/src/onion/circuit/shell.rs
+++ b/crates/node/src/onion/circuit/shell.rs
@@ -113,7 +113,8 @@ impl OnionCircuitShell {
     async_trait::async_trait
 )]
 impl Interpret for OnionCircuitShell
-where H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static
+where
+    H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static,
 {
     type Effect = OnionCircuitEffect;
 
@@ -143,14 +144,17 @@ where H: OnionCircuitHandler + crate::extension::ext::MaybeSend + 'static
                 payload,
             } => {
                 self.handler
-                    .handle_exit(scope, OnionCircuitExitFrame {
-                        from,
-                        circuit_id,
-                        return_peer,
-                        client,
-                        forward_nonce,
-                        payload,
-                    })
+                    .handle_exit(
+                        scope,
+                        OnionCircuitExitFrame {
+                            from,
+                            circuit_id,
+                            return_peer,
+                            client,
+                            forward_nonce,
+                            payload,
+                        },
+                    )
                     .await?;
                 Ok(Vec::new())
             }
diff --git a/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs b/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
index f7494c1e6..a18a45cb5 100644
--- a/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
+++ b/crates/node/src/onion/circuit/tests/test_circuit_protocol.rs
@@ -424,17 +424,20 @@ fn expired_exit_layer_emits_no_exit_effect() {
     let state = OnionCircuitState::default();
     let circuit_id = OnionCircuitId::new([8; 16]);
 
-    let transition = reducer.apply(&state, OnionCircuitInput::ForwardReady {
-        from: client.account_did(),
-        received_at_ms: 100,
-        circuit_id,
-        layer: OnionForwardLayer::Exit {
-            client: OnionClientReturn::new(client.session_public_key()),
-            expires_at_ms: 100,
-            forward_nonce: OnionForwardNonce::new([9; 16]),
-            payload: test_payload("expired"),
+    let transition = reducer.apply(
+        &state,
+        OnionCircuitInput::ForwardReady {
+            from: client.account_did(),
+            received_at_ms: 100,
+            circuit_id,
+            layer: OnionForwardLayer::Exit {
+                client: OnionClientReturn::new(client.session_public_key()),
+                expires_at_ms: 100,
+                forward_nonce: OnionForwardNonce::new([9; 16]),
+                payload: test_payload("expired"),
+            },
         },
-    });
+    );
 
     assert_eq!(transition.state, state);
     assert!(transition.effects.is_empty());
diff --git a/crates/node/src/onion/https/mod.rs b/crates/node/src/onion/https/mod.rs
index 277df809d..766e8e419 100644
--- a/crates/node/src/onion/https/mod.rs
+++ b/crates/node/src/onion/https/mod.rs
@@ -224,12 +224,15 @@ impl OnionHttpsRuntime {
                 continue;
             }
             let (sender, receiver) = oneshot::channel();
-            pending.insert(id, PendingRequest {
-                expected_return_peer,
-                expected_exit,
-                return_id,
-                sender,
-            });
+            pending.insert(
+                id,
+                PendingRequest {
+                    expected_return_peer,
+                    expected_exit,
+                    return_id,
+                    sender,
+                },
+            );
             return Ok((id, receiver));
         }
         Err(Error::OnionRouteError(
diff --git a/crates/node/src/onion/https/tests/test_https_proxy.rs b/crates/node/src/onion/https/tests/test_https_proxy.rs
index e8beece2a..af93ce518 100644
--- a/crates/node/src/onion/https/tests/test_https_proxy.rs
+++ b/crates/node/src/onion/https/tests/test_https_proxy.rs
@@ -76,13 +76,16 @@ fn normalizes_empty_request_defaults() {
     let target = OnionProxyTarget::parse_authority("Example.COM:443").unwrap();
     let wire = client_request_with_default_path(&target, request, default_path().as_str()).unwrap();
 
-    assert_eq!(wire, OnionHttpsRequest {
-        target: "example.com:443".to_string(),
-        method: "GET".to_string(),
-        path: "/".to_string(),
-        headers: Vec::new(),
-        body: Vec::new(),
-    });
+    assert_eq!(
+        wire,
+        OnionHttpsRequest {
+            target: "example.com:443".to_string(),
+            method: "GET".to_string(),
+            path: "/".to_string(),
+            headers: Vec::new(),
+            body: Vec::new(),
+        }
+    );
 }
 
 #[test]
diff --git a/crates/node/src/onion/mod.rs b/crates/node/src/onion/mod.rs
index 9cf69869a..3ca4ddda0 100644
--- a/crates/node/src/onion/mod.rs
+++ b/crates/node/src/onion/mod.rs
@@ -822,7 +822,13 @@ impl OnionExitRegistration {
             .iter()
             .map(|descriptor| descriptor.encode().map_err(Error::CoreError))
             .collect::>>()?;
-        self.publisher.publish_many(context, encoded).await?;
+        self.publisher
+            .publish_many_replacing(context, encoded, |observed| {
+                observed
+                    .decode::()
+                    .is_ok_and(|descriptor| descriptor.did == context.did())
+            })
+            .await?;
         Ok(descriptors)
     }
 
diff --git a/crates/node/src/onion/replay.rs b/crates/node/src/onion/replay.rs
index 541151398..ba0b1e2fc 100644
--- a/crates/node/src/onion/replay.rs
+++ b/crates/node/src/onion/replay.rs
@@ -76,7 +76,8 @@ impl Default for OnionReplayCache {
 }
 
 impl OnionReplayCache
-where K: Eq + Hash
+where
+    K: Eq + Hash,
 {
     #[cfg(test)]
     fn with_limits(max_entries: usize, ttl_ms: u128) -> Self {
diff --git a/crates/node/src/onion/route/tests/test_route_selection.rs b/crates/node/src/onion/route/tests/test_route_selection.rs
index 815ffc3d6..37f292d00 100644
--- a/crates/node/src/onion/route/tests/test_route_selection.rs
+++ b/crates/node/src/onion/route/tests/test_route_selection.rs
@@ -80,9 +80,12 @@ fn online_node_at(
     heartbeat_at_ms: u128,
     expires_at_ms: u128,
 ) -> CoreResult {
-    online_node_at_with_capabilities(session_sk, heartbeat_at_ms, expires_at_ms, vec![
-        ONION_RELAY_CAPABILITY.to_string(),
-    ])
+    online_node_at_with_capabilities(
+        session_sk,
+        heartbeat_at_ms,
+        expires_at_ms,
+        vec![ONION_RELAY_CAPABILITY.to_string()],
+    )
 }
 
 fn online_node_at_with_capabilities(
@@ -240,12 +243,14 @@ fn directory_candidates_reject_foreign_network_descriptors() -> Result<()> {
         test_dht_protocol(),
         50,
         route_request("web", 1, false)?.service_name(),
-        vec![
-            online_node_at_with_network_and_capabilities(&relay, 2, 20, 100, vec![
-                ONION_RELAY_CAPABILITY.to_string(),
-            ])
-            .map_err(Error::CoreError)?,
-        ],
+        vec![online_node_at_with_network_and_capabilities(
+            &relay,
+            2,
+            20,
+            100,
+            vec![ONION_RELAY_CAPABILITY.to_string()],
+        )
+        .map_err(Error::CoreError)?],
         vec![exit],
     );
 
diff --git a/crates/node/src/onion/tcp/mod.rs b/crates/node/src/onion/tcp/mod.rs
index 84b994728..63eac1e9c 100644
--- a/crates/node/src/onion/tcp/mod.rs
+++ b/crates/node/src/onion/tcp/mod.rs
@@ -130,11 +130,14 @@ impl NativeOnionCircuitHandle {
         let handler_session_sk = session_sk.clone();
         extensions.register(
             OnionCircuitProtocol::new(capabilities),
-            OnionCircuitShell::new(session_sk, NativeOnionCircuitHandler {
-                runtime: runtime.clone(),
-                https,
-                session_sk: handler_session_sk,
-            }),
+            OnionCircuitShell::new(
+                session_sk,
+                NativeOnionCircuitHandler {
+                    runtime: runtime.clone(),
+                    https,
+                    session_sk: handler_session_sk,
+                },
+            ),
         )?;
         Ok(Self {
             runtime,
@@ -273,9 +276,12 @@ impl OnionTcpRuntime {
                 return Err(error);
             }
         };
-        let open_payload = match encode_tcp_payload(&service, OnionTcpPayload::Open {
-            target: target.authority(),
-        }) {
+        let open_payload = match encode_tcp_payload(
+            &service,
+            OnionTcpPayload::Open {
+                target: target.authority(),
+            },
+        ) {
             Ok(payload) => payload,
             Err(error) => {
                 self.remove_client_stream(key);
diff --git a/crates/node/src/onion/tests/test_exit_registry.rs b/crates/node/src/onion/tests/test_exit_registry.rs
index 76addbf12..f055fa14c 100644
--- a/crates/node/src/onion/tests/test_exit_registry.rs
+++ b/crates/node/src/onion/tests/test_exit_registry.rs
@@ -59,10 +59,10 @@ fn signed_exit_for_session_at(
 
 #[test]
 fn default_exit_services_include_native_tcp_and_https() {
-    assert_eq!(default_onion_exit_services(), vec![
-        OnionExitService::tcp(),
-        OnionExitService::https()
-    ]);
+    assert_eq!(
+        default_onion_exit_services(),
+        vec![OnionExitService::tcp(), OnionExitService::https()]
+    );
     assert_eq!(https_onion_exit_services(), vec![OnionExitService::https()]);
 }
 
@@ -143,9 +143,10 @@ fn exit_policy_allow_list_controls_targets() -> Result<()> {
 
 #[test]
 fn exit_policy_wildcard_allows_all_targets_with_specific_denies() -> Result<()> {
-    let policy = OnionExitPolicy::from_target_strings(vec!["*:*".to_string()], vec![
-        "api.example.com:443".to_string(),
-    ])?;
+    let policy = OnionExitPolicy::from_target_strings(
+        vec!["*:*".to_string()],
+        vec!["api.example.com:443".to_string()],
+    )?;
     let google = OnionExitTarget::parse("google.com:443")?;
     let example = OnionExitTarget::parse("example.com:8443")?;
     let api = OnionExitTarget::parse("api.example.com:443")?;
diff --git a/crates/node/src/processor/builder.rs b/crates/node/src/processor/builder.rs
index 5a15227be..33b486ab6 100644
--- a/crates/node/src/processor/builder.rs
+++ b/crates/node/src/processor/builder.rs
@@ -142,7 +142,9 @@ impl ProcessorBuilder {
 
     /// Add a custom periodic registration task.
     pub fn registration_task(mut self, task: T) -> Self
-    where T: RegistrationTask + 'static {
+    where
+        T: RegistrationTask + 'static,
+    {
         self.registration_tasks.push(Arc::new(task));
         self
     }
diff --git a/crates/node/src/processor/config.rs b/crates/node/src/processor/config.rs
index dcea574b7..629d4896f 100644
--- a/crates/node/src/processor/config.rs
+++ b/crates/node/src/processor/config.rs
@@ -495,7 +495,9 @@ impl Serialize for ProcessorConfig {
 
 impl<'de> serde::de::Deserialize<'de> for ProcessorConfig {
     fn deserialize(deserializer: D) -> core::result::Result
-    where D: serde::Deserializer<'de> {
+    where
+        D: serde::Deserializer<'de>,
+    {
         match ProcessorConfigSerialized::deserialize(deserializer) {
             Ok(ins) => {
                 let cfg: ProcessorConfig = ins
diff --git a/crates/node/src/processor/mod.rs b/crates/node/src/processor/mod.rs
index 5c6268385..08fcb3c0f 100644
--- a/crates/node/src/processor/mod.rs
+++ b/crates/node/src/processor/mod.rs
@@ -255,7 +255,7 @@ impl Processor {
         Ok(self.select_onion_exits_from_entry(&refreshed_entry, service, include_expired))
     }
 
-    async fn fetch_storage_entry(&self, entry_key: Did) -> Result> {
+    pub(crate) async fn fetch_storage_entry(&self, entry_key: Did) -> Result> {
         self.storage_fetch(entry_key).await?;
         for attempt in 0..DHT_LOOKUP_CACHE_POLL_ATTEMPTS {
             if let Some(entry) = self.storage_check_cache(entry_key).await {
diff --git a/crates/node/src/processor/tests/test_config.rs b/crates/node/src/processor/tests/test_config.rs
index 5e483eeb5..00f93fb30 100644
--- a/crates/node/src/processor/tests/test_config.rs
+++ b/crates/node/src/processor/tests/test_config.rs
@@ -160,7 +160,7 @@ external_address: null
 webrtc_udp_port_min: null
 webrtc_udp_port_max: null
 session_sk: "{}"
-stabilize_interval: 3
+stabilize_interval: 15
 online_node_heartbeat_interval_secs: 30
 online_node_ttl_secs: 60
 online_node_type: Native
@@ -300,10 +300,10 @@ fn default_onion_exit_config_uses_native_tcp_backed_services() {
 
     assert!(config.advertise_onion_exit);
     assert_eq!(config.onion_exit_services, default_onion_exit_services());
-    assert_eq!(config.onion_exit_services, vec![
-        OnionExitService::tcp(),
-        OnionExitService::https()
-    ]);
+    assert_eq!(
+        config.onion_exit_services,
+        vec![OnionExitService::tcp(), OnionExitService::https()]
+    );
 }
 
 #[test]
diff --git a/crates/node/src/processor/tests/test_network.rs b/crates/node/src/processor/tests/test_network.rs
index e4eaa039e..1621938ee 100644
--- a/crates/node/src/processor/tests/test_network.rs
+++ b/crates/node/src/processor/tests/test_network.rs
@@ -229,9 +229,12 @@ async fn provider_exposes_sent_and_received_peer_measurements() {
     assert!(provider_measurement.evidence.sent >= 1);
 
     let rpc_value = provider
-        .request(Method::PeerMeasurement, PeerMeasurementRequest {
-            did: p2.did().to_string(),
-        })
+        .request(
+            Method::PeerMeasurement,
+            PeerMeasurementRequest {
+                did: p2.did().to_string(),
+            },
+        )
         .await
         .unwrap();
     let rpc_measurement: PeerMeasurementResponse = serde_json::from_value(rpc_value).unwrap();
diff --git a/crates/node/src/processor/tests/test_registry.rs b/crates/node/src/processor/tests/test_registry.rs
index 97891a9a7..92f4615de 100644
--- a/crates/node/src/processor/tests/test_registry.rs
+++ b/crates/node/src/processor/tests/test_registry.rs
@@ -155,6 +155,125 @@ async fn online_node_concurrent_publish_keeps_one_self_record() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn online_node_publish_replaces_observed_self_records() -> Result<()> {
+    let processor = prepare_processor().await;
+    let other = prepare_processor().await;
+    let now_ms = get_epoch_ms();
+    let stale_self = processor.online_node_descriptor_at(now_ms.saturating_sub(30_000))?;
+    let other_descriptor = other.online_node_descriptor_at(now_ms)?;
+
+    processor
+        .storage_store(Processor::online_node_registry_entry(vec![
+            stale_self,
+            other_descriptor.clone(),
+        ])?)
+        .await?;
+
+    let published = processor.publish_online_node_descriptor().await?;
+    let entry_key = entry::Entry::gen_did(ONLINE_NODES_TOPIC)?;
+    processor.storage_fetch(entry_key).await?;
+    let entry = processor
+        .storage_check_cache(entry_key)
+        .await
+        .expect("online node registry entry should be cached after publish");
+    let stored = Processor::online_node_descriptors_from_entry(&entry);
+
+    assert_eq!(stored.len(), 2);
+    assert_eq!(
+        stored
+            .iter()
+            .filter(|descriptor| descriptor.did == processor.did())
+            .count(),
+        1
+    );
+    assert!(stored.iter().any(|descriptor| descriptor == &published));
+    assert!(stored
+        .iter()
+        .any(|descriptor| descriptor == &other_descriptor));
+    Ok(())
+}
+
+#[tokio::test]
+async fn onion_exit_publish_replaces_observed_self_records() -> Result<()> {
+    let processor = prepare_processor().await;
+    let other = prepare_processor().await;
+    let now_ms = get_epoch_ms();
+    let mut policy = onion_policy(&["example.com:443"], &[])?;
+    policy.max_circuits = 8;
+    policy.max_streams_per_circuit = 2;
+    policy.max_bytes_per_minute = 4096;
+    let stale_tcp = onion_exit_descriptor_for_processor_with_service(
+        &processor,
+        OnionExitService::tcp(),
+        now_ms.saturating_sub(30_000),
+        policy.clone(),
+    )?;
+    let stale_https = onion_exit_descriptor_for_processor_with_service(
+        &processor,
+        OnionExitService::https(),
+        now_ms.saturating_sub(20_000),
+        policy.clone(),
+    )?;
+    let stale_api = onion_exit_descriptor_for_processor_with_service(
+        &processor,
+        OnionExitService::new("api", OnionExitTransport::Tcp)?,
+        now_ms.saturating_sub(10_000),
+        policy.clone(),
+    )?;
+    let other_https = onion_exit_descriptor_for_processor_with_service(
+        &other,
+        OnionExitService::https(),
+        now_ms,
+        policy.clone(),
+    )?;
+
+    processor
+        .storage_store(Processor::onion_exit_registry_entry(vec![
+            stale_tcp,
+            stale_https,
+            stale_api,
+            other_https.clone(),
+        ])?)
+        .await?;
+
+    let registration = OnionExitRegistration::new(
+        Duration::from_secs(30),
+        Duration::from_secs(90),
+        default_online_node_type(),
+        vec![OnionExitService::https()],
+        policy,
+    );
+    let published = registration
+        .publish_descriptors(&processor.registration_context())
+        .await?;
+    let published_descriptor = published
+        .into_iter()
+        .next()
+        .ok_or_else(|| Error::InvalidConfig("expected one onion-exit descriptor".to_string()))?;
+    let entry_key = entry::Entry::gen_did(ONION_EXITS_TOPIC)?;
+    processor.storage_fetch(entry_key).await?;
+    let entry = processor
+        .storage_check_cache(entry_key)
+        .await
+        .expect("onion exit registry entry should be cached after publish");
+    let stored = Processor::onion_exit_descriptors_from_entry(&entry);
+
+    assert_eq!(stored.len(), 2);
+    assert_eq!(
+        stored
+            .iter()
+            .filter(|descriptor| descriptor.did == processor.did())
+            .count(),
+        1
+    );
+    assert!(stored
+        .iter()
+        .any(|descriptor| descriptor == &published_descriptor));
+    assert!(stored.iter().any(|descriptor| descriptor == &other_https));
+    Ok(())
+}
+
 #[tokio::test]
 async fn online_node_lookup_filters_expired_descriptors_by_default() -> Result<()> {
     let processor = prepare_processor().await;
diff --git a/crates/node/src/provider/browser/provider.rs b/crates/node/src/provider/browser/provider.rs
index b79a1526d..1acf2f1dc 100644
--- a/crates/node/src/provider/browser/provider.rs
+++ b/crates/node/src/provider/browser/provider.rs
@@ -12,6 +12,7 @@ use futures::FutureExt;
 use js_sys;
 use js_sys::Uint8Array;
 use rings_core::dht::Did;
+use rings_core::dht::EntryStorage;
 use rings_core::ecc::PublicKey;
 use rings_core::lifecycle::StopSource;
 use rings_core::measure::PeerQuality;
@@ -32,6 +33,7 @@ use wasm_bindgen_futures::JsFuture;
 
 use crate::error::Error;
 use crate::error::Result as NodeResult;
+use crate::measure::MeasureStorage;
 use crate::measure::peer_quality_thresholds;
 use crate::onion::circuit::encode_initial_forward;
 use crate::onion::circuit::route_first_hop;
@@ -416,6 +418,73 @@ fn wrapped_signer(signer: js_sys::Function) -> AsyncSigner {
     )
 }
 
+async fn open_browser_entry_storage(storage_name: &str) -> NodeResult {
+    IdbStorage::new_with_cap_and_name(50000, storage_name)
+        .await
+        .map(|storage| Box::new(storage) as EntryStorage)
+        .map_err(|source| Error::BrowserStorageOpen {
+            name: storage_name.to_string(),
+            source,
+        })
+}
+
+async fn open_browser_entry_storage_or_memory(storage_name: &str) -> Option {
+    match open_browser_entry_storage(storage_name).await {
+        Ok(storage) => Some(storage),
+        Err(error) => {
+            tracing::warn!(
+                storage_name = %storage_name,
+                error = %error,
+                "browser entry IndexedDB unavailable; falling back to in-memory entry storage"
+            );
+            None
+        }
+    }
+}
+
+async fn open_browser_measure_storage(storage_name: &str) -> Option {
+    match IdbStorage::new_with_cap_and_name(50000, storage_name).await {
+        Ok(storage) => Some(Box::new(storage) as MeasureStorage),
+        Err(source) => {
+            tracing::warn!(
+                storage_name = %storage_name,
+                error = %source,
+                "browser measurement IndexedDB unavailable; falling back to in-memory measurement storage"
+            );
+            None
+        }
+    }
+}
+
+impl Provider {
+    /// Create a browser provider backed by IndexedDB storage and install its default backend.
+    ///
+    /// This is the Rust-side constructor for browser frontends. It keeps provider ownership as the
+    /// lifecycle boundary while reusing the same storage, backend, and onion-protocol setup as the
+    /// wasm-exported constructors.
+    pub async fn new_browser_provider_with_storage(
+        config: ProcessorConfig,
+        storage_name: String,
+    ) -> NodeResult {
+        let onion_https_exit_policy = config.onion_https_exit_policy();
+        let entry_storage = open_browser_entry_storage_or_memory(&storage_name).await;
+        let measure_storage =
+            open_browser_measure_storage(&format!("{storage_name}/measure")).await;
+
+        let provider = Self::new_provider_with_storage_internal(
+            config,
+            entry_storage,
+            measure_storage,
+        )
+        .await?;
+        provider.set_backend()?;
+        if let Some(policy) = onion_https_exit_policy {
+            provider.install_onion_https_protocol(Some(policy))?;
+        }
+        Ok(provider)
+    }
+}
+
 #[wasm_export]
 impl Provider {
     /// make provider as an As arc ref
@@ -448,17 +517,8 @@ impl Provider {
         future_to_promise(async move {
             let signer = wrapped_signer(signer);
 
-            let entry_storage = Box::new(
-                IdbStorage::new_with_cap_and_name(50000, "rings-node")
-                    .await
-                    .map_err(JsError::from)?,
-            );
-
-            let measure_storage = Box::new(
-                IdbStorage::new_with_cap_and_name(50000, "rings-node/measure")
-                    .await
-                    .map_err(JsError::from)?,
-            );
+            let entry_storage = open_browser_entry_storage_or_memory("rings-node").await;
+            let measure_storage = open_browser_measure_storage("rings-node/measure").await;
 
             let provider = Provider::new_provider_internal(
                 network_id,
@@ -467,8 +527,8 @@ impl Provider {
                 account,
                 account_type,
                 Signer::Async(Box::new(signer)),
-                Some(entry_storage),
-                Some(measure_storage),
+                entry_storage,
+                measure_storage,
             )
             .await?;
 
@@ -496,17 +556,8 @@ impl Provider {
                 .map_err(JsError::from)?;
             policy.validate_targets().map_err(JsError::from)?;
 
-            let entry_storage = Box::new(
-                IdbStorage::new_with_cap_and_name(50000, "rings-node")
-                    .await
-                    .map_err(JsError::from)?,
-            );
-
-            let measure_storage = Box::new(
-                IdbStorage::new_with_cap_and_name(50000, "rings-node/measure")
-                    .await
-                    .map_err(JsError::from)?,
-            );
+            let entry_storage = open_browser_entry_storage_or_memory("rings-node").await;
+            let measure_storage = open_browser_measure_storage("rings-node/measure").await;
 
             let config_policy = policy.clone();
             let provider = Provider::new_provider_internal_with_config(
@@ -516,8 +567,8 @@ impl Provider {
                 account,
                 account_type,
                 Signer::Async(Box::new(signer)),
-                Some(entry_storage),
-                Some(measure_storage),
+                entry_storage,
+                measure_storage,
                 move |config| {
                     config
                         .enable_https_onion_exit()
@@ -578,32 +629,9 @@ impl Provider {
         storage_name: String,
     ) -> js_sys::Promise {
         future_to_promise(async move {
-            let onion_https_exit_policy = config.onion_https_exit_policy();
-            let entry_storage = Box::new(
-                IdbStorage::new_with_cap_and_name(50000, &storage_name)
-                    .await
-                    .map_err(JsError::from)?,
-            );
-
-            let measure_storage = Box::new(
-                IdbStorage::new_with_cap_and_name(50000, &format!("{storage_name}/measure"))
-                    .await
-                    .map_err(JsError::from)?,
-            );
-
-            let provider = Self::new_provider_with_storage_internal(
-                config,
-                Some(entry_storage),
-                Some(measure_storage),
-            )
-            .await
-            .map_err(JsError::from)?;
-            provider.set_backend().map_err(JsError::from)?;
-            if let Some(policy) = onion_https_exit_policy {
-                provider
-                    .install_onion_https_protocol(Some(policy))
-                    .map_err(JsError::from)?;
-            }
+            let provider = Self::new_browser_provider_with_storage(config, storage_name)
+                .await
+                .map_err(JsError::from)?;
             Ok(JsValue::from(provider))
         })
     }
diff --git a/crates/node/src/registration.rs b/crates/node/src/registration.rs
index e5afa6170..da55aa2cf 100644
--- a/crates/node/src/registration.rs
+++ b/crates/node/src/registration.rs
@@ -14,6 +14,7 @@ use rings_core::dht::Did;
 use rings_core::ecc::VerificationPublicKey;
 use rings_core::message::Encoded;
 use rings_core::message::Encoder;
+use rings_core::prelude::entry;
 use rings_core::session::SessionSk;
 use rings_core::utils::get_epoch_ms;
 
@@ -179,10 +180,46 @@ impl DhtRegistrationPublisher {
         &self,
         context: &RegistrationContext<'_>,
         values: impl IntoIterator,
+    ) -> Result<()> {
+        self.publish_many_with_replacement(context, values, false, |_| false)
+            .await
+    }
+
+    /// Publish the current value set, tombstoning older observed values with the same registry key.
+    ///
+    /// Invariant: registry topics are keyed presence sets, not append-only heartbeat logs.
+    /// Preservation: every observed value replaced by the current publish is tombstoned after the
+    /// replacement value has been touched, while unrelated publisher keys stay joinable.
+    pub async fn publish_many_replacing(
+        &self,
+        context: &RegistrationContext<'_>,
+        values: impl IntoIterator,
+        replaces_observed_value: impl Fn(&Encoded) -> bool,
+    ) -> Result<()> {
+        self.publish_many_with_replacement(context, values, true, replaces_observed_value)
+            .await
+    }
+
+    async fn publish_many_with_replacement(
+        &self,
+        context: &RegistrationContext<'_>,
+        values: impl IntoIterator,
+        load_observed_values: bool,
+        replaces_observed_value: impl Fn(&Encoded) -> bool,
     ) -> Result<()> {
         let current_values = values.into_iter().collect::>();
         let mut published_values = self.published_values.lock().await;
-        let stale_values = begin_registration_publish(&mut published_values, ¤t_values);
+        let observed_values = if load_observed_values {
+            self.observed_registry_values(context).await?
+        } else {
+            vec![]
+        };
+        let stale_values = begin_registration_publish(
+            &mut published_values,
+            ¤t_values,
+            observed_values,
+            replaces_observed_value,
+        );
 
         for value in ¤t_values {
             context
@@ -200,22 +237,41 @@ impl DhtRegistrationPublisher {
         finish_registration_publish(&mut published_values, current_values);
         Ok(())
     }
+
+    async fn observed_registry_values(
+        &self,
+        context: &RegistrationContext<'_>,
+    ) -> Result> {
+        let entry_key = entry::Entry::gen_did(&self.topic)?;
+        let Some(entry) = context.processor.fetch_storage_entry(entry_key).await? else {
+            return Ok(vec![]);
+        };
+        Ok(entry.data)
+    }
 }
 
 fn begin_registration_publish(
     published_values: &mut BTreeSet,
     current_values: &BTreeSet,
+    observed_values: Vec,
+    replaces_observed_value: impl Fn(&Encoded) -> bool,
 ) -> Vec {
-    let stale_values = published_values
+    let mut stale_values = published_values
         .iter()
         .filter(|published| !current_values.contains(*published))
         .cloned()
-        .collect::>();
+        .collect::>();
+    stale_values.extend(
+        observed_values
+            .into_iter()
+            .filter(|observed| !current_values.contains(observed))
+            .filter(replaces_observed_value),
+    );
     // Invariant: every value whose touch may have reached storage is remembered
     // before the first await. If the publish future is later cancelled by an
     // attempt timeout, the next attempt can still tombstone the value.
     published_values.extend(current_values.iter().cloned());
-    stale_values
+    stale_values.into_iter().collect()
 }
 
 fn finish_registration_publish(
@@ -334,7 +390,13 @@ impl OnlineNodeRegistration {
         let now_ms = get_epoch_ms();
         let descriptor = self.descriptor_at(context, now_ms)?;
         let encoded = descriptor.encode().map_err(Error::CoreError)?;
-        self.publisher.publish(context, encoded).await?;
+        self.publisher
+            .publish_many_replacing(context, std::iter::once(encoded), |observed| {
+                observed
+                    .decode::()
+                    .is_ok_and(|descriptor| descriptor.did == context.did())
+            })
+            .await?;
         Ok(descriptor)
     }
 
@@ -394,7 +456,7 @@ mod tests {
         let current = BTreeSet::from([attempted.clone()]);
         let mut known = BTreeSet::from([old.clone()]);
 
-        let stale = begin_registration_publish(&mut known, ¤t);
+        let stale = begin_registration_publish(&mut known, ¤t, vec![], |_| false);
 
         assert_eq!(stale, vec![old.clone()]);
         assert_eq!(known, BTreeSet::from([old, attempted]));
@@ -408,9 +470,9 @@ mod tests {
         let mut known = BTreeSet::from([old.clone()]);
 
         let cancelled_current = BTreeSet::from([cancelled.clone()]);
-        let _ = begin_registration_publish(&mut known, &cancelled_current);
+        let _ = begin_registration_publish(&mut known, &cancelled_current, vec![], |_| false);
         let replacement_current = BTreeSet::from([replacement.clone()]);
-        let stale = begin_registration_publish(&mut known, &replacement_current);
+        let stale = begin_registration_publish(&mut known, &replacement_current, vec![], |_| false);
 
         assert_eq!(
             stale.into_iter().collect::>(),
@@ -431,13 +493,14 @@ mod tests {
                     let replacement = encoded_subset(replacement_mask);
                     let mut known = old.clone();
 
-                    let _ = begin_registration_publish(&mut known, ¤t);
+                    let _ = begin_registration_publish(&mut known, ¤t, vec![], |_| false);
                     let attempted = old.union(¤t).cloned().collect::>();
                     assert_eq!(known, attempted);
 
-                    let stale = begin_registration_publish(&mut known, &replacement)
-                        .into_iter()
-                        .collect::>();
+                    let stale =
+                        begin_registration_publish(&mut known, &replacement, vec![], |_| false)
+                            .into_iter()
+                            .collect::>();
                     let expected_stale = attempted
                         .difference(&replacement)
                         .cloned()
@@ -450,4 +513,22 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn registration_publish_tombstones_matching_observed_values() {
+        let current = BTreeSet::from([encoded("self-new")]);
+        let observed_self_old = encoded("self-old");
+        let observed_other = encoded("other");
+        let mut known = BTreeSet::new();
+
+        let stale = begin_registration_publish(
+            &mut known,
+            ¤t,
+            vec![observed_self_old.clone(), observed_other],
+            |observed| observed == &observed_self_old,
+        );
+
+        assert_eq!(stale, vec![observed_self_old]);
+        assert_eq!(known, current);
+    }
 }
diff --git a/crates/webview/src/browser.rs b/crates/webview/src/browser.rs
index a06e66842..9deeaf867 100644
--- a/crates/webview/src/browser.rs
+++ b/crates/webview/src/browser.rs
@@ -15,6 +15,7 @@ pub fn bootstrap_script(gateway_prefix: &str, document_url: &Url) -> String {
   const prefix = {prefix:?};
   const targetBase = {target_base:?};
   const marker = "{marker}";
+  const controlledAssetPaths = new Set(["/assets/webview-overlay.js"]);
   const urlAttributes = new Set(["href", "src", "action", "poster", "data", "cite", "formaction", "manifest", "xlink:href"]);
   const srcsetAttributes = new Set(["srcset", "imagesrcset"]);
   const styleProxies = new WeakMap();
@@ -61,9 +62,23 @@ pub fn bootstrap_script(gateway_prefix: &str, document_url: &Url) -> String {
     const lower = String(value).trim().toLowerCase();
     return !lower || ["javascript:", "mailto:", "tel:", "data:", "blob:", "about:"].some((scheme) => lower.startsWith(scheme));
   }}
+  function controlledAssetPath(input) {{
+    const text = String(input);
+    const origin = globalThis.location?.origin;
+    if (!origin) return undefined;
+    try {{
+      const url = new URL(text, origin);
+      if (controlledAssetPaths.has(url.pathname)) {{
+        return `${{url.pathname}}${{url.search}}${{url.hash}}`;
+      }}
+    }} catch (_error) {{}}
+    return undefined;
+  }}
   function encodeTarget(input, base = resolveTargetBase()) {{
     const text = String(input);
     if (isUnrewritableTarget(text)) return text;
+    const controlled = controlledAssetPath(text);
+    if (controlled) return controlled;
     const gatewayPath = gatewayPathFromText(text);
     if (gatewayPath) return gatewayPath;
     const url = new URL(text, base);
@@ -520,6 +535,20 @@ pub fn bootstrap_script(gateway_prefix: &str, document_url: &Url) -> String {
     }};
   }}
   const nativeSetAttribute = globalThis.Element?.prototype?.setAttribute;
+  function loadLocalScript(path, markerAttribute) {{
+    const script = globalThis.document?.createElement?.("script");
+    if (!script) return false;
+    script.async = false;
+    if (nativeSetAttribute) {{
+      nativeSetAttribute.call(script, "src", path);
+      if (markerAttribute) nativeSetAttribute.call(script, markerAttribute, "");
+    }} else {{
+      script.src = path;
+      if (markerAttribute) script.setAttribute?.(markerAttribute, "");
+    }}
+    (globalThis.document?.head || globalThis.document?.documentElement)?.append?.(script);
+    return true;
+  }}
   if (nativeSetAttribute) {{
     globalThis.Element.prototype.setAttribute = function(name, value) {{
       const lower = String(name).toLowerCase();
@@ -592,6 +621,7 @@ pub fn bootstrap_script(gateway_prefix: &str, document_url: &Url) -> String {
   patchUrlProperty("HTMLEmbedElement", "src");
   patchUrlProperty("HTMLObjectElement", "data");
   gatewayState.prefix = prefix;
+  gatewayState.loadLocalScript = loadLocalScript;
 }})();"#,
         prefix = gateway_prefix,
         target_base = document_url.as_str(),
diff --git a/crates/webview/src/header.rs b/crates/webview/src/header.rs
index b9b4e9877..ed2e81dff 100644
--- a/crates/webview/src/header.rs
+++ b/crates/webview/src/header.rs
@@ -26,6 +26,10 @@ impl HeaderPolicy {
         request
             .headers
             .retain(|header| !should_strip_request_header(header.name.as_str()));
+        request.headers.push(GatewayHeader {
+            name: "Accept-Encoding".to_string(),
+            value: "identity".to_string(),
+        });
         if let Some(source_origin) = request.source_origin.as_ref() {
             request.headers.push(GatewayHeader {
                 name: "Origin".to_string(),
@@ -100,6 +104,8 @@ fn should_strip_request_header(name: &str) -> bool {
 fn should_strip_response_header(name: &str) -> bool {
     const STRIPPED: &[&str] = &[
         "connection",
+        "content-encoding",
+        "content-length",
         "keep-alive",
         "proxy-authenticate",
         "proxy-authorization",
@@ -151,6 +157,40 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn response_policy_strips_headers_invalidated_by_gateway_rewrites() -> Result<()> {
+        let target = Url::parse("https://example.com/app/page")?;
+        let policy = HeaderPolicy::new(GatewayPrefix::new("/webview/")?);
+        let response = GatewayResponse::new(
+            200,
+            vec![
+                GatewayHeader::new("Content-Encoding", "gzip")?,
+                GatewayHeader::new("Content-Length", "128")?,
+                GatewayHeader::new("Content-Type", "text/html")?,
+                GatewayHeader::new("X-Frame-Options", "DENY")?,
+            ],
+            Vec::new(),
+        )?;
+
+        let normalized = policy.normalize_response(&target, response)?;
+
+        assert!(normalized.headers.iter().all(|header| {
+            !matches!(
+                header.name.to_ascii_lowercase().as_str(),
+                "content-encoding" | "content-length" | "x-frame-options"
+            )
+        }));
+        assert!(normalized
+            .headers
+            .iter()
+            .any(|header| header.name_eq("content-type") && header.value == "text/html"));
+        assert!(normalized.headers.iter().any(|header| {
+            header.name_eq("content-security-policy")
+                && header.value == GATEWAY_CONTENT_SECURITY_POLICY
+        }));
+        Ok(())
+    }
+
     #[test]
     fn refresh_header_rewrites_to_gateway_url() -> Result<()> {
         let target = Url::parse("https://example.com/app/page")?;
@@ -190,6 +230,7 @@ mod tests {
                 GatewayHeader::new("Referer", "http://127.0.0.1:3000/webview/x")?,
                 GatewayHeader::new("Sec-Fetch-Dest", "document")?,
                 GatewayHeader::new("Cookie", "caller=leak")?,
+                GatewayHeader::new("Accept-Encoding", "gzip")?,
                 GatewayHeader::new("Accept", "text/html")?,
                 GatewayHeader::new("X-App-Trace", "kept")?,
             ],
@@ -209,6 +250,9 @@ mod tests {
             .headers
             .iter()
             .any(|header| header.name_eq("accept") && header.value == "text/html"));
+        assert!(normalized.headers.iter().any(|header| {
+            header.name_eq("accept-encoding") && header.value.eq_ignore_ascii_case("identity")
+        }));
         assert!(normalized
             .headers
             .iter()
diff --git a/crates/webview/tests/browser_gateway.rs b/crates/webview/tests/browser_gateway.rs
index a3d03e8b7..64d489503 100644
--- a/crates/webview/tests/browser_gateway.rs
+++ b/crates/webview/tests/browser_gateway.rs
@@ -332,7 +332,11 @@ fn playwright_browser_renders_gateway_fixture_without_direct_remote_requests() -
     let log = FixtureLog::default();
     let prefix = GatewayPrefix::new("/webview/")?;
     let target = TargetUrl::parse("https://example.test/docs/index.html")?;
-    let bootstrap = bootstrap_script(prefix.as_str(), target.as_url());
+    let bootstrap = format!(
+        "{}\n{}",
+        bootstrap_script(prefix.as_str(), target.as_url()),
+        fixture_overlay_loader()
+    );
     let gateway = WebviewGateway::new(prefix.clone(), BrowserFixtureTransport::new(log.clone()))
         .with_bootstrap_script(bootstrap);
     let server = BrowserFixtureServer::start(prefix.clone(), gateway)?;
@@ -593,11 +597,14 @@ const pageUrl = {page_url:?};
     const dynamicPing = document.querySelector("#dynamic-ping-link");
     const namespaceImage = document.querySelector("#namespace-image");
     const refreshFrame = document.querySelector("#refresh-navigation-srcdoc");
+    const overlayScript = document.querySelector("script[data-rings-webview-overlay-loader]");
     const backgroundImage = (selector) => {{
       const element = document.querySelector(selector);
       return element ? getComputedStyle(element).backgroundImage : "";
     }};
     return {{
+      overlayMounted: Boolean(document.querySelector("#rings-webview-debug-overlay")),
+      overlayScriptSrc: overlayScript?.src || "",
       titleText: title?.textContent,
       titleColor: title ? getComputedStyle(title).color : "",
       fetchText: document.querySelector("#fetch-result")?.textContent,
@@ -677,6 +684,9 @@ const pageUrl = {page_url:?};
   if (result.titleText !== "Rings WebView Fixture") {{
     throw new Error(`page title did not render: ${{JSON.stringify(result)}}`);
   }}
+  if (!result.overlayMounted || !result.overlayScriptSrc.endsWith("/assets/webview-overlay.js")) {{
+    throw new Error(`webview overlay did not mount from local asset: ${{JSON.stringify(result)}}`);
+  }}
   if (result.titleColor !== "rgb(1, 2, 3)") {{
     throw new Error(`stylesheet did not apply: ${{JSON.stringify(result)}}`);
   }}
@@ -743,6 +753,19 @@ const pageUrl = {page_url:?};
     Ok(())
 }
 
+fn fixture_overlay_loader() -> &'static str {
+    r#"
+(() => {
+  if (globalThis.__ringsWebviewGateway?.loadLocalScript?.("/assets/webview-overlay.js", "data-rings-webview-overlay-loader")) return;
+  const script = document.createElement("script");
+  script.src = "/assets/webview-overlay.js";
+  script.async = false;
+  script.dataset.ringsWebviewOverlayLoader = "";
+  (document.head || document.documentElement).append(script);
+})();
+"#
+}
+
 fn playwright_available() -> Result {
     let output = Command::new("node")
         .arg("-e")
diff --git a/crates/webview/tests/browser_gateway/fixture_server.rs b/crates/webview/tests/browser_gateway/fixture_server.rs
index cdbc06d9b..f20eb361e 100644
--- a/crates/webview/tests/browser_gateway/fixture_server.rs
+++ b/crates/webview/tests/browser_gateway/fixture_server.rs
@@ -95,6 +95,25 @@ fn handle_connection(
         .set_nonblocking(false)
         .map_err(|error| WebviewError::Transport(error.to_string()))?;
     let request = read_http_request(stream)?;
+    if request.path == "/assets/webview-overlay.js" {
+        return write_http_response(
+            stream,
+            &GatewayResponse::new(
+                200,
+                vec![GatewayHeader::new(
+                    "Content-Type",
+                    "application/javascript; charset=utf-8",
+                )?],
+                br#"
+globalThis.__ringsWebviewDebugOverlay = { installed: true };
+document.documentElement.appendChild(Object.assign(document.createElement("div"), {
+  id: "rings-webview-debug-overlay",
+}));
+"#
+                .to_vec(),
+            )?,
+        );
+    }
     if !request.path.starts_with(prefix.as_str()) {
         return write_http_response(
             stream,
diff --git a/docker/cluster/Dockerfile b/docker/cluster/Dockerfile
index b73ea14bf..e8a613f0b 100644
--- a/docker/cluster/Dockerfile
+++ b/docker/cluster/Dockerfile
@@ -31,14 +31,14 @@ ENV RINGS_ALLOW_RANDOM_KEYS=true \
     RINGS_CLUSTER_DIR=/var/lib/rings-cluster \
     RINGS_CONNECT_TOPOLOGY=ring \
     RINGS_ICE_SERVERS=stun://stun.l.google.com:19302 \
-    RINGS_LOG_LEVEL=info \
+    RINGS_LOG_LEVEL=warn \
     RINGS_NETWORK_ID=1 \
     RINGS_NODE_COUNT=3 \
     RINGS_READY_RETRIES=60 \
     RINGS_READY_SLEEP_SECONDS=1 \
     RINGS_RUNTIME=current-thread \
     RINGS_SESSION_TTL_SECONDS=2592000 \
-    RINGS_STABILIZE_INTERVAL=3
+    RINGS_STABILIZE_INTERVAL=15
 
 EXPOSE 51000-51018/tcp
 
diff --git a/docker/cluster/README.md b/docker/cluster/README.md
index 2a41c36fe..39dd75d38 100644
--- a/docker/cluster/README.md
+++ b/docker/cluster/README.md
@@ -63,6 +63,7 @@ Useful environment variables:
 - `RINGS_CLUSTER_DIR`: config, logs, storage, and session key directory; default `/var/lib/rings-cluster`
 - `RINGS_ICE_SERVERS`: ICE server list passed to every node; set it to an empty string to run without ICE servers
 - `RINGS_RUNTIME`: Tokio runtime flavor for each node process; default `current-thread`
+- `RINGS_LOG_LEVEL`: node log level; default `warn`
 - `RINGS_EXTERNAL_IP`: optional native WebRTC NAT 1:1 IP advertised in ICE host candidates; default unset. For browser testing from the Docker host, use `127.0.0.1`.
 - `RINGS_EXTERNAL_IP_APPEND_CONTAINER_IP`: when `RINGS_EXTERNAL_IP` is set, also advertise the container IP so nodes inside the same container can still connect to each other; default `true`
 - `RINGS_WEBRTC_UDP_PORT_MIN` and `RINGS_WEBRTC_UDP_PORT_MAX`: optional fixed native WebRTC UDP port range; publish the same range with `/udp` when browser peers must establish data channels to non-ingress nodes
diff --git a/docker/cluster/rings-cluster-entrypoint.sh b/docker/cluster/rings-cluster-entrypoint.sh
index e24954ce3..8ad1ee5be 100644
--- a/docker/cluster/rings-cluster-entrypoint.sh
+++ b/docker/cluster/rings-cluster-entrypoint.sh
@@ -15,11 +15,11 @@ if [[ -v RINGS_ICE_SERVERS ]]; then
 else
     ICE_SERVERS="stun://stun.l.google.com:19302"
 fi
-STABILIZE_INTERVAL="${RINGS_STABILIZE_INTERVAL:-3}"
+STABILIZE_INTERVAL="${RINGS_STABILIZE_INTERVAL:-15}"
 SESSION_TTL_SECONDS="${RINGS_SESSION_TTL_SECONDS:-2592000}"
 READY_RETRIES="${RINGS_READY_RETRIES:-60}"
 READY_SLEEP_SECONDS="${RINGS_READY_SLEEP_SECONDS:-1}"
-LOG_LEVEL="${RINGS_LOG_LEVEL:-info}"
+LOG_LEVEL="${RINGS_LOG_LEVEL:-warn}"
 RUNTIME="${RINGS_RUNTIME:-current-thread}"
 EXTERNAL_IP="${RINGS_EXTERNAL_IP:-}"
 APPEND_CONTAINER_EXTERNAL_IP="${RINGS_EXTERNAL_IP_APPEND_CONTAINER_IP:-true}"
diff --git a/frontend/Cargo.lock b/frontend/Cargo.lock
index f57dd3477..7c179bc1d 100644
--- a/frontend/Cargo.lock
+++ b/frontend/Cargo.lock
@@ -4264,7 +4264,7 @@ dependencies = [
 
 [[package]]
 name = "rings-core"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "ark-bls12-381",
  "ark-ec",
@@ -4326,7 +4326,7 @@ dependencies = [
 
 [[package]]
 name = "rings-derive"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -4336,7 +4336,7 @@ dependencies = [
 
 [[package]]
 name = "rings-frontend"
-version = "0.1.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "base58",
@@ -4358,7 +4358,7 @@ dependencies = [
 
 [[package]]
 name = "rings-node"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "anyhow",
  "arrayref",
@@ -4404,7 +4404,7 @@ dependencies = [
 
 [[package]]
 name = "rings-rpc"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "base64 0.13.1",
@@ -4420,7 +4420,7 @@ dependencies = [
 
 [[package]]
 name = "rings-snark"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "bellpepper-core",
  "byteorder",
@@ -4447,7 +4447,7 @@ dependencies = [
 
 [[package]]
 name = "rings-transport"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "bincode",
@@ -4469,7 +4469,7 @@ dependencies = [
 
 [[package]]
 name = "rings-webview"
-version = "0.14.0"
+version = "1.0.0"
 dependencies = [
  "async-trait",
  "js-sys",
diff --git a/frontend/Cargo.toml b/frontend/Cargo.toml
index 6feea96b0..f68720e40 100644
--- a/frontend/Cargo.toml
+++ b/frontend/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "rings-frontend"
-version = "0.1.0"
+version = "1.0.0"
 edition = "2021"
 license = "GPL-3.0"
 publish = false
diff --git a/frontend/assets/webview-host.js b/frontend/assets/webview-host.js
index 83ea231fa..59666f399 100644
--- a/frontend/assets/webview-host.js
+++ b/frontend/assets/webview-host.js
@@ -1,7 +1,7 @@
 (() => {
   "use strict";
 
-  const workerUrl = "/rings-webview-service-worker.js?gateway-host-protocol=3";
+  const workerUrl = "/rings-webview-service-worker.js?gateway-host-protocol=4";
   let registrationPromise;
   const debugEntries = [];
 
diff --git a/frontend/assets/webview-overlay.js b/frontend/assets/webview-overlay.js
index 232f0dbf1..830419a98 100644
--- a/frontend/assets/webview-overlay.js
+++ b/frontend/assets/webview-overlay.js
@@ -13,11 +13,15 @@
     network: undefined,
     onion: undefined,
     panel: undefined,
+    addressForm: undefined,
+    loadingTrack: undefined,
     view: "log",
     levelFilter: "all",
     textFilter: "",
+    loading: false,
     originalBodyPaddingTop: undefined,
     originalBodyPaddingBottom: undefined,
+    bodySpacingScheduled: false,
   };
 
   function isWebviewContext() {
@@ -184,6 +188,26 @@
     container.scrollTop = container.scrollHeight;
   }
 
+  function setLoading(loading) {
+    state.loading = Boolean(loading);
+    if (!state.addressForm) return;
+    state.addressForm.dataset.loading = String(state.loading);
+    state.addressForm.setAttribute("aria-busy", String(state.loading));
+    if (state.loadingTrack) state.loadingTrack.hidden = !state.loading;
+  }
+
+  function syncDocumentLoading() {
+    if (document.readyState === "complete") {
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    globalThis.addEventListener("load", () => setLoading(false), { once: true });
+    globalThis.addEventListener("pageshow", () => {
+      if (document.readyState === "complete") setLoading(false);
+    }, { once: true });
+  }
+
   function record(scope, message, level = "info", resource = undefined, onion = undefined, at = undefined) {
     const entry = { at: at || new Date().toISOString(), scope, message, level };
     if (resource) entry.resource = resource;
@@ -260,7 +284,10 @@
   }
 
   function applyBodySpacing() {
-    if (!document.body) return;
+    if (!document.body) {
+      scheduleBodySpacing();
+      return;
+    }
     if (state.originalBodyPaddingTop === undefined) {
       state.originalBodyPaddingTop = getComputedStyle(document.body).paddingTop || "0px";
       state.originalBodyPaddingBottom = getComputedStyle(document.body).paddingBottom || "0px";
@@ -275,6 +302,29 @@
     }
   }
 
+  function scheduleBodySpacing() {
+    if (state.bodySpacingScheduled || document.body) return;
+    state.bodySpacingScheduled = true;
+    const retry = () => {
+      state.bodySpacingScheduled = false;
+      applyBodySpacing();
+    };
+    if (typeof MutationObserver === "function" && document.documentElement) {
+      const observer = new MutationObserver(() => {
+        if (!document.body) return;
+        observer.disconnect();
+        retry();
+      });
+      observer.observe(document.documentElement, { childList: true });
+      document.addEventListener("DOMContentLoaded", () => {
+        observer.disconnect();
+        retry();
+      }, { once: true });
+      return;
+    }
+    document.addEventListener("DOMContentLoaded", retry, { once: true });
+  }
+
   async function prepareGatewayForNavigation() {
     const host = globalThis.RingsWebviewHost;
     if (!host || typeof host.ensureReady !== "function") return;
@@ -293,11 +343,13 @@
       return;
     }
     record("overlay", "Connecting through the local Rings gateway");
+    setLoading(true);
     try {
       await prepareGatewayForNavigation();
       record("overlay", "Request sent to the local Rings gateway");
       location.href = path;
     } catch (error) {
+      setLoading(false);
       record("overlay", `gateway unavailable: ${String(error)}`, "error");
     }
   }
@@ -393,12 +445,17 @@
         :host { all: initial; }
         #toolbar { position: fixed; inset: 0 0 auto 0; z-index: 2147483647; display: grid; min-width: 0; min-height: 46px; box-sizing: border-box; grid-template-columns: auto minmax(0, 1fr) auto; gap: 7px; align-items: center; padding: 6px 8px; border-bottom: 1px solid #ddccb0; background: #fffaf0; color: #111827; box-shadow: 0 1px 4px rgba(17, 24, 39, 0.16); font: 12px/1 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
         #controls { display: flex; min-width: 0; gap: 5px; }
-        #address-form { display: grid; min-width: 0; grid-template-columns: minmax(0, 1fr) auto; gap: 6px; }
-        #address { width: 100%; min-width: 0; height: 32px; box-sizing: border-box; padding: 5px 9px; border: 1px solid #d9c5a6; border-radius: 5px; background: #fffdf8; color: #111827; font: 12px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace; }
+        #address-form { position: relative; display: grid; min-width: 0; grid-template-columns: minmax(0, 1fr) auto; gap: 6px; }
+        #address { grid-column: 1; grid-row: 1; width: 100%; min-width: 0; height: 32px; box-sizing: border-box; padding: 5px 9px; border: 1px solid #d9c5a6; border-radius: 5px; background: #fffdf8; color: #111827; font: 12px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace; }
         #address:focus { border-color: #b42318; outline: 3px solid rgba(180, 35, 24, 0.12); }
+        #address-form[data-loading=true] #address { border-color: #8ab4f8; box-shadow: inset 0 -2px 0 rgba(26, 115, 232, 0.18); }
+        #loading-track { position: relative; z-index: 2; grid-column: 1; grid-row: 1; align-self: end; height: 2px; margin: 0 2px 2px; overflow: hidden; border-radius: 999px; pointer-events: none; }
+        #loading-track[hidden] { display: none; }
+        #loading-bar { position: absolute; inset: 0 auto 0 0; width: 42%; border-radius: inherit; background: linear-gradient(90deg, #1a73e8, #34a853); transform: translateX(-120%); animation: rings-webview-loading 1.15s cubic-bezier(.4, 0, .2, 1) infinite; }
+        @keyframes rings-webview-loading { 0% { transform: translateX(-120%) scaleX(.65); } 45% { transform: translateX(72%) scaleX(1); } 100% { transform: translateX(250%) scaleX(.75); } }
         #toolbar button { display: grid; min-width: 34px; height: 32px; min-height: 32px; box-sizing: border-box; place-items: center; padding: 0 9px; border: 1px solid #d9c5a6; border-radius: 5px; background: #fffaf0; color: #374151; font: 800 12px/1 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; cursor: pointer; }
         #toolbar button:hover, #toolbar button[data-active=true] { border-color: #111827; background: #111827; color: #fff; }
-        #go { min-width: 38px; }
+        #go { grid-column: 2; grid-row: 1; min-width: 38px; }
         #toggle { min-width: 34px; padding: 0; }
         #panel { position: fixed; inset: auto 0 0 0; z-index: 2147483647; display: grid; width: 100vw; height: 300px; max-height: 45vh; box-sizing: border-box; grid-template-rows: auto minmax(0, 1fr); border-top: 1px solid #dadce0; background: #fff; color: #202124; box-shadow: 0 -1px 3px rgba(60, 64, 67, 0.22); overflow: hidden; font: 12px/1.35 ui-monospace, SFMono-Regular, Menlo, monospace; }
         #panel[hidden] { display: none; }
@@ -442,6 +499,7 @@
         
         

           
+