@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/tan/challenge.ts

@@ -0,0 +1,261 @@
+import { latin1Decode } from '../util/bytes.js';
+import { copyDate } from '../util/dates.js';
+import { characterReference } from '../util/text.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 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. */
+function decodeEntity(name: string): string | undefined {
+  return characterReference(name) ?? (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, one character per byte the bank sent (ISO 8859-1). */
+  readonly reference: string;
+
+  /**
+   * Challenge text as the bank sent it, including the formatting tags of a structured challenge
+   * (`TanMethod.structuredChallenge`); `plainMessage` is the text to show. Show either as text only, never as HTML
+   * (`innerHTML`, `v-html`): it is the bank's text, not markup to trust.
+   */
+  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: a later prompt for the approval replaces it, or 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, with a copy of `validUntil`, which no other challenge shares. 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 = copyDate(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) flicker = FlickerCode.tryParse(latin1Decode(data));
+    } 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.
+   *
+   * Show it as text, such as with `textContent`, or `{{ }}` in Vue, and `white-space: pre-line` for its line breaks;
+   * never as HTML (`innerHTML`, `v-html`). It keeps the tags the specification does not define, and `&lt;` becomes
+   * `<`, so that as HTML the bank's text could run scripts in the app.
+   */
+  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 a TAN challenge. Blanks around it do not count, and digits of
+   * another width, such as full-width ones, count as the digits they are (Unicode NFKC).
+   */
+  | { 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 a TAN challenge (`TanAnswer`). */
+  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.
+ *
+ * The call fails with a `TypeError`, without reaching the bank, for anything but a `TanAnswer`, for `approved` to a TAN
+ * challenge, for a TAN to an app approval the user can report, and for a TAN that the method rules out: longer than
+ * `TanMethod.maxTanLength`, with anything but the digits 0 to 9 where `TanMethod.numericTan`, or that FinTS 3.0 cannot
+ * send (ISO 8859-1 only). Where the user cannot report the approval (`TanChallenge.manualConfirmation` is `false`),
+ * offer no confirm button: any `TanAnswer` but `cancelled` is ignored.
+ *
+ * If the bank has not confirmed a reported approval yet, the callback is called again with the next
+ * `TanChallenge.attempt` and the bank's latest instructions. 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. New
+ * instructions of the bank then replace the open prompt with the next attempt, which the callback gets after the
+ * handlers of the earlier prompt's `resolved` have run.
+ */
+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,308 @@
+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. Some banks state the LDE of HHD 1.4 with three digits;
+ * a code that both LDE widths read is taken with two, as the specification has it.
+ */
+const layouts = [
+  { lcDigits: 3, lengthDigits: 2 },
+  { lcDigits: 3, lengthDigits: 3 },
+  { lcDigits: 2, lengthDigits: 2 },
+];
+
+/** The most bytes a length field states: HHD 1.3 flags ASCII data in bit 4 of it, HHD 1.4 in bit 6. */
+const maxElementLength: Readonly<Record<HhdVersion, number>> = { hhd13: 0x0f, hhd14: 0x3f };
+
+/** The most bytes of a rendered code, which its one-byte length (LC) states. */
+const maxCodeLength = 0xff;
+
+/** The characters a TAN generator shows; one byte each. */
+const printableAscii = /^[\x20-\x7E]*$/;
+
+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 a TAN generator can
+   * take: one with characters after the length it states, an empty data element, data other than printable ASCII, or
+   * more data than its length fields can state, such as more than 15 bytes in an element in HHD 1.3 or 255 bytes in all.
+   */
+  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.dataLength(lengthDigits))),
+      );
+    }
+    // Only a layout whose fields fill exactly the LC characters, which end the code, can be the right one.
+    if (!challenge.isAtEnd || !code.isAtEnd) throw new FormatError('Flicker code fields do not match its length');
+    const flicker = new FlickerCode(controlBytes.length === 0 ? 'hhd13' : 'hhd14', lc, startCode, dataElements);
+    if (!flicker.fitsTanGenerator) throw new FormatError('Flicker code data the TAN generator cannot take');
+    return flicker;
+  }
+
+  /** Whether the code renders as the bank sent it: its data printable ASCII, every length within its field. */
+  private get fitsTanGenerator(): boolean {
+    const elements = [this.startCode, ...this.dataElements];
+    return elements.every((element) => element.fits(this.version)) && this.payload().length <= 2 * maxCodeLength;
+  }
+
+  /** 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);
+  }
+
+  /**
+   * A data element length field (LDE) of `digits` decimal digits: 1 to 63 characters. The challenge leaves out an
+   * element without data, and sets none of the flags in bits 6 and 7, which only the rendered code carries.
+   */
+  dataLength(digits: number): number {
+    const length = this.decimal(digits);
+    if (length === 0 || length > 0x3f) throw new FormatError('Invalid data element length');
+    return length;
+  }
+
+  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);
+  }
+
+  /** Whether the data are printable ASCII, and no more bytes than the length field of `version` can state. */
+  fits(version: HhdVersion): boolean {
+    const d = this.data;
+    return d === undefined || (printableAscii.test(d) && this.renderData().length / 2 <= maxElementLength[version]);
+  }
+
+  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);
+  }
+}

package/src/tan/tan-image.ts

@@ -0,0 +1,38 @@
+import { base64Encode, latin1Decode } from '../util/bytes.js';
+
+/** The formats of photoTAN and QR-TAN images: raster images, which unlike SVG cannot carry scripts. */
+const imageMimeTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp']);
+
+/** An image challenge (photoTAN, QR-TAN) with its MIME type. */
+export class TanImage {
+  constructor(
+    /** The media type of `bytes`, for example `image/png`. */
+    readonly mimeType: string,
+    /** The encoded image. */
+    readonly bytes: Uint8Array,
+  ) {}
+
+  /**
+   * Reads the bank's image container: a two-byte length and the MIME type, then a two-byte length and the image.
+   *
+   * `undefined` unless the MIME type, in any case, is that of a PNG, JPEG, GIF, WebP or BMP image, and the container
+   * holds the whole image.
+   */
+  static tryParse(data: Uint8Array): TanImage | undefined {
+    if (data.length < 4) return undefined;
+    const mimeLength = (data[0]! << 8) | data[1]!;
+    if (mimeLength === 0 || data.length < 2 + mimeLength + 2) return undefined;
+    const mime = latin1Decode(data.subarray(2, 2 + mimeLength)).toLowerCase();
+    if (!imageMimeTypes.has(mime)) return undefined;
+    const offset = 2 + mimeLength;
+    const imageLength = (data[offset]! << 8) | data[offset + 1]!;
+    const start = offset + 2;
+    if (start + imageLength > data.length) return undefined;
+    return new TanImage(mime, data.subarray(start, start + imageLength));
+  }
+
+  /** The image as a `data:` URL, for the `src` of an `<img>` only: the bytes are the bank's, whatever their type says. */
+  toDataUrl(): string {
+    return `data:${this.mimeType};base64,${base64Encode(this.bytes)}`;
+  }
+}