README

toolbox-bitwarden-helper

A helper to retrieve SPARTED secrets from bitwarden vault

Installation

yarn add toolbox-bitwarden-helper

We are using a service user with limited access to retrieve secrets needed by some scripts we do.

So you can't log with your personal bitwarden account.

You must provide SPARTED_BW_CI_EMAIL and SPARTED_BW_CI_MASTER_PASSWORD in the environment to use this package.

Class usage

This package export a class BwHelper so you can use it as follow

const BwHelper = require('toolbox-bitwarden-helper');

// This will log you to bitwarden cli and sync the vault on the machine
// the helper will keep the session active until you do a logout
const helper = new BwHelper();

// This will lock the vault and logout the user
helper.logout();

We are exposing login and sync method as follow

// Yay after that you're logged to the vault
// If you're already logged it will logout and generate a new session
helper.login();

// This will retrieve the last version of your online vault and save the date of the last sync
helper.sync();

But if the constructor do its job you don't have to use it.

⚠️ Important note

Don't forget to logout when you have finished your job with this package. Because the session is persisted until you'll lock the vault (this will revoke the session).

Methods

`Get` method

Take a string or an options object in parameter

Options object props:

search: The value to search in a bitwarden item
key: The bitwarden item key to compare with the search value (default to 'name')
exact: Boolean to control the match preference (default: true)
- false: it will search all the item occurrence that include search value and return an array
- true: will match exactly the same value and return one item
type: The bitwarden item type to retrieve, only itemis available for now

Some examples:

// Will retrieve a secret by its name
helper.get('secret-name');
/**
  {
    type: 'item',
    id: '5b081d65-2a09-4def-96a0-acca00fced56',
    name: 'secret-name',
    password: null,
    revisionDate: '2021-02-09T15:20:52.760Z',
    attachments: undefined
  }
*/

// Exact same than above, the previous example is just an alias of this call
helper.get({ search: 'secret-name' });
/**
  {
    type: 'item',
    id: '5b081d65-2a09-4def-96a0-acca00fced56',
    name: 'secret-name',
    password: null,
    revisionDate: '2021-02-09T15:20:52.760Z',
    attachments: undefined
  }
*/

// Will retrieve a password by its bitwarden id
helper.get({ search: '5b081d65-2a09-4def-96a0-acca00fced56', key: 'id' });
/**
  {
    type: 'item',
    id: '5b081d65-2a09-4def-96a0-acca00fced56',
    name: 'test-name',
    password: null,
    revisionDate: '2021-02-09T15:20:52.760Z',
    attachments: undefined
  }
*/

// Will retrieve all the password marching name including 'test' string
helper.get({ search: 'test', exact: false });
/**
  [{
    type: 'item',
    id: '5b081d65-2a09-4def-96a0-acca00fced56',
    name: 'test-name',
    password: null,
    revisionDate: '2021-02-09T15:20:52.760Z',
    attachments: undefined
  },{
    type: 'item',
    id: '5b081d65-2a09-4def-96a0-acca00fced56',
    name: 'test-unicorn',
    password: null,
    revisionDate: '2021-02-09T15:20:52.760Z',
    attachments: undefined
  }]
*/

`List` method

Will just return the same output than the following cli command

bw list (items|collections)

Here the flow typing declared to handle bitwarden item:

  type SearchItemType = 'item';

  type LoginInfo = {|
    username?: string,
    password?: string,
    passwordRevisionDate?: string,
  |};

  type Attachment = {|
    id: string,
    fileName: string,
    size: number,
    sizeName: string,
    url: string,
  |};

  type BitwardenItem = {|
    object: SearchItemType,
    id: string,
    organizationId: string,
    type: number,
    name: string,
    login: LoginInfo,
    collectionIds: $ReadOnlyArray<string>,
    revisionDate: string,
    attachments?: $ReadOnlyArray<Attachment>,
    folderId?: string,
  |};

Depends on

The official cli in node.js: @bitwarden/cli

Usage no npm install needed!