From 341883562f6847295da5b7a1a84acd54ed52a85c Mon Sep 17 00:00:00 2001 From: develicit <16333003+Jeon1691@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:59:54 +0900 Subject: [PATCH] fix(relay): bind room routing to authenticated members per room Pairing tokens are issued without authentication for any device ID, yet pairing sockets were inserted into the device-keyed connection map. A caller could open a pairing that named an existing member's device ID, take over that member's room route, and remove it again on disconnect. - Keep pairing sockets out of room routing; they route only through their session's pairing senders and cannot send room traffic. - Key member routes and queued text by (room ID, device ID). - Give each member registration a connection ID; cleanup removes a route only while that registration still owns it. - Check non-revoked membership while holding the room entry, ordered with revocation, which removes the route and closes that socket. - Report clipsync_ws_connections as live authenticated sockets. --- crates/clipsync-relay/src/state.rs | 137 +++- crates/clipsync-relay/src/state_tests.rs | 89 ++- crates/clipsync-relay/src/ws.rs | 88 +-- .../clipsync-relay/src/ws_boundary_tests.rs | 12 +- crates/clipsync-relay/src/ws_tests.rs | 33 +- .../tests/connection_registry.rs | 644 ++++++++++++++++++ docs/assurance-case.md | 2 +- docs/security.md | 19 +- 8 files changed, 934 insertions(+), 90 deletions(-) create mode 100644 crates/clipsync-relay/tests/connection_registry.rs diff --git a/crates/clipsync-relay/src/state.rs b/crates/clipsync-relay/src/state.rs index f687d25..3e792b5 100644 --- a/crates/clipsync-relay/src/state.rs +++ b/crates/clipsync-relay/src/state.rs @@ -3,6 +3,7 @@ use std::collections::HashMap; use std::net::IpAddr; use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::Arc; use std::time::{Duration, Instant}; use chrono::{DateTime, Utc}; @@ -19,13 +20,43 @@ use clipsync_protocol::{ use crate::auth::issue_token; use crate::{JoinError, RelayConfig, WsOut}; +/// Identifies one room-member registration, so a socket's cleanup can retire +/// only the route it installed and never a newer socket's replacement. +pub type ConnectionId = u64; + +/// Device IDs are client-chosen and public (presence frames, webhooks), and +/// one device may belong to several rooms, so member state is keyed per room. +type MemberKey = (String, String); + +fn member_key(room_id: &str, device_id: &str) -> MemberKey { + (room_id.to_string(), device_id.to_string()) +} + +pub(crate) struct MemberRoute { + pub(crate) id: ConnectionId, + pub(crate) sender: mpsc::Sender, +} + +/// Counts one authenticated socket, pairing or room member, until dropped. +pub(crate) struct LiveConnection(Arc); + +impl Drop for LiveConnection { + fn drop(&mut self) { + self.0.fetch_sub(1, Ordering::Relaxed); + } +} + pub struct RelayState { pub config: RelayConfig, pairing_by_code: DashMap, pairing_by_id: DashMap, rooms: DashMap, - pub connections: DashMap>, - queue: DashMap)>, + // Only sockets authenticated with a device token for a non-revoked room + // member are routed here. Pairing sockets route via `pairing_senders`. + pub(crate) member_routes: DashMap, + next_connection_id: AtomicU64, + live_connections: Arc, + queue: DashMap)>, ip_fails: DashMap, pub connections_total: AtomicU64, pub frames_forwarded: AtomicU64, @@ -70,7 +101,9 @@ impl RelayState { pairing_by_code: DashMap::new(), pairing_by_id: DashMap::new(), rooms: DashMap::new(), - connections: DashMap::new(), + member_routes: DashMap::new(), + next_connection_id: AtomicU64::new(0), + live_connections: Arc::new(AtomicU64::new(0)), queue: DashMap::new(), ip_fails: DashMap::new(), connections_total: AtomicU64::new(0), @@ -332,13 +365,51 @@ impl RelayState { self.rooms.get_mut(id) } - pub fn register_conn(&self, device_id: &str, tx: mpsc::Sender) { - self.connections.insert(device_id.to_string(), tx); + pub(crate) fn live_connection(&self) -> LiveConnection { + self.live_connections.fetch_add(1, Ordering::Relaxed); + LiveConnection(self.live_connections.clone()) + } + + /// Routes room traffic for `device_id` in `room_id` to `tx`, replacing any + /// older socket of the same member. Only non-revoked members qualify. + pub fn register_conn( + &self, + room_id: &str, + device_id: &str, + tx: mpsc::Sender, + ) -> Result { + // Holding the room entry orders this insert with `revoke`, which + // removes the route under the same entry's write lock. + let room = self.rooms.get(room_id).ok_or("unknown room")?; + let device = room.devices.get(device_id).ok_or("unknown device")?; + if device.revoked { + return Err("device revoked"); + } + let id = self.next_connection_id.fetch_add(1, Ordering::Relaxed); + self.member_routes.insert( + member_key(room_id, device_id), + MemberRoute { id, sender: tx }, + ); + drop(room); self.connections_total.fetch_add(1, Ordering::Relaxed); + Ok(id) } - pub fn unregister_conn(&self, device_id: &str) { - self.connections.remove(device_id); + /// Removes the member route only if registration `id` still owns it. + pub fn unregister_conn(&self, room_id: &str, device_id: &str, id: ConnectionId) -> bool { + self.member_routes + .remove_if(&member_key(room_id, device_id), |_, route| route.id == id) + .is_some() + } + + pub(crate) fn member_sender( + &self, + room_id: &str, + device_id: &str, + ) -> Option> { + self.member_routes + .get(&member_key(room_id, device_id)) + .map(|route| route.sender.clone()) } pub fn peer_ids(&self, room_id: &str, except: &str) -> Vec { @@ -352,16 +423,24 @@ impl RelayState { .collect() } - pub fn is_online(&self, device_id: &str) -> bool { - self.connections.contains_key(device_id) + pub fn is_online(&self, room_id: &str, device_id: &str) -> bool { + self.member_routes + .contains_key(&member_key(room_id, device_id)) } - pub fn queue_text(&self, device_id: &str, env: QueuedEnvelope, expires_at: DateTime) { - self.queue.insert(device_id.to_string(), (env, expires_at)); + pub fn queue_text( + &self, + room_id: &str, + device_id: &str, + env: QueuedEnvelope, + expires_at: DateTime, + ) { + self.queue + .insert(member_key(room_id, device_id), (env, expires_at)); } - pub fn take_queue(&self, device_id: &str) -> Option { - let (_, (env, exp)) = self.queue.remove(device_id)?; + pub fn take_queue(&self, room_id: &str, device_id: &str) -> Option { + let (_, (env, exp)) = self.queue.remove(&member_key(room_id, device_id))?; if exp < Utc::now() { self.expired.fetch_add(1, Ordering::Relaxed); None @@ -371,17 +450,25 @@ impl RelayState { } pub fn revoke(&self, room_id: &str, device_id: &str) -> bool { - let Some(mut room) = self.rooms.get_mut(room_id) else { - return false; - }; - if let Some(dev) = room.devices.get_mut(device_id) { - dev.revoked = true; - self.connections.remove(device_id); - room.epoch += 1; - true - } else { - false - } + self.revoke_member(room_id, device_id).is_some() + } + + /// Revokes a room member and removes its route. `None` means the device is + /// not a member; otherwise the removed socket, if any, is returned so the + /// caller can close exactly the connection that lost its route. + pub(crate) fn revoke_member( + &self, + room_id: &str, + device_id: &str, + ) -> Option>> { + let mut room = self.rooms.get_mut(room_id)?; + room.devices.get_mut(device_id)?.revoked = true; + room.epoch += 1; + Some( + self.member_routes + .remove(&member_key(room_id, device_id)) + .map(|(_, route)| route.sender), + ) } pub fn gc(&self) { @@ -401,7 +488,7 @@ impl RelayState { pub fn metrics_text(&self) -> String { format!( "clipsync_ws_connections {}\nclipsync_frames_forwarded {}\nclipsync_pairing_ok {}\nclipsync_pairing_fail {}\nclipsync_expired {}\n", - self.connections.len(), + self.live_connections.load(Ordering::Relaxed), self.frames_forwarded.load(Ordering::Relaxed), self.pairing_ok.load(Ordering::Relaxed), self.pairing_fail.load(Ordering::Relaxed), diff --git a/crates/clipsync-relay/src/state_tests.rs b/crates/clipsync-relay/src/state_tests.rs index 8423c94..6c54196 100644 --- a/crates/clipsync-relay/src/state_tests.rs +++ b/crates/clipsync-relay/src/state_tests.rs @@ -108,6 +108,7 @@ fn failed_join_rate_limit_resets_after_its_window_and_abort_removes_the_code() { #[test] fn queue_expiry_discards_only_expired_envelopes_and_gc_counts_them() { let (state, offer, _, owner) = fixture(); + let room = offer.room_id.to_string(); let now = Utc::now(); let routing = RoutingHeader { version: clipsync_protocol::PROTOCOL_VERSION, @@ -127,23 +128,105 @@ fn queue_expiry_discards_only_expired_envelopes_and_gc_counts_them() { ciphertext: "opaque".into(), }; state.queue_text( + &room, "expired-on-read", envelope.clone(), now - chrono::Duration::seconds(1), ); - assert!(state.take_queue("expired-on-read").is_none()); + assert!(state.take_queue(&room, "expired-on-read").is_none()); state.queue_text( + &room, "expired-on-gc", envelope.clone(), now - chrono::Duration::seconds(1), ); state.queue_text( + &room, "fresh", envelope.clone(), now + chrono::Duration::seconds(60), ); state.gc(); - assert!(state.take_queue("expired-on-gc").is_none()); - assert_eq!(state.take_queue("fresh"), Some(envelope)); + assert!(state.take_queue(&room, "expired-on-gc").is_none()); + assert_eq!(state.take_queue(&room, "fresh"), Some(envelope)); assert_eq!(state.expired.load(Ordering::Relaxed), 2); } + +fn paired_room() -> (RelayState, String, String, String) { + let (state, offer, sid, owner) = fixture(); + let member = DeviceId::new(); + state + .join_pairing( + join(&offer.pairing_code, member.clone()), + "127.0.0.1".parse().unwrap(), + ) + .unwrap(); + assert!(state.complete_pairing(sid.as_str()).is_none()); + let (_, _, room_id, _, _) = state.complete_pairing(sid.as_str()).unwrap(); + ( + state, + room_id.to_string(), + owner.to_string(), + member.to_string(), + ) +} + +#[test] +fn stale_connection_cleanup_cannot_remove_a_newer_member_route() { + let (state, room, _, member) = paired_room(); + let (old_tx, _old_rx) = mpsc::channel(1); + let (new_tx, _new_rx) = mpsc::channel(1); + let old = state.register_conn(&room, &member, old_tx).unwrap(); + let new = state.register_conn(&room, &member, new_tx.clone()).unwrap(); + assert_ne!(old, new); + + assert!(!state.unregister_conn(&room, &member, old)); + assert!(state + .member_sender(&room, &member) + .unwrap() + .same_channel(&new_tx)); + assert!(state.is_online(&room, &member)); + + assert!(state.unregister_conn(&room, &member, new)); + assert!(!state.is_online(&room, &member)); + assert!(!state.unregister_conn(&room, &member, new)); +} + +#[test] +fn member_routes_require_a_live_membership_and_are_scoped_per_room() { + let (state, room, owner, member) = paired_room(); + let (tx, _rx) = mpsc::channel(1); + assert_eq!( + state.register_conn(&RoomId::new().to_string(), &member, tx.clone()), + Err("unknown room") + ); + assert_eq!( + state.register_conn(&room, &DeviceId::new().to_string(), tx.clone()), + Err("unknown device") + ); + assert!(state.member_routes.is_empty()); + + state.register_conn(&room, &member, tx.clone()).unwrap(); + assert!(state.is_online(&room, &member)); + assert!(!state.is_online(&RoomId::new().to_string(), &member)); + assert!(!state.is_online(&room, &owner)); +} + +#[test] +fn revocation_drops_the_route_returns_its_socket_and_blocks_reregistration() { + let (state, room, _, member) = paired_room(); + let (tx, _rx) = mpsc::channel(1); + state.register_conn(&room, &member, tx.clone()).unwrap(); + + let removed = state.revoke_member(&room, &member).unwrap().unwrap(); + assert!(removed.same_channel(&tx)); + assert!(!state.is_online(&room, &member)); + assert_eq!( + state.register_conn(&room, &member, tx), + Err("device revoked") + ); + assert!(state + .revoke_member(&room, &DeviceId::new().to_string()) + .is_none()); + assert!(!state.revoke(&RoomId::new().to_string(), &member)); +} diff --git a/crates/clipsync-relay/src/ws.rs b/crates/clipsync-relay/src/ws.rs index 52728fb..56282b0 100644 --- a/crates/clipsync-relay/src/ws.rs +++ b/crates/clipsync-relay/src/ws.rs @@ -18,6 +18,7 @@ use clipsync_protocol::{ }; use crate::auth::verify_token; +use crate::state::{ConnectionId, LiveConnection}; use crate::RelayState; #[derive(Clone, Debug)] @@ -48,6 +49,9 @@ struct ConnCtx { pairing_sid: Option, device_role: DeviceRole, pairing_side: Option, + // Set only for device-token sockets that own a room-member route. + member_conn: Option, + _live: LiveConnection, } // A protocol-v1 Ed25519 SPAKE message is 33 bytes (44 in base64). Retain only @@ -101,8 +105,11 @@ fn register_pairing_connection( if session.pairing_senders[side].is_some() { session.pending_spake = [None, None]; } - state.register_conn(&conn.device_id, tx.clone()); + // Pairing tokens are issued without authentication for any device ID, so + // a pairing socket is routed only within its session and never becomes a + // room-member route. session.pairing_senders[side] = Some(tx.clone()); + state.connections_total.fetch_add(1, Ordering::Relaxed); conn.pairing_side = Some(side); let peer_online = session.pairing_senders[1 - side] .as_ref() @@ -173,7 +180,8 @@ async fn handle_socket(socket: WebSocket, state: Arc, token_q: Optio } } Message::Binary(b) => { - if let Some(c) = &ctx { + // Like frames before hello, pairing-socket binary is dropped. + if let Ok(c) = member_ctx(&ctx) { forward_binary(&state, c, b.to_vec(), &tx).await; } } @@ -186,10 +194,17 @@ async fn handle_socket(socket: WebSocket, state: Arc, token_q: Optio } } + // `c` (and its live-connection count) is dropped only after any leave + // notice is queued, so observers of the metric also see that notice. if let Some(c) = ctx { - state - .connections - .remove_if(&c.device_id, |_, sender| sender.same_channel(&tx)); + if let Some(id) = c.member_conn { + state.unregister_conn(&c.room_id, &c.device_id, id); + // A replacement may already own this member's routing entry. Its + // peers must stay online when the superseded socket finishes closing. + if !state.is_online(&c.room_id, &c.device_id) { + notify_peers_left(&state, &c).await; + } + } if let (Some(sid), Some(side)) = (&c.pairing_sid, c.pairing_side) { if let Some(mut session) = state.pairing_mut(sid) { if session.pairing_senders[side] @@ -201,16 +216,21 @@ async fn handle_socket(socket: WebSocket, state: Arc, token_q: Optio } } } - // A replacement may already own this device's routing entry. Its - // peers must stay online when the superseded socket finishes closing. - if !state.is_online(&c.device_id) { - notify_peers_left(&state, &c).await; - } } let _ = tx.send(WsOut::Close).await; let _ = writer.await; } +/// Room traffic needs a device-token member connection. Pairing tokens are +/// issued without authentication and are confined to their pairing session. +fn member_ctx(ctx: &Option) -> Result<&ConnCtx, String> { + let c = ctx.as_ref().ok_or("hello required")?; + if c.member_conn.is_none() { + return Err("room member connection required".into()); + } + Ok(c) +} + fn message_rate_exceeded(last: &mut Instant, burst: &mut u32, now: Instant) -> bool { if now.duration_since(*last) < Duration::from_millis(20) { *burst += 1; @@ -278,14 +298,9 @@ async fn handle_control( }, device_role: claims.role, pairing_side: None, + member_conn: None, + _live: state.live_connection(), }; - if claims.typ != "pair" { - let room = state.room(&conn.room_id).ok_or("unknown room")?; - let device = room.devices.get(&conn.device_id).ok_or("unknown device")?; - if device.revoked { - return Err("device revoked".into()); - } - } if claims.typ == "pair" { let arrival = register_pairing_connection(state, &mut conn, tx, role)?; let hello_ok = ControlMessage::HelloOk { @@ -303,19 +318,19 @@ async fn handle_control( send_msg(tx, &pending).await; } } else { - state.register_conn(&conn.device_id, tx.clone()); + conn.member_conn = + Some(state.register_conn(&conn.room_id, &conn.device_id, tx.clone())?); let peers: Vec = state .peer_ids(&conn.room_id, &conn.device_id) .into_iter() .filter_map(|id| { - let room = state.room(&conn.room_id)?; - let mut info = room.devices.get(&id)?.info.clone(); - info.online = state.is_online(&id); + let mut info = state.room(&conn.room_id)?.devices.get(&id)?.info.clone(); + info.online = state.is_online(&conn.room_id, &id); Some(info) }) .collect(); let peer_online = peers.iter().any(|p| p.online); - let queued = state.take_queue(&conn.device_id); + let queued = state.take_queue(&conn.room_id, &conn.device_id); let hello_ok = ControlMessage::HelloOk { room_id: claims.rid.clone(), peer_online, @@ -362,7 +377,7 @@ async fn handle_control( nonce, ciphertext, } => { - let c = ctx.as_ref().ok_or("hello required")?; + let c = member_ctx(ctx)?; if routing.item_kind != ItemKind::Text { return Err("text envelope item_kind mismatch".into()); } @@ -387,7 +402,7 @@ async fn handle_control( ciphertext: ciphertext.clone(), }; for peer in &peers { - if let Some(p) = state.connections.get(peer) { + if let Some(p) = state.member_sender(&c.room_id, peer) { any_online = true; if let Ok(s) = env.encode() { let _ = p.send(WsOut::Text(s)).await; @@ -395,6 +410,7 @@ async fn handle_control( } } else { state.queue_text( + &c.room_id, peer, QueuedEnvelope { routing: routing.clone(), @@ -431,11 +447,11 @@ async fn handle_control( Ok(()) } ControlMessage::Manifest { ref routing, .. } => { - let c = ctx.as_ref().ok_or("hello required")?; + let c = member_ctx(ctx)?; let peers = state.peer_ids(&c.room_id, &c.device_id); let online: Vec<_> = peers .iter() - .filter(|p| state.is_online(p)) + .filter(|p| state.is_online(&c.room_id, p)) .cloned() .collect(); if online.is_empty() { @@ -465,24 +481,20 @@ async fn handle_control( Ok(()) } ControlMessage::Ack { .. } | ControlMessage::EpochWrapMsg { .. } => { - let c = ctx.as_ref().ok_or("hello required")?; + let c = member_ctx(ctx)?; fanout_except(state, &c.room_id, &c.device_id, &msg).await; Ok(()) } ControlMessage::Revoke { ref device_id } => { - let c = ctx.as_ref().ok_or("hello required")?; + let c = member_ctx(ctx)?; if c.device_role != DeviceRole::Owner { return Err("manage permission required".into()); } - // Revoke removes the routing entry. Keep the sender long enough - // to close the authenticated socket after invalidating its device. + // Revoke removes the routing entry and hands back that socket's + // sender, so the connection that lost its route is the one closed. let revoked_connection = state - .connections - .get(device_id.as_str()) - .map(|connection| connection.value().clone()); - if !state.revoke(&c.room_id, device_id.as_str()) { - return Err("device not found".into()); - } + .revoke_member(&c.room_id, device_id.as_str()) + .ok_or("device not found")?; fanout_except(state, &c.room_id, &c.device_id, &msg).await; if let Some(p) = revoked_connection { let _ = p.send(WsOut::Close).await; @@ -616,7 +628,7 @@ async fn forward_binary( let peers = state.peer_ids(&c.room_id, &c.device_id); let mut sent = false; for peer in peers { - if let Some(p) = state.connections.get(&peer) { + if let Some(p) = state.member_sender(&c.room_id, &peer) { let _ = p.send(WsOut::Binary(bytes.clone())).await; state.frames_forwarded.fetch_add(1, Ordering::Relaxed); sent = true; @@ -636,7 +648,7 @@ async fn forward_binary( async fn fanout_except(state: &Arc, room_id: &str, except: &str, msg: &ControlMessage) { if let Ok(s) = msg.encode() { for peer in state.peer_ids(room_id, except) { - if let Some(p) = state.connections.get(&peer) { + if let Some(p) = state.member_sender(room_id, &peer) { let _ = p.send(WsOut::Text(s.clone())).await; state.frames_forwarded.fetch_add(1, Ordering::Relaxed); } diff --git a/crates/clipsync-relay/src/ws_boundary_tests.rs b/crates/clipsync-relay/src/ws_boundary_tests.rs index 18f94f2..5adb794 100644 --- a/crates/clipsync-relay/src/ws_boundary_tests.rs +++ b/crates/clipsync-relay/src/ws_boundary_tests.rs @@ -23,6 +23,8 @@ fn pending_pairing(state: &RelayState) -> (PairingSessionId, ConnCtx) { pairing_sid: Some(sid.to_string()), device_role: DeviceRole::Owner, pairing_side: None, + member_conn: None, + _live: state.live_connection(), }, ) } @@ -55,7 +57,6 @@ async fn pairing_registration_rejects_wrong_room_completion_and_identity_without .expect("invalid admission was accepted"); assert_eq!(error, expected, "{case}"); assert!(ctx.pairing_side.is_none(), "{case}"); - assert!(state.connections.is_empty(), "{case}"); assert!(rx.try_recv().is_err(), "{case}"); assert!(state .pairing(sid.as_str()) @@ -153,11 +154,10 @@ async fn repeated_hello_cannot_switch_authenticated_identity_or_replace_its_rout assert_eq!(ctx.as_ref().unwrap().device_id, owner.as_str()); assert_eq!(ctx.as_ref().unwrap().device_role, DeviceRole::Owner); assert!(state - .connections - .get(owner.as_str()) + .member_sender(rid.as_str(), owner.as_str()) .unwrap() .same_channel(&tx)); - assert!(!state.is_online(member.as_str())); + assert!(!state.is_online(rid.as_str(), member.as_str())); assert!(rx.try_recv().is_err()); } @@ -183,7 +183,7 @@ async fn revoking_an_offline_member_and_reporting_client_errors_preserve_the_own .await .unwrap(); assert!(state.room(rid.as_str()).unwrap().devices[member.as_str()].revoked); - assert!(state.is_online(owner.as_str())); + assert!(state.is_online(rid.as_str(), owner.as_str())); for authenticated in [false, true] { let error = ControlMessage::Error { code: "client-report".into(), @@ -198,7 +198,7 @@ async fn revoking_an_offline_member_and_reporting_client_errors_preserve_the_own .await .unwrap(); } - assert!(state.is_online(owner.as_str())); + assert!(state.is_online(rid.as_str(), owner.as_str())); assert!(state.room(rid.as_str()).is_some()); } handle_control(&state, &tx, &mut ctx, ControlMessage::Ping { ts: 77 }, None) diff --git a/crates/clipsync-relay/src/ws_tests.rs b/crates/clipsync-relay/src/ws_tests.rs index d2d9f21..47b29d8 100644 --- a/crates/clipsync-relay/src/ws_tests.rs +++ b/crates/clipsync-relay/src/ws_tests.rs @@ -64,17 +64,17 @@ async fn regression_f98_stale_room_socket_close_does_not_announce_live_replaceme let mut peer = connect(address, &member, &rid, &member_token).await; let mut old = connect(address, &owner, &rid, &owner_token).await; assert!(matches!(control(&mut peer).await, ControlMessage::PeerJoined { device } if device.device_id == owner)); - let old_sender = state.connections.get(owner.as_str()).unwrap().value().clone(); + let old_sender = state.member_sender(rid.as_str(), owner.as_str()).unwrap(); let mut current = connect(address, &owner, &rid, &owner_token).await; assert!(matches!(control(&mut peer).await, ControlMessage::PeerJoined { device } if device.device_id == owner)); - let current_sender = state.connections.get(owner.as_str()).unwrap().value().clone(); + let current_sender = state.member_sender(rid.as_str(), owner.as_str()).unwrap(); assert!(!old_sender.same_channel(¤t_sender)); old.close(None).await.unwrap(); // The old writer's receiver closes only after its socket cleanup has // queued any leave notification and sent its Close. No blind delay. old_sender.closed().await; - assert!(state.connections.get(owner.as_str()).unwrap().same_channel(¤t_sender)); + assert!(state.member_sender(rid.as_str(), owner.as_str()).unwrap().same_channel(¤t_sender)); peer.send(ClientMessage::Text(ControlMessage::Ping { ts: 9801 }.encode().unwrap().into())).await.unwrap(); assert!(matches!(control(&mut peer).await, ControlMessage::Pong { ts: 9801 }), "a stale socket must not announce a still-live device as offline"); @@ -90,7 +90,7 @@ async fn regression_f98_stale_room_socket_close_does_not_announce_live_replaceme current.close(None).await.unwrap(); current_sender.closed().await; assert!(matches!(control(&mut peer).await, ControlMessage::PeerLeft { device_id } if device_id == owner)); - assert!(!state.is_online(owner.as_str())); + assert!(!state.is_online(rid.as_str(), owner.as_str())); peer.send(ClientMessage::Text(ControlMessage::Ping { ts: 9802 }.encode().unwrap().into())).await.unwrap(); assert!(matches!(control(&mut peer).await, ControlMessage::Pong { ts: 9802 }), "retiring the current socket must announce exactly one leave"); @@ -367,7 +367,7 @@ async fn control_messages_require_hello_and_revoke_requires_the_owner() { .await .unwrap(); assert!(state.room(rid.as_str()).unwrap().devices[member.as_str()].revoked); - assert!(!state.is_online(member.as_str())); + assert!(!state.is_online(rid.as_str(), member.as_str())); } #[tokio::test] @@ -384,7 +384,7 @@ async fn text_queues_offline_but_binary_requires_an_online_peer() { version: clipsync_protocol::PROTOCOL_VERSION, message_id: MessageId::new(), transfer_id: TransferId::new(), - room_id: rid, + room_id: rid.clone(), sender_device_id: owner, recipient: Recipient::Broadcast, sent_at: chrono::Utc::now(), @@ -408,7 +408,10 @@ async fn text_queues_offline_but_binary_requires_an_online_peer() { } )); assert_eq!( - state.take_queue(member.as_str()).unwrap().ciphertext, + state + .take_queue(rid.as_str(), member.as_str()) + .unwrap() + .ciphertext, "opaque-ciphertext" ); let manifest = ControlMessage::Manifest { @@ -438,7 +441,9 @@ async fn text_queues_offline_but_binary_requires_an_online_peer() { } )); let (peer_tx, mut peer_rx) = mpsc::channel(32); - state.register_conn(member.as_str(), peer_tx); + state + .register_conn(rid.as_str(), member.as_str(), peer_tx) + .unwrap(); handle_control(&state, &tx, &mut ctx, envelope, None) .await .unwrap(); @@ -931,7 +936,7 @@ async fn regression_f88_revocation_closes_the_registered_socket_before_discardin ), "revoked socket was removed from routing without being told to close" ); - assert!(!state.is_online(member.as_str())); + assert!(!state.is_online(rid.as_str(), member.as_str())); let room = state.room(rid.as_str()).unwrap(); assert!(room.devices[member.as_str()].revoked); assert!(!room.devices[owner.as_str()].revoked); @@ -950,10 +955,10 @@ async fn regression_f88_revocation_closes_the_registered_socket_before_discardin "device revoked" ); assert!( - !state.is_online(member.as_str()), + !state.is_online(rid.as_str(), member.as_str()), "rejected credentials were re-registered as an online device" ); - assert!(state.take_queue(owner.as_str()).is_none()); + assert!(state.take_queue(rid.as_str(), owner.as_str()).is_none()); } #[tokio::test] @@ -1042,7 +1047,7 @@ async fn regression_f88_revoked_network_peer_is_closed_cannot_send_and_cannot_re .await .is_err()); assert_eq!(state.frames_forwarded.load(Ordering::Relaxed), forwarded); - assert!(state.take_queue(owner.as_str()).is_none()); + assert!(state.take_queue(rid.as_str(), owner.as_str()).is_none()); let (mut rejected, _) = tokio_tungstenite::connect_async(&url).await.unwrap(); rejected .send(ClientMessage::Text( @@ -1061,7 +1066,7 @@ async fn regression_f88_revoked_network_peer_is_closed_cannot_send_and_cannot_re assert!( matches!(ControlMessage::decode(&text).unwrap(), ControlMessage::Error { message, .. } if message == "device revoked") ); - assert!(!state.is_online(member.as_str())); + assert!(!state.is_online(rid.as_str(), member.as_str())); assert_eq!(state.connections_total.load(Ordering::Relaxed), 2); owner_socket .send(ClientMessage::Text( @@ -1365,7 +1370,7 @@ async fn regression_f98_expiry_discards_pending_spake_and_prevents_admission_or_ .unwrap_err(), "pairing expired" ); - assert!(!state.is_online(owner.as_str())); + assert!(state.pairing(sid.as_str()).unwrap().pairing_senders[0].is_none()); assert!(owner_rx.try_recv().is_err()); assert!(state .complete_pairing_bound(sid.as_str(), Some(offer.room_id.as_str())) diff --git a/crates/clipsync-relay/tests/connection_registry.rs b/crates/clipsync-relay/tests/connection_registry.rs new file mode 100644 index 0000000..c34b5e4 --- /dev/null +++ b/crates/clipsync-relay/tests/connection_registry.rs @@ -0,0 +1,644 @@ +// Copyright the ClipSync contributors. +// SPDX-License-Identifier: MIT +//! Room routing belongs to authenticated members, is scoped to one room, and +//! is owned by exactly one socket at a time. + +use chrono::Utc; +use clipsync_protocol::{ + AckStatus, ClientRole, ControlMessage, CreatePairingRequest, CreatePairingResponse, DeviceId, + ItemKind, JoinPairingRequest, JoinPairingResponse, MessageId, PairingSessionId, Recipient, + RoomId, RoutingHeader, TransferId, PROTOCOL_VERSION, +}; +use clipsync_relay::{router, RelayConfig}; +use futures_util::{SinkExt, StreamExt}; +use std::net::SocketAddr; +use std::time::Duration; +use tokio_tungstenite::tungstenite::Message; + +type Socket = + tokio_tungstenite::WebSocketStream>; + +// Generous bounds for loopback fixtures; every wait is condition-driven, so +// these only turn a regression into a failure instead of a hang. +const FIXTURE_DEADLINE: Duration = Duration::from_secs(20); +const FRAME_DEADLINE: Duration = Duration::from_secs(3); +const METRICS_POLL: Duration = Duration::from_millis(5); +// Well inside the relay's queue retention, so queued text cannot expire mid-test. +const TEXT_LIFETIME_SECS: i64 = 60; +// The relay forwards nonces opaquely; this is a 12-byte AEAD nonce in hex. +const OPAQUE_NONCE: &str = "000000000000000000000000"; + +struct Relay { + url: String, + client: reqwest::Client, + task: tokio::task::JoinHandle<()>, +} + +impl Drop for Relay { + fn drop(&mut self) { + self.task.abort(); + } +} + +struct Room { + id: RoomId, + owner: DeviceId, + owner_token: String, + member_token: String, +} + +impl Room { + fn token(&self, device: &DeviceId) -> &str { + if *device == self.owner { + &self.owner_token + } else { + &self.member_token + } + } +} + +impl Relay { + async fn start() -> Self { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let url = format!("http://{address}"); + let app = router(RelayConfig { + bind: address, + public_url: url.clone(), + token_secret: vec![73; 32], + webhook_url: None, + webhook_secret: None, + }); + let task = tokio::spawn(async move { + axum::serve( + listener, + app.into_make_service_with_connect_info::(), + ) + .await + .unwrap(); + }); + let client = reqwest::Client::builder() + .no_proxy() + .timeout(FRAME_DEADLINE) + .build() + .unwrap(); + Self { url, client, task } + } + + /// `/v1/pairing/create` is unauthenticated: any caller may name any device. + async fn create(&self, owner: &DeviceId) -> (PairingSessionId, CreatePairingResponse) { + let sid = PairingSessionId::new(); + let created = self + .client + .post(format!("{}/v1/pairing/create", self.url)) + .json(&CreatePairingRequest { + pairing_session_id: sid.clone(), + device_id: owner.clone(), + device_name: "registry owner".into(), + os: "fixture".into(), + protocol_version: PROTOCOL_VERSION, + ttl_secs: None, + }) + .send() + .await + .unwrap() + .error_for_status() + .unwrap() + .json() + .await + .unwrap(); + (sid, created) + } + + async fn join(&self, code: &str, member: &DeviceId) -> JoinPairingResponse { + self.client + .post(format!("{}/v1/pairing/join", self.url)) + .json(&JoinPairingRequest { + pairing_code: code.into(), + device_id: member.clone(), + device_name: "registry member".into(), + os: "fixture".into(), + protocol_version: PROTOCOL_VERSION, + }) + .send() + .await + .unwrap() + .error_for_status() + .unwrap() + .json() + .await + .unwrap() + } + + async fn socket(&self, hello: ControlMessage) -> Socket { + let (mut socket, _) = tokio::time::timeout( + FRAME_DEADLINE, + tokio_tungstenite::connect_async(format!( + "{}/v1/ws", + self.url.replacen("http://", "ws://", 1) + )), + ) + .await + .unwrap() + .unwrap(); + send(&mut socket, hello).await; + socket + } + + /// Completes a real relay pairing, then closes both pairing sockets and + /// waits until `settled` authenticated sockets remain. + async fn pair(&self, owner: &DeviceId, member: &DeviceId, settled: Option) -> Room { + let (room, mut creator, mut joiner) = self.pair_open(owner, member).await; + creator.close(None).await.unwrap(); + joiner.close(None).await.unwrap(); + if let Some(settled) = settled { + self.connections(settled).await; + } + room + } + + /// Completes a real relay pairing and keeps both pairing sockets open. + async fn pair_open(&self, owner: &DeviceId, member: &DeviceId) -> (Room, Socket, Socket) { + let (sid, created) = self.create(owner).await; + let joined = self.join(&created.pairing_code, member).await; + let mut creator = self + .socket(pairing_hello( + owner, + ClientRole::PairingA, + &created.room_id, + &created.pairing_token, + &sid, + )) + .await; + until(&mut creator, "creator HelloOk", |m| { + matches!(m, ControlMessage::HelloOk { .. }) + }) + .await; + let mut joiner = self + .socket(pairing_hello( + member, + ClientRole::PairingB, + &joined.room_id, + &joined.pairing_token, + &sid, + )) + .await; + until(&mut joiner, "joiner HelloOk", |m| { + matches!(m, ControlMessage::HelloOk { .. }) + }) + .await; + until(&mut creator, "joiner presence", |m| { + matches!(m, ControlMessage::PeerJoined { .. }) + }) + .await; + let bind = ControlMessage::DeviceBind { + pairing_session_id: sid.clone(), + nonce: OPAQUE_NONCE.into(), + ciphertext: "opaque device binding".into(), + }; + send(&mut creator, bind.clone()).await; + send(&mut joiner, bind).await; + let owner_token = pairing_token(&mut creator).await; + let member_token = pairing_token(&mut joiner).await; + let room = Room { + id: created.room_id, + owner: owner.clone(), + owner_token, + member_token, + }; + (room, creator, joiner) + } + + /// Connects an established-room device and returns its `HelloOk`. + async fn member(&self, room: &Room, device: &DeviceId) -> (Socket, ControlMessage) { + let mut socket = self + .socket(ControlMessage::Hello { + protocol_version: PROTOCOL_VERSION, + device_id: device.clone(), + device_name: "registry device".into(), + os: "fixture".into(), + role: ClientRole::Member, + room_id: Some(room.id.clone()), + token: room.token(device).into(), + pairing_session_id: None, + }) + .await; + let hello_ok = until(&mut socket, "member HelloOk", |m| { + matches!(m, ControlMessage::HelloOk { .. }) + }) + .await; + (socket, hello_ok) + } + + async fn connections(&self, expected: usize) { + let line = format!("clipsync_ws_connections {expected}"); + tokio::time::timeout(FRAME_DEADLINE, async { + loop { + let metrics = self + .client + .get(format!("{}/metrics", self.url)) + .send() + .await + .unwrap() + .text() + .await + .unwrap(); + if metrics.lines().any(|candidate| candidate == line) { + break; + } + tokio::time::sleep(METRICS_POLL).await; + } + }) + .await + .unwrap_or_else(|_| panic!("relay did not reach `{line}`")); + } +} + +fn pairing_hello( + device: &DeviceId, + role: ClientRole, + room: &RoomId, + token: &str, + sid: &PairingSessionId, +) -> ControlMessage { + ControlMessage::Hello { + protocol_version: PROTOCOL_VERSION, + device_id: device.clone(), + device_name: "registry pairing".into(), + os: "fixture".into(), + role, + room_id: Some(room.clone()), + token: token.into(), + pairing_session_id: Some(sid.clone()), + } +} + +fn text(room: &RoomId, sender: &DeviceId, ciphertext: &str) -> ControlMessage { + let sent_at = Utc::now(); + ControlMessage::TextEnvelope { + routing: RoutingHeader { + version: PROTOCOL_VERSION, + message_id: MessageId::new(), + transfer_id: TransferId::new(), + room_id: room.clone(), + sender_device_id: sender.clone(), + recipient: Recipient::Broadcast, + sent_at, + expires_at: sent_at + chrono::Duration::seconds(TEXT_LIFETIME_SECS), + item_kind: ItemKind::Text, + seq: 1, + }, + nonce: OPAQUE_NONCE.into(), + ciphertext: ciphertext.into(), + } +} + +async fn send(socket: &mut Socket, message: ControlMessage) { + socket + .send(Message::Text(message.encode().unwrap().into())) + .await + .unwrap(); +} + +async fn next_control(socket: &mut Socket) -> Option { + loop { + match socket.next().await? { + Ok(Message::Text(text)) => return Some(ControlMessage::decode(&text).unwrap()), + Ok(Message::Ping(bytes)) => socket.send(Message::Pong(bytes)).await.unwrap(), + Ok(Message::Close(_)) | Err(_) => return None, + Ok(_) => {} + } + } +} + +/// Reads until `wanted` matches, skipping unrelated control frames. +async fn until( + socket: &mut Socket, + what: &str, + wanted: impl Fn(&ControlMessage) -> bool, +) -> ControlMessage { + tokio::time::timeout(FRAME_DEADLINE, async { + loop { + match next_control(socket).await { + Some(message) if wanted(&message) => return message, + Some(_) => {} + None => panic!("socket closed before {what}"), + } + } + }) + .await + .unwrap_or_else(|_| panic!("{what} was not delivered")) +} + +/// Everything the relay queued for this socket before it answers `ts`. +async fn drain_to_pong(socket: &mut Socket, ts: i64) -> Vec { + send(socket, ControlMessage::Ping { ts }).await; + let mut before = Vec::new(); + tokio::time::timeout(FRAME_DEADLINE, async { + loop { + match next_control(socket).await { + Some(ControlMessage::Pong { ts: received }) if received == ts => return, + Some(message) => before.push(message), + None => panic!("socket closed before pong {ts}"), + } + } + }) + .await + .unwrap_or_else(|_| panic!("pong {ts} was not delivered")); + before +} + +async fn pairing_token(socket: &mut Socket) -> String { + match until(socket, "PairingComplete", |m| { + matches!(m, ControlMessage::PairingComplete { .. }) + }) + .await + { + ControlMessage::PairingComplete { device_token, .. } => device_token, + _ => unreachable!("filtered by until"), + } +} + +fn ack_status(message: &ControlMessage) -> Option { + match message { + ControlMessage::Ack { status, .. } => Some(*status), + _ => None, + } +} + +async fn text_ack(socket: &mut Socket) -> AckStatus { + let ack = until(socket, "sender Ack", |m| ack_status(m).is_some()).await; + ack_status(&ack).unwrap() +} + +fn ciphertext(message: &ControlMessage) -> Option<&str> { + match message { + ControlMessage::TextEnvelope { ciphertext, .. } => Some(ciphertext), + _ => None, + } +} + +async fn received_text(socket: &mut Socket, what: &str) -> String { + let envelope = until(socket, what, |m| ciphertext(m).is_some()).await; + ciphertext(&envelope).unwrap().to_owned() +} + +fn assert_no_text(frames: &[ControlMessage], who: &str) { + assert!( + frames.iter().all(|frame| ciphertext(frame).is_none()), + "{who} must not receive room text: {frames:?}" + ); +} + +fn assert_not_left(frames: &[ControlMessage], device: &DeviceId) { + assert!( + !frames.iter().any( + |frame| matches!(frame, ControlMessage::PeerLeft { device_id } if device_id == device) + ), + "a live member must not be announced as left: {frames:?}" + ); +} + +/// Sends room text from `sender` and requires live delivery to `recipient`. +async fn assert_live_delivery( + room: &Room, + sender_id: &DeviceId, + sender: &mut Socket, + recipient: &mut Socket, + marker: &str, +) { + send(sender, text(&room.id, sender_id, marker)).await; + assert_eq!(text_ack(sender).await, AckStatus::Delivered); + assert_eq!(received_text(recipient, marker).await, marker); +} + +#[tokio::test] +async fn pairing_token_for_a_member_device_id_cannot_take_over_its_room_route() { + tokio::time::timeout(FIXTURE_DEADLINE, async { + let relay = Relay::start().await; + let (owner, member) = (DeviceId::new(), DeviceId::new()); + let room = relay.pair(&owner, &member, Some(0)).await; + let (mut owner_socket, _) = relay.member(&room, &owner).await; + let (mut member_socket, _) = relay.member(&room, &member).await; + until( + &mut owner_socket, + "member presence", + |m| matches!(m, ControlMessage::PeerJoined { device } if device.device_id == member), + ) + .await; + + // Device IDs are public (PeerJoined, webhooks). Anyone can open an + // unauthenticated pairing that names the member's device ID. + let (sid, attack) = relay.create(&member).await; + let mut attacker = relay + .socket(pairing_hello( + &member, + ClientRole::PairingA, + &attack.room_id, + &attack.pairing_token, + &sid, + )) + .await; + // HelloOk is sent only after the socket is registered. + until(&mut attacker, "attacker HelloOk", |m| { + matches!(m, ControlMessage::HelloOk { .. }) + }) + .await; + + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut member_socket, + "owner-to-member while pairing socket is open", + ) + .await; + assert_no_text(&drain_to_pong(&mut attacker, 1).await, "pairing socket"); + + attacker.close(None).await.unwrap(); + relay.connections(2).await; + assert_not_left(&drain_to_pong(&mut owner_socket, 2).await, &member); + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut member_socket, + "owner-to-member after pairing socket closed", + ) + .await; + }) + .await + .expect("pairing-token hijack fixture exceeded its deadline"); +} + +#[tokio::test] +async fn same_device_id_in_another_room_cannot_shadow_a_member_route() { + tokio::time::timeout(FIXTURE_DEADLINE, async { + let relay = Relay::start().await; + let (owner, member, accomplice) = (DeviceId::new(), DeviceId::new(), DeviceId::new()); + let room = relay.pair(&owner, &member, Some(0)).await; + let (mut owner_socket, _) = relay.member(&room, &owner).await; + let (mut member_socket, _) = relay.member(&room, &member).await; + until( + &mut owner_socket, + "member presence", + |m| matches!(m, ControlMessage::PeerJoined { device } if device.device_id == member), + ) + .await; + + // A fully authenticated device token, but for a room the attacker + // created under the victim's device ID. + let attack_room = relay.pair(&member, &accomplice, None).await; + let (mut shadow, _) = relay.member(&attack_room, &member).await; + + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut member_socket, + "owner-to-member while shadow is online", + ) + .await; + assert_no_text(&drain_to_pong(&mut shadow, 1).await, "other-room device"); + + shadow.close(None).await.unwrap(); + relay.connections(2).await; + assert_not_left(&drain_to_pong(&mut owner_socket, 2).await, &member); + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut member_socket, + "owner-to-member after shadow closed", + ) + .await; + }) + .await + .expect("cross-room shadow fixture exceeded its deadline"); +} + +#[tokio::test] +async fn queued_text_for_a_device_id_is_scoped_to_its_room() { + tokio::time::timeout(FIXTURE_DEADLINE, async { + let relay = Relay::start().await; + let (owner, member, accomplice) = (DeviceId::new(), DeviceId::new(), DeviceId::new()); + let room = relay.pair(&owner, &member, Some(0)).await; + let attack_room = relay.pair(&member, &accomplice, Some(0)).await; + + let (mut owner_socket, _) = relay.member(&room, &owner).await; + send(&mut owner_socket, text(&room.id, &owner, "queued by owner")).await; + assert_eq!(text_ack(&mut owner_socket).await, AckStatus::Accepted); + + let (mut accomplice_socket, _) = relay.member(&attack_room, &accomplice).await; + send( + &mut accomplice_socket, + text(&attack_room.id, &accomplice, "queued by other room"), + ) + .await; + assert_eq!(text_ack(&mut accomplice_socket).await, AckStatus::Accepted); + + let (_member_socket, hello_ok) = relay.member(&room, &member).await; + let ControlMessage::HelloOk { queued_text, .. } = hello_ok else { + unreachable!("filtered by member()") + }; + assert_eq!( + queued_text.map(|queued| queued.ciphertext).as_deref(), + Some("queued by owner"), + "another room must not replace or receive this room's queued text" + ); + }) + .await + .expect("room-scoped queue fixture exceeded its deadline"); +} + +#[tokio::test] +async fn closing_a_superseded_member_socket_keeps_the_newer_route() { + tokio::time::timeout(FIXTURE_DEADLINE, async { + let relay = Relay::start().await; + let (owner, member) = (DeviceId::new(), DeviceId::new()); + let room = relay.pair(&owner, &member, Some(0)).await; + let (mut owner_socket, _) = relay.member(&room, &owner).await; + let (mut superseded, _) = relay.member(&room, &member).await; + let (mut current, _) = relay.member(&room, &member).await; + + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut current, + "owner-to-newest member socket", + ) + .await; + assert_no_text( + &drain_to_pong(&mut superseded, 1).await, + "superseded socket", + ); + + superseded.close(None).await.unwrap(); + relay.connections(2).await; + assert_not_left(&drain_to_pong(&mut owner_socket, 2).await, &member); + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut current, + "owner-to-member after superseded socket closed", + ) + .await; + }) + .await + .expect("superseded member fixture exceeded its deadline"); +} + +#[tokio::test] +async fn pairing_socket_kept_open_after_completion_cannot_send_room_traffic() { + tokio::time::timeout(FIXTURE_DEADLINE, async { + let relay = Relay::start().await; + let (owner, member) = (DeviceId::new(), DeviceId::new()); + let (room, mut creator, mut joiner) = relay.pair_open(&owner, &member).await; + joiner.close(None).await.unwrap(); + let (mut member_socket, _) = relay.member(&room, &member).await; + + // The creator's pairing token names the now-established room, but it + // never authenticated as a room member and revocation cannot close it. + let refused = |m: &ControlMessage| { + matches!(m, ControlMessage::Error { message, .. } if message == "room member connection required") + }; + send(&mut creator, text(&room.id, &owner, "from pairing socket")).await; + until(&mut creator, "text refusal", refused).await; + send(&mut creator, ControlMessage::Revoke { device_id: member.clone() }).await; + until(&mut creator, "revoke refusal", refused).await; + creator + .send(Message::Binary(vec![1, 2, 3].into())) + .await + .unwrap(); + let after_binary = drain_to_pong(&mut creator, 1).await; + assert!( + !after_binary + .iter() + .any(|m| matches!(m, ControlMessage::Ack { .. })), + "pairing-socket binary must be dropped, not routed: {after_binary:?}" + ); + + let member_frames = drain_to_pong(&mut member_socket, 2).await; + assert_no_text(&member_frames, "member"); + assert!( + !member_frames + .iter() + .any(|m| matches!(m, ControlMessage::Revoke { .. })), + "pairing socket must not revoke room members: {member_frames:?}" + ); + let (mut owner_socket, _) = relay.member(&room, &owner).await; + assert_live_delivery( + &room, + &owner, + &mut owner_socket, + &mut member_socket, + "member route intact after pairing-socket attempts", + ) + .await; + creator.close(None).await.unwrap(); + }) + .await + .expect("open pairing socket fixture exceeded its deadline"); +} diff --git a/docs/assurance-case.md b/docs/assurance-case.md index 71300f7..8c798bd 100644 --- a/docs/assurance-case.md +++ b/docs/assurance-case.md @@ -38,7 +38,7 @@ administrators can access local clipboard contents and keys. | User input → CLI/core | Typed command parsing, configuration validation, clipboard item limits; CLI/core smoke and end-to-end tests | | Native clipboard/files → encrypted transfers | Clipboard item checks, protocol size limits, manifest construction; clipboard platform and format-matrix tests | | Untrusted relay/network → transport/core | TLS certificate validation, typed messages, framing/size checks, AEAD authentication, pairing transcript/key confirmation; protocol fuzzing, crypto tests and relay end-to-end tests | -| Client → relay membership/routing | HMAC device token verification, expiry, room/device membership and revocation in relay auth/ws handlers; pairing/revocation/session-bound tests | +| Client → relay membership/routing | HMAC device token verification, expiry, room/device membership and revocation in relay auth/ws handlers; member routes keyed by room and device and owned by one connection, with pairing sockets kept out of room routing; pairing/revocation/session-bound and connection-registry tests | | Remote filename/transfer → local inbox | Allowlisted ULID staging IDs and safe basename rules, size/chunk/hash checks and staging confinement; transfer traversal and file round-trip regressions | | Application → local storage/OS | Private Unix data/inbox directories and secret files, atomic credential writes, separated metadata/secret serialization; storage migration/failure/permission tests. Windows relies on profile ACLs | | Local command → daemon | Per-user local IPC and OS service ownership; native platform tests. This is not a privilege boundary against same-user malware | diff --git a/docs/security.md b/docs/security.md index d56afc2..52b7554 100644 --- a/docs/security.md +++ b/docs/security.md @@ -54,9 +54,22 @@ protocol changes; the current v1 format is retained for existing clients. ## Relay The relay routes opaque ciphertext. It stores at most one latest encrypted text -envelope per recipient in memory for 60 seconds. Image and file frames are -forwarded only while the peer is online and are never assembled or written to -disk. +envelope per recipient device in each room, in memory for 60 seconds. Image and +file frames are forwarded only while the peer is online and are never assembled +or written to disk. + +Room traffic and presence reach only sockets authenticated with a device token +for a current, non-revoked room member, and routes are keyed by room and device +ID. Device IDs are not secret, and the pairing endpoints issue pairing tokens +for any device ID without authentication. A pairing socket therefore exchanges +frames only within its own pairing session; it cannot send room traffic, or +receive, displace or take offline a room member's route, and a device in one +room cannot shadow the same device ID in another room. When a member reconnects, the newest socket owns the +route; cleanup of an older socket removes only the route it installed. +Revocation removes the member's route and closes that socket. Pairing requests +that name a device ID already connected to a room are not rejected: such a +check would reveal presence to unauthenticated callers and stop a device from +pairing into another room, while routing no longer depends on it. Webhooks carry metadata only: opaque IDs, item kind, encrypted size, timestamp, status. Destination checks must include DNS results, IPv4/IPv6 special ranges,