uPort Persona

A library for creating, updating and reading attributes and claims on uport personas. It's intended as an easy interface to the uport-registry, allowing developers to focus on the actual data instead of the datastructure of the object stored in the registry. It contains two main classes Persona for getting information on a persona, and MutablePersona which is a subclass of Persona with additional features for updating persona information.

Example usage

Importing

import { Persona, MutablePersona } from 'uport-persona';

Basic information viewing

For each persona you want to interact with you have to create a separate instance of the Persona class.

// the address of the persona you want to interact with
let myAddress = "0x123...";
let ipfsProvider = {
  host: 'localhost',
  port: '5001',
  protocol: 'https',
  root: ''
}
let persona = new Persona(myAddress, ipfs, web3.currentProvider);
persona.load().then(() => { ... });

Once instantiated you can start by getting the current profile:

let profile = persona.getProfile();

The profile is in JSON format containing all attributes associated with the persona.

Viewing attestations

An attestation, also called a claim is the basic building block of the information associated with a persona. By default all attributes are self signed claims created by the persona that it's associated with. But an attribute can have multiple claims, meaning that several parties have signed it. The claims are in the same format as blockstack-profiles. To get all claims associated with the persona:

let claims = persona.getAllClaims();

You can also get all claims to a specific attribute:

let claims = persona.getClaims("MyAttribute");

Signing attributes as a third party

As a third party you would like to attest to the fact that the given persona has a specific attribute. By signing an attribute you create a claim.

let thirdPartyPrivKey = ...
let thirdPartyAddress = "0x...";
let claim = persona.signAttribute("MyAttribute", thirdPartyPrivKey, thirdPartyAddress);

Modifying a persona

To modify a persona the MutablePersona class needs to be used. It's instantiated in the same way as the Persona class. An important thing to note is that MutablePersona will make changes locally and only write the changes to the blockchain if the method writeToRegistry is called.

// the address of the persona you want to interact with
let myAddress = "0x123...";
let ipfs = ipfsApi(<hostname>, <port>);
let persona = new MutablePersona(myAddress, ipfs, web3.currentProvider);
persona.load().then(() => { ... });

Creating a profile.

Note that the first thing that needs to be added to a profile is the public signing key. If this is not done the addAttribute method will throw an error.

let myPrivSignKey = ...
persona.setPublicSigningKey(myPrivSignKey)
persona.addAttribute({ attributeName: attributeValue }, privKey);

Adding a claim.

persona.addClaim(claim)

Write the changes to the blockchain.

While making changes to the persona these changes are only stored in the javascript object. To save the changes to the blockchain the following function needs to be called.

persona.writeToRegistry().then((txHash) => { ... });

Running tests

Simply run

$ npm test

Documentation

Persona

Class representing a persona.

Kind: global class

Persona
- instance
  - .constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object
  - .loadAttributes() ⇒ Promise.<JSON, Error>
  - .load(claims) ⇒ Promise.<JSON, Error>
  - .getProfile() ⇒ JSON
  - .getPublicSigningKey() ⇒ String
  - .getPublicEncryptionKey() ⇒ String
  - .getAllClaims() ⇒ JSON
  - .getClaims(attributesName) ⇒ JSON
  - .signAttribute(attribute, privSignKey, issuerId) ⇒ Object
  - .signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ Array
- static
  - .isTokenValid(token) ⇒ Boolean
  - .privateKeyToPublicKey(privateKey) ⇒ String

persona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

Class constructor. Creates a new persona object. The registryAddress is an optional argument and if not specified will be set to the default consensys testnet uport-registry.

Kind: instance method of Persona
Returns: Object - self

Param	Type	Default	Description
address	`String`		the address of the persona
ipfsProvider	`String`		an ipfs provider
web3Provider	`String`		web3 provider
[registryAddress]	`String`	`'0xa9be82e93628abaac5ab557a9b3b02f711c0151c'`	the uport-registry address to use.

persona.loadAttributes() ⇒ `Promise.<JSON, Error>`

This should be the only function used to get attributes from the uport-registry. This can be overridden in a subclass.

Kind: instance method of Persona
Returns: Promise.<JSON, Error> - A promise that returns all claims registered to the persona. Encrypted claims would be included here. Or an Error if rejected.

