@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/session/sepa-accounts.ts

@@ -0,0 +1,115 @@
+import { Account, AccountIndex } from '../core/account.js';
+import { FinTsUnsupportedError, tryLookUp } from '../core/errors.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import { sepaAccountsQuery } from '../v3/queries.js';
+import type { DialogRunner } from './dialog-runner.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), and the accounts the app passes completed from both.
+ *
+ * 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, also by
+ * ending the dialog, or names no account in it, it is kept for this client only: an empty list completes nothing, and
+ * saved it would outlast a fault of a single answer until the bank changes its user parameter data.
+ */
+export class SepaAccounts {
+  /**
+   * The list this client keeps unsaved, with the version of the user parameter data it was read under; empty where the
+   * bank rejected it or named no account.
+   */
+  private unsaved: { updVersion: number | undefined; accounts: readonly Account[] } | undefined;
+
+  constructor(
+    private readonly parameters: ParameterStore,
+    private readonly state: SessionState,
+    private readonly dialogs: DialogRunner,
+  ) {}
+
+  /** 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.parameters.userParameters?.accounts ?? [];
+    const listed = new AccountIndex(sepa);
+    const known = new AccountIndex(accounts);
+    return [
+      ...accounts.map((account) => withSepaDetails(account, listed.find(account))),
+      ...sepa.filter((s) => known.find(s) === undefined),
+    ];
+  }
+
+  /**
+   * `account` as the bank knows it: the one of `completedAccounts` it matches, with what the bank states of it first,
+   * so that an account the app has built itself, such as from an IBAN alone, goes out with the account number, the
+   * sub-account and the BIC the bank's orders take, and the currency of its statements. Where the bank names none it
+   * matches, only what identifies `account`, and its currency: the rest, such as the transactions it permits, only the
+   * bank can state.
+   *
+   * Throws `FinTsUnsupportedError` for such an account where the user parameter data list all permitted transactions:
+   * they permit nothing for an account they leave out, and the client cannot tell it from a mistyped one.
+   */
+  async complete(account: Account): Promise<Account> {
+    const known = (await this.completedAccounts()).find((a) => account.matches(a));
+    if (known !== undefined) {
+      // A sub-account belongs to the account number it comes with.
+      const national = known.accountNumber === undefined ? account : known;
+      return known.copyWith({
+        accountNumber: national.accountNumber,
+        subAccount: national.subAccount,
+        iban: known.iban ?? account.iban,
+        bic: known.bic ?? account.bic,
+        currency: known.currency ?? account.currency,
+      });
+    }
+    if (this.parameters.userParameters?.listsAllTransactions === true) {
+      throw new FinTsUnsupportedError("The bank does not name this account among the user's, and so permits nothing");
+    }
+    return new Account({
+      accountNumber: account.accountNumber,
+      subAccount: account.subAccount,
+      bankCode: account.bankCode,
+      countryCode: account.countryCode,
+      iban: account.iban,
+      bic: account.bic,
+      currency: account.currency,
+    });
+  }
+
+  /** 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.parameters.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 = sepaAccountsQuery(this.parameters);
+    if (query === undefined) return [];
+    // Where the bank rejects the list, also by ending the dialog, the accounts stay as the user parameter data state
+    // them: asked again, a bank that ends the dialog in answer would cost each call a login.
+    const accounts = await tryLookUp(() => this.dialogs.query(() => query));
+    if (accounts !== undefined && accounts.length > 0 && updVersion !== undefined && updVersion > 0) {
+      this.state.cacheSepaAccounts(accounts, updVersion);
+    } else {
+      this.unsaved = { updVersion, accounts: accounts ?? [] };
+    }
+    return accounts ?? [];
+  }
+}
+
+/**
+ * A copy of `account`, which shares no date with the user parameter data, with the IBAN and BIC of `match`, its entry
+ * in the SEPA account list, if any.
+ */
+function withSepaDetails(account: Account, match: Account | undefined): 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 });
+}

package/src/session/session-setup.ts

