A NodeJS password vault.
Please be aware that breaking changes will occur during 0.* (alpha) development. Until 1.0 is released, assume that every minor version contains breaking changes to encryption, structure and API.
Archives that contain
Entrys. Together, in a nested structure, these items act as a secure store for a user's credentials (much like standard managers these days). Entries allow you to store a credential's username and password, along with other miscellaneous properties (meta) and invisible functional info (attributes).
Buttercup archives sit in memory as an Object instance that is built from delta-style commands that modify the structure. As changes are made to the archive, new delta commands are added to the history and saved to the archive's
Datasource. Archives are compressed and encrypted before being saved.
The core of the system, this Buttercup Core, boasts a few awesome features:
This library also supports a variety of datasources for loading from and saving to:
Buttercup can easily be imported and used in NodeJS applications from version 4.x and upwards:
const Buttercup = ; // buttercup-core is "buttercup" on npm
Archives are easily created by making a new instance:
const Archive = ButtercupArchive;let myArchive = ;
Groups can be created within other groups or archives:
let websitesGroup = myArchive;let bankingGroup = websitesGroup;
Entries can be created within groups, which hold authentication information:
let worldBank = bankingGroup;worldBank;
Entries can be moved to other groups, and groups to other groups or archives:
worldBank;bankingGroup; // move up to the root level
Groups and entries can easily be deleted:
myEntry; // `myEntry` reference no longer validmyGroup; // `myGroup` reference no longer valid
It's important to note that just because a group or entry is deleted, does not mean that its corresponding information has. Historical commands are still stored in the archive dataset until they are flattened (after several thousand following commands).
Archives can be saved with datasources:
const FileDatasource createCredentials = Buttercup;let ds = "~/myArchive.bcup";ds;ds;
Archives can be managed more easily using a
Workspace. Workspaces are designed to handle a primary archive and potentially several shared archives, each with their own master password and datasource. When integrating with Buttercup server, workspaces allow you to handle multiple shared archives where groups can be handled by multiple users.
const Workspace createCredentials = Buttercup;let workspace = ;workspace;workspace;
Workspaces also allow you to detect conflicts before saving so you can perform merges on the local content:
You can search within archives for certain entries or groups:
You can import from other password archive formats, such as KeePass. Checkout the Buttercup Importer project.
Some things in Buttercup are best run purely on Node, such has password-based key derivation. When preparing this for the web or other platforms (such as with Webpack or Browserify), things can move very slowly. There are implementations for functions, such as PBKDF2, that exist for web use that are many times faster than the output of such build utilities.
You can override PBKDF2 by doing the following (documented on iocane):
const Buttercup = ;Buttercupvendoriocanecomponents;// Where 'newPBKDF2Function' is a function that returns a Promise with the hash in a Buffer
Using a native PBKDF2 implementation is always advisable, for speed, as this is usually the most intense procedure within Buttercup (computationally).
You can also override the built in encryption methods used in iocane - This can be very useful in other environments aswell:
const Buttercup = ;Buttercupvendoriocanecomponents;Buttercupvendoriocanecomponents;
Specifying new crypto methods can help with compatibility. Check iocane's documention on how to use these methods.
webdav-fs under the hood for support of several storage providers, and this in turn uses
node-fetch for requests.
node-fetch does not work in every environment (such as React-Native) and needs to be switched for a native alterative, like
global.fetch. Webdav-fs supports this via the
setFetchMethod, which can be called in Buttercup like so:
const Buttercup = ;ButtercupvendorwebdavFS;// Where `global.fetch` is a fetch-API supporting method
Entries and groups have attributes, describing how they should be treated by the various interfaces that interact with the archive. Attributes are not visible to the users and can contain a variety of different properties.
For instance, you could get the role of a group like so:
let groupRole = group;
Entry types and facades are documented separately.
Buttercup supports the DEBUG environment variable. You can debug an application using Buttercup like so:
This also works when running the tests:
DEBUG=buttercupcore:* npm test
The iocane submodule also supports DEBUG:
DEBUG=buttercupcore:*,iocane ./app# orDEBUG=buttercupcore:*,iocane npm test