@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/v3/message.ts

@@ -0,0 +1,373 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { BankMessage } from '../core/bank-info.js';
+import { FinTsFeedback } from '../core/feedback.js';
+import { TanMethod } from '../tan/tan-models.js';
+import { base64Encode, BytesBuilder, latin1Encode, utf8Decode } from '../util/bytes.js';
+import { formatFintsDate, formatFintsTime } from '../util/dates.js';
+import { FormatError } from '../util/errors.js';
+import { decodeBankText, decodeBase64Lines } from '../util/text.js';
+import {
+  Binary,
+  dataElementMemory,
+  maxDataElements,
+  parseSegments,
+  type Segment,
+  SegmentSpec,
+  type SegmentValue,
+  Verbatim,
+} from './syntax.js';
+
+/** Signature data of a PIN/TAN message. */
+export interface PinTanCredentials {
+  readonly countryCode: string;
+  readonly bankCode: string;
+  readonly userId: string;
+  readonly systemId: string;
+  readonly pin: string;
+  readonly securityFunction: string;
+}
+
+function isTwoStep(c: PinTanCredentials): boolean {
+  return c.securityFunction !== TanMethod.oneStep.securityFunction;
+}
+
+// Codes of the PIN/TAN security envelope, from the FinTS security specification. PIN/TAN neither hashes, signs nor
+// encrypts, but the envelope must name the algorithms of the chip card procedures all the same.
+
+/** Area the signature covers: signature head and data (SHM). */
+const signedArea = 1;
+
+/** Role of the security supplier: issuer (ISS). */
+const issuer = 1;
+
+/** Security identification: message sender (MS), empty CID, then the customer system ID. */
+function sender(systemId: string): SegmentValue {
+  return [1, null, new Verbatim(systemId)];
+}
+
+/** Security reference number, the same in every message. */
+const securityReference = 1;
+
+/** Security time stamp (STS). */
+function timestamp(time: Date): SegmentValue {
+  return [1, formatFintsDate(time), formatFintsTime(time)];
+}
+
+/** Hash algorithm: owner hashing (OHA), mutually agreed algorithm (ZZZ), initialisation value in clear (IVC). */
+const hashAlgorithm = [1, 999, 1];
+
+/** Signature algorithm: owner signing (OSG), RSA, ISO 9796-1. */
+const signatureAlgorithm = [6, 10, 16];
+
+/** Security function of the encryption head: plain text, since PIN/TAN does not encrypt. */
+const plainText = 998;
+
+/**
+ * Encryption algorithm: owner symmetric (OSY), CBC, 2-key triple DES, a key of zeros, symmetric key (KYE),
+ * initialisation value in clear (IVC).
+ */
+const encryptionAlgorithm = [2, 2, 13, new Binary(new Uint8Array(8)), 5, 1];
+
+/** Compression function: none. */
+const noCompression = 0;
+
+/** Key name: bank, user, key type `S` (signature) or `V` (encryption), key number and version 0. */
+function keyName(c: PinTanCredentials, keyType: string): SegmentValue {
+  return [c.countryCode, c.bankCode, c.userId, keyType, 0, 0];
+}
+
+/** A random integer from 0 below `bound`, from a cryptographically secure source. */
+function secureRandom(bound: number): number {
+  const values = new Uint32Array(1);
+  crypto.getRandomValues(values);
+  return values[0]! % bound;
+}
+
+/** A random 14-digit reference that ties the signature head (HNSHK) to the signature end (HNSHA). */
+function securityControlReference(): string {
+  return `${secureRandom(900000000) + 100000000}${secureRandom(100000).toString().padStart(5, '0')}`;
+}
+
+/** A message to send, and the same message with PIN and TAN masked for logging. */
+export class OutgoingMessage {
+  constructor(
+    readonly bytes: Uint8Array,
+    /** The parts of the masked message, each decoded on its own as the bank's text is. */
+    private readonly maskedParts: readonly Uint8Array[],
+  ) {}
+
+  /** The message with PIN and TAN masked; decoded only when a logger asks for it. */
+  get masked(): string {
+    return this.maskedParts.map(decodeBankText).join('');
+  }
+}
+
+/** The segments between header and trailer, as sent and with PIN and TAN masked, and the number for the trailer. */
+interface Body {
+  readonly bytes: Uint8Array;
+  readonly masked: readonly Uint8Array[];
+  readonly nextNumber: number;
+}
+
+/**
+ * Builds a message: header (HNHBK), the `segments`, trailer (HNHBS).
+ *
+ * With `security` the segments are signed with PIN and optional `tan` (HNSHK … HNSHA) and wrapped in the encryption
+ * envelope (HNVSK, HNVSD) that PIN/TAN uses without actual encryption.
+ *
+ * The masked message states the sizes of its masked content, so that the log does not tell how long PIN and TAN are.
+ */
+export function buildMessage(parts: {
+  dialogId: string;
+  messageNumber: number;
+  segments: readonly SegmentSpec[];
+  security?: PinTanCredentials | undefined;
+  tan?: string | undefined;
+  now?: Date;
+}): OutgoingMessage {
+  const body =
+    parts.security === undefined
+      ? plainBody(parts.segments)
+      : signedBody(parts.segments, parts.security, parts.tan, parts.now ?? new Date());
+  const trailer = new SegmentSpec('HNHBS', 1, [parts.messageNumber]).build(body.nextNumber);
+  // The header states the size of the whole message, itself included; its own size does not depend on it.
+  const header = (size: number): Uint8Array =>
+    new SegmentSpec('HNHBK', 3, [
+      size.toString().padStart(12, '0'),
+      300,
+      new Verbatim(parts.dialogId),
+      parts.messageNumber,
+    ]).build(1);
+  const sizeOf = (sections: readonly Uint8Array[]): number => header(0).length + lengthOf(sections) + trailer.length;
+  const result = new BytesBuilder();
+  result.add(header(sizeOf([body.bytes])));
+  result.add(body.bytes);
+  result.add(trailer);
+  return new OutgoingMessage(result.takeBytes(), [header(sizeOf(body.masked)), ...body.masked, trailer]);
+}
+
+/** The number of bytes in `parts` together. */
+function lengthOf(parts: readonly Uint8Array[]): number {
+  return parts.reduce((sum, part) => sum + part.length, 0);
+}
+
+/** The segments of a message without security, as the anonymous dialog sends them. */
+function plainBody(segments: readonly SegmentSpec[]): Body {
+  const built = segments.map((segment, i) => segment.build(i + 2));
+  const bytes = new BytesBuilder();
+  built.forEach((b) => {
+    bytes.add(b);
+  });
+  return { bytes: bytes.takeBytes(), masked: built, nextNumber: built.length + 2 };
+}
+
+/** The segments signed with PIN and optional `tan`, inside the encryption envelope. */
+function signedBody(
+  segments: readonly SegmentSpec[],
+  security: PinTanCredentials,
+  tan: string | undefined,
+  time: Date,
+): Body {
+  const profile = ['PIN', isTwoStep(security) ? 2 : 1];
+  const controlReference = securityControlReference();
+  const inner = new BytesBuilder();
+  const maskedInner: Uint8Array[] = [];
+  const addInner = (built: Uint8Array, masked?: Uint8Array): void => {
+    inner.add(built);
+    maskedInner.push(masked ?? built);
+  };
+
+  addInner(
+    new SegmentSpec('HNSHK', 4, [
+      profile,
+      security.securityFunction,
+      controlReference,
+      signedArea,
+      issuer,
+      sender(security.systemId),
+      securityReference,
+      timestamp(time),
+      hashAlgorithm,
+      signatureAlgorithm,
+      keyName(security, 'S'),
+    ]).build(2),
+  );
+  let number = 3;
+  for (const segment of segments) addInner(segment.build(number++));
+  const signatureEnd = (pin: string, tanValue: string | undefined): SegmentSpec =>
+    new SegmentSpec('HNSHA', 2, [controlReference, null, [pin, tanValue]]);
+  addInner(
+    signatureEnd(security.pin, tan).build(number),
+    signatureEnd('***', tan === undefined ? undefined : '***').build(number),
+  );
+
+  const innerBytes = inner.takeBytes();
+  const encryptionHead = new SegmentSpec('HNVSK', 3, [
+    profile,
+    plainText,
+    issuer,
+    sender(security.systemId),
+    timestamp(time),
+    encryptionAlgorithm,
+    keyName(security, 'V'),
+    noCompression,
+  ]).build(998);
+  const bytes = new BytesBuilder();
+  bytes.add(encryptionHead);
+  bytes.add(new SegmentSpec('HNVSD', 1, [new Binary(innerBytes)]).build(999));
+  const masked = [
+    encryptionHead,
+    latin1Encode(`HNVSD:999:1+@${lengthOf(maskedInner)}@`),
+    ...maskedInner,
+    latin1Encode("'"),
+  ];
+  return { bytes: bytes.takeBytes(), masked, nextNumber: number + 1 };
+}
+
+/** A received message, with the segments of the encryption envelope unpacked. */
+export class IncomingMessage3 {
+  /**
+   * Return codes for the whole message (HIRMG), then for single request segments (HIRMS).
+   *
+   * The segment a HIRMS refers to is not kept: each message carries one order, and the answer that completes an
+   * approval reports on the order of an earlier message (PIN/TAN B.4.2.1).
+   */
+  readonly feedback: readonly FinTsFeedback[];
+
+  /** Whether the bank rejected the message as a whole (an error in HIRMG), rather than single orders in it. */
+  readonly messageRejected: boolean;
+
+  private constructor(
+    readonly segments: readonly Segment[],
+    /** The memory the message holds, in bytes: its length, and what its parts take beyond that. */
+    readonly size: number,
+  ) {
+    this.feedback = Object.freeze(
+      ['HIRMG', 'HIRMS'].flatMap((type) => segments.filter((s) => s.type === type).flatMap(feedbackOf)),
+    );
+    this.messageRejected = segments
+      .filter((s) => s.type === 'HIRMG')
+      .flatMap(feedbackOf)
+      .some((f) => f.isError);
+  }
+
+  /**
+   * Parses a message; throws `FormatError` if `data` is not one complete FinTS message, such as the HTML page of a
+   * proxy, a maintenance notice, a message cut short, which lacks the message trailer (HNHBS) at its end, or two
+   * messages run together, whose second would pass for part of the first.
+   *
+   * Its `size` counts the memory of its data elements along with its bytes, since a message of many short elements
+   * takes far more memory than bytes.
+   */
+  static parse(data: Uint8Array): IncomingMessage3 {
+    const budget = { elements: maxDataElements };
+    const outer = parseSegments(data, budget);
+    if (outer[0]?.type !== 'HNHBK') throw new FormatError('Not a FinTS message: no message header');
+    if (outer.at(-1)?.type !== 'HNHBS') throw new FormatError('Incomplete FinTS message: no message trailer');
+    if (outer.filter((s) => s.type === 'HNHBK' || s.type === 'HNHBS').length > 2) {
+      throw new FormatError('More than one FinTS message');
+    }
+    const segments: Segment[] = [];
+    for (const s of outer) {
+      if (s.type !== 'HNVSD') {
+        segments.push(s);
+        continue;
+      }
+      const payload = s.binary(1);
+      if (payload === undefined) throw new FormatError('Encrypted data (HNVSD) without binary data');
+      for (const inner of parseSegments(payload, budget)) segments.push(inner);
+    }
+    return new IncomingMessage3(segments, data.length + (maxDataElements - budget.elements) * dataElementMemory);
+  }
+
+  static combine(first: IncomingMessage3, second: IncomingMessage3): IncomingMessage3 {
+    return new IncomingMessage3([...first.segments, ...second.segments], first.size + second.size);
+  }
+
+  /** Free-text messages the bank addresses to the user. */
+  get bankMessages(): BankMessage[] {
+    return this.findAll('HIKIM').map((m) => new BankMessage(m.text(1) ?? '', m.text(2) ?? ''));
+  }
+
+  /** The dialog ID the bank assigned, as `Segment.verbatim` reads it, to send back byte for byte. */
+  get dialogId(): string | undefined {
+    return this.find('HNHBK')?.verbatim(3);
+  }
+
+  /**
+   * Whether the message answers message `number` of the dialog `dialogId`: header and trailer carry that number, and the
+   * header names that message where it names the message it refers to (Bezugsnachricht). The dialog ID counts only once
+   * the bank has assigned one; before, `dialogId` is `undefined`, since every first message goes out under the same.
+   */
+  answers(number: number, dialogId: string | undefined): boolean {
+    const header = this.find('HNHBK');
+    // The trailer comes last, after the segments of the encryption envelope, which might hold one of their own.
+    const trailer = this.segments.at(-1);
+    if (header === undefined || trailer?.type !== 'HNHBS') return false;
+    const inDialog = (id: string | undefined): boolean => dialogId === undefined || id === dialogId;
+    const namesReference = header.group(5).some((e) => !e.isEmpty);
+    return (
+      header.integer(4) === number &&
+      trailer.integer(1) === number &&
+      inDialog(header.verbatim(3)) &&
+      (!namesReference || (header.integer(5, 1) === number && inDialog(header.verbatim(5, 0))))
+    );
+  }
+
+  find(type: string): Segment | undefined {
+    return this.segments.find((s) => s.type === type);
+  }
+
+  findAll(type: string): Segment[] {
+    return this.segments.filter((s) => s.type === type);
+  }
+}
+
+/**
+ * The return codes of `s`. Their parameters are values the client or the app sends back, such as the position to
+ * continue at or new login data, so they are read as `Segment.verbatim` reads them.
+ */
+function feedbackOf(s: Segment): FinTsFeedback[] {
+  const feedback: FinTsFeedback[] = [];
+  for (let i = 1; i < s.length; i++) {
+    const code = s.text(i);
+    if (code === undefined) continue;
+    const parameters: string[] = [];
+    // Empty parameters stay, as empty text, so that each keeps its position.
+    for (let j = 3; j < s.group(i).length; j++) parameters.push(s.verbatim(i, j) ?? '');
+    feedback.push(new FinTsFeedback({ code, reference: s.text(i, 1), text: s.text(i, 2) ?? '', parameters }));
+  }
+  return feedback;
+}
+
+/**
+ * Unpacks the transport encoding: PIN/TAN servers answer in base64, a few with the raw message.
+ *
+ * Returns anything else unchanged, for `IncomingMessage3.parse` to reject.
+ */
+export function decodeTransport(body: Uint8Array): Uint8Array {
+  if (startsWithMessageHeader(body)) return body;
+  try {
+    // Base64 is ASCII, which UTF-8 decodes natively; anything else is no base64 either way.
+    return decodeBase64Lines(utf8Decode(body, true));
+  } catch (error) {
+    if (error instanceof FormatError) return body;
+    throw error;
+  }
+}
+
+const messageHeader = latin1Encode('HNHBK');
+const whitespaceBytes = new Set([0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x20]);
+
+/** Whether `body` is a raw message: its header segment comes first, after any white space. */
+function startsWithMessageHeader(body: Uint8Array): boolean {
+  let start = 0;
+  while (start < body.length && whitespaceBytes.has(body[start]!)) start++;
+  if (body.length - start < messageHeader.length) return false;
+  return messageHeader.every((byte, i) => body[start + i] === byte);
+}
+
+export function encodeTransport(message: Uint8Array): Uint8Array {
+  return latin1Encode(base64Encode(message));
+}

