@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/v3/parameters.ts

@@ -0,0 +1,524 @@
+// 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 type { Balance } from '../core/balance.js';
+import { BankInfo } from '../core/bank-info.js';
+import { FinTsProtocolError } from '../core/errors.js';
+import { TanMethod, tanMediumRequirementOf } from '../tan/tan-models.js';
+import { base64Decode, base64Encode, concatBytes } from '../util/bytes.js';
+import { nonBlank, tryParseInt } from '../util/text.js';
+import { AccountExtension } from './account-extension.js';
+import { parseSegments, type Segment } from './syntax.js';
+
+/**
+ * A two-step TAN method as HITANS describes it: whether the client can run it, and the HITANS version, which is the
+ * version of the HKTAN segments the method is used with.
+ */
+interface OfferedMethod {
+  readonly method: TanMethod;
+  readonly runnable: boolean;
+  readonly version: number;
+}
+
+/** Positions of the data elements in the header of the bank parameter data (HIBPA), after the segment header. */
+const Hibpa = {
+  version: 1,
+  /** Country code, then bank code. */
+  bankId: 2,
+  bankName: 3,
+  languages: 5,
+  fintsVersions: 6,
+  maxMessageSize: 7,
+  minTimeout: 8,
+  maxTimeout: 9,
+} as const;
+
+/**
+ * The data element of every parameter segment (`HI…S`) that holds its specific parameters, after the maximum number of
+ * orders, the minimum number of signatures and the security class.
+ */
+const parameterGroup = 4;
+
+/** The standard language in the communication access (HIKOM). */
+const hikomStandardLanguage = 2;
+
+function defined<T>(values: readonly (T | undefined)[]): T[] {
+  return values.filter((v): v is T => v !== undefined);
+}
+
+/** `bpd`, or `FinTsProtocolError` if the bank has not sent its parameter data yet. */
+export function requireBankParameters(bpd: Bpd3 | undefined): Bpd3 {
+  if (bpd === undefined) throw new FinTsProtocolError('No bank parameter data available');
+  return bpd;
+}
+
+/** FinTS 3.0 bank parameter data (BPD): HIBPA and the parameter segments (`HI…S`), parsed once. */
+export class Bpd3 {
+  readonly bankInfo: BankInfo;
+
+  /** The two-step TAN methods of HITANS versions 6 and 7, by security function. */
+  private readonly offeredMethods: ReadonlyMap<string, OfferedMethod>;
+
+  /** Two-step TAN methods the bank offers and the client can run. */
+  readonly tanMethods: readonly TanMethod[];
+
+  /** Security functions of the two-step methods the bank offers in a form the client cannot run. */
+  readonly unsupportedTanMethods: readonly string[];
+  readonly pinTan: PinTanParameters;
+
+  /** camt formats the bank offers for HKCAZ. */
+  readonly camtFormats: readonly string[];
+
+  /** Versions of each parameter segment, by segment type. */
+  private readonly versions: ReadonlyMap<string, ReadonlySet<number>>;
+
+  /**
+   * The dialog language HKVVB names: the bank's standard language (HIKOM), else the first it supports (HIBPA). Only
+   * these may be sent once the parameter data are known; `0`, the default, only before (Formals C.3.1.3).
+   */
+  readonly dialogLanguage: number;
+
+  private encodedValue: string | undefined;
+
+  private constructor(
+    readonly segments: readonly Segment[],
+    hibpa: Segment,
+    fallbackBankCode: string,
+  ) {
+    this.bankInfo = new BankInfo({
+      bankCode: hibpa.text(Hibpa.bankId, 1) ?? fallbackBankCode,
+      name: hibpa.text(Hibpa.bankName),
+      bpdVersion: hibpa.integer(Hibpa.version) ?? 0,
+      languages: defined(hibpa.texts(Hibpa.languages)),
+      supportedVersions: defined(hibpa.texts(Hibpa.fintsVersions)),
+      maxMessageSize: hibpa.integer(Hibpa.maxMessageSize),
+      minTimeout: hibpa.integer(Hibpa.minTimeout),
+      maxTimeout: hibpa.integer(Hibpa.maxTimeout),
+    });
+    this.offeredMethods = parseTanMethods(segments);
+    const offered = [...this.offeredMethods.values()];
+    this.tanMethods = Object.freeze(offered.filter((o) => o.runnable).map((o) => o.method));
+    this.unsupportedTanMethods = Object.freeze(
+      offered.filter((o) => !o.runnable).map((o) => o.method.securityFunction),
+    );
+    this.pinTan = PinTanParameters.parse(segments);
+    this.camtFormats = segments
+      .filter((s) => s.type === 'HICAZS')
+      .flatMap((s) => defined(s.texts(parameterGroup)))
+      .filter((format) => format.includes('camt'));
+    this.versions = versionsByType(segments);
+    this.dialogLanguage = dialogLanguageOf(segments, this.bankInfo);
+  }
+
+  /** The version of the parameter data, which the client reports back so that the bank sends newer ones only. */
+  get version(): number {
+    return this.bankInfo.bpdVersion;
+  }
+
+  /** The segments as the saved state keeps them, encoded once. */
+  get encoded(): string {
+    return (this.encodedValue ??= encodeSegments(this.segments));
+  }
+
+  /** The BPD in `all`, or `undefined` if they contain no HIBPA segment. */
+  static fromSegments(all: readonly Segment[], fallbackBankCode: string): Bpd3 | undefined {
+    const segments = all.filter(isParameterSegment);
+    const hibpa = segments.find((s) => s.type === 'HIBPA');
+    return hibpa === undefined ? undefined : new Bpd3(segments, hibpa, fallbackBankCode);
+  }
+
+  /** The parameter segment type of a business transaction: `HKSAL` → `HISALS`. */
+  static parameterName(transaction: string): string {
+    return `HI${transaction.substring(2)}S`;
+  }
+
+  /** The highest version of `transaction` that the bank offers and the client `implemented`. */
+  bestVersion(transaction: string, implemented: ReadonlySet<number>): number | undefined {
+    let best: number | undefined;
+    for (const version of this.versions.get(Bpd3.parameterName(transaction)) ?? []) {
+      if (implemented.has(version) && (best === undefined || version > best)) best = version;
+    }
+    return best;
+  }
+
+  /** The version of the HKTAN segments that go with `method`; `undefined` for a method the bank does not offer. */
+  tanVersion(method: TanMethod): number | undefined {
+    return this.offeredMethods.get(method.securityFunction)?.version;
+  }
+}
+
+function dialogLanguageOf(segments: readonly Segment[], bankInfo: BankInfo): number {
+  const languages = new Set([1, 2, 3]);
+  const standard = segments.find((s) => s.type === 'HIKOM')?.integer(hikomStandardLanguage);
+  if (standard !== undefined && languages.has(standard)) return standard;
+  return bankInfo.languages.map((l) => tryParseInt(l)).find((l) => l !== undefined && languages.has(l)) ?? 0;
+}
+
+function isParameterSegment(s: Segment): boolean {
+  const type = s.type;
+  if (['HIBPA', 'HIKOM', 'HISHV', 'HIKPV'].includes(type)) return true;
+  if (type === 'HIRMS' || type === 'HIRMG') return false;
+  return type.length >= 5 && (type.startsWith('HI') || type.startsWith('DI')) && type.endsWith('S');
+}
+
+function versionsByType(segments: readonly Segment[]): Map<string, Set<number>> {
+  const versions = new Map<string, Set<number>>();
+  for (const s of segments) {
+    let set = versions.get(s.type);
+    if (set === undefined) versions.set(s.type, (set = new Set()));
+    set.add(s.version);
+  }
+  return versions;
+}
+
+/** Parses the two-step TAN methods from HITANS versions 6 and 7; for a method offered in several, the highest wins. */
+function parseTanMethods(segments: readonly Segment[]): Map<string, OfferedMethod> {
+  const byCode = new Map<string, OfferedMethod>();
+  for (const s of segments.filter((s) => s.type === 'HITANS')) {
+    for (const offered of parseHitans(s)) {
+      const existing = byCode.get(offered.method.securityFunction);
+      if (existing === undefined || offered.version > existing.version) {
+        byCode.set(offered.method.securityFunction, offered);
+      }
+    }
+  }
+  return byCode;
+}
+
+/** The fields describing one TAN method in HITANS, in order; version 6 ends with `activeMediaCount`. */
+const HitansField = {
+  securityFunction: 0,
+  processVariant: 1,
+  technicalId: 2,
+  dkMethod: 3,
+  dkVersion: 4,
+  name: 5,
+  maxTanLength: 6,
+  tanFormat: 7,
+  returnValueText: 8,
+  /** "Maximale Länge des Rückgabewertes": the return value is the challenge. */
+  maxChallengeLength: 9,
+  multipleTans: 10,
+  tanTimeAndDialogRelation: 11,
+  orderCancellation: 12,
+  smsChargeAccountRequired: 13,
+  orderingAccountRequired: 14,
+  challengeClassRequired: 15,
+  structuredChallenge: 16,
+  initializationMode: 17,
+  mediumNameRequired: 18,
+  hhdUcRequired: 19,
+  activeMediaCount: 20,
+  maxStatusPolls: 21,
+  firstPollDelay: 22,
+  pollInterval: 23,
+  manualConfirmation: 24,
+  automaticPolling: 25,
+} as const;
+
+function parseHitans(s: Segment): OfferedMethod[] {
+  const version = s.version;
+  if (version !== 6 && version !== 7) return [];
+  // Version 7 adds the fields for decoupled approval.
+  const fieldsPerMethod = version === 6 ? HitansField.activeMediaCount + 1 : HitansField.automaticPolling + 1;
+  const all = s.texts(parameterGroup);
+  const methods: OfferedMethod[] = [];
+  // The group starts with three general fields, then lists the methods.
+  for (let start = 3; start < all.length; start += fieldsPerMethod) {
+    const fields = all.slice(start, start + fieldsPerMethod);
+    const field = (f: number): string | undefined => fields[f];
+    const number = (f: number): number | undefined => tryParseInt(field(f));
+    const code = field(HitansField.securityFunction);
+    if (code === undefined) continue;
+    // Process variant 1 needs the order hash and another message flow; the client runs variant 2, the one of PSD2
+    // strong customer authentication. An SMS charge account or an HHD_UC answer, where required, it cannot send.
+    const runnable =
+      number(HitansField.processVariant) !== 1 &&
+      field(HitansField.smsChargeAccountRequired) !== '2' &&
+      field(HitansField.hhdUcRequired) !== 'J';
+    const dkMethod = field(HitansField.dkMethod);
+    const decoupledFields = version === 7;
+    const method = new TanMethod({
+      securityFunction: code,
+      technicalId: field(HitansField.technicalId),
+      dkMethod,
+      dkVersion: field(HitansField.dkVersion),
+      name: field(HitansField.name) ?? code,
+      maxTanLength: number(HitansField.maxTanLength),
+      numericTan: field(HitansField.tanFormat) !== '2',
+      returnValueText: field(HitansField.returnValueText),
+      maxChallengeLength: number(HitansField.maxChallengeLength),
+      structuredChallenge: field(HitansField.structuredChallenge) === 'J',
+      mediumRequirement: tanMediumRequirementOf(field(HitansField.mediumNameRequired)),
+      activeMediaCount: number(HitansField.activeMediaCount),
+      decoupled: decoupledFields && dkMethod !== undefined && dkMethod.toLowerCase().startsWith('decoupled'),
+      decoupledMaxPolls: decoupledFields ? number(HitansField.maxStatusPolls) : undefined,
+      decoupledFirstPollDelaySeconds: decoupledFields ? number(HitansField.firstPollDelay) : undefined,
+      decoupledPollIntervalSeconds: decoupledFields ? number(HitansField.pollInterval) : undefined,
+      decoupledManualConfirmation: !decoupledFields || field(HitansField.manualConfirmation) !== 'N',
+      decoupledAutomaticPolling: !decoupledFields || field(HitansField.automaticPolling) !== 'N',
+    });
+    methods.push({ method, runnable, version });
+  }
+  return methods;
+}
+
+/**
+ * PIN/TAN parameters (HIPINS): the PIN length, which business transactions PIN/TAN allows, and which of them need a
+ * TAN.
+ */
+export class PinTanParameters {
+  private constructor(
+    private readonly tanRequired: ReadonlyMap<string, boolean>,
+    /** The shortest and longest PIN the bank takes. */
+    readonly pinLength: { min: number | undefined; max: number | undefined },
+  ) {}
+
+  /** Reads the HIPINS segment of the highest version. */
+  static parse(segments: readonly Segment[]): PinTanParameters {
+    let hipins: Segment | undefined;
+    for (const s of segments.filter((s) => s.type === 'HIPINS')) {
+      if (hipins === undefined || s.version > hipins.version) hipins = s;
+    }
+    if (hipins === undefined) return new PinTanParameters(new Map(), { min: undefined, max: undefined });
+    const fields = hipins.texts(parameterGroup);
+    const tanRequired = new Map<string, boolean>();
+    // Five general fields, the PIN lengths first; then pairs of segment type and TAN flag.
+    for (let i = 5; i + 1 < fields.length; i += 2) {
+      const type = fields[i];
+      if (type !== undefined) tanRequired.set(type, fields[i + 1] === 'J');
+    }
+    return new PinTanParameters(tanRequired, { min: tryParseInt(fields[0]), max: tryParseInt(fields[1]) });
+  }
+
+  /** Whether the bank wants a TAN for the business transaction of `segmentType`, such as `HKKAZ`. */
+  requiresTan(segmentType: string): boolean {
+    return this.tanRequired.get(segmentType) ?? false;
+  }
+
+  /** Whether PIN/TAN allows `segmentType` at all: HIPINS lists it, or lists no business transactions (PIN/TAN B.8.1). */
+  allowsWithPinTan(segmentType: string): boolean {
+    return this.tanRequired.size === 0 || this.tanRequired.has(segmentType);
+  }
+}
+
+interface UpdEntry {
+  readonly account: Account;
+  readonly extension: AccountExtension | undefined;
+}
+
+/** The user ID (Benutzerkennung), the version and the usage ("UPD-Verwendung") of the user parameter data in HIUPA. */
+const hiupaUserId = 1;
+const hiupaVersion = 2;
+const hiupaUsage = 3;
+
+/** Business transaction codes such as `HKSAL` or `DKPAE`. */
+const transactionCode = /^[A-Z]{4,6}$/;
+
+/** FinTS 3.0 user parameter data (UPD): HIUPA and the accounts (HIUPD), parsed once. */
+export class Upd3 {
+  /** The user the bank sent them for; `undefined` where it names none. */
+  readonly userId: string | undefined;
+
+  /** The version of the parameter data, which the client reports back so that the bank sends newer ones only. */
+  readonly version: number;
+
+  /**
+   * Whether the lists of permitted transactions are complete: the bank permits nothing they leave out ("UPD-Verwendung"
+   * 0).
+   */
+  readonly listsAllTransactions: boolean;
+
+  /** The transactions any entry lists as permitted, with or without an account. */
+  readonly listedTransactions: ReadonlySet<string>;
+
+  /** The accounts with the extension each carries, where it does. */
+  private readonly entries: readonly UpdEntry[];
+
+  /** The accounts the user may access. */
+  readonly accounts: readonly Account[];
+
+  private encodedValue: string | undefined;
+
+  /** `listsAll` tells whether HIUPA declares the lists of permitted transactions complete ("UPD-Verwendung" 0). */
+  private constructor(
+    readonly segments: readonly Segment[],
+    hiupa: Segment,
+    listsAll: boolean,
+    defaultBankCode: string,
+    defaultCountry: string,
+  ) {
+    const hiupds = segments.filter((s) => s.type === 'HIUPD');
+    this.userId = hiupa.text(hiupaUserId)?.trim();
+    this.version = hiupa.integer(hiupaVersion) ?? 0;
+    this.listsAllTransactions = listsAll;
+    this.listedTransactions = new Set(hiupds.flatMap(transactionsOf));
+    this.entries = Object.freeze(
+      hiupds.map((s) => entryOf(s, defaultBankCode, defaultCountry, listsAll)).filter((e) => e !== undefined),
+    );
+    this.accounts = Object.freeze(this.entries.map((e) => e.account));
+  }
+
+  /** The segments as the saved state keeps them, encoded once. */
+  get encoded(): string {
+    return (this.encodedValue ??= encodeSegments(this.segments));
+  }
+
+  /**
+   * The balance of `account` the user parameter data carry, where it holds all a balance query would deliver, so that
+   * the client asks for none (Formals E.3.1, F.3.2); `undefined` otherwise.
+   */
+  completeBalance(account: Account): Balance | undefined {
+    return this.entries.find((e) => e.account.matches(account))?.extension?.completeBalance(account);
+  }
+
+  /** The UPD in `all`, or `undefined` if they contain no HIUPA segment. */
+  static fromSegments(all: readonly Segment[], defaultBankCode: string, defaultCountry: string): Upd3 | undefined {
+    const segments = all.filter((s) => s.type === 'HIUPA' || s.type === 'HIUPD');
+    const hiupa = segments.find((s) => s.type === 'HIUPA');
+    if (hiupa === undefined) return undefined;
+    return new Upd3(segments, hiupa, hiupa.text(hiupaUsage) === '0', defaultBankCode, defaultCountry);
+  }
+}
+
+/**
+ * The data element where the permitted transactions start, by HIUPD version: version 6 inserts the IBAN, version 5 the
+ * account type.
+ */
+function allowedFrom(version: number): number {
+  return version >= 6 ? 10 : version === 5 ? 9 : 8;
+}
+
+/** The permitted transactions of the HIUPD `s`. */
+function transactionsOf(s: Segment): string[] {
+  const codes: string[] = [];
+  for (let i = allowedFrom(s.version); i < s.length; i++) {
+    const code = s.text(i, 0);
+    if (code !== undefined && transactionCode.test(code)) codes.push(code);
+  }
+  return codes;
+}
+
+/**
+ * The account extension of `s` (version 6, "Erweiterung, kontobezogen"): the JSON object behind the permitted
+ * transactions, whose count varies. A bank that leaves its colons unescaped splits it into group elements, which are
+ * joined again.
+ */
+function extensionOf(s: Segment): AccountExtension | undefined {
+  if (s.version < 6) return undefined;
+  for (let i = allowedFrom(s.version); i < s.length; i++) {
+    const text = s
+      .group(i)
+      .map((e) => e.text)
+      .join(':');
+    if (text.trimStart().startsWith('{')) return AccountExtension.tryParse(text);
+  }
+  return undefined;
+}
+
+function entryOf(s: Segment, defaultBankCode: string, defaultCountry: string, listsAll: boolean): UpdEntry | undefined {
+  const account = accountOf(s, defaultBankCode, defaultCountry, listsAll);
+  if (account === undefined) return undefined;
+  const extension = extensionOf(s);
+  return {
+    account: extension === undefined ? account : account.copyWith({ bic: extension.bic, dataStatus: extension.status }),
+    extension,
+  };
+}
+
+function accountOf(
+  s: Segment,
+  defaultBankCode: string,
+  defaultCountry: string,
+  listsAll: boolean,
+): Account | undefined {
+  const version = s.version;
+  // Every version names the account as KTV2, by position: a sub-account or bank code the bank leaves out is empty.
+  const [number, subAccount, country, bank] = s.texts(1);
+  const iban = version >= 6 ? s.text(2) : undefined;
+  if (number === undefined && iban === undefined) return undefined;
+  // Field positions by HIUPD version: version 6 inserts the IBAN, version 5 the account type.
+  const fields =
+    version >= 6
+      ? { customer: 3, type: 4, currency: 5, name1: 6, name2: 7, product: 8 }
+      : version === 5
+        ? { customer: 2, type: 3, currency: 4, name1: 5, name2: 6, product: 7 }
+        : { customer: 2, type: undefined, currency: 3, name1: 4, name2: 5, product: 6 };
+  return new Account({
+    accountNumber: number,
+    subAccount,
+    countryCode: country ?? defaultCountry,
+    bankCode: bank ?? defaultBankCode,
+    iban,
+    customerId: s.text(fields.customer),
+    typeCode: fields.type === undefined ? undefined : s.integer(fields.type),
+    currency: s.text(fields.currency),
+    ownerName: nonBlank(defined([s.text(fields.name1), s.text(fields.name2)]).join(' ')),
+    productName: s.text(fields.product),
+    allowedTransactions: transactionsOf(s),
+    allowedTransactionsComplete: listsAll,
+  });
+}
+
+/**
+ * The version of `transaction` to send, for `account` where it concerns one: the highest the bank offers and the client
+ * `implemented`. `undefined` where there is none, or the parameter data do not permit the transaction
+ * (`permitsTransaction`).
+ */
+export function offeredVersion(
+  bpd: Bpd3 | undefined,
+  upd: Upd3 | undefined,
+  transaction: string,
+  implemented: ReadonlySet<number>,
+  options: { account?: Account; requiresEntry?: boolean },
+): number | undefined {
+  return permitsTransaction(bpd, upd, transaction, options) ? bpd?.bestVersion(transaction, implemented) : undefined;
+}
+
+/**
+ * Whether the parameter data let the user send `transaction`, for `account` where it concerns one: the bank allows it
+ * with PIN/TAN, and the user parameter data permit it (Formals E.1, F.3.4; PIN/TAN B.1, B.8.1).
+ *
+ * - `account`, which the session has taken as the bank knows it (`SepaAccounts.complete`), permits what it lists, and
+ *   anything else only where its list is incomplete ("UPD-Verwendung" 1). One only the SEPA account list names lists
+ *   nothing, and so permits anything; where the lists are complete, the session refuses one the bank names nowhere.
+ * - A transaction without account, such as the TAN media list, is permitted where some entry lists it or the lists are
+ *   incomplete.
+ * - One that `requiresEntry`, the SEPA account list, must be listed even where the lists are incomplete (Formals F.3.4),
+ *   unless they list nothing at all, which tells nothing.
+ */
+function permitsTransaction(
+  bpd: Bpd3 | undefined,
+  upd: Upd3 | undefined,
+  transaction: string,
+  options: { account?: Account; requiresEntry?: boolean },
+): boolean {
+  if (bpd !== undefined && !bpd.pinTan.allowsWithPinTan(transaction)) return false;
+  if (upd === undefined) return true;
+  if (options.account !== undefined) return allows(options.account, transaction);
+  const listed = upd.listedTransactions;
+  if (listed.has(transaction)) return true;
+  return !upd.listsAllTransactions && (!(options.requiresEntry ?? false) || listed.size === 0);
+}
+
+/** Whether the bank lists `transaction`, such as `HKCAZ`, as permitted for `account`. */
+export function lists(account: Account, transaction: string): boolean {
+  return account.allowedTransactions.includes(transaction);
+}
+
+/**
+ * Whether the bank may permit `transaction` on `account`: it lists it, or its list is not complete
+ * (`Account.allowedTransactionsComplete`), so that only the bank can tell.
+ */
+function allows(account: Account, transaction: string): boolean {
+  return lists(account, transaction) || !account.allowedTransactionsComplete;
+}
+
+/** Serializes parameter segments for the saved state. */
+function encodeSegments(segments: readonly Segment[]): string {
+  return base64Encode(concatBytes(segments.map((s) => s.encode())));
+}
+
+export function decodeSegments(data: string): Segment[] {
+  return parseSegments(base64Decode(data));
+}

