SimpleWebAuthn

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

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)

Packages:

• @simplewebauthn/[email protected]

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+

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Improved signature verification of the latest FIDO MDS JWTs (#390)

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

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)

Packages:

• @simplewebauthn/[email protected]

Changes:

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

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

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

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/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

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)

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)

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:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] browserSupportsWebAuthnAutofill() no longer supports the old Chrome Canary way of testing for conditional UI support (#298)
• [server] Version sync

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] Multiple calls to startRegistration() and startAuthentication() will now more reliably cancel the preceding call (#275)
• [server] Version sync
• [testing] Version sync
• [typescript-types] Version sync

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] The value of the user verification flag is now returned from verifyAuthenticationResponse() as authenticationInfo.userVerified, similar to how verifyRegistrationResponse() currently returns this value.

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Improve support for requiring resident keys when targeting WebAuthn L1 (#259)
• [server] Encourage authenticators to produce Ed25519 credential keypairs when supported (#261)

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:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [server] Signatures can now be verified with OKP public keys that use the Ed25519 curve and EDDSA algorithm (#256)
• [testing] Version sync
• [typescript-types] Version sync

Breaking Changes

• [server] 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({
  // ...
});

• [browser] browserSupportsWebauthn() has been renamed to browserSupportsWebAuthn() (#257)

Update calls to browserSupportsWebauthn() to capitalize the "A" in "WebAuthn":

Before:

if (browserSupportsWebauthn()) {
  // ...
}

After:

if (browserSupportsWebAuthn()) {
  // ...
}

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Support FIDO Conformance user verification requirements (#254)

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.

• [server] Rename the devicePublicKey property on the AuthenticationExtensionsAuthenticatorOutputs type to devicePubKey (#243; no one supports this yet so it's not a breaking change)

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Enhance compliance with current FIDO conformance requirements (#249, #251)
• [server] Minor performance improvements (#150)

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Remove support for the following defunct FIDO metadata authentication algorithms: "rsa_emsa_pkcs1_sha256_raw", "rsa_emsa_pkcs1_sha256_der", "sm2_sm3_raw" (#245)
• [server] Update remaining FIDO metadata constants to match v2.2 of the FIDO Registry of Predefined Values (#244)

Packages:

• @simplewebauthn/[email protected]

Changes:

• [server] Add support for "rsa_emsa_pkcs1_sha256_raw" and "rsa_emsa_pkcs1_sha256_der" authentication algorithms in FIDO MDS metadata statements (#241)

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] "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)
• [server] TPM attestation statement verification now properly verifies statements with ECC public area type (#239)

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [server] verifyRegistrationResponse() and verifyAuthenticationResponse() now return authenticator extension data upon successful verification as the new authenticatorExtensionResults property (#230)
• [browser] Code quality improvements
• [typescript-types] Code quality improvements

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [browser] 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)
• [browser] startRegistration() and startAuthentication() will return a new authenticatorAttachment value when present that captures whether a cross-platform or platform authenticator was just used (#221)
• [typescript-types] A new 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)
• [typescript-types] A new "hybrid" transport has been added to AuthenticatorTransportFuture while browsers migrate away from the existing "cable" transport for cross-device auth (#222)

Packages:

• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]
• @simplewebauthn/[email protected]

Changes:

• [server] generateRegistrationOptions() and generateAuthenticationOptions() will stop reporting typing errors for definitions of excludeCredentials and allowCredentials that were otherwise fine before v5.2.0 (#203)
• [typescript-types] The new AuthenticatorTransportFuture and PublicKeyCredentialDescriptorFuture have been added to track changes to WebAuthn that outpace TypeScript's DOM lib typings
• [browser] Version sync