@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/session/app-approval.ts

@@ -0,0 +1,265 @@
+import { FinTsDecoupledTimeoutError, FinTsTanCancelledError } from '../core/errors.js';
+import { FeedbackCodes, hasCode } from '../core/feedback.js';
+import { nextAttempt, withResolved, type TanAnswer, type TanChallenge } from '../tan/challenge.js';
+import type { TanMethod } from '../tan/tan-models.js';
+import { Deferred } from '../util/async.js';
+import { invalidArgument } from '../util/errors.js';
+import type { Approval, BankResponse } from './protocol.js';
+
+/** How long to wait for an app approval when the bank does not say. */
+const defaultMaxStatusPolls = 60;
+const defaultFirstPollDelayMs = 2_000;
+const defaultPollIntervalMs = 2_000;
+
+/** Bounds for the bank's polling parameters, against faulty parameter data. */
+const minPollIntervalMs = 1_000;
+const maxPollDelayMs = 60_000;
+const maxApprovalWaitMs = 10 * 60_000;
+
+/** Shows a challenge and returns the user's answer. */
+export type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
+
+/** Waits for `delayMs`, or until `interrupt` settles. */
+export type Pause = (delayMs: number, interrupt?: Promise<unknown>) => Promise<void>;
+
+/** What an `AppApprovalWait` needs: `ask` shows a challenge, `pause` waits, `receive` takes in each status response. */
+export interface AppApprovalHooks<R> {
+  readonly ask: AskUser;
+  readonly pause: Pause;
+  /** Takes in each status response; throws if it reports errors. */
+  readonly receive: (response: R) => void;
+}
+
+/**
+ * Waits for the user to approve a message in the banking app, and for the bank to confirm it (PIN/TAN B.4.2.2).
+ *
+ * The bank's parameters decide who triggers the status requests:
+ * - The client polls by itself while the callback shows the instructions (`PollingWhileShown`) where the bank allows
+ *   automatic status requests and announces no push message (3957), and also where the user cannot report the
+ *   approval: then polling is the one way left to complete it, whatever the other parameters say (step 2a).
+ * - Otherwise the client asks after each report of the user (`PollingAfterReports`), which stands in for the push
+ *   message the client cannot receive.
+ *
+ * The bank's limit on status requests holds either way, and two requests are at least a second apart. One instance
+ * handles one `Approval`; `run` may be called once. A failure of `ask` or `pause`, such as a closed client, ends the
+ * wait.
+ */
+export function appApprovalWait<R extends BankResponse>(
+  approval: Approval<R>,
+  hooks: AppApprovalHooks<R>,
+): AppApprovalWait<R> {
+  const method = approval.challenge.method;
+  const automatic = !method.decoupledManualConfirmation || (method.decoupledAutomaticPolling && !approval.waitForPush);
+  return automatic ? new PollingWhileShown(approval, hooks) : new PollingAfterReports(approval, hooks);
+}
+
+export abstract class AppApprovalWait<R extends BankResponse> {
+  private requests = 0;
+
+  /** The time the client waited by itself, which counts towards the longest wait. */
+  protected waitedMs = 0;
+
+  constructor(
+    protected readonly approval: Approval<R>,
+    protected readonly hooks: AppApprovalHooks<R>,
+  ) {}
+
+  /**
+   * Returns the bank's response once the approval is through. Throws `FinTsTanCancelledError` if the user cancels and
+   * `FinTsDecoupledTimeoutError` if the approval takes too long.
+   */
+  abstract run(): Promise<R>;
+
+  protected get method(): TanMethod {
+    return this.approval.challenge.method;
+  }
+
+  /** Whether the user may report the approval (PIN/TAN, "Manuelle Bestätigung möglich"). */
+  protected get userConfirms(): boolean {
+    return this.method.decoupledManualConfirmation;
+  }
+
+  protected get pollIntervalMs(): number {
+    return clamp(
+      seconds(this.method.decoupledPollIntervalSeconds) ?? defaultPollIntervalMs,
+      minPollIntervalMs,
+      maxPollDelayMs,
+    );
+  }
+
+  protected get firstPollDelayMs(): number {
+    return clamp(seconds(this.method.decoupledFirstPollDelaySeconds) ?? defaultFirstPollDelayMs, 0, maxPollDelayMs);
+  }
+
+  /**
+   * Sends the next status request and returns the answer, once `receive` has taken it in.
+   *
+   * Throws if the answer reports errors, and `FinTsDecoupledTimeoutError` if the approval is still pending after as
+   * many requests as the bank allows, or after the longest wait.
+   */
+  protected async requestStatus(): Promise<R> {
+    const response = await this.approval.checkStatus();
+    this.requests++;
+    this.hooks.receive(response);
+    // A maximum of 0 allows any number of requests (PIN/TAN, "Maximale Anzahl Statusabfragen Decoupled").
+    const maxRequests = this.method.decoupledMaxPolls ?? defaultMaxStatusPolls;
+    if (
+      isPending(response) &&
+      ((maxRequests > 0 && this.requests >= maxRequests) || this.waitedMs >= maxApprovalWaitMs)
+    ) {
+      throw new FinTsDecoupledTimeoutError();
+    }
+    return response;
+  }
+
+  /**
+   * `challenge` as the next prompt, with the new instructions of `pending`, the last status answer, where it gives any
+   * (PIN/TAN B.4.2.2.1, step 2b).
+   */
+  protected nextPrompt(challenge: TanChallenge, pending: R): TanChallenge {
+    return nextAttempt(challenge, this.approval.instructionsIn(pending));
+  }
+}
+
+/**
+ * The client polls by itself while the callback shows the instructions, and settles `TanChallenge.resolved` when it is
+ * done.
+ *
+ * `run` shows the prompt, waits the bank's first delay, then asks the bank until it confirms, waiting the interval in
+ * between. The callback's answer only records what the user did:
+ * - `stopped` settles on a cancel, a TAN or a failing callback; the loop stops before its next request.
+ * - `report` settles on a report of the approval, which cuts the current wait short once, though not below a second.
+ *   The report closed the prompt, so it is shown anew while the bank has not confirmed yet.
+ * - A user who cannot report the approval has every answer but `TanAnswer.cancelled` ignored.
+ */
+class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
+  /** Settles when the client needs no more answer, which `TanChallenge.resolved` tells the callback. */
+  private readonly finished = new Deferred<void>();
+
+  /** Settles when the user cancels or the callback fails; `stopReason` holds the error that ends the wait. */
+  private readonly stopped = new Deferred<void>();
+  private stopReason: { error: unknown } | undefined;
+
+  /** Settles when the user reports the approval in the prompt shown now; `undefined` once the report was used. */
+  private report: Deferred<void> | undefined;
+
+  async run(): Promise<R> {
+    let challenge = this.approval.challenge;
+    this.show(challenge);
+    try {
+      await this.sleep(this.firstPollDelayMs);
+      for (;;) {
+        this.throwIfStopped();
+        // A request under way is awaited even when the user cancels meanwhile; its answer counts.
+        const response = await this.requestStatus();
+        if (!isPending(response)) return response;
+        this.throwIfStopped();
+        // The user reported the approval, which closed the prompt, but the bank has not confirmed it yet.
+        if (this.userConfirms && this.report === undefined)
+          this.show((challenge = this.nextPrompt(challenge, response)));
+        await this.sleep(this.pollIntervalMs, minPollIntervalMs);
+      }
+    } finally {
+      this.finished.resolve();
+    }
+  }
+
+  /** Shows `challenge` without waiting for the answer. */
+  private show(challenge: TanChallenge): void {
+    const report = (this.report = this.userConfirms ? new Deferred<void>() : undefined);
+    void this.hooks.ask(withResolved(challenge, this.finished.promise)).then(
+      (answer) => {
+        switch (answer.kind) {
+          case 'cancelled':
+            this.stop(new FinTsTanCancelledError());
+            break;
+          case 'approved':
+            report?.resolve();
+            break;
+          case 'tan':
+            if (report !== undefined) this.stop(tanForApproval());
+            break;
+          // The user cannot report the approval: the client waits for the bank.
+        }
+      },
+      (error: unknown) => {
+        this.stop(error);
+      },
+    );
+  }
+
+  private stop(error: unknown): void {
+    if (this.stopped.isCompleted) return;
+    this.stopReason = { error };
+    this.stopped.resolve();
+  }
+
+  private throwIfStopped(): void {
+    if (this.stopReason !== undefined) throw this.stopReason.error;
+  }
+
+  /**
+   * Waits for `delayMs`, or until the user cancels or reports the approval; a report does not cut the wait below
+   * `floorMs`. A wait cut short counts towards the longest wait with its floor only.
+   */
+  private async sleep(delayMs: number, floorMs = 0): Promise<void> {
+    const report = this.report;
+    if (floorMs > 0) await this.hooks.pause(floorMs, this.stopped.promise);
+    const interrupt =
+      report === undefined ? this.stopped.promise : Promise.race([this.stopped.promise, report.promise]);
+    await this.hooks.pause(delayMs - floorMs, interrupt);
+    const cutShort = report?.isCompleted ?? false;
+    this.waitedMs += cutShort ? floorMs : delayMs;
+    // One report, one early request.
+    if (cutShort) this.report = undefined;
+  }
+}
+
+/**
+ * The client asks the bank after each report of the user; while the approval is pending, the user is asked again with
+ * the bank's latest instructions.
+ */
+class PollingAfterReports<R extends BankResponse> extends AppApprovalWait<R> {
+  async run(): Promise<R> {
+    let challenge = this.approval.challenge;
+    await this.confirm(challenge);
+    for (;;) {
+      const response = await this.requestStatus();
+      if (!isPending(response)) return response;
+      challenge = this.nextPrompt(challenge, response);
+      // The prompt comes back at once; however fast the user reports again, the next request waits a second.
+      await Promise.all([this.confirm(challenge), this.hooks.pause(minPollIntervalMs)]);
+      this.waitedMs += minPollIntervalMs;
+    }
+  }
+
+  /** Shows `challenge` and waits until the user reports the approval or cancels. */
+  private async confirm(challenge: TanChallenge): Promise<void> {
+    const answer = await this.hooks.ask(challenge);
+    switch (answer.kind) {
+      case 'approved':
+        return;
+      case 'cancelled':
+        throw new FinTsTanCancelledError();
+      case 'tan':
+        throw tanForApproval();
+    }
+  }
+}
+
+/** Whether `response` tells that the approval is still pending (return code 3956). */
+function isPending(response: BankResponse): boolean {
+  return hasCode(response.feedback, FeedbackCodes.decoupledStillPending);
+}
+
+function tanForApproval(): TypeError {
+  return invalidArgument('Answered an approval in the banking app with a TAN', 'tanCallback');
+}
+
+function seconds(value: number | undefined): number | undefined {
+  return value === undefined ? undefined : value * 1000;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}

