whodis-client

!ci_on_commit
!deploy_on_tag

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

---

Install

``sh
npm install --save whodis-client
`

Example

$3

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

`ts
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: 'hello@whodis.io', // 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.

$3

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.

`ts
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.

$3

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.

`ts
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.