1use std::collections::BTreeMap;
2
3use thiserror::Error;
4
5use crate::{
6 ClientId, ConnectRequest, EmbeddedRequest, EmbeddedRequestError, TraceId, ValueError,
7 decode_embedded_request_param, encode_embedded_request_param,
8};
9
10const PROTOCOL_VERSION: &str = "2";
11
12#[must_use]
14pub fn encode_telegram_url_parameters(parameters: &str) -> String {
15 parameters
16 .replace('.', "%2E")
17 .replace('-', "%2D")
18 .replace('_', "%5F")
19 .replace('&', "-")
20 .replace('=', "__")
21 .replace('%', "--")
22}
23
24#[must_use]
26pub fn decode_telegram_url_parameters(parameters: &str) -> String {
27 parameters
28 .replace("--", "%")
29 .replace("__", "=")
30 .replace('-', "&")
31 .replace("%5F", "_")
32 .replace("%2D", "-")
33 .replace("%2E", ".")
34}
35
36#[derive(Clone, Debug, Eq, PartialEq)]
38pub enum ReturnStrategy {
39 Back,
41 None,
43 Custom(String),
45}
46
47#[derive(Clone, Debug, Eq, PartialEq)]
49pub struct ConnectLink {
50 client_id: ClientId,
51 request: Option<ConnectRequest>,
52 return_strategy: ReturnStrategy,
53 embedded_request: Option<EmbeddedRequest>,
54 trace_id: Option<TraceId>,
55 extensions: Vec<(String, String)>,
56}
57
58impl ConnectLink {
59 #[must_use]
62 pub fn connect(
63 client_id: ClientId,
64 request: ConnectRequest,
65 return_strategy: ReturnStrategy,
66 embedded_request: Option<EmbeddedRequest>,
67 trace_id: Option<TraceId>,
68 ) -> Self {
69 Self {
70 client_id,
71 request: Some(request),
72 return_strategy,
73 embedded_request,
74 trace_id,
75 extensions: Vec::new(),
76 }
77 }
78
79 #[must_use]
81 pub fn reduced(
82 client_id: ClientId,
83 return_strategy: ReturnStrategy,
84 trace_id: Option<TraceId>,
85 ) -> Self {
86 Self {
87 client_id,
88 request: None,
89 return_strategy,
90 embedded_request: None,
91 trace_id,
92 extensions: Vec::new(),
93 }
94 }
95
96 pub fn parse(value: &str) -> Result<Self, ConnectLinkError> {
98 let url = url::Url::parse(value)?;
99 let mut known = BTreeMap::<String, String>::new();
100 let mut extensions = Vec::new();
101 for (name, value) in url.query_pairs() {
102 let name = name.into_owned();
103 let value = value.into_owned();
104 if matches!(name.as_str(), "v" | "id" | "r" | "ret" | "e" | "trace_id") {
105 if known.insert(name.clone(), value).is_some() {
106 return Err(ConnectLinkError::DuplicateParameter(name));
107 }
108 } else {
109 extensions.push((name, value));
110 }
111 }
112
113 let client_id = known
114 .remove("id")
115 .ok_or(ConnectLinkError::MissingParameter("id"))?
116 .parse()?;
117 let request = known
118 .remove("r")
119 .map(|request| serde_json::from_str::<ConnectRequest>(&request))
120 .transpose()?;
121 let version = known.remove("v");
122 if let Some(version) = version.as_deref()
123 && version != PROTOCOL_VERSION
124 {
125 return Err(ConnectLinkError::UnsupportedVersion(version.to_owned()));
126 }
127 if request.is_some() && version.is_none() {
128 return Err(ConnectLinkError::MissingParameter("v"));
129 }
130
131 let embedded_request = known
134 .remove("e")
135 .and_then(|parameter| decode_embedded_request_param(¶meter).ok());
136 if embedded_request.is_some() && request.is_none() {
137 return Err(ConnectLinkError::EmbeddedRequestWithoutConnect);
138 }
139
140 let return_parameter = known.remove("ret");
141 let return_strategy = parse_return_strategy(return_parameter.as_deref())?;
142 let trace_id = known
143 .remove("trace_id")
144 .map(TraceId::try_from)
145 .transpose()?;
146
147 Ok(Self {
148 client_id,
149 request,
150 return_strategy,
151 embedded_request,
152 trace_id,
153 extensions,
154 })
155 }
156
157 pub fn to_url(&self, base_url: &str) -> Result<url::Url, ConnectLinkError> {
163 let mut url = url::Url::parse(base_url).map_err(ConnectLinkError::InvalidBaseUrl)?;
164 if url.query().is_some() || url.fragment().is_some() {
165 return Err(ConnectLinkError::BaseUrlContainsQueryOrFragment);
166 }
167
168 let request = self
169 .request
170 .as_ref()
171 .map(serde_json::to_string)
172 .transpose()
173 .map_err(ConnectLinkError::EncodeConnectRequest)?;
174 let embedded = self
175 .embedded_request
176 .as_ref()
177 .map(encode_embedded_request_param)
178 .transpose()?;
179 if embedded.is_some() && request.is_none() {
180 return Err(ConnectLinkError::EmbeddedRequestWithoutConnect);
181 }
182 let return_strategy = match &self.return_strategy {
183 ReturnStrategy::Back => "back",
184 ReturnStrategy::None => "none",
185 ReturnStrategy::Custom(value) => {
186 let parsed = url::Url::parse(value)
187 .map_err(|_| ConnectLinkError::InvalidReturnStrategy(value.clone()))?;
188 if parsed.scheme().is_empty() {
189 return Err(ConnectLinkError::InvalidReturnStrategy(value.clone()));
190 }
191 value
192 }
193 };
194
195 {
196 let mut query = url.query_pairs_mut();
197 if request.is_some() {
198 let _ = query.append_pair("v", PROTOCOL_VERSION);
199 }
200 let _ = query.append_pair("id", &self.client_id.to_string());
201 if let Some(request) = request.as_deref() {
202 let _ = query.append_pair("r", request);
203 }
204 let _ = query.append_pair("ret", return_strategy);
205 if let Some(trace_id) = &self.trace_id {
206 let _ = query.append_pair("trace_id", trace_id.as_str());
207 }
208 if let Some(embedded) = embedded.as_deref() {
209 let _ = query.append_pair("e", embedded);
210 }
211 for (name, value) in &self.extensions {
212 let _ = query.append_pair(name, value);
213 }
214 }
215 Ok(url)
216 }
217
218 #[must_use]
220 pub const fn client_id(&self) -> ClientId {
221 self.client_id
222 }
223
224 #[must_use]
226 pub const fn request(&self) -> Option<&ConnectRequest> {
227 self.request.as_ref()
228 }
229
230 #[must_use]
232 pub const fn return_strategy(&self) -> &ReturnStrategy {
233 &self.return_strategy
234 }
235
236 #[must_use]
238 pub const fn embedded_request(&self) -> Option<&EmbeddedRequest> {
239 self.embedded_request.as_ref()
240 }
241
242 #[must_use]
244 pub const fn trace_id(&self) -> Option<&TraceId> {
245 self.trace_id.as_ref()
246 }
247
248 #[must_use]
250 pub fn extensions(&self) -> &[(String, String)] {
251 &self.extensions
252 }
253}
254
255fn parse_return_strategy(value: Option<&str>) -> Result<ReturnStrategy, ConnectLinkError> {
256 match value {
257 None | Some("back") => Ok(ReturnStrategy::Back),
258 Some("none") => Ok(ReturnStrategy::None),
259 Some(custom) => {
260 let parsed = url::Url::parse(custom)
261 .map_err(|_| ConnectLinkError::InvalidReturnStrategy(custom.to_owned()))?;
262 if parsed.scheme().is_empty() {
263 return Err(ConnectLinkError::InvalidReturnStrategy(custom.to_owned()));
264 }
265 Ok(ReturnStrategy::Custom(custom.to_owned()))
266 }
267 }
268}
269
270#[derive(Debug, Error)]
272pub enum ConnectLinkError {
273 #[error("invalid TON Connect base URL: {0}")]
275 InvalidBaseUrl(url::ParseError),
276 #[error("TON Connect base URL must not contain a query or fragment")]
278 BaseUrlContainsQueryOrFragment,
279 #[error("invalid TON Connect URL: {0}")]
281 InvalidUrl(#[from] url::ParseError),
282 #[error("missing TON Connect query parameter: {0}")]
284 MissingParameter(&'static str),
285 #[error("duplicate TON Connect query parameter: {0}")]
287 DuplicateParameter(String),
288 #[error("unsupported TON Connect protocol version: {0}")]
290 UnsupportedVersion(String),
291 #[error("embedded request requires a connect request")]
293 EmbeddedRequestWithoutConnect,
294 #[error("invalid TON Connect return strategy: {0}")]
296 InvalidReturnStrategy(String),
297 #[error(transparent)]
299 InvalidValue(#[from] ValueError),
300 #[error("invalid TON Connect request: {0}")]
302 InvalidConnectRequest(#[from] serde_json::Error),
303 #[error("failed to encode TON Connect request: {0}")]
305 EncodeConnectRequest(serde_json::Error),
306 #[error(transparent)]
308 InvalidEmbeddedRequest(#[from] EmbeddedRequestError),
309}
310
311#[cfg(test)]
312mod tests {
313 use base64::{Engine as _, engine::general_purpose};
314
315 use super::*;
316 use crate::ConnectItem;
317
318 const CLIENT_ID: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
319
320 #[test]
321 fn parses_unified_link_and_percent_decoded_connect_request() {
322 let request = r#"{"manifestUrl":"https://app.example/tonconnect-manifest.json","items":[{"name":"ton_addr"}]}"#;
323 let query = url::form_urlencoded::Serializer::new(String::new())
324 .append_pair("v", "2")
325 .append_pair("id", CLIENT_ID)
326 .append_pair("r", request)
327 .append_pair("ret", "back")
328 .append_pair("future", "preserved")
329 .finish();
330 let parsed = ConnectLink::parse(&format!("tc://?{query}"));
331 assert!(parsed.as_ref().is_ok_and(|link| link.request().is_some()));
332 assert!(matches!(
333 parsed.as_ref().map(ConnectLink::return_strategy),
334 Ok(ReturnStrategy::Back)
335 ));
336 assert!(parsed.is_ok_and(|link| {
337 link.extensions() == [("future".to_owned(), "preserved".to_owned())]
338 }));
339 }
340
341 #[test]
344 fn parses_tonkeeper_ios_demo_dapp_vector() -> Result<(), Box<dyn std::error::Error>> {
345 let value = concat!(
346 "tc://?v=2&id=4091db63def30d086acef76cd045a20ca6def5744bad530d2a86766d3e781477",
347 "&r=%7B%22manifestUrl%22%3A%22https%3A%2F%2Fton-connect.github.io%2F",
348 "demo-dapp-with-react-ui%2Ftonconnect-manifest.json%22%2C%22items%22%3A%5B",
349 "%7B%22name%22%3A%22ton_addr%22%7D%2C%7B%22name%22%3A%22ton_proof",
350 "%22%2C%22payload%22%3A%224c9523d2c0017c3e00000000652fc398090082a031a65",
351 "ab99be6209a91c0f818%22%7D%5D%7D"
352 );
353 let link = ConnectLink::parse(value)?;
354 assert_eq!(
355 link.client_id().to_string(),
356 "4091db63def30d086acef76cd045a20ca6def5744bad530d2a86766d3e781477"
357 );
358 let request = link.request().ok_or("full request is required")?;
359 assert_eq!(
360 request.manifest_url.as_str(),
361 "https://ton-connect.github.io/demo-dapp-with-react-ui/tonconnect-manifest.json"
362 );
363 assert!(matches!(
364 request.items.as_slice(),
365 [ConnectItem::TonAddr { .. }, ConnectItem::TonProof { payload }]
366 if payload == "4c9523d2c0017c3e00000000652fc398090082a031a65ab99be6209a91c0f818"
367 ));
368 Ok(())
369 }
370
371 #[test]
372 fn supports_reduced_link_but_not_embedded_action_without_connect() {
373 let reduced = format!("tc://?id={CLIENT_ID}&ret=none");
374 let embedded = general_purpose::URL_SAFE_NO_PAD.encode(r#"{"m":"sd","t":"text","tx":"x"}"#);
375 let invalid = format!("tc://?id={CLIENT_ID}&e={embedded}");
376 assert!(ConnectLink::parse(&reduced).is_ok_and(|link| link.request().is_none()));
377 assert!(matches!(
378 ConnectLink::parse(&invalid),
379 Err(ConnectLinkError::EmbeddedRequestWithoutConnect)
380 ));
381 }
382
383 #[test]
384 fn rejects_duplicate_identifiers_and_unknown_versions() {
385 let duplicate = format!("tc://?id={CLIENT_ID}&id={CLIENT_ID}");
386 let version = format!("tc://?id={CLIENT_ID}&v=3");
387 let invalid_return = format!("tc://?id={CLIENT_ID}&ret=relative");
388 assert!(matches!(
389 ConnectLink::parse(&duplicate),
390 Err(ConnectLinkError::DuplicateParameter(parameter)) if parameter == "id"
391 ));
392 assert!(matches!(
393 ConnectLink::parse(&version),
394 Err(ConnectLinkError::UnsupportedVersion(version)) if version == "3"
395 ));
396 assert!(matches!(
397 ConnectLink::parse(&invalid_return),
398 Err(ConnectLinkError::InvalidReturnStrategy(value)) if value == "relative"
399 ));
400 }
401
402 #[test]
403 fn malformed_embedded_request_is_ignored_for_bridge_fallback() {
404 let request = r#"{"manifestUrl":"https://app.example/tonconnect-manifest.json","items":[{"name":"ton_addr"}]}"#;
405 let query = url::form_urlencoded::Serializer::new(String::new())
406 .append_pair("v", "2")
407 .append_pair("id", CLIENT_ID)
408 .append_pair("r", request)
409 .append_pair("e", "not-base64url")
410 .finish();
411 let parsed = ConnectLink::parse(&format!("tc://?{query}"));
412
413 assert!(parsed.is_ok_and(|link| link.embedded_request().is_none()));
414 }
415
416 #[test]
419 fn telegram_parameter_encoding_matches_typescript_vectors() {
420 for parameters in [
421 concat!(
422 "v=2&id=1a7894bfea897afa462bc8ccc6857c992cc92b0a5ef994ab2f855e764ece4942",
423 "&r=%7B%22manifestUrl%22%3A%22https%3A%2F%2Ftonconnect-sdk-demo-dapp",
424 ".vercel.app%2Ftonconnect-manifest.json%22%2C%22items%22%3A%5B",
425 "%7B%22name%22%3A%22ton_addr%22%7D%5D%7D&ret=none"
426 ),
427 concat!(
428 "id=17b086055e59e7c87fee47797e92be1a51be0dd1a42f2a39131f79cf5169682e",
429 "&ret=back"
430 ),
431 concat!(
432 "v=2&id=7730cae23f454f8d4ba52b07a4ea869773834be331edcadbb5e2da5d94ddfa2d",
433 "&trace_id=019d85ea-ca0e-7129-8155-05c7534ef894&r=%7B%22items%22%3A",
434 "%5B%7B%22name%22%3A%22ton_addr%22%7D%5D%7D"
435 ),
436 ] {
437 let encoded = encode_telegram_url_parameters(parameters);
438 assert_eq!(decode_telegram_url_parameters(&encoded), parameters);
439 assert!(!encoded.contains('&'));
440 assert!(!encoded.contains('='));
441 }
442 }
443
444 #[test]
445 fn complete_and_reduced_links_have_canonical_round_trips()
446 -> Result<(), Box<dyn std::error::Error>> {
447 let request = serde_json::from_str::<ConnectRequest>(
448 r#"{
449 "manifestUrl":"https://app.example/tonconnect-manifest.json",
450 "items":[{"name":"ton_addr","network":"00042"}]
451 }"#,
452 )?;
453 let embedded = decode_embedded_request_param(
454 &general_purpose::URL_SAFE_NO_PAD.encode(r#"{"m":"sd","t":"text","tx":"hello"}"#),
455 )?;
456 let trace_id = TraceId::try_from("018f4f84-7b8d-7c3f-8d8e-123456789abc")?;
457 let client_id = CLIENT_ID.parse()?;
458 let link = ConnectLink::connect(
459 client_id,
460 request,
461 ReturnStrategy::Custom("demo-app://return/path".to_owned()),
462 Some(embedded),
463 Some(trace_id.clone()),
464 );
465
466 let encoded = link.to_url("tc://")?;
467 assert_eq!(ConnectLink::parse(encoded.as_str())?, link);
468 assert_eq!(link.trace_id(), Some(&trace_id));
469
470 let reduced = ConnectLink::reduced(client_id, ReturnStrategy::None, None);
471 let encoded = reduced.to_url("https://wallet.example/connect")?;
472 assert_eq!(ConnectLink::parse(encoded.as_str())?, reduced);
473 assert!(
474 !encoded
475 .query_pairs()
476 .any(|(name, _)| name == "v" || name == "r")
477 );
478 Ok(())
479 }
480
481 #[test]
482 fn link_encoding_rejects_ambiguous_base_and_return_urls()
483 -> Result<(), Box<dyn std::error::Error>> {
484 let client_id = CLIENT_ID.parse()?;
485 let with_query = ConnectLink::reduced(client_id, ReturnStrategy::Back, None);
486 assert!(matches!(
487 with_query.to_url("https://wallet.example/connect?existing=1"),
488 Err(ConnectLinkError::BaseUrlContainsQueryOrFragment)
489 ));
490
491 let bad_return = ConnectLink::reduced(
492 client_id,
493 ReturnStrategy::Custom("relative/path".to_owned()),
494 None,
495 );
496 assert!(matches!(
497 bad_return.to_url("tc://"),
498 Err(ConnectLinkError::InvalidReturnStrategy(_))
499 ));
500 Ok(())
501 }
502}