@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/v3/protocol.ts

@@ -0,0 +1,331 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { Account } from '../core/account.js';
+import type { Balance } from '../core/balance.js';
+import type { MessageLogger } from '../core/client.js';
+import { requirePin, type FinTsConfig } from '../core/config.js';
+import { FinTsError, FinTsTransportError, FinTsUnsupportedError } from '../core/errors.js';
+import { hasErrors } from '../core/feedback.js';
+import type { Transaction, TransactionFormat } from '../core/transaction.js';
+import type { FinTsTransport } from '../core/transport.js';
+import { camtTransactions, mt940Transactions } from '../formats/readers.js';
+import { BankConnection, checkMessageSize } from '../session/bank-connection.js';
+import { LoginGuard } from '../session/login-guard.js';
+import { offeredVersion, requireBankParameters } from '../session/parameter-data.js';
+import {
+  balanceQuery,
+  checkBeforeSigning,
+  chooseTransactions,
+  type PinTanProtocol,
+  type Query,
+  type Synchronization,
+} from '../session/protocol.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import { invalidArgument } from '../util/errors.js';
+import { readOptionalString, type JsonObject } from '../util/json.js';
+import { decodeBankText } from '../util/text.js';
+import { FinTs3Dialog, type FinTs3DialogHost, type Signing3 } from './dialog.js';
+import { buildMessage, decodeTransport, encodeTransport, IncomingMessage3 } from './message.js';
+import { Bpd3, decodeSegments, encodeSegments, Upd3 } from './parameters.js';
+import { balanceAccount, parseBalance, parseSepaAccounts, parseTanMedia, Segments } from './segments.js';
+import { isLatin1, type Segment, type SegmentSpec } from './syntax.js';
+
+/** Customer ID the specification reserves for anonymous dialogs. */
+const anonymousCustomerId = '9999999999';
+
+/** Longest product ID (Produktbezeichnung) and product version HKVVB takes. */
+const maxProductIdLength = 25;
+const maxProductVersionLength = 5;
+
+/** A business transaction in FinTS 3.0. */
+export type FinTs3Query<T> = Query<IncomingMessage3, SegmentSpec, T>;
+
+function requireLatin1(text: string, name: string): string {
+  // The message leaves out the value, which may be the PIN.
+  if (!isLatin1(text)) throw invalidArgument(`${name} contains characters FinTS 3.0 cannot send (ISO 8859-1 only)`);
+  return text;
+}
+
+function requireMaxLength(text: string, maxLength: number, name: string): void {
+  if (text.length > maxLength) throw invalidArgument(`At most ${maxLength} characters in FinTS 3.0`, name);
+}
+
+function requireSendable(config: FinTsConfig): FinTsConfig {
+  requireLatin1(config.userId, 'userId');
+  requireLatin1(config.customerId, 'customerId');
+  requireLatin1(config.productId, 'productId');
+  requireLatin1(config.productVersion, 'productVersion');
+  // Cut short, the product would be one the bank does not know.
+  requireMaxLength(config.productId, maxProductIdLength, 'productId');
+  requireMaxLength(config.productVersion, maxProductVersionLength, 'productVersion');
+  return config;
+}
+
+/** The segments of `type` in all `pages`. */
+function all(pages: readonly IncomingMessage3[], type: string): Segment[] {
+  return pages.flatMap((p) => p.findAll(type));
+}
+
+/** FinTS 3.0 messages and business transactions (HBCI segment syntax, PIN/TAN security). */
+export class FinTs3Protocol implements PinTanProtocol<IncomingMessage3, SegmentSpec>, FinTs3DialogHost {
+  readonly config: FinTsConfig;
+  private readonly pin: string;
+  private readonly connection: BankConnection;
+  readonly loginGuard = new LoginGuard();
+
+  /** Customer system ID the bank assigned in the synchronization. */
+  systemId: string | undefined;
+  private bpd: Bpd3 | undefined;
+  private upd: Upd3 | undefined;
+
+  /**
+   * Throws `TypeError` if the PIN is empty, if the PIN or login data contain characters FinTS 3.0 cannot send (ISO
+   * 8859-1 only), or the product ID or version is longer than its field in HKVVB.
+   */
+  constructor(config: FinTsConfig, pin: string, transport?: FinTsTransport, logger?: MessageLogger) {
+    this.config = requireSendable(config);
+    this.pin = requireLatin1(requirePin(pin), 'pin');
+    this.connection = new BankConnection(config.url, transport, logger);
+  }
+
+  get bankParameters(): Bpd3 | undefined {
+    return this.bpd;
+  }
+
+  get userParameters(): Upd3 | undefined {
+    return this.upd;
+  }
+
+  /** Dialogs cannot start without the customer system ID. */
+  get synchronization(): Synchronization {
+    return this.systemId === undefined ? 'required' : 'none';
+  }
+
+  forgetSystemId(): boolean {
+    const had = this.systemId !== undefined;
+    this.systemId = undefined;
+    return had;
+  }
+
+  initSegments(systemId: string, anonymous = false): SegmentSpec[] {
+    return [
+      Segments.identification({
+        countryCode: this.config.countryCode,
+        bankCode: this.config.bankCode,
+        customerId: anonymous ? anonymousCustomerId : this.config.customerId,
+        systemId,
+        systemIdRequired: !anonymous,
+      }),
+      Segments.processingPreparation({
+        bpdVersion: this.bpd?.version ?? 0,
+        updVersion: anonymous ? 0 : (this.upd?.version ?? 0),
+        language: this.bpd?.dialogLanguage ?? 0,
+        productId: this.config.productId,
+        productVersion: this.config.productVersion,
+      }),
+    ];
+  }
+
+  async post(message: {
+    dialogId: string;
+    number: number;
+    segments: readonly SegmentSpec[];
+    signing: Signing3 | undefined;
+    tan: string | undefined;
+  }): Promise<Uint8Array> {
+    const signing = message.signing;
+    if (signing !== undefined) checkBeforeSigning(this.loginGuard, this.pin, this.bpd);
+    const outgoing = buildMessage({
+      dialogId: message.dialogId,
+      messageNumber: message.number,
+      segments: message.segments,
+      security:
+        signing === undefined
+          ? undefined
+          : {
+              countryCode: this.config.countryCode,
+              bankCode: this.config.bankCode,
+              userId: this.config.userId,
+              systemId: signing.systemId,
+              pin: this.pin,
+              securityFunction: signing.securityFunction,
+            },
+      tan: message.tan,
+    });
+    checkMessageSize(outgoing.bytes.length, this.bpd?.bankInfo.maxMessageSize);
+    this.connection.log('outgoing', () => outgoing.masked);
+    const bytes = decodeTransport(await this.connection.post(encodeTransport(outgoing.bytes), 'text/plain'));
+    this.connection.log('incoming', () => decodeBankText(bytes));
+    return bytes;
+  }
+
+  keepParameterData(response: IncomingMessage3): void {
+    this.keepBankParameters(response);
+    this.upd = Upd3.fromSegments(response.segments, this.config.bankCode, this.config.countryCode) ?? this.upd;
+    this.systemId = response.find('HISYN')?.text(1) ?? this.systemId;
+  }
+
+  private keepBankParameters(response: IncomingMessage3): void {
+    this.bpd = Bpd3.fromSegments(response.segments, this.config.bankCode) ?? this.bpd;
+  }
+
+  /** Keeps the bank parameter data of an anonymous dialog, and nothing that belongs to a user. */
+  async fetchBankParametersAnonymously(): Promise<IncomingMessage3> {
+    const response = await this.requestBankParametersAnonymously();
+    this.keepBankParameters(response);
+    return response;
+  }
+
+  /**
+   * Asks for the bank parameter data in an anonymous dialog that announces strong customer authentication; a bank that
+   * rejects the announcement, with a return code or by failing on it, is asked again without it.
+   *
+   * A timeout or a broken connection is not a reason to ask again: it would only double the wait.
+   */
+  private async requestBankParametersAnonymously(): Promise<IncomingMessage3> {
+    let announced: IncomingMessage3;
+    try {
+      announced = await this.anonymousDialog(true);
+    } catch (error) {
+      if (error instanceof FinTsTransportError && error.statusCode === undefined) throw error;
+      if (!(error instanceof FinTsError)) throw error;
+      return this.anonymousDialog(false);
+    }
+    if (!hasErrors(announced.feedback) || announced.find('HIBPA') !== undefined) return announced;
+    return this.anonymousDialog(false);
+  }
+
+  private async anonymousDialog(announceSca: boolean): Promise<IncomingMessage3> {
+    const dialog = FinTs3Dialog.anonymous(this);
+    try {
+      return await dialog.requestBankParameters(announceSca);
+    } finally {
+      await dialog.end();
+    }
+  }
+
+  newDialog(method: TanMethod, tanMedium?: string): FinTs3Dialog {
+    return FinTs3Dialog.signed(this, method, tanMedium);
+  }
+
+  combine(first: IncomingMessage3, second: IncomingMessage3): IncomingMessage3 {
+    return IncomingMessage3.combine(first, second);
+  }
+
+  // --- Business transactions ---
+
+  private version(
+    transaction: string,
+    implemented: readonly number[],
+    options: { account?: Account; requiresEntry?: boolean } = {},
+  ): number | undefined {
+    return offeredVersion(this.bpd, this.upd, transaction, new Set(implemented), options);
+  }
+
+  tanMedia(): FinTs3Query<TanMedium[]> | undefined {
+    const version = this.version('HKTAB', [4, 5]);
+    if (version === undefined) return undefined;
+    return {
+      order: () => Segments.tanMedia(version),
+      read: (pages) => all(pages, 'HITAB').flatMap(parseTanMedia),
+    };
+  }
+
+  sepaAccounts(): FinTs3Query<Account[]> | undefined {
+    const version = this.version('HKSPA', [1, 2, 3], { requiresEntry: true });
+    if (version === undefined) return undefined;
+    return {
+      order: (continuation) => Segments.sepaAccounts(version, continuation),
+      read: (pages) =>
+        all(pages, 'HISPA').flatMap((s) => parseSepaAccounts(s, this.config.countryCode, this.config.bankCode)),
+    };
+  }
+
+  balance(account: Account): FinTs3Query<Balance> {
+    const version = this.version('HKSAL', [6, 7, 8], { account });
+    if (version === undefined) {
+      throw new FinTsUnsupportedError('The bank reports no balance (HKSAL) for this account');
+    }
+    return balanceQuery<IncomingMessage3, SegmentSpec, Segment>(account, {
+      order: (continuation) => Segments.balance(version, account, continuation),
+      records: (pages) => all(pages, 'HISAL'),
+      accountOf: balanceAccount,
+      read: parseBalance,
+    });
+  }
+
+  transactions(
+    account: Account,
+    format: TransactionFormat,
+    from: Date | undefined,
+    to: Date | undefined,
+  ): FinTs3Query<Transaction[]> {
+    const request = chooseTransactions(format, account, this.upd, {
+      camt: { name: 'HKCAZ', version: this.version('HKCAZ', [1], { account }) },
+      camtFormats: requireBankParameters(this.bpd).camtFormats,
+      mt940: { name: 'HKKAZ', version: this.version('HKKAZ', [6, 7], { account }) },
+    });
+    const version = request.version;
+    if (request.camt) {
+      return {
+        order: (continuation) =>
+          Segments.transactionsCamt(version, account, request.camtFormats, { from, to, continuation }),
+        // The third element group holds the booked documents, the fourth element the pending one.
+        read: (pages) =>
+          camtTransactions(
+            all(pages, 'HICAZ').flatMap((s) =>
+              s
+                .group(3)
+                .filter((d) => !d.isEmpty)
+                .map((d) => d.bytes),
+            ),
+            all(pages, 'HICAZ')
+              .map((s) => s.binary(4))
+              .filter((d) => d !== undefined),
+          ),
+      };
+    }
+    return {
+      order: (continuation) => Segments.transactionsMt940(version, account, { from, to, continuation }),
+      // The first element holds the booked transactions, the second the pending ones.
+      read: (pages) =>
+        mt940Transactions(
+          all(pages, 'HIKAZ')
+            .map((s) => s.binary(1))
+            .filter((d) => d !== undefined),
+          all(pages, 'HIKAZ')
+            .map((s) => s.binary(2))
+            .filter((d) => d !== undefined),
+          request.currency,
+        ),
+    };
+  }
+
+  // --- Saved state ---
+
+  saveState(): JsonObject {
+    return {
+      systemId: this.systemId ?? null,
+      bpd: this.bpd === undefined ? null : encodeSegments(this.bpd.segments),
+      upd: this.upd === undefined ? null : encodeSegments(this.upd.segments),
+    };
+  }
+
+  restoreState(saved: JsonObject): void {
+    const bpd = readOptionalString(saved, 'bpd');
+    const upd = readOptionalString(saved, 'upd');
+    const restoredSystemId = readOptionalString(saved, 'systemId');
+    const restoredBpd = bpd === undefined ? undefined : Bpd3.fromSegments(decodeSegments(bpd), this.config.bankCode);
+    const restoredUpd =
+      upd === undefined
+        ? undefined
+        : Upd3.fromSegments(decodeSegments(upd), this.config.bankCode, this.config.countryCode);
+    this.systemId = restoredSystemId;
+    this.bpd = restoredBpd;
+    this.upd = restoredUpd;
+  }
+
+  close(): void {
+    this.connection.close();
+  }
+}

