README.md

µPort core

This library is intended to be used to create, update, and recover µPort identities, as well as using the identity to sign and encrypt data.

Usage

Simply install using npm

$ npm install muport-core

and then import into your project

const MuPort = require('muport-core')

MuPort

Primary object for interacting with a µPort identity. MuPort enables creation and updating of µPort identities. It also provides functionality to sign claims and help other identities recover.

Kind: global class

• MuPort
  • new MuPort(serializeState, [opts])
  • instance
    • .helpRecover(did) ⇒ Promise.<String, Error>
    • .getDid() ⇒ String
    • .getDidDocument() ⇒ Object
    • .getRecoveryDelegateDids() ⇒ Array.<String>
    • .updateIdentity(publicProfile, delegateDids) ⇒ Promise.<Object, Error>
    • .signJWT(payload) ⇒ Promise.<String, Error>
    • .verifyJWT(jwt, audience) ⇒ Promise.<Object, Error>
    • .encrypt(msg, toPublic, nonce) ⇒ Object
    • .decrypt(ciphertext, fromPublic, nonce, toBuffer) ⇒ String | Buffer
    • .symEncrypt(msg, nonce) ⇒ Object
    • .symDecrypt(ciphertext, nonce, toBuffer) ⇒ String | Buffer
    • .serializeState() ⇒ String
  • static
    • .newIdentity(publicProfile, delegateDids, [opts]) ⇒ Promise.<MuPort, Error>
    • .recoverIdentity(did, shares, [opts]) ⇒ Promise.<MuPort, Error>
    • .resolveIdentityDocument(did, [opts]) ⇒ Promise.<Object, Error>

new MuPort(serializeState, [opts])

Instantiates a µPort identity from its serialized state.

Param	Type	Description
serializeState	String	the serialized state of a µPort identity
[opts]	Object	optional parameters
opts.ipfsConf	Object	configuration options for ipfs-mini
opts.rpcProviderUrl	String	rpc url to a custom ethereum node

muPort.helpRecover(did) ⇒ Promise.<String, Error>

Help another identity recover. Returns a decrypted share if the current identity is a delegate returns undefined otherwise

Kind: instance method of MuPort
Returns: Promise.<String, Error> - a share that the recovering identity can use

Param	Type	Description
did	String	the did of the identity that should be recovered

muPort.getDid() ⇒ String

The DID is the identifier of the identity. This is a unique string that can be used to look up information about the identity.

Kind: instance method of MuPort
Returns: String - the DID

muPort.getDidDocument() ⇒ Object

The DID Document is a json object that contains information such as public keys

Kind: instance method of MuPort
Returns: Object - the DID Document

muPort.getRecoveryDelegateDids() ⇒ Array.<String>

The recovery delegates that can help this identity recover

Kind: instance method of MuPort
Returns: Array.<String> - an array containing the DIDs of the delegates

muPort.updateIdentity(publicProfile, delegateDids) ⇒ Promise.<Object, Error>

This function is used to update the publicProfile and/or the recoveryNetwork of the identity. The returned object has three properties; address an ethereum address, costInEther a number, and finishUpdate a function. In order to complete the update of the delegates you have to send costInEther ether to the address on mainnet (or other network if you are using a custom config). Once that is done the finishUpdate function can be called. This function sends a transaction to the network that updates the identity. The function will throw an error if there is to little ether in the address. Both publicProfile and delegateDids are optional and you may pass null if you don't wish to update one of them.

Kind: instance method of MuPort
Returns: Promise.<Object, Error> - an object with the data needed to finalize the update

Param	Type	Description
publicProfile	Object	a new public profile for the identity
delegateDids	Array.<String>	an array containing the 3 DIDs of the new delegates

muPort.signJWT(payload) ⇒ Promise.<String, Error>

Signs the given payload (claim) and return a promis with the JWT.

Kind: instance method of MuPort
Returns: Promise.<String, Error> - a promise that resolves to a JWT

