Skip to content

Latest commit

 

History

History
149 lines (99 loc) · 5.98 KB

README.md

File metadata and controls

149 lines (99 loc) · 5.98 KB
Raw

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.

Install

API

npm i gunsafe

CLI

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

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

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