Decentralized identifier management library for browser and node.js
Clone or download
Latest commit b850abb Sep 10, 2018

README.md

DID Client (did-io)

Build Status

A DID (Decentralized Identifier) resolution library for Javascript

Table of Contents

Security

TBD

Background

TBD

See also (related specs):

Install

Requires Node.js 8.3+

To install locally (for development):

git clone https://github.com/digitalbazaar/did-io.git
cd did-io
npm install

To install as a dependency in another project, add this to your package.json:

"did-io": "^0.7.0"

Usage

Setting Up Storage

To work with DIDs, you'll need storage for keys, local DID docs, and notes.

By default, everything is stored in ~/.dids/<method>/<mode>/, where mode is test/live etc.

DIDs are essentially repositories of public keys on various networks / ledgers. Any non-trivial operations that involve them, such as registering, updating, authenticating and so on, necessarily involve working with corresponding private keys.

To aid with experimentation and development of DID-related prototypes, did-io uses a simple filesystem based JSON blob storage system, to store private keys, local copies of DID documents, and DID metadata on one's local machine.

Keys from DID Documents (as well as related metadata) you control will be stored in the ~/.dids/<method>/<mode>/ folder by default, and will be organized by DID.

For example for a DID of "did:method:abcd", the following files would be potentially created:

  • ~/.dids/method/test/did:method:abcd.json
  • ~/.dids/method/test/did:method:abcd.keys.json
  • ~/.dids/method/test/did:method:abcd.meta.json

You can override the storage mechanism for each ledger method (to store JSON files in a different directory, or to use an in-memory MockStore for unit testing).

Veres One Ledger Usage

See the Veres One Method spec for context.

const dids = require('did-io');

const v1 = dids.methods.veres({ mode: 'test' });
// or use mode: 'dev' when testing against a local Veres One node

Retrieving a Veres One DID Document

const did = 'did:v1:test:nym:ApvL3PKAzQvFnRVqyZKhSYD2i8XcsLG1Dy4FrSdEKAdR';

v1.get({ did })
  .then(didDoc => { console.log(JSON.stringify(didDoc, null, 2)); })
  .catch(console.error);

If available (meaning, if you were the one that registered this DID Doc on your machine), this operation also loads corresponding private keys from the local v1.keyStore.

Generating and Registering a Veres One DID Document

// Generate a new DID Document, store the private keys locally
v1.generate({})
  .then(didDocument => {
    // A new didDocument is generated. Log it to console
    console.log('Generated:', JSON.stringify(didDocument, null, 2));
    return didDocument;
  })

  // Now register the newly generated DID Document
  // Use Equihash Proof of Work by default (see below)
  .then(didDocument => v1.register({ didDocument }))

  // Log the results
  .then(registrationResult => {
    // Log the result of registering the didDoc to the VeresOne Test ledger
    console.log('Registered!', JSON.stringify(registrationResult, null, 2));
  })
  .catch(console.error);

Note: This also saves the generated private/public key pairs, a local copy of the document, as well as any metadata, in the local (typically on-disk) store. See Setting Up Storage for more detail.

Registering a (newly generated) DID Document

To register a DID Document using an Equihash proof of work:

v1.register({ didDocument }); // async/Promise based operation

To register using an Accelerator:

const accelerator = 'genesis.testnet.veres.one';
const authDoc = didDocumentFromAccelerator; // obtained previously

v1.register({ didDocument, accelerator, authDoc })
  .then(result => console.log(JSON.stringify(await result.text(), null, 2)))
  .catch(console.error);

Contribute

See the contribute file!

PRs accepted.

Small note: If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com

License

New BSD License (3-clause) © Digital Bazaar