@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/tan/tan-models.ts

@@ -0,0 +1,252 @@
+import { copyDate } from '../util/dates.js';
+import { maskedId } from '../util/text.js';
+
+/** Whether a TAN method needs the name of a TAN medium. */
+export type TanMediumRequirement =
+  /** The method takes no medium name. */
+  | 'notAllowed'
+  /** The method takes a medium name but works without one. */
+  | 'optional'
+  /** The method needs the name of the medium. */
+  | 'required';
+
+/** Reads the FinTS code: `0` not allowed, `1` optional, `2` required. */
+export function tanMediumRequirementOf(code: string | undefined): TanMediumRequirement {
+  return code === '1' ? 'optional' : code === '2' ? 'required' : 'notAllowed';
+}
+
+/** What `TanMethod` takes; the bank states the details it knows. */
+export interface TanMethodInit {
+  securityFunction: string;
+  name: string;
+  technicalId?: string | undefined;
+  dkMethod?: string | undefined;
+  dkVersion?: string | undefined;
+  maxTanLength?: number | undefined;
+  numericTan?: boolean;
+  returnValueText?: string | undefined;
+  maxChallengeLength?: number | undefined;
+  mediumRequirement?: TanMediumRequirement;
+  activeMediaCount?: number | undefined;
+  structuredChallenge?: boolean;
+  decoupled?: boolean;
+  decoupledMaxPolls?: number | undefined;
+  decoupledFirstPollDelaySeconds?: number | undefined;
+  decoupledPollIntervalSeconds?: number | undefined;
+  decoupledManualConfirmation?: boolean;
+  decoupledAutomaticPolling?: boolean;
+}
+
+/** A TAN procedure offered by the bank (FinTS "Sicherheitsfunktion"). */
+export class TanMethod {
+  /** Bank-specific code of the procedure, for example `942`; `999` is the one-step procedure. */
+  readonly securityFunction: string;
+
+  /** The name the bank gives the procedure, for example `pushTAN`. */
+  readonly name: string;
+
+  /** The bank's technical identification of the procedure. */
+  readonly technicalId: string | undefined;
+
+  /** DK procedure family such as `HHD1.4`, `mobileTAN` or `Decoupled`. */
+  readonly dkMethod: string | undefined;
+
+  /** Version of the `dkMethod`. */
+  readonly dkVersion: string | undefined;
+
+  /** Longest TAN the user may enter. */
+  readonly maxTanLength: number | undefined;
+
+  /** Whether the TAN consists of digits only. */
+  readonly numericTan: boolean;
+
+  /** The bank's label for the value the user sends back, for example `TAN`. */
+  readonly returnValueText: string | undefined;
+
+  /** Longest challenge text the bank sends for this procedure. */
+  readonly maxChallengeLength: number | undefined;
+
+  /** Whether a TAN medium name goes with this procedure. */
+  readonly mediumRequirement: TanMediumRequirement;
+
+  /**
+   * Most TAN media a user can have active at once for this procedure, as the bank's parameters state it ("Anzahl
+   * unterstützter aktiver TAN-Medien"); not how many the user has.
+   *
+   * Where it is above 1 and `needsMediumName`, each message names the medium, since the user may have several.
+   */
+  readonly activeMediaCount: number | undefined;
+
+  /** Whether the challenge text is structured (marked up) rather than plain. */
+  readonly structuredChallenge: boolean;
+
+  /** Whether approval happens in a separate app instead of entering a TAN. */
+  readonly decoupled: boolean;
+
+  /**
+   * Most status requests the bank allows for a decoupled approval, 0 for any number. The client sends 60 where the bank
+   * states none, and polls for 10 minutes at most.
+   */
+  readonly decoupledMaxPolls: number | undefined;
+
+  /** How long to wait before the first status request of a decoupled approval, in seconds. */
+  readonly decoupledFirstPollDelaySeconds: number | undefined;
+
+  /** How long to wait between two status requests of a decoupled approval, in seconds. */
+  readonly decoupledPollIntervalSeconds: number | undefined;
+
+  /** Whether the user may report the approval, rather than the client asking the bank by itself. */
+  readonly decoupledManualConfirmation: boolean;
+
+  /** Whether the bank allows the client to ask for the approval by itself. */
+  readonly decoupledAutomaticPolling: boolean;
+
+  constructor(init: TanMethodInit) {
+    this.securityFunction = init.securityFunction;
+    this.name = init.name;
+    this.technicalId = init.technicalId;
+    this.dkMethod = init.dkMethod;
+    this.dkVersion = init.dkVersion;
+    this.maxTanLength = init.maxTanLength;
+    this.numericTan = init.numericTan ?? true;
+    this.returnValueText = init.returnValueText;
+    this.maxChallengeLength = init.maxChallengeLength;
+    this.mediumRequirement = init.mediumRequirement ?? 'notAllowed';
+    this.activeMediaCount = init.activeMediaCount;
+    this.structuredChallenge = init.structuredChallenge ?? false;
+    this.decoupled = init.decoupled ?? false;
+    this.decoupledMaxPolls = init.decoupledMaxPolls;
+    this.decoupledFirstPollDelaySeconds = init.decoupledFirstPollDelaySeconds;
+    this.decoupledPollIntervalSeconds = init.decoupledPollIntervalSeconds;
+    this.decoupledManualConfirmation = init.decoupledManualConfirmation ?? true;
+    this.decoupledAutomaticPolling = init.decoupledAutomaticPolling ?? true;
+  }
+
+  /** The one-step procedure (PIN only, no TAN). */
+  static readonly oneStep = new TanMethod({ securityFunction: '999', name: 'One-step (PIN only)' });
+
+  /** Whether this is the one-step procedure. */
+  get isOneStep(): boolean {
+    return this.securityFunction === TanMethod.oneStep.securityFunction;
+  }
+
+  /** Whether the bank needs the name of a TAN medium for this procedure. */
+  get needsMediumName(): boolean {
+    return this.mediumRequirement === 'required';
+  }
+
+  toString(): string {
+    return `TanMethod(${this.securityFunction}, ${this.name})`;
+  }
+}
+
+/** State of a TAN medium as reported by the bank. */
+export type TanMediumStatus =
+  /** The medium is in use. */
+  | 'active'
+  /** The medium can be used but is not the active one. */
+  | 'available'
+  /** The medium is the active follow-up card. */
+  | 'activeFollowUpCard'
+  /** The medium is an available follow-up card. */
+  | 'availableFollowUpCard'
+  /** The bank states no status, or one that is not known. */
+  | 'unknown';
+
+/** Reads the FinTS code `1` to `4`. */
+export function tanMediumStatusOf(code: string | undefined): TanMediumStatus {
+  switch (code) {
+    case '1':
+      return 'active';
+    case '2':
+      return 'available';
+    case '3':
+      return 'activeFollowUpCard';
+    case '4':
+      return 'availableFollowUpCard';
+    default:
+      return 'unknown';
+  }
+}
+
+/** What `TanMedium` takes; the bank states the details it knows. */
+export interface TanMediumInit {
+  mediumClass: string;
+  status: TanMediumStatus;
+  name?: string | undefined;
+  securityFunction?: string | undefined;
+  cardNumber?: string | undefined;
+  cardSequenceNumber?: string | undefined;
+  mobileNumber?: string | undefined;
+  mobileNumberMasked?: string | undefined;
+  validFrom?: Date | undefined;
+  validUntil?: Date | undefined;
+  lastUsed?: Date | undefined;
+  activatedOn?: Date | undefined;
+}
+
+/** A TAN device registered for the user, such as a phone or TAN generator. */
+export class TanMedium {
+  /** `G` TAN generator, `M` mobile phone, `L` TAN list, `S` secoder, `B` bilateral. */
+  readonly mediumClass: string;
+
+  /** Whether the medium is in use. */
+  readonly status: TanMediumStatus;
+
+  /** The name the medium is registered under; this is what the bank wants back to pick the medium. */
+  readonly name: string | undefined;
+
+  /** The TAN procedure the medium belongs to (HITAB version 5). */
+  readonly securityFunction: string | undefined;
+
+  /** Card number of a TAN generator. */
+  readonly cardNumber: string | undefined;
+
+  /** Sequence number of the card of a TAN generator. */
+  readonly cardSequenceNumber: string | undefined;
+
+  /** Phone number of a mobile phone medium, if the bank states it in full. */
+  readonly mobileNumber: string | undefined;
+
+  /** Phone number with the middle digits hidden. */
+  readonly mobileNumberMasked: string | undefined;
+
+  /** The medium is valid from this date. */
+  readonly validFrom: Date | undefined;
+
+  /** The medium is valid until this date. */
+  readonly validUntil: Date | undefined;
+
+  /** When the medium was used last. */
+  readonly lastUsed: Date | undefined;
+
+  /** When the medium was activated. */
+  readonly activatedOn: Date | undefined;
+
+  /** Takes copies of the dates of `init`: each medium has its own, which no other one shares. */
+  constructor(init: TanMediumInit) {
+    this.mediumClass = init.mediumClass;
+    this.status = init.status;
+    this.name = init.name;
+    this.securityFunction = init.securityFunction;
+    this.cardNumber = init.cardNumber;
+    this.cardSequenceNumber = init.cardSequenceNumber;
+    this.mobileNumber = init.mobileNumber;
+    this.mobileNumberMasked = init.mobileNumberMasked;
+    this.validFrom = copyDate(init.validFrom);
+    this.validUntil = copyDate(init.validUntil);
+    this.lastUsed = copyDate(init.lastUsed);
+    this.activatedOn = copyDate(init.activatedOn);
+  }
+
+  /** Whether the medium is the one in use. */
+  get isActive(): boolean {
+    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. */
+  toString(): string {
+    const label = this.name ?? (this.cardNumber === undefined ? this.mediumClass : maskedId(this.cardNumber));
+    return `TanMedium(${label}, ${this.status})`;
+  }
+}

package/src/util/async.ts

@@ -0,0 +1,48 @@
+/** A promise with its resolve and reject functions, which tells whether it has settled. */
+export class Deferred<T> {
+  readonly promise: Promise<T>;
+  private resolveFn!: (value: T) => void;
+  private rejectFn!: (error: unknown) => void;
+  private settled = false;
+
+  constructor() {
+    this.promise = new Promise<T>((resolve, reject) => {
+      this.resolveFn = resolve;
+      this.rejectFn = reject;
+    });
+    // A rejection nobody waits for is not an unhandled one: whoever awaits the promise still gets it.
+    this.promise.catch(() => undefined);
+  }
+
+  get isCompleted(): boolean {
+    return this.settled;
+  }
+
+  resolve(value: T): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.resolveFn(value);
+  }
+
+  reject(error: unknown): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.rejectFn(error);
+  }
+}
+
+/**
+ * Runs asynchronous actions one after another, in the order they were submitted.
+ *
+ * A failing action does not stop the ones queued after it.
+ */
+export class SerialExecutor {
+  private last: Promise<unknown> = Promise.resolve();
+
+  /** Runs `action` once the actions submitted before have finished; the result is that of `action`. */
+  run<T>(action: () => Promise<T>): Promise<T> {
+    const result = this.last.then(action);
+    this.last = result.catch(() => undefined);
+    return result;
+  }
+}

