Idsync core library

A NodeJS secrets vault.

Installation

To use idsync in a NodeJS environment, you can simply install and require it:

npm install idsync --save

In a Node environment, for example:

const { Vault } = require("idsync");

Or for Typescript:

import { Vault } from "idsync";

In a web environment, use the following:

import { Vault } from "idsync/web";

Idsync core supports Node version 12 and up. Most features may work on Node 10, but it is not officially supported.

Usage

Idsync uses Vaults, Groups and Entrys to manipulate data in a workspace-like environment. These 3 constructs have no knowledge of encryption or storage, and simply provide interfaces for working with the data structures.

To manage vaults, their storage and their states in a higher-level manner more appropriate for building applications, check out the VaultManager and VaultSource constructs.

To get started, we should create a new Vault:

import { Vault, init } from "idsync";

// Initialise environment
init();

// Create an empty vault
const vault1 = new Vault();

// Create aa vault with "General" and "Trash" groups
const vault2 = Vault.createWithDefaults();

The init() function call is used to initialise the environment (performs the same function as @idsync/app-env used to). It is required for Idsync to work. It can be called more than once without effect.

Entries can't be added directly to a Vault, but can be to Groups. Creating Groups and Entries is trivial:

const vault = Vault.createWithDefaults();
const myGroup = vault.createGroup("My Group");
const myEntry = myGroup.createEntry("My Entry");

Every command on Vaults, Groups and Entries modifies the Vault instance, but does not save it to storage. There is no command or need to commit any data - each instance links back to the original Vault. Vaults are saved and loaded using Datasources:

import { Credentials, FileDatasource, Vault, init } from "idsync";

init();

const datasourceCredentials = Credentials.fromDatasource({
    path: "./user.denali"
}, "masterPassword!");
const fileDatasource = new FileDatasource(datasourceCredentials);
const vault = Vault.createWithDefaults();
vault
    .createGroup("Websites")
        .createEntry("My bank")
            .setProperty("username", "user-name")
            .setProperty("password", "s3cureP4$");

const vaultCredentials = Credentials.fromPassword("masterPassword!");
await fileDatasource.save(vault.format.history, vaultCredentials);

Later:

const datasourceCredentials = Credentials.fromDatasource({
    path: "./user.denali"
}, "masterPassword!");
const fileDatasource = new FileDatasource(datasourceCredentials);

fileDatasource
    .load(datasourceCredentials)
    .then(Vault.createFromHistory)
    .then(vault => {
        // ...
    });

Vault Formats

Idsync currently supports 2 concurrent vault formats, as it is in the process of transitioning from Format A (legacy) to Format B. You can switch the operational format by doing the following:

const { VaultFormatB, init, setDefaultFormat } = require("idsync");

init();

setDefaultFormat(VaultFormatB);

Idsync will automatically transition to using Format B as the default in some weeks or months (since v5 was released).

Compatibility

Idsync's compatibility is defined as the following:

• NodeJS version 12 and up
• Current versions of the following browsers:
  • Google Chrome
  • Mozilla Firefox
  • Safari
• React Native 0.60+

Browser support is strictly dependent on:

• Popularity
• The availability of required crypto libaries such as SubtleCrypto