@metamask/passkey-controller 3.1.0 → 4.1.0

package/dist/PasskeyController.js

@@ -0,0 +1,828 @@
+import { BaseController } from '@metamask/base-controller';
+import { areUint8ArraysEqual, stringToBytes } from '@metamask/utils';
+import { Mutex } from 'async-mutex';
+import { WEBAUTHN_TIMEOUT_MS, CeremonyManager } from './ceremony-manager.js';
+import { controllerName, PasskeyControllerErrorCode, PasskeyControllerErrorMessage, } from './constants.js';
+import { PasskeyControllerError } from './errors.js';
+import { deriveKeyFromAuthenticationResponse } from './key-derivation.js';
+import { createModuleLogger, projectLogger } from './logger.js';
+import { decryptWithKey, encryptWithKey, randomBytesToBase64URL, } from './utils/crypto.js';
+import { base64URLToBytes, bytesToBase64URL } from './utils/encoding.js';
+import { COSEALG } from './webauthn/constants.js';
+import { decodeClientDataJSON } from './webauthn/decode-client-data-json.js';
+import { verifyAuthenticationResponse } from './webauthn/verify-authentication-response.js';
+import { verifyRegistrationResponse } from './webauthn/verify-registration-response.js';
+/**
+ * Returns the default (empty) state for {@link PasskeyController}.
+ *
+ * @returns A fresh state object with no enrolled passkey.
+ */
+export function getDefaultPasskeyControllerState() {
+    return { passkeyRecord: null };
+}
+const passkeyControllerMetadata = {
+    passkeyRecord: {
+        persist: true,
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        usedInUi: true,
+    },
+};
+const log = createModuleLogger(projectLogger, controllerName);
+/**
+ * Selectors for {@link PasskeyControllerState}.
+ *
+ * Use these instead of dedicated getter methods on the controller, so that
+ * derived values can be consumed from Redux selectors and other places that
+ * only have access to a state object.
+ */
+export const passkeyControllerSelectors = {
+    selectIsPasskeyEnrolled: (state) => state.passkeyRecord !== null,
+};
+const MESSENGER_EXPOSED_METHODS = [
+    'isPasskeyEnrolled',
+    'generateRegistrationOptions',
+    'generatePasskeyReplacementRegistrationOptions',
+    'completePasskeyReplacement',
+    'cancelPasskeyReplacement',
+    'generatePostRegistrationAuthenticationOptions',
+    'generateAuthenticationOptions',
+    'protectVaultKeyWithPasskey',
+    'retrieveVaultKeyWithPasskey',
+    'unlockWithPasskey',
+    'verifyPasskeyAuthentication',
+    'renewVaultKeyProtection',
+    'changePasswordWithPasskeyVerification',
+    'exportSeedPhraseWithPasskey',
+    'exportAccountsWithPasskey',
+    'removePasskeyWithPasskeyVerification',
+    'removePasskeyWithPasswordVerification',
+    'clearState',
+    'destroy',
+];
+/**
+ * Controller that enrolls a WebAuthn passkey and uses it to protect and unlock
+ * the vault encryption key.
+ */
+export class PasskeyController extends BaseController {
+    #ceremonyManager = new CeremonyManager();
+    #expectedRPIDs;
+    #rpId;
+    #rpName;
+    #expectedOrigin;
+    #userName;
+    #userDisplayName;
+    #getIsOnboardingCompleted;
+    #operationMutex = new Mutex();
+    /**
+     * Creates a passkey controller with WebAuthn relying-party settings.
+     *
+     * @param options - Constructor options.
+     * @param options.messenger - The messenger to use for communication.
+     * @param options.state - The initial state of the controller.
+     * @param options.rpId - The relying party ID to use for the passkey.
+     * @param options.expectedRPID - The expected relying party ID to use for the passkey.
+     * @param options.rpName - The relying party name to use for the passkey.
+     * @param options.expectedOrigin - The expected origin to use for the passkey.
+     * @param options.userName - The user name to use for the passkey.
+     * @param options.userDisplayName - The user display name to use for the passkey.
+     * @param options.getIsOnboardingCompleted - The callback to use to check if onboarding is complete.
+     */
+    constructor({ messenger, state = {}, rpId, expectedRPID, rpName, expectedOrigin, userName, userDisplayName, getIsOnboardingCompleted, }) {
+        super({
+            messenger,
+            metadata: passkeyControllerMetadata,
+            name: controllerName,
+            state: { ...getDefaultPasskeyControllerState(), ...state },
+        });
+        const expectedRPIDs = Array.isArray(expectedRPID)
+            ? expectedRPID
+            : [expectedRPID];
+        this.#expectedRPIDs = [...expectedRPIDs];
+        this.#rpId = rpId;
+        this.#rpName = rpName;
+        this.#expectedOrigin = expectedOrigin;
+        this.#userName = userName ?? rpName;
+        this.#userDisplayName = userDisplayName ?? rpName;
+        this.#getIsOnboardingCompleted = getIsOnboardingCompleted;
+        this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * Whether a passkey is enrolled and vault key material is stored.
+     *
+     * @returns `true` if enrolled, otherwise `false`.
+     */
+    isPasskeyEnrolled() {
+        return passkeyControllerSelectors.selectIsPasskeyEnrolled(this.state);
+    }
+    /**
+     * Builds WebAuthn credential creation options for passkey enrollment.
+     *
+     * @param creationOptionsConfig - Optional creation behavior.
+     * @param creationOptionsConfig.prfAvailable - Request the PRF extension unless `false`. Defaults to `true`.
+     * @returns Public key credential creation options for `navigator.credentials.create()`.
+     */
+    generateRegistrationOptions(creationOptionsConfig) {
+        return this.#generateRegistrationOptions({
+            includePrf: creationOptionsConfig?.prfAvailable !== false,
+        });
+    }
+    /**
+     * Builds WebAuthn credential creation options for replacing a userHandle
+     * passkey with a PRF-capable passkey.
+     *
+     * The existing passkey record is retained while the replacement ceremony is
+     * in flight.
+     *
+     * @returns Public key credential creation options for `navigator.credentials.create()`.
+     */
+    generatePasskeyReplacementRegistrationOptions() {
+        const record = this.#requireEnrolled();
+        if (record.keyDerivation.method !== 'userHandle') {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.MigrationNotRequired, { code: PasskeyControllerErrorCode.MigrationNotRequired });
+        }
+        const excludeCredential = {
+            id: record.credential.id,
+            type: 'public-key',
+            ...(record.credential.transports
+                ? { transports: record.credential.transports }
+                : {}),
+        };
+        return this.#generateRegistrationOptions({
+            excludeCredentials: [excludeCredential],
+            includePrf: true,
+            isReplacement: true,
+            sourceCredentialId: record.credential.id,
+        });
+    }
+    #generateRegistrationOptions({ excludeCredentials, includePrf, isReplacement = false, sourceCredentialId, }) {
+        if (!isReplacement && this.isPasskeyEnrolled()) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.AlreadyEnrolled, { code: PasskeyControllerErrorCode.AlreadyEnrolled });
+        }
+        const prfSalt = includePrf ? randomBytesToBase64URL(32) : undefined;
+        const userHandle = randomBytesToBase64URL(64);
+        const challenge = randomBytesToBase64URL(32);
+        const extensions = {};
+        if (prfSalt) {
+            extensions.prf = { eval: { first: prfSalt } };
+        }
+        const options = {
+            rp: {
+                name: this.#rpName,
+                id: this.#rpId,
+            },
+            user: {
+                id: userHandle,
+                name: this.#userName,
+                displayName: this.#userDisplayName,
+            },
+            challenge,
+            pubKeyCredParams: [
+                { alg: COSEALG.EdDSA, type: 'public-key' },
+                { alg: COSEALG.ES256, type: 'public-key' },
+                { alg: COSEALG.RS256, type: 'public-key' },
+            ],
+            timeout: WEBAUTHN_TIMEOUT_MS,
+            authenticatorSelection: {
+                userVerification: 'required',
+                authenticatorAttachment: 'platform',
+                residentKey: 'preferred',
+            },
+            hints: ['client-device', 'hybrid'],
+            attestation: 'none',
+            ...(excludeCredentials ? { excludeCredentials } : {}),
+            ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
+        };
+        this.#ceremonyManager.saveRegistrationCeremony(challenge, {
+            userHandle,
+            prfSalt,
+            challenge,
+            createdAt: Date.now(),
+            ...(isReplacement ? { isReplacement: true, sourceCredentialId } : {}),
+        });
+        return options;
+    }
+    /**
+     * Verifies and completes replacement of an enrolled userHandle passkey with
+     * a PRF-capable passkey.
+     *
+     * The existing passkey record remains active until the replacement
+     * registration and post-registration authentication have both been verified
+     * and the existing vault key has been wrapped with the new PRF-derived key.
+     *
+     * @param params - Replacement completion inputs.
+     * @param params.registrationResponse - Result of `navigator.credentials.create()`.
+     * @param params.authenticationResponse - Result of `navigator.credentials.get()`
+     *   after {@link generatePostRegistrationAuthenticationOptions}.
+     * @returns Resolves when the replacement completes.
+     */
+    async completePasskeyReplacement(params) {
+        return this.#withOperationLock(() => this.#completePasskeyReplacement(params));
+    }
+    async #completePasskeyReplacement(params) {
+        const sourceRecord = this.#requireEnrolled();
+        if (sourceRecord.keyDerivation.method !== 'userHandle') {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.MigrationNotRequired, { code: PasskeyControllerErrorCode.MigrationNotRequired });
+        }
+        const { challenge: registrationChallenge, ceremony: registrationCeremony } = this.#getRegistrationCeremony(params.registrationResponse);
+        if (!registrationCeremony?.isReplacement) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.NoRegistrationCeremony, { code: PasskeyControllerErrorCode.NoRegistrationCeremony });
+        }
+        if (registrationCeremony.sourceCredentialId !== sourceRecord.credential.id) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.ReplacementSourceChanged, { code: PasskeyControllerErrorCode.ReplacementSourceChanged });
+        }
+        // Migration should only run when keyring is unlocked.
+        // this will throw an error if the keyring is locked.
+        const vaultKey = await this.messenger.call('KeyringController:exportEncryptionKey');
+        try {
+            const credential = await this.#verifyRegistrationResponse(params.registrationResponse, registrationCeremony);
+            if (credential.id === sourceRecord.credential.id) {
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.RegistrationVerificationFailed, { code: PasskeyControllerErrorCode.RegistrationVerificationFailed });
+            }
+            const { newCounter } = await this.#verifyAuthenticationResponse(params.authenticationResponse, credential);
+            const keyDerivation = this.#getKeyDerivation(params.authenticationResponse, registrationCeremony, { requirePrf: true });
+            const replacementRecord = this.#createPasskeyRecord({
+                vaultKey,
+                authenticationResponse: params.authenticationResponse,
+                credential,
+                newCounter,
+                keyDerivation,
+            });
+            this.#savePasskeyRecord(replacementRecord, sourceRecord);
+        }
+        finally {
+            this.#ceremonyManager.deleteRegistrationCeremony(registrationChallenge);
+        }
+    }
+    /**
+     * Cancels an in-flight passkey replacement ceremony.
+     *
+     * @param registrationChallenge - Challenge returned by
+     *   {@link generatePasskeyReplacementRegistrationOptions}.
+     */
+    cancelPasskeyReplacement(registrationChallenge) {
+        const registrationCeremony = this.#ceremonyManager.getRegistrationCeremony(registrationChallenge);
+        if (registrationCeremony?.isReplacement) {
+            this.#ceremonyManager.deleteRegistrationCeremony(registrationChallenge);
+        }
+    }
+    /**
+     * Builds WebAuthn credential request options for the post-registration
+     * authentication step (between `create` and {@link protectVaultKeyWithPasskey}).
+     *
+     * @param params - Input for the pending registration ceremony.
+     * @param params.registrationResponse - Result of `navigator.credentials.create()`.
+     * @returns Public key credential request options for `navigator.credentials.get()`.
+     */
+    generatePostRegistrationAuthenticationOptions(params) {
+        // get registration ceremony
+        const { registrationResponse } = params;
+        const regChallenge = this.#getChallengeFromClientData(registrationResponse.response.clientDataJSON);
+        const registrationCeremony = this.#ceremonyManager.getRegistrationCeremony(regChallenge);
+        if (!registrationCeremony) {
+            log('No active passkey registration ceremony for challenge');
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.NoRegistrationCeremony, { code: PasskeyControllerErrorCode.NoRegistrationCeremony });
+        }
+        // build auth options
+        const challenge = randomBytesToBase64URL(32);
+        const extensions = {};
+        if (registrationCeremony.prfSalt) {
+            extensions.prf = { eval: { first: registrationCeremony.prfSalt } };
+        }
+        const options = {
+            challenge,
+            rpId: this.#rpId,
+            allowCredentials: [
+                {
+                    id: registrationResponse.id,
+                    type: 'public-key',
+                    transports: registrationResponse.response.transports,
+                },
+            ],
+            userVerification: 'required',
+            hints: ['client-device', 'hybrid'],
+            timeout: WEBAUTHN_TIMEOUT_MS,
+            extensions,
+        };
+        // save auth ceremony
+        this.#ceremonyManager.saveAuthenticationCeremony(challenge, {
+            challenge,
+            registrationChallenge: regChallenge,
+            createdAt: Date.now(),
+        });
+        return options;
+    }
+    /**
+     * Builds WebAuthn credential request options for the enrolled passkey.
+     *
+     * @returns Public key credential request options for `navigator.credentials.get()`.
+     */
+    generateAuthenticationOptions() {
+        const record = this.#requireEnrolled();
+        const challenge = randomBytesToBase64URL(32);
+        const extensions = {};
+        if (record.keyDerivation.method === 'prf') {
+            extensions.prf = { eval: { first: record.keyDerivation.prfSalt } };
+        }
+        const options = {
+            challenge,
+            rpId: this.#rpId,
+            allowCredentials: [
+                {
+                    id: record.credential.id,
+                    type: 'public-key',
+                    transports: record.credential.transports,
+                },
+            ],
+            userVerification: 'required',
+            hints: ['client-device', 'hybrid'],
+            timeout: WEBAUTHN_TIMEOUT_MS,
+            extensions,
+        };
+        this.#ceremonyManager.saveAuthenticationCeremony(challenge, {
+            challenge,
+            createdAt: Date.now(),
+        });
+        return options;
+    }
+    /**
+     * Verifies registration and post-registration authentication, then stores the
+     * vault key encrypted under the new passkey.
+     *
+     * Fetches the current vault encryption key from KeyringController before wrapping.
+     * When onboarding is complete, requires `password` for step-up verification first.
+     *
+     * @param params - Enrollment completion inputs.
+     * @param params.registrationResponse - Result of `navigator.credentials.create()`.
+     * @param params.authenticationResponse - Result of `navigator.credentials.get()` after {@link generatePostRegistrationAuthenticationOptions}.
+     * @param params.password - Wallet password when onboarding is complete (step-up).
+     * @returns Resolves when enrollment completes.
+     */
+    async protectVaultKeyWithPasskey(params) {
+        return this.#withOperationLock(() => this.#protectVaultKeyWithPasskey(params));
+    }
+    async #protectVaultKeyWithPasskey(params) {
+        if (this.isPasskeyEnrolled()) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.AlreadyEnrolled, { code: PasskeyControllerErrorCode.AlreadyEnrolled });
+        }
+        await this.#assertEnrollmentAllowed(params.password);
+        const vaultKey = await this.messenger.call('KeyringController:exportEncryptionKey');
+        const { registrationResponse } = params;
+        const { challenge, ceremony: registrationCeremony } = this.#getRegistrationCeremony(registrationResponse);
+        if (!registrationCeremony) {
+            log('No active passkey registration ceremony for challenge');
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.NoRegistrationCeremony, { code: PasskeyControllerErrorCode.NoRegistrationCeremony });
+        }
+        try {
+            const credential = await this.#verifyRegistrationResponse(registrationResponse, registrationCeremony);
+            const { newCounter } = await this.#verifyAuthenticationResponse(params.authenticationResponse, credential);
+            const keyDerivation = this.#getKeyDerivation(params.authenticationResponse, registrationCeremony);
+            const passkeyRecord = this.#createPasskeyRecord({
+                vaultKey,
+                authenticationResponse: params.authenticationResponse,
+                credential,
+                newCounter,
+                keyDerivation,
+            });
+            this.#savePasskeyRecord(passkeyRecord);
+        }
+        finally {
+            // delete registration ceremony
+            this.#ceremonyManager.deleteRegistrationCeremony(challenge);
+        }
+    }
+    #getRegistrationCeremony(registrationResponse) {
+        const challenge = this.#getChallengeFromClientData(registrationResponse.response.clientDataJSON);
+        return {
+            challenge,
+            ceremony: this.#ceremonyManager.getRegistrationCeremony(challenge),
+        };
+    }
+    async #verifyRegistrationResponse(registrationResponse, registrationCeremony) {
+        const { verified, registrationInfo } = await verifyRegistrationResponse({
+            response: registrationResponse,
+            expectedChallenge: registrationCeremony.challenge,
+            expectedOrigin: this.#expectedOrigin,
+            expectedRPIDs: this.#expectedRPIDs,
+            requireUserVerification: true,
+        }).catch((error) => {
+            log('Error verifying passkey registration response', error);
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.RegistrationVerificationFailed, {
+                code: PasskeyControllerErrorCode.RegistrationVerificationFailed,
+                cause: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+        if (!verified || !registrationInfo) {
+            log('Passkey registration verification returned unverified or missing registration info');
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.RegistrationVerificationFailed, { code: PasskeyControllerErrorCode.RegistrationVerificationFailed });
+        }
+        const credential = {
+            id: registrationInfo.credentialId,
+            publicKey: bytesToBase64URL(registrationInfo.publicKey),
+            counter: registrationInfo.counter,
+            transports: registrationInfo.transports,
+            aaguid: registrationInfo.aaguid,
+        };
+        if (registrationResponse.id !== credential.id ||
+            registrationResponse.rawId !== credential.id) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.RegistrationVerificationFailed, { code: PasskeyControllerErrorCode.RegistrationVerificationFailed });
+        }
+        return credential;
+    }
+    #getKeyDerivation(authenticationResponse, registrationCeremony, options) {
+        const prfFirst = authenticationResponse.clientExtensionResults?.prf?.results?.first;
+        const authHasPrfOutput = typeof prfFirst === 'string' && prfFirst.length > 0;
+        if (options?.requirePrf) {
+            if (!authHasPrfOutput || !registrationCeremony.prfSalt) {
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.PrfRequired, { code: PasskeyControllerErrorCode.PrfRequired });
+            }
+            return { method: 'prf', prfSalt: registrationCeremony.prfSalt };
+        }
+        if (authHasPrfOutput && registrationCeremony.prfSalt) {
+            return { method: 'prf', prfSalt: registrationCeremony.prfSalt };
+        }
+        if (authenticationResponse.response.userHandle !==
+            registrationCeremony.userHandle) {
+            log('Post-registration assertion userHandle does not match registration ceremony');
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.AuthenticationVerificationFailed, { code: PasskeyControllerErrorCode.AuthenticationVerificationFailed });
+        }
+        return { method: 'userHandle' };
+    }
+    #createPasskeyRecord({ vaultKey, authenticationResponse, credential, newCounter, keyDerivation, }) {
+        const encKey = deriveKeyFromAuthenticationResponse(authenticationResponse, {
+            credential,
+            keyDerivation,
+        });
+        const { ciphertext, iv } = encryptWithKey(vaultKey, encKey);
+        return {
+            credential: {
+                ...credential,
+                counter: Math.max(newCounter, credential.counter),
+            },
+            encryptedVaultKey: { ciphertext, iv },
+            keyDerivation,
+        };
+    }
+    #savePasskeyRecord(passkeyRecord, expectedSourceRecord) {
+        this.update((state) => {
+            if (expectedSourceRecord &&
+                (state.passkeyRecord?.credential.id !==
+                    expectedSourceRecord.credential.id ||
+                    state.passkeyRecord?.keyDerivation.method !== 'userHandle')) {
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.ReplacementSourceChanged, { code: PasskeyControllerErrorCode.ReplacementSourceChanged });
+            }
+            state.passkeyRecord = passkeyRecord;
+        });
+    }
+    /**
+     * Verifies an authentication assertion and returns the decrypted vault key.
+     *
+     * Prefer orchestrated methods ({@link unlockWithPasskey},
+     * {@link exportSeedPhraseWithPasskey}, {@link exportAccountsWithPasskey}) for product
+     * flows instead of calling KeyringController with the returned key manually.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns The plaintext vault encryption key.
+     */
+    async retrieveVaultKeyWithPasskey(authenticationResponse) {
+        return this.#withOperationLock(() => this.#retrieveVaultKeyWithPasskey(authenticationResponse));
+    }
+    async #retrieveVaultKeyWithPasskey(authenticationResponse) {
+        const passkeyRecord = this.#requireEnrolled();
+        // verify authentication response and update counter
+        const { newCounter } = await this.#verifyAuthenticationResponse(authenticationResponse, passkeyRecord.credential);
+        this.update((state) => {
+            if (!state.passkeyRecord) {
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.NotEnrolled, { code: PasskeyControllerErrorCode.NotEnrolled });
+            }
+            state.passkeyRecord.credential.counter = Math.max(newCounter, state.passkeyRecord.credential.counter);
+        });
+        // derive key
+        const encKey = deriveKeyFromAuthenticationResponse(authenticationResponse, passkeyRecord);
+        // decrypt vault key
+        try {
+            const vaultKey = decryptWithKey(passkeyRecord.encryptedVaultKey.ciphertext, passkeyRecord.encryptedVaultKey.iv, encKey);
+            return vaultKey;
+        }
+        catch (cause) {
+            log('Error decrypting vault key with passkey', cause instanceof Error ? cause : new Error(String(cause)));
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.VaultKeyDecryptionFailed, {
+                code: PasskeyControllerErrorCode.VaultKeyDecryptionFailed,
+                cause: cause instanceof Error ? cause : new Error(String(cause)),
+            });
+        }
+    }
+    /**
+     * Unlocks the keyring using a passkey authentication assertion.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns Resolves when the keyring is unlocked.
+     */
+    async unlockWithPasskey(authenticationResponse) {
+        return this.#withOperationLock(async () => {
+            const vaultKey = await this.#retrieveVaultKeyWithPasskey(authenticationResponse);
+            await this.messenger.call('KeyringController:submitEncryptionKey', vaultKey);
+        });
+    }
+    /**
+     * Exports the seed phrase after passkey step-up authentication.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @param keyringId - Optional keyring id; defaults to the primary HD keyring.
+     * @returns Raw seed phrase bytes from KeyringController.
+     */
+    async exportSeedPhraseWithPasskey(authenticationResponse, keyringId) {
+        return this.#withOperationLock(async () => {
+            const vaultKey = await this.#retrieveVaultKeyWithPasskey(authenticationResponse);
+            return await this.messenger.call('KeyringController:exportSeedPhrase', { encryptionKey: vaultKey }, keyringId);
+        });
+    }
+    /**
+     * Exports private keys for the given addresses after passkey step-up authentication.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @param addresses - Account addresses to export.
+     * @returns Private keys in the same order as `addresses`.
+     */
+    async exportAccountsWithPasskey(authenticationResponse, addresses) {
+        return this.#withOperationLock(async () => {
+            const vaultKey = await this.#retrieveVaultKeyWithPasskey(authenticationResponse);
+            const privateKeys = [];
+            for (const address of addresses) {
+                privateKeys.push(await this.messenger.call('KeyringController:exportAccount', { encryptionKey: vaultKey }, address));
+            }
+            return privateKeys;
+        });
+    }
+    /**
+     * Checks whether the given authentication assertion is valid for the enrolled passkey.
+     *
+     * On failure, returns `false` for {@link PasskeyControllerError} with a `code`;
+     * other errors propagate.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns `true` if verification succeeds, otherwise `false`.
+     */
+    async verifyPasskeyAuthentication(authenticationResponse) {
+        return this.#withOperationLock(() => this.#verifyPasskeyAuthentication(authenticationResponse));
+    }
+    async #verifyPasskeyAuthentication(authenticationResponse) {
+        try {
+            await this.#retrieveVaultKeyWithPasskey(authenticationResponse);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof PasskeyControllerError && error.code !== undefined) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Re-wraps the vault key after rotation. Updates persisted `encryptedVaultKey` on success.
+     *
+     * Does not verify WebAuthn or ceremony state—call only after your layer has authenticated
+     * the user (passkey `get()` + verified assertion, or verified password). On passkey paths,
+     * pass the same `authenticationResponse` you just verified (e.g. from
+     * {@link retrieveVaultKeyWithPasskey} / {@link verifyPasskeyAuthentication}).
+     *
+     * For password change with passkey step-up, prefer
+     * {@link changePasswordWithPasskeyVerification}, which orchestrates keyring export,
+     * `changePassword`, and re-wrap in one call.
+     *
+     * @param params - Re-wrap inputs.
+     * @param params.authenticationResponse - Used to derive the wrapping key.
+     * @param params.oldVaultKey - Expected current vault key.
+     * @param params.newVaultKey - New vault key to encrypt under the passkey.
+     * @returns Resolves when the passkey record is updated.
+     */
+    async renewVaultKeyProtection(params) {
+        return this.#withOperationLock(() => this.#renewVaultKeyProtection(params));
+    }
+    async #renewVaultKeyProtection(params) {
+        const { authenticationResponse } = params;
+        const passkeyRecord = this.#requireEnrolled();
+        // derive key
+        const encKey = deriveKeyFromAuthenticationResponse(authenticationResponse, passkeyRecord);
+        // decrypt vault key
+        let decryptedVaultKey;
+        try {
+            decryptedVaultKey = decryptWithKey(passkeyRecord.encryptedVaultKey.ciphertext, passkeyRecord.encryptedVaultKey.iv, encKey);
+        }
+        catch (error) {
+            log('Error decrypting vault key during passkey vault key renewal', error instanceof Error ? error : new Error(String(error)));
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.VaultKeyDecryptionFailed, {
+                code: PasskeyControllerErrorCode.VaultKeyDecryptionFailed,
+                cause: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+        // check if vault key matches
+        const { oldVaultKey, newVaultKey } = params;
+        if (!areUint8ArraysEqual(stringToBytes(decryptedVaultKey), stringToBytes(oldVaultKey))) {
+            log('Passkey renewal rejected: decrypted vault key does not match oldVaultKey');
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.VaultKeyMismatch, { code: PasskeyControllerErrorCode.VaultKeyMismatch });
+        }
+        // encrypt new vault key
+        const { ciphertext, iv } = encryptWithKey(newVaultKey, encKey);
+        // persist passkey record (mutate current state only for vault key material)
+        this.update((state) => {
+            if (!state.passkeyRecord) {
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.NotEnrolled, {
+                    code: PasskeyControllerErrorCode.NotEnrolled,
+                });
+            }
+            state.passkeyRecord.encryptedVaultKey = { ciphertext, iv };
+        });
+    }
+    /**
+     * Changes the wallet password after passkey step-up authentication.
+     *
+     * When `renewVaultKeyProtection` is `true` (default), re-wraps the vault key under the
+     * passkey after rotation. When `false`, removes the passkey instead.
+     *
+     * @param params - Change-password inputs.
+     * @param params.newPassword - New wallet password.
+     * @param params.authenticationResponse - Result of `navigator.credentials.get()`.
+     * @param params.options - Optional flow controls.
+     * @param params.options.renewVaultKeyProtection - Re-wrap vault key after password change.
+     * @returns Resolves when the password change completes.
+     */
+    async changePasswordWithPasskeyVerification(params) {
+        return this.#withOperationLock(() => this.#changePasswordWithPasskeyVerification(params));
+    }
+    async #changePasswordWithPasskeyVerification(params) {
+        this.#requireEnrolled();
+        const verified = await this.#verifyPasskeyAuthentication(params.authenticationResponse);
+        if (!verified) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.AuthenticationVerificationFailed, { code: PasskeyControllerErrorCode.AuthenticationVerificationFailed });
+        }
+        const renewVaultKeyProtection = params.options?.renewVaultKeyProtection ?? true;
+        if (!renewVaultKeyProtection) {
+            await this.messenger.call('KeyringController:changePassword', params.newPassword);
+            this.#removePasskey();
+            return;
+        }
+        const vaultKeyBefore = await this.messenger.call('KeyringController:exportEncryptionKey');
+        await this.messenger.call('KeyringController:changePassword', params.newPassword);
+        try {
+            const vaultKeyAfter = await this.messenger.call('KeyringController:exportEncryptionKey');
+            await this.#renewVaultKeyProtection({
+                authenticationResponse: params.authenticationResponse,
+                oldVaultKey: vaultKeyBefore,
+                newVaultKey: vaultKeyAfter,
+            });
+        }
+        catch (error) {
+            this.#removePasskey();
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.VaultKeyRenewalFailed, {
+                code: PasskeyControllerErrorCode.VaultKeyRenewalFailed,
+                cause: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    /**
+     * Removes the enrolled passkey after verifying a passkey authentication assertion.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns Resolves when the passkey is removed.
+     */
+    async removePasskeyWithPasskeyVerification(authenticationResponse) {
+        return this.#withOperationLock(() => this.#removePasskeyWithPasskeyVerification(authenticationResponse));
+    }
+    async #removePasskeyWithPasskeyVerification(authenticationResponse) {
+        this.#requireEnrolled();
+        const verified = await this.#verifyPasskeyAuthentication(authenticationResponse);
+        if (!verified) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.AuthenticationVerificationFailed, { code: PasskeyControllerErrorCode.AuthenticationVerificationFailed });
+        }
+        this.#removePasskey();
+    }
+    /**
+     * Removes the enrolled passkey after verifying the wallet password.
+     *
+     * @param password - Wallet password for step-up verification.
+     * @returns Resolves when the passkey is removed.
+     */
+    async removePasskeyWithPasswordVerification(password) {
+        return this.#withOperationLock(() => this.#removePasskeyWithPasswordVerification(password));
+    }
+    async #removePasskeyWithPasswordVerification(password) {
+        this.#requireEnrolled();
+        await this.messenger.call('KeyringController:verifyPassword', password);
+        this.#removePasskey();
+    }
+    /**
+     * Resets state and clears in-flight registration/authentication ceremonies.
+     *
+     * For user-facing passkey removal with step-up, use
+     * {@link removePasskeyWithPasskeyVerification} or
+     * {@link removePasskeyWithPasswordVerification}.
+     */
+    clearState() {
+        this.#removePasskey();
+    }
+    /**
+     * Releases all in-flight ceremony state and tears down the messenger.
+     */
+    destroy() {
+        this.#ceremonyManager.clear();
+        super.destroy();
+    }
+    /**
+     * Validates a WebAuthn authentication response against stored credential data.
+     *
+     * @param authenticationResponse - Parsed authentication response from the client.
+     * @param credential - Credential identifiers and public key material for verification.
+     * @returns Updated authenticator signature counter.
+     */
+    async #verifyAuthenticationResponse(authenticationResponse, credential) {
+        // get challenge
+        const challenge = this.#getChallengeFromClientData(authenticationResponse.response.clientDataJSON);
+        // get authentication ceremony
+        const authenticationCeremony = this.#ceremonyManager.getAuthenticationCeremony(challenge);
+        if (!authenticationCeremony) {
+            log('No active passkey authentication ceremony for challenge');
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.NoAuthenticationCeremony, { code: PasskeyControllerErrorCode.NoAuthenticationCeremony });
+        }
+        try {
+            if (authenticationResponse.id !== credential.id ||
+                authenticationResponse.rawId !== credential.id) {
+                log('Passkey authentication response credential ID does not match the expected credential');
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.AuthenticationVerificationFailed, {
+                    code: PasskeyControllerErrorCode.AuthenticationVerificationFailed,
+                });
+            }
+            // verify authentication response
+            const result = await verifyAuthenticationResponse({
+                response: authenticationResponse,
+                expectedChallenge: authenticationCeremony.challenge,
+                expectedOrigin: this.#expectedOrigin,
+                expectedRPIDs: this.#expectedRPIDs,
+                credential: {
+                    id: credential.id,
+                    publicKey: base64URLToBytes(credential.publicKey),
+                    counter: credential.counter,
+                    transports: credential.transports,
+                },
+                requireUserVerification: true,
+            }).catch((error) => {
+                log('Error verifying passkey authentication response', error instanceof Error ? error : new Error(String(error)));
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.AuthenticationVerificationFailed, {
+                    code: PasskeyControllerErrorCode.AuthenticationVerificationFailed,
+                    cause: error instanceof Error ? error : new Error(String(error)),
+                });
+            });
+            if (!result.verified) {
+                log('Passkey authentication verification returned unverified');
+                throw new PasskeyControllerError(PasskeyControllerErrorMessage.AuthenticationVerificationFailed, {
+                    code: PasskeyControllerErrorCode.AuthenticationVerificationFailed,
+                });
+            }
+            return { newCounter: result.authenticationInfo.newCounter };
+        }
+        finally {
+            // delete authentication ceremony
+            this.#ceremonyManager.deleteAuthenticationCeremony(challenge);
+        }
+    }
+    /**
+     * Serializes orchestrated passkey operations that mutate state or call KeyringController.
+     *
+     * @param callback - Operation to run while the mutex is held.
+     * @returns The result of the callback.
+     */
+    async #withOperationLock(callback) {
+        return this.#operationMutex.runExclusive(callback);
+    }
+    async #assertEnrollmentAllowed(password) {
+        if (!this.#getIsOnboardingCompleted()) {
+            return;
+        }
+        if (!password) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.EnrollmentPasswordRequired, {
+                code: PasskeyControllerErrorCode.EnrollmentPasswordRequired,
+            });
+        }
+        await this.messenger.call('KeyringController:verifyPassword', password);
+    }
+    #requireEnrolled() {
+        const record = this.state.passkeyRecord;
+        if (!record) {
+            throw new PasskeyControllerError(PasskeyControllerErrorMessage.NotEnrolled, {
+                code: PasskeyControllerErrorCode.NotEnrolled,
+            });
+        }
+        return record;
+    }
+    #getChallengeFromClientData(clientDataJSON) {
+        return decodeClientDataJSON(clientDataJSON).challenge;
+    }
+    /**
+     * Clears enrolled passkey state and in-flight ceremonies.
+     */
+    #removePasskey() {
+        this.update(() => getDefaultPasskeyControllerState());
+        this.#ceremonyManager.clear();
+    }
+}
+//# sourceMappingURL=PasskeyController.js.map