@project-christopher/client-library v1.0.4

Introduction

Client Library | Encrypted communication tool (client side)

The project is maintained by Project Christopher.

Installation

To use client-library, you will need to import it from a separate NodeJS App.

To install it, use: npm i @project-christopher/client-lirary or yarn add @project-christopher/client-lirary.

Then, you can import it using:

import {Client} from "@project-christopher/client-lirary"

Usage

Initialize

Create an object for the library and initialize the library with the appropriate configuration.

Using default values:

let client: Client = new Client({encryption: {private_key: ""}});

or declare a path that points to your configuration file:

let client: Client = new Client("path/to/configuration.json");

or pass a JSON object directly

let client: Client = new Client({ ... });

An error will be thrown is case of invalid configuration.

Register events

The event must be string type, it can be random. but the library has blacklisted some events. These events are decided from each server driver. For example for socket.io driver is connection, connect, connect_error, disconnect, disconnecting, newListener, removeListener.

client.on('connection', async (client: Client, error_: string) => {
  if (!error_)
    console.log('Client with id ' + client.id + ' and ip address ' + client.address + ' authenticated successfully.');
  else
    console.log('Client with ip address ' + client.address + ' failed authentication, error code: ' + error_);
});

client.on('disconnect', async (client: Client, reason: string) =>
        console.log('Client with id ' + client.id + ' disconnected. Reason: ' + reason))

and a random event to receive data:

client.on('data', async (data: object, callback: any) => {
  // encrypted is an error_ if it is typeof string
  if (data.error_)
    return console.log('Encountered error for id', data.client.id, 'with error code:', data.error_);
  // Decrypt data
  let plainData = await data.decrypt();

  // Respond with an encrypted message (json or string).
  callback({message: 'Hello, World!'});
});

To stop listening on an event use:

client.off(eventName);

or stop listening all events:

client.offAll();

Connect and Disconnect

let id = "my-id" 
let extra = {test: 'pass'}

// Connect to server
await client.connect(id, JSON.stringify(extra))
//or
await client.connect(null, null) // do not sent extra and generate custom id from server.

// and disconnect from the server.
await client.disconnect();

If id is set to null then it will auto generate from the server side. In case of an error, connect function will throw an appropriate exception.

Emit

let event = 'data';
let dataToSend = {message: 'Hello, World!'}

// Emit data to a client
await client.emit(event, JSON.stringify(dataToSend));

// Emit data to a client and wait for reponse
await client.emit(event, JSON.stringify(dataToSend)
        , async (response) => console.log(response))

In case of an error, emit function will throw an appropriate exception.

Extra functions

Client library provides some extra functionalities.

// The configuration file can host other data except from the ones needed from the client library.
// You can access a copy of them using the following function:
let configuration = server.getConfiguration()

and the available drivers functions:

// Return the availale driver names.
console.log(Client.asyncEncryptionDrivers());
console.log(Client.syncEncryptionDrivers());
console.log(Client.serverDrivers());

Configuration

The configuration format for initializing the library (default).

{
  "connection": {
    "token": ""
  },
  "encryption": {
    "disable": false,
    "asynchronous": {
      "driver": "rsa",
      "bits": 2048,
      "public_key": ""
    },
    "synchronous": {
      "driver": "aes-128-gcm",
      "key_bytes": 190
    }
  },
  "client": {
    "driver": "socket.io",
    "address": "",
    /* socket.io */
    "socket.io": {
      "path": "/socket.io/"
    }
  }
}

• connection: all the information needed for the establishing a connection.
  • token: the token needed for verification (string or json)
• encrytpion: all the information needed for the encrypted communication.
  • disable: if true, the drivers are auto set to none and no encryption is applied.
  • asynchronous: the information for the asynchronous encryption.
    • driver: the asynchronous encryption driver
    • bits: the size of the encryption keys in bits. .
    • private_key: The private key of the server.
• synchronous: the information for the synchronous encryption.
  • driver: the synchronous encryption driver.
  • key_bytes: the length of the symmetric encryption key that will be generated, must not be greater than the asynchronous.bits / 8. If padding is applied then the number must be less.
• client: the information needed for the client.
  • driver: The server driver.
  • address: The server's address where the client will connect.
  • socket.io: Extra configuration for the socket.io driver.
    • path: It is the name of the path that is captured on the server side.
• broadcast: the information needed for the broadcast server.
  • port: The port where the broadcast server will listen.

Available Drivers

• Asynchronous encryption: rsa, none
• Synchronous encryption: aes-128-gcm, none
• Server: socket.io

Create custom drivers

Create a file and put inside the driver folder (either for server or encryption). The file must export a class that extends the appropriate parent class, AsyncDriver, SyncDriver, ServerDriver. Then edit the appropriate driver file to return the driver.