0.2.9 • Published 4 years ago

webauthn-components

Licence

ISC

Version

0.2.9

Deps

Size

79 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Web Components for the Web Authentication API

A collection of Web Components that make the Web Authentication API a little easier to use.

Installation

npm i webauthn-components

These components use CSS ::part to enable styling

^{Back to components list}

Used for connecting with a previously registered account

Usage

with default values

import "webauthn-components/login";

/* html */
<webauthn-login></webauthn-login>;

with custom values

import "webauthn-components/login";

/* html */
<webauthn-login label="Email" input-type="email" input-name="email"></webauthn-login>;

Properties

assertionStartUrl

Endpoint for retrieving details and challenge from the server

type: String
default: /api/assertion/start

assertionFinishUrl

Endpoint for completing the assertion process and sending the challenge result to the server

type: String
default: /api/assertion/finish

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

publicKeyCredentialRequestOptionsDecoder

PublicKeyCredentialRequestOptions decoding function (i.e. Base64URLString to ArrayBuffer)

type: Function
default: decodePublicKeyCredentialRequestOptions from utils/parse

loginCredentialEncoder

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

type: Function
default: encodeLoginCredential from utils/parse

buttonText

The text displayed on the login button

type: String
default: Login
reflected attribute: button-text

inputType

The type of input to use for the username

type: String
default: text (any valid HTML input type)
reflected attribute: input-type

inputName

The name of the input to use for the username

type: String
default: username
reflected attribute: input-name

label

Username label content

type: String
default: Username
reflected attribute: label

noUsername

Should login be done without a username

type: Boolean
default: false
reflected attribute: no-username

Events

Emitted when the login process starts (i.e. on form submit)

type: CustomEvent
detail: null

Emitted when retrieving the local credentials using navigator.credentials.get()

type: CustomEvent
detail: null

Emitted when the login process is completed succesfully

type: CustomEvent
detail: {...} (content returned by the assertionFinishUrl endpoint)

Emitted when the login process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-login::part(form) {...}

::part(label)

Exposes the label element for styling

webauthn-login::part(label) {...}

::part(input)

Exposes the input element for styling

webauthn-login::part(input) {...}

::part(button)

Exposes the button element for styling

webauthn-login::part(button) {...}

webauthn-registration

^{Back to components list}

Used for creating a new account

Usage

with default values

import "webauthn-components/registration";

/* html */
<webauthn-registration></webauthn-registration>;

with custom values

import "webauthn-components/registration";

/* html */
<webauthn-registration label="Email" input-type="email" input-name="email"></webauthn-registration>;

const registrationComponent = document.querySelector("webauthn-registration");
registrationComponent.fetchOptions = { ...registrationComponent.fetchOptions, cache: "no-cache" };

Properties

registrationStartUrl

Endpoint for retrieving initial details and challenge from the server

type: String
default: /api/registration/start

registrationFinishUrl

Endpoint for completing the registration process

type: String
default: /api/registration/finish

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

publicKeyCredentialCreateOptionsDecoder

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

type: Function
default: decodePublicKeyCredentialCreateOptions from utils/parse

registerCredentialEncoder

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

type: Function
default: encodeRegisterCredential from utils/parse

buttonText

The text displayed on the login button

type: String
default: Login
reflected attribute: button-text

inputType

The type of input to use for the username

type: String
default: text (any valid HTML input type)
reflected attribute: input-type

inputName

The name of the input to use for the username

type: String
default: username
reflected attribute: input-name

label

Username label content

type: String
default: Username
reflected attribute: label

noUsername

Should login be done without a username

type: Boolean
default: false
reflected attribute: no-username

Events

registration-started

Emitted when the registration process starts (i.e. on form submit)

type: CustomEvent
detail: null

registration-created

Emitted after creating the local credentials using navigator.credentials.create()

type: CustomEvent
detail: null

registration-finished

Emitted when the registration process is completed succesfully

type: CustomEvent
detail: {...} (content returned by the registrationFinishUrl endpoint)

registration-error

Emitted when the registration process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-registration::part(form) {...}

::part(label)

Exposes the label element for styling

webauthn-registration::part(label) {...}

::part(input)

Exposes the input element for styling

webauthn-registration::part(input) {...}

::part(button)

Exposes the button element for styling

webauthn-registration::part(button) {...}

webauthn-recovery

^{Back to components list}

Used for recovering access to an existing account

Usage

