@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/session/session-setup.ts

@@ -0,0 +1,165 @@
+import type { BankInfo } from '../core/bank-info.js';
+import { FinTsBankError, FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData } from '../core/errors.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import type { LoginGuard, RefusalReason } from './login-guard.js';
+import { requireBankParameters } from './parameter-data.js';
+import type { BankResponse, PinTanProtocol, ProtocolDialog } from './protocol.js';
+import type { ResponseHandler } from './response-handler.js';
+import type { TanSelection } from './tan-selection.js';
+
+/**
+ * What has to be settled before a login: the bank parameter data, the synchronization, and through `TanSelection` the
+ * TAN method and medium. Each of the dialogs this takes serves one purpose only.
+ *
+ * Where the bank refuses a login for a reason the session can take care of, `remedied` does so and logs in again.
+ */
+export class SessionSetup<R extends BankResponse, O> {
+  /** Whether a synchronization dialog ran, so that a helpful one runs once only. */
+  private synchronizationTried = false;
+
+  constructor(
+    private readonly protocol: PinTanProtocol<R, O>,
+    private readonly responses: ResponseHandler<R>,
+    private readonly tans: TanSelection<R, O>,
+    private readonly guard: LoginGuard,
+  ) {}
+
+  /**
+   * The bank's general information: from an anonymous dialog where the bank answers one, else from the synchronization.
+   * No TAN method or medium is chosen for it.
+   */
+  async bankInfo(): Promise<BankInfo> {
+    if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    if (this.protocol.bankParameters === undefined) await this.synchronizeIfDue();
+    return requireBankParameters(this.protocol.bankParameters).bankInfo;
+  }
+
+  /** The TAN methods the bank allows for this user, which the synchronization reports. */
+  async methods(): Promise<TanMethod[]> {
+    await this.loadParameters();
+    return this.tans.available();
+  }
+
+  /** Settles what is still open: the bank parameter data, the synchronization, the TAN method and medium. */
+  async prepare(): Promise<void> {
+    await this.loadParameters();
+    await this.tans.ensureMethodChosen();
+    if (this.tans.mediumToLookUp) await this.tans.chooseMedium(await this.lookUpTanMedia());
+  }
+
+  /** A new dialog signed with the TAN method and medium in use, once `prepare` has settled them. */
+  async newDialog(): Promise<ProtocolDialog<R, O>> {
+    await this.prepare();
+    return this.tans.newDialog();
+  }
+
+  /**
+   * Runs `attempt`, which may log in, and runs it once more for each reason of a refused login the session can take
+   * care of, so that a bank that keeps refusing fails with its own error:
+   *
+   * | Refusal (`LoginGuard.remediableReasons`) | Remedy |
+   * | --- | --- |
+   * | 3920 without the method, or 9075 after the one-step method | another allowed method (`TanSelection.replace`) |
+   * | 9391 | a new synchronization, which issues a customer system ID |
+   */
+  async remedied<T>(attempt: () => Promise<T>): Promise<T> {
+    // A refusal of an earlier call stops the attempt before it sends the PIN; there is nothing to remedy.
+    if (this.guard.hasRefusal) return attempt();
+    const remedied = new Set<RefusalReason>();
+    for (;;) {
+      try {
+        return await attempt();
+      } catch (error) {
+        if (!(error instanceof FinTsBankError)) throw error;
+        const reason = this.guard.remediableReasons(error).find((r) => !remedied.has(r));
+        const rejected = this.guard.refusedMethod;
+        if (reason === undefined || rejected === undefined || !(await this.remedy(reason, rejected))) throw error;
+        remedied.add(reason);
+        this.guard.pardon(error);
+      }
+    }
+  }
+
+  /** Takes care of `reason`, given for refusing a login signed with `rejected`; returns whether it could. */
+  private async remedy(reason: RefusalReason, rejected: TanMethod): Promise<boolean> {
+    switch (reason) {
+      case 'tanMethodNotAllowed':
+        // The parameter data name the methods to choose from; the refusal may be the first to deliver them.
+        if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+        return this.tans.replace(rejected);
+      case 'systemIdRejected':
+        // Without a customer system ID there is none to lose, and logging in once more would only send the PIN again.
+        return this.protocol.forgetSystemId();
+    }
+  }
+
+  /**
+   * Loads the bank parameter data if they are missing, then synchronizes if that is due.
+   *
+   * The bank parameter data come first, from an anonymous dialog: the dialogs signed with the PIN need them for the
+   * dialog language, the PIN length and the TAN methods (PIN/TAN B.4.3.1, Formals C.3.1.3). A bank that does not answer
+   * anonymously delivers them with the synchronization.
+   *
+   * After a refused login it throws the refusal right away, before the user is asked for a TAN method or medium.
+   */
+  private async loadParameters(): Promise<void> {
+    this.guard.check();
+    if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    await this.synchronizeIfDue();
+  }
+
+  /**
+   * Asks for the bank parameter data without logging in. A bank that does not answer anonymously is no error, but a
+   * failed connection is: the synchronization would only wait for the same server again.
+   */
+  private async fetchBankParametersAnonymously(): Promise<void> {
+    try {
+      this.responses.showBankMessages(await this.protocol.fetchBankParametersAnonymously());
+    } catch (error) {
+      // Optional: the login delivers the parameters as well.
+      if (error instanceof FinTsTransportError || !(error instanceof FinTsError)) throw error;
+    }
+  }
+
+  /** Runs the synchronization dialog where it is due (`TanSelection.synchronizationDialog`). */
+  private async synchronizeIfDue(): Promise<void> {
+    const due =
+      this.protocol.synchronization === 'required' ||
+      (this.protocol.synchronization === 'helpful' && !this.synchronizationTried);
+    if (!due) return;
+    this.synchronizationTried = true;
+    await this.once(this.tans.synchronizationDialog(), (dialog) =>
+      this.responses.startDialog(dialog, () => dialog.start(true)),
+    );
+    if (this.protocol.synchronization === 'required') {
+      throw new FinTsProtocolError('The bank did not complete the synchronization');
+    }
+  }
+
+  /**
+   * The TAN media of the method in use; `undefined` if the bank does not list them or rejects the list, after which the
+   * client reports a missing medium before the login.
+   *
+   * The lookup runs in a dialog of its own, whose start asks for the list, since the regular dialog start needs the
+   * medium the list tells (PIN/TAN B.4.3.1.3).
+   */
+  private async lookUpTanMedia(): Promise<TanMedium[] | undefined> {
+    const query = this.protocol.tanMedia();
+    if (query === undefined) return undefined;
+    return this.guard.tryLookUp(() =>
+      this.once(this.tans.lookupDialog(), async (dialog) => {
+        const pages = await this.responses.startDialogWith(dialog, dialog.startWith(query.order(undefined)));
+        return parseBankData(() => query.read(pages));
+      }),
+    );
+  }
+
+  /** Runs `use` in `dialog`, a dialog of its own, and ends it afterwards, however `use` ends. */
+  private async once<T>(dialog: ProtocolDialog<R, O>, use: (dialog: ProtocolDialog<R, O>) => Promise<T>): Promise<T> {
+    try {
+      return await use(dialog);
+    } finally {
+      await dialog.end();
+    }
+  }
+}

