@coderoftime/fints 0.1.0 → 0.3.0

package/src/v3/message.ts

@@ -2,13 +2,20 @@
 
 import { BankMessage } from '../core/bank-info.js';
 import { FinTsFeedback } from '../core/feedback.js';
-import type { BankResponse } from '../session/protocol.js';
 import { TanMethod } from '../tan/tan-models.js';
-import { base64Encode, BytesBuilder, latin1Decode, latin1Encode } from '../util/bytes.js';
+import { base64Encode, concatBytes, latin1Encode, utf8Decode } from '../util/bytes.js';
 import { formatFintsDate, formatFintsTime } from '../util/dates.js';
 import { FormatError } from '../util/errors.js';
 import { decodeBankText, decodeBase64Lines } from '../util/text.js';
-import { Binary, parseSegments, type Segment, SegmentSpec, type SegmentValue } from './syntax.js';
+import {
+  Binary,
+  parsedElementBytes,
+  parseSegments,
+  type Segment,
+  SegmentSpec,
+  type SegmentValue,
+  Verbatim,
+} from './syntax.js';
 
 /** Signature data of a PIN/TAN message. */
 export interface PinTanCredentials {
@@ -35,7 +42,7 @@ const issuer = 1;
 
 /** Security identification: message sender (MS), empty CID, then the customer system ID. */
 function sender(systemId: string): SegmentValue {
-  return [1, null, systemId];
+  return [1, null, new Verbatim(systemId)];
 }
 
 /** Security reference number, the same in every message. */
@@ -69,10 +76,14 @@ function keyName(c: PinTanCredentials, keyType: string): SegmentValue {
   return [c.countryCode, c.bankCode, c.userId, keyType, 0, 0];
 }
 
-/** A random integer from 0 below `bound`, from a cryptographically secure source. */
+/** A random integer from 0 below `bound`, each equally likely, from a cryptographically secure source. */
 function secureRandom(bound: number): number {
+  // Values from the last multiple of `bound` on cover only the low remainders, which they would make more likely.
+  const limit = 2 ** 32 - (2 ** 32 % bound);
   const values = new Uint32Array(1);
-  crypto.getRandomValues(values);
+  do {
+    crypto.getRandomValues(values);
+  } while (values[0]! >= limit);
   return values[0]! % bound;
 }
 
@@ -85,20 +96,21 @@ function securityControlReference(): string {
 export class OutgoingMessage {
   constructor(
     readonly bytes: Uint8Array,
-    /** The parts of the masked message, each decoded on its own as the bank's text is. */
-    private readonly maskedParts: readonly Uint8Array[],
+    private readonly buildMasked: () => Uint8Array,
   ) {}
 
-  /** The message with PIN and TAN masked; decoded only when a logger asks for it. */
+  /**
+   * The message with PIN and TAN masked; built only when a logger asks for it. It is decoded as a whole, as the bank's
+   * text is, so a message that mixes ISO 8859-1 text with UTF-8 text (`encodeText`) shows all of it as ISO 8859-1.
+   */
   get masked(): string {
-    return this.maskedParts.map(decodeBankText).join('');
+    return decodeBankText(this.buildMasked());
   }
 }
 
-/** The segments between header and trailer, as sent and with PIN and TAN masked, and the number for the trailer. */
+/** The segments between header and trailer, and the number of the trailer. */
 interface Body {
-  readonly bytes: Uint8Array;
-  readonly masked: readonly Uint8Array[];
+  readonly segments: readonly Uint8Array[];
   readonly nextNumber: number;
 }
 
@@ -108,7 +120,8 @@ interface Body {
  * With `security` the segments are signed with PIN and optional `tan` (HNSHK … HNSHA) and wrapped in the encryption
  * envelope (HNVSK, HNVSD) that PIN/TAN uses without actual encryption.
  *
- * The masked message states the sizes of its masked content, so that the log does not tell how long PIN and TAN are.
+ * The masked message is built as the message is, from the same time stamp and security control reference, with `***`
+ * for PIN and TAN, so that the log does not tell how long they are.
  */
 export function buildMessage(parts: {
   dialogId: string;
@@ -118,54 +131,49 @@ export function buildMessage(parts: {
   tan?: string | undefined;
   now?: Date;
 }): OutgoingMessage {
-  const body =
-    parts.security === undefined
-      ? plainBody(parts.segments)
-      : signedBody(parts.segments, parts.security, parts.tan, parts.now ?? new Date());
-  const trailer = new SegmentSpec('HNHBS', 1, [parts.messageNumber]).build(body.nextNumber);
-  // The header states the size of the whole message, itself included; its own size does not depend on it.
-  const header = (size: number): Uint8Array =>
-    new SegmentSpec('HNHBK', 3, [size.toString().padStart(12, '0'), 300, parts.dialogId, parts.messageNumber]).build(1);
-  const sizeOf = (sections: readonly Uint8Array[]): number => header(0).length + lengthOf(sections) + trailer.length;
-  const result = new BytesBuilder();
-  result.add(header(sizeOf([body.bytes])));
-  result.add(body.bytes);
-  result.add(trailer);
-  return new OutgoingMessage(result.takeBytes(), [header(sizeOf(body.masked)), ...body.masked, trailer]);
+  const { security, tan } = parts;
+  if (security === undefined) {
+    const bytes = withHeaderAndTrailer(parts, plainBody(parts.segments));
+    return new OutgoingMessage(bytes, () => bytes);
+  }
+  const time = parts.now ?? new Date();
+  const controlReference = securityControlReference();
+  const build = (pin: string, tanValue: string | undefined): Uint8Array =>
+    withHeaderAndTrailer(parts, signedBody(parts.segments, security, pin, tanValue, time, controlReference));
+  return new OutgoingMessage(build(security.pin, tan), () => build('***', tan === undefined ? undefined : '***'));
 }
 
-/** The number of bytes in `parts` together. */
-function lengthOf(parts: readonly Uint8Array[]): number {
-  return parts.reduce((sum, part) => sum + part.length, 0);
+/** `body` between the header and the trailer of message `messageNumber` of the dialog `dialogId`. */
+function withHeaderAndTrailer(parts: { dialogId: string; messageNumber: number }, body: Body): Uint8Array {
+  const trailer = new SegmentSpec('HNHBS', 1, [parts.messageNumber]).build(body.nextNumber);
+  const header = (size: number): Uint8Array =>
+    new SegmentSpec('HNHBK', 3, [
+      size.toString().padStart(12, '0'),
+      300,
+      new Verbatim(parts.dialogId),
+      parts.messageNumber,
+    ]).build(1);
+  // The header states the size of the whole message, itself included; its own size does not depend on it.
+  const size = header(0).length + body.segments.reduce((sum, s) => sum + s.length, 0) + trailer.length;
+  return concatBytes([header(size), ...body.segments, trailer]);
 }
 
 /** The segments of a message without security, as the anonymous dialog sends them. */
 function plainBody(segments: readonly SegmentSpec[]): Body {
-  const built = segments.map((segment, i) => segment.build(i + 2));
-  const bytes = new BytesBuilder();
-  built.forEach((b) => {
-    bytes.add(b);
-  });
-  return { bytes: bytes.takeBytes(), masked: built, nextNumber: built.length + 2 };
+  return { segments: segments.map((segment, i) => segment.build(i + 2)), nextNumber: segments.length + 2 };
 }
 
-/** The segments signed with PIN and optional `tan`, inside the encryption envelope. */
+/** The segments signed with `pin` and optional `tan`, inside the encryption envelope. */
 function signedBody(
   segments: readonly SegmentSpec[],
   security: PinTanCredentials,
+  pin: string,
   tan: string | undefined,
   time: Date,
+  controlReference: string,
 ): Body {
   const profile = ['PIN', isTwoStep(security) ? 2 : 1];
-  const controlReference = securityControlReference();
-  const inner = new BytesBuilder();
-  const maskedInner: Uint8Array[] = [];
-  const addInner = (built: Uint8Array, masked?: Uint8Array): void => {
-    inner.add(built);
-    maskedInner.push(masked ?? built);
-  };
-
-  addInner(
+  const inner = [
     new SegmentSpec('HNSHK', 4, [
       profile,
       security.securityFunction,
@@ -179,17 +187,10 @@ function signedBody(
       signatureAlgorithm,
       keyName(security, 'S'),
     ]).build(2),
-  );
+  ];
   let number = 3;
-  for (const segment of segments) addInner(segment.build(number++));
-  const signatureEnd = (pin: string, tanValue: string | undefined): SegmentSpec =>
-    new SegmentSpec('HNSHA', 2, [controlReference, null, [pin, tanValue]]);
-  addInner(
-    signatureEnd(security.pin, tan).build(number),
-    signatureEnd('***', tan === undefined ? undefined : '***').build(number),
-  );
-
-  const innerBytes = inner.takeBytes();
+  for (const segment of segments) inner.push(segment.build(number++));
+  inner.push(new SegmentSpec('HNSHA', 2, [controlReference, null, [pin, tan]]).build(number));
   const encryptionHead = new SegmentSpec('HNVSK', 3, [
     profile,
     plainText,
@@ -200,20 +201,12 @@ function signedBody(
     keyName(security, 'V'),
     noCompression,
   ]).build(998);
-  const bytes = new BytesBuilder();
-  bytes.add(encryptionHead);
-  bytes.add(new SegmentSpec('HNVSD', 1, [new Binary(innerBytes)]).build(999));
-  const masked = [
-    encryptionHead,
-    latin1Encode(`HNVSD:999:1+@${lengthOf(maskedInner)}@`),
-    ...maskedInner,
-    latin1Encode("'"),
-  ];
-  return { bytes: bytes.takeBytes(), masked, nextNumber: number + 1 };
+  const encryptedData = new SegmentSpec('HNVSD', 1, [new Binary(concatBytes(inner))]).build(999);
+  return { segments: [encryptionHead, encryptedData], nextNumber: number + 1 };
 }
 
 /** A received message, with the segments of the encryption envelope unpacked. */
-export class IncomingMessage3 implements BankResponse {
+export class IncomingMessage3 {
   /**
    * Return codes for the whole message (HIRMG), then for single request segments (HIRMS).
    *
@@ -222,10 +215,12 @@ export class IncomingMessage3 implements BankResponse {
    */
   readonly feedback: readonly FinTsFeedback[];
 
+  /** Whether the bank rejected the message as a whole (an error in HIRMG), rather than single orders in it. */
   readonly messageRejected: boolean;
 
   private constructor(
     readonly segments: readonly Segment[],
+    /** The memory the message holds, in bytes: its length, and what its parts take beyond that. */
     readonly size: number,
   ) {
     this.feedback = Object.freeze(
@@ -238,34 +233,95 @@ export class IncomingMessage3 implements BankResponse {
   }
 
   /**
-   * Parses a message; throws `FormatError` if `data` is not a FinTS message, such as the HTML page of a proxy or a
-   * maintenance notice.
+   * Parses a message; throws `FormatError` if `data` is not one complete FinTS message, such as the HTML page of a
+   * proxy, a maintenance notice, a message cut short, which lacks the message trailer (HNHBS) at its end, or two
+   * messages run together, whose second would pass for part of the first. It does as well for more than one encrypted
+   * part (HNVSD), each of which `parseSegments` would allow as many data elements as the whole message.
+   *
+   * Its `size` counts the memory of the data elements it keeps along with its bytes, since a message of many short
+   * elements takes far more memory than bytes.
    */
   static parse(data: Uint8Array): IncomingMessage3 {
-    const outer = parseSegments(data);
+    let outer: Segment[] = [];
+    try {
+      outer = parseSegments(data);
+    } catch (error) {
+      // Text that is no FinTS message, such as a web page, seldom ends with a segment terminator; that it has no
+      // message header says more than what the parser trips over first.
+      if (!(error instanceof FormatError) || startsWithMessageHeader(data)) throw error;
+    }
     if (outer[0]?.type !== 'HNHBK') throw new FormatError('Not a FinTS message: no message header');
+    if (outer.at(-1)?.type !== 'HNHBS') throw new FormatError('Incomplete FinTS message: no message trailer');
+    if (outer.filter((s) => s.type === 'HNHBK' || s.type === 'HNHBS').length > 2) {
+      throw new FormatError('More than one FinTS message');
+    }
+    if (outer.filter((s) => s.type === 'HNVSD').length > 1) {
+      throw new FormatError('More than one encrypted part (HNVSD)');
+    }
     const segments: Segment[] = [];
     for (const s of outer) {
-      if (s.type === 'HNVSD') {
-        const payload = s.binary(1);
-        if (payload !== undefined) segments.push(...parseSegments(payload));
-      } else {
+      if (s.type !== 'HNVSD') {
         segments.push(s);
+        continue;
       }
+      const payload = s.binary(1);
+      if (payload === undefined) throw new FormatError('Encrypted data (HNVSD) without binary data');
+      for (const inner of parseSegments(payload)) segments.push(inner);
     }
-    return new IncomingMessage3(segments, data.length);
+    let elements = 0;
+    for (const s of segments) for (const group of s.elements) elements += group.length;
+    return new IncomingMessage3(segments, data.length + elements * parsedElementBytes);
   }
 
   static combine(first: IncomingMessage3, second: IncomingMessage3): IncomingMessage3 {
     return new IncomingMessage3([...first.segments, ...second.segments], first.size + second.size);
   }
 
+  /** Free-text messages the bank addresses to the user. */
   get bankMessages(): BankMessage[] {
     return this.findAll('HIKIM').map((m) => new BankMessage(m.text(1) ?? '', m.text(2) ?? ''));
   }
 
+  /** The dialog ID the bank assigned, as `Segment.verbatim` reads it, to send back byte for byte. */
   get dialogId(): string | undefined {
-    return this.find('HNHBK')?.text(3);
+    return this.find('HNHBK')?.verbatim(3);
+  }
+
+  /**
+   * Whether the message answers message `number` of the dialog `dialogId`: header and trailer carry that number, and the
+   * header names that message where it names the message it refers to (Bezugsnachricht). The dialog ID counts only once
+   * the bank has assigned one; before, `dialogId` is `undefined`, since every first message goes out under the same.
+   */
+  answers(number: number, dialogId: string | undefined): boolean {
+    const header = this.find('HNHBK');
+    // The trailer comes last, after the segments of the encryption envelope, which might hold one of their own.
+    const trailer = this.segments.at(-1);
+    if (header === undefined || trailer?.type !== 'HNHBS') return false;
+    const inDialog = (id: string | undefined): boolean => dialogId === undefined || id === dialogId;
+    const namesReference = header.group(5).some((e) => !e.isEmpty);
+    return (
+      header.integer(4) === number &&
+      trailer.integer(1) === number &&
+      inDialog(header.verbatim(3)) &&
+      (!namesReference || (header.integer(5, 1) === number && inDialog(header.verbatim(5, 0))))
+    );
+  }
+
+  /**
+   * Whether the message is the bank's dialog abort message (Formals B.7.6) for message `number` of the dialog
+   * `dialogId`: unencrypted, with nothing but the header, an error for the whole message (HIRMG) and the trailer. Its
+   * header names the dialog ID and the message number where the bank knows them, and `unbekannt` and 9999 where not.
+   */
+  aborts(number: number, dialogId: string | undefined): boolean {
+    const header = this.segments[0]!;
+    const id = header.verbatim(3);
+    const messageNumber = header.integer(4);
+    return (
+      this.segments.length === 3 &&
+      this.messageRejected &&
+      (id === 'unbekannt' || id === dialogId) &&
+      (messageNumber === 9999 || messageNumber === number)
+    );
   }
 
   find(type: string): Segment | undefined {
@@ -277,6 +333,10 @@ export class IncomingMessage3 implements BankResponse {
   }
 }
 
+/**
+ * The return codes of `s`. Their parameters are values the client or the app sends back, such as the position to
+ * continue at or new login data, so they are read as `Segment.verbatim` reads them.
+ */
 function feedbackOf(s: Segment): FinTsFeedback[] {
   const feedback: FinTsFeedback[] = [];
   for (let i = 1; i < s.length; i++) {
@@ -284,7 +344,7 @@ function feedbackOf(s: Segment): FinTsFeedback[] {
     if (code === undefined) continue;
     const parameters: string[] = [];
     // Empty parameters stay, as empty text, so that each keeps its position.
-    for (let j = 3; j < s.group(i).length; j++) parameters.push(s.text(i, j) ?? '');
+    for (let j = 3; j < s.group(i).length; j++) parameters.push(s.verbatim(i, j) ?? '');
     feedback.push(new FinTsFeedback({ code, reference: s.text(i, 1), text: s.text(i, 2) ?? '', parameters }));
   }
   return feedback;
@@ -298,7 +358,8 @@ function feedbackOf(s: Segment): FinTsFeedback[] {
 export function decodeTransport(body: Uint8Array): Uint8Array {
   if (startsWithMessageHeader(body)) return body;
   try {
-    return decodeBase64Lines(latin1Decode(body));
+    // Base64 is ASCII, which UTF-8 decodes natively; anything else is no base64 either way.
+    return decodeBase64Lines(utf8Decode(body, true));
   } catch (error) {
     if (error instanceof FormatError) return body;
     throw error;

package/src/v3/parameter-store.ts

@@ -0,0 +1,226 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { FinTsConfig } from '../core/config.js';
+import { FormatError } from '../util/errors.js';
+import { readOptionalBoolean, readOptionalObject, readOptionalString, type JsonObject } from '../util/json.js';
+import { trimBlanks } from '../util/text.js';
+import type { IncomingMessage3 } from './message.js';
+import { Bpd3, decodeSegments, Upd3 } from './parameters.js';
+import { Verbatim } from './syntax.js';
+
+/** The limits the bank parameter data set on the messages the client sends (`ParameterStore.limits`). */
+export interface MessageLimits {
+  /** The shortest and longest PIN a login may carry. */
+  readonly pinLength: { readonly min: number | undefined; readonly max: number | undefined } | undefined;
+
+  /** The size of the largest message, in kilobytes. */
+  readonly maxMessageSize: number | undefined;
+}
+
+/**
+ * The parameter data and IDs the bank sends the user `config` names, which the messages and business transactions
+ * take, and which the saved state keeps: the bank and user parameter data, the customer system ID, and the names of
+ * the TAN media as the bank sent them.
+ */
+export class ParameterStore {
+  private systemIdValue: string | undefined;
+  private bpd: Bpd3 | undefined;
+
+  /**
+   * Whether the bank parameter data came from the anonymous dialog. They serve until those of a dialog signed with the
+   * PIN come: the bank may send a user other ones (PIN/TAN B.4.3.1), and the anonymous dialog may have had to do
+   * without the announcement of strong customer authentication. So signed dialogs report version 0 for them, which has
+   * the bank send its parameter data anew.
+   */
+  private bpdAnonymous = false;
+
+  /** The limits a refresh took from the anonymous dialog's parameter data (`keepRefreshedLimits`). */
+  private refreshedLimits: MessageLimits | undefined;
+  private upd: Upd3 | undefined;
+
+  /**
+   * The names of the TAN media in the bank's last list whose text would not go back as the bank sent them, by their
+   * text, as `parseTanMedia` notes them (`readTanMediumNames` for a state of 0.2.0). Saved with the state, as the
+   * medium in use is.
+   */
+  private tanMediumNames = new Map<string, string>();
+
+  constructor(readonly config: FinTsConfig) {}
+
+  /** The bank parameter data received so far, if any. */
+  get bankParameters(): Bpd3 | undefined {
+    return this.bpd;
+  }
+
+  /** The user parameter data received so far, if any. */
+  get userParameters(): Upd3 | undefined {
+    return this.upd;
+  }
+
+  /**
+   * The customer system ID the bank assigned in the synchronization, as `Segment.verbatim` reads it; `undefined`
+   * before. No dialog signed with the PIN starts without it.
+   */
+  get systemId(): string | undefined {
+    return this.systemIdValue;
+  }
+
+  /**
+   * The limits on the messages the client sends: those of the bank parameter data, unless a refresh took others
+   * (`keepRefreshedLimits`).
+   */
+  get limits(): MessageLimits {
+    const bpd = this.bpd;
+    return this.refreshedLimits ?? { pinLength: bpd?.pinTan.pinLength, maxMessageSize: bpd?.bankInfo.maxMessageSize };
+  }
+
+  /**
+   * The version of the bank parameter data a dialog reports: 0 where there are none, only the anonymous dialog's, or
+   * where limits a refresh took stand in for theirs (`keepRefreshedLimits`).
+   */
+  get reportedBpdVersion(): number {
+    return this.bpd === undefined || this.bpdAnonymous || this.refreshedLimits !== undefined ? 0 : this.bpd.version;
+  }
+
+  /**
+   * The version of the user parameter data a signed dialog reports: 0 where there are none, or where they name another
+   * user ID than the one logging in, so that the bank sends the user's anew. They may be another user's, as where a
+   * relay mixed up the answers to the synchronizations of two users and the bank takes the other user's customer system
+   * ID. A bank that names the user by another ID than the login's, such as for an alias, only sends its user parameter
+   * data at every login.
+   */
+  get reportedUpdVersion(): number {
+    const upd = this.upd;
+    return upd !== undefined && upd.userId === this.config.userId ? upd.version : 0;
+  }
+
+  /**
+   * Drops the customer system ID the bank no longer accepts, so that a synchronization is required again, and with it
+   * the user parameter data, which the next login delivers anew: what came along with an ID the bank does not know may
+   * not be the user's either (`reportedUpdVersion`). Returns whether there was an ID.
+   */
+  forgetSystemId(): boolean {
+    const had = this.systemIdValue !== undefined;
+    this.systemIdValue = undefined;
+    this.upd = undefined;
+    return had;
+  }
+
+  /**
+   * Keeps the parameter data and IDs in `response`, an answer to the opening of a signed dialog: the login, which may be
+   * a synchronization, or its approval. The bank sends them there (Formals C.3.1); taken from the answer to an order,
+   * the parameter data a bank repeats there in part would replace the complete ones.
+   */
+  keep(response: IncomingMessage3): void {
+    this.keepBankParameters(response, false);
+    this.upd = Upd3.fromSegments(response.segments, this.config.bankCode, this.config.countryCode) ?? this.upd;
+    this.systemIdValue = response.find('HISYN')?.verbatim(1) ?? this.systemIdValue;
+  }
+
+  /**
+   * Keeps the bank parameter data in `response`, the answer of an anonymous dialog, where there are none from a dialog
+   * signed with the PIN: until those come, the dialogs signed with the PIN have the bank send its parameter data anew,
+   * since it may send a user other ones (PIN/TAN B.4.3.1). Keeps nothing that belongs to a user.
+   */
+  keepAnonymous(response: IncomingMessage3): void {
+    if (this.bpd === undefined || this.bpdAnonymous) this.keepBankParameters(response, true);
+  }
+
+  /**
+   * Keeps the limits of the bank parameter data in `response`, the answer of an anonymous dialog the client asked for
+   * after the limits kept ruled out a login: those may be outdated, as saved ones are. Parameter data of the version
+   * kept tell nothing new, and the bank may send a user other ones than the anonymous dialog (PIN/TAN B.4.3.1), so of
+   * those of another version it keeps the limits only, and the PIN lengths only where they state them (HIPINS). They
+   * stand in for those kept until a dialog signed with the PIN brings parameter data.
+   */
+  keepRefreshedLimits(response: IncomingMessage3): void {
+    const fresh = Bpd3.fromSegments(response.segments, this.config.bankCode);
+    if (fresh === undefined || fresh.version === this.bpd?.version) return;
+    this.refreshedLimits = {
+      pinLength: fresh.pinTan.pinLength ?? this.limits.pinLength,
+      maxMessageSize: fresh.bankInfo.maxMessageSize,
+    };
+  }
+
+  private keepBankParameters(response: IncomingMessage3, anonymous: boolean): void {
+    const bpd = Bpd3.fromSegments(response.segments, this.config.bankCode);
+    if (bpd === undefined) return;
+    this.bpd = bpd;
+    this.bpdAnonymous = anonymous;
+    this.refreshedLimits = undefined;
+  }
+
+  /** Keeps `names`, the names of the bank's latest list of TAN media as `parseTanMedia` notes them. */
+  keepTanMediumNames(names: Map<string, string>): void {
+    this.tanMediumNames = names;
+  }
+
+  /**
+   * The TAN medium `name` to send: as the bank sent it, where its last list of TAN media noted that (`parseTanMedia`);
+   * otherwise as text, which goes out without the blanks at either end a name the app passes may have.
+   */
+  tanMediumToSend(name: string): string | Verbatim {
+    const asSent = this.tanMediumNames.get(name);
+    return asSent === undefined ? name : new Verbatim(asSent);
+  }
+
+  /** The parameter data and IDs as JSON data, for the client's saved state. */
+  saveState(): JsonObject {
+    return {
+      systemId: this.systemIdValue ?? null,
+      bpd: this.bpd?.encoded ?? null,
+      bpdAnonymous: this.bpdAnonymous,
+      upd: this.upd?.encoded ?? null,
+      tanMediumNames: Object.fromEntries(this.tanMediumNames),
+      [blanksNotedKey]: true,
+    };
+  }
+
+  /**
+   * Restores what `saveState` saved, with `tanMedium`, the medium in use the state holds; throws if `saved` is damaged,
+   * leaving the store unchanged.
+   */
+  restoreState(saved: JsonObject, tanMedium?: string): void {
+    const bpd = readOptionalString(saved, 'bpd');
+    const upd = readOptionalString(saved, 'upd');
+    const restoredSystemId = readOptionalString(saved, 'systemId');
+    // A state of fints-ts 0.1 or the Dart package 0.2.0 does not tell, so its parameter data are fetched anew.
+    const restoredBpdAnonymous = readOptionalBoolean(saved, 'bpdAnonymous') ?? true;
+    const restoredBpd = bpd === undefined ? undefined : Bpd3.fromSegments(decodeSegments(bpd), this.config.bankCode);
+    const restoredUpd =
+      upd === undefined
+        ? undefined
+        : Upd3.fromSegments(decodeSegments(upd), this.config.bankCode, this.config.countryCode);
+    const restoredNames = readTanMediumNames(saved, tanMedium);
+    this.systemIdValue = restoredSystemId;
+    this.bpd = restoredBpd;
+    this.bpdAnonymous = restoredBpdAnonymous;
+    this.refreshedLimits = undefined;
+    this.upd = restoredUpd;
+    this.tanMediumNames = restoredNames;
+  }
+}
+
+/** The key of the saved state that tells the TAN medium names apart from those version 0.2.0 saved. */
+const blanksNotedKey = 'tanMediumBlanksNoted';
+
+/**
+ * The TAN medium names `saveState` saved; none in a state of fints-ts 0.1 or the Dart package 0.2.0.
+ *
+ * Version 0.2.0 noted no name with blanks at either end, and sent every name as it is, so `tanMedium` keeps going out
+ * with its blanks from such a state: the bank may have listed it so.
+ */
+function readTanMediumNames(saved: JsonObject, tanMedium: string | undefined): Map<string, string> {
+  const listed = readOptionalObject(saved, 'tanMediumNames');
+  const names = new Map(
+    Object.entries(listed ?? {}).map(([name, asSent]) => {
+      if (typeof asSent !== 'string') throw new FormatError('Saved state: a TAN medium name is not a string');
+      return [name, asSent];
+    }),
+  );
+  const savedBy020 = listed !== undefined && readOptionalBoolean(saved, blanksNotedKey) !== true;
+  if (savedBy020 && tanMedium !== undefined && trimBlanks(tanMedium) !== tanMedium && !names.has(tanMedium)) {
+    names.set(tanMedium, tanMedium);
+  }
+  return names;
+}