ebicsclient 0.2.0__tar.gz → 1.3.1__tar.gz

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
 

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/.github/workflows/release.yml

@@ -8,10 +8,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.12"
 
@@ -42,7 +42,7 @@ jobs:
       - name: Build sdist and wheel
         run: uv build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v5
         with:
           name: dist
           path: dist/
@@ -58,7 +58,7 @@ jobs:
       # anywhere; PyPI trusts this repository + workflow + environment combination.
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v6
         with:
           name: dist
           path: dist/

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/CLAUDE.md

@@ -78,10 +78,13 @@ MVP = read **and** write, validated live against ZKB: key init (INI/HIA/HPB) →
 `EOP/camt.053.001.08` and parse balances → upload `MCT/pain.001.001.09` with the A006 electronic
 signature. All of this is built and bank-accepted.
 
+The pain.002/camt.052/camt.054 parsers are built (M5, validated on genuine ZKB messages).
 Still deliberately **out of scope** — do not build until there is a concrete need and a way to
-validate it: distributed signatures (EDS), a pain.002 status-report parser, camt.052/camt.054
-reporting, non-H005 EBICS versions, and multi-bank quirk handling. The `protocol/` and `formats/`
-seams exist for these. Scope creep is what turns a stable standard into a maintenance burden.
+validate it: distributed signatures (EDS — the ZKB test subscriber has ``NumSigRequired=0``, so
+EDS cannot be validated there) and multi-bank quirk handling. **H004 and earlier EBICS versions
+will never be supported** (owner decision; see docs/04) — the `protocol/` seam exists for a
+future EBICS version, not for the past. Scope creep is what turns a stable standard into a
+maintenance burden.
 
 ## Workflow
 

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebicsclient
-Version: 0.2.0
+Version: 1.3.1
 Summary: Pure-Python client for the EBICS 3.0 (H005) banking protocol
 Project-URL: Homepage, https://github.com/schulluk/ebicsclient
 Project-URL: Repository, https://github.com/schulluk/ebicsclient
@@ -95,7 +95,7 @@ License: Copyright © 2026 Lukas Schulze
         **Use** means anything you do with the software requiring one of your licenses.
 License-File: LICENSE.md
 Keywords: banking,camt,ebics,fintech,h005,iso20022
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: License :: Other/Proprietary License
@@ -118,9 +118,25 @@ Description-Content-Type: text/markdown
 
 # ebicsclient — a pure-Python EBICS 3.0 (H005) client
 
