@@ -62,6 +62,20 @@ pub enum Role {
6262 Target ,
6363}
6464
65+ /// Public channel binding for independently authenticated application approval.
66+ /// This identifies the locked peers and transcript, not their account identity.
67+ #[ derive( Debug , Clone , PartialEq , Eq ) ]
68+ pub struct PairingBinding {
69+ /// Identifier derived from this QR session's random secret.
70+ pub session_id : [ u8 ; 32 ] ,
71+ /// The initiating device's ephemeral public key.
72+ pub source_pubkey : PublicKey ,
73+ /// The receiving device's ephemeral public key.
74+ pub target_pubkey : PublicKey ,
75+ /// The commitment verified by `sas-confirm`.
76+ pub transcript_hash : [ u8 ; 32 ] ,
77+ }
78+
6579/// Protocol state.
6680#[ derive( Debug , Clone , Copy , PartialEq , Eq ) ]
6781pub enum SessionState {
@@ -115,6 +129,8 @@ pub struct PairingSession {
115129 desktop_code_requested : bool ,
116130 desktop_code : Option < Zeroizing < String > > ,
117131 code_attempts : u8 ,
132+ /// Strict target-side code-entry negotiation and request correlation.
133+ target_desktop_code : Option < desktop_code:: TargetDesktopCode > ,
118134}
119135
120136impl PairingSession {
@@ -150,6 +166,7 @@ impl PairingSession {
150166 desktop_code_requested : false ,
151167 desktop_code : None ,
152168 code_attempts : 0 ,
169+ target_desktop_code : None ,
153170 } ;
154171
155172 ( session, qr)
@@ -357,6 +374,13 @@ impl PairingSession {
357374 ///
358375 /// Returns the session and the `offer` event to publish.
359376 pub fn new_target ( qr : & QrPayload ) -> Result < ( Self , Event ) , PairingError > {
377+ Self :: new_target_with_confirmation ( qr, false )
378+ }
379+
380+ fn new_target_with_confirmation (
381+ qr : & QrPayload ,
382+ desktop_code : bool ,
383+ ) -> Result < ( Self , Event ) , PairingError > {
360384 let keys = Keys :: generate ( ) ;
361385 let session_id = derive_session_id ( & qr. session_secret ) ;
362386
@@ -383,13 +407,14 @@ impl PairingSession {
383407 desktop_code_requested : false ,
384408 desktop_code : None ,
385409 code_attempts : 0 ,
410+ target_desktop_code : desktop_code. then ( desktop_code:: TargetDesktopCode :: default) ,
386411 } ;
387412
388413 // Build and return the offer event.
389414 let msg = PairingMessage :: Offer {
390415 session_id : hex:: encode ( session_id) ,
391416 version : 1 ,
392- confirmation : None ,
417+ confirmation : desktop_code . then ( || "desktop-code-v1" . into ( ) ) ,
393418 } ;
394419 let event = session. build_event ( & msg) ?;
395420 session. state = SessionState :: Confirming ;
@@ -408,6 +433,14 @@ impl PairingSession {
408433 self . expect_state ( SessionState :: Confirming ) ?;
409434 self . expect_role ( Role :: Target ) ?;
410435 self . validate_event_from_peer ( event) ?;
436+ if let Some ( code) = & self . target_desktop_code {
437+ if !code. challenged || code. pending_request_id . is_none ( ) {
438+ return Err ( PairingError :: UnexpectedMessage {
439+ expected : "desktop code challenge and submission" . into ( ) ,
440+ got : "sas-confirm" . into ( ) ,
441+ } ) ;
442+ }
443+ }
411444
412445 let msg = self . decrypt_message ( event) ?;
413446 let received_hash = match & msg {
@@ -443,6 +476,9 @@ impl PairingSession {
443476 }
444477
445478 self . state = SessionState :: AwaitingConfirmation ;
479+ if let Some ( code) = & mut self . target_desktop_code {
480+ code. pending_request_id = None ;
481+ }
446482 self . record_event ( event) ;
447483 let code = self . sas_code . ok_or ( PairingError :: SasMismatch ) ?;
448484 Ok ( format_sas ( code) )
@@ -487,13 +523,23 @@ impl PairingSession {
487523
488524 /// (Target) Build the `complete` event to publish.
489525 pub fn send_complete ( & mut self ) -> Result < Event , PairingError > {
526+ self . send_complete_with_result ( true )
527+ }
528+
529+ /// (Target) Acknowledge whether the received payload was durably imported.
530+ /// Call only after the application has completed its secure-storage attempt.
531+ pub fn send_complete_with_result ( & mut self , success : bool ) -> Result < Event , PairingError > {
490532 self . check_expired ( ) ?;
491533 self . expect_state ( SessionState :: PayloadExchanged ) ?;
492534 self . expect_role ( Role :: Target ) ?;
493535
494- let msg = PairingMessage :: Complete { success : true } ;
536+ let msg = PairingMessage :: Complete { success } ;
495537 let event = self . build_event ( & msg) ?;
496- self . state = SessionState :: Completed ;
538+ self . state = if success {
539+ SessionState :: Completed
540+ } else {
541+ SessionState :: Aborted
542+ } ;
497543 Ok ( event)
498544 }
499545}
@@ -608,6 +654,45 @@ impl PairingSession {
608654 relays : self . relay_urls . clone ( ) ,
609655 } ) )
610656 }
657+
658+ /// Capture the live exchange's public channel binding, in source/target
659+ /// order on both devices. Source must first accept an offer. Applications
660+ /// submit this independently through each user's authenticated session;
661+ /// no application credential needs to travel over the pairing protocol.
662+ /// This method does not authorize exporting identity material.
663+ pub fn binding ( & self ) -> Result < PairingBinding , PairingError > {
664+ self . check_expired ( ) ?;
665+ if !matches ! (
666+ self . state,
667+ SessionState :: Confirming
668+ | SessionState :: AwaitingConfirmation
669+ | SessionState :: Transferring
670+ ) {
671+ return Err ( PairingError :: UnexpectedMessage {
672+ expected : "live pairing with a locked peer" . into ( ) ,
673+ got : "unbound or terminal session" . into ( ) ,
674+ } ) ;
675+ }
676+ let peer = self . peer_pubkey . ok_or ( PairingError :: SasMismatch ) ?;
677+ let sas_input = self . sas_input . ok_or ( PairingError :: SasMismatch ) ?;
678+ let own = self . keys . public_key ( ) ;
679+ let ( source_pubkey, target_pubkey) = match self . role {
680+ Role :: Source => ( own, peer) ,
681+ Role :: Target => ( peer, own) ,
682+ } ;
683+ Ok ( PairingBinding {
684+ session_id : self . session_id ,
685+ source_pubkey,
686+ target_pubkey,
687+ transcript_hash : derive_transcript_hash (
688+ & self . session_id ,
689+ & source_pubkey. to_bytes ( ) ,
690+ & target_pubkey. to_bytes ( ) ,
691+ & sas_input,
692+ & self . session_secret ,
693+ ) ,
694+ } )
695+ }
611696}
612697
613698#[ cfg( test) ]
0 commit comments