package/src/session/bank-connection.ts

@@ -0,0 +1,51 @@
+import type { MessageDirection, MessageLogger } from '../core/client.js';
+import { FinTsError, FinTsProtocolError, FinTsTransportError } from '../core/errors.js';
+import { HttpTransport, type FinTsTransport } from '../core/transport.js';
+
+/**
+ * Throws `FinTsProtocolError` if a message of `size` bytes exceeds the bank's `limit` in kilobytes (1024 bytes): the
+ * specification does not allow to send such a message.
+ */
+export function checkMessageSize(size: number, limit: number | undefined): void {
+  if (limit !== undefined && limit > 0 && size > limit * 1024) {
+    throw new FinTsProtocolError(`A message of ${size} bytes exceeds the bank's maximum message size of ${limit} KB`);
+  }
+}
+
+/** The bank's FinTS endpoint: posts messages there and reports them to the logger. */
+export class BankConnection {
+  private readonly transport: FinTsTransport;
+
+  /** A connection to `url` through `transport`, an `HttpTransport` by default. */
+  constructor(
+    /** Where the messages go. */
+    readonly url: URL,
+    transport: FinTsTransport | undefined,
+    private readonly logger: MessageLogger | undefined,
+  ) {
+    this.transport = transport ?? new HttpTransport();
+  }
+
+  /**
+   * Posts `body`; reports any failure of the transport as `FinTsError`, with the original as its `cause`: a custom
+   * transport that calls `fetch` fails with a `TypeError` where the network does.
+   */
+  async post(body: Uint8Array, contentType: string): Promise<Uint8Array> {
+    try {
+      return await this.transport.post(this.url, body, contentType);
+    } catch (error) {
+      if (error instanceof FinTsError) throw error;
+      throw new FinTsTransportError(error instanceof Error ? error.message : String(error), { cause: error });
+    }
+  }
+
+  /** Reports a message to the logger; `message` is only built when a logger is set. */
+  log(direction: MessageDirection, message: () => string): void {
+    this.logger?.(direction, message());
+  }
+
+  /** Closes the transport. */
+  close(): void {
+    this.transport.close();
+  }
+}

