@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/v3/syntax.ts

@@ -0,0 +1,307 @@
+// 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, 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: unescaped text bytes or binary data. */
+export class DataElement {
+  private decoded: string | undefined;
+
+  constructor(
+    readonly bytes: Uint8Array,
+    readonly isBinary: boolean,
+  ) {}
+
+  get isEmpty(): boolean {
+    return !this.isBinary && this.bytes.length === 0;
+  }
+
+  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[])[]) {}
+
+  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;
+  }
+
+  binary(index: number, sub = 0): Uint8Array | undefined {
+    const e = this.element(index, sub);
+    if (e === undefined || e.isEmpty) return undefined;
+    return 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));
+  }
+
+  encode(): Uint8Array {
+    const out = new BytesBuilder();
+    this.elements.forEach((g, i) => {
+      if (i > 0) out.addByte(dataElementSeparator);
+      g.forEach((e, j) => {
+        if (j > 0) out.addByte(groupElementSeparator);
+        if (e.isBinary) writeBinary(out, e.bytes);
+        else writeEscaped(out, e.bytes);
+      });
+    });
+    out.addByte(segmentTerminator);
+    return out.takeBytes();
+  }
+
+  toString(): string {
+    return decodeBankText(this.encode());
+  }
+}
+
+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`. The clients check the login data for
+ * ISO 8859-1 up front.
+ */
+export function encodeText(value: string): Uint8Array {
+  return isLatin1(value) ? latin1Encode(value) : utf8Encode(value);
+}
+
+/** Whether `value` fits into ISO 8859-1, the FinTS 3.0 character set. */
+export function isLatin1(value: string): boolean {
+  for (let i = 0; i < value.length; i++) if (value.charCodeAt(i) > 0xff) return false;
+  return true;
+}
+
+/**
+ * Splits a FinTS 3.0 message into segments, resolving escapes and binary data (`@length@bytes`).
+ *
+ * Throws `FormatError` for a negative binary length.
+ */
+export function parseSegments(data: Uint8Array): Segment[] {
+  const segments: Segment[] = [];
+  let elements: DataElement[][] = [];
+  let group: DataElement[] = [];
+  let current: number[] = [];
+  let binary: Uint8Array | undefined;
+  let segmentStarted = false;
+
+  const endElement = (): void => {
+    group.push(binary !== undefined ? new DataElement(binary, true) : new DataElement(Uint8Array.from(current), false));
+    current = [];
+    binary = undefined;
+  };
+
+  const endSegment = (): void => {
+    endElement();
+    elements.push(group);
+    const segment = new Segment(elements);
+    // Skip empty segments, such as a stray double terminator.
+    if (segment.type !== '') segments.push(segment);
+    elements = [];
+    group = [];
+    segmentStarted = false;
+  };
+
+  let i = 0;
+  while (i < data.length) {
+    const c = data[i]!;
+    if (c === escapeCharacter) {
+      if (i + 1 < data.length) current.push(data[i + 1]!);
+      segmentStarted = true;
+      i += 2;
+      continue;
+    }
+    if (c === binaryMarker && current.length === 0 && binary === undefined) {
+      const end = data.indexOf(binaryMarker, i + 1);
+      const length = end > i + 1 ? tryParseInt(latin1Decode(data.subarray(i + 1, end))) : undefined;
+      if (length !== undefined && length < 0) throw new FormatError('Negative binary length');
+      // Compared this way round, a huge length cannot overflow the sum.
+      if (length !== undefined && length <= data.length - (end + 1)) {
+        binary = data.subarray(end + 1, end + 1 + length);
+        segmentStarted = true;
+        i = end + 1 + length;
+        continue;
+      }
+    }
+    if (c === groupElementSeparator) {
+      endElement();
+    } else if (c === dataElementSeparator) {
+      endElement();
+      elements.push(group);
+      group = [];
+    } else if (c === segmentTerminator) {
+      endSegment();
+    } else {
+      // Line breaks and spaces between segments are padding, not content.
+      const isPadding =
+        !segmentStarted &&
+        current.length === 0 &&
+        elements.length === 0 &&
+        group.length === 0 &&
+        (c === 0x0a || c === 0x0d || c === 0x20);
+      if (!isPadding) {
+        current.push(c);
+        segmentStarted = true;
+      }
+    }
+    i++;
+  }
+  if (segmentStarted && current.length > 0) endSegment();
+  return segments;
+}
+
+/** Binary data in a segment to send, written as `@length@bytes`. */
+export class Binary {
+  constructor(readonly bytes: Uint8Array) {}
+}
+
+/** A value of a segment to send; see `SegmentSpec`. */
+export type SegmentValue = string | number | boolean | Binary | 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 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 (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();
+}