uport-credentials

DID Specification | Getting Started

uPort Credentials Library

Required Upgrade to uport-credentials@1.0.0 or uport@^0.6.3

^0.6.3 (uport) to support new both new uPort Mobile Clients and legacy uPort Mobile Clients - View Details

v1.0.0 (uport-credentials) to support only new uPort Mobile Clients and to use new features and fixes. In the future only v1.0.0 onwards will be supported.

:bangbang: :warning: v1.0.0 is released at the npm next tag at uport-credentials@next. While ^0.6.3 remains at uport on npm. Only the newest uPort Mobile Client release will work with v1.0.0. It will become the default release once the newest uPort Mobile Client release is widely adopted (~ 2 weeks). Reference master branch for docs and info on current default release ^0.6.3. Documentation for v1.0.0 can only be found here and in the docs folder. The developer site will not contain v1.0.0 documentation until it is the default release :warning: :bangbang:

Integrate uPort Into Your Application

uPort provides a set of tools for creating and managing identities that conform to the decentralized identifier (DID) specification, and for requesting and exchanging verified data between identities.

uPort Credentials simplifies the process of identity creation within JavaScript applications; additionally, it allows applications to easily sign and verify data — signed by other identities to facilitate secure communication between parties. These pieces of data take the form of signed JSON Web Tokens (JWTs), they have specific fields designed for use with uPort clients, described in the uPort specifications, collectively referred to as verifications.

To allow for maximum flexibility, uPort Credential’s only deals with creation and validation of verifications. To pass verifications between a JavaScript application and a user via the uPort mobile app, we have developed the uPort Transports library, use it in conjunction with uPort Credentials when necessary.

To hit the ground running with uPort Credentials, visit the Getting Started guide.

For details on uPort's underlying architecture, read our spec repo or check out the uPort identity contracts.

This library is part of a suite of tools maintained by the uPort Project, a ConsenSys formation. For more information on the project, visit uport.me

Changelog

1.0.0

With the release of uPort Credentials v1.0.0, there are a number of changes to our API -- the main differences to watch out for are described in this document, and the full API reference can be found here. The primary changes consist of function name changes, with the hope of improving clarity. We have also clarified the role of this library as the primary method for creating and verifying messages in the form of verifiable claims, all of which are described in the uPort specs repo.

New static method createIdentity

With the new identity architecture used in this release, it is now possible to create a uPort identity without any on-chain interactions. This static method creates a new keypair of a did and privateKey, which are all that are necessary to create a new identity. A new Credentials object can then be instantiated with a brand new identity as follows:

const {did, privateKey} = Credentials.createIdentity()
const credentials = new Credentials({did, priYeah vateKey})

createRequest -> createDisclosureRequest

This is a simple name change to clarify the fact this creates a request as part of a selective disclosure flow.

New method createDisclosureResponse

To better support two-way communication between all types of uPort clients, it is now possible to create a disclosure response as well as a request from uport-credentials. This is the response part of the selective disclosure flow, and is equivalent to what gets returned by the mobile app when a disclosure is approved.

createVerificationRequest -> createVerificationSignatureRequest

Another name change to clarify that this request asks for a signature from a user, on the provided unsignedClaim.

receive, authenticate -> authenticateDisclosureResponse

The receive method has been removed, and the equivalent authenticate method has been renamed to reflect that it is verifying the response to a selective disclosure request, as well as the fact that the original request came from the verifying identity (i.e. the current Credentials instance). This makes the selective disclosure flow suitable for user authentication.

New method verifyDisclosure

This is a new function to verify a JWT that is not necessarily part of a selective disclosure request (e.g. a JWT that is part of a public profile, or given from a third party). It differs from authenticateDisclsoureResponse in that it does not verify an authentication challenge, so doesn't confirm that the request originated from this identity. Instead it just verifies the data and signer of the claim, and returns the verified object.

attest -> createVerification

We have renamed attest to better clarify that the return value of the attestation creation method is a JWT, and that it does no sending of the attestation/verification on its own. In addition, we have adopted the language verification to refer to the most general sense of attestation, claim, and credential, as the language often can get confusing.

New method createTxRequest

This is a request for a user to make an ethereum transaction. It provides the signature and address of the contract inside a signed JWT, allowing the recipient to verify the identity requesting that they make the transaction, and have the parameters and contract address pre-filled.

lookup -> removed

As the primary method for identity creation and management has changed, we no longer need to look up identities in a uport-specific contract. Instead, DIDs are resolved with the appropriate did-resolver, which handles any lookup/document retrieval necessary for a particular DID.