CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Changed

• Use @metamask/utils SHA-256, SHA-384, and SHA-512 digests for asynchronous WebAuthn verification and RP ID matching, while retaining Noble SHA-256 for synchronous HKDF (#10188)
• Bump @metamask/utils from ^11.12.0 to ^12.0.0 (#10192)

4.0.0

Changed

• BREAKING: Drop CommonJS support (#9536)
  • This package is now ESM-only, but can still be used in CommonJS projects via require(esm) in modern Node.js versions (22+), or dynamic imports in older Node.js versions.
• BREAKING: Bump minimum Node.js version to 22 (#9976)
• BREAKING: Bump TypeScript target to ES2022 (#10019)
  • This package now ships ES2022 code, requiring a compatible modern environment or bundler configuration to consume.
• Bump @metamask/utils from ^11.11.0 to ^11.12.0 (#10076)
• Bump @metamask/base-controller from ^9.1.0 to ^10.0.0 (#10160)
• Bump @metamask/keyring-controller from ^27.1.1 to ^28.0.0 (#10160)
• Bump @metamask/messenger from ^2.0.0 to ^3.0.0 (#10160)

3.1.0

Added

• Added new util, getAAGUIDFromRegistrationResponse to read the authenticator AAGUID from a navigator.credentials.create() result. (#9951)

Changed

• Bump @metamask/keyring-controller from ^27.1.0 to ^27.1.1 (#9791)

3.0.0

Added

• Orchestrated passkey product flows on PasskeyController and their messenger actions. (#9548)
  • unlockWithPasskey
  • removePasskeyWithPasskeyVerification
  • removePasskeyWithPasswordVerification
  • changePasswordWithPasskeyVerification
  • exportSeedPhraseWithPasskey
  • exportAccountsWithPasskey
• PasskeyControllerOptions with required getIsOnboardingCompleted constructor callback for enrollment step-up gating. (#9548)
• Added new error constants, PasskeyControllerErrorCode.VaultKeyRenewalFailed, PasskeyControllerErrorCode.EnrollmentPasswordRequired, PasskeyControllerErrorMessage.VaultKeyRenewalFailed and PasskeyControllerErrorMessage.EnrollmentPasswordRequired. (#9548)
• @metamask/keyring-controller dependency for KeyringController messenger action types used during orchestration. (#9548)

Changed

• BREAKING: protectVaultKeyWithPasskey no longer accepts vaultKey; the controller fetches the current encryption key via KeyringController:exportEncryptionKey and optionally verifies the wallet password when onboarding is complete. ((#9548))
• BREAKING: PasskeyController constructor requires getIsOnboardingCompleted. ((#9548))
• BREAKING: removePasskey and PasskeyController:removePasskey are no longer public; use removePasskeyWithPasskeyVerification, removePasskeyWithPasswordVerification, or clearState. (#9548)
• PasskeyControllerMessenger may call a fixed set of KeyringController actions during orchestrated flows (#9548)
• Orchestrated async passkey operations are serialized with an internal mutex to prevent concurrent vault/keyring races. (#9548)

2.1.0

Added

• Expose public PasskeyController methods through its messenger (#9515)
  • The following actions are now available:
    • PasskeyController:isPasskeyEnrolled
    • PasskeyController:generateRegistrationOptions
    • PasskeyController:verifyRegistrationResponse
    • PasskeyController:generatePostRegistrationAuthenticationOptions
    • PasskeyController:generateAuthenticationOptions
    • PasskeyController:verifyAuthenticationResponse
    • PasskeyController:protectVaultKeyWithPasskey
    • PasskeyController:retrieveVaultKeyWithPasskey
    • PasskeyController:verifyPasskeyAuthentication
    • PasskeyController:renewVaultKeyProtection
    • PasskeyController:removePasskey
    • PasskeyController:clearState
    • PasskeyController:destroy
  • Corresponding action types (e.g. PasskeyControllerIsPasskeyEnrolledAction) are available as well.

Changed

• Bump @metamask/utils from ^11.9.0 to ^11.11.0 (#9074)
• Bump @metamask/messenger from ^1.2.0 to ^2.0.0 (#9392)

2.0.1

Changed

• PasskeyController verifies registration and authentication responses with requireUserVerification: true, so the WebAuthn user verification (UV) flag must be set; assertions with user presence only no longer pass verification (#8696)

Fixed

• generateAuthenticationOptions now sets userVerification: 'required' so client WebAuthn requests align with server-side verification requirements and do not fail on authenticators that skip UV when set to 'preferred' (#8696)

2.0.0

Added

• generatePostRegistrationAuthenticationOptions to issue navigator.credentials.get() options after navigator.credentials.create(), keyed to the in-flight registration ceremony (including PRF eval when a salt was used) (#8663)
• already_enrolled (PasskeyControllerErrorCode.AlreadyEnrolled) when calling protectVaultKeyWithPasskey while a passkey is already enrolled (#8663)

Changed

• BREAKING: Enrollment completes in three steps: generateRegistrationOptions → create() → generatePostRegistrationAuthenticationOptions → get() → protectVaultKeyWithPasskey; protectVaultKeyWithPasskey now requires authenticationResponse, and the vault wrapping key is derived from that post-registration assertion (same path as unlock: PRF when present, otherwise userHandle) (#8663)
• BREAKING: PasskeyController constructor option rpID is replaced with expectedRPID: string | string[] (normalized to a string array, which may be empty). Optional rpId sets rp.id / rpId in generated WebAuthn options; when omitted, those fields are omitted. Verification passes that array to verifyRegistrationResponse / verifyAuthenticationResponse as expectedRPIDs (#8663)
• BREAKING: verifyRegistrationResponse and verifyAuthenticationResponse now take expectedRPIDs: string[] instead of expectedRPID: string (#8663)
• verifyRegistrationResponse / verifyAuthenticationResponse accept an empty expectedRPIDs array to skip RP ID hash allowlist matching; successful authentication then reports authenticationInfo.rpID as an empty string (#8663)
• Increase CEREMONY_TTL_SLACK_MS to 2 minutes so in-flight ceremony state (CEREMONY_MAX_AGE_MS, 3 minutes including WebAuthn timeout) tolerates longer gaps between WebAuthn options and completion (e.g. post-registration authentication) (#8663)
• Bump @metamask/messenger from ^1.1.1 to ^1.2.0 (#8632)

Fixed

• protectVaultKeyWithPasskey rejects post-registration assertions whose userHandle is missing or does not match the in-flight registration ceremony when using userHandle key derivation (assertion userHandle is not signature-bound) (#8663)

1.0.0

Added

• Initial @metamask/passkey-controller: PasskeyController for WebAuthn passkey vault key protection (HKDF-derived keys, AES-256-GCM wrap/unwrap), PRF or userHandle derivation, challenge-keyed CeremonyManager, enrollment/unlock/renewal flows, verifyPasskeyAuthentication, selectors, and exported ceremony timing constants. (#8422)
• PasskeyControllerError with stable code, optional cause / context, toJSON, and toString; PasskeyControllerErrorCode, PasskeyControllerErrorMessage, and controllerName. Replaces PasskeyAuthenticationRejectedError—use PasskeyControllerError and code for auth failures.
• BREAKING: Operational error messages are prefixed with PasskeyController - ; prefer code or instanceof PasskeyControllerError over matching raw strings.
• renewVaultKeyProtection uses the same vault_key_decryption_failed code as retrieveVaultKeyWithPasskey when AES-GCM decrypt fails.
• Thrown failures from verifyRegistrationResponse / verifyAuthenticationResponse are wrapped in PasskeyControllerError with registration_verification_failed / authentication_verification_failed and the underlying error as cause (aligned with the verified: false path).
• Debug logging (via @metamask/utils) for registration/authentication verification failures, missing ceremony state, vault decrypt failures, and vault key mismatch during renewal.

Fixed

• Registration verification requires the credential id/rawId to match the credential id in authenticator data; vault wrapping key derivation uses that verified credential id so enrollment keys align with the stored credential.
• Registration options request attestation conveyance 'none' so clients are not asked for direct attestation formats the verifier does not implement (none and self-attested packed only).