with default values

import "webauthn-components/recovery";

/* html */
<webauthn-recovery></webauthn-recovery>;

with custom values

import "webauthn-components/recovery";

/* html */
<webauthn-recovery label="Recovery code" input-type="number" input-name="code"></webauthn-recovery>;

const recoveryComponent = document.querySelector("webauthn-recovery");
recoveryComponent.fetchOptions = { ...recoveryComponent.fetchOptions, cache: "no-cache" };

Properties

recoveryStartUrl

Endpoint for retrieving initial details and challenge from the server

type: String
default: /api/registration/start

recoveryFinishUrl

Endpoint for completing the recovery process

type: String
default: /api/registration/finish

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

publicKeyCredentialCreateOptionsDecoder

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

type: Function
default: decodePublicKeyCredentialCreateOptions from utils/parse

registerCredentialEncoder

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

type: Function
default: encodeRegisterCredential from utils/parse

buttonText

The text displayed on the recovery button

type: String
default: Recover
reflected attribute: button-text

inputType

The type of input to use for the recovery token

type: String
default: text (any valid HTML input type)
reflected attribute: input-type

inputName

The name of the input to use for the recovery token

type: String
default: recovery-token
reflected attribute: input-name

label

Recovery token label content

type: String
default: Recovery token
reflected attribute: label

Events

recovery-started

Emitted when the recovery process starts (i.e. on form submit)

type: CustomEvent
detail: null

recovery-created

Emitted after creating the local credentials using navigator.credentials.create()

type: CustomEvent
detail: null

recovery-finished

Emitted when the recovery process is completed succesfully

type: CustomEvent
detail: {...} (content returned by the registrationFinishUrl endpoint)

recovery-error

Emitted when the recovery process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-recovery::part(form) {...}

::part(label)

Exposes the label element for styling

webauthn-recovery::part(label) {...}

::part(input)

Exposes the input element for styling

webauthn-recovery::part(input) {...}

::part(button)

Exposes the button element for styling

webauthn-recovery::part(button) {...}

webauthn-enrollment-requester

^{Back to components list}

Used for initiating the enrollment flow, which adds a new device to an existing account

Usage

with default values

import "webauthn-components/enrollment-requester";

/* html */
<webauthn-enrollment-requester></webauthn-enrollment-requester>;

with custom values

import "webauthn-components/enrollment-requester";

/* html */
<webauthn-enrollment-requester label="Enrollment code" input-type="number" input-name="code"></webauthn-enrollment-requester>;

const enrollmentComponent = document.querySelector("webauthn-enrollment-requester");
enrollmentComponent.fetchOptions = { ...enrollmentComponent.fetchOptions, cache: "no-cache" };

Properties

enrollmentStartUrl

Endpoint for retrieving initial details and challenge from the server

type: String
default: /api/registration/start

enrollmentFinishUrl

Endpoint for completing the recovery process

type: String
default: /api/registration/finish

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

publicKeyCredentialCreateOptionsDecoder

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

type: Function
default: decodePublicKeyCredentialCreateOptions from utils/parse

registerCredentialEncoder

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

type: Function
default: encodeRegisterCredential from utils/parse

buttonText

The text displayed on the enrollment button

type: String
default: Enroll device
reflected attribute: button-text

inputType

The type of input to use for the enrollment token

type: String
default: text (any valid HTML input type)
reflected attribute: input-type

inputName

The name of the input to use for the enrollment token

type: String
default: registration-add-token
reflected attribute: input-name

label

Enrollment token label content

type: String
default: Enrollment token
reflected attribute: label

Events

enrollment-requested

Emitted when the enrollment process starts (i.e. on form submit)

type: CustomEvent
detail: null

enrollment-created

Emitted after creating the local credentials using navigator.credentials.create()

type: CustomEvent
detail: null

enrollment-finished

Emitted when the enrollment process is completed succesfully

type: CustomEvent
detail: {...} (content returned by the registrationFinishUrl endpoint)

enrollment-error

Emitted when the enrollment process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

::part(label)

Exposes the label element for styling

webauthn-enrollment-requester::part(label) {...}

::part(input)

Exposes the input element for styling

webauthn-enrollment-requester::part(input) {...}

::part(button)

Exposes the button element for styling

webauthn-enrollment-requester::part(button) {...}

webauthn-enrollment-provider

^{Back to components list}

Used for generating the registration add token, required to add a new device to an existing account

