UAuth JS Library

The @uauth/js library is the core UAuth library for single-page applications. It manages login sessions with the Uauth Service and provides a login popup flow built with React.

Client

The Client class is the default export for the @uauth/js package.

constructor

constructor(options: ClientOptions)

const uauth = new Client(options);

login()

Initiates UAuth authentication with an auth server redirect and callback flow. When using this method, the redirectUri in the ClientOptions must point to a page that calls loginCallback().

async login(
    options: Partial<LoginOptions> = {}
): Promise<void>

loginWithPopUp()

Initiates UAuth authentication with a React popup flow.

async loginWithPopup(
    options: Partial<Omit<LoginOptions, 'responseMode'>> = {},
    config?: PopupConfig,
): Promise<Authorization>

loginCallback()

Parses the authorization code and application state after login() has been called and the authorization server has redirected back to the redirectUri defined in the ClientOptions.

async loginCallback<T>(
    options?: Partial<LoginCallbackOptions>,
): Promise<LoginCallbackResponse<T>>

authorization()

Returns the Authorization for the current login session.

async authorization(
    options: AuthorizationOptions = {},
): Promise<Authorization>

user()

Returns the UserInfo associated with the current UAuth instance.

async user(options: UserOptions = {}): Promise<UserInfo>

getVerifiedAccounts()

Returns VerifiedAddress array containing all verified accounts associated with an authorized domain, with optional symbol filtering, which allows a DApp to request only the verified accounts they are interested in.

getVerifiedAccounts(
  authorization: Authorization,
  symbols: string[] = []
): VerifiedAddress[]

getAuthorizationAccount

The UAuth service allows users to login with certain verified accounts associated with a domain's ud.me profile in addition to the Ethereum or Polygon wallet that owns the domain. This method takes an Authorization from loginWithPopup() or loginCallback() and returns a VerifiedAddress describing the account that authorized a login request, such as a verified Solana wallet.

getAuthorizationAccount(
    authorization: Authorization,
    type = 'sig',
    version = 'v1'
): VerifiedAddress | undefined

logout()

Executes the beforeRedirect callback if defined in LogoutOptions, deletes the session authorization from the local clientstore, and redirects to the postLogoutRedirectUri.

async logout({
    clientID,
    username,
    scope,
    resource,
    ...options
}: Partial<LogoutOptions> = {}): Promise<void>

ClientOptions

The options object passed to the Client constructor.

export interface ClientOptions {
  // Fallback Login Options
  clientID: string
  clientSecret?: string
  redirectUri: string
  clientAuthMethod?: ClientAuthMethod
  resource?: string
  responseMode?: ResponseMode
  scope?: string
  prompt?: string
  maxAge?: number

  // Fallback Logout Options
  rpInitiatedLogout?: boolean
  postLogoutRedirectUri?: string

  // Cache Options
  cacheOptions?: CacheOptions

  // Other Options
  window?: Window | undefined
  fallbackIssuer?: string
  storeType?: StoreType
  store?: Store
  createIpfsUrl?: (cid: string, path: string) => string
  resolution?: DomainResolver
}

LoginOptions

The options object passed to login() and loginWithPopup().

interface LoginOptions {
  clientID: string
  clientSecret?: string
  clientAuthMethod: ClientAuthMethod
  maxAge: number
  prompt: string
  resource?: string
  redirectUri: string
  responseMode: ResponseMode
  scope: string
  flowId?: 'login' | 'signup'
  packageName?: string
  packageVersion?: string

  username?: string
  state?: any
  beforeRedirect?(url: string): Promise<void> | void
}

Authorization

The login authorization returned by loginWithPopup() and loginCallback().

interface Authorization {
  accessToken: string
  expiresAt: number
  idToken: IdToken
  scope: string
  resource?: string
}

AuthorizationOptions

interface AuthorizationOptions {
  clientID?: string
  username?: string
  scope?: string
  resource?: string
}

UserOptions

The options object passed to user().

interface UserOptions extends AuthorizationOptions {
  claims?: string[]
}

BaseLogoutOptions

interface BaseLogoutOptions {
  rpInitiatedLogout: boolean
  postLogoutRedirectUri?: string
}

LogoutOptions

The options object passed to logout(). Extends BaseLogoutOptions and AuthorizationOptions.

interface LogoutOptions {
  state?: any
  beforeRedirect?(url: string): Promise<void> | void
}

LoginCallbackOptions

The options object passed to loginCallback().

interface LoginCallbackOptions {
  url?: string
}

LoginCallbackResponse

The object returned by loginCallback().

interface LoginCallbackResponse<T> {
  authorization: Authorization
  state?: T
}

UserInfo

The object returned by user(). Equivalent to the response of the UserInfo endpoint of the UAuth server. Contains the claims requested by the current authorization session, based on the values defined in the ClientOptions.scope field. See Scopes for Login for more information about supported login scopes.

interface UserInfo {
// Partial<WalletClaims>
  wallet_address: string
  wallet_type_hint: WalletType
  eip4361_message: string
  eip4361_signature: string

// Partial<EmailClaims>
  email: string
  email_verified: boolean

// Partial<AddressClaims>
  address: AddressClaim

// Partial<PhoneClaims>
  phone_number: string
  phone_number_verified: boolean

// Partial<ProfileClaims>
  name: string
  given_name: string
  family_name: string
  middle_name: string
  nickname: string
  preferred_username: string
  profile: string
  picture: string
  website: string
  gender: string
  birthdate: string
  zoneinfo: string
  locale: string
  updated_at: string

// Partial<HumanityCheckClaims> { sub: string }
  humanity_check_id: string
}

VerifiedAddress

Defines a verified address associated with an authorized domain. Returned by getVerifiedAccounts() and getAuthorizationAccount().

interface VerifiedAddress {
  address: string
  message: string
  signature: string
  symbol: string
}