@@ -0,0 +1,184 @@
+import type { BankInfo } from '../core/bank-info.js';
+import { FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData, tryLookUp } from '../core/errors.js';
+import { hasErrors } from '../core/feedback.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import { FinTs3Dialog } from '../v3/dialog.js';
+import type { IncomingMessage3 } from '../v3/message.js';
+import { requireBankParameters } from '../v3/parameters.js';
+import type { FinTs3Protocol } from '../v3/protocol.js';
+import { tanMediaQuery } from '../v3/queries.js';
+import type { RefusalReason } from './login-guard.js';
+import { SignedDialog, type SessionParts } from './signed-dialog.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 {
+  constructor(
+    private readonly session: SessionParts,
+    private readonly protocol: FinTs3Protocol,
+    private readonly tans: TanSelection,
+  ) {}
+
+  /**
+   * 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.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    if (this.session.parameters.bankParameters === undefined) await this.synchronizeIfDue();
+    return requireBankParameters(this.session.parameters.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. Returns the TAN
+   * media it looked up to choose the medium; `undefined` where it looked up none, or the bank listed none.
+   */
+  async prepare(): Promise<TanMedium[] | undefined> {
+    await this.loadParameters();
+    await this.tans.ensureMethodChosen();
+    if (!this.tans.mediumToLookUp) return undefined;
+    const media = await this.lookUpTanMedia();
+    await this.tans.chooseMedium(media);
+    return media;
+  }
+
+  /** A new dialog signed with the TAN method and medium in use, once `prepare` has settled them. */
+  async newDialog(): Promise<SignedDialog> {
+    await this.prepare();
+    return new SignedDialog(this.tans.newDialog(), this.session);
+  }
+
+  /** Runs `attempt`, which may log in, once more after each refused login `remedy` takes care of. */
+  remedied<T>(attempt: () => Promise<T>): Promise<T> {
+    return this.session.guard.remedied(attempt, (reason, rejected) => this.remedy(reason, rejected));
+  }
+
+  /**
+   * Takes care of `reason`, given for refusing a login signed with `rejected`, with another TAN method or a new
+   * synchronization; 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.session.parameters.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.session.parameters.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.session.guard.check();
+    if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    await this.synchronizeIfDue();
+  }
+
+  /**
+   * Asks for the bank parameter data without logging in, keeps them where there are none from a dialog signed with the
+   * PIN (`ParameterStore.keepAnonymous`), and passes the bank's messages on: all an anonymous dialog tells, since the
+   * TAN methods it lists are not those of a user. 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 {
+      const response = await this.requestBankParametersAnonymously();
+      this.session.parameters.keepAnonymous(response);
+      for (const message of response.bankMessages) this.session.prompts.showBankMessage(message);
+    } catch (error) {
+      // Optional: the login delivers the parameters as well.
+      if (error instanceof FinTsTransportError || !(error instanceof FinTsError)) throw error;
+    }
+  }
+
+  /**
+   * Asks for the bank parameter data in an anonymous dialog that announces strong customer authentication; a bank that
+   * rejects the announcement, with a return code or by failing on it, is asked again without it.
+   *
+   * A timeout or a broken connection is not a reason to ask again: it would only double the wait.
+   */
+  private async requestBankParametersAnonymously(): Promise<IncomingMessage3> {
+    let announced: IncomingMessage3;
+    try {
+      announced = await this.anonymousDialog(true);
+    } catch (error) {
+      if (error instanceof FinTsTransportError && error.statusCode === undefined) throw error;
+      if (!(error instanceof FinTsError)) throw error;
+      return this.anonymousDialog(false);
+    }
+    if (!hasErrors(announced.feedback) || announced.find('HIBPA') !== undefined) return announced;
+    return this.anonymousDialog(false);
+  }
+
+  private async anonymousDialog(announceSca: boolean): Promise<IncomingMessage3> {
+    const dialog = FinTs3Dialog.anonymous(this.protocol);
+    try {
+      return await dialog.requestBankParameters(announceSca);
+    } finally {
+      await dialog.end();
+    }
+  }
+
+  /**
+   * Runs the synchronization, a login in a dialog of its own, while there is no customer system ID, without which no
+   * regular dialog starts. It runs before the TAN method and medium are settled (`TanSelection.synchronizationDialog`
+   * tells which method signs it).
+   */
+  private async synchronizeIfDue(): Promise<void> {
+    if (this.session.parameters.systemId !== undefined) return;
+    await this.once(this.tans.synchronizationDialog(), (dialog) => dialog.login(true));
+    // Set by the synchronization, which the compiler cannot see.
+    if ((this.session.parameters.systemId as string | undefined) === undefined) {
+      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 = tanMediaQuery(this.session.parameters);
+    if (query === undefined) return undefined;
+    return tryLookUp(() =>
+      this.once(this.tans.lookupDialog(), async (dialog) => {
+        const answers = await dialog.loginWith(query.order(undefined));
+        return parseBankData(() => query.read(answers));
+      }),
+    );
+  }
+
+  /** Runs `use` in `dialog`, a dialog of its own, and ends it afterwards, however `use` ends. */
+  private async once<T>(dialog: FinTs3Dialog, use: (dialog: SignedDialog) => Promise<T>): Promise<T> {
+    const signed = new SignedDialog(dialog, this.session);
+    try {
+      return await use(signed);
+    } finally {
+      await signed.end();
+    }
+  }
+}

