Store local data in a secure data vault.
npm install @webdisrupt/persona
npm i @webdisrupt/persona
`
Getting Started
Once installed, you will need to import the package and create a new instance. Each instance can house a single logged in persona. The persona will handle all the saving and and loading of data and abstract it to high level functions.
`javascript
import { persona } from 'persona';
let persona = new persona({
appName : "my-app-whereyoucanfindit-com",
path : "C:\\custom\personas";
recentlyLoaded : [],
previous : {}
});
`
$3
Although none of these parameters are technically required, we do reccommend at a bare minimium using the appName to help scope your data.
- appName: This should represent your application name and is used for scoping data. So you might want to make it a very long unique name.
- path: The default path is "C:\\personas". You can change this, but know that it will not detect their previous profile information. So it is not recommended to change this yourself, but instead allow the end-user to change instead.
- RecentlyLoaded: A minimal object referencing previously loaded profiles. There is no saving implemented for this yet, so you will have to save it yourself and pass it in on every new instance. If not provided it will load from the system.persona file.
Persona Seed Model
`javascript
{
id: "string",
username: "string",
avatar: "Base64",
location: "file location"
}
`
- pervious: Last loaded persona for quick reference on subsequent ussage. If not provided it will load from the system.persona file.
Upgrade from version to 3
Refactored the Persona functionality only to use the master password in encryption to simplify the system and allow users to change their username without re-encrypting all their data. This will break previously encrypted data. If you need to upgrade please copy over previous data, or I will add conversion features.
Upgrade from version 1 to 2
Some massive changes have happened in version 2.0. The qaulity and mantainability have been reimagined. The only noticable usability change is that storage block and directory storage block functionality is now located under the module object with more standardized names.
Response Model
All function calls have a standardized response object. It contains a status which provides a bool on success or failure. The second property is a user friendly message on what happened. The last is an optional data property that contians any data requested.
Standard response object model
`javascript
{status: boolean, message: string, data:any}
`
Persona Root
The persona root file is the core of the persona system and contains various standardized information. This file is json and contain a couple different encrypted pieces of data. This data can be unlocked and is the core of the persona system. It also stores all references to the data storage block which hold application specific information.
$3
Creating a new persona and starts referencing it in your session.
Essentially the same as creating a new account.
`javascript
persona.create("username", "password", 1);
`
$3
Loads an exisitng Persona and starts referencing it in your session. Essentially the same as logging in.
`javascript
persona.load("username", "password");
`
$3
Saves the persona that is currently referenced.
`javascript
persona.save();
`
$3
Deletes the currently referenced persona.
`javascript
persona.delete();
`
$3
Unloads the currently referenced persona. Essentially the same as logging out.
`javascript
persona.unload();
`
$3
Get all recently loaded profiles. This list is updated along with the previous user, on user login. (persona.load())
`javascript
persona.getRecentList();
`
$3
Check whether user is logged in. Additionally returns previously used simplified login data. See the Persona Seed Model.
`javascript
persona.isLoggedIn()
`
$3
Returns the loggedIn user's profile details. Note these are optional. See the Profile Model.
`javascript
persona.getProfile()
`
Profile Model
`javascript
avatar?: string,
firstName?: string,
lastName?: string,
phone?: string,
email?: string,
age?: Date,
gender?: string,
attributes?:Array // Profile Attribute is just a simple key value pair.
`
$3
Saves the loggedIn user's profile details. See the Profile Model.
`javascript
persona.saveProfile()
`
Module - Storage Blocks
What are Perona data storage blocks? A chunk of data that can take any format and has been secured using AES 256 encryption. Each block contains a unique id that is referenced by the root file. Each block contains a randomly generated file id so it cannot be identified. The id is structured as radnomFilename|uniqueApplicationName|uniqueDataBlockName. Please make your unique application name very unique to avoid collissions with other applications. This reference will be stored in your persona.root file and can be referenced after intial login is performed.
$3
Saves a block of data to an existing block or creates a new block based on the application id & save sotrage id.
`javascript
persona.module.storageBlock.save("unique-id-string", "Whatever format or data you want to save.")
`
$3
Loads a block of data from an existing block.
`javascript
persona.module.storageBlock.load("unique-id-string");
`
$3
Loads multiple storage blocks fluidly and assigns any storage block found to the corresponding object property. If the property is not found, then it assigns the previous data.
`javascript
let dataObject = {
block1: { prop1: "...", prop2: "..." },
block2: { prop1: "...", prop2: "..." },
block3: ["", "", ""]
}
persona.module.storageBlock.loadAll(dataObject);
`
$3
Deletes a storage block.
`javascript
persona.module.storageBlock.delete("unique-id-string");
`
$3
Gets all the storage block that are defined inside the current Persona.
`javascript
persona.module.storageBlock.getList();
`
Module - Storage blocks Directory
$3
Saves a directory to a data storage block. This allows you to protect entire folders. Use the last argument tells this function whether to clear this directory after it is saved. The third argument is optional.
`javascript
persona.module.storageBlockDirectory.save("directory/path", "unique-id-string", true);
`
$3
Creates a directory from loading a data storage block. This allows you to protect entire folders.
`javascript
persona.module.storageBlockDirectory.load("unique-id-string");
`
$3
Gets current load/save progress based on the provided storage block name.
`javascript
persona.module.storageBlockDirectory.getProgress("unique-id-string");
`
$3
Removes a directory and all files inside that directory based on storage block name.
`javascript
persona.module.storageBlockDirectory.removeDirectory("unique-id-string");
`
$3
Checks if a directory exists only using the current storage block name.
`javascript
persona.module.storageBlockDirectory.checkDirectory("unique-id-string");
`
$3
Marks a directory to a specific version. If a number is not provided it will increment the current known version. This tells the system if there has been any content changes to that directory. This is stored encrypted in a storage block and also as a pstore.version file. This function only updates the pstore.version file.
`javascript
persona.module.storageBlockDirectory.setVersion("unique-id-string", ?Number);
`
$3
Gets the current file version from the directories pstore.version file.
`javascript
persona.module.storageBlockDirectory.getVersion("unique-id-string");
``