persona.load(claims) ⇒ `Promise.<JSON, Error>`

This function always have to be called before interacting with the persona. This function loads the profile of the persona from the uport-registry into the persona object. The only time this function should not be called is when creating a completely new persona. If the Claims argument is given these claims are used instead of loading anything from the uport-registry.

Kind: instance method of Persona
Returns: Promise.<JSON, Error> - A promise that returns all claims registered to the persona. Encrypted claims would be included here. Or an Error if rejected.

Param	Type	Description
claims	`Object`	A list of claims. If argument is not given the persona will load from the registry.

persona.getProfile() ⇒ `JSON`

This function returns the profile of the persona in JSON format.

Kind: instance method of Persona
Returns: JSON - profile

persona.getPublicSigningKey() ⇒ `String`

Returns the public signing key of the persona.

Kind: instance method of Persona

persona.getPublicEncryptionKey() ⇒ `String`

Returns the public encryption key of the persona, if set.

Kind: instance method of Persona

persona.getAllClaims() ⇒ `JSON`

Returns all claims associated with the persona.

Kind: instance method of Persona
Returns: JSON - List of claims

persona.getClaims(attributesName) ⇒ `JSON`

Returns all claims that have the given attribute name.

Kind: instance method of Persona
Returns: JSON - List of claims

Param	Type	Description
attributesName	`String`	the name of the attribute to check

persona.signAttribute(attribute, privSignKey, issuerId) ⇒ `Object`

Signs the given attribute to the persona. This method is to be used by third parties who wishes to attest to an attribute of the persona. Note that this does not add anything to the persona, it only returns a signed claim. To add a claim to a persona the addClaim method of MutablePersona has to be used.

Kind: instance method of Persona
Returns: Object - claim

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the attestor
issuerId	`String`	the address of the attestor (voluntary, to allow finding info on the attestor from uport-registry)

persona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ `Array`

Same as signAttribute but for a list of attributes.

Kind: instance method of Persona
Returns: Array - List of claims

Param	Type	Description
attribute	`Array`	the attribute to add, in the format [{attrName: attr},...]
privSignKey	`String`	the private signing key of the attestor
issuerId	`String`	the ethereum address of the attestor

Persona.isTokenValid(token) ⇒ `Boolean`

A static function for checking if a token is valid.

Kind: static method of Persona

Param	Type
token	`Object`

Persona.privateKeyToPublicKey(privateKey) ⇒ `String`

A static function for checking if a token is valid.

Kind: static method of Persona
Returns: String - publicKey

Param	Type
privateKey	`String`

MutablePersona ⇐ `Persona`

Class representing a persona that can be modified.

Kind: global class
Extends: Persona

MutablePersona ⇐ Persona
- .writeToRegistry() ⇒ Promise.<String, Error>
- .addClaim(claim)
- .addClaims(claimList)
- .removeClaim(claim)
- .addAttribute(attribute, privSignKey)
- .replaceAttribute(attribute, privSignKey)
- .removeAttribute(attribute)
- .setPublicSigningKey(privSignKey)
- .setPublicencryptionKey(pubEncKey, privSignKey)
- .constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object
- .loadAttributes() ⇒ Promise.<JSON, Error>
- .load(claims) ⇒ Promise.<JSON, Error>
- .getProfile() ⇒ JSON
- .getPublicSigningKey() ⇒ String
- .getPublicEncryptionKey() ⇒ String
- .getAllClaims() ⇒ JSON
- .getClaims(attributesName) ⇒ JSON
- .signAttribute(attribute, privSignKey, issuerId) ⇒ Object
- .signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ Array

mutablePersona.writeToRegistry() ⇒ `Promise.<String, Error>`

This should be the only function ever used to write the persona onto the blockchain. This can be overridden in a subclass.

It stores whatever is in this.tokenRecords.

Kind: instance method of MutablePersona
Returns: Promise.<String, Error> - A promise that returns the txHash of the transaction updating the registry. Or an Error if rejected.

mutablePersona.addClaim(claim)

Add a signed claim to this persona. This should be used to add tokens signed by third parties.

Kind: instance method of MutablePersona

Param	Type	Description
claim	`JSON`	the claim to add

mutablePersona.addClaims(claimList)

Add mulitple signed claims to this persona. This should be used to add tokens signed by third parties.