package/src/session/session-state.ts

@@ -0,0 +1,204 @@
+import { Account } from '../core/account.js';
+import { hostOf, type FinTsConfig } from '../core/config.js';
+import { FinTsFeedback } from '../core/feedback.js';
+import { FormatError } from '../util/errors.js';
+import {
+  isJsonObject,
+  isString,
+  readObject,
+  readOptionalInt,
+  readOptionalObject,
+  readOptionalList,
+  readOptionalString,
+  type JsonObject,
+} from '../util/json.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import type { LoginGuard, LoginGuardState } from './login-guard.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, the parameter data and the guard's refusal as JSON, which `restoreSession` reads. */
+export function saveSession(parameters: ParameterStore, guard: LoginGuard, session: SessionState): string {
+  return JSON.stringify({
+    format: stateFormat,
+    version: protocolVersion,
+    owner: ownerOf(parameters.config),
+    session: session.toJson(),
+    // Under the key the Dart package reads as well.
+    protocol: parameters.saveState(),
+    loginGuard: guardStateToJson(guard.saveState()),
+  });
+}
+
+/**
+ * The session saved in `json`, and the parameter data and the guard's refused login 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. The refused login belongs to the user at the bank, so it comes first: it holds
+ * for another server or protocol version as well, and where the rest is damaged; a state saved by the Dart package or
+ * an earlier version has none.
+ */
+export function restoreSession(json: string | undefined, parameters: ParameterStore, guard: LoginGuard): SessionState {
+  if (json === undefined) return new SessionState();
+  try {
+    const saved: unknown = JSON.parse(json);
+    if (!isJsonObject(saved) || saved.format !== stateFormat) return new SessionState();
+    const [server, ...user] = readOptionalList(saved, 'owner', isString) ?? [];
+    const expected = userOf(parameters.config);
+    if (user.length !== expected.length || user.some((value, i) => value !== expected[i])) return new SessionState();
+    const loginGuard = readOptionalObject(saved, 'loginGuard');
+    if (loginGuard !== undefined) guard.restoreState(guardStateFromJson(loginGuard));
+    if (server !== hostOf(parameters.config.url) || saved.version !== protocolVersion) return new SessionState();
+    const session = SessionState.fromJson(readObject(saved, 'session'));
+    parameters.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: the server, then `userOf`. */
+function ownerOf(config: FinTsConfig): string[] {
+  return [hostOf(config.url), ...userOf(config)];
+}
+
+/** The user at the bank, whom a refused login belongs to. */
+function userOf(config: FinTsConfig): string[] {
+  return [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,
+  });
+}
+
+function guardStateToJson(state: LoginGuardState): JsonObject {
+  return { refusal: state.refusal?.map(feedbackToJson) ?? null, unreadLogins: state.unreadLogins };
+}
+
+function guardStateFromJson(json: JsonObject): LoginGuardState {
+  return {
+    refusal: readOptionalList(json, 'refusal', isJsonObject)?.map(feedbackFromJson),
+    unreadLogins: readOptionalInt(json, 'unreadLogins') ?? 0,
+  };
+}
+
+function feedbackToJson(f: FinTsFeedback): JsonObject {
+  return { code: f.code, reference: f.reference ?? null, text: f.text, parameters: [...f.parameters] };
+}
+
+function feedbackFromJson(json: JsonObject): FinTsFeedback {
+  const code = readOptionalString(json, 'code');
+  if (code === undefined) throw new FormatError('Saved state: return code without code');
+  return new FinTsFeedback({
+    code,
+    reference: readOptionalString(json, 'reference'),
+    text: readOptionalString(json, 'text') ?? '',
+    parameters: readOptionalList(json, 'parameters', isString) ?? [],
+  });
+}