@coderoftime/fints 0.2.0 → 0.3.0

package/src/v3/protocol.ts

@@ -7,13 +7,19 @@ 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 type { MessageLimits, 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 long the request on its way when the client is closed may take, and then its dialog ends, where the transport
+ * takes the abort (`beginClose`).
+ */
+const closingGraceMs = 5000;
+
 /** How a message is signed: the security function of the TAN method and the customer system ID. */
 export interface Signing3 {
   readonly securityFunction: string;
@@ -29,6 +35,15 @@ export interface PinGuard {
   loginSent(): void;
 }
 
+/**
+ * Throws if `limits` rule out a message of `size` bytes, or the length of `loginPin`, the PIN of a login: `TypeError`
+ * for the PIN, which the bank would count as a failed attempt, and `FinTsProtocolError` for the size.
+ */
+function checkLimits(limits: MessageLimits, size: number, loginPin: string | undefined): void {
+  if (loginPin !== undefined) requirePinLength(loginPin, limits.pinLength?.min, limits.pinLength?.max);
+  checkMessageSize(size, limits.maxMessageSize);
+}
+
 /** 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';
@@ -43,9 +58,11 @@ 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;
 
+  /** The error with which the limits last stopped a login (`stoppedLogin`). */
+  private stoppedLoginError: unknown;
+
   constructor(
     readonly parameters: ParameterStore,
     private readonly guard: PinGuard,
@@ -91,26 +108,28 @@ export class FinTs3Protocol {
   }): Promise<Uint8Array> {
     if (this.closing && !isDialogEnd(message.segments)) throw clientClosedError();
     const signing = message.signing;
+    const security =
+      signing === undefined
+        ? undefined
+        : {
+            countryCode: this.config.countryCode,
+            bankCode: this.config.bankCode,
+            userId: this.config.userId,
+            systemId: signing.systemId,
+            pin: this.guard.pin,
+            securityFunction: signing.securityFunction,
+          };
     // 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 login = security !== 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,
-            },
+      security,
       tan: message.tan,
     });
-    checkMessageSize(outgoing.bytes.length, this.parameters.bankParameters?.bankInfo.maxMessageSize);
+    this.checkOutgoing(outgoing.bytes.length, login ? security.pin : undefined);
+    this.connection.checkSendable();
     this.connection.log('outgoing', () => outgoing.masked);
     if (login) this.guard.loginSent();
     const bytes = decodeTransport(await this.connection.post(encodeTransport(outgoing.bytes), 'text/plain'));
@@ -119,27 +138,41 @@ export class FinTs3Protocol {
   }
 
   /**
-   * The PIN to sign a login with, the first message of a dialog.
+   * Throws if the limits of the parameter data rule out a message of `size` bytes, or the length of `loginPin`, the PIN
+   * of a login (`checkLimits`). The later messages of a dialog, its end included, take the PIN the bank has accepted,
+   * whatever the parameter data it delivered since say.
    *
-   * 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.
+   * Remembers the error that stops a login (`stoppedLogin`): the parameter data may be outdated, as saved ones are,
+   * and new ones would come only in answer to the login they rule out.
    */
