@arcblock/did-connect-js 1.21.2

package/lib/handlers/wallet.js

@@ -0,0 +1,168 @@
+/* eslint-disable object-curly-newline */
+// eslint-disable-next-line
+const debug = require('debug')(`${require('../../package.json').name}:handlers:wallet`);
+
+const cors = require('cors');
+
+const createHandlers = require('./util');
+const BaseHandler = require('./base');
+
+const noop = () => {};
+
+/**
+ * Events that are emitted during an DID Connect process
+ *
+ *  - scanned: when the qrcode is scanned by wallet
+ *  - succeed: when authentication complete
+ *  - error: when something goes wrong
+ *
+ * @class WalletHandlers
+ * @extends {EventEmitter}
+ */
+class WalletHandlers extends BaseHandler {
+  /**
+   * Creates an instance of DID Auth Handlers.
+   *
+   * @class
+   * @param {object} config
+   * @param {object} config.tokenStorage - function to generate action token
+   * @param {object} config.authenticator - Authenticator instance that can to jwt sign/verify
+   * @param {function} [config.pathTransformer=null] - how should we update pathname
+   * @param {function} [config.onConnect=noop] - function called before each auth request send back to app, used to check for permission, throw error to halt the auth process
+   * @param {object} [config.options={}] - custom options to define all handlers attached
+   * @param {string} [config.options.prefix='/api/did'] - url prefix for this group endpoints
+   * @param {number} [config.options.cleanupDelay=60000] - how long to wait before cleanup finished session
+   * @param {string} [config.options.tokenKey='_t_'] - query param key for `token`
+   * @param {string} [config.options.encKey='_ek_'] - query param key for encryption key
+   * @param {string} [config.options.versionKey='_v_'] - query param key for protocol `version`
+   */
+  constructor({ pathTransformer, tokenStorage, authenticator, onConnect = noop, options = {} }) {
+    super({ pathTransformer, tokenStorage, authenticator, onConnect });
+
+    this.options = {
+      prefix: '/api/did',
+      cleanupDelay: 60000,
+      tokenKey: '_t_',
+      encKey: '_ek_',
+      versionKey: '_v_',
+      ...options,
+    };
+  }
+
+  /**
+   * Attach routes and handlers for authenticator
+   * Now express app have route handlers attached to the following url
+   * - `GET /api/did/{action}/token` create new token
+   * - `GET /api/did/{action}/status` check for token status
+   * - `GET /api/did/{action}/timeout` expire a token
+   * - `GET /api/did/{action}/auth` create auth response
+   * - `POST /api/did/{action}/auth` process payment request
+   *
+   * @method
+   * @param {object} config
+   * @param {object} config.app - express instance to attach routes to
+   * @param {object} [config.claims] - claims for this request
+   * @param {string} config.action - action of this group of routes
+   * @param {function} [config.onStart=noop] - callback when a new action start
+   * @param {function} [config.onConnect=noop] - callback when a new action start
+   * @param {function} config.onAuth - callback when user completed auth in DID Wallet, and data posted back
+   * @param {function} [config.onDecline=noop] - callback when user has declined in wallet
+   * @param {function} [config.onComplete=noop] - callback when the whole auth process is done, action token is removed
+   * @param {function} [config.onExpire=noop] - callback when the action token expired
+   * @param {function} [config.onError=console.error] - callback when there are some errors
+   * @param {boolean|string|did} [config.authPrincipal=true] - whether should we do auth principal claim first
+   * @param {boolean} [config.persistentDynamicClaims=false] - whether should we persist dynamic claims
+   * @return void
+   */
+  attach({
+    app,
+    action,
+    claims = undefined,
+    onStart = noop,
+    onConnect,
+    onAuth,
+    onDecline = noop,
+    onComplete = noop,
+    onExpire = noop,
+    // eslint-disable-next-line no-console
+    onError = console.error,
+    authPrincipal = true,
+    persistentDynamicClaims = false,
+  }) {
+    if (typeof onAuth !== 'function') {
+      throw new Error('onAuth callback is required to attach did auth handlers');
+    }
+    if (typeof onDecline !== 'function') {
+      throw new Error('onDecline callback is required to attach did auth handlers');
+    }
+    if (typeof onComplete !== 'function') {
+      throw new Error('onComplete callback is required to attach did auth handlers');
+    }
+
+    const { prefix } = this.options;
+
+    // pathname for DID Wallet, which will be included for authenticator signing
+    const pathname = `${prefix}/${action}/auth`;
+    debug('attach routes', { action, prefix, pathname });
+
+    // eslint-disable-next-line consistent-return
+    const onConnectWrapped = async (...args) => {
+      if (typeof this.onConnect === 'function') {
+        await this.onConnect(...args);
+      }
+      if (typeof onConnect === 'function') {
+        return onConnect(...args);
+      }
+    };
+
+    const {
+      generateSession,
+      expireSession,
+      checkSession,
+      onAuthRequest,
+      onAuthResponse,
+      ensureContext,
+      ensureSignedJson,
+    } = createHandlers({
+      action,
+      pathname,
+      claims,
+      onStart,
+      onConnect: onConnectWrapped, // must be deterministic when returning dynamic claims
+      onAuth,
+      onDecline,
+      onComplete,
+      onExpire,
+      onError,
+      authPrincipal,
+      persistentDynamicClaims,
+      options: this.options,
+      pathTransformer: this.pathTransformer,
+      tokenStorage: this.tokenStorage,
+      authenticator: this.authenticator,
+    });
+
+    app.use(`${prefix}/${action}`, cors({ origin: '*', optionsSuccessStatus: 204 }));
+
+    // 1. WEB|Wallet: to generate new token
+    app.get(`${prefix}/${action}/token`, generateSession);
+    app.post(`${prefix}/${action}/token`, generateSession);
+
+    // 2. WEB: check for token status
+    app.get(`${prefix}/${action}/status`, ensureContext, checkSession);
+
+    // 3. WEB: to expire old token
+    app.get(`${prefix}/${action}/timeout`, ensureContext, expireSession);
+
+    // 4. Wallet: fetch auth request
+    app.get(pathname, ensureContext, ensureSignedJson, onAuthRequest);
+
+    // 5. Wallet: submit auth response
+    app.post(pathname, ensureContext, ensureSignedJson, onAuthResponse);
+
+    // 6. Wallet: submit auth response for web wallet
+    app.get(`${pathname}/submit`, ensureContext, ensureSignedJson, onAuthResponse);
+  }
+}
+
+module.exports = WalletHandlers;

