@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/v3/message.ts

@@ -0,0 +1,321 @@
+// 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 type { BankResponse } from '../session/protocol.js';
+import { TanMethod } from '../tan/tan-models.js';
+import { base64Encode, BytesBuilder, latin1Decode, latin1Encode } 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, parseSegments, type Segment, SegmentSpec, type SegmentValue } 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, 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, 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 implements BankResponse {
+  /**
+   * 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[];
+
+  readonly messageRejected: boolean;
+
+  private constructor(
+    readonly segments: readonly Segment[],
+    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 a FinTS message, such as the HTML page of a proxy or a
+   * maintenance notice.
+   */
+  static parse(data: Uint8Array): IncomingMessage3 {
+    const outer = parseSegments(data);
+    if (outer[0]?.type !== 'HNHBK') throw new FormatError('Not a FinTS message: no message header');
+    const segments: Segment[] = [];
+    for (const s of outer) {
+      if (s.type === 'HNVSD') {
+        const payload = s.binary(1);
+        if (payload !== undefined) segments.push(...parseSegments(payload));
+      } else {
+        segments.push(s);
+      }
+    }
+    return new IncomingMessage3(segments, data.length);
+  }
+
+  static combine(first: IncomingMessage3, second: IncomingMessage3): IncomingMessage3 {
+    return new IncomingMessage3([...first.segments, ...second.segments], first.size + second.size);
+  }
+
+  get bankMessages(): BankMessage[] {
+    return this.findAll('HIKIM').map((m) => new BankMessage(m.text(1) ?? '', m.text(2) ?? ''));
+  }
+
+  get dialogId(): string | undefined {
+    return this.find('HNHBK')?.text(3);
+  }
+
+  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);
+  }
+}
+
+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.text(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 {
+    return decodeBase64Lines(latin1Decode(body));
+  } 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));
+}