feat: add decoupled TAN support (pushTAN/app-based authentication)

Implements FinTS 3.0 decoupled TAN flow (tanProcess=2) for async app-based
approval. Adds DecoupledTanManager with configurable polling, state machine
(INITIATED→CONFIRMED), cancellation, and timeout handling. Dialog gains
handleDecoupledTan/cancelDecoupledTan/checkDecoupledTanStatus methods.
Fixes HKTAN process code to use "S" for status polling. HITANS timing fields
(seconds) are now correctly converted to ms. Integration tests updated to
reflect 0-second server values and timing-safe mock delays.

Author: dtrunk90

packages/fints/src/decoupled-tan/__tests__/test-decoupled-tan-integration.ts

@@ -43,8 +43,10 @@ describe("Decoupled TAN Integration", () => {
                 tanProcess: "2",
                 name: "pushTAN",
                 decoupledMaxStatusRequests: 60,
-                decoupledWaitBeforeFirstStatusRequest: 2000,
-                decoupledWaitBetweenStatusRequests: 2000,
+                // Values are in seconds per HITANS spec (converted to ms by DecoupledTanManager).
+                // Use 0 so the test config (10ms) effectively drives timing.
+                decoupledWaitBeforeFirstStatusRequest: 0,
+                decoupledWaitBetweenStatusRequests: 0,
             } as any,
         ];
     });
