@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/core/client.ts

@@ -0,0 +1,149 @@
+import type { TanCallback, TanMediumSelector, TanMethodSelector } from '../tan/challenge.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import type { Account } from './account.js';
+import type { Balance } from './balance.js';
+import type { BankInfo, BankMessage } from './bank-info.js';
+import type { FinTsFeedback } from './feedback.js';
+import type { Transaction, TransactionFormat } from './transaction.js';
+import type { FinTsTransport } from './transport.js';
+
+/** Which way a FinTS message travels: from the client to the bank, or back. */
+export type MessageDirection = 'outgoing' | 'incoming';
+
+/** Receives every FinTS message with PIN and TAN masked. */
+export type MessageLogger = (direction: MessageDirection, message: string) => void;
+
+/** Receives free-text messages the bank sends during login. */
+export type BankMessageHandler = (message: BankMessage) => void;
+
+/** Receives a warning the bank sends, a return code from 3000 to 3999. */
+export type WarningHandler = (warning: FinTsFeedback) => void;
+
+/**
+ * How a client reaches the user and the bank, apart from the login data in `FinTsConfig`.
+ *
+ * An error thrown by a callback that only informs the app (`onBankMessage`, `onWarning`, `logger`) fails the call once
+ * the call's exchange with the bank is over, so that it cannot break off a dialog half-way; an error of the call itself
+ * takes precedence.
+ */
+export interface FinTsClientOptions {
+  /** Called whenever the bank asks for a TAN or an app approval. */
+  tanCallback: TanCallback;
+
+  /** Picks the TAN method when the bank offers several; the first is used without it. */
+  tanMethodSelector?: TanMethodSelector;
+
+  /** Picks the TAN medium when the method needs one and the user has several; the first is used without it. */
+  tanMediumSelector?: TanMediumSelector;
+
+  /** Receives the free-text messages the bank sends during login. */
+  onBankMessage?: BankMessageHandler;
+
+  /**
+   * Receives the bank's warnings, such as 3951 (switch to another TAN method), but not those the client acts on itself,
+   * such as 3040 (more data follow). Show them to the user with code and text, as the specification asks.
+   */
+  onWarning?: WarningHandler;
+
+  /** Receives every FinTS message with PIN and TAN masked, for diagnosis; the messages contain account data. */
+  logger?: MessageLogger;
+
+  /**
+   * The `FinTsClient.state` of a previous session, which skips the bank setup steps.
+   *
+   * A state saved for another user or bank is ignored.
+   */
+  state?: string | undefined;
+
+  /**
+   * Sends the messages; an `HttpTransport` by default.
+   *
+   * The client closes it on `FinTsClient.close`, so hand each client a transport of its own.
+   */
+  transport?: FinTsTransport;
+}
+
+/** What `getTransactions` takes besides the account. */
+export interface TransactionQuery {
+  /** The first day, a day in the future counting as today; banks typically ask for a TAN beyond 90 days ago. */
+  from?: Date | undefined;
+  /** The last day, a day in the future counting as today. */
+  to?: Date | undefined;
+  /** The format to ask for; `auto` by default. */
+  format?: TransactionFormat;
+}
+
+/**
+ * Read access to a bank account over FinTS.
+ *
+ * All calls share one bank dialog, so strong authentication happens once per session. Calls run one after another; call
+ * `close` when done.
+ *
+ * A callback in `FinTsClientOptions` must not wait for another call of its client, which would wait for the running
+ * call. On Node.js, Deno and Bun such a call fails with `FinTsStateError`; elsewhere it would wait forever. `close` works
+ * from anywhere.
+ */
+export interface FinTsClient {
+  /**
+   * Serialized session data: bank and user parameters, customer system ID, the TAN methods the user may use, the chosen
+   * TAN method and medium, and the SEPA account list.
+   *
+   * Contains no PIN or TAN, but account details, so store it encrypted.
+   */
+  readonly state: string;
+
+  /** Security function code of the TAN method in use, for example `942`; `undefined` before the first login. */
+  readonly selectedTanMethod: string | undefined;
+
+  /** Name of the TAN medium sent to the bank, if the method needs one. */
+  readonly selectedTanMedium: string | undefined;
+
+  /**
+   * Switches to another TAN method, and optionally TAN medium, for the following calls.
+   *
+   * Ends the current dialog, so the next call logs in again with the new method. If the bank does not offer
+   * `securityFunction`, the client picks another method at that login.
+   */
+  selectTanMethod(securityFunction: string, tanMedium?: string): Promise<void>;
+
+  /** General information about the bank, from the bank parameter data. */
+  getBankInfo(): Promise<BankInfo>;
+
+  /** TAN procedures the bank allows for this user. */
+  getTanMethods(): Promise<TanMethod[]>;
+
+  /** TAN devices registered for this user. */
+  getTanMedia(): Promise<TanMedium[]>;
+
+  /** Accounts of the user, completed with IBAN and BIC where the bank provides them. */
+  getAccounts(): Promise<Account[]>;
+
+  /**
+   * The balance of `account`.
+   *
+   * Where the user parameter data carry the complete balance (account extension), possibly from the saved `state`, it
+   * comes from there without a query; `Balance.bookedAsOf` tells the day it states.
+   *
+   * Throws `FinTsUnsupportedError`, without asking the bank, where the parameter data rule the query out.
+   */
+  getBalance(account: Account): Promise<Balance>;
+
+  /**
+   * Transactions from the day of `from` to the day of `to`, both included, booked and pending, sorted by date; those of
+   * the same day in the bank's order.
+   *
+   * Only the local calendar day counts, and a day in the future counts as today. Banks typically ask for a TAN when
+   * `from` is more than 90 days ago; see also `Account.dataStatus`. Throws `TypeError` if `from` lies on a day after
+   * `to`, and `FinTsUnsupportedError`, without asking the bank, where the parameter data rule the query out.
+   */
+  getTransactions(account: Account, query?: TransactionQuery): Promise<Transaction[]>;
+
+  /**
+   * Ends the bank dialog and releases the connection.
+   *
+   * A running call stops at its next step, also while it waits for a TAN, an app approval or a selection, and fails with
+   * `FinTsStateError`, as do all later calls. A request already on its way is awaited, at most for the transport's
+   * timeout.
+   */
+  close(): Promise<void>;
+}

