WebAuthn, Simplified. A collection of TypeScript-first libraries for simpler WebAuthn integration. Supports modern browsers, Node, Deno, and more.
MIT License
Bot releases are visible (Hide)
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:
Published by MasterKale almost 2 years ago
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 Uint8Array
scose
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:
aaguid
authData
clientDataHash
credentialID
credentialPublicKey
rpIdHash
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
isBase64URLString()
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 response
verifyAuthenticationResponse()
method has had its credential
argument renamed to response
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)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,
});
generateRegistrationOptions()
now defaults to preferring the creation of discoverable credentials. See below for refactor tips (#324)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',
},
});
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.Published by MasterKale about 2 years ago
This release 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:
"rsa_emsa_pkcs1_sha256_raw"
and "rsa_emsa_pkcs1_sha256_der"
authentication algorithms in FIDO MDS metadata statements (#241)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 typings