package/src/session/dialog-runner.ts

@@ -0,0 +1,119 @@
+import { FinTsBankError, FinTsProtocolError, parseBankData } from '../core/errors.js';
+import { continuations, FeedbackCodes, hasCode } from '../core/feedback.js';
+import type { BankResponse, ProtocolDialog, Query } from './protocol.js';
+import type { ResponseHandler } from './response-handler.js';
+import type { SessionSetup } from './session-setup.js';
+import type { UserPrompts } from './user-prompts.js';
+
+/** Most pages the client fetches for one query, far more than banks send. */
+const maxPages = 1000;
+
+/** Most data one query may hold, summed over its pages: the transport bounds a single response only. */
+const maxQueryMebibytes = 128;
+
+/**
+ * Keeps one dialog open for all calls and runs the queries in it.
+ *
+ * A dialog the bank has ended is not used again: the call that learns of it fails, and the next call logs in anew. The
+ * client does not repeat the call by itself, since the bank's answer cannot tell a dialog that had ended before from an
+ * order it refuses along with ending the dialog, and a new login may cost the user another approval.
+ */
+export class DialogRunner<R extends BankResponse, O> {
+  private dialog: ProtocolDialog<R, O> | undefined;
+
+  constructor(
+    private readonly setup: SessionSetup<R, O>,
+    private readonly responses: ResponseHandler<R>,
+    private readonly prompts: UserPrompts,
+  ) {}
+
+  /** The open dialog, or a new one once the setup is complete and the user has passed strong authentication. */
+  async open(): Promise<ProtocolDialog<R, O>> {
+    const current = this.dialog;
+    if (current?.isActive === true) return current;
+    this.dialog = undefined;
+    const dialog = await this.setup.remedied(() => this.login());
+    this.dialog = dialog;
+    return dialog;
+  }
+
+  private async login(): Promise<ProtocolDialog<R, O>> {
+    const dialog = await this.setup.newDialog();
+    try {
+      await this.responses.startDialog(dialog, () => dialog.start());
+      return dialog;
+    } catch (error) {
+      // After a refused login the dialog is discarded already, and ending it sends nothing. After any other failure,
+      // such as a cancelled TAN, the bank still knows the dialog.
+      await dialog.end();
+      throw error;
+    }
+  }
+
+  /** Ends the open dialog, if there is one. */
+  async end(): Promise<void> {
+    const dialog = this.dialog;
+    this.dialog = undefined;
+    await dialog?.end();
+  }
+
+  /**
+   * Runs the query `build` returns in the session's dialog and reads all its pages.
+   *
+   * The query is built once the dialog is open, since building it takes the parameter data.
+   */
+  async query<T>(build: () => Query<R, O, T>): Promise<T> {
+    const dialog = await this.open();
+    const query = build();
+    const pages = await this.fetchPages(dialog, query.order);
+    return parseBankData(() => query.read(pages));
+  }
+
+  /** Sends `order` in `dialog` and completes its approval. */
+  private async run(dialog: ProtocolDialog<R, O>, order: O): Promise<R> {
+    this.prompts.checkOpen();
+    try {
+      return await this.responses.complete(dialog, await dialog.send(order));
+    } catch (error) {
+      // The bank rejected the order and the dialog stays usable, or the bank ended the dialog or rejected the PIN and
+      // the dialog is discarded already. A cancelled or failed approval, or a broken connection, leaves the dialog in an
+      // unknown state.
+      if (!(error instanceof FinTsBankError)) await this.end();
+      throw error;
+    }
+  }
+
+  /** Sends the order built by `order` until the bank has delivered all pages (Formals B.6.3, "Aufsetzpunkt"). */
+  private async fetchPages(dialog: ProtocolDialog<R, O>, order: (continuation: string | undefined) => O): Promise<R[]> {
+    const pages: R[] = [];
+    const seen = new Set<string>();
+    let size = 0;
+    let continuation: string | undefined;
+    for (;;) {
+      const page = await this.run(dialog, order(continuation));
+      pages.push(page);
+      size += page.size;
+      const positions = [...continuations(page.feedback)];
+      // A message carries one order, so the bank names one position at most.
+      if (positions.length > 1) throw new FinTsProtocolError('The bank names several positions to continue at');
+      continuation = positions[0];
+      if (continuation === undefined) {
+        // Read as the last page, more data without a position would look like all there is.
+        if (hasCode(page.feedback, FeedbackCodes.moreData)) {
+          throw new FinTsProtocolError('The bank has more data, but names no position to continue at');
+        }
+        return pages;
+      }
+      // A repeated position or endless pages would keep the client busy forever, and unbounded pages exhaust memory.
+      if (seen.has(continuation) || pages.length === maxPages) {
+        throw new FinTsProtocolError('The bank does not stop sending pages');
+      }
+      seen.add(continuation);
+      if (size > maxQueryMebibytes * 1024 * 1024) {
+        throw new FinTsProtocolError(
+          `The bank sends more than ${maxQueryMebibytes} MiB for one query; ask for a shorter period`,
+        );
+      }
+    }
+  }
+}