package/src/core/config.ts

@@ -0,0 +1,141 @@
+import { invalidArgument } from '../util/errors.js';
+
+/** Numeric country code of Germany (ISO 3166), where FinTS banks are. */
+export const defaultCountryCode = '280';
+
+/** What `FinTsConfig` takes. */
+export interface FinTsConfigInit {
+  /** The bank's FinTS PIN/TAN endpoint; must be https. */
+  url: string | URL;
+  /** German bank code (BLZ). */
+  bankCode: string;
+  /** Login name (Benutzerkennung / Legitimations-ID). */
+  userId: string;
+  /** Customer ID; defaults to `userId`. */
+  customerId?: string | undefined;
+  /** FinTS product registration number from the Deutsche Kreditwirtschaft; at most 25 characters. */
+  productId: string;
+  /** Version of the app as registered with the product; at most five characters. `1.0` by default. */
+  productVersion?: string;
+  /** Numeric country code of the bank, `280` (Germany) by default. */
+  countryCode?: string;
+  /**
+   * Allows plain http for the loopback addresses `localhost`, `127.x.x.x` and `::1`, for tests against a local server.
+   *
+   * Any other host must use https, whatever this says: the PIN travels with every message.
+   */
+  allowInsecureUrl?: boolean;
+}
+
+/** Connection and login data for one bank user. */
+export class FinTsConfig {
+  /** Numeric country code of Germany (ISO 3166), where FinTS banks are. */
+  static readonly defaultCountryCode = defaultCountryCode;
+
+  readonly url: URL;
+  readonly bankCode: string;
+  readonly userId: string;
+  private readonly explicitCustomerId: string | undefined;
+  readonly productId: string;
+  readonly productVersion: string;
+  readonly countryCode: string;
+  readonly allowInsecureUrl: boolean;
+
+  /**
+   * Throws `TypeError` if `url` is not a valid URL, has no host or is not https, unless `allowInsecureUrl` is set and
+   * `url` is a loopback address, and if a login detail or the product is empty: the bank would refuse the login.
+   */
+  constructor(init: FinTsConfigInit) {
+    // `URL` would read `https:bank` and `https:///bank` as the host `bank`; such a URL is a mistake, not a host.
+    if (typeof init.url === 'string' && !/^[a-z][a-z0-9+.-]*:\/\/[^/]/i.test(init.url)) {
+      throw invalidArgument('The URL has no host', 'url');
+    }
+    let url: URL;
+    try {
+      url = new URL(init.url);
+    } catch {
+      throw invalidArgument('Not a valid URL', 'url');
+    }
+    this.url = url;
+    this.bankCode = init.bankCode;
+    this.userId = init.userId;
+    this.explicitCustomerId = init.customerId;
+    this.productId = init.productId;
+    this.productVersion = init.productVersion ?? '1.0';
+    this.countryCode = init.countryCode ?? defaultCountryCode;
+    this.allowInsecureUrl = init.allowInsecureUrl ?? false;
+    requireSecureUrl(url, this.allowInsecureUrl);
+    requireNotBlank(this.bankCode, 'bankCode');
+    requireNotBlank(this.userId, 'userId');
+    if (this.explicitCustomerId !== undefined) requireNotBlank(this.explicitCustomerId, 'customerId');
+    requireNotBlank(this.productId, 'productId');
+    requireNotBlank(this.productVersion, 'productVersion');
+    requireNotBlank(this.countryCode, 'countryCode');
+  }
+
+  /** Customer ID; defaults to `userId`. */
+  get customerId(): string {
+    return this.explicitCustomerId ?? this.userId;
+  }
+}
+
+function requireNotBlank(value: string, name: string): void {
+  if (value.trim() === '') throw invalidArgument('Must not be empty', name);
+}
+
+/** The host of `url` without the brackets of an IPv6 address, as `URL` writes it. */
+export function hostOf(url: URL): string {
+  const host = url.hostname;
+  return host.startsWith('[') && host.endsWith(']') ? host.substring(1, host.length - 1) : host;
+}
+
+/**
+ * Throws `TypeError` unless `url` names a host and uses https: the PIN travels with every message.
+ *
+ * With `allowInsecure`, http is accepted for loopback hosts only.
+ */
+export function requireSecureUrl(url: URL, allowInsecure = false): void {
+  if (hostOf(url) === '') throw invalidArgument('The URL has no host', 'url');
+  const loopbackHttp = allowInsecure && url.protocol === 'http:' && isLoopback(hostOf(url));
+  if (url.protocol !== 'https:' && !loopbackHttp) throw invalidArgument('PIN/TAN requires an https URL', 'url');
+}
+
+/**
+ * Throws `TypeError` for an empty PIN, which the bank would count as a failed attempt, and for one with leading or
+ * trailing blanks: FinTS values carry none (Formals B.4.1), so such a PIN could only go out changed.
+ *
+ * The message leaves out the value.
+ */
+export function requirePin(pin: string): string {
+  if (pin.trim() === '') throw invalidArgument('The PIN is empty', 'pin');
+  if (pin.trim() !== pin) throw invalidArgument('The PIN begins or ends with a blank', 'pin');
+  return pin;
+}
+
+/**
+ * Throws `TypeError` if `pin` is shorter than `min` or longer than `max` characters, the bank's limits: the bank would
+ * count such a PIN as a failed attempt. A limit that is `undefined` or below 1 does not apply.
+ *
+ * The message leaves out the PIN and its length.
+ */
+export function requirePinLength(pin: string, min: number | undefined, max: number | undefined): void {
+  const tooShort = min !== undefined && min > 0 && pin.length < min;
+  const tooLong = max !== undefined && max > 0 && pin.length > max;
+  if (tooShort || tooLong) {
+    const range = [
+      ...(min !== undefined && min > 0 ? [`at least ${min}`] : []),
+      ...(max !== undefined && max > 0 ? [`at most ${max}`] : []),
+    ].join(' and ');
+    throw invalidArgument(`The bank takes PINs of ${range} characters`, 'pin');
+  }
+}
+
+const loopbackAddress = /^127(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+
+/**
+ * Only addresses and names that cannot leave the machine: a resolver may send a subdomain such as `bank.localhost`, or
+ * a string that is not an address, such as `127.999.1.1`, to DNS.
+ */
+function isLoopback(host: string): boolean {
+  return host === 'localhost' || host === '::1' || loopbackAddress.test(host);
+}

package/src/core/errors.ts

@@ -0,0 +1,203 @@
+import { FormatError } from '../util/errors.js';
+import { endsDialog, FeedbackCodes, type FinTsFeedback } from './feedback.js';
+
+/** Base class of all errors the client raises about the bank and its data. */
+export abstract class FinTsError extends Error {
+  protected constructor(name: string, message: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    // Set explicitly: a minifier renames classes, and `constructor.name` would show a meaningless name.
+    this.name = name;
+  }
+}
+
+/** The connection to the bank failed or returned an HTTP error. */
+export class FinTsTransportError extends FinTsError {
+  /** The HTTP status code of the response, `undefined` if there was none, for example after a timeout. */
+  readonly statusCode: number | undefined;
+
+  constructor(message: string, options?: { statusCode?: number; cause?: unknown }) {
+    super('FinTsTransportError', message, options?.cause);
+    this.statusCode = options?.statusCode;
+  }
+}
+
+/** The bank's response could not be understood. */
+export class FinTsProtocolError extends FinTsError {
+  constructor(message: string) {
+    super('FinTsProtocolError', message);
+  }
+}
+
+/** The bank does not offer the requested business transaction. */
+export class FinTsUnsupportedError extends FinTsError {
+  constructor(message: string) {
+    super('FinTsUnsupportedError', message);
+  }
+}
+
+/**
+ * The bank rejected the request; `feedback` holds all return codes.
+ *
+ * After a refused login every later call that would send the PIN fails with the same error, without contacting the
+ * bank; create a new client to try again. The README tells which errors refuse a login.
+ */
+export class FinTsBankError extends FinTsError {
+  /** All return codes of the response, warnings and successes included. */
+  readonly feedback: readonly FinTsFeedback[];
+
+  /** A rejection with the return codes in `feedback`; `message` defaults to the errors among them. */
+  constructor(feedback: readonly FinTsFeedback[], message?: string, name = 'FinTsBankError') {
+    super(
+      name,
+      message ??
+        feedback
+          .filter((f) => f.isError)
+          .map((f) => f.toString())
+          .join('; '),
+    );
+    this.feedback = Object.freeze([...feedback]);
+  }
+
+  /** The return codes of `feedback`. */
+  get codes(): string[] {
+    return this.feedback.map((f) => f.code);
+  }
+}
+
+/** Wrong or blocked PIN, a refused login as `FinTsBankError` describes it. */
+export class FinTsPinError extends FinTsBankError {
+  constructor(feedback: readonly FinTsFeedback[]) {
+    super(feedback, undefined, 'FinTsPinError');
+  }
+}
+
+/** Invalid, expired or rejected TAN, as the bank reports it in answer to a TAN or to an approval status request. */
+export class FinTsTanError extends FinTsBankError {
+  constructor(feedback: readonly FinTsFeedback[]) {
+    super(feedback, undefined, 'FinTsTanError');
+  }
+}
+
+/**
+ * The bank has changed the user's login data and expects the new ones from now on (return code 3072).
+ *
+ * The client has ended the dialog, and every later call fails with this error. Create a new client with the new data; a
+ * `loginName` replaces user ID and customer ID: pass it as `userId`, without a customer ID.
+ */
+export class FinTsLoginDataChangedError extends FinTsBankError {
+  constructor(feedback: readonly FinTsFeedback[]) {
+    super(feedback, 'The bank has changed the login data', 'FinTsLoginDataChangedError');
+  }
+
+  /** The new user ID (Benutzerkennung); `undefined` where the bank names none. */
+  get userId(): string | undefined {
+    return this.parameter(0);
+  }
+
+  /** The new customer ID (Kunden-ID); `undefined` where the bank names none. */
+  get customerId(): string | undefined {
+    return this.parameter(1);
+  }
+
+  /** The new login name (Anmeldename); `undefined` where the bank names none. */
+  get loginName(): string | undefined {
+    return this.parameter(2);
+  }
+
+  private parameter(index: number): string | undefined {
+    const change = this.feedback.find((f) => f.code === FeedbackCodes.newLoginData);
+    const value = change?.parameters[index]?.trim();
+    return value === undefined || value === '' ? undefined : value;
+  }
+}
+
+/** The bank ended the dialog, for example after a timeout. */
+export class FinTsDialogAbortedError extends FinTsBankError {
+  constructor(feedback: readonly FinTsFeedback[]) {
+    super(feedback, undefined, 'FinTsDialogAbortedError');
+  }
+}
+
+/** The user cancelled the TAN entry or the approval in the banking app. */
+export class FinTsTanCancelledError extends FinTsError {
+  constructor() {
+    super('FinTsTanCancelledError', 'TAN entry cancelled');
+  }
+}
+
+/** The user did not approve in the banking app within the bank's polling limit. */
+export class FinTsDecoupledTimeoutError extends FinTsError {
+  constructor() {
+    super('FinTsDecoupledTimeoutError', 'Approval on the separate device was not completed in time');
+  }
+}
+
+/**
+ * The client was closed, or called from inside one of its own callbacks, which would wait for itself.
+ *
+ * It does not extend `FinTsError`: it tells about the app's use of the client, not about the bank.
+ */
+export class FinTsStateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FinTsStateError';
+  }
+}
+
+/**
+ * Return codes for a wrong or blocked PIN, from the FinTS return code list (Rückmeldungscodes): 9340 signature (PIN)
+ * wrong, 9910 PIN invalid or blocked, 9930 PIN blocked, 9931 blocked after failed attempts, 9942 PIN invalid.
+ */
+const pinErrors = new Set(['9340', '9910', '9930', '9931', '9942']);
+
+/**
+ * Return codes for a rejected TAN: 9941 TAN invalid, 9943 and 9991 TAN already used (the return code list and the
+ * PIN/TAN specification give different numbers), 9951 two-step timeout.
+ *
+ * The return code list gives 9941 and 9951 a second meaning, "Signatur ungültig" (invalid signature), which in PIN/TAN
+ * is the PIN; see `bankErrorFor`.
+ */
+const tanErrors = new Set(['9941', '9943', '9951', '9991']);
+
+/**
+ * Whether `f` reports a wrong or blocked PIN. Two of the codes stand for other faults as well, which the text tells:
+ * 9340 "Sicherheitsprofil unbekannt", 9910 "TAN-Reihe gesperrt" and "Chipkarte gesperrt".
+ */
+function isPinError(f: FinTsFeedback): boolean {
+  if (!f.isError || !pinErrors.has(f.code)) return false;
+  const text = f.text.toLowerCase();
+  switch (f.code) {
+    case '9340':
+      return !text.includes('profil');
+    case '9910':
+      return !text.includes('tan-reihe') && !text.includes('chipkarte');
+    default:
+      return true;
+  }
+}
+
+/**
+ * The most specific error for the errors in `feedback`, the answer to a message that `completesApproval` or not.
+ *
+ * Only the answer to a TAN or an approval status request can reject a TAN; anywhere else a TAN return code is a plain
+ * `FinTsBankError`. In answer to a login, 9941 or 9951 may reject the PIN, and the client must not take a refused login
+ * for a wrong TAN, after which it would send the PIN again.
+ */
+export function bankErrorFor(feedback: readonly FinTsFeedback[], completesApproval = false): FinTsBankError {
+  if (feedback.some(isPinError)) return new FinTsPinError(feedback);
+  if (completesApproval && feedback.some((f) => f.isError && tanErrors.has(f.code))) {
+    return new FinTsTanError(feedback);
+  }
+  if (endsDialog(feedback)) return new FinTsDialogAbortedError(feedback);
+  return new FinTsBankError(feedback);
+}
+
+/** Runs `parse` on data from the bank and reports malformed data as `FinTsProtocolError`. */
+export function parseBankData<T>(parse: () => T): T {
+  try {
+    return parse();
+  } catch (error) {
+    if (error instanceof FormatError) throw new FinTsProtocolError(`Malformed bank data: ${error.message}`);
+    throw error;
+  }
+}

