Skip to main content

ton_connect_client/
lib.rs

1//! Runtime-neutral wallet-side TON Connect session orchestration.
2//!
3//! The client owns protocol, replay, encryption, and SSE cursor state. The host
4//! owns HTTP streaming, durable storage, wallet operations, and user approval.
5
6#![deny(missing_docs)]
7#![forbid(unsafe_code)]
8
9use std::num::{NonZeroU32, NonZeroUsize};
10
11use serde::{Deserialize, Deserializer, Serialize, de};
12use thiserror::Error;
13use ton_connect_core::{
14    AppRequest, BridgeCodecError, BridgeSseDecoder, ClientId, ConnectEvent, ConnectEventError,
15    ConnectEventErrorCode, ConnectEventPayload, ConnectLink, ConnectLinkError, ConnectRequest,
16    ConnectValidationError, EmbeddedRequest, EmbeddedRequestError, EmbeddedResponse, EmptyObject,
17    HeartbeatMode, HttpBridgeError, HttpBridgeUrl, HttpSessionError, KnownAppRequest,
18    PersistedHttpSession, PreparedBridgePost, RawAccountAddress, ResponseValidationError, RpcError,
19    SessionCrypto, SessionCryptoError, SessionStateError, TraceId, WalletEventKind, WalletResponse,
20    WalletSessionPhase, WalletSessionState, decode_embedded_request_param,
21    encode_embedded_request_param,
22};
23
24/// Limits and bridge identity used by one wallet-side HTTP session.
25#[derive(Clone, Debug, Eq, PartialEq)]
26pub struct TonConnectClientConfig {
27    bridge_url: HttpBridgeUrl,
28    max_event_bytes: NonZeroUsize,
29    message_ttl_seconds: NonZeroU32,
30    heartbeat: HeartbeatMode,
31}
32
33impl TonConnectClientConfig {
34    /// Creates an HTTP bridge configuration from already validated values.
35    #[must_use]
36    pub const fn new(
37        bridge_url: HttpBridgeUrl,
38        max_event_bytes: NonZeroUsize,
39        message_ttl_seconds: NonZeroU32,
40        heartbeat: HeartbeatMode,
41    ) -> Self {
42        Self {
43            bridge_url,
44            max_event_bytes,
45            message_ttl_seconds,
46            heartbeat,
47        }
48    }
49
50    /// Returns the wallet-owned bridge base URL.
51    #[must_use]
52    pub const fn bridge_url(&self) -> &HttpBridgeUrl {
53        &self.bridge_url
54    }
55}
56
57/// A fresh dApp request accepted by the replay reducer.
58#[derive(Clone, Debug, Eq, PartialEq)]
59pub struct IncomingRequest {
60    request: AppRequest,
61    trace_id: Option<TraceId>,
62    closes_session: bool,
63}
64
65#[derive(Deserialize, Serialize)]
66#[serde(rename_all = "camelCase", deny_unknown_fields)]
67struct PersistedIncomingRequest {
68    request: AppRequest,
69    trace_id: Option<TraceId>,
70    closes_session: bool,
71}
72
73/// Complete session state that a host can store and restore after a restart.
74///
75/// The serialized value contains the HTTP session secret key. Store it with
76/// the same protection as wallet authentication credentials.
77#[derive(Serialize)]
78#[serde(rename_all = "camelCase", deny_unknown_fields)]
79pub struct PersistedTonConnectClient {
80    session: PersistedHttpSession,
81    connect_request: Option<ConnectRequest>,
82    embedded_request: Option<String>,
83    initial_trace_id: Option<TraceId>,
84}
85
86#[derive(Deserialize)]
87#[serde(rename_all = "camelCase", deny_unknown_fields)]
88struct PersistedTonConnectClientWire {
89    session: PersistedHttpSession,
90    connect_request: Option<ConnectRequest>,
91    embedded_request: Option<String>,
92    initial_trace_id: Option<TraceId>,
93}
94
95impl<'de> Deserialize<'de> for PersistedTonConnectClient {
96    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
97    where
98        D: Deserializer<'de>,
99    {
100        let wire = PersistedTonConnectClientWire::deserialize(deserializer)?;
101        let pending = wire.session.reducer().phase() == WalletSessionPhase::PendingConnect;
102        if pending != wire.connect_request.is_some()
103            || (wire.embedded_request.is_some() && wire.connect_request.is_none())
104        {
105            return Err(de::Error::custom(
106                "persisted TON Connect client does not match its session phase",
107            ));
108        }
109        if let Some(embedded) = wire.embedded_request.as_deref() {
110            let _ = decode_embedded_request_param(embedded).map_err(de::Error::custom)?;
111        }
112        Ok(Self {
113            session: wire.session,
114            connect_request: wire.connect_request,
115            embedded_request: wire.embedded_request,
116            initial_trace_id: wire.initial_trace_id,
117        })
118    }
119}
120
121impl IncomingRequest {
122    /// Returns the original bridge request envelope.
123    #[must_use]
124    pub const fn request(&self) -> &AppRequest {
125        &self.request
126    }
127
128    /// Parses the method-specific request body.
129    pub fn decode(&self) -> Result<KnownAppRequest, RpcError> {
130        self.request.clone().decode()
131    }
132
133    /// Returns the bridge topic for the response.
134    #[must_use]
135    pub fn topic(&self) -> &str {
136        &self.request.method
137    }
138
139    /// Returns the trace identifier that the bridge attached to the request.
140    #[must_use]
141    pub const fn trace_id(&self) -> Option<&TraceId> {
142        self.trace_id.as_ref()
143    }
144
145    /// Reports whether this request atomically ended the session.
146    #[must_use]
147    pub const fn closes_session(&self) -> bool {
148        self.closes_session
149    }
150
151    /// Serializes this already authenticated request for crash-safe approval.
152    pub fn persisted(&self) -> Result<String, TonConnectClientError> {
153        serde_json::to_string(&PersistedIncomingRequest {
154            request: self.request.clone(),
155            trace_id: self.trace_id.clone(),
156            closes_session: self.closes_session,
157        })
158        .map_err(TonConnectClientError::PendingRequestJson)
159    }
160
161    /// Restores an authenticated request persisted after its replay transition.
162    pub fn restore(persisted: &str) -> Result<Self, TonConnectClientError> {
163        let wire = serde_json::from_str::<PersistedIncomingRequest>(persisted)
164            .map_err(TonConnectClientError::PendingRequestJson)?;
165        let closes_session = matches!(
166            wire.request.clone().decode(),
167            Ok(KnownAppRequest::Disconnect(_))
168        );
169        if closes_session != wire.closes_session {
170            return Err(TonConnectClientError::InvalidPendingRequest);
171        }
172        Ok(Self {
173            request: wire.request,
174            trace_id: wire.trace_id,
175            closes_session: wire.closes_session,
176        })
177    }
178}
179
180/// Wallet-side TON Connect HTTP session state machine.
181pub struct TonConnectClient {
182    connect_request: Option<ConnectRequest>,
183    embedded_request: Option<EmbeddedRequest>,
184    initial_trace_id: Option<TraceId>,
185    peer_client_id: ClientId,
186    bridge_url: HttpBridgeUrl,
187    max_event_bytes: NonZeroUsize,
188    message_ttl_seconds: NonZeroU32,
189    heartbeat: HeartbeatMode,
190    crypto: SessionCrypto,
191    reducer: WalletSessionState,
192    connected_address: Option<RawAccountAddress>,
193    last_bridge_event_id: Option<String>,
194    decoder: BridgeSseDecoder,
195}
196
197impl TonConnectClient {
198    /// Parses a full connect link and creates a fresh encrypted HTTP session.
199    pub fn from_link(
200        link: &str,
201        config: TonConnectClientConfig,
202    ) -> Result<Self, TonConnectClientError> {
203        let link = ConnectLink::parse(link)?;
204        Self::from_parsed_link(&link, config)
205    }
206
207    /// Creates a fresh encrypted HTTP session from a parsed full connect link.
208    pub fn from_parsed_link(
209        link: &ConnectLink,
210        config: TonConnectClientConfig,
211    ) -> Result<Self, TonConnectClientError> {
212        let Some(connect_request) = link.request().cloned() else {
213            return Err(TonConnectClientError::MissingConnectRequest);
214        };
215        let embedded_request = link.embedded_request().cloned();
216        let initial_trace_id = link.trace_id().cloned();
217        let peer_client_id = link.client_id();
218        let crypto = SessionCrypto::generate()?;
219        let decoder = BridgeSseDecoder::new(config.max_event_bytes);
220        Ok(Self {
221            connect_request: Some(connect_request),
222            embedded_request,
223            initial_trace_id,
224            peer_client_id,
225            bridge_url: config.bridge_url,
226            max_event_bytes: config.max_event_bytes,
227            message_ttl_seconds: config.message_ttl_seconds,
228            heartbeat: config.heartbeat,
229            crypto,
230            reducer: WalletSessionState::pending_connect(),
231            connected_address: None,
232            last_bridge_event_id: None,
233            decoder,
234        })
235    }
236
237    /// Restores a previously persisted session without creating new keys.
238    pub fn restore(
239        persisted: &PersistedTonConnectClient,
240        max_event_bytes: NonZeroUsize,
241        message_ttl_seconds: NonZeroU32,
242        heartbeat: HeartbeatMode,
243    ) -> Result<Self, TonConnectClientError> {
244        Ok(Self {
245            connect_request: persisted.connect_request.clone(),
246            embedded_request: persisted
247                .embedded_request
248                .as_deref()
249                .map(decode_embedded_request_param)
250                .transpose()?,
251            initial_trace_id: persisted.initial_trace_id.clone(),
252            peer_client_id: persisted.session.peer_client_id(),
253            bridge_url: persisted.session.bridge_url().clone(),
254            max_event_bytes,
255            message_ttl_seconds,
256            heartbeat,
257            crypto: persisted.session.restore_crypto()?,
258            reducer: persisted.session.reducer().clone(),
259            connected_address: persisted.session.connected_address(),
260            last_bridge_event_id: persisted.session.last_bridge_event_id().map(str::to_owned),
261            decoder: BridgeSseDecoder::new(max_event_bytes),
262        })
263    }
264
265    /// Returns the initial connect request while the session is being approved.
266    #[must_use]
267    pub const fn connect_request(&self) -> Option<&ConnectRequest> {
268        self.connect_request.as_ref()
269    }
270
271    /// Returns the optional one-tap action from the connect link.
272    #[must_use]
273    pub const fn embedded_request(&self) -> Option<&EmbeddedRequest> {
274        self.embedded_request.as_ref()
275    }
276
277    /// Returns the dApp bridge client identifier fixed for this session.
278    #[must_use]
279    pub const fn peer_client_id(&self) -> ClientId {
280        self.peer_client_id
281    }
282
283    /// Returns the wallet bridge client identifier fixed for this session.
284    #[must_use]
285    pub const fn client_id(&self) -> ClientId {
286        self.crypto.client_id()
287    }
288
289    /// Returns the current protocol lifecycle phase.
290    #[must_use]
291    pub const fn phase(&self) -> WalletSessionPhase {
292        self.reducer.phase()
293    }
294
295    /// Returns the account fixed by a successful connect response.
296    #[must_use]
297    pub const fn connected_address(&self) -> Option<RawAccountAddress> {
298        self.connected_address
299    }
300
301    /// Returns the most recent bridge SSE resume cursor.
302    #[must_use]
303    pub fn last_bridge_event_id(&self) -> Option<&str> {
304        self.last_bridge_event_id.as_deref()
305    }
306
307    /// Builds the next SSE subscription URL and resets stream-local framing state.
308    #[must_use]
309    pub fn begin_events_subscription(&mut self) -> url::Url {
310        self.decoder = BridgeSseDecoder::new(self.max_event_bytes);
311        self.bridge_url.events_endpoint_with_heartbeat(
312            self.crypto.client_id(),
313            self.last_bridge_event_id.as_deref(),
314            self.initial_trace_id.as_ref(),
315            self.heartbeat,
316        )
317    }
318
319    /// Validates and encrypts a successful connect event.
320    ///
321    /// Persist [`Self::persisted`] before the host posts the returned message.
322    pub fn approve_connect(
323        &mut self,
324        payload: ConnectEventPayload,
325        embedded_response: Option<EmbeddedResponse>,
326    ) -> Result<PreparedBridgePost, TonConnectClientError> {
327        let Some(request) = self.connect_request.as_ref() else {
328            return Err(TonConnectClientError::MissingConnectRequest);
329        };
330        let transition = self.reducer.prepare_event(WalletEventKind::Connect)?;
331        let event = ConnectEvent::Connect {
332            id: transition.id(),
333            payload,
334            response: embedded_response,
335        };
336        event.validate_for_connect(request, self.embedded_request.as_ref())?;
337        let Some(address) = connected_address(&event) else {
338            return Err(TonConnectClientError::MissingConnectedAddress);
339        };
340        let post = self.prepare_post(&event, None, self.initial_trace_id.as_ref())?;
341        self.reducer = transition.into_state();
342        self.connected_address = Some(address);
343        self.connect_request = None;
344        self.embedded_request = None;
345        self.initial_trace_id = None;
346        Ok(post)
347    }
348
349    /// Encrypts a terminal connect error and closes the pending session.
350    ///
351    /// Persist [`Self::persisted`] before the host posts the returned message.
352    pub fn reject_connect(
353        &mut self,
354        code: ConnectEventErrorCode,
355        message: String,
356    ) -> Result<PreparedBridgePost, TonConnectClientError> {
357        let transition = self.reducer.prepare_event(WalletEventKind::ConnectError)?;
358        let event = ConnectEvent::ConnectError {
359            id: transition.id(),
360            payload: ConnectEventError { code, message },
361        };
362        let post = self.prepare_post(&event, None, self.initial_trace_id.as_ref())?;
363        self.reducer = transition.into_state();
364        self.connect_request = None;
365        self.embedded_request = None;
366        self.initial_trace_id = None;
367        Ok(post)
368    }
369
370    /// Encrypts a wallet-initiated disconnect event and closes the session.
371    ///
372    /// Post the returned message before deleting the persisted session secret.
373    pub fn disconnect(
374        &mut self,
375        trace_id: Option<&TraceId>,
376    ) -> Result<PreparedBridgePost, TonConnectClientError> {
377        let transition = self.reducer.prepare_event(WalletEventKind::Disconnect)?;
378        let event = ConnectEvent::Disconnect {
379            id: transition.id(),
380            payload: EmptyObject,
381        };
382        let post = self.prepare_post(&event, None, trace_id)?;
383        self.reducer = transition.into_state();
384        Ok(post)
385    }
386
387    /// Decodes an SSE chunk and returns only fresh authenticated dApp requests.
388    ///
389    /// Messages from another peer, malformed ciphertext, and replayed request
390    /// identifiers are discarded before they reach wallet approval code.
391    /// Persist [`Self::persisted`] before processing any returned request.
392    pub fn ingest_sse_chunk(
393        &mut self,
394        chunk: &[u8],
395    ) -> Result<Vec<IncomingRequest>, TonConnectClientError> {
396        let events = self.decoder.push(chunk)?;
397        let mut requests = Vec::new();
398        for event in events {
399            if let Some(event_id) = event.event_id() {
400                self.last_bridge_event_id = Some(event_id.to_owned());
401            }
402            let trace_id = event.message().trace_id().cloned();
403            let Ok(request) = event.decrypt::<AppRequest>(&self.crypto, self.peer_client_id) else {
404                continue;
405            };
406            let Ok(prepared) = self.reducer.prepare_request(&request) else {
407                continue;
408            };
409            let closes_session = prepared.closes_session();
410            self.reducer = prepared.into_state();
411            requests.push(IncomingRequest {
412                request,
413                trace_id,
414                closes_session,
415            });
416        }
417        Ok(requests)
418    }
419
420    /// Validates correlation when possible and encrypts a wallet RPC response.
421    pub fn prepare_response(
422        &self,
423        incoming: &IncomingRequest,
424        response: &WalletResponse,
425    ) -> Result<PreparedBridgePost, TonConnectClientError> {
426        if response_id(response) != incoming.request.id {
427            return Err(TonConnectClientError::ResponseIdMismatch);
428        }
429        if let Ok(known) = incoming.decode() {
430            let _ = response.validate_for(&known)?;
431        }
432        self.prepare_post(response, Some(incoming.topic()), incoming.trace_id())
433    }
434
435    /// Captures the complete secret-bearing session state for protected storage.
436    pub fn persisted(&self) -> Result<PersistedTonConnectClient, TonConnectClientError> {
437        Ok(PersistedTonConnectClient {
438            session: PersistedHttpSession::new(
439                &self.crypto,
440                self.peer_client_id,
441                self.bridge_url.clone(),
442                self.reducer.clone(),
443                self.connected_address,
444                self.last_bridge_event_id.clone(),
445            )?,
446            connect_request: self.connect_request.clone(),
447            embedded_request: self
448                .embedded_request
449                .as_ref()
450                .map(encode_embedded_request_param)
451                .transpose()?,
452            initial_trace_id: self.initial_trace_id.clone(),
453        })
454    }
455
456    fn prepare_post<T: Serialize>(
457        &self,
458        payload: &T,
459        topic: Option<&str>,
460        trace_id: Option<&TraceId>,
461    ) -> Result<PreparedBridgePost, TonConnectClientError> {
462        Ok(self.bridge_url.prepare_post(
463            &self.crypto,
464            self.peer_client_id,
465            self.message_ttl_seconds,
466            topic,
467            trace_id,
468            payload,
469        )?)
470    }
471}
472
473fn connected_address(event: &ConnectEvent) -> Option<RawAccountAddress> {
474    let ConnectEvent::Connect { payload, .. } = event else {
475        return None;
476    };
477    payload.items.iter().find_map(|reply| match reply {
478        ton_connect_core::ConnectItemReply::TonAddress(account) => Some(account.address),
479        ton_connect_core::ConnectItemReply::TonProof(_)
480        | ton_connect_core::ConnectItemReply::Error(_) => None,
481    })
482}
483
484fn response_id(response: &WalletResponse) -> &str {
485    match response {
486        WalletResponse::Success(response) => &response.id,
487        WalletResponse::Error { id, .. } => id,
488    }
489}
490
491/// Failure in wallet-side TON Connect session orchestration.
492#[derive(Debug, Error)]
493pub enum TonConnectClientError {
494    /// A reduced link cannot start a new wallet session.
495    #[error("TON Connect link does not contain a connect request")]
496    MissingConnectRequest,
497    /// A validated connect response unexpectedly contained no account.
498    #[error("TON Connect connect response has no connected account")]
499    MissingConnectedAddress,
500    /// A wallet response does not echo the accepted dApp request identifier.
501    #[error("TON Connect wallet response id does not match the dApp request")]
502    ResponseIdMismatch,
503    /// A persisted authenticated request has inconsistent lifecycle metadata.
504    #[error("persisted TON Connect request is inconsistent")]
505    InvalidPendingRequest,
506    /// A persisted authenticated request is malformed JSON.
507    #[error("invalid persisted TON Connect request: {0}")]
508    PendingRequestJson(serde_json::Error),
509    /// The deep link is malformed.
510    #[error(transparent)]
511    Link(#[from] ConnectLinkError),
512    /// Session key generation or encryption failed.
513    #[error(transparent)]
514    Crypto(#[from] SessionCryptoError),
515    /// The connect event does not match the initiating request.
516    #[error(transparent)]
517    ConnectValidation(#[from] ConnectValidationError),
518    /// The protocol reducer rejected a lifecycle transition.
519    #[error(transparent)]
520    SessionState(#[from] SessionStateError),
521    /// HTTP bridge framing or endpoint construction failed.
522    #[error(transparent)]
523    HttpBridge(#[from] HttpBridgeError),
524    /// Bridge plaintext encryption or encoding failed.
525    #[error(transparent)]
526    BridgeCodec(#[from] BridgeCodecError),
527    /// A known response does not match its request method.
528    #[error(transparent)]
529    ResponseValidation(#[from] ResponseValidationError),
530    /// Persisted session material is malformed.
531    #[error(transparent)]
532    HttpSession(#[from] HttpSessionError),
533    /// An embedded request cannot be encoded or restored.
534    #[error(transparent)]
535    EmbeddedRequest(#[from] EmbeddedRequestError),
536}