@prettyfluid/zentinel/README-INTERNAL.md

Integration helper for Zentinel

# Installation and Usage

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

### 1. Install this package

```sh
    npm install @prettyfluid/zentinel
```

### 2. Import and init

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

```ts
const zentinel = new Zentinel();
```

### 3. Register new user and authorise

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

//identifier of your company in Zentinel
const clientId = "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/decrypt your data, sharing the data with the Corporation

Create a mapper from the pre-defined category id for data encryption/decryption

```ts
//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

```ts
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 key as the optional argument to share the data with the Corporation
const zentinelRecordId = await mapper.saveData(user, "myCorporationName");
```

Load and decrypt the previously stored object

```ts
const decryptedData = await mapper.loadData(zentinelRecordId);

//The decryptedData object will looks like
//decryptedData:
//{
//    firstName: 'Peter',
//    lastName: 'Parker',
//    zentinelId: '68ba2d97-1ac3-410d-bb87-e8d816c006c1'
//}
```

# 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/handing messages.

### Initialization

```ts
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:

```ts
//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:

```ts
//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:

```ts
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 store the encrypted information and retrieve it. Zentinel can work with any type of javascript object. For storing and retrieving the correct data format it requires a special schema, called Category. To create custom categories, contact the Zentinel support. As a result the Id of the category is provided. This categoryId declares the data model to be encrypted and stored. This categoryId has to be stored inside of your application (for example - as enum/dictionary). This catagoryId will be used to encrypt/decrypt all the objects of the needed format. For example, the category for the following data models:

```ts
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:

```js
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:

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

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

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

```ts
const userRecordId = await mapper.saveData(user, "myCorporationName");
```

By the resulting id the stored object can be restored.
Use the method loadData from mapper with the same category:

```ts
const existingUser = await mapper.loadData();

//resultingObject:
// {
//    firstName: 'Peter',
//    lastName: 'Parker',
//    zentinelId: '68ba2d97-1ac3-410d-bb87-e8d816c006c1'
//    phones: [{
//        number: '12026518652',
//        mobile: true,
//        zentinelId: '0be37752-f049-4ab6-a801-2dc03ea439eb'
//    }]
// }
```

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

```ts
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.