@coderoftime/fints 0.1.0 → 0.2.0

package/src/session/signed-dialog.ts

@@ -0,0 +1,192 @@
+import { requireLatin1 } from '../core/config.js';
+import {
+  bankErrorFor,
+  FinTsLoginDataChangedError,
+  FinTsProtocolError,
+  FinTsTanCancelledError,
+} from '../core/errors.js';
+import { allowedTanMethodsIn, FeedbackCodes, hasCode, hasErrors, userWarnings } from '../core/feedback.js';
+import type { TanMethod } from '../tan/tan-models.js';
+import { invalidArgument } from '../util/errors.js';
+import type { Approval, FinTs3Dialog } from '../v3/dialog.js';
+import { IncomingMessage3 } from '../v3/message.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import type { SegmentSpec } from '../v3/syntax.js';
+import { appApprovalWait } from './app-approval.js';
+import type { LoginGuard, RequestKind } from './login-guard.js';
+import type { SessionState } from './session-state.js';
+import type { UserPrompts } from './user-prompts.js';
+
+/** The parts of the session that every `SignedDialog` reports to. */
+export interface SessionParts {
+  readonly parameters: ParameterStore;
+  readonly state: SessionState;
+  readonly prompts: UserPrompts;
+  readonly guard: LoginGuard;
+}
+
+/**
+ * A dialog signed with the PIN, which settles each answer before it hands it out: it keeps the parameter data of the
+ * dialog's opening, passes the notices on, has the `LoginGuard` judge the answer and throws its errors, and completes
+ * the approval the bank asks for. The session sends every message signed with the PIN through it, so that the guard
+ * judges every answer, that to the dialog's end included.
+ */
+export class SignedDialog {
+  constructor(
+    private readonly dialog: FinTs3Dialog,
+    private readonly session: SessionParts,
+  ) {}
+
+  /** Whether the bank knows this dialog and it has not ended. */
+  get isActive(): boolean {
+    return this.dialog.isActive;
+  }
+
+  /** Logs in, which opens the dialog; with `synchronize` the bank also assigns a customer system ID. */
+  async login(synchronize = false): Promise<IncomingMessage3> {
+    return this.settle(await this.dialog.start(synchronize), 'login');
+  }
+
+  /**
+   * Logs in, asking strong authentication for `order`, then sends `order` in a message of its own, as for listing the
+   * TAN media while no medium is chosen yet (`FinTs3Dialog.startWith`); returns both answers.
+   */
+  async loginWith(order: SegmentSpec): Promise<IncomingMessage3[]> {
+    const start = this.dialog.startWith(order);
+    const login = await this.settle(await start.login(), 'login');
+    return [login, await this.settle(await start.order(), 'order')];
+  }
+
+  /** Sends `order`, the first page of a query, and completes the approval the bank asks for. */
+  async send(order: SegmentSpec): Promise<IncomingMessage3> {
+    return this.settle(await this.dialog.send(order), 'order');
+  }
+
+  /**
+   * Sends `order` for a further page of a query (Formals B.6.3), whose answer must not ask for an approval: the client
+   * completes that of the first page only, so that a bank that asks anew for every page cannot prompt the user once per
+   * page. Throws `FinTsProtocolError` if it asks for one.
+   */
+  async sendFurtherPage(order: SegmentSpec): Promise<IncomingMessage3> {
+    const response = await this.dialog.send(order);
+    this.receive(response, 'order', false);
+    if (this.dialog.approvalAskedIn(response) !== undefined) {
+      throw new FinTsProtocolError('The bank asks for an approval of a further page of the same query');
+    }
+    return response;
+  }
+
+  /**
+   * Ends the dialog at the bank; does nothing if it is not active. Of the answer only a rejected PIN counts, which the
+   * guard judges: the dialog is over either way.
+   */
+  async end(): Promise<void> {
+    const response = await this.dialog.end();
+    if (response !== undefined && hasErrors(response.feedback)) {
+      this.session.guard.judge(bankErrorFor(response.feedback), 'order', this.dialog.method);
+    }
+  }
+
+  /**
+   * Receives `response`, the answer to a request of `kind`: keeps its parameter data where it answers the `opening` of
+   * the dialog, the login or its approval, even alongside errors, since the remedy for a refused login may need them;
+   * passes its notices on; and has the guard judge it, then throws its errors, as the refusal of the login where they
+   * amount to one.
+   */
+  private receive(response: IncomingMessage3, kind: RequestKind, opening: boolean): void {
+    if (opening) this.session.parameters.keep(response);
+    this.readNotices(response);
+    const error = hasErrors(response.feedback) ? bankErrorFor(response.feedback, kind === 'approval') : undefined;
+    const refusal = this.session.guard.judge(error, kind, this.dialog.method);
+    // Every further message of a refused login's dialog would carry the refused PIN.
+    if (refusal !== undefined) this.dialog.discard();
+    if (error !== undefined) throw refusal ?? error;
+  }
+
+  /**
+   * Where `response` answers a login, a request of `kind` other than `order`, or its approval with new login data: ends
+   * the dialog, stops the client from logging in with the old ones, and fails the call with
+   * `FinTsLoginDataChangedError` (Rückmeldungscodes C.6). It runs before any approval, which would cost the user a TAN
+   * for a session that ends anyway. New login data next to an error are the login's refusal already
+   * (`loginRefusalFor`).
+   */
+  private async retireOldLoginData(response: IncomingMessage3, kind: RequestKind): Promise<void> {
+    if (kind === 'order' || !hasCode(response.feedback, FeedbackCodes.newLoginData)) return;
+    await this.end();
+    const error = new FinTsLoginDataChangedError(response.feedback);
+    throw this.session.guard.judge(error, kind, this.dialog.method) ?? error;
+  }
+
+  /**
+   * Receives `response`, the answer to a request of `kind`, then completes the approval it asks for; returns it joined
+   * with the response that completes the approval.
+   *
+   * Throws `FinTsProtocolError` if that response asks for an approval once more: the bank has not executed the message
+   * then either, and read as done it would report an empty result.
+   */
+  private async settle(response: IncomingMessage3, kind: RequestKind): Promise<IncomingMessage3> {
+    const opening = kind !== 'order';
+    this.receive(response, kind, opening);
+    await this.retireOldLoginData(response, kind);
+    const approval = this.dialog.approvalAskedIn(response);
+    if (approval === undefined) return response;
+    const approved = approval.challenge.isDecoupled
+      ? await this.awaitAppApproval(approval, opening)
+      : await this.enterTan(approval, opening);
+    await this.retireOldLoginData(approved, kind);
+    if (this.dialog.approvalAskedIn(approved) !== undefined) {
+      throw new FinTsProtocolError('The bank asks for another approval in answer to the approval');
+    }
+    return IncomingMessage3.combine(response, approved);
+  }
+
+  /** Passes on the notices in `response`: the TAN methods the user may use (3920), the bank's messages and warnings. */
+  private readNotices(response: IncomingMessage3): void {
+    const allowed = allowedTanMethodsIn(response.feedback);
+    if (allowed.length > 0) this.session.state.rememberAllowedMethods(allowed);
+    for (const message of response.bankMessages) this.session.prompts.showBankMessage(message);
+    for (const warning of userWarnings(response.feedback)) this.session.prompts.showWarning(warning);
+  }
+
+  /** Asks the user for the TAN `approval` takes and sends it; `opening` tells whether it approves the login. */
+  private async enterTan(approval: Approval<IncomingMessage3>, opening: boolean): Promise<IncomingMessage3> {
+    const answer = await this.session.prompts.askTan(approval.challenge);
+    if (answer.kind === 'approved') {
+      throw invalidArgument('Answered a TAN challenge with an approval in the banking app', 'tanCallback');
+    }
+    // NFKC, so that digits of another width, such as those of a Japanese input method, go out as the digits they are.
+    const tan = answer.kind === 'tan' ? answer.tan.normalize('NFKC').trim() : '';
+    if (tan === '') throw new FinTsTanCancelledError();
+    const response = await approval.submitTan(requireTanOf(approval.challenge.method, tan));
+    this.receive(response, 'approval', opening);
+    return response;
+  }
+
+  /** Waits for the user to approve in the banking app; `opening` tells whether the approval is that of the login. */
+  private awaitAppApproval(approval: Approval<IncomingMessage3>, opening: boolean): Promise<IncomingMessage3> {
+    const prompts = this.session.prompts;
+    return appApprovalWait(approval, {
+      ask: (challenge) => prompts.askTan(challenge),
+      pause: (delayMs, interrupt) => prompts.pause(delayMs, interrupt),
+      receive: (response) => {
+        this.receive(response, 'approval', opening);
+      },
+    }).run();
+  }
+}
+
+/**
+ * Throws `TypeError` for a TAN that `method` rules out, which the bank would count as a failed attempt: one longer than
+ * `TanMethod.maxTanLength`, or with other characters than digits for a `TanMethod.numericTan` method; and for one that
+ * FinTS 3.0 cannot send. The message leaves out the TAN.
+ */
+function requireTanOf(method: TanMethod, tan: string): string {
+  const max = method.maxTanLength;
+  if (max !== undefined && max > 0 && tan.length > max) {
+    throw invalidArgument(`The TAN method ${method.name} takes TANs of at most ${max} characters`, 'tan');
+  }
+  if (method.numericTan && !/^[0-9]+$/.test(tan)) {
+    throw invalidArgument(`The TAN method ${method.name} takes digits only`, 'tan');
+  }
+  return requireLatin1(tan, 'tan');
+}

