lib-fints 1.0.0

package/README.md

@@ -0,0 +1,216 @@
+# Lib-FinTS
+
+A Typescript/Javascript client library for Online-Banking via the FinTS 3.0 protocol with PIN/TAN. The library has no dependencies on other libraries
+
+## Getting Started
+
+These instructions will show you how to install the library on your local machine and give a quick sample of how to use the library
+
+### Prerequisites
+
+#### Product Registration
+
+In order to communicate with banks via the FinTS protocol you have to register a product ID with the german banking industry (Deutsche Kreditwirtschaft) which you need to pass as part of the configuration to the client:
+
+> In order to fulfill the PSD2 requirements regarding transparency about the software used by customers, the German Banking Industry has established a process for registering FinTS products in order to be able to provide customers with information regarding FinTS usage.
+> FinTS product registration is currently offered free of charge by the German Banking Industry.
+
+[ZKA Registration Website](https://www.hbci-zka.de/register/prod_register.htm)
+
+### Runtime Environment
+
+The library is written in Typescript and compiled to the ES2022 Javascript language standard which means a minimum Node version of 18 is required.
+
+**A note about Browsers:**
+It wouldn't be hard to make the code compatible with a browser environment, but communicating directly from the front-end with a bank server will most likely fail because of the imposed CORS restrictions from web browsers and the lack of corresponding CORS headers in bank server responses.
+
+### Installing
+
+Installation is straight forward by simply adding the npm package. The package has no further dependencies on other packages.
+
+```
+npm i lib-fints
+```
+
+### Sample Usage
+
+The main public API of this library is the `FinTSClient` class and `FinTSConfig` class. In order to instantiate the client you need to provide a configration instance. There are basically two ways to initialize a configuration object, one is when you communicate with a bank for the first time and the other when you already have banking information from a prevous session available (more on that later).
+
+If you don't have any previous banking information available you can use the static `forFirstTimeUse()` factory method like this:
+
+```typescript
+const config = FinTSConfig.forFirstTimeUse(productId, productVersion, bankUrl, bankId, userId, pin);
+
+const client = new FinTSClient(config);
+```
+
+Then you should first make a synchronization call to get banking and account information:
+
+```typescript
+let syncResponse = await client.synchronize();
+```
+
+you should always check the `success` and `requiresTan` properties of any response object because other data might only be available when `success=true` and `requiresTan=false`.
+in any case you can also check the `bankAnswers` array for return messages from the bank which may contain the reasons for a failed request.
+
+If the call is successfull the response will contain a `bankingInformation` object filled with all the relevant information provided by the bank from synchronization:
+
+```typescript
+export type BankingInformation = {
+  systemId: string;
+  bpd?: BPD;
+  upd?: UPD;
+  bankMessages: BankMessage[];
+};
+```
+
+The BPD object (_BankParameterDaten_) contains general information (e.g. available TAN methods and allowed transactions) and the UPD object (_UserParameterDaten_) user-specific information which is mainly the list of the user's bank accounts.
+
+Unfortunately with this first synchronization call most banks will most likely only return most of the BPA information but no UPD (accounts) information, which is needed to fetch balances or statements. The reason for this is that you need to specify a TAN method before making the synchronization call, but how would you know which TAN methods are available and how to specify them? This is why you need to make a second synchronization call with a TAN method selected from the `availableTanMethodIds`in the BPA, returned from the first synchronization call:
+
+```typescript
+// for simplicity, we just select the first available TAN method
+client.selectTanMethod(syncResponse.bankingInformation.BPD.availableTanMethodIds[0]);
+```
+
+now you can repeat the syncronization call from above and it will return additional data including the UPD with the account information.
+
+Finally you can start fetching balances or statements:
+
+```typescript
+// for simplicity, use the first account
+const account = syncResponse.bankingInformation.upd.bankAccounts[0];
+
+// fetch the current balance
+const balanceResponse = await client.getAccountBalance(account.accountNumber);
+
+// fetch all available statements
+const statementResponse = await client.getAccountStatements(account.accountNumber);
+```
+
+These are only the most basic steps needed to retrieve information from the bank. It kept many questions unanswered like "how to handle TANs" or "how to avoid synchronizations every time you start a new session". These are explained in the corresponding sections below.
+
+## More detailed API Description
+
+### Handle TAN challenges from the bank
+
+Most transactions may require authorization with a two step TAN process. As mentioned above in the sample, every response may set the `requiresTan`property to `true` which means that the response does not include the expected transaction data, but some additional TAN related properties. You first need to handle this TAN challenge by asking the user for the TAN and sending it back to the bank to continue the process and retrieve the actual transaction result:
+
+```typescript
+// we use the node readline interface later to ask the user for a TAN
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+let response = await client.getAccountStatements(account.accountNumber);
+
+if (!response.success) {
+  return;
+}
+
+// need to check if a TAN is required to continue the transaction
+if (response.requiresTan) {
+  // asking the user for the TAN, using the tanChallenge property
+  const tan = await rl.question(response.tanChallenge + ': ');
+  // continue the transaction by providing the tanReference from the response and the entered TAN
+  response = await client.getAccountStatementsWithTan(response.tanReference!, tan);
+}
+```
+
+The `FinTSClient`contains for every transaction method like `synchronize()` or `getAccountStatements()` a corresponding `...WithTan()` method which needs to be called to continue the transaction with the given `tanReference` returned in the first response. The response object of this second call should now contain all transaction related data, assuming `success=true`.
+
+### Starting a session from saved banking information
+
+As mentioned earlier there is a second way to initialize the `FinTSClient` with a `FinTSConfig` when you already performed a synchronization in a previous session and this is by providing the `bankingInformation` object received from previous uses. This `bankingInformation` object, which contains the general bank (BPD) and accounts information (UPD), should be persisted after a session and reloaded in the next session.
+This not only saves you from making the same synchronization requests every time before making a transaction, but the sychronization will also assign a `systemId` (a property in `bankingInformation`) to your client which should stay the same once assigned.
+
+```typescript
+const config = FinTSConfig.fromBankingInformation(
+  productId,
+  productVersion,
+  bankingInformation,
+  userId,
+  pin,
+  tanMethodId,
+  tanMediaName // when also needed (see below)
+);
+const client = new FinTSClient(config);
+```
+
+You should also set the TAN method to use, by using the optional `tanMethodId` and `tanMediaName` parameters or calling `client.selectTanMethod()` before making the first transaction.
+
+#### Tan Media
+
+It might be the case that you have more than one active TAN media available (like multiple mobile phones) and the bank requires you to also specify which TAN media to use.
+You can find out if this is the case by inspecting the `TanMethod` object in the BPD.
+You can get a list of all available TAN methods from the `config.availableTanMethods` property or if you already selected a TAN method with `config.selectedTanMethod`.
+
+```typescript
+export type TanMethod = {
+  id: number;
+  name: string;
+  version: number;
+  activeTanMediaCount: number;
+  activeTanMedia: string[];
+  tanMediaRequirement: TanMediaRequirement;
+};
+```
+
+The `TanMethod` object contains a property `tanMediaRequirement` and if this is set to `TanMediaRequirement.Required`, you also need to select a TAN media, either by providing the name in the configuration factory method `FinTSConfig.fromBankingInformation()` or by using `client.selectTanMedia()`.
+
+The property `activeTanMedia` contains a list of the TAN media names you can use for selection.
+
+#### Banking Information may be updated any time
+
+The `bankingInformation` is primarily obtained by the `synchronize()` calls as seen above. But what if the banking information changed since the last synchronization call and how would you know? For this reason the BPD and UPD are versioned and with every transaction made, not just synchronizations, the currently used versions are provided to the bank and if something changed, the bank will sent back new versions of the BPD and UPD respectively. This is all handled by the client but you need to check the `bankingInformationUpdated` property, which is available in every response, which tells you if there were changes and make sure to persist the new version for future sessions. You can always get the up-to-date version of the `bankingInformation` object with `config.bankingInformation`.
+
+### Debugging
+
+If you need to debug issues and the `response.bankAnswers` don't provide enough information, you can enable debugging of messages with:
+
+```typescript
+config.debugEnabled = true;
+```
+
+This will print out all sent messages and received responses to the console in a structured format.
+
+## Limitations
+
+- Only FinTS 3.0 is supported (older versions may not work)
+- Only PIN/TAN security is supported
+- Currently only the following transactions are supported:
+  - Synchronize bank and account information
+  - Fetching account balances
+  - Fetching account statements
+
+Implementing further transactions should be straight forward and contributions are highly appreciated
+
+### Successfully tested with the following banks
+
+- DKB
+- ING-DiBa
+- Renault Bank Direkt
+
+## Built With
+
+- [Typescript](https://www.typescriptlang.org/) - Programming Language
+- [Vitest](https://vitest.dev/) - Testing Framework
+- [pnpm](https://pnpm.io/) - Package manager
+
+## Contributing
+
+Feel free to create an issue if you want to report a bug.
+
+If you tested this library with some other bank it would be great to hear from you and update the information on this page
+
+As this is a free-time project, a lot of things are still remaining which could be added to this library, especially other kinds of transactions. If you want to contribute with pull-requests this would be highly appreciated
+
+## License
+
+This project is licensed under the LGPL 3.0 License - see the [LICENSE.md](LICENSE.md) file for details
+
+## References
+
+- [Product Registration](https://www.hbci-zka.de/register/prod_register.htm)
+- [FinTS 3.0 Specification](https://www.hbci-zka.de/spec/3_0.htm)

package/dist/accountBalance.js

@@ -0,0 +1 @@
+export {};

package/dist/bankAccount.js

@@ -0,0 +1,34 @@
+export var AccountType;
+(function (AccountType) {
+    AccountType["CheckingAccount"] = "CheckingAccount";
+    AccountType["SavingsAccount"] = "SavingsAccount";
+    AccountType["FixedDepositAccount"] = "FixedDepositAccount";
+    AccountType["SecuritiesAccount"] = "SecuritiesAccount";
+    AccountType["LoanMortgageAccount"] = "LoanMortgageAccount";
+    AccountType["CreditCardAccount"] = "CreditCardAccount";
+    AccountType["InvestmentCompanyFund"] = "InvestmentCompanyFund";
+    AccountType["HomeSavingsContract"] = "HomeSavingsContract";
+    AccountType["InsurancePolicy"] = "InsurancePolicy";
+    AccountType["Miscellaneous"] = "Miscellaneous";
+})(AccountType || (AccountType = {}));
+export function finTsAccountTypeToEnum(accountType) {
+    if (accountType >= 1 && accountType <= 9)
+        return AccountType.CheckingAccount;
+    if (accountType >= 10 && accountType <= 19)
+        return AccountType.SavingsAccount;
+    if (accountType >= 20 && accountType <= 29)
+        return AccountType.FixedDepositAccount;
+    if (accountType >= 30 && accountType <= 39)
+        return AccountType.SecuritiesAccount;
+    if (accountType >= 40 && accountType <= 49)
+        return AccountType.LoanMortgageAccount;
+    if (accountType >= 50 && accountType <= 59)
+        return AccountType.CreditCardAccount;
+    if (accountType >= 60 && accountType <= 69)
+        return AccountType.InvestmentCompanyFund;
+    if (accountType >= 70 && accountType <= 79)
+        return AccountType.HomeSavingsContract;
+    if (accountType >= 80 && accountType <= 89)
+        return AccountType.InsurancePolicy;
+    return AccountType.Miscellaneous;
+}

package/dist/bankAnswer.js

@@ -0,0 +1 @@
+export {};

package/dist/bankTransaction.js

@@ -0,0 +1 @@
+export {};

package/dist/bankingInformation.js

@@ -0,0 +1 @@
+export {};

package/dist/bpd.js

@@ -0,0 +1 @@
+export {};

package/dist/client.js

@@ -0,0 +1,165 @@
+import { Dialog } from './dialog.js';
+import { HKTAB } from './segments/HKTAB.js';
+import { StatementInteraction } from './interactions/statementInteraction.js';
+import { BalanceInteraction } from './interactions/balanceInteraction.js';
+import { FinTSConfig } from './config.js';
+import { InitDialogInteraction } from './interactions/initDialogInteraction.js';
+import { TanMediaInteraction } from './interactions/tanMediaInteraction.js';
+import { HKSAL } from './segments/HKSAL.js';
+import { HKKAZ } from './segments/HKKAZ.js';
+/**
+ * A client to communicate with a bank over the FinTS protocol
+ */
+export class FinTSClient {
+    config;
+    openCustomerInteractions = new Map();
+    /**
+     * Creates a new FinTS client
+     * @param config - the configuration for the client, use the static factory methods FinTSConfig.forFirstTimeUse or FinTSConfig.fromBankingInformation to create a configuration
+     */
+    constructor(config) {
+        this.config = config;
+        if (!config) {
+            throw new Error('configuration must be provided when creating a FinTSClient');
+        }
+        if (!(config instanceof FinTSConfig)) {
+            throw new Error('configuration must be an instance of class FinTSConfig');
+        }
+    }
+    /**
+     * Selects a TAN method by its ID
+     * @param tanMethodId - the ID of the TAN method to select, get the ID from FinTSClient.config.availableTanMethods
+     * @returns the selected TAN method
+     */
+    selectTanMethod(tanMethodId) {
+        this.config.selectTanMethod(tanMethodId);
+        return this.config.selectedTanMethod;
+    }
+    /**
+     * Selects a TAN media by its name
+     * @param tanMediaName - the name of the TAN media to select corresponding to a name in TanMethod.activeTanMedia
+     */
+    selectTanMedia(tanMediaName) {
+        this.config.selectTanMedia(tanMediaName);
+    }
+    /**
+     * Synchronizes information with the bank, updating config.bankingInformation
+     * @returns the synchronization response
+     */
+    async synchronize() {
+        const dialog = new Dialog(this.config);
+        const syncResponse = await this.initDialog(dialog, true);
+        if (!syncResponse.success || syncResponse.requiresTan) {
+            return syncResponse;
+        }
+        if (this.config.selectedTanMethod && this.config.isTransactionSupported(HKTAB.Id)) {
+            const tanMediaResponse = await dialog.startCustomerOrderInteraction(new TanMediaInteraction());
+            let tanMethod = this.config.selectedTanMethod;
+            if (tanMethod) {
+                tanMethod.activeTanMedia = tanMediaResponse.tanMediaList;
+            }
+            syncResponse.bankAnswers.push(...tanMediaResponse.bankAnswers);
+        }
+        await dialog.end();
+        return syncResponse;
+    }
+    /**
+     * Continues the synchronization transaction when a TAN is required
+     * @param tanReference The TAN reference provided in the first call's response
+     * @param tan The TAN entered by the user
+     * @returns the synchronization response
+     */
+    async synchronizeWithTan(tanReference, tan) {
+        return this.continueCustomerInteractionWithTan(tanReference, tan);
+    }
+    /**
+     * Checks if the bank supports fetching an account balance in general or for the given account number when provided
+     * @param accountNumber when the account number is provided, checks if the account supports fetching the balance
+     * @returns true if the bank (and account) supports fetching the account balance
+     */
+    canGetAccountBalance(accountNumber) {
+        return accountNumber
+            ? this.config.isAccountTransactionSupported(accountNumber, HKSAL.Id)
+            : this.config.isTransactionSupported(HKSAL.Id);
+    }
+    /**
+     * Fetches the account balance for the given account number
+     * @param accountNumber - the account number to fetch the balance for, must be an account available in the config.baningInformation.UPD.accounts
+     * @returns the account balance response
+     */
+    async getAccountBalance(accountNumber) {
+        return this.startCustomerOrderInteraction(new BalanceInteraction(accountNumber));
+    }
+    /**
+     * Continues the account balance fetching when a TAN is required
+     * @param tanReference The TAN reference provided in the first call's response
+     * @param tan The TAN entered by the user
+     * @returns the account balance response
+     */
+    async getAccountBalanceWithTan(tanReference, tan) {
+        return this.continueCustomerInteractionWithTan(tanReference, tan);
+    }
+    /**
+     * Checks if the bank supports fetching account statements in general or for the given account number when provided
+     * @param accountNumber when the account number is provided, checks if the account supports fetching of statements
+     * @returns true if the bank (and account) supports fetching account statements
+     */
+    canGetAccountStatements(accountNumber) {
+        return accountNumber
+            ? this.config.isAccountTransactionSupported(accountNumber, HKKAZ.Id)
+            : this.config.isTransactionSupported(HKKAZ.Id);
+    }
+    /**
+     * Fetches the account statements for the given account number
+     * @param accountNumber - the account number to fetch the statements for, must be an account available in the config.baningInformation.UPD.accounts
+     * @param from - an optional start date of the period to fetch the statements for
+     * @param to - an optional end date of the period to fetch the statements for
+     * @returns an account statements response containing an array of statements
+     */
+    async getAccountStatements(accountNumber, from, to) {
+        return this.startCustomerOrderInteraction(new StatementInteraction(accountNumber, from, to));
+    }
+    /**
+     * Continues the account statements fetching when a TAN is required
+     * @param tanReference The TAN reference provided in the first call's response
+     * @param tan The TAN entered by the user
+     * @returns an account statements response containing an array of statements
+     */
+    async getAccountStatementsWithTan(tanReference, tan) {
+        return this.continueCustomerInteractionWithTan(tanReference, tan);
+    }
+    async startCustomerOrderInteraction(interaction) {
+        const dialog = new Dialog(this.config);
+        const syncResponse = await this.initDialog(dialog);
+        if (!syncResponse.success || syncResponse.requiresTan) {
+            return syncResponse;
+        }
+        const clientResponse = await dialog.startCustomerOrderInteraction(interaction);
+        if (clientResponse.requiresTan) {
+            this.openCustomerInteractions.set(clientResponse.tanReference, interaction);
+        }
+        else {
+            await dialog.end();
+        }
+        return clientResponse;
+    }
+    async continueCustomerInteractionWithTan(tanReference, tan) {
+        const interaction = this.openCustomerInteractions.get(tanReference);
+        if (!interaction) {
+            throw new Error('No open customer interaction found for TAN reference: ' + tanReference);
+        }
+        const dialog = interaction.dialog;
+        const response = await dialog.sendTanMessage(interaction.segId, tanReference, tan);
+        await dialog.end();
+        this.openCustomerInteractions.delete(tanReference);
+        return interaction.getClientResponse(response);
+    }
+    async initDialog(dialog, syncSystemId = false) {
+        const interaction = new InitDialogInteraction(this.config, syncSystemId);
+        const initResponse = await dialog.initialize(interaction);
+        if (initResponse.requiresTan) {
+            this.openCustomerInteractions.set(initResponse.tanReference, interaction);
+        }
+        return initResponse;
+    }
+}

package/dist/codes.js

@@ -0,0 +1,79 @@
+export var Language;
+(function (Language) {
+    Language[Language["Default"] = 0] = "Default";
+    Language[Language["German"] = 1] = "German";
+    Language[Language["English"] = 2] = "English";
+    Language[Language["French"] = 3] = "French";
+})(Language || (Language = {}));
+export var Service;
+(function (Service) {
+    Service[Service["Tonline"] = 1] = "Tonline";
+    Service[Service["TcpIp"] = 2] = "TcpIp";
+    Service[Service["Https"] = 3] = "Https";
+})(Service || (Service = {}));
+export var HashAlgorithm;
+(function (HashAlgorithm) {
+    HashAlgorithm[HashAlgorithm["SHA1"] = 1] = "SHA1";
+    HashAlgorithm[HashAlgorithm["SHA256"] = 3] = "SHA256";
+    HashAlgorithm[HashAlgorithm["SHA384"] = 4] = "SHA384";
+    HashAlgorithm[HashAlgorithm["SHA512"] = 5] = "SHA512";
+    HashAlgorithm[HashAlgorithm["SHA256_256"] = 6] = "SHA256_256";
+})(HashAlgorithm || (HashAlgorithm = {}));
+export var SyncMode;
+(function (SyncMode) {
+    SyncMode[SyncMode["NewSystemId"] = 0] = "NewSystemId";
+    SyncMode[SyncMode["LastProcessedMsgNr"] = 1] = "LastProcessedMsgNr";
+    SyncMode[SyncMode["SignatureId"] = 2] = "SignatureId";
+})(SyncMode || (SyncMode = {}));
+export var LimitType;
+(function (LimitType) {
+    LimitType["SingleOrder"] = "E";
+    LimitType["Day"] = "T";
+    LimitType["Week"] = "W";
+    LimitType["Month"] = "M";
+    LimitType["Time"] = "Z";
+})(LimitType || (LimitType = {}));
+export var UpdUsage;
+(function (UpdUsage) {
+    UpdUsage[UpdUsage["MissingNotAllowed"] = 0] = "MissingNotAllowed";
+    UpdUsage[UpdUsage["MissingUnknown"] = 1] = "MissingUnknown";
+})(UpdUsage || (UpdUsage = {}));
+export var CreditDebit;
+(function (CreditDebit) {
+    CreditDebit["Credit"] = "C";
+    CreditDebit["Debit"] = "D";
+})(CreditDebit || (CreditDebit = {}));
+export var TanMediaType;
+(function (TanMediaType) {
+    TanMediaType[TanMediaType["All"] = 0] = "All";
+    TanMediaType[TanMediaType["Active"] = 1] = "Active";
+    TanMediaType[TanMediaType["Available"] = 2] = "Available";
+})(TanMediaType || (TanMediaType = {}));
+export var TanMediaClass;
+(function (TanMediaClass) {
+    TanMediaClass["All"] = "A";
+    TanMediaClass["List"] = "L";
+    TanMediaClass["TanGenerator"] = "G";
+    TanMediaClass["Mobile"] = "M";
+    TanMediaClass["Secoder"] = "S";
+    TanMediaClass["Bilateral"] = "B";
+})(TanMediaClass || (TanMediaClass = {}));
+export var TanMediaRequirement;
+(function (TanMediaRequirement) {
+    TanMediaRequirement[TanMediaRequirement["NotAllowed"] = 0] = "NotAllowed";
+    TanMediaRequirement[TanMediaRequirement["Optional"] = 1] = "Optional";
+    TanMediaRequirement[TanMediaRequirement["Required"] = 2] = "Required";
+})(TanMediaRequirement || (TanMediaRequirement = {}));
+export var TanStatus;
+(function (TanStatus) {
+    TanStatus[TanStatus["Active"] = 1] = "Active";
+    TanStatus[TanStatus["Available"] = 2] = "Available";
+    TanStatus[TanStatus["ActiveFollowUpCard"] = 3] = "ActiveFollowUpCard";
+    TanStatus[TanStatus["AvailableFollowUpCard"] = 4] = "AvailableFollowUpCard";
+})(TanStatus || (TanStatus = {}));
+export var TanUsage;
+(function (TanUsage) {
+    TanUsage[TanUsage["All"] = 0] = "All";
+    TanUsage[TanUsage["Single"] = 1] = "Single";
+    TanUsage[TanUsage["MobileAndGenerator"] = 2] = "MobileAndGenerator";
+})(TanUsage || (TanUsage = {}));