Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

29.8 KB
Raw Blame
"""Enable Banking (PSD2) provider — European banks via open banking.

Auth model: RS256 JWT signed with the operator's application private key,
`kid` header set to the application ID. No client secret, no refresh token.
Sessions are valid for the consent window the user grants at their bank
(typically 90–180 days); after that, re-authorization is required.

The flow requires the user to pick a country and bank before the
authorization URL can be generated, so `get_oauth_url` takes
`flow_params={"country", "institution_name"}`.
"""
from __future__ import annotations

import hashlib
import logging
import time
from datetime import date, datetime, timedelta, timezone
from decimal import Decimal, InvalidOperation
from pathlib import Path
from typing import Any, Optional

import httpx
from jose import jwt

from app.agents.services.crypto import decrypt, encrypt
from app.core.config import get_settings
from app.providers.base import (
    AccountData,
    BankProvider,
    ConnectionData,
    InstitutionData,
    InstitutionListData,
    ProviderRateLimited,
    ProviderUserActionRequired,
    SessionExpiredError,
    TransactionData,
    default_oauth_redirect_uri,
    mask_last4,
)

logger = logging.getLogger(__name__)

JWT_ISSUER = "enablebanking.com"
JWT_AUDIENCE = "api.enablebanking.com"
JWT_LIFETIME_SECONDS = 3500  # under EB's 1h cap; refresh well before
JWT_CACHE_REFRESH_BEFORE = 600  # re-mint with 10 min buffer

MAX_VALID_UNTIL_DAYS = 179
DEFAULT_VALID_UNTIL_DAYS = MAX_VALID_UNTIL_DAYS
DEFAULT_PSU_TYPE = "personal"
# Days of history requested on a fresh fetch, counted inclusively (today is
# day 1). Many banks cap the window at exactly 90 days.
DEFAULT_HISTORY_DAYS = 90
# Shorter window retried when a bank rejects the default one as out of bounds.
FALLBACK_HISTORY_DAYS = 30
TRANSACTION_PAGE_LIMIT = 50  # safety cap
# Session states after which no data can be read until the user re-authorizes.
TERMINAL_SESSION_STATUSES = frozenset(
    {"EXPIRED", "REVOKED", "CLOSED", "CANCELLED", "INVALID"}
)


def _map_cash_account_type(eb_type: Optional[str]) -> str:
    """Map EB cash_account_type (ISO 20022) to Securo internal type."""
    if not eb_type:
        return "checking"
    mapping = {
        "CACC": "checking",  # current
        "SVGS": "savings",
        "CARD": "credit_card",
        "CASH": "checking",
        "LOAN": "checking",  # we don't model loan accounts yet
        "OTHR": "checking",
    }
    return mapping.get(eb_type.upper(), "checking")


def _account_identifier(raw: dict) -> Optional[str]:
    """Pull the bank's own identifier for an account out of an EB details payload.

    EB reports it in three places, in descending order of usefulness: the IBAN
    on `account_id`, a non-IBAN scheme (BBAN, sort-code-and-account) on
    `account_id.other`, and the `all_account_ids` list. Banks outside SEPA only
    populate the latter two, so we fall through rather than assuming an IBAN.
    """
    account_id = raw.get("account_id") or {}
    if isinstance(account_id, dict):
        iban = account_id.get("iban")
        if iban:
            return str(iban)
        other = account_id.get("other") or {}
        if isinstance(other, dict) and other.get("identification"):
            return str(other["identification"])
    for entry in raw.get("all_account_ids") or []:
        if isinstance(entry, dict) and entry.get("identification"):
            return str(entry["identification"])
    return None


def _pick_balance(balances: list[dict]) -> Optional[dict]:
    """Pick the most useful balance from EB's list (prefer closing booked)."""
    if not balances:
        return None
    priority = ["CLBD", "ITAV", "CLAV", "XPCD", "OPBD", "OPAV"]
    by_type = {b.get("balance_type") or b.get("type"): b for b in balances if isinstance(b, dict)}
    for key in priority:
        if key in by_type:
            return by_type[key]
    return balances[0] if isinstance(balances[0], dict) else None


def _balance_decimal(balance: Optional[dict]) -> Decimal:
    if not balance:
        return Decimal("0")
    amount = balance.get("balance_amount") or balance.get("amount") or {}
    try:
        return Decimal(str(amount.get("amount", "0")))
    except (InvalidOperation, AttributeError):
        return Decimal("0")


def _balance_currency(balance: Optional[dict], fallback: str) -> str:
    if not balance:
        return fallback
    amount = balance.get("balance_amount") or balance.get("amount") or {}
    return amount.get("currency") or fallback


def _parse_iso_date(value: Any) -> Optional[date]:
    if not isinstance(value, str):
        return None
    try:
        return date.fromisoformat(value[:10])
    except (ValueError, TypeError):
        return None


def _join_remittance(value: Any) -> str:
    if isinstance(value, list):
        return " ".join(str(v) for v in value if v).strip()
    return (value or "").strip() if isinstance(value, str) else ""


def _counterparty_name(raw: dict, party: str) -> str:
    party_obj = raw.get(party)
    name = party_obj.get("name") if isinstance(party_obj, dict) else None
    if not isinstance(name, str) or not name.strip():
        name = raw.get(f"{party}_name")
    return name.strip() if isinstance(name, str) else ""


def _txn_fingerprint(account_uid: str, raw: dict) -> str:
    """Stable id for a booked transaction.

    EB's `entry_reference` is unreliable across providers, so we hash the
    fields most likely to persist across re-fetches of the same booked txn.
    Pending → booked transitions deliberately produce a different id; the
    sync layer's pending↔posted twin matcher handles that.
    """
    amount = raw.get("transaction_amount") or {}
    creditor_acc = raw.get("creditor_account")
    debtor_acc = raw.get("debtor_account")
    creditor_iban = (
        creditor_acc.get("iban")
        if isinstance(creditor_acc, dict) and isinstance(creditor_acc.get("iban"), str)
        else ""
    )
    debtor_iban = (
        debtor_acc.get("iban")
        if isinstance(debtor_acc, dict) and isinstance(debtor_acc.get("iban"), str)
        else ""
    )
    creditor_identity = creditor_iban.strip() or _counterparty_name(raw, "creditor")
    debtor_identity = debtor_iban.strip() or _counterparty_name(raw, "debtor")
    parts = [
        str(account_uid),
        str(raw.get("booking_date") or ""),
        str(raw.get("value_date") or ""),
        str(raw.get("transaction_date") or ""),
        str(amount.get("amount") or "") if isinstance(amount, dict) else "",
        str(amount.get("currency") or "") if isinstance(amount, dict) else "",
        str(raw.get("credit_debit_indicator") or ""),
        _join_remittance(raw.get("remittance_information"))[:80],
        creditor_identity,
        debtor_identity,
    ]
    digest = hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
    return digest[:32]


def _extract_payee(raw: dict, indicator: str, source: str) -> Optional[str]:
    """Pick a payee name from EB transaction payload.

    DBIT (money out): creditor (the recipient).
    CRDT (money in): debtor (the sender).
    """
    if source == "none":
        return None
    creditor = _counterparty_name(raw, "creditor")
    debtor = _counterparty_name(raw, "debtor")
    if source == "description":
        return None  # let description carry the info
    if indicator == "DBIT":
        return creditor or debtor
    return debtor or creditor


def _history_start(today: date, days: int) -> date:
    """First day of a ``days``-long window ending today, both ends inclusive."""
    return today - timedelta(days=days - 1)