package/lib/index.d.ts

@@ -0,0 +1,384 @@
+// Generate by [js2dts@0.3.3](https://github.com/whxaxes/js2dts#readme)
+
+import * as events from 'events';
+declare class BaseAuthenticator {}
+declare class WalletAuthenticator extends BaseAuthenticator {
+  wallet: any;
+  appInfo: any;
+  memberAppInfo: any;
+  chainInfo: any;
+  delegator: any;
+  delegation: any;
+  baseUrl: any;
+  tokenKey: any;
+  timeout: any;
+  /**
+   * @typedef ApplicationInfo
+   * @prop {string} name - application name
+   * @prop {string} description - application description
+   * @prop {string} icon - application icon/logo url
+   * @prop {string} link - application home page, with which user can return application from wallet
+   * @prop {string} path - deep link url
+   * @prop {string} publisher - application did with `did:abt:` prefix
+   */
+
+  /**
+   * @typedef ChainInfo
+   * @prop {string} id - application chain id
+   * @prop {string} type - application chain type
+   * @prop {string} host - graphql endpoint of the application chain
+   */
+
+  /**
+   * Creates an instance of DID Authenticator.
+   *
+   * @class
+   * @param {object} config
+   * @param {WalletObject|Function} config.wallet - wallet instance {@see @ocap/wallet} or a function that returns wallet instance
+   * @param {WalletObject|Function} [config.delegator] - the party that authorizes `wallet` to perform actions on behalf of `wallet`
+   * @param {string|Function} [config.delegation] - the jwt token that proves delegation relationship
+   * @param {ApplicationInfo|Function} config.appInfo - application basic info or a function that returns application info
+   * @param {ChainInfo|Function} config.chainInfo - application chain info or a function that returns chain info
+   * @param {Number} [config.timeout=8000] - timeout in milliseconds when generating claim
+   * @param {object} [config.baseUrl] - url to assemble wallet request uri, can be inferred from request object
+   * @param {string} [config.tokenKey='_t_'] - query param key for `token`
+   * @example
+   * const { fromRandom } = require('@ocap/wallet');
+   *
+   * const wallet = fromRandom().toJSON();
+   * const chainHost = 'https://beta.abtnetwork.io/api';
+   * const chainId = 'beta';
+   * const auth = new Authenticator({
+   *   wallet,
+   *   baseUrl: 'http://beta.abtnetwork.io/webapp',
+   *   appInfo: {
+   *     name: 'DID Wallet Demo',
+   *     description: 'Demo application to show the potential of DID Wallet',
+   *     icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
+   *   },
+   *   memberAppInfo: null,
+   *   chainInfo: {
+   *     host: chainHost,
+   *     id: chainId,
+   *   },
+   *   timeout: 8000,
+   * });
+   */
+  constructor(T100: _Lib.T101);
+  /**
+   * Generate a deep link url that can be displayed as QRCode for DID Wallet to consume
+   *
+   * @method
+   * @param {object} params
+   * @param {string} params.baseUrl - baseUrl inferred from request object
+   * @param {string} params.pathname - wallet callback pathname
+   * @param {string} params.token - action token
+   * @param {object} params.query - params that should be persisted in wallet callback url
+   * @returns {string}
+   */
+  uri(T102?: _Lib.T103): string;
+  /**
+   * Compute public url to return to wallet
+   *
+   * @method
+   * @param {string} pathname
+   * @param {object} params
+   * @returns {string}
+   */
+  getPublicUrl(pathname: string, params?: any, baseUrl?: string): string;
+  /**
+   * Sign a plain response, usually on auth success or error
+   *
+   * @method
+   * @param {object} params
+   * @param {object} params.response - response
+   * @param {string} params.errorMessage - error message, default to empty
+   * @param {string} params.successMessage - success message, default to empty
+   * @param {string} params.nextWorkflow - https://github.com/ArcBlock/ABT-DID-Protocol#concatenate-multiple-workflow
+   * @param {string} params.nextUrl - tell wallet do open this url in webview
+   * @param {object} params.cookies - key-value pairs to be set as cookie before open nextUrl
+   * @param {object} params.storages - key-value pairs to be set as localStorage before open nextUrl
+   * @param {string} baseUrl
+   * @param {object} request
+   * @returns {Promise<object>} { appPk, agentPk, authInfo }
+   */
+  signResponse(T104: _Lib.T105, baseUrl: string, request: any, extraParams?: _Lib.T106): Promise<any>;
+  /**
+   * Sign a auth response that returned to wallet: tell the wallet the appInfo/chainInfo
+   *
+   * @method
+   * @param {object} params
+   * @param {object} params.claims - info required by application to complete the auth
+   * @param {string} params.pathname - pathname to assemble callback url
+   * @param {string} params.baseUrl - baseUrl
+   * @param {object} params.challenge - random challenge to be included in the body
+   * @param {object} params.extraParams - extra query params and locale
+   * @param {object} params.request
+   * @param {object} params.context
+   * @param {string} params.context.token - action token
+   * @param {number} params.context.currentStep - current step
+   * @param {string} [params.context.sharedKey] - shared key between app and wallet
+   * @param {string} [params.context.encryptionKey] - encryption key from wallet
+   * @param {Function} [params.context.mfaCode] - function used to generate mfa code
+   * @param {string} params.context.userDid - decoded from req.query, base58
+   * @param {string} params.context.userPk - decoded from req.query, base58
+   * @param {string} params.context.didwallet - DID Wallet os and version
+   * @returns {Promise<object>} { appPk, agentPk, sharedKey, authInfo }
+   */
+  sign(T107: _Lib.T109): Promise<any>;
+  /**
+   * Determine chainInfo on the fly
+   *
+   * @param {object} params - contains the context of this request
+   * @param {object|undefined} [info=undefined] - chain info object or function
+   * @returns {Promise<ChainInfo>}
+   * @memberof WalletAuthenticator
+   */
+  getChainInfo(params: any, info: any): Promise<ChainInfo>;
+  /**
+   * Determine appInfo/memberAppInfo on the fly
+   *
+   * @param {object} params - contains the context of this request
+   * @param {string} key - appInfo | memberAppInfo
+   * @returns {Promise<ApplicationInfo>}
+   * @memberof WalletAuthenticator
+   */
+  getAppInfo(params: any, key?: string): Promise<ApplicationInfo>;
+  getWalletInfo(params: any): Promise<any>;
+  getDelegator(params: any): Promise<any>;
+  getDelegation(params: any): Promise<any>;
+  /**
+   * Verify a DID auth response sent from DID Wallet
+   *
+   * @method
+   * @param {object} data
+   * @param {string} [locale=en]
+   * @param {boolean} [enforceTimestamp=true]
+   * @returns Promise<boolean>
+   */
+  verify(data: any, locale?: string, enforceTimestamp?: boolean): Promise<_Lib.T110>;
+  genRequestedClaims(T111: _Lib.T112): Promise<any[]>;
+  getClaimInfo(T113: _Lib.T114): Promise<any>;
+  signature(T115: _Lib.T114): Promise<_Lib.T116>;
+  prepareTx(T117: _Lib.T114): Promise<_Lib.T118>;
+  tryWithTimeout(asyncFn: any): Promise<any>;
+}
+declare class BaseHandler extends events {
+  authenticator: any;
+  tokenStorage: any;
+  pathTransformer(...args: any[]): any;
+  onConnect(...args: any[]): any;
+  /**
+   * Creates an instance of DID Auth Handlers.
+   *
+   * @class
+   * @param {object} config
+   * @param {function} config.pathTransformer - function to transform path when generate action;
+   * @param {object} config.tokenStorage - function to generate action token
+   * @param {object} config.authenticator - Authenticator instance that can to jwt sign/verify
+   * @param {function} [config.onConnect=noop] - function called when wallet selected did
+   */
+  constructor(T119: _Lib.T120);
+}
+/**
+ * Events that are emitted during an DID Connect process
+ *
+ *  - scanned: when the qrcode is scanned by wallet
+ *  - succeed: when authentication complete
+ *  - error: when something goes wrong
+ *
+ * @class WalletHandlers
+ * @extends {EventEmitter}
+ */
+declare class WalletHandlers extends BaseHandler {
+  options: _Lib.T124;
+  /**
+   * Creates an instance of DID Auth Handlers.
+   *
+   * @class
+   * @param {object} config
+   * @param {object} config.tokenStorage - function to generate action token
+   * @param {object} config.authenticator - Authenticator instance that can to jwt sign/verify
+   * @param {function} [config.pathTransformer=null] - how should we update pathname
+   * @param {function} [config.onConnect=noop] - function called before each auth request send back to app, used to check for permission, throw error to halt the auth process
+   * @param {object} [config.options={}] - custom options to define all handlers attached
+   * @param {string} [config.options.prefix='/api/did'] - url prefix for this group endpoints
+   * @param {number} [config.options.cleanupDelay=60000] - how long to wait before cleanup finished session
+   * @param {string} [config.options.tokenKey='_t_'] - query param key for `token`
+   * @param {string} [config.options.encKey='_ek_'] - query param key for encryption key
+   * @param {string} [config.options.versionKey='_v_'] - query param key for protocol `version`
+   */
+  constructor(T121: _Lib.T123);
+  /**
+   * Attach routes and handlers for authenticator
+   * Now express app have route handlers attached to the following url
+   * - `GET /api/did/{action}/token` create new token
+   * - `GET /api/did/{action}/status` check for token status
+   * - `GET /api/did/{action}/timeout` expire a token
+   * - `GET /api/did/{action}/auth` create auth response
+   * - `POST /api/did/{action}/auth` process payment request
+   *
+   * @method
+   * @param {object} config
+   * @param {object} config.app - express instance to attach routes to
+   * @param {object} [config.claims] - claims for this request
+   * @param {string} config.action - action of this group of routes
+   * @param {function} [config.onStart=noop] - callback when a new action start
+   * @param {function} [config.onConnect=noop] - callback when a new action start
+   * @param {function} config.onAuth - callback when user completed auth in DID Wallet, and data posted back
+   * @param {function} [config.onDecline=noop] - callback when user has declined in wallet
+   * @param {function} [config.onComplete=noop] - callback when the whole auth process is done, action token is removed
+   * @param {function} [config.onExpire=noop] - callback when the action token expired
+   * @param {function} [config.onError=console.error] - callback when there are some errors
+   * @param {boolean|string|did} [config.authPrincipal=true] - whether should we do auth principal claim first
+   * @param {boolean} [config.persistentDynamicClaims=false] - whether should we persist dynamic claims
+   * @return void
+   */
+  attach(T125: _Lib.T126): void;
+}
+declare const _Lib: _Lib.T127;
+declare namespace _Lib {
+  export interface T101 {
+    wallet: any;
+  }
+  export interface T103 {
+    baseUrl: string;
+    pathname: string;
+    token: string;
+    query: any;
+  }
+  export interface T105 {
+    response: any;
+    errorMessage: string;
+    successMessage: string;
+    nextWorkflow: string;
+    nextUrl: string;
+    cookies: any;
+    storages: any;
+  }
+  export interface T106 {
+    [key: string]: any;
+  }
+  export interface T108 {
+    token: string;
+    currentStep: number;
+    sharedKey?: string;
+    encryptionKey?: string;
+    mfaCode?: (...args: any[]) => any;
+    userDid: string;
+    userPk: string;
+    didwallet: string;
+  }
+  export interface T109 {
+    claims: any;
+    pathname: string;
+    baseUrl: string;
+    challenge: any;
+    extraParams: any;
+    request: any;
+    context: _Lib.T108;
+  }
+  export interface ChainInfo {
+    id: string;
+    type: string;
+    host: string;
+  }
+  export interface ApplicationInfo {
+    name: string;
+    description: string;
+    icon: string;
+    link: string;
+    path: string;
+    publisher: string;
+  }
+  export interface T110 {
+    token: any;
+    userDid: string;
+    userPk: any;
+    claims: any;
+    action: any;
+    challenge: any;
+    timestamp: string;
+  }
+  export interface T112 {
+    claims: any;
+    context: any;
+    extraParams: any;
+  }
+  export interface T114 {
+    claim: any;
+    context: any;
+    extraParams: any;
+  }
+  export interface T116 {
+    type: string;
+    description: any;
+    origin: string;
+    typeUrl: any;
+    display: any;
+    method: any;
+    digest: any;
+    chainInfo: any;
+    meta: any;
+    mfa: any;
+    nonce: any;
+    requirement: any;
+  }
+  export interface T118 {
+    type: string;
+    description: string;
+    partialTx: string;
+    display: any;
+    requirement: any;
+    chainInfo: any;
+    meta: any;
+    mfa: any;
+    nonce: any;
+  }
+  export interface T120 {
+    pathTransformer: (...args: any[]) => any;
+    tokenStorage: any;
+    authenticator: any;
+    onConnect?: (...args: any[]) => any;
+  }
+  export interface T122 {
+    prefix?: string;
+    cleanupDelay?: number;
+    tokenKey?: string;
+    encKey?: string;
+    versionKey?: string;
+  }
+  export interface T123 {
+    tokenStorage: any;
+    authenticator: any;
+    pathTransformer?: (...args: any[]) => any;
+    onConnect?: (...args: any[]) => any;
+    options?: _Lib.T122;
+  }
+  export interface T124 {
+    prefix: string;
+    cleanupDelay: number;
+    tokenKey: string;
+    encKey: string;
+    versionKey: string;
+  }
+  export interface T126 {
+    app: any;
+    claims?: any;
+    action: string;
+    onStart?: (...args: any[]) => any;
+    onConnect?: (...args: any[]) => any;
+    onAuth: (...args: any[]) => any;
+    onDecline?: (...args: any[]) => any;
+    onComplete?: (...args: any[]) => any;
+    onExpire?: (...args: any[]) => any;
+    onError?: (...args: any[]) => any;
+    authPrincipal?: any;
+    persistentDynamicClaims?: boolean;
+  }
+  export interface T127 {
+    WalletAuthenticator: typeof WalletAuthenticator;
+    WalletHandlers: typeof WalletHandlers;
+  }
+}
+export = _Lib;

