1#![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#[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 #[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 #[must_use]
52 pub const fn bridge_url(&self) -> &HttpBridgeUrl {
53 &self.bridge_url
54 }
55}
56
57#[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#[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 #[must_use]
124 pub const fn request(&self) -> &AppRequest {
125 &self.request
126 }
127
128 pub fn decode(&self) -> Result<KnownAppRequest, RpcError> {
130 self.request.clone().decode()
131 }
132
133 #[must_use]
135 pub fn topic(&self) -> &str {
136 &self.request.method
137 }
138
139 #[must_use]
141 pub const fn trace_id(&self) -> Option<&TraceId> {
142 self.trace_id.as_ref()
143 }
144
145 #[must_use]
147 pub const fn closes_session(&self) -> bool {
148 self.closes_session
149 }
150
151 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 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
180pub 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 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 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 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 #[must_use]
267 pub const fn connect_request(&self) -> Option<&ConnectRequest> {
268 self.connect_request.as_ref()
269 }
270
271 #[must_use]
273 pub const fn embedded_request(&self) -> Option<&EmbeddedRequest> {
274 self.embedded_request.as_ref()
275 }
276
277 #[must_use]
279 pub const fn peer_client_id(&self) -> ClientId {
280 self.peer_client_id
281 }
282
283 #[must_use]
285 pub const fn client_id(&self) -> ClientId {
286 self.crypto.client_id()
287 }
288
289 #[must_use]
291 pub const fn phase(&self) -> WalletSessionPhase {
292 self.reducer.phase()
293 }
294
295 #[must_use]
297 pub const fn connected_address(&self) -> Option<RawAccountAddress> {
298 self.connected_address
299 }
300
301 #[must_use]
303 pub fn last_bridge_event_id(&self) -> Option<&str> {
304 self.last_bridge_event_id.as_deref()
305 }
306
307 #[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 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 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 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 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 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 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#[derive(Debug, Error)]
493pub enum TonConnectClientError {
494 #[error("TON Connect link does not contain a connect request")]
496 MissingConnectRequest,
497 #[error("TON Connect connect response has no connected account")]
499 MissingConnectedAddress,
500 #[error("TON Connect wallet response id does not match the dApp request")]
502 ResponseIdMismatch,
503 #[error("persisted TON Connect request is inconsistent")]
505 InvalidPendingRequest,
506 #[error("invalid persisted TON Connect request: {0}")]
508 PendingRequestJson(serde_json::Error),
509 #[error(transparent)]
511 Link(#[from] ConnectLinkError),
512 #[error(transparent)]
514 Crypto(#[from] SessionCryptoError),
515 #[error(transparent)]
517 ConnectValidation(#[from] ConnectValidationError),
518 #[error(transparent)]
520 SessionState(#[from] SessionStateError),
521 #[error(transparent)]
523 HttpBridge(#[from] HttpBridgeError),
524 #[error(transparent)]
526 BridgeCodec(#[from] BridgeCodecError),
527 #[error(transparent)]
529 ResponseValidation(#[from] ResponseValidationError),
530 #[error(transparent)]
532 HttpSession(#[from] HttpSessionError),
533 #[error(transparent)]
535 EmbeddedRequest(#[from] EmbeddedRequestError),
536}