|
| 1 | +# `@metamask/passkey-controller` |
| 2 | + |
| 3 | +Manages passkey-based vault key protection using [WebAuthn](https://www.w3.org/TR/webauthn-3/). Orchestrates the full passkey lifecycle: generating WebAuthn ceremony options, verifying authenticator responses, and protecting/retrieving the vault encryption key via AES-256-GCM wrapping with HKDF-derived keys. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +`yarn add @metamask/passkey-controller` |
| 8 | + |
| 9 | +or |
| 10 | + |
| 11 | +`npm install @metamask/passkey-controller` |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +The controller follows a two-phase ceremony pattern for both enrollment and authentication: |
| 16 | + |
| 17 | +1. **Generate options** — call a synchronous method that returns options JSON and records **in-flight ceremony** state (challenge-keyed; not a user login session). |
| 18 | +2. **Verify response** — pass the authenticator's response back to the controller, which verifies the WebAuthn signature and performs the cryptographic operation (protect or retrieve the vault key). |
| 19 | + |
| 20 | +### Key derivation strategies |
| 21 | + |
| 22 | +The controller supports two key derivation methods, selected automatically during enrollment: |
| 23 | + |
| 24 | +| Strategy | When used | Input key material | |
| 25 | +| -------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- | |
| 26 | +| **PRF** | Authenticator supports the [WebAuthn PRF extension](https://w3c.github.io/webauthn/#prf-extension) | PRF evaluation output | |
| 27 | +| **userHandle** | PRF is unavailable | Random `userHandle` generated during registration | |
| 28 | + |
| 29 | +Both strategies feed the input key material through **HKDF-SHA256** with the credential ID as salt and a fixed info string to produce the 32-byte AES-256 wrapping key. |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +### Setting up the controller |
| 34 | + |
| 35 | +```typescript |
| 36 | +import { PasskeyController } from '@metamask/passkey-controller'; |
| 37 | +import type { PasskeyControllerMessenger } from '@metamask/passkey-controller'; |
| 38 | + |
| 39 | +const messenger: PasskeyControllerMessenger = /* create via root messenger */; |
| 40 | + |
| 41 | +const controller = new PasskeyController({ |
| 42 | + messenger, |
| 43 | + rpID: 'example.com', |
| 44 | + rpName: 'My Wallet', |
| 45 | + expectedOrigin: 'chrome-extension://abcdef1234567890', |
| 46 | + // Optional — both default to `rpName` when omitted. |
| 47 | + userName: 'My Wallet', |
| 48 | + userDisplayName: 'My Wallet', |
| 49 | +}); |
| 50 | +``` |
| 51 | + |
| 52 | +### Passkey enrollment (registration) |
| 53 | + |
| 54 | +```typescript |
| 55 | +// 1. Generate registration options (synchronous) |
| 56 | +const options = controller.generateRegistrationOptions(); |
| 57 | + |
| 58 | +// 2. Pass options to the browser WebAuthn API |
| 59 | +const response = await navigator.credentials.create({ publicKey: options }); |
| 60 | + |
| 61 | +// 3. Verify and protect the vault key |
| 62 | +await controller.protectVaultKeyWithPasskey({ |
| 63 | + registrationResponse: response, |
| 64 | + vaultKey: myVaultEncryptionKey, |
| 65 | +}); |
| 66 | +``` |
| 67 | + |
| 68 | +### Passkey unlock (authentication) |
| 69 | + |
| 70 | +```typescript |
| 71 | +// 1. Generate authentication options (synchronous) |
| 72 | +const options = controller.generateAuthenticationOptions(); |
| 73 | + |
| 74 | +// 2. Pass options to the browser WebAuthn API |
| 75 | +const response = await navigator.credentials.get({ publicKey: options }); |
| 76 | + |
| 77 | +// 3. Verify and retrieve the vault key |
| 78 | +const vaultKey = await controller.retrieveVaultKeyWithPasskey(response); |
| 79 | +``` |
| 80 | + |
| 81 | +### Password change (vault key renewal) |
| 82 | + |
| 83 | +```typescript |
| 84 | +const options = controller.generateAuthenticationOptions(); |
| 85 | +const response = await navigator.credentials.get({ publicKey: options }); |
| 86 | + |
| 87 | +await controller.renewVaultKeyProtection({ |
| 88 | + authenticationResponse: response, |
| 89 | + oldVaultKey: currentVaultKey, |
| 90 | + newVaultKey: newVaultKey, |
| 91 | +}); |
| 92 | +``` |
| 93 | + |
| 94 | +### Checking enrollment and removing a passkey |
| 95 | + |
| 96 | +```typescript |
| 97 | +controller.isPasskeyEnrolled(); // boolean |
| 98 | + |
| 99 | +controller.removePasskey(); // user-facing unenroll; clears persisted passkey and in-flight ceremonies |
| 100 | + |
| 101 | +controller.clearState(); // same persisted reset + clears in-flight ceremony state; use for app lifecycle (e.g. wallet reset) |
| 102 | +``` |
| 103 | + |
| 104 | +### Selectors |
| 105 | + |
| 106 | +For Redux selectors and other code paths without access to the controller |
| 107 | +instance, use the exported selector(s): |
| 108 | + |
| 109 | +```typescript |
| 110 | +import { passkeyControllerSelectors } from '@metamask/passkey-controller'; |
| 111 | + |
| 112 | +passkeyControllerSelectors.selectIsPasskeyEnrolled(state); // boolean |
| 113 | +``` |
| 114 | + |
| 115 | +### Errors |
| 116 | + |
| 117 | +`PasskeyControllerError` is thrown for controller failures. Expected operational |
| 118 | +cases use a stable `code` from `PasskeyControllerErrorCode` (for example: |
| 119 | +`not_enrolled`, `no_registration_ceremony`, `authentication_verification_failed`, |
| 120 | +`missing_key_material`, `vault_key_decryption_failed`). Human-readable strings |
| 121 | +live on `PasskeyControllerErrorMessage`. Use `instanceof PasskeyControllerError` |
| 122 | +and a defined `error.code` to tell these apart from malformed WebAuthn payloads |
| 123 | +and other `Error` values. Thrown errors from the internal WebAuthn verify helpers |
| 124 | +are also surfaced as `PasskeyControllerError` with the same `registration_verification_failed` |
| 125 | +or `authentication_verification_failed` code and the original error as `cause`. |
| 126 | +`verifyPasskeyAuthentication` returns `false` only for |
| 127 | +those controller errors (with `code`) and rethrows everything else. |
| 128 | + |
| 129 | +## API |
| 130 | + |
| 131 | +### State |
| 132 | + |
| 133 | +| Property | Type | Description | |
| 134 | +| --------------- | ----------------------- | --------------------------------------------------------------------------------------------- | |
| 135 | +| `passkeyRecord` | `PasskeyRecord \| null` | Enrolled passkey credential data and encrypted vault key. `null` when no passkey is enrolled. | |
| 136 | + |
| 137 | +### Messenger actions |
| 138 | + |
| 139 | +| Action | Handler | |
| 140 | +| ---------------------------- | ------------------------------------ | |
| 141 | +| `PasskeyController:getState` | Returns the current controller state | |
| 142 | + |
| 143 | +For derived enrollment status outside of components that hold a controller |
| 144 | +reference, use `passkeyControllerSelectors.selectIsPasskeyEnrolled` (see |
| 145 | +[Selectors](#selectors)). |
| 146 | + |
| 147 | +### Messenger events |
| 148 | + |
| 149 | +| Event | Payload | |
| 150 | +| -------------------------------- | ------------------------------------------------------------ | |
| 151 | +| `PasskeyController:stateChanged` | Emitted when state changes (standard `BaseController` event) | |
| 152 | + |
| 153 | +## Contributing |
| 154 | + |
| 155 | +This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme). |
0 commit comments