@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/session/user-prompts.ts

@@ -0,0 +1,174 @@
+import type { BankMessage } from '../core/bank-info.js';
+import type { FinTsClientOptions, MessageLogger } from '../core/client.js';
+import { FinTsStateError } from '../core/errors.js';
+import type { FinTsFeedback } from '../core/feedback.js';
+import type { TanAnswer, TanChallenge } from '../tan/challenge.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import { Deferred } from '../util/async.js';
+import { invalidArgument } from '../util/errors.js';
+
+function closedError(): FinTsStateError {
+  return new FinTsStateError('The FinTS client is closed');
+}
+
+/**
+ * Everything a session tells the app, asks of it or waits for: the bank's messages, warnings and log, the TAN callback,
+ * the selectors and the pauses between status requests.
+ *
+ * Once the client is closed nothing is told or asked, and every wait ends with `FinTsStateError`. Errors of the
+ * callbacks that only inform the app wait for `reportingCallbackErrors`, as `FinTsClientOptions` promises.
+ */
+export class UserPrompts {
+  private closed = false;
+
+  /** The first error an informing callback threw during the running call. */
+  private callbackError: { error: unknown } | undefined;
+
+  /** Aborts the waits under way; each wait removes its abort when it is over. */
+  private readonly aborts = new Set<() => void>();
+
+  constructor(private readonly options: FinTsClientOptions) {}
+
+  /** Ends every wait; the client calls it once. */
+  close(): void {
+    this.closed = true;
+    for (const abort of [...this.aborts]) abort();
+    this.aborts.clear();
+  }
+
+  /** Throws `FinTsStateError` once `close` was called. */
+  checkOpen(): void {
+    if (this.closed) throw closedError();
+  }
+
+  /**
+   * Runs `call` and then fails it with the first error an informing callback threw meanwhile; an error of `call` itself
+   * takes precedence.
+   */
+  async reportingCallbackErrors<T>(call: () => Promise<T>): Promise<T> {
+    this.callbackError = undefined;
+    const result = await call();
+    // Set by a callback while `call` ran, which the compiler cannot see.
+    const failure = this.callbackError as { error: unknown } | undefined;
+    if (failure !== undefined) throw failure.error;
+    return result;
+  }
+
+  /** The app's logger, whose errors are kept for `reportingCallbackErrors`; `undefined` without one. */
+  get logger(): MessageLogger | undefined {
+    const logger = this.options.logger;
+    if (logger === undefined) return undefined;
+    return (direction, message) => {
+      this.inform(() => {
+        logger(direction, message);
+      });
+    };
+  }
+
+  /** Passes the bank's `message` to the app, unless the client is closed. */
+  showBankMessage(message: BankMessage): void {
+    const handler = this.options.onBankMessage;
+    if (handler !== undefined && !this.closed) {
+      this.inform(() => {
+        handler(message);
+      });
+    }
+  }
+
+  /** Passes the bank's `warning` to the app, unless the client is closed. */
+  showWarning(warning: FinTsFeedback): void {
+    const handler = this.options.onWarning;
+    if (handler !== undefined && !this.closed) {
+      this.inform(() => {
+        handler(warning);
+      });
+    }
+  }
+
+  private inform(callback: () => void): void {
+    try {
+      callback();
+    } catch (error) {
+      this.callbackError ??= { error };
+    }
+  }
+
+  /** Shows `challenge` through the TAN callback and returns its answer. */
+  askTan(challenge: TanChallenge): Promise<TanAnswer> {
+    return this.unlessClosed(() => this.options.tanCallback(challenge));
+  }
+
+  /** Waits for `delayMs` milliseconds, or until `interrupt` settles. */
+  pause(delayMs: number, interrupt?: Promise<unknown>): Promise<void> {
+    if (this.closed) return Promise.reject(closedError());
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const elapsed = new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, Math.max(0, delayMs));
+    });
+    // Neither an interrupted wait nor a closed client may leave a timer behind that keeps the process alive.
+    return this.unlessClosed(() =>
+      Promise.race([elapsed, ...(interrupt === undefined ? [] : [interrupt.then(() => undefined)])]),
+    ).finally(() => {
+      clearTimeout(timer);
+    });
+  }
+
+  /**
+   * The TAN method to use among `candidates`: the app's choice, or the first without a selector or an answer.
+   *
+   * Throws `TypeError` if the selector returns a method that is not among `candidates`.
+   */
+  async chooseMethod(candidates: readonly TanMethod[]): Promise<TanMethod> {
+    const selector = this.options.tanMethodSelector;
+    if (candidates.length === 1 || selector === undefined) return candidates[0]!;
+    const chosen = await this.unlessClosed(() => selector(candidates));
+    if (chosen === undefined) return candidates[0]!;
+    const match = candidates.find((m) => m.securityFunction === chosen.securityFunction);
+    if (match === undefined) throw invalidArgument('Returned a TAN method the bank did not offer', 'tanMethodSelector');
+    return match;
+  }
+
+  /**
+   * The TAN medium to use among the active `media`: the app's choice, or the first without a selector or an answer.
+   *
+   * Throws `TypeError` if the selector returns a medium that is not among `media`.
+   */
+  async chooseMedium(media: readonly TanMedium[]): Promise<TanMedium> {
+    const selector = this.options.tanMediumSelector;
+    if (media.length === 1 || selector === undefined) return media[0]!;
+    const chosen = await this.unlessClosed(() => selector(media));
+    if (chosen === undefined) return media[0]!;
+    const match = media.find((m) => m.name === chosen.name);
+    if (match === undefined) throw invalidArgument('Returned a TAN medium the bank did not list', 'tanMediumSelector');
+    return match;
+  }
+
+  /**
+   * Starts `wait` and ends it with `FinTsStateError` if `close` is called before it is over.
+   *
+   * Once the client is closed, the returned promise rejects rather than this function throwing: a caller that starts
+   * several waits at once would otherwise leave the failure of those started first unheard.
+   */
+  private unlessClosed<T>(wait: () => T | Promise<T>): Promise<T> {
+    if (this.closed) return Promise.reject(closedError());
+    const result = new Deferred<T>();
+    const abort = (): void => {
+      result.reject(closedError());
+    };
+    this.aborts.add(abort);
+    // Runs `wait` at once, as far as its first `await`, and turns an error it throws into a rejection.
+    const started = (async (): Promise<T> => wait())();
+    started
+      .then(
+        (value) => {
+          result.resolve(value);
+        },
+        (error: unknown) => {
+          result.reject(error);
+        },
+      )
+      .finally(() => this.aborts.delete(abort))
+      .catch(() => undefined);
+    return result.promise;
+  }
+}

