https://github.com/3box/muport-core-js
JavaScript framework for associating a DID to an Ethereum address
https://github.com/3box/muport-core-js
Last synced: 11 months ago
JSON representation
JavaScript framework for associating a DID to an Ethereum address
- Host: GitHub
- URL: https://github.com/3box/muport-core-js
- Owner: 3box
- License: mit
- Archived: true
- Created: 2018-03-01T10:13:00.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-05-23T22:28:55.000Z (about 7 years ago)
- Last Synced: 2024-11-25T09:43:42.794Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 604 KB
- Stars: 11
- Watchers: 15
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# µPort core
[](https://circleci.com/gh/uport-project/muport-core-js) [](https://codecov.io/gh/uport-project/muport-core-js)
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
```js
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](#MuPort)
* [new MuPort(serializeState, [opts])](#new_MuPort_new)
* _instance_
* [.helpRecover(did)](#MuPort+helpRecover) ⇒ Promise.<String, Error>
* [.getDid()](#MuPort+getDid) ⇒ String
* [.getDidDocument()](#MuPort+getDidDocument) ⇒ Object
* [.getRecoveryDelegateDids()](#MuPort+getRecoveryDelegateDids) ⇒ Array.<String>
* [.updateIdentity(publicProfile, delegateDids)](#MuPort+updateIdentity) ⇒ Promise.<Object, Error>
* [.signJWT(payload)](#MuPort+signJWT) ⇒ Promise.<String, Error>
* [.verifyJWT(jwt, audience)](#MuPort+verifyJWT) ⇒ Promise.<Object, Error>
* [.encrypt(msg, toPublic, nonce)](#MuPort+encrypt) ⇒ Object
* [.decrypt(ciphertext, fromPublic, nonce, toBuffer)](#MuPort+decrypt) ⇒ String \| Buffer
* [.symEncrypt(msg, nonce)](#MuPort+symEncrypt) ⇒ Object
* [.symDecrypt(ciphertext, nonce, toBuffer)](#MuPort+symDecrypt) ⇒ String \| Buffer
* [.serializeState()](#MuPort+serializeState) ⇒ String
* _static_
* [.newIdentity(publicProfile, delegateDids, [opts])](#MuPort.newIdentity) ⇒ Promise.<MuPort, Error>
* [.recoverIdentity(did, shares, [opts])](#MuPort.recoverIdentity) ⇒ Promise.<MuPort, Error>
* [.resolveIdentityDocument(did, [opts])](#MuPort.resolveIdentityDocument) ⇒ 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](#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](#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](#MuPort)
**Returns**: Object - the DID Document
### muPort.getRecoveryDelegateDids() ⇒ Array.<String>
The recovery delegates that can help this identity recover
**Kind**: instance method of [MuPort](#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](#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](#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](#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](#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](#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](#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](#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](#MuPort)
**Returns**: String - the serialized state
### MuPort.newIdentity(publicProfile, delegateDids, [opts]) ⇒ Promise.<MuPort, Error>
Creates a new µPort identity.
**Kind**: static method of [MuPort](#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](#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](#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 |