open-banking-io 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d7f5d02a8a4a808faa00f6c78558b2e11c90a7c5b852062682746c1ab2a3da1
+  data.tar.gz: c24bf4296b70c0b5ffc6af71faae40d4c559301f59654358c6c34e94130bbef3
+SHA512:
+  metadata.gz: d4870301dfb82caf2456f2b24a7ae8e6b469375da2bf6ff86821196eaf620f3e1b734deae2a391884e7eaa6dd3eea150c6714962d1f77247e950b5e4b2bef8db
+  data.tar.gz: 24788e31dd5f8deb079a4c3bd2dd411ab6f93e1928eb4de6ed6bf0b398d241b22c8ab8e7009be3f758c286a3131ab3d123dc16cc46ce6c0449f01eb88a4c181c

data/README.md

@@ -0,0 +1,66 @@
+# open-banking-io (Ruby)
+
+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
+gem install open-banking-io
+```
+
+```ruby
+require "open_banking_io"
+
+# Load the credentials .json you exported from the app (API key + private key).
+client = OpenBankingIO::Client.from_credentials("credentials.json")
+
+client.get_accounts.each do |account|
+  booked = account.balances.find { |b| b.type == "ITBD" }
+  label = account.display_name || account.owner_name
+  puts "#{label} #{account.iban}: #{booked&.amount} #{account.currency}"
+
+  page = client.get_transactions(account.id, limit: 50)
+  page.items.each do |t|
+    puts "  #{t.booking_date}  #{t.creditor_name || t.debtor_name}  #{t.amount} #{t.currency}"
+  end
+
+  # Trigger an online sync (decrypts the account uid locally and posts it):
+  client.sync(account.id)
+end
+```
+
+Or construct it explicitly:
+
+```ruby
+client = OpenBankingIO::Client.new(
+  api_base_url: api_base_url,
+  api_key: api_key,
+  private_key_pkcs8: private_key_pkcs8
+)
+```
+
+## API
+
+- `get_accounts` → `Array<Account>` — decrypts each account's envelope, display name and balances.
+- `get_transactions(account_id, from: nil, to: nil, limit: nil, offset: nil)` → `TransactionPage`
+- `get_connections` → `Array<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 `BigDecimal`. Models are immutable keyword-initialised `Struct`s.
+
+## Encryption
+
+Envelopes use **ECDH P-256 → HKDF-SHA256 → AES-256-GCM**, implemented entirely with Ruby's OpenSSL
+standard library. Decryption requires the private key from your credentials bundle and happens fully
+in-process. See the [repo README](https://github.com/open-banking-io/clients) for the full scheme and
+the other language clients (.NET, Node, Python, Rust, Go, Java).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+MIT licensed.

data/lib/open_banking_io/client.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "net/http"
+require "bigdecimal"
+
+require_relative "envelope"
+require_relative "models"
+
+module OpenBankingIO
+  # Raised when the API returns a non-success HTTP status.
+  class HTTPError < StandardError
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body = body
+      super("open-banking.io request failed with HTTP #{status}")
+    end
+  end
+
+  # 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.
+  class Client
+    DEFAULT_OPEN_TIMEOUT = 15
+    DEFAULT_READ_TIMEOUT = 60
+
+    # Builds a client from a credentials-bundle JSON string or a path to a bundle file.
+    def self.from_credentials(path_or_json)
+      raw = if File.file?(path_or_json.to_s)
+              File.read(path_or_json)
+            else
+              path_or_json
+            end
+
+      bundle = JSON.parse(raw)
+      api_base_url = bundle["apiBaseUrl"].to_s
+      api_key = bundle["apiKey"]
+      raise ArgumentError, "The credentials bundle has no apiKey" if api_key.nil? || api_key.empty?
+
+      enc_key = bundle["encryptionKey"] || {}
+      private_key = enc_key["privateKey"] || enc_key["privateKeyPkcs8B64"]
+      if private_key.nil? || private_key.to_s.empty?
+        raise ArgumentError, "The credentials bundle has no encryption private key"
+      end
+
+      new(api_base_url: api_base_url, api_key: api_key, private_key_pkcs8: private_key)
+    end
+
+    def initialize(api_base_url:, api_key:, private_key_pkcs8:)
+      raise ArgumentError, "api_base_url is required" if blank?(api_base_url)
+      raise ArgumentError, "api_key is required" if blank?(api_key)
+      raise ArgumentError, "private_key_pkcs8 is required" if blank?(private_key_pkcs8)
+
+      @base_uri = URI.parse(api_base_url.to_s.sub(%r{/+\z}, "") + "/")
+      @api_key = api_key
+      @private_key = Envelope.load_private_key(private_key_pkcs8)
+    end
+
+    # Lists the user's accounts with all sensitive fields decrypted.
+    def get_accounts
+      account_wires.map { |w| map_account(w) }
+    end
+
+    # Returns a page of an account's statement, newest first, with decrypted fields.
+    def get_transactions(account_id, from: nil, to: nil, limit: nil, offset: nil)
+      params = {}
+      params["from"] = from unless from.nil?
+      params["to"] = to unless to.nil?
+      params["limit"] = limit unless limit.nil?
+      params["offset"] = offset unless offset.nil?
+
+      page = get_json("api/accounts/#{account_id}/transactions", params)
+      items = (page["items"] || []).map { |t| map_transaction(t) }
+      TransactionPage.new(items: items, total: page["total"] || 0)
+    end
+
+    # Lists the user's bank connections.
+    def get_connections
+      get_json("api/connections").map do |c|
+        Connection.new(
+          session_id: c["sessionId"] || "",
+          aspsp_name: c["aspspName"] || "",
+          aspsp_country: c["aspspCountry"] || "",
+          valid_until: c["validUntil"],
+          status: c["status"] || "",
+          account_count: c["accountCount"] || 0,
+          last_synced_at: c["lastSyncedAt"],
+          psu_type: c["psuType"]
+        )
+      end
+    end
+
+    # 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.
+    def sync(account_id)
+      account = account_wires.find { |a| a["id"] == account_id }
+      raise ArgumentError, "Account #{account_id} not found" if account.nil?
+
+      uid = decrypt_uid(account)
+      if uid.nil?
+        raise ArgumentError, "Account has no active session (reconnect required) -- cannot sync"
+      end
+
+      result = post_json("api/accounts/#{account_id}/sync", { "uid" => uid })
+      SyncResult.new(
+        new_transactions: result["newTransactions"] || 0,
+        total_fetched: result["totalFetched"] || 0
+      )
+    end
+
+    # Triggers an online sync of every account that has an active session.
+    def sync_all
+      items = []
+      account_wires.each do |a|
+        uid = decrypt_uid(a)
+        items << { "accountId" => a["id"], "uid" => uid } unless uid.nil?
+      end
+
+      result = post_json("api/sync", { "items" => items })
+      SyncAllResult.new(
+        accounts: result["accounts"] || 0,
+        new_transactions: result["newTransactions"] || 0
+      )
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def account_wires
+      get_json("api/accounts")
+    end
+
+    def decrypt_uid(account)
+      payload = Envelope.decrypt_to_json(@private_key, account["uidEnc"])
+      payload && payload["uid"]
+    end
+
+    def map_account(a)
+      acc = Envelope.decrypt_to_json(@private_key, a["enc"]) || {}
+      name = Envelope.decrypt_to_json(@private_key, a["displayNameEnc"]) || {}
+
+      balances = (a["balances"] || []).map do |b|
+        dec = Envelope.decrypt_to_json(@private_key, b["enc"]) || {}
+        Balance.new(
+          type: b["type"] || "",
+          currency: b["currency"] || "",
+          reference_date: b["referenceDate"],
+          name: dec["name"],
+          amount: parse_decimal(dec["amount"])
+        )
+      end
+
+      Account.new(
+        id: a["id"] || "",
+        aspsp_name: a["aspspName"] || "",
+        aspsp_country: a["aspspCountry"] || "",
+        currency: a["currency"] || "",
+        account_type: a["accountType"],
+        bic: a["bic"],
+        needs_reconnect: a["needsReconnect"] || false,
+        iban: acc["iban"],
+        bban: acc["bban"],
+        owner_name: acc["ownerName"],
+        account_name: acc["accountName"],
+        product: acc["product"],
+        display_name: name["displayName"],
+        balances: balances
+      )
+    end
+
+    def map_transaction(t)
+      d = Envelope.decrypt_to_json(@private_key, t["enc"]) || {}
+      Transaction.new(
+        id: t["id"] || "",
+        currency: t["currency"] || "",
+        credit_debit_indicator: t["creditDebitIndicator"] || "",
+        status: t["status"],
+        booking_date: t["bookingDate"],
+        value_date: t["valueDate"],
+        transaction_date: t["transactionDate"],
+        bank_transaction_code: t["bankTransactionCode"],
+        amount: parse_decimal(d["amount"]),
+        creditor_name: d["creditorName"],
+        creditor_iban: d["creditorIban"],
+        creditor_bban: d["creditorBban"],
+        creditor_agent_bic: d["creditorAgentBic"],
+        debtor_name: d["debtorName"],
+        debtor_iban: d["debtorIban"],
+        debtor_bban: d["debtorBban"],
+        debtor_agent_bic: d["debtorAgentBic"],
+        remittance_information: d["remittanceInformation"],
+        note: d["note"],
+        reference_number: d["referenceNumber"],
+        exchange_rate: d["exchangeRate"],
+        merchant_category_code: d["merchantCategoryCode"],
+        balance_after_transaction: parse_decimal_nullable(d["balanceAfter"]),
+        balance_after_currency: d["balanceAfterCurrency"]
+      )
+    end
+
+    def parse_decimal(value)
+      return BigDecimal(0) if value.nil? || value == ""
+
+      BigDecimal(value.to_s)
+    end
+
+    def parse_decimal_nullable(value)
+      return nil if value.nil? || value == ""
+
+      BigDecimal(value.to_s)
+    end
+
+    # -- HTTP ------------------------------------------------------------------
+
+    def get_json(path, params = {})
+      uri = resolve(path)
+      unless params.empty?
+        uri.query = URI.encode_www_form(params)
+      end
+
+      request = Net::HTTP::Get.new(uri)
+      send_request(uri, request)
+    end
+
+    def post_json(path, body)
+      uri = resolve(path)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(body)
+      send_request(uri, request)
+    end
+
+    def resolve(path)
+      (@base_uri + path.sub(%r{\A/+}, "")).dup
+    end
+
+    def send_request(uri, request)
+      request["X-Api-Key"] = @api_key
+      request["Accept"] = "application/json"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = DEFAULT_OPEN_TIMEOUT
+      http.read_timeout = DEFAULT_READ_TIMEOUT
+
+      response = http.request(request)
+      code = response.code.to_i
+      raise HTTPError.new(code, response.body) unless code.between?(200, 299)
+
+      body = response.body
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    end
+  end
+end

data/lib/open_banking_io/envelope.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module OpenBankingIO
+  # 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.
+  module Envelope
+    VERSION_BYTE = 0x01
+    POINT_LEN = 65
+    NONCE_LEN = 12
+    TAG_LEN = 16
+    HKDF_SALT = ("\x00".b * 32).freeze
+    HKDF_INFO = "bank.core.ci/zk/v1".b.freeze
+    GROUP = OpenSSL::PKey::EC::Group.new("prime256v1")
+
+    module_function
+
+    # Loads a base64 PKCS#8 EC (P-256) private key.
+    def load_private_key(private_key_pkcs8_b64)
+      key = OpenSSL::PKey.read(Base64.decode64(private_key_pkcs8_b64))
+      unless key.is_a?(OpenSSL::PKey::EC)
+        raise ArgumentError, "Private key is not an EC key"
+      end
+
+      key
+    end
+
+    # Decrypts the raw bytes of a zero-knowledge envelope, returning the plaintext bytes.
+    def decrypt(private_key, envelope_bytes)
+      min_len = 1 + POINT_LEN + NONCE_LEN + TAG_LEN
+      if envelope_bytes.bytesize < min_len || envelope_bytes.getbyte(0) != VERSION_BYTE
+        raise ArgumentError, "Invalid or unsupported envelope"
+      end
+
+      eph_pub_bytes = envelope_bytes.byteslice(1, POINT_LEN)
+      nonce = envelope_bytes.byteslice(1 + POINT_LEN, NONCE_LEN)
+      tag = envelope_bytes.byteslice(1 + POINT_LEN + NONCE_LEN, TAG_LEN)
+      ciphertext = envelope_bytes.byteslice((1 + POINT_LEN + NONCE_LEN + TAG_LEN)..) || "".b
+
+      pub = OpenSSL::PKey::EC::Point.new(GROUP, OpenSSL::BN.new(eph_pub_bytes, 2))
+      shared = private_key.dh_compute_key(pub)
+
+      key = OpenSSL::KDF.hkdf(
+        shared,
+        salt: HKDF_SALT,
+        info: HKDF_INFO,
+        length: 32,
+        hash: "SHA256"
+      )
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.decrypt
+      cipher.key = key
+      cipher.iv = nonce
+      cipher.auth_tag = tag
+      cipher.auth_data = ""
+      cipher.update(ciphertext) + cipher.final
+    end
+
+    # Decrypts a base64 envelope and parses its JSON payload. +nil+ in -> +nil+ out.
+    def decrypt_to_json(private_key, envelope_b64)
+      return nil if envelope_b64.nil?
+
+      plaintext = decrypt(private_key, Base64.decode64(envelope_b64))
+      JSON.parse(plaintext)
+    end
+  end
+end

data/lib/open_banking_io/models.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module OpenBankingIO
+  # Public, decrypted models for the open-banking.io client.
+  #
+  # These are immutable keyword-initialised value objects (Struct). Amounts are exposed
+  # as BigDecimal; dates as String (ISO-8601) as returned by the service.
+
+  # A balance snapshot. +type+ is the ISO 20022 code (ITBD booked, ITAV available, ...).
+  Balance = Struct.new(
+    :type,
+    :name,
+    :amount,          # BigDecimal
+    :currency,
+    :reference_date,
+    keyword_init: true
+  )
+
+  # A bank account with its sensitive fields decrypted.
+  Account = Struct.new(
+    :id,
+    :aspsp_name,
+    :aspsp_country,
+    :currency,
+    :account_type,
+    :bic,
+    :needs_reconnect,
+    :iban,
+    :bban,
+    :owner_name,
+    :account_name,
+    :product,
+    :display_name,
+    :balances,        # Array<Balance>
+    keyword_init: true
+  )
+
+  # A statement transaction with its sensitive fields decrypted.
+  Transaction = Struct.new(
+    :id,
+    :currency,
+    :credit_debit_indicator,
+    :status,
+    :booking_date,
+    :value_date,
+    :transaction_date,
+    :bank_transaction_code,
+    :amount,          # BigDecimal
+    :creditor_name,
+    :creditor_iban,
+    :creditor_bban,
+    :creditor_agent_bic,
+    :debtor_name,
+    :debtor_iban,
+    :debtor_bban,
+    :debtor_agent_bic,
+    :remittance_information,
+    :note,
+    :reference_number,
+    :exchange_rate,
+    :merchant_category_code,
+    :balance_after_transaction,   # BigDecimal or nil
+    :balance_after_currency,
+    keyword_init: true
+  )
+
+  # A page of transactions, newest first.
+  TransactionPage = Struct.new(:items, :total, keyword_init: true)
+
+  # A bank connection (consent).
+  Connection = Struct.new(
+    :session_id,
+    :aspsp_name,
+    :aspsp_country,
+    :valid_until,
+    :status,
+    :account_count,
+    :last_synced_at,
+    :psu_type,
+    keyword_init: true
+  )
+
+  SyncResult = Struct.new(:new_transactions, :total_fetched, keyword_init: true)
+
+  SyncAllResult = Struct.new(:accounts, :new_transactions, keyword_init: true)
+end

data/lib/open_banking_io/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenBankingIO
+  VERSION = "0.1.0"
+end

data/lib/open_banking_io.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "open_banking_io/version"
+require_relative "open_banking_io/envelope"
+require_relative "open_banking_io/models"
+require_relative "open_banking_io/client"
+
+# Server-to-server client for open-banking.io with local zero-knowledge envelope decryption.
+module OpenBankingIO
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: open-banking-io
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- open-banking.io
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Authenticates with your API key and decrypts open-banking.io's zero-knowledge
+  data envelopes locally with your exported private key (ECDH P-256 -> HKDF-SHA256
+  -> AES-256-GCM). The service only ever returns ciphertext it cannot read.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/open_banking_io.rb
+- lib/open_banking_io/client.rb
+- lib/open_banking_io/envelope.rb
+- lib/open_banking_io/models.rb
+- lib/open_banking_io/version.rb
+homepage: https://open-banking.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://open-banking.io
+  source_code_uri: https://github.com/open-banking-io/clients
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Server-to-server client for open-banking.io with local zero-knowledge envelope
+  decryption.
+test_files: []