@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/v3/account-extension.ts

@@ -0,0 +1,190 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { AccountDataStatus, type Account } from '../core/account.js';
+import { Amount, withMark } from '../core/amount.js';
+import { Balance } from '../core/balance.js';
+import { parseFintsDate, parseUtcPlusOneDateTime } from '../util/dates.js';
+import { FormatError } from '../util/errors.js';
+
+/** A booked or pending balance of the extension: credit/debit mark, value, date and time. */
+interface Saldo {
+  readonly amount: Amount;
+  readonly date: Date;
+  readonly time: Date | undefined;
+}
+
+/** The balance of the extension (`AcctBal`, built like HISAL version 7), read without the account it belongs to. */
+interface AccountBalance {
+  readonly booked: Saldo;
+  readonly pending: Saldo | undefined;
+  readonly creditLine: Amount | undefined;
+  readonly available: Amount | undefined;
+  readonly used: Amount | undefined;
+  readonly overdraft: Amount | undefined;
+  readonly bookingDate: Date | undefined;
+  readonly bookingTime: Date | undefined;
+}
+
+/**
+ * The account extension of the user parameter data (HIUPD "Erweiterung, kontobezogen", Formals E.3.1): JSON with the
+ * BIC, the balance, and what the bank tells about the data it holds for the account.
+ */
+export class AccountExtension {
+  private constructor(
+    /** The BIC of the account, which spares the SEPA account list (Formals F.3.4). */
+    readonly bic: string | undefined,
+    /** What the bank tells about the account's data. */
+    readonly status: AccountDataStatus,
+    private readonly balance: AccountBalance | undefined,
+    /** Whether `balance` holds all a balance query would deliver (`BalComplete`). */
+    private readonly balanceComplete: boolean,
+  ) {}
+
+  /**
+   * Reads `json`; `undefined` if it is not a JSON object or any element is malformed, which voids the whole extension
+   * (Formals F.2, KF3).
+   */
+  static tryParse(json: string): AccountExtension | undefined {
+    try {
+      const decoded: unknown = JSON.parse(json);
+      return isObject(decoded) ? AccountExtension.read(new Json(decoded)) : undefined;
+    } catch (error) {
+      if (error instanceof FormatError || error instanceof SyntaxError) return undefined;
+      throw error;
+    }
+  }
+
+  private static read(json: Json): AccountExtension {
+    const balance = json.object('AcctBal');
+    const next = json.object('AcctStatNext');
+    return new AccountExtension(
+      json.string('BIC'),
+      new AccountDataStatus({
+        inventory: json.object('Inventory')?.strings ?? new Map(),
+        lastTransactions: json.string('umsltzt'),
+        nextTransactionsAt: next === undefined ? undefined : moment(next, '000000'),
+        transactionBalancesCurrent: json.flag('BalStatAcct') || json.flag('BalStatAct'),
+      }),
+      balance === undefined ? undefined : readBalance(balance),
+      json.flag('BalComplete'),
+    );
+  }
+
+  /** The balance of `account`, where the extension holds all a balance query would deliver (Formals F.3.2). */
+  completeBalance(account: Account): Balance | undefined {
+    const b = this.balance;
+    if (b === undefined || !this.balanceComplete) return undefined;
+    return new Balance({
+      account,
+      booked: b.booked.amount,
+      bookedAsOf: b.booked.date,
+      bookedAsOfTime: b.booked.time,
+      pending: b.pending?.amount,
+      creditLine: b.creditLine,
+      available: b.available,
+      used: b.used,
+      overdraft: b.overdraft,
+      bookingDate: b.bookingDate,
+      bookingTime: b.bookingTime,
+    });
+  }
+}
+
+function readBalance(json: Json): AccountBalance {
+  const currency = json.string('Cur') ?? fail('Extension balance without currency');
+  const amount = (key: string): Amount | undefined => {
+    const value = json.string(key);
+    return value === undefined ? undefined : Amount.parseDecimal(value, currency);
+  };
+  const saldo = (key: string): Saldo | undefined => {
+    const s = json.object(key);
+    if (s === undefined) return undefined;
+    const value = s.string('Val') ?? fail('Extension balance without value');
+    return {
+      amount: withMark(Amount.parseDecimal(value, currency), s.string('DebCrd'), 'C', 'D'),
+      date: parseFintsDate(s.string('Date')) ?? fail('Extension balance without date'),
+      time: moment(s),
+    };
+  };
+  const bookTime = json.object('BookTime');
+  return {
+    booked: saldo('CurValBal') ?? fail('Extension balance without booked balance'),
+    pending: saldo('InclPendTransBal'),
+    creditLine: amount('OverdraftLim'),
+    available: amount('AvailFunds'),
+    used: amount('AlrdyDrwnOnBal'),
+    overdraft: amount('OverDraft'),
+    bookingDate: bookTime === undefined ? undefined : parseFintsDate(bookTime.string('Date')),
+    bookingTime: bookTime === undefined ? undefined : moment(bookTime),
+  };
+}
+
+/**
+ * The moment of `Date` and `Time` in `json`, which the extension states in UTC+01:00 all year round; `undefined`
+ * without a time, unless `defaultTime` stands in for it.
+ */
+function moment(json: Json, defaultTime?: string): Date | undefined {
+  const time = json.string('Time') ?? defaultTime;
+  if (time === undefined) return undefined;
+  return parseUtcPlusOneDateTime(json.string('Date'), time) ?? fail('Extension date or time is malformed');
+}
+
+function fail(message: string): never {
+  throw new FormatError(message);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A JSON object of the extension, read by key without regard to case: the specification itself spells some keys
+ * differently (`OverDraftLim` and `OverdraftLim`). Values of the wrong type are a `FormatError`.
+ */
+class Json {
+  private readonly values = new Map<string, unknown>();
+
+  constructor(values: Record<string, unknown>) {
+    for (const [key, value] of Object.entries(values)) this.values.set(key.toLowerCase(), value);
+  }
+
+  private value(key: string): unknown {
+    return this.values.get(key.toLowerCase());
+  }
+
+  /** A string, or a number written as string: dates and times come as either. */
+  string(key: string): string | undefined {
+    const value = this.value(key);
+    if (value === undefined || value === null) return undefined;
+    if (typeof value === 'string') return value.trim() === '' ? undefined : value.trim();
+    if (typeof value === 'number') return String(value);
+    throw new FormatError(`Extension element "${key}" is not text`);
+  }
+
+  flag(key: string): boolean {
+    const value = this.value(key);
+    if (value === undefined || value === null) return false;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') return value === 'J' || value.toLowerCase() === 'true';
+    throw new FormatError(`Extension element "${key}" is not a flag`);
+  }
+
+  object(key: string): Json | undefined {
+    const value = this.value(key);
+    if (value === undefined || value === null) return undefined;
+    if (isObject(value)) return new Json(value);
+    throw new FormatError(`Extension element "${key}" is not an object`);
+  }
+
+  /** The object's values as strings, keyed in capitals, as segment IDs are written. */
+  get strings(): Map<string, string> {
+    const result = new Map<string, string>();
+    for (const [key, value] of this.values) {
+      if (value === null) result.set(key.toUpperCase(), '');
+      else if (typeof value === 'string') result.set(key.toUpperCase(), value);
+      else if (typeof value === 'number') result.set(key.toUpperCase(), String(value));
+      else throw new FormatError(`Extension element "${key}" is not text`);
+    }
+    return result;
+  }
+}

package/src/v3/client.ts

@@ -0,0 +1,29 @@
+import type { FinTsClientOptions } from '../core/client.js';
+import { FinTsConfig, type FinTsConfigInit } from '../core/config.js';
+import { PinTanClient } from '../session/pin-tan-client.js';
+import type { IncomingMessage3 } from './message.js';
+import { FinTs3Protocol } from './protocol.js';
+import type { SegmentSpec } from './syntax.js';
+
+/** What `FinTs3Client` takes. */
+export interface FinTs3ClientInit {
+  /** Where and as whom to log in: a `FinTsConfig`, or what its constructor takes. */
+  config: FinTsConfig | FinTsConfigInit;
+  /** The user's PIN; the client keeps it in memory only and never logs it. */
+  pin: string;
+  /** How the client reaches the user and the bank. */
+  options: FinTsClientOptions;
+}
+
+/** FinTS 3.0 PIN/TAN client, the version German banks use. */
+export class FinTs3Client extends PinTanClient<IncomingMessage3, SegmentSpec> {
+  /**
+   * Throws `TypeError` if the configuration is invalid, if the PIN is empty, or if the PIN or login data contain
+   * characters FinTS 3.0 cannot send: it uses ISO 8859-1, so `€` and most non-Latin letters are not possible. Throws as
+   * well for a product ID longer than 25 or a product version longer than 5 characters.
+   */
+  constructor(init: FinTs3ClientInit) {
+    const config = init.config instanceof FinTsConfig ? init.config : new FinTsConfig(init.config);
+    super(init.options, (logger) => new FinTs3Protocol(config, init.pin, init.options.transport, logger));
+  }
+}

package/src/v3/dialog.ts

@@ -0,0 +1,199 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { FinTsProtocolError } from '../core/errors.js';
+import { FeedbackCodes, hasCode } from '../core/feedback.js';
+import { requireBankParameters } from '../session/parameter-data.js';
+import { PinTanDialog } from '../session/pin-tan-dialog.js';
+import type { Approval, StartWithOrder } from '../session/protocol.js';
+import { TanMethod } from '../tan/tan-models.js';
+import { IncomingMessage3 } from './message.js';
+import type { Bpd3 } from './parameters.js';
+import { Segments, TanResponse } from './segments.js';
+import type { SegmentSpec } from './syntax.js';
+
+/** Dialog ID of a dialog the bank has not answered yet, and customer system ID before synchronization. */
+const unassigned = '0';
+
+/** The first version of HKTAN that supports strong customer authentication. */
+const firstScaVersion = 6;
+
+/** The first version of HKTAN that supports app approvals, with the status request (process S). */
+const firstDecoupledVersion = 7;
+
+/** How a message is signed: the security function of the TAN method and the customer system ID. */
+export interface Signing3 {
+  readonly securityFunction: string;
+  readonly systemId: string;
+}
+
+/**
+ * What a dialog needs from the session: the parameter data received so far, the segments that open a dialog, and the
+ * way to the bank. The `FinTs3Protocol` provides it, and keeps the login data and the PIN to itself.
+ */
+export interface FinTs3DialogHost {
+  /** The bank parameter data received so far, if any. */
+  readonly bankParameters: Bpd3 | undefined;
+
+  /** The customer system ID the bank assigned; `undefined` before the synchronization. */
+  readonly systemId: string | undefined;
+
+  /** Identification (HKIDN) and processing preparation (HKVVB), which open every dialog. */
+  initSegments(systemId: string, anonymous?: boolean): SegmentSpec[];
+
+  /**
+   * Sends `segments` as message `number` of the dialog `dialogId` and returns the bank's answer, not yet parsed.
+   *
+   * With `signing` the message is signed with the PIN and the `tan`, after `LoginGuard.check`; without, it goes out
+   * unsigned, as in an anonymous dialog.
+   */
+  post(message: {
+    dialogId: string;
+    number: number;
+    segments: readonly SegmentSpec[];
+    signing: Signing3 | undefined;
+    tan: string | undefined;
+  }): Promise<Uint8Array>;
+}
+
+/** One FinTS 3.0 dialog: numbered messages under the dialog ID the bank assigns in its first answer. */
+export class FinTs3Dialog extends PinTanDialog<IncomingMessage3, SegmentSpec> {
+  private systemId: string;
+  private id = unassigned;
+
+  private constructor(
+    private readonly host: FinTs3DialogHost,
+    method: TanMethod,
+    tanMedium: string | undefined,
+    private readonly anonymous: boolean,
+  ) {
+    super(method, tanMedium);
+    this.systemId = anonymous ? unassigned : (host.systemId ?? unassigned);
+  }
+
+  static signed(host: FinTs3DialogHost, method: TanMethod, tanMedium?: string): FinTs3Dialog {
+    return new FinTs3Dialog(host, method, tanMedium, false);
+  }
+
+  /** A dialog without login, which only delivers the bank parameter data. */
+  static anonymous(host: FinTs3DialogHost): FinTs3Dialog {
+    return new FinTs3Dialog(host, TanMethod.oneStep, undefined, true);
+  }
+
+  protected get bankParameters(): Bpd3 | undefined {
+    return this.host.bankParameters;
+  }
+
+  get isActive(): boolean {
+    return this.id !== unassigned && !this.hasEnded;
+  }
+
+  /** The version of the HKTAN segments: that of the HITANS segment the bank describes the method in. */
+  private get tanVersion(): number {
+    return this.bankParameters?.tanVersion(this.method) ?? firstScaVersion;
+  }
+
+  start(synchronize = false): Promise<IncomingMessage3> {
+    if (synchronize) this.systemId = unassigned;
+    return this.sendSegments([
+      ...this.host.initSegments(this.systemId),
+      ...(this.isTwoStep ? [this.tanRequest('HKIDN')] : []),
+      ...(synchronize ? [Segments.synchronization()] : []),
+    ]);
+  }
+
+  /**
+   * Opens the dialog, asking strong authentication for `order` with a two-step method, then sends `order` in the next
+   * message.
+   */
+  startWith(order: SegmentSpec): StartWithOrder<IncomingMessage3> {
+    return {
+      login: () =>
+        this.sendSegments([
+          ...this.host.initSegments(this.systemId),
+          ...(this.isTwoStep ? [this.tanRequest(order.type)] : []),
+        ]),
+      order: () => this.sendSegments([order]),
+    };
+  }
+
+  /**
+   * Opens the anonymous dialog; the answer carries the bank parameter data.
+   *
+   * With `announceSca` the message also carries HKTAN, the way a client that can do strong customer authentication
+   * tells the bank so, whereupon the bank may send parameter data suited to it (PIN/TAN, B.4.3.1).
+   */
+  requestBankParameters(announceSca = false): Promise<IncomingMessage3> {
+    return this.sendSegments([
+      ...this.host.initSegments(unassigned, true),
+      ...(announceSca ? [Segments.tanProcess4(firstScaVersion, 'HKIDN')] : []),
+    ]);
+  }
+
+  send(order: SegmentSpec): Promise<IncomingMessage3> {
+    const needsTan = this.isTwoStep && requireBankParameters(this.bankParameters).pinTan.requiresTan(order.type);
+    return this.sendSegments([order, ...(needsTan ? [this.tanRequest(order.type)] : [])]);
+  }
+
+  protected async sendEnd(): Promise<void> {
+    await this.sendSegments([Segments.dialogEnd(this.id)]);
+  }
+
+  private tanRequest(segmentType: string): SegmentSpec {
+    return Segments.tanProcess4(this.tanVersion, segmentType, this.mediumName);
+  }
+
+  /**
+   * The approval a HITAN segment of process 4 asks for, answered with HKTAN process 2 (TAN) or S (status).
+   *
+   * Throws `FinTsProtocolError` for an app approval with a method of HITANS #6: the status request (process S) came with
+   * version 7, along with app approvals (PIN/TAN B.5.2).
+   */
+  protected approvalIn(response: IncomingMessage3): Approval<IncomingMessage3> | undefined {
+    const tan = tanResponseOf(response, '4');
+    if (tan === undefined || tan.isDummy) return undefined;
+    if (hasCode(response.feedback, FeedbackCodes.decoupledPending) && this.tanVersion < firstDecoupledVersion) {
+      throw new FinTsProtocolError('The bank asks for an app approval, which needs HKTAN version 7');
+    }
+    const reference = tan.reference!;
+    return this.approvalOf(response, {
+      reference,
+      message: tan.challenge,
+      hhdUc: tan.hhdUc,
+      validUntil: tan.validUntil,
+      tanMediumName: tan.mediumName,
+      submitTan: (value) => this.sendSegments([Segments.tanProcess2(this.tanVersion, reference)], value),
+      checkStatus: () => this.sendSegments([Segments.tanProcessStatus(this.tanVersion, reference)]),
+      // A status answer that the approval is still pending may carry new instructions (PIN/TAN B.4.2.2.1, step 2b).
+      instructionsIn: (status) => tanResponseOf(status, 'S')?.challenge,
+    });
+  }
+
+  private sendSegments(segments: readonly SegmentSpec[], tan?: string): Promise<IncomingMessage3> {
+    return this.transmit(
+      (number) =>
+        this.host.post({
+          dialogId: this.id,
+          number,
+          segments,
+          signing: this.anonymous
+            ? undefined
+            : { securityFunction: this.method.securityFunction, systemId: this.systemId },
+          tan,
+        }),
+      (answer) => IncomingMessage3.parse(answer),
+    );
+  }
+
+  /** The bank assigns the dialog ID in its answer to the first message. */
+  protected readDialogData(response: IncomingMessage3): void {
+    if (this.id === unassigned) this.id = response.dialogId ?? unassigned;
+  }
+}
+
+/** The TAN part of `response` that answers TAN `process`. */
+function tanResponseOf(response: IncomingMessage3, process: string): TanResponse | undefined {
+  return response
+    .findAll('HITAN')
+    .map((s) => TanResponse.parse(s))
+    .find((t) => t.process === process);
+}