epics 3.0.0.rc1 → 3.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfb2519dc2e22c76ab739665eae1376bc45f525b8025c158e25606892839bed9
-  data.tar.gz: 29a8b4673f7b494c1a8b07e27865bfee5abe5056e176e29612bc4e08058fb340
+  metadata.gz: 2d81d3bda7eef2d4468cba9327d5e72ad7222eec73e76bfe82c609765a212075
+  data.tar.gz: b49bcb37a43532a0f9d5074478e22cfa126c4b3e7bf594894f8be27e60aeca37
 SHA512:
-  metadata.gz: 8fbe472fa138faa685cc8c35891d697d114b3cee9086c47ea3bea7a1c36d817176239647e04fc42dca327fcb07bcb0b0ce410d33e3060ccb446e4d4a092f4b50
-  data.tar.gz: bc95a07d0c74576667827a341c3aed4ad1cf2777b000426e351baab9d542c8b0cb0679076ba0660350e96d50c26b7d1ab603217a0ed9d64f4a300f6b96e419e4
+  metadata.gz: '09ce2c4c8afa08bf91a00112d8a1078b388a76b40276006706f0c821a1aab7924655a9de56032956d1e74975dda1be8438e42d11211fae95b2d4aa4634b7f7f5'
+  data.tar.gz: fe3a33f8d19057cbe437189ae98b18e32eafbedde991bb12b1cf0c10a63384a5910f254272f4d9d43f972951d50fa18601bd2b521253603b2f3893e6a81c9e13

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ### Unreleased
 
+- [FIX] A download spanning several segments returned only its first segment, so zipped
+  downloads such as `C52` and `C53` raised `Zip::Error` and plain ones such as `STA` came
+  back cut off without an error. The remaining segments are now requested in the transfer
+  phase and the order data is decrypted once all segments are joined. A segmented response
+  without a readable `NumSegments` raises `Epics::InvalidResponseError`
+- [FIX] Truncated order data was inflated as far as it went and returned. It now raises
+  `Epics::InvalidOrderDataError`, with the `Zlib` or `OpenSSL` error as its `cause`, and a
+  negative receipt is sent instead of a positive one, so the bank does not consider a
+  broken download as delivered
+
 ### 3.0.0.rc1
 
 Major release adding EBICS 3.0 (H005) and EBICS 2.4 (H003) support, alongside a

data/README.md

