web-authn

Passkey register / authenticate with HTML. Pair it with Quark to render the result.

<web-authn start-method="register" options-url="/api/registration-options" verify-url="/api/users">
    <form>
        <button type="submit">One click sign up!</button>
    </form>
</web-authn>

Features

• Provides data Use Quark to render the verify response
• Full ceremony Fetches options, runs the browser's WebAuthn prompt, then verifies — one element
• Register or authenticate start-method picks the ceremony
• Submit command --submit starts the ceremony programmatically — for forms outside the DOM subtree, or buttons outside the <form>
• Chainable web-authn-success fires like any {tag}-success event — chain a redirect or next step
• Highly configurable Headers, credentials, redirect, etc

Installation

<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/web-authn@0.1.5/dist/index.umd.min.js"></script>

npm install @excom/web-authn

<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/web-authn"></script>
<link rel="stylesheet" href="/node_modules/@excom/web-authn">

import "@excom/web-authn";

Depends on @simplewebauthn/browser for the actual WebAuthn calls (startRegistration / startAuthentication). You can use any server-side library to handle the WebAuthn requests, but it is recommended to use the counterpart library, @simplewebauthn/server, since they seamlessly understand the same contract.

Usage

<web-authn options-url="/api/webauthn/register/options"
  verify-url="/api/webauthn/register/verify" start-method="register">
  <form>
    <input name="username" required>
    <button type="submit">Register passkey</button>
  </form>
</web-authn>

On submit: options-url is fetched for ceremony options, the browser's native passkey prompt runs (@simplewebauthn/browser), and the resulting credential is posted to verify-url. Use start-method="authenticate" for sign-in instead of registration.

Hook the lifecycle state with CSS:

web-authn[is-loading] { /* show loading spinner */ }
web-authn[is-error]::before { content: "An error occurred." }

Or Quark:

web-authn[is-success] {
  $res: prop("provision").body;
  span { content: $res.verified; }
}

Chain a next step off success the same way you would for any <super-form> or <provider-fetch>:

<event-handler listen-for="web-authn-success" fire-event="onboarding-step-complete">
  <web-authn options-url="/api/webauthn/register/options"
    verify-url="/api/webauthn/register/verify" start-method="register">
    <form><input name="username"><button type="submit">Register</button></form>
  </web-authn>
</event-handler>

Examples

Authenticate

API Reference