package/src/session/session-state.ts

@@ -0,0 +1,170 @@
+import { Account } from '../core/account.js';
+import { hostOf, type FinTsConfig } from '../core/config.js';
+import { FormatError } from '../util/errors.js';
+import {
+  isJsonObject,
+  isString,
+  readObject,
+  readOptionalInt,
+  readOptionalList,
+  readOptionalString,
+  type JsonObject,
+} from '../util/json.js';
+import type { BankResponse, PinTanProtocol } from './protocol.js';
+
+/** Layout of the saved session; a state of another layout is ignored. */
+const stateFormat = 1;
+
+/** The protocol version the state is for, named as the Dart package names it, so that both read each other's states. */
+const protocolVersion = 'v300';
+
+/** The session and the protocol's parameter data as one JSON string, which `restoreSession` reads. */
+export function saveSession<R extends BankResponse, O>(protocol: PinTanProtocol<R, O>, session: SessionState): string {
+  return JSON.stringify({
+    format: stateFormat,
+    version: protocolVersion,
+    owner: ownerOf(protocol.config),
+    session: session.toJson(),
+    protocol: protocol.saveState(),
+  });
+}
+
+/**
+ * The session saved in `json`, and the protocol's parameter data restored from it.
+ *
+ * A missing or damaged state, or one saved for another user, bank, server or protocol version, gives a new session,
+ * which only costs a new synchronization.
+ */
+export function restoreSession<R extends BankResponse, O>(
+  json: string | undefined,
+  protocol: PinTanProtocol<R, O>,
+): SessionState {
+  if (json === undefined) return new SessionState();
+  try {
+    const saved: unknown = JSON.parse(json);
+    if (!isJsonObject(saved) || saved.format !== stateFormat || saved.version !== protocolVersion) {
+      return new SessionState();
+    }
+    const owner = readOptionalList(saved, 'owner', isString);
+    const expected = ownerOf(protocol.config);
+    if (owner?.length !== expected.length || owner.some((value, i) => value !== expected[i])) {
+      return new SessionState();
+    }
+    const session = SessionState.fromJson(readObject(saved, 'session'));
+    protocol.restoreState(readObject(saved, 'protocol'));
+    return session;
+  } catch (error) {
+    // Damaged JSON, base64 or parameter data, and values of the wrong type, only cost a new synchronization.
+    if (error instanceof FormatError || error instanceof SyntaxError) return new SessionState();
+    throw error;
+  }
+}
+
+/** Whose data a state holds, so that the state of another user or bank is never used. */
+function ownerOf(config: FinTsConfig): string[] {
+  return [hostOf(config.url), config.bankCode, config.userId, config.customerId];
+}
+
+/**
+ * The session data saved between app starts: the allowed TAN methods, the TAN method and medium in use, and the SEPA
+ * account list.
+ */
+export class SessionState {
+  private allowedMethodsValue: readonly string[] | undefined;
+  private tanMethodValue: string | undefined;
+  private tanMediumValue: string | undefined;
+  private sepaAccountsValue: readonly Account[] | undefined;
+  private sepaUpdVersion: number | undefined;
+
+  /** TAN methods the bank allows for this user (return code 3920); `undefined` until the bank has said. */
+  get allowedMethods(): readonly string[] | undefined {
+    return this.allowedMethodsValue;
+  }
+
+  /** Security function of the TAN method in use. */
+  get tanMethod(): string | undefined {
+    return this.tanMethodValue;
+  }
+
+  /** Name of the TAN medium in use. */
+  get tanMedium(): string | undefined {
+    return this.tanMediumValue;
+  }
+
+  /** Keeps the TAN methods the bank reports as allowed for this user. */
+  rememberAllowedMethods(securityFunctions: readonly string[]): void {
+    this.allowedMethodsValue = Object.freeze([...securityFunctions]);
+  }
+
+  /**
+   * Switches to the TAN method `securityFunction` and the TAN `medium` together, so that no medium of another method
+   * stays behind; `undefined` leaves the choice to the next login.
+   */
+  useTanMethod(securityFunction: string | undefined, medium?: string): void {
+    this.tanMethodValue = securityFunction;
+    this.tanMediumValue = medium;
+  }
+
+  /** Switches to the TAN `medium` of the method in use. */
+  useTanMedium(medium: string | undefined): void {
+    this.tanMediumValue = medium;
+  }
+
+  /** The SEPA account list read under the user parameter data of `updVersion`, if it is cached. */
+  sepaAccounts(updVersion: number | undefined): readonly Account[] | undefined {
+    return updVersion !== undefined && updVersion === this.sepaUpdVersion ? this.sepaAccountsValue : undefined;
+  }
+
+  /** Caches the SEPA account list `accounts`, read under the user parameter data of `updVersion`. */
+  cacheSepaAccounts(accounts: readonly Account[], updVersion: number | undefined): void {
+    this.sepaAccountsValue = Object.freeze([...accounts]);
+    this.sepaUpdVersion = updVersion;
+  }
+
+  /** Reads what `toJson` wrote; throws `FormatError` if `json` is damaged. */
+  static fromJson(json: JsonObject): SessionState {
+    const allowedMethods = readOptionalList(json, 'allowedMethods', isString);
+    const sepaAccounts = readOptionalList(json, 'sepaAccounts', isJsonObject)?.map(accountFromJson);
+    const sepaUpdVersion = readOptionalInt(json, 'sepaUpdVersion');
+    const state = new SessionState();
+    state.useTanMethod(readOptionalString(json, 'tanMethod'), readOptionalString(json, 'tanMedium'));
+    if (allowedMethods !== undefined) state.rememberAllowedMethods(allowedMethods);
+    if (sepaAccounts !== undefined) state.cacheSepaAccounts(sepaAccounts, sepaUpdVersion);
+    return state;
+  }
+
+  /** The session as JSON data. */
+  toJson(): JsonObject {
+    return {
+      allowedMethods: this.allowedMethodsValue ?? null,
+      tanMethod: this.tanMethodValue ?? null,
+      tanMedium: this.tanMediumValue ?? null,
+      sepaUpdVersion: this.sepaUpdVersion ?? null,
+      sepaAccounts: this.sepaAccountsValue?.map(accountToJson) ?? null,
+    };
+  }
+}
+
+function accountToJson(a: Account): JsonObject {
+  return {
+    iban: a.iban ?? null,
+    bic: a.bic ?? null,
+    accountNumber: a.accountNumber ?? null,
+    subAccount: a.subAccount ?? null,
+    countryCode: a.countryCode,
+    bankCode: a.bankCode,
+  };
+}
+
+function accountFromJson(json: JsonObject): Account {
+  const bankCode = readOptionalString(json, 'bankCode');
+  if (bankCode === undefined) throw new FormatError('Saved state: account without bank code');
+  return new Account({
+    iban: readOptionalString(json, 'iban'),
+    bic: readOptionalString(json, 'bic'),
+    accountNumber: readOptionalString(json, 'accountNumber'),
+    subAccount: readOptionalString(json, 'subAccount'),
+    countryCode: readOptionalString(json, 'countryCode'),
+    bankCode,
+  });
+}

