@coderoftime/fints 0.1.0 → 0.3.0

package/src/v3/bank-connection.ts

@@ -0,0 +1,126 @@
+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 posted since the last `abortRequestsAfter`. */
+  private requests = new AbortController();
+
+  /** How many requests are on their way. */
+  private onTheirWay = 0;
+
+  /** Starts the time of the requests posted after `abortRequestsAfter`, once none posted before is on its way. */
+  private startLaterRequests: (() => void) | undefined;
+
+  /** The timers of `abortRequestsAfter`, which `close` clears. */
+  private readonly deadlines: ReturnType<typeof setTimeout>[] = [];
+
+  /** 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.
+   *
+   * Once the time `abortRequestsAfter` gives is up, it fails at once, before anything reaches the transport
+   * (`checkSendable`), and a request on its way fails then without waiting for the transport, which may ignore the
+   * abort.
+   */
+  async post(body: Uint8Array, contentType: string): Promise<Uint8Array> {
+    this.checkSendable();
+    const signal = this.requests.signal;
+    let stopWaiting!: () => void;
+    const aborted = new Promise<never>((_, reject) => {
+      stopWaiting = () => {
+        reject(new FinTsTransportError('Request aborted'));
+      };
+    });
+    signal.addEventListener('abort', stopWaiting);
+    this.onTheirWay++;
+    try {
+      return await Promise.race([this.transport.post(new URL(this.href), body, contentType, signal), aborted]);
+    } catch (error) {
+      if (error instanceof FinTsTransportError) throw error;
+      throw new FinTsTransportError(failureMessage(error));
+    } finally {
+      signal.removeEventListener('abort', stopWaiting);
+      this.onTheirWay--;
+      if (this.onTheirWay === 0) this.startLaterRequests?.();
+    }
+  }
+
+  /**
+   * Throws the `FinTsTransportError` that `post` fails with once the time `abortRequestsAfter` gives is up; a caller
+   * checks it before it reports a message as outgoing, since such a message never goes out.
+   */
+  checkSendable(): void {
+    if (this.requests.signal.aborted) throw new FinTsTransportError('Request aborted');
+  }
+
+  /** 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());
+  }
+
+  /**
+   * Gives the requests on their way `graceMs` to finish, and aborts them then. Those posted later, such as the dialog
+   * ends of a closing client, have as long again from the moment the earlier ones are over or aborted, and are aborted
+   * in turn once that time is up, as is any posted after it: a bank that has stopped answering would hold them up to
+   * the transport's timeout.
+   */
+  abortRequestsAfter(graceMs: number): void {
+    const earlier = this.requests;
+    const later = new AbortController();
+    this.requests = later;
+    const afterGrace = (action: () => void): void => {
+      this.deadlines.push(setTimeout(action, graceMs));
+    };
+    this.startLaterRequests = () => {
+      this.startLaterRequests = undefined;
+      afterGrace(() => {
+        later.abort();
+      });
+    };
+    if (this.onTheirWay === 0) {
+      this.startLaterRequests();
+    } else {
+      afterGrace(() => {
+        earlier.abort();
+        this.startLaterRequests?.();
+      });
+    }
+  }
+
+  close(): void {
+    for (const deadline of this.deadlines) clearTimeout(deadline);
+    this.transport.close();
+  }
+}

package/src/v3/dialog.ts

@@ -1,14 +1,13 @@
 // Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
 