-A from-scratch, pure-Python client for the **EBICS** banking protocol. It **downloads account
-statements (camt.053)** and **initiates payments (pain.001)** over EBICS 3.0 / H005 — starting with
-Zürcher Kantonalbank (ZKB), against which the whole flow is validated live.
+A from-scratch, pure-Python client for the **EBICS** banking protocol (EBICS 3.0 / H005),
+validated live against Zürcher Kantonalbank (ZKB).
+
+**What it provides today:**
+
+- **Key ceremony** — INI/HIA/HPB with X.509 key transmission (self-signed *mit Schlüsseln* or
+  CA-issued *mit Zertifikaten*), the printable initialisation letter (HTML/PDF), and bank-key
+  **pinning** across sessions
+- **Read** — statement/report downloads with parsers into typed models: **camt.053** end-of-day
+  statements, **camt.052** intraday reports, **camt.054** booking advices (incl. QRR/SCOR/LSV),
+  and **pain.002** payment status reports
+- **Write** — **pain.001** payment submission (BTU) with the A006 electronic signature
+- **Security throughout** — the bank's `AuthSignature` is verified on **every** response, unknown
+  return codes are never masked, and everything fails closed
+- **Self-inspection** — `available_order_types()` (HAA) and `subscriber_info()` (HTD)
+
+**What is missing:** distributed signatures (EDS/VEU — multi-person payment approval; see
+milestone 7 below), and validation against banks beyond ZKB. Legacy EBICS versions (H004 and
+earlier) are deliberately unsupported.
 
 - **Stack:** Python 3.11+, just two runtime deps — `cryptography` (RSA/AES) and `lxml` (XML /
   inclusive Canonical XML 1.0); everything else stdlib. No PHP/Java sidecar. (Rationale:
@@ -238,11 +254,31 @@ a real bank statement.
 - [x] camt.052 intraday reports
 - [x] camt.054 booking advices (incl. the QRR / SCOR / LSV variants via `service_option`)
 
-**Milestone 6 — Protocol conveniences & breadth**
+**Milestone 6 — Protocol hardening & conveniences**
+
+- [x] Verify the bank's `AuthSignature` on every response — validated live on ZKB
+- [x] Subscriber self-inspection — `available_order_types()` (HAA) and `subscriber_info()` (HTD)
+
+**Milestone 7 — Distributed signatures (EDS/VEU)** (next; parked until validatable)
+
+EDS (*Elektronische Verteilte Unterschrift*) is EBICS's workflow for orders that need
+**multiple people to sign before the bank executes them** — dual control on payments. An order
+is uploaded with `requestEDS` and parks in the bank's VEU queue; further signatories list the
+queue, inspect the order, and deliver their A006 signatures until the configured quorum (e.g.
+first + second signature) is reached. The building blocks (A006 signing, the `SignatureFlag`,
+the admin-download transaction pattern) are in place; what is missing is a **validatable
+multi-user setup** — the ZKB test subscriber is single-user with `NumSigRequired=0`, so the
+workflow cannot be exercised there. This milestone starts when a downstream setup with a real
+multi-signature profile exists.
+
+- [ ] Upload into the VEU queue (`SignatureFlag` with `requestEDS`)
+- [ ] List pending orders (HVU/HVZ) and fetch order details (HVD) and transactions (HVT)
+- [ ] Deliver an additional signature (HVE) and cancel a pending order (HVS)
+- [ ] Validate the full quorum workflow against a multi-signature bank profile
 
-- [ ] Subscriber self-inspection — available order types (HAA) and subscriber info (HTD)
-- [ ] Distributed signatures (EDS)
-- [ ] Further EBICS versions (e.g. H004) via the `protocol/` seam
+This client is **EBICS 3.0 (H005) only** — legacy versions (H004 and earlier) will not be
+supported (see [docs/04](docs/04-implementation-plan.md)); the `protocol/` seam exists for a
+future EBICS version, not for the past.
 
 ## License
 

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/README.md

@@ -1,8 +1,24 @@
 # ebicsclient — a pure-Python EBICS 3.0 (H005) client
 
-A from-scratch, pure-Python client for the **EBICS** banking protocol. It **downloads account
-statements (camt.053)** and **initiates payments (pain.001)** over EBICS 3.0 / H005 — starting with
-Zürcher Kantonalbank (ZKB), against which the whole flow is validated live.
+A from-scratch, pure-Python client for the **EBICS** banking protocol (EBICS 3.0 / H005),
+validated live against Zürcher Kantonalbank (ZKB).
+
+**What it provides today:**
+
+- **Key ceremony** — INI/HIA/HPB with X.509 key transmission (self-signed *mit Schlüsseln* or
+  CA-issued *mit Zertifikaten*), the printable initialisation letter (HTML/PDF), and bank-key
+  **pinning** across sessions
+- **Read** — statement/report downloads with parsers into typed models: **camt.053** end-of-day
+  statements, **camt.052** intraday reports, **camt.054** booking advices (incl. QRR/SCOR/LSV),
+  and **pain.002** payment status reports
+- **Write** — **pain.001** payment submission (BTU) with the A006 electronic signature
+- **Security throughout** — the bank's `AuthSignature` is verified on **every** response, unknown
+  return codes are never masked, and everything fails closed
+- **Self-inspection** — `available_order_types()` (HAA) and `subscriber_info()` (HTD)
+
+**What is missing:** distributed signatures (EDS/VEU — multi-person payment approval; see
+milestone 7 below), and validation against banks beyond ZKB. Legacy EBICS versions (H004 and
+earlier) are deliberately unsupported.
 
 - **Stack:** Python 3.11+, just two runtime deps — `cryptography` (RSA/AES) and `lxml` (XML /
   inclusive Canonical XML 1.0); everything else stdlib. No PHP/Java sidecar. (Rationale:
@@ -120,11 +136,31 @@ a real bank statement.
 - [x] camt.052 intraday reports
 - [x] camt.054 booking advices (incl. the QRR / SCOR / LSV variants via `service_option`)
 
-**Milestone 6 — Protocol conveniences & breadth**
+**Milestone 6 — Protocol hardening & conveniences**
 
-- [ ] Subscriber self-inspection — available order types (HAA) and subscriber info (HTD)
-- [ ] Distributed signatures (EDS)
-- [ ] Further EBICS versions (e.g. H004) via the `protocol/` seam
+- [x] Verify the bank's `AuthSignature` on every response — validated live on ZKB
+- [x] Subscriber self-inspection — `available_order_types()` (HAA) and `subscriber_info()` (HTD)
+
+**Milestone 7 — Distributed signatures (EDS/VEU)** (next; parked until validatable)
+
+EDS (*Elektronische Verteilte Unterschrift*) is EBICS's workflow for orders that need
+**multiple people to sign before the bank executes them** — dual control on payments. An order
+is uploaded with `requestEDS` and parks in the bank's VEU queue; further signatories list the
+queue, inspect the order, and deliver their A006 signatures until the configured quorum (e.g.
+first + second signature) is reached. The building blocks (A006 signing, the `SignatureFlag`,
+the admin-download transaction pattern) are in place; what is missing is a **validatable
+multi-user setup** — the ZKB test subscriber is single-user with `NumSigRequired=0`, so the
+workflow cannot be exercised there. This milestone starts when a downstream setup with a real
+multi-signature profile exists.
+
+- [ ] Upload into the VEU queue (`SignatureFlag` with `requestEDS`)
+- [ ] List pending orders (HVU/HVZ) and fetch order details (HVD) and transactions (HVT)
+- [ ] Deliver an additional signature (HVE) and cancel a pending order (HVS)
+- [ ] Validate the full quorum workflow against a multi-signature bank profile
+
+This client is **EBICS 3.0 (H005) only** — legacy versions (H004 and earlier) will not be
+supported (see [docs/04](docs/04-implementation-plan.md)); the `protocol/` seam exists for a
+future EBICS version, not for the past.
 
 ## License
 

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/examples/zkb_handshake.py

@@ -15,6 +15,8 @@ Steps, matching the EBICS initialisation ceremony (see docs/05, docs/07):
     download   fetch the EOP/camt.053 statements and print their closing balances
     upload     upload a pain.001 payment file (path in EBICS_UPLOAD_PATH)
     pain002    fetch the pain.002 payment status report(s) and print them
+    haa        list the order types with data available at the bank
+    htd        show the subscriber data registered at the bank
 
 Run each step in order, e.g.::
 
@@ -83,7 +85,8 @@ def main() -> int:
     parser.add_argument(
         "step",
         choices=[
-            "generate", "ini", "hia", "letter", "hpb", "hashes", "download", "upload", "pain002"
+            "generate", "ini", "hia", "letter", "hpb", "hashes", "download", "upload",
+            "pain002", "haa", "htd",
         ],
     )
     step = parser.parse_args().step
@@ -219,6 +222,34 @@ def _pain002() -> int:
     return 0
 
 
+def _haa() -> int:
+    client = _build_client()
+    _fetch_bank_keys(client)
+    order_types = client.available_order_types()
+    if not order_types:
+        print("HAA: no order types currently have data available.")
+        return 0
+    print(f"HAA: {len(order_types)} order type(s) with data available:")
+    for btf in order_types:
+        print(f"  {btf.service_name}/{btf.scope or '-'}/{btf.message_name}"
+              f" v{btf.message_version or '-'} container={btf.container or '-'}")
+    return 0
+
+
+def _htd() -> int:
+    client = _build_client()
+    _fetch_bank_keys(client)
+    info = client.subscriber_info()
+    print(f"HTD: user {info.user_id} (status {info.user_status}), name: {info.name}")
+    print(f"  permissions: {len(info.permissions)}, partner order types: {len(info.order_types)}")
+    for entry in info.order_types:
+        service = entry.service
+        btf = (f"{service.service_name}/{service.scope or '-'}/{service.message_name}"
+               f" v{service.message_version or '-'}") if service else "-"
+        print(f"  {entry.admin_order_type:<4} {btf:<40} {entry.description or ''}")
+    return 0
+
+
 def _build_client() -> Client:
     return Client(_bank(), _user(), _load_keyring())
 
@@ -284,6 +315,8 @@ _STEPS = {
     "download": _download,
     "upload": _upload,
     "pain002": _pain002,
+    "haa": _haa,
+    "htd": _htd,
 }
 
 

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ebicsclient"
-version = "0.2.0"
+version = "1.3.1"
 description = "Pure-Python client for the EBICS 3.0 (H005) banking protocol"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -12,7 +12,7 @@ license = { file = "LICENSE.md" }
 authors = [{ name = "Lukas Schulze" }]
 keywords = ["ebics", "banking", "iso20022", "camt", "h005", "fintech"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Financial and Insurance Industry",
     "License :: Other/Proprietary License",

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/src/ebicsclient/__init__.py

@@ -30,6 +30,7 @@ from ebicsclient.errors import (
     MessageFormatError,
     MissingDependencyError,
     ProtocolError,
+    ResponseAuthenticationError,
     Retryability,
     ReturnCodeError,
     TransportError,
@@ -63,11 +64,13 @@ from ebicsclient.models import (
     Keyring,
     Letter,
     Notification,
+    OrderTypeInfo,
     OutputFormat,
     PaymentStatus,
     PaymentStatusReport,
     Statement,
     StatusReason,
+    SubscriberInfo,
     TransactionStatus,
     UploadPayload,
     User,
@@ -116,15 +119,18 @@ __all__ = [
     "MessageFormatError",
     "MissingDependencyError",
     "Notification",
+    "OrderTypeInfo",
     "OutputFormat",
     "PaymentStatus",
     "PaymentStatusReport",
     "ProtocolError",
+    "ResponseAuthenticationError",
     "Retryability",
     "ReturnCodeError",
     "SelfSignedCertificateProvider",
     "Statement",
     "StatusReason",
+    "SubscriberInfo",
     "TransactionStatus",
     "TransportError",
     "TrustAnchorVerifier",

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/src/ebicsclient/certificates.py

@@ -91,8 +91,18 @@ class MappingCertificateProvider:
         Args:
             certificates: A mapping from each :class:`~ebicsclient.keys.CertificateUsage` to
                 the CA-issued certificate certifying that key.
+
+        Raises:
+            TypeError: a mapping value is not an ``x509.Certificate``.
         """
         self._certificates = dict(certificates)
+        for usage, certificate in self._certificates.items():
+            if not isinstance(certificate, x509.Certificate):
+                raise TypeError(
+                    f"The {usage} certificate must be an x509.Certificate, got "
+                    f"{type(certificate).__name__} — load PEM/DER bytes with "
+                    f"load_certificate()"
+                )
 
     def certificate(
         self, usage: CertificateUsage, private_key: rsa.RSAPrivateKey, subject_name: str
@@ -152,6 +162,12 @@ class TrustAnchorVerifier:
         self._anchors = list(trust_anchors)
         if not self._anchors:
             raise BankCertificateError("At least one trust anchor is required")
+        for anchor in self._anchors:
+            if not isinstance(anchor, x509.Certificate):
+                raise TypeError(
+                    f"Trust anchors must be x509.Certificate objects, got "
+                    f"{type(anchor).__name__} — load PEM/DER bytes with load_certificate()"
+                )
 
     def verify(self, certificate: x509.Certificate, usage: CertificateUsage) -> None:
         """Check the bank certificate's validity period and issuer against the anchors."""
@@ -176,11 +192,16 @@ def load_certificate(data: bytes) -> x509.Certificate:
         The parsed certificate.
 
     Raises:
-        CertificateError: the bytes are not a readable X.509 certificate.
+        CertificateError: the data is not bytes or not a readable X.509 certificate.
     """
+    if not isinstance(data, bytes | bytearray):
+        raise CertificateError(
+            f"Certificate data must be bytes, got {type(data).__name__} — read the "
+            f"certificate file in binary mode ('rb')"
+        )
     for loader in (x509.load_pem_x509_certificate, x509.load_der_x509_certificate):
         try:
-            return loader(data)
+            return loader(bytes(data))
         except ValueError:
             continue
     raise CertificateError("Data is not a readable PEM or DER X.509 certificate")

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/src/ebicsclient/client.py

@@ -32,6 +32,7 @@ from ebicsclient.models import (
     OutputFormat,
     PaymentStatusReport,
     Statement,
+    SubscriberInfo,
     User,
 )
 from ebicsclient.protocol import h005
@@ -240,13 +241,31 @@ class Client:
             ReturnCodeError: the bank reported a non-OK return code (e.g. no data available).
             CryptoError: the order data could not be decrypted.
         """
-        if self._bank_keys is None:
-            raise ClientStateError("Download requires the bank's keys; call hpb() first")
+        bank_keys = self._require_bank_keys("Download")
         logger.info("Download: opening a %s/%s transaction", btf.service_name, btf.message_name)
         request = h005.build_download_initialisation_request(
-            self._bank, self._user, self._keyring, self._bank_keys, btf
+            self._bank, self._user, self._keyring, bank_keys, btf
+        )
+        return self._run_download_transaction(request, bank_keys)
+
+    def _require_bank_keys(self, operation: str) -> BankKeys:
+        if self._bank_keys is None:
+            raise ClientStateError(f"{operation} requires the bank's keys; call hpb() first")
+        return self._bank_keys
+
+    def _post_verified(self, request: bytes, bank_keys: BankKeys) -> bytes:
+        # Every ebicsResponse is authenticated with the bank's X002 signature; verify it
+        # BEFORE trusting anything in the response — including its return code.
+        response = self._transport.post(request)
+        h005.verify_response_signature(response, bank_keys.authentication)
+        return response
+
+    def _run_download_transaction(
+        self, initialisation_request: bytes, bank_keys: BankKeys
+    ) -> bytes:
+        initialisation = h005.parse_download_initialisation_response(
+            self._post_verified(initialisation_request, bank_keys)
         )
-        initialisation = h005.parse_download_initialisation_response(self._transport.post(request))
 
         # Order data is one base64 stream split into NumSegments pieces: fetch the rest, in
         # order, driven by the authoritative segment count from the initialisation response.
@@ -259,7 +278,9 @@ class Client:
                 number,
                 last_segment=number == initialisation.num_segments,
             )
-            segment = h005.parse_download_segment_response(self._transport.post(transfer))
+            segment = h005.parse_download_segment_response(
+                self._post_verified(transfer, bank_keys)
+            )
             segments.append(segment.order_data_segment)
 
         # Acknowledge the completed transfer so the bank marks the download as delivered.
@@ -267,7 +288,7 @@ class Client:
         receipt = h005.build_download_receipt_request(
             self._bank, self._keyring, initialisation.transaction_id
         )
-        h005.parse_download_receipt_response(self._transport.post(receipt))
+        h005.parse_download_receipt_response(self._post_verified(receipt, bank_keys))
         logger.info(
             "Download: received %d segment(s) for transaction %s",
             initialisation.num_segments,
@@ -281,6 +302,60 @@ class Client:
             self._keyring.encryption, initialisation.transaction_key, encrypted_order_data
         )
 
+    def available_order_types(self) -> list[BusinessTransactionFormat]:
+        """Download the order types for which the bank currently holds data (HAA).
+
+        Runs the administrative ``HAA`` download and returns the Business Transaction
+        Formats with data waiting — an authoritative "is there anything to fetch?" check.
+        The bank's keys must already be available (call :meth:`hpb` first).
+
+        Returns:
+            The order types with data available (empty when nothing is waiting).
+
+        Raises:
+            ClientStateError: the bank's keys have not been fetched yet (run HPB first).
+            TransportError: a request could not be delivered.
+            ProtocolError: a response could not be parsed.
+            ResponseAuthenticationError: a response failed signature verification.
+            ReturnCodeError: the bank rejected the request.
+            CryptoError: the order data could not be decrypted.
+        """
+        bank_keys = self._require_bank_keys("HAA")
+        logger.info("HAA: requesting the order types with data available")
+        request = h005.build_admin_download_initialisation_request(
+            self._bank, self._user, self._keyring, bank_keys, "HAA"
+        )
+        return h005.parse_available_order_types(
+            self._run_download_transaction(request, bank_keys)
+        )
+
+    def subscriber_info(self) -> SubscriberInfo:
+        """Download the bank's registered data for this subscriber (HTD).
+
+        Runs the administrative ``HTD`` download and returns the bank's authoritative
+        view of the subscriber: the user's status and name, the permissions granted, and
+        every order type registered for the partner — the ground truth for diagnosing
+        rejected order types. The bank's keys must already be available (call :meth:`hpb`
+        first).
+
+        Returns:
+            The subscriber's registered data.
+
+        Raises:
+            ClientStateError: the bank's keys have not been fetched yet (run HPB first).
+            TransportError: a request could not be delivered.
+            ProtocolError: a response could not be parsed.
+            ResponseAuthenticationError: a response failed signature verification.
+            ReturnCodeError: the bank rejected the request.
+            CryptoError: the order data could not be decrypted.
+        """
+        bank_keys = self._require_bank_keys("HTD")
+        logger.info("HTD: requesting the subscriber data registered at the bank")
+        request = h005.build_admin_download_initialisation_request(
+            self._bank, self._user, self._keyring, bank_keys, "HTD"
+        )
+        return h005.parse_subscriber_info(self._run_download_transaction(request, bank_keys))
+
     def download_statements(self) -> list[Statement]:
         """Download the end-of-period camt.053 statements and parse them.
 
@@ -390,14 +465,23 @@ class Client:
             ReturnCodeError: the bank rejected the upload (e.g. a bad signature or order data).
             CryptoError: the order data could not be signed or encrypted.
         """
-        if self._bank_keys is None:
-            raise ClientStateError("Upload requires the bank's keys; call hpb() first")
+        if not isinstance(order_data, bytes | bytearray):
+            # A str here would fail deep inside compression with an opaque error; and
+            # implicitly encoding it could silently alter the document. The caller owns
+            # the encoding: read the file in binary mode or encode it explicitly.
+            raise TypeError(
+                f"order_data must be bytes, got {type(order_data).__name__} — read the "
+                f"file in binary mode ('rb') or use .encode() on an XML string"
+            )
+        bank_keys = self._require_bank_keys("Upload")
         logger.info("Upload: opening a %s/%s transaction", btf.service_name, btf.message_name)
-        payload = h005.prepare_upload(self._user, self._keyring, self._bank_keys, order_data)
+        payload = h005.prepare_upload(self._user, self._keyring, bank_keys, order_data)
         request = h005.build_upload_initialisation_request(
-            self._bank, self._user, self._keyring, self._bank_keys, btf, payload
+            self._bank, self._user, self._keyring, bank_keys, btf, payload
+        )
+        transaction_id = h005.parse_upload_initialisation_response(
+            self._post_verified(request, bank_keys)
         )
-        transaction_id = h005.parse_upload_initialisation_response(self._transport.post(request))
 
         segments = payload.order_data_segments
         for number, segment_data in enumerate(segments, start=1):
@@ -409,7 +493,7 @@ class Client:
                 segment_data,
                 last_segment=number == len(segments),
             )
-            h005.parse_upload_transfer_response(self._transport.post(transfer))
+            h005.parse_upload_transfer_response(self._post_verified(transfer, bank_keys))
         logger.info(
             "Upload: sent %d segment(s) for transaction %s", len(segments), transaction_id
         )

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/src/ebicsclient/errors.py

@@ -125,6 +125,15 @@ class ProtocolError(EbicsError):
     """The bank's response violated the expected EBICS protocol or could not be parsed."""
 
 
+class ResponseAuthenticationError(ProtocolError):
+    """The bank's response failed authentication-signature verification.
+
+    Every ``ebicsResponse`` carries the bank's ``AuthSignature`` (X002) over its
+    ``authenticate="true"`` nodes. A missing or invalid signature means the response
+    cannot be attributed to the bank — do not trust its contents. Fail closed.
+    """
+
+
 class BankKeyMismatchError(ProtocolError):
     """The bank's HPB public keys did not match the pinned values.
 

{ebicsclient-0.2.0 → ebicsclient-1.3.1}/src/ebicsclient/keys.py

@@ -43,6 +43,18 @@ _KEY_FIELDS = ("signature", "authentication", "encryption")
 _CERTIFICATE_VALIDITY_DAYS = 365 * 10
 
 
+def _require_passphrase(passphrase: object) -> None:
+    # A non-str passphrase (e.g. a numeric value from an unquoted config entry) would
+    # surface as an AttributeError deep in the serialisation layer; fail here instead.
+    if not isinstance(passphrase, str):
+        raise KeyringError(
+            f"passphrase must be a str, got {type(passphrase).__name__} — quote it in "
+            f"your configuration"
+        )
+    if not passphrase:
+        raise KeyringError("A non-empty passphrase is required to encrypt the keyring")
+
+
 def generate_keyring(key_size: int = _MINIMUM_KEY_SIZE) -> Keyring:
     """Generate a fresh set of the three EBICS RSA key pairs.
 
@@ -182,8 +194,7 @@ def serialize_keyring(keyring: Keyring, passphrase: str) -> bytes:
     Raises:
         KeyringError: the passphrase is empty.
     """
-    if not passphrase:
-        raise KeyringError("A non-empty passphrase is required to encrypt the keyring")
+    _require_passphrase(passphrase)
     encryption = serialization.BestAvailableEncryption(passphrase.encode("utf-8"))
     encoded = {
         field: _private_key_to_pem(getattr(keyring, field), encryption) for field in _KEY_FIELDS
@@ -206,6 +217,7 @@ def deserialize_keyring(data: bytes, passphrase: str) -> Keyring:
         KeyringError: the data is malformed, of an unknown version, or the passphrase
             is wrong.
     """
+    _require_passphrase(passphrase)
     try:
         envelope = json.loads(data)
     except (json.JSONDecodeError, UnicodeDecodeError) as error:
@@ -224,30 +236,32 @@ def deserialize_keyring(data: bytes, passphrase: str) -> Keyring:
     return Keyring(**keys)
 
 
-def save_keyring(keyring: Keyring, path: Path, passphrase: str) -> None:
+def save_keyring(keyring: Keyring, path: str | Path, passphrase: str) -> None:
     """Write an encrypted keyring to a file (convenience over :func:`serialize_keyring`).
 
     Args:
         keyring: The key pairs to persist.
-        path: Destination file path; overwritten if it already exists.
+        path: Destination file path (a ``str`` or ``Path``); overwritten if it exists.
         passphrase: Secret used to encrypt the private keys. Never stored or logged.
 
     Raises:
-        KeyringError: the passphrase is empty, or the file could not be written.
+        KeyringError: the passphrase is empty or not a string, or the file could not be
+            written.
     """
     data = serialize_keyring(keyring, passphrase)
+    destination = Path(path)
     try:
-        path.write_bytes(data)
+        destination.write_bytes(data)
     except OSError as error:
-        raise KeyringError(f"Could not write keyring to {path}: {error}") from error
-    logger.info("Wrote encrypted keyring to %s", path)
+        raise KeyringError(f"Could not write keyring to {destination}: {error}") from error
+    logger.info("Wrote encrypted keyring to %s", destination)
 
 
-def load_keyring(path: Path, passphrase: str) -> Keyring:
+def load_keyring(path: str | Path, passphrase: str) -> Keyring:
     """Read and decrypt a keyring file (convenience over :func:`deserialize_keyring`).
 
     Args:
-        path: Path to the encrypted keyring file.
+        path: Path to the encrypted keyring file (a ``str`` or ``Path``).
         passphrase: Secret used when the keyring was saved.
 
     Returns:
@@ -255,12 +269,13 @@ def load_keyring(path: Path, passphrase: str) -> Keyring:
 
     Raises:
         KeyringError: the file is missing, malformed, of an unknown version, or the
-            passphrase is wrong.
+            passphrase is wrong or not a string.
     """
+    source = Path(path)
     try:
-        data = path.read_bytes()
+        data = source.read_bytes()
     except OSError as error:
-        raise KeyringError(f"Could not read keyring from {path}: {error}") from error
+        raise KeyringError(f"Could not read keyring from {source}: {error}") from error
     return deserialize_keyring(data, passphrase)