@prettyfluid/zentinel v0.2.23

Installation and Usage

​

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

import { Zentinel } from "@prettyfluid/zentinel";
//init
const zentinel = new Zentinel();
const login = "user@mail.com";
const password = "somePass";
const clientId = "corporationName";

async function main() {
  const categoryId = 10; //ID of your category
  const user = await this.zentinel.restoreSession(publicKey!);
  //this will return a user Object, store the id param of this object to use as the "owner-id param" for the data decryption on the Java Agent
  const mapper = await zentinel.initDataMapper(categoryId);
  //use the CorporationName param from the Java Agent installation doc as the clientId
  const recordId = await mapper.saveData(data, clientId);
  // recordId = "7304f354-b432-4f84-a9e5-cb91a4cf46fb";
  //use this recordId as the "external-id" param to decrypt the data via the Java Agent
  return recordId;
}

//redirect user to zentinel page and get back public auth token
this.zentinel.loginWithRedirection(window.location.href + "?public=");

//get from url string
const public =
  "eyJhbHBoYSI6ImROY1ZIU1BjNWpyRDRTeEdZS0JCblhkaHNQbEY3Rk5rVTg1RXo4ZFl5QlE9I...";

main().then(console.log);
//data should be structured the same way it was structured while creating the category
const data = {
  firstName: "John",
  lastName: "Doe",
  address: {
    zip: "11004",
    city: "NYC",
    state: "New York",
  },
};

​

1. Install this package

​

npm install @prettyfluid/zentinel

​

2. Import and init

​

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

​

const zentinel = new Zentinel();

​

3. Get session token from the zentinel page

​

//redirect user to zentinel page and get back public auth token
this.zentinel.loginWithRedirection(window.location.href + "?public=");

//get from url string
const public =
  "eyJhbHBoYSI6ImROY1ZIU1BjNWpyRDRTeEdZS0JCblhkaHNQbEY3Rk5rVTg1RXo4ZFl5QlE9I...";

​

4. User login with existing public key

//get after previous step
const public =
  "eyJhbHBoYSI6ImROY1ZIU1BjNWpyRDRTeEdZS0JCblhkaHNQbEY3Rk5rVTg1RXo4ZFl5QlE9I...";

//authorize user
const user = await this.zentinel.restoreSession(publicKey);

​

5. 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 encrypted
const categoryId = 342;
const mapper = await zentinel.initDataMapper(categoryId);

​ Data encryption and storing to Zentinel servers ​

const myPrivateData = {
  firstName: "Peter",
  lastName: "Parker",
};
//Pass the corporation name (clientId) as the optional argument to share the data with the Corporation
const zentinelRecordId = await mapper.saveData(user, clientId);

​ 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. ​​

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 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

​ To encrypt 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, clientId);

​ 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. 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. Collapse