diff --git a/Cargo.lock b/Cargo.lock index 17b5109..cae775e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2,6 +2,16 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "aead" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1973cfbc1a2daf9cf550e74e1f088c28e7f7d8c1e1418fb6c9dc5184b7e84c99" +dependencies = [ + "crypto-common", + "inout", +] + [[package]] name = "ahash" version = "0.8.12" @@ -24,6 +34,56 @@ dependencies = [ "memchr", ] +[[package]] +name = "anstream" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000" + +[[package]] +name = "anstyle-parse" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" +dependencies = [ + "anstyle", + "once_cell_polyfill", + "windows-sys 0.61.2", +] + [[package]] name = "anyhow" version = "1.0.104" @@ -111,6 +171,12 @@ version = "0.23.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5" +[[package]] +name = "bitflags" +version = "1.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" + [[package]] name = "bitflags" version = "2.13.2" @@ -144,6 +210,16 @@ version = "1.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" +[[package]] +name = "cc" +version = "1.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86e055fa6e3e40ad6187ba25b6855eeb635d5271f8e0f0e1e9a5826b8d75bea0" +dependencies = [ + "find-msvc-tools", + "shlex", +] + [[package]] name = "cfg-if" version = "1.0.5" @@ -157,8 +233,34 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06" dependencies = [ "cfg-if", + "cipher", "cpufeatures", "rand_core", + "zeroize", +] + +[[package]] +name = "chacha20poly1305" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b89e1c441e926b9c82a8d023f6e1b7ae0adcfaa7d621814e4d60789bac751cb" +dependencies = [ + "aead", + "chacha20", + "cipher", + "poly1305", + "zeroize", +] + +[[package]] +name = "cipher" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c" +dependencies = [ + "block-buffer", + "crypto-common", + "inout", ] [[package]] @@ -167,6 +269,12 @@ version = "0.5.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" +[[package]] +name = "colorchoice" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" + [[package]] name = "config" version = "0.15.27" @@ -249,7 +357,9 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453" dependencies = [ + "getrandom 0.4.3", "hybrid-array", + "rand_core", ] [[package]] @@ -294,6 +404,37 @@ version = "2.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06" +[[package]] +name = "defmt" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4a0795ac740cb54d7b3775c9c17345f6aaecf884c01733b39d6017738e0e3e1" +dependencies = [ + "bitflags 1.3.2", + "defmt-macros", +] + +[[package]] +name = "defmt-macros" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "840bb056bd99c495c9188198a258ab787c79f306d864db3e6e8451442d6d8366" +dependencies = [ + "defmt-parser", + "proc-macro2", + "quote", + "syn 3.0.5", +] + +[[package]] +name = "defmt-parser" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "71958f69fb2de856c5dd51ac9377e986ca1aa5919f931bf5395a807277f889a0" +dependencies = [ + "thiserror", +] + [[package]] name = "deranged" version = "0.5.9" @@ -368,6 +509,29 @@ dependencies = [ "simdutf8", ] +[[package]] +name = "env_filter" +version = "2.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "900d271a03799a1ee8d1ca9b19893b48ca674a9284fefcfb85f05e74ed314217" +dependencies = [ + "log", + "regex", +] + +[[package]] +name = "env_logger" +version = "0.11.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "de671bd27a75a797dc9ae289ba1e77276e75e2026408aab65185384e2d5cd3f6" +dependencies = [ + "anstream", + "anstyle", + "env_filter", + "jiff", + "log", +] + [[package]] name = "equivalent" version = "1.0.2" @@ -392,7 +556,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -401,6 +565,12 @@ version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "64cd1e32ddd350061ae6edb1b082d7c54915b5c672c389143b9a63403a109f24" +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + [[package]] name = "foldhash" version = "0.2.0" @@ -754,12 +924,64 @@ dependencies = [ "hashbrown 0.17.1", ] +[[package]] +name = "inout" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b5cf4372d022092674a83b8febf5865f7a573cc0c5baec5e49c879b6a20978f" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" + [[package]] name = "itoa" version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +[[package]] +name = "jiff" +version = "0.2.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2b005715dcbeb0089a3c0dab99f2ff1cc3b2525323552703d648585d342a383" +dependencies = [ + "defmt", + "jiff-core", + "jiff-static", + "log", + "portable-atomic", + "portable-atomic-util", + "serde_core", +] + +[[package]] +name = "jiff-core" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e52fe76043ccecc9005d2305ebaadf7d7fc0cc89ca6baa10a94d6bc68c7128c" +dependencies = [ + "defmt", + "log", +] + +[[package]] +name = "jiff-static" +version = "0.2.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2cc9817253cf7c7ee4684451bd327e88d6f3658014e54a29198625590650695c" +dependencies = [ + "jiff-core", + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "json5" version = "1.3.1" @@ -829,7 +1051,7 @@ checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" dependencies = [ "libc", "wasi", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -844,7 +1066,7 @@ version = "0.50.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" dependencies = [ - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -859,6 +1081,12 @@ version = "1.21.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" +[[package]] +name = "once_cell_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" + [[package]] name = "ordered-multimap" version = "0.7.3" @@ -887,6 +1115,31 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "poly1305" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2d0073b297041425c7c3df6eb4792d598a15323fe63346852b092eca02904c" +dependencies = [ + "cpufeatures", + "universal-hash", +] + +[[package]] +name = "portable-atomic" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85" + +[[package]] +name = "portable-atomic-util" +version = "0.2.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715" +dependencies = [ + "portable-atomic", +] + [[package]] name = "potential_utf" version = "0.1.6" @@ -949,6 +1202,18 @@ version = "0.10.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" +[[package]] +name = "regex" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + [[package]] name = "regex-automata" version = "0.4.18" @@ -966,13 +1231,27 @@ version = "0.8.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom 0.2.17", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + [[package]] name = "ron" version = "0.12.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "81116b9531d61eabc41aeb228e4b6b2435bcca3233b98cf3b3077d4e6e9debb3" dependencies = [ - "bitflags", + "bitflags 2.13.2", "once_cell", "serde", "serde_derive", @@ -999,6 +1278,40 @@ dependencies = [ "semver", ] +[[package]] +name = "rustls" +version = "0.23.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf" +dependencies = [ + "once_cell", + "ring", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-pki-types" +version = "1.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96" +dependencies = [ + "zeroize", +] + +[[package]] +name = "rustls-webpki" +version = "0.103.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4443b1b6d39d7c663139942cc4558262562d2c84123bb6282ef177009ca8b281" +dependencies = [ + "ring", + "rustls-pki-types", + "untrusted", +] + [[package]] name = "rustversion" version = "1.0.23" @@ -1141,6 +1454,12 @@ dependencies = [ "lazy_static", ] +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + [[package]] name = "signal-hook-registry" version = "1.4.8" @@ -1182,7 +1501,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -1333,7 +1652,7 @@ dependencies = [ "signal-hook-registry", "socket2", "tokio-macros", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -1347,6 +1666,16 @@ dependencies = [ "syn 3.0.5", ] +[[package]] +name = "tokio-rustls" +version = "0.26.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c9cc2678c2cdd569ef8215e2afd7954ada2ae20b4fdd2c5fe6139a3b02d105db" +dependencies = [ + "rustls", + "tokio", +] + [[package]] name = "tokio-tungstenite" version = "0.30.0" @@ -1355,8 +1684,12 @@ checksum = "17a073bfed563fa236697a068031408a93cd9522e08abf9933ead3e73411bd71" dependencies = [ "futures-util", "log", + "rustls", + "rustls-pki-types", "tokio", + "tokio-rustls", "tungstenite", + "webpki-roots 0.26.11", ] [[package]] @@ -1529,6 +1862,8 @@ dependencies = [ "httparse", "log", "rand", + "rustls", + "rustls-pki-types", "sha1", "thiserror", ] @@ -1563,6 +1898,22 @@ version = "1.13.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8" +[[package]] +name = "universal-hash" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f4987bdc12753382e0bec4a65c50738ffaabc998b9cdd1f952fb5f39b0048a96" +dependencies = [ + "crypto-common", + "ctutils", +] + +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + [[package]] name = "url" version = "2.5.8" @@ -1581,6 +1932,12 @@ version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be" +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + [[package]] name = "valuable" version = "0.1.1" @@ -1593,6 +1950,32 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "wallet-session-client" +version = "0.1.0" +dependencies = [ + "chacha20poly1305", + "ed25519-dalek", + "env_logger", + "futures-util", + "getrandom 0.4.3", + "hkdf", + "log", + "rustls", + "serde", + "serde_json", + "serde_urlencoded", + "sha2", + "thiserror", + "tokio", + "tokio-tungstenite", + "url", + "wallet-session-core", + "wallet-session-relay", + "x25519-dalek", + "zeroize", +] + [[package]] name = "wallet-session-core" version = "0.1.0" @@ -1650,6 +2033,24 @@ dependencies = [ "wit-bindgen", ] +[[package]] +name = "webpki-roots" +version = "0.26.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9" +dependencies = [ + "webpki-roots 1.0.11", +] + +[[package]] +name = "webpki-roots" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f5f280bbb2b287bc8e7de7e3852945a0ff50d1bbcb5ed42b6c7a568c546df171" +dependencies = [ + "rustls-pki-types", +] + [[package]] name = "winapi" version = "0.3.9" @@ -1678,6 +2079,15 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets", +] + [[package]] name = "windows-sys" version = "0.61.2" @@ -1687,6 +2097,70 @@ dependencies = [ "windows-link", ] +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + [[package]] name = "winnow" version = "1.0.4" @@ -1715,6 +2189,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e7e8131a03190127fb2263afc72b322ecadae46b6ff8c6f399ff5d02f5559af6" dependencies = [ "curve25519-dalek", + "getrandom 0.4.3", "rand_core", "zeroize", ] @@ -1799,6 +2274,20 @@ name = "zeroize" version = "1.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e" +dependencies = [ + "zeroize_derive", +] + +[[package]] +name = "zeroize_derive" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] [[package]] name = "zerotrie" diff --git a/Cargo.toml b/Cargo.toml index f6c4007..fc2f3d7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,8 +1,7 @@ [workspace] resolver = "3" members = [ - "crates/core", - "crates/relay" + "crates/*", ] [workspace.package] diff --git a/README.md b/README.md index 3a3e9af..c088721 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Relay implementation of the Web-to-Wallet communications protocol, as described Currently repository contains these crates: - [core](./crates/core/) -- core types which are shared between client and relay; +- [client](./crates/client/) -- client implementation of the relay protocol; - [relay](./crates/relay/) -- relay server implementation. ## Relay deployment diff --git a/crates/client/Cargo.toml b/crates/client/Cargo.toml new file mode 100644 index 0000000..99fba2f --- /dev/null +++ b/crates/client/Cargo.toml @@ -0,0 +1,42 @@ +[package] +name = "wallet-session-client" +version = "0.1.0" +edition = "2024" +description = "Client implementation of the wallet-session relay protocol" +license = "MIT" +repository = "https://github.com/BlockstreamResearch/wallet-session" + +[dependencies] +wallet-session-core = { path = "../core", version = "0.1.0" } + +tokio = { version = "1.53.1", features = [ + "rt-multi-thread", + "macros", + "net", + "sync", + "time", +] } +tokio-tungstenite = { version = "0.30.0", features = ["rustls-tls-webpki-roots"] } +# tokio-tungstenite's rustls support does not pick a CryptoProvider. Enabling +# `ring` here gives rustls exactly one provider feature; `tls` installs it. +rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"] } +futures-util = "0.3.34" +url = "2" +getrandom = "0.4" +sha2 = "0.11.0" +chacha20poly1305 = { version = "0.11.0", features = ["zeroize"] } +ed25519-dalek = "3.0.0" +x25519-dalek = { version = "3.0.0", features = ["getrandom"] } +hkdf = "0.13.0" + +serde.workspace = true +serde_json.workspace = true +serde_urlencoded = "0.7" +thiserror.workspace = true +log = "0.4" +zeroize = { version = "1", features = ["derive"] } + +[dev-dependencies] +wallet-session-relay = { path = "../relay" } +env_logger = "0.11" +tokio = { version = "1.53.1", features = ["test-util"] } diff --git a/crates/client/src/client.rs b/crates/client/src/client.rs new file mode 100644 index 0000000..8dbcbf1 --- /dev/null +++ b/crates/client/src/client.rs @@ -0,0 +1,1569 @@ +use std::{ + collections::VecDeque, + sync::{ + Arc, + atomic::{AtomicBool, Ordering}, + }, + time::Duration, +}; + +use serde_json::Value; +use tokio::sync::mpsc; +use wallet_session_core::{ + crypto::MessageCipher, + did::DidKey, + frame::{RelayFrame, RelayFrameBody}, + message::{Message, MessageId, MessageType, Topic}, + payload::{ + AckPayload, ApprovePayload, DisconnectPayload, Opaque, ProposalPayload, RejectPayload, + RequestPayload, ResponsePayload, SessionDeletePayload, + }, +}; + +use crate::{ + config::{ClientConfig, MAX_RETRY_DELAY}, + crypto::{Aad, CipherError, SealedPayload}, + error::{ClientError, JsonErrorSummary, Result}, + handshake::{ + EphemeralKeyPair, SessionKey, SessionTopic, decode_public_key, validate_peer_public, + }, + identity::{IdentityKey, unix_now}, + messages::{ClientMessage, RequestId}, + random, + relay::{INBOX_CAPACITY, Inbox, Transport}, + reliability::{ClientEvent, DeliveryEvent, EVENT_CAPACITY, Reliability, requires_ack}, + replay::{self, Observation, ReplayMemory}, + session::{Role, Session, SessionState}, +}; + +/// Default session lifetime. +const SESSION_EXPIRY: Duration = Duration::from_secs(24 * 60 * 60); + +/// Maximum accepted clock skew between envelope `ts` and local time. +const MAX_TS_SKEW_SECS: u64 = 300; + +/// Maximum application messages buffered while waiting for `session_ready`. +const MAX_PENDING_MESSAGES: usize = 256; + +/// A terminal client state that no later operation can leave. +#[derive(Clone, Copy)] +enum Terminal { + Closed, + Transport(&'static str), + NotEstablished, +} + +impl Terminal { + fn error(self) -> ClientError { + match self { + Terminal::Closed => ClientError::Closed, + Terminal::Transport(reason) => ClientError::Transport(reason), + Terminal::NotEstablished => ClientError::SessionNotEstablished, + } + } +} + +/// Local side of the session handshake. +enum Handshake { + /// No handshake activity yet. + Idle, + + /// We sent the proposal carried by frame `proposal_id` and hold its + /// ephemeral keypair. + Proposed { + proposal_id: MessageId, + keypair: EphemeralKeyPair, + }, + + /// We received the proposal carried by frame `proposal_id` and already + /// derived the session material from our own ephemeral keypair and the + /// peer's public key. + PeerProposed { + proposal_id: MessageId, + proposal: ProposalPayload, + public_key: String, + key: SessionKey, + topic: SessionTopic, + }, + + /// Session key established; traffic uses the session topic and key. + Established, +} + +/// A message frame that passed wire validation, sender policy, topic/kind +/// policy and authentication. +struct InboundEnvelope { + id: MessageId, + topic: Topic, + wire: Message, + plaintext: Vec, + now: u64, +} + +/// One relay connection, its outbound reliability and its inbound replay +/// memory. +struct Link { + topic: Topic, + _transport: Transport, + reliability: Reliability, + cipher: C, + replay: ReplayMemory, + shared_ready: Arc, + joined: Arc, + saw_disconnect: bool, +} + +impl Link { + fn is_ready(&self) -> bool { + self.shared_ready.load(Ordering::Relaxed) + } + + /// Whether the relay ever reported both peers on this topic. + fn has_joined(&self) -> bool { + self.joined.load(Ordering::Relaxed) + } +} + +impl Link +where + C: MessageCipher, +{ + #[allow(clippy::too_many_arguments)] + fn new( + config: &ClientConfig, + identity: &IdentityKey, + role: Role, + topic: Topic, + cipher: C, + lifecycle: mpsc::Sender, + outcomes: mpsc::UnboundedSender, + inbox: &mpsc::Sender, + ) -> Self { + let ready = Arc::new(AtomicBool::new(false)); + let joined = Arc::new(AtomicBool::new(false)); + let transport = Transport::connect( + config.clone(), + identity.clone(), + role, + topic.clone(), + Arc::clone(&ready), + Arc::clone(&joined), + inbox.clone(), + ); + let reliability = Reliability::spawn( + transport.outbound(), + Arc::clone(&ready), + lifecycle, + outcomes, + config.ack_base_delay, + config.ack_max_attempts, + config.retransmit_spacing, + config.retransmit_bytes_per_second, + ); + + Self { + topic, + _transport: transport, + reliability, + cipher, + replay: ReplayMemory::new(Duration::from_secs(MAX_TS_SKEW_SECS), replay::CAPACITY), + shared_ready: ready, + joined, + saw_disconnect: false, + } + } +} + +/// A paired client. +/// +/// # Driving the client +/// +/// Inbound work, including acknowledgements, retransmissions and relay +/// lifecycle events, is driven by [`Client::recv`], [`Client::next_event`] and +/// [`Client::wait_session_ready`]. Applications must keep one of those futures +/// pending; [`Client::send`] and [`Client::poll_event`] do not drive the receive +/// path. Since every method takes `&mut self`, the usual pattern is a +/// `tokio::select!` loop over one of the driving futures and the +/// application's own work. +/// +/// Those three futures may be cancelled, which is what `select!` does to the +/// branches that lose. Cancelling one after it has dequeued a frame may drop +/// that frame. We only acknowledge a frame once we have processed it, so the +/// peer retransmits a dropped message within its usual retry budget; the +/// exceptions are the one-shot `disconnect` and `session_delete`, and relay +/// control frames, which are not retransmitted. +/// +/// # Errors +/// +/// [`ClientError::Closed`], [`ClientError::Transport`] and +/// [`ClientError::SessionNotEstablished`] are terminal: the client is closed +/// and outstanding sends are reported as `Failed`. Whatever was already +/// accepted is still handed over first: [`Client::recv`] returns messages +/// that were queued before the client closed, and [`Client::next_event`] +/// returns outstanding delivery outcomes. Once those are drained, every call +/// returns the error that closed the client. Other errors report a single +/// event and leave the client usable, for example [`ClientError::PeerDisconnected`] (the relay said the +/// peer left; it may come back), [`ClientError::UnexpectedHandshake`] (a +/// handshake message that does not fit our state was refused), or a +/// [`ClientError::ProtocolViolation`] for an envelope that reuses a frame id or +/// nonce. +/// +/// Counterpart, replay memory, and reliability state are owned by this +/// instance and are not persisted. Constructing a new client for the same +/// pairing key starts with an empty replay memory and no counterpart, so +/// long-lived applications should keep one client alive rather than recreate +/// it from the pairing key. Restart recovery requires persisting and restoring +/// that state, which this crate does not implement. +/// +/// Delivery outcomes reserve pending capacity until the application consumes +/// them. With 256 pending messages or unconsumed outcomes per link, further +/// sends return [`ClientError::Busy`] instead of dropping an outcome. +/// +/// # Logging +/// +/// The relay connection token and the topic travel in the WebSocket URL. +/// This crate logs neither, but `tungstenite` logs the whole request at +/// `trace` level. Do not enable `trace` for `tungstenite` wherever logs are +/// kept or shared: the token is valid for `token_ttl`, and a pairing topic +/// lets whoever reads it take the free role on it. +pub struct Client { + config: ClientConfig, + identity: IdentityKey, + inbox: mpsc::Receiver, + inbox_tx: mpsc::Sender, + lifecycle: mpsc::Receiver, + lifecycle_tx: mpsc::Sender, + outcomes: mpsc::UnboundedReceiver, + outcomes_tx: mpsc::UnboundedSender, + pairing: Option>, + session_link: Option>, + session: Session, + handshake: Handshake, + did: DidKey, + pending: VecDeque, + pairing_proposal: Option, + pairing_approval: Option, + terminal: Option, +} + +impl Client +where + C: MessageCipher, +{ + /// Connect to the relay for the pairing topic. + /// + /// The cipher must provide a fresh cipher for the derived session key so + /// the session starts with a new nonce prefix and counter. + pub async fn connect( + config: ClientConfig, + identity: IdentityKey, + role: Role, + topic: Topic, + cipher: C, + ) -> Result { + config.validate()?; + let did = identity.did(); + let (inbox_tx, inbox) = mpsc::channel(INBOX_CAPACITY); + let (lifecycle_tx, lifecycle) = mpsc::channel(EVENT_CAPACITY); + let (outcomes_tx, outcomes) = mpsc::unbounded_channel(); + let pairing = Link::new( + &config, + &identity, + role, + topic.clone(), + cipher, + lifecycle_tx.clone(), + outcomes_tx.clone(), + &inbox_tx, + ); + let session = Session::new(topic, role); + + Ok(Self { + config, + identity, + inbox, + inbox_tx, + lifecycle, + lifecycle_tx, + outcomes, + outcomes_tx, + pairing: Some(pairing), + session_link: None, + session, + handshake: Handshake::Idle, + did, + pending: VecDeque::new(), + pairing_proposal: None, + pairing_approval: None, + terminal: None, + }) + } + + pub fn session(&self) -> &Session { + &self.session + } + + /// Whether the relay session on the active topic is ready. + pub fn is_ready(&self) -> bool { + self.active_link().is_some_and(Link::is_ready) + } + + fn active_link(&self) -> Option<&Link> { + self.session_link.as_ref().or(self.pairing.as_ref()) + } + + fn terminal_error(&self) -> Option { + self.terminal.map(Terminal::error) + } + + /// Stop all traffic, report outstanding sends, and release both links. + fn close(&mut self, terminal: Terminal) { + // Keep the first cause. A later `disconnect()` on an already closed + // client must not replace why it actually stopped. + self.terminal.get_or_insert(terminal); + self.session.state = SessionState::Disconnected; + // Nothing can use a pending proposal's session key or our proposal + // keypair any more, so do not keep them in memory until the client + // is dropped. + self.handshake = Handshake::Idle; + if let Some(mut link) = self.pairing.take() { + link.reliability.fail_all(); + } + if let Some(mut link) = self.session_link.take() { + link.reliability.fail_all(); + } + } + + fn active_topic(&self) -> &Topic { + &self.session.topic + } + + fn link(&self, topic: &Topic) -> Option<&Link> { + if self + .pairing + .as_ref() + .is_some_and(|link| link.topic == *topic) + { + return self.pairing.as_ref(); + } + self.session_link + .as_ref() + .filter(|link| link.topic == *topic) + } + + fn link_mut(&mut self, topic: &Topic) -> Option<&mut Link> { + if self + .pairing + .as_ref() + .is_some_and(|link| link.topic == *topic) + { + return self.pairing.as_mut(); + } + self.session_link + .as_mut() + .filter(|link| link.topic == *topic) + } + + /// Apply one transport lifecycle item, returning a relay frame if present. + fn handle_inbox_item(&mut self, item: Inbox) -> Result> { + match item { + Inbox::Frame(frame) => Ok(Some(frame)), + Inbox::Connected(topic) => { + self.set_connected(&topic, true); + Ok(None) + } + Inbox::Disconnected(topic) => { + self.set_connected(&topic, false); + Ok(None) + } + Inbox::Closed { topic, reason } => { + let active = topic == *self.active_topic(); + if let Some(link) = self.link_mut(&topic) { + link.reliability.fail_all(); + } + self.set_connected(&topic, false); + if active { + self.close(Terminal::Transport(reason)); + return Err(ClientError::Transport(reason)); + } + log::debug!("relay link closed for inactive topic {}", topic.log_tag()); + Ok(None) + } + Inbox::Retire(topic) => { + if self + .pairing + .as_ref() + .is_some_and(|link| link.topic == topic) + { + log::debug!("retiring pairing link {}", topic.log_tag()); + self.retire_pairing(); + } + Ok(None) + } + Inbox::SessionTimeout(topic) => { + // Only a link the proposer never joined is abandoned. A peer + // that joined and is briefly away is handled like any other + // disconnect. That includes one that joined after the timer + // fired but before we got to this item: the session works, + // and closing it would only be for the timer's sake. + let abandoned = self + .session_link + .as_ref() + .is_some_and(|link| link.topic == topic && !link.has_joined()); + if abandoned { + log::warn!("session link {} was never joined; closing", topic.log_tag()); + self.close(Terminal::NotEstablished); + return Err(ClientError::SessionNotEstablished); + } + Ok(None) + } + } + } + + /// Await the next relay frame, folding in transport lifecycle events. + /// + /// Processing a frame can close the client, for example an inbound + /// `disconnect`. After that no link is left to feed the inbox, so check + /// for a terminal state before every wait rather than only on entry to + /// the public method. + async fn next_frame(&mut self) -> Result { + loop { + if let Some(error) = self.terminal_error() { + return Err(error); + } + let item = self.inbox.recv().await.ok_or(ClientError::Closed)?; + if let Some(frame) = self.handle_inbox_item(item)? { + return Ok(frame); + } + } + } + + /// Process one relay frame's body. + async fn handle_frame( + &mut self, + frame: RelayFrame, + deliver: bool, + ) -> Result> { + if matches!(&frame.body, RelayFrameBody::Message { .. }) { + return self.handle_message_frame(frame, deliver).await; + } + + match frame.body { + RelayFrameBody::SessionReady => { + // A `peer_disconnected` set `Disconnected`; the peer is back. + if frame.topic == *self.active_topic() + && matches!(self.handshake, Handshake::Established) + { + self.session.state = SessionState::Active; + } + Ok(None) + } + RelayFrameBody::PeerDisconnected => { + if frame.topic == *self.active_topic() { + // The transport clears the shared readiness flag before + // forwarding this frame. + self.session.state = SessionState::Disconnected; + return Err(ClientError::PeerDisconnected); + } + Ok(None) + } + RelayFrameBody::Message { .. } => unreachable!("handled above"), + } + } + + fn set_connected(&mut self, topic: &Topic, connected: bool) { + let active = *topic == *self.active_topic(); + let Some(link) = self.link_mut(topic) else { + return; + }; + + if connected { + if link.saw_disconnect { + link.saw_disconnect = false; + if active { + link.reliability.emit(ClientEvent::Reconnected); + } + } + } else if !link.saw_disconnect { + link.saw_disconnect = true; + if active { + link.reliability.emit(ClientEvent::Reconnecting); + } + } + } + + /// Wait until the relay reports the active topic ready. + /// + /// Before the handshake this waits on the pairing topic. After the + /// handshake it waits on the derived session topic. Messages received + /// while waiting are queued for the next [`Client::recv`]. + /// + /// See the [`Client`] docs for cancellation and which errors are terminal. + pub async fn wait_session_ready(&mut self) -> Result<()> { + if let Some(error) = self.terminal_error() { + return Err(error); + } + while !self.is_ready() { + let frame = self.next_frame().await?; + // Consume acknowledgements and retransmissions that arrive while + // waiting. Application messages are queued for the next `recv` + // while there is room; otherwise they are left unacknowledged so + // the peer retries later. + let deliver = self.pending.len() < MAX_PENDING_MESSAGES; + if let Some(message) = self.handle_frame(frame, deliver).await? { + self.pending.push_back(message); + } + } + if matches!(self.handshake, Handshake::Established) { + self.session.state = SessionState::Active; + } + Ok(()) + } + + /// Seal and send an application message, returning its envelope id. + /// + /// Handshake messages must use [`Client::propose`], [`Client::approve`] + /// and [`Client::reject`], which also update the handshake state. + /// Acknowledgements are sent automatically after a message passes the + /// receive checks; [`ClientMessage::Ack`] is therefore rejected here. + /// + /// Application messages are refused until the handshake is established, + /// then use the derived session topic. + /// + /// A tracked send reserves pending/outcome capacity until its delivery + /// event is consumed. Applications that only call `send`/`recv` must + /// still drain [`Client::poll_event`] or [`Client::next_event`]; once 256 + /// sends are pending or their outcomes are unconsumed, sends return + /// [`ClientError::Busy`]. + pub async fn send(&mut self, message: &ClientMessage) -> Result { + if let Some(error) = self.terminal_error() { + return Err(error); + } + match message { + ClientMessage::Proposal(_) | ClientMessage::Approve(_) | ClientMessage::Reject(_) => { + return Err(ClientError::UnexpectedHandshake); + } + ClientMessage::Ack(_) => { + return Err(ClientError::ProtocolViolation( + "acknowledgements are sent automatically", + )); + } + ClientMessage::Disconnect(_) | ClientMessage::SessionDelete(_) => { + return Err(ClientError::ProtocolViolation( + "end the session with disconnect() or session_delete()", + )); + } + // The receiver drops these without an ack, so sending one would + // only end in `Failed` after the whole retry budget. + ClientMessage::Response(response) if !response.is_valid() => { + return Err(ClientError::ProtocolViolation( + "response must carry exactly one of response or error", + )); + } + _ => {} + } + self.ensure_session_ready()?; + let topic = self.active_topic().clone(); + self.send_on(&topic, message).await + } + + /// Whether application messages may be sent. + fn ensure_session_ready(&self) -> Result<()> { + if !matches!(self.handshake, Handshake::Established) { + return Err(ClientError::SessionNotActive); + } + if !self.active_link().is_some_and(Link::is_ready) { + return Err(ClientError::NotReady); + } + Ok(()) + } + + async fn send_on(&mut self, topic: &Topic, message: &ClientMessage) -> Result { + let id = random::id()?; + let track = requires_ack(message.message_type()); + self.send_with_id_on(topic, id.clone(), message, track) + .await?; + Ok(id) + } + + /// Seal and send a message with a caller-chosen envelope id, tracking it + /// for retransmission when `track` is set. + async fn send_with_id_on( + &mut self, + topic: &Topic, + id: MessageId, + message: &ClientMessage, + track: bool, + ) -> Result<()> { + let did = self.did.clone(); + let role = self.session.role; + let kind = message.message_type(); + let plaintext = message.to_bytes()?; + let ts = unix_now(); + let aad = Aad::new(&id, kind, topic, &did, ts, role).to_bytes(); + + let link = self.link_mut(topic).ok_or(ClientError::Closed)?; + let sealed = link.cipher.seal(&aad, &plaintext)?; + let wire = Message::new(kind, did, ts, sealed.nonce, sealed.data); + let frame = RelayFrame { + v: RelayFrame::VERSION, + id, + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: serde_json::to_string(&wire)?, + }, + }; + link.reliability.dispatch(frame, track, ts) + } + + /// Receive the next application message, processing acknowledgements and + /// lifecycle traffic while waiting. + /// + /// See the [`Client`] docs for cancellation and which errors are terminal. + pub async fn recv(&mut self) -> Result { + // Messages queued and already acknowledged before the link became + // terminal are still owed to the application. + if let Some(message) = self.pending.pop_front() { + return Ok(message); + } + if let Some(error) = self.terminal_error() { + return Err(error); + } + + loop { + let frame = self.next_frame().await?; + if let Some(message) = self.handle_frame(frame, true).await? { + return Ok(message); + } + } + } + + /// Process one `message` frame. Returns the message to deliver, or `None` + /// for acknowledgements, retransmissions and envelopes for inactive + /// handshake state. + async fn handle_message_frame( + &mut self, + frame: RelayFrame, + deliver: bool, + ) -> Result> { + let Some(envelope) = self.authenticate_frame(frame) else { + return Ok(None); + }; + self.process_envelope(envelope, deliver).await + } + + /// Apply wire, sender, topic and cryptographic checks to a frame. + /// + /// This does not mutate client state. The plaintext is returned unparsed + /// so the caller can preserve replay-classification ordering before + /// interpreting it. + fn authenticate_frame(&self, frame: RelayFrame) -> Option { + let RelayFrame { + id, topic, body, .. + } = frame; + let RelayFrameBody::Message { payload } = body else { + return None; + }; + + let Some(link) = self.link(&topic) else { + log::warn!("dropping frame for unknown topic {}", topic.log_tag()); + return None; + }; + + let wire: Message = match serde_json::from_str(&payload) { + Ok(wire) => wire, + Err(error) => { + log::warn!( + "dropping malformed envelope on topic {}: {}", + topic.log_tag(), + JsonErrorSummary(&error) + ); + return None; + } + }; + + if wire.from == self.did { + log::warn!("dropping frame from own identity {}", wire.from); + return None; + } + if let Some(counterpart) = &self.session.peer_did { + if wire.from != *counterpart { + log::warn!( + "dropping frame from {}; established counterpart is {}", + wire.from, + counterpart + ); + return None; + } + } else if topic != self.session.pairing_topic { + log::warn!("dropping session-topic frame before the counterpart is established"); + return None; + } + + if wire.version != Message::VERSION { + log::warn!("dropping frame with unsupported version {}", wire.version); + return None; + } + let now = unix_now(); + if now.abs_diff(wire.ts) > MAX_TS_SKEW_SECS { + log::warn!("dropping frame with stale timestamp ts={}", wire.ts); + return None; + } + if link.replay.is_stale(wire.ts) { + log::warn!("dropping frame with discarded timestamp ts={}", wire.ts); + return None; + } + + let role = self.session.role; + let aad = Aad::new( + &id, + wire.kind, + &topic, + &wire.from, + wire.ts, + role.counterpart(), + ) + .to_bytes(); + let sealed = SealedPayload { + nonce: wire.nonce.clone(), + data: wire.data.clone(), + }; + let plaintext = match link.cipher.open(&aad, &sealed) { + Ok(bytes) => bytes, + Err(error) => { + log::warn!( + "dropping unauthenticated envelope on topic {}: {error}", + topic.log_tag() + ); + return None; + } + }; + + // The pairing key is for the handshake only. Application kinds on the + // pairing topic are dropped even after the session is established, so + // a leaked pairing key cannot bypass the session key. Conversely, the + // session topic carries application traffic only. + if !self.allowed_on_topic(&topic, wire.kind) { + log::warn!( + "dropping {} on topic {}", + wire.kind.as_str(), + topic.log_tag() + ); + return None; + } + + Some(InboundEnvelope { + id, + topic, + wire, + plaintext, + now, + }) + } + + /// Whether `kind` may travel on `topic`. + fn allowed_on_topic(&self, topic: &Topic, kind: MessageType) -> bool { + if *topic == self.session.pairing_topic { + kind.is_handshake() || kind == MessageType::Ack + } else { + kind.is_application() + } + } + + /// Whether a handshake message arrived after the handshake completed. + fn is_late_handshake(&self, message: &ClientMessage) -> bool { + matches!(self.handshake, Handshake::Established) + && matches!( + message, + ClientMessage::Proposal(_) | ClientMessage::Approve(_) | ClientMessage::Reject(_) + ) + } + + /// Apply replay and handshake semantics to an authenticated frame. + /// + /// When `deliver` is false there is no room to queue a new message for + /// the application. + async fn process_envelope( + &mut self, + envelope: InboundEnvelope, + deliver: bool, + ) -> Result> { + let InboundEnvelope { + id, + topic, + wire, + plaintext, + now, + } = envelope; + + // A `disconnect` or `session_delete` is sent once: its sender closes + // straight after sending it and never retransmits it, so dropping one + // for lack of room would lose it for good. It ends the session, so + // letting it through grows the replay memory and the pending queue by + // one at most. + let one_shot = matches!( + wire.kind, + MessageType::Disconnect | MessageType::SessionDelete + ); + + let observation = self + .link_mut(&topic) + .expect("topic was checked") + .replay + .classify(&id, &wire, now); + match observation { + Observation::Retransmission => { + if requires_ack(wire.kind) { + self.send_ack(&id, &topic).await?; + } + log::debug!("re-acknowledged retransmission {id}"); + return Ok(None); + } + Observation::Conflict => { + return Err(ClientError::ProtocolViolation( + "envelope reuses a frame id or nonce with different content", + )); + } + // Dropping an ack would report a delivered message as `Failed`, + // so let it through; `commit_ack` decides whether to record it. + Observation::Full if wire.kind != MessageType::Ack && !one_shot => { + log::warn!("dropping envelope: replay memory is full"); + return Ok(None); + } + Observation::Full | Observation::New => {} + } + let has_room = observation == Observation::New; + + // While `wait_session_ready`/`next_event` has no room to queue a new + // message, drop it without recording or acknowledging it, so the peer + // retransmits it later instead of the application silently losing it. + // This comes after replay classification so that a retransmission of + // something we already accepted is still re-acknowledged above. + if !deliver && wire.kind != MessageType::Ack && !one_shot { + log::warn!("dropping message: pending queue is full"); + return Ok(None); + } + + let message = match serde_json::from_slice::(&plaintext) { + Ok(message) => message, + Err(error) => { + log::warn!( + "dropping malformed plaintext on topic {}: {}", + topic.log_tag(), + JsonErrorSummary(&error) + ); + return Ok(None); + } + }; + if message.message_type() != wire.kind { + log::warn!( + "dropping envelope: plaintext type does not match kind {}", + wire.kind.as_str() + ); + return Ok(None); + } + + if let ClientMessage::Response(response) = &message + && !response.is_valid() + { + log::warn!("dropping response without exactly one of response or error"); + return Ok(None); + } + + let terminates = matches!( + &message, + ClientMessage::Disconnect(_) | ClientMessage::SessionDelete(_) + ); + if terminates { + self.session.state = SessionState::Disconnected; + } + + // acks are consumed by reliability + if let ClientMessage::Ack(ack) = &message { + self.commit_ack(&id, &topic, &wire, ack, has_room); + return Ok(None); + } + + // Once established, the pairing key may no longer create new handshake + // state. Retransmissions of the handshake were re-acked above. + if self.is_late_handshake(&message) { + log::warn!("dropping handshake message after establishment"); + return Ok(None); + } + + // An `approve` establishes the session while `observe` runs. Record it + // before that so the pairing replay memory keeps the envelope. + let rekeys = matches!(&message, ClientMessage::Approve(_)); + if rekeys { + let link = self.link_mut(&topic).expect("topic was checked"); + link.replay.record(&id, &wire); + } + + if topic == self.session.pairing_topic + && let Err(error) = self.observe(&id, &message) + { + if let Some(link) = self.link_mut(&topic) { + link.replay.forget(&id); + } + return Err(error); + } + self.pin_counterpart(&topic, &wire.from); + + if requires_ack(message.message_type()) { + let acked = self.send_ack(&id, &topic).await; + // Act on a disconnect even if we could not ack it, for the same + // reason as above; only the peer's bookkeeping misses the ack. + // A handshake message has already changed our state in `observe`, + // and its retransmission would be refused or only re-acked, so it + // too must reach the application now or it never will. + let committed = terminates || topic == self.session.pairing_topic; + if !committed { + acked?; + } + } + + if !rekeys { + let link = self.link_mut(&topic).expect("topic was checked"); + link.replay.record(&id, &wire); + } + + if terminates { + // The peer ended the session. Deliver this final message, then + // make every later operation observe a terminal client. + self.close(Terminal::Closed); + } + + Ok(Some(message)) + } + + /// Pin the sender of the first envelope we accept on the pairing topic as + /// the counterpart. It stays the counterpart for the session topic and + /// across reconnects. + /// + /// This happens only once the envelope is accepted, not as soon as it + /// authenticates. Otherwise a pairing-key holder could get itself pinned + /// with a single message we then refuse (a proposal to a proposer, say), + /// and every frame from the real peer would be dropped from then on. + fn pin_counterpart(&mut self, topic: &Topic, from: &DidKey) { + if *topic == self.session.pairing_topic && self.session.peer_did.is_none() { + self.session.peer_did = Some(from.clone()); + log::debug!("established counterpart {from}"); + } + } + + /// Process an inbound ack and report delivery. + /// + /// `has_room` says whether the replay memory has room for a new record. + /// An ack that completes one of our sends is recorded even when it does + /// not, up to a fixed headroom, so a conflicting copy of it is still + /// caught. An ack that completes nothing has no effect, so it is neither + /// recorded nor allowed to establish the counterpart: otherwise a + /// pairing-key holder could fill the replay memory, or get itself + /// pinned, by acking made-up ids. + fn commit_ack( + &mut self, + id: &MessageId, + topic: &Topic, + wire: &Message, + ack: &AckPayload, + has_room: bool, + ) { + let ack_id = ack.ack_id.clone(); + let retires_pairing = + *topic == self.session.pairing_topic && self.pairing_approval.as_ref() == Some(&ack_id); + let link = self.link_mut(topic).expect("topic was checked"); + let completed = link.reliability.mark_delivered(&ack_id); + if completed && (has_room || link.replay.has_ack_headroom()) { + link.replay.record(id, wire); + } + if completed { + self.pin_counterpart(topic, &wire.from); + } + // A late ack for an approve we already gave up on completes nothing, + // and like any such ack it must have no effect. + if retires_pairing && completed { + self.retire_pairing(); + } + } + + /// Acknowledge a received envelope by id, on the topic it arrived on. + async fn send_ack(&mut self, ack_id: &MessageId, topic: &Topic) -> Result<()> { + let result = self + .send_on( + topic, + &ClientMessage::Ack(AckPayload { + ack_id: ack_id.clone(), + }), + ) + .await; + match result { + Ok(_) => Ok(()), + Err(ClientError::Busy) => { + // The peer retransmits unacknowledged messages; dropping this + // ack under local backpressure is recoverable. + log::warn!("dropping ack: outbound queue is full"); + Ok(()) + } + // A link's transport closes its outbound queue only once it has + // stopped and put its `Closed` in the inbox, behind every frame + // it received before. So an ack that finds the queue closed is + // followed by that `Closed`, which says what happened: it closes + // the client if this is the active link and only drops the link + // if it is not. Answering `Closed` here instead would lose the + // message we are acking and report the wrong terminal cause. + Err(ClientError::Closed) => { + log::debug!("dropping ack: relay link {} is closed", topic.log_tag()); + Ok(()) + } + Err(error) => Err(error), + } + } + + /// Non-blocking read of the next reliability event, if any. + /// + /// This does not process inbound frames. Call [`Client::recv`] or + /// [`Client::next_event`] to drive acknowledgements and delivery. + pub fn poll_event(&mut self) -> Option { + let event = self + .outcomes + .try_recv() + .ok() + .map(|(event, _permit)| event) + .or_else(|| self.lifecycle.try_recv().ok())?; + Some(self.received_event(event)) + } + + fn received_event(&mut self, event: ClientEvent) -> ClientEvent { + match &event { + ClientEvent::Delivered { id } => { + if self.pairing_proposal.as_ref() == Some(id) { + self.pairing_proposal = None; + } + } + ClientEvent::Failed { id, .. } => { + if self.pairing_approval.as_ref() == Some(id) { + self.retire_pairing(); + } + if self.pairing_proposal.as_ref() == Some(id) { + self.pairing_proposal = None; + if matches!(self.handshake, Handshake::Proposed { .. }) { + self.handshake = Handshake::Idle; + if self.session.state == SessionState::ProposalSent { + self.session.state = SessionState::Idle; + } + } + } + } + ClientEvent::Reconnecting | ClientEvent::Reconnected => {} + } + event + } + + /// Await the next reliability event while processing inbound frames. + /// + /// Use this instead of polling [`Client::poll_event`] when acknowledgements + /// or lifecycle traffic may arrive while the application waits. Delivery + /// outcomes are returned before lifecycle events, so the two are not + /// ordered relative to each other. + /// + /// See the [`Client`] docs for cancellation and which errors are terminal. + pub async fn next_event(&mut self) -> Result { + loop { + // Outcomes are still owed after a terminal transition; drain them + // before surfacing the terminal error. + if let Ok((event, _permit)) = self.outcomes.try_recv() { + return Ok(self.received_event(event)); + } + if let Ok(event) = self.lifecycle.try_recv() { + return Ok(self.received_event(event)); + } + if let Some(error) = self.terminal_error() { + return Err(error); + } + + tokio::select! { + item = self.inbox.recv() => { + let item = item.ok_or(ClientError::Closed)?; + match self.handle_next_event_item(item).await { + // Closing reports every outstanding send as `Failed`. + // Go round again so those come out before the error, + // which the next pass returns once they are drained. + Err(_) if self.terminal.is_some() => {} + result => result?, + } + } + event = self.outcomes.recv() => { + let (event, _permit) = event.ok_or(ClientError::Closed)?; + return Ok(self.received_event(event)); + } + event = self.lifecycle.recv() => { + let event = event.ok_or(ClientError::Closed)?; + return Ok(self.received_event(event)); + } + } + } + } + + /// Process one inbox item for [`Client::next_event`], queueing any message + /// for a later [`Client::recv`]. + async fn handle_next_event_item(&mut self, item: Inbox) -> Result<()> { + if let Some(frame) = self.handle_inbox_item(item)? { + let deliver = self.pending.len() < MAX_PENDING_MESSAGES; + if let Some(message) = self.handle_frame(frame, deliver).await? { + self.pending.push_back(message); + } + } + Ok(()) + } + + /// Drop the pairing connection once the handshake no longer needs it. + fn retire_pairing(&mut self) { + let Some(mut link) = self.pairing.take() else { + return; + }; + log::debug!("retiring pairing link {}", link.topic.log_tag()); + link.reliability.fail_all(); + } + + /// Update handshake state from an inbound pairing message carried by + /// frame `id`. + fn observe(&mut self, id: &MessageId, message: &ClientMessage) -> Result<()> { + // Proposals come from the proposer; approves and rejects come from + // the responder. Without this a pairing-key holder could, say, push + // an idle proposer into `PeerProposed`, after which it could neither + // propose (wrong state) nor approve (wrong role). + let sender = match message { + ClientMessage::Proposal(_) => Some(Role::Proposer), + ClientMessage::Approve(_) | ClientMessage::Reject(_) => Some(Role::Responder), + _ => None, + }; + if sender.is_some_and(|sender| sender != self.session.role.counterpart()) { + return Err(ClientError::UnexpectedHandshake); + } + + match message { + ClientMessage::Proposal(proposal) => { + // The proposer starts over with a fresh keypair when its + // proposal fails to be acknowledged. Until we approve, the + // newest proposal replaces the pending one, so our approve + // answers the proposal the proposer is still waiting on. + if !matches!( + self.handshake, + Handshake::Idle | Handshake::PeerProposed { .. } + ) { + return Err(ClientError::UnexpectedHandshake); + } + let peer_public = decode_public_key(&proposal.ephemeral_public_key)?; + // Derive now, while the proposal is being accepted, so a + // low-order peer key is rejected before this proposal is + // acknowledged or changes the handshake state. + let keypair = EphemeralKeyPair::generate(); + let public_key = keypair.public_key_encoded(); + let (key, topic) = keypair.derive(&peer_public)?; + self.handshake = Handshake::PeerProposed { + proposal_id: id.clone(), + proposal: proposal.clone(), + public_key, + key, + topic, + }; + self.session.state = SessionState::ProposalReceived; + } + ClientMessage::Approve(approve) => { + let Handshake::Proposed { proposal_id, .. } = &self.handshake else { + return Err(ClientError::UnexpectedHandshake); + }; + // An approve for an earlier proposal carries a key derived + // from that proposal's keypair, which we no longer hold. + // Accepting it would put us on a different session topic + // from the responder, with neither side ever noticing. + if approve.proposal_id != *proposal_id { + return Err(ClientError::UnexpectedHandshake); + } + let peer_public = decode_public_key(&approve.ephemeral_public_key)?; + // Keep the proposal keypair until the peer's key is known to + // produce a usable shared secret, so a weak approve cannot + // strand the proposer in `Idle`. + validate_peer_public(&peer_public)?; + let Handshake::Proposed { keypair, .. } = + std::mem::replace(&mut self.handshake, Handshake::Idle) + else { + unreachable!("state checked above"); + }; + let (key, topic) = keypair.derive(&peer_public)?; + // A valid approve proves the peer received the proposal, even + // when its explicit proposal ack was lost. + if let Some(proposal_id) = self.pairing_proposal.take() + && let Some(link) = self.pairing.as_mut() + { + link.reliability.mark_delivered(&proposal_id); + } + let cipher = match self.session_cipher(&key) { + Ok(cipher) => cipher, + Err(error) => { + // The keypair is spent, so this proposal can never + // be completed. Leave the proposer where a failed + // proposal leaves it, free to propose again. + self.session.state = SessionState::Idle; + return Err(error); + } + }; + self.establish_session(cipher, topic); + } + ClientMessage::Reject(reject) => { + // A reject answers our outstanding proposal. Drop its keypair + // so a late approve for it cannot establish anything; the + // application may propose again. + let Handshake::Proposed { proposal_id, .. } = &self.handshake else { + return Err(ClientError::UnexpectedHandshake); + }; + // Like an approve, it names that proposal. A retransmitted + // reject of an earlier proposal must not end the current one + // or count as its delivery. + if reject.proposal_id != *proposal_id { + return Err(ClientError::UnexpectedHandshake); + } + self.handshake = Handshake::Idle; + // Like an approve, a reject proves the proposal arrived. + if let Some(proposal_id) = self.pairing_proposal.take() + && let Some(link) = self.pairing.as_mut() + { + link.reliability.mark_delivered(&proposal_id); + } + self.session.state = SessionState::Rejected; + } + _ => {} + } + Ok(()) + } + + /// Start the session-topic connection and keep the pairing link alive + /// until its handshake acknowledgements have had their retry window. + fn establish_session(&mut self, cipher: C, topic: SessionTopic) { + let session_topic = topic.as_topic().clone(); + let link = Link::new( + &self.config, + &self.identity, + self.session.role, + session_topic.clone(), + cipher, + self.lifecycle_tx.clone(), + self.outcomes_tx.clone(), + &self.inbox_tx, + ); + + self.session_link = Some(link); + self.session.topic = session_topic; + self.handshake = Handshake::Established; + self.session.state = SessionState::Active; + self.schedule_pairing_retirement(); + } + + /// A fresh cipher for the derived session key. + fn session_cipher(&self, key: &SessionKey) -> Result { + Ok(self + .pairing + .as_ref() + .ok_or(ClientError::Closed)? + .cipher + .for_key(key.as_bytes())?) + } + + /// Close the client if the proposer has not joined the session link by + /// the join timeout after the handshake retry window. + /// + /// This is armed when the approve goes out, whatever happens to it. Its + /// ack proves nothing, since anyone holding the pairing key can send one, + /// and its `Failed` proves nothing either (§9.1). Only `session_ready` on + /// the session link shows the proposer derived the same session topic. + fn schedule_session_timeout(&self) { + let Some(topic) = self.session_link.as_ref().map(|link| link.topic.clone()) else { + return; + }; + let window = self + .pairing_retirement_window() + .saturating_add(self.config.session_join_timeout); + let inbox = self.inbox_tx.clone(); + tokio::spawn(async move { + tokio::time::sleep(window).await; + let _ = inbox.send(Inbox::SessionTimeout(topic)).await; + }); + } + + /// Retire the pairing connection after the handshake ack retry window. + fn schedule_pairing_retirement(&self) { + let window = self.pairing_retirement_window(); + let inbox = self.inbox_tx.clone(); + let topic = self.session.pairing_topic.clone(); + tokio::spawn(async move { + tokio::time::sleep(window).await; + // Wait for inbox capacity instead of dropping the only retirement + // signal. The send fails once the client and its receiver are gone. + let _ = inbox.send(Inbox::Retire(topic)).await; + }); + } + + /// Upper bound on how long handshake retransmissions can still arrive. + fn pairing_retirement_window(&self) -> Duration { + let attempts = self.config.ack_max_attempts.min(31) as u32; + let factor = 2u32.saturating_pow(attempts.saturating_add(1)); + self.config + .ack_base_delay + .saturating_mul(factor.saturating_sub(1)) + .saturating_add(Duration::from_secs(1)) + .clamp(Duration::from_secs(1), MAX_RETRY_DELAY) + } + + /// Send a `proposal` carrying ephemeral public key. + /// + /// Returns the proposal's envelope id, which its `Delivered` or `Failed` + /// event carries. + pub async fn propose(&mut self, proposal: Value) -> Result { + if let Some(error) = self.terminal_error() { + return Err(error); + } + if self.session.role != Role::Proposer { + return Err(ClientError::ProtocolViolation( + "only the proposer may propose", + )); + } + if !matches!(self.handshake, Handshake::Idle) { + return Err(ClientError::UnexpectedHandshake); + } + if !self.pairing.as_ref().is_some_and(Link::is_ready) { + return Err(ClientError::NotReady); + } + let keypair = EphemeralKeyPair::generate(); + let payload = ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: session_expiry(), + proposal: Opaque(serde_json::to_vec(&proposal)?), + }; + let topic = self.session.pairing_topic.clone(); + let proposal_id = self + .send_on(&topic, &ClientMessage::Proposal(payload)) + .await?; + self.pairing_proposal = Some(proposal_id.clone()); + self.handshake = Handshake::Proposed { + proposal_id: proposal_id.clone(), + keypair, + }; + self.session.state = SessionState::ProposalSent; + Ok(proposal_id) + } + + /// Approve `proposal`, sending an `approve` carrying our ephemeral public + /// key, and switch to the session topic and key. + /// + /// `proposal` is the one the application showed the user. A newer + /// proposal from the counterpart replaces the pending one, and is + /// delivered through [`Client::recv`] like the first; if that happened in + /// the meantime this returns [`ClientError::ProposalSuperseded`] rather + /// than approve terms the user never saw. A newer proposal identical to + /// `proposal` in every field has the same terms, so it is approved. + /// + /// Returns the approve's envelope id, which its `Delivered` or `Failed` + /// event carries. + pub async fn approve( + &mut self, + proposal: &ProposalPayload, + approval: Value, + ) -> Result { + if let Some(error) = self.terminal_error() { + return Err(error); + } + if self.session.role != Role::Responder { + return Err(ClientError::ProtocolViolation( + "only the responder may approve", + )); + } + let (proposal_id, public_key, key, topic) = match &self.handshake { + Handshake::PeerProposed { + proposal_id, + proposal: pending, + public_key, + key, + topic, + } => { + if pending != proposal { + return Err(ClientError::ProposalSuperseded); + } + ( + proposal_id.clone(), + public_key.clone(), + key.clone(), + topic.clone(), + ) + } + _ => return Err(ClientError::UnexpectedHandshake), + }; + if !self.pairing.as_ref().is_some_and(Link::is_ready) { + return Err(ClientError::NotReady); + } + // Everything that can fail happens before the approve goes out. Once + // it is on the wire the proposer may establish the session, and we + // must then be able to as well. + let cipher = self.session_cipher(&key)?; + let payload = ApprovePayload { + proposal_id, + ephemeral_public_key: public_key, + approval: Opaque(serde_json::to_vec(&approval)?), + }; + let pairing_topic = self.session.pairing_topic.clone(); + let approve_id = self + .send_on(&pairing_topic, &ClientMessage::Approve(payload)) + .await?; + self.pairing_approval = Some(approve_id.clone()); + self.establish_session(cipher, topic); + self.schedule_session_timeout(); + Ok(approve_id) + } + + /// Reject `proposal` and move to `Rejected`. + /// + /// As with [`Client::approve`], `proposal` is the one the application + /// showed the user, and this returns [`ClientError::ProposalSuperseded`] + /// if a newer one has replaced it. Rejecting also forgets the session key + /// derived for the proposal, so a later `approve` fails until a new + /// proposal arrives. + pub async fn reject( + &mut self, + proposal: &ProposalPayload, + code: u32, + message: impl Into, + ) -> Result<()> { + if let Some(error) = self.terminal_error() { + return Err(error); + } + if self.session.role != Role::Responder { + return Err(ClientError::ProtocolViolation( + "only the responder may reject", + )); + } + let Handshake::PeerProposed { + proposal_id, + proposal: pending, + .. + } = &self.handshake + else { + return Err(ClientError::UnexpectedHandshake); + }; + if pending != proposal { + return Err(ClientError::ProposalSuperseded); + } + let proposal_id = proposal_id.clone(); + if !self.pairing.as_ref().is_some_and(Link::is_ready) { + return Err(ClientError::NotReady); + } + let topic = self.session.pairing_topic.clone(); + self.send_on( + &topic, + &ClientMessage::Reject(RejectPayload { + proposal_id, + code, + message: message.into(), + }), + ) + .await?; + self.handshake = Handshake::Idle; + self.session.state = SessionState::Rejected; + Ok(()) + } + + /// Send a `request` and return its correlation id. + /// + /// The JSON value is encoded into the protocol's opaque `request` field. + pub async fn request(&mut self, request: Value) -> Result { + if let Some(error) = self.terminal_error() { + return Err(error); + } + self.ensure_session_ready()?; + let id = random::id()?; + let request_id = id.to_string(); + let payload = RequestPayload { + request_id: request_id.clone(), + request: opaque(request)?, + }; + let topic = self.active_topic().clone(); + self.send_with_id_on(&topic, id, &ClientMessage::Request(payload), true) + .await?; + Ok(request_id) + } + + /// Send a `response` (or error) for a request. + /// + /// Each JSON value is encoded into its opaque `response` or `error` field. + pub async fn respond( + &mut self, + request_id: impl Into, + response: Option, + error: Option, + ) -> Result<()> { + let payload = ResponsePayload { + request_id: request_id.into(), + response: response.map(opaque).transpose()?, + error: error.map(opaque).transpose()?, + }; + self.send(&ClientMessage::Response(payload)).await?; + Ok(()) + } + + /// Gracefully disconnect. + /// + /// See [`Client::session_delete`] for how the peer is notified. + pub async fn disconnect(&mut self, reason: impl Into, code: u32) -> Result<()> { + self.end_session(ClientMessage::Disconnect(DisconnectPayload { + reason: reason.into(), + code, + message: String::new(), + })) + .await + } + + /// Tell the peer the session was deleted, then close. + /// + /// The local client is closed even when the peer cannot be notified, for + /// example because the link is not ready; the notification error is + /// returned after the teardown. + /// + /// The notification is best effort. `Ok` means it was queued: it is + /// written ahead of the connection closing, but nothing retransmits it, + /// and it produces no `Delivered` or `Failed` event. If the socket fails + /// first, the peer instead learns of the end through `peer_disconnected` + /// once its grace window passes. + pub async fn session_delete(&mut self, code: u32, message: impl Into) -> Result<()> { + self.end_session(ClientMessage::SessionDelete(SessionDeletePayload { + code, + message: message.into(), + })) + .await + } + + /// Send a final, untracked message and close the client. + async fn end_session(&mut self, message: ClientMessage) -> Result<()> { + let result = self.send_final(&message).await; + self.session.state = SessionState::Disconnected; + self.close(Terminal::Closed); + result + } + + async fn send_final(&mut self, message: &ClientMessage) -> Result<()> { + if let Some(error) = self.terminal_error() { + return Err(error); + } + self.ensure_session_ready()?; + let topic = self.active_topic().clone(); + let id = random::id()?; + self.send_with_id_on(&topic, id, message, false).await + } +} + +/// Encode a JSON application value as the protocol's opaque payload. +fn opaque(value: Value) -> Result { + Ok(Opaque(serde_json::to_vec(&value)?)) +} + +/// Session expiry timestamp for a fresh proposal. +fn session_expiry() -> u64 { + unix_now().saturating_add(SESSION_EXPIRY.as_secs()) +} diff --git a/crates/client/src/config.rs b/crates/client/src/config.rs new file mode 100644 index 0000000..dbb0a53 --- /dev/null +++ b/crates/client/src/config.rs @@ -0,0 +1,572 @@ +use std::time::Duration; + +use url::Url; + +use crate::error::ClientError; + +/// Longest accepted retransmission delay. +/// +/// Receivers reject envelopes once their `ts` is more than 300 seconds old, so +/// a longer delay cannot produce a useful retry. The cap also keeps retry +/// arithmetic away from `Duration` and `Instant` overflow. +pub(crate) const MAX_RETRY_DELAY: Duration = Duration::from_secs(300); + +/// Longest accepted transport timeout or interval. +/// +/// Deadlines are computed as `Instant::now() + duration`, which panics on +/// overflow. A day is far longer than any of these needs to be. +const MAX_TIMEOUT: Duration = Duration::from_secs(24 * 60 * 60); + +/// Client configuration. +#[derive(Debug, Clone)] +pub struct ClientConfig { + /// Relay WebSocket endpoint used to connect and advertised in pairing URIs. + pub relay_url: String, + + /// Audience (`aud`) expected by the relay in the connection token. + pub audience: String, + + /// Optional registration id sent to the relay as an attribution label. + pub registration_id: Option, + + /// Allow `ws://` relay URLs. Without this, only `wss://` is accepted. + pub allow_insecure_ws: bool, + + /// Lifetime of the signed connection token. Must be at least one second, + /// and leave room for `connection_stability` (see there). + pub token_ttl: Duration, + + /// Maximum time without an inbound frame before the relay is considered dead. + pub idle_timeout: Duration, + + /// Maximum time to establish the WebSocket connection. + pub connect_timeout: Duration, + + /// Maximum time for a single WebSocket write. + pub write_timeout: Duration, + + /// Maximum time to send a close frame and close the socket. + pub close_timeout: Duration, + + /// Base delay before the first retransmission of an un-ACKed message. + /// Must be non-zero and no longer than the 300-second envelope lifetime. + pub ack_base_delay: Duration, + + /// Maximum retransmissions before a message is reported failed. + pub ack_max_attempts: usize, + + /// Minimum spacing between retransmissions. Must be non-zero and no + /// longer than the 300-second envelope lifetime. + pub retransmit_spacing: Duration, + + /// Maximum retransmission bytes per second used to pace reconnects. + pub retransmit_bytes_per_second: usize, + + /// Interval between client keepalive pings. + pub ping_interval: Duration, + + /// How long to wait for a pong before treating the connection as dead. + pub pong_timeout: Duration, + + /// Initial delay before the first reconnect attempt. + pub reconnect_initial_delay: Duration, + + /// Maximum reconnect backoff delay. + pub reconnect_max_delay: Duration, + + /// Maximum reconnect attempts before giving up. + pub reconnect_max_attempts: usize, + + /// How long a connection must stay up before it resets the reconnect budget. + /// + /// A connection waiting for its counterpart may never see `session_ready`, + /// but it is still healthy and should not exhaust its retries on token + /// expiry or ordinary network drops. + /// + /// Must be non-zero, and together with `connect_timeout` shorter than + /// the lifetime a token is sure to have: the whole seconds of + /// `token_ttl`, less one, since tokens carry truncated whole-second `iat` + /// and `exp`. The token is signed before we connect, so the connect + /// itself uses up part of that lifetime. Otherwise a token expiry can + /// arrive before a connection is considered stable, and every routine + /// token renewal spends a reconnect attempt. + pub connection_stability: Duration, + + /// How long a responder keeps a session link that the proposer has not + /// joined, counted from the end of the handshake retry window that starts + /// when it sends `approve`. When it expires the client closes with + /// [`ClientError::SessionNotEstablished`]. + pub session_join_timeout: Duration, +} + +impl ClientConfig { + /// Build a config whose token audience is the same as the relay URL. + pub fn new(relay_url: impl Into) -> Self { + let relay_url = relay_url.into(); + Self { + audience: relay_url.clone(), + relay_url, + registration_id: None, + allow_insecure_ws: false, + token_ttl: Duration::from_secs(300), + idle_timeout: Duration::from_secs(60), + connect_timeout: Duration::from_secs(10), + write_timeout: Duration::from_secs(10), + close_timeout: Duration::from_secs(2), + ack_base_delay: Duration::from_secs(2), + ack_max_attempts: 5, + retransmit_spacing: Duration::from_millis(100), + retransmit_bytes_per_second: 256 * 1024, + ping_interval: Duration::from_secs(30), + pong_timeout: Duration::from_secs(10), + reconnect_initial_delay: Duration::from_millis(250), + reconnect_max_delay: Duration::from_secs(5), + reconnect_max_attempts: 5, + connection_stability: Duration::from_secs(30), + session_join_timeout: Duration::from_secs(30), + } + } + + /// Set the registration id sent to the relay. + pub fn with_registration_id(mut self, registration_id: impl Into) -> Self { + self.registration_id = Some(registration_id.into()); + self + } + + /// Allow an insecure `ws://` relay URL. + pub fn with_insecure_ws(mut self) -> Self { + self.allow_insecure_ws = true; + self + } + + /// Validate the configuration before starting a client. + pub fn validate(&self) -> Result<(), ClientError> { + let url = Url::parse(&self.relay_url) + .map_err(|_| ClientError::InvalidConfig("invalid relay URL"))?; + match url.scheme() { + "wss" => {} + "ws" if self.allow_insecure_ws => {} + "ws" => { + return Err(ClientError::InvalidConfig( + "ws:// relay URL requires explicit opt-in", + )); + } + _ => { + return Err(ClientError::InvalidConfig( + "relay URL must use ws:// or wss://", + )); + } + } + + for (timeout, name) in [ + (self.token_ttl, "token_ttl"), + (self.idle_timeout, "idle_timeout"), + (self.connect_timeout, "connect_timeout"), + (self.write_timeout, "write_timeout"), + (self.close_timeout, "close_timeout"), + (self.ack_base_delay, "ack_base_delay"), + (self.retransmit_spacing, "retransmit_spacing"), + (self.ping_interval, "ping_interval"), + (self.pong_timeout, "pong_timeout"), + (self.connection_stability, "connection_stability"), + (self.session_join_timeout, "session_join_timeout"), + ] { + if timeout.is_zero() { + return Err(ClientError::InvalidConfig(name)); + } + } + + for (delay, name) in [ + (self.ack_base_delay, "ack_base_delay"), + (self.retransmit_spacing, "retransmit_spacing"), + ] { + if delay > MAX_RETRY_DELAY { + return Err(ClientError::InvalidConfig(name)); + } + } + + for (timeout, name) in [ + (self.token_ttl, "token_ttl"), + (self.idle_timeout, "idle_timeout"), + (self.connect_timeout, "connect_timeout"), + (self.write_timeout, "write_timeout"), + (self.close_timeout, "close_timeout"), + (self.ping_interval, "ping_interval"), + (self.pong_timeout, "pong_timeout"), + (self.connection_stability, "connection_stability"), + (self.session_join_timeout, "session_join_timeout"), + (self.reconnect_initial_delay, "reconnect_initial_delay"), + (self.reconnect_max_delay, "reconnect_max_delay"), + ] { + if timeout > MAX_TIMEOUT { + return Err(ClientError::InvalidConfig(name)); + } + } + + // With no attempts, a frame dispatched while offline would be reported + // failed on the next ready edge without ever being written. + if self.ack_max_attempts == 0 { + return Err(ClientError::InvalidConfig("ack_max_attempts")); + } + + // Tokens carry whole-second `iat`/`exp`, so a shorter lifetime would + // produce a token that is already expired. + if self.token_ttl < Duration::from_secs(1) { + return Err(ClientError::InvalidConfig( + "token_ttl must be at least one second", + )); + } + + if self.reconnect_initial_delay > self.reconnect_max_delay { + return Err(ClientError::InvalidConfig( + "reconnect_initial_delay must not exceed reconnect_max_delay", + )); + } + + // `iat` is truncated to a whole second, so a token may already be up + // to a second old when the relay accepts it, and it was signed before + // the connect began. Both durations were bounded above. + let token_lifetime = Duration::from_secs(self.token_ttl.as_secs() - 1); + if self.connect_timeout + self.connection_stability >= token_lifetime { + return Err(ClientError::InvalidConfig( + "connect_timeout plus connection_stability must be shorter than token_ttl less one second", + )); + } + + if self.retransmit_bytes_per_second == 0 { + return Err(ClientError::InvalidConfig("retransmit_bytes_per_second")); + } + + Ok(()) + } + + /// Set the audience expected by the relay, when it differs from `relay_url`. + pub fn with_audience(mut self, audience: impl Into) -> Self { + self.audience = audience.into(); + self + } + + /// Set the connection token lifetime. + pub fn with_token_ttl(mut self, token_ttl: Duration) -> Self { + self.token_ttl = token_ttl; + self + } + + /// Set the inbound idle timeout. + pub fn with_idle_timeout(mut self, idle_timeout: Duration) -> Self { + self.idle_timeout = idle_timeout; + self + } + + /// Set the WebSocket connect timeout. + pub fn with_connect_timeout(mut self, connect_timeout: Duration) -> Self { + self.connect_timeout = connect_timeout; + self + } + + /// Set the WebSocket write timeout. + pub fn with_write_timeout(mut self, write_timeout: Duration) -> Self { + self.write_timeout = write_timeout; + self + } + + /// Set the WebSocket close timeout. + pub fn with_close_timeout(mut self, close_timeout: Duration) -> Self { + self.close_timeout = close_timeout; + self + } + + /// Set the base retransmission delay. + pub fn with_ack_base_delay(mut self, ack_base_delay: Duration) -> Self { + self.ack_base_delay = ack_base_delay; + self + } + + /// Set the maximum retransmission attempts. + pub fn with_ack_max_attempts(mut self, ack_max_attempts: usize) -> Self { + self.ack_max_attempts = ack_max_attempts; + self + } + + /// Set the minimum spacing between retransmissions. + pub fn with_retransmit_spacing(mut self, retransmit_spacing: Duration) -> Self { + self.retransmit_spacing = retransmit_spacing; + self + } + + /// Set the maximum retransmission byte rate. + pub fn with_retransmit_bytes_per_second(mut self, bytes_per_second: usize) -> Self { + self.retransmit_bytes_per_second = bytes_per_second; + self + } + + /// Set the keepalive ping interval. + pub fn with_ping_interval(mut self, ping_interval: Duration) -> Self { + self.ping_interval = ping_interval; + self + } + + /// Set the pong deadline. + pub fn with_pong_timeout(mut self, pong_timeout: Duration) -> Self { + self.pong_timeout = pong_timeout; + self + } + + /// Set the initial reconnect delay. + pub fn with_reconnect_initial_delay(mut self, delay: Duration) -> Self { + self.reconnect_initial_delay = delay; + self + } + + /// Set the maximum reconnect backoff delay. + pub fn with_reconnect_max_delay(mut self, delay: Duration) -> Self { + self.reconnect_max_delay = delay; + self + } + + /// Set the maximum reconnect attempts. + pub fn with_reconnect_max_attempts(mut self, attempts: usize) -> Self { + self.reconnect_max_attempts = attempts; + self + } + + /// Set how long a connection must stay up to reset the reconnect budget. + pub fn with_connection_stability(mut self, stability: Duration) -> Self { + self.connection_stability = stability; + self + } + + /// Set how long an unjoined session link survives a failed `approve`. + pub fn with_session_join_timeout(mut self, timeout: Duration) -> Self { + self.session_join_timeout = timeout; + self + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rejects_insecure_ws_without_opt_in() { + let config = ClientConfig::new("ws://127.0.0.1:8080"); + assert!(matches!( + config.validate(), + Err(ClientError::InvalidConfig( + "ws:// relay URL requires explicit opt-in" + )) + )); + assert!(config.with_insecure_ws().validate().is_ok()); + } + + #[test] + fn requires_websocket_urls() { + assert!(matches!( + ClientConfig::new("https://relay.example.com").validate(), + Err(ClientError::InvalidConfig( + "relay URL must use ws:// or wss://" + )) + )); + assert!( + ClientConfig::new("wss://relay.example.com") + .validate() + .is_ok() + ); + } + + #[test] + fn rejects_timeouts_that_overflow_deadlines() { + let huge = Duration::MAX; + for config in [ + ClientConfig::new("wss://relay.example.com").with_idle_timeout(huge), + ClientConfig::new("wss://relay.example.com").with_connect_timeout(huge), + ClientConfig::new("wss://relay.example.com").with_write_timeout(huge), + ClientConfig::new("wss://relay.example.com").with_close_timeout(huge), + ClientConfig::new("wss://relay.example.com").with_ping_interval(huge), + ClientConfig::new("wss://relay.example.com").with_pong_timeout(huge), + ClientConfig::new("wss://relay.example.com").with_session_join_timeout(huge), + ClientConfig::new("wss://relay.example.com").with_reconnect_initial_delay(huge), + ClientConfig::new("wss://relay.example.com").with_reconnect_max_delay(huge), + ClientConfig::new("wss://relay.example.com") + .with_token_ttl(huge) + .with_connection_stability(MAX_TIMEOUT), + ] { + assert!( + matches!(config.validate(), Err(ClientError::InvalidConfig(_))), + "{config:?} must be rejected" + ); + } + } + + #[test] + fn rejects_inconsistent_durations() { + let config = ClientConfig::new("wss://relay.example.com"); + assert!(matches!( + config + .clone() + .with_token_ttl(Duration::from_millis(500)) + .with_connection_stability(Duration::from_millis(100)) + .validate(), + Err(ClientError::InvalidConfig( + "token_ttl must be at least one second" + )) + )); + assert!(matches!( + config + .with_reconnect_initial_delay(Duration::from_secs(10)) + .with_reconnect_max_delay(Duration::from_secs(5)) + .validate(), + Err(ClientError::InvalidConfig( + "reconnect_initial_delay must not exceed reconnect_max_delay" + )) + )); + } + + #[test] + fn requires_at_least_one_ack_attempt() { + let config = ClientConfig::new("wss://relay.example.com"); + assert!(matches!( + config.clone().with_ack_max_attempts(0).validate(), + Err(ClientError::InvalidConfig("ack_max_attempts")) + )); + assert!(config.with_ack_max_attempts(1).validate().is_ok()); + } + + #[test] + fn rejects_zero_transport_timeouts() { + for config in [ + ClientConfig::new("wss://relay.example.com").with_token_ttl(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_idle_timeout(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_connect_timeout(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_write_timeout(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_close_timeout(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_ack_base_delay(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_ping_interval(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_pong_timeout(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_retransmit_spacing(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_connection_stability(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_session_join_timeout(Duration::ZERO), + ClientConfig::new("wss://relay.example.com").with_retransmit_bytes_per_second(0), + ] { + assert!(matches!( + config.validate(), + Err(ClientError::InvalidConfig(_)) + )); + } + } + + #[test] + fn rejects_unbounded_retry_delays() { + for delay in [MAX_RETRY_DELAY + Duration::from_secs(1), Duration::MAX] { + assert!(matches!( + ClientConfig::new("wss://relay.example.com") + .with_ack_base_delay(delay) + .validate(), + Err(ClientError::InvalidConfig("ack_base_delay")) + )); + assert!(matches!( + ClientConfig::new("wss://relay.example.com") + .with_retransmit_spacing(delay) + .validate(), + Err(ClientError::InvalidConfig("retransmit_spacing")) + )); + } + + assert!( + ClientConfig::new("wss://relay.example.com") + .with_ack_base_delay(MAX_RETRY_DELAY) + .with_retransmit_spacing(MAX_RETRY_DELAY) + .validate() + .is_ok() + ); + } + + #[test] + fn requires_stability_shorter_than_token_ttl() { + // The default connect timeout is 10 s, and a 30 s token is sure of + // 29 s. + assert!( + ClientConfig::new("wss://relay.example.com") + .with_token_ttl(Duration::from_secs(30)) + .with_connection_stability(Duration::from_millis(18_999)) + .validate() + .is_ok() + ); + for stability in [ + Duration::from_secs(19), + Duration::from_secs(29), + Duration::from_secs(30), + ] { + assert!(matches!( + ClientConfig::new("wss://relay.example.com") + .with_token_ttl(Duration::from_secs(30)) + .with_connection_stability(stability) + .validate(), + Err(ClientError::InvalidConfig( + "connect_timeout plus connection_stability must be shorter than token_ttl less one second" + )) + )); + } + } + + #[test] + fn fractional_token_ttl_only_counts_whole_seconds() { + // A 1.9 s token is issued for one whole second, and is not sure to + // outlive the truncation of its `iat`, so no stability fits. + assert!(matches!( + ClientConfig::new("wss://relay.example.com") + .with_token_ttl(Duration::from_millis(1_900)) + .with_connect_timeout(Duration::from_millis(100)) + .with_connection_stability(Duration::from_millis(100)) + .validate(), + Err(ClientError::InvalidConfig( + "connect_timeout plus connection_stability must be shorter than token_ttl less one second" + )) + )); + // A 2.9 s token is sure of one second. + let config = ClientConfig::new("wss://relay.example.com") + .with_token_ttl(Duration::from_millis(2_900)) + .with_connect_timeout(Duration::from_millis(500)); + assert!( + config + .clone() + .with_connection_stability(Duration::from_millis(499)) + .validate() + .is_ok() + ); + assert!(matches!( + config + .with_connection_stability(Duration::from_millis(500)) + .validate(), + Err(ClientError::InvalidConfig( + "connect_timeout plus connection_stability must be shorter than token_ttl less one second" + )) + )); + } + + #[test] + fn connect_time_counts_against_the_token_lifetime() { + // A 4 s token is sure of 3 s. + let config = ClientConfig::new("wss://relay.example.com") + .with_token_ttl(Duration::from_secs(4)) + .with_connection_stability(Duration::from_secs(1)); + assert!( + config + .clone() + .with_connect_timeout(Duration::from_millis(1_999)) + .validate() + .is_ok() + ); + for connect_timeout in [Duration::from_secs(2), Duration::from_secs(5)] { + assert!(matches!( + config + .clone() + .with_connect_timeout(connect_timeout) + .validate(), + Err(ClientError::InvalidConfig( + "connect_timeout plus connection_stability must be shorter than token_ttl less one second" + )) + )); + } + } +} diff --git a/crates/client/src/crypto.rs b/crates/client/src/crypto.rs new file mode 100644 index 0000000..6d56310 --- /dev/null +++ b/crates/client/src/crypto.rs @@ -0,0 +1,426 @@ +use chacha20poly1305::{ + XChaCha20Poly1305, XNonce, + aead::{Aead, KeyInit, Payload}, +}; +use serde::{Deserialize, Serialize}; +use thiserror::Error; +use wallet_session_core::{ + connection::Role, + crypto::MessageCipher, + did::DidKey, + message::{Ciphertext, Message, MessageId, MessageType, Nonce, Topic}, +}; + +/// Symmetric key length +pub const KEY_LEN: usize = 32; + +/// Random per-sender nonce prefix length +pub const SENDER_PREFIX_LEN: usize = 16; + +/// AEAD nonce length: sender prefix plus counter +pub const NONCE_LEN: usize = 24; + +/// AEAD associated data bound to the plaintext envelope header. +/// +/// Each field is a UTF-8 string prefixed by its length as a four-byte +/// big-endian integer: +/// +/// `AAD = LP(version) || LP(id) || LP(kind) || LP(topic) || LP(from) || LP(ts) || LP(role)` +/// +/// The sender uses its own role; the receiver rebuilds the AAD with its +/// counterpart's role, so an envelope returned to its sender does not +/// authenticate. +/// +/// TODO: verify `from` against the expected peer identity once it is known. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Aad<'a> { + /// Protocol version + pub version: u8, + + /// Envelope id + pub id: &'a MessageId, + + /// Message type + pub kind: MessageType, + + /// Subscription topic + pub topic: &'a Topic, + + /// Sender identity + pub from: &'a DidKey, + + /// Envelope timestamp + pub ts: u64, + + /// Sender role on the topic + pub role: Role, +} + +impl<'a> Aad<'a> { + /// Build associated data with the current envelope version. + pub fn new( + id: &'a MessageId, + kind: MessageType, + topic: &'a Topic, + from: &'a DidKey, + ts: u64, + role: Role, + ) -> Self { + Self { + version: Message::VERSION, + id, + kind, + topic, + from, + ts, + role, + } + } + + /// Serialize the associated data as length-prefixed UTF-8 bytes. + pub fn to_bytes(&self) -> Vec { + let version = self.version.to_string(); + let id = self.id.to_string(); + let topic = self.topic.to_string(); + let from = self.from.to_string(); + let ts = self.ts.to_string(); + let fields = [ + version.as_str(), + id.as_str(), + self.kind.as_str(), + topic.as_str(), + from.as_str(), + ts.as_str(), + self.role.as_str(), + ]; + + let mut bytes = Vec::new(); + for field in fields { + let len = u32::try_from(field.len()).expect("AAD field length fits u32"); + bytes.extend_from_slice(&len.to_be_bytes()); + bytes.extend_from_slice(field.as_bytes()); + } + bytes + } +} + +/// Cipher output for a single message: nonce plus ciphertext. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct SealedPayload { + /// AEAD nonce + pub nonce: Nonce, + + /// Ciphertext with tag + pub data: Ciphertext, +} + +/// Encryption and decryption failures. +#[derive(Debug, Error)] +pub enum CipherError { + /// Encryption failed. + #[error("encryption failed")] + Encrypt, + + /// Decryption failed (bad key, tampered data, or AAD mismatch). + #[error("decryption failed")] + Decrypt, + + /// A nonce had the wrong length. + #[error("invalid nonce length: {0}")] + NonceLength(usize), + + /// The send counter is exhausted. + #[error("nonce counter exhausted")] + CounterExhausted, + + /// A random source failed. + #[error("random source failure: {0}")] + Random(#[from] getrandom::Error), +} + +/// XChaCha20-Poly1305 provider +pub struct XChaCha20Poly1305Cipher { + prefix: [u8; SENDER_PREFIX_LEN], + counter: u64, + inner: XChaCha20Poly1305, +} + +impl XChaCha20Poly1305Cipher { + /// Build a cipher with a random sender prefix. + /// + /// The key is taken by reference so no extra copy of it is left behind; + /// the cipher keeps its own and wipes it on drop. + pub fn new(key: &[u8; KEY_LEN]) -> Result { + let mut prefix = [0u8; SENDER_PREFIX_LEN]; + getrandom::fill(&mut prefix)?; + Self::from_prefix(key, prefix) + } + + fn from_prefix( + key: &[u8; KEY_LEN], + prefix: [u8; SENDER_PREFIX_LEN], + ) -> Result { + Ok(Self { + prefix, + counter: 0, + inner: XChaCha20Poly1305::new(key.into()), + }) + } + + /// Build a cipher with a fixed sender prefix. Test-only. + #[cfg(test)] + fn with_prefix( + key: &[u8; KEY_LEN], + prefix: [u8; SENDER_PREFIX_LEN], + ) -> Result { + Self::from_prefix(key, prefix) + } + + fn nonce(&self) -> [u8; NONCE_LEN] { + let mut nonce = [0u8; NONCE_LEN]; + nonce[..SENDER_PREFIX_LEN].copy_from_slice(&self.prefix); + nonce[SENDER_PREFIX_LEN..].copy_from_slice(&self.counter.to_be_bytes()); + nonce + } +} + +impl MessageCipher for XChaCha20Poly1305Cipher { + type Sealed = SealedPayload; + type Error = CipherError; + fn seal(&mut self, aad: &[u8], plaintext: &[u8]) -> Result { + let next_counter = self + .counter + .checked_add(1) + .ok_or(CipherError::CounterExhausted)?; + let nonce = self.nonce(); + let data = self + .inner + .encrypt( + &XNonce::from(nonce), + Payload { + msg: plaintext, + aad, + }, + ) + .map_err(|_| CipherError::Encrypt)?; + self.counter = next_counter; + + let nonce = Nonce::new(nonce.to_vec()).map_err(|_| CipherError::NonceLength(NONCE_LEN))?; + Ok(SealedPayload { + nonce, + data: Ciphertext::new(data), + }) + } + + fn open(&self, aad: &[u8], sealed: &SealedPayload) -> Result, CipherError> { + let nonce = sealed.nonce.as_bytes(); + let nonce: [u8; NONCE_LEN] = nonce + .try_into() + .map_err(|_| CipherError::NonceLength(nonce.len()))?; + + self.inner + .decrypt( + &XNonce::from(nonce), + Payload { + msg: sealed.data.as_bytes(), + aad, + }, + ) + .map_err(|_| CipherError::Decrypt) + } + + fn for_key(&self, key: &[u8; KEY_LEN]) -> Result { + Self::new(key) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + type TestResult = Result<(), Box>; + + fn topic() -> Topic { + Topic::new([1u8; 32]).expect("topic") + } + + fn did(seed: u8) -> DidKey { + DidKey::from_ed25519_bytes([seed; 32]) + } + + fn message_id() -> MessageId { + MessageId::from_bytes([3u8; MessageId::LEN]) + } + + fn aad(kind: MessageType, topic: &Topic) -> Vec { + Aad::new( + &message_id(), + kind, + topic, + &did(7), + 1_700_000_000, + Role::Proposer, + ) + .to_bytes() + } + + #[test] + fn aad_is_length_prefixed_and_includes_ts_and_role() { + let topic = topic(); + let from = did(7); + let aad = Aad::new( + &message_id(), + MessageType::Request, + &topic, + &from, + 1_700_000_000, + Role::Proposer, + ) + .to_bytes(); + + let fields = [ + Message::VERSION.to_string(), + message_id().to_string(), + "request".to_owned(), + topic.to_string(), + from.to_string(), + "1700000000".to_owned(), + "proposer".to_owned(), + ]; + let mut expected = Vec::new(); + for field in fields { + expected.extend_from_slice(&(field.len() as u32).to_be_bytes()); + expected.extend_from_slice(field.as_bytes()); + } + + assert_eq!(aad, expected); + } + + #[test] + fn aad_binds_timestamp_and_role() { + let topic = topic(); + let from = did(7); + let aad = |ts, role| { + Aad::new(&message_id(), MessageType::Request, &topic, &from, ts, role).to_bytes() + }; + + assert_ne!( + aad(1_700_000_000, Role::Proposer), + aad(1_700_000_001, Role::Proposer) + ); + assert_ne!( + aad(1_700_000_000, Role::Proposer), + aad(1_700_000_000, Role::Responder) + ); + } + + #[test] + fn round_trips() -> TestResult { + let topic = topic(); + let aad = aad(MessageType::Request, &topic); + let mut cipher = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + + let sealed = cipher.seal(&aad, b"hello")?; + assert_eq!(cipher.open(&aad, &sealed)?, b"hello"); + Ok(()) + } + + #[test] + fn rejects_tampered_aad() -> TestResult { + let topic = topic(); + let mut cipher = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + let sealed = cipher.seal(&aad(MessageType::Request, &topic), b"hello")?; + + let other = aad(MessageType::Response, &topic); + assert!(matches!( + cipher.open(&other, &sealed), + Err(CipherError::Decrypt) + )); + Ok(()) + } + + #[test] + fn rejects_tampered_from() -> TestResult { + let topic = topic(); + let mut cipher = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + + let sealed = cipher.seal( + &Aad::new( + &message_id(), + MessageType::Request, + &topic, + &did(1), + 1_700_000_000, + Role::Proposer, + ) + .to_bytes(), + b"hello", + )?; + let tampered = Aad::new( + &message_id(), + MessageType::Request, + &topic, + &did(2), + 1_700_000_000, + Role::Proposer, + ) + .to_bytes(); + + assert!(matches!( + cipher.open(&tampered, &sealed), + Err(CipherError::Decrypt) + )); + Ok(()) + } + + #[test] + fn nonce_advances_per_message() -> TestResult { + let topic = topic(); + let aad = aad(MessageType::Request, &topic); + let mut cipher = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + + let first = cipher.seal(&aad, b"a")?; + let second = cipher.seal(&aad, b"a")?; + assert_ne!(first.nonce, second.nonce); + Ok(()) + } + + #[test] + fn session_cipher_starts_with_fresh_nonce_state() -> TestResult { + let pairing = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + let session = pairing.for_key(&[8u8; 32])?; + + assert_ne!(pairing.prefix, session.prefix); + assert_eq!(session.counter, 0); + Ok(()) + } + + #[test] + fn session_cipher_does_not_open_with_the_pairing_key() -> TestResult { + let topic = topic(); + let aad = aad(MessageType::Request, &topic); + let pairing = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + let mut session = pairing.for_key(&[8u8; 32])?; + + let sealed = session.seal(&aad, b"hello")?; + assert!(matches!( + pairing.open(&aad, &sealed), + Err(CipherError::Decrypt) + )); + Ok(()) + } + + #[test] + fn counter_exhaustion_fails_closed() -> TestResult { + let topic = topic(); + let aad = aad(MessageType::Request, &topic); + let mut cipher = XChaCha20Poly1305Cipher::with_prefix(&[9u8; 32], [3u8; 16])?; + cipher.counter = u64::MAX; + + assert!(matches!( + cipher.seal(&aad, b"hello"), + Err(CipherError::CounterExhausted) + )); + Ok(()) + } +} diff --git a/crates/client/src/error.rs b/crates/client/src/error.rs new file mode 100644 index 0000000..651fb92 --- /dev/null +++ b/crates/client/src/error.rs @@ -0,0 +1,121 @@ +use thiserror::Error; + +/// Client-side failures. +#[derive(Debug, Error)] +pub enum ClientError { + #[error("websocket error: {0}")] + WebSocket(#[from] tokio_tungstenite::tungstenite::Error), + + #[error("json error: {0}")] + Json(#[from] serde_json::Error), + + #[error("encoding error: {0}")] + Codec(#[from] wallet_session_core::error::Error), + + #[error("cipher error: {0}")] + Cipher(#[from] crate::crypto::CipherError), + + #[error("handshake error: {0}")] + Handshake(#[from] crate::handshake::HandshakeError), + + #[error("invalid pairing uri: {0}")] + PairingUri(String), + + #[error("invalid url: {0}")] + Url(#[from] url::ParseError), + + #[error("invalid query parameters: {0}")] + Query(#[from] serde_urlencoded::ser::Error), + + #[error("relay connection closed")] + Closed, + + #[error("relay transport failed: {0}")] + Transport(&'static str), + + #[error("invalid client configuration: {0}")] + InvalidConfig(&'static str), + + /// The outbound queue is full, or the link has too many pending messages + /// and unconsumed delivery outcomes. Drain `poll_event()`/`next_event()` + /// and retry later. + #[error("client is under backpressure")] + Busy, + + #[error("relay connection timed out")] + Timeout, + + #[error("peer disconnected")] + PeerDisconnected, + + #[error("unexpected handshake message")] + UnexpectedHandshake, + + /// The proposal passed to `approve()` or `reject()` is no longer the + /// pending one: the counterpart sent a newer proposal, which `recv()` + /// delivered. Show that one to the user instead. + #[error("the proposal was superseded by a newer one")] + ProposalSuperseded, + + #[error("protocol violation: {0}")] + ProtocolViolation(&'static str), + + #[error("random source failure: {0}")] + Random(#[from] getrandom::Error), + + #[error("session is not active")] + SessionNotActive, + + #[error("relay session is not ready")] + NotReady, + + /// The proposer did not join the session topic within the join timeout + /// after the responder's `approve`. The client is closed. + #[error("session was not established")] + SessionNotEstablished, +} + +pub type Result = std::result::Result; + +/// A JSON parse error, described without the input it may quote. +/// +/// serde's `Display` echoes unknown variants and mistyped strings verbatim, +/// which lets whoever controls the input (the relay, or the peer once a +/// frame is decrypted) write into our logs. Log this instead. +pub(crate) struct JsonErrorSummary<'a>(pub(crate) &'a serde_json::Error); + +impl std::fmt::Display for JsonErrorSummary<'_> { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!( + f, + "{:?} error at line {} column {}", + self.0.classify(), + self.0.line(), + self.0.column() + ) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn json_error_summary_does_not_echo_input() { + let secret = "do-not-log-this-value"; + let input = format!(r#"{{"kind":"{secret}"}}"#); + #[derive(Debug, serde::Deserialize)] + #[allow(dead_code)] + enum Kind { + Request, + } + #[derive(Debug, serde::Deserialize)] + #[allow(dead_code)] + struct Frame { + kind: Kind, + } + let error = serde_json::from_str::(&input).expect_err("unknown variant"); + assert!(error.to_string().contains(secret), "serde does echo it"); + assert!(!JsonErrorSummary(&error).to_string().contains(secret)); + } +} diff --git a/crates/client/src/handshake.rs b/crates/client/src/handshake.rs new file mode 100644 index 0000000..ed7b822 --- /dev/null +++ b/crates/client/src/handshake.rs @@ -0,0 +1,255 @@ +use std::fmt; + +use hkdf::Hkdf; +use sha2::Sha256; +use thiserror::Error; +use wallet_session_core::{codec, message::Topic}; +use x25519_dalek::{EphemeralSecret, PublicKey}; +use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing}; + +/// HKDF info label for the session symmetric key. +const SESSION_KEY_INFO: &[u8] = b"wallet-session/v1/session-key"; + +/// HKDF info label for the session topic. +const SESSION_TOPIC_INFO: &[u8] = b"wallet-session/v1/session-topic"; + +/// Symmetric session key derived by both peers. +#[derive(Clone, PartialEq, Eq, Zeroize, ZeroizeOnDrop)] +pub struct SessionKey([u8; 32]); + +impl SessionKey { + /// Borrow the raw key bytes. + pub fn as_bytes(&self) -> &[u8; 32] { + &self.0 + } +} + +impl fmt::Debug for SessionKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("SessionKey(..)") + } +} + +/// Session topic derived by both peers. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct SessionTopic(Topic); + +impl SessionTopic { + /// Borrow the topic. + pub fn as_topic(&self) -> &Topic { + &self.0 + } +} + +/// A one-time X25519 keypair for the session handshake. +pub struct EphemeralKeyPair { + secret: EphemeralSecret, +} + +impl EphemeralKeyPair { + /// Generate a fresh ephemeral keypair. + pub fn generate() -> Self { + Self { + secret: EphemeralSecret::random(), + } + } + + /// Raw public key bytes. + pub fn public_key(&self) -> [u8; 32] { + PublicKey::from(&self.secret).to_bytes() + } + + /// Base64url-encoded public key for the handshake payload. + pub fn public_key_encoded(&self) -> String { + codec::encode(&self.public_key()) + } + + /// Derive the session key and topic from the peer's public key. + /// + /// Consumes the keypair: ephemeral secrets are used once. + pub fn derive( + self, + peer_public: &[u8; 32], + ) -> Result<(SessionKey, SessionTopic), HandshakeError> { + let shared = self.secret.diffie_hellman(&PublicKey::from(*peer_public)); + let shared = Zeroizing::new(shared.to_bytes()); + derive_from_shared(&shared) + } +} + +/// Reject a peer public key that would produce an all-zero shared secret. +pub(crate) fn validate_peer_public(peer_public: &[u8; 32]) -> Result<(), HandshakeError> { + let probe = EphemeralSecret::random(); + let shared = probe.diffie_hellman(&PublicKey::from(*peer_public)); + if shared.was_contributory() { + Ok(()) + } else { + Err(HandshakeError::WeakKey) + } +} + +/// Derive the session key and topic from an X25519 shared secret. +fn derive_from_shared(shared: &[u8; 32]) -> Result<(SessionKey, SessionTopic), HandshakeError> { + if shared.iter().all(|byte| *byte == 0) { + return Err(HandshakeError::WeakKey); + } + + let hkdf = Hkdf::::new(None, shared); + + let mut key = Zeroizing::new([0u8; 32]); + hkdf.expand(SESSION_KEY_INFO, key.as_mut()) + .map_err(|_| HandshakeError::Derive)?; + + let mut topic = Zeroizing::new([0u8; 32]); + hkdf.expand(SESSION_TOPIC_INFO, topic.as_mut()) + .map_err(|_| HandshakeError::Derive)?; + let topic = Topic::new(topic.to_vec())?; + + Ok((SessionKey(*key), SessionTopic(topic))) +} + +/// Decode a base64url public key from a handshake payload. +pub fn decode_public_key(encoded: &str) -> Result<[u8; 32], HandshakeError> { + let bytes = codec::decode(encoded)?; + bytes.try_into().map_err(|_| HandshakeError::PeerKey) +} + +/// Handshake and key-agreement failures. +#[derive(Debug, Error)] +pub enum HandshakeError { + /// The peer's public key was not a valid 32-byte base64url value. + #[error("invalid peer public key")] + PeerKey, + + /// The derived shared secret was all zero (low-order public key). + #[error("weak peer public key")] + WeakKey, + + /// HKDF expansion failed. + #[error("key derivation failed")] + Derive, + + /// The derived session topic was invalid. + #[error("invalid session topic: {0}")] + Topic(#[from] wallet_session_core::error::Error), +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn peers_derive_the_same_session() { + let alice = EphemeralKeyPair::generate(); + let bob = EphemeralKeyPair::generate(); + let alice_public = alice.public_key(); + let bob_public = bob.public_key(); + + let (alice_key, alice_topic) = alice.derive(&bob_public).expect("alice derive"); + let (bob_key, bob_topic) = bob.derive(&alice_public).expect("bob derive"); + + assert_eq!(alice_key, bob_key); + assert_eq!(alice_topic, bob_topic); + } + + #[test] + fn session_key_debug_redacts_material() { + let alice = EphemeralKeyPair::generate(); + let bob = EphemeralKeyPair::generate(); + let (key, _topic) = alice.derive(&bob.public_key()).expect("derive"); + let rendered = format!("{key:?}"); + + assert_eq!(rendered, "SessionKey(..)"); + assert!(!rendered.contains(&codec::encode(key.as_bytes()))); + } + + #[test] + fn distinct_pairs_derive_distinct_keys() { + let alice = EphemeralKeyPair::generate(); + let bob = EphemeralKeyPair::generate(); + let mallory = EphemeralKeyPair::generate(); + + let (_, alice_topic) = alice.derive(&bob.public_key()).expect("derive"); + let (_, other_topic) = mallory.derive(&bob.public_key()).expect("derive"); + assert_ne!(alice_topic, other_topic); + } + + #[test] + fn decodes_public_key() { + let pair = EphemeralKeyPair::generate(); + let decoded = decode_public_key(&pair.public_key_encoded()).expect("decode"); + assert_eq!(decoded, pair.public_key()); + assert!(decode_public_key("nope").is_err()); + } + + #[test] + fn session_derivation_known_answer() { + let shared: [u8; 32] = std::array::from_fn(|index| index as u8); + let (key, topic) = derive_from_shared(&shared).expect("derive"); + + let expected_key = + wallet_session_core::codec::decode("9ftlKHcaDzlqxuX9UqBAt9hnPpJ9JCZ7O9HAWPAEvcg") + .expect("key vector"); + assert_eq!(key.as_bytes().as_slice(), expected_key.as_slice()); + assert_eq!( + topic.as_topic().to_string(), + "V-btxMBvFE8yC3YzeMsNae9_4Zr0Cyw5A8VvKl2C9sE" + ); + } + + #[test] + fn rejects_all_zero_shared_secret() { + assert!(matches!( + derive_from_shared(&[0u8; 32]), + Err(HandshakeError::WeakKey) + )); + } + + /// libsodium's blocklist: the canonical encodings of the small-order + /// points (0, 1, the two points of order 8, and p - 1), plus the + /// non-canonical encodings p and p + 1 of 0 and 1. X25519 maps all of + /// them to an all-zero shared secret, whatever our scalar. + const LOW_ORDER: [&str; 7] = [ + "0000000000000000000000000000000000000000000000000000000000000000", + "0100000000000000000000000000000000000000000000000000000000000000", + "e0eb7a7c3b41b8ae1656e3faf19fc46ada098deb9c32b1fd866205165f49b800", + "5f9c95bca3508c24b1d0b1559c83ef5b04445cc4581c8e86d8224eddd09f1157", + "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f", + "edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f", + "eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f", + ]; + + fn low_order_points() -> impl Iterator { + LOW_ORDER.iter().map(|hex| { + let mut point = [0u8; 32]; + for (byte, pair) in point.iter_mut().zip(hex.as_bytes().chunks(2)) { + let pair = std::str::from_utf8(pair).expect("ascii"); + *byte = u8::from_str_radix(pair, 16).expect("hex"); + } + point + }) + } + + #[test] + fn derive_rejects_low_order_peer_keys() { + for point in low_order_points() { + let keypair = EphemeralKeyPair::generate(); + assert!( + matches!(keypair.derive(&point), Err(HandshakeError::WeakKey)), + "{point:02x?} must be rejected" + ); + } + } + + #[test] + fn validate_peer_public_rejects_low_order_keys() { + for point in low_order_points() { + assert!( + matches!(validate_peer_public(&point), Err(HandshakeError::WeakKey)), + "{point:02x?} must be rejected" + ); + } + let peer = EphemeralKeyPair::generate(); + assert!(validate_peer_public(&peer.public_key()).is_ok()); + } +} diff --git a/crates/client/src/identity.rs b/crates/client/src/identity.rs new file mode 100644 index 0000000..869a5c8 --- /dev/null +++ b/crates/client/src/identity.rs @@ -0,0 +1,107 @@ +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use ed25519_dalek::{Signer, SigningKey}; +use wallet_session_core::{auth::RelayAuthToken, codec, did::DidKey}; +use zeroize::{Zeroize, ZeroizeOnDrop}; + +use crate::{error::Result, random}; + +/// Long-term identity seed, persisted across reconnects and restarts. +#[derive(Clone, Zeroize, ZeroizeOnDrop)] +pub struct Seed([u8; 32]); + +impl Seed { + pub fn from_bytes(bytes: [u8; 32]) -> Self { + Self(bytes) + } + + /// Generate a fresh random seed. + pub fn random() -> Result { + Ok(Self(random::bytes()?)) + } + + /// Borrow the raw seed bytes for persistence. + pub fn as_bytes(&self) -> &[u8; 32] { + &self.0 + } +} + +/// Ed25519 identity used to sign connection tokens. +#[derive(Clone)] +pub struct IdentityKey(SigningKey); + +// `SigningKey` zeroizes its secret key material when dropped. +impl ZeroizeOnDrop for IdentityKey {} + +impl IdentityKey { + /// Derive the identity key from a persisted seed. + pub fn from_seed(seed: &Seed) -> Self { + Self(SigningKey::from_bytes(seed.as_bytes())) + } + + /// Generate a fresh identity key from a random seed. + pub fn random() -> Result { + Ok(Self::from_seed(&Seed::random()?)) + } + + /// `did:key` identifier derived from the identity public key. + pub fn did(&self) -> DidKey { + DidKey::from_ed25519_bytes(self.0.verifying_key().to_bytes()) + } + + /// Sign a connection token for the given relay session and audience. + pub fn connection_token( + &self, + session_id: &str, + audience: &str, + ttl: Duration, + ) -> Result { + let now = unix_now(); + let token = RelayAuthToken { + iss: self.did(), + sub: session_id.to_owned(), + aud: audience.to_owned(), + iat: now, + exp: now.saturating_add(ttl.as_secs()), + }; + + let header = codec::encode(br#"{"alg":"EdDSA","typ":"JWT"}"#); + let payload = codec::encode(&serde_json::to_vec(&token)?); + let signing_input = format!("{header}.{payload}"); + let signature = self.0.sign(signing_input.as_bytes()); + let signature = codec::encode(&signature.to_bytes()); + + Ok(format!("{signing_input}.{signature}")) + } +} + +/// Current Unix time in seconds, saturating at 0 before the epoch. +pub fn unix_now() -> u64 { + match SystemTime::now().duration_since(UNIX_EPOCH) { + Ok(duration) => duration.as_secs(), + Err(_) => 0, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn did_is_stable_for_a_seed() { + let seed = Seed::from_bytes([7u8; 32]); + let first = IdentityKey::from_seed(&seed).did(); + let second = IdentityKey::from_seed(&seed).did(); + assert_eq!(first, second); + assert!(first.to_string().starts_with("did:key:z")); + } + + #[test] + fn connection_token_has_three_segments() { + let identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + let token = identity + .connection_token("session", "wss://relay", Duration::from_secs(60)) + .expect("token"); + assert_eq!(token.split('.').count(), 3); + } +} diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs new file mode 100644 index 0000000..b61221e --- /dev/null +++ b/crates/client/src/lib.rs @@ -0,0 +1,48 @@ +//! Client for the wallet-session relay protocol. +//! +//! A [`Client`] owns one pairing topic and, after the handshake, one derived +//! session topic. Its counterpart, replay memory, and outstanding reliability +//! state are in memory for the lifetime of that client instance. Creating a +//! new client with the same pairing key starts with empty replay state and no +//! counterpart, so long-lived applications should reuse the existing client. +//! +//! Inbound work, including acknowledgements and relay lifecycle events, is +//! driven by [`Client::recv`], [`Client::next_event`], and +//! [`Client::wait_session_ready`]. Applications should keep one of those +//! futures pending while the session is active. +//! +//! Delivery outcomes are also part of the inbound work. Each tracked send +//! keeps a reservation until its `Delivered` or `Failed` event is consumed by +//! [`Client::poll_event`] or [`Client::next_event`]. Applications that only +//! call `request`/`recv` must still drain events; otherwise sends eventually +//! return [`ClientError::Busy`]. + +mod client; +mod config; +mod error; +mod identity; +mod messages; +mod pairing; +mod random; +mod relay; +mod reliability; +mod replay; +mod session; +mod tls; + +pub mod crypto; +pub mod handshake; + +pub use client::Client; +pub use config::ClientConfig; +pub use crypto::XChaCha20Poly1305Cipher; +pub use error::{ClientError, Result}; +pub use identity::{IdentityKey, Seed}; +pub use messages::{ClientMessage, RequestId}; +pub use pairing::{PairingKey, PairingUri}; +pub use reliability::ClientEvent; +pub use session::{Role, Session, SessionState}; +pub use wallet_session_core::payload::{ + AckPayload, ApprovePayload, DisconnectPayload, Opaque, ProposalPayload, RejectPayload, + RequestPayload, ResponsePayload, SessionDeletePayload, +}; diff --git a/crates/client/src/messages.rs b/crates/client/src/messages.rs new file mode 100644 index 0000000..cc18e10 --- /dev/null +++ b/crates/client/src/messages.rs @@ -0,0 +1,158 @@ +use serde::{Deserialize, Serialize}; +use wallet_session_core::{ + message::MessageType, + payload::{ + AckPayload, ApprovePayload, DisconnectPayload, ProposalPayload, RejectPayload, + RequestPayload, ResponsePayload, SessionDeletePayload, + }, +}; + +use crate::error::Result; + +/// Caller-assigned id correlating a request with its response. +pub type RequestId = String; + +/// Plaintext application message exchanged over the relay. +/// +/// The variant bodies are the payload types from `wallet_session_core`, so the +/// wire representation is the one defined by the protocol. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(tag = "type", rename_all = "snake_case")] +pub enum ClientMessage { + /// Propose a session. + Proposal(ProposalPayload), + + /// Approve a session. + Approve(ApprovePayload), + + /// Reject a proposal. + Reject(RejectPayload), + + /// Application request. + Request(RequestPayload), + + /// Application response to a request. + Response(ResponsePayload), + + /// Acknowledge receipt of a message. + Ack(AckPayload), + + /// Graceful teardown. + Disconnect(DisconnectPayload), + + /// Notify the peer that the session was deleted. + SessionDelete(SessionDeletePayload), +} + +impl ClientMessage { + /// Message type used as the plaintext envelope tag. + pub fn message_type(&self) -> MessageType { + match self { + ClientMessage::Proposal(_) => MessageType::Proposal, + ClientMessage::Approve(_) => MessageType::Approve, + ClientMessage::Reject(_) => MessageType::Reject, + ClientMessage::Request(_) => MessageType::Request, + ClientMessage::Response(_) => MessageType::Response, + ClientMessage::Ack(_) => MessageType::Ack, + ClientMessage::Disconnect(_) => MessageType::Disconnect, + ClientMessage::SessionDelete(_) => MessageType::SessionDelete, + } + } + + pub fn to_bytes(&self) -> Result> { + Ok(serde_json::to_vec(self)?) + } + + pub fn from_bytes(bytes: &[u8]) -> Result { + Ok(serde_json::from_slice(bytes)?) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + use wallet_session_core::payload::Opaque; + + #[test] + fn request_round_trips() { + let message = ClientMessage::Request(RequestPayload { + request_id: "req-1".to_owned(), + request: Opaque(serde_json::to_vec(&json!({ "method": "get" })).expect("json")), + }); + let bytes = message.to_bytes().expect("bytes"); + assert_eq!(ClientMessage::from_bytes(&bytes).expect("parsed"), message); + assert_eq!(message.message_type(), MessageType::Request); + } + + #[test] + fn response_error_variant_round_trips() { + let message = ClientMessage::Response(ResponsePayload { + request_id: "req-1".to_owned(), + response: None, + error: Some(Opaque( + serde_json::to_vec(&json!({ "code": 4001 })).expect("json"), + )), + }); + let bytes = message.to_bytes().expect("bytes"); + assert_eq!(ClientMessage::from_bytes(&bytes).expect("parsed"), message); + } + + #[test] + fn ack_uses_the_documented_field_name() { + let ack_id = wallet_session_core::message::MessageId::from_bytes([1u8; 16]); + let message = ClientMessage::Ack(AckPayload { + ack_id: ack_id.clone(), + }); + + assert_eq!( + serde_json::to_value(&message).expect("json"), + json!({ "type": "ack", "ackId": ack_id.to_string() }) + ); + assert_eq!( + ClientMessage::from_bytes(format!(r#"{{"type":"ack","ackId":"{ack_id}"}}"#).as_bytes()) + .expect("parsed"), + message + ); + } + + #[test] + fn request_uses_the_documented_field_names() { + let message = ClientMessage::Request(RequestPayload { + request_id: "req-1".to_owned(), + request: Opaque(vec![1, 2, 3]), + }); + let value = serde_json::to_value(&message).expect("json"); + + assert_eq!( + value, + json!({ "type": "request", "requestId": "req-1", "request": "AQID" }) + ); + assert!(value.get("request_id").is_none()); + } + + #[test] + fn response_uses_the_documented_field_names() { + let message = ClientMessage::Response(ResponsePayload { + request_id: "req-1".to_owned(), + response: Some(Opaque(vec![1, 2, 3])), + error: None, + }); + let value = serde_json::to_value(&message).expect("json"); + + assert_eq!(value["type"], "response"); + assert_eq!(value["requestId"], "req-1"); + assert_eq!(value["response"], "AQID"); + assert!(value.get("request_id").is_none()); + assert!(value.get("error").is_none()); + + let message = ClientMessage::Response(ResponsePayload { + request_id: "req-1".to_owned(), + response: None, + error: Some(Opaque(vec![4, 5])), + }); + let value = serde_json::to_value(&message).expect("json"); + assert_eq!(value["error"], "BAU"); + assert!(value.get("response").is_none()); + } +} diff --git a/crates/client/src/pairing.rs b/crates/client/src/pairing.rs new file mode 100644 index 0000000..5a77461 --- /dev/null +++ b/crates/client/src/pairing.rs @@ -0,0 +1,171 @@ +use std::fmt; + +use sha2::{Digest, Sha256}; +use url::{Url, form_urlencoded}; +use wallet_session_core::{codec, message::Topic}; +use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing}; + +use crate::{error::ClientError, error::Result, random}; + +const CONNECTION_SCHEME: &str = "bsconnect"; + +/// 32-byte symmetric pairing key shared out of band +#[derive(Clone, PartialEq, Eq, Zeroize, ZeroizeOnDrop)] +pub struct PairingKey([u8; 32]); + +impl PairingKey { + /// Generate a fresh random pairing key. + pub fn random() -> Result { + Ok(Self(random::bytes()?)) + } + + /// Wrap raw pairing key bytes. + pub fn from_bytes(bytes: [u8; 32]) -> Self { + Self(bytes) + } + + /// Borrow the raw key bytes. + pub fn as_bytes(&self) -> &[u8; 32] { + &self.0 + } + + /// Pairing topic derived from the key + pub fn topic(&self) -> Result { + let digest = Sha256::digest(self.0); + Ok(Topic::new(digest.to_vec())?) + } + + /// Base64url representation used in the pairing URI + pub fn to_base64(&self) -> String { + codec::encode(&self.0) + } + + /// Parse a base64url pairing key. + pub fn from_base64(encoded: &str) -> Result { + let bytes = Zeroizing::new(codec::decode(encoded)?); + let bytes: [u8; 32] = bytes + .as_slice() + .try_into() + .map_err(|_| ClientError::PairingUri("bad pairing key length".to_owned()))?; + Ok(Self(bytes)) + } +} + +impl fmt::Debug for PairingKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("PairingKey(..)") + } +} + +/// Pairing URI +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PairingUri { + /// Symmetric pairing key. + pub key: PairingKey, + + /// Relay endpoint to connect to. + pub relay: String, +} + +impl PairingUri { + /// Build a pairing URI for a key and relay endpoint. + pub fn new(key: PairingKey, relay: impl Into) -> Self { + Self { + key, + relay: relay.into(), + } + } + + pub fn parse(uri: &str) -> Result { + let url = Url::parse(uri).map_err(|_| ClientError::PairingUri("invalid URI".to_owned()))?; + if url.scheme() != CONNECTION_SCHEME || url.host_str() != Some("pairing") { + return Err(ClientError::PairingUri("not a pairing URI".to_owned())); + } + + let mut key = None; + let mut relay = None; + for (name, value) in url.query_pairs() { + match name.as_ref() { + "key" => key = Some(PairingKey::from_base64(&value)?), + "relay" => relay = Some(value.into_owned()), + _ => {} + } + } + + Ok(Self { + key: key.ok_or_else(|| ClientError::PairingUri("missing pairing key".to_owned()))?, + relay: relay + .ok_or_else(|| ClientError::PairingUri("missing relay endpoint".to_owned()))?, + }) + } +} + +impl fmt::Display for PairingUri { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let query = form_urlencoded::Serializer::new(String::new()) + .append_pair("key", &self.key.to_base64()) + .append_pair("relay", &self.relay) + .finish(); + write!(f, "{CONNECTION_SCHEME}://pairing?{query}") + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn topic_is_sha256_of_key() { + let key = PairingKey::from_bytes([3u8; 32]); + let expected = Topic::new(Sha256::digest([3u8; 32]).to_vec()).expect("topic"); + assert_eq!(key.topic().expect("topic"), expected); + } + + #[test] + fn pairing_uri_round_trips() { + let uri = PairingUri::new( + PairingKey::from_bytes([9u8; 32]), + "wss://relay.example.com/", + ); + let rendered = uri.to_string(); + assert_eq!(PairingUri::parse(&rendered).expect("parsed"), uri); + } + + #[test] + fn rejects_unknown_scheme() { + assert!(PairingUri::parse("https://example.com").is_err()); + } + + #[test] + fn errors_do_not_echo_pairing_secrets_or_uris() { + let key = codec::encode(&[9u8; 32]); + let uri = format!("https://example.com/?key={key}&relay=wss://relay.example.com"); + let error = PairingUri::parse(&uri).expect_err("wrong scheme"); + let text = error.to_string(); + assert!(!text.contains(&key), "{text}"); + assert!(!text.contains("relay.example.com"), "{text}"); + + let short = codec::encode(&[1u8; 31]); + let error = PairingKey::from_base64(&short).expect_err("short key"); + let text = error.to_string(); + assert!(!text.contains(&short), "{text}"); + } + + #[test] + fn missing_fields_have_fixed_errors() { + let error = PairingUri::parse("bsconnect://pairing?relay=wss://relay.example.com") + .expect_err("missing key"); + assert_eq!( + error.to_string(), + "invalid pairing uri: missing pairing key" + ); + + let key = codec::encode(&[0u8; 32]); + let error = PairingUri::parse(&format!("bsconnect://pairing?key={key}")) + .expect_err("missing relay"); + assert_eq!( + error.to_string(), + "invalid pairing uri: missing relay endpoint" + ); + } +} diff --git a/crates/client/src/random.rs b/crates/client/src/random.rs new file mode 100644 index 0000000..b244f28 --- /dev/null +++ b/crates/client/src/random.rs @@ -0,0 +1,13 @@ +use wallet_session_core::message::MessageId; + +use crate::error::Result; + +pub(crate) fn bytes() -> Result<[u8; N]> { + let mut bytes = [0u8; N]; + getrandom::fill(&mut bytes)?; + Ok(bytes) +} + +pub(crate) fn id() -> Result { + Ok(MessageId::from_bytes(bytes()?)) +} diff --git a/crates/client/src/relay.rs b/crates/client/src/relay.rs new file mode 100644 index 0000000..4dcd904 --- /dev/null +++ b/crates/client/src/relay.rs @@ -0,0 +1,1013 @@ +use std::{ + collections::VecDeque, + sync::{ + Arc, + atomic::{AtomicBool, Ordering}, + }, + time::Duration, +}; + +use futures_util::{Sink, SinkExt, StreamExt}; +use tokio::{ + net::TcpStream, + sync::{mpsc, watch}, + task::JoinHandle, + time::{Instant, MissedTickBehavior, interval_at, sleep_until}, +}; +use tokio_tungstenite::{ + MaybeTlsStream, WebSocketStream, connect_async_with_config, + tungstenite::{ + Bytes, Error as TungsteniteError, Message, + protocol::{CloseFrame, WebSocketConfig, frame::coding::CloseCode}, + }, +}; +use wallet_session_core::{ + connection::{ConnectionQuery, Role}, + frame::{RelayFrame, RelayFrameBody}, + message::{MessageType, Topic}, +}; + +use crate::{ + config::ClientConfig, + error::{JsonErrorSummary, Result}, + identity::IdentityKey, + random, +}; + +/// Client-side relay WebSocket stream. +pub(crate) type RelayStream = WebSocketStream>; + +/// Frames buffered between the transport task and the client. +pub(crate) const INBOX_CAPACITY: usize = 64; + +/// Frames buffered between the client and the transport task. +pub(crate) const OUTBOUND_CAPACITY: usize = 64; + +/// Maximum relay frame accepted from the relay, matching the relay default. +const MAX_RELAY_FRAME_BYTES: usize = 256 * 1024; + +/// Maximum buffered WebSocket write bytes. +const MAX_WRITE_BUFFER_BYTES: usize = 2 * MAX_RELAY_FRAME_BYTES; + +/// Everything the connection task can put on the wire. +pub(crate) enum Outbound { + /// A relay frame to serialize and send. + Frame(RelayFrame), +} + +/// Everything a connection task reports to the client. +pub(crate) enum Inbox { + /// A relay frame received from the relay. + Frame(RelayFrame), + + /// The socket for `topic` is established (initial or after reconnect). + Connected(Topic), + + /// The connection for `topic` was lost; a reconnect is starting. + Disconnected(Topic), + + /// Reconnect attempts for `topic` were exhausted or permanently rejected. + Closed { topic: Topic, reason: &'static str }, + + /// The client no longer needs the pairing connection for `topic`. + Retire(Topic), + + /// The session-join window for `topic` after a failed `approve` ended. + SessionTimeout(Topic), +} + +/// Why one connection attempt ended. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum ConnectionEnd { + /// The client is shutting down. + Shutdown, + + /// Retry after the configured backoff. + Reconnect { reason: &'static str }, + + /// Retry immediately, for example after a token-expiry close. + ReconnectNow { reason: &'static str }, + + /// Do not retry. + Fatal { reason: &'static str }, +} + +struct ConnectionResult { + end: ConnectionEnd, + /// How long the relay kept responding: the whole connection, or, if it + /// ended because the relay stopped responding (a pong, idle or write + /// deadline passed), until it last answered one of our pings. + healthy_for: Duration, + /// Lifecycle and control items the client had no room for yet. + undelivered: Vec, +} + +/// Hand a message frame to the client without blocking the connection loop. +/// +/// A full inbox is backpressure: the frame is dropped and the peer +/// retransmits the envelope, since we never acked it. While control items +/// are queued, message frames are dropped the same way, so the client never +/// sees an envelope ahead of the lifecycle item that preceded it. +/// +/// A `disconnect` or `session_delete` is the exception. Its sender closes +/// straight after sending it and never retransmits it, so one that finds no +/// room waits at the back of the control queue instead. Only the first one +/// waits and later ones are dropped, which keeps the queue bounded: one that +/// replaced it at the back would split repeated control frames that +/// `queue_control` otherwise merges. The kind is read before the envelope is +/// authenticated; the client drops a forged one like any other. +/// +/// Returns `false` once the client has dropped the inbox. +fn deliver_message( + control: &mut VecDeque, + inbox: &mpsc::Sender, + frame: RelayFrame, +) -> bool { + let frame = if control.is_empty() { + match inbox.try_send(Inbox::Frame(frame)) { + Ok(()) => return true, + Err(mpsc::error::TrySendError::Closed(_)) => return false, + Err(mpsc::error::TrySendError::Full(Inbox::Frame(frame))) => frame, + Err(mpsc::error::TrySendError::Full(_)) => unreachable!("sent a frame"), + } + } else { + frame + }; + let waiting = control.iter().any(|item| { + matches!(item, Inbox::Frame(queued) if matches!(queued.body, RelayFrameBody::Message { .. })) + }); + if is_one_shot(&frame) && !waiting { + control.push_back(Inbox::Frame(frame)); + } else { + log::debug!("dropping inbound frame: client inbox full or control items pending"); + } + true +} + +/// Whether a message frame carries a `disconnect` or `session_delete`. +fn is_one_shot(frame: &RelayFrame) -> bool { + #[derive(serde::Deserialize)] + struct Kind { + kind: MessageType, + } + + let RelayFrameBody::Message { payload } = &frame.body else { + return false; + }; + serde_json::from_str::(payload).is_ok_and(|envelope| { + matches!( + envelope.kind, + MessageType::Disconnect | MessageType::SessionDelete + ) + }) +} + +/// Send a lifecycle item, waiting for the client to make room. +/// +/// Returns `false` only when the transport shuts down or the client drops the +/// inbox. A full inbox is not terminal: the application may drain it later, +/// so the task must stay alive to deliver the lifecycle item. +async fn send_inbox_wait( + inbox: &mpsc::Sender, + item: Inbox, + shutdown: &mut watch::Receiver, +) -> bool { + tokio::select! { + result = inbox.send(item) => result.is_ok(), + _ = shutdown.changed() => false, + } +} + +/// A reconnecting relay connection for one topic and role. +/// +/// A background task owns the WebSocket lifecycle and exposes a stable +/// outbound channel, so the client and reliability layer never observe a +/// socket swap. Inbound events go to the shared channel owned by the client. +pub(crate) struct Transport { + outbound: mpsc::Sender, + shutdown: watch::Sender, + _task: JoinHandle<()>, +} + +impl Drop for Transport { + fn drop(&mut self) { + let _ = self.shutdown.send(true); + } +} + +impl Transport { + /// Start (asynchronously) a connection to the relay for `topic` as `role`. + /// + /// `ready` follows the relay's current view of the counterpart. `joined` + /// latches the first `session_ready` and is never cleared. + pub(crate) fn connect( + config: ClientConfig, + identity: IdentityKey, + role: Role, + topic: Topic, + ready: Arc, + joined: Arc, + inbox: mpsc::Sender, + ) -> Self { + let (outbound, outbound_rx) = mpsc::channel(OUTBOUND_CAPACITY); + let (shutdown, shutdown_rx) = watch::channel(false); + let _task = tokio::spawn(connection_task( + config, + identity, + role, + topic.clone(), + outbound_rx, + ready, + joined, + inbox, + shutdown_rx, + )); + + Self { + outbound, + shutdown, + _task, + } + } + + /// Cloneable handle to the outbound writer. + pub(crate) fn outbound(&self) -> mpsc::Sender { + self.outbound.clone() + } +} + +#[allow(clippy::too_many_arguments)] +async fn connection_task( + config: ClientConfig, + identity: IdentityKey, + role: Role, + topic: Topic, + mut outbound: mpsc::Receiver, + ready: Arc, + joined: Arc, + inbox: mpsc::Sender, + mut shutdown: watch::Receiver, +) { + let mut retries = 0usize; + let mut delay = config.reconnect_initial_delay; + + loop { + ready.store(false, Ordering::Relaxed); + let connected = tokio::select! { + biased; + result = connect_with_timeout(&config, &identity, role, &topic) => result, + _ = shutdown.changed() => return, + }; + + let end = match connected { + Ok(stream) => { + let result = run_connection( + stream, + &topic, + &mut outbound, + &ready, + &joined, + &inbox, + &mut shutdown, + &config, + ) + .await; + ready.store(false, Ordering::Relaxed); + if !matches!(result.end, ConnectionEnd::Shutdown) { + // Reliability re-flushes unacked tracked frames on the next + // ready edge. Do not let copies queued on the old socket + // bypass that gating and pacing. Do this before waiting + // for inbox room below: the retry task may be waiting for + // outbound room, and it must not be held up until the + // application drains its inbox. + while outbound.try_recv().is_ok() {} + + // The socket is gone, so there is nothing left to service + // while we wait for room. + for item in result.undelivered { + if !send_inbox_wait(&inbox, item, &mut shutdown).await { + return; + } + } + } + // Only a connection on which the relay kept responding for a + // while shows the relay is healthy. `session_ready` alone + // does not: a relay that says ready and then closes, or stops + // responding, would otherwise keep us reconnecting forever, + // and on a token-expiry close without even a backoff. A + // connection that was healthy that long and only then + // stalled still counts. + if result.healthy_for >= config.connection_stability { + retries = 0; + delay = config.reconnect_initial_delay; + } + result.end + } + Err(error) => { + let end = classify_connect_error(&error); + if let ConnectionEnd::Reconnect { reason } | ConnectionEnd::Fatal { reason } = end { + log::debug!("relay connect failed: {reason}"); + } + end + } + }; + + match end { + ConnectionEnd::Shutdown => return, + ConnectionEnd::Fatal { reason } => { + let _ = + send_inbox_wait(&inbox, Inbox::Closed { topic, reason }, &mut shutdown).await; + return; + } + ConnectionEnd::ReconnectNow { reason } => { + if retries >= config.reconnect_max_attempts { + let _ = send_inbox_wait(&inbox, Inbox::Closed { topic, reason }, &mut shutdown) + .await; + return; + } + retries += 1; + if !send_inbox_wait(&inbox, Inbox::Disconnected(topic.clone()), &mut shutdown).await + { + return; + } + } + ConnectionEnd::Reconnect { reason } => { + if !send_inbox_wait(&inbox, Inbox::Disconnected(topic.clone()), &mut shutdown).await + { + return; + } + if retries >= config.reconnect_max_attempts { + let _ = send_inbox_wait(&inbox, Inbox::Closed { topic, reason }, &mut shutdown) + .await; + return; + } + tokio::select! { + _ = tokio::time::sleep(delay) => {} + _ = shutdown.changed() => return, + } + retries += 1; + delay = delay.saturating_mul(2).min(config.reconnect_max_delay); + } + } + } +} + +async fn connect_with_timeout( + config: &ClientConfig, + identity: &IdentityKey, + role: Role, + topic: &Topic, +) -> Result { + tokio::time::timeout( + config.connect_timeout, + connect_once(config, identity, role, topic), + ) + .await + .map_err(|_| crate::error::ClientError::Timeout)? +} + +fn classify_connect_error(error: &crate::error::ClientError) -> ConnectionEnd { + use crate::error::ClientError; + + match error { + ClientError::InvalidConfig(_) => ConnectionEnd::Fatal { + reason: "invalid client configuration", + }, + ClientError::Url(_) => ConnectionEnd::Fatal { + reason: "invalid relay URL", + }, + ClientError::Query(_) => ConnectionEnd::Fatal { + reason: "invalid connection parameters", + }, + ClientError::Random(_) => ConnectionEnd::Fatal { + reason: "random source failure", + }, + ClientError::WebSocket(TungsteniteError::Http(response)) + if response.status().is_client_error() => + { + ConnectionEnd::Fatal { + reason: "relay rejected connection", + } + } + ClientError::Timeout => ConnectionEnd::Reconnect { + reason: "relay connect timed out", + }, + _ => ConnectionEnd::Reconnect { + reason: "relay connection failed", + }, + } +} + +async fn connect_once( + config: &ClientConfig, + identity: &IdentityKey, + role: Role, + topic: &Topic, +) -> Result { + crate::tls::ensure_crypto_provider(); + + let session_id = random::id()?.to_string(); + let token = identity.connection_token(&session_id, &config.audience, config.token_ttl)?; + + let query = ConnectionQuery { + auth: token, + role, + topic: topic.clone(), + registration_id: config.registration_id.clone(), + }; + let query = serde_urlencoded::to_string(&query)?; + + let mut url = url::Url::parse(&config.relay_url)?; + url.set_query(Some(&query)); + + log::debug!( + "connecting to relay host={} topic={}", + url.host_str().unwrap_or("?"), + topic.log_tag() + ); + let (stream, _response) = + connect_async_with_config(url.as_str(), Some(websocket_config()), false).await?; + Ok(stream) +} + +/// WebSocket limits that bound what a relay can make the client buffer. +fn websocket_config() -> WebSocketConfig { + WebSocketConfig::default() + .max_message_size(Some(MAX_RELAY_FRAME_BYTES)) + .max_frame_size(Some(MAX_RELAY_FRAME_BYTES)) + .max_write_buffer_size(MAX_WRITE_BUFFER_BYTES) +} + +/// Drive one WebSocket session. +#[allow(clippy::too_many_arguments)] +async fn run_connection( + stream: RelayStream, + topic: &Topic, + outbound: &mut mpsc::Receiver, + ready: &AtomicBool, + joined: &AtomicBool, + inbox: &mpsc::Sender, + shutdown: &mut watch::Receiver, + config: &ClientConfig, +) -> ConnectionResult { + let (mut sink, mut source) = stream.split(); + let started_at = Instant::now(); + + let mut ping = interval_at(Instant::now() + config.ping_interval, config.ping_interval); + ping.set_missed_tick_behavior(MissedTickBehavior::Delay); + let mut awaiting_pong = false; + let mut pong_deadline = Instant::now(); + let mut idle_deadline = Instant::now() + config.idle_timeout; + let mut session_writable = false; + let mut stalled = false; + // Only a pong shows the relay is reading what we send. Frames it sends + // on its own, pings included, do not. + let mut last_pong = started_at; + + // `Connected` and relay control frames must reach the client even while + // its inbox is full, but waiting for room must not stop us answering + // pings or reading the socket. Queue them here and hand them over as soon + // as there is capacity. While anything is queued, message frames are + // dropped (the peer retransmits them) so the client never sees a frame + // ahead of the lifecycle item that precedes it. A teardown, which is not + // retransmitted, joins the queue instead (see `deliver_message`). + // + // Outbound frames come first in the `select!` below, so a final message + // the client queued just before going away is still written even when + // the closed inbox ends the loop on the next turn. + let mut control = VecDeque::from([Inbox::Connected(topic.clone())]); + + let end = loop { + tokio::select! { + biased; + outbound_item = outbound.recv() => match outbound_item { + Some(Outbound::Frame(frame)) => { + // A frame queued before the relay made this session + // writable must not cross the new connection. Tracked + // frames are re-dispatched by reliability on the ready + // edge; stale untracked acks are dropped and the peer + // retransmits the envelopes. + if !session_writable { + log::debug!( + "dropping outbound frame before session_ready on topic {}", + frame.topic.log_tag() + ); + continue; + } + let Ok(text) = serde_json::to_string(&frame) else { + break ConnectionEnd::Reconnect { reason: "invalid outbound frame" }; + }; + log::trace!( + "client -> topic={} bytes={}", + frame.topic.log_tag(), + text.len() + ); + match send_with_timeout(&mut sink, Message::text(text), config.write_timeout).await { + Write::Sent => {} + Write::TimedOut => { + stalled = true; + break ConnectionEnd::Reconnect { reason: "relay write timed out" }; + } + Write::Failed => break ConnectionEnd::Reconnect { reason: "relay connection lost" }, + } + } + None => break ConnectionEnd::Shutdown, + }, + permit = inbox.reserve(), if !control.is_empty() => match permit { + Ok(permit) => { + if let Some(item) = control.pop_front() { + permit.send(item); + } + } + Err(_) => break ConnectionEnd::Shutdown, + }, + message = source.next() => match message { + Some(Ok(Message::Text(text))) => { + idle_deadline = Instant::now() + config.idle_timeout; + match serde_json::from_str::(&text) { + // The relay binds this socket to one topic. A frame for + // another topic or version must not move our + // readiness or reach the client. + Ok(frame) if frame.v != RelayFrame::VERSION || frame.topic != *topic => { + log::warn!( + "dropping relay frame with version {} for topic {}", + frame.v, + frame.topic.log_tag() + ); + } + Ok(frame) => { + log::trace!( + "client <- topic={} bytes={}", + frame.topic.log_tag(), + text.len() + ); + if matches!(&frame.body, RelayFrameBody::SessionReady) { + // A peer can return after its grace window and + // the relay sends another `session_ready` on + // the same socket. The shared flag must follow + // every one of them, not just the first. + session_writable = true; + ready.store(true, Ordering::Relaxed); + joined.store(true, Ordering::Relaxed); + } + if matches!(&frame.body, RelayFrameBody::PeerDisconnected) { + session_writable = false; + ready.store(false, Ordering::Relaxed); + } + if !matches!(&frame.body, RelayFrameBody::Message { .. }) { + queue_control(&mut control, frame); + } else if !deliver_message(&mut control, inbox, frame) { + break ConnectionEnd::Shutdown; + } + } + Err(error) => { + log::warn!("invalid relay frame: {}", JsonErrorSummary(&error)); + } + } + } + Some(Ok(Message::Ping(payload))) => { + idle_deadline = Instant::now() + config.idle_timeout; + match send_with_timeout( + &mut sink, + Message::Pong(payload), + config.write_timeout, + ) + .await + { + Write::Sent => {} + Write::TimedOut => { + stalled = true; + break ConnectionEnd::Reconnect { reason: "relay write timed out" }; + } + Write::Failed => break ConnectionEnd::Reconnect { reason: "relay connection lost" }, + } + } + Some(Ok(Message::Pong(_))) => { + idle_deadline = Instant::now() + config.idle_timeout; + last_pong = Instant::now(); + awaiting_pong = false; + } + Some(Ok(Message::Close(frame))) => break classify_close(frame), + Some(Ok(Message::Binary(_) | Message::Frame(_))) => { + idle_deadline = Instant::now() + config.idle_timeout; + } + Some(Err(error)) => { + log::debug!("relay read error: {error}"); + break ConnectionEnd::Reconnect { reason: "relay connection lost" }; + } + None => break ConnectionEnd::Reconnect { reason: "relay connection closed" }, + }, + _ = ping.tick(), if !awaiting_pong => { + awaiting_pong = true; + pong_deadline = Instant::now() + config.pong_timeout; + match send_with_timeout(&mut sink, Message::Ping(Bytes::new()), config.write_timeout).await { + Write::Sent => {} + Write::TimedOut => { + stalled = true; + break ConnectionEnd::Reconnect { reason: "relay write timed out" }; + } + Write::Failed => break ConnectionEnd::Reconnect { reason: "relay connection lost" }, + } + } + _ = sleep_until(pong_deadline), if awaiting_pong => { + log::debug!("relay pong timed out"); + stalled = true; + break ConnectionEnd::Reconnect { reason: "relay pong timed out" }; + } + _ = sleep_until(idle_deadline) => { + log::debug!("relay idle timeout"); + stalled = true; + break ConnectionEnd::Reconnect { reason: "relay idle timeout" }; + } + _ = shutdown.changed() => break ConnectionEnd::Shutdown, + } + }; + + if matches!(end, ConnectionEnd::Shutdown) { + close_socket(&mut sink, config.close_timeout).await; + } + + let healthy_for = if stalled { + last_pong.saturating_duration_since(started_at) + } else { + started_at.elapsed() + }; + ConnectionResult { + end, + healthy_for, + undelivered: control.into(), + } +} + +/// Queue a relay control frame for the client. +/// +/// An undelivered `session_ready` is stale once anything newer arrives, so it +/// is replaced. A `peer_disconnected` is kept even if the peer has returned +/// since: the application must still learn that the peer was gone and its +/// grace window ran out. A repeated one collapses into the first. So besides +/// `Connected` the queue never holds more than one `peer_disconnected` +/// followed by one `session_ready`, and at most one teardown that +/// `deliver_message` queued among them. +fn queue_control(control: &mut VecDeque, frame: RelayFrame) { + let is = |item: Option<&Inbox>, wanted: fn(&RelayFrameBody) -> bool| matches!(item, Some(Inbox::Frame(queued)) if wanted(&queued.body)); + let ready = |body: &RelayFrameBody| matches!(body, RelayFrameBody::SessionReady); + let gone = |body: &RelayFrameBody| matches!(body, RelayFrameBody::PeerDisconnected); + + if is(control.back(), ready) { + control.pop_back(); + } + if gone(&frame.body) && is(control.back(), gone) { + return; + } + control.push_back(Inbox::Frame(frame)); +} + +fn classify_close(frame: Option) -> ConnectionEnd { + match frame { + Some(frame) if frame.code == CloseCode::Policy => match frame.reason.as_str() { + "token expired" => ConnectionEnd::ReconnectNow { + reason: "token expired", + }, + "role already taken" => ConnectionEnd::Fatal { + reason: "role already taken", + }, + _ => ConnectionEnd::Fatal { + reason: "relay policy rejection", + }, + }, + _ => ConnectionEnd::Reconnect { + reason: "relay closed connection", + }, + } +} + +/// How a bounded write ended. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Write { + Sent, + /// The write deadline passed: the relay stopped reading. + TimedOut, + /// The socket failed the write, for example because it was reset. + Failed, +} + +async fn send_with_timeout(sink: &mut S, message: Message, timeout: Duration) -> Write +where + S: Sink + Unpin, +{ + match tokio::time::timeout(timeout, sink.send(message)).await { + Ok(Ok(())) => Write::Sent, + Ok(Err(_)) => Write::Failed, + Err(_) => Write::TimedOut, + } +} + +async fn close_socket(sink: &mut S, timeout: Duration) +where + S: Sink + Unpin, +{ + let close = async { + let frame = CloseFrame { + code: CloseCode::Normal, + reason: "client shutdown".into(), + }; + let _ = sink.send(Message::Close(Some(frame))).await; + let _ = sink.close().await; + }; + let _ = tokio::time::timeout(timeout, close).await; +} + +#[cfg(test)] +mod tests { + use super::*; + + fn control(body: RelayFrameBody) -> RelayFrame { + RelayFrame { + v: RelayFrame::VERSION, + id: wallet_session_core::message::MessageId::from_bytes([0u8; 16]), + topic: Topic::new([9u8; 32]).expect("topic"), + body, + } + } + + fn kinds(control: &VecDeque) -> Vec<&'static str> { + control + .iter() + .map(|item| match item { + Inbox::Connected(_) => "connected", + Inbox::Frame(frame) => match frame.body { + RelayFrameBody::SessionReady => "ready", + RelayFrameBody::PeerDisconnected => "gone", + RelayFrameBody::Message { .. } => "message", + }, + _ => "other", + }) + .collect() + } + + #[test] + fn queued_peer_disconnect_survives_the_peer_returning() { + let topic = Topic::new([9u8; 32]).expect("topic"); + let mut queue = VecDeque::from([Inbox::Connected(topic)]); + + queue_control(&mut queue, control(RelayFrameBody::SessionReady)); + // A stale ready is replaced; a disconnect is kept when the peer returns. + queue_control(&mut queue, control(RelayFrameBody::PeerDisconnected)); + queue_control(&mut queue, control(RelayFrameBody::SessionReady)); + assert_eq!(kinds(&queue), ["connected", "gone", "ready"]); + + // Leaving and returning again collapses into the same shape. + queue_control(&mut queue, control(RelayFrameBody::PeerDisconnected)); + queue_control(&mut queue, control(RelayFrameBody::PeerDisconnected)); + assert_eq!(kinds(&queue), ["connected", "gone"]); + queue_control(&mut queue, control(RelayFrameBody::SessionReady)); + assert_eq!(kinds(&queue), ["connected", "gone", "ready"]); + } + + #[test] + fn websocket_limits_match_the_relay_default() { + let config = websocket_config(); + assert_eq!(config.max_message_size, Some(MAX_RELAY_FRAME_BYTES)); + assert_eq!(config.max_frame_size, Some(MAX_RELAY_FRAME_BYTES)); + assert_eq!(config.max_write_buffer_size, MAX_WRITE_BUFFER_BYTES); + } + + struct PendingSink; + + impl Sink for PendingSink { + type Error = std::io::Error; + + fn poll_ready( + self: std::pin::Pin<&mut Self>, + _: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + std::task::Poll::Pending + } + + fn start_send( + self: std::pin::Pin<&mut Self>, + _: Message, + ) -> std::result::Result<(), Self::Error> { + unreachable!() + } + + fn poll_flush( + self: std::pin::Pin<&mut Self>, + _: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + std::task::Poll::Pending + } + + fn poll_close( + self: std::pin::Pin<&mut Self>, + _: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + std::task::Poll::Pending + } + } + + #[tokio::test(start_paused = true)] + async fn write_timeout_fails_a_stalled_sink() { + let mut sink = PendingSink; + assert_eq!( + send_with_timeout(&mut sink, Message::text("frame"), Duration::from_secs(1)).await, + Write::TimedOut + ); + } + + struct BrokenSink; + + impl Sink for BrokenSink { + type Error = std::io::Error; + + fn poll_ready( + self: std::pin::Pin<&mut Self>, + _: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + std::task::Poll::Ready(Err(std::io::ErrorKind::ConnectionReset.into())) + } + + fn start_send( + self: std::pin::Pin<&mut Self>, + _: Message, + ) -> std::result::Result<(), Self::Error> { + Err(std::io::ErrorKind::ConnectionReset.into()) + } + + fn poll_flush( + self: std::pin::Pin<&mut Self>, + _: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + std::task::Poll::Ready(Err(std::io::ErrorKind::ConnectionReset.into())) + } + + fn poll_close( + self: std::pin::Pin<&mut Self>, + _: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + std::task::Poll::Ready(Ok(())) + } + } + + #[tokio::test] + async fn a_failed_write_is_not_a_stall() { + let mut sink = BrokenSink; + assert_eq!( + send_with_timeout(&mut sink, Message::text("frame"), Duration::from_secs(1)).await, + Write::Failed + ); + } + + /// A lifecycle item waits as long as it takes for room in the inbox. It + /// must never give up, which is what left the client with no transport + /// and no error before. + #[tokio::test(start_paused = true)] + async fn lifecycle_sends_wait_for_room_instead_of_giving_up() { + let topic = Topic::new([9u8; 32]).expect("topic"); + let (inbox, mut receiver) = mpsc::channel(1); + inbox + .try_send(Inbox::Connected(topic.clone())) + .expect("first item"); + let (_shutdown_tx, mut shutdown) = watch::channel(false); + let send = tokio::spawn(async move { + send_inbox_wait(&inbox, Inbox::Disconnected(topic), &mut shutdown).await + }); + + // Far longer than any timeout the transport uses. + tokio::time::sleep(Duration::from_secs(24 * 60 * 60)).await; + assert!(!send.is_finished(), "the send must still be waiting"); + + assert!(matches!(receiver.recv().await, Some(Inbox::Connected(_)))); + assert!( + send.await.expect("task"), + "the send completes once there is room" + ); + assert!(matches!( + receiver.recv().await, + Some(Inbox::Disconnected(_)) + )); + } + + fn message(kind: &str) -> RelayFrame { + control(RelayFrameBody::Message { + payload: format!(r#"{{"kind":"{kind}"}}"#), + }) + } + + #[test] + fn message_delivery_is_non_blocking() { + let (inbox, receiver) = mpsc::channel(1); + let mut queue = VecDeque::new(); + assert!(deliver_message(&mut queue, &inbox, message("request"))); + assert!(deliver_message(&mut queue, &inbox, message("request"))); + assert!( + queue.is_empty(), + "a message the inbox has no room for is dropped" + ); + + drop(receiver); + assert!(!deliver_message(&mut queue, &inbox, message("request"))); + } + + #[test] + fn a_teardown_waits_when_the_inbox_is_full() { + let (inbox, _receiver) = mpsc::channel(1); + let mut queue = VecDeque::new(); + assert!(deliver_message(&mut queue, &inbox, message("request"))); + + assert!(deliver_message(&mut queue, &inbox, message("disconnect"))); + assert_eq!(kinds(&queue), ["message"]); + // Later messages, and later teardowns, are dropped behind it. + assert!(deliver_message(&mut queue, &inbox, message("request"))); + assert!(deliver_message( + &mut queue, + &inbox, + message("session_delete") + )); + assert_eq!(kinds(&queue), ["message"]); + assert!(matches!( + queue.front(), + Some(Inbox::Frame(RelayFrame { body: RelayFrameBody::Message { payload }, .. })) + if payload.contains("disconnect") + )); + } + + #[test] + fn teardowns_and_control_frames_keep_the_queue_bounded() { + // Whoever sends these, relay or peer, must not be able to grow the + // queue: a teardown waiting at the back must not stop repeated + // control frames from merging. + let topic = Topic::new([9u8; 32]).expect("topic"); + let (inbox, _receiver) = mpsc::channel(1); + inbox + .try_send(Inbox::Connected(topic.clone())) + .expect("fill the inbox"); + for first in [ + RelayFrameBody::PeerDisconnected, + RelayFrameBody::SessionReady, + ] { + let mut queue = VecDeque::from([Inbox::Connected(topic.clone())]); + for _ in 0..1000 { + queue_control(&mut queue, control(first.clone())); + assert!(deliver_message(&mut queue, &inbox, message("disconnect"))); + let second = match first { + RelayFrameBody::PeerDisconnected => RelayFrameBody::SessionReady, + _ => RelayFrameBody::PeerDisconnected, + }; + queue_control(&mut queue, control(second)); + } + assert!(queue.len() <= 5, "{:?}", kinds(&queue)); + } + } + + #[test] + fn a_teardown_waits_behind_queued_control_items() { + let topic = Topic::new([9u8; 32]).expect("topic"); + let (inbox, _receiver) = mpsc::channel(8); + let mut queue = VecDeque::from([Inbox::Connected(topic)]); + assert!(deliver_message(&mut queue, &inbox, message("request"))); + assert!(deliver_message(&mut queue, &inbox, message("disconnect"))); + assert_eq!(kinds(&queue), ["connected", "message"]); + } + + #[test] + fn classifies_policy_closes() { + let close = |code: CloseCode, reason: &str| { + Some(CloseFrame { + code, + reason: reason.into(), + }) + }; + + assert_eq!( + classify_close(close(CloseCode::Policy, "token expired")), + ConnectionEnd::ReconnectNow { + reason: "token expired" + } + ); + assert_eq!( + classify_close(close(CloseCode::Policy, "role already taken")), + ConnectionEnd::Fatal { + reason: "role already taken" + } + ); + assert_eq!( + classify_close(close(CloseCode::Policy, "something else")), + ConnectionEnd::Fatal { + reason: "relay policy rejection" + } + ); + assert_eq!( + classify_close(close(CloseCode::Normal, "")), + ConnectionEnd::Reconnect { + reason: "relay closed connection" + } + ); + assert_eq!( + classify_close(None), + ConnectionEnd::Reconnect { + reason: "relay closed connection" + } + ); + } +} diff --git a/crates/client/src/reliability.rs b/crates/client/src/reliability.rs new file mode 100644 index 0000000..8399997 --- /dev/null +++ b/crates/client/src/reliability.rs @@ -0,0 +1,1145 @@ +use std::{ + collections::HashMap, + sync::{ + Arc, Mutex, + atomic::{AtomicBool, Ordering}, + }, + time::Duration, +}; + +use tokio::{ + sync::{OwnedSemaphorePermit, Semaphore, mpsc}, + task::JoinHandle, + time::{Instant, interval}, +}; +use wallet_session_core::{ + frame::RelayFrame, + message::{MessageId, MessageType}, +}; + +use crate::{config::MAX_RETRY_DELAY, error::ClientError, identity::unix_now, relay::Outbound}; + +/// Events buffered between the reliability task and the client. +pub(crate) const EVENT_CAPACITY: usize = 256; + +/// Maximum pending messages plus unconsumed delivery outcomes per link. +pub(crate) const PENDING_CAPACITY: usize = 256; + +/// A delivery event and the reservation it releases when consumed. +pub(crate) type DeliveryEvent = (ClientEvent, OwnedSemaphorePermit); + +/// Reliability events surfaced to the application. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ClientEvent { + /// A sent message was acknowledged by the peer. + Delivered { + /// Envelope id that was acknowledged. + id: MessageId, + }, + + /// A sent message was not confirmed as delivered. + /// + /// Its retransmissions ran out, its `ts` became too old for the peer to + /// accept, or the client closed while it was outstanding. This means + /// "delivery unconfirmed", not "not delivered": a copy that was already + /// sent can still reach the peer until its `ts` is 300 seconds old, and an ack that arrives after this event produces no + /// further event. Re-sending the same operation under a new id can + /// therefore perform it twice, so requests that must not repeat should be + /// idempotent at the application level. + Failed { + /// Envelope id that was not acknowledged. + id: MessageId, + + /// Retransmissions attempted before giving up. + attempts: usize, + }, + + /// The relay connection was lost and a reconnect is starting. + Reconnecting, + + /// The relay connection was re-established. + Reconnected, +} + +/// Whether a message type must be acknowledged. +pub(crate) fn requires_ack(kind: MessageType) -> bool { + matches!( + kind, + MessageType::Proposal + | MessageType::Approve + | MessageType::Reject + | MessageType::Request + | MessageType::Response + | MessageType::Disconnect + | MessageType::SessionDelete + ) +} + +struct Pending { + frame: RelayFrame, + attempts: usize, + next: Instant, + sequence: u64, + expires_at: u64, + sent: bool, + permit: OwnedSemaphorePermit, +} + +/// Outbound reliability: ack tracking and retransmission. +pub(crate) struct Reliability { + outbox: mpsc::Sender, + pending: Arc>>, + ready: Arc, + lifecycle: mpsc::Sender, + outcomes: mpsc::UnboundedSender, + permits: Arc, + base_delay: Duration, + next_sequence: u64, + _retry: JoinHandle<()>, +} + +impl Reliability { + #[allow(clippy::too_many_arguments)] + pub(crate) fn spawn( + outbox: mpsc::Sender, + ready: Arc, + lifecycle: mpsc::Sender, + outcomes: mpsc::UnboundedSender, + base_delay: Duration, + max_attempts: usize, + retransmit_spacing: Duration, + retransmit_bytes_per_second: usize, + ) -> Self { + let pending = Arc::new(Mutex::new(HashMap::new())); + let permits = Arc::new(Semaphore::new(PENDING_CAPACITY)); + let _retry = tokio::spawn(retry_loop( + Arc::clone(&pending), + Arc::clone(&ready), + outbox.clone(), + outcomes.clone(), + base_delay, + max_attempts, + retransmit_spacing, + retransmit_bytes_per_second, + )); + + Self { + outbox, + pending, + ready, + lifecycle, + outcomes, + permits, + base_delay, + next_sequence: 0, + _retry, + } + } + + /// Emit a droppable lifecycle event to the application. + pub(crate) fn emit(&self, event: ClientEvent) { + let _ = self.lifecycle.try_send(event); + } + + /// Enqueue a frame, tracking it for retransmission when `track` is set. + pub(crate) fn dispatch( + &mut self, + frame: RelayFrame, + track: bool, + ts: u64, + ) -> Result<(), ClientError> { + let id = frame.id.clone(); + let is_ready = self.ready.load(Ordering::Relaxed); + if track { + let permit = self + .permits + .clone() + .try_acquire_owned() + .map_err(|_| ClientError::Busy)?; + let sequence = self.next_sequence; + self.next_sequence = self.next_sequence.wrapping_add(1); + let pending = Pending { + frame: frame.clone(), + attempts: 0, + next: Instant::now() + self.base_delay, + sequence, + expires_at: ts.saturating_add(300), + sent: is_ready, + permit, + }; + let mut pending_messages = self.pending.lock().expect("reliability lock"); + if !pending_messages.contains_key(&id) && pending_messages.len() >= PENDING_CAPACITY { + return Err(ClientError::Busy); + } + pending_messages.insert(id.clone(), pending); + } + + // While the relay session is not ready, tracked frames wait only in + // the pending map. Sending them now would duplicate the reconnect + // flush after the transport queue survives a disconnect. + if track && !is_ready { + return Ok(()); + } + + match self.outbox.try_send(Outbound::Frame(frame)) { + Ok(()) => Ok(()), + Err(mpsc::error::TrySendError::Full(_)) => { + if track { + self.pending.lock().expect("reliability lock").remove(&id); + } + Err(ClientError::Busy) + } + Err(mpsc::error::TrySendError::Closed(_)) => { + if track { + self.pending.lock().expect("reliability lock").remove(&id); + } + Err(ClientError::Closed) + } + } + } + + /// Report and remove every outstanding tracked message. + pub(crate) fn fail_all(&mut self) { + let pending: Vec<(MessageId, Pending)> = self + .pending + .lock() + .expect("reliability lock") + .drain() + .collect(); + for (id, entry) in pending { + let _ = self.outcomes.send(( + ClientEvent::Failed { + id, + attempts: entry.attempts, + }, + entry.permit, + )); + } + } + + /// Record an inbound ACK, reporting delivery. Returns whether it + /// completed an outstanding send. + pub(crate) fn mark_delivered(&mut self, ack_id: &MessageId) -> bool { + let Some(entry) = self + .pending + .lock() + .expect("reliability lock") + .remove(ack_id) + else { + return false; + }; + let _ = self + .outcomes + .send((ClientEvent::Delivered { id: ack_id.clone() }, entry.permit)); + true + } +} + +impl Drop for Reliability { + fn drop(&mut self) { + // Stop the retry task so its outbox clone is released and the writer + // task can close the socket. + self._retry.abort(); + } +} + +#[allow(clippy::too_many_arguments)] +async fn retry_loop( + pending: Arc>>, + ready: Arc, + outbox: mpsc::Sender, + outcomes: mpsc::UnboundedSender, + base_delay: Duration, + max_attempts: usize, + retransmit_spacing: Duration, + retransmit_bytes_per_second: usize, +) { + let mut ticker = interval(Duration::from_millis(50)); + let mut was_ready = ready.load(Ordering::Relaxed); + let mut next_send = Instant::now(); + + loop { + ticker.tick().await; + + let now = Instant::now(); + let now_unix = unix_now(); + let is_ready = ready.load(Ordering::Relaxed); + let mut resend = None; + let mut failed = Vec::new(); + + { + let mut pending = pending.lock().expect("reliability lock"); + + // An envelope past ts + 300 can no longer be accepted by the peer. + let expired: Vec = pending + .iter() + .filter(|(_, entry)| now_unix > entry.expires_at) + .map(|(id, _)| id.clone()) + .collect(); + for id in expired { + if let Some(entry) = pending.remove(&id) { + failed.push((id, entry)); + } + } + + if is_ready { + if !was_ready { + // A reconnect flush starts now, but is paced below. + next_send = now; + } + // Only frames that were never written on this connection + // need their first write. A frame dispatched after the relay + // became ready was already sent by `dispatch`; resetting its + // deadline here would duplicate it. Keep entries already in + // their final ack wait on their original deadline instead of + // failing them immediately. + for entry in pending + .values_mut() + .filter(|entry| !entry.sent && entry.attempts < max_attempts) + { + entry.next = now; + } + } else { + // A frame written on a connection that ended is not known to + // have reached the peer. Retry it after the next ready edge, + // but leave final-ack waits on their original deadline. + for entry in pending + .values_mut() + .filter(|entry| entry.attempts < max_attempts) + { + entry.sent = false; + } + } + + if is_ready && now >= next_send { + let candidate = pending + .iter() + .filter(|(_, entry)| entry.next <= now) + .map(|(id, entry)| (id.clone(), entry.next, entry.sequence)) + .min_by_key(|(_, next, sequence)| (*next, *sequence)); + + if let Some((id, _, _)) = candidate { + let entry = pending.get_mut(&id).expect("candidate exists"); + if entry.attempts >= max_attempts { + if let Some(entry) = pending.remove(&id) { + failed.push((id, entry)); + } + } else { + entry.attempts += 1; + entry.next = now + backoff(base_delay, entry.attempts); + entry.sent = true; + resend = Some((id, entry.frame.clone())); + } + } + } + + // Report failures before waiting for outbox room below. These + // entries are already gone from `pending`, so if the task were + // aborted (the link closing) or the outbox closed during that + // wait, nothing else could ever report them. + // + // Do it before releasing the lock, too. `fail_all` takes the + // same lock when the client closes, so every failure is then + // published either here or there before the close returns, and + // none can turn up after the terminal error. + for (id, entry) in failed { + let _ = outcomes.send(( + ClientEvent::Failed { + id, + attempts: entry.attempts, + }, + entry.permit, + )); + } + } + + was_ready = is_ready; + + if let Some((id, frame)) = resend { + let frame_len = serde_json::to_string(&frame) + .map(|text| text.len()) + .unwrap_or(0); + if outbox.send(Outbound::Frame(frame)).await.is_err() { + return; + } + // The frame only leaves now, after waiting for outbox room. Count + // its ack window and the pacing from here, or a long wait would + // use up the window before the frame was even written. + let sent_at = Instant::now(); + if let Some(entry) = pending.lock().expect("reliability lock").get_mut(&id) { + entry.next = sent_at + backoff(base_delay, entry.attempts); + } + let byte_delay = + Duration::from_secs_f64(frame_len as f64 / retransmit_bytes_per_second as f64); + let spacing = retransmit_spacing.max(byte_delay); + next_send = sent_at + .checked_add(spacing) + .unwrap_or(sent_at + MAX_RETRY_DELAY); + } + } +} + +fn backoff(base: Duration, attempts: usize) -> Duration { + base.saturating_mul(2u32.pow(attempts.min(31) as u32)) + .min(MAX_RETRY_DELAY) +} + +#[cfg(test)] +mod tests { + use super::*; + use wallet_session_core::{frame::RelayFrameBody, message::Topic}; + + struct TestEvents { + lifecycle: mpsc::Receiver, + outcomes: mpsc::UnboundedReceiver, + } + + impl TestEvents { + fn try_recv(&mut self) -> Option { + self.outcomes + .try_recv() + .ok() + .map(|(event, _permit)| event) + .or_else(|| self.lifecycle.try_recv().ok()) + } + } + + fn spawn_reliability( + outbox: mpsc::Sender, + ready: Arc, + base_delay: Duration, + max_attempts: usize, + retransmit_spacing: Duration, + ) -> (Reliability, TestEvents) { + spawn_reliability_with_bytes( + outbox, + ready, + base_delay, + max_attempts, + retransmit_spacing, + 256 * 1024, + ) + } + + fn spawn_reliability_with_bytes( + outbox: mpsc::Sender, + ready: Arc, + base_delay: Duration, + max_attempts: usize, + retransmit_spacing: Duration, + retransmit_bytes_per_second: usize, + ) -> (Reliability, TestEvents) { + let (lifecycle, lifecycle_rx) = mpsc::channel(EVENT_CAPACITY); + let (outcomes, outcomes_rx) = mpsc::unbounded_channel(); + let reliability = Reliability::spawn( + outbox, + ready, + lifecycle, + outcomes, + base_delay, + max_attempts, + retransmit_spacing, + retransmit_bytes_per_second, + ); + ( + reliability, + TestEvents { + lifecycle: lifecycle_rx, + outcomes: outcomes_rx, + }, + ) + } + + /// A distinct, valid message id for a test label. + fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) + } + + fn frame(id: &str) -> RelayFrame { + RelayFrame { + v: 1, + id: message_id(id), + topic: Topic::new([0u8; 32]).expect("topic"), + body: RelayFrameBody::Message { + payload: "payload".to_owned(), + }, + } + } + + #[tokio::test] + async fn failures_are_reported_while_the_outbox_is_full() { + // An outbox with no room, which nothing drains. + let (outbox, _outbound) = mpsc::channel(1); + outbox + .try_send(Outbound::Frame(frame("filler"))) + .expect("room for one"); + let ready = ready(false); + let (mut reliability, mut events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(100), + ); + + // One entry has already expired; the other needs its first write once + // the link is ready, which will wait on the full outbox. + reliability + .dispatch(frame("expired"), true, unix_now() - 400) + .expect("dispatch"); + reliability + .dispatch(frame("waiting"), true, unix_now()) + .expect("dispatch"); + ready.store(true, Ordering::Relaxed); + + let (event, _permit) = tokio::time::timeout(Duration::from_secs(2), events.outcomes.recv()) + .await + .expect("the failure must not wait for outbox room") + .expect("outcome"); + assert_eq!( + event, + ClientEvent::Failed { + id: message_id("expired"), + attempts: 0 + } + ); + } + + #[tokio::test(start_paused = true)] + async fn the_ack_window_starts_when_a_retry_reaches_the_outbox() { + // An outbox with no room until the test drains it. + let (outbox, mut outbound) = mpsc::channel(1); + outbox + .try_send(Outbound::Frame(frame("filler"))) + .expect("room for one"); + let ready = ready(false); + let (mut reliability, mut events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(1), + 1, + Duration::from_millis(100), + ); + + // Its only write waits four seconds for room. The ack window after + // it is two seconds. + reliability + .dispatch(frame("slow"), true, unix_now()) + .expect("dispatch"); + ready.store(true, Ordering::Relaxed); + tokio::time::sleep(Duration::from_secs(4)).await; + assert!( + matches!(outbound.recv().await, Some(Outbound::Frame(f)) if f.id == message_id("filler")) + ); + assert!( + matches!(outbound.recv().await, Some(Outbound::Frame(f)) if f.id == message_id("slow")) + ); + + assert!( + tokio::time::timeout(Duration::from_millis(1_500), events.outcomes.recv()) + .await + .is_err(), + "the window must not have run while the frame waited for room" + ); + let (event, _permit) = tokio::time::timeout(Duration::from_secs(1), events.outcomes.recv()) + .await + .expect("the window ends") + .expect("outcome"); + assert_eq!( + event, + ClientEvent::Failed { + id: message_id("slow"), + attempts: 1 + } + ); + } + + #[tokio::test] + async fn delivery_outcomes_survive_a_full_lifecycle_queue() { + let (outbox, _outbound) = mpsc::channel(16); + let (lifecycle, mut lifecycle_rx) = mpsc::channel(1); + let (outcomes, mut outcomes_rx) = mpsc::unbounded_channel(); + let mut reliability = Reliability::spawn( + outbox, + ready(true), + lifecycle, + outcomes, + Duration::from_secs(1), + 5, + Duration::from_millis(100), + 256 * 1024, + ); + + // Fill and overflow the droppable lifecycle channel. + reliability.emit(ClientEvent::Reconnecting); + reliability.emit(ClientEvent::Reconnected); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + reliability.mark_delivered(&message_id("a")); + + let (event, _permit) = outcomes_rx.try_recv().expect("delivery outcome"); + assert_eq!( + event, + ClientEvent::Delivered { + id: message_id("a") + } + ); + assert!(lifecycle_rx.try_recv().is_ok()); + } + + #[tokio::test] + async fn delivered_outcomes_hold_capacity_until_consumed() { + let (outbox, _outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, mut events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(100), + ); + + for index in 0..PENDING_CAPACITY { + let label = format!("d{index}"); + reliability + .dispatch(frame(&label), true, unix_now()) + .expect("dispatch"); + reliability.mark_delivered(&message_id(&label)); + } + + // Every outcome still holds its permit. + assert!(matches!( + reliability.dispatch(frame("overflow"), true, unix_now()), + Err(ClientError::Busy) + )); + + // Consuming one outcome releases one reservation. + let _ = events.outcomes.try_recv().expect("delivery outcome"); + reliability + .dispatch(frame("replacement"), true, unix_now()) + .expect("released capacity"); + } + + #[tokio::test] + async fn failed_outcomes_hold_capacity_until_consumed() { + let (outbox, _outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, mut events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(100), + ); + + for index in 0..PENDING_CAPACITY { + reliability + .dispatch(frame(&format!("f{index}")), true, unix_now()) + .expect("dispatch"); + } + reliability.fail_all(); + + assert!(matches!( + reliability.dispatch(frame("overflow"), true, unix_now()), + Err(ClientError::Busy) + )); + + let _ = events.outcomes.try_recv().expect("failed outcome"); + reliability + .dispatch(frame("replacement"), true, unix_now()) + .expect("released capacity"); + } + + #[test] + fn ack_classification() { + assert!(requires_ack(MessageType::Proposal)); + assert!(requires_ack(MessageType::Request)); + assert!(requires_ack(MessageType::Response)); + assert!(!requires_ack(MessageType::Ack)); + } + + #[test] + fn backoff_is_capped_at_the_retry_window() { + assert_eq!(backoff(Duration::from_secs(1), 1), Duration::from_secs(2)); + assert_eq!(backoff(Duration::from_secs(1), 31), MAX_RETRY_DELAY); + } + + #[tokio::test(start_paused = true)] + async fn huge_retransmit_spacing_does_not_overflow() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, _events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(1), + 5, + Duration::MAX, + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + ready.store(true, Ordering::Relaxed); + tokio::time::advance(Duration::from_secs(1)).await; + tokio::task::yield_now().await; + + assert!(matches!(outbound.try_recv(), Ok(Outbound::Frame(_)))); + } + + fn ready(value: bool) -> Arc { + Arc::new(AtomicBool::new(value)) + } + + #[tokio::test] + async fn reports_a_full_outbound_queue() { + let (outbox, _outbound) = mpsc::channel(1); + let (mut reliability, _events) = spawn_reliability( + outbox, + ready(true), + Duration::from_secs(1), + 5, + Duration::from_millis(100), + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("first dispatch"); + assert!(matches!( + reliability.dispatch(frame("b"), true, unix_now()), + Err(ClientError::Busy) + )); + assert_eq!( + reliability.pending.lock().expect("reliability lock").len(), + 1, + "a refused frame must not stay pending" + ); + } + + #[tokio::test] + async fn delivers_when_acked() { + let (outbox, mut outbound) = mpsc::channel(16); + let (mut reliability, mut events) = spawn_reliability( + outbox, + ready(true), + Duration::from_secs(1), + 5, + Duration::from_millis(100), + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + assert!(matches!(outbound.try_recv(), Ok(Outbound::Frame(_)))); + + reliability.mark_delivered(&message_id("a")); + assert_eq!( + events.try_recv().expect("event"), + ClientEvent::Delivered { + id: message_id("a") + } + ); + } + + #[tokio::test(start_paused = true)] + async fn retries_then_fails() { + let (outbox, mut outbound) = mpsc::channel(16); + let (mut reliability, mut events) = spawn_reliability( + outbox, + ready(true), + Duration::from_secs(1), + 2, + Duration::from_millis(100), + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + assert!(matches!(outbound.try_recv(), Ok(Outbound::Frame(_)))); + + // Let the retry task run through the backoff schedule and give up. + for _ in 0..200 { + tokio::time::advance(Duration::from_millis(100)).await; + tokio::task::yield_now().await; + } + + let mut resends = 0; + while let Ok(Outbound::Frame(_)) = outbound.try_recv() { + resends += 1; + } + assert_eq!(resends, 2, "expected exactly two retransmissions"); + + let mut failed = None; + while let Some(event) = events.try_recv() { + if let ClientEvent::Failed { id, attempts } = event { + failed = Some((id, attempts)); + } + } + assert_eq!(failed, Some((message_id("a"), 2))); + } + + #[tokio::test(start_paused = true)] + async fn pauses_while_disconnected_and_flushes_on_reconnect() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, _events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(1), + 3, + Duration::from_millis(100), + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + assert!( + outbound.try_recv().is_err(), + "a frame dispatched while not ready must not be queued" + ); + + for _ in 0..20 { + tokio::time::advance(Duration::from_millis(100)).await; + tokio::task::yield_now().await; + } + assert!( + outbound.try_recv().is_err(), + "no send expected while disconnected" + ); + + ready.store(true, Ordering::Relaxed); + for _ in 0..5 { + tokio::time::advance(Duration::from_millis(100)).await; + tokio::task::yield_now().await; + } + assert!( + matches!(outbound.try_recv(), Ok(Outbound::Frame(_))), + "expected a flush after readiness" + ); + } + + #[tokio::test(start_paused = true)] + async fn ready_edge_does_not_duplicate_a_frame_sent_after_readiness() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, _events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(100), + ); + + // Let the retry task observe the disconnected state. + for _ in 0..5 { + tokio::time::advance(Duration::from_millis(50)).await; + tokio::task::yield_now().await; + } + + // The link becomes ready and dispatch writes the frame before the + // retry task's next tick observes the ready edge. + ready.store(true, Ordering::Relaxed); + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + assert!(matches!(outbound.try_recv(), Ok(Outbound::Frame(_)))); + while outbound.try_recv().is_ok() {} + + // Treating that edge as a reconnect flush would duplicate the frame. + for _ in 0..5 { + tokio::time::advance(Duration::from_millis(50)).await; + tokio::task::yield_now().await; + } + assert!( + outbound.try_recv().is_err(), + "the ready edge must not duplicate a frame sent after readiness" + ); + } + + #[tokio::test(start_paused = true)] + async fn reconnect_flushes_a_frame_sent_before_disconnect() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(true); + let (mut reliability, _events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(100), + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + assert!(matches!(outbound.try_recv(), Ok(Outbound::Frame(_)))); + + // Observe the disconnect, then the reconnect. + ready.store(false, Ordering::Relaxed); + for _ in 0..5 { + tokio::time::advance(Duration::from_millis(50)).await; + tokio::task::yield_now().await; + } + ready.store(true, Ordering::Relaxed); + for _ in 0..5 { + tokio::time::advance(Duration::from_millis(50)).await; + tokio::task::yield_now().await; + } + + assert!( + matches!(outbound.try_recv(), Ok(Outbound::Frame(_))), + "reconnect must flush a frame sent before the disconnect" + ); + } + + #[tokio::test(start_paused = true)] + async fn flushes_pending_frames_in_order_and_with_spacing() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, _events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(100), + ); + + for id in ["a", "b", "c"] { + reliability + .dispatch(frame(id), true, unix_now()) + .expect("dispatch"); + } + ready.store(true, Ordering::Relaxed); + + let start = Instant::now(); + let mut sent: Vec<(Duration, MessageId)> = Vec::new(); + for _ in 0..20 { + tokio::time::advance(Duration::from_millis(50)).await; + tokio::task::yield_now().await; + while let Ok(Outbound::Frame(frame)) = outbound.try_recv() { + sent.push((Instant::now().duration_since(start), frame.id)); + } + } + + let ids: Vec = sent.iter().map(|(_, id)| id.clone()).collect(); + assert_eq!(ids, [message_id("a"), message_id("b"), message_id("c")]); + assert_eq!(sent.len(), 3); + assert!( + sent[1].0 >= sent[0].0 + Duration::from_millis(100), + "second frame was not spaced: {:?}", + sent + ); + assert!( + sent[2].0 >= sent[1].0 + Duration::from_millis(100), + "third frame was not spaced: {:?}", + sent + ); + } + + #[tokio::test(start_paused = true)] + async fn full_pending_queue_flushes_every_frame_in_order() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, _events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(1), + ); + + let mut expected = Vec::new(); + for index in 0..PENDING_CAPACITY { + let id = format!("f{index}"); + reliability + .dispatch(frame(&id), true, unix_now()) + .expect("dispatch"); + expected.push(message_id(&id)); + } + assert!(matches!( + reliability.dispatch(frame("overflow"), true, unix_now()), + Err(ClientError::Busy) + )); + + ready.store(true, Ordering::Relaxed); + let mut sent = Vec::new(); + for _ in 0..(PENDING_CAPACITY * 2) { + tokio::time::advance(Duration::from_millis(50)).await; + tokio::task::yield_now().await; + while let Ok(Outbound::Frame(frame)) = outbound.try_recv() { + sent.push(frame.id); + } + if sent.len() == PENDING_CAPACITY { + break; + } + } + + assert_eq!(sent, expected); + } + + #[tokio::test(start_paused = true)] + async fn reconnect_flush_does_not_fail_a_final_ack_wait_early() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(true); + let (mut reliability, mut events) = spawn_reliability( + outbox, + Arc::clone(&ready), + Duration::from_secs(1), + 1, + Duration::from_millis(10), + ); + + reliability + .dispatch(frame("a"), true, unix_now()) + .expect("dispatch"); + while outbound.try_recv().is_ok() {} + + // Consume the single retry; the entry now waits for its final ack. + tokio::time::advance(Duration::from_millis(1_100)).await; + tokio::task::yield_now().await; + while outbound.try_recv().is_ok() {} + + // A frame sent before the disconnect is only flushed again when the + // retry task observes a real ready edge. Use it to synchronise on the + // retry task having seen `ready == false`. + reliability + .dispatch(frame("probe"), true, unix_now()) + .expect("dispatch"); + assert!(matches!(outbound.try_recv(), Ok(Outbound::Frame(_)))); + + ready.store(false, Ordering::Relaxed); + tokio::time::advance(Duration::from_millis(100)).await; + tokio::task::yield_now().await; + + ready.store(true, Ordering::Relaxed); + tokio::time::advance(Duration::from_millis(200)).await; + tokio::task::yield_now().await; + assert!( + matches!( + outbound.try_recv(), + Ok(Outbound::Frame(frame)) if frame.id == message_id("probe") + ), + "the retry task must have observed the disconnected state" + ); + + // The final ack wait for `a` must not be failed at the ready edge. + assert!( + events.try_recv().is_none(), + "the final ack wait must be allowed to finish" + ); + + tokio::time::advance(Duration::from_secs(3)).await; + tokio::task::yield_now().await; + let mut failed_a = false; + while let Some(event) = events.try_recv() { + if let ClientEvent::Failed { id, attempts } = event + && id == message_id("a") + { + assert_eq!(attempts, 1); + failed_a = true; + } + } + assert!(failed_a, "the final ack wait must eventually fail"); + } + + #[tokio::test(start_paused = true)] + async fn reconnect_flush_paces_by_bytes() { + let (outbox, mut outbound) = mpsc::channel(16); + let ready = ready(false); + let (mut reliability, _events) = spawn_reliability_with_bytes( + outbox, + Arc::clone(&ready), + Duration::from_secs(60), + 5, + Duration::from_millis(1), + 100, + ); + + for id in ["a", "b"] { + let mut frame = frame(id); + if let RelayFrameBody::Message { payload } = &mut frame.body { + *payload = "x".repeat(500); + } + reliability + .dispatch(frame, true, unix_now()) + .expect("dispatch"); + } + ready.store(true, Ordering::Relaxed); + + tokio::time::advance(Duration::from_secs(1)).await; + tokio::task::yield_now().await; + assert!( + matches!(outbound.try_recv(), Ok(Outbound::Frame(_))), + "the first frame should be sent" + ); + assert!( + outbound.try_recv().is_err(), + "the second frame must wait for the byte budget" + ); + + tokio::time::advance(Duration::from_secs(10)).await; + tokio::task::yield_now().await; + assert!( + matches!(outbound.try_recv(), Ok(Outbound::Frame(_))), + "the second frame should follow after the byte delay" + ); + } + + #[tokio::test(start_paused = true)] + async fn expired_frames_fail_without_sending() { + let (outbox, mut outbound) = mpsc::channel(16); + let (mut reliability, mut events) = spawn_reliability( + outbox, + ready(false), + Duration::from_secs(1), + 5, + Duration::from_millis(100), + ); + + reliability + .dispatch(frame("old"), true, unix_now().saturating_sub(301)) + .expect("dispatch"); + for _ in 0..3 { + tokio::time::advance(Duration::from_millis(100)).await; + tokio::task::yield_now().await; + } + + assert!(outbound.try_recv().is_err()); + assert!(matches!( + events.try_recv(), + Some(ClientEvent::Failed { id, .. }) if id == message_id("old") + )); + } + + #[tokio::test] + async fn fail_all_reports_every_pending_frame() { + let (outbox, _outbound) = mpsc::channel(16); + let (mut reliability, mut events) = spawn_reliability( + outbox, + ready(false), + Duration::from_secs(1), + 5, + Duration::from_millis(100), + ); + + for id in ["a", "b"] { + reliability + .dispatch(frame(id), true, unix_now()) + .expect("dispatch"); + } + reliability.fail_all(); + + let mut failed = Vec::new(); + while let Some(event) = events.try_recv() { + if let ClientEvent::Failed { id, .. } = event { + failed.push(id); + } + } + failed.sort_by_key(|id| id.to_string()); + assert_eq!(failed, [message_id("a"), message_id("b")]); + assert!(reliability.pending.lock().expect("lock").is_empty()); + } +} diff --git a/crates/client/src/replay.rs b/crates/client/src/replay.rs new file mode 100644 index 0000000..669159e --- /dev/null +++ b/crates/client/src/replay.rs @@ -0,0 +1,335 @@ +//! Per-key replay memory for authenticated inbound envelopes. + +use std::collections::HashMap; +use std::time::Duration; + +use wallet_session_core::message::{Message, MessageId}; + +/// Maximum records kept per key. +pub(crate) const CAPACITY: usize = 8192; + +/// Extra records allowed beyond [`CAPACITY`] for acks that complete one of +/// our sends, so that a full memory does not turn a delivered message into a +/// failed one. Beyond this such an ack is processed without being recorded. +pub(crate) const ACK_HEADROOM: usize = 256; + +/// How a received envelope relates to the replay memory. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum Observation { + /// A new envelope: record it and deliver it. + New, + + /// The identical envelope was already accepted: acknowledge it again, + /// but do not deliver it again. + Retransmission, + + /// An id or nonce was reused with different content. + Conflict, + + /// A new envelope cannot be recorded without exceeding the memory cap. + Full, +} + +struct Record { + digest: [u8; 32], + nonce: Vec, + ts: u64, + expires_at: u64, +} + +/// Replay memory for one key. +/// +/// A record is kept until the local clock passes the envelope's `ts` plus the +/// accepted clock-skew window. When a record expires, its `ts` is remembered, +/// so a clock that steps backward cannot make the discarded envelope +/// acceptable again. +pub(crate) struct ReplayMemory { + retention_secs: u64, + capacity: usize, + by_id: HashMap, + by_nonce: HashMap, MessageId>, + largest_discarded_ts: Option, +} + +impl ReplayMemory { + /// Build an empty replay memory with the given retention window and cap. + pub(crate) fn new(retention: Duration, capacity: usize) -> Self { + Self { + retention_secs: retention.as_secs(), + capacity, + by_id: HashMap::new(), + by_nonce: HashMap::new(), + largest_discarded_ts: None, + } + } + + /// Whether `ts` is at or below a timestamp already discarded from the + /// replay memory. + pub(crate) fn is_stale(&self, ts: u64) -> bool { + self.largest_discarded_ts + .is_some_and(|largest| ts <= largest) + } + + /// Classify an authenticated envelope against the replay memory. + /// + /// `now` is the local Unix time, after the caller has checked `message.ts` + /// against the clock-skew window. A [`Observation::New`] envelope is only + /// remembered once the caller has delivered or acknowledged it, with + /// [`ReplayMemory::record`]. + pub(crate) fn classify(&mut self, id: &MessageId, message: &Message, now: u64) -> Observation { + self.prune(now); + + if let Some(record) = self.by_id.get(id) { + return if record.digest == message.digest() { + Observation::Retransmission + } else { + log::debug!("replay conflict: frame {id} reused with different content"); + Observation::Conflict + }; + } + + if let Some(owner) = self.by_nonce.get(message.nonce.as_bytes()) + && owner != id + { + log::debug!( + "replay conflict: nonce {} used by frame {owner} and frame {id} \ + (kind={:?}, from={}, ts={})", + message.nonce, + message.kind, + message.from, + message.ts + ); + return Observation::Conflict; + } + + if self.by_id.len() >= self.capacity { + return Observation::Full; + } + + Observation::New + } + + /// Whether an ack that completed a send may still be recorded although the + /// memory is full. + pub(crate) fn has_ack_headroom(&self) -> bool { + self.by_id.len() < self.capacity.saturating_add(ACK_HEADROOM) + } + + /// Remember an envelope that was classified as [`Observation::New`]. + pub(crate) fn record(&mut self, id: &MessageId, message: &Message) { + let nonce = message.nonce.as_bytes().to_vec(); + self.by_nonce.insert(nonce.clone(), id.clone()); + self.by_id.insert( + id.clone(), + Record { + digest: message.digest(), + nonce, + ts: message.ts, + expires_at: message.ts.saturating_add(self.retention_secs), + }, + ); + } + + /// Forget an envelope that was recorded but then rejected before delivery. + pub(crate) fn forget(&mut self, id: &MessageId) { + if let Some(record) = self.by_id.remove(id) { + self.by_nonce.remove(&record.nonce); + } + } + + /// Drop records whose expiry has passed and remember their timestamps. + fn prune(&mut self, now: u64) { + let expired: Vec = self + .by_id + .iter() + .filter(|(_, record)| record.expires_at < now) + .map(|(id, _)| id.clone()) + .collect(); + + for id in expired { + if let Some(record) = self.by_id.remove(&id) { + self.by_nonce.remove(&record.nonce); + self.largest_discarded_ts = Some( + self.largest_discarded_ts + .map_or(record.ts, |largest| largest.max(record.ts)), + ); + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use wallet_session_core::{ + did::DidKey, + message::{Ciphertext, MessageType, Nonce}, + }; + + const TEST_CAPACITY: usize = 8; + + /// A distinct, valid message id for a test label. + fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) + } + + fn message_with_nonce(ts: u64, nonce: [u8; 24]) -> Message { + Message::new( + MessageType::Request, + DidKey::from_ed25519_bytes([1u8; 32]), + ts, + Nonce::new(nonce.to_vec()).expect("nonce"), + Ciphertext::new(vec![3, 4]), + ) + } + + fn message(ts: u64) -> Message { + message_with_nonce(ts, [2u8; 24]) + } + + fn nonce_with_counter(counter: u64) -> [u8; 24] { + let mut nonce = [7u8; 24]; + nonce[16..].copy_from_slice(&counter.to_be_bytes()); + nonce + } + + /// Classify and record, as the client does after delivering a message. + fn observe( + memory: &mut ReplayMemory, + id: &MessageId, + message: &Message, + now: u64, + ) -> Observation { + let observation = memory.classify(id, message, now); + if observation == Observation::New { + memory.record(id, message); + } + observation + } + + #[test] + fn ack_headroom_is_bounded() { + let mut memory = ReplayMemory::new(Duration::from_secs(300), 2); + let now = 1_000; + for counter in 0..(2 + ACK_HEADROOM) as u64 { + assert!(memory.has_ack_headroom(), "record {counter}"); + let message = message_with_nonce(now, nonce_with_counter(counter)); + memory.record(&message_id(&format!("ack-{counter}")), &message); + } + assert!( + !memory.has_ack_headroom(), + "the headroom past the capacity is fixed" + ); + } + + #[test] + fn classifies_retransmissions_and_conflicts() { + let mut memory = ReplayMemory::new(Duration::from_secs(300), TEST_CAPACITY); + let original = message(1_000); + + assert_eq!( + observe(&mut memory, &message_id("frame-1"), &original, 1_000), + Observation::New + ); + assert_eq!( + observe(&mut memory, &message_id("frame-1"), &original, 1_000), + Observation::Retransmission + ); + + let mut modified = original.clone(); + modified.data = Ciphertext::new(vec![9]); + assert_eq!( + observe(&mut memory, &message_id("frame-1"), &modified, 1_000), + Observation::Conflict + ); + + // The same nonce under a different frame id is also a conflict. + assert_eq!( + observe(&mut memory, &message_id("frame-2"), &original, 1_000), + Observation::Conflict + ); + } + + #[test] + fn accepts_unseen_nonces_regardless_of_counter_order() { + let mut memory = ReplayMemory::new(Duration::from_secs(300), TEST_CAPACITY); + let later = message_with_nonce(1_000, nonce_with_counter(1)); + let earlier = message_with_nonce(1_000, nonce_with_counter(0)); + + // A later counter is accepted first. An unseen earlier counter is not + // a replay of it; counters only have to be unique per key. + assert_eq!( + observe(&mut memory, &message_id("frame-later"), &later, 1_000), + Observation::New + ); + assert_eq!( + observe(&mut memory, &message_id("frame-earlier"), &earlier, 1_000), + Observation::New + ); + } + + #[test] + fn expires_after_the_envelope_window() { + let mut memory = ReplayMemory::new(Duration::from_secs(300), TEST_CAPACITY); + let original = message(1_000); + + assert_eq!( + observe(&mut memory, &message_id("frame-1"), &original, 1_000), + Observation::New + ); + assert_eq!( + observe(&mut memory, &message_id("frame-1"), &original, 1_300), + Observation::Retransmission + ); + + // Pruning at 1_301 discards the record and remembers its timestamp. + assert_eq!( + observe(&mut memory, &message_id("frame-1"), &original, 1_301), + Observation::New + ); + assert!(memory.is_stale(1_000)); + assert!(!memory.is_stale(1_001)); + } + + #[test] + fn rejects_new_records_when_full_until_expiry() { + let mut memory = ReplayMemory::new(Duration::from_secs(300), 2); + for counter in 0..2 { + let message = message_with_nonce(1_000, nonce_with_counter(counter)); + let id = message_id(&format!("frame-{counter}")); + assert_eq!(observe(&mut memory, &id, &message, 1_000), Observation::New); + } + + let third = message_with_nonce(1_000, nonce_with_counter(2)); + assert_eq!( + observe(&mut memory, &message_id("frame-2"), &third, 1_000), + Observation::Full + ); + assert_eq!(memory.by_id.len(), 2, "a full memory does not grow"); + + // Expired records free capacity for newer timestamps. + let fourth = message_with_nonce(1_001, nonce_with_counter(3)); + assert_eq!( + observe(&mut memory, &message_id("frame-3"), &fourth, 1_301), + Observation::New + ); + } + + #[test] + fn discarded_timestamp_outlives_the_record() { + let mut memory = ReplayMemory::new(Duration::from_secs(300), TEST_CAPACITY); + let original = message(1_000); + + observe(&mut memory, &message_id("frame-1"), &original, 1_000); + let mut later = message(1_001); + later.nonce = Nonce::new([3u8; 24]).expect("nonce"); + observe(&mut memory, &message_id("frame-2"), &later, 1_301); + + // The record is gone, but a copy replayed after a clock rollback is + // still rejected by the remembered discarded timestamp. + assert!(memory.is_stale(original.ts)); + } +} diff --git a/crates/client/src/session.rs b/crates/client/src/session.rs new file mode 100644 index 0000000..613484b --- /dev/null +++ b/crates/client/src/session.rs @@ -0,0 +1,100 @@ +use std::fmt; + +use wallet_session_core::{did::DidKey, message::Topic}; + +pub use wallet_session_core::connection::Role; + +/// Lifecycle state of a session. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SessionState { + /// Connected, waiting for `session_ready`. + Idle, + + /// Proposal sent, awaiting approval. + ProposalSent, + + /// Proposal received, awaiting a local decision. + ProposalReceived, + + /// Session established. + Active, + + /// Proposal rejected. + Rejected, + + /// Session torn down. + Disconnected, +} + +/// A single paired session. +/// +/// Its `Debug` output shows topics only by their log tag: a pairing topic is +/// a bearer secret, and anyone who learns it can take the free role on it. +#[derive(Clone)] +pub struct Session { + /// Topic used for the initial handshake. + pub pairing_topic: Topic, + + /// Topic currently carrying application traffic. + pub topic: Topic, + + /// Local role. + pub role: Role, + + /// `did:key` of the peer, once known. + /// + /// This is the `from` of the first envelope we accepted on the pairing + /// topic. Envelopes are not signed with the identity key, so it is only + /// the identity that a holder of the pairing key declared. Do not use it + /// to recognise a known wallet or application. + pub peer_did: Option, + + /// Current lifecycle state. + pub state: SessionState, +} + +impl fmt::Debug for Session { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("Session") + .field("pairing_topic", &self.pairing_topic.log_tag()) + .field("topic", &self.topic.log_tag()) + .field("role", &self.role) + .field("peer_did", &self.peer_did) + .field("state", &self.state) + .finish() + } +} + +impl Session { + /// Start a session on `topic` for the given role. + pub fn new(topic: Topic, role: Role) -> Self { + Self { + pairing_topic: topic.clone(), + topic, + role, + peer_did: None, + state: SessionState::Idle, + } + } + + /// Whether application messages may be exchanged. + pub fn is_active(&self) -> bool { + self.state == SessionState::Active + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn debug_does_not_show_topics() { + let session = Session::new(Topic::new([9u8; 32]).expect("topic"), Role::Responder); + let debug = format!("{session:?}"); + let topic = &session.pairing_topic; + for raw in [topic.to_string(), format!("{topic:?}")] { + assert!(!debug.contains(&raw), "{debug}"); + } + assert!(debug.contains("Responder"), "{debug}"); + } +} diff --git a/crates/client/src/tls.rs b/crates/client/src/tls.rs new file mode 100644 index 0000000..0e056da --- /dev/null +++ b/crates/client/src/tls.rs @@ -0,0 +1,31 @@ +//! TLS provider setup for `wss://` relay connections. +//! +//! `tokio-tungstenite` enables rustls without selecting a crypto provider. +//! Enabling the `ring` feature on our direct rustls dependency gives rustls +//! exactly one provider feature, and this module installs it before the first +//! connection. If the embedding application already installed a provider, that +//! choice is kept. + +use std::sync::Once; + +static INSTALL: Once = Once::new(); + +/// Install the default rustls provider once per process. +pub(crate) fn ensure_crypto_provider() { + INSTALL.call_once(|| { + // An application may have installed its own provider already; in that + // case rustls returns it as an error and we leave it in place. + let _ = rustls::crypto::ring::default_provider().install_default(); + }); +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn installs_a_process_default() { + ensure_crypto_provider(); + assert!(rustls::crypto::CryptoProvider::get_default().is_some()); + } +} diff --git a/crates/client/tests/e2e.rs b/crates/client/tests/e2e.rs new file mode 100644 index 0000000..baef818 --- /dev/null +++ b/crates/client/tests/e2e.rs @@ -0,0 +1,617 @@ +use std::{ + sync::Arc, + time::{Duration, SystemTime, UNIX_EPOCH}, +}; + +use futures_util::{SinkExt, StreamExt}; +use serde_json::json; +use tokio::net::{TcpListener, TcpStream}; +use tokio_tungstenite::{ + MaybeTlsStream, WebSocketStream, connect_async, tungstenite::Message as WsMessage, +}; +use wallet_session_client::{ + AckPayload, Client, ClientConfig, ClientError, ClientEvent, ClientMessage, IdentityKey, Opaque, + PairingKey, ProposalPayload, RequestPayload, Role, Seed, SessionState, XChaCha20Poly1305Cipher, + crypto::{Aad, SealedPayload}, + handshake::{EphemeralKeyPair, decode_public_key}, +}; +use wallet_session_core::{ + connection::ConnectionQuery, + crypto::MessageCipher, + did::DidKey, + frame::{RelayFrame, RelayFrameBody}, + message::{Ciphertext, Message as Envelope, MessageId, MessageType, Topic}, +}; +use wallet_session_relay::{ + config::NativeRelayTransportConfig, + limits::{Limiter, RelayLimitsConfig}, + registry::Registry, + server::serve, +}; + +const AUDIENCE: &str = "wss://relay.example.com"; + +type TestResult = Result<(), Box>; + +#[tokio::test] +async fn sealed_request_response() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run()).await??; + Ok(()) +} + +/// Request/response over the relay with real XChaCha20-Poly1305 encryption. +async fn run() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let key = pairing.as_bytes(); + + let proposer_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_registration_id("reg-1"); + let responder_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE); + + let mut proposer = Client::connect( + proposer_config, + IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])), + Role::Proposer, + topic.clone(), + XChaCha20Poly1305Cipher::new(key)?, + ) + .await?; + let mut responder = Client::connect( + responder_config, + IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])), + Role::Responder, + topic.clone(), + XChaCha20Poly1305Cipher::new(key)?, + ) + .await?; + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => { + let proposal: serde_json::Value = serde_json::from_slice(&payload.proposal.0)?; + assert_eq!(proposal, json!({ "capabilities": ["read"] })); + payload + } + other => panic!("expected proposal, got {other:?}"), + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + assert_ne!(proposer.session().topic, topic); + assert_ne!(responder.session().topic, topic); + assert_eq!(proposer.session().pairing_topic, topic); + assert_eq!(responder.session().pairing_topic, topic); + + assert!(matches!( + responder + .respond("invalid", Some(json!({})), Some(json!({}))) + .await, + Err(ClientError::ProtocolViolation(_)) + )); + assert!(matches!( + responder.respond("invalid", None, None).await, + Err(ClientError::ProtocolViolation(_)) + )); + + let request_id = proposer.request(json!({ "method": "get_status" })).await?; + match responder.recv().await? { + ClientMessage::Request(payload) => { + assert_eq!(payload.request_id, request_id); + let request: serde_json::Value = serde_json::from_slice(&payload.request.0)?; + assert_eq!(request, json!({ "method": "get_status" })); + } + other => panic!("expected request, got {other:?}"), + } + + responder + .respond(request_id.clone(), Some(json!({ "result": "ok" })), None) + .await?; + match proposer.recv().await? { + ClientMessage::Response(payload) => { + assert_eq!(payload.request_id, request_id); + let response = payload.response.expect("response body"); + let response: serde_json::Value = serde_json::from_slice(&response.0)?; + assert_eq!(response, json!({ "result": "ok" })); + } + other => panic!("expected response, got {other:?}"), + } + + // The proposer's request was acknowledged by the responder. + let mut delivered = Vec::new(); + while let Some(ClientEvent::Delivered { id }) = proposer.poll_event() { + delivered.push(id); + } + assert!( + delivered.iter().any(|id| id.to_string() == request_id), + "expected a Delivered event for {request_id}, got {delivered:?}" + ); + + // A second request has no response. `next_event` must process the inbound + // ack itself, without the application calling `recv`. + let second = proposer + .request(json!({ "method": "wait_for_ack" })) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, second), + other => panic!("expected the second request, got {other:?}"), + } + let event = tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await??; + assert!( + matches!(event, ClientEvent::Delivered { ref id } if id.to_string() == second), + "expected a Delivered event for {second}, got {event:?}" + ); + + // A local disconnect is terminal: later operations fail instead of hanging. + proposer.disconnect("done", 4000).await?; + match tokio::time::timeout(Duration::from_secs(2), responder.recv()).await?? { + ClientMessage::Disconnect(payload) => assert_eq!(payload.code, 4000), + other => panic!("expected disconnect, got {other:?}"), + } + assert_eq!(responder.session().state, SessionState::Disconnected); + // The disconnect is sent untracked, so closing reports no `Failed` for it. + let event = proposer.next_event().await; + assert!( + matches!(event, Err(ClientError::Closed)), + "unexpected event after disconnect: {event:?}" + ); + assert!(matches!(proposer.recv().await, Err(ClientError::Closed))); + assert!(matches!( + proposer + .request(json!({ "method": "after_disconnect" })) + .await, + Err(ClientError::Closed) + )); + + Ok(()) +} + +type RawStream = WebSocketStream>; + +fn unix_now() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock") + .as_secs() +} + +fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) +} + +async fn connect_raw( + relay_url: &str, + identity: &IdentityKey, + role: Role, + topic: &Topic, +) -> Result> { + let token = identity.connection_token("e2e-raw", AUDIENCE, Duration::from_secs(60))?; + let query = ConnectionQuery { + auth: token, + role, + topic: topic.clone(), + registration_id: None, + }; + let mut url = url::Url::parse(relay_url)?; + url.set_query(Some(&serde_urlencoded::to_string(&query)?)); + let (stream, _) = connect_async(url.as_str()).await?; + Ok(stream) +} + +async fn read_raw_frame(stream: &mut RawStream) -> Result> { + loop { + match stream.next().await { + Some(Ok(WsMessage::Text(text))) => return Ok(serde_json::from_str(&text)?), + Some(Ok(WsMessage::Ping(_) | WsMessage::Pong(_))) => continue, + Some(Ok(WsMessage::Close(frame))) => { + return Err(std::io::Error::other(format!( + "relay closed the connection: {frame:?}" + )) + .into()); + } + Some(Ok(_)) => continue, + Some(Err(error)) => return Err(error.into()), + None => return Err(std::io::Error::other("relay stream ended").into()), + } + } +} + +async fn wait_raw_session_ready(stream: &mut RawStream) -> Result<(), Box> { + loop { + let frame = read_raw_frame(stream).await?; + if matches!(frame.body, RelayFrameBody::SessionReady) { + return Ok(()); + } + } +} + +fn seal_message( + topic: &Topic, + from: DidKey, + id: MessageId, + message: &ClientMessage, + role: Role, + cipher: &mut XChaCha20Poly1305Cipher, +) -> Result> { + let ts = unix_now(); + let aad = Aad::new(&id, message.message_type(), topic, &from, ts, role).to_bytes(); + let plaintext = message.to_bytes()?; + let sealed = cipher.seal(&aad, &plaintext)?; + let wire = Envelope::new(message.message_type(), from, ts, sealed.nonce, sealed.data); + Ok(RelayFrame { + v: 1, + id, + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: serde_json::to_string(&wire)?, + }, + }) +} + +fn open_message( + frame: &RelayFrame, + cipher: &XChaCha20Poly1305Cipher, + receiver_role: Role, +) -> Result> { + let RelayFrameBody::Message { payload } = &frame.body else { + return Err("expected a message frame".into()); + }; + let wire: Envelope = serde_json::from_str(payload)?; + let aad = Aad::new( + &frame.id, + wire.kind, + &frame.topic, + &wire.from, + wire.ts, + receiver_role.counterpart(), + ) + .to_bytes(); + let bytes = cipher.open( + &aad, + &SealedPayload { + nonce: wire.nonce.clone(), + data: wire.data.clone(), + }, + )?; + Ok(ClientMessage::from_bytes(&bytes)?) +} + +fn tamper(frame: RelayFrame) -> Result> { + let mut frame = frame; + let RelayFrameBody::Message { payload } = &mut frame.body else { + return Err("expected a message frame".into()); + }; + let mut wire: Envelope = serde_json::from_str(payload)?; + let mut bytes = wire.data.as_bytes().to_vec(); + *bytes.first_mut().ok_or("empty ciphertext")? ^= 0x01; + wire.data = Ciphertext::new(bytes); + *payload = serde_json::to_string(&wire)?; + Ok(frame) +} + +/// Drive `recv` and the raw stream together, requiring neither a delivered +/// message nor a relay frame (such as an ack) before the timeout. +async fn expect_nothing( + client: &mut Client, + raw: &mut RawStream, + what: &str, +) { + let mut receiving = Box::pin(client.recv()); + let mut incoming = Box::pin(read_raw_frame(raw)); + tokio::select! { + result = &mut receiving => panic!("{what} was delivered: {result:?}"), + result = &mut incoming => panic!("{what} was answered: {result:?}"), + _ = tokio::time::sleep(Duration::from_millis(300)) => {} + } +} + +fn request(request_id: &str) -> ClientMessage { + ClientMessage::Request(RequestPayload { + request_id: request_id.to_owned(), + request: Opaque( + serde_json::to_vec(&json!({ "method": "get_status" })).expect("request JSON"), + ), + }) +} + +#[tokio::test] +async fn session_topic_requires_the_derived_key() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_session_key()).await??; + Ok(()) +} + +/// With a real cipher, the session topic must reject frames sealed with the +/// pairing key or with tampered session ciphertext, and accept a frame sealed +/// with the derived session key. +async fn run_session_key() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let key = pairing.as_bytes(); + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + XChaCha20Poly1305Cipher::new(key)?, + ) + .await?; + let mut pairing_stream = + connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing_stream).await?; + + let mut pairing_cipher = XChaCha20Poly1305Cipher::new(key)?; + let keypair = EphemeralKeyPair::generate(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let proposal_frame = seal_message( + &topic, + proposer_identity.did(), + message_id("proposal"), + &proposal, + Role::Proposer, + &mut pairing_cipher, + )?; + pairing_stream + .send(WsMessage::text(serde_json::to_string(&proposal_frame)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + let approve_frame = loop { + let frame = read_raw_frame(&mut pairing_stream).await?; + let RelayFrameBody::Message { payload } = &frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(payload)?; + if wire.kind == MessageType::Approve { + break frame; + } + }; + let approve = open_message(&approve_frame, &pairing_cipher, Role::Proposer)?; + let ClientMessage::Approve(approve) = approve else { + return Err("expected approve".into()); + }; + let client_public = decode_public_key(&approve.ephemeral_public_key)?; + let (session_key, session_topic) = keypair.derive(&client_public)?; + let session_topic = session_topic.as_topic().clone(); + + let ack = ClientMessage::Ack(AckPayload { + ack_id: approve_frame.id.clone(), + }); + let ack_frame = seal_message( + &topic, + proposer_identity.did(), + message_id("approve-ack"), + &ack, + Role::Proposer, + &mut pairing_cipher, + )?; + pairing_stream + .send(WsMessage::text(serde_json::to_string(&ack_frame)?)) + .await?; + match tokio::time::timeout(Duration::from_secs(2), responder.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id, approve_frame.id), + other => panic!("expected approve delivery, got {other:?}"), + } + + let mut session_cipher = XChaCha20Poly1305Cipher::new(session_key.as_bytes())?; + let mut session_stream = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session_stream).await?; + responder.wait_session_ready().await?; + + // Wrong key: the pairing cipher on the session topic. + let wrong_key = request("wrong-key"); + let wrong_frame = seal_message( + &session_topic, + proposer_identity.did(), + message_id("wrong-key"), + &wrong_key, + Role::Proposer, + &mut pairing_cipher, + )?; + session_stream + .send(WsMessage::text(serde_json::to_string(&wrong_frame)?)) + .await?; + assert!( + tokio::time::timeout(Duration::from_millis(300), responder.recv()) + .await + .is_err(), + "a frame sealed with the pairing key must not be delivered" + ); + assert!( + tokio::time::timeout( + Duration::from_millis(300), + read_raw_frame(&mut session_stream) + ) + .await + .is_err(), + "a frame sealed with the pairing key must not be acknowledged" + ); + + // Tampered session ciphertext. + let valid = request("valid-session"); + let valid_frame = seal_message( + &session_topic, + proposer_identity.did(), + message_id("valid-session"), + &valid, + Role::Proposer, + &mut session_cipher, + )?; + let tampered = tamper(valid_frame.clone())?; + session_stream + .send(WsMessage::text(serde_json::to_string(&tampered)?)) + .await?; + assert!( + tokio::time::timeout(Duration::from_millis(300), responder.recv()) + .await + .is_err(), + "a tampered session frame must not be delivered" + ); + assert!( + tokio::time::timeout( + Duration::from_millis(300), + read_raw_frame(&mut session_stream) + ) + .await + .is_err(), + "a tampered session frame must not be acknowledged" + ); + + // Valid session frame. + session_stream + .send(WsMessage::text(serde_json::to_string(&valid_frame)?)) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "valid-session"), + other => panic!("expected valid session request, got {other:?}"), + } + let ack_frame = read_raw_frame(&mut session_stream).await?; + match open_message(&ack_frame, &session_cipher, Role::Proposer)? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, valid_frame.id), + other => panic!("expected session ack, got {other:?}"), + } + + // Reflection: one of the responder's own requests, sent back to it. An + // accepted request would be delivered and acked, so silence shows it was + // refused. Besides carrying the responder's own `from`, the AAD binds its + // role, so the real cipher refuses it too. + responder.request(json!({ "method": "reflect_me" })).await?; + let own_request = read_raw_frame(&mut session_stream).await?; + match open_message(&own_request, &session_cipher, Role::Proposer)? { + ClientMessage::Request(_) => {} + other => panic!("expected the responder's request, got {other:?}"), + } + session_stream + .send(WsMessage::text(serde_json::to_string(&own_request)?)) + .await?; + expect_nothing(&mut responder, &mut session_stream, "a reflected envelope").await; + + // Role binding on its own: the peer's identity and the session key, but + // an AAD built for the responder's role. Only the role differs from a + // valid request, so only the AEAD can refuse it. + let wrong_role = seal_message( + &session_topic, + proposer_identity.did(), + message_id("wrong-role"), + &request("wrong-role"), + Role::Responder, + &mut session_cipher, + )?; + session_stream + .send(WsMessage::text(serde_json::to_string(&wrong_role)?)) + .await?; + expect_nothing(&mut responder, &mut session_stream, "a wrong-role envelope").await; + + // Kind mismatch: an authenticated envelope of kind `response` whose + // plaintext is a request. + let mismatched = { + let id = message_id("kind-mismatch"); + let ts = unix_now(); + let from = proposer_identity.did(); + let aad = Aad::new( + &id, + MessageType::Response, + &session_topic, + &from, + ts, + Role::Proposer, + ) + .to_bytes(); + let sealed = session_cipher.seal(&aad, &request("kind-mismatch").to_bytes()?)?; + let wire = Envelope::new(MessageType::Response, from, ts, sealed.nonce, sealed.data); + RelayFrame { + v: 1, + id, + topic: session_topic.clone(), + body: RelayFrameBody::Message { + payload: serde_json::to_string(&wire)?, + }, + } + }; + session_stream + .send(WsMessage::text(serde_json::to_string(&mismatched)?)) + .await?; + expect_nothing(&mut responder, &mut session_stream, "a kind mismatch").await; + + // Replay conflict: the id of an accepted frame with different content. + let conflict = seal_message( + &session_topic, + proposer_identity.did(), + valid_frame.id.clone(), + &request("conflicting"), + Role::Proposer, + &mut session_cipher, + )?; + session_stream + .send(WsMessage::text(serde_json::to_string(&conflict)?)) + .await?; + assert!(matches!( + tokio::time::timeout(Duration::from_secs(2), responder.recv()).await?, + Err(ClientError::ProtocolViolation(_)) + )); + + Ok(()) +} diff --git a/crates/client/tests/live_relay.rs b/crates/client/tests/live_relay.rs new file mode 100644 index 0000000..47c0523 --- /dev/null +++ b/crates/client/tests/live_relay.rs @@ -0,0 +1,679 @@ +//! Opt-in tests against an already-deployed relay. +//! +//! `cargo test` never touches the network: every test in this file is +//! `#[ignore]`. Run them explicitly: +//! +//! ```text +//! WALLET_SESSION_RELAY_URL=wss://relay.example.com/ \ +//! WALLET_SESSION_RELAY_AUDIENCE=wss://relay.example.com \ +//! cargo test -p wallet-session-client --test live_relay -- --ignored --nocapture +//! ``` +//! +//! `WALLET_SESSION_RELAY_AUDIENCE` defaults to the relay URL. Set it +//! explicitly when the relay's configured audience differs from the URL used +//! to reach it (for example when a proxy rewrites the host). +//! +//! The tests share one deployment, so they run one at a time. They use random +//! identities and topics, so repeated runs do not collide with each other. + +use std::time::{Duration, Instant}; + +use futures_util::StreamExt; +use serde_json::json; +use tokio::{net::TcpStream, sync::Mutex, time::timeout}; +use tokio_tungstenite::{ + MaybeTlsStream, WebSocketStream, connect_async, + tungstenite::{Message, protocol::frame::coding::CloseCode}, +}; +use url::Url; +use wallet_session_client::{ + Client, ClientConfig, ClientError, ClientEvent, ClientMessage, IdentityKey, PairingKey, Role, + Seed, SessionState, XChaCha20Poly1305Cipher, +}; +use wallet_session_core::{connection::ConnectionQuery, message::Topic}; + +/// Connection token lifetime used by the live tests. It is longer than +/// `TEST_TIMEOUT` but shorter than the relay's ten-minute default cap, so the +/// tests still fit deployments that lower the cap. +const TOKEN_TTL: Duration = Duration::from_secs(240); + +/// Upper bound for one live test, including connect, reconnect and routing. +const TEST_TIMEOUT: Duration = Duration::from_secs(120); + +/// Request/response pairs sent by the long-session test. +const LONG_SESSION_MESSAGES: usize = 50; + +/// Pacing between pairs. Each pair produces one request frame from the +/// proposer and two frames from the responder (ack + response), so this stays +/// below the relay's default per-connection inbound message rate. +const LONG_SESSION_INTERVAL: Duration = Duration::from_millis(150); + +/// The long session needs more time than a single round trip. +const LONG_SESSION_TIMEOUT: Duration = Duration::from_secs(120); + +/// Serialize live tests: a small deployment may have per-source admission +/// limits that a parallel test run would trip. +static LIVE_LOCK: Mutex<()> = Mutex::const_new(()); + +type TestResult = Result<(), Box>; +type LiveClient = Client; +type RawStream = WebSocketStream>; + +/// A deployed relay and the audience its tokens must carry. +struct LiveRelay { + url: String, + audience: String, +} + +impl LiveRelay { + fn from_env() -> Self { + // Show the test's own progress lines and client warnings. Debug logs + // are opt-in through RUST_LOG because the client's connect debug line + // contains the connection token. + let _ = env_logger::Builder::from_env( + env_logger::Env::default() + .default_filter_or("live_relay=info,wallet_session_client=warn"), + ) + .is_test(true) + .try_init(); + + // Raw `connect_async` calls below bypass `Client::connect`, which is + // where the library normally installs the rustls provider. + let _ = rustls::crypto::ring::default_provider().install_default(); + + let url = std::env::var("WALLET_SESSION_RELAY_URL").unwrap_or_else(|_| { + panic!( + "set WALLET_SESSION_RELAY_URL to the deployed relay, for example \ + wss://relay.example.com/ (live tests are ignored by default)" + ) + }); + let audience = + std::env::var("WALLET_SESSION_RELAY_AUDIENCE").unwrap_or_else(|_| url.clone()); + + eprintln!("live relay: url={url} audience={audience}"); + Self { url, audience } + } + + fn config(&self) -> ClientConfig { + ClientConfig::new(self.url.clone()) + .with_insecure_ws() + .with_audience(self.audience.clone()) + .with_token_ttl(TOKEN_TTL) + .with_idle_timeout(Duration::from_secs(30)) + .with_ack_base_delay(Duration::from_millis(250)) + .with_ack_max_attempts(8) + .with_ping_interval(Duration::from_secs(10)) + .with_pong_timeout(Duration::from_secs(10)) + .with_reconnect_initial_delay(Duration::from_millis(100)) + .with_reconnect_max_delay(Duration::from_millis(500)) + .with_reconnect_max_attempts(3) + } +} + +/// A connected proposer/responder pair plus the material needed to reconnect +/// the responder under the same identity. +struct Pair { + proposer: LiveClient, + responder: LiveClient, + topic: Topic, + key: [u8; 32], + responder_seed: Seed, +} + +async fn connect_pair(live: &LiveRelay) -> Result> { + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let key = *pairing.as_bytes(); + let responder_seed = Seed::random()?; + + let mut proposer = Client::connect( + live.config().with_registration_id("live-test"), + IdentityKey::random()?, + Role::Proposer, + topic.clone(), + XChaCha20Poly1305Cipher::new(&key)?, + ) + .await?; + let mut responder = Client::connect( + live.config(), + IdentityKey::from_seed(&responder_seed), + Role::Responder, + topic.clone(), + XChaCha20Poly1305Cipher::new(&key)?, + ) + .await?; + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + Ok(Pair { + proposer, + responder, + topic, + key, + responder_seed, + }) +} + +/// Complete the pairing handshake and wait for both session links. +async fn establish_session( + proposer: &mut LiveClient, + responder: &mut LiveClient, +) -> Result<(), Box> { + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => payload, + other => panic!("expected proposal, got {other:?}"), + }; + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + Ok(()) +} + +/// Build a handshake URL with the signed connection query. +fn url_with_query( + base: &str, + query: &ConnectionQuery, +) -> Result> { + let mut url = Url::parse(base)?; + url.set_query(Some(&serde_urlencoded::to_string(query)?)); + Ok(url.to_string()) +} + +/// Open a raw WebSocket connection, bypassing the client's reconnect logic so +/// handshake and close behavior can be asserted directly. +async fn connect_raw( + live: &LiveRelay, + identity: &IdentityKey, + role: Role, + topic: &Topic, +) -> Result> { + let token = identity.connection_token("live-test", &live.audience, TOKEN_TTL)?; + let query = ConnectionQuery { + auth: token, + role, + topic: topic.clone(), + registration_id: None, + }; + let url = url_with_query(&live.url, &query)?; + let (stream, response) = connect_async(url).await?; + + assert_eq!( + response.status().as_u16(), + 101, + "relay did not upgrade the WebSocket handshake" + ); + Ok(stream) +} + +#[tokio::test] +#[ignore = "requires a deployed relay; set WALLET_SESSION_RELAY_URL"] +async fn full_session_round_trip() -> TestResult { + let _guard = LIVE_LOCK.lock().await; + let live = LiveRelay::from_env(); + + timeout(TEST_TIMEOUT, async { + let Pair { + mut proposer, + mut responder, + .. + } = connect_pair(&live).await?; + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => { + let proposal: serde_json::Value = serde_json::from_slice(&payload.proposal.0)?; + assert_eq!(proposal, json!({ "capabilities": ["read"] })); + payload + } + other => panic!("expected proposal, got {other:?}"), + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + let request_id = proposer.request(json!({ "method": "get_status" })).await?; + match responder.recv().await? { + ClientMessage::Request(payload) => { + assert_eq!(payload.request_id, request_id); + let request: serde_json::Value = serde_json::from_slice(&payload.request.0)?; + assert_eq!(request, json!({ "method": "get_status" })); + } + other => panic!("expected request, got {other:?}"), + } + + responder + .respond(request_id.clone(), Some(json!({ "result": "ok" })), None) + .await?; + match proposer.recv().await? { + ClientMessage::Response(payload) => { + assert_eq!(payload.request_id, request_id); + assert_eq!(payload.error, None); + let response = payload.response.expect("response body"); + let response: serde_json::Value = serde_json::from_slice(&response.0)?; + assert_eq!(response, json!({ "result": "ok" })); + } + other => panic!("expected response, got {other:?}"), + } + + // The responder acknowledged the request before sending the response, + // so the delivery event is already queued when the response arrives. + let mut delivered = Vec::new(); + while let Some(event) = proposer.poll_event() { + if let ClientEvent::Delivered { id } = event { + delivered.push(id); + } + } + assert!( + delivered.iter().any(|id| id.to_string() == request_id), + "expected a Delivered event for {request_id}, got {delivered:?}" + ); + + Ok::<(), Box>(()) + }) + .await + .expect("live relay test timed out")?; + + Ok(()) +} + +#[tokio::test] +#[ignore = "requires a deployed relay; set WALLET_SESSION_RELAY_URL"] +async fn long_session_with_100_messages() -> TestResult { + let _guard = LIVE_LOCK.lock().await; + let live = LiveRelay::from_env(); + + timeout(LONG_SESSION_TIMEOUT, async { + let Pair { + mut proposer, + mut responder, + .. + } = connect_pair(&live).await?; + + eprintln!("long session: proposing"); + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => { + let proposal: serde_json::Value = serde_json::from_slice(&payload.proposal.0)?; + assert_eq!(proposal, json!({ "capabilities": ["read"] })); + eprintln!("long session: proposal received"); + payload + } + other => panic!("expected proposal, got {other:?}"), + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + eprintln!("long session: approved; starting {LONG_SESSION_MESSAGES} messages"); + + // A non-trivial payload also exercises the relay's byte accounting. + let payload = "x".repeat(512); + let started_at = Instant::now(); + let mut latencies = Vec::with_capacity(LONG_SESSION_MESSAGES); + + for seq in 1..=LONG_SESSION_MESSAGES { + let sent_at = Instant::now(); + let request_id = proposer + .request(json!({ + "seq": seq, + "method": "echo", + "data": payload.clone(), + })) + .await?; + eprintln!( + "[{seq:03}/{LONG_SESSION_MESSAGES}] proposer -> request id={request_id} bytes={}", + payload.len() + ); + + match responder.recv().await? { + ClientMessage::Request(message) => { + assert_eq!(message.request_id, request_id); + let request: serde_json::Value = serde_json::from_slice(&message.request.0)?; + assert_eq!(request["seq"].as_u64(), Some(seq as u64)); + assert_eq!(request["data"].as_str(), Some(payload.as_str())); + eprintln!( + "[{seq:03}/{LONG_SESSION_MESSAGES}] responder <- request id={}", + message.request_id + ); + } + other => panic!("expected request {seq}, got {other:?}"), + } + + responder + .respond( + request_id.clone(), + Some(json!({ + "seq": seq, + "ok": true, + "data": payload.clone(), + })), + None, + ) + .await?; + eprintln!("[{seq:03}/{LONG_SESSION_MESSAGES}] responder -> response id={request_id}"); + + match proposer.recv().await? { + ClientMessage::Response(message) => { + assert_eq!(message.request_id, request_id); + assert_eq!(message.error, None); + let response = message.response.expect("response body"); + let response: serde_json::Value = serde_json::from_slice(&response.0)?; + assert_eq!(response["seq"].as_u64(), Some(seq as u64)); + assert_eq!(response["ok"], json!(true)); + assert_eq!(response["data"].as_str(), Some(payload.as_str())); + } + other => panic!("expected response {seq}, got {other:?}"), + } + + let mut delivered = false; + while let Some(event) = proposer.poll_event() { + if let ClientEvent::Delivered { id } = event + && id.to_string() == request_id + { + delivered = true; + } + } + assert!( + delivered, + "no Delivered event for request {seq} ({request_id})" + ); + + let latency = sent_at.elapsed(); + latencies.push(latency); + eprintln!( + "[{seq:03}/{LONG_SESSION_MESSAGES}] proposer <- response id={request_id} \ + delivered=true rtt={latency:?} elapsed={:?}", + started_at.elapsed() + ); + + tokio::time::sleep(LONG_SESSION_INTERVAL).await; + } + + let total = started_at.elapsed(); + let sum: Duration = latencies.iter().sum(); + let average = sum / LONG_SESSION_MESSAGES as u32; + let minimum = latencies.iter().min().copied().unwrap_or_default(); + let maximum = latencies.iter().max().copied().unwrap_or_default(); + eprintln!( + "long session complete: messages={LONG_SESSION_MESSAGES} total={total:?} \ + avg_rtt={average:?} min_rtt={minimum:?} max_rtt={maximum:?}" + ); + + Ok::<(), Box>(()) + }) + .await + .expect("long live relay test timed out")?; + + Ok(()) +} + +#[tokio::test] +#[ignore = "requires a deployed relay; set WALLET_SESSION_RELAY_URL"] +async fn disconnect_is_delivered_and_acknowledged() -> TestResult { + let _guard = LIVE_LOCK.lock().await; + let live = LiveRelay::from_env(); + + timeout(TEST_TIMEOUT, async { + let Pair { + mut proposer, + mut responder, + .. + } = connect_pair(&live).await?; + establish_session(&mut proposer, &mut responder).await?; + + // Prove the session is active before tearing it down. + let request_id = proposer + .request(json!({ "method": "before_disconnect" })) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected request before disconnect, got {other:?}"), + } + responder + .respond(request_id.clone(), Some(json!({ "ok": true })), None) + .await?; + match proposer.recv().await? { + ClientMessage::Response(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected response before disconnect, got {other:?}"), + } + + // Drain delivery events from the request above; the only tracked + // message left after this point is the disconnect. + let mut request_delivered = false; + while let Some(event) = proposer.poll_event() { + if let ClientEvent::Delivered { id } = event + && id.to_string() == request_id + { + request_delivered = true; + } + } + assert!( + request_delivered, + "pre-disconnect request was not acknowledged" + ); + eprintln!("disconnect test: session active"); + + let proposer_reason = "user closed the pairing"; + let proposer_code = 4000; + proposer.disconnect(proposer_reason, proposer_code).await?; + assert_eq!(proposer.session().state, SessionState::Disconnected); + eprintln!( + "disconnect test: proposer -> disconnect reason={proposer_reason:?} \ + code={proposer_code}" + ); + + match responder.recv().await? { + ClientMessage::Disconnect(payload) => { + assert_eq!(payload.reason, proposer_reason); + assert_eq!(payload.code, proposer_code); + assert!( + payload.message.is_empty(), + "unexpected message: {:?}", + payload.message + ); + eprintln!( + "disconnect test: responder <- disconnect reason={:?} code={}", + payload.reason, payload.code + ); + } + other => panic!("expected disconnect from proposer, got {other:?}"), + } + + // Receiving the disconnect closed the responder, and the proposer + // closed as soon as it sent it. Neither side can send anything more, + // and the disconnect, which is sent untracked, produces no delivery + // outcome. + assert_eq!(responder.session().state, SessionState::Disconnected); + assert!(matches!(responder.recv().await, Err(ClientError::Closed))); + assert!(matches!( + responder + .disconnect("wallet closed the pairing", 4001) + .await, + Err(ClientError::Closed) + )); + assert!(matches!(proposer.recv().await, Err(ClientError::Closed))); + assert!( + proposer.poll_event().is_none(), + "a disconnect must not produce a delivery outcome" + ); + eprintln!("disconnect test: both sides closed"); + + Ok::<(), Box>(()) + }) + .await + .expect("disconnect live relay test timed out")?; + + Ok(()) +} + +#[tokio::test] +#[ignore = "requires a deployed relay; set WALLET_SESSION_RELAY_URL"] +async fn reconnect_resumes_buffered_frames() -> TestResult { + let _guard = LIVE_LOCK.lock().await; + let live = LiveRelay::from_env(); + + timeout(TEST_TIMEOUT, async { + let Pair { + mut proposer, + responder, + topic, + key, + responder_seed, + } = connect_pair(&live).await?; + + // Drop the responder without a disconnect message and give the relay + // time to reserve its slot before the proposer sends. + drop(responder); + tokio::time::sleep(Duration::from_millis(300)).await; + + // The proposal is buffered for the reserved responder slot. + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + // The same identity reconnects within the deployment's grace window. + let mut responder = Client::connect( + live.config(), + IdentityKey::from_seed(&responder_seed), + Role::Responder, + topic.clone(), + XChaCha20Poly1305Cipher::new(&key)?, + ) + .await?; + responder.wait_session_ready().await?; + + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => { + let proposal: serde_json::Value = serde_json::from_slice(&payload.proposal.0)?; + assert_eq!(proposal, json!({ "capabilities": ["read"] })); + payload + } + other => panic!("expected buffered proposal after reconnect, got {other:?}"), + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + let request_id = proposer.request(json!({ "method": "get_status" })).await?; + match responder.recv().await? { + ClientMessage::Request(payload) => { + assert_eq!(payload.request_id, request_id); + let request: serde_json::Value = serde_json::from_slice(&payload.request.0)?; + assert_eq!(request, json!({ "method": "get_status" })); + } + other => panic!("expected request after reconnect, got {other:?}"), + } + + responder + .respond(request_id.clone(), Some(json!({ "result": "ok" })), None) + .await?; + match proposer.recv().await? { + ClientMessage::Response(payload) => { + assert_eq!(payload.request_id, request_id); + let response = payload.response.expect("response body"); + let response: serde_json::Value = serde_json::from_slice(&response.0)?; + assert_eq!(response, json!({ "result": "ok" })); + } + other => panic!("expected response, got {other:?}"), + } + + Ok::<(), Box>(()) + }) + .await + .expect("live relay test timed out")?; + + Ok(()) +} + +#[tokio::test] +#[ignore = "requires a deployed relay; set WALLET_SESSION_RELAY_URL"] +async fn wrong_audience_is_rejected() -> TestResult { + let _guard = LIVE_LOCK.lock().await; + let live = LiveRelay::from_env(); + + timeout(TEST_TIMEOUT, async { + let identity = IdentityKey::random()?; + let topic = PairingKey::random()?.topic()?; + let token = + identity.connection_token("live-test", "wss://wrong-audience.invalid", TOKEN_TTL)?; + let query = ConnectionQuery { + auth: token, + role: Role::Proposer, + topic, + registration_id: None, + }; + let url = url_with_query(&live.url, &query)?; + + let error = connect_async(url) + .await + .expect_err("relay accepted a token minted for the wrong audience"); + match error { + tokio_tungstenite::tungstenite::Error::Http(response) => { + assert_eq!( + response.status().as_u16(), + 400, + "relay must answer a bad token with 400 Bad Request" + ); + } + other => panic!("expected HTTP 400 for a wrong-audience token, got {other:?}"), + } + + Ok::<(), Box>(()) + }) + .await + .expect("live relay test timed out")?; + + Ok(()) +} + +#[tokio::test] +#[ignore = "requires a deployed relay; set WALLET_SESSION_RELAY_URL"] +async fn role_slot_is_exclusive() -> TestResult { + let _guard = LIVE_LOCK.lock().await; + let live = LiveRelay::from_env(); + + timeout(TEST_TIMEOUT, async { + let topic = PairingKey::random()?.topic()?; + + // Occupy the proposer slot with one identity. + let _first = connect_raw(&live, &IdentityKey::random()?, Role::Proposer, &topic).await?; + tokio::time::sleep(Duration::from_millis(300)).await; + + // A different identity must not be able to take the same slot. + let mut second = + connect_raw(&live, &IdentityKey::random()?, Role::Proposer, &topic).await?; + let message = timeout(Duration::from_secs(5), second.next()) + .await + .expect("timed out waiting for the role rejection") + .expect("relay closed without a close frame")?; + + match message { + Message::Close(Some(frame)) => { + assert_eq!(frame.code, CloseCode::Policy); + assert_eq!(frame.reason.as_str(), "role already taken"); + } + other => panic!("expected a policy close for the taken role, got {other:?}"), + } + + Ok::<(), Box>(()) + }) + .await + .expect("live relay test timed out")?; + + Ok(()) +} diff --git a/crates/client/tests/plaintext.rs b/crates/client/tests/plaintext.rs new file mode 100644 index 0000000..b907d4c --- /dev/null +++ b/crates/client/tests/plaintext.rs @@ -0,0 +1,4647 @@ +use std::{ + sync::{ + Arc, + atomic::{AtomicU64, Ordering}, + }, + time::Duration, +}; + +use futures_util::{SinkExt, StreamExt}; +use serde_json::json; +use tokio::net::{TcpListener, TcpStream}; +use tokio_tungstenite::{ + MaybeTlsStream, WebSocketStream, connect_async, tungstenite::Message as WsMessage, +}; +use wallet_session_client::{ + AckPayload, ApprovePayload, Client, ClientConfig, ClientError, ClientEvent, ClientMessage, + DisconnectPayload, IdentityKey, Opaque, PairingKey, ProposalPayload, RejectPayload, + RequestPayload, ResponsePayload, Role, Seed, SessionState, + handshake::{EphemeralKeyPair, HandshakeError, decode_public_key}, +}; +use wallet_session_relay::{ + config::NativeRelayTransportConfig, + limits::{Limiter, RateLimit, RelayLimitsConfig}, + registry::Registry, + server::serve, +}; + +use wallet_session_client::crypto::{CipherError, NONCE_LEN, SENDER_PREFIX_LEN, SealedPayload}; +use wallet_session_core::{ + connection::ConnectionQuery, + crypto::MessageCipher, + did::DidKey, + frame::{RelayFrame, RelayFrameBody}, + message::{Ciphertext, Message as Envelope, MessageId, MessageType, Nonce, Topic}, +}; + +const AUDIENCE: &str = "wss://relay.example.com"; + +type TestResult = Result<(), Box>; + +/// Process-unique prefix so two test clients don't share a nonce space. +static PREFIX_SEQ: AtomicU64 = AtomicU64::new(0); + +/// Data the test cipher refuses to open, standing in for a bad AEAD tag. +const TAMPERED: &[u8] = b"plaintext-tampered"; + +/// Test-only passthrough cipher: no encryption, but a valid nonce sequence. +#[derive(Debug, Clone)] +pub struct PlaintextCipher { + prefix: [u8; SENDER_PREFIX_LEN], + counter: u64, + /// How many messages this cipher can seal before it fails. + seal_limit: u64, + /// Whether deriving a session cipher from this one fails. + for_key_fails: bool, +} + +impl PlaintextCipher { + /// Build a plaintext cipher with a fresh sender prefix. + pub fn new() -> Self { + let sequence = PREFIX_SEQ.fetch_add(1, Ordering::Relaxed); + let mut prefix = [0u8; SENDER_PREFIX_LEN]; + prefix[SENDER_PREFIX_LEN - 8..].copy_from_slice(&sequence.to_be_bytes()); + Self { + prefix, + counter: 0, + seal_limit: u64::MAX, + for_key_fails: false, + } + } + + /// A cipher that cannot produce a session cipher, as the real one cannot + /// when it gets no randomness for the new nonce prefix. + pub fn failing_for_key() -> Self { + Self { + for_key_fails: true, + ..Self::new() + } + } + + /// A cipher that fails every seal after the first `limit`, as the real + /// one does once its nonce counter is exhausted. + pub fn with_seal_limit(limit: u64) -> Self { + Self { + seal_limit: limit, + ..Self::new() + } + } + + fn nonce(&self) -> Nonce { + let mut nonce = [0u8; NONCE_LEN]; + nonce[..SENDER_PREFIX_LEN].copy_from_slice(&self.prefix); + nonce[SENDER_PREFIX_LEN..].copy_from_slice(&self.counter.to_be_bytes()); + Nonce::new(nonce.to_vec()).expect("nonce length") + } +} + +impl Default for PlaintextCipher { + fn default() -> Self { + Self::new() + } +} + +impl MessageCipher for PlaintextCipher { + type Sealed = SealedPayload; + type Error = CipherError; + + fn seal(&mut self, _aad: &[u8], plaintext: &[u8]) -> Result { + if self.counter >= self.seal_limit { + return Err(CipherError::CounterExhausted); + } + let nonce = self.nonce(); + self.counter = self.counter.wrapping_add(1); + Ok(SealedPayload { + nonce, + data: Ciphertext::new(plaintext.to_vec()), + }) + } + + fn open(&self, _aad: &[u8], sealed: &SealedPayload) -> Result, CipherError> { + if sealed.data.as_bytes() == TAMPERED { + return Err(CipherError::Decrypt); + } + Ok(sealed.data.as_bytes().to_vec()) + } + + fn for_key(&self, _key: &[u8; 32]) -> Result { + if self.for_key_fails { + return Err(CipherError::Encrypt); + } + Ok(Self::new()) + } +} + +#[tokio::test] +async fn plaintext_request_response() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run()).await??; + Ok(()) +} + +async fn run() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + + let proposer_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_registration_id("reg-1"); + let responder_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE); + + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + + let mut proposer = Client::connect( + proposer_config, + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut responder = Client::connect( + responder_config, + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + // Relay readiness is not session establishment. + assert_eq!(proposer.session().state, SessionState::Idle); + assert_eq!(responder.session().state, SessionState::Idle); + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => { + let proposal: serde_json::Value = serde_json::from_slice(&payload.proposal.0)?; + assert_eq!(proposal, json!({ "capabilities": ["read"] })); + payload + } + other => panic!("expected proposal, got {other:?}"), + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + assert_ne!(proposer.session().topic, topic); + assert_ne!(responder.session().topic, topic); + assert_eq!(proposer.session().pairing_topic, topic); + assert_eq!(responder.session().pairing_topic, topic); + + let request_id = proposer.request(json!({ "method": "get_status" })).await?; + match responder.recv().await? { + ClientMessage::Request(payload) => { + assert_eq!(payload.request_id, request_id); + let request: serde_json::Value = serde_json::from_slice(&payload.request.0)?; + assert_eq!(request, json!({ "method": "get_status" })); + } + other => panic!("expected request, got {other:?}"), + } + + responder + .respond(request_id.clone(), Some(json!({ "result": "ok" })), None) + .await?; + match proposer.recv().await? { + ClientMessage::Response(payload) => { + assert_eq!(payload.request_id, request_id); + assert_eq!(payload.error, None); + let response = payload.response.expect("response body"); + let response: serde_json::Value = serde_json::from_slice(&response.0)?; + assert_eq!(response, json!({ "result": "ok" })); + } + other => panic!("expected response, got {other:?}"), + } + + // Handshake kinds and manual acks are not accepted by generic `send`. + assert!(matches!( + proposer + .send(&ClientMessage::Ack(AckPayload { + ack_id: message_id("manual-ack") + })) + .await, + Err(ClientError::ProtocolViolation( + "acknowledgements are sent automatically" + )) + )); + assert!(matches!( + proposer + .send(&ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: "not-sent".to_owned(), + session_expiry: 0, + proposal: Opaque(Vec::new()), + })) + .await, + Err(ClientError::UnexpectedHandshake) + )); + assert!(matches!( + responder.propose(json!({ "not": "allowed" })).await, + Err(ClientError::ProtocolViolation( + "only the proposer may propose" + )) + )); + let proposal = ProposalPayload { + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + session_expiry: 0, + proposal: Opaque(Vec::new()), + }; + assert!(matches!( + proposer + .approve(&proposal, json!({ "not": "allowed" })) + .await, + Err(ClientError::ProtocolViolation( + "only the responder may approve" + )) + )); + + Ok(()) +} + +#[tokio::test] +async fn responder_reconnects_within_grace_and_resumes() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_reconnect()).await??; + Ok(()) +} + +/// The responder drops abruptly, the proposer keeps going (its proposal is +/// buffered), and the same identity reconnects within the grace window. The +/// buffered proposal is redelivered and the handshake then completes normally. +async fn run_reconnect() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_secs(5)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + + let proposer_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_registration_id("reg-1"); + let responder_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE); + let responder_seed = Seed::from_bytes([2u8; 32]); + + let mut proposer = Client::connect( + proposer_config, + IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])), + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut responder = Client::connect( + responder_config.clone(), + IdentityKey::from_seed(&responder_seed), + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + // The responder drops abruptly, without a disconnect message. + drop(responder); + // Let the relay observe the drop and reserve the responder's slot. The + // grace window is much longer than this, so a slow scheduler cannot push + // the reconnect below past it. + tokio::time::sleep(Duration::from_millis(300)).await; + + // Sent while the responder is away: the relay buffers it for redelivery. + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + // The same identity reconnects within the grace window. + let mut responder = Client::connect( + responder_config, + IdentityKey::from_seed(&responder_seed), + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + + responder.wait_session_ready().await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => { + let proposal: serde_json::Value = serde_json::from_slice(&payload.proposal.0)?; + assert_eq!(proposal, json!({ "capabilities": ["read"] })); + payload + } + other => panic!("expected buffered proposal after reconnect, got {other:?}"), + }; + + responder.approve(&shown, json!({ "ok": true })).await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + proposer.wait_session_ready().await?; + responder.wait_session_ready().await?; + + let request_id = proposer.request(json!({ "method": "get_status" })).await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected request after reconnect, got {other:?}"), + } + + responder + .respond(request_id.clone(), Some(json!({ "result": "ok" })), None) + .await?; + match proposer.recv().await? { + ClientMessage::Response(payload) => { + assert_eq!(payload.request_id, request_id); + let response = payload.response.expect("response body"); + let response: serde_json::Value = serde_json::from_slice(&response.0)?; + assert_eq!(response, json!({ "result": "ok" })); + } + other => panic!("expected response, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn survivor_is_notified_when_peer_does_not_reconnect() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_expiry()).await??; + Ok(()) +} + +/// The responder drops and does not reconnect, so after the grace window the +/// relay tells the survivor, whose `recv` fails with `PeerDisconnected`. +async fn run_expiry() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(200)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + + let proposer_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_registration_id("reg-1"); + let responder_config = ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE); + + let mut proposer = Client::connect( + proposer_config, + IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])), + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let responder = Client::connect( + responder_config, + IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])), + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + + proposer.wait_session_ready().await?; + + // The responder drops and never reconnects. + drop(responder); + + let outcome = proposer.recv().await; + assert!( + matches!(outcome, Err(ClientError::PeerDisconnected)), + "expected PeerDisconnected, got {outcome:?}" + ); + assert_eq!(proposer.session().state, SessionState::Disconnected); + assert!( + !proposer.is_ready(), + "peer disconnection must clear readiness" + ); + + Ok(()) +} + +#[tokio::test] +async fn peer_return_restores_tracked_sends() -> TestResult { + tokio::time::timeout(Duration::from_secs(15), run_peer_return()).await??; + Ok(()) +} + +/// A peer that returns after the grace window gets another `session_ready` +/// on the survivor's existing socket. Tracked sends must resume even though +/// the survivor never reconnected. +async fn run_peer_return() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(200)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + // The client under test is the survivor; a raw peer plays the wallet. + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let raw = establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + let session_topic = raw.topic.clone(); + let mut session_cipher = raw.cipher.clone(); + + // The wallet goes away without a local client reconnect. + drop(raw.session); + + let outcome = responder.recv().await; + assert!( + matches!(outcome, Err(ClientError::PeerDisconnected)), + "expected PeerDisconnected, got {outcome:?}" + ); + assert!(!responder.is_ready(), "peer loss must clear readiness"); + + // It returns on the same session topic; the relay sends a second + // `session_ready` on the survivor's existing socket. + let mut session = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + responder.wait_session_ready().await?; + + // A tracked send must now reach the wire without a local reconnect. + let request_id = responder + .request(json!({ "method": "after_peer_return" })) + .await?; + match read_raw_message(&mut session, &session_cipher).await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected request after peer return, got {other:?}"), + } + + let ack_id = request_id.parse::()?; + let ack = client_frame( + &session_topic, + proposer_identity.did(), + "peer-return-ack", + &ClientMessage::Ack(AckPayload { ack_id }), + &mut session_cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&ack)?)) + .await?; + match tokio::time::timeout(Duration::from_secs(2), responder.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id.to_string(), request_id), + other => panic!("expected delivery after peer return, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn peer_disconnect_survives_a_full_inbox() -> TestResult { + tokio::time::timeout( + Duration::from_secs(10), + run_peer_disconnect_full_inbox(false), + ) + .await??; + Ok(()) +} + +#[tokio::test] +async fn peer_disconnect_survives_the_peer_returning() -> TestResult { + tokio::time::timeout( + Duration::from_secs(10), + run_peer_disconnect_full_inbox(true), + ) + .await??; + Ok(()) +} + +/// `peer_disconnected` is sent once. If it arrives while the application is +/// not draining and the inbox is full, it must still be reported once the +/// application catches up, even if the peer has come back by then. +async fn run_peer_disconnect_full_inbox(peer_returns: bool) -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + // Filling the inbox takes more than the default per-connection burst. + let limiter = Arc::new(Limiter::new(RelayLimitsConfig { + inbound_message_rate: RateLimit { + burst: 10_000, + interval: Duration::from_secs(3600), + }, + ..RelayLimitsConfig::default() + })); + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + limiter, + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(50)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Overfill the inbox while the application is not driving the client, + // then leave for longer than the grace window. + for index in 0..80 { + let frame = request_frame( + &raw.topic, + proposer_identity.did(), + &format!("full-{index}"), + &format!("full-{index}"), + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + } + let session_topic = raw.topic.clone(); + drop(raw); + tokio::time::sleep(Duration::from_millis(300)).await; + let returned = if peer_returns { + let mut session = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + Some(session) + } else { + None + }; + + // Catch up. The requests that fit are delivered, then the disconnect. + let mut delivered = 0; + loop { + match tokio::time::timeout(Duration::from_secs(2), responder.recv()).await { + Ok(Ok(ClientMessage::Request(_))) => delivered += 1, + Ok(Err(ClientError::PeerDisconnected)) => break, + Ok(other) => panic!("unexpected result: {other:?}"), + Err(_) => panic!("peer_disconnected was lost"), + } + } + assert!( + delivered > 0, + "the requests that fit in the inbox must be delivered first" + ); + assert_eq!(responder.session().state, SessionState::Disconnected); + if let Some(mut session) = returned { + // Carry on with `recv` alone: the returned peer's message arrives, + // and the session says it is active again. + let mut cipher = PlaintextCipher::new(); + let frame = request_frame( + &session_topic, + proposer_identity.did(), + "returned", + "returned", + &mut cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + loop { + match tokio::time::timeout(Duration::from_secs(2), responder.recv()).await?? { + ClientMessage::Request(payload) if payload.request_id == "returned" => break, + ClientMessage::Request(_) => {} + other => panic!("unexpected message: {other:?}"), + } + } + assert!(responder.is_ready()); + assert!(responder.session().is_active()); + } else { + assert!(!responder.is_ready()); + } + + Ok(()) +} + +#[tokio::test] +async fn disconnect_is_accepted_when_the_queue_is_full() -> TestResult { + tokio::time::timeout(Duration::from_secs(20), run_disconnect_full_queue()).await??; + Ok(()) +} + +/// The sender of a `disconnect` closes straight away and never retransmits +/// it, so the receiver must act on it even when it has no room to queue +/// another message. +async fn run_disconnect_full_queue() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let limiter = Arc::new(Limiter::new(RelayLimitsConfig { + inbound_message_rate: RateLimit { + burst: 10_000, + interval: Duration::from_secs(3600), + }, + ..RelayLimitsConfig::default() + })); + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + limiter, + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Fill the pending queue while the application only drives `next_event`, + // one acknowledged request at a time. + for index in 0..256 { + let frame = request_frame( + &raw.topic, + proposer_identity.did(), + &format!("fill-{index}"), + &format!("fill-{index}"), + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + loop { + let mut event = Box::pin(responder.next_event()); + let incoming = Box::pin(read_raw_message(&mut raw.session, &raw.cipher)); + let message = tokio::select! { + event = &mut event => panic!("unexpected event: {event:?}"), + message = incoming => message?, + }; + if let ClientMessage::Ack(ack) = message { + assert_eq!(ack.ack_id, frame.id); + break; + } + } + } + + let disconnect = client_frame( + &raw.topic, + proposer_identity.did(), + "full-disconnect", + &ClientMessage::Disconnect(DisconnectPayload { + reason: "done".to_owned(), + code: 4000, + message: String::new(), + }), + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&disconnect)?)) + .await?; + let error = tokio::time::timeout(Duration::from_secs(2), async { + loop { + if let Err(error) = responder.next_event().await { + return error; + } + } + }) + .await + .expect("the disconnect must be acted on although the queue is full"); + assert!( + matches!(error, ClientError::Closed), + "unexpected error: {error:?}" + ); + + // The queued requests and then the disconnect are still handed over. + for _ in 0..256 { + assert!(matches!(responder.recv().await?, ClientMessage::Request(_))); + } + assert!(matches!( + responder.recv().await?, + ClientMessage::Disconnect(_) + )); + assert!(matches!(responder.recv().await, Err(ClientError::Closed))); + + Ok(()) +} + +/// Records the replay memory keeps before it refuses new envelopes. A +/// multiple of the batch size the test below fills it with. +const REPLAY_CAPACITY: usize = 8192; + +#[tokio::test] +async fn disconnect_is_accepted_when_the_replay_memory_is_full() -> TestResult { + tokio::time::timeout(Duration::from_secs(120), run_disconnect_full_replay()).await??; + Ok(()) +} + +/// Like a full pending queue, a full replay memory must not cost us a +/// `disconnect`, which its sender never retransmits. +async fn run_disconnect_full_replay() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + // Several megabytes go through the relay, so lift its rate limits. + let unlimited = RateLimit { + burst: u32::MAX, + interval: Duration::from_secs(1), + }; + let limiter = Arc::new(Limiter::new(RelayLimitsConfig { + inbound_message_rate: unlimited, + inbound_byte_rate: unlimited, + inbound_wire_byte_rate: unlimited, + identity_inbound_byte_rate: unlimited, + source_inbound_byte_rate: unlimited, + global_inbound_byte_rate: unlimited, + ..RelayLimitsConfig::default() + })); + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + limiter, + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Fill the session's replay memory, delivering and acknowledging every + // request so the pending queue stays empty. Send in batches small + // enough for the client's inbox and outbound queues, so none is dropped. + const BATCH: usize = 32; + for batch in 0..REPLAY_CAPACITY / BATCH { + let labels: Vec = (0..BATCH) + .map(|index| format!("fill-{}", batch * BATCH + index)) + .collect(); + for label in &labels { + let frame = request_frame( + &raw.topic, + proposer_identity.did(), + label, + label, + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + } + for label in &labels { + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(&payload.request_id, label), + other => panic!("expected request, got {other:?}"), + } + } + for label in &labels { + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(ack) => assert_eq!(ack.ack_id, message_id(label)), + other => panic!("expected ack, got {other:?}"), + } + } + } + + // The memory is full: a further request is neither delivered nor acked. + let overflow = request_frame( + &raw.topic, + proposer_identity.did(), + "overflow", + "overflow", + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&overflow)?)) + .await?; + expect_no_delivery_or_ack(&mut responder, &mut raw.session).await?; + + let disconnect = client_frame( + &raw.topic, + proposer_identity.did(), + "full-disconnect", + &ClientMessage::Disconnect(DisconnectPayload { + reason: "done".to_owned(), + code: 4000, + message: String::new(), + }), + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&disconnect)?)) + .await?; + let delivered = tokio::time::timeout(Duration::from_secs(2), responder.recv()) + .await + .expect("the disconnect must be acted on although the replay memory is full")?; + assert!( + matches!(delivered, ClientMessage::Disconnect(_)), + "unexpected message: {delivered:?}" + ); + assert!(matches!(responder.recv().await, Err(ClientError::Closed))); + + Ok(()) +} + +#[tokio::test] +async fn a_closed_pairing_link_does_not_close_the_session() -> TestResult { + tokio::time::timeout(Duration::from_secs(30), run_closed_pairing_link()).await??; + Ok(()) +} + +/// After establishment the pairing link is no longer the active one. If its +/// transport stops while a frame it received is still queued, failing to +/// acknowledge that frame must not be reported as the client closing. +async fn run_closed_pairing_link() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + // The relay tells the proposer about the responder's pairing link half a + // second after it closes, well after the responder's transport stopped. + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(500)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing_key = PairingKey::random()?; + let pairing_topic = pairing_key.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + // The relay closes a connection when its token expires, and with no + // reconnect attempts the transport then stops. A token lives at least + // five seconds and at most six here. + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_token_ttl(Duration::from_secs(6)) + .with_connect_timeout(Duration::from_secs(1)) + .with_connection_stability(Duration::from_secs(1)) + .with_reconnect_max_attempts(0), + responder_identity, + Role::Responder, + pairing_topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &pairing_topic, + ) + .await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + // Establish three seconds later, so the session link's token outlives + // the pairing link's by at least two seconds. + tokio::time::sleep(Duration::from_secs(3)).await; + + let keypair = EphemeralKeyPair::generate(); + let mut cipher = PlaintextCipher::new(); + let proposal = client_frame( + &pairing_topic, + proposer_identity.did(), + "raw-proposal", + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }), + &mut cipher, + )?; + let proposal = serde_json::to_string(&proposal)?; + pairing.send(WsMessage::text(proposal.clone())).await?; + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => payload, + other => return Err(format!("expected proposal, got {other:?}").into()), + }; + responder.approve(&shown, json!({ "test": true })).await?; + + // Leave the approve unacknowledged, so the pairing link stays up. + let (_, session_topic) = read_raw_approve(&mut pairing, &cipher, keypair).await?; + let mut session = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + + // Retransmit the proposal, then wait until the responder's pairing link + // has expired, all while the application is not driving the client. + pairing.send(WsMessage::text(proposal)).await?; + loop { + let frame = read_raw_frame(&mut pairing).await?; + if matches!(frame.body, RelayFrameBody::PeerDisconnected) { + break; + } + } + + let mut session_cipher = PlaintextCipher::new(); + let request = request_frame( + &session_topic, + proposer_identity.did(), + "after-pairing", + "after-pairing", + &mut session_cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&request)?)) + .await?; + + // The queued retransmission comes first, and its ack can no longer be + // sent. The session is unaffected. + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "after-pairing"), + other => panic!("expected request, got {other:?}"), + } + assert!(responder.is_ready()); + + Ok(()) +} + +#[tokio::test] +async fn a_message_queued_before_the_link_closes_is_delivered() -> TestResult { + tokio::time::timeout(Duration::from_secs(20), run_queued_before_close()).await??; + Ok(()) +} + +/// A message the transport received before it stopped is delivered, and +/// the client then reports why it closed. +async fn run_queued_before_close() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + // The relay tells the proposer about the responder's link half a second + // after it closes, well after the responder's transport stopped. + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(500)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing_key = PairingKey::random()?; + let pairing_topic = pairing_key.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + // The relay closes the connection when its token expires, within three + // seconds, and with no reconnect attempts the transport then stops. + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_token_ttl(Duration::from_secs(3)) + .with_connect_timeout(Duration::from_secs(1)) + .with_connection_stability(Duration::from_millis(500)) + .with_reconnect_max_attempts(0), + responder_identity, + Role::Responder, + pairing_topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &pairing_topic, + ) + .await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + // Send a proposal while the application is not driving the client, and + // wait until the responder's link has expired. + let keypair = EphemeralKeyPair::generate(); + let mut cipher = PlaintextCipher::new(); + let proposal = client_frame( + &pairing_topic, + proposer_identity.did(), + "queued-proposal", + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + loop { + let frame = read_raw_frame(&mut pairing).await?; + if matches!(frame.body, RelayFrameBody::PeerDisconnected) { + break; + } + } + + // The proposal's ack can no longer be sent, but the proposal itself is + // still handed over, and the error after it gives the real cause. + assert!(matches!( + responder.recv().await?, + ClientMessage::Proposal(_) + )); + let error = responder.recv().await.expect_err("the client has closed"); + assert!( + matches!(error, ClientError::Transport("token expired")), + "unexpected error: {error:?}" + ); + assert_eq!(responder.session().state, SessionState::Disconnected); + + Ok(()) +} + +#[tokio::test] +async fn stray_acks_do_not_fill_the_replay_memory() -> TestResult { + tokio::time::timeout(Duration::from_secs(120), run_stray_acks()).await??; + Ok(()) +} + +/// Acks that complete nothing must not use up the replay memory, or anyone +/// holding the key could get every later message dropped. +async fn run_stray_acks() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + // Several megabytes go through the relay, so lift its rate limits. + let unlimited = RateLimit { + burst: u32::MAX, + interval: Duration::from_secs(1), + }; + let limiter = Arc::new(Limiter::new(RelayLimitsConfig { + inbound_message_rate: unlimited, + inbound_byte_rate: unlimited, + inbound_wire_byte_rate: unlimited, + identity_inbound_byte_rate: unlimited, + source_inbound_byte_rate: unlimited, + global_inbound_byte_rate: unlimited, + ..RelayLimitsConfig::default() + })); + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + limiter, + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Send as many stray acks as the replay memory holds, in batches that + // each end with a request. Once the request is delivered and acked, the + // client has processed the whole batch. The batches fit in the client's + // inbox, so none is dropped. + const BATCH: usize = 32; + for batch in 0..REPLAY_CAPACITY / (BATCH - 1) + 1 { + for index in 0..BATCH - 1 { + let label = format!("stray-{}", batch * BATCH + index); + let ack = client_frame( + &raw.topic, + proposer_identity.did(), + &label, + &ClientMessage::Ack(AckPayload { + ack_id: message_id(&format!("made-up-{}", batch * BATCH + index)), + }), + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&ack)?)) + .await?; + } + let label = format!("req-{batch}"); + let request = request_frame( + &raw.topic, + proposer_identity.did(), + &label, + &label, + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&request)?)) + .await?; + let delivered = tokio::time::timeout(Duration::from_secs(2), responder.recv()) + .await + .expect("stray acks must not leave the request without room")?; + match delivered { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, label), + other => panic!("expected request, got {other:?}"), + } + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(ack) => assert_eq!(ack.ack_id, request.id), + other => panic!("expected ack, got {other:?}"), + } + } + + Ok(()) +} + +#[tokio::test] +async fn disconnect_inside_wait_session_ready_is_terminal() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_disconnect_while_waiting()).await??; + Ok(()) +} + +/// A frame processed inside `wait_session_ready` can close the client. The +/// next wait must then report the terminal error instead of carrying on. +async fn run_disconnect_while_waiting() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(50)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // The peer says goodbye and leaves. Nothing drives the client until the + // relay has also reported the peer gone, so the session is not ready and + // both frames wait in the inbox. + let disconnect = client_frame( + &raw.topic, + proposer_identity.did(), + "goodbye", + &ClientMessage::Disconnect(DisconnectPayload { + reason: "done".to_owned(), + code: 4000, + message: String::new(), + }), + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&disconnect)?)) + .await?; + drop(raw); + tokio::time::sleep(Duration::from_millis(300)).await; + assert!(!responder.is_ready()); + + // The disconnect closes the client inside the wait. Without a terminal + // check before the next wait, the queued `peer_disconnected` would be + // reported instead. + assert!(matches!( + responder.wait_session_ready().await, + Err(ClientError::Closed) + )); + assert!(matches!( + responder.recv().await?, + ClientMessage::Disconnect(_) + )); + assert!(matches!(responder.recv().await, Err(ClientError::Closed))); + + Ok(()) +} + +#[tokio::test] +async fn session_delete_reaches_the_peer_and_closes() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_session_delete()).await??; + Ok(()) +} + +async fn run_session_delete() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + responder.session_delete(7, "deleted").await?; + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::SessionDelete(payload) => { + assert_eq!(payload.code, 7); + assert_eq!(payload.message, "deleted"); + } + other => panic!("expected session_delete, got {other:?}"), + } + assert_eq!(responder.session().state, SessionState::Disconnected); + assert!(matches!(responder.recv().await, Err(ClientError::Closed))); + assert!(matches!( + responder.next_event().await, + Err(ClientError::Closed) + )); + + Ok(()) +} + +#[tokio::test] +async fn inbound_disconnect_is_terminal_and_acked() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_inbound_disconnect_terminal()).await??; + Ok(()) +} + +/// A peer's `disconnect` is acknowledged and delivered once, then every +/// later operation observes a terminal client. +async fn run_inbound_disconnect_terminal() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Leave a tracked send outstanding when the peer disconnects. + let request_id = responder + .request(json!({ "method": "pending_at_disconnect" })) + .await?; + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected pending request, got {other:?}"), + } + + let disconnect = ClientMessage::Disconnect(DisconnectPayload { + reason: "peer-bye".to_owned(), + code: 1000, + message: String::new(), + }); + let disconnect = client_frame( + &raw.topic, + proposer_identity.did(), + "peer-disconnect", + &disconnect, + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&disconnect)?)) + .await?; + + match responder.recv().await? { + ClientMessage::Disconnect(payload) => assert_eq!(payload.reason, "peer-bye"), + other => panic!("expected disconnect, got {other:?}"), + } + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, message_id("peer-disconnect")), + other => panic!("expected disconnect ack, got {other:?}"), + } + + // Closing reports the outstanding request before the terminal error. + match tokio::time::timeout(Duration::from_secs(2), responder.next_event()).await?? { + ClientEvent::Failed { id, .. } => assert_eq!(id.to_string(), request_id), + other => panic!("expected the pending request to fail, got {other:?}"), + } + assert!(matches!(responder.recv().await, Err(ClientError::Closed))); + assert!(matches!( + responder + .request(json!({ "method": "after_disconnect" })) + .await, + Err(ClientError::Closed) + )); + + Ok(()) +} + +type RawStream = WebSocketStream>; + +/// Connect to the relay as a raw peer, bypassing `Client`. +async fn connect_raw( + relay_url: &str, + identity: &IdentityKey, + role: Role, + topic: &Topic, +) -> Result> { + let token = identity.connection_token("raw-test", AUDIENCE, Duration::from_secs(60))?; + let query = ConnectionQuery { + auth: token, + role, + topic: topic.clone(), + registration_id: None, + }; + let mut url = url::Url::parse(relay_url)?; + url.set_query(Some(&serde_urlencoded::to_string(&query)?)); + let (stream, _) = connect_async(url.as_str()).await?; + Ok(stream) +} + +/// Read the next relay frame, ignoring WebSocket control frames. +async fn read_raw_frame(stream: &mut RawStream) -> Result> { + loop { + match stream.next().await { + Some(Ok(WsMessage::Text(text))) => return Ok(serde_json::from_str(&text)?), + Some(Ok(WsMessage::Ping(_) | WsMessage::Pong(_))) => continue, + Some(Ok(WsMessage::Close(frame))) => { + return Err(std::io::Error::other(format!( + "relay closed the connection: {frame:?}" + )) + .into()); + } + Some(Ok(_)) => continue, + Some(Err(error)) => return Err(error.into()), + None => return Err(std::io::Error::other("relay stream ended").into()), + } + } +} + +/// Read and decrypt the next application message from the raw peer. +async fn read_raw_message( + stream: &mut RawStream, + cipher: &PlaintextCipher, +) -> Result> { + let frame = read_raw_frame(stream).await?; + let RelayFrameBody::Message { payload } = frame.body else { + return Err(std::io::Error::other("expected a message frame").into()); + }; + let wire: Envelope = serde_json::from_str(&payload)?; + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + Ok(ClientMessage::from_bytes(&bytes)?) +} + +/// A distinct, valid message id for a test label. +fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) +} + +fn client_frame( + topic: &Topic, + from: DidKey, + id: &str, + message: &ClientMessage, + cipher: &mut PlaintextCipher, +) -> Result> { + let ts = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH)?; + let plaintext = message.to_bytes()?; + let sealed = cipher.seal(&[], &plaintext)?; + let wire = Envelope::new( + message.message_type(), + from, + ts.as_secs(), + sealed.nonce, + sealed.data, + ); + Ok(RelayFrame { + v: 1, + id: message_id(id), + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: serde_json::to_string(&wire)?, + }, + }) +} + +/// Build a frame carrying arbitrary envelope data, bypassing a real cipher. +fn envelope_frame( + topic: &Topic, + from: DidKey, + id: &str, + kind: MessageType, + nonce: [u8; 24], + data: &[u8], +) -> Result> { + let ts = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH)?; + let wire = Envelope::new( + kind, + from, + ts.as_secs(), + Nonce::new(nonce.to_vec())?, + Ciphertext::new(data.to_vec()), + ); + Ok(RelayFrame { + v: 1, + id: message_id(id), + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: serde_json::to_string(&wire)?, + }, + }) +} + +fn request_frame( + topic: &Topic, + from: DidKey, + id: &str, + request_id: &str, + cipher: &mut PlaintextCipher, +) -> Result> { + client_frame( + topic, + from, + id, + &ClientMessage::Request(RequestPayload { + request_id: request_id.to_owned(), + request: Opaque(serde_json::to_vec(&json!({ "method": "get_status" }))?), + }), + cipher, + ) +} + +/// Build one application frame of each kind that must never travel on the +/// pairing topic. +fn pairing_application_frames( + topic: &Topic, + from: DidKey, + label: &str, + cipher: &mut PlaintextCipher, +) -> Result, Box> { + Ok(vec![ + request_frame( + topic, + from.clone(), + &format!("{label}-request"), + label, + cipher, + )?, + client_frame( + topic, + from.clone(), + &format!("{label}-response"), + &ClientMessage::Response(ResponsePayload { + request_id: label.to_owned(), + response: Some(Opaque(serde_json::to_vec(&json!({ "ok": true }))?)), + error: None, + }), + cipher, + )?, + client_frame( + topic, + from, + &format!("{label}-disconnect"), + &ClientMessage::Disconnect(DisconnectPayload { + reason: "test".to_owned(), + code: 1000, + message: "application traffic on the pairing topic".to_owned(), + }), + cipher, + )?, + ]) +} + +/// Read frames until the relay sends `session_ready`. +async fn wait_raw_session_ready(stream: &mut RawStream) -> Result<(), Box> { + loop { + let frame = read_raw_frame(stream).await?; + if matches!(frame.body, RelayFrameBody::SessionReady) { + return Ok(()); + } + } +} + +/// A raw proposer connected to both the pairing and session topics. +struct RawSession { + pairing: RawStream, + pairing_topic: Topic, + pairing_cipher: PlaintextCipher, + approve: RelayFrame, + session: RawStream, + cipher: PlaintextCipher, + topic: Topic, +} + +/// Drive a `Client` responder through a handshake with a raw proposer, then +/// return a session-topic connection for the raw proposer. +async fn establish_raw_session( + relay_url: &str, + pairing_topic: &Topic, + responder: &mut Client, + proposer_identity: &IdentityKey, +) -> Result> { + let mut pairing = + connect_raw(relay_url, proposer_identity, Role::Proposer, pairing_topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let keypair = EphemeralKeyPair::generate(); + let mut cipher = PlaintextCipher::new(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let frame = client_frame( + pairing_topic, + proposer_identity.did(), + "raw-proposal", + &proposal, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + + let shown = match responder.recv().await? { + ClientMessage::Proposal(payload) => payload, + other => return Err(format!("expected proposal, got {other:?}").into()), + }; + + approve_raw_session( + relay_url, + pairing, + pairing_topic, + responder, + &shown, + proposer_identity, + keypair, + cipher, + ) + .await +} + +/// Complete the handshake for a raw proposer after its proposal was accepted. +#[allow(clippy::too_many_arguments)] +async fn approve_raw_session( + relay_url: &str, + mut pairing: RawStream, + pairing_topic: &Topic, + responder: &mut Client, + shown: &ProposalPayload, + proposer_identity: &IdentityKey, + keypair: EphemeralKeyPair, + mut cipher: PlaintextCipher, +) -> Result> { + let returned_id = responder.approve(shown, json!({ "test": true })).await?; + + let (approve_frame, session_topic) = read_raw_approve(&mut pairing, &cipher, keypair).await?; + let approve_id = approve_frame.id.clone(); + assert_eq!( + returned_id, approve_id, + "approve() returns the approve's frame id" + ); + + let ack = ClientMessage::Ack(AckPayload { + ack_id: approve_id.clone(), + }); + let ack_frame = client_frame( + pairing_topic, + proposer_identity.did(), + "raw-approve-ack", + &ack, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&ack_frame)?)) + .await?; + + // Wait until the responder has consumed the ack, which also retires the + // pairing link. Returning after session_ready alone races with that ack. + loop { + match responder.next_event().await? { + ClientEvent::Delivered { id } if id == approve_id => break, + ClientEvent::Failed { id, .. } if id == approve_id => { + return Err("approve was not acknowledged".into()); + } + _ => {} + } + } + + let mut session = + connect_raw(relay_url, proposer_identity, Role::Proposer, &session_topic).await?; + wait_raw_session_ready(&mut session).await?; + responder.wait_session_ready().await?; + + Ok(RawSession { + pairing, + pairing_topic: pairing_topic.clone(), + pairing_cipher: cipher, + approve: approve_frame, + session, + cipher: PlaintextCipher::new(), + topic: session_topic, + }) +} + +/// Read the responder's `approve` on the pairing topic and derive the session +/// topic from it, without acknowledging it. +async fn read_raw_approve( + pairing: &mut RawStream, + cipher: &PlaintextCipher, + keypair: EphemeralKeyPair, +) -> Result<(RelayFrame, Topic), Box> { + loop { + let frame = read_raw_frame(pairing).await?; + let RelayFrameBody::Message { payload } = &frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(payload)?; + if wire.kind != MessageType::Approve { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + let ClientMessage::Approve(approve) = ClientMessage::from_bytes(&bytes)? else { + return Err("expected approve payload".into()); + }; + let peer_public = decode_public_key(&approve.ephemeral_public_key)?; + let (_key, session_topic) = keypair.derive(&peer_public)?; + return Ok((frame, session_topic.as_topic().clone())); + } +} + +/// Drive `recv` and the raw stream together, requiring neither a delivered +/// message nor a relay frame (such as an ack) before the timeout. +async fn expect_no_delivery_or_ack( + responder: &mut Client, + raw: &mut RawStream, +) -> TestResult { + let mut receiving = Box::pin(responder.recv()); + let mut incoming = Box::pin(read_raw_frame(raw)); + tokio::select! { + result = &mut receiving => panic!("unexpected delivery: {result:?}"), + result = &mut incoming => panic!("unexpected relay frame: {result:?}"), + _ = tokio::time::sleep(Duration::from_millis(300)) => {} + } + Ok(()) +} + +#[tokio::test] +async fn pending_cap_covers_handshake_messages_and_still_acks() -> TestResult { + tokio::time::timeout( + Duration::from_secs(30), + run_pending_cap_handshake_messages(), + ) + .await??; + Ok(()) +} + +/// Every delivered kind shares the pending cap. Fill it with authenticated +/// handshake messages, then prove the overflowing message is not acknowledged +/// or queued while a later ack is still processed. +async fn run_pending_cap_handshake_messages() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + // The cap test needs more than the default per-connection message burst. + let limiter = Arc::new(Limiter::new(RelayLimitsConfig { + inbound_message_rate: RateLimit { + burst: 10_000, + interval: Duration::from_secs(3600), + }, + ..RelayLimitsConfig::default() + })); + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + limiter, + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_secs(60)), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + let proposal = |index: u32, cipher: &mut PlaintextCipher| { + client_frame( + &topic, + proposer_identity.did(), + &format!("proposal-{index}"), + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "index": index })).expect("json")), + }), + cipher, + ) + }; + let proposal_index = |message: ClientMessage| -> Option { + let ClientMessage::Proposal(payload) = message else { + return None; + }; + let value: serde_json::Value = serde_json::from_slice(&payload.proposal.0).ok()?; + value["index"].as_u64() + }; + + // Reject one proposal so the responder tracks an outbound message that a + // later ack can deliver. + let first = proposal(u32::MAX, &mut cipher)?; + pairing + .send(WsMessage::text(serde_json::to_string(&first)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + responder.reject(&shown, 1, "not now").await?; + let reject_id = loop { + let frame = read_raw_frame(&mut pairing).await?; + let RelayFrameBody::Message { payload } = &frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(payload)?; + if wire.kind == MessageType::Reject { + break frame.id; + } + }; + + // Fill the pending queue with proposals one round trip at a time, so + // every ack is observable and the outbox is not overwhelmed by a burst. + // Each proposal replaces the pending one, so all of them are accepted. + let mut first_queued = None; + for index in 0..256u32 { + let frame = proposal(index, &mut cipher)?; + let frame_id = frame.id.clone(); + first_queued.get_or_insert_with(|| frame.clone()); + pairing + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + + // Drive the client while waiting for the ack it sends for this frame. + // A retransmitted reject is not the ack we are waiting for. + let ack_id = loop { + let mut event = Box::pin(responder.next_event()); + let incoming = Box::pin(read_raw_frame(&mut pairing)); + let frame = tokio::select! { + event = &mut event => { + return Err( + format!("unexpected event while filling the cap: {event:?}").into(), + ); + } + frame = incoming => frame?, + }; + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind != MessageType::Ack { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + let ClientMessage::Ack(ack) = ClientMessage::from_bytes(&bytes)? else { + continue; + }; + break ack.ack_id; + }; + assert_eq!(ack_id, frame_id); + } + + // One more authenticated handshake message overflows the cap: it must be + // dropped before it is recorded or acknowledged. + let overflow = proposal(256, &mut cipher)?; + pairing + .send(WsMessage::text(serde_json::to_string(&overflow)?)) + .await?; + let overflow_wait = async { + loop { + let mut event = Box::pin(responder.next_event()); + let incoming = Box::pin(read_raw_frame(&mut pairing)); + let frame = tokio::select! { + event = &mut event => panic!("unexpected event: {event:?}"), + frame = incoming => frame?, + }; + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind != MessageType::Ack { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + let ClientMessage::Ack(_) = ClientMessage::from_bytes(&bytes)? else { + continue; + }; + return Ok::>(true); + } + }; + assert!( + tokio::time::timeout(Duration::from_millis(300), overflow_wait) + .await + .is_err(), + "overflowing handshake message must not be acknowledged" + ); + + // A retransmission of a message that is already queued is still + // acknowledged while the queue is full, so its sender does not give up on + // a message we hold. + let first_queued = first_queued.expect("filled the queue"); + pairing + .send(WsMessage::text(serde_json::to_string(&first_queued)?)) + .await?; + let reacked = async { + loop { + let mut event = Box::pin(responder.next_event()); + let incoming = Box::pin(read_raw_frame(&mut pairing)); + let frame = tokio::select! { + event = &mut event => panic!("unexpected event: {event:?}"), + frame = incoming => frame?, + }; + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind != MessageType::Ack { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + if let ClientMessage::Ack(ack) = ClientMessage::from_bytes(&bytes)? { + return Ok::>(ack.ack_id); + } + } + }; + let reacked = tokio::time::timeout(Duration::from_secs(2), reacked).await??; + assert_eq!(reacked, first_queued.id); + + // Acks are still processed while the pending queue is full. + let ack = ClientMessage::Ack(AckPayload { + ack_id: reject_id.clone(), + }); + let ack = client_frame( + &topic, + proposer_identity.did(), + "reject-ack", + &ack, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&ack)?)) + .await?; + match tokio::time::timeout(Duration::from_secs(2), responder.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id, reject_id), + other => panic!("expected delivery of the reject, got {other:?}"), + } + + // The queued handshake messages remain deliverable in order. + for index in 0..256u64 { + let message = responder.recv().await?; + assert_eq!(proposal_index(message), Some(index)); + } + + // The overflowing message was dropped rather than queued. + assert!( + tokio::time::timeout(Duration::from_millis(300), responder.recv()) + .await + .is_err(), + "the overflowing handshake message must not be queued" + ); + + // It was not recorded either: once there is room, the same frame is new. + pairing + .send(WsMessage::text(serde_json::to_string(&overflow)?)) + .await?; + assert_eq!(proposal_index(responder.recv().await?), Some(256)); + + Ok(()) +} + +#[tokio::test] +async fn retransmission_is_reacknowledged() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_retransmission()).await??; + Ok(()) +} + +/// An identical retransmission must not be delivered twice, but must be +/// acknowledged again. +async fn run_retransmission() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let RawSession { + mut session, + mut cipher, + topic: session_topic, + .. + } = establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + let request_id = "raw-request-1"; + let frame = request_frame( + &session_topic, + proposer_identity.did(), + "raw-frame-1", + request_id, + &mut cipher, + )?; + let text = serde_json::to_string(&frame)?; + + session.send(WsMessage::text(text.clone())).await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected request, got {other:?}"), + } + match read_raw_message(&mut session, &cipher).await? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, frame.id), + other => panic!("expected ack, got {other:?}"), + } + + // Retransmit the identical envelope. It must not reach the application + // again, but the responder must send a fresh ack. + session.send(WsMessage::text(text)).await?; + let receiving = tokio::spawn(async move { responder.recv().await }); + let ack = tokio::time::timeout( + Duration::from_secs(2), + read_raw_message(&mut session, &cipher), + ) + .await??; + match ack { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, frame.id), + other => panic!("expected re-ack, got {other:?}"), + } + assert!( + !receiving.is_finished(), + "the duplicate must not be delivered to the application again" + ); + receiving.abort(); + + Ok(()) +} + +#[tokio::test] +async fn pairing_topic_rejects_application_traffic() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_pairing_topic_guard()).await??; + Ok(()) +} + +/// Application traffic must not use the pairing key before or after the +/// handshake, and the session topic must keep working. +async fn run_pairing_topic_guard() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_secs(60)), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + + assert!(matches!( + responder.request(json!({ "method": "too_early" })).await, + Err(ClientError::SessionNotActive) + )); + + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Once the approve has been acknowledged, the pairing link is retired: + // even an otherwise valid handshake retransmission is no longer re-acked. + let _ = raw + .pairing + .send(WsMessage::text(serde_json::to_string(&raw.approve)?)) + .await; + let outcome = tokio::time::timeout(Duration::from_millis(300), async { + loop { + let frame = match read_raw_frame(&mut raw.pairing).await { + Ok(frame) => frame, + Err(_) => return Ok::<(), Box>(()), + }; + let RelayFrameBody::Message { payload } = &frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(payload)?; + if wire.kind == MessageType::Ack { + return Err(format!( + "the retired pairing link must not acknowledge handshake traffic, got {frame:?}" + ) + .into()); + } + } + }) + .await; + if let Ok(Err(error)) = outcome { + panic!("{error}"); + } + + // The pairing key still exists locally, but an application envelope on the + // pairing topic is rejected even though the session is established. + let pairing_request = request_frame( + &raw.pairing_topic, + proposer_identity.did(), + "pairing-app-frame", + "pairing-app-request", + &mut raw.pairing_cipher, + )?; + raw.pairing + .send(WsMessage::text(serde_json::to_string(&pairing_request)?)) + .await?; + expect_no_delivery_or_ack(&mut responder, &mut raw.session).await?; + + // The session topic remains usable. + let session_request = request_frame( + &raw.topic, + proposer_identity.did(), + "session-frame", + "session-request", + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&session_request)?)) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "session-request"), + other => panic!("expected session request, got {other:?}"), + } + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, message_id("session-frame")), + other => panic!("expected session ack, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn unexpected_approve_preserves_the_handshake() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_unexpected_approve()).await??; + Ok(()) +} + +/// A bad `approve` in the wrong handshake state must not discard the peer's +/// proposal, so the real approval can still complete. +async fn run_unexpected_approve() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut raw).await?; + + let mut cipher = PlaintextCipher::new(); + let keypair = EphemeralKeyPair::generate(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let proposal = client_frame( + &topic, + proposer_identity.did(), + "unexpected-proposal", + &proposal, + &mut cipher, + )?; + raw.send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + + let bad = ClientMessage::Approve(ApprovePayload { + proposal_id: message_id("unexpected-proposal"), + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let bad = client_frame( + &topic, + proposer_identity.did(), + "unexpected-approve", + &bad, + &mut cipher, + )?; + raw.send(WsMessage::text(serde_json::to_string(&bad)?)) + .await?; + assert!( + matches!( + responder.recv().await, + Err(ClientError::UnexpectedHandshake) + ), + "an approve in the wrong state must be rejected" + ); + + // The original PeerProposed state is still intact. + responder.approve(&shown, json!({ "ok": true })).await?; + + Ok(()) +} + +#[tokio::test] +async fn weak_proposal_is_rejected_without_acking() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_weak_proposal()).await??; + Ok(()) +} + +/// A proposal with a low-order public key must not be acknowledged or change +/// the handshake state. A later valid proposal still completes the handshake. +async fn run_weak_proposal() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + let weak = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: wallet_session_core::codec::encode(&[0u8; 32]), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "weak": true }))?), + }); + let weak = client_frame( + &topic, + proposer_identity.did(), + "weak-proposal", + &weak, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&weak)?)) + .await?; + + assert!(matches!( + responder.recv().await, + Err(ClientError::Handshake(HandshakeError::WeakKey)) + )); + assert_eq!(responder.session().state, SessionState::Idle); + + // The weak proposal must not be acknowledged. + match tokio::time::timeout(Duration::from_millis(300), read_raw_frame(&mut pairing)).await { + Err(_) => {} + Ok(Err(_)) => {} + Ok(Ok(frame)) => panic!("weak proposal must not be acknowledged: {frame:?}"), + } + + // A valid proposal still completes the handshake. + let keypair = EphemeralKeyPair::generate(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "valid": true }))?), + }); + let proposal = client_frame( + &topic, + proposer_identity.did(), + "valid-proposal", + &proposal, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + assert!(matches!( + read_raw_message(&mut pairing, &cipher).await?, + ClientMessage::Ack(_) + )); + + let mut raw = approve_raw_session( + &relay_url, + pairing, + &topic, + &mut responder, + &shown, + &proposer_identity, + keypair, + cipher, + ) + .await?; + + let request = request_frame( + &raw.topic, + proposer_identity.did(), + "weak-recovery-session", + "session", + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&request)?)) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "session"), + other => panic!("expected session request, got {other:?}"), + } + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(payload) => { + assert_eq!(payload.ack_id, message_id("weak-recovery-session")) + } + other => panic!("expected session ack, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn weak_approve_preserves_the_proposal() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_weak_approve()).await??; + Ok(()) +} + +/// A low-order `approve` must not be acknowledged or consume the proposal +/// keypair. A later valid approve still completes the handshake. +async fn run_weak_approve() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + let mut cipher = PlaintextCipher::new(); + let (proposal_id, proposer_public) = loop { + let frame = read_raw_frame(&mut pairing).await?; + let proposal_id = frame.id.clone(); + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind != MessageType::Proposal { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + let ClientMessage::Proposal(proposal) = ClientMessage::from_bytes(&bytes)? else { + return Err("expected proposal payload".into()); + }; + break ( + proposal_id, + decode_public_key(&proposal.ephemeral_public_key)?, + ); + }; + + let proposal_ack = ClientMessage::Ack(AckPayload { + ack_id: proposal_id.clone(), + }); + let proposal_ack = client_frame( + &topic, + responder_identity.did(), + "weak-approve-proposal-ack", + &proposal_ack, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal_ack)?)) + .await?; + match proposer.next_event().await? { + ClientEvent::Delivered { id } => assert_eq!(id, proposal_id), + other => panic!("expected the proposal acknowledgment, got {other:?}"), + } + + let weak = ClientMessage::Approve(ApprovePayload { + proposal_id: proposal_id.clone(), + ephemeral_public_key: wallet_session_core::codec::encode(&[0u8; 32]), + approval: Opaque(serde_json::to_vec(&json!({ "ok": false }))?), + }); + let weak = client_frame( + &topic, + responder_identity.did(), + "weak-approve", + &weak, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&weak)?)) + .await?; + + assert!(matches!( + proposer.recv().await, + Err(ClientError::Handshake(HandshakeError::WeakKey)) + )); + assert_eq!(proposer.session().state, SessionState::ProposalSent); + + // The weak approve must not be acknowledged. + match tokio::time::timeout(Duration::from_millis(300), read_raw_frame(&mut pairing)).await { + Err(_) => {} + Ok(Err(_)) => {} + Ok(Ok(frame)) => panic!("weak approve must not be acknowledged: {frame:?}"), + } + + // A valid approve still completes the handshake with the original keypair. + let responder_keypair = EphemeralKeyPair::generate(); + let approve = ClientMessage::Approve(ApprovePayload { + proposal_id: proposal_id.clone(), + ephemeral_public_key: responder_keypair.public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }); + let approve = client_frame( + &topic, + responder_identity.did(), + "valid-approve", + &approve, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&approve)?)) + .await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + assert!(matches!( + read_raw_message(&mut pairing, &cipher).await?, + ClientMessage::Ack(_) + )); + + let (_key, session_topic) = responder_keypair.derive(&proposer_public)?; + let session_topic = session_topic.as_topic().clone(); + let mut session = connect_raw( + &relay_url, + &responder_identity, + Role::Responder, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + proposer.wait_session_ready().await?; + + let request_id = proposer + .request(json!({ "method": "weak_approve_recovery" })) + .await?; + match read_raw_message(&mut session, &cipher).await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected session request, got {other:?}"), + } + let ack = ClientMessage::Ack(AckPayload { + ack_id: request_id.parse::()?, + }); + let ack = client_frame( + &session_topic, + responder_identity.did(), + "weak-approve-session-ack", + &ack, + &mut cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&ack)?)) + .await?; + match tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id.to_string(), request_id), + other => panic!("expected delivery after weak approve, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn approve_is_an_implicit_proposal_ack() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_implicit_proposal_ack()).await??; + Ok(()) +} + +/// A valid approve proves the peer received the proposal even when the +/// explicit proposal ack was lost. +async fn run_implicit_proposal_ack() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_millis(100)) + .with_ack_max_attempts(1), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + let mut cipher = PlaintextCipher::new(); + let (proposal_id, proposer_public) = loop { + let frame = read_raw_frame(&mut pairing).await?; + let proposal_id = frame.id.clone(); + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind != MessageType::Proposal { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + let ClientMessage::Proposal(proposal) = ClientMessage::from_bytes(&bytes)? else { + return Err("expected proposal payload".into()); + }; + break ( + proposal_id, + decode_public_key(&proposal.ephemeral_public_key)?, + ); + }; + + // Deliberately do not send the explicit proposal ack. + let responder_keypair = EphemeralKeyPair::generate(); + let approve = ClientMessage::Approve(ApprovePayload { + proposal_id: proposal_id.clone(), + ephemeral_public_key: responder_keypair.public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }); + let approve = client_frame( + &topic, + responder_identity.did(), + "implicit-approve", + &approve, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&approve)?)) + .await?; + + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + match tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id, proposal_id), + other => panic!("expected the proposal delivery, got {other:?}"), + } + + // No failure arrives after the retry window. + tokio::time::sleep(Duration::from_millis(300)).await; + assert!( + proposer.poll_event().is_none(), + "an approved proposal must not be reported failed" + ); + + let (_key, session_topic) = responder_keypair.derive(&proposer_public)?; + let session_topic = session_topic.as_topic().clone(); + let mut session = connect_raw( + &relay_url, + &responder_identity, + Role::Responder, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + proposer.wait_session_ready().await?; + + Ok(()) +} + +#[tokio::test] +async fn failed_proposal_returns_to_idle() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_failed_proposal()).await??; + Ok(()) +} + +/// An unacknowledged proposal returns the proposer to `Idle` so the +/// application can try again. +async fn run_failed_proposal() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_millis(10)) + .with_ack_max_attempts(1), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let _pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + match tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await?? { + ClientEvent::Failed { .. } => {} + other => panic!("expected the proposal failure, got {other:?}"), + } + assert_eq!(proposer.session().state, SessionState::Idle); + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + Ok(()) +} + +#[tokio::test] +async fn proposal_to_a_proposer_is_refused() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_proposal_to_proposer()).await??; + Ok(()) +} + +/// A proposal sent to a proposer must not change its handshake state, so it +/// can still make its own proposal afterwards. +async fn run_proposal_to_proposer() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + let proposal = client_frame( + &topic, + responder_identity.did(), + "backwards-proposal", + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + assert!(matches!( + proposer.recv().await, + Err(ClientError::UnexpectedHandshake) + )); + assert_eq!(proposer.session().state, SessionState::Idle); + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + assert_eq!(proposer.session().state, SessionState::ProposalSent); + + Ok(()) +} + +#[tokio::test] +async fn reject_ends_the_proposal_on_both_sides() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_reject_ends_proposal()).await??; + Ok(()) +} + +/// A received reject ends the proposer's outstanding proposal; a local +/// reject forgets the responder's pending one. +async fn run_reject_ends_proposal() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + let relay_url = format!("ws://{addr}"); + let config = || { + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + }; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + // Proposer side. + let topic = PairingKey::random()?.topic()?; + let mut proposer = Client::connect( + config(), + proposer_identity.clone(), + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let mut cipher = PlaintextCipher::new(); + + proposer.propose(json!({ "attempt": 1 })).await?; + let (proposal_id, _) = read_raw_proposal(&mut pairing, &cipher, None).await?; + let reject = client_frame( + &topic, + responder_identity.did(), + "reject", + &ClientMessage::Reject(RejectPayload { + proposal_id: proposal_id.clone(), + code: 1, + message: "no".into(), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&reject)?)) + .await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Reject(_))); + assert_eq!(proposer.session().state, SessionState::Rejected); + match tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id, proposal_id), + other => panic!("expected the reject to count as delivery, got {other:?}"), + } + + // A late approve for the rejected proposal establishes nothing. + let approve = client_frame( + &topic, + responder_identity.did(), + "late-approve", + &ClientMessage::Approve(ApprovePayload { + proposal_id, + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&approve)?)) + .await?; + assert!(matches!( + proposer.recv().await, + Err(ClientError::UnexpectedHandshake) + )); + assert_eq!(proposer.session().state, SessionState::Rejected); + proposer.propose(json!({ "attempt": 2 })).await?; + assert_eq!(proposer.session().state, SessionState::ProposalSent); + + // Responder side. + let topic = PairingKey::random()?.topic()?; + let mut responder = Client::connect( + config(), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let proposal = client_frame( + &topic, + proposer_identity.did(), + "proposal", + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + responder.reject(&shown, 1, "no").await?; + assert_eq!(responder.session().state, SessionState::Rejected); + assert!(matches!( + responder.approve(&shown, json!({ "ok": true })).await, + Err(ClientError::UnexpectedHandshake) + )); + + Ok(()) +} + +#[tokio::test] +async fn refused_envelope_does_not_pin_the_counterpart() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_refused_envelope_pin()).await??; + Ok(()) +} + +/// A pairing-key holder sends one proposal to a proposer under its own +/// identity. It is refused, so it must not become the counterpart and lock +/// the real responder out. +async fn run_refused_envelope_pin() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + let intruder_identity = IdentityKey::from_seed(&Seed::from_bytes([3u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let mut cipher = PlaintextCipher::new(); + + let proposal_id = proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + // The intruder's proposal authenticates but is refused. + let intrusion = client_frame( + &topic, + intruder_identity.did(), + "intruder-proposal", + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&intrusion)?)) + .await?; + assert!(matches!( + proposer.recv().await, + Err(ClientError::UnexpectedHandshake) + )); + assert!(proposer.session().peer_did.is_none()); + + // An ack for a made-up id completes nothing, so it must not pin the + // intruder either. The approve below is a processing barrier for it. + let stray_ack = client_frame( + &topic, + intruder_identity.did(), + "intruder-ack", + &ClientMessage::Ack(AckPayload { + ack_id: message_id("made-up"), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&stray_ack)?)) + .await?; + + // The real responder's approve still establishes the session. + let approve = client_frame( + &topic, + responder_identity.did(), + "real-approve", + &ClientMessage::Approve(ApprovePayload { + proposal_id, + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&approve)?)) + .await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + assert_eq!(proposer.session().state, SessionState::Active); + assert_eq!(proposer.session().peer_did, Some(responder_identity.did())); + + Ok(()) +} + +#[tokio::test] +async fn handshake_answers_are_delivered_when_their_ack_fails() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_answer_ack_fails()).await??; + Ok(()) +} + +/// An approve or a reject changes the handshake state when it is accepted. +/// The application must get it even if we then fail to acknowledge it. +async fn run_answer_ack_fails() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + let relay_url = format!("ws://{addr}"); + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + for approve in [true, false] { + let topic = PairingKey::random()?.topic()?; + // The proposer can seal its proposal, but not the ack that follows. + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + proposer_identity.clone(), + Role::Proposer, + topic.clone(), + PlaintextCipher::with_seal_limit(1), + ) + .await?; + let mut pairing = + connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let mut cipher = PlaintextCipher::new(); + + proposer.propose(json!({ "attempt": 1 })).await?; + let (proposal_id, _) = read_raw_proposal(&mut pairing, &cipher, None).await?; + let answer = if approve { + ClientMessage::Approve(ApprovePayload { + proposal_id, + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }) + } else { + ClientMessage::Reject(RejectPayload { + proposal_id, + code: 1, + message: "no".into(), + }) + }; + let answer = client_frame( + &topic, + responder_identity.did(), + "answer", + &answer, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&answer)?)) + .await?; + + let delivered = proposer.recv().await?; + if approve { + assert!(matches!(delivered, ClientMessage::Approve(_))); + assert_eq!(proposer.session().state, SessionState::Active); + } else { + assert!(matches!(delivered, ClientMessage::Reject(_))); + assert_eq!(proposer.session().state, SessionState::Rejected); + } + } + + Ok(()) +} + +#[tokio::test] +async fn proposer_can_propose_again_after_a_cipher_failure() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_cipher_failure()).await??; + Ok(()) +} + +/// The approve spends the proposal keypair. If the session cipher then +/// cannot be built, the proposal is over and the proposer must say so. +async fn run_cipher_failure() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + let relay_url = format!("ws://{addr}"); + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let topic = PairingKey::random()?.topic()?; + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::failing_for_key(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let mut cipher = PlaintextCipher::new(); + + let proposal_id = proposer.propose(json!({ "attempt": 1 })).await?; + read_raw_proposal(&mut pairing, &cipher, None).await?; + let approve = client_frame( + &topic, + responder_identity.did(), + "approve", + &ClientMessage::Approve(ApprovePayload { + proposal_id: proposal_id.clone(), + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&approve)?)) + .await?; + + let error = proposer.recv().await.expect_err("no session cipher"); + assert!( + matches!(error, ClientError::Cipher(_)), + "unexpected error: {error:?}" + ); + assert_eq!(proposer.session().state, SessionState::Idle); + match tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await?? { + ClientEvent::Delivered { id } => assert_eq!(id, proposal_id), + other => panic!("expected the proposal to be settled, got {other:?}"), + } + proposer.propose(json!({ "attempt": 2 })).await?; + assert_eq!(proposer.session().state, SessionState::ProposalSent); + + Ok(()) +} + +#[tokio::test] +async fn stale_approve_after_reproposal_is_rejected() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_stale_approve()).await??; + Ok(()) +} + +/// Read pairing frames until a proposal other than `skip` arrives, returning +/// its frame id and the proposer's public key. +async fn read_raw_proposal( + pairing: &mut RawStream, + cipher: &PlaintextCipher, + skip: Option<&MessageId>, +) -> Result<(MessageId, String), Box> { + loop { + let frame = read_raw_frame(pairing).await?; + if skip == Some(&frame.id) { + continue; + } + let RelayFrameBody::Message { payload } = &frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(payload)?; + if wire.kind != MessageType::Proposal { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + let ClientMessage::Proposal(proposal) = ClientMessage::from_bytes(&bytes)? else { + return Err("expected proposal payload".into()); + }; + return Ok((frame.id, proposal.ephemeral_public_key)); + } +} + +/// After a failed proposal the proposer proposes again with a new keypair. +/// An approve that answers the first proposal must not establish a session. +async fn run_stale_approve() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_millis(10)) + .with_ack_max_attempts(1), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let mut cipher = PlaintextCipher::new(); + + // The first proposal is read but never acknowledged. + let sent = proposer.propose(json!({ "attempt": 1 })).await?; + let (first_id, _) = read_raw_proposal(&mut pairing, &cipher, None).await?; + assert_eq!(sent, first_id, "propose() returns the proposal's frame id"); + match tokio::time::timeout(Duration::from_secs(2), proposer.next_event()).await?? { + ClientEvent::Failed { id, .. } => assert_eq!(id, first_id), + other => panic!("expected the proposal failure, got {other:?}"), + } + proposer.propose(json!({ "attempt": 2 })).await?; + let (second_id, _) = read_raw_proposal(&mut pairing, &cipher, Some(&first_id)).await?; + + // A reject of the first proposal arrives late. It must not end the second + // one. + let stale_reject = client_frame( + &topic, + responder_identity.did(), + "stale-reject", + &ClientMessage::Reject(RejectPayload { + proposal_id: first_id.clone(), + code: 1, + message: "no".into(), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&stale_reject)?)) + .await?; + assert!(matches!( + proposer.recv().await, + Err(ClientError::UnexpectedHandshake) + )); + assert_eq!(proposer.session().state, SessionState::ProposalSent); + + // An approve for the first proposal arrives late. + let stale = client_frame( + &topic, + responder_identity.did(), + "stale-approve", + &ClientMessage::Approve(ApprovePayload { + proposal_id: first_id, + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&stale)?)) + .await?; + assert!(matches!( + proposer.recv().await, + Err(ClientError::UnexpectedHandshake) + )); + assert_eq!(proposer.session().state, SessionState::ProposalSent); + + // The approve for the current proposal still establishes the session. + let current = client_frame( + &topic, + responder_identity.did(), + "current-approve", + &ClientMessage::Approve(ApprovePayload { + proposal_id: second_id, + ephemeral_public_key: EphemeralKeyPair::generate().public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(¤t)?)) + .await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + assert_eq!(proposer.session().state, SessionState::Active); + + Ok(()) +} + +#[tokio::test] +async fn newer_proposal_replaces_a_pending_one() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_newer_proposal()).await??; + Ok(()) +} + +/// Until it approves, a responder answers the newest proposal from its +/// counterpart. +async fn run_newer_proposal() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + let mut cipher = PlaintextCipher::new(); + + let mut propose = |label: &str, keypair: &EphemeralKeyPair| { + client_frame( + &topic, + proposer_identity.did(), + label, + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "label": label })).expect("json")), + }), + &mut cipher, + ) + }; + // The second proposal reuses the first one's key and only changes its + // terms, so comparing keys alone would not tell them apart. + let keypair = EphemeralKeyPair::generate(); + let first = propose("first-proposal", &keypair)?; + let second = propose("second-proposal", &keypair)?; + let second_id = second.id.clone(); + + let mut shown = Vec::new(); + for frame in [first, second] { + pairing + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + let ClientMessage::Proposal(proposal) = responder.recv().await? else { + panic!("expected a proposal"); + }; + shown.push(proposal); + } + + // The first proposal was replaced. Approving it must not approve the + // second one in its place. + assert!(matches!( + responder.approve(&shown[0], json!({ "ok": true })).await, + Err(ClientError::ProposalSuperseded) + )); + assert!(matches!( + responder.reject(&shown[0], 1, "no").await, + Err(ClientError::ProposalSuperseded) + )); + + responder.approve(&shown[1], json!({ "ok": true })).await?; + let (approve, _) = loop { + let frame = read_raw_frame(&mut pairing).await?; + let RelayFrameBody::Message { payload } = &frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(payload)?; + if wire.kind != MessageType::Approve { + continue; + } + let bytes = PlaintextCipher::new().open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + break (ClientMessage::from_bytes(&bytes)?, frame); + }; + let ClientMessage::Approve(approve) = approve else { + return Err("expected approve payload".into()); + }; + assert_eq!(approve.proposal_id, second_id); + + Ok(()) +} + +#[tokio::test] +async fn failed_approve_closes_an_unjoined_session() -> TestResult { + tokio::time::timeout( + Duration::from_secs(10), + run_failed_approve_session_timeout(true), + ) + .await??; + Ok(()) +} + +#[tokio::test] +async fn failed_approve_closes_without_consuming_events() -> TestResult { + tokio::time::timeout( + Duration::from_secs(10), + run_failed_approve_session_timeout(false), + ) + .await??; + Ok(()) +} + +/// When the approve is lost, the responder must not wait forever on a +/// session link the proposer never joins, whether or not the application +/// consumes the approve's `Failed` outcome. +async fn run_failed_approve_session_timeout(consume_events: bool) -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(100)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_millis(10)) + .with_ack_max_attempts(1) + .with_session_join_timeout(Duration::from_millis(100)), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + let keypair = EphemeralKeyPair::generate(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let proposal = client_frame( + &topic, + proposer_identity.did(), + "timeout-proposal", + &proposal, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + + // The approve is sent but never acknowledged. The proposer also never + // joins the session topic. + responder.approve(&shown, json!({ "ok": true })).await?; + + // The proposer never joins the session topic, so the join window ends the + // client and the call driving it reports why. + let error = if consume_events { + match tokio::time::timeout(Duration::from_secs(2), responder.next_event()).await?? { + ClientEvent::Failed { .. } => {} + other => panic!("expected the approve failure, got {other:?}"), + } + tokio::time::timeout(Duration::from_secs(2), async { + loop { + if let Err(error) = responder.next_event().await { + return error; + } + } + }) + .await? + } else { + // Without consuming the outcome the join window still runs: it was + // armed when the approve went out. + tokio::time::timeout(Duration::from_secs(5), responder.wait_session_ready()) + .await? + .expect_err("the session must not become ready") + }; + assert!( + matches!(error, ClientError::SessionNotEstablished), + "unexpected error: {error:?}" + ); + assert_eq!(responder.session().state, SessionState::Disconnected); + assert!(matches!( + responder.recv().await, + Err(ClientError::SessionNotEstablished) + )); + assert!(matches!( + responder.request(json!({ "method": "no_session" })).await, + Err(ClientError::SessionNotEstablished) + )); + // Ending the session afterwards must not replace the cause. + assert!(matches!( + responder.session_delete(1, "giving up").await, + Err(ClientError::SessionNotEstablished) + )); + assert!(matches!( + responder.recv().await, + Err(ClientError::SessionNotEstablished) + )); + + Ok(()) +} + +#[tokio::test] +async fn acked_approve_still_closes_an_unjoined_session() -> TestResult { + tokio::time::timeout(Duration::from_secs(20), run_acked_approve_unjoined()).await??; + Ok(()) +} + +/// Anyone holding the pairing key can acknowledge our approve. That must not +/// stop the join timeout: only the proposer joining the session topic does. +async fn run_acked_approve_unjoined() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_millis(10)) + .with_ack_max_attempts(1) + .with_session_join_timeout(Duration::from_millis(100)), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + let keypair = EphemeralKeyPair::generate(); + let proposal = client_frame( + &topic, + proposer_identity.did(), + "acked-proposal", + &ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + let approve_id = responder.approve(&shown, json!({ "ok": true })).await?; + + // Acknowledge the approve, but never join the session topic. + let (approve, _) = read_raw_approve(&mut pairing, &cipher, keypair).await?; + assert_eq!(approve.id, approve_id); + let ack = client_frame( + &topic, + proposer_identity.did(), + "acked-approve-ack", + &ClientMessage::Ack(AckPayload { ack_id: approve_id }), + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&ack)?)) + .await?; + + let error = tokio::time::timeout(Duration::from_secs(5), responder.wait_session_ready()) + .await + .expect("the join timeout must close the client") + .expect_err("the session must not become ready"); + assert!( + matches!(error, ClientError::SessionNotEstablished), + "unexpected error: {error:?}" + ); + + Ok(()) +} + +#[tokio::test] +async fn joined_session_survives_the_join_timeout() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_joined_session_timeout()).await??; + Ok(()) +} + +/// A failed `approve` only means its acks were lost. If the proposer did join +/// the session topic, the join timeout must not tear the session down, even +/// when the peer happens to be away when the timer fires. +async fn run_joined_session_timeout() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_millis(50)), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_ack_base_delay(Duration::from_millis(10)) + .with_ack_max_attempts(1) + .with_session_join_timeout(Duration::from_millis(200)), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + let keypair = EphemeralKeyPair::generate(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let proposal = client_frame( + &topic, + proposer_identity.did(), + "joined-proposal", + &proposal, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + + // The proposer reads the approve and joins the session topic, but never + // acknowledges the approve. + responder.approve(&shown, json!({ "ok": true })).await?; + let (_approve, session_topic) = read_raw_approve(&mut pairing, &cipher, keypair).await?; + let mut session = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + responder.wait_session_ready().await?; + match tokio::time::timeout(Duration::from_secs(2), responder.next_event()).await?? { + ClientEvent::Failed { .. } => {} + other => panic!("expected the approve failure, got {other:?}"), + } + + // The proposer goes away past its grace window and stays away while the + // join timeout fires. Only `PeerDisconnected` may be reported. + drop(session); + let driving = tokio::time::timeout(Duration::from_millis(500), async { + loop { + match responder.next_event().await { + Ok(_) | Err(ClientError::PeerDisconnected) => {} + Err(error) => return error, + } + } + }) + .await; + if let Ok(error) = driving { + panic!("the joined session was closed: {error:?}"); + } + + // The proposer returns and the session still carries traffic. + let mut session = connect_raw( + &relay_url, + &proposer_identity, + Role::Proposer, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + responder.wait_session_ready().await?; + let request_id = responder.request(json!({ "method": "still_here" })).await?; + match read_raw_message(&mut session, &PlaintextCipher::new()).await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, request_id), + other => panic!("expected the request, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn pairing_kind_guard_rejects_before_and_between_handshake() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_pairing_kind_guard_stages()).await??; + Ok(()) +} + +async fn run_pairing_kind_guard_stages() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing_key = PairingKey::random()?; + let topic = pairing_key.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &proposer_identity, Role::Proposer, &topic).await?; + responder.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + let mut cipher = PlaintextCipher::new(); + + // Before any handshake: the pairing key must not carry application traffic. + for frame in + pairing_application_frames(&topic, proposer_identity.did(), "guard-before", &mut cipher)? + { + pairing + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + } + expect_no_delivery_or_ack(&mut responder, &mut pairing).await?; + assert!(responder.session().peer_did.is_none()); + + let keypair = EphemeralKeyPair::generate(); + let proposal = ClientMessage::Proposal(ProposalPayload { + ephemeral_public_key: keypair.public_key_encoded(), + session_expiry: 0, + proposal: Opaque(serde_json::to_vec(&json!({ "test": true }))?), + }); + let proposal = client_frame( + &topic, + proposer_identity.did(), + "guard-proposal", + &proposal, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal)?)) + .await?; + let ClientMessage::Proposal(shown) = responder.recv().await? else { + panic!("expected a proposal"); + }; + assert!(matches!( + read_raw_message(&mut pairing, &cipher).await?, + ClientMessage::Ack(_) + )); + + // Between proposal and approve: still only handshake traffic is allowed. + for frame in pairing_application_frames( + &topic, + proposer_identity.did(), + "guard-between", + &mut cipher, + )? { + pairing + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + } + expect_no_delivery_or_ack(&mut responder, &mut pairing).await?; + + // The handshake and the session still work after the rejected frames. + let mut raw = approve_raw_session( + &relay_url, + pairing, + &topic, + &mut responder, + &shown, + &proposer_identity, + keypair, + cipher, + ) + .await?; + let request = request_frame( + &raw.topic, + proposer_identity.did(), + "guard-session", + "session", + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&request)?)) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "session"), + other => panic!("expected the session request, got {other:?}"), + } + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, message_id("guard-session")), + other => panic!("expected a session ack, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn pairing_kind_guard_rejects_during_proposer_retirement_window() -> TestResult { + tokio::time::timeout( + Duration::from_secs(10), + run_proposer_retirement_window_guard(), + ) + .await??; + Ok(()) +} + +async fn run_proposer_retirement_window_guard() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing_key = PairingKey::random()?; + let topic = pairing_key.topic()?; + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + + let mut proposer = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + proposer_identity, + Role::Proposer, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut pairing = connect_raw(&relay_url, &responder_identity, Role::Responder, &topic).await?; + proposer.wait_session_ready().await?; + wait_raw_session_ready(&mut pairing).await?; + + proposer + .propose(json!({ "capabilities": ["read"] })) + .await?; + + let mut cipher = PlaintextCipher::new(); + let (proposal_id, proposal) = loop { + let frame = read_raw_frame(&mut pairing).await?; + let proposal_id = frame.id.clone(); + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind != MessageType::Proposal { + continue; + } + let bytes = cipher.open( + &[], + &SealedPayload { + nonce: wire.nonce, + data: wire.data, + }, + )?; + break (proposal_id, ClientMessage::from_bytes(&bytes)?); + }; + let ClientMessage::Proposal(proposal) = proposal else { + return Err("expected proposal payload".into()); + }; + + // Acknowledge the proposal so its retry does not race the late request. + let proposal_ack = ClientMessage::Ack(AckPayload { + ack_id: proposal_id.clone(), + }); + let proposal_ack = client_frame( + &topic, + responder_identity.did(), + "guard-proposal-ack", + &proposal_ack, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&proposal_ack)?)) + .await?; + + let keypair = EphemeralKeyPair::generate(); + let approve = ClientMessage::Approve(ApprovePayload { + proposal_id: proposal_id.clone(), + ephemeral_public_key: keypair.public_key_encoded(), + approval: Opaque(serde_json::to_vec(&json!({ "ok": true }))?), + }); + let approve = client_frame( + &topic, + responder_identity.did(), + "guard-approve", + &approve, + &mut cipher, + )?; + pairing + .send(WsMessage::text(serde_json::to_string(&approve)?)) + .await?; + assert!(matches!(proposer.recv().await?, ClientMessage::Approve(_))); + + let peer_public = decode_public_key(&proposal.ephemeral_public_key)?; + let (_key, session_topic) = keypair.derive(&peer_public)?; + let session_topic = session_topic.as_topic().clone(); + + // Consume the proposer's ack for the approve. The proposer's pairing link + // is still inside its retirement window. + loop { + let frame = read_raw_frame(&mut pairing).await?; + let RelayFrameBody::Message { payload } = frame.body else { + continue; + }; + let wire: Envelope = serde_json::from_str(&payload)?; + if wire.kind == MessageType::Ack { + break; + } + } + + // The session is established, but the pairing link still exists. An + // application envelope must still be rejected by the kind/topic guard. + for frame in pairing_application_frames( + &topic, + responder_identity.did(), + "guard-retirement", + &mut cipher, + )? { + pairing + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + } + expect_no_delivery_or_ack(&mut proposer, &mut pairing).await?; + + // The session topic remains usable after the rejected pairing frame. + let mut session = connect_raw( + &relay_url, + &responder_identity, + Role::Responder, + &session_topic, + ) + .await?; + wait_raw_session_ready(&mut session).await?; + proposer.wait_session_ready().await?; + + let mut session_cipher = PlaintextCipher::new(); + let request = request_frame( + &session_topic, + responder_identity.did(), + "guard-session", + "session", + &mut session_cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&request)?)) + .await?; + match proposer.recv().await? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "session"), + other => panic!("expected the session request, got {other:?}"), + } + match read_raw_message(&mut session, &session_cipher).await? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, message_id("guard-session")), + other => panic!("expected a session ack, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn oversized_relay_frame_is_rejected() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_oversized_frame()).await??; + Ok(()) +} + +/// A relay that forwards a frame above the client's WebSocket limit must cause +/// a transport failure, not an application delivery. +async fn run_oversized_frame() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig { + inbound_byte_rate: RateLimit { + burst: 1024 * 1024, + interval: Duration::from_secs(1), + }, + ..RelayLimitsConfig::default() + })), + NativeRelayTransportConfig::new(AUDIENCE).with_max_incoming_frame_bytes(512 * 1024), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + // Two base64 layers (the opaque payload and the envelope ciphertext) put + // this above 256 KiB on the wire while staying inside the relay's default + // byte budget. + let request = ClientMessage::Request(RequestPayload { + request_id: "oversized".to_owned(), + request: Opaque(vec![0u8; 200 * 1024]), + }); + let frame = client_frame( + &raw.topic, + proposer_identity.did(), + "oversized-frame", + &request, + &mut raw.cipher, + )?; + let text = serde_json::to_string(&frame)?; + assert!(text.len() > 256 * 1024); + raw.session.send(WsMessage::text(text)).await?; + + if let Ok(Ok(message)) = + tokio::time::timeout(Duration::from_millis(500), responder.recv()).await + { + panic!("oversized frame was delivered: {message:?}"); + } + + Ok(()) +} + +#[tokio::test] +async fn recoverable_bad_frames_are_dropped() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_recoverable_bad_frames()).await??; + Ok(()) +} + +/// A malformed envelope, a failed AEAD open, and plaintext that is not a client +/// message must not end the receive loop. The next valid message is delivered. +async fn run_recoverable_bad_frames() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity, + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let mut raw = + establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + let malformed = RelayFrame { + v: 1, + id: message_id("malformed-envelope"), + topic: raw.topic.clone(), + body: RelayFrameBody::Message { + payload: "not json".to_owned(), + }, + }; + raw.session + .send(WsMessage::text(serde_json::to_string(&malformed)?)) + .await?; + + let bad_plaintext = envelope_frame( + &raw.topic, + proposer_identity.did(), + "bad-plaintext", + MessageType::Request, + [11u8; 24], + b"not a client message", + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&bad_plaintext)?)) + .await?; + + let bad_tag = envelope_frame( + &raw.topic, + proposer_identity.did(), + "bad-tag", + MessageType::Request, + [12u8; 24], + TAMPERED, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&bad_tag)?)) + .await?; + + let invalid_response = ClientMessage::Response(ResponsePayload { + request_id: "invalid".to_owned(), + response: Some(Opaque(Vec::new())), + error: Some(Opaque(Vec::new())), + }); + let invalid_response = client_frame( + &raw.topic, + proposer_identity.did(), + "invalid-response", + &invalid_response, + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&invalid_response)?)) + .await?; + + for (id, nonce, plaintext) in [ + ( + "null-error-response", + [13u8; 24], + r#"{"type":"response","requestId":"null-error","response":"AQID","error":null}"#, + ), + ( + "null-response-response", + [14u8; 24], + r#"{"type":"response","requestId":"null-response","response":null,"error":"BAU"}"#, + ), + ( + "empty-response", + [15u8; 24], + r#"{"type":"response","requestId":"empty"}"#, + ), + ] { + let frame = envelope_frame( + &raw.topic, + proposer_identity.did(), + id, + MessageType::Response, + nonce, + plaintext.as_bytes(), + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&frame)?)) + .await?; + } + + let valid = request_frame( + &raw.topic, + proposer_identity.did(), + "valid-after-bad", + "valid-request", + &mut raw.cipher, + )?; + raw.session + .send(WsMessage::text(serde_json::to_string(&valid)?)) + .await?; + + match tokio::time::timeout(Duration::from_secs(2), responder.recv()).await?? { + ClientMessage::Request(payload) => assert_eq!(payload.request_id, "valid-request"), + other => panic!("expected the valid request, got {other:?}"), + } + match read_raw_message(&mut raw.session, &raw.cipher).await? { + ClientMessage::Ack(payload) => assert_eq!(payload.ack_id, message_id("valid-after-bad")), + other => panic!("expected an ack for the valid request, got {other:?}"), + } + + Ok(()) +} + +#[tokio::test] +async fn own_and_foreign_identities_are_rejected() -> TestResult { + tokio::time::timeout(Duration::from_secs(10), run_identities()).await??; + Ok(()) +} + +/// Frames from the receiver's own identity, and from an identity other than +/// the established counterpart, must not be delivered or acknowledged. +async fn run_identities() -> TestResult { + let _ = env_logger::builder() + .is_test(true) + .parse_default_env() + .try_init(); + + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + tokio::spawn(serve( + listener, + Arc::new(Registry::new()), + Arc::new(Limiter::new(RelayLimitsConfig::default())), + NativeRelayTransportConfig::new(AUDIENCE), + )); + + let relay_url = format!("ws://{addr}"); + let pairing = PairingKey::random()?; + let topic = pairing.topic()?; + + let responder_identity = IdentityKey::from_seed(&Seed::from_bytes([2u8; 32])); + let proposer_identity = IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])); + let foreign_identity = IdentityKey::from_seed(&Seed::from_bytes([9u8; 32])); + + let mut responder = Client::connect( + ClientConfig::new(&relay_url) + .with_insecure_ws() + .with_audience(AUDIENCE), + responder_identity.clone(), + Role::Responder, + topic.clone(), + PlaintextCipher::new(), + ) + .await?; + let RawSession { + mut session, + mut cipher, + topic: session_topic, + .. + } = establish_raw_session(&relay_url, &topic, &mut responder, &proposer_identity).await?; + + assert_eq!(responder.session().peer_did, Some(proposer_identity.did())); + assert_eq!(responder.session().state, SessionState::Active); + + // The receiver's own identity is rejected. + let own = request_frame( + &session_topic, + responder_identity.did(), + "own-frame", + "own-request", + &mut cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&own)?)) + .await?; + expect_no_delivery_or_ack(&mut responder, &mut session).await?; + + // A different sender is rejected because the counterpart is pinned to the + // proposer that completed the handshake. + let foreign = request_frame( + &session_topic, + foreign_identity.did(), + "foreign-frame", + "foreign-request", + &mut cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&foreign)?)) + .await?; + expect_no_delivery_or_ack(&mut responder, &mut session).await?; + assert_eq!(responder.session().peer_did, Some(proposer_identity.did())); + + // A later frame from the counterpart proves the rejected frames were + // skipped rather than merely still queued. + let after = request_frame( + &session_topic, + proposer_identity.did(), + "after-foreign-frame", + "after-foreign-request", + &mut cipher, + )?; + session + .send(WsMessage::text(serde_json::to_string(&after)?)) + .await?; + match responder.recv().await? { + ClientMessage::Request(payload) => { + assert_eq!(payload.request_id, "after-foreign-request"); + } + other => panic!("expected the post-foreign request, got {other:?}"), + } + match read_raw_message(&mut session, &cipher).await? { + ClientMessage::Ack(payload) => { + assert_eq!(payload.ack_id, message_id("after-foreign-frame")); + } + other => panic!("expected ack for the post-foreign request, got {other:?}"), + } + + Ok(()) +} diff --git a/crates/client/tests/transport.rs b/crates/client/tests/transport.rs new file mode 100644 index 0000000..504b4dd --- /dev/null +++ b/crates/client/tests/transport.rs @@ -0,0 +1,1006 @@ +use std::{ + sync::{ + Arc, + atomic::{AtomicUsize, Ordering}, + }, + time::{Duration, Instant}, +}; + +use futures_util::{SinkExt, StreamExt}; +use serde_json::json; +use tokio::{ + net::{TcpListener, TcpStream}, + sync::oneshot, + time::timeout, +}; +use tokio_tungstenite::{ + accept_async, + tungstenite::{ + Bytes, Message, + protocol::{CloseFrame, frame::coding::CloseCode}, + }, +}; +use wallet_session_client::{ + Client, ClientConfig, ClientError, ClientEvent, ClientMessage, DisconnectPayload, IdentityKey, + Opaque, ResponsePayload, Role, Seed, SessionDeletePayload, XChaCha20Poly1305Cipher, +}; +use wallet_session_core::{ + frame::{RelayFrame, RelayFrameBody}, + message::{MessageId, Topic}, +}; + +const AUDIENCE: &str = "ws://test"; + +type TestResult = Result<(), Box>; +type TestClient = Client; + +fn config(addr: std::net::SocketAddr) -> ClientConfig { + ClientConfig::new(format!("ws://{addr}")) + .with_insecure_ws() + .with_audience(AUDIENCE) + .with_connect_timeout(Duration::from_secs(1)) + .with_write_timeout(Duration::from_secs(1)) + .with_close_timeout(Duration::from_secs(1)) + .with_ping_interval(Duration::from_secs(30)) + .with_pong_timeout(Duration::from_secs(5)) +} + +async fn connect( + _addr: std::net::SocketAddr, + config: ClientConfig, +) -> Result> { + Ok(Client::connect( + config, + IdentityKey::from_seed(&Seed::from_bytes([1u8; 32])), + Role::Proposer, + Topic::new([9u8; 32])?, + XChaCha20Poly1305Cipher::new(&[7u8; 32])?, + ) + .await?) +} + +async fn accept(listener: &TcpListener) -> std::io::Result { + let (stream, _) = listener.accept().await?; + Ok(stream) +} + +#[tokio::test] +async fn policy_close_is_terminal_and_surfaced() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + let _ = socket + .close(Some(CloseFrame { + code: CloseCode::Policy, + reason: "role already taken".into(), + })) + .await; + }); + } + }) + }; + + let mut client = connect(addr, config(addr)).await?; + let error = timeout(Duration::from_secs(2), client.recv()) + .await? + .expect_err("unexpected message"); + assert!( + matches!(error, ClientError::Transport("role already taken")), + "unexpected error: {error:?}" + ); + let again = timeout(Duration::from_millis(100), client.recv()) + .await? + .expect_err("the terminal state must not hang"); + assert!( + matches!(again, ClientError::Transport("role already taken")), + "unexpected repeated error: {again:?}" + ); + + // Wait past the 250ms default reconnect delay, so a retry scheduled + // alongside the terminal error would have happened. + tokio::time::sleep(Duration::from_millis(400)).await; + assert_eq!( + accepts.load(Ordering::Relaxed), + 1, + "a policy rejection must not reconnect" + ); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn token_expiry_reconnects_without_backoff() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + let accepted = accepts.fetch_add(1, Ordering::Relaxed) + 1; + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + if accepted == 1 { + let _ = socket + .close(Some(CloseFrame { + code: CloseCode::Policy, + reason: "token expired".into(), + })) + .await; + } else { + // Keep the reconnected socket open for the assertion. + let _ = socket.next().await; + } + }); + } + }) + }; + + let _client = connect( + addr, + config(addr).with_reconnect_initial_delay(Duration::from_secs(5)), + ) + .await?; + + let started = Instant::now(); + timeout(Duration::from_secs(1), async { + while accepts.load(Ordering::Relaxed) < 2 { + tokio::time::sleep(Duration::from_millis(10)).await; + } + }) + .await + .expect("token expiry did not reconnect immediately"); + assert!( + started.elapsed() < Duration::from_secs(1), + "token expiry must bypass the reconnect backoff" + ); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn stable_connections_reset_the_token_expiry_budget() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + // Start the stable-connection window only after the client + // is demonstrably running its connection loop. + while let Some(message) = socket.next().await { + if matches!(message, Ok(Message::Ping(_))) { + break; + } + } + tokio::time::sleep(Duration::from_millis(100)).await; + let _ = socket + .close(Some(CloseFrame { + code: CloseCode::Policy, + reason: "token expired".into(), + })) + .await; + }); + } + }) + }; + + let _client = connect( + addr, + config(addr) + .with_ping_interval(Duration::from_millis(10)) + .with_reconnect_max_attempts(1) + .with_connection_stability(Duration::from_millis(50)), + ) + .await?; + + timeout(Duration::from_secs(2), async { + while accepts.load(Ordering::Relaxed) < 4 { + tokio::time::sleep(Duration::from_millis(10)).await; + } + }) + .await + .expect("stable token-expiry reconnects must not exhaust the retry budget"); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn reconnect_attempts_are_exactly_bounded() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + let _ = socket + .close(Some(CloseFrame { + code: CloseCode::Policy, + reason: "token expired".into(), + })) + .await; + }); + } + }) + }; + + let mut client = connect(addr, config(addr).with_reconnect_max_attempts(2)).await?; + let error = timeout(Duration::from_secs(1), client.recv()) + .await? + .expect_err("unexpected message"); + assert!( + matches!(error, ClientError::Transport("token expired")), + "unexpected error: {error:?}" + ); + assert_eq!( + accepts.load(Ordering::Relaxed), + 3, + "one initial connection plus exactly two retries" + ); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn shutdown_sends_a_normal_close_frame() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let (connected_tx, connected_rx) = oneshot::channel(); + let (close_tx, close_rx) = oneshot::channel(); + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("websocket"); + socket + .send(Message::Ping(Bytes::new())) + .await + .expect("ping"); + let mut connected_tx = Some(connected_tx); + while let Some(Ok(message)) = socket.next().await { + match message { + Message::Pong(_) => { + if let Some(tx) = connected_tx.take() { + let _ = tx.send(()); + } + } + Message::Close(Some(frame)) => { + let _ = close_tx.send(frame); + return; + } + _ => {} + } + } + }); + + let client = connect(addr, config(addr)).await?; + timeout(Duration::from_secs(1), connected_rx).await??; + drop(client); + + let close = timeout(Duration::from_secs(1), close_rx).await??; + assert_eq!(close.code, CloseCode::Normal); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn sends_before_readiness_are_rejected() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("websocket"); + while socket.next().await.is_some() {} + }); + + let mut client = connect(addr, config(addr)).await?; + tokio::time::sleep(Duration::from_millis(50)).await; + + assert!( + matches!( + client.propose(json!({ "test": true })).await, + Err(ClientError::NotReady) + ), + "handshake sends require pairing readiness" + ); + assert!(matches!( + client.request(json!({ "method": "too_early" })).await, + Err(ClientError::SessionNotActive) + )); + + drop(client); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn inbox_stall_does_not_kill_the_transport() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let topic = Topic::new([9u8; 32])?; + let (closed_tx, closed_rx) = oneshot::channel::<()>(); + let server = { + let accepts = Arc::clone(&accepts); + let topic = topic.clone(); + let mut closed_tx = Some(closed_tx); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + let accepted = accepts.fetch_add(1, Ordering::Relaxed) + 1; + let topic = topic.clone(); + let closed = if accepted == 1 { + closed_tx.take() + } else { + None + }; + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + if accepted == 1 { + // Fill the client inbox faster than it is drained. + for index in 0..100u8 { + let frame = RelayFrame { + v: 1, + id: MessageId::from_bytes([index; MessageId::LEN]), + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: "not an envelope".to_owned(), + }, + }; + let text = serde_json::to_string(&frame).expect("json"); + if socket.send(Message::Text(text.into())).await.is_err() { + return; + } + } + // End the connection while the client inbox is full, + // so the lifecycle send has to wait. + let _ = socket.close(None).await; + if let Some(closed) = closed { + let _ = closed.send(()); + } + } else { + let frame = RelayFrame { + v: 1, + id: MessageId::from_bytes([u8::MAX; MessageId::LEN]), + topic, + body: RelayFrameBody::SessionReady, + }; + let text = serde_json::to_string(&frame).expect("json"); + let _ = socket.send(Message::Text(text.into())).await; + let _ = socket.next().await; + } + }); + } + }) + }; + + let mut client = connect( + addr, + config(addr) + .with_idle_timeout(Duration::from_millis(50)) + .with_reconnect_initial_delay(Duration::from_millis(10)), + ) + .await?; + + // Once the server has filled the inbox and closed the socket, the + // transport has to wait to report `Disconnected`. Wait well past twice the + // idle timeout, which is when the old code gave up and exited silently. + timeout(Duration::from_secs(2), closed_rx).await??; + tokio::time::sleep(Duration::from_millis(250)).await; + assert_eq!( + accepts.load(Ordering::Relaxed), + 1, + "the task should be stalled on a lifecycle send" + ); + + // Draining the backlog must let the task finish its lifecycle sends and + // reconnect instead of exiting silently. + timeout(Duration::from_secs(2), client.wait_session_ready()).await??; + assert!( + accepts.load(Ordering::Relaxed) >= 2, + "the transport must reconnect after the inbox drains" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn disconnect_closes_locally_when_not_ready() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("websocket"); + while socket.next().await.is_some() {} + }); + + let mut client = connect(addr, config(addr)).await?; + tokio::time::sleep(Duration::from_millis(50)).await; + + let result = client.disconnect("bye", 1000).await; + assert!( + matches!( + result, + Err(ClientError::SessionNotActive | ClientError::NotReady) + ), + "unexpected disconnect result: {result:?}" + ); + // Bounded, so a regression fails instead of hanging the suite. + assert!(matches!( + timeout(Duration::from_secs(2), client.recv()).await?, + Err(ClientError::Closed) + )); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn pings_are_answered_while_the_client_inbox_is_full() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let topic = Topic::new([9u8; 32])?; + let (pong_tx, pong_rx) = oneshot::channel(); + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("websocket"); + + // Fill the client inbox faster than it is drained. + for index in 0..100u8 { + let frame = RelayFrame { + v: 1, + id: MessageId::from_bytes([index; MessageId::LEN]), + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: "not an envelope".to_owned(), + }, + }; + let text = serde_json::to_string(&frame).expect("json"); + socket + .send(Message::Text(text.into())) + .await + .expect("frame"); + } + + socket + .send(Message::Ping(Bytes::new())) + .await + .expect("ping"); + let pong = timeout(Duration::from_secs(1), async { + while let Some(message) = socket.next().await { + if matches!(message, Ok(Message::Pong(_))) { + return true; + } + } + false + }) + .await + .unwrap_or(false); + let _ = pong_tx.send(pong); + std::future::pending::<()>().await; + }); + + let _client = connect(addr, config(addr)).await?; + let ponged = timeout(Duration::from_secs(2), pong_rx).await??; + assert!( + ponged, + "the transport must answer pings while the client inbox is full" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn liveness_timeouts_do_not_reset_the_reconnect_budget() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(_socket) = accept_async(stream).await else { + return; + }; + // Complete the upgrade, then stop reading so pings are + // never answered. This is a black-holed socket. + std::future::pending::<()>().await; + }); + } + }) + }; + + let mut client = connect( + addr, + config(addr) + .with_connection_stability(Duration::from_millis(10)) + .with_ping_interval(Duration::from_millis(100)) + .with_pong_timeout(Duration::from_millis(100)) + .with_reconnect_initial_delay(Duration::from_millis(10)) + .with_reconnect_max_attempts(1), + ) + .await?; + + let error = timeout(Duration::from_secs(3), client.recv()) + .await? + .expect_err("the client should become terminal"); + assert!( + matches!(error, ClientError::Transport("relay pong timed out")), + "unexpected error: {error:?}" + ); + assert_eq!( + accepts.load(Ordering::Relaxed), + 2, + "a liveness timeout must not reset the retry budget" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn a_stall_after_a_healthy_stretch_resets_the_budget() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + // Answer pings for well over the stability period, then + // stop reading, like a network that drops out. + let _ = timeout(Duration::from_millis(500), async { + while socket.next().await.is_some() {} + }) + .await; + std::future::pending::<()>().await; + }); + } + }) + }; + + let mut client = connect( + addr, + config(addr) + .with_connection_stability(Duration::from_millis(200)) + .with_ping_interval(Duration::from_millis(50)) + .with_pong_timeout(Duration::from_millis(100)) + .with_reconnect_initial_delay(Duration::from_millis(10)) + .with_reconnect_max_attempts(1), + ) + .await?; + + // With one attempt, a second outage would close the client unless the + // healthy stretch before each one resets the budget. + assert!( + timeout(Duration::from_secs(3), client.recv()) + .await + .is_err(), + "the client must keep reconnecting" + ); + assert!( + accepts.load(Ordering::Relaxed) >= 3, + "each healthy connection is followed by a reconnect" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn relay_pings_alone_do_not_reset_the_budget() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + // Keep sending our own pings, but never read, so the + // client's pings go unanswered. + loop { + if socket.send(Message::Ping(Bytes::new())).await.is_err() { + return; + } + tokio::time::sleep(Duration::from_millis(20)).await; + } + }); + } + }) + }; + + let mut client = connect( + addr, + config(addr) + .with_connection_stability(Duration::from_millis(100)) + .with_ping_interval(Duration::from_millis(50)) + .with_pong_timeout(Duration::from_millis(200)) + .with_reconnect_initial_delay(Duration::from_millis(10)) + .with_reconnect_max_attempts(1), + ) + .await?; + + let error = timeout(Duration::from_secs(3), client.recv()) + .await? + .expect_err("the client should become terminal"); + assert!( + matches!(error, ClientError::Transport("relay pong timed out")), + "unexpected error: {error:?}" + ); + assert_eq!( + accepts.load(Ordering::Relaxed), + 2, + "pings from the relay must not count as it answering ours" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn ready_then_stalled_connections_do_not_reset_the_budget() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + // Say the session is ready, then stop answering pings. + let frame = RelayFrame { + v: 1, + id: MessageId::from_bytes([u8::MAX; MessageId::LEN]), + topic: Topic::new([9u8; 32]).expect("topic"), + body: RelayFrameBody::SessionReady, + }; + let text = serde_json::to_string(&frame).expect("json"); + let _ = socket.send(Message::Text(text.into())).await; + std::future::pending::<()>().await; + }); + } + }) + }; + + let mut client = connect( + addr, + config(addr) + .with_ping_interval(Duration::from_millis(100)) + .with_pong_timeout(Duration::from_millis(100)) + .with_reconnect_initial_delay(Duration::from_millis(10)) + .with_reconnect_max_attempts(1), + ) + .await?; + + let error = timeout(Duration::from_secs(3), client.recv()) + .await? + .expect_err("the client should become terminal"); + assert!( + matches!(error, ClientError::Transport("relay pong timed out")), + "unexpected error: {error:?}" + ); + assert_eq!( + accepts.load(Ordering::Relaxed), + 2, + "a stalled connection must not reset the retry budget, even after session_ready" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn foreign_relay_frames_do_not_signal_readiness() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let (release, released) = oneshot::channel::<()>(); + let (processed, foreign_processed) = oneshot::channel::<()>(); + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("upgraded"); + let ready = |v: u8, topic: [u8; 32]| { + let frame = RelayFrame { + v, + id: MessageId::from_bytes([u8::MAX; MessageId::LEN]), + topic: Topic::new(topic).expect("topic"), + body: RelayFrameBody::SessionReady, + }; + Message::Text(serde_json::to_string(&frame).expect("json").into()) + }; + // Another topic, then an unknown version of ours. + socket.send(ready(1, [8u8; 32])).await.expect("sent"); + socket.send(ready(2, [9u8; 32])).await.expect("sent"); + // The client handles frames in order, so its pong to this ping means + // it has processed both frames above. + socket + .send(Message::Ping(Bytes::from_static(b"barrier"))) + .await + .expect("sent"); + while let Some(Ok(message)) = socket.next().await { + if matches!(&message, Message::Pong(payload) if payload.as_ref() == b"barrier") { + break; + } + } + let _ = processed.send(()); + let _ = released.await; + socket.send(ready(1, [9u8; 32])).await.expect("sent"); + std::future::pending::<()>().await; + }); + + let mut client = connect(addr, config(addr)).await?; + timeout(Duration::from_secs(2), foreign_processed).await??; + assert!( + !client.is_ready(), + "a foreign session_ready must not make the client ready" + ); + + release.send(()).expect("server waiting"); + timeout(Duration::from_secs(2), client.wait_session_ready()).await??; + assert!(client.is_ready()); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn send_refuses_messages_it_cannot_deliver() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("websocket"); + while socket.next().await.is_some() {} + }); + let mut client = connect(addr, config(addr)).await?; + + // A response the receiver would drop unacknowledged. + for (response, error) in [(None, None), (Some(vec![1]), Some(vec![2]))] { + let result = client + .send(&ClientMessage::Response(ResponsePayload { + request_id: "r".into(), + response: response.map(Opaque), + error: error.map(Opaque), + })) + .await; + assert!( + matches!(result, Err(ClientError::ProtocolViolation(_))), + "unexpected result: {result:?}" + ); + } + + // Ending the session must go through the methods that also close locally. + for message in [ + ClientMessage::Disconnect(DisconnectPayload { + reason: "bye".into(), + code: 1000, + message: String::new(), + }), + ClientMessage::SessionDelete(SessionDeletePayload { + code: 1000, + message: String::new(), + }), + ] { + let result = client.send(&message).await; + assert!( + matches!(result, Err(ClientError::ProtocolViolation(_))), + "unexpected result: {result:?}" + ); + } + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn ready_then_expired_connections_exhaust_the_budget() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let accepts = Arc::new(AtomicUsize::new(0)); + let server = { + let accepts = Arc::clone(&accepts); + tokio::spawn(async move { + loop { + let Ok(stream) = accept(&listener).await else { + return; + }; + accepts.fetch_add(1, Ordering::Relaxed); + tokio::spawn(async move { + let Ok(mut socket) = accept_async(stream).await else { + return; + }; + // Say the session is ready, then close at once as if the + // token had expired. + let frame = RelayFrame { + v: 1, + id: MessageId::from_bytes([u8::MAX; MessageId::LEN]), + topic: Topic::new([9u8; 32]).expect("topic"), + body: RelayFrameBody::SessionReady, + }; + let text = serde_json::to_string(&frame).expect("json"); + let _ = socket.send(Message::Text(text.into())).await; + let _ = socket + .close(Some(CloseFrame { + code: CloseCode::Policy, + reason: "token expired".into(), + })) + .await; + }); + } + }) + }; + + let mut client = connect(addr, config(addr).with_reconnect_max_attempts(2)).await?; + let error = timeout(Duration::from_secs(3), async { + loop { + if let Err(error) = client.recv().await { + return error; + } + } + }) + .await?; + assert!( + matches!(error, ClientError::Transport("token expired")), + "unexpected error: {error:?}" + ); + assert_eq!( + accepts.load(Ordering::Relaxed), + 3, + "session_ready on a connection that closes at once must not reset the budget" + ); + + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn connect_timeout_is_surfaced_and_stops() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let _stream = stream; + std::future::pending::<()>().await; + }); + + let mut client = connect( + addr, + config(addr) + .with_connect_timeout(Duration::from_millis(100)) + .with_reconnect_max_attempts(0), + ) + .await?; + let error = timeout(Duration::from_secs(2), client.recv()) + .await? + .expect_err("unexpected message"); + assert!( + matches!(error, ClientError::Transport("relay connect timed out")), + "unexpected error: {error:?}" + ); + server.abort(); + Ok(()) +} + +#[tokio::test] +async fn outcomes_come_before_the_error_that_closes_the_client() -> TestResult { + let listener = TcpListener::bind("127.0.0.1:0").await?; + let addr = listener.local_addr()?; + let server = tokio::spawn(async move { + let stream = accept(&listener).await.expect("accepted"); + let mut socket = accept_async(stream).await.expect("websocket"); + let frame = RelayFrame { + v: 1, + id: MessageId::from_bytes([u8::MAX; MessageId::LEN]), + topic: Topic::new([9u8; 32]).expect("topic"), + body: RelayFrameBody::SessionReady, + }; + let text = serde_json::to_string(&frame).expect("json"); + socket + .send(Message::Text(text.into())) + .await + .expect("ready"); + // Take the proposal without acknowledging it, then refuse the + // connection for good. + while let Some(Ok(message)) = socket.next().await { + if message.is_text() { + break; + } + } + let _ = socket + .close(Some(CloseFrame { + code: CloseCode::Policy, + reason: "role already taken".into(), + })) + .await; + }); + + let mut client = connect(addr, config(addr)).await?; + client.wait_session_ready().await?; + let proposal = client.propose(json!({ "test": true })).await?; + + let mut failed = false; + let error = timeout(Duration::from_secs(3), async { + loop { + match client.next_event().await { + Ok(ClientEvent::Failed { id, .. }) if id == proposal => failed = true, + Ok(_) => {} + Err(error) => return error, + } + } + }) + .await?; + assert!( + matches!(error, ClientError::Transport("role already taken")), + "unexpected error: {error:?}" + ); + assert!(failed, "the proposal's outcome must come before the error"); + + server.abort(); + Ok(()) +} diff --git a/crates/core/src/crypto.rs b/crates/core/src/crypto.rs index 588864e..09760bb 100644 --- a/crates/core/src/crypto.rs +++ b/crates/core/src/crypto.rs @@ -12,6 +12,11 @@ pub trait MessageCipher: Send { /// Decrypt a received sealed representation. fn open(&self, aad: &[u8], sealed: &Self::Sealed) -> Result, Self::Error>; - /// Switch to a new 32-byte symmetric key. - fn rekey(&mut self, key: &[u8; 32]); + /// Create a fresh cipher for a new 32-byte key. + /// + /// Implementations must start with fresh nonce state: the sender prefix + /// must be regenerated and the counter must start at zero. + fn for_key(&self, key: &[u8; 32]) -> Result + where + Self: Sized; } diff --git a/crates/core/src/frame.rs b/crates/core/src/frame.rs index 9577fd5..3404819 100644 --- a/crates/core/src/frame.rs +++ b/crates/core/src/frame.rs @@ -1,6 +1,6 @@ use serde::{Deserialize, Serialize}; -use crate::message::Topic; +use crate::message::{MessageId, Topic}; /// Plaintext control frame exchanged over the relay. #[derive(Debug, Clone, Serialize, Deserialize)] @@ -8,8 +8,8 @@ pub struct RelayFrame { /// Protocol version. pub v: u8, - /// 16 random bytes, base64url. - pub id: String, + /// Message id. + pub id: MessageId, /// Frame topic. pub topic: Topic, @@ -19,6 +19,11 @@ pub struct RelayFrame { pub body: RelayFrameBody, } +impl RelayFrame { + /// The only relay frame version this crate speaks. + pub const VERSION: u8 = 1; +} + /// The relay control/forward variants carried by a [`RelayFrame`]. #[derive(Debug, Clone, Serialize, Deserialize)] #[serde(tag = "type", rename_all = "snake_case")] diff --git a/crates/core/src/message.rs b/crates/core/src/message.rs index e460d26..d85ac33 100644 --- a/crates/core/src/message.rs +++ b/crates/core/src/message.rs @@ -42,6 +42,23 @@ impl Message { data, } } + + /// Cryptographic digest of all authenticated envelope fields. + pub fn digest(&self) -> [u8; 32] { + fn field(hasher: &mut Sha256, bytes: &[u8]) { + hasher.update((bytes.len() as u64).to_be_bytes()); + hasher.update(bytes); + } + + let mut hasher = Sha256::new(); + hasher.update([self.version]); + field(&mut hasher, self.kind.as_str().as_bytes()); + field(&mut hasher, &self.from.to_ed25519_bytes()); + field(&mut hasher, &self.ts.to_be_bytes()); + field(&mut hasher, self.nonce.as_bytes()); + field(&mut hasher, self.data.as_bytes()); + hasher.finalize().into() + } } /// Plaintext frame for the relay. @@ -51,8 +68,8 @@ pub struct ControlFrame { #[serde(rename = "v")] version: u8, - /// 16 random bytes, base64url. - id: String, + /// Message id. + id: MessageId, /// Message type. #[serde(rename = "type")] @@ -65,10 +82,10 @@ pub struct ControlFrame { impl ControlFrame { pub const VERSION: u8 = 1; - pub fn new(id: impl Into, type_: MessageType, topic: Topic) -> Self { + pub fn new(id: MessageId, type_: MessageType, topic: Topic) -> Self { Self { version: Self::VERSION, - id: id.into(), + id, type_, topic, } @@ -108,6 +125,26 @@ impl MessageType { MessageType::SessionReady => "session_ready", } } + + /// Whether this kind belongs to the pairing handshake. + pub fn is_handshake(&self) -> bool { + matches!( + self, + MessageType::Proposal | MessageType::Approve | MessageType::Reject + ) + } + + /// Whether this kind is application traffic carried on the session topic. + pub fn is_application(&self) -> bool { + matches!( + self, + MessageType::Request + | MessageType::Response + | MessageType::Ack + | MessageType::Disconnect + | MessageType::SessionDelete + ) + } } impl From<&Payload> for MessageType { @@ -134,6 +171,58 @@ impl From for MessageType { } } +/// 16-byte message id, base64url. +#[derive(Serialize, Debug, Clone, PartialEq, Eq, Hash)] +pub struct MessageId(#[serde(with = "crate::codec::base64url")] Vec); + +impl<'de> Deserialize<'de> for MessageId { + fn deserialize(deserializer: D) -> Result + where + D: serde::Deserializer<'de>, + { + let encoded = String::deserialize(deserializer)?; + encoded + .parse::() + .map_err(serde::de::Error::custom) + } +} + +impl MessageId { + /// Number of bytes in a message id. + pub const LEN: usize = 16; + + /// Build a message id from raw bytes, rejecting the wrong length. + pub fn new(bytes: impl Into>) -> Result { + let bytes = bytes.into(); + if bytes.len() != Self::LEN { + return Err(Error::InvalidLength { + expected: Self::LEN, + actual: bytes.len(), + }); + } + Ok(Self(bytes)) + } + + /// Build a message id from a full-length byte array. + pub fn from_bytes(bytes: [u8; Self::LEN]) -> Self { + Self(bytes.to_vec()) + } +} + +impl fmt::Display for MessageId { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&codec::encode(&self.0)) + } +} + +impl FromStr for MessageId { + type Err = Error; + + fn from_str(s: &str) -> Result { + Self::new(codec::decode(s)?) + } +} + /// 32-byte topic, base64url. #[derive(Serialize, Debug, Clone, PartialEq, Eq, Hash)] pub struct Topic(#[serde(with = "crate::codec::base64url")] Vec); @@ -303,6 +392,55 @@ impl FromStr for Ciphertext { mod tests { use super::*; + #[test] + fn message_id_accepts_16_bytes() { + assert!(MessageId::new([0u8; 16]).is_ok()); + } + + #[test] + fn message_id_rejects_wrong_length() { + assert!(matches!( + MessageId::new([0u8; 15]), + Err(Error::InvalidLength { + expected: 16, + actual: 15 + }) + )); + } + + #[test] + fn message_id_base64url_round_trip() { + let id = MessageId::new([7u8; 16]).unwrap(); + assert_eq!(id.to_string().parse::().unwrap(), id); + } + + #[test] + fn message_id_deserialization_enforces_the_16_byte_invariant() { + let id = MessageId::new([7u8; 16]).unwrap(); + let json = serde_json::to_string(&id).unwrap(); + assert_eq!(serde_json::from_str::(&json).unwrap(), id); + + for bad in [ + String::new(), + codec::encode(&[7u8; 15]), + codec::encode(&[7u8; 17]), + ] { + let json = format!("\"{bad}\""); + assert!( + serde_json::from_str::(&json).is_err(), + "{json} must be rejected" + ); + } + } + + #[test] + fn message_id_serializes_as_plain_string() { + let id = MessageId::new([7u8; 16]).unwrap(); + let json = serde_json::to_string(&id).unwrap(); + assert_eq!(json, format!("\"{id}\"")); + assert_eq!(serde_json::from_str::(&json).unwrap(), id); + } + #[test] fn topic_accepts_32_bytes() { assert!(Topic::new([0u8; 32]).is_ok()); diff --git a/crates/core/src/payload.rs b/crates/core/src/payload.rs index c065d89..09dec1b 100644 --- a/crates/core/src/payload.rs +++ b/crates/core/src/payload.rs @@ -1,9 +1,29 @@ -use serde::{Deserialize, Serialize}; +use std::fmt; + +use serde::{Deserialize, Deserializer, Serialize}; + +use crate::message::MessageId; + +/// Distinguish an omitted optional field from an explicit `null`. +fn deserialize_optional_alternative<'de, D>(deserializer: D) -> Result, D::Error> +where + D: Deserializer<'de>, +{ + let value = Option::::deserialize(deserializer)? + .ok_or_else(|| serde::de::Error::custom("field must be omitted, not null"))?; + Ok(Some(value)) +} /// Opaque application data carried inside a payload shape. -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Opaque(#[serde(with = "crate::codec::base64url")] pub Vec); +impl fmt::Debug for Opaque { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("Opaque(..)") + } +} + /// Body of a `proposal` message. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] @@ -22,6 +42,9 @@ pub struct ProposalPayload { #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct ApprovePayload { + /// The `id` of the frame that carried the proposal being approved. + pub proposal_id: MessageId, + /// The responder's one-time X25519 public key. pub ephemeral_public_key: String, @@ -30,8 +53,12 @@ pub struct ApprovePayload { } /// Body of a `reject` message. -#[derive(Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] pub struct RejectPayload { + /// The `id` of the frame that carried the proposal being rejected. + pub proposal_id: MessageId, + /// Reason code for the rejection pub code: u32, @@ -40,7 +67,7 @@ pub struct RejectPayload { } /// Body of a `request` message. -#[derive(Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct RequestPayload { /// Caller-assigned identifier used to correlate the eventual `response` @@ -52,32 +79,49 @@ pub struct RequestPayload { } /// Body of a `response` message. -#[derive(Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct ResponsePayload { /// Identifier of the `request` being answered. pub request_id: String, /// Opaque application result; present on success, absent on error. + #[serde( + default, + deserialize_with = "deserialize_optional_alternative", + skip_serializing_if = "Option::is_none" + )] pub response: Option, /// Failure description; present on error, absent on success. + #[serde( + default, + deserialize_with = "deserialize_optional_alternative", + skip_serializing_if = "Option::is_none" + )] pub error: Option, } +impl ResponsePayload { + /// Whether exactly one of `response` and `error` is present. + pub fn is_valid(&self) -> bool { + self.response.is_some() != self.error.is_some() + } +} + /// Body of an `ack` message. /// /// Confirms receipt of an ack-required message, driving the retransmission /// logic. -#[derive(Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct AckPayload { /// The envelope `id` of the message being acknowledged. - pub ack_id: String, + pub ack_id: MessageId, } /// Body of a `disconnect` message. -#[derive(Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct DisconnectPayload { /// Short reason label for the disconnect. pub reason: String, @@ -90,7 +134,7 @@ pub struct DisconnectPayload { } /// Body of a `session_delete` message. -#[derive(Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct SessionDeletePayload { /// Machine-readable close code. pub code: u32, @@ -148,10 +192,55 @@ mod tests { type TestResult = Result<(), Box>; + #[test] + fn response_serializes_exactly_one_alternative() -> TestResult { + let success = ResponsePayload { + request_id: "req-1".to_owned(), + response: Some(Opaque(vec![1, 2, 3])), + error: None, + }; + let value = serde_json::to_value(&success)?; + assert_eq!(value.get("response"), Some(&serde_json::json!("AQID"))); + assert!(value.get("error").is_none()); + assert!(success.is_valid()); + + let failure = ResponsePayload { + request_id: "req-1".to_owned(), + response: None, + error: Some(Opaque(vec![4, 5])), + }; + let value = serde_json::to_value(&failure)?; + assert!(value.get("response").is_none()); + assert_eq!(value.get("error"), Some(&serde_json::json!("BAU"))); + assert!(failure.is_valid()); + + let neither = ResponsePayload { + request_id: "req-1".to_owned(), + response: None, + error: None, + }; + assert!(!neither.is_valid()); + + let both = ResponsePayload { + request_id: "req-1".to_owned(), + response: Some(Opaque(Vec::new())), + error: Some(Opaque(Vec::new())), + }; + assert!(!both.is_valid()); + Ok(()) + } + + #[test] + fn opaque_debug_redacts_application_data() { + let opaque = Opaque(vec![1, 2, 3, 4]); + assert_eq!(format!("{opaque:?}"), "Opaque(..)"); + } + #[test] fn bodies_with_the_same_shape_are_distinguished() -> TestResult { - let rejected: Payload = - serde_json::from_str(r#"{"type":"reject","code":1,"message":"no"}"#)?; + let rejected: Payload = serde_json::from_str( + r#"{"type":"reject","proposalId":"AAAAAAAAAAAAAAAAAAAAAA","code":1,"message":"no"}"#, + )?; assert!(matches!(rejected, Payload::Reject(_))); let disconnected: Payload = serde_json::from_str( diff --git a/crates/relay/src/connection.rs b/crates/relay/src/connection.rs index 133b74b..e5a5bec 100644 --- a/crates/relay/src/connection.rs +++ b/crates/relay/src/connection.rs @@ -17,7 +17,7 @@ use tokio_tungstenite::{ protocol::{CloseFrame, frame::coding::CloseCode}, }, }; -use wallet_session_core::{codec, connection::ConnectionQuery}; +use wallet_session_core::connection::ConnectionQuery; use crate::{ auth::{Identity, IdentityError, unix_now}, @@ -30,6 +30,7 @@ use crate::{ use wallet_session_core::{ did::DidKey, frame::{RelayFrame, RelayFrameBody}, + message::MessageId, }; /// Server-side relay WebSocket stream, read through the connection's wire @@ -99,10 +100,10 @@ fn reject_response() -> ErrorResponse { response } -pub(crate) fn random_id() -> Result { - let mut bytes = [0u8; 16]; +pub(crate) fn random_id() -> Result { + let mut bytes = [0u8; MessageId::LEN]; getrandom::fill(&mut bytes)?; - Ok(codec::encode(&bytes)) + Ok(MessageId::from_bytes(bytes)) } /// The client behind an accepted handshake. @@ -982,6 +983,14 @@ mod tests { Topic::new([1u8; 32]) } + /// A distinct, valid message id for a test label. + fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) + } + fn parse(query: &str) -> Result<(ConnectionQuery, Identity), ConnectionError> { parse_connection( &uri(query).map_err(|_| ConnectionError::HandshakeFailed)?, @@ -1176,7 +1185,7 @@ mod tests { } /// Ids of the frames a test reader accepted. - type Accepted = Arc>>; + type Accepted = Arc>>; /// A reader that takes `per_message` to accept each message, and the ids /// of the frames it accepted. @@ -1235,7 +1244,7 @@ mod tests { ) -> Result> { let frame = RelayFrame { v: RELAY_FRAME_VERSION, - id: id.to_owned(), + id: message_id(id), topic: topic()?, body: RelayFrameBody::Message { payload: "ciphertext".to_owned(), @@ -1267,7 +1276,10 @@ mod tests { window.contains(&elapsed), "the writer must stop once a frame has waited the queue timeout, not {elapsed:?}" ); - assert_eq!(*accepted.lock().expect("accepted ids"), ["m0", "m1", "m2"]); + assert_eq!( + *accepted.lock().expect("accepted ids"), + [message_id("m0"), message_id("m1"), message_id("m2")] + ); drop(tx); assert_eq!(budget.held(), 0, "frames left behind give their bytes back"); @@ -1296,7 +1308,12 @@ mod tests { ); assert_eq!( *accepted.lock().expect("accepted ids"), - ["m0", "m1", "m2", "m3"] + [ + message_id("m0"), + message_id("m1"), + message_id("m2"), + message_id("m3") + ] ); assert_eq!(budget.held(), 0, "written frames give their bytes back"); @@ -1351,7 +1368,7 @@ mod tests { }; let ready = RelayFrame { v: RELAY_FRAME_VERSION, - id: "ready".to_owned(), + id: message_id("ready"), topic: topic()?, body: RelayFrameBody::SessionReady, }; diff --git a/crates/relay/src/health.rs b/crates/relay/src/health.rs index c9ffc0f..a3a3455 100644 --- a/crates/relay/src/health.rs +++ b/crates/relay/src/health.rs @@ -112,7 +112,7 @@ mod tests { use wallet_session_core::{ did::DidKey, frame::{RelayFrame, RelayFrameBody}, - message::Topic, + message::{MessageId, Topic}, }; use super::*; @@ -185,7 +185,7 @@ mod tests { permit, &RelayFrame { v: 1, - id: "ready".to_owned(), + id: MessageId::from_bytes([0u8; MessageId::LEN]), topic: topic.clone(), body: RelayFrameBody::SessionReady, }, diff --git a/crates/relay/src/registry.rs b/crates/relay/src/registry.rs index 1f08f7e..ec6ac28 100644 --- a/crates/relay/src/registry.rs +++ b/crates/relay/src/registry.rs @@ -175,6 +175,7 @@ mod tests { use tokio::sync::mpsc; use crate::limits::{Limiter, OutboundBudget, RelayLimitsConfig}; + use wallet_session_core::message::MessageId; /// A permit for `identity`, from a limiter that is never shared: these /// tests do not exercise the per-identity cap. @@ -219,7 +220,7 @@ mod tests { fn notification(topic: &Topic) -> RelayFrame { RelayFrame { v: 1, - id: "gone".to_owned(), + id: MessageId::from_bytes([1u8; MessageId::LEN]), topic: topic.clone(), body: wallet_session_core::frame::RelayFrameBody::PeerDisconnected, } @@ -228,7 +229,7 @@ mod tests { fn ready(topic: &Topic) -> RelayFrame { RelayFrame { v: 1, - id: "ready".to_owned(), + id: MessageId::from_bytes([2u8; MessageId::LEN]), topic: topic.clone(), body: wallet_session_core::frame::RelayFrameBody::SessionReady, } diff --git a/crates/relay/src/server.rs b/crates/relay/src/server.rs index 0dd7e68..61617eb 100644 --- a/crates/relay/src/server.rs +++ b/crates/relay/src/server.rs @@ -205,7 +205,7 @@ mod tests { }, }; use wallet_session_core::frame::{RelayFrame, RelayFrameBody}; - use wallet_session_core::message::Topic; + use wallet_session_core::message::{MessageId, Topic}; const AUDIENCE: &str = "wss://relay.example.com"; @@ -229,6 +229,14 @@ mod tests { Topic::new([9u8; 32]) } + /// A distinct, valid message id for a test label. + fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) + } + async fn connect( addr: SocketAddr, role: &str, @@ -296,7 +304,7 @@ mod tests { let message = RelayFrame { v: RELAY_FRAME_VERSION, - id: "m1".to_owned(), + id: message_id("m1"), topic: topic.clone(), body: RelayFrameBody::Message { payload: "hello".to_owned(), @@ -419,11 +427,17 @@ mod tests { /// can wait for the relay to finish tearing that connection down. async fn serve_tracked( config: NativeRelayTransportConfig, + ) -> Result<(SocketAddr, Handlers), Box> { + serve_tracked_with_limiter(config, limiter()).await + } + + async fn serve_tracked_with_limiter( + config: NativeRelayTransportConfig, + limiter: Arc, ) -> Result<(SocketAddr, Handlers), Box> { let listener = TcpListener::bind("127.0.0.1:0").await?; let addr = listener.local_addr()?; let registry = Arc::new(Registry::new()); - let limiter = limiter(); let (handlers_tx, handlers) = mpsc::unbounded_channel(); tokio::spawn(async move { while let Ok((stream, _)) = listener.accept().await { @@ -520,7 +534,7 @@ mod tests { let message = RelayFrame { v: RELAY_FRAME_VERSION, - id: "buffered".to_owned(), + id: message_id("buffered"), topic: topic.clone(), body: RelayFrameBody::Message { payload: "queued".to_owned(), @@ -618,7 +632,7 @@ mod tests { fn message(topic: &Topic, id: &str, payload: &str) -> RelayFrame { RelayFrame { v: RELAY_FRAME_VERSION, - id: id.to_owned(), + id: message_id(id), topic: topic.clone(), body: RelayFrameBody::Message { payload: payload.to_owned(), @@ -737,7 +751,7 @@ mod tests { } assert_eq!( redelivered, - ["m2", "m3"], + [message_id("m2"), message_id("m3")], "the oldest buffered frame makes room for the newest" ); Ok(()) @@ -1276,7 +1290,7 @@ mod tests { // Clients must not forge the relay-only session_ready frame. let rogue = RelayFrame { v: RELAY_FRAME_VERSION, - id: "rogue".to_owned(), + id: message_id("rogue"), topic: topic.clone(), body: RelayFrameBody::SessionReady, }; @@ -1349,7 +1363,7 @@ mod tests { let forged = RelayFrame { v: RELAY_FRAME_VERSION, - id: "forged".to_owned(), + id: message_id("forged"), topic: topic.clone(), body: RelayFrameBody::PeerDisconnected, }; @@ -1428,6 +1442,99 @@ mod tests { Ok(()) } + /// Frame ids are 16 bytes, base64url. Anything else is a malformed frame, + /// and the relay closes the sender rather than forwarding it. + #[tokio::test] + async fn non_canonical_frame_id_closes_connection() -> TestResult { + let addr = serve_with( + NativeRelayTransportConfig::new(AUDIENCE).with_session_grace(Duration::from_secs(2)), + ) + .await?; + + let topic = topic()?; + let mut proposer = connect(addr, "proposer", &topic, Some("reg-1")).await?; + let mut responder = connect(addr, "responder", &topic, None).await?; + assert!(matches!( + read_frame(&mut proposer).await?.body, + RelayFrameBody::SessionReady + )); + assert!(matches!( + read_frame(&mut responder).await?.body, + RelayFrameBody::SessionReady + )); + + let frame = RelayFrame { + v: 1, + id: message_id("short-id"), + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: "x".to_owned(), + }, + }; + let mut value = serde_json::to_value(&frame)?; + // Five bytes, which is valid base64url but not a frame id. + value["id"] = serde_json::Value::from("c2hvcnQ"); + proposer + .send(Message::Text(value.to_string().into())) + .await?; + assert!( + expect_closed(&mut proposer).await, + "a frame id that is not 16 bytes should close the connection" + ); + Ok(()) + } + + /// A 16-byte id has exactly one encoding. Padding, or non-zero trailing + /// bits in the last character, must not be accepted as another spelling + /// of the same id. + #[tokio::test] + async fn non_canonical_frame_id_encodings_close_connection() -> TestResult { + let canonical = message_id("x").to_string(); + assert_eq!(canonical.len(), 22); + let mut trailing_bits = canonical.clone(); + trailing_bits.replace_range(21.., "B"); + for (label, id) in [ + ("padding", format!("{canonical}==")), + ("trailing bits", trailing_bits), + ] { + let addr = serve_with( + NativeRelayTransportConfig::new(AUDIENCE) + .with_session_grace(Duration::from_secs(2)), + ) + .await?; + let topic = topic()?; + let mut proposer = connect(addr, "proposer", &topic, Some("reg-1")).await?; + let mut responder = connect(addr, "responder", &topic, None).await?; + assert!(matches!( + read_frame(&mut proposer).await?.body, + RelayFrameBody::SessionReady + )); + assert!(matches!( + read_frame(&mut responder).await?.body, + RelayFrameBody::SessionReady + )); + + let frame = RelayFrame { + v: 1, + id: message_id("x"), + topic: topic.clone(), + body: RelayFrameBody::Message { + payload: "x".to_owned(), + }, + }; + let mut value = serde_json::to_value(&frame)?; + value["id"] = serde_json::Value::from(id); + proposer + .send(Message::Text(value.to_string().into())) + .await?; + assert!( + expect_closed(&mut proposer).await, + "a frame id with {label} should close the connection" + ); + } + Ok(()) + } + #[tokio::test] async fn unsupported_frame_version_closes_connection() -> TestResult { let addr = serve_with( @@ -1449,7 +1556,7 @@ mod tests { let rogue = RelayFrame { v: 2, - id: "rogue".to_owned(), + id: message_id("rogue"), topic: topic.clone(), body: RelayFrameBody::Message { payload: "future".to_owned(), @@ -2011,7 +2118,10 @@ mod tests { { delivered.push(frame.id); } - assert_eq!(delivered, ["m0", "m1", "m2"]); + assert_eq!( + delivered, + [message_id("m0"), message_id("m1"), message_id("m2")] + ); Ok(()) } @@ -2252,12 +2362,13 @@ mod tests { ..ping_limits() })); let config = NativeRelayTransportConfig::new(AUDIENCE); - let addr = serve_with_limiter(config, Arc::clone(&limiter)).await?; + let (addr, mut handlers) = serve_tracked_with_limiter(config, Arc::clone(&limiter)).await?; // Every ping after the first is dropped, and once the drops pass the // consecutive-drop limit the sender is disconnected. Sends may fail // after that. let mut hog = connect(addr, "proposer", &topic()?, None).await?; + let handler = handlers.recv().await.ok_or("relay stopped accepting")?; let _ = send_pings(&mut hog, MAX_CONSECUTIVE_RATE_DROPS + 8, PING_PAYLOAD).await; let limit = u64::from(PING_PAYLOAD) * u64::from(MAX_CONSECUTIVE_RATE_DROPS); let dropped = wait_for_count(|| limiter.dropped_share_bytes(), limit + 1).await; @@ -2265,9 +2376,14 @@ mod tests { dropped > limit, "the relay must process enough dropped pings to reach the disconnect threshold" ); + let result = timeout(SYNC_TIMEOUT, handler).await?; assert!( - expect_closed_within(&mut hog, Duration::from_secs(10)).await, - "an identity flooding control frames over its share must be disconnected" + matches!( + result, + Ok(Err(ServerError::Connection(ConnectionError::RateLimited))) + ), + "an identity flooding control frames over its share must be disconnected \ + for exceeding its rate, got {result:?}" ); assert_eq!(limiter.dropped_global_bytes(), 0); Ok(()) @@ -2609,7 +2725,7 @@ mod tests { .await?; // The message is whole, so every fragment was read, in order. - assert_eq!(read_frame(&mut responder).await?.id, "f0"); + assert_eq!(read_frame(&mut responder).await?.id, message_id("f0")); // What the burst did not cover takes about 2.7 seconds. let elapsed = started.elapsed(); assert!( @@ -2619,7 +2735,7 @@ mod tests { // The sender is still connected, and its next frame goes through. send(&mut proposer, &message(&topic, "f1", "still-connected")).await?; - assert_eq!(read_frame(&mut responder).await?.id, "f1"); + assert_eq!(read_frame(&mut responder).await?.id, message_id("f1")); Ok(()) } diff --git a/crates/relay/src/session.rs b/crates/relay/src/session.rs index 8014173..27d5180 100644 --- a/crates/relay/src/session.rs +++ b/crates/relay/src/session.rs @@ -651,7 +651,7 @@ mod tests { use crate::connection::RELAY_FRAME_VERSION; use crate::limits::{Limiter, RelayLimitsConfig}; use wallet_session_core::frame::RelayFrameBody; - use wallet_session_core::message::Topic; + use wallet_session_core::message::{MessageId, Topic}; type TestResult = Result<(), Box>; @@ -670,6 +670,14 @@ mod tests { Topic::new([1u8; 32]) } + /// A distinct, valid message id for a test label. + fn message_id(label: &str) -> MessageId { + let mut bytes = [0u8; MessageId::LEN]; + let label = &label.as_bytes()[..label.len().min(MessageId::LEN)]; + bytes[..label.len()].copy_from_slice(label); + MessageId::from_bytes(bytes) + } + fn peer(seed: u8) -> (PeerHandle, mpsc::Receiver) { peer_with(seed, PEER_QUEUE, PEER_BUDGET) } @@ -693,7 +701,7 @@ mod tests { } /// Ids of the frames waiting in a queue, taking them out as a writer would. - fn take_ids(rx: &mut mpsc::Receiver) -> Vec { + fn take_ids(rx: &mut mpsc::Receiver) -> Vec { let mut ids = Vec::new(); while let Ok(queued) = rx.try_recv() { ids.push(queued.frame.id); @@ -717,7 +725,7 @@ mod tests { fn frame(topic: &Topic) -> RelayFrame { RelayFrame { v: RELAY_FRAME_VERSION, - id: "frame-id".to_owned(), + id: message_id("frame-id"), topic: topic.clone(), body: RelayFrameBody::Message { payload: "ciphertext".to_owned(), @@ -728,7 +736,7 @@ mod tests { fn ready(topic: &Topic) -> RelayFrame { RelayFrame { v: RELAY_FRAME_VERSION, - id: "ready".to_owned(), + id: message_id("ready"), topic: topic.clone(), body: RelayFrameBody::SessionReady, } @@ -738,7 +746,7 @@ mod tests { fn notification() -> RelayFrame { RelayFrame { v: RELAY_FRAME_VERSION, - id: "gone".to_owned(), + id: message_id("gone"), topic: topic().expect("topic"), body: RelayFrameBody::PeerDisconnected, } @@ -746,7 +754,7 @@ mod tests { fn frame_with_id(topic: &Topic, id: &str) -> RelayFrame { RelayFrame { - id: id.to_owned(), + id: message_id(id), ..frame(topic) } } @@ -783,7 +791,7 @@ mod tests { role: Role, tx: &mpsc::Sender, rx: &mut mpsc::Receiver, - ) -> Result, SessionError> { + ) -> Result, SessionError> { let mut ids = Vec::new(); loop { let drain = session.drain_backlog(role, tx)?; @@ -932,7 +940,7 @@ mod tests { // frames to the disconnected peer are buffered, not dropped session.route(Role::Proposer, frame(&topic()?), MAX_BUFFERED, BUFFER_TTL)?; - assert_eq!(responder_rx.try_recv()?.frame.id, "ready"); + assert_eq!(responder_rx.try_recv()?.frame.id, message_id("ready")); assert!(responder_rx.try_recv().is_err()); // same identity reconnects within grace and receives session_ready, @@ -943,7 +951,7 @@ mod tests { assert!(matches!(registration, Registration::BothReady)); assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "frame-id"] + [message_id("ready"), message_id("frame-id")] ); Ok(()) } @@ -985,7 +993,7 @@ mod tests { let ids = received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?; assert_eq!( ids, - ["ready", "frame-id"], + [message_id("ready"), message_id("frame-id")], "only the unexpired frame is redelivered" ); Ok(()) @@ -1008,7 +1016,14 @@ mod tests { let tx = responder.tx.clone(); register(&session, Role::Responder, responder)?; let ids = received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?; - assert_eq!(ids, ["ready", "frame-id", "frame-id"]); + assert_eq!( + ids, + [ + message_id("ready"), + message_id("frame-id"), + message_id("frame-id") + ] + ); Ok(()) } @@ -1039,7 +1054,7 @@ mod tests { register(&session, Role::Proposer, proposer)?; register(&session, Role::Responder, responder)?; disconnect_current(&session, Role::Responder, Duration::from_secs(1))?; - assert_eq!(proposer_rx.try_recv()?.frame.id, "ready"); + assert_eq!(proposer_rx.try_recv()?.frame.id, message_id("ready")); tokio::time::advance(Duration::from_secs(2)).await; let notice = notification(); @@ -1104,8 +1119,8 @@ mod tests { BUFFER_TTL, )?; - assert_eq!(responder_rx.try_recv()?.frame.id, "ready"); - assert_eq!(responder_rx.try_recv()?.frame.id, "m1"); + assert_eq!(responder_rx.try_recv()?.frame.id, message_id("ready")); + assert_eq!(responder_rx.try_recv()?.frame.id, message_id("m1")); Ok(()) } @@ -1144,7 +1159,13 @@ mod tests { assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "old1", "old2", "new1", "new2"] + [ + message_id("ready"), + message_id("old1"), + message_id("old2"), + message_id("new1"), + message_id("new2") + ] ); // Once drained, frames go straight to the queue again. @@ -1154,7 +1175,7 @@ mod tests { MAX_BUFFERED, BUFFER_TTL, )?; - assert_eq!(responder_rx.try_recv()?.frame.id, "live"); + assert_eq!(responder_rx.try_recv()?.frame.id, message_id("live")); Ok(()) } @@ -1196,8 +1217,8 @@ mod tests { let mut ids = take_ids(&mut responder_rx); ids.extend(received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?); - let mut expected = vec!["ready".to_owned()]; - expected.extend((0..total).map(|i| format!("m{i:02}"))); + let mut expected = vec![message_id("ready")]; + expected.extend((0..total).map(|i| message_id(&format!("m{i:02}")))); assert_eq!(ids, expected); Ok(()) } @@ -1225,12 +1246,12 @@ mod tests { // The stale connection finally gets to run. assert_eq!( received_ids(&session, Role::Responder, &first_tx, &mut first_rx).await?, - ["ready"], + [message_id("ready")], "a stale connection must not consume the new connection's backlog" ); assert_eq!( received_ids(&session, Role::Responder, &second_tx, &mut second_rx).await?, - ["ready", "frame-id"] + [message_id("ready"), message_id("frame-id")] ); Ok(()) } @@ -1242,7 +1263,7 @@ mod tests { let (old, mut old_rx) = peer(2); register(&session, Role::Proposer, proposer)?; register(&session, Role::Responder, old)?; - assert_eq!(proposer_rx.try_recv()?.frame.id, "ready"); + assert_eq!(proposer_rx.try_recv()?.frame.id, message_id("ready")); // Same identity, new connection, while the old one is still registered. let (new, mut new_rx) = peer(2); @@ -1253,7 +1274,7 @@ mod tests { )); // The counterpart sees the peer come back. - assert_eq!(proposer_rx.try_recv()?.frame.id, "ready"); + assert_eq!(proposer_rx.try_recv()?.frame.id, message_id("ready")); // Routing now reaches the new connection only. session.route( @@ -1264,7 +1285,7 @@ mod tests { )?; assert_eq!( received_ids(&session, Role::Responder, &new_tx, &mut new_rx).await?, - ["ready", "m1"] + [message_id("ready"), message_id("m1")] ); // The replaced connection's queue is closed once its old frames drain. @@ -1297,8 +1318,8 @@ mod tests { MAX_BUFFERED, BUFFER_TTL, )?; - assert_eq!(owner_rx.try_recv()?.frame.id, "ready"); - assert_eq!(owner_rx.try_recv()?.frame.id, "m1"); + assert_eq!(owner_rx.try_recv()?.frame.id, message_id("ready")); + assert_eq!(owner_rx.try_recv()?.frame.id, message_id("m1")); Ok(()) } @@ -1327,7 +1348,7 @@ mod tests { )?; assert_eq!( received_ids(&session, Role::Responder, &new_tx, &mut new_rx).await?, - ["ready", "m1"] + [message_id("ready"), message_id("m1")] ); // And an expiry the old teardown might have scheduled is a no-op. @@ -1369,7 +1390,7 @@ mod tests { assert_eq!( received_ids(&session, Role::Responder, &second_tx, &mut second_rx).await?, - ["ready", "old", "new"], + [message_id("ready"), message_id("old"), message_id("new")], "frames not yet handed to the replaced connection must not be lost" ); Ok(()) @@ -1491,7 +1512,7 @@ mod tests { assert_eq!( received_ids(&session, Role::Responder, &other_tx, &mut other_rx).await?, - ["ready"], + [message_id("ready")], "frames buffered for the previous owner must not reach another identity" ); Ok(()) @@ -1515,7 +1536,7 @@ mod tests { assert_eq!( received_ids(&session, Role::Responder, &tx, &mut reconnect_rx).await?, - ["ready", "frame-id"], + [message_id("ready"), message_id("frame-id")], "the owner gets its frames back after the reservation expired" ); Ok(()) @@ -1552,7 +1573,7 @@ mod tests { assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready"], + [message_id("ready")], "a frame reclaimed before its TTL must not be delivered after it" ); Ok(()) @@ -1602,7 +1623,7 @@ mod tests { tokio::time::advance(Duration::from_secs(3)).await; assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "late"], + [message_id("ready"), message_id("late")], "at t=9 only the frame queued at t=6 is still deliverable" ); Ok(()) @@ -1632,7 +1653,7 @@ mod tests { assert_eq!( received_ids(&session, Role::Responder, &second_tx, &mut second_rx).await?, - ["ready"], + [message_id("ready")], "an inherited frame must not outlive its TTL" ); Ok(()) @@ -1711,7 +1732,7 @@ mod tests { )); assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["gone", "ready"], + [message_id("gone"), message_id("ready")], "frames from an expired counterpart must not follow peer_disconnected" ); Ok(()) @@ -1745,7 +1766,7 @@ mod tests { )); assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready"], + [message_id("ready")], "frames the previous proposer sent must not reach the responder as the new one's" ); Ok(()) @@ -1753,10 +1774,12 @@ mod tests { #[test] fn encoded_len_is_the_text_the_writer_sends() -> TestResult { + // Frame ids are base64url and never need escaping, so put every + // character JSON escapes in the payload. let frame = RelayFrame { - id: "quote \" backslash \\ newline \n control \u{1}".to_owned(), body: RelayFrameBody::Message { - payload: "é \u{7f} \u{1f} \u{1F600}".to_owned(), + payload: "quote \" backslash \\ newline \n control \u{1} é \u{7f} \u{1f} \u{1F600}" + .to_owned(), }, ..frame(&topic()?) }; @@ -1782,12 +1805,15 @@ mod tests { route_id(&session, id)?; } assert_eq!(budget.held(), 2 * one, "session_ready is not charged"); - assert_eq!(take_ids(&mut responder_rx), ["ready", "m1", "m2"]); + assert_eq!( + take_ids(&mut responder_rx), + [message_id("ready"), message_id("m1"), message_id("m2")] + ); // Written frames give their bytes back. assert_eq!(budget.held(), 0); route_id(&session, "m4")?; - assert_eq!(take_ids(&mut responder_rx), ["m4"]); + assert_eq!(take_ids(&mut responder_rx), [message_id("m4")]); Ok(()) } @@ -1812,7 +1838,12 @@ mod tests { assert_eq!( take_ids(&mut responder_rx), - ["ready", "m1", "gone", "ready"], + [ + message_id("ready"), + message_id("m1"), + message_id("gone"), + message_id("ready") + ], "control frames bypass the byte budget" ); Ok(()) @@ -1840,7 +1871,13 @@ mod tests { assert_eq!(budget.held(), 4 * one); assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "m1", "m3", "m4", "m5"] + [ + message_id("ready"), + message_id("m1"), + message_id("m3"), + message_id("m4"), + message_id("m5") + ] ); assert_eq!(budget.held(), 0, "written frames give their bytes back"); Ok(()) @@ -1868,7 +1905,7 @@ mod tests { session.route(Role::Proposer, large, MAX_BUFFERED, BUFFER_TTL)?; assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "m1", "m2"] + [message_id("ready"), message_id("m1"), message_id("m2")] ); Ok(()) } @@ -1900,7 +1937,12 @@ mod tests { session.route(Role::Proposer, large_frame(&topic, 2 * one), 2, BUFFER_TTL)?; assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "m1", "m2", "m3"] + [ + message_id("ready"), + message_id("m1"), + message_id("m2"), + message_id("m3") + ] ); Ok(()) } @@ -1928,7 +1970,7 @@ mod tests { register(&session, Role::Responder, responder)?; assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "m1", "m2"] + [message_id("ready"), message_id("m1"), message_id("m2")] ); Ok(()) } @@ -1945,7 +1987,7 @@ mod tests { assert_eq!(drain.delivered, 1); // The writer takes session_ready, which frees a queue slot but no bytes. - assert_eq!(responder_rx.try_recv()?.frame.id, "ready"); + assert_eq!(responder_rx.try_recv()?.frame.id, message_id("ready")); // Room for m3 means dropping m2, the whole backlog. A frame left on an // empty backlog would never be drained, so m3 goes to the queue. @@ -1958,7 +2000,10 @@ mod tests { finished: true, } ); - assert_eq!(take_ids(&mut responder_rx), ["m1", "m3"]); + assert_eq!( + take_ids(&mut responder_rx), + [message_id("m1"), message_id("m3")] + ); Ok(()) } @@ -1991,7 +2036,7 @@ mod tests { assert_eq!(budget.held(), 2 * one, "moved to the new budget"); assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "m2", "m3"] + [message_id("ready"), message_id("m2"), message_id("m3")] ); Ok(()) } @@ -2007,7 +2052,7 @@ mod tests { register(&session, Role::Responder, responder)?; assert_eq!( received_ids(&session, Role::Responder, &tx, &mut responder_rx).await?, - ["ready", "m2", "m3"] + [message_id("ready"), message_id("m2"), message_id("m3")] ); Ok(()) } @@ -2035,7 +2080,7 @@ mod tests { assert_eq!(second_budget.held(), 2 * one); assert_eq!( received_ids(&session, Role::Responder, &second_tx, &mut second_rx).await?, - ["ready", "m2", "m3"] + [message_id("ready"), message_id("m2"), message_id("m3")] ); Ok(()) } @@ -2091,7 +2136,7 @@ mod tests { register(&session, Role::Responder, second)?; assert_eq!( received_ids(&session, Role::Responder, &second_tx, &mut second_rx).await?, - ["ready", "late"], + [message_id("ready"), message_id("late")], "the backlog survives the connection, with the expiry it was buffered with" ); Ok(()) @@ -2120,7 +2165,7 @@ mod tests { register(&session, Role::Responder, other)?; assert_eq!( received_ids(&session, Role::Responder, &other_tx, &mut other_rx).await?, - ["ready"], + [message_id("ready")], "frames kept for the previous owner must not reach another identity" ); assert_eq!( diff --git a/docs/spec.md b/docs/spec.md index 91c1c60..6caeb2b 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -130,9 +130,15 @@ Responder (wallet) -- Scans the pairing QR-code, approves or rejects proposals, Roles are not permanent: a client can be a proposer in one session and a responder in another. Both roles run the same client implementation and differ only in which side initiates. +Within a session the roles are fixed. Only the proposer sends `proposal`; only the responder sends `approve` or `reject`. A receiver drops, without acknowledging, a handshake message that its counterpart's role may not send. + ## 7. Topic -Topic is a 32-byte value. Topics are derived from initial pairing key clients as a SHA256 hash. +A topic is a 32-byte value, encoded as unpadded base64url on the wire. + +Every binary field in this document (keys, topics, ids, nonces, ciphertext and opaque application data) uses the URL-safe base64 alphabet without padding, in its canonical form: a decoder rejects padding, and non-zero bits left over in the last character. A field of fixed length, such as a 16-byte frame id, also has exactly one valid length. + +The pairing topic is `SHA-256(pairing_key)`. The session topic is derived from the X25519 shared secret with HKDF-SHA256 (§9.1); it is not a hash of the pairing key. No other topic is derived by hashing a bearer key. ## 8. Pairing @@ -166,10 +172,48 @@ Session establishment flow: 2. responder scans QR-code, derives topic from pairing key, and connects to the Relay by this topic. 3. Relay sending `session_ready` control frame to both sides 4. proposer embeds its ephemeral public key in the proposal, encrypted with the pairing key -5. responder derives the session key, and embeds its own ephemeral public key in the approve message, encrypted with the pairing key; +5. responder derives the session key, and embeds its own ephemeral public key in the approve message, encrypted with the pairing key, together with the `id` of the frame that carried the proposal it approves; 6. proposer derives the same session key; 7. both parties continues exchanging messages by the new session key, using the same session. +A valid `approve` or `reject` also acknowledges the proposal it answers, so a lost `ack` for the proposal does not make the proposer report it as failed. A `reject` names the proposal it answers in the same way as an `approve` (see below), and the proposer drops a `reject` for any proposal but its outstanding one. It ends that proposal on both sides: the responder forgets the pending proposal and the key it derived for it, and the proposer discards the proposal's keypair. The pairing connection stays open, and the proposer may propose again. + +A proposer whose proposal is never acknowledged may propose again with a fresh ephemeral keypair. An `approve` therefore names the proposal it answers. The proposer MUST drop, without acknowledging, an `approve` whose `proposalId` is not the `id` of its outstanding proposal: the responder's key was derived against a keypair the proposer no longer holds, and accepting it would leave the two peers on different session topics. Until it approves, a responder that receives a newer `proposal` from its counterpart replaces the pending one. Its user then has to decide on the newer proposal: a decision made on the replaced one MUST NOT be sent as the answer to the newer one, since the proposer could otherwise swap the terms after the user has seen them. A newer proposal whose `ephemeralPublicKey`, `sessionExpiry` and `proposal` are all identical to the replaced one's offers the user nothing new, and a decision made on either may answer it. + +### 9.1 Session key and topic derivation + +Both peers use the 32-byte X25519 shared secret as HKDF-SHA256 input key +material. `salt = None` in the HKDF API is the RFC 5869 salt of 32 zero bytes. + +``` +PRK = HKDF-Extract(salt = 32 zero bytes, IKM = shared_secret) + +session_key = HKDF-Expand(PRK, info = "wallet-session/v1/session-key", L = 32) +session_topic_bytes = HKDF-Expand(PRK, info = "wallet-session/v1/session-topic", L = 32) +``` + +The two Expand calls are independent and both start from the same PRK. The +session topic used on the wire is `base64url(session_topic_bytes)`. A shared +secret of all zero bytes is rejected. + +The receiver MUST abort that handshake attempt: it MUST NOT acknowledge or +deliver a `proposal` or `approve` that yields an all-zero shared secret. A weak +`proposal` leaves the responder's handshake as it was: idle, or with an earlier +valid proposal still pending. A weak `approve` leaves the proposer in its +proposed state. Either way a later valid message can still complete the +handshake. The client reports the weak-key error to the application. It cannot +answer with a `reject`: a weak `proposal` never becomes the pending proposal a +`reject` would answer, and the proposer never sends one. The application should +treat the pairing as compromised or broken and start over. + +See Appendix A for a known-answer vector. + +The Relay binds each connection to one topic. After deriving the session topic, each peer opens a new connection to it. + +The pairing connection carries handshake kinds and their acknowledgements only. After the `approve` frame is acknowledged, or after the handshake retry window expires, the pairing connection MAY be closed. The window starts when a peer establishes the session: for the responder when it sends `approve`, for the proposer when it accepts one. The default retry window is 127 seconds: a 2-second base delay, five retries with doubling, and a 1-second margin. A peer MUST tolerate closure of the pairing connection after that window; application traffic MUST use the session topic. + +The window is local. Retransmissions pause while the counterpart is disconnected (§13), so a delayed `approve` can still be in flight when the proposer retires its pairing connection, and the responder then sees its `approve` reported as failed even though the proposer may have received it. A responder MUST NOT treat that as a failed handshake on its own. It keeps the session connection until the relay reports `session_ready` on it, which means the proposer derived the same session topic, or until a join timeout (30 seconds by default, counted from the end of the retry window that starts when it sends the `approve`) passes without that ever happening. Only in the latter case was the session not established. An acknowledgement of the `approve` does not stop the join timeout: any holder of the pairing key can send one, and only `session_ready` shows that the proposer derived the session topic. + # Part II. Relay Protocol @@ -209,17 +253,27 @@ The envelope `id` and `topic` are those of the enclosing relay frame and are not Messages on the pairing topic are encrypted with the pairing key; messages on the session topic with the session key. +Kind/topic confinement: + +- The pairing topic carries only `proposal`, `approve`, `reject` and `ack`. +- The session topic carries only `request`, `response`, `ack`, `disconnect` and `session_delete`. +- An `ack` travels on the topic of the envelope it acknowledges. + +A receiver MUST drop a frame whose kind is not allowed on its topic. After the handshake is established, a new handshake kind on the pairing topic is also dropped; only retransmissions already in the replay memory may be re-acknowledged. + A receiver processes each `message` frame in the following order. An envelope rejected at any step is neither delivered to the application nor acknowledged. 1. Reject an unsupported `version`, a `topic` it is not subscribed to, a `from` equal to its own identity and, once the counterpart is established, a `from` other than the counterpart's. 2. Authenticate: decrypt `data` with the topic's key, the envelope `nonce` and the AAD of §11 built with the counterpart's role. Reject an invalid tag. 3. Reject an envelope whose `ts` is more than 300 seconds (5 minutes) older or newer than the local system clock. Also reject one whose `ts` is not greater than the largest `ts` the receiver has discarded from the replay memory of the key. 4. Look up the frame `id` and the `nonce` in the replay memory of the key. An envelope that matches a record by either one, and whose frame `id`, `kind`, `from`, `ts`, `nonce` and `data` are all identical to that record's, is a retransmission: it is acknowledged again if its kind requires an acknowledgement (§13), and it is not delivered again. An envelope that matches a record with any other content is a protocol violation; the receiver must reject it and may end the session. -5. Otherwise, record the envelope in the replay memory, deliver it to the application, and acknowledge it if its kind requires an acknowledgement. +5. Otherwise, record the envelope in the replay memory, deliver it to the application, and acknowledge it if its kind requires an acknowledgement. A receiver may bound its replay memory. One whose memory is full drops a new envelope instead (its sender retransmits it later), except an `ack` that completes one of the receiver's own outstanding sends: dropping that would report a delivered message as failed, so it is processed, and recorded beyond the bound up to a fixed headroom; past that it is processed without being recorded. An `ack` that completes nothing has no effect and may be dropped. A `disconnect` or `session_delete` is not dropped either: its sender never retransmits it (§12). It is processed and recorded, which grows the memory by one record at most, since the receiver then closes. Steps 1 to 3 may run in any order, but only an envelope that has passed all three reaches step 4: an envelope that has not been authenticated is never treated as a retransmission. -The counterpart is the `from` of the first envelope that passes steps 1 to 3 on the pairing topic. It remains the counterpart for that pairing and for the session derived from it, across reconnects. Step 1 rejects the receiver's own identity, so the two peers of a session must have different identities. The AEAD authenticates `from` only as the identity that a holder of the key declares; the identity key does not sign envelopes (§4). +The kind/topic check above runs once the envelope is authenticated, before step 4. The checks on the decrypted plaintext in §12 (its `type` equals `kind`, a `response` carries exactly one alternative) run after step 4 and before step 5, so a retransmission found at step 4 is acknowledged again without being re-checked. An envelope that fails them is dropped like one rejected at any other step. + +The counterpart is the `from` of the first envelope on the pairing topic that the receiver accepts: one that passes every check of this section and is delivered or, for an `ack`, completes one of the receiver's outstanding sends. An envelope that authenticates but is then refused, for example a handshake message from the wrong role, does not establish the counterpart. It remains the counterpart for that pairing and for the session derived from it, across reconnects. Step 1 rejects the receiver's own identity, so the two peers of a session must have different identities. The AEAD authenticates `from` only as the identity that a holder of the key declares; the identity key does not sign envelopes (§4). The replay memory holds, for each key, every envelope the receiver has accepted at step 5. Each record is kept at least until the local clock passes the envelope's `ts` plus 300 seconds. From then on, step 3 rejects every copy of the envelope, so no envelope is delivered twice. Step 3 admits a `ts` at most 300 seconds ahead of the local clock, so no record has to be kept longer than 10 minutes after it was made. While the local clock runs forward, the second check of step 3 rejects nothing the first does not. If the clock steps backward, it keeps discarded envelopes rejected. A receiver may discard the replay memory of a key once it stops accepting envelopes under that key. @@ -230,7 +284,7 @@ Each sender generates a fresh random sender prefix per key. The counter incremen Nonce scheme: ``` -nonce = sender_prefix (16 random bytes) || counter (8 bytes, starts at 0) +nonce = sender_prefix (16 random bytes) || counter (8-byte unsigned big-endian, starts at 0) ``` The AEAD AAD concatenates the following fields, each prefixed with its length: @@ -255,6 +309,10 @@ Relay `type`s (the frame's `type` field): WebSocket ping and pong control frames are not relay frames. +The plaintext in `payload` is a JSON object with a `type` discriminator. Its +value MUST equal the authenticated envelope `kind`; a receiver MUST reject a +plaintext whose `type` does not match `kind`. + Message `kind`s carried inside `payload`: `proposal` -- Propose a session; carries the ephemeral public key. @@ -268,24 +326,33 @@ Message `kind`s carried inside `payload`: Payload shapes: -- `proposal`: `{ ephemeralPublicKey, sessionExpiry, proposal }` -- `approve`: `{ ephemeralPublicKey, approval }` -- `reject`: `{ code, message }` -- `request`: `{ requestId, request }` -- `response`: `{ requestId, response }` or `{ requestId, error }` -- `ack`: `{ ackId }`, where `ackId` is the `id` of the frame that carried the acknowledged message -- `disconnect`: `{ reason, code, message }` -- `session_delete`: `{ code, message }` +- `proposal`: `{ "type": "proposal", "ephemeralPublicKey": ..., "sessionExpiry": ..., "proposal": ... }` +- `approve`: `{ "type": "approve", "proposalId": ..., "ephemeralPublicKey": ..., "approval": ... }`, where `proposalId` is the `id` of the frame that carried the approved proposal +- `reject`: `{ "type": "reject", "proposalId": ..., "code": ..., "message": ... }`, where `proposalId` is the `id` of the frame that carried the rejected proposal +- `request`: `{ "type": "request", "requestId": ..., "request": ... }` +- `response`: `{ "type": "response", "requestId": ..., "response": ... }` or `{ "type": "response", "requestId": ..., "error": ... }` +- `ack`: `{ "type": "ack", "ackId": ... }`, where `ackId` is the `id` of the frame that carried the acknowledged message +- `disconnect`: `{ "type": "disconnect", "reason": ..., "code": ..., "message": ... }` +- `session_delete`: `{ "type": "session_delete", "code": ..., "message": ... }` -`proposal` and `approval` are opaque application data. +A `response` carries exactly one of `response` and `error`. The absent field +MUST be omitted, not encoded as `null`; an explicit `null` is invalid. A +response with both fields, neither field, or an explicit `null` alternative is +rejected: it is neither delivered nor acknowledged. + +`proposal`, `approval`, `request`, `response`, and `error` are opaque application data, encoded as base64url strings. + +`sessionExpiry` is the Unix time at which the proposer suggests the session should end. It is advisory in this version of the protocol: neither peer is required to end the session when it passes, and applications that rely on it must enforce it themselves. + +A `disconnect` or `session_delete` ends the session. The receiver acknowledges it and delivers it to the application like any other message, then closes. A receiver that drops other messages for lack of room, counting on their retransmission, MUST NOT drop a `disconnect` or `session_delete` that way, wherever it runs out of room. The sender closes as soon as it has sent it; since nothing is left to retransmit it, the sender does not wait for its acknowledgement. ## 13. Reliability -Ack: every message of type `proposal`, `approve`, `reject`, `request`, `response`, `disconnect`, and `session_delete` must be acknowledged with an `ack` whose `ackId` equals the `id` of the frame that carried the message. The `ack` message is not itself acknowledged. The receiver sends the `ack` on the topic the message arrived on, only after the message passes the receiver checks of §10, and never for a rejected envelope. An `ack` is sent for every accepted envelope whose type requires one, including a retransmission found in the replay memory (§10, step 4): such a retransmission is acknowledged again and is not delivered to the application a second time. Each `ack` is a new envelope with its own frame `id`, `nonce` and `ts`. Retransmissions must be identical: the same frame `id`, and the same authenticated envelope header and ciphertext (`kind`, `from`, `ts`, `nonce`, `data`). +Ack: every message of type `proposal`, `approve`, `reject`, `request`, `response`, `disconnect`, and `session_delete` must be acknowledged with an `ack` whose `ackId` equals the `id` of the frame that carried the message. The `ack` message is not itself acknowledged. The receiver sends the `ack` on the topic the message arrived on, only after the message passes the receiver checks of §10, and never for a rejected envelope. A receiver under local backpressure may drop an `ack` it cannot send; the sender's retransmission is then acknowledged again (§10, step 4). An `ack` is sent for every accepted envelope whose type requires one, including a retransmission found in the replay memory (§10, step 4): such a retransmission is acknowledged again and is not delivered to the application a second time. Each `ack` is a new envelope with its own frame `id`, `nonce` and `ts`. Retransmissions must be identical: the same frame `id`, and the same authenticated envelope header and ciphertext (`kind`, `from`, `ts`, `nonce`, `data`). -A sender accepts an `ack` only if the envelope carrying it passes the receiver checks of §10, which means it comes from the established counterpart. Its `ackId` must also name a message the sender sent on that topic and still has outstanding. Such an `ack` completes the send. The sender ignores any other `ack` without error. That includes an `ack` for an id it never sent on that topic, or for a message already completed or given up on, so a late `ack` plus a re-`ack` for the same id cannot fail a send. +A sender accepts an `ack` only if the envelope carrying it passes the receiver checks of §10. Once the counterpart is established, that means it comes from the counterpart. Before that, an `ack` that completes a send establishes the counterpart itself (§10); a proposer whose responder acknowledges its proposal before the user decides is in this case. Its `ackId` must also name a message the sender sent on that topic and still has outstanding. Such an `ack` completes the send. The sender ignores any other `ack` without error. That includes an `ack` for an id it never sent on that topic, or for a message already completed or given up on, so a late `ack` plus a re-`ack` for the same id cannot fail a send. -If a sender does not receive an `ack` within 2 seconds, it must retransmit the envelope. Retries must use exponential backoff, doubling from the base delay, up to a maximum of 5 attempts. If the WebSocket disconnects, un-ACKed messages must be held in a local in memory queue and retransmitted immediately upon successful reconnection, and each such retransmission counts as an attempt. A post-reconnect flush is paced traffic like any other: a sender with many pending messages must spread them within the relay's inbound budget instead of sending them in one burst. The sender gives up when the last attempt fails, or earlier once its own clock passes the envelope's `ts` plus 300 seconds, because receivers reject every copy after that (§10, step 3). It then reports the failure to the application. With the values here, the last attempt is about a minute after the first send. The schedule does not affect recognition: a receiver keeps an envelope in its replay memory for as long as it would accept a copy, so every retransmission it accepts is recognized as one. +If a sender does not receive an `ack` within 2 seconds, it must retransmit the envelope. The exceptions are `disconnect` and `session_delete`: the sender closes right after sending them (§12), so it neither retransmits them nor waits for their `ack`. Retries must use exponential backoff, doubling from the base delay, up to a maximum of 5 attempts. If the WebSocket disconnects, un-ACKed messages must be held in a local in memory queue and retransmitted immediately upon successful reconnection, and each such retransmission counts as an attempt. A post-reconnect flush is paced traffic like any other: a sender with many pending messages must spread them within the relay's inbound budget instead of sending them in one burst. The sender gives up when the last attempt fails, or earlier once its own clock passes the envelope's `ts` plus 300 seconds, because receivers reject every copy after that (§10, step 3). It then reports the failure to the application. With the values here, the last attempt is about a minute after the first send. The schedule does not affect recognition: a receiver keeps an envelope in its replay memory for as long as it would accept a copy, so every retransmission it accepts is recognized as one. ## 14. Connection lifecycle @@ -299,4 +366,22 @@ Token expiry is a disconnect cause: the relay closes with `1008` and reason `tok A reconnect does not reset the client state of §10 and §13. The established counterpart, the replay memory and the outstanding messages belong to the pairing or session and its keys, not to the connection. A repeated `session_ready` does not start a new session. A peer that reconnects under a different identity is rejected by its counterpart (§10, step 1), even if the Relay admitted that identity to the slot after the grace window. +## Appendix A. Test vectors + +### A.1 Session key and topic derivation + +``` +shared_secret = 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f +PRK = 46bd320605c5a6b6163ab70bc6345b92a5f908e79fe58979c23ebb47d1a5e307 +session_key = f5fb6528771a0f396ac6e5fd52a040b7d8673e927d24267b3bd1c058f004bdc8 +session_topic = 57e6edc4c06f144f320b763378cb0d69ef7fe19af40b2c3903c56f2a5d82f6c1 +``` + +Encoded forms: + +``` +session_key_base64url = 9ftlKHcaDzlqxuX9UqBAt9hnPpJ9JCZ7O9HAWPAEvcg +session_topic_base64url = V-btxMBvFE8yC3YzeMsNae9_4Zr0Cyw5A8VvKl2C9sE +``` +