ThreeIdProvider

ThreeIdProvider is a JavaScript SDK that allows developers to create and manage 3ID identities on the Ceramic network. It exposes a DID Provider interface which exposes JOSE signing and decryption though a JSON-RPC interface. ThreeIdProvider can be used in combination with js-did.

Getting Started

Installation

Install 3id-did-provider in your npm project:

$ npm install 3id-did-provider

Usage

Import ThreeIdProvider into your project

Import the 3id-did-provider module

const ThreeIdProvider = require('3id-did-provider')

Import using the dist build in your html code

Understanding the getPermission function

the getPermission configuration parameter is always required when creating an instance of ThreeIdProvider. It is used to give an application permission to decrypt and sign data. What this function should do is to present a dialog to the user in the wallet UI, asking for permission to access the given paths.

The function is called with one parameter which is the request object. It looks like this:

{
  type: 'authenticate',
  origin: 'https://my.app.origin',
  payload: {
    paths: ['/path/1', '/path/2']
  }
}

In the above example the app with origin https://my.app.origin is requesting access to /path/1 and /path/2. If the user consents to this the function should just return the paths array, otherwise an empty array. Note that an array containing only some of the requested paths may also be returned.

Instantiate ThreeIdProvider with an authentication method

To create an instance with an auth method you can pass two params to the create function as shown below. If the auth method doesn't have a 3ID associated with it yet a new 3ID will be created. This means that a seed will be randomly generated in the background. and the given authSecret will be added as an authentication method to the newly created 3ID.

const authSecret = new Uint8Array([ ... ]) // 32 bytes of entropy used to authenticate
const authId = 'myAuthenticationMethod' // a name of the auth method
const ceramic = ... // An instance of Ceramic (either @ceramicnetwork/core, or @ceramicnetwork/http-client)

const threeId = await ThreeIdProvider.create({ getPermission, authSecret, authId, ceramic })

Instantiate ThreeIdProvider with a seed

To create a wallet with a seed you can simply pass it as an option to the constructor. This will create an instance of the ThreeIdProvider that derives all it's keys from this seed. Be careful, if this seed is lost the DID and all of it's data will be lost as well. Note that you will get different 3IDs every time the create method is invoked with the same seed. An authentication method must be used in order to interact with the same 3ID consistently.

const seed = new Uint8Array([ ... ]) // 32 bytes of entropy used as the seed
const ceramic = ... // An instance of Ceramic (either @ceramicnetwork/core, or @ceramicnetwork/http-client)

const threeId = await ThreeIdProvider.create({ getPermission, seed, ceramic })

Using the ThreeIdProvider with js-did

An instance of the DID provider from ThreeIdProvider can be passed directly to js-did.

import ThreeIdResolver from '@ceramicnetwork/3id-did-resolve'
import Ceramic from '@ceramicnetwork/http-client'

const provider = threeId.getDidProvider()
const resolver = ThreeIdResolver.getResolver(new Ceramic())

const did = new DID({ provider, resolver })

Maintainers

@oed

API Documentation

Keychain

Kind: global class

• Keychain
  • new Keychain()
  • .list() ⇒ Array.<string>
  • .add(authId, authSecret)
  • .remove(authId)
  • .status() ⇒ KeychainStatus
  • .commit()

new Keychain()

The Keychain enables adding and removing of authentication methods.

keychain.list() ⇒ Array.<string>

List all current authentication methods.

Kind: instance method of Keychain
Returns: Array.<string> - A list of authIds.

keychain.add(authId, authSecret)

Add a new authentication method (adds to staging).

Kind: instance method of Keychain

Param	Type	Description
authId	String	An identifier for the auth method
authSecret	Uint8Array	The authSecret to use, should be of sufficient entropy

keychain.remove(authId)

Remove an authentication method (adds to staging).

Kind: instance method of Keychain

Param	Type	Description
authId	String	An identifier for the auth method

keychain.status() ⇒ KeychainStatus

Show the staging status of the keychain. Since removing auth methods will rotate the keys of the 3ID its a good idea to remove multiple auth methods at once if desired. Therefore we introduce a commit pattern to do multiple updates to the keychain at once.

Kind: instance method of Keychain
Returns: KeychainStatus - Object that states the staging status of the keychain

keychain.commit()

Commit the staged changes to the keychain.

Kind: instance method of Keychain

Permissions

Kind: global class

• Permissions
  • new Permissions()
  • .request(origin, paths) ⇒ Array.<String>
  • .has(origin, paths) ⇒ Boolean
  • .get(origin) ⇒ Array.<String>
  • .set(origin, paths)

new Permissions()

The Permissions class exposes methods to read and update the given permissions

permissions.request(origin, paths) ⇒ Array.<String>

Request permission for given paths for a given origin.

Kind: instance method of Permissions
Returns: Array.<String> - The paths that where granted permission for

Param	Type	Description
origin	String	Application domain
paths	Array.<String>	The desired paths

permissions.has(origin, paths) ⇒ Boolean

Determine if permission has been given for paths for a given origin.

Kind: instance method of Permissions
Returns: Boolean - True if permission has previously been given

Param	Type	Description
origin	String	Application domain
paths	Array.<String>	The desired paths

permissions.get(origin) ⇒ Array.<String>

Get the paths which the given origin has permission for.

Kind: instance method of Permissions
Returns: Array.<String> - The permissioned paths

Param	Type	Description
origin	String	Application domain

permissions.set(origin, paths)

Set the paths which the given origin should have permission for.

Kind: instance method of Permissions

Param	Type	Description
origin	String	Application domain
paths	Array.<String>	The desired paths

ThreeIdProvider

Kind: global class

• ThreeIdProvider
  • new ThreeIdProvider()
  • instance
    • .keychain
    • .permissions
    • .id
    • .getDidProvider() ⇒ DidProvider
  • static
    • .create(config) ⇒ ThreeIdProvider

new ThreeIdProvider()

Use ThreeIdProvider.create() to create an ThreeIdProvider instance

threeIdProvider.keychain

Kind: instance property of ThreeIdProvider
Properties

Name	Type	Description
keychain	Keychain	Edit the keychain

threeIdProvider.permissions

Kind: instance property of ThreeIdProvider
Properties

Name	Type	Description
permissions	Permissions	Edit permissions

threeIdProvider.id

Kind: instance property of ThreeIdProvider
Properties

Name	Type	Description
id	string	The DID of the ThreeIdProvider instance

threeIdProvider.getDidProvider() ⇒ DidProvider

Get the DIDProvider

Kind: instance method of ThreeIdProvider
Returns: DidProvider - The DIDProvider for this ThreeIdProvider instance

ThreeIdProvider.create(config) ⇒ ThreeIdProvider

Creates an instance of ThreeIdProvider

Kind: static method of ThreeIdProvider
Returns: ThreeIdProvider - An ThreeIdProvider instance

Param	Type	Description
config	Object	The configuration to be used
config.getPermission	function	The function that is called to ask the user for permission
config.ceramic	CeramicApi	The ceramic instance to use
config.loader	TileLoader	An optional TileLoader instance to use
config.seed	Uint8Array	The seed of the 3ID, 32 bytes
config.authSecret	Uint8Array	The authSecret to use, 32 bytes
config.authId	String	The authId is used to identify the authSecret
config.disableIDX	Boolean	Disable creation of the IDX document
config.v03ID	String	A v0 3ID, has to be passed if a migration is being preformed