# js-polykey
> Polykey Core Library
Latest version **0.0.16** (published 2020-08-06) · Apache-2.0 license · 0 weekly downloads
> **Deprecated.** This package is deprecated.
## Install
```sh
npm install js-polykey
pnpm add js-polykey
yarn add js-polykey
bun add js-polykey
```
Provides the commands `pk`, `polykey`.
## Health
**Score 10/100 (F)** — status: deprecated.
Negative: deprecated.
## Facts
| | |
|---|---|
| Version | 0.0.16 |
| Published | 2020-08-06 |
| First published | 2020-07-30 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=12.14.0 |
| Dependencies | 26 |
| Unpacked size | 2.3 MB |
| Known vulnerabilities | 0 (+26 in 2 direct dependencies) |
| Install scripts | no |
| Author | Roger Qiu |
| Maintainers | robert.cronin |
| Keywords | secrets |
## Links
- npm: https://www.npmjs.com/package/js-polykey
- Repository: https://github.com/MatrixAI/js-polykey
- Homepage: https://github.com/MatrixAI/js-polykey#readme
- Issues: https://github.com/MatrixAI/js-polykey/issues
- npm.io page: https://npm.io/package/js-polykey
## Dependencies (26)
- [chalk](https://npm.io/package/chalk.md) ^4.0.0
- [kbpgp](https://npm.io/package/kbpgp.md) ^2.0.82
- [twilio](https://npm.io/package/twilio.md) ^3.48.1
- [zxcvbn](https://npm.io/package/zxcvbn.md) ^4.4.2
- [core-js](https://npm.io/package/core-js.md) ^3.6.5
- [express](https://npm.io/package/express.md) ^4.17.1
- [threads](https://npm.io/package/threads.md) ^1.6.0
- [commander](https://npm.io/package/commander.md) ^5.1.0
- [socket.io](https://npm.io/package/socket.io.md) ^2.3.0
- [virtualfs](https://npm.io/package/virtualfs.md) ^2.2.0
- [node-forge](https://npm.io/package/node-forge.md) ^0.9.1
- [protobufjs](https://npm.io/package/protobufjs.md) ^6.9.0
- [async-mutex](https://npm.io/package/async-mutex.md) ^0.2.4
- [configstore](https://npm.io/package/configstore.md) ^5.0.1
- [encryptedfs](https://npm.io/package/encryptedfs.md) ^1.0.2
- [futoin-hkdf](https://npm.io/package/futoin-hkdf.md) ^1.3.2
- [keybase-bot](https://npm.io/package/keybase-bot.md) ^3.6.1
- [cli-progress](https://npm.io/package/cli-progress.md) ^3.8.2
- [@grpc/grpc-js](https://npm.io/package/@grpc/grpc-js.md) ^1.1.2
- [isomorphic-git](https://npm.io/package/isomorphic-git.md) ^1.5.0
- [@types/inquirer](https://npm.io/package/@types/inquirer.md) ^6.5.0
- [google-protobuf](https://npm.io/package/google-protobuf.md) ^4.0.0-rc.2
- [readable-stream](https://npm.io/package/readable-stream.md) ^3.6.0
- [@types/commander](https://npm.io/package/@types/commander.md) ^2.12.2
- [@types/configstore](https://npm.io/package/@types/configstore.md) ^4.0.0
- [google-auth-library](https://npm.io/package/google-auth-library.md) ^6.0.5
## Recent versions
- 0.0.16 (latest) — 2020-08-06
- 0.0.15 — 2020-08-06
- 0.0.13 — 2020-08-05
- 0.0.12 — 2020-08-05
- 0.0.11 — 2020-08-05
- 0.0.10 — 2020-08-03
- 0.0.7 — 2020-08-03
- 0.0.6 — 2020-07-30
- 0.0.5 — 2020-07-30
## README
# Polykey (library)
## Overview
js-polykey is the library used in the distributed secret sharing `PolyKey` app. You can find the actual application [here](https://github.com/matrixai/polykey). A polykey node is comprised of one or many Vaults to store Secrets. These vaults are encrypted with keys derived from the master private key. Secrets always remain encrypted on disk and are only decrypted in memory. All you need to connect with and share secrets with another keynode on the same local area network is it's public key, poykey takes care of discovery. Once connected, you can securely share vaults with each other and polykey will ensure those vaults are synced.
PolyKey requires a public/private keypair for all crypto operations, this can be provided to a pre-initialized KeyManager instance before polykey is initialized or it can be generated (this is the default).
## Dependencies
The major dependencies of js-polykey are:
- [kbpgp](https://github.com/keybase/kbpgp) for all asymmetric cryptography.
- [EncryptedFS](https://github.com/MatrixAI/js-encryptedfs) for symmetric encryption within Vaults.
- [isomorphi-git](https://github.com/isomorphic-git/isomorphic-git) for version control within Vaults.
## KeyManager
This class is responsible for managing the public and private keys as well as any crypto operations using those keys. The symmetric vault keys are also managed by this instance.
The KeyManager is able to be loaded separately to the PolyKey main class and then passed into PolyKey. This is useful for loading the keypair prior to initializing PolyKey.
// Initialize key manager first
const keyManager = new KeyManager()
await keyManager.loadKeyPair('./keys/private.key', './keys/public.key')
// Initialize polykey instance
const pk = new PolyKey(keyManager)
### Key Generation
The key manager class can generate new symmetric keys using key derivation and the loaded private key
const newKey = await keyManager.generateKey('secret passphrase')
## Testing:
PolyKey uses jest to test:
jest
The tests also rely on certificates being available in the tmp folder and environment variables set to a valid certificate authority run on the network somewhere. Please see `.env.example` for an example of these environment variables. Certificates can be generated with `./scripts/generate_ssl_certs.sh` as long as a step-ca is running on the specified url in `.env`.
Note: sometimes grpc-js can complain about the ssl certificates in `tmp/` with a non-descriptive error of "No connection established". Best way to solve this is to remove the certs, start the CA server and re-issue the certs with `./scripts/generate_ssl_certs.sh`.
# Command Line Interface (CLI)
Here is a demo of the CLI on [asciinema](https://asciinema.org/a/347434).
The PolyKey CLI exposes various git-style sub commands that can be used to manipulate the PolyKey node:
Commands:
config [options] configure polykey
keymanager manipulate the keymanager
node network operations on the current polykey node
secrets manipulate secrets for a given vault
vaults manipulate vaults
crypto crypto operations
help [command] display help for command
Usage looks like the following:
polykey node ...
polykey vaults ...
# Sub commands are heirarchical like so:
polykey vaults add ...
polykey secrets remove ...
PolyKey also exposes a helpful alias, `pk`, to make typing out commands a little quicker:
pk secrets ...
pk crypto ...
If you ever get stuck, every sub command has a help flag:
# Either one of -h or --help will do
pk -h
pk vaults --help
pk secrets add -h
## Config
With this command you can manipulate the configuration of PolyKey including changing the password, importing new private and public keys and changing the path to polykey.
Options:
-pub, --public-key provide the path to an existing public key
-priv, --private-key provide the path to an existing private key
-pass, --private-passphrase provide the passphrase to the private key
-path, --polykey-path provide the polykey path. defaults to ~/.polykey
-v, --verbose increase verbosity by one level
Example usage:
# Change the location of PolyKey, perhaps to another node on the same computer
pk config --polykey-path='~/PolyKeyNode2'
# Import a new public key
pk config -pub ./keys/publicKey.txt
You can also easily clear the config to start fresh:
pk config clear
If one of the required configuration parameters is missing from the config store, PolyKey will prompt you for it on the next command.
## KeyManager
This command is used to interact with PolyKey's KeyManager. With this command you can generate new keys, import keys and more.
TODO: add commands to interact with the keymanager
Commands:
derive [options] manipulate the keymanager
## Node
The node sub command lets you control the daemon responsible for network operations.
Commands:
start start the polykey node
stop stop the polykey node
TODO: add commands to interact with the node
## Vaults
The vaults sub command lets you manipulate vaults, e.g. to list the existing vaults, add a new vault or destroy an old vault.
Commands:
list|ls [options] list all available vaults
add create new vault(s)
remove [options] destroy an existing vault
Command examples:
# List names of all existing vaults
pk vaults ls
# Create a new vault called 'SecureVault'
pk vaults add 'SecureVault'
# Remove 'SecureVault'
pk vaults remove --vault-name='SecureVault'
# Remove all vaults at once
pk vaults remove -a
## Secrets
The secrets sub command lets you manipulate secrets in a specific vault including to add new secrets, remove old secrets and modify existing secrets.
Commands:
list|ls [options] list all available secrets for a given vault
add [options] add a secret to a given vault
remove [options] remove a secret from a given vault
Command examples:
# List names of all secrets within 'SecureVault'
pk secrets list --vault-name='SecureVault'
# Add a new secret named 'Secret' to 'SecureVault
pk secrets add --vault-name='SecureVault' --secret-name='Secret'
# Remove 'Secret' from 'SecureVault'
pk secrets remove --vault-name='SecureVault' --secret-name='Secret'
## Crypto
The crypto sub command allows you to perform asymmetric cryptography operations (sign/encrypt/verify/decrypt) on files using the loaded public/prvate keypair.
PolyKey signs and verifies files using a [detached signature](https://en.wikipedia.org/wiki/Detached_signature)
TODO: add encryption and decryption
```
Commands:
sign [options] verification operations
verify [options] signing operations
```
Command examples:
```
pk crypto sign ./file --signing-key='./my_priv_key' --key-passphrase='password'
# If no signing key is provided, polykey will use the loaded private key
pk crypto sign ./file
pk crypto verify ./signed_file --verifying-key='./my_pub_key' --detach-sig='./signed_file.sig'
# If no verifying key is provided, polykey will use the loaded public key
pk crypto verify ./signed_file --detach-sig='./signed_file.sig'
```
## Verbosity
TODO: explain verbosity levels when it is implemented
# Build
## Proto Files
All `.proto` files are stored in the the `proto` directory. JavaScript and type definition files are build using the following command:
```
npm run build:proto
```
---
_Source: https://npm.io/package/js-polykey · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._