Param	Type	Description
payload	*	the payload to sign

muPort.verifyJWT(jwt, audience) ⇒ Promise.<Object, Error>

Verifies a JWT.

Kind: instance method of MuPort
Returns: Promise.<Object, Error> - a promise that resolves to the decoded JWT

Param	Type	Default	Description
jwt	String		the JWT to verify
audience	String	this.did	the audience, defaults to did of current identity

muPort.encrypt(msg, toPublic, nonce) ⇒ Object

Asymmetrically encrypt a message

Kind: instance method of MuPort
Returns: Object - an object containing the nonce and the ciphertext

Param	Type	Description
msg	String	the message to encrypt
toPublic	String	the public key to encrypt to, encoded as a base64 string
nonce	String	(optional) the nonce, encoded as a base64 string

muPort.decrypt(ciphertext, fromPublic, nonce, toBuffer) ⇒ String | Buffer

Decrypt an asymmetrically encrypted message

Kind: instance method of MuPort
Returns: String | Buffer - the decrypted message

Param	Type	Description
ciphertext	String	the ciphertext to decrypt, encoded as a base64 string
fromPublic	String	the public key of the entity that encrypted the msg, encoded as a base64 string
nonce	String	the nonce, encoded as a base64 string
toBuffer	Boolean	a boolean deciding whether to

muPort.symEncrypt(msg, nonce) ⇒ Object

Symmetrically encrypt a message

Kind: instance method of MuPort
Returns: Object - an object containing the nonce and the ciphertext

Param	Type	Description
msg	String	the message to encrypt
nonce	String	(optional) the nonce, encoded as a base64 string

muPort.symDecrypt(ciphertext, nonce, toBuffer) ⇒ String | Buffer

Decrypt a symmetrically encrypted message

Kind: instance method of MuPort
Returns: String | Buffer - the decrypted message

Param	Type	Description
ciphertext	String	the ciphertext to decrypt, encoded as a base64 string
nonce	String	the nonce, encoded as a base64 string
toBuffer	Boolean	a boolean deciding whether to

muPort.serializeState() ⇒ String

Serialize the state of the current identity to be able to reconstruct it later.

Kind: instance method of MuPort
Returns: String - the serialized state

MuPort.newIdentity(publicProfile, delegateDids, [opts]) ⇒ Promise.<MuPort, Error>

Creates a new µPort identity.

Kind: static method of MuPort
Returns: Promise.<MuPort, Error> - a promise that resolves to an instance of the MuPort class

Param	Type	Description
publicProfile	Object	a public profile for the new identity
delegateDids	Array.<String>	three DIDs that can be used to recover the identity at a later point (optional)
[opts]	Object	optional parameters
opts.externalMgmtKey	String	an ethereum address to be used as an external managementKey
opts.ipfsConf	Object	configuration options for ipfs-mini
opts.rpcProviderUrl	String	rpc url to a custom ethereum node

MuPort.recoverIdentity(did, shares, [opts]) ⇒ Promise.<MuPort, Error>

Recovers a µPort identity.

Kind: static method of MuPort
Returns: Promise.<MuPort, Error> - a promise that resolves to an instance of the MuPort class

Param	Type	Description
did	String	the DID of the identity to be recovered
shares	Array.<String>	atleast two shares that your delegates helped recover
[opts]	Object	optional parameters
opts.ipfsConf	Object	configuration options for ipfs-mini
opts.rpcProviderUrl	String	rpc url to a custom ethereum node

MuPort.resolveIdentityDocument(did, [opts]) ⇒ Promise.<Object, Error>

Resovles the identity document for the given DID.

Kind: static method of MuPort
Returns: Promise.<Object, Error> - a promise that resolves to the identity document

Param	Type	Description
did	String	the DID of the identity
[opts]	Object	optional parameters
opts.ipfsConf	Object	configuration options for ipfs-mini
opts.rpcProviderUrl	String	rpc url to a custom ethereum node