@prettyfluid/zentinel-dev v0.1.13

Installation and Usage

This package is available for licensed users only. Please contact Info@Prettyfluid.com for licensing information.

1. Install this package

npm install @prettyfluid/zentinel

2. Import and init

import { Zentinel } from "@prettyfluid/zentinel";

const zentinel = new Zentinel();

3. Register new user and authorise

//credentials
const email = "user@example.com";
const password = "SecurePassword";

//identifier of your Corporation in Zentinel
const corporationId = "myCorporationName";

await zentinel.registration(email, password, clientId);
await zentinel.login(email, password, clientId);

//authorisation token for your server
const token = await zentinel.getToken();

4. Encrypt the data, share the data with the Corporation

Create a mapper from the pre-defined category id for data encryption and storing

//the id of pre-defined category that declares the format of the object to be decrypted
const categoryId = 342;
const mapper = await zentinel.initDataMapper(categoryId);

Data encryption and storing to Zentinel servers

const myPrivateData = {
  firstName: "Peter",
  lastName: "Parker",
};

//Returns an id of encrypted record in the Zentinel platform
const zentinelRecordId = await mapper.saveData(myPrivateData);

//Pass the corporation name (corporationId) as the optional argument to share the data with the Corporation
const zentinelRecordId = await mapper.saveData(user, corporationId);

Store the zentinelRecordId to encrypt the data using the Java Agent.

General information

This package is a wrapper for the original Zentinel application to simplify the communication process and determine the API format.The main Zentinel app is a specific iframe and this package helps with its initialization and sending/receiving messages.

Initialization

const zentinel = new Zentinel();

Construction of a new instance of Zentinel iframe also puts a new iframe to the web page and its instance has to be a singleton and has to be provided to other parts of the web application.

Auth

Before starting to work with the data encryption/description any data manipulations the authorisation to the system should be done. Use the following methods to create new user:

//creating a new User
const user = await zentinel.registration(email, password, clientId);
//provide mail confirmation token from redirect link:
const confirmationToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...";
await zentinel.confirmEmail(confirmationToken);

After that you can login into zentinel:

//login as an existing User
const existingUser = await zentinel.login(email, password, clientId);

These methods return a promised instance of the created/authorized user. After that the data methods can be used. Optionally, the bearer token can be retrieved using the method below:

const token = await zentinel.getToken();
//'Bearer eyJhbGciOiJSUzI1...'

Zentinel iframe is managing this token by it's own, no additional actions are required to work with this package.

Data processing

Categories

The key feature of the Zentinel application is the ability to securely store and retrieve the data. For storing and retrieving the correct data format the application requires a special schema, called Category. Contact the Zentinel support to receive the categoryId for your application. categoryId declares the data model (the format of the data) for the encryption.

The categoryId has to be stored in your application (for example as a config variable). It will be used to encrypt/decrypt all the objects of the needed format.

For example, the category for the following data models:

enum categories {
  userInfo = 10, //pre-defined category id
}

//example of data model defined by this category
interface userInfo {
  firstName: string;
  lastName: string;
  phones: {
    number: string;
    mobile: boolean;
  }[];
}

or the js implementation:

const categories = {
  userInfo: 10, //pre-defined category id
};

//example of data model, defined by this category
const userInfo = {
  firstName: "",
  lastName: "",
  phones: [
    {
      number: "",
      mobile: true,
    },
  ],
};

Mapper and data encrypting/decrypting

To encrypt/decrypt the data, a mapper should be created. This mapper will map the data, declared by corresponding category. Use fabric method initDataMapper from Zentinel, which loads the category by id and inits a mapper instance:

const mapper = await zentinel.initDataMapper(categories.userInfo);

Now it can be used to process all objects with this format:

const user = {
  firstName: "Peter",
  lastName: "Parker",
  phones: [
    {
      number: "12026518652",
      mobile: true,
    },
  ],
};
//to encrypt and store the data, just use the saveData method from mapper:
const userRecordId = await mapper.saveData(user);

Pass the corporation key as the optional argument to share the data with the Corporation

const userRecordId = await mapper.saveData(user, corporationId);

By the resulting id the stored object can be restored via the Java Agent

For modifying the records the same method saveData should be used Zentinal application automatically detects the existing record by provided field zentinelId and makes the required updates

existingUser.firstName = "John";
existingUser.lastName = "Doe";
await mapper.saveData(existingUser);

Data convert and specific use-cases

Before the start of the encryption process, Zentinel automatically casts provided properties to string format (and deserialize when decrypting). It works only with simple data types, and different blobs/images/files must be converted to base64 format on the client-side. Note: when encrypting stringified boolean/number/etc values, those will be cast to related types on decrypting.