@coderoftime/fints 0.2.0 → 0.3.0

package/src/tan/challenge.ts

@@ -1,6 +1,7 @@
 import { latin1Decode } from '../util/bytes.js';
 import { copyDate } from '../util/dates.js';
-import { characterReference } from '../util/text.js';
+import { frozenWithInspect, inspectCustom } from '../util/inspect.js';
+import { characterReference, trimBlanks } from '../util/text.js';
 import { challengeInstruction, FlickerCode, hasEmbeddedFlickerCode } from './flicker.js';
 import { TanImage } from './tan-image.js';
 import type { TanMedium, TanMethod } from './tan-models.js';
@@ -25,6 +26,9 @@ const formattingTag = /<\/?(?:b|i|u|ul|ol)\b[^<>]*>/gi;
 const entityReference = /&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g;
 const blankLines = /\n{3,}/g;
 
+/** Longest challenge `plainMessage` formats: far longer than the specification allows (an..2048). */
+const maxFormattedLength = 65_536;
+
 const namedEntities: Record<string, string> = {
   amp: '&',
   lt: '<',
@@ -131,8 +135,9 @@ export class TanChallenge {
     if (data !== undefined) {
       image = TanImage.tryParse(data);
       if (image === undefined) flicker = FlickerCode.tryParse(latin1Decode(data));
-    } else if (init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
-      flicker = FlickerCode.tryParse(init.message);
+    }
+    if (image === undefined && init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
+      flicker ??= FlickerCode.tryParse(init.message);
     }
     return new TanChallenge({
       ...init,
@@ -157,7 +162,7 @@ export class TanChallenge {
    * A method with structured challenges (`TanMethod.structuredChallenge`) may use the formatting tags the specification
    * defines. Line breaks, paragraphs and list items become new lines. Bold, italics, underlining and list tags are
    * removed, and the entity references of such markup are resolved. Any other challenge stays as the bank sent it,
-   * which is how the specification wants it shown.
+   * which is how the specification wants it shown. So does a structured challenge of more than 65,536 characters.
    *
    * Show it as text, such as with `textContent`, or `{{ }}` in Vue, and `white-space: pre-line` for its line breaks;
    * never as HTML (`innerHTML`, `v-html`). It keeps the tags the specification does not define, and `&lt;` becomes
@@ -167,19 +172,33 @@ export class TanChallenge {
     const text = this.message;
     if (text === undefined) return undefined;
     const instruction = challengeInstruction(text);
-    if (!this.method.structuredChallenge) return instruction;
-    return instruction
-      .replace(lineBreak, '\n')
-      .replace(blockTag, '\n')
-      .replace(formattingTag, '')
-      .replace(entityReference, (match, name: string) => decodeEntity(name) ?? match)
-      .replace(blankLines, '\n\n')
-      .trim();
+    if (!this.method.structuredChallenge || instruction.length > maxFormattedLength) return instruction;
+    return trimBlanks(
+      instruction
+        .replace(lineBreak, '\n')
+        .replace(blockTag, '\n')
+        .replace(formattingTag, '')
+        .replace(entityReference, (match, name: string) => decodeEntity(name) ?? match)
+        .replace(blankLines, '\n\n'),
+    );
+  }
+
+  /**
+   * What Node.js's `util.inspect` and `console.log` show: the method, the kind of challenge and the attempt; not the
+   * text, the reference, the challenge data, the image or the medium, which may name the user, the account or the order.
+   */
+  [inspectCustom](): string {
+    const kinds = [
+      ...(this.isDecoupled ? ['decoupled'] : []),
+      ...(this.flickerCode === undefined ? [] : ['flicker code']),
+      ...(this.image === undefined ? [] : ['image']),
+    ];
+    return `TanChallenge(${[this.method.toString(), ...kinds, `attempt ${this.attempt}`].join(', ')})`;
   }
 }
 
 // Copies of a challenge for the prompts of one approval. Not methods of `TanChallenge`, so that they are not part of its
-// API; they stand beside the class, so that a field added to it is added here as well.
+// API. The own fields of a challenge are those of `TanChallengeInit`, so a copy spreads it.
 
 /** `challenge` again, counted as the next prompt for the same approval, with the bank's new instructions `message`. */
 export function nextAttempt(challenge: TanChallenge, message?: string): TanChallenge {
@@ -192,27 +211,15 @@ export function withResolved(challenge: TanChallenge, resolved: Promise<void>):
 }
 
 function copyChallenge(challenge: TanChallenge, changes: Partial<TanChallengeInit>): TanChallenge {
-  return new TanChallenge({
-    method: challenge.method,
-    reference: challenge.reference,
-    message: challenge.message,
-    hhdUc: challenge.hhdUc,
-    flickerCode: challenge.flickerCode,
-    image: challenge.image,
-    isDecoupled: challenge.isDecoupled,
-    validUntil: challenge.validUntil,
-    tanMediumName: challenge.tanMediumName,
-    attempt: challenge.attempt,
-    resolved: challenge.resolved,
-    ...changes,
-  });
+  const init: TanChallengeInit = challenge;
+  return new TanChallenge({ ...init, ...changes });
 }
 
 /** The user's answer to a `TanChallenge`: `TanAnswer.tan(…)`, `TanAnswer.approved` or `TanAnswer.cancelled`. */
 export type TanAnswer =
   /**
-   * The TAN the user entered; an empty one cancels a TAN challenge. Blanks around it do not count, and digits of
-   * another width, such as full-width ones, count as the digits they are (Unicode NFKC).
+   * The TAN the user entered; an empty one cancels a TAN challenge. Blanks around it do not count, and full-width
+   * characters, as East Asian input methods type them, count as their ASCII counterparts.
    */
   | { readonly kind: 'tan'; readonly tan: string }
   /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
@@ -220,13 +227,18 @@ export type TanAnswer =
   /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
   | { readonly kind: 'cancelled' };
 
-const approvedAnswer: TanAnswer = Object.freeze({ kind: 'approved' });
-const cancelledAnswer: TanAnswer = Object.freeze({ kind: 'cancelled' });
+/** `answer` frozen, which `util.inspect` shows by its kind, never with the TAN. */
+function frozenAnswer(answer: TanAnswer): TanAnswer {
+  return frozenWithInspect(answer, (a) => `TanAnswer(${a.kind})`);
+}
+
+const approvedAnswer = frozenAnswer({ kind: 'approved' });
+const cancelledAnswer = frozenAnswer({ kind: 'cancelled' });
 
 /** The answers a `TanCallback` returns. */
 export const TanAnswer = Object.freeze({
   /** The TAN the user entered; an empty one cancels a TAN challenge (`TanAnswer`). */
-  tan: (tan: string): TanAnswer => Object.freeze({ kind: 'tan', tan }),
+  tan: (tan: string): TanAnswer => frozenAnswer({ kind: 'tan', tan }),
   /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
   approved: approvedAnswer,
   /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
@@ -252,10 +264,12 @@ export const TanAnswer = Object.freeze({
  */
 export type TanCallback = (challenge: TanChallenge) => TanAnswer | Promise<TanAnswer>;
 
-/** Picks one of several allowed TAN methods; the first is used when this returns `undefined`. */
+/** Picks one of several allowed TAN methods; the first is used when this returns `undefined` or `null`. */
 export type TanMethodSelector = (
   methods: readonly TanMethod[],
-) => TanMethod | undefined | Promise<TanMethod | undefined>;
+) => TanMethod | null | undefined | Promise<TanMethod | null | undefined>;
 
-/** Picks one of several active TAN media; the first is used when this returns `undefined`. */
-export type TanMediumSelector = (media: readonly TanMedium[]) => TanMedium | undefined | Promise<TanMedium | undefined>;
+/** Picks one of several active TAN media; the first is used when this returns `undefined` or `null`. */
+export type TanMediumSelector = (
+  media: readonly TanMedium[],
+) => TanMedium | null | undefined | Promise<TanMedium | null | undefined>;

package/src/tan/flicker.ts

@@ -1,5 +1,6 @@
 import { FormatError } from '../util/errors.js';
-import { withoutWhitespace } from '../util/text.js';
+import { inspectCustom } from '../util/inspect.js';
+import { trimBlanks, withoutWhitespace } from '../util/text.js';
 
 /** Version of the chipTAN HHD specification a flicker code follows: 1.3, or 1.4, which adds control bytes. */
 export type HhdVersion = 'hhd13' | 'hhd14';
@@ -10,17 +11,29 @@ const codeMarker = 'CHLGUC';
 const textMarker = 'CHLGTEXT';
 const markerLengthDigits = 4;
 
+/**
+ * The flicker code and the instruction text of a combined challenge; `undefined` unless `message` starts with
+ * `CHLGUC`, after blanks, and states the length of the code. White space in the code wraps lines and is dropped.
+ */
+function splitCombined(message: string): { code: string; instruction: string } | undefined {
+  const text = trimBlanks(message, { end: false });
+  const end = text.indexOf(textMarker);
+  if (!text.startsWith(codeMarker) || end < 0) return undefined;
+  const lengthAndCode = withoutWhitespace(text.substring(codeMarker.length, end));
+  const code = lengthAndCode.substring(markerLengthDigits);
+  const length = lengthAndCode.substring(0, markerLengthDigits);
+  if (!/^[0-9]{4}$/.test(length) || parseInt(length, 10) !== code.length) return undefined;
+  return { code, instruction: text.substring(end + textMarker.length + markerLengthDigits) };
+}
+
 /** Whether `message` is a combined challenge with an embedded flicker code. */
 export function hasEmbeddedFlickerCode(message: string): boolean {
-  return message.includes(codeMarker);
+  return splitCombined(message) !== undefined;
 }
 
 /** The instruction text of a combined challenge; `message` itself if it is none. */
 export function challengeInstruction(message: string): string {
-  const start = message.indexOf(textMarker);
-  if (start < 0) return message;
-  const textStart = start + textMarker.length + markerLengthDigits;
-  return textStart < message.length ? message.substring(textStart) : '';
+  return splitCombined(message)?.instruction ?? message;
 }
 
 /**
@@ -60,15 +73,16 @@ export class FlickerCode {
   ) {}
 
   /**
-   * Parses the challenge data sent by the bank; throws `FormatError` if it is not a flicker code a TAN generator can
+   * Parses the challenge data sent by the bank, the code itself or a combined challenge, which embeds it in the
+   * challenge text (`CHLGUC`), wrapped into lines; throws `FormatError` if it is not a flicker code a TAN generator can
    * take: one with characters after the length it states, an empty data element, data other than printable ASCII, or
    * more data than its length fields can state, such as more than 15 bytes in an element in HHD 1.3 or 255 bytes in all.
    */
   static parse(code: string): FlickerCode {
-    const cleaned = extractCode(code);
+    const embedded = splitCombined(code)?.code ?? trimBlanks(code);
     for (const layout of layouts) {
       try {
-        return FlickerCode.parseLayout(new Reader(cleaned), layout.lcDigits, layout.lengthDigits);
+        return FlickerCode.parseLayout(new Reader(embedded), layout.lcDigits, layout.lengthDigits);
       } catch (error) {
         // Not this layout; try the next one.
         if (!(error instanceof FormatError)) throw error;
@@ -96,14 +110,15 @@ export class FlickerCode {
     const controlBytes: number[] = [];
     if ((startLength & 0x80) !== 0) {
       do {
+        if (controlBytes.length === 10) throw new FormatError('Too many control bytes in flicker code');
         controlBytes.push(challenge.hex(2));
-      } while ((controlBytes.at(-1)! & 0x80) !== 0 && controlBytes.length < 10);
+      } while ((controlBytes.at(-1)! & 0x80) !== 0);
     }
-    const startCode = new StartCode(challenge.take(startLength & 0x3f), controlBytes);
+    const startCode = new StartCode(challenge.take(elementLength(startLength & 0x7f)), controlBytes);
     const dataElements: DataElement[] = [];
     for (let i = 0; i < 3; i++) {
       dataElements.push(
-        new DataElement(challenge.isAtEnd ? undefined : challenge.take(challenge.dataLength(lengthDigits))),
+        new DataElement(challenge.isAtEnd ? undefined : challenge.take(elementLength(challenge.decimal(lengthDigits)))),
       );
     }
     // Only a layout whose fields fill exactly the LC characters, which end the code, can be the right one.
@@ -183,15 +198,21 @@ export class FlickerCode {
     }
     return result;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: the version, not the data, which may hold IBAN and amount. */
+  [inspectCustom](): string {
+    return `FlickerCode(${this.version})`;
+  }
 }
 
-/** The code of a combined challenge, or `code` itself without whitespace. */
-function extractCode(code: string): string {
-  const compact = withoutWhitespace(code);
-  const start = compact.indexOf(codeMarker);
-  const codeStart = start + codeMarker.length + markerLengthDigits;
-  const end = compact.indexOf(textMarker);
-  return start >= 0 && end >= codeStart ? compact.substring(codeStart, end) : compact;
+/**
+ * The length a field of the challenge states for the start code or a data element: 1 to 63 characters. The challenge
+ * leaves out an element without data and sets no flag in bit 6, which only the rendered code carries; bit 7 of the start
+ * code, which announces control bytes, is masked off before.
+ */
+function elementLength(length: number): number {
+  if (length === 0 || length > 0x3f) throw new FormatError('Invalid data element length');
+  return length;
 }
 
 function xorChecksum(payload: string): string {
@@ -238,16 +259,6 @@ class Reader {
     return parseInt(Reader.match(/^[0-9A-Fa-f]+$/, this.take(digits)), 16);
   }
 
-  /**
-   * A data element length field (LDE) of `digits` decimal digits: 1 to 63 characters. The challenge leaves out an
-   * element without data, and sets none of the flags in bits 6 and 7, which only the rendered code carries.
-   */
-  dataLength(digits: number): number {
-    const length = this.decimal(digits);
-    if (length === 0 || length > 0x3f) throw new FormatError('Invalid data element length');
-    return length;
-  }
-
   private static match(pattern: RegExp, field: string): string {
     if (!pattern.test(field)) throw new FormatError('Invalid length field', field);
     return field;

package/src/tan/tan-image.ts

@@ -1,4 +1,6 @@
 import { base64Encode, latin1Decode } from '../util/bytes.js';
+import { inspectCustom } from '../util/inspect.js';
+import { counted } from '../util/text.js';
 
 /** The formats of photoTAN and QR-TAN images: raster images, which unlike SVG cannot carry scripts. */
 const imageMimeTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp']);
@@ -16,7 +18,7 @@ export class TanImage {
    * Reads the bank's image container: a two-byte length and the MIME type, then a two-byte length and the image.
    *
    * `undefined` unless the MIME type, in any case, is that of a PNG, JPEG, GIF, WebP or BMP image, and the container
-   * holds the whole image.
+   * holds the whole image, of at least one byte.
    */
   static tryParse(data: Uint8Array): TanImage | undefined {
     if (data.length < 4) return undefined;
@@ -27,7 +29,7 @@ export class TanImage {
     const offset = 2 + mimeLength;
     const imageLength = (data[offset]! << 8) | data[offset + 1]!;
     const start = offset + 2;
-    if (start + imageLength > data.length) return undefined;
+    if (imageLength === 0 || start + imageLength > data.length) return undefined;
     return new TanImage(mime, data.subarray(start, start + imageLength));
   }
 
@@ -35,4 +37,9 @@ export class TanImage {
   toDataUrl(): string {
     return `data:${this.mimeType};base64,${base64Encode(this.bytes)}`;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: type and size, not the image, which shows the order. */
+  [inspectCustom](): string {
+    return `TanImage(${this.mimeType}, ${counted(this.bytes.length, 'byte')})`;
+  }
 }

package/src/tan/tan-models.ts

@@ -1,4 +1,5 @@
 import { copyDate } from '../util/dates.js';
+import { inspectCustom } from '../util/inspect.js';
 import { maskedId } from '../util/text.js';
 
 /** Whether a TAN method needs the name of a TAN medium. */
@@ -138,6 +139,11 @@ export class TanMethod {
   toString(): string {
     return `TanMethod(${this.securityFunction}, ${this.name})`;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: `toString`, not the fields. */
+  [inspectCustom](): string {
+    return this.toString();
+  }
 }
 
 /** State of a TAN medium as reported by the bank. */
@@ -244,9 +250,17 @@ export class TanMedium {
     return this.status === 'active' || this.status === 'activeFollowUpCard';
   }
 
-  /** The name, or the last digits of the card number, so that logs and crash reports do not collect the number. */
+  /**
+   * The medium class, or the last digits of the card number, and the status: no name, which the user may have given the
+   * medium after themselves, such as `Max’s iPhone`, so that logs and crash reports collect neither.
+   */
   toString(): string {
-    const label = this.name ?? (this.cardNumber === undefined ? this.mediumClass : maskedId(this.cardNumber));
+    const label = this.cardNumber === undefined ? this.mediumClass : maskedId(this.cardNumber);
     return `TanMedium(${label}, ${this.status})`;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: `toString`, not the fields. */
+  [inspectCustom](): string {
+    return this.toString();
+  }
 }

package/src/util/arguments.ts

@@ -0,0 +1,40 @@
+import { invalidArgument } from './errors.js';
+
+// Plain JavaScript passes arguments of types the declarations rule out, which the Dart package's types refuse. These
+// checks refuse them as well, with messages that leave out the value.
+
+/** `value`; throws `TypeError` unless it is a string. */
+export function requireString(value: unknown, name: string): string {
+  if (typeof value !== 'string') throw invalidArgument('Must be a string', name);
+  return value;
+}
+
+/** `value`, `undefined` for `null`; throws `TypeError` unless it is a string or neither. */
+export function optionalString(value: unknown, name: string): string | undefined {
+  return value === undefined || value === null ? undefined : requireString(value, name);
+}
+
+/** `value`, `undefined` for `null`; throws `TypeError` unless it is an integer or neither. */
+export function optionalInteger(value: unknown, name: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isInteger(value)) throw invalidArgument('Must be an integer', name);
+  return value as number;
+}
+
+/** `value`, `undefined` for `null`; throws `TypeError` unless it is a boolean or neither. */
+export function optionalBoolean(value: unknown, name: string): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'boolean') throw invalidArgument('Must be a boolean', name);
+  return value;
+}
+
+/** `value`; throws `TypeError` unless it is a function. */
+export function requireFunction<F>(value: F, name: string): F {
+  if (typeof value !== 'function') throw invalidArgument('Must be a function', name);
+  return value;
+}
+
+/** `value`, `undefined` for `null`; throws `TypeError` unless it is a function or neither. */
+export function optionalFunction<F>(value: F | null | undefined, name: string): F | undefined {
+  return value === undefined || value === null ? undefined : requireFunction(value, name);
+}

package/src/util/async.ts

@@ -37,12 +37,18 @@ export class Deferred<T> {
  * A failing action does not stop the ones queued after it.
  */
 export class SerialExecutor {
-  private last: Promise<unknown> = Promise.resolve();
+  private last: Promise<void> = Promise.resolve();
 
-  /** Runs `action` once the actions submitted before have finished; the result is that of `action`. */
+  /**
+   * Runs `action` once the actions submitted before have finished; the result is that of `action`, which the executor
+   * does not keep.
+   */
   run<T>(action: () => Promise<T>): Promise<T> {
-    const result = this.last.then(action);
-    this.last = result.catch(() => undefined);
+    const result = this.last.then(() => action());
+    this.last = result.then(
+      () => undefined,
+      () => undefined,
+    );
     return result;
   }
 }

package/src/util/bytes.ts

@@ -56,14 +56,14 @@ export function fromCharCodes(codes: Uint8Array | Uint16Array): string {
 }
 
 const utf8Encoder = new TextEncoder();
-const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
-const lenientUtf8Decoder = new TextDecoder('utf-8', { ignoreBOM: true });
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+const lenientUtf8Decoder = new TextDecoder('utf-8');
 
 export function utf8Encode(text: string): Uint8Array {
   return utf8Encoder.encode(text);
 }
 
-/** Decodes UTF-8; throws `FormatError` for malformed data unless `allowMalformed`. */
+/** Decodes UTF-8, without a leading BOM; throws `FormatError` for malformed data unless `allowMalformed`. */
 export function utf8Decode(bytes: Uint8Array, allowMalformed = false): string {
   try {
     return (allowMalformed ? lenientUtf8Decoder : utf8Decoder).decode(bytes);

package/src/util/dates.ts

@@ -1,6 +1,7 @@
 // A value is either a calendar date, a local `Date` at midnight of which only the day counts, or the exact moment of a
-// date with a time of day, which the bank states in German time (see `germanTime`). The parsers keep the two apart: a
-// date without a valid time of day is not a moment.
+// date with a time of day, which the bank states in German time (see `germanTime`) unless it gives the UTC offset. The
+// parsers keep the two apart: a date without a valid time of day is not a moment. A time of day runs from 00:00:00 to
+// 23:59:59, and 24:00:00, which ISO 8601 and XML Schema allow for the end of a day, is midnight of the next.
 
 const hourMs = 3_600_000;
 
@@ -30,8 +31,11 @@ export function formatIsoDate(d: Date): string {
 const fintsDate = /^(\d{4})(\d{2})(\d{2})$/;
 const fintsTime = /^(\d{2})(\d{2})(\d{2})/;
 const isoDate = /^(\d{4})-(\d{2})-(\d{2})/;
-const isoTime = /^(\d{2}):(\d{2}):(\d{2})/;
-const isoDateTime = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})(?:\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
+// The time of an XML Schema `dateTime`, whose UTC offset lies between -14:00 and +14:00.
+const isoTime = /^(\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-](?:(?:0\d|1[0-3]):[0-5]\d|14:00))?$/;
+
+/** A date and time of day as a clock shows them, the month counted from 1. */
+type Clock = [year: number, month: number, day: number, hour: number, minute: number, second: number];
 
 /** Parses a FinTS 3.0 date `YYYYMMDD` as a calendar date; `undefined` if it is missing or invalid. */
 export function parseFintsDate(date: string | undefined): Date | undefined {
@@ -43,52 +47,64 @@ export function parseFintsDate(date: string | undefined): Date | undefined {
  * invalid.
  */
 export function parseFintsDateTime(date: string | undefined, time: string | undefined): Date | undefined {
-  return moment(parseDate(fintsDate, date), fintsTime, time);
+  const clock = clockOn(parseDate(fintsDate, date), match(fintsTime, time));
+  return clock && germanTime(...clock);
 }
 
 /**
- * Parses an ISO 8601 date `YYYY-MM-DD` as a calendar date, ignoring extra characters such as a time part; `undefined`
- * if it is missing or invalid.
+ * Parses an ISO 8601 date `YYYY-MM-DD` as a calendar date, ignoring what follows it, such as a time zone; `undefined`
+ * if it is missing or invalid. A `T` right after the date makes it a date and time, which must be one `parseIsoMoment`
+ * reads, and the date the day in Germany at that moment: for a time in UTC late in the evening, the next day.
  */
 export function parseIsoDate(date: string | undefined): Date | undefined {
-  return parseDate(isoDate, date);
+  if (date?.charAt(10) !== 'T') return parseDate(isoDate, date);
+  const moment = parseIsoMoment(date);
+  return moment && germanDay(moment);
 }
 
 /**
  * Parses an ISO 8601 date and time as XML Schema writes it, `YYYY-MM-DDThh:mm:ss` with optional fractional seconds and
- * UTC offset (`Z` or `±hh:mm`), as the moment it names, to the second: in German time where it states no offset.
- * `undefined` if it is missing or invalid.
+ * UTC offset (`Z` or `±hh:mm` up to ±14:00), as the moment it names, to the second: in German time where it states no
+ * offset. `undefined` if it is invalid.
  */
-export function parseIsoMoment(dateTime: string | undefined): Date | undefined {
-  const m = dateTime === undefined ? null : isoDateTime.exec(dateTime);
-  if (!m) return undefined;
-  const [, date, time, offset] = m;
-  const german = moment(parseIsoDate(date), isoTime, time);
-  if (german === undefined || offset === undefined) return german;
-  // Every engine reads a valid date and time with an offset alike (ECMAScript Date Time String Format), but some roll
-  // an invalid date, such as 30 February, over into the next month: `german` has checked them.
-  const exact = new Date(`${date}T${time}${offset}`);
-  return Number.isNaN(exact.getTime()) ? undefined : exact;
+function parseIsoMoment(dateTime: string): Date | undefined {
+  const t = isoTime.exec(dateTime.slice(11));
+  const clock = clockOn(parseDate(isoDate, dateTime), t);
+  if (clock === undefined) return undefined;
+  const zone = t?.[5];
+  return zone === undefined ? germanTime(...clock) : new Date(utc(...clock) - offsetMs(zone));
+}
+
+/** The UTC offset `Z` or `±hh:mm` in milliseconds. */
+function offsetMs(zone: string): number {
+  if (zone === 'Z') return 0;
+  const ms = (Number(zone.slice(1, 3)) * 60 + Number(zone.slice(4))) * 60_000;
+  return zone.startsWith('-') ? -ms : ms;
+}
+
+function match(pattern: RegExp, text: string | undefined): RegExpExecArray | null {
+  return text === undefined ? null : pattern.exec(text);
 }
 
 function parseDate(pattern: RegExp, date: string | undefined): Date | undefined {
-  const d = date === undefined ? null : pattern.exec(date);
+  const d = match(pattern, date);
   return d ? validDate(Number(d[1]), Number(d[2]), Number(d[3])) : undefined;
 }
 
-/** Hour, minute and second of the time matched by `pattern` in `time`; `undefined` if it is missing or invalid. */
-function parseTime(pattern: RegExp, time: string | undefined): [number, number, number] | undefined {
-  const t = time === undefined ? null : pattern.exec(time);
-  if (!t) return undefined;
+/**
+ * The time of day `t` on `day`, where `t` matched hour, minute and second, and maybe a fraction of a second after them;
+ * `undefined` if either is missing or the time is invalid.
+ */
+function clockOn(day: Date | undefined, t: RegExpExecArray | null): Clock | undefined {
+  if (day === undefined || !t) return undefined;
   const [hour, minute, second] = [Number(t[1]), Number(t[2]), Number(t[3])];
-  return hour > 23 || minute > 59 || second > 59 ? undefined : [hour, minute, second];
-}
-
-/** The moment of the German time matched by `timePattern` in `time` on `day`. */
-function moment(day: Date | undefined, timePattern: RegExp, time: string | undefined): Date | undefined {
-  const t = parseTime(timePattern, time);
-  if (day === undefined || t === undefined) return undefined;
-  return germanTime(day.getFullYear(), day.getMonth() + 1, day.getDate(), ...t);
+  // The fraction counts only here: 24:00:00.5 lies past the end of the day.
+  if (hour === 24 && minute === 0 && second === 0 && !/[1-9]/.test(t[4] ?? '')) {
+    const next = localDate(day.getFullYear(), day.getMonth() + 1, day.getDate() + 1);
+    return [next.getFullYear(), next.getMonth() + 1, next.getDate(), 0, 0, 0];
+  }
+  if (hour > 23 || minute > 59 || second > 59) return undefined;
+  return [day.getFullYear(), day.getMonth() + 1, day.getDate(), hour, minute, second];
 }
 
 /**
@@ -97,10 +113,8 @@ function moment(day: Date | undefined, timePattern: RegExp, time: string | undef
  * fewer than six digits lost its leading zeros as a JSON number.
  */
 export function parseUtcPlusOneDateTime(date: string | undefined, time: string | undefined): Date | undefined {
-  const day = parseDate(fintsDate, date);
-  const t = parseTime(fintsTime, time?.padStart(6, '0'));
-  if (day === undefined || t === undefined) return undefined;
-  return new Date(utc(day.getFullYear(), day.getMonth() + 1, day.getDate(), ...t) - hourMs);
+  const clock = clockOn(parseDate(fintsDate, date), match(fintsTime, time?.padStart(6, '0')));
+  return clock && new Date(utc(...clock) - hourMs);
 }
 
 /**
@@ -117,7 +131,7 @@ function germanTime(year: number, month: number, day: number, hour: number, minu
 }
 
 /** The calendar day a German clock shows at `moment`, as a local `Date` at midnight like every calendar date. */
-export function germanDay(moment: Date): Date {
+function germanDay(moment: Date): Date {
   const utcMs = moment.getTime();
   const clock = new Date(utcMs + (isSummerTime(utcMs) ? 2 : 1) * hourMs);
   return localDate(clock.getUTCFullYear(), clock.getUTCMonth() + 1, clock.getUTCDate());

package/src/util/errors.ts

@@ -2,17 +2,22 @@
  * Data that do not have the expected format, such as a malformed MT940 line or amount.
  *
  * The message leaves out `source`, which may hold account data, such as amounts, names and IBANs, so that logs and
- * crash reports do not collect them.
+ * crash reports do not collect them. For the same reason `source` is a getter, not a field: `JSON.stringify` and
+ * Node.js's report of an uncaught error show an error's fields as they are.
  */
 export class FormatError extends Error {
   override name = 'FormatError';
 
-  /** The part of the data that is malformed, where the parser can tell it. */
-  readonly source: string | undefined;
+  readonly #source: string | undefined;
 
   constructor(message: string, source?: string) {
     super(message);
-    this.source = source;
+    this.#source = source;
+  }
+
+  /** The part of the data that is malformed, where the parser can tell it. */
+  get source(): string | undefined {
+    return this.#source;
   }
 }