feat(cable): caller-driven teardown and linger for linking data

README.md

@@ -39,6 +39,7 @@ _Looking for the D-Bus API proposal?_ Check out [credentialsd][credentialsd].
   - 🟢 Discoverable credentials (resident keys)
   - 🟢 Hybrid transport (caBLE v2): QR-initiated transactions
   - 🟢 Hybrid transport (caBLE v2): State-assisted transactions (remember this phone)
+  - 🟢 Hybrid transport (caBLE v2): Linger after the ceremony to capture the linking update
   - 🟢 Hybrid transport (CTAP 2.3): direct BLE L2CAP data channel, QR-initiated, no tunnel server
 
 ## Runtime requirements

libwebauthn/Cargo.toml

@@ -120,6 +120,8 @@ reqwest = { version = "0.12", default-features = false, features = [
 [dev-dependencies]
 tracing-subscriber = { version = "0.3.3", features = ["env-filter"] }
 qrcode = "0.14.1"
+# test-util enables paused time for deterministic timeout/linger tests
+tokio = { version = "1.45", features = ["test-util"] }
 # For turning on logging in unittests
 test-log = { version = "0.2" }
 

libwebauthn/examples/ceremony/webauthn_cable.rs

@@ -3,10 +3,10 @@
 //! MakeCredential only.
 use std::error::Error;
 
-use libwebauthn::transport::cable::is_available;
 use libwebauthn::transport::cable::qr_code_device::{
     CableQrCodeDevice, CableTransports, QrCodeOperationHint,
 };
+use libwebauthn::transport::cable::{is_available, CableClose};
 use qrcode::render::unicode;
 use qrcode::QrCode;
 
@@ -96,5 +96,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         .expect("Failed to serialize MakeCredential response");
     println!("WebAuthn MakeCredential response (JSON):\n{response_json}");
 
+    // A transient QR code never lingers, so this is a plain graceful close.
+    channel.close(CableClose::Immediate).await;
     Ok(())
 }

libwebauthn/examples/ceremony/webauthn_cable_wss.rs

@@ -2,13 +2,15 @@ use std::error::Error;
 use std::sync::Arc;
 use std::time::Duration;
 
-use libwebauthn::transport::cable::is_available;
 use libwebauthn::transport::cable::known_devices::{
     CableKnownDevice, ClientPayloadHint, EphemeralDeviceInfoStore,
 };
 use libwebauthn::transport::cable::qr_code_device::{
     CableQrCodeDevice, CableTransports, QrCodeOperationHint,
 };
+use libwebauthn::transport::cable::{
+    is_available, CableClose, CableLingerConfig, CableLingerRegistry,
+};
 use qrcode::render::unicode;
 use qrcode::QrCode;
 use tokio::time::sleep;
@@ -68,6 +70,14 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     }
 
     let device_info_store = Arc::new(EphemeralDeviceInfoStore::default());
+    // One registry per client, threaded through every hybrid channel. It lets
+    // a connection keep receiving the linking update after the ceremony, and
+    // a new connection evict the one still lingering.
+    let linger_registry = CableLingerRegistry::new();
+    let settings = || ChannelSettings {
+        cable_linger: Some(CableLingerConfig::new(linger_registry.clone())),
+        ..Default::default()
+    };
     let request_origin: RequestOrigin = "https://example.org".try_into().expect("Invalid origin");
     let psl = SystemPublicSuffixList::auto().expect(
         "PSL not available; install the publicsuffix-list (or publicsuffix-list-dafsa) package, or pass an explicit path",
@@ -89,7 +99,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
             .build();
         println!("{}", image);
 
-        let mut channel = device.channel(ChannelSettings::default()).await.unwrap();
+        let mut channel = device.channel(settings()).await.unwrap();
         println!("Channel established {:?}", channel);
 
         let state_recv = channel.get_ux_update_receiver();
@@ -113,10 +123,18 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
             .to_json_string(&request, JsonFormat::Prettified)
             .expect("Failed to serialize MakeCredential response");
         println!("WebAuthn MakeCredential response (JSON):\n{response_json}");
+
+        // Say goodbye, then keep receiving in the background: the phone may
+        // send its linking information a while after the response.
+        channel.close(CableClose::Linger).await;
     }
 
-    println!("Waiting for 5 seconds before contacting the device...");
+    println!("Waiting for 5 seconds for a linking update...");
     sleep(Duration::from_secs(5)).await;
+    println!(
+        "Connections still lingering: {}",
+        linger_registry.lingering_count()
+    );
 
     // Second leg: prefer state-assisted reconnection if the peer offered
     // linking info, otherwise fall back to a fresh QR. Many authenticators
@@ -131,12 +149,11 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         )
         .await
         .unwrap();
-        let mut channel = known_device
-            .channel(ChannelSettings::default())
-            .await
-            .unwrap();
+        // Opening this channel evicts the lingering QR connection.
+        let mut channel = known_device.channel(settings()).await.unwrap();
         println!("Channel established {:?}", channel);
         run_get_assertion(&mut channel, &request_origin, &psl).await?;
+        channel.close(CableClose::Immediate).await;
     } else {
         println!("No known devices (peer did not offer linking). Falling back to QR.");
         let mut device: CableQrCodeDevice = CableQrCodeDevice::new_persistent(
@@ -151,11 +168,15 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
             .light_color(unicode::Dense1x2::Dark)
             .build();
         println!("{}", image);
-        let mut channel = device.channel(ChannelSettings::default()).await.unwrap();
+        let mut channel = device.channel(settings()).await.unwrap();
         println!("Channel established {:?}", channel);
         run_get_assertion(&mut channel, &request_origin, &psl).await?;
+        // Nothing follows that could use a linking update, so just close.
+        channel.close(CableClose::Immediate).await;
     }
 
+    // Signal any lingering connection to stop before the runtime goes away.
+    linger_registry.close_lingering();
     Ok(())
 }
 

libwebauthn/examples/management/persistent_cred_management_hid.rs

@@ -42,6 +42,7 @@ pub async fn main() -> Result<(), WebAuthnError<HidError>> {
         // token through it. The same settings apply to any transport.
         let settings = ChannelSettings {
             persistent_token_store: Some(store.clone()),
+            ..Default::default()
         };
         let mut channel = device.channel(settings).await?;
         let state_recv = channel.get_ux_update_receiver();