@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/session/app-approval.ts

@@ -0,0 +1,278 @@
+import { FinTsDecoupledTimeoutError, FinTsTanCancelledError } from '../core/errors.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 } 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;
+const defaultFirstPollDelayMs = 2_000;
+const defaultPollIntervalMs = 2_000;
+
+/** Bounds for the bank's polling parameters, against faulty parameter data. */
+const minPollIntervalMs = 1_000;
+const maxPollDelayMs = 60_000;
+const maxApprovalWaitMs = 10 * 60_000;
+
+/** Shows a challenge and returns the user's answer. */
+type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
+
+/** Waits for `delayMs`, or until `interrupt` settles. */
+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> {
+  readonly ask: AskUser;
+  readonly pause: Pause;
+  /** Takes in each status response; throws if it reports errors. */
+  readonly receive: (response: R) => void;
+}
+
+/**
+ * Waits for the user to approve a message in the banking app, and for the bank to confirm it (PIN/TAN B.4.2.2).
+ *
+ * The bank's parameters decide who triggers the status requests:
+ * - The client polls by itself while the callback shows the instructions (`PollingWhileShown`) where the bank allows
+ *   automatic status requests and announces no push message (3957), and also where the user cannot report the
+ *   approval: then polling is the one way left to complete it, whatever the other parameters say (step 2a).
+ * - Otherwise the client asks after each report of the user (`PollingAfterReports`), which stands in for the push
+ *   message the client cannot receive.
+ *
+ * The bank's limit on status requests holds either way, and two requests are at least a second apart. One instance
+ * 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 StatusAnswer>(
+  approval: Approval<R>,
+  hooks: AppApprovalHooks<R>,
+): AppApprovalWait<R> {
+  const method = approval.challenge.method;
+  const automatic = !method.decoupledManualConfirmation || (method.decoupledAutomaticPolling && !approval.waitForPush);
+  return automatic ? new PollingWhileShown(approval, hooks) : new PollingAfterReports(approval, hooks);
+}
+
+export abstract class AppApprovalWait<R extends StatusAnswer> {
+  private requests = 0;
+
+  /** The time the client waited by itself, which counts towards the longest wait. */
+  protected waitedMs = 0;
+
+  constructor(
+    protected readonly approval: Approval<R>,
+    protected readonly hooks: AppApprovalHooks<R>,
+  ) {}
+
+  /**
+   * Returns the bank's response once the approval is through. Throws `FinTsTanCancelledError` if the user cancels and
+   * `FinTsDecoupledTimeoutError` if the approval takes too long.
+   */
+  abstract run(): Promise<R>;
+
+  protected get method(): TanMethod {
+    return this.approval.challenge.method;
+  }
+
+  /** Whether the user may report the approval (PIN/TAN, "Manuelle Bestätigung möglich"). */
+  protected get userConfirms(): boolean {
+    return this.method.decoupledManualConfirmation;
+  }
+
+  protected get pollIntervalMs(): number {
+    return clamp(
+      seconds(this.method.decoupledPollIntervalSeconds) ?? defaultPollIntervalMs,
+      minPollIntervalMs,
+      maxPollDelayMs,
+    );
+  }
+
+  protected get firstPollDelayMs(): number {
+    return clamp(seconds(this.method.decoupledFirstPollDelaySeconds) ?? defaultFirstPollDelayMs, 0, maxPollDelayMs);
+  }
+
+  /**
+   * Sends the next status request and returns the answer, once `receive` has taken it in.
+   *
+   * Throws if the answer reports errors, and `FinTsDecoupledTimeoutError` if the approval is still pending after as
+   * many requests as the bank allows, or after the longest wait.
+   */
+  protected async requestStatus(): Promise<R> {
+    const response = await this.approval.checkStatus();
+    this.requests++;
+    this.hooks.receive(response);
+    // A maximum of 0 allows any number of requests (PIN/TAN, "Maximale Anzahl Statusabfragen Decoupled").
+    const maxRequests = this.method.decoupledMaxPolls ?? defaultMaxStatusPolls;
+    if (
+      isPending(response) &&
+      ((maxRequests > 0 && this.requests >= maxRequests) || this.waitedMs >= maxApprovalWaitMs)
+    ) {
+      throw new FinTsDecoupledTimeoutError();
+    }
+    return response;
+  }
+
+  /**
+   * `challenge` as the next prompt, with the new instructions of `pending`, the last status answer, where it gives any
+   * (PIN/TAN B.4.2.2.1, step 2b).
+   */
+  protected nextPrompt(challenge: TanChallenge, pending: R): TanChallenge {
+    return nextAttempt(challenge, this.approval.instructionsIn(pending));
+  }
+}
+
+/**
+ * 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. 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 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>();
+  private stopReason: { error: unknown } | undefined;
+
+  /** Settles when the user reports the approval in the prompt shown now; `undefined` once the report was used. */
+  private report: Deferred<void> | undefined;
+
+  async run(): Promise<R> {
+    let challenge = this.approval.challenge;
+    this.show(challenge);
+    try {
+      await this.sleep(this.firstPollDelayMs);
+      for (;;) {
+        this.throwIfStopped();
+        // A request under way is awaited even when the user cancels meanwhile; its answer counts.
+        const response = await this.requestStatus();
+        if (!isPending(response)) return response;
+        this.throwIfStopped();
+        // 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.shown?.resolve();
+    }
+  }
+
+  /** 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);
+    // 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 {
+    if (this.stopped.isCompleted) return;
+    this.stopReason = { error };
+    this.stopped.resolve();
+  }
+
+  private throwIfStopped(): void {
+    if (this.stopReason !== undefined) throw this.stopReason.error;
+  }
+
+  /**
+   * Waits for `delayMs`, or until the user cancels or reports the approval; a report does not cut the wait below
+   * `floorMs`. A wait cut short counts towards the longest wait with its floor only.
+   */
+  private async sleep(delayMs: number, floorMs = 0): Promise<void> {
+    const report = this.report;
+    if (floorMs > 0) await this.hooks.pause(floorMs, this.stopped.promise);
+    const interrupt =
+      report === undefined ? this.stopped.promise : Promise.race([this.stopped.promise, report.promise]);
+    await this.hooks.pause(delayMs - floorMs, interrupt);
+    const cutShort = report?.isCompleted ?? false;
+    this.waitedMs += cutShort ? floorMs : delayMs;
+    // One report, one early request.
+    if (cutShort) this.report = undefined;
+  }
+}
+
+/**
+ * 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 StatusAnswer> extends AppApprovalWait<R> {
+  async run(): Promise<R> {
+    let challenge = this.approval.challenge;
+    await this.confirm(challenge);
+    for (;;) {
+      const response = await this.requestStatus();
+      if (!isPending(response)) return response;
+      challenge = this.nextPrompt(challenge, response);
+      // The prompt comes back at once; however fast the user reports again, the next request waits a second.
+      await Promise.all([this.confirm(challenge), this.hooks.pause(minPollIntervalMs)]);
+      this.waitedMs += minPollIntervalMs;
+    }
+  }
+
+  /** Shows `challenge` and waits until the user reports the approval or cancels. */
+  private async confirm(challenge: TanChallenge): Promise<void> {
+    const answer = await this.hooks.ask(challenge);
+    switch (answer.kind) {
+      case 'approved':
+        return;
+      case 'cancelled':
+        throw new FinTsTanCancelledError();
+      case 'tan':
+        throw tanForApproval();
+    }
+  }
+}
+
+/** Whether `response` tells that the approval is still pending (return code 3956). */
+function isPending(response: StatusAnswer): boolean {
+  return hasCode(response.feedback, FeedbackCodes.decoupledStillPending);
+}
+
+function tanForApproval(): TypeError {
+  return invalidArgument('Answered an approval in the banking app with a TAN', 'tanCallback');
+}
+
+function seconds(value: number | undefined): number | undefined {
+  return value === undefined ? undefined : value * 1000;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}

