@cogitojs/telepath-js

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.

Setting up a secure channel is done using these steps:

1. The web app requests a secure connection to the mobile app by invoking the createChannel function on the javascript library.
2. The createChannel function generates a random channel id I and a symmetric encryption key E.
3. The web app displays a QR code containing the channel id I and key E.
4. The owner of the phone opens the app, points the camera to the QR code.
5. The phone app extracts the channel id and the key from the QR code.
6. Both phone and web app can now communicate on channel I. They encrypt/decrypt their messages using key E.

Telepath channels 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.

-------------                             ------------
|    web    |  ---------- red ----------> |  mobile  |
|    app    |  <--------- blue ---------- |    app   |
-------------                             ------------

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.

An example of such a URL and its QR Code:

https://example.com/telepath/connect#I=2oxSJ6_eyP7JXsn6VK7ooB_u&E=m8JzVbVlEwlzzR0-o8-AU0F6oONYcqvLW5YVLvLLP6s

The URL is made up of the following components:

<base url>telepath/connect#I=<channel id>&E=<encryption key>

where:

• <base url> is the url that is registered to open the mobile app in iOS or Android
• <channel id> is the channel id string, percent encoded for use in a URL fragment
• <encryption key> is the encryption key, base64url encoded

Usage

Add @cogitojs/telepath-js as a dependency:

yarn add @cogitojs/telepath-js

Then import Telepath in your own module:

import { Telepath } from '@cogitojs/telepath-js'

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 = new Telepath('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:

const channel = await this.telepath.createChannel({
  id: channelId,
  key: channelKey,
  appName: 'My Web App'
})

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.

const connectUrl = channel.createConnectUrl('https://example.com')
// returns: https://example.com/telepath/connect#I=<channelId>&E=<symmetricKey>

Sending messages through the channel

Messages are exchanged using JSON-RPC:

const request = { jsonrpc: '2.0', method:'test', id: 1 }
const response = await channel.send(request)

The send method returns a promise. The queuing service will be polled for a response for at least 10 minutes. If no response is available after this time it will return null.

Notifications

Telepath also supports "fire and forget"-style notifications. So instead of a request-response loop, you can send a message and forget about it, or you can register a notification handler to receive incoming notifications.

If you want to be able to receive notifications, after creating the Telepath channel you need to call startNotifications and subscribe for notifications:

await channel.startNotifications()
const subscription = channel.subscribeForNotifications(message => {
  console.log('received notification: ' + message)
}, error => {
  console.log('notification error: ' + error)
})
// later...
channel.unsubscribeForNotifications(subscription)

Sending notifications work like this (please remember that notifications must be valid JSON-RPC 2.0 message):

const notification = { jsonrpc: '2.0', method:'test' }
await channel.notify(notification)

Please note that the channel.notify promise being resolve only means that the notification was sent, not that it was received by the other party.

Unit Testing

This module provides a test double that you can use in your unit tests. This test double prevents real network communication from happening. It is very limited in functionality but it will suffice for many purposes. Have a look at telepath-mock.js to review the exact capabilities.

You can use the test double by creating a manual mock in your workspace. Put a file named telepath-js.js in the folder your-project/src/__mocks__/@cogitojs. Inside that file, put the following statement:

export { Telepath } from '@cogitojs/telepath-js/source/telepath-mock'

Known Limitations

Currently uses independent encryption of messages. A recipient can therefore not detect if some messages have been duplicated, deleted or reordered.