package/src/session/login-guard.ts

@@ -0,0 +1,135 @@
+import { FinTsBankError, FinTsLoginDataChangedError, FinTsPinError, FinTsTanError } from '../core/errors.js';
+import { allowedTanMethodsIn, FeedbackCodes, hasCode } from '../core/feedback.js';
+import type { TanMethod } from '../tan/tan-models.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;
+ * - `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';
+
+/**
+ * A reason for a refused login that the session can take care of by itself, after which it logs in once more: the user
+ * may not use the TAN method the login was signed with, or the bank no longer accepts the customer system ID.
+ */
+export type RefusalReason = 'tanMethodNotAllowed' | 'systemIdRejected';
+
+/**
+ * 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`).
+ *
+ * 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.
+ */
+export class LoginGuard {
+  private refusal: FinTsBankError | undefined;
+
+  /** The TAN method of the refused login; `undefined` without a refusal, and for new login data. */
+  private refusedMethodValue: TanMethod | undefined;
+
+  /** Throws the bank's refusal of an earlier login, so that the PIN is not sent again. */
+  check(): void {
+    if (this.refusal !== undefined) throw this.refusal;
+  }
+
+  /** Whether the guard holds a refusal. */
+  get hasRefusal(): boolean {
+    return this.refusal !== undefined;
+  }
+
+  /** 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;
+  }
+
+  /**
+   * 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.
+   */
+  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;
+    }
+    return refused;
+  }
+
+  /** 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 `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.
+   */
+  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;
+    }
+  }
+
+  /**
+   * 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.
+   */
+  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');
+    }
+    if (hasCode(feedback, FeedbackCodes.newSystemIdRequired)) reasons.push('systemIdRejected');
+    return reasons;
+  }
+
+  /** 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 isRefusal(error: unknown): boolean {
+    return error === this.refusal;
+  }
+}