npm package: @omegajs/keypair
Description: Keychain structured to produce attestations and deterministic key pairs using Ed25519.
Latest version: 1.0.0

# @omegajs/keypair

Keychain structured to produce attestations and deterministic key pairs using Ed25519.

## Install Via L1FE's NPM
```
npm config set registry https://npm.l1fe.tech
npm install @omegajs/keypair
```

## Install Via L1FE's Git Repository
```
git clone https://lab.l1fe.tech/omega/keypair.git
cd keypair
npm install
```

## Usage

``` js
const Keychain = require('@omegajs/keypair');

const keyInstance = new Keychain();

const currentKey = keyInstance.get(); // fetches the current keypair instance
const specificKey = keyInstance.get('example'); // retrieves a modified keypair instance for 'example'

const subKeychain = keyInstance.sub('test'); // creates a sub keychain modified by 'test'
const nestedSubKeychain = subKeychain.sub('demo'); // further nested sub keychain

// for signing purposes

const signature = currentKey.sign(message);
const pubKey = currentKey.publicKey;
```

## API

#### `keychainInstance = new Keychain(publicKeyOrKeyPair)`

Make a new Keychain instance.

```js
const keychainInstance = new Keychain(); // auto-generates a new keypair
const keychainInstance = new Keychain(publicKey); // creates a "readonly" keychain
const keychainInstance = new Keychain(keyPair); // creates a keychain using an existing keypair
```

#### `keychainInstance.home`

References the keypair used to create the Keychain.

#### `keychainInstance.base`

Refers to the current active keypair or home if none selected.

#### `keychainInstance.tweak`

Points to the current tweak used.

#### `keychainInstance.head`

Represents the key pair in use, essentially base + tweak.

#### `keychainInstance = Keychain.from(keyChainOrPublicKeyOrKeyPair)`

Functions similarly to the constructor, returning the Keychain if already provided.
This is helpful for ensuring compatibility with the Keychain version in your application.

```js
const Keychain = require('@omegajs/keypair');

function customModule (keychainInstance) {
  const keychain = Keychain.from(keychainInstance); // ensures compatibility with installed Keychain version
}
```

#### `keyPair = keychainInstance.get([nameOrKeyPair])`

Acquire a new KeyPair from the Keychain, with an optional name or key pair for pre-modification.

```js
const keyPair = keychainInstance.get(); // retrieves a keypair from the current head
const keyPair = keychainInstance.get('example'); // first modifies with "example"
const keyPair = keychainInstance.get(anotherKeyPair); // modifies with this keypair
```

#### `keyPair.sign(message)`

Allows signing of a message using the key pair.

#### `keyPair.dh(otherPublicKey)`

Enables Diffie-Hellman negotiation with another keypair.

#### `keyPair.publicKey`

Retrieves the public key of this key pair.

#### `subKeychain = keychainInstance.sub(nameOrKeyPair)`

Create a modified sub Keychain using a name or key pair.

```js
const subKeychain = keychainInstance.sub('example'); // modifies the current keychain
const subKeychain = keychainInstance.sub({ publicKey: ... }); // creates a new "readonly" sub keychain
const subKeychain = keychainInstance.sub({ publicKey: ..., scalar: ... }); // creates a modifiable sub keychain
```

Note that the following keypairs are equivalent:

```js
const keyPair = keychainInstance.get('example');
const keyPair = keychainInstance.sub('example').get();
```

All modifications are one-way, using this method:

```js
modSeed = blake2b([currentMod ? currentMod.publicKey : blank, modInput]);
```

Ie, you need to know the previous modification to get to it.

#### `subKeychain = keychainInstance.checkout(publicKeyOrKeyPair)`

Creates a new Keychain based on a specific keypair or public key.
This keeps the "home" reference, allowing navigation back to the original keychain.

```js
const checkoutKeychain = keychainInstance.checkout(somePublicKey);
// to return to home
const homeKeychain = checkoutKeychain.checkout(checkoutKeychain.home);
```

## Bootstrapping helpers

To easily setup deterministic keychains you can use the following methods to store the seed on disk
for your keychain. Note that these might change / be removed as we iterate, and you should try and store
your seed elsewhere if possible for maximum security, depending on what you are building.

```js
const keychain = Keychain.openSync('./my-keychain'); // synchronous method
const keychain = await Keychain.open('./my-keychain'); // asynchronous method
```

## License

Apache-2.0