npm package: @stead/sls
Description: > Secures localStorage data with high level of encryption and data compression.
Latest version: 1.0.1

# SLS (Secure Local Storage)

> Secures localStorage data with high level of encryption and data compression.

A custom fork of [Secure LS](https://github.com/softvar/secure-ls) 

## Installation

```
$ yarn add @stead/sls
```

## Scripts

* `yarn build` - produces production version of the library under the `dist` folder
* `yarn dev` - produces development version of the library and runs a watcher
* `yarn test` - runs the tests :)

## Libraries used

* **Encryption / Decryption** using [The Cipher Algorithms](https://code.google.com/archive/p/crypto-js)

  It requires secret-key for encrypting and decrypting data securely. If custom secret-key is provided as mentioned below in APIs, then the library will pick that otherwise it will generate yet another very `secure` unique password key using [PBKDF2](https://code.google.com/archive/p/crypto-js/#PBKDF2), which will be further used for future API requests.

  `PBKDF2` is a password-based key derivation function. In many applications of cryptography, user security is ultimately dependent on a password, and because a password usually can't be used directly as a cryptographic key, some processing is required.

  A salt provides a large set of keys for any given password, and an iteration count increases the cost of producing keys from a password, thereby also increasing the difficulty of attack.

  Eg: `55e8f5585789191d350329b9ebcf2b11` and `db51d35aad96610683d5a40a70b20c39`.

  For the generation of such strings, `secretPhrase` is being used and can be found in code easily but that won't make it unsecure, `PBKDF2`'s layer on top of that will handle security.

* **Compresion / Decompression** using [lz-string](https://github.com/pieroxy/lz-string)

## Usage

* Example 1: With `default` settings i.e. `Base64` Encoding and Data Compression

```
> var ls = new SLS();
> ls.set('key1', {data: 'test'}); // set key1
> ls.get('key1'); // print data
  {data: 'test'}
```

* Example 2: With `AES` Encryption and Data Compression

```
> var ls = new SLS({encodingType: 'aes'});
> ls.set('key1', {data: 'test'}); // set key1
> ls.get('key1'); // print data
  {data: 'test'}

> ls.set('key2', [1, 2, 3]); // set another key
> ls.getAllKeys(); // get all keys
  ["key1", "key2"]
> ls.removeAll(); // remove all keys

```

* Example 3: With `RC4` Encryption but no Data Compression

```
> var ls = new SLS({encodingType: 'rc4', isCompression: false});
> ls.set('key1', {data: 'test'}); // set key1
> ls.get('key1'); // print data
  {data: 'test'}

> ls.set('key2', [1, 2, 3]); // set another key
> ls.getAllKeys(); // get all keys
  ["key1", "key2"]
> ls.removeAll(); // remove all keys

```

* Example 3: With `DES` Encryption, no Data Compression and custom secret key

```
> var ls = new SLS({encodingType: 'des', isCompression: false, encryptionSecret: 'my-secret-key'});
> ls.set('key1', {data: 'test'}); // set key1
> ls.get('key1'); // print data
  {data: 'test'}

> ls.set('key2', [1, 2, 3]); // set another key
> ls.getAllKeys(); // get all keys
  ["key1", "key2"]
> ls.removeAll(); // remove all keys

```

## API Documentation

#### Create an instance / reference before using.

```
var ls = new SLS();
```

`Contructor` accepts a configurable `Object` with all three keys being optional.


| Config Keys              |     default    |      accepts                              |
| ------------------------ | -------------- | ----------------------------------------- |
| **encodingType**         |     Base64     |  `base64`/`aes`/`des`/`rabbit`/`rc4`/`''` |
| **isCompression**        |     `true`     |    `true`/`false`                         |
| **encryptionSecret**     |  PBKDF2 value  |    String                                 |
| **encryptionNamespace**  |      null      |    String                                 |

**Note:** `encryptionSecret` will only be used for the Encryption and Decryption of data
with `AES`, `DES`, `RC4`, `RABBIT`, and the library will discard it if no encoding / Base64
encoding method is choosen.

`encryptionNamespace` is used to make multiple instances with different `encryptionSecret`
and/or different `encryptionSecret` possible.

    var ls1 = new SLS({encodingType: 'des', encryptionSecret: 'my-secret-key-1'});
    var ls2 = new SLS({encodingType: 'aes', encryptionSecret: 'my-secret-key-2'});

**Examples:**

* No config or empty Object i.e. Default **`Base64 Encoding`** and **`Data compression`**

```
var ls = new SLS();
// or
var ls = new SLS({});
```

* No encoding No data compression i.e. **`Normal`** way of storing data

```
var ls = new SLS({encodingType: '', isCompression: false});
```

* **`Base64`** encoding but **`no`** data compression

```
var ls = new SLS({isCompression: false});
```

* **`AES`** encryption and **`data compression`**

```
var ls = new SLS({encodingType: 'aes'});
```

* **`RC4`** encryption and **`no`** data compression

```
var ls = new SLS({encodingType: 'rc4', isCompression: false});
```

* **`RABBIT`** encryption, **`no`** data compression and `custom` encryptionSecret

```
var ls = new SLS({encodingType: 'rc4', isCompression: false, encryptionSecret: 's3cr3tPa$$w0rd@123'});
```


#### Methods

* **`set`**

  Saves `data` in specifed `key` in localStorage. If the key is not provided, the library will warn. Following types of JavaScript objects are supported:

  * Array
  * ArrayBuffer
  * Blob
  * Float32Array
  * Float64Array
  * Int8Array
  * Int16Array
  * Int32Array
  * Number
  * Object
  * Uint8Array
  * Uint8ClampedArray
  * Uint16Array
  * Uint32Array
  * String

  |   Parameter   |        Description          |
  | ------------- | --------------------------- |
  |     key       |     key to store data in    |
  |     data      |      data to be stored      |

  ```
    ls.set('key-name', {test: 'secure-ls'})
  ```

* **`get`**

  Gets `data` back from specified `key` from the localStorage library. If the key is not provided, the library will warn.

  |   Parameter   |         Description                 |
  | ------------- | ----------------------------------- |
  |     key       |     key in which data is stored     |

  ```
    ls.get('key-name')
  ```

* **`remove`**

  Removes the value of a key from the localStorage. If the `meta key`, which stores the list of keys, is tried to be removed even if there are other keys which were created by `secure-ls` library, the library will warn for the action.

  |   Parameter   |         Description                       |
  | ------------- | ----------------------------------------- |
  |     key       |     remove key in which data is stored    |

  ```
    ls.remove('key-name')
  ```

* **`removeAll`**

  Removes all the keys that were created by the `secure-ls` library, even the `meta key`.

  ```
    ls.removeAll()
  ```

* **`clear`**

  Removes all the keys ever created for that particular domain. Remember localStorage works differently for `http` and `https` protocol;

  ```
    ls.clear()
  ```

* **`getAllKeys`**

  Gets the list of keys that were created using the `secure-ls` library. Helpful when data needs to be retrieved for all the keys or when keys name are not known(dynamically created keys).

  `getAllKeys()`

  ```
    ls.getAllKeys()
  ```