Connect Deep Links

[martykan]

In order to support Connect on mobile platforms, we need a way to invoke Connect from a mobile app. This can be done by using deeplinks.

Deeplinks are URLs that can be used to open an app from a web page or another app. We can also use them for bi-directional communication to pass the result of a method using a callback link.

The deeplink can either be a URL scheme or a universal link. The URL scheme is a custom URL that is unique to the app (such as trezor-suite://), while the universal link is a standard URL that can be used by multiple apps.
For universal URLs we can present a fallback web page if the app is not installed.

Specification

The first proposal for the deep link format is specified in #14044.

It does not specify the URL scheme, host or path, but it specifies the query parameters. The query parameters are:

• method - name of method Trezor Connect that is called
• params - JSON payload for the method
• callback - URL to where the response is redirected

The rest of the URL can depend on the environment used.

For production environments we should use a universal link, since mobile OS give some security guarantees with Android App Links and iOS Universal Links.
Also it's useful to provide a fallback, which could point to a web page that leads to the app download page on mobile or Connect Popup on desktop.

An example of what the URLs could look like:

Production: https:/connect.trezor.io/9/deeplink/?method=getAddress&params=%7B%22path%22:%22m/49%27/0%27/0%27/0/0%22%7D&callback=https://httpbin.org/get

Dev: https://dev.suite.sldev.cz/connect/<branch>/deeplink/?method=getAddress&params=%7B%22path%22:%22m/49%27/0%27/0%27/0/0%22%7D&callback=https://httpbin.org/get

Local: trezor-suite://connect-deeplink/?method=getAddress&params=%7B%22path%22:%22m/49%27/0%27/0%27/0/0%22%7D&callback=https://httpbin.org/get

The callback URL will be opened with a query parameter response that will contain a JSON encoded response from the method, in the same form as the usual Connect response.

Security

There are some security risks connected with deeplinks. The key part is that the app can be opened by a malicious website. To prevent this, we should check the origin of the deeplink, however that is not always possible directly - eg. the user can be instructed to copy-paste the URL.

A more reliable solution could be to verify the callback URL and only allow methods that are safe unless you have access to the callback's response data.
For example no broadcasting transactions, since they would be executed even if the callback is not verified.

There are still more security risks that need to be considered, such as the possibility of a malicious app intercepting the deeplink and executing it instead of the intended app.

Implementation

For handling the deeplinks, there should be a new package eg. @trezor/connect-deeplink
This package should consolidate methods for both creating and parsing the deeplink URLs.
These will be used in other parts of the codebase or 3rd party apps.

However the main way to use the deeplinks would be through an API that is compatible with TrezorConnect and simplifies the deeplink process itself.
This API would construct the deeplink URL and open it through a mechanism that would be provided during initialization, so it can be used in different environments.

For example with Expo, I imagine it could look like this:

import * as Linking from 'expo-linking';

await TrezorConnect.init({
  ...
  deeplinkOpen: (url) => {
    Linking.openURL(url);
  },
});

Linking.addEventListener('url', ({ url }) => {
  TrezorConnect.handleDeeplink(url);
});

// Method call - the deeplinking itself is abstracted
const response = await TrezorConnect.getPublicKey({ ... });

We could also support some of the environments directly.

Documentation

There specification should be documented in a new section in Connect Explorer, along with explanation of the use case and documentation of the implementation package.

Related

Epic #14248

[karliatto]

I think this is good enough just I was looking at the resources below:

• https://docs.expo.dev/guides/linking/#custom-url-schemes
• https://developer.uber.com/docs/riders/ride-requests/tutorials/deep-links/introduction#standard-deep-links

And might be interesting consider since it is used by projects in production.

uber://?client_id=<CLIENT_ID>&action=setPickup&pickup[latitude]=37.775818&pickup[longitude]=-122.418028&pickup[nickname]=UberHQ&pickup[formatted_address]=1455%20Market%20St%2C%20San%20Francisco%2C%20CA%2094103&dropoff[latitude]=37.802374&dropoff[longitude]=-122.405818&dropoff[nickname]=Coit%20Tower&dropoff[formatted_address]=1%20Telegraph%20Hill%20Blvd%2C%20San%20Francisco%2C%20CA%2094133&product_id=a1111c8c-c720-46c3-8534-2fcdd730040d&link_text=View%20team%20roster&partner_deeplink=partner%3A%2F%2Fteam%2F9383

So it would be:

https:/connect.trezor.io/9/deeplink/?method=getAddress&params[path]&params[coin]=btc&params[showOnTrezor]=true&callback[url]=https://httpbin.org/get

Edit: We decided to go with the JSON approach in the description of the issue.

[Hannsek]

Can we close this @martykan ?