@coderoftime/fints 0.1.0 → 0.2.0

package/src/v3/message.ts

@@ -2,13 +2,21 @@
 
 import { BankMessage } from '../core/bank-info.js';
 import { FinTsFeedback } from '../core/feedback.js';
-import type { BankResponse } from '../session/protocol.js';
 import { TanMethod } from '../tan/tan-models.js';
-import { base64Encode, BytesBuilder, latin1Decode, latin1Encode } from '../util/bytes.js';
+import { base64Encode, BytesBuilder, latin1Encode, utf8Decode } from '../util/bytes.js';
 import { formatFintsDate, formatFintsTime } from '../util/dates.js';
 import { FormatError } from '../util/errors.js';
 import { decodeBankText, decodeBase64Lines } from '../util/text.js';
-import { Binary, parseSegments, type Segment, SegmentSpec, type SegmentValue } from './syntax.js';
+import {
+  Binary,
+  dataElementMemory,
+  maxDataElements,
+  parseSegments,
+  type Segment,
+  SegmentSpec,
+  type SegmentValue,
+  Verbatim,
+} from './syntax.js';
 
 /** Signature data of a PIN/TAN message. */
 export interface PinTanCredentials {
@@ -35,7 +43,7 @@ const issuer = 1;
 
 /** Security identification: message sender (MS), empty CID, then the customer system ID. */
 function sender(systemId: string): SegmentValue {
-  return [1, null, systemId];
+  return [1, null, new Verbatim(systemId)];
 }
 
 /** Security reference number, the same in every message. */
@@ -125,7 +133,12 @@ export function buildMessage(parts: {
   const trailer = new SegmentSpec('HNHBS', 1, [parts.messageNumber]).build(body.nextNumber);
   // The header states the size of the whole message, itself included; its own size does not depend on it.
   const header = (size: number): Uint8Array =>
-    new SegmentSpec('HNHBK', 3, [size.toString().padStart(12, '0'), 300, parts.dialogId, parts.messageNumber]).build(1);
+    new SegmentSpec('HNHBK', 3, [
+      size.toString().padStart(12, '0'),
+      300,
+      new Verbatim(parts.dialogId),
+      parts.messageNumber,
+    ]).build(1);
   const sizeOf = (sections: readonly Uint8Array[]): number => header(0).length + lengthOf(sections) + trailer.length;
   const result = new BytesBuilder();
   result.add(header(sizeOf([body.bytes])));
@@ -213,7 +226,7 @@ function signedBody(
 }
 
 /** A received message, with the segments of the encryption envelope unpacked. */
-export class IncomingMessage3 implements BankResponse {
+export class IncomingMessage3 {
   /**
    * Return codes for the whole message (HIRMG), then for single request segments (HIRMS).
    *
@@ -222,10 +235,12 @@ export class IncomingMessage3 implements BankResponse {
    */
   readonly feedback: readonly FinTsFeedback[];
 
+  /** Whether the bank rejected the message as a whole (an error in HIRMG), rather than single orders in it. */
   readonly messageRejected: boolean;
 
   private constructor(
     readonly segments: readonly Segment[],
+    /** The memory the message holds, in bytes: its length, and what its parts take beyond that. */
     readonly size: number,
   ) {
     this.feedback = Object.freeze(
@@ -238,34 +253,66 @@ export class IncomingMessage3 implements BankResponse {
   }
 
   /**
-   * Parses a message; throws `FormatError` if `data` is not a FinTS message, such as the HTML page of a proxy or a
-   * maintenance notice.
+   * Parses a message; throws `FormatError` if `data` is not one complete FinTS message, such as the HTML page of a
+   * proxy, a maintenance notice, a message cut short, which lacks the message trailer (HNHBS) at its end, or two
+   * messages run together, whose second would pass for part of the first.
+   *
+   * Its `size` counts the memory of its data elements along with its bytes, since a message of many short elements
+   * takes far more memory than bytes.
    */
   static parse(data: Uint8Array): IncomingMessage3 {
-    const outer = parseSegments(data);
+    const budget = { elements: maxDataElements };
+    const outer = parseSegments(data, budget);
     if (outer[0]?.type !== 'HNHBK') throw new FormatError('Not a FinTS message: no message header');
+    if (outer.at(-1)?.type !== 'HNHBS') throw new FormatError('Incomplete FinTS message: no message trailer');
+    if (outer.filter((s) => s.type === 'HNHBK' || s.type === 'HNHBS').length > 2) {
+      throw new FormatError('More than one FinTS message');
+    }
     const segments: Segment[] = [];
     for (const s of outer) {
-      if (s.type === 'HNVSD') {
-        const payload = s.binary(1);
-        if (payload !== undefined) segments.push(...parseSegments(payload));
-      } else {
+      if (s.type !== 'HNVSD') {
         segments.push(s);
+        continue;
       }
+      const payload = s.binary(1);
+      if (payload === undefined) throw new FormatError('Encrypted data (HNVSD) without binary data');
+      for (const inner of parseSegments(payload, budget)) segments.push(inner);
     }
-    return new IncomingMessage3(segments, data.length);
+    return new IncomingMessage3(segments, data.length + (maxDataElements - budget.elements) * dataElementMemory);
   }
 
   static combine(first: IncomingMessage3, second: IncomingMessage3): IncomingMessage3 {
     return new IncomingMessage3([...first.segments, ...second.segments], first.size + second.size);
   }
 
+  /** Free-text messages the bank addresses to the user. */
   get bankMessages(): BankMessage[] {
     return this.findAll('HIKIM').map((m) => new BankMessage(m.text(1) ?? '', m.text(2) ?? ''));
   }
 
+  /** The dialog ID the bank assigned, as `Segment.verbatim` reads it, to send back byte for byte. */
   get dialogId(): string | undefined {
-    return this.find('HNHBK')?.text(3);
+    return this.find('HNHBK')?.verbatim(3);
+  }
+
+  /**
+   * Whether the message answers message `number` of the dialog `dialogId`: header and trailer carry that number, and the
+   * header names that message where it names the message it refers to (Bezugsnachricht). The dialog ID counts only once
+   * the bank has assigned one; before, `dialogId` is `undefined`, since every first message goes out under the same.
+   */
+  answers(number: number, dialogId: string | undefined): boolean {
+    const header = this.find('HNHBK');
+    // The trailer comes last, after the segments of the encryption envelope, which might hold one of their own.
+    const trailer = this.segments.at(-1);
+    if (header === undefined || trailer?.type !== 'HNHBS') return false;
+    const inDialog = (id: string | undefined): boolean => dialogId === undefined || id === dialogId;
+    const namesReference = header.group(5).some((e) => !e.isEmpty);
+    return (
+      header.integer(4) === number &&
+      trailer.integer(1) === number &&
+      inDialog(header.verbatim(3)) &&
+      (!namesReference || (header.integer(5, 1) === number && inDialog(header.verbatim(5, 0))))
+    );
   }
 
   find(type: string): Segment | undefined {
@@ -277,6 +324,10 @@ export class IncomingMessage3 implements BankResponse {
   }
 }
 
+/**
+ * The return codes of `s`. Their parameters are values the client or the app sends back, such as the position to
+ * continue at or new login data, so they are read as `Segment.verbatim` reads them.
+ */
 function feedbackOf(s: Segment): FinTsFeedback[] {
   const feedback: FinTsFeedback[] = [];
   for (let i = 1; i < s.length; i++) {
@@ -284,7 +335,7 @@ function feedbackOf(s: Segment): FinTsFeedback[] {
     if (code === undefined) continue;
     const parameters: string[] = [];
     // Empty parameters stay, as empty text, so that each keeps its position.
-    for (let j = 3; j < s.group(i).length; j++) parameters.push(s.text(i, j) ?? '');
+    for (let j = 3; j < s.group(i).length; j++) parameters.push(s.verbatim(i, j) ?? '');
     feedback.push(new FinTsFeedback({ code, reference: s.text(i, 1), text: s.text(i, 2) ?? '', parameters }));
   }
   return feedback;
@@ -298,7 +349,8 @@ function feedbackOf(s: Segment): FinTsFeedback[] {
 export function decodeTransport(body: Uint8Array): Uint8Array {
   if (startsWithMessageHeader(body)) return body;
   try {
-    return decodeBase64Lines(latin1Decode(body));
+    // Base64 is ASCII, which UTF-8 decodes natively; anything else is no base64 either way.
+    return decodeBase64Lines(utf8Decode(body, true));
   } catch (error) {
     if (error instanceof FormatError) return body;
     throw error;

package/src/v3/parameter-store.ts

@@ -0,0 +1,160 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { FinTsConfig } from '../core/config.js';
+import { FormatError } from '../util/errors.js';
+import { readOptionalBoolean, readOptionalObject, readOptionalString, type JsonObject } from '../util/json.js';
+import type { IncomingMessage3 } from './message.js';
+import { Bpd3, decodeSegments, Upd3 } from './parameters.js';
+
+/**
+ * The parameter data and IDs the bank sends the user `config` names, which the messages and business transactions
+ * take, and which the saved state keeps: the bank and user parameter data, the customer system ID, and the names of
+ * the TAN media as the bank sent them.
+ */
+export class ParameterStore {
+  private systemIdValue: string | undefined;
+  private bpd: Bpd3 | undefined;
+
+  /**
+   * Whether the bank parameter data came from the anonymous dialog. They serve until those of a dialog signed with the
+   * PIN come: the bank may send a user other ones (PIN/TAN B.4.3.1), and the anonymous dialog may have had to do
+   * without the announcement of strong customer authentication. So signed dialogs report version 0 for them, which has
+   * the bank send its parameter data anew.
+   */
+  private bpdAnonymous = false;
+  private upd: Upd3 | undefined;
+
+  /**
+   * The names of the TAN media in the bank's last list whose text differs from what the bank sent, by their text, as
+   * `parseTanMedia` notes them. Saved with the state, as the medium in use is.
+   */
+  private tanMediumNames = new Map<string, string>();
+
+  constructor(readonly config: FinTsConfig) {}
+
+  /** The bank parameter data received so far, if any. */
+  get bankParameters(): Bpd3 | undefined {
+    return this.bpd;
+  }
+
+  /** The user parameter data received so far, if any. */
+  get userParameters(): Upd3 | undefined {
+    return this.upd;
+  }
+
+  /**
+   * The customer system ID the bank assigned in the synchronization, as `Segment.verbatim` reads it; `undefined`
+   * before. No dialog signed with the PIN starts without it.
+   */
+  get systemId(): string | undefined {
+    return this.systemIdValue;
+  }
+
+  /** The version of the bank parameter data a dialog reports: 0 where there are none, or only the anonymous dialog's. */
+  get reportedBpdVersion(): number {
+    return this.bpd === undefined || this.bpdAnonymous ? 0 : this.bpd.version;
+  }
+
+  /**
+   * The version of the user parameter data a signed dialog reports: 0 where there are none, or where they name another
+   * user ID than the one logging in, so that the bank sends the user's anew. They may be another user's, as where a
+   * relay mixed up the answers to the synchronizations of two users and the bank takes the other user's customer system
+   * ID. A bank that names the user by another ID than the login's, such as for an alias, only sends its user parameter
+   * data at every login.
+   */
+  get reportedUpdVersion(): number {
+    const upd = this.upd;
+    return upd !== undefined && upd.userId === this.config.userId ? upd.version : 0;
+  }
+
+  /**
+   * Drops the customer system ID the bank no longer accepts, so that a synchronization is required again, and with it
+   * the user parameter data, which the next login delivers anew: what came along with an ID the bank does not know may
+   * not be the user's either (`reportedUpdVersion`). Returns whether there was an ID.
+   */
+  forgetSystemId(): boolean {
+    const had = this.systemIdValue !== undefined;
+    this.systemIdValue = undefined;
+    this.upd = undefined;
+    return had;
+  }
+
+  /**
+   * Keeps the parameter data and IDs in `response`, an answer to the opening of a signed dialog: the login, which may be
+   * a synchronization, or its approval. The bank sends them there (Formals C.3.1); taken from the answer to an order,
+   * the parameter data a bank repeats there in part would replace the complete ones.
+   */
+  keep(response: IncomingMessage3): void {
+    this.keepBankParameters(response, false);
+    this.upd = Upd3.fromSegments(response.segments, this.config.bankCode, this.config.countryCode) ?? this.upd;
+    this.systemIdValue = response.find('HISYN')?.verbatim(1) ?? this.systemIdValue;
+  }
+
+  /**
+   * Keeps the bank parameter data in `response`, the answer of an anonymous dialog, where there are none from a dialog
+   * signed with the PIN: until those come, the dialogs signed with the PIN have the bank send its parameter data anew,
+   * since it may send a user other ones (PIN/TAN B.4.3.1). Keeps nothing that belongs to a user.
+   */
+  keepAnonymous(response: IncomingMessage3): void {
+    if (this.bpd === undefined || this.bpdAnonymous) this.keepBankParameters(response, true);
+  }
+
+  private keepBankParameters(response: IncomingMessage3, anonymous: boolean): void {
+    const bpd = Bpd3.fromSegments(response.segments, this.config.bankCode);
+    if (bpd === undefined) return;
+    this.bpd = bpd;
+    this.bpdAnonymous = anonymous;
+  }
+
+  /** Keeps `names`, the names of the bank's latest list of TAN media as `parseTanMedia` notes them. */
+  keepTanMediumNames(names: Map<string, string>): void {
+    this.tanMediumNames = names;
+  }
+
+  /** The TAN medium `name` as the bank sent it in its list of TAN media; `name` itself for one it did not list. */
+  tanMediumAsSent(name: string): string {
+    return this.tanMediumNames.get(name) ?? name;
+  }
+
+  /** The parameter data and IDs as JSON data, for the client's saved state. */
+  saveState(): JsonObject {
+    return {
+      systemId: this.systemIdValue ?? null,
+      bpd: this.bpd?.encoded ?? null,
+      bpdAnonymous: this.bpdAnonymous,
+      upd: this.upd?.encoded ?? null,
+      tanMediumNames: Object.fromEntries(this.tanMediumNames),
+    };
+  }
+
+  /** Restores what `saveState` saved; throws if `saved` is damaged, leaving the store unchanged. */
+  restoreState(saved: JsonObject): void {
+    const bpd = readOptionalString(saved, 'bpd');
+    const upd = readOptionalString(saved, 'upd');
+    const restoredSystemId = readOptionalString(saved, 'systemId');
+    // A state of the Dart package or an earlier version does not tell, so its parameter data are fetched anew.
+    const restoredBpdAnonymous = readOptionalBoolean(saved, 'bpdAnonymous') ?? true;
+    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);
+    const restoredNames = readTanMediumNames(saved);
+    this.systemIdValue = restoredSystemId;
+    this.bpd = restoredBpd;
+    this.bpdAnonymous = restoredBpdAnonymous;
+    this.upd = restoredUpd;
+    this.tanMediumNames = restoredNames;
+  }
+}
+
+/** The TAN medium names `saveState` saved; none in a state of the Dart package or an earlier version. */
+function readTanMediumNames(saved: JsonObject): Map<string, string> {
+  const names = readOptionalObject(saved, 'tanMediumNames') ?? {};
+  return new Map(
+    Object.entries(names).map(([name, asSent]) => {
+      if (typeof asSent !== 'string') throw new FormatError('Saved state: a TAN medium name is not a string');
+      return [name, asSent];
+    }),
+  );
+}

package/src/v3/parameters.ts

@@ -3,10 +3,10 @@
 import { Account } from '../core/account.js';
 import type { Balance } from '../core/balance.js';
 import { BankInfo } from '../core/bank-info.js';
-import { highestCommonVersion, type BankParameters, type UserParameters } from '../session/parameter-data.js';
+import { FinTsProtocolError } from '../core/errors.js';
 import { TanMethod, tanMediumRequirementOf } from '../tan/tan-models.js';
-import { base64Decode, base64Encode, BytesBuilder } from '../util/bytes.js';
-import { tryParseInt } from '../util/text.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';
 
@@ -46,14 +46,23 @@ 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 implements BankParameters {
+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;
 
@@ -69,6 +78,8 @@ export class Bpd3 implements BankParameters {
    */
   readonly dialogLanguage: number;
 
+  private encodedValue: string | undefined;
+
   private constructor(
     readonly segments: readonly Segment[],
     hibpa: Segment,
@@ -99,16 +110,14 @@ export class Bpd3 implements BankParameters {
     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;
   }
 
-  get pinLength(): { min: number | undefined; max: number | undefined } {
-    return this.pinTan.pinLength;
-  }
-
-  allowsWithPinTan(transaction: string): boolean {
-    return this.pinTan.allowsWithPinTan(transaction);
+  /** 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. */
@@ -123,8 +132,13 @@ export class Bpd3 implements BankParameters {
     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 {
-    return highestCommonVersion(this.versions.get(Bpd3.parameterName(transaction)), implemented);
+    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. */
@@ -293,7 +307,8 @@ interface UpdEntry {
   readonly extension: AccountExtension | undefined;
 }
 
-/** The version and the usage ("UPD-Verwendung") of the user parameter data in HIUPA. */
+/** 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;
 
@@ -301,15 +316,30 @@ const hiupaUsage = 3;
 const transactionCode = /^[A-Z]{4,6}$/;
 
 /** FinTS 3.0 user parameter data (UPD): HIUPA and the accounts (HIUPD), parsed once. */
-export class Upd3 implements UserParameters {
+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[],
@@ -319,6 +349,7 @@ export class Upd3 implements UserParameters {
     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));
@@ -328,11 +359,15 @@ export class Upd3 implements UserParameters {
     this.accounts = Object.freeze(this.entries.map((e) => e.account));
   }
 
-  /** FinTS 3.0 UPD do not list the allowed TAN methods; the bank reports them with return code 3920. */
-  get allowedTanMethods(): readonly string[] {
-    return [];
+  /** 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);
   }
@@ -398,19 +433,8 @@ function accountOf(
   listsAll: boolean,
 ): Account | undefined {
   const version = s.version;
-  const nationalAccount = s.texts(1);
-  let number: string | undefined;
-  let subAccount: string | undefined;
-  let country: string | undefined;
-  let bank: string | undefined;
-  if (nationalAccount.length >= 4) {
-    [number, subAccount, country, bank] = nationalAccount;
-  } else if (nationalAccount.length === 3) {
-    // Older banks leave out the sub-account.
-    [number, country, bank] = nationalAccount;
-  } else if (nationalAccount.length > 0) {
-    number = nationalAccount[0];
-  }
+  // 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.
@@ -420,9 +444,6 @@ function accountOf(
       : 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 };
-  const owner = defined([s.text(fields.name1), s.text(fields.name2)])
-    .join(' ')
-    .trim();
   return new Account({
     accountNumber: number,
     subAccount,
@@ -432,18 +453,70 @@ function accountOf(
     customerId: s.text(fields.customer),
     typeCode: fields.type === undefined ? undefined : s.integer(fields.type),
     currency: s.text(fields.currency),
-    ownerName: owner === '' ? undefined : owner,
+    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. */
-export function encodeSegments(segments: readonly Segment[]): string {
-  const out = new BytesBuilder();
-  for (const s of segments) out.add(s.encode());
-  return base64Encode(out.takeBytes());
+function encodeSegments(segments: readonly Segment[]): string {
+  return base64Encode(concatBytes(segments.map((s) => s.encode())));
 }
 
 export function decodeSegments(data: string): Segment[] {