package/src/util/bytes.ts

@@ -0,0 +1,129 @@
+import { FormatError } from './errors.js';
+
+/** The `parts` joined into one array. */
+export function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+  let length = 0;
+  for (const part of parts) length += part.length;
+  const result = new Uint8Array(length);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+
+/** Collects bytes, like a growing buffer. */
+export class BytesBuilder {
+  private readonly parts: Uint8Array[] = [];
+
+  add(bytes: Uint8Array | readonly number[]): void {
+    this.parts.push(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes));
+  }
+
+  addByte(byte: number): void {
+    this.add(Uint8Array.of(byte));
+  }
+
+  takeBytes(): Uint8Array {
+    const result = concatBytes(this.parts);
+    this.parts.length = 0;
+    return result;
+  }
+}
+
+/** ISO 8859-1 bytes of `text`, which must contain no character beyond U+00FF. */
+export function latin1Encode(text: string): Uint8Array {
+  const bytes = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i) & 0xff;
+  return bytes;
+}
+
+/** The text of ISO 8859-1 `bytes`. */
+export function latin1Decode(bytes: Uint8Array): string {
+  return fromCharCodes(bytes);
+}
+
+/** The text of the UTF-16 code units `codes`. */
+export function fromCharCodes(codes: Uint8Array | Uint16Array): string {
+  let text = '';
+  // In chunks, since a large array exceeds the argument limit of some engines. `apply` takes the array as it is, where a
+  // spread would iterate over it.
+  for (let i = 0; i < codes.length; i += 0x8000) {
+    text += Reflect.apply(String.fromCharCode, undefined, codes.subarray(i, i + 0x8000)) as string;
+  }
+  return text;
+}
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const lenientUtf8Decoder = new TextDecoder('utf-8', { ignoreBOM: true });
+
+export function utf8Encode(text: string): Uint8Array {
+  return utf8Encoder.encode(text);
+}
+
+/** Decodes UTF-8; throws `FormatError` for malformed data unless `allowMalformed`. */
+export function utf8Decode(bytes: Uint8Array, allowMalformed = false): string {
+  try {
+    return (allowMalformed ? lenientUtf8Decoder : utf8Decoder).decode(bytes);
+  } catch {
+    throw new FormatError('Invalid UTF-8');
+  }
+}
+
+const base64Alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const base64Values = (() => {
+  const values = new Int16Array(128).fill(-1);
+  for (let i = 0; i < base64Alphabet.length; i++) values[base64Alphabet.charCodeAt(i)] = i;
+  // The URL-safe alphabet as well.
+  values['-'.charCodeAt(0)] = 62;
+  values['_'.charCodeAt(0)] = 63;
+  return values;
+})();
+
+export function base64Encode(bytes: Uint8Array): string {
+  let out = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8) | bytes[i + 2]!;
+    out +=
+      base64Alphabet[n >> 18]! +
+      base64Alphabet[(n >> 12) & 63]! +
+      base64Alphabet[(n >> 6) & 63]! +
+      base64Alphabet[n & 63]!;
+  }
+  const rest = bytes.length - i;
+  if (rest === 1) {
+    const n = bytes[i]! << 16;
+    out += base64Alphabet[n >> 18]! + base64Alphabet[(n >> 12) & 63]! + '==';
+  } else if (rest === 2) {
+    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8);
+    out += base64Alphabet[n >> 18]! + base64Alphabet[(n >> 12) & 63]! + base64Alphabet[(n >> 6) & 63]! + '=';
+  }
+  return out;
+}
+
+/** Decodes base64, in the standard or the URL-safe alphabet; throws `FormatError` if `text` is not base64. */
+export function base64Decode(text: string): Uint8Array {
+  if (text.length % 4 !== 0) throw new FormatError('Invalid base64 length, must be a multiple of four');
+  let padding = 0;
+  if (text.endsWith('==')) padding = 2;
+  else if (text.endsWith('=')) padding = 1;
+  const out = new Uint8Array((text.length / 4) * 3 - padding);
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    let n = 0;
+    for (let j = 0; j < 4; j++) {
+      const c = text.charCodeAt(i + j);
+      const isPadding = c === 0x3d && i + 4 === text.length && j >= 4 - padding;
+      const value = isPadding ? 0 : c < 128 ? base64Values[c]! : -1;
+      if (value < 0) throw new FormatError('Invalid base64 character', text.charAt(i + j));
+      n = (n << 6) | value;
+    }
+    if (o < out.length) out[o++] = n >> 16;
+    if (o < out.length) out[o++] = (n >> 8) & 0xff;
+    if (o < out.length) out[o++] = n & 0xff;
+  }
+  return out;
+}