@@ -220,35 +222,57 @@ describe("Decoupled TAN Integration", () => {
         }, 10000);
 
         test("should handle cancellation gracefully", async () => {
-            // Mock pending response
-            mockConnection.send = jest.fn().mockResolvedValue({
-                dialogId: "test-dialog",
-                returnValues: jest.fn().mockReturnValue(new Map([["3956", { code: "3956", message: "Pending" }]])),
-                success: true,
-            });
+            // Mock pending response with a delay so cancel fires while a request is in flight
+            mockConnection.send = jest.fn().mockImplementation(
+                () =>
+                    new Promise((resolve) =>
+                        setTimeout(
+                            () =>
+                                resolve({
+                                    dialogId: "test-dialog",
+                                    returnValues: jest
+                                        .fn()
+                                        .mockReturnValue(new Map([["3956", { code: "3956", message: "Pending" }]])),
+                                    success: true,
+                                }),
+                            30,
+                        ),
+                    ),
+            );
 
             const pollPromise = dialog.handleDecoupledTan("ref123", "Please confirm");
 
-            // Cancel after a short delay
+            // Cancel before the first mock response resolves
             setTimeout(() => {
                 dialog.cancelDecoupledTan();
-            }, 100);
+            }, 10);
 
             await expect(pollPromise).rejects.toThrow(/cancelled/i);
         }, 10000);
 
         test("should track status during polling", async () => {
-            // Mock pending response
-            mockConnection.send = jest.fn().mockResolvedValue({
-                dialogId: "test-dialog",
-                returnValues: jest.fn().mockReturnValue(new Map([["3956", { code: "3956", message: "Pending" }]])),
-                success: true,
-            });
+            // Mock pending response with a delay so status check runs while request is in flight
+            mockConnection.send = jest.fn().mockImplementation(
+                () =>
+                    new Promise((resolve) =>
+                        setTimeout(
+                            () =>
+                                resolve({
+                                    dialogId: "test-dialog",
+                                    returnValues: jest
+                                        .fn()
+                                        .mockReturnValue(new Map([["3956", { code: "3956", message: "Pending" }]])),
+                                    success: true,
+                                }),
+                            50,
+                        ),
+                    ),
+            );
 
             const pollPromise = dialog.handleDecoupledTan("ref123", "Please confirm");
 
-            // Check status while polling
-            await new Promise((resolve) => setTimeout(resolve, 100));
+            // Check status while the first mock response is still pending
+            await new Promise((resolve) => setTimeout(resolve, 20));
             const status = dialog.checkDecoupledTanStatus();
 
             expect(status).toBeDefined();

packages/fints/src/decoupled-tan/decoupled-tan-manager.ts

@@ -5,6 +5,7 @@ import { HKTAN } from "../segments";
 import { Response } from "../response";
 import { TanMethod } from "../tan-method";
 import { Request } from "../request";
+import { escapeFinTS } from "../utils";
 
 /**
  * FinTS return code constants for decoupled TAN authentication
@@ -15,7 +16,8 @@ const RETURN_CODE_PENDING_CONFIRMATION = "3956"; // Strong customer authenticati
 /**
  * HKTAN process type for decoupled TAN status polling
  */
-const HKTAN_PROCESS_DECOUPLED_STATUS = "2"; // Decoupled/asynchronous authentication status check
+// FinTS 3.0 Security PIN/TAN spec §TAN-Prozess=S: status polling for decoupled TAN
+const HKTAN_PROCESS_DECOUPLED_STATUS = "S";
 
 /**
  * Default configuration for decoupled TAN
@@ -85,16 +87,17 @@ export class DecoupledTanManager {
             ...config,
         };
 
-        // Override with server-provided values if available
+        // Override with server-provided values if available.
+        // HITANS timing fields are in seconds; convert to ms for internal use.
         if (tanMethod) {
             if (tanMethod.decoupledMaxStatusRequests !== undefined) {
                 this.config.maxStatusRequests = tanMethod.decoupledMaxStatusRequests;
             }
             if (tanMethod.decoupledWaitBeforeFirstStatusRequest !== undefined) {
-                this.config.waitBeforeFirstStatusRequest = tanMethod.decoupledWaitBeforeFirstStatusRequest;
+                this.config.waitBeforeFirstStatusRequest = tanMethod.decoupledWaitBeforeFirstStatusRequest * 1000;
             }
             if (tanMethod.decoupledWaitBetweenStatusRequests !== undefined) {
-                this.config.waitBetweenStatusRequests = tanMethod.decoupledWaitBetweenStatusRequests;
+                this.config.waitBetweenStatusRequests = tanMethod.decoupledWaitBetweenStatusRequests * 1000;
             }
         }
 
@@ -307,7 +310,7 @@ export class DecoupledTanManager {
                 segNo: 3, // Standard position for HKTAN in status-only requests
                 version,
                 process: HKTAN_PROCESS_DECOUPLED_STATUS,
-                aref: this.status.transactionReference,
+                aref: escapeFinTS(this.status.transactionReference),
             }),
         ];
 
@@ -328,6 +331,10 @@ export class DecoupledTanManager {
         // Send the request using the dialog's connection
         const response = await this.dialog.connection.send(request);
 
+        // Keep dialog state in sync (dialog.send() is not used here to avoid TanRequiredError on 0030)
+        this.dialog.dialogId = response.dialogId;
+        this.dialog.msgNo++;
+
         return response;
     }
 

packages/fints/src/dialog.ts

@@ -7,6 +7,7 @@ import {
     HKEND,
     HISALS,
     HIKAZS,
+    HICAZS,
     HICDBS,
     HIUPD,
     HITANS,
@@ -113,6 +114,15 @@ export class Dialog extends DialogConfig {
      * Set to `true` during synchronization if the bank returns a HIKAZS parameter segment.
      */
     public supportsTransactions = false;
+    /**
+     * Whether the bank supports fetching CAMT account transactions (HKCAZ).
+     * Set to `true` during synchronization if the bank returns a HICAZS parameter segment.
+     */
+    public supportsCamtTransactions = false;
+    /** Version of the HKCAZ segment supported by the bank (from HICAZS). */
+    public hicazsVersion = 1;
+    /** CAMT format URI advertised by the bank in HICAZS, required in HKCAZ requests. */
+    public hicazsCamtFormat = "";
     /**
      * Whether the bank supports fetching standing orders (HKCDB).
      * Set to `true` during synchronization if the bank returns a HICDBS parameter segment.
@@ -189,6 +199,11 @@ export class Dialog extends DialogConfig {
         const hikazsVer = response.segmentMaxVersion(HIKAZS);
         this.supportsTransactions = hikazsVer > 0;
         if (hikazsVer > 0) this.hikazsVersion = hikazsVer;
+        const hicazsVer = response.segmentMaxVersion(HICAZS);
+        this.supportsCamtTransactions = hicazsVer > 0;
+        if (hicazsVer > 0) this.hicazsVersion = hicazsVer;
+        const hicazs = response.findSegment(HICAZS);
+        if (hicazs?.camtFormat) this.hicazsCamtFormat = hicazs.camtFormat;
         const hicdbVer = response.segmentMaxVersion(HICDBS);
         this.supportsStandingOrders = hicdbVer > 0;
         if (hicdbVer > 0) this.hicdbVersion = hicdbVer;

packages/fints/src/segments/hktan.ts

@@ -22,7 +22,7 @@ export class HKTAN extends SegmentClass(HKTANProps) {
 
     protected serialize() {
         const { process, segmentReference, aref, medium, version } = this;
-        if (!["2", "4"].includes(process)) {
+        if (!["2", "4", "S"].includes(process)) {
             throw new Error(`HKTAN process ${process} not implemented.`);
         }
         if (![3, 4, 5, 6, 7].includes(version)) {
@@ -49,7 +49,7 @@ export class HKTAN extends SegmentClass(HKTANProps) {
                     return [process];
                 }
             }
-        } else if (process === "2") {
+        } else if (process === "2" || process === "S") {
             if (version === 6 || version === 7) {
                 return [process, "", "", "", aref, "N"];
             }