@coderoftime/fints 0.1.0 → 0.2.0

package/src/session/app-approval.ts

@@ -1,10 +1,15 @@
 import { FinTsDecoupledTimeoutError, FinTsTanCancelledError } from '../core/errors.js';
-import { FeedbackCodes, hasCode } from '../core/feedback.js';
+import { FeedbackCodes, hasCode, type FinTsFeedback } from '../core/feedback.js';
 import { nextAttempt, withResolved, type TanAnswer, type TanChallenge } from '../tan/challenge.js';
 import type { TanMethod } from '../tan/tan-models.js';
 import { Deferred } from '../util/async.js';
 import { invalidArgument } from '../util/errors.js';
-import type { Approval, BankResponse } from './protocol.js';
+import type { Approval } from '../v3/dialog.js';
+
+/** What a wait reads of the bank's answer to a status request: its return codes. */
+interface StatusAnswer {
+  readonly feedback: readonly FinTsFeedback[];
+}
 
 /** How long to wait for an app approval when the bank does not say. */
 const defaultMaxStatusPolls = 60;
@@ -17,10 +22,10 @@ const maxPollDelayMs = 60_000;
 const maxApprovalWaitMs = 10 * 60_000;
 
 /** Shows a challenge and returns the user's answer. */
-export type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
+type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
 
 /** Waits for `delayMs`, or until `interrupt` settles. */
