Wondering what’s next for npm?Check out our public roadmap! »

    @teamhanko/hanko-webauthn
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    @teamhanko/hanko-webauthn

    @teamhanko/hanko-webauthn is a client-side Javascript library that serves as a wrapper for the WebAuthn API by encoding binary data using base64url (also known as "websafe" or "urlsafe" base64).

    The WebAuthn API itself takes input and output values that look almost like JSON, except that binary data is represented as ArrayBuffers. Using hanko-webauthn allows the data to be sent from/to the server as normal JSON without any custom client-side processing.

    Installation

    NPM/Yarn

    # Using npm
    npm install --save @teamhanko/hanko-webauthn
    
    # Using yarn
    yarn add @teamhanko/hanko-webauthn

    CDN

    Alternatively, you can load the library via CDN using a script tag in your application <head>:

    <script src="https://cdn.jsdelivr.net/npm/@teamhanko/hanko-webauthn@latest/dist/browser-global/hanko-webauthn.browser-global.js"></script>

    When using this method a browser global hankoWebAuthn will be set.

    // destructure global
    const { create: createCredentials, get: getCredentials } = hankoWebAuthn;
    
    // using the global directly
    hankoWebAuthn.create();

    Usage

    The following are simple examples for performing registration and authentication using the SDK . For more information, refer to the Hanko API implementation guide.

    Registration

    import {create as createCredential} from "@teamhanko/hanko-webauthn"
    
    // register credential for a given userName, which typically would be read from
    // a registration form
    async function register(userName) {
      try {
        const credentialCreationOptions = await initializeRegistration(userName);
        const webAuthnResponse = await createCredential(credentialCreationOptions);
        return await finalizeRegistration(webAuthnResponse)
      } catch (error) {
        // handle error
      }
    }
    
    // retrieve credential creation options to pass to the WebAuthn API
    async function initializeRegistration(userName) {
      // adjust fetch URL to backend handler for retrieving 
      // credential creation options from FIDO server
      const response = await fetch(`/webauthn/registration/initialize?user_name=${userName}`);
    
      if (!response.ok) {
        // handle fetch error
      }
    
      return response.json();
    }
    
    // verify WebAuthn response
    async function finalizeRegistration(webAuthnResponse) {
      // adjust fetch URL to backend handler for verifying 
      // WebAuthn response with FIDO server
      const response = await fetch('/webauthn/registration/finalize', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(webAuthnResponse)
      });
    
      if (!response.ok) {
        // handle fetch error
      }
    
      return response.json();
    }

    Authentication

    import {get as getCredential} from "@teamhanko/hanko-webauthn"
    
    // authenticate with a credential for a given userName, which typically would be read from
    // a login form
    async function authenticate(userName) {
      try {
        const credentialRequestOptions = await initializeAuthentication(userName);
        const credential = await getCredential(credentialRequestOptions);
        return await finalizeAuthentication(credential)
      } catch (error) {
        // handle error
      }
    }
    
    // retrieve credential request options to pass to the WebAuthn API
    async function initializeAuthentication(userName) {
      // adjust fetch URL to backend handler for retrieving 
      // credential request options from FIDO server
      const response = await fetch(`/webauthn/authentication/initialize?user_name=${userName}`);
    
      if (!response.ok) {
        // handle fetch error
      }
    
      return response.json()
    }
    
    // verify WebAuthn response
    async function finalizeAuthentication(webAuthnResponse) {
      // adjust fetch URL to backend handler for verifying 
      // WebAuthn response with FIDO server
      const response = await fetch("/webauthn/authentication/finalize", {
        method: 'POST',
        headers: {'Content-Type': 'application/json'}, 
        body: JSON.stringify(webAuthnResponse)
      });
    
      if (!response.ok) {
        // handle fetch error
      }
    
      return response.json();
    }

    API

    function create(requestJSON: CredentialCreationOptionsJSON): Promise<PublicKeyCredentialWithAttestationJSON>;
    function get(requestJSON: CredentialRequestOptionsJSON): Promise<PublicKeyCredentialWithAssertionJSON>;
    function supported(): boolean;
    function isUserVerifyingPlatformAuthenticatorAvailable: Promise<boolean>;
    function isSecurityKeySupported(): Promise<boolean>;

    Acknowledgements

    @teamhanko/hanko-webauthn is a fork of the @github/webauthn-json library.

    Install

    npm i @teamhanko/hanko-webauthn

    DownloadsWeekly Downloads

    45

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    732 kB

    Total Files

    43

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar