init
This commit is contained in:
Lars Nolden
@@ -0,0 +1,486 @@
|
||||
package banking
|
||||
|
||||
// DTOs and authentication follow https://enablebanking.com/docs/api/reference/.
|
||||
// In particular entry_reference is stable across sessions, transaction_id is NOT;
|
||||
// GET /sessions returns UID strings, unlike POST /sessions' account objects.
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"crypto"
|
||||
"crypto/rand"
|
||||
"crypto/rsa"
|
||||
"crypto/sha256"
|
||||
"crypto/x509"
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"encoding/pem"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"finance-duck/internal/domain"
|
||||
)
|
||||
|
||||
// ErrReconnect identifies inactive bank consent, not application authentication
|
||||
// failures or temporary transport/provider errors.
|
||||
var ErrReconnect = errors.New("bank consent requires reconnection")
|
||||
|
||||
type Session struct {
|
||||
ID string `json:"session_id"`
|
||||
ValidUntil string `json:"valid_until"`
|
||||
Accounts []domain.Account `json:"accounts"`
|
||||
}
|
||||
type Balance struct {
|
||||
Amount domain.Money `json:"amount"`
|
||||
Currency string `json:"currency"`
|
||||
Type string `json:"type"`
|
||||
ReferenceDate string `json:"reference_date,omitempty"`
|
||||
}
|
||||
type Provider interface {
|
||||
Authorize(context.Context, string, string, string) (string, error)
|
||||
Exchange(context.Context, string) (Session, error)
|
||||
Status(context.Context, string) (Session, error)
|
||||
Balances(context.Context, string) ([]Balance, error)
|
||||
Transactions(context.Context, domain.Account, string, string) ([]domain.Facts, error)
|
||||
}
|
||||
type EnableBanking struct {
|
||||
HTTPClient *http.Client
|
||||
BaseURL string
|
||||
appID string
|
||||
key *rsa.PrivateKey
|
||||
redirectURL string
|
||||
}
|
||||
|
||||
var _ Provider = (*EnableBanking)(nil)
|
||||
|
||||
func NewEnableBanking(appID, keyFile, redirectURL string) (*EnableBanking, error) {
|
||||
if strings.TrimSpace(appID) == "" {
|
||||
return nil, fmt.Errorf("Enable Banking application ID is required")
|
||||
}
|
||||
redirect, err := url.Parse(redirectURL)
|
||||
if err != nil || redirect.Host == "" || (redirect.Scheme != "https" && redirect.Scheme != "http") || redirect.User != nil {
|
||||
return nil, fmt.Errorf("invalid Enable Banking redirect URL")
|
||||
}
|
||||
content, err := os.ReadFile(keyFile)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read Enable Banking RSA private key: %w", err)
|
||||
}
|
||||
block, _ := pem.Decode(content)
|
||||
if block == nil {
|
||||
return nil, fmt.Errorf("Enable Banking key must be PEM encoded")
|
||||
}
|
||||
var key *rsa.PrivateKey
|
||||
switch block.Type {
|
||||
case "RSA PRIVATE KEY":
|
||||
key, err = x509.ParsePKCS1PrivateKey(block.Bytes)
|
||||
case "PRIVATE KEY":
|
||||
var parsed any
|
||||
parsed, err = x509.ParsePKCS8PrivateKey(block.Bytes)
|
||||
if err == nil {
|
||||
var ok bool
|
||||
key, ok = parsed.(*rsa.PrivateKey)
|
||||
if !ok {
|
||||
err = fmt.Errorf("not RSA")
|
||||
}
|
||||
}
|
||||
default:
|
||||
err = fmt.Errorf("unsupported key type")
|
||||
}
|
||||
if err != nil || key == nil {
|
||||
return nil, fmt.Errorf("invalid Enable Banking RSA private key")
|
||||
}
|
||||
if key.N.BitLen() < 2048 {
|
||||
return nil, fmt.Errorf("Enable Banking RSA key must be at least 2048 bits")
|
||||
}
|
||||
if err = key.Validate(); err != nil {
|
||||
return nil, fmt.Errorf("invalid Enable Banking RSA private key")
|
||||
}
|
||||
return &EnableBanking{HTTPClient: &http.Client{Timeout: 30 * time.Second}, BaseURL: "https://api.enablebanking.com", appID: appID, key: key, redirectURL: redirectURL}, nil
|
||||
}
|
||||
func (p *EnableBanking) jwt() (string, error) {
|
||||
if p.key == nil || p.appID == "" {
|
||||
return "", fmt.Errorf("Enable Banking is not configured")
|
||||
}
|
||||
now := time.Now().Unix()
|
||||
header, _ := json.Marshal(map[string]any{"typ": "JWT", "alg": "RS256", "kid": p.appID})
|
||||
claims, _ := json.Marshal(map[string]any{"iss": "enablebanking.com", "aud": "api.enablebanking.com", "iat": now, "exp": now + 3600})
|
||||
unsigned := base64.RawURLEncoding.EncodeToString(header) + "." + base64.RawURLEncoding.EncodeToString(claims)
|
||||
hash := sha256.Sum256([]byte(unsigned))
|
||||
signature, err := rsa.SignPKCS1v15(rand.Reader, p.key, crypto.SHA256, hash[:])
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("sign Enable Banking token")
|
||||
}
|
||||
return unsigned + "." + base64.RawURLEncoding.EncodeToString(signature), nil
|
||||
}
|
||||
func (p *EnableBanking) request(ctx context.Context, method, path string, input, output any) error {
|
||||
// Enforce a deadline even when a caller injects a client without Timeout.
|
||||
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
|
||||
defer cancel()
|
||||
token, err := p.jwt()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var body io.Reader
|
||||
if input != nil {
|
||||
b, e := json.Marshal(input)
|
||||
if e != nil {
|
||||
return fmt.Errorf("encode Enable Banking request")
|
||||
}
|
||||
body = bytes.NewReader(b)
|
||||
}
|
||||
base, err := url.Parse(p.BaseURL)
|
||||
if err != nil || base.Host == "" || base.User != nil || (base.Scheme != "http" && base.Scheme != "https") {
|
||||
return fmt.Errorf("invalid Enable Banking base URL")
|
||||
}
|
||||
req, err := http.NewRequestWithContext(ctx, method, strings.TrimRight(p.BaseURL, "/")+path, body)
|
||||
if err != nil {
|
||||
return fmt.Errorf("create Enable Banking request")
|
||||
}
|
||||
req.Header.Set("Authorization", "Bearer "+token)
|
||||
req.Header.Set("Accept", "application/json")
|
||||
if input != nil {
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
}
|
||||
client := http.Client{Timeout: 30 * time.Second}
|
||||
if p.HTTPClient != nil {
|
||||
client = *p.HTTPClient
|
||||
}
|
||||
// Never forward signed credentials or financial requests through redirects.
|
||||
client.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }
|
||||
response, err := client.Do(req)
|
||||
if err != nil {
|
||||
if errors.Is(err, context.Canceled) {
|
||||
return context.Canceled
|
||||
}
|
||||
if errors.Is(err, context.DeadlineExceeded) {
|
||||
return fmt.Errorf("Enable Banking request timed out")
|
||||
}
|
||||
return fmt.Errorf("Enable Banking connection failed")
|
||||
}
|
||||
defer response.Body.Close()
|
||||
if response.StatusCode < 200 || response.StatusCode >= 300 {
|
||||
return fmt.Errorf("Enable Banking returned HTTP %d", response.StatusCode)
|
||||
}
|
||||
const limit = 16 << 20
|
||||
b, err := io.ReadAll(io.LimitReader(response.Body, limit+1))
|
||||
if err != nil {
|
||||
return fmt.Errorf("read Enable Banking response")
|
||||
}
|
||||
if len(b) > limit {
|
||||
return fmt.Errorf("Enable Banking response exceeded size limit")
|
||||
}
|
||||
if err = json.Unmarshal(b, output); err != nil {
|
||||
return fmt.Errorf("invalid Enable Banking response")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
type accessDTO struct {
|
||||
ValidUntil string `json:"valid_until"`
|
||||
}
|
||||
type institutionDTO struct {
|
||||
Name string `json:"name"`
|
||||
Country string `json:"country"`
|
||||
}
|
||||
type accountIdentificationDTO struct {
|
||||
IBAN string `json:"iban"`
|
||||
}
|
||||
type accountDTO struct {
|
||||
UID string `json:"uid"`
|
||||
IdentificationHash string `json:"identification_hash"`
|
||||
AccountID accountIdentificationDTO `json:"account_id"`
|
||||
Name string `json:"name"`
|
||||
Details string `json:"details"`
|
||||
Currency string `json:"currency"`
|
||||
}
|
||||
|
||||
func (a accountDTO) account(institution string) (domain.Account, error) {
|
||||
if !validCurrency(a.Currency) {
|
||||
return domain.Account{}, fmt.Errorf("Enable Banking account has invalid currency")
|
||||
}
|
||||
stable := a.IdentificationHash
|
||||
if stable == "" {
|
||||
stable = normalizeIBAN(a.AccountID.IBAN)
|
||||
}
|
||||
if stable == "" {
|
||||
return domain.Account{}, fmt.Errorf("Enable Banking account lacks stable identification")
|
||||
}
|
||||
name := a.Details
|
||||
if name == "" {
|
||||
name = a.Name
|
||||
}
|
||||
if name == "" {
|
||||
name = institution
|
||||
}
|
||||
return domain.Account{ID: "acct_" + digest("enablebanking", stable), DisplayName: name, Institution: institution, Currency: a.Currency, ExternalAccountID: a.UID, IBAN: normalizeIBAN(a.AccountID.IBAN), Active: a.UID != ""}, nil
|
||||
}
|
||||
func (p *EnableBanking) Authorize(ctx context.Context, institution, country, state string) (string, error) {
|
||||
country = strings.ToUpper(strings.TrimSpace(country))
|
||||
institution = strings.TrimSpace(institution)
|
||||
if institution == "" || len(country) != 2 || state == "" {
|
||||
return "", fmt.Errorf("institution, country and authorization state are required")
|
||||
}
|
||||
var list struct {
|
||||
ASPSPs []struct {
|
||||
institutionDTO
|
||||
MaximumConsentValidity int64 `json:"maximum_consent_validity"`
|
||||
} `json:"aspsps"`
|
||||
}
|
||||
query := url.Values{"country": {country}, "psu_type": {"personal"}, "service": {"AIS"}}
|
||||
if err := p.request(ctx, http.MethodGet, "/aspsps?"+query.Encode(), nil, &list); err != nil {
|
||||
return "", err
|
||||
}
|
||||
var validity int64
|
||||
for _, a := range list.ASPSPs {
|
||||
if a.Name == institution && a.Country == country {
|
||||
validity = a.MaximumConsentValidity
|
||||
break
|
||||
}
|
||||
}
|
||||
if validity <= 0 {
|
||||
return "", fmt.Errorf("institution is unavailable for personal account information or has no valid consent duration")
|
||||
}
|
||||
// Avoid overflow or unexpectedly long access while honoring each bank's limit.
|
||||
if validity > 180*24*3600 {
|
||||
validity = 180 * 24 * 3600
|
||||
}
|
||||
request := struct {
|
||||
Access struct {
|
||||
ValidUntil string `json:"valid_until"`
|
||||
Balances bool `json:"balances"`
|
||||
Transactions bool `json:"transactions"`
|
||||
} `json:"access"`
|
||||
ASPSP institutionDTO `json:"aspsp"`
|
||||
State string `json:"state"`
|
||||
RedirectURL string `json:"redirect_url"`
|
||||
PSUType string `json:"psu_type"`
|
||||
}{ASPSP: institutionDTO{institution, country}, State: state, RedirectURL: p.redirectURL, PSUType: "personal"}
|
||||
request.Access.ValidUntil = time.Now().UTC().Add(time.Duration(validity) * time.Second).Format(time.RFC3339)
|
||||
request.Access.Balances = true
|
||||
request.Access.Transactions = true
|
||||
var response struct {
|
||||
URL string `json:"url"`
|
||||
}
|
||||
if err := p.request(ctx, http.MethodPost, "/auth", request, &response); err != nil {
|
||||
return "", err
|
||||
}
|
||||
parsed, err := url.Parse(response.URL)
|
||||
if err != nil || parsed.Host == "" || parsed.Scheme != "https" || parsed.User != nil {
|
||||
return "", fmt.Errorf("Enable Banking returned invalid authorization URL")
|
||||
}
|
||||
return response.URL, nil
|
||||
}
|
||||
func (p *EnableBanking) Exchange(ctx context.Context, code string) (Session, error) {
|
||||
if code == "" {
|
||||
return Session{}, fmt.Errorf("authorization code is required")
|
||||
}
|
||||
var response struct {
|
||||
ID string `json:"session_id"`
|
||||
Accounts []accountDTO `json:"accounts"`
|
||||
Access accessDTO `json:"access"`
|
||||
ASPSP institutionDTO `json:"aspsp"`
|
||||
}
|
||||
if err := p.request(ctx, http.MethodPost, "/sessions", map[string]string{"code": code}, &response); err != nil {
|
||||
return Session{}, err
|
||||
}
|
||||
if response.ID == "" {
|
||||
return Session{}, fmt.Errorf("Enable Banking returned no session ID")
|
||||
}
|
||||
if _, err := time.Parse(time.RFC3339, response.Access.ValidUntil); err != nil {
|
||||
return Session{}, fmt.Errorf("Enable Banking returned invalid session expiry")
|
||||
}
|
||||
result := Session{ID: response.ID, ValidUntil: response.Access.ValidUntil, Accounts: []domain.Account{}}
|
||||
for _, a := range response.Accounts {
|
||||
account, err := a.account(response.ASPSP.Name)
|
||||
if err != nil {
|
||||
return Session{}, err
|
||||
}
|
||||
result.Accounts = append(result.Accounts, account)
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
func (p *EnableBanking) Status(ctx context.Context, sessionID string) (Session, error) {
|
||||
if sessionID == "" {
|
||||
return Session{}, fmt.Errorf("session ID is required")
|
||||
}
|
||||
var response struct {
|
||||
Status string `json:"status"`
|
||||
Accounts []string `json:"accounts"`
|
||||
AccountsData []accountDTO `json:"accounts_data"`
|
||||
Access accessDTO `json:"access"`
|
||||
ASPSP institutionDTO `json:"aspsp"`
|
||||
}
|
||||
if err := p.request(ctx, http.MethodGet, "/sessions/"+url.PathEscape(sessionID), nil, &response); err != nil {
|
||||
return Session{}, err
|
||||
}
|
||||
if response.Status != "AUTHORIZED" {
|
||||
return Session{}, fmt.Errorf("Enable Banking session is not authorized: %w", ErrReconnect)
|
||||
}
|
||||
expires, err := time.Parse(time.RFC3339, response.Access.ValidUntil)
|
||||
if err != nil {
|
||||
return Session{}, fmt.Errorf("Enable Banking returned invalid session expiry")
|
||||
}
|
||||
if !expires.After(time.Now()) {
|
||||
return Session{}, fmt.Errorf("Enable Banking session expired: %w", ErrReconnect)
|
||||
}
|
||||
result := Session{ID: sessionID, ValidUntil: response.Access.ValidUntil, Accounts: []domain.Account{}}
|
||||
hashes := map[string]string{}
|
||||
for _, a := range response.AccountsData {
|
||||
hashes[a.UID] = a.IdentificationHash
|
||||
}
|
||||
for _, id := range response.Accounts {
|
||||
if id == "" {
|
||||
return Session{}, fmt.Errorf("Enable Banking returned empty account identifier")
|
||||
}
|
||||
var details accountDTO
|
||||
if err := p.request(ctx, http.MethodGet, "/accounts/"+url.PathEscape(id)+"/details", nil, &details); err != nil {
|
||||
return Session{}, err
|
||||
}
|
||||
details.UID = id
|
||||
if details.IdentificationHash == "" {
|
||||
details.IdentificationHash = hashes[id]
|
||||
}
|
||||
a, err := details.account(response.ASPSP.Name)
|
||||
if err != nil {
|
||||
return Session{}, err
|
||||
}
|
||||
result.Accounts = append(result.Accounts, a)
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
|
||||
type amountDTO struct {
|
||||
Amount string `json:"amount"`
|
||||
Currency string `json:"currency"`
|
||||
}
|
||||
|
||||
func (p *EnableBanking) Balances(ctx context.Context, externalAccountID string) ([]Balance, error) {
|
||||
if externalAccountID == "" {
|
||||
return nil, fmt.Errorf("account is not connected to Enable Banking")
|
||||
}
|
||||
var response struct {
|
||||
Balances []struct {
|
||||
Amount amountDTO `json:"balance_amount"`
|
||||
Type string `json:"balance_type"`
|
||||
ReferenceDate string `json:"reference_date"`
|
||||
} `json:"balances"`
|
||||
}
|
||||
if err := p.request(ctx, http.MethodGet, "/accounts/"+url.PathEscape(externalAccountID)+"/balances", nil, &response); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
result := make([]Balance, 0, len(response.Balances))
|
||||
for _, b := range response.Balances {
|
||||
amount, err := domain.ParseMoney(b.Amount.Amount)
|
||||
if err != nil || !validCurrency(b.Amount.Currency) {
|
||||
return nil, fmt.Errorf("Enable Banking returned invalid balance amount")
|
||||
}
|
||||
result = append(result, Balance{Amount: amount, Currency: b.Amount.Currency, Type: b.Type, ReferenceDate: b.ReferenceDate})
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
|
||||
type transactionDTO struct {
|
||||
EntryReference string `json:"entry_reference"`
|
||||
Amount amountDTO `json:"transaction_amount"`
|
||||
Indicator string `json:"credit_debit_indicator"`
|
||||
Status string `json:"status"`
|
||||
BookingDate string `json:"booking_date"`
|
||||
ValueDate string `json:"value_date"`
|
||||
TransactionDate string `json:"transaction_date"`
|
||||
Remittance []string `json:"remittance_information"`
|
||||
ReferenceNumber string `json:"reference_number"`
|
||||
Creditor struct {
|
||||
Name string `json:"name"`
|
||||
} `json:"creditor"`
|
||||
Debtor struct {
|
||||
Name string `json:"name"`
|
||||
} `json:"debtor"`
|
||||
CreditorAccount accountIdentificationDTO `json:"creditor_account"`
|
||||
DebtorAccount accountIdentificationDTO `json:"debtor_account"`
|
||||
}
|
||||
|
||||
func (p *EnableBanking) Transactions(ctx context.Context, account domain.Account, from, to string) ([]domain.Facts, error) {
|
||||
if account.ID == "" || account.ExternalAccountID == "" {
|
||||
return nil, fmt.Errorf("account is not connected to Enable Banking")
|
||||
}
|
||||
for _, date := range []string{from, to} {
|
||||
if date != "" {
|
||||
if _, err := time.Parse("2006-01-02", date); err != nil {
|
||||
return nil, fmt.Errorf("invalid transaction date range")
|
||||
}
|
||||
}
|
||||
}
|
||||
if from != "" && to != "" && from > to {
|
||||
return nil, fmt.Errorf("invalid transaction date range")
|
||||
}
|
||||
query := url.Values{"transaction_status": {"BOOK"}}
|
||||
if from != "" {
|
||||
query.Set("date_from", from)
|
||||
}
|
||||
if to != "" {
|
||||
query.Set("date_to", to)
|
||||
}
|
||||
result := make([]domain.Facts, 0)
|
||||
seen := map[string]bool{}
|
||||
for range 1000 {
|
||||
var response struct {
|
||||
Transactions []transactionDTO `json:"transactions"`
|
||||
ContinuationKey string `json:"continuation_key"`
|
||||
}
|
||||
if err := p.request(ctx, http.MethodGet, "/accounts/"+url.PathEscape(account.ExternalAccountID)+"/transactions?"+query.Encode(), nil, &response); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
for _, t := range response.Transactions {
|
||||
if t.Status != "BOOK" {
|
||||
continue
|
||||
}
|
||||
amount, err := domain.ParseMoney(t.Amount.Amount)
|
||||
if err != nil || strings.HasPrefix(amount.String(), "-") || !validCurrency(t.Amount.Currency) {
|
||||
return nil, fmt.Errorf("Enable Banking returned invalid transaction amount")
|
||||
}
|
||||
party, iban := t.Debtor.Name, t.DebtorAccount.IBAN
|
||||
switch t.Indicator {
|
||||
case "DBIT":
|
||||
amount, err = domain.ParseMoney("-" + amount.String())
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("invalid debit amount")
|
||||
}
|
||||
party, iban = t.Creditor.Name, t.CreditorAccount.IBAN
|
||||
case "CRDT":
|
||||
default:
|
||||
return nil, fmt.Errorf("Enable Banking returned invalid credit/debit indicator")
|
||||
}
|
||||
// Booked records without a booking date cannot be placed truthfully in the journal.
|
||||
if _, err := time.Parse("2006-01-02", t.BookingDate); err != nil {
|
||||
return nil, fmt.Errorf("Enable Banking booked transaction has no valid booking date")
|
||||
}
|
||||
if (from != "" && t.BookingDate < from) || (to != "" && t.BookingDate > to) {
|
||||
continue
|
||||
}
|
||||
if t.ValueDate != "" {
|
||||
if _, err := time.Parse("2006-01-02", t.ValueDate); err != nil {
|
||||
return nil, fmt.Errorf("Enable Banking returned invalid value date")
|
||||
}
|
||||
}
|
||||
description := strings.Join(t.Remittance, "\n")
|
||||
if description == "" {
|
||||
description = t.ReferenceNumber
|
||||
}
|
||||
result = append(result, domain.Facts{Source: "enablebanking", AccountID: account.ID, BookingDate: t.BookingDate, ValueDate: t.ValueDate, Amount: amount, Currency: t.Amount.Currency, RawDescription: description, ExternalID: t.EntryReference, Counterparty: party, CounterpartyIBAN: normalizeIBAN(iban)})
|
||||
}
|
||||
if response.ContinuationKey == "" {
|
||||
return result, nil
|
||||
}
|
||||
if seen[response.ContinuationKey] {
|
||||
return nil, fmt.Errorf("Enable Banking repeated a pagination key")
|
||||
}
|
||||
seen[response.ContinuationKey] = true
|
||||
query.Set("continuation_key", response.ContinuationKey)
|
||||
}
|
||||
return nil, fmt.Errorf("Enable Banking transaction pagination exceeded limit")
|
||||
}
|
||||
Reference in New Issue
Block a user