@coderoftime/fints 0.1.0 → 0.3.0

package/src/session/session-setup.ts

@@ -1,27 +1,28 @@
 import type { BankInfo } from '../core/bank-info.js';
-import { FinTsBankError, FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData } from '../core/errors.js';
+import { FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData, tryLookUp } from '../core/errors.js';
+import { hasErrors } from '../core/feedback.js';
 import type { TanMedium, TanMethod } from '../tan/tan-models.js';
-import type { LoginGuard, RefusalReason } from './login-guard.js';
-import { requireBankParameters } from './parameter-data.js';
-import type { BankResponse, PinTanProtocol, ProtocolDialog } from './protocol.js';
-import type { ResponseHandler } from './response-handler.js';
+import { FinTs3Dialog } from '../v3/dialog.js';
+import type { IncomingMessage3 } from '../v3/message.js';
+import { requireBankParameters } from '../v3/parameters.js';
+import type { FinTs3Protocol } from '../v3/protocol.js';
+import { tanMediaQuery } from '../v3/queries.js';
+import type { RefusalReason } from './login-guard.js';
+import { SignedDialog, type SessionParts } from './signed-dialog.js';
 import type { TanSelection } from './tan-selection.js';
 
 /**
  * What has to be settled before a login: the bank parameter data, the synchronization, and through `TanSelection` the
  * TAN method and medium. Each of the dialogs this takes serves one purpose only.
  *
- * Where the bank refuses a login for a reason the session can take care of, `remedied` does so and logs in again.
+ * Where the bank refuses a login for a reason the session can take care of, `remedied` does so and logs in again; so it
+ * does where the limits of bank parameter data that may be outdated keep a login from going out.
  */
