Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
b7ef598
feat: read enrolled identifiers and bind challenges to the profile
huggingbot Oct 28, 2026
61e9370
docs: add changelog entries for getIdentifiers
huggingbot Oct 28, 2026
3d6bb9b
refactor: rename EscrowIdentifiers to GetIdentifiersResponse
huggingbot Oct 28, 2026
6bcf84c
feat: prove new SIWE identifiers with recovery mutations
huggingbot Oct 28, 2026
01d7d43
docs: add changelog entry for SIWE proofs
huggingbot Oct 28, 2026
3436a6d
docs: note the SIWE approvedIdentifiers exemption
huggingbot Oct 28, 2026
023dfc5
fix: simplify new SIWE identifier lookup and validate SIWE namespace
huggingbot Oct 28, 2026
19c3300
feat: fence recovery approvals with a per-profile lease
huggingbot Oct 29, 2026
8dbfe32
chore: Update doc
huggingbot Nov 6, 2026
9e66a7d
fix: count SIWE address casing variants as one identifier
huggingbot Nov 6, 2026
dee2a3a
fix: validate SIWE verifier fields before deriving namespace
huggingbot Nov 6, 2026
3d08d44
Merge remote-tracking branch 'origin/main' into feat/mfa-recovery-siw…
huggingbot Nov 10, 2026
2386920
Merge remote-tracking branch 'origin/feat/mfa-recovery-siwe-enrollmen…
huggingbot Nov 10, 2026
2bda960
Merge remote-tracking branch 'origin/main' into feat/mfa-recovery-locks
huggingbot Nov 11, 2026
10b8c1b
fix: drop the lock ID when another operation holds the lease
huggingbot Nov 12, 2026
433bb4d
fix: drop the lock ID when release finds another operation's lease
huggingbot Nov 12, 2026
921e24c
fix: acquire the lease before every approval and drop renewLock
huggingbot Nov 12, 2026
07cb4d5
test: make the lock stub reject a non-owner release
huggingbot Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions packages/mfa-recovery-controller/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,11 @@ flowchart LR

| Piece | Role |
| --------------------------- | --------------------------------------------------------------------------- |
| `pendingOperation` | Only persisted field: encrypted `authorizing` / `writing` blob, or `null` |
| `pendingOperation` | Persisted encrypted `authorizing` / `writing` blob, or `null` |
| `lockId` | Persisted lease ID, reused on retry and restart, or `null` |
| `escrows[]` | Build-time replica set; non-empty, unique `id`s; mutations require **all** |
| `authProvider` | Profile id + request-bound Auth API approval |
| `lockProvider` | Per-profile lease, acquired before every approval |
| `identifierAuthProvider` | Key-bound IdP assertion (passkey / OIDC / SIWE) |
| `pendingOperationEncryptor` | Encrypts / decrypts the pending blob with wallet secure storage |
| `now` | Clock (Unix seconds) for AuthController token expiry; defaults to `unixNow` |
Expand Down Expand Up @@ -67,7 +69,9 @@ matches the hash computed over its hex-encoded form.

