@arcblock/did-connect-js 1.21.2

package/lib/handlers/util.js

@@ -0,0 +1,943 @@
+/* eslint-disable no-underscore-dangle */
+/* eslint-disable prefer-destructuring */
+/* eslint-disable object-curly-newline */
+/* eslint-disable consistent-return */
+const url = require('url');
+const get = require('lodash/get');
+const set = require('lodash/set');
+const pick = require('lodash/pick');
+const omit = require('lodash/omit');
+const random = require('lodash/random');
+const cloneDeep = require('lodash/cloneDeep');
+const isEqual = require('lodash/isEqual');
+const isPlainObject = require('lodash/isPlainObject');
+const semver = require('semver');
+const Mcrypto = require('@ocap/mcrypto');
+const SealedBox = require('tweetnacl-sealedbox-js');
+const stringify = require('json-stable-stringify');
+const { isValid: isValidDid } = require('@arcblock/did');
+const { stripHexPrefix, toBase64, fromBase64 } = require('@ocap/util');
+
+const { encrypt, decrypt, SESSION_STATUS, PROTECTED_KEYS } = require('../protocol');
+
+// Scheme: https://tools.ietf.org/html/rfc3986#section-3.1
+// Absolute URL: https://tools.ietf.org/html/rfc3986#section-4.3
+const ABSOLUTE_URL_REGEX = /^[a-zA-Z][a-zA-Z\d+\-.]*?:/;
+// Windows paths like `c:\`
+const WINDOWS_PATH_REGEX = /^[a-zA-Z]:\\/;
+const isUrl = (input) => {
+  if (typeof input !== 'string') {
+    return false;
+  }
+  if (WINDOWS_PATH_REGEX.test(input)) {
+    return false;
+  }
+  return ABSOLUTE_URL_REGEX.test(input);
+};
+
+// eslint-disable-next-line
+const debug = require('debug')(`${require('../../package.json').name}:handlers:util`);
+
+const sha3 = Mcrypto.Hasher.SHA3.hash256;
+const getLocale = (req) => (req.acceptsLanguages('en-US', 'zh-CN') || 'en-US').split('-').shift();
+const getSessionId = () => Date.now().toString();
+const noop = () => ({});
+const noTouch = (x) => x;
+
+const errors = {
+  tokenMissing: {
+    en: 'Session Id is required to check status',
+    zh: '缺少会话 ID 参数',
+  },
+  didMismatch: {
+    en: 'Login user and wallet user mismatch, please relogin and try again',
+    zh: '登录用户和扫码用户不匹配，为保障安全，请重新登录应用',
+  },
+  mfaMismatch: {
+    en: 'Dynamic verification code mismatch, please try again later',
+    zh: '动态验证码不匹配，请重试',
+  },
+  challengeMismatch: {
+    en: 'Challenge mismatch',
+    zh: '随机校验码不匹配',
+  },
+  token404: {
+    en: 'Session not found or expired',
+    zh: '会话不存在或已过期',
+  },
+  didMissing: {
+    en: 'userDid is required to start auth',
+    zh: 'userDid 参数缺失，请勿尝试连接多个不同的钱包',
+  },
+  pkMissing: {
+    en: 'userPk is required to start auth',
+    zh: 'userPk 参数缺失，请勿尝试连接多个不同的钱包',
+  },
+  authClaim: {
+    en: 'authPrincipal claim is not configured correctly',
+    zh: 'authPrincipal 声明配置不正确',
+  },
+  userDeclined: {
+    en: 'You have declined the authentication request',
+    zh: '授权请求被拒绝',
+  },
+  userBusy: {
+    en: 'Busy processing another DID Connect request',
+    zh: '正在处理其他请求',
+  },
+};
+
+// This logic exist because the handlers maybe attached to a nested router
+// pathname pattern: /:prefix/:action/auth
+// But the group of handlers may be attached to a sub router, which has a baseUrl of `/api/login` (can only be extracted from `req.originalUrl`)
+// We need to ensure the full url is given to DID Wallet
+// eg: `/agent/login/auth` on the current router will be converted to `/api/login/agent/login/auth`
+const _preparePathname = (path, req) => {
+  const delimiter = path.replace(/\/retrieve$/, '').replace(/\/auth$/, '');
+  const fullPath = url.parse(req.originalUrl).pathname;
+  const [prefix] = fullPath.split(delimiter);
+  const cleanPath = [prefix, path].join('/').replace(/\/+/g, '/');
+  // console.log('preparePathname', { path, delimiter, fullPath, prefix, cleanPath });
+  return cleanPath;
+};
+
+const getBaseUrl = (req) => {
+  if (req.headers['x-path-prefix']) {
+    return `/${req.headers['x-path-prefix']}/`.replace(/\/+/g, '/');
+  }
+
+  return '/';
+};
+
+// This makes the lib smart enough to infer baseURL from request object
+const prepareBaseUrl = (req, params) => {
+  const pathPrefix = getBaseUrl(req).replace(/\/$/, '');
+  const [hostname = '', port = 80] = (
+    req.get('x-forwarded-host') ||
+    req.get('x-real-hostname') ||
+    req.get('host') ||
+    ''
+  ).split(':');
+  // NOTE: x-real-port exist because sometimes the auth api is behind a port-forwarding proxy
+  const finalPort = get(params, 'x-real-port', null) || req.get('X-Real-Port') || port || '';
+  return url.format({
+    protocol:
+      get(params, 'x-real-protocol') || req.get('X-Real-protocol') || req.get('X-Forwarded-Proto') || req.protocol,
+    hostname,
+    port: Number(finalPort) === 80 ? '' : finalPort,
+    pathname: pathPrefix,
+  });
+};
+
+// https://github.com/joaquimserafim/base64-url/blob/54d9c9ede66a8724f280cf24fd18c38b9a53915f/index.js#L10
+const unescape = (str) => (str + '==='.slice((str.length + 3) % 4)).replace(/-/g, '+').replace(/_/g, '/');
+const decodeEncKey = (str) => new Uint8Array(Buffer.from(unescape(str), 'base64'));
+
+const getStepChallenge = () => stripHexPrefix(Mcrypto.getRandomBytes(16)).toUpperCase();
+
+const parseWalletUA = (userAgent) => {
+  const ua = (userAgent || '').toString().toLowerCase();
+  let os = '';
+  let version = '';
+  if (ua.indexOf('android') > -1) {
+    os = 'android';
+  } else if (ua.indexOf('iphone') > -1) {
+    os = 'ios';
+  } else if (ua.indexOf('ipad') > -1) {
+    os = 'ios';
+  } else if (ua.indexOf('ipod') > -1) {
+    os = 'ios';
+  } else if (ua.indexOf('arcwallet') === 0) {
+    os = 'web';
+  } else if (ua.indexOf('abtwallet') === 0) {
+    os = 'web';
+  }
+
+  const match = ua.split(/\s+/).find((x) => x.startsWith('arcwallet/') || x.startsWith('abtwallet/'));
+  if (match) {
+    const tmp = match.split('/');
+    if (tmp.length > 1 && semver.coerce(tmp[1])) {
+      version = semver.coerce(tmp[1]).version;
+    }
+  }
+
+  return { os, version, jwt: '1.1.0' };
+};
+
+const isDeepLink = (str) => str.startsWith('https://abtwallet.io/i/') || str.startsWith('https://didwallet.io/i/');
+
+// whether we should force did-wallet to connect with userDid from session
+const isConnectedOnly = (params, sessionUserDid = '') => {
+  if (typeof params.forceConnected === 'string' && isValidDid(params.forceConnected)) {
+    return params.forceConnected;
+  }
+
+  if (!sessionUserDid) {
+    return false;
+  }
+
+  if (isValidDid(sessionUserDid) === false) {
+    return false;
+  }
+
+  if (params.connectedDid !== sessionUserDid) {
+    return false;
+  }
+
+  // auto
+  if (typeof params.forceConnected === 'undefined') {
+    return true;
+  }
+
+  // query string from client: `true` | `false` | did
+  if (typeof params.forceConnected === 'string') {
+    try {
+      return !!JSON.parse(params.forceConnected);
+    } catch {
+      return false;
+    }
+  }
+
+  return !!params.forceConnected;
+};
+
+// If we treat an did-connect roundtrip as a session, then action token is the session id
+module.exports = function createHandlers({
+  action,
+  pathname,
+  claims,
+  onStart,
+  onConnect,
+  onAuth,
+  onDecline,
+  onComplete,
+  onExpire,
+  onError,
+  pathTransformer,
+  tokenStorage,
+  authenticator,
+  authPrincipal,
+  persistentDynamicClaims = false,
+  getSignParams = noop,
+  getPathName = noTouch,
+  options,
+}) {
+  const { tokenKey, encKey, versionKey, cleanupDelay } = options;
+
+  const defaultSteps = (Array.isArray(claims) ? claims : [claims]).filter(Boolean);
+
+  // Smart detection of user-defined authPrincipal claim
+  if (defaultSteps.length > 0) {
+    const keys = Object.keys(defaultSteps[0]);
+    const firstClaim = defaultSteps[0][keys[0]];
+    if (Array.isArray(firstClaim)) {
+      if (firstClaim[0] === 'authPrincipal') {
+        // eslint-disable-next-line no-param-reassign
+        authPrincipal = false;
+      }
+    } else if (keys[0] === 'authPrincipal') {
+      // eslint-disable-next-line no-param-reassign
+      authPrincipal = false;
+    }
+  }
+
+  // Prepend default authPrincipal claim if not set
+  if (authPrincipal) {
+    let target = '';
+    let description = 'Please continue with your account';
+    let chainInfo;
+    let targetType;
+
+    if (typeof authPrincipal === 'string') {
+      if (isValidDid(authPrincipal)) {
+        // If auth principal is provided as a did
+        target = authPrincipal;
+      } else {
+        // If auth principal is provided as a string
+        description = authPrincipal;
+      }
+    }
+    if (typeof authPrincipal === 'object') {
+      target = get(authPrincipal, 'target', target);
+      description = get(authPrincipal, 'description', description);
+      targetType = get(authPrincipal, 'targetType', targetType);
+
+      // If provided a chainInfo
+      if (authPrincipal.chainInfo && authenticator._isValidChainInfo(authPrincipal.chainInfo)) {
+        chainInfo = authPrincipal.chainInfo;
+      }
+    }
+
+    const supervised = defaultSteps.length === 0;
+    defaultSteps.unshift({
+      authPrincipal: {
+        skippable: true,
+        description,
+        target,
+        chainInfo,
+        targetType,
+        supervised,
+      },
+    });
+  }
+
+  // Whether we can skip the authPrincipal step safely
+  const canSkipConnect = defaultSteps[0] && defaultSteps[0].authPrincipal && defaultSteps[0].authPrincipal.skippable;
+
+  const createExtraParams = (locale, params, extra = {}) => {
+    const finalParams = { ...params, ...(extra || {}) };
+    return {
+      locale,
+      action,
+      ...Object.keys(finalParams)
+        .filter((x) => !['userDid', 'userInfo', 'userSession', 'appSession', 'userPk', 'token'].includes(x))
+        .reduce((obj, x) => {
+          obj[x] = finalParams[x];
+          return obj;
+        }, {}),
+    };
+  };
+
+  const createSessionUpdater =
+    (token, params) =>
+    // eslint-disable-next-line require-await
+    async (key, value, secure = false) => {
+      const getUpdate = (k, v) => {
+        if (secure && params[encKey]) {
+          const encrypted = SealedBox.seal(Buffer.from(stringify(v)), decodeEncKey(params[encKey]));
+          return { [k]: Buffer.from(encrypted).toString('base64') };
+        }
+
+        return { [k]: v };
+      };
+
+      // If key is an object, update multiple keys
+      if (typeof key === 'object') {
+        secure = value; // eslint-disable-line no-param-reassign
+        const keys = Object.keys(key);
+        const updates = Object.assign(...keys.map((k) => getUpdate(k, key[k])));
+        return tokenStorage.update(token, updates);
+      }
+
+      return tokenStorage.update(token, omit(getUpdate(key, value), PROTECTED_KEYS));
+    };
+
+  // used for multi-factor authentication
+  const createMfaCodeGenerator = (token) => async () => {
+    const mfaCode = random(10, 99);
+    await tokenStorage.update(token, { mfaCode });
+    return mfaCode;
+  };
+
+  const onProcessError = ({ req, res, stage, err }) => {
+    const { token, store } = req.context || {};
+    if (token) {
+      tokenStorage.update(token, { status: SESSION_STATUS.ERROR, error: err.message, mfaCode: 0 });
+    }
+
+    res.jsonp({ error: err.message });
+    onError({ token, extraParams: get(store, 'extraParams', {}), stage, err });
+  };
+
+  const preparePathname = (str, req) => {
+    const auto = _preparePathname(str, req);
+    const custom = pathTransformer(auto);
+    // console.log('preparePathname', { str, auto, custom });
+    return custom;
+  };
+
+  // For web app
+  const generateSession = async (req, res) => {
+    try {
+      const params = {
+        'x-real-port': req.get('x-real-port'),
+        'x-real-protocol': req.get('x-real-protocol'),
+        deviceDid: req.get('x-device-did'),
+        connectedDid: get(req, 'cookies.connected_did', ''),
+        connectedPk: get(req, 'cookies.connected_pk', ''),
+        ...req.body,
+        ...req.query,
+        ...req.params,
+      };
+
+      // force to connected user if we are during a session, and this behavior is customizable
+      params.forceConnected = isConnectedOnly(params, req.get('x-user-did'));
+
+      const token = sha3(getSessionId({ req, action, pathname })).replace(/^0x/, '').slice(0, 8);
+      await tokenStorage.create(token, SESSION_STATUS.CREATED);
+
+      // These fields are used to track the source session
+      // - sourceToken is the token of previous session
+      // - destToken is the token of final target session
+      let sourceToken = params.sourceToken || '';
+      const sourceTokenState = sourceToken ? await tokenStorage.read(sourceToken) : null;
+      if (sourceTokenState) {
+        if ([SESSION_STATUS.SUCCEED].includes(sourceTokenState.status)) {
+          sourceToken = '';
+        } else {
+          await tokenStorage.update(sourceToken, { destToken: token });
+        }
+      }
+
+      const finalPath = preparePathname(getPathName(pathname, req), req);
+      const baseUrl = prepareBaseUrl(req, params);
+      const uri = await authenticator.uri({ token, pathname: finalPath, baseUrl, query: {} });
+
+      // Always set currentStep to 0 when generate a new token
+      // Since the did of logged in user may be different of the auth did
+      const challenge = getStepChallenge();
+      const didwallet = parseWalletUA(req.query['user-agent'] || req.headers['user-agent']);
+      const extraParams = createExtraParams(getLocale(req), params);
+      const hookParams = {
+        req,
+        request: req,
+        challenge,
+        baseUrl,
+        deepLink: uri,
+        extraParams,
+        updateSession: createSessionUpdater(token, extraParams),
+        didwallet,
+      };
+
+      const [wallet, delegator] = await Promise.all([
+        authenticator.getWalletInfo({ baseUrl, request: req, extraParams }),
+        authenticator.getDelegator({ baseUrl, request: req, extraParams }),
+      ]);
+      const [appInfo, memberAppInfo] = await Promise.all([
+        authenticator.getAppInfo({ baseUrl, request: req, wallet, delegator, extraParams }, 'appInfo'),
+        authenticator.getAppInfo({ baseUrl, request: req, wallet, delegator, extraParams }, 'memberAppInfo'),
+      ]);
+      await tokenStorage.update(token, {
+        currentStep: 0,
+        mfaSupported: !didwallet.os, // If we are mobile (both webview and mobile browsers , os is truthy), mfa should be disabled
+        challenge,
+        sharedKey: getStepChallenge(), // used for wallet to encrypt userInfo
+        extraParams: params,
+        appInfo,
+        memberAppInfo,
+        sourceToken,
+      });
+      // debug('generate token', { action, pathname, token });
+
+      // The data returned by onStart will be set to extra of response data
+      //   {String} extra.connectedDid：The server will notify the connectedDid in wallet to automatically connect (no code scanning is required) (notification is unreliable)
+      //   {Boolean} extra.saveConnect: The server tells the app web side to remember the connect session did after the connect is complete
+      const extra = await onStart(hookParams);
+
+      res.jsonp({ token, status: SESSION_STATUS.CREATED, url: uri, appInfo, memberAppInfo, extra: extra || {} });
+    } catch (err) {
+      onProcessError({ req, res, stage: 'generate-token', err });
+    }
+  };
+
+  // For web app
+  const checkSession = async (req, res) => {
+    try {
+      const { locale, token, store, params } = req.context;
+      if (!token) {
+        res.status(400).json({ error: errors.tokenMissing[locale] });
+        return;
+      }
+      if (!store) {
+        res.status(400).json({ error: errors.token404[locale] });
+        return;
+      }
+
+      if (store.status === SESSION_STATUS.FORBIDDEN) {
+        res.status(403).json({ error: errors.didMismatch[locale] });
+        return;
+      }
+
+      if (store.status === SESSION_STATUS.SUCCEED) {
+        setTimeout(() => {
+          tokenStorage.delete(token).catch(console.error);
+        }, cleanupDelay);
+        const extraParams = createExtraParams(locale, params, get(store, 'extraParams', {}));
+        await onComplete({
+          req,
+          request: req,
+          userDid: store.did,
+          userPk: store.pk,
+          extraParams,
+          updateSession: createSessionUpdater(token, extraParams),
+        });
+      }
+
+      res.status(200).json(
+        Object.keys(store)
+          .filter((x) => PROTECTED_KEYS.includes(x) === false)
+          .reduce((acc, key) => {
+            acc[key] = store[key];
+            return acc;
+          }, {})
+      );
+    } catch (err) {
+      onProcessError({ req, res, stage: 'check-token-status', err });
+    }
+  };
+
+  // For web app
+  const expireSession = async (req, res) => {
+    try {
+      const { locale, token, store } = req.context;
+      if (!token) {
+        res.status(400).json({ error: errors.tokenMissing[locale] });
+        return;
+      }
+      if (!store) {
+        res.status(400).json({ error: errors.token404[locale] });
+        return;
+      }
+
+      onExpire({ token, extraParams: get(store, 'extraParams', {}), status: 'expired' });
+
+      // We do not delete tokens that are scanned by wallet since it will cause confusing
+      if (store.status !== SESSION_STATUS.SCANNED) {
+        await tokenStorage.delete(token);
+      }
+      res.status(200).json({ token });
+    } catch (err) {
+      onProcessError({ req, res, stage: 'mark-token-timeout', err });
+    }
+  };
+
+  // Only check userDid and userPk if we have done auth principal
+  const checkUser = async ({ context, userDid, userPk }) => {
+    const { locale, token, store } = context;
+    const isConnected = store.currentStep > 0;
+
+    // Only check userDid and userPk if we have done auth principal
+    if (isConnected) {
+      if (!userDid) {
+        return errors.didMissing[locale];
+      }
+      if (!userPk) {
+        return errors.pkMissing[locale];
+      }
+
+      // check userDid mismatch
+      if (userDid !== store.did) {
+        await tokenStorage.update(token, { status: SESSION_STATUS.FORBIDDEN });
+        return errors.didMismatch[locale];
+      }
+    }
+
+    return false;
+  };
+
+  // eslint-disable-next-line consistent-return
+  const onAuthRequest = async (req, res) => {
+    const { locale, token, store, params, didwallet } = req.context;
+    const extraParams = createExtraParams(locale, params, get(store, 'extraParams', {}));
+    const userDid = params.userDid || store.did || extraParams.connectedDid;
+    const userPk = params.userPk || store.pk || extraParams.connectedPk;
+
+    const error = await checkUser({ context: req.context, userDid, userPk });
+    if (error) {
+      return res.jsonp({ error });
+    }
+
+    if (params[versionKey] && store.clientVersion !== params[versionKey]) {
+      store.clientVersion = params[versionKey];
+      store.encryptionKey = params[encKey];
+      await tokenStorage.update(token, { clientVersion: params[versionKey], encryptionKey: params[encKey] });
+    }
+
+    try {
+      const steps = [...cloneDeep(defaultSteps)];
+      const shouldSkipConnect = canSkipConnect && !!extraParams.connectedDid;
+      if (shouldSkipConnect) {
+        set(steps, '[0].authPrincipal.supervised', false);
+      }
+      if (extraParams.forceConnected) {
+        let target = extraParams.connectedDid;
+        if (typeof extraParams.forceConnected === 'string' && isValidDid(extraParams.forceConnected)) {
+          target = extraParams.forceConnected;
+        }
+        if (isValidDid(target)) {
+          set(steps, '[0].authPrincipal.target', target);
+        }
+      }
+
+      if (store.status !== SESSION_STATUS.SCANNED) {
+        await tokenStorage.update(token, { status: SESSION_STATUS.SCANNED, connectedWallet: didwallet });
+      }
+
+      // Since we can not store dynamic claims anywhere, we should calculate it on the fly
+      if (store.dynamic || shouldSkipConnect) {
+        const newClaims = await onConnect({
+          req,
+          request: req,
+          userDid,
+          userPk,
+          didwallet,
+          challenge: store.challenge,
+          pathname: preparePathname(getPathName(pathname, req), req),
+          baseUrl: prepareBaseUrl(req, extraParams),
+          extraParams,
+          updateSession: createSessionUpdater(token, extraParams),
+        });
+        if (newClaims) {
+          if (Array.isArray(newClaims)) {
+            steps.push(...newClaims);
+          } else {
+            steps.push(newClaims);
+          }
+        }
+      }
+
+      const signParams = await getSignParams(req);
+      const signedClaim = await authenticator.sign(
+        Object.assign(signParams, {
+          context: {
+            token,
+            userDid,
+            userPk,
+            didwallet,
+            ...pick(store, ['currentStep', 'sharedKey', 'encryptionKey']),
+            mfaCode: store.mfaSupported ? createMfaCodeGenerator(token) : undefined,
+          },
+          claims: steps[store.currentStep],
+          pathname: preparePathname(getPathName(pathname, req), req),
+          baseUrl: prepareBaseUrl(req, extraParams),
+          extraParams,
+          challenge: store.challenge,
+          appInfo: store.appInfo,
+          memberAppInfo: store.memberAppInfo,
+          request: req,
+        })
+      );
+
+      res.jsonp(encrypt(signedClaim, store));
+    } catch (err) {
+      onProcessError({ req, res, stage: 'send-auth-claim', err });
+    }
+  };
+
+  // eslint-disable-next-line consistent-return
+  const onAuthResponse = async (req, res) => {
+    const { locale, token, store, params, didwallet } = req.context;
+
+    try {
+      const {
+        userDid,
+        userPk,
+        action: userAction,
+        challenge: userChallenge,
+        claims: claimResponse,
+        timestamp,
+      } = await authenticator.verify(decrypt(params, store), locale);
+      // debug('onAuthResponse.verify', { userDid, token, claims: claimResponse });
+
+      if (!store.did || !store.pk) {
+        await tokenStorage.update(token, { did: userDid, pk: userPk });
+      }
+
+      const extraParams = createExtraParams(locale, params, get(store, 'extraParams', {}));
+      const cbParams = {
+        step: store.currentStep,
+        req,
+        request: req,
+        userDid,
+        userPk,
+        challenge: store.challenge,
+        didwallet,
+        claims: claimResponse,
+        baseUrl: prepareBaseUrl(req, extraParams),
+        extraParams,
+        updateSession: createSessionUpdater(token, extraParams),
+        timestamp,
+      };
+
+      const steps = [...defaultSteps];
+      const shouldSkipConnect = canSkipConnect && !!extraParams.connectedDid;
+
+      // Since we can not store dynamic claims anywhere, we should calculate it on the fly
+      if (store.dynamic || shouldSkipConnect) {
+        const newClaims = await onConnect(cbParams);
+        if (newClaims) {
+          if (Array.isArray(newClaims)) {
+            steps.push(...newClaims);
+          } else {
+            steps.push(newClaims);
+          }
+        }
+      } else if (persistentDynamicClaims && Array.isArray(store.dynamicClaims)) {
+        steps.push(...store.dynamicClaims);
+      }
+
+      // Ensure user approval
+      if (userAction === 'declineAuth') {
+        await tokenStorage.update(token, {
+          status: SESSION_STATUS.ERROR,
+          error: errors.userDeclined[locale],
+          mfaCode: 0,
+          currentStep: steps.length - 1,
+        });
+
+        const result = await onDecline(cbParams);
+        return res.jsonp({ ...(result || {}) });
+      }
+
+      if (userAction === 'busy') {
+        await tokenStorage.update(token, {
+          status: SESSION_STATUS.BUSY,
+          error: errors.userBusy[locale],
+          mfaCode: 0,
+          currentStep: steps.length - 1,
+        });
+
+        return res.jsonp({});
+      }
+
+      // Since only 1 MFA is allowed when multiple claims is requested, we just need to check the first one
+      if (store.mfaCode && !claimResponse.some((x) => isEqual(x.mfaCode, [store.mfaCode]))) {
+        return onProcessError({ req, res, stage: 'verify-mfa-code', err: new Error(errors.mfaMismatch[locale]) });
+      }
+
+      // Ensure JWT challenge match
+      if (!userChallenge) {
+        return res.jsonp({ error: errors.challengeMismatch[locale] });
+      }
+      if (userChallenge !== store.challenge) {
+        return res.jsonp({ error: errors.challengeMismatch[locale] });
+      }
+
+      // Ensure userDid match between authPrincipal and later process
+      const error = await checkUser({ context: req.context, userDid, userPk });
+      if (error) {
+        return res.jsonp({ error });
+      }
+
+      const isConnected = store.currentStep > 0;
+      if (isConnected === false) {
+        // Some permission check login can be done here
+        // Error thrown from this callback will terminate the process
+        const newClaims = await onConnect(cbParams);
+        if (newClaims) {
+          await tokenStorage.update(token, {
+            dynamic: !persistentDynamicClaims,
+            dynamicClaims: persistentDynamicClaims ? newClaims : undefined,
+          });
+          if (Array.isArray(newClaims)) {
+            steps.push(...newClaims);
+          } else {
+            steps.push(newClaims);
+          }
+        }
+      }
+
+      const onLastStep = async (result) => {
+        let nextWorkflow = isUrl(extraParams.nw) ? extraParams.nw : '';
+        if (nextWorkflow && result && result.nextWorkflowData) {
+          if (isPlainObject(result.nextWorkflowData) === false) {
+            const err = new Error(`expect nextWorkflowData should be a plain object, got: ${result.nextWorkflowData}`);
+            return onProcessError({ req, res, stage: 'validate-next-workflow-data', err });
+          }
+
+          const tmp = new URL(nextWorkflow);
+          const merged = Object.assign(extraParams.previousWorkflowData || {}, result.nextWorkflowData);
+          const previousWorkflowData = toBase64(JSON.stringify(merged));
+          // For max url length please refer to discussion at https://stackoverflow.com/a/417184/686854
+          if (previousWorkflowData.length > 8192) {
+            const err = new Error('base64 encoded nextWorkflowData should be less than 8192 characters');
+            return onProcessError({ req, res, stage: 'append-next-workflow', err });
+          }
+
+          if (isDeepLink(nextWorkflow)) {
+            const actualUrl = decodeURIComponent(tmp.searchParams.get('url'));
+            const obj = new URL(actualUrl);
+            obj.searchParams.set('previousWorkflowData', previousWorkflowData);
+            tmp.searchParams.set('url', obj.href);
+          } else {
+            tmp.searchParams.set('previousWorkflowData', previousWorkflowData);
+          }
+
+          nextWorkflow = tmp.href;
+        }
+
+        const updates = {};
+
+        // If we have nextWorkflow, return it to browser
+        let actualNw = nextWorkflow || result?.nextWorkflow || '';
+        if (actualNw) {
+          if (isDeepLink(actualNw)) {
+            actualNw = new URL(actualNw).searchParams.get('url');
+          }
+          if (actualNw) {
+            updates.nextWorkflow = decodeURIComponent(actualNw);
+          }
+        }
+
+        // If we have nextWorkflow, do not mark current session as complete
+        // Instead, save the relationship between the two
+        // Then, mark both session as complete on nextWorkflow complete
+        // In theory, we can use this mechanism to concat infinite sessions
+        if (result && result.nextToken && result.nextWorkflow) {
+          try {
+            await tokenStorage.update(result.nextToken, { prevToken: token });
+          } catch (err) {
+            console.error('DIDAuth: failed to to update nextToken', err);
+            updates.status = SESSION_STATUS.SUCCEED;
+          }
+        } else {
+          if (store.prevToken) {
+            try {
+              await tokenStorage.update(store.prevToken, { status: SESSION_STATUS.SUCCEED });
+            } catch (err) {
+              console.error('DIDAuth: failed to to update prevToken', err);
+            }
+          }
+          updates.status = SESSION_STATUS.SUCCEED;
+        }
+
+        await tokenStorage.update(token, updates);
+        return res.jsonp({ ...Object.assign({ nextWorkflow }, result || {}) });
+      };
+
+      // If we are only requesting the authPrincipal claim
+      // We make such assertion here, because the onConnect callback can modify the steps
+      if (steps.length === 1) {
+        const result = await onAuth(cbParams);
+        return onLastStep(result);
+      }
+
+      // If we got requestedClaims other than the authPrincipal
+      if (isConnected && store.currentStep < steps.length) {
+        // Call onAuth on each step, since we do not hold all results until complete
+        const result = await onAuth(cbParams);
+
+        // Only return if we are walked through all steps
+        const isLastStep = store.currentStep === steps.length - 1;
+        if (isLastStep) {
+          return onLastStep(result);
+        }
+      }
+
+      // Move to next step: nextStep is persisted here to avoid an memory storage error
+      const nextStep = store.currentStep + 1;
+      const nextChallenge = getStepChallenge();
+      await tokenStorage.update(token, { currentStep: nextStep, challenge: nextChallenge, mfaCode: 0 });
+      const signParams = await getSignParams(req);
+
+      try {
+        const nextSignedClaim = await authenticator.sign(
+          Object.assign(signParams, {
+            context: {
+              token,
+              userDid,
+              userPk,
+              didwallet,
+              ...pick(store, ['currentStep', 'sharedKey', 'encryptionKey']),
+              mfaCode: store.mfaSupported ? createMfaCodeGenerator(token) : undefined,
+            },
+            claims: steps[nextStep],
+            pathname: preparePathname(getPathName(pathname, req), req),
+            baseUrl: prepareBaseUrl(req, extraParams),
+            extraParams,
+            challenge: nextChallenge,
+            appInfo: store.appInfo,
+            memberAppInfo: store.memberAppInfo,
+            request: req,
+          })
+        );
+        return res.jsonp(encrypt(nextSignedClaim, store));
+      } catch (err) {
+        return onProcessError({ req, res, stage: 'next-auth-claim', err });
+      }
+    } catch (err) {
+      onProcessError({ req, res, stage: 'verify-auth-claim', err });
+    }
+  };
+
+  const ensureContext = async (req, res, next) => {
+    const didwallet = parseWalletUA(req.query['user-agent'] || req.headers['user-agent']);
+    const params = { ...req.body, ...req.query, ...req.params };
+    const token = params[tokenKey];
+    const locale = getLocale(req);
+
+    let store = null;
+    if (token) {
+      store = await tokenStorage.read(token);
+      if (params.previousWorkflowData) {
+        try {
+          store.extraParams.previousWorkflowData = JSON.parse(fromBase64(params.previousWorkflowData));
+          await tokenStorage.update(token, { extraParams: store.extraParams });
+        } catch (e) {
+          console.warn('Could not parse previousWorkflowData', params.previousWorkflowData, e);
+        }
+      }
+      if (store?.destToken && typeof params.notrace === 'undefined') {
+        const result = await tokenStorage.read(store.destToken);
+        if (result) {
+          store = result;
+        }
+      }
+    }
+
+    req.context = { locale, token, didwallet, params, store };
+    return next();
+  };
+
+  const ensureSignedJson = (req, res, next) => {
+    if (req.ensureSignedJson === undefined) {
+      req.ensureSignedJson = true;
+      const originJsonp = res.jsonp;
+      res.jsonp = async (payload) => {
+        if (payload.appPk && payload.authInfo) {
+          return originJsonp.call(res, payload);
+        }
+
+        const data = payload.response ? { response: payload.response } : { response: payload };
+        const fields = ['error', 'errorMessage', 'successMessage', 'nextWorkflow', 'nextUrl', 'cookies', 'storages'];
+
+        // Attach protocol fields to the root
+        fields.forEach((x) => {
+          if (payload[x]) {
+            data[x] = payload[x];
+          }
+        });
+        data.errorMessage = data.error || data.errorMessage || '';
+
+        // Remove protocol fields from the response
+        if (typeof data.response === 'object') {
+          data.response = omit(data.response, fields);
+        }
+
+        const params = { ...req.body, ...req.query, ...req.params };
+        const token = params[tokenKey];
+        const store = token ? await tokenStorage.read(token) : null;
+
+        const extraParams = get(store, 'extraParams', {});
+        const signedData = await authenticator.signResponse(data, prepareBaseUrl(req, extraParams), req, extraParams);
+        // debug('ensureSignedJson.do', signed);
+        originJsonp.call(res, encrypt(signedData, store));
+      };
+    }
+
+    const { token, store, locale } = req.context;
+    if (!token || !store) {
+      return res.jsonp({ error: errors.token404[locale] });
+    }
+
+    next();
+  };
+
+  return {
+    generateSession,
+    expireSession,
+    checkSession,
+    onAuthRequest,
+    onAuthResponse,
+    ensureContext,
+    ensureSignedJson,
+    createExtraParams,
+  };
+};
+
+module.exports.isDeepLink = isDeepLink;
+module.exports.isConnectedOnly = isConnectedOnly;
+module.exports.parseWalletUA = parseWalletUA;
+module.exports.preparePathname = _preparePathname;
+module.exports.prepareBaseUrl = prepareBaseUrl;
+module.exports.getStepChallenge = getStepChallenge;