package/src/tan/challenge.ts

@@ -0,0 +1,252 @@
+import { latin1Decode } from '../util/bytes.js';
+import { challengeInstruction, FlickerCode, hasEmbeddedFlickerCode } from './flicker.js';
+import { TanImage } from './tan-image.js';
+import type { TanMedium, TanMethod } from './tan-models.js';
+
+/** Challenge text banks send when there is nothing to show. */
+const noChallenge = 'nochallenge';
+
+/** `message`, or `undefined` where it is empty or the filler banks send when there is nothing to show. */
+export function challengeText(message: string | undefined): string | undefined {
+  return message === undefined || message === '' || message === noChallenge ? undefined : message;
+}
+
+const printableAscii = /^[\x20-\x7E]+$/;
+const lineBreak = /<br\b[^<>]*>/gi;
+const blockTag = /<\/?(?:p|li)\b[^<>]*>/gi;
+
+/**
+ * The formatting tags a structured challenge may carry besides line breaks, paragraphs and list items (PIN/TAN, Data
+ * Dictionary "Challenge"). Angle brackets around anything else, such as `<50 EUR>`, are part of the text the user
+ * approves, so they stay. Excluding `<` and `>` from the tag keeps the search linear.
+ */
+const formattingTag = /<\/?(?:b|i|u|ul|ol)\b[^<>]*>/gi;
+const entityReference = /&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g;
+const blankLines = /\n{3,}/g;
+
+const namedEntities: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  auml: 'ä',
+  ouml: 'ö',
+  uuml: 'ü',
+  Auml: 'Ä',
+  Ouml: 'Ö',
+  Uuml: 'Ü',
+  szlig: 'ß',
+  euro: '€',
+};
+
+/**
+ * The character `name` refers to; `undefined` for an unknown name and for a number that is not a character, as XML
+ * defines them: `NUL`, half a surrogate pair, or beyond Unicode.
+ */
+function decodeEntity(name: string): string | undefined {
+  if (name.startsWith('#')) {
+    const isHex = name.startsWith('#x') || name.startsWith('#X');
+    const digits = name.substring(isHex ? 2 : 1);
+    const code = (isHex ? /^[0-9a-fA-F]+$/ : /^[0-9]+$/).test(digits) ? parseInt(digits, isHex ? 16 : 10) : NaN;
+    const isCharacter = code > 0 && (code < 0xd800 || code > 0xdfff) && code <= 0x10ffff;
+    return isCharacter ? String.fromCodePoint(code) : undefined;
+  }
+  return Object.hasOwn(namedEntities, name) ? namedEntities[name] : undefined;
+}
+
+/** What `TanChallenge` takes. */
+export interface TanChallengeInit {
+  method: TanMethod;
+  reference: string;
+  message?: string | undefined;
+  hhdUc?: Uint8Array | undefined;
+  flickerCode?: FlickerCode | undefined;
+  image?: TanImage | undefined;
+  isDecoupled?: boolean;
+  validUntil?: Date | undefined;
+  tanMediumName?: string | undefined;
+  attempt?: number;
+  resolved?: Promise<void> | undefined;
+}
+
+/** A request from the bank to authorize an action with a TAN or an app approval. */
+export class TanChallenge {
+  /** The TAN method the challenge is for. */
+  readonly method: TanMethod;
+
+  /** Bank reference of the pending action. */
+  readonly reference: string;
+
+  /** Challenge text as sent by the bank; may contain simple HTML. See `plainMessage`. */
+  readonly message: string | undefined;
+
+  /** Raw challenge data for TAN generators (HHD_UC). */
+  readonly hhdUc: Uint8Array | undefined;
+
+  /** chipTAN optical flicker code, if the challenge contains one. */
+  readonly flickerCode: FlickerCode | undefined;
+
+  /** photoTAN / QR-TAN image, if the challenge contains one. */
+  readonly image: TanImage | undefined;
+
+  /** Approval happens in a separate app; see `TanCallback` for what to answer. */
+  readonly isDecoupled: boolean;
+
+  /** The exact moment until which the bank accepts the TAN or the approval, where it states date and time of day. */
+  readonly validUntil: Date | undefined;
+
+  /** Name of the TAN medium the bank sent the challenge to. */
+  readonly tanMediumName: string | undefined;
+
+  /** Counts repeated prompts for the same decoupled approval. */
+  readonly attempt: number;
+
+  /**
+   * Settles when the client needs no more answer to this challenge: the bank confirmed the approval, or the approval
+   * failed, timed out or was cancelled. Set where the client asks the bank by itself while the callback shows the
+   * challenge (`TanCallback`), `undefined` otherwise. It never rejects.
+   */
+  readonly resolved: Promise<void> | undefined;
+
+  /** A challenge as the bank sent it. Use `TanChallenge.create` to have a flicker code or image detected in the data. */
+  constructor(init: TanChallengeInit) {
+    this.method = init.method;
+    this.reference = init.reference;
+    this.message = init.message;
+    this.hhdUc = init.hhdUc;
+    this.flickerCode = init.flickerCode;
+    this.image = init.image;
+    this.isDecoupled = init.isDecoupled ?? false;
+    this.validUntil = init.validUntil;
+    this.tanMediumName = init.tanMediumName;
+    this.attempt = init.attempt ?? 1;
+    this.resolved = init.resolved;
+  }
+
+  /** Builds a challenge and detects a photoTAN image or chipTAN flicker code in `hhdUc` or `message`. */
+  static create(init: Omit<TanChallengeInit, 'flickerCode' | 'image' | 'resolved'>): TanChallenge {
+    let image: TanImage | undefined;
+    let flicker: FlickerCode | undefined;
+    const data = init.hhdUc !== undefined && init.hhdUc.length > 0 ? init.hhdUc : undefined;
+    if (data !== undefined) {
+      image = TanImage.tryParse(data);
+      if (image === undefined) {
+        const text = latin1Decode(data);
+        if (printableAscii.test(text)) flicker = FlickerCode.tryParse(text);
+      }
+    } else if (init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
+      flicker = FlickerCode.tryParse(init.message);
+    }
+    return new TanChallenge({
+      ...init,
+      message: challengeText(init.message),
+      hhdUc: data,
+      flickerCode: flicker,
+      image,
+    });
+  }
+
+  /**
+   * Whether the user can report the approval in the banking app; `false` where only the bank's confirmation completes
+   * it, which `TanCallback` tells how to handle.
+   */
+  get manualConfirmation(): boolean {
+    return !this.isDecoupled || this.method.decoupledManualConfirmation;
+  }
+
+  /**
+   * `message` as the user reads it.
+   *
+   * A method with structured challenges (`TanMethod.structuredChallenge`) may use the formatting tags the specification
+   * defines. Line breaks, paragraphs and list items become new lines. Bold, italics, underlining and list tags are
+   * removed, and the entity references of such markup are resolved. Any other challenge stays as the bank sent it,
+   * which is how the specification wants it shown.
+   */
+  get plainMessage(): string | undefined {
+    const text = this.message;
+    if (text === undefined) return undefined;
+    const instruction = challengeInstruction(text);
+    if (!this.method.structuredChallenge) return instruction;
+    return instruction
+      .replace(lineBreak, '\n')
+      .replace(blockTag, '\n')
+      .replace(formattingTag, '')
+      .replace(entityReference, (match, name: string) => decodeEntity(name) ?? match)
+      .replace(blankLines, '\n\n')
+      .trim();
+  }
+}
+
+// Copies of a challenge for the prompts of one approval. Not methods of `TanChallenge`, so that they are not part of its
+// API; they stand beside the class, so that a field added to it is added here as well.
+
+/** `challenge` again, counted as the next prompt for the same approval, with the bank's new instructions `message`. */
+export function nextAttempt(challenge: TanChallenge, message?: string): TanChallenge {
+  return copyChallenge(challenge, { attempt: challenge.attempt + 1, message: message ?? challenge.message });
+}
+
+/** `challenge` with `TanChallenge.resolved` set to `resolved`. */
+export function withResolved(challenge: TanChallenge, resolved: Promise<void>): TanChallenge {
+  return copyChallenge(challenge, { resolved });
+}
+
+function copyChallenge(challenge: TanChallenge, changes: Partial<TanChallengeInit>): TanChallenge {
+  return new TanChallenge({
+    method: challenge.method,
+    reference: challenge.reference,
+    message: challenge.message,
+    hhdUc: challenge.hhdUc,
+    flickerCode: challenge.flickerCode,
+    image: challenge.image,
+    isDecoupled: challenge.isDecoupled,
+    validUntil: challenge.validUntil,
+    tanMediumName: challenge.tanMediumName,
+    attempt: challenge.attempt,
+    resolved: challenge.resolved,
+    ...changes,
+  });
+}
+
+/** The user's answer to a `TanChallenge`: `TanAnswer.tan(…)`, `TanAnswer.approved` or `TanAnswer.cancelled`. */
+export type TanAnswer =
+  /** The TAN the user entered; an empty one cancels. */
+  | { readonly kind: 'tan'; readonly tan: string }
+  /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+  | { readonly kind: 'approved' }
+  /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+  | { readonly kind: 'cancelled' };
+
+const approvedAnswer: TanAnswer = Object.freeze({ kind: 'approved' });
+const cancelledAnswer: TanAnswer = Object.freeze({ kind: 'cancelled' });
+
+/** The answers a `TanCallback` returns. */
+export const TanAnswer = Object.freeze({
+  /** The TAN the user entered; an empty one cancels. */
+  tan: (tan: string): TanAnswer => Object.freeze({ kind: 'tan', tan }),
+  /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+  approved: approvedAnswer,
+  /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+  cancelled: cancelledAnswer,
+});
+
+/**
+ * Shows the `TanChallenge` to the user and returns the `TanAnswer`: `TanAnswer.tan(…)` for a TAN, `TanAnswer.approved`
+ * once the user reports an approval in the banking app (`TanChallenge.isDecoupled`), `TanAnswer.cancelled` to cancel
+ * either. An answer that does not fit the challenge fails the call with a `TypeError`.
+ *
+ * Where the client polls the bank by itself, it sets `TanChallenge.resolved`: close the prompt when it settles, the
+ * callback's result is no longer waited for then. If the bank has not confirmed a reported approval yet, the callback is
+ * called again with the next `TanChallenge.attempt`. Where `TanChallenge.manualConfirmation` is `false`, offer no
+ * confirm button: any answer but `TanAnswer.cancelled` is ignored.
+ */
+export type TanCallback = (challenge: TanChallenge) => TanAnswer | Promise<TanAnswer>;
+
+/** Picks one of several allowed TAN methods; the first is used when this returns `undefined`. */
+export type TanMethodSelector = (
+  methods: readonly TanMethod[],
+) => TanMethod | undefined | Promise<TanMethod | undefined>;
+
+/** Picks one of several active TAN media; the first is used when this returns `undefined`. */
+export type TanMediumSelector = (media: readonly TanMedium[]) => TanMedium | undefined | Promise<TanMedium | undefined>;

