open-banking-io 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d7f5d02a8a4a808faa00f6c78558b2e11c90a7c5b852062682746c1ab2a3da1
-  data.tar.gz: c24bf4296b70c0b5ffc6af71faae40d4c559301f59654358c6c34e94130bbef3
+  metadata.gz: 52d72498c008ed13bec684867aef1f1b693c6f9ba0ed824e981ae554787c19a8
+  data.tar.gz: 47d0c4dbfc8511f80b0ac8b9d2270fbd68f969141b222c7dda61a2c8254e577c
 SHA512:
-  metadata.gz: d4870301dfb82caf2456f2b24a7ae8e6b469375da2bf6ff86821196eaf620f3e1b734deae2a391884e7eaa6dd3eea150c6714962d1f77247e950b5e4b2bef8db
-  data.tar.gz: 24788e31dd5f8deb079a4c3bd2dd411ab6f93e1928eb4de6ed6bf0b398d241b22c8ab8e7009be3f758c286a3131ab3d123dc16cc46ce6c0449f01eb88a4c181c
+  metadata.gz: 13cce72e500507d12756086fc0d3dd6595556fb4200f6d9da9c69bc112558aefafa684043814988b8e58a0ee1907a2480d9d29b0721c9f6de73677afb3b25818
+  data.tar.gz: f607fde4595bf4b1499d32db231d7939d60b064dfe2308cdcecd80557735bf7c0ad062052003d11787c5f2d661269b24518130dd41c5c5a1e52dd8963c97b6fe

data/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://open-banking.io">
+    <img src="https://raw.githubusercontent.com/open-banking-io/clients/main/.github/logo.png" alt="open-banking.io" height="56">
+  </a>
+</p>
+
 # open-banking-io (Ruby)
 
 Server-to-server client for [open-banking.io](https://open-banking.io). It authenticates with your
@@ -49,12 +55,15 @@ client = OpenBankingIO::Client.new(
 
 Amounts are exposed as `BigDecimal`. Models are immutable keyword-initialised `Struct`s.
 
+Every request sets connect/read timeouts (15s/60s) and a `User-Agent: open-banking-io/ruby/<version>` header.
+
 ## 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).
+in-process. Full wire format and the other language clients:
+[repo README](https://github.com/open-banking-io/clients) ·
+[`THREAT_MODEL.md`](https://github.com/open-banking-io/clients/blob/main/THREAT_MODEL.md).
 
 ## Development
 

data/lib/open_banking_io/client.rb

@@ -7,6 +7,7 @@ require "bigdecimal"
 
 require_relative "envelope"
 require_relative "models"
+require_relative "version"
 
 module OpenBankingIO
   # Raised when the API returns a non-success HTTP status.
@@ -28,14 +29,20 @@ module OpenBankingIO
   class Client
     DEFAULT_OPEN_TIMEOUT = 15
     DEFAULT_READ_TIMEOUT = 60
+    USER_AGENT = "open-banking-io/ruby/#{VERSION}".freeze
 
     # Builds a client from a credentials-bundle JSON string or a path to a bundle file.
-    def self.from_credentials(path_or_json)
+    #
+    # Optional +open_timeout+/+read_timeout+ (seconds) and a caller-supplied +http_client+
+    # (an object responding to +#request+, e.g. a preconfigured Net::HTTP) are threaded
+    # straight through to +#initialize+; the defaults preserve the previous behaviour.
+    def self.from_credentials(path_or_json, open_timeout: DEFAULT_OPEN_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT, http_client: nil)
       raw = if File.file?(path_or_json.to_s)
-              File.read(path_or_json)
-            else
-              path_or_json
-            end
+        File.read(path_or_json)
+      else
+        path_or_json
+      end
 
       bundle = JSON.parse(raw)
       api_base_url = bundle["apiBaseUrl"].to_s
@@ -48,17 +55,37 @@ module OpenBankingIO
         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)
+      new(
+        api_base_url: api_base_url,
+        api_key: api_key,
+        private_key_pkcs8: private_key,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        http_client: http_client
+      )
     end
 
-    def initialize(api_base_url:, api_key:, private_key_pkcs8:)
+    # +open_timeout+/+read_timeout+ are seconds applied to the internally built Net::HTTP.
+    # +http_client+, when given, is any object responding to +#request+ (e.g. a preconfigured
+    # Net::HTTP for a proxy, custom CA/mTLS or connection pooling); it is used as-is instead
+    # of building one internally. All three are optional and default to the previous behaviour.
+    def initialize(api_base_url:, api_key:, private_key_pkcs8:,
+      open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+      http_client: nil)
       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}, "") + "/")
+      # Strip any trailing slashes without a backtracking regex (avoids ReDoS on
+      # pathological input) then re-append a single one, so the base always ends in "/".
+      base = api_base_url.to_s
+      base = base.chomp("/") while base.end_with?("/")
+      @base_uri = URI.parse(base + "/")
       @api_key = api_key
       @private_key = Envelope.load_private_key(private_key_pkcs8)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @http_client = http_client
     end
 
     # Lists the user's accounts with all sensitive fields decrypted.
@@ -108,7 +135,7 @@ module OpenBankingIO
         raise ArgumentError, "Account has no active session (reconnect required) -- cannot sync"
       end
 
-      result = post_json("api/accounts/#{account_id}/sync", { "uid" => uid })
+      result = post_json("api/accounts/#{account_id}/sync", {"uid" => uid})
       SyncResult.new(
         new_transactions: result["newTransactions"] || 0,
         total_fetched: result["totalFetched"] || 0
@@ -120,10 +147,10 @@ module OpenBankingIO
       items = []
       account_wires.each do |a|
         uid = decrypt_uid(a)
-        items << { "accountId" => a["id"], "uid" => uid } unless uid.nil?
+        items << {"accountId" => a["id"], "uid" => uid} unless uid.nil?
       end
 
-      result = post_json("api/sync", { "items" => items })
+      result = post_json("api/sync", {"items" => items})
       SyncAllResult.new(
         accounts: result["accounts"] || 0,
         new_transactions: result["newTransactions"] || 0
@@ -228,6 +255,10 @@ module OpenBankingIO
         uri.query = URI.encode_www_form(params)
       end
 
+      # `path` is an internal, library-controlled API route resolved against the configured
+      # base URI (see #resolve), not user-supplied file/URL input. This is an HTTP API client;
+      # issuing the request is its purpose.
+      # nosemgrep: ruby.rails.security.audit.avoid-tainted-http-request.avoid-tainted-http-request
       request = Net::HTTP::Get.new(uri)
       send_request(uri, request)
     end
@@ -247,11 +278,9 @@ module OpenBankingIO
     def send_request(uri, request)
       request["X-Api-Key"] = @api_key
       request["Accept"] = "application/json"
+      request["User-Agent"] = USER_AGENT
 
-      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
+      http = @http_client || build_http(uri)
 
       response = http.request(request)
       code = response.code.to_i
@@ -262,5 +291,13 @@ module OpenBankingIO
 
       JSON.parse(body)
     end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http
+    end
   end
 end

data/lib/open_banking_io/envelope.rb

@@ -15,7 +15,7 @@ module OpenBankingIO
     POINT_LEN = 65
     NONCE_LEN = 12
     TAG_LEN = 16
-    HKDF_SALT = ("\x00".b * 32).freeze
+    HKDF_SALT = ("\x00".b * 32)
     HKDF_INFO = "bank.core.ci/zk/v1".b.freeze
     GROUP = OpenSSL::PKey::EC::Group.new("prime256v1")
 
@@ -43,7 +43,7 @@ module OpenBankingIO
       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))
+      pub = decode_public_point(eph_pub_bytes)
       shared = private_key.dh_compute_key(pub)
 
       key = OpenSSL::KDF.hkdf(
@@ -63,6 +63,17 @@ module OpenBankingIO
       cipher.update(ciphertext) + cipher.final
     end
 
+    # Parses the 65-byte raw ephemeral public key into a P-256 point.
+    #
+    # A malformed or off-curve point makes +EC::Point.new+ raise an OpenSSL-internal
+    # error; we wrap it in a clean +ArgumentError+ so callers see a consistent envelope
+    # error rather than a leaking implementation detail.
+    def decode_public_point(eph_pub_bytes)
+      OpenSSL::PKey::EC::Point.new(GROUP, OpenSSL::BN.new(eph_pub_bytes, 2))
+    rescue OpenSSL::PKey::EC::Point::Error, OpenSSL::BNError => e
+      raise ArgumentError, "Invalid ephemeral public key in envelope: #{e.message}"
+    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?

data/lib/open_banking_io/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: open-banking-io
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - open-banking.io
@@ -65,6 +65,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.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.