auths_core/ports/
pairing.rs

1use std::future::Future;
2use std::time::Duration;
3
4use crate::pairing::{
5    CreateSessionRequest, CreateSessionResponse, GetConfirmationResponse, GetSessionResponse,
6    SubmitConfirmationRequest, SubmitResponseRequest,
7};
8use crate::ports::network::NetworkError;
9
10/// Port trait for communicating with a pairing relay server.
11///
12/// Implementations handle transport details (HTTP, WebSocket, etc.).
13/// SDK orchestrators depend only on this abstraction.
14///
15/// Usage:
16/// ```ignore
17/// use auths_core::ports::pairing::PairingRelayClient;
18///
19/// async fn run(relay: &impl PairingRelayClient, registry: &str) {
20///     let resp = relay.create_session(registry, &request).await?;
21/// }
22/// ```
23pub trait PairingRelayClient: Send + Sync {
24    /// Creates a new pairing session on the relay server.
25    ///
26    /// Args:
27    /// * `registry_url`: Base URL of the pairing relay server.
28    /// * `request`: Session creation parameters including controller DID and capabilities.
29    ///
30    /// Usage:
31    /// ```ignore
32    /// let resp = relay.create_session("https://registry.example.com", &request).await?;
33    /// ```
34    fn create_session(
35        &self,
36        registry_url: &str,
37        request: &CreateSessionRequest,
38    ) -> impl Future<Output = Result<CreateSessionResponse, NetworkError>> + Send;
39
40    /// Fetches the current state of a pairing session.
41    ///
42    /// Args:
43    /// * `registry_url`: Base URL of the pairing relay server.
44    /// * `session_id`: The session identifier returned by `create_session`.
45    ///
46    /// Usage:
47    /// ```ignore
48    /// let session = relay.get_session("https://registry.example.com", &session_id).await?;
49    /// ```
50    fn get_session(
51        &self,
52        registry_url: &str,
53        session_id: &str,
54    ) -> impl Future<Output = Result<GetSessionResponse, NetworkError>> + Send;
55
56    /// Looks up a session by its short human-readable code.
57    ///
58    /// Args:
59    /// * `registry_url`: Base URL of the pairing relay server.
60    /// * `code`: The normalised short code (e.g. `"abc123"`).
61    ///
62    /// Usage:
63    /// ```ignore
64    /// let session = relay.lookup_by_code("https://registry.example.com", "abc123").await?;
65    /// ```
66    fn lookup_by_code(
67        &self,
68        registry_url: &str,
69        code: &str,
70    ) -> impl Future<Output = Result<GetSessionResponse, NetworkError>> + Send;
71
72    /// Submits a device pairing response to a session.
73    ///
74    /// Args:
75    /// * `registry_url`: Base URL of the pairing relay server.
76    /// * `session_id`: The session to respond to.
77    /// * `response`: The pairing response payload (device keys, DID, signature).
78    ///
79    /// Usage:
80    /// ```ignore
81    /// relay.submit_response("https://registry.example.com", &session_id, &response).await?;
82    /// ```
83    fn submit_response(
84        &self,
85        registry_url: &str,
86        session_id: &str,
87        response: &SubmitResponseRequest,
88    ) -> impl Future<Output = Result<(), NetworkError>> + Send;
89
90    /// Waits for a session to reach a terminal state, using WebSocket with HTTP polling fallback.
91    ///
92    /// Returns `None` if `timeout` elapses before any terminal state is reached.
93    ///
94    /// Args:
95    /// * `registry_url`: Base URL of the pairing relay server.
96    /// * `session_id`: The session to watch.
97    /// * `timeout`: Maximum time to wait before returning `None`.
98    ///
99    /// Usage:
100    /// ```ignore
101    /// let result = relay.wait_for_update(registry, &session_id, Duration::from_secs(60)).await?;
102    /// ```
103    fn wait_for_update(
104        &self,
105        registry_url: &str,
106        session_id: &str,
107        timeout: Duration,
108    ) -> impl Future<Output = Result<Option<GetSessionResponse>, NetworkError>> + Send;
109
110    /// Submits a SAS confirmation (encrypted attestation or abort signal).
111    ///
112    /// Args:
113    /// * `url`: Base URL of the pairing server.
114    /// * `session_id`: The session to confirm.
115    /// * `request`: The confirmation payload.
116    fn submit_confirmation(
117        &self,
118        url: &str,
119        session_id: &str,
120        request: &SubmitConfirmationRequest,
121    ) -> impl Future<Output = Result<(), NetworkError>> + Send;
122
123    /// Polls for a SAS confirmation from the initiator.
124    ///
125    /// Args:
126    /// * `url`: Base URL of the pairing server.
127    /// * `session_id`: The session to check.
128    fn get_confirmation(
129        &self,
130        url: &str,
131        session_id: &str,
132    ) -> impl Future<Output = Result<GetConfirmationResponse, NetworkError>> + Send;
133}
auths_core/ports/pairing.rs

auths_core/ports/
pairing.rs
