Table of Contents

ItemKeyStore

Manages a set of item keys. This includes generation, encryption, and decryption of the set.

Parameters

  • self Object? The properties of this ItemKeyStore

encryptKey

The master encryption key.

Type: jose.JWK.Key

id

The keystore identifier.

Type: string

group

The group name.

Type: string

encrypted

The encrypted key set, as a Compact JWE.

Type: string

toJSON

Creates a JSON representation of this ItemKeyStore. This method returns a plain Object with the following properties:

  • group {String} The name of the keystore's group
  • encrypted {Stirng} The encrypted map of keys

Returns Object The JSON representation

load

Loads the item keys. This method decrypts the stored encrypted key set using the current or specified master encryption key.

If {master} is provided, it overwrites the current master encryption key.

Parameters

  • master jose.JWK.Key? The new master encryption key to use

  • Throws Error If the master encryption key is not set, or there is no encrypted key set, or encryption fails

Returns ItemKeyStore This ItemKeyStore

save

Saves the item keys. This method serializes the item keys into and encrypts them using the current master encryption key.

Once this method completes, {encrypted} is set to the newly encrypted key set.

  • Throws Error If the master encryption key is invalid, or encryption fails

Returns ItemKeyStore This ItemKeyStore

clear

Clears all decrypted values. Optionally, it also clears the encrypted store.

Parameters

  • all boolean true to also delete encrypted keys (optional, default false)

Returns ItemKeyStore This ItemKeyStore

size

The number of item keys available (not encrypted).

Type: number

all

Retrieves all of the item keys. The returned map is a snapshot of the current state, and will not reflect any changes made after this method is called.

Returns Map<string, jose.JWK.Key> The list of item keys.

get

Retrieves an item key for the given id.

Parameters

  • id string The item key identifier

Returns jose.JWK.Key The item key, or undefined if not known

add

Adds an item key for the given id. If a key for {id} is already known, it is returned instead of generating a new one.

Parameters

  • id string The item key identifier

Returns jose.JWK.Key The new or existing item key

delete

Removes the item key for the given id.

Parameters

  • id string The item key identifier

Returns void

protect

Encrypts an item.

The {item} is expected to have a string id property, which is used to match it its key. If a key for the item's id does not exist, it is first created.

Parameters

  • item Object The item to encrypt

  • Throws Error if {item} is invalid, or if encryption failed

Returns string The encrypted item as a compact JWE

unprotect

Decrypts an item.

Parameters

  • id string The item id
  • jwe string The encrypted item as a compact JWE

  • Throws Error if {id} or {jwe} is invalid, or if decryption failed

Returns Object The decrypted item

DEFAULT_KEYSTORE_ID

Default keystore identifier.

Type: string

DEFAULT_KEYSTORE_GROUP

Default keystore group name.

Type: string

DataStore

Represents item storage.

Parameters

  • cfg Object The configuration parameters.

prepare

Prepares this DataStore. This method:

  1. initializes and opens the local database; and
  2. loads any stored keys from the local database.

If the database is already prepared, this method does nothing.

Returns DataStore This DataStore.

initialized

Indicates whether this DataStore is initialized.

Type: boolean

initialize

Initializes this DataStore with the given options. This method creates an empty item keystore, and encrypts it using the password specified in {opts}.

NOTE: If {salt} is provided here, it overrides and replaces any previously set salt, including from {DataStore.open}.

Parameters

  • opts Object The initialization options
    • opts.appKey jose.JWK.Key? The master app key to setup with
    • opts.salt string? The salt to use in deriving the master keys
    • opts.rebase boolean Rebase an already initialized DataStore to use a new password (optional, default false)

Returns DataStore This datastore

reset

Resets this Datastore. This method deletes all items and keys stored. This is not a recoverable action.

Returns DataStore This datastore instance

locked

Indicates if this datastore is locked or unlocked.

Type: boolean

lock

Locks this datastore.

Returns DataStore This DataStore once locked

unlock

Attempts to unlock this datastore.

Parameters

  • appKey jose.JWK.Key The application key to unlock the datastore

