FIDO2.js

fido2-js is a simple library for parsing and verifying FIDO2 attestation and assertion responses.

Depends on cbor-x, @peculiar/x509, and SubtleCrypto API. Works in browsers.

Doesn't provide means of generating requests for the client, but that isn't hard to do on your own anyway.

Supports common methods of attestation such as EC, OKP and RSA.

Usage

This is an ESM-only package, and starting version 20.17 Node.js supports requiring pure ESM modules. See Loading ECMAScript modules using require.

Attestation

const { attestation } = require('fido2-js');
// or
import { attestation } from 'fido2-js';

// for the returned object to actually be of attestation,
// client data type must be 'webauthn.create'.
// it should be also stated that parse method can throw on malformed input
const parsed = await attestation(
    {
        clientDataJSON: '...',
        attestationObject: '...',
    },
    {
        challenge,
        origins: [origin],
        userFactor: ['verified', 'present'],
    }
).catch(err => err);

if (parsed instanceof Error) { // safe to assume Error
    console.error(parsed);
} else {
    publicKey = parsed.jwk();

    console.log('attestation succeeded', parsed);
}

Assertion

const { assertion } = require('fido2-js');
// or
import { assertion } from 'fido2-js';

const parsed = await assertion(
    {
        clientDataJSON: '...',
        authenticatorData: '...',
        signature: '...',
        userHandle: '...',
    },
    {
        challenge,
        origins: [origin],
        publicKey, // can also pass a COSE credentialPublicKey or a CryptoKey object
        counter: 0,
        userFactor: ['verified', 'present'], // can also just pass 'either'
        userHandle: /* base64 string or some byte array */,
    }
).catch(err => err);

if (parsed instanceof Error) { // safe to assume Error
    console.error(parsed);
} else {
    console.log('assertion succeeded', parsed);
}

Browser

You can easily pull this library along with its dependencies from jsdeliver:

<script type="module">
    import { assertion, attestation } from 'https://cdn.jsdelivr.net/npm/[email protected]/+esm';
    import parse from 'https://cdn.jsdelivr.net/npm/[email protected]/parse.js/+esm';

    // ...
</script>

Bonus

There's plenty of WebAuthn tutorials out there, but most of them only show basic flow of authentication, without revealing the much-needed-to-know details.

If you're new to FIDO2 WebAuthn, I suggest playing with the parse function to better understand the protocol shapes. MDN's WebAuthn documentation is your best friend for this: Web Authentication API | MDN

import parse from 'fido2-js/parse';

// the parse function lets you only parse the response returned by authenticator,
// letting you a view into the structure of said object and visually understand
// what you're working with, I wish I had this when starting out!

// mere example. your function (endpoint on the server) implementation would be different
function endpoint(body) {
    // a very detailed explanation of all of these things can found at https://www.w3.org/TR/webauthn-3/
    // the response variable is returned by assertion and attestation functions
    const { response, rawAuthenticatorData, rawClientData } = parse(body);

    console.log(response, rawAuthenticatorData, rawClientData);
}

You can also view a browser-only example at browser.html.

[!NOTE] On Linux, if you don't have a physical security key available, you may need an authenticator emulator. Check out virtual-fido.

License

MIT.