-export class SessionSetup<R extends BankResponse, O> {
-  /** Whether a synchronization dialog ran, so that a helpful one runs once only. */
-  private synchronizationTried = false;
-
+export class SessionSetup {
   constructor(
-    private readonly protocol: PinTanProtocol<R, O>,
-    private readonly responses: ResponseHandler<R>,
-    private readonly tans: TanSelection<R, O>,
-    private readonly guard: LoginGuard,
+    private readonly session: SessionParts,
+    private readonly protocol: FinTs3Protocol,
+    private readonly tans: TanSelection,
   ) {}
 
   /**
@@ -29,9 +30,9 @@ export class SessionSetup<R extends BankResponse, O> {
    * No TAN method or medium is chosen for it.
    */
   async bankInfo(): Promise<BankInfo> {
-    if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
-    if (this.protocol.bankParameters === undefined) await this.synchronizeIfDue();
-    return requireBankParameters(this.protocol.bankParameters).bankInfo;
+    if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    if (this.session.parameters.bankParameters === undefined) await this.synchronizeIfDue();
+    return requireBankParameters(this.session.parameters.bankParameters).bankInfo;
   }
 
   /** The TAN methods the bank allows for this user, which the synchronization reports. */
@@ -40,56 +41,58 @@ export class SessionSetup<R extends BankResponse, O> {
     return this.tans.available();
   }
 
-  /** Settles what is still open: the bank parameter data, the synchronization, the TAN method and medium. */
-  async prepare(): Promise<void> {
+  /**
+   * Settles what is still open: the bank parameter data, the synchronization, the TAN method and medium. Returns the TAN
+   * media it looked up to choose the medium; `undefined` where it looked up none, or the bank listed none.
+   */
+  async prepare(): Promise<TanMedium[] | undefined> {
     await this.loadParameters();
     await this.tans.ensureMethodChosen();
-    if (this.tans.mediumToLookUp) await this.tans.chooseMedium(await this.lookUpTanMedia());
+    if (!this.tans.mediumToLookUp) return undefined;
+    const media = await this.lookUpTanMedia();
+    await this.tans.chooseMedium(media);
+    return media;
   }
 
   /** A new dialog signed with the TAN method and medium in use, once `prepare` has settled them. */
-  async newDialog(): Promise<ProtocolDialog<R, O>> {
+  async newDialog(): Promise<SignedDialog> {
     await this.prepare();
-    return this.tans.newDialog();
+    return new SignedDialog(this.tans.newDialog(), this.session);
   }
 
   /**
-   * Runs `attempt`, which may log in, and runs it once more for each reason of a refused login the session can take
-   * care of, so that a bank that keeps refusing fails with its own error:
+   * Runs `attempt`, which may log in, once more after each refused login `remedy` takes care of.
    *
-   * | Refusal (`LoginGuard.remediableReasons`) | Remedy |
-   * | --- | --- |
-   * | 3920 without the method, or 9075 after the one-step method | another allowed method (`TanSelection.replace`) |
-   * | 9391 | a new synchronization, which issues a customer system ID |
+   * Where the limits of the bank parameter data kept a login from going out (`FinTs3Protocol.stoppedLogin`), it fetches
+   * them anew in an anonymous dialog, once, and runs `attempt` once more: they may be outdated, as saved ones are, and
+   * new ones would come only in answer to the login they rule out. The new limits judge the login built anew, not the
+   * one stopped: it reports version 0 for the parameter data they stand in for, so it may be shorter.
    */
   async remedied<T>(attempt: () => Promise<T>): Promise<T> {
-    // A refusal of an earlier call stops the attempt before it sends the PIN; there is nothing to remedy.
-    if (this.guard.hasRefusal) return attempt();
-    const remedied = new Set<RefusalReason>();
-    for (;;) {
-      try {
-        return await attempt();
-      } catch (error) {
-        if (!(error instanceof FinTsBankError)) throw error;
-        const reason = this.guard.remediableReasons(error).find((r) => !remedied.has(r));
-        const rejected = this.guard.refusedMethod;
-        if (reason === undefined || rejected === undefined || !(await this.remedy(reason, rejected))) throw error;
-        remedied.add(reason);
-        this.guard.pardon(error);
-      }
+    const run = (): Promise<T> =>
+      this.session.guard.remedied(attempt, (reason, rejected) => this.remedy(reason, rejected));
+    try {
+      return await run();
+    } catch (error) {
+      if (!this.protocol.stoppedLogin(error)) throw error;
+      await this.fetchBankParametersAnonymously(true);
+      return run();
     }
   }
 
-  /** Takes care of `reason`, given for refusing a login signed with `rejected`; returns whether it could. */
+  /**
+   * Takes care of `reason`, given for refusing a login signed with `rejected`, with another TAN method or a new
+   * synchronization; returns whether it could.
+   */
   private async remedy(reason: RefusalReason, rejected: TanMethod): Promise<boolean> {
     switch (reason) {
       case 'tanMethodNotAllowed':
         // The parameter data name the methods to choose from; the refusal may be the first to deliver them.
-        if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+        if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
         return this.tans.replace(rejected);
       case 'systemIdRejected':
         // Without a customer system ID there is none to lose, and logging in once more would only send the PIN again.
-        return this.protocol.forgetSystemId();
+        return this.session.parameters.forgetSystemId();
     }
   }
 
@@ -103,35 +106,68 @@ export class SessionSetup<R extends BankResponse, O> {
    * After a refused login it throws the refusal right away, before the user is asked for a TAN method or medium.
    */
   private async loadParameters(): Promise<void> {
-    this.guard.check();
-    if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    this.session.guard.check();
+    if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
     await this.synchronizeIfDue();
   }
 
   /**
-   * Asks for the bank parameter data without logging in. A bank that does not answer anonymously is no error, but a
-   * failed connection is: the synchronization would only wait for the same server again.
+   * Asks for the bank parameter data without logging in, keeps them where there are none from a dialog signed with the
+   * PIN (`ParameterStore.keepAnonymous`), or with `refresh` their limits only (`ParameterStore.keepRefreshedLimits`),
+   * and passes the bank's messages on: all an anonymous dialog tells, since the TAN methods it lists are not those of a
+   * user. A bank that does not answer anonymously is no error, but a failed connection is: the synchronization would
+   * only wait for the same server again.
    */
-  private async fetchBankParametersAnonymously(): Promise<void> {
+  private async fetchBankParametersAnonymously(refresh = false): Promise<void> {
     try {
-      this.responses.showBankMessages(await this.protocol.fetchBankParametersAnonymously());
+      const response = await this.requestBankParametersAnonymously();
+      if (refresh) this.session.parameters.keepRefreshedLimits(response);
+      else this.session.parameters.keepAnonymous(response);
+      for (const message of response.bankMessages) this.session.prompts.showBankMessage(message);
     } catch (error) {
       // Optional: the login delivers the parameters as well.
       if (error instanceof FinTsTransportError || !(error instanceof FinTsError)) throw error;
     }
   }
 
-  /** Runs the synchronization dialog where it is due (`TanSelection.synchronizationDialog`). */
+  /**
+   * Asks for the bank parameter data in an anonymous dialog that announces strong customer authentication; a bank that
+   * rejects the announcement, with a return code or by failing on it, is asked again without it.
+   *
+   * A timeout or a broken connection is not a reason to ask again: it would only double the wait.
+   */
+  private async requestBankParametersAnonymously(): Promise<IncomingMessage3> {
+    let announced: IncomingMessage3;
+    try {
+      announced = await this.anonymousDialog(true);
+    } catch (error) {
+      if (error instanceof FinTsTransportError && error.statusCode === undefined) throw error;
+      if (!(error instanceof FinTsError)) throw error;
+      return this.anonymousDialog(false);
+    }
+    if (!hasErrors(announced.feedback) || announced.find('HIBPA') !== undefined) return announced;
+    return this.anonymousDialog(false);
+  }
+
+  private async anonymousDialog(announceSca: boolean): Promise<IncomingMessage3> {
+    const dialog = FinTs3Dialog.anonymous(this.protocol);
+    try {
+      return await dialog.requestBankParameters(announceSca);
+    } finally {
+      await dialog.end();
+    }
+  }
+
+  /**
+   * Runs the synchronization, a login in a dialog of its own, while there is no customer system ID, without which no
+   * regular dialog starts. It runs before the TAN method and medium are settled (`TanSelection.synchronizationDialog`
+   * tells which method signs it).
+   */
   private async synchronizeIfDue(): Promise<void> {
-    const due =
-      this.protocol.synchronization === 'required' ||
-      (this.protocol.synchronization === 'helpful' && !this.synchronizationTried);
-    if (!due) return;
-    this.synchronizationTried = true;
-    await this.once(this.tans.synchronizationDialog(), (dialog) =>
-      this.responses.startDialog(dialog, () => dialog.start(true)),
-    );
-    if (this.protocol.synchronization === 'required') {
+    if (this.session.parameters.systemId !== undefined) return;
+    await this.once(this.tans.synchronizationDialog(), (dialog) => dialog.login(true));
+    // Set by the synchronization, which the compiler cannot see.
+    if ((this.session.parameters.systemId as string | undefined) === undefined) {
       throw new FinTsProtocolError('The bank did not complete the synchronization');
     }
   }
@@ -144,22 +180,23 @@ export class SessionSetup<R extends BankResponse, O> {
    * medium the list tells (PIN/TAN B.4.3.1.3).
    */
   private async lookUpTanMedia(): Promise<TanMedium[] | undefined> {
-    const query = this.protocol.tanMedia();
+    const query = tanMediaQuery(this.session.parameters);
     if (query === undefined) return undefined;
-    return this.guard.tryLookUp(() =>
+    return tryLookUp(() =>
       this.once(this.tans.lookupDialog(), async (dialog) => {
-        const pages = await this.responses.startDialogWith(dialog, dialog.startWith(query.order(undefined)));
-        return parseBankData(() => query.read(pages));
+        const answers = await dialog.loginWith(query.order(undefined));
+        return parseBankData(() => query.read(answers));
       }),
     );
   }
 
   /** Runs `use` in `dialog`, a dialog of its own, and ends it afterwards, however `use` ends. */
-  private async once<T>(dialog: ProtocolDialog<R, O>, use: (dialog: ProtocolDialog<R, O>) => Promise<T>): Promise<T> {
+  private async once<T>(dialog: FinTs3Dialog, use: (dialog: SignedDialog) => Promise<T>): Promise<T> {
+    const signed = new SignedDialog(dialog, this.session);
     try {
-      return await use(dialog);
+      return await use(signed);
     } finally {
-      await dialog.end();
+      await signed.end();
     }
   }
 }

package/src/session/session-state.ts

@@ -1,16 +1,19 @@
 import { Account } from '../core/account.js';
 import { hostOf, type FinTsConfig } from '../core/config.js';
+import { FinTsFeedback } from '../core/feedback.js';
 import { FormatError } from '../util/errors.js';
 import {
   isJsonObject,
   isString,
   readObject,
   readOptionalInt,
+  readOptionalObject,
   readOptionalList,
   readOptionalString,
   type JsonObject,
 } from '../util/json.js';
-import type { BankResponse, PinTanProtocol } from './protocol.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import type { LoginGuard, LoginGuardState } from './login-guard.js';
 
 /** Layout of the saved session; a state of another layout is ignored. */
 const stateFormat = 1;
@@ -18,40 +21,44 @@ const stateFormat = 1;
 /** The protocol version the state is for, named as the Dart package names it, so that both read each other's states. */
 const protocolVersion = 'v300';
 
-/** The session and the protocol's parameter data as one JSON string, which `restoreSession` reads. */
-export function saveSession<R extends BankResponse, O>(protocol: PinTanProtocol<R, O>, session: SessionState): string {
+/** The session, the parameter data and the guard's refusal as JSON, which `restoreSession` reads. */
+export function saveSession(parameters: ParameterStore, guard: LoginGuard, session: SessionState): string {
   return JSON.stringify({
     format: stateFormat,
     version: protocolVersion,
-    owner: ownerOf(protocol.config),
+    owner: ownerOf(parameters.config),
     session: session.toJson(),
-    protocol: protocol.saveState(),
+    // Under the key the Dart package reads as well.
+    protocol: parameters.saveState(),
+    loginGuard: guardStateToJson(guard.saveState()),
   });
 }
 
 /**
- * The session saved in `json`, and the protocol's parameter data restored from it.
+ * The session saved in `json`, and the parameter data and the guard's refused login restored from it.
  *
  * A missing or damaged state, or one saved for another user, bank, server or protocol version, gives a new session,
- * which only costs a new synchronization.
+ * which only costs a new synchronization. The refused login and the count of logins whose answer was lost belong to the
+ * user at the bank, so they come first: they hold for another server or protocol version as well, and where the rest is
+ * damaged; a state saved by fints-ts 0.1 or the Dart package 0.2.0 has neither. A damaged section of their own fails
+ * closed: it restores a refusal without return codes, since it may have held one.
  */
-export function restoreSession<R extends BankResponse, O>(
-  json: string | undefined,
-  protocol: PinTanProtocol<R, O>,
-): SessionState {
+export function restoreSession(json: string | undefined, parameters: ParameterStore, guard: LoginGuard): SessionState {
   if (json === undefined) return new SessionState();
   try {
     const saved: unknown = JSON.parse(json);
-    if (!isJsonObject(saved) || saved.format !== stateFormat || saved.version !== protocolVersion) {
-      return new SessionState();
-    }
-    const owner = readOptionalList(saved, 'owner', isString);
-    const expected = ownerOf(protocol.config);
-    if (owner?.length !== expected.length || owner.some((value, i) => value !== expected[i])) {
-      return new SessionState();
-    }
+    if (!isJsonObject(saved) || saved.format !== stateFormat) return new SessionState();
+    // Entries of another type differ like any other value, so that a damaged server entry keeps the refused login.
+    const owner: unknown = saved.owner ?? [];
+    if (!Array.isArray(owner)) return new SessionState();
+    const [server, ...user] = owner as unknown[];
+    const expected = userOf(parameters.config);
+    if (user.length !== expected.length || user.some((value, i) => value !== expected[i])) return new SessionState();
+    const guardState = savedGuardState(saved);
+    if (guardState !== undefined) guard.restoreState(guardState);
+    if (server !== hostOf(parameters.config.url) || saved.version !== protocolVersion) return new SessionState();
     const session = SessionState.fromJson(readObject(saved, 'session'));
-    protocol.restoreState(readObject(saved, 'protocol'));
+    parameters.restoreState(readObject(saved, 'protocol'), session.tanMedium);
     return session;
   } catch (error) {
     // Damaged JSON, base64 or parameter data, and values of the wrong type, only cost a new synchronization.
@@ -60,9 +67,14 @@ export function restoreSession<R extends BankResponse, O>(
   }
 }
 
-/** Whose data a state holds, so that the state of another user or bank is never used. */
+/** Whose data a state holds, so that the state of another user or bank is never used: the server, then `userOf`. */
 function ownerOf(config: FinTsConfig): string[] {
-  return [hostOf(config.url), config.bankCode, config.userId, config.customerId];
+  return [hostOf(config.url), ...userOf(config)];
+}
+
+/** The user at the bank, whom a refused login belongs to. */
+function userOf(config: FinTsConfig): string[] {
+  return [config.bankCode, config.userId, config.customerId];
 }
 
 /**
@@ -129,7 +141,9 @@ export class SessionState {
     const state = new SessionState();
     state.useTanMethod(readOptionalString(json, 'tanMethod'), readOptionalString(json, 'tanMedium'));
     if (allowedMethods !== undefined) state.rememberAllowedMethods(allowedMethods);
-    if (sepaAccounts !== undefined) state.cacheSepaAccounts(sepaAccounts, sepaUpdVersion);
+    // fints-ts 0.1 and the Dart package 0.2.0 saved an empty list as well, which completes nothing; without it, the
+    // list is asked for again.
+    if (sepaAccounts !== undefined && sepaAccounts.length > 0) state.cacheSepaAccounts(sepaAccounts, sepaUpdVersion);
     return state;
   }
 
@@ -168,3 +182,40 @@ function accountFromJson(json: JsonObject): Account {
     bankCode,
   });
 }
+
+function guardStateToJson(state: LoginGuardState): JsonObject {
+  return { refusal: state.refusal?.map(feedbackToJson) ?? null, unreadLogins: state.unreadLogins };
+}
+
+/** The guard's section of `saved`, `undefined` where there is none; a damaged one is a refusal without return codes. */
+function savedGuardState(saved: JsonObject): LoginGuardState | undefined {
+  try {
+    const json = readOptionalObject(saved, 'loginGuard');
+    return json === undefined ? undefined : guardStateFromJson(json);
+  } catch (error) {
+    if (error instanceof FormatError) return { refusal: [], unreadLogins: 0 };
+    throw error;
+  }
+}
+
+function guardStateFromJson(json: JsonObject): LoginGuardState {
+  return {
+    refusal: readOptionalList(json, 'refusal', isJsonObject)?.map(feedbackFromJson),
+    unreadLogins: readOptionalInt(json, 'unreadLogins') ?? 0,
+  };
+}
+
+function feedbackToJson(f: FinTsFeedback): JsonObject {
+  return { code: f.code, reference: f.reference ?? null, text: f.text, parameters: [...f.parameters] };
+}
+
+function feedbackFromJson(json: JsonObject): FinTsFeedback {
+  const code = readOptionalString(json, 'code');
+  if (code === undefined) throw new FormatError('Saved state: return code without code');
+  return new FinTsFeedback({
+    code,
+    reference: readOptionalString(json, 'reference'),
+    text: readOptionalString(json, 'text') ?? '',
+    parameters: readOptionalList(json, 'parameters', isString) ?? [],
+  });
+}

package/src/session/signed-dialog.ts

@@ -0,0 +1,222 @@
+import { requireLatin1 } from '../core/config.js';
+import {
+  bankErrorFor,
+  FinTsBankError,
+  FinTsLoginDataChangedError,
+  FinTsLoginRefusedError,
+  FinTsProtocolError,
+  FinTsTanCancelledError,
+} from '../core/errors.js';
+import {
+  allowedTanMethodsIn,
+  FeedbackCodes,
+  hasCode,
+  hasErrors,
+  userWarnings,
+  type FinTsFeedback,
+} from '../core/feedback.js';
+import type { TanMethod } from '../tan/tan-models.js';
+import { invalidArgument } from '../util/errors.js';
+import { trimBlanks, withAsciiForms } from '../util/text.js';
+import type { Approval, FinTs3Dialog } from '../v3/dialog.js';
+import { IncomingMessage3 } from '../v3/message.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import type { SegmentSpec } from '../v3/syntax.js';
+import { appApprovalWait } from './app-approval.js';
+import type { LoginGuard, RequestKind } from './login-guard.js';
+import type { SessionState } from './session-state.js';
+import type { UserPrompts } from './user-prompts.js';
+
+/** The parts of the session that every `SignedDialog` reports to. */
+export interface SessionParts {
+  readonly parameters: ParameterStore;
+  readonly state: SessionState;
+  readonly prompts: UserPrompts;
+  readonly guard: LoginGuard;
+}
+
+/**
+ * A dialog signed with the PIN, which settles each answer before it hands it out: it keeps the parameter data of the
+ * dialog's opening, passes the notices on, has the `LoginGuard` judge the answer and throws its errors, and completes
+ * the approval the bank asks for. The session sends every message signed with the PIN through it, so that the guard
+ * judges every answer, that to the dialog's end included.
+ */
+export class SignedDialog {
+  constructor(
+    private readonly dialog: FinTs3Dialog,
+    private readonly session: SessionParts,
+  ) {}
+
+  /** Whether the bank knows this dialog and it has not ended. */
+  get isActive(): boolean {
+    return this.dialog.isActive;
+  }
+
+  /** Logs in, which opens the dialog; with `synchronize` the bank also assigns a customer system ID. */
+  login(synchronize = false): Promise<IncomingMessage3> {
+    return this.settleLogin(() => this.dialog.start(synchronize));
+  }
+
+  /**
+   * Logs in, asking strong authentication for `order`, then sends `order` in a message of its own, as for listing the
+   * TAN media while no medium is chosen yet (`FinTs3Dialog.startWith`); returns both answers.
+   */
+  async loginWith(order: SegmentSpec): Promise<IncomingMessage3[]> {
+    const start = this.dialog.startWith(order);
+    const login = await this.settleLogin(start.login);
+    return [login, await this.settle(await start.order(), 'order')];
+  }
+
+  /**
+   * Sends `order` and completes the approval the bank asks for. `admitApproval` runs before the user is asked, and
+   * refuses the approval by throwing.
+   */
+  async send(order: SegmentSpec, admitApproval?: () => void): Promise<IncomingMessage3> {
+    return this.settle(await this.dialog.send(order), 'order', admitApproval);
+  }
+
+  /**
+   * Ends the dialog at the bank; does nothing if it is not active. Of the answer only a rejected PIN counts, which the
+   * guard judges: the dialog is over either way.
+   */
+  async end(): Promise<void> {
+    const response = await this.dialog.end();
+    if (response !== undefined && hasErrors(response.feedback)) {
+      this.session.guard.judge(bankErrorFor(response.feedback), 'order', this.dialog.method);
+    }
+  }
+
+  /**
+   * Receives `response`, the answer to a request of `kind`: keeps its parameter data where it answers the `opening` of
+   * the dialog, the login or its approval, even alongside errors, since the remedy for a refused login may need them;
+   * passes its notices on; and has the guard judge it, then throws its errors, as the refusal of the login where they
+   * amount to one.
+   */
+  private receive(response: IncomingMessage3, kind: RequestKind, opening: boolean): void {
+    if (opening) this.session.parameters.keep(response);
+    this.readNotices(response);
+    const error = hasErrors(response.feedback) ? bankErrorFor(response.feedback, kind === 'approval') : undefined;
+    const refusal = this.session.guard.judge(error, kind, this.dialog.method);
+    // Every further message of a refused login's dialog would carry the refused PIN.
+    if (refusal !== undefined) this.dialog.discard();
+    if (error !== undefined) throw refusal ?? error;
+  }
+
+  /**
+   * Sends the login `send` and settles its answer. New login data next to an error in the answer to its approval are
+   * retired all the same (`retireLoginData`), although the guard counts that error as no refusal; next to an error in
+   * the answer to the login they are its refusal already (`loginRefusalFor`).
+   */
+  private async settleLogin(send: () => Promise<IncomingMessage3>): Promise<IncomingMessage3> {
+    try {
+      return await this.settle(await send(), 'login');
+    } catch (error) {
+      if (
+        !(error instanceof FinTsBankError) ||
+        error instanceof FinTsLoginRefusedError ||
+        !hasCode(error.feedback, FeedbackCodes.newLoginData)
+      ) {
+        throw error;
+      }
+      return this.retireLoginData(error.feedback, 'approval');
+    }
+  }
+
+  /**
+   * Where `response` answers a login, a request of `kind` other than `order`, or its approval with new login data,
+   * retires them (`retireLoginData`). It runs before any approval, which would cost the user a TAN for a session that
+   * ends anyway.
+   */
+  private async retireOldLoginData(response: IncomingMessage3, kind: RequestKind): Promise<void> {
+    if (kind === 'order' || !hasCode(response.feedback, FeedbackCodes.newLoginData)) return;
+    await this.retireLoginData(response.feedback, kind);
+  }
+
+  /**
+   * Ends the dialog, whose answer to a request of `kind` brought new login data with `feedback`, stops the client from
+   * logging in with the old ones, and fails the call with `FinTsLoginDataChangedError` (Rückmeldungscodes C.6).
+   */
+  private async retireLoginData(feedback: readonly FinTsFeedback[], kind: RequestKind): Promise<never> {
+    await this.end();
+    const error = new FinTsLoginDataChangedError(feedback);
+    throw this.session.guard.judge(error, kind, this.dialog.method) ?? error;
+  }
+
+  /**
+   * Receives `response`, the answer to a request of `kind`, then completes the approval it asks for, once
+   * `admitApproval` has let it; returns it joined with the response that completes the approval.
+   *
+   * Throws `FinTsProtocolError` if that response asks for an approval once more: the bank has not executed the message
+   * then either, and read as done it would report an empty result.
+   */
+  private async settle(
+    response: IncomingMessage3,
+    kind: RequestKind,
+    admitApproval?: () => void,
+  ): Promise<IncomingMessage3> {
+    const opening = kind !== 'order';
+    this.receive(response, kind, opening);
+    await this.retireOldLoginData(response, kind);
+    const approval = this.dialog.approvalAskedIn(response);
+    if (approval === undefined) return response;
+    admitApproval?.();
+    const approved = approval.challenge.isDecoupled
+      ? await this.awaitAppApproval(approval, opening)
+      : await this.enterTan(approval, opening);
+    await this.retireOldLoginData(approved, kind);
+    if (this.dialog.approvalAskedIn(approved) !== undefined) {
+      throw new FinTsProtocolError('The bank asks for another approval in answer to the approval');
+    }
+    return IncomingMessage3.combine(response, approved);
+  }
+
+  /** Passes on the notices in `response`: the TAN methods the user may use (3920), the bank's messages and warnings. */
+  private readNotices(response: IncomingMessage3): void {
+    const allowed = allowedTanMethodsIn(response.feedback);
+    if (allowed.length > 0) this.session.state.rememberAllowedMethods(allowed);
+    for (const message of response.bankMessages) this.session.prompts.showBankMessage(message);
+    for (const warning of userWarnings(response.feedback)) this.session.prompts.showWarning(warning);
+  }
+
+  /** Asks the user for the TAN `approval` takes and sends it; `opening` tells whether it approves the login. */
+  private async enterTan(approval: Approval<IncomingMessage3>, opening: boolean): Promise<IncomingMessage3> {
+    const answer = await this.session.prompts.askTan(approval.challenge);
+    if (answer.kind === 'approved') {
+      throw invalidArgument('Answered a TAN challenge with an approval in the banking app', 'tanCallback');
+    }
+    // Not NFKC, which also changes characters FinTS 3.0 sends as they are, such as `²`, in a TAN the bank compares.
+    const tan = answer.kind === 'tan' ? trimBlanks(withAsciiForms(answer.tan)) : '';
+    if (tan === '') throw new FinTsTanCancelledError();
+    const response = await approval.submitTan(requireTanOf(approval.challenge.method, tan));
+    this.receive(response, 'approval', opening);
+    return response;
+  }
+
+  /** Waits for the user to approve in the banking app; `opening` tells whether the approval is that of the login. */
+  private awaitAppApproval(approval: Approval<IncomingMessage3>, opening: boolean): Promise<IncomingMessage3> {
+    const prompts = this.session.prompts;
+    return appApprovalWait(approval, {
+      ask: (challenge) => prompts.askTan(challenge),
+      pause: (delayMs, interrupt) => prompts.pause(delayMs, interrupt),
+      receive: (response) => {
+        this.receive(response, 'approval', opening);
+      },
+    }).run();
+  }
+}
+
+/**
+ * Throws `TypeError` for a TAN that `method` rules out, which the bank would count as a failed attempt: one longer than
+ * `TanMethod.maxTanLength`, or with other characters than digits for a `TanMethod.numericTan` method; and for one that
+ * FinTS 3.0 cannot send. The message leaves out the TAN.
+ */
+function requireTanOf(method: TanMethod, tan: string): string {
+  const max = method.maxTanLength;
+  if (max !== undefined && max > 0 && tan.length > max) {
+    throw invalidArgument(`The TAN method ${method.name} takes TANs of at most ${max} characters`, 'tan');
+  }
+  if (method.numericTan && !/^[0-9]+$/.test(tan)) {
+    throw invalidArgument(`The TAN method ${method.name} takes digits only`, 'tan');
+  }
+  return requireLatin1(tan, 'tan');
+}