Releases: MasterKale/SimpleWebAuthn
v8.0.0 - Around the (ESM) World
This major release marks the completion of a long journey that started with the release of v7.0.0:
SimpleWebAuthn is now available for use in non-Node projects! 🎉
SimpleWebAuthn debuted in mid-2020 as a combination of libraries aiming to make WebAuthn simpler to
use across browsers and "NodeJS + CommonJS" applications. Since then NodeJS has evolved to gain ESM
support, and additional JavaScript and TypeScript runtimes have debuted that offer ESM-centric,
TypeScript-first alternatives while also implementing Web APIs to offer a more consistent and
capable execution environment for developers.
I've wanted to make this project available to developers using these Node alternatives to help them
get past some of WebAuthn's rough spots. Today I'm happy to announce that this goal has been
achieved! 😌
See the Changes below for more information, as well as additional information on breaking
changes made in this release.
Packages
- @simplewebauthn/browser@8.0.0
- @simplewebauthn/server@8.0.0
- @simplewebauthn/typescript-types@8.0.0
Changes
- [server] [typescript-types] SimpleWebAuthn can now also be used in runtimes other than Node.
Deno is now a first-class runtime for this project alongside Node.- The following list of runtimes are officially supported:
- (Existing) NodeJS using CommonJS
- (Existing) NodeJS using ECMAScript Modules (ESM)
- (New) Deno @ https://deno.land/x/simplewebauthn
- The following list of runtimes are periodically tested but unofficially supported:
- (New) CloudFlare Workers
- (New) Bun
- The following list of runtimes are officially supported:
- [browser] Version sync
Breaking Changes
- [server]
generateRegistrationOptions()
andgenerateAuthenticationOptions()
are now
asynchronous methods. Refactor calls to these methods to handle thePromise
that's now returned
in whatever way is appropriate for your project. - [server]
generateChallenge()
(in@simplewebauthn/server/helpers
) is now an asynchronous
method. Refactor calls to this method to handle thePromise
that's now returned in whatever way
is appropriate for your project.
v7.4.0
Packages:
- @simplewebauthn/browser@7.4.0
- @simplewebauthn/iso-webcrypto@7.4.0
- @simplewebauthn/server@7.4.0
- @simplewebauthn/typescript-types@7.4.0
Changes:
- [browser] [typescript-types]
AuthenticatorAttestationResponseJSON
now includes additional, optionalpublicKeyAlgorithm
,publicKey
, andauthenticatorData
convenience values that track JSON interface changes in WebAuthn L3 draft (#400) - [iso-crypto] Version sync
- [server]
verifyRegistrationResponse()
andverifyAuthenticationResponse()
now return the matched origin and RP ID in their to output to help RP's that use the same verification logic with multiple origins and RP ID's understand where a response was generated and for which RP (#415) - [typescript-types]
"smart-card"
is now a recognized value forAuthenticatorTransportFuture
(#399)
v7.3.1
Packages:
- @simplewebauthn/server@7.3.1
Changes:
- [server] The
AttestationStatement.size
property declaration is now more tolerant of older versions of TypeScript - [server] Declared minimum supported TypeScript version of 4.4+
v7.3.0
v7.2.0
Packages:
- @simplewebauthn/browser@7.2.0
- @simplewebauthn/iso-webcrypto@7.2.0
- @simplewebauthn/server@7.2.0
Changes:
- [server]
generateRegistrationOptions()
defaults to-8
,-7
, and-257
for supported public key algorithms (#361) - [browser] [iso-webcrypto] [server] Users will no longer need to also
npm install @simplewebauthn/typescript-types
to pull in type definitions when using these libraries (#370) - [browser] Errors raised by
startRegistration()
andstartAuthentication()
now include acode
property to help programmatically detect identified errors. A newcause
property is also populated that will always include the original error raised by the WebAuthn API call (#367) - [browser] Aborting conditional UI (i.e. calling
startAuthentication(..., true)
and then subsequently callingstartAuthentication()
for modal UI) will now throw anAbortError
instead of astring
(#371)
v7.1.0
v7.0.1
v7.0.0 - The one that sets the library loose
The highlight of this release is the rearchitecture of @simplewebauthn/server to start allowing it to be used in more environments than Node. This was accomplished by refactoring the library completely away from Node's Buffer
type and crypto
package, and instead leveraging Uint8Array
and the WebCrypto Web API for all cryptographic operations. This means that, hypothetically, this library can now also work in any non-Node environment that provides access to the WebCrypto API on the global crypto
object.
Existing Node support is still first-class! In fact because @simplewebauth/server still builds to CommonJS it will continue to be tricky to incorporate the library in non-Node, ESM-only environments that do not support CommonJS modules (whether natively, via a bundler, etc...) A future update will attempt to fix this to offer better support for use in ESM-only projects with support for WebCrypto (e.g. Deno).
Please read all of the changes below! There are significant breaking changes in this update and additional information has been included to help adapt existing projects to the newest version of these libraries.
Packages:
- @simplewebauthn/browser@7.0.0
- @simplewebauthn/server@7.0.0
- @simplewebauthn/typescript-types@7.0.0
- @simplewebauthn/iso-webcrypto@7.0.0
Changes:
- [server] A new "isomorphic" library architecture allows for use of this library in non-Node environments. In addition, the library now targets Node 16 and above (#299)
- [server]
@simplewebauthn/server/helpers
now includes several new helpers for working with WebAuthn-related data types that should work in all run times:isoCBOR
for working with CBOR-encoded valuesisoCrypto
for leveraging the WebCrypto API when working with various WebAuthn/FIDO2 data structuresisoBase64URL
for encoding and decoding values into base64url (with optional base64 support)isoUint8Array
for working withUint8Array
scose
for working with COSE-related methods and types
- [server] Certificate chains using self-signed X.509 root certificates now validate more reliably (#310)
- [server] Code execution times for some common use cases are approximately 60-90% faster (#311, #315)
- [iso-webcrypto] This new library helps @simplewebauthn/server reference the WebCrypto API in more environments than Node. This package is available on NPM, but it is not officially supported for use outside of @simplewebauthn/server!
Breaking Changes
- [server] The following values returned from
verifyRegistrationResponse()
are now aUint8Array
instead of aBuffer
. They will need to be passed intoBuffer.from(...)
to convert them toBuffer
if needed:aaguid
authData
clientDataHash
credentialID
credentialPublicKey
rpIdHash
- [server] The following values returned from
verifyAuthenticationResponse()
are now aUint8Array
instead of aBuffer
. They will need to be passed intoBuffer.from(...)
to convert them toBuffer
if needed:credentialID
- [server] The
isBase64URLString()
helper is nowisoBase64URL.isBase64url()
- [server] The
decodeCborFirst()
helper is nowisoCBOR.decodeFirst()
- [server] The
convertPublicKeyToPEM()
helper has been removed - [typescript-types] [server] [browser] New JSON-serialization-friendly data structures added to the WebAuthn L3 spec have been preemptively mapped into this project. Some types, values, and methods have been refactored or replaced accordingly (#320):
- The
RegistrationCredentialJSON
type has been replaced by theRegistrationResponseJSON
type - The
AuthenticationCredentialJSON
type has been replaced by theAuthenticationResponseJSON
type RegistrationCredentialJSON.transports
has been relocated intoRegistrationResponseJSON.response.transports
to mirror response structure in the WebAuthn spec- The
verifyRegistrationResponse()
method has had itscredential
argument renamed toresponse
- The
verifyAuthenticationResponse()
method has had itscredential
argument renamed toresponse
- The
- [server]
generateRegistrationOptions()
now marks user verification as"preferred"
during registration and authentication (to reduce some user friction at the browser+authenticator level), and requires user verification during response verification. See below for refactor tips (#307)
Refactor Tips
RP's implementing a second-factor flow with WebAuthn, where UV is not important (because username+password are provided before WebAuthn is leveraged for the second factor), should not require user verification when verifying responses:verifyRegistrationResponse()
Before
const verification = await verifyRegistrationResponse({
credential: attestationFIDOU2F,
// ...
});
After
const verification = await verifyRegistrationResponse({
credential: attestationFIDOU2F,
// ...
requireUserVerification: false,
});
verifyAuthenticationResponse()
Before
const verification = await verifyAuthenticationResponse({
credential: assertionResponse,
// ...
});
After
const verification = await verifyAuthenticationResponse({
credential: assertionResponse,
// ...
requireUserVerification: false,
});
- [server]
generateRegistrationOptions()
now defaults to preferring the creation of discoverable credentials. See below for refactor tips (#324)
Refactor Tips
RP's that do not require support for discoverable credentials from authenticators will need to update their calls to `generateRegistrationOptions()` accordingly:generateRegistrationOptions()
Before
const options = generateRegistrationOptions({
rpName: 'SimpleWebAuthn',
rpID: 'simplewebauthn.dev',
userID: '1234',
userName: 'usernameHere',
});
After
const options = generateRegistrationOptions({
rpName: 'SimpleWebAuthn',
rpID: 'simplewebauthn.dev',
userID: '1234',
userName: 'usernameHere',
authenticatorSelection: {
// See https://www.w3.org/TR/webauthn-2/#enumdef-residentkeyrequirement
residentKey: 'discouraged',
},
});
v6.2.2
v6.2.1
Packages:
- @simplewebauthn/browser@6.2.1
- @simplewebauthn/server@6.2.1
- @simplewebauthn/testing@6.2.1
- @simplewebauthn/typescript-types@6.2.1
Changes:
- [browser] Multiple calls to
startRegistration()
andstartAuthentication()
will now more reliably cancel the preceding call (#275) - [server] Version sync
- [testing] Version sync
- [typescript-types] Version sync