@arcblock/did-auth/lib/index.d.ts

Helper function to setup DID authentication support on a node.js web server

// 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-auth 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;