@coderoftime/fints 0.1.0 → 0.3.0

package/src/core/balance.ts

@@ -1,4 +1,5 @@
-import { formatIsoDate } from '../util/dates.js';
+import { copyDate, formatIsoDate } from '../util/dates.js';
+import { inspectCustom } from '../util/inspect.js';
 import type { Account } from './account.js';
 import type { Amount } from './amount.js';
 
@@ -59,18 +60,19 @@ export class Balance {
   /** The bank's name for the account, for example `Girokonto`. */
   readonly productName: string | undefined;
 
+  /** Takes copies of the dates of `init`: each balance has its own, which no other one shares. */
   constructor(init: BalanceInit) {
     this.account = init.account;
     this.booked = init.booked;
-    this.bookedAsOf = init.bookedAsOf;
-    this.bookedAsOfTime = init.bookedAsOfTime;
+    this.bookedAsOf = copyDate(init.bookedAsOf);
+    this.bookedAsOfTime = copyDate(init.bookedAsOfTime);
     this.pending = init.pending;
     this.creditLine = init.creditLine;
     this.available = init.available;
     this.used = init.used;
     this.overdraft = init.overdraft;
-    this.bookingDate = init.bookingDate;
-    this.bookingTime = init.bookingTime;
+    this.bookingDate = copyDate(init.bookingDate);
+    this.bookingTime = copyDate(init.bookingTime);
     this.productName = init.productName;
   }
 
@@ -81,4 +83,9 @@ export class Balance {
   toString(): string {
     return `Balance(${this.account.toString()}, ${formatIsoDate(this.bookedAsOf)})`;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: `toString`, not the fields. */
+  [inspectCustom](): string {
+    return this.toString();
+  }
 }

package/src/core/bank-info.ts

@@ -1,4 +1,9 @@
-/** General bank information from the bank parameter data (BPD). */
+import { inspectCustom } from '../util/inspect.js';
+
+/**
+ * General bank information from the bank parameter data (BPD). The maximum message size and the timeouts are
+ * `undefined` where the bank states none, or more than 9999, the four digits HIBPA allows.
+ */
 export class BankInfo {
   /** German bank code (BLZ). */
   readonly bankCode: string;
@@ -15,7 +20,7 @@ export class BankInfo {
   /** Languages the bank's messages come in, as codes the bank defines. */
   readonly languages: readonly string[];
 
-  /** Largest message in kilobytes (1024 bytes) the bank accepts; the client sends nothing larger. */
+  /** Largest message in kilobytes (1024 bytes) the bank accepts, `0` for no limit; the client sends nothing larger. */
   readonly maxMessageSize: number | undefined;
 
   /**
@@ -26,7 +31,7 @@ export class BankInfo {
 
   /**
    * Time in seconds after which the bank will likely end a dialog without messages, `0` for no limit (HIBPA, Formals
-   * C.9). The client starts a new dialog for a call after that time.
+   * C.9). The client starts a new dialog for a call after that time, or after 5 minutes where the bank states none.
    */
   readonly maxTimeout: number | undefined;
 
@@ -49,9 +54,19 @@ export class BankInfo {
     this.minTimeout = init.minTimeout;
     this.maxTimeout = init.maxTimeout;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: the bank code and the version of the parameter data. */
+  [inspectCustom](): string {
+    return `BankInfo(${this.bankCode}, BPD version ${this.bpdVersion})`;
+  }
 }
 
-/** Free-text message sent by the bank during login. */
+/**
+ * Free-text message sent by the bank during login.
+ *
+ * Subject and text are the bank's, of any length: show them as text only, never as HTML (`innerHTML`, `v-html`), since
+ * they are no markup to trust.
+ */
 export class BankMessage {
   constructor(
     /** What the message is about. */
@@ -60,7 +75,16 @@ export class BankMessage {
     readonly text: string,
   ) {}
 
+  /**
+   * Neither subject nor text, which may address the user, so that logs and crash reports do not collect them; show
+   * `subject` and `text` to the user.
+   */
   toString(): string {
-    return `${this.subject}: ${this.text}`;
+    return 'BankMessage(…)';
+  }
+
+  /** What Node.js's `util.inspect` and `console.log` show: `toString`, not the fields. */
+  [inspectCustom](): string {
+    return this.toString();
   }
 }

package/src/core/client.ts

@@ -3,6 +3,7 @@ import type { TanMedium, TanMethod } from '../tan/tan-models.js';
 import type { Account } from './account.js';
 import type { Balance } from './balance.js';
 import type { BankInfo, BankMessage } from './bank-info.js';
+import type { FinTsLoginRefusedError } from './errors.js';
 import type { FinTsFeedback } from './feedback.js';
 import type { Transaction, TransactionFormat } from './transaction.js';
 import type { FinTsTransport } from './transport.js';
@@ -25,6 +26,11 @@ export type WarningHandler = (warning: FinTsFeedback) => void;
  * An error thrown by a callback that only informs the app (`onBankMessage`, `onWarning`, `logger`) fails the call once
  * the call's exchange with the bank is over, so that it cannot break off a dialog half-way; an error of the call itself
  * takes precedence.
+ *
+ * The client reads the options once, when it is built: changing them later changes nothing. Its constructor throws
+ * `TypeError` for a `tanCallback` that is no function, another callback that is neither a function nor `undefined` or
+ * `null`, which mean none, a `state` that is neither a string nor either of these, and a `transport` without the
+ * functions `post` and `close`.
  */
 export interface FinTsClientOptions {
   /** Called whenever the bank asks for a TAN or an app approval. */
@@ -36,12 +42,17 @@ export interface FinTsClientOptions {
   /** Picks the TAN medium when the method needs one and the user has several; the first is used without it. */
   tanMediumSelector?: TanMediumSelector;
 
-  /** Receives the free-text messages the bank sends during login. */
+  /**
+   * Receives the free-text messages the bank sends during login. How many there are and how long they are is the
+   * bank's choice, without a limit, so bound what the app shows of them; show their text as text, never as markup.
+   */
   onBankMessage?: BankMessageHandler;
 
   /**
    * Receives the bank's warnings, such as 3951 (switch to another TAN method), but not those the client acts on itself,
-   * such as 3040 (more data follow). Show them to the user with code and text, as the specification asks.
+   * such as 3040 (more data follow). Show them to the user with code and text, as the specification asks. How many
+   * there are and how long they are is the bank's choice, without a limit, so bound what the app shows of them; show
+   * their text as text, never as markup.
    */
   onWarning?: WarningHandler;
 
@@ -49,9 +60,16 @@ export interface FinTsClientOptions {
   logger?: MessageLogger;
 
   /**
-   * The `FinTsClient.state` of a previous session, which skips the bank setup steps.
+   * The `FinTsClient.state` of a previous session, which skips the bank setup steps. A refused login in it keeps the
+   * client from sending the PIN (`FinTsClient.loginRefusal`).
+   *
+   * A state belongs to one client at a time: restore the clients of one bank user one after another, each from the
+   * state the one before saved, never two at once from the same state. The state saved last wins, and could lift a
+   * refused login the other client saved.
    *
-   * A state saved for another user or bank is ignored.
+   * A state saved for another user or bank is ignored, and of one saved for another server of the bank, such as before
+   * the bank moved its FinTS URL, or for FinTS 4.1 by the Dart package, only the refused login and the count of logins
+   * whose answer was lost hold.
    */
   state?: string | undefined;
 
@@ -76,40 +94,74 @@ export interface TransactionQuery {
 /**
  * Read access to a bank account over FinTS.
  *
- * All calls share one bank dialog, so strong authentication happens once per session. Calls run one after another; call
- * `close` when done.
+ * 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. Calls share one bank dialog while it is open, so that 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 `BankInfo.maxTimeout`,
+ * after `selectTanMethod` and `clearLoginRefusal`, once the bank has ended the dialog, and after a message failed with
+ * another error than the bank's (`FinTsBankError`), such as a cancelled approval or a broken connection. Calls run one
+ * after another; call `close` when done.
  *
  * A callback in `FinTsClientOptions` 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`; elsewhere it would wait forever. `close` works
- * from anywhere.
+ * call. On Node.js, Deno 2.1 and Bun 1.2.6 or later such a call fails with `FinTsStateError`; elsewhere it waits
+ * forever. `close` works from anywhere.
  */
 export interface FinTsClient {
   /**
    * Serialized session data: bank and user parameters, customer system ID, the TAN methods the user may use, the chosen
-   * TAN method and medium, and the SEPA account list.
+   * TAN method and medium, the SEPA account list, and a refused login (`loginRefusal`) with the count of logins whose
+   * answer was lost.
    *
-   * Contains no PIN or TAN, but account details, so store it encrypted.
+   * Contains no PIN or TAN, but the user ID and customer ID, the customer system ID, the account holders' names and
+   * account details, and after a refused login the texts and parameters of the bank's return codes as the bank sent
+   * them, which for return code 3072 are the new login data; so store it encrypted. It holds what this client knows,
+   * and replaces the state it was restored from: one client at a time per state (`FinTsClientOptions.state`).
    */
   readonly state: string;
 
+  /**
+   * The refused login that keeps the client from sending the PIN again (`FinTsLoginRefusedError`); `undefined` while
+   * there is none. It is kept in `state` until `clearLoginRefusal`.
+   */
+  readonly loginRefusal: FinTsLoginRefusedError | undefined;
+
   /** Security function code of the TAN method in use, for example `942`; `undefined` before the first login. */
   readonly selectedTanMethod: string | undefined;
 
-  /** Name of the TAN medium sent to the bank, if the method needs one. */
+  /**
+   * Name of the TAN medium in use, if the method needs one, as the app passed it or the bank listed it; one the app
+   * passed goes out without blanks at either end.
+   */
   readonly selectedTanMedium: string | undefined;
 
   /**
    * Switches to another TAN method, and optionally TAN medium, for the following calls.
    *
    * Ends the current dialog, so the next call logs in again with the new method. If the bank does not offer
-   * `securityFunction`, the client picks another method at that login.
+   * `securityFunction`, the client picks another method at that login. Without `tanMedium`, also for `null`, that login
+   * looks the TAN media up where the method needs one. Rejects with `TypeError`, before it ends the dialog, for a
+   * `securityFunction` or `tanMedium` that is no string.
    */
   selectTanMethod(securityFunction: string, tanMedium?: string): Promise<void>;
 
+  /**
+   * Lifts `loginRefusal` and signs with `pin` from now on. Ends the current dialog, so that the next call logs in with
+   * it, and forgets the TAN medium, which the bank may have refused, such as that of a phone the user has replaced: where
+   * the TAN method needs one, the next call looks the media up anew and asks the `tanMediumSelector`.
+   *
+   * Pass a PIN the user has entered after the refusal, never a stored one unasked: banks lock the access after a few
+   * failed logins. Rejects with `TypeError` for a PIN the client cannot send, as its constructor throws, and with the
+   * refusal where it is a `FinTsLoginDataChangedError`: only a new client with the new login data can log in.
+   */
+  clearLoginRefusal(pin: string): Promise<void>;
+
   /** General information about the bank, from the bank parameter data. */
   getBankInfo(): Promise<BankInfo>;
 
-  /** TAN procedures the bank allows for this user. */
+  /**
+   * TAN procedures the bank allows for this user, which the synchronization reports. Where the session has no customer
+   * system ID yet, as without a saved state, this call logs in for it: it may ask `tanMethodSelector` where the bank
+   * refuses the one-step method, and `tanCallback` for an approval.
+   */
   getTanMethods(): Promise<TanMethod[]>;
 
   /** TAN devices registered for this user. */
@@ -124,7 +176,9 @@ export interface FinTsClient {
    * Where the user parameter data carry the complete balance (account extension), possibly from the saved `state`, it
    * comes from there without a query; `Balance.bookedAsOf` tells the day it states.
    *
-   * Throws `FinTsUnsupportedError`, without asking the bank, where the parameter data rule the query out.
+   * Rejects with `FinTsUnsupportedError` where the parameter data rule the query out, without sending it; the login,
+   * which delivers them, may have gone out. Rejects with `TypeError`, before it waits for other calls, for an `account`
+   * that is no `Account`, such as one written to JSON and read back.
    */
   getBalance(account: Account): Promise<Balance>;
 
@@ -133,17 +187,27 @@ export interface FinTsClient {
    * the same day in the bank's order.
    *
    * Only the local calendar day counts, and a day in the future counts as today. Banks typically ask for a TAN when
-   * `from` is more than 90 days ago; see also `Account.dataStatus`. Throws `TypeError` if `from` lies on a day after
-   * `to`, and `FinTsUnsupportedError`, without asking the bank, where the parameter data rule the query out.
+   * `from` is more than 90 days ago; see also `Account.dataStatus`. Rejects with `TypeError`, before it waits for other
+   * calls, if `account` is no `Account`, `from` or `to` is no valid `Date`, `from` lies on a day after `to` or `format`
+   * is no `TransactionFormat`, and with `FinTsUnsupportedError`, without sending the query, where the parameter data
+   * rule it out; the login may have gone out.
    */
   getTransactions(account: Account, query?: TransactionQuery): Promise<Transaction[]>;
 
   /**
-   * Ends the bank dialog and releases the connection.
+   * Ends the bank dialog, releases the connection and forgets the PIN.
    *
    * A running call stops at its next step, also while it waits for a TAN, an app approval or a selection, and fails with
-   * `FinTsStateError`, as do all later calls. A request already on its way is awaited, at most for the transport's
-   * timeout.
+   * `FinTsStateError`, as do all later calls. A request already on its way has five seconds to bring its answer, which
+   * counts as any other: the logger gets it, and the client keeps what it brings, such as the parameter data or the
+   * customer system ID. The call fails with `FinTsStateError` all the same, also where that answer completes it, unless
+   * the answer brings an error, such as a rejected PIN, which the call fails with instead. After those five seconds the
+   * client stops waiting for the request, whatever the transport, and aborts it where the transport supports that, as
+   * `HttpTransport` does: the call fails with `FinTsTransportError` then, as after a broken connection, and an aborted
+   * login counts as one whose answer was lost. After the request, the call sends nothing but the end of its
+   * dialogs, that of an aborted message included, unless the message opened it. These dialog ends have five seconds
+   * once that request, if any, is over: then they are aborted the same way, and none goes out later, so that a bank
+   * that has stopped answering holds up neither `close` nor the call for longer.
    */
   close(): Promise<void>;
 }

package/src/core/config.ts

@@ -1,38 +1,56 @@
+import { optionalBoolean, optionalString, requireString } from '../util/arguments.js';
 import { invalidArgument } from '../util/errors.js';
+import { inspectCustom } from '../util/inspect.js';
+import { isLatin1, trimBlanks } from '../util/text.js';
 
-/** Numeric country code of Germany (ISO 3166), where FinTS banks are. */
+/**
+ * The country code FinTS gives Germany, where FinTS banks are: the ISO 3166 code of the Federal Republic before 1990,
+ * not today's `276`.
+ */
 export const defaultCountryCode = '280';
 
+/**
+ * Longest bank code (Kreditinstitutscode), user or customer ID (data type `id`), product ID (Produktbezeichnung) and
+ * product version FinTS 3.0 takes.
+ */
+const maxBankCodeLength = 30;
+const maxIdLength = 30;
+const maxProductIdLength = 25;
+const maxProductVersionLength = 5;
+
 /** What `FinTsConfig` takes. */
 export interface FinTsConfigInit {
-  /** The bank's FinTS PIN/TAN endpoint; must be https. */
+  /** The bank's FinTS PIN/TAN endpoint; must be https, without user name or password. */
   url: string | URL;
-  /** German bank code (BLZ). */
+  /** Bank code: for a German bank its BLZ, eight digits. */
   bankCode: string;
-  /** Login name (Benutzerkennung / Legitimations-ID). */
+  /** Login name (Benutzerkennung / Legitimations-ID); at most 30 characters. */
   userId: string;
-  /** Customer ID; defaults to `userId`. */
+  /** Customer ID, at most 30 characters; defaults to `userId`. */
   customerId?: string | undefined;
   /** FinTS product registration number from the Deutsche Kreditwirtschaft; at most 25 characters. */
   productId: string;
   /** Version of the app as registered with the product; at most five characters. `1.0` by default. */
   productVersion?: string;
-  /** Numeric country code of the bank, `280` (Germany) by default. */
+  /** Country code of the bank, three digits: `280`, the default, for Germany. */
   countryCode?: string;
   /**
    * Allows plain http for the loopback addresses `localhost`, `127.x.x.x` and `::1`, for tests against a local server.
    *
-   * Any other host must use https, whatever this says: the PIN travels with every message.
+   * Any other host must use https, whatever this says: the PIN travels with every message. The default `HttpTransport`
+   * sends plain http wherever the global `fetch` sends it, though, as it sends https: a replacement of that `fetch` and
+   * a global dispatcher get the PIN, and a proxy that `fetch` takes from the environment sees it unencrypted. See
+   * `HttpTransport`.
    */
   allowInsecureUrl?: boolean;
 }
 
-/** Connection and login data for one bank user. */
+/** Connection and login data for one bank user; frozen, so that the client sends what the constructor has checked. */
 export class FinTsConfig {
-  /** Numeric country code of Germany (ISO 3166), where FinTS banks are. */
+  /** The country code FinTS gives Germany, where FinTS banks are: `280`, not today's ISO 3166 code `276`. */
   static readonly defaultCountryCode = defaultCountryCode;
 
-  readonly url: URL;
+  private readonly href: string;
   readonly bankCode: string;
   readonly userId: string;
   private readonly explicitCustomerId: string | undefined;
@@ -42,8 +60,17 @@ export class FinTsConfig {
   readonly allowInsecureUrl: boolean;
 
   /**
-   * Throws `TypeError` if `url` is not a valid URL, has no host or is not https, unless `allowInsecureUrl` is set and
-   * `url` is a loopback address, and if a login detail or the product is empty: the bank would refuse the login.
+   * Throws `TypeError` if `url` is not a valid URL, has no host, holds a user name or password, or is not https, unless
+   * `allowInsecureUrl` is set and `url` is a loopback address. Throws as well where the bank would refuse the login: for
+   * a login or product detail that is empty, has characters FinTS 3.0 cannot send (it uses ISO 8859-1, so `€` and most
+   * non-Latin letters are not possible) or is longer than its field (30 characters for the bank code, the user ID and
+   * the customer ID, 25 for the product ID, 5 for its version), for a country code of other than three digits, and for
+   * a German bank code of other than eight. Throws as well for a detail of another type than `FinTsConfigInit` names,
+   * such as a number as `bankCode` or the string `'false'` as `allowInsecureUrl`; `null` counts as a detail not given.
+   * The message leaves out the value.
+   *
+   * Drops leading and trailing blanks of the login details and the product, as FinTS sends them without (Formals
+   * B.4.1): `'alice '` is the user `alice`, also for a saved state.
    */
   constructor(init: FinTsConfigInit) {
     // `URL` would read `https:bank` and `https:///bank` as the host `bank`; such a URL is a mistake, not a host.
@@ -56,31 +83,61 @@ export class FinTsConfig {
     } catch {
       throw invalidArgument('Not a valid URL', 'url');
     }
-    this.url = url;
-    this.bankCode = init.bankCode;
-    this.userId = init.userId;
-    this.explicitCustomerId = init.customerId;
-    this.productId = init.productId;
-    this.productVersion = init.productVersion ?? '1.0';
-    this.countryCode = init.countryCode ?? defaultCountryCode;
-    this.allowInsecureUrl = init.allowInsecureUrl ?? false;
+    this.href = url.href;
+    this.allowInsecureUrl = optionalBoolean(init.allowInsecureUrl, 'allowInsecureUrl') ?? false;
     requireSecureUrl(url, this.allowInsecureUrl);
-    requireNotBlank(this.bankCode, 'bankCode');
-    requireNotBlank(this.userId, 'userId');
-    if (this.explicitCustomerId !== undefined) requireNotBlank(this.explicitCustomerId, 'customerId');
-    requireNotBlank(this.productId, 'productId');
-    requireNotBlank(this.productVersion, 'productVersion');
-    requireNotBlank(this.countryCode, 'countryCode');
+    this.countryCode = requireValue(init.countryCode ?? defaultCountryCode, 'countryCode');
+    if (!/^\d{3}$/.test(this.countryCode)) {
+      throw invalidArgument('Must be three digits, 280 for Germany', 'countryCode');
+    }
+    this.bankCode = requireValue(init.bankCode, 'bankCode', maxBankCodeLength);
+    if (this.countryCode === defaultCountryCode && !/^\d{8}$/.test(this.bankCode)) {
+      throw invalidArgument('A German bank code (BLZ) has eight digits', 'bankCode');
+    }
+    this.userId = requireValue(init.userId, 'userId', maxIdLength);
+    const customerId = optionalString(init.customerId, 'customerId');
+    this.explicitCustomerId =
+      customerId === undefined ? undefined : requireValue(customerId, 'customerId', maxIdLength);
+    this.productId = requireValue(init.productId, 'productId', maxProductIdLength);
+    this.productVersion = requireValue(init.productVersion ?? '1.0', 'productVersion', maxProductVersionLength);
+    Object.freeze(this);
+  }
+
+  /**
+   * The bank's FinTS PIN/TAN endpoint, as checked by the constructor. A new `URL` on each access, so that changing one
+   * cannot change where the client posts the PIN.
+   */
+  get url(): URL {
+    return new URL(this.href);
   }
 
   /** Customer ID; defaults to `userId`. */
   get customerId(): string {
     return this.explicitCustomerId ?? this.userId;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: the bank code, neither the login data nor the product ID. */
+  [inspectCustom](): string {
+    return `FinTsConfig(${this.bankCode})`;
+  }
+}
+
+/**
+ * `value` without leading and trailing blanks; throws `TypeError` if it is no string, nothing is left, or what is left
+ * is not sendable (`requireLatin1`) or longer than `maxLength`: cut short, a value would be one the bank does not know.
+ */
+function requireValue(value: unknown, name: string, maxLength = Number.POSITIVE_INFINITY): string {
+  const trimmed = trimBlanks(requireString(value, name));
+  if (trimmed === '') throw invalidArgument('Must not be empty', name);
+  requireLatin1(trimmed, name);
+  if (trimmed.length > maxLength) throw invalidArgument(`At most ${maxLength} characters in FinTS 3.0`, name);
+  return trimmed;
 }
 
-function requireNotBlank(value: string, name: string): void {
-  if (value.trim() === '') throw invalidArgument('Must not be empty', name);
+/** `text`, unless it has characters FinTS 3.0 cannot send (ISO 8859-1 only); the message leaves out the value. */
+export function requireLatin1(text: string, name: string): string {
+  if (!isLatin1(text)) throw invalidArgument('Contains characters FinTS 3.0 cannot send (ISO 8859-1 only)', name);
+  return text;
 }
 
 /** The host of `url` without the brackets of an IPv6 address, as `URL` writes it. */
@@ -92,24 +149,27 @@ export function hostOf(url: URL): string {
 /**
  * Throws `TypeError` unless `url` names a host and uses https: the PIN travels with every message.
  *
- * With `allowInsecure`, http is accepted for loopback hosts only.
+ * With `allowInsecure`, http is accepted for loopback hosts only. Throws as well for a user name or password in `url`:
+ * `fetch` refuses such a URL, with the whole URL in its error message. The message leaves them out.
  */
-export function requireSecureUrl(url: URL, allowInsecure = false): void {
+function requireSecureUrl(url: URL, allowInsecure = false): void {
   if (hostOf(url) === '') throw invalidArgument('The URL has no host', 'url');
+  if (url.username !== '' || url.password !== '') throw invalidArgument('The URL must not contain credentials', 'url');
   const loopbackHttp = allowInsecure && url.protocol === 'http:' && isLoopback(hostOf(url));
   if (url.protocol !== 'https:' && !loopbackHttp) throw invalidArgument('PIN/TAN requires an https URL', 'url');
 }
 
 /**
- * Throws `TypeError` for an empty PIN, which the bank would count as a failed attempt, and for one with leading or
- * trailing blanks: FinTS values carry none (Formals B.4.1), so such a PIN could only go out changed.
+ * `pin`, unless FinTS 3.0 cannot send it: throws `TypeError` for an empty PIN, which the bank would count as a failed
+ * attempt, for one with leading or trailing blanks, which would go out without them since FinTS values carry none
+ * (Formals B.4.1), and for one with characters outside ISO 8859-1.
  *
  * The message leaves out the value.
  */
 export function requirePin(pin: string): string {
-  if (pin.trim() === '') throw invalidArgument('The PIN is empty', 'pin');
-  if (pin.trim() !== pin) throw invalidArgument('The PIN begins or ends with a blank', 'pin');
-  return pin;
+  if (trimBlanks(pin) === '') throw invalidArgument('The PIN is empty', 'pin');
+  if (trimBlanks(pin) !== pin) throw invalidArgument('The PIN begins or ends with a blank', 'pin');
+  return requireLatin1(pin, 'pin');
 }
 
 /**