Module: did-session

Manages user account DIDs in web based environments.

Purpose

Manages, creates and authorizes a DID session key for a user. Returns an authenticated DIDs instance to be used in other Ceramic libraries. Supports did:pkh for blockchain accounts with Sign-In with Ethereum and CACAO for authorization.

Installation

npm install did-session

Usage

Authorize and use DIDs where needed. Import the AuthMethod you need, Ethereum accounts used here for example.

import { DIDSession } from 'did-session'
import { EthereumWebAuth, getAccountId } from '@didtools/pkh-ethereum'

const ethProvider = // import/get your web3 eth provider
const addresses = await ethProvider.request({ method: 'eth_requestAccounts' })
const accountId = await getAccountId(ethProvider, addresses[0])
const authMethod = await EthereumWebAuth.getAuthMethod(ethprovider, accountId)

const session = await DIDSession.get(accountId, authMethod, { resources: [...]})

// Uses DIDs in ceramic & glaze libraries, ie
const ceramic = new CeramicClient()
ceramic.did = session.did

// pass ceramic instance where needed

Additional helper functions are available to help you manage a session lifecycle and the user experience.

// Check if authorized or created from existing session string
didsession.hasSession

// Check if session expired
didsession.isExpired

// Get resources session is authorized for
didsession.authorizations

// Check number of seconds till expiration, may want to re auth user at a time before expiration
didsession.expiresInSecs

Configuration

The resources your app needs to write access to must be passed during authorization. Resources are an array of Model Stream Ids or Streams Ids. Typically you will just pass resources from @composedb libraries as you will already manage your Composites and Models there. For example:

import { ComposeClient } from '@composedb/client'

//... Reference above and `@composedb` docs for additional configuration here

const client = new ComposeClient({ceramic, definition})
const resources = client.resources
const session = await DIDSession.get(accountId, authMethod, { resources })
client.setDID(session.did)

By default a session will expire in 1 week. You can change this time by passing the expiresInSecs option to indicate how many seconds from the current time you want this session to expire.

const oneDay = 60 * 60 * 24
const session = await DIDSession.get(accountId, authMethod, { resources: [...], expiresInSecs: oneDay })

A domain/app name is used when making requests, by default in a browser based environment the library will use the domain name of your app. If you are using the library in a non web based environment you will need to pass the domain option otherwise an error will thrown.

const session = await DIDSession.get(accountId, authMethod, { resources: [...], domain: 'YourAppName' })

Upgrading from @glazed/did-session to did-session

authorize changes to a static method which returns a did-session instance and getDID() becomes a did getter. For example:

// Before @glazed/did-session
const session = new DIDSession({ authProvider })
const did = await session.authorize()

// Now did-session
const session = await DIDSession.get(accountId, authMethod, { resources: [...]})
const did = session.did

Upgrading from did-session@0.x.x to did-session@1.x.x

AuthProviders change to AuthMethod interfaces. Similarly you can import the auth libraries you need. How you configure and manage these AuthMethods may differ, but each will return an AuthMethod function to be used with did-session.

// Before with v0.x.x
...
import { EthereumAuthProvider } from '@ceramicnetwork/blockchain-utils-linking'

const ethProvider = // import/get your web3 eth provider
const addresses = await ethProvider.request({ method: 'eth_requestAccounts' })
const authProvider = new EthereumAuthProvider(ethProvider, addresses[0])
const session = new DIDSession({ authProvider })
const did = await session.authorize()

// Now did-session@1.0.0
...
import { EthereumWebAuth, getAccountId } from '@didtools/pkh-ethereum'

const ethProvider = // import/get your web3 eth provider
const addresses = await ethProvider.request({ method: 'eth_requestAccounts' })
const accountId = await getAccountId(ethProvider, addresses[0])
const authMethod = await EthereumWebAuth.getAuthMethod(ethProvider, accountId)
const session = await DIDSession.get(accountId, authMethod, { resources: [...]})
const did = session.did

Classes

• DIDSession

Type Aliases

SessionParams

Ƭ SessionParams: Object

Type declaration

Name	Type
cacao	Cacao
did	DID
keySeed?	Uint8Array

Functions

cacaoContainsResources

▸ cacaoContainsResources(cacao, resources): boolean

Parameters

Name	Type
cacao	Cacao
resources	string[]

Returns

boolean

---

createDIDCacao

▸ createDIDCacao(didKey, cacao): Promise<DID>

Parameters

Name	Type
didKey	DID
cacao	Cacao

Returns

Promise<DID>

---

createDIDKey

▸ createDIDKey(seed?): Promise<DID>

Parameters

Name	Type
seed?	Uint8Array

Returns

Promise<DID>

---

getAccountIdByDID

▸ getAccountIdByDID(did): AccountId

Parameters

Name	Type
did	string

Returns

AccountId