open-banking-io 0.1.0__tar.gz

open_banking_io-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# .NET
+bin/
+obj/
+*.user
+
+# Node
+node_modules/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+*.pyc
+
+# Build output (both node tsup + python build)
+dist/
+build/
+
+# misc
+.DS_Store

open_banking_io-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: open-banking-io
+Version: 0.1.0
+Summary: Server-to-server client for open-banking.io with local zero-knowledge envelope decryption.
+Project-URL: Homepage, https://open-banking.io
+Project-URL: Repository, https://github.com/open-banking-io/clients
+Author: open-banking.io
+License: MIT
+Keywords: banking,ecdh,open-banking,psd2,zero-knowledge
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# open-banking-io (Python)
+
+Server-to-server client for [open-banking.io](https://open-banking.io). It authenticates with your
+**API key** and decrypts the **zero-knowledge** data envelopes locally with your exported **private
+key** — the service only ever returns ciphertext it cannot read.
+
+```bash
+pip install open-banking-io
+```
+
+```python
+from open_banking_io import OpenBankingClient
+
+# Load the credentials .json you exported from the app (API key + private key).
+with OpenBankingClient.from_credentials("credentials.json") as client:
+    for account in client.get_accounts():
+        booked = next((b for b in account.balances if b.type == "ITBD"), None)
+        label = account.display_name or account.owner_name
+        print(f"{label} {account.iban}: {booked.amount if booked else None} {account.currency}")
+
+        page = client.get_transactions(account.id, limit=50)
+        for t in page.items:
+            print(f"  {t.booking_date}  {t.creditor_name or t.debtor_name}  {t.amount} {t.currency}")
+
+    # Trigger an online sync (decrypts the account uid locally and posts it):
+    client.sync(account.id)
+```
+
+Or construct it explicitly:
+
+```python
+client = OpenBankingClient(api_base_url, api_key, private_key_pkcs8)
+```
+
+## API
+
+- `get_accounts() -> list[Account]` — decrypts each account's envelope, display name and balances.
+- `get_transactions(account_id, *, date_from=None, date_to=None, limit=None, offset=None) -> TransactionPage`
+- `get_connections() -> list[Connection]`
+- `sync(account_id) -> SyncResult` — decrypts the account uid locally and posts it.
+- `sync_all() -> SyncAllResult` — syncs every account that has an active session.
+
+Amounts are exposed as `decimal.Decimal`. Models are plain `@dataclass`es.
+
+## Encryption
+
+Envelopes use **ECDH P-256 → HKDF-SHA256 → AES-256-GCM**. Decryption requires the private key from
+your credentials bundle and happens entirely in-process. See the
+[repo README](https://github.com/open-banking-io/clients) for the full scheme and the other language
+clients (.NET, Node).
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e .[dev]
+.venv/bin/pytest -q
+```
+
+MIT licensed.

open_banking_io-0.1.0/README.md

@@ -0,0 +1,60 @@
+# open-banking-io (Python)
+
+Server-to-server client for [open-banking.io](https://open-banking.io). It authenticates with your
+**API key** and decrypts the **zero-knowledge** data envelopes locally with your exported **private
+key** — the service only ever returns ciphertext it cannot read.
+
+```bash
+pip install open-banking-io
+```
+
+```python
+from open_banking_io import OpenBankingClient
+
+# Load the credentials .json you exported from the app (API key + private key).
+with OpenBankingClient.from_credentials("credentials.json") as client:
+    for account in client.get_accounts():
+        booked = next((b for b in account.balances if b.type == "ITBD"), None)
+        label = account.display_name or account.owner_name
+        print(f"{label} {account.iban}: {booked.amount if booked else None} {account.currency}")
+
+        page = client.get_transactions(account.id, limit=50)
+        for t in page.items:
+            print(f"  {t.booking_date}  {t.creditor_name or t.debtor_name}  {t.amount} {t.currency}")
+
+    # Trigger an online sync (decrypts the account uid locally and posts it):
+    client.sync(account.id)
+```
+
+Or construct it explicitly:
+
+```python
+client = OpenBankingClient(api_base_url, api_key, private_key_pkcs8)
+```
+
+## API
+
+- `get_accounts() -> list[Account]` — decrypts each account's envelope, display name and balances.
+- `get_transactions(account_id, *, date_from=None, date_to=None, limit=None, offset=None) -> TransactionPage`
+- `get_connections() -> list[Connection]`
+- `sync(account_id) -> SyncResult` — decrypts the account uid locally and posts it.
+- `sync_all() -> SyncAllResult` — syncs every account that has an active session.
+
+Amounts are exposed as `decimal.Decimal`. Models are plain `@dataclass`es.
+
+## Encryption
+
+Envelopes use **ECDH P-256 → HKDF-SHA256 → AES-256-GCM**. Decryption requires the private key from
+your credentials bundle and happens entirely in-process. See the
+[repo README](https://github.com/open-banking-io/clients) for the full scheme and the other language
+clients (.NET, Node).
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e .[dev]
+.venv/bin/pytest -q
+```
+
+MIT licensed.

open_banking_io-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "open-banking-io"
+version = "0.1.0"
+description = "Server-to-server client for open-banking.io with local zero-knowledge envelope decryption."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "open-banking.io" }]
+keywords = ["open-banking", "psd2", "banking", "zero-knowledge", "ecdh"]
+dependencies = [
+    "cryptography>=42.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpserver>=1.0",
+]
+
+[project.urls]
+Homepage = "https://open-banking.io"
+Repository = "https://github.com/open-banking-io/clients"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/open_banking_io"]

