# secure-vault

> Secure, password based symetric encryption.

Latest version **2.0.0** (published 2020-07-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install secure-vault
pnpm add secure-vault
yarn add secure-vault
bun add secure-vault
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2020-07-13 |
| First published | 2020-07-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=0.10.0 |
| Dependencies | 2 |
| Unpacked size | 90.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Forbes Lindesay |
| Maintainers | forbeslindesay |

## Links

- npm: https://www.npmjs.com/package/secure-vault
- Repository: https://github.com/ForbesLindesay/secure-vault
- Homepage: https://github.com/ForbesLindesay/secure-vault#readme
- Issues: https://github.com/ForbesLindesay/secure-vault/issues
- npm.io page: https://npm.io/package/secure-vault

## Dependencies (2)

- [ts-opaque](https://npm.io/package/ts-opaque.md) ^2.1.1
- [byte-base64](https://npm.io/package/byte-base64.md) ^1.0.2

## Recent versions

- 2.0.0 (latest) — 2020-07-13
- 1.0.0 — 2020-07-11

## README

# secure-vault

Secure, password based symetric encryption. When you create a "vault" it can be used to encrypt and decrypt multiple messages with a single password.

> N.B. server side usage requires at least node.js version 14

[![Rolling Versions](https://img.shields.io/badge/Rolling%20Versions-Enabled-brightgreen)](https://rollingversions.com/ForbesLindesay/secure-vault)

## Installation

```
yarn add secure-vault
```

## Usage

```ts
import {
  createVault,
  unlockVault,
  password,
  secretData,
  secretDataToString,
} from 'secure-vault';

const unlocked = createVault(password('My super secure password'));

// You can encrypt something using the unlocked vault. The resulting cipherText
// safe to share:
const encrypted = unlocked.encrypt(secretData('My secret message'));

// To access the data later, you'll need a way to retrieve the same vault.
// To do this, you can `lock` the vault, which creates a serializable
// copy of the vault that can only be unlocked using the password.
const locked = unlocked.lock();

// Assuming you've saved the `lockedVaultStr` and `cipherTextStr`, and you know
// the secret password, you can unlock the vault and then decrypt your data:
const unlocked2 = unlockVault(locked, password('My super secure password'));

const secret = secretDataToString(unlocked2.decrypt(encrypted));
console.log(secret);
// => 'My secret message'
```

## API

### `Password`

The password is the secret phrase that's used to encrypt the data. Ideally this should be as long as possible, to keep the data secure. You can create a `Password` from a `string` using:

```ts
import {password} from 'secure-vault';

const pwd = password('My Secret Pass Phrase');
```

_(You can alternatively create one from a Uint8 array by passing the Uint8 array to `password`)_

### `SecretData`

The secret data is the data you want to encrypt, or the data you have decrypted. You can create `SecretData` from a `string` using:

```ts
import {secretData} from 'secure-vault';

// N.B. "data" here is not yet encrypted
const data = secretData('A secret I want to hide');
```

You can also convert `SecretData` back into a string using:

```ts
import {secretDataToString} from 'secure-vault';

// N.B. "data" here is not yet encrypted
const str = secretDataToString(data);
```

_(You can alternatively use a Uint8 array by passing the Uint8 array to `secretData`)_

### `EncryptedData`

The encrypted data is safe to share publicly. The only way to decrypt the encrypted data is to have access to either the `UnlockedVault` or both the `LockedVault` and the `Password`. You can directly store the encrypted data as a `Uint8Array` or you can convert it to and from a string:

```ts
import {encryptedData, encryptedDataToString} from 'secure-vault';

const str = encryptedDataToString(encrypted);
const encrypted = encryptedData(str);
```

### `LockedVault`

A locked vault represents the key used to encrypt and decrypt the data, but it cannot be used until it's unlocked. The only way to unlock it is with the password. The locked vault must be stored somewhere along with the encrypted data, but you can reuse the same vault for many different encrypted values. You can directly store the locked vault as a `Uint8Array` or you can convert it to and from a string:

```ts
import {lockedVault, lockedVaultToString} from 'secure-vault';

const str = lockedVaultToString(locked);
const locked = lockedVault(str);
```

### `UnlockedVault`

An unlocked vault represents a vault with its associated password. You can use the unlocked vault to encrypt and decrypt any amount of data you need. To store the keys, you should "lock" the vault.

Creating a vault:

```ts
import {createVault, password, lockedVaultToString} from 'secure-vault';

const unlocked = createVault(password('My secret password'));
const lockedStr = lockedVaultToString(unlocked.lock());
```

Unlocking a vault:

```ts
import {unlockVault, password, lockedVault} from 'secure-vault';

const unlocked = unlockVault(
  lockedVault(lockedStr),
  password('My secret password'),
);
```

#### `unlockedVault.encrypt(secretData: SecretData) => Promise<EncryptedData>`

You can call `unlockedVault.encrypt` to encrypt some secret data:

```ts
const encryptedStr = encryptedDataToString(
  await unlockedVault.encrypt(secretData('My Secret Message')),
);
```

#### `unlockedVault.decrypt(encryptedData: EncryptedData) => Promise<SecretData>`

You can call `unlockedVault.encrypt` to decrypt some encrtyped data:

```ts
const mySecretMessage = secretDataToString(
  await unlockedVault.decrypt(encryptedData(encryptedStr)),
);
```

#### `unlockedVault.lock() => LockedVault`

You can get a locked vault for storage by calling `unlockedVault.lock()`.

## Notes regarding security

- Secure Vault uses a randomly generated 96 bit IV. This means you should not encrypt more than 2^32 secrets using one vault: https://crypto.stackexchange.com/a/66500/723
- Secure Vault usese a 128 bit salt. This should be acceptable for most use cases: https://stackoverflow.com/a/5197921/272958
- Secure Vault uses 200,000 iterations for PBKDF2. At time of writing this is approximately 2x the default for [lastpass](https://support.logmeininc.com/lastpass/help/about-password-iterations-lp030027#:~:text=By%20default%2C%20the%20number%20of,process%20in%20your%20Account%20Settings.)

These values are not configureable, but the encrypted data from Secure Vault is versioned, so we will be able to change the defaults in a non-breaking way once these defaults no longer provide an appropriate level of security.

---
_Source: https://npm.io/package/secure-vault · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._