@simplewebauthn/browser - npm Package Versions

v8.2.1

Packages

• @simplewebauthn/browser@8.2.1

Changes

• [browser] startRegistration() will visibly warn in the browser console when a WebAuthn API method call errors out in a way that is likely due to a browser extension intercepting the API (#447)

v8.2.0

Packages

• @simplewebauthn/browser@8.2.0
• @simplewebauthn/server@8.2.0

Changes

• [browser] startRegistration() will no longer error out on registration responses generated by the 1Password browser extension (#443, with thanks to @unix)
• [browser] Helper methods base64URLStringToBuffer() and bufferToBase64URLString() are now exported from @simplewebauthn/browser (#444)
• [server] verifyRegistrationResponse() and verifyAuthenticationResponse() now accept a new expectedType argument that can be used to, for example, verify Secure Payment Confirmation responses (#436, with thanks to @fabiancook)
• [server] Responses containing malformed authenticator data returned from Firefox 117 will no longer raise an error (#441)

v8.0.2

Packages

• @simplewebauthn/browser@8.0.2

Changes

• [browser] The NPM package now targets ES2021 for support in older browsers like Safari 13.1 (#429)

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 (#425)
  • 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
• [browser] Version sync

Breaking Changes

• [server] generateRegistrationOptions() and generateAuthenticationOptions() are now asynchronous methods. Refactor calls to these methods to handle the Promise 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 the Promise 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, optional publicKeyAlgorithm, publicKey, and authenticatorData convenience values that track JSON interface changes in WebAuthn L3 draft (#400)
• [iso-crypto] Version sync
• [server] verifyRegistrationResponse() and verifyAuthenticationResponse() 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 for AuthenticatorTransportFuture (#399)

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() and startAuthentication() now include a code property to help programmatically detect identified errors. A new cause 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 calling startAuthentication() for modal UI) will now throw an AbortError instead of a string (#371)

v7.1.0

Packages:

• @simplewebauthn/browser@7.1.0

Changes:

• [browser] startRegistration() and startAuthentication() now pass through all NotAllowedError's without trying to interpret what caused them (#353)

v7.0.1

Packages:

• @simplewebauthn/browser@7.0.1
• @simplewebauthn/iso-webcrypto@7.0.1
• @simplewebauthn/server@7.0.1

Changes:

• [server] Update dependencies for better deduping in projects using @simplewebauthn/server (#341)
• [browser] Version sync
• [iso-webcrypto] Version sync

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 values
  • isoCrypto for leveraging the WebCrypto API when working with various WebAuthn/FIDO2 data structures
  • isoBase64URL for encoding and decoding values into base64url (with optional base64 support)
  • isoUint8Array for working with Uint8Arrays
  • cose 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 a Uint8Array instead of a Buffer. They will need to be passed into Buffer.from(...) to convert them to Buffer if needed:
  • aaguid
  • authData
  • clientDataHash
  • credentialID
  • credentialPublicKey
  • rpIdHash
• [server] The following values returned from verifyAuthenticationResponse() are now a Uint8Array instead of a Buffer. They will need to be passed into Buffer.from(...) to convert them to Buffer if needed:
  • credentialID
• [server] The isBase64URLString() helper is now isoBase64URL.isBase64url()
• [server] The decodeCborFirst() helper is now isoCBOR.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 the RegistrationResponseJSON type
  • The AuthenticationCredentialJSON type has been replaced by the AuthenticationResponseJSON type
  • RegistrationCredentialJSON.transports has been relocated into RegistrationResponseJSON.response.transports to mirror response structure in the WebAuthn spec
  • The verifyRegistrationResponse() method has had its credential argument renamed to response
  • The verifyAuthenticationResponse() method has had its credential argument renamed to response
• [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)

<details> <summary>Refactor Tips</summary> 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,
});

</details>

• [server] generateRegistrationOptions() now defaults to preferring the creation of discoverable credentials. See below for refactor tips (#324)

<details> <summary>Refactor Tips</summary> 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',
  },
});

</details>