Telepath (JavaScript)

Provides a secure channel for communication between a web app running in a browser and an app running on a mobile device.

Setting up a secure channel between the mobile device and a browser is done using a QR code that is presented by the web app whenever a secure channel is required. The user can then open the secure channel by scanning the QR code using the app on the phone.

Description

Telepath consists of a javascript library that can be used in web apps, and an iOS library for mobile apps.

Because both the browser and phone are likely to be behind distinct NAT, we use a service with a public ip address to facilitate peer-to-peer communication between them. This is a fairly simple service that only holds end-to-end encrypted messages in queues.

The channel supports bi-directional communication; both from the web app to the mobile app, and vice-versa. A channel therefore consists of two queues, which we’ve named ‘blue’ and ‘red’. The red queue is used to send messages from the web app to the mobile app, and the blue queue is used for the reverse route.

The web app requests a secure connection to the identity app by invoking the createChannel function on the javascript library.

The createChannel function generates a random channel id I and a symmetric encryption key E.

The web app displays a QR code containing the channel id I and key E.

The owner of the phone opens the app, points the camera to the QR code.

The phone app extracts the channel id and the key from the QR code.

Both phone and web app can now communicate on channel I. They encrypt/decrypt their messages using key E.

QR Code

The channel id I and key E are first encoded in a URL, and then the URL is encoded in a QR code. This allows a user to scan the QR code using the standard camera app in iOS and be directed to the telepath-enabled mobile app.

Usage

Creating an instance of Telepath

You create an instance of Telepath by providing the URL of the queuing
service to the Telepath class:

const telepath =newTelepath('https://queuing.example.com')

Having an instance of Telepath, you can create a new channel
with a random id and a random encryption key as follows:

const channel =await telepath.createChannel({ appName:'My Web App'})

If you do not want the channel with a random id and a key, but rather recreate
the channel with the previously obtained id and the key, you can provide them
as additional attributes in the object passed to the createChannel method:

Obtaining a connection URL

At some point, you will need to create a QR code so that you can scan
with a mobile app and obtain the channel identifier and the symmetric
key as described above. Telepath provides a convenience method that given the base url
(see Section QR Code above) it return a properly formatted connection URL.
You can use this connection URL as an input to your QR code generation library.
The resulting QR code can be scanned by the mobile
app and used to connect to this channel. The telepath library does not include
functionality for displaying QR codes, you can use a QR code component such as
qrcode.react for this purpose.