# loopback-secure-storage

> Secure (AES) file system storage component for Loopback / IBM API ORM

Latest version **2.0.3** (published 2020-04-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install loopback-secure-storage
pnpm add loopback-secure-storage
yarn add loopback-secure-storage
bun add loopback-secure-storage
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2020-04-22 |
| First published | 2019-03-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 27.1 KB |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | François Leparoux |
| Maintainers | rascafr |
| Keywords | loopback, express, aes, storage, secure-storage, encryption, decryption |

## Links

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

## Dependencies (5)

- [fs](https://npm.io/package/fs.md) 0.0.1-security
- [path](https://npm.io/package/path.md) ^0.12.7
- [uuid](https://npm.io/package/uuid.md) ^3.3.2
- [aes-js](https://npm.io/package/aes-js.md) ^3.1.2
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 2.0.3 (latest) — 2020-04-22
- 2.0.2 — 2020-04-22
- 2.0.0 — 2020-04-22
- 1.1.7 — 2019-03-19
- 1.1.4 — 2019-03-18
- 1.1.3 — 2019-03-18
- 1.1.2 — 2019-03-18
- 1.1.1 — 2019-03-18
- 1.1.0 — 2019-03-18
- 1.0.0 — 2019-03-18

## README

# loopback-secure-storage
Secure (AES) file system storage component for Express & Loopback / IBM API ORM

## Changelog

### Version 2

Work has been done on the library, thereby is it not compatible with the previous versions (last one was 1.1.7). It is now used as a singleton and not a stateless module anymore.

Your current configuration json file is still compatible, but now you can specify the allowed extensions (combined with the mime type check).

You can also setup the configuration as a js object when calling the initialisation method of the module instance.

For everyone to be satisfied, the module's methods can be used as promises or with callback (excepted for the servers methods).

## Features

- AES encryption / decryption
- HTTP upload / download support methods (express-compatible)
- 128bits key support (generate / use / check)
- compatible with Loopback's storage component (usage, config)
- can be used as an express method

## Example

Because code is always better than a Markdown file, an example is available [here](https://github.com/rascafr/example-loopback-secure-storage). Feel free to clone and tweak it!

## Installation

In your own project, run `npm i loopback-secure-storage` and you're good to go.

## Configuration

The configuration object expected by the module is the following one:

```js
const config = {
    name: "secureStorageConfig",            // Container name

    root: `./storage/container`,            // Container root directory (project root reference)

    nameMakeUnique: true,                   // set to true to prevent name collisions for the uploaded files

    maxFileSize: SecureStorage.asMiB(50),   // maximum byte size: as KiB, GiB, or a simple integer
                                            // (optional, omit key or set as 0 to skip size verification)

    allowedContentTypes: [                  // optional mime type filter if key is set
        "text/plain"
    ],
    allowedExtensions: [                    // optional extension filter if key is set
        "txt"
    ],
    sysKey: "your-16-bytes-aes-key"         // the AES key to use
}
```

### As object, as config file?

You can pass this configuration directly to the `init()` method, or save it under a json file (like other json config files used in Loopback).

Add the file in your `server` directory, named `storage.NODE_ENV.json`:

```json
{
    "secureStorageConfig": {
        "name": "secureStorageConfig",      // Loopback container name
        "root": ...
    }
}
```

**Note:** You do not have to create the "root" directory, if it does not exists, then the module will do the job when the app starts.

## Usage

```js
const SecureStorage = require('loopback-secure-storage');

// using a configuration object
SecureStorage.init({...});

// or... using a configuration file
SecureStorage.init('secureStorageConfig');

// write and read a file
SecureStorage.writeFile('myFile.txt', 'data to be written')
    .then(() => SecureStorage.readFile('myFile.txt'))
    .then(readData => console.log(readData));

// or use it as a server method
app.post('/uploadFile', (req, res) => {
    SecureStorage.uploadFile({req}, (err, fileObj) => {
        console.log('Saved', fileObj)
    });
});

// download file
// 'res' object from express will be filled with data and headers to be sent back to the client
app.get('/downloadFile', (req, res) => {
    SecureStorage.downloadFile('file-unique-name', res);
});
```

## Key management

To generate a key, you can use the `getRandomKey` method provided with the package as:

```js
const SecureStorage = require('loopback-secure-storage');
const key = SecureStorage.getRandomKey().hex;

// ... expected output:
// { bytes: [ 212, 202, 144, 124, 187, 170, 143, 47, 14, 139, 30, 72, 72, 165, 148, 68 ],
//   hex: 'd4ca907cbbaa8f2f0e8b1e4848a59444' }
```

## Testing

Module can be tested with `mocha` by running the command `npm run test`.

> ⚠️ Test sequence uses the port `4201` to start a temporary express server. Please ensure it is available on your environment during this phase.

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