package/src/v3/segments.ts

@@ -0,0 +1,331 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { Account } from '../core/account.js';
+import { Amount, withMark } from '../core/amount.js';
+import { Balance } from '../core/balance.js';
+import { noReference } from '../session/protocol.js';
+import { TanMedium, tanMediumStatusOf } from '../tan/tan-models.js';
+import { formatFintsDate, parseFintsDate, parseFintsDateTime } from '../util/dates.js';
+import { FormatError } from '../util/errors.js';
+import { type Segment, SegmentSpec, type SegmentValue } from './syntax.js';
+
+/** Bank identification (KIK): country code and bank code. */
+export function bankIdentification(countryCode: string, bankCode: string): SegmentValue {
+  return [countryCode, bankCode];
+}
+
+/** National account (KTV): account number, sub-account and bank identification. */
+export function nationalAccount(a: Account): SegmentValue[] {
+  return [a.accountNumber, a.subAccount, a.countryCode, a.bankCode];
+}
+
+/** International account (KTI): IBAN, BIC, then the national account. */
+export function internationalAccount(a: Account): SegmentValue[] {
+  return [a.iban, a.bic, ...nationalAccount(a)];
+}
+
+function dateOrEmpty(date: Date | undefined): string | undefined {
+  return date === undefined ? undefined : formatFintsDate(date);
+}
+
+// HKTAN fields: order reference (Auftragsreferenz), "more TANs follow" and the TAN medium name.
+const orderReferenceField = 5;
+const moreTansField = 6;
+const tanMediumField = 11;
+
+/** Builders for the request segments the client sends. */
+export const Segments = Object.freeze({
+  /** HKIDN: who is logging in, from which customer system. */
+  identification(parts: {
+    countryCode: string;
+    bankCode: string;
+    customerId: string;
+    systemId: string;
+    systemIdRequired: boolean;
+  }): SegmentSpec {
+    return new SegmentSpec('HKIDN', 2, [
+      bankIdentification(parts.countryCode, parts.bankCode),
+      parts.customerId,
+      parts.systemId,
+      parts.systemIdRequired ? 1 : 0,
+    ]);
+  },
+
+  /** HKVVB: the parameter data versions the client knows, the dialog language and the registered product. */
+  processingPreparation(parts: {
+    bpdVersion: number;
+    updVersion: number;
+    language: number;
+    productId: string;
+    productVersion: string;
+  }): SegmentSpec {
+    return new SegmentSpec('HKVVB', 3, [
+      parts.bpdVersion,
+      parts.updVersion,
+      parts.language,
+      parts.productId,
+      parts.productVersion,
+    ]);
+  },
+
+  /** HKSYN: requests a new customer system ID. */
+  synchronization(): SegmentSpec {
+    return new SegmentSpec('HKSYN', 3, [0]);
+  },
+
+  dialogEnd(dialogId: string): SegmentSpec {
+    return new SegmentSpec('HKEND', 1, [dialogId]);
+  },
+
+  /** HKTAN process 4: asks for strong customer authentication of the `segmentType` sent in the same message. */
+  tanProcess4(version: number, segmentType: string, mediumName?: string): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, { 1: '4', 2: segmentType, [tanMediumField]: mediumName });
+  },
+
+  /** HKTAN process 2: submits the TAN (carried in the signature) for the order with `reference`. */
+  tanProcess2(version: number, reference: string): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, { 1: '2', [orderReferenceField]: reference, [moreTansField]: false });
+  },
+
+  /** HKTAN process S: asks whether the order with `reference` was approved in the banking app. */
+  tanProcessStatus(version: number, reference: string): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, { 1: 'S', [orderReferenceField]: reference, [moreTansField]: false });
+  },
+
+  /** HKSAL: the balance of one account (not of all accounts). */
+  balance(version: number, account: Account, continuation?: string): SegmentSpec {
+    return new SegmentSpec('HKSAL', version, [
+      version >= 7 ? internationalAccount(account) : nationalAccount(account),
+      false,
+      null,
+      continuation,
+    ]);
+  },
+
+  /** HKKAZ: MT940 transactions of one account. */
+  transactionsMt940(
+    version: number,
+    account: Account,
+    period: { from?: Date | undefined; to?: Date | undefined; continuation?: string | undefined },
+  ): SegmentSpec {
+    return new SegmentSpec('HKKAZ', version, [
+      version >= 7 ? internationalAccount(account) : nationalAccount(account),
+      false,
+      dateOrEmpty(period.from),
+      dateOrEmpty(period.to),
+      null,
+      period.continuation,
+    ]);
+  },
+
+  /** HKCAZ: camt transactions of one account in one of `formats`. */
+  transactionsCamt(
+    version: number,
+    account: Account,
+    formats: readonly string[],
+    period: { from?: Date | undefined; to?: Date | undefined; continuation?: string | undefined },
+  ): SegmentSpec {
+    return new SegmentSpec('HKCAZ', version, [
+      internationalAccount(account),
+      formats,
+      false,
+      dateOrEmpty(period.from),
+      dateOrEmpty(period.to),
+      null,
+      period.continuation,
+    ]);
+  },
+
+  /** HKSPA: IBAN and BIC of all accounts. */
+  sepaAccounts(version: number, continuation?: string): SegmentSpec {
+    return new SegmentSpec('HKSPA', version, [null, ...(version >= 2 ? [null, continuation] : [])]);
+  },
+
+  /** HKTAB: all TAN media of all classes. */
+  tanMedia(version: number): SegmentSpec {
+    return new SegmentSpec('HKTAB', version, [0, 'A']);
+  },
+});
+
+/** Positions of the data elements in the TAN part of a response (HITAN versions 6 and 7), after the segment header. */
+const Hitan = { process: 1, reference: 3, challenge: 4, hhdUc: 5, validUntil: 6, mediumName: 7 } as const;
+
+/** The TAN part of a response (HITAN). */
+export class TanResponse {
+  constructor(
+    /** The TAN process the segment answers: `4` asks for an approval, `S` answers a status request. */
+    readonly process: string | undefined,
+    readonly reference: string | undefined,
+    readonly challenge: string | undefined,
+    readonly hhdUc: Uint8Array | undefined,
+    readonly validUntil: Date | undefined,
+    readonly mediumName: string | undefined,
+  ) {}
+
+  static parse(s: Segment): TanResponse {
+    return new TanResponse(
+      s.text(Hitan.process),
+      s.text(Hitan.reference),
+      s.text(Hitan.challenge),
+      s.binary(Hitan.hhdUc),
+      parseFintsDateTime(s.text(Hitan.validUntil, 0), s.text(Hitan.validUntil, 1)),
+      s.text(Hitan.mediumName),
+    );
+  }
+
+  /** Whether the bank needs no approval although it answered with a TAN segment. */
+  get isDummy(): boolean {
+    return this.reference === undefined || this.reference === noReference;
+  }
+}
+
+/** Positions of the data elements in a balance (HISAL), after the segment header. */
+const Hisal = {
+  account: 1,
+  productName: 2,
+  accountCurrency: 3,
+  bookedBalance: 4,
+  pendingBalance: 5,
+  creditLine: 6,
+  availableAmount: 7,
+  usedAmount: 8,
+  overdraft: 9,
+  bookingTime: 10,
+} as const;
+
+/** Positions inside a balance (SDO): credit/debit mark, value, currency, date and time. */
+const Sdo = { mark: 0, value: 1, currency: 2, date: 3, time: 4 } as const;
+
+/** An amount with currency (BTG) at `index`, or `undefined` if empty. */
+function amountAt(s: Segment, index: number, fallbackCurrency: string): Amount | undefined {
+  const value = s.text(index, 0);
+  if (value === undefined) return undefined;
+  return Amount.parseDecimal(value, s.text(index, 1) ?? fallbackCurrency);
+}
+
+/**
+ * Parses a balance (HISAL); throws `FormatError` if the booked balance is missing or malformed, or a balance has no
+ * credit/debit mark.
+ */
+export function parseBalance(s: Segment, account: Account): Balance {
+  const currency = s.text(Hisal.accountCurrency) ?? account.currency;
+  const signedBalance = (index: number): Amount | undefined => {
+    const value = s.text(index, Sdo.value);
+    if (value === undefined) return undefined;
+    const amountCurrency = s.text(index, Sdo.currency) ?? currency;
+    if (amountCurrency === undefined) throw new FormatError('Balance without currency');
+    return withMark(Amount.parseDecimal(value, amountCurrency), s.text(index, Sdo.mark), 'C', 'D');
+  };
+
+  const booked = signedBalance(Hisal.bookedBalance);
+  if (booked === undefined) throw new FormatError('Balance without booked amount');
+  const bookedDate = s.text(Hisal.bookedBalance, Sdo.date);
+  const bookedAsOf = parseFintsDate(bookedDate);
+  if (bookedAsOf === undefined) throw new FormatError('Balance without date');
+  return new Balance({
+    account,
+    productName: s.text(Hisal.productName),
+    booked,
+    bookedAsOf,
+    bookedAsOfTime: parseFintsDateTime(bookedDate, s.text(Hisal.bookedBalance, Sdo.time)),
+    pending: signedBalance(Hisal.pendingBalance),
+    creditLine: amountAt(s, Hisal.creditLine, booked.currency),
+    available: amountAt(s, Hisal.availableAmount, booked.currency),
+    used: amountAt(s, Hisal.usedAmount, booked.currency),
+    overdraft: amountAt(s, Hisal.overdraft, booked.currency),
+    bookingDate: parseFintsDate(s.text(Hisal.bookingTime, 0)),
+    bookingTime: parseFintsDateTime(s.text(Hisal.bookingTime, 0), s.text(Hisal.bookingTime, 1)),
+  });
+}
+
+/**
+ * The account a balance (HISAL) belongs to: international (IBAN, BIC, then national) from version 7, national before.
+ */
+export function balanceAccount(s: Segment): Account {
+  const fields = s.texts(Hisal.account);
+  const international = s.version >= 7;
+  const national = international ? 2 : 0;
+  return new Account({
+    iban: international ? fields[0] : undefined,
+    bic: international ? fields[1] : undefined,
+    accountNumber: fields[national],
+    subAccount: fields[national + 1],
+    countryCode: fields[national + 2] ?? '',
+    bankCode: fields[national + 3] ?? '',
+  });
+}
+
+/** Positions inside an account of the SEPA account list (HISPA "Kontoverbindung SEPA"). */
+const Hispa = {
+  isSepaAccount: 0,
+  iban: 1,
+  bic: 2,
+  accountNumber: 3,
+  subAccount: 4,
+  countryCode: 5,
+  bankCode: 6,
+} as const;
+
+/**
+ * Parses the SEPA account list (HISPA), one account per data element. An account the bank marks as no payment account
+ * ("Kontoverwendung SEPA" N) is left out: it has no SEPA connection.
+ */
+export function parseSepaAccounts(s: Segment, defaultCountry: string, defaultBank: string): Account[] {
+  const accounts: Account[] = [];
+  for (let i = 1; i < s.length; i++) {
+    if (s.text(i, Hispa.isSepaAccount) === 'N') continue;
+    if (s.text(i, Hispa.iban) === undefined && s.text(i, Hispa.accountNumber) === undefined) continue;
+    accounts.push(
+      new Account({
+        iban: s.text(i, Hispa.iban),
+        bic: s.text(i, Hispa.bic),
+        accountNumber: s.text(i, Hispa.accountNumber),
+        subAccount: s.text(i, Hispa.subAccount),
+        countryCode: s.text(i, Hispa.countryCode) ?? defaultCountry,
+        bankCode: s.text(i, Hispa.bankCode) ?? defaultBank,
+      }),
+    );
+  }
+  return accounts;
+}
+
+/**
+ * Elements of the account a TAN medium belongs to, a national account (`ktv`: account number, sub-account, country
+ * code, bank code), which shifts every field behind it.
+ */
+const accountWidth = 4;
+
+/** Parses the TAN media list (HITAB versions 4 and 5, PIN/TAN "TAN-Medium-Liste"). */
+export function parseTanMedia(s: Segment): TanMedium[] {
+  // Version 5 adds the security function in front of the card number.
+  const version5 = s.version >= 5;
+  const cardNumber = version5 ? 3 : 2;
+  // The card number, card sequence number and card type are followed by the account. Behind it come: valid from, valid
+  // until, TAN list number, name, masked and full mobile number, SMS charge account (six elements), number of free TANs,
+  // last use, activation.
+  const after = cardNumber + 3 + accountWidth;
+  const media: TanMedium[] = [];
+  // The first data element is the TAN usage option; the media follow.
+  for (let i = 2; i < s.length; i++) {
+    const fields = s.texts(i);
+    const mediumClass = fields[0];
+    if (mediumClass === undefined) continue;
+    media.push(
+      new TanMedium({
+        mediumClass,
+        status: tanMediumStatusOf(fields[1]),
+        securityFunction: version5 ? fields[2] : undefined,
+        cardNumber: fields[cardNumber],
+        cardSequenceNumber: fields[cardNumber + 1],
+        validFrom: parseFintsDate(fields[after]),
+        validUntil: parseFintsDate(fields[after + 1]),
+        name: fields[after + 3],
+        mobileNumberMasked: fields[after + 4],
+        mobileNumber: fields[after + 5],
+        lastUsed: parseFintsDate(fields[after + 13]),
+        activatedOn: parseFintsDate(fields[after + 14]),
+      }),
+    );
+  }
+  return media;
+}