Usage

with default values

import "webauthn-components/enrollment-provider";

/* html */
<webauthn-enrollment-provider></webauthn-enrollment-provider>;

with custom values

import "webauthn-components/enrollment-provider";

/* html */
<webauthn-enrollment-provider button-text="Get registration token"></webauthn-enrollment-provider>;

const enrollmentComponent = document.querySelector("webauthn-enrollment-provider");
enrollmentComponent.fetchOptions = { ...enrollmentComponent.fetchOptions, cache: "no-cache" };

Properties

enrollmentTokenUrl

Endpoint for retrieving the registration add token from the server

type: String
default: /api/registration/add

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "GET",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

buttonText

The text displayed on the enrollment button

type: String
default: Connect
reflected attribute: button-text

Events

enrollment-requested

Emitted when the enrollment process starts (i.e. on form submit)

type: CustomEvent
detail: null

enrollment-provided

Emitted when the server returns the registration add token

type: CustomEvent
detail: {...} (content returned by the enrollmentTokenUrl endpoint)

enrollment-error

Emitted when the enrollment process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

::part(button)

Exposes the button element for styling

webauthn-enrollment-requester::part(button) {...}

webauthn-rtc-enrollment-requester

^{Back to components list}

Used for initiating the enrollment flow using WebRTC

Usage

with default values

import "webauthn-components/rtc/enrollment-requester";

/* html */
<webauthn-rtc-enrollment-requester></webauthn-rtc-enrollment-requester>;

with custom values

import "webauthn-components/rtc/enrollment-requester";

/* html */
<webauthn-rtc-enrollment-requester request-button-text="Get connection code"></webauthn-rtc-enrollment-requester>;

const enrollmentComponent = document.querySelector("webauthn-rtc-enrollment-requester");
enrollmentComponent.confirmButtonText = `Add this device to ${userName}'s account`;
enrollmentComponent.agreementText = "I know what I'm doing";

Properties

enrollmentStartUrl

Endpoint for retrieving initial details and challenge from the server

type: String
default: /api/registration/start

enrollmentFinishUrl

Endpoint for completing the recovery process

type: String
default: /api/registration/finish

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "POST",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

webSocketSignalingEndpoint

WebSocket endpoint used for the discovery of the two devices through WebRTC

type: String
default: /api/socket

rtcIceServers

List of ICE servers to use for WebRTC connectivity

type: Array
default: [{ urls: "stun:stun.services.mozilla.com" }]

RTC

Access to the RTCPeerConnection instance associated with this component

type: RTCPeerConnection
default: null until initialization

publicKeyCredentialCreateOptionsDecoder

PublicKeyCredentialCreateOptions decoding function (i.e. Base64URLString to ArrayBuffer)

type: Function
default: decodePublicKeyCredentialCreateOptions from utils/parse

registerCredentialEncoder

Credential encoding function (i.e. ArrayBuffer to Base64URLString)

type: Function
default: encodeRegisterCredential from utils/parse

requestButtonText

The text displayed on the button used to generate WebSocket room code

type: String
default: Generate code
reflected attribute: request-button-text

confirmButtonText

The text displayed on the button used to confirm the enrollment

type: String
default: Enroll device
reflected attribute: confirm-button-text

cancelButtonText

The text displayed on the button used to cancel the enrollment

type: String
default: Cancel
reflected attribute: cancel-button-text

agreementText

The text displayed next to the checkbox for confirming the enrollment

type: String
default: I understand that this device will be added to another account
reflected attribute: agreement-text

peerCode

The WebSocket room code used to establish connectivity between the devices

type: String
default: ""
reflected attribute: peer-code

registrationAddToken

The registration add token received from the authenticated device

type: String
default: ""
reflected attribute: registration-add-token

Events

enrollment-code-requested

Emitted when user start the enrollment process by requesting a peer code

type: CustomEvent
detail: null

enrollment-provider-connected