package/src/tan/flicker.ts

@@ -0,0 +1,270 @@
+import { FormatError } from '../util/errors.js';
+import { withoutWhitespace } from '../util/text.js';
+
+/** Version of the chipTAN HHD specification a flicker code follows: 1.3, or 1.4, which adds control bytes. */
+export type HhdVersion = 'hhd13' | 'hhd14';
+
+// A combined challenge embeds the flicker code in the challenge text:
+// `CHLGUC` + four-digit length + code + `CHLGTEXT` + four digits + instruction text.
+const codeMarker = 'CHLGUC';
+const textMarker = 'CHLGTEXT';
+const markerLengthDigits = 4;
+
+/** Whether `message` is a combined challenge with an embedded flicker code. */
+export function hasEmbeddedFlickerCode(message: string): boolean {
+  return message.includes(codeMarker);
+}
+
+/** The instruction text of a combined challenge; `message` itself if it is none. */
+export function challengeInstruction(message: string): string {
+  const start = message.indexOf(textMarker);
+  if (start < 0) return message;
+  const textStart = start + textMarker.length + markerLengthDigits;
+  return textStart < message.length ? message.substring(textStart) : '';
+}
+
+/**
+ * Digit counts of the challenge length (LC) and of the data element lengths (LDE) to try when parsing.
+ *
+ * HHD 1.4 states the LC with three digits, HHD 1.3 with two.
+ */
+const layouts = [
+  { lcDigits: 3, lengthDigits: 2 },
+  { lcDigits: 3, lengthDigits: 3 },
+  { lcDigits: 2, lengthDigits: 2 },
+];
+
+function hex(value: number, width: number): string {
+  return value.toString(16).toUpperCase().padStart(width, '0');
+}
+
+/** A chipTAN optical challenge (flicker code) in HHD 1.3 or 1.4 format. */
+export class FlickerCode {
+  private constructor(
+    /** The HHD version the code follows, told by the control bytes of its start code. */
+    readonly version: HhdVersion,
+    /** Length of the challenge (LC) as stated at the start of the code. */
+    readonly lc: number,
+    private readonly startCode: StartCode,
+    private readonly dataElements: readonly DataElement[],
+  ) {}
+
+  /** Parses the challenge data sent by the bank; throws `FormatError` if it is not a flicker code. */
+  static parse(code: string): FlickerCode {
+    const cleaned = extractCode(code);
+    for (const layout of layouts) {
+      try {
+        return FlickerCode.parseLayout(new Reader(cleaned), layout.lcDigits, layout.lengthDigits);
+      } catch (error) {
+        // Not this layout; try the next one.
+        if (!(error instanceof FormatError)) throw error;
+      }
+    }
+    throw new FormatError('Invalid flicker code', code);
+  }
+
+  /** Parses `code`, or returns `undefined` if it is not a flicker code. */
+  static tryParse(code: string): FlickerCode | undefined {
+    try {
+      return FlickerCode.parse(code);
+    } catch (error) {
+      if (error instanceof FormatError) return undefined;
+      throw error;
+    }
+  }
+
+  private static parseLayout(code: Reader, lcDigits: number, lengthDigits: number): FlickerCode {
+    const lc = code.decimal(lcDigits);
+    const challenge = new Reader(code.take(lc));
+    // The start code has a hex length field whose top bit announces control bytes (HHD 1.4); the top bit of each
+    // control byte announces another one.
+    const startLength = challenge.hex(2);
+    const controlBytes: number[] = [];
+    if ((startLength & 0x80) !== 0) {
+      do {
+        controlBytes.push(challenge.hex(2));
+      } while ((controlBytes.at(-1)! & 0x80) !== 0 && controlBytes.length < 10);
+    }
+    const startCode = new StartCode(challenge.take(startLength & 0x3f), controlBytes);
+    const dataElements: DataElement[] = [];
+    for (let i = 0; i < 3; i++) {
+      dataElements.push(
+        new DataElement(challenge.isAtEnd ? undefined : challenge.take(challenge.decimal(lengthDigits) & 0x3f)),
+      );
+    }
+    // The fields fill exactly the LC characters; a layout that reads them otherwise is the wrong one.
+    if (!challenge.isAtEnd) throw new FormatError('Flicker code fields do not match its length');
+    return new FlickerCode(controlBytes.length === 0 ? 'hhd13' : 'hhd14', lc, startCode, dataElements);
+  }
+
+  /** The data of the start code, which opens the challenge. */
+  get startCodeData(): string {
+    return this.startCode.data ?? '';
+  }
+
+  /** The first data element of the challenge; `undefined` if the code leaves it out. */
+  get dataElement1(): string | undefined {
+    return this.dataElements[0]?.data;
+  }
+
+  /** The second data element of the challenge; `undefined` if the code leaves it out. */
+  get dataElement2(): string | undefined {
+    return this.dataElements[1]?.data;
+  }
+
+  /** The third data element of the challenge; `undefined` if the code leaves it out. */
+  get dataElement3(): string | undefined {
+    return this.dataElements[2]?.data;
+  }
+
+  /** The hex string transmitted to the TAN generator, including checksums. */
+  render(): string {
+    const payload = this.payload();
+    return `${payload}${this.luhnChecksum()}${xorChecksum(payload)}`;
+  }
+
+  private payload(): string {
+    let s = this.startCode.renderLength(this.version);
+    for (const c of this.startCode.controlBytes) s += hex(c, 2);
+    s += this.startCode.renderData();
+    for (const element of this.dataElements) {
+      s += element.renderLength(this.version);
+      s += element.renderData();
+    }
+    return `${hex(Math.floor((s.length + 2) / 2), 2)}${s}`;
+  }
+
+  private luhnChecksum(): string {
+    let s = '';
+    for (const c of this.startCode.controlBytes) s += hex(c, 2);
+    s += this.startCode.renderData();
+    for (const element of this.dataElements) if (element.data !== undefined) s += element.renderData();
+    let sum = 0;
+    for (let i = 0; i + 1 < s.length; i += 2) {
+      sum += parseInt(s[i]!, 16) + digitSum(2 * parseInt(s[i + 1]!, 16));
+    }
+    const mod = sum % 10;
+    return mod === 0 ? '0' : hex(10 - mod, 1);
+  }
+
+  /** Frames to animate: each is `[clock, bit0, bit1, bit2, bit3]` for the five bars. */
+  frames(): boolean[][] {
+    const code = `0FFF${this.render()}`;
+    const result: boolean[][] = [];
+    for (let i = 0; i + 1 < code.length; i += 2) {
+      for (const nibble of [code[i + 1]!, code[i]!]) {
+        const v = parseInt(nibble, 16);
+        const bits = [(v & 1) !== 0, (v & 2) !== 0, (v & 4) !== 0, (v & 8) !== 0];
+        result.push([true, ...bits]);
+        result.push([false, ...bits]);
+      }
+    }
+    return result;
+  }
+}
+
+/** The code of a combined challenge, or `code` itself without whitespace. */
+function extractCode(code: string): string {
+  const compact = withoutWhitespace(code);
+  const start = compact.indexOf(codeMarker);
+  const codeStart = start + codeMarker.length + markerLengthDigits;
+  const end = compact.indexOf(textMarker);
+  return start >= 0 && end >= codeStart ? compact.substring(codeStart, end) : compact;
+}
+
+function xorChecksum(payload: string): string {
+  let x = 0;
+  for (const c of payload) x ^= parseInt(c, 16);
+  return hex(x, 1);
+}
+
+function digitSum(n: number): number {
+  let sum = 0;
+  while (n !== 0) {
+    sum += n % 10;
+    n = Math.floor(n / 10);
+  }
+  return sum;
+}
+
+/** Reads the fields of a flicker code from left to right; throws `FormatError` when a field is missing or malformed. */
+class Reader {
+  private position = 0;
+
+  constructor(private readonly code: string) {}
+
+  get remaining(): number {
+    return this.code.length - this.position;
+  }
+
+  get isAtEnd(): boolean {
+    return this.remaining === 0;
+  }
+
+  take(length: number): string {
+    if (length > this.remaining) throw new FormatError('Flicker code too short');
+    const field = this.code.substring(this.position, this.position + length);
+    this.position += length;
+    return field;
+  }
+
+  decimal(digits: number): number {
+    return parseInt(Reader.match(/^[0-9]+$/, this.take(digits)), 10);
+  }
+
+  hex(digits: number): number {
+    return parseInt(Reader.match(/^[0-9A-Fa-f]+$/, this.take(digits)), 16);
+  }
+
+  private static match(pattern: RegExp, field: string): string {
+    if (!pattern.test(field)) throw new FormatError('Invalid length field', field);
+    return field;
+  }
+}
+
+/**
+ * A data element of the flicker code: a length field (LDE) followed by the data; `undefined` data if the code leaves
+ * the element out.
+ */
+class DataElement {
+  constructor(readonly data: string | undefined) {}
+
+  get isBcd(): boolean {
+    return this.data === undefined || /^[0-9]+$/.test(this.data);
+  }
+
+  renderData(): string {
+    const d = this.data;
+    if (d === undefined) return '';
+    if (!this.isBcd) {
+      let ascii = '';
+      for (let i = 0; i < d.length; i++) ascii += hex(d.charCodeAt(i), 2);
+      return ascii;
+    }
+    return d.length % 2 === 1 ? `${d}F` : d;
+  }
+
+  renderLength(version: HhdVersion): string {
+    if (this.data === undefined) return '';
+    const length = Math.floor(this.renderData().length / 2);
+    if (this.isBcd) return hex(length, 2);
+    if (version === 'hhd14') return hex(length + 0x40, 2);
+    return `1${hex(length, 1)}`;
+  }
+}
+
+/** The start code: a data element whose length field may announce control bytes (HHD 1.4). */
+class StartCode extends DataElement {
+  constructor(
+    data: string | undefined,
+    readonly controlBytes: readonly number[],
+  ) {
+    super(data);
+  }
+
+  override renderLength(version: HhdVersion): string {
+    const s = super.renderLength(version);
+    if (version === 'hhd13' || this.controlBytes.length === 0) return s;
+    return hex(parseInt(s, 16) + 0x80, 2);
+  }
+}