@metamask-previews/passkey-controller 2.1.0-preview-b47b10d1b → 2.1.0-preview-1ed087802

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Orchestrated passkey product flows on `PasskeyController` and their messenger actions. ([#9548](https://github.com/MetaMask/core/pull/9548))
+  - `unlockWithPasskey`
+  - `removePasskeyWithPasskeyVerification`
+  - `removePasskeyWithPasswordVerification`
+  - `changePasswordWithPasskeyVerification`
+  - `exportSeedPhraseWithPasskey`
+  - `exportAccountsWithPasskey`
+- `PasskeyControllerOptions` with required `getIsOnboardingCompleted` constructor callback for enrollment step-up gating. ([#9548](https://github.com/MetaMask/core/pull/9548))
+- Added new error constants, `PasskeyControllerErrorCode.VaultKeyRenewalFailed`, `PasskeyControllerErrorCode.EnrollmentPasswordRequired`, `PasskeyControllerErrorMessage.VaultKeyRenewalFailed` and `PasskeyControllerErrorMessage.EnrollmentPasswordRequired`. ([#9548](https://github.com/MetaMask/core/pull/9548))
+- `@metamask/keyring-controller` dependency for KeyringController messenger action types used during orchestration. ([#9548](https://github.com/MetaMask/core/pull/9548))
+
+### Changed
+
+- **BREAKING:** `protectVaultKeyWithPasskey` no longer accepts `vaultKey`; the controller fetches the current encryption key via `KeyringController:exportEncryptionKey` and optionally verifies the wallet password when onboarding is complete. (([#9548](https://github.com/MetaMask/core/pull/9548)))
+- **BREAKING:** `PasskeyController` constructor requires `getIsOnboardingCompleted`. (([#9548](https://github.com/MetaMask/core/pull/9548)))
+- **BREAKING:** `removePasskey` and `PasskeyController:removePasskey` are no longer public; use `removePasskeyWithPasskeyVerification`, `removePasskeyWithPasswordVerification`, or `clearState`. ([#9548](https://github.com/MetaMask/core/pull/9548))
+- `PasskeyControllerMessenger` may call a fixed set of KeyringController actions during orchestrated flows ([#9548](https://github.com/MetaMask/core/pull/9548))
+- Orchestrated async passkey operations are serialized with an internal mutex to prevent concurrent vault/keyring races. ([#9548](https://github.com/MetaMask/core/pull/9548))
+
 ## [2.1.0]
 
 ### Added

package/README.md

@@ -34,6 +34,8 @@ Both strategies feed the input key material through **HKDF-SHA256** with the cre
 
 ### Setting up the controller
 
+The restricted messenger must allow the KeyringController actions listed in [Keyring integration](#keyring-integration). Onboarding completion is supplied via constructor callback (not via messenger).
+
 ```typescript
 import { PasskeyController } from '@metamask/passkey-controller';
 import type { PasskeyControllerMessenger } from '@metamask/passkey-controller';
@@ -50,6 +52,7 @@ const controller = new PasskeyController({
   // Optional — both default to `rpName` when omitted.
   userName: 'My Wallet',
   userDisplayName: 'My Wallet',
+  getIsOnboardingCompleted: () => onboardingController.state.completedOnboarding,
 });
 ```
 
@@ -57,6 +60,8 @@ const controller = new PasskeyController({
 
 ### Passkey enrollment (registration)
 
+`protectVaultKeyWithPasskey` fetches the current vault encryption key from KeyringController. When onboarding is complete, pass the wallet `password` for step-up verification first.
+
 ```typescript
 // 1. Generate registration options (synchronous)
 const regOptions = controller.generateRegistrationOptions();
@@ -74,48 +79,72 @@ const authResponse = await navigator.credentials.get({
   publicKey: authOptions,
 });
 
-// 4. Verify registration + post-registration auth once, then persist
+// 4. Verify registration + post-registration auth, then persist
 await controller.protectVaultKeyWithPasskey({
   registrationResponse: regResponse,
   authenticationResponse: authResponse,
-  vaultKey: myVaultEncryptionKey,
+  password: settingsEnroll ? walletPassword : undefined,
 });
 ```
 
 ### Passkey unlock (authentication)
 
+Prefer `unlockWithPasskey`, which verifies the assertion and submits the vault key to KeyringController.
+
 ```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);
+await controller.unlockWithPasskey(response);
 ```
 
-### Password change (vault key renewal)
+### Orchestrated product flows
 
-```typescript
-const options = controller.generateAuthenticationOptions();
-const response = await navigator.credentials.get({ publicKey: options });
+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 |
 
-await controller.renewVaultKeyProtection({
+```typescript
+// Change password (re-wraps passkey protection by default)
+await controller.changePasswordWithPasskeyVerification({
+  newPassword: 'new-secret',
   authenticationResponse: response,
-  oldVaultKey: currentVaultKey,
-  newVaultKey: newVaultKey,
+  options: { renewVaultKeyProtection: true },
 });
+
+// Export seed phrase (raw Uint8Array; format in your app layer)
+const seedPhrase = await controller.exportSeedPhraseWithPasskey(
+  response,
+  keyringId,
+);
+
+// Export private keys for multiple addresses (one assertion)
+const privateKeys = await controller.exportAccountsWithPasskey(response, [
+  '0xabc…',
+  '0xdef…',
+]);
 ```
 
+### Low-level methods
+
+`retrieveVaultKeyWithPasskey` and `renewVaultKeyProtection` remain available for advanced composition. Prefer the orchestrated methods above for standard product flows. Use `clearState` for wallet reset lifecycle.
+
 ### Checking enrollment and removing a passkey
 
 ```typescript
 controller.isPasskeyEnrolled(); // boolean
 
-controller.removePasskey(); // user-facing unenroll; clears persisted passkey and in-flight ceremonies
+await controller.removePasskeyWithPasskeyVerification(response);
+await controller.removePasskeyWithPasswordVerification(password);
 
-controller.clearState(); // same persisted reset + clears in-flight ceremony state; use for app lifecycle (e.g. wallet reset)
+controller.clearState(); // persisted reset + clears in-flight ceremony state; use for app lifecycle (e.g. wallet reset)
 ```
 
 ### Selectors
@@ -134,7 +163,8 @@ passkeyControllerSelectors.selectIsPasskeyEnrolled(state); // boolean
 `PasskeyControllerError` is thrown for controller failures. Expected operational
 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`). Human-readable strings
+`authentication_verification_failed`, `missing_key_material`, `vault_key_decryption_failed`,
+`vault_key_mismatch`, `vault_key_renewal_failed`, `enrollment_password_required`). 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
@@ -153,9 +183,27 @@ those controller errors (with `code`) and rethrows everything else.
 
 ### Messenger actions
 
-| Action                       | Handler                              |
-| ---------------------------- | ------------------------------------ |
-| `PasskeyController:getState` | Returns the current controller state |
+| Action                                                            | Purpose                                    |
+| ----------------------------------------------------------------- | ------------------------------------------ |
+| `PasskeyController:getState`                                      | Persisted `passkeyRecord`                  |
+| `PasskeyController:isPasskeyEnrolled`                             | Enrollment boolean                         |
+| `PasskeyController:generateRegistrationOptions`                   | WebAuthn `create()` options                |
+| `PasskeyController:generatePostRegistrationAuthenticationOptions` | WebAuthn `get()` after `create()`          |
+| `PasskeyController:generateAuthenticationOptions`                 | WebAuthn `get()` for unlock / step-up      |
+| `PasskeyController:protectVaultKeyWithPasskey`                    | Enroll: verify ceremonies + wrap vault key |
+| `PasskeyController:retrieveVaultKeyWithPasskey`                   | Verify assertion + return vault key        |
+| `PasskeyController:unlockWithPasskey`                             | Unlock keyring via passkey                 |
+| `PasskeyController:exportSeedPhraseWithPasskey`                   | Export SRP after passkey step-up           |
+| `PasskeyController:exportAccountsWithPasskey`                     | Export private keys after passkey step-up  |
+| `PasskeyController:verifyPasskeyAuthentication`                   | Boolean assertion verification             |
+| `PasskeyController:renewVaultKeyProtection`                       | Re-wrap vault key after rotation           |
+| `PasskeyController:changePasswordWithPasskeyVerification`         | Change password with passkey step-up       |
+| `PasskeyController:removePasskeyWithPasskeyVerification`          | Remove passkey after assertion step-up     |
+| `PasskeyController:removePasskeyWithPasswordVerification`         | Remove passkey after password step-up      |
+| `PasskeyController:clearState`                                    | Reset state                                |
+| `PasskeyController:destroy`                                       | Tear down messenger + ceremony state       |
+
+Corresponding `PasskeyController*Action` types are exported from the package entry point.
 
 For derived enrollment status outside of components that hold a controller
 reference, use `passkeyControllerSelectors.selectIsPasskeyEnrolled` (see
@@ -167,6 +215,21 @@ reference, use `passkeyControllerSelectors.selectIsPasskeyEnrolled` (see
 | -------------------------------- | ------------------------------------------------------------ |
 | `PasskeyController:stateChanged` | Emitted when state changes (standard `BaseController` event) |
 
+### Keyring integration
+
+`PasskeyController` calls these KeyringController actions during orchestrated flows. Allow them on the restricted messenger at init:
+
+| Messenger action                        |
+| --------------------------------------- |
+| `KeyringController:verifyPassword`      |
+| `KeyringController:exportEncryptionKey` |
+| `KeyringController:submitEncryptionKey` |
+| `KeyringController:changePassword`      |
+| `KeyringController:exportSeedPhrase`    |
+| `KeyringController:exportAccount`       |
+
+Onboarding completion is **not** read via messenger. Pass `getIsOnboardingCompleted` in the constructor (see [Setting up the controller](#setting-up-the-controller)).
+
 ## 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-method-action-types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"PasskeyController-method-action-types.cjs","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';\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 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 * @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.vaultKey - Vault encryption key to encrypt and persist.\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 * @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 * 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 * @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 */\nexport type PasskeyControllerRenewVaultKeyProtectionAction = {\n  type: `PasskeyController:renewVaultKeyProtection`;\n  handler: PasskeyController['renewVaultKeyProtection'];\n};\n\n/**\n * Clears enrolled passkey state and in-flight ceremonies. Call only after the same\n * auth gate as renewal (verified passkey assertion or password).\n */\nexport type PasskeyControllerRemovePasskeyAction = {\n  type: `PasskeyController:removePasskey`;\n  handler: PasskeyController['removePasskey'];\n};\n\n/**\n * Resets state and clears in-flight registration/authentication ceremonies.\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  | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction\n  | PasskeyControllerGenerateAuthenticationOptionsAction\n  | PasskeyControllerProtectVaultKeyWithPasskeyAction\n  | PasskeyControllerRetrieveVaultKeyWithPasskeyAction\n  | PasskeyControllerVerifyPasskeyAuthenticationAction\n  | PasskeyControllerRenewVaultKeyProtectionAction\n  | PasskeyControllerRemovePasskeyAction\n  | PasskeyControllerClearStateAction\n  | PasskeyControllerDestroyAction;\n"]}
+{"version":3,"file":"PasskeyController-method-action-types.cjs","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';\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 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  | 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-method-action-types.d.cts

@@ -48,10 +48,14 @@ export type PasskeyControllerGenerateAuthenticationOptionsAction = {
  * Verifies registration and post-registration authentication, then stores the
  * vault key encrypted under the new passkey.
  *
+ * Fetches the current vault encryption key from KeyringController before wrapping.
+ * When onboarding is complete, requires `password` for step-up verification first.
+ *
  * @param params - Enrollment completion inputs.
  * @param params.registrationResponse - Result of `navigator.credentials.create()`.
  * @param params.authenticationResponse - Result of `navigator.credentials.get()` after {@link generatePostRegistrationAuthenticationOptions}.
- * @param params.vaultKey - Vault encryption key to encrypt and persist.
+ * @param params.password - Wallet password when onboarding is complete (step-up).
+ * @returns Resolves when enrollment completes.
  */
 export type PasskeyControllerProtectVaultKeyWithPasskeyAction = {
     type: `PasskeyController:protectVaultKeyWithPasskey`;
@@ -60,6 +64,10 @@ export type PasskeyControllerProtectVaultKeyWithPasskeyAction = {
 /**
  * Verifies an authentication assertion and returns the decrypted vault key.
  *
+ * Prefer orchestrated methods ({@link unlockWithPasskey},
+ * {@link exportSeedPhraseWithPasskey}, {@link exportAccountsWithPasskey}) for product
+ * flows instead of calling KeyringController with the returned key manually.
+ *
  * @param authenticationResponse - Result of `navigator.credentials.get()`.
  * @returns The plaintext vault encryption key.
  */
@@ -67,6 +75,38 @@ export type PasskeyControllerRetrieveVaultKeyWithPasskeyAction = {
     type: `PasskeyController:retrieveVaultKeyWithPasskey`;
     handler: PasskeyController['retrieveVaultKeyWithPasskey'];
 };
+/**
+ * Unlocks the keyring using a passkey authentication assertion.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @returns Resolves when the keyring is unlocked.
+ */
+export type PasskeyControllerUnlockWithPasskeyAction = {
+    type: `PasskeyController:unlockWithPasskey`;
+    handler: PasskeyController['unlockWithPasskey'];
+};
+/**
+ * Exports the seed phrase after passkey step-up authentication.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @param keyringId - Optional keyring id; defaults to the primary HD keyring.
+ * @returns Raw seed phrase bytes from KeyringController.
+ */
+export type PasskeyControllerExportSeedPhraseWithPasskeyAction = {
+    type: `PasskeyController:exportSeedPhraseWithPasskey`;
+    handler: PasskeyController['exportSeedPhraseWithPasskey'];
+};
+/**
+ * Exports private keys for the given addresses after passkey step-up authentication.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @param addresses - Account addresses to export.
+ * @returns Private keys in the same order as `addresses`.
+ */
+export type PasskeyControllerExportAccountsWithPasskeyAction = {
+    type: `PasskeyController:exportAccountsWithPasskey`;
+    handler: PasskeyController['exportAccountsWithPasskey'];
+};
 /**
  * Checks whether the given authentication assertion is valid for the enrolled passkey.
  *
@@ -88,25 +128,63 @@ export type PasskeyControllerVerifyPasskeyAuthenticationAction = {
  * pass the same `authenticationResponse` you just verified (e.g. from
  * {@link retrieveVaultKeyWithPasskey} / {@link verifyPasskeyAuthentication}).
  *
+ * For password change with passkey step-up, prefer
+ * {@link changePasswordWithPasskeyVerification}, which orchestrates keyring export,
+ * `changePassword`, and re-wrap in one call.
+ *
  * @param params - Re-wrap inputs.
  * @param params.authenticationResponse - Used to derive the wrapping key.
  * @param params.oldVaultKey - Expected current vault key.
  * @param params.newVaultKey - New vault key to encrypt under the passkey.
+ * @returns Resolves when the passkey record is updated.
  */
 export type PasskeyControllerRenewVaultKeyProtectionAction = {
     type: `PasskeyController:renewVaultKeyProtection`;
     handler: PasskeyController['renewVaultKeyProtection'];
 };
 /**
- * Clears enrolled passkey state and in-flight ceremonies. Call only after the same
- * auth gate as renewal (verified passkey assertion or password).
+ * Changes the wallet password after passkey step-up authentication.
+ *
+ * When `renewVaultKeyProtection` is `true` (default), re-wraps the vault key under the
+ * passkey after rotation. When `false`, removes the passkey instead.
+ *
+ * @param params - Change-password inputs.
+ * @param params.newPassword - New wallet password.
+ * @param params.authenticationResponse - Result of `navigator.credentials.get()`.
+ * @param params.options - Optional flow controls.
+ * @param params.options.renewVaultKeyProtection - Re-wrap vault key after password change.
+ * @returns Resolves when the password change completes.
  */
-export type PasskeyControllerRemovePasskeyAction = {
-    type: `PasskeyController:removePasskey`;
-    handler: PasskeyController['removePasskey'];
+export type PasskeyControllerChangePasswordWithPasskeyVerificationAction = {
+    type: `PasskeyController:changePasswordWithPasskeyVerification`;
+    handler: PasskeyController['changePasswordWithPasskeyVerification'];
+};
+/**
+ * Removes the enrolled passkey after verifying a passkey authentication assertion.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @returns Resolves when the passkey is removed.
+ */
+export type PasskeyControllerRemovePasskeyWithPasskeyVerificationAction = {
+    type: `PasskeyController:removePasskeyWithPasskeyVerification`;
+    handler: PasskeyController['removePasskeyWithPasskeyVerification'];
+};
+/**
+ * Removes the enrolled passkey after verifying the wallet password.
+ *
+ * @param password - Wallet password for step-up verification.
+ * @returns Resolves when the passkey is removed.
+ */
+export type PasskeyControllerRemovePasskeyWithPasswordVerificationAction = {
+    type: `PasskeyController:removePasskeyWithPasswordVerification`;
+    handler: PasskeyController['removePasskeyWithPasswordVerification'];
 };
 /**
  * Resets state and clears in-flight registration/authentication ceremonies.
+ *
+ * For user-facing passkey removal with step-up, use
+ * {@link removePasskeyWithPasskeyVerification} or
+ * {@link removePasskeyWithPasswordVerification}.
  */
 export type PasskeyControllerClearStateAction = {
     type: `PasskeyController:clearState`;
@@ -122,5 +200,5 @@ export type PasskeyControllerDestroyAction = {
 /**
  * Union of all PasskeyController action types.
  */
-export type PasskeyControllerMethodActions = PasskeyControllerIsPasskeyEnrolledAction | PasskeyControllerGenerateRegistrationOptionsAction | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction | PasskeyControllerGenerateAuthenticationOptionsAction | PasskeyControllerProtectVaultKeyWithPasskeyAction | PasskeyControllerRetrieveVaultKeyWithPasskeyAction | PasskeyControllerVerifyPasskeyAuthenticationAction | PasskeyControllerRenewVaultKeyProtectionAction | PasskeyControllerRemovePasskeyAction | PasskeyControllerClearStateAction | PasskeyControllerDestroyAction;
+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.cts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PasskeyController-method-action-types.d.cts","sourceRoot":"","sources":["../src/PasskeyController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gCAA4B;AAE7D;;;;GAIG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACrD,IAAI,EAAE,qCAAqC,CAAC;IAC5C,OAAO,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kDAAkD,GAAG;IAC/D,IAAI,EAAE,+CAA+C,CAAC;IACtD,OAAO,EAAE,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oEAAoE,GAC9E;IACE,IAAI,EAAE,iEAAiE,CAAC;IACxE,OAAO,EAAE,iBAAiB,CAAC,+CAA+C,CAAC,CAAC;CAC7E,CAAC;AAEJ;;;;GAIG;AACH,MAAM,MAAM,oDAAoD,GAAG;IACjE,IAAI,EAAE,iDAAiD,CAAC;IACxD,OAAO,EAAE,iBAAiB,CAAC,+BAA+B,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iDAAiD,GAAG;IAC9D,IAAI,EAAE,8CAA8C,CAAC;IACrD,OAAO,EAAE,iBAAiB,CAAC,4BAA4B,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kDAAkD,GAAG;IAC/D,IAAI,EAAE,+CAA+C,CAAC;IACtD,OAAO,EAAE,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,kDAAkD,GAAG;IAC/D,IAAI,EAAE,+CAA+C,CAAC;IACtD,OAAO,EAAE,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,8CAA8C,GAAG;IAC3D,IAAI,EAAE,2CAA2C,CAAC;IAClD,OAAO,EAAE,iBAAiB,CAAC,yBAAyB,CAAC,CAAC;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oCAAoC,GAAG;IACjD,IAAI,EAAE,iCAAiC,CAAC;IACxC,OAAO,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAC;CAC7C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GACtC,wCAAwC,GACxC,kDAAkD,GAClD,oEAAoE,GACpE,oDAAoD,GACpD,iDAAiD,GACjD,kDAAkD,GAClD,kDAAkD,GAClD,8CAA8C,GAC9C,oCAAoC,GACpC,iCAAiC,GACjC,8BAA8B,CAAC"}
+{"version":3,"file":"PasskeyController-method-action-types.d.cts","sourceRoot":"","sources":["../src/PasskeyController-method-action-types.ts"],"names":[],"mappings":"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"}

package/dist/PasskeyController-method-action-types.d.mts

@@ -48,10 +48,14 @@ export type PasskeyControllerGenerateAuthenticationOptionsAction = {
  * Verifies registration and post-registration authentication, then stores the
  * vault key encrypted under the new passkey.
  *
+ * Fetches the current vault encryption key from KeyringController before wrapping.
+ * When onboarding is complete, requires `password` for step-up verification first.
+ *
  * @param params - Enrollment completion inputs.
  * @param params.registrationResponse - Result of `navigator.credentials.create()`.
  * @param params.authenticationResponse - Result of `navigator.credentials.get()` after {@link generatePostRegistrationAuthenticationOptions}.
- * @param params.vaultKey - Vault encryption key to encrypt and persist.
+ * @param params.password - Wallet password when onboarding is complete (step-up).
+ * @returns Resolves when enrollment completes.
  */
 export type PasskeyControllerProtectVaultKeyWithPasskeyAction = {
     type: `PasskeyController:protectVaultKeyWithPasskey`;
@@ -60,6 +64,10 @@ export type PasskeyControllerProtectVaultKeyWithPasskeyAction = {
 /**
  * Verifies an authentication assertion and returns the decrypted vault key.
  *
+ * Prefer orchestrated methods ({@link unlockWithPasskey},
+ * {@link exportSeedPhraseWithPasskey}, {@link exportAccountsWithPasskey}) for product
+ * flows instead of calling KeyringController with the returned key manually.
+ *
  * @param authenticationResponse - Result of `navigator.credentials.get()`.
  * @returns The plaintext vault encryption key.
  */
@@ -67,6 +75,38 @@ export type PasskeyControllerRetrieveVaultKeyWithPasskeyAction = {
     type: `PasskeyController:retrieveVaultKeyWithPasskey`;
     handler: PasskeyController['retrieveVaultKeyWithPasskey'];
 };
+/**
+ * Unlocks the keyring using a passkey authentication assertion.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @returns Resolves when the keyring is unlocked.
+ */
+export type PasskeyControllerUnlockWithPasskeyAction = {
+    type: `PasskeyController:unlockWithPasskey`;
+    handler: PasskeyController['unlockWithPasskey'];
+};
+/**
+ * Exports the seed phrase after passkey step-up authentication.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @param keyringId - Optional keyring id; defaults to the primary HD keyring.
+ * @returns Raw seed phrase bytes from KeyringController.
+ */
+export type PasskeyControllerExportSeedPhraseWithPasskeyAction = {
+    type: `PasskeyController:exportSeedPhraseWithPasskey`;
+    handler: PasskeyController['exportSeedPhraseWithPasskey'];
+};
+/**
+ * Exports private keys for the given addresses after passkey step-up authentication.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @param addresses - Account addresses to export.
+ * @returns Private keys in the same order as `addresses`.
+ */
+export type PasskeyControllerExportAccountsWithPasskeyAction = {
+    type: `PasskeyController:exportAccountsWithPasskey`;
+    handler: PasskeyController['exportAccountsWithPasskey'];
+};
 /**
  * Checks whether the given authentication assertion is valid for the enrolled passkey.
  *
@@ -88,25 +128,63 @@ export type PasskeyControllerVerifyPasskeyAuthenticationAction = {
  * pass the same `authenticationResponse` you just verified (e.g. from
  * {@link retrieveVaultKeyWithPasskey} / {@link verifyPasskeyAuthentication}).
  *
+ * For password change with passkey step-up, prefer
+ * {@link changePasswordWithPasskeyVerification}, which orchestrates keyring export,
+ * `changePassword`, and re-wrap in one call.
+ *
  * @param params - Re-wrap inputs.
  * @param params.authenticationResponse - Used to derive the wrapping key.
  * @param params.oldVaultKey - Expected current vault key.
  * @param params.newVaultKey - New vault key to encrypt under the passkey.
+ * @returns Resolves when the passkey record is updated.
  */
 export type PasskeyControllerRenewVaultKeyProtectionAction = {
     type: `PasskeyController:renewVaultKeyProtection`;
     handler: PasskeyController['renewVaultKeyProtection'];
 };
 /**
- * Clears enrolled passkey state and in-flight ceremonies. Call only after the same
- * auth gate as renewal (verified passkey assertion or password).
+ * Changes the wallet password after passkey step-up authentication.
+ *
+ * When `renewVaultKeyProtection` is `true` (default), re-wraps the vault key under the
+ * passkey after rotation. When `false`, removes the passkey instead.
+ *
+ * @param params - Change-password inputs.
+ * @param params.newPassword - New wallet password.
+ * @param params.authenticationResponse - Result of `navigator.credentials.get()`.
+ * @param params.options - Optional flow controls.
+ * @param params.options.renewVaultKeyProtection - Re-wrap vault key after password change.
+ * @returns Resolves when the password change completes.
  */
-export type PasskeyControllerRemovePasskeyAction = {
-    type: `PasskeyController:removePasskey`;
-    handler: PasskeyController['removePasskey'];
+export type PasskeyControllerChangePasswordWithPasskeyVerificationAction = {
+    type: `PasskeyController:changePasswordWithPasskeyVerification`;
+    handler: PasskeyController['changePasswordWithPasskeyVerification'];
+};
+/**
+ * Removes the enrolled passkey after verifying a passkey authentication assertion.
+ *
+ * @param authenticationResponse - Result of `navigator.credentials.get()`.
+ * @returns Resolves when the passkey is removed.
+ */
+export type PasskeyControllerRemovePasskeyWithPasskeyVerificationAction = {
+    type: `PasskeyController:removePasskeyWithPasskeyVerification`;
+    handler: PasskeyController['removePasskeyWithPasskeyVerification'];
+};
+/**
+ * Removes the enrolled passkey after verifying the wallet password.
+ *
+ * @param password - Wallet password for step-up verification.
+ * @returns Resolves when the passkey is removed.
+ */
+export type PasskeyControllerRemovePasskeyWithPasswordVerificationAction = {
+    type: `PasskeyController:removePasskeyWithPasswordVerification`;
+    handler: PasskeyController['removePasskeyWithPasswordVerification'];
 };
 /**
  * Resets state and clears in-flight registration/authentication ceremonies.
+ *
+ * For user-facing passkey removal with step-up, use
+ * {@link removePasskeyWithPasskeyVerification} or
+ * {@link removePasskeyWithPasswordVerification}.
  */
 export type PasskeyControllerClearStateAction = {
     type: `PasskeyController:clearState`;
@@ -122,5 +200,5 @@ export type PasskeyControllerDestroyAction = {
 /**
  * Union of all PasskeyController action types.
  */
-export type PasskeyControllerMethodActions = PasskeyControllerIsPasskeyEnrolledAction | PasskeyControllerGenerateRegistrationOptionsAction | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction | PasskeyControllerGenerateAuthenticationOptionsAction | PasskeyControllerProtectVaultKeyWithPasskeyAction | PasskeyControllerRetrieveVaultKeyWithPasskeyAction | PasskeyControllerVerifyPasskeyAuthenticationAction | PasskeyControllerRenewVaultKeyProtectionAction | PasskeyControllerRemovePasskeyAction | PasskeyControllerClearStateAction | PasskeyControllerDestroyAction;
+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

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

@@ -1 +1 @@
-{"version":3,"file":"PasskeyController-method-action-types.d.mts","sourceRoot":"","sources":["../src/PasskeyController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gCAA4B;AAE7D;;;;GAIG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACrD,IAAI,EAAE,qCAAqC,CAAC;IAC5C,OAAO,EAAE,iBAAiB,CAAC,mBAAmB,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,kDAAkD,GAAG;IAC/D,IAAI,EAAE,+CAA+C,CAAC;IACtD,OAAO,EAAE,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oEAAoE,GAC9E;IACE,IAAI,EAAE,iEAAiE,CAAC;IACxE,OAAO,EAAE,iBAAiB,CAAC,+CAA+C,CAAC,CAAC;CAC7E,CAAC;AAEJ;;;;GAIG;AACH,MAAM,MAAM,oDAAoD,GAAG;IACjE,IAAI,EAAE,iDAAiD,CAAC;IACxD,OAAO,EAAE,iBAAiB,CAAC,+BAA+B,CAAC,CAAC;CAC7D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iDAAiD,GAAG;IAC9D,IAAI,EAAE,8CAA8C,CAAC;IACrD,OAAO,EAAE,iBAAiB,CAAC,4BAA4B,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kDAAkD,GAAG;IAC/D,IAAI,EAAE,+CAA+C,CAAC;IACtD,OAAO,EAAE,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,kDAAkD,GAAG;IAC/D,IAAI,EAAE,+CAA+C,CAAC;IACtD,OAAO,EAAE,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,8CAA8C,GAAG;IAC3D,IAAI,EAAE,2CAA2C,CAAC;IAClD,OAAO,EAAE,iBAAiB,CAAC,yBAAyB,CAAC,CAAC;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oCAAoC,GAAG;IACjD,IAAI,EAAE,iCAAiC,CAAC;IACxC,OAAO,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAC;CAC7C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GACtC,wCAAwC,GACxC,kDAAkD,GAClD,oEAAoE,GACpE,oDAAoD,GACpD,iDAAiD,GACjD,kDAAkD,GAClD,kDAAkD,GAClD,8CAA8C,GAC9C,oCAAoC,GACpC,iCAAiC,GACjC,8BAA8B,CAAC"}
+{"version":3,"file":"PasskeyController-method-action-types.d.mts","sourceRoot":"","sources":["../src/PasskeyController-method-action-types.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"PasskeyController-method-action-types.mjs","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';\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 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 * @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.vaultKey - Vault encryption key to encrypt and persist.\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 * @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 * 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 * @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 */\nexport type PasskeyControllerRenewVaultKeyProtectionAction = {\n  type: `PasskeyController:renewVaultKeyProtection`;\n  handler: PasskeyController['renewVaultKeyProtection'];\n};\n\n/**\n * Clears enrolled passkey state and in-flight ceremonies. Call only after the same\n * auth gate as renewal (verified passkey assertion or password).\n */\nexport type PasskeyControllerRemovePasskeyAction = {\n  type: `PasskeyController:removePasskey`;\n  handler: PasskeyController['removePasskey'];\n};\n\n/**\n * Resets state and clears in-flight registration/authentication ceremonies.\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  | PasskeyControllerGeneratePostRegistrationAuthenticationOptionsAction\n  | PasskeyControllerGenerateAuthenticationOptionsAction\n  | PasskeyControllerProtectVaultKeyWithPasskeyAction\n  | PasskeyControllerRetrieveVaultKeyWithPasskeyAction\n  | PasskeyControllerVerifyPasskeyAuthenticationAction\n  | PasskeyControllerRenewVaultKeyProtectionAction\n  | PasskeyControllerRemovePasskeyAction\n  | PasskeyControllerClearStateAction\n  | PasskeyControllerDestroyAction;\n"]}
+{"version":3,"file":"PasskeyController-method-action-types.mjs","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';\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 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  | 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"]}