package/src/v3/parameter-store.ts

@@ -0,0 +1,160 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { FinTsConfig } from '../core/config.js';
+import { FormatError } from '../util/errors.js';
+import { readOptionalBoolean, readOptionalObject, readOptionalString, type JsonObject } from '../util/json.js';
+import type { IncomingMessage3 } from './message.js';
+import { Bpd3, decodeSegments, Upd3 } from './parameters.js';
+
+/**
+ * The parameter data and IDs the bank sends the user `config` names, which the messages and business transactions
+ * take, and which the saved state keeps: the bank and user parameter data, the customer system ID, and the names of
+ * the TAN media as the bank sent them.
+ */
+export class ParameterStore {
+  private systemIdValue: string | undefined;
+  private bpd: Bpd3 | undefined;
+
+  /**
+   * Whether the bank parameter data came from the anonymous dialog. They serve until those of a dialog signed with the
+   * PIN come: the bank may send a user other ones (PIN/TAN B.4.3.1), and the anonymous dialog may have had to do
+   * without the announcement of strong customer authentication. So signed dialogs report version 0 for them, which has
+   * the bank send its parameter data anew.
+   */
+  private bpdAnonymous = false;
+  private upd: Upd3 | undefined;
+
+  /**
+   * The names of the TAN media in the bank's last list whose text differs from what the bank sent, by their text, as
+   * `parseTanMedia` notes them. Saved with the state, as the medium in use is.
+   */
+  private tanMediumNames = new Map<string, string>();
+
+  constructor(readonly config: FinTsConfig) {}
+
+  /** The bank parameter data received so far, if any. */
+  get bankParameters(): Bpd3 | undefined {
+    return this.bpd;
+  }
+
+  /** The user parameter data received so far, if any. */
+  get userParameters(): Upd3 | undefined {
+    return this.upd;
+  }
+
+  /**
+   * The customer system ID the bank assigned in the synchronization, as `Segment.verbatim` reads it; `undefined`
+   * before. No dialog signed with the PIN starts without it.
+   */
+  get systemId(): string | undefined {
+    return this.systemIdValue;
+  }
+
+  /** The version of the bank parameter data a dialog reports: 0 where there are none, or only the anonymous dialog's. */
+  get reportedBpdVersion(): number {
+    return this.bpd === undefined || this.bpdAnonymous ? 0 : this.bpd.version;
+  }
+
+  /**
+   * The version of the user parameter data a signed dialog reports: 0 where there are none, or where they name another
+   * user ID than the one logging in, so that the bank sends the user's anew. They may be another user's, as where a
+   * relay mixed up the answers to the synchronizations of two users and the bank takes the other user's customer system
+   * ID. A bank that names the user by another ID than the login's, such as for an alias, only sends its user parameter
+   * data at every login.
+   */
+  get reportedUpdVersion(): number {
+    const upd = this.upd;
+    return upd !== undefined && upd.userId === this.config.userId ? upd.version : 0;
+  }
+
+  /**
+   * Drops the customer system ID the bank no longer accepts, so that a synchronization is required again, and with it
+   * the user parameter data, which the next login delivers anew: what came along with an ID the bank does not know may
+   * not be the user's either (`reportedUpdVersion`). Returns whether there was an ID.
+   */
+  forgetSystemId(): boolean {
+    const had = this.systemIdValue !== undefined;
+    this.systemIdValue = undefined;
+    this.upd = undefined;
+    return had;
+  }
+
+  /**
+   * Keeps the parameter data and IDs in `response`, an answer to the opening of a signed dialog: the login, which may be
+   * a synchronization, or its approval. The bank sends them there (Formals C.3.1); taken from the answer to an order,
+   * the parameter data a bank repeats there in part would replace the complete ones.
+   */
+  keep(response: IncomingMessage3): void {
+    this.keepBankParameters(response, false);
+    this.upd = Upd3.fromSegments(response.segments, this.config.bankCode, this.config.countryCode) ?? this.upd;
+    this.systemIdValue = response.find('HISYN')?.verbatim(1) ?? this.systemIdValue;
+  }
+
+  /**
+   * Keeps the bank parameter data in `response`, the answer of an anonymous dialog, where there are none from a dialog
+   * signed with the PIN: until those come, the dialogs signed with the PIN have the bank send its parameter data anew,
+   * since it may send a user other ones (PIN/TAN B.4.3.1). Keeps nothing that belongs to a user.
+   */
+  keepAnonymous(response: IncomingMessage3): void {
+    if (this.bpd === undefined || this.bpdAnonymous) this.keepBankParameters(response, true);
+  }
+
+  private keepBankParameters(response: IncomingMessage3, anonymous: boolean): void {
+    const bpd = Bpd3.fromSegments(response.segments, this.config.bankCode);
+    if (bpd === undefined) return;
+    this.bpd = bpd;
+    this.bpdAnonymous = anonymous;
+  }
+
+  /** Keeps `names`, the names of the bank's latest list of TAN media as `parseTanMedia` notes them. */
+  keepTanMediumNames(names: Map<string, string>): void {
+    this.tanMediumNames = names;
+  }
+
+  /** The TAN medium `name` as the bank sent it in its list of TAN media; `name` itself for one it did not list. */
+  tanMediumAsSent(name: string): string {
+    return this.tanMediumNames.get(name) ?? name;
+  }
+
+  /** The parameter data and IDs as JSON data, for the client's saved state. */
+  saveState(): JsonObject {
+    return {
+      systemId: this.systemIdValue ?? null,
+      bpd: this.bpd?.encoded ?? null,
+      bpdAnonymous: this.bpdAnonymous,
+      upd: this.upd?.encoded ?? null,
+      tanMediumNames: Object.fromEntries(this.tanMediumNames),
+    };
+  }
+
+  /** Restores what `saveState` saved; throws if `saved` is damaged, leaving the store unchanged. */
+  restoreState(saved: JsonObject): void {
+    const bpd = readOptionalString(saved, 'bpd');
+    const upd = readOptionalString(saved, 'upd');
+    const restoredSystemId = readOptionalString(saved, 'systemId');
+    // A state of the Dart package or an earlier version does not tell, so its parameter data are fetched anew.
+    const restoredBpdAnonymous = readOptionalBoolean(saved, 'bpdAnonymous') ?? true;
+    const restoredBpd = bpd === undefined ? undefined : Bpd3.fromSegments(decodeSegments(bpd), this.config.bankCode);
+    const restoredUpd =
+      upd === undefined
+        ? undefined
+        : Upd3.fromSegments(decodeSegments(upd), this.config.bankCode, this.config.countryCode);
+    const restoredNames = readTanMediumNames(saved);
+    this.systemIdValue = restoredSystemId;
+    this.bpd = restoredBpd;
+    this.bpdAnonymous = restoredBpdAnonymous;
+    this.upd = restoredUpd;
+    this.tanMediumNames = restoredNames;
+  }
+}
+
+/** The TAN medium names `saveState` saved; none in a state of the Dart package or an earlier version. */
+function readTanMediumNames(saved: JsonObject): Map<string, string> {
+  const names = readOptionalObject(saved, 'tanMediumNames') ?? {};
+  return new Map(
+    Object.entries(names).map(([name, asSent]) => {
+      if (typeof asSent !== 'string') throw new FormatError('Saved state: a TAN medium name is not a string');
+      return [name, asSent];
+    }),
+  );
+}