package/lib/index.js

@@ -0,0 +1,7 @@
+const WalletAuthenticator = require('./authenticator/wallet');
+const WalletHandlers = require('./handlers/wallet');
+
+module.exports = {
+  WalletAuthenticator,
+  WalletHandlers,
+};

package/lib/protocol.js

@@ -0,0 +1,46 @@
+const AES = require('@ocap/mcrypto/lib/crypter/aes').default;
+const { decode } = require('@arcblock/jwt');
+const { fromBase58 } = require('@ocap/util');
+
+const VERSION = '1.0.0';
+
+const decrypt = (data, config = {}, dataKey = 'userInfo') => {
+  try {
+    decode(data[dataKey]);
+    return data;
+  } catch {
+    // Do nothing
+  }
+
+  if (config.sharedKey && data.version === VERSION) {
+    data[dataKey] = AES.decrypt(fromBase58(data[dataKey]), config.sharedKey, 'buffer').toString('utf8');
+  }
+  return data;
+};
+
+const encrypt = (data, config = {}, dataKey = 'authInfo') => {
+  const { clientVersion, sharedKey } = config || {};
+  if (data.sensitive && sharedKey && clientVersion === VERSION) {
+    data.version = VERSION;
+    data[dataKey] = AES.encrypt(data[dataKey], sharedKey, 'base58');
+  }
+
+  delete data.sensitive;
+
+  return data;
+};
+
+module.exports = {
+  decrypt,
+  encrypt,
+  VERSION,
+  PROTECTED_KEYS: ['challenge', 'nonce', 'sharedKey', 'encryptionKey'],
+  SESSION_STATUS: {
+    CREATED: 'created',
+    SUCCEED: 'succeed',
+    ERROR: 'error',
+    BUSY: 'busy',
+    SCANNED: 'scanned',
+    FORBIDDEN: 'forbidden',
+  },
+};