v5.3.0

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] startAuthentication() now accepts a second useBrowserAutofill boolean argument that sets up support for credential selection via a browser's autofill prompt (a.k.a. Conditional UI). The new browserSupportsWebAuthnAutofill() helper method can be used independently to determine when this feature is supported by the browser (#214)
• [browser] startRegistration() and startAuthentication() will return a new authenticatorAttachment value when present that captures whether a cross-platform or platform authenticator was just used (#221)
• [typescript-types] A new PublicKeyCredentialFuture interface has been added to define new properties currently defined in the WebAuthn L3 spec draft. These new values support the above new functionality until official TypeScript types are updated accordingly (#214, #221)
• [typescript-types] A new "hybrid" transport has been added to AuthenticatorTransportFuture while browsers migrate away from the existing "cable" transport for cross-device auth (#222)

v5.2.1

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [server] generateRegistrationOptions() and generateAuthenticationOptions() will stop reporting typing errors for definitions of excludeCredentials and allowCredentials that were otherwise fine before v5.2.0 (#203)
• [typescript-types] The new AuthenticatorTransportFuture and PublicKeyCredentialDescriptorFuture have been added to track changes to WebAuthn that outpace TypeScript's DOM lib typings
• [browser] Version sync

v5.2.0

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser, typescript-types] The new "cable" transport is now recognized as a potential value of the AuthenticatorTransport type (#198)
• [server] verifyRegistrationResponse() and verifyAuthenticationResponse() now return credentialDeviceType and credentialBackedUp within authenticatorInfo as parsed values of two new flags being added to authenticator data. These response verification methods will also now throw an error when the invalid combination of these two flags (credentialDeviceType: "singleDevice", credentialBackedUp: true) is detected (#195)
  • This feature supports detection of "multi-device credentials" gradually coming to all major platform authenticator vendors later this year.

v5.1.0

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] Custom errors raised when calling startRegistration() and startAuthentication() will now have the same name property as the original error (#191)
• [server] Cleaned up code and added tests (#192, #193)

v5.0.0 - The one with more insights

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] Most common WebAuthn errors that can occur when calling startRegistration() and startAuthentication() will now return descriptions with more specific insights into what went wrong (#184)
• [testing] Version sync
• [typescript-types] Version sync

Breaking Changes

• [server] The fidoUserVerification argument to verifyAuthenticationResponse() has been replaced with the simpler requireUserVerification boolean (#181)

Previous values of "required" should specify true for this new argument; previous values of "preferred" or "discouraged" should specify false:

Before:

const verification = verifyAuthenticationResponse({
  // ...snip...
  fidoUserVerification: 'required',
});

After:

const verification = verifyAuthenticationResponse({
  // ...snip...
  requireUserVerification: true,
});

v4.4.0

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Attestation statement verification involving FIDO metadata now correctly validates the credential public keypair algorithm against possible algorithms defined in the metadata statement.
• [server] The expired GlobalSign R2 root certificate for "android-safetynet" responses has been removed
• [server] Certificate path validation errors will now identify which part of the chain and which certificate has an issue
• [server] verifyAuthenticationResponse()'s expectedChallenge argument also accepts a function that accepts a Base64URL string and returns a boolean to run custom logic against the clientDataJSON.challenge returned by the authenticator (see v4.3.0 release notes for more info).

v4.3.0

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] The expectedChallenge argument passed to verifyRegistrationResponse() can now be a function that accepts a Base64URL string and returns a boolean to run custom logic against the clientDataJSON.challenge returned by the authenticator. This allows for arbitrary data to be included in the challenge so it can be signed by the authenticator.

After generating registration options, the challenge can be augmented with additional data:

const options = generateRegistrationOptions(opts);

// Remember the plain challenge
inMemoryUserDeviceDB[loggedInUserId].currentChallenge = options.challenge;

// Add data to be signed
options.challenge = base64url(JSON.stringify({
  actualChallenge: options.challenge,
  arbitraryData: 'arbitraryDataForSigning',
}));

Then, when invoking verifyRegistrationResponse(), pass in a method for expectedChallenge to parse the challenge and return a boolean:

const expectedChallenge = inMemoryUserDeviceDB[loggedInUserId].currentChallenge;

const verification = await verifyRegistrationResponse({
  expectedChallenge: (challenge: string) => {
    const parsedChallenge = JSON.parse(base64url.decode(challenge));
    return parsedChallenge.actualChallenge === expectedChallenge;
  },
  // ...
});

To retrieve the arbitrary data afterwards, use decodeClientDataJSON() afterwards to get it out:

import { decodeClientDataJSON } from '@simplewebauthn/server/helpers';

const { challenge } = decodeClientDataJSON(response.clientDataJSON);
const parsedChallenge = JSON.parse(base64url.decode(challenge));
console.log(parsedChallenge.arbitraryData); // 'arbitraryDataForSigning'

v4.2.0

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] The debug library has been incorporated to support logging output from the library's internal operations. Add the following environment variable to your application to view this output when using this library:

DEBUG=SimpleWebAuthn:*

The following logging scopes are defined in this release:

SimpleWebAuthn:MetadataService

See PR #159 for a preview of logging output.

v4.1.0

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] platformAuthenticatorIsAvailable() now checks that WebAuthn is supported at all before attempting to query for the status of an available platform authenticator.
• [server] MetadataService.initialize() gained a new verificationMode option that can be set to "permissive" to allow registration response verification to continue when an unregistered AAGUID is encountered. Default behavior, that fails registration response verification, is represented by the alternative value "strict"; MetadataService continues to default to this more restrictive behavior.

v4.0.0 - The one with some new names

A lot has happened to me since I first launched SimpleWebAuthn back in May 2020. My understanding of WebAuthn has grown by leaps and bounds thanks in part to my representing Duo/Cisco in the W3C's WebAuth Adoption Working Group. I'm now in a point in my life in which it's no longer sufficient to think, "what's in SimpleWebAuthn's best interests?" Now, I have an opportunity to think bigger - "what's in the WebAuthn API's best interests?"

While early on I thought "attestation" and "assertion" were important names to WebAuthn, I've since come to better appreciate the spec's efforts to encourage the use of "registration" and "authentication" instead. To that end I decided it was time to rename all of the project's various public methods and types to get as much as possible to use "registration" and "authentication" instead.

This release is one of the more disruptive because it affects everyone who's used SimpleWebAuthn to date. The good news is that, while method and type names have changed, their capabilities remain the same. Updating your code to this version of SimpleWebAuthn should only involve renaming existing method calls and type annotations.

Please take the time to read the entire changelog for this release! There are a handful of new features also included that users with advanced use cases will find helpful. The simple use cases of the library remain unchanged - most new features are for power users who require extra scrutiny of authenticators that interact with their website and are otherwise opt-in as needed.

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] A new (asynchronous) helper method platformAuthenticatorIsAvailable() has been added for detecting when hardware-bound authenticators like Touch ID, Windows Hello, etc... are available for use. More info is available here.
• [server] The new SettingsService can be used to configure aspects of SimpleWebAuthn like root certs for enhanced registration response verification or for validating FIDO MDS BLOBs with MetadataService. More info is available here.
• [server] Known root certificates for the following attestation formats have been updated: 'android-key', 'android-safetynet', 'apple'
• [server] A wide range of internal helper methods are now exported from '@simplewebauthn/server/helpers' (not a new package, but a subpath.) These methods can be used, for example, to process non-standard responses that are not officially part of the WebAuthn spec and thus unlikely to ever be supported by SimpleWebAuthn.
• [server] MetadataService now supports FIDO Alliance Metadata Service version 3.0.

Breaking Changes

• [browser, server, typescript-types] All methods and types that included "attestation" in the name have been renamed to use "registration" instead
• [browser, server, typescript-types] All methods and types that included "assertion" in the name have been renamed to use "authentication" instead.

The quickest way to update your code is to try changing "attestation" to "registration" and "assertion" to "authentication" in the name of whatever method or type is no longer working and see if that fixes it (exceptions to this rule are called out with asterisks below.) If it doesn't, check out PR #147 to see all of the renamed methods and types and try to cross-reference the original to see what it was renamed to.

Examples:

• generateAttestationOptions() -> generateRegistrationOptions()
• GenerateAttestationOptionsOpts -> GenerateRegistrationOptionsOpts
• verifyAssertionResponse() -> verifyAuthenticationResponse()
• VerifiedAttestation -> VerifiedRegistrationResponse (*)
• VerifiedAssertion -> VerifiedAuthenticationResponse (*)
• startAttestation() -> startRegistration()
• startAssertion() -> startAuthentication()

These examples are not a comprehensive list of all the renamed methods! Rather these are examples of how method names were changed to try and eliminate "attestation" and "assertion" from the public API of both @simplewebauthn/browser and @simplewebauthn/server.

• [server] The opts argument for MetadataService.initialize() is now optional.
• [server] The opts.mdsServers argument for MetadataService.initialize(opts) is now a simple array of URL strings to FIDO Alliance MDSv3-compatible servers. If no value is specified then MetadataService will query the official FIDO Alliance Metadata Service version 3.0.

See here for more information about the updated MetadataService.

• [browser] supportsWebAuthn() has been renamed to browserSupportsWebAuthn() in an effort to make the method convey a clearer idea of what supports WebAuthn.