@metamask-previews/passkey-controller 0.0.0-preview-4c0846313

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial `@metamask/passkey-controller` ([#8422](https://github.com/MetaMask/core/pull/8422)): `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.
+- `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).
+
+[Unreleased]: https://github.com/MetaMask/core/

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# `@metamask/passkey-controller`
+
+Manages passkey-based vault key protection using [WebAuthn](https://www.w3.org/TR/webauthn-3/). Orchestrates the full passkey lifecycle: generating WebAuthn ceremony options, verifying authenticator responses, and protecting/retrieving the vault encryption key via AES-256-GCM wrapping with HKDF-derived keys.
+
+## Installation
+
+`yarn add @metamask/passkey-controller`
+
+or
+
+`npm install @metamask/passkey-controller`
+
+## Overview
+
+The controller follows a two-phase ceremony pattern for both enrollment and authentication:
+
+1. **Generate options** — call a synchronous method that returns options JSON and records **in-flight ceremony** state (challenge-keyed; not a user login session).
+2. **Verify response** — pass the authenticator's response back to the controller, which verifies the WebAuthn signature and performs the cryptographic operation (protect or retrieve the vault key).
+
+### Key derivation strategies
+
+The controller supports two key derivation methods, selected automatically during enrollment:
+
+| Strategy       | When used                                                                                          | Input key material                                |
+| -------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| **PRF**        | Authenticator supports the [WebAuthn PRF extension](https://w3c.github.io/webauthn/#prf-extension) | PRF evaluation output                             |
+| **userHandle** | PRF is unavailable                                                                                 | Random `userHandle` generated during registration |
+
+Both strategies feed the input key material through **HKDF-SHA256** with the credential ID as salt and a fixed info string to produce the 32-byte AES-256 wrapping key.
+
+## Usage
+
+### Setting up the controller
+
+```typescript
+import { PasskeyController } from '@metamask/passkey-controller';
+import type { PasskeyControllerMessenger } from '@metamask/passkey-controller';
+
+const messenger: PasskeyControllerMessenger = /* create via root messenger */;
+
+const controller = new PasskeyController({
+  messenger,
+  rpID: 'example.com',
+  rpName: 'My Wallet',
+  expectedOrigin: 'chrome-extension://abcdef1234567890',
+  // Optional — both default to `rpName` when omitted.
+  userName: 'My Wallet',
+  userDisplayName: 'My Wallet',
+});
+```
+
+### Passkey enrollment (registration)
+
+```typescript
+// 1. Generate registration options (synchronous)
+const options = controller.generateRegistrationOptions();
+
+// 2. Pass options to the browser WebAuthn API
+const response = await navigator.credentials.create({ publicKey: options });
+
+// 3. Verify and protect the vault key
+await controller.protectVaultKeyWithPasskey({
+  registrationResponse: response,
+  vaultKey: myVaultEncryptionKey,
+});
+```
+
+### Passkey unlock (authentication)
+
+```typescript
+// 1. Generate authentication options (synchronous)
+const options = controller.generateAuthenticationOptions();
+
+// 2. Pass options to the browser WebAuthn API
+const response = await navigator.credentials.get({ publicKey: options });
+
+// 3. Verify and retrieve the vault key
+const vaultKey = await controller.retrieveVaultKeyWithPasskey(response);
+```
+
+### Password change (vault key renewal)
+
+```typescript
+const options = controller.generateAuthenticationOptions();
+const response = await navigator.credentials.get({ publicKey: options });
+
+await controller.renewVaultKeyProtection({
+  authenticationResponse: response,
+  oldVaultKey: currentVaultKey,
+  newVaultKey: newVaultKey,
+});
+```
+
+### Checking enrollment and removing a passkey
+
+```typescript
+controller.isPasskeyEnrolled(); // boolean
+
+controller.removePasskey(); // user-facing unenroll; clears persisted passkey and in-flight ceremonies
+
+controller.clearState(); // same persisted reset + clears in-flight ceremony state; use for app lifecycle (e.g. wallet reset)
+```
+
+### Selectors
+
+For Redux selectors and other code paths without access to the controller
+instance, use the exported selector(s):
+
+```typescript
+import { passkeyControllerSelectors } from '@metamask/passkey-controller';
+
+passkeyControllerSelectors.selectIsPasskeyEnrolled(state); // boolean
+```
+
+### Errors
+
+`PasskeyControllerError` is thrown for controller failures. Expected operational
+cases use a stable `code` from `PasskeyControllerErrorCode` (for example:
+`not_enrolled`, `no_registration_ceremony`, `authentication_verification_failed`,
+`missing_key_material`, `vault_key_decryption_failed`). Human-readable strings
+live on `PasskeyControllerErrorMessage`. Use `instanceof PasskeyControllerError`
+and a defined `error.code` to tell these apart from malformed WebAuthn payloads
+and other `Error` values. Thrown errors from the internal WebAuthn verify helpers
+are also surfaced as `PasskeyControllerError` with the same `registration_verification_failed`
+or `authentication_verification_failed` code and the original error as `cause`.
+`verifyPasskeyAuthentication` returns `false` only for
+those controller errors (with `code`) and rethrows everything else.
+
+## API
+
+### State
+
+| Property        | Type                    | Description                                                                                   |
+| --------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
+| `passkeyRecord` | `PasskeyRecord \| null` | Enrolled passkey credential data and encrypted vault key. `null` when no passkey is enrolled. |
+
+### Messenger actions
+
+| Action                       | Handler                              |
+| ---------------------------- | ------------------------------------ |
+| `PasskeyController:getState` | Returns the current controller state |
+
+For derived enrollment status outside of components that hold a controller
+reference, use `passkeyControllerSelectors.selectIsPasskeyEnrolled` (see
+[Selectors](#selectors)).
+
+### Messenger events
+
+| Event                            | Payload                                                      |
+| -------------------------------- | ------------------------------------------------------------ |
+| `PasskeyController:stateChanged` | Emitted when state changes (standard `BaseController` event) |
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

package/dist/PasskeyController.cjs

@@ -0,0 +1,448 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _PasskeyController_instances, _PasskeyController_ceremonyManager, _PasskeyController_rpID, _PasskeyController_rpName, _PasskeyController_expectedOrigin, _PasskeyController_userName, _PasskeyController_userDisplayName, _PasskeyController_requireEnrolled, _PasskeyController_getChallengeFromClientData, _PasskeyController_verifyAuthenticationResponse;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PasskeyController = exports.passkeyControllerSelectors = exports.getDefaultPasskeyControllerState = void 0;
+const base_controller_1 = require("@metamask/base-controller");
+const webcrypto_1 = require("@noble/ciphers/webcrypto");
+const ceremony_manager_1 = require("./ceremony-manager.cjs");
+const constants_1 = require("./constants.cjs");
+const errors_1 = require("./errors.cjs");
+const key_derivation_1 = require("./key-derivation.cjs");
+const logger_1 = require("./logger.cjs");
+const crypto_1 = require("./utils/crypto.cjs");
+const encoding_1 = require("./utils/encoding.cjs");
+const constants_2 = require("./webauthn/constants.cjs");
+const decode_client_data_json_1 = require("./webauthn/decode-client-data-json.cjs");
+const verify_authentication_response_1 = require("./webauthn/verify-authentication-response.cjs");
+const verify_registration_response_1 = require("./webauthn/verify-registration-response.cjs");
+/**
+ * Returns the default (empty) state for {@link PasskeyController}.
+ *
+ * @returns A fresh state object with no enrolled passkey.
+ */
+function getDefaultPasskeyControllerState() {
+    return { passkeyRecord: null };
+}
+exports.getDefaultPasskeyControllerState = getDefaultPasskeyControllerState;
+const passkeyControllerMetadata = {
+    passkeyRecord: {
+        persist: true,
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        usedInUi: true,
+    },
+};
+const log = (0, logger_1.createModuleLogger)(logger_1.projectLogger, constants_1.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.
+ */
+exports.passkeyControllerSelectors = {
+    selectIsPasskeyEnrolled: (state) => state.passkeyRecord !== null,
+};
+/**
+ * Passkey-based protection for the vault encryption key (WebAuthn).
+ *
+ * Uses PRF-backed derivation when available; otherwise uses the credential
+ * `userHandle`.
+ */
+class PasskeyController extends base_controller_1.BaseController {
+    /**
+     * Constructs a new {@link PasskeyController}.
+     *
+     * @param args - The constructor arguments.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - Initial state. Missing properties are filled in with
+     *   defaults from {@link getDefaultPasskeyControllerState}.
+     * @param args.rpID - WebAuthn Relying Party ID (typically the eTLD+1 of the
+     *   client origin, or `localhost` in dev).
+     * @param args.rpName - Human-readable Relying Party name shown by the OS
+     *   passkey UI.
+     * @param args.expectedOrigin - One or more acceptable origins for the
+     *   `clientDataJSON.origin` check (e.g. `chrome-extension://...`).
+     * @param args.userName - Optional `user.name` shown by the OS passkey UI.
+     *   Defaults to `rpName` so client builds (Stable, Flask, etc.) can
+     *   differentiate without changes here.
+     * @param args.userDisplayName - Optional `user.displayName` shown by the OS
+     *   passkey UI. Defaults to `rpName`.
+     */
+    constructor({ messenger, state = {}, rpID, rpName, expectedOrigin, userName, userDisplayName, }) {
+        super({
+            messenger,
+            metadata: passkeyControllerMetadata,
+            name: constants_1.controllerName,
+            state: { ...getDefaultPasskeyControllerState(), ...state },
+        });
+        _PasskeyController_instances.add(this);
+        _PasskeyController_ceremonyManager.set(this, new ceremony_manager_1.CeremonyManager());
+        _PasskeyController_rpID.set(this, void 0);
+        _PasskeyController_rpName.set(this, void 0);
+        _PasskeyController_expectedOrigin.set(this, void 0);
+        _PasskeyController_userName.set(this, void 0);
+        _PasskeyController_userDisplayName.set(this, void 0);
+        __classPrivateFieldSet(this, _PasskeyController_rpID, rpID, "f");
+        __classPrivateFieldSet(this, _PasskeyController_rpName, rpName, "f");
+        __classPrivateFieldSet(this, _PasskeyController_expectedOrigin, expectedOrigin, "f");
+        __classPrivateFieldSet(this, _PasskeyController_userName, userName ?? rpName, "f");
+        __classPrivateFieldSet(this, _PasskeyController_userDisplayName, userDisplayName ?? rpName, "f");
+    }
+    /**
+     * Checks if the passkey is enrolled.
+     *
+     * @returns Whether the passkey is enrolled.
+     */
+    isPasskeyEnrolled() {
+        return exports.passkeyControllerSelectors.selectIsPasskeyEnrolled(this.state);
+    }
+    /**
+     * Registration options for enrolling a passkey.
+     *
+     * Call before {@link protectVaultKeyWithPasskey}.
+     *
+     * @param creationOptionsConfig - Optional configuration.
+     * @param creationOptionsConfig.prfAvailable - Omit PRF when `false`. Default `true`.
+     * @returns Options for `navigator.credentials.create()`.
+     */
+    generateRegistrationOptions(creationOptionsConfig) {
+        const includePrf = creationOptionsConfig?.prfAvailable !== false;
+        const prfSalt = includePrf
+            ? (0, encoding_1.bytesToBase64URL)((0, webcrypto_1.randomBytes)(32).slice())
+            : undefined;
+        const userHandle = (0, encoding_1.bytesToBase64URL)((0, webcrypto_1.randomBytes)(64).slice());
+        const challenge = (0, encoding_1.bytesToBase64URL)((0, webcrypto_1.randomBytes)(32).slice());
+        const extensions = {};
+        if (prfSalt) {
+            extensions.prf = { eval: { first: prfSalt } };
+        }
+        const options = {
+            rp: { name: __classPrivateFieldGet(this, _PasskeyController_rpName, "f"), id: __classPrivateFieldGet(this, _PasskeyController_rpID, "f") },
+            user: {
+                id: userHandle,
+                name: __classPrivateFieldGet(this, _PasskeyController_userName, "f"),
+                displayName: __classPrivateFieldGet(this, _PasskeyController_userDisplayName, "f"),
+            },
+            challenge,
+            pubKeyCredParams: [
+                { alg: constants_2.COSEALG.EdDSA, type: 'public-key' },
+                { alg: constants_2.COSEALG.ES256, type: 'public-key' },
+                { alg: constants_2.COSEALG.RS256, type: 'public-key' },
+            ],
+            timeout: ceremony_manager_1.WEBAUTHN_TIMEOUT_MS,
+            authenticatorSelection: {
+                userVerification: 'preferred',
+                authenticatorAttachment: 'platform',
+                residentKey: 'preferred',
+            },
+            hints: ['client-device', 'hybrid'],
+            attestation: 'none',
+            ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
+        };
+        __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").saveRegistrationCeremony(challenge, {
+            userHandle,
+            prfSalt: prfSalt ?? '',
+            challenge,
+            createdAt: Date.now(),
+        });
+        return options;
+    }
+    /**
+     * WebAuthn request options for authenticating with the enrolled passkey.
+     *
+     * Call before {@link retrieveVaultKeyWithPasskey},
+     * {@link verifyPasskeyAuthentication}, or {@link renewVaultKeyProtection}.
+     *
+     * @returns Options for `navigator.credentials.get()`.
+     */
+    generateAuthenticationOptions() {
+        const record = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_requireEnrolled).call(this);
+        const challenge = (0, encoding_1.bytesToBase64URL)((0, webcrypto_1.randomBytes)(32).slice());
+        const extensions = {};
+        if (record.keyDerivation.method === 'prf') {
+            extensions.prf = { eval: { first: record.keyDerivation.prfSalt } };
+        }
+        const options = {
+            challenge,
+            rpId: __classPrivateFieldGet(this, _PasskeyController_rpID, "f"),
+            allowCredentials: [
+                {
+                    id: record.credential.id,
+                    type: 'public-key',
+                    transports: record.credential.transports,
+                },
+            ],
+            userVerification: 'preferred',
+            hints: ['client-device', 'hybrid'],
+            timeout: ceremony_manager_1.WEBAUTHN_TIMEOUT_MS,
+            extensions,
+        };
+        __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").saveAuthenticationCeremony(challenge, {
+            challenge,
+            createdAt: Date.now(),
+        });
+        return options;
+    }
+    /**
+     * Completes enrollment and binds the vault key to the new passkey.
+     *
+     * @param params - Protection parameters.
+     * @param params.registrationResponse - Credential from `navigator.credentials.create()`.
+     * @param params.vaultKey - Vault encryption key to protect.
+     */
+    async protectVaultKeyWithPasskey(params) {
+        const { registrationResponse, vaultKey } = params;
+        // get challenge
+        const challenge = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_getChallengeFromClientData).call(this, registrationResponse.response.clientDataJSON);
+        const registrationCeremony = __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").getRegistrationCeremony(challenge);
+        if (!registrationCeremony) {
+            log('No active passkey registration ceremony for challenge');
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NoRegistrationCeremony, { code: constants_1.PasskeyControllerErrorCode.NoRegistrationCeremony });
+        }
+        try {
+            // verify registration response
+            const { verified, registrationInfo } = await (0, verify_registration_response_1.verifyRegistrationResponse)({
+                response: registrationResponse,
+                expectedChallenge: registrationCeremony.challenge,
+                expectedOrigin: __classPrivateFieldGet(this, _PasskeyController_expectedOrigin, "f"),
+                expectedRPID: __classPrivateFieldGet(this, _PasskeyController_rpID, "f"),
+                requireUserVerification: false,
+            }).catch((error) => {
+                log('Error verifying passkey registration response', error);
+                throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.RegistrationVerificationFailed, {
+                    code: constants_1.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 errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.RegistrationVerificationFailed, { code: constants_1.PasskeyControllerErrorCode.RegistrationVerificationFailed });
+            }
+            // derive key
+            const { encKey, keyDerivation } = (0, key_derivation_1.deriveKeyFromRegistrationResponse)(registrationResponse, registrationCeremony, registrationInfo.credentialId);
+            // encrypt vault key
+            const { ciphertext, iv } = (0, crypto_1.encryptWithKey)(vaultKey, encKey);
+            // persist passkey record
+            this.update((state) => {
+                state.passkeyRecord = {
+                    credential: {
+                        id: registrationInfo.credentialId,
+                        publicKey: (0, encoding_1.bytesToBase64URL)(registrationInfo.publicKey),
+                        counter: registrationInfo.counter,
+                        transports: registrationInfo.transports,
+                    },
+                    encryptedVaultKey: { ciphertext, iv },
+                    keyDerivation,
+                };
+            });
+        }
+        finally {
+            __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").deleteRegistrationCeremony(challenge);
+        }
+    }
+    /**
+     * Returns the decrypted vault encryption key from the passkey authentication
+     * response.
+     *
+     * @param authenticationResponse - Credential from `navigator.credentials.get()`.
+     * @returns The vault encryption key.
+     */
+    async retrieveVaultKeyWithPasskey(authenticationResponse) {
+        // verify authentication response
+        await __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_verifyAuthenticationResponse).call(this, authenticationResponse);
+        // derive key (#verifyAuthenticationResponse guarantees enrolled)
+        const passkeyRecord = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_requireEnrolled).call(this);
+        const encKey = (0, key_derivation_1.deriveKeyFromAuthenticationResponse)(authenticationResponse, passkeyRecord);
+        // decrypt vault key
+        let vaultKey;
+        try {
+            vaultKey = (0, crypto_1.decryptWithKey)(passkeyRecord.encryptedVaultKey.ciphertext, passkeyRecord.encryptedVaultKey.iv, encKey);
+        }
+        catch (cause) {
+            log('Error decrypting vault key with passkey', cause instanceof Error ? cause : new Error(String(cause)));
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.VaultKeyDecryptionFailed, {
+                code: constants_1.PasskeyControllerErrorCode.VaultKeyDecryptionFailed,
+                cause: cause instanceof Error ? cause : new Error(String(cause)),
+            });
+        }
+        return vaultKey;
+    }
+    /**
+     * Returns whether passkey authentication succeeds for this credential (same
+     * work as {@link retrieveVaultKeyWithPasskey} without exposing the vault key).
+     *
+     * Returns `false` only when the failure is a {@link PasskeyControllerError}
+     * with a defined `code`. Unexpected errors (e.g. malformed `clientDataJSON`,
+     * internal bugs) are rethrown.
+     *
+     * @param authenticationResponse - Credential from `navigator.credentials.get()`.
+     * @returns `true` if authentication succeeds, otherwise `false`.
+     */
+    async verifyPasskeyAuthentication(authenticationResponse) {
+        try {
+            await this.retrieveVaultKeyWithPasskey(authenticationResponse);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof errors_1.PasskeyControllerError && error.code !== undefined) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Updates the vault encryption key for the same passkey (e.g. after a password change).
+     *
+     * Caller MUST first verify the assertion via {@link verifyPasskeyAuthentication}
+     * or {@link retrieveVaultKeyWithPasskey}. This method does not re-verify
+     * because the ceremony is single-use (deleted on verify) and the signature
+     * counter is advanced (replay would be rejected). Authentication here is
+     * enforced by the prior verification plus the `oldVaultKey` match below.
+     *
+     * @param params - Renewal parameters.
+     * @param params.authenticationResponse - Credential from `navigator.credentials.get()`,
+     *   already verified by the caller.
+     * @param params.oldVaultKey - Expected current vault key.
+     * @param params.newVaultKey - New vault key to protect.
+     */
+    async renewVaultKeyProtection(params) {
+        const { authenticationResponse } = params;
+        const passkeyRecord = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_requireEnrolled).call(this);
+        // derive key
+        const encKey = (0, key_derivation_1.deriveKeyFromAuthenticationResponse)(authenticationResponse, passkeyRecord);
+        // decrypt vault key
+        let decryptedVaultKey;
+        try {
+            decryptedVaultKey = (0, crypto_1.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 errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.VaultKeyDecryptionFailed, {
+                code: constants_1.PasskeyControllerErrorCode.VaultKeyDecryptionFailed,
+                cause: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+        // check if vault key matches
+        const { oldVaultKey, newVaultKey } = params;
+        if (decryptedVaultKey !== oldVaultKey) {
+            log('Passkey renewal rejected: decrypted vault key does not match oldVaultKey');
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.VaultKeyMismatch, { code: constants_1.PasskeyControllerErrorCode.VaultKeyMismatch });
+        }
+        // encrypt new vault key
+        const { ciphertext, iv } = (0, crypto_1.encryptWithKey)(newVaultKey, encKey);
+        // persist passkey record (mutate current state only for vault key material)
+        this.update((state) => {
+            if (!state.passkeyRecord) {
+                throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NotEnrolled, {
+                    code: constants_1.PasskeyControllerErrorCode.NotEnrolled,
+                });
+            }
+            state.passkeyRecord.encryptedVaultKey = { ciphertext, iv };
+        });
+    }
+    /**
+     * Unenrolls the passkey, removing the protected vault key material.
+     */
+    removePasskey() {
+        this.update(() => getDefaultPasskeyControllerState());
+        __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").clear();
+    }
+    /**
+     * Resets state and clears in-flight registration/authentication ceremonies.
+     */
+    clearState() {
+        this.removePasskey();
+    }
+    /**
+     * Releases all in-flight ceremony state and tears down the messenger.
+     */
+    destroy() {
+        __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").clear();
+        super.destroy();
+    }
+}
+exports.PasskeyController = PasskeyController;
+_PasskeyController_ceremonyManager = new WeakMap(), _PasskeyController_rpID = new WeakMap(), _PasskeyController_rpName = new WeakMap(), _PasskeyController_expectedOrigin = new WeakMap(), _PasskeyController_userName = new WeakMap(), _PasskeyController_userDisplayName = new WeakMap(), _PasskeyController_instances = new WeakSet(), _PasskeyController_requireEnrolled = function _PasskeyController_requireEnrolled() {
+    const record = this.state.passkeyRecord;
+    if (!record) {
+        throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NotEnrolled, {
+            code: constants_1.PasskeyControllerErrorCode.NotEnrolled,
+        });
+    }
+    return record;
+}, _PasskeyController_getChallengeFromClientData = function _PasskeyController_getChallengeFromClientData(clientDataJSON) {
+    return (0, decode_client_data_json_1.decodeClientDataJSON)(clientDataJSON).challenge;
+}, _PasskeyController_verifyAuthenticationResponse = 
+/**
+ * Verifies an authentication response for the enrolled passkey.
+ *
+ * @param authenticationResponse - Authentication result JSON.
+ */
+async function _PasskeyController_verifyAuthenticationResponse(authenticationResponse) {
+    let challenge;
+    try {
+        // get challenge
+        challenge = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_getChallengeFromClientData).call(this, authenticationResponse.response.clientDataJSON);
+        // get passkey record
+        const record = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_requireEnrolled).call(this);
+        // get authentication ceremony
+        const authenticationCeremony = __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").getAuthenticationCeremony(challenge);
+        if (!authenticationCeremony) {
+            log('No active passkey authentication ceremony for challenge');
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NoAuthenticationCeremony, { code: constants_1.PasskeyControllerErrorCode.NoAuthenticationCeremony });
+        }
+        // verify authentication response
+        const result = await (0, verify_authentication_response_1.verifyAuthenticationResponse)({
+            response: authenticationResponse,
+            expectedChallenge: authenticationCeremony.challenge,
+            expectedOrigin: __classPrivateFieldGet(this, _PasskeyController_expectedOrigin, "f"),
+            expectedRPID: __classPrivateFieldGet(this, _PasskeyController_rpID, "f"),
+            credential: {
+                id: record.credential.id,
+                publicKey: (0, encoding_1.base64URLToBytes)(record.credential.publicKey),
+                counter: record.credential.counter,
+                transports: record.credential.transports,
+            },
+            // UV optional for device compatibility; vault key remains password-gated.
+            requireUserVerification: false,
+        }).catch((error) => {
+            log('Error verifying passkey authentication response', error instanceof Error ? error : new Error(String(error)));
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.AuthenticationVerificationFailed, {
+                code: constants_1.PasskeyControllerErrorCode.AuthenticationVerificationFailed,
+                cause: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+        if (!result.verified) {
+            log('Passkey authentication verification returned unverified');
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.AuthenticationVerificationFailed, {
+                code: constants_1.PasskeyControllerErrorCode.AuthenticationVerificationFailed,
+            });
+        }
+        // persist passkey record with updated counter without clobbering concurrent updates
+        this.update((state) => {
+            if (!state.passkeyRecord) {
+                throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NotEnrolled, { code: constants_1.PasskeyControllerErrorCode.NotEnrolled });
+            }
+            const latest = state.passkeyRecord;
+            latest.credential.counter = Math.max(result.authenticationInfo.newCounter, latest.credential.counter);
+        });
+    }
+    finally {
+        if (challenge) {
+            __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").deleteAuthenticationCeremony(challenge);
+        }
+    }
+};
+//# sourceMappingURL=PasskeyController.cjs.map