Returns DataStore This DataStore once unlocked

list

Retrieves all of the items stored in this DataStore.

Returns Map<string, Object> The map of stored item, by id

get

Retrieves a single item from this DataStore

Parameters

  • id string The item id to retrieve

Returns Object The JSON representing the item, or null if there is no item for {id}

add

Adds a new item to this DataStore.

The {id} of the item is replaced with a new UUID.

Parameters

Returns Object The added item, with all fields completed

update

Updates an existing item in this DataStore.

{item} is expected to be a complete object; any (mutable) fields missing are removed from the stored value. API users should call #get, then make the desired changes to the returned value.

Parameters

  • item Object The item to update

  • Throws Error if this item does not exist

  • Throws TypeError if item is not an object with a id member
  • Throws DataStoreError if the item violates the schema

Returns Object The updated item

touch

Touches an existing item in this DataStore.

{item} is expected to be a complete object. API users should call #get, then pass the returned value to {touch}

Parameters

  • item Object The item to touch

  • Throws Error if this item does not exist

  • Throws TypeError if item is not an object with a id member
  • Throws DataStoreError if the item violates the schema

Returns Object The updated item

remove

Removes an item from this DataStore.

Parameters

  • id string The item id to remove

Returns Object The removed item, or null if no item was removed

open

Creates a new {DataStore} using the given configuration, and prepares it for use. This method calls DataStore#prepare, returning the (promised) DataStore once it's ready for use.

The signature for {recordMetric} (if provided) should conform to the following:

async function recordMetric(method, id, fields) {
  // {method} is one of "added" | "updated" | "deleted"
  // {id} is the item.id
  // {fields} either:
  // * array strings denoting which fields were changed (if method === "updated")
  // * undefined (otherwise)
}

Parameters

  • cfg Object? The configuration parameters
    • cfg.bucket string The bucket to persist data to (optional, default "lockbox")
    • cfg.salt string? the salt to use for key derivations
    • cfg.recordMetric Function? The function to record item metrics events

Returns DataStore A new (prepared) DataStore

DEFAULT_BUCKET

Default bucket name to use for localdatabase.open.

Type: string

DATABASE_VERSION

The current (local) database version number.

Type: number

open

Opens a (Dexie) Database with the given (bucket) name. This method: 1. creates a new Dexie instance; 2. initializes up to the latest; and 3. opens the database

Parameters

  • bucket string? The name of the database.

Returns Dexie The initialized and opened Dexie database.

DataStoreError

Extends Error

Errors specific to DataStore operations.

Parameters

  • reason string The reason for the error (optional, default DataStoreError.GENERIC_ERROR)
  • message string? The error message

reason

The reason name for this DataStoreError.

Type: string

DataStoreError.LOCKED

An attempt was made to use a datastore that is still locked.

Type: string

DataStoreError.LOCALDB_VERSION

When opening a local database, the actual database version does not match the expected version.

Type: string

DataStoreError.NOT_INITIALIZED

The datastore is not yet initialized.

Type: string

DataStoreError.INITIALIZED

An attempt was made to initialize a datastore that is already initialized.

Type: string

DataStoreError.MISSING_APP_KEY

No master key was provided.

Type: string

DataStoreError.WRONG_APP_KEY

The master key is not valid for the encrypted data.

Type: string

DataStoreError.OFFLINE

An operation requires network connectivity, but there is none.

Type: string

DataStoreError.INVALID_ITEM

The item to be added/updated is invalid.

Type: string

DataStoreError.MISSING_ITEM

The item to be updated does not exist.

Type: string

DataStoreError.GENERIC_ERROR

An otherwise unspecified error occurred with the datastore.

Type: string

DataStoreError.SYNC_LOCKED

An attempt was made to sync a datastore, but cannot be completed until unlocked.

Type: string

DataStoreError.NETWORK

An operation encountered a (generic) network error.

Type: string

DataStoreError.AUTH

An operation requires (remote) authentication before it can be performed.

Type: string

DataStoreError.CRYPTO

There was a cryptographic error.

Type: string