fix(auth): a new recovery phrase takes the password too

password.setRecoveryKeys took a session and a TOTP code alone, so a phone signed in with its authenticator beside it could set a phrase of its holder's own and, through the phrase's reset, a new password, never knowing the old one. It now takes the old password's SRP proof (from beginChange, the caller's own) and a TOTP or recovery code, as changing the password does: one owner proof for both (_proveOwner), forwarded by members, asked for in the account section's New recovery phrase. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-10-20 20:01:07 +02:00 · 2026-10-20 20:01:07 +02:00 · 5fb28bd817
commit 5fb28bd817
parent 4f7b123ad4
23 changed files with 447 additions and 169 deletions
--- a/docs/adr/0017-password-totp-and-keys.md
+++ b/docs/adr/0017-password-totp-and-keys.md
@ -176,7 +176,10 @@ released, stays at 1), after the second reading.
 - **Changing while signed in:** the password (`password.beginChange`, `password.change`:
  the old password's SRP proof, a TOTP or recovery code, the same keys rewrapped on the
  device; every other session ends) and the recovery phrase (`password.setRecoveryKeys`:
-  the keys wrapped under a new phrase, for a code). A session alone changes neither.
+  the keys wrapped under a new phrase, with the old password's proof and a code, as a
+  change of password takes). A session alone changes neither, nor a session with the
+  authenticator beside it (a phone signed in): its holder's own phrase would set a new
+  password through `resetPasswordWithPhrase` (found at step 3's review, 20 Oct).
 - **Sessions end in every service:** a change of password ends every other session of
  the account, a reset of the password or the account all of them, on the register and
  on every member, by a notice kept until each confirms (`sessions_ended_notice`, a new
--- a/packages/halkyon_app/lib/src/password/bloc/account_security_cubit.dart
+++ b/packages/halkyon_app/lib/src/password/bloc/account_security_cubit.dart
@ -195,7 +195,7 @@ enum NewPhraseStep() {
  /// Shown, to write down.
  shown,

-  /// Three words typed back, and a code.
+  /// Three words typed back, the password and a code.
  check,

  /// Kept: the old one opens nothing any more.
@ -228,7 +228,7 @@ final class const NewPhraseState({

 /// A new recovery phrase for the signed-in person's keys (on this device):
 /// made, shown, three of its words typed back, then kept by the instance
-/// for a code from the authenticator.
+/// for the password and a code from the authenticator.
 class NewPhraseCubit(final PasswordRepository _passwords)
    extends Cubit<NewPhraseState> {
  this : super(const NewPhraseState());
@ -263,15 +263,20 @@ class NewPhraseCubit(final PasswordRepository _passwords)
  void shownAgain() =>
      emit(NewPhraseState(step: NewPhraseStep.shown, phrase: state.phrase));

-  /// The words typed back, and a [code]: the instance keeps it.
-  Future<void> checked(List<String> words, String code) async {
+  /// The words typed back, the [password] and a [code]: the instance keeps
+  /// it.
+  Future<void> checked(
+    List<String> words, {
+    required String password,
+    required String code,
+  }) async {
    if (!checksPhrase(state.phrase, state.checked, words)) {
      emit(_again(phraseWrong: true));
      return;
    }
    emit(_again(busy: true));
    try {
-      await _passwords.keepPhrase(_made!, code);
+      await _passwords.keepPhrase(_made!, password: password, code: code);
      if (!isClosed) {
        emit(NewPhraseState(step: NewPhraseStep.done, phrase: state.phrase));
      }
--- a/packages/halkyon_app/lib/src/password/data/password_gateway.dart
+++ b/packages/halkyon_app/lib/src/password/data/password_gateway.dart
@ -104,8 +104,16 @@ abstract interface class PasswordGateway() {
    required protocol.NewPassword password,
  });

-  /// A new recovery phrase's wrapping of the keys, for a [code].
-  Future<void> setRecoveryKeys(String code, protocol.WrappedKeys keys);
+  /// A new recovery phrase's wrapping of the keys: [answer] to [challenge]
+  /// ([beginChange]) proves the password, with a [totpCode] or
+  /// [recoveryCode].
+  Future<void> setRecoveryKeys(
+    protocol.PasswordChallenge challenge,
+    SrpAnswer answer, {
+    String? totpCode,
+    String? recoveryCode,
+    required protocol.WrappedKeys keys,
+  });

  /// Asks for the reset of a lost authenticator: [answer] to [challenge]
  /// proves the password, and a code mailed for [request] or the recovery
--- a/packages/halkyon_app/lib/src/password/data/password_repository.dart
+++ b/packages/halkyon_app/lib/src/password/data/password_repository.dart
@ -338,12 +338,27 @@ class PasswordRepository(
    return NewPhrase(made.phrase, made.recoveryKeys);
  }

-  /// [phrase] in place of the old recovery phrase, for a [code]: the old
-  /// one opens nothing any more.
-  Future<void> keepPhrase(NewPhrase phrase, String code) async {
+  /// [phrase] in place of the old recovery phrase, with the [password] and
+  /// a [code] from an authenticator, as changing the password takes: the old
+  /// phrase opens nothing any more. (A session and a code alone would let
+  /// whoever holds a phone signed in set a phrase of their own, and with it
+  /// a new password.)
+  Future<void> keepPhrase(
+    NewPhrase phrase, {
+    required String password,
+    required String code,
+  }) async {
+    final challenge = await _gateway.beginChange();
+    final unlock = await _crypto.unlock(
+      password,
+      salt: Uint8List.sublistView(challenge.salt),
+      costs: challenge.costs,
+    );
    await _gateway.setRecoveryKeys(
-      code.replaceAll(' ', ''),
-      phrase._recoveryKeys,
+      challenge,
+      await _crypto.answer(unlock, challenge),
+      totpCode: code.replaceAll(' ', ''),
+      keys: phrase._recoveryKeys,
    );
    _changed();
  }
--- a/packages/halkyon_app/lib/src/password/data/serverpod_password_gateway.dart
+++ b/packages/halkyon_app/lib/src/password/data/serverpod_password_gateway.dart
@ -190,10 +190,22 @@ class ServerpodPasswordGateway(
  );

  @override
-  Future<void> setRecoveryKeys(String code, protocol.WrappedKeys keys) =>
-      _failing(
-        () => _base.password.setRecoveryKeys(code: code, recoveryKeys: keys),
-      );
+  Future<void> setRecoveryKeys(
+    protocol.PasswordChallenge challenge,
+    SrpAnswer answer, {
+    String? totpCode,
+    String? recoveryCode,
+    required protocol.WrappedKeys keys,
+  }) => _failing(
+    () => _base.password.setRecoveryKeys(
+      challenge: challenge.challenge,
+      clientValue: answer.clientValue,
+      clientProof: answer.clientProof,
+      totpCode: totpCode,
+      recoveryCode: recoveryCode,
+      recoveryKeys: keys,
+    ),
+  );

  @override
  Future<DateTime> resetAuthenticator(
--- a/packages/halkyon_app/lib/src/password/widget/account_security_section.dart
+++ b/packages/halkyon_app/lib/src/password/widget/account_security_section.dart
@ -570,6 +570,7 @@ class const _NewPhrase() extends StatefulWidget {

 class _NewPhraseState() extends State<_NewPhrase> {
  final _words = [for (var i = 0; i < 3; i++) TextEditingController()];
+  final _password = TextEditingController();
  final _code = TextEditingController();
  late final NewPhraseCubit _cubit;

@ -584,6 +585,7 @@ class _NewPhraseState() extends State<_NewPhrase> {
    for (final word in _words) {
      word.dispose();
    }
+    _password.dispose();
    _code.dispose();
    _cubit.close();
    super.dispose();
@ -594,7 +596,11 @@ class _NewPhraseState() extends State<_NewPhrase> {
      case NewPhraseStep.shown:
        _cubit.writtenDown();
      case NewPhraseStep.check:
-        _cubit.checked([for (final word in _words) word.text], _code.text);
+        _cubit.checked(
+          [for (final word in _words) word.text],
+          password: _password.text,
+          code: _code.text,
+        );
      case NewPhraseStep.making || NewPhraseStep.done:
        Navigator.of(context).pop();
    }
@ -611,6 +617,7 @@ class _NewPhraseState() extends State<_NewPhrase> {
          for (final word in _words) {
            word.clear();
          }
+          _password.clear();
          _code.clear();
        }
        if (state.step == NewPhraseStep.done) {
@ -653,6 +660,14 @@ class _NewPhraseState() extends State<_NewPhrase> {
                      ? l10n.passwordPhraseWrong
                      : null,
                ),
+                // The password too, as changing it takes: a phone signed in
+                // with its authenticator must not set a phrase of its own.
+                PasswordField(
+                  controller: _password,
+                  label: l10n.passwordCurrent,
+                  enabled: !state.busy,
+                ),
+                const SizedBox(height: 8),
                CodeField(
                  controller: _code,
                  kind: CodeKind.totp,
--- a/packages/halkyon_app/lib/src/testing/fake_password_gateway.dart
+++ b/packages/halkyon_app/lib/src/testing/fake_password_gateway.dart
@ -496,6 +496,20 @@ class FakePasswordGateway(final AuthGateway _auth) implements PasswordGateway {
    String? recoveryCode,
    required protocol.NewPassword password,
  }) => _call('change', () {
+    _ownerProved(challenge, answer, totpCode, recoveryCode)
+      ..password = utf8.decode(Uint8List.sublistView(password.verifier))
+      ..passwordKeys = password.passwordKeys;
+  });
+
+  /// The signed-in person's account, once [answer] to [challenge] proved
+  /// its password and a code came: refused as the register refuses a
+  /// change.
+  FakePasswordAccount _ownerProved(
+    protocol.PasswordChallenge challenge,
+    SrpAnswer answer,
+    String? totpCode,
+    String? recoveryCode,
+  ) {
    final account = _proved(challenge, answer);
    if (account.person != _signedIn() ||
        ((totpCode ?? '').isEmpty && (recoveryCode ?? '').isEmpty)) {
@ -508,20 +522,19 @@ class FakePasswordGateway(final AuthGateway _auth) implements PasswordGateway {
    )) {
      throw const PasswordFailed(PasswordProblem.setupIncomplete);
    }
-    account
-      ..password = utf8.decode(Uint8List.sublistView(password.verifier))
-      ..passwordKeys = password.passwordKeys;
-  });
+    return account;
+  }

  @override
-  Future<void> setRecoveryKeys(String code, protocol.WrappedKeys keys) =>
-      _call('setRecoveryKeys', () {
-        final account = _accountAs(null);
-        if (code != fakeTotpCode) {
-          throw const PasswordFailed(PasswordProblem.wrongCode);
-        }
-        account.recoveryKeys = keys;
-      });
+  Future<void> setRecoveryKeys(
+    protocol.PasswordChallenge challenge,
+    SrpAnswer answer, {
+    String? totpCode,
+    String? recoveryCode,
+    required protocol.WrappedKeys keys,
+  }) => _call('setRecoveryKeys', () {
+    _ownerProved(challenge, answer, totpCode, recoveryCode).recoveryKeys = keys;
+  });

  @override
  Future<DateTime> resetAuthenticator(
--- a/packages/halkyon_app/test/password/data/password_repository_test.dart
+++ b/packages/halkyon_app/test/password/data/password_repository_test.dart
@ -302,15 +302,33 @@ void main() {
        expect(anna.password, 'correct horse');
      });

-      test('makes a new recovery phrase, which the instance takes for a '
-          'code', () async {
+      test('makes a new recovery phrase, which the instance takes for the '
+          'password and a code alone', () async {
        final phrase = await passwords.newPhrase();
+        final before = anna.recoveryKeys;
        await expectLater(
-          passwords.keepPhrase(phrase, '000000'),
-          failsWith(PasswordProblem.wrongCode),
+          passwords.keepPhrase(
+            phrase,
+            password: 'correct horse',
+            code: '000000',
+          ),
+          failsWith(PasswordProblem.wrongCredentials),
        );
+        await expectLater(
+          passwords.keepPhrase(
+            phrase,
+            password: 'wrong',
+            code: fakeTotpCode,
+          ),
+          failsWith(PasswordProblem.wrongCredentials),
+        );
+        expect(anna.recoveryKeys, same(before));

-        await passwords.keepPhrase(phrase, fakeTotpCode);
+        await passwords.keepPhrase(
+          phrase,
+          password: 'correct horse',
+          code: fakeTotpCode,
+        );

        await auth.signOut();
        final pending = await passwords.resetPassword(
--- a/packages/halkyon_app/test/password/widget/password_sheets_test.dart
+++ b/packages/halkyon_app/test/password/widget/password_sheets_test.dart
@ -352,5 +352,53 @@ void main() {
        findsOneWidget,
      );
    });
+
+    testWidgets('makes a new recovery phrase only with the password and a '
+        'code', (tester) async {
+      final anna = dependencies.passwordGateway.addAccount(
+        'anna@example.org',
+        password: 'correct horse',
+        crypto: dependencies.crypto,
+      );
+      final passwords = dependencies.passwords;
+      await passwords.enter(
+        await passwords.signIn(
+          await passwords.unlock('anna@example.org', 'correct horse'),
+          totpCode: fakeTotpCode,
+        ),
+      );
+      final before = anna.recoveryKeys;
+      await show(tester);
+
+      await tester.tap(find.text('New recovery phrase'));
+      await tester.pumpAndSettle();
+      expect(
+        find.textContaining(wordsOf(otherFakePhrase).first),
+        findsWidgets,
+      );
+      await tapButton(tester, "I've written it down");
+      await typeCheckedWords(tester, otherFakePhrase);
+      // A code alone, from a phone signed in with its authenticator.
+      await tester.enterText(field('Current password'), 'wrong');
+      await tester.enterText(
+        field('Code from your authenticator app'),
+        fakeTotpCode,
+      );
+      await tapButton(tester, 'Continue');
+      expect(
+        find.text("The address, the password or the code isn't right."),
+        findsOneWidget,
+      );
+      expect(anna.recoveryKeys, same(before));
+
+      await tester.enterText(field('Current password'), 'correct horse');
+      await tapButton(tester, 'Continue');
+
+      expect(anna.recoveryKeys, isNot(same(before)));
+      expect(
+        find.text('New recovery phrase set. The old one no longer works.'),
+        findsOneWidget,
+      );
+    });
  });
 }
--- a/packages/halkyon_base_client/lib/src/protocol/client.dart
+++ b/packages/halkyon_base_client/lib/src/protocol/client.dart
@ -459,16 +459,25 @@ class EndpointPassword extends _isc.EndpointRef {
  );

  /// A new recovery phrase: [recoveryKeys], the caller's keys wrapped under
-  /// it on the device, replace the old wrapping, for a [code] from one of
-  /// their authenticators. Refusals as `setRecoveryKeys`'.
+  /// it on the device, replace the old wrapping, with the password's proof
+  /// for [challenge] ([beginChange]) and a [totpCode] or [recoveryCode], as
+  /// [change] takes. Refusals as `setRecoveryKeys`'.
  _ida.Future<void> setRecoveryKeys({
-    required String code,
+    required _isc.UuidValue challenge,
+    required _idt.ByteData clientValue,
+    required _idt.ByteData clientProof,
+    String? totpCode,
+    String? recoveryCode,
    required _i3so7e0p.WrappedKeys recoveryKeys,
  }) => caller.callServerEndpoint<void>(
    'halkyon_base.password',
    'setRecoveryKeys',
    {
-      'code': code,
+      'challenge': challenge,
+      'clientValue': clientValue,
+      'clientProof': clientProof,
+      'totpCode': totpCode,
+      'recoveryCode': recoveryCode,
      'recoveryKeys': recoveryKeys,
    },
  );
--- a/packages/halkyon_base_server/README.md
+++ b/packages/halkyon_base_server/README.md
@ -15,7 +15,7 @@ Endpoints, under the nickname `base` in a host's client (`client.modules.base.em
 | Endpoint | Methods | Who may call |
 |---|---|---|
 | `anonymousIdp` | `login` (Serverpod's anonymous sign-in, at most 30 new accounts per network and hour) | anyone |
-| `password` | `set`: the caller's password, with the address a mailed code proves unless they have one; `beginChange`, `change`: a new password with the old one's proof and a code, every other session ending; `setRecoveryKeys`: a new recovery phrase's wrapping, for a code | signed in |
+| `password` | `set`: the caller's password, with the address a mailed code proves unless they have one; `beginChange`, `change`: a new password with the old one's proof and a code, every other session ending; `setRecoveryKeys`: a new recovery phrase's wrapping, with the old password's proof and a code | signed in |
 | `passwordSignIn` | `begin`, `complete`: SRP-6a's two steps with a code from an authenticator (or a recovery code; a setup never finished, a code by mail); a session. `signUp`: an account at the address a mailed code proves, with a password; a session | without a session |
 | `authenticator` | `enrol`, `confirm` (the first brings ten recovery codes; another takes a code from one confirmed before), `list`, `remove`, `newRecoveryCodes` | signed in |
 | `accountRecovery` | `resetAuthenticator`, `beginKeyProof`, `resetPassword` (with the recovery phrase), `startAccountReset`, `completeAccountReset` | without a session |
@ -216,8 +216,9 @@ Built on the three parts above, on the register (members forward every step thro
  password, new keys, no authenticators.
 - **Changing while signed in:** `password.beginChange` and `password.change` take the old
  password's SRP proof, a TOTP or recovery code and the same keys wrapped under the new
-  password; `password.setRecoveryKeys` replaces the phrase's wrapping for a code. A
-  session alone changes neither.
+  password; `password.setRecoveryKeys` replaces the phrase's wrapping with the same
+  proof and code (a phrase of one's own would otherwise set a new password through the
+  phrase's reset). A session alone changes neither, nor a session and a code.
 - **Sessions end everywhere:** a change of password ends every other session of the
  account; a reset of the password or the account ends all. The register ends its own
  and keeps a `sessions_ended_notice` per member (told at once and hourly until it
--- a/packages/halkyon_base_server/lib/src/generated/endpoints.dart
+++ b/packages/halkyon_base_server/lib/src/generated/endpoints.dart
@ -729,11 +729,31 @@ class Endpoints extends _is.EndpointDispatch {
        'setRecoveryKeys': _is.MethodConnector(
          name: 'setRecoveryKeys',
          params: {
-            'code': _is.ParameterDescription(
-              name: 'code',
-              type: _is.getType<String>(),
+            'challenge': _is.ParameterDescription(
+              name: 'challenge',
+              type: _is.getType<_is.UuidValue>(),
              nullable: false,
            ),
+            'clientValue': _is.ParameterDescription(
+              name: 'clientValue',
+              type: _is.getType<_idt.ByteData>(),
+              nullable: false,
+            ),
+            'clientProof': _is.ParameterDescription(
+              name: 'clientProof',
+              type: _is.getType<_idt.ByteData>(),
+              nullable: false,
+            ),
+            'totpCode': _is.ParameterDescription(
+              name: 'totpCode',
+              type: _is.getType<String?>(),
+              nullable: true,
+            ),
+            'recoveryCode': _is.ParameterDescription(
+              name: 'recoveryCode',
+              type: _is.getType<String?>(),
+              nullable: true,
+            ),
            'recoveryKeys': _is.ParameterDescription(
              name: 'recoveryKeys',
              type: _is.getType<_iji0wmu8.WrappedKeys>(),
@ -747,7 +767,11 @@ class Endpoints extends _is.EndpointDispatch {
              ) async => (endpoints['password'] as _ig7fyg1b.PasswordEndpoint)
                  .setRecoveryKeys(
                    session,
-                    code: params['code'],
+                    challenge: params['challenge'],
+                    clientValue: params['clientValue'],
+                    clientProof: params['clientProof'],
+                    totpCode: params['totpCode'],
+                    recoveryCode: params['recoveryCode'],
                    recoveryKeys: params['recoveryKeys'],
                  ),
        ),
--- a/packages/halkyon_base_server/lib/src/password/authenticators.dart
+++ b/packages/halkyon_base_server/lib/src/password/authenticators.dart
@ -272,7 +272,7 @@ Future<void> removeAuthenticator(
  if (confirmed.length < 2) {
    throw refusedFor(PasswordRefusal.lastAuthenticator);
  }
-  await requireAuthenticatorCode(session, keys, person, confirmed, code);
+  await _requireAuthenticatorCode(session, keys, person, confirmed, code);
  // Serializable: two removals at once must not take both of the last two.
  await session.db.transaction(
    (transaction) async {
@ -318,7 +318,7 @@ Future<List<String>> newRecoveryCodes(
  if (confirmed.isEmpty) {
    throw refusedFor(PasswordRefusal.setupIncomplete);
  }
-  await requireAuthenticatorCode(session, keys, person, confirmed, code);
+  await _requireAuthenticatorCode(session, keys, person, confirmed, code);
  return await session.db.transaction(
    (transaction) =>
        _replaceRecoveryCodes(session, keys, person, transaction: transaction),
@ -360,7 +360,7 @@ Future<void> _countTry(Session session, UuidValue person) async {
 /// authenticators, each try counted (10 an hour,
 /// [PasswordRefusal.tooManyAttempts]); refused otherwise
 /// ([PasswordRefusal.wrongCode]).
-Future<void> requireAuthenticatorCode(
+Future<void> _requireAuthenticatorCode(
  Session session,
  PasswordKeys keys,
  UuidValue person,
--- a/packages/halkyon_base_server/lib/src/password/password_change.dart
+++ b/packages/halkyon_base_server/lib/src/password/password_change.dart
@ -2,16 +2,18 @@ import 'dart:typed_data';

 import 'package:clock/clock.dart';
 import 'package:halkyon_base_server/src/generated/protocol.dart';
-import 'package:halkyon_base_server/src/password/authenticators.dart';
+import 'package:halkyon_base_server/src/password/password_config.dart';
 import 'package:halkyon_base_server/src/password/passwords.dart';
 import 'package:halkyon_base_server/src/register/sessions_ended.dart';
 import 'package:serverpod/serverpod.dart';

 // Changing what keeps an account while signed in (ADR 0017), on the
-// register: the password, with the old password's proof and a code from an
-// authenticator, and the recovery phrase's wrapping of the keys, with a code.
-// A session alone changes neither: whoever took one over would otherwise
-// lock the owner out of their keys.
+// register: the password, and the recovery phrase's wrapping of the keys,
+// each with the old password's proof and a code from an authenticator (or a
+// recovery code). A session alone changes neither, nor a session with the
+// authenticator beside it (a phone signed in): a phrase of the holder's own
+// would set a new password through `resetPasswordWithPhrase`, so the phrase
+// takes the password too.

 /// Changes [person]'s password to [password] (the same keys, wrapped under
 /// the new password's key on the device): the old password's proof for
@ -41,32 +43,16 @@ Future<void> changePassword(
  if (!isNewPassword(password)) {
    throw refusedFor(PasswordRefusal.invalidSetup);
  }
-  final proved = await provePassword(
+  final row = await _proveOwner(
    session,
    keys,
+    person: person,
    challenge: challenge,
    clientValue: clientValue,
    clientProof: clientProof,
-  );
-  final row = proved.password;
-  if (row.authUserId != person) {
-    throw refusedFor(PasswordRefusal.wrongCredentials);
-  }
-  if ((totpCode?.trim() ?? '').isEmpty &&
-      (recoveryCode?.trim() ?? '').isEmpty) {
-    throw refusedFor(PasswordRefusal.wrongCredentials);
-  }
-  // With a code: the code is checked, or, where the authenticators' reset
-  // took effect and none is confirmed, it says so (true).
-  if (await secondFactor(
-    session,
-    keys,
-    person,
    totpCode: totpCode,
    recoveryCode: recoveryCode,
-  )) {
-    throw refusedFor(PasswordRefusal.setupIncomplete);
-  }
+  );
  await session.db.transaction((transaction) async {
    // UPDATE "account_password" SET "salt" = $1, "kdfAlgorithm" = $2,
    //   "kdfOpsLimit" = $3, "kdfMemLimit" = $4, "verifier" = $5,
@ -98,38 +84,37 @@ Future<void> changePassword(

 /// Replaces the wrapping of [person]'s keys under their recovery phrase
 /// with [recoveryKeys] (a new phrase, made on the device, which holds the
-/// keys), for a [code] from one of their authenticators: the old phrase opens
-/// nothing any more.
+/// keys): the old password's proof for [challenge] (`beginPasswordChange`)
+/// and a [totpCode] or [recoveryCode] from the account, as changing the
+/// password takes. The old phrase opens nothing any more.
 ///
 /// Refused ([PasswordRefusedException]) for wrapped keys out of range
-/// ([PasswordRefusal.invalidSetup]), without a password
-/// ([PasswordRefusal.noPassword]) or a confirmed authenticator
-/// ([PasswordRefusal.setupIncomplete]), and for a wrong code
-/// ([PasswordRefusal.wrongCode]; 10 tries an hour,
-/// [PasswordRefusal.tooManyAttempts]). Nothing changes then.
+/// ([PasswordRefusal.invalidSetup]), and otherwise as [changePassword].
+/// Nothing changes then.
 Future<void> setRecoveryKeys(
  Session session, {
  required UuidValue person,
-  required String code,
+  required UuidValue challenge,
+  required ByteData clientValue,
+  required ByteData clientProof,
+  String? totpCode,
+  String? recoveryCode,
  required WrappedKeys recoveryKeys,
 }) async {
  final keys = requirePasswordKeys(session.serverpod);
  if (!isWrappedKeys(recoveryKeys)) {
    throw refusedFor(PasswordRefusal.invalidSetup);
  }
-  // SELECT * FROM "account_password" WHERE "authUserId" = $1
-  final row = await AccountPassword.db.findFirstRow(
+  final row = await _proveOwner(
    session,
-    where: (t) => t.authUserId.equals(person),
+    keys,
+    person: person,
+    challenge: challenge,
+    clientValue: clientValue,
+    clientProof: clientProof,
+    totpCode: totpCode,
+    recoveryCode: recoveryCode,
  );
-  if (row == null) {
-    throw refusedFor(PasswordRefusal.noPassword);
-  }
-  final confirmed = await confirmedAuthenticatorsOf(session, person);
-  if (confirmed.isEmpty) {
-    throw refusedFor(PasswordRefusal.setupIncomplete);
-  }
-  await requireAuthenticatorCode(session, keys, person, confirmed, code);
  // UPDATE "account_password" SET "recoveryKeysNonce" = $1,
  //   "recoveryKeysCipherText" = $2, "updatedAt" = $3 WHERE "id" = $4
  await AccountPassword.db.updateRow(
@ -141,3 +126,51 @@ Future<void> setRecoveryKeys(
    ),
  );
 }
+
+/// [person]'s password row, once they proved owning the account for a
+/// change: the old password's proof for [challenge], [person]'s own, and a
+/// [totpCode] or [recoveryCode] ([secondFactor], which also calls off a reset
+/// waiting). Refused ([PasswordRefusedException]) for a wrong password, a
+/// challenge that isn't [person]'s, or a wrong, used or missing code, alike
+/// ([PasswordRefusal.wrongCredentials]); a challenge unknown, used or too old
+/// ([PasswordRefusal.challengeExpired]); and, once the password proved right,
+/// for an account without a confirmed authenticator
+/// ([PasswordRefusal.setupIncomplete]).
+Future<AccountPassword> _proveOwner(
+  Session session,
+  PasswordKeys keys, {
+  required UuidValue person,
+  required UuidValue challenge,
+  required ByteData clientValue,
+  required ByteData clientProof,
+  String? totpCode,
+  String? recoveryCode,
+}) async {
+  final proved = await provePassword(
+    session,
+    keys,
+    challenge: challenge,
+    clientValue: clientValue,
+    clientProof: clientProof,
+  );
+  final row = proved.password;
+  if (row.authUserId != person) {
+    throw refusedFor(PasswordRefusal.wrongCredentials);
+  }
+  if ((totpCode?.trim() ?? '').isEmpty &&
+      (recoveryCode?.trim() ?? '').isEmpty) {
+    throw refusedFor(PasswordRefusal.wrongCredentials);
+  }
+  // With a code: the code is checked, or, where the authenticators' reset
+  // took effect and none is confirmed, it says so (true).
+  if (await secondFactor(
+    session,
+    keys,
+    person,
+    totpCode: totpCode,
+    recoveryCode: recoveryCode,
+  )) {
+    throw refusedFor(PasswordRefusal.setupIncomplete);
+  }
+  return row;
+}
--- a/packages/halkyon_base_server/lib/src/password/password_endpoint.dart
+++ b/packages/halkyon_base_server/lib/src/password/password_endpoint.dart
@ -79,16 +79,25 @@ class PasswordEndpoint extends Endpoint {
  }

  /// A new recovery phrase: [recoveryKeys], the caller's keys wrapped under
-  /// it on the device, replace the old wrapping, for a [code] from one of
-  /// their authenticators. Refusals as `setRecoveryKeys`'.
+  /// it on the device, replace the old wrapping, with the password's proof
+  /// for [challenge] ([beginChange]) and a [totpCode] or [recoveryCode], as
+  /// [change] takes. Refusals as `setRecoveryKeys`'.
  Future<void> setRecoveryKeys(
    Session session, {
-    required String code,
+    required UuidValue challenge,
+    required ByteData clientValue,
+    required ByteData clientProof,
+    String? totpCode,
+    String? recoveryCode,
    required WrappedKeys recoveryKeys,
  }) => AccountRegister.of(session.serverpod).setRecoveryKeys(
    session,
    person: session.authenticated!.authUserId,
-    code: code,
+    challenge: challenge,
+    clientValue: clientValue,
+    clientProof: clientProof,
+    totpCode: totpCode,
+    recoveryCode: recoveryCode,
    recoveryKeys: recoveryKeys,
  );
 }
--- a/packages/halkyon_base_server/lib/src/register/account_register.dart
+++ b/packages/halkyon_base_server/lib/src/register/account_register.dart
@ -300,12 +300,16 @@ abstract interface class AccountRegister {
    UuidValue? keepSession,
  });

-  /// Replaces the wrapping of [person]'s keys under their recovery phrase.
-  /// Refusals as `setRecoveryKeys`'.
+  /// Replaces the wrapping of [person]'s keys under their recovery phrase,
+  /// with the password's proof and a code. Refusals as `setRecoveryKeys`'.
  Future<void> setRecoveryKeys(
    Session session, {
    required UuidValue person,
-    required String code,
+    required UuidValue challenge,
+    required ByteData clientValue,
+    required ByteData clientProof,
+    String? totpCode,
+    String? recoveryCode,
    required WrappedKeys recoveryKeys,
  });

--- a/packages/halkyon_base_server/lib/src/register/instance_api.dart
+++ b/packages/halkyon_base_server/lib/src/register/instance_api.dart
@ -360,7 +360,11 @@ Future<Map<String, Object?>?> _answer(
      await register.setRecoveryKeys(
        session,
        person: arguments.id('person'),
-        code: arguments.string('code'),
+        challenge: arguments.id('challenge'),
+        clientValue: arguments.bytes('clientValue'),
+        clientProof: arguments.bytes('clientProof'),
+        totpCode: arguments.optionalString('totpCode'),
+        recoveryCode: arguments.optionalString('recoveryCode'),
        recoveryKeys: arguments.model('recoveryKeys', WrappedKeys.fromJson),
      );
      return const {};
--- a/packages/halkyon_base_server/lib/src/register/local_register.dart
+++ b/packages/halkyon_base_server/lib/src/register/local_register.dart
@ -620,12 +620,20 @@ final class LocalRegister implements AccountRegister {
  Future<void> setRecoveryKeys(
    Session session, {
    required UuidValue person,
-    required String code,
+    required UuidValue challenge,
+    required ByteData clientValue,
+    required ByteData clientProof,
+    String? totpCode,
+    String? recoveryCode,
    required WrappedKeys recoveryKeys,
  }) => change.setRecoveryKeys(
    session,
    person: person,
-    code: code,
+    challenge: challenge,
+    clientValue: clientValue,
+    clientProof: clientProof,
+    totpCode: totpCode,
+    recoveryCode: recoveryCode,
    recoveryKeys: recoveryKeys,
  );

--- a/packages/halkyon_base_server/lib/src/register/remote_register.dart
+++ b/packages/halkyon_base_server/lib/src/register/remote_register.dart
@ -584,11 +584,19 @@ final class RemoteRegister implements AccountRegister {
  Future<void> setRecoveryKeys(
    Session session, {
    required UuidValue person,
-    required String code,
+    required UuidValue challenge,
+    required ByteData clientValue,
+    required ByteData clientProof,
+    String? totpCode,
+    String? recoveryCode,
    required WrappedKeys recoveryKeys,
  }) => _ask(RegisterOperation.setRecoveryKeys, {
    'person': person.uuid,
-    'code': code,
+    'challenge': challenge.uuid,
+    'clientValue': _bytes(clientValue),
+    'clientProof': _bytes(clientProof),
+    'totpCode': totpCode,
+    'recoveryCode': recoveryCode,
    'recoveryKeys': recoveryKeys.toJson(),
  });

--- a/packages/halkyon_base_server/test/integration/password/password_change_test.dart
+++ b/packages/halkyon_base_server/test/integration/password/password_change_test.dart
@ -316,77 +316,98 @@ void main() {
      });

      group('the recovery phrase', () {
-        test("takes new wrapped keys for a code: the old phrase's wrapping "
-            'goes', () async {
-          final fresh = WrappedKeys(
-            nonce: ByteData(24),
-            cipherText: ByteData(wrappedKeysLength),
-          );
+        final fresh = WrappedKeys(
+          nonce: ByteData(24),
+          cipherText: ByteData(wrappedKeysLength),
+        );

-          await atNow(
-            () => endpoints.password.setRecoveryKeys(
-              onPhone(),
-              code: codeOf(enrolment, at: now),
-              recoveryKeys: fresh,
-            ),
+        /// Gives Anna's keys a new phrase's wrapping ([fresh]) from her
+        /// phone, the old password proved by [privateValue] (hers by
+        /// default) or a made-up proof ([withoutProof]), with [totpCode] (her
+        /// authenticator's now by default).
+        Future<void> newPhrase({
+          BigInt? privateValue,
+          bool withoutProof = false,
+          String? totpCode,
+          bool withoutCode = false,
+          WrappedKeys? recoveryKeys,
+          TestSessionBuilder? as,
+        }) => atNow(() async {
+          final challenge = await endpoints.password.beginChange(onPhone());
+          final answer = device.answer(challenge, privateValue: privateValue);
+          await endpoints.password.setRecoveryKeys(
+            as ?? onPhone(),
+            challenge: challenge.challenge,
+            clientValue: answer.clientValue,
+            clientProof: withoutProof ? ByteData(32) : answer.clientProof,
+            totpCode: withoutCode
+                ? null
+                : totpCode ?? codeOf(enrolment, at: now),
+            recoveryKeys: recoveryKeys ?? fresh,
          );
-
-          final proof = await endpoints.accountRecovery.beginKeyProof(
-            notSignedIn(),
-            address: 'anna@example.org',
-          );
-          expect(proof.recoveryKeys.toJson(), fresh.toJson());
        });

-        test('is refused for a wrong code, keys out of range, and without a '
-            'password, keeping the wrapping', () async {
-          final fresh = WrappedKeys(
-            nonce: ByteData(24),
-            cipherText: ByteData(wrappedKeysLength),
+        Future<WrappedKeys> wrapping() async =>
+            (await endpoints.accountRecovery.beginKeyProof(
+              notSignedIn(),
+              address: 'anna@example.org',
+            )).recoveryKeys;
+
+        test('takes new wrapped keys with the old password and a code: the '
+            "old phrase's wrapping goes", () async {
+          await newPhrase();
+
+          expect((await wrapping()).toJson(), fresh.toJson());
+        });
+
+        test("is refused alike without the password's proof, for a wrong "
+            "one, another person's, and a missing or wrong code, keeping "
+            'the wrapping', () async {
+          // A session and a code alone: whoever holds a phone signed in with
+          // its authenticator would otherwise set a phrase of their own, and
+          // with it a new password.
+          await expectLater(
+            newPhrase(withoutProof: true),
+            refused(PasswordRefusal.wrongCredentials),
          );
          await expectLater(
-            atNow(
-              () => endpoints.password.setRecoveryKeys(
-                onPhone(),
-                code: '000000',
-                recoveryKeys: fresh,
+            newPhrase(privateValue: BigInt.from(4242)),
+            refused(PasswordRefusal.wrongCredentials),
+          );
+          await expectLater(
+            newPhrase(withoutCode: true),
+            refused(PasswordRefusal.wrongCredentials),
+          );
+          await expectLater(
+            newPhrase(totpCode: '000000'),
+            refused(PasswordRefusal.wrongCredentials),
+          );
+          final ben = await newAnonymousPerson(session);
+          final bensLaptop = await signInNewDevice(session, ben);
+          await expectLater(
+            newPhrase(
+              as: sessionBuilder.copyWith(
+                authentication: AuthenticationOverride.authenticationInfo(
+                  ben.uuid,
+                  {identified},
+                  authId: bensLaptop.uuid,
+                ),
              ),
            ),
-            refused(PasswordRefusal.wrongCode),
+            refused(PasswordRefusal.wrongCredentials),
          );
          await expectLater(
-            atNow(
-              () => endpoints.password.setRecoveryKeys(
-                onPhone(),
-                code: codeOf(enrolment, at: now),
-                recoveryKeys: WrappedKeys(
-                  nonce: ByteData(24),
-                  cipherText: ByteData(8),
-                ),
+            newPhrase(
+              recoveryKeys: WrappedKeys(
+                nonce: ByteData(24),
+                cipherText: ByteData(8),
              ),
            ),
            refused(PasswordRefusal.invalidSetup),
          );
-          final ben = await newAnonymousPerson(session);
-          await expectLater(
-            endpoints.password.setRecoveryKeys(
-              sessionBuilder.copyWith(
-                authentication: AuthenticationOverride.authenticationInfo(
-                  ben.uuid,
-                  {},
-                ),
-              ),
-              code: '123456',
-              recoveryKeys: fresh,
-            ),
-            refused(PasswordRefusal.noPassword),
-          );
-          final proof = await endpoints.accountRecovery.beginKeyProof(
-            notSignedIn(),
-            address: 'anna@example.org',
-          );
+
          expect(
-            proof.recoveryKeys.toJson(),
+            (await wrapping()).toJson(),
            device.recoveryKeys.toJson(),
          );
        });
--- a/Show more
+++ b/Show more