def _is_wrong_period_error(resp: httpx.Response) -> bool:
    """True when the bank rejected the requested date range as out of bounds."""
    if resp.status_code != 422:
        return False
    try:
        body = resp.json()
    except ValueError:
        return False
    return isinstance(body, dict) and body.get("error") == "WRONG_TRANSACTIONS_PERIOD"


class EnableBankingProvider(BankProvider):
    """Enable Banking PSD2 connector."""

    # Cache the JWT across requests to amortize the RS256 signing cost.
    _cached_token: Optional[str] = None
    _cached_token_exp: float = 0.0
    _cached_private_key: Optional[str] = None

    @property
    def name(self) -> str:
        return "enable_banking"

    @property
    def flow_type(self) -> str:
        return "oauth"

    @property
    def redirect_uri(self) -> str:
        return (
            get_settings().enable_banking_oauth_redirect_uri
            or default_oauth_redirect_uri()
        )

    # ----- credentials -----

    @classmethod
    def _load_private_key(cls) -> str:
        if cls._cached_private_key:
            return cls._cached_private_key
        settings = get_settings()
        key_file = (settings.enable_banking_private_key_file or "").strip()
        if key_file:
            cls._cached_private_key = Path(key_file).read_text(encoding="utf-8")
            return cls._cached_private_key
        raw = settings.enable_banking_private_key.get_secret_value() or ""
        if "\\n" in raw and "\n" not in raw:
            raw = raw.replace("\\n", "\n")
        cls._cached_private_key = raw
        return cls._cached_private_key

    @classmethod
    def _jwt_token(cls) -> str:
        now = time.time()
        if cls._cached_token and now < cls._cached_token_exp - JWT_CACHE_REFRESH_BEFORE:
            return cls._cached_token
        settings = get_settings()
        app_id = settings.enable_banking_app_id
        if not app_id:
            raise RuntimeError("ENABLE_BANKING_APP_ID is not configured")
        private_key = cls._load_private_key()
        if not private_key:
            raise RuntimeError("Enable Banking private key is not configured")
        issued_at = int(now)
        exp = issued_at + JWT_LIFETIME_SECONDS
        claims = {
            "iss": JWT_ISSUER,
            "aud": JWT_AUDIENCE,
            "iat": issued_at,
            "exp": exp,
        }
        token = jwt.encode(
            claims,
            private_key,
            algorithm="RS256",
            headers={"kid": app_id, "typ": "JWT"},
        )
        cls._cached_token = token
        cls._cached_token_exp = exp
        return token

    # ----- HTTP layer -----

    def _client(self) -> httpx.AsyncClient:
        settings = get_settings()
        return httpx.AsyncClient(
            base_url=settings.enable_banking_api_url.rstrip("/"),
            headers={
                "Authorization": f"Bearer {self._jwt_token()}",
                "Accept": "application/json",
                "Content-Type": "application/json",
                "User-Agent": "Securo/0.1 (+https://usesecuro.com)",
            },
            timeout=30.0,
        )

    async def _request(
        self,
        method: str,
        path: str,
        *,
        params: Optional[dict] = None,
        json_body: Optional[dict] = None,
    ) -> dict:
        async with self._client() as client:
            resp = await client.request(method, path, params=params, json=json_body)
        if resp.status_code in (401, 410):
            raise SessionExpiredError(
                f"Enable Banking returned {resp.status_code} for {path}"
            )
        if resp.status_code == 429:
            # The bank (ASPSP) is throttling us — transient, not a broken
            # connection. Surface a distinct type so sync can skip-and-retry
            # instead of erroring the connection.
            raise ProviderRateLimited(
                f"Enable Banking {method} {path} → 429: {resp.text[:200]}"
            )
        if resp.status_code >= 400:
            raise httpx.HTTPStatusError(
                f"Enable Banking {method} {path} → {resp.status_code}: {resp.text[:300]}",
                request=resp.request,
                response=resp,
            )
        return resp.json()

    # ----- institution listing -----

    async def list_institutions(
        self, country: Optional[str] = None
    ) -> InstitutionListData:
        params: dict[str, Any] = {}
        if country:
            params["country"] = country.upper()
        data = await self._request("GET", "/aspsps", params=params or None)
        raw_list = data.get("aspsps") or []
        institutions: list[InstitutionData] = []
        countries: set[str] = set()
        for item in raw_list:
            inst_country = (item.get("country") or "").upper()
            if inst_country:
                countries.add(inst_country)
            if (maximum_consent_validity := item.get("maximum_consent_validity", None)) is not None:
                maximum_consent_validity = timedelta(seconds=maximum_consent_validity).days

            institutions.append(
                InstitutionData(
                    name=item.get("name") or "",
                    display_name=item.get("name") or "",
                    country=inst_country,
                    logo=item.get("logo"),
                    bic=item.get("bic"),
                    psu_types=list(item.get("psu_types") or []),
                    max_consent_days=maximum_consent_validity,
                )
            )
        institutions.sort(key=lambda i: (i.country, i.display_name.lower()))
        return InstitutionListData(
            countries=sorted(countries),
            institutions=institutions,
        )

    # ----- OAuth (authorization) -----

    def _build_auth_payload(
        self,
        *,
        country: str,
        institution_name: str,
        redirect_uri: str,
        state: str,
        psu_type: str,
        valid_until_days: int,
    ) -> dict:
        valid_until_days = min(valid_until_days, MAX_VALID_UNTIL_DAYS)
        valid_until_dt = datetime.now(timezone.utc) + timedelta(days=valid_until_days)
        # EB wants RFC3339 with a trailing 'Z' for UTC.
        valid_until = valid_until_dt.replace(microsecond=0).isoformat().replace(
            "+00:00", "Z"
        )
        return {
            "access": {"valid_until": valid_until},
            "aspsp": {"name": institution_name, "country": country.upper()},
            "state": state,
            "redirect_url": redirect_uri,
            "psu_type": psu_type,
        }

    async def get_oauth_url(
        self,
        redirect_uri: str,
        state: str,
        flow_params: Optional[dict] = None,
    ) -> str:
        flow_params = flow_params or {}
        country = (flow_params.get("country") or "").strip().upper()
        institution_name = (flow_params.get("institution_name") or "").strip()
        if not country or not institution_name:
            raise ValueError(
                "Enable Banking requires flow_params with 'country' and 'institution_name'"
            )
        psu_type = (flow_params.get("psu_type") or DEFAULT_PSU_TYPE).strip()
        valid_until_days = int(
            flow_params.get("valid_until_days") or DEFAULT_VALID_UNTIL_DAYS
        )
        payload = self._build_auth_payload(
            country=country,
            institution_name=institution_name,
            redirect_uri=redirect_uri,
            state=state,
            psu_type=psu_type,
            valid_until_days=valid_until_days,
        )
        data = await self._request("POST", "/auth", json_body=payload)
        url = data.get("url")
        if not url:
            raise RuntimeError("Enable Banking /auth did not return a redirect URL")
        return url

    async def reauth_url(
        self,
        credentials: dict,
        settings: dict,
        redirect_uri: str,
        state: str,
    ) -> str:
        stored = (settings or {}).get("flow_params") or {}
        if not stored.get("country") or not stored.get("institution_name"):
            raise RuntimeError(
                "Cannot reauth Enable Banking connection without stored flow_params"
            )
        return await self.get_oauth_url(redirect_uri, state, flow_params=stored)

    # ----- session exchange -----

    async def handle_oauth_callback(self, code: str) -> ConnectionData:
        data = await self._request("POST", "/sessions", json_body={"code": code})
        session_id = data.get("session_id")
        if not session_id:
            raise RuntimeError("Enable Banking /sessions response missing session_id")

        accounts_raw = data.get("accounts")
        if not accounts_raw:
            raise ProviderUserActionRequired(
                "Enable Banking returned no accounts. In restricted mode you must "
                "pre-link accounts in the Enable Banking portal before connecting.",
                code="no_accounts_linked",
                help_url="https://enablebanking.com/",
            )

        aspsp = data.get("aspsp") or {}
        institution_name = aspsp.get("name") or "Bank"
        access = data.get("access") or {}
        valid_until = access.get("valid_until")

        accounts: list[AccountData] = []
        for raw_acc in accounts_raw:
            if isinstance(raw_acc, str):
                continue  # restricted clients can return account IDs as strings
            accounts.append(await self._build_account(raw_acc))

        encrypted_session = encrypt(session_id) or session_id
        credentials: dict[str, Any] = {
            "session_id_enc": encrypted_session,
            "valid_until": valid_until,
            "aspsp": {
                "name": institution_name,
                "country": aspsp.get("country"),
            },
        }
        return ConnectionData(
            external_id=session_id,
            institution_name=institution_name,
            credentials=credentials,
            accounts=accounts,
            # The session payload sometimes carries the ASPSP logo; when it
            # doesn't, the sync layer backfills it via get_institution_logo.
            logo_url=aspsp.get("logo"),
        )

    async def get_institution_logo(self, credentials: dict) -> Optional[str]:
        aspsp = credentials.get("aspsp") or {}
        name = aspsp.get("name")
        country = aspsp.get("country")
        if not name:
            return None
        institutions = await self.list_institutions(country)
        for inst in institutions.institutions:
            if inst.name == name:
                return inst.logo
        return None

    async def _build_account(
        self, raw: dict, stable_external_id: Optional[str] = None
    ) -> AccountData:
        uid = raw.get("uid") or raw.get("account_uid") or ""
        currency = raw.get("currency") or "EUR"
        # EB doesn't include balances in the session payload; fetch separately.
        balance = Decimal("0")
        try:
            bal_resp = await self._request("GET", f"/accounts/{uid}/balances")
            picked = _pick_balance(bal_resp.get("balances") or [])
            balance = _balance_decimal(picked)
            currency = _balance_currency(picked, currency)
        except (httpx.HTTPError, SessionExpiredError) as exc:
            logger.warning(
                "Failed to fetch balances for account %s: %s", uid, exc
            )
        name = (
            raw.get("display_name")
            or raw.get("product")
            or raw.get("name")
            or "Account"
        )
        return AccountData(
            external_id=uid,
            name=name,
            type=_map_cash_account_type(raw.get("cash_account_type")),
            balance=balance,
            currency=currency,
            masked_number=mask_last4(_account_identifier(raw)),
            # From the session payload: `uid` is scoped to one session, this
            # hash is what lets a later session find the same account again.
            stable_external_id=stable_external_id,
        )

    # ----- account / transaction fetches -----

    def _session_id(self, credentials: dict) -> str:
        enc = credentials.get("session_id_enc")
        if enc:
            decoded = decrypt(enc)
            if decoded:
                return decoded
        # Backward compat: plaintext during dev.
        return credentials.get("session_id") or ""

    @staticmethod
    def _account_uids(session_data: dict) -> list[str]:
        """Extract account uids from a GET /sessions payload.

        EB exposes the uids in two shapes and neither carries the account
        name/type: `accounts` is a list of uid *strings*, while
        `accounts_data` is a list of objects keyed by `uid` (plus identity
        hashes only). The human-readable name/type/currency live behind
        /accounts/{uid}/details, fetched per account below.
        """
        uids: list[str] = []
        for entry in session_data.get("accounts_data") or []:
            if isinstance(entry, dict):
                uid = entry.get("uid") or entry.get("account_uid")
                if uid:
                    uids.append(uid)
        if uids:
            return uids
        # Fallback: `accounts` is a plain list of uid strings.
        return [a for a in (session_data.get("accounts") or []) if isinstance(a, str)]

    async def get_accounts(self, credentials: dict) -> list[AccountData]:
        session_id = self._session_id(credentials)
        if not session_id:
            raise SessionExpiredError("Enable Banking session_id missing")
        data = await self._request("GET", f"/sessions/{session_id}")
        # The bank can end consent well before `valid_until`; EB still answers
        # 200 here but flags the session, and every account call then fails.
        # Raise so the connection is marked expired instead of "syncing" zero
        # accounts forever.
        status = (data.get("status") or "").upper()
        if status in TERMINAL_SESSION_STATUSES:
            raise SessionExpiredError(f"Enable Banking session is {status}")
        uids = self._account_uids(data)
        # EB keys each account by a uid scoped to this session; the
        # identification_hash is the id that survives a reauthorisation. It comes
        # in the same payload we just fetched, so carry it through; otherwise a
        # reconnect re-keys every account and the sync duplicates them all.
        stable_external_ids = {
            entry.get("uid"): entry.get("identification_hash")
            for entry in (data.get("accounts_data") or [])
            if isinstance(entry, dict) and entry.get("uid")
        }
        result: list[AccountData] = []
        for uid in uids:
            try:
                details = await self._request("GET", f"/accounts/{uid}/details")
            except httpx.HTTPError as exc:
                # A *transient* per-account failure. Without details we can't
                # safely name/type the account, and a bare-uid AccountData would
                # overwrite the stored name with a placeholder. Skip this account
                # for this run (non-destructive: the existing row and its
                # transactions are left intact and the next sync retries) rather
                # than corrupt it. SessionExpiredError is deliberately NOT caught
                # here: a dead consent is global, never per-account.
                logger.warning("Failed to fetch details for account %s: %s", uid, exc)
                continue
            result.append(await self._build_account(details, stable_external_ids.get(uid)))
        return result

    async def get_transactions(
        self,
        credentials: dict,
        account_external_id: str,
        since: Optional[date] = None,
        payee_source: str = "auto",
    ) -> list[TransactionData]:
        _ = self._session_id(credentials)  # surface expired credentials early
        # Enable Banking reads date_to as an inclusive UTC calendar day, so the
        # window ends on the UTC date regardless of the application calendar;
        # otherwise an application west of UTC would stop short of the day's
        # newest transactions until its own date caught up.
        today = datetime.now(timezone.utc).date()
        if since is not None:
            return await self._fetch_transactions(
                account_external_id, since, today, payee_source
            )
        try:
            return await self._fetch_transactions(
                account_external_id,
                _history_start(today, DEFAULT_HISTORY_DAYS),
                today,
                payee_source,
            )
        except httpx.HTTPStatusError as exc:
            if not _is_wrong_period_error(exc.response):
                raise
            logger.warning(
                "Enable Banking rejected a %d-day history window for account %s; "
                "retrying with %d days",
                DEFAULT_HISTORY_DAYS,
                account_external_id,
                FALLBACK_HISTORY_DAYS,
            )
            return await self._fetch_transactions(
                account_external_id,
                _history_start(today, FALLBACK_HISTORY_DAYS),
                today,
                payee_source,
            )

    async def _fetch_transactions(
        self,
        account_external_id: str,
        start: date,
        end: date,
        payee_source: str,
    ) -> list[TransactionData]:
        date_from = start.isoformat()
        date_to = end.isoformat()
        transactions: list[TransactionData] = []
        continuation_key: Optional[str] = None
        seen_continuation_keys: set[str] = set()
        seen_transaction_ids: set[str] = set()
        for _ in range(TRANSACTION_PAGE_LIMIT):
            params: dict[str, Any] = {"date_from": date_from, "date_to": date_to}
            if continuation_key:
                params["continuation_key"] = continuation_key
            page = await self._request(
                "GET",
                f"/accounts/{account_external_id}/transactions",
                params=params,
            )
            for raw_txn, status in self._iter_transactions(page):
                parsed = self._build_transaction(
                    account_external_id, raw_txn, status, payee_source
                )
                # A broken pagination cursor can make Enable Banking return a
                # page we have already consumed. Keep the result idempotent
                # even before the repeated cursor is detected below.
                if parsed and parsed.external_id not in seen_transaction_ids:
                    transactions.append(parsed)
                    seen_transaction_ids.add(parsed.external_id)

            next_continuation_key = page.get("continuation_key") or None
            if not next_continuation_key:
                break
            if next_continuation_key in seen_continuation_keys:
                logger.warning(
                    "Enable Banking pagination loop detected for account %s "
                    "(repeated continuation key); stopping pagination",
                    account_external_id,
                )
                break
            seen_continuation_keys.add(next_continuation_key)
            continuation_key = next_continuation_key
        return transactions

    @staticmethod
    def _iter_transactions(page: dict):
        """Yield (raw_txn, status) tuples handling both nested and flat shapes."""
        body = page.get("transactions")
        if isinstance(body, dict):
            for raw in body.get("booked") or []:
                yield raw, "posted"
            for raw in body.get("pending") or []:
                yield raw, "pending"
        elif isinstance(body, list):
            for raw in body:
                raw_status = (raw.get("status") or "").upper()
                yield raw, "pending" if raw_status in {"PDNG", "PENDING"} else "posted"

    def _build_transaction(
        self,
        account_uid: str,
        raw: dict,
        status: str,
        payee_source: str,
    ) -> Optional[TransactionData]:
        amount_obj = raw.get("transaction_amount") or {}
        if not isinstance(amount_obj, dict):
            return None
        try:
            amount = Decimal(str(amount_obj.get("amount", "0")))
        except InvalidOperation:
            return None
        indicator = (raw.get("credit_debit_indicator") or "").upper()
        txn_type = "debit" if indicator == "DBIT" else "credit"
        amount = amount.copy_abs()
        currency = amount_obj.get("currency") or "EUR"
        booking = _parse_iso_date(raw.get("booking_date"))
        value = _parse_iso_date(raw.get("value_date"))
        txn_date = booking or value or _parse_iso_date(raw.get("transaction_date"))
        if not txn_date:
            return None
        additional_value = raw.get("additional_information")
        additional = additional_value.strip() if isinstance(additional_value, str) else ""
        description = _join_remittance(raw.get("remittance_information")) or additional
        if not description:
            creditor = _counterparty_name(raw, "creditor")
            debtor = _counterparty_name(raw, "debtor")
            if indicator == "DBIT":
                description = creditor or debtor or ""
            else:
                description = debtor or creditor or ""
        description = description.strip()[:500] or "Transaction"
        entry_ref = (raw.get("entry_reference") or "").strip()
        external_id = (
            entry_ref if entry_ref and entry_ref != "0" else _txn_fingerprint(account_uid, raw)
        )
        return TransactionData(
            external_id=external_id,
            description=description,
            amount=amount,
            date=txn_date,
            type=txn_type,
            currency=currency,
            status=status,
            payee=_extract_payee(raw, indicator, payee_source),
            raw_data=raw,
        )

    # ----- credential lifecycle -----

    async def refresh_credentials(self, credentials: dict) -> dict:
        valid_until = credentials.get("valid_until")
        if valid_until:
            try:
                # Accept both RFC3339 with 'Z' and offset forms.
                normalized = valid_until.replace("Z", "+00:00")
                expires_at = datetime.fromisoformat(normalized)
                if expires_at.tzinfo is None:
                    expires_at = expires_at.replace(tzinfo=timezone.utc)
                if expires_at <= datetime.now(timezone.utc):
                    raise SessionExpiredError(
                        "Enable Banking session expired; user must re-authorize"
                    )
            except ValueError:
                pass
        return credentials