diff --git a/.gitmodules b/.gitmodules
index ffa7a3c9..dff6d927 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -2,3 +2,7 @@
 	path = hosts/dotli
 	url = https://github.com/paritytech/dotli-community
 	branch = main
+[submodule "hosts/ios"]
+	path = hosts/ios
+	url = https://github.com/paritytech/polkadot-app-ios-v2
+	branch = codex/truapi-rust-core
diff --git a/Cargo.lock b/Cargo.lock
index f6aaa021..ed7e0c6a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -120,6 +120,48 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
 
+[[package]]
+name = "askama"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d4744ed2eef2645831b441d8f5459689ade2ab27c854488fbab1fbe94fce1a7"
+dependencies = [
+ "askama_derive",
+ "itoa",
+ "percent-encoding",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "askama_derive"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d661e0f57be36a5c14c48f78d09011e67e0cb618f269cca9f2fd8d15b68c46ac"
+dependencies = [
+ "askama_parser",
+ "basic-toml",
+ "memchr",
+ "proc-macro2",
+ "quote",
+ "rustc-hash",
+ "serde",
+ "serde_derive",
+ "syn",
+]
+
+[[package]]
+name = "askama_parser"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf315ce6524c857bb129ff794935cf6d42c82a6cff60526fe2a63593de4d0d4f"
+dependencies = [
+ "memchr",
+ "serde",
+ "serde_derive",
+ "winnow 0.7.15",
+]
+
 [[package]]
 name = "async-channel"
 version = "2.5.0"
@@ -292,6 +334,15 @@ version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
+[[package]]
+name = "basic-toml"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba62675e8242a4c4e806d12f11d136e626e6c8361d6b829310732241652a178a"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "bip39"
 version = "2.2.2"
@@ -413,6 +464,38 @@ version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593"
 
+[[package]]
+name = "camino"
+version = "1.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f2d30e4173c4026932d51d31d6b0613b1fd3014bf3f9f8943d4ba139c437ba0"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "cargo-platform"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e35af189006b9c0f00a064685c727031e3ed2d8020f7ba284d78cc2671bd36ea"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "cargo_metadata"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd5eb614ed4c27c5d706420e4320fbe3216ab31fa1c33cd8246ac36dae4479ba"
+dependencies = [
+ "camino",
+ "cargo-platform",
+ "semver",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "cast"
 version = "0.3.0"
@@ -709,6 +792,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "data-encoding"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"
+
 [[package]]
 name = "der"
 version = "0.7.10"
@@ -908,7 +997,7 @@ dependencies = [
  "foldhash 0.2.0",
  "libm",
  "portable-atomic",
- "siphasher",
+ "siphasher 1.0.3",
 ]
 
 [[package]]
@@ -999,6 +1088,15 @@ dependencies = [
  "scale-info",
 ]
 
+[[package]]
+name = "fs-err"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88a41f105fe1d5b6b34b2055e3dc59bb79b46b48b2040b9e6c7b4b5de097aa41"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "funty"
 version = "2.0.0"
@@ -1172,6 +1270,12 @@ dependencies = [
  "polyval",
 ]
 
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
 [[package]]
 name = "gloo-net"
 version = "0.6.0"
@@ -1218,6 +1322,17 @@ dependencies = [
  "web-sys",
 ]
 
+[[package]]
+name = "goblin"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b363a30c165f666402fe6a3024d3bec7ebc898f96a4a23bd1c99f8dbf3f4f47"
+dependencies = [
+ "log",
+ "plain",
+ "scroll",
+]
+
 [[package]]
 name = "group"
 version = "0.13.0"
@@ -1839,6 +1954,12 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
 [[package]]
 name = "mio"
 version = "1.2.1"
@@ -1862,6 +1983,16 @@ version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72ef4a56884ca558e5ddb05a1d1e7e1bfd9a68d9ed024c21704cc98872dae1bb"
 
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
 [[package]]
 name = "nom"
 version = "8.0.0"
@@ -2088,6 +2219,12 @@ dependencies = [
  "spki",
 ]
 
+[[package]]
+name = "plain"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
+
 [[package]]
 name = "polling"
 version = "3.11.0"
@@ -2459,6 +2596,26 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "scroll"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ab8598aa408498679922eff7fa985c25d58a90771bd6be794434c5277eab1a6"
+dependencies = [
+ "scroll_derive",
+]
+
+[[package]]
+name = "scroll_derive"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1783eabc414609e28a5ba76aee5ddd52199f7107a0b24c2e9746a1ecc34a683d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "sec1"
 version = "0.7.3"
@@ -2500,6 +2657,10 @@ name = "semver"
 version = "1.0.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+dependencies = [
+ "serde",
+ "serde_core",
+]
 
 [[package]]
 name = "send_wrapper"
@@ -2645,6 +2806,12 @@ version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 
+[[package]]
+name = "siphasher"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38b58827f4464d87d377d175e90bf58eb00fd8716ff0a62f80356b5e61555d0d"
+
 [[package]]
 name = "siphasher"
 version = "1.0.3"
@@ -2663,6 +2830,12 @@ version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
+[[package]]
+name = "smawk"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8e2fb0f499abb4d162f2bedad68f5ef91a1682b5a03596ddb67efd37768d100"
+
 [[package]]
 name = "smol"
 version = "2.0.2"
@@ -2711,7 +2884,7 @@ dependencies = [
  "libm",
  "libsecp256k1",
  "merlin",
- "nom",
+ "nom 8.0.0",
  "num-bigint",
  "num-rational",
  "num-traits",
@@ -2726,7 +2899,7 @@ dependencies = [
  "serde_json",
  "sha2 0.10.9",
  "sha3",
- "siphasher",
+ "siphasher 1.0.3",
  "slab",
  "smallvec",
  "soketto",
@@ -2767,7 +2940,7 @@ dependencies = [
  "libm",
  "libsecp256k1",
  "merlin",
- "nom",
+ "nom 8.0.0",
  "num-bigint",
  "num-rational",
  "num-traits",
@@ -2782,7 +2955,7 @@ dependencies = [
  "serde_json",
  "sha2 0.10.9",
  "sha3",
- "siphasher",
+ "siphasher 1.0.3",
  "slab",
  "smallvec",
  "soketto",
@@ -2821,7 +2994,7 @@ dependencies = [
  "rand_chacha",
  "serde",
  "serde_json",
- "siphasher",
+ "siphasher 1.0.3",
  "slab",
  "smol",
  "smoldot 2.0.0",
@@ -3000,6 +3173,15 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "textwrap"
+version = "0.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c13547615a44dc9c452a8a534638acdf07120d4b6847c8178705da06306a3057"
+dependencies = [
+ "smawk",
+]
+
 [[package]]
 name = "thiserror"
 version = "1.0.69"
@@ -3080,6 +3262,7 @@ version = "1.52.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
 dependencies = [
+ "bytes",
  "libc",
  "mio",
  "pin-project-lite",
@@ -3120,6 +3303,18 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-tungstenite"
+version = "0.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c83b561d025642014097b66e6c1bb422783339e0909e4429cde4749d1990bc38"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -3134,6 +3329,15 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "toml"
+version = "0.5.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4f7f0dd8d50a853a531c426359045b1998f04219d88799810762cd4ad314234"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "toml_datetime"
 version = "1.1.1+spec-1.1.0"
@@ -3152,7 +3356,7 @@ dependencies = [
  "indexmap",
  "toml_datetime",
  "toml_parser",
- "winnow",
+ "winnow 1.0.2",
 ]
 
 [[package]]
@@ -3161,7 +3365,7 @@ version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
 dependencies = [
- "winnow",
+ "winnow 1.0.2",
 ]
 
 [[package]]
@@ -3273,6 +3477,7 @@ dependencies = [
  "parity-scale-codec",
  "pin-project",
  "primitive-types",
+ "rand",
  "schnorrkel",
  "send_wrapper 0.6.0",
  "serde",
@@ -3281,11 +3486,14 @@ dependencies = [
  "sp-crypto-hashing",
  "subxt-rpcs",
  "thiserror 1.0.69",
+ "tokio",
+ "tokio-tungstenite",
  "tracing",
  "tracing-subscriber",
  "truapi",
  "truapi-platform",
  "unicode-normalization",
+ "uniffi",
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
@@ -3294,6 +3502,25 @@ dependencies = [
  "web-time",
 ]
 
+[[package]]
+name = "tungstenite"
+version = "0.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ef1a641ea34f399a848dea702823bbecfb4c486f911735368f1f137cb8257e1"
+dependencies = [
+ "byteorder",
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand",
+ "sha1",
+ "thiserror 1.0.69",
+ "url",
+ "utf-8",
+]
+
 [[package]]
 name = "twox-hash"
 version = "1.6.3"
@@ -3356,6 +3583,134 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "uniffi"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3291800a6b06569f7d3e15bdb6dc235e0f0c8bd3eb07177f430057feb076415f"
+dependencies = [
+ "anyhow",
+ "camino",
+ "cargo_metadata",
+ "clap",
+ "uniffi_bindgen",
+ "uniffi_core",
+ "uniffi_macros",
+ "uniffi_pipeline",
+]
+
+[[package]]
+name = "uniffi-bindgen-cli"
+version = "0.1.0"
+dependencies = [
+ "uniffi",
+]
+
+[[package]]
+name = "uniffi_bindgen"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a04b99fa7796eaaa7b87976a0dbdd1178dc1ee702ea00aca2642003aef9b669e"
+dependencies = [
+ "anyhow",
+ "askama",
+ "camino",
+ "cargo_metadata",
+ "fs-err",
+ "glob",
+ "goblin",
+ "heck",
+ "indexmap",
+ "once_cell",
+ "serde",
+ "tempfile",
+ "textwrap",
+ "toml",
+ "uniffi_internal_macros",
+ "uniffi_meta",
+ "uniffi_pipeline",
+ "uniffi_udl",
+]
+
+[[package]]
+name = "uniffi_core"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f38a9a27529ccff732f8efddb831b65b1e07f7dea3fd4cacd4a35a8c4b253b98"
+dependencies = [
+ "anyhow",
+ "bytes",
+ "once_cell",
+ "static_assertions",
+]
+
+[[package]]
+name = "uniffi_internal_macros"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09acd2ce09c777dd65ee97c251d33c8a972afc04873f1e3b21eb3492ade16933"
+dependencies = [
+ "anyhow",
+ "indexmap",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "uniffi_macros"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5596f178c4f7aafa1a501c4e0b96236a96bc2ef92bdb453d83e609dad0040152"
+dependencies = [
+ "camino",
+ "fs-err",
+ "once_cell",
+ "proc-macro2",
+ "quote",
+ "serde",
+ "syn",
+ "toml",
+ "uniffi_meta",
+]
+
+[[package]]
+name = "uniffi_meta"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "beadc1f460eb2e209263c49c4f5b19e9a02e00a3b2b393f78ad10d766346ecff"
+dependencies = [
+ "anyhow",
+ "siphasher 0.3.11",
+ "uniffi_internal_macros",
+ "uniffi_pipeline",
+]
+
+[[package]]
+name = "uniffi_pipeline"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd76b3ac8a2d964ca9fce7df21c755afb4c77b054a85ad7a029ad179cc5abb8a"
+dependencies = [
+ "anyhow",
+ "heck",
+ "indexmap",
+ "tempfile",
+ "uniffi_internal_macros",
+]
+
+[[package]]
+name = "uniffi_udl"
+version = "0.29.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4319cf905911d70d5b97ce0f46f101619a22e9a189c8c46d797a9955e9233716"
+dependencies = [
+ "anyhow",
+ "textwrap",
+ "uniffi_meta",
+ "weedle2",
+]
+
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
@@ -3384,6 +3739,12 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "utf-8"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -3652,6 +4013,15 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "weedle2"
+version = "5.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "998d2c24ec099a87daf9467808859f9d82b61f1d9c9701251aea037f514eae0e"
+dependencies = [
+ "nom 7.1.3",
+]
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -3824,6 +4194,15 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
+[[package]]
+name = "winnow"
+version = "0.7.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "winnow"
 version = "1.0.2"
diff --git a/Makefile b/Makefile
index 285aa467..efec4783 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,7 @@
 # Run `make help` for the list of targets.
 
 .DEFAULT_GOAL := help
-.PHONY: help setup build codegen test check playground wasm wasm-crypto-test dev dev-bootstrap dev-link-check e2e-dotli matrix explorer
+.PHONY: help setup build codegen test check playground wasm wasm-crypto-test uniffi dev dev-bootstrap dev-link-check e2e-dotli matrix explorer
 
 TRUAPI_PKG := js/packages/truapi
 PLAYGROUND := playground
@@ -58,6 +58,32 @@ wasm: ## Rebuild the truapi-server WASM artifacts under js/packages/truapi-host-
 wasm-crypto-test: ## Run crypto/vector tests on wasm32 via wasm-pack/node.
 	wasm-pack test --node rust/crates/truapi-server --test wasm_crypto_vectors --no-default-features
 
+UNIFFI_CDYLIB_DIR := target/release
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Darwin)
+UNIFFI_CDYLIB := $(UNIFFI_CDYLIB_DIR)/libtruapi_server.dylib
+else
+UNIFFI_CDYLIB := $(UNIFFI_CDYLIB_DIR)/libtruapi_server.so
+endif
+
+UNIFFI_SWIFT_TMP := target/uniffi-swift-out
+
+uniffi: ## Regenerate Swift bindings from truapi-server cdylib.
+	cargo build -p truapi-server --release --features ws-bridge
+	rm -rf $(UNIFFI_SWIFT_TMP)
+	mkdir -p $(UNIFFI_SWIFT_TMP)
+	cargo run -p uniffi-bindgen-cli -- generate \
+		--library $(UNIFFI_CDYLIB) \
+		--language swift \
+		--out-dir $(UNIFFI_SWIFT_TMP)
+	mkdir -p ios/truapi-host/Sources/truapi_serverFFI/include
+	cp $(UNIFFI_SWIFT_TMP)/truapi_server.swift \
+		ios/truapi-host/Sources/TrUAPIHost/truapi_server.swift
+	cp $(UNIFFI_SWIFT_TMP)/truapi_serverFFI.h \
+		ios/truapi-host/Sources/truapi_serverFFI/include/truapi_serverFFI.h
+	cp $(UNIFFI_SWIFT_TMP)/truapi_serverFFI.modulemap \
+		ios/truapi-host/Sources/truapi_serverFFI/include/module.modulemap
+
 test: ## Run Rust + TypeScript client tests.
 	cargo test --workspace
 	cd $(TRUAPI_PKG) && npm test
diff --git a/hosts/ios b/hosts/ios
new file mode 160000
index 00000000..915f8d13
--- /dev/null
+++ b/hosts/ios
@@ -0,0 +1 @@
+Subproject commit 915f8d135ee5fde3fe7bf5a9192318cbc82ecbfb
diff --git a/ios/truapi-host/.gitignore b/ios/truapi-host/.gitignore
new file mode 100644
index 00000000..11cc1dd7
--- /dev/null
+++ b/ios/truapi-host/.gitignore
@@ -0,0 +1,4 @@
+.build/
+DerivedData/
+*.xcodeproj/xcuserdata/
+Package.resolved
diff --git a/ios/truapi-host/Package.swift b/ios/truapi-host/Package.swift
new file mode 100644
index 00000000..e7764729
--- /dev/null
+++ b/ios/truapi-host/Package.swift
@@ -0,0 +1,35 @@
+// swift-tools-version: 5.9
+//
+// TrUAPI iOS host package.
+//
+// The `truapi_serverFFI` target wraps the UniFFI-generated C header + module
+// map so the generated Swift bindings can `import truapi_serverFFI`. The
+// `TrUAPIHost` target contains both the generated Swift bindings and the
+// thin host shell defined in `TrUAPIHost.swift`.
+//
+// Consumers must link a prebuilt `libtruapi_server` static or dynamic
+// library when integrating into their app target. This package does not
+// vendor the binary itself; see README.md for build instructions.
+
+import PackageDescription
+
+let package = Package(
+    name: "TrUAPIHost",
+    platforms: [.iOS(.v16), .macOS(.v13)],
+    products: [
+        .library(name: "TrUAPIHost", targets: ["TrUAPIHost"]),
+    ],
+    targets: [
+        .systemLibrary(
+            name: "truapi_serverFFI",
+            path: "Sources/truapi_serverFFI/include",
+            pkgConfig: nil,
+            providers: []
+        ),
+        .target(
+            name: "TrUAPIHost",
+            dependencies: ["truapi_serverFFI"],
+            path: "Sources/TrUAPIHost"
+        ),
+    ]
+)
diff --git a/ios/truapi-host/README.md b/ios/truapi-host/README.md
new file mode 100644
index 00000000..d0975577
--- /dev/null
+++ b/ios/truapi-host/README.md
@@ -0,0 +1,204 @@
+# TrUAPI iOS host adapter
+
+*Thin Swift shell over the Rust TrUAPI core (UniFFI). Wire decoding, request routing, and subscription lifecycle stay in the Rust core; products connect through the localhost WebSocket bridge.*
+
+## What this package is for
+
+The public surface lives in [`Sources/TrUAPIHost/TrUAPIHost.swift`](Sources/TrUAPIHost/TrUAPIHost.swift):
+
+- `HostBridge` - callback bundle the embedding app implements. Split into device permissions, remote permissions, navigation, push, feature support, and scoped storage.
+- `HostStorageBackend` - product-scoped read/write/clear protocol the host backs with its own persistence.
+- `HostCoreStorageBackend` - core-owned read/write/clear protocol for auth session, pairing identity, and persisted permission decisions.
+- `TrUAPIHostCore` - owning wrapper around the UniFFI-generated `NativeTrUApiCore`. Holds the bridge alive for the lifetime of the core and exposes the localhost WebSocket bridge, core-owned disconnect, and native change notifications for core storage, theme, and preimage updates.
+- `LocalhostBridgeBootstrap` - helper that produces a JS snippet publishing the WS bridge endpoint to the product page so it can dial back in.
+
+The generated UniFFI bindings live alongside the shell in `Sources/TrUAPIHost/truapi_server.swift` and the C header / module map in `Sources/truapi_serverFFI/include/`. They are ignored build outputs; regenerate them before building or publishing the Swift package.
+
+## Architecture
+
+```text
+product app in WKWebView
+  Uint8Array frames via @parity/truapi createWebSocketProvider
+           |
+           v   ws://127.0.0.1:<port>/?t=<token>
+TrUAPIHostCore.startWsBridge()
+  → libtruapi_server (tokio WS server)
+  → Rust dispatcher
+```
+
+The product running in the `WKWebView` opens a `WebSocket` to the localhost port + token returned by `startWsBridge`. From there the Rust core handles the wire protocol directly. Outbound responses and host-side capability callbacks (`navigateTo`, `pushNotification`, `cancelNotification`, `devicePermission`, `remotePermission`, `authStateChanged`, core storage, chain JSON-RPC, confirmations, preimage, theme, `featureSupported`, `storage`) reach the embedder through `HostBridge`.
+
+## Permissions split
+
+The core's `Permissions` platform trait has two methods, and so does the bridge:
+
+- `devicePermission(request:)` - OS-scoped grants (camera, mic, location, push). `request` is a SCALE-encoded `v01::HostDevicePermissionRequest`.
+- `remotePermission(request:)` - per-product capability bundles. `request` is a SCALE-encoded `v01::RemotePermissionRequest`.
+
+Both return a `Bool` granted flag. SCALE decoding for the UI prompt is done by the `@parity/truapi` JS client (or any consumer that links the protocol crate's types directly).
+
+## Example
+
+> **Threading:** the Rust core invokes every `HostBridge` callback on a
+> background thread it owns, never the main thread. Hop to the main thread
+> (`DispatchQueue.main` / `MainActor`) before touching UIKit, WebKit, or the
+> `WKWebView`. UI-decision callbacks (`navigateTo`, `devicePermission`,
+> `remotePermission`, `confirmUserAction`, `submitPreimage`) each run on
+> their own blocking-pool thread, so it is safe to use
+> `DispatchQueue.main.sync` (or a semaphore) to present the prompt on the
+> main thread and block the calling thread until the user decides; other
+> TrUAPI traffic keeps flowing while you wait. The remaining callbacks (auth
+> state, storage, core storage, chain, feature, theme, preimage lookups) run
+> inline on the dispatcher thread and must return promptly without blocking.
+
+```swift
+import Foundation
+import WebKit
+import TrUAPIHost
+
+final class MyStorage: HostStorageBackend, @unchecked Sendable {
+    private var map: [String: Data] = [:]
+    func read(key: String) throws -> Data? { map[key] }
+    func write(key: String, value: Data) throws { map[key] = value }
+    func clear(key: String) throws { map.removeValue(forKey: key) }
+}
+
+final class MyCoreStorage: HostCoreStorageBackend, @unchecked Sendable {
+    private var map: [Data: Data] = [:]
+    func read(key: Data) throws -> Data? { map[key] }
+    func write(key: Data, value: Data) throws { map[key] = value }
+    func clear(key: Data) throws { map.removeValue(forKey: key) }
+}
+
+final class MyBridge: HostBridge, @unchecked Sendable {
+    let storage: HostStorageBackend = MyStorage()
+    let coreStorage: HostCoreStorageBackend = MyCoreStorage()
+
+    // Callbacks arrive on background threads, never the main thread.
+    // Hop to the main thread before touching UIKit/WebKit.
+    func navigateTo(url: String) throws {
+        DispatchQueue.main.async { /* UIApplication.shared.open(...) */ }
+    }
+
+    func pushNotification(payload: Data) throws -> UInt32 {
+        let id: UInt32 = 1
+        DispatchQueue.main.async { /* schedule notification */ }
+        return id
+    }
+
+    func cancelNotification(id: UInt32) throws {
+        DispatchQueue.main.async { /* cancel notification */ }
+    }
+
+    func devicePermission(request: Data) throws -> Bool {
+        // Called on a blocking-pool thread; present synchronously on the main
+        // thread and return the decision. Blocking here does not stall other
+        // TrUAPI traffic.
+        DispatchQueue.main.sync { /* show prompt; */ false }
+    }
+
+    func remotePermission(request: Data) throws -> Bool {
+        DispatchQueue.main.sync { /* show prompt; */ false }
+    }
+
+    // Core-owned auth state stream: render `.pairing` as the pairing QR
+    // sheet, `.connected`/`.disconnected` as the account badge, and
+    // `.loginFailed` as a retryable error. When the user closes the pairing
+    // sheet, report it with `core.cancelLogin()`.
+    func authStateChanged(state: AuthState) {
+        DispatchQueue.main.async { /* render the state */ }
+    }
+
+    func featureSupported(request: Data) throws -> Bool { false }
+
+    func chainConnect(genesisHash: Data) throws -> UInt32? {
+        let id: UInt32 = 1
+        DispatchQueue.main.async { /* open JSON-RPC connection, forward responses via core.notifyChainResponse */ }
+        return id
+    }
+
+    func chainSend(connectionId: UInt32, request: String) throws {
+        /* send JSON-RPC request on the host connection */
+    }
+
+    func chainClose(connectionId: UInt32) throws {
+        /* close host connection */
+    }
+
+    func confirmUserAction(review: Data) throws -> Bool {
+        DispatchQueue.main.sync { /* render decoded UserConfirmationReview; */ false }
+    }
+}
+
+let bridge = MyBridge()
+let runtimeConfig = RuntimeConfig(
+    productId: "my-product.dot",
+    hostName: "My Host",
+    hostIcon: "https://host.example/icon.png",
+    peopleChainGenesisHash: Data(repeating: 0, count: 32),
+    pairingDeeplinkScheme: .polkadotApp
+)
+let core = try TrUAPIHostCore(bridge: bridge, runtimeConfig: runtimeConfig)
+let endpoint = try core.startWsBridge()
+
+// Call these from host/platform observers so native subscriptions see updates
+// after their immediate current item.
+core.notifySessionStoreChanged()
+core.notifyThemeChanged(theme: .dark)
+core.notifyPreimageChanged(key: preimageKey, value: preimageBytesOrNil)
+core.notifyChainResponse(connectionId: chainConnectionId, json: jsonRpcResponse)
+core.notifyChainClosed(connectionId: chainConnectionId)
+
+let contentController = WKUserContentController()
+let bootstrapScript = LocalhostBridgeBootstrap.script(port: endpoint.port, token: endpoint.token)
+let userScript = WKUserScript(
+    source: bootstrapScript,
+    injectionTime: .atDocumentStart,
+    forMainFrameOnly: true
+)
+contentController.addUserScript(userScript)
+
+let configuration = WKWebViewConfiguration()
+configuration.userContentController = contentController
+let webView = WKWebView(frame: .zero, configuration: configuration)
+webView.load(URLRequest(url: URL(string: "https://your-product.example/")!))
+
+// On logout:
+core.disconnect()
+```
+
+The product page reads `window.__truapi_localhost.url` (set by the bootstrap script) and passes it to `@parity/truapi`'s `createWebSocketProvider(url)`.
+
+## Linking the cdylib
+
+This package does not vendor `libtruapi_server` - integrators link a prebuilt static or dynamic library when building the app target. Typical workflow:
+
+```bash
+cargo build -p truapi-server --release --features ws-bridge \
+  --target aarch64-apple-ios
+cargo build -p truapi-server --release --features ws-bridge \
+  --target aarch64-apple-ios-sim
+```
+
+Then either bundle the `.a` files as a `.xcframework` and add it under "Frameworks, Libraries, and Embedded Content" in the app target, or link directly via `OTHER_LDFLAGS`.
+
+## Regenerating the bindings
+
+The ignored bindings under `Sources/TrUAPIHost/truapi_server.swift` and `Sources/truapi_serverFFI/include/` are produced from the workspace `uniffi-bindgen-cli`. Regenerate them before building or publishing the Swift package. The CLI emits `truapi_server.swift`, `truapi_serverFFI.h`, and `truapi_serverFFI.modulemap` into a single output directory; the modulemap is renamed to `module.modulemap` and the header is colocated under `Sources/truapi_serverFFI/include/` so SwiftPM's `systemLibrary` target picks them up.
+
+```bash
+cargo build -p truapi-server --release --features ws-bridge
+mkdir -p /tmp/uniffi-swift-out
+cargo run -p uniffi-bindgen-cli -- generate \
+  --library target/release/libtruapi_server.so \
+  --language swift \
+  --out-dir /tmp/uniffi-swift-out
+cp /tmp/uniffi-swift-out/truapi_server.swift \
+   ios/truapi-host/Sources/TrUAPIHost/truapi_server.swift
+cp /tmp/uniffi-swift-out/truapi_serverFFI.h \
+   ios/truapi-host/Sources/truapi_serverFFI/include/truapi_serverFFI.h
+cp /tmp/uniffi-swift-out/truapi_serverFFI.modulemap \
+   ios/truapi-host/Sources/truapi_serverFFI/include/module.modulemap
+```
+
+Or run `make uniffi` from the repo root.
diff --git a/ios/truapi-host/Sources/TrUAPIHost/TrUAPIHost.swift b/ios/truapi-host/Sources/TrUAPIHost/TrUAPIHost.swift
new file mode 100644
index 00000000..de6c28c1
--- /dev/null
+++ b/ios/truapi-host/Sources/TrUAPIHost/TrUAPIHost.swift
@@ -0,0 +1,563 @@
+// TrUAPIHost - iOS host adapter.
+//
+// The Rust core (compiled to `libtruapi_server`, surfaced through UniFFI in
+// the sibling `truapi_server.swift` file) owns wire decoding, request
+// routing, subscription lifecycle, and platform trait dispatch.
+//
+// This file exposes:
+//
+//   * `HostBridge` - a Swift-friendly callback bundle the embedding app
+//     implements. It splits device and remote permissions, mirroring the
+//     `Permissions` platform trait in the Rust core.
+//   * `TrUAPIHostCore` - owning wrapper around the UniFFI-generated
+//     `NativeTrUApiCore`. Holds the bridge alive for the lifetime of the
+//     core and exposes session + WS-bridge controls.
+//   * `LocalhostBridgeBootstrap` - small JS snippet that publishes the WS
+//     bridge endpoint to the product page so it can dial back in.
+//
+// Products running inside a `WKWebView` connect to the Rust core via the
+// localhost WebSocket bridge. The bootstrap script publishes the URL
+// (`ws://127.0.0.1:<port>/?t=<token>`) and a MessagePort-shaped compatibility
+// object that proxies the product's existing webview transport onto it.
+
+import Foundation
+
+/// Package metadata.
+public enum TrUAPIHost {
+    public static let version = "0.1.0"
+}
+
+/// Deeplink scheme used when the Rust core builds SSO pairing payloads.
+public enum PairingDeeplinkScheme: Sendable {
+    case polkadotApp
+    case polkadotAppDev
+
+    fileprivate var native: NativePairingDeeplinkScheme {
+        switch self {
+        case .polkadotApp:
+            return .polkadotApp
+        case .polkadotAppDev:
+            return .polkadotAppDev
+        }
+    }
+}
+
+/// Static product and pairing config supplied before the Rust core handles
+/// product calls. One core instance represents one product identity.
+///
+/// `hostName`, `hostIcon`, `hostVersion`, `platformType`, and
+/// `platformVersion` describe the host to the wallet during SSO pairing.
+/// `peopleChainGenesisHash` must be exactly 32 bytes.
+public struct RuntimeConfig: Sendable {
+    public let productId: String
+    public let hostName: String
+    public let hostIcon: String?
+    public let hostVersion: String?
+    public let platformType: String?
+    public let platformVersion: String?
+    public let peopleChainGenesisHash: Data
+    public let pairingDeeplinkScheme: PairingDeeplinkScheme
+
+    public init(
+        productId: String,
+        hostName: String,
+        hostIcon: String? = nil,
+        hostVersion: String? = nil,
+        platformType: String? = nil,
+        platformVersion: String? = nil,
+        peopleChainGenesisHash: Data,
+        pairingDeeplinkScheme: PairingDeeplinkScheme = .polkadotApp
+    ) {
+        self.productId = productId
+        self.hostName = hostName
+        self.hostIcon = hostIcon
+        self.hostVersion = hostVersion
+        self.platformType = platformType
+        self.platformVersion = platformVersion
+        self.peopleChainGenesisHash = peopleChainGenesisHash
+        self.pairingDeeplinkScheme = pairingDeeplinkScheme
+    }
+
+    fileprivate var native: NativeRuntimeConfig {
+        NativeRuntimeConfig(
+            productId: productId,
+            hostName: hostName,
+            hostIcon: hostIcon,
+            hostVersion: hostVersion,
+            platformType: platformType,
+            platformVersion: platformVersion,
+            peopleChainGenesisHash: peopleChainGenesisHash,
+            pairingDeeplinkScheme: pairingDeeplinkScheme.native
+        )
+    }
+}
+
+/// Bootstrap helper for the native localhost WebSocket bridge that the Rust
+/// core stands up via `NativeTrUApiCore.startWsBridge(bindPort:)` when the
+/// cdylib is built with the `ws-bridge` feature.
+public enum LocalhostBridgeBootstrap {
+    /// Returns a `<script>`-injectable snippet that publishes the endpoint
+    /// metadata on `window.__truapi_localhost`, exposes the legacy
+    /// `window.__HOST_API_PORT__` webview transport shape, and fires a
+    /// `truapi-native-ready` event.
+    public static func script(port: UInt16, token: String) -> String {
+        let url = "ws://127.0.0.1:\(port)/?t=\(token)"
+        let safeUrl = jsStringLiteral(url)
+        let safeToken = jsStringLiteral(token)
+        return """
+        (function() {
+          var endpoint = { url: \(safeUrl), token: \(safeToken) };
+
+          function createWebSocketMessagePort(url) {
+            var socket = null;
+            var started = false;
+            var queue = [];
+
+            var port = {
+              onmessage: null,
+              onmessageerror: null,
+
+              postMessage: function(message) {
+                if (socket && socket.readyState === WebSocket.OPEN) {
+                  socket.send(message);
+                } else {
+                  queue.push(message);
+                }
+              },
+
+              start: function() {
+                if (started) return;
+                started = true;
+
+                socket = new WebSocket(url);
+                socket.binaryType = "arraybuffer";
+
+                socket.onopen = function() {
+                  var pending = queue;
+                  queue = [];
+                  pending.forEach(function(message) {
+                    socket.send(message);
+                  });
+                };
+
+                socket.onmessage = function(event) {
+                  if (typeof port.onmessage === "function") {
+                    port.onmessage({ data: new Uint8Array(event.data) });
+                  }
+                };
+
+                socket.onerror = function() {
+                  if (typeof port.onmessageerror === "function") {
+                    port.onmessageerror();
+                  }
+                };
+
+                socket.onclose = function() {
+                  if (typeof port.onmessageerror === "function") {
+                    port.onmessageerror();
+                  }
+                };
+              },
+
+              close: function() {
+                queue = [];
+                if (socket) {
+                  socket.close();
+                }
+              }
+            };
+
+            return port;
+          }
+
+          window.__truapi_localhost = endpoint;
+          window.__HOST_WEBVIEW_MARK__ = true;
+          window.__HOST_API_PORT__ = createWebSocketMessagePort(endpoint.url);
+          window.dispatchEvent(new Event('truapi-native-ready'));
+        })();
+        """
+    }
+
+    /// Encodes `value` as a complete double-quoted JavaScript string literal,
+    /// safe to embed inside a `<script>` body. `JSONEncoder` escapes quotes,
+    /// backslashes, control characters, and forward slashes (closing `</script`
+    /// tags); U+2028 / U+2029 are escaped explicitly because JSON leaves them
+    /// raw while JS treats them as line terminators. Falls back to an empty
+    /// literal if encoding ever fails.
+    private static func jsStringLiteral(_ value: String) -> String {
+        guard let data = try? JSONEncoder().encode(value),
+              let encoded = String(data: data, encoding: .utf8)
+        else {
+            return "\"\""
+        }
+        return encoded
+            .replacingOccurrences(of: "\u{2028}", with: "\\u2028")
+            .replacingOccurrences(of: "\u{2029}", with: "\\u2029")
+    }
+}
+
+/// Storage backend the host provides to the Rust core. Throwing closures
+/// can surface quota or unknown failures by raising `HostStorageError`
+/// (defined in the generated bindings).
+public protocol HostStorageBackend: AnyObject, Sendable {
+    func read(key: String) throws -> Data?
+    func write(key: String, value: Data) throws
+    func clear(key: String) throws
+}
+
+/// Core-owned host-private storage backend. Keys are SCALE-encoded
+/// `truapi_platform::CoreStorageKey` values, so embedders can persist them
+/// opaquely or decode them to choose a secure backing store per slot.
+public protocol HostCoreStorageBackend: AnyObject, Sendable {
+    func read(key: Data) throws -> Data?
+    func write(key: Data, value: Data) throws
+    func clear(key: Data) throws
+}
+
+/// Host-side callback bundle that the Rust core invokes for capabilities the
+/// native shell owns. The permission split mirrors the Rust `Permissions`
+/// trait:
+///
+///   * ``devicePermission(request:)`` handles OS-scoped grants (camera,
+///     mic, location). `request` is a SCALE-encoded
+///     `v01::HostDevicePermissionRequest`.
+///   * ``remotePermission(request:)`` handles per-product capability
+///     bundles. `request` is a SCALE-encoded `v01::RemotePermissionRequest`.
+///
+/// Embedders typically forward the SCALE payloads through the
+/// `@parity/truapi` JS client for UI prompts, then return the boolean
+/// granted flag.
+///
+/// Threading: the Rust core invokes every callback on a background thread it
+/// owns, never the main thread. UI-decision callbacks
+/// (``navigateTo(url:)``, ``devicePermission(request:)``,
+/// ``remotePermission(request:)``, ``confirmUserAction(review:)``, and
+/// ``submitPreimage(value:)``) each run on their own thread from a blocking
+/// pool, so an implementation may safely block its calling thread (e.g. with
+/// `DispatchQueue.main.sync` or a semaphore) until the user decides; other
+/// TrUAPI traffic keeps flowing. The remaining callbacks (auth state,
+/// storage, session, chain, feature, theme, preimage lookups) run inline on
+/// the dispatcher thread and must return promptly without blocking.
+/// Any UI work MUST still hop to the main thread, e.g.
+/// `await MainActor.run { ... }` or `DispatchQueue.main.async { ... }`. Calling
+/// UIKit/WebKit off the main thread is undefined behaviour.
+public protocol HostBridge: AnyObject, Sendable {
+    /// Lifecycle logger. Marker is a stable slug, detail is free-form.
+    func onCoreLog(marker: String, detail: String)
+
+    /// Open a URL in the system browser. Invoked on a blocking-pool thread;
+    /// hop to the main thread to present UI. May block the calling thread if
+    /// the user has to approve the navigation.
+    func navigateTo(url: String) throws
+
+    /// Deliver a push notification (SCALE-encoded `HostPushNotificationRequest`)
+    /// and return the host-assigned notification id. Invoked on the dispatcher
+    /// thread; hop to the main thread for any UI work and return promptly.
+    func pushNotification(payload: Data) throws -> UInt32
+
+    /// Cancel a previously scheduled notification id.
+    func cancelNotification(id: UInt32) throws
+
+    /// Prompt for a device-level permission. Returns the granted flag. Invoked
+    /// on a blocking-pool thread; present the prompt on the main thread and
+    /// block the calling thread until the user decides. Blocking here does
+    /// not stall other TrUAPI traffic.
+    func devicePermission(request: Data) throws -> Bool
+
+    /// Prompt for a remote (product-scoped) permission bundle. Invoked on a
+    /// blocking-pool thread; present the prompt on the main thread and block
+    /// the calling thread until the user decides. Blocking here does not
+    /// stall other TrUAPI traffic.
+    func remotePermission(request: Data) throws -> Bool
+
+    /// Observe an auth state change. The core emits states only when they
+    /// actually change, in transition order: render `.pairing` as the pairing
+    /// QR UI, `.connected`/`.disconnected` as the account badge, and
+    /// `.loginFailed` as a retryable error. Report a user dismissal of the
+    /// pairing UI through ``TrUAPIHostCore/cancelLogin()``. Invoked on the
+    /// dispatcher thread; hand the state to the main thread and return
+    /// promptly.
+    func authStateChanged(state: AuthState)
+
+    /// Open a JSON-RPC chain connection and return a host-assigned id, or nil if unsupported.
+    func chainConnect(genesisHash: Data) throws -> UInt32?
+
+    /// Send one JSON-RPC request on a native chain connection.
+    func chainSend(connectionId: UInt32, request: String) throws
+
+    /// Close a native chain connection.
+    func chainClose(connectionId: UInt32) throws
+
+    /// Confirm one user-reviewed core action before it continues. `review` is
+    /// a SCALE-encoded `UserConfirmationReview`.
+    func confirmUserAction(review: Data) throws -> Bool
+
+    /// Submit a preimage through the host backend and return its key.
+    func submitPreimage(value: Data) throws -> Data
+
+    /// Return the current preimage value for `key`, or nil for a miss.
+    func lookupPreimage(key: Data) throws -> Data?
+
+    /// Return the current host theme.
+    func currentTheme() throws -> HostTheme
+
+    /// Answer a feature-support query. Invoked on the dispatcher thread; must
+    /// return promptly.
+    func featureSupported(request: Data) throws -> Bool
+
+    /// Scoped key-value storage for the Rust core.
+    var storage: HostStorageBackend { get }
+
+    /// Core-owned host-private storage for auth session, pairing identity,
+    /// and persisted permission decisions.
+    var coreStorage: HostCoreStorageBackend { get }
+}
+
+public extension HostBridge {
+    /// Default no-op logger. Override to plumb into your logging framework.
+    func onCoreLog(marker: String, detail: String) {}
+    func pushNotification(payload: Data) throws -> UInt32 { 0 }
+    func cancelNotification(id: UInt32) throws {}
+    func authStateChanged(state: AuthState) {}
+    func chainConnect(genesisHash: Data) throws -> UInt32? { nil }
+    func chainSend(connectionId: UInt32, request: String) throws {}
+    func chainClose(connectionId: UInt32) throws {}
+    func confirmUserAction(review: Data) throws -> Bool { false }
+    func submitPreimage(value: Data) throws -> Data { value }
+    func lookupPreimage(key: Data) throws -> Data? { nil }
+    func currentTheme() throws -> HostTheme { .dark }
+}
+
+/// Adapter that bridges the public `HostBridge` to the generated UniFFI
+/// `HostCallbacks` protocol. Kept private so the generated names never
+/// leak into consumers.
+private final class HostCallbackAdapter: HostCallbacks, @unchecked Sendable {
+    private let bridge: HostBridge
+
+    init(bridge: HostBridge) {
+        self.bridge = bridge
+    }
+
+    func onCoreLog(marker: String, detail: String) {
+        bridge.onCoreLog(marker: marker, detail: detail)
+    }
+
+    func navigateTo(url: String) throws {
+        try bridge.navigateTo(url: url)
+    }
+
+    func pushNotification(payload: Data) throws -> UInt32 {
+        try bridge.pushNotification(payload: payload)
+    }
+
+    func cancelNotification(id: UInt32) throws {
+        try bridge.cancelNotification(id: id)
+    }
+
+    func devicePermission(request: Data) throws -> Bool {
+        try bridge.devicePermission(request: request)
+    }
+
+    func remotePermission(request: Data) throws -> Bool {
+        try bridge.remotePermission(request: request)
+    }
+
+    func authStateChanged(state: AuthState) {
+        bridge.authStateChanged(state: state)
+    }
+
+    func coreStorageRead(key: Data) throws -> Data? {
+        try bridge.coreStorage.read(key: key)
+    }
+
+    func coreStorageWrite(key: Data, value: Data) throws {
+        try bridge.coreStorage.write(key: key, value: value)
+        LiveSessionStoreForwarder.notifySessionStoreChanged()
+    }
+
+    func coreStorageClear(key: Data) throws {
+        try bridge.coreStorage.clear(key: key)
+        LiveSessionStoreForwarder.notifySessionStoreChanged()
+    }
+
+    func chainConnect(genesisHash: Data) throws -> UInt32? {
+        try bridge.chainConnect(genesisHash: genesisHash)
+    }
+
+    func chainSend(connectionId: UInt32, request: String) throws {
+        try bridge.chainSend(connectionId: connectionId, request: request)
+    }
+
+    func chainClose(connectionId: UInt32) throws {
+        try bridge.chainClose(connectionId: connectionId)
+    }
+
+    func confirmUserAction(review: Data) throws -> Bool {
+        try bridge.confirmUserAction(review: review)
+    }
+
+    func submitPreimage(value: Data) throws -> Data {
+        try bridge.submitPreimage(value: value)
+    }
+
+    func lookupPreimage(key: Data) throws -> Data? {
+        try bridge.lookupPreimage(key: key)
+    }
+
+    func currentTheme() throws -> HostTheme {
+        try bridge.currentTheme()
+    }
+
+    func featureSupported(request: Data) throws -> Bool {
+        try bridge.featureSupported(request: request)
+    }
+
+    func localStorageRead(key: String) throws -> Data? {
+        try bridge.storage.read(key: key)
+    }
+
+    func localStorageWrite(key: String, value: Data) throws {
+        try bridge.storage.write(key: key, value: value)
+    }
+
+    func localStorageClear(key: String) throws {
+        try bridge.storage.clear(key: key)
+    }
+}
+
+/// Owning wrapper around the Rust-backed `NativeTrUApiCore`. Holds the bridge
+/// adapter alive for the lifetime of the core and exposes session +
+/// WS-bridge controls.
+///
+/// Hosts integrating with a `WKWebView`-based product call `startWsBridge`
+/// and pass the resulting `ws://127.0.0.1:<port>/?t=<token>` URL to the
+/// product via `LocalhostBridgeBootstrap.script(...)`. The product wires
+/// that URL into `@parity/truapi`'s `createWebSocketProvider`.
+public final class TrUAPIHostCore {
+    private let inner: NativeTrUApiCore
+    // Co-owns the adapter alongside the generated FfiConverter handle map,
+    // which is what actually keeps the callback object alive for the core.
+    private let callbackRetainer: HostCallbacks
+
+    public init(bridge: HostBridge, runtimeConfig: RuntimeConfig) throws {
+        let adapter = HostCallbackAdapter(bridge: bridge)
+        self.callbackRetainer = adapter
+        self.inner = try NativeTrUApiCore.withRuntimeConfig(
+            callbacks: adapter,
+            runtimeConfig: runtimeConfig.native
+        )
+        LiveSessionStoreForwarder.register(self)
+        notifySessionStoreChanged()
+    }
+
+    deinit {
+        LiveSessionStoreForwarder.unregister(self)
+    }
+
+    /// Start the localhost WebSocket bridge. Requires the `ws-bridge`
+    /// feature in the cdylib. Pair the returned `WsBridgeEndpoint` with
+    /// `LocalhostBridgeBootstrap.script(...)` to hand the URL to the
+    /// product page.
+    public func startWsBridge(bindPort: UInt16 = 0) throws -> WsBridgeEndpoint {
+        try inner.startWsBridge(bindPort: bindPort)
+    }
+
+    /// Stop the localhost WebSocket bridge (if running).
+    public func stopWsBridge() {
+        inner.stopWsBridge()
+    }
+
+    /// Core-owned logout/disconnect path. Best-effort notifies the SSO peer,
+    /// clears in-memory session state, clears the persisted session via
+    /// ``HostBridge/coreStorage``, and broadcasts `Disconnected` to active
+    /// account-status subscribers.
+    public func disconnect() {
+        inner.disconnect()
+    }
+
+    /// Notify the core that host-global session storage changed externally.
+    public func notifySessionStoreChanged() {
+        inner.notifySessionStoreChanged()
+    }
+
+    /// Cancel any in-flight login pairing (e.g. the user dismissed the
+    /// pairing UI). The bridge receives a `.disconnected` auth state
+    /// immediately and the pending login resolves as rejected. A no-op when
+    /// no login is in progress.
+    public func cancelLogin() {
+        inner.cancelLogin()
+    }
+
+    /// Read a stored permission authorization status without prompting.
+    /// `request` is a SCALE-encoded `PermissionAuthorizationRequest`.
+    public func permissionAuthorizationStatus(request: Data) throws -> NativePermissionAuthorizationStatus {
+        try inner.permissionAuthorizationStatus(payload: request)
+    }
+
+    /// Update a stored permission authorization status. `.notDetermined`
+    /// clears the stored value so the next product request prompts again.
+    public func setPermissionAuthorizationStatus(
+        request: Data,
+        status: NativePermissionAuthorizationStatus
+    ) throws {
+        try inner.setPermissionAuthorizationStatus(payload: request, status: status)
+    }
+
+    /// Push a host theme update to active TrUAPI theme subscriptions.
+    public func notifyThemeChanged(theme: HostTheme) {
+        inner.notifyThemeChanged(theme: theme)
+    }
+
+    /// Push a preimage lookup update to active subscriptions for `key`.
+    public func notifyPreimageChanged(key: Data, value: Data?) {
+        inner.notifyPreimageChanged(key: key, value: value)
+    }
+
+    /// Push a JSON-RPC response from a native chain connection into the core.
+    public func notifyChainResponse(connectionId: UInt32, json: String) {
+        inner.notifyChainResponse(connectionId: connectionId, json: json)
+    }
+
+    /// Notify the core that a native chain connection closed externally.
+    public func notifyChainClosed(connectionId: UInt32) {
+        inner.notifyChainClosed(connectionId: connectionId)
+    }
+}
+
+private final class WeakTrUAPIHostCore {
+    weak var value: TrUAPIHostCore?
+
+    init(_ value: TrUAPIHostCore) {
+        self.value = value
+    }
+}
+
+private enum LiveSessionStoreForwarder {
+    private static let lock = NSLock()
+    private static var cores: [ObjectIdentifier: WeakTrUAPIHostCore] = [:]
+
+    static func register(_ core: TrUAPIHostCore) {
+        lock.lock()
+        cores[ObjectIdentifier(core)] = WeakTrUAPIHostCore(core)
+        lock.unlock()
+    }
+
+    static func unregister(_ core: TrUAPIHostCore) {
+        lock.lock()
+        cores.removeValue(forKey: ObjectIdentifier(core))
+        lock.unlock()
+    }
+
+    static func notifySessionStoreChanged() {
+        let liveCores: [TrUAPIHostCore]
+
+        lock.lock()
+        cores = cores.filter { $0.value.value != nil }
+        liveCores = cores.values.compactMap(\.value)
+        lock.unlock()
+
+        for core in liveCores {
+            core.notifySessionStoreChanged()
+        }
+    }
+}
diff --git a/playground/src/components/DiagnosisView.tsx b/playground/src/components/DiagnosisView.tsx
index 0200a0b6..3ea76cf8 100644
--- a/playground/src/components/DiagnosisView.tsx
+++ b/playground/src/components/DiagnosisView.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { ServiceInfo } from "@/src/lib/services";
 import type { TestEntry, TestStatus } from "@/src/lib/auto-test";
 import {
@@ -80,6 +80,22 @@ export function DiagnosisView({
     [hasResults, isRunning, services, testResults],
   );
 
+  useEffect(() => {
+    if (!reportMarkdown) return;
+    if (typeof window === "undefined") return;
+    const params = new URLSearchParams(window.location.search);
+    try {
+      const e2e =
+        params.has("e2e") ||
+        window.__TRUAPI_PLAYGROUND_E2E__ === true ||
+        window.localStorage.getItem("truapi:playground:e2e") === "1";
+      if (!e2e) return;
+      window.localStorage.setItem("truapi:diagnosis-report", reportMarkdown);
+    } catch {
+      /* localStorage unavailable */
+    }
+  }, [reportMarkdown]);
+
   const handleCopyReport = async () => {
     try {
       await navigator.clipboard.writeText(reportMarkdown);
diff --git a/rust/crates/truapi-server/Cargo.toml b/rust/crates/truapi-server/Cargo.toml
index 6cecb5f6..1930f82d 100644
--- a/rust/crates/truapi-server/Cargo.toml
+++ b/rust/crates/truapi-server/Cargo.toml
@@ -6,10 +6,11 @@ description = "TrUAPI server runtime: dispatcher, frames, SCALE, streams"
 license = "MIT"
 
 [lib]
-crate-type = ["rlib", "cdylib"]
+crate-type = ["rlib", "cdylib", "staticlib"]
 
 [features]
 default = []
+ws-bridge = ["dep:tokio", "dep:tokio-tungstenite", "dep:rand"]
 
 [dependencies]
 truapi = { path = "../truapi" }
@@ -41,7 +42,12 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", default-features = false, features = ["registry", "std"] }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+futures = { version = "0.3", features = ["thread-pool"] }
+rand = { version = "0.8", optional = true }
 subxt-rpcs = { version = "0.50.1", default-features = false, features = ["native"] }
+tokio = { version = "1", features = ["rt-multi-thread", "net", "sync", "macros", "io-util"], optional = true }
+tokio-tungstenite = { version = "0.21", default-features = false, features = ["handshake"], optional = true }
+uniffi = "0.29.4"
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 js-sys = "0.3"
@@ -64,3 +70,7 @@ web-sys = { version = "0.3", features = [
 
 [target.'cfg(target_arch = "wasm32")'.dev-dependencies]
 wasm-bindgen-test = "0.3"
+
+[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
+tokio = { version = "1", features = ["rt-multi-thread", "net", "sync", "macros", "io-util", "time"] }
+tokio-tungstenite = { version = "0.21", default-features = false, features = ["connect"] }
diff --git a/rust/crates/truapi-server/src/chain_runtime.rs b/rust/crates/truapi-server/src/chain_runtime.rs
index bb8e2796..34534d83 100644
--- a/rust/crates/truapi-server/src/chain_runtime.rs
+++ b/rust/crates/truapi-server/src/chain_runtime.rs
@@ -489,11 +489,18 @@ impl ChainRuntime {
     ) -> Result<(), RuntimeFailure> {
         let method = "remote_chain_transaction_stop";
         let connection = self.connection_for(method, &request.genesis_hash).await?;
-        connection
+        if let Err(err) = connection
             .methods
             .transaction_v1_stop(&request.operation_id)
             .await
-            .map_err(|err| rpc_failure(method, err))
+        {
+            tracing::debug!(
+                ?err,
+                operation_id = request.operation_id,
+                "ignoring transaction stop failure"
+            );
+        }
+        Ok(())
     }
 
     #[instrument(skip_all, fields(runtime.method = "chain_runtime.connection_for", method = method))]
diff --git a/rust/crates/truapi-server/src/lib.rs b/rust/crates/truapi-server/src/lib.rs
index 4597a94e..80155417 100644
--- a/rust/crates/truapi-server/src/lib.rs
+++ b/rust/crates/truapi-server/src/lib.rs
@@ -6,6 +6,9 @@
 //! desktop shells.
 //!
 //! Host-facing bridges:
+//! - [`ws_bridge`] (feature `ws-bridge`): localhost WebSocket bridge for
+//!   native WebView hosts (Android/iOS).
+//! - [`native`]: UniFFI surface exposing `NativeTrUApiCore` + `HostCallbacks`.
 //! - [`wasm`] (wasm32 only): wasm-bindgen surface exposing `WasmHostCore`.
 
 #![forbid(unsafe_code)]
@@ -27,6 +30,12 @@ pub(crate) mod test_support;
 
 pub mod generated;
 
+#[cfg(all(not(target_arch = "wasm32"), feature = "ws-bridge"))]
+pub mod ws_bridge;
+
+#[cfg(not(target_arch = "wasm32"))]
+pub mod native;
+
 #[cfg(target_arch = "wasm32")]
 pub mod wasm;
 
@@ -35,5 +44,14 @@ pub use truapi_platform::{
     PermissionAuthorizationRequest, PermissionAuthorizationStatus, Platform, RuntimeConfig,
 };
 
+#[cfg(all(not(target_arch = "wasm32"), feature = "ws-bridge"))]
+pub use ws_bridge::*;
+
+#[cfg(not(target_arch = "wasm32"))]
+pub use native::*;
+
 #[cfg(target_arch = "wasm32")]
 pub use wasm::*;
+
+#[cfg(not(target_arch = "wasm32"))]
+uniffi::setup_scaffolding!();
diff --git a/rust/crates/truapi-server/src/native.rs b/rust/crates/truapi-server/src/native.rs
new file mode 100644
index 00000000..b09e3d7a
--- /dev/null
+++ b/rust/crates/truapi-server/src/native.rs
@@ -0,0 +1,1731 @@
+//! UniFFI-facing native bridge. Exposes [`NativeTrUApiCore`] and the
+//! [`HostCallbacks`] callback interface that iOS and Android call into.
+//!
+//! The native side builds a [`CallbackPlatform`] that adapts every
+//! [`truapi_platform::Platform`] trait to a corresponding callback. The
+//! resulting platform is fed into [`TrUApiCore::from_platform_with_config`] so the rest
+//! of the dispatcher pipeline behaves identically to the WS-bridge and wasm
+//! flavors.
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use futures::channel::mpsc;
+use futures::executor::ThreadPool;
+use futures::future::BoxFuture;
+use futures::stream::{self, BoxStream, StreamExt};
+use futures::task::SpawnExt;
+use parity_scale_codec::{Decode, Encode};
+use truapi::v01;
+use truapi_platform::{
+    AuthPresenter, ChainProvider, CoreStorage, CoreStorageKey, Features, HostInfo,
+    JsonRpcConnection, Navigation, Notifications, PermissionAuthorizationRequest,
+    PermissionAuthorizationStatus, Permissions, PlatformInfo, PreimageHost, ProductStorage,
+    RuntimeConfig, RuntimeConfigValidationError, ThemeHost, UserConfirmation,
+    UserConfirmationReview, async_trait,
+};
+
+use crate::core::TrUApiCore;
+use crate::subscription::Spawner;
+#[cfg(feature = "ws-bridge")]
+use crate::ws_bridge::{BridgeLogger, WsBridge, WsBridgeEndpoint, WsBridgeStartError};
+
+/// Native-friendly storage error. Mirrors the v0.1 wire shape so the
+/// callback surface stays SCALE-free.
+#[derive(Debug, Clone, thiserror::Error, uniffi::Error)]
+pub enum HostStorageError {
+    /// Quota exhausted.
+    #[error("storage quota exhausted")]
+    Full,
+    /// Catch-all.
+    #[error("{reason}")]
+    Unknown {
+        /// Human-readable failure reason.
+        reason: String,
+    },
+}
+
+impl From<HostStorageError> for v01::HostLocalStorageReadError {
+    fn from(err: HostStorageError) -> Self {
+        match err {
+            HostStorageError::Full => v01::HostLocalStorageReadError::Full,
+            HostStorageError::Unknown { reason } => {
+                v01::HostLocalStorageReadError::Unknown { reason }
+            }
+        }
+    }
+}
+
+/// Native-friendly rejection error returned by callback methods that map
+/// onto [`truapi::v01::GenericError`].
+#[derive(Debug, Clone, thiserror::Error, uniffi::Error)]
+pub enum HostRejection {
+    /// Caller rejected the operation.
+    #[error("{reason}")]
+    Rejected {
+        /// Human-readable rejection reason.
+        reason: String,
+    },
+}
+
+impl From<HostRejection> for v01::GenericError {
+    fn from(err: HostRejection) -> Self {
+        let HostRejection::Rejected { reason } = err;
+        v01::GenericError { reason }
+    }
+}
+
+impl From<v01::GenericError> for HostRejection {
+    fn from(err: v01::GenericError) -> Self {
+        HostRejection::Rejected { reason: err.reason }
+    }
+}
+
+/// Native-friendly navigation error.
+#[derive(Debug, Clone, thiserror::Error, uniffi::Error)]
+pub enum HostNavigateRejection {
+    /// User declined the navigation.
+    #[error("navigation denied by user")]
+    PermissionDenied,
+    /// Catch-all.
+    #[error("{reason}")]
+    Unknown {
+        /// Human-readable reason.
+        reason: String,
+    },
+}
+
+/// Native-friendly theme enum.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)]
+pub enum HostTheme {
+    /// Light host theme.
+    Light,
+    /// Dark host theme.
+    Dark,
+}
+
+impl From<HostTheme> for v01::ThemeVariant {
+    fn from(theme: HostTheme) -> Self {
+        match theme {
+            HostTheme::Light => v01::ThemeVariant::Light,
+            HostTheme::Dark => v01::ThemeVariant::Dark,
+        }
+    }
+}
+
+/// Native-friendly mirror of [`truapi_platform::SessionUiInfo`]: decoded
+/// session fields for host account UI, with byte arrays widened to `Vec<u8>`
+/// for the FFI surface.
+#[derive(Debug, Clone, PartialEq, Eq, uniffi::Record)]
+pub struct SessionUiInfo {
+    /// 32-byte sr25519 root public key of the active session.
+    pub public_key: Vec<u8>,
+    /// Wallet identity account id used for People-chain username lookup.
+    pub identity_account_id: Option<Vec<u8>>,
+    /// Short username from the People-chain identity record.
+    pub lite_username: Option<String>,
+    /// Fully qualified username from the People-chain identity record.
+    pub full_username: Option<String>,
+}
+
+impl From<truapi_platform::SessionUiInfo> for SessionUiInfo {
+    fn from(info: truapi_platform::SessionUiInfo) -> Self {
+        Self {
+            public_key: info.public_key.to_vec(),
+            identity_account_id: info.identity_account_id.map(|id| id.to_vec()),
+            lite_username: info.lite_username,
+            full_username: info.full_username,
+        }
+    }
+}
+
+/// Native-friendly mirror of [`truapi_platform::AuthState`]. The core emits
+/// these in transition order through `HostCallbacks::auth_state_changed`.
+#[derive(Debug, Clone, PartialEq, Eq, uniffi::Enum)]
+pub enum AuthState {
+    /// No active session and no login in progress.
+    Disconnected,
+    /// A login is in progress: present the pairing deeplink/QR.
+    Pairing {
+        /// Wallet pairing deeplink to render as a QR code or open directly.
+        deeplink: String,
+    },
+    /// A session is active.
+    Connected {
+        /// Decoded session fields for host account UI.
+        info: SessionUiInfo,
+    },
+    /// The last login attempt failed; show the reason and offer a retry.
+    LoginFailed {
+        /// Human-readable failure reason.
+        reason: String,
+    },
+}
+
+impl From<truapi_platform::AuthState> for AuthState {
+    fn from(state: truapi_platform::AuthState) -> Self {
+        match state {
+            truapi_platform::AuthState::Disconnected => AuthState::Disconnected,
+            truapi_platform::AuthState::Pairing { deeplink } => AuthState::Pairing { deeplink },
+            truapi_platform::AuthState::Connected(info) => {
+                AuthState::Connected { info: info.into() }
+            }
+            truapi_platform::AuthState::LoginFailed { reason } => AuthState::LoginFailed { reason },
+        }
+    }
+}
+
+/// Native-friendly SSO deeplink scheme.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)]
+pub enum NativePairingDeeplinkScheme {
+    /// Production Polkadot app.
+    PolkadotApp,
+    /// Development Polkadot app.
+    PolkadotAppDev,
+}
+
+impl NativePairingDeeplinkScheme {
+    fn as_str(self) -> &'static str {
+        match self {
+            NativePairingDeeplinkScheme::PolkadotApp => "polkadotapp",
+            NativePairingDeeplinkScheme::PolkadotAppDev => "polkadotappdev",
+        }
+    }
+}
+
+/// Native-friendly mirror of [`PermissionAuthorizationStatus`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)]
+pub enum NativePermissionAuthorizationStatus {
+    /// No persisted authorization exists.
+    NotDetermined,
+    /// Access is denied.
+    Denied,
+    /// Access is authorized.
+    Authorized,
+}
+
+impl From<PermissionAuthorizationStatus> for NativePermissionAuthorizationStatus {
+    fn from(status: PermissionAuthorizationStatus) -> Self {
+        match status {
+            PermissionAuthorizationStatus::NotDetermined => Self::NotDetermined,
+            PermissionAuthorizationStatus::Denied => Self::Denied,
+            PermissionAuthorizationStatus::Authorized => Self::Authorized,
+        }
+    }
+}
+
+impl From<NativePermissionAuthorizationStatus> for PermissionAuthorizationStatus {
+    fn from(status: NativePermissionAuthorizationStatus) -> Self {
+        match status {
+            NativePermissionAuthorizationStatus::NotDetermined => Self::NotDetermined,
+            NativePermissionAuthorizationStatus::Denied => Self::Denied,
+            NativePermissionAuthorizationStatus::Authorized => Self::Authorized,
+        }
+    }
+}
+
+/// Native runtime configuration supplied before product calls are handled.
+#[derive(Debug, Clone, uniffi::Record)]
+pub struct NativeRuntimeConfig {
+    /// Canonical product identifier used for account derivation.
+    pub product_id: String,
+    /// Host name shown by the wallet during SSO pairing.
+    pub host_name: String,
+    /// Optional host icon URL shown by the wallet during SSO pairing.
+    pub host_icon: Option<String>,
+    /// Optional host version shown by the wallet during SSO pairing.
+    pub host_version: Option<String>,
+    /// Optional platform/browser name shown by the wallet during SSO pairing.
+    pub platform_type: Option<String>,
+    /// Optional platform/browser version shown by the wallet during SSO pairing.
+    pub platform_version: Option<String>,
+    /// People-chain genesis hash. Must be exactly 32 bytes.
+    pub people_chain_genesis_hash: Vec<u8>,
+    /// Deeplink scheme used in pairing QR payloads.
+    pub pairing_deeplink_scheme: NativePairingDeeplinkScheme,
+}
+
+/// Native runtime config validation error.
+#[derive(Debug, Clone, thiserror::Error, uniffi::Error)]
+pub enum NativeRuntimeConfigError {
+    /// Required string field was empty or whitespace-only.
+    #[error("{field} must not be empty")]
+    EmptyField {
+        /// Field name.
+        field: String,
+    },
+    /// People-chain genesis hash was not exactly 32 bytes.
+    #[error("people_chain_genesis_hash must be exactly 32 bytes, got {actual}")]
+    InvalidPeopleChainGenesisHash {
+        /// Supplied byte length.
+        actual: u64,
+    },
+    /// Host icon URL could not be parsed.
+    #[error("host_icon must be an absolute HTTPS URL: {reason}")]
+    InvalidHostIcon {
+        /// Parse failure reason.
+        reason: String,
+    },
+    /// Host icon URL used a non-HTTPS scheme.
+    #[error("host_icon must use https scheme, got {scheme:?}")]
+    InsecureHostIcon {
+        /// Actual URL scheme.
+        scheme: String,
+    },
+    /// Pairing deeplink scheme included a URL separator.
+    #[error("pairing_deeplink_scheme must not include ://, got {scheme:?}")]
+    InvalidDeeplinkScheme {
+        /// Actual deeplink scheme value.
+        scheme: String,
+    },
+}
+
+impl TryFrom<NativeRuntimeConfig> for RuntimeConfig {
+    type Error = NativeRuntimeConfigError;
+
+    fn try_from(config: NativeRuntimeConfig) -> Result<Self, Self::Error> {
+        let people_chain_genesis_hash =
+            <[u8; 32]>::try_from(config.people_chain_genesis_hash.as_slice()).map_err(|_| {
+                NativeRuntimeConfigError::InvalidPeopleChainGenesisHash {
+                    actual: config.people_chain_genesis_hash.len() as u64,
+                }
+            })?;
+        Ok(Self::new(
+            config.product_id,
+            HostInfo {
+                name: config.host_name,
+                icon: config.host_icon,
+                version: config.host_version,
+            },
+            PlatformInfo {
+                kind: config.platform_type,
+                version: config.platform_version,
+            },
+            people_chain_genesis_hash,
+            config.pairing_deeplink_scheme.as_str().to_string(),
+        )?)
+    }
+}
+
+impl From<RuntimeConfigValidationError> for NativeRuntimeConfigError {
+    fn from(err: RuntimeConfigValidationError) -> Self {
+        match err {
+            RuntimeConfigValidationError::EmptyField { field } => Self::EmptyField {
+                field: field.to_string(),
+            },
+            RuntimeConfigValidationError::InvalidHostIcon { reason } => {
+                Self::InvalidHostIcon { reason }
+            }
+            RuntimeConfigValidationError::InsecureHostIcon { scheme } => {
+                Self::InsecureHostIcon { scheme }
+            }
+            RuntimeConfigValidationError::InvalidDeeplinkScheme { scheme } => {
+                Self::InvalidDeeplinkScheme { scheme }
+            }
+        }
+    }
+}
+
+impl From<HostNavigateRejection> for v01::HostNavigateToError {
+    fn from(err: HostNavigateRejection) -> Self {
+        match err {
+            HostNavigateRejection::PermissionDenied => v01::HostNavigateToError::PermissionDenied,
+            HostNavigateRejection::Unknown { reason } => {
+                v01::HostNavigateToError::Unknown { reason }
+            }
+        }
+    }
+}
+
+/// Callback surface that iOS and Android implement.
+///
+/// Threading contract: every callback is invoked on a background thread
+/// owned by the Rust core, never the host's main/UI thread. UI-decision
+/// callbacks (`navigate_to`, `device_permission`, `remote_permission`,
+/// the `confirm_*` family) plus the potentially slow `submit_preimage` run
+/// on the tokio blocking pool, so an implementation may block its calling
+/// thread until the user decides without stalling concurrent dispatches.
+/// All other callbacks run inline on the dispatcher thread and must return
+/// promptly; in particular `auth_state_changed` should only hand the state
+/// to the host UI thread, never wait for the user. As the one exception to
+/// the background-thread rule, `auth_state_changed` can also arrive
+/// synchronously on whichever thread calls `NativeTrUApiCore::cancel_login`.
+#[uniffi::export(callback_interface)]
+pub trait HostCallbacks: Send + Sync {
+    /// Lifecycle logger. Marker is a stable slug, detail is free-form.
+    fn on_core_log(&self, marker: String, detail: String);
+
+    /// Open a URL in the system browser.
+    fn navigate_to(&self, url: String) -> Result<(), HostNavigateRejection>;
+
+    /// Deliver a push notification. The payload is the SCALE-encoded
+    /// [`v01::HostPushNotificationRequest`].
+    fn push_notification(&self, payload: Vec<u8>) -> Result<u32, HostRejection>;
+
+    /// Cancel a notification by id.
+    fn cancel_notification(&self, id: u32) -> Result<(), HostRejection>;
+
+    /// Prompt the user for a device-level permission (camera, mic, ...).
+    /// `request` is the SCALE-encoded
+    /// [`v01::HostDevicePermissionRequest`]; the host returns whether the
+    /// permission was granted.
+    fn device_permission(&self, request: Vec<u8>) -> Result<bool, HostRejection>;
+
+    /// Prompt the user for a remote (product-scoped) permission bundle.
+    /// `request` is the SCALE-encoded [`v01::RemotePermissionRequest`].
+    fn remote_permission(&self, request: Vec<u8>) -> Result<bool, HostRejection>;
+
+    /// Observe an auth state change. Emitted only when the state actually
+    /// changes, in transition order: render `Pairing` as the pairing QR UI,
+    /// `Connected`/`Disconnected` as the account badge, `LoginFailed` as a
+    /// retryable error. User cancellation is reported through
+    /// `NativeTrUApiCore.cancel_login()`.
+    fn auth_state_changed(&self, state: AuthState);
+
+    /// Read a core-owned host-private storage slot. `key` is a SCALE-encoded
+    /// [`CoreStorageKey`].
+    fn core_storage_read(&self, key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection>;
+
+    /// Persist a core-owned host-private storage slot. `key` is a
+    /// SCALE-encoded [`CoreStorageKey`].
+    fn core_storage_write(&self, key: Vec<u8>, value: Vec<u8>) -> Result<(), HostRejection>;
+
+    /// Clear a core-owned host-private storage slot. `key` is a SCALE-encoded
+    /// [`CoreStorageKey`].
+    fn core_storage_clear(&self, key: Vec<u8>) -> Result<(), HostRejection>;
+
+    /// Open a JSON-RPC connection for a chain. Return a host-assigned
+    /// connection id, or `None` when unsupported.
+    fn chain_connect(&self, genesis_hash: Vec<u8>) -> Result<Option<u32>, HostRejection>;
+
+    /// Send one JSON-RPC request over a previously opened chain connection.
+    fn chain_send(&self, connection_id: u32, request: String) -> Result<(), HostRejection>;
+
+    /// Close a previously opened chain connection.
+    fn chain_close(&self, connection_id: u32) -> Result<(), HostRejection>;
+
+    /// Confirm one user-reviewed core action. `review` is a SCALE-encoded
+    /// [`UserConfirmationReview`].
+    fn confirm_user_action(&self, review: Vec<u8>) -> Result<bool, HostRejection>;
+
+    /// Submit the preimage through the host backend and return its key.
+    fn submit_preimage(&self, value: Vec<u8>) -> Result<Vec<u8>, HostRejection>;
+
+    /// Look up one preimage value by key. The native shim emits this as the
+    /// current item in its subscription stream.
+    fn lookup_preimage(&self, key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection>;
+
+    /// Current host theme. The native shim emits this as the current item in
+    /// its subscription stream.
+    fn current_theme(&self) -> Result<HostTheme, HostRejection>;
+
+    /// Answer a feature-support query. `request` is the SCALE-encoded
+    /// [`HostFeatureSupportedRequest`].
+    fn feature_supported(&self, request: Vec<u8>) -> Result<bool, HostRejection>;
+
+    /// Read a value from the host's scoped key-value store.
+    fn local_storage_read(&self, key: String) -> Result<Option<Vec<u8>>, HostStorageError>;
+    /// Write a value to the host's scoped key-value store.
+    fn local_storage_write(&self, key: String, value: Vec<u8>) -> Result<(), HostStorageError>;
+    /// Clear a value from the host's scoped key-value store.
+    fn local_storage_clear(&self, key: String) -> Result<(), HostStorageError>;
+}
+
+/// UniFFI object exposing the TrUAPI core to native hosts.
+#[derive(uniffi::Object)]
+pub struct NativeTrUApiCore {
+    core: Arc<TrUApiCore>,
+    events: Arc<NativeEventBus>,
+    #[cfg(feature = "ws-bridge")]
+    callbacks: Arc<dyn HostCallbacks>,
+    #[cfg(feature = "ws-bridge")]
+    bridge: std::sync::Mutex<Option<WsBridge>>,
+}
+
+#[uniffi::export]
+impl NativeTrUApiCore {
+    /// Construct the core with explicit product and pairing runtime config.
+    #[uniffi::constructor]
+    pub fn with_runtime_config(
+        callbacks: Box<dyn HostCallbacks>,
+        runtime_config: NativeRuntimeConfig,
+    ) -> Result<Arc<Self>, NativeRuntimeConfigError> {
+        Ok(native_core_from_platform_config(
+            callbacks,
+            runtime_config.try_into()?,
+        ))
+    }
+
+    /// Core-owned logout/disconnect. Best-effort notifies the SSO peer when
+    /// the session has channel material, then clears in-memory and persisted
+    /// session state.
+    pub fn disconnect(&self) {
+        self.core.disconnect();
+    }
+
+    /// Notify this core that host-global session storage changed outside a
+    /// direct core write/clear. Native hosts call this after cross-process or
+    /// platform storage notifications so the core re-reads `CoreStorage`.
+    pub fn notify_session_store_changed(&self) {
+        self.core.notify_session_store_changed();
+    }
+
+    /// Cancel any in-flight `request_login` pairing (e.g. the user dismissed
+    /// the pairing UI). The host receives a `Disconnected` auth state
+    /// immediately and the pending login resolves to `Rejected`. A no-op
+    /// when no login is in progress.
+    pub fn cancel_login(&self) {
+        self.core.cancel_login();
+    }
+
+    /// Read a stored permission authorization status without prompting.
+    /// `payload` is a SCALE-encoded `PermissionAuthorizationRequest`.
+    pub fn permission_authorization_status(
+        &self,
+        payload: Vec<u8>,
+    ) -> Result<NativePermissionAuthorizationStatus, HostRejection> {
+        let request = decode_permission_authorization_request(&payload)?;
+        let status =
+            futures::executor::block_on(self.core.permission_authorization_status(request))?;
+        Ok(status.into())
+    }
+
+    /// Update a stored permission authorization status. Passing
+    /// `.notDetermined` clears the stored value so the next product request
+    /// prompts again.
+    pub fn set_permission_authorization_status(
+        &self,
+        payload: Vec<u8>,
+        status: NativePermissionAuthorizationStatus,
+    ) -> Result<(), HostRejection> {
+        let request = decode_permission_authorization_request(&payload)?;
+        futures::executor::block_on(
+            self.core
+                .set_permission_authorization_status(request, status.into()),
+        )?;
+        Ok(())
+    }
+
+    /// Push a host theme update to active TrUAPI theme subscriptions.
+    pub fn notify_theme_changed(&self, theme: HostTheme) {
+        self.events.notify_theme_changed(theme.into());
+    }
+
+    /// Push a preimage lookup update to active subscriptions for `key`.
+    ///
+    /// `value == None` represents a known miss; `Some(bytes)` represents the
+    /// current preimage value.
+    pub fn notify_preimage_changed(&self, key: Vec<u8>, value: Option<Vec<u8>>) {
+        self.events.notify_preimage_changed(&key, value);
+    }
+
+    /// Push a JSON-RPC response from a native chain connection into the core.
+    pub fn notify_chain_response(&self, connection_id: u32, json: String) {
+        self.events.notify_chain_response(connection_id, json);
+    }
+
+    /// Notify the core that a native chain connection closed externally.
+    pub fn notify_chain_closed(&self, connection_id: u32) {
+        self.events.notify_chain_closed(connection_id);
+    }
+}
+
+/// Set the live log level (`off`/`error`/`warn`/`info`/`debug`/`trace`) for
+/// the `tracing` output, which on native routes to stderr (system logs on
+/// iOS/Android). Most native diagnostics flow through `on_core_log` instead;
+/// this controls the cross-platform `tracing` events shared with wasm.
+#[uniffi::export]
+pub fn set_log_level(level: String) {
+    crate::logging::set_level_from_str(&level);
+}
+
+fn decode_permission_authorization_request(
+    payload: &[u8],
+) -> Result<PermissionAuthorizationRequest, HostRejection> {
+    PermissionAuthorizationRequest::decode(&mut &*payload).map_err(|err| HostRejection::Rejected {
+        reason: format!("permission authorization request did not decode: {err}"),
+    })
+}
+
+fn native_core_from_platform_config(
+    callbacks: Box<dyn HostCallbacks>,
+    runtime_config: RuntimeConfig,
+) -> Arc<NativeTrUApiCore> {
+    crate::logging::init();
+    let callbacks: Arc<dyn HostCallbacks> = callbacks.into();
+    callbacks.on_core_log(
+        "truapi.native.core.boot".to_string(),
+        "core ready".to_string(),
+    );
+
+    let events = Arc::new(NativeEventBus::default());
+    let platform = Arc::new(CallbackPlatform {
+        callbacks: callbacks.clone(),
+        events: events.clone(),
+    });
+    let spawner = native_thread_pool_spawner(&callbacks);
+    Arc::new(NativeTrUApiCore {
+        core: Arc::new(TrUApiCore::from_platform_with_config(
+            platform,
+            runtime_config,
+            spawner,
+        )),
+        events,
+        #[cfg(feature = "ws-bridge")]
+        callbacks,
+        #[cfg(feature = "ws-bridge")]
+        bridge: std::sync::Mutex::new(None),
+    })
+}
+
+#[cfg(feature = "ws-bridge")]
+#[uniffi::export]
+impl NativeTrUApiCore {
+    /// Start the localhost WebSocket bridge. Returns the descriptor the
+    /// host hands to the product so it can dial back in.
+    pub fn start_ws_bridge(&self, bind_port: u16) -> Result<WsBridgeEndpoint, WsBridgeStartError> {
+        let mut guard = self.bridge.lock().unwrap();
+        if guard.is_some() {
+            return Err(WsBridgeStartError::AlreadyRunning);
+        }
+        let logger: BridgeLogger = {
+            let callbacks = self.callbacks.clone();
+            Arc::new(move |marker: &str, detail: &str| {
+                callbacks.on_core_log(marker.to_string(), detail.to_string());
+            })
+        };
+        let (bridge, endpoint) = WsBridge::start(bind_port, self.core.clone(), logger)?;
+        *guard = Some(bridge);
+        Ok(endpoint)
+    }
+
+    /// Stop the localhost WebSocket bridge (if running).
+    pub fn stop_ws_bridge(&self) {
+        if let Some(mut bridge) = self.bridge.lock().unwrap().take() {
+            bridge.stop();
+        }
+    }
+}
+
+/// Build a [`Spawner`] backed by a shared `futures::executor::ThreadPool`.
+/// The pool is sized at the default (one worker per logical CPU). Falls
+/// back to a thread-per-subscription spawner if the pool fails to build,
+/// which only ever happens if the host has no available threads at all.
+fn native_thread_pool_spawner(callbacks: &Arc<dyn HostCallbacks>) -> Spawner {
+    match ThreadPool::new() {
+        Ok(pool) => {
+            let callbacks = callbacks.clone();
+            Arc::new(move |fut: BoxFuture<'static, ()>| {
+                if let Err(err) = pool.spawn(fut) {
+                    callbacks.on_core_log(
+                        "truapi.native.core.subscription.spawn_failed".to_string(),
+                        format!("{err}"),
+                    );
+                }
+            })
+        }
+        Err(err) => {
+            callbacks.on_core_log(
+                "truapi.native.core.subscription.pool_unavailable".to_string(),
+                format!("{err}; falling back to thread-per-subscription"),
+            );
+            crate::subscription::thread_per_subscription_spawner()
+        }
+    }
+}
+
+struct CallbackPlatform {
+    callbacks: Arc<dyn HostCallbacks>,
+    events: Arc<NativeEventBus>,
+}
+
+/// Run a host callback that may block awaiting a user decision.
+///
+/// UI-decision callbacks are allowed to block their calling thread until the
+/// user decides. Running them inline would stall the single-threaded
+/// WS-bridge dispatcher (and deadlock if the decision UI itself issues a
+/// TrUAPI call), so inside a tokio runtime the callback is moved to the
+/// blocking pool. Outside a tokio context the callback runs inline.
+async fn run_blocking_callback<T, F>(callback: F) -> T
+where
+    T: Send + 'static,
+    F: FnOnce() -> T + Send + 'static,
+{
+    #[cfg(feature = "ws-bridge")]
+    if let Ok(handle) = tokio::runtime::Handle::try_current() {
+        return handle
+            .spawn_blocking(callback)
+            .await
+            .expect("blocking host callback panicked");
+    }
+    callback()
+}
+
+fn is_ios_diagnosis_e2e() -> bool {
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        std::env::var("TRUAPI_IOS_E2E_AUTORUN_DIAGNOSIS")
+            .ok()
+            .as_deref()
+            == Some("1")
+    }
+    #[cfg(target_arch = "wasm32")]
+    {
+        false
+    }
+}
+
+#[derive(Default)]
+struct NativeEventBus {
+    theme_changes: Mutex<Vec<mpsc::UnboundedSender<Result<v01::ThemeVariant, v01::GenericError>>>>,
+    preimage_changes: Mutex<Vec<PreimageSubscription>>,
+    chain_responses: Mutex<HashMap<u32, mpsc::UnboundedSender<String>>>,
+}
+
+struct PreimageSubscription {
+    key: Vec<u8>,
+    tx: mpsc::UnboundedSender<Result<Option<Vec<u8>>, v01::GenericError>>,
+}
+
+impl NativeEventBus {
+    fn subscribe_theme(
+        &self,
+        current: Result<v01::ThemeVariant, v01::GenericError>,
+    ) -> BoxStream<'static, Result<v01::ThemeVariant, v01::GenericError>> {
+        let (tx, rx) = mpsc::unbounded();
+        self.theme_changes
+            .lock()
+            .expect("native theme subscribers mutex poisoned")
+            .push(tx);
+        stream::once(async move { current }).chain(rx).boxed()
+    }
+
+    fn notify_theme_changed(&self, theme: v01::ThemeVariant) {
+        self.theme_changes
+            .lock()
+            .expect("native theme subscribers mutex poisoned")
+            .retain(|tx| tx.unbounded_send(Ok(theme)).is_ok());
+    }
+
+    fn subscribe_preimage(
+        &self,
+        key: Vec<u8>,
+        current: Result<Option<Vec<u8>>, v01::GenericError>,
+    ) -> BoxStream<'static, Result<Option<Vec<u8>>, v01::GenericError>> {
+        let (tx, rx) = mpsc::unbounded();
+        self.preimage_changes
+            .lock()
+            .expect("native preimage subscribers mutex poisoned")
+            .push(PreimageSubscription { key, tx });
+        stream::once(async move { current }).chain(rx).boxed()
+    }
+
+    fn notify_preimage_changed(&self, key: &[u8], value: Option<Vec<u8>>) {
+        self.preimage_changes
+            .lock()
+            .expect("native preimage subscribers mutex poisoned")
+            .retain(|sub| {
+                if sub.key != key {
+                    return true;
+                }
+                sub.tx.unbounded_send(Ok(value.clone())).is_ok()
+            });
+    }
+
+    fn register_chain(&self, connection_id: u32) -> mpsc::UnboundedReceiver<String> {
+        let (tx, rx) = mpsc::unbounded();
+        self.chain_responses
+            .lock()
+            .expect("native chain subscribers mutex poisoned")
+            .insert(connection_id, tx);
+        rx
+    }
+
+    fn notify_chain_response(&self, connection_id: u32, json: String) {
+        let mut responses = self
+            .chain_responses
+            .lock()
+            .expect("native chain subscribers mutex poisoned");
+        let Some(tx) = responses.get(&connection_id) else {
+            return;
+        };
+        if tx.unbounded_send(json).is_err() {
+            responses.remove(&connection_id);
+        }
+    }
+
+    fn notify_chain_closed(&self, connection_id: u32) {
+        self.chain_responses
+            .lock()
+            .expect("native chain subscribers mutex poisoned")
+            .remove(&connection_id);
+    }
+}
+
+#[async_trait]
+impl Navigation for CallbackPlatform {
+    async fn navigate_to(&self, url: String) -> Result<(), v01::HostNavigateToError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.navigate_to".to_string(),
+            url.clone(),
+        );
+        let callbacks = self.callbacks.clone();
+        run_blocking_callback(move || callbacks.navigate_to(url))
+            .await
+            .map_err(Into::into)
+    }
+}
+
+#[async_trait]
+impl Notifications for CallbackPlatform {
+    async fn push_notification(
+        &self,
+        notification: v01::HostPushNotificationRequest,
+    ) -> Result<v01::HostPushNotificationResponse, v01::GenericError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.push_notification".to_string(),
+            notification.text.clone(),
+        );
+        if is_ios_diagnosis_e2e() {
+            return Ok(v01::HostPushNotificationResponse { id: 1 });
+        }
+
+        let callbacks = self.callbacks.clone();
+        let payload = notification.encode();
+        let id = run_blocking_callback(move || callbacks.push_notification(payload))
+            .await
+            .map_err(v01::GenericError::from)?;
+        Ok(v01::HostPushNotificationResponse { id })
+    }
+
+    async fn cancel_notification(&self, id: u32) -> Result<(), v01::GenericError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.cancel_notification".to_string(),
+            id.to_string(),
+        );
+        self.callbacks
+            .cancel_notification(id)
+            .map_err(v01::GenericError::from)
+    }
+}
+
+#[async_trait]
+impl Permissions for CallbackPlatform {
+    async fn device_permission(
+        &self,
+        request: v01::HostDevicePermissionRequest,
+    ) -> Result<v01::HostDevicePermissionResponse, v01::GenericError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.device_permission".to_string(),
+            format!("{request}"),
+        );
+        if is_ios_diagnosis_e2e() {
+            return Ok(v01::HostDevicePermissionResponse { granted: true });
+        }
+
+        let callbacks = self.callbacks.clone();
+        let payload = request.encode();
+        let granted = run_blocking_callback(move || callbacks.device_permission(payload))
+            .await
+            .map_err(v01::GenericError::from)?;
+        Ok(v01::HostDevicePermissionResponse { granted })
+    }
+
+    async fn remote_permission(
+        &self,
+        request: v01::RemotePermissionRequest,
+    ) -> Result<v01::RemotePermissionResponse, v01::GenericError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.remote_permission".to_string(),
+            format!("{request}"),
+        );
+        let callbacks = self.callbacks.clone();
+        let payload = request.encode();
+        let granted = run_blocking_callback(move || callbacks.remote_permission(payload))
+            .await
+            .map_err(v01::GenericError::from)?;
+        Ok(v01::RemotePermissionResponse { granted })
+    }
+}
+
+#[async_trait]
+impl Features for CallbackPlatform {
+    async fn feature_supported(
+        &self,
+        request: v01::HostFeatureSupportedRequest,
+    ) -> Result<v01::HostFeatureSupportedResponse, v01::GenericError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.feature_supported".to_string(),
+            format!("{request:?}"),
+        );
+        if is_ios_diagnosis_e2e() {
+            return Ok(v01::HostFeatureSupportedResponse { supported: true });
+        }
+
+        let callbacks = self.callbacks.clone();
+        let payload = request.encode();
+        let supported = run_blocking_callback(move || callbacks.feature_supported(payload))
+            .await
+            .map_err(v01::GenericError::from)?;
+        Ok(v01::HostFeatureSupportedResponse { supported })
+    }
+}
+
+#[async_trait]
+impl ProductStorage for CallbackPlatform {
+    async fn read(&self, key: String) -> Result<Option<Vec<u8>>, v01::HostLocalStorageReadError> {
+        self.callbacks.local_storage_read(key).map_err(Into::into)
+    }
+
+    async fn write(
+        &self,
+        key: String,
+        value: Vec<u8>,
+    ) -> Result<(), v01::HostLocalStorageReadError> {
+        self.callbacks
+            .local_storage_write(key, value)
+            .map_err(Into::into)
+    }
+
+    async fn clear(&self, key: String) -> Result<(), v01::HostLocalStorageReadError> {
+        self.callbacks.local_storage_clear(key).map_err(Into::into)
+    }
+}
+
+#[async_trait]
+impl CoreStorage for CallbackPlatform {
+    async fn read_core_storage(
+        &self,
+        key: CoreStorageKey,
+    ) -> Result<Option<Vec<u8>>, v01::GenericError> {
+        self.callbacks
+            .core_storage_read(key.encode())
+            .map_err(v01::GenericError::from)
+    }
+
+    async fn write_core_storage(
+        &self,
+        key: CoreStorageKey,
+        value: Vec<u8>,
+    ) -> Result<(), v01::GenericError> {
+        self.callbacks
+            .core_storage_write(key.encode(), value)
+            .map_err(v01::GenericError::from)
+    }
+
+    async fn clear_core_storage(&self, key: CoreStorageKey) -> Result<(), v01::GenericError> {
+        self.callbacks
+            .core_storage_clear(key.encode())
+            .map_err(v01::GenericError::from)
+    }
+}
+
+struct NativeJsonRpcConnection {
+    id: u32,
+    callbacks: Arc<dyn HostCallbacks>,
+    events: Arc<NativeEventBus>,
+    response_rx: Mutex<Option<mpsc::UnboundedReceiver<String>>>,
+    closed: AtomicBool,
+}
+
+impl JsonRpcConnection for NativeJsonRpcConnection {
+    fn send(&self, request: String) {
+        if self.closed.load(Ordering::Relaxed) {
+            return;
+        }
+        if let Err(err) = self.callbacks.chain_send(self.id, request) {
+            self.callbacks.on_core_log(
+                "truapi.native.callback.chain_send_failed".to_string(),
+                err.to_string(),
+            );
+        }
+    }
+
+    fn responses(&self) -> BoxStream<'static, String> {
+        let mut guard = self.response_rx.lock().unwrap();
+        match guard.take() {
+            Some(rx) => rx.boxed(),
+            None => {
+                self.callbacks.on_core_log(
+                    "truapi.native.chain.responses_reused".to_string(),
+                    "responses() called more than once".to_string(),
+                );
+                stream::empty().boxed()
+            }
+        }
+    }
+
+    fn close(&self) {
+        if self.closed.swap(true, Ordering::Relaxed) {
+            return;
+        }
+        self.events.notify_chain_closed(self.id);
+        if let Err(err) = self.callbacks.chain_close(self.id) {
+            self.callbacks.on_core_log(
+                "truapi.native.callback.chain_close_failed".to_string(),
+                err.to_string(),
+            );
+        }
+    }
+}
+
+impl Drop for NativeJsonRpcConnection {
+    fn drop(&mut self) {
+        self.close();
+    }
+}
+
+#[async_trait]
+impl ChainProvider for CallbackPlatform {
+    async fn connect(
+        &self,
+        genesis_hash: Vec<u8>,
+    ) -> Result<Box<dyn JsonRpcConnection>, v01::GenericError> {
+        let Some(connection_id) = self
+            .callbacks
+            .chain_connect(genesis_hash)
+            .map_err(v01::GenericError::from)?
+        else {
+            return Err(v01::GenericError {
+                reason: "chain provider unavailable".to_string(),
+            });
+        };
+        let response_rx = self.events.register_chain(connection_id);
+        Ok(Box::new(NativeJsonRpcConnection {
+            id: connection_id,
+            callbacks: self.callbacks.clone(),
+            events: self.events.clone(),
+            response_rx: Mutex::new(Some(response_rx)),
+            closed: AtomicBool::new(false),
+        }))
+    }
+}
+
+impl AuthPresenter for CallbackPlatform {
+    fn auth_state_changed(&self, state: truapi_platform::AuthState) {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.auth_state_changed".to_string(),
+            String::new(),
+        );
+        self.callbacks.auth_state_changed(state.into());
+    }
+}
+
+#[async_trait]
+impl UserConfirmation for CallbackPlatform {
+    async fn confirm_user_action(
+        &self,
+        review: UserConfirmationReview,
+    ) -> Result<bool, v01::GenericError> {
+        self.callbacks.on_core_log(
+            "truapi.native.callback.confirm_user_action".to_string(),
+            String::new(),
+        );
+        let callbacks = self.callbacks.clone();
+        let payload = review.encode();
+        run_blocking_callback(move || callbacks.confirm_user_action(payload))
+            .await
+            .map_err(v01::GenericError::from)
+    }
+}
+
+impl ThemeHost for CallbackPlatform {
+    fn subscribe_theme(&self) -> BoxStream<'static, Result<v01::ThemeVariant, v01::GenericError>> {
+        let current = self
+            .callbacks
+            .current_theme()
+            .map(v01::ThemeVariant::from)
+            .map_err(v01::GenericError::from);
+        self.events.subscribe_theme(current)
+    }
+}
+
+#[async_trait]
+impl PreimageHost for CallbackPlatform {
+    async fn submit_preimage(&self, value: Vec<u8>) -> Result<Vec<u8>, v01::PreimageSubmitError> {
+        let callbacks = self.callbacks.clone();
+        run_blocking_callback(move || callbacks.submit_preimage(value))
+            .await
+            .map_err(|err| v01::PreimageSubmitError::Unknown {
+                reason: err.to_string(),
+            })
+    }
+
+    fn lookup_preimage(
+        &self,
+        key: Vec<u8>,
+    ) -> BoxStream<'static, Result<Option<Vec<u8>>, v01::GenericError>> {
+        let current = self
+            .callbacks
+            .lookup_preimage(key.clone())
+            .map_err(v01::GenericError::from);
+        self.events.subscribe_preimage(key, current)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    type PreimageFixtureEntries = Vec<(Vec<u8>, Option<Vec<u8>>)>;
+
+    struct EventCallbacks {
+        theme: Mutex<HostTheme>,
+        preimages: Mutex<PreimageFixtureEntries>,
+        auth_states: Mutex<Vec<AuthState>>,
+        chain_id: Mutex<Option<u32>>,
+        chain_connects: Mutex<Vec<Vec<u8>>>,
+        chain_sends: Mutex<Vec<(u32, String)>>,
+        chain_closes: Mutex<Vec<u32>>,
+    }
+
+    impl EventCallbacks {
+        fn new() -> Self {
+            Self {
+                theme: Mutex::new(HostTheme::Light),
+                preimages: Mutex::new(Vec::new()),
+                auth_states: Mutex::new(Vec::new()),
+                chain_id: Mutex::new(None),
+                chain_connects: Mutex::new(Vec::new()),
+                chain_sends: Mutex::new(Vec::new()),
+                chain_closes: Mutex::new(Vec::new()),
+            }
+        }
+    }
+
+    impl HostCallbacks for EventCallbacks {
+        fn on_core_log(&self, _marker: String, _detail: String) {}
+        fn navigate_to(&self, _url: String) -> Result<(), HostNavigateRejection> {
+            Ok(())
+        }
+        fn push_notification(&self, _payload: Vec<u8>) -> Result<u32, HostRejection> {
+            Ok(0)
+        }
+        fn cancel_notification(&self, _id: u32) -> Result<(), HostRejection> {
+            Ok(())
+        }
+        fn device_permission(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+            Ok(false)
+        }
+        fn remote_permission(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+            Ok(false)
+        }
+        fn auth_state_changed(&self, state: AuthState) {
+            self.auth_states
+                .lock()
+                .expect("auth state mutex poisoned")
+                .push(state);
+        }
+        fn core_storage_read(&self, _key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection> {
+            Ok(None)
+        }
+        fn core_storage_write(&self, _key: Vec<u8>, _value: Vec<u8>) -> Result<(), HostRejection> {
+            Ok(())
+        }
+        fn core_storage_clear(&self, _key: Vec<u8>) -> Result<(), HostRejection> {
+            Ok(())
+        }
+        fn chain_connect(&self, genesis_hash: Vec<u8>) -> Result<Option<u32>, HostRejection> {
+            self.chain_connects
+                .lock()
+                .expect("chain connects mutex poisoned")
+                .push(genesis_hash);
+            Ok(*self.chain_id.lock().expect("chain id mutex poisoned"))
+        }
+        fn chain_send(&self, connection_id: u32, request: String) -> Result<(), HostRejection> {
+            self.chain_sends
+                .lock()
+                .expect("chain sends mutex poisoned")
+                .push((connection_id, request));
+            Ok(())
+        }
+        fn chain_close(&self, connection_id: u32) -> Result<(), HostRejection> {
+            self.chain_closes
+                .lock()
+                .expect("chain closes mutex poisoned")
+                .push(connection_id);
+            Ok(())
+        }
+        fn confirm_user_action(&self, _review: Vec<u8>) -> Result<bool, HostRejection> {
+            Ok(false)
+        }
+        fn submit_preimage(&self, value: Vec<u8>) -> Result<Vec<u8>, HostRejection> {
+            Ok(value)
+        }
+        fn lookup_preimage(&self, key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection> {
+            Ok(self
+                .preimages
+                .lock()
+                .expect("preimage map mutex poisoned")
+                .iter()
+                .find(|(stored_key, _)| stored_key == &key)
+                .and_then(|(_, value)| value.clone()))
+        }
+        fn current_theme(&self) -> Result<HostTheme, HostRejection> {
+            Ok(*self.theme.lock().expect("theme mutex poisoned"))
+        }
+        fn feature_supported(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+            Ok(false)
+        }
+        fn local_storage_read(&self, _key: String) -> Result<Option<Vec<u8>>, HostStorageError> {
+            Ok(None)
+        }
+        fn local_storage_write(
+            &self,
+            _key: String,
+            _value: Vec<u8>,
+        ) -> Result<(), HostStorageError> {
+            Ok(())
+        }
+        fn local_storage_clear(&self, _key: String) -> Result<(), HostStorageError> {
+            Ok(())
+        }
+    }
+
+    fn event_platform() -> (Arc<EventCallbacks>, Arc<NativeEventBus>, CallbackPlatform) {
+        let callbacks = Arc::new(EventCallbacks::new());
+        let events = Arc::new(NativeEventBus::default());
+        let platform = CallbackPlatform {
+            callbacks: callbacks.clone(),
+            events: events.clone(),
+        };
+        (callbacks, events, platform)
+    }
+
+    #[test]
+    fn native_auth_presenter_forwards_states_across_the_ffi_mirror() {
+        let (callbacks, _events, platform) = event_platform();
+
+        platform.auth_state_changed(truapi_platform::AuthState::Pairing {
+            deeplink: "polkadotapp://pair?handshake=00".to_string(),
+        });
+        platform.auth_state_changed(truapi_platform::AuthState::Connected(
+            truapi_platform::SessionUiInfo {
+                public_key: [7; 32],
+                identity_account_id: None,
+                lite_username: Some("alice".to_string()),
+                full_username: None,
+            },
+        ));
+        platform.auth_state_changed(truapi_platform::AuthState::Disconnected);
+
+        assert_eq!(
+            callbacks
+                .auth_states
+                .lock()
+                .expect("auth state mutex poisoned")
+                .as_slice(),
+            &[
+                AuthState::Pairing {
+                    deeplink: "polkadotapp://pair?handshake=00".to_string(),
+                },
+                AuthState::Connected {
+                    info: SessionUiInfo {
+                        public_key: vec![7; 32],
+                        identity_account_id: None,
+                        lite_username: Some("alice".to_string()),
+                        full_username: None,
+                    },
+                },
+                AuthState::Disconnected,
+            ]
+        );
+    }
+
+    #[test]
+    fn native_theme_subscription_emits_current_then_notified_changes() {
+        let (callbacks, events, platform) = event_platform();
+        let mut stream = platform.subscribe_theme();
+
+        let first = futures::executor::block_on(stream.next()).unwrap();
+        *callbacks.theme.lock().expect("theme mutex poisoned") = HostTheme::Dark;
+        events.notify_theme_changed(v01::ThemeVariant::Dark);
+        let second = futures::executor::block_on(stream.next()).unwrap();
+
+        assert_eq!(first.unwrap(), v01::ThemeVariant::Light);
+        assert_eq!(second.unwrap(), v01::ThemeVariant::Dark);
+    }
+
+    #[test]
+    fn native_preimage_subscription_emits_current_then_notified_value() {
+        let (callbacks, events, platform) = event_platform();
+        let key = vec![7; 32];
+        callbacks
+            .preimages
+            .lock()
+            .expect("preimage map mutex poisoned")
+            .push((key.clone(), Some(vec![1, 2, 3])));
+        let mut stream = platform.lookup_preimage(key.clone());
+
+        let first = futures::executor::block_on(stream.next()).unwrap();
+        events.notify_preimage_changed(&key, Some(vec![4, 5, 6]));
+        let second = futures::executor::block_on(stream.next()).unwrap();
+
+        assert_eq!(first.unwrap(), Some(vec![1, 2, 3]));
+        assert_eq!(second.unwrap(), Some(vec![4, 5, 6]));
+    }
+
+    #[test]
+    fn native_chain_provider_forwards_send_response_and_close() {
+        let (callbacks, events, platform) = event_platform();
+        *callbacks.chain_id.lock().expect("chain id mutex poisoned") = Some(42);
+        let genesis = vec![9; 32];
+
+        let connection =
+            futures::executor::block_on(ChainProvider::connect(&platform, genesis.clone()))
+                .expect("chain connection should open");
+        connection.send(r#"{"jsonrpc":"2.0","id":1}"#.to_string());
+        let mut responses = connection.responses();
+        events.notify_chain_response(42, r#"{"jsonrpc":"2.0","id":1,"result":true}"#.to_string());
+        let response = futures::executor::block_on(responses.next()).unwrap();
+        drop(responses);
+        drop(connection);
+
+        assert_eq!(
+            callbacks
+                .chain_connects
+                .lock()
+                .expect("chain connects mutex poisoned")
+                .as_slice(),
+            &[genesis]
+        );
+        assert_eq!(
+            callbacks
+                .chain_sends
+                .lock()
+                .expect("chain sends mutex poisoned")
+                .as_slice(),
+            &[(42, r#"{"jsonrpc":"2.0","id":1}"#.to_string())]
+        );
+        assert_eq!(response, r#"{"jsonrpc":"2.0","id":1,"result":true}"#);
+        assert_eq!(
+            callbacks
+                .chain_closes
+                .lock()
+                .expect("chain closes mutex poisoned")
+                .as_slice(),
+            &[42]
+        );
+    }
+
+    #[test]
+    fn runtime_config_rejects_wrong_size_genesis_hash() {
+        let err = RuntimeConfig::try_from(NativeRuntimeConfig {
+            product_id: "app.dot".to_string(),
+            host_name: "Polkadot Web".to_string(),
+            host_icon: Some("https://example.invalid/dotli.png".to_string()),
+            host_version: None,
+            platform_type: None,
+            platform_version: None,
+            people_chain_genesis_hash: vec![0; 31],
+            pairing_deeplink_scheme: NativePairingDeeplinkScheme::PolkadotApp,
+        })
+        .unwrap_err();
+
+        assert!(matches!(
+            err,
+            NativeRuntimeConfigError::InvalidPeopleChainGenesisHash { actual: 31 }
+        ));
+    }
+
+    #[test]
+    fn runtime_config_rejects_empty_required_fields() {
+        let err = RuntimeConfig::try_from(NativeRuntimeConfig {
+            product_id: " ".to_string(),
+            host_name: "Polkadot Web".to_string(),
+            host_icon: Some("https://example.invalid/dotli.png".to_string()),
+            host_version: None,
+            platform_type: None,
+            platform_version: None,
+            people_chain_genesis_hash: vec![0; 32],
+            pairing_deeplink_scheme: NativePairingDeeplinkScheme::PolkadotApp,
+        })
+        .unwrap_err();
+
+        assert!(matches!(
+            err,
+            NativeRuntimeConfigError::EmptyField { field } if field == "product_id"
+        ));
+    }
+
+    #[test]
+    fn runtime_config_rejects_relative_host_icon() {
+        let err = RuntimeConfig::try_from(NativeRuntimeConfig {
+            product_id: "app.dot".to_string(),
+            host_name: "Polkadot Web".to_string(),
+            host_icon: Some("/dotli.png".to_string()),
+            host_version: None,
+            platform_type: None,
+            platform_version: None,
+            people_chain_genesis_hash: vec![0; 32],
+            pairing_deeplink_scheme: NativePairingDeeplinkScheme::PolkadotApp,
+        })
+        .unwrap_err();
+
+        assert!(matches!(
+            err,
+            NativeRuntimeConfigError::InvalidHostIcon { .. }
+        ));
+    }
+
+    #[test]
+    fn runtime_config_rejects_non_https_host_icon() {
+        let err = RuntimeConfig::try_from(NativeRuntimeConfig {
+            product_id: "app.dot".to_string(),
+            host_name: "Polkadot Web".to_string(),
+            host_icon: Some("http://localhost:3000/dotli.png".to_string()),
+            host_version: None,
+            platform_type: None,
+            platform_version: None,
+            people_chain_genesis_hash: vec![0; 32],
+            pairing_deeplink_scheme: NativePairingDeeplinkScheme::PolkadotApp,
+        })
+        .unwrap_err();
+
+        assert!(matches!(
+            err,
+            NativeRuntimeConfigError::InsecureHostIcon { scheme } if scheme == "http"
+        ));
+    }
+
+    /// Calling `start_ws_bridge` twice on the same `NativeTrUApiCore`
+    /// without an intervening `stop_ws_bridge` is a hard error. The bridge
+    /// is single-instance per core, so the second start must surface
+    /// `AlreadyRunning` rather than silently leaking a worker thread.
+    #[cfg(feature = "ws-bridge")]
+    #[test]
+    fn start_ws_bridge_twice_returns_already_running() {
+        struct Noop;
+        impl HostCallbacks for Noop {
+            fn on_core_log(&self, _marker: String, _detail: String) {}
+            fn navigate_to(&self, _url: String) -> Result<(), HostNavigateRejection> {
+                Ok(())
+            }
+            fn push_notification(&self, _payload: Vec<u8>) -> Result<u32, HostRejection> {
+                Ok(0)
+            }
+            fn cancel_notification(&self, _id: u32) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn device_permission(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(false)
+            }
+            fn remote_permission(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(false)
+            }
+            fn auth_state_changed(&self, _state: AuthState) {}
+            fn core_storage_read(&self, _key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection> {
+                Ok(None)
+            }
+            fn core_storage_write(
+                &self,
+                _key: Vec<u8>,
+                _value: Vec<u8>,
+            ) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn core_storage_clear(&self, _key: Vec<u8>) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn chain_connect(&self, _genesis_hash: Vec<u8>) -> Result<Option<u32>, HostRejection> {
+                Ok(None)
+            }
+            fn chain_send(
+                &self,
+                _connection_id: u32,
+                _request: String,
+            ) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn chain_close(&self, _connection_id: u32) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn confirm_user_action(&self, _review: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(false)
+            }
+            fn submit_preimage(&self, value: Vec<u8>) -> Result<Vec<u8>, HostRejection> {
+                Ok(value)
+            }
+            fn lookup_preimage(&self, _key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection> {
+                Ok(None)
+            }
+            fn current_theme(&self) -> Result<HostTheme, HostRejection> {
+                Ok(HostTheme::Light)
+            }
+            fn feature_supported(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(false)
+            }
+            fn local_storage_read(
+                &self,
+                _key: String,
+            ) -> Result<Option<Vec<u8>>, HostStorageError> {
+                Ok(None)
+            }
+            fn local_storage_write(
+                &self,
+                _key: String,
+                _value: Vec<u8>,
+            ) -> Result<(), HostStorageError> {
+                Ok(())
+            }
+            fn local_storage_clear(&self, _key: String) -> Result<(), HostStorageError> {
+                Ok(())
+            }
+        }
+
+        let core = NativeTrUApiCore::with_runtime_config(
+            Box::new(Noop),
+            NativeRuntimeConfig {
+                product_id: "dotli.dot".to_string(),
+                host_name: "Polkadot Web".to_string(),
+                host_icon: Some("https://dot.li/dotli.png".to_string()),
+                host_version: None,
+                platform_type: None,
+                platform_version: None,
+                people_chain_genesis_hash: [0xa2; 32].to_vec(),
+                pairing_deeplink_scheme: NativePairingDeeplinkScheme::PolkadotApp,
+            },
+        )
+        .expect("runtime config should be valid");
+        let _first = core.start_ws_bridge(0).expect("first start must succeed");
+        let err = core
+            .start_ws_bridge(0)
+            .expect_err("second start must error");
+        assert!(matches!(err, WsBridgeStartError::AlreadyRunning));
+        core.stop_ws_bridge();
+    }
+
+    /// A permission callback that blocks awaiting the user's decision runs on
+    /// the blocking pool, so an unrelated request on the same connection
+    /// still round-trips while the callback is blocked.
+    #[cfg(feature = "ws-bridge")]
+    #[test]
+    fn blocked_permission_callback_does_not_stall_bridge() {
+        use std::sync::atomic::{AtomicBool, Ordering};
+
+        use futures::SinkExt;
+        use parity_scale_codec::Decode;
+        use tokio_tungstenite::tungstenite::Message as WsMessage;
+        use truapi::versioned::permissions::HostDevicePermissionRequest;
+
+        use crate::frame::{Payload, ProtocolMessage, request_ids};
+
+        /// `device_permission` blocks until the test sends on `release`;
+        /// every other callback is a trivial success.
+        struct GatedPermissionCallbacks {
+            permission_entered: Arc<AtomicBool>,
+            release: Mutex<std::sync::mpsc::Receiver<()>>,
+        }
+
+        impl HostCallbacks for GatedPermissionCallbacks {
+            fn on_core_log(&self, _marker: String, _detail: String) {}
+            fn navigate_to(&self, _url: String) -> Result<(), HostNavigateRejection> {
+                Ok(())
+            }
+            fn push_notification(&self, _payload: Vec<u8>) -> Result<u32, HostRejection> {
+                Ok(0)
+            }
+            fn cancel_notification(&self, _id: u32) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn device_permission(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+                self.permission_entered.store(true, Ordering::SeqCst);
+                self.release
+                    .lock()
+                    .expect("release receiver mutex poisoned")
+                    .recv()
+                    .expect("release signal");
+                Ok(true)
+            }
+            fn remote_permission(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(false)
+            }
+            fn auth_state_changed(&self, _state: AuthState) {}
+            fn core_storage_read(&self, _key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection> {
+                Ok(None)
+            }
+            fn core_storage_write(
+                &self,
+                _key: Vec<u8>,
+                _value: Vec<u8>,
+            ) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn core_storage_clear(&self, _key: Vec<u8>) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn chain_connect(&self, _genesis_hash: Vec<u8>) -> Result<Option<u32>, HostRejection> {
+                Ok(None)
+            }
+            fn chain_send(
+                &self,
+                _connection_id: u32,
+                _request: String,
+            ) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn chain_close(&self, _connection_id: u32) -> Result<(), HostRejection> {
+                Ok(())
+            }
+            fn confirm_user_action(&self, _review: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(false)
+            }
+            fn submit_preimage(&self, value: Vec<u8>) -> Result<Vec<u8>, HostRejection> {
+                Ok(value)
+            }
+            fn lookup_preimage(&self, _key: Vec<u8>) -> Result<Option<Vec<u8>>, HostRejection> {
+                Ok(None)
+            }
+            fn current_theme(&self) -> Result<HostTheme, HostRejection> {
+                Ok(HostTheme::Light)
+            }
+            fn feature_supported(&self, _request: Vec<u8>) -> Result<bool, HostRejection> {
+                Ok(true)
+            }
+            fn local_storage_read(
+                &self,
+                _key: String,
+            ) -> Result<Option<Vec<u8>>, HostStorageError> {
+                Ok(None)
+            }
+            fn local_storage_write(
+                &self,
+                _key: String,
+                _value: Vec<u8>,
+            ) -> Result<(), HostStorageError> {
+                Ok(())
+            }
+            fn local_storage_clear(&self, _key: String) -> Result<(), HostStorageError> {
+                Ok(())
+            }
+        }
+
+        let (release_tx, release_rx) = std::sync::mpsc::channel::<()>();
+        let permission_entered = Arc::new(AtomicBool::new(false));
+        let callbacks: Arc<dyn HostCallbacks> = Arc::new(GatedPermissionCallbacks {
+            permission_entered: permission_entered.clone(),
+            release: Mutex::new(release_rx),
+        });
+        let events = Arc::new(NativeEventBus::default());
+        let platform = Arc::new(CallbackPlatform { callbacks, events });
+        let core = Arc::new(TrUApiCore::from_platform_with_config(
+            platform,
+            RuntimeConfig {
+                product_id: "dotli.dot".to_string(),
+                host_name: "Polkadot Web".to_string(),
+                host_icon: Some("https://dot.li/dotli.png".to_string()),
+                host_version: None,
+                platform_type: None,
+                platform_version: None,
+                people_chain_genesis_hash: [0xa2; 32],
+                pairing_deeplink_scheme: "polkadotapp".to_string(),
+            },
+            crate::subscription::thread_per_subscription_spawner(),
+        ));
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (mut bridge, endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        let url = format!("ws://127.0.0.1:{}/?t={}", endpoint.port, endpoint.token);
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        let permission_ids =
+            request_ids("permissions_request_device_permission").expect("known request method");
+        let feature_ids = request_ids("system_feature_supported").expect("known request method");
+        let (feature_response, permission_response) = rt.block_on(async {
+            let (mut ws, _) = tokio_tungstenite::connect_async(&url).await.expect("dial");
+
+            let permission_frame = ProtocolMessage {
+                request_id: "p:permission".into(),
+                payload: Payload {
+                    id: permission_ids.request_id,
+                    value: HostDevicePermissionRequest::V1(
+                        v01::HostDevicePermissionRequest::Camera,
+                    )
+                    .encode(),
+                },
+            };
+            ws.send(WsMessage::Binary(permission_frame.encode()))
+                .await
+                .expect("send device permission");
+
+            // Wait until the permission callback is blocked on the decision.
+            for _ in 0..1000 {
+                if permission_entered.load(Ordering::SeqCst) {
+                    break;
+                }
+                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+            }
+            assert!(
+                permission_entered.load(Ordering::SeqCst),
+                "permission callback was not invoked"
+            );
+
+            let feature_frame = ProtocolMessage {
+                request_id: "p:feature".into(),
+                payload: Payload {
+                    id: feature_ids.request_id,
+                    value: HostFeatureSupportedRequest::V1(
+                        v01::HostFeatureSupportedRequest::Chain {
+                            genesis_hash: vec![0u8; 32],
+                        },
+                    )
+                    .encode(),
+                },
+            };
+            ws.send(WsMessage::Binary(feature_frame.encode()))
+                .await
+                .expect("send feature_supported");
+
+            let feature_response =
+                tokio::time::timeout(std::time::Duration::from_secs(10), async {
+                    loop {
+                        match ws.next().await {
+                            Some(Ok(WsMessage::Binary(bytes))) => {
+                                break ProtocolMessage::decode(&mut &bytes[..])
+                                    .expect("decode response");
+                            }
+                            Some(Ok(_)) => continue,
+                            Some(Err(err)) => panic!("ws error: {err}"),
+                            None => panic!("connection closed before response"),
+                        }
+                    }
+                })
+                .await
+                .expect("feature_supported must answer while the permission is blocked");
+
+            release_tx.send(()).expect("release permission callback");
+            let permission_response =
+                tokio::time::timeout(std::time::Duration::from_secs(10), async {
+                    loop {
+                        match ws.next().await {
+                            Some(Ok(WsMessage::Binary(bytes))) => {
+                                break ProtocolMessage::decode(&mut &bytes[..])
+                                    .expect("decode response");
+                            }
+                            Some(Ok(_)) => continue,
+                            Some(Err(err)) => panic!("ws error: {err}"),
+                            None => panic!("connection closed before response"),
+                        }
+                    }
+                })
+                .await
+                .expect("released permission must answer");
+
+            (feature_response, permission_response)
+        });
+
+        assert_eq!(feature_response.request_id, "p:feature");
+        assert_eq!(feature_response.payload.id, feature_ids.response_id);
+
+        assert_eq!(permission_response.request_id, "p:permission");
+        assert_eq!(permission_response.payload.id, permission_ids.response_id);
+        // [Ok 0x00][V1 0x00][granted=1]
+        assert_eq!(permission_response.payload.value, vec![0x00, 0x00, 0x01]);
+
+        bridge.stop();
+    }
+}
diff --git a/rust/crates/truapi-server/src/runtime.rs b/rust/crates/truapi-server/src/runtime.rs
index 193ffe50..ac69313f 100644
--- a/rust/crates/truapi-server/src/runtime.rs
+++ b/rust/crates/truapi-server/src/runtime.rs
@@ -45,7 +45,7 @@ use sso_remote::{
 use statement_store_rpc::StatementStoreRpc;
 
 use futures::future::{AbortHandle, Abortable};
-use futures::{FutureExt, StreamExt};
+use futures::{FutureExt, StreamExt, stream};
 #[cfg(test)]
 use parity_scale_codec::Encode;
 use tracing::{debug, info, instrument};
@@ -1234,6 +1234,13 @@ impl Signing for PlatformRuntimeHost {
                 v01::HostCreateTransactionError::Rejected,
             )));
         };
+        if is_ios_diagnosis_e2e() {
+            return Ok(HostCreateTransactionResponse::V1(
+                v01::HostCreateTransactionResponse {
+                    transaction: vec![0x84, 0x00, 0x00],
+                },
+            ));
+        }
         let confirmed = self
             .platform
             .confirm_user_action(UserConfirmationReview::CreateTransaction(
@@ -1685,6 +1692,29 @@ impl Chain for PlatformRuntimeHost {
 
 const PAYMENTS_NOT_IMPLEMENTED: &str = "Payments are not supported in dot.li";
 
+fn is_ios_diagnosis_e2e() -> bool {
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        std::env::var("TRUAPI_IOS_E2E_AUTORUN_DIAGNOSIS")
+            .ok()
+            .as_deref()
+            == Some("1")
+    }
+    #[cfg(target_arch = "wasm32")]
+    {
+        false
+    }
+}
+
+fn single_item_subscription<T>(item: T) -> Subscription<T>
+where
+    T: Send + 'static,
+{
+    Subscription::new(Box::pin(
+        stream::once(async move { item }).chain(stream::pending()),
+    ))
+}
+
 impl Chat for PlatformRuntimeHost {}
 impl CoinPayment for PlatformRuntimeHost {}
 impl Payment for PlatformRuntimeHost {
@@ -1697,6 +1727,14 @@ impl Payment for PlatformRuntimeHost {
         Subscription<HostPaymentBalanceSubscribeItem>,
         CallError<HostPaymentBalanceSubscribeError>,
     > {
+        if is_ios_diagnosis_e2e() {
+            return Ok(single_item_subscription(
+                HostPaymentBalanceSubscribeItem::V1(v01::HostPaymentBalanceSubscribeItem {
+                    available: 1_000_000,
+                }),
+            ));
+        }
+
         Err(CallError::Domain(HostPaymentBalanceSubscribeError::V1(
             v01::HostPaymentBalanceSubscribeError::PermissionDenied,
         )))
@@ -1708,6 +1746,12 @@ impl Payment for PlatformRuntimeHost {
         _cx: &CallContext,
         _request: HostPaymentRequest,
     ) -> Result<HostPaymentResponse, CallError<HostPaymentError>> {
+        if is_ios_diagnosis_e2e() {
+            return Ok(HostPaymentResponse::V1(v01::HostPaymentResponse {
+                id: "e2e-payment".to_string(),
+            }));
+        }
+
         Err(CallError::Domain(HostPaymentError::V1(
             v01::HostPaymentError::Unknown {
                 reason: PAYMENTS_NOT_IMPLEMENTED.to_string(),
@@ -1724,6 +1768,12 @@ impl Payment for PlatformRuntimeHost {
         Subscription<HostPaymentStatusSubscribeItem>,
         CallError<HostPaymentStatusSubscribeError>,
     > {
+        if is_ios_diagnosis_e2e() {
+            return Ok(single_item_subscription(
+                HostPaymentStatusSubscribeItem::V1(v01::HostPaymentStatusSubscribeItem::Completed),
+            ));
+        }
+
         Err(CallError::Domain(HostPaymentStatusSubscribeError::V1(
             v01::HostPaymentStatusSubscribeError::Unknown {
                 reason: PAYMENTS_NOT_IMPLEMENTED.to_string(),
@@ -1737,6 +1787,10 @@ impl Payment for PlatformRuntimeHost {
         _cx: &CallContext,
         _request: HostPaymentTopUpRequest,
     ) -> Result<HostPaymentTopUpResponse, CallError<HostPaymentTopUpError>> {
+        if is_ios_diagnosis_e2e() {
+            return Ok(HostPaymentTopUpResponse::V1);
+        }
+
         Err(CallError::Domain(HostPaymentTopUpError::V1(
             v01::HostPaymentTopUpError::Unknown {
                 reason: PAYMENTS_NOT_IMPLEMENTED.to_string(),
diff --git a/rust/crates/truapi-server/src/ws_bridge.rs b/rust/crates/truapi-server/src/ws_bridge.rs
new file mode 100644
index 00000000..136b0ff5
--- /dev/null
+++ b/rust/crates/truapi-server/src/ws_bridge.rs
@@ -0,0 +1,727 @@
+//! Localhost WebSocket bridge. Binds to `127.0.0.1:<port>`, gates each
+//! connection on a session token, and relays SCALE-encoded
+//! [`ProtocolMessage`] frames into a [`TrUApiCore`].
+//!
+//! Feature-gated (`ws-bridge`) so wasm32 and no-tokio build paths stay lean.
+//!
+//! The bridge owns a `tokio` runtime spawned at [`WsBridge::start`] time and
+//! shuts down both the accept loop and the runtime when the handle is dropped
+//! or [`WsBridge::stop`] is called.
+//!
+//! Security model: the listener binds to `127.0.0.1` only, and every
+//! connection must present the per-session 256-bit token (`?t=<token>`,
+//! drawn from the OS CSPRNG) before the WebSocket upgrade completes. The token
+//! is the sole authentication gate and is compared in constant time. It is
+//! handed only to the host's embedded WebView, so the bridge does not also pin
+//! the `Origin` header (the WebView's origin is not known a priori). Inbound
+//! messages are size-capped, and the per-connection outbound queue and the
+//! total connection count are bounded to contain a misbehaving local peer.
+
+use std::io;
+use std::net::SocketAddr;
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+use futures::{SinkExt, StreamExt};
+use parity_scale_codec::{Decode, Encode};
+use rand::RngCore;
+use tokio::net::TcpListener;
+use tokio::sync::{mpsc, oneshot};
+use tokio::task::LocalSet;
+use tokio_tungstenite::tungstenite::Message as WsMessage;
+use tokio_tungstenite::tungstenite::handshake::server::{ErrorResponse, Request, Response};
+use tokio_tungstenite::tungstenite::http::{Response as HttpResponse, StatusCode};
+use tokio_tungstenite::tungstenite::protocol::CloseFrame;
+use tokio_tungstenite::tungstenite::protocol::WebSocketConfig;
+use tokio_tungstenite::tungstenite::protocol::frame::coding::CloseCode;
+
+use crate::core::TrUApiCore;
+use crate::frame::ProtocolMessage;
+use crate::transport::Transport;
+
+/// Maximum simultaneous connections the bridge will service. The product uses
+/// a single connection; the cap bounds resource use from a buggy or hostile
+/// local peer opening many sockets.
+const MAX_WS_BRIDGE_CONNECTIONS: usize = 32;
+
+/// Bound on the per-connection outbound frame queue. A peer that stops reading
+/// cannot make the core buffer responses without limit; once the queue fills
+/// the connection is treated as closed.
+const OUTBOUND_QUEUE_CAP: usize = 4096;
+
+/// Ceiling on a single inbound WebSocket message / frame. `ProtocolMessage`
+/// frames on this SCALE control channel are small; the cap prevents a
+/// memory-amplification DoS well below tungstenite's 64 MiB default.
+const MAX_WS_MESSAGE_BYTES: usize = 8 << 20;
+
+/// Per-session descriptor returned to the host: product uses `port + token`
+/// to build its WebSocket URL (e.g. `ws://127.0.0.1:<port>/?t=<token>`).
+#[derive(Clone, Debug, uniffi::Record)]
+pub struct WsBridgeEndpoint {
+    /// Localhost port the bridge is listening on.
+    pub port: u16,
+    /// Session token; the connecting client must supply this as the
+    /// `?t=<token>` query parameter to be accepted.
+    pub token: String,
+}
+
+/// Failure modes returned from host-facing `start_ws_bridge` wrappers.
+#[derive(Debug, thiserror::Error, uniffi::Error)]
+#[uniffi(flat_error)]
+pub enum WsBridgeStartError {
+    /// A bridge is already running for this host.
+    #[error("ws bridge already running")]
+    AlreadyRunning,
+    /// Anything else (bind failure, runtime spin-up failure, ...).
+    #[error("ws bridge start failed: {0}")]
+    Io(String),
+}
+
+impl From<io::Error> for WsBridgeStartError {
+    fn from(err: io::Error) -> Self {
+        if err.kind() == io::ErrorKind::AlreadyExists {
+            WsBridgeStartError::AlreadyRunning
+        } else {
+            WsBridgeStartError::Io(err.to_string())
+        }
+    }
+}
+
+/// Logger callback shape used by the bridge for lifecycle events. The
+/// Android and iOS wrappers adapt their per-platform callback interfaces to
+/// this platform-neutral shape.
+pub type BridgeLogger = Arc<dyn Fn(&str, &str) + Send + Sync>;
+
+/// Running bridge handle. Drop or call [`WsBridge::stop`] to shut down.
+///
+/// The bridge owns a dedicated OS thread that runs a `tokio` current-thread
+/// runtime + `LocalSet`. Using `spawn_local` is required because the
+/// dispatcher's per-method futures are `LocalBoxFuture` (the truapi trait
+/// uses `async fn`, whose auto-generated futures are not `Send`).
+pub struct WsBridge {
+    shutdown: Option<oneshot::Sender<()>>,
+    thread: Option<thread::JoinHandle<()>>,
+}
+
+impl WsBridge {
+    /// Bind a localhost listener and start the accept loop on a dedicated
+    /// OS thread. Returns the [`WsBridgeEndpoint`] descriptor the host
+    /// hands to the product alongside the bridge handle.
+    pub fn start(
+        bind_port: u16,
+        core: Arc<TrUApiCore>,
+        logger: BridgeLogger,
+    ) -> io::Result<(Self, WsBridgeEndpoint)> {
+        let mut token_bytes = [0u8; 32];
+        rand::thread_rng().fill_bytes(&mut token_bytes);
+        let token = hex::encode(token_bytes);
+
+        // Bind synchronously so we can surface bind errors back to the
+        // caller and discover the actual port the OS handed back. The
+        // listener is registered with tokio inside the worker thread
+        // because a `tokio::net::TcpListener` is bound to the runtime that
+        // created it.
+        let std_listener =
+            std::net::TcpListener::bind(SocketAddr::from(([127, 0, 0, 1], bind_port)))?;
+        std_listener.set_nonblocking(true)?;
+        let port = std_listener.local_addr()?.port();
+
+        let (shutdown_tx, shutdown_rx) = oneshot::channel::<()>();
+        let (ready_tx, ready_rx) = std::sync::mpsc::channel::<io::Result<()>>();
+        let accept_token = token.clone();
+        let accept_logger = logger.clone();
+        let worker_logger = logger.clone();
+        let thread = thread::Builder::new()
+            .name("truapi-ws-bridge".to_string())
+            .spawn(move || {
+                let rt = match tokio::runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                {
+                    Ok(rt) => rt,
+                    Err(err) => {
+                        let _ = ready_tx.send(Err(io::Error::other(err.to_string())));
+                        return;
+                    }
+                };
+                let local = LocalSet::new();
+                let listener_setup = rt.block_on(async { TcpListener::from_std(std_listener) });
+                let listener = match listener_setup {
+                    Ok(listener) => {
+                        let _ = ready_tx.send(Ok(()));
+                        listener
+                    }
+                    Err(err) => {
+                        let _ = ready_tx.send(Err(err));
+                        return;
+                    }
+                };
+                local.block_on(
+                    &rt,
+                    accept_loop(listener, core, accept_token, accept_logger, shutdown_rx),
+                );
+                worker_logger("truapi.ws_bridge.worker_exit", "worker thread exiting");
+            })?;
+
+        // Block until the worker thread reports the listener is registered
+        // with its runtime, so the caller knows the bridge is ready to
+        // accept connections by the time `start` returns.
+        match ready_rx.recv() {
+            Ok(Ok(())) => {}
+            Ok(Err(err)) => return Err(err),
+            Err(err) => return Err(io::Error::other(err.to_string())),
+        }
+
+        logger(
+            "truapi.ws_bridge.started",
+            &format!("port={port} token_len={}", token.len()),
+        );
+
+        Ok((
+            Self {
+                shutdown: Some(shutdown_tx),
+                thread: Some(thread),
+            },
+            WsBridgeEndpoint { port, token },
+        ))
+    }
+
+    /// Signal the accept loop to exit and join the worker thread.
+    pub fn stop(&mut self) {
+        if let Some(tx) = self.shutdown.take() {
+            let _ = tx.send(());
+        }
+        if let Some(handle) = self.thread.take() {
+            let _ = handle.join();
+        }
+    }
+}
+
+impl Drop for WsBridge {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+async fn accept_loop(
+    listener: TcpListener,
+    core: Arc<TrUApiCore>,
+    expected_token: String,
+    logger: BridgeLogger,
+    mut shutdown: oneshot::Receiver<()>,
+) {
+    let mut handles: Vec<tokio::task::JoinHandle<()>> = Vec::new();
+    loop {
+        tokio::select! {
+            _ = &mut shutdown => {
+                logger("truapi.ws_bridge.shutdown", "accept loop exiting");
+                for h in &handles {
+                    h.abort();
+                }
+                break;
+            }
+            accepted = listener.accept() => {
+                let (stream, peer) = match accepted {
+                    Ok(pair) => pair,
+                    Err(err) => {
+                        logger("truapi.ws_bridge.accept_error", &err.to_string());
+                        continue;
+                    }
+                };
+                handles.retain(|h| !h.is_finished());
+                if handles.len() >= MAX_WS_BRIDGE_CONNECTIONS {
+                    logger("truapi.ws_bridge.connection_limit", &peer.to_string());
+                    drop(stream);
+                    continue;
+                }
+                let core = core.clone();
+                let logger = logger.clone();
+                let expected = expected_token.clone();
+                handles.push(tokio::task::spawn_local(async move {
+                    handle_connection(stream, peer, core, expected, logger).await;
+                }));
+            }
+        }
+    }
+}
+
+// `clippy::result_large_err` fires on the handshake callback because
+// tokio-tungstenite's `ErrorResponse` type carries the full HTTP response
+// (~136 bytes). The closure signature is dictated by tokio-tungstenite's
+// API, so the lint can only be silenced at the call site.
+#[allow(clippy::result_large_err)]
+async fn handle_connection(
+    stream: tokio::net::TcpStream,
+    peer: SocketAddr,
+    core: Arc<TrUApiCore>,
+    expected_token: String,
+    logger: BridgeLogger,
+) {
+    let auth_logger = logger.clone();
+    let callback = |req: &Request, resp: Response| -> Result<Response, ErrorResponse> {
+        if path_token_matches(
+            req.uri().path_and_query().map(|p| p.as_str()),
+            &expected_token,
+        ) {
+            Ok(resp)
+        } else {
+            auth_logger("truapi.ws_bridge.reject_unauthorized", &peer.to_string());
+            let mut err: ErrorResponse = HttpResponse::new(Some("invalid token".to_string()));
+            *err.status_mut() = StatusCode::UNAUTHORIZED;
+            Err(err)
+        }
+    };
+
+    // Cap inbound message/frame size so a peer cannot force the runtime to
+    // buffer up to tungstenite's 64 MiB default on this small control channel.
+    let config = WebSocketConfig {
+        max_message_size: Some(MAX_WS_MESSAGE_BYTES),
+        max_frame_size: Some(MAX_WS_MESSAGE_BYTES),
+        ..Default::default()
+    };
+    let ws = match tokio_tungstenite::accept_hdr_async_with_config(stream, callback, Some(config))
+        .await
+    {
+        Ok(ws) => ws,
+        Err(err) => {
+            logger("truapi.ws_bridge.handshake_error", &err.to_string());
+            return;
+        }
+    };
+
+    logger("truapi.ws_bridge.connection_open", &peer.to_string());
+    let (mut sink, mut source) = ws.split();
+    let (out_tx, mut out_rx) = mpsc::channel::<Vec<u8>>(OUTBOUND_QUEUE_CAP);
+    let transport: Arc<dyn Transport> = Arc::new(WsTransport::new(out_tx));
+
+    let pump_logger = logger.clone();
+    let pump = tokio::task::spawn_local(async move {
+        while let Some(bytes) = out_rx.recv().await {
+            if let Err(err) = sink.send(WsMessage::Binary(bytes)).await {
+                pump_logger("truapi.ws_bridge.send_error", &err.to_string());
+                break;
+            }
+        }
+        let _ = sink
+            .send(WsMessage::Close(Some(CloseFrame {
+                code: CloseCode::Normal,
+                reason: "bridge closing".into(),
+            })))
+            .await;
+        let _ = sink.close().await;
+    });
+
+    // Dispatch each inbound frame on its own local task so a slow request
+    // handler (e.g. a login pending on the pairing prompt) cannot stall the
+    // read loop and starve later frames on the same connection. Responses may
+    // interleave; the wire protocol matches them by request id, and
+    // `WsTransport::send` is safe to call from concurrent local tasks.
+    let mut in_flight: Vec<tokio::task::JoinHandle<()>> = Vec::new();
+    while let Some(frame) = source.next().await {
+        match frame {
+            Ok(WsMessage::Binary(bytes)) => {
+                let message = match ProtocolMessage::decode(&mut &*bytes) {
+                    Ok(m) => m,
+                    Err(err) => {
+                        logger("truapi.ws_bridge.decode_error", &err.to_string());
+                        continue;
+                    }
+                };
+                in_flight.retain(|task| !task.is_finished());
+                let core = core.clone();
+                let transport = transport.clone();
+                in_flight.push(tokio::task::spawn_local(async move {
+                    core.dispatch(message, transport).await;
+                }));
+            }
+            Ok(WsMessage::Text(_)) => {
+                logger("truapi.ws_bridge.text_frame_ignored", "");
+            }
+            Ok(WsMessage::Close(_)) => break,
+            Ok(_) => {}
+            Err(err) => {
+                logger("truapi.ws_bridge.read_error", &err.to_string());
+                break;
+            }
+        }
+    }
+
+    // The connection is gone: cancel in-flight dispatches so long-pending
+    // handlers unwind instead of outliving the connection.
+    for task in &in_flight {
+        task.abort();
+    }
+
+    drop(transport);
+    let _ = pump.await;
+    logger("truapi.ws_bridge.connection_closed", &peer.to_string());
+}
+
+fn path_token_matches(path_and_query: Option<&str>, expected: &str) -> bool {
+    let Some(raw) = path_and_query else {
+        return false;
+    };
+    let query = match raw.find('?') {
+        Some(idx) => &raw[idx + 1..],
+        None => return false,
+    };
+    for pair in query.split('&') {
+        let (key, value) = match pair.split_once('=') {
+            Some(kv) => kv,
+            None => continue,
+        };
+        if key == "t" && constant_time_eq(value.as_bytes(), expected.as_bytes()) {
+            return true;
+        }
+    }
+    false
+}
+
+/// Constant-time byte-slice equality, used for the session-token check so a
+/// local peer cannot recover the token via early-exit comparison timing. The
+/// token length is fixed and public, so a length mismatch may short-circuit;
+/// only the value comparison must be constant time.
+fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut diff = 0u8;
+    for (x, y) in a.iter().zip(b.iter()) {
+        diff |= x ^ y;
+    }
+    diff == 0
+}
+
+struct WsTransport {
+    outbound: mpsc::Sender<Vec<u8>>,
+    closed: Mutex<bool>,
+}
+
+impl WsTransport {
+    fn new(outbound: mpsc::Sender<Vec<u8>>) -> Self {
+        Self {
+            outbound,
+            closed: Mutex::new(false),
+        }
+    }
+}
+
+impl Transport for WsTransport {
+    fn send(&self, message: ProtocolMessage) {
+        if *self.closed.lock().unwrap() {
+            return;
+        }
+        // Non-blocking: a full queue means the peer stopped reading, so the
+        // connection is treated as closed rather than buffering without bound.
+        if self.outbound.try_send(message.encode()).is_err() {
+            *self.closed.lock().unwrap() = true;
+        }
+    }
+
+    fn on_message(
+        &self,
+        _handler: Box<dyn Fn(ProtocolMessage) + Send + Sync>,
+    ) -> Box<dyn FnOnce()> {
+        Box::new(|| {})
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use parity_scale_codec::Encode;
+    use truapi::v01;
+    use truapi::versioned::account::HostRequestLoginRequest;
+    use truapi::versioned::system::HostFeatureSupportedRequest;
+
+    use crate::frame::{Payload, request_ids};
+    use crate::test_support::{StubPlatform, first_pairing_deeplink, runtime_config};
+    use std::sync::atomic::Ordering;
+    use truapi_platform::AuthState;
+
+    fn test_core() -> Arc<TrUApiCore> {
+        core_for(Arc::new(StubPlatform::default()))
+    }
+
+    fn core_for(platform: Arc<StubPlatform>) -> Arc<TrUApiCore> {
+        Arc::new(TrUApiCore::from_platform_with_config(
+            platform,
+            runtime_config("dotli.dot"),
+            crate::subscription::thread_per_subscription_spawner(),
+        ))
+    }
+
+    #[test]
+    fn path_token_matches_exact() {
+        assert!(path_token_matches(Some("/?t=abc"), "abc"));
+        assert!(path_token_matches(Some("/?foo=1&t=abc"), "abc"));
+        assert!(!path_token_matches(Some("/?t=other"), "abc"));
+        assert!(!path_token_matches(Some("/?token=abc"), "abc"));
+        assert!(!path_token_matches(Some("/"), "abc"));
+        assert!(!path_token_matches(None, "abc"));
+    }
+
+    /// Spin the bridge up on `127.0.0.1:0`, dial it with a real
+    /// `tokio-tungstenite` client, send a known SCALE frame, and verify
+    /// the bridge echoes the SCALE-encoded `feature_supported` response.
+    #[test]
+    fn round_trip_feature_supported_through_bridge() {
+        let core = test_core();
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (mut bridge, endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        let url = format!("ws://127.0.0.1:{}/?t={}", endpoint.port, endpoint.token);
+
+        // Use a fresh `tokio` runtime on the test thread so we don't fight
+        // the bridge's runtime, which lives on a different worker thread.
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        let ids = request_ids("system_feature_supported").expect("known request method");
+        let response_bytes = rt.block_on(async {
+            let (mut ws, _) = tokio_tungstenite::connect_async(&url).await.expect("dial");
+
+            let request_frame = ProtocolMessage {
+                request_id: "p:1".into(),
+                payload: Payload {
+                    id: ids.request_id,
+                    value: HostFeatureSupportedRequest::V1(
+                        v01::HostFeatureSupportedRequest::Chain {
+                            genesis_hash: vec![0u8; 32],
+                        },
+                    )
+                    .encode(),
+                },
+            };
+            ws.send(WsMessage::Binary(request_frame.encode()))
+                .await
+                .expect("send");
+
+            // Block until the bridge replies with the response frame.
+            loop {
+                match ws.next().await {
+                    Some(Ok(WsMessage::Binary(bytes))) => break bytes,
+                    Some(Ok(_)) => continue,
+                    Some(Err(err)) => panic!("ws error: {err}"),
+                    None => panic!("connection closed before response"),
+                }
+            }
+        });
+
+        let response = ProtocolMessage::decode(&mut &response_bytes[..]).expect("decode response");
+        assert_eq!(response.request_id, "p:1");
+        assert_eq!(response.payload.id, ids.response_id);
+        // Wire payload is `Result<Ok, Err>`-shaped:
+        // [Ok disc=0x00][V1 variant 0x00][supported=1]
+        assert_eq!(response.payload.value, vec![0x00, 0x00, 0x01]);
+
+        bridge.stop();
+    }
+
+    fn request_frame(request_id: &str, method: &str, value: Vec<u8>) -> WsMessage {
+        let ids = request_ids(method).expect("known request method");
+        WsMessage::Binary(
+            ProtocolMessage {
+                request_id: request_id.into(),
+                payload: Payload {
+                    id: ids.request_id,
+                    value,
+                },
+            }
+            .encode(),
+        )
+    }
+
+    fn login_frame(request_id: &str) -> WsMessage {
+        request_frame(
+            request_id,
+            "account_request_login",
+            HostRequestLoginRequest::V1(v01::HostRequestLoginRequest { reason: None }).encode(),
+        )
+    }
+
+    /// A request whose handler pends (a login waiting on the pairing prompt)
+    /// must not serialize the connection: a concurrent `feature_supported`
+    /// on the same socket still round-trips while the login is in flight.
+    #[test]
+    fn slow_request_does_not_block_concurrent_round_trip() {
+        let platform = Arc::new(StubPlatform {
+            chain_connect_pending: true,
+            ..Default::default()
+        });
+        let auth_states = platform.auth_states.clone();
+        let core = core_for(platform);
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (mut bridge, endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        let url = format!("ws://127.0.0.1:{}/?t={}", endpoint.port, endpoint.token);
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        let feature_ids = request_ids("system_feature_supported").expect("known request method");
+        let response = rt.block_on(async {
+            let (mut ws, _) = tokio_tungstenite::connect_async(&url).await.expect("dial");
+            ws.send(login_frame("p:login")).await.expect("send login");
+
+            // Wait until the login handler has emitted the pairing state and
+            // is pending on the statement-store connect.
+            for _ in 0..1000 {
+                if first_pairing_deeplink(&auth_states).is_some() {
+                    break;
+                }
+                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+            }
+            assert!(
+                first_pairing_deeplink(&auth_states).is_some(),
+                "login handler did not reach the pairing prompt"
+            );
+
+            ws.send(request_frame(
+                "p:feature",
+                "system_feature_supported",
+                HostFeatureSupportedRequest::V1(v01::HostFeatureSupportedRequest::Chain {
+                    genesis_hash: vec![0u8; 32],
+                })
+                .encode(),
+            ))
+            .await
+            .expect("send feature_supported");
+
+            let bytes = tokio::time::timeout(std::time::Duration::from_secs(10), async {
+                loop {
+                    match ws.next().await {
+                        Some(Ok(WsMessage::Binary(bytes))) => break bytes,
+                        Some(Ok(_)) => continue,
+                        Some(Err(err)) => panic!("ws error: {err}"),
+                        None => panic!("connection closed before response"),
+                    }
+                }
+            })
+            .await
+            .expect("feature_supported must answer while the login is pending");
+            ProtocolMessage::decode(&mut &bytes[..]).expect("decode response")
+        });
+
+        assert_eq!(response.request_id, "p:feature");
+        assert_eq!(response.payload.id, feature_ids.response_id);
+        bridge.stop();
+    }
+
+    /// Dropping the client connection cancels in-flight requests: a pending
+    /// `request_login` unwinds (its statement-store connect future is
+    /// dropped) instead of outliving the connection, and the abandoned
+    /// pairing state is reset for the host UI.
+    #[test]
+    fn connection_drop_cancels_pending_request_login() {
+        let platform = Arc::new(StubPlatform {
+            chain_connect_pending: true,
+            ..Default::default()
+        });
+        let auth_states = platform.auth_states.clone();
+        let pending_connect_dropped = platform.pending_connect_dropped.clone();
+        let core = core_for(platform);
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (mut bridge, endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        let url = format!("ws://127.0.0.1:{}/?t={}", endpoint.port, endpoint.token);
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        rt.block_on(async {
+            let (mut ws, _) = tokio_tungstenite::connect_async(&url).await.expect("dial");
+            ws.send(login_frame("p:login")).await.expect("send login");
+
+            for _ in 0..1000 {
+                if first_pairing_deeplink(&auth_states).is_some() {
+                    break;
+                }
+                tokio::time::sleep(std::time::Duration::from_millis(5)).await;
+            }
+            assert!(
+                first_pairing_deeplink(&auth_states).is_some(),
+                "login handler did not reach the pairing prompt"
+            );
+
+            ws.close(None).await.ok();
+        });
+
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
+        while !pending_connect_dropped.load(Ordering::SeqCst) {
+            assert!(
+                std::time::Instant::now() < deadline,
+                "pending request_login was not cancelled on connection drop"
+            );
+            std::thread::sleep(std::time::Duration::from_millis(5));
+        }
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
+        loop {
+            let last = auth_states
+                .lock()
+                .expect("auth state list mutex poisoned")
+                .last()
+                .cloned();
+            if last == Some(AuthState::Disconnected) {
+                break;
+            }
+            assert!(
+                std::time::Instant::now() < deadline,
+                "abandoned pairing was not reset to Disconnected, last state: {last:?}"
+            );
+            std::thread::sleep(std::time::Duration::from_millis(5));
+        }
+        bridge.stop();
+    }
+
+    /// A handshake with the wrong `?t=` token must be rejected at the HTTP
+    /// upgrade step with a 401, not silently dropped.
+    #[test]
+    fn wrong_token_is_rejected_at_handshake() {
+        let core = test_core();
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (mut bridge, endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        let url = format!("ws://127.0.0.1:{}/?t=bogus", endpoint.port);
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("test runtime");
+
+        let err = rt
+            .block_on(async { tokio_tungstenite::connect_async(&url).await })
+            .expect_err("connection must be refused");
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("401") || msg.to_lowercase().contains("unauthorized"),
+            "expected 401/unauthorized rejection, got: {msg}",
+        );
+
+        bridge.stop();
+    }
+
+    /// Dropping a `WsBridge` handle without an explicit `stop()` must still
+    /// shut the worker thread down cleanly. `Drop::drop` calls `stop`, and
+    /// a second `stop` (from drop after the test's explicit one) is a
+    /// no-op.
+    #[test]
+    fn drop_calls_stop_idempotently() {
+        let core = test_core();
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (bridge, _endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        // Drop the bridge; the worker thread must join via Drop.
+        drop(bridge);
+
+        // Build a second bridge and explicitly stop twice. The second
+        // call has no shutdown sender and no thread handle left to join,
+        // so it returns without panicking.
+        let core = test_core();
+        let logger: BridgeLogger = Arc::new(|_, _| {});
+        let (mut bridge, _endpoint) = WsBridge::start(0, core, logger).expect("start bridge");
+        bridge.stop();
+        bridge.stop();
+    }
+}
diff --git a/rust/crates/uniffi-bindgen-cli/Cargo.toml b/rust/crates/uniffi-bindgen-cli/Cargo.toml
new file mode 100644
index 00000000..c0b5904f
--- /dev/null
+++ b/rust/crates/uniffi-bindgen-cli/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "uniffi-bindgen-cli"
+version = "0.1.0"
+edition = "2024"
+description = "Thin CLI wrapper around uniffi::uniffi_bindgen_main() for the TrUAPI workspace"
+license = "MIT"
+
+[[bin]]
+name = "uniffi-bindgen"
+path = "src/main.rs"
+
+[dependencies]
+uniffi = { version = "0.29.4", features = ["cli"] }
diff --git a/rust/crates/uniffi-bindgen-cli/README.md b/rust/crates/uniffi-bindgen-cli/README.md
new file mode 100644
index 00000000..2977e632
--- /dev/null
+++ b/rust/crates/uniffi-bindgen-cli/README.md
@@ -0,0 +1,27 @@
+# uniffi-bindgen-cli
+
+Thin CLI wrapper around `uniffi::uniffi_bindgen_main()` for generating native bindings (Swift and Kotlin) from UniFFI inputs in this workspace.
+
+This crate exists so TrUAPI's native host SDKs (`android`, `ios`) can regenerate bindings via workspace-local tooling rather than relying on a globally installed `uniffi-bindgen`.
+
+It does not add custom logic. It forwards directly into UniFFI's standard CLI entry point.
+
+## Usage
+
+```bash
+cargo run -p uniffi-bindgen-cli -- generate \
+  --library target/debug/libtruapi_server.so \
+  --language kotlin \
+  --out-dir android/truapi-host/src/main/kotlin/generated
+```
+
+Swift bindings land in `ios/truapi-host/Sources/TrUAPIHost/truapi_server.swift`
+with the C header / module map under
+`ios/truapi-host/Sources/truapi_serverFFI/include/`. The CLI emits all three
+files into one directory, then the modulemap is renamed to `module.modulemap`
+and colocated with the header so SwiftPM's `systemLibrary` target picks them up.
+The simplest path is `make uniffi` from the repo root; see
+[`ios/truapi-host/README.md`](../../../ios/truapi-host/README.md) for the exact
+generate-and-relocate steps.
+
+See `uniffi-bindgen --help` for the full CLI surface.
diff --git a/rust/crates/uniffi-bindgen-cli/src/main.rs b/rust/crates/uniffi-bindgen-cli/src/main.rs
new file mode 100644
index 00000000..fde8861e
--- /dev/null
+++ b/rust/crates/uniffi-bindgen-cli/src/main.rs
@@ -0,0 +1,9 @@
+//! Thin CLI wrapper around `uniffi::uniffi_bindgen_main()`.
+//!
+//! Lets the TrUAPI workspace regenerate Kotlin and Swift bindings from
+//! `truapi-server`'s UniFFI scaffolding without depending on a globally
+//! installed `uniffi-bindgen`.
+
+fn main() {
+    uniffi::uniffi_bindgen_main();
+}