概览
此库按照 ABT - DID - 协议,旨在让开发者更容易在节点.js应用程序中处理定制的DD连接会话,并且应当始终与 连接 UX 软件包,如果您正在编组块块,您可以在 块状 SDK 更有用处.
在典型的DDE Connection会话中,应用程序可以要求用户签署交易或提供一些信息,例如:
- 提供用户配置文件,其中可能包含名称、电子邮件
- 证明NFT的所有权
- 证明护照的所有权
以下图表显示一个典型的 DD 连接会话是如何工作的 :
Claim 是 DID Connect 会话中的关键概念,它被应用程序用来发送完成会话所需的信息的规格。 索赔由下列人员确定: type,并用一组属性定义。 查阅索赔部分的更多信息.
安装
npm install @arcblock/did-auth
// or
pnpm install @arcblock/did-auth
使用量
基本用途
const SimpleStorage = require('@arcblock/did-auth-storage-nedb');
const { fromRandom } = require('@ocap/wallet');
const { WalletAuthenticator, WalletHandlers } = require('@arcblock/did-auth');
// First setup authenticator and handler factory
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/[email protected]',
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' }),
});
// Then attach handler to express server
const express = require('express');
const app = express();
// This is required if you want to use dynamic baseUrl inference
app.set('trust proxy', true);
handlers.attach({
action: 'profile',
claims: {
// This function can be async or returns a promise
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
},
onAuth: async ({ userDid, claims, extraParams }) => {
// `userDid` is the current connected did
// `claims` contains what the user has submitted
// `extraParams` is set from webapp when creating the session
try {
const profile = claims.find((x) => x.type === 'profile');
console.info('login.success', { userDid, profile });
} catch (err) {
console.error('login.error', err);
}
},
});
然后您的应用程序后端可以处理 DID 连接会话, 并接受用户的配置 。 前端集成请退出 连接 UX 是否。 。 。 .
多项索赔
您可以在单个 DDE 连接会话中请求多个请求 :
handlers.attach({
action: 'multiple-claims',
claims: {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
asset: ({ userDid, extraParams }) => {
// `userDid` is the current connected did
// `extraParams` is set from webapp when creating the session
return {
description: 'Please provide a valid NFT',
trustedIssuers: ['nft-issuer-did'],
};
},
},
onAuth: async ({ claims, userDid }) => {
// `claims` contains both the profile and the asset claim
},
});
如果您想要提供多个同类型索赔:
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 }) => {
// `claims` contains both the profile and the asset claim
},
});
动态索赔
通过返回索赔对象 onConnect callback, 您可以为 DID 连接会话提供动态请求 .
handlers.attach({
action: 'dynamic-claims',
// Can be async or returns a promise
onConnect: ({ userDid }) => {
// check userDid for some business logic
// then return the claim object
// you can return multiple claims here
return {
profile: () => ({
fields: ['fullName', 'email'],
description: 'Please provide your name and email to continue',
}),
};
},
onAuth: async ({ claims, userDid }) => {
// `claims` now contains the result for the dynamic claim
},
});
生命周期召回
在 DID- Connect 会话的生命周期中支持后续回调 .
onStart({ req, challenge, didwallet, extraParams, updateSession }): 可选的, 当新会话开始时调用, 可以是async, 从此调回的值将会返回到浏览器并可从浏览器中获取, 错误来自onStart将停止会议.onConnect({ req, challenge, userDid, userPk, extraParams, updateSession }): 可选, 当钱包已选中时userDid财务报告和审定财务报表userPk中,您可以在此返回动态索赔,或者进行一些权限检查,错误来自onConnect将停止会议.onDecline({ req, challenge, userDid, userPk, extraParams, updateSession }): 可选, 当钱包拒绝了 dapp 请求时 .onAuth({ req, challenge, claims, userDid, userPk, extraParams, updateSession }): 需要, 当钱包已经批准 dapp 请求, 并提交信息时, 将会在索赔中提供, 这是一份 dapp 请求的信息列表 .onComplete({ req, userDid, userPk, extraParams, updateSession }):可选,当已连接会话完成时.onExpire({ extraParams }): 可选, 当已连接会话已过期 .onError({ err, extraParams }):可选,当已连接会话遇到出错时,默认为console.error。 。 。 .
最常用的回调是 onConnect 财务报告和审定财务报表 onAuth。 。 。 .
开发者应始终附加一个 onAuth 调用 DDE 连接会话处理器 。 并在用户批准后将业务逻辑放入回调中提交所请求的信息.
有时,开发者可能想要将一些信息传递到会话存储中,例如交易散列或登录令牌,这样浏览器就可以获取供后期使用,开发者可以通过调用实现此目的 updateSession 从 onAuth{\fn华文仿宋\fs16\1chd1d1d1}嗯..,
handlers.attach({
action: 'dynamic-claims',
onAuth: ({ userDid, updateSession }) => {
// to persist plain non-sensible info
await updateSession({ key: 'non-sensible' });
// to persist sensible info: that need to be encrypted
await updateSession({ key: 'sensible' }, true);
},
});
索偿
A 类 claim 指定应用程序可以要求用户提供何种信息。 确定了每项索赔的规格 这里,完整的索赔要求和答复说明可见于 ABT 协议。 。 。 .