-import { FinTsProtocolError } from '../core/errors.js';
-import { FeedbackCodes, hasCode } from '../core/feedback.js';
-import { requireBankParameters } from '../session/parameter-data.js';
-import { PinTanDialog } from '../session/pin-tan-dialog.js';
-import type { Approval, StartWithOrder } from '../session/protocol.js';
+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 type { Bpd3 } from './parameters.js';
-import { Segments, TanResponse } from './segments.js';
+import { requireBankParameters } from './parameters.js';
+import type { FinTs3Protocol } from './protocol.js';
+import { noReference, 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. */
@@ -20,96 +19,121 @@ const firstScaVersion = 6;
 /** The first version of HKTAN that supports app approvals, with the status request (process S). */
 const firstDecoupledVersion = 7;
 
-/** How a message is signed: the security function of the TAN method and the customer system ID. */
-export interface Signing3 {
-  readonly securityFunction: string;
-  readonly systemId: string;
-}
-
 /**
- * What a dialog needs from the session: the parameter data received so far, the segments that open a dialog, and the
- * way to the bank. The `FinTs3Protocol` provides it, and keeps the login data and the PIN to itself.
+ * 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.
  */
-export interface FinTs3DialogHost {
-  /** The bank parameter data received so far, if any. */
-  readonly bankParameters: Bpd3 | undefined;
+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;
 
-  /** The customer system ID the bank assigned; `undefined` before the synchronization. */
-  readonly systemId: string | undefined;
+  /** Sends the TAN the user entered. */
+  readonly submitTan: (tan: string) => Promise<R>;
 
-  /** Identification (HKIDN) and processing preparation (HKVVB), which open every dialog. */
-  initSegments(systemId: string, anonymous?: boolean): SegmentSpec[];
+  /** Asks the bank whether the user has approved in the banking app. */
+  readonly checkStatus: () => Promise<R>;
 
   /**
-   * Sends `segments` as message `number` of the dialog `dialogId` and returns the bank's answer, not yet parsed.
-   *
-   * With `signing` the message is signed with the PIN and the `tan`, after `LoginGuard.check`; without, it goes out
-   * unsigned, as in an anonymous dialog.
+   * 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.
    */
-  post(message: {
-    dialogId: string;
-    number: number;
-    segments: readonly SegmentSpec[];
-    signing: Signing3 | undefined;
-    tan: string | undefined;
-  }): Promise<Uint8Array>;
+  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. */
-export class FinTs3Dialog extends PinTanDialog<IncomingMessage3, SegmentSpec> {
+/**
+ * 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 host: FinTs3DialogHost,
-    method: TanMethod,
-    tanMedium: string | undefined,
+    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,
   ) {
-    super(method, tanMedium);
-    this.systemId = anonymous ? unassigned : (host.systemId ?? unassigned);
+    this.systemId = anonymous ? unassigned : (protocol.parameters.systemId ?? unassigned);
   }
 
-  static signed(host: FinTs3DialogHost, method: TanMethod, tanMedium?: string): FinTs3Dialog {
-    return new FinTs3Dialog(host, method, tanMedium, false);
+  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(host: FinTs3DialogHost): FinTs3Dialog {
-    return new FinTs3Dialog(host, TanMethod.oneStep, undefined, true);
-  }
-
-  protected get bankParameters(): Bpd3 | undefined {
-    return this.host.bankParameters;
+  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.bankParameters?.tanVersion(this.method) ?? firstScaVersion;
+    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.host.initSegments(this.systemId),
+      ...this.protocol.initSegments(this.systemId),
       ...(this.isTwoStep ? [this.tanRequest('HKIDN')] : []),
       ...(synchronize ? [Segments.synchronization()] : []),
     ]);
   }
 
   /**
-   * Opens the dialog, asking strong authentication for `order` with a two-step method, then sends `order` in the next
-   * message.
+   * 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): StartWithOrder<IncomingMessage3> {
+  startWith(order: SegmentSpec): {
+    readonly login: () => Promise<IncomingMessage3>;
+    readonly order: () => Promise<IncomingMessage3>;
+  } {
     return {
       login: () =>
         this.sendSegments([
-          ...this.host.initSegments(this.systemId),
+          ...this.protocol.initSegments(this.systemId),
           ...(this.isTwoStep ? [this.tanRequest(order.type)] : []),
         ]),
       order: () => this.sendSegments([order]),
@@ -124,69 +148,139 @@ export class FinTs3Dialog extends PinTanDialog<IncomingMessage3, SegmentSpec> {
    */
   requestBankParameters(announceSca = false): Promise<IncomingMessage3> {
     return this.sendSegments([
-      ...this.host.initSegments(unassigned, true),
+      ...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.bankParameters).pinTan.requiresTan(order.type);
+    const needsTan =
+      this.isTwoStep && requireBankParameters(this.protocol.parameters.bankParameters).pinTan.requiresTan(order.type);
     return this.sendSegments([order, ...(needsTan ? [this.tanRequest(order.type)] : [])]);
   }
 
-  protected async sendEnd(): Promise<void> {
-    await this.sendSegments([Segments.dialogEnd(this.id)]);
+  /**
+   * 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;
+    }
   }
 
-  private tanRequest(segmentType: string): SegmentSpec {
-    return Segments.tanProcess4(this.tanVersion, segmentType, this.mediumName);
+  /** Forgets the dialog without contacting the bank, for example after the bank rejected the PIN. */
+  discard(): void {
+    this.ended = true;
   }
 
   /**
-   * The approval a HITAN segment of process 4 asks for, answered with HKTAN process 2 (TAN) or S (status).
+   * 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.
    *
-   * Throws `FinTsProtocolError` for 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).
+   * 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).
    */
-  protected approvalIn(response: IncomingMessage3): Approval<IncomingMessage3> | undefined {
+  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) return undefined;
-    if (hasCode(response.feedback, FeedbackCodes.decoupledPending) && this.tanVersion < firstDecoupledVersion) {
+    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 this.approvalOf(response, {
-      reference,
-      message: tan.challenge,
-      hhdUc: tan.hhdUc,
-      validUntil: tan.validUntil,
-      tanMediumName: tan.mediumName,
+    // The placeholder the dialog that looks up the TAN media sends, and the bank may echo, is no medium.
+    const medium = tan.mediumName ?? this.tanMedium;
+    return {
+      challenge: TanChallenge.create({
+        method: this.method,
+        reference,
+        message: tan.challenge,
+        hhdUc: tan.hhdUc,
+        isDecoupled: decoupled || this.method.decoupled,
+        validUntil: tan.validUntil,
+        tanMediumName: medium === noReference ? undefined : medium,
+      }),
       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) => tanResponseOf(status, 'S')?.challenge,
-    });
-  }
-
-  private sendSegments(segments: readonly SegmentSpec[], tan?: string): Promise<IncomingMessage3> {
-    return this.transmit(
-      (number) =>
-        this.host.post({
-          dialogId: this.id,
-          number,
-          segments,
-          signing: this.anonymous
-            ? undefined
-            : { securityFunction: this.method.securityFunction, systemId: this.systemId },
-          tan,
-        }),
-      (answer) => IncomingMessage3.parse(answer),
+      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.tanMediumToSend(medium),
     );
   }
 
-  /** The bank assigns the dialog ID in its answer to the first message. */
-  protected readDialogData(response: IncomingMessage3): void {
-    if (this.id === unassigned) this.id = response.dialogId ?? unassigned;
+  /**
+   * 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. Only the bank's dialog abort message may name the dialog or the
+   * message as unknown instead (`IncomingMessage3.aborts`), so that its text reaches the user.
+   *
+   * 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, a dialog abort message, a rejected opening message (Formals C.1.2), or a broken connection
+   * (C.6). A request that fails while the client is closing, as one it aborts (`FinTs3Protocol.beginClose`), leaves the
+   * dialog active instead, since the bank may have received it: its end follows under the next number. Not so where
+   * the request opened the dialog, whose ID only the answer tells.
+   *
+   * 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) {
+        if (this.protocol.isClosing && this.id !== unassigned) this.messageNumber++;
+        else this.discard();
+      }
+      throw error;
+    }
+    this.messageNumber++;
+    const response = parseBankData(() => IncomingMessage3.parse(answer));
+    const assigned = this.id === unassigned ? undefined : this.id;
+    const aborted = response.aborts(number, assigned);
+    if (!aborted && !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 (aborted || endsDialog(response.feedback) || (number === 1 && response.messageRejected)) this.discard();
+    return response;
   }
 }