did-session/README.md

Manage user DIDs in a web environment

# 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

```sh
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](https://eips.ethereum.org/EIPS/eip-1193)) are used here for example.

```js
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.

```js
// 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.

```js
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:

```js
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.

```js
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.

```js
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.

```js
// 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:

```js
// 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](LICENSE-MIT) and [Apache 2](LICENSE-APACHE)