@cogitojs/telepath-js
v0.3.0
Published
Secure communication channel between mobile app and web app
Downloads
115
Keywords
Readme
@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:
- The web app requests a secure connection to the mobile app by invoking the
createChannel
function on the javascript library. - The
createChannel
function generates a random channel idI
and a symmetric encryption keyE
. - The web app displays a QR code containing the channel id
I
and keyE
. - 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 keyE
.
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.