@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/session/protocol.ts

@@ -0,0 +1,311 @@
+import type { Account } from '../core/account.js';
+import type { Balance } from '../core/balance.js';
+import type { BankMessage } from '../core/bank-info.js';
+import { requirePinLength, type FinTsConfig } from '../core/config.js';
+import { FinTsBankError, FinTsProtocolError, FinTsUnsupportedError } from '../core/errors.js';
+import type { FinTsFeedback } from '../core/feedback.js';
+import type { Transaction, TransactionFormat } from '../core/transaction.js';
+import type { TanChallenge } from '../tan/challenge.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import type { LoginGuard } from './login-guard.js';
+import { knownAccount, lists, type BankParameters, type UserParameters } from './parameter-data.js';
+
+/**
+ * The filler the specification names for a reference that does not exist.
+ *
+ * The bank puts it into a dummy answer when no approval is needed. The client sends it as the TAN medium name in the
+ * dialog that looks up the TAN media, before it knows a medium; the bank ignores it there (PIN/TAN B.4.3.1.3).
+ */
+export const noReference = 'noref';
+
+/**
+ * A business transaction by its name, such as `HKCAZ`, and the version to send; `undefined` where the bank does not
+ * offer it or the parameter data do not permit it.
+ */
+export interface OfferedTransaction {
+  readonly name: string;
+  readonly version: number | undefined;
+}
+
+/**
+ * What to request for transactions: camt.052 (`camt`) or MT940, the `version` to send, the `camtFormats` to name, and
+ * the `currency` of statements that state none.
+ */
+export interface TransactionsRequest {
+  readonly camt: boolean;
+  readonly version: number;
+  readonly camtFormats: readonly string[];
+  readonly currency: string | undefined;
+}
+
+/**
+ * What to request for the transactions of `account` in `format`.
+ *
+ * The client reads camt.052 only, so camt counts as offered only if `camtFormats` include it. With `auto` the client
+ * takes camt where the bank offers it, unless the user parameter data `upd` list only MT940 transactions for the
+ * account.
+ *
+ * Throws `FinTsUnsupportedError` if the bank does not offer the chosen format for the account.
+ */
+export function chooseTransactions(
+  format: TransactionFormat,
+  account: Account,
+  upd: UserParameters | undefined,
+  offered: { camt: OfferedTransaction; camtFormats: readonly string[]; mt940: OfferedTransaction },
+): TransactionsRequest {
+  const readable = offered.camtFormats.filter((f) => f.includes('camt.052'));
+  const camtVersion = readable.length === 0 ? undefined : offered.camt.version;
+  const known = knownAccount(upd, account);
+  const useCamt =
+    format === 'camt' ||
+    (format === 'auto' &&
+      camtVersion !== undefined &&
+      (lists(known, offered.camt.name) || !lists(known, offered.mt940.name)));
+  const version = useCamt ? camtVersion : offered.mt940.version;
+  if (version === undefined) {
+    const name = useCamt ? offered.camt.name : offered.mt940.name;
+    throw new FinTsUnsupportedError(
+      `The bank offers no ${useCamt ? 'camt ' : ''}transactions (${name}) for this account`,
+    );
+  }
+  return { camt: useCamt, version, camtFormats: readable, currency: known.currency ?? account.currency };
+}
+
+/**
+ * The query for the balance of `account`.
+ *
+ * `order` builds the request for each page. Once all pages are in, `records` collects the balance records of all pages,
+ * `balanceRecord` picks the one for `account` with the help of `accountOf`, and `read` turns it into the `Balance`.
+ */
+export function balanceQuery<R extends BankResponse, O, T>(
+  account: Account,
+  parts: {
+    order: (continuation: string | undefined) => O;
+    records: (pages: readonly R[]) => T[];
+    accountOf: (record: T) => Account;
+    read: (record: T, account: Account) => Balance;
+  },
+): Query<R, O, Balance> {
+  return {
+    order: parts.order,
+    read: (pages) =>
+      parts.read(
+        balanceRecord(
+          parts.records(pages),
+          account,
+          parts.accountOf,
+          pages.flatMap((p) => p.feedback),
+        ),
+        account,
+      ),
+  };
+}
+
+/**
+ * Checks that a message signed with `pin` may go out.
+ *
+ * It may not if the bank refused a login before (`LoginGuard.check`), or if the bank parameters `bpd` rule out the
+ * PIN's length: the bank would count such a PIN as a failed attempt.
+ */
+export function checkBeforeSigning(guard: LoginGuard, pin: string, bpd: BankParameters | undefined): void {
+  guard.check();
+  requirePinLength(pin, bpd?.pinLength.min, bpd?.pinLength.max);
+}
+
+/**
+ * The balance record of `account` in `records`: the one whose account matches. A single record is taken as it is,
+ * since the query asked for this one account only.
+ *
+ * Throws `FinTsBankError` with the bank's `feedback` if there is none, and `FinTsProtocolError` if there are several
+ * and none matches.
+ */
+export function balanceRecord<T>(
+  records: readonly T[],
+  account: Account,
+  accountOf: (record: T) => Account,
+  feedback: readonly FinTsFeedback[],
+): T {
+  if (records.length === 0) throw new FinTsBankError(feedback, 'No balance returned');
+  if (records.length === 1) return records[0]!;
+  const match = records.find((record) => accountOf(record).matches(account));
+  if (match === undefined) {
+    throw new FinTsProtocolError('The bank returned balances, but none for the requested account');
+  }
+  return match;
+}
+
+/** A bank response, reduced to what the protocol-independent session logic needs. */
+export interface BankResponse {
+  /** Return codes of the whole message and of its parts. */
+  readonly feedback: readonly FinTsFeedback[];
+
+  /** Whether the bank rejected the message as a whole (an error in HIRMG), rather than single orders in it. */
+  readonly messageRejected: boolean;
+
+  /** Free-text messages the bank addresses to the user. */
+  readonly bankMessages: readonly BankMessage[];
+
+  /** The length of the message in bytes, a measure of the memory it holds. */
+  readonly size: number;
+}
+
+/** The bank's request to approve a message with a TAN or in a banking app. */
+export interface Approval<R> {
+  /** What the user is asked. */
+  readonly challenge: TanChallenge;
+
+  /** Sends the TAN the user entered. */
+  readonly submitTan: (tan: string) => Promise<R>;
+
+  /** Asks the bank whether the user has approved in the banking app. */
+  readonly checkStatus: () => Promise<R>;
+
+  /**
+   * Whether the bank announces a push message for once the user has approved (return code 3957), before which the
+   * status must not be asked. The client has no push channel, so the user reports the approval instead.
+   */
+  readonly waitForPush: boolean;
+
+  /** The new instructions a status answer gives the user (return code 3956); `undefined` where it gives none. */
+  readonly instructionsIn: (response: R) => string | undefined;
+}
+
+/** One message exchange of a dialog, sent when called. */
+export type Exchange<R> = () => Promise<R>;
+
+/**
+ * The messages that open a dialog and send an order: `login` opens the dialog, and `order` sends the order in a message
+ * of its own.
+ */
+export interface StartWithOrder<R> {
+  readonly login: Exchange<R>;
+  readonly order: Exchange<R> | undefined;
+}
+
+/** What the handling of responses needs of a dialog, whatever its protocol. */
+export interface DialogHandle<R extends BankResponse> {
+  /** The TAN method the dialog's messages are signed with. */
+  readonly method: TanMethod;
+
+  /** Whether the bank knows this dialog and it has not ended. */
+  readonly isActive: boolean;
+
+  /**
+   * The approval `response`, the dialog's latest answer, asks for with return code 0030 (TAN) or 3955 (banking app);
+   * `undefined` if it asks for none.
+   *
+   * The bank has not executed the message then, so a request without a challenge is a `FinTsProtocolError`: read as
+   * done, it would report an empty result.
+   */
+  approvalAskedIn(response: R): Approval<R> | undefined;
+
+  /** Forgets the dialog without contacting the bank, for example after the bank rejected the PIN. */
+  discard(): void;
+
+  /**
+   * Ends the dialog at the bank; does nothing if it is not active.
+   *
+   * Bank and connection errors are ignored, since the bank may have ended the dialog on its side already.
+   */
+  end(): Promise<void>;
+}
+
+/** One dialog with the bank: a numbered sequence of messages under one dialog ID. */
+export interface ProtocolDialog<R extends BankResponse, O> extends DialogHandle<R> {
+  /** Opens the dialog; with `synchronize` the bank also assigns a customer system ID. */
+  start(synchronize?: boolean): Promise<R>;
+
+  /** The messages that open the dialog and send `order` while no TAN medium is chosen yet, as for listing the media. */
+  startWith(order: O): StartWithOrder<R>;
+
+  /** Sends `order`, asking for strong customer authentication where the bank requires it. */
+  send(order: O): Promise<R>;
+}
+
+/** A business transaction: the order to send for each page, and how to read all pages the bank sent. */
+export interface Query<R, O, T> {
+  /** The order for the page at `continuation`; `undefined` for the first page. */
+  readonly order: (continuation: string | undefined) => O;
+
+  /** Reads the result; throws `FormatError` for malformed data. */
+  readonly read: (pages: readonly R[]) => T;
+}
+
+/**
+ * What the regular dialogs still need from a synchronization, a login in a dialog of its own, before the TAN method and
+ * medium are settled (`TanSelection.synchronizationDialog` tells which method signs it):
+ * - `none`: nothing, so no synchronization runs;
+ * - `helpful`: nothing they cannot get themselves, but it tells the TAN methods the user may use before the user
+ *   chooses one, so it runs once per client;
+ * - `required`: the customer system ID, without which no regular dialog starts (FinTS 3.0).
+ */
+export type Synchronization = 'none' | 'helpful' | 'required';
+
+/** What the handling of responses needs of a protocol, whatever the orders it builds. */
+export interface ResponseProtocol<R extends BankResponse> {
+  /** Keeps the parameter data and IDs in `response`, the answer to a message of a logged-in dialog. */
+  keepParameterData(response: R): void;
+
+  /** Joins a response with the one completing its approval. */
+  combine(first: R, second: R): R;
+}
+
+/**
+ * The protocol-specific half of a PIN/TAN client: builds and reads the messages.
+ *
+ * `PinTanClient` holds the other half, the session logic.
+ */
+export interface PinTanProtocol<R extends BankResponse, O> extends ResponseProtocol<R> {
+  /** Where and as whom the client talks to the bank. */
+  readonly config: FinTsConfig;
+
+  /** The bank parameter data received so far, if any. */
+  readonly bankParameters: BankParameters | undefined;
+
+  /** The user parameter data received so far, if any. */
+  readonly userParameters: UserParameters | undefined;
+
+  /** What regular dialogs still need from a synchronization dialog. */
+  readonly synchronization: Synchronization;
+
+  /**
+   * Drops the customer system ID the bank no longer accepts, so that a synchronization is required again; returns
+   * whether there was one.
+   */
+  forgetSystemId(): boolean;
+
+  /** Keeps the PIN from going out after a refused login: the protocol checks it before every message it signs. */
+  readonly loginGuard: LoginGuard;
+
+  /** Requests the bank parameter data without logging in, and keeps them. */
+  fetchBankParametersAnonymously(): Promise<R>;
+
+  /** A new dialog signed with `method` and, where the method needs one, `tanMedium`. */
+  newDialog(method: TanMethod, tanMedium?: string): ProtocolDialog<R, O>;
+
+  /** Lists the TAN media; `undefined` if the bank does not offer it. */
+  tanMedia(): Query<R, O, TanMedium[]> | undefined;
+
+  /** Lists IBAN and BIC of the accounts; `undefined` if the bank does not offer it. */
+  sepaAccounts(): Query<R, O, Account[]> | undefined;
+
+  /** The balance of `account`; throws `FinTsUnsupportedError` if the bank does not report balances. */
+  balance(account: Account): Query<R, O, Balance>;
+
+  /** The transactions of `account`; throws `FinTsUnsupportedError` if the bank does not offer `format`. */
+  transactions(
+    account: Account,
+    format: TransactionFormat,
+    from: Date | undefined,
+    to: Date | undefined,
+  ): Query<R, O, Transaction[]>;
+
+  /** The parameter data and IDs the protocol keeps, as JSON data, for the client's saved state. */
+  saveState(): Record<string, unknown>;
+
+  /** Restores what `saveState` saved; throws if `saved` is damaged, leaving the protocol unchanged. */
+  restoreState(saved: Record<string, unknown>): void;
+
+  /** Releases the connection. */
+  close(): void;
+}

