@coderoftime/fints 0.0.0-stage → 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

@@ -0,0 +1,203 @@
+import { FinTsTanSetupError } from '../core/errors.js';
+import { TanMethod, type TanMedium } from '../tan/tan-models.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';
+
+/**
+ * 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 {
+  /**
+   * 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: FinTs3Protocol,
+    private readonly state: SessionState,
+    private readonly prompts: UserPrompts,
+  ) {}
+
+  /** The TAN method in use; the one-step method until one is chosen. */
+  get method(): TanMethod {
+    const code = this.state.tanMethod;
+    if (code === undefined || code === TanMethod.oneStep.securityFunction) return 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.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 `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(): FinTs3Dialog {
+    const method = this.method;
+    if (this.lacksMedium(method)) {
+      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 FinTs3Dialog.signed(this.protocol, method, this.state.tanMedium);
+  }
+
+  /**
+   * The dialog that looks up the TAN media, signed with the TAN method in use.
+   *
+   * 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(): FinTs3Dialog {
+    const method = this.method;
+    return FinTs3Dialog.signed(this.protocol, method, this.lacksMedium(method) ? noReference : this.state.tanMedium);
+  }
+
+  /**
+   * The synchronization dialog. It runs before the TAN media are looked up, so its method must do without a medium the
+   * user has not chosen: the placeholder for one is meant for the lookup only (PIN/TAN B.4.3.1.3). The first method
+   * that does signs it:
+   * 1. the TAN method in use;
+   * 2. the one-step method, as for a user whose methods are not known yet (PIN/TAN B.4.3.1), unless the bank has refused
+   *    a one-step login;
+   * 3. another two-step method the user may use.
+   *
+   * Throws `FinTsTanSetupError` if none does, before the bank could refuse the login.
+   */
+  synchronizationDialog(): FinTs3Dialog {
+    const method = this.method;
+    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 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',
+    );
+  }
+
+  /** Whether `method` needs a medium the user has not chosen. */
+  private lacksMedium(method: TanMethod): boolean {
+    return this.state.tanMedium === undefined && needsMediumChoice(method);
+  }
+
+  /**
+   * 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 `FinTsTanSetupError` if the bank offers the user nothing but methods the client cannot run.
+   */
+  available(): TanMethod[] {
+    const bpd = this.protocol.parameters.bankParameters;
+    if (bpd === undefined) return [TanMethod.oneStep];
+    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 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',
+      );
+    }
+    return runnable.length === 0 ? [TanMethod.oneStep] : runnable;
+  }
+
+  /**
+   * Stops using `rejected`, the method of a login the bank refused; returns whether another available method is left.
+   *
+   * The user chooses that method, unless the one in use is still available: a refused one-step synchronization does
+   * not rule out the method the user chose before.
+   */
+  async replace(rejected: TanMethod): Promise<boolean> {
+    if (rejected.isOneStep) this.oneStepRefused = true;
+    const others = this.available().filter((m) => m.securityFunction !== rejected.securityFunction);
+    if (others.some((m) => m.securityFunction === this.state.tanMethod)) return true;
+    if (others.length === 0) return false;
+    this.state.useTanMethod((await this.prompts.chooseMethod(others)).securityFunction);
+    return true;
+  }
+
+  /** Keeps the chosen TAN method if it is still available, otherwise lets the user choose. */
+  async ensureMethodChosen(): Promise<void> {
+    const candidates = this.available();
+    const method =
+      candidates.find((m) => m.securityFunction === this.state.tanMethod) ??
+      (await this.prompts.chooseMethod(candidates));
+    if (method.securityFunction !== this.state.tanMethod) this.state.useTanMethod(method.securityFunction);
+  }
+
+  /**
+   * 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 in vain for it in this session.
+   */
+  get mediumToLookUp(): boolean {
+    const method = this.method;
+    return this.lacksMedium(method) && !this.lookupsWithoutMedium.has(method.securityFunction);
+  }
+
+  /**
+   * Lets the user choose the medium of the method in use among the active ones in `media`, the result of a lookup;
+   * none where the lookup gave no list or no active medium.
+   */
+  async chooseMedium(media: TanMedium[] | undefined): Promise<void> {
+    const method = this.method;
+    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 lookup that found no medium for the method in use; `undefined` where there was none, or the bank
+   * gave no list.
+   *
+   * 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.
+   */
+  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. */
+  private async chooseMediumOf(method: TanMethod, media: readonly TanMedium[]): Promise<string | undefined> {
+    const active = media.filter((m) => m.isActive && m.name !== undefined);
+    // HITAB version 5 names the method each medium belongs to; a medium of another method would not do.
+    const ofMethod = active.filter((m) => m.securityFunction === method.securityFunction);
+    const candidates = ofMethod.length === 0 ? active : ofMethod;
+    if (candidates.length === 0) return undefined;
+    return (await this.prompts.chooseMedium(candidates)).name;
+  }
+}
+
+/**
+ * Whether messages signed with `method` must name the TAN medium: the method requires the name, and the user may have
+ * several media (PIN/TAN, HKTAN "Bezeichnung des TAN-Mediums").
+ */
+function needsMediumChoice(method: TanMethod): boolean {
+  return method.needsMediumName && (method.activeMediaCount ?? 0) > 1;
+}

package/src/session/user-prompts.ts

@@ -0,0 +1,193 @@
+import type { BankMessage } from '../core/bank-info.js';
+import type { FinTsClientOptions, MessageLogger } from '../core/client.js';
+import { clientClosedError } from '../core/errors.js';
+import type { FinTsFeedback } from '../core/feedback.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';
+
+/**
+ * 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, or when nothing waits for it any more. */
+  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 clientClosedError();
+  }
+
+  /**
+   * 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; 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(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(clientClosedError());
+    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 `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>, unwanted?: Promise<unknown>): Promise<T> {
+    if (this.closed) return Promise.reject(clientClosedError());
+    const result = new Deferred<T>();
+    const abort = (): void => {
+      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.
+    const started = (async (): Promise<T> => wait())();
+    started
+      .then(
+        (value) => {
+          result.resolve(value);
+        },
+        (error: unknown) => {
+          result.reject(error);
+        },
+      )
+      .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');
+}