feat: add decoupled TAN and CAMT.052 support

[dtrunk90]

Summary

This PR adds two related features needed for Sparda Bank (and other banks using modern FinTS authentication and CAMT-based account statements):

Decoupled TAN (pushTAN / app-based authentication)

• Implements the FinTS 3.0 decoupled TAN flow (tanProcess=2) where transaction approval happens asynchronously on a separate device (e.g. a mobile banking app)
• Adds DecoupledTanManager with configurable polling, a full state machine (INITIATED → CHALLENGE_SENT → PENDING_CONFIRMATION → CONFIRMED / CANCELLED / TIMED_OUT / FAILED), user cancellation, and total timeout
• Dialog gains three new methods: handleDecoupledTan(), cancelDecoupledTan(), checkDecoupledTanStatus()
• Fixes HKTAN process code: status polling requests now correctly use process "S" instead of "4"
• HITANS timing fields (decoupledWaitBeforeFirstStatusRequest, decoupledWaitBetweenStatusRequests) are in seconds per spec and are now correctly converted to milliseconds
• Return codes handled: 3956 (SCA pending), 3076 (PSD2 SCA required), 0030 (order accepted / TAN confirmed)

CAMT.052 account statement support (HKCAZ/HICAZ)

• Adds HKCAZ request segment (request CAMT account transactions)
• Adds HICAZ response segment (binary-encoded CAMT XML payload)
• Adds HICAZS parameter segment (server capabilities: max days, supported CAMT format)
• Adds a regex-based parseCamt052() parser that maps CAMT.052 XML to the existing mt940-js Statement/Transaction interface, including:
  • name, description, bankReference (Verwendungszweck from <Ustrd>)
  • isCredit, isExpense, currency, amount, date, valueDate
  • id from <AcctSvcrRef> (usable as transaction ID in Firefly III etc.)
  • descriptionStructured with counterparty IBAN/BIC, EndToEndId, mandate reference, creditor ID
  • Namespace-aware tag matching (handles both plain and prefixed XML like ns2:Ntry)

Tests

• Integration tests for the full decoupled TAN polling loop, cancellation, and status tracking
• Unit tests for HICAZ, HICAZS, HKCAZ segment serialization/deserialization
• Unit tests for parseCamt052 covering credit/debit transactions, balances, account identification, descriptionStructured, and namespaced XML

References

larsdecker/n8n-nodes-fints#105

[Copilot]

Pull request overview

Adds FinTS decoupled TAN (asynchronous/pushTAN-style) handling and introduces CAMT.052-based transaction fetching (HKCAZ/HICAZ/HICAZS) as an alternative to MT940 statements.

Changes:

• Add new CAMT-related segments (HKCAZ request, HICAZ response, HICAZS parameter segment) plus a CAMT.052 parser and tests.
• Implement/adjust decoupled TAN polling behavior (HKTAN process "S" for status polling; HITANS timing conversion to ms).
• Extend Client.statements() and Dialog.sync() to detect/support CAMT transactions and route statement fetching accordingly.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/fints/src/segments/index.ts	Exports newly added CAMT segment implementations.
packages/fints/src/segments/hktan.ts	Allows HKTAN process "S" and serializes it like process "2" for polling.
packages/fints/src/segments/hkcaz.ts	Adds HKCAZ request segment serialization for CAMT transaction fetching.
packages/fints/src/segments/hicaz.ts	Adds HICAZ response segment deserialization for CAMT payload fields.
packages/fints/src/segments/hicazs.ts	Adds HICAZS parameter segment deserialization (max days + format).
packages/fints/src/segments/tests/test-hkcaz.ts	Tests HKCAZ serialization.
packages/fints/src/segments/tests/test-hicaz.ts	Tests HICAZ deserialization cases.
packages/fints/src/segments/tests/test-hicazs.ts	Tests HICAZS deserialization.
packages/fints/src/dialog.ts	Tracks CAMT support/version/format from sync response (currently has critical issues).
packages/fints/src/decoupled-tan/decoupled-tan-manager.ts	Uses HKTAN process "S", converts HITANS timing seconds→ms, and syncs dialog state on direct sends.
packages/fints/src/decoupled-tan/tests/test-decoupled-tan-integration.ts	Adjusts integration timing and in-flight cancellation/status checks.
packages/fints/src/client.ts	Adds CAMT statement path (HKCAZ/HICAZ) and decoupled TAN handling during CAMT fetch (currently has critical issues).
packages/fints/src/camt052-parser.ts	Implements regex-based CAMT.052 XML → Statement/Transaction mapping (currently has a balance-date parsing issue).
packages/fints/src/tests/test-camt052-parser.ts	Adds unit tests for CAMT.052 parsing (missing assertion that would catch the balance-date issue).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.