package/src/session/tan-selection.ts

@@ -1,6 +1,8 @@
-import { FinTsUnsupportedError } from '../core/errors.js';
+import { FinTsTanSetupError } from '../core/errors.js';
 import { TanMethod, type TanMedium } from '../tan/tan-models.js';
-import { noReference, type BankResponse, type PinTanProtocol, type ProtocolDialog } from './protocol.js';
+import { FinTs3Dialog } from '../v3/dialog.js';
+import type { FinTs3Protocol } from '../v3/protocol.js';
+import { noReference } from '../v3/segments.js';
 import type { SessionState } from './session-state.js';
 import type { UserPrompts } from './user-prompts.js';
 
@@ -8,18 +10,18 @@ import type { UserPrompts } from './user-prompts.js';
  * The TAN method and medium the session's messages are signed with, chosen by the user among what the bank offers and
  * the user may use, and kept in the session state.
  */
-export class TanSelection<R extends BankResponse, O> {
-  /** TAN methods whose media were looked up in this session. A lookup is not repeated, even where it gave no medium. */
-  private readonly mediaLookedUp = new Set<string>();
-
-  /** The list the last lookup gave, until `takeLookedUpMedia` hands it out. */
-  private lookedUpMedia: TanMedium[] | undefined;
+export class TanSelection {
+  /**
+   * The lookups of this session that found no medium to choose, by TAN method, with the list each gave; `undefined`
+   * where the bank gave none. Such a lookup is not repeated for its method until `select` or `forgetMedium` drops it.
+   */
+  private readonly lookupsWithoutMedium = new Map<string, TanMedium[] | undefined>();
 
   /** Whether the bank refused a login signed with the one-step method in this session. */
   private oneStepRefused = false;
 
   constructor(
-    private readonly protocol: PinTanProtocol<R, O>,
+    private readonly protocol: FinTs3Protocol,
     private readonly state: SessionState,
     private readonly prompts: UserPrompts,
   ) {}
@@ -28,31 +30,41 @@ export class TanSelection<R extends BankResponse, O> {
   get method(): TanMethod {
     const code = this.state.tanMethod;
     if (code === undefined || code === TanMethod.oneStep.securityFunction) return TanMethod.oneStep;
-    return this.protocol.bankParameters?.tanMethods.find((m) => m.securityFunction === code) ?? TanMethod.oneStep;
+    const methods = this.protocol.parameters.bankParameters?.tanMethods ?? [];
+    return methods.find((m) => m.securityFunction === code) ?? TanMethod.oneStep;
   }
 
   /** Switches to `securityFunction` and `tanMedium` for the dialogs to come. */
   select(securityFunction: string, tanMedium: string | undefined): void {
     this.state.useTanMethod(securityFunction, tanMedium);
-    this.mediaLookedUp.delete(securityFunction);
+    this.lookupsWithoutMedium.delete(securityFunction);
+  }
+
+  /**
+   * Forgets the medium in use and the lookups of this session, so that the next login looks the media up anew where the
+   * method needs one: the bank may have refused the medium, such as that of a phone the user has replaced.
+   */
+  forgetMedium(): void {
+    this.state.useTanMedium(undefined);
+    this.lookupsWithoutMedium.clear();
   }
 
   /**
    * A dialog signed with the TAN method in use and its medium.
    *
-   * Throws `FinTsUnsupportedError` if the method needs a medium the user has not chosen: the bank would refuse the
+   * Throws `FinTsTanSetupError` if the method needs a medium the user has not chosen: the bank would refuse the
    * login, and the client would not send the PIN again.
    */
-  newDialog(): ProtocolDialog<R, O> {
+  newDialog(): FinTs3Dialog {
     const method = this.method;
     if (this.lacksMedium(method)) {
-      throw new FinTsUnsupportedError(
+      throw new FinTsTanSetupError(
         `The TAN method ${method.name} needs a TAN medium, and the client could not learn one: the bank lists no ` +
           'active medium for it, or does not offer or permit the list of TAN media, or rejected it. Pass a medium to ' +
           'selectTanMethod, or choose another method',
       );
     }
-    return this.protocol.newDialog(method, this.state.tanMedium);
+    return FinTs3Dialog.signed(this.protocol, method, this.state.tanMedium);
   }
 
   /**
@@ -61,9 +73,9 @@ export class TanSelection<R extends BankResponse, O> {
    * It runs before the medium is known, so it names a placeholder where the method needs one; the bank ignores the
    * medium in this dialog (PIN/TAN B.4.3.1.3).
    */
-  lookupDialog(): ProtocolDialog<R, O> {
+  lookupDialog(): FinTs3Dialog {
     const method = this.method;
-    return this.protocol.newDialog(method, this.lacksMedium(method) ? noReference : this.state.tanMedium);
+    return FinTs3Dialog.signed(this.protocol, method, this.lacksMedium(method) ? noReference : this.state.tanMedium);
   }
 
   /**
@@ -75,15 +87,15 @@ export class TanSelection<R extends BankResponse, O> {
    *    a one-step login;
    * 3. another two-step method the user may use.
    *
-   * Throws `FinTsUnsupportedError` if none does, before the bank could refuse the login.
+   * Throws `FinTsTanSetupError` if none does, before the bank could refuse the login.
    */
-  synchronizationDialog(): ProtocolDialog<R, O> {
+  synchronizationDialog(): FinTs3Dialog {
     const method = this.method;
-    if (!this.lacksMedium(method)) return this.protocol.newDialog(method, this.state.tanMedium);
-    if (!this.oneStepRefused) return this.protocol.newDialog(TanMethod.oneStep);
+    if (!this.lacksMedium(method)) return FinTs3Dialog.signed(this.protocol, method, this.state.tanMedium);
+    if (!this.oneStepRefused) return FinTs3Dialog.signed(this.protocol, TanMethod.oneStep);
     const other = this.available().find((m) => !m.isOneStep && !this.lacksMedium(m));
-    if (other !== undefined) return this.protocol.newDialog(other);
-    throw new FinTsUnsupportedError(
+    if (other !== undefined) return FinTs3Dialog.signed(this.protocol, other);
+    throw new FinTsTanSetupError(
       `The bank refuses the one-step method, and the TAN method ${method.name} needs a TAN medium, which the client ` +
         'can look up only after the synchronization. Pass the medium to selectTanMethod, or choose another method',
     );
@@ -98,17 +110,17 @@ export class TanSelection<R extends BankResponse, O> {
    * The two-step TAN methods the bank offers, the user may use and this client can run; the one-step method if there
    * are none.
    *
-   * Throws `FinTsUnsupportedError` if the bank offers the user nothing but methods the client cannot run.
+   * Throws `FinTsTanSetupError` if the bank offers the user nothing but methods the client cannot run.
    */
   available(): TanMethod[] {
-    const bpd = this.protocol.bankParameters;
+    const bpd = this.protocol.parameters.bankParameters;
     if (bpd === undefined) return [TanMethod.oneStep];
-    const allowed = this.state.allowedMethods ?? this.protocol.userParameters?.allowedTanMethods;
+    const allowed = this.state.allowedMethods;
     const isAllowed = (securityFunction: string): boolean =>
       allowed === undefined || allowed.length === 0 || allowed.includes(securityFunction);
     const runnable = bpd.tanMethods.filter((m) => isAllowed(m.securityFunction));
     if (runnable.length === 0 && bpd.unsupportedTanMethods.some(isAllowed)) {
-      throw new FinTsUnsupportedError(
+      throw new FinTsTanSetupError(
         'The bank offers only TAN methods this client cannot run: process variant 1, or methods that need an SMS ' +
           'charge account or an HHD_UC answer',
       );
@@ -142,11 +154,11 @@ export class TanSelection<R extends BankResponse, O> {
 
   /**
    * Whether the media of the method in use have to be looked up: it needs a medium the user has not chosen, and they
-   * were not looked up for it in this session.
+   * were not looked up in vain for it in this session.
    */
   get mediumToLookUp(): boolean {
     const method = this.method;
-    return this.lacksMedium(method) && !this.mediaLookedUp.has(method.securityFunction);
+    return this.lacksMedium(method) && !this.lookupsWithoutMedium.has(method.securityFunction);
   }
 
   /**
@@ -155,21 +167,20 @@ export class TanSelection<R extends BankResponse, O> {
    */
   async chooseMedium(media: TanMedium[] | undefined): Promise<void> {
     const method = this.method;
-    this.lookedUpMedia = media;
-    this.state.useTanMedium(media === undefined ? undefined : await this.chooseMediumOf(method, media));
-    this.mediaLookedUp.add(method.securityFunction);
+    const medium = media === undefined ? undefined : await this.chooseMediumOf(method, media);
+    this.state.useTanMedium(medium);
+    if (medium === undefined) this.lookupsWithoutMedium.set(method.securityFunction, media);
   }
 
   /**
-   * The list of the last lookup, once; `undefined` if there was none since the last time.
+   * The list of the lookup that found no medium for the method in use; `undefined` where there was none, or the bank
+   * gave no list.
    *
-   * `getTanMedia` takes it, so that the list is not asked for twice in a row. It also outlasts a call that failed for
-   * want of an active medium, so that the app can show the user the list that tells why; later calls ask anew.
+   * It outlasts the call that failed for want of the medium, so that `getTanMedia` can show the user the list that tells
+   * why: the client neither looks the media up again for the method nor can list them in a dialog without a medium.
    */
-  takeLookedUpMedia(): TanMedium[] | undefined {
-    const media = this.lookedUpMedia;
-    this.lookedUpMedia = undefined;
-    return media;
+  get lookedUpMedia(): TanMedium[] | undefined {
+    return this.lookupsWithoutMedium.get(this.method.securityFunction);
   }
 
   /** The name of the medium the user chooses among the active ones in `media`; `undefined` if none is active. */

package/src/session/user-prompts.ts

@@ -1,16 +1,12 @@
 import type { BankMessage } from '../core/bank-info.js';
 import type { FinTsClientOptions, MessageLogger } from '../core/client.js';
-import { FinTsStateError } from '../core/errors.js';
+import { clientClosedError } from '../core/errors.js';
 import type { FinTsFeedback } from '../core/feedback.js';
-import type { TanAnswer, TanChallenge } from '../tan/challenge.js';
+import { TanAnswer, type 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.
@@ -24,7 +20,7 @@ export class UserPrompts {
   /** 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. */
+  /** Aborts the waits under way; each wait removes its abort when it is over, or when nothing waits for it any more. */
   private readonly aborts = new Set<() => void>();
 
   constructor(private readonly options: FinTsClientOptions) {}
@@ -38,7 +34,7 @@ export class UserPrompts {
 
   /** Throws `FinTsStateError` once `close` was called. */
   checkOpen(): void {
-    if (this.closed) throw closedError();
+    if (this.closed) throw clientClosedError();
   }
 
   /**
@@ -93,14 +89,17 @@ export class UserPrompts {
     }
   }
 
-  /** Shows `challenge` through the TAN callback and returns its answer. */
+  /**
+   * Shows `challenge` through the TAN callback and returns its answer; rejects with `TypeError` for anything but a
+   * `TanAnswer`. Once `TanChallenge.resolved` settles, nothing waits for the answer any more.
+   */
   askTan(challenge: TanChallenge): Promise<TanAnswer> {
-    return this.unlessClosed(() => this.options.tanCallback(challenge));
+    return this.unlessClosed(async () => tanAnswerOf(await this.options.tanCallback(challenge)), challenge.resolved);
   }
 
   /** Waits for `delayMs` milliseconds, or until `interrupt` settles. */
   pause(delayMs: number, interrupt?: Promise<unknown>): Promise<void> {
-    if (this.closed) return Promise.reject(closedError());
+    if (this.closed) return Promise.reject(clientClosedError());
     let timer: ReturnType<typeof setTimeout> | undefined;
     const elapsed = new Promise<void>((resolve) => {
       timer = setTimeout(resolve, Math.max(0, delayMs));
@@ -144,16 +143,20 @@ export class UserPrompts {
   }
 
   /**
-   * Starts `wait` and ends it with `FinTsStateError` if `close` is called before it is over.
+   * Starts `wait` and ends it with `FinTsStateError` if `close` is called before it is over. Once `unwanted` settles,
+   * nothing waits for it any more: it is forgotten then, rather than kept until a callback that never answers does.
    *
    * 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());
+  private unlessClosed<T>(wait: () => T | Promise<T>, unwanted?: Promise<unknown>): Promise<T> {
+    if (this.closed) return Promise.reject(clientClosedError());
     const result = new Deferred<T>();
     const abort = (): void => {
-      result.reject(closedError());
+      result.reject(clientClosedError());
+    };
+    const forget = (): void => {
+      this.aborts.delete(abort);
     };
     this.aborts.add(abort);
     // Runs `wait` at once, as far as its first `await`, and turns an error it throws into a rejection.
@@ -167,8 +170,24 @@ export class UserPrompts {
           result.reject(error);
         },
       )
-      .finally(() => this.aborts.delete(abort))
+      .finally(forget)
       .catch(() => undefined);
+    void unwanted?.then(forget, forget);
     return result.promise;
   }
 }
+
+/**
+ * `answer`, a result of the TAN callback, as a `TanAnswer`; throws `TypeError` for anything else, such as the
+ * `undefined` of a callback that returns nothing. The answer is read once, so that what was checked is what counts.
+ */
+function tanAnswerOf(answer: unknown): TanAnswer {
+  const { kind, tan } = (typeof answer === 'object' && answer !== null ? answer : {}) as {
+    kind?: unknown;
+    tan?: unknown;
+  };
+  if (kind === 'tan' && typeof tan === 'string') return TanAnswer.tan(tan);
+  if (kind === 'approved') return TanAnswer.approved;
+  if (kind === 'cancelled') return TanAnswer.cancelled;
+  throw invalidArgument('Returned no TanAnswer', 'tanCallback');
+}

package/src/tan/challenge.ts

@@ -1,4 +1,6 @@
 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';
@@ -11,7 +13,6 @@ 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;
 
@@ -41,19 +42,9 @@ const namedEntities: Record<string, string> = {
   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.
- */
+/** 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 {
-  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;
+  return characterReference(name) ?? (Object.hasOwn(namedEntities, name) ? namedEntities[name] : undefined);
 }
 
 /** What `TanChallenge` takes. */
@@ -76,10 +67,14 @@ export class TanChallenge {
   /** The TAN method the challenge is for. */
   readonly method: TanMethod;
 
-  /** Bank reference of the pending action. */
+  /** Bank reference of the pending action, one character per byte the bank sent (ISO 8859-1). */
   readonly reference: string;
 
-  /** Challenge text as sent by the bank; may contain simple HTML. See `plainMessage`. */
+  /**
+   * 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). */
@@ -104,13 +99,16 @@ export class TanChallenge {
   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.
+   * 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. Use `TanChallenge.create` to have a flicker code or image detected in the data. */
+  /**
+   * 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;
@@ -119,7 +117,7 @@ export class TanChallenge {
     this.flickerCode = init.flickerCode;
     this.image = init.image;
     this.isDecoupled = init.isDecoupled ?? false;
-    this.validUntil = init.validUntil;
+    this.validUntil = copyDate(init.validUntil);
     this.tanMediumName = init.tanMediumName;
     this.attempt = init.attempt ?? 1;
     this.resolved = init.resolved;
@@ -132,10 +130,7 @@ export class TanChallenge {
     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);
-      }
+      if (image === undefined) flicker = FlickerCode.tryParse(latin1Decode(data));
     } else if (init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
       flicker = FlickerCode.tryParse(init.message);
     }
@@ -163,6 +158,10 @@ export class TanChallenge {
    * 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;
@@ -211,7 +210,10 @@ function copyChallenge(challenge: TanChallenge, changes: Partial<TanChallengeIni
 
 /** 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. */
+  /**
+   * 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' }
@@ -223,7 +225,7 @@ 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. */
+  /** 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,
@@ -234,12 +236,19 @@ export const TanAnswer = Object.freeze({
 /**
  * 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`.
+ * 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.
  *
- * 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.
+ * 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>;