@coderoftime/fints 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,3 +1,142 @@
+## 0.2.0
+
+### Breaking
+
+- Keep a `FinTs3Client` out of Vue's reactive state (`ref`, `reactive`, Pinia): its fields are ECMAScript private now,
+  which Vue's proxies cannot reach, so every call fails with a `TypeError`. Use a plain variable, a `shallowRef` or
+  `markRaw`.
+- `FinTsTransport.post` takes an `AbortSignal` as fourth argument, which the client aborts on `close`: pass it to
+  `fetch`. Code that calls `post` itself must pass one; `HttpTransport.post` takes it optionally.
+- A custom transport reports failures as `FinTsTransportError`, with `statusCode` for an HTTP error. The client turns
+  any other error, another `FinTsError` included, into a `FinTsTransportError` that keeps only its message and that of
+  its cause, and `FinTsTransportError` takes and carries no `cause` any more.
+- A refused login is a `FinTsLoginRefusedError`, which `FinTsPinError` and `FinTsLoginDataChangedError` now extend, also
+  where the bank ends the dialog in answer to the login (it was `FinTsDialogAbortedError`). The client sends the PIN no
+  more then: see Added for `loginRefusal` and `clearLoginRefusal`.
+- `FinTsTanSetupError` replaces `FinTsUnsupportedError` where the client has no TAN method or medium to log in with: let
+  the user choose a medium or another method (`selectTanMethod`) rather than hide the feature.
+- `FinTsError` takes the message only, as `Error` does, and `FinTsBankError` takes no `name`: a subclass declares
+  `override name = '…'`.
+- `FinTsConfig` throws a `TypeError` for what the bank would refuse: a URL with user name or password, a country code of
+  other than three digits (280 for Germany, not 276), a German bank code of other than eight, and login details outside
+  ISO 8859-1. It trims the login details and the product, and `config.url` is a new copy at each access.
+- `HttpTransport` throws a `TypeError` for a `timeoutMs` that is no positive number up to 2147483647, and for a
+  `maxResponseBytes` that is no positive number.
+- A TAN longer than `TanMethod.maxTanLength`, with anything but the digits 0 to 9 for a `numericTan` method, or with
+  characters outside ISO 8859-1 fails the call with a `TypeError` before it is sent. Full-width digits count as digits
+  (NFKC).
+- A TAN callback answer that is no `TanAnswer`, such as the `undefined` of a callback that returns nothing, fails the
+  call with a `TypeError`.
+- Bank data are read strictly, failing `getTransactions` with `FinTsProtocolError` and the parsers with `FormatError`:
+  an MT940 statement that does not balance, states a balance, its account or its number twice, or holds an unreadable
+  balance, and MT940 text without fields; in camt, an unreadable date, a `DtTm` without time, and a document without
+  statements.
+- A negative amount next to a credit/debit mark is malformed: in camt and HISAL it fails the call, and it voids the
+  account extension of the user parameter data; a camt debit of `-5.00` used to read as a credit.
+- `TanImage.tryParse` takes PNG, JPEG, GIF, WebP and BMP only, no SVG, and `TanImage.mimeType` is in lower case.
+  `FlickerCode.parse` rejects a code that would not render as the bank sent it, so `TanChallenge.flickerCode` is
+  `undefined` for it.
+- `Account` keeps IBAN and BIC without blanks and in capitals. `Account.allowedTransactions` counts segment IDs only,
+  such as `HKCAZ`, no versioned names such as `HKCAZ_1`.
+- `FinTsFeedback.parameters`, and with them the new login data of `FinTsLoginDataChangedError`, and
+  `TanChallenge.reference` are read one character per byte (ISO 8859-1), as the client sends them back.
+
+### Security
+
+- The client keeps the PIN in a private field, out of reach of `JSON.stringify` and Node.js's `util.inspect`, though not
+  of a debugger or the browser's DevTools: never log the client. It forgets the PIN once closed or refused.
+- A refused login is kept in `state`, as the bank's return codes, so that a client restored from it, also one for
+  another URL of the bank, does not send the PIN. Any error in the answer to a login refuses it, and so does a wrong PIN
+  reported later, at the dialog end included. Run the clients of one user one after another: the state saved last wins.
+- After two logins in a row whose answer was lost, timed out or could not be read, which the bank may have counted, the
+  client refuses the login itself, with a `FinTsLoginRefusedError` without return codes, also across restored clients.
+- A call sends at most three logins the bank refuses: another TAN method and a new customer system ID count once per
+  call each, and a refused one-step login is repeated with another method only where the bank names the method (9075, or
+  a 3920 next to no error but 9050 or 9800).
+- New login data (3072) fail the call as soon as an answer to the login brings them, before any approval and also next
+  to errors; `clearLoginRefusal` cannot lift them.
+- `close` stops a running call at its next message and aborts the request on its way; only the ends of its dialogs go
+  out after it.
+- Error messages keep the PIN and account data out: a transport's error passes on its message only, without `cause`;
+  `FormatError` and `FinTsProtocolError` leave out the data; a URL with credentials is rejected before `fetch` puts it
+  in an error.
+- Messages go to the bank's URL only: `HttpTransport` rejects the answer to a redirect its `fetch` followed or from
+  another URL, and the transport gets a copy of the checked URL for each message.
+- An answer must be one complete message, with the number and, once assigned, the dialog ID of the message sent: one cut
+  short, broken in its framing, joined to another or answering another message fails with `FinTsProtocolError`. The
+  first answer of a dialog cannot be matched, so a relay must never mix up answers.
+- Parameter data come only from the answers to a dialog's opening; the anonymous dialog's serve until the user's arrive,
+  and those of another user, of a rejected customer system ID (9391) or of a state from an earlier version or the Dart
+  package are fetched anew.
+- A balance (HISAL) and camt transactions (HICAZ) must be for the account asked for, or the call fails with
+  `FinTsProtocolError`. MT940 is not checked, since banks write the `:25:` line in many ways.
+- An account the app builds itself goes out as the bank knows it and is checked against the transactions the bank
+  permits for it; one the bank names nowhere fails with `FinTsUnsupportedError` where those lists are complete
+  (UPD-Verwendung 0).
+- Hostile answers no longer exhaust the memory or hold up the thread: past 200,000 data elements per answer, 128 MiB or
+  200,000 statements and transactions per query, or XML of 256 levels or a million elements and attributes, a call fails
+  with `FinTsProtocolError`, and `Mt940.parse` and `Camt.parse` with `FormatError`; reading takes linear time.
+- An MT940 statement must balance, and name its account and number once, so that a payer cannot add a transaction or an
+  account with a purpose line that starts like a field, such as `:61:` or `:25:`.
+- A SEPA keyword in the text the payer or payee writes (`SVWZ+`, `ABWA+`, `ABWE+`) is part of that text, and one that
+  occurs twice has no value: such text replaced the creditor ID, mandate reference or IBAN the bank stated.
+- The creditor ID of a camt transaction is the creditor's (`Cdtr`) only, and the `EREF`, `MREF` and `CRED` of
+  `purposeCodes` come from their elements only, never from the remittance text.
+- A flicker code that would not render as the bank sent it is refused rather than shown altered on the TAN generator,
+  and so is a data element length of 0 or above 63. A TAN image of type SVG, which may carry scripts, is refused.
+- The docs say to show challenge text as text, never as HTML (`innerHTML`, `v-html`): it is the bank's text, or a
+  relay's.
+- The README relay serves the signed-in sessions of the app only, limits their requests, forwards to the bank of the
+  session only, refuses redirects and passes the signal on: update relays built from it.
+
+### Fixed
+
+- The README relay reports the relay's HTTP status as `FinTsTransportError.statusCode`, and its server passes the bank's
+  on. Without it, a bank that fails on the anonymous announcement of strong authentication never delivered its parameter
+  data.
+- The README names the minimum Deno (2.1) and Bun (1.2.6): with older ones a call from inside a callback waits forever
+  instead of failing with `FinTsStateError`.
+- The docs say when a call logs in again, which may ask for another approval, that `getTanMethods` may log in, that
+  `FinTsUnsupportedError` may follow a login, and the client's own limits of an app approval: 60 status requests where
+  the bank states none, and 10 minutes.
+- The PIN's length limits apply to the login only: a synchronization whose first parameter data ruled out the PIN the
+  bank had accepted failed its own dialog end.
+- An answer to a TAN or an app approval that asks for an approval once more (0030, 3955) fails with `FinTsProtocolError`
+  instead of reading as done, and only the first page of a query may ask for an approval.
+- While the client polls for an app approval, new instructions of the bank replace the open prompt, whose
+  `TanChallenge.resolved` settles; a settled prompt is no longer kept until `close`.
+- `getTanMedia` asks the bank unless the same call has just looked the media up; the list of a lookup that found no
+  active medium is handed out by every call; a TAN method switched back to has its media looked up anew;
+  `clearLoginRefusal` forgets the TAN medium, which the bank may have refused.
+- `getTransactions` rejects a `from` or `to` that is no valid `Date` with a `TypeError`, before it waits for other
+  calls; an Invalid Date went out as `0NaNNaNNaN`.
+- Values the bank issued go back as it sent them: dialog ID, customer system ID, TAN order reference, position to
+  continue at and TAN medium name, such as one in UTF-8 that fits ISO 8859-1, which the bank did not know otherwise.
+- A SEPA account list the bank answers by ending the dialog counts as rejected, and an empty one is not saved, so that
+  neither costs every client another login.
+- `HttpTransport` calls its `fetch` as a plain function (a browser's native one failed with `Illegal invocation`),
+  checks the size of an answer without a stream body, and reads the body of node-fetch.
+- MT940: `@@` separates the lines wherever the first line holds it; each page is decoded on its own; a booking date lies
+  in the year that places it within its statement; only `?` separates the subfields of `:86:`.
+- camt: a batch booking is split only into details that add up to it, in its currency; details count in `NtryDtls` and
+  purpose lines in `RmtInf` only; a `DtTm` counts on its German day; purpose lines cut at 35 characters keep their
+  blanks; `&constructor;` is an unknown entity.
+- Models keep copies of the `Date`s they are given, so that changing one in place changes no other, nor what a later
+  `getAccounts`, `getBalance` or `getTanMedia` returns. A complete balance of the account extension states the
+  `productName`.
+- An account of the user parameter data whose national account leaves out the bank code keeps its country code.
+- `state` encodes the parameter data once, as the bank sent them, and bank text is decoded in bulk: both held up the
+  thread with large data.
+- `FinTs3Client` extends no internal class, so that its declarations name no internal types.
+
+### Added
+
+- `FinTsClient.loginRefusal`, the refused login that keeps the client from sending the PIN, and
+  `clearLoginRefusal(pin)`, which lifts it with a PIN the user has entered anew; `FinTsLoginRefusedError`.
+- `FinTsTanSetupError`, for a missing TAN method or medium.
+- `Camt.parse`, which gives each statement of a camt document as a `CamtStatement` with its account.
+- `close` aborts a request on its way, through the signal of `FinTsTransport.post`; `HttpTransport` stops it.
+
 ## 0.1.0
 
 First release: a TypeScript port of the FinTS 3.0 client of the Dart package `fints`.
@@ -7,5 +146,7 @@ First release: a TypeScript port of the FinTS 3.0 client of the Dart package `fi
   parameters; TAN method and medium selection, chipTAN flicker codes and photoTAN images.
 - Bank parameter data, customer system ID and the chosen TAN method in an exportable state string, in the layout of the
   Dart package.
-- A client never sends its PIN again once the bank has refused a login.
+- A client never sends its PIN again once the bank has refused a login, but where the bank names a reason the client
+  takes care of in the same call: another TAN method (3920, or 9075 after the one-step method) or a new customer system
+  ID (9391).
 - Runs wherever `fetch`, Web Crypto and `TextDecoder` are available; no runtime dependencies.

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), with stricter safeguards (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 need TypeScript 5.6 or later.
 
 ## 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);
     },
@@ -65,7 +67,15 @@ try {
 }
 ```
 
-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; a bank that asks again for a later page fails the call with `FinTsProtocolError`.
+
+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.
+
+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 +85,59 @@ 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 when 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.
+   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();
+
+   // 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 });
+     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 });
+     }
+   }
+   ```
 
-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.
+   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 without following redirects, 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 +150,98 @@ 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. `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, with more than 200,000 data elements, or with the number or dialog ID of another message fails the call with `FinTsProtocolError`. 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, or more than 200,000 statements and transactions, fails with `FinTsProtocolError` as well: ask for a shorter period then.
+
+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` or `9800`) 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)); `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.
 - `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.
+- New: the `fetch` and `timeoutMs` of `HttpTransport`, `TanImage.toDataUrl()`, `Camt.parse`, `loginRefusal`, `clearLoginRefusal`.
+- `close` aborts a request on its way instead of waiting for the answer.
+- The saved state has the same layout, so either package restores the other's; only this one keeps a refused login in it.
+- `FinTsConfig` rejects login data the bank would refuse, before the PIN goes out.
+- Answers, flicker codes and TAN images are read strictly; SVG images are refused.
+- Values the bank issued, such as a TAN medium name in UTF-8, go back byte for byte.
+- New instructions of the bank replace the open app approval prompt while the client polls.
+- MT940 statements must balance.
+- camt batch bookings are split only where their details add up, the creditor ID is the creditor's, and `DtTm` counts on its German day.
+- A SEPA keyword in the text the payer or payee writes (`SVWZ+`, `ABWA+`, `ABWE+`) never replaces a value the bank stated.
 
 ## 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,48 @@
+import type { 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.
+     */
+    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,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,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,EAAE,MAAM,uBAAuB,CAAC;AAQzD,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAShE,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;AAeD,8DAA8D;AAC9D,qBAAa,YAAa,YAAW,WAAW;;IAkC9C;;;;;;OAMG;gBACS,IAAI,EAAE,gBAAgB;IAmBlC,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;IAED,eAAe,CAAC,gBAAgB,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5E,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;IAIjC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAaxC,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAyB7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyCvB"}