package/src/session/response-handler.ts

@@ -0,0 +1,130 @@
+import { bankErrorFor, FinTsLoginDataChangedError, FinTsTanCancelledError } from '../core/errors.js';
+import {
+  allowedTanMethodsIn,
+  FeedbackCodes,
+  hasCode,
+  hasErrors,
+  userWarnings,
+  type FinTsFeedback,
+} from '../core/feedback.js';
+import { invalidArgument } from '../util/errors.js';
+import { appApprovalWait } from './app-approval.js';
+import type { LoginGuard, RequestKind } from './login-guard.js';
+import type { Approval, BankResponse, DialogHandle, Exchange, ResponseProtocol, StartWithOrder } from './protocol.js';
+import type { SessionState } from './session-state.js';
+import type { UserPrompts } from './user-prompts.js';
+
+/** Checks what the bank answers and completes the approvals it asks for. The `LoginGuard` judges what errors mean. */
+export class ResponseHandler<R extends BankResponse> {
+  constructor(
+    private readonly protocol: ResponseProtocol<R>,
+    private readonly state: SessionState,
+    private readonly prompts: UserPrompts,
+    private readonly guard: LoginGuard,
+  ) {}
+
+  /** Sends `login`, the exchange that opens `dialog`, and completes the approval the bank asks for. */
+  startDialog(dialog: DialogHandle<R>, login: Exchange<R>): Promise<R> {
+    return this.start(dialog, login, 'login');
+  }
+
+  /**
+   * Opens `dialog` with `start`, which also sends an order, and returns the answers: the login's, then the order's where
+   * the order has a message of its own. Completes the approval of each before the next.
+   */
+  async startDialogWith(dialog: DialogHandle<R>, start: StartWithOrder<R>): Promise<R[]> {
+    const order = start.order;
+    if (order === undefined) return [await this.start(dialog, start.login, 'loginWithOrder')];
+    const login = await this.startDialog(dialog, start.login);
+    return [login, await this.complete(dialog, await order())];
+  }
+
+  /** Receives `response`, the answer to an order in `dialog`, and completes the approval the bank asks for. */
+  complete(dialog: DialogHandle<R>, response: R): Promise<R> {
+    return this.settle(dialog, response, 'order');
+  }
+
+  /**
+   * Receives `response`, the answer to a request of `kind` in `dialog`: keeps its parameter data, even alongside errors,
+   * since the remedy for a refused login may need them; passes its notices on; and throws its errors once the guard has
+   * judged them (`LoginGuard.judge`).
+   */
+  receive(dialog: DialogHandle<R>, response: R, kind: RequestKind): void {
+    this.protocol.keepParameterData(response);
+    this.readNotices(response);
+    if (!hasErrors(response.feedback)) return;
+    const error = bankErrorFor(response.feedback, kind === 'approval');
+    // Every further message of a refused login's dialog would carry the refused PIN.
+    if (this.guard.judge(error, kind, dialog.isActive, dialog.method)) dialog.discard();
+    throw error;
+  }
+
+  /**
+   * Passes the bank's messages in `response` to the user: all an anonymous dialog tells, since the TAN methods it lists
+   * are not those of a user.
+   */
+  showBankMessages(response: R): void {
+    for (const message of response.bankMessages) this.prompts.showBankMessage(message);
+  }
+
+  private async start(dialog: DialogHandle<R>, login: Exchange<R>, kind: RequestKind): Promise<R> {
+    const response = await this.settle(dialog, await login(), kind);
+    if (hasCode(response.feedback, FeedbackCodes.newLoginData)) await this.retireLoginData(dialog, response.feedback);
+    return response;
+  }
+
+  /**
+   * Ends `dialog`, whose login brought new login data, and stops the client from logging in with the old ones
+   * (Rückmeldungscodes C.6).
+   */
+  private async retireLoginData(dialog: DialogHandle<R>, feedback: readonly FinTsFeedback[]): Promise<never> {
+    await dialog.end();
+    const error = new FinTsLoginDataChangedError(feedback);
+    this.guard.refuse(error);
+    throw error;
+  }
+
+  /**
+   * Receives `response`, the answer to a request of `kind`, then completes the approval it asks for; returns it joined
+   * with the response that completes the approval.
+   */
+  private async settle(dialog: DialogHandle<R>, response: R, kind: RequestKind): Promise<R> {
+    this.receive(dialog, response, kind);
+    const approval = dialog.approvalAskedIn(response);
+    if (approval === undefined) return response;
+    const approved = approval.challenge.isDecoupled
+      ? await this.awaitAppApproval(dialog, approval)
+      : await this.enterTan(dialog, approval);
+    return this.protocol.combine(response, approved);
+  }
+
+  /** Passes on the notices in `response`: the TAN methods the user may use (3920), the bank's messages and warnings. */
+  private readNotices(response: R): void {
+    const allowed = allowedTanMethodsIn(response.feedback);
+    if (allowed.length > 0) this.state.rememberAllowedMethods(allowed);
+    this.showBankMessages(response);
+    for (const warning of userWarnings(response.feedback)) this.prompts.showWarning(warning);
+  }
+
+  private async enterTan(dialog: DialogHandle<R>, approval: Approval<R>): Promise<R> {
+    const answer = await this.prompts.askTan(approval.challenge);
+    if (answer.kind === 'approved') {
+      throw invalidArgument('Answered a TAN challenge with an approval in the banking app', 'tanCallback');
+    }
+    const tan = answer.kind === 'tan' ? answer.tan.trim() : '';
+    if (tan === '') throw new FinTsTanCancelledError();
+    const response = await approval.submitTan(tan);
+    this.receive(dialog, response, 'approval');
+    return response;
+  }
+
+  private awaitAppApproval(dialog: DialogHandle<R>, approval: Approval<R>): Promise<R> {
+    return appApprovalWait(approval, {
+      ask: (challenge) => this.prompts.askTan(challenge),
+      pause: (delayMs, interrupt) => this.prompts.pause(delayMs, interrupt),
+      receive: (response) => {
+        this.receive(dialog, response, 'approval');
+      },
+    }).run();
+  }
+}