package/src/v3/protocol.ts

@@ -0,0 +1,148 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { MessageLogger } from '../core/client.js';
+import { requirePinLength, type FinTsConfig } from '../core/config.js';
+import { clientClosedError } from '../core/errors.js';
+import type { FinTsTransport } from '../core/transport.js';
+import { decodeBankText } from '../util/text.js';
+import { BankConnection, checkMessageSize } from './bank-connection.js';
+import { buildMessage, decodeTransport, encodeTransport } from './message.js';
+import type { ParameterStore } from './parameter-store.js';
+import { Segments } from './segments.js';
+import type { SegmentSpec } from './syntax.js';
+
+/** Customer ID the specification reserves for anonymous dialogs. */
+const anonymousCustomerId = '9999999999';
+
+/** How a message is signed: the security function of the TAN method and the customer system ID. */
+export interface Signing3 {
+  readonly securityFunction: string;
+  readonly systemId: string;
+}
+
+/** Hands out the PIN for each message the protocol signs, and so decides whether one may go out. */
+export interface PinGuard {
+  /** The PIN to sign a message with; throws instead where none may go out. */
+  readonly pin: string;
+
+  /** Counts a login signed with the PIN, the first message of a dialog, before it goes out. */
+  loginSent(): void;
+}
+
+/** Whether `segments` are those of a dialog end, the one message a closing client still sends. */
+function isDialogEnd(segments: readonly SegmentSpec[]): boolean {
+  return segments.length === 1 && segments[0]!.type === 'HKEND';
+}
+
+/**
+ * Builds, signs and posts FinTS 3.0 messages (HBCI segment syntax, PIN/TAN security) for the user `parameters.config`
+ * names, with the parameter data and IDs `parameters` keeps. Every message signed with the PIN takes it from the
+ * `PinGuard` (`post`), which keeps it from going out after a refused login.
+ */
+export class FinTs3Protocol {
+  private readonly config: FinTsConfig;
+  private readonly connection: BankConnection;
+
+  /** Whether the client is closing, so that only dialog ends go out (`beginClose`). */
+  private closing = false;
+
+  constructor(
+    readonly parameters: ParameterStore,
+    private readonly guard: PinGuard,
+    transport?: FinTsTransport,
+    logger?: MessageLogger,
+  ) {
+    this.config = parameters.config;
+    this.connection = new BankConnection(this.config.url, transport, logger);
+  }
+
+  /** Identification (HKIDN) and processing preparation (HKVVB), which open every dialog. */
+  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.parameters.reportedBpdVersion,
+        updVersion: anonymous ? 0 : this.parameters.reportedUpdVersion,
+        language: this.parameters.bankParameters?.dialogLanguage ?? 0,
+        productId: this.config.productId,
+        productVersion: this.config.productVersion,
+      }),
+    ];
+  }
+
+  /**
+   * Sends `segments` as message `number` of the dialog `dialogId` and returns the bank's answer, not yet parsed.
+   *
+   * With `signing` the message is signed with the PIN, which `PinGuard.pin` hands out, and the `tan`; without, it
+   * goes out unsigned, as in an anonymous dialog.
+   */
+  async post(message: {
+    dialogId: string;
+    number: number;
+    segments: readonly SegmentSpec[];
+    signing: Signing3 | undefined;
+    tan: string | undefined;
+  }): Promise<Uint8Array> {
+    if (this.closing && !isDialogEnd(message.segments)) throw clientClosedError();
+    const signing = message.signing;
+    // The first message of a signed dialog logs in: from here on the bank may count the PIN.
+    const login = signing !== undefined && message.number === 1;
+    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: login ? this.pinForLogin() : this.guard.pin,
+              securityFunction: signing.securityFunction,
+            },
+      tan: message.tan,
+    });
+    checkMessageSize(outgoing.bytes.length, this.parameters.bankParameters?.bankInfo.maxMessageSize);
+    this.connection.log('outgoing', () => outgoing.masked);
+    if (login) this.guard.loginSent();
+    const bytes = decodeTransport(await this.connection.post(encodeTransport(outgoing.bytes), 'text/plain'));
+    this.connection.log('incoming', () => decodeBankText(bytes));
+    return bytes;
+  }
+
+  /**
+   * The PIN to sign a login with, the first message of a dialog.
+   *
+   * Throws instead where the guard holds the PIN back (`PinGuard.pin`), or if the bank parameters rule out the PIN's
+   * length: the bank would count such a PIN as a failed attempt. The later messages of a dialog, its end included, take
+   * the PIN the bank has accepted, whatever the parameter data it delivered since say.
+   */
+  private pinForLogin(): string {
+    const pin = this.guard.pin;
+    const length = this.parameters.bankParameters?.pinTan.pinLength;
+    requirePinLength(pin, length?.min, length?.max);
+    return pin;
+  }
+
+  /**
+   * Aborts the request on its way, and sends nothing but dialog ends from now on: any other message fails with
+   * `FinTsStateError` before it goes out, so that a call under way stops at its next one. The client calls it as soon as
+   * it is closed, and `close` once it has ended its dialog.
+   */
+  beginClose(): void {
+    this.closing = true;
+    this.connection.abortRequests();
+  }
+
+  close(): void {
+    this.connection.close();
+  }
+}