@prettyfluid/zentinel
Version:
Integration helper for Zentinel
263 lines (203 loc) • 6.49 kB
Markdown
## Installation and Usage
> This package is available for licensed users only. Please contact Info@Prettyfluid.com for licensing information.
>
> Code example:
>
```ts
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
```sh
npm install @prettyfluid/zentinel
```
### 2. Import and init
```ts
import { Zentinel } from "@prettyfluid/zentinel";
```
```ts
const zentinel = new Zentinel();
```
### 3. Get session token from the zentinel page
```ts
//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
```ts
//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
```ts
//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
```ts
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
```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.
## 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:
```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
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:
```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, 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
```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. 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