Kind: instance method of MutablePersona

Param	Type	Description
claimList	`JSON`	the claims to add

mutablePersona.removeClaim(claim)

Removes a signed claim from a persona.

Kind: instance method of MutablePersona

Param	Type	Description
claim	`JSON`	the claim to remove

mutablePersona.addAttribute(attribute, privSignKey)

Adds a self signed attribute to the persona. Only to be used if you own the privSignKey of this persona.

Kind: instance method of MutablePersona

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the persona

mutablePersona.replaceAttribute(attribute, privSignKey)

Removes all tokens having the same attribute name as the given attribute and adds the given attribute.

Kind: instance method of MutablePersona

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the persona

mutablePersona.removeAttribute(attribute)

Removes all attributes with the same attribute name as the given attribute.

Kind: instance method of MutablePersona

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}

mutablePersona.setPublicSigningKey(privSignKey)

Sets the public signing key of the persona.

Kind: instance method of MutablePersona

Param	Type	Description
privSignKey	`String`	the private signing key of the persona

mutablePersona.setPublicencryptionKey(pubEncKey, privSignKey)

Sets the public encryption key of the persona.

Kind: instance method of MutablePersona

Param	Type	Description
pubEncKey	`String`	the public encryption key of the persona
privSignKey	`String`	the private signing key of the persona

mutablePersona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

Class constructor. Creates a new persona object. The registryAddress is an optional argument and if not specified will be set to the default consensys testnet uport-registry.

Kind: instance method of MutablePersona
Returns: Object - self

Param	Type	Default	Description
address	`String`		the address of the persona
ipfsProvider	`String`		an ipfs provider
web3Provider	`String`		web3 provider
[registryAddress]	`String`	`'0xa9be82e93628abaac5ab557a9b3b02f711c0151c'`	the uport-registry address to use.

mutablePersona.loadAttributes() ⇒ `Promise.<JSON, Error>`

This should be the only function used to get attributes from the uport-registry. This can be overridden in a subclass.

Kind: instance method of MutablePersona
Returns: Promise.<JSON, Error> - A promise that returns all claims registered to the persona. Encrypted claims would be included here. Or an Error if rejected.

mutablePersona.load(claims) ⇒ `Promise.<JSON, Error>`

This function always have to be called before interacting with the persona. This function loads the profile of the persona from the uport-registry into the persona object. The only time this function should not be called is when creating a completely new persona. If the Claims argument is given these claims are used instead of loading anything from the uport-registry.

Kind: instance method of MutablePersona
Returns: Promise.<JSON, Error> - A promise that returns all claims registered to the persona. Encrypted claims would be included here. Or an Error if rejected.

Param	Type	Description
claims	`Object`	A list of claims. If argument is not given the persona will load from the registry.

mutablePersona.getProfile() ⇒ `JSON`

This function returns the profile of the persona in JSON format.

Kind: instance method of MutablePersona
Returns: JSON - profile

mutablePersona.getPublicSigningKey() ⇒ `String`

Returns the public signing key of the persona.

Kind: instance method of MutablePersona

mutablePersona.getPublicEncryptionKey() ⇒ `String`

Returns the public encryption key of the persona, if set.

Kind: instance method of MutablePersona

mutablePersona.getAllClaims() ⇒ `JSON`

Returns all claims associated with the persona.

Kind: instance method of MutablePersona
Returns: JSON - List of claims

mutablePersona.getClaims(attributesName) ⇒ `JSON`

Returns all claims that have the given attribute name.

Kind: instance method of MutablePersona
Returns: JSON - List of claims

Param	Type	Description
attributesName	`String`	the name of the attribute to check

mutablePersona.signAttribute(attribute, privSignKey, issuerId) ⇒ `Object`

Signs the given attribute to the persona. This method is to be used by third parties who wishes to attest to an attribute of the persona. Note that this does not add anything to the persona, it only returns a signed claim. To add a claim to a persona the addClaim method of MutablePersona has to be used.

Kind: instance method of MutablePersona
Returns: Object - claim

Param	Type	Description
attribute	`Object`	the attribute to add, in the format {attrName: attr}
privSignKey	`String`	the private signing key of the attestor
issuerId	`String`	the address of the attestor (voluntary, to allow finding info on the attestor from uport-registry)

