This package has been renamed to @simplewebauthn/types. Please install @simplewebauthn/types instead to ensure you receive future updates.
TypeScript types used by the @simplewebauthn series of libraries
TypeScript typings for @simplewebauthn/server and @simplewebauthn/browser
This package is available on npm:
MasterKale
npm install @simplewebauthn/typescript-typesIt is also available for import into Deno projects from deno.land/x:
import {...} from 'https://deno.land/x/simplewebauthn/deno/typescript-types.ts';Changes:
"android-key" attestation statement verification has been modernized
(#675)"tpm" attestation statements
(#673)Changes:
cross-fetch dependency has been removed from the project to silence in the
console DeprecationWarning's about a "punycode" module
(#661)startRegistration() and startAuthentication() will now warn about calls made
using the pre-v11 call structure to encourage refactoring to use the current call structure, but
still try to handle such calls the best they can
(#664)Hot on the heels of the last major release, v13 introduces support for registration hints! Refined types and improved attestation trust anchor verification are also included. Last but not least, we say goodbye to one of the project's packages for better docs and fewer dependencies to install. Read on for more information, including refactor advice for dealing with the retirement of @simplewebauthn/types.
Changes:
preferredAuthenticatorType argument can be set when calling
generateRegistrationOptions() to generate options that encourage the browser to direct the user
to register one of three types of authenticators: 'securityKey', 'localDevice', or
'remoteDevice' (a.k.a. opinionated
WebAuthn hints
support) (#653)startRegistration() will recognize hints if specified in optionsJSON
(#652)Its types will now be included directly in @simplewebauthn/browser and @simplewebauthn/server.
To refactor existing imports from /types, simply import them from /browser or /server instead:
Before:
import type {
AuthenticationResponseJSON,
RegistrationResponseJSON,
WebAuthnCredential,
} from '@simplewebauthn/types'; // <--After:
import type {
AuthenticationResponseJSON,
RegistrationResponseJSON,
WebAuthnCredential,
} from '@simplewebauthn/server'; // <--attestationType no longer accepts 'indirect'The benefits of indirect attestation are too minimal to be useful for Relying Parties. In practice
it is almost never used over ignoring the concept completely with 'none' or needing to be
intentional and setting 'direct'.
RP's that have been specifying attestationType: 'indirect' when calling
generateRegistrationOptions() will need to refactor their code to either omit
attestationType (generateRegistrationOptions() will default to attestationType: 'none') or set
attestationType: 'direct' instead:
Before:
const options = await generateRegistrationOptions({
// ...
attestationType: 'indirect',
});After:
const options = await generateRegistrationOptions({
// ...
});-or-
const options = await generateRegistrationOptions({
// ...
attestationType: 'direct',
});All SimpleWebAuthn packages are now available for installation from the JavaScript Registry (JSR)! JSR is an "open-source package registry for modern JavaScript and TypeScript" - you can read more about this new package registry and its ESM-centric capabilities here.
All packages in v12.0.0 are functionally identical to v11.0.0! And JSR package hosting is in
addition to existing package hosting on NPM. Nothing changes about package installation via
npm install. Read on for more information.
To install from JSR, use npx jsr add @simplewebauthn/... or deno add jsr:@simplewebauthn/...
depending on which package manager is available.
npm for package management:npx jsr add @simplewebauthn/browsernpx jsr add @simplewebauthn/servernpx jsr add @simplewebauthn/typesdeno for package management:deno add jsr:@simplewebauthn/browserdeno add jsr:@simplewebauthn/serverdeno add jsr:@simplewebauthn/typesv12.0.0 officially deprecates importing SimpleWebAuthn from deno.land/x. See Breaking Changes below for refactor guidance.
Importing SimpleWebAuthn packages from "https://deno.land/x/simplewebauthn/..." URLs is no longer
supported. Please use Deno's native support for JSR imports instead, available in projects running
Deno v1.42 and higher.
Before:
import { generateAuthenticationOptions } from 'https://deno.land/x/simplewebauthn/deno/server.ts';After:
import { generateAuthenticationOptions } from 'jsr:@simplewebauthn/server';Alternatively, use deno add to install these packages from
JSR:
# Deno v1.42 and higher
deno add jsr:@simplewebauthn/serverimport { generateAuthenticationOptions } from '@simplewebauthn/server';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.
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)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)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)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)uvm and dpk have been removed
(#611)startRegistration() and startAuthentication() have been replaced by a single objectProperty 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 });AuthenticatorDevice type has been renamed to WebAuthnCredentialAuthenticatorDevice.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,
});isoCrypto.verify() now has better support for signature verification with ECC
public keys using P-256, P-385, and P-521 curves
(#594, with thanks to @nlordell)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.
user.displayName now defaults to an empty string if a value is not specified for
userDisplayName when calling generateRegistrationOptions()
(#538)browserSupportsWebAuthnAutofill() helper will no longer break in environments
in which PublicKeyCredential is not present
(#557, with thanks to @clarafitzgerald)generateRegistrationOptions() now expects Base64URLString for excluded credential IDsgenerateAuthenticationOptions() now expects Base64URLString for allowed credential IDscredentialID returned from response verification methods is now a Base64URLStringAuthenticatorDevice.credentialID is now a Base64URLStringisoBase64URL.isBase64url() is now called isoBase64URL.isBase64URL()generateRegistrationOptions() now accepts an optional Uint8Array instead of a string for
userIDisoBase64URL.toString() and isoBase64URL.fromString() have been renamedgenerateRegistrationOptions() will now generate random user IDsuser.id is now treated like a base64url string in startRegistration()userHandle is now treated like a base64url string in startAuthentication()rpID is now a required argument when calling generateAuthenticationOptions()
(#555)generateRegistrationOptions() now expects Base64URLString for excluded credential IDsThe 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.
generateAuthenticationOptions() now expects Base64URLString for allowed credential IDsSimilarly, 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.
credentialID returned from response verification methods is now a Base64URLStringIt 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 });
}AuthenticatorDevice.credentialID is now a Base64URLStringCalls to verifyAuthenticationResponse() will need to be updated to encode the credential ID to a
base64url string:
Before
const verification = await verifyAuthenticationResponse({
// ...
authenticator: {
// ...
credentialID: credIDBytes,
},
});After
import { isoBase64URL } from '@simplewebauthn/server/helpers';
const verification = await verifyAuthenticationResponse({
// ...
authenticator: {
// ...
credentialID: isoBase64URL.fromBuffer(credIDBytes),
},
});isoBase64URL.isBase64url() is now called isoBase64URL.isBase64URL()Note the capitalization change from "url" to "URL" in the method name. Update calls to this method accordingly.
generateRegistrationOptions() will now generate random user IDsuser.id is now treated like a base64url string in startRegistration()userHandle is now treated like a base64url string in startAuthentication()A random identifier will now be generated when a value is not provided for the now-optional userID
argument when calling generateRegistrationOptions(). This identifier will be base64url-encoded
string of 32 random bytes. RPs that wish to take advantage of this can simply omit this
argument.
Additionally, startRegistration() will base64url-decode user.id before calling WebAuthn. During
auth startAuthentication() will base64url-encode userHandle in the returned credential. This
should be a transparent change for RP's that simply feed @simplewebauthn/server options output
into the corresponding @simplewebauthn/browser methods.
However, RP's that wish to continue generating their own user identifiers will need to take additional steps to ensure they get back user IDs in the expected format after authentication.
Before (SimpleWebAuthn v9)
// @simplewebauthn/server v9.x
const opts = generateRegistrationOptions({
// ...
userID: 'randomUserID',
});// @simplewebauthn/browser v9.x
const credential = await startAuthentication(...);
sendToServer(credential);// @simplewebauthn/server v9.x
const credential = await receiveFromBrowser();
console.log(
credential.response.userhandle, // 'randomUserID'
);After (SimpleWebAuthn v10)
// @simplewebauthn/server v10.x
import { isoUint8Array } from '@simplewebauthn/server/helpers';
const opts = generateRegistrationOptions({
// ...
userID: isoUint8Array.fromUTF8String('randomUserID'),
});// @simplewebauthn/browser v10.x
const credential = await startAuthentication(...);
sendToServer(credential);// @simplewebauthn/server v10.x
import { isoBase64URL } from '@simplewebauthn/server/helpers';
const credential = await receiveFromBrowser();
console.log(
isoBase64URL.toUTF8String(credential.response.userhandle), // 'randomUserID'
);isoBase64URL.toString() and isoBase64URL.fromString() have been renamedThe method names have been updated to reflect the use of UTF-8 string encoding:
Before:
const foo = isoBase64URL.toString('...');
const bar = isoBase64URL.fromString('...');After:
const foo = isoBase64URL.toUTF8String('...');
const bar = isoBase64URL.fromUTF8String('...');rpID is now a required argument when calling generateAuthenticationOptions()Update calls to this method to specify the same rpID as passed into
generateRegistrationOptions():
Before
generateRegistrationOptions({ rpID: 'example.com', ... });
generateAuthenticationOptions();After
generateRegistrationOptions({ rpID: 'example.com', ... });
generateAuthenticationOptions({ rpID: 'example.com' });"Cannot find module 'cbor-x/index-no-eval' or its corresponding type declarations" build errors
when transpiling TypeScript projects using @simplewebauthn/server
(#521)eval() (#511, with thanks to
@Maronato)@simplewebauthn/typescript-types package has been renamed to
@simplewebauthn/types (#508)@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/typesimport { ... } from '@simplwebauthn/types';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)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)generateRegistrationOptions() will now be
treated as UTF-8 strings to align with the existing behavior of generateAuthenticationOptions()
(#507)verifyAuthenticationResponse() (#499)globalThis.crypto first before trying to import
Node's node:crypto as a fallback (#468)deno vendor will no longer error out because typescript-types/src/dom.ts
is missing (#466)stream API
for better Web API environment compatibility
(#455, with thanks to @Maronato)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)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)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)startRegistration() will no longer error out on registration responses generated
by the 1Password browser extension (#443,
with thanks to @unix)base64URLStringToBuffer() and bufferToBase64URLString() are now
exported from @simplewebauthn/browser
(#444)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)MetadataService has been disabled
(#434)expectedChallenge argument for verifyRegistrationResponse() and
verifyAuthenticationResponse() methods now also accept asynchronous methods
(#432, with thanks to @jordanbtucker)"type": "module" in their package.json will no longer error
out when trying to use methods that leverage the Crypto APIs
(#428)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.
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.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.Packages:
Changes:
AuthenticatorAttestationResponseJSON now includes additional,
optional publicKeyAlgorithm, publicKey, and authenticatorData convenience values that track
JSON interface changes in WebAuthn L3 draft
(#400)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)"smart-card" is now a recognized value for AuthenticatorTransportFuture
(#399)Packages:
Changes:
AttestationStatement.size property declaration is now more tolerant of older
versions of TypeScriptPackages:
Changes:
Packages:
Changes:
generateRegistrationOptions() defaults to -8, -7, and -257 for supported
public key algorithms (#361)npm install @simplewebauthn/typescript-types to pull in type definitions when using these
libraries (#370)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)startAuthentication(..., true) and then
subsequently calling startAuthentication() for modal UI) will now throw an AbortError instead
of a string (#371)Packages:
Changes:
startRegistration() and startAuthentication() now pass through all
NotAllowedError's without trying to interpret what caused them
(#353)Packages:
Changes:
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:
Changes:
@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 with Uint8Arrayscose for working with COSE-related methods and typesverifyRegistrationResponse() are now a
Uint8Array instead of a Buffer. They will need to be passed into Buffer.from(...) to convert
them to Buffer if needed:aaguidauthDataclientDataHashcredentialIDcredentialPublicKeyrpIdHashverifyAuthenticationResponse() are now a
Uint8Array instead of a Buffer. They will need to be passed into Buffer.from(...) to convert
them to Buffer if needed:credentialIDisBase64URLString() helper is now isoBase64URL.isBase64url()decodeCborFirst() helper is now isoCBOR.decodeFirst()convertPublicKeyToPEM() helper has been removedRegistrationCredentialJSON type has been replaced by the RegistrationResponseJSON typeAuthenticationCredentialJSON type has been replaced by the AuthenticationResponseJSON
typeRegistrationCredentialJSON.transports has been relocated into
RegistrationResponseJSON.response.transports to mirror response structure in the WebAuthn specverifyRegistrationResponse() method has had its credential argument renamed to
responseverifyAuthenticationResponse() method has had its credential argument renamed to
responsegenerateRegistrationOptions() 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)verifyRegistrationResponse()
Before
js
const verification = await verifyRegistrationResponse({
credential: attestationFIDOU2F,
// ...
});
After
js
const verification = await verifyRegistrationResponse({
credential: attestationFIDOU2F,
// ...
requireUserVerification: false,
});
### verifyAuthenticationResponse()
Before
js
const verification = await verifyAuthenticationResponse({
credential: assertionResponse,
// ...
});
After
js
const verification = await verifyAuthenticationResponse({
credential: assertionResponse,
// ...
requireUserVerification: false,
});
generateRegistrationOptions() now defaults to preferring the creation of
discoverable credentials. See below for refactor tips
(#324)generateRegistrationOptions() accordingly:
### generateRegistrationOptions()
Before
js
const options = generateRegistrationOptions({
rpName: 'SimpleWebAuthn',
rpID: 'simplewebauthn.dev',
userID: '1234',
userName: 'usernameHere',
});
After
js
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',
},
});
Packages:
Changes:
browserSupportsWebAuthnAutofill() no longer supports the old Chrome Canary way of
testing for conditional UI support (#298)Packages:
Changes:
startRegistration() and startAuthentication() will now more
reliably cancel the preceding call (#275)Packages:
Changes:
verifyAuthenticationResponse() as authenticationInfo.userVerified, similar to how
verifyRegistrationResponse() currently returns this value
(#263)Packages:
Changes:
This release also marks the return of the library's ability to pass FIDO Conformance! Adding Ed25519 signature verification (see below) finally allowed the library to pass all required tests, and nearly all optional tests.
Packages:
Changes:
verifyAuthenticationResponse() now returns
Promise<VerifiedAuthenticationResponse> instead of VerifiedAuthenticationResponse
(#256)Update your existing calls to verifyAuthenticationResponse() to handle the values resolved by the
promises, whether with .then() or await depending on your code structure:
Before:
const verification = verifyAuthenticationResponse({
// ...
});After:
const verification = await verifyAuthenticationResponse({
// ...
});browserSupportsWebauthn() has been renamed to browserSupportsWebAuthn()
(#257)Update calls to browserSupportsWebauthn() to capitalize the "A" in "WebAuthn":
Before:
if (browserSupportsWebauthn()) {
// ...
}After:
if (browserSupportsWebAuthn()) {
// ...
}Packages:
Changes:
To leverage these requirements (as might be the case for RP's seeking FIDO certification), update
your calls to verifyAuthenticationResponse() to replace requireUserVerification with the new
advancedFIDOConfig.userVerification option:
Before:
const verification = verifyAuthenticationResponse({
// ...
requireUserVerification: true,
});After
const verification = verifyAuthenticationResponse({
// ...
advancedFIDOConfig: {
// UserVerificationRequirement: 'required' | 'preferred' | 'discouraged'
userVerification: 'required',
},
});Setting advancedFIDOConfig.userVerification to 'required' will only require the uv flag to be
true; up flag may be false. Setting it to 'preferred' or 'discouraged' will allow both up
and uv to be false during verification.
devicePublicKey property on the
AuthenticationExtensionsAuthenticatorOutputs type to devicePubKey
(#243; no one supports this yet so it's
not a breaking change)Packages:
Changes:
Packages:
Changes:
"rsa_emsa_pkcs1_sha256_raw", "rsa_emsa_pkcs1_sha256_der", "sm2_sm3_raw"
(#245)Packages:
Changes:
"rsa_emsa_pkcs1_sha256_raw" and "rsa_emsa_pkcs1_sha256_der"
authentication algorithms in FIDO MDS metadata statements
(#241)Packages:
Changes:
"type": "module" has been added to package.json to appease modern front end
tooling that expects this value to be present when using the ESM build
(#237)Packages:
Changes:
verifyRegistrationResponse() and verifyAuthenticationResponse() now return
authenticator extension data upon successful verification as the new
authenticatorExtensionResults property
(#230)Packages:
Changes:
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)startRegistration() and startAuthentication() will return a new
authenticatorAttachment value when present that captures whether a cross-platform or platform
authenticator was just used (#221)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)"hybrid" transport has been added to AuthenticatorTransportFuture
while browsers migrate away from the existing "cable" transport for cross-device auth
(#222)Packages:
Changes:
generateRegistrationOptions() and generateAuthenticationOptions() will stop
reporting typing errors for definitions of excludeCredentials and allowCredentials that were
otherwise fine before v5.2.0 (#203)AuthenticatorTransportFuture and
PublicKeyCredentialDescriptorFuture have been added to track changes to WebAuthn that outpace
TypeScript's DOM lib typingsPackages:
Changes:
"cable" transport is now recognized as a potential value
of the AuthenticatorTransport type
(#198)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)Packages:
Changes:
startRegistration() and startAuthentication()
will now have the same name property as the original error
(#191)Packages:
Changes:
startRegistration() and
startAuthentication() will now return descriptions with more specific insights into what went
wrong (#184)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,
});Packages:
Changes:
"android-safetynet" responses has
been removedverifyAuthenticationResponse()'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).Packages:
Changes:
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'Packages:
Changes:
DEBUG=SimpleWebAuthn:*The following logging scopes are defined in this release:
SimpleWebAuthn:MetadataServiceSee PR #159 for a preview of logging output.
Packages:
Changes:
platformAuthenticatorIsAvailable() now checks that WebAuthn is supported at all
before attempting to query for the status of an available platform authenticator.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.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:
Changes:
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.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.'android-key', 'android-safetynet', 'apple''@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.MetadataService now supports
FIDO Alliance Metadata Service version 3.0.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->GenerateRegistrationOptionsOptsverifyAssertionResponse()->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.
opts argument for MetadataService.initialize() is now optional.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.
supportsWebAuthn() has been renamed to browserSupportsWebAuthn() in an
effort to make the method convey a clearer idea of what supports WebAuthn.Packages:
Changes:
tslib dependency for
production is no longer necessary as transpilation to ES5 is now fully the responsibility of the
framework implementing @simplewebauthn/browser.This release is focused on updating @simplewebauthn/browser for better browser support out of the box. Most projects will now pull in its (slightly larger) ES5 bundle to ensure maximum browser compatibility, including older browsers in which WebAuthn will never be available. The ES2018 build is still available for projects that only need to target newer browsers, but bundler configuration changes must now be made to include it instead of the ES5 build.
Packages:
Changes:
startAssertion() no longer Base64URL-encodes userHandle stringjsrsasign to 10.2.0 (see
GHSA-27fj-mc8w-j9wg)startAssertion() fixresponse.userHandle as returned from startAssertion().Packages:
Changes:
Packages:
Changes:
// Newly exported types
import type {
GenerateAssertionOptionsOpts,
GenerateAttestationOptionsOpts,
VerifiedAssertion,
VerifiedAttestation,
VerifyAssertionResponseOpts,
VerifyAttestationResponseOpts,
} from '@simplewebauthn/server';Packages:
Changes:
startAttestation() and startAssertion() now include extension results as
clientExtensionResults in their return valuePublicKeyCredentialCreationOptionsJSON and
PublicKeyCredentialRequestOptionsJSON types with new optional extensions property to
support specifying WebAuthn extensions when calling generateAttestationOptions() and
generateAssertionOptions()AttestationCredentialJSON and AssertionCredentialJSON
types with new clientExtensionResults properties to contain output from WebAuthn's
credential.getClientExtensionResults()This major release includes improvements intended to make it easier to support passwordless and usernameless WebAuthn flows. Additional information returned from attestation verification can be used by RP's to further scrutinize the attestation now or in the future.
I also made the decision to reduce the amount of encoding from Buffer to Base64URL and decoding from Base64URL to Buffer throughout the library. Verification methods now return raw Buffers so that RP's are free to store and retrieve these values as they see fit without the library imposing any kind of encoding overhead that may complicate storage in a database, etc...
Packages:
Changes:
verifyAttestationResponse() now returns a different data structure
with additional information that RP's can use to more easily support passwordless and usernameless
WebAuthn flows.Buffer values are now returned in place of previously-base64url-encoded values.
This is intended to offer more flexibility in how these values are persisted without imposing an
encoding scheme that may introduce undesirable overhead.Before:
type VerifiedAttestation = {
verified: boolean;
userVerified: boolean;
authenticatorInfo?: {
fmt: ATTESTATION_FORMAT;
counter: number;
base64PublicKey: string;
base64CredentialID: string;
};
};After:
type VerifiedAttestation = {
verified: boolean;
attestationInfo?: {
fmt: ATTESTATION_FORMAT;
counter: number;
aaguid: string;
credentialPublicKey: Buffer;
credentialID: Buffer;
credentialType: string;
userVerified: boolean;
attestationObject: Buffer;
};
};verifyAssertionResponse() now returns a different data structure to
align with changes made to verifyAttestationResponse().Before:
type VerifiedAssertion = {
verified: boolean;
authenticatorInfo: {
counter: number;
base64CredentialID: string;
};
};After:
type VerifiedAssertion = {
verified: boolean;
assertionInfo: {
credentialID: Buffer;
newCounter: number;
};
};excludeCredentials argument in generateAttestationOptions() now expects a
Buffer type for a credential's id property. Previously id needed to be a string. Existing
credential IDs stored in base64url encoding can be easily converted to Buffer with a library like
base64url:Before:
const options = generateAttestationOptions({
// ...
excludeCredentials: [{
id: 'PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o',
// ...
}],
// ...
});After:
const options = generateAttestationOptions({
// ...
excludeCredentials: [{
id: base64url.toBuffer('PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o'),
// ...
}],
// ...
});allowCredentials argument in generateAssertionOptions() now expects a
Buffer type for a credential's id property. Previously id needed to be a string. Existing
credential IDs stored in base64url encoding can be easily converted to Buffer with a library like
base64url:Before:
const options = generateAssertionOptions({
// ...
allowCredentials: [{
id: 'PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o',
// ...
}],
// ...
});After:
const options = generateAssertionOptions({
// ...
allowCredentials: [{
id: base64url.toBuffer('PPa1spYTB680cQq5q6qBtFuPLLdG1FQ73EastkT8n0o'),
// ...
}],
// ...
});AuthenticatorDevice type has been updated to expect Buffer's for
credential data. Naming of its properties have also been updated to help maintain consistency with
naming in the WebAuthn spec:Before:
type AuthenticatorDevice = {
publicKey: Base64URLString;
credentialID: Base64URLString;
counter: number;
transports?: AuthenticatorTransport[];
};After:
type AuthenticatorDevice = {
credentialPublicKey: Buffer;
credentialID: Buffer;
counter: number;
transports?: AuthenticatorTransport[];
};Packages:
Changes:
verifyAttestationResponse()
and verifyAssertionResponse()generateAttestationOptions() to force legacy
authenticatorSelection.requireResidentKey to true when authenticatorSelection.residentKey is
"required" (as per L2 of the WebAuthn spec)AuthenticatorDevice type with optional transports propertyThere are no breaking changes in this release. Several recent minor changes presented an opportunity to release a "v1.0". I'd received enough positive feedback about SimpleWebAuthn and noticed growing usage which granted me the confidence to take advantage of this opportunity.
And perhaps this will give the project more legitimacy in the eyes of larger organizations wishing to use it but waiting for the libraries to "get out of beta"...
Packages:
Changes:
toUint8Array() for easier testing when integratedPackages:
Changes:
allowCredentials in generateAssertionOptions() optionalgenerateAssertionOptions() without any optionsallowCredentials before starting assertionPackages:
Changes:
Packages:
Changes:
rpID argument to generateAssertionOptions()Packages:
Changes:
Packages:
Changes:
Packages:
Changes:
allowCredentials and
excludeCredentialstransports in response from
startAttestation()AuthenticatorAttestationResponseFuture type for better typing of
credential response methods (getTransports(), getAuthenticatorData(), etc...)generateAttestationOptions() and
generateAssertionOptions() must be updated to specify credentials with their own transports:generateAttestationOptions()
// OLD
const options = generateAttestationOptions({
excludedCredentialIDs: devices.map((dev) => dev.credentialID),
suggestedTransports: ['usb', 'ble', 'nfc', 'internal'],
});
// NEW
const options = generateAttestationOptions({
excludeCredentials: devices.map((dev) => ({
id: dev.credentialID,
type: 'public-key',
transports: dev.transports,
})),
});generateAssertionOptions()
// OLD
const options = generateAssertionOptions({
allowedCredentialIDs: user.devices.map((dev) => dev.credentialID),
suggestedTransports: ['usb', 'ble', 'nfc', 'internal'],
});
// NEW
const options = generateAssertionOptions({
allowCredentials: devices.map((dev) => ({
id: dev.credentialID,
type: 'public-key',
transports: dev.transports,
})),
});Packages:
Changes:
Packages:
Changes:
authenticatorInfo.base64PublicKey returned by verifyAttestationResponse() is now
the entire public key buffer instead of a pared down form of it (it's still returned
base64url-encoded). This helps ensure support for existing public keys, as well as future public
key formats that may be introduced in the future. Public keys previously returned by this method
must be upgraded via
this "upgrader" script to
work with future assertions.serviceName argument for generateAttestationOptions() has been renamed to
rpName. This brings it in line with the existing rpID argument and maps more obviously to its
respective property within the returned options.Packages:
Changes:
authenticatorSelection in return value from
generateAttestationOptions() for enhanced device compatibility.Packages:
Changes:
supportedAlgorithmIDs when calling
generateAttestationOptions()Packages:
Changes:
challenge parameter of generateAttestationOptions() and
generateAssertionOptions() is now optional.startAttestation() and startAssertion() now convert the base64url-encoded
options.challenge to a buffer before passing it to the authenticator.verifyAttestationResponse() and verifyAssertionResponse() now require the
base64url-encoded challenge to be passed in as expectedChallenge:Before:
const challenge = 'someChallenge';
const opts = generateAttestationOptions({
...atteOpts,
challenge,
});
const verification = verifyAttestationResponse({
...atteResp,
// Raw original value
expectedChallenge: challenge,
});After:
const challenge = 'someChallenge';
const opts = generateAttestationOptions({
...atteOpts,
// This is now optional
challenge,
});
const verification = verifyAttestationResponse({
...atteResp,
// Now expected to be the base64url-encoded `challenge` returned
// by `generateAttestationOptions()`
expectedChallenge: opts.challenge,
});Packages:
Changes:
Packages:
Changes:
Packages:
Changes:
generateAttestationOptions() and verifyAttestationResponse()Packages:
Changes:
Packages:
Changes:
verifyAttestationResponse() changed from boolean to
Promise<boolean>. This was necessary to support querying FIDO MDS for an authenticator metadata
statement during attestation verification.requireUserVerification parameter of verifyAssertionResponse() has
been replaced with the new optional fidoUserVerification parameter. This enables greater control
over user verification when verifying assertions.Packages:
Changes:
verifyAttestationResponse() options param description.Packages:
Changes:
verifyAttestationResponse() and verifyAssertionResponse()
methods now take a single arguments object.requireUserVerification argument.Packages:
Changes:
AuthenticatorAttestationResponseJSON and
AuthenticatorAssertionResponseJSONPackages:
Changes:
startAttestation() and startAssertion() to return more of
the output from the navigator.credentials callsbase64-js dependency with internal functionalitygenerateAttestationOptions() and
generateAssertionOptions() by renaming the excludedBase64CredentialIDs and
allowedBase64CredentialIDs to excludedCredentialIDs and allowedCredentialIDs respectively