package/src/util/call-context.ts

@@ -0,0 +1,41 @@
+/** The part of Node.js's `AsyncLocalStorage` this package uses. */
+interface AsyncStorage<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, callback: () => R): R;
+}
+
+type AsyncStorageConstructor = new <T>() => AsyncStorage<T>;
+
+/**
+ * `AsyncLocalStorage` where the runtime has it, found through `process.getBuiltinModule` (Node.js 22.3, Deno 2.1 and
+ * Bun 1.2.6 or later) rather than by importing `node:async_hooks`, so that bundlers for the browser have nothing to
+ * resolve.
+ */
+const AsyncStorageClass: AsyncStorageConstructor | undefined = (() => {
+  const runtime = globalThis as {
+    process?: { getBuiltinModule?: (id: string) => { AsyncLocalStorage?: AsyncStorageConstructor } | undefined };
+  };
+  try {
+    return runtime.process?.getBuiltinModule?.('node:async_hooks')?.AsyncLocalStorage;
+  } catch {
+    return undefined;
+  }
+})();
+
+/**
+ * Tells which asynchronous call an operation runs in, through every `await` and callback it starts. Where the runtime
+ * cannot track that, as in browsers, `current` is always `undefined`.
+ */
+export class CallContext<T extends object> {
+  private readonly storage: AsyncStorage<T> | undefined = AsyncStorageClass ? new AsyncStorageClass<T>() : undefined;
+
+  /** The value of the call that runs now, if the runtime can tell. */
+  get current(): T | undefined {
+    return this.storage?.getStore();
+  }
+
+  /** Runs `action` as the call `value`. */
+  run<R>(value: T, action: () => R): R {
+    return this.storage ? this.storage.run(value, action) : action();
+  }
+}