mutablePersona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ `Array`

Same as signAttribute but for a list of attributes.

Kind: instance method of MutablePersona
Returns: Array - List of claims

Param	Type	Description
attribute	`Array`	the attribute to add, in the format [{attrName: attr},...]
privSignKey	`String`	the private signing key of the attestor
issuerId	`String`	the ethereum address of the attestor

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
dist		dist
lib		lib
test		test
.babelrc		.babelrc
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
example.js		example.js
package.json		package.json
readme-template.hbs		readme-template.hbs

License

DivvyDAO/uport-persona

Folders and files

Latest commit

History

Repository files navigation

uPort Persona

Example usage

Importing

Basic information viewing

Viewing attestations

Signing attributes as a third party

Modifying a persona

Creating a profile.

Adding a claim.

Write the changes to the blockchain.

Running tests

Documentation

Persona

persona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object

persona.loadAttributes() ⇒ Promise.<JSON, Error>

persona.load(claims) ⇒ Promise.<JSON, Error>

persona.getProfile() ⇒ JSON

persona.getPublicSigningKey() ⇒ String

persona.getPublicEncryptionKey() ⇒ String

persona.getAllClaims() ⇒ JSON

persona.getClaims(attributesName) ⇒ JSON

persona.signAttribute(attribute, privSignKey, issuerId) ⇒ Object

persona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ Array

Persona.isTokenValid(token) ⇒ Boolean

Persona.privateKeyToPublicKey(privateKey) ⇒ String

MutablePersona ⇐ Persona

mutablePersona.writeToRegistry() ⇒ Promise.<String, Error>

mutablePersona.addClaim(claim)

mutablePersona.addClaims(claimList)

mutablePersona.removeClaim(claim)

mutablePersona.addAttribute(attribute, privSignKey)

mutablePersona.replaceAttribute(attribute, privSignKey)

mutablePersona.removeAttribute(attribute)

mutablePersona.setPublicSigningKey(privSignKey)

mutablePersona.setPublicencryptionKey(pubEncKey, privSignKey)

mutablePersona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ Object

mutablePersona.loadAttributes() ⇒ Promise.<JSON, Error>

mutablePersona.load(claims) ⇒ Promise.<JSON, Error>

mutablePersona.getProfile() ⇒ JSON

mutablePersona.getPublicSigningKey() ⇒ String

mutablePersona.getPublicEncryptionKey() ⇒ String

mutablePersona.getAllClaims() ⇒ JSON

mutablePersona.getClaims(attributesName) ⇒ JSON

mutablePersona.signAttribute(attribute, privSignKey, issuerId) ⇒ Object

mutablePersona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ Array

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

persona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

persona.loadAttributes() ⇒ `Promise.<JSON, Error>`

persona.load(claims) ⇒ `Promise.<JSON, Error>`

persona.getProfile() ⇒ `JSON`

persona.getPublicSigningKey() ⇒ `String`

persona.getPublicEncryptionKey() ⇒ `String`

persona.getAllClaims() ⇒ `JSON`

persona.getClaims(attributesName) ⇒ `JSON`

persona.signAttribute(attribute, privSignKey, issuerId) ⇒ `Object`

persona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ `Array`

Persona.isTokenValid(token) ⇒ `Boolean`

Persona.privateKeyToPublicKey(privateKey) ⇒ `String`

MutablePersona ⇐ `Persona`

mutablePersona.writeToRegistry() ⇒ `Promise.<String, Error>`

mutablePersona.constructor(address, ipfsProvider, web3Provider, [registryAddress]) ⇒ `Object`

mutablePersona.loadAttributes() ⇒ `Promise.<JSON, Error>`

mutablePersona.load(claims) ⇒ `Promise.<JSON, Error>`

mutablePersona.getProfile() ⇒ `JSON`

mutablePersona.getPublicSigningKey() ⇒ `String`

mutablePersona.getPublicEncryptionKey() ⇒ `String`

mutablePersona.getAllClaims() ⇒ `JSON`

mutablePersona.getClaims(attributesName) ⇒ `JSON`

mutablePersona.signAttribute(attribute, privSignKey, issuerId) ⇒ `Object`

mutablePersona.signMultipleAttributes(attribute, privSignKey, issuerId) ⇒ `Array`

Packages