Emitted after a enrollment provider has successfuly connected via WebRTC`

type: CustomEvent
detail: { user: String }

enrollment-cancelled

Emitted when the enrollment process is cancelled by the requesting user

type: CustomEvent
detail: null

enrollment-agreement-accepted

Emitted when the user has checked the agreement field

type: CustomEvent
detail: null

enrollment-agreement-declined

Emitted when the user has unchecked the agreement field

type: CustomEvent
detail: null

enrollment-registration-token-received

Emitted when the registration add token is received from the provider and set on the property

type: CustomEvent
detail: null

enrollment-started

Emitted when the enrollment process begins registering the new device

type: CustomEvent
detail: null

enrollment-created

Emitted when the enrollment process has successfuly created the credentials

type: CustomEvent
detail: null

enrollment-completedd

Emitted when the enrollment process has successfuly completed and the device has been registered to an existing account

type: CustomEvent
detail: { ... } (content returned by the enrollmentFinishUrl endpoint)

enrollment-error

Emitted when the enrollment process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

::part(label)

Exposes the label elements for styling

webauthn-enrollment-requester::part(label) {...}

::part(checkbox)

Exposes the input[type=checkbox] element for styling

webauthn-enrollment-requester::part(checkbox) {...}

::part(button)

Exposes the button elements for styling

webauthn-enrollment-requester::part(button) {...}

::part(request-button)

Exposes the request button element for styling

webauthn-enrollment-requester::part(request-button) {...}

::part(confirm-button)

Exposes the confirm button element for styling

webauthn-enrollment-requester::part(confirm-button) {...}

::part(cancel-button)

Exposes the cancel button element for styling

webauthn-enrollment-requester::part(cancel-button) {...}

::part(hidden)

Exposes the elements marked [hidden] for styling

webauthn-enrollment-requester::part(hidden) {...}

webauthn-rtc-enrollment-provider

^{Back to components list}

Used for providing the registration add token in the enrollment flow using WebRTC

Usage

with default values

import "webauthn-components/rtc/enrollment-provider";

/* html */
<webauthn-rtc-enrollment-provider></webauthn-rtc-enrollment-provider>;

with custom values

import "webauthn-components/rtc/enrollment-provider";

/* html */
<webauthn-rtc-enrollment-provider button-text="Establish connection"></webauthn-rtc-enrollment-provider>;

const enrollmentComponent = document.querySelector("webauthn-rtc-enrollment-provider");
enrollmentComponent.webSocketSignalingEndpoint = "/api/ws";
enrollmentComponent.inputName = "ws-peer-code"

Properties

enrollmentTokenUrl

Endpoint for retrieving the registration add token for the current account

type: String
default: /api/registration/add

fetchOptions

Fetch options used for all request within this component

type: Object
default:

{
  "method": "GET",
  "credentials": "include",
  "headers": {
    "Content-Type": "application/json"
  }
}

webSocketSignalingEndpoint

WebSocket endpoint used for the discovery of the two devices through WebRTC

type: String
default: /api/socket

rtcIceServers

List of ICE servers to use for WebRTC connectivity

type: Array
default: [{ urls: "stun:stun.services.mozilla.com" }]

RTC

Access to the RTCPeerConnection instance associated with this component

type: RTCPeerConnection
default: null until initialization

buttonText

The text displayed on the button used to connect to the enrollment requester

type: String
default: Connect
reflected attribute: button-text

label

The text on the label for the peer code input

type: String
default: Code
reflected attribute: label

inputType

The type of the input used for the peer code

type: String
default: text
reflected attribute: input-type

inputName

The name of the input used for the peer code

type: String
default: code
reflected attribute: input-name

Events

enrollment-started

Emitted when the enrollment process begins and the two devices try to connect to each other

type: CustomEvent
detail: null

enrollment-requested

Emitted when the component receives an enrollment request from the peer

type: CustomEvent
detail: null

enrollment-provided

Emitted when the registration add token is sent to the peer device requesting it

type: CustomEvent
detail: { ... } (content returned by the enrollmentTokenUrl endpoint)

enrollment-cancelled

Emitted when the enrollment process is cancelled by the requesting user

type: CustomEvent
detail: null

enrollment-completed

Emitted when the enrollment process has successfuly completed and the peer device has been registered to the current account

type: CustomEvent
detail: null

enrollment-error

Emitted when the enrollment process is interrupted by an error

type: CustomEvent
detail: { message: String }

Styling

::part(form)

Exposes the form element for styling

webauthn-enrollment-requester::part(form) {...}

::part(label)

Exposes the label element for styling

webauthn-enrollment-requester::part(label) {...}

::part(input)

Exposes the input element for styling

webauthn-enrollment-requester::part(input) {...}

::part(button)

Exposes the button element for styling

webauthn-enrollment-requester::part(button) {...}

License

MIT License

A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

Refer to the LICENSE file for the complete text.

Keywords

web components authn