@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/v3/bank-connection.ts

@@ -0,0 +1,67 @@
+import type { MessageDirection, MessageLogger } from '../core/client.js';
+import { FinTsProtocolError, FinTsTransportError } from '../core/errors.js';
+import { failureMessage, 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;
+
+  /** Where the messages go, as `FinTsConfig` checked it. */
+  private readonly href: string;
+
+  /** Aborts the requests on their way (`abortRequests`). */
+  private requests = new AbortController();
+
+  /** A connection to `url` through `transport`, an `HttpTransport` by default. */
+  constructor(
+    url: URL,
+    transport: FinTsTransport | undefined,
+    private readonly logger: MessageLogger | undefined,
+  ) {
+    this.href = url.href;
+    this.transport = transport ?? new HttpTransport();
+  }
+
+  /**
+   * Posts `body` to a new copy of the URL, so that a transport that changes the one it is given changes no later
+   * request.
+   *
+   * Reports any failure of the transport as `FinTsTransportError`: a custom transport that calls `fetch` fails with a
+   * `TypeError` where the network does, and one that throws another `FinTsError`, such as `FinTsPinError`, would pass
+   * for an answer of the bank. Of such an error only the message is kept (`failureMessage`), since it may hold `body`,
+   * as the errors of HTTP clients such as axios do.
+   */
+  async post(body: Uint8Array, contentType: string): Promise<Uint8Array> {
+    try {
+      return await this.transport.post(new URL(this.href), body, contentType, this.requests.signal);
+    } catch (error) {
+      if (error instanceof FinTsTransportError) throw error;
+      throw new FinTsTransportError(failureMessage(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());
+  }
+
+  /** Aborts the requests on their way; those posted afterwards, such as the dialog ends of a closing client, go out. */
+  abortRequests(): void {
+    this.requests.abort();
+    this.requests = new AbortController();
+  }
+
+  close(): void {
+    this.transport.close();
+  }
+}

package/src/v3/dialog.ts

@@ -0,0 +1,283 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData } from '../core/errors.js';
+import { endsDialog, FeedbackCodes, hasCode, hasErrors } from '../core/feedback.js';
+import { challengeText, TanChallenge } from '../tan/challenge.js';
+import { TanMethod } from '../tan/tan-models.js';
+import { IncomingMessage3 } from './message.js';
+import { requireBankParameters } from './parameters.js';
+import type { FinTs3Protocol } from './protocol.js';
+import { Segments, TanResponse } from './segments.js';
+import type { SegmentSpec } from './syntax.js';
+
+/** Dialog ID of a dialog the bank has not answered yet, and customer system ID before synchronization. */
+const unassigned = '0';
+
+/** The first version of HKTAN that supports strong customer authentication. */
+const firstScaVersion = 6;
+
+/** The first version of HKTAN that supports app approvals, with the status request (process S). */
+const firstDecoupledVersion = 7;
+
+/**
+ * How long a dialog may stay idle where the bank states no timeout: on the safe side, since a dialog given up too early
+ * only costs a new login, while one kept too long fails the next call.
+ */
+const defaultIdleLimitMs = 5 * 60_000;
+
+/** The bank's request to approve a message with a TAN or in a banking app; `R` is the bank's answer. */
+export interface Approval<R> {
+  /** What the user is asked. */
+  readonly challenge: TanChallenge;
+
+  /** Sends the TAN the user entered. */
+  readonly submitTan: (tan: string) => Promise<R>;
+
+  /** Asks the bank whether the user has approved in the banking app. */
+  readonly checkStatus: () => Promise<R>;
+
+  /**
+   * Whether the bank announces a push message for once the user has approved (return code 3957), before which the
+   * status must not be asked. The client has no push channel, so the user reports the approval instead.
+   */
+  readonly waitForPush: boolean;
+
+  /** The new instructions a status answer gives the user (return code 3956); `undefined` where it gives none. */
+  readonly instructionsIn: (response: R) => string | undefined;
+}
+
+/**
+ * One FinTS 3.0 dialog: numbered messages under the dialog ID the bank assigns in its first answer, signed with a TAN
+ * method and medium, and the approvals the bank asks for. The `FinTs3Protocol` builds the messages and signs them.
+ */
+export class FinTs3Dialog {
+  private systemId: string;
+  private id = unassigned;
+  private messageNumber = 1;
+  private ended = false;
+
+  /** When the bank last answered without rejecting the whole message, which shows it still knows the dialog. */
+  private lastAnswer: number | undefined;
+
+  private constructor(
+    private readonly protocol: FinTs3Protocol,
+    readonly method: TanMethod,
+    /** The TAN medium the messages name, where the method takes one. */
+    readonly tanMedium: string | undefined,
+    private readonly anonymous: boolean,
+  ) {
+    this.systemId = anonymous ? unassigned : (protocol.parameters.systemId ?? unassigned);
+  }
+
+  static signed(protocol: FinTs3Protocol, method: TanMethod, tanMedium?: string): FinTs3Dialog {
+    return new FinTs3Dialog(protocol, method, tanMedium, false);
+  }
+
+  /** A dialog without login, which only delivers the bank parameter data. */
+  static anonymous(protocol: FinTs3Protocol): FinTs3Dialog {
+    return new FinTs3Dialog(protocol, TanMethod.oneStep, undefined, true);
+  }
+
+  /** Whether the bank knows this dialog and it has not ended. */
+  get isActive(): boolean {
+    return this.id !== unassigned && !this.hasEnded;
+  }
+
+  /**
+   * Whether the dialog has ended, on either side.
+   *
+   * The bank ends a dialog idle for longer than its maximum timeout (HIBPA, Formals C.9), or five minutes where it
+   * states none. Such a dialog is neither used nor ended again: the bank would refuse any message in it.
+   */
+  private get hasEnded(): boolean {
+    return this.ended || this.idleTooLong;
+  }
+
+  private get idleTooLong(): boolean {
+    const last = this.lastAnswer;
+    const timeout = this.protocol.parameters.bankParameters?.bankInfo.maxTimeout;
+    // A timeout of 0 or below: the bank keeps idle dialogs without limit.
+    const limit = timeout === undefined ? defaultIdleLimitMs : timeout <= 0 ? undefined : timeout * 1000;
+    return last !== undefined && limit !== undefined && Date.now() - last > limit;
+  }
+
+  /** Whether the messages are signed with a two-step TAN method, so that the bank may ask for approvals. */
+  private get isTwoStep(): boolean {
+    return !this.method.isOneStep;
+  }
+
+  /** The version of the HKTAN segments: that of the HITANS segment the bank describes the method in. */
+  private get tanVersion(): number {
+    return this.protocol.parameters.bankParameters?.tanVersion(this.method) ?? firstScaVersion;
+  }
+
+  /** Opens the dialog; with `synchronize` the bank also assigns a customer system ID. */
+  start(synchronize = false): Promise<IncomingMessage3> {
+    if (synchronize) this.systemId = unassigned;
+    return this.sendSegments([
+      ...this.protocol.initSegments(this.systemId),
+      ...(this.isTwoStep ? [this.tanRequest('HKIDN')] : []),
+      ...(synchronize ? [Segments.synchronization()] : []),
+    ]);
+  }
+
+  /**
+   * The messages that open the dialog and send `order` while no TAN medium is chosen yet, as for listing the media:
+   * `login` opens the dialog, asking strong authentication for `order` with a two-step method, and `order` sends the
+   * order in a message of its own.
+   */
+  startWith(order: SegmentSpec): {
+    readonly login: () => Promise<IncomingMessage3>;
+    readonly order: () => Promise<IncomingMessage3>;
+  } {
+    return {
+      login: () =>
+        this.sendSegments([
+          ...this.protocol.initSegments(this.systemId),
+          ...(this.isTwoStep ? [this.tanRequest(order.type)] : []),
+        ]),
+      order: () => this.sendSegments([order]),
+    };
+  }
+
+  /**
+   * Opens the anonymous dialog; the answer carries the bank parameter data.
+   *
+   * With `announceSca` the message also carries HKTAN, the way a client that can do strong customer authentication
+   * tells the bank so, whereupon the bank may send parameter data suited to it (PIN/TAN, B.4.3.1).
+   */
+  requestBankParameters(announceSca = false): Promise<IncomingMessage3> {
+    return this.sendSegments([
+      ...this.protocol.initSegments(unassigned, true),
+      ...(announceSca ? [Segments.tanProcess4(firstScaVersion, 'HKIDN')] : []),
+    ]);
+  }
+
+  /** Sends `order`, asking for strong customer authentication where the bank requires it. */
+  send(order: SegmentSpec): Promise<IncomingMessage3> {
+    const needsTan =
+      this.isTwoStep && requireBankParameters(this.protocol.parameters.bankParameters).pinTan.requiresTan(order.type);
+    return this.sendSegments([order, ...(needsTan ? [this.tanRequest(order.type)] : [])]);
+  }
+
+  /**
+   * Ends the dialog at the bank and returns the answer; `undefined` if the dialog is not active or the end failed.
+   *
+   * Bank and connection errors are ignored, since the bank may have ended the dialog on its side already.
+   */
+  async end(): Promise<IncomingMessage3 | undefined> {
+    if (!this.isActive) return undefined;
+    this.ended = true;
+    try {
+      return await this.sendSegments([Segments.dialogEnd(this.id)]);
+    } catch (error) {
+      if (!(error instanceof FinTsError)) throw error;
+      return undefined;
+    }
+  }
+
+  /** Forgets the dialog without contacting the bank, for example after the bank rejected the PIN. */
+  discard(): void {
+    this.ended = true;
+  }
+
+  /**
+   * The approval `response`, the dialog's latest answer, asks for with return code 0030 (TAN) or 3955 (banking app):
+   * HITAN of process 4, answered with HKTAN process 2 (TAN) or S (status); `undefined` if it asks for none, or carries
+   * only the dummy challenge of a message the bank exempts from strong authentication.
+   *
+   * The bank has not executed the message then, so a request without a challenge is a `FinTsProtocolError`: read as
+   * done, it would report an empty result. So is an app approval with a method of HITANS #6: the status request
+   * (process S) came with version 7, along with app approvals (PIN/TAN B.5.2).
+   */
+  approvalAskedIn(response: IncomingMessage3): Approval<IncomingMessage3> | undefined {
+    const feedback = response.feedback;
+    const decoupled = hasCode(feedback, FeedbackCodes.decoupledPending);
+    if (hasErrors(feedback) || !(hasCode(feedback, FeedbackCodes.tanRequired) || decoupled)) return undefined;
+    const tan = tanResponseOf(response, '4');
+    if (tan === undefined || tan.isDummy) {
+      throw new FinTsProtocolError('The bank asks for an approval, but sends no challenge');
+    }
+    if (decoupled && this.tanVersion < firstDecoupledVersion) {
+      throw new FinTsProtocolError('The bank asks for an app approval, which needs HKTAN version 7');
+    }
+    const reference = tan.reference!;
+    return {
+      challenge: TanChallenge.create({
+        method: this.method,
+        reference,
+        message: tan.challenge,
+        hhdUc: tan.hhdUc,
+        isDecoupled: decoupled || this.method.decoupled,
+        validUntil: tan.validUntil,
+        tanMediumName: tan.mediumName ?? this.tanMedium,
+      }),
+      submitTan: (value) => this.sendSegments([Segments.tanProcess2(this.tanVersion, reference)], value),
+      checkStatus: () => this.sendSegments([Segments.tanProcessStatus(this.tanVersion, reference)]),
+      waitForPush: hasCode(feedback, FeedbackCodes.decoupledWaitForPush),
+      // A status answer that the approval is still pending may carry new instructions (PIN/TAN B.4.2.2.1, step 2b).
+      instructionsIn: (status) => challengeText(tanResponseOf(status, 'S')?.challenge),
+    };
+  }
+
+  private tanRequest(segmentType: string): SegmentSpec {
+    const medium = this.method.mediumRequirement === 'notAllowed' ? undefined : this.tanMedium;
+    return Segments.tanProcess4(
+      this.tanVersion,
+      segmentType,
+      medium === undefined ? undefined : this.protocol.parameters.tanMediumAsSent(medium),
+    );
+  }
+
+  /**
+   * Sends `segments`, with `tan` where they complete an approval, as the next message, and reads the bank's answer. The
+   * message counts once the bank has answered, whatever it answered.
+   *
+   * The bank assigns the dialog ID in its answer to the first message, so the answer to another user's first message
+   * passes for it (`ParameterStore.reportedUpdVersion`). Any other answer to another message fails with
+   * `FinTsProtocolError` before anything of it is kept: a relay or proxy that mixes up answers would hand the client
+   * another user's data, or a page of another query.
+   *
+   * The dialog ends on the client's side, without a dialog end, where it is over for the bank: after a return code that
+   * ends it, such as 9800, and after a rejected opening message (Formals C.1.2), or a broken connection (C.6).
+   *
+   * Only an answer that does not reject the whole message starts the idle time anew (`hasEnded`): a rejection may come
+   * from a bank that has ended the dialog without saying so.
+   */
+  private async sendSegments(segments: readonly SegmentSpec[], tan?: string): Promise<IncomingMessage3> {
+    const number = this.messageNumber;
+    let answer: Uint8Array;
+    try {
+      answer = await this.protocol.post({
+        dialogId: this.id,
+        number,
+        segments,
+        signing: this.anonymous
+          ? undefined
+          : { securityFunction: this.method.securityFunction, systemId: this.systemId },
+        tan,
+      });
+    } catch (error) {
+      if (error instanceof FinTsTransportError) this.discard();
+      throw error;
+    }
+    this.messageNumber++;
+    const response = parseBankData(() => IncomingMessage3.parse(answer));
+    const assigned = this.id === unassigned ? undefined : this.id;
+    if (!response.answers(number, assigned)) {
+      throw new FinTsProtocolError('The answer belongs to another message than the one sent');
+    }
+    if (assigned === undefined) this.id = response.dialogId ?? unassigned;
+    if (!response.messageRejected) this.lastAnswer = Date.now();
+    if (endsDialog(response.feedback) || (number === 1 && response.messageRejected)) this.discard();
+    return response;
+  }
+}
+
+/** The TAN part of `response` that answers TAN `process`. */
+function tanResponseOf(response: IncomingMessage3, process: string): TanResponse | undefined {
+  return response
+    .findAll('HITAN')
+    .map((s) => TanResponse.parse(s))
+    .find((t) => t.process === process);
+}