@metamask/passkey-controller 3.1.0 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.0]
+
+### Added
+
+- Add PRF migration methods for enrolled legacy `userHandle` passkeys ([#10310](https://github.com/MetaMask/core/pull/10310))
+  - `generatePasskeyReplacementRegistrationOptions` stages a PRF-only
+    replacement registration while retaining the existing record.
+  - `completePasskeyReplacement` verifies the replacement registration and PRF
+    assertion, re-wraps the vault key, and atomically commits the new record.
+  - `cancelPasskeyReplacement` removes the targeted replacement ceremony and
+    its linked post-registration authentication ceremony.
+
+### Changed
+
+- Use `@metamask/utils` SHA-256, SHA-384, and SHA-512 digests for asynchronous WebAuthn verification and RP ID matching, while retaining Noble SHA-256 for synchronous HKDF ([#10188](https://github.com/MetaMask/core/pull/10188))
+- Bump `@metamask/utils` from `^11.12.0` to `^12.0.0` ([#10192](https://github.com/MetaMask/core/pull/10192))
+
+### Fixed
+
+- Keep replacement ceremonies retryable after password and vault-key export failures ([#10310](https://github.com/MetaMask/core/pull/10310))
+
+## [4.0.0]
+
+### Changed
+
+- **BREAKING:** Drop CommonJS support ([#9536](https://github.com/MetaMask/core/pull/9536))
+  - This package is now ESM-only, but can still be used in CommonJS projects via `require(esm)` in modern Node.js versions (22+), or dynamic imports in older Node.js versions.
+- **BREAKING:** Bump minimum Node.js version to 22 ([#9976](https://github.com/MetaMask/core/pull/9976))
+- **BREAKING:** Bump TypeScript target to ES2022 ([#10019](https://github.com/MetaMask/core/pull/10019))
+  - This package now ships ES2022 code, requiring a compatible modern environment or bundler configuration to consume.
+- Bump `@metamask/utils` from `^11.11.0` to `^11.12.0` ([#10076](https://github.com/MetaMask/core/pull/10076))
+- Bump `@metamask/base-controller` from `^9.1.0` to `^10.0.0` ([#10160](https://github.com/MetaMask/core/pull/10160))
+- Bump `@metamask/keyring-controller` from `^27.1.1` to `^28.0.0` ([#10160](https://github.com/MetaMask/core/pull/10160))
+- Bump `@metamask/messenger` from `^2.0.0` to `^3.0.0` ([#10160](https://github.com/MetaMask/core/pull/10160))
+
 ## [3.1.0]
 
 ### Added
@@ -112,7 +147,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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/compare/@metamask/passkey-controller@3.1.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/passkey-controller@4.1.0...HEAD
+[4.1.0]: https://github.com/MetaMask/core/compare/@metamask/passkey-controller@4.0.0...@metamask/passkey-controller@4.1.0
+[4.0.0]: https://github.com/MetaMask/core/compare/@metamask/passkey-controller@3.1.0...@metamask/passkey-controller@4.0.0
 [3.1.0]: https://github.com/MetaMask/core/compare/@metamask/passkey-controller@3.0.0...@metamask/passkey-controller@3.1.0
 [3.0.0]: https://github.com/MetaMask/core/compare/@metamask/passkey-controller@2.1.0...@metamask/passkey-controller@3.0.0
 [2.1.0]: https://github.com/MetaMask/core/compare/@metamask/passkey-controller@2.0.1...@metamask/passkey-controller@2.1.0

package/README.md

@@ -87,6 +87,91 @@ await controller.protectVaultKeyWithPasskey({
 });
 ```
 
+### Migrating a `userHandle` passkey to PRF
+
+Use the dedicated replacement flow for an enrolled passkey whose
+`passkeyRecord.keyDerivation.method` is `userHandle`. The existing record
+remains active until the replacement is fully verified and the vault key has
+been wrapped with the new PRF-derived key.
+
+```mermaid
+flowchart LR
+    n1["PasskeyCtrl:migrateToPRF"] --> n2["PasskeyCtrl:register"]
+    n2 --> n3["PRF Supported"]
+    n3 --> n6["YES"] & n7["NO"]
+    n7 --> n4["Do Nothing"]
+    n6 --> n5["PasskeyCtrl:verify"]
+    n5 --> n8["Success"]
+    n8 --> n9["YES"] & n10["NO"]
+    n10 --> n4
+    n9 --> n11["PasskeyCtrl:replaceUserHandleRecord"]
+    n4 --> n12["Continue with current userHandle passkey"]
+
+    n1@{ shape: rounded}
+    n2@{ shape: rounded}
+    n3@{ shape: diam}
+    n6@{ shape: rect}
+    n7@{ shape: rect}
+    n4@{ shape: rect}
+    n5@{ shape: rounded}
+    n8@{ shape: diam}
+    n9@{ shape: rect}
+    n10@{ shape: rect}
+    n11@{ shape: rounded}
+    n12@{ shape: rect}
+```
+
+In the client side,
+
+```typescript
+// 1. Stage a PRF-only replacement registration.
+const replacementOptions =
+  controller.generatePasskeyReplacementRegistrationOptions();
+
+let replacementRegistrationResponse;
+let replacementAuthenticationResponse;
+try {
+  // 2. Register the new authenticator. The old credential is excluded.
+  replacementRegistrationResponse = await navigator.credentials.create({
+    publicKey: replacementOptions,
+  });
+
+  // 3. Request the post-registration PRF assertion.
+  const replacementAuthenticationOptions =
+    controller.generatePostRegistrationAuthenticationOptions({
+      registrationResponse: replacementRegistrationResponse,
+    });
+  replacementAuthenticationResponse = await navigator.credentials.get({
+    publicKey: replacementAuthenticationOptions,
+  });
+} catch (error) {
+  // Call this when the browser ceremony is canceled or abandoned before
+  // completion. TTL pruning remains the fallback if this is not called.
+  controller.cancelPasskeyReplacement(replacementOptions.challenge);
+  throw error;
+}
+
+// 4. Verify both responses and atomically replace the persisted record.
+await controller.completePasskeyReplacement({
+  registrationResponse: replacementRegistrationResponse,
+  authenticationResponse: replacementAuthenticationResponse,
+  password: settingsEnroll ? walletPassword : undefined,
+});
+```
+
+The replacement authentication response must contain non-empty PRF output;
+there is no `userHandle` fallback. After onboarding, the `password` argument
+is required for the same step-up authorization used by normal enrollment.
+A missing or wrong password, or a failed vault-key export, leaves the
+replacement ceremony in place so the same `create()`/`get()` responses can be
+retried. `cancelPasskeyReplacement` removes only the targeted replacement
+ceremony and its linked post-registration authentication ceremony; it does
+not remove the enrolled passkey.
+
+The atomicity guarantee applies to the controller state update. If the wallet's
+generic persistence subscriber cannot write the new state, it logs the failure
+and the previous record may remain on disk for the next restart.
+
 ### Passkey unlock (authentication)
 
 Prefer `unlockWithPasskey`, which verifies the assertion and submits the vault key to KeyringController.
@@ -102,14 +187,17 @@ await controller.unlockWithPasskey(response);
 
 These methods combine passkey verification with KeyringController calls. Use them from UI layers that already performed `navigator.credentials.get()`.
 
-| Method                                  | Purpose                                                   |
-| --------------------------------------- | --------------------------------------------------------- |
-| `unlockWithPasskey`                     | Unlock keyring after passkey assertion                    |
-| `removePasskeyWithPasskeyVerification`  | Remove passkey after assertion step-up                    |
-| `removePasskeyWithPasswordVerification` | Remove passkey after password step-up                     |
-| `changePasswordWithPasskeyVerification` | Change password; re-wrap vault key by default             |
-| `exportSeedPhraseWithPasskey`           | Export SRP bytes after assertion step-up                  |
-| `exportAccountsWithPasskey`             | Export private keys for addresses after assertion step-up |
+| Method                                          | Purpose                                                      |
+| ----------------------------------------------- | ------------------------------------------------------------ |
+| `unlockWithPasskey`                             | Unlock keyring after passkey assertion                       |
+| `generatePasskeyReplacementRegistrationOptions` | Generate PRF-only replacement registration options           |
+| `completePasskeyReplacement`                    | Verify and atomically complete `userHandle` → PRF migration  |
+| `cancelPasskeyReplacement`                      | Cancel one replacement ceremony and its linked auth ceremony |
+| `removePasskeyWithPasskeyVerification`          | Remove passkey after assertion step-up                       |
+| `removePasskeyWithPasswordVerification`         | Remove passkey after password step-up                        |
+| `changePasswordWithPasskeyVerification`         | Change password; re-wrap vault key by default                |
+| `exportSeedPhraseWithPasskey`                   | Export SRP bytes after assertion step-up                     |
+| `exportAccountsWithPasskey`                     | Export private keys for addresses after assertion step-up    |
 
 ```typescript
 // Change password (re-wraps passkey protection by default)
@@ -164,7 +252,8 @@ passkeyControllerSelectors.selectIsPasskeyEnrolled(state); // boolean
 cases use a stable `code` from `PasskeyControllerErrorCode` (for example:
 `not_enrolled`, `already_enrolled`, `no_registration_ceremony`,
 `authentication_verification_failed`, `missing_key_material`, `vault_key_decryption_failed`,
-`vault_key_mismatch`, `vault_key_renewal_failed`, `enrollment_password_required`). Human-readable strings
+`vault_key_mismatch`, `vault_key_renewal_failed`, `enrollment_password_required`,
+`migration_not_required`, `prf_required`, `replacement_source_changed`). 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
@@ -188,6 +277,9 @@ those controller errors (with `code`) and rethrows everything else.
 | `PasskeyController:getState`                                      | Persisted `passkeyRecord`                  |
 | `PasskeyController:isPasskeyEnrolled`                             | Enrollment boolean                         |
 | `PasskeyController:generateRegistrationOptions`                   | WebAuthn `create()` options                |
+| `PasskeyController:generatePasskeyReplacementRegistrationOptions` | PRF replacement `create()` options         |
+| `PasskeyController:completePasskeyReplacement`                    | Complete PRF replacement                   |
+| `PasskeyController:cancelPasskeyReplacement`                      | Cancel one replacement ceremony            |
 | `PasskeyController:generatePostRegistrationAuthenticationOptions` | WebAuthn `get()` after `create()`          |
 | `PasskeyController:generateAuthenticationOptions`                 | WebAuthn `get()` for unlock / step-up      |
 | `PasskeyController:protectVaultKeyWithPasskey`                    | Enroll: verify ceremonies + wrap vault key |

package/dist/{PasskeyController-method-action-types.d.mts → PasskeyController-method-action-types.d.ts}

@@ -2,7 +2,7 @@
  * This file is auto generated.
  * Do not edit manually.
  */
-import type { PasskeyController } from "./PasskeyController.mjs";
+import type { PasskeyController } from './PasskeyController.js';
 /**
  * Whether a passkey is enrolled and vault key material is stored.
  *
@@ -23,6 +23,47 @@ export type PasskeyControllerGenerateRegistrationOptionsAction = {
     type: `PasskeyController:generateRegistrationOptions`;
     handler: PasskeyController['generateRegistrationOptions'];
 };
+/**
+ * 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()`.
+ */
+export type PasskeyControllerGeneratePasskeyReplacementRegistrationOptionsAction = {
+    type: `PasskeyController:generatePasskeyReplacementRegistrationOptions`;
+    handler: PasskeyController['generatePasskeyReplacementRegistrationOptions'];
+};
+/**
+ * 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.
+ */
+export type PasskeyControllerCompletePasskeyReplacementAction = {
+    type: `PasskeyController:completePasskeyReplacement`;
+    handler: PasskeyController['completePasskeyReplacement'];
+};
+/**
+ * Cancels an in-flight passkey replacement ceremony.
+ *
+ * @param registrationChallenge - Challenge returned by
+ * {@link generatePasskeyReplacementRegistrationOptions}.
+ */
+export type PasskeyControllerCancelPasskeyReplacementAction = {
+    type: `PasskeyController:cancelPasskeyReplacement`;
+    handler: PasskeyController['cancelPasskeyReplacement'];
+};
 /**
  * Builds WebAuthn credential request options for the post-registration
  * authentication step (between `create` and {@link protectVaultKeyWithPasskey}).
@@ -200,5 +241,5 @@ export type PasskeyControllerDestroyAction = {
 /**
  * Union of all PasskeyController action types.
  */
-export type PasskeyControllerMethodActions = PasskeyControllerIsPasskeyEnrolledAction | PasskeyControllerGenerateRegistrationOptionsAction | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction | PasskeyControllerGenerateAuthenticationOptionsAction | PasskeyControllerProtectVaultKeyWithPasskeyAction | PasskeyControllerRetrieveVaultKeyWithPasskeyAction | PasskeyControllerUnlockWithPasskeyAction | PasskeyControllerExportSeedPhraseWithPasskeyAction | PasskeyControllerExportAccountsWithPasskeyAction | PasskeyControllerVerifyPasskeyAuthenticationAction | PasskeyControllerRenewVaultKeyProtectionAction | PasskeyControllerChangePasswordWithPasskeyVerificationAction | PasskeyControllerRemovePasskeyWithPasskeyVerificationAction | PasskeyControllerRemovePasskeyWithPasswordVerificationAction | PasskeyControllerClearStateAction | PasskeyControllerDestroyAction;
-//# sourceMappingURL=PasskeyController-method-action-types.d.mts.map
+export type PasskeyControllerMethodActions = PasskeyControllerIsPasskeyEnrolledAction | PasskeyControllerGenerateRegistrationOptionsAction | PasskeyControllerGeneratePasskeyReplacementRegistrationOptionsAction | PasskeyControllerCompletePasskeyReplacementAction | PasskeyControllerCancelPasskeyReplacementAction | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction | PasskeyControllerGenerateAuthenticationOptionsAction | PasskeyControllerProtectVaultKeyWithPasskeyAction | PasskeyControllerRetrieveVaultKeyWithPasskeyAction | PasskeyControllerUnlockWithPasskeyAction | PasskeyControllerExportSeedPhraseWithPasskeyAction | PasskeyControllerExportAccountsWithPasskeyAction | PasskeyControllerVerifyPasskeyAuthenticationAction | PasskeyControllerRenewVaultKeyProtectionAction | PasskeyControllerChangePasswordWithPasskeyVerificationAction | PasskeyControllerRemovePasskeyWithPasskeyVerificationAction | PasskeyControllerRemovePasskeyWithPasswordVerificationAction | PasskeyControllerClearStateAction | PasskeyControllerDestroyAction;
+//# sourceMappingURL=PasskeyController-method-action-types.d.ts.map

package/dist/PasskeyController-method-action-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PasskeyController-method-action-types.d.ts","sourceRoot":"","sources":["../src/PasskeyController-method-action-types.ts"],"names":[],"mappings":"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"}

package/dist/{PasskeyController-method-action-types.mjs → PasskeyController-method-action-types.js}

@@ -3,4 +3,4 @@
  * Do not edit manually.
  */
 export {};
-//# sourceMappingURL=PasskeyController-method-action-types.mjs.map
+//# sourceMappingURL=PasskeyController-method-action-types.js.map

package/dist/PasskeyController-method-action-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PasskeyController-method-action-types.js","sourceRoot":"","sources":["../src/PasskeyController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { PasskeyController } from './PasskeyController.js';\n\n/**\n * Whether a passkey is enrolled and vault key material is stored.\n *\n * @returns `true` if enrolled, otherwise `false`.\n */\nexport type PasskeyControllerIsPasskeyEnrolledAction = {\n  type: `PasskeyController:isPasskeyEnrolled`;\n  handler: PasskeyController['isPasskeyEnrolled'];\n};\n\n/**\n * Builds WebAuthn credential creation options for passkey enrollment.\n *\n * @param creationOptionsConfig - Optional creation behavior.\n * @param creationOptionsConfig.prfAvailable - Request the PRF extension unless `false`. Defaults to `true`.\n * @returns Public key credential creation options for `navigator.credentials.create()`.\n */\nexport type PasskeyControllerGenerateRegistrationOptionsAction = {\n  type: `PasskeyController:generateRegistrationOptions`;\n  handler: PasskeyController['generateRegistrationOptions'];\n};\n\n/**\n * Builds WebAuthn credential creation options for replacing a userHandle\n * passkey with a PRF-capable passkey.\n *\n * The existing passkey record is retained while the replacement ceremony is\n * in flight.\n *\n * @returns Public key credential creation options for `navigator.credentials.create()`.\n */\nexport type PasskeyControllerGeneratePasskeyReplacementRegistrationOptionsAction =\n  {\n    type: `PasskeyController:generatePasskeyReplacementRegistrationOptions`;\n    handler: PasskeyController['generatePasskeyReplacementRegistrationOptions'];\n  };\n\n/**\n * Verifies and completes replacement of an enrolled userHandle passkey with\n * a PRF-capable passkey.\n *\n * The existing passkey record remains active until the replacement\n * registration and post-registration authentication have both been verified\n * and the existing vault key has been wrapped with the new PRF-derived key.\n *\n * @param params - Replacement completion inputs.\n * @param params.registrationResponse - Result of `navigator.credentials.create()`.\n * @param params.authenticationResponse - Result of `navigator.credentials.get()`\n * after {@link generatePostRegistrationAuthenticationOptions}.\n * @returns Resolves when the replacement completes.\n */\nexport type PasskeyControllerCompletePasskeyReplacementAction = {\n  type: `PasskeyController:completePasskeyReplacement`;\n  handler: PasskeyController['completePasskeyReplacement'];\n};\n\n/**\n * Cancels an in-flight passkey replacement ceremony.\n *\n * @param registrationChallenge - Challenge returned by\n * {@link generatePasskeyReplacementRegistrationOptions}.\n */\nexport type PasskeyControllerCancelPasskeyReplacementAction = {\n  type: `PasskeyController:cancelPasskeyReplacement`;\n  handler: PasskeyController['cancelPasskeyReplacement'];\n};\n\n/**\n * Builds WebAuthn credential request options for the post-registration\n * authentication step (between `create` and {@link protectVaultKeyWithPasskey}).\n *\n * @param params - Input for the pending registration ceremony.\n * @param params.registrationResponse - Result of `navigator.credentials.create()`.\n * @returns Public key credential request options for `navigator.credentials.get()`.\n */\nexport type PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction =\n  {\n    type: `PasskeyController:generatePostRegistrationAuthenticationOptions`;\n    handler: PasskeyController['generatePostRegistrationAuthenticationOptions'];\n  };\n\n/**\n * Builds WebAuthn credential request options for the enrolled passkey.\n *\n * @returns Public key credential request options for `navigator.credentials.get()`.\n */\nexport type PasskeyControllerGenerateAuthenticationOptionsAction = {\n  type: `PasskeyController:generateAuthenticationOptions`;\n  handler: PasskeyController['generateAuthenticationOptions'];\n};\n\n/**\n * Verifies registration and post-registration authentication, then stores the\n * vault key encrypted under the new passkey.\n *\n * Fetches the current vault encryption key from KeyringController before wrapping.\n * When onboarding is complete, requires `password` for step-up verification first.\n *\n * @param params - Enrollment completion inputs.\n * @param params.registrationResponse - Result of `navigator.credentials.create()`.\n * @param params.authenticationResponse - Result of `navigator.credentials.get()` after {@link generatePostRegistrationAuthenticationOptions}.\n * @param params.password - Wallet password when onboarding is complete (step-up).\n * @returns Resolves when enrollment completes.\n */\nexport type PasskeyControllerProtectVaultKeyWithPasskeyAction = {\n  type: `PasskeyController:protectVaultKeyWithPasskey`;\n  handler: PasskeyController['protectVaultKeyWithPasskey'];\n};\n\n/**\n * Verifies an authentication assertion and returns the decrypted vault key.\n *\n * Prefer orchestrated methods ({@link unlockWithPasskey},\n * {@link exportSeedPhraseWithPasskey}, {@link exportAccountsWithPasskey}) for product\n * flows instead of calling KeyringController with the returned key manually.\n *\n * @param authenticationResponse - Result of `navigator.credentials.get()`.\n * @returns The plaintext vault encryption key.\n */\nexport type PasskeyControllerRetrieveVaultKeyWithPasskeyAction = {\n  type: `PasskeyController:retrieveVaultKeyWithPasskey`;\n  handler: PasskeyController['retrieveVaultKeyWithPasskey'];\n};\n\n/**\n * Unlocks the keyring using a passkey authentication assertion.\n *\n * @param authenticationResponse - Result of `navigator.credentials.get()`.\n * @returns Resolves when the keyring is unlocked.\n */\nexport type PasskeyControllerUnlockWithPasskeyAction = {\n  type: `PasskeyController:unlockWithPasskey`;\n  handler: PasskeyController['unlockWithPasskey'];\n};\n\n/**\n * Exports the seed phrase after passkey step-up authentication.\n *\n * @param authenticationResponse - Result of `navigator.credentials.get()`.\n * @param keyringId - Optional keyring id; defaults to the primary HD keyring.\n * @returns Raw seed phrase bytes from KeyringController.\n */\nexport type PasskeyControllerExportSeedPhraseWithPasskeyAction = {\n  type: `PasskeyController:exportSeedPhraseWithPasskey`;\n  handler: PasskeyController['exportSeedPhraseWithPasskey'];\n};\n\n/**\n * Exports private keys for the given addresses after passkey step-up authentication.\n *\n * @param authenticationResponse - Result of `navigator.credentials.get()`.\n * @param addresses - Account addresses to export.\n * @returns Private keys in the same order as `addresses`.\n */\nexport type PasskeyControllerExportAccountsWithPasskeyAction = {\n  type: `PasskeyController:exportAccountsWithPasskey`;\n  handler: PasskeyController['exportAccountsWithPasskey'];\n};\n\n/**\n * Checks whether the given authentication assertion is valid for the enrolled passkey.\n *\n * On failure, returns `false` for {@link PasskeyControllerError} with a `code`;\n * other errors propagate.\n *\n * @param authenticationResponse - Result of `navigator.credentials.get()`.\n * @returns `true` if verification succeeds, otherwise `false`.\n */\nexport type PasskeyControllerVerifyPasskeyAuthenticationAction = {\n  type: `PasskeyController:verifyPasskeyAuthentication`;\n  handler: PasskeyController['verifyPasskeyAuthentication'];\n};\n\n/**\n * Re-wraps the vault key after rotation. Updates persisted `encryptedVaultKey` on success.\n *\n * Does not verify WebAuthn or ceremony state—call only after your layer has authenticated\n * the user (passkey `get()` + verified assertion, or verified password). On passkey paths,\n * pass the same `authenticationResponse` you just verified (e.g. from\n * {@link retrieveVaultKeyWithPasskey} / {@link verifyPasskeyAuthentication}).\n *\n * For password change with passkey step-up, prefer\n * {@link changePasswordWithPasskeyVerification}, which orchestrates keyring export,\n * `changePassword`, and re-wrap in one call.\n *\n * @param params - Re-wrap inputs.\n * @param params.authenticationResponse - Used to derive the wrapping key.\n * @param params.oldVaultKey - Expected current vault key.\n * @param params.newVaultKey - New vault key to encrypt under the passkey.\n * @returns Resolves when the passkey record is updated.\n */\nexport type PasskeyControllerRenewVaultKeyProtectionAction = {\n  type: `PasskeyController:renewVaultKeyProtection`;\n  handler: PasskeyController['renewVaultKeyProtection'];\n};\n\n/**\n * Changes the wallet password after passkey step-up authentication.\n *\n * When `renewVaultKeyProtection` is `true` (default), re-wraps the vault key under the\n * passkey after rotation. When `false`, removes the passkey instead.\n *\n * @param params - Change-password inputs.\n * @param params.newPassword - New wallet password.\n * @param params.authenticationResponse - Result of `navigator.credentials.get()`.\n * @param params.options - Optional flow controls.\n * @param params.options.renewVaultKeyProtection - Re-wrap vault key after password change.\n * @returns Resolves when the password change completes.\n */\nexport type PasskeyControllerChangePasswordWithPasskeyVerificationAction = {\n  type: `PasskeyController:changePasswordWithPasskeyVerification`;\n  handler: PasskeyController['changePasswordWithPasskeyVerification'];\n};\n\n/**\n * Removes the enrolled passkey after verifying a passkey authentication assertion.\n *\n * @param authenticationResponse - Result of `navigator.credentials.get()`.\n * @returns Resolves when the passkey is removed.\n */\nexport type PasskeyControllerRemovePasskeyWithPasskeyVerificationAction = {\n  type: `PasskeyController:removePasskeyWithPasskeyVerification`;\n  handler: PasskeyController['removePasskeyWithPasskeyVerification'];\n};\n\n/**\n * Removes the enrolled passkey after verifying the wallet password.\n *\n * @param password - Wallet password for step-up verification.\n * @returns Resolves when the passkey is removed.\n */\nexport type PasskeyControllerRemovePasskeyWithPasswordVerificationAction = {\n  type: `PasskeyController:removePasskeyWithPasswordVerification`;\n  handler: PasskeyController['removePasskeyWithPasswordVerification'];\n};\n\n/**\n * Resets state and clears in-flight registration/authentication ceremonies.\n *\n * For user-facing passkey removal with step-up, use\n * {@link removePasskeyWithPasskeyVerification} or\n * {@link removePasskeyWithPasswordVerification}.\n */\nexport type PasskeyControllerClearStateAction = {\n  type: `PasskeyController:clearState`;\n  handler: PasskeyController['clearState'];\n};\n\n/**\n * Releases all in-flight ceremony state and tears down the messenger.\n */\nexport type PasskeyControllerDestroyAction = {\n  type: `PasskeyController:destroy`;\n  handler: PasskeyController['destroy'];\n};\n\n/**\n * Union of all PasskeyController action types.\n */\nexport type PasskeyControllerMethodActions =\n  | PasskeyControllerIsPasskeyEnrolledAction\n  | PasskeyControllerGenerateRegistrationOptionsAction\n  | PasskeyControllerGeneratePasskeyReplacementRegistrationOptionsAction\n  | PasskeyControllerCompletePasskeyReplacementAction\n  | PasskeyControllerCancelPasskeyReplacementAction\n  | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction\n  | PasskeyControllerGenerateAuthenticationOptionsAction\n  | PasskeyControllerProtectVaultKeyWithPasskeyAction\n  | PasskeyControllerRetrieveVaultKeyWithPasskeyAction\n  | PasskeyControllerUnlockWithPasskeyAction\n  | PasskeyControllerExportSeedPhraseWithPasskeyAction\n  | PasskeyControllerExportAccountsWithPasskeyAction\n  | PasskeyControllerVerifyPasskeyAuthenticationAction\n  | PasskeyControllerRenewVaultKeyProtectionAction\n  | PasskeyControllerChangePasswordWithPasskeyVerificationAction\n  | PasskeyControllerRemovePasskeyWithPasskeyVerificationAction\n  | PasskeyControllerRemovePasskeyWithPasswordVerificationAction\n  | PasskeyControllerClearStateAction\n  | PasskeyControllerDestroyAction;\n"]}

package/dist/{PasskeyController.d.cts → PasskeyController.d.ts}

@@ -1,8 +1,8 @@
-import { BaseController } from "@metamask/base-controller";
-import { controllerName } from "./constants.cjs";
-import type { PasskeyControllerMessenger, PasskeyControllerOptions, PasskeyControllerState } from "./types.cjs";
-import type { PasskeyAuthenticationOptions, PasskeyAuthenticationResponse, PasskeyRegistrationOptions, PasskeyRegistrationResponse } from "./webauthn/types.cjs";
-export type { PasskeyControllerActions, PasskeyControllerAllowedActions, PasskeyControllerEvents, PasskeyControllerGetStateAction, PasskeyControllerMessenger, PasskeyControllerOptions, PasskeyControllerState, PasskeyControllerStateChangedEvent, } from "./types.cjs";
+import { BaseController } from '@metamask/base-controller';
+import { controllerName } from './constants.js';
+import type { PasskeyControllerMessenger, PasskeyControllerOptions, PasskeyControllerState } from './types.js';
+import type { PasskeyAuthenticationOptions, PasskeyAuthenticationResponse, PasskeyRegistrationOptions, PasskeyRegistrationResponse } from './webauthn/types.js';
+export type { PasskeyControllerActions, PasskeyControllerAllowedActions, PasskeyControllerEvents, PasskeyControllerGetStateAction, PasskeyControllerMessenger, PasskeyControllerOptions, PasskeyControllerState, PasskeyControllerStateChangedEvent, } from './types.js';
 /**
  * Returns the default (empty) state for {@link PasskeyController}.
  *
@@ -56,6 +56,41 @@ export declare class PasskeyController extends BaseController<typeof controllerN
     generateRegistrationOptions(creationOptionsConfig?: {
         prfAvailable?: boolean;
     }): PasskeyRegistrationOptions;
+    /**
+     * 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(): PasskeyRegistrationOptions;
+    /**
+     * 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.
+     */
+    completePasskeyReplacement(params: {
+        registrationResponse: PasskeyRegistrationResponse;
+        authenticationResponse: PasskeyAuthenticationResponse;
+    }): Promise<void>;
+    /**
+     * Cancels an in-flight passkey replacement ceremony.
+     *
+     * @param registrationChallenge - Challenge returned by
+     *   {@link generatePasskeyReplacementRegistrationOptions}.
+     */
+    cancelPasskeyReplacement(registrationChallenge: string): void;
     /**
      * Builds WebAuthn credential request options for the post-registration
      * authentication step (between `create` and {@link protectVaultKeyWithPasskey}).
@@ -205,4 +240,4 @@ export declare class PasskeyController extends BaseController<typeof controllerN
      */
     destroy(): void;
 }
-//# sourceMappingURL=PasskeyController.d.cts.map
+//# sourceMappingURL=PasskeyController.d.ts.map

package/dist/PasskeyController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PasskeyController.d.ts","sourceRoot":"","sources":["../src/PasskeyController.ts"],"names":[],"mappings":"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"}