did-session

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 for the blockchain or method you need and begin using it with did-session.

Ethereum accounts with EthereumWebAuth and an Ethereum provider (implementing the standard EIP-1193) are used here for example.

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

const ethProvider = // import/get your web3 eth provider (Implements EIP-1193)
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

You can also get an AccountId from a user's DID instead of the address and provider.

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

const ethProvider = // import/get your web3 eth provider (Implements EIP-1193)
const userDID = // have a user's DID
const authMethod = await EthereumWebAuth.getAuthMethod(ethprovider, getAccountIdByDID(userDID))

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 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

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

License

Dual licensed under MIT and Apache 2