-  private pinForLogin(): string {
-    const pin = this.guard.pin;
-    const length = this.parameters.bankParameters?.pinTan.pinLength;
-    requirePinLength(pin, length?.min, length?.max);
-    return pin;
+  private checkOutgoing(size: number, loginPin: string | undefined): void {
+    try {
+      checkLimits(this.parameters.limits, size, loginPin);
+    } catch (error) {
+      if (loginPin !== undefined) this.stoppedLoginError = error;
+      throw error;
+    }
+  }
+
+  /** Whether `error` is the one with which the limits of the parameter data last stopped a login. */
+  stoppedLogin(error: unknown): boolean {
+    return this.stoppedLoginError !== undefined && this.stoppedLoginError === error;
+  }
+
+  /** Whether the client is closing, so that only dialog ends go out (`beginClose`). */
+  get isClosing(): boolean {
+    return this.closing;
   }
 
   /**
-   * 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.
+   * 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 request on its way has `closingGraceMs` to bring its answer, which
+   * counts as any other, and is aborted then; the dialog ends have as long again once it is over, and none goes out
+   * later. 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();
+    this.connection.abortRequestsAfter(closingGraceMs);
   }
 
   close(): void {

package/src/v3/queries.ts

@@ -104,8 +104,9 @@ export function balanceQuery(parameters: ParameterStore, account: Account): Quer
   if (offered === undefined) {
     throw new FinTsUnsupportedError('The bank reports no balance (HKSAL) for this account');
   }
+  const nationalAllowed = requireBankParameters(parameters.bankParameters).nationalAccountAllowed;
   return {
-    order: (continuation) => Segments.balance(offered, account, continuation),
+    order: (continuation) => Segments.balance(offered, account, nationalAllowed, continuation),
     read: (pages) =>
       parseBalance(
         balanceRecord(
@@ -123,8 +124,8 @@ export function balanceQuery(parameters: ParameterStore, account: Account): Quer
  * the bank knows it, with the transactions the bank permits for it and its currency (`SepaAccounts.complete`).
  *
  * The client reads camt.052 only, so camt counts as offered only where the bank offers a camt.052 format. With `auto`
- * the client takes camt where the bank offers it, unless the user parameter data list only MT940 transactions for the
- * account.
+ * the client takes camt where the bank offers it, unless MT940 can be requested for the account and the user parameter
+ * data list only MT940 transactions for it.
  *
  * Throws `FinTsUnsupportedError` if the bank does not offer the chosen format for the account.
  */
@@ -135,14 +136,15 @@ export function transactionsQuery(
   from: Date | undefined,
   to: Date | undefined,
 ): Query<Transaction[]> {
-  const camtFormats = requireBankParameters(parameters.bankParameters).camtFormats.filter((f) =>
-    f.includes('camt.052'),
-  );
-  const camtVersion = camtFormats.length === 0 ? undefined : version(parameters, 'HKCAZ', [1], { account });
+  const bpd = requireBankParameters(parameters.bankParameters);
+  const camtVersion = bpd.camtFormats.length === 0 ? undefined : version(parameters, 'HKCAZ', [1], { account });
+  const mt940Version = version(parameters, 'HKKAZ', [6, 7], { account });
   const camt =
     format === 'camt' ||
-    (format === 'auto' && camtVersion !== undefined && (lists(account, 'HKCAZ') || !lists(account, 'HKKAZ')));
-  const offered = camt ? camtVersion : version(parameters, 'HKKAZ', [6, 7], { account });
+    (format === 'auto' &&
+      camtVersion !== undefined &&
+      (mt940Version === undefined || lists(account, 'HKCAZ') || !lists(account, 'HKKAZ')));
+  const offered = camt ? camtVersion : mt940Version;
   if (offered === undefined) {
     throw new FinTsUnsupportedError(
       `The bank offers no ${camt ? 'camt ' : ''}transactions (${camt ? 'HKCAZ' : 'HKKAZ'}) for this account`,
@@ -150,9 +152,14 @@ export function transactionsQuery(
   }
   if (camt) {
     return {
-      order: (continuation) => Segments.transactionsCamt(offered, account, camtFormats, { from, to, continuation }),
+      order: (continuation) =>
+        Segments.transactionsCamt(offered, account, bpd.nationalAccountAllowed, bpd.camtFormats, {
+          from,
+          to,
+          continuation,
+        }),
       // The first element names the account, the third element group holds the booked documents, the fourth
-      // element the pending one.
+      // element the pending one: binary data, which a bank may send as text instead.
       read: (pages) => {
         const segments = all(pages, 'HICAZ');
         if (!segments.every((s) => camtAccount(s).matches(account))) {
@@ -165,23 +172,24 @@ export function transactionsQuery(
               .filter((d) => !d.isEmpty)
               .map((d) => d.bytes),
           ),
-          segments.map((s) => s.binary(4)).filter((d) => d !== undefined),
+          segments.map((s) => s.bytes(4)).filter((d) => d !== undefined),
         );
       },
     };
   }
   return {
-    order: (continuation) => Segments.transactionsMt940(offered, account, { from, to, continuation }),
-    // The first element holds the booked transactions, the second the pending ones. Unlike HICAZ, HIKAZ names no
-    // account, and banks write the account line of a statement (`:25:`) in many ways, so it is not compared with
-    // `account`: a strict comparison would fail every query of such a bank.
+    order: (continuation) =>
+      Segments.transactionsMt940(offered, account, bpd.nationalAccountAllowed, { from, to, continuation }),
+    // The first element holds the booked transactions, the second the pending ones: binary data, which a bank may send
+    // as text instead. Unlike HICAZ, HIKAZ names no account, and banks write the account line of a statement (`:25:`)
+    // in many ways, so it is not compared with `account`: a strict comparison would fail every query of such a bank.
     read: (pages) =>
       mt940Transactions(
         all(pages, 'HIKAZ')
-          .map((s) => s.binary(1))
+          .map((s) => s.bytes(1))
           .filter((d) => d !== undefined),
         all(pages, 'HIKAZ')
-          .map((s) => s.binary(2))
+          .map((s) => s.bytes(2))
           .filter((d) => d !== undefined),
         // The currency of statements that state none.
         account.currency,

package/src/v3/segments.ts

@@ -6,6 +6,7 @@ import { Balance } from '../core/balance.js';
 import { TanMedium, tanMediumStatusOf } from '../tan/tan-models.js';
 import { formatFintsDate, parseFintsDate, parseFintsDateTime } from '../util/dates.js';
 import { FormatError } from '../util/errors.js';
+import { trimBlanks } from '../util/text.js';
 import { type Segment, SegmentSpec, type SegmentValue, Verbatim } from './syntax.js';
 
 /**
@@ -26,9 +27,13 @@ function nationalAccount(a: Account): SegmentValue[] {
   return [a.accountNumber, a.subAccount, a.countryCode, a.bankCode];
 }
 
-/** International account (KTI): IBAN, BIC, then the national account. */
-function internationalAccount(a: Account): SegmentValue[] {
-  return [a.iban, a.bic, ...nationalAccount(a)];
+/**
+ * International account (KTI): IBAN and BIC, then the national account where the bank allows it (HISPAS). An IBAN goes
+ * only with its BIC (Messages B.3.2): without one the national account names the account, where it has a number.
+ */
+function internationalAccount(a: Account, nationalAllowed: boolean): SegmentValue[] {
+  const iban = a.bic !== undefined || a.accountNumber === undefined ? a.iban : undefined;
+  return [iban, a.bic, ...(nationalAllowed || iban === undefined ? nationalAccount(a) : [])];
 }
 
 function dateOrEmpty(date: Date | undefined): string | undefined {
@@ -89,14 +94,10 @@ export const Segments = Object.freeze({
 
   /**
    * HKTAN process 4: asks for strong customer authentication of the `segmentType` sent in the same message, with the TAN
-   * medium `mediumName`, as the bank sent it.
+   * medium `mediumName`: a `Verbatim` where it has to go back as the bank sent it (`ParameterStore.tanMediumToSend`).
    */
-  tanProcess4(version: number, segmentType: string, mediumName?: string): SegmentSpec {
-    return SegmentSpec.numbered('HKTAN', version, {
-      1: '4',
-      2: segmentType,
-      [tanMediumField]: Verbatim.of(mediumName),
-    });
+  tanProcess4(version: number, segmentType: string, mediumName?: string | Verbatim): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, { 1: '4', 2: segmentType, [tanMediumField]: mediumName });
   },
 
   /** HKTAN process 2: submits the TAN (carried in the signature) for the order with `reference`. */
@@ -117,24 +118,28 @@ export const Segments = Object.freeze({
     });
   },
 
-  /** HKSAL: the balance of one account (not of all accounts). */
-  balance(version: number, account: Account, continuation?: string): SegmentSpec {
+  /**
+   * HKSAL: the balance of one account (not of all accounts), named by its national account as well where
+   * `nationalAllowed` (HISPAS).
+   */
+  balance(version: number, account: Account, nationalAllowed: boolean, continuation?: string): SegmentSpec {
     return new SegmentSpec('HKSAL', version, [
-      version >= 7 ? internationalAccount(account) : nationalAccount(account),
+      version >= 7 ? internationalAccount(account, nationalAllowed) : nationalAccount(account),
       false,
       null,
       Verbatim.of(continuation),
     ]);
   },
 
-  /** HKKAZ: MT940 transactions of one account. */
+  /** HKKAZ: MT940 transactions of one account, named by its national account as well where `nationalAllowed`. */
   transactionsMt940(
     version: number,
     account: Account,
+    nationalAllowed: boolean,
     period: { from?: Date | undefined; to?: Date | undefined; continuation?: string | undefined },
   ): SegmentSpec {
     return new SegmentSpec('HKKAZ', version, [
-      version >= 7 ? internationalAccount(account) : nationalAccount(account),
+      version >= 7 ? internationalAccount(account, nationalAllowed) : nationalAccount(account),
       false,
       dateOrEmpty(period.from),
       dateOrEmpty(period.to),
@@ -143,15 +148,19 @@ export const Segments = Object.freeze({
     ]);
   },
 
-  /** HKCAZ: camt transactions of one account in one of `formats`. */
+  /**
+   * HKCAZ: camt transactions of one account in one of `formats`, named by its national account as well where
+   * `nationalAllowed`.
+   */
   transactionsCamt(
     version: number,
     account: Account,
+    nationalAllowed: boolean,
     formats: readonly string[],
     period: { from?: Date | undefined; to?: Date | undefined; continuation?: string | undefined },
   ): SegmentSpec {
     return new SegmentSpec('HKCAZ', version, [
-      internationalAccount(account),
+      internationalAccount(account, nationalAllowed),
       formats,
       false,
       dateOrEmpty(period.from),
@@ -333,8 +342,9 @@ const accountWidth = 4;
 /**
  * Parses the TAN media list (HITAB versions 4 and 5, PIN/TAN "TAN-Medium-Liste").
  *
- * Each name whose text is not what `Segment.verbatim` reads, such as a name in UTF-8, goes into `namesAsSent`, keyed
- * by its text: it has to go back as the bank sent it, which its text does not tell where it fits ISO 8859-1.
+ * Each name whose text would not go back as the bank sent it goes into `namesAsSent` as `Segment.verbatim` reads it,
+ * keyed by its text: a name in UTF-8, which its text does not tell where it fits ISO 8859-1, and one with blanks at
+ * either end, which text goes out without (Formals B.4.1).
  */
 export function parseTanMedia(s: Segment, namesAsSent?: Map<string, string>): TanMedium[] {
   // Version 5 adds the security function in front of the card number.
@@ -352,7 +362,9 @@ export function parseTanMedia(s: Segment, namesAsSent?: Map<string, string>): Ta
     if (mediumClass === undefined) continue;
     const name = fields[after + 3];
     const nameAsSent = s.verbatim(i, after + 3);
-    if (name !== undefined && nameAsSent !== undefined && nameAsSent !== name) namesAsSent?.set(name, nameAsSent);
+    if (name !== undefined && nameAsSent !== undefined && nameAsSent !== trimBlanks(name)) {
+      namesAsSent?.set(name, nameAsSent);
+    }
     media.push(
       new TanMedium({
         mediumClass,

package/src/v3/syntax.ts

@@ -2,7 +2,7 @@
 
 import { BytesBuilder, latin1Decode, latin1Encode, utf8Encode } from '../util/bytes.js';
 import { FormatError } from '../util/errors.js';
-import { decodeBankText, isLatin1, tryParseInt } from '../util/text.js';
+import { decodeBankText, isLatin1, trimBlanks, tryParseInt } from '../util/text.js';
 
 // FinTS 3.0 syntax characters.
 const dataElementSeparator = 0x2b; // '+'
@@ -59,6 +59,8 @@ export class DataElement {
  * Index 0 is the segment header (type, number, version, reference); the data elements follow from index 1.
  */
 export class Segment {
+  private typeValue: string | undefined;
+
   constructor(
     readonly elements: readonly (readonly DataElement[])[],
     /** The bytes the segment was read from: `start` to `end` in `source`, terminator included. */
@@ -68,7 +70,8 @@ export class Segment {
   ) {}
 
   get type(): string {
-    return this.text(0)?.trim() ?? '';
+    this.typeValue ??= trimBlanks(this.text(0) ?? '');
+    return this.typeValue;
   }
 
   get version(): number {
@@ -99,6 +102,12 @@ export class Segment {
     return e?.isBinary === true ? e.bytes : undefined;
   }
 
+  /** The binary data or the text without escape characters at `index`; `undefined` for an empty element. */
+  bytes(index: number, sub = 0): Uint8Array | undefined {
+    const e = this.element(index, sub);
+    return e === undefined || e.isEmpty ? undefined : e.bytes;
+  }
+
   /**
    * The element at `index` as the bank sent it, for a value the client sends back, such as the dialog ID: untrimmed,
    * and one character per byte (ISO 8859-1, the FinTS 3.0 character set), so that `Verbatim` gives the bank back the
@@ -111,7 +120,7 @@ export class Segment {
   }
 
   integer(index: number, sub = 0): number | undefined {
-    return tryParseInt(this.text(index, sub)?.trim());
+    return tryParseInt(this.text(index, sub));
   }
 
   /** The texts of the group at `index`; `undefined` for empty elements. */
@@ -151,17 +160,20 @@ export function encodeText(value: string): Uint8Array {
 }
 
 /**
- * The data elements one message may hold, segment headers and group elements included: several times what the
- * parameter data of a user with hundreds of accounts take, and few enough that a hostile message cannot exhaust the
- * memory, at about `dataElementMemory` bytes each.
+ * The data elements and segments one parse may produce together, segment headers and group elements included: what
+ * the user parameter data of 6,000 accounts take, at about 155 data elements each, which is about what 9,999 KB, the
+ * largest message size HIBPA can state, hold of real data. Without a limit, a message of nothing but separators would
+ * take a hundred times its size in memory.
+ *
+ * @internal Exported for the tests.
  */
-export const maxDataElements = 200_000;
+export const maxParts = 1_000_000;
 
 /**
- * The memory a data element of a received message takes, in bytes, with its share of the segment and of a return code:
- * about this much in V8, however few bytes of the message it is made of.
+ * What `IncomingMessage3.size` counts for each data element it keeps: more than any of them takes once parsed, so that
+ * a message of many short elements counts as the memory it holds rather than its bytes.
  */
-export const dataElementMemory = 256;
+export const parsedElementBytes = 512;
 
 /** Every empty data element of a received segment; it has no bytes to change. */
 const emptyElement = new DataElement(new Uint8Array(0), 0, 0, false);
@@ -184,10 +196,14 @@ function isDigit(byte: number | undefined): boolean {
  *
  * The elements share the memory of `data`. Throws `FormatError` for anything a complete message cannot hold: a
  * malformed binary length, binary data beyond the end of `data` or not followed by a separator, a last segment without
- * terminator, and more elements than `budget` has left, which parses of the same message share.
+ * terminator, and more than `maxParts` data elements and segments, an empty one included.
  */
-export function parseSegments(data: Uint8Array, budget = { elements: maxDataElements }): Segment[] {
+export function parseSegments(data: Uint8Array): Segment[] {
   const segments: Segment[] = [];
+  let parts = 0;
+  const count = (): void => {
+    if (++parts > maxParts) throw new FormatError(`More than ${maxParts} data elements and segments`);
+  };
   // Created with their first element: an array that starts empty reserves room for more than most of them hold.
   let elements: DataElement[][] | undefined;
   let group: DataElement[] | undefined;
@@ -228,7 +244,7 @@ export function parseSegments(data: Uint8Array, budget = { elements: maxDataElem
       i++;
       continue;
     }
-    if (--budget.elements < 0) throw new FormatError('Too many data elements');
+    count();
     if (elements === undefined && group === undefined) segmentStart = i;
     const element = data[i] === binaryMarker ? readBinary() : readText();
     if (group === undefined) group = [element];
@@ -239,6 +255,7 @@ export function parseSegments(data: Uint8Array, budget = { elements: maxDataElem
     else elements.push(group);
     group = undefined;
     if (separator === segmentTerminator) {
+      count();
       const segment = new Segment(elements, data, segmentStart, i);
       // Skip empty segments, such as a stray double terminator.
       if (segment.type !== '') segments.push(segment);
@@ -363,7 +380,7 @@ function encodeValue(value: SingleValue): Uint8Array {
   } else {
     // All but binary data go without leading and trailing blanks (Formals B.4.1). Encode first, then escape the bytes,
     // so that nothing unescaped slips into the syntax.
-    writeEscaped(out, encodeText(String(value).trim()));
+    writeEscaped(out, encodeText(trimBlanks(String(value))));
   }
   return out.takeBytes();
 }