@metamask/passkey-controller 2.0.1 → 3.0.0

package/dist/PasskeyController.d.mts

@@ -1,27 +1,8 @@
-import type { ControllerGetStateAction, ControllerStateChangedEvent } from "@metamask/base-controller";
 import { BaseController } from "@metamask/base-controller";
-import type { Messenger } from "@metamask/messenger";
 import { controllerName } from "./constants.mjs";
-import type { PasskeyRecord } from "./types.mjs";
+import type { PasskeyControllerMessenger, PasskeyControllerOptions, PasskeyControllerState } from "./types.mjs";
 import type { PasskeyAuthenticationOptions, PasskeyAuthenticationResponse, PasskeyRegistrationOptions, PasskeyRegistrationResponse } from "./webauthn/types.mjs";
-export type PasskeyControllerState = {
-    passkeyRecord: PasskeyRecord | null;
-};
-export type PasskeyControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PasskeyControllerState>;
-/**
- * Actions exposed by {@link PasskeyController} on its messenger.
- *
- * Only `:getState` is exposed. Derived enrollment status is available via
- * {@link passkeyControllerSelectors.selectIsPasskeyEnrolled}, and lifecycle
- * methods ({@link PasskeyController.generateRegistrationOptions},
- * {@link PasskeyController.protectVaultKeyWithPasskey}, etc.) accept or
- * return non-`Json` runtime values (WebAuthn `PublicKeyCredential` objects
- * and the vault key string), so they require a direct controller reference.
- */
-export type PasskeyControllerActions = PasskeyControllerGetStateAction;
-export type PasskeyControllerStateChangedEvent = ControllerStateChangedEvent<typeof controllerName, PasskeyControllerState>;
-export type PasskeyControllerEvents = PasskeyControllerStateChangedEvent;
-export type PasskeyControllerMessenger = Messenger<typeof controllerName, PasskeyControllerActions, PasskeyControllerEvents>;
+export type { PasskeyControllerActions, PasskeyControllerAllowedActions, PasskeyControllerEvents, PasskeyControllerGetStateAction, PasskeyControllerMessenger, PasskeyControllerOptions, PasskeyControllerState, PasskeyControllerStateChangedEvent, } from "./types.mjs";
 /**
  * Returns the default (empty) state for {@link PasskeyController}.
  *
@@ -47,29 +28,18 @@ export declare class PasskeyController extends BaseController<typeof controllerN
     /**
      * Creates a passkey controller with WebAuthn relying-party settings.
      *
-     * @param args - Constructor options.
-     * @param args.messenger - Controller messenger.
-     * @param args.state - Partial initial state; merged with {@link getDefaultPasskeyControllerState}.
-     * @param args.expectedRPID - Relying party ID(s) for verification (SHA-256 hash match in
-     *   authenticator data). Pass a string or array of strings; an empty array skips RP ID
-     *   allowlist checks in {@link verifyRegistrationResponse} / {@link verifyAuthenticationResponse}.
-     * @param args.rpId - When set, included as `rp.id` on registration options and `rpId` on
-     *   authentication options. When omitted, those fields are left unset (client default RP ID).
-     * @param args.rpName - Relying party name shown in the platform passkey UI.
-     * @param args.expectedOrigin - Allowed value(s) for the WebAuthn client origin.
-     * @param args.userName - Optional passkey user name; defaults to `rpName`.
-     * @param args.userDisplayName - Optional display name; defaults to `rpName`.
-     */
-    constructor({ messenger, state, rpId, expectedRPID, rpName, expectedOrigin, userName, userDisplayName, }: {
-        messenger: PasskeyControllerMessenger;
-        state?: Partial<PasskeyControllerState>;
-        rpId?: string;
-        expectedRPID: string | string[];
-        rpName: string;
-        expectedOrigin: string | string[];
-        userName?: string;
-        userDisplayName?: string;
-    });
+     * @param options - Constructor options.
+     * @param options.messenger - The messenger to use for communication.
+     * @param options.state - The initial state of the controller.
+     * @param options.rpId - The relying party ID to use for the passkey.
+     * @param options.expectedRPID - The expected relying party ID to use for the passkey.
+     * @param options.rpName - The relying party name to use for the passkey.
+     * @param options.expectedOrigin - The expected origin to use for the passkey.
+     * @param options.userName - The user name to use for the passkey.
+     * @param options.userDisplayName - The user display name to use for the passkey.
+     * @param options.getIsOnboardingCompleted - The callback to use to check if onboarding is complete.
+     */
+    constructor({ messenger, state, rpId, expectedRPID, rpName, expectedOrigin, userName, userDisplayName, getIsOnboardingCompleted, }: PasskeyControllerOptions);
     /**
      * Whether a passkey is enrolled and vault key material is stored.
      *
@@ -107,23 +77,54 @@ export declare class PasskeyController extends BaseController<typeof controllerN
      * 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.
      */
     protectVaultKeyWithPasskey(params: {
         registrationResponse: PasskeyRegistrationResponse;
         authenticationResponse: PasskeyAuthenticationResponse;
-        vaultKey: string;
+        password?: string;
     }): Promise<void>;
     /**
      * 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.
      */
     retrieveVaultKeyWithPasskey(authenticationResponse: PasskeyAuthenticationResponse): Promise<string>;
+    /**
+     * Unlocks the keyring using a passkey authentication assertion.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns Resolves when the keyring is unlocked.
+     */
+    unlockWithPasskey(authenticationResponse: PasskeyAuthenticationResponse): Promise<void>;
+    /**
+     * 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.
+     */
+    exportSeedPhraseWithPasskey(authenticationResponse: PasskeyAuthenticationResponse, keyringId?: string): Promise<Uint8Array>;
+    /**
+     * 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`.
+     */
+    exportAccountsWithPasskey(authenticationResponse: PasskeyAuthenticationResponse, addresses: string[]): Promise<string[]>;
     /**
      * Checks whether the given authentication assertion is valid for the enrolled passkey.
      *
@@ -142,10 +143,15 @@ export declare class PasskeyController extends BaseController<typeof controllerN
      * 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.
      */
     renewVaultKeyProtection(params: {
         authenticationResponse: PasskeyAuthenticationResponse;
@@ -153,12 +159,45 @@ export declare class PasskeyController extends BaseController<typeof controllerN
         newVaultKey: string;
     }): Promise<void>;
     /**
-     * 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.
+     */
+    changePasswordWithPasskeyVerification(params: {
+        newPassword: string;
+        authenticationResponse: PasskeyAuthenticationResponse;
+        options?: {
+            renewVaultKeyProtection?: boolean;
+        };
+    }): Promise<void>;
+    /**
+     * Removes the enrolled passkey after verifying a passkey authentication assertion.
+     *
+     * @param authenticationResponse - Result of `navigator.credentials.get()`.
+     * @returns Resolves when the passkey is removed.
+     */
+    removePasskeyWithPasskeyVerification(authenticationResponse: PasskeyAuthenticationResponse): Promise<void>;
+    /**
+     * Removes the enrolled passkey after verifying the wallet password.
+     *
+     * @param password - Wallet password for step-up verification.
+     * @returns Resolves when the passkey is removed.
      */
-    removePasskey(): void;
+    removePasskeyWithPasswordVerification(password: string): Promise<void>;
     /**
      * Resets state and clears in-flight registration/authentication ceremonies.
+     *
+     * For user-facing passkey removal with step-up, use
+     * {@link removePasskeyWithPasskeyVerification} or
+     * {@link removePasskeyWithPasswordVerification}.
      */
     clearState(): void;
     /**

package/dist/PasskeyController.d.mts.map

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