Skip to main content

ton_connect_core/
deep_link.rs

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/// Encodes a TON Connect query for Telegram's `startapp` transport.
13#[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/// Decodes Telegram `startapp` substitutions back to a TON Connect query.
25#[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/// Action the wallet takes after the connect prompt completes.
37#[derive(Clone, Debug, Eq, PartialEq)]
38pub enum ReturnStrategy {
39    /// Return to the application that opened the wallet.
40    Back,
41    /// Do not perform a return jump.
42    None,
43    /// Open an explicit absolute application URL.
44    Custom(String),
45}
46
47/// A parsed TON Connect universal, unified, or custom-scheme link.
48#[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    /// Creates a complete connect link value before choosing a wallet-specific
60    /// universal or custom-scheme base URL.
61    #[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    /// Creates the reduced `id`/`ret` link accepted by compatible wallets.
80    #[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    /// Parses both a full connect link and the protocol's reduced `id`/`ret` link.
97    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        // Malformed or unsupported embedded requests are deliberately ignored.
132        // The dApp SDK then falls back to ordinary bridge RPC after connect.
133        let embedded_request = known
134            .remove("e")
135            .and_then(|parameter| decode_embedded_request_param(&parameter).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    /// Encodes this value against a wallet universal URL, `tc://`, or a
158    /// wallet-specific custom scheme.
159    ///
160    /// Query parameters already present on `base_url` are rejected so caller
161    /// data cannot shadow the protocol's singleton parameters.
162    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    /// Returns the dApp's bridge client identifier.
219    #[must_use]
220    pub const fn client_id(&self) -> ClientId {
221        self.client_id
222    }
223
224    /// Returns the connect request, absent only for reduced `id`/`ret` links.
225    #[must_use]
226    pub const fn request(&self) -> Option<&ConnectRequest> {
227        self.request.as_ref()
228    }
229
230    /// Returns the post-action navigation strategy.
231    #[must_use]
232    pub const fn return_strategy(&self) -> &ReturnStrategy {
233        &self.return_strategy
234    }
235
236    /// Returns the optional one-tap request.
237    #[must_use]
238    pub const fn embedded_request(&self) -> Option<&EmbeddedRequest> {
239        self.embedded_request.as_ref()
240    }
241
242    /// Returns the optional analytics correlation identifier.
243    #[must_use]
244    pub const fn trace_id(&self) -> Option<&TraceId> {
245        self.trace_id.as_ref()
246    }
247
248    /// Returns unknown query parameters retained for forward compatibility.
249    #[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/// Failure to parse a TON Connect link.
271#[derive(Debug, Error)]
272pub enum ConnectLinkError {
273    /// A universal, unified, or custom-scheme base URL is malformed.
274    #[error("invalid TON Connect base URL: {0}")]
275    InvalidBaseUrl(url::ParseError),
276    /// A base URL already contains values that could shadow protocol fields.
277    #[error("TON Connect base URL must not contain a query or fragment")]
278    BaseUrlContainsQueryOrFragment,
279    /// The outer link itself is not an absolute URL.
280    #[error("invalid TON Connect URL: {0}")]
281    InvalidUrl(#[from] url::ParseError),
282    /// A required query parameter is absent.
283    #[error("missing TON Connect query parameter: {0}")]
284    MissingParameter(&'static str),
285    /// A singleton protocol query parameter appeared more than once.
286    #[error("duplicate TON Connect query parameter: {0}")]
287    DuplicateParameter(String),
288    /// The link requests a protocol version other than version 2.
289    #[error("unsupported TON Connect protocol version: {0}")]
290    UnsupportedVersion(String),
291    /// A compact request appeared without a connect request.
292    #[error("embedded request requires a connect request")]
293    EmbeddedRequestWithoutConnect,
294    /// The custom return target is not an absolute URL.
295    #[error("invalid TON Connect return strategy: {0}")]
296    InvalidReturnStrategy(String),
297    /// A scalar protocol value is malformed.
298    #[error(transparent)]
299    InvalidValue(#[from] ValueError),
300    /// The URL-decoded connect request violates its JSON schema.
301    #[error("invalid TON Connect request: {0}")]
302    InvalidConnectRequest(#[from] serde_json::Error),
303    /// A typed connect request could not be serialized.
304    #[error("failed to encode TON Connect request: {0}")]
305    EncodeConnectRequest(serde_json::Error),
306    /// The compact embedded request is malformed.
307    #[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    /// Ported from Tonkeeper iOS `TCUrlParserTests.swift` at
342    /// `ddd80aa0542079e839c2b9db2b16492d3150d732`.
343    #[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    /// Ported from both official TypeScript URL suites at
417    /// `273bc3a6050e6024886ca50c12677dc42ae142a9`.
418    #[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}