package/src/session/dialog-runner.ts

@@ -0,0 +1,122 @@
+import { FinTsBankError, FinTsProtocolError, parseBankData } from '../core/errors.js';
+import { continuations, FeedbackCodes, hasCode } from '../core/feedback.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 { 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 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;
+
+/**
+ * Keeps one dialog open for all calls and runs the queries in it.
+ *
+ * A dialog the bank has ended is not used again: the call that learns of it fails, and the next call logs in anew. The
+ * 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 {
+  private dialog: SignedDialog | undefined;
+
+  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<SignedDialog> {
+    const current = this.dialog;
+    if (current?.isActive === true) return current;
+    this.dialog = undefined;
+    const dialog = await this.setup.remedied(() => this.login());
+    this.dialog = dialog;
+    return dialog;
+  }
+
+  private async login(): Promise<SignedDialog> {
+    const dialog = await this.setup.newDialog();
+    try {
+      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,
+      // such as a cancelled TAN, the bank still knows the dialog.
+      await dialog.end();
+      throw error;
+    }
+  }
+
+  /** Ends the open dialog, if there is one. */
+  async end(): Promise<void> {
+    const dialog = this.dialog;
+    this.dialog = undefined;
+    await dialog?.end();
+  }
+
+  /**
+   * Runs the query `build` returns in the session's dialog and reads all its pages.
+   *
+   * The query is built once the dialog is open, since building it takes the parameter data.
+   */
+  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, which only the `firstPage` of a query may ask for. */
+  private async run(dialog: SignedDialog, order: SegmentSpec, firstPage: boolean): Promise<IncomingMessage3> {
+    try {
+      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
+      // unknown state.
+      if (!(error instanceof FinTsBankError)) await this.end();
+      throw error;
+    }
+  }
+
+  /** Sends the order built by `order` until the bank has delivered all pages (Formals B.6.3, "Aufsetzpunkt"). */
+  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), 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');
+      continuation = positions[0];
+      if (continuation === undefined) {
+        // Read as the last page, more data without a position would look like all there is.
+        if (hasCode(page.feedback, FeedbackCodes.moreData)) {
+          throw new FinTsProtocolError('The bank has more data, but names no position to continue at');
+        }
+        return pages;
+      }
+      // 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);
+    }
+  }
+}

package/src/session/login-guard.ts

@@ -0,0 +1,221 @@
+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, 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' | '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
+ * may not use the TAN method the login was signed with, or the bank no longer accepts the customer system ID.
+ */
+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;
+}
+
+/**
+ * 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.
+ *
+ * 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 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;
+
+  /** Logins sent since the bank last took the PIN whose answer the client has not read. */
+  private unreadLogins = 0;
+
+  /** 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 {
+    const refusal = this.refusal;
+    if (refusal !== undefined) throw refusal;
+  }
+
+  /** 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;
+  }
+
+  /** Counts a login signed with the PIN as unread until `judge` reads its answer. */
+  loginSent(): void {
+    this.unreadLogins++;
+  }
+
+  /**
+   * 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 | 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 refusal;
+  }
+
+  /** 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 `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 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();
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  replacePin(pin: string): void {
+    if (this.refusalValue instanceof FinTsLoginDataChangedError) throw this.refusalValue;
+    this.#pin = pin;
+    this.liftRefusal();
+    this.unreadLogins = 0;
+    this.unreadLoginsRefusal = undefined;
+  }
+
+  /** Forgets the PIN; the client calls it once it is closed. */
+  close(): void {
+    this.#pin = undefined;
+  }
+
+  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));
+}