open_banking_io-0.1.0/src/open_banking_io/__init__.py

@@ -0,0 +1,29 @@
+"""open-banking.io Python client.
+
+Server-to-server client that authenticates with an API key and decrypts the
+zero-knowledge data envelopes locally with your exported private key.
+"""
+
+from .client import OpenBankingClient
+from .models import (
+    Account,
+    Balance,
+    Connection,
+    SyncAllResult,
+    SyncResult,
+    Transaction,
+    TransactionPage,
+)
+
+__all__ = [
+    "OpenBankingClient",
+    "Account",
+    "Balance",
+    "Transaction",
+    "TransactionPage",
+    "Connection",
+    "SyncResult",
+    "SyncAllResult",
+]
+
+__version__ = "0.1.0"

open_banking_io-0.1.0/src/open_banking_io/client.py

@@ -0,0 +1,283 @@
+"""Server-to-server client for open-banking.io.
+
+Authenticates with an API key (``X-Api-Key``) and decrypts the zero-knowledge data
+envelopes locally with the exported private key -- the service only ever returns
+ciphertext it cannot read.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any
+
+import httpx
+
+from . import envelope
+from .models import (
+    Account,
+    Balance,
+    Connection,
+    SyncAllResult,
+    SyncResult,
+    Transaction,
+    TransactionPage,
+)
+
+
+def _parse_date(value: str | None) -> date | None:
+    if not value:
+        return None
+    return date.fromisoformat(value)
+
+
+def _parse_datetime(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    # Normalize a trailing 'Z' which datetime.fromisoformat handles only on 3.11+.
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    return datetime.fromisoformat(value)
+
+
+def _parse_decimal(value: str | None) -> Decimal:
+    if value is None or value == "":
+        return Decimal(0)
+    return Decimal(value)
+
+
+def _parse_decimal_nullable(value: str | None) -> Decimal | None:
+    if value is None or value == "":
+        return None
+    return Decimal(value)
+
+
+class OpenBankingClient:
+    """Decrypting client for the open-banking.io API."""
+
+    def __init__(
+        self,
+        api_base_url: str,
+        api_key: str,
+        private_key_pkcs8: str,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_base_url or not api_base_url.strip():
+            raise ValueError("api_base_url is required")
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+        if not private_key_pkcs8 or not private_key_pkcs8.strip():
+            raise ValueError("private_key_pkcs8 is required")
+
+        self._private_key = envelope.load_private_key(private_key_pkcs8)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client()
+        self._http.base_url = httpx.URL(api_base_url.rstrip("/") + "/")
+        self._http.headers["X-Api-Key"] = api_key
+
+    # -- Construction ----------------------------------------------------------
+
+    @classmethod
+    def from_credentials(
+        cls, path_or_json: str, http_client: httpx.Client | None = None
+    ) -> "OpenBankingClient":
+        """Builds a client from a credentials-bundle JSON string or a path to a bundle file."""
+        if os.path.exists(path_or_json):
+            with open(path_or_json, "r", encoding="utf-8") as fh:
+                raw = fh.read()
+        else:
+            raw = path_or_json
+
+        bundle = json.loads(raw)
+        api_base_url = bundle.get("apiBaseUrl", "")
+        api_key = bundle.get("apiKey")
+        if not api_key:
+            raise ValueError("The credentials bundle has no apiKey")
+
+        enc_key = bundle.get("encryptionKey") or {}
+        private_key = enc_key.get("privateKey") or enc_key.get("privateKeyPkcs8B64")
+        if not private_key:
+            raise ValueError("The credentials bundle has no encryption private key")
+
+        return cls(api_base_url, api_key, private_key, http_client)
+
+    # -- Public API ------------------------------------------------------------
+
+    def get_accounts(self) -> list[Account]:
+        """Lists the user's accounts with all sensitive fields decrypted."""
+        wires = self._get_account_wires()
+        return [self._map_account(w) for w in wires]
+
+    def get_transactions(
+        self,
+        account_id: str,
+        *,
+        date_from: date | str | None = None,
+        date_to: date | str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> TransactionPage:
+        """Returns a page of an account's statement, newest first, with decrypted fields."""
+        params: dict[str, Any] = {}
+        if date_from is not None:
+            params["from"] = date_from.isoformat() if isinstance(date_from, date) else date_from
+        if date_to is not None:
+            params["to"] = date_to.isoformat() if isinstance(date_to, date) else date_to
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        resp = self._http.get(f"api/accounts/{account_id}/transactions", params=params)
+        resp.raise_for_status()
+        page = resp.json()
+
+        items = [self._map_transaction(t) for t in page.get("items", [])]
+        return TransactionPage(items=items, total=page.get("total", 0))
+
+    def get_connections(self) -> list[Connection]:
+        """Lists the user's bank connections."""
+        resp = self._http.get("api/connections")
+        resp.raise_for_status()
+        return [
+            Connection(
+                session_id=c.get("sessionId", ""),
+                aspsp_name=c.get("aspspName", ""),
+                aspsp_country=c.get("aspspCountry", ""),
+                valid_until=_parse_datetime(c.get("validUntil")),
+                status=c.get("status", ""),
+                account_count=c.get("accountCount", 0),
+                last_synced_at=_parse_datetime(c.get("lastSyncedAt")),
+                psu_type=c.get("psuType"),
+            )
+            for c in resp.json()
+        ]
+
+    def sync(self, account_id: str) -> SyncResult:
+        """Triggers an online sync of one account.
+
+        Decrypts that account's Enable Banking uid and posts it, so the service can
+        fetch fresh data without ever holding the uid in plaintext.
+        """
+        wires = self._get_account_wires()
+        account = next((a for a in wires if a.get("id") == account_id), None)
+        if account is None:
+            raise ValueError(f"Account {account_id} not found")
+        uid = self._decrypt_uid(account)
+        if uid is None:
+            raise ValueError(
+                "Account has no active session (reconnect required) -- cannot sync"
+            )
+
+        resp = self._http.post(f"api/accounts/{account_id}/sync", json={"uid": uid})
+        resp.raise_for_status()
+        result = resp.json()
+        return SyncResult(
+            new_transactions=result.get("newTransactions", 0),
+            total_fetched=result.get("totalFetched", 0),
+        )
+
+    def sync_all(self) -> SyncAllResult:
+        """Triggers an online sync of every account that has an active session."""
+        wires = self._get_account_wires()
+        items = []
+        for a in wires:
+            uid = self._decrypt_uid(a)
+            if uid is not None:
+                items.append({"accountId": a.get("id"), "uid": uid})
+
+        resp = self._http.post("api/sync", json={"items": items})
+        resp.raise_for_status()
+        result = resp.json()
+        return SyncAllResult(
+            accounts=result.get("accounts", 0),
+            new_transactions=result.get("newTransactions", 0),
+        )
+
+    # -- Internals -------------------------------------------------------------
+
+    def _get_account_wires(self) -> list[dict[str, Any]]:
+        resp = self._http.get("api/accounts")
+        resp.raise_for_status()
+        return resp.json()
+
+    def _decrypt_uid(self, account: dict[str, Any]) -> str | None:
+        payload = envelope.decrypt_to_json(self._private_key, account.get("uidEnc"))
+        return payload.get("uid") if payload else None
+
+    def _map_account(self, a: dict[str, Any]) -> Account:
+        acc = envelope.decrypt_to_json(self._private_key, a.get("enc")) or {}
+        name = envelope.decrypt_to_json(self._private_key, a.get("displayNameEnc")) or {}
+
+        balances = []
+        for b in a.get("balances", []):
+            dec = envelope.decrypt_to_json(self._private_key, b.get("enc")) or {}
+            balances.append(
+                Balance(
+                    type=b.get("type", ""),
+                    currency=b.get("currency", ""),
+                    reference_date=_parse_date(b.get("referenceDate")),
+                    name=dec.get("name"),
+                    amount=_parse_decimal(dec.get("amount")),
+                )
+            )
+
+        return Account(
+            id=a.get("id", ""),
+            aspsp_name=a.get("aspspName", ""),
+            aspsp_country=a.get("aspspCountry", ""),
+            currency=a.get("currency", ""),
+            account_type=a.get("accountType"),
+            bic=a.get("bic"),
+            needs_reconnect=a.get("needsReconnect", False),
+            iban=acc.get("iban"),
+            bban=acc.get("bban"),
+            owner_name=acc.get("ownerName"),
+            account_name=acc.get("accountName"),
+            product=acc.get("product"),
+            display_name=name.get("displayName"),
+            balances=balances,
+        )
+
+    def _map_transaction(self, t: dict[str, Any]) -> Transaction:
+        d = envelope.decrypt_to_json(self._private_key, t.get("enc")) or {}
+        return Transaction(
+            id=t.get("id", ""),
+            currency=t.get("currency", ""),
+            credit_debit_indicator=t.get("creditDebitIndicator", ""),
+            status=t.get("status"),
+            booking_date=_parse_date(t.get("bookingDate")),
+            value_date=_parse_date(t.get("valueDate")),
+            transaction_date=_parse_date(t.get("transactionDate")),
+            bank_transaction_code=t.get("bankTransactionCode"),
+            amount=_parse_decimal(d.get("amount")),
+            creditor_name=d.get("creditorName"),
+            creditor_iban=d.get("creditorIban"),
+            creditor_bban=d.get("creditorBban"),
+            creditor_agent_bic=d.get("creditorAgentBic"),
+            debtor_name=d.get("debtorName"),
+            debtor_iban=d.get("debtorIban"),
+            debtor_bban=d.get("debtorBban"),
+            debtor_agent_bic=d.get("debtorAgentBic"),
+            remittance_information=d.get("remittanceInformation"),
+            note=d.get("note"),
+            reference_number=d.get("referenceNumber"),
+            exchange_rate=d.get("exchangeRate"),
+            merchant_category_code=d.get("merchantCategoryCode"),
+            balance_after_transaction=_parse_decimal_nullable(d.get("balanceAfter")),
+            balance_after_currency=d.get("balanceAfterCurrency"),
+        )
+
+    # -- Lifecycle -------------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "OpenBankingClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

open_banking_io-0.1.0/src/open_banking_io/envelope.py

@@ -0,0 +1,70 @@
+"""Decrypts open-banking.io's zero-knowledge data envelopes.
+
+Scheme: ephemeral ECDH on NIST P-256 -> HKDF-SHA256 -> AES-256-GCM.
+Wire: ``version(1)=0x01 | ephemeralPublicKeyRaw(65) | nonce(12) | tag(16) | ciphertext``.
+Only the user's private key can decrypt -- the service stores ciphertext it cannot read.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+_VERSION = 0x01
+_POINT_LEN = 65
+_NONCE_LEN = 12
+_TAG_LEN = 16
+_HKDF_SALT = b"\x00" * 32
+_HKDF_INFO = b"bank.core.ci/zk/v1"
+
+
+def load_private_key(private_key_pkcs8_b64: str) -> ec.EllipticCurvePrivateKey:
+    """Loads a base64 PKCS#8 EC (SECP256R1) private key."""
+    der = base64.b64decode(private_key_pkcs8_b64)
+    key = serialization.load_der_private_key(der, password=None)
+    if not isinstance(key, ec.EllipticCurvePrivateKey):
+        raise ValueError("Private key is not an EC key")
+    return key
+
+
+def decrypt(private_key: ec.EllipticCurvePrivateKey, envelope: bytes) -> bytes:
+    """Decrypts the raw bytes of a zero-knowledge envelope."""
+    if len(envelope) < 1 + _POINT_LEN + _NONCE_LEN + _TAG_LEN or envelope[0] != _VERSION:
+        raise ValueError("Invalid or unsupported envelope")
+
+    eph_pub_bytes = envelope[1 : 1 + _POINT_LEN]
+    nonce = envelope[1 + _POINT_LEN : 1 + _POINT_LEN + _NONCE_LEN]
+    tag = envelope[
+        1 + _POINT_LEN + _NONCE_LEN : 1 + _POINT_LEN + _NONCE_LEN + _TAG_LEN
+    ]
+    ciphertext = envelope[1 + _POINT_LEN + _NONCE_LEN + _TAG_LEN :]
+
+    eph_pub = ec.EllipticCurvePublicKey.from_encoded_point(
+        ec.SECP256R1(), eph_pub_bytes
+    )
+    shared = private_key.exchange(ec.ECDH(), eph_pub)
+
+    key = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=_HKDF_SALT,
+        info=_HKDF_INFO,
+    ).derive(shared)
+
+    return AESGCM(key).decrypt(nonce, ciphertext + tag, None)
+
+
+def decrypt_to_json(
+    private_key: ec.EllipticCurvePrivateKey, envelope_b64: str | None
+) -> dict[str, Any] | None:
+    """Decrypts a base64 envelope and parses its JSON payload. ``None`` in -> ``None``."""
+    if envelope_b64 is None:
+        return None
+    plaintext = decrypt(private_key, base64.b64decode(envelope_b64))
+    return json.loads(plaintext)