package/src/session/sepa-accounts.ts

@@ -0,0 +1,97 @@
+import type { Account } from '../core/account.js';
+import { FinTsDialogAbortedError } from '../core/errors.js';
+import type { DialogRunner } from './dialog-runner.js';
+import type { LoginGuard } from './login-guard.js';
+import type { BankResponse, PinTanProtocol } from './protocol.js';
+import type { SessionState } from './session-state.js';
+
+/**
+ * IBAN and BIC of the user's accounts, from the bank's SEPA account list where the user parameter data lack them
+ * (Formals F.3.4).
+ *
+ * The list is read once per version of the user parameter data and kept in the saved state. Under version 0, which
+ * holds for one dialog only (Formals E.2), without user parameter data, or where the bank rejects the list, it is kept
+ * for this client only. Where the bank ends the dialog in answer to the list, the next call asks once more.
+ */
+export class SepaAccounts<R extends BankResponse, O> {
+  /**
+   * The list this client keeps unsaved, with the version of the user parameter data it was read under; empty where the
+   * bank rejected it.
+   */
+  private unsaved: { updVersion: number | undefined; accounts: readonly Account[] } | undefined;
+
+  /** Whether a call already went on without the list because the bank ended the dialog in answer to it. */
+  private abortSkipped = false;
+
+  constructor(
+    private readonly protocol: PinTanProtocol<R, O>,
+    private readonly state: SessionState,
+    private readonly dialogs: DialogRunner<R, O>,
+    private readonly guard: LoginGuard,
+  ) {}
+
+  /** The accounts of the user parameter data completed with IBAN and BIC, then the accounts only the list names. */
+  async completedAccounts(): Promise<Account[]> {
+    const sepa = await this.list();
+    const accounts = this.protocol.userParameters?.accounts ?? [];
+    return [
+      ...accounts.map((account) => withSepaDetails(account, sepa)),
+      ...sepa.filter((s) => !accounts.some((a) => s.matches(a))),
+    ];
+  }
+
+  /** `account` with IBAN and BIC filled in from the list. */
+  async complete(account: Account): Promise<Account> {
+    if (account.iban !== undefined && account.bic !== undefined) return account;
+    return withSepaDetails(account, await this.list());
+  }
+
+  /** The list, read in the session's dialog, whose start delivers the user parameter data it is cached for. */
+  private async list(): Promise<readonly Account[]> {
+    await this.dialogs.open();
+    const upd = this.protocol.userParameters;
+    if (
+      upd !== undefined &&
+      upd.accounts.length > 0 &&
+      upd.accounts.every((a) => a.iban !== undefined && a.bic !== undefined)
+    ) {
+      return [];
+    }
+    const updVersion = upd?.version;
+    const saved = this.state.sepaAccounts(updVersion);
+    if (saved !== undefined) return saved;
+    if (this.unsaved !== undefined && this.unsaved.updVersion === updVersion) return this.unsaved.accounts;
+    const query = this.protocol.sepaAccounts();
+    if (query === undefined) return [];
+    // Where the bank rejects the list, the accounts stay as the user parameter data state them.
+    const outcome = { aborted: false };
+    const accounts = await this.guard.tryLookUp(async () => {
+      try {
+        return await this.dialogs.query(() => query);
+      } catch (error) {
+        if (error instanceof FinTsDialogAbortedError) outcome.aborted = true;
+        throw error;
+      }
+    });
+    if (outcome.aborted && !this.abortSkipped) {
+      // The bank may have ended the dialog for a reason of its own, such as a timeout, so this call goes on without the
+      // list and the next one asks again in its new dialog. Only once: banks also end the dialog when they reject the
+      // list, and each time costs the next call a login.
+      this.abortSkipped = true;
+      return [];
+    }
+    if (accounts !== undefined && updVersion !== undefined && updVersion > 0) {
+      this.state.cacheSepaAccounts(accounts, updVersion);
+    } else {
+      this.unsaved = { updVersion, accounts: accounts ?? [] };
+    }
+    return accounts ?? [];
+  }
+}
+
+function withSepaDetails(account: Account, sepa: readonly Account[]): Account {
+  const match = sepa.find((s) => account.matches(s));
+  if (match === undefined) return account;
+  // A BIC of the list takes precedence over the one of the user parameter data (Formals E.3.1.1, "BIC").
+  return account.copyWith({ iban: account.iban ?? match.iban, bic: match.bic ?? account.bic });
+}