@coderoftime/fints 0.1.0 → 0.3.0

package/README.md

@@ -2,25 +2,25 @@
 
 A FinTS 3.0 client for German banks, written in TypeScript, without runtime dependencies. It reads accounts, balances and transactions with PIN/TAN, including PSD2 strong customer authentication and app approval (pushTAN, SecureGo plus and the like).
 
-It is a port of the Dart package [`fints`](https://pub.dev/packages/fints) and behaves the same: same session logic, same safeguards, same tests. FinTS 4.1, which hardly any bank offers, is not part of the port.
+It is a port of the Dart package [`fints`](https://pub.dev/packages/fints) (see [Differences from the Dart package](#differences-from-the-dart-package)). FinTS 4.1, which hardly any bank offers, is not part of the port.
 
 ## Features
 
 - **PIN/TAN** with the one-step method (`999`) and two-step methods of process variant 2 (`HKTAN` process 4, then 2 or `S`).
 - **Strong customer authentication** at login and per transaction where the bank asks for it, including exemptions (`3076`).
-- **App approval** (decoupled), polled by the bank's own parameters; the client stops when the app is closed or the user cancels.
-- **TAN media** lookup and selection, **chipTAN flicker codes** (HHD 1.3 and 1.4, as frames to animate) and **photoTAN/QR images** (as `data:` URLs).
+- **App approval** (decoupled), polled as the bank's parameters say, for 10 minutes at most; the client stops when the app is closed or the user cancels.
+- **TAN media** lookup and selection, **chipTAN flicker codes** (HHD 1.3 and 1.4, as frames to animate) and **photoTAN/QR images** (PNG, JPEG, GIF, WebP or BMP, as `data:` URLs for an `<img>`).
 - **Balances** (`HKSAL` 6–8) and **transactions** as camt.052 (`HKCAZ`) or MT940/MT942 (`HKKAZ` 6–7), with automatic paging.
 - **IBAN and BIC** from the SEPA account list (`HKSPA`), and the account extension of the user parameter data.
-- **Safe by default**: the PIN is never sent again after the bank refused a login, so a retrying app cannot lock the access; only what the bank's parameter data permit is sent; PIN and TAN are masked in every log.
-- **Saved sessions**: bank and user parameters, customer system ID and the chosen TAN method in one state string, which spares the setup steps at the next start.
-- Parsers for MT940 (German structured `:86:` fields, SEPA keywords) and camt.052/053.
+- **Safe by default**: after a refused login the PIN is not sent again until the user enters it anew, also by a client restored from the saved state (see [Refused logins](#refused-logins)); only what the bank's parameter data permit is sent; PIN and TAN are masked in every log.
+- **Saved sessions**: bank and user parameters, customer system ID, the chosen TAN method and a refused login in one state string, which spares the setup steps at the next start.
+- Parsers for MT940 (German structured `:86:` fields, SEPA keywords) and camt.052/053/054, statement by statement with the account each is for (`Mt940.parse`, `Camt.parse`), or as one list of transactions (`parseTransactions`).
 
 ## Requirements
 
 1. **A FinTS product registration.** German banks only accept registered products. Register for free with the Deutsche Kreditwirtschaft at <https://www.fints.org/de/hersteller/produktregistrierung> and pass the ID as `productId`. Keep it out of your repository.
 2. **Your bank's FinTS URL and bank code (BLZ)**, for example from the DK institute list.
-3. **A runtime with `fetch`, Web Crypto and `TextDecoder`**: Node.js 22.12 or later, Deno, Bun, or a browser behind a server of your own (see [Using it with Vue](#using-it-with-vue)). The type declarations need TypeScript 5.6 or later.
+3. **A runtime with `fetch`, Web Crypto and `TextDecoder`**: Node.js from 22.12, Deno from 2.1, Bun from 1.2.6, or a browser behind a server of your own (see [Using it with Vue](#using-it-with-vue)). The type declarations use the global `URL`, `AbortSignal` and `fetch` types: include the TypeScript lib `DOM` or `@types/node`.
 
 ## Usage
 
@@ -44,11 +44,13 @@ const client = new FinTs3Client({
     onWarning: (warning) => showNotice(warning.code, warning.text), // banks want code and text shown
     tanCallback: async (challenge) => {
       if (challenge.isDecoupled) {
-        // Close the prompt when challenge.resolved settles; offer "approved" only if challenge.manualConfirmation.
+        // Close the prompt when challenge.resolved settles; the bank's new instructions come with the next call.
+        // Offer "approved" only if challenge.manualConfirmation.
         const confirmed = await showApprovalPrompt(challenge);
         return confirmed ? TanAnswer.approved : TanAnswer.cancelled;
       }
-      // Show challenge.plainMessage, challenge.image?.toDataUrl() or challenge.flickerCode?.frames().
+      // Show challenge.plainMessage as text (textContent, never innerHTML), challenge.image?.toDataUrl() in an
+      // <img>, or challenge.flickerCode?.frames().
       const tan = await askForTan(challenge);
       return tan === undefined ? TanAnswer.cancelled : TanAnswer.tan(tan);
     },
@@ -60,12 +62,25 @@ try {
   const balance = await client.getBalance(accounts[0]!);
   const transactions = await client.getTransactions(accounts[0]!, { from: new Date(2024, 0, 1) });
 } finally {
-  saveEncrypted(client.state); // no PIN or TAN, but account data
-  await client.close();
+  try {
+    await client.close();
+  } finally {
+    saveEncrypted(client.state); // after close, whose answers may change it; no PIN or TAN, but login and account data
+  }
 }
 ```
 
-All calls share one bank dialog, so the user approves once per session. Calls run one after another; a call from inside a callback would wait for itself, so on Node.js, Deno and Bun it fails with `FinTsStateError` (in browsers it is not detected).
+A call logs in where it needs to, which sends the PIN and may ask the callbacks for a TAN method, a TAN medium and an approval; so does `getTanMethods` of a client without saved state. Calls share one bank dialog while it is open, so the approval of its login serves them all. The next call logs in anew, which may ask for another approval, once the dialog has idled longer than the bank allows (`BankInfo.maxTimeout`, 5 minutes where it states none), after `selectTanMethod` and `clearLoginRefusal`, once the bank has ended the dialog, and after a message failed with another error than a `FinTsBankError`, such as a cancelled or timed-out approval, a failing `tanCallback`, or a lost or unreadable answer. A query may need an approval of its own, such as one for transactions older than 90 days, and so may up to three of its further pages; where a fourth asks for one, the call fails with `FinTsProtocolError` before the user is asked.
+
+Calls run one after another. A callback must not wait for another call of its client, which would wait for the running call: on Node.js, Deno and Bun such a call fails with `FinTsStateError`, in browsers it waits forever.
+
+A saved state belongs to one client at a time. Run the clients of one bank user one after another, each restored from the state the one before saved, for example behind a lock or a queue per user, never two at once from the same state, such as for two browser tabs: the state saved last wins, and could lift a refused login the other client saved.
+
+Never log the client: `JSON.stringify` and Node.js's `console.log` leave out the PIN, which the client keeps in a private field until it is closed or the login refused, but a debugger and the browser's DevTools show it.
+
+`console.log` and `util.inspect` on Node.js, Deno and Bun show the objects of this package only by what identifies no person, account or TAN: codes, kinds, counts, dates and the last digits of an IBAN or card number, such as `Account(…3000, Girokonto)`, `TanChallenge(TanMethod(942, pushTAN), decoupled, attempt 1)` or `FinTsFeedback(9010)`. They leave out the bank's texts, references and parameters, TAN media names, TANs, challenge data and images, login data, and the amounts of balances and transactions; an `Amount` on its own shows as its `toString`, such as `-123.45 EUR`. `toString` of a `FinTsFeedback` and of a `BankMessage` leaves out the bank's texts as well: show `code` and `text`, or `subject` and `text`, to the user. An error shows its message and stack, and a `FinTsTransportError` its `statusCode`, also where Node.js reports it uncaught; the message of a `FinTsBankError`, and so its stack, holds the bank's texts and parameters of its errors, such as an IBAN, so log its `codes` instead. `JSON.stringify` and the browser console show every field, IBANs, names, amounts, purposes and the TAN of a `TanAnswer` included, so that a server can pass the data to its own front end: neither belongs in logs. Only `JSON.stringify` of an error leaves out the `feedback` of a `FinTsBankError` and the `source` of a `FormatError`.
+
+An account the app builds itself, such as `new Account({ bankCode, iban })`, stands for the account of `getAccounts` it matches by IBAN or account number, whose details and permitted transactions the queries take. One the bank names nowhere goes out with what identifies it only, and fails with `FinTsUnsupportedError` where the bank's lists of permitted transactions are complete.
 
 Calendar dates, such as `Transaction.bookingDate`, are `Date`s at local midnight, of which only the day counts. Moments, such as `Balance.bookedAsOfTime`, are exact; the bank states them in German time.
 
@@ -75,29 +90,63 @@ Calendar dates, such as `Transaction.bookingDate`, are `Date`s at local midnight
 
 There are three ways to set it up:
 
-1. **The client runs on your server** (Nuxt server routes, Express, …). The Vue app calls your own API; the server keeps one `FinTs3Client` per session and passes the TAN challenges to the browser, for example with a pending request the browser answers. This keeps the bank traffic and the product ID on the server.
+1. **The client runs on your server** (Nuxt server routes, Express, …). The Vue app calls your own API; the server keeps one `FinTs3Client` per session and passes the TAN challenges to the browser, for example with a pending request the browser answers. Two sessions of one bank user share the saved state, so run their clients one after another (see [Usage](#usage)). This keeps the bank traffic and the product ID on the server.
 2. **The client runs in the browser, through a relay.** The library runs in the Vue app, so TAN prompts are plain local UI, and a small endpoint of yours forwards each message to the bank. Pass a transport that posts to it:
 
    ```ts
-   import type { FinTsTransport } from '@coderoftime/fints';
+   import { FinTsTransportError, type FinTsTransport } from '@coderoftime/fints';
 
    const relay: FinTsTransport = {
-     async post(url, body, contentType) {
+     async post(url, body, contentType, signal) {
        const response = await fetch('/api/fints-relay', {
          method: 'POST',
          headers: { 'Content-Type': contentType, 'X-FinTS-URL': url.href },
-         body,
+         body: body.slice(), // a copy on an ArrayBuffer of its own, the only kind TypeScript's fetch types take
+         signal, // aborted five seconds after the client is closed
+         redirect: 'error', // never send the PIN on to another address
+         cache: 'no-store',
        });
-       if (!response.ok) throw new Error(`Relay: HTTP ${response.status}`);
+       if (!response.ok) {
+         // The bank's HTTP status, which the relay passes on and the client acts on (FinTsTransport.post).
+         throw new FinTsTransportError(`Relay: HTTP ${response.status}`, { statusCode: response.status });
+       }
        return new Uint8Array(await response.arrayBuffer());
      },
      close() {},
    };
    ```
 
-   The relay must forward only to the bank URLs of the DK institute list, never to any URL a caller names, or it is an open proxy. The product ID ends up in the page; anyone can read it there.
+   Until it is closed, the client limits neither the time of an exchange nor the size of an answer, so a transport of your own has to, unless it goes through a relay that does, as this one does. The relay forwards with `HttpTransport`, which times out, limits the size of the answer and follows no redirect, and passes the bank's HTTP status on. A sketch with the web-standard `Request` and `Response`:
+
+   ```ts
+   import { FinTsTransportError, HttpTransport } from '@coderoftime/fints';
+
+   const bank = new HttpTransport();
+   const maxBodyBytes = 1024 * 1024; // far more than a message of the client takes
+
+   // Behind the app's login and a rate limit per session; bankUrl is the bank the user chose, as URL.href writes it.
+   export async function relay(request: Request, session: { bankUrl: string }): Promise<Response> {
+     if (request.headers.get('X-FinTS-URL') !== session.bankUrl) return new Response(null, { status: 403 });
+     // Checked before the body is read, of which the server reads no more than the length states.
+     const length = Number(request.headers.get('Content-Length') ?? NaN);
+     if (!(length <= maxBodyBytes)) return new Response(null, { status: 413 });
+     try {
+       const body = new Uint8Array(await request.arrayBuffer());
+       const answer = await bank.post(new URL(session.bankUrl), body, 'text/plain', request.signal);
+       return new Response(answer.slice(), { headers: { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' } });
+     } catch (error) {
+       // The bank's HTTP status, which the client acts on; 502 where the bank did not answer.
+       const status = error instanceof FinTsTransportError ? error.statusCode : undefined;
+       return new Response(null, { status: status ?? 502 });
+     }
+   }
+   ```
+
+   Anyone who can call the relay can send logins to the banks it forwards to, from your server's address, which a bank may then block for all your users. So serve it to the signed-in sessions of your app only, limit the requests of each session, and forward only to the bank the user chose for the session, from a list of known https URLs such as the DK institute list. The body holds PIN and TAN: never log it, on either side, nor put it in an error message, which the client passes on. And never mix up the answers of two sessions: the client cannot tell the answer to the first message of a dialog from that of another user. The product ID ends up in the page; anyone can read it there.
 
-3. **The app is not a web page**: Electron, Tauri or Capacitor can send requests without CORS. Pass a `FinTsTransport` that uses the platform's HTTP client, or `HttpTransport` where `fetch` is not bound by CORS.
+3. **The app is not a web page**: Electron, Tauri or Capacitor can send requests without CORS. Pass a `FinTsTransport` that uses the platform's HTTP client without following redirects, with a timeout and a limit on the size of the answer, or `HttpTransport` where `fetch` is not bound by CORS.
+
+Keep a client in the Vue app out of reactive state (`ref`, `reactive`, a Pinia store): Vue wraps it in a proxy there, which cannot reach the client's private fields, so every call fails with a `TypeError`. A plain variable, a `shallowRef` or `markRaw(client)` keeps the client as it is.
 
 A TAN prompt in Vue fits the callback as a promise the dialog resolves:
 
@@ -110,48 +159,97 @@ export const pending = ref<{ challenge: TanChallenge; answer: (a: TanAnswer) =>
 export function tanCallback(challenge: TanChallenge): Promise<TanAnswer> {
   return new Promise((answer) => {
     pending.value = { challenge, answer };
-    void challenge.resolved?.then(() => (pending.value = undefined)); // the bank confirmed the app approval
+    void challenge.resolved?.then(() => (pending.value = undefined)); // the client needs no answer any more
   });
 }
 // The dialog component shows pending.value.challenge and calls pending.value.answer(TanAnswer.tan(input)),
 // TanAnswer.approved or TanAnswer.cancelled, then clears pending.value.
 ```
 
+The dialog shows the challenge's text with `{{ }}`, which Vue escapes, never with `v-html`: `plainMessage` and `message`, like any text of the bank, are no markup to trust, and as HTML they could run scripts in the page where the user enters the PIN. The same holds for the bank messages and warnings of `onBankMessage` and `onWarning`, whose number and length the bank chooses without a limit, so bound what the app shows of them. `white-space: pre-line` keeps the line breaks of `plainMessage`:
+
+```vue
+<div v-if="pending">
+  <p style="white-space: pre-line">{{ pending.challenge.plainMessage }}</p>
+  <img v-if="pending.challenge.image" :src="pending.challenge.image.toDataUrl()" alt="TAN image" />
+</div>
+```
+
 ## Errors
 
-| Error                        | Meaning                                                                                                                                          |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `FinTsPinError`              | Wrong or blocked PIN. The client sends no PIN any more; create a new client to try again.                                                        |
-| `FinTsTanError`              | Wrong, expired or used TAN. The session stays usable.                                                                                            |
-| `FinTsTanCancelledError`     | The user cancelled the TAN or the app approval.                                                                                                  |
-| `FinTsDecoupledTimeoutError` | The app approval did not come within the bank's limit.                                                                                           |
-| `FinTsLoginDataChangedError` | The bank issued new login data (`3072`); `loginName` tells it.                                                                                   |
-| `FinTsDialogAbortedError`    | The bank ended the dialog; the next call logs in anew.                                                                                           |
-| `FinTsBankError`             | Any other rejection; `feedback` holds the return codes. After a refused login, later calls fail with the same error without contacting the bank. |
-| `FinTsUnsupportedError`      | The bank or the user's parameter data do not offer the transaction; nothing was sent.                                                            |
-| `FinTsProtocolError`         | The bank's answer could not be read.                                                                                                             |
-| `FinTsTransportError`        | No connection, an HTTP error or a timeout.                                                                                                       |
-| `FinTsStateError`            | The client was closed, or called from inside one of its callbacks.                                                                               |
-| `TypeError`                  | An invalid argument, such as an empty PIN or a period that ends before it starts; the message never contains the PIN.                            |
-
-The client never sends a message larger than the bank's maximum (`BankInfo.maxMessageSize`, in kilobytes), and never repeats a call by itself: the bank's answer cannot tell whether an order went through.
+| Error                        | Meaning                                                                                                               |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `FinTsLoginRefusedError`     | The bank refused the login. The client sends the PIN no more, see [Refused logins](#refused-logins).                  |
+| `FinTsPinError`              | Wrong or blocked PIN, a `FinTsLoginRefusedError`.                                                                     |
+| `FinTsTanError`              | Wrong, expired or used TAN. The session stays usable.                                                                 |
+| `FinTsTanCancelledError`     | The user cancelled the TAN or the app approval.                                                                       |
+| `FinTsDecoupledTimeoutError` | The app approval did not come within the requests the bank allows (60 where it states none) or 10 minutes.            |
+| `FinTsLoginDataChangedError` | The bank issued new login data (`3072`); `loginName` tells it. A `FinTsLoginRefusedError` for the old data.           |
+| `FinTsDialogAbortedError`    | The bank ended the dialog; the next call logs in anew.                                                                |
+| `FinTsBankError`             | Any other rejection; `feedback` holds the return codes.                                                               |
+| `FinTsUnsupportedError`      | The parameter data do not offer the transaction; the client did not send it, though it may have logged in.            |
+| `FinTsTanSetupError`         | No TAN method or medium to log in with; pass a medium to `selectTanMethod`, or choose another method.                 |
+| `FinTsProtocolError`         | The bank's answer could not be read. The message leaves out the data, which may be account data.                      |
+| `FinTsTransportError`        | No connection, an HTTP error (`statusCode`), a timeout or an abort by `close`. The message may have reached the bank. |
+| `FinTsStateError`            | The client was closed, or called from inside one of its callbacks.                                                    |
+| `TypeError`                  | An invalid argument, such as an empty PIN or a TAN that the TAN method rules out; the message never shows PIN or TAN. |
+
+The client never repeats a call by itself: the bank's answer cannot tell whether an order went through.
+
+It reads only complete answers to the message it sent: one cut short, broken, or with the number or dialog ID of another message fails the call with `FinTsProtocolError`. Only the bank's dialog abort message, which names neither (dialog ID `unbekannt`, message number 9999), answers any message: it fails the call with a `FinTsBankError` that holds the bank's text, and ends the dialog. The first message of every dialog goes out with the same number and dialog ID, though, so the answer to another user's first message passes: a relay must never mix up answers. A query whose pages hold more than 128 MiB, each data element counted as 512 bytes, or more than 200,000 statements and transactions, fails with `FinTsProtocolError` as well: ask for a shorter period then. So that a broken or hostile server cannot block the app or exhaust its memory, the client also refuses an answer with more than 1,000,000 data elements and segments in its plain or in its encrypted part, or with more than one encrypted part; XML nested more than 100 levels deep, or with more than 500,000 nodes besides text or one per 16 characters, whichever is more; an MT940 field or camt remittance information (`Ustrd`) of more than 65,536 characters; and an amount written with more than 64 characters. `Mt940.parse`, `Camt.parse` and `Amount.parseDecimal` throw `FormatError` for these.
+
+MT940 statements must balance. Where a bank wraps a purpose at a fixed width, a payer could start a line of it like a field, such as `:61:`, which would add a transaction; `getTransactions` fails with `FinTsProtocolError` instead, and `Mt940.parse` with `FormatError`. The check misses such lines that add up to nothing, and statements without balances, such as pending transactions (MT942).
+
+## Refused logins
+
+Banks lock the online access after a few failed logins. So once the bank has refused a login, the client does not send the PIN again: every call that would fails with the refusal, a `FinTsLoginRefusedError`, without contacting the bank. Any error in the answer to a login refuses it, since a return code does not always tell whether the PIN was the reason, and so does a wrong PIN the bank reports later in the dialog.
+
+Only where the bank names a reason the client can take care of does the same call log in once more, once per reason: with another TAN method where the bank lists those the user may use without the one the login was signed with (`3920`, after the one-step method only next to no error but `9050`, `9800` or `9955`) or demands strong authentication of a one-step login (`9075`), and with a new customer system ID where the bank rejects the old one (`9391`). None of them follows a wrong PIN, and a call sends at most three logins the bank refuses.
+
+A login whose answer is lost, times out, is aborted by `close` or cannot be read may have counted as a failed attempt all the same. After two such logins in a row the client refuses the login itself, with a `FinTsLoginRefusedError` whose `feedback` is empty; it cannot tell a login that never reached the bank, so a connection that fails twice in a row stops it as well. A login the bank takes clears the count.
+
+The refusal and that count are part of `client.state`, so a client restored from it does not send the PIN either, as long as the clients of the user take turns with the state (see [Usage](#usage)); where their part of the state is damaged, the client restores a refusal whose `feedback` is empty. `client.loginRefusal` tells it before any call. Lift it with a PIN the user has entered anew, unless the bank has changed the login data:
+
+```ts
+const refusal = client.loginRefusal;
+if (refusal instanceof FinTsLoginDataChangedError) {
+  // The old login data are retired: build a new client with refusal.loginName as userId, or its userId and customerId.
+} else if (refusal !== undefined) {
+  showNotice(refusal.message); // the bank's errors, or why the client stopped by itself
+  await client.clearLoginRefusal(await askForPin());
+}
+```
+
+Never pass `clearLoginRefusal` a stored PIN without asking the user: that is how a retrying app locks the access. It also forgets the TAN medium, which the bank may have refused instead, such as that of a replaced phone, so that the next call looks the media up anew.
 
 ## Differences from the Dart package
 
-- Errors are named `…Error` instead of `…Exception`; invalid arguments are `TypeError`s, malformed data `FormatError`s.
+This section compares with the Dart package as its source stands after its release 0.2.0, which differs in more ways. Both keep the saved state in the same layout, a refused login included, so each restores the other's. The Dart package 0.2.0 keeps no refused login, though: restored from a state of this package, it sends the PIN the bank refused. They differ in:
+
+- Errors are named `…Error` instead of `…Exception`; invalid arguments are `TypeError`s, malformed data `FormatError`s, and a closed client or a call from inside a callback a `FinTsStateError`. Some messages are worded differently.
 - `getTransactions(account, { from, to, format })` takes an options object; enums are string unions such as `'mt940'`.
 - The polling parameters of `TanMethod` are in seconds: `decoupledFirstPollDelaySeconds`, `decoupledPollIntervalSeconds`.
-- `HttpTransport` takes a `fetch` and `timeoutMs`; `TanImage.toDataUrl()` is new.
-- The saved state has the same layout, so a state saved by one package can be restored by the other.
+- No FinTS 4.1, so no `FinTs4Client`, `FinTsClient.version` or `BankInfo.bic`. `FinTsConfig` checks the login data against what FinTS 3.0 can send, which the Dart package does in `FinTs3Client`, and also refuses a user ID or customer ID of more than 30 characters, which the Dart package sends.
+- `HttpTransport` takes a `fetch` and `timeoutMs` instead of an HTTP client and a `Duration`. `FinTsTransport.post` takes an `AbortSignal`, with which `close` aborts a request on its way after five seconds, also through a custom transport, and then stops waiting for it whatever the transport does; the Dart package aborts only its own `HttpTransport` (`abortRequests`) and waits for any other transport up to that transport's timeout.
+- HTTP goes through the runtime's `fetch`, with its proxies, timeouts and trusted certificates. Plain http to a local server, which `allowInsecureUrl` allows, goes wherever the global `fetch` sends it, as https does: to whatever replaces `globalThis.fetch`, such as a test's stub, to a global dispatcher on Node.js, and through any proxy that `fetch` takes from the environment (Node.js with `NODE_USE_ENV_PROXY=1`, Deno and Bun with `HTTP_PROXY`), which sees the PIN. Exempt the host with `NO_PROXY=localhost,127.0.0.1,::1` or pass a `fetch` that connects directly. The Dart package connects to the loopback host directly, also bypassing a client set with `runWithClient`, and on native platforms follows `HTTPS_PROXY` and `NO_PROXY` for https, which Node.js does only with `NODE_USE_ENV_PROXY=1`.
+- A call from inside a callback fails on Node.js, Deno and Bun only; in browsers it waits forever, where the Dart package fails on every platform.
+- `console.log` and `util.inspect` show the objects of this package as [Usage](#usage) describes, where the Dart package prints most of them as `Instance of '…'`, and `toString` of a `FinTsFeedback` or a `BankMessage` leaves out the bank's texts, which the Dart package prints. The browser console shows every field, where the Dart package on the web prints `toString`.
+- `JSON.stringify` gives every field of a model, the TAN of a `TanAnswer` included, and of an error its `name`, and the `statusCode` of a `FinTsTransportError`; the Dart package's models and errors have no JSON form.
+- Some bank data are read and sent otherwise. In MT940, the counterparty's IBAN and BIC come from the subfields `?31` and `?30` only, not from `IBAN+` and `BIC+` in the payer's reference, a bank code in `?30` next to an IBAN is the bank code, the customer reference `KREF+` stands for the one of `:86:`, and the balance date `0` or `000000` for none. A camt purpose falls back to the structured creditor reference, and remittance information of more than 65,536 characters is refused. Challenge text counts as a combined chipTAN challenge only where it starts with `CHLGUC` and states the length of its code. The bank's dialog abort message fails the call with a `FinTsBankError`. A balance or transaction query that names the account by its international account (KTI) leaves out the national account where the bank parameter data rule it out, unless the account has no BIC, and sends no IBAN without its BIC, unless the account has no account number. A one-step login that the bank answers with `9955` and `3920` is repeated with a two-step method.
 
 ## Development
 
 ```sh
 npm install
-npm run check   # type check, lint, format check and tests
+npm run check   # type check, lint, unused code, format check and tests with coverage
 npm run build
 ```
 
+The check fails for Node.js APIs in `src/` that browsers lack, for files, exports and dependencies nothing uses, or only
+the tests ([knip](https://knip.dev)), and for coverage below the thresholds in `vitest.config.ts`, which each module
+that guards what goes to and comes from the bank has to reach on its own. The coverage report is in
+`coverage/index.html`.
+
 ## License
 
 BSD 3-Clause, see [LICENSE](LICENSE). Commercial use is allowed; a product that ships the library must reproduce its copyright notice and license in its documentation or notices.

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { Account } from './core/account.js';
+import type { Balance } from './core/balance.js';
+import type { BankInfo } from './core/bank-info.js';
+import type { FinTsClient, FinTsClientOptions, TransactionQuery } from './core/client.js';
+import { FinTsConfig, type FinTsConfigInit } from './core/config.js';
+import { type FinTsLoginRefusedError } from './core/errors.js';
+import type { Transaction } from './core/transaction.js';
+import { TanMedium, type TanMethod } from './tan/tan-models.js';
+/** What `FinTs3Client` takes. */
+export interface FinTs3ClientInit {
+    /** Where and as whom to log in: a `FinTsConfig`, or what its constructor takes. */
+    config: FinTsConfig | FinTsConfigInit;
+    /**
+     * The user's PIN. The client keeps it in memory only, never logs it, and forgets it once it is closed or the bank has
+     * refused the login. It is out of reach of `JSON.stringify` and Node.js's `util.inspect` of the client, but not of a
+     * debugger or the browser's DevTools: never log the client. A client whose `options.state` holds a refused login
+     * does not send it (`FinTsClient.loginRefusal`).
+     */
+    pin: string;
+    /** How the client reaches the user and the bank. */
+    options: FinTsClientOptions;
+}
+/** FinTS 3.0 PIN/TAN client, the version German banks use. */
+export declare class FinTs3Client implements FinTsClient {
+    #private;
+    /**
+     * A client with the session restored from `FinTsClientOptions.state` where it was saved for this user and bank.
+     *
+     * Throws `TypeError` if the configuration is invalid, as the constructor of `FinTsConfig` tells, or the PIN is empty,
+     * begins or ends with a blank, or has characters FinTS 3.0 cannot send: it uses ISO 8859-1, so `€` and most
+     * non-Latin letters are not possible. Throws `TypeError` as well for an option of another type than
+     * `FinTsClientOptions` names, as `FinTsClientOptions` tells.
+     */
+    constructor(init: FinTs3ClientInit);
+    get state(): string;
+    get loginRefusal(): FinTsLoginRefusedError | undefined;
+    get selectedTanMethod(): string | undefined;
+    get selectedTanMedium(): string | undefined;
+    selectTanMethod(securityFunction: string, tanMedium?: string): Promise<void>;
+    clearLoginRefusal(pin: string): Promise<void>;
+    getBankInfo(): Promise<BankInfo>;
+    getTanMethods(): Promise<TanMethod[]>;
+    getTanMedia(): Promise<TanMedium[]>;
+    getAccounts(): Promise<Account[]>;
+    getBalance(account: Account): Promise<Balance>;
+    getTransactions(account: Account, query?: TransactionQuery): Promise<Transaction[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAc,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAA0C,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACvG,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,uBAAuB,CAAC;AAS5E,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAUhE,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,MAAM,EAAE,WAAW,GAAG,eAAe,CAAC;IACtC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AA2CD,8DAA8D;AAC9D,qBAAa,YAAa,YAAW,WAAW;;IAkC9C;;;;;;;OAOG;gBACS,IAAI,EAAE,gBAAgB;IAyBlC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,YAAY,IAAI,sBAAsB,GAAG,SAAS,CAErD;IAED,IAAI,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAE1C;IAED,IAAI,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAE1C;IAEK,eAAe,CAAC,gBAAgB,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlF,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAIhC,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIrC,WAAW,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAenC,WAAW,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAI3B,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAe9C,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA4CvB"}

package/dist/client.js

@@ -0,0 +1,242 @@
+import { Account } from './core/account.js';
+import { FinTsConfig, requirePin } from './core/config.js';
+import { FinTsStateError, FinTsUnsupportedError } from './core/errors.js';
+import { DialogRunner } from './session/dialog-runner.js';
+import { LoginGuard } from './session/login-guard.js';
+import { SepaAccounts } from './session/sepa-accounts.js';
+import { SessionSetup } from './session/session-setup.js';
+import { restoreSession, saveSession } from './session/session-state.js';
+import { TanSelection } from './session/tan-selection.js';
+import { UserPrompts } from './session/user-prompts.js';
+import { TanMedium } from './tan/tan-models.js';
+import { optionalString, requireString } from './util/arguments.js';
+import { SerialExecutor } from './util/async.js';
+import { CallContext } from './util/call-context.js';
+import { calendarDay, notAfterToday } from './util/dates.js';
+import { invalidArgument } from './util/errors.js';
+import { ParameterStore } from './v3/parameter-store.js';
+import { FinTs3Protocol } from './v3/protocol.js';
+import { balanceQuery, tanMediaQuery, transactionsQuery } from './v3/queries.js';
+/** A token of the client call running now, so that a call from inside its callbacks is recognized. */
+const runningCalls = new CallContext();
+/**
+ * `transport`, `undefined` for `null`; throws `TypeError` unless it is neither or has the functions of a
+ * `FinTsTransport`.
+ */
+function optionalTransport(transport) {
+    if (transport === undefined || transport === null)
+        return undefined;
+    const candidate = transport;
+    if (typeof candidate.post !== 'function' || typeof candidate.close !== 'function') {
+        throw invalidArgument('Must have the functions post and close', 'transport');
+    }
+    return transport;
+}
+/** Throws `TypeError` for anything but an `Account`, such as one written to JSON and read back. */
+function requireAccount(account) {
+    if (!(account instanceof Account))
+        throw invalidArgument('Must be an Account', 'account');
+}
+/**
+ * The calendar day of `bound`, the `name` bound of a `TransactionQuery`: the bank takes dates without time of day.
+ * Throws `TypeError` for anything but a valid `Date`, such as an Invalid Date, which would go out as `0NaNNaNNaN`.
+ */
+function requestedDay(bound, name) {
+    if (bound === undefined)
+        return undefined;
+    if (!(bound instanceof Date) || Number.isNaN(bound.getTime()))
+        throw invalidArgument('Not a valid Date', name);
+    return calendarDay(bound);
+}
+/**
+ * The format a `TransactionQuery` asks for with `format`: `auto` where it is `undefined`. Throws `TypeError` for anything
+ * but a `TransactionFormat`, such as `'CAMT'` or `null`.
+ */
+function requestedFormat(format) {
+    if (format === undefined)
+        return 'auto';
+    if (format === 'auto' || format === 'mt940' || format === 'camt')
+        return format;
+    throw invalidArgument("Must be 'auto', 'mt940' or 'camt'", 'format');
+}
+/** FinTS 3.0 PIN/TAN client, the version German banks use. */
+export class FinTs3Client {
+    // A call such as `getBalance` runs through these parts:
+    // 1. `DialogRunner.open` reuses the session's dialog or logs in, through `SessionSetup.remedied`, which logs in once
+    //    more for each refusal it can take care of.
+    // 2. `SessionSetup.prepare` first settles what is open: the bank parameter data, the synchronization, and through
+    //    `TanSelection` the TAN method and medium.
+    // 3. `SignedDialog.login` sends the login and completes the strong authentication the bank asks for, a TAN or an app
+    //    approval (`AppApprovalWait`).
+    // 4. `DialogRunner.query` sends the order in that dialog, completes its approval the same way, and fetches all pages.
+    //
+    // `FinTs3Protocol` builds, signs and posts the messages of each `FinTs3Dialog`, the queries build the orders and read
+    // the answers, and the `ParameterStore` keeps the bank's parameter data and IDs. `SepaAccounts` completes IBAN and
+    // BIC, and `UserPrompts` is everything the app is told or asked. The `LoginGuard` holds the PIN: the protocol takes it
+    // from the guard for every message it signs, and `SignedDialog` has the guard judge every answer, so that the PIN does
+    // not go out after a refusal.
+    //
+    // The fields are ECMAScript private, so that neither `util.inspect` nor `JSON.stringify` of a client reaches the PIN
+    // or the account data behind them.
+    #prompts;
+    #guard;
+    #parameters;
+    #protocol;
+    #sessionState;
+    #tans;
+    #setup;
+    #dialogs;
+    #sepa;
+    #queue = new SerialExecutor();
+    #closed;
+    /** The call running now, which a call from inside its callbacks would wait for. */
+    #runningCall;
+    /**
+     * A client with the session restored from `FinTsClientOptions.state` where it was saved for this user and bank.
+     *
+     * Throws `TypeError` if the configuration is invalid, as the constructor of `FinTsConfig` tells, or the PIN is empty,
+     * begins or ends with a blank, or has characters FinTS 3.0 cannot send: it uses ISO 8859-1, so `€` and most
+     * non-Latin letters are not possible. Throws `TypeError` as well for an option of another type than
+     * `FinTsClientOptions` names, as `FinTsClientOptions` tells.
+     */
+    constructor(init) {
+        const config = init.config instanceof FinTsConfig ? init.config : new FinTsConfig(init.config);
+        const { state, transport } = init.options;
+        this.#prompts = new UserPrompts(init.options);
+        this.#guard = new LoginGuard(requirePin(init.pin));
+        this.#parameters = new ParameterStore(config);
+        this.#protocol = new FinTs3Protocol(this.#parameters, this.#guard, optionalTransport(transport), this.#prompts.logger);
+        this.#sessionState = restoreSession(optionalString(state, 'state'), this.#parameters, this.#guard);
+        this.#tans = new TanSelection(this.#protocol, this.#sessionState, this.#prompts);
+        const session = {
+            parameters: this.#parameters,
+            state: this.#sessionState,
+            prompts: this.#prompts,
+            guard: this.#guard,
+        };
+        this.#setup = new SessionSetup(session, this.#protocol, this.#tans);
+        this.#dialogs = new DialogRunner(this.#setup);
+        this.#sepa = new SepaAccounts(this.#parameters, this.#sessionState, this.#dialogs);
+    }
+    get state() {
+        return saveSession(this.#parameters, this.#guard, this.#sessionState);
+    }
+    get loginRefusal() {
+        return this.#guard.refusal;
+    }
+    get selectedTanMethod() {
+        return this.#sessionState.tanMethod;
+    }
+    get selectedTanMedium() {
+        return this.#sessionState.tanMedium;
+    }
+    async selectTanMethod(securityFunction, tanMedium) {
+        // Checked before the dialog ends; an async method, so that every argument error is a rejection.
+        const method = requireString(securityFunction, 'securityFunction');
+        const medium = optionalString(tanMedium, 'tanMedium');
+        return this.#serialized(async () => {
+            await this.#dialogs.end();
+            this.#tans.select(method, medium);
+        });
+    }
+    clearLoginRefusal(pin) {
+        return this.#serialized(async () => {
+            const sendable = requirePin(pin);
+            // The dialog ends with the PIN it was opened with.
+            await this.#dialogs.end();
+            this.#guard.replacePin(sendable);
+            this.#tans.forgetMedium();
+        });
+    }
+    getBankInfo() {
+        return this.#serialized(() => this.#setup.remedied(() => this.#setup.bankInfo()));
+    }
+    getTanMethods() {
+        return this.#serialized(() => this.#setup.remedied(() => this.#setup.methods()));
+    }
+    getTanMedia() {
+        return this.#serialized(async () => {
+            // The session keeps the list of a lookup that found no medium; the app gets media of its own.
+            const lookedUp = (await this.#setup.remedied(() => this.#setup.prepare())) ?? this.#tans.lookedUpMedia;
+            return (lookedUp?.map((m) => new TanMedium(m)) ??
+                (await this.#dialogs.query(() => {
+                    const query = tanMediaQuery(this.#parameters);
+                    if (query === undefined)
+                        throw new FinTsUnsupportedError('The bank does not list TAN media');
+                    return query;
+                })));
+        });
+    }
+    getAccounts() {
+        return this.#serialized(() => this.#sepa.completedAccounts());
+    }
+    async getBalance(account) {
+        // Checked before the call waits for others; an async method, so that every argument error is a rejection.
+        requireAccount(account);
+        return this.#serialized(async () => {
+            const completed = await this.#sepa.complete(account);
+            // The dialog start delivers the user parameter data, which may carry the complete balance: then the client must
+            // not ask for it separately (Formals E.3.1.1, F.3.2).
+            await this.#dialogs.open();
+            return (this.#parameters.userParameters?.completeBalance(completed) ??
+                (await this.#dialogs.query(() => balanceQuery(this.#parameters, completed))));
+        });
+    }
+    async getTransactions(account, query = {}) {
+        // Checked before the call waits for others; an async method, so that every argument error is a rejection.
+        requireAccount(account);
+        const firstDay = requestedDay(query.from, 'from');
+        const lastDay = requestedDay(query.to, 'to');
+        if (firstDay !== undefined && lastDay !== undefined && firstDay.getTime() > lastDay.getTime()) {
+            throw invalidArgument('`from` lies on a day after `to`', 'from');
+        }
+        const format = requestedFormat(query.format);
+        return this.#serialized(async () => {
+            const completed = await this.#sepa.complete(account);
+            const transactions = await this.#dialogs.query(() => transactionsQuery(this.#parameters, completed, format, notAfterToday(firstDay), notAfterToday(lastDay)));
+            // A stable sort, so that transactions of the same day keep the bank's order.
+            return transactions.sort((a, b) => (a.bookingDate ?? a.valueDate).getTime() - (b.bookingDate ?? b.valueDate).getTime());
+        });
+    }
+    close() {
+        this.#closed ??= this.#closeNow();
+        return this.#closed;
+    }
+    #closeNow() {
+        this.#prompts.close();
+        this.#protocol.beginClose();
+        return this.#queue.run(() => this.#prompts.reportingCallbackErrors(async () => {
+            try {
+                await this.#dialogs.end();
+            }
+            finally {
+                this.#guard.close();
+                this.#protocol.close();
+            }
+        }));
+    }
+    #serialized(action) {
+        const caller = runningCalls.current;
+        if (caller !== undefined && caller === this.#runningCall) {
+            // The call would wait behind the running one, which waits for the callback: neither would ever end.
+            return Promise.reject(new FinTsStateError('The FinTS client was called from inside one of its callbacks'));
+        }
+        return this.#queue.run(async () => {
+            const call = {};
+            this.#runningCall = call;
+            try {
+                return await runningCalls.run(call, () => this.#guard.runCall(async () => {
+                    this.#prompts.checkOpen();
+                    const result = await this.#prompts.reportingCallbackErrors(action);
+                    // Also where the last answer arrived after `close`: a closed client hands out no account data.
+                    this.#prompts.checkOpen();
+                    return result;
+                }));
+            }
+            finally {
+                this.#runningCall = undefined;
+            }
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}