open_banking_io-0.1.0/src/open_banking_io/models.py

@@ -0,0 +1,102 @@
+"""Public, decrypted models for the open-banking.io client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal
+
+
+@dataclass
+class Balance:
+    """A balance snapshot. ``type`` is the ISO 20022 code (ITBD booked, ITAV available, ...)."""
+
+    type: str
+    name: str | None
+    amount: Decimal
+    currency: str
+    reference_date: date | None
+
+
+@dataclass
+class Account:
+    """A bank account with its sensitive fields decrypted."""
+
+    id: str
+    aspsp_name: str
+    aspsp_country: str
+    currency: str
+    account_type: str | None
+    bic: str | None
+    needs_reconnect: bool
+    iban: str | None
+    bban: str | None
+    owner_name: str | None
+    account_name: str | None
+    product: str | None
+    display_name: str | None
+    balances: list[Balance] = field(default_factory=list)
+
+
+@dataclass
+class Transaction:
+    """A statement transaction with its sensitive fields decrypted."""
+
+    id: str
+    currency: str
+    credit_debit_indicator: str
+    status: str | None
+    booking_date: date | None
+    value_date: date | None
+    transaction_date: date | None
+    bank_transaction_code: str | None
+    amount: Decimal
+    creditor_name: str | None
+    creditor_iban: str | None
+    creditor_bban: str | None
+    creditor_agent_bic: str | None
+    debtor_name: str | None
+    debtor_iban: str | None
+    debtor_bban: str | None
+    debtor_agent_bic: str | None
+    remittance_information: str | None
+    note: str | None
+    reference_number: str | None
+    exchange_rate: str | None
+    merchant_category_code: str | None
+    balance_after_transaction: Decimal | None
+    balance_after_currency: str | None
+
+
+@dataclass
+class TransactionPage:
+    """A page of transactions, newest first."""
+
+    items: list[Transaction]
+    total: int
+
+
+@dataclass
+class Connection:
+    """A bank connection (consent)."""
+
+    session_id: str
+    aspsp_name: str
+    aspsp_country: str
+    valid_until: datetime | None
+    status: str
+    account_count: int
+    last_synced_at: datetime | None
+    psu_type: str | None
+
+
+@dataclass
+class SyncResult:
+    new_transactions: int
+    total_fetched: int
+
+
+@dataclass
+class SyncAllResult:
+    accounts: int
+    new_transactions: int

open_banking_io-0.1.0/tests/conftest.py

@@ -0,0 +1,37 @@
+import json
+from pathlib import Path
+
+import pytest
+
+# python/tests/ -> python/ -> repo root -> fixtures/
+FIXTURES = Path(__file__).resolve().parents[2] / "fixtures"
+
+
+def load_fixture(*parts: str) -> dict | list:
+    with open(FIXTURES.joinpath(*parts), "r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+@pytest.fixture
+def fixtures_dir() -> Path:
+    return FIXTURES
+
+
+@pytest.fixture
+def keypair() -> dict:
+    return load_fixture("keypair.json")
+
+
+@pytest.fixture
+def credentials() -> dict:
+    return load_fixture("credentials.json")
+
+
+@pytest.fixture
+def envelopes() -> dict:
+    return load_fixture("envelopes.json")
+
+
+@pytest.fixture
+def expected() -> dict:
+    return load_fixture("expected.json")

open_banking_io-0.1.0/tests/test_crypto.py

@@ -0,0 +1,50 @@
+"""Wire-format interop: decrypt the shared fixtures and assert they match expected."""
+
+from decimal import Decimal
+
+from open_banking_io import envelope
+
+
+def _priv(keypair):
+    return envelope.load_private_key(keypair["privateKeyPkcs8B64"])
+
+
+def test_account_envelope(keypair, envelopes, expected):
+    priv = _priv(keypair)
+    acc = envelope.decrypt_to_json(priv, envelopes["account"])
+    assert acc == expected["account"]
+    assert acc["iban"] == "DK6466952001724927"
+
+
+def test_display_name_envelope(keypair, envelopes, expected):
+    priv = _priv(keypair)
+    name = envelope.decrypt_to_json(priv, envelopes["displayName"])
+    assert name == expected["displayName"]
+    assert name["displayName"] == "Drift"
+
+
+def test_uid_envelope(keypair, envelopes, expected):
+    priv = _priv(keypair)
+    uid = envelope.decrypt_to_json(priv, envelopes["uid"])
+    assert uid["uid"] == expected["uid"]["uid"]
+    assert uid["uid"] == "c5d93aa7-5e23-4da0-ba88-42b9a584492c"
+
+
+def test_balance_envelope(keypair, envelopes, expected):
+    priv = _priv(keypair)
+    bal = envelope.decrypt_to_json(priv, envelopes["balance"])
+    # The shared balance envelope is the booked (ITBD) balance.
+    assert Decimal(bal["amount"]) == Decimal(expected["balances"]["ITBD"]["amount"])
+    assert Decimal(bal["amount"]) == Decimal("828.13")
+    assert bal["name"] == "Tatic"
+
+
+def test_transaction_envelope(keypair, envelopes, expected):
+    priv = _priv(keypair)
+    txn = envelope.decrypt_to_json(priv, envelopes["transaction"])
+    exp = expected["transaction"]
+    assert Decimal(txn["amount"]) == Decimal(exp["amount"])
+    assert Decimal(txn["amount"]) == Decimal("194.23")
+    assert txn["creditorName"] == "One.com"
+    assert txn["merchantCategoryCode"] == "4816"
+    assert Decimal(txn["balanceAfter"]) == Decimal("633.90")

open_banking_io-0.1.0/tests/test_integration.py

@@ -0,0 +1,182 @@
+"""Integration test: serve the shared API fixtures over HTTP and exercise the client."""
+
+import json
+from decimal import Decimal
+
+import httpx
+import pytest
+from werkzeug import Response
+
+from open_banking_io import OpenBankingClient
+
+API_KEY = "obk_test_3f8b9c2e1a7d4655b0e9f2c1a8d7e6f5"
+
+
+def _json_response(data, status=200) -> Response:
+    return Response(json.dumps(data), status=status, mimetype="application/json")
+
+
+def _unauthorized() -> Response:
+    return _json_response({"error": "unauthorized"}, status=401)
+
+
+@pytest.fixture
+def server(httpserver, fixtures_dir):
+    account_id = "11111111-1111-4111-8111-111111111111"
+    captured: dict = {}
+
+    def load(path):
+        return json.loads((fixtures_dir / "api" / path).read_text())
+
+    def static_handler(path):
+        data = load(path)
+
+        def handler(request):
+            if request.headers.get("X-Api-Key") != API_KEY:
+                return _unauthorized()
+            return _json_response(data)
+
+        return handler
+
+    httpserver.expect_request("/api/accounts", method="GET").respond_with_handler(
+        static_handler("accounts.json")
+    )
+    httpserver.expect_request(
+        f"/api/accounts/{account_id}/transactions", method="GET"
+    ).respond_with_handler(static_handler("transactions.json"))
+    httpserver.expect_request("/api/connections", method="GET").respond_with_handler(
+        static_handler("connections.json")
+    )
+
+    sync_data = load("sync.json")
+
+    def sync_handler(request):
+        if request.headers.get("X-Api-Key") != API_KEY:
+            return _unauthorized()
+        captured["sync_body"] = json.loads(request.get_data())
+        return _json_response(sync_data)
+
+    httpserver.expect_request(
+        f"/api/accounts/{account_id}/sync", method="POST"
+    ).respond_with_handler(sync_handler)
+
+    sync_all_data = load("sync-all.json")
+
+    def sync_all_handler(request):
+        if request.headers.get("X-Api-Key") != API_KEY:
+            return _unauthorized()
+        captured["sync_all_body"] = json.loads(request.get_data())
+        return _json_response(sync_all_data)
+
+    httpserver.expect_request("/api/sync", method="POST").respond_with_handler(
+        sync_all_handler
+    )
+
+    httpserver._captured = captured  # type: ignore[attr-defined]
+    return httpserver
+
+
+def _client(server, credentials):
+    return OpenBankingClient(
+        api_base_url=server.url_for("").rstrip("/"),
+        api_key=credentials["apiKey"],
+        private_key_pkcs8=credentials["encryptionKey"]["privateKey"],
+    )
+
+
+def test_get_accounts_decrypts(server, credentials):
+    with _client(server, credentials) as client:
+        accounts = client.get_accounts()
+
+    assert len(accounts) == 1
+    acc = accounts[0]
+    assert acc.iban == "DK6466952001724927"
+    assert acc.owner_name == "Tatic ApS"
+    assert acc.display_name == "Drift"
+    assert acc.aspsp_name == "Lunar"
+
+    by_type = {b.type: b for b in acc.balances}
+    assert by_type["ITBD"].amount == Decimal("828.13")
+    assert by_type["ITAV"].amount == Decimal("633.90")
+
+
+def test_get_transactions_decrypts(server, credentials):
+    with _client(server, credentials) as client:
+        page = client.get_transactions(
+            "11111111-1111-4111-8111-111111111111", limit=50
+        )
+
+    assert page.total == 1
+    txn = page.items[0]
+    assert txn.amount == Decimal("194.23")
+    assert txn.creditor_name == "One.com"
+    assert txn.merchant_category_code == "4816"
+    assert txn.balance_after_transaction == Decimal("633.90")
+    assert txn.credit_debit_indicator == "DBIT"
+
+
+def test_get_connections(server, credentials):
+    with _client(server, credentials) as client:
+        connections = client.get_connections()
+
+    assert len(connections) == 1
+    conn = connections[0]
+    assert conn.session_id == "22222222-2222-4222-8222-222222222222"
+    assert conn.aspsp_name == "Lunar"
+    assert conn.account_count == 1
+    assert conn.psu_type == "business"
+
+
+def test_sync_posts_decrypted_uid(server, credentials):
+    with _client(server, credentials) as client:
+        result = client.sync("11111111-1111-4111-8111-111111111111")
+
+    assert result.total_fetched == 1
+    body = server._captured["sync_body"]
+    assert body == {"uid": "c5d93aa7-5e23-4da0-ba88-42b9a584492c"}
+
+
+def test_sync_all_posts_decrypted_uids(server, credentials):
+    with _client(server, credentials) as client:
+        result = client.sync_all()
+
+    assert result.accounts == 1
+    body = server._captured["sync_all_body"]
+    assert body["items"][0]["uid"] == "c5d93aa7-5e23-4da0-ba88-42b9a584492c"
+    assert body["items"][0]["accountId"] == "11111111-1111-4111-8111-111111111111"
+
+
+def test_wrong_api_key_raises(server, credentials):
+    client = OpenBankingClient(
+        api_base_url=server.url_for("").rstrip("/"),
+        api_key="wrong-key",
+        private_key_pkcs8=credentials["encryptionKey"]["privateKey"],
+    )
+    with pytest.raises(httpx.HTTPStatusError):
+        client.get_accounts()
+    client.close()
+
+
+def test_wrong_private_key_raises(server, credentials):
+    # A structurally valid but different EC key must fail to decrypt (GCM auth tag).
+    import base64
+
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec
+
+    other = ec.generate_private_key(ec.SECP256R1())
+    der = other.private_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    wrong_key = base64.b64encode(der).decode()
+
+    client = OpenBankingClient(
+        api_base_url=server.url_for("").rstrip("/"),
+        api_key=credentials["apiKey"],
+        private_key_pkcs8=wrong_key,
+    )
+    with pytest.raises(Exception):
+        client.get_accounts()
+    client.close()