@coderoftime/fints 0.1.0 → 0.3.0

package/src/session/login-guard.ts

@@ -1,16 +1,23 @@
-import { FinTsBankError, FinTsLoginDataChangedError, FinTsPinError, FinTsTanError } from '../core/errors.js';
-import { allowedTanMethodsIn, FeedbackCodes, hasCode } from '../core/feedback.js';
+import {
+  clientClosedError,
+  FinTsLoginDataChangedError,
+  FinTsLoginRefusedError,
+  FinTsPinError,
+  loginRefusalFor,
+  type FinTsBankError,
+} from '../core/errors.js';
+import { allowedTanMethodsIn, FeedbackCodes, hasCode, type FinTsFeedback } from '../core/feedback.js';
 import type { TanMethod } from '../tan/tan-models.js';
+import type { PinGuard } from '../v3/protocol.js';
 
 /**
  * The kind of request a bank response answers, which decides what its errors mean for the login (`LoginGuard.judge`)
  * and whether they can reject a TAN:
- * - `login`: the login that opens a dialog;
- * - `loginWithOrder`: a login that carries an order in the same message, whose errors may concern the order alone;
+ * - `login`: the login that opens a dialog, which carries no order;
  * - `order`: an order in a dialog the bank has opened;
  * - `approval`: a message that completes an approval, the TAN or the question whether the user approved in the app.
  */
-export type RequestKind = 'login' | 'loginWithOrder' | 'order' | 'approval';
+export type RequestKind = 'login' | 'order' | 'approval';
 
 /**
  * A reason for a refused login that the session can take care of by itself, after which it logs in once more: the user
@@ -18,118 +25,213 @@ export type RequestKind = 'login' | 'loginWithOrder' | 'order' | 'approval';
  */
 export type RefusalReason = 'tanMethodNotAllowed' | 'systemIdRejected';
 
+/** What the saved state keeps of the guard: the return codes of the bank's refusal, and `unreadLogins`. */
+export interface LoginGuardState {
+  readonly refusal: readonly FinTsFeedback[] | undefined;
+  readonly unreadLogins: number;
+}
+
 /**
- * Keeps a retrying app from locking the user's access: once the bank has refused a login, the client does not send the
- * PIN again.
- *
- * Banks lock the access after a few failed attempts, and a return code does not always tell whether the PIN was the
- * reason. So `judge` counts as a refused login:
- * - a rejected PIN, wherever the bank reports it;
- * - any other error in the answer to a login, unless the login carries an order and the bank keeps the dialog open:
- *   then the error concerns the order.
- *
- * Errors in the answer to an order or an approval are no refusal, such as a wrong TAN at login: the bank checks the PIN
- * before it asks for the approval. New login data (return code 3072) end the old ones for good (`refuse`).
+ * Logins in a row whose answer the client could not read, after which it sends the PIN no more: one may be a glitch of
+ * the connection, but with two the client would not learn of a wrong PIN before the bank locks the access.
+ */
+const maxUnreadLogins = 2;
+
+/**
+ * Holds the PIN and hands it out only while no login is refused (`pin`), so that a retrying app cannot lock the user's
+ * access. `FinTsLoginRefusedError` tells which logins count as refused; `judge` decides it for each answer.
  *
- * The guard fails closed: a refusal counts from the moment `judge` sees it, and only `pardon` lifts it, once the
- * session has taken care of a `RefusalReason` the refusal names (`remediableReasons`). The protocol calls `check`
- * before every message it signs with the PIN.
+ * A refusal counts at once and fails closed: only `remedied` lifts it, within the call that met it (`runCall`), once
+ * the session has taken care of a reason it names, or has failed the call trying, each reason once per call, so that a
+ * call sends at most three logins the bank refuses. A refusal that outlasts the call is final, and the guard forgets
+ * the PIN; only a PIN the user enters anew lifts it (`replacePin`), unless it brings new login data.
  */