Public surface (all exposed as messenger actions): `register`,
`updateRecoverySecret`, `updateIdentifiers`, `authenticateIdentifier`,
`getRecoverySecret`, `getIdentifiers`, `resume`, `abort`, `getPhase`.
`getRecoverySecret`, `getIdentifiers`, `resume`, `abort`, `getPhase`,
`acquireLock`, `releaseLock` (see
[Recovery Lock](README.md#recovery-lock)).

`getIdentifiers` takes an AAL1 approval and returns the enrolled identifiers
at the highest consistent escrow version as `epoch`, plus Auth's identifiers.
Expand Down
2 changes: 2 additions & 0 deletions packages/mfa-recovery-controller/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Rejects SIWE identifiers with malformed verifier fields, an invalid address or domain, or a `namespace` that is not their verifier's `domain:chainId` with `invalid_identifier` ([#11151](https://github.com/MetaMask/core/pull/11151))
- Rejects duplicate identifiers with `duplicate_identifier` and more than 16 identifiers with `too_many_identifiers` ([#11151](https://github.com/MetaMask/core/pull/11151))
- Clears a `writing` mutation in `abort()` and `resume()` once its approval has expired and no escrow applied it; `resume()` then throws `MutationRejectedError` ([#11151](https://github.com/MetaMask/core/pull/11151))
- Requires a `lockProvider` and adds `acquireLock` and `releaseLock`; the lease is acquired, or extended if already held, before every approval, and its ID is persisted in `lockId` ([#10910](https://github.com/MetaMask/core/pull/10910))
- Exports `RecoveryRegistrationLockProvider`, `RecoveryRegistrationLockProviderOptions`, `RecoveryRegistrationLockProviderMessenger` and `RecoveryLockProvider` for holding the lease in the recovery registration service ([#10910](https://github.com/MetaMask/core/pull/10910))
- Exports `MfaRecoveryController`, `getDefaultMfaRecoveryControllerState`, and the controller's action, event, messenger, state, and options types.
- Exports `AuthApiRecoveryAuthProvider`, `AuthApiRecoveryAuthProviderOptions` and `AuthApiRecoveryAuthProviderMessenger` for requesting approvals through `AuthenticationController:requestMfaApproval`, using the profile id from `AuthenticationController:refreshCanonicalProfileId` ([#10883](https://github.com/MetaMask/core/pull/10883))
- Exports `CubistEscrowProvider` and `CubistEscrowProviderOptions` for storing recovery secrets with CubeSigner.
Expand Down
15 changes: 15 additions & 0 deletions packages/mfa-recovery-controller/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,21 @@ Pending mutations are encrypted in controller state. `resume()` completes them;
`abort()` is allowed before writing, or once the write approval has expired and
no escrow applied the mutation. See [Architecture](ARCHITECTURE.md).

## Recovery Lock

Configure `RecoveryRegistrationLockProvider` with the registration service URL,
`fetch`, and a messenger that can call
`AuthenticationController:getBearerToken` and
`AuthenticationController:refreshCanonicalProfileId`.

Call `acquireLock()` before reading identifiers, hold it while changing Auth
identifiers and mutating, then call `releaseLock()`. Call `acquireLock()` again
after long user interaction to extend the lease.

The controller acquires the 6-minute lease before every 5-minute approval, and
escrows reject expired approvals. So once another operation can take the lease,
this operation's approvals are dead.

## Auth API Integration

Configure `AuthApiRecoveryAuthProvider` with a messenger that can call
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import type { Identifier } from '../src/types.js';
import {
StubAuthProvider,
StubIdentifierAuthProvider,
StubRecoveryLockProvider,
passthroughEncryptor,
} from '../tests/stubs.js';

Expand Down Expand Up @@ -133,6 +134,7 @@ async function main(flags: Record<string, string>): Promise<void> {
const controller = new MfaRecoveryController({
messenger: getControllerMessenger(),
authProvider: new StubAuthProvider([PASSKEY, SOCIAL]),
lockProvider: new StubRecoveryLockProvider(),
identifierAuthProvider: new StubIdentifierAuthProvider(),
escrows: [escrow],
pendingOperationEncryptor: passthroughEncryptor,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,23 @@

import type { MfaRecoveryController } from './MfaRecoveryController.js';

/**
* Acquires or extends the per-profile recovery lease. Hold it from the first
* read through any Auth identifier changes and mutations.
*/
export type MfaRecoveryControllerAcquireLockAction = {
type: `MfaRecoveryController:acquireLock`;
handler: MfaRecoveryController['acquireLock'];
};

/**
* Releases the lease. A pending mutation must finish first.
*/
export type MfaRecoveryControllerReleaseLockAction = {
type: `MfaRecoveryController:releaseLock`;
handler: MfaRecoveryController['releaseLock'];
};

/**
* Creates version 1 of a recovery record.
*
Expand Down Expand Up @@ -111,6 +128,8 @@ export type MfaRecoveryControllerGetPhaseAction = {
* Union of all MfaRecoveryController action types.
*/
export type MfaRecoveryControllerMethodActions =
| MfaRecoveryControllerAcquireLockAction
| MfaRecoveryControllerReleaseLockAction
| MfaRecoveryControllerRegisterAction
| MfaRecoveryControllerUpdateRecoverySecretAction
| MfaRecoveryControllerUpdateIdentifiersAction
Expand Down
167 changes: 163 additions & 4 deletions packages/mfa-recovery-controller/src/MfaRecoveryController.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import {
StubAuthProvider,
StubEscrowProvider,
StubIdentifierAuthProvider,
StubRecoveryLockProvider,
createAuthControllerToken,
passthroughEncryptor,
} from '../tests/stubs.js';
Expand All @@ -21,7 +22,11 @@ import {
hash,
unixNow,
} from './crypto.js';
import { IncompleteMutationError, MutationRejectedError } from './errors.js';
import {
IncompleteMutationError,
MfaRecoveryError,
MutationRejectedError,
} from './errors.js';
import type {
MfaRecoveryControllerMessenger,
MfaRecoveryControllerOptions,
Expand Down Expand Up @@ -70,6 +75,7 @@ describe('MfaRecoveryController', () => {
await withController(({ controller }) => {
expect(controller.state).toMatchInlineSnapshot(`
{
"lockId": null,
"pendingOperation": null,
}
`);
Expand All @@ -83,6 +89,7 @@ describe('MfaRecoveryController', () => {
new MfaRecoveryController({
messenger: getMessenger(rootMessenger),
authProvider: new StubAuthProvider(),
lockProvider: new StubRecoveryLockProvider(),
identifierAuthProvider: new StubIdentifierAuthProvider(),
escrows: [],
pendingOperationEncryptor: passthroughEncryptor,
Expand All @@ -99,6 +106,7 @@ describe('MfaRecoveryController', () => {
new MfaRecoveryController({
messenger: getMessenger(rootMessenger),
authProvider: new StubAuthProvider(),
lockProvider: new StubRecoveryLockProvider(),
identifierAuthProvider: new StubIdentifierAuthProvider(),
escrows: [
new StubEscrowProvider('escrow-a', wrapKey, receiptKey),
Expand Down Expand Up @@ -145,6 +153,7 @@ describe('MfaRecoveryController', () => {
),
).toMatchInlineSnapshot(`
{
"lockId": null,
"pendingOperation": null,
}
`);
Expand All @@ -168,6 +177,145 @@ describe('MfaRecoveryController', () => {
});
});

describe('recovery lock', () => {
it('acquires the lease with the same ID before every approval', async () => {
await withController(
async ({ controller, authProvider, lockProvider }) => {
const calls: string[] = [];
vi.spyOn(lockProvider, 'acquire').mockImplementation(
async (lockId) => {
calls.push(`acquire ${lockId}`);
},
);
const authorize =
authProvider.authorizeRecoveryRequest.bind(authProvider);
vi.spyOn(authProvider, 'authorizeRecoveryRequest').mockImplementation(
async (params) => {
calls.push('approval');
return await authorize(params);
},
);

await controller.register(SECRET, IDENTIFIERS);
await controller.updateRecoverySecret(
PASSKEY,
SECRET_2,
REGISTERED_EPOCH,
);

const { lockId } = controller.state;
expect(calls).toStrictEqual([
`acquire ${lockId}`,
'approval',
`acquire ${lockId}`,
'approval',
]);
expect(lockId).toStrictEqual(expect.any(String));
},
);
});

it('requests no approval when another operation holds the lease', async () => {
await withController(
async ({ controller, authProvider, lockProvider }) => {
lockProvider.lockId = 'other-operation';
const authorize = vi.spyOn(authProvider, 'authorizeRecoveryRequest');

await expect(
controller.register(SECRET, IDENTIFIERS),
).rejects.toMatchObject({ code: 'recovery_lock_conflict' });
expect(authorize).not.toHaveBeenCalled();
},
);
});

it('drops the lock ID when another operation holds the lease', async () => {
await withController(async ({ controller, lockProvider }) => {
lockProvider.lockId = 'other-operation';
await expect(
controller.register(SECRET, IDENTIFIERS),
).rejects.toMatchObject({ code: 'recovery_lock_conflict' });
expect(controller.state.lockId).toBeNull();

lockProvider.lockId = null;
await controller.resume();
expect(await controller.getPhase()).toBe('idle');
expect(controller.state.lockId).toBe(lockProvider.lockId);
});
});

it('keeps the lock ID when acquiring fails otherwise', async () => {
await withController(async ({ controller, lockProvider }) => {
vi.spyOn(lockProvider, 'acquire').mockRejectedValueOnce(
new MfaRecoveryError('Unavailable', 'recovery_lock_unavailable'),
);
await expect(controller.acquireLock()).rejects.toMatchObject({
code: 'recovery_lock_unavailable',
});
expect(controller.state.lockId).toStrictEqual(expect.any(String));
});
});

it('drops the lock ID on release when another operation holds the lease', async () => {
await withController(async ({ controller, lockProvider }) => {
await controller.acquireLock();
const release = vi.spyOn(lockProvider, 'release');
release.mockRejectedValueOnce(
new MfaRecoveryError('Unavailable', 'recovery_lock_unavailable'),
);
await expect(controller.releaseLock()).rejects.toMatchObject({
code: 'recovery_lock_unavailable',
});
expect(controller.state.lockId).toStrictEqual(expect.any(String));

lockProvider.lockId = 'other-operation';
await controller.releaseLock();
expect(controller.state.lockId).toBeNull();
expect(lockProvider.lockId).toBe('other-operation');
});
});

it('reuses the persisted lock ID and releases it', async () => {
await withController(async ({ controller, lockProvider }) => {
await controller.acquireLock();
const { lockId } = controller.state;
await controller.acquireLock();
expect(controller.state.lockId).toBe(lockId);
expect(lockProvider.lockId).toBe(lockId);

await controller.releaseLock();
expect(controller.state.lockId).toBeNull();
expect(lockProvider.lockId).toBeNull();
await controller.releaseLock();
});
});

it('reacquires an expired lease before an approval', async () => {
await withController(async ({ controller, lockProvider }) => {
await controller.acquireLock();
const { lockId } = controller.state;
lockProvider.lockId = null;

await controller.register(SECRET, IDENTIFIERS);

expect(lockProvider.lockId).toBe(lockId);
});
});

it('keeps the lease while a mutation is pending', async () => {
await withController(async ({ controller, escrowA }) => {
escrowA.failNextApplyCount = 1;
await expect(
controller.register(SECRET, IDENTIFIERS),
).rejects.toBeInstanceOf(IncompleteMutationError);

await expect(controller.releaseLock()).rejects.toMatchObject({
code: 'pending_mutation',
});
});
});
});

describe('register', () => {
it('replicates the recovery secret to every escrow', async () => {
await withController(async ({ controller, escrowA, escrowB }) => {
Expand Down Expand Up @@ -228,7 +376,7 @@ describe('MfaRecoveryController', () => {

expect(listener).toHaveBeenCalled();
expect(listener).toHaveBeenLastCalledWith(
{ pendingOperation: null },
{ lockId: expect.any(String), pendingOperation: null },
expect.any(Array),
);
});
Expand Down Expand Up @@ -1072,6 +1220,7 @@ describe('MfaRecoveryController', () => {
...options,
messenger: getMessenger(getRootMessenger()),
state: {
lockId: controller.state.lockId,
pendingOperation: await passthroughEncryptor.encrypt(pending),
},
});
Expand Down Expand Up @@ -1388,6 +1537,7 @@ describe('MfaRecoveryController', () => {
...options,
messenger: getMessenger(getRootMessenger()),
state: {
lockId: controller.state.lockId,
pendingOperation: await passthroughEncryptor.encrypt(authorizing),
},
});
Expand Down Expand Up @@ -1737,7 +1887,10 @@ describe('MfaRecoveryController', () => {
const resumed = new MfaRecoveryController({
...options,
messenger: getMessenger(getRootMessenger()),
state: { pendingOperation: JSON.stringify(pending) },
state: {
lockId: controller.state.lockId,
pendingOperation: JSON.stringify(pending),
},
});
options.authProvider.identifiers = [...IDENTIFIERS, OTHER_PASSKEY];
const apply = vi.spyOn(escrowA, 'applyMutation');
Expand Down Expand Up @@ -2110,6 +2263,7 @@ type RootMessenger = Messenger<
type WithControllerCallback<ReturnValue> = (payload: {
controller: MfaRecoveryController;
authProvider: StubAuthProvider;
lockProvider: StubRecoveryLockProvider;
rootMessenger: RootMessenger;
controllerMessenger: MfaRecoveryControllerMessenger;
escrowA: StubEscrowProvider;
Expand All @@ -2133,10 +2287,14 @@ function getMessenger(
function getOptions(
escrowA: StubEscrowProvider,
escrowB: StubEscrowProvider,
): MfaRecoveryControllerOptions & { authProvider: StubAuthProvider } {
): MfaRecoveryControllerOptions & {
authProvider: StubAuthProvider;
lockProvider: StubRecoveryLockProvider;
} {
return {
messenger: getMessenger(getRootMessenger()),
authProvider: new StubAuthProvider(IDENTIFIERS),
lockProvider: new StubRecoveryLockProvider(),
identifierAuthProvider: new StubIdentifierAuthProvider(),
escrows: [escrowA, escrowB],
pendingOperationEncryptor: passthroughEncryptor,
Expand Down Expand Up @@ -2214,6 +2372,7 @@ async function withController<ReturnValue>(
return await testFunction({
controller,
authProvider: options.authProvider,
lockProvider: options.lockProvider,
rootMessenger,
controllerMessenger,
escrowA,
Expand Down
Loading
Loading