package/src/util/dates.ts

@@ -0,0 +1,210 @@
+// 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.
+
+const hourMs = 3_600_000;
+
+function twoDigits(n: number): string {
+  return n.toString().padStart(2, '0');
+}
+
+function year(d: Date): string {
+  return d.getFullYear().toString().padStart(4, '0');
+}
+
+/** `YYYYMMDD`, the FinTS 3.0 date format. */
+export function formatFintsDate(d: Date): string {
+  return `${year(d)}${twoDigits(d.getMonth() + 1)}${twoDigits(d.getDate())}`;
+}
+
+/** `HHMMSS`, the FinTS 3.0 time format. */
+export function formatFintsTime(d: Date): string {
+  return `${twoDigits(d.getHours())}${twoDigits(d.getMinutes())}${twoDigits(d.getSeconds())}`;
+}
+
+/** `YYYY-MM-DD`, the ISO 8601 date format of camt. */
+export function formatIsoDate(d: Date): string {
+  return `${year(d)}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
+}
+
+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})?$/;
+
+/** 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 {
+  return parseDate(fintsDate, date);
+}
+
+/**
+ * Parses a FinTS 3.0 date `YYYYMMDD` and time `HHMMSS` as the moment they name; `undefined` if either is missing or
+ * invalid.
+ */
+export function parseFintsDateTime(date: string | undefined, time: string | undefined): Date | undefined {
+  return moment(parseDate(fintsDate, date), fintsTime, time);
+}
+
+/**
+ * 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.
+ */
+export function parseIsoDate(date: string | undefined): Date | undefined {
+  return parseDate(isoDate, date);
+}
+
+/**
+ * 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.
+ */
+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 parseDate(pattern: RegExp, date: string | undefined): Date | undefined {
+  const d = date === undefined ? null : pattern.exec(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;
+  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);
+}
+
+/**
+ * Parses a FinTS 3.0 date `YYYYMMDD` and time `HHMMSS` given in UTC+01:00 all year round, as the account extension of
+ * the user parameter data states its times (Formals E.3.1); `undefined` if either is missing or invalid. A time with
+ * 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);
+}
+
+/**
+ * The moment a German clock shows the given time.
+ *
+ * German time is CET (UTC+1), and CEST (UTC+2) from 01:00 UTC on the last Sunday of March to 01:00 UTC on the last
+ * Sunday of October (the EU rule). The hour the clocks show twice in October counts as CEST; a time in the hour that is
+ * skipped in March counts as CET.
+ */
+function germanTime(year: number, month: number, day: number, hour: number, minute: number, second: number): Date {
+  const clock = utc(year, month, day, hour, minute, second);
+  const summer = clock - 2 * hourMs;
+  return new Date(isSummerTime(summer) ? summer : clock - hourMs);
+}
+
+/** 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 {
+  const utcMs = moment.getTime();
+  const clock = new Date(utcMs + (isSummerTime(utcMs) ? 2 : 1) * hourMs);
+  return localDate(clock.getUTCFullYear(), clock.getUTCMonth() + 1, clock.getUTCDate());
+}
+
+function isSummerTime(utcMs: number): boolean {
+  const y = new Date(utcMs).getUTCFullYear();
+  return utcMs >= clockChange(y, 3) && utcMs < clockChange(y, 10);
+}
+
+/** 01:00 UTC on the last Sunday of `month`, when the EU changes the clocks. */
+function clockChange(year: number, month: number): number {
+  const lastDay = daysInMonth(year, month);
+  const weekday = new Date(utc(year, month, lastDay, 0, 0, 0)).getUTCDay();
+  return utc(year, month, lastDay - weekday, 1, 0, 0);
+}
+
+/** Milliseconds since the epoch of the UTC time; `month` counts from 1, and years below 100 are not moved to 19xx. */
+function utc(year: number, month: number, day: number, hour: number, minute: number, second: number): number {
+  const d = new Date(0);
+  d.setUTCFullYear(year, month - 1, day);
+  d.setUTCHours(hour, minute, second, 0);
+  return d.getTime();
+}
+
+/** Local midnight of the day; `month` counts from 1, and years below 100 are not moved to 19xx. */
+function localDate(year: number, month: number, day: number): Date {
+  const d = new Date(0);
+  d.setFullYear(year, month - 1, day);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}
+
+/** The date, or `undefined` if `month` or `day` is out of range; `Date` would roll it over into another date. */
+function validDate(year: number, month: number, day: number): Date | undefined {
+  if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) return undefined;
+  return localDate(year, month, day);
+}
+
+/**
+ * The date, with a day beyond the end of the month moved to its last day: banks write 30 February or 31 April for
+ * month-end bookings. `undefined` for a month or day that no month has.
+ */
+export function clampedDate(year: number, month: number, day: number): Date | undefined {
+  if (month < 1 || month > 12 || day < 1 || day > 31) return undefined;
+  return validDate(year, month, day) ?? localDate(year, month, daysInMonth(year, month));
+}
+
+const swiftDate = /^(\d{2})(\d{2})(\d{2})$/;
+
+/**
+ * Parses a SWIFT date `YYMMDD`, as MT940 writes it, with month ends as `clampedDate` reads them; years from 80 on count
+ * as 19xx. `undefined` if the date is invalid.
+ */
+export function parseSwiftDate(yymmdd: string): Date | undefined {
+  const m = swiftDate.exec(yymmdd);
+  if (!m) return undefined;
+  const yy = Number(m[1]);
+  return clampedDate(yy >= 80 ? 1900 + yy : 2000 + yy, Number(m[2]), Number(m[3]));
+}
+
+/** Number of days the `month` (1 to 12) of `year` has. */
+function daysInMonth(year: number, month: number): number {
+  if (month === 2) return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28;
+  return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+
+/** A copy of `d`, so that a model keeps dates of its own: a `Date` can be changed in place. */
+export function copyDate(d: Date): Date;
+export function copyDate(d: Date | undefined): Date | undefined;
+export function copyDate(d: Date | undefined): Date | undefined {
+  return d && new Date(d.getTime());
+}
+
+/** The calendar day `moment` falls on in local time, as a local `Date` at midnight. */
+export function calendarDay(moment: Date): Date {
+  return localDate(moment.getFullYear(), moment.getMonth() + 1, moment.getDate());
+}
+
+/**
+ * The calendar `day`, moved back to the bank's today if it lies after it: banks reject future dates in queries.
+ *
+ * The bank's today is the German day at `now`, the current time by default; east of Germany the local day starts
+ * earlier.
+ */
+export function notAfterToday(day: Date | undefined, now: Date = new Date()): Date | undefined {
+  if (day === undefined) return undefined;
+  const today = germanDay(now);
+  return day.getTime() > today.getTime() ? today : day;
+}