DID Core

This repository contains a library which is a reference implementation of Decentralized Identifiers (DIDs) v1.0.

Design goal

The main design goal of this library is to be unopinionated and extendible by the consumer. Unopinionated in this sense means that the library does not enforce a specific ideology to use it. Extendible means that the consumer of this library can use this as a base on which they can build more use-case specific functionality.

Another goal is to provide as much utility as possible regarding the main data types (DIDs and DID Documents). By adding this, it allows the consumer to choose their usage of the library to make it fit into their existing infrastructure.

Usage

Using this library is rather straightforward. Please feel free to open an issue if a pattern is missing or does not make sense.

Did class

To create an instance of the Did class, the following code can be used:

import { Did } from 'did-core'

const did = new Did('did:example:org#key-01')

Creating an instance of a Did will also validate the provided DID via a Regex and Zod. Validation however, does not mean that the DID is resolvable or registered.

The URL parts (path, query, fragment and parameters) and DID parts, can be retrieved with the following code:

import { Did } from 'did-core'

const did = new Did('did:example:org#key-01')

const urlParts = did.urlParts
const didParts = did.didParts

A common builder pattern is also applied to this class and can be used to quickly, for example, add a path.

import { Did } from 'did-core'

const did = new Did('did:example:org#key-01').addPath('some-path')

const didWithPath = did.didUrl

Did Document class

A DID Document can be used with the DidDocument class. As with the Did class, a builder pattern is applied to add fields to the document. The DidDocument does some validation, like making sure the service.ids are unique and the verification method references exist, but it will require additional business logic for use-case specific validation. In the future, it should be possible to supply your own validation functionality (please open an issue if this is required).

import { DidDocument } from 'did-core'

const didDocument = new DidDocument({ id: 'did:example:org' })

The id is the only required field, but all the fields of the document can be supplied. The id field also may take an instance of a Did class.

Adding items like verification methods, capability invocations, etc. can be done when instantiating the class, or with builder functionality.

import { DidDocument } from 'did-core'

const didDocument = new DidDocument({
    id: 'did:example:org',
    verificationMethod: [
        {
            id: 'did:example:org#key-01',
            type: 'some-type',
            controller: 'did:example:org'
        }
    ]
}).addAuthentication('did:example:org#key-01')

The addAuthentication method is created for all items inside the DID Document and maybe take a string, Did, VerificationMethod or VerificationMethodOptions. If a string or Did is supplied, it must be a valid reference to an item inside the verificationMethod list inside the DID Document. If it is a not inside it will throw an error, if it should be added anyways, addAuthenticationUnsafe can be used and it will not throw an if the reference is not inside the verificationMethod. It will however, still error if it is not a valid DID URL.

To get the associated verification method from a DID URL, the following method can be used:

import { DidDocument } from 'did-core'

const didDocument = new DidDocument({
    id: 'did:example:org',
    verificationMethod: [
        {
            id: 'did:example:org#key-01',
            type: 'some-type',
            controller: 'did:example:org'
        }
    ]
})

const verificationMethod = didDocument.findVerificationMethodByDidUrl(
    'did:example:org#key-01'
) // errors if not found

// or

const maybeVerificationMethod = didDocument.safeFindVerificationMethodByDidUrl(
    'did:example:org#key-01'
) // returns undefined if not found

Future work

There is no functionality added yet specifically for JSON-LD. The @context field may be supplied to the DID Document, but it will not resolve and validate the URLs.