@coderoftime/fints 0.1.0 → 0.2.0

package/src/session/protocol.ts

@@ -1,311 +0,0 @@
-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

@@ -1,130 +0,0 @@
-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/v3/client.ts

@@ -1,29 +0,0 @@
-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));
-  }
-}