authWithPopup

Open a JoyID app popup window to authenticate user.

Types

function authWithPopup (
  request: AuthRequest,
  config?: PopupConfigOptions
): Promise<AuthResponse>

interface AuthRequest {
  /**
   * The URL of your app that JoyID app should redirect to after authentication
   */
  redirectURL: string
  /**
   * name of your app
   */
  name?: string
  /**
   * logo of your app
   */
  logo?: string
  /**
   * The challenge that was requested to be signed
   */
  challenge?: string
  /**
   * Custom state that will be returned to your app after authentication
   */
  state?: any
}

interface AuthResponse {
  type: 'Auth'
  error?: string
  data?: AuthResponseData
}

interface AuthResponseData {
  // The CKB address of the authenticated user
  address: string
  // The Ethereum address of the authenticated user
  ethAddress: string
  // The public key of the authenticated user
  pubkey: string
  /**
   * The challenge that was requested to be signed
   */
  challenge?: string
  /**
   * The message that was signed by the authenticator,
   * Note that the message may not be the original raw message,
   * but is combined with client data and authenticator data
   * according to [WebAuthn Spec](https://www.w3.org/TR/webauthn-2/#sctn-op-get-assertion).
   */
  message?: string
  /**
   * The signature of the message that was signed by the authenticator
   */
  signature?: string
  /**
   * key type of the authenticated user
   */
  keyType: 'main_key' | 'sub_key' | 'main_session_key' | 'sub_session_key'
}

interface PopupConfigOptions {
  /**
   * Default is 300s
   */
  timeoutInSeconds?: number
}

Example

import { authWithPopup } from '@joyid/core'

async function joyidAuth() {
  const request = {
    redirectURL: 'https://example.com',
    title: 'Example App',
    logo: 'https://example.com/logo.png',
    challenge: 'Sign this message',
  }
  const res = await authWithPopup(request)
  if (res.error != null) {
    console.error(res.error)
  } else {
    // the user has authenticated,
    // do something with res.data, it's type safe!
  }
}

Details

The challenge of request is optional, when challenge is passed in, the JoyID App will ask the user to perform a biometric authentication to sign the challenge, and the corresponding signature will be returned after the user has confirmed the authentication. If challenge is not passed in, user will not be asked to perform biometric authentication, and the JoyID App will return the user's JoyID info immediately.

Please note that for security reasons you cannot fully specify the challenge you need to sign during authentication, for example you need to sign the challenge as:

Sign this message

What the user actually signs when signing is:

JoyID authorize prefix:
Sign this message
Edit this page on GitHub
Table of Contents