@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/v3/syntax.ts

@@ -0,0 +1,369 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { BytesBuilder, latin1Decode, latin1Encode, utf8Encode } from '../util/bytes.js';
+import { FormatError } from '../util/errors.js';
+import { decodeBankText, isLatin1, tryParseInt } from '../util/text.js';
+
+// FinTS 3.0 syntax characters.
+const dataElementSeparator = 0x2b; // '+'
+const groupElementSeparator = 0x3a; // ':'
+const segmentTerminator = 0x27; // "'"
+const escapeCharacter = 0x3f; // '?'
+const binaryMarker = 0x40; // '@'
+
+function isSyntaxCharacter(byte: number): boolean {
+  return (
+    byte === dataElementSeparator ||
+    byte === groupElementSeparator ||
+    byte === segmentTerminator ||
+    byte === escapeCharacter ||
+    byte === binaryMarker
+  );
+}
+
+/**
+ * One (group) data element of a received segment: text or binary data, from `start` to `end` in `source`. A view or
+ * copy of its own would take more memory than most elements hold.
+ */
+export class DataElement {
+  private decoded: string | undefined;
+
+  constructor(
+    private readonly source: Uint8Array,
+    private readonly start: number,
+    private readonly end: number,
+    readonly isBinary: boolean,
+    /** Whether the text holds escape characters, which `bytes` leaves out. */
+    private readonly escaped = false,
+  ) {}
+
+  /** The binary data, or the text without escape characters. */
+  get bytes(): Uint8Array {
+    const bytes = this.source.subarray(this.start, this.end);
+    return this.escaped ? unescape(bytes) : bytes;
+  }
+
+  get isEmpty(): boolean {
+    return !this.isBinary && this.start === this.end;
+  }
+
+  get text(): string {
+    this.decoded ??= decodeBankText(this.bytes);
+    return this.decoded;
+  }
+}
+
+/**
+ * A received segment: data elements separated by `+`, each a group of elements separated by `:`.
+ *
+ * Index 0 is the segment header (type, number, version, reference); the data elements follow from index 1.
+ */
+export class Segment {
+  constructor(
+    readonly elements: readonly (readonly DataElement[])[],
+    /** The bytes the segment was read from: `start` to `end` in `source`, terminator included. */
+    private readonly source: Uint8Array,
+    private readonly start: number,
+    private readonly end: number,
+  ) {}
+
+  get type(): string {
+    return this.text(0)?.trim() ?? '';
+  }
+
+  get version(): number {
+    return this.integer(0, 2) ?? 0;
+  }
+
+  get length(): number {
+    return this.elements.length;
+  }
+
+  group(index: number): readonly DataElement[] {
+    return this.elements[index] ?? [];
+  }
+
+  element(index: number, sub = 0): DataElement | undefined {
+    return this.group(index)[sub];
+  }
+
+  text(index: number, sub = 0): string | undefined {
+    const e = this.element(index, sub);
+    if (e === undefined || e.isEmpty) return undefined;
+    return e.text;
+  }
+
+  /** The binary data at `index`; `undefined` for an element that holds text. */
+  binary(index: number, sub = 0): Uint8Array | undefined {
+    const e = this.element(index, sub);
+    return e?.isBinary === true ? e.bytes : undefined;
+  }
+
+  /**
+   * The element at `index` as the bank sent it, for a value the client sends back, such as the dialog ID: untrimmed,
+   * and one character per byte (ISO 8859-1, the FinTS 3.0 character set), so that `Verbatim` gives the bank back the
+   * very bytes it sent, in whatever encoding. `undefined` for an empty element.
+   */
+  verbatim(index: number, sub = 0): string | undefined {
+    const e = this.element(index, sub);
+    if (e === undefined || e.isEmpty) return undefined;
+    return latin1Decode(e.bytes);
+  }
+
+  integer(index: number, sub = 0): number | undefined {
+    return tryParseInt(this.text(index, sub)?.trim());
+  }
+
+  /** The texts of the group at `index`; `undefined` for empty elements. */
+  texts(index: number): (string | undefined)[] {
+    return this.group(index).map((e) => (e.isEmpty ? undefined : e.text));
+  }
+
+  /** The bytes the segment was read from, as the bank sent them, terminator included. */
+  encode(): Uint8Array {
+    return this.source.subarray(this.start, this.end);
+  }
+}
+
+function writeEscaped(out: BytesBuilder, bytes: Uint8Array): void {
+  const escaped: number[] = [];
+  for (const b of bytes) {
+    if (isSyntaxCharacter(b)) escaped.push(escapeCharacter);
+    escaped.push(b);
+  }
+  out.add(escaped);
+}
+
+function writeBinary(out: BytesBuilder, bytes: Uint8Array): void {
+  out.add(latin1Encode(`@${bytes.length}@`));
+  out.add(bytes);
+}
+
+/**
+ * Encodes `value` in ISO 8859-1, the FinTS 3.0 character set, or in UTF-8 where it does not fit: such text can only
+ * come from a bank that sends UTF-8, such as a TAN medium named `Max’s iPhone`. `FinTsConfig` checks the login data for
+ * ISO 8859-1 up front, and the client the PIN and the TAN.
+ *
+ * @internal Exported for the tests.
+ */
+export function encodeText(value: string): Uint8Array {
+  return isLatin1(value) ? latin1Encode(value) : utf8Encode(value);
+}
+
+/**
+ * The data elements one message may hold, segment headers and group elements included: several times what the
+ * parameter data of a user with hundreds of accounts take, and few enough that a hostile message cannot exhaust the
+ * memory, at about `dataElementMemory` bytes each.
+ */
+export const maxDataElements = 200_000;
+
+/**
+ * The memory a data element of a received message takes, in bytes, with its share of the segment and of a return code:
+ * about this much in V8, however few bytes of the message it is made of.
+ */
+export const dataElementMemory = 256;
+
+/** Every empty data element of a received segment; it has no bytes to change. */
+const emptyElement = new DataElement(new Uint8Array(0), 0, 0, false);
+
+function isSeparator(byte: number | undefined): boolean {
+  return byte === dataElementSeparator || byte === groupElementSeparator || byte === segmentTerminator;
+}
+
+/** Line breaks and spaces between segments are padding, not content. */
+function isPadding(byte: number): boolean {
+  return byte === 0x0a || byte === 0x0d || byte === 0x20;
+}
+
+function isDigit(byte: number | undefined): boolean {
+  return byte !== undefined && byte >= 0x30 && byte <= 0x39;
+}
+
+/**
+ * Splits a FinTS 3.0 message into segments, resolving escapes and binary data (`@length@bytes`).
+ *
+ * The elements share the memory of `data`. Throws `FormatError` for anything a complete message cannot hold: a
+ * malformed binary length, binary data beyond the end of `data` or not followed by a separator, a last segment without
+ * terminator, and more elements than `budget` has left, which parses of the same message share.
+ */
+export function parseSegments(data: Uint8Array, budget = { elements: maxDataElements }): Segment[] {
+  const segments: Segment[] = [];
+  // Created with their first element: an array that starts empty reserves room for more than most of them hold.
+  let elements: DataElement[][] | undefined;
+  let group: DataElement[] | undefined;
+  let segmentStart = 0;
+  let i = 0;
+
+  const readBinary = (): DataElement => {
+    let end = i + 1;
+    let length = 0;
+    while (isDigit(data[end])) {
+      length = length * 10 + data[end++]! - 0x30;
+      if (length > data.length) throw new FormatError('Binary data beyond the end of the message');
+    }
+    if (end === i + 1 || data[end] !== binaryMarker) throw new FormatError('Malformed binary length');
+    const start = end + 1;
+    if (length > data.length - start) throw new FormatError('Binary data beyond the end of the message');
+    i = start + length;
+    if (i < data.length && !isSeparator(data[i])) throw new FormatError('Binary data not followed by a separator');
+    return new DataElement(data, start, i, true);
+  };
+
+  const readText = (): DataElement => {
+    const start = i;
+    let escaped = false;
+    while (i < data.length && !isSeparator(data[i])) {
+      if (data[i] === escapeCharacter) {
+        escaped = true;
+        i++;
+      }
+      i++;
+    }
+    if (i > data.length) throw new FormatError('Escape character at the end of the message');
+    return i === start ? emptyElement : new DataElement(data, start, i, false, escaped);
+  };
+
+  while (i < data.length) {
+    if (elements === undefined && group === undefined && isPadding(data[i]!)) {
+      i++;
+      continue;
+    }
+    if (--budget.elements < 0) throw new FormatError('Too many data elements');
+    if (elements === undefined && group === undefined) segmentStart = i;
+    const element = data[i] === binaryMarker ? readBinary() : readText();
+    if (group === undefined) group = [element];
+    else group.push(element);
+    const separator = data[i++];
+    if (separator === groupElementSeparator) continue;
+    if (elements === undefined) elements = [group];
+    else elements.push(group);
+    group = undefined;
+    if (separator === segmentTerminator) {
+      const segment = new Segment(elements, data, segmentStart, i);
+      // Skip empty segments, such as a stray double terminator.
+      if (segment.type !== '') segments.push(segment);
+      elements = undefined;
+    }
+  }
+  if (elements !== undefined || group !== undefined) throw new FormatError('Segment without terminator');
+  return segments;
+}
+
+/** `text` without the escape characters in front of syntax characters. */
+function unescape(text: Uint8Array): Uint8Array {
+  const out = new Uint8Array(text.length);
+  let o = 0;
+  for (let j = 0; j < text.length; j++) {
+    if (text[j] === escapeCharacter) j++;
+    out[o++] = text[j]!;
+  }
+  return out.subarray(0, o);
+}
+
+/** Binary data in a segment to send, written as `@length@bytes`. */
+export class Binary {
+  constructor(readonly bytes: Uint8Array) {}
+}
+
+/**
+ * A value the bank issued, such as the dialog ID, to send back as `Segment.verbatim` reads it: escaped, but not
+ * trimmed, so that the bank gets back the very bytes it sent. Text from elsewhere, such as a TAN medium name the app
+ * passes, goes out as `encodeText` encodes it.
+ */
+export class Verbatim {
+  constructor(readonly text: string) {}
+
+  /** `text` as a `Verbatim`; `undefined` stays empty. */
+  static of(text: string | undefined): Verbatim | undefined {
+    return text === undefined ? undefined : new Verbatim(text);
+  }
+}
+
+/** A value of a segment to send; see `SegmentSpec`. */
+export type SegmentValue = string | number | boolean | Binary | Verbatim | null | undefined | readonly SegmentValue[];
+
+/**
+ * A segment to send.
+ *
+ * `elements` holds the data elements after the header: `null` or `undefined` for an empty element, an array for a data
+ * element group, a boolean for `J`/`N`, `Binary` for binary data, `Verbatim` for a value the bank issued, and anything
+ * else as its text, without leading and trailing blanks. Trailing empty elements are left out, as the specification
+ * asks.
+ */
+export class SegmentSpec {
+  constructor(
+    readonly type: string,
+    readonly version: number,
+    readonly elements: readonly SegmentValue[],
+    /** The number of the segment an answer refers to (Bezugssegment); requests have none. */
+    readonly reference?: number,
+  ) {}
+
+  /**
+   * A segment given by the field numbers of its data elements, as in the specification (1 is the first data element
+   * after the header); missing numbers stay empty.
+   */
+  static numbered(type: string, version: number, fields: Readonly<Record<number, SegmentValue>>): SegmentSpec {
+    const count = Math.max(0, ...Object.keys(fields).map(Number));
+    const elements: SegmentValue[] = [];
+    for (let number = 1; number <= count; number++) elements.push(fields[number]);
+    return new SegmentSpec(type, version, elements);
+  }
+
+  /** Encodes the segment with `number`. */
+  build(number: number): Uint8Array {
+    const out = new BytesBuilder();
+    out.add(
+      encodeText(`${this.type}:${number}:${this.version}${this.reference === undefined ? '' : `:${this.reference}`}`),
+    );
+    const encoded = this.elements.map(encodeGroup);
+    while (encoded.length > 0 && encoded.at(-1)!.length === 0) encoded.pop();
+    for (const e of encoded) {
+      out.addByte(dataElementSeparator);
+      out.add(e);
+    }
+    out.addByte(segmentTerminator);
+    return out.takeBytes();
+  }
+}
+
+/** A single value of a segment to send, not a group. */
+type SingleValue = Exclude<SegmentValue, readonly SegmentValue[]>;
+
+function isGroup(value: SegmentValue): value is readonly SegmentValue[] {
+  return Array.isArray(value);
+}
+
+function encodeGroup(value: SegmentValue): Uint8Array {
+  const parts: Uint8Array[] = [];
+  const flatten = (v: SegmentValue): void => {
+    if (isGroup(v)) v.forEach(flatten);
+    else parts.push(encodeValue(v));
+  };
+  flatten(value);
+  while (parts.length > 0 && parts.at(-1)!.length === 0) parts.pop();
+  const out = new BytesBuilder();
+  parts.forEach((part, i) => {
+    if (i > 0) out.addByte(groupElementSeparator);
+    out.add(part);
+  });
+  return out.takeBytes();
+}
+
+function encodeValue(value: SingleValue): Uint8Array {
+  const out = new BytesBuilder();
+  if (value === null || value === undefined) {
+    // Empty.
+  } else if (value instanceof Binary) {
+    writeBinary(out, value.bytes);
+  } else if (value instanceof Verbatim) {
+    writeEscaped(out, encodeText(value.text));
+  } else if (typeof value === 'boolean') {
+    out.addByte(value ? 0x4a : 0x4e); // 'J' or 'N'
+  } else {
+    // All but binary data go without leading and trailing blanks (Formals B.4.1). Encode first, then escape the bytes,
+    // so that nothing unescaped slips into the syntax.
+    writeEscaped(out, encodeText(String(value).trim()));
+  }
+  return out.takeBytes();
+}