package/src/core/feedback.ts

@@ -0,0 +1,137 @@
+/** A return code with text from the bank, for example `0020: Auftrag ausgeführt`. */
+export class FinTsFeedback {
+  /** The four-digit return code; `0…` reports success, `3…` a warning and `9…` an error. */
+  readonly code: string;
+
+  /** The element of the request the code refers to, if the bank names one. */
+  readonly reference: string | undefined;
+
+  /** The bank's explanation of the code. */
+  readonly text: string;
+
+  /** Values the bank adds to the code, such as the position to continue at. */
+  readonly parameters: readonly string[];
+
+  constructor(init: { code: string; reference?: string | undefined; text: string; parameters?: readonly string[] }) {
+    this.code = init.code;
+    this.reference = init.reference;
+    this.text = init.text;
+    this.parameters = Object.freeze([...(init.parameters ?? [])]);
+  }
+
+  /** Whether the code reports success. */
+  get isSuccess(): boolean {
+    return this.code.startsWith('0');
+  }
+
+  /** Whether the code is a warning. */
+  get isWarning(): boolean {
+    return this.code.startsWith('3');
+  }
+
+  /** Whether the code is an error. */
+  get isError(): boolean {
+    return this.code.startsWith('9');
+  }
+
+  toString(): string {
+    return `${this.code}: ${this.text}${this.parameters.length === 0 ? '' : ` [${this.parameters.join(', ')}]`}`;
+  }
+}
+
+/** Return codes the client reacts to, as named in the FinTS return code list (Rückmeldungscodes). */
+export const FeedbackCodes = Object.freeze({
+  /** Order received, strong authentication required (Auftrag empfangen – Sicherheitsfreigabe erforderlich). */
+  tanRequired: '0030',
+  /** More information available; the first parameter is where to continue (Es liegen weitere Informationen vor). */
+  moreData: '3040',
+  /**
+   * The bank has new login data for the user; the parameters are the user ID, the customer ID and the login name
+   * (Neue Anmeldedaten).
+   */
+  newLoginData: '3072',
+  /** The one- and two-step methods the user may use, as parameters. */
+  allowedTanMethods: '3920',
+  /** Approval happens on another channel, such as a banking app (Sicherheitsfreigabe erfolgt über anderen Kanal). */
+  decoupledPending: '3955',
+  /** Strong authentication still pending (Starke Kundenauthentifizierung noch ausstehend). */
+  decoupledStillPending: '3956',
+  /** Wait for the push message (Auf Push-Nachricht warten). */
+  decoupledWaitForPush: '3957',
+  /** The bank ended the dialog (Dialog abgebrochen). */
+  dialogAborted: '9800',
+  /**
+   * The bank ended the dialog because it requires strong authentication (Dialog abgebrochen – starke Authentifizierung
+   * erforderlich).
+   */
+  scaRequired: '9075',
+  /** The customer system ID is not accepted any more; a synchronization delivers a new one (Neue Kundensystem-ID holen). */
+  newSystemIdRequired: '9391',
+});
+
+/**
+ * The return codes with which the bank ends the dialog ("Dialog abgebrochen" in the return code list): 9800 and 9075,
+ * and 9077 (hardened browser required), 9078 (product not registered) and 9361 (security procedure no longer allowed).
+ */
+const dialogEnding = new Set<string>([FeedbackCodes.dialogAborted, FeedbackCodes.scaRequired, '9077', '9078', '9361']);
+
+/**
+ * The warnings about the protocol, which the client acts on itself and the user has no use for: paging, the allowed TAN
+ * methods, the steps of an approval and 3076 (no strong authentication needed), new login data, which fail the call,
+ * and 3060 (some warnings), which only announces the others.
+ */
+const protocolWarnings = new Set<string>([
+  FeedbackCodes.moreData,
+  '3060',
+  FeedbackCodes.newLoginData,
+  '3076',
+  FeedbackCodes.allowedTanMethods,
+  FeedbackCodes.decoupledPending,
+  FeedbackCodes.decoupledStillPending,
+  FeedbackCodes.decoupledWaitForPush,
+]);
+
+// Reading return codes the way the session logic needs; not part of the public API.
+
+/** Whether a return code `code` is among the `feedback`. */
+export function hasCode(feedback: readonly FinTsFeedback[], code: string): boolean {
+  return feedback.some((f) => f.code === code);
+}
+
+/** Whether any return code is an error. */
+export function hasErrors(feedback: readonly FinTsFeedback[]): boolean {
+  return feedback.some((f) => f.isError);
+}
+
+/** The positions to continue at that the bank names with return code 3040; empty on the last page. */
+export function continuations(feedback: readonly FinTsFeedback[]): Set<string> {
+  const positions = new Set<string>();
+  for (const f of feedback) {
+    const position = f.parameters[0];
+    if (f.code === FeedbackCodes.moreData && position !== undefined && position !== '') positions.add(position);
+  }
+  return positions;
+}
+
+/**
+ * The security functions of the TAN methods the user may use, as the bank lists them with return code 3920, in all such
+ * return codes; empty if it lists none.
+ */
+export function allowedTanMethodsIn(feedback: readonly FinTsFeedback[]): string[] {
+  const codes = new Set<string>();
+  for (const f of feedback) {
+    if (f.code !== FeedbackCodes.allowedTanMethods) continue;
+    for (const code of f.parameters) if (code !== '') codes.add(code);
+  }
+  return [...codes];
+}
+
+/** Whether the bank ended the dialog with one of its return codes for that. */
+export function endsDialog(feedback: readonly FinTsFeedback[]): boolean {
+  return feedback.some((f) => dialogEnding.has(f.code));
+}
+
+/** The warnings for the user: all but those about the protocol. */
+export function userWarnings(feedback: readonly FinTsFeedback[]): FinTsFeedback[] {
+  return feedback.filter((f) => f.isWarning && !protocolWarnings.has(f.code));
+}