@coderoftime/fints 0.1.0 → 0.3.0

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, trimBlanks, tryParseInt } from '../util/text.js';
 import { AccountExtension } from './account-extension.js';
 import { parseSegments, type Segment } from './syntax.js';
 
@@ -33,6 +33,12 @@ const Hibpa = {
   maxTimeout: 9,
 } as const;
 
+/** The size or time at `index` of `hibpa`, a field of at most four digits; `undefined` for a larger value, as for none. */
+function hibpaLimit(hibpa: Segment, index: number): number | undefined {
+  const value = hibpa.integer(index);
+  return value !== undefined && value <= 9999 ? value : undefined;
+}
+
 /**
  * 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.
@@ -46,20 +52,35 @@ 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;
 
-  /** camt formats the bank offers for HKCAZ. */
+  /** The camt.052 formats the bank offers for HKCAZ, the one camt message the client reads. */
   readonly camtFormats: readonly string[];
 
+  /**
+   * Whether an international account (KTI) may name the national account as well: HISPAS does not rule it out
+   * ("Nationale Kontoverbindung erlaubt").
+   */
+  readonly nationalAccountAllowed: boolean;
+
   /** Versions of each parameter segment, by segment type. */
   private readonly versions: ReadonlyMap<string, ReadonlySet<number>>;
 
@@ -69,20 +90,19 @@ export class Bpd3 implements BankParameters {
    */
   readonly dialogLanguage: number;
 
-  private constructor(
-    readonly segments: readonly Segment[],
-    hibpa: Segment,
-    fallbackBankCode: string,
-  ) {
+  /** The segments as the saved state keeps them. */
+  readonly encoded: string;
+
+  private constructor(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),
+      maxMessageSize: hibpaLimit(hibpa, Hibpa.maxMessageSize),
+      minTimeout: hibpaLimit(hibpa, Hibpa.minTimeout),
+      maxTimeout: hibpaLimit(hibpa, Hibpa.maxTimeout),
     });
     this.offeredMethods = parseTanMethods(segments);
     const offered = [...this.offeredMethods.values()];
@@ -94,23 +114,18 @@ export class Bpd3 implements BankParameters {
     this.camtFormats = segments
       .filter((s) => s.type === 'HICAZS')
       .flatMap((s) => defined(s.texts(parameterGroup)))
-      .filter((format) => format.includes('camt'));
+      .filter((format) => format.includes('camt.052'));
+    this.nationalAccountAllowed = highest(segments, 'HISPAS')?.text(parameterGroup, 1) !== 'N';
     this.versions = versionsByType(segments);
     this.dialogLanguage = dialogLanguageOf(segments, this.bankInfo);
+    this.encoded = encodeSegments(segments);
   }
 
+  /** 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 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);
@@ -123,8 +138,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. */
@@ -140,13 +160,23 @@ function dialogLanguageOf(segments: readonly Segment[], bankInfo: BankInfo): num
   return bankInfo.languages.map((l) => tryParseInt(l)).find((l) => l !== undefined && languages.has(l)) ?? 0;
 }
 
+const generalParameterSegments = new Set(['HIBPA', 'HIKOM', 'HISHV', 'HIKPV']);
+
 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;
+  if (generalParameterSegments.has(type)) return true;
+  // Return codes for single segments end with an S, as parameter segments do.
+  if (type === 'HIRMS') return false;
   return type.length >= 5 && (type.startsWith('HI') || type.startsWith('DI')) && type.endsWith('S');
 }
 
+/** The segment of `type` with the highest version in `segments`. */
+function highest(segments: readonly Segment[], type: string): Segment | undefined {
+  let found: Segment | undefined;
+  for (const s of segments) if (s.type === type && (found === undefined || s.version > found.version)) found = s;
+  return found;
+}
+
 function versionsByType(segments: readonly Segment[]): Map<string, Set<number>> {
   const versions = new Map<string, Set<number>>();
   for (const s of segments) {
@@ -256,17 +286,14 @@ function parseHitans(s: Segment): OfferedMethod[] {
 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 },
+    /** The shortest and longest PIN the bank takes; `undefined` where the bank parameter data have no HIPINS. */
+    readonly pinLength: { min: number | undefined; max: number | undefined } | 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 hipins = highest(segments, 'HIPINS');
+    if (hipins === undefined) return new PinTanParameters(new Map(), 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.
@@ -293,7 +320,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,24 +329,41 @@ 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[];
 
+  /** The segments as the saved state keeps them. */
+  readonly encoded: string;
+
   /** `listsAll` tells whether HIUPA declares the lists of permitted transactions complete ("UPD-Verwendung" 0). */
   private constructor(
-    readonly segments: readonly Segment[],
+    segments: readonly Segment[],
     hiupa: Segment,
     listsAll: boolean,
     defaultBankCode: string,
     defaultCountry: string,
   ) {
     const hiupds = segments.filter((s) => s.type === 'HIUPD');
+    this.userId = nonBlank(hiupa.text(hiupaUserId));
     this.version = hiupa.integer(hiupaVersion) ?? 0;
     this.listsAllTransactions = listsAll;
     this.listedTransactions = new Set(hiupds.flatMap(transactionsOf));
@@ -326,13 +371,13 @@ export class Upd3 implements UserParameters {
       hiupds.map((s) => entryOf(s, defaultBankCode, defaultCountry, listsAll)).filter((e) => e !== undefined),
     );
     this.accounts = Object.freeze(this.entries.map((e) => e.account));
+    this.encoded = encodeSegments(segments);
   }
 
-  /** 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 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);
   }
@@ -372,11 +417,13 @@ function transactionsOf(s: Segment): string[] {
 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);
+    const text = trimBlanks(
+      s
+        .group(i)
+        .map((e) => e.text)
+        .join(':'),
+    );
+    if (text.startsWith('{')) return AccountExtension.tryParse(text);
   }
   return undefined;
 }
@@ -391,6 +438,22 @@ function entryOf(s: Segment, defaultBankCode: string, defaultCountry: string, li
   };
 }
 
+/** Whether `code` is a country code, three digits, such as `280`; a German bank code has eight. */
+function isCountryCode(code: string | undefined): boolean {
+  return code !== undefined && /^[0-9]{3}$/.test(code);
+}
+
+/**
+ * The national account of the HIUPD `s`: number, sub-account, country and bank code (KTV2), by position in every
+ * version, so that a sub-account or bank code the bank leaves out is empty. Three elements whose second is a country
+ * code and whose third is not are the older layout without sub-account: number, country and bank code.
+ */
+function nationalAccountOf(s: Segment): (string | undefined)[] {
+  const ktv = s.texts(1);
+  const [number, second, third] = ktv;
+  return ktv.length === 3 && isCountryCode(second) && !isCountryCode(third) ? [number, undefined, second, third] : ktv;
+}
+
 function accountOf(
   s: Segment,
   defaultBankCode: string,
@@ -398,19 +461,7 @@ 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];
-  }
+  const [number, subAccount, country, bank] = nationalAccountOf(s);
   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 +471,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 +480,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[] {