@@ -354,6 +354,10 @@ puts e.STA('2014-09-01', '2014-09-11')
 ^62RATAJA 13B/1083-032 PSZCZOL^63KI
 ```
 
+If the order data cannot be decrypted or inflated, e.g. because it arrived truncated,
+the download is rejected to the bank with a negative receipt and
+`Epics::InvalidOrderDataError` is raised, with the underlying error as its `cause`.
+
 ### Uploads
 
 - CD1 (Uploads a SEPA Direct Debit document of type COR1)

data/lib/epics/client.rb

@@ -604,10 +604,32 @@ class Epics::Client
     document = order_type.new(self, *args, **options)
     res = post(url, document.to_xml).body
     document.transaction_id = res.transaction_id
+    segments = [res, *remaining_segments(document, res)]
+    order_data = begin
+      res.decrypt_order_data(segments.map(&:order_data_encrypted).join)
+    rescue StandardError => e
+      reject_download(document) if res.segmented?
+      raise Epics::InvalidOrderDataError.new(order_type.name.split('::').last, e)
+    end
+    post(url, document.to_receipt_xml) if res.segmented?
+
+    order_data
+  end
 
-    post(url, document.to_receipt_xml).body if res.segmented? && res.last_segment?
+  def remaining_segments(document, res)
+    return [] if !res.segmented? || res.last_segment?
+
+    (2..res.num_segments).map do |segment_number|
+      post(url, document.to_transfer_download_xml(segment_number, segment_number == res.num_segments)).body
+    end
+  end
 
-    res.order_data
+  # The bank answers a negative receipt with an error, and the reason the order data
+  # could not be read is the one worth raising.
+  def reject_download(document)
+    post(url, document.to_receipt_xml(acknowledged: false))
+  rescue StandardError
+    nil
   end
 
   def download_and_unzip(order_type, *args, **options)

data/lib/epics/generic_request.rb

@@ -50,8 +50,13 @@ class Epics::GenericRequest
     raise NotImplementedError
   end
 
-  def to_receipt_xml
-    builder = request_factory.create_transfer_receipt(transaction_id, 0)
+  def to_transfer_download_xml(segment_number, is_last_segment)
+    builder = request_factory.create_transfer_download(transaction_id, segment_number, is_last_segment)
+    builder.to_xml
+  end
+
+  def to_receipt_xml(acknowledged: true)
+    builder = request_factory.create_transfer_receipt(transaction_id, acknowledged ? 0 : 1)
     builder.to_xml
   end
 

data/lib/epics/response.rb

@@ -46,6 +46,12 @@ class Epics::Response
     !!doc.at_xpath('//xmlns:header/xmlns:mutable/xmlns:SegmentNumber', xmlns: client.urn_schema)
   end
 
+  def num_segments
+    Integer(doc.xpath('//xmlns:header/xmlns:static/xmlns:NumSegments', xmlns: client.urn_schema).text, 10)
+  rescue ArgumentError => e
+    raise Epics::InvalidResponseError.new('NumSegments', e)
+  end
+
   def return_code
     doc.xpath('//xmlns:ReturnCode', xmlns: client.urn_schema).last.content
   rescue NoMethodError
@@ -93,11 +99,20 @@ class Epics::Response
   end
 
   def order_data
-    order_data_encrypted = Base64.decode64(doc.xpath('//xmlns:OrderData', xmlns: client.urn_schema).first.content)
+    decrypt_order_data(order_data_encrypted)
+  end
+
+  def order_data_encrypted
+    Base64.decode64(doc.xpath('//xmlns:OrderData', xmlns: client.urn_schema).first.content)
+  end
 
-    data = (cipher.update(order_data_encrypted) + cipher.final)
+  # Segments cannot be decrypted on their own, so pass all of them joined. Only the first
+  # response carries the transaction key.
+  def decrypt_order_data(order_data_encrypted)
+    decipher = cipher
+    data = decipher.update(order_data_encrypted) + decipher.final
 
-    Zlib::Inflate.new.inflate(data)
+    Zlib::Inflate.inflate(data)
   end
 
   def cipher

data/lib/epics/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Epics
-  VERSION = '3.0.0.rc1'
+
+  VERSION = '3.0.0.rc2'
+
 end

data/lib/epics.rb

@@ -115,6 +115,32 @@ module Epics
     end
   end
 
+  # Raised when the bank's response lacks a value the protocol requires, or carries one
+  # that cannot be read.
+  class InvalidResponseError < StandardError
+    attr_reader :field
+
+    def initialize(field, original = nil)
+      @field = field
+      message = "Could not read #{field} from the bank's response"
+      message += " (#{original.message})" if original
+      super(message)
+    end
+  end
+
+  # Raised when the order data of a download cannot be decrypted or inflated, e.g.
+  # because it arrived truncated. The bank has been sent a negative receipt by then.
+  class InvalidOrderDataError < StandardError
+    attr_reader :order_type
+
+    def initialize(order_type, original = nil)
+      @order_type = order_type
+      message = "Could not read the order data of the #{order_type} download"
+      message += " (#{original.message})" if original
+      super(message)
+    end
+  end
+
   class VersionSupportError < StandardError
     attr_reader :version
 

data/spec/response_spec.rb

@@ -89,6 +89,37 @@ RSpec.describe Epics::Response do
     end
   end
 
+  describe '#num_segments' do
+    let(:ebics_response) { File.read('spec/fixtures/xml/sta_response_continued.xml') }
+
+    it 'pulls the number of segments from the response' do
+      expect(subject.num_segments).to eq(2)
+    end
+
+    describe 'when the number has leading zeros' do
+      let(:ebics_response) do
+        File.read('spec/fixtures/xml/sta_response_continued.xml').sub('<NumSegments>2<', '<NumSegments>09<')
+      end
+
+      it 'reads it as a decimal' do
+        expect(subject.num_segments).to eq(9)
+      end
+    end
+
+    describe 'when the number is missing' do
+      let(:ebics_response) do
+        File.read('spec/fixtures/xml/sta_response_continued.xml').sub(%r{<NumSegments>2</NumSegments>}, '')
+      end
+
+      it 'raises an error naming the field' do
+        expect { subject.num_segments }.to raise_error(Epics::InvalidResponseError, /NumSegments/) do |error|
+          expect(error.field).to eq('NumSegments')
+          expect(error.cause).to be_a(ArgumentError)
+        end
+      end
+    end
+  end
+
   describe '#segmented?' do
     describe 'when the response is segemnted' do
       let(:ebics_response) { File.read('spec/fixtures/xml/sta_response.xml') }

data/spec/segmented_download_spec.rb

@@ -0,0 +1,248 @@
+RSpec.describe 'segmented downloads' do
+  versions = [Epics::Keyring::VERSION_24, Epics::Keyring::VERSION_25, Epics::Keyring::VERSION_30]
+
+  let(:url) { 'https://194.180.18.30/ebicsweb/ebicsweb' }
+  let(:version) { Epics::Keyring::VERSION_25 }
+  let(:client) do
+    Epics::Client.new(File.open(File.join(File.dirname(__FILE__), 'fixtures', 'SIZBN001.key')),
+                      'secret', url, 'SIZBN001', 'EBIX', 'EBICS', version:)
+  end
+  let(:ns) { { 'e' => client.urn_schema } }
+  let(:transaction_id) { 'ECD6F062AAEDFA77250526A68CBEC549' }
+
+  describe 'Epics::GenericRequest#to_transfer_download_xml' do
+    let(:order) { Epics::C53.new(client, from: Date.new(2026, 9, 24), to: Date.new(2026, 9, 24)) }
+    let(:xml) { Nokogiri::XML(order.to_transfer_download_xml(2, false)) }
+
+    before { order.transaction_id = transaction_id }
+
+    versions.each do |version|
+      context version do
+        let(:version) { version }
+
+        it 'is a valid EBICS document' do
+          expect(xml.to_xml).to be_a_valid_ebics_doc(version)
+        end
+
+        it 'requests the segment of the transaction without sending order data' do
+          expect(xml.at_xpath('//e:header/e:static/e:TransactionID', ns).text).to eq(transaction_id)
+          expect(xml.at_xpath('//e:header/e:mutable/e:TransactionPhase', ns).text).to eq('Transfer')
+          expect(xml.at_xpath('//e:header/e:mutable/e:SegmentNumber', ns).text).to eq('2')
+          expect(xml.at_xpath('//e:header/e:mutable/e:SegmentNumber', ns)['lastSegment']).to eq('false')
+          expect(xml.at_xpath('//e:body', ns).elements).to be_empty
+        end
+      end
+    end
+
+    it 'marks the last segment' do
+      segment_number = Nokogiri::XML(order.to_transfer_download_xml(3, true))
+                               .at_xpath('//e:header/e:mutable/e:SegmentNumber', ns)
+
+      expect(segment_number.text).to eq('3')
+      expect(segment_number['lastSegment']).to eq('true')
+    end
+  end
+
+  describe 'Epics::GenericRequest#to_receipt_xml' do
+    let(:order) { Epics::C53.new(client, from: Date.new(2026, 9, 24), to: Date.new(2026, 9, 24)) }
+
+    before { order.transaction_id = transaction_id }
+
+    def receipt_code(xml)
+      Nokogiri::XML(xml).at_xpath('//e:body/e:TransferReceipt/e:ReceiptCode', ns).text
+    end
+
+    it 'acknowledges the download by default' do
+      expect(receipt_code(order.to_receipt_xml)).to eq('0')
+    end
+
+    versions.each do |version|
+      context version do
+        let(:version) { version }
+
+        it 'rejects the download when not acknowledged' do
+          xml = order.to_receipt_xml(acknowledged: false)
+
+          expect(xml).to be_a_valid_ebics_doc(version)
+          expect(receipt_code(xml)).to eq('1')
+        end
+      end
+    end
+  end
+
+  describe 'Epics::Client#download' do
+    def response(phase, order_data: nil, segment_number: nil, num_segments: nil, return_code: '000000')
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <ebicsResponse xmlns="#{client.urn_schema}" Version="#{version}" Revision="1">
+          <header authenticate="true">
+            <static>
+              <TransactionID>#{transaction_id}</TransactionID>
+              #{"<NumSegments>#{num_segments}</NumSegments>" if num_segments}
+            </static>
+            <mutable>
+              <TransactionPhase>#{phase}</TransactionPhase>
+              #{segment_number_xml(segment_number) if segment_number}
+              <ReturnCode>#{return_code}</ReturnCode>
+            </mutable>
+          </header>
+          <body>
+            #{data_transfer_xml(phase, order_data) if order_data}
+            <ReturnCode authenticate="true">000000</ReturnCode>
+          </body>
+        </ebicsResponse>
+      XML
+    end
+
+    def segment_number_xml(segment_number)
+      %(<SegmentNumber lastSegment="#{segment_number == segments.size}">#{segment_number}</SegmentNumber>)
+    end
+
+    def data_transfer_xml(phase, order_data)
+      <<~XML
+        <DataTransfer>
+          #{data_encryption_info_xml if phase == 'Initialisation'}
+          <OrderData>#{Base64.strict_encode64(order_data)}</OrderData>
+        </DataTransfer>
+      XML
+    end
+
+    def data_encryption_info_xml
+      <<~XML
+        <DataEncryptionInfo authenticate="true">
+          <TransactionKey>#{Base64.strict_encode64(client.encryption_key.key.public_encrypt(transaction_key))}</TransactionKey>
+        </DataEncryptionInfo>
+      XML
+    end
+
+    def summarize(request)
+      segment_number = request.at_xpath('//e:header/e:mutable/e:SegmentNumber', ns)
+      receipt_code = request.at_xpath('//e:body/e:TransferReceipt/e:ReceiptCode', ns)
+
+      [request.at_xpath('//e:header/e:mutable/e:TransactionPhase', ns).text,
+       segment_number&.text,
+       segment_number&.[]('lastSegment'),
+       receipt_code&.text].compact
+    end
+
+    let(:zipped_order_data) { File.binread(File.join(File.dirname(__FILE__), 'fixtures', 'test.zip')) }
+    let(:transaction_key) { SecureRandom.random_bytes(16) }
+    let(:order_data_encrypted) do
+      cipher = OpenSSL::Cipher.new('aes-128-cbc').encrypt
+      cipher.key = transaction_key
+
+      cipher.update(Zlib::Deflate.deflate(zipped_order_data)) + cipher.final
+    end
+    let(:missing_bytes) { 0 }
+    let(:segment_count) { 3 }
+    let(:segments) do
+      received = order_data_encrypted.byteslice(0, order_data_encrypted.bytesize - missing_bytes)
+
+      received.bytes.each_slice((received.bytesize / segment_count.to_f).ceil).map { |bytes| bytes.pack('C*') }
+    end
+    let(:initialisation_response) do
+      response('Initialisation', order_data: segments.first, segment_number: 1, num_segments: segments.size)
+    end
+    let(:aborted_segment) { nil }
+    let(:requests) { [] }
+
+    subject { client.C53(Date.new(2026, 9, 24), Date.new(2026, 9, 24)) }
+
+    before do
+      stub_request(:post, url).to_return do |http_request|
+        requests << summarize(Nokogiri::XML(http_request.body))
+        phase, *details = requests.last
+        body = case phase
+               when 'Initialisation' then initialisation_response
+               when 'Transfer'
+                 segment_number = Integer(details.first)
+                 if segment_number == aborted_segment
+                   response('Transfer', return_code: '091102')
+                 else
+                   response('Transfer', order_data: segments[segment_number - 1], segment_number:)
+                 end
+               when 'Receipt' then response('Receipt', return_code: details == ['0'] ? '011000' : '011001')
+               end
+
+        { status: 200, body: }
+      end
+    end
+
+    context 'when the order data arrives short by whole cipher blocks' do
+      let(:missing_bytes) { 32 }
+
+      it 'raises after sending a negative receipt' do
+        expect { subject }.to raise_error(Epics::InvalidOrderDataError, /C53/) do |error|
+          expect(error.cause).to be_a(Zlib::BufError)
+        end
+        expect(requests).to eq([%w[Initialisation], %w[Transfer 2 false], %w[Transfer 3 true], %w[Receipt 1]])
+      end
+    end
+
+    context 'when the order data arrives short by part of a cipher block' do
+      let(:missing_bytes) { 5 }
+
+      it 'raises after sending a negative receipt' do
+        expect { subject }.to raise_error(Epics::InvalidOrderDataError, /C53/) do |error|
+          expect(error.cause).to be_a(OpenSSL::Cipher::CipherError)
+        end
+        expect(requests).to eq([%w[Initialisation], %w[Transfer 2 false], %w[Transfer 3 true], %w[Receipt 1]])
+      end
+    end
+
+    context 'when the bank aborts the transaction during the transfer' do
+      let(:aborted_segment) { 2 }
+
+      it "raises the bank's error without sending a receipt" do
+        expect { subject }.to raise_error(Epics::Error::TechnicalError) do |error|
+          expect(error.symbol).to eq('EBICS_TX_ABORT')
+        end
+        expect(requests).to eq([%w[Initialisation], %w[Transfer 2 false]])
+      end
+    end
+
+    context 'when the negative receipt cannot be sent' do
+      let(:missing_bytes) { 32 }
+
+      before do
+        stub_request(:post, url).with { |request| summarize(Nokogiri::XML(request.body)) == %w[Receipt 1] }
+                                .to_raise(Faraday::ConnectionFailed)
+      end
+
+      it 'raises the reason the order data could not be read' do
+        expect { subject }.to raise_error(Epics::InvalidOrderDataError, /C53/) do |error|
+          expect(error.cause).to be_a(Zlib::BufError)
+        end
+      end
+    end
+
+    context 'when the response is not segmented' do
+      let(:initialisation_response) { response('Initialisation', order_data: order_data_encrypted) }
+
+      it 'returns the order data without sending a receipt' do
+        expect(subject).to eq(["ebics is great\n"])
+        expect(requests).to eq([%w[Initialisation]])
+      end
+    end
+
+    context 'when the order data fits into a single segment' do
+      let(:segment_count) { 1 }
+
+      it 'returns the order data and sends the receipt' do
+        expect(subject).to eq(["ebics is great\n"])
+        expect(requests).to eq([%w[Initialisation], %w[Receipt 0]])
+      end
+    end
+
+    versions.each do |version|
+      context "when the order data spans several segments (#{version})" do
+        let(:version) { version }
+
+        it 'returns the order data of all segments and sends the receipt after the last one' do
+          expect(subject).to eq(["ebics is great\n"])
+          expect(requests).to eq([%w[Initialisation], %w[Transfer 2 false], %w[Transfer 3 true], %w[Receipt 0]])
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epics
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc1
+  version: 3.0.0.rc2
 platform: ruby
 authors:
 - Lars Brillert
@@ -455,6 +455,7 @@ files:
 - spec/response_business_error_spec.rb
 - spec/response_spec.rb
 - spec/response_validation_spec.rb
+- spec/segmented_download_spec.rb
 - spec/signature_algorithm/rsa_pss_spec.rb
 - spec/spec_helper.rb
 - spec/support/ebics_matcher.rb
@@ -520,7 +521,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: a ruby implementation of the EBICS protocol
 test_files:
@@ -633,6 +634,7 @@ test_files:
 - spec/response_business_error_spec.rb
 - spec/response_spec.rb
 - spec/response_validation_spec.rb
+- spec/segmented_download_spec.rb
 - spec/signature_algorithm/rsa_pss_spec.rb
 - spec/spec_helper.rb
 - spec/support/ebics_matcher.rb