Overview
This library is implemented according to ABT-DID-Protocol, aiming to make it easier for developers to handle customized DID Connect Sessions in Node.js applications, and should always be used together with DID Connect UX package, if you are composing a blocklet, you may find the wrapped implementation in Blocklet SDK more useful.
Within a typical DID Connect Session, the application may request user to sign a transaction or provide some information, such as:
- Provide a user profile, which may contain name, email
- Prove ownership of a NFT
- Prove ownership of a passport
The following diagram demonstrates how a typical DID Connect Session works:
Claim
is the key concept in DID Connect Session, its used by the application to send specification of required info to finish the session. A claim is identified by type
, and defined with a set of properties. Checkout the claim section for more information.
Install
npm install @arcblock/did-auth
// or
yarn add @arcblock/did-auth
Usage
Basic Usage
const SimpleStorage = require('@arcblock/did-auth-storage-nedb');
const { fromRandom } = require('@ocap/wallet');
const { WalletAuthenticator, WalletHandlers } = require('@arcblock/did-auth');
const wallet = fromRandom();
const authenticator = new WalletAuthenticator({
wallet,
baseUrl: 'http://wangshijun.natapp1.cc',
appInfo: {
description: 'Starter projects to develop web application on forge',
icon: '/images/logo@2x.png',
name: 'Forge Web Starter',
},
chainInfo: {
host: 'http://did-workshop.arcblock.co:8210/api',
id: 'forge',
},
});
const handlers = new WalletHandlers({
authenticator,
tokenStorage: new SimpleStorage({ dbPath: '/tmp/test/auth.db' }),
});
const express = require('express');
const app = express();
app.set('trust proxy', true);
handlers.attach({
action: 'profile',
claims: {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
},
onAuth: async ({ userDid, claims, extraParams }) => {
try {
const profile = claims.find((x) => x.type === 'profile');
console.info('login.success', { userDid, profile });
} catch (err) {
console.error('login.error', err);
}
},
});
Then your application backend is ready to handle DID Connect Session that request and accept profile from user. For frontend integration please checkout DID Connect UX.
Multiple Claims
You can request multiple claims in a single DID Connect Session:
handlers.attach({
action: 'multiple-claims',
claims: {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
asset: ({ userDid, extraParams }) => {
return {
description: 'Please provide a valid NFT',
trustedIssuers: ['nft-issuer-did'],
};
},
},
onAuth: async ({ claims, userDid }) => {
},
});
If you want to provide multiple claims of the same type:
handlers.attach({
action: 'multiple-claims',
claims: {
signText: [
'signature',
{
type: 'mime:text/plain',
data: 'xxxx',
description: 'sign the text to continue',
},
],
signHtml: [
'signature',
{
type: 'mime:text/html',
data: `<h2>This is title</h2>`,
description: 'sign the html to continue',
},
],
},
onAuth: async ({ claims, userDid }) => {
},
});
Dynamic Claims
By returning a claims object from onConnect
callback, you can provide dynamic claims for the DID Connect Session.
handlers.attach({
action: 'dynamic-claims',
onConnect: ({ userDid }) => {
return {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
};
},
onAuth: async ({ claims, userDid }) => {
},
});
Lifecycle Callbacks
Following callbacks are supported during the lifecycle of a DID-Connect session.
onStart({ req, challenge, didwallet, extraParams, updateSession })
: optional, called when a new session starts, can be async, return values from this callback will be returned to and available from browser, error thrown from onStart
will halt the session.onConnect({ req, challenge, userDid, userPk, extraParams, updateSession })
: optional, when wallet has selected userDid
and userPk
, you can return dynamic claims here, or do some permission check, error thrown from onConnect
will halt the session.onDecline({ req, challenge, userDid, userPk, extraParams, updateSession })
: optional, when wallet has rejected dapp request.onAuth({ req, challenge, claims, userDid, userPk, extraParams, updateSession })
: required, when wallet has approved dapp request, and submitted info will be available in claims, which is a list of the dapp requested info.onComplete({ req, userDid, userPk, extraParams, updateSession })
: optional, when the did connect session has completed.onExpire({ extraParams })
: optional, when the did connect session has expired.onError({ err, extraParams })
: optional, when the did connect session encountered some error, default to console.error
.
Most commonly used callbacks are onConnect
and onAuth
.
Developer should always attach an onAuth
callback for a DID Connect session handler. And put the business logic once user has approved and submitted the requested info in the callback.
Sometimes, developer may want to pass some information to the session storage, such as a transaction hash or login token, so that the browser can fetch for later use, developer can achieve this by call updateSession
from onAuth
. eg,
handlers.attach({
action: 'dynamic-claims',
onAuth: ({ userDid, updateSession }) => {
await updateSession({ key: 'non-sensible' });
await updateSession({ key: 'sensible' }, true);
},
});
Claims
A claim
specifies what kind of information the application can request user to provide. specifications for each claim are defined here, complete claim request and response specification can be found in the ABT DID Protocol.