package/src/session/tan-selection.ts

@@ -0,0 +1,192 @@
+import { FinTsUnsupportedError } from '../core/errors.js';
+import { TanMethod, type TanMedium } from '../tan/tan-models.js';
+import { noReference, type BankResponse, type PinTanProtocol, type ProtocolDialog } from './protocol.js';
+import type { SessionState } from './session-state.js';
+import type { UserPrompts } from './user-prompts.js';
+
+/**
+ * The TAN method and medium the session's messages are signed with, chosen by the user among what the bank offers and
+ * the user may use, and kept in the session state.
+ */
+export class TanSelection<R extends BankResponse, O> {
+  /** TAN methods whose media were looked up in this session. A lookup is not repeated, even where it gave no medium. */
+  private readonly mediaLookedUp = new Set<string>();
+
+  /** The list the last lookup gave, until `takeLookedUpMedia` hands it out. */
+  private lookedUpMedia: TanMedium[] | undefined;
+
+  /** Whether the bank refused a login signed with the one-step method in this session. */
+  private oneStepRefused = false;
+
+  constructor(
+    private readonly protocol: PinTanProtocol<R, O>,
+    private readonly state: SessionState,
+    private readonly prompts: UserPrompts,
+  ) {}
+
+  /** The TAN method in use; the one-step method until one is chosen. */
+  get method(): TanMethod {
+    const code = this.state.tanMethod;
+    if (code === undefined || code === TanMethod.oneStep.securityFunction) return TanMethod.oneStep;
+    return this.protocol.bankParameters?.tanMethods.find((m) => m.securityFunction === code) ?? TanMethod.oneStep;
+  }
+
+  /** Switches to `securityFunction` and `tanMedium` for the dialogs to come. */
+  select(securityFunction: string, tanMedium: string | undefined): void {
+    this.state.useTanMethod(securityFunction, tanMedium);
+    this.mediaLookedUp.delete(securityFunction);
+  }
+
+  /**
+   * A dialog signed with the TAN method in use and its medium.
+   *
+   * Throws `FinTsUnsupportedError` if the method needs a medium the user has not chosen: the bank would refuse the
+   * login, and the client would not send the PIN again.
+   */
+  newDialog(): ProtocolDialog<R, O> {
+    const method = this.method;
+    if (this.lacksMedium(method)) {
+      throw new FinTsUnsupportedError(
+        `The TAN method ${method.name} needs a TAN medium, and the client could not learn one: the bank lists no ` +
+          'active medium for it, or does not offer or permit the list of TAN media, or rejected it. Pass a medium to ' +
+          'selectTanMethod, or choose another method',
+      );
+    }
+    return this.protocol.newDialog(method, this.state.tanMedium);
+  }
+
+  /**
+   * The dialog that looks up the TAN media, signed with the TAN method in use.
+   *
+   * It runs before the medium is known, so it names a placeholder where the method needs one; the bank ignores the
+   * medium in this dialog (PIN/TAN B.4.3.1.3).
+   */
+  lookupDialog(): ProtocolDialog<R, O> {
+    const method = this.method;
+    return this.protocol.newDialog(method, this.lacksMedium(method) ? noReference : this.state.tanMedium);
+  }
+
+  /**
+   * The synchronization dialog. It runs before the TAN media are looked up, so its method must do without a medium the
+   * user has not chosen: the placeholder for one is meant for the lookup only (PIN/TAN B.4.3.1.3). The first method
+   * that does signs it:
+   * 1. the TAN method in use;
+   * 2. the one-step method, as for a user whose methods are not known yet (PIN/TAN B.4.3.1), unless the bank has refused
+   *    a one-step login;
+   * 3. another two-step method the user may use.
+   *
+   * Throws `FinTsUnsupportedError` if none does, before the bank could refuse the login.
+   */
+  synchronizationDialog(): ProtocolDialog<R, O> {
+    const method = this.method;
+    if (!this.lacksMedium(method)) return this.protocol.newDialog(method, this.state.tanMedium);
+    if (!this.oneStepRefused) return this.protocol.newDialog(TanMethod.oneStep);
+    const other = this.available().find((m) => !m.isOneStep && !this.lacksMedium(m));
+    if (other !== undefined) return this.protocol.newDialog(other);
+    throw new FinTsUnsupportedError(
+      `The bank refuses the one-step method, and the TAN method ${method.name} needs a TAN medium, which the client ` +
+        'can look up only after the synchronization. Pass the medium to selectTanMethod, or choose another method',
+    );
+  }
+
+  /** Whether `method` needs a medium the user has not chosen. */
+  private lacksMedium(method: TanMethod): boolean {
+    return this.state.tanMedium === undefined && needsMediumChoice(method);
+  }
+
+  /**
+   * The two-step TAN methods the bank offers, the user may use and this client can run; the one-step method if there
+   * are none.
+   *
+   * Throws `FinTsUnsupportedError` if the bank offers the user nothing but methods the client cannot run.
+   */
+  available(): TanMethod[] {
+    const bpd = this.protocol.bankParameters;
+    if (bpd === undefined) return [TanMethod.oneStep];
+    const allowed = this.state.allowedMethods ?? this.protocol.userParameters?.allowedTanMethods;
+    const isAllowed = (securityFunction: string): boolean =>
+      allowed === undefined || allowed.length === 0 || allowed.includes(securityFunction);
+    const runnable = bpd.tanMethods.filter((m) => isAllowed(m.securityFunction));
+    if (runnable.length === 0 && bpd.unsupportedTanMethods.some(isAllowed)) {
+      throw new FinTsUnsupportedError(
+        'The bank offers only TAN methods this client cannot run: process variant 1, or methods that need an SMS ' +
+          'charge account or an HHD_UC answer',
+      );
+    }
+    return runnable.length === 0 ? [TanMethod.oneStep] : runnable;
+  }
+
+  /**
+   * Stops using `rejected`, the method of a login the bank refused; returns whether another available method is left.
+   *
+   * The user chooses that method, unless the one in use is still available: a refused one-step synchronization does
+   * not rule out the method the user chose before.
+   */
+  async replace(rejected: TanMethod): Promise<boolean> {
+    if (rejected.isOneStep) this.oneStepRefused = true;
+    const others = this.available().filter((m) => m.securityFunction !== rejected.securityFunction);
+    if (others.some((m) => m.securityFunction === this.state.tanMethod)) return true;
+    if (others.length === 0) return false;
+    this.state.useTanMethod((await this.prompts.chooseMethod(others)).securityFunction);
+    return true;
+  }
+
+  /** Keeps the chosen TAN method if it is still available, otherwise lets the user choose. */
+  async ensureMethodChosen(): Promise<void> {
+    const candidates = this.available();
+    const method =
+      candidates.find((m) => m.securityFunction === this.state.tanMethod) ??
+      (await this.prompts.chooseMethod(candidates));
+    if (method.securityFunction !== this.state.tanMethod) this.state.useTanMethod(method.securityFunction);
+  }
+
+  /**
+   * Whether the media of the method in use have to be looked up: it needs a medium the user has not chosen, and they
+   * were not looked up for it in this session.
+   */
+  get mediumToLookUp(): boolean {
+    const method = this.method;
+    return this.lacksMedium(method) && !this.mediaLookedUp.has(method.securityFunction);
+  }
+
+  /**
+   * Lets the user choose the medium of the method in use among the active ones in `media`, the result of a lookup;
+   * none where the lookup gave no list or no active medium.
+   */
+  async chooseMedium(media: TanMedium[] | undefined): Promise<void> {
+    const method = this.method;
+    this.lookedUpMedia = media;
+    this.state.useTanMedium(media === undefined ? undefined : await this.chooseMediumOf(method, media));
+    this.mediaLookedUp.add(method.securityFunction);
+  }
+
+  /**
+   * The list of the last lookup, once; `undefined` if there was none since the last time.
+   *
+   * `getTanMedia` takes it, so that the list is not asked for twice in a row. It also outlasts a call that failed for
+   * want of an active medium, so that the app can show the user the list that tells why; later calls ask anew.
+   */
+  takeLookedUpMedia(): TanMedium[] | undefined {
+    const media = this.lookedUpMedia;
+    this.lookedUpMedia = undefined;
+    return media;
+  }
+
+  /** The name of the medium the user chooses among the active ones in `media`; `undefined` if none is active. */
+  private async chooseMediumOf(method: TanMethod, media: readonly TanMedium[]): Promise<string | undefined> {
+    const active = media.filter((m) => m.isActive && m.name !== undefined);
+    // HITAB version 5 names the method each medium belongs to; a medium of another method would not do.
+    const ofMethod = active.filter((m) => m.securityFunction === method.securityFunction);
+    const candidates = ofMethod.length === 0 ? active : ofMethod;
+    if (candidates.length === 0) return undefined;
+    return (await this.prompts.chooseMedium(candidates)).name;
+  }
+}
+
+/**
+ * Whether messages signed with `method` must name the TAN medium: the method requires the name, and the user may have
+ * several media (PIN/TAN, HKTAN "Bezeichnung des TAN-Mediums").
+ */
+function needsMediumChoice(method: TanMethod): boolean {
+  return method.needsMediumName && (method.activeMediaCount ?? 0) > 1;
+}