whodis-client

A simple client for easy, typed interactions with the whodis.io api in clientside/insecure environments

Install

npm install --save whodis-client

Example

ask auth challenge

To ask a user to signup or login, you must ask them an authentication challenge.

import { askAuthChallenge, ChallengeGoal, ChallengeType, ContactMethodType } from 'whodis';

const { challengeUuid } = await askAuthChallenge({
  directoryUuid, // specify which directory you want to to challenge the user for (note: users only exist in the context of a specific directory)
  clientUuid, // specify which credential gives you access to this directory (note: this is a public key and can be used in the browser / insecure environments)
  goal: ChallengeGoal.SIGNUP, // alternatively, you could request a challenge with a goal of `LOGIN` if the account already exists
  type: ChallengeType.CONFIRMATION_CODE,
  contactMethod: {
    type: ContactMethodType.EMAIL, // alternatively, you could request a challenge to a contact method type of 'PHONE'
    address: '[email protected]', // an email address - or a phone number if contact method type = 'PHONE'
  },
});

In the example above, we sent this user a confirmation code challenge. The user will receive a message, ${5-digit-code} is your ${titleCase(namespace)} confirmation code., to the specified contact method.

answer auth challenge

Now that the challenge has been asked, the user can answer it in order to authenticate their ownership of that contact method and receive an AuthToken, a JSON Web Token (JWT) issued by whodis.io, in exchange.

import { answerAuthChallenge } from 'whodis-client';

const { token } = await answerAuthChallenge({
  challengeUuid, // the challengeUuid you got from askAuthChallenge,
  challengeAnswer: '12345', // the user's input, which should match the confirmation code they were sent in the message
});

This token can now be used with standard authentication libraries like simple-jwt-auth in order to authenticate and authorize access to apis. That library exposes methods by which you can easily getAuthedClaims and extract the userUuid from the token for downstream usage.

refresh token

The tokens generated by whodis have separate expiration dates for when they can be used for authentication and when they can be refreshed. If your user's token is expired, instead of forcing them to login again, you can first try to refresh their token.

import { isTokenExpired, isTokenRefreshable, refreshToken } from 'whodis-client';

if (isTokenExpired({ token }) && isTokenRefreshable({ token })) {
  const { token: refreshedToken } = await refreshToken({ token });
}

Note: this method will only make an api call to the whodis servers if the token is still refreshable.