-export type Pause = (delayMs: number, interrupt?: Promise<unknown>) => Promise<void>;
+type Pause = (delayMs: number, interrupt?: Promise<unknown>) => Promise<void>;
 
 /** What an `AppApprovalWait` needs: `ask` shows a challenge, `pause` waits, `receive` takes in each status response. */
 export interface AppApprovalHooks<R> {
@@ -44,7 +49,7 @@ export interface AppApprovalHooks<R> {
  * handles one `Approval`; `run` may be called once. A failure of `ask` or `pause`, such as a closed client, ends the
  * wait.
  */
-export function appApprovalWait<R extends BankResponse>(
+export function appApprovalWait<R extends StatusAnswer>(
   approval: Approval<R>,
   hooks: AppApprovalHooks<R>,
 ): AppApprovalWait<R> {
@@ -53,7 +58,7 @@ export function appApprovalWait<R extends BankResponse>(
   return automatic ? new PollingWhileShown(approval, hooks) : new PollingAfterReports(approval, hooks);
 }
 
-export abstract class AppApprovalWait<R extends BankResponse> {
+export abstract class AppApprovalWait<R extends StatusAnswer> {
   private requests = 0;
 
   /** The time the client waited by itself, which counts towards the longest wait. */
@@ -122,19 +127,20 @@ export abstract class AppApprovalWait<R extends BankResponse> {
 }
 
 /**
- * The client polls by itself while the callback shows the instructions, and settles `TanChallenge.resolved` when it is
- * done.
+ * The client polls by itself while the callback shows the instructions, and settles the `TanChallenge.resolved` of a
+ * prompt when it needs no more answer to it.
  *
  * `run` shows the prompt, waits the bank's first delay, then asks the bank until it confirms, waiting the interval in
- * between. The callback's answer only records what the user did:
+ * between. A status answer with new instructions replaces the prompt with one that shows them. The callback's answer
+ * only records what the user did, and counts while its prompt is shown:
  * - `stopped` settles on a cancel, a TAN or a failing callback; the loop stops before its next request.
  * - `report` settles on a report of the approval, which cuts the current wait short once, though not below a second.
  *   The report closed the prompt, so it is shown anew while the bank has not confirmed yet.
  * - A user who cannot report the approval has every answer but `TanAnswer.cancelled` ignored.
  */
-class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
-  /** Settles when the client needs no more answer, which `TanChallenge.resolved` tells the callback. */
-  private readonly finished = new Deferred<void>();
+class PollingWhileShown<R extends StatusAnswer> extends AppApprovalWait<R> {
+  /** Settles when the prompt shown now needs no more answer, which its `TanChallenge.resolved` tells the callback. */
+  private shown: Deferred<void> | undefined;
 
   /** Settles when the user cancels or the callback fails; `stopReason` holds the error that ends the wait. */
   private readonly stopped = new Deferred<void>();
@@ -154,38 +160,45 @@ class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
         const response = await this.requestStatus();
         if (!isPending(response)) return response;
         this.throwIfStopped();
-        // The user reported the approval, which closed the prompt, but the bank has not confirmed it yet.
-        if (this.userConfirms && this.report === undefined)
-          this.show((challenge = this.nextPrompt(challenge, response)));
+        // A report closed the prompt, but the bank has not confirmed the approval yet; or the bank's instructions changed.
+        const reported = this.userConfirms && this.report === undefined;
+        const next = this.nextPrompt(challenge, response);
+        if (reported || next.message !== challenge.message) this.show((challenge = next));
         await this.sleep(this.pollIntervalMs, minPollIntervalMs);
       }
     } finally {
-      this.finished.resolve();
+      this.shown?.resolve();
     }
   }
 
-  /** Shows `challenge` without waiting for the answer. */
+  /** Shows `challenge` in place of the prompt before, without waiting for the answer. */
   private show(challenge: TanChallenge): void {
+    this.shown?.resolve();
+    const shown = (this.shown = new Deferred<void>());
     const report = (this.report = this.userConfirms ? new Deferred<void>() : undefined);
-    void this.hooks.ask(withResolved(challenge, this.finished.promise)).then(
-      (answer) => {
-        switch (answer.kind) {
-          case 'cancelled':
-            this.stop(new FinTsTanCancelledError());
-            break;
-          case 'approved':
-            report?.resolve();
-            break;
-          case 'tan':
-            if (report !== undefined) this.stop(tanForApproval());
-            break;
-          // The user cannot report the approval: the client waits for the bank.
-        }
-      },
-      (error: unknown) => {
-        this.stop(error);
-      },
-    );
+    // Asked a microtask later: the app closes the prompt before on its `resolved` first, and then opens this one.
+    void Promise.resolve()
+      .then(() => this.hooks.ask(withResolved(challenge, shown.promise)))
+      .then(
+        (answer) => {
+          if (shown.isCompleted) return;
+          switch (answer.kind) {
+            case 'cancelled':
+              this.stop(new FinTsTanCancelledError());
+              break;
+            case 'approved':
+              report?.resolve();
+              break;
+            case 'tan':
+              if (report !== undefined) this.stop(tanForApproval());
+              break;
+            // The user cannot report the approval: the client waits for the bank.
+          }
+        },
+        (error: unknown) => {
+          if (!shown.isCompleted) this.stop(error);
+        },
+      );
   }
 
   private stop(error: unknown): void {
@@ -219,7 +232,7 @@ class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
  * The client asks the bank after each report of the user; while the approval is pending, the user is asked again with
  * the bank's latest instructions.
  */
-class PollingAfterReports<R extends BankResponse> extends AppApprovalWait<R> {
+class PollingAfterReports<R extends StatusAnswer> extends AppApprovalWait<R> {
   async run(): Promise<R> {
     let challenge = this.approval.challenge;
     await this.confirm(challenge);
@@ -248,7 +261,7 @@ class PollingAfterReports<R extends BankResponse> extends AppApprovalWait<R> {
 }
 
 /** Whether `response` tells that the approval is still pending (return code 3956). */
-function isPending(response: BankResponse): boolean {
+function isPending(response: StatusAnswer): boolean {
   return hasCode(response.feedback, FeedbackCodes.decoupledStillPending);
 }
 

package/src/session/dialog-runner.ts

@@ -1,14 +1,19 @@
 import { FinTsBankError, FinTsProtocolError, parseBankData } from '../core/errors.js';
 import { continuations, FeedbackCodes, hasCode } from '../core/feedback.js';
-import type { BankResponse, ProtocolDialog, Query } from './protocol.js';
-import type { ResponseHandler } from './response-handler.js';
+import type { IncomingMessage3 } from '../v3/message.js';
+import type { Query } from '../v3/queries.js';
+import type { SegmentSpec } from '../v3/syntax.js';
 import type { SessionSetup } from './session-setup.js';
-import type { UserPrompts } from './user-prompts.js';
+import type { SignedDialog } from './signed-dialog.js';
 
 /** Most pages the client fetches for one query, far more than banks send. */
 const maxPages = 1000;
 
-/** Most data one query may hold, summed over its pages: the transport bounds a single response only. */
+/**
+ * Most data one query may hold, summed over its pages as `IncomingMessage3.size` measures it: the transport and the
+ * parser bound a single response only. The statements and transactions read from them have a budget of their own
+ * (`RecordBudget`).
+ */
 const maxQueryMebibytes = 128;
 
 /**
@@ -18,17 +23,13 @@ const maxQueryMebibytes = 128;
  * client does not repeat the call by itself, since the bank's answer cannot tell a dialog that had ended before from an
  * order it refuses along with ending the dialog, and a new login may cost the user another approval.
  */
-export class DialogRunner<R extends BankResponse, O> {
-  private dialog: ProtocolDialog<R, O> | undefined;
+export class DialogRunner {
+  private dialog: SignedDialog | undefined;
 
-  constructor(
-    private readonly setup: SessionSetup<R, O>,
-    private readonly responses: ResponseHandler<R>,
-    private readonly prompts: UserPrompts,
-  ) {}
+  constructor(private readonly setup: SessionSetup) {}
 
   /** The open dialog, or a new one once the setup is complete and the user has passed strong authentication. */
-  async open(): Promise<ProtocolDialog<R, O>> {
+  async open(): Promise<SignedDialog> {
     const current = this.dialog;
     if (current?.isActive === true) return current;
     this.dialog = undefined;
@@ -37,10 +38,10 @@ export class DialogRunner<R extends BankResponse, O> {
     return dialog;
   }
 
-  private async login(): Promise<ProtocolDialog<R, O>> {
+  private async login(): Promise<SignedDialog> {
     const dialog = await this.setup.newDialog();
     try {
-      await this.responses.startDialog(dialog, () => dialog.start());
+      await dialog.login();
       return dialog;
     } catch (error) {
       // After a refused login the dialog is discarded already, and ending it sends nothing. After any other failure,
@@ -62,18 +63,17 @@ export class DialogRunner<R extends BankResponse, O> {
    *
    * The query is built once the dialog is open, since building it takes the parameter data.
    */
-  async query<T>(build: () => Query<R, O, T>): Promise<T> {
+  async query<T>(build: () => Query<T>): Promise<T> {
     const dialog = await this.open();
     const query = build();
     const pages = await this.fetchPages(dialog, query.order);
     return parseBankData(() => query.read(pages));
   }
 
-  /** Sends `order` in `dialog` and completes its approval. */
-  private async run(dialog: ProtocolDialog<R, O>, order: O): Promise<R> {
-    this.prompts.checkOpen();
+  /** Sends `order` in `dialog` and completes its approval, which only the `firstPage` of a query may ask for. */
+  private async run(dialog: SignedDialog, order: SegmentSpec, firstPage: boolean): Promise<IncomingMessage3> {
     try {
-      return await this.responses.complete(dialog, await dialog.send(order));
+      return firstPage ? await dialog.send(order) : await dialog.sendFurtherPage(order);
     } catch (error) {
       // The bank rejected the order and the dialog stays usable, or the bank ended the dialog or rejected the PIN and
       // the dialog is discarded already. A cancelled or failed approval, or a broken connection, leaves the dialog in an
@@ -84,15 +84,23 @@ export class DialogRunner<R extends BankResponse, O> {
   }
 
   /** Sends the order built by `order` until the bank has delivered all pages (Formals B.6.3, "Aufsetzpunkt"). */
-  private async fetchPages(dialog: ProtocolDialog<R, O>, order: (continuation: string | undefined) => O): Promise<R[]> {
-    const pages: R[] = [];
+  private async fetchPages(
+    dialog: SignedDialog,
+    order: (continuation: string | undefined) => SegmentSpec,
+  ): Promise<IncomingMessage3[]> {
+    const pages: IncomingMessage3[] = [];
     const seen = new Set<string>();
     let size = 0;
     let continuation: string | undefined;
     for (;;) {
-      const page = await this.run(dialog, order(continuation));
+      const page = await this.run(dialog, order(continuation), continuation === undefined);
       pages.push(page);
       size += page.size;
+      if (size > maxQueryMebibytes * 1024 * 1024) {
+        throw new FinTsProtocolError(
+          `The bank sends more than ${maxQueryMebibytes} MiB for one query; ask for a shorter period`,
+        );
+      }
       const positions = [...continuations(page.feedback)];
       // A message carries one order, so the bank names one position at most.
       if (positions.length > 1) throw new FinTsProtocolError('The bank names several positions to continue at');
@@ -104,16 +112,11 @@ export class DialogRunner<R extends BankResponse, O> {
         }
         return pages;
       }
-      // A repeated position or endless pages would keep the client busy forever, and unbounded pages exhaust memory.
+      // A repeated position or endless pages would keep the client busy forever.
       if (seen.has(continuation) || pages.length === maxPages) {
         throw new FinTsProtocolError('The bank does not stop sending pages');
       }
       seen.add(continuation);
-      if (size > maxQueryMebibytes * 1024 * 1024) {
-        throw new FinTsProtocolError(
-          `The bank sends more than ${maxQueryMebibytes} MiB for one query; ask for a shorter period`,
-        );
-      }
     }
   }
 }

package/src/session/login-guard.ts

@@ -1,16 +1,23 @@
-import { FinTsBankError, FinTsLoginDataChangedError, FinTsPinError, FinTsTanError } from '../core/errors.js';
-import { allowedTanMethodsIn, FeedbackCodes, hasCode } from '../core/feedback.js';
+import {
+  clientClosedError,
+  FinTsLoginDataChangedError,
+  FinTsLoginRefusedError,
+  FinTsPinError,
+  loginRefusalFor,
+  type FinTsBankError,
+} from '../core/errors.js';
+import { allowedTanMethodsIn, FeedbackCodes, hasCode, type FinTsFeedback } from '../core/feedback.js';
 import type { TanMethod } from '../tan/tan-models.js';
+import type { PinGuard } from '../v3/protocol.js';
 
 /**
  * The kind of request a bank response answers, which decides what its errors mean for the login (`LoginGuard.judge`)
  * and whether they can reject a TAN:
- * - `login`: the login that opens a dialog;
- * - `loginWithOrder`: a login that carries an order in the same message, whose errors may concern the order alone;
+ * - `login`: the login that opens a dialog, which carries no order;
  * - `order`: an order in a dialog the bank has opened;
  * - `approval`: a message that completes an approval, the TAN or the question whether the user approved in the app.
  */
-export type RequestKind = 'login' | 'loginWithOrder' | 'order' | 'approval';
+export type RequestKind = 'login' | 'order' | 'approval';
 
 /**
  * A reason for a refused login that the session can take care of by itself, after which it logs in once more: the user
@@ -18,118 +25,197 @@ export type RequestKind = 'login' | 'loginWithOrder' | 'order' | 'approval';
  */
 export type RefusalReason = 'tanMethodNotAllowed' | 'systemIdRejected';
 
+/** What the saved state keeps of the guard: the return codes of the bank's refusal, and `unreadLogins`. */
+export interface LoginGuardState {
+  readonly refusal: readonly FinTsFeedback[] | undefined;
+  readonly unreadLogins: number;
+}
+
 /**
- * Keeps a retrying app from locking the user's access: once the bank has refused a login, the client does not send the
- * PIN again.
- *
- * Banks lock the access after a few failed attempts, and a return code does not always tell whether the PIN was the
- * reason. So `judge` counts as a refused login:
- * - a rejected PIN, wherever the bank reports it;
- * - any other error in the answer to a login, unless the login carries an order and the bank keeps the dialog open:
- *   then the error concerns the order.
- *
- * Errors in the answer to an order or an approval are no refusal, such as a wrong TAN at login: the bank checks the PIN
- * before it asks for the approval. New login data (return code 3072) end the old ones for good (`refuse`).
+ * Logins in a row whose answer the client could not read, after which it sends the PIN no more: one may be a glitch of
+ * the connection, but with two the client would not learn of a wrong PIN before the bank locks the access.
+ */
+const maxUnreadLogins = 2;
+
+/**
+ * Holds the PIN and hands it out only while no login is refused (`pin`), so that a retrying app cannot lock the user's
+ * access. `FinTsLoginRefusedError` tells which logins count as refused; `judge` decides it for each answer.
  *
- * The guard fails closed: a refusal counts from the moment `judge` sees it, and only `pardon` lifts it, once the
- * session has taken care of a `RefusalReason` the refusal names (`remediableReasons`). The protocol calls `check`
- * before every message it signs with the PIN.
+ * A refusal counts at once and fails closed: only `remedied` lifts it, within the call that met it (`runCall`), once
+ * the session has taken care of a reason it names, each reason once per call, so that a call sends at most three
+ * logins the bank refuses. A refusal that outlasts the call is final, and the guard forgets the PIN; only a PIN the
+ * user enters anew lifts it (`replacePin`), unless it brings new login data.
  */
-export class LoginGuard {
-  private refusal: FinTsBankError | undefined;
+export class LoginGuard implements PinGuard {
+  // ECMAScript private, so that neither `util.inspect` nor `JSON.stringify` of the client reaches it.
+  #pin: string | undefined;
+
+  private refusalValue: FinTsLoginRefusedError | undefined;
+
+  /** The TAN method of the login `refusalValue` refused, which a restored refusal does not tell. */
+  private refusedMethod: TanMethod | undefined;
 
-  /** The TAN method of the refused login; `undefined` without a refusal, and for new login data. */
-  private refusedMethodValue: TanMethod | undefined;
+  /** Logins sent since the bank last took the PIN whose answer the client has not read. */
+  private unreadLogins = 0;
 
-  /** Throws the bank's refusal of an earlier login, so that the PIN is not sent again. */
+  /** The refusal of `maxUnreadLogins` unread logins, kept so that `check` throws the same error each time. */
+  private unreadLoginsRefusal: FinTsLoginRefusedError | undefined;
+
+  /** The reasons `remedied` has lifted a refusal for in the running call. */
+  private readonly pardonedReasons = new Set<RefusalReason>();
+
+  constructor(pin: string) {
+    this.#pin = pin;
+  }
+
+  /** The PIN to sign a message with; throws the refusal instead (`check`), and `FinTsStateError` once closed. */
+  get pin(): string {
+    this.check();
+    if (this.#pin === undefined) throw clientClosedError();
+    return this.#pin;
+  }
+
+  /** Throws the refusal, if there is one. */
   check(): void {
-    if (this.refusal !== undefined) throw this.refusal;
+    const refusal = this.refusal;
+    if (refusal !== undefined) throw refusal;
   }
 
-  /** Whether the guard holds a refusal. */
-  get hasRefusal(): boolean {
-    return this.refusal !== undefined;
+  /** The bank's refusal, else that of `maxUnreadLogins` unread logins; `undefined` while there is none. */
+  get refusal(): FinTsLoginRefusedError | undefined {
+    if (this.refusalValue !== undefined || this.unreadLogins < maxUnreadLogins) return this.refusalValue;
+    this.unreadLoginsRefusal ??= new FinTsLoginRefusedError(
+      [],
+      `The answers to the last ${maxUnreadLogins} logins were lost or unreadable, and the bank may have counted them ` +
+        'as failed attempts',
+    );
+    return this.unreadLoginsRefusal;
   }
 
-  /** The TAN method the refused login was signed with; `undefined` where the guard holds no refusal of a login. */
-  get refusedMethod(): TanMethod | undefined {
-    return this.refusedMethodValue;
+  /** Counts a login signed with the PIN as unread until `judge` reads its answer. */
+  loginSent(): void {
+    this.unreadLogins++;
   }
 
   /**
-   * Whether `error`, raised for the answer to a request of `kind` in a dialog signed with `method`, refuses the login;
-   * records it if it does.
-   *
-   * `dialogOpen` tells whether the bank keeps the dialog open after its answer.
+   * Judges `error`, if the answer to a request of `kind` in a dialog signed with `method` has one: returns the refusal
+   * of the login it amounts to, and records it unless the guard holds one already. Any error refuses a login; after the
+   * login only one that refuses it itself, a rejected PIN or new login data, since the bank checked the PIN before.
    */
-  judge(error: FinTsBankError, kind: RequestKind, dialogOpen: boolean, method: TanMethod): boolean {
-    const refused = error instanceof FinTsPinError || kind === 'login' || (kind === 'loginWithOrder' && !dialogOpen);
-    if (refused && this.refusal === undefined) {
-      this.refusal = error;
-      this.refusedMethodValue = method;
+  judge(error: FinTsBankError | undefined, kind: RequestKind, method: TanMethod): FinTsLoginRefusedError | undefined {
+    const refused = error instanceof FinTsLoginRefusedError || (error !== undefined && kind === 'login');
+    if (kind === 'login') this.unreadLogins = refused ? Math.max(0, this.unreadLogins - 1) : 0;
+    if (!refused) return undefined;
+    const refusal = loginRefusalFor(error.feedback);
+    if (this.refusalValue === undefined) {
+      this.refusalValue = refusal;
+      this.refusedMethod = method;
     }
-    return refused;
+    return refusal;
   }
 
-  /** Records `error` as the reason the client logs in no more, unless it holds a refusal already. */
-  refuse(error: FinTsBankError): void {
-    this.refusal ??= error;
+  /** Runs `call`, one call of the client; a refusal that outlasts it is final, and the next call remedies anew. */
+  async runCall<T>(call: () => Promise<T>): Promise<T> {
+    try {
+      return await call();
+    } finally {
+      this.pardonedReasons.clear();
+      this.forgetPinIfRefused();
+    }
   }
 
   /**
-   * Runs `lookup`, which only completes data, such as the SEPA account list; `undefined` where the bank rejects it, so
-   * that the caller carries on without it.
-   *
-   * A refused login is thrown, and so is a wrong TAN, which the user must hear of. An aborted dialog counts as a
-   * rejection: banks end the dialog along with many.
+   * Runs `attempt`, which may log in, and runs it once more each time `remedy` takes care of a reason the refusal it
+   * failed with names; `remedy` gets the reason and the TAN method of the refused login, and returns whether it could.
    */
-  async tryLookUp<T>(lookup: () => Promise<T>): Promise<T | undefined> {
-    try {
-      return await lookup();
-    } catch (error) {
-      if (!(error instanceof FinTsBankError) || this.isRefusal(error) || error instanceof FinTsTanError) throw error;
-      return undefined;
+  async remedied<T>(
+    attempt: () => Promise<T>,
+    remedy: (reason: RefusalReason, rejected: TanMethod) => Promise<boolean>,
+  ): Promise<T> {
+    // A refusal of an earlier call stops the attempt before it sends the PIN; there is nothing to remedy.
+    if (this.refusal !== undefined) return attempt();
+    for (;;) {
+      try {
+        return await attempt();
+      } catch (error) {
+        const refusal = this.refusalValue;
+        const rejected = this.refusedMethod;
+        // Only the bank's refusal the guard holds names reasons; any other error, a second refusal too, fails the call.
+        if (refusal === undefined || error !== refusal || rejected === undefined) throw error;
+        const reason = remediableReasons(refusal, rejected).find((r) => !this.pardonedReasons.has(r));
+        if (reason === undefined || !(await remedy(reason, rejected))) throw error;
+        this.pardonedReasons.add(reason);
+        // A closed client keeps the refusal.
+        if (this.#pin !== undefined) this.liftRefusal();
+      }
     }
   }
 
   /**
-   * The reasons the session can take care of in `error`: 3920 without the TAN method of the refused login, 9075 after
-   * the one-step method, and 9391. Empty if `error` is not the refusal the guard holds, rejects the PIN, or brings new
-   * login data.
-   *
-   * Only the return codes of the refusal itself count: TAN methods listed earlier say nothing about this login.
+   * Signs with `pin` from now on, a PIN the user has entered anew and the protocol can send, and lifts the refusal.
+   * Throws the refusal instead where it brings new login data, which end the old ones for good.
    */
-  remediableReasons(error: FinTsBankError): RefusalReason[] {
-    const method = this.refusedMethodValue;
-    if (
-      !this.isRefusal(error) ||
-      method === undefined ||
-      error instanceof FinTsPinError ||
-      error instanceof FinTsLoginDataChangedError
-    ) {
-      return [];
-    }
-    const feedback = error.feedback;
-    const allowed = allowedTanMethodsIn(feedback);
-    const reasons: RefusalReason[] = [];
-    if (
-      (allowed.length > 0 && !allowed.includes(method.securityFunction)) ||
-      (method.isOneStep && hasCode(feedback, FeedbackCodes.scaRequired))
-    ) {
-      reasons.push('tanMethodNotAllowed');
-    }
-    if (hasCode(feedback, FeedbackCodes.newSystemIdRequired)) reasons.push('systemIdRejected');
-    return reasons;
+  replacePin(pin: string): void {
+    if (this.refusalValue instanceof FinTsLoginDataChangedError) throw this.refusalValue;
+    this.#pin = pin;
+    this.liftRefusal();
+    this.unreadLogins = 0;
+    this.unreadLoginsRefusal = undefined;
   }
 
-  /** Lifts `refusal` once the session has taken care of its reason, so that the next login may send the PIN. */
-  pardon(refusal: FinTsBankError): void {
-    if (!this.isRefusal(refusal)) return;
-    this.refusal = undefined;
-    this.refusedMethodValue = undefined;
+  /** Forgets the PIN; the client calls it once it is closed. */
+  close(): void {
+    this.#pin = undefined;
   }
 
-  private isRefusal(error: unknown): boolean {
-    return error === this.refusal;
+  saveState(): LoginGuardState {
+    return { refusal: this.refusalValue?.feedback, unreadLogins: this.unreadLogins };
   }
+
+  /** Restores what `saveState` returned; a restored refusal is final. */
+  restoreState(saved: LoginGuardState): void {
+    if (saved.refusal !== undefined) this.refusalValue = loginRefusalFor(saved.refusal);
+    this.unreadLogins = Math.max(0, saved.unreadLogins);
+    this.forgetPinIfRefused();
+  }
+
+  private liftRefusal(): void {
+    this.refusalValue = undefined;
+    this.refusedMethod = undefined;
+  }
+
+  private forgetPinIfRefused(): void {
+    if (this.refusal !== undefined) this.#pin = undefined;
+  }
+}
+
+/**
+ * The reasons `refusal`, of a login signed with `method`, names that the session can take care of: a TAN method the
+ * refusal names as not allowed (`refusesMethod`), and 9391. None for a rejected PIN or new login data.
+ */
+function remediableReasons(refusal: FinTsLoginRefusedError, method: TanMethod): RefusalReason[] {
+  if (refusal instanceof FinTsPinError || refusal instanceof FinTsLoginDataChangedError) return [];
+  const reasons: RefusalReason[] = [];
+  if (refusesMethod(refusal.feedback, method)) reasons.push('tanMethodNotAllowed');
+  if (hasCode(refusal.feedback, FeedbackCodes.newSystemIdRequired)) reasons.push('systemIdRejected');
+  return reasons;
+}
+
+/** Error codes that only say that the message failed, not why: 9050 (the message contains errors) and 9800. */
+const unspecificErrors = new Set(['9050', FeedbackCodes.dialogAborted]);
+
+/**
+ * Whether `feedback`, which refuses a login signed with `method`, names the method as the reason: a 3920 that lists the
+ * methods the user may use without it, or 9075 after the one-step method.
+ *
+ * Only the return codes of the refusal itself count: TAN methods listed earlier say nothing about this login. Banks
+ * list two-step methods only, so a 3920 always leaves the one-step method out, also where the login succeeds. After
+ * the one-step method a 3920 counts only where the bank names no other error than an unspecific one: any other, such
+ * as "Anmeldung fehlgeschlagen", may be about the PIN.
+ */
+function refusesMethod(feedback: readonly FinTsFeedback[], method: TanMethod): boolean {
+  if (method.isOneStep && hasCode(feedback, FeedbackCodes.scaRequired)) return true;
+  const allowed = allowedTanMethodsIn(feedback);
+  if (allowed.length === 0 || allowed.includes(method.securityFunction)) return false;
+  return !method.isOneStep || feedback.every((f) => !f.isError || unspecificErrors.has(f.code));
 }