@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/v3/parameters.ts

@@ -0,0 +1,451 @@
+// 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 { highestCommonVersion, type BankParameters, type UserParameters } from '../session/parameter-data.js';
+import { TanMethod, tanMediumRequirementOf } from '../tan/tan-models.js';
+import { base64Decode, base64Encode, BytesBuilder } from '../util/bytes.js';
+import { 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);
+}
+
+/** FinTS 3.0 bank parameter data (BPD): HIBPA and the parameter segments (`HI…S`), parsed once. */
+export class Bpd3 implements BankParameters {
+  readonly bankInfo: BankInfo;
+
+  /** The two-step TAN methods of HITANS versions 6 and 7, by security function. */
+  private readonly offeredMethods: ReadonlyMap<string, OfferedMethod>;
+
+  readonly tanMethods: readonly TanMethod[];
+  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 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);
+  }
+
+  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);
+    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`;
+  }
+
+  bestVersion(transaction: string, implemented: ReadonlySet<number>): number | undefined {
+    return highestCommonVersion(this.versions.get(Bpd3.parameterName(transaction)), implemented);
+  }
+
+  /** 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 version and the usage ("UPD-Verwendung") of the user parameter data in HIUPA. */
+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 implements UserParameters {
+  readonly version: number;
+  readonly listsAllTransactions: boolean;
+  readonly listedTransactions: ReadonlySet<string>;
+
+  /** The accounts with the extension each carries, where it does. */
+  private readonly entries: readonly UpdEntry[];
+  readonly accounts: readonly Account[];
+
+  /** `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.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));
+  }
+
+  /** FinTS 3.0 UPD do not list the allowed TAN methods; the bank reports them with return code 3920. */
+  get allowedTanMethods(): readonly string[] {
+    return [];
+  }
+
+  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;
+  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 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 };
+  const owner = defined([s.text(fields.name1), s.text(fields.name2)])
+    .join(' ')
+    .trim();
+  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: owner === '' ? undefined : owner,
+    productName: s.text(fields.product),
+    allowedTransactions: transactionsOf(s),
+    allowedTransactionsComplete: listsAll,
+  });
+}
+
+/** 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());
+}
+
+export function decodeSegments(data: string): Segment[] {
+  return parseSegments(base64Decode(data));
+}