zachferland/uport-persona-1

A library for creating, updating and reading attributes and claims on uport personas.

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