@metamask-previews/passkey-controller 1.0.0-preview-95a687acf → 1.0.0-preview-4e0ae1bc9

package/CHANGELOG.md

@@ -7,10 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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](https://github.com/MetaMask/core/pull/8663))
+- `already_enrolled` (`PasskeyControllerErrorCode.AlreadyEnrolled`) when calling `protectVaultKeyWithPasskey` while a passkey is already enrolled ([#8663](https://github.com/MetaMask/core/pull/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](https://github.com/MetaMask/core/pull/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](https://github.com/MetaMask/core/pull/8663))
+- **BREAKING:** `verifyRegistrationResponse` and `verifyAuthenticationResponse` now take `expectedRPIDs: string[]` instead of `expectedRPID: string` ([#8663](https://github.com/MetaMask/core/pull/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](https://github.com/MetaMask/core/pull/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](https://github.com/MetaMask/core/pull/8663))
 - Bump `@metamask/messenger` from `^1.1.1` to `^1.2.0` ([#8632](https://github.com/MetaMask/core/pull/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](https://github.com/MetaMask/core/pull/8663))
+
 ## [1.0.0]
 
 ### Added

package/README.md

@@ -12,19 +12,21 @@ or
 
 ## Overview
 
-The controller follows a two-phase ceremony pattern for both enrollment and authentication:
+The controller follows a two-phase ceremony pattern for unlock (authentication) and a three-step pattern for enrollment: registration options → post-registration authentication options → combined verify and protect.
 
 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).
 
+For enrollment, the wrapping key is always derived from the **post-registration** `get()` response (same path as unlock), not from the `create()` response alone.
+
 ### 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 |
+| Strategy       | When used                                                                                                                                           | Input key material                                                                    |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| **PRF**        | Post-registration assertion includes non-empty [PRF extension](https://w3c.github.io/webauthn/#prf-extension) output and registration used PRF salt | PRF evaluation output from the assertion (ceremony `prfSalt` is stored on the record) |
+| **userHandle** | Otherwise                                                                                                                                           | Random `userHandle` from registration (asserted on the post-registration `get()`)     |
 
 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.
 
@@ -40,7 +42,9 @@ const messenger: PasskeyControllerMessenger = /* create via root messenger */;
 
 const controller = new PasskeyController({
   messenger,
-  rpID: 'example.com',
+  rpId: 'example.com',
+  // Or multiple verification candidates: expectedRPID: ['a.example', 'b.example']
+  expectedRPID: 'example.com',
   rpName: 'My Wallet',
   expectedOrigin: 'chrome-extension://abcdef1234567890',
   // Optional — both default to `rpName` when omitted.
@@ -49,18 +53,31 @@ const controller = new PasskeyController({
 });
 ```
 
+`expectedRPID` is a string or string array used to verify the authenticator `rpIdHash`. Optional `rpId`, when set, is sent as `rp.id` / `rpId` in generated WebAuthn options; when omitted, those fields are omitted so the client uses its default RP ID behavior.
+
 ### Passkey enrollment (registration)
 
 ```typescript
 // 1. Generate registration options (synchronous)
-const options = controller.generateRegistrationOptions();
+const regOptions = controller.generateRegistrationOptions();
 
-// 2. Pass options to the browser WebAuthn API
-const response = await navigator.credentials.create({ publicKey: options });
+// 2. Create the passkey in the browser
+const regResponse = await navigator.credentials.create({
+  publicKey: regOptions,
+});
+
+// 3. Post-registration authentication (same wrapping-key path as unlock)
+const authOptions = controller.generatePostRegistrationAuthenticationOptions({
+  registrationResponse: regResponse,
+});
+const authResponse = await navigator.credentials.get({
+  publicKey: authOptions,
+});
 
-// 3. Verify and protect the vault key
+// 4. Verify registration + post-registration auth once, then persist
 await controller.protectVaultKeyWithPasskey({
-  registrationResponse: response,
+  registrationResponse: regResponse,
+  authenticationResponse: authResponse,
   vaultKey: myVaultEncryptionKey,
 });
 ```
@@ -116,8 +133,8 @@ passkeyControllerSelectors.selectIsPasskeyEnrolled(state); // boolean
 
 `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
+`not_enrolled`, `already_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

package/dist/PasskeyController.cjs

@@ -10,12 +10,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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;
+var _PasskeyController_instances, _PasskeyController_ceremonyManager, _PasskeyController_expectedRPIDs, _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 utils_1 = require("@metamask/utils");
-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");
@@ -56,32 +55,27 @@ 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`.
+ * Controller that enrolls a WebAuthn passkey and uses it to protect and unlock
+ * the vault encryption key.
  */
 class PasskeyController extends base_controller_1.BaseController {
     /**
-     * Constructs a new {@link PasskeyController}.
+     * Creates a passkey controller with WebAuthn relying-party settings.
      *
-     * @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`.
+     * @param args - Constructor options.
+     * @param args.messenger - Controller messenger.
+     * @param args.state - Partial initial state; merged with {@link getDefaultPasskeyControllerState}.
+     * @param args.expectedRPID - Relying party ID(s) for verification (SHA-256 hash match in
+     *   authenticator data). Pass a string or array of strings; an empty array skips RP ID
+     *   allowlist checks in {@link verifyRegistrationResponse} / {@link verifyAuthenticationResponse}.
+     * @param args.rpId - When set, included as `rp.id` on registration options and `rpId` on
+     *   authentication options. When omitted, those fields are left unset (client default RP ID).
+     * @param args.rpName - Relying party name shown in the platform passkey UI.
+     * @param args.expectedOrigin - Allowed value(s) for the WebAuthn client origin.
+     * @param args.userName - Optional passkey user name; defaults to `rpName`.
+     * @param args.userDisplayName - Optional display name; defaults to `rpName`.
      */
-    constructor({ messenger, state = {}, rpID, rpName, expectedOrigin, userName, userDisplayName, }) {
+    constructor({ messenger, state = {}, rpId, expectedRPID, rpName, expectedOrigin, userName, userDisplayName, }) {
         super({
             messenger,
             metadata: passkeyControllerMetadata,
@@ -90,47 +84,54 @@ class PasskeyController extends base_controller_1.BaseController {
         });
         _PasskeyController_instances.add(this);
         _PasskeyController_ceremonyManager.set(this, new ceremony_manager_1.CeremonyManager());
-        _PasskeyController_rpID.set(this, void 0);
+        _PasskeyController_expectedRPIDs.set(this, void 0);
+        _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");
+        const expectedRPIDs = Array.isArray(expectedRPID)
+            ? expectedRPID
+            : [expectedRPID];
+        __classPrivateFieldSet(this, _PasskeyController_expectedRPIDs, [...expectedRPIDs], "f");
+        __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.
+     * Whether a passkey is enrolled and vault key material is stored.
      *
-     * @returns Whether the passkey is enrolled.
+     * @returns `true` if enrolled, otherwise `false`.
      */
     isPasskeyEnrolled() {
         return exports.passkeyControllerSelectors.selectIsPasskeyEnrolled(this.state);
     }
     /**
-     * Registration options for enrolling a passkey.
-     *
-     * Call before {@link protectVaultKeyWithPasskey}.
+     * Builds WebAuthn credential creation options for passkey enrollment.
      *
-     * @param creationOptionsConfig - Optional configuration.
-     * @param creationOptionsConfig.prfAvailable - Omit PRF when `false`. Default `true`.
-     * @returns Options for `navigator.credentials.create()`.
+     * @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) {
+        if (this.isPasskeyEnrolled()) {
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.AlreadyEnrolled, { code: constants_1.PasskeyControllerErrorCode.AlreadyEnrolled });
+        }
         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 prfSalt = includePrf ? (0, crypto_1.randomBytesToBase64URL)(32) : undefined;
+        const userHandle = (0, crypto_1.randomBytesToBase64URL)(64);
+        const challenge = (0, crypto_1.randomBytesToBase64URL)(32);
         const extensions = {};
         if (prfSalt) {
             extensions.prf = { eval: { first: prfSalt } };
         }
         const options = {
-            rp: { name: __classPrivateFieldGet(this, _PasskeyController_rpName, "f"), id: __classPrivateFieldGet(this, _PasskeyController_rpID, "f") },
+            rp: {
+                name: __classPrivateFieldGet(this, _PasskeyController_rpName, "f"),
+                id: __classPrivateFieldGet(this, _PasskeyController_rpId, "f"),
+            },
             user: {
                 id: userHandle,
                 name: __classPrivateFieldGet(this, _PasskeyController_userName, "f"),
@@ -154,30 +155,72 @@ class PasskeyController extends base_controller_1.BaseController {
         };
         __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").saveRegistrationCeremony(challenge, {
             userHandle,
-            prfSalt: prfSalt ?? '',
+            prfSalt,
             challenge,
             createdAt: Date.now(),
         });
         return options;
     }
     /**
-     * WebAuthn request options for authenticating with the enrolled passkey.
+     * Builds WebAuthn credential request options for the post-registration
+     * authentication step (between `create` and {@link protectVaultKeyWithPasskey}).
      *
-     * Call before {@link retrieveVaultKeyWithPasskey},
-     * {@link verifyPasskeyAuthentication}, or {@link renewVaultKeyProtection}.
+     * @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 = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_getChallengeFromClientData).call(this, registrationResponse.response.clientDataJSON);
+        const registrationCeremony = __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").getRegistrationCeremony(regChallenge);
+        if (!registrationCeremony) {
+            log('No active passkey registration ceremony for challenge');
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NoRegistrationCeremony, { code: constants_1.PasskeyControllerErrorCode.NoRegistrationCeremony });
+        }
+        // build auth options
+        const challenge = (0, crypto_1.randomBytesToBase64URL)(32);
+        const extensions = {};
+        if (registrationCeremony.prfSalt) {
+            extensions.prf = { eval: { first: registrationCeremony.prfSalt } };
+        }
+        const options = {
+            challenge,
+            rpId: __classPrivateFieldGet(this, _PasskeyController_rpId, "f"),
+            allowCredentials: [
+                {
+                    id: registrationResponse.id,
+                    type: 'public-key',
+                    transports: registrationResponse.response.transports,
+                },
+            ],
+            userVerification: 'preferred',
+            hints: ['client-device', 'hybrid'],
+            timeout: ceremony_manager_1.WEBAUTHN_TIMEOUT_MS,
+            extensions,
+        };
+        // save auth ceremony
+        __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").saveAuthenticationCeremony(challenge, {
+            challenge,
+            createdAt: Date.now(),
+        });
+        return options;
+    }
+    /**
+     * Builds WebAuthn credential request options for the enrolled passkey.
      *
-     * @returns Options for `navigator.credentials.get()`.
+     * @returns Public key credential request 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 challenge = (0, crypto_1.randomBytesToBase64URL)(32);
         const extensions = {};
         if (record.keyDerivation.method === 'prf') {
             extensions.prf = { eval: { first: record.keyDerivation.prfSalt } };
         }
         const options = {
             challenge,
-            rpId: __classPrivateFieldGet(this, _PasskeyController_rpID, "f"),
+            rpId: __classPrivateFieldGet(this, _PasskeyController_rpId, "f"),
             allowCredentials: [
                 {
                     id: record.credential.id,
@@ -197,15 +240,20 @@ class PasskeyController extends base_controller_1.BaseController {
         return options;
     }
     /**
-     * Completes enrollment and binds the vault key to the new passkey.
+     * Verifies registration and post-registration authentication, then stores the
+     * vault key encrypted under the new passkey.
      *
-     * @param params - Protection parameters.
-     * @param params.registrationResponse - Credential from `navigator.credentials.create()`.
-     * @param params.vaultKey - Vault encryption key to protect.
+     * @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.vaultKey - Vault encryption key to encrypt and persist.
      */
     async protectVaultKeyWithPasskey(params) {
-        const { registrationResponse, vaultKey } = params;
-        // get challenge
+        if (this.isPasskeyEnrolled()) {
+            throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.AlreadyEnrolled, { code: constants_1.PasskeyControllerErrorCode.AlreadyEnrolled });
+        }
+        const { registrationResponse, authenticationResponse, vaultKey } = params;
+        // get registration ceremony
         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) {
@@ -218,7 +266,7 @@ class PasskeyController extends base_controller_1.BaseController {
                 response: registrationResponse,
                 expectedChallenge: registrationCeremony.challenge,
                 expectedOrigin: __classPrivateFieldGet(this, _PasskeyController_expectedOrigin, "f"),
-                expectedRPID: __classPrivateFieldGet(this, _PasskeyController_rpID, "f"),
+                expectedRPIDs: __classPrivateFieldGet(this, _PasskeyController_expectedRPIDs, "f"),
                 requireUserVerification: false,
             }).catch((error) => {
                 log('Error verifying passkey registration response', error);
@@ -231,19 +279,36 @@ class PasskeyController extends base_controller_1.BaseController {
                 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
+            // verify authentication response
+            const credential = {
+                id: registrationInfo.credentialId,
+                publicKey: (0, encoding_1.bytesToBase64URL)(registrationInfo.publicKey),
+                counter: registrationInfo.counter,
+                transports: registrationInfo.transports,
+                aaguid: registrationInfo.aaguid,
+            };
+            const { newCounter } = await __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_verifyAuthenticationResponse).call(this, authenticationResponse, credential);
+            // determine key derivation method
+            const prfFirst = authenticationResponse.clientExtensionResults?.prf?.results?.first;
+            const authHasPrfOutput = typeof prfFirst === 'string' && prfFirst.length > 0;
+            const keyDerivation = authHasPrfOutput && registrationCeremony.prfSalt
+                ? { method: 'prf', prfSalt: registrationCeremony.prfSalt }
+                : { method: 'userHandle' };
+            if (keyDerivation.method === 'userHandle' &&
+                authenticationResponse.response.userHandle !==
+                    registrationCeremony.userHandle) {
+                log('Post-registration assertion userHandle does not match registration ceremony');
+                throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.AuthenticationVerificationFailed, { code: constants_1.PasskeyControllerErrorCode.AuthenticationVerificationFailed });
+            }
+            // derive key and encrypt vault key
+            const encKey = (0, key_derivation_1.deriveKeyFromAuthenticationResponse)(authenticationResponse, { credential, keyDerivation });
             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,
-                        aaguid: registrationInfo.aaguid,
+                        ...credential,
+                        counter: Math.max(newCounter, credential.counter),
                     },
                     encryptedVaultKey: { ciphertext, iv },
                     keyDerivation,
@@ -251,26 +316,32 @@ class PasskeyController extends base_controller_1.BaseController {
             });
         }
         finally {
+            // delete registration ceremony
             __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").deleteRegistrationCeremony(challenge);
         }
     }
     /**
-     * Returns the decrypted vault encryption key from the passkey authentication
-     * response.
+     * Verifies an authentication assertion and returns the decrypted vault key.
      *
-     * @param authenticationResponse - Credential from `navigator.credentials.get()`.
-     * @returns The vault encryption key.
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns The plaintext 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);
+        // verify authentication response and update counter
+        const { newCounter } = await __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_verifyAuthenticationResponse).call(this, authenticationResponse, passkeyRecord.credential);
+        this.update((state) => {
+            if (!state.passkeyRecord) {
+                throw new errors_1.PasskeyControllerError(constants_1.PasskeyControllerErrorMessage.NotEnrolled, { code: constants_1.PasskeyControllerErrorCode.NotEnrolled });
+            }
+            state.passkeyRecord.credential.counter = Math.max(newCounter, state.passkeyRecord.credential.counter);
+        });
+        // derive key
         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);
+            const vaultKey = (0, crypto_1.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)));
@@ -279,18 +350,15 @@ class PasskeyController extends base_controller_1.BaseController {
                 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).
+     * Checks whether the given authentication assertion is valid for the enrolled passkey.
      *
-     * Returns `false` only when the failure is a {@link PasskeyControllerError}
-     * with a defined `code`. Unexpected errors (e.g. malformed `clientDataJSON`,
-     * internal bugs) are rethrown.
+     * On failure, returns `false` for {@link PasskeyControllerError} with a `code`;
+     * other errors propagate.
      *
-     * @param authenticationResponse - Credential from `navigator.credentials.get()`.
-     * @returns `true` if authentication succeeds, otherwise `false`.
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns `true` if verification succeeds, otherwise `false`.
      */
     async verifyPasskeyAuthentication(authenticationResponse) {
         try {
@@ -305,19 +373,17 @@ class PasskeyController extends base_controller_1.BaseController {
         }
     }
     /**
-     * Updates the vault encryption key for the same passkey (e.g. after a password change).
+     * Re-wraps the vault key after rotation. Updates persisted `encryptedVaultKey` on success.
      *
-     * 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.
+     * 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}).
      *
-     * @param params - Renewal parameters.
-     * @param params.authenticationResponse - Credential from `navigator.credentials.get()`,
-     *   already verified by the caller.
+     * @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 protect.
+     * @param params.newVaultKey - New vault key to encrypt under the passkey.
      */
     async renewVaultKeyProtection(params) {
         const { authenticationResponse } = params;
@@ -355,7 +421,8 @@ class PasskeyController extends base_controller_1.BaseController {
         });
     }
     /**
-     * Unenrolls the passkey, removing the protected vault key material.
+     * Clears enrolled passkey state and in-flight ceremonies. Call only after the same
+     * auth gate as renewal (verified passkey assertion or password).
      */
     removePasskey() {
         this.update(() => getDefaultPasskeyControllerState());
@@ -376,7 +443,7 @@ class PasskeyController extends base_controller_1.BaseController {
     }
 }
 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() {
+_PasskeyController_ceremonyManager = new WeakMap(), _PasskeyController_expectedRPIDs = 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, {
@@ -388,34 +455,33 @@ _PasskeyController_ceremonyManager = new WeakMap(), _PasskeyController_rpID = ne
     return (0, decode_client_data_json_1.decodeClientDataJSON)(clientDataJSON).challenge;
 }, _PasskeyController_verifyAuthenticationResponse = 
 /**
- * Verifies an authentication response for the enrolled passkey.
+ * Validates a WebAuthn authentication response against stored credential data.
  *
- * @param authenticationResponse - Authentication result JSON.
+ * @param authenticationResponse - Parsed authentication response from the client.
+ * @param credential - Credential identifiers and public key material for verification.
+ * @returns Updated authenticator signature counter.
  */
-async function _PasskeyController_verifyAuthenticationResponse(authenticationResponse) {
-    let challenge;
+async function _PasskeyController_verifyAuthenticationResponse(authenticationResponse, credential) {
+    // get challenge
+    const challenge = __classPrivateFieldGet(this, _PasskeyController_instances, "m", _PasskeyController_getChallengeFromClientData).call(this, authenticationResponse.response.clientDataJSON);
+    // 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 });
+    }
     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"),
+            expectedRPIDs: __classPrivateFieldGet(this, _PasskeyController_expectedRPIDs, "f"),
             credential: {
-                id: record.credential.id,
-                publicKey: (0, encoding_1.base64URLToBytes)(record.credential.publicKey),
-                counter: record.credential.counter,
-                transports: record.credential.transports,
+                id: credential.id,
+                publicKey: (0, encoding_1.base64URLToBytes)(credential.publicKey),
+                counter: credential.counter,
+                transports: credential.transports,
             },
             // UV optional for device compatibility; vault key remains password-gated.
             requireUserVerification: false,
@@ -432,19 +498,11 @@ async function _PasskeyController_verifyAuthenticationResponse(authenticationRes
                 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);
-        });
+        return { newCounter: result.authenticationInfo.newCounter };
     }
     finally {
-        if (challenge) {
-            __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").deleteAuthenticationCeremony(challenge);
-        }
+        // delete authentication ceremony
+        __classPrivateFieldGet(this, _PasskeyController_ceremonyManager, "f").deleteAuthenticationCeremony(challenge);
     }
 };
 //# sourceMappingURL=PasskeyController.cjs.map