Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/draeder/gunsafe

A decentralized secure vault API built on Gun chain
https://github.com/draeder/gunsafe

decentralization p2p secure storage

Last synced: 3 months ago
JSON representation

A decentralized secure vault API built on Gun chain

Awesome Lists containing this project

README 

        
# Gunsafe

## A decentralized secure vault API built on Gun chain



- Simple API

- Local first

- No need to remember passwords, only what you named your vault

- P2P ready

- Secured with encryption provided by SEA

- Synchronization capabilities included.



Gunsafe can securely store key-value pairs of strings, objects, functions. It is offline by default, but may be paired with other instances with its `gun.gunsafe.pair()` method.



Gunsafe secures each of its vault's data with an SEA keypair generated by device/machine ID and salted with the desired name of the vault. This ensures only your device can ever decrypt your vault's data, unless you choose to pair your vault with another instance.



This makes Gunsafe relatively versitile. It could be used to create a shared chatroom, or document collaboration, for example.



> Note: gunsafe should work in a browser with a bundler of your choice, but has yet to be tested.



Since this is early release software, please use due dilligence when building with it. Please report any bugs, questions, PRs, or anything else [here](https://github.com/draeder/gunsafe).



## Install

### API

```js

npm i gunsafe

```



### CLI

```js

npm i gunsafe -g

```



If you're using the gunsafe CLI in VS Code, you may notice each instance of VS Code creates a new gunsafe key pair. You can work around this by pairing your instances in each VS Code instance.



# Gunsafe Example CLI

Gunsafe has an alpha-state CLI available as an example of its capabilities. You may install it with `npm i --g` if you want it available to all of your terminal windows.



> Note: The CLI currently stores the key in the current working directory. If you install this (non globally) in a folder you are using with git, be sure to add `key` to your gitignore file to avoid leaking your secure key. This will be addressed in a future version by encrypting the key based on hardware signature.



## Usage

```

> gunsafe

```

Gunsafe CLI accepts commands from the terminal when it is running.



## CLI commands

### `CTRL-W` or `OPTION-BACKSPACE`

Toggle document / multiline record mode



When in this mode the first string of text entered becomes the record's name. 



The subsequent entries become the record's contents and will be save to gunsafe when you toggle out of document mode.



> Note: there are some known parsing issues that cause lines to disappear when they have certain special characters. This will be addressed.



### `CTRL-C` or `CTRL-D`

Quit gunsafe



### `keypair`

Shows your gunsafe session keypair. This is the password to your vault, so use this command with caution.



### `peers [ optional list of space separated Gun relay peers without brackets]` 

Display (default) or set the list of peers to enable online mode.



### `pair < optional pairing key string >`

Display a pairing key to pair other instances with this one, or pass a pairing key string in to establish syncronization with another instance (local or remote).



### `put < key name string of your data > --data < your data string >`

Command to put a key-value pair to this gunsafe instance



#### `--data`

Without this argument, the entire passed in string will be used as your key name and the record will have no data, so it will be unretrievable.



### `get < key name string of desired record > [ --run ] [ --global ]`

Retrieve the stored key name's data



Optionally run the record code with `--run`. By default it will run in a local scope context in which it was envoked, but may also be run in a global context with `--global`. If the record is not code, it will return the gunsafe prompt.



The ability to run stored code adds some additional possibilities to the versatility of Gunsafe, but use with care! The `--run --global` argument uses `eval()`, for example. While the default `--run` argument runs the code in local scope context. 



> Neither approaches should be consiered 'secure', but have been provided with this CLI as a way to quickly test code snippets you may save to your gunsafe.



### `list [ --deleted ]`

List the available record key names ( default ), or optionally list only the deleted records with `--deleted`.



### `delete [ key name ]`

Delete the record with the matching key name. Excluding the key name will destroy all of the records in your vault. Use caution.



## API

### `gun.gunsafe.name(key, name)`

Creates a new gunsafe from the passed in key, and logs the instance into gunsafe for secure data storage and retrieval



#### Example

```js

import SEA from 'gun/sea.js'

import gunsafe from 'gunsafe'



gun.gunsafe()



let pair = await new SEA.pair()



gun.gunsafe.name(pair.epriv, 'Unique gunsafe name')



```



### `gun.gunsafe.put(name : string, data : any)`

Encrypts and puts a record into gunsafe with the name `name` and value `data`



### `gun.gunsafe.get(name : string [, run : bool, global : bool, cb ])`

Gets a record from gunsafe and optionally executes the record if it is runnable code



#### `cb`

A callback containing the record data



If `run` and optionally `global` are passed in, the record will be executed if the code is runnalbe. If not, the record will be returned.



#### `run`

Runs the code using `new Function(string)`



#### `global`

Runs the code using `eval(string)`



### `gun.gunsafe.list([deleted : bool ])`

Returns the record names



Optionally pass in `true` to show deleted record names



### `gun.gunsafe.delete([, name : string ])`

Deletes all of the records unless the record name is passed in.



### `gun.gunsafe.peers([ peers : string])`

Displays the connected peers



Gunsafe starts in local-only mode by default. You may pass a list space-separated of peers in as a parameter to make gunsafe available across networks.



#### Example

```js

gun.gunsafe.peers('https://relay.peer.ooo/gun https://gunjs.herokuapp.com/gun')

```



### `gun.gunsafe.pair([ key : string ])`

Initiates gunsafe pairing and returns the pairing key



If a `key` is passed in on another instance of gunsafe, the two instances will be paired and synchronized to each other.



### `gun.gunsafe.key()`

Returns the current gunsafe keypair. **Use with caution. This is your gunsafe instance's password.**



# License

MIT