@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/core/config.ts

@@ -0,0 +1,182 @@
+import { invalidArgument } from '../util/errors.js';
+import { isLatin1 } from '../util/text.js';
+
+/**
+ * The country code FinTS gives Germany, where FinTS banks are: the ISO 3166 code of the Federal Republic before 1990,
+ * not today's `276`.
+ */
+export const defaultCountryCode = '280';
+
+/** Longest bank code (Kreditinstitutscode), product ID (Produktbezeichnung) and product version FinTS 3.0 takes. */
+const maxBankCodeLength = 30;
+const maxProductIdLength = 25;
+const maxProductVersionLength = 5;
+
+/** What `FinTsConfig` takes. */
+export interface FinTsConfigInit {
+  /** The bank's FinTS PIN/TAN endpoint; must be https, without user name or password. */
+  url: string | URL;
+  /** Bank code: for a German bank its BLZ, eight digits. */
+  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;
+  /** Country code of the bank, three digits: `280`, the default, for Germany. */
+  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 {
+  /** The country code FinTS gives Germany, where FinTS banks are: `280`, not today's ISO 3166 code `276`. */
+  static readonly defaultCountryCode = defaultCountryCode;
+
+  private readonly href: string;
+  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, holds a user name or password, or is not https, unless
+   * `allowInsecureUrl` is set and `url` is a loopback address. Throws as well where the bank would refuse the login: for
+   * a login or product detail that is empty, has characters FinTS 3.0 cannot send (it uses ISO 8859-1, so `€` and most
+   * non-Latin letters are not possible) or is longer than its field (30 characters for the bank code, 25 for the
+   * product ID, 5 for its version), for a country code of other than three digits, and for a German bank code of other
+   * than eight. The message leaves out the value.
+   *
+   * Drops leading and trailing blanks of the login details and the product, as FinTS sends them without (Formals
+   * B.4.1): `'alice '` is the user `alice`, also for a saved state.
+   */
+  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.href = url.href;
+    this.allowInsecureUrl = init.allowInsecureUrl ?? false;
+    requireSecureUrl(url, this.allowInsecureUrl);
+    this.countryCode = requireValue(init.countryCode ?? defaultCountryCode, 'countryCode');
+    if (!/^\d{3}$/.test(this.countryCode)) {
+      throw invalidArgument('Must be three digits, 280 for Germany', 'countryCode');
+    }
+    this.bankCode = requireValue(init.bankCode, 'bankCode', maxBankCodeLength);
+    if (this.countryCode === defaultCountryCode && !/^\d{8}$/.test(this.bankCode)) {
+      throw invalidArgument('A German bank code (BLZ) has eight digits', 'bankCode');
+    }
+    this.userId = requireValue(init.userId, 'userId');
+    this.explicitCustomerId = init.customerId === undefined ? undefined : requireValue(init.customerId, 'customerId');
+    this.productId = requireValue(init.productId, 'productId', maxProductIdLength);
+    this.productVersion = requireValue(init.productVersion ?? '1.0', 'productVersion', maxProductVersionLength);
+  }
+
+  /**
+   * The bank's FinTS PIN/TAN endpoint, as checked by the constructor. A new `URL` on each access, so that changing one
+   * cannot change where the client posts the PIN.
+   */
+  get url(): URL {
+    return new URL(this.href);
+  }
+
+  /** Customer ID; defaults to `userId`. */
+  get customerId(): string {
+    return this.explicitCustomerId ?? this.userId;
+  }
+}
+
+/**
+ * `value` without leading and trailing blanks; throws `TypeError` if nothing is left, or what is left is not sendable
+ * (`requireLatin1`) or longer than `maxLength`: cut short, a value would be one the bank does not know.
+ */
+function requireValue(value: string, name: string, maxLength = Number.POSITIVE_INFINITY): string {
+  const trimmed = value.trim();
+  if (trimmed === '') throw invalidArgument('Must not be empty', name);
+  requireLatin1(trimmed, name);
+  if (trimmed.length > maxLength) throw invalidArgument(`At most ${maxLength} characters in FinTS 3.0`, name);
+  return trimmed;
+}
+
+/** `text`, unless it has characters FinTS 3.0 cannot send (ISO 8859-1 only); the message leaves out the value. */
+export function requireLatin1(text: string, name: string): string {
+  if (!isLatin1(text)) throw invalidArgument('Contains characters FinTS 3.0 cannot send (ISO 8859-1 only)', name);
+  return text;
+}
+
+/** 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. Throws as well for a user name or password in `url`:
+ * `fetch` refuses such a URL, with the whole URL in its error message. The message leaves them out.
+ */
+function requireSecureUrl(url: URL, allowInsecure = false): void {
+  if (hostOf(url) === '') throw invalidArgument('The URL has no host', 'url');
+  if (url.username !== '' || url.password !== '') throw invalidArgument('The URL must not contain credentials', 'url');
+  const loopbackHttp = allowInsecure && url.protocol === 'http:' && isLoopback(hostOf(url));
+  if (url.protocol !== 'https:' && !loopbackHttp) throw invalidArgument('PIN/TAN requires an https URL', 'url');
+}
+
+/**
+ * `pin`, unless FinTS 3.0 cannot send it: throws `TypeError` for an empty PIN, which the bank would count as a failed
+ * attempt, for one with leading or trailing blanks, which would go out without them since FinTS values carry none
+ * (Formals B.4.1), and for one with characters outside ISO 8859-1.
+ *
+ * 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 requireLatin1(pin, '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,277 @@
+import { FormatError } from '../util/errors.js';
+import { nonBlank } from '../util/text.js';
+import { endsDialog, FeedbackCodes, hasCode, type FinTsFeedback } from './feedback.js';
+
+/**
+ * Base class of all errors the client raises about the bank and its data.
+ *
+ * Each error class states its `name`: a minifier renames classes, and `constructor.name` would show a meaningless one.
+ */
+export abstract class FinTsError extends Error {
+  abstract override name: string;
+}
+
+/**
+ * The connection to the bank failed or returned an HTTP error.
+ *
+ * It carries no `cause`: the transport's own error may hold the message it was sending, PIN and TAN included.
+ */
+export class FinTsTransportError extends FinTsError {
+  override name = 'FinTsTransportError';
+
+  /**
+   * The HTTP status code of the bank's answer, `undefined` where none came, for example after a timeout; the client
+   * acts on it (`FinTsTransport.post`).
+   */
+  readonly statusCode: number | undefined;
+
+  constructor(message: string, options?: { statusCode?: number }) {
+    super(message);
+    this.statusCode = options?.statusCode;
+  }
+}
+
+/** The bank's response could not be understood. */
+export class FinTsProtocolError extends FinTsError {
+  override name = 'FinTsProtocolError';
+}
+
+/** The bank does not offer the requested business transaction. */
+export class FinTsUnsupportedError extends FinTsError {
+  override name = 'FinTsUnsupportedError';
+}
+
+/**
+ * The client has no TAN method or medium to log in with: the method in use needs a TAN medium the client could not
+ * learn, or the bank offers the user only TAN methods the client cannot run. Pass a medium to
+ * `FinTsClient.selectTanMethod`, or choose another method.
+ *
+ * The client does not send a login the bank would refuse for it, but the steps before, such as the synchronization or
+ * the lookup of the TAN media, may have gone out.
+ */
+export class FinTsTanSetupError extends FinTsError {
+  override name = 'FinTsTanSetupError';
+}
+
+/** The bank rejected the request; `feedback` holds all return codes. A refused login is a `FinTsLoginRefusedError`. */
+export class FinTsBankError extends FinTsError {
+  override name = 'FinTsBankError';
+
+  /** 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) {
+    super(
+      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);
+  }
+}
+
+/**
+ * The bank refused the login, so the client sends the PIN no more: every later call that would send it fails with this
+ * error without contacting the bank, also in a client restored from the saved state, until
+ * `FinTsClient.clearLoginRefusal` takes a PIN the user has entered anew; for good where the bank has changed the login
+ * data (`FinTsLoginDataChangedError`).
+ *
+ * Banks lock the access after a few failed logins, and a return code does not always tell whether the PIN was the
+ * reason, so any error in the answer to a login refuses it, also one that ends the dialog, and so does a wrong PIN
+ * wherever the bank reports it. Only where the bank names a reason the client can take care of, another TAN method or a
+ * new customer system ID, does the same call log in once more, for each reason once. The client refuses the login
+ * itself where it could not read the answers to two logins in a row, which the bank may have counted as failed
+ * attempts; `feedback` is empty then.
+ */
+export class FinTsLoginRefusedError extends FinTsBankError {
+  override name = 'FinTsLoginRefusedError';
+}
+
+/** Wrong or blocked PIN. */
+export class FinTsPinError extends FinTsLoginRefusedError {
+  override name = '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 {
+  override name = '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, where the bank opened one, and logs in with the old data no more. 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 FinTsLoginRefusedError {
+  override name = 'FinTsLoginDataChangedError';
+
+  constructor(feedback: readonly FinTsFeedback[]) {
+    super(feedback, 'The bank has changed the login data');
+  }
+
+  /** 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);
+    return nonBlank(change?.parameters[index]);
+  }
+}
+
+/**
+ * The bank ended the dialog, for example after a timeout; the next call logs in anew. Where the bank ends the dialog
+ * in answer to a login, the call fails with `FinTsLoginRefusedError` instead.
+ */
+export class FinTsDialogAbortedError extends FinTsBankError {
+  override name = 'FinTsDialogAbortedError';
+}
+
+/** The user cancelled the TAN entry or the approval in the banking app. */
+export class FinTsTanCancelledError extends FinTsError {
+  override name = 'FinTsTanCancelledError';
+
+  constructor() {
+    super('TAN entry cancelled');
+  }
+}
+
+/**
+ * The user did not approve in the banking app in time: within the status requests the bank allows, 60 where it states
+ * none, and 10 minutes of polling at most.
+ */
+export class FinTsDecoupledTimeoutError extends FinTsError {
+  override name = 'FinTsDecoupledTimeoutError';
+
+  constructor() {
+    super('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 {
+  override name = 'FinTsStateError';
+}
+
+/** The error of whatever a closed client is asked to do. */
+export function clientClosedError(): FinTsStateError {
+  return new FinTsStateError('The FinTS client is closed');
+}
+
+/**
+ * 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);
+}
+
+/**
+ * The refusal of a login whose answer carried `feedback`: `FinTsPinError` for a rejected PIN, else
+ * `FinTsLoginDataChangedError` for new login data, also next to other errors, and `FinTsLoginRefusedError` for anything
+ * else. The same for a refusal restored from the saved state, which keeps only `feedback`.
+ *
+ * New login data end the old ones for good, so the session takes care of no other reason the answer names.
+ */
+export function loginRefusalFor(feedback: readonly FinTsFeedback[]): FinTsLoginRefusedError {
+  if (feedback.some(isPinError)) return new FinTsPinError(feedback);
+  if (hasCode(feedback, FeedbackCodes.newLoginData)) return new FinTsLoginDataChangedError(feedback);
+  return new FinTsLoginRefusedError(feedback);
+}
+
+/**
+ * Runs `parse` on data from the bank and reports malformed data as `FinTsProtocolError`, whose message leaves the data
+ * out (`FormatError`).
+ */
+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;
+  }
+}
+
+/**
+ * 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. An aborted dialog counts as a rejection: banks end the dialog along with many.
+ * A refused login and a rejected TAN fail the call: the user must hear of them.
+ */
+export async function tryLookUp<T>(lookup: () => Promise<T>): Promise<T | undefined> {
+  try {
+    return await lookup();
+  } catch (error) {
+    if (
+      !(error instanceof FinTsBankError) ||
+      error instanceof FinTsLoginRefusedError ||
+      error instanceof FinTsTanError
+    ) {
+      throw error;
+    }
+    return undefined;
+  }
+}

package/src/core/feedback.ts

@@ -0,0 +1,140 @@
+/** 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: one character per byte the bank sent (ISO
+   * 8859-1, the FinTS character set), since the client and the app send them back as they came.
+   */
+  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));
+}