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.
Simply install using npm
$ npm install muport-core
and then import into your project
const MuPort = require('muport-core')
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() ⇒
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
- .helpRecover(did) ⇒
- static
- .newIdentity(publicProfile, delegateDids, [opts]) ⇒
Promise.<MuPort, Error>
- .recoverIdentity(did, shares, [opts]) ⇒
Promise.<MuPort, Error>
- .resolveIdentityDocument(did, [opts]) ⇒
Promise.<Object, Error>
- .newIdentity(publicProfile, delegateDids, [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 |
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 |
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
The DID Document is a json object that contains information such as public keys
Kind: instance method of MuPort
Returns: Object
- the DID Document
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
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 |
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
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 |
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 |
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 |
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 |
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 |
Serialize the state of the current identity to be able to reconstruct it later.
Kind: instance method of MuPort
Returns: String
- the serialized state
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 |
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 |
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 |