Library for parsing and verifying FIDO2 WebAuthn attestations and assertions
npm install fido2-jsfido2-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.
This is an ESM-only package, and starting version 20.17 Node.js supports requiring pure ESM modules. See Loading ECMAScript modules using require.
``js
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);
}
`
`js
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);
}
`
You can easily pull this library along with its dependencies from jsdeliver:
`html`
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
`js
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.
MIT.