hanko-frontend-sdk

This package utilizes the Hanko API to provide functionality that allows an easier UI integration. It is meant for use in browsers only.

Installation

# npm
npm install @teamhanko/hanko-frontend-sdk

# yarn
yarn add @teamhanko/hanko-frontend-sdk

# pnpm
pnpm install @teamhanko/hanko-frontend-sdk

Usage

Import as a module:

import { Hanko } from "@teamhanko/hanko-frontend-sdk"

const hanko = new Hanko("http://localhost:3000")

With a script tag via CDN:

<script src="https://cdn.jsdelivr.net/npm/@teamhanko/hanko-frontend-sdk/dist/sdk.umd.js"></script>

<script>
    const hanko = new hankoFrontendSdk.Hanko("http://localhost:3000")
    ...
</script>

Documentation

To see the latest documentation, please click here.

Exports

SDK

• Hanko - A class that bundles all functionalities.

Clients

• ConfigClient - A class to fetch configurations.
• UserClient - A class to manage users.
• WebauthnClient - A class to handle WebAuthn-related functionalities.
• PasswordClient - A class to manage passwords and password logins.
• PasscodeClient - A class to handle passcode logins.

Utilities

• WebauthnSupport - A class to check the browser's WebAuthn support.

DTOs

• Config
• PasswordConfig
• WebauthnFinalized
• Credential
• UserInfo
• User
• Email
• Emails
• Passcode

Errors

• HankoError
• TechnicalError
• ConflictError
• RequestTimeoutError
• WebauthnRequestCancelledError
• InvalidPasswordError
• InvalidPasscodeError
• InvalidWebauthnCredentialError
• PasscodeExpiredError
• MaxNumOfPasscodeAttemptsReachedError
• NotFoundError
• TooManyRequestsError
• UnauthorizedError

Examples

Get the current user / Validate the JWT against the Hanko API

The Hanko API issues a JWT when a user logs in. For certain actions, like obtaining the user object, a valid JWT is required. The following example shows how to get the user object of the current user, or to identify that the user is not logged in:

import { Hanko, UnauthorizedError } from "@teamhanko/hanko-frontend-sdk"

const hanko = new Hanko("http://localhost:3000")

try {
    const user = await hanko.user.getCurrent()

    // A valid JWT is in place so that the user object was able to be fetched.
} catch (e) {
    if (e instanceof UnauthorizedError) {
        // Display an error or prompt the user to login again. After a successful call to `hanko.webauthn.login()`,
        // `hanko.password.login()` or `hanko.passcode.finalize()` a JWT will be issued and `hanko.user.getCurrent()`
        // would succeed.
    }
}

Register a WebAuthn credential

There are a number of situations where you may want the user to register a WebAuthn credential. For example, after user creation, when a user logs in to a new browser/device, or to take advantage of the "caBLE" support and pair a smartphone with a desktop computer:

import { Hanko, UnauthorizedError, WebauthnRequestCancelledError } from "@teamhanko/hanko-frontend-sdk"

const hanko = new Hanko("http://localhost:3000")

// By passing the user object (see example above) to `hanko.webauthn.shouldRegister(user)` you get an indication of
// whether a WebAuthn credential registration should be performed on the current browser. This is useful if the user has
// logged in using a method other than WebAuthn, and you then want to display a UI that allows the user to register a
// credential when possibly none exists.

try {
    // Will cause the browser to present a dialog with various options depending on the WebAuthn implemention.
    await hanko.webauthn.register()

    // Credential has been registered.
} catch(e) {
    if (e instanceof WebauthnRequestCancelledError) {
        // The WebAuthn API failed. Usually in this case the user cancelled the WebAuthn dialog.
    } else if (e instanceof UnauthorizedError) {
        // The user needs to login to perform this action.
    }
}

Bugs

Found a bug? Please report on our GitHub page.

License

The hanko-frontend-sdk project is licensed under the MIT License.