@simplewebauthn/browser - npm Package Versions

v11.0.0 - The one that auto-registers

Say hello to support for automatic passkey registration, support for valid conditional UI <input> elements stashed away in web components, and to the new WebAuthnCredential type that modernizes some logic within.

There are some breaking changes in this release! Please see Breaking Changes below for refactor guidance.

Packages

• @simplewebauthn/browser@11.0.0
• @simplewebauthn/server@11.0.0
• @simplewebauthn/types@11.0.0

Changes

• [browser] [server] A new useAutoRegister argument has been added to startRegistration() to support attempts to automatically register passkeys for users who just completed non-passkey auth. verifyRegistrationResponse() has gained a new requireUserPresence option that can be set to false when verifying responses from startRegistration({ useAutoRegister: true, ... }) (#623)
• [browser] A new verifyBrowserAutofillInput argument has been added to startAuthentication() to disable throwing an error when a correctly configured <input> element cannot be found (but perhaps a valid one is present in a web component shadow's DOM) (#621)
• [server] [types] The AuthenticatorDevice type has been renamed to WebAuthnCredential and has had its properties renamed. The return value out of verifyRegistrationResponse() and corresponding inputs into verifyAuthenticationResponse() have been updated accordingly. See Breaking Changes below for refactor guidance (#625)
• [server] verifyRegistrationResponse() now verifies that the authenticator data AAGUID matches the leaf cert's id-fido-gen-ce-aaguid extension AAGUID when it is present (#609)
• [server] TPM attestation verification recognizes the corrected TPM manufacturer identifier for IBM (#610)
• [server] Types for the defunct authenticator extensions uvm and dpk have been removed (#611)

Breaking Changes

[browser] Positional arguments in startRegistration() and startAuthentication() have been replaced by a single object

Property names in the object match the names of the previously-positional arguments. To update existing implementations, wrap existing options in an object with corresponding properties:

Before:

startRegistration(options);
startAuthentication(options, true);

After:

startRegistration({ optionsJSON: options });
startAuthentication({ optionsJSON: options, useBrowserAutofill: true });

[server] [types] The AuthenticatorDevice type has been renamed to WebAuthnCredential

AuthenticatorDevice.credentialID and AuthenticatorDevice.credentialPublicKey have been shortened to WebAuthnCredential.id and WebAuthnCredential.publicKey respectively.

verifyRegistrationResponse() has been updated accordingly to return a new credential value of type WebAuthnCredential. Update code that stores credentialID, credentialPublicKey, and counter out of verifyRegistrationResponse() to store credential.id, credential.publicKey, and credential.counter instead:

Before:

const { registrationInfo } = await verifyRegistrationResponse({...});

storeInDatabase(
  registrationInfo.credentialID,
  registrationInfo.credentialPublicKey,
  registrationInfo.counter,
  body.response.transports,
);

After:

const { registrationInfo } = await verifyRegistrationResponse({...});

storeInDatabase(
  registrationInfo.credential.id,
  registrationInfo.credential.publicKey,
  registrationInfo.credential.counter,
  registrationInfo.credential.transports,
);

Update calls to verifyAuthenticationResponse() to match the new credential argument that replaces the authenticator argument:

Before:

import { AuthenticatorDevice } from '@simplewebauthn/types';

const authenticator: AuthenticatorDevice = {
  credentialID: ...,
  credentialPublicKey: ...,
  counter: 0,
  transports: [...],
};

const verification = await verifyAuthenticationResponse({
  // ...
  authenticator,
});

After:

import { WebAuthnCredential } from '@simplewebauthn/types';

const credential: WebAuthnCredential = {
  id: ...,
  publicKey: ...,
  counter: 0,
  transports: [...],
};

const verification = await verifyAuthenticationResponse({
  // ...
  credential,
});

v10.0.0 - The one that goes up to 20

Thanks for everything, Node 16 and Node 18, but it's time to move on! The headlining change of this release is the targeting of Node LTS v20+ as the minimum Node runtime. Additional developer-centric quality-of-life changes have also been made in the name of streamlining use of SimpleWebAuthn on both the back end and front end.

This release is packed with updates, so buckle up! Refactor advice for breaking changes is, as always, offered below.

Packages

• @simplewebauthn/browser@10.0.0
• @simplewebauthn/server@10.0.0
• @simplewebauthn/types@10.0.0

Changes

• [server] The minimum supported Node version has been raised to Node v20 (#531)
• [server] user.displayName now defaults to an empty string if a value is not specified for userDisplayName when calling generateRegistrationOptions() (#538)
• [browser] The browserSupportsWebAuthnAutofill() helper will no longer break in environments in which PublicKeyCredential is not present (#557, with thanks to @clarafitzgerald)

Breaking Changes

• [server] The following breaking changes were made in PR #529:
  • generateRegistrationOptions() now expects Base64URLString for excluded credential IDs
  • generateAuthenticationOptions() now expects Base64URLString for allowed credential IDs
  • credentialID returned from response verification methods is now a Base64URLString
  • AuthenticatorDevice.credentialID is now a Base64URLString
  • isoBase64URL.isBase64url() is now called isoBase64URL.isBase64URL()
• [browser, server] The following breaking changes were made in PR #552:
  • generateRegistrationOptions() now accepts an optional Uint8Array instead of a string for userID
  • isoBase64URL.toString() and isoBase64URL.fromString() have been renamed
  • generateRegistrationOptions() will now generate random user IDs
  • user.id is now treated like a base64url string in startRegistration()
  • userHandle is now treated like a base64url string in startAuthentication()
• [server] rpID is now a required argument when calling generateAuthenticationOptions() (#555)

---

[server] generateRegistrationOptions() now expects Base64URLString for excluded credential IDs

The isoBase64URL helper can be used to massage Uint8Array credential IDs into base64url strings:

Before

const opts = await generateRegistrationOptions({
  // ...
  excludeCredentials: devices.map((dev) => ({
    id: dev.credentialID, // type: Uint8Array
    type: 'public-key',
    transports: dev.transports,
  })),
});

After

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

const opts = await generateRegistrationOptions({
  // ...
  excludeCredentials: devices.map((dev) => ({
    id: isoBase64URL.fromBuffer(dev.credentialID), // type: string
    transports: dev.transports,
  })),
});

The type argument is no longer needed either.

---

[server] generateAuthenticationOptions() now expects Base64URLString for allowed credential IDs

Similarly, the isoBase64URL helper can also be used during auth to massage Uint8Array credential IDs into base64url strings:

Before

const opts = await generateAuthenticationOptions({
  // ...
  allowCredentials: devices.map((dev) => ({
    id: dev.credentialID, // type: Uint8Array
    type: 'public-key',
    transports: dev.transports,
  })),
});

After

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

const opts = await generateAuthenticationOptions({
  // ...
  allowCredentials: devices.map((dev) => ({
    id: isoBase64URL.fromBuffer(dev.credentialID), // type: Base64URLString (a.k.a string)
    transports: dev.transports,
  })),
});

The type argument is no longer needed either.

---

[server] credentialID returned from response verification methods is now a Base64URLString

It is no longer necessary to manually stringify credentialID out of response verification methods:

Before

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

// Registration
const { verified, registrationInfo } = await verifyRegistrationResponse({ ... });
if (verified && registrationInfo) {
  const { credentialID } = registrationInfo;
  await storeInDatabase({ credIDString: isoBase64URL.fromBuffer(credentialID), ... });
}

// Authentication
const { verified, authenticationInfo } = await verifyAuthenticationResponse({ ... });
if (verified && authenticationInfo) {
  const { newCounter, credentialID } = authenticationInfo;
  dbAuthenticator.counter = authenticationInfo.newCounter;
  await updateCounterInDatabase({
    credIDString: isoBase64URL.fromBuffer(credentialID),
    newCounter,
  });
}

After

// Registration
const { verified, registrationInfo } = await verifyRegistrationResponse({ ... });
if (verified && registrationInfo) {
  const { credentialID } = registrationInfo;
  await storeInDatabase({ credIDString: credentialID, ... });
}

// Authentication
const { verified, authenticationInfo } = await verifyAuthenticationResponse({ ... });
if (verified && authenticationInfo) {
  const { newCounter, credentialID } = authenticationInfo;
  dbAuthenticator.counter = authenticationInfo.newCounter;
  await updateCounterInDatabase({ credIDString: credentialID, newCounter });
}

---

v9.0.1

Packages

• @simplewebauthn/browser@9.0.1
• @simplewebauthn/server@9.0.1
• @simplewebauthn/types@9.0.1

Changes

• [server] Fixed an issue with use with CBOR handling in runtime environments that restrict use of eval() (#511, with thanks to @Maronato)
• [browser, types] Monorepo version sync

v9.0.0 - The one in which 11 characters were saved

Packages

• @simplewebauthn/browser@9.0.0
• @simplewebauthn/server@9.0.0
• @simplewebauthn/types@9.0.0

Changes

• [types] The @simplewebauthn/typescript-types package has been renamed to @simplewebauthn/types (#508)

Breaking Changes

• Any reference to @simplwebauthn/typescript-types will need to be replaced with the new package name @simplewebauthn/types:

Before:

import { ... } from '@simplwebauthn/typescript-types';

After:

$> npm uninstall @simplewebauthn/typescript-types
$> npm install -D @simplewebauthn/types

import { ... } from '@simplwebauthn/types';

v8.3.7

Packages

• @simplewebauthn/browser@8.3.7
• @simplewebauthn/server@8.3.7

Changes

• [browser] The WebAuthnError class can now be imported from @simplewebauthn/browser for simpler error detection and handling when calling startRegistration() and startAuthentication() (#505, with thanks to @zoontek)
• [server] The COSEPublicKeyEC2, COSEPublicKeyOKP, and COSEPublicKeyRSA types can now be imported from @simplwebauthn/server/helpers to help type possible return values from decodeCredentialPublicKey() (#504, with thanks to @mmv08)
• [server] Custom challenge strings passed to generateRegistrationOptions() will now be treated as UTF-8 strings to align with the existing behavior of generateAuthenticationOptions() (#507)

v8.3.4

Packages

• @simplewebauthn/browser@.3.4
• @simplewebauthn/server@.3.4
• @simplewebauthn/typescript-types@.3.4

Changes

• [server] The library will now try to use globalThis.crypto first before trying to import Node's node:crypto as a fallback (#468)
• [browser, types] Version sync

v8.3.3

Packages

• @simplewebauthn/browser@8.3.3
• @simplewebauthn/server@8.3.3
• @simplewebauthn/typescript-types@8.3.3

Changes

• [server, types] deno vendor will no longer error out because typescript-types/src/dom.ts is missing (#466)
• [server] Authenticator data will now be preserved after bad CBOR encoding is detected and temporarily fixed when handling security key responses from Firefox (#465)
• [browser] Version sync due to changes in typescript-types

v8.3.1

Packages

• @simplewebauthn/browser@8.3.1

Changes

• [browser] Calling startAuthentication(..., true) to set up conditional UI will now require the "webauthn" value in an input's autocomplete="..." be either the only value or the last value (#451)

v8.3.0

Packages

• @simplewebauthn/browser@8.3.0

Changes

• [browser] The WebAuthnAbortService singleton can now be imported, with a cancelCeremony() method that can be called to manually cancel any active WebAuthn ceremonies. This can be used by developers building projects that use client-side routing to better control the behavior of their UX in response to router navigation events. (#449)