-export class LoginGuard {
-  private refusal: FinTsBankError | undefined;
+export class LoginGuard implements PinGuard {
+  // ECMAScript private, so that neither `util.inspect` nor `JSON.stringify` of the client reaches it.
+  #pin: string | undefined;
+
+  private refusalValue: FinTsLoginRefusedError | undefined;
+
+  /** The TAN method of the login `refusalValue` refused, which a restored refusal does not tell. */
+  private refusedMethod: TanMethod | undefined;
+
+  /** Logins sent since the bank last took the PIN whose answer the client has not read. */
+  private unreadLogins = 0;
 
-  /** The TAN method of the refused login; `undefined` without a refusal, and for new login data. */
-  private refusedMethodValue: TanMethod | undefined;
+  /** The refusal of `maxUnreadLogins` unread logins, kept so that `check` throws the same error each time. */
+  private unreadLoginsRefusal: FinTsLoginRefusedError | undefined;
 
-  /** Throws the bank's refusal of an earlier login, so that the PIN is not sent again. */
+  /** The reasons `remedied` has lifted a refusal for in the running call. */
+  private readonly pardonedReasons = new Set<RefusalReason>();
+
+  constructor(pin: string) {
+    this.#pin = pin;
+  }
+
+  /** The PIN to sign a message with; throws the refusal instead (`check`), and `FinTsStateError` once closed. */
+  get pin(): string {
+    this.check();
+    if (this.#pin === undefined) throw clientClosedError();
+    return this.#pin;
+  }
+
+  /** Throws the refusal, if there is one. */
   check(): void {
-    if (this.refusal !== undefined) throw this.refusal;
+    const refusal = this.refusal;
+    if (refusal !== undefined) throw refusal;
   }
 
-  /** Whether the guard holds a refusal. */
-  get hasRefusal(): boolean {
-    return this.refusal !== undefined;
+  /** The bank's refusal, else that of `maxUnreadLogins` unread logins; `undefined` while there is none. */
+  get refusal(): FinTsLoginRefusedError | undefined {
+    if (this.refusalValue !== undefined || this.unreadLogins < maxUnreadLogins) return this.refusalValue;
+    this.unreadLoginsRefusal ??= new FinTsLoginRefusedError(
+      [],
+      `The answers to the last ${maxUnreadLogins} logins were lost or unreadable, and the bank may have counted them ` +
+        'as failed attempts',
+    );
+    return this.unreadLoginsRefusal;
   }
 
-  /** The TAN method the refused login was signed with; `undefined` where the guard holds no refusal of a login. */
-  get refusedMethod(): TanMethod | undefined {
-    return this.refusedMethodValue;
+  /** Counts a login signed with the PIN as unread until `judge` reads its answer. */
+  loginSent(): void {
+    this.unreadLogins++;
   }
 
   /**
-   * Whether `error`, raised for the answer to a request of `kind` in a dialog signed with `method`, refuses the login;
-   * records it if it does.
-   *
-   * `dialogOpen` tells whether the bank keeps the dialog open after its answer.
+   * Judges `error`, if the answer to a request of `kind` in a dialog signed with `method` has one: returns the refusal
+   * of the login it amounts to, and records it unless the guard holds one already. Any error refuses a login; after the
+   * login only one that refuses it itself, a rejected PIN or new login data, since the bank checked the PIN before.
    */
-  judge(error: FinTsBankError, kind: RequestKind, dialogOpen: boolean, method: TanMethod): boolean {
-    const refused = error instanceof FinTsPinError || kind === 'login' || (kind === 'loginWithOrder' && !dialogOpen);
-    if (refused && this.refusal === undefined) {
-      this.refusal = error;
-      this.refusedMethodValue = method;
+  judge(error: FinTsBankError | undefined, kind: RequestKind, method: TanMethod): FinTsLoginRefusedError | undefined {
+    const refused = error instanceof FinTsLoginRefusedError || (error !== undefined && kind === 'login');
+    if (kind === 'login') this.unreadLogins = refused ? Math.max(0, this.unreadLogins - 1) : 0;
+    if (!refused) return undefined;
+    const refusal = loginRefusalFor(error.feedback);
+    if (this.refusalValue === undefined) {
+      this.refusalValue = refusal;
+      this.refusedMethod = method;
     }
-    return refused;
+    return refusal;
   }
 
-  /** Records `error` as the reason the client logs in no more, unless it holds a refusal already. */
-  refuse(error: FinTsBankError): void {
-    this.refusal ??= error;
+  /** Runs `call`, one call of the client; a refusal that outlasts it is final, and the next call remedies anew. */
+  async runCall<T>(call: () => Promise<T>): Promise<T> {
+    try {
+      return await call();
+    } finally {
+      this.pardonedReasons.clear();
+      this.forgetPinIfRefused();
+    }
   }
 
   /**
-   * Runs `lookup`, which only completes data, such as the SEPA account list; `undefined` where the bank rejects it, so
-   * that the caller carries on without it.
-   *
-   * A refused login is thrown, and so is a wrong TAN, which the user must hear of. An aborted dialog counts as a
-   * rejection: banks end the dialog along with many.
+   * Runs `attempt`, which may log in, and runs it once more each time `remedy` takes care of a reason the refusal it
+   * failed with names; `remedy` gets the reason and the TAN method of the refused login, and returns whether it could.
    */
-  async tryLookUp<T>(lookup: () => Promise<T>): Promise<T | undefined> {
-    try {
-      return await lookup();
-    } catch (error) {
-      if (!(error instanceof FinTsBankError) || this.isRefusal(error) || error instanceof FinTsTanError) throw error;
-      return undefined;
+  async remedied<T>(
+    attempt: () => Promise<T>,
+    remedy: (reason: RefusalReason, rejected: TanMethod) => Promise<boolean>,
+  ): Promise<T> {
+    // A refusal of an earlier call stops the attempt before it sends the PIN; there is nothing to remedy.
+    if (this.refusal !== undefined) return attempt();
+    for (;;) {
+      try {
+        return await attempt();
+      } catch (error) {
+        const refusal = this.refusalValue;
+        const rejected = this.refusedMethod;
+        // Only the bank's refusal the guard holds names reasons; any other error, a second refusal too, fails the call.
+        if (refusal === undefined || error !== refusal || rejected === undefined) throw error;
+        const reason = remediableReasons(refusal, rejected).find((r) => !this.pardonedReasons.has(r));
+        if (reason === undefined) throw error;
+        this.pardonedReasons.add(reason);
+        // The refusal named a reason the session takes care of, not the PIN, so it does not outlast a remedy that fails,
+        // such as a TAN method prompt the app ends: the call fails with the remedy's own error. On a closed client the
+        // next attempt fails before it sends anything.
+        const remedied = await remedy(reason, rejected).catch((remedyError: unknown) => {
+          this.liftRefusal();
+          throw remedyError;
+        });
+        if (!remedied) throw error;
+        this.liftRefusal();
+      }
     }
   }
 
   /**
-   * The reasons the session can take care of in `error`: 3920 without the TAN method of the refused login, 9075 after
-   * the one-step method, and 9391. Empty if `error` is not the refusal the guard holds, rejects the PIN, or brings new
-   * login data.
-   *
-   * Only the return codes of the refusal itself count: TAN methods listed earlier say nothing about this login.
+   * Signs with `pin` from now on, a PIN the user has entered anew and the protocol can send, and lifts the refusal.
+   * Throws the refusal instead where it brings new login data, which end the old ones for good.
    */
-  remediableReasons(error: FinTsBankError): RefusalReason[] {
-    const method = this.refusedMethodValue;
-    if (
-      !this.isRefusal(error) ||
-      method === undefined ||
-      error instanceof FinTsPinError ||
-      error instanceof FinTsLoginDataChangedError
-    ) {
-      return [];
-    }
-    const feedback = error.feedback;
-    const allowed = allowedTanMethodsIn(feedback);
-    const reasons: RefusalReason[] = [];
-    if (
-      (allowed.length > 0 && !allowed.includes(method.securityFunction)) ||
-      (method.isOneStep && hasCode(feedback, FeedbackCodes.scaRequired))
-    ) {
-      reasons.push('tanMethodNotAllowed');
+  replacePin(pin: string): void {
+    if (this.refusalValue instanceof FinTsLoginDataChangedError) throw this.refusalValue;
+    this.#pin = pin;
+    this.liftRefusal();
+    this.unreadLogins = 0;
+    this.unreadLoginsRefusal = undefined;
+  }
+
+  /** Forgets the PIN; the client calls it once it is closed. */
+  close(): void {
+    this.#pin = undefined;
+  }
+
+  saveState(): LoginGuardState {
+    return { refusal: this.refusalValue?.feedback, unreadLogins: this.unreadLogins };
+  }
+
+  /** Restores what `saveState` returned; a restored refusal is final, also one without return codes. */
+  restoreState(saved: LoginGuardState): void {
+    if (saved.refusal !== undefined) {
+      this.refusalValue =
+        saved.refusal.length > 0
+          ? loginRefusalFor(saved.refusal)
+          : new FinTsLoginRefusedError([], 'A login was refused, and the saved state no longer tells why');
     }
-    if (hasCode(feedback, FeedbackCodes.newSystemIdRequired)) reasons.push('systemIdRejected');
-    return reasons;
+    this.unreadLogins = Math.max(0, saved.unreadLogins);
+    this.forgetPinIfRefused();
   }
 
-  /** Lifts `refusal` once the session has taken care of its reason, so that the next login may send the PIN. */
-  pardon(refusal: FinTsBankError): void {
-    if (!this.isRefusal(refusal)) return;
-    this.refusal = undefined;
-    this.refusedMethodValue = undefined;
+  private liftRefusal(): void {
+    this.refusalValue = undefined;
+    this.refusedMethod = undefined;
   }
 
-  private isRefusal(error: unknown): boolean {
-    return error === this.refusal;
+  private forgetPinIfRefused(): void {
+    if (this.refusal !== undefined) this.#pin = undefined;
   }
 }
+
+/**
+ * The reasons `refusal`, of a login signed with `method`, names that the session can take care of: a TAN method the
+ * refusal names as not allowed (`refusesMethod`), and 9391. None for a rejected PIN or new login data.
+ */
+function remediableReasons(refusal: FinTsLoginRefusedError, method: TanMethod): RefusalReason[] {
+  if (refusal instanceof FinTsPinError || refusal instanceof FinTsLoginDataChangedError) return [];
+  const reasons: RefusalReason[] = [];
+  if (refusesMethod(refusal.feedback, method)) reasons.push('tanMethodNotAllowed');
+  if (hasCode(refusal.feedback, FeedbackCodes.newSystemIdRequired)) reasons.push('systemIdRejected');
+  return reasons;
+}
+
+/**
+ * Error codes that cannot be about the PIN: 9050 (the message contains errors) and 9800, which only say that the
+ * message failed, and 9955 (the one-step method is not allowed).
+ */
+const errorsNotAboutThePin = new Set(['9050', FeedbackCodes.dialogAborted, '9955']);
+
+/**
+ * Whether `feedback`, which refuses a login signed with `method`, names the method as the reason: a 3920 that lists the
+ * methods the user may use without it, or 9075 after the one-step method.
+ *
+ * Only the return codes of the refusal itself count: TAN methods listed earlier say nothing about this login. Banks
+ * list two-step methods only, so a 3920 always leaves the one-step method out, also where the login succeeds. After
+ * the one-step method a 3920 counts only where the bank names no other error than one not about the PIN: any other,
+ * such as "Anmeldung fehlgeschlagen", may be about it. PIN/TAN B.8.2 has the bank answer a one-step dialog of a user
+ * bound to two-step methods with 9955 and 3920.
+ */
+function refusesMethod(feedback: readonly FinTsFeedback[], method: TanMethod): boolean {
+  if (method.isOneStep && hasCode(feedback, FeedbackCodes.scaRequired)) return true;
+  const allowed = allowedTanMethodsIn(feedback);
+  if (allowed.length === 0 || allowed.includes(method.securityFunction)) return false;
+  return !method.isOneStep || feedback.every((f) => !f.isError || errorsNotAboutThePin.has(f.code));
+}

package/src/session/sepa-accounts.ts

@@ -1,55 +1,85 @@
-import type { Account } from '../core/account.js';
-import { FinTsDialogAbortedError } from '../core/errors.js';
+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 { 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).
+ * (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, it is kept
- * for this client only. Where the bank ends the dialog in answer to the list, the next call asks once more.
+ * 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<R extends BankResponse, O> {
+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.
+   * bank rejected it or named no account.
    */
   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 parameters: ParameterStore,
     private readonly state: SessionState,
-    private readonly dialogs: DialogRunner<R, O>,
-    private readonly guard: LoginGuard,
+    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.protocol.userParameters?.accounts ?? [];
+    const accounts = this.parameters.userParameters?.accounts ?? [];
+    const listed = new AccountIndex(sepa);
+    const known = new AccountIndex(accounts);
     return [
-      ...accounts.map((account) => withSepaDetails(account, sepa)),
-      ...sepa.filter((s) => !accounts.some((a) => s.matches(a))),
+      ...accounts.map((account) => withSepaDetails(account, listed.find(account))),
+      ...sepa.filter((s) => known.find(s) === undefined),
     ];
   }
 
-  /** `account` with IBAN and BIC filled in from the list. */
+  /**
+   * `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> {
-    if (account.iban !== undefined && account.bic !== undefined) return account;
-    return withSepaDetails(account, await this.list());
+    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.protocol.userParameters;
+    const upd = this.parameters.userParameters;
     if (
       upd !== undefined &&
       upd.accounts.length > 0 &&
@@ -61,26 +91,12 @@ export class SepaAccounts<R extends BankResponse, O> {
     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();
+    const query = sepaAccountsQuery(this.parameters);
     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) {
+    // 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 ?? [] };
@@ -89,9 +105,11 @@ export class SepaAccounts<R extends BankResponse, O> {
   }
 }
 
-function withSepaDetails(account: Account, sepa: readonly Account[]): Account {
-  const match = sepa.find((s) => account.matches(s));
-  if (match === undefined) return account;
+/**
+ * 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 });
+  return account.copyWith({ iban: account.iban ?? match?.iban, bic: match?.bic ?? account.bic });
 }