@coderoftime/fints 0.1.0 → 0.3.0

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,15 +1,18 @@
 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 { optionalFunction, requireFunction } from '../util/arguments.js';
 import { Deferred } from '../util/async.js';
 import { invalidArgument } from '../util/errors.js';
 
-function closedError(): FinTsStateError {
-  return new FinTsStateError('The FinTS client is closed');
-}
+/** The callbacks of `FinTsClientOptions`. */
+type Callbacks = Pick<
+  FinTsClientOptions,
+  'tanCallback' | 'tanMethodSelector' | 'tanMediumSelector' | 'onBankMessage' | 'onWarning' | 'logger'
+>;
 
 /**
  * Everything a session tells the app, asks of it or waits for: the bank's messages, warnings and log, the TAN callback,
@@ -24,10 +27,28 @@ 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) {}
+  /** The callbacks as the client was built with them, as in the Dart package, whose options are final. */
+  private readonly options: Callbacks;
+
+  /**
+   * Throws `TypeError` for a `tanCallback` that is no function, and for another callback that is neither a function
+   * nor `undefined` or `null`, which mean none.
+   */
+  constructor(options: FinTsClientOptions) {
+    const tanCallback = requireFunction(options.tanCallback, 'tanCallback');
+    this.options = {
+      // Called on the app's options, which a callback written as a method of them may refer to as `this`.
+      tanCallback: (challenge) => tanCallback.call(options, challenge),
+      tanMethodSelector: optionalFunction(options.tanMethodSelector, 'tanMethodSelector'),
+      tanMediumSelector: optionalFunction(options.tanMediumSelector, 'tanMediumSelector'),
+      onBankMessage: optionalFunction(options.onBankMessage, 'onBankMessage'),
+      onWarning: optionalFunction(options.onWarning, 'onWarning'),
+      logger: optionalFunction(options.logger, 'logger'),
+    };
+  }
 
   /** Ends every wait; the client calls it once. */
   close(): void {
@@ -38,7 +59,7 @@ export class UserPrompts {
 
   /** Throws `FinTsStateError` once `close` was called. */
   checkOpen(): void {
-    if (this.closed) throw closedError();
+    if (this.closed) throw clientClosedError();
   }
 
   /**
@@ -93,14 +114,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));
@@ -122,7 +146,7 @@ export class UserPrompts {
     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]!;
+    if (chosen === undefined || chosen === null) 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;
@@ -137,23 +161,27 @@ export class UserPrompts {
     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]!;
+    if (chosen === undefined || chosen === null) 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.
+   * 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 +195,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,7 @@
 import { latin1Decode } from '../util/bytes.js';
+import { copyDate } from '../util/dates.js';
+import { frozenWithInspect, inspectCustom } from '../util/inspect.js';
+import { characterReference, trimBlanks } 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 +14,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;
 
@@ -24,6 +26,9 @@ 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;
 
+/** Longest challenge `plainMessage` formats: far longer than the specification allows (an..2048). */
+const maxFormattedLength = 65_536;
+
 const namedEntities: Record<string, string> = {
   amp: '&',
   lt: '<',
@@ -41,19 +46,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 +71,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 +103,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 +121,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,12 +134,10 @@ 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);
-      }
-    } else if (init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
-      flicker = FlickerCode.tryParse(init.message);
+      if (image === undefined) flicker = FlickerCode.tryParse(latin1Decode(data));
+    }
+    if (image === undefined && init.message !== undefined && hasEmbeddedFlickerCode(init.message)) {
+      flicker ??= FlickerCode.tryParse(init.message);
     }
     return new TanChallenge({
       ...init,
@@ -162,25 +162,43 @@ export class TanChallenge {
    * 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.
+   * which is how the specification wants it shown. So does a structured challenge of more than 65,536 characters.
+   *
+   * 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();
+    if (!this.method.structuredChallenge || instruction.length > maxFormattedLength) return instruction;
+    return trimBlanks(
+      instruction
+        .replace(lineBreak, '\n')
+        .replace(blockTag, '\n')
+        .replace(formattingTag, '')
+        .replace(entityReference, (match, name: string) => decodeEntity(name) ?? match)
+        .replace(blankLines, '\n\n'),
+    );
+  }
+
+  /**
+   * What Node.js's `util.inspect` and `console.log` show: the method, the kind of challenge and the attempt; not the
+   * text, the reference, the challenge data, the image or the medium, which may name the user, the account or the order.
+   */
+  [inspectCustom](): string {
+    const kinds = [
+      ...(this.isDecoupled ? ['decoupled'] : []),
+      ...(this.flickerCode === undefined ? [] : ['flicker code']),
+      ...(this.image === undefined ? [] : ['image']),
+    ];
+    return `TanChallenge(${[this.method.toString(), ...kinds, `attempt ${this.attempt}`].join(', ')})`;
   }
 }
 
 // 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.
+// API. The own fields of a challenge are those of `TanChallengeInit`, so a copy spreads it.
 
 /** `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 {
@@ -193,38 +211,34 @@ export function withResolved(challenge: TanChallenge, resolved: Promise<void>):
 }
 
 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,
-  });
+  const init: TanChallengeInit = challenge;
+  return new TanChallenge({ ...init, ...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. */
+  /**
+   * The TAN the user entered; an empty one cancels a TAN challenge. Blanks around it do not count, and full-width
+   * characters, as East Asian input methods type them, count as their ASCII counterparts.
+   */
   | { 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' });
+/** `answer` frozen, which `util.inspect` shows by its kind, never with the TAN. */
+function frozenAnswer(answer: TanAnswer): TanAnswer {
+  return frozenWithInspect(answer, (a) => `TanAnswer(${a.kind})`);
+}
+
+const approvedAnswer = frozenAnswer({ kind: 'approved' });
+const cancelledAnswer = frozenAnswer({ 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 TAN the user entered; an empty one cancels a TAN challenge (`TanAnswer`). */
+  tan: (tan: string): TanAnswer => frozenAnswer({ 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`. */
@@ -234,19 +248,28 @@ 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>;
 
-/** Picks one of several allowed TAN methods; the first is used when this returns `undefined`. */
+/** Picks one of several allowed TAN methods; the first is used when this returns `undefined` or `null`. */
 export type TanMethodSelector = (
   methods: readonly TanMethod[],
-) => TanMethod | undefined | Promise<TanMethod | undefined>;
+) => TanMethod | null | undefined | Promise<TanMethod | null | 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>;
+/** Picks one of several active TAN media; the first is used when this returns `undefined` or `null`. */
+export type TanMediumSelector = (
+  media: readonly TanMedium[],